feat(cli): RFC-010 Slice 1 — declared plane capability surface + honest addressing (#217)

* feat(cli): declared plane capability surface + wrong-plane guard (RFC-010 Slice 1)

New `planes.rs` is the single source of truth for which plane each subcommand
belongs to (Data / Storage / Control / Session). `command_plane` is an
exhaustive match — adding a `Command` variant is a compile error until its
plane is declared, so the surface cannot silently drift from the command set.
It descends into the nested enums where the plane differs per subcommand
(`schema plan` is storage while `schema show/apply` are data; `queries
validate` opens the graph while `queries list` reads only config).

`guard_addressing` runs once in `main` before dispatch: the data-plane
addressing flags `--server`/`--graph` on any non-data verb now fail with one
declared, pinned error instead of being silently ignored (`optimize --server
prod` previously dropped `--server`). `init`'s message drops the `--target`
half since it takes only a positional URI today.

Test: `cli_schema_config::schema_plan_with_server_flag_errors_wrong_plane`
pins the per-subcommand label, proving the guard descends into the nested enum.

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

* feat(cli): storage-plane verbs fail loudly on a remote target (RFC-010 Slice 1)

`optimize`/`repair`/`cleanup` switch from `resolve_uri` to `resolve_local_uri`,
so a `--target` (or positional URI) that resolves to a remote server now fails
with a declared storage-plane message instead of whatever `Omnigraph::open`
said about an `http(s)://` URI. The `resolve_local_graph` bail is reworded to
that storage-plane message, so every storage verb already on the local resolver
(`schema plan`, `queries validate`, `lint`) speaks with one voice.

Net: `optimize --target knowledge` resolves to the graph's storage URI and runs
embedded; `optimize --target prod` (remote) fails loudly; `optimize --server`
is caught earlier by the guard. Positional-URI invocations are unchanged.

Tests (pinned strings, per RFC-010's test plan): optimize happy path on a local
graph, `optimize --server` wrong-plane error, `optimize <https>` storage-plane
error; the existing `query_lint_rejects_http_targets_without_schema` assertion
is updated to the new shared message.

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

---------

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

crates/omnigraph-cli/src/helpers.rs

@@ -464,8 +464,11 @@ pub(crate) fn resolve_local_graph(
     let graph = resolve_cli_graph(config, cli_uri, cli_target)?;
     if graph.is_remote {
         bail!(
-            "{} is only supported against local graph URIs in this milestone",
-            operation
+            "`{}` is a storage-plane command and needs direct storage access; \
+             the resolved target is a remote server ({}). Pass the graph's \
+             file:// or s3:// URI.",
+            operation,
+            graph.uri
         );
     }
     Ok(graph)

crates/omnigraph-cli/src/main.rs

@@ -49,6 +49,7 @@ mod cli;
 mod client;
 mod helpers;
 mod output;
+mod planes;
 use cli::*;
 use helpers::*;
 use output::*;
@@ -70,6 +71,10 @@ async fn main() -> Result<()> {
         Cli::from_arg_matches(&matches)?
     };
     let http_client = build_http_client()?;
+    // RFC-010 Slice 1: reject data-plane addressing flags (--server/--graph) on
+    // a verb that doesn't live on the data plane, from one declared table —
+    // before any per-command dispatch.
+    planes::guard_addressing(&cli)?;
     match cli.command {
         Command::Config { command } => match command {
             ConfigCommand::Migrate { config, write, json } => {
@@ -781,7 +786,7 @@ async fn main() -> Result<()> {
             json,
         } => {
             let config = load_cli_config(config.as_ref())?;
-            let uri = resolve_uri(&config, uri, target.as_deref())?;
+            let uri = resolve_local_uri(&config, uri, target.as_deref(), "optimize")?;
             let db = Omnigraph::open(&uri).await?;
             let stats = db.optimize().await?;
             if json {
@@ -823,7 +828,7 @@ async fn main() -> Result<()> {
             json,
         } => {
             let config = load_cli_config(config.as_ref())?;
-            let uri = resolve_uri(&config, uri, target.as_deref())?;
+            let uri = resolve_local_uri(&config, uri, target.as_deref(), "repair")?;
             let db = Omnigraph::open(&uri).await?;
             let stats = db
                 .repair(omnigraph::db::RepairOptions { confirm, force })
@@ -907,7 +912,7 @@ async fn main() -> Result<()> {
             json,
         } => {
             let config = load_cli_config(config.as_ref())?;
-            let uri = resolve_uri(&config, uri, target.as_deref())?;
+            let uri = resolve_local_uri(&config, uri, target.as_deref(), "cleanup")?;
 
             let older_than_dur = older_than.as_deref().map(parse_duration_arg).transpose()?;
 

crates/omnigraph-cli/src/planes.rs

@@ -0,0 +1,151 @@
+//! Declared CLI "planes" (RFC-010 Slice 1).
+//!
+//! Every subcommand belongs to exactly one plane. This classification is the
+//! single source of truth the wrong-plane guard consumes — and that later
+//! RFC-010 slices (the capability surface, plane-grouped help) will consume
+//! too. The `command_plane` match is **exhaustive on purpose**: adding a
+//! `Command` variant is a compile error until its plane is declared, so the
+//! surface cannot silently drift from the command set.
+//!
+//! See [docs/dev/rfc-010-cli-planes-restructure.md].
+
+use color_eyre::Result;
+use color_eyre::eyre::bail;
+
+use crate::cli::{Cli, Command, QueriesCommand, SchemaCommand};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum Plane {
+    /// Runs against a graph, embedded **or** via `--server` (the `GraphClient`
+    /// axis). The only plane on which the data-plane addressing flags
+    /// (`--server`/`--graph`) apply.
+    Data,
+    /// Direct storage access; no server. Maintenance + local-only inspection
+    /// that must work with the server down.
+    Storage,
+    /// Operates on a cluster directory, not a graph URI.
+    Control,
+    /// Touches no graph at all — session / config / local tooling.
+    Session,
+}
+
+impl std::fmt::Display for Plane {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(match self {
+            Plane::Data => "data",
+            Plane::Storage => "storage",
+            Plane::Control => "control",
+            Plane::Session => "session",
+        })
+    }
+}
+
+/// The plane a subcommand belongs to. Exhaustive — a new `Command` variant
+/// will not compile until classified. Descends into the nested enums where
+/// the plane differs per subcommand (`schema plan` is storage while `schema
+/// show`/`apply` are data; `queries validate` opens the graph while `queries
+/// list` only reads config).
+pub(crate) fn command_plane(cmd: &Command) -> Plane {
+    match cmd {
+        Command::Query { .. }
+        | Command::Mutate { .. }
+        | Command::Load { .. }
+        | Command::Ingest { .. }
+        | Command::Branch { .. }
+        | Command::Snapshot { .. }
+        | Command::Export { .. }
+        | Command::Commit { .. }
+        | Command::Graphs { .. } => Plane::Data,
+        Command::Schema {
+            command: SchemaCommand::Show { .. } | SchemaCommand::Apply { .. },
+        } => Plane::Data,
+        Command::Schema {
+            command: SchemaCommand::Plan { .. },
+        } => Plane::Storage,
+        Command::Queries {
+            command: QueriesCommand::Validate { .. },
+        } => Plane::Storage,
+        Command::Queries {
+            command: QueriesCommand::List { .. },
+        } => Plane::Session,
+        Command::Init { .. }
+        | Command::Optimize { .. }
+        | Command::Repair { .. }
+        | Command::Cleanup { .. }
+        | Command::Lint { .. } => Plane::Storage,
+        Command::Cluster { .. } => Plane::Control,
+        Command::Policy { .. }
+        | Command::Embed(_)
+        | Command::Login { .. }
+        | Command::Logout { .. }
+        | Command::Config { .. }
+        | Command::Version => Plane::Session,
+    }
+}
+
+/// User-facing label for a subcommand (descends one level for the nested
+/// families so messages read `schema plan`, `queries validate`, etc.).
+pub(crate) fn command_label(cmd: &Command) -> &'static str {
+    match cmd {
+        Command::Version => "version",
+        Command::Login { .. } => "login",
+        Command::Logout { .. } => "logout",
+        Command::Config { .. } => "config",
+        Command::Embed(_) => "embed",
+        Command::Init { .. } => "init",
+        Command::Load { .. } => "load",
+        Command::Ingest { .. } => "ingest",
+        Command::Branch { .. } => "branch",
+        Command::Schema { command } => match command {
+            SchemaCommand::Plan { .. } => "schema plan",
+            SchemaCommand::Apply { .. } => "schema apply",
+            SchemaCommand::Show { .. } => "schema show",
+        },
+        Command::Lint { .. } => "lint",
+        Command::Queries { command } => match command {
+            QueriesCommand::Validate { .. } => "queries validate",
+            QueriesCommand::List { .. } => "queries list",
+        },
+        Command::Snapshot { .. } => "snapshot",
+        Command::Export { .. } => "export",
+        Command::Commit { .. } => "commit",
+        Command::Query { .. } => "query",
+        Command::Mutate { .. } => "mutate",
+        Command::Policy { .. } => "policy",
+        Command::Optimize { .. } => "optimize",
+        Command::Repair { .. } => "repair",
+        Command::Cleanup { .. } => "cleanup",
+        Command::Cluster { .. } => "cluster",
+        Command::Graphs { .. } => "graphs",
+    }
+}
+
+/// Reject the data-plane addressing flags (`--server`/`--graph`) on any verb
+/// that does not live on the data plane. This replaces the old silent-ignore
+/// — e.g. `optimize --server prod` previously dropped `--server` and tried to
+/// resolve a default target, failing (if at all) with an unrelated message.
+/// Now it fails with one honest, declared error. RFC-010 Slice 1.
+pub(crate) fn guard_addressing(cli: &Cli) -> Result<()> {
+    if cli.server.is_none() && cli.graph.is_none() {
+        return Ok(());
+    }
+    let plane = command_plane(&cli.command);
+    if plane == Plane::Data {
+        return Ok(());
+    }
+    let label = command_label(&cli.command);
+    let how = match plane {
+        // `init` is the one storage verb with no `--target` today (it takes a
+        // 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.",
+        },
+        Plane::Control => "It operates on a cluster directory (pass --config <dir>).",
+        Plane::Session => "It does not address a graph.",
+        Plane::Data => unreachable!("data plane returned early"),
+    };
+    bail!(
+        "`{label}` is a {plane}-plane command; --server/--graph address the data plane and do not apply. {how}"
+    );
+}