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 MakaIncubating如何把大规模运行时恢复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-phase3a24bb5f33它包含大量相互耦合的恢复能力原型。生产实现不再把 #1346 当作可合并交付单元原因有三一次合并一个巨型 PR 无法证明任何单一不变量审查与回滚都不可控旧实验 commit 边界与生产不变量并不对齐机械 cherry-pick 会带入半成品 API 与未定型的语义#1346 从未发布、没有用户其 SQLite 数据是一次性实验数据不值得承诺兼容迁移。因此生产落地遵循“一个 PR 证明一个完整不变量”的原则禁止按旧 commit 边界机械 cherry-pick。四个切片的唯一不变量如下切片唯一需要证明的不变量PR Arecovery fact 只有一个原子写入权威且 online/reopen/rebuild/Resolver 必然同构PR Bcontinuation cursor 只来自 immutable RuntimeEvents同一 source boundary 只有一个 claimPR CT1 选择 file reconcile 时必须有可信 evidence自动恢复只做 after-state finalizePR Dstore、worker、registry、后台恢复任务各有唯一 host owner 和完整关闭顺序Phase 3B/4A 的 workspace checkpoint 是后续独立切片不进入 PR A。2. 提取规则平铺分支与黑盒测试先行文档定义了七条提取规则核心要点如下每个新 PR 从当时最新upstream/main建立平铺分支flattened branch即重写历史、不留 merge commit先迁移或重写能表达黑盒不变量的测试再补最小生产代码——测试先行保证不变量可被客观证明不 cherry-pick merge commit同时跨越两个不变量的旧 commit 只能按 hunk 阅读和手工重写不为让旧测试通过而恢复已否决的 public API每个 PR 必须执行 path diff、range-diff 和 production-shaped crash testsPR A–C 合并后关闭 #1346但保留其讨论作为设计与审查记录。这套规则的直接产物是四个 PR 各自的文件账本与测试账本下文逐一展开。3. PR A恢复事实的原子写入权威3.1 保留并重写的能力PR A 是恢复权威recovery authority的最小闭环。它保留了 #1346 中真正有价值的设计并全部重写为可验证实现包括精确的 reconcile-result / recovery-decision v1 schemastrict-JSON admissibility 与冻结的 mainline v1 tool args hash bytes未来的 domain separation 必须由显式 dispatch/hash v2 引入不能原地改变t1_after_preflight_v1call、dispatch、outcome、reconcile、decision 五条 semantic lanegeneric append/import 对保留事实的 authority gate一个 SQLite recovery bundle transactioncompleted 必须引用同 execution identity 的成功 outcomeparked 是 v1 的永久终态只有 exact bundle retry 幂等tool projection 可以只从 immutable RuntimeEvents 重建mutable partial corruption fail-softimmutable corruption fail-closedSQL row identity 与 payload identity 交叉校验online、close/reopen、rebuild、Resolver 的黄金等价性golden equivalence。其中两个工程取舍值得特别说明。第一workspace-wide semantic fail-stopPR A 首版刻意采用该策略任一 session 的 canonical tool-ledger corruption 都会阻止该 SQLite workspace 后续所有 tool-bearing boundary普通非工具事件仍可写——这是 correctness-first 的隔离取舍不是偶然副作用。第二SQLite 与 JSONL 共享唯一 lossless canonical RuntimeEvent codecvalidator 消费 codec 返回的 eventstore 持久化同一次编码返回的稳定 JSON bytesSQLite 对每个 invocation 强制唯一(sessionId, runId, turnId)execution spineJSONL immutable append 对 exact retry 物理去重并在落盘前验证目标 invocation 身份。3.2 明确不带入 PR APR 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_authority1 future newer schema - fail closed这项决策只删除未发布实验格式的迁移负担不删除正式 mainline 数据升级责任mainline schema 4 仍须支持迁移到 schema 5。3.4 PR A 文件账本仓库现状文档列出的文件归属与当前仓库一一对应Coreruntime-event.tsexact recovery fact envelope decoder、canonical-runtime-event.ts唯一 lossless decoder 与稳定 bytes owner、tool-args-identity.tsstrict JSON mainline v1 hash 兼容、tool-ledger-scanner.tsshared lane / duplicate / order / identity scanner、tool-recovery-fact.tstruthful observation 与 terminal decision、tool-recovery-bundle.ts共享 bundle 与 causal interpreterStoragesqlite-runtime-schema.tsschema 5 runtime_recovery_authority1capability当前 schema 已演进至 18、sqlite-runtime-store.ts全局 prospective gate、invocation spine、atomic recovery bundle、projection rebuild、agent-run-store.tsJSONL authority gate、header identity 与 immutable exact retry 去重Runtimerecovery-resolver.ts只消费共享 scanner/interpreter不维护第二套 map、runtime-event-read-model.tsrecovery 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版本均为 1maka.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_decisionprotocol: tool_recovery_v1分为completed必须带成功 outcomeEventId与parkedreasonCode 只能是三种 reconcile 观察对应的 park reason两种 disposition。值得注意的实现细节所有校验函数都使用hasExactKeystool-recovery-fact.ts做精确键集合比对——键个数必须完全相等且逐键匹配任何多余字段都会导致校验失败从而保证恢复事实的 payload 形状不可被污染。completed决策必须引用同 execution identity 的成功 outcomeparked是 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 并未真正达成一致的参数会碰撞成同一个 hashstringifyMainlineV1ToolArgsIdentity保留 mainline 历史stableHash({ toolName, args })的字节语义包括required/enum数组按规范化后字符串排序见canonicalizeMainlineV1中对parentKey的处理tool-args-identity.ts以及显式跳过__proto__键——mainline v1 曾把__proto__赋进普通对象而触发Object.prototype旧 setter导致该键在序列化字节中缺失新实现显式跳过以冻结历史字节而不是改变语义。同文件中的stripUndefinedDeeptool-args-identity.ts处理了 provider 元数据里的undefined字段如 Anthropiccaller对象中toolId: undefined删除undefined键并保留数组空洞为null使 immutable event 读回后仍与写入时含义一致——这是编码器拒绝非 round-trip 值后的必要前置。3.5 PR A 测试账本PR A 的测试覆盖极其密集涵盖以下类别对应文档 §5全部“已覆盖”core authority teststrict 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 authoritystorage authority testgeneric 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 rebuildstorage process crash testreconcile/outcome/decision SIGKILL rollback post-COMMITPOSIX 覆盖Windows 有限支持跳过storage multi-process testexact/conflicting bundle、多进程 WAL 竞争、schema 4→5 并发升级runtime equivalence testonline reopen rebuild Resolver 黄金等价性、prepared / normal T2 success/error / parked / recovered completion、parked 不再进入 reconcileruntime planner testparked / orphan corruption 不得产生 safe replayruntime read-model testaudit fact 不产生 message rowJSONL storage testordinary/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 Bcontinuation 的不可变边界与原子 claimPR A 合并后#1521PR B 从包含 PR A 的upstream/maine4c6ddbf建立平铺分支分支名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 projectiondurable continuation-start 的执行权限由 store-ownedstart_kind决定只有新写入的runtime_admissionstart 是 provider-call T1claim_repairstart 只用于零 provider 调用的崩溃收敛永不授予执行权。不变量拆为三个已实现层次B1 — immutable boundary 与 replay物理event_seq、canonical RuntimeEvent bytes、segment digest、ordered manifest、provider replay digestB2 — durable authority 与 provider T1SQLite unique claim、执行前完整重验证、exact target invocation、store-owned live start、一次性 admission proof/receipt然后才允许 backend/provider 启动B2.1 — pre-provider crash convergenceclaim-only / created-without-start 通过 deterministic repair start terminal 收敛normal start/no-terminal 无 owner proof 时只 park。B3typed retry/reattach branch仍然 defer不进入本 PR。4.2 源码级解读runtime-boundary.ts 的边界代数packages/core/src/runtime-boundary.ts 是 PR B 的核心代数。要点如下Immutable prefix 与 proofbuildImmutableRuntimePrefix/buildImmutableRuntimePrefixProof通过foldImmutableRuntimePrefixruntime-boundary.ts单遍折叠事件流逐条校验event_seq必须从 1 连续递增gap 直接抛错、partial快照被拒绝、每个事件的(sessionId, invocationId, runId, turnId)必须与声明 identity 一致digest 使用 domain 前缀maka.runtime-prefix.v1与长度前缀updateLengthPrefixed哈希保证字节级可复现Segment 与 cursorcreateRuntimeBoundaryCursorruntime-boundary.ts要求所有 segment 属于同一 session、runId/invocationId 不重复允许同一逻辑 Turn 出现连续物理尝试时升级为runtime_boundary_cursor_v2ContinuationClaimV1.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 必须在事前就确定它唯一规则、单一实现continuationStartEventMatchesClaimruntime-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 文件归属Coreruntime-boundary.tsimmutable prefix/segment/composite cursor/claim v1 与 strict decoder、runtime-event.tsexactcontinuation_start_v2payload provenance 是持久化镜像不可自证执行权限、runtime-event-store.tsRuntimeContinuationAuthorityStorecapability、agent-run.tscontinuation_source_v2header lineage以及runtime-boundary.test.ts、runtime-event.test.ts、agent-run-continuation-source.test.tsStoragesqlite-runtime-schema.tsschema 6 runtime_continuation_authority1claim row 持久化start_kindSQL CHECK 限定取值runtime_admission/claim_repair见 sqlite-runtime-schema.ts、sqlite-runtime-store.tsprefix 一致性读、latest-source claim transaction、terminal-tail seal、分离的 live/repair start command、原子交叉校验 event/start_event_id/start_kind、agent-run-store.tsJSONL 拒绝 continuation-start authority factRun admission identity 创建后不可修改以及sqlite-recovery-concurrency.test.ts与sqlite-recovery-concurrency-child.tsproduction-shaped 多进程 claim fixtureRuntimecontinuation-replay.ts每个 lineage segment 的唯一 provider replay materializer、model-history.ts冻结PROVIDER_REPLAY_PROJECTION_VERSION、runtime-resume.tsimmutable lineage planner、V2 replay-edge 与历史 claim authority 校验、runtime-kernel.tsimmediate-source latest 重验、exact tool equality、原子 claim、provider T1 顺序continuation dispatch fail closed仅消费合法的一次性 start proof、runtime-continuation-admission.tsopaque、runner-bound、one-shot start proof/receipt、session-manager.tsclaim-only saga、branch/revision 创建前 preflight、runtime-event-read-model.tscontinuation-start 是消息不可见的 canonical audit factUI 与文档runtime-resume-copy.tsclaim 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/positioncycle / lineage depth / missing ancestor 稳定 parkV2 ancestor 的 claim row 缺失或未绑定 target/start 报runtime_lineage_claim_mismatchreplay 正确性类canonical-equivalent JSON 产生同 prefix digestancestor segment 顺序改变则 manifest digest 改变interrupted text/thinking suffix 截到最近 user/tool stable boundaryA→B→C continuation 中 A 被裁掉的 suffix 不会在 C 重现unmatched call 后仍有 provider-visible 内容时报provider_replay_non_suffix_gapclaim 原子性类两进程同时 claim 同一 boundary 时 1 acquired 1 existingclaim insert 后事务失败则无 durable claimstart event insert 后事务失败则 claim 保留、target prefix 为空immediate source terminal 后有后缀或存在多个 terminal 时 claim fail closedstart_kind 权威类live start 的 T1 marker 与 Runner 不一致时 one-shot proof/receipt 拒绝 provider admissionclaim-only / created-without-start reopen 走 deterministic repairprovider 0 次normal start/no-terminal reopen 报continuation_started_indeterminate且不伪造 terminalSIGKILL 崩溃矩阵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 Dhosted child provider RateLimit retry 入口已删除历史linked_child_resume/linked_child_provider_retrydescriptor 只在 startup recovery 中收敛为 durable terminal factprovider 调用 0 次早期legacy_provider_retry兼容 lane 也已移除在上述 composition/owner 测试完成前不能把当前切片描述为 hosted auto-resume 已默认可用当前也不存在 child provider retry 的 live 或降级准入路径。4.6 PR B 验证记录2026-07-28 在 Windows 有限支持环境完成文档 §8.5Core boundary/decoder/AgentRun V2 定向集合54/54Storage SQLite schema/claim/start/terminal/concurrency 定向集合43/43Runtime continuation/replay/admission/planner 定向集合46/46SessionManager continuation、authority、branch-preflight 与 upstream 冲突回归25/25真实进程 SIGKILL crash harness1/1Core、Storage、Runtime、UI 构建全部通过UI resume copy4/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-pathsrange-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/main466f238b唯一内容冲突位于 Desktop settings E2E保留上游更精确的三按钮 permission fixture。5.2 合并门槛core、storage、runtime build 通过PR A 定向测试全部通过三个包完整测试通过或明确记录与改动无关的平台既有失败SQLite transaction crash matrix 通过所有成功接受的 tool-bearing transition 均满足scan.hasCorruption falseJSONL 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 spinefull scan 移到 store open 或显式 integrity checkJSONL 是 legacy/readable fallback不承担跨进程的全局 invocation uniqueness恢复 authority 需要 SQLite。6. 旧 commit 去向实验的考古学旧 PR A 的八个非 merge commit 只作为阅读来源不整体 cherry-pick文档 §6旧 commit处理34805553core fact authority测试与最小 schema 手工重写68ee74deSQLite bundletransaction 思路手工重写f464cfb1runtime causality被共享 scanner/interpreter 替代5f2b0ae5restart tests有效场景重写到新 fixture4de05393writer bypass收敛为 core generic authority gateb36486b7evidence identity收敛为 strict hash bundle validatorb0683358rebuild racesduplicate/order 场景重写c843519eJSONL validation仅提取 generic writer gate#1346 中其余 commit 按职责进入 PR B、PR C、PR D 或直接 defer/dropGit carrier、restricted verification、auto redo、retry/reattach 不从实验分支迁移。7. #1346 的关闭条件PR A–C 合并后在 #1346 最后评论列出 replacement PR明确未迁移的原型和原因保持 Draft 并关闭不 squash/mergePR body 与 review thread 保留为历史证据PR D 可独立推进不阻塞 #1346 关闭。8. 下一个切片Git-native workspace M0 Baseline AuthorityContinuation 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.tsexact v1 facts、semantic lane、deterministic authority spine、pure scanner、core/runtime-event.tstypedactions.workspaceFact与 control-plane stream、storage 侧runtime-event-authority.ts/sqlite-runtime-schema.ts/sqlite-runtime-store.ts/agent-run-store.ts/conversation-operational-state.tsordinary Session purge 不得删除 authority stream、runtime 侧runtime-event-read-model.tsworkspace 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Apache Maka Runtime Resume 恢复权威拆分账本：从 1346 实验到 PR A/B 不变量驱动的平铺落地
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 MakaIncubating如何把大规模运行时恢复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-phase3a24bb5f33它包含大量相互耦合的恢复能力原型。生产实现不再把 #1346 当作可合并交付单元原因有三一次合并一个巨型 PR 无法证明任何单一不变量审查与回滚都不可控旧实验 commit 边界与生产不变量并不对齐机械 cherry-pick 会带入半成品 API 与未定型的语义#1346 从未发布、没有用户其 SQLite 数据是一次性实验数据不值得承诺兼容迁移。因此生产落地遵循“一个 PR 证明一个完整不变量”的原则禁止按旧 commit 边界机械 cherry-pick。四个切片的唯一不变量如下切片唯一需要证明的不变量PR Arecovery fact 只有一个原子写入权威且 online/reopen/rebuild/Resolver 必然同构PR Bcontinuation cursor 只来自 immutable RuntimeEvents同一 source boundary 只有一个 claimPR CT1 选择 file reconcile 时必须有可信 evidence自动恢复只做 after-state finalizePR Dstore、worker、registry、后台恢复任务各有唯一 host owner 和完整关闭顺序Phase 3B/4A 的 workspace checkpoint 是后续独立切片不进入 PR A。2. 提取规则平铺分支与黑盒测试先行文档定义了七条提取规则核心要点如下每个新 PR 从当时最新upstream/main建立平铺分支flattened branch即重写历史、不留 merge commit先迁移或重写能表达黑盒不变量的测试再补最小生产代码——测试先行保证不变量可被客观证明不 cherry-pick merge commit同时跨越两个不变量的旧 commit 只能按 hunk 阅读和手工重写不为让旧测试通过而恢复已否决的 public API每个 PR 必须执行 path diff、range-diff 和 production-shaped crash testsPR A–C 合并后关闭 #1346但保留其讨论作为设计与审查记录。这套规则的直接产物是四个 PR 各自的文件账本与测试账本下文逐一展开。3. PR A恢复事实的原子写入权威3.1 保留并重写的能力PR A 是恢复权威recovery authority的最小闭环。它保留了 #1346 中真正有价值的设计并全部重写为可验证实现包括精确的 reconcile-result / recovery-decision v1 schemastrict-JSON admissibility 与冻结的 mainline v1 tool args hash bytes未来的 domain separation 必须由显式 dispatch/hash v2 引入不能原地改变t1_after_preflight_v1call、dispatch、outcome、reconcile、decision 五条 semantic lanegeneric append/import 对保留事实的 authority gate一个 SQLite recovery bundle transactioncompleted 必须引用同 execution identity 的成功 outcomeparked 是 v1 的永久终态只有 exact bundle retry 幂等tool projection 可以只从 immutable RuntimeEvents 重建mutable partial corruption fail-softimmutable corruption fail-closedSQL row identity 与 payload identity 交叉校验online、close/reopen、rebuild、Resolver 的黄金等价性golden equivalence。其中两个工程取舍值得特别说明。第一workspace-wide semantic fail-stopPR A 首版刻意采用该策略任一 session 的 canonical tool-ledger corruption 都会阻止该 SQLite workspace 后续所有 tool-bearing boundary普通非工具事件仍可写——这是 correctness-first 的隔离取舍不是偶然副作用。第二SQLite 与 JSONL 共享唯一 lossless canonical RuntimeEvent codecvalidator 消费 codec 返回的 eventstore 持久化同一次编码返回的稳定 JSON bytesSQLite 对每个 invocation 强制唯一(sessionId, runId, turnId)execution spineJSONL immutable append 对 exact retry 物理去重并在落盘前验证目标 invocation 身份。3.2 明确不带入 PR APR 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_authority1 future newer schema - fail closed这项决策只删除未发布实验格式的迁移负担不删除正式 mainline 数据升级责任mainline schema 4 仍须支持迁移到 schema 5。3.4 PR A 文件账本仓库现状文档列出的文件归属与当前仓库一一对应Coreruntime-event.tsexact recovery fact envelope decoder、canonical-runtime-event.ts唯一 lossless decoder 与稳定 bytes owner、tool-args-identity.tsstrict JSON mainline v1 hash 兼容、tool-ledger-scanner.tsshared lane / duplicate / order / identity scanner、tool-recovery-fact.tstruthful observation 与 terminal decision、tool-recovery-bundle.ts共享 bundle 与 causal interpreterStoragesqlite-runtime-schema.tsschema 5 runtime_recovery_authority1capability当前 schema 已演进至 18、sqlite-runtime-store.ts全局 prospective gate、invocation spine、atomic recovery bundle、projection rebuild、agent-run-store.tsJSONL authority gate、header identity 与 immutable exact retry 去重Runtimerecovery-resolver.ts只消费共享 scanner/interpreter不维护第二套 map、runtime-event-read-model.tsrecovery 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版本均为 1maka.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_decisionprotocol: tool_recovery_v1分为completed必须带成功 outcomeEventId与parkedreasonCode 只能是三种 reconcile 观察对应的 park reason两种 disposition。值得注意的实现细节所有校验函数都使用hasExactKeystool-recovery-fact.ts做精确键集合比对——键个数必须完全相等且逐键匹配任何多余字段都会导致校验失败从而保证恢复事实的 payload 形状不可被污染。completed决策必须引用同 execution identity 的成功 outcomeparked是 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 并未真正达成一致的参数会碰撞成同一个 hashstringifyMainlineV1ToolArgsIdentity保留 mainline 历史stableHash({ toolName, args })的字节语义包括required/enum数组按规范化后字符串排序见canonicalizeMainlineV1中对parentKey的处理tool-args-identity.ts以及显式跳过__proto__键——mainline v1 曾把__proto__赋进普通对象而触发Object.prototype旧 setter导致该键在序列化字节中缺失新实现显式跳过以冻结历史字节而不是改变语义。同文件中的stripUndefinedDeeptool-args-identity.ts处理了 provider 元数据里的undefined字段如 Anthropiccaller对象中toolId: undefined删除undefined键并保留数组空洞为null使 immutable event 读回后仍与写入时含义一致——这是编码器拒绝非 round-trip 值后的必要前置。3.5 PR A 测试账本PR A 的测试覆盖极其密集涵盖以下类别对应文档 §5全部“已覆盖”core authority teststrict 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 authoritystorage authority testgeneric 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 rebuildstorage process crash testreconcile/outcome/decision SIGKILL rollback post-COMMITPOSIX 覆盖Windows 有限支持跳过storage multi-process testexact/conflicting bundle、多进程 WAL 竞争、schema 4→5 并发升级runtime equivalence testonline reopen rebuild Resolver 黄金等价性、prepared / normal T2 success/error / parked / recovered completion、parked 不再进入 reconcileruntime planner testparked / orphan corruption 不得产生 safe replayruntime read-model testaudit fact 不产生 message rowJSONL storage testordinary/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 Bcontinuation 的不可变边界与原子 claimPR A 合并后#1521PR B 从包含 PR A 的upstream/maine4c6ddbf建立平铺分支分支名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 projectiondurable continuation-start 的执行权限由 store-ownedstart_kind决定只有新写入的runtime_admissionstart 是 provider-call T1claim_repairstart 只用于零 provider 调用的崩溃收敛永不授予执行权。不变量拆为三个已实现层次B1 — immutable boundary 与 replay物理event_seq、canonical RuntimeEvent bytes、segment digest、ordered manifest、provider replay digestB2 — durable authority 与 provider T1SQLite unique claim、执行前完整重验证、exact target invocation、store-owned live start、一次性 admission proof/receipt然后才允许 backend/provider 启动B2.1 — pre-provider crash convergenceclaim-only / created-without-start 通过 deterministic repair start terminal 收敛normal start/no-terminal 无 owner proof 时只 park。B3typed retry/reattach branch仍然 defer不进入本 PR。4.2 源码级解读runtime-boundary.ts 的边界代数packages/core/src/runtime-boundary.ts 是 PR B 的核心代数。要点如下Immutable prefix 与 proofbuildImmutableRuntimePrefix/buildImmutableRuntimePrefixProof通过foldImmutableRuntimePrefixruntime-boundary.ts单遍折叠事件流逐条校验event_seq必须从 1 连续递增gap 直接抛错、partial快照被拒绝、每个事件的(sessionId, invocationId, runId, turnId)必须与声明 identity 一致digest 使用 domain 前缀maka.runtime-prefix.v1与长度前缀updateLengthPrefixed哈希保证字节级可复现Segment 与 cursorcreateRuntimeBoundaryCursorruntime-boundary.ts要求所有 segment 属于同一 session、runId/invocationId 不重复允许同一逻辑 Turn 出现连续物理尝试时升级为runtime_boundary_cursor_v2ContinuationClaimV1.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 必须在事前就确定它唯一规则、单一实现continuationStartEventMatchesClaimruntime-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 文件归属Coreruntime-boundary.tsimmutable prefix/segment/composite cursor/claim v1 与 strict decoder、runtime-event.tsexactcontinuation_start_v2payload provenance 是持久化镜像不可自证执行权限、runtime-event-store.tsRuntimeContinuationAuthorityStorecapability、agent-run.tscontinuation_source_v2header lineage以及runtime-boundary.test.ts、runtime-event.test.ts、agent-run-continuation-source.test.tsStoragesqlite-runtime-schema.tsschema 6 runtime_continuation_authority1claim row 持久化start_kindSQL CHECK 限定取值runtime_admission/claim_repair见 sqlite-runtime-schema.ts、sqlite-runtime-store.tsprefix 一致性读、latest-source claim transaction、terminal-tail seal、分离的 live/repair start command、原子交叉校验 event/start_event_id/start_kind、agent-run-store.tsJSONL 拒绝 continuation-start authority factRun admission identity 创建后不可修改以及sqlite-recovery-concurrency.test.ts与sqlite-recovery-concurrency-child.tsproduction-shaped 多进程 claim fixtureRuntimecontinuation-replay.ts每个 lineage segment 的唯一 provider replay materializer、model-history.ts冻结PROVIDER_REPLAY_PROJECTION_VERSION、runtime-resume.tsimmutable lineage planner、V2 replay-edge 与历史 claim authority 校验、runtime-kernel.tsimmediate-source latest 重验、exact tool equality、原子 claim、provider T1 顺序continuation dispatch fail closed仅消费合法的一次性 start proof、runtime-continuation-admission.tsopaque、runner-bound、one-shot start proof/receipt、session-manager.tsclaim-only saga、branch/revision 创建前 preflight、runtime-event-read-model.tscontinuation-start 是消息不可见的 canonical audit factUI 与文档runtime-resume-copy.tsclaim 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/positioncycle / lineage depth / missing ancestor 稳定 parkV2 ancestor 的 claim row 缺失或未绑定 target/start 报runtime_lineage_claim_mismatchreplay 正确性类canonical-equivalent JSON 产生同 prefix digestancestor segment 顺序改变则 manifest digest 改变interrupted text/thinking suffix 截到最近 user/tool stable boundaryA→B→C continuation 中 A 被裁掉的 suffix 不会在 C 重现unmatched call 后仍有 provider-visible 内容时报provider_replay_non_suffix_gapclaim 原子性类两进程同时 claim 同一 boundary 时 1 acquired 1 existingclaim insert 后事务失败则无 durable claimstart event insert 后事务失败则 claim 保留、target prefix 为空immediate source terminal 后有后缀或存在多个 terminal 时 claim fail closedstart_kind 权威类live start 的 T1 marker 与 Runner 不一致时 one-shot proof/receipt 拒绝 provider admissionclaim-only / created-without-start reopen 走 deterministic repairprovider 0 次normal start/no-terminal reopen 报continuation_started_indeterminate且不伪造 terminalSIGKILL 崩溃矩阵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 Dhosted child provider RateLimit retry 入口已删除历史linked_child_resume/linked_child_provider_retrydescriptor 只在 startup recovery 中收敛为 durable terminal factprovider 调用 0 次早期legacy_provider_retry兼容 lane 也已移除在上述 composition/owner 测试完成前不能把当前切片描述为 hosted auto-resume 已默认可用当前也不存在 child provider retry 的 live 或降级准入路径。4.6 PR B 验证记录2026-07-28 在 Windows 有限支持环境完成文档 §8.5Core boundary/decoder/AgentRun V2 定向集合54/54Storage SQLite schema/claim/start/terminal/concurrency 定向集合43/43Runtime continuation/replay/admission/planner 定向集合46/46SessionManager continuation、authority、branch-preflight 与 upstream 冲突回归25/25真实进程 SIGKILL crash harness1/1Core、Storage、Runtime、UI 构建全部通过UI resume copy4/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-pathsrange-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/main466f238b唯一内容冲突位于 Desktop settings E2E保留上游更精确的三按钮 permission fixture。5.2 合并门槛core、storage、runtime build 通过PR A 定向测试全部通过三个包完整测试通过或明确记录与改动无关的平台既有失败SQLite transaction crash matrix 通过所有成功接受的 tool-bearing transition 均满足scan.hasCorruption falseJSONL 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 spinefull scan 移到 store open 或显式 integrity checkJSONL 是 legacy/readable fallback不承担跨进程的全局 invocation uniqueness恢复 authority 需要 SQLite。6. 旧 commit 去向实验的考古学旧 PR A 的八个非 merge commit 只作为阅读来源不整体 cherry-pick文档 §6旧 commit处理34805553core fact authority测试与最小 schema 手工重写68ee74deSQLite bundletransaction 思路手工重写f464cfb1runtime causality被共享 scanner/interpreter 替代5f2b0ae5restart tests有效场景重写到新 fixture4de05393writer bypass收敛为 core generic authority gateb36486b7evidence identity收敛为 strict hash bundle validatorb0683358rebuild racesduplicate/order 场景重写c843519eJSONL validation仅提取 generic writer gate#1346 中其余 commit 按职责进入 PR B、PR C、PR D 或直接 defer/dropGit carrier、restricted verification、auto redo、retry/reattach 不从实验分支迁移。7. #1346 的关闭条件PR A–C 合并后在 #1346 最后评论列出 replacement PR明确未迁移的原型和原因保持 Draft 并关闭不 squash/mergePR body 与 review thread 保留为历史证据PR D 可独立推进不阻塞 #1346 关闭。8. 下一个切片Git-native workspace M0 Baseline AuthorityContinuation 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.tsexact v1 facts、semantic lane、deterministic authority spine、pure scanner、core/runtime-event.tstypedactions.workspaceFact与 control-plane stream、storage 侧runtime-event-authority.ts/sqlite-runtime-schema.ts/sqlite-runtime-store.ts/agent-run-store.ts/conversation-operational-state.tsordinary Session purge 不得删除 authority stream、runtime 侧runtime-event-read-model.tsworkspace 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考