frontend-project-context 1.0.0

package/docs/15-SOURCE-LIFECYCLE-CLOSURE-DESIGN.md

@@ -0,0 +1,260 @@
+# 1.0.0 Source Lifecycle Closure 设计与实现记录
+
+> 权威说明：本文只冻结首次公开发布前的来源生命周期修补范围。产品身份、内核、永久边界和不变量仍以 [00-PRODUCT-CONSTITUTION.md](./00-PRODUCT-CONSTITUTION.md) 为准；当前事实与授权以 [PROJECT_STATE.json](../PROJECT_STATE.json) 为准。
+>
+> 状态：`implemented-local-verified; implementation-authority-consumed; public-publication-authorized-authenticated`
+>
+> 审查基线：产品宪法 `1.1.1`、PROJECT_STATE schema `39`、package `1.0.0`、Contract schema 1、A-01 至 A-39 加 B0/CLI 共 43 项本地通过。实现后 PROJECT_STATE schema 为 41，Contract reader 支持 1/2，A-01 至 A-45 加 B0/CLI 共 49 项本地通过。
+
+## 1. 设计结论
+
+重大项目调整不需要新的框架扫描器、AI Runtime 或第二套治理系统。现有能力已经覆盖：
+
+- `check` 全项目检测 source、contract、verification 和 projection 漂移；
+- `dashboard` 汇总全部来源状态、引用关系、影响 item 和 projection；
+- `review-source` 对单一来源给出当前 digest 与确定性影响集；
+- `accept-source-change` 处理同一 locator 上仍可读取的内容变化；
+- `revise`、`deprecate`、`approve --pending` 和 `publish` 完成 item 后续治理。
+
+唯一无法通过稳定 CLI 关闭的情况是：**已登记本地来源被删除、搬迁或永久退役**。`accept-source-change` 明确拒绝 missing/unreadable；`register` 明确拒绝同 ID locator 变化；Contract schema 1 没有 source lifecycle，checker 会永久报告 missing。维护者最终只能直接编辑内部 JSON，这与已经声明的知识维护闭环不一致。
+
+因此首次公开发布前只补 `Source Lifecycle Closure`：允许显式登记替代来源、把受影响 item 修订到替代来源，并在无当前知识继续依赖时显式废弃旧来源。默认仍 fail closed，任何来源或规范都不会自动批准。
+
+## 2. 需求分类
+
+按产品宪法第 9 节，本缺口分类为 **内核缺陷**，不是新产品方向：
+
+1. 来源注册与追溯属于固定内核；
+2. `source-missing` 已经是稳定 finding，但没有无需手改 store 的安全恢复出口；
+3. 该缺口在任意项目搬迁文件时都会出现，不依赖 Vue、React、路由或业务语义；
+4. 修补只延长既有 source → item → approval → projection 生命周期，不改变产品身份。
+
+自然语言需求到代码位置解析属于 Coding Agent 或可选消费者适配器，不进入本次内核修补。
+
+## 3. 用户闭环
+
+### 3.1 来源内容仍在原位置
+
+继续使用既有流程，不增加命令：
+
+```text
+check/dashboard
+→ review-source
+→ accept-source-change --expected-digest ... --affected-items ... --write
+→ revise/deprecate item
+→ approve --pending
+→ publish
+→ check
+```
+
+### 3.2 来源搬迁到新位置
+
+来源 locator 是 provenance 身份的一部分，因此不在原 ID 上静默改路径：
+
+```text
+check/dashboard 确认旧来源 missing
+→ register 新 source ID 与新 locator --write
+→ revise 受影响 item，改为引用新 source ID --write
+→ approve --pending --ids ... --write
+→ deprecate-source 旧 source ID --write
+→ publish --write
+→ check
+```
+
+旧来源作为 deprecated provenance 留在 Contract，Git 历史之外仍能解释旧 item；它不再读取文件、不进入 source lock，也不支持新 proposed/approved item 引用。
+
+### 3.3 来源永久退役
+
+```text
+check/dashboard
+→ revise 或 deprecate 所有仍引用旧来源的 proposed/approved item
+→ approve 需要保留的 revision
+→ deprecate-source --expected-source-digest ... --by ... --rationale ... --write
+→ publish --write
+→ check
+```
+
+`deprecate-source` 不级联修改 item、不删除审计记录、不自动选择替代来源。
+
+## 4. 最小 CLI 合同
+
+只新增一个命令：
+
+```text
+project-context deprecate-source --project PATH --id SOURCE_ID
+  [--expected-source-digest SHA256] --by NAME --rationale TEXT
+  [--write] [--json]
+```
+
+行为固定为：
+
+- 默认 preview；`--write` 必须同时提供本命令自己的 `--expected-source-digest`；
+- digest 是当前 canonical source object 的 digest，不是文件当前内容 digest；preview 和 `review-source --json` 都返回该值；
+- source 必须存在且仍为 active；已 deprecated 返回稳定输入错误；
+- 任何 proposed 或 approved item 仍通过 `sources` 或 `verification.source` 引用它时拒绝写入，并返回稳定引用列表；
+- deprecated item 可以继续引用 deprecated source，以保留历史 provenance；
+- 本地来源可以处于 changed、missing 或 unreadable，废弃动作不要求文件恢复；
+- 成功时把 source 标记为 deprecated，记录 `by/at/rationale`，并从 source lock 删除对应 checkpoint；
+- 不改 item、不批准内容、不删除 source、不写 projection；Contract digest 变化后既有 projection 自然 stale；
+- 写前重新核对 Contract、source lock、projection lock 快照和 source object digest；状态变化时零写入。
+
+`register`、`propose`、`approve`、`revise`、`check`、`review-source`、`dashboard` 和 `publish` 只做 schema 2 兼容调整，不新增其他用户入口。
+
+## 5. 数据模型
+
+### 5.1 Contract schema 2
+
+source 增加显式 lifecycle：
+
+```json
+{
+  "id": "source-old-guide",
+  "kind": "file",
+  "path": "docs/old-guide.md",
+  "digest": "sha256:...",
+  "status": "deprecated",
+  "deprecation": {
+    "by": "maintainer",
+    "at": "2026-09-08T00:00:00.000Z",
+    "rationale": "Replaced by source-new-guide after the documentation restructure."
+  }
+}
+```
+
+规则：
+
+- schema 2 的每个 source 必须有 `status: active | deprecated`；
+- active source 不允许 `deprecation`；deprecated source 必须有完整 deprecation；
+- proposed/approved item 的 `sources` 和 `verification.source` 只能指向 active source；
+- deprecated item 可以引用 active 或 deprecated source；
+- deprecated local source 保留最后一次人工确认 digest，但 checker 不再读取 locator；
+- source lock 只保存 active local source；deprecated source 的 lock entry 视为 orphan finding；
+- 不增加 source kind、item kind、scope kind、projection target 或新 store 文件。
+
+### 5.2 Proposal 与 lock
+
+- proposal 继续 schema 1；proposal source 没有 lifecycle 字段，合并到 schema 2 Contract 时按 active 处理；
+- source lock 和 projection lock 继续 schema 1；
+- renderer 继续 version 3；
+- Dashboard View Model 从 2 升为 3，只增加 source `deprecated` 状态和 deprecation 审计字段，不复制来源正文。
+
+### 5.3 兼容迁移
+
+- reader 同时接受 Contract schema 1 和 2；schema 1 source 在内存中解释为 active，但只读命令不得因此写盘；
+- 既有普通命令对 schema 1 项目保持原字节和行为；
+- 第一次成功执行 `deprecate-source --write` 时，把全部现有 source 显式标为 active、目标 source 标为 deprecated，并原子写成 schema 2；
+- schema 2 一旦写入，不自动降级；旧 1.0.0-RC reader 不支持 schema 2，升级说明必须明确；
+- 现有 schema 1 项目无需预先运行 `migrate`，不新增迁移命令。
+
+## 6. 影响集与人工权限
+
+实现必须复用 `sourceImpact` 和现有 item 引用检查：
+
+1. preview 显示 direct、verification、override-dependent、fallback 与 projection 集合；
+2. deprecation 的阻断引用集合覆盖所有 proposed/approved item 的 `sources` 与 `verification.source`；
+3. 不因文件名、source 内容、subject 或 scope 猜测替代关系；
+4. 新来源必须先通过既有 `register --write` 显式登记；
+5. item 必须通过既有 `revise --write` 进入 pending，再通过 `approve --pending --write` 明确批准；
+6. source deprecation 必须有本命令自己的署名、理由、baseline digest 和 `--write`。
+
+不存在自动接受、自动迁移 locator、自动 revision、自动批准或自动 publish。
+
+## 7. 原子性与失败恢复
+
+`deprecate-source` 同时改变 Contract 和 source lock，复用现有 `writeProjectState` 的 lock-first 顺序：
+
+1. 从已加载 snapshot 构造并完整验证 next schema 2 Contract 与 next source lock；
+2. 写前核对 contract/source/projection lock digest 和 source object digest；
+3. 先写 next source lock，再写 next Contract；
+4. 第二步失败时仅在当前 lock 仍等于本命令写入值时恢复旧 lock；
+5. 恢复失败或遭遇并发时，最终状态必须被 `check` 识别为 source-lock mismatch/orphan，不能静默编译；
+6. 不新增文件锁、数据库、history ledger、retry 或后台任务。
+
+## 8. Finding、错误类别与退出码
+
+现有退出码 0–4 不变。
+
+新增或扩展的稳定类别：
+
+| 退出码 | code | 含义 |
+| --- | --- | --- |
+| 0 | `source-deprecation-preview` / 写入成功 | preview 或显式废弃成功 |
+| 1 | `source-baseline-changed`、`project-state-changed` | baseline 或项目快照已变化 |
+| 2 | `source-not-found`、`source-already-deprecated`、`source-still-referenced`、参数/schema 错误 | 当前状态不允许废弃 |
+| 3 | 既有 projection ownership conflict | 所有权冲突语义不变 |
+| 4 | `internal-error` | 非预期失败 |
+
+checker/dashboard 扩展：
+
+- active local source 继续产生 changed/missing/unreadable；
+- deprecated source 不产生文件漂移 finding；
+- deprecated source 仍在 source lock 时产生 `source-lock-deprecated`；
+- proposed/approved item 引用 deprecated source 时产生或抛出 `source-reference-deprecated`；
+- `context`/`publish` 对上述 source finding 继续 fail closed。
+
+## 9. 唯一实现范围
+
+获得单独实现授权后，只允许以下变化：
+
+| 文件/模块 | 唯一允许变化 |
+| --- | --- |
+| `contract-schema.mjs` | 读取 Contract schema 1/2；验证 source lifecycle 和引用约束 |
+| `maintenance.mjs` | source object digest、deprecate preview/commit 和引用预检 |
+| `authoring.mjs` / `approver.mjs` | schema 2 Contract 中新增 source 按 active 合并；拒绝批准 deprecated source 引用 |
+| `checker.mjs` / `source-reader.mjs` | 跳过 deprecated source IO；补稳定 lifecycle finding |
+| `project-store.mjs` | 保持既有快照与 lock-first 写入，支持 schema 2 Contract bytes |
+| `dashboard-model.mjs` / `dashboard-renderer.mjs` | 只增加 deprecated source 展示；View Model schema 3 |
+| `cli.mjs` | `deprecate-source`、help、allowlist 和稳定输出 |
+| `test/project-context/` | A-40 至 A-45；既有 43 项不得删除或弱化 |
+| README、UPGRADING、CHANGELOG、04、05、08、14、15、RTK、PROJECT_STATE、自托管 Contract | 实现完成后同步真实结果 |
+
+明确不修改 discovery 识别范围、scope compiler、Context 内容、projection target 或安装模型。
+
+## 10. 冻结验收 A-40 至 A-45
+
+- **A-40 缺失来源可恢复**：missing active source 阻断；登记替代来源、revision/reapproval、显式 deprecate-source 和 republish 后 check clean，全程不手改 store。
+- **A-41 source deprecation 权限**：preview 零写入；缺 `--write`、baseline、by、rationale 或 baseline 不匹配均零写入；deprecated source 可重复识别但不可重复废弃。
+- **A-42 引用安全**：任一 proposed/approved item 的 source 或 verification 仍引用目标时拒绝；deprecated item 可保留历史引用；不级联修改 item。
+- **A-43 schema 1/2 兼容**：schema 1 继续可读且不发生隐式写；首次 deprecation 按固定规则升 schema 2；proposal/locks 保持 schema 1；旧 renderer 投影按既有规则 stale。
+- **A-44 checker/dashboard/context 一致性**：active 与 deprecated source 分类一致；deprecated 不触发 IO；非法引用和 deprecated lock 被稳定发现；Context/Publish fail closed；看板双语解释完整。
+- **A-45 原子性与永久边界**：模拟 Contract/source-lock/target source baseline 并发和第二步失败；最终可检查且不覆盖并发状态；全量 43 项继续通过，零 Provider、网络、dependency install、child process、Git、业务代码修改或真实项目访问。
+
+实现 Gate：A-01 至 A-45、B0-01/B0-02、CLI 与 release pack 验收全部通过；README 能让另一位维护或维护者完成一次 missing → replacement → retirement → clean 的独立闭环。
+
+## 11. 后续路线，但不在本次实现范围
+
+### 11.1 CI 持续对账
+
+现有 `context:check` 已可在 pull request 和 main push 自动发现漂移，`dashboard` 已可生成全局影响视图。后续只需改进示例，让外部 CI 在失败时保存 dashboard HTML/JSON artifact；这是接入适配，不需要任务调度器或新的核心扫描器。
+
+### 11.2 Targeted Context 消费协议
+
+“AI 指哪打哪”应拆成模型中立消费协议：Coding Agent 先解析候选路径，再调用现有 `context --path ...` 取得确定性 Contract 子集。路径解析、符号索引、调用图和自然语言推断属于 Agent/IDE/LSP 适配层，不能进入本次内核修补，也不能自动扩大写入权限。
+
+是否设计该适配器必须在 Source Lifecycle Closure 实现、验收和首次发布决策之后单独授权。
+
+## 12. 不做项与停止条件
+
+本阶段不做：
+
+- 自动接受 source change、自动批准、自动 revision/deprecation 或自动 publish；
+- 自动修改业务代码、运行项目测试或执行真实开发任务；
+- 自研 Agent Runtime、Provider、MCP、IDE、LSP、符号索引或调用图；
+- 新增框架识别、source kind、item kind、scope kind 或 projection target；
+- 批量 change-set、任务调度、daemon、watch、数据库、文件锁或 Git/Worktree 管理；
+- 网络、依赖安装、真实业务项目、Git commit/tag/push 或 package publish。
+
+## 13. 本地实现结果与停止
+
+2026-09-08 经单独授权，本文第 9 节的唯一范围已经实现，没有推倒重写：
+
+- Contract schema 1/2 reader、source lifecycle 验证、authoring/approval 引用边界已落地；
+- `deprecate-source` 已提供 preview、source object digest baseline、阻断引用、署名/理由审计与显式写入；
+- deprecated source 不再触发 locator IO，source lock checkpoint 被移除，旧 projection 因 Contract digest 变化自然 stale；
+- project store 写前增加 projection lock snapshot 核对，双文件继续使用 lock-first 与条件恢复；
+- Dashboard View Model 升为 3，并以中英标签显示 deprecation 审计；
+- A-40 至 A-45 与全部既有测试通过，`npm run check` 为 49/49。
+
+兼容结果：schema 1 项目可继续只读和普通维护且不会隐式写盘；只有首次成功来源废弃才确定性升级 Contract schema 2；proposal、source lock、projection lock 仍为 schema 1，renderer 仍为 3。自托管 Contract 当前没有需要废弃的来源，因此保持 schema 1，避免无业务理由的强制迁移。
+
+本次实现授权已经完成并消耗。实现阶段未访问真实业务项目、Provider 或网络，未安装依赖，未执行 Git 或发布操作，也未新增第 12 节所列任何非目标。Source Lifecycle Closure 的发布保持条件已关闭；随后用户已单独授权完成 public npm 发布，发布者 npmjs.org CLI 身份已经验证。

package/docs/README.md

@@ -0,0 +1,74 @@
+# 文档索引
+
+产品宪法是唯一规范真源；其余文档记录设计形成过程、实现说明或证据，不能反向改变产品定义。
+
+## 唯一规范真源
+
+0. [00-PRODUCT-CONSTITUTION.md](./00-PRODUCT-CONSTITUTION.md)
+
+   固定产品身份、内核、永久边界、v1 完成条件、真实项目规则、需求分类和阶段停止规则。动态的当前事实、授权和下一步由 `PROJECT_STATE.json` 唯一记录；其他文档与宪法冲突时，以宪法为准。
+
+## 支持性设计文档
+
+1. [01-PRODUCT-CORE.md](./01-PRODUCT-CORE.md)
+
+   定义用户问题、产品核心、长期资产、成功标准和非目标。
+
+2. [02-MARKET-BOUNDARY.md](./02-MARKET-BOUNDARY.md)
+
+   定义哪些能力直接采用 Kiro、Ruler、Rulesync、Spec Kit 和成熟 Coding Agent，哪些差异才允许自研。
+
+3. [03-FINAL-SOLUTION.md](./03-FINAL-SOLUTION.md)
+
+   冻结 Project Contract、Context Compiler、投影和漂移检查组成的最终产品方案。
+
+4. [04-PROGRAM-DESIGN.md](./04-PROGRAM-DESIGN.md)
+
+   在产品方案之后给出 v1 可实现的程序结构、文件合同、命令和安全写入规则。
+
+5. [05-ACCEPTANCE-CONTRACT.md](./05-ACCEPTANCE-CONTRACT.md)
+
+   记录程序验收、团队维护验收结果和真实价值验收设计；当前完成门槛以产品宪法第 7 节为准。
+
+6. [08-INSTALLATION-AND-DISTRIBUTION.md](./08-INSTALLATION-AND-DISTRIBUTION.md)
+
+   定义项目内安装、静态投影、团队分发和后续发布边界；具体 v1 CLI 合同以 04 为准。
+
+7. [11-V1-AUTHORING-CLOSURE-DESIGN.md](./11-V1-AUTHORING-CLOSURE-DESIGN.md)
+
+   记录 v1 authoring 闭环的冻结方案与本地实现结果：通用来源登记、scoped item 提案、显式批准、完整 bundle 内容、安全写入、兼容性和 A-15 至 A-20 验收。
+
+8. [12-KNOWLEDGE-MAINTENANCE-CLOSURE-ROADMAP.md](./12-KNOWLEDGE-MAINTENANCE-CLOSURE-ROADMAP.md)
+
+   记录 `0.7.0` 冻结设计、本地实现与团队维护验收结果：来源变化审查与显式接受、影响集、同 ID revision、deprecation、pending reapproval、原子性、错误、`0.6.1` 兼容和 A-21 至 A-30。文末衔接已完成的 `0.8.0` 只读治理看板。
+
+9. [13-READ-ONLY-GOVERNANCE-DASHBOARD-DESIGN.md](./13-READ-ONLY-GOVERNANCE-DASHBOARD-DESIGN.md)
+
+   记录 `0.8.0` 只读治理看板冻结设计、`0.9.0` 派生数据精简，以及 source lifecycle 后的 View Model schema 3：六个视图、HTML/JSON stdout、安全、无障碍、兼容和 A-31 至 A-38。
+
+10. [14-FORMAL-RELEASE-READINESS.md](./14-FORMAL-RELEASE-READINESS.md)
+
+    冻结 `frontend-project-context@1.0.0` 的包边界、项目接入、CI、迁移与 A-39；source lifecycle 保持条件已关闭，public npm 已授权、完成配置并验证发布者身份。
+
+11. [15-SOURCE-LIFECYCLE-CLOSURE-DESIGN.md](./15-SOURCE-LIFECYCLE-CLOSURE-DESIGN.md)
+
+    记录首次公开发布前来源生命周期修补的冻结设计与本地实现：处理来源删除、搬迁和永久退役，不自动接受、批准或修复；A-40 至 A-45 已通过。
+
+## 历史证据
+
+12. [06-HISTORICAL-PROTOTYPE.md](./06-HISTORICAL-PROTOTYPE.md)
+13. [07-REAL-TASK-EVIDENCE.md](./07-REAL-TASK-EVIDENCE.md)
+
+历史文档只解释为什么不再建设任务执行 Harness。它们不是程序需求、工作流或授权来源。
+
+## Beta 证据
+
+14. [09-B0-DTG-TMC-MOBILE.md](./09-B0-DTG-TMC-MOBILE.md)
+
+   记录首次真实项目只读接入、通用修补和同项目回归。报告中的历史“下一步”不再产生新需求。
+
+15. [10-B0-DTG-TMC-PC.md](./10-B0-DTG-TMC-PC.md)
+
+   记录第二个真实项目只读接入和跨项目对比：核心链路与首轮通用修补再次通过。产品宪法已经停止继续寻找项目和扩充技术发现白名单。
+
+机器状态见 [PROJECT_STATE.json](../PROJECT_STATE.json)。新窗口先读取产品宪法，再读取 [RTK.md](../RTK.md)。

package/examples/README.md

@@ -0,0 +1,17 @@
+# 最小团队接入示例
+
+包实际发布后，把 [package.json](./package.json) 中的脚本和 devDependency 合并到项目，并把 [project-context-check.yml](./project-context-check.yml) 复制到 `.github/workflows/project-context-check.yml`。
+
+维护者首次初始化：
+
+```bash
+npm run context:init -- --id my-project --name "My Project" --write
+```
+
+团队和 CI 的只读 Gate：
+
+```bash
+npm run context:check
+```
+
+应提交 `.project-context/contract.json`、`.project-context/sources.lock.json`、`.project-context/projections.lock.json` 和团队明确采用的受管投影。不要提交 proposal、dashboard HTML、tarball、node_modules 或临时 Context Bundle。

package/examples/package.json

@@ -0,0 +1,11 @@
+{
+  "private": true,
+  "scripts": {
+    "context:init": "project-context init --project .",
+    "context:check": "project-context check --project .",
+    "context:dashboard": "project-context dashboard --project ."
+  },
+  "devDependencies": {
+    "frontend-project-context": "1.0.0"
+  }
+}

package/examples/project-context-check.yml

@@ -0,0 +1,22 @@
+name: Project Context
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - run: npm ci
+      - run: npm run context:check

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "frontend-project-context",
+  "version": "1.0.0",
+  "description": "Project-local, model-neutral context governance and compilation for AI coding tools.",
+  "private": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "license": "Apache-2.0",
+  "type": "module",
+  "files": [
+    "bin/",
+    "src/",
+    "docs/",
+    "examples/",
+    "CHANGELOG.md",
+    "UPGRADING.md",
+    "PROJECT_STATE.json",
+    "RTK.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "bin": {
+    "project-context": "./bin/project-context.mjs"
+  },
+  "scripts": {
+    "check": "node --check bin/project-context.mjs && node --test test/project-context test/release",
+    "test": "node --test test/project-context test/release",
+    "prepack": "npm run check"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "ai-coding",
+    "context-governance",
+    "project-contract"
+  ]
+}

package/src/project-context/approver.mjs

@@ -0,0 +1,177 @@
+import { canonicalJson } from "./canonical-json.mjs";
+import {
+  sourceForContract,
+  sourceRegistrationShape,
+  sourceStatus,
+  validateContract,
+  validateProposal,
+  validateSourceLock,
+} from "./contract-schema.mjs";
+import { fail } from "./errors.mjs";
+import { writeProjectState } from "./project-store.mjs";
+import { readSourceDigest } from "./source-reader.mjs";
+import { findConflicts, validateOverrides } from "./scope-compiler.mjs";
+
+function sameScope(left, right) {
+  return left.kind === right.kind && (left.path ?? ".") === (right.path ?? ".");
+}
+
+function approval(options, timestamp) {
+  return {
+    by: options.by,
+    at: timestamp,
+    ...(options.rationale !== undefined ? { rationale: options.rationale } : {}),
+  };
+}
+
+function preflightContract(nextContract) {
+  validateContract(nextContract);
+  const findings = [...validateOverrides(nextContract.items), ...findConflicts(nextContract.items)];
+  if (findings.length > 0) {
+    fail("approval-preflight-failed", "approval would create invalid scope overrides or unresolved contract conflicts", {
+      exitCode: 1,
+      details: { findings },
+    });
+  }
+}
+
+export async function approveProposal(root, project, proposalInput, options) {
+  const proposal = validateProposal(structuredClone(proposalInput));
+  if (proposal.projectId !== project.contract.project.id) {
+    fail("proposal-project-mismatch", "proposal belongs to a different project");
+  }
+  const ids = [...new Set(options.ids)];
+  if (ids.length !== options.ids.length) fail("approval-id-duplicate", "approval IDs must be unique");
+  const proposedById = new Map(proposal.items.map((item) => [item.id, item]));
+  for (const id of ids) {
+    if (!proposedById.has(id)) fail("proposal-id-missing", `proposal does not contain item: ${id}`);
+  }
+  const selected = ids.map((id) => proposedById.get(id));
+  const selectedSourceIds = new Set(selected.flatMap((item) => item.sources));
+  const proposalSources = new Map(proposal.sources.map((source) => [source.id, source]));
+  for (const sourceId of selectedSourceIds) {
+    const source = proposalSources.get(sourceId);
+    if (!source) fail("proposal-source-missing", `proposal source is missing: ${sourceId}`);
+    const actual = await readSourceDigest(root, source);
+    if (actual !== null && actual !== source.digest) {
+      fail("proposal-source-changed", `source changed after discovery: ${sourceId}`, {
+        exitCode: 1,
+        details: { source: sourceId, expected: source.digest, actual },
+      });
+    }
+  }
+  const nextContract = structuredClone(project.contract);
+  for (const sourceId of selectedSourceIds) {
+    const source = proposalSources.get(sourceId);
+    const existing = nextContract.sources.find((entry) => entry.id === sourceId);
+    if (existing && (
+      sourceStatus(existing) === "deprecated" ||
+      canonicalJson(sourceRegistrationShape(existing)) !== canonicalJson(source)
+    )) {
+      fail("source-id-conflict", `source ID conflicts with contract: ${sourceId}`);
+    }
+    if (!existing) nextContract.sources.push(sourceForContract(source, nextContract.schemaVersion));
+  }
+  const timestamp = options.at ?? new Date().toISOString();
+  for (const item of selected) {
+    const sameSubjectAndScope = nextContract.items.find(
+      (entry) => entry.id !== item.id && entry.subject === item.subject && sameScope(entry.scope, item.scope) && entry.status === "approved",
+    );
+    if (sameSubjectAndScope) {
+      fail("subject-scope-conflict", `approved item already owns subject and scope: ${item.subject}`, {
+        details: { existing: sameSubjectAndScope.id, proposed: item.id },
+      });
+    }
+    const approved = {
+      ...structuredClone(item),
+      status: "approved",
+      approval: approval(options, timestamp),
+    };
+    const index = nextContract.items.findIndex((entry) => entry.id === approved.id);
+    if (index === -1) nextContract.items.push(approved);
+    else fail("item-id-conflict", `item ID already exists; use revise for governed replacement: ${approved.id}`);
+  }
+  nextContract.sources.sort((left, right) => left.id.localeCompare(right.id));
+  nextContract.items.sort((left, right) => left.id.localeCompare(right.id));
+  preflightContract(nextContract);
+  const confirmedSources = new Map(project.sourcesLock.sources.map((entry) => [entry.id, entry.digest]));
+  for (const sourceId of selectedSourceIds) {
+    const source = proposalSources.get(sourceId);
+    if (typeof source.digest === "string") confirmedSources.set(source.id, source.digest);
+  }
+  const nextSourcesLock = {
+    schemaVersion: 1,
+    sources: [...confirmedSources].map(([id, digest]) => ({ id, digest })).sort((left, right) => left.id.localeCompare(right.id)),
+  };
+  validateSourceLock(nextSourcesLock);
+  if (options.write) {
+    await writeProjectState(project, nextContract, nextSourcesLock);
+  }
+  return { contract: nextContract, sourcesLock: nextSourcesLock, approvedIds: ids, written: Boolean(options.write) };
+}
+
+export async function approvePendingItems(root, project, options) {
+  const ids = [...new Set(options.ids)];
+  if (ids.length !== options.ids.length) fail("approval-id-duplicate", "approval IDs must be unique");
+  const itemsById = new Map(project.contract.items.map((item) => [item.id, item]));
+  const selected = ids.map((id) => {
+    const item = itemsById.get(id);
+    if (!item) fail("item-not-found", `contract item does not exist: ${id}`, { details: { item: id } });
+    if (item.status !== "proposed") {
+      fail("item-not-pending", `contract item is not pending approval: ${id}`, {
+        details: { item: id, status: item.status },
+      });
+    }
+    return item;
+  });
+
+  const sourceIds = new Set(selected.flatMap((item) => [
+    ...item.sources,
+    ...(item.verification?.source ? [item.verification.source] : []),
+  ]));
+  const sourcesById = new Map(project.contract.sources.map((source) => [source.id, source]));
+  const locksById = new Map(project.sourcesLock.sources.map((entry) => [entry.id, entry.digest]));
+  for (const sourceId of sourceIds) {
+    const source = sourcesById.get(sourceId);
+    if (!source) fail("source-reference-missing", `pending item references unknown source: ${sourceId}`);
+    if (sourceStatus(source) === "deprecated") {
+      fail("source-reference-deprecated", `pending item references deprecated source: ${sourceId}`, {
+        details: { source: sourceId },
+      });
+    }
+    let actual;
+    try {
+      actual = await readSourceDigest(root, source);
+    } catch (error) {
+      fail("pending-source-changed", `pending item source is unavailable: ${sourceId}`, {
+        exitCode: 1,
+        details: { source: sourceId, reason: error.code ?? "unreadable" },
+      });
+    }
+    if (actual === null) continue;
+    const locked = locksById.get(sourceId);
+    if (!locked || locked !== source.digest || actual !== source.digest) {
+      fail("pending-source-changed", `pending item source is not at its accepted checkpoint: ${sourceId}`, {
+        exitCode: 1,
+        details: { source: sourceId, contract: source.digest, locked: locked ?? null, actual },
+      });
+    }
+  }
+
+  const timestamp = options.at ?? new Date().toISOString();
+  const selectedIds = new Set(ids);
+  const nextContract = structuredClone(project.contract);
+  nextContract.items = nextContract.items.map((item) => selectedIds.has(item.id)
+    ? { ...item, status: "approved", approval: approval(options, timestamp) }
+    : item);
+  nextContract.items.sort((left, right) => left.id.localeCompare(right.id));
+  preflightContract(nextContract);
+  if (options.write) await writeProjectState(project, nextContract, project.sourcesLock, options.storeOptions);
+  return {
+    contract: nextContract,
+    sourcesLock: project.sourcesLock,
+    approvedIds: ids,
+    mode: "pending",
+    written: Boolean(options.write),
+  };
+}