Make native query answers compact and honor output budgets

.gitignore

@@ -15,4 +15,6 @@ apps/web/tsconfig.tsbuildinfo
 /.worktrees/
 __pycache__/
 *.pyc
+# Disposable query/output caches can be created from any working directory.
+**/.compass/cache/
 .DS_Store

CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+- Default typed query and MCP text to compact, source-located answers. Keep
+  uncertainty visible and expose full paged audit detail with `--verbose` or
+  `--evidence`; raw machine contracts are unchanged.
+- Enforce UTF-8 output budgets with exact continuations across finite commands.
+  Add immutable saved-output reading via `compass output`; reject partial
+  machine output and budgets on unbounded streams.
+- Cache complete native query responses by verified graph, Program IR, request
+  limits, profiles and semantic mode, with bounded disposable storage and
+  corruption fallback. Reuse one pinned engine across CLI page widening.
+
 ## 0.4.1 - 2026-10-01
 
 - Match engineering business vocabulary through bounded synonyms and witnessed

COMPATIBILITY.md

@@ -1665,3 +1665,29 @@ independently of the bounded path ledger.
 The resolver also preserves qualified external Rust receivers established by
 source factory return contracts, subject to the existing inference policy. An
 absent method on a source-local return type remains unresolved.
+
+## Compact query text and completed-output budgets
+
+Human-readable typed query defaults now omit audit fields and redundant ledgers.
+Use `--verbose` or `--evidence` for full paged status and record provenance.
+No-match/candidate pages are capped at 199 approximate tokens. Text is a display
+surface; raw `compass.query/1`, discovery, Agent View and MCP structured content
+retain their schemas and semantic records. MCP text uses the same compact
+presentation. Keep evidence mode unchanged when continuing a cursor; incompatible
+prefixes fail explicitly.
+
+`--budget N` is a completed-output ceiling of `4*N` UTF-8 bytes across streams,
+including newline/continuation. Supported range is 32–65536. It no longer selects
+legacy query traversal; `--traverse` or `--page` does. Native query pagers keep
+whole entries or report the budget required for one entry. Other completed
+answers use content-addressed `compass.saved-output/1` records and the additive
+`compass output ID --offset BYTE --budget N` command. This reader does not repeat
+command side effects. Oversized machine output fails rather than publish partial
+JSON/JSONL; streaming commands/events reject finite budgets before starting.
+
+Saved answers are disposable, work-directory-local and independently bounded.
+Response cache v1 is also disposable: checksum-checked typed complete records
+are bound to graph/Program IR, executable version, planner/ranker profiles,
+complete request and semantic mode. A changed response-cache meaning requires a
+new cache filename/version; missing/corrupt caches do not change native results.
+Neither cache rewrites published graphs or historical realizations.

MIGRATION.md

@@ -5,6 +5,22 @@ sidecars. Its output root now preserves the familiar flat artifact shape so
 file-based workflows can transition while Compass's snapshot and store
 layout remains visible and clearly owned.
 
+## Compact output and budgets
+
+Typed query text is compact by default. Select `--verbose` or `--evidence` to
+recover audit status and per-record provenance. JSON contracts are unchanged.
+Keep that mode fixed between cursor pages; restart the query when switching.
+
+`query --budget N` now bounds output instead of selecting legacy traversal.
+Add `--traverse` or `--page` if the old relevance renderer is required.
+Budgets accept 32–65536 approximate tokens and include continuation instructions.
+Follow `compass output ID --offset BYTE --budget N` from the same directory for
+commands that save their completed output. Saved answers can be evicted; the
+reader never repeats an action. Oversized machine output fails intact; omit the
+budget or read the saved record with a large enough budget. Streaming events,
+watch, REPL and serve reject this finite-output control; budgeted init needs `--yes`.
+No graph rebuild is required for compact text or disposable response caching.
+
 ## Graph rebuilds and query resolution
 
 To enable full bounded document/prose recall, rebuild with

PERFORMANCE.md

@@ -1498,3 +1498,59 @@ unrelated host work and ordinary OS caches remained uncontrolled. Three runs
 per binary on one known repository do not establish general performance or an
 approved release baseline. All six graphs still omit one node and 45 edges;
 normal release qualification remains required.
+
+## Compact query text and complete-response caching
+
+The October 2, 2026 replay uses unchanged `suite_natural.toml` and `suite_v2.toml`
+oracles over the same pinned Cobra, Flask, Gson, Zod and Axum source trees and
+frozen graphs. Both native binaries use the normal optimized workspace release
+profile and Rust 1.97.1. The installed comparator remains Graphify 0.9.67; its
+natural-suite observations are the archived paired run, and the standard suite
+was replayed against the same archived graph inputs.
+
+| Fixed panel | Native before | Native after | Comparator | Mean native before tokens | Mean native after tokens | Mean comparator tokens |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: |
+| 25 natural questions | 24/25 | 24/25 | 17/25 | 544.52 | 547.44 | 757.44 |
+| 50 standard questions | 49/50 | 49/50 | 44/50 | 419.10 | 363.76 | 549.74 |
+
+Every native row retains its previous oracle verdict. Standard-suite mean cost
+falls 13.2%; the natural mean grows slightly because compact answers retain
+uncertainty warnings. Both native means remain below the comparator on these
+panels. The known `Find` omission in the natural Cobra question and
+`route_endpoint` omission in the standard Axum impact question remain failures.
+Tokens are the existing harness's `ceil(stdout UTF-8 bytes / 4)` estimate over
+its complete workflow. Comparator installation warnings are recorded separately
+on stderr. These source-reviewed text-recall panels do not independently measure
+precision or establish population-wide superiority. MCP text is compact but its
+unchanged full structured content still contributes to clients consuming both.
+
+A separately registered cache panel executes the first callers question in each
+standard-suite repository as raw JSON: three alternating trials per binary,
+each with a fresh task-owned cache directory and six command invocations. Warm
+cost is the median of invocations 2–6, summarized across the three trials.
+All 180 raw JSON outputs are byte-identical across both binaries and repetitions
+for each repository. Source excerpts and truncated execution responses remain
+uncached.
+
+| Repository | Before cold median ms | Before warm median ms | After cold median ms | After warm median ms | Cache eligible |
+| --- | ---: | ---: | ---: | ---: | --- |
+| Cobra | 85 | 85 | 73 | 34 | Yes |
+| Flask | 348 | 220 | 386 | 34 | Yes |
+| Gson | 488 | 292 | 438 | 259 | No: partial graph |
+| Zod | 967 | 994 | 897 | 34 | Yes |
+| Axum | 401 | 284 | 648 | 30 | Yes |
+
+The initial panel stopped when Gson's frozen partial publication made its small
+response truncated. The recorded amendment kept all questions, inputs, limits,
+trials and repetitions, and recorded eligibility instead of requiring every
+input to be complete. Gson remains in the table and its cache has no response
+entry. Cold Flask and Axum observations regress; cache reuse is not a claim that
+every command or first invocation gets faster. Ordinary OS caches and unrelated
+host load remain uncontrolled, including an 8.135-second cold Zod observation.
+The earlier debug replay had timeouts and is excluded from optimized timing and
+final verdicts.
+
+[`compact_query_output_review.json`](benchmarks/agent_query/compact_query_output_review.json)
+contains source and artifact pins, suite and binary hashes, the registration and
+amendment, every oracle observation and every cold/warm timing. These focused
+query measurements do not replace release-wide performance qualification.

SECURITY.md

@@ -137,3 +137,22 @@ of source-backed prose per document/rationale resource, so exported artifacts
 include those excerpts as well as existing names and provenance. Apply the same
 repository disclosure policy to these graph artifacts. Corpus size/deadline
 failures remain explicit and do not publish a partially built semantic index.
+
+## Local query and saved-output caches
+
+Completed-output budgets can save source excerpts, report content and diagnostics
+under the working directory's `.compass/cache/output`. Treat these records and
+query-response cache databases as repository-derived sensitive data. They are
+local only and must not be committed or attached to public issues. New saved
+output directories use owner-only permissions on Unix; existing directory access
+policy remains the owner's responsibility. Redirected directories and record
+symlinks are rejected. Publication uses the existing atomic create primitive.
+Readers enforce schema, digest, regular-file, byte-size and UTF-8 offset checks;
+retention scans are bounded. A content digest detects corruption and does not
+authenticate the original output or graph semantics.
+
+The response cache has 32 entries, a 1 MiB payload limit and a 64 MiB SQLite page
+ceiling. Lookup requires the verified graph identity and Program IR/profile/
+request/mode identity, validates payload length, checksum and typed schema, and
+checks deadlines. Source excerpts and partial responses are excluded. Cache
+errors use native execution. Neither cache adds network or credential access.