docs(architecture): audit managed workspace authorities

docs/architecture/managed-dependency-storage-authority-v1.zh-CN.md

@@ -1,7 +1,8 @@
 ---
 document_status: implementation-contract
-status: draft-stacked-foundation
+status: merged-stacked-foundation
 date: 2026-08-08
+last_verified: 2026-09-04
 milestone: M1.3-storage-authority
 base: upstream/main@08bcf324b
 ---
@@ -28,23 +29,25 @@ base: upstream/main@08bcf324b
 
 跟踪：[Managed dependencies #4326](https://github.com/apache/maka/issues/4326)
 
-## 1. 本 PR 只证明一个不变量
+## 1. 当前 foundation 只证明一个不变量
 
 > 同一个 canonical dependency environment identity 最多对应一棵由 Maka 发布、由 artifact 权限域之外的 durable receipt 证明、可在崩溃后收敛重开的依赖树；任何身份、路径、内容或平台证据不可证明时 fail closed。
 
-本 PR 的 owner 是 `ManagedDependencyEnvironmentAuthority`。它拥有 environment identity、artifact publication、SQLite receipt、lease、pending reservation 与 GC。注入的 producer 只获得一次性 staging 中的 `outputRoot` 与 `scratchRoot`，不获得 storage root、canonical artifact path 或 receipt database。
+当前实现的 owner 是 `ManagedDependencyEnvironmentAuthority`。它拥有 environment identity、artifact publication、SQLite receipt、lease、pending reservation 与 GC。注入的 producer 只获得一次性 staging 中的 `outputRoot` 与 `scratchRoot`，不获得 storage root、canonical artifact path 或 receipt database。
 
 同一个 canonical storage root 在同一时刻只能存在一个该 authority：同进程由 module-private owner claim 拒绝重复实例，跨进程由稳定 lock artifact 上的 OS exclusive lock 拒绝第二个 owner。lock 在 receipt database 或 artifact 被读取、修复、发布、租用、GC 之前取得，只在 authority 完整关闭或初始化失败时释放；active lease 导致的 close 拒绝不会释放 owner。
 
-本 PR 不包含：
+当前实现不包含：
 
 - bundled npm 的实现与网络策略；
 - `node_modules/.bin` symlink 的 producer 配额扫描；
 - workspace execution owner/worker logical binding；
 - Desktop/CLI/Runtime Host 接线；
 - release packaging、audit 或 SBOM。
 
-因此该 PR 是 stacked foundation，在出现下一个生产 owner consumer 前保持 Draft；不得单独宣称 M1.3 用户能力闭环。
+实现已由 [#2485](https://github.com/apache/maka/pull/2485) 合并，但仍是没有生产 consumer 的 stacked
+foundation；后续接线由 [#4326](https://github.com/apache/maka/issues/4326) 跟踪，不得单独宣称 M1.3
+用户能力闭环。
 
 ## 2. 权威与原子性边界
 
@@ -61,7 +64,7 @@ canonical identity validation
   -> process owner claim + cross-process OS lock
   -> pending reservation
   -> producer-owned random staging
-  -> producer provision resolves (PR 2 must prove its process tree has exited)
+  -> producer provision resolves (the future producer slice must prove its process tree has exited)
   -> deep-copy node_modules into new authority-owned inodes
   -> delete the producer-owned tree
   -> one authoritative tree seal:
@@ -104,7 +107,7 @@ Windows 上只读 dependency file 是合法输入。authority 只在自己的 un
 - acquire 开始即安装 pending reservation，直到正式 lease 建立或失败清理；GC 不得删除 pending/inflight/leased digest。
 - cache cost 为内容字节数加每个 entry 的固定治理成本，避免大量空文件绕过软配额。
 - GC 串行执行；一次 GC rejection 可报告给当前调用者，但不能永久毒化后续 GC task chain。
-- authority startup 遇到 malformed receipt 或 unowned cache entry 时整体 fail closed。Quarantine 会引入新的 durable lifecycle，不在本 PR 静默增加。
+- authority startup 遇到 malformed receipt 或 unowned cache entry 时整体 fail closed。Quarantine 会引入新的 durable lifecycle，不在本 authority 静默增加。
 
 ## 5. Crash 与对抗矩阵
 
@@ -155,13 +158,15 @@ Windows 上只读 dependency file 是合法输入。authority 只在自己的 un
 | `9a42a761c` | `fix(runtime-host): transport packaged dependency authority` | PR 4     | Desktop/CLI/Runtime Host 生命周期与关闭顺序                              |
 | `980143a3b` | `docs(architecture): split M1.3 authority boundaries`  | 文档证据 | 不迁移旧总文档；由每个平铺 PR 维护自己的 owner/rollback 合同             |
 
-后续平铺顺序固定为：
+原定平铺边界现在由 #2485 与 #4326 记录：
 
-1. PR 1：本文件定义的 storage authority；
-2. PR 2：producer boundary，必须证明 producer 进程树退出后 `provision()` 才 resolve，并包含真实 npm `.bin` symlink 的配额与取消/超时测试；
-3. PR 3：bundled npm runtime 供应链、发布审计与许可证材料；
-4. PR 4：唯一生产 consumer，把真实 baseline、environment lease 和 Read/Glob/Grep worker 串成闭环。
+1. 已合并 #2485：本文件定义的 storage authority；
+2. 待 #4326：producer boundary，必须证明 producer 进程树退出后 `provision()` 才 resolve，并包含真实 npm `.bin` symlink 的配额与取消/超时测试；
+3. 待 #4326：bundled npm runtime 供应链、发布审计与许可证材料；
+4. 待 #4326：唯一生产 consumer，把真实 baseline、environment lease 和 Read/Glob/Grep worker 串成闭环。
 
-PR 1–3 只是堆叠地基；PR 4 合并前不能把 M1.3 描述为用户可用。PR 2 不得通过拒绝所有 POSIX symlink 规避 `.bin`：producer inventory 应计量合法 link，最终 storage authority 与 worker 仍负责 target containment；Windows 继续拒绝 reparse point。
+Storage authority 与后续 producer/supply-chain 切片都只是堆叠地基；生产 consumer 合并前不能把 M1.3
+描述为用户可用。Producer slice 不得通过拒绝所有 POSIX symlink 规避 `.bin`：producer inventory 应计量
+合法 link，最终 storage authority 与 worker 仍负责 target containment；Windows 继续拒绝 reparse point。
 
-验证时必须执行 storage build、focused authority tests、真实 Windows ADS test，以及三个 child-process crash failpoint。后续 PR 不得通过放宽本 authority 的 fail-closed 规则来提高采用率。
+验证时必须执行 storage build、focused authority tests、真实 Windows ADS test，以及四个 child-process crash failpoint。后续 PR 不得通过放宽本 authority 的 fail-closed 规则来提高采用率。

docs/architecture/runtime-workspace-version-authority-v1.zh-CN.md

@@ -19,12 +19,12 @@
 
 # Workspace Version Authority v1：Baseline 事实权威
 
-- 状态：authority foundation 已合并；schema 9 reader/migration、RuntimeEvents、projection reader/rebuild 继续受支持，当前没有生产 baseline writer consumer
-- 更新日期：2026-08-29
+- 状态：authority foundation 已合并；当前 schema 15 继续支持 baseline facts、root binding、successor/mutation facts 与 projection reader/rebuild，仍没有生产 baseline 或 mutation consumer
+- 更新日期：2026-09-04
 - 主要不变量：经专用 writer 提交的一个 workspace epoch，其 baseline canonical facts 与三个 SQLite projection 对外只能全可见或全不可见
 - 事实权威：immutable RuntimeEvents
 - artifact owner：后续 Gitoxide data plane；本切片不执行 Git 命令
-- 主要发布证明平台：Linux、macOS；Windows 当前仅验证 SQLite 事务与多进程路径
+- 主要发布证明平台：Linux CI 与 Windows recovery gate；macOS 当前没有独立 recovery gate
 
 ## 1. 本切片为什么存在
 
@@ -47,8 +47,10 @@ epoch opened RuntimeEvent
 可删除、可重建、每次读取都要与 canonical facts 交叉验证的 projection。若维护操作或外部损坏只删除
 projection，公开 reader 会 fail closed，直到显式 rebuild；这种损坏态不被伪装成合法的“全不可见”。
 
-本节定义的 baseline transaction 只接受 baseline；独立的 successor/mutation authority extension 不属于这个
-历史切片。它不创建 internal repository、不创建 worktree、不调用工具，也不改变 Desktop/CLI 行为。
+本节定义的 baseline transaction 只接受 baseline；后续实现的
+[`Managed Mutation Lifecycle Authority v1`](./runtime-managed-workspace-mutation-lifecycle-authority-v1.zh-CN.md)
+独立拥有 successor/mutation extension，不属于这个历史切片。两者当前都不创建 internal repository、
+不创建 worktree，也不改变 Desktop/CLI 行为。
 
 authority slice 本身只证明事实合同、SQLite 原子写入与 projection 可重建性。旧 Git-CLI-shaped
 Baseline Open composition 从未获得生产调用方，现已删除；后续生产 writer 必须由 Gitoxide data plane
@@ -60,16 +62,16 @@ policy hash 都不构成证据。
 | 项目 | 决策 |
 |---|---|
 | 协议 owner | `@maka/core` 的 strict fact contract 与 pure scanner |
-| baseline 写入 owner | storage-internal WeakMap writer；不属于 package API，当前没有 production baseline producer；独立 successor/mutation writer 不由旧 owner 提供 |
+| 写入 owner | baseline 与 successor/mutation writer 都是 storage-internal seam，不属于 package API；当前没有 production producer/consumer |
 | 原子性边界 | 单个 `BEGIN IMMEDIATE ... COMMIT` SQLite transaction |
 | canonical source | store-owned authority stream 中的两条 immutable RuntimeEvents |
 | disposable state | `runtime_workspace_epochs`、`runtime_workspace_versions`、`runtime_workspace_heads` |
 | 正常失败 | exact retry 返回 existing；payload/identity drift 返回 conflict |
 | 损坏失败 | malformed fact、orphan、projection mismatch、partial snapshot 污染全部 fail closed |
 | 运行时回滚 | 事务未提交时五部分全部回滚；已提交时五部分全部可读 |
-| 版本回滚 | schema 9 数据库不能由只支持 schema 8 的旧 binary 打开；降级必须使用升级前备份 |
+| 版本回滚 | 当前 schema 15 数据库不能由只支持旧 schema 的 binary 打开；降级必须使用升级前备份 |
 
-逻辑回滚可以停止调用本 writer，但必须保留 schema 9 reader/migration；不能通过删除 capability marker
+逻辑回滚可以停止调用本 writer，但必须保留 schema 7/9 及后续 reader/migration；不能通过删除 capability marker
 伪装成旧格式。
 
 ## 3. Authority stream
@@ -195,30 +197,34 @@ event，因此 caller 没有机会夹带另一条 semantic lane。该 seam 所
 
 ## 6. Baseline writer 状态
 
-`commitWorkspaceBaselineInternal` 继续作为 schema 9 authority 的 storage-internal 测试 seam，用于证明
+`commitWorkspaceBaselineInternal` 继续作为当前 schema 15 中 root-bound baseline authority 的
+storage-internal 测试 seam，用于证明
 atomic bundle、exact retry、conflict、crash rollback 与 projection rebuild。旧 Git executable receipt →
 writer composition 已删除；后续 Gitoxide producer 必须重新建立 artifact admission，不能复用或恢复旧
 owner、receipt 或 worktree materialization path。
 
-## 7. Schema 7–8 与 projection
+## 7. Schema 7–15 与 projection
 
 Schema 7 从 schema 6 增加 workspace authority facts/projections 并写入 capability：
 
 ```text
 runtime_workspace_version_authority @ 1
 ```
 
-三张 projection：
+三张 workspace version projection、一张 active mutation reservation projection，以及 durable root binding：
 
 | 表 | 含义 |
 |---|---|
 | `runtime_workspace_epochs` | epoch identity、source 与 materialization policy |
-| `runtime_workspace_versions` | accepted baseline commit/tree 与因果引用 |
-| `runtime_workspace_heads` | 当前 epoch head；M0 必须等于 baseline |
+| `runtime_workspace_versions` | accepted baseline 与 schema 13 起的 tool-mutation successor commit/tree 及因果引用 |
+| `runtime_workspace_heads` | 当前 epoch head；baseline 从 revision 1 开始，successor 接受后递增 |
+| `runtime_managed_mutation_reservations` | schema 14 起的 active T1 reservation；由 managed-mutation facts 重建，terminal 或 successor 接受后释放 |
 | `runtime_storage_root_binding` | singleton durable rootId；阻止单独复制/移动 `runtime.sqlite` 后被另一 storage root 静默认领 |
 
 Schema 9 增加 `runtime_storage_root_binding(singleton=1, root_id, protocol_version=1)`。当时 schema 8 仍含
-旧 Eval harness 的 event table；schema 12 已删除该表。M0 在任何
+旧 Eval harness 的 event table；schema 12 已删除该表。Schema 13 扩展 version projection 以接受
+`tool_mutation` successor，schema 14 增加 `changed_paths_json` 与 durable mutation reservation，schema 15
+只扩展 continuation projection，不改变 workspace fact 合同。Baseline writer 在任何
 workspace fact 写入前，通过 storage-internal binder 将它绑定到 authenticated root owner 的 durable
 `rootId`；已绑定数据库只接受 exact rootId。没有 binding 但已经含任何 Session、RuntimeEvent、claim 或
 workspace fact 等逻辑数据的实验数据库必须显式 adopt/清理，不能自动认领；只有除 schema/capability metadata
@@ -232,13 +238,14 @@ workspace fact 等逻辑数据的实验数据库必须显式 adopt/清理，不
 构造 store 时缺少 capability、capability 版本未知或数据库 schema 比 binary 新，全部拒绝打开；不静默
 降级到 JSONL 或无 authority 模式。
 
-读取 epoch/version/head 时，store 先从全部 immutable RuntimeEvents 重建 canonical baseline 集合，再与
-三张 projection 做完整比较。整次 canonical scan、projection compare 与目标 lookup 必须位于同一个
+读取 epoch/version/head 或 active mutation reservation 时，store 先从全部 immutable RuntimeEvents 重建
+canonical workspace ledger，包括 baseline、所有 causal successor 与 managed mutation T1/terminal facts，再与
+四张 projection 做完整比较。整次 canonical scan、projection compare 与目标 lookup 必须位于同一个
 SQLite read transaction/snapshot；否则并发 writer 可能让读者拼接两个合法时刻并误报 corruption。
 不能只信 projection，也不能用冗余 `event_kind` 过滤 canonical rows。
 
-显式 rebuild 先在内存中严格扫描所有事实，只有 canonical ledger 完整时才在一个事务中替换 projection。
-扫描失败不会先清空旧 projection；事务插入失败也会保留旧状态。
+显式 rebuild 先在内存中严格扫描所有事实，只有 canonical ledger 完整时才在一个事务中替换 epoch、version、
+head 与 active mutation reservation projection。扫描失败不会先清空旧 projection；事务插入失败也会保留旧状态。
 
 ## 8. 幂等、并发与 crash matrix
 
@@ -248,7 +255,8 @@ SQLite read transaction/snapshot；否则并发 writer 可能让读者拼接两
 | 两进程提交相同 baseline | 一个 created、一个 existing |
 | 两进程提交冲突 baseline | 只接受一个；另一个 conflict |
 | reader 扫描期间另一进程提交 baseline | reader 在旧 snapshot 返回 absent；下一次读取看到完整 baseline |
-| schema 6/7 两进程同时升级 | 在 migration lock 内重读版本，每个 pending migration 只执行一次 |
+| schema 10 两进程同时升级到 current | 在 migration lock 内重读版本，每个 pending migration 只执行一次 |
+| populated schema 12 升级到 current 后提交 successor | 保留 baseline，并接受 successor、递增 head revision |
 | epoch event insert 后崩溃 | facts/projections 全无 |
 | version event insert 后崩溃 | facts/projections 全无 |
 | epoch projection insert 后崩溃 | facts/projections 全无 |
@@ -260,17 +268,18 @@ SQLite read transaction/snapshot；否则并发 writer 可能让读者拼接两
 | authority partial snapshot 出现 | fail closed，不把 mutable state 当 canonical fact |
 
 事务内五个 failpoint 已有定向 rollback 测试。真实子进程 kill harness 覆盖“事务内被杀”和“commit
-后被杀”；它在 Linux/macOS CI 承担发布证明，Windows 本地不反向宣称同等 crash durability。
+后被杀”；Linux CI 与 Windows recovery gate 都运行该 suite。macOS 当前没有独立 recovery gate，
+不能仅凭跨平台代码反向宣称同等恢复证据。
 
 ## 9. 平台能力矩阵
 
 | 能力 | Linux | macOS | Windows |
 |---|---|---|---|
 | strict fact/lane | 支持 | 支持 | 支持 |
-| SQLite bundle 原子性 | 支持 | 支持 | 支持 |
-| 多进程 exact/conflict arbitration | 支持 | 支持 | 已有定向测试 |
-| schema 6/7→8 并发升级 | 支持 | 支持 | 已有定向测试 |
-| 真实 SIGKILL crash harness | 发布门槛 | 发布门槛 | 当前不承诺 |
+| SQLite bundle 原子性 | 支持 | 实现预期；无独立 recovery gate | 支持 |
+| 多进程 exact/conflict arbitration | 支持 | 实现预期；无独立 recovery gate | recovery/baseline gate |
+| schema 10→current 并发升级 | 支持 | 实现预期；无独立 recovery gate | recovery/baseline gate |
+| 真实进程终止 crash harness | Linux CI | 当前无独立 recovery gate | Windows recovery gate |
 | Git object/worktree 语义 | 后续切片 | 后续切片 | 后续能力矩阵 |
 
 本表只描述 authority persistence，不能推导 managed worktree 已跨平台可用。
@@ -289,8 +298,9 @@ SQLite read transaction/snapshot；否则并发 writer 可能让读者拼接两
 - continuation boundary 绑定 workspace version；
 - Desktop/CLI 设置、默认启用或自动恢复。
 
-本文不定义 mutation。Successor/mutation fact 必须由其独立 authority 与真实 Durable Write 的 T1/T2、
-tool outcome 引用、session retention 和 head CAS 一起冻结。
+本文的 baseline transaction 不定义 mutation。Successor/mutation fact 由
+[`Managed Mutation Lifecycle Authority v1`](./runtime-managed-workspace-mutation-lifecycle-authority-v1.zh-CN.md)
+与真实 Durable Write 的 T1/T2、tool outcome 引用、session retention 和 head CAS 一起冻结。
 
 ## 11. 后续生产接线
 
@@ -307,5 +317,5 @@ opaque invocation capability、bounded invocation → opaque repository admissio
 
 这些基础设施尚未建立 signed packaged-release trust root，也没有 Desktop/CLI/T1 消费者，因此不能据此
 恢复 managed mode。后续 production writer 必须从真实 Gitoxide artifact admission 出发，并继续复用本
-文档定义的 schema 9 RuntimeEvents 与 projection authority；接线前仍需先拍板 ignored dependencies/scratch、
+文档定义、并由 schema 13–14 扩展至 successor/mutation 的 RuntimeEvents 与 projection authority；接线前仍需先拍板 ignored dependencies/scratch、
 identity marker、symlink/LFS/submodule/case/filemode 平台政策。