Expose exact write receipts for mutation and load

[mrkorchun]

What & why

Return the exact GraphCommit published by Mutation and Load through embedded, HTTP, and CLI surfaces. Callers can correlate a durable acknowledgement without rereading a branch head that may already have advanced.

Scope

• Adds opt-in receipt-bearing engine methods; existing result-only methods remain compatibility wrappers.
• Effectful ordinary, conditional, and stored mutations return the commit from the same manifest CAS.
• A successful zero-row mutation returns commit: null and creates no graph commit.
• Load, raw NDJSON load, and deprecated ingest return the single commit they publish, including the empty/no-sidecar Load path.
• Adds optional commit fields to additive JSON response DTOs and regenerates OpenAPI.
• Preserves graph-head preconditions and the existing Mutation/Load publication and recovery protocols.

This PR deliberately does not expose a public per-commit changes endpoint or ordering ABI. That belongs to RFC-030 C1/C2 with bounded cursors, retention-gap behavior, authorization, and byte/row/commit ceilings. Part of #478; this PR does not close the issue.

Invariants

The receipt comes directly from the same __manifest CAS that makes the write visible; no branch-head reread reconstructs it. This adds no storage or recovery schema, WAL, event store, alternate publisher, or Blob-specific write path.

Verification

• cargo fmt --all -- --check
• git diff --check
• scripts/check-agents-md.sh
• default and failpoint-superset workspace Clippy with warnings denied
• RUST_MIN_STACK=16777216 cargo test --workspace --locked --features omnigraph-engine/failpoints,omnigraph-cluster/failpoints
• server data_routes 42/42 and stored_queries 15/15
• OpenAPI regeneration and drift suite 92/92
• CLI cli_data 77/77, parity_matrix 13/13, system_local 27 passed / 1 ignored
• the three changed remote CLI write journeys run explicitly and pass
• independent final engine/API/docs reviews: no findings

Compatibility

The wire change is additive and optional: older servers omit commit; newer clients preserve null for a no-op. Existing embedded result-only APIs remain available.

Greptile Summary

The PR exposes the exact manifest-published commit from mutation and load operations across embedded, HTTP, and CLI surfaces while preserving result-only compatibility methods.

• Adds receipt-bearing mutation and load APIs sourced directly from the publication CAS.
• Adds optional commit data to shared response DTOs, CLI output, HTTP responses, and OpenAPI.
• Returns no mutation commit for zero-row operations while returning the publication commit for loads, including empty loads.
• Registers all new public writer methods in the write-surface protocol registry.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains; the previous writer-registration issue and embedded-ingest receipt omission are both resolved at current HEAD.

Important Files Changed

Filename	Overview
crates/omnigraph/src/exec/mutation.rs	Adds receipt-bearing mutation wrappers and returns the exact published commit, with None for successful zero-row mutations.
crates/omnigraph/src/loader/mod.rs	Threads the exact manifest publication commit through load, graph-batch load, and file-load receipt APIs.
crates/omnigraph/src/db/graph_coordinator.rs	Returns the same GraphCommit constructed from the successful manifest publication outcome.
crates/omnigraph-api-types/src/lib.rs	Adds optional commit fields and shared receipt-to-response mappings for ingest and graph-batch load.
crates/omnigraph-cli/src/client.rs	Uses receipt-bearing engine methods for embedded mutation, load, and ingest, resolving the previously reported embedded-ingest omission.
crates/omnigraph-server/src/handlers.rs	Maps mutation and load receipts into the corresponding HTTP response DTOs.
crates/omnigraph/tests/forbidden_apis.rs	Registers all seven new public receipt-bearing writer methods under the appropriate Mutation v9 or Load v9 protocol classification.
openapi.json	Publishes the additive optional commit fields for mutation and load response schemas.

Sequence Diagram

sequenceDiagram
    participant Caller
    participant Surface as Embedded / HTTP / CLI
    participant Engine as Mutation / Load
    participant Manifest as __manifest CAS
    Caller->>Surface: Write request
    Surface->>Engine: Receipt-bearing method
    Engine->>Manifest: Publish table pointers and lineage
    Manifest-->>Engine: Exact GraphCommit
    Engine-->>Surface: Result + commit receipt
    Surface-->>Caller: Optional commit in response

Loading

_{Reviews (7): Last reviewed commit: "feat(api): expose exact write receipts" | Re-trigger Greptile}

Context used (3)

• Knowledge Base — OmniGraph write path
• Knowledge Base — CLI and Config
• Knowledge Base — Server Request Handling

[mrkorchun]

Compatibility note: the embedded engine API is source-compatible because existing mutate* / load* signatures are unchanged and receipt variants are opt-in. The JSON wire change is additive/optional per docs/dev/versioning.md. One Rust-only edge remains: downstream code constructing the public ChangeOutput, IngestOutput, or GraphBatchLoadOutput DTOs with struct literals must add commit: None. Avoiding that would require parallel response-wrapper DTOs; I kept the smaller native optional-field shape, but can split wrappers if strict Rust DTO source compatibility is preferred.

[mrkorchun]

Addressed the embedded-ingest parity finding in ec8cc6d: the embedded arm now uses load_file_as_with_receipt and ingest_receipt_output, with a regression assertion that graph_commit_id is present. cargo check --locked -p omnigraph-cli passes.

[greptile-apps]

Want your agent to iterate on Greptile's feedback? Start a greploop in Claude Code and it will work through the open comments and keep going until this PR reviews clean.