feat(cluster): the storage: root — state, catalog, and graph roots relocatable

cluster.yaml gains an optional storage: URI deciding where everything the
cluster STORES lives: the state ledger, lock, content-addressed catalog,
recovery sidecars, approval artifacts, and the derived graph roots
(<storage>/graphs/<id>.omni). Absent, it defaults to the config directory
itself — the original layout, byte-compatible, so pre-existing clusters and
the whole test suite are untouched. Declared configuration always stays in
the working tree (Terraform's config-local/state-remote split); credentials
are env-only, never in cluster.yaml.

Every command resolves its store from the declared root (a bad root is a
loud invalid_storage_root). Graph-root derivation, the delete executor
(prefix delete via the adapter), the sweep's existence probes, the catalog
payload write/verify/read paths, and the serving snapshot all flow through
ClusterStore — the last raw-fs holdouts for stored state are gone, and the
deny-list gains the rule that keeps it that way.

Tests: default-layout byte-compat, a file:// root relocating the entire
cluster (ledger+catalog+graphs under the new root, nothing under the config
dir, serving snapshot follows), invalid-root validation. 98 in-crate + 9
failpoints + full workspace gate green. The s3:// flavor lands with PR 3's
gated RustFS e2e.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/dev/invariants.md

@@ -206,6 +206,10 @@ case is exceptional.
   fits.
 - Discarding retrieval score/rank before fusion or projection decisions.
 - Auto-creating placeholder nodes for orphan edges.
+- Raw filesystem I/O for cluster-stored state (ledger, lock, sidecars,
+  approvals, catalog) outside the cluster crate's storage module — every
+  stored byte goes through the engine `StorageAdapter` so `file://` and
+  `s3://` stay one code path.
 - Wire-protocol-specific code in compiler or engine crates.
 - Cloud-only correctness fixes or forks of the OSS engine for correctness.
 - Mutating immutable substrate state in place, including Lance fragments or

docs/user/cluster-config.md

@@ -101,6 +101,20 @@ updates all of its queries together. Paths are relative to the config
 directory — the cluster is one explicit folder, so no `./` prefixes are
 needed.
 
+`storage:` (optional) is the **storage root URI** for everything the cluster
+stores — the state ledger, lock, content-addressed catalog, recovery
+sidecars, approval artifacts, and the derived graph roots
+(`<storage>/graphs/<id>.omni`). Absent, it defaults to the config directory
+itself (the original layout, byte-compatible with pre-existing clusters).
+`s3://bucket/prefix` puts the whole cluster on S3-compatible object storage:
+the ledger CAS uses conditional writes (verified against AWS S3 semantics and
+RustFS), the lock becomes genuinely cross-machine, and graph roots are
+engine-native S3 URIs. Credentials are **never** in `cluster.yaml` — the
+standard `AWS_*` environment contract applies, identical to graph storage.
+Declared configuration (`cluster.yaml` and the schema/query/policy sources it
+references) always stays in the working tree: config is versioned in git,
+state lives in the store — the Terraform split.
+
 `metadata.name` is a display label. `state.backend` may be omitted or set to
 `cluster`; external state backends are reserved for a later stage. `state.lock`
 defaults to `true`. When enabled, `cluster plan`, `cluster apply`,

docs/user/cluster.md

@@ -40,6 +40,8 @@ company-brain/
 ```yaml
 # cluster.yaml
 version: 1
+# storage: s3://omnigraph-local/clusters/company-brain   # optional: put the
+#   ledger, catalog, and graph data on object storage (default: this folder)
 metadata:
   name: company-brain
 graphs: