Implement RFC-022 unified graph write protocol

[aaltshuler]

Summary

• enroll mutation and load in RFC-022's exact branch-wide OCC protocol, capturing the native Lance branch identity, graph head, schema identity, and table authority as one write token
• add schema-v3 recovery sidecars with pre-minted lineage, exact Lance transaction ownership, effect confirmation, deterministic roll-forward/rollback, and bounded full reprepare for safe write shapes
• harden branch merge, schema apply, native branch controls, cleanup, refresh, and recovery with root-shared schema → branch → table gates plus fresh catalog, sidecar, and manifest revalidation
• keep expensive physical indexes out of logical write effects and expose typed read_set_conflict (409) and recovery_required (503) HTTP responses
• add the RFC-022–027 architecture series and review ledger; RFC-026 treats MemWAL as Lance's strategic streaming architecture, not an experimental path

Why

The previous path did not capture branch identity, graph lineage, schema authority, and table versions as one coherent validation token. A publisher retry could therefore reparent validation-sensitive work, recovery sidecars could not always prove ownership of the exact Lance effects they observed, and native branch/control operations had same-process ABA and stale-catalog windows.

RFC-022 defines one correctness protocol while preserving writer-specific Lance effect adapters. This slice implements the mutation/load adapter and closes the adjacent control-plane race windows needed to make that adapter safe.

User and developer impact

• safe insert/append/merge conflicts fully reprepare from the current graph base
• strict update/delete/overwrite conflicts return structured 409 responses before effects
• post-effect uncertainty remains durably recoverable and returns structured 503 responses
• branch deletion waits out live owners and may orphan target-scoped intents for audited discard; graph-global schema recovery still blocks deletion
• schema apply, load, and mutate no longer build expensive indexes inline; explicit reconciliation owns physical index materialization

Validation

• cargo test --workspace --locked
• cargo test --locked -p omnigraph-engine --features failpoints --test failpoints -- --test-threads=1 — 80/80
• feature-gated schema suite — 23/23
• recovery suite — 19/19
• OpenAPI suite — 81/81
• scripts/check-agents-md.sh — 67 links across 63 docs
• git diff --check

Current boundary

RFC-022 and its follow-up RFCs remain drafts. The ordered gates in this slice are process-local: unrestricted multi-process writers against the same graph still require a substrate-native conditional-reference primitive or distributed fence. Branch merge uses a hardened authority bridge in this PR; it is not yet the final unified exact-effect adapter.

Greptile Summary

This PR implements the RFC-022 unified graph write path. The main changes are:

• Captures branch, graph head, schema, and table authority in one write token.
• Adds schema-v3 recovery sidecars and typed recovery responses.
• Routes mutation and load through the new OCC and recovery protocol.
• Hardens branch, schema, cleanup, refresh, and recovery gates.
• Moves physical index convergence out of logical write effects.
• Updates architecture, operations, API, and RFC documentation.

Confidence Score: 4/5

This is close, but the schema-apply API contract should be fixed before merging.

• Recovery-required responses keep the error-code enum stable.
• Most recovery-capable write routes document the new 503 response.
• Schema apply can return the same recovery response but does not document it in OpenAPI.

crates/omnigraph-server/src/handlers.rs and crates/omnigraph-server/tests/openapi.rs

Important Files Changed

Filename	Overview
crates/omnigraph-api-types/src/lib.rs	Adds structured read-set conflict and recovery-required fields while keeping the public error-code enum unchanged.
crates/omnigraph-server/src/lib.rs	Maps read-set conflicts to 409 responses and recovery-required states to 503 responses with structured recovery details.
crates/omnigraph-server/src/handlers.rs	Updates most write-route response metadata for the new conflict and recovery outcomes, with one schema-apply response gap.
crates/omnigraph-server/tests/openapi.rs	Adds OpenAPI coverage for the new error fields and recovery responses, but does not cover schema apply.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant Client
    participant Server as schema/apply handler
    participant Engine as schema write path
    participant API as error mapping
    Client->>Server: "POST /graphs/{graph_id}/schema/apply"
    Server->>Engine: apply schema
    Engine-->>Server: recovery required
    Server->>API: convert engine error
    API-->>Client: 503 ErrorOutput with recovery_required

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 Client
    participant Server as schema/apply handler
    participant Engine as schema write path
    participant API as error mapping
    Client->>Server: "POST /graphs/{graph_id}/schema/apply"
    Server->>Engine: apply schema
    Engine-->>Server: recovery required
    Server->>API: convert engine error
    API-->>Client: 503 ErrorOutput with recovery_required

Loading

Comments Outside Diff (2)

1. crates/omnigraph/src/db/manifest/recovery.rs, line 2319-2328 (link)

   Recovery Audit Uses Latest Commit

   When this convergence path finds the sidecar intent already satisfied, it records the audit against the latest omnigraph:recovery commit rather than the commit that satisfied this operation. If another recovery commit lands first, the audit row for this sidecar can point at an unrelated graph commit, so operators following the audit trail see the wrong recovery commit for the operation.

   

2. crates/omnigraph-server/src/handlers.rs, line 1136 (link)

   Document Schema Recovery

   server_schema_apply still calls apply_schema_as_with_catalog_check() through ApiError::from_omni, so a recovery-blocked schema migration can return the new 503 ErrorOutput with recovery_required. This route does not list 503 in its OpenAPI responses, while the other recovery-capable write routes do. Clients generated from the spec can treat a valid schema-apply recovery response as an unexpected status or body shape instead of exposing the operation id needed to recover.

   Context Used: AGENTS.md (source)

   

_{Reviews (2): Last reviewed commit: "Preserve recovery error wire compatibili..." | Re-trigger Greptile}

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 potential bugs to report.

View in Devin Review to see 1 additional finding.