knodin 0.12.2 → 0.13.0

package/dist/src/tools/knodin-tools.js

@@ -9,6 +9,10 @@
 import fs from "node:fs";
 import nodePath from "node:path";
 import { fileURLToPath } from "node:url";
+import { ClassConsumerQueryError, } from "../class-consumer-contract.js";
+import { readClassConsumerCursor } from "../class-consumer-cursor.js";
+import { validateClassConsumerDelivery } from "../class-consumer-delivery.js";
+import { finalizeClassConsumerPage } from "../class-consumer-page.js";
 import { resolveCliRuntimeCommand } from "../cli-args.js";
 import { compactExplainResult, compactQueryResult, compactSearchResult, expandCompactIdentity, } from "../compact-structural.js";
 import { buildKnodinContext } from "../context.js";
@@ -20,17 +24,21 @@ import { createEngine, KNODIN_SCHEMA_VERSION, REPO_WIDE_QUERY_PATTERNS, } from "
 import { measurePerfPhaseSync } from "../engine/perf.js";
 import { runSealedQuery } from "../engine/sealed-query.js";
 import { resolveDbPath } from "../engine/state-paths.js";
+import { deliverEvidenceBundle } from "../evidence-bundle.js";
+import { createEvidenceGraphAdapter } from "../evidence-graph.js";
 import { runExecutionProfile } from "../execution-profile.js";
 import { diagnoseFailure, } from "../failure-diagnosis.js";
 import { decorateGraphQueryResult, inspectGraphQueryHealth } from "../graph-query-health.js";
+import { findImplementationCandidates } from "../implementation-search.js";
 import { inspectRepositoryIntegrationStatus } from "../init.js";
+import { buildTaskInvestigation } from "../investigation.js";
 import { attachLifecycleHealth, attachRepairLifecycle } from "../lifecycle-health.js";
 import { readManagerUpdateState, readUpdateJournal, updateAttention } from "../manager-update.js";
 import { listMirrors } from "../mirror.js";
 import { compressOutput, compressOutputFile, deleteOutputArtifact, readOutputArtifact, } from "../output-compression.js";
 import { appendTelemetryRecord, clearTelemetry, countOutputTokens, exportTelemetry, measureOutput, readTelemetryRecords, telemetryStatus, writeTelemetryReport, } from "../output-telemetry.js";
 import { auditPullRequests, ghUnavailableReason, triagePrDetail } from "../pr-triage.js";
-import { deliverProgressiveEvidence, } from "../progressive-evidence.js";
+import { deliverProgressiveEvidence, evidenceHandleSecret, } from "../progressive-evidence.js";
 import { createRepairPlan } from "../repair-progress.js";
 import { runRepositoryInitializationProcess } from "../repository-init-process.js";
 import { discoverRepositories, initializeRepositories, inventoryRepository, searchRepositories, } from "../repository-management.js";
@@ -95,9 +103,8 @@ function inspectGatewayGraphHealth(repo) {
  * The probe is cheap — `engine.status(..., { audit: "cached" })` — so the latch
  * was buying very little in exchange for that failure mode.
  */
-async function compactGraphUnavailable(repo) {
-    const health = await inspectGatewayGraphHealth(repo);
-    return health.available ? null : health;
+async function compactGraphHealth(repo) {
+    return inspectGatewayGraphHealth(repo);
 }
 /** Runs `fn`, converting any thrown error into a structured `{ error }` result
  * instead of letting it escape into the stdio transport. Extracted from the
@@ -155,6 +162,7 @@ const QUERY_PATTERNS = [
     "handlers_of",
     "endpoints_for",
     "consumers_of",
+    "class_consumers",
     "children_of",
     "community",
     "federated_repos",
@@ -236,9 +244,15 @@ function buildDocumentedKnodinTools() {
                         enum: ["locate", "outline", "evidence", "expand"],
                         description: "evidence only: deterministic progressive-delivery level.",
                     },
+                    evidenceFiles: {
+                        type: "array",
+                        items: { type: "string" },
+                        maxItems: 32,
+                        description: "evidence only: multiple repo-relative files for a verified evidence/expand bundle; exclusive with file. alreadyPresent accepts returned bundle file handles.",
+                    },
                     continuation: {
                         type: "string",
-                        description: "evidence only: integrity-checked continuation returned by the prior level/page.",
+                        description: "evidence/class_consumers: authenticated continuation from the previous page; repeat the same target and filters.",
                     },
                     baselineHash: {
                         type: "string",
@@ -271,7 +285,7 @@ function buildDocumentedKnodinTools() {
                         description: "feature_path — deterministic downstream DFS over resolved source references. It is bounded by depth and item limits, source-evidenced per hop, cycle-guarded, and never claims runtime execution; dynamic dispatch and unresolved calls are omitted. " +
                             "lsp_diagnostics accepts a repo-relative TypeScript/JavaScript file; lsp_definitions, lsp_declarations, and lsp_implementations accept file:line:column. These use an optional local TypeScript language-service adapter, never start a daemon or write files, and return an explicit unavailable result when no local adapter supports the file type. " +
                             "api_contract_mismatches — bounded, source-evidenced static mismatch findings for literal Express/Fastify routes and literal fetch/Axios clients. Matching requires method and normalized path, and requires exact origin equality when a client uses an absolute origin; dynamic routes remain explicitly unresolved. mcp_tools — list indexed TypeScript MCP SDK tool registrations, or pass symbol to look up one exact tool name; returns description/schema/handler/file and exact versus heuristic confidence. import_cycles — repo-wide canonical directed file-import cycles; no symbol required, type-only imports included, non-import lineage/ORM edges excluded, and limit/truncated bounds output. " +
-                            "query: the graph pattern to run (callers_of, callees_of, imports_of, importers_of, inheritors_of, structural_implementations_of, tests_for, file_summary, shortest_path, cross_substrate_path, impact, dead_code, large_functions, large_files, rename_preview, flows, flow_of, flow_analysis, resource_reachability, stats, traverse, knowledge_gaps, community, federated_repos). cross_substrate_path proves only one static Salesforce Flow action to one uniquely resolved Apex @InvocableMethod and returns exact endpoint identities/evidence, freshness, budgets, and explicit unsupported crossings; it does not resolve Terraform, dbt, or arbitrary substrate paths. resource_reachability is a repo-wide, bounded, cached, on-demand TS/JS static heuristic for literal process.env/fs.readFileSync sources reaching console.log/fetch/db.query sinks; it reports evidence, coverage, omissions, freshness, truncation, and continuation and is never runtime reachability or exploitability proof. structural_implementations_of returns TypeScript structurally typed object implementations separately from nominal extends/implements results. federated_repos — discover and list all registered/configured repository paths that this engine federates queries across. community — fetch a single community's full detail (name, size, cohesion, files, and symbols) by name or substring filter; empty `symbol` = all communities. large_files — whole-file line counts (min 200), sorted descending — the file-level counterpart to large_functions, for spotting god files rather than god functions; same optional path-substring filter, empty `symbol` = all files. stats — repo-level index size + health in one call (per-repo symbol/reference/dependency/embedding/file counts, per-kind and per-language breakdowns, orphaned-embedding count, schema version, last-indexed HEAD, and cached community/hub/bridge/flow totals); federated, empty `symbol`. traverse — typed BFS from `symbol` within `depth` hops (default 3, 1–6), selectable upstream/downstream/both and explicit edge kinds; every discovered edge includes direction, kind, provenance, confidence, files, and source line, with optional Tree-sitter-grounded argument expressions honestly marked heuristic. Sets `truncated` when the `limit` cap binds; single-repo. knowledge_gaps — repo-health weaknesses in one call: thin communities (<3 symbols), single-file communities, isolated (zero-degree) symbols, and untested hub/bridge hotspots; sourced from the cached map(), federated, empty `symbol`, one row carrying a `knowledgeGaps` block. surprising_connections — resolved edges scored by a composite surprise formula (cross-community, cross-language, peripheral-to-hub, cross-test-boundary, unusual edge kind) to surface unexpected coupling; sorted highest-first, top 15 by default, federated, empty `symbol`, each row carrying a `surprise` block. suggested_questions — prioritized, human-readable review prompts synthesized from knowledge_gaps + surprising_connections (untested hotspots first, then surprising edges, then thin/single-file communities); federated, empty `symbol`, each row a `question` string citing the real symbol/file, top 10 by default. architecture_overview — a federated architecture view with scoped community coupling and independently selectable packages, layers, boundaries, hotspots, entry points, and language facets; `path` is segment-safe and applies consistently. Spring/event patterns (Java): triggers_of — the schedule edge between a @Scheduled method and its synthetic scheduler (pass the method to get its scheduler, or the scheduler to list scheduled methods). publishers_of — methods that publish a given event type (ApplicationEventPublisher.publishEvent). listeners_of — @EventListener methods that listen for a given event type. handlers_of — methods that handle a given HTTP endpoint path (Spring @*Mapping + the existing JS/Python endpoints). endpoints_for — the inverse: endpoint path(s) a given method handles. consumers_of — classes/methods consuming a given @Value config property. children_of — symbols contained in a file path (same as file_summary) or, for a class name, its member symbols by line-range containment. All seven require `symbol` (the target); single-repo, not federated.",
+                            "query: the graph pattern to run (callers_of, callees_of, imports_of, importers_of, inheritors_of, structural_implementations_of, tests_for, file_summary, shortest_path, cross_substrate_path, impact, dead_code, large_functions, large_files, rename_preview, flows, flow_of, flow_analysis, resource_reachability, stats, traverse, knowledge_gaps, community, federated_repos). cross_substrate_path proves only one static Salesforce Flow action to one uniquely resolved Apex @InvocableMethod and returns exact endpoint identities/evidence, freshness, budgets, and explicit unsupported crossings; it does not resolve Terraform, dbt, or arbitrary substrate paths. resource_reachability is a repo-wide, bounded, cached, on-demand TS/JS static heuristic for literal process.env/fs.readFileSync sources reaching console.log/fetch/db.query sinks; it reports evidence, coverage, omissions, freshness, truncation, and continuation and is never runtime reachability or exploitability proof. structural_implementations_of returns TypeScript structurally typed object implementations separately from nominal extends/implements results. federated_repos — discover and list all registered/configured repository paths that this engine federates queries across. community — fetch a single community's full detail (name, size, cohesion, files, and symbols) by name or substring filter; empty `symbol` = all communities. large_files — whole-file line counts (min 200), sorted descending — the file-level counterpart to large_functions, for spotting god files rather than god functions; same optional path-substring filter, empty `symbol` = all files. stats — repo-level index size + health in one call (per-repo symbol/reference/dependency/embedding/file counts, per-kind and per-language breakdowns, orphaned-embedding count, schema version, last-indexed HEAD, and cached community/hub/bridge/flow totals); federated, empty `symbol`. traverse — typed BFS from `symbol` within `depth` hops (default 3, 1–6), selectable upstream/downstream/both and explicit edge kinds; every discovered edge includes direction, kind, provenance, confidence, files, and source line, with optional Tree-sitter-grounded argument expressions honestly marked heuristic. Sets `truncated` when the `limit` cap binds; single-repo. knowledge_gaps — repo-health weaknesses in one call: thin communities (<3 symbols), single-file communities, isolated (zero-degree) symbols, and untested hub/bridge hotspots; sourced from the cached map(), federated, empty `symbol`, one row carrying a `knowledgeGaps` block. surprising_connections — resolved edges scored by a composite surprise formula (cross-community, cross-language, peripheral-to-hub, cross-test-boundary, unusual edge kind) to surface unexpected coupling; sorted highest-first, top 15 by default, federated, empty `symbol`, each row carrying a `surprise` block. suggested_questions — prioritized, human-readable review prompts synthesized from knowledge_gaps + surprising_connections (untested hotspots first, then surprising edges, then thin/single-file communities); federated, empty `symbol`, each row a `question` string citing the real symbol/file, top 10 by default. architecture_overview — a federated architecture view with scoped community coupling and independently selectable packages, layers, boundaries, hotspots, entry points, and language facets; `path` is segment-safe and applies consistently. class_consumers returns direct typed Apex class-use sites separately from method callers and Java config consumers; count is observed sites, consumerFileCount distinct files, testScope defaults all, limit caps sites (1-1000), path is a canonical prefix, and continuation resumes the same target/filters only while the graph snapshot remains unchanged. Supported syntax only, not runtime or complete class-use coverage. Spring/event patterns (Java): triggers_of — the schedule edge between a @Scheduled method and its synthetic scheduler (pass the method to get its scheduler, or the scheduler to list scheduled methods). publishers_of — methods that publish a given event type (ApplicationEventPublisher.publishEvent). listeners_of — @EventListener methods that listen for a given event type. handlers_of — methods that handle a given HTTP endpoint path (Spring @*Mapping + the existing JS/Python endpoints). endpoints_for — the inverse: endpoint path(s) a given method handles. consumers_of — classes/methods consuming a given @Value config property. children_of — symbols contained in a file path (same as file_summary) or, for a class name, its member symbols by line-range containment. All seven require `symbol` (the target); single-repo, not federated.",
                     },
                     depth: {
                         type: "number",
@@ -405,7 +419,7 @@ function buildDocumentedKnodinTools() {
                     testScope: {
                         type: "string",
                         enum: ["all", "test", "production"],
-                        description: "search/file_metrics: include all, test-only, or production-only files.",
+                        description: "search/file_metrics/class_consumers: all (default), test-only, or production-only files.",
                     },
                     caseSensitive: {
                         type: "boolean",
@@ -488,6 +502,11 @@ function buildDocumentedKnodinTools() {
                         type: "string",
                         description: "context only (required): free-text description of what you're doing (e.g. 'review PR #42', 'debug login timeout', 'how does auth work'). Drives a keyword heuristic that suggests which operation to run next — a hint only, never a constraint.",
                     },
+                    contextMode: {
+                        type: "string",
+                        enum: ["orientation", "implementation"],
+                        description: "context only: implementation ranks candidate functions/methods/classes without selecting a target. Omit for orientation; supply symbol for a target investigation.",
+                    },
                     changedFiles: {
                         type: "array",
                         items: { type: "string" },
@@ -734,14 +753,14 @@ export function getDocumentedKnodinToolsForSchemaProof() {
 const COMPACT_PARAMETER_DESCRIPTIONS = {
     operation: "Capability.",
     symbol: "Target.",
-    pattern: "Query pattern.",
-    impactMode: "Symbol or file.",
+    pattern: "Pattern.",
+    impactMode: "Symbol/file.",
     apply: "Apply edits.",
     // Shortened from "Review diff scope." / "Documentation section." on main: the
     // `remote` operation added to the enum costs tokens, and this surface has a
     // hard ceiling enforced by tool-schema-budget.spec.ts.
     diffScope: "Diff scope.",
-    section: "Docs section.",
+    section: "Docs.",
     persistTelemetry: "Persist telemetry.",
 };
 /**
@@ -996,6 +1015,11 @@ async function handlePullRequestsOperation(options) {
     }));
 }
 function validateKnodinArgs(args) {
+    if (args.contextMode !== undefined &&
+        !["orientation", "implementation"].includes(args.contextMode))
+        throw new Error("Invalid contextMode");
+    if (args.contextMode === "implementation" && args.symbol)
+        throw new Error("Choose implementation discovery or a target symbol, not both");
     const requireStringArray = (name, value) => {
         if (value !== undefined &&
             (!Array.isArray(value) || value.some((item) => typeof item !== "string")))
@@ -1010,6 +1034,7 @@ function validateKnodinArgs(args) {
         "exclude",
         "roots",
         "alreadyPresent",
+        "evidenceFiles",
         "chatFiles",
     ])
         requireStringArray(name, args[name]);
@@ -1148,6 +1173,10 @@ function compactFailureRelation(relation) {
 function compactFailureDiagnosis(result) {
     return {
         status: result.status,
+        available: result.available,
+        state: result.state,
+        indexCoverage: result.indexCoverage,
+        coverageNotice: result.coverageNotice,
         input: [result.input.kind, result.input.artifactId, result.input.bytes, result.input.complete],
         // `reference` is [reported path, line, column]. `owner` is
         // [stable identity, symbol, kind, start, end, signature].
@@ -1335,31 +1364,61 @@ function handleDocsOperation(section, bounded) {
 }
 async function tryCompactStructural(args, repo, selector, bounded) {
     const { operation, detailLevel, includeSource, symbol, file, byteBudget } = args;
+    const compactCandidate = detailLevel === "compact" &&
+        ((operation === "explain" && includeSource === true && !!symbol) ||
+            (operation === "search" && !!args.query) ||
+            (operation === "query" &&
+                ["file_summary", "batch_outline", "project_overview"].includes(args.pattern ?? "")));
+    if (!compactCandidate)
+        return { handled: false, value: NOT_COMPACT_STRUCTURAL };
+    const health = await compactGraphHealth(repo);
+    // Compact strings cannot carry the mandatory scope contract. Scoped, pending
+    // and unknown coverage use the normal decorated, budgeted response instead.
+    if (health.available) {
+        const coverage = health.graph.indexCoverage;
+        if (coverage?.mode !== "full" ||
+            coverage.intentState !== "complete" ||
+            coverage.repositoryComplete !== true ||
+            coverage.negativeScope !== "repository")
+            return { handled: false, value: NOT_COMPACT_STRUCTURAL, qualifiedFallback: true };
+    }
     const unavailable = async (op) => {
-        const health = await compactGraphUnavailable(repo);
-        return health ? bounded(health, op, true) : null;
+        return health.available ? null : bounded(health, op, true);
+    };
+    const verifiedCompact = async (value) => {
+        if (!health.available)
+            return { handled: true, value };
+        const after = await compactGraphHealth(repo);
+        if (!after.available)
+            return { handled: true, value: bounded(after, operation, true) };
+        const beforeCoverage = health.graph.indexCoverage;
+        const afterCoverage = after.graph.indexCoverage;
+        if (!afterCoverage ||
+            afterCoverage.mode !== "full" ||
+            afterCoverage.intentState !== "complete" ||
+            !afterCoverage.repositoryComplete ||
+            afterCoverage.negativeScope !== "repository" ||
+            afterCoverage.digest !== beforeCoverage?.digest ||
+            afterCoverage.revision !== beforeCoverage?.revision ||
+            afterCoverage.origin !== beforeCoverage?.origin)
+            return { handled: false, value: NOT_COMPACT_STRUCTURAL, qualifiedFallback: true };
+        return { handled: true, value };
     };
     if (operation === "explain" && detailLevel === "compact" && includeSource === true && symbol) {
         const blocked = await unavailable("explain");
-        return {
-            handled: true,
-            value: blocked ?? (await runCompactExplain(symbol, repo, selector, file, byteBudget)),
-        };
+        return verifiedCompact(blocked ?? (await runCompactExplain(symbol, repo, selector, file, byteBudget)));
     }
     if (operation === "search" && detailLevel === "compact" && args.query) {
         const blocked = await unavailable("search");
-        return {
-            handled: true,
-            value: blocked ??
-                (await runCompactSearch(args.query, repo, Math.min(args.limit ?? args.itemBudget ?? 5, args.itemBudget ?? 100), {
-                    languages: args.languages,
-                    extensions: args.extensions,
-                    kinds: args.kinds,
-                    path: args.path,
-                    testScope: args.testScope,
-                    offset: args.offset,
-                }, byteBudget)),
-        };
+        return verifiedCompact(blocked ??
+            (await runCompactSearch(args.query, repo, Math.min(args.limit ?? args.itemBudget ?? 5, args.itemBudget ?? 100), {
+                languages: args.languages,
+                extensions: args.extensions,
+                kinds: args.kinds,
+                path: args.path,
+                testScope: args.testScope,
+                offset: args.offset,
+            }, byteBudget)));
     }
     const compactPattern = operation === "query" &&
         detailLevel === "compact" &&
@@ -1371,11 +1430,8 @@ async function tryCompactStructural(args, repo, selector, bounded) {
     if (!compactPattern)
         return { handled: false, value: NOT_COMPACT_STRUCTURAL };
     const blocked = await unavailable(`query:${compactPattern}`);
-    return {
-        handled: true,
-        value: blocked ??
-            (await runCompactQuery(compactPattern, symbol ?? "", repo, Math.min(args.limit ?? args.itemBudget ?? 100, args.itemBudget ?? 1000), args.depth, selector, byteBudget)),
-    };
+    return verifiedCompact(blocked ??
+        (await runCompactQuery(compactPattern, symbol ?? "", repo, Math.min(args.limit ?? args.itemBudget ?? 100, args.itemBudget ?? 1000), args.depth, selector, byteBudget)));
 }
 const mcpRequestSignals = new WeakMap();
 export function attachMcpRequestSignal(args, signal) {
@@ -1423,7 +1479,7 @@ async function handleDiagnosticsOperation(repo, args, bounded) {
         })
         : persistDiagnosticsPreview(repo, options), `diagnostics:${args.telemetryAction === "export" ? "archive" : "preview"}`);
 }
-async function dispatchKnodinTool(args) {
+async function dispatchKnodinTool(args, qualifiedCompactFallback = false) {
     const startedAt = performance.now();
     const parsedArgs = (args ?? {});
     const { operation, symbol, base, diffScope, from, toRevision, reviewFiles, query, pattern, queries, to, limit, depth, impactMode, direction, relationKinds, minConfidence, includeTests, includeDataFlow, flowVariable, apply, force, detailLevel, prNumber, prState, branches, auditRange, auditBase, auditHead, expectedLogin, worktreeAction, worktreePath, telemetryAction, telemetryRetentionDays, task, changedFiles, repoPath, section, systemAction, repositories, scope, distributed, repositoryIds, components, evidence, relationshipType, requireComplete, repositoryAction, roots, linkedWorktrees, cursor, allowPartial, dryRun, manifestPath, planDigest, identity, file, kind, toIdentity, toFile, toKind, byteBudget, tokenBudget, itemBudget, includeSource, languages, extensions, kinds, path, architectureFacets, testScope, caseSensitive, offset, minLines, minComplexity, topN, sort, packAction, format, include, exclude, filePolicies, alreadyPresent, chatFiles, lineNumbers, includeTree, outputPath, artifactPath, startLine, endLine, regex, regexFlags, gitDiffScope, gitLog, statusAudit, timeoutMs, client, repairPlan, persistTelemetry, } = parsedArgs;
@@ -1483,6 +1539,11 @@ async function dispatchKnodinTool(args) {
     const observe = (output, op, minimal = false) => {
         const root = output;
         const budgetMeta = root.responseBudget;
+        const evidenceBudget = op === "evidence" &&
+            (root.protocol === "knodin-evidence-bundle-v1" ||
+                root.protocol === "knodin-progressive-evidence-v1")
+            ? root.budget
+            : undefined;
         if (op === "review")
             measurePerfPhaseSync("review_serialization", () => JSON.stringify(output));
         const telemetry = measureOutput({
@@ -1492,6 +1553,7 @@ async function dispatchKnodinTool(args) {
             startedAt,
             detailMode: minimal ? "minimal" : (detailLevel ?? "standard"),
             truncated: budgetMeta?.truncated === true ||
+                evidenceBudget?.truncated === true ||
                 root.telemetry?.truncated === true,
             schemaTokens: gatewaySchemaTokens(),
         });
@@ -1543,12 +1605,14 @@ async function dispatchKnodinTool(args) {
         const verified = await inspectGatewayGraphHealth(repo);
         if (!verified.available)
             return bounded(verified, op, minimal);
-        return bounded(decorateGraphQueryResult(result, verified.state, verified.graph.freshness), op, minimal);
+        return bounded(decorateGraphQueryResult(result, verified.state, verified.graph.freshness, verified.graph.indexCoverage, health.graph.indexCoverage), op, minimal);
     };
     validateKnodinArgs(parsedArgs);
     const compactStructural = await tryCompactStructural(parsedArgs, repo, selector, bounded);
     if (compactStructural.handled)
         return compactStructural.value;
+    if (compactStructural.qualifiedFallback)
+        return dispatchKnodinTool({ ...parsedArgs, detailLevel: "minimal" }, true);
     if (detailLevel === "compact")
         throw new Error("knodin: compact detail is unsupported here");
     switch (operation) {
@@ -1687,6 +1751,22 @@ async function dispatchKnodinTool(args) {
         case "execute":
             return handleExecutionOperation(repo, parsedArgs.profile, engine, bounded);
         case "evidence":
+            if (parsedArgs.evidenceFiles) {
+                if (parsedArgs.file)
+                    throw new Error("Choose file or evidenceFiles, not both");
+                if (parsedArgs.evidenceLevel !== "evidence" && parsedArgs.evidenceLevel !== "expand")
+                    throw new Error("Evidence bundles require evidence or expand level");
+                return observe(await deliverEvidenceBundle({
+                    repo,
+                    files: parsedArgs.evidenceFiles,
+                    level: parsedArgs.evidenceLevel,
+                    continuation: parsedArgs.continuation,
+                    alreadyPresent: parsedArgs.alreadyPresent,
+                    byteLimit: parsedArgs.byteBudget,
+                    tokenLimit: parsedArgs.tokenBudget,
+                    itemLimit: parsedArgs.itemBudget,
+                }, createEvidenceGraphAdapter(engine)), "evidence");
+            }
             return handleProgressiveEvidenceOperation(repo, parsedArgs, observe);
         case "pack": {
             if (packAction !== undefined && !["export", "read", "grep"].includes(packAction))
@@ -1756,7 +1836,11 @@ async function dispatchKnodinTool(args) {
         case "context": {
             if (!task)
                 throw new Error("knodin context requires `task`");
-            return graphRead("context", () => buildKnodinContext(engine, task, repo, base, changedFiles));
+            if (parsedArgs.contextMode === "implementation")
+                return graphRead("context", () => findImplementationCandidates(engine, repo, { task, limit, offset }));
+            return graphRead("context", () => symbol
+                ? buildTaskInvestigation(engine, repo, { task, symbol, ...selector, limit, depth })
+                : buildKnodinContext(engine, task, repo, base, changedFiles));
         }
         case "search":
             if (!query)
@@ -1769,7 +1853,8 @@ async function dispatchKnodinTool(args) {
                 kinds,
                 path,
                 testScope,
-                includeSource,
+                includeSource: qualifiedCompactFallback ? false : includeSource,
+                structural: qualifiedCompactFallback ? true : undefined,
                 offset,
             }));
         case "textSearch": {
@@ -1824,7 +1909,7 @@ async function dispatchKnodinTool(args) {
             return bounded({
                 results: outputs.map((item) => ({
                     ...item,
-                    output: decorateGraphQueryResult(item.output, verifiedQueryHealth.state, verifiedQueryHealth.graph.freshness),
+                    output: decorateGraphQueryResult(item.output, verifiedQueryHealth.state, verifiedQueryHealth.graph.freshness, verifiedQueryHealth.graph.indexCoverage, queryHealth.graph.indexCoverage),
                 })),
             }, "query_batch");
         }
@@ -1862,12 +1947,100 @@ async function dispatchKnodinTool(args) {
                 : await inspectGatewayGraphHealth(repo);
             if (queryHealth && !queryHealth.available)
                 return bounded(queryHealth, `query:${pattern}`);
+            if (pattern === "class_consumers") {
+                if (limit !== undefined && limit > 1000)
+                    throw new Error("class_consumers limit must not exceed 1000 sites");
+                if (offset !== undefined ||
+                    kinds !== undefined ||
+                    relationKinds !== undefined ||
+                    direction !== undefined ||
+                    depth !== undefined ||
+                    includeTests !== undefined)
+                    throw new Error("class_consumers supports testScope/path filters and signed continuation, not offset/kinds/relations/direction/depth");
+                const secret = evidenceHandleSecret(repo).secret;
+                const cursor = parsedArgs.continuation
+                    ? readClassConsumerCursor(parsedArgs.continuation, secret)
+                    : undefined;
+                const request = {
+                    symbol: target ?? "",
+                    selector,
+                    testScope: testScope ?? "all",
+                    path,
+                    limit: limit ?? 100,
+                    ...(cursor
+                        ? {
+                            after: cursor.after,
+                            expectedQueryDigest: cursor.queryDigest,
+                            expectedSnapshotDigest: cursor.snapshotDigest,
+                        }
+                        : {}),
+                };
+                try {
+                    const page = await engine.queryClassConsumers(repo, request);
+                    // Defer maintenance, not the audit, until a later eligible status or close.
+                    const verified = await inspectGraphQueryHealth(repo, async (target) => attachLifecycleHealth(target, await engine.status(target, { audit: "cached", checkpoint: "defer" })));
+                    if (!verified.available)
+                        return bounded(verified, "query:class_consumers");
+                    // Revalidate facts revisions too: a health probe alone cannot detect every same-scope edit.
+                    await validateClassConsumerDelivery(page, request, (next) => engine.queryClassConsumers(repo, next));
+                    const sharedIndex = sharedIndexEnvelope();
+                    return observe(finalizeClassConsumerPage(page, {
+                        secret,
+                        budget,
+                        decorate: (candidate) => ({
+                            ...decorateGraphQueryResult(candidate, verified.state, undefined, verified.graph.indexCoverage, queryHealth?.available ? queryHealth.graph.indexCoverage : undefined),
+                            sharedIndex,
+                        }),
+                    }), "query:class_consumers");
+                }
+                catch (error) {
+                    if (error instanceof ClassConsumerQueryError &&
+                        [
+                            "CLASS_CONSUMER_TARGET_NOT_FOUND",
+                            "CLASS_CONSUMER_TARGET_AMBIGUOUS",
+                            "CLASS_CONSUMER_TARGET_CAPABILITY_MISSING",
+                        ].includes(error.code)) {
+                        const targetResolution = error.code === "CLASS_CONSUMER_TARGET_CAPABILITY_MISSING"
+                            ? "capability-missing"
+                            : error.code === "CLASS_CONSUMER_TARGET_NOT_FOUND"
+                                ? "not-found"
+                                : "ambiguous";
+                        const delivered = bounded({
+                            available: false,
+                            status: "unavailable",
+                            pattern,
+                            targetResolution,
+                            code: error.code,
+                            error: error.message,
+                            candidates: error.candidates,
+                            ...(queryHealth?.available
+                                ? {
+                                    indexCoverage: queryHealth.graph.indexCoverage,
+                                    freshness: queryHealth.graph.freshness,
+                                }
+                                : {}),
+                        }, "query:class_consumers");
+                        if (delivered.code !== error.code ||
+                            delivered.targetResolution !== targetResolution ||
+                            delivered.available !== false ||
+                            delivered.status !== "unavailable")
+                            throw new Error("Response budget cannot preserve the class-consumer error contract; increase the budget.");
+                        return delivered;
+                    }
+                    throw error;
+                }
+            }
             if (pattern === "rename_preview") {
                 // rename_preview routes through the rename engine: dry-run (preview +
                 // unified diff) by default, writing to disk only when `apply` is true.
                 return engine
                     .rename(symbol ?? "", to ?? "", repo, apply === true, true, selector)
-                    .then((result) => bounded(decorateGraphQueryResult(result, queryHealth?.available ? queryHealth.state : "healthy", queryHealth?.available ? queryHealth.graph.freshness : undefined), "query:rename_preview"));
+                    .then(async (result) => {
+                    const verified = await inspectGatewayGraphHealth(repo);
+                    if (!verified.available)
+                        return bounded(verified, "query:rename_preview");
+                    return bounded(decorateGraphQueryResult(result, verified.state, verified.graph.freshness, verified.graph.indexCoverage, queryHealth?.available ? queryHealth.graph.indexCoverage : undefined), "query:rename_preview");
+                });
             }
             const queryResult = await engine.query(pattern, target ?? "", repo, to, Math.min(limit ?? itemBudget ?? 100, itemBudget ?? 1000), depth, detailLevel === "source" ? undefined : detailLevel, selector, pattern === "impact"
                 ? {
@@ -1908,9 +2081,19 @@ async function dispatchKnodinTool(args) {
                 // A verified probe supersedes the unverified one for both fields, so
                 // state and freshness always come from the same observation.
                 const authoritative = verifiedQueryHealth?.available ? verifiedQueryHealth : queryHealth;
-                decorated = decorateGraphQueryResult(result, authoritative.state, authoritative.graph.freshness);
+                decorated = decorateGraphQueryResult(result, authoritative.state, authoritative.graph.freshness, authoritative.graph.indexCoverage, queryHealth.graph.indexCoverage);
+            }
+            const delivered = bounded(decorated, `query:${pattern}`);
+            if (pattern === "inheritors_of") {
+                const qualification = decorated
+                    .inheritanceQuery;
+                const retained = delivered
+                    .inheritanceQuery;
+                if (qualification &&
+                    ["version", "mode", "partial", "truncated", "apex"].some((key) => retained?.[key] !== qualification[key]))
+                    throw new Error("Response budget cannot preserve the inheritance qualification; increase the budget.");
             }
-            return bounded(decorated, `query:${pattern}`);
+            return delivered;
         }
         default:
             throw new Error(`unknown knodin operation: ${String(operation)}`);

package/docs/CLI.md

@@ -66,6 +66,35 @@ example repository existence, mutually exclusive configuration modes, and
 graph-query target rules), but syntax cannot reach a handler unless the shared
 declarative model accepts it first.
 
+## Task discovery and investigation
+
+`context` supports explicit implementation discovery and selected-symbol
+investigation in addition to ordinary repository orientation:
+
+```bash
+knodin context "find code that persists an order" --implementations --limit 10 --json
+knodin context "rename persist" --symbol persist --file src/storage.ts --json
+knodin context "rename persist" --symbol persist --identity '<returned-identity>' --limit 20 --depth 3 --json
+```
+
+`--implementations` ranks functions, methods, constructors, and classes and
+returns identity/file-specific followups. It chooses no target and intentionally
+excludes types, interfaces, and constants; use ordinary `search` to find those.
+Use `--offset` and `--limit` to page through candidates. Incomplete semantic
+coverage remains visible even when an exact-name candidate can be returned.
+
+`--symbol` composes definition/source, rename sites, callers, upstream impact,
+tests, and file importers. A duplicated name requires `--file` or `--identity`;
+an unknown target is reported separately from a symbol with no callers. Bounded
+or unavailable sections include followups and unresolved work. This is static
+evidence to inspect, not a complete edit plan or proof of test coverage.
+`--implementations` and `--symbol` are mutually exclusive.
+
+The single MCP gateway uses `operation: "context"`, `task`, and
+`contextMode: "implementation"` for discovery. For investigation, supply
+`symbol` with optional `file` or `identity` and omit implementation mode. Both
+surfaces return compatible identity/file-specific followups.
+
 Optional Claude lifecycle integration is explicit and user-global:
 
 ```bash
@@ -128,6 +157,13 @@ exact local source and stable continuations. A returned evidence handle plus
 current-file match; all other baseline states return the required source. See
 `docs/PROGRESSIVE-EVIDENCE.md` for the protocol and limitations.
 
+Use `knodin evidence evidence --files src/widget.ts,src/caller.ts --items 20
+--json` for a multi-file bundle, or `expand` to include indexed direct file
+dependencies. A signed `--continuation` recovers remaining source; completed
+per-file receipts can later be passed through `--already-present` to reuse
+unchanged content. Manifest entries have a null receipt until complete delivery,
+and the manifest itself counts toward the byte/token budget.
+
 `knodin review` returns separately itemized graph impact, test gaps, structural
 centrality, churn, co-change, and coupling evidence. Git history has explicit
 commit/file/time bounds and truthful unavailable or truncation states; see
@@ -157,3 +193,59 @@ not Node's backtracking regular-expression engine. Backreferences and lookaround
 are rejected because they cannot retain RE2's linear-time guarantee. Route
 matching treats application path text literally and recognizes only complete
 Express/NestJS-style `:name` or `{name}` path segments as parameters.
+
+### Local flow-analysis budgets
+
+`knodin query flow_analysis <symbol> --bytes 1536 --tokens 384 --json`
+requires an effective budget of at least 1536 serialized bytes (384 estimated
+tokens). The effective ceiling is the stricter of `--bytes` and `--tokens × 4`;
+a smaller ceiling is rejected, never automatically enlarged. Required evidence
+and qualifications may still require more than this minimum.
+
+Flow budget metadata and drill-down continuation guidance use operation
+`query:flow_analysis`, consistently with MCP. This guidance is not a resumable
+cursor: repeat the query with a narrower selector or an explicitly larger budget.
+Other commands retain their existing operation names and budget policies.
+
+### Typed Apex class consumers
+
+`knodin query inheritors_of Base --json` aggregates same-name nominal inheritance
+across languages; it does not select one global target. `inheritanceQuery` preserves
+the query mode, partial/truncation flags, and Apex resolution status. Apex rows
+require independently verified typed endpoints; an ambiguous or missing Apex
+capability can leave qualified non-Apex results. Apex `--file` or `--identity`
+selectors establish a selected typed target; non-Apex inheritance retains its
+legacy name matching rather than promising exact identity resolution. Budgets
+that cannot preserve this qualification fail closed.
+The tuple describes engine analysis; `responseBudget.truncated` separately reports
+wire-size trimming. Read both before interpreting a bounded result as complete.
+
+`knodin query class_consumers GlobalWrappers --test-scope all --limit 100 --json`
+returns direct typed source sites for an Apex class or interface, separately from method `callers_of` and Java
+configuration `consumers_of`. `count` is total observed matching sites,
+`consumerFileCount` is distinct files, and `returnedCount` is this page's sites.
+`files` contains aggregates only for files represented on this page.
+`targetKind` identifies the resolved declaration as `class` or `interface` and is
+preserved on every page. Interface consumers cover supported type-position roles,
+not constructors, static-field reads, `implements` relationships, or inferred
+runtime dispatch. Query implementation relationships separately.
+
+Use `--test-scope test|production|all` (default `all`), a canonical repository-relative
+`--path` prefix, and stable `--identity`/`--file` target selectors when needed.
+`--limit` accepts 1–1000 sites; `--bytes`, `--tokens`, and `--items` bound the complete
+response. Repeat the same target and filters with `--continuation '<returned token>'`;
+page budgets may change. Tokens authenticate the last delivered site and the graph,
+coverage, and typed-facts snapshot. Forged, mismatched, or stale tokens fail closed.
+A minimum complete site plus qualifications must fit; source fields are never shortened.
+
+Sites retain exact spelling, role, source-owner identity when known, and exclusive
+end positions: one-based lines/UTF-16 columns and zero-based UTF-8 byte offsets.
+The target's own file is excluded. Nine supported syntax roles do not cover every
+Apex use, metadata relationship, or runtime path. Read `classConsumerAnalysis` and
+`indexCoverage` before interpreting a negative; missing/invalid descriptors and
+unresolved uses remain qualified, not proof that a class is unused.
+An indexed retained interface declaration without a safely matching interface
+symbol returns `CLASS_CONSUMER_TARGET_CAPABILITY_MISSING`, `targetResolution: capability-missing`,
+and a nonzero exit—not a successful zero or a fabricated identity. Follow the
+reported repair guidance within the declared index scope. An unknown name remains
+`not-found`; this qualification does not certify interfaces outside indexed coverage.