omnigraph/docs/releases/v0.8.0.md

Omnigraph v0.8.0

This release moves the graph commit lineage into __manifest (RFC-013 Phase 7), retires the two legacy commit-graph datasets, and surfaces the storage-format version to operators. It is the first release with an internal-schema change since v0.4.0, and storage is strict-single-version: there is no in-place migration — a graph from an older release is rebuilt via export/import. Read the upgrade notes before rolling it out.

Graph lineage now lives in __manifest (internal schema v4)

The graph commit DAG (commits, parents, merge parents, per-branch heads, and the authoring actor) is now stored in __manifest as graph_commit / graph_head rows, written in the same commit (CAS) as the table-version rows of a graph publish. Previously the lineage lived in a separate _graph_commits.lance dataset written after the manifest commit, leaving a narrow window where a crash could land a manifest version with no matching lineage row. Folding the lineage into the publish closes that gap by construction: a graph commit and its lineage now land atomically at one manifest version. The in-memory commit graph is a pure projection of those manifest rows.

This bumps the __manifest internal schema stamp to v4.

The _graph_commits.lance / _graph_commit_actors.lance tables are retired

With lineage in __manifest and branch authority already on the manifest, the two legacy commit-graph datasets are no longer created, read, or written. A graph this release creates has neither. This removes two cold-open directory listings per graph open and simplifies maintenance (optimize compacts only __manifest among the internal tables now).

Strict-single-version storage: rebuild via export/import, no in-place migration

Internal schema v4 is a hard version gate, enforced in both directions on every open (read-write and read-only):

• A graph stamped below v4 (created by an older release whose storage format this binary does not read) is refused with a rebuild-via-export/import message. There is no in-place upgrade: export the graph with the older binary, then omnigraph init + omnigraph load with this one. Data, vectors, and blobs are preserved; commit history and branches are not carried over. See the upgrade guide.
• A graph stamped above v4 (created by a newer release) is refused with an upgrade omnigraph before opening this graph error, so an old binary cannot silently misread a newer format.

This replaces the speculative one-time on-disk migration that earlier drafts of this release described. The rationale (lower long-term liability than carrying in-place migration code for a pre-release format) is in docs/dev/versioning.md.

See the storage-format version

Operators can now read the internal-schema version directly instead of discovering it through a refusal:

• omnigraph version prints an internal-schema <N> line (the version this binary serves).
• omnigraph snapshot reports the opened graph's on-disk internal_schema_version.
• The server GET /healthz response includes internal_schema_version (the binary's served version).

Upgrade order

Upgrade every binary that touches a graph to v0.8.0 together. A mixed fleet where an older binary still writes a graph another has stamped v4 is unsupported, as with any internal-schema bump. To move a pre-v4 graph forward, follow the upgrade guide: export with the old binary, then init + load with v0.8.0.