# Changes, Diffs and Change Feeds

Source: https://www.omnigraph.dev/docs/branching/changes

OmniGraph can describe what one commit changed, compare any two points in
history, review what a branch changed, or deliver an ordered feed of changes
on a branch. Every surface reports logical nodes and edges, not storage
details, in one change shape.

HTTP calls follow the [HTTP contract](https://www.omnigraph.dev/docs/operations/server.md#http-contract),
including the required request header and response check before consuming a
JSON or streamed body.

## Inspect one commit

```bash
omnigraph commit changes <commit-id> --target ./graph.omni --json
```

The equivalent HTTP route is
`GET /graphs/{graph_id}/commits/{commit_id}/changes`. The commit is compared
with its first parent. Each response includes:

* `cause`: the commit id, parent, optional merged parent, authored branch,
  optional actor, and authorship time in Unix microseconds.
* `changes`: inserts with `after`, updates with `before` and `after`,
  and deletes with `before`. Each image contains `properties`; an edge image
  also contains `endpoints: {from, to}`. A Blob property holds its export
  value (`base64:…` or an external URI), or, for a stored reference to a byte
  range of an object, `{"uri", "offset", "length"}` (see
  [Blobs](https://www.omnigraph.dev/docs/schema/blobs.md)).

Filter with repeatable `--kind node|edge`, `--type <name>`, and
`--op insert|update|delete` options. A page holds at most 8,192 changes; the
HTTP routes default to 1,000. Results are deterministic by entity kind, type
identity, logical id, and operation.

Large results are paginated. The CLI normally follows every
`next_page_token` and asks for 8,192 changes per page, because every page
restarts its comparison and fewer, larger pages cost less; passing
`--page-token` fetches exactly one page, of 1,000 changes unless `--limit`
sets the size. A page token continues that one commit result and is not a
change-feed cursor.

A parentless commit returns `409` with reason `parentless_commit`. A diff
that crosses a schema boundary returns `409` with reason
`schema_boundary`; take a new baseline instead of treating either response
as an empty change.

## Compare two points

```bash
omnigraph diff --from <commit-id> --to main --target ./graph.omni --json
```

Each side is a branch name, meaning its head when the diff starts, or a commit
id: a published commit, an unpublished proposal, or an unattached snapshot. A
string that names both a branch and a commit is refused; name the branch's
head by its commit id instead. The equivalent HTTP route is
`GET /graphs/{graph_id}/diff?from=<side>&to=<side>`, and the GQ statement
`branch diff <from> to <to>` answers the same comparison at `POST /query`,
a commit id quoted (`branch diff "<commit-id>" to main`).

The result is the net change from the `from` state to the `to` state, in the
`commit changes` change shape and order, with `from_commit_id` and
`to_commit_id` naming the exact commits the sides resolved to. There is no
`cause`: a range of commits has no single author. Intermediate history is not
replayed, so an update that was later reverted produces nothing, and a delete
followed by an equal reinsert produces nothing. A diff from a commit's first
parent to the commit equals that commit's `commit changes`, without the cause.

Comparing two branch heads also shows what the target changed since the
branches diverged, reversed. To review a branch, use the branch form below.

The kind, type and operation filters, `--limit` and `--page-token` work as for
`commit changes`. A page token keeps the commits the first page resolved, so
later pages answer for them even after the branches move. Each continuation is
checked against the request's sides, on the server and in the embedded CLI
alike. A side spelled as a commit id reaches only that commit. A branch side
reaches its head now, any of its earlier heads within its last 1,024 commits,
and any commit the caller may read as a side of its own. A token naming any
other commit is refused with `400`; start the diff again without it. A diff
across a
schema change returns `409` with reason `schema_boundary`, and a side whose
history was reclaimed returns `410` with `change_feed_gap`.

Types unchanged between the two points are skipped. A changed type is
compared row by row. For a single commit the engine reads the fragments that
commit wrote. Across several commits it pairs the two versions' live rows by
Lance's stable row id and reads only the rows whose version stamp differs or
that exist on one side alone, so the cost follows the changed rows and the
fragments that hold them, not the table's size, and stays flat across a
compaction. That pairing applies when the `from` side is on the `to` side's
history with no merge commit after it: a branch review whose merge base is on
the source's first-parent history, and a two-point diff whose `to` names a
branch whose first-parent chain holds `from`. A merge, a fast forward included,
can give a type the merged branch's rows, whose history never passed through
`from`. A diff of two diverged heads compares every row of each changed type,
and so do a review of a branch that has merged its target since the fork, a
window that crosses a merge commit, and a merge commit's own changes, except
for a type the merge wrote in one step. The `change_lineage`
[session setting](https://www.omnigraph.dev/docs/queries-search/settings.md) selects the comparison for every
change read: `on` (the default) pairs rows by id, `off` compares every row,
and `verify` runs both and fails the page where they disagree, which a debug
build does by default.

## Review a branch

```bash
omnigraph branch diff feature --into main --target ./graph.omni --json
omnigraph branch merge-base feature --into main --target ./graph.omni --json
```

`branch diff` reports what `feature` changed since its merge base with `main`
(`main` when `--into` is omitted): the net change from the merge base to the
head of `feature`. Changes `main` made after the merge base do not appear. The
response also names the base as `base_commit_id`. `branch merge-base` prints
that commit alone, the one a merge of `feature` into `main` would classify
against. While `feature` has never merged `main` in, the base is on its
first-parent history, and `changes poll --branch feature --start
after:<merge-base>` replays its commits since then; a merge commit in that
range still carries the changes it brought in. A base off `feature`'s
first-parent history is refused as a start: for example, after `main` is
merged into a `feature` that had diverged from it, the base is the `main`
commit that merge brought in. `branch diff` gives the net change from any
base.

The HTTP routes are `GET /graphs/{graph_id}/branches/diff?source=&target=` and
`GET /graphs/{graph_id}/branches/merge-base?source=&target=`; the GQ statements
are `branch diff feature into main` and `branch merge-base feature into main`.

A statement answers rows through `POST /query` or `omnigraph query -e`. A
`branch diff` row has `kind`, `type` (the type's name), `id`, `op`, `before`
and `after`; the compared commits and the token for the next page travel in
the answer's `page` object, and `after page "<token>"` (then `limit <n>`)
continues it. A `branch merge-base` row names `source`, `target`, both heads
and `merge_base_commit_id`. Statements take no kind, type or operation filter
yet; use the routes or CLI commands for those. To see whether
the merge would succeed, run it as a [dry run](https://www.omnigraph.dev/docs/branching/merge.md#preview-a-merge).

## Follow a branch

```bash
# Start at the current head. Existing history is not replayed.
omnigraph changes poll --start now --target ./graph.omni --json

# Replay the branch's first-parent history.
omnigraph changes poll --start beginning --target ./graph.omni --json

# Continue after a known commit, or resume from a saved cursor.
omnigraph changes poll --start after:<commit-id> --target ./graph.omni --json
omnigraph changes poll --cursor <cursor> --target ./graph.omni --json
```

`now` is the default when neither `--start` nor `--cursor` is supplied.
Use `--branch` to follow a branch other than `main`. The same kind, type,
operation filters, and `--limit` supported by `commit changes` are available
here.

Each poll captures a fixed branch head and returns complete commits in
first-parent order. A commit with no logical entity changes may still appear
as an empty block and advance the feed.

The durable `cursor` appears only on the terminal page, after every returned
commit block is complete. A page ending partway through a commit has only a
`next_page_token`. On the terminal page, `caught_up` says whether the poll
reached its captured head. The CLI consumes feed page tokens itself and prints
the cursor only after reaching that terminal page.

Delivery is at least once: retrying a cursor may replay the next complete
commit. Apply each block idempotently by `graph_commit_id`, then persist the
terminal cursor atomically with the applied blocks.

Cursors are opaque and caller-owned; the server stores no consumer position.
A cursor is bound to its graph, branch lifetime, and filter scope. Reusing it
with a different scope, or using a page token as a cursor, returns `400`.

The HTTP route is `GET /graphs/{graph_id}/changes`. Its `cursor`, `start`,
and `page_token` parameters are mutually exclusive.

## Recover from a retention gap

A cursor does not prevent `cleanup` from reclaiming old history. When a feed,
commit diff or diff can no longer be read, the server returns `410` with
`change_feed_gap`, including `first_unreadable_commit_id` and, when
available, the rejected `cursor`. Retrying the same cursor cannot close the
gap; install a new baseline:

```bash
omnigraph changes baseline --out snapshot.jsonl --target ./graph.omni --json
```

If a poll has already accumulated complete readable blocks before it reaches a
gap, it first returns those blocks with `caught_up: false`; polling the
returned cursor then produces the deterministic `410`.

The HTTP equivalent is `POST /graphs/{graph_id}/changes/baseline`. Send `{}`
for the default `main` scope or include branch and filter fields. The
`application/x-ndjson` response streams an exact entity snapshot followed by
one terminal record:

```json
{"baseline":{"snapshot_commit_id":"...","resume_cursor":"..."}}
```

Snapshot records use the export line format, and a Blob property holds the
same value shapes as a change image. That includes the
`{"uri", "offset", "length"}` object for a stored reference to a byte range of
an object, which export refuses; a snapshot holding one does not reload with
`load` (see [Blobs](https://www.omnigraph.dev/docs/schema/blobs.md)).

An interrupted stream has no terminal record and therefore no usable cursor.
Install the complete snapshot durably before saving `resume_cursor`; the
resumed feed begins with commits after the captured snapshot.

Baseline kind and type filters select the snapshot contents. An operation
filter applies only to the resumed feed. Baselines require the `export`
policy action; commit changes, diffs and feed polling require `read`. A diff
needs `read` on the branch each side resolves to; a side the actor cannot read
answers `404` exactly as a side that names nothing, whatever the other side
names. The engine reads a commit whose branch was deleted while a live
branch retains it (a stacked branch's merge base after its parent was merged
and deleted): diffs, commit changes, reads at the commit and the feed open the
retired incarnation by its exact commit. The HTTP `commit changes` route still
needs `read` on the branch that wrote the commit, so a policy that does not
grant the deleted name answers `404` there. A commit that no live branch retains,
or whose recorded incarnation was reclaimed, answers the same `404` as a
commit that names nothing; the error names the spelling the caller used, never
the deleted branch. Branch creation from such a commit still refuses with
`branch_deleted`.
`branch diff` and `branch merge-base` need `read` on both branches, every
page included, and answer `403` otherwise. On a later page, a commit the
token names that its side no longer resolves to needs `read` on the branch
that wrote it, unless it was an earlier head of the side's branch, such as a
fork's first head that `main` wrote. An unknown or unreadable one answers the
same `400`.

The CLI's durable `--out` installation is available on POSIX platforms. The
file contains only snapshot entity records, not the terminal handshake. The CLI
syncs and atomically replaces it before printing
`{"snapshot_commit_id":"...","resume_cursor":"..."}` to JSON stdout. Concurrent
captures to the same path stay serialized until the cursor output is flushed.
A cursor-output failure returns an error; the installed snapshot remains in place.