feat(agent): add bounded graph discovery and orientation

CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+- Improve agent discovery accuracy and latency with deterministic identifier-
+  subword postings, exact trusted-call relationship-term postings, bounded
+  proof-complete caller recall, distinct supporting-callee evidence, fair
+  candidate allocation, persistence-predicate precision within trusted
+  relation candidates, capacity-aware traversal, selected-subgraph edge-ref
+  filtering, bounded batched node and edge hydration, and one pinned immutable
+  store reader with a bounded decoded-object cache per request.
+  Legacy store snapshots remain readable and report incomplete identifier or
+  relationship coverage until they are rebuilt. The immutable relationship
+  capability is v2, and the disposable SQLite query accelerator now uses
+  internal format v7 and rebuilds automatically.
+
 - Add a digest-pinned 500-question, AI-reviewed synthetic relevance matrix
   covering all query classes, execute it in CI with strict ranking, recall,
   intent, structural, no-answer, and work bounds, and keep its generated JSON

COMPATIBILITY.md

@@ -98,15 +98,38 @@ and reference are internal realizations of the backend-neutral `compass-store`
 contract, not a stable SQL schema or pointer format that consumers may query
 directly.
 
-The additive `compass ask` command routes bounded natural-language questions
-to the existing typed search, callers, callees, impact, or node-trail operation
-and returns the same `compass.query/1` response contract. `compass query`
-automatically uses that path for high-confidence questions against a current
-typed graph. Generic or contradictory questions, historical `--at` queries,
-and requests with `--traverse`, `--dfs`, `--context`, `--budget`, or `--page`
-retain the established text-traversal behavior. Explicit typed query commands
-remain available and unchanged; ambiguous questions never invent a direction
-or select an arbitrary symbol.
+The additive `compass ask` command continues to route bounded questions to the
+typed `compass.query/1` operations. Plain `compass query` against a typed graph
+now defaults to `compass.query.discovery/1`; `--dfs` and `--context` compose
+with discovery. Explicit `--traverse` or legacy-only `--budget`/`--page`
+preserve the established text traversal and reject discovery controls.
+CompassQL and explicit typed query commands remain unchanged. Discovery text
+pagination uses the versioned `compass.query.discovery-text-page/1` cursor;
+JSON rejects those presentation-only controls.
+
+Default discovery JSON remains the strict `compass.query.discovery/1` shape.
+The additive `--result-envelope` option requires `--format json` and returns a
+typed `compass.query.discovery-result/1` envelope containing the unchanged v1
+result plus its query-owned `semanticResultDigest`. The digest is computed from
+canonical v1 semantic response bytes; the digest field is outside that result,
+so the v1 payload and its byte/shape contract remain unchanged.
+
+Clustered updates publish `orientation.json` (`compass.orientation/1`) from the
+same fitted model as `GRAPH_REPORT.md` and include it in the coherent snapshot
+and build state. `compass export orientation-json` and
+`compass://orientation` validate that its generation, source/configuration
+identity, commit, graph summary, and exact streamed `graph.json` artifact
+digest match the selected guarded graph. A direct or historical graph without
+that coherent artifact fails explicitly.
+
+MCP structured tool results use the `compass.mcp.tool-result/1` envelope. Its
+`result` retains the domain schema and domain truncation fields unchanged;
+`transportTruncation` separately reports the MCP byte bound. A response that
+would exceed that bound fails with typed required/limit/omitted byte metadata
+instead of publishing a partial semantic result.
+Natural discovery results additionally expose the same query-owned
+`semanticResultDigest` in this transport envelope, enabling direct/persistent
+result parity checks without requiring an agent client to invent a digest.
 
 Structural operands use the same bounded exact, alias, term, and typo recall
 channels as search. A unique relationship-role seed may disambiguate a
@@ -128,6 +151,66 @@ been removed. This does not change the `compass.query/1` schema, but intentional
 score and ordering improvements can change which equally lexical candidate is
 ranked first; ordering remains deterministic and backend-neutral.
 
+Discovery term indexes preserve their existing full tokens and add bounded
+camel-case, acronym, and underscore subwords derived from raw symbol names,
+qualified names, and aliases. They also add exact relationship-term postings
+from source-backed callable nodes through direct `calls` edges whose evidence
+is entirely exact and non-heuristic. Relationship postings use only the called
+target's terminal symbol name; namespace and owner terms from its qualified
+name remain available to direct lexical recall but do not become caller
+evidence. Parallel edges are deduplicated for this recall index; inferred,
+ambiguous, mixed-confidence, heuristic, source-less, and non-callable sources
+do not participate.
+
+Direct symbols and candidates with at least two trusted relationship concepts
+share one deterministic behavior-ranking channel. They are ordered by
+production status, bounded operation-predicate alignment, direct
+terminal/owner concept coverage, semantic kind, field and predicate precision,
+relationship concept coverage, distinct supporting targets, and evidence
+confidence. A relationship candidate keeps its lexical or alias source when
+it also has direct indexed evidence; only relationship-only recall is labeled
+as a relation seed. Fixed whole-token operation families (including
+persistence, dispatch, invocation, processing, recognition, refresh,
+resolution, and scheduling) affect ranking only: they cannot add a posting,
+candidate, relationship concept, or relation eligibility. Equal evidence
+vectors remain explicitly ambiguous.
+
+Discovery performs at most eight deterministic multi-concept term-index
+intersections before independent term unions. Intersection reads spend the
+same candidate, posting, object, byte, and probe budgets as all other recall;
+exhaustion remains explicit truncation rather than an empty result. A complete
+exact-name lookup can prove its top channel despite truncation in lower recall
+channels, while duplicate exact names remain ambiguous.
+
+Discovery traversal bounds adjacency reads by remaining node capacity and
+stops endpoint hydration at the node cap. Store-backed final edge assembly
+scans unit-valued outgoing references, rejects targets outside the selected
+subgraph before record hydration, and resolves the remaining edge IDs through
+a bounded shared tree traversal. This preserves canonical parallel-edge order
+and exact edge omissions when the reference scan completes; a shared expansion
+limit still produces explicit incomplete counts. Exact term candidates and
+adjacency records use bounded multi-key tree walks so immutable branch and leaf
+objects are decoded once per batch. A pinned request reader retains only
+digest-verified, decoded, schema-validated tree objects in an 8 MiB envelope
+with a 7 MiB decoded-object budget and a 1,024-object ceiling. Branches are
+retained preferentially and leaves use LRU eviction; cache hits do not bypass
+any logical item, byte, object, depth, or truncation accounting.
+
+The immutable store records identifier and relationship capabilities as
+separate empty reserved postings in its existing additive terms root, which
+older same-major readers ignore. Relationship membership is also stored as a
+bounded unit-valued `(source, term)` key so a complete sparse posting can prove
+membership in one truncated dense posting without scanning adjacency. The v2
+relationship capability also stores bounded unit-valued
+`(source, term, target)` evidence so ranking can count distinct query-supporting
+callees without inflating parallel calls or one callee that matches multiple
+concepts. Current readers still open snapshots without either capability but
+report incomplete discovery coverage; rebuild the graph to make discovery
+recall equivalent across the JSON and store engines. The disposable SQLite
+query cache adds `relationship_terms(term, source_id)` and
+`relationship_term_targets(term, source_id, target_id)` tables, uses internal
+format v7, and is rebuilt automatically.
+
 Optional MCP query feedback remains local and disabled by default.
 `COMPASS_QUERY_LOG=<path>` writes the versioned `compass.query-log/1` JSONL
 contract up to a 16 MiB file bound. The review importer accepts only its

MIGRATION.md

@@ -34,6 +34,7 @@ compass-out/
 ├── graph.json
 ├── graph.html        # unless --no-viz or the render limit omits it
 ├── GRAPH_REPORT.md
+├── orientation.json  # versioned agent context bound to this exact graph.json
 ├── manifest.json
 └── cache/
 ```
@@ -44,6 +45,26 @@ cache payloads remain Compass contracts: do not copy `graphify-out/cache/` or
 `graphify-out/manifest.json` into `compass-out/`. Compass rebuilds them from
 source while retaining its own internal snapshot and store protocols.
 
+## Update natural-query automation
+
+Plain `compass query "<question>"` now returns structured discovery text by
+default on a typed graph. Replace discovery text paging based on `--budget` and
+numeric `--page` with `--text-budget` and the opaque `next=<cursor>` token.
+Keep the question, discovery options, and graph unchanged while following a
+cursor. Use explicit `--traverse` when an existing workflow intentionally needs
+the former relevance traversal; its `--budget`/`--page` behavior remains.
+CompassQL and explicit `ask`, `search`, `callers`, `callees`, and other typed
+commands are unchanged.
+
+MCP clients must read structured results from the `result` field of the
+`compass.mcp.tool-result/1` envelope and inspect `transportTruncation`
+separately from the domain result's own `truncated` field.
+
+Run `compass update .` once after upgrading to publish `orientation.json` with
+the exact `graph.json` digest. Agent-facing orientation/report exports fail
+explicitly for older, missing, detached, or stale sidecars instead of pairing
+evidence by filename alone.
+
 ## Opt into Program IR generation
 
 Structural graph builds now omit the optional `program.json` artifact by

PERFORMANCE.md

@@ -24,6 +24,19 @@ Compare a proposed change with a previously approved Compass result captured on
 the same runner and corpus. A median regression above 10% requires explicit
 review and evidence explaining the tradeoff.
 
+Real-repository natural-query qualification materializes one SQLite-backed
+query artifact per repository. Fresh latency/RSS is one direct `compass query`
+process per observation; warm latency is measured inside one persistent MCP
+session after an unmeasured iteration. The harness requires exact artifact
+identity across compared runs, checks all seven discovery work counters, and
+requires the complete eight-corpus run to include at least one query on a graph
+of 50,000 or more nodes that inspects no
+more than 25% of the graph's nodes during candidate recall. Current results
+must carry the Rust-owned semantic digest. An explicitly enabled legacy
+baseline may retain a labeled full-payload harness digest for timing reference,
+but its quality failures remain visible and it cannot be promoted or used as a
+current candidate.
+
 ## Query-relevance qualification
 
 The native query-relevance gate keeps three intentionally separate evidence

README.md

@@ -38,7 +38,12 @@ compass install
 compass watch
 ```
 
-Run `compass watch` in a second terminal. Once installed, an assistant runs `compass query "<question>"` before broad source searches. It reads `compass-out/GRAPH_REPORT.md` for repository-wide architecture context and opens only the source needed to verify its answer.
+Run `compass watch` in a second terminal. For a focused task, an installed
+assistant starts with `compass query "<question>"`. On a first session or broad
+repository orientation, it reads only the bounded **Agent Orientation** at the
+start of `compass-out/GRAPH_REPORT.md`, then runs a focused query. It checks
+direction, ambiguity, completeness, truncation, and pagination before opening
+only the cited source needed to verify its answer.
 
 Inside a Git repository, `compass install` detects supported assistants and always includes the portable Agent Skills integration. Confirm that the intended host appears under `Selected`. If it does not, select one or more platforms explicitly:
 
@@ -241,6 +246,7 @@ Compass writes:
 compass-out/
 ├── graph.json        machine-readable graph
 ├── GRAPH_REPORT.md   architecture and community summary
+├── orientation.json  versioned Agent Orientation from the same graph generation
 ├── graph.html        interactive visualization when size permits
 ├── manifest.json     incremental build state
 ├── snapshots/        coherent retained build snapshots
@@ -252,16 +258,21 @@ compass-out/
 
 ```bash
 compass query "where is authentication enforced?"
-compass query "where is authentication enforced?" --budget 8000 --page 2
+compass query "where is authentication enforced?" --text-budget 8000
+compass query "where is authentication enforced?" --cursor '<TOKEN>'
 compass explain TokenVerifier
 compass path ApiHandler TokenVerifier
 compass affected TokenVerifier --depth 3
 ```
 
 These commands read the saved graph and do not call a model.
-Natural `query` and `explain` output is deterministically paged. Callers may set
-an approximate per-page token budget with `--budget N` (2,000 by default) and
-follow the reported `next` page with `--page N`.
+Plain natural `query` uses bounded structured discovery. Its text projection
+pages whole deterministic entries with `--text-budget N` (2,000 by default).
+Follow `next=<cursor>` with the unchanged semantic question and options until
+`next=none`; the presentation-only text budget may change between pages. The
+cursor fails if semantic inputs, the selected graph, or the semantic result
+changed. `--traverse`, `--budget`, and `--page` retain the
+legacy traversal contract; CompassQL is unchanged.
 
 ## Compass-specific workflows
 
@@ -331,24 +342,20 @@ not detect a host-specific adapter. An explicit `--platform` selection bypasses
 detection. Start a new assistant session after installation. In Codex, review
 and trust the hook under `/hooks`; in Gemini CLI, run `/skills reload`.
 
-The skill teaches assistants to refresh an existing graph when it is stale,
-run a focused Compass query before broad source searches, and open only the
-source files needed to verify an answer. It reads `compass-out/GRAPH_REPORT.md`
-when repository-wide architecture context is useful. Installation does not
-build a graph; on the first architecture, dependency, history, or impact
-question, the assistant can run the local deterministic build and continue.
+The skill teaches assistants to keep `compass watch` in a second terminal (or
+use `compass update .` as a reported fallback), run a focused query first, and
+open only cited source. For first-session or broad orientation it reads only
+the bounded Agent Orientation at the start of `GRAPH_REPORT.md`, then queries.
+It inspects direction, ambiguity, graph completeness, domain truncation, and
+pagination; ambiguous seeds are retried by exact node ID. Installation does
+not build a graph.
 
 ```text
-coding question
-        |
-        v
-run a focused Compass query
-        |
-        v
-read GRAPH_REPORT.md for repository-wide context
-        |
-        v
-inspect the smallest useful source set
+focused task ───────────────> focused query
+first/broad orientation ────> bounded Agent Orientation ──> focused query
+                                      |
+                                      v
+                 inspect completion and the smallest cited source set
 ```
 
 See [Assistant setup](docs/guides/assistant-setup.md) for supported platforms,

benchmarks/performance/README.md

@@ -41,12 +41,21 @@ python3 benchmarks/performance/harness.py run \
 ```
 
 Use `--repository NAME` repeatedly to select repositories and `--workload`
-to select `build`, `query`, or `compassql`. Query selections still perform the
-build prerequisite. Raw graphs and process logs remain under the owned
+to select `build`, `query`, or `compassql`. Query-only runs materialize one
+SQLite query artifact per repository instead of repeating the build matrix.
+Fresh query samples use one direct CLI process; warm samples share one MCP
+server, with one unmeasured iteration in each mode. Raw graphs and process logs remain under the owned
 workspace; `run.json` and `summary.md` are written under the output directory.
-Every process is fresh, expensive build workloads have three samples, query
-workloads have one untimed warmup and ten measured samples, and reports retain
-excluded observations.
+Expensive build workloads have three samples, query workloads have ten measured
+samples, and reports retain excluded observations.
+
+Use `--reuse-corpora-root PATH` only with detached, clean checkouts whose
+origin, commit, and tree exactly match the suite. Use
+`--reuse-query-artifacts PATH` to validate and query an existing artifact tree
+without pruning it. Pre-digest Compass revisions may be measured only with the
+explicit `--allow-legacy-query-digest` baseline mode; those results retain
+strict quality failures, are labeled as legacy, and cannot be promoted as a
+current passing baseline.
 
 Promotion is allowed only for a complete, clean, passing eight-repository run:
 
@@ -70,10 +79,12 @@ python3 benchmarks/performance/harness.py compare \
 Both tools use the same corpus commits. Build comparisons use the same
 structural profile: Compass `--code-only --no-cluster --no-viz --store json`
 and Graphify's native `--code-only` profile. Every cold, warm, incremental, and
-natural-language query row must independently reach
+fresh natural-language query row must independently reach
 `graphify p50 / compass p50 >= 5.00`; averages cannot hide a failed row.
 Compass build peak RSS must not exceed Graphify, and Graphify's shared graph
-facts must remain present and compatible in Compass. CompassQL is excluded from
+facts must remain present and compatible in Compass. Only fresh natural-query
+rows participate in the cross-tool ratio; persistent warm queries are a
+Compass baseline comparison. CompassQL is excluded from
 the cross-tool ratio because Graphify has no equivalent workload.
 
 The comparison environment is isolated under `target/performance/` and is not a