feat: improve relationship recall and agent query contracts

CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+- Improve agent-facing query correctness and recovery: callers, impact, and
+  affected include source-backed alias/import/export usage evidence; CompassQL
+  exposes live node degree and supports ordering by pre-projection bindings;
+  historical reads neutralize configured checkout filters; direction-only
+  trail misses suggest `compass path`; and full reports retain bounded hub,
+  suggested-query, and learned-question entries.
+- Unify bounded relationship resolution across callers, impact, and affected,
+  including importer-consistency diagnostics and explicit relationship
+  provenance. Add the bounded `compass architecture` view, shared agent output
+  formats, visible coverage witnesses, a 64-candidate query default, and
+  read-only historical queries with state-health audit events.
+
 ## 0.3.28 - 2026-09-19
 
 - Improve agent-facing query correctness and recovery across callers, impact,

COMPATIBILITY.md

@@ -118,6 +118,11 @@ View must reject unknown major versions, enforce the documented bounds, and
 distinguish `no_match`, `needs_resolution`, `no_path`, source truncation, and
 projection truncation from a positive complete answer.
 
+The additive `relationship_inconsistency` diagnostic extends the strict
+`compass.query/1` diagnostic enum and changes its contract fingerprint. Strict
+TypeScript consumers and the checked-in manifest must accept the new value
+before interpreting a relationship result that carries it.
+
 Immutable history now accepts up to 5 GiB of aggregate authoritative key and
 value bytes per realization, raised from 512 MiB. The history schema and
 canonical encoding are unchanged, as are the per-key, per-value, per-tree,

MIGRATION.md

@@ -23,6 +23,19 @@ reports `NO PATH FOUND` separately when both endpoints exist but are
 unreachable. Consumers that parsed the prior human path prose should migrate to
 these explicit signals; machine-query schema versions are unchanged.
 
+Typed relationship commands now share source-backed import/reference
+resolution. `callers`, `impact`, and typed `affected` may therefore return
+additional importer evidence and can emit a `relationship_inconsistency`
+diagnostic when their bounded traversal disagrees with the importer probe.
+Treat that diagnostic as incomplete coverage rather than an empty answer.
+The default typed search candidate limit is now 64; count-shaped automation
+should inspect the structured `truncated` flag and diagnostics.
+
+`ask`, `search`, `query`, `callers`, `callees`, `impact`, `path`, and `explain`
+accept the shared `--format text|json|agent-json` contract where applicable.
+Use `compass architecture --format agent-json` for a bounded repository
+overview with omission counts and witness IDs.
+
 ## Rebuild SQLite adjacency sidecars
 
 Store snapshots now declare edge-ID-ordered directional adjacency so bounded

crates/compass-cli/assets/compass-skill/SKILL.md

@@ -105,9 +105,13 @@ Use the specialized navigation commands when they fit:
 - `compass explain "<concept>"` for one node and its neighborhood; use the same
   `--budget N` and `--page N` continuation workflow for large neighborhoods or
   ambiguity lists.
+- `compass architecture` for a bounded repository overview with explicit
+  coverage, omissions, and witness group IDs.
 - `compass program` for normalized functions, call evidence, or capability
   completeness rather than graph topology.
-- `compass affected "<symbol>" --depth N` for downstream review scope.
+- `compass affected "<symbol>" --depth N` for downstream review scope; on a
+  typed graph it shares importer/reference resolution with `impact`, and
+  `--format agent-json` preserves bounded diagnostics for an agent.
 - `compass query --cql "..."` for exact, deterministic graph patterns.
 - `compass tree` for a graph-aware repository tree.
 - `compass query "<question>" --at REV` for an immutable historical graph.
@@ -197,7 +201,7 @@ recovery, and MCP setup.
 Classify the effect before selecting a command:
 
 - Read-only local: `ask`, `search`, `callers`, `callees`, `impact`, `explore`,
-  `node`, `call-graph`, `query`, `program`, `path`, `explain`, `affected`,
+  `node`, `call-graph`, `query`, `program`, `path`, `explain`, `architecture`, `affected`,
   `tree`, `document`, `models list`, `models verify`, and local diagnostics.
 - Local publication: `init`, `ensure`, `update`, `extract`, `watch`, `cluster-only`,
   `label`, `models install`, history materialization, installation, and
@@ -261,7 +265,8 @@ the user wants human-readable community labels and accepts provider use. Use
 
 Do not force every request through `query`:
 
-- Architecture or concept: `query`, then `explain`.
+- Architecture or concept: `architecture`, then `query` or `explain` for a
+  focused relationship.
 - Dependency route: `path`.
 - Change-review scope: `affected`.
 - Exact relationship or automation: `query --cql`.

crates/compass-cli/assets/compass-skill/references/command-reference.md

@@ -35,8 +35,12 @@ whether a Compass capability is covered by the installed skill. Run
 - `compass path`: shortest known graph route between two matched nodes.
 - `compass explain`: budgeted, deterministic pages for one matched node plus
   its local neighborhood.
+- `compass architecture`: bounded architecture projection with explicit
+  coverage, omissions, and witness IDs for agent inspection.
 - `compass affected`: downstream review candidates, optionally filtered by
-  relation and depth.
+  relation and depth. Typed graphs use the same source-backed relationship
+  resolver as `callers` and `impact`; use `--format json|agent-json` when an
+  agent needs diagnostics and evidence counts.
 - `compass tree`: repository hierarchy enriched with graph metadata.
 - `compass history`: configure, materialize, inspect, export, prefer, or garbage
   collect immutable commit realizations.
@@ -55,9 +59,10 @@ whether a Compass capability is covered by the installed skill. Run
 - `compass store restore`: validate that manifest, graph export, selector, and
   sidecar before restoring into a new or empty output directory.
 
-These are read-only unless a missing historical realization must be materialized.
-An `--at REV` query can therefore create local history-store artifacts even
-though the query itself does not edit the working tree.
+These commands are read-only. An `--at REV` query requires an existing
+materialized realization; run `compass history build REV --code-only` explicitly
+before querying an uncached revision. Query caches may still be refreshed, but
+no extraction or credential-dependent provider runs implicitly.
 
 ## Build and enrich
 

crates/compass-cli/assets/compass-skill/references/history.md

@@ -32,17 +32,20 @@ compass history build main --all --first-parent --code-only --format json
 compass history list --format json
 ```
 
-Explicit historical queries can materialize a missing revision even when eager
-history is disabled:
+Explicit historical queries are read-only. They never materialize a missing
+revision or invoke extraction; build the exact revision first:
 
 ```bash
+compass history build HEAD~20 --code-only
 compass query "authentication flow" --at HEAD~20
 compass path OldHandler Database --at v1.2.0
 compass explain LegacyGateway --at RELEASE_TAG
 ```
 
-Compass resolves a revision to an exact commit and builds it in a protected,
-offline worktree. Report the resolved revision when answering.
+If the selected revision is not already materialized, the command stops with
+the exact `compass history build REV --code-only` prerequisite. Compass still
+resolves every read to an exact immutable realization; report that resolved
+revision when answering.
 
 ## Compare and inspect
 
@@ -62,6 +65,9 @@ Use `compass diff` for a ranked semantic review. Use `compass history diff`
 when the user needs an exhaustive, deterministic record-level comparison of
 immutable graph roots.
 
+`compass history export` is read-only as well; build an uncached revision with
+`compass history build REV --code-only` before exporting it.
+
 Semantic realizations with different extraction fingerprints are not silently
 treated as equivalent. Use `history list`, `show`, and `prefer` to inspect or
 select an intended realization.

crates/compass-cli/assets/compass-skill/references/query.md

@@ -85,6 +85,7 @@ compass explore CheckoutController PaymentGateway --root .
 compass node route:/checkout CheckoutController.create
 compass explain PaymentGateway
 compass explain PaymentGateway --budget 8000 --page 2
+compass architecture --format agent-json
 compass path CheckoutHandler PaymentGateway
 compass affected authorizePayment --depth 3
 compass tree

crates/compass-cli/src/code_query_commands.rs

@@ -11,12 +11,15 @@ use compass_query::{
     EngineSelection, NaturalQueryRequest, open_with_engine, open_with_verified_document,
 };
 
-use crate::Outcome;
+use crate::{Outcome, SharedOutputFormat, parse_shared_output_format};
 
 pub(crate) fn command(operation: &str, args: &[String]) -> Outcome {
-    let format = option(args, "--format").unwrap_or("text");
-    if format == "agent-json"
-        && args.iter().any(|arg| {
+    let (format, query_args) = match parse_shared_output_format(args, operation) {
+        Ok(parsed) => parsed,
+        Err(error) => return Outcome::failure(format!("error: {error}")),
+    };
+    if format == SharedOutputFormat::AgentJson
+        && query_args.iter().any(|arg| {
             matches!(
                 arg.as_str(),
                 "--cursor" | "--text-budget" | "--evidence" | "--result-envelope"
@@ -28,29 +31,29 @@ pub(crate) fn command(operation: &str, args: &[String]) -> Outcome {
             "error: --cursor, --text-budget, --evidence, and --result-envelope are text-only and cannot be used with --format agent-json".to_owned(),
         );
     }
-    match execute(operation, args) {
+    match execute(operation, &query_args) {
         Ok(execution) => {
-            if format == "json" {
+            if format == SharedOutputFormat::Json {
                 match serde_json::to_string_pretty(&execution.response) {
                     Ok(json) => Outcome::success(json),
                     Err(error) => Outcome::failure(format!("error: {error}")),
                 }
-            } else if format == "agent-json" {
+            } else if format == SharedOutputFormat::AgentJson {
                 match build_code_query_view(&execution.response, execution.context)
                     .and_then(|view| serde_json::to_string_pretty(&view).map_err(Into::into))
                 {
                     Ok(json) => Outcome::success(json),
                     Err(error) => Outcome::failure(format!("error: {error}")),
                 }
-            } else if format == "text" {
+            } else if format == SharedOutputFormat::Text {
                 match build_code_query_view(&execution.response, execution.context)
                     .and_then(|view| render_agent_query_text(&view))
                 {
                     Ok(text) => Outcome::success(text),
                     Err(error) => Outcome::failure(format!("error: {error}")),
                 }
             } else {
-                Outcome::failure("error: --format must be json, agent-json, or text".to_owned())
+                Outcome::failure("error: unsupported output format".to_owned())
             }
         }
         Err(error) => Outcome::failure(format!("error: {error}")),