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 号架构基线的当前对象定义。

前言

本书位于 10 号需求契约11 号架构基线 之后。10 号书定义 inkrail 应当成立的对象契约;11 号书定义这些契约的工程承载位置;本书定义实现活动如何被拆分、执行、审核和关闭。

本书还引用 08 号 RDF 投影查询工作流 作为内置查询动作的 SPARQL 语义来源,引用 asciidoc-abundant-treecreate-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-architecturerel=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 与已核验依赖事实。

依据 路径或对象 进入本书的位置

需求契约

10 号 inkrail CLI 设计书

项目记忆、标准书架、路径推导、新鲜度、查询模式、输出表面、错误语义、内置动作和测试合同。

架构基线

11 号软件架构与工程质量设计书

Public API、module roles、data models、runtime flows、adapter contracts 和 quality gates。

查询语义来源

08 号 RDF 投影查询工作流

Built-in action registry 的 SPARQL templates、variables、sorting、source coordinate 和审计事实边界。

材料治理规则

micheng-ts/projects/asciidoc-abundant-tree/docs/bookshelf/books/08-body-lab-material-system/

Lab object、work package、review package、status ledger、closure record、进入 body 规则和检查清单。

Implementation plan 形态

micheng-ts/projects/asciidoc-abundant-tree/docs/bookshelf/books/11-book-entry-source-mapped-logical-document-implementation-plan/

执行契约、当前源码状态、审核包模板、状态台账和关闭记录模板。

工程骨架参考

projects/rootward/templates/typescript

ESM package、bin entry、runCli(args,{cwd})、output projection、filesystem abstraction 和 test fixture 组织形态。

Projection dependency

asciidoc-abundant-tree@0.1.12

Book-entry parse、source files、RDF12 TTL、RDF12 JSON-LD 和 projector identity。

Workspace initializer dependency

create-asciidoc-multi-book-workspace@0.1.5

Formal export initWorkspace、标准书架生成、fixed template outputs 和 runtime script。

Rootward template 只提供工程形态参考。其 sourcesscannersdiscoverscan 业务语义不得进入 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 只包含 LICENSEREADME.md。当前 package 没有 src/、没有 CLI binary、没有 public library API、没有 runtime tests。

pnpm check 在本书创建前后均可作为基线验证命令。该命令执行版本检查、docs bookshelf tests、docs build 和 package dry-run。当前 package dry-run 只发布 LICENSEREADME.mdpackage.json 三个文件。

本计划的 WP-01 才允许把 packages/inkrail 从 specification package 转为 runtime package shell。任何工作包不得在当前源码状态章节中预写 runtime 已存在的事实。

6. 执行规则

工作包状态使用受控集合:

未开始

工作包没有实现提交。

执行中

工作包存在实现活动,尚未提交审核包。

待审核

工作包提交 hash 和审核包已经产生。

打回

审核结论要求补充事实、拆分范围或修正实现。

通过

审核者确认该工作包满足验收条件。

每个工作包开始前必须满足上游门槛。除 WP-00 外,前置工作包必须处于 通过 状态。工作包章节中的 blocks-onunlocks 关系定义启动顺序。

每个工作包必须列出上下文闭包。上下文闭包包含目标 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-treecreate-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、OPTIONALFILTER NOT EXISTSGROUP BYHAVING 或 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

关闭记录关闭目标治理对象。

本书第一版使用 ownerwpstatussurfacepackage 五个 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.adoc include 全部存在,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 treepackage boundarypublic exportsCLI consumerbuild/lint/package gates;Rootward template package.jsontsconfig.jsontsdown.config.tsvitest.config.tssrc/bin.tssrc/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。

解锁关系

本工作包通过后解锁 WP-02WP-03

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 modeloutput projection flowoutput test contract;Rootward src/core/errors.tssrc/core/result.tssrc/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
实施任务

定义 InkrailErrorCodeInkrailFailureInkrailDiagnosticInkrailResult<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-03WP-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 类型。

上游门槛

WP-01WP-02 通过。

上下文闭包

11 号 public exportsconsumer roles10 号 query modesinitialization 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。

解锁关系

本工作包通过后,与 WP-02 共同解锁 WP-04

第三部:项目记忆、Profile 与初始化

本部实现项目记忆、profile、路径推导、项目配置 mutation、标准书架 initializer adapter 和书架本地 runtime dispatch。它把 10 号第二部契约落入 11 号 project-memory 架构对象。

14. WP-04:Config Schema and Project Context

目标

实现 .inkrail/config.toml raw schema、normalized config、parse/serialize、project discovery 和 project context model。

上游门槛

WP-02WP-03 通过。

上下文闭包

10 号 project config model11 号 config modelproject/book modelpath modelapplication 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。

解锁关系

本工作包通过后解锁 WP-05WP-06

15. WP-05:Book Selection and Path Derivation

目标

实现 target book selection 与 standard/custom profile path derivation。

上游门槛

WP-04 通过。

上下文闭包

10 号 book path derivationquery modes 中的 book selection11 号 path modelproject/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、未知 book BOOK_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。

解锁关系

本工作包通过后解锁 WP-07WP-08WP-09

16. WP-06:Project Memory Mutation Services

目标

实现项目记忆 mutation services 与基础命令:initbookshelves addbooks addbooks usebooks listconfig printstatusdoctor

上游门槛

WP-04WP-05 通过。

上下文闭包

10 号 initialization contractproject config model11 号 application servicesconfig modeldocumentation 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 输出教学文本或扩大公共契约。

解锁关系

本工作包通过后,与 WP-05 共同解锁 WP-07WP-08

17. WP-07:Workspace Initializer Adapter and Bookshelf Init

目标

集成 create-asciidoc-multi-book-workspace@0.1.5 formal export initWorkspace,实现 inkrail bookshelf init 与可选 --register

上游门槛

WP-05WP-06 通过。

上下文闭包

10 号 standard bookshelf templateinitialization contract11 号 workspace initializer adapterbookshelf initialization flow;上游 micheng-ts/projects/asciidoc-multi-book-workspace/package.jsonsrc/index.tssrc/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.adocbooks/shared/package.json.gitignoretools/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;复制标准模板到 inkrail core;force 删除未知用户文件;sample books 自动进入

解锁关系

本工作包通过后为 WP-20 提供标准书架初始化前置。

18. WP-08:Bookshelf Runtime Dispatch

目标

实现已登记 standard bookshelf 的 local buildcheckclean script 调度。

上游门槛

WP-05WP-06WP-07 通过。

上下文闭包

10 号 bookshelf build dispatch11 号 bookshelf runtime dispatch flowfilesystem/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.12 adapter,并用 contract tests 锁定 book-entry parse、source files、RDF12 TTL 和 RDF12 JSON-LD 能力。

上游门槛

WP-05 通过。

上下文闭包

11 号 abundant-tree adapterexplicit projection flowversion/capability locks;上游 src/index.ts public 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 只使用 parseAbundantTreerdf12 public 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。

解锁关系

本工作包通过后解锁 WP-10WP-12WP-13

20. WP-10:Source Set and Projection Fingerprints

目标

实现 source file fingerprint、source set fingerprint 和 projection fingerprint。

上游门槛

WP-09 通过。

上下文闭包

10 号 fingerprint model11 号 source-set fingerprintprojection fingerprintpath 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.jsonrdf12-json-ld.json state records,以及 refresh decision。

上游门槛

WP-10 通过。

上下文闭包

10 号 refresh state machine11 号 state storerefresh state machine flowprojection 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

目标

实现 projectAdoc service 和 CLI inkrail project,支持 rdf12rdf12-json-ld 输出。

上游门槛

WP-09 通过。

上下文闭包

10 号 RDF12/JSON-LD projections11 号 explicit projection flowabundant-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 refresh command。

上游门槛

WP-10WP-11 通过。

上下文闭包

10 号 refresh state machine11 号 refresh state machine flowproject mode query flowstate 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 持有。

解锁关系

本工作包通过后解锁 WP-14WP-16

第五部:查询、输出与内置动作

本部实现 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 engine11 号 Oxigraph adapterquery result modelversion/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 被丢失或字符串化。

解锁关系

本工作包通过后解锁 WP-15WP-16

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 JSONquery result modeloutput 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。

上游门槛

WP-13WP-14 通过。

上下文闭包

10 号 query modes11 号 project mode query flowTTL-only query flowquery 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。

上游门槛

WP-15WP-16 通过。

上下文闭包

10 号 output surfaces11 号 output projection flowoutput 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 教程。

解锁关系

本工作包通过后,与 WP-18 共同解锁 WP-19

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 contractheading actionsstructure actionsxref actionsdegree/neighborhood actionsaudit actions08 号 query libraryheading locationstructural scopexref edgexref degreexref neighborhoodquality audit11 号 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 和 printQuery result。

测试任务

用 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。

上游门槛

WP-18WP-17 通过。

上下文闭包

10 号 source actionheading actionsstructure actionsxref actionsdegree/neighborhood actionsaudit actions11 号 built-in action flowCLI consumerWP-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 strategytest layeringcontract test matrix10 号 initialization contractrefresh state machinequery modesbuilt-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 contract11 号 documentation quality;当前 README.mdpackages/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 gatesarchitecture 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-recordentry-rulesmigration-cleanup本书 closure record template10 号 body11 号 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.adoc include,状态台账所有 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. 工作包信息

工作包编号

WP-NN

工作包名称

<章节标题>

提交 hash

<git commit hash>

执行者

<name>

审核者

<name>

审核状态

待审核打回通过

35. 修改文件

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

36. 上下文闭包阅读记录

本节记录执行者进入工作包前实际阅读的 body、架构、源码、测试、模板、依赖和治理材料。未阅读材料不得写成已读。

37. 完成范围

本节列出已经实现并由测试或验证命令覆盖的对象事实。完成范围不得使用“基本完成”“后续完善”等模糊状态词。

38. 未处理对象

本节列出工作包边界外的对象。每个未处理对象必须指向后续工作包、明确非目标、打回项或新的 lab object。

39. 已运行命令与结果

命令必须是实际运行过的命令。失败命令必须记录失败摘要、失败范围和是否阻塞状态转移。

40. 检查清单

  • 目标对象来自 10 号书、11 号书、08 号书或已核验依赖事实。

  • 本工作包没有重新定义目标 body。

  • 本工作包没有触发全局打回条件。

  • 本工作包新增代码有相应测试层。

  • 本工作包文档、测试、配置和样例影响面已纳入文件边界。

  • 本工作包未处理对象有去向。

41. 审核结论

结论

通过打回

理由

<对象级理由>

后续动作

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

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. 关闭对象

关闭对象

12-inkrail-runtime-implementation-wbs

目标 body 依据

10 号 inkrail CLI 设计书11 号软件架构与工程质量设计书

材料体系依据

100_body200_lab 材料体系设计

43. 最终提交

最终提交 hash

<git commit 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 号书

修订入口

<新 lab object 或非目标理由>

术语表

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-abundant-tree] asciidoc-abundant-tree

  • [asciidoc-multi-book-workspace] create-asciidoc-multi-book-workspace

  • [oxigraph] Oxigraph RDF store and SPARQL engine。

  • [rdfjs] RDF/JS data model。

  • [rdf12-concepts] W3C, RDF 1.2 Concepts and Abstract Data Model

  • [sparql12-query] W3C, SPARQL 1.2 Query Language

  • [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]