前言

本书定义 asciidoc-abundant-tree 中 book-entry source-mapped logical document 的实现计划。书稿入口回源逻辑文档规约 定义目标对象；本书定义从当前 single-file parser 基线到该目标对象的工程批次、文件边界、测试要求、审核门槛、状态台账和关闭条件。

当前源码已经具备 single-file parser、source-aware AbundantDocument、metadata surface recovery、xref occurrence recovery、anchor occurrence recovery、RDF 1.2 下游投影、CLI 和 serializer 基础。当前源码不具备 book-entry mode、logical source builder、line origin、source file table、origin-aware source coordinate recovery 和 book-entry CLI。上述事实是实现基线，不是目标对象。

本书的核心断言是：book-entry mode 必须同时成立 logical document 和 origin source coordinate。每个批次必须产生可验证的源码变化、测试变化、文档变化和审核证据。没有审核通过结论的批次不得解锁下一批。

本书是 100_body 与 200_lab：书籍化项目材料体系设计 定义的 lab book。它不替代 10 号书，不反向支撑 10 号书成立。本书只承担实现治理、批次执行、审核证据和关闭追溯职责。

本书面向执行者、审核者、协调者和后续维护者。执行者使用本书获取每批上下文闭包、文件边界、实施任务、测试任务和提交规则。审核者使用本书判断批次是否满足目标规格、工程质量契约、覆盖率门槛和打回条件。协调者使用状态台账判断批次是否可启动。后续维护者使用审核包和关闭记录追溯 book-entry mode 的实现过程。

本书使用中文叙事。book-entry mode、entry file、source set、logical document、line origin、source file table、origin source coordinate、parser core、work package、review package、status ledger、closure record 等术语在正文中保留英文形式或中英并列形式，以保持与 09 号书、10 号书、源码和测试之间的术语连续性。

第一部：执行契约

这一部定义本计划书的对象边界、工程质量契约、覆盖率门槛、批次状态、提交规则、审核规则、全局打回条件和当前源码基线。

1. 执行契约

本章定义本计划书的执行契约。所有批次章节、审核包、状态台账和关闭记录均受本章约束。

1.1. 对象边界

本计划书的对象是 book-entry source-mapped logical document 的实现序列。目标对象由 10 号书 定义；上游 parser 公共契约由 9 号书 定义；材料治理规则由 8 号书 定义。

本计划书不重新定义 logical document、line origin、source file table、include resolution、origin source coordinate 或 AbundantDocument。本计划书只定义如何从当前源码状态到达这些对象：哪些文件承担哪些职责，哪些测试证明行为成立，哪些质量门槛阻止低质量实现进入下一状态。

本计划书不定义下游 RDF 图对象，不实现完整 AsciiDoc preprocessor，不生成 HTML、PDF、site navigation 或 build/adoc 发布产物。下游投影器只作为 book-entry origin coordinate 的消费者进入本计划。

1.2. 公共目标

Library API 的目标入口是显式 book-entry mode：

parseAbundantTree({
	sourcePath: "docs/bookshelf/books/10-book-entry-source-mapped-logical-document/book.adoc",
	mode: "book-entry",
	documentRoot: "docs/bookshelf",
});

CLI 的目标入口是显式 --mode book-entry：

asciidoc-abundant-tree docs/bookshelf/books/10-book-entry-source-mapped-logical-document/book.adoc \
  --mode book-entry \
  --document-root docs/bookshelf \
  --format json

未声明 mode 的 library API 和 CLI 调用保持 single-file 语义。:doctype: book、文件名、include directive 和目录形状都不是模式切换开关。

1.3. 主数据流

Book-entry pipeline 的主数据流固定为：

entry file
  -> include resolution
  -> logical text + line origins + source file table
  -> parser core
  -> origin-aware AbundantDocument
  -> serializers and downstream projectors

该数据流中的 logical text 是 parser surface。line origins 和 source file table 是 origin recovery 的内部 IR。AbundantDocument 是下游主输入。下游投影器不得把 line origin table 作为主契约。

1.4. 批次状态

批次状态使用受控集合：

未开始

批次没有实现提交。
执行中

批次存在实现活动，尚未提交审核包。
待审核

批次提交 hash 和审核包已经产生。
打回

审核者拒绝通过该批次。
通过

审核者确认该批次满足本书验收条件。

批次状态记录在 批次状态台账。状态台账只记录治理事实，不记录愿望、估计、口头进度或情绪判断。

1.5. 批次门槛

每个批次开始前必须满足以下门槛：

  • 前一批次状态为 通过。

  • 前一批次提交 hash 已写入 批次状态台账。

  • 当前工作树中不存在与本批无关的未提交修改。

  • 执行者已经阅读本批上下文闭包列出的目标规格、上游 parser 契约、当前代码入口、测试入口和治理规则。

Batch 00 没有前置批次。Batch 00 开始前必须确认本计划书位于 docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/，10 号书位于 docs/bookshelf/books/10-book-entry-source-mapped-logical-document/，当前源码位于 src/。

1.6. 上下文闭包

每个批次必须列出上下文闭包。上下文闭包包含目标规格闭包、上游 parser 契约闭包、当前代码闭包、测试闭包和治理闭包。

执行者没有阅读本批上下文闭包时，不得开始本批实现。审核者必须检查 review package 是否记录本批上下文闭包的阅读事实。

上下文闭包不是装饰引用。每个 xref 或路径必须服务批次目标、文件边界、验收标准或打回条件。

1.7. 语言规则

批次任务、验收标准、审核结论和状态台账核心字段使用对象语言。以下表达不得作为任务授权、完成声明或审核依据：

  • 建议。

  • 可以考虑。

  • 最好。

  • 尽量。

  • 后续再说。

  • 视情况。

  • 基本完成。

  • 差不多。

  • 暂时支持。

  • 简单支持。

  • 未来完善。

  • 先这么做。

未确定对象不得进入实施任务。未确定对象必须登记为风险、相邻人工制品、打回项、后续 proposal 或明确非目标。

1.8. 工程质量契约

实现必须满足本节的工程质量契约。测试通过不替代工程质量判断。

1.8.1. 模块边界

Book-entry 输入构造位于 src/book-entry/。该目录承载 logical source builder、include resolution、path boundary、line origin、source file table 和构造 diagnostics。Include resolution 不得混入 src/parser.ts 主流程。

src/parser.ts 承担 public dispatcher 和 parser orchestration。它不得同时承担 include resolver、line origin mapper、origin raw recovery、CLI option parser 和 downstream projection 职责。

Parser core 必须具有内存文本入口。该入口接受 logical text 和 origin recovery context。Book-entry mode 不得通过写临时文件再调用 loadFile 取得 logical document。

Asciidoctor adapter 必须显式区分 file parse 和 memory parse。loadFile 服务 single-file mode；memory parse 入口服务 logical document。两种入口不得通过模糊布尔参数混合。

1.8.2. 数据流

Line origin 是内部 IR。下游主契约是 origin-aware AbundantDocument。如果实现提供 line origin debug surface，该表面必须与下游主契约分离。

Raw recovery 必须从 origin source file line table 恢复。Logical text 只能用于 official parse 和 logical interval 定位，不能作为 heading raw、block raw、xref raw 或 anchor raw 的 source file。

Source coordinate recovery 必须通过显式 mapper 或 coordinate service 完成。禁止在多个模块中散落重复的 line origin 查找、source file table 查找和 origin line table 切片逻辑。

Source scope index 必须包含 file identity。Book-entry mode 下，任何 containing section 查找都必须同时比较 relativePath 和 line range。

1.8.3. 控制流

Include resolution 必须在读取目标文件前检查 documentRoot 边界。越界 include 不得先读取再产生 warning。

Include cycle 必须通过 include stack 或访问状态检测。循环检测不得依赖递归深度错误。

Unsupported include attrlist 必须阻止 logical document 成立。实现不得把 tag、lines 或其它改变目标文件行集的 attrlist 静默当作 full-file include。

工具错误、构造错误和 recovery diagnostic 必须分层。构造错误阻止 successful AbundantDocument 成立；recovery diagnostic 只能用于局部 source coordinate 无法可靠恢复的情况。

1.8.4. 性能

同一 absolute path 在一个 book-entry 构造中最多读取一次。重复 include 可以在 logical document 中出现多次；source file table 中仍只有一个 file record。

Line origin lookup 不得在高频 recovery 路径上对全表做线性扫描。Origin lookup 应使用数组索引、map 或等价的 bounded lookup 结构。

Source file table 必须缓存 line table。Raw recovery 不得反复对同一 source text 执行 split。

Section scope lookup 不得对全书所有 sections 做无界扫描。实现应按 relativePath 分组或使用等价索引结构。

Downstream projection 不得为每个 resource 重复计算 documentRoot-relative path。Resource-level source coordinate 已有 origin relativePath 时，下游应直接消费该事实。

1.8.5. 可维护性

每个新增模块必须具有单一职责。src/book-entry/** 负责输入构造；parser core 负责解析编排；origin mapper 负责 logical-to-origin recovery；RDF12 修改只负责 downstream coordinate regression。

公共类型变更必须伴随 serializer、public API tests 和 downstream tests。类型逃逸、any 扩散或未测试的兼容分支不得通过审核。

代码注释只记录代码自身无法表达的约束、why 和不变量。注释不得解释代码表面动作。

新增 helper 必须消除真实重复或封装真实不变量。为了绕过测试而创建的一次性 wrapper 不得通过审核。

1.9. 覆盖率门槛

本计划的覆盖率目标是 90%。

Batch 00 必须运行 pnpm test:coverage 并记录当前覆盖率基线。若当前全项目覆盖率低于 90%，Batch 00 review package 必须记录真实基线，不得把目标写成通过事实。

新增 src/book-entry/** 模块的覆盖率必须不低于 90%。修改 parser core、source recovery、CLI mode parsing 和 downstream coordinate projection 的批次必须提供对应测试证据。

Batch 08 必须运行 pnpm test:coverage 并记录 coverage summary。最终完成声明不得省略覆盖率结果。覆盖率命令失败时，review package 必须记录失败输出、失败原因和阻塞判断。

1.10. 文件提交规则

提交在内部 Git 仓库 micheng-ts/projects/asciidoc-abundant-tree 中执行。

新文件必须先进入 Git index：

git add <new-files>

每批至少产生两个 Git 证据点：

实现提交

包含本批源码、测试、文档正文或 fixture 变更。状态台账中的提交 hash 指向该提交。
审核证据提交

包含本批审核包和状态台账更新。审核包记录实现提交 hash、实际命令结果和审核结论。

实现提交与审核证据提交均使用 git commit --only 限定路径：

git commit --only -m "<message>" -- <paths>

每个提交只包含该提交职责内的本批文件。跨批文件、其它项目文件、构建产物和无关格式化不得进入本批提交。

1.11. 审核包

每批完成后必须提交审核包。审核包格式见 阶段审核包模板。

审核包必须包含批次编号、批次名称、提交 hash、执行者、审核者、审核状态、修改文件、上下文闭包阅读记录、完成范围、未处理对象、已运行命令、命令结果、覆盖率结果、规约检查清单、工程质量检查清单和审核结论。

审核包文件位于本书 backmatter/，命名为 batch-NN-review-package.adoc。审核证据提交必须包含本批审核包和 批次状态台账更新；没有审核包文件的批次不得进入 待审核 状态。

没有提交 hash 的批次不得进入审核。没有审核通过结论的批次不得解锁下一批。计划运行但未运行的命令不得写入已运行命令。

1.12. 全局打回条件

出现以下任一情况，当前批次必须打回：

  • 未显式设置 mode: "book-entry" 却展开 include。

  • Single-file mode 展开 include。

  • :doctype: book 触发隐式 book-entry mode。

  • Book-entry 构造成功但没有 line origin。

  • Logical line count 与 line origin count 不一致。

  • Include path 越出 documentRoot 后仍读取目标文件。

  • Unsupported include attrlist 被当作 full-file include 处理。

  • Source coordinate 缺少 origin relativePath，却被下游当作 entry file coordinate。

  • Block span 跨多个 origin source files 时输出假 raw。

  • Containing section 只按 line number 查找。

  • 下游投影器读取 internal line origin table 作为主契约。

  • RDF12、JSON 或 pretty tree 输出把 build/adoc 聚合路径当作 origin source file，除非调用者显式把该聚合产物作为 ordinary single-file 输入。

  • Serializer 重新解析 AsciiDoc。

  • Parser core 为 book-entry 重新实现完整 AsciiDoc preprocessor。

  • 测试只证明 logical text 可解析，不证明 origin coordinate 正确。

  • 覆盖率命令未运行却写成通过。

1.13. 覆盖矩阵

10 号书承诺 实现批次 验收批次

显式 mode: "book-entry"，不隐式切换

Batch 01、Batch 05

Batch 05、Batch 08

documentRoot 是 relativePath 基准和路径边界

Batch 01、Batch 02、Batch 05

Batch 05、Batch 07、Batch 08

source set 与 source file table

Batch 02

Batch 02、Batch 07、Batch 08

full-file include resolution

Batch 02

Batch 02、Batch 03、Batch 08

escaped include 不展开

Batch 02

Batch 02、Batch 08

unsupported attrlist 阻止 logical document 成立

Batch 02

Batch 07、Batch 08

include cycle 阻止 logical document 成立

Batch 02

Batch 07、Batch 08

logical text 不写入 build/adoc

Batch 02

Batch 06、Batch 08

每个 logical line 有唯一 line origin

Batch 02

Batch 02、Batch 07

parser core 内存文本入口

Batch 03

Batch 03、Batch 08

heading raw 从 origin file 恢复

Batch 04

Batch 04、Batch 08

xref occurrence source coordinate 指向 origin file

Batch 04

Batch 04、Batch 08

source scope 查找比较 relativePath

Batch 04

Batch 04、Batch 08

downstream projector 不读取 line origin table

Batch 06

Batch 06、Batch 08

single-file mode 保持不变

Batch 00、Batch 01、Batch 03、Batch 05

Batch 08

contract tests 与最终完成声明

Batch 00、Batch 08

Batch 08

2. 当前源码状态

本章记录实现计划的源码基线。该基线描述当前事实，不定义目标对象。

2.1. 仓库与验证基线

项目位于：

/home/t103o/workbench/micheng-ts/projects/asciidoc-abundant-tree

该目录是内部 Git 仓库。提交和状态检查必须在该仓库中执行。

本计划书撰写前，工作树处于干净状态。以下基线命令已经作为调查证据运行：

pnpm test -- test/parser-include-source-map.test.ts test/parser-input-edges.test.ts
pnpm --dir docs/bookshelf test

第一条命令通过，Vitest 报告 38 个测试文件、258 个测试通过。第二条命令通过，书架 node test 报告 11 个测试通过。

2.2. 当前公共模型

src/model.ts 定义 AbundantDocument、节点 union、source layer、official layer、source span、line span、diagnostic 和 parse options。

当前 AbundantDocument.mode 只有 single-file。当前 ParseAbundantTreeOptions 只有 sourcePath。当前公共模型没有 book-entry mode、documentRoot、LineOrigin、SourceFileRecord 或 origin relativePath。

当前 SourceSpan 只包含 1-based line 和 1-based column。当前 SourceLayer 只包含 raw、line、span 和 sourceSpan。该模型不能区分 entry file 第 8 行和 chapter file 第 8 行。

2.3. 当前 parser 入口

src/parser.ts 当前把 single-file parse 固定为以下流程：

resolve(sourcePath)
  -> readFileSync(sourcePath)
  -> buildLineTable(source)
  -> adapter.loadFile(sourcePath)
  -> projectSourceSurfaces(...)
  -> projectOfficialDocument(...)
  -> assemble AbundantDocument(mode: "single-file")

该流程把 official parse surface 和 source recovery surface 绑定到同一个物理文件。它没有 parser core 内存文本入口，也没有 logical text、line origin 或 source file table。

2.4. 当前 Asciidoctor adapter

src/asciidoctor-adapter.ts 当前只公开 loadFile(sourcePath)。该入口调用 processor.loadFile(sourcePath, { safe: "secure", sourcemap: true, to_file: false })。

当前 adapter 没有 memory parse 入口。Book-entry mode 不能依赖当前 loadFile(entryPath)，因为该入口解析的是 entry file，不是 include resolution 后的 logical text。

2.5. 当前 include 相关测试

test/parser-include-source-map.test.ts 当前保护 single-file secure mode。该测试证明 include directive 在 single-file mode 下不展开，并且 official source location 指向外部文件时，projectSourceSurfaces 产生 source-location.external-file diagnostic 并跳过对应 official block。

该测试不是 book-entry pipeline 测试。它不构造 logical document，不生成 line origin，不恢复 origin source coordinate。

2.6. 当前 source surface recovery

src/source-surfaces.ts 遍历 official block surface，使用 single-file line table 恢复 source interval、section surface、inline occurrences、anchor occurrences、section scope 和 diagnostics。

当前 sectionByLine 是 Map<number, SectionNode>。assignContainingSectionIds 只按 line number 查找 section。该结构在 single-file mode 下成立，在 book-entry mode 下会把不同 source file 中的相同行号混在同一 scope 空间中。

src/inline-occurrence-scanner.ts 当前按 logical line table 扫描 xref 和 anchor，并生成 line/column source span。该 scanner 没有 origin relativePath。

src/official-projector.ts 当前从 single-file line table 读取 paragraph text、listing content、table span、section raw 和 target source span。该 projector 没有 origin raw recovery。

2.7. 当前 CLI

src/cli.ts 当前支持：

asciidoc-abundant-tree <file.adoc>
asciidoc-abundant-tree <file.adoc> --json
asciidoc-abundant-tree <file.adoc> --format tree
asciidoc-abundant-tree <file.adoc> --format json
asciidoc-abundant-tree <file.adoc> --format rdf12
asciidoc-abundant-tree <file.adoc> --format rdf12-json-ld
asciidoc-abundant-tree --help

当前 CLI 没有 --mode，没有 --document-root。当前 documentRoot 只在 RDF12 输出中默认为 process.cwd()，它不是 parser 输入构造参数。

2.8. 当前 downstream coordinate

src/rdf12-projection/path-coordinate.ts 根据 documentRoot 和 document.sourcePath 计算一个 document-level relativePath。

src/rdf12-projection/projector.ts 把该 relativePath 传给 structure、labels、xref、attributes 和 payload projection。当前 RDF12 resource-level source coordinate 默认来自同一个 document-level path。

Book-entry mode 要求同一 AbundantDocument 中的不同 resource 可以具有不同 origin relativePath。当前 RDF12 coordinate 数据流不能满足该要求。

2.9. 可复用基础设施

当前源码具有以下可复用基础设施：

  • src/source-lines.ts 提供 line table、line text、line span 和 source span 工具。

  • src/source-interval-resolver.ts 提供 official block source interval recovery。

  • src/official-block-walker.ts 提供 official AST 遍历。

  • src/metadata-parser.ts 提供 metadata surface parsing。

  • src/inline-occurrence-scanner.ts 提供 xref 和 anchor occurrence scanning。

  • src/official-projector.ts 提供 official projection 到 AbundantDocument tree 的基础。

  • src/serializers.ts 提供 pretty tree 和 JSON serialization。

  • src/rdf12-projection/** 提供 RDF 1.2 downstream projection、source location triples、path coordinate 和 serializer。

这些基础设施可以被 book-entry implementation 复用。复用不得改变 09 号书 single-file 契约。

2.10. 目标缺口

当前源码缺少以下目标对象：

  • mode: "book-entry" public option。

  • documentRoot parser input boundary。

  • src/book-entry/ input construction 模块。

  • full-file include resolution。

  • escaped include preservation。

  • unsupported include attrlist construction error。

  • include cycle detection。

  • source file table。

  • logical text。

  • line origin。

  • parser core memory entry。

  • origin source coordinate public model。

  • origin raw recovery。

  • relativePath-aware source scope lookup。

  • book-entry CLI。

  • downstream coordinate regression tests。

  • book-entry contract tests。

第二部：输入构造与公共模型

这一部建立迁移护栏，扩展公共模型，并实现 book-entry logical source builder。

3. Batch 00：基线与迁移护栏

3.1. 批次目标

本批建立 book-entry 迁移基线、目标验收、负契约测试、覆盖率基线和迁移期间允许失败集合。本批不修改运行时代码。

本批的核心产物是测试护栏。测试护栏必须直接来自 10 号书目标契约，而不是来自当前 single-file 实现形状。

3.2. 上游门槛

Batch 00 没有前置批次。开始前必须确认本计划书执行契约已经存在，当前工作树中不存在与本计划无关的未提交修改。

3.3. 本批上下文闭包

执行者必须阅读：

3.4. 输入事实

当前 parser 只支持 single-file mode。当前源码没有 book-entry public mode、logical source builder、line origin、source file table 或 origin-aware source coordinate。

10 号书要求 book-entry mode 由显式 public input 触发，并要求下游消费者从 AbundantDocument 中读取 origin source coordinate。

3.5. 文件边界

创建：

  • test/book-entry/fixtures/simple-book/book.adoc

  • test/book-entry/fixtures/simple-book/frontmatter/preface.adoc

  • test/book-entry/fixtures/simple-book/chapters/01-entry-origin.adoc

  • test/book-entry/fixtures/simple-book/chapters/02-target-origin.adoc

  • test/book-entry/fixtures/simple-book/chapters/nested/section.adoc

  • test/book-entry/fixtures/simple-book/backmatter/glossary.adoc

  • test/book-entry/fixtures/negative/missing-include.adoc

  • test/book-entry/fixtures/negative/circular-a.adoc

  • test/book-entry/fixtures/negative/circular-b.adoc

  • test/book-entry/fixtures/negative/unsupported-tag.adoc

  • test/book-entry/fixtures/negative/unsupported-lines.adoc

  • test/book-entry/fixtures/negative/outside-root.adoc

  • test/book-entry/book-entry.acceptance.test.ts

  • test/book-entry/book-entry-negative.test.ts

  • test/book-entry/single-file-regression.test.ts

  • docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/batch-00-review-package.adoc

修改：

  • docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/batch-status-ledger.adoc

不得修改：

  • src/**

  • README.md

  • CHANGELOG.md

3.6. Fixture 要求

simple-book/book.adoc 必须包含 document title、part heading、frontmatter include、chapter include、nested include、backmatter include 和 escaped include。Escaped include 必须以反斜杠开头，并作为普通 source line 保留。

两个 chapter 文件必须包含相同行号的 section surface。该 fixture 服务 Batch 04 的 relativePath-aware source scope 测试。

一个 chapter 文件必须包含 xref occurrence，另一个 chapter 文件必须包含 target section。该 fixture 服务 xref origin coordinate 和 target origin coordinate 测试。

Nested include 文件必须包含可被 parser 投影的 heading。该 fixture 服务递归 include 和 nested origin coordinate 测试。

3.7. 实施任务

  1. 创建 book-entry fixture 目录。

  2. 创建目标验收测试文件。

  3. 在目标验收测试顶部集中登记迁移期允许失败集合。

  4. 创建 negative contract 测试文件。

  5. 创建 single-file regression 测试文件。

  6. 记录当前覆盖率基线命令。

  7. 在真实提交和审核包产生后，将 Batch 00 状态台账条目更新为 待审核，并写入提交 hash 与审核包 xref。

  8. 本批计划文本不得预写未发生的状态事实。

3.8. 目标验收断言

book-entry.acceptance.test.ts 必须覆盖：

  • book-entry mode 返回 mode: "book-entry"。

  • sourcePath 表示 entry file。

  • Included heading 出现在 AbundantDocument section tree 中。

  • Entry heading 的 source relativePath 指向 entry file。

  • Chapter heading 的 source relativePath 指向 chapter file。

  • Nested include heading 的 source relativePath 指向 nested file。

  • Heading raw 来自 origin file。

  • Heading raw 不从 logical text 直接切取。

  • Xref occurrence 的 source coordinate 指向 xref 所在 origin file。

  • Target source coordinate 指向 target 所在 origin file。

  • Escaped include 不展开。

  • Same line number in different origin files 不污染 containing section scope。

book-entry-negative.test.ts 必须覆盖：

  • Missing include 失败。

  • Circular include 失败。

  • Unsupported tag attrlist 失败。

  • Unsupported lines attrlist 失败。

  • Include path outside documentRoot 失败。

  • Logical line count 与 line origin count 不一致时失败。

single-file-regression.test.ts 必须覆盖：

  • Single-file mode 不展开 include。

  • :doctype: book 不触发 book-entry mode。

  • 未传 mode 时保持 single-file。

3.9. 迁移期允许失败集合

Batch 00 可以把 book-entry 目标测试登记为 expected fail。Expected fail 标记必须集中在测试文件顶部，并标明移除批次：

公共模型与 coordinate identity 相关失败

Batch 01 移除。
logical source builder 相关失败

Batch 02 移除。
parser core memory entry 相关失败

Batch 03 移除。
origin-aware recovery 相关失败

Batch 04 移除。
public API 和 CLI 相关失败

Batch 05 移除。
downstream coordinate 相关失败

Batch 06 移除。
diagnostics 和 negative contracts 相关失败

Batch 07 移除。
最终迁移标记

Batch 08 全部删除。

Expected fail 不得散落在具体断言旁。审核者必须能从文件顶部看到每个允许失败对象的移除批次。

3.10. 验证命令

pnpm test -- test/book-entry test/parser-include-source-map.test.ts test/parser-input-edges.test.ts
pnpm typecheck
pnpm test:coverage
pnpm --dir docs/bookshelf test

Book-entry 目标测试在 Batch 00 可以包含 expected fail。Single-file regression、typecheck 和书架测试必须通过。Coverage 命令必须运行并记录真实结果。

3.11. 提交规则

git add test/book-entry
git commit --only -m "test: add book-entry migration guardrails" -- test/book-entry
git add docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/batch-00-review-package.adoc docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/batch-status-ledger.adoc
git commit --only -m "docs: record book-entry batch 00 review" -- docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/batch-00-review-package.adoc docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/batch-status-ledger.adoc

第二个提交记录第一个提交的 hash。状态台账的 Batch 00 提交 hash 指向第一个提交。

3.12. 审核规则

审核者必须确认本批没有修改 src/**。审核者必须确认目标测试直接来自 10 号书 contract tests、source coordinate recovery 和 diagnostics 章节。审核者必须确认 expected fail 集中登记，并且每个 expected fail 有移除批次。

3.13. 打回条件

出现以下任一情况，本批不通过：

  • 本批修改 src/**。

  • 目标测试只证明 include 展开，不证明 origin coordinate。

  • Negative tests 缺少 missing include、cycle、unsupported attrlist 或 outside documentRoot。

  • Expected fail 标记散落在断言旁。

  • Single-file regression 未覆盖 :doctype: book 不触发 book-entry。

  • 覆盖率命令未运行却写成通过。

4. Batch 01：公共模型与坐标身份

4.1. 批次目标

本批扩展 public model，使 AbundantDocument 能表达 single-file 和 book-entry 两种输入构造身份，并使可回源事实能携带 origin relativePath。

本批不实现 include resolution。本批不实现 parser core memory entry。本批只建立公共模型、类型边界、serializer 表面和目标测试。

4.2. 上游门槛

4.3. 本批上下文闭包

执行者必须阅读：

4.4. 输入事实

当前 AbundantDocument.mode 只有 single-file。当前 ParseAbundantTreeOptions 没有 mode 和 documentRoot。当前 source coordinate 没有文件身份。

10 号书要求 book-entry 输出中每个可回源事实指向 origin source file。下游投影器不得读取 line origin table 作为主契约。

4.5. 文件边界

修改：

  • src/model.ts

  • src/serializers.ts

  • src/index.ts

  • test/serializers.test.ts

  • test/parser.test.ts

  • test/book-entry/book-entry.acceptance.test.ts

不得修改：

  • src/parser.ts 的运行时流程，除非只为类型编译做最小兼容。

  • src/book-entry/**

  • src/rdf12-projection/**

4.6. 公共模型目标

AbundantDocument.mode 必须扩展为：

"single-file" | "book-entry"

ParseAbundantTreeOptions 必须成为 discriminated union：

export type ParseAbundantTreeOptions =
	| {
			sourcePath: string;
			mode?: "single-file";
	  }
	| {
			sourcePath: string;
			mode: "book-entry";
			documentRoot: string;
	  };

可回源事实必须能表达 origin relativePath。公共坐标权威位置是 SourceLayer.relativePath。SourceSpan 只表达 line/column 范围，不携带 file identity：

export type SourceLayer = {
	raw?: string;
	relativePath?: string;
	line?: number;
	span?: LineSpan;
	sourceSpan?: SourceSpan;
};

节点如果同时保留顶层 sourceSpan 和 source.sourceSpan，顶层 sourceSpan 只能作为兼容镜像存在。消费者读取 origin file identity 时必须使用 source.relativePath。实现不得让顶层 span 与 source layer relativePath 表达两个互相矛盾的 coordinate。

4.7. 实施任务

  1. 扩展 AbundantDocument.mode。

  2. 扩展 ParseAbundantTreeOptions。

  3. 为 source layer 增加 relativePath，并把它作为 public origin file identity 的权威位置。

  4. 更新 public type exports。

  5. 更新 serializer ordering，使 relativePath 在 pretty tree 和 JSON 中可见。

  6. 更新 single-file parser 测试，确认 single-file 输出仍为 mode: "single-file"。

  7. 更新 book-entry expected-fail 测试中的公共 JSON 目标形状。

4.8. 测试任务

parser.test.ts 必须断言未传 mode 时输出 mode: "single-file"。

serializers.test.ts 必须断言 source.relativePath 在 JSON serialization 中保留，并且 pretty tree 不隐藏该字段。

book-entry.acceptance.test.ts 必须断言目标公共形状可以表达 entry file、chapter file 和 nested file 的不同 relativePath。

Public model tests 必须断言 SourceSpan 不携带 file identity。该断言保护 line/column range 与 origin file identity 的职责分离。

4.9. 验收标准

  • Public model 可以表达 book-entry mode。

  • Public parse options 可以表达显式 documentRoot。

  • 可回源事实通过 source.relativePath 表达 origin relativePath。

  • SourceSpan 只表达 line/column 范围。

  • Line origin table 没有进入 AbundantDocument 主模型。

  • Single-file mode 保持默认语义。

  • Serializer 不重新解析 AsciiDoc。

4.10. 验证命令

pnpm test -- test/parser.test.ts test/serializers.test.ts test/book-entry/book-entry.acceptance.test.ts
pnpm typecheck
pnpm test:coverage

4.11. 提交规则

git add src/model.ts src/serializers.ts src/index.ts test/parser.test.ts test/serializers.test.ts test/book-entry
git commit --only -m "feat: extend parser model for book-entry coordinates" -- src/model.ts src/serializers.ts src/index.ts test/parser.test.ts test/serializers.test.ts test/book-entry
git add docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/batch-01-review-package.adoc docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/batch-status-ledger.adoc
git commit --only -m "docs: record book-entry batch 01 review" -- docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/batch-01-review-package.adoc docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/batch-status-ledger.adoc

第二个提交记录第一个提交的 hash。状态台账的 Batch 01 提交 hash 指向第一个提交。

4.12. 审核规则

审核者必须检查 public model 是否有单一 coordinate 权威。审核者必须检查 line origin table 没有进入下游主契约。审核者必须检查类型变更没有通过 any 或类型断言掩盖不一致。

4.13. 打回条件

出现以下任一情况，本批不通过：

  • AbundantDocument 暴露 line origin table 作为下游主契约。

  • SourceSpan、SourceLayer 和节点顶层字段表达互相矛盾的 file identity。

  • SourceSpan 携带 file identity。

  • 消费者必须读取顶层 sourceSpan 才能取得 origin file identity。

  • Single-file consumer 必须理解 book-entry internal IR 才能读取旧字段。

  • mode 仍只能是 single-file。

  • TypeScript 类型错误通过 any、双重断言或未测试分支绕过。

5. Batch 02：Logical Source Builder

5.1. 批次目标

本批实现 book-entry input construction 模块。该模块从 entry file 出发，解析受支持 full-file include directive，生成 logical text、line origins、source file table 和构造错误。

本批不调用 Asciidoctor。本批不构造 AbundantDocument。本批不修改 CLI。

5.2. 上游门槛

5.3. 本批上下文闭包

执行者必须阅读：

5.4. 输入事实

Book-entry logical document 是 parser input construction 对象。它不是 Asciidoctor AST，不是 downstream resource graph，不是 build/adoc 发布产物。

10 号书只授权 full-file include resolution。Escaped include 不展开。Unsupported attrlist、missing include、outside documentRoot 和 cycle 都阻止 logical document 成立。

5.5. 文件边界

创建：

  • src/book-entry/model.ts

  • src/book-entry/path-boundary.ts

  • src/book-entry/include-resolution.ts

  • src/book-entry/logical-source-builder.ts

  • src/book-entry/diagnostics.ts

  • test/book-entry/logical-source-builder.test.ts

  • test/book-entry/include-resolution.test.ts

  • docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/batch-02-review-package.adoc

修改：

  • test/book-entry/book-entry-negative.test.ts

  • test/book-entry/book-entry.acceptance.test.ts

  • docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/batch-status-ledger.adoc

不得修改：

  • src/parser.ts

  • src/asciidoctor-adapter.ts

  • src/rdf12-projection/**

5.6. 内部数据模型

src/book-entry/model.ts 必须定义等价于以下对象的内部类型：

export type LineOrigin = {
	readonly logicalLine: number;
	readonly absolutePath: string;
	readonly relativePath: string;
	readonly sourceLine: number;
};

export type SourceFileRecord = {
	readonly absolutePath: string;
	readonly relativePath: string;
	readonly text: string;
	readonly lineTable: LineTable;
};

export type LogicalSource = {
	readonly entryPath: string;
	readonly documentRoot: string;
	readonly logicalText: string;
	readonly lineOrigins: readonly LineOrigin[];
	readonly sourceFiles: readonly SourceFileRecord[];
};

实现可以使用更精确的名称，但必须保留这些对象职责。

5.7. 实施任务

  1. 创建 src/book-entry/ 模块边界。

  2. 实现 documentRoot-relative path 计算和越界检查。

  3. 实现 full-file include directive 识别。

  4. 实现 escaped include preservation。

  5. 实现 include target 按 containing file directory 解析。

  6. 实现 recursive include resolution。

  7. 实现 include cycle detection。

  8. 实现 source file table 去重。

  9. 实现 logical text construction。

  10. 为每个 logical line 生成唯一 line origin。

  11. 实现 construction error 类型和 diagnostic code。

  12. 确保 builder 不调用 Asciidoctor。

5.8. 诊断 code

本批必须定义稳定 construction error code：

include.missing-target

Include target file does not exist.
include.outside-document-root

Resolved include path is outside documentRoot.
include.cycle

Include graph contains a cycle.
include.unsupported-attrlist

Include directive uses an unsupported attrlist.
logical-line-origin.count-mismatch

Logical line count does not match line origin count.
line-origin.source-file-missing

Line origin references a file missing from source file table.
line-origin.source-line-out-of-range

Line origin references a source line outside the origin file line table.

Diagnostic message 必须描述对象事实，不写“暂时不支持”或“以后实现”。

5.9. 测试任务

logical-source-builder.test.ts 必须覆盖：

  • Simple include 展开。

  • Nested include 展开。

  • Shared attributes include 展开。

  • Repeated include 在 logical text 中出现多次。

  • Same absolute path 在 source file table 中只出现一次。

  • Escaped include 不展开。

  • Relative include target 按 containing directive 所在目录解析。

  • Logical line count 与 line origin count 一致。

  • 每个 line origin 的 source file 存在于 source file table。

  • 每个 line origin 的 sourceLine 位于对应 line table 范围内。

include-resolution.test.ts 必须覆盖：

  • Missing include 失败。

  • Circular include 失败。

  • Unsupported tag=main 失败。

  • Unsupported lines=1..20 失败。

  • Outside documentRoot 失败。

  • 越界 include 不读取目标文件。

5.10. 性能要求

Source file table 必须以 absolutePath 去重。Builder 在一个 book-entry 构造中不得重复读取同一 absolutePath。

Line origins 必须以 logical line 顺序保存。按 logical line 查找 origin 时不得对全表做线性扫描。

Source file record 必须缓存 line table。Raw recovery 批次不得重新 split 同一 source text。

5.11. 验收标准

  • src/book-entry/** 新模块覆盖率不低于 90%。

  • Builder 不调用 Asciidoctor。

  • Builder 不解析 block、xref、anchor 或 metadata。

  • Builder 不写入 build/adoc。

  • Construction errors 阻止 logical source 成立。

  • Escaped include 作为普通 source line 进入 logical text。

  • Logical text 非 include 行保持原文。

5.12. 验证命令

pnpm test -- test/book-entry/logical-source-builder.test.ts test/book-entry/include-resolution.test.ts test/book-entry/book-entry-negative.test.ts
pnpm typecheck
pnpm test:coverage

5.13. 提交规则

git add src/book-entry test/book-entry
git commit --only -m "feat: build source-mapped book-entry logical text" -- src/book-entry test/book-entry
git add docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/batch-02-review-package.adoc docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/batch-status-ledger.adoc
git commit --only -m "docs: record book-entry batch 02 review" -- docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/batch-02-review-package.adoc docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/batch-status-ledger.adoc

第二个提交记录第一个提交的 hash。状态台账的 Batch 02 提交 hash 指向第一个提交。

5.14. 审核规则

审核者必须检查 include path 边界在读取文件前执行。审核者必须检查 unsupported attrlist 没有被当作 full-file include。审核者必须检查 builder 与 Asciidoctor 没有依赖关系。

5.15. 打回条件

出现以下任一情况，本批不通过：

  • Include 越界后仍读取文件。

  • Unsupported attrlist 被当作 whole-file include。

  • Logical text 构造改写普通 source line。

  • Line origin 缺失或重复。

  • Source file table 重复读取同一 absolutePath。

  • Builder 调用 Asciidoctor 或扫描 AsciiDoc block 结构。

  • src/book-entry/** 覆盖率低于 90%。

第三部：Parser 集成与回源

这一部建立 parser core 内存入口，并把 logical coordinate 恢复为 origin source coordinate。

6. Batch 03：Parser Core 内存入口

6.1. 批次目标

本批把 logical source 接入 parser core。Parser core 必须能解析 in-memory logical text，并返回标准 AbundantDocument。

本批不完成 origin-aware raw recovery。Logical line 到 origin source coordinate 的完整转换归属 Batch 04。

6.2. 上游门槛

6.3. 本批上下文闭包

执行者必须阅读：

6.4. 输入事实

Current parser 入口读取一个 physical source file，并调用 adapter.loadFile(sourcePath)。Book-entry pipeline 需要 parser 解析 logical text，而不是 entry file。

Asciidoctor official AST 仍然是 block identity 和 structure relation 的权威。Source recovery 仍然由 parser source layer 负责。Book-entry mode 不创建旁路 document model。

6.5. 文件边界

修改：

  • src/parser.ts

  • src/asciidoctor-adapter.ts

  • src/source-surfaces.ts

  • src/official-projector.ts

  • test/parser.test.ts

  • test/parser-include-source-map.test.ts

  • test/book-entry/book-entry.acceptance.test.ts

  • docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/batch-status-ledger.adoc

允许创建：

  • src/parser-core.ts

  • test/book-entry/parser-integration.test.ts

  • docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/batch-03-review-package.adoc

不得修改：

  • src/rdf12-projection/**

  • src/cli.ts

  • README.md

  • CHANGELOG.md

6.6. 实施任务

  1. 拆出 parser core，使 file input 和 logical input 共享 official projection、source surface projection、target merge 和 serializer-compatible document assembly。

  2. 在 Asciidoctor adapter 中新增 memory parse 入口。该入口解析 logical text。

  3. 保留 loadFile(sourcePath) 作为 single-file mode 专用入口。

  4. 让 parseAbundantTree({ sourcePath, mode: "book-entry", documentRoot }) 调用 logical source builder，再调用 parser core。

  5. 让 book-entry 返回 AbundantDocument，并设置 mode: "book-entry"。

  6. 让 book-entry 返回的 sourcePath 表示 entry file。

  7. 保持 single-file path 的运行时行为不变。

  8. 写 characterization test，证明 memory parse 的 official source line 与 logical line 对齐。

6.7. Parser core 约束

Parser core 的输入必须包含 logical line table。Parser core 不得从 entry file 重新读取 source text 作为 parse surface。

Parser core 可以接收 origin recovery context，但本批只要求 logical line 级行为成立。Origin recovery context 在 Batch 04 成为 source coordinate mapper 的输入。

Book-entry mode 不得写临时文件再调用 loadFile。临时文件会把 logical document 伪装成 source file identity，并破坏 10 号书的非源文件身份规则。

6.8. 测试任务

parser-integration.test.ts 必须覆盖：

  • Book-entry parser 解析 logical text。

  • Included heading 出现在 AbundantDocument.children。

  • document.mode 是 book-entry。

  • document.sourcePath 是 entry file path。

  • Asciidoctor memory parse source line 与 logical line 对齐。

  • Book-entry parser 不依赖 Asciidoctor include sourcemap。

parser.test.ts 必须继续覆盖 single-file public API。

parser-include-source-map.test.ts 必须继续覆盖 single-file secure-mode include 不展开。

6.9. 验收标准

  • Public parser 返回标准 AbundantDocument，不是 book-entry 专用旁路对象。

  • Book-entry mode 使用 logical text 作为 official parse surface。

  • Single-file mode 调用 loadFile(sourcePath)。

  • Memory parse 入口与 file parse 入口可审查地区分。

  • Included headings 可以进入 section tree。

  • Book-entry mode 不生成 build/adoc 文件。

6.10. 验证命令

pnpm test -- test/book-entry/parser-integration.test.ts test/book-entry/book-entry.acceptance.test.ts test/parser.test.ts test/parser-include-source-map.test.ts
pnpm typecheck
pnpm test:coverage

6.11. 提交规则

git add src/parser.ts src/asciidoctor-adapter.ts src/source-surfaces.ts src/official-projector.ts src/parser-core.ts test/parser.test.ts test/parser-include-source-map.test.ts test/book-entry
git commit --only -m "feat: parse book-entry logical documents" -- src/parser.ts src/asciidoctor-adapter.ts src/source-surfaces.ts src/official-projector.ts src/parser-core.ts test/parser.test.ts test/parser-include-source-map.test.ts test/book-entry
git add docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/batch-03-review-package.adoc docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/batch-status-ledger.adoc
git commit --only -m "docs: record book-entry batch 03 review" -- docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/batch-03-review-package.adoc docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/batch-status-ledger.adoc

若 src/parser-core.ts 未创建，第一个提交命令应移除该路径；审核包和状态台账路径不得从第二个提交命令中移除。

第二个提交记录第一个提交的 hash。状态台账的 Batch 03 提交 hash 指向第一个提交。

6.12. 审核规则

审核者必须检查 book-entry mode 没有调用 loadFile(entryPath) 作为 logical document parse。审核者必须检查 parser core 不通过临时文件模拟 memory parse。审核者必须检查 single-file include regression 没有回退。

6.13. 打回条件

出现以下任一情况，本批不通过：

  • Book-entry mode 调用 adapter.loadFile(entryPath) 并依赖 Asciidoctor include sourcemap。

  • Parser core 把 logical text 写入临时文件。

  • Single-file mode 行为变化。

  • Memory parse source line 无法与 logical line 对齐却继续通过。

  • Book-entry mode 返回非标准 AbundantDocument。

7. Batch 04：Origin-aware Source Recovery

7.1. 批次目标

本批把 parser 在 logical document 中观察到的 source line、source span 和 source interval 转换为 origin source coordinate。

本批完成 heading raw、xref occurrence、anchor occurrence、target、paragraph、listing、table 和 source scope 的 origin-aware recovery。

7.2. 上游门槛

7.3. 本批上下文闭包

执行者必须阅读：

7.4. 输入事实

Logical line number 是 parser observation surface。Origin source coordinate 是 public recovery surface。二者必须通过 line origin 映射连接。

Logical document 没有 source file identity。Raw recovery 必须回到 origin source file line table。

7.5. 文件边界

修改：

  • src/source-lines.ts

  • src/source-surfaces.ts

  • src/inline-occurrence-scanner.ts

  • src/official-projector.ts

  • src/source-interval-resolver.ts

  • src/book-entry/**

  • test/source-surfaces.test.ts

  • test/official-projector.test.ts

  • test/parser-input-edges.test.ts

  • test/book-entry/book-entry.acceptance.test.ts

  • docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/batch-status-ledger.adoc

允许创建：

  • src/book-entry/origin-coordinate.ts

  • src/book-entry/source-scope-index.ts

  • test/book-entry/source-coordinate-recovery.test.ts

  • test/book-entry/source-scope-index.test.ts

  • docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/batch-04-review-package.adoc

不得修改：

  • src/rdf12-projection/**

  • src/cli.ts

  • README.md

  • CHANGELOG.md

7.6. 实施任务

  1. 实现 logical line 到 line origin 的 lookup。

  2. 实现 origin line table lookup。

  3. 实现 origin source span construction。

  4. 实现 origin raw slice recovery。

  5. 将 section source layer 映射到 origin relativePath。

  6. 将 xref occurrence source layer 映射到 origin relativePath。

  7. 将 anchor occurrence source layer 映射到 origin relativePath。

  8. 将 target source coordinate 映射到 origin relativePath。

  9. 将 paragraph、listing 和 table source layer 映射到 origin relativePath。

  10. 将 source scope index 改为 relativePath-aware。

  11. 跨 origin source files 的 block span 不输出假 raw，并产生 recovery diagnostic。

  12. 保持 single-file recovery 行为不变。

7.7. Source scope 规则

错误规则：

candidate.startLine <= line <= candidate.endLine

正确规则：

candidate.relativePath == occurrence.relativePath
candidate.startLine <= occurrence.line <= candidate.endLine

实现必须把正确规则编码为可测试对象。审核者不得接受只在注释中说明该规则的实现。

7.8. Recovery diagnostic

本批必须定义或使用以下 recovery diagnostic：

source-recovery.cross-origin-block

Block span maps to more than one origin source file.
source-recovery.origin-line-missing

Origin file line table cannot recover requested source line.
source-recovery.logical-interval-unmapped

Parser core interval cannot map to line origin.

Recovery diagnostic 必须阻止假精确坐标输出。无法可靠恢复的 source coordinate 应保持缺失。

7.9. 测试任务

source-coordinate-recovery.test.ts 必须覆盖：

  • Entry file heading source relativePath 指向 entry file。

  • Chapter heading source relativePath 指向 chapter file。

  • Nested include heading source relativePath 指向 nested file。

  • Heading raw 来自 origin file。

  • Heading raw 不从 logical text 直接切取。

  • Xref occurrence source relativePath 指向 xref 所在 origin file。

  • Anchor occurrence source relativePath 指向 anchor 所在 origin file。

  • Target source relativePath 指向 target 定义所在 origin file。

  • Listing raw、contentSpan 和 source span 来自 origin file。

  • Table source span 来自 origin file。

  • Cross-origin block 不输出假 raw，并产生 recovery diagnostic。

source-scope-index.test.ts 必须覆盖：

  • 两个不同 origin files 中相同行号的 section 不互相污染。

  • Xref containingSectionId 使用 xref occurrence 的 relativePath。

  • Anchor containingSectionId 使用 anchor occurrence 的 relativePath。

parser-input-edges.test.ts 必须继续覆盖 CRLF 和 Unicode columns。

7.10. 验收标准

  • 每个可回源事实携带 origin relativePath，或缺失 coordinate 并产生 diagnostic。

  • Raw recovery 从 origin source file line table 恢复。

  • Source scope lookup 比较 relativePath。

  • Cross-origin block 不输出假 raw。

  • Single-file mode 坐标回归通过。

  • 新增 origin coordinate mapper 代码覆盖率不低于 90%。

7.11. 验证命令

pnpm test -- test/book-entry/source-coordinate-recovery.test.ts test/book-entry/source-scope-index.test.ts test/book-entry/book-entry.acceptance.test.ts test/parser-input-edges.test.ts test/source-surfaces.test.ts test/official-projector.test.ts
pnpm typecheck
pnpm test:coverage

7.12. 提交规则

git add src/source-lines.ts src/source-surfaces.ts src/inline-occurrence-scanner.ts src/official-projector.ts src/source-interval-resolver.ts src/book-entry test/book-entry test/parser-input-edges.test.ts test/source-surfaces.test.ts test/official-projector.test.ts
git commit --only -m "feat: recover book-entry origin source coordinates" -- src/source-lines.ts src/source-surfaces.ts src/inline-occurrence-scanner.ts src/official-projector.ts src/source-interval-resolver.ts src/book-entry test/book-entry test/parser-input-edges.test.ts test/source-surfaces.test.ts test/official-projector.test.ts
git add docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/batch-04-review-package.adoc docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/batch-status-ledger.adoc
git commit --only -m "docs: record book-entry batch 04 review" -- docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/batch-04-review-package.adoc docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/batch-status-ledger.adoc

第二个提交记录第一个提交的 hash。状态台账的 Batch 04 提交 hash 指向第一个提交。

7.13. 审核规则

审核者必须检查所有 line containment 查找都比较 relativePath。审核者必须检查 raw recovery 没有从 logical text 直接切取。审核者必须检查 cross-origin block 的 diagnostic 和缺失 coordinate 同时成立。

7.14. 打回条件

出现以下任一情况，本批不通过：

  • 任一 book-entry source coordinate 使用 entry file path 替代真实 origin file。

  • sectionByLine 或同等结构仍只按 line number 匹配。

  • Raw recovery 从 logical text 直接切取。

  • Cross-origin block 输出假 raw。

  • 坐标使用 0-based line 或 column。

  • 缺失坐标使用 0、-1 或空字符串代替。

  • Origin coordinate mapper 覆盖率低于 90%。

第四部：公共入口与下游坐标

这一部锁定 book-entry public API、CLI mode、downstream coordinate regression、diagnostics 和 negative contracts。

8. Batch 05：Public API 与 CLI Mode

8.1. 批次目标

本批把 book-entry mode 锁定为显式 public API 和 CLI mode。本批还定义 documentRoot 的 CLI 行为、错误出口和 help surface。

8.2. 上游门槛

8.3. 本批上下文闭包

执行者必须阅读：

8.4. 输入事实

10 号书要求调用者显式声明 book-entry mode。Library API 中，book-entry 调用必须提供 documentRoot。CLI 可以使用当前工作目录作为默认 documentRoot，并允许调用者显式覆盖。

8.5. 文件边界

修改：

  • src/parser.ts

  • src/cli.ts

  • src/index.ts

  • test/cli.test.ts

  • test/cli-error.test.ts

  • test/book-entry/book-entry.acceptance.test.ts

允许修改：

  • README.md

不得修改：

  • src/rdf12-projection/**

  • CHANGELOG.md

8.6. CLI 公共表面

CLI 必须支持：

asciidoc-abundant-tree <file.adoc> --mode book-entry --document-root <root> --format json
asciidoc-abundant-tree <file.adoc> --mode book-entry --format tree
asciidoc-abundant-tree <file.adoc> --mode single-file --format json
asciidoc-abundant-tree <file.adoc> --format json

默认 mode 是 single-file。--mode book-entry 只选择输入构造方式，不改变 output format 的对象定义。

--document-root 在 book-entry mode 中作为 relativePath 基准和路径边界。CLI 未显式传入 --document-root 时，默认值是当前工作目录。

8.7. 实施任务

  1. 扩展 CLI args parser，支持 --mode single-file|book-entry。

  2. 扩展 CLI args parser，支持 --document-root <path>。

  3. 更新 --help 输出。

  4. Library API 在 book-entry mode 缺少 documentRoot 时抛出错误。

  5. CLI book-entry mode 使用解析后的 documentRoot。

  6. CLI single-file mode 忽略 documentRoot 对 parser 输入构造的影响，但 RDF12 output 仍使用 documentRoot 作为 projection option。

  7. 错误输出写入 stderr。

  8. 成功输出写入 stdout。

  9. 更新 README public usage。

8.8. 测试任务

cli.test.ts 必须覆盖：

  • --help 显示 --mode 和 --document-root。

  • --mode book-entry --format json 输出 book-entry JSON。

  • --mode book-entry --format tree 输出 pretty tree。

  • 未提供 --mode 时保持 single-file。

  • --mode single-file 不展开 include。

  • CLI book-entry mode 默认 documentRoot 为 current working directory。

  • CLI book-entry mode 可以显式覆盖 documentRoot。

  • --format rdf12 和 --format rdf12-json-ld 可以消费 book-entry AbundantDocument。

cli-error.test.ts 必须覆盖：

  • Unsupported mode 返回错误。

  • --mode 缺少值返回错误。

  • --document-root 缺少值返回错误。

  • Library API book-entry 缺少 documentRoot 抛错。

  • Input file outside documentRoot 返回错误。

  • Include outside documentRoot 返回错误。

  • rdf、ttl、turtle 仍不是 format alias。

8.9. 验收标准

  • Book-entry mode 必须显式声明。

  • :doctype: book 不触发 book-entry。

  • Library API 和 CLI mode 语义一致。

  • CLI 错误出口与 9 号书一致。

  • README 只描述当前 public behavior，不叙述迁移过程。

8.10. 验证命令

pnpm test -- test/cli.test.ts test/cli-error.test.ts test/book-entry/book-entry.acceptance.test.ts
pnpm typecheck
pnpm test:coverage

8.11. 提交规则

git add src/parser.ts src/cli.ts src/index.ts test/cli.test.ts test/cli-error.test.ts test/book-entry README.md
git commit --only -m "feat: expose book-entry parser mode" -- src/parser.ts src/cli.ts src/index.ts test/cli.test.ts test/cli-error.test.ts test/book-entry README.md
git add docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/batch-05-review-package.adoc docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/batch-status-ledger.adoc
git commit --only -m "docs: record book-entry batch 05 review" -- docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/batch-05-review-package.adoc docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/batch-status-ledger.adoc

若 README 未修改，第一个提交命令应移除该路径；审核包和状态台账路径不得从第二个提交命令中移除。

第二个提交记录第一个提交的 hash。状态台账的 Batch 05 提交 hash 指向第一个提交。

8.12. 审核规则

审核者必须检查 mode 选择只来自 public option 或 CLI flag。审核者必须检查 CLI argument parser 不静默忽略未知参数。审核者必须检查 stdout/stderr 行为。

8.13. 打回条件

出现以下任一情况，本批不通过：

  • 文件名、doctype 或 include directive 触发隐式 book-entry。

  • Library API 和 CLI mode 语义不一致。

  • Unknown mode 被静默当作 single-file。

  • --document-root 越界检查缺失。

  • 错误消息写入 stdout。

  • 成功输出写入 stderr。

9. Batch 06：Downstream Coordinate Regression

9.1. 批次目标

本批使 downstream projectors 消费 book-entry AbundantDocument 中的 origin source coordinate。本批不改变 RDF 1.2 标题投影图对象语义。

本批的主要 downstream surface 是 RDF12 projection。RDF12 resource-level source coordinate 必须来自节点自身 source layer，而不是来自 document-level sourcePath。

9.2. 上游门槛

9.3. 本批上下文闭包

执行者必须阅读：

9.4. 输入事实

当前 RDF12 projection 根据 document.sourcePath 计算一个 document-level relativePath，并把该 path 传给多个 resource projection 模块。

Book-entry mode 允许同一 AbundantDocument 中的 resources 来自不同 origin files。下游 projection 必须读取 resource 自身 source coordinate。

9.5. 文件边界

修改：

  • src/rdf12-projection/source-location.ts

  • src/rdf12-projection/projector.ts

  • src/rdf12-projection/structure-projector.ts

  • src/rdf12-projection/labels.ts

  • src/rdf12-projection/xref-projector.ts

  • src/rdf12-projection/payload-projector.ts

  • test/rdf12-projection/structure-projector.test.ts

  • test/rdf12-projection/xref-projector.test.ts

  • test/rdf12-projection/query-contracts.test.ts

  • test/book-entry/book-entry.acceptance.test.ts

  • docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/batch-status-ledger.adoc

允许创建：

  • test/rdf12-projection/book-entry-coordinate.test.ts

  • docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/batch-06-review-package.adoc

不得修改：

  • src/book-entry/**

  • src/parser.ts

  • RDF12 graph object semantics unrelated to source coordinate。

9.6. 实施任务

  1. 为 RDF12 source-location projection 增加 resource-level relativePath 读取规则。

  2. 保留 document-level provenance 对 entry file 的描述。

  3. 让 heading resource 使用 section source layer 的 relativePath。

  4. 让 xref edge evidence 使用 xref occurrence source layer 的 relativePath。

  5. 让 payload、direct field 和 label 相关 source coordinate 使用 owner 或 occurrence 的 origin coordinate。

  6. 删除对所有 resource 统一传入 document-level relativePath 的旧路径，或隔离为 document-level provenance 专用路径。

  7. 确认 downstream projector 不读取 line origin table。

  8. 保持 6 号书和 7 号书锁定的 RDF12 graph 对象语义。

9.7. 测试任务

book-entry-coordinate.test.ts 必须覆盖：

  • Book-entry RDF12 graph 中不同 headings 可以拥有不同 aat:relativePath。

  • Entry heading 使用 entry file relativePath。

  • Chapter heading 使用 chapter file relativePath。

  • Nested include heading 使用 nested file relativePath。

  • Xref edge evidence 使用 xref occurrence 所在文件 relativePath。

  • Projection-level source document provenance 可以继续指向 entry file。

  • 输出不包含 build/adoc 聚合路径。

  • RDF12 projector 不需要 line origin table 参数。

Existing RDF12 tests 必须继续证明：

  • RDF12 标题投影图对象语义不变。

  • Turtle 和 JSON-LD serializer 不回退。

  • rdf、ttl、turtle 不是 CLI format alias。

9.8. 验收标准

  • Resource-level source coordinate 来自 node 或 occurrence 自身 source layer。

  • Document-level path coordinate 只用于 document/provenance 层对象。

  • Downstream projector 不读取 internal line origin table。

  • RDF12 graph 不出现 build/adoc 聚合路径，除非输入本身就是普通 single-file 聚合产物。

  • RDF12 标题投影图语义不改变。

9.9. 验证命令

pnpm test -- test/rdf12-projection/book-entry-coordinate.test.ts test/rdf12-projection/structure-projector.test.ts test/rdf12-projection/xref-projector.test.ts test/rdf12-projection/query-contracts.test.ts test/book-entry/book-entry.acceptance.test.ts
pnpm typecheck
pnpm test:coverage

9.10. 提交规则

git add src/rdf12-projection test/rdf12-projection test/book-entry
git commit --only -m "feat: project book-entry origin coordinates downstream" -- src/rdf12-projection test/rdf12-projection test/book-entry
git add docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/batch-06-review-package.adoc docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/batch-status-ledger.adoc
git commit --only -m "docs: record book-entry batch 06 review" -- docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/batch-06-review-package.adoc docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/batch-status-ledger.adoc

第二个提交记录第一个提交的 hash。状态台账的 Batch 06 提交 hash 指向第一个提交。

9.11. 审核规则

审核者必须检查 RDF12 修改只改变 source coordinate consumption，不改变标题投影图对象。审核者必须检查 line origin table 没有进入 RDF12 public API。

9.12. 打回条件

出现以下任一情况，本批不通过：

  • 所有 RDF12 resources 继续使用 entry file relativePath。

  • RDF12 projector 要求调用者传入 internal line origin table。

  • 为修坐标改动 RDF12 标题投影图对象语义。

  • build/adoc 聚合路径出现在 book-entry origin coordinate 中。

  • Downstream coordinate 测试只检查 document-level provenance，不检查 resource-level coordinate。

10. Batch 07：Diagnostics 与 Negative Contracts

10.1. 批次目标

本批集中加固 book-entry construction errors、origin recovery diagnostics、CLI/API error surface 和 negative contracts。

本批不新增目标对象。本批把前序批次已经实现的失败面收敛为稳定、可测试、可审核的 public failure behavior。

10.2. 上游门槛

10.3. 本批上下文闭包

执行者必须阅读：

10.4. 输入事实

10 号书区分 construction errors 和 recovery diagnostics。Construction errors 阻止 logical document 成立。Recovery diagnostics 描述局部 origin recovery 缺口，并阻止假精确坐标输出。

9 号书区分工具错误、tool diagnostic 和下游 lint。Book-entry failure surface 必须保持该分层。

10.5. 文件边界

修改：

  • src/book-entry/**

  • src/parser.ts

  • src/cli.ts

  • src/source-surfaces.ts

  • test/book-entry/book-entry-negative.test.ts

  • test/book-entry/source-coordinate-recovery.test.ts

  • test/cli-error.test.ts

  • docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/batch-07-review-package.adoc

  • docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/batch-status-ledger.adoc

不得修改：

  • RDF12 graph semantics。

  • README 或 CHANGELOG，除非错误消息 public surface 已经需要更新使用说明。

10.6. Construction error 契约

以下情况必须阻止 logical document 成立：

  • Entry file 不存在。

  • Include target 不存在。

  • Include path 越出 documentRoot。

  • Include graph 出现循环。

  • Include directive 使用 unsupported attrlist。

  • Logical line count 与 line origin count 不一致。

  • Line origin 指向 source file table 中不存在的 file。

  • Line origin 的 sourceLine 越出 origin file line table。

这些错误不得被输出为成功 AbundantDocument.toolDiagnostics。

10.7. Recovery diagnostic 契约

以下情况进入 recovery diagnostic：

  • Block span 映射到多个 origin source files。

  • Origin file line table 无法恢复 raw。

  • Parser core 提供的 logical interval 无法映射到 line origin。

Recovery diagnostic 必须阻止假精确坐标输出。无法可靠恢复的 source coordinate 应保持缺失。

10.8. Message 规则

Diagnostic message 描述失败对象和失败原因。Message 不写实现者过程，不写时间状态，不写“暂时不支持”。

正确方向：

include.unsupported-attrlist: include directive uses unsupported attrlist 'tag=main'.

错误方向：

tag include 暂时不支持，后续再实现。

10.9. 测试任务

book-entry-negative.test.ts 必须覆盖：

  • Construction error 不返回 successful AbundantDocument。

  • 每个 construction error 有稳定 code。

  • 每个 construction error message 描述对象事实。

  • Unsupported attrlist message 包含 attrlist surface。

  • Cycle error message 可定位 cycle 对象。

source-coordinate-recovery.test.ts 必须覆盖：

  • Cross-origin block recovery diagnostic。

  • Diagnostic 后不输出假 raw。

  • Diagnostic 后不输出假 source coordinate。

cli-error.test.ts 必须覆盖：

  • Construction errors 返回非零 exit code。

  • 错误消息写入 stderr。

  • stdout 为空。

  • Unknown args 和 unsupported mode 仍按 CLI error 处理。

10.10. 验收标准

  • Construction errors、tool errors、tool diagnostics 和 downstream lint 不混层。

  • 错误 code 稳定并被测试覆盖。

  • Message 使用对象事实语言。

  • 成功 AbundantDocument 不包含 construction error。

  • Recovery diagnostic 不伪造 coordinate。

10.11. 验证命令

pnpm test -- test/book-entry/book-entry-negative.test.ts test/book-entry/source-coordinate-recovery.test.ts test/cli-error.test.ts
pnpm typecheck
pnpm test:coverage

10.12. 提交规则

git add src/book-entry src/parser.ts src/cli.ts src/source-surfaces.ts test/book-entry test/cli-error.test.ts
git commit --only -m "fix: harden book-entry diagnostics" -- src/book-entry src/parser.ts src/cli.ts src/source-surfaces.ts test/book-entry test/cli-error.test.ts
git add docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/batch-07-review-package.adoc docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/batch-status-ledger.adoc
git commit --only -m "docs: record book-entry batch 07 review" -- docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/batch-07-review-package.adoc docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/batch-status-ledger.adoc

第二个提交记录第一个提交的 hash。状态台账的 Batch 07 提交 hash 指向第一个提交。

10.13. 审核规则

审核者必须检查 construction error 没有被降级为 warning。审核者必须检查 diagnostic messages 没有过程语言。审核者必须检查 recovery diagnostic 与 coordinate 缺失同时成立。

10.14. 打回条件

出现以下任一情况，本批不通过：

  • Construction error 返回 successful AbundantDocument。

  • Construction error 被写入 document child。

  • Diagnostic code 未被测试覆盖。

  • Message 使用“暂时”“后续”“目前”作为失败语义。

  • Recovery diagnostic 后仍输出假 raw 或假 coordinate。

  • CLI construction error 写入 stdout。

第五部：最终门禁与关闭

这一部删除迁移期允许失败集合，执行最终验证，更新当前公共材料，并关闭本计划。

11. Batch 08：Final Gates and Closure

11.1. 批次目标

本批删除所有迁移期允许失败标记，锁定 book-entry public contract、coverage evidence、文档表面、书架表面和本计划关闭记录。

本批是最终门禁批次。没有本批审核通过结论，本计划不得声明完成。

11.2. 上游门槛

11.3. 本批上下文闭包

执行者必须阅读：

11.4. 输入事实

最终完成声明必须回到 9 号书 parser 契约、10 号书 book-entry 契约、8 号书 lab 治理规则和实际验证命令。

Review package 只记录实际发生的证据。未运行命令不能写成通过。

11.5. 文件边界

修改：

  • test/book-entry/**

  • test/cli.test.ts

  • test/cli-error.test.ts

  • test/rdf12-projection/**

  • README.md

  • CHANGELOG.md

  • docs/bookshelf/catalog.adoc

  • docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/book.adoc

  • docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/batch-08-review-package.adoc

  • docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/batch-status-ledger.adoc

  • docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/closure-record.adoc

允许修改：

  • src/**，仅限最终测试暴露的契约缺口修复。

11.6. 实施任务

  1. 删除 Batch 00 中登记的全部迁移期 expected fail 标记。

  2. 确认 book-entry contract tests 全部通过。

  3. 确认 single-file regression tests 全部通过。

  4. 确认 CLI 和 library API 行为一致。

  5. 确认 JSON、pretty tree 和 RDF12 downstream 坐标均可回 origin source file。

  6. 运行最终验证命令。

  7. 记录 coverage summary。

  8. 更新 README 中 book-entry public usage。

  9. 更新 CHANGELOG。

  10. 更新书架 catalog，加入本计划书入口。

  11. 基于 关闭记录模板 创建 backmatter/closure-record.adoc。

  12. 更新 book.adoc，使实际关闭记录进入书稿公共表面。

  13. 将 Batch 08 状态台账条目更新为 通过，并写入最终提交 hash 与审核包 xref。

11.7. 最终验证命令

pnpm test
pnpm typecheck
pnpm lint
pnpm build
pnpm pack:check
pnpm smoke:cli
pnpm test:coverage
pnpm --dir docs/bookshelf test
pnpm --dir docs/bookshelf run build

审核包必须列出实际运行的完整命令和结果。命令失败时，必须保留失败输出摘要，并说明是否阻塞完成声明。

11.8. 覆盖率验收

最终覆盖率目标是 90%。Batch 08 review package 必须记录全项目 coverage summary。

新增 src/book-entry/** 模块覆盖率必须不低于 90%。Parser core、origin recovery、CLI mode parsing 和 downstream coordinate projection 的修改必须有测试覆盖证据。

若历史代码基线导致全项目覆盖率低于 90%，本批不得直接声明完成。审核者必须打回，或创建明确补测 work package 并保持本计划未关闭。

11.9. 文档验收

README 只描述当前 public behavior。README 不叙述迁移过程，不把本计划书作为使用者理解当前对象的必要入口。

CHANGELOG 记录 book-entry public mode、origin source coordinate 和相关 CLI/API 行为。CHANGELOG 不替代 9 号书或 10 号书。

书架 catalog 可以列出本计划书。Catalog 不得让本计划书抢占 10 号书的当前规格入口。

11.10. 关闭条件

本计划关闭前必须满足：

  • Batch 00 至 Batch 08 状态均为 通过。

  • 每批提交 hash 均写入状态台账。

  • 每批审核包均可通过 xref 定位。

  • 最终验证命令结果已记录。

  • Coverage evidence 已记录。

  • 未处理对象有明确去向。

  • 需要修订 9 号书或 10 号书的对象已经进入新的 lab object 或明确非目标。

  • backmatter/closure-record.adoc 记录关闭理由、结果去向和后续入口。

  • book.adoc 包含实际关闭记录，关闭记录不只停留在文件系统中。

11.11. 验收标准

  • 没有迁移期 expected fail 标记。

  • Book-entry mode contract tests 全部通过。

  • Single-file mode regression 全部通过。

  • CLI、library API、pretty tree、JSON 和 RDF12 downstream surface 表达同一 origin coordinate 事实。

  • pnpm test:coverage 结果满足覆盖率门槛。

  • README、CHANGELOG 和书架 catalog 与当前行为一致。

  • backmatter/closure-record.adoc 存在并指向最终提交与验证证据。

  • book.adoc 包含实际关闭记录。

11.12. 提交规则

git add src test README.md CHANGELOG.md docs/bookshelf/catalog.adoc
git commit --only -m "feat: finalize book-entry source-mapped parsing" -- src test README.md CHANGELOG.md docs/bookshelf/catalog.adoc
git add docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/book.adoc docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/batch-08-review-package.adoc docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/batch-status-ledger.adoc docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/closure-record.adoc
git commit --only -m "docs: record book-entry plan closure" -- docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/book.adoc docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/batch-08-review-package.adoc docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/batch-status-ledger.adoc docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/backmatter/closure-record.adoc

若最终批次没有源码修改，第一个提交命令应移除 src。若 README、CHANGELOG 或 catalog 未修改，审核者必须确认不修改的依据。第二个提交记录第一个提交的 hash；状态台账的 Batch 08 提交 hash 指向第一个提交。book.adoc、batch-08-review-package.adoc、batch-status-ledger.adoc 和 closure-record.adoc 不得从第二个提交命令中移除。

11.13. 审核规则

审核者必须从 public API、CLI、JSON、pretty tree、RDF12 和 docs bookshelf 六个表面检查同一对象。任一表面仍以 entry file path 替代 origin source file 时，本批不得通过。

11.14. 打回条件

出现以下任一情况，本批不通过：

  • 任一迁移期 expected fail 仍存在。

  • 任一 final gate 命令未运行却写成通过。

  • 覆盖率低于 90%，且没有打回或补测 work package。

  • Book-entry 输出需要下游读取 line origin table 才能回源。

  • README 描述与 CLI/API 行为不一致。

  • 书架 xref 断裂。

  • backmatter/closure-record.adoc 缺少最终验证命令、coverage summary 或未处理对象去向。

  • 实际关闭记录未进入 book.adoc。

Appendix A: 阶段审核包模板

每个批次完成后必须提交审核包。审核包是批次事实记录，不是进度汇报。

A.1. 批次信息

批次编号

Batch NN
批次名称

<批次标题>
提交 hash

<git commit hash>
执行者

<name>
审核者

<name>
审核状态

待审核、打回 或 通过

A.2. 修改文件

src/...
test/...
docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/...

文件列表必须只包含本批提交中的路径。文件边界外修改必须作为受审例外记录。

A.3. 上下文闭包阅读记录

- 目标规格闭包：<已读章节列表>
- 上游 parser 契约闭包：<已读章节列表>
- 当前代码闭包：<已读源码路径>
- 测试闭包：<已读测试路径>
- 治理闭包：<已读计划书或材料体系章节>

本节记录执行者进入批次前实际阅读的上下文闭包。未阅读的上下文闭包不得写成已读。

A.4. 完成范围

本节列出本批已经实现并由测试覆盖的对象事实。

- <对象事实 1>
- <对象事实 2>
- <对象事实 3>

完成范围不得写入“基本完成”“大概完成”“后续完善”等状态词。

A.5. 未处理对象

本节列出本批边界外的对象。边界外对象必须指向后续批次、明确非目标、打回项或新的 lab object。

- <对象>：归属 Batch NN。

未处理对象不得以“后续再说”形式悬空。

A.6. 已运行命令

pnpm test -- ...
pnpm typecheck
pnpm test:coverage

命令必须是实际运行过的命令。不得把计划运行的命令写成本节内容。

A.7. 命令结果

<命令 1>: PASS
<命令 2>: PASS
<命令 3>: FAIL, <失败摘要与阻塞判断>

失败命令必须保留失败输出摘要，并说明失败是否阻塞本批状态转移。

A.8. 覆盖率结果

pnpm test:coverage: PASS
Statements: <percent>
Branches: <percent>
Functions: <percent>
Lines: <percent>
src/book-entry/**: <percent>

未运行 coverage 命令时，本节必须写明未运行原因和阻塞判断。不得把 coverage 目标写成通过事实。

A.9. 规约检查清单

  • 本批目标对象来自 10 号书或 9 号书，不来自当前实现惯性。

  • 本批没有重新定义 10 号书目标对象。

  • 本批没有破坏 single-file mode。

  • 本批没有把 line origin table 变成下游主契约。

  • 本批没有输出假 source coordinate。

  • 本批测试覆盖了正向事实。

  • 本批测试覆盖了必要负向事实。

  • 本批未处理对象有去向。

A.10. 工程质量检查清单

  • 本批没有修改批次边界外文件，或已记录受审例外。

  • 本批没有引入全局打回条件。

  • 本批数据流符合 执行契约。

  • 本批控制流符合 执行契约。

  • 本批新增代码有对应测试。

  • 本批性能相关结构没有无界扫描高频路径。

  • 本批新增模块职责清晰。

  • 本批没有通过 any 或类型逃逸掩盖公共模型冲突。

  • 本批注释只记录代码无法表达的约束或 why。

A.11. 审核结论

结论

通过 或 打回
理由

<对象级理由>
后续动作

<下一批次、返工项、关闭入口或新 lab object>

Appendix B: 批次状态台账

本台账记录批次事实。状态字段只使用 未开始、执行中、待审核、打回 和 通过。

批次 名称 状态 提交 hash 审核记录

Batch 00

基线与迁移护栏

通过

4a8299800c0da0966ea051fc25dccfc7fbae9569

batch-00-review-package.adoc

Batch 01

公共模型与坐标身份

通过

7766995b9263e8cfb8a05d087762033bf66578b3

batch-01-review-package.adoc

Batch 02

Logical Source Builder

通过

9c50aa619299a76f0f272cdcc44b51b101a0c530

batch-02-review-package.adoc

Batch 03

Parser Core 内存入口

通过

ea6c2b9c24bd5239204fd0cc470deedcbab30a5f

batch-03-review-package.adoc

Batch 04

Origin-aware Source Recovery

通过

3367ab40119fa1a65034a8940c2f0bed7dee7f78

batch-04-review-package.adoc

Batch 05

Public API 与 CLI Mode

通过

3ada9168fbe1546c9cf7567c708ee3193189d9f2

batch-05-review-package.adoc

Batch 06

Downstream Coordinate Regression

通过

0aaa1ff598dfeb107e6aed3906f0e6ff8eb11528

batch-06-review-package.adoc

Batch 07

Diagnostics 与 Negative Contracts

通过

ae4ff07a2f6a408a9d150706ff81ba841f9ce6b3

batch-07-review-package.adoc

Batch 08

Final Gates and Closure

通过

d5dd50e33b81f0f7c9ee6895ed90f68c586458d4

batch-08-review-package.adoc

B.1. 台账规则

  • 批次提交产生后，提交 hash 必须写入本表。

  • 审核包路径必须写入审核记录。

  • 批次被打回时，审核记录必须写明打回对象和返工入口。

  • 下一批次开始前，上一批次状态必须为 通过。

  • 台账备注不得记录愿望、估计、口头进度或情绪判断。

Appendix C: 关闭记录模板

关闭记录记录本计划书的结束方式。关闭记录是 lab object 的治理事实，不是当前 parser 对象定义。

实际关闭记录文件为 backmatter/closure-record.adoc。该文件创建后必须由 book.adoc include，进入本计划书公共表面。

C.1. 关闭对象

关闭对象

11-book-entry-source-mapped-logical-document-implementation-plan
目标 body 依据

书稿入口回源逻辑文档规约
上游 parser 依据

asciidoc-abundant-tree 解析器规约
材料体系依据

100_body 与 200_lab：书籍化项目材料体系设计

C.2. 最终提交

最终提交 hash

<git commit hash>
最终审核状态

通过 或 打回
关闭结论

完成、打回、替代、废弃 或 归档

C.3. 最终验证命令

pnpm test
pnpm typecheck
pnpm lint
pnpm build
pnpm pack:check
pnpm smoke:cli
pnpm test:coverage
pnpm --dir docs/bookshelf test
pnpm --dir docs/bookshelf run build

关闭记录必须写入实际运行结果。未运行命令不得写成通过。

C.4. 覆盖率结果

Statements: <percent>
Branches: <percent>
Functions: <percent>
Lines: <percent>
src/book-entry/**: <percent>

覆盖率低于 90% 时，本计划不得关闭为完成状态。

C.5. 已进入当前事实的对象

- <public API/object fact>
- <CLI/object fact>
- <source coordinate/object fact>
- <diagnostic/object fact>

本节只列已经由代码、测试、文档和审核证据共同支撑的对象事实。

C.6. 未处理对象与去向

- <对象>：<非目标、后续 Batch、打回项、新 proposal、相邻人工制品或关闭理由>

未处理对象必须有去向。不得写“后续再说”。

C.7. Body 修订判断

是否需要修订 9 号书

是 或 否
是否需要修订 10 号书

是 或 否
修订入口

<新 lab object 或非目标理由>

实现中发现目标 body 缺口时，关闭记录必须指向新的 lab object。计划书不得在关闭记录中直接改写 body 事实。

C.8. 后续入口

当前对象入口

<current body entry>
治理追溯入口

<archive entry or closed lab entry>
后续治理入口

<active lab entry or none>

Appendix D: 关闭记录

本关闭记录记录 11-book-entry-source-mapped-logical-document-implementation-plan 的 Batch 08 通过与计划关闭事实。

D.1. 关闭对象

关闭对象

11-book-entry-source-mapped-logical-document-implementation-plan
目标 body 依据

书稿入口回源逻辑文档规约
上游 parser 依据

asciidoc-abundant-tree 解析器规约
材料体系依据

100_body 与 200_lab：书籍化项目材料体系设计

D.2. 最终提交

最终提交 hash

d5dd50e33b81f0f7c9ee6895ed90f68c586458d4
最终审核状态

通过
关闭结论

完成

D.3. 最终验证命令

pnpm test
pnpm typecheck
pnpm lint
pnpm build
pnpm pack:check
pnpm smoke:cli
pnpm test:coverage
pnpm --dir docs/bookshelf test
pnpm --dir docs/bookshelf run build

D.4. 最终验证结果

pnpm test:
  PASS
  Test Files 47 passed (47)
  Tests 357 passed (357)

pnpm typecheck:
  PASS
  tsc --noEmit exited 0

pnpm lint:
  PASS
  reviewer rerun: biome check --vcs-use-ignore-file=false . checked 301 files. No fixes applied.

pnpm build:
  PASS
  tsdown built dist/cli.mjs, dist/index.mjs, dist/src-BemgHLtg.mjs, dist/index.d.mts, and dist/cli.d.mts.

pnpm pack:check:
  PASS
  pnpm build, publint, and npm pack --dry-run completed. npm emitted environment-config warnings for unsupported npm config keys; packaging completed.

pnpm smoke:cli:
  PASS
  dist CLI produced rdf12 and rdf12-json-ld output for samples/reference-links.adoc.

pnpm test:coverage:
  PASS
  Test Files 47 passed (47)
  Tests 357 passed (357)
  Global branch coverage is above the configured 90% threshold.

pnpm --dir docs/bookshelf test:
  PASS
  node --test reported 11 pass, 0 fail.

pnpm --dir docs/bookshelf run build:
  PASS
  bookshelf adoc/html build and local resource check completed.

D.5. 覆盖率结果

Statements: 96.33% (1840/1910)
Branches: 90.41% (1255/1388)
Functions: 97.94% (430/439)
Lines: 96.27% (1810/1880)

src/book-entry/**:
Statements: 98.51%
Branches: 96.21%
Functions: 100%
Lines: 98.49%

D.6. 已进入当前事实的对象

- Library API: `parseAbundantTree({ sourcePath })` remains single-file mode; `parseAbundantTree({ sourcePath, mode: "book-entry", documentRoot })` constructs a documentRoot-bounded logical document from supported full-file includes.
- CLI: `--mode book-entry` explicitly selects book-entry input construction; omitted mode and `--mode single-file` preserve single-file input behavior.
- Source coordinate: book-entry `AbundantDocument` section, xref, anchor, target, paragraph, listing, table, and downstream RDF12 resource coordinates use origin `relativePath` facts instead of an aggregate `build/adoc` path.
- Diagnostics: book-entry construction errors block document construction; origin recovery diagnostics prevent fake raw text and fake precise source coordinates.
- Downstream projection: RDF12 projection consumes public `AbundantDocument` source layers and does not require a line origin table parameter.
- Regression state: executable source and tests contain no migration expected-fail markers.

D.7. 未处理对象与去向

- Future semantic expansion beyond supported full-file include directives: outside this implementation plan; requires a new lab object before entering body facts.
- RDF12 vocabulary changes unrelated to source coordinates: outside this implementation plan; governed by RDF12 projection body and its own implementation plan.
- HTML/PDF/EPUB/static-site generation by parser runtime: outside package boundary; README records the current runtime boundary.

D.8. Body 修订判断

是否需要修订 9 号书

否
是否需要修订 10 号书

否
修订入口

无；Batch 08 edits updated README, CHANGELOG, tests, review package, closure record, and plan book surface.

D.9. 后续入口

当前对象入口

书稿入口回源逻辑文档规约
治理追溯入口

批次状态台账 and Batch 08 阶段审核包
后续治理入口

none

Appendix E: 术语表

book-entry mode

从书稿入口构造 source-mapped logical document 的显式输入模式。

entry file

调用者显式传入的书稿入口 source file。

documentRoot

Book-entry mode 中 relativePath 的基准和 include path 的允许边界。

source set

Entry file 通过受支持 include directive 到达的 source files 集合。

logical document

Book-entry pipeline 在内存中构造的 AsciiDoc 文本。Parser 将其作为一份逻辑 source document 解析。

logical line

Logical document 中的 1-based line。

line origin

Logical line 到 origin source file 和 origin source line 的映射。

source file table

参与 logical document 构造的 source files 记录集合。

origin source coordinate

可回源事实在原始 source file 中的位置。

origin raw recovery

从 origin source file line table 恢复 raw slice 的过程。

parser core

共享 official parse、source surface projection、official projection、target merge 和 document assembly 的内部 parser orchestration。

construction error

阻止 logical document 成立的输入构造错误。

recovery diagnostic

描述局部 source coordinate recovery 缺口的 diagnostic。

downstream coordinate regression

下游投影器消费 origin-aware AbundantDocument 后仍输出正确 origin source coordinate 的回归验证。

work package

有明确目标、上下文闭包、文件边界、实施任务、测试任务、验收标准、验证命令、提交规则、审核规则和打回条件的工作单元。

review package

工作包状态转移的审核证据包。

status ledger

批次当前治理状态的台账投影。

closure record

本计划结束方式、最终证据、未处理对象去向和后续入口的记录。

参考坐标