RFC-022: enroll branch merge in the unified write path

[aaltshuler]

What & why

Enroll branch merge in the RFC-022 unified write adapter so a merge is classified from immutable source/target snapshots, publishes under exact target authority, and remains recoverable without adopting foreign Lance state or re-parenting onto a target winner.

The adapter pre-mints fixed merge lineage and ordered per-table Lance transaction identities, arms schema-v4 recovery before the first table/ref effect, confirms the exact physical and logical output, and publishes the complete merge delta in one manifest CAS.

Backing issue / RFC

• Fixes an accepted issue: Closes #
• Implements / is an accepted RFC: RFC-022 — Unified Write Path
• Trivial fast-lane (typo / docs / dependency bump / comment / one-line CI) — no issue/RFC required

Checklist

• Change is focused (one logical change)
• Tests added/updated for behavior changes (or N/A)
• Public docs updated if user-facing surface changed (or N/A)
• Reviewed against docs/dev/invariants.md — no Hard Invariant weakened, no deny-list item hit (or justified)

Notes for reviewers

• Source semantics are explicit: merge the captured source commit. A later source advance on the same incarnation is allowed but never substituted; source delete/recreate ABA is rejected.
• Target semantics are strict: branch identifier, exact optional graph head, schema identity, and table expectations are revalidated under schema → branch → table gates. The publisher cannot silently re-parent a prepared merge.
• Schema-v4 recovery distinguishes exact multi-commit data effects from ref-only first-touch forks and carries pointer-only slots in the complete logical delta.
• Each logical data step commits with a pre-minted (read_version, uuid) and zero transparent conflict retries. Confirmation and recovery prove the contiguous exact chain from Lance history. Only a CreateIndex suffix after the complete chain is rollback-discardable derived state; any foreign, missing, or non-contiguous operation fails closed.
• Compensation is restartable: a crash after Lance Restore but before the compensating manifest publish recognizes and reuses that exact restore rather than restoring repeatedly.
• Fixed original/rollback commit IDs make recovery lineage and audit finalization exactly-once across Phase-D failures.
• Exact history scans are bounded at 1,024 versions. The logical merge chain is currently at most three commits; exceeding the ceiling fails closed.
• Native ref create/delete still lacks conditional CAS, so destructive first-touch recovery retains the documented single-writer-process boundary.

Validation:

• cargo test --workspace --locked
• cargo test -p omnigraph-engine --features failpoints --test failpoints --locked (94 passed)
• Branch-merge failpoint filter (26 passed), including foreign Append-before-index-tail, same-table winner, Phase-D finalization, first-touch ambiguity, and restore-before-publish restart
• Merge truth table, fast-forward, branching, cost, and server concurrency suites
• scripts/check-agents-md.sh
• git diff --check

---

Greptile Summary

This PR moves branch merge onto the unified RFC-022 write path. The main changes are:

• Captured source and target authority for merge classification.
• Schema-v4 recovery sidecars for branch-merge effects.
• Pre-minted exact Lance transaction identities for merge data steps.
• Exact roll-forward and rollback handling for confirmed merge effects.
• Updated recovery, branching, and write-path documentation.

Confidence Score: 4/5

The branch-merge write path needs fixes before merging. Valid merge states can fail after recovery is armed, and pointer-only merges can lose their recovery intent.

• Planned exact transactions can outlive no-op staged steps and force rollback.
• All-pointer merge output can be dropped if the process stops before manifest publish.
• The new v4 recovery code otherwise appears to fail closed on foreign or unverifiable state.

crates/omnigraph/src/exec/merge.rs

Important Files Changed

Filename	Overview
crates/omnigraph/src/exec/merge.rs	Branch merge now captures write authority, creates v4 recovery envelopes, and commits merge data with exact transaction identities; the transaction planning and pointer-only recovery paths can fail valid merges or lose recovery intent.
crates/omnigraph/src/db/manifest/recovery.rs	Adds schema-v4 BranchMerge recovery payloads, validation, classification, exact roll-forward, rollback, and visible outcome finalization.
crates/omnigraph/src/storage_layer.rs	Extends storage operations for exact staged commits and branch identifier reads used by branch-merge recovery.
crates/omnigraph/src/db/commit_graph.rs	Adds merge-base computation for already captured graph commit IDs.
crates/omnigraph/src/db/manifest.rs	Re-exports the new BranchMerge recovery sidecar types and helpers.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
  participant Merge as Branch merge
  participant Sidecar as Recovery sidecar
  participant Lance as Lance tables and refs
  participant Manifest as Manifest publish
  Merge->>Sidecar: Arm authority, lineage, planned effects
  Merge->>Lance: Commit exact data steps or create refs
  Merge->>Sidecar: Confirm complete merge output
  Merge->>Manifest: Publish table updates and merge lineage
  alt crash before manifest publish
    Sidecar->>Lance: Classify exact effects
    Sidecar->>Manifest: Roll forward confirmed delta or roll back owned effects
  end

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
  participant Merge as Branch merge
  participant Sidecar as Recovery sidecar
  participant Lance as Lance tables and refs
  participant Manifest as Manifest publish
  Merge->>Sidecar: Arm authority, lineage, planned effects
  Merge->>Lance: Commit exact data steps or create refs
  Merge->>Sidecar: Confirm complete merge output
  Merge->>Manifest: Publish table updates and merge lineage
  alt crash before manifest publish
    Sidecar->>Lance: Classify exact effects
    Sidecar->>Manifest: Roll forward confirmed delta or roll back owned effects
  end

Loading

_{Reviews (1): Last reviewed commit: "Enroll branch merge in RFC-022 write pat..." | Re-trigger Greptile}

Greptile also left 3 inline comments on this PR.

Context used:

• Context used - AGENTS.md (source)
• Context used - CLAUDE.md (source)

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.