Skip to content

feat(runtime-host): recover exact Gitoxide Write/Edit candidates - #43

Draft
zhiiw wants to merge 9 commits into
codex/managed-write-edit-stack-v1from
codex/gitoxide-write-edit-recovery-v1
Draft

zhiiw wants to merge 9 commits into
codex/managed-write-edit-stack-v1from
codex/gitoxide-write-edit-recovery-v1

Conversation

@zhiiw

@zhiiw zhiiw commented Aug 30, 2026 •

Copy link
Copy Markdown
Owner

Summary

Add the Gitoxide recovery half of managed Write/Edit on top of the managed mutation acceptance kernel.

This stacked PR proves one primary invariant:

Recovery never confuses an active T1 with a settled projection, and once SQLite has accepted a successor, accepted-ref repair adopts the exact durable candidate receipt instead of re-running Write/Edit or recomputing its transform.

Ownership

  • Candidate receipt authority owns the strict operation-bound durable receipt and can reissue only an in-process bearer that exactly matches the current accepted base, helper artifact, candidate ref, commit/tree/blob, path, and execution profile.
  • SQLite remains the accepted-truth owner.
  • Accepted-ref projection is derived state and can move only with an owner-bound projection capability issued by exact SQLite successor replay.
  • Runtime/continuation owns pre-T2 replay. Projection repair does not execute an active mutation.

Recovery states

  • Active mutation reservation: return gitoxide_managed_mutation_replay_required; never report already_current.
  • Durable successor and accepted ref already exact: return already_current.
  • Durable successor and accepted ref still at the exact parent: reopen the durable candidate receipt, exact-replay the SQLite successor to reissue a projection capability, then CAS the ref.
  • Accepted ref at a third value: fail closed.
  • Timeout, cancellation, helper corruption, or any error other than the exact target mismatch: propagate the original failure; do not reinterpret it as repairable drift.

Important correction

The earlier implementation reconstructed the result by reading the parent tree and calling the current pure transform again. That made post-T2 recovery depend on current code and created a second result derivation path. This PR removes that path. Post-T2 recovery now validates immutable call/dispatch/outcome evidence and directly reopens the already-persisted candidate receipt.

Pre-T2 process loss may still deterministically recompute the pure transform under the same durable operation. The safety guarantee is at-most-one accepted successor, not exactly-once invocation of a pure function.

Test and delivery notes

  • Rebuilt as nine commits on top of the six-commit kernel branch and current upstream/main.
  • git range-diff preserves all fifteen extracted commits exactly.
  • Fixed the real crash fixture so workspaceVersionId is not accidentally embedded in the strict epoch payload.
  • Added active-reservation regression coverage and strict candidate-reopen/tamper coverage.
  • Four affected workspaces build successfully.
  • Focused suite: 81 passed, 1 helper-dependent test explicitly skipped locally; the real helper workflow remains the platform gate.
  • git diff --check passes.

This is a stacked Draft for review. After the kernel PR merges, it can be retargeted/rebuilt directly onto the new main without changing the recovery contract.

中文说明

摘要

本 stacked PR 在 managed mutation kernel 之上补齐 Gitoxide recovery,证明一个主要不变量:

recovery 不能把 active T1 误认为已经收敛;SQLite 一旦接受 successor,accepted-ref repair 只能采用精确的 durable candidate receipt,不能重新执行 Write/Edit,也不能重新计算 transform。

Owner 与恢复状态

  • Candidate receipt authority:拥有严格、operation-bound 的 durable receipt;只会在 accepted base、helper artifact、candidate ref、commit/tree/blob、path 与 execution profile 全部精确一致时重签进程内 capability。
  • SQLite:仍是 accepted truth 唯一 owner。
  • Accepted-ref projection:只是派生状态,只能消费 exact SQLite successor replay 签发的 owner-bound projection capability。
  • Runtime/continuation:负责 pre-T2 replay;projection repair 不执行 active mutation。

active reservation 存在时返回 gitoxide_managed_mutation_replay_required,禁止报告 already_current。durable successor 已存在且 ref 仍停在精确 parent 时,直接重开 receipt、精确 replay SQLite successor 以重签 projection capability,再执行 ref CAS。ref 是第三值时 fail closed。超时、取消、helper corruption 等非 exact target mismatch 错误原样上抛,不能被误判成可修复 drift。

关键修正

旧实现会重新读取 parent tree 并调用当前 pure transform,这让 post-T2 recovery 依赖当前代码,并形成第二条 result derivation path。现在该路径已经删除:post-T2 只验证 immutable call/dispatch/outcome evidence,然后直接重开已持久化 candidate receipt。

T2 前进程退出后,同一 durable operation 仍可确定性重算纯 transform;安全保证是“最多一个 successor 被接受”,不是“纯函数调用 exactly once”。

验证

本分支以六提交 kernel 为基座,在最新 upstream/main 上增加九个提交;15 个 extraction commits 经 range-diff 全部精确保留。修复了 crash fixture 把 workspaceVersionId 误塞进 strict epoch payload 的问题;新增 active reservation 与 receipt reopen/tamper 回归。四个 workspace 构建通过;定向套件 81 pass、1 个真实 helper 用例本地明确 skip,三平台 helper workflow 仍是发布 gate;git diff --check 通过。

@zhiiw
zhiiw force-pushed the codex/gitoxide-write-edit-recovery-v1 branch from b5d5e5d to 4dd9676 Compare August 30, 2026 14:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant