diff --git a/docs/user/cli-reference.md b/docs/user/cli-reference.md index 0326e64..5091953 100644 --- a/docs/user/cli-reference.md +++ b/docs/user/cli-reference.md @@ -20,6 +20,7 @@ A reference for the `omnigraph` binary's command surface and `omnigraph.yaml` sc | `run list \| show \| publish \| abort` | transactional run ops | | `schema plan \| apply \| show (alias: get)` | migrations | | `lint` (alias: `check`) | offline / graph-backed query validation. Replaces `query lint` / `query check`, which are kept as deprecated argv-level shims that print a one-line warning and rewrite to `omnigraph lint` | +| `queries validate \| list` | operate on the server-side stored-query registry (the `queries:` block). `validate` type-checks every stored query against the live schema offline (opens the selected graph; exits non-zero on any breakage), catching schema drift without restarting the server; `list` prints each query's name, MCP exposure, and typed params. Distinct from `lint`, which validates a single `.gq` file | | `optimize` | non-destructive Lance compaction | | `cleanup --keep N --older-than 7d --confirm` | destructive version GC | | `embed` | offline JSONL embedding pipeline | @@ -34,6 +35,13 @@ graphs: : uri: bearer_token_env: + queries: # per-graph stored-query registry (server-role; multi-graph mode) + : # key MUST equal the `query ` symbol inside the .gq + file: # relative to this config's directory + mcp: + expose: false # default false: HTTP-callable but not listed as an MCP tool + tool_name: # optional MCP tool-name override (defaults to ; + # must be unique across exposed queries) server: graph: bind: @@ -59,6 +67,8 @@ aliases: graph: branch: format: +queries: # top-level stored-query registry (single-graph mode); mirrors top-level `policy` + : { file: , mcp: { expose: false } } policy: file: ./policy.yaml ``` diff --git a/docs/user/policy.md b/docs/user/policy.md index 749d3be..0674f56 100644 --- a/docs/user/policy.md +++ b/docs/user/policy.md @@ -14,16 +14,17 @@ Per-graph actions (bind to `Omnigraph::Graph::""`): 6. `branch_delete` 7. `branch_merge` 8. `admin` — reserved for policy-management surfaces (hot reload, audit log, approvals). No call site today; see MR-724 for the reservation rationale. +9. `invoke_query` — gates invoking a server-side stored query (the `queries:` registry). Branch-scoped, like `read` / `change`. Coarse in this release: an `invoke_query` allow rule permits any stored query on the graph; a future, additive refinement adds an optional per-query-name scope without changing rules written against the coarse action. No invocation call site yet — the handler lands in a later change. A stored *mutation* is double-gated: `invoke_query` to reach the tool, plus `change` for the write itself (the engine `_as` writers still enforce per the query body). Server-scoped action (v0.6.0+; binds to `Omnigraph::Server::"root"`): -9. `graph_list` — `GET /graphs` registry enumeration (multi-graph mode) +10. `graph_list` — `GET /graphs` registry enumeration (multi-graph mode) Server-scoped actions cannot use `branch_scope` or `target_branch_scope` — they operate on the registry, not on a graph's branches. A rule cannot mix server-scoped and per-graph actions; split into separate rules. (Runtime `graph_create` / `graph_delete` are reserved but not shipped in v0.6.0; operators add/remove graphs by editing `omnigraph.yaml` and restarting.) ## Scope kinds -- `branch_scope` — applied to source branch (`read`, `export`, `change`) +- `branch_scope` — applied to source branch (`read`, `export`, `change`, `invoke_query`) - `target_branch_scope` — applied to destination (`schema_apply`, branch ops, run ops) - `protected_branches` — named list with special rules; rule scopes are `any | protected | unprotected` diff --git a/docs/user/server.md b/docs/user/server.md index 6f55e16..5b5fbb0 100644 --- a/docs/user/server.md +++ b/docs/user/server.md @@ -20,6 +20,10 @@ Mode inference (four-rule matrix): 4. `--config` + non-empty `graphs:` + no single-mode selector → **multi** 5. otherwise → error with migration hint +### Stored-query validation at startup + +If a graph declares a `queries:` registry (see [cli-reference](cli-reference.md)), the server **loads and type-checks every stored query against that graph's live schema at startup** and **refuses to boot** if any query references a type or property the schema lacks — the same fail-loud posture as a malformed policy file, so schema drift surfaces at the deploy boundary rather than at invocation. Two MCP-exposed queries claiming the same tool name is likewise a boot error. Non-blocking advisories (e.g. an MCP-exposed query with a vector parameter an agent cannot supply) are logged. Validate offline before deploying with `omnigraph queries validate`. *(Stored-query invocation over HTTP/MCP is not yet exposed — this release ships the registry, its boot-time validation, and the `invoke_query` Cedar action ahead of the invocation handler.)* + ## Endpoint inventory Per-graph endpoints — same body shape across modes; URLs differ: