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.

crates/omnigraph-server/src/config.rs

@@ -331,6 +331,36 @@ impl OmnigraphConfig {
         }
     }
 
+    /// The policy file that applies for a graph selection — the policy
+    /// sibling of [`OmnigraphConfig::query_entries_for`], so policy and
+    /// queries resolve by the same identity rule. A named graph in
+    /// `graphs:` uses its per-graph `policy.file` with **no** top-level
+    /// fallback (a named graph with no per-graph policy has no policy —
+    /// that keeps the boot-time coherence check meaningful); anything else
+    /// (no selection, or a bare URI) uses the top-level `policy.file`.
+    pub fn resolve_policy_file_for(&self, graph: Option<&str>) -> Option<PathBuf> {
+        match graph {
+            Some(name) if self.graphs.contains_key(name) => self.resolve_target_policy_file(name),
+            _ => self.resolve_policy_file(),
+        }
+    }
+
+    /// Names of any top-level config blocks (`policy.file`, `queries:`)
+    /// that are populated. Used by the boot-time coherence check: when a
+    /// **named** graph is served (single-mode by name, or multi-mode),
+    /// the top-level blocks are not honored, so a populated one is a
+    /// configuration error rather than a silent no-op.
+    pub fn populated_top_level_blocks(&self) -> Vec<&'static str> {
+        let mut blocks = Vec::new();
+        if self.policy.file.is_some() {
+            blocks.push("policy.file");
+        }
+        if !self.queries.is_empty() {
+            blocks.push("queries");
+        }
+        blocks
+    }
+
     /// Resolve a stored-query `.gq` file path (from a registry entry),
     /// relative to the config's `base_dir`. Mirrors policy-file
     /// resolution; the registry loader calls this to turn each entry's
@@ -640,6 +670,42 @@ queries:
         );
     }
 
+    #[test]
+    fn resolve_policy_file_for_follows_identity() {
+        let temp = tempdir().unwrap();
+        fs::write(
+            temp.path().join("omnigraph.yaml"),
+            "policy:\n  file: ./top.yaml\ngraphs:\n  prod:\n    uri: s3://b/prod\n    \
+             policy:\n      file: ./prod.yaml\n  bare:\n    uri: s3://b/bare\n",
+        )
+        .unwrap();
+        let config = load_config_in(temp.path(), None).unwrap();
+
+        // Named graph with its own policy → per-graph (not top-level).
+        assert!(
+            config
+                .resolve_policy_file_for(Some("prod"))
+                .unwrap()
+                .ends_with("prod.yaml")
+        );
+        // Named graph with NO per-graph policy → None (no top-level fallback;
+        // load-bearing for the boot coherence check).
+        assert!(config.resolve_policy_file_for(Some("bare")).is_none());
+        // Anonymous (bare URI) or an unknown name → top-level.
+        assert!(
+            config
+                .resolve_policy_file_for(None)
+                .unwrap()
+                .ends_with("top.yaml")
+        );
+        assert!(
+            config
+                .resolve_policy_file_for(Some("nope"))
+                .unwrap()
+                .ends_with("top.yaml")
+        );
+    }
+
     #[test]
     fn queries_block_absent_yields_empty_registry() {
         let temp = tempdir().unwrap();

crates/omnigraph-server/src/lib.rs

@@ -927,11 +927,34 @@ pub fn load_server_settings(
         let uri = normalize_root_uri(&raw_uri).wrap_err_with(|| {
             format!("normalize single-graph URI '{raw_uri}' from server settings")
         })?;
-        let policy_file = config.resolve_policy_file();
-        // Single mode uses the top-level `queries:` (mirrors top-level
-        // `policy.file`). Load + identity-check now (no engine needed);
-        // the schema type-check happens when the engine opens.
-        let queries = QueryRegistry::load(&config, config.query_entries_for(None))
+        // Config follows graph IDENTITY, not mode: a bare URI is anonymous
+        // (top-level config); a graph chosen by name uses its per-graph
+        // `graphs.<name>.{policy,queries}`. `resolve_target_uri` already
+        // errored on an unknown name, so a `Some(name)` here is a known graph.
+        let selected: Option<&str> = if has_cli_uri {
+            None
+        } else {
+            cli_target.as_deref().or_else(|| config.server_graph_name())
+        };
+        // A named selection must not leave a populated top-level block
+        // silently unused — refuse boot and point at the per-graph block.
+        if let Some(name) = selected {
+            let unhonored = config.populated_top_level_blocks();
+            if !unhonored.is_empty() {
+                bail!(
+                    "serving named graph '{name}', but top-level {} {} set — a named graph \
+                     uses its own `graphs.{name}.…` block, so the top-level value is ignored. \
+                     Move it to `graphs.{name}` (e.g. `graphs.{name}.policy.file`, \
+                     `graphs.{name}.queries`).",
+                    unhonored.join(" and "),
+                    if unhonored.len() == 1 { "is" } else { "are" },
+                );
+            }
+        }
+        // Load + identity-check now (no engine needed); the schema
+        // type-check happens when the engine opens.
+        let policy_file = config.resolve_policy_file_for(selected);
+        let queries = QueryRegistry::load(&config, config.query_entries_for(selected))
             .map_err(|errs| color_eyre::eyre::eyre!(format_registry_load_errors(&uri, &errs)))?;
         ServerConfigMode::Single {
             uri,
@@ -939,12 +962,16 @@ pub fn load_server_settings(
             queries,
         }
     } else if has_explicit_config && has_graphs_map {
-        if config.resolve_policy_file().is_some() {
+        // Multi mode: every graph uses its per-graph block; top-level
+        // policy/queries are never honored, so a populated one is an error.
+        let unhonored = config.populated_top_level_blocks();
+        if !unhonored.is_empty() {
             bail!(
-                "top-level `policy.file` is single-graph/CLI-local policy only; \
-                 in multi-graph mode move per-graph rules to \
-                 `graphs.<graph_id>.policy.file` and move `graph_list` rules to \
-                 `server.policy.file`."
+                "multi-graph mode: top-level {} {} not honored — each graph uses its own \
+                 `graphs.<graph_id>.…` block. Move per-graph rules there (and any \
+                 `graph_list` policy to `server.policy.file`).",
+                unhonored.join(" and "),
+                if unhonored.len() == 1 { "is" } else { "are" },
             );
         }
         // Rule 4 → Multi mode. Build a startup config per graph.