企业官网建设流程全解析

Apache Maka Runtime Resume 恢复权威拆分账本：从 #1346 实验到 PR A/B 不变量驱动的平铺落地

【免费下载链接】makaApache Maka (Incubating) is a high-performance agent workspace that keeps a complete record of everything it did.项目地址: https://gitcode.com/GitHub_Trending/mak/maka

本文以 docs/architecture/runtime-resume-extraction-ledger.zh-CN.md 为主线，系统讲解 Apache Maka（Incubating）如何把大规模运行时恢复（Runtime Resume）实验 #1346 按“一个 PR 证明一个完整不变量”的方式拆解为 PR A–D，逐一重写为可合并、可审计、可被 crash 测试验证的生产级能力。读者将掌握：恢复事实（recovery fact）的原子写入权威、continuation claim 的不可变边界与 store-owned start_kind 语义、以及 SQLite/JSONL 双存储下的 authority gate 与 fail-closed 策略，并能在源码中定位每一层实现与对应测试。

1. 背景：为什么 #1346 不能整体合并

#1346 是 Apache Maka 的 Runtime Resume 设计与集成实验分支（集成实验来源origin/codex/runtime-resume-phase3a@24bb5f33），它包含大量相互耦合的恢复能力原型。生产实现不再把 #1346 当作可合并交付单元，原因有三：

1. 一次合并一个巨型 PR 无法证明任何单一不变量，审查与回滚都不可控；
2. 旧实验 commit 边界与生产不变量并不对齐，机械 cherry-pick 会带入半成品 API 与未定型的语义；
3. #1346 从未发布、没有用户，其 SQLite 数据是一次性实验数据，不值得承诺兼容迁移。

因此生产落地遵循“一个 PR 证明一个完整不变量”的原则，禁止按旧 commit 边界机械 cherry-pick。四个切片的唯一不变量如下：

Phase 3B/4A 的 workspace checkpoint 是后续独立切片，不进入 PR A。

2. 提取规则：平铺分支与黑盒测试先行

文档定义了七条提取规则，核心要点如下：

1. 每个新 PR 从当时最新upstream/main建立平铺分支（flattened branch），即重写历史、不留 merge commit；
2. 先迁移或重写能表达黑盒不变量的测试，再补最小生产代码——测试先行保证不变量可被客观证明；
3. 不 cherry-pick merge commit；
4. 同时跨越两个不变量的旧 commit 只能按 hunk 阅读和手工重写；
5. 不为让旧测试通过而恢复已否决的 public API；
6. 每个 PR 必须执行 path diff、range-diff 和 production-shaped crash tests；
7. PR A–C 合并后关闭 #1346，但保留其讨论作为设计与审查记录。

这套规则的直接产物是四个 PR 各自的文件账本与测试账本，下文逐一展开。

3. PR A：恢复事实的原子写入权威

3.1 保留并重写的能力

PR A 是恢复权威（recovery authority）的最小闭环。它保留了 #1346 中真正有价值的设计，并全部重写为可验证实现，包括：

• 精确的 reconcile-result / recovery-decision v1 schema；
• strict-JSON admissibility 与冻结的 mainline v1 tool args hash bytes；未来的 domain separation 必须由显式 dispatch/hash v2 引入，不能原地改变t1_after_preflight_v1；
• call、dispatch、outcome、reconcile、decision 五条 semantic lane；
• generic append/import 对保留事实的 authority gate；
• 一个 SQLite recovery bundle transaction；
• completed 必须引用同 execution identity 的成功 outcome；
• parked 是 v1 的永久终态，只有 exact bundle retry 幂等；
• tool projection 可以只从 immutable RuntimeEvents 重建；
• mutable partial corruption fail-soft，immutable corruption fail-closed；
• SQL row identity 与 payload identity 交叉校验；
• online、close/reopen、rebuild、Resolver 的黄金等价性（golden equivalence）。

其中两个工程取舍值得特别说明。第一，workspace-wide semantic fail-stop：PR A 首版刻意采用该策略，任一 session 的 canonical tool-ledger corruption 都会阻止该 SQLite workspace 后续所有 tool-bearing boundary，普通非工具事件仍可写——这是 correctness-first 的隔离取舍，不是偶然副作用。第二，SQLite 与 JSONL 共享唯一 lossless canonical RuntimeEvent codec：validator 消费 codec 返回的 event，store 持久化同一次编码返回的稳定 JSON bytes；SQLite 对每个 invocation 强制唯一(sessionId, runId, turnId)execution spine；JSONL immutable append 对 exact retry 物理去重，并在落盘前验证目标 invocation 身份。

3.2 明确不带入 PR A

PR A 刻意排除的项包括：recovery contract registry / observer / reconciler、Write/Edit file checkpoint、continuation planning / claim / provider replay、Desktop/CLI 自动 resume 接线、Git carrier / restricted verifier / retry-reattach 原型，以及 #1346 SQLite 数据迁移、downgrade 或 mixed-version reader。这些能力要么属于 PR B–D，要么直接 defer/drop。

3.3 实验格式断代：fail closed

#1346 从未发布、没有用户，因此 PR A 不猜测兼容，直接断代：

#1346 experimental capability -> unsupported, fail closed mainline schema 4 -> supported migration to schema 5 PR A capability -> runtime_recovery_authority@1 future newer schema -> fail closed

这项决策只删除未发布实验格式的迁移负担，不删除正式 mainline 数据升级责任（mainline schema 4 仍须支持迁移到 schema 5）。

3.4 PR A 文件账本（仓库现状）

文档列出的文件归属与当前仓库一一对应：

• Core：runtime-event.ts（exact recovery fact envelope decoder）、canonical-runtime-event.ts（唯一 lossless decoder 与稳定 bytes owner）、tool-args-identity.ts（strict JSON + mainline v1 hash 兼容）、tool-ledger-scanner.ts（shared lane / duplicate / order / identity scanner）、tool-recovery-fact.ts（truthful observation 与 terminal decision）、tool-recovery-bundle.ts（共享 bundle 与 causal interpreter）；
• Storage：sqlite-runtime-schema.ts（schema 5 +runtime_recovery_authority@1capability，当前 schema 已演进至 18）、sqlite-runtime-store.ts（全局 prospective gate、invocation spine、atomic recovery bundle、projection rebuild）、agent-run-store.ts（JSONL authority gate、header identity 与 immutable exact retry 去重）；
• Runtime：recovery-resolver.ts（只消费共享 scanner/interpreter，不维护第二套 map）、runtime-event-read-model.ts（recovery audit fact 不产生聊天消息）、runtime-commit-sink.ts（使用 core canonical args identity）、runtime-resume.ts（真实 corruption machine code 与 terminal parked）。

3.4.1 源码级解读：tool-recovery-fact.ts 的 v1 schema 与严格校验

packages/core/src/tool-recovery-fact.ts 定义了两种 fact envelope，版本均为 1：

• maka.tool.reconcile_result：携带protocol: 'tool_reconcile_v1'、operationId、observation（取值为matches_expected_state/matches_prior_state/diverged/unreadable）、observationSchema: 'state_identity_v1'与observationDigest: sha256:...；
• maka.tool.recovery_decision：protocol: 'tool_recovery_v1'，分为completed（必须带成功 outcomeEventId）与parked（reasonCode 只能是三种 reconcile 观察对应的 park reason）两种 disposition。

值得注意的实现细节：所有校验函数都使用hasExactKeys（tool-recovery-fact.ts）做精确键集合比对——键个数必须完全相等且逐键匹配，任何多余字段都会导致校验失败，从而保证恢复事实的 payload 形状不可被污染。completed决策必须引用同 execution identity 的成功 outcome，parked是 v1 的永久终态。

3.4.2 源码级解读：tool-args-identity.ts 的 strict JSON 与 mainline v1 hash 兼容

packages/core/src/tool-args-identity.ts 的canonicalToolArgsHash是 T1 边界的身份锚点，其核心设计是“校验与身份序列化刻意分离”：

• stableJsonStringify走 strict JSON 规范化（canonicalizeStrictJson），拒绝undefined、bigint、Date、非有限数字、accessor、自定义 prototype 等一切会产生歧义的取值——否则 provider 与 runtime 并未真正达成一致的参数会碰撞成同一个 hash；
• stringifyMainlineV1ToolArgsIdentity保留 mainline 历史stableHash({ toolName, args })的字节语义，包括：required/enum数组按规范化后字符串排序（见canonicalizeMainlineV1中对parentKey的处理，tool-args-identity.ts），以及显式跳过__proto__键——mainline v1 曾把__proto__赋进普通对象而触发Object.prototype旧 setter，导致该键在序列化字节中缺失；新实现显式跳过以冻结历史字节，而不是改变语义。

同文件中的stripUndefinedDeep（tool-args-identity.ts）处理了 provider 元数据里的undefined字段（如 Anthropiccaller对象中toolId: undefined）：删除undefined键并保留数组空洞为null，使 immutable event 读回后仍与写入时含义一致——这是编码器拒绝非 round-trip 值后的必要前置。

3.5 PR A 测试账本

PR A 的测试覆盖极其密集，涵盖以下类别（对应文档 §5，全部“已覆盖”）：

• core authority test：strict JSON admissibility + mainline v1 hash compatibility、required/enum特殊排序与 ordinary array 的 literal vectors、历史__proto__hash omission、sparse/accessor/custom array identity rejection、semantic lane smuggling、partial/branch-qualified authority；
• storage authority test：generic SQLite/JSONL writer bypass、T1 wrong hash、completed missing/mismatched outcome、completed/parked exact retry、reconcile/outcome/decision exception rollback、populated mainline schema 4 数据、schema 4→5 锁内重读、#1346 capability rejection、immutable row/payload mismatch、corrupt mutable partial、多 operation 交错后 journal/projection rebuild；
• storage process crash test：reconcile/outcome/decision SIGKILL rollback + post-COMMIT（POSIX 覆盖，Windows 有限支持跳过）；
• storage multi-process test：exact/conflicting bundle、多进程 WAL 竞争、schema 4→5 并发升级；
• runtime equivalence test：online = reopen = rebuild = Resolver 黄金等价性、prepared / normal T2 success/error / parked / recovered completion、parked 不再进入 reconcile；
• runtime planner test：parked / orphan corruption 不得产生 safe replay；
• runtime read-model test：audit fact 不产生 message row；
• JSONL storage test：ordinary/tool exact retry 与 conflicting retry、event 与目标 invocation identity、terminal target Run identity。

其中“unrelated session corruption 阻断新 session tool boundary”正是 workspace-wide semantic fail-stop 的测试化身。

4. PR B：continuation 的不可变边界与原子 claim

PR A 合并后（#1521），PR B 从包含 PR A 的upstream/main@e4c6ddbf建立平铺分支（分支名codex/runtime-continuation-correctness），先重写 immutable boundary、lineage replay、claim race 与 provider-call T1 测试，再补最小生产路径。

4.1 PR B 的唯一不变量

continuation 只有在一个版本化的 composite immutable boundary 被执行前重验证并原子 claim 后才能调用 provider；每个 lineage segment 使用同一 replay projection；durable continuation-start 的执行权限由 store-ownedstart_kind决定：只有新写入的runtime_admissionstart 是 provider-call T1；claim_repairstart 只用于零 provider 调用的崩溃收敛，永不授予执行权。

不变量拆为三个已实现层次：

• B1 — immutable boundary 与 replay：物理event_seq、canonical RuntimeEvent bytes、segment digest、ordered manifest、provider replay digest；
• B2 — durable authority 与 provider T1：SQLite unique claim、执行前完整重验证、exact target invocation、store-owned live start、一次性 admission proof/receipt，然后才允许 backend/provider 启动；
• B2.1 — pre-provider crash convergence：claim-only / created-without-start 通过 deterministic repair start + terminal 收敛；normal start/no-terminal 无 owner proof 时只 park。

B3（typed retry/reattach branch）仍然 defer，不进入本 PR。

4.2 源码级解读：runtime-boundary.ts 的边界代数

packages/core/src/runtime-boundary.ts 是 PR B 的核心代数。要点如下：

• Immutable prefix 与 proof：buildImmutableRuntimePrefix/buildImmutableRuntimePrefixProof通过foldImmutableRuntimePrefix（runtime-boundary.ts）单遍折叠事件流，逐条校验：event_seq必须从 1 连续递增（gap 直接抛错）、partial快照被拒绝、每个事件的(sessionId, invocationId, runId, turnId)必须与声明 identity 一致；digest 使用 domain 前缀maka.runtime-prefix.v1与长度前缀（updateLengthPrefixed）哈希，保证字节级可复现；
• Segment 与 cursor：createRuntimeBoundaryCursor（runtime-boundary.ts）要求所有 segment 属于同一 session、runId/invocationId 不重复；允许同一逻辑 Turn 出现连续物理尝试时升级为runtime_boundary_cursor_v2（ContinuationClaimV1.providerProjectionVersion取值 1 | 2，与 model-history.ts 中PROVIDER_REPLAY_PROJECTION_VERSION = 2对应）；
• Claim 的 targetOpening 预冻结：ContinuationClaimV1.targetOpening预先声明目标 invocation 的第一个事件必须携带的 opening fact——continuation 的 start event 同时就是目标 invocation 的 event 1，因此 claim 必须在事前就确定它；
• 唯一规则、单一实现：continuationStartEventMatchesClaim（runtime-boundary.ts）同时被 store（拒绝不匹配的 start）与 runtime（拒绝跨不匹配边界恢复）消费，避免同一谓词的两份拷贝各自放行对方拒绝的边界。它检查start.provenance === startKind、claimId、boundaryDigest、replayManifestDigest、providerProjectionVersion、providerReplayDigest以及 immediateSource 的高水位（source.position.lastEventSeq）——start_kind由此成为 store 行级 authority。

4.3 PR B 文件归属

• Core：runtime-boundary.ts（immutable prefix/segment/composite cursor/claim v1 与 strict decoder）、runtime-event.ts（exactcontinuation_start_v2；payload provenance 是持久化镜像，不可自证执行权限）、runtime-event-store.ts（RuntimeContinuationAuthorityStorecapability）、agent-run.ts（continuation_source_v2header lineage），以及runtime-boundary.test.ts、runtime-event.test.ts、agent-run-continuation-source.test.ts；
• Storage：sqlite-runtime-schema.ts（schema 6 +runtime_continuation_authority@1；claim row 持久化start_kind，SQL CHECK 限定取值runtime_admission/claim_repair，见 sqlite-runtime-schema.ts）、sqlite-runtime-store.ts（prefix 一致性读、latest-source claim transaction、terminal-tail seal、分离的 live/repair start command、原子交叉校验 event/start_event_id/start_kind）、agent-run-store.ts（JSONL 拒绝 continuation-start authority fact；Run admission identity 创建后不可修改），以及sqlite-recovery-concurrency.test.ts与sqlite-recovery-concurrency-child.ts（production-shaped 多进程 claim fixture）；
• Runtime：continuation-replay.ts（每个 lineage segment 的唯一 provider replay materializer）、model-history.ts（冻结PROVIDER_REPLAY_PROJECTION_VERSION）、runtime-resume.ts（immutable lineage planner、V2 replay-edge 与历史 claim authority 校验）、runtime-kernel.ts（immediate-source latest 重验、exact tool equality、原子 claim、provider T1 顺序；continuation dispatch fail closed，仅消费合法的一次性 start proof）、runtime-continuation-admission.ts（opaque、runner-bound、one-shot start proof/receipt）、session-manager.ts（claim-only saga、branch/revision 创建前 preflight）、runtime-event-read-model.ts（continuation-start 是消息不可见的 canonical audit fact）；
• UI 与文档：runtime-resume-copy.ts（claim repair / started-indeterminate / authority unavailable 文案）、本 extraction ledger、Phase 3–4 设计文档。

4.4 PR B 已覆盖测试要点

文档 §8.3 列出了完整的 crash/race 矩阵，代表性场景包括：

• fail closed 类：event_seqgap、identity drift、mutable partial、伪造 digest/position；cycle / lineage depth / missing ancestor 稳定 park；V2 ancestor 的 claim row 缺失或未绑定 target/start 报runtime_lineage_claim_mismatch；
• replay 正确性类：canonical-equivalent JSON 产生同 prefix digest；ancestor segment 顺序改变则 manifest digest 改变；interrupted text/thinking suffix 截到最近 user/tool stable boundary；A→B→C continuation 中 A 被裁掉的 suffix 不会在 C 重现；unmatched call 后仍有 provider-visible 内容时报provider_replay_non_suffix_gap；
• claim 原子性类：两进程同时 claim 同一 boundary 时 1 acquired + 1 existing；claim insert 后事务失败则无 durable claim；start event insert 后事务失败则 claim 保留、target prefix 为空；immediate source terminal 后有后缀或存在多个 terminal 时 claim fail closed；
• start_kind 权威类：live start 的 T1 marker 与 Runner 不一致时 one-shot proof/receipt 拒绝 provider admission；claim-only / created-without-start reopen 走 deterministic repair（provider 0 次）；normal start/no-terminal reopen 报continuation_started_indeterminate且不伪造 terminal；
• SIGKILL 崩溃矩阵：claim committed / target Run created / live start committed / terminal RuntimeEvent committed / terminal header committed 五个 durable boundary 逐一覆盖，reopen 后稳定分类，live start/no-terminal 保守 park。

4.5 诚实的 production scope 边界

文档明确要求区分已覆盖与未覆盖：

• authority-capableSessionManager + SqliteRuntimeStore的协议与 production-shaped 路径已覆盖；
• runtime-host 的 execution-store facade 当前仍以 file RuntimeEvent store 为主，尚未拥有 B2 continuation authority；其 SQLite authority/owner 接线进入 PR D；
• hosted child provider RateLimit retry 入口已删除；历史linked_child_resume/linked_child_provider_retrydescriptor 只在 startup recovery 中收敛为 durable terminal fact（provider 调用 0 次）；早期legacy_provider_retry兼容 lane 也已移除；
• 在上述 composition/owner 测试完成前，不能把当前切片描述为 hosted auto-resume 已默认可用，当前也不存在 child provider retry 的 live 或降级准入路径。

4.6 PR B 验证记录

2026-07-28 在 Windows 有限支持环境完成（文档 §8.5）：

• Core boundary/decoder/AgentRun V2 定向集合：54/54；
• Storage SQLite schema/claim/start/terminal/concurrency 定向集合：43/43；
• Runtime continuation/replay/admission/planner 定向集合：46/46；
• SessionManager continuation、authority、branch-preflight 与 upstream 冲突回归：25/25；
• 真实进程 SIGKILL crash harness：1/1；
• Core、Storage、Runtime、UI 构建全部通过；UI resume copy：4/4。

文档特别强调：这些结果只证明本切片受影响路径，不把未运行的全仓测试描述为“已完整覆盖”。最终 schema 支持已发布 mainline v5 → v6 的 populated RuntimeEvent 升级；#1346 与本分支中途产生的未发布实验 schema 6 不承诺兼容，可备份后清理。

5. 平铺与审计：range-diff 与合并门槛

5.1 提交前审计命令

git diff --name-status upstream/main...HEAD git log --no-merges --name-only upstream/main..HEAD git range-diff upstream/main..codex/runtime-recovery-authority upstream/main..HEAD git diff --stat codex/runtime-recovery-authority HEAD -- <PR-A-owned-paths>

range-diff 的目标不是伪造 commit 等价，而是确认旧实现中的有效场景都有明确去向。路径审计必须证明 PR A 没带入 file checkpoint、continuation 或 host lifecycle。

2026-07-27 审计结果：旧 PR A 的 8 个 commit 全部显示为 removed；新平铺 PR A 最初的 4 个实现 commit 与后续 10 个审查收敛 commit 全部显示为 added；没有 commit 被错误标记为等价 cherry-pick。分支已再次重放到upstream/main@466f238b，唯一内容冲突位于 Desktop settings E2E（保留上游更精确的三按钮 permission fixture）。

5.2 合并门槛

• core、storage、runtime build 通过；PR A 定向测试全部通过；三个包完整测试通过（或明确记录与改动无关的平台既有失败）；
• SQLite transaction crash matrix 通过；
• 所有成功接受的 tool-bearing transition 均满足scan.hasCorruption === false；
• JSONL exact retry 不增加物理行，冲突 retry 不改变原 ledger；
• 一个 SQLite invocation 只能对应一个(sessionId, runId, turnId)；
• canonical codec 拒绝任何 nested loss、accessor/custom prototype 或toJSON改写；
• recovery.hasCorruption与 terminal parked 均独立阻断 provider continuation；
• 文档中的能力边界与代码一致；工作树不包含用户的 workspace/测试文件。

5.3 后续清偿项（不阻塞 correctness gate）

• 从 public commit input 删除冗余journalEventId，完全由 store 派生；
• 为全局 prospective scan 增加 event count / duration 指标，再演进为可重建的增量 reducer；落地后把 transition scan 缩到 candidate execution spine，full scan 移到 store open 或显式 integrity check；
• JSONL 是 legacy/readable fallback，不承担跨进程的全局 invocation uniqueness；恢复 authority 需要 SQLite。

6. 旧 commit 去向：实验的考古学

旧 PR A 的八个非 merge commit 只作为阅读来源，不整体 cherry-pick（文档 §6）：

#1346 中其余 commit 按职责进入 PR B、PR C、PR D 或直接 defer/drop；Git carrier、restricted verification、auto redo、retry/reattach 不从实验分支迁移。

7. #1346 的关闭条件

PR A–C 合并后：在 #1346 最后评论列出 replacement PR；明确未迁移的原型和原因；保持 Draft 并关闭，不 squash/merge；PR body 与 review thread 保留为历史证据；PR D 可独立推进，不阻塞 #1346 关闭。

8. 下一个切片：Git-native workspace M0 Baseline Authority

Continuation Authority 合并后，workspace plane 不再从 #1346 移植通用 file checkpoint carrier。新的首个平铺切片（文档 §10）只证明：

经专用 writer 提交的同一(workspaceId, workspaceEpochId)，其 epoch-opened fact、baseline-accepted fact、epoch/version/head projection 对外只能全可见或全不可见；并发只能接受一个 baseline identity。若 projection 被外部删除，reader 必须 fail closed，不能把损坏态当作未创建。

Schema 9 进一步要求该 authority stream 在首次写入前绑定 authenticated storage root 的 durablerootId；只有 metadata-only 新库可自动绑定，已有逻辑数据必须显式 adoption，单独复制数据库不能改变归属。

文件归属涵盖 core/workspace-version-authority.ts（exact v1 facts、semantic lane、deterministic authority spine、pure scanner）、core/runtime-event.ts（typedactions.workspaceFact与 control-plane stream）、storage 侧runtime-event-authority.ts/sqlite-runtime-schema.ts/sqlite-runtime-store.ts/agent-run-store.ts/conversation-operational-state.ts（ordinary Session purge 不得删除 authority stream）、runtime 侧runtime-event-read-model.ts（workspace control fact 对聊天 projection 不可见）。明确不迁移 #1346 local/Git file checkpoint carrier、mutation prepared/settled/no-op fact、Git worktree owner 与 Desktop/CLI 接线等。证明矩阵要求 canonical scan 与 projection compare 位于同一个 SQLite read snapshot、五个事务内 failpoint 全回滚、两进程 schema 6/7→8 migration、DB rootId exact binding 与跨 root 单文件复制拒绝等。详细协议与剩余边界见 Workspace Version Authority v1。

9. 结语：不变量先行的大型运行时落地方法论

从 #1346 到 PR A/B，再到后续 workspace baseline 切片，Apache Maka 的恢复权威落地展示了一条可复制的方法论：用“一个 PR 证明一个完整不变量”对抗巨型实验分支的不可合并性。其关键动作包括——测试先行（黑盒不变量先于生产代码）、平铺重写（hunk 阅读 + 手工重写而非 cherry-pick）、共享单一实现（scanner/interpreter/validator 全链路共用，拒绝第二套 map 或谓词副本）、fail-closed 优先（immutable corruption、claim 不一致、authority read 失败一律拒绝而非降级）、以及 crash matrix 验证（SIGKILL 五个 durable boundary + 多进程 WAL 竞争）。这套纪律同时回答了“如何安全地丢弃实验代码”与“如何把实验中的真知灼见变成可合并的生产能力”两个问题。

读者如需继续深入，可重点阅读：tool-recovery-fact.ts、tool-recovery-bundle.ts、tool-args-identity.ts、runtime-boundary.ts、canonical-runtime-event.ts、sqlite-runtime-schema.ts、runtime-resume.ts，以及测试账本对应的packages/core/src/__tests__/tool-recovery-authority.test.ts、packages/storage/src/__tests__/sqlite-recovery-concurrency.test.ts、packages/runtime/src/__tests__/runtime-continuation.test.ts等文件。

【免费下载链接】makaApache Maka (Incubating) is a high-performance agent workspace that keeps a complete record of everything it did.项目地址: https://gitcode.com/GitHub_Trending/mak/maka