omnigraph/docs/user
Ragnor Comerford cd570ce59c
Resolve graph config by identity, not server mode
Which policy/queries block applies for a graph was decided three different,
mode-dependent ways: single-mode boot used top-level even for a named graph;
multi-mode used per-graph (and silently ignored a top-level queries block); the
CLI used per-graph for a named target. So `queries validate --target prod`
could check a different registry than the single-mode server loaded, and a
named graph's per-graph policy/queries were silently shadowed.

Make config a function of graph IDENTITY: a graph served by NAME
(--target/server.graph, a graphs: entry) uses its own graphs.<name>.{policy,
queries}; a bare URI is anonymous and uses top-level. One rule, applied by
single-mode boot, multi-mode boot, and the CLI — so they can't diverge and the
CLI predicts the server exactly.

No silent ignore: serving a named graph while a top-level policy/queries block
is populated now refuses boot, naming the block (the multi-mode top-level-policy
bail, extended to queries and to single-mode-named). The CLI's `queries
validate` derives the schema URI and the registry from ONE selection, and a
positional URI forces anonymous (ignoring cli.graph) so the two can't come from
different graphs.

BREAKING (released behavior): single mode by name (--target/server.graph) with
top-level policy/queries previously used top-level; it now uses the per-graph
block and refuses boot if top-level is also populated. Bare-URI single mode is
unchanged. Loud, with migration text pointing at graphs.<name>.

- config: resolve_policy_file_for (policy sibling of query_entries_for, no
  top-level fallback) + populated_top_level_blocks for the coherence check.
- characterization tests (single-mode named -> per-graph; named + top-level ->
  bail; multi-mode top-level queries -> bail; CLI positional-URI -> top-level).
- docs: policy.md, server.md, cli-reference.md.
2026-05-31 15:57:20 +02:00
..
audit.md Rename repo terminology to graph (#118) 2026-05-24 16:46:00 +01:00
branches-commits.md docs: split user and developer docs (#93) 2026-05-15 03:45:22 +03:00
changes.md docs: split user and developer docs (#93) 2026-05-15 03:45:22 +03:00
cli-reference.md Resolve graph config by identity, not server mode 2026-05-31 15:57:20 +02:00
cli.md feat: inline query strings in CLI and HTTP server (#110) 2026-05-29 13:41:54 +02:00
constants.md docs: split user and developer docs (#93) 2026-05-15 03:45:22 +03:00
deployment.md docs: align release artifact docs 2026-05-29 14:04:16 +02:00
embeddings.md Rename repo terminology to graph (#118) 2026-05-24 16:46:00 +01:00
errors.md docs: split user and developer docs (#93) 2026-05-15 03:45:22 +03:00
index.md Rename repo terminology to graph (#118) 2026-05-24 16:46:00 +01:00
indexes.md docs: split user and developer docs (#93) 2026-05-15 03:45:22 +03:00
install.md docs: align release artifact docs 2026-05-29 14:04:16 +02:00
maintenance.md docs: split user and developer docs (#93) 2026-05-15 03:45:22 +03:00
policy.md Resolve graph config by identity, not server mode 2026-05-31 15:57:20 +02:00
query-language.md docs: split user and developer docs (#93) 2026-05-15 03:45:22 +03:00
schema-language.md schema: HTTP allow_data_loss exposure + e2e drop coverage (MR-694 follow-up) (#107) 2026-05-19 01:56:46 +03:00
schema-lint.md docs: split user and developer docs (#93) 2026-05-15 03:45:22 +03:00
server.md Resolve graph config by identity, not server mode 2026-05-31 15:57:20 +02:00
storage.md Rename repo terminology to graph (#118) 2026-05-24 16:46:00 +01:00
transactions.md Rename repo terminology to graph (#118) 2026-05-24 16:46:00 +01:00