From 4187d56f8a3d259d3b5714dcd6247f22ce19c825 Mon Sep 17 00:00:00 2001 From: Andrew Altshuler Date: Sat, 13 Jun 2026 22:58:51 +0300 Subject: [PATCH] fix(cli): align lint plane label + document the plane model (RFC-010 follow-up) (#218) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Addresses the Greptile review on #217: P1 — `lint` reported two different names. `command_label` returns `lint`, but `execute_query_lint` passed `"query lint"` as the resolver operation string, so `lint --server` said `lint` while `lint ` said `query lint`. Both were pinned by tests. `query lint` is the *deprecated* alias (argv-rewritten to `lint`), so the canonical name is `lint`: switch both user-facing strings in `execute_query_lint` (the storage-plane bail label and the requires-schema-or-target usage message) to `lint`, and update the two pinned assertions in `cli_data.rs`. P2 — user-doc debt (AGENTS.md rule 1: error text is observable behavior). Document the plane model in `cli-reference.md` (new *Command planes* section: data vs storage/maintenance vs control, which addressing flags apply, and the declared wrong-plane / remote-target errors), and add an addressing note to `maintenance.md` cross-referencing it. Co-authored-by: Claude Opus 4.8 --- crates/omnigraph-cli/src/helpers.rs | 4 ++-- crates/omnigraph-cli/tests/cli_data.rs | 4 ++-- docs/user/cli-reference.md | 15 +++++++++++++++ docs/user/maintenance.md | 2 ++ 4 files changed, 21 insertions(+), 4 deletions(-) diff --git a/crates/omnigraph-cli/src/helpers.rs b/crates/omnigraph-cli/src/helpers.rs index 9991486..e9809b5 100644 --- a/crates/omnigraph-cli/src/helpers.rs +++ b/crates/omnigraph-cli/src/helpers.rs @@ -754,10 +754,10 @@ pub(crate) async fn execute_query_lint( let has_graph_target = cli_uri.is_some() || cli_target.is_some() || config.cli_graph_name().is_some(); if !has_graph_target { - bail!("query lint requires --schema or a resolvable graph target"); + bail!("lint requires --schema or a resolvable graph target"); } - let uri = resolve_local_uri(config, cli_uri, cli_target, "query lint")?; + let uri = resolve_local_uri(config, cli_uri, cli_target, "lint")?; let db = Omnigraph::open(&uri).await?; Ok(lint_query_file( &db.catalog(), diff --git a/crates/omnigraph-cli/tests/cli_data.rs b/crates/omnigraph-cli/tests/cli_data.rs index 01dbeb3..f558018 100644 --- a/crates/omnigraph-cli/tests/cli_data.rs +++ b/crates/omnigraph-cli/tests/cli_data.rs @@ -586,7 +586,7 @@ query list_people() { // RFC-010 Slice 1: the storage-plane verbs now share one declared message // (was: "query lint is only supported against local graph URIs …"). assert!( - stderr.contains("`query lint` is a storage-plane command and needs direct storage access") + stderr.contains("`lint` is a storage-plane command and needs direct storage access") && stderr.contains("remote server"), "storage-plane remote-target message not found; got: {stderr}" ); @@ -615,7 +615,7 @@ query list_people() { ); let stderr = String::from_utf8_lossy(&output.stderr); assert!( - stderr.contains("query lint requires --schema or a resolvable graph target") + stderr.contains("lint requires --schema or a resolvable graph target") ); } diff --git a/docs/user/cli-reference.md b/docs/user/cli-reference.md index b419adf..3843b2e 100644 --- a/docs/user/cli-reference.md +++ b/docs/user/cli-reference.md @@ -28,6 +28,21 @@ Top-level command families and subcommands. Graph-targeting commands accept a po | `policy validate \| test \| explain` | Cedar tooling. Selects `cli.graph`, else `server.graph`, else top-level `policy.file` | | `version` / `-v` | print `omnigraph 0.3.x` | +## Command planes + +Every command lives on one **plane**, which determines how it reaches a graph and which addressing flags apply (RFC-010): + +- **Data plane** — `query`, `mutate`, `load`, `ingest`, `branch *`, `snapshot`, `export`, `commit *`, `schema show`, `schema apply` (and `graphs list`, remote-only today). Run against a graph **embedded or via a server**: accept a positional `URI` / `--target` / `--server` (+ `--graph` for multi-graph servers). +- **Storage / maintenance plane** — `init`, `optimize`, `repair`, `cleanup`, `schema plan`, `queries validate`, `lint`. Run with **direct storage access** (`file://` / `s3://`), never through a server. They accept a positional `URI` or `--target`, but **not** `--server` / `--graph`, and a `--target` that resolves to a remote (`http(s)://`) server is rejected. (`init` takes only a positional `URI` today — no `--target`.) +- **Control plane** — `cluster *`. Operates on a cluster directory via `--config `. + +These restrictions are enforced and reported, not silent: + +- A data-plane addressing flag on a non-data verb fails loudly, e.g.: ``optimize is a storage-plane command; --server/--graph address the data plane and do not apply. Use --target or a storage URI.`` +- A storage-plane verb pointed at a remote target fails loudly, e.g.: ``optimize is a storage-plane command and needs direct storage access; the resolved target is a remote server (https://…). Pass the graph's file:// or s3:// URI.`` + +To maintain a server-backed graph, run the maintenance verbs from a host with storage access against the graph's storage URI (or `--target`), out-of-band from the serving process — there are no server routes for `optimize` / `repair` / `cleanup` by design. + ## Config surfaces Two config surfaces with single owners (RFC-007/RFC-008), plus a zero-config diff --git a/docs/user/maintenance.md b/docs/user/maintenance.md index e69bba3..3386582 100644 --- a/docs/user/maintenance.md +++ b/docs/user/maintenance.md @@ -2,6 +2,8 @@ `db/omnigraph/optimize.rs` and `db/omnigraph/repair.rs`. +**Addressing (RFC-010).** `optimize`, `repair`, and `cleanup` are **storage-plane** CLI commands: they run with direct storage access against a positional `URI` or `--target`, never through a server, and reject `--server` / `--graph` or a `--target` that resolves to a remote (`http(s)://`) URL with a declared error. There are no server routes for them by design — to maintain a server-backed graph, run them out-of-band against the graph's storage URI. See the *Command planes* section of [cli-reference.md](cli-reference.md). + ## `optimize_all_tables(db)` — non-destructive - Lance `compact_files()` on every node + edge table on `main`, then **publishes the compacted version to the `__manifest`** so the manifest's `table_version` tracks the compacted Lance HEAD. Reads pin the manifest version, so without this publish compaction would be invisible to readers *and* would break the HEAD-vs-manifest precondition of the next schema apply / strict update/delete ("stale view … refresh and retry"). The publish advances the graph version (a system-attributed commit) only for tables that actually compacted.