feat(cli): cluster-managed maintenance addressing + init signpost (RFC-010 Slice 3) (#221)

* feat(cluster): cluster_root_for_graph_uri detection helper (RFC-010 Slice 3)

Public helper the CLI uses to refuse `init` into a cluster-managed location:
given a graph storage URI of the cluster layout (`<root>/graphs/<id>.omni`),
return the cluster root if `<root>` holds `__cluster/state.json`, else None.

Cheap by construction — a URI that doesn't match the `<root>/graphs/<id>.omni`
shape returns None with zero I/O, so ordinary `init` targets never probe
storage. Works for file:// and s3:// via the storage adapter. Adds two
ClusterStore accessors (`display_root`, `has_state`).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* feat(cli): cluster-managed maintenance addressing + init signpost (RFC-010 Slice 3)

Two cluster-graph-aware CLI behaviors, sharing the cluster-resolution path.

Maintenance addressing. `optimize`/`repair`/`cleanup` gain
`--cluster <dir|s3://…> --cluster-graph <id>`, which resolves the graph's
storage URI from the served cluster snapshot (the same truth a `--cluster`
server boots from — `read_serving_snapshot*`) and opens it embedded. The
operator no longer hand-types `<storage>/graphs/<id>.omni`. A distinct flag is
required because the global `--graph` is `requires = server` and means a remote
multi-graph id. clap enforces both-or-neither and exclusion with the positional
URI / `--target`; an unserved graph errors loudly, pointing at `cluster apply`.

init signpost. `init` refuses a cluster-managed positional path (the
`<root>/graphs/<id>.omni` layout where `<root>` holds `__cluster/state.json`,
detected by `cluster_root_for_graph_uri`) and points at `cluster apply` — graphs
in an established cluster are created with ledger/recovery/approvals, not by
hand. The check is gated on the path shape, so ordinary `init` does no extra I/O
and existing pre-apply cluster-graph inits are unaffected.

planes guard remediation now also mentions `--cluster … --cluster-graph …`
(the two Slice-1 guard-string tests track it). Docs updated (cli-reference
Command planes, maintenance.md, cluster.md §7); the stale "no S3-hosted cluster
directories" limitation is dropped (RFC-006 landed it).

Tests (cli_cluster.rs, reusing the apply-a-cluster fixture): resolve by id,
unknown-id error, `--cluster` requires `--cluster-graph`, init refusal +
signpost, and ordinary init still works.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(cli): resolve cluster graphs from the state ledger, not the serving snapshot

Addresses the Greptile review on #221. `read_serving_snapshot*` does
all-or-nothing serving validation — recovery-sidecar checks plus a digest
verify of every catalog payload (query .gq, policy blobs). Using it to resolve
a maintenance target coupled `optimize`/`repair`/`cleanup` to the readiness of
unrelated resources: a single corrupt policy blob, or a pending recovery sweep,
would block the command before it could touch the graph — worst for `repair`,
the tool you reach for *when the cluster is degraded*.

Add `omnigraph_cluster::resolve_graph_storage_uri(cluster, graph_id)`: read the
state ledger, confirm the graph is in the applied revision, return
`graph_root(id)` — the URI is deterministically derivable, no catalog
validation. The CLI's cluster resolver now calls it.

Test: `optimize --cluster … --cluster-graph …` still resolves after the catalog
payloads (`__cluster/resources/`) are removed — the ledger-only path is not
blocked by degraded/unrelated catalog state.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

crates/omnigraph-cli/src/cli.rs

@@ -238,6 +238,13 @@ pub(crate) enum Command {
         target: Option<String>,
         #[arg(long)]
         config: Option<PathBuf>,
+        /// Cluster directory or storage-root URI; with --cluster-graph, resolves
+        /// the graph's storage URI from the served cluster state.
+        #[arg(long, conflicts_with_all = ["uri", "target"], requires = "cluster_graph")]
+        cluster: Option<String>,
+        /// Graph id within --cluster.
+        #[arg(long, requires = "cluster")]
+        cluster_graph: Option<String>,
         #[arg(long)]
         json: bool,
     },
@@ -249,6 +256,13 @@ pub(crate) enum Command {
         target: Option<String>,
         #[arg(long)]
         config: Option<PathBuf>,
+        /// Cluster directory or storage-root URI; with --cluster-graph, resolves
+        /// the graph's storage URI from the served cluster state.
+        #[arg(long, conflicts_with_all = ["uri", "target"], requires = "cluster_graph")]
+        cluster: Option<String>,
+        /// Graph id within --cluster.
+        #[arg(long, requires = "cluster")]
+        cluster_graph: Option<String>,
         /// Publish verified maintenance drift. Without this flag, repair only
         /// previews what it would do.
         #[arg(long)]
@@ -268,6 +282,13 @@ pub(crate) enum Command {
         target: Option<String>,
         #[arg(long)]
         config: Option<PathBuf>,
+        /// Cluster directory or storage-root URI; with --cluster-graph, resolves
+        /// the graph's storage URI from the served cluster state.
+        #[arg(long, conflicts_with_all = ["uri", "target"], requires = "cluster_graph")]
+        cluster: Option<String>,
+        /// Graph id within --cluster.
+        #[arg(long, requires = "cluster")]
+        cluster_graph: Option<String>,
         /// Number of recent versions to keep per table. Either `--keep` or
         /// `--older-than` (or both) must be set.
         #[arg(long)]

crates/omnigraph-cli/src/helpers.rs

@@ -513,6 +513,37 @@ pub(crate) fn resolve_local_uri(
     Ok(resolve_local_graph(config, cli_uri, cli_target, operation)?.uri)
 }
 
+/// Resolve a storage-plane verb's target to a direct storage URI (RFC-010
+/// Slice 3). `--cluster <dir|uri> --cluster-graph <id>` resolves the graph's
+/// storage URI from the **served cluster state** (the truth a `--cluster`
+/// server serves); otherwise the ordinary positional-URI / `--target` path.
+/// clap enforces both-or-neither and exclusion with `uri`/`--target`, so the
+/// mismatched arm is defensive.
+pub(crate) async fn resolve_storage_uri(
+    config: &OmnigraphConfig,
+    cli_uri: Option<String>,
+    cli_target: Option<&str>,
+    cluster: Option<&str>,
+    cluster_graph: Option<&str>,
+    operation: &str,
+) -> Result<String> {
+    match (cluster, cluster_graph) {
+        (Some(cluster), Some(graph_id)) => resolve_cluster_graph_uri(cluster, graph_id).await,
+        (None, None) => resolve_local_uri(config, cli_uri, cli_target, operation),
+        _ => bail!("--cluster and --cluster-graph must be given together"),
+    }
+}
+
+/// Look up a graph's storage URI from a cluster's applied state ledger. Uses
+/// the lightweight `resolve_graph_storage_uri` (NOT the full serving-snapshot
+/// validation), so maintenance — especially `repair` — works even when an
+/// unrelated catalog payload is corrupt or a recovery sweep is pending.
+async fn resolve_cluster_graph_uri(cluster: &str, graph_id: &str) -> Result<String> {
+    omnigraph_cluster::resolve_graph_storage_uri(cluster, graph_id)
+        .await
+        .map_err(|diagnostic| color_eyre::eyre::eyre!("{}", diagnostic.message))
+}
+
 pub(crate) fn resolve_branch(
     config: &OmnigraphConfig,
     cli_branch: Option<String>,

crates/omnigraph-cli/src/main.rs

@@ -147,6 +147,16 @@ async fn main() -> Result<()> {
             }
         }
         Command::Init { schema, uri, force } => {
+            // RFC-010 Slice 3: graphs inside an established cluster are created
+            // by `cluster apply` (which records ledger/recovery/approvals), not
+            // by hand-running `init` into the cluster's storage layout.
+            if let Some(root) = omnigraph_cluster::cluster_root_for_graph_uri(&uri).await {
+                bail!(
+                    "`{uri}` is inside cluster `{root}`. Graphs in a cluster are created by \
+                     `cluster apply` (which records ledger, recovery, and approvals), not `init`. \
+                     Declare the graph in cluster.yaml and run `cluster apply`."
+                );
+            }
             let schema_source = fs::read_to_string(&schema)?;
             ensure_local_graph_parent(&uri)?;
             Omnigraph::init_with_options(
@@ -783,10 +793,20 @@ async fn main() -> Result<()> {
             uri,
             target,
             config,
+            cluster,
+            cluster_graph,
             json,
         } => {
             let config = load_cli_config(config.as_ref())?;
-            let uri = resolve_local_uri(&config, uri, target.as_deref(), "optimize")?;
+            let uri = resolve_storage_uri(
+                &config,
+                uri,
+                target.as_deref(),
+                cluster.as_deref(),
+                cluster_graph.as_deref(),
+                "optimize",
+            )
+            .await?;
             let db = Omnigraph::open(&uri).await?;
             let stats = db.optimize().await?;
             if json {
@@ -823,12 +843,22 @@ async fn main() -> Result<()> {
             uri,
             target,
             config,
+            cluster,
+            cluster_graph,
             confirm,
             force,
             json,
         } => {
             let config = load_cli_config(config.as_ref())?;
-            let uri = resolve_local_uri(&config, uri, target.as_deref(), "repair")?;
+            let uri = resolve_storage_uri(
+                &config,
+                uri,
+                target.as_deref(),
+                cluster.as_deref(),
+                cluster_graph.as_deref(),
+                "repair",
+            )
+            .await?;
             let db = Omnigraph::open(&uri).await?;
             let stats = db
                 .repair(omnigraph::db::RepairOptions { confirm, force })
@@ -906,13 +936,23 @@ async fn main() -> Result<()> {
             uri,
             target,
             config,
+            cluster,
+            cluster_graph,
             keep,
             older_than,
             confirm,
             json,
         } => {
             let config = load_cli_config(config.as_ref())?;
-            let uri = resolve_local_uri(&config, uri, target.as_deref(), "cleanup")?;
+            let uri = resolve_storage_uri(
+                &config,
+                uri,
+                target.as_deref(),
+                cluster.as_deref(),
+                cluster_graph.as_deref(),
+                "cleanup",
+            )
+            .await?;
 
             let older_than_dur = older_than.as_deref().map(parse_duration_arg).transpose()?;
 

crates/omnigraph-cli/src/planes.rs

@@ -139,7 +139,7 @@ pub(crate) fn guard_addressing(cli: &Cli) -> Result<()> {
         // required positional URI), so its remediation drops the `--target` half.
         Plane::Storage => match cli.command {
             Command::Init { .. } => "Pass a storage URI.",
-            _ => "Use --target <name> or a storage URI.",
+            _ => "Use --target <name>, a storage URI, or --cluster <dir> --cluster-graph <id>.",
         },
         Plane::Control => "It operates on a cluster directory (pass --config <dir>).",
         Plane::Session => "It does not address a graph.",