feat(changes): graph diff, branch review and merge dry run

[ragnorc]

Update: GQ statements (d3b05e3)

Following review, the surfaces are GQ branch statements, control reads at POST /query. The CLI verbs and HTTP routes wrap the same engine call:

• branch diff <source> [into <target>];
• branch diff <from> to <to>;
• branch merge-base <source> [into <target>];
• branch merge <source> [into <target>] dry run.

A branch diff statement answers rows, with its compared commits and continuation token in a new optional page object on ReadOutput. GQT no longer has its own diff, merge-base and dry-run steps; the four cases run the statements as ordinary --- query steps. The sections below describe the step kinds this update replaced; RFC 0030 §8.5 and RFC 0045 hold the current contract.

Implements the graph diff phases D1–D3 of RFC 0030 as amended in #964. This branch carries that PR's two RFC commits, so review that one first; this PR's own changes are in feat(changes): …. Each phase is available on the engine, HTTP and the CLI, and tested at each boundary and in GQT.

What changes

D1: graph diff. Omnigraph::diff_page reports the net entity changes between two points.

• A side is a branch name (its head when the diff starts) or a commit id: published, proposal or unattached.
• The output uses the commit changes entity shape and frozen order, without a cause.
• A string that names both a branch and a commit is refused (AmbiguousReadTarget, 400). One that names neither is ReadTargetNotFound (404).
• The diff-page token binds the graph identity, a digest of the spelled sides, the resolved commit ids and the filter. Later pages therefore answer for the commits the first page resolved, even after the branches move.
• Routes: GET /graphs/{id}/diff?from=&to= and GET /graphs/{id}/branches/diff?source=&target= (merge base → source head, reporting base_commit_id).
• CLI: omnigraph diff --from --to and branch diff <branch> [--into].

D2: merge base. Omnigraph::merge_base returns the commit a merge would classify against, using the merge's own rule. Exposed as GET /branches/merge-base and branch merge-base.

D3: merge dry run. Session::branch_merge_dry_run runs the merge's capture, classification and validation, then returns before any effect.

• It takes no schema permit, branch gate or input-tag pin, and writes nothing.
• A conflict gives the same MergeConflicts as a real merge (409).
• Exposed as dry_run: true on POST /branches/merge and branch merge --dry-run.
• It needs read on both branches, not branch_merge.

Policy. /diff authorizes read on the branch each side resolves to. A denied side answers the same 404 as an unknown one, so branch existence is not disclosed. The branch routes and the dry run use the ordinary read check (403).

Retired. The table-shaped diff_between/diff_commits and their ChangeSet types are removed (RFC 0030 §8.6), and their callers move to diff_page:

• the DST oracle;
• the engine changes.rs tests;
• the failpoint diffs;
• legacy_columns;
• warm_read_cost.

Two behaviors change and are noted in the changelog. A row rewritten with equal values is no longer an update. A pair across a dropped and re-added type refuses with ChangeSchemaBoundary.

Decisions changed in implementation. These are recorded in the RFC 0030 decision log.

• The dry run reports no change counts.
• The page token also binds the sides digest.

GQT

RFC 0045 gains three steps, documented in the RFC and the GQT README:

• --- diff, in from:/to:, source:[target:] or commit: form;
• --- merge-base, with --- expect commit $name;
• --- merge-dry-run, which takes the merge expects.

The engine and DST paths call the engine. The served path sends the HTTP routes. Four cases, each on the engine, two DST seeds and the served target:

• graph_diff_branch_review: merge base, branch diff, two-point diffs, and a dry run that leaves main unchanged.
• graph_diff_merge_proposal: a proposal's own diff, the diff from main to it, and an empty review once published.
• graph_diff_net_range: a reverted update, an insert later deleted, an equal reinsert, a changed reinsert and an insert later updated. Only the net change at the endpoints is reported.
• graph_diff_refusals: a typed not-found side, no merge base for a missing branch, and a dry-run conflict equal to the merge's.

Tests run

All locally with RUST_MIN_STACK=16777216:

• Engine (failpoints feature):
  • --test integration changes:: (56 passed), with new graph-diff tests for:
    • a commit's parent;
    • the net range;
    • branch review;
    • every read-target kind, including proposal and unattached expiry;
    • ambiguity;
    • stable endpoints across pages.
  • merge_truth_table::: every cell first runs a measured dry run and asserts zero manifest and data writes, an unmoved main, and the merge's own outcome.
  • legacy_columns::, warm_read_cost::by_id_reads, --test forbidden_apis (35) and the three rfc_0067_*_diff_* failpoint tests.
  • After merging current main, changes:: and merge_truth_table:: again (58 passed).
• Server --test integration: data_routes::, auth_policy:: and openapi:: (221 passed). openapi.json is regenerated.
• CLI --test integration: parity_matrix:: and cli_data:: (119 passed), including parity_diff_over_shared_history and parity_branch_review.
• omnigraph-gqt-core (202 passed), and omnigraph-gqt gq_logic_tests graph_diff (4 cases, engine and DST), before and after merging main.
• The served conformance for the four cases (served and in-process both green).
• cargo fmt --all --check, workspace clippy (also after merging main), omnigraph-gqt clippy, check-docs.py, typos, check-agents-md.sh and check-ci-cells.py.

Under local load (other builds held the load average near 20 on 18 cores), each new GQT case took 8.6–9.8 s against the 10 s budget, close to comparable existing cases such as unpublished_commit_merge (8.5 s); I split the merge-proposal half out of the branch-review case for that reason. In the same conditions, runner_dispatch timed out in 3 to 18 of its 26 tests. Each of those tests passes when run alone, and none exercises the diff steps.

Review follow-up (#964)

The review of the RFC amendment found two contract gaps; both corrections are merged in from #964 (5169758), with their tests here (3bb0775).

• Merge base and the feed. --start after:<merge-base> works only while the source has never merged the target in. After that the base is off the source's first-parent chain and the feed refuses it. The user guide now says so and points at branch diff. change_feed_merge_commit_is_first_parent_relative_with_merged_parent_on_cause asserts the refusal and the branch diff from that base.
• Branch review authorization. The routes already required read on source and target. policy_branch_review_needs_read_on_the_target pins the case where both diff endpoints are readable but the target is not, on the first page, a continuation and merge-base.

Rerun: engine changes:: (56), server auth_policy:: and data_routes:: (128), clippy for the engine and server targets, and the docs checks.

[azimafroozeh]

The new surface went into GQT instead of GQ. The three step kinds (--- diff, --- merge-base, --- merge-dry-run) should be GQ statements under branch_stmt, beside branch merge … as commit; then GQT needs no new step, and the routes and CLI stay as wrappers

[ragnorc]

Done in d3b05e3. The three surfaces are now GQ branch statements under branch_stmt, and GQT has no new step kind.

The statements. Each is a control read in RFC 0055's sense: it enters POST /query and omnigraph query, and POST /mutate refuses it as a read.

• branch diff <source> [into <target>] reviews a branch.
• branch diff <from> to <to> compares two points; a side is a branch or a quoted commit id.
• branch diff takes after page "<token>" and limit <n>.
• branch merge-base <source> [into <target>].
• branch merge <source> [into <target>] dry run, as a clause beside as commit.

The HTTP routes and CLI verbs stay, as wrappers of the same engine call. The server runs the route's own authorization and error mapping for each statement, so the 403/404 decisions and the dry run's 409 are identical. Embedded callers (the CLI's direct path and GQT) go through one Session::branch_read.

GQT. The four graph_diff_* cases are ordinary --- query statement steps, and they pass on the engine, DST and served targets. The statement steps needed two rules, recorded as a 2026-10-13 entry in RFC 0045's log:

• A branch read carries no shape section. Its columns are the statement's own, and a .pg shape has no object type for before/after; RFC 0056 notes the same gap.
• A bound ${name} may appear in a quoted side and in an expected row, the same substitution a params body has. Without it a merge-base row, which is commit ids, could not be asserted.

The answer shape. These reuse what RFC 0056 (#670) proposes, so the two RFCs don't diverge.

• Rows project the HTTP change shape, but name the type by its name. The opaque type id is per graph, so it stays on the routes.
• The compared commits and the continuation token travel in an optional page object on ReadOutput.
• The statements take no kind/type/op filter yet. RFC 0056's clause order (paging before filters) leaves room to add them.

RFC 0030 §8.5, RFC 0055 (decision log) and RFC 0045 are updated in the same change.

Addressed