ast-mcp-server 0.9.1 → 0.10.0

package/CHANGELOG.md

@@ -6,16 +6,42 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
-## [0.9.1] — local release candidate, pending release (2026-08-16)
+## [0.10.0] — local release candidate, pending release (2026-08-19)
+
+### Added
+
+- Added deterministic atomic `ast_explore` clusters, categorized omission metadata, opt-in compiler-authoritative call spines, and registered-handler parity across MCP and the batch CLI.
+- Added read-only `ast_find_test_candidates` across MCP and `ast-tool run`, with incoming compiler authority, fail-closed incomplete evidence, whole-candidate pagination, and lossless final JSON/TOON parity.
 
 ### Fixed
 
-- Public-registry verification now creates and normalizes its harness-owned explicit canary cache root to owner-private `0700`, independent of the runner umask, before exercising the package's fail-closed SQLite storage boundary.
+- Oversized `ast_explore` call-spine aggregates are omitted atomically instead of failing valid requests.
+- SQLite capability fallback now preserves fresh compiler-backed reads while retaining failed memory-backed index observability. Stable capability and invalid-root fallbacks retry only after restart or policy change; transient storage failures continue to recover automatically.
+
+### Release status
+
+- This local candidate is pending its exact-tree release matrix, CI, and the repository's separately authorized delivery sequence. It has not been published to npm, assigned to `next` or `latest`, tagged in Git, or released on GitHub; registry and GitHub readbacks remain authoritative.
+
+## [0.9.2] — local release candidate, pending release (2026-08-16)
+
+### Fixed
+
+- Public-registry verification now derives both the consumer report and the release-preflight exact-key validator from one canonical SQLite-default gate contract, preventing duplicated fixtures from masking producer/validator drift while preserving fail-closed rejection of missing or unexpected gates.
 
 ### Release status
 
 - This local recovery candidate is pending exact-tree CI and the repository's separately authorized delivery sequence. It has not been published to npm, assigned to `next` or `latest`, tagged in Git, or released on GitHub; registry and GitHub readbacks remain authoritative.
 
+## [0.9.1] — published to `next`, verification failed, not promoted (2026-08-16)
+
+### Fixed
+
+- Public-registry verification now creates and normalizes its harness-owned explicit canary cache root to owner-private `0700`, independent of the runner umask, before exercising the package's fail-closed SQLite storage boundary.
+
+### Release status
+
+- npm published these immutable bytes under `next` with provenance and the expected Git commit. The public registry consumer passed every package, provenance, SQLite, mutation, and setup gate, including the corrected owner-private canary root; final release preflight then rejected the report because its duplicated exact-key schema still described the earlier memory-default gate set. Version `0.9.1` was never promoted to `latest`, tagged in Git, or released on GitHub.
+
 ## [0.9.0] — published to `next`, verification failed, not promoted (2026-08-16)
 
 ### Added

package/README.md

@@ -25,16 +25,17 @@ Coding agents often fall back to two generic operations: read files as plain tex
 
 This MCP server gives the agent structural code tools in addition to generic file reads and writes. Under the hood, `ts-morph` uses the TypeScript compiler project model, so the server can reason about declarations and references as code rather than undifferentiated text.
 
-| Need                           | Structural operation      | Returned scope                                             |
-| ------------------------------ | ------------------------- | ---------------------------------------------------------- |
-| Read a bounded file            | `ast_get_file`            | Exact selected source lines, hashes, and bounded freshness |
-| Explore bounded context        | `ast_explore`             | Ranked selectors plus optional source and references       |
-| Understand a file              | `ast_get_outline`         | Signatures without implementation bodies                   |
-| Inspect one declaration        | `ast_get_symbol_source`   | Exact source for one function, method, class, or type      |
-| Find usages across the project | `ast_find_references`     | Compiler-resolved reference locations                      |
-| Understand symbol impact       | `ast_get_impact`          | Bounded direct/transitive compiler-backed relationships    |
-| Rename a symbol everywhere     | `ast_rename_symbol`       | A reviewed project-wide rename plan                        |
-| Change one implementation      | `ast_replace_symbol_body` | A body-only plan that preserves the declaration            |
+| Need                           | Structural operation       | Returned scope                                              |
+| ------------------------------ | -------------------------- | ----------------------------------------------------------- |
+| Read a bounded file            | `ast_get_file`             | Exact selected source lines, hashes, and bounded freshness  |
+| Explore bounded context        | `ast_explore`              | Ranked selectors plus optional source and references        |
+| Understand a file              | `ast_get_outline`          | Signatures without implementation bodies                    |
+| Inspect one declaration        | `ast_get_symbol_source`    | Exact source for one function, method, class, or type       |
+| Find usages across the project | `ast_find_references`      | Compiler-resolved reference locations                       |
+| Understand symbol impact       | `ast_get_impact`           | Bounded direct/transitive compiler-backed relationships     |
+| Select affected tests          | `ast_find_test_candidates` | Whole candidate proofs from incoming compiler relationships |
+| Rename a symbol everywhere     | `ast_rename_symbol`        | A reviewed project-wide rename plan                         |
+| Change one implementation      | `ast_replace_symbol_body`  | A body-only plan that preserves the declaration             |
 
 Reads can start with a bounded file slice, a compact outline, or exact source only for the declaration that needs inspection. Mutations are prepared in memory first, compared against baseline diagnostics, and returned as immutable, hash-bound plans. Nothing is written until the caller reviews and explicitly applies the plan.
 
@@ -46,6 +47,7 @@ Reads can start with a bounded file slice, a compact outline, or exact source on
 - Use `ast_get_outline` for a compact body-free view of a known file without source lines.
 - Use `ast_get_symbol_source` when one declaration or implementation is the required evidence.
 - Use `ast_get_impact` when the exact symbol is known and bounded direct/transitive compiler relationships are needed; it is read-only evidence, not a mutation plan.
+- Use `ast_find_test_candidates` when an exact symbol should map to conservative test candidates. It forces incoming compiler traversal, returns complete relationship paths, and never executes tests.
 
 `snapshot_state: "fresh"` means that the returned file bytes match the synchronized compiler snapshot. The separate `freshness` object describes the project/session state and preserves causes such as source changes or watcher failure. Neither field means that the project has zero TypeScript diagnostics; use `ast_get_diagnostics` for compiler errors and warnings.
 
@@ -62,7 +64,7 @@ The server exposes evidence labels instead of collapsing every result into an un
 
 Freshness is orthogonal to TypeScript diagnostics. `fresh` means the evidence matches the synchronized snapshot; `pending`, `rebuilding`, `stale`, or `degraded` means the response must not be presented as current compiler evidence. Read tools expose the state, causes (`source_change`, `config_change`, `index_failure`, `watcher_failure`, or `compiler_rebuild`), and bounded `checked_at` timestamp. `ast_get_impact` refuses non-fresh compiler relationships. `ast_explore` returns the state together with `completeness`, `unresolved`, `budget`, and `truncation` metadata rather than silently dropping evidence.
 
-All reads are budgeted. Callers control pagination and, where applicable, `max_bytes`, `reference_limit`, `max_depth`, `max_nodes`, and `max_edges`; responses report the effective limits and whether a record, byte, depth, edge, invocation, or serialization limit truncated the result. A truncated or unresolved result is incomplete evidence, not an empty negative result. The internal test-candidate resolver follows the same rule: it accepts only fresh, exact compiler-backed impact, emits direct/transitive evidence and bounded relationship IDs, and never executes tests or guesses from filenames alone.
+All reads are budgeted. Callers control pagination and, where applicable, `max_bytes`, `reference_limit`, `max_depth`, `max_nodes`, and `max_edges`; responses report the effective limits and whether a record, byte, depth, edge, invocation, or serialization limit truncated the result. A truncated or unresolved result is incomplete evidence, not an empty negative result. `ast_find_test_candidates` follows the same rule: it accepts only fresh, exact compiler-backed impact, emits direct/transitive evidence and bounded relationship IDs, and never executes tests or guesses from filenames alone. Only a complete authoritative traversal may return `candidates: []` with `proven_empty: true`.
 
 ## Why this helps
 
@@ -82,11 +84,11 @@ The included batch benchmark records a 50% reduction in model round-trips and a
 
 ## Supported environment and trust boundary
 
-The local `0.9.1` release candidate requires Node.js `>=22.13.0`; its evidence matrix targets exact Node.js 22.13.0 and the current Node.js 24 line. Published v0.8.1 retains its immutable historical Node.js 22.5.0/24 evidence. Managed setup-file publication additionally requires GNU coreutils 9.7 `mv` supporting `--update=none-fail`, `--exchange`, `--no-copy`, and `--no-target-directory`, GNU coreutils `ln -L -T`, procfs descriptor paths at `/proc/self/fd`, and `O_DIRECTORY`/`O_NOFOLLOW`. Other Linux architectures or systems without those filesystem primitives, macOS, and Windows remain unverified.
+The local `0.10.0` release candidate requires Node.js `>=22.13.0`; its evidence matrix targets exact Node.js 22.13.0 and the current Node.js 24 line. Published v0.8.1 retains its immutable historical Node.js 22.5.0/24 evidence. Managed setup-file publication additionally requires GNU coreutils 9.7 `mv` supporting `--update=none-fail`, `--exchange`, `--no-copy`, and `--no-target-directory`, GNU coreutils `ln -L -T`, procfs descriptor paths at `/proc/self/fd`, and `O_DIRECTORY`/`O_NOFOLLOW`. Other Linux architectures or systems without those filesystem primitives, macOS, and Windows remain unverified.
 
 This is a local stdio server. It runs with the invoking user's filesystem permissions, and clients may request any `project_root` that user can access. It does not provide HTTP authentication, sandboxing, tenant isolation, or a remote-service security boundary. Remote, untrusted, and multi-tenant operation is unsupported.
 
-In the local `0.9.1` release candidate, an absent `AST_SYMBOL_INDEX_PERSISTENCE` or explicit `enabled` selects the private SQLite symbol-index cache. `disabled` is the immediate memory-only rollback. `canary` requires an explicit absolute normalized `AST_SYMBOL_INDEX_CACHE_ROOT`. Invalid policy or storage fails closed to compiler-authoritative memory reads with bounded path-free status.
+In the local `0.10.0` release candidate, an absent `AST_SYMBOL_INDEX_PERSISTENCE` or explicit `enabled` selects the private SQLite symbol-index cache. `disabled` is the immediate memory-only rollback. `canary` requires an explicit absolute normalized `AST_SYMBOL_INDEX_CACHE_ROOT`. Invalid policy or storage fails closed to compiler-authoritative memory reads with bounded path-free status.
 
 The default cache root is selected from `AST_SYMBOL_INDEX_CACHE_ROOT`, then `XDG_CACHE_HOME`, then `HOME`. Inspect or clear only derived cache artifacts through the bounded CLI:
 
@@ -298,6 +300,7 @@ Project-scoped tools accept `project_root`, either the project directory or an e
 | `ast_search_symbols`        | Paginated structural symbol discovery                                | No            |
 | `ast_find_references`       | Compiler-resolved references with bounded context                    | No            |
 | `ast_get_impact`            | Bounded incoming/outgoing compiler-backed impact evidence            | No            |
+| `ast_find_test_candidates`  | Paginated affected tests with atomic compiler relationship proofs    | No            |
 | `ast_get_diagnostics`       | Project- or file-scoped TypeScript diagnostics                       | No            |
 | `ast_rename_symbol`         | Prepare a project-wide rename                                        | No            |
 | `ast_replace_symbol_body`   | Prepare a body-only replacement while preserving the signature       | No            |
@@ -307,7 +310,9 @@ Project-scoped tools accept `project_root`, either the project directory or an e
 
 Read results use project-relative paths, deterministic ordering, structured MCP output, and pagination where result sets can grow with the project.
 
-`ast_explore` supports query, exact file, and exact symbol routes. Its default `summary` profile returns bounded reusable selectors; `context` adds selected source and `full` adds compiler references. Every response reports freshness, completeness, truncation, unresolved selectors, record limits, and a serialized byte budget. Use the primitive tools when a single exact operation is clearer or when preparing a mutation.
+`ast_explore` supports query, exact file, and exact symbol routes. Its default `summary` profile returns bounded reusable selectors; `context` adds selected source and `full` adds compiler references. Whole symbol clusters are admitted under the caller's `max_bytes` ceiling, so source, reference records, and call paths are never sliced. `omissions` classifies withheld components as `budget`, `incomplete`, or `untrusted`, and any requested omission keeps completeness false.
+
+Exact `file_path` plus `symbol_path` requests may opt into bounded static `call_spines`. Only fresh, exact, compiler-resolved invocation sites qualify; generic references, dynamic dispatch, and runtime behavior are not inferred. Absence of `call_spines` performs no call traversal. Every response still reports freshness, completeness, truncation, unresolved selectors, record limits, and canonical serialized-byte accounting. Use the primitive tools when a single exact operation is clearer or when preparing a mutation. See [ADR 0013](docs/adr/0013-ast-explore-presentation.md).
 
 Symbol search is relevance-ranked and defaults to at most 20 `summary` records containing `file`, a directly reusable `selector`, `kind`, and body-free `signature`. Request `detail: "selectors"` for routing coordinates only, or `detail: "full", limit: 100` for the v0.4.0 fields/page. References default to `detail: "locations"`; request `detail: "context"` only when the bounded source line is needed.
 
@@ -357,6 +362,8 @@ Example search-to-source pipeline:
 
 A `$ref` is an RFC 6901 JSON Pointer rooted at prior step results. References cannot point forward. If `emit` is omitted, only the final step result is returned; intermediate results remain inside the process.
 
+`ast_find_test_candidates` and `ast_explore` are admitted as read steps. The batch runner injects the pipeline `project_root`, rejects a conflicting step root, and invokes the same registered MCP implementation. Candidate relationship proofs and exploration clusters remain whole; final JSON and TOON differ only in serialization, not logical evidence.
+
 ### Bounded foreach
 
 ```json

package/SECURITY.md

@@ -11,7 +11,7 @@ Security fixes are provided for the exact version currently identified by the np
 | Earlier npm versions                        | No        |
 | Unpublished release candidates              | No        |
 
-This project supports trusted single-user local stdio use; the supported operating-system and architecture boundary remains Linux x64 only. The local `0.9.1` release candidate requires Node.js `>=22.13.0`, with evidence targeted at exact Node.js 22.13.0 and the governed Node.js 24 major. Published v0.8.1 retains its immutable Node.js 22.5.0/24 release matrix. Managed setup mutation requires GNU coreutils 9.7 `mv --update=none-fail --exchange --no-copy --no-target-directory`, GNU coreutils `ln -L -T`, and procfs descriptor-relative paths at `/proc/self/fd` with `O_DIRECTORY`/`O_NOFOLLOW`. The candidate's default SQLite cache also relies on Linux ownership, mode, no-follow, link-count and inode-identity checks; it does not defend against a malicious same-UID process. Other Linux architectures and systems without those primitives are unverified, as are macOS and Windows. Remote, untrusted, and multi-tenant use is outside the supported security boundary.
+This project supports trusted single-user local stdio use; the supported operating-system and architecture boundary remains Linux x64 only. The local `0.10.0` release candidate requires Node.js `>=22.13.0`, with evidence targeted at exact Node.js 22.13.0 and the governed Node.js 24 major. Published v0.8.1 retains its immutable Node.js 22.5.0/24 release matrix. Managed setup mutation requires GNU coreutils 9.7 `mv --update=none-fail --exchange --no-copy --no-target-directory`, GNU coreutils `ln -L -T`, and procfs descriptor-relative paths at `/proc/self/fd` with `O_DIRECTORY`/`O_NOFOLLOW`. The candidate's default SQLite cache also relies on Linux ownership, mode, no-follow, link-count and inode-identity checks; it does not defend against a malicious same-UID process. Other Linux architectures and systems without those primitives are unverified, as are macOS and Windows. Remote, untrusted, and multi-tenant use is outside the supported security boundary.
 
 ## Reporting a vulnerability
 

package/dist/batch/schema.js

@@ -14,6 +14,8 @@ export const READ_BATCH_TOOLS = [
     "ast_get_symbol_source",
     "ast_search_symbols",
     "ast_find_references",
+    "ast_find_test_candidates",
+    "ast_explore",
     "ast_get_diagnostics",
 ];
 export const PREPARE_BATCH_TOOLS = [

package/dist/server.js

@@ -3,6 +3,7 @@ import { McpServer, } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { PublicOperationalError } from "./services/public-errors.js";
 import { registerApplyOperation } from "./tools/apply_operation.js";
 import { registerFindReferences } from "./tools/find_references.js";
+import { registerFindTestCandidates } from "./tools/find_test_candidates.js";
 import { registerGetDiagnostics } from "./tools/get_diagnostics.js";
 import { registerGetFile } from "./tools/get_file.js";
 import { registerGetImpact } from "./tools/get_impact.js";
@@ -47,6 +48,7 @@ export function createServer(options = {}) {
     registerSearchSymbols(server);
     registerFindReferences(server);
     registerGetImpact(server);
+    registerFindTestCandidates(server);
     registerGetDiagnostics(server);
     registerGetFile(server);
     registerRenameSymbol(server);

package/dist/services/agent-targets.js

@@ -5,6 +5,7 @@ const EXPECTED_TOOLS = [
     "ast_get_symbol_source",
     "ast_search_symbols",
     "ast_find_references",
+    "ast_find_test_candidates",
     "ast_get_diagnostics",
     "ast_rename_symbol",
     "ast_replace_symbol_body",

package/dist/services/call-spines.js

@@ -0,0 +1,101 @@
+const endpointKey = (endpoint) => [endpoint.file, endpoint.symbol_path, endpoint.selector].join("\u0000");
+const sequenceKey = (values) => JSON.stringify(values);
+const exactCall = (edge) => edge.kind === "call" &&
+    edge.provenance === "compiler" &&
+    edge.confidence === "exact" &&
+    edge.resolution === "resolved" &&
+    edge.freshness.state === "fresh" &&
+    edge.compiler_authoritative;
+function assertLimit(value, minimum, name) {
+    if (!Number.isSafeInteger(value) || value < minimum)
+        throw new Error(`Call spine ${name} is invalid.`);
+    return value;
+}
+export function planCallSpines(root, edges, options) {
+    const maxDepth = assertLimit(options.max_depth, 0, "max_depth");
+    const maxNodes = assertLimit(options.max_nodes, 1, "max_nodes");
+    const maxEdges = assertLimit(options.max_edges, 1, "max_edges");
+    const accepted = edges.filter(exactCall);
+    const freshness = options.freshness?.state ?? edges[0]?.freshness.state;
+    const authorityState = freshness !== "fresh" || accepted.length !== edges.length
+        ? "untrusted"
+        : options.discovery_complete === false
+            ? "incomplete"
+            : "authoritative";
+    const reasons = new Set();
+    const rootKey = endpointKey(root);
+    const initial = { endpoint: root, endpoints: [root], relationshipIds: [], depth: 0 };
+    const records = new Map([[rootKey, initial]]);
+    const observedEdges = new Set();
+    let layer = [initial];
+    while (layer.length > 0) {
+        const candidates = new Map();
+        for (const current of layer.sort((left, right) => endpointKey(left.endpoint).localeCompare(endpointKey(right.endpoint)))) {
+            const incident = accepted
+                .filter((edge) => options.direction === "outgoing"
+                ? endpointKey(edge.source) === endpointKey(current.endpoint)
+                : endpointKey(edge.target) === endpointKey(current.endpoint))
+                .sort((left, right) => left.relationship_id.localeCompare(right.relationship_id));
+            for (const edge of incident) {
+                if (!observedEdges.has(edge.relationship_id) && observedEdges.size >= maxEdges) {
+                    reasons.add("edge_limit");
+                    continue;
+                }
+                observedEdges.add(edge.relationship_id);
+                const next = options.direction === "outgoing" ? edge.target : edge.source;
+                const key = endpointKey(next);
+                if (current.endpoints.some((endpoint) => endpointKey(endpoint) === key) || records.has(key))
+                    continue;
+                if (current.depth >= maxDepth) {
+                    reasons.add("depth_limit");
+                    continue;
+                }
+                const outgoing = options.direction === "outgoing";
+                const candidate = {
+                    endpoint: next,
+                    endpoints: outgoing ? [...current.endpoints, next] : [next, ...current.endpoints],
+                    relationshipIds: outgoing
+                        ? [...current.relationshipIds, edge.relationship_id]
+                        : [edge.relationship_id, ...current.relationshipIds],
+                    depth: current.depth + 1,
+                };
+                const previous = candidates.get(key);
+                if (!previous ||
+                    sequenceKey(candidate.relationshipIds) < sequenceKey(previous.relationshipIds))
+                    candidates.set(key, candidate);
+            }
+        }
+        const ordered = [...candidates.values()].sort((left, right) => endpointKey(left.endpoint).localeCompare(endpointKey(right.endpoint)));
+        const available = maxNodes - records.size;
+        if (ordered.length > available)
+            reasons.add("node_limit");
+        layer = ordered.slice(0, Math.max(0, available));
+        for (const record of layer)
+            records.set(endpointKey(record.endpoint), record);
+    }
+    const paths = [...records.values()]
+        .filter((record) => record.depth > 0)
+        .sort((left, right) => left.depth - right.depth ||
+        endpointKey(left.endpoint).localeCompare(endpointKey(right.endpoint)))
+        .map((record) => ({
+        endpoint: record.endpoint,
+        endpoints: record.endpoints,
+        relationship_ids: record.relationshipIds,
+    }));
+    const incomplete = authorityState !== "authoritative" || reasons.size > 0;
+    return {
+        root,
+        direction: options.direction,
+        paths,
+        visited: {
+            nodes: records.size,
+            edges: observedEdges.size,
+            max_depth: Math.max(0, ...paths.map((path) => path.relationship_ids.length)),
+        },
+        budget: { max_depth: maxDepth, max_nodes: maxNodes, max_edges: maxEdges },
+        incomplete,
+        truncation_reasons: ["depth_limit", "node_limit", "edge_limit"].filter((reason) => reasons.has(reason)),
+        authority_state: authorityState,
+        empty_proven: paths.length === 0 && !incomplete,
+    };
+}

package/dist/services/context-builder.js

@@ -1,15 +1,20 @@
-import { Buffer } from "node:buffer";
 import path from "node:path";
 import { buildFileOutline, nodeSourceWithLocation } from "./outline.js";
 import { paginate } from "./pagination.js";
+import { resolveImpactRoot } from "./impact.js";
+import { planCallSpines } from "./call-spines.js";
 import { isCooperativeInterruption, NO_REQUEST_CONTEXT, } from "./request-context.js";
 import { findDeclarationByName, getSourceFileOrThrow, reportSymbolIndexFailure, } from "./project.js";
 import { collectSymbolReferences } from "./references.js";
+import { collectCompilerCallRelationships } from "./relationships.js";
+import { presentExploreClusters } from "./explore-presentation.js";
 import { searchProjectSymbolsPage, searchProjectSymbolsPageWithIndex, sourceFileSymbols, symbolMatchRank, } from "./symbols.js";
 export const EXPLORE_DEFAULT_LIMIT = 20;
 export const EXPLORE_DEFAULT_REFERENCE_LIMIT = 20;
 export const EXPLORE_DEFAULT_MAX_BYTES = 64 * 1024;
 export const EXPLORE_MAX_BYTES = 1024 * 1024;
+export const EXPLORE_DEFAULT_OMISSION_DETAIL_LIMIT = 20;
+export const EXPLORE_MAX_OMISSION_DETAIL_LIMIT = 100;
 function matchesQuery(record, query) {
     const normalizedQuery = query.toLowerCase();
     return (record.name.toLowerCase().includes(normalizedQuery) ||
@@ -130,9 +135,6 @@ function projectSymbol(detail, record) {
         signature: record.signature,
     };
 }
-function jsonBytes(value) {
-    return Buffer.byteLength(JSON.stringify(value), "utf8");
-}
 function effectiveExpansion(request) {
     return {
         source: request.includeSource ?? (request.detail === "context" || request.detail === "full"),
@@ -148,6 +150,27 @@ export async function buildExploreContext(context, request, requestContext = NO_
     const expansion = effectiveExpansion(request);
     const unresolved = [];
     const evidence = [];
+    let callSpines;
+    if (request.callSpines) {
+        if (!request.filePath || !request.symbolPath || routed.route !== "symbol") {
+            throw new Error("Call spines require an exact file_path and symbol_path.");
+        }
+        const freshness = {
+            state: effectiveContext.status.state,
+            causes: effectiveContext.status.causes,
+            checked_at: effectiveContext.status.lastSuccessfulSyncAt,
+        };
+        const root = resolveImpactRoot(effectiveContext.project, effectiveContext.projectRoot, { file_path: request.filePath, symbol_path: request.symbolPath }, requestContext);
+        const projected = collectCompilerCallRelationships(effectiveContext.project, effectiveContext.projectRoot, freshness, { max_edges: request.callSpines.maxEdges }, requestContext);
+        callSpines = planCallSpines(root, projected.edges, {
+            direction: request.callSpines.direction,
+            max_depth: request.callSpines.maxDepth,
+            max_nodes: request.callSpines.maxNodes,
+            max_edges: request.callSpines.maxEdges,
+            discovery_complete: !projected.incomplete,
+            freshness,
+        });
+    }
     for (const record of page.items) {
         requestContext.checkpoint();
         let sourceFile;
@@ -190,30 +213,66 @@ export async function buildExploreContext(context, request, requestContext = NO_
         }
     }
     const symbols = page.items.map((record) => projectSymbol(request.detail, record));
-    let returnedSymbols = [...symbols];
-    let returnedEvidence = [...evidence];
-    let reason = page.has_more ? "record_limit" : null;
-    let result = createResult(effectiveContext, request, routed.route, routed.file, routed.symbol, returnedSymbols, returnedEvidence, page.total, unresolved, reason);
-    while (jsonBytes(result) > request.maxBytes &&
-        (returnedEvidence.length > 0 || returnedSymbols.length > 0)) {
-        requestContext.checkpoint();
-        reason = "byte_limit";
-        if (returnedEvidence.length > 0) {
-            returnedEvidence = returnedEvidence.slice(0, -1);
+    const initialResult = createResult(effectiveContext, request, routed.route, routed.file, routed.symbol, symbols, evidence, page.total, unresolved, page.has_more ? "record_limit" : null);
+    const evidenceBySelector = new Map(evidence.map((item) => [item.selector, item]));
+    const omissions = unresolved.map((item) => ({
+        subject: item.selector,
+        category: "incomplete",
+        component: item.reason === "source_unresolved" ? "source" : "references",
+        reason: item.reason,
+    }));
+    for (const item of evidence) {
+        if (item.references?.has_more) {
+            omissions.push({
+                subject: item.selector,
+                category: "budget",
+                component: "references",
+                reason: "reference_limit",
+            });
         }
-        else {
-            returnedSymbols = returnedSymbols.slice(0, -1);
-            const selectors = new Set(returnedSymbols.map((symbol) => symbol.selector));
-            returnedEvidence = returnedEvidence.filter((item) => selectors.has(item.selector));
+    }
+    if (callSpines?.authority_state === "untrusted") {
+        omissions.push({
+            subject: callSpines.root.selector,
+            category: "untrusted",
+            component: "call_spine",
+            reason: "non_exact_evidence",
+        });
+    }
+    else if (callSpines?.authority_state === "incomplete") {
+        omissions.push({
+            subject: callSpines.root.selector,
+            category: "incomplete",
+            component: "call_spine",
+            reason: "call_discovery_incomplete",
+        });
+    }
+    if (callSpines) {
+        for (const reason of callSpines.truncation_reasons) {
+            omissions.push({
+                subject: callSpines.root.selector,
+                category: "budget",
+                component: "call_spine",
+                reason,
+            });
         }
-        result = createResult(effectiveContext, request, routed.route, routed.file, routed.symbol, returnedSymbols, returnedEvidence, page.total, unresolved, reason);
     }
     requestContext.checkpoint();
-    const usedBytes = jsonBytes(result);
-    return {
-        ...result,
-        budget: { ...result.budget, used_bytes: usedBytes },
-    };
+    return presentExploreClusters({
+        base: initialResult,
+        clusters: symbols.map((symbol) => ({
+            symbol,
+            evidence: evidenceBySelector.get(symbol.selector),
+        })),
+        offset: request.offset,
+        limit: request.limit,
+        total: page.total,
+        maxBytes: request.maxBytes,
+        omissions,
+        omissionDetailLimit: request.omissionDetailLimit ?? EXPLORE_DEFAULT_OMISSION_DETAIL_LIMIT,
+        callSpines,
+        unresolved,
+    });
 }
 function createResult(context, request, route, file, symbol, symbols, evidence, total, unresolved, reason) {
     const hasMore = request.offset + symbols.length < total;

package/dist/services/explore-presentation.js

@@ -0,0 +1,160 @@
+import { Buffer } from "node:buffer";
+export const EXPLORE_OMISSION_REASONS = [
+    "byte_limit",
+    "reference_limit",
+    "source_unresolved",
+    "references_unresolved",
+    "non_exact_evidence",
+    "call_discovery_incomplete",
+    "depth_limit",
+    "node_limit",
+    "edge_limit",
+];
+function jsonBytes(value) {
+    return Buffer.byteLength(JSON.stringify(value), "utf8");
+}
+function summarize(omissions, detailLimit) {
+    const details = [...omissions].sort((left, right) => [left.subject, left.category, left.component, left.reason]
+        .join("\0")
+        .localeCompare([right.subject, right.category, right.component, right.reason].join("\0")));
+    const countMap = new Map();
+    for (const item of omissions) {
+        const key = `${item.category}\0${item.component}`;
+        countMap.set(key, (countMap.get(key) ?? 0) + 1);
+    }
+    const counts = [...countMap]
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, count]) => {
+        const [category, component] = key.split("\0");
+        return { category, component, count };
+    });
+    return {
+        counts,
+        details: details.slice(0, detailLimit),
+        total: omissions.length,
+        has_more: details.length > detailLimit,
+    };
+}
+function selectorOnly(symbol) {
+    return { file: symbol.file, selector: symbol.selector, kind: symbol.kind };
+}
+function omittedClusterParts(symbol, evidence) {
+    const component = (value) => ({
+        subject: symbol.selector,
+        category: "budget",
+        component: value,
+        reason: "byte_limit",
+    });
+    return [
+        ...(symbol.signature === undefined ? [] : [component("signature")]),
+        ...(evidence?.source === undefined ? [] : [component("source")]),
+        ...(evidence?.references === undefined ? [] : [component("references")]),
+    ];
+}
+export function presentExploreClusters(input) {
+    const symbols = [];
+    const evidence = [];
+    let omissions = [...input.omissions];
+    let consumed = 0;
+    let byteLimited = false;
+    const build = (detailLimit, includeCallSpines) => {
+        const callSpinesOmitted = input.callSpines !== undefined && !includeCallSpines;
+        const effectiveOmissions = callSpinesOmitted
+            ? [
+                ...omissions,
+                {
+                    subject: input.callSpines.root.selector,
+                    category: "budget",
+                    component: "call_spine",
+                    reason: "byte_limit",
+                },
+            ]
+            : omissions;
+        const spinesComplete = input.callSpines === undefined
+            ? undefined
+            : includeCallSpines && !input.callSpines.incomplete;
+        const hasMore = input.offset + consumed < input.total;
+        const evidenceComplete = effectiveOmissions.length === 0 &&
+            (input.unresolved?.length ?? 0) === 0 &&
+            spinesComplete !== false;
+        const reason = byteLimited || callSpinesOmitted ? "byte_limit" : hasMore ? "record_limit" : null;
+        const result = {
+            ...input.base,
+            ...(includeCallSpines && input.callSpines ? { call_spines: input.callSpines } : {}),
+            symbols,
+            evidence,
+            offset: input.offset,
+            limit: input.limit,
+            total: input.total,
+            has_more: hasMore,
+            next_offset: hasMore ? input.offset + consumed : null,
+            omissions: summarize(effectiveOmissions, detailLimit),
+            completeness: {
+                complete: !hasMore && evidenceComplete,
+                symbols_complete: !hasMore,
+                evidence_complete: evidenceComplete,
+                ...(spinesComplete === undefined ? {} : { spines_complete: spinesComplete }),
+                unresolved: input.unresolved ?? [],
+            },
+            budget: {
+                max_records: input.limit,
+                max_bytes: input.maxBytes,
+                max_depth: null,
+                max_edges: null,
+                max_invocations: 1,
+                used_bytes: 0,
+            },
+            truncation: { truncated: reason !== null, reason },
+        };
+        let usedBytes = 0;
+        let fixed = result;
+        for (let index = 0; index < 10; index += 1) {
+            fixed = { ...result, budget: { ...result.budget, used_bytes: usedBytes } };
+            const next = jsonBytes(fixed);
+            if (next === usedBytes)
+                return fixed;
+            usedBytes = next;
+        }
+        return { ...fixed, budget: { ...fixed.budget, used_bytes: jsonBytes(fixed) } };
+    };
+    const fittingResult = () => {
+        for (let detailLimit = input.omissionDetailLimit; detailLimit >= 0; detailLimit -= 1) {
+            if (input.callSpines) {
+                const included = build(detailLimit, true);
+                if (included.budget.used_bytes <= input.maxBytes)
+                    return included;
+            }
+            const omitted = build(detailLimit, false);
+            if (omitted.budget.used_bytes <= input.maxBytes)
+                return omitted;
+        }
+        return null;
+    };
+    for (const cluster of input.clusters) {
+        const omissionsBeforeCluster = omissions;
+        symbols.push(cluster.symbol);
+        if (cluster.evidence)
+            evidence.push(cluster.evidence);
+        consumed += 1;
+        if (fittingResult())
+            continue;
+        symbols[symbols.length - 1] = selectorOnly(cluster.symbol);
+        if (cluster.evidence)
+            evidence.pop();
+        omissions = [...omissions, ...omittedClusterParts(cluster.symbol, cluster.evidence)];
+        byteLimited = true;
+        if (fittingResult())
+            continue;
+        if (symbols.length > 1) {
+            symbols.pop();
+            consumed -= 1;
+            omissions = omissionsBeforeCluster;
+            break;
+        }
+        throw new Error(`max_bytes cannot fit selector ${cluster.symbol.selector}.`);
+    }
+    const result = fittingResult();
+    if (!result)
+        throw new Error("max_bytes cannot fit the ast_explore result shell.");
+    return result;
+}

package/dist/services/project.js

@@ -62,8 +62,7 @@ function fallbackToMemory(session, reason) {
     session.context = {
         ...session.context,
         status: transitionProjectStatus(session.context.status, {
-            type: "index_failed",
-            error: boundedReason,
+            type: "index_disabled",
         }),
         symbolIndex: new InMemorySymbolIndex(),
         symbolIndexBackend: "memory",
@@ -124,6 +123,10 @@ async function ensureSessionSymbolIndex(session, requestContext) {
             symbolIndexObservability: createInitialSymbolIndexRuntimeObservability(policy),
         };
     }
+    if (session.context.symbolIndexFallbackReason === "capability_unavailable" ||
+        (session.context.symbolIndexFallbackReason !== null && policy.backend === "memory")) {
+        return;
+    }
     if (policy.backend === "memory") {
         if (policy.mode === "enabled" || policy.mode === "canary") {
             fallbackToMemory(session, policy.reason);