1. 摘要
本书定义 inkrail runtime implementation WBS 与治理计划。它引用 10 号需求契约和 11 号架构基线,将当前 specification package 到 runtime package 的实现活动拆分为受控 work packages,并定义每个工作包的上下文闭包、文件边界、验证命令、提交规则、审核证据、状态台账和关闭条件。
本书是 lab book。它不重新定义 inkrail 的需求对象,不重新定义软件架构,不替代 README、用户指南或 CLI help。它的职责是组织实现兑现过程,使执行者、审核者、协调者和后续维护者能够用同一组治理事实判断实现是否符合既有 body。
版本说明
本书属于 inkrail 设计书架。v0.1.0 定义 runtime 实现前的工作分解、审核结构和关闭规则。
本书记录治理对象。工作包完成证据、审核包、状态台账和关闭记录属于本书公共表面;它们不进入 10 号需求契约或 11 号架构基线的当前对象定义。
前言
本书还引用 08 号 RDF 投影查询工作流 作为内置查询动作的 SPARQL 语义来源,引用 asciidoc-abundant-tree、create-asciidoc-multi-book-workspace、Oxigraph 和 Rootward TypeScript template 作为实现依据和工程参考。
本书使用结构化书写约定。章节 role 标明治理对象身份;xref relation predicate 标明依赖、实现、验证、解锁和关闭关系;named attributes 保存工作包编号、责任域、公共表面和依赖包等附加字段。
第一部:治理表面与当前基线
本部定义 12 号书的治理表面、对象身份、目标 body 依据、当前源码基线、执行规则、全局质量契约、全局打回条件和源文件编排纪律。
2. 治理切片
本章用一个 runtime 工作包展示本书的最小完整治理切片。该切片从 11 号架构对象进入 work package,经由文件边界、测试边界、验证命令、实现提交、审核包和状态台账,形成可关闭的治理事实。
11 号架构对象:Oxigraph adapter 与 Query result model
-> WP-14:Oxigraph Adapter and Query Classifier
-> 文件边界:packages/inkrail/src/adapters/oxigraph.ts 与 adapter contract tests
-> 测试边界:adapter contract tests 与 RDF term fixture
-> 验证命令:pnpm --filter inkrail test
-> 实现提交 hash
-> review package
-> status ledger: WP-14 通过
-> 解锁:WP-15 RDF Term JSON Model 与 WP-16 Raw Query Modes
该切片说明本书的对象不是时间排期。Work package 是 body fact 的治理投影。它必须指出目标依据、上下文闭包、文件边界、验证方式、提交证据、审核结论和下游解锁关系。
本书中的工作包使用稳定 ID、role 和附加字段标明身份:
[#wp-14-oxigraph-adapter-and-query-classifier.work-package, owner=query-runtime, wp=WP-14]
== WP-14:Oxigraph Adapter and Query Classifier
本工作包实现 xref:{book-11}#oxigraph-adapter[11 号书中的 Oxigraph 适配器, rel=implements-architecture]。
本工作包验证 xref:{book-11}#query-result-model[11 号书中的 Query Result 模型, rel=verifies-contract]。
wp 标明工作包编号。owner 标明责任域。.work-package 标明章节身份。rel=implements-architecture 与 rel=verifies-contract 标明当前章节和目标 body 之间的治理边。
执行者读取工作包以确定可修改事实承载物。审核者读取工作包以判断提交是否符合目标。协调者读取状态台账以判断治理状态。后续维护者读取审核包和关闭记录以追溯 runtime 如何进入当前事实。
3. 计划对象身份
本书是 inkrail Runtime 实现工作分解与治理计划书。英文对象名是 inkrail Runtime Implementation WBS and Governance Plan。
本书是 lab book。它治理从当前 specification package 到 runtime package 的受控实现过程。它不重新定义 inkrail 人工制品,不重新定义 11 号架构,不替代用户文档,不记录尚未发生的实现事实。
本书的直接消费者包括执行者、审核者、协调者和后续维护者。执行者使用工作包确定上下文闭包、文件边界和验证命令。审核者使用工作包和审核包连接 Git diff、命令结果和审核结论。协调者使用状态台账判断工作包位置。维护者使用关闭记录追溯实现结果进入当前事实的路径。
本书的完成条件是治理结构成立:每个工作包都有目标依据、文件边界、实施任务、测试任务、验收标准、验证命令、提交规则、审核规则和打回条件;后置区提供审核包模板、初始状态台账和关闭记录模板;catalog 明确本书是实现治理入口。
4. 目标 Body 依据
本书的目标对象来自 current body 与已核验依赖事实。
| 依据 | 路径或对象 | 进入本书的位置 |
|---|---|---|
需求契约 |
项目记忆、标准书架、路径推导、新鲜度、查询模式、输出表面、错误语义、内置动作和测试合同。 |
|
架构基线 |
Public API、module roles、data models、runtime flows、adapter contracts 和 quality gates。 |
|
查询语义来源 |
Built-in action registry 的 SPARQL templates、variables、sorting、source coordinate 和审计事实边界。 |
|
材料治理规则 |
|
Lab object、work package、review package、status ledger、closure record、进入 body 规则和检查清单。 |
Implementation plan 形态 |
|
执行契约、当前源码状态、审核包模板、状态台账和关闭记录模板。 |
工程骨架参考 |
|
ESM package、bin entry、 |
Projection dependency |
|
Book-entry parse、source files、RDF12 TTL、RDF12 JSON-LD 和 projector identity。 |
Workspace initializer dependency |
|
Formal export |
Rootward template 只提供工程形态参考。其 sources、scanners、discover 和 scan 业务语义不得进入 inkrail config、API、tests 或 documentation。
5. 当前源码状态
本章记录本书撰写时的源码基线。该基线描述当前事实,不定义目标对象。
inkrail 项目位于:
micheng-ts/projects/inkrail
本书创建提交为 d56edd7d。该提交新增本书、更新 catalog,并提交写作前上下文资料 docs/plans/资料10.md。提交后的内部 Git 状态为 main…origin/main [ahead 1],工作树无未提交修改。
packages/inkrail 当前只有:
LICENSE
README.md
package.json
packages/inkrail/package.json 当前描述是 inkrail CLI design specification package.。当前 exports 只包含 ./package.json。当前 files 只包含 LICENSE 和 README.md。当前 package 没有 src/、没有 CLI binary、没有 public library API、没有 runtime tests。
根 pnpm check 在本书创建前后均可作为基线验证命令。该命令执行版本检查、docs bookshelf tests、docs build 和 package dry-run。当前 package dry-run 只发布 LICENSE、README.md 和 package.json 三个文件。
本计划的 WP-01 才允许把 packages/inkrail 从 specification package 转为 runtime package shell。任何工作包不得在当前源码状态章节中预写 runtime 已存在的事实。
6. 执行规则
工作包状态使用受控集合:
未开始
|
工作包没有实现提交。 |
执行中
|
工作包存在实现活动,尚未提交审核包。 |
待审核
|
工作包提交 hash 和审核包已经产生。 |
打回
|
审核结论要求补充事实、拆分范围或修正实现。 |
通过
|
审核者确认该工作包满足验收条件。 |
每个工作包开始前必须满足上游门槛。除 WP-00 外,前置工作包必须处于 通过 状态。工作包章节中的 blocks-on 和 unlocks 关系定义启动顺序。
每个工作包必须列出上下文闭包。上下文闭包包含目标 body 章节、架构章节、查询语义来源、当前源码路径、模板或上游依赖路径、测试入口和治理规则。未阅读上下文闭包时,不得开始该工作包实现。
每个工作包必须产生可审查证据。证据包括实现提交 hash、修改文件、已运行命令、命令结果、完成范围、未处理对象、审核结论和状态台账更新。
新文件必须先进入 Git index。提交应在内部 Git 仓库 micheng-ts/projects/inkrail 中执行,并使用 git commit --only -m "…" — <paths> 限定路径,避免混入无关 staged 内容。
状态台账只记录治理事实。愿望、估计、口头进度、情绪判断和未发生动作不得进入台账核心字段。
7. 全局质量契约
所有 runtime 工作包遵守 11 号架构基线定义的 module role。
Domain core 保存纯对象、规则、类型和可确定函数。Domain core 不 import filesystem、process、Oxigraph、commands、io 或上游 parser 内部模块。
Application services 组合 domain core 与 adapters。Services 返回结构化 result,不格式化 CLI 输出,不把 exit code 当作 domain 本体。
Adapters 封装外部依赖和运行环境。asciidoc-abundant-tree、create-asciidoc-multi-book-workspace、Oxigraph、filesystem 和 process runner 的调用只能通过 adapter boundary 进入 runtime。
Commands 映射 CLI arguments 到 service input。Command handler 不拥有 book selection、freshness decision、SPARQL semantics 或 RDF term serialization。
Output projectors 把 structured result 投影为 stdout、stderr、pretty table 或 JSON envelope。Output projectors 不执行查询,不刷新 projection,不读取 project config。
所有新增代码必须有相应测试层。Core tests 锁定纯规则。Service integration tests 锁定 use-case branching。Adapter contract tests 锁定真实依赖能力。CLI surface tests 锁定参数映射、stdout/stderr、exit code 和 --print-query stop point。Package boundary tests 锁定 publish artifact。
TypeScript runtime 必须使用 strict TypeScript、Vitest、tsdown 和 Biome gate。新增注释只记录代码自身无法表达的 why、约束或不变量。
8. 全局打回条件
出现以下任一情况,当前工作包必须打回:
-
CLI command handler 持有 domain rule、freshness rule、SPARQL semantics 或 RDF term serialization。
-
Library consumer 必须构造 CLI args 才能执行项目查询、TTL-only 查询或内置动作。
-
Domain core import filesystem、process、Oxigraph、commands、io 或上游 parser internal modules。
-
Adapter deep import 扩散到 services、core、commands 或 public API。
-
Project mode 使用 stale TTL fallback。
-
TTL-only mode 声称 project freshness。
-
Explicit projection 写
.inkrail/state/。 -
RDF term JSON 把 NamedNode、Literal、BlankNode、DefaultGraph、Variable 或 Quad term 压成字符串。
-
Oxigraph Store 暴露给 public API。
-
Built-in action 改写 08 号查询语义中的 variables、sorting、
OPTIONAL、FILTER NOT EXISTS、GROUP BY、HAVING或 property path。 -
--print-query触发 project resolution、TTL read、refresh state machine 或 SPARQL execution。 -
Review package 把未运行命令写成 PASS。
-
Status ledger 写入愿望、估计、口头进度或未授权目标。
-
工作包修改文件边界外对象且未记录受审例外。
-
README、user guide 或 CLI output 承诺 cross-book union query、payload business interpretation、remote federation 或 stale TTL fallback。
打回记录必须说明打回对象、依据、需要补充的事实和返工入口。
9. 源文件编排与关系词表
本书使用源文件编排号保持结构稳定。Part 目录使用 100-、200-、300-。Chapter 文件在所属 part 内使用 010-、020-、030-。中间插入新主题时使用相邻编号之间的空位。
本书采用以下 role:
| governance-slice |
治理切片。 |
| plan-object |
计划对象身份或目标依据。 |
| source-baseline |
当前源码基线。 |
| execution-rule |
执行规则。 |
| quality-contract |
全局质量契约。 |
| rejection-condition |
全局打回条件。 |
| work-package |
工作包。 |
| review-contract |
审核包契约。 |
| status-ledger |
状态台账。 |
| closure-contract |
关闭记录契约。 |
| boundary-rule |
源文件编排、关系词表或边界规则。 |
本书采用以下 relation predicate:
| depends-on-body |
当前计划对象依赖目标 body 事实。 |
| implements-architecture |
当前工作包实现目标架构对象。 |
| implements-contract |
当前工作包兑现目标需求契约。 |
| sources-query-from |
当前工作包的查询语义来源于目标查询章节。 |
| uses-template-reference |
当前工作包使用工程模板作为形态参考。 |
| uses-adapter-source |
当前工作包使用上游包源码或 package export 作为 adapter 依据。 |
| verifies-contract |
当前测试或门禁验证目标契约。 |
| unlocks |
当前工作包通过后解锁目标工作包。 |
| blocks-on |
当前工作包启动前受目标工作包阻塞。 |
| records-evidence |
审核包或台账记录目标工作包证据。 |
| closes |
关闭记录关闭目标治理对象。 |
本书第一版使用 owner、wp、status、surface 和 package 五个 named attributes。新增字段必须先在本章登记。
第二部:Runtime Package 与 Public API 外壳
本部将 packages/inkrail 从 specification package 转为可构建的 runtime package shell,并建立 public API、result、failure 和 output projection 的基础边界。
10. WP-00:Baseline Gates and Review Infrastructure
- 目标
-
创建本书、登记 catalog、建立审核包模板、状态台账和关闭记录模板。本工作包只修改治理材料,不写 runtime 业务代码。
- 上游门槛
-
10 号需求契约、11 号架构基线、08 号查询语义和材料体系已经阅读。当前
pnpm check通过。当前packages/inkrail仍是 specification package。 - 上下文闭包
-
计划对象身份、目标 Body 依据、当前源码状态、材料体系
chapters/04-lab.adoc、implementation plan 示例的 execution contract、review template、status ledger 和 closure template。 - 文件边界
docs/bookshelf/books/12-inkrail-runtime-implementation-wbs/**
docs/bookshelf/catalog.adoc
- 实施任务
-
创建 12 号书完整源文件结构。第一部定义治理表面、对象身份、目标依据、当前源码基线、执行规则、质量契约、打回条件和 source-order notation。后置区创建 review package template、status ledger、closure record template、glossary、bibliography 和 index。Catalog 把 12 号登记为 implementation governance entry。
- 测试任务
-
运行 docs bookshelf test/build/full check。验证
book.adocinclude 全部存在,catalog xref 可解析,新增书不会破坏 workspace contract。 - 验证命令
pnpm --dir docs/bookshelf test
pnpm --dir docs/bookshelf build
pnpm check
- 提交规则
-
实现提交只包含本工作包文件边界内的源码、测试、文档、fixture 或配置修改。审核证据提交只包含本工作包 review package、状态台账和必要的计划书记录更新。文件边界外修改必须写入审核包的受审例外。
- 审核规则
-
审核者必须核对目标依据、文件边界、实际命令、命令结果、未处理对象去向、全局打回条件和解锁关系。缺少提交 hash、review package 或实际命令结果时,本工作包不得进入
通过。 - 验收标准
-
12 号书可构建。状态台账中 WP-00 至 WP-23 均为
未开始,没有预写未来提交 hash。Catalog 不把 12 号写成 current body。 - 打回条件
-
12 号重新定义 10 号需求或 11 号架构;状态台账写入愿望或估计;closure record template 写成已经完成的事实;catalog 让 12 号抢占 10/11 号入口。
- 解锁关系
-
本工作包通过后解锁 WP-01。
11. WP-01:Runtime Package Shell
- 目标
-
建立 TypeScript runtime package 外壳,使
packages/inkrail具备 ESM library entry、CLI bin entry、build/typecheck/test/lint/pack gates 和基础目录。 - 上游门槛
-
WP-00 通过。当前 package 只有 metadata files。
- 上下文闭包
-
11 号 source tree、package boundary、public exports、CLI consumer 和 build/lint/package gates;Rootward template
package.json、tsconfig.json、tsdown.config.ts、vitest.config.ts、src/bin.ts、src/cli.ts;当前packages/inkrail/package.json。 - 文件边界
packages/inkrail/package.json
packages/inkrail/tsconfig.json
packages/inkrail/tsdown.config.ts
packages/inkrail/vitest.config.ts
packages/inkrail/src/index.ts
packages/inkrail/src/bin.ts
packages/inkrail/src/cli.ts
packages/inkrail/src/core/
packages/inkrail/src/services/
packages/inkrail/src/adapters/
packages/inkrail/src/commands/
packages/inkrail/src/io/
packages/inkrail/src/test-support/
- 实施任务
-
将 package 描述从 specification package 转为 runtime package shell。添加
exports "."与./package.json。添加bin指向 built CLI entry。添加files: ["dist", "README.md", "LICENSE"]。引入 tsdown、Vitest、TypeScript、Biome 和 runtime dependencies 的最小 manifest。创建 source tree skeleton。bin.ts只调用runCli(process.argv.slice(2), { cwd })并写 stdout/stderr/exitCode。 - 测试任务
-
添加最小 smoke test,证明 public entry 可 import,
runCli([])能返回 usage failure,build 输出 index/bin entry。Package dry-run 不包含src/、tests、coverage、tmp 或 docs build。 - 验证命令
pnpm --filter inkrail typecheck
pnpm --filter inkrail test
pnpm --filter inkrail lint
pnpm --filter inkrail build
pnpm --filter inkrail pack:check
pnpm check
- 提交规则
-
实现提交只包含本工作包文件边界内的源码、测试、文档、fixture 或配置修改。审核证据提交只包含本工作包 review package、状态台账和必要的计划书记录更新。文件边界外修改必须写入审核包的受审例外。
- 审核规则
-
审核者必须核对目标依据、文件边界、实际命令、命令结果、未处理对象去向、全局打回条件和解锁关系。缺少提交 hash、review package 或实际命令结果时,本工作包不得进入
通过。 - 验收标准
-
Runtime shell 可构建、可测试、可 dry-run pack。Public exports 不再只有
./package.json。CLI bin 不包含业务逻辑。 - 打回条件
-
Rootward
sources/scanners/discover/scan语义残留;package exports 不含".";bin 直接实现业务规则;pack dry-run 发布 forbidden files。 - 解锁关系
12. WP-02:Result, Failure, and Output Foundation
- 目标
-
建立 Inkrail 命名的 result、failure、diagnostic 和 CLI output projection 基础。CLI exit code 是投影,不是 domain 本体。
- 上游门槛
-
WP-01 通过。
- 上下文闭包
-
10 号错误语义 与 输出表面;11 号 query result model、output projection flow 和 output test contract;Rootward
src/core/errors.ts、src/core/result.ts、src/io/output.ts。 - 文件边界
packages/inkrail/src/core/errors.ts
packages/inkrail/src/core/result.ts
packages/inkrail/src/core/diagnostics.ts
packages/inkrail/src/io/json-output.ts
packages/inkrail/src/io/pretty-output.ts
packages/inkrail/src/io/diagnostics.ts
packages/inkrail/src/cli.ts
packages/inkrail/src/**/*.{test,spec}.ts
- 实施任务
-
定义
InkrailErrorCode、InkrailFailure、InkrailDiagnostic、InkrailResult<T>。覆盖 10 号错误码。定义 CLI projection 中的 exit code mapping。实现 JSON success stdout、JSON failure stderr、pretty failure stderr 和 stack trace exclusion。 - 测试任务
-
验证 success JSON 写 stdout,failure JSON 写 stderr,pretty failure 包含 stable error code 和 details,usage failure 不输出 stack trace。测试 domain failure 进入 CLI projection 时不丢失 code/details。
- 验证命令
pnpm --filter inkrail test
pnpm --filter inkrail typecheck
pnpm --filter inkrail lint
- 提交规则
-
实现提交只包含本工作包文件边界内的源码、测试、文档、fixture 或配置修改。审核证据提交只包含本工作包 review package、状态台账和必要的计划书记录更新。文件边界外修改必须写入审核包的受审例外。
- 审核规则
-
审核者必须核对目标依据、文件边界、实际命令、命令结果、未处理对象去向、全局打回条件和解锁关系。缺少提交 hash、review package 或实际命令结果时,本工作包不得进入
通过。 - 验收标准
-
Public failure object 不使用
CliError作为 domain 类型名。Exit code 只存在于 CLI projection。所有 10 号错误码有稳定 code surface。 - 打回条件
-
Failure object 命名为 CLI-only domain;failure JSON 写 stdout;pretty failure 输出 stack trace;error code 覆盖不全;output projector 执行 query 或 project loading。
- 解锁关系
-
本工作包通过后解锁 WP-03、WP-04 和后续 service failure propagation tests。
13. WP-03:Public API Export Surface
- 目标
-
建立
src/index.ts的 public API surface,使 library consumer 能直接消费 project、mutation、projection、query、model 和 action registry 类型。 - 上游门槛
- 上下文闭包
-
11 号 public exports 与 consumer roles;10 号 query modes 与 initialization contract;Rootward
src/index.ts的局限性。 - 文件边界
packages/inkrail/src/index.ts
packages/inkrail/src/core/**
packages/inkrail/src/services/**
packages/inkrail/src/cli.ts
packages/inkrail/src/**/*.{test,spec}.ts
- 实施任务
-
导出 project API、mutation API、projection API、query API、model API 和 built-in action registry 类型。
runCli可以导出为 CLI consumer 表面,但不得成为 library consumer 的唯一入口。禁止导出 commands、io internals、test-support、Oxigraph Store 和 workspace initializer import path。 - 测试任务
-
使用 import tests 锁定 export names。验证 library consumer 可以 import result/error/config/book/path/query/RDF term/action types,而不构造 CLI args。
- 验证命令
pnpm --filter inkrail test
pnpm --filter inkrail build
pnpm --filter inkrail pack:check
- 提交规则
-
实现提交只包含本工作包文件边界内的源码、测试、文档、fixture 或配置修改。审核证据提交只包含本工作包 review package、状态台账和必要的计划书记录更新。文件边界外修改必须写入审核包的受审例外。
- 审核规则
-
审核者必须核对目标依据、文件边界、实际命令、命令结果、未处理对象去向、全局打回条件和解锁关系。缺少提交 hash、review package 或实际命令结果时,本工作包不得进入
通过。 - 验收标准
-
Package export
"."解析到 built index。Type declarations 包含 public API names。Public surface 与 11 号 appendix A 一致。 - 打回条件
-
Public API 只导出
runCli;commands/io/test-support 公开导出;Oxigraph Store 暴露;adapter deep import path 进入 public API。 - 解锁关系
第三部:项目记忆、Profile 与初始化
本部实现项目记忆、profile、路径推导、项目配置 mutation、标准书架 initializer adapter 和书架本地 runtime dispatch。它把 10 号第二部契约落入 11 号 project-memory 架构对象。
14. WP-04:Config Schema and Project Context
- 目标
-
实现
.inkrail/config.tomlraw schema、normalized config、parse/serialize、project discovery 和 project context model。 - 上游门槛
- 上下文闭包
-
10 号 project config model;11 号 config model、project/book model、path model 和 application services;Rootward config/project discovery tests 只提供测试形态参考。
- 文件边界
packages/inkrail/src/core/config.ts
packages/inkrail/src/core/project.ts
packages/inkrail/src/core/paths.ts
packages/inkrail/src/adapters/toml.ts
packages/inkrail/src/services/load-project.ts
packages/inkrail/src/**/*.{test,spec}.ts
- 实施任务
-
定义 raw TOML shape 与 normalized config。实现 CLI identifier validation、path validation、standard/custom profile validation、default book validation。实现 explicit project 与 cwd-upward discovery。实现 config parse failure、schema failure 和 project not found failure。
- 测试任务
-
覆盖非法 id、重复 bookshelf id、重复 book id、绝对路径、反斜杠、
..、default_book 指向缺失 book、standard profile 声明派生字段、custom profile 缺必填字段、TOML parse failure、explicit project missing config、cwd upward missing project。 - 验证命令
pnpm --filter inkrail test
pnpm --filter inkrail typecheck
- 提交规则
-
实现提交只包含本工作包文件边界内的源码、测试、文档、fixture 或配置修改。审核证据提交只包含本工作包 review package、状态台账和必要的计划书记录更新。文件边界外修改必须写入审核包的受审例外。
- 审核规则
-
审核者必须核对目标依据、文件边界、实际命令、命令结果、未处理对象去向、全局打回条件和解锁关系。缺少提交 hash、review package 或实际命令结果时,本工作包不得进入
通过。 - 验收标准
-
Config model 与 10/11 号一致。Path validation 是 core rule。Project discovery 不泄漏到 CLI command handler。
- 打回条件
-
Config 保留 Rootward
sources/scanners;custom profile 猜测标准路径;standard profile 允许手写派生字段;路径用 ad hoc string 拼接绕过 path model。 - 解锁关系
15. WP-05:Book Selection and Path Derivation
- 目标
-
实现 target book selection 与 standard/custom profile path derivation。
- 上游门槛
-
WP-04 通过。
- 上下文闭包
-
10 号 book path derivation 与 query modes 中的 book selection;11 号 path model 与 project/book model。
- 文件边界
packages/inkrail/src/core/books.ts
packages/inkrail/src/core/profiles.ts
packages/inkrail/src/core/paths.ts
packages/inkrail/src/services/load-project.ts
packages/inkrail/src/**/*.{test,spec}.ts
- 实施任务
-
实现
selectTargetBook,优先级为 explicit book、default_book、single book fallback。实现deriveBookPaths,标准 profile 派生 book entry、documentRoot、RDF12 TTL、RDF12 JSON-LD、HTML、expanded ADOC 和 watch globs。Custom profile 只使用 config 声明路径。 - 测试任务
-
覆盖 explicit book override、default book、single book fallback、multi book
BOOK_REQUIRED、未知 bookBOOK_NOT_FOUND。验证 standard profile 的所有派生路径和 display/operation path 分离。 - 验证命令
pnpm --filter inkrail test
pnpm --filter inkrail typecheck
- 提交规则
-
实现提交只包含本工作包文件边界内的源码、测试、文档、fixture 或配置修改。审核证据提交只包含本工作包 review package、状态台账和必要的计划书记录更新。文件边界外修改必须写入审核包的受审例外。
- 审核规则
-
审核者必须核对目标依据、文件边界、实际命令、命令结果、未处理对象去向、全局打回条件和解锁关系。缺少提交 hash、review package 或实际命令结果时,本工作包不得进入
通过。 - 验收标准
-
Book selection 是 domain rule。Watch globs 不等同 source set。HTML 和 expanded ADOC 不进入 query freshness。
- 打回条件
-
Book selection 写在 CLI command handler;watch globs 被当作 source set;custom profile 被强行推导;standard path 派生遗漏 RDF12 JSON-LD 或 expanded ADOC。
- 解锁关系
16. WP-06:Project Memory Mutation Services
- 目标
-
实现项目记忆 mutation services 与基础命令:
init、bookshelves add、books add、books use、books list、config print、status和doctor。 - 上游门槛
- 上下文闭包
-
10 号 initialization contract 与 project config model;11 号 application services、config model 和 documentation quality;Rootward init/status/config print tests 只提供 fixture 形态参考。
- 文件边界
packages/inkrail/src/services/init-project.ts
packages/inkrail/src/services/load-project.ts
packages/inkrail/src/commands/init.ts
packages/inkrail/src/commands/bookshelves.ts
packages/inkrail/src/commands/books.ts
packages/inkrail/src/commands/config-print.ts
packages/inkrail/src/commands/status.ts
packages/inkrail/src/commands/doctor.ts
packages/inkrail/src/**/*.{test,spec}.ts
- 实施任务
-
initInkrailProject创建.inkrail/config.toml、.inkrail/cache/、.inkrail/state/和必要 ignore files。Registration services 修改 config 并保持 serializer roundtrip。Status/doctor 返回 project memory 与 diagnostics,不定义新的需求对象。 - 测试任务
-
覆盖初次 init、重复 init、force、register bookshelf、register book、set default book、list books、config print roundtrip、status、doctor diagnostics。验证 init 不创建书架、不自动登记样本书。
- 验证命令
pnpm --filter inkrail test
pnpm --filter inkrail typecheck
- 提交规则
-
实现提交只包含本工作包文件边界内的源码、测试、文档、fixture 或配置修改。审核证据提交只包含本工作包 review package、状态台账和必要的计划书记录更新。文件边界外修改必须写入审核包的受审例外。
- 审核规则
-
审核者必须核对目标依据、文件边界、实际命令、命令结果、未处理对象去向、全局打回条件和解锁关系。缺少提交 hash、review package 或实际命令结果时,本工作包不得进入
通过。 - 验收标准
-
Project memory mutation 由 services 承担,CLI 只映射参数。Config serializer 不丢字段。Doctor diagnostics 结构化返回。
- 打回条件
-
init创建 bookshelf;init自动登记样本书;serializer 丢失已支持但未知的配置字段;doctor 输出教学文本或扩大公共契约。 - 解锁关系
17. WP-07:Workspace Initializer Adapter and Bookshelf Init
- 目标
-
集成
create-asciidoc-multi-book-workspace@0.1.5formal exportinitWorkspace,实现inkrail bookshelf init与可选--register。 - 上游门槛
- 上下文闭包
-
10 号 standard bookshelf template 与 initialization contract;11 号 workspace initializer adapter 与 bookshelf initialization flow;上游
micheng-ts/projects/asciidoc-multi-book-workspace/package.json、src/index.ts、src/init-workspace.ts。 - 文件边界
packages/inkrail/src/adapters/workspace-initializer.ts
packages/inkrail/src/services/bookshelf-init.ts
packages/inkrail/src/commands/bookshelf.ts
packages/inkrail/src/**/*.{test,spec}.ts
- 实施任务
-
Adapter 使用 formal export
initWorkspace。Service 处理 target path、force、register id、project config update 和 upstream error mapping。--register只写,profile 为inkrail-asciidoc-multi-book,root 为 project-relative path。 - 测试任务
-
覆盖 target missing、empty dir、target file、non-empty without force、force preservation、生成
catalog.adoc、books/、shared/、package.json、.gitignore、tools/adoc-books.mjs、不包含 maintainer-only files、--register写 bookshelves、样本书不登记。 - 验证命令
pnpm --filter inkrail test
pnpm --filter inkrail typecheck
- 提交规则
-
实现提交只包含本工作包文件边界内的源码、测试、文档、fixture 或配置修改。审核证据提交只包含本工作包 review package、状态台账和必要的计划书记录更新。文件边界外修改必须写入审核包的受审例外。
- 审核规则
-
审核者必须核对目标依据、文件边界、实际命令、命令结果、未处理对象去向、全局打回条件和解锁关系。缺少提交 hash、review package 或实际命令结果时,本工作包不得进入
通过。 - 验收标准
-
上游 initializer import 只存在于 adapter。Inkrail 不 vendor 标准模板。Register 行为不污染 books list。
- 打回条件
-
使用上游 deep import;复制标准模板到
inkrailcore;force 删除未知用户文件;sample books 自动进入。 - 解锁关系
-
本工作包通过后为 WP-20 提供标准书架初始化前置。
18. WP-08:Bookshelf Runtime Dispatch
- 目标
-
实现已登记 standard bookshelf 的 local
build、check和cleanscript 调度。 - 上游门槛
- 上下文闭包
-
10 号 bookshelf build dispatch;11 号 bookshelf runtime dispatch flow 与 filesystem/process adapters;standard workspace package scripts。
- 文件边界
packages/inkrail/src/adapters/process-runner.ts
packages/inkrail/src/services/bookshelf-runtime.ts
packages/inkrail/src/commands/bookshelf.ts
packages/inkrail/src/**/*.{test,spec}.ts
- 实施任务
-
Load project,resolve bookshelf,require standard profile,validate package script,validate
tools/adoc-books.mjs,run script in bookshelf root,forward stdout/stderr/status into structured result。 - 测试任务
-
覆盖 registered standard profile dispatch、未知 bookshelf、custom profile unsupported、missing package script、missing runtime script、non-zero status、stdout/stderr forwarding、dispatch 不写 RDF state、project query 不隐式 build/check/clean。
- 验证命令
pnpm --filter inkrail test
pnpm --filter inkrail typecheck
- 提交规则
-
实现提交只包含本工作包文件边界内的源码、测试、文档、fixture 或配置修改。审核证据提交只包含本工作包 review package、状态台账和必要的计划书记录更新。文件边界外修改必须写入审核包的受审例外。
- 审核规则
-
审核者必须核对目标依据、文件边界、实际命令、命令结果、未处理对象去向、全局打回条件和解锁关系。缺少提交 hash、review package 或实际命令结果时,本工作包不得进入
通过。 - 验收标准
-
Dispatch 只服务 standard profile。Process runner 是 adapter。Dispatch result 保留 stdout/stderr/status。RDF projection state 不受影响。
- 打回条件
-
Dispatch 写
.inkrail/state;query 隐式执行 bookshelf build;custom profile 被强行调度;non-zero local runtime status 被吞掉。 - 解锁关系
-
本工作包通过后,书架 runtime dispatch 成为 WP-20 的可用前置;该工作包不解锁 projection runtime 工作包。
第四部:投影、状态与刷新 Runtime
本部实现 projection runtime 的核心对象:asciidoc-abundant-tree adapter capability lock、source set fingerprint、projection fingerprint、state store、explicit projection service 和 project refresh state machine。
19. WP-09:Abundant-tree Adapter Capability Lock
- 目标
-
建立
asciidoc-abundant-tree@0.1.12adapter,并用 contract tests 锁定 book-entry parse、source files、RDF12 TTL 和 RDF12 JSON-LD 能力。 - 上游门槛
-
WP-05 通过。
- 上下文闭包
-
11 号 abundant-tree adapter、explicit projection flow 和 version/capability locks;上游
src/index.tspublic exports;08 号 build/projection workflow。 - 文件边界
packages/inkrail/src/adapters/abundant-tree.ts
packages/inkrail/src/services/projection.ts
packages/inkrail/src/**/*.{test,spec}.ts
packages/inkrail/test/fixtures/**
- 实施任务
-
Adapter 只使用
parseAbundantTree和rdf12public API。Project mode projection 使用mode: "book-entry"和 documentRoot。Explicit single-file projection 保持 single-file semantics。Adapter 返回 source files、TTL、JSON-LD、projector identity 和 structured failure。 - 测试任务
-
使用真实上游依赖验证 book-entry source files、shared attributes inclusion、TTL output、JSON-LD output、source coordinate preservation、single-file mode 不展开 include。
- 验证命令
pnpm --filter inkrail test
pnpm --filter inkrail typecheck
- 提交规则
-
实现提交只包含本工作包文件边界内的源码、测试、文档、fixture 或配置修改。审核证据提交只包含本工作包 review package、状态台账和必要的计划书记录更新。文件边界外修改必须写入审核包的受审例外。
- 审核规则
-
审核者必须核对目标依据、文件边界、实际命令、命令结果、未处理对象去向、全局打回条件和解锁关系。缺少提交 hash、review package 或实际命令结果时,本工作包不得进入
通过。 - 验收标准
-
Adapter capability 由 fixture test 锁定。上游 internals 不进入 Inkrail。Parser、include resolver、payload interpreter 不在 Inkrail 中实现。
- 打回条件
-
Import 上游内部 source modules;在 Inkrail 复制 parser/include resolver;adapter 解释 payload raw;single-file mode 展开 include。
- 解锁关系
20. WP-10:Source Set and Projection Fingerprints
- 目标
-
实现 source file fingerprint、source set fingerprint 和 projection fingerprint。
- 上游门槛
-
WP-09 通过。
- 上下文闭包
-
10 号 fingerprint model;11 号 source-set fingerprint、projection fingerprint 和 path model;adapter source files contract。
- 文件边界
packages/inkrail/src/core/fingerprint.ts
packages/inkrail/src/core/freshness.ts
packages/inkrail/src/services/projection.ts
packages/inkrail/src/**/*.{test,spec}.ts
- 实施任务
-
Source file fingerprint 包含 documentRoot-relative path、size、mtimeMs 和 contentHash。Source set hash 按 relativePath 稳定排序。Projection fingerprint 包含 format、outputPath、outputHash、projectedFromSourceSetHash、documentRoot、projector identity 和 options。
- 测试任务
-
覆盖 traversal order 不影响 hash、content change 改变 hash、shared attributes 进入 source set、mtimeMs 只是快速线索、outputHash 改变、documentRoot/options/projector mismatch 触发 stale decision。
- 验证命令
pnpm --filter inkrail test
pnpm --filter inkrail typecheck
- 提交规则
-
实现提交只包含本工作包文件边界内的源码、测试、文档、fixture 或配置修改。审核证据提交只包含本工作包 review package、状态台账和必要的计划书记录更新。文件边界外修改必须写入审核包的受审例外。
- 审核规则
-
审核者必须核对目标依据、文件边界、实际命令、命令结果、未处理对象去向、全局打回条件和解锁关系。缺少提交 hash、review package 或实际命令结果时,本工作包不得进入
通过。 - 验收标准
-
Fingerprint 输入序列稳定。Watch globs 不定义 source set membership。Projection fingerprint 不替代 artifact existence check。
- 打回条件
-
只用 mtime 判断 freshness;hash 受 filesystem/list traversal order 影响;projection fingerprint 不含 projector identity;shared attributes 被排除。
- 解锁关系
-
本工作包通过后解锁 WP-11。
21. WP-11:State Store and Refresh Decision
- 目标
-
实现
.inkrail/state/books/<book-id>/rdf12.json与rdf12-json-ld.jsonstate records,以及 refresh decision。 - 上游门槛
-
WP-10 通过。
- 上下文闭包
-
10 号 refresh state machine;11 号 state store、refresh state machine flow 和 projection fingerprint。
- 文件边界
packages/inkrail/src/core/freshness.ts
packages/inkrail/src/services/refresh.ts
packages/inkrail/src/services/projection.ts
packages/inkrail/src/adapters/filesystem.ts
packages/inkrail/src/**/*.{test,spec}.ts
- 实施任务
-
读取、验证、写入 projection state record。State record 包含 schemaVersion、book identity、sourceSet、projection 和 updatedAt。Refresh decision 检查 state missing、schema unsupported、parse failed、artifact missing、hash mismatch、documentRoot mismatch、options mismatch、projector mismatch。
- 测试任务
-
覆盖 state missing、parse failed、unsupported schema、artifact missing、hash mismatch、projector mismatch、successful state write ordering、query failure 不回滚 projection state。
- 验证命令
pnpm --filter inkrail test
pnpm --filter inkrail typecheck
- 提交规则
-
实现提交只包含本工作包文件边界内的源码、测试、文档、fixture 或配置修改。审核证据提交只包含本工作包 review package、状态台账和必要的计划书记录更新。文件边界外修改必须写入审核包的受审例外。
- 审核规则
-
审核者必须核对目标依据、文件边界、实际命令、命令结果、未处理对象去向、全局打回条件和解锁关系。缺少提交 hash、review package 或实际命令结果时,本工作包不得进入
通过。 - 验收标准
-
State file 不替代 projection artifact。TTL 与 JSON-LD state 独立。State write 在 artifact 写入和 outputHash 计算后发生。
- 打回条件
-
State 替代 artifact;RDF12 和 JSON-LD 共用 state;query failure 回滚已成功 projection;book identity 与 config 唯一性冲突未处理。
- 解锁关系
-
本工作包通过后解锁 WP-13。
22. WP-12:Explicit Projection Service
- 目标
-
实现
projectAdocservice 和 CLIinkrail project,支持rdf12与rdf12-json-ld输出。 - 上游门槛
-
WP-09 通过。
- 上下文闭包
-
10 号 RDF12/JSON-LD projections;11 号 explicit projection flow 与 abundant-tree adapter。
- 文件边界
packages/inkrail/src/services/projection.ts
packages/inkrail/src/commands/project.ts
packages/inkrail/src/adapters/abundant-tree.ts
packages/inkrail/src/**/*.{test,spec}.ts
- 实施任务
-
Explicit projection 默认 single-file semantics。调用者可显式传
--mode book-entry --document-root。Service 生成指定 format 并写 out path。该 service 不读取 project memory,不写.inkrail/state/,不登记 book。 - 测试任务
-
覆盖 single-file default 不展开 include、book-entry mode 要求 documentRoot、rdf12 output、jsonld output、out path parent creation、不写 state、不读取 config。
- 验证命令
pnpm --filter inkrail test
pnpm --filter inkrail typecheck
- 提交规则
-
实现提交只包含本工作包文件边界内的源码、测试、文档、fixture 或配置修改。审核证据提交只包含本工作包 review package、状态台账和必要的计划书记录更新。文件边界外修改必须写入审核包的受审例外。
- 审核规则
-
审核者必须核对目标依据、文件边界、实际命令、命令结果、未处理对象去向、全局打回条件和解锁关系。缺少提交 hash、review package 或实际命令结果时,本工作包不得进入
通过。 - 验收标准
-
Explicit projection 是无项目状态的投影工具。Book-entry mode 是显式输入语义。State store 不受 explicit projection 影响。
- 打回条件
-
Explicit projection 写
.inkrail/state;根据:doctype: book隐式切换模式;未传 documentRoot 却执行 book-entry;读取 project config。 - 解锁关系
-
本工作包通过后,explicit projection CLI 与 service surface 可供 WP-21 用户文档同步引用;project mode refresh 不依赖本工作包。
23. WP-13:Project Refresh State Machine
- 目标
-
实现 project mode RDF12 refresh state machine 和 explicit
refreshcommand。 - 上游门槛
- 上下文闭包
-
10 号 refresh state machine;11 号 refresh state machine flow、project mode query flow 和 state store。
- 文件边界
packages/inkrail/src/services/refresh.ts
packages/inkrail/src/services/projection.ts
packages/inkrail/src/commands/refresh.ts
packages/inkrail/src/**/*.{test,spec}.ts
- 实施任务
-
按项目上下文、config、target book、path derivation、source set、fingerprint、state、artifact、freshness decision、projection、state write 的顺序执行。
refresh --projection rdf12/jsonld/all分别刷新对应 format。Project mode query 只要求 RDF12 freshness。 - 测试任务
-
覆盖 book entry missing、source set failed、TTL missing、stale TTL、documentRoot/options/projector mismatch、projection failed、JSON-LD 独立 refresh、query only requires RDF12 freshness 和禁止 stale TTL fallback。
- 验证命令
pnpm --filter inkrail test
pnpm --filter inkrail typecheck
- 提交规则
-
实现提交只包含本工作包文件边界内的源码、测试、文档、fixture 或配置修改。审核证据提交只包含本工作包 review package、状态台账和必要的计划书记录更新。文件边界外修改必须写入审核包的受审例外。
- 审核规则
-
审核者必须核对目标依据、文件边界、实际命令、命令结果、未处理对象去向、全局打回条件和解锁关系。缺少提交 hash、review package 或实际命令结果时,本工作包不得进入
通过。 - 验收标准
-
Project mode 已知 stale 时只能刷新或失败。Refresh events 结构化返回。JSON-LD freshness 不阻塞 query。
- 打回条件
-
刷新失败后旧 TTL 继续 query;JSON-LD freshness 成为 query 前置;查询失败回滚成功 projection;状态机步骤被 command handler 持有。
- 解锁关系
第五部:查询、输出与内置动作
本部实现 Oxigraph query adapter、RDF term JSON、raw query modes、output projection、built-in action registry 和 CLI command mapping。
24. WP-14:Oxigraph Adapter and Query Classifier
- 目标
-
封装 Oxigraph Store,加载 TTL,执行 SPARQL,并把 union return type 分类为 Inkrail query result model。
- 上游门槛
-
WP-13 通过。
- 上下文闭包
-
10 号 query engine;11 号 Oxigraph adapter、query result model 和 version/capability locks;Oxigraph binding types。
- 文件边界
packages/inkrail/src/adapters/oxigraph.ts
packages/inkrail/src/services/query.ts
packages/inkrail/src/core/query-result.ts
packages/inkrail/src/**/*.{test,spec}.ts
- 实施任务
-
Adapter 创建 in-memory store,加载 Turtle,执行 SELECT/ASK/CONSTRUCT/DESCRIBE/property path。Classifier 把 boolean、Map rows 和 Quad[] 转换为 Inkrail result model。默认不请求 string results_format。
- 测试任务
-
覆盖 TTL load success/failure、SELECT rows、ASK boolean、CONSTRUCT/DESCRIBE quads、property path、RDF 1.2 / RDF-star quad term fixture、SPARQL failure。
- 验证命令
pnpm --filter inkrail test
pnpm --filter inkrail typecheck
- 提交规则
-
实现提交只包含本工作包文件边界内的源码、测试、文档、fixture 或配置修改。审核证据提交只包含本工作包 review package、状态台账和必要的计划书记录更新。文件边界外修改必须写入审核包的受审例外。
- 审核规则
-
审核者必须核对目标依据、文件边界、实际命令、命令结果、未处理对象去向、全局打回条件和解锁关系。缺少提交 hash、review package 或实际命令结果时,本工作包不得进入
通过。 - 验收标准
-
Public API 不暴露 Oxigraph Store。Query classifier 与 11 号模型一致。TTL load failure 映射
TTL_LOAD_FAILED,SPARQL failure 映射QUERY_FAILED。 - 打回条件
-
Store 暴露 public API;string results 成为默认;adapter 定义 built-in action;quad term 被丢失或字符串化。
- 解锁关系
25. WP-15:RDF Term JSON Model
- 目标
-
实现 public API 和 CLI JSON 共用的 RDF term JSON serializer。
- 上游门槛
-
WP-14 通过。
- 上下文闭包
-
10 号 output surfaces 中的 RDF term 规则;11 号 RDF term JSON、query result model 和 output test contract。
- 文件边界
packages/inkrail/src/core/rdf-terms.ts
packages/inkrail/src/adapters/oxigraph.ts
packages/inkrail/src/**/*.{test,spec}.ts
- 实施任务
-
Serialize NamedNode、Literal、BlankNode、DefaultGraph、Variable 和 Quad term。Literal 保留 datatype、language 和 direction 字段。Quad term 保留 subject、predicate、object、graph。未识别的 term shape 返回 structured failure。
- 测试任务
-
覆盖所有 supported term classes、nested quad term、literal language/datatype、未识别 term failure、pretty output 不改变 JSON contract。
- 验证命令
pnpm --filter inkrail test
pnpm --filter inkrail typecheck
- 提交规则
-
实现提交只包含本工作包文件边界内的源码、测试、文档、fixture 或配置修改。审核证据提交只包含本工作包 review package、状态台账和必要的计划书记录更新。文件边界外修改必须写入审核包的受审例外。
- 审核规则
-
审核者必须核对目标依据、文件边界、实际命令、命令结果、未处理对象去向、全局打回条件和解锁关系。缺少提交 hash、review package 或实际命令结果时,本工作包不得进入
通过。 - 验收标准
-
JSON output 保留 RDF/JS-compatible structure。Pretty renderer 可以短文本化,但机器 JSON 不丢结构。
- 打回条件
-
RDF term 压成 string;literal 丢 datatype/language;quad term 拆坏;未识别 term 输出部分结果。
- 解锁关系
-
本工作包通过后解锁 WP-17。
26. WP-16:Raw Query Modes
- 目标
-
实现 project mode raw query 与 TTL-only raw query。
- 上游门槛
- 上下文闭包
-
10 号 query modes;11 号 project mode query flow、TTL-only query flow 和 query result model。
- 文件边界
packages/inkrail/src/services/query.ts
packages/inkrail/src/commands/query.ts
packages/inkrail/src/**/*.{test,spec}.ts
- 实施任务
-
Project mode 支持 query argument、
--file和--stdin,并在 query 前执行 RDF12 refresh state machine。TTL-only mode 支持--ttl加 query argument、file 或 stdin,不查 project,不 refresh,不 state,不声明 freshness。 - 测试任务
-
覆盖三种 query input surface、query read failure、project mode query 前的 refresh、TTL-only mode 不查找 project、TTL-only failure surfaces 和 mode-specific envelope。
- 验证命令
pnpm --filter inkrail test
pnpm --filter inkrail typecheck
- 提交规则
-
实现提交只包含本工作包文件边界内的源码、测试、文档、fixture 或配置修改。审核证据提交只包含本工作包 review package、状态台账和必要的计划书记录更新。文件边界外修改必须写入审核包的受审例外。
- 审核规则
-
审核者必须核对目标依据、文件边界、实际命令、命令结果、未处理对象去向、全局打回条件和解锁关系。缺少提交 hash、review package 或实际命令结果时,本工作包不得进入
通过。 - 验收标准
-
Project result 包含 book/projection/freshness。TTL-only result 不包含 book/freshness。Query input priority 和错误码稳定。
- 打回条件
-
TTL-only 查找
.inkrail/config;project mode 不执行 refresh;raw query text handling 由 CLI command handler 即兴处理;TTL-only 声称 freshness。 - 解锁关系
-
本工作包通过后解锁 WP-18。
27. WP-17:Output Projection Surface
- 目标
-
实现 CLI pretty、JSON、stdout/stderr 和 exit code projection。
- 上游门槛
- 上下文闭包
-
10 号 output surfaces;11 号 output projection flow 与 output test contract;Rootward
io/output.ts只提供输出投影组织形态参考。 - 文件边界
packages/inkrail/src/io/json-output.ts
packages/inkrail/src/io/pretty-output.ts
packages/inkrail/src/io/table.ts
packages/inkrail/src/io/diagnostics.ts
packages/inkrail/src/cli.ts
packages/inkrail/src/**/*.{test,spec}.ts
- 实施任务
-
Success pretty 写 stdout;success JSON 写 stdout;refresh events/diagnostics/failure 写 stderr;failure JSON 写 stderr;SELECT 使用 variables/rows;ASK 使用
ask或 JSON value;graph result 使用 quads。Exit code 来自 CLI projection。 - 测试任务
-
覆盖 stdout/stderr 分离、refresh stderr、failure stderr、JSON envelope、RDF term JSON preservation、TTL-only no freshness field、no tutorial text、usage failure no stack trace。
- 验证命令
pnpm --filter inkrail test
pnpm --filter inkrail typecheck
- 提交规则
-
实现提交只包含本工作包文件边界内的源码、测试、文档、fixture 或配置修改。审核证据提交只包含本工作包 review package、状态台账和必要的计划书记录更新。文件边界外修改必须写入审核包的受审例外。
- 审核规则
-
审核者必须核对目标依据、文件边界、实际命令、命令结果、未处理对象去向、全局打回条件和解锁关系。缺少提交 hash、review package 或实际命令结果时,本工作包不得进入
通过。 - 验收标准
-
Output projection 不执行 query,不读 config,不 refresh。字段名保留 SPARQL variables。JSON machine surface 保持稳定。
- 打回条件
-
Diagnostics 混入 stdout;failure JSON 写 stdout;field names 被友好化而脱离 SPARQL variables;command output 写 source coordinate 教程。
- 解锁关系
28. WP-18:Built-in Action Registry
- 目标
-
建立内置查询动作 registry。Registry 保存 action id、CLI path、query kind、parameter schema、SPARQL template、variables、sort contract 和 source workflow reference。
- 上游门槛
-
WP-16 通过。
- 上下文闭包
-
10 号 query template contract、heading actions、structure actions、xref actions、degree/neighborhood actions 和 audit actions;08 号 query library、heading location、structural scope、xref edge、xref degree、xref neighborhood 和 quality audit;11 号 built-in action flow。
- 文件边界
packages/inkrail/src/core/query-actions.ts
packages/inkrail/src/services/built-in-actions.ts
packages/inkrail/src/**/*.{test,spec}.ts
- 实施任务
-
定义 source、outline、heading locate/raw、labels、structure、xrefs、degree、neighborhood、audit action definitions。每个 definition 保留 query source reference 和 exact variables/sort contract。实现 SPARQL rendering 和
printQueryresult。 - 测试任务
-
用 fixture 或 snapshots 锁定 SPARQL templates、SELECT variables、ORDER BY、OPTIONAL、FILTER NOT EXISTS、GROUP BY、HAVING、property path、parameter interpolation 和 source reference。
- 验证命令
pnpm --filter inkrail test
pnpm --filter inkrail typecheck
- 提交规则
-
实现提交只包含本工作包文件边界内的源码、测试、文档、fixture 或配置修改。审核证据提交只包含本工作包 review package、状态台账和必要的计划书记录更新。文件边界外修改必须写入审核包的受审例外。
- 审核规则
-
审核者必须核对目标依据、文件边界、实际命令、命令结果、未处理对象去向、全局打回条件和解锁关系。缺少提交 hash、review package 或实际命令结果时,本工作包不得进入
通过。 - 验收标准
-
Registry 是 built-in action 语义唯一来源。CLI command mapping 只消费 registry。
--print-query在 render 后停止。 - 打回条件
-
SPARQL 凭记忆改写;registry 缺 source workflow reference;action 改变事实边界;parameter interpolation 可注入 arbitrary SPARQL structure。
- 解锁关系
-
本工作包通过后解锁 WP-19。
29. WP-19:Built-in CLI Command Mapping
- 目标
-
把 built-in action registry 映射到 CLI command surface。
- 上游门槛
- 上下文闭包
-
10 号 source action、heading actions、structure actions、xref actions、degree/neighborhood actions 和 audit actions;11 号 built-in action flow 与 CLI consumer;WP-18 registry。
- 文件边界
packages/inkrail/src/commands/builtins.ts
packages/inkrail/src/services/built-in-actions.ts
packages/inkrail/src/cli.ts
packages/inkrail/src/**/*.{test,spec}.ts
- 实施任务
-
注册 source、outline、heading、labels、structure、xrefs、degree、neighborhood、audit commands。CLI parameters 映射到 registry parameter schema。支持 project mode 与适用的 TTL-only mode。
--print-query直接输出 rendered SPARQL。 - 测试任务
-
覆盖每个 command path、参数映射、JSON/pretty mode、
--print-query不查找 project、不读取 TTL、不执行 refresh、不执行 query、variables 与 registry 一致、未知/非法 parameter failure。 - 验证命令
pnpm --filter inkrail test
pnpm --filter inkrail typecheck
- 提交规则
-
实现提交只包含本工作包文件边界内的源码、测试、文档、fixture 或配置修改。审核证据提交只包含本工作包 review package、状态台账和必要的计划书记录更新。文件边界外修改必须写入审核包的受审例外。
- 审核规则
-
审核者必须核对目标依据、文件边界、实际命令、命令结果、未处理对象去向、全局打回条件和解锁关系。缺少提交 hash、review package 或实际命令结果时,本工作包不得进入
通过。 - 验收标准
-
Command handler 不拼 SPARQL。Command output 使用 WP-17 projection。Command set 与 10 号 appendix C 一致。
- 打回条件
-
CLI command 自己拥有 query semantics;
--print-query触发 refresh;command output variables 与 registry SELECT variables 不一致。 - 解锁关系
-
本工作包通过后解锁 WP-20。
第六部:文档、发布与关闭
本部完成 runtime 闭环:最小端到端 fixture、用户文档同步、build/lint/package/final gates 和计划关闭判断。
30. WP-20:End-to-end Fixture and Contract Closure
- 目标
-
建立最小标准书架端到端 fixture,验证
init → bookshelf init/register → books add/use → refresh → query → built-in action JSON的完整 runtime chain。 - 上游门槛
-
WP-19 通过。
- 上下文闭包
-
11 号 fixture strategy、test layering 和 contract test matrix;10 号 initialization contract、refresh state machine、query modes 和 built-in action query template contract。
- 文件边界
packages/inkrail/test/fixtures/**
packages/inkrail/src/**/*.{test,spec}.ts
packages/inkrail/src/test-support/**
- 实施任务
-
创建最小 standard bookshelf fixture 或 fixture builder。覆盖 project memory、standard profile、book-entry projection、RDF12 TTL freshness、Oxigraph query 和 built-in JSON output。端到端 fixture 不覆盖所有 built-in actions;它证明主 runtime chain 成立。
- 测试任务
-
验证 source coordinate、freshness、JSON envelope、RDF term JSON 和 command exit code。确保 fixture 不依赖前次运行产生的 build output。
- 验证命令
pnpm --filter inkrail test
pnpm --filter inkrail typecheck
- 提交规则
-
实现提交只包含本工作包文件边界内的源码、测试、文档、fixture 或配置修改。审核证据提交只包含本工作包 review package、状态台账和必要的计划书记录更新。文件边界外修改必须写入审核包的受审例外。
- 审核规则
-
审核者必须核对目标依据、文件边界、实际命令、命令结果、未处理对象去向、全局打回条件和解锁关系。缺少提交 hash、review package 或实际命令结果时,本工作包不得进入
通过。 - 验收标准
-
端到端 fixture 连接主要模块,而不替代 core/service/adapter tests。Fixture 位于 package 或 project-local test area。
- 打回条件
-
端到端 fixture 只证明命令能跑;未验证 freshness/source coordinate/RDF term;fixture 依赖旧 build output。
- 解锁关系
-
本工作包通过后解锁 WP-21。
31. WP-21:README, User Guide, and Docs Sync
- 目标
-
将 runtime 完成后的用户表面同步到 root README、package README 和用户指南。
- 上游门槛
-
WP-20 通过。
- 上下文闭包
-
10 号 readme/guide contract;11 号 documentation quality;当前
README.md、packages/inkrail/README.md和 docs catalog。 - 文件边界
README.md
packages/inkrail/README.md
docs/bookshelf/catalog.adoc
docs/bookshelf/books/12-inkrail-runtime-implementation-wbs/**
docs/**/user-guide*.adoc
CHANGELOG.md
- 实施任务
-
README 说明 install、project init、bookshelf init/register、book register/default、refresh、query、built-ins、TTL-only、explicit projection、source-aware output 和边界。Package README 不再声明无 runtime。User guide 承担 source coordinate 与 reading/editing loop 说明。
- 测试任务
-
文档示例命令对应 supported commands。Docs 不承诺跨书联合查询、payload 业务解释、remote federation 或 stale TTL fallback。
- 验证命令
pnpm --dir docs/bookshelf test
pnpm --dir docs/bookshelf build
pnpm check
- 提交规则
-
实现提交只包含本工作包文件边界内的源码、测试、文档、fixture 或配置修改。审核证据提交只包含本工作包 review package、状态台账和必要的计划书记录更新。文件边界外修改必须写入审核包的受审例外。
- 审核规则
-
审核者必须核对目标依据、文件边界、实际命令、命令结果、未处理对象去向、全局打回条件和解锁关系。缺少提交 hash、review package 或实际命令结果时,本工作包不得进入
通过。 - 验收标准
-
用户入口与 runtime surface 一致。Command output 不承担教学文本。10/11 号 body 只在发现契约变化时通过新的受控修订修改。
- 打回条件
-
README 仍说 package 没有 runtime;文档承诺非目标;用户指南把 stale TTL 当可用 fallback;示例命令不受测试或契约支持。
- 解锁关系
-
本工作包通过后解锁 WP-22。
32. WP-22:Build, Lint, Package, and Final Gates
- 目标
-
执行 runtime final gates、docs gates 和 package boundary checks。
- 上游门槛
-
WP-21 通过。
- 上下文闭包
-
11 号 build/lint/package gates 与 architecture acceptance;package manifest scripts;docs bookshelf build/test commands。
- 文件边界
packages/inkrail/package.json
packages/inkrail/**
docs/bookshelf/**
- 实施任务
-
确认 scripts 稳定:typecheck、test、lint、build、pack:check、full check。验证 package exports、bin、types、dist、README、LICENSE、package.json。记录 pack dry-run required/forbidden files。
- 测试任务
-
验证 final gate 命令实际运行并记录结果。检查 package dry-run 的 required files 与 forbidden files,检查 exports、bin、types 与 dist output 的一致性。
- 验证命令
pnpm --filter inkrail typecheck
pnpm --filter inkrail test
pnpm --filter inkrail lint
pnpm --filter inkrail build
pnpm --filter inkrail pack:check
pnpm check
- 提交规则
-
实现提交只包含本工作包文件边界内的源码、测试、文档、fixture 或配置修改。审核证据提交只包含本工作包 review package、状态台账和必要的计划书记录更新。文件边界外修改必须写入审核包的受审例外。
- 审核规则
-
审核者必须核对目标依据、文件边界、实际命令、命令结果、未处理对象去向、全局打回条件和解锁关系。缺少提交 hash、review package 或实际命令结果时,本工作包不得进入
通过。 - 验收标准
-
全部命令通过。Package dry-run 只包含允许发布文件。Bin 指向 built file。Exports 可解析。Docs build 与 runtime checks 同时通过。
- 打回条件
-
任一最终命令失败且未登记阻塞;pack 包含 forbidden files;bin 指向不存在文件;types 缺失;lint/typecheck/test/build 任一被跳过却写成通过。
- 解锁关系
-
本工作包通过后解锁 WP-23。
33. WP-23:Plan Closure and Body Revision Assessment
- 目标
-
关闭本 implementation WBS,并判断实现结果是否需要修订 10 号或 11 号 body。
- 上游门槛
-
WP-22 通过。
- 上下文闭包
-
材料体系
closure-record、entry-rules、migration-cleanup;本书 closure record template;10 号 body 与 11 号 body。 - 文件边界
docs/bookshelf/books/12-inkrail-runtime-implementation-wbs/backmatter/closure-record.adoc
docs/bookshelf/books/12-inkrail-runtime-implementation-wbs/book.adoc
docs/bookshelf/catalog.adoc
docs/bookshelf/books/10-inkrail-cli-design/**
docs/bookshelf/books/11-inkrail-software-architecture-and-quality-design/**
- 实施任务
-
创建实际 closure record。记录最终提交、最终命令结果、package boundary、已进入当前事实对象、未处理对象去向、body revision 判断、当前对象入口、治理追溯入口和后续治理入口。若实现发现需求或架构缺口,开启新的 lab object 或修订相应 body。
- 测试任务
-
验证 closure record 被
book.adocinclude,状态台账所有 WP 为通过或有明确关闭/打回记录。Docs build 通过。 - 验证命令
pnpm --dir docs/bookshelf test
pnpm --dir docs/bookshelf build
pnpm check
- 提交规则
-
实现提交只包含本工作包文件边界内的源码、测试、文档、fixture 或配置修改。审核证据提交只包含本工作包 review package、状态台账和必要的计划书记录更新。文件边界外修改必须写入审核包的受审例外。
- 审核规则
-
审核者必须核对目标依据、文件边界、实际命令、命令结果、未处理对象去向、全局打回条件和解锁关系。缺少提交 hash、review package 或实际命令结果时,本工作包不得进入
通过。 - 验收标准
-
本计划有关闭记录。未处理对象没有悬空项。10/11 号修订判断有依据。Catalog 不让关闭计划抢占 current body。
- 打回条件
-
关闭记录写“后续再说”;实现发现 body 缺口但不进入新 lab 或 body revision;状态台账仍有无去向的未开始/打回项;closure record 未进入 book public surface。
- 解锁关系
-
本工作包通过后关闭本 implementation WBS;后续实现变更必须开启新的 lab object 或进入已登记的 body revision。
Appendix A: 阶段审核包模板
审核包是工作包状态转移的证据记录,不是进度汇报。
34. 工作包信息
| 工作包编号 |
|
| 工作包名称 |
|
| 提交 hash |
|
| 执行者 |
|
| 审核者 |
|
| 审核状态 |
|
35. 修改文件
文件列表只包含本工作包提交中的路径。文件边界外修改必须作为受审例外记录。
36. 上下文闭包阅读记录
本节记录执行者进入工作包前实际阅读的 body、架构、源码、测试、模板、依赖和治理材料。未阅读材料不得写成已读。
37. 完成范围
本节列出已经实现并由测试或验证命令覆盖的对象事实。完成范围不得使用“基本完成”“后续完善”等模糊状态词。
38. 未处理对象
本节列出工作包边界外的对象。每个未处理对象必须指向后续工作包、明确非目标、打回项或新的 lab object。
39. 已运行命令与结果
命令必须是实际运行过的命令。失败命令必须记录失败摘要、失败范围和是否阻塞状态转移。
40. 检查清单
-
目标对象来自 10 号书、11 号书、08 号书或已核验依赖事实。
-
本工作包没有重新定义目标 body。
-
本工作包没有触发全局打回条件。
-
本工作包新增代码有相应测试层。
-
本工作包文档、测试、配置和样例影响面已纳入文件边界。
-
本工作包未处理对象有去向。
41. 审核结论
| 结论 |
|
| 理由 |
|
| 后续动作 |
|
Appendix B: 工作包状态台账
本台账记录工作包治理事实。状态字段只使用 未开始、执行中、待审核、打回 和 通过。
| 工作包 | 名称 | 状态 | 提交 hash | 审核记录 |
|---|---|---|---|---|
WP-00 |
Baseline Gates and Review Infrastructure |
未开始 |
待创建 |
|
WP-01 |
Runtime Package Shell |
未开始 |
待创建 |
|
WP-02 |
Result, Failure, and Output Foundation |
未开始 |
待创建 |
|
WP-03 |
Public API Export Surface |
未开始 |
待创建 |
|
WP-04 |
Config Schema and Project Context |
未开始 |
待创建 |
|
WP-05 |
Book Selection and Path Derivation |
未开始 |
待创建 |
|
WP-06 |
Project Memory Mutation Services |
未开始 |
待创建 |
|
WP-07 |
Workspace Initializer Adapter and Bookshelf Init |
未开始 |
待创建 |
|
WP-08 |
Bookshelf Runtime Dispatch |
未开始 |
待创建 |
|
WP-09 |
Abundant-tree Adapter Capability Lock |
未开始 |
待创建 |
|
WP-10 |
Source Set and Projection Fingerprints |
未开始 |
待创建 |
|
WP-11 |
State Store and Refresh Decision |
未开始 |
待创建 |
|
WP-12 |
Explicit Projection Service |
未开始 |
待创建 |
|
WP-13 |
Project Refresh State Machine |
未开始 |
待创建 |
|
WP-14 |
Oxigraph Adapter and Query Classifier |
未开始 |
待创建 |
|
WP-15 |
RDF Term JSON Model |
未开始 |
待创建 |
|
WP-16 |
Raw Query Modes |
未开始 |
待创建 |
|
WP-17 |
Output Projection Surface |
未开始 |
待创建 |
|
WP-18 |
Built-in Action Registry |
未开始 |
待创建 |
|
WP-19 |
Built-in CLI Command Mapping |
未开始 |
待创建 |
|
WP-20 |
End-to-end Fixture and Contract Closure |
未开始 |
待创建 |
|
WP-21 |
README, User Guide, and Docs Sync |
未开始 |
待创建 |
|
WP-22 |
Build, Lint, Package, and Final Gates |
未开始 |
待创建 |
|
WP-23 |
Plan Closure and Body Revision Assessment |
未开始 |
待创建 |
提交产生后,提交 hash 必须写入本表。审核包路径必须写入审核记录。台账备注不得记录愿望、估计、口头进度或情绪判断。
Appendix C: 关闭记录模板
关闭记录记录本计划书的结束方式。实际关闭记录应在 runtime implementation 完成后创建,并由本书 include。
42. 关闭对象
| 关闭对象 |
|
| 目标 body 依据 | |
| 材料体系依据 |
|
43. 最终提交
| 最终提交 hash |
|
| 最终审核状态 |
|
| 关闭结论 |
|
44. 最终验证命令
pnpm --filter inkrail typecheck
pnpm --filter inkrail test
pnpm --filter inkrail lint
pnpm --filter inkrail build
pnpm --filter inkrail pack:check
pnpm check
关闭记录必须写入实际运行结果。未运行命令不得写成通过。
45. 已进入当前事实的对象
本节只列已经由代码、测试、文档和审核证据共同支撑的对象事实。
46. 未处理对象与去向
未处理对象必须有去向。不得写“后续再说”。
47. Body 修订判断
| 是否需要修订 10 号书 |
|
| 是否需要修订 11 号书 |
|
| 修订入口 |
|
术语表
- implementation WBS
-
将目标 body 事实拆成可执行、可审核、可关闭工作包的工作分解结构。
- work package
-
受控变更的工作单元,必须有目标、文件边界、验证命令、审核规则和打回条件。
- review package
-
工作包状态转移的证据记录。
- status ledger
-
记录工作包当前治理状态的台账。
- closure record
-
记录治理对象结束方式和结果去向的关闭材料。
- target body basis
-
工作包所依赖的当前 body 或已核验事实。
- context closure
-
工作包启动前必须阅读的规格、架构、源码、测试、模板、依赖和治理上下文。
- global rejection condition
-
触发工作包打回的全局对象错误。
- package boundary
-
npm publish artifact 的文件边界。
- capability lock
-
用 adapter contract test 锁定的依赖能力事实。
参考坐标
-
[inkrail-cli-design] inkrail CLI 设计书。
-
[inkrail-architecture] inkrail 软件架构与工程质量设计书。
-
[rdf12-query-workflow] AsciiDoc 书稿 RDF 投影查询工作流。
-
[body-lab-material-system]
micheng-ts/projects/asciidoc-abundant-tree/docs/bookshelf/books/08-body-lab-material-system/。 -
[implementation-plan-reference]
micheng-ts/projects/asciidoc-abundant-tree/docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/。 -
[structured-writing-conventions]
micheng-ts/projects/asciidoc-multi-book-workspace/docs/07-structured-writing-conventions.md。 -
[rootward-typescript-template]
projects/rootward/templates/typescript。 -
[asciidoc-multi-book-workspace]
create-asciidoc-multi-book-workspace。 -
[rdf12-concepts] W3C, RDF 1.2 Concepts and Abstract Data Model。
-
[configuration-management] ISO/IEC/IEEE 828, Systems and software engineering — Configuration management。
索引
本索引 section 位于书籍后置区域。正文中的显式 heading ID、role、relation predicate 和 index terms 是后续结构查询入口。
核心索引词:
indexterm:[implementation WBS]
indexterm:[work package]
indexterm:[review package]
indexterm:[status ledger]
indexterm:[closure record]
indexterm:[public API shell]
indexterm:[state store]
indexterm:[refresh state machine]
indexterm:[query action registry]
indexterm:[RDF term JSON]
indexterm:[package boundary]