omnigraph/docs/releases/v0.7.0.md

Omnigraph v0.7.0

v0.7.0 takes the cluster control plane to object storage and overhauls the configuration architecture around two single-owner surfaces. A cluster — state ledger, content-addressed catalog, and graph data — can now live entirely on an S3-compatible bucket, and a server can boot from that bucket with no local files at all. Operator identity, credentials, and personal aliases move to a home-level config; the legacy combined omnigraph.yaml enters a guided, staged deprecation.

Highlights

• Clusters on object storage (storage:). cluster.yaml gains an optional storage: s3://bucket/prefix root. Every stored byte — the state ledger, lock, recovery sidecars, approval artifacts, catalog blobs, and the derived graph roots (<storage>/graphs/<id>.omni) — flows through one storage layer, so file:// (the default, byte-compatible with existing clusters) and s3:// are a single code path. The ledger's compare-and-swap uses S3 conditional writes (If-Match / If-None-Match), verified against AWS semantics, RustFS, and Tigris-backed stores; the state lock is genuinely cross-machine on object storage.
• Config-free serving: --cluster s3://bucket/prefix. The server accepts a bare storage-root URI and boots from the applied revision on the bucket — the ledger and catalog are the whole deployment artifact. Policy bundles serve as digest-verified content from the catalog (never re-read from disk), closing the last gap for fully remote clusters. The preferred container shape becomes bucket, no volume (see docs/user/deployment.md).
• Per-operator configuration (~/.omnigraph/). A home-level config carries operator identity (operator.actor, the new last hop of the --as chain), output defaults, named servers, and personal aliases. $OMNIGRAPH_HOME relocates it; $OMNIGRAPH_CONFIG now stands in for --config in both binaries.
• Credentials keyed by server name. omnigraph login <server> stores a bearer token in ~/.omnigraph/credentials (created 0600; over- permissive files are refused). Token resolution for a request whose URL matches an operator-defined server: OMNIGRAPH_TOKEN_<NAME> env → the credentials file → the legacy bearer_token_env chain unchanged. A token is only ever sent to the server it is keyed to.
• Operator targeting and aliases. --server <name> (with --graph <id> for multi-graph servers) addresses operator-defined endpoints on every remote-capable command. Operator aliases are pure bindings — personal name → (server, graph, stored-query name, default params) — invoking catalog-owned stored queries; they carry no query content.
• omnigraph.yaml deprecation begins. Loading the legacy file prints a per-key notice naming each present key's new home (OMNIGRAPH_SUPPRESS_YAML_DEPRECATION=1 to silence in CI). omnigraph config migrate proposes — and with --write, applies — the split: team half to a ready-to-review cluster.yaml, personal half merged into the operator config (existing entries always win). omnigraph init no longer scaffolds the file. Migrated teams can set OMNIGRAPH_NO_LEGACY_CONFIG=1 to turn any legacy-file load into a hard error. The file itself keeps working until its removal at the next major version.

Breaking / behavior changes

• omnigraph init no longer writes an omnigraph.yaml into the working directory. Start cluster configs from the documentation templates, or run omnigraph config migrate against an existing legacy file.
• Loading a legacy omnigraph.yaml now emits a deprecation block on stderr (suppressible; see above). Output on stdout is unchanged.
• ServingPolicy (cluster crate API) carries verified policy content instead of a blob path; read_serving_snapshot and several cluster command entry points are now async.

Upgrade notes

• Existing clusters need no migration: an absent storage: key keeps the config-directory layout byte-for-byte.
• Existing omnigraph.yaml setups keep working through the deprecation window; omnigraph config migrate produces the recommended split.
• Operator setup is three lines: mkdir -p ~/.omnigraph, write operator.actor (and servers:) into ~/.omnigraph/config.yaml, then echo $TOKEN | omnigraph login <server>.

Internals

• The cluster, server, and CLI crates were modularized (the 7.9k-line cluster lib.rs is now eight focused modules; the server and CLI test monoliths split into per-area suites) — pure code movement, no behavior change.
• New gated end-to-end suites run the full cluster lifecycle against a real S3-compatible store in CI, including a lock-release regression and a config-free server boot from a bare bucket URI.
• The deployment guide gains the bucket-no-volume container recipe for AWS and Railway, validated against a live Railway deployment (Railway buckets are S3-compatible and pass the conditional-write contract test).