knodin 0.12.2 → 0.13.1

package/dist/src/evidence-graph.js

@@ -0,0 +1,163 @@
+import { createHash } from "node:crypto";
+import { compareBytes } from "./compare.js";
+import { readEvidenceUtf8, } from "./evidence-bundle.js";
+import { isFileRelationship } from "./file-dependency.js";
+import { inspectGraphQueryHealth } from "./graph-query-health.js";
+import { indexCoverageCore, indexCoverageNotice, indexCoverageSnapshot, } from "./index-coverage-read.js";
+import { normalizeEvidenceFile } from "./progressive-evidence.js";
+const MAX_EXPANSION_DEPTH = 3;
+/** File dependencies from the graph, never inferred from same-name text matches. */
+export function createEvidenceGraphAdapter(engine) {
+    return {
+        async relatedFiles(repo, files) {
+            const health = await inspectGraphQueryHealth(repo, (root) => engine.status(root));
+            if (!health.available)
+                return {
+                    files: [],
+                    freshness: "unknown",
+                    omissions: [`Graph unavailable: ${health.state}.`],
+                    indexCoverage: indexCoverageCore(health.graph?.indexCoverage),
+                    coverageNotice: indexCoverageNotice(health.graph?.indexCoverage),
+                };
+            // Establish the query freshness lease, including supported incremental reconciliation.
+            await engine.query("file_summary", files[0] ?? "", repo, undefined, 1);
+            const status = await engine.status(repo);
+            const coverageAtRead = indexCoverageSnapshot(status.indexCoverage);
+            if (status.status !== "healthy" || status.freshness?.state !== "fresh")
+                return {
+                    files: [],
+                    freshness: "unknown",
+                    indexCoverage: indexCoverageCore(status.indexCoverage),
+                    coverageNotice: indexCoverageNotice(status.indexCoverage),
+                    omissions: [
+                        `Graph status is ${status.status}, freshness ${status.freshness?.state ?? "unknown"}; related files were not expanded.`,
+                    ],
+                };
+            const related = [];
+            const omissions = [];
+            const coverageNotice = indexCoverageNotice(status.indexCoverage);
+            if (coverageNotice)
+                omissions.push(coverageNotice);
+            let fresh = true;
+            // Breadth-first discovery stays bounded independently of response paging.
+            // Include seeds in the cap so bundle delivery never receives >32 files.
+            const seeds = [
+                ...new Set(files.map((file) => normalizeEvidenceFile(repo, file).relative)),
+            ].sort(compareBytes);
+            if (seeds.length > 32)
+                throw new RangeError("evidence expansion requires at most 32 seeds");
+            const selected = new Set(seeds);
+            const sourceHashes = Object.create(null);
+            let sourceBytes = 0;
+            const pinSource = (file) => {
+                if (sourceHashes[file] !== undefined)
+                    return;
+                const { source, bytes } = readEvidenceUtf8(normalizeEvidenceFile(repo, file).absolute);
+                sourceBytes += bytes;
+                if (sourceBytes > 8 * 1024 * 1024)
+                    throw new RangeError("evidence bundle source exceeds 8 MiB; narrow the selection");
+                sourceHashes[file] = createHash("sha256").update(source).digest("hex");
+            };
+            for (const file of seeds)
+                pinSource(file);
+            const queue = seeds.map((file) => ({ file, depth: 0 }));
+            let depthBound = false;
+            let fileBound = false;
+            for (const { file, depth } of queue) {
+                if (depth >= MAX_EXPANSION_DEPTH) {
+                    depthBound = true;
+                    continue;
+                }
+                for (const pattern of ["imports_of", "importers_of"]) {
+                    const result = await engine.query(pattern, file, repo, undefined, 32);
+                    // Missing operation coverage is supported for older adapters, but an
+                    // explicit mismatch invalidates the lease even after an ABA transition.
+                    if (result.indexCoverage !== undefined &&
+                        indexCoverageSnapshot(result.indexCoverage) !== coverageAtRead)
+                        fresh = false;
+                    if (result.staleness !== "fresh" || result.available === false)
+                        fresh = false;
+                    if (result.hasMore || result.count > result.results.length)
+                        omissions.push(`${pattern} ${file}: only ${result.results.length} of ${result.count} relationships returned.`);
+                    for (const row of [...result.results].sort((a, b) => compareBytes(a.file ?? "", b.file ?? "") || compareBytes(a.kind ?? "", b.kind ?? ""))) {
+                        if (!row.file)
+                            continue;
+                        if (!isFileRelationship(row.kind, row.file, pattern === "importers_of")) {
+                            omissions.push(`${pattern} ${file}: non-file relationship omitted (${row.kind ?? "unknown"}).`);
+                            continue;
+                        }
+                        let normalized;
+                        try {
+                            normalized = normalizeEvidenceFile(repo, row.file).relative;
+                        }
+                        catch {
+                            omissions.push(`${pattern} ${file}: non-file, missing or ineligible dependency omitted (${row.kind ?? "dependency"}).`);
+                            continue;
+                        }
+                        if (!selected.has(normalized)) {
+                            if (selected.size >= 32) {
+                                fileBound = true;
+                                continue;
+                            }
+                            selected.add(normalized);
+                            pinSource(normalized);
+                            queue.push({ file: normalized, depth: depth + 1 });
+                        }
+                        related.push({
+                            file: normalized,
+                            identity: row.identity,
+                            relation: `${pattern}:${file}:${row.kind ?? "dependency"}`,
+                            confidence: "heuristic",
+                            // Dependency queries do not define row.line as a declaration location.
+                            // In particular, an incoming edge is declared in the importer, not `file`.
+                        });
+                    }
+                }
+            }
+            if (depthBound)
+                omissions.push(`Expansion stopped at ${MAX_EXPANSION_DEPTH} dependency hops; the remaining frontier was not inspected.`);
+            if (fileBound)
+                omissions.push("Expansion limited to 32 files including seeds; additional related files were omitted.");
+            const after = await engine.status(repo);
+            // Probe timestamps are observational; compare source generation and fingerprints only.
+            const generationChanged = coverageAtRead !== indexCoverageSnapshot(after.indexCoverage) ||
+                status.indexGeneration !== after.indexGeneration ||
+                status.freshness?.currentHead !== after.freshness?.currentHead ||
+                status.freshness?.indexedHead !== after.freshness?.indexedHead ||
+                status.freshness?.workingTree?.indexedFingerprint !==
+                    after.freshness?.workingTree?.indexedFingerprint;
+            if (generationChanged || after.status !== "healthy" || after.freshness?.state !== "fresh")
+                fresh = false;
+            if (!fresh)
+                omissions.push("Graph changed or became stale during evidence expansion; relationships were withheld.");
+            const validate = async () => {
+                const current = await engine.status(repo);
+                if (!fresh ||
+                    current.status !== "healthy" ||
+                    current.freshness?.state !== "fresh" ||
+                    coverageAtRead !== indexCoverageSnapshot(current.indexCoverage) ||
+                    status.indexGeneration !== current.indexGeneration ||
+                    status.freshness?.currentHead !== current.freshness?.currentHead ||
+                    status.freshness?.indexedHead !== current.freshness?.indexedHead ||
+                    status.freshness?.workingTree?.indexedFingerprint !==
+                        current.freshness?.workingTree?.indexedFingerprint)
+                    throw new Error("Graph changed during evidence delivery; restart the bundle");
+            };
+            // Validate the raw source pins as well as observational graph metadata.
+            // These are selected-file snapshots, not a claim that every indexed byte was checked.
+            for (const [file, expected] of Object.entries(sourceHashes)) {
+                const actual = readEvidenceUtf8(normalizeEvidenceFile(repo, file).absolute).source;
+                if (createHash("sha256").update(actual).digest("hex") !== expected)
+                    throw new Error("Source changed during evidence expansion; restart the bundle");
+            }
+            return {
+                files: fresh ? related : [],
+                freshness: fresh ? "fresh" : "stale",
+                omissions,
+                indexCoverage: indexCoverageCore(after.indexCoverage),
+                coverageNotice: indexCoverageNotice(after.indexCoverage),
+                ...(fresh ? { sourceHashes, validate } : {}),
+            };
+        },
+    };
+}

package/dist/src/failure-diagnosis.js

@@ -2,6 +2,7 @@ import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { gitExecutable } from "./git-executable.js";
+import { indexCoverageCore, indexCoverageNotice, indexCoverageSnapshot, } from "./index-coverage-read.js";
 import { compressOutput, readOutputArtifact } from "./output-compression.js";
 const CODE_EXTENSIONS = [
     ".tsx",
@@ -552,6 +553,15 @@ function confidenceLevel(diagnosticCount, status) {
         return "refused";
     return status === "resolved" ? "exact" : "qualified";
 }
+function diagnosisSnapshot(health) {
+    return JSON.stringify([
+        health.indexGeneration,
+        health.freshness.currentHead,
+        health.freshness.indexedHead,
+        health.freshness.workingTree.indexedFingerprint,
+        indexCoverageSnapshot(health.indexCoverage),
+    ]);
+}
 export async function diagnoseFailure(graph, repo, request) {
     const maxDiagnostics = integer("maxDiagnostics", request.maxDiagnostics, DEFAULT_DIAGNOSTICS, 1, MAX_DIAGNOSTICS);
     const diagnosticOffset = integer("diagnosticOffset", request.diagnosticOffset, 0, 0, 1_000_000);
@@ -560,6 +570,38 @@ export async function diagnoseFailure(graph, repo, request) {
     const relationLimit = integer("relationLimit", request.relationLimit, DEFAULT_RELATIONS, 1, MAX_RELATIONS);
     const recentCommitLimit = integer("recentCommitLimit", request.recentCommitLimit, 3, 0, 10);
     const input = diagnosisSource(repo, request);
+    // A cold read can legitimately reconcile. Establish it before capturing the
+    // lease, then keep every diagnostic and relation within that same observation.
+    await graph.query("file_summary", "", repo, undefined, 1);
+    const before = await graph.status(repo, { audit: "cached" });
+    const beforeSnapshot = diagnosisSnapshot(before);
+    const coverageAtRead = indexCoverageSnapshot(before.indexCoverage);
+    let observationChanged = false;
+    let staleObservation = false;
+    let missingQueryCoverage = false;
+    const observedGraph = {
+        status: (...args) => graph.status(...args),
+        query: async (...args) => {
+            const result = await graph.query(...args);
+            // Explicit observations catch changed-and-restored scope as well as
+            // final drift. Legacy adapters may omit this field; never invent it.
+            missingQueryCoverage ||= result.indexCoverage === undefined;
+            if (result.indexCoverage !== undefined)
+                observationChanged ||= indexCoverageSnapshot(result.indexCoverage) !== coverageAtRead;
+            staleObservation ||= !["fresh", "reconciled"].includes(result.staleness ?? "unknown");
+            return result;
+        },
+        search: async (...args) => {
+            missingQueryCoverage = true; // SearchPage does not expose a scope observation.
+            const start = await graph.status(repo, { audit: "cached" });
+            const result = await graph.search(...args);
+            const end = await graph.status(repo, { audit: "cached" });
+            observationChanged ||=
+                diagnosisSnapshot(start) !== beforeSnapshot || diagnosisSnapshot(end) !== beforeSnapshot;
+            staleObservation ||= result.results.some((row) => row.staleness !== undefined && !["fresh", "reconciled"].includes(row.staleness));
+            return result;
+        },
+    };
     const detectedReferences = extractDiagnosticReferences(input.content, Number.MAX_SAFE_INTEGER);
     const references = detectedReferences.slice(diagnosticOffset, diagnosticOffset + maxDiagnostics);
     const omittedDiagnostics = Math.max(0, detectedReferences.length - diagnosticOffset - references.length);
@@ -571,7 +613,7 @@ export async function diagnoseFailure(graph, repo, request) {
     let omittedRelations = 0;
     let omittedContextBytes = 0;
     for (const reference of references) {
-        const resolved = await resolveReferencePath(graph, repo, reference);
+        const resolved = await resolveReferencePath(observedGraph, repo, reference);
         if (!resolved.file) {
             unresolved.push({
                 reference,
@@ -580,7 +622,7 @@ export async function diagnoseFailure(graph, repo, request) {
             });
             continue;
         }
-        const resolvedDiagnosis = await diagnoseResolvedReference(graph, repo, reference, resolved.file, {
+        const resolvedDiagnosis = await diagnoseResolvedReference(observedGraph, repo, reference, resolved.file, {
             relationLimit,
             recentCommitLimit,
             contextLines,
@@ -596,7 +638,21 @@ export async function diagnoseFailure(graph, repo, request) {
         diagnostics.push(resolvedDiagnosis.diagnostic);
     }
     const health = await graph.status(repo, { audit: "cached" });
-    const status = diagnosisStatus(diagnostics.length, unresolved.length + omittedDiagnostics, input.complete, contextTruncated, health.freshness.state);
+    const changed = observationChanged || beforeSnapshot !== diagnosisSnapshot(health);
+    if (changed) {
+        // Do not leave either graph-derived negatives or source snippets beside
+        // a refusal: consumers can otherwise mistake them for a coherent result.
+        diagnostics.length = 0;
+        unresolved.length = 0;
+        snippets.length = 0;
+        contextBytes = 0;
+        contextTruncated = false;
+        omittedRelations = 0;
+        omittedContextBytes = 0;
+    }
+    let status = diagnosisStatus(diagnostics.length, unresolved.length + omittedDiagnostics, input.complete, contextTruncated, health.freshness.state);
+    if (staleObservation && status === "resolved")
+        status = "partial";
     const omissionReasons = [];
     if (omittedDiagnostics > 0)
         omissionReasons.push("diagnostic-item-budget");
@@ -607,6 +663,8 @@ export async function diagnoseFailure(graph, repo, request) {
     if (!input.complete)
         omissionReasons.push("input-byte-budget");
     const confidenceReasons = [
+        ...(changed ? ["changed-during-diagnosis"] : []),
+        ...(staleObservation ? ["stale-query-evidence"] : []),
         ...(diagnostics.length === 0 ? ["no-safe-source-reference"] : []),
         ...(unresolved.length > 0 ? ["unresolved-source-reference"] : []),
         ...omissionReasons,
@@ -615,6 +673,11 @@ export async function diagnoseFailure(graph, repo, request) {
     const returnedRelations = diagnostics.reduce((total, diagnostic) => total + diagnostic.tests.length + diagnostic.upstream.length + diagnostic.downstream.length, 0);
     return {
         schemaVersion: 1,
+        ...(changed ? { available: false, state: "changed-during-diagnosis" } : {}),
+        ...(before.indexCoverage ? { indexCoverage: indexCoverageCore(before.indexCoverage) } : {}),
+        ...(indexCoverageNotice(before.indexCoverage)
+            ? { coverageNotice: indexCoverageNotice(before.indexCoverage) }
+            : {}),
         status,
         input: {
             kind: input.kind,
@@ -640,7 +703,7 @@ export async function diagnoseFailure(graph, repo, request) {
             relations: omittedRelations,
             contextBytes: omittedContextBytes,
             reasons: omissionReasons,
-            continuation: omittedDiagnostics > 0 && input.artifactId
+            continuation: !changed && omittedDiagnostics > 0 && input.artifactId
                 ? { artifactId: input.artifactId, nextDiagnostic: diagnosticOffset + references.length }
                 : null,
         },
@@ -656,6 +719,18 @@ export async function diagnoseFailure(graph, repo, request) {
             },
             returned: { diagnostics: diagnostics.length, relations: returnedRelations, contextBytes },
         },
-        limitations: diagnosisLimitations(input.complete, references.length, contextTruncated, health.freshness.state),
+        limitations: [
+            ...diagnosisLimitations(input.complete, references.length, contextTruncated, health.freshness.state),
+            ...(changed
+                ? [
+                    "Graph generation or index coverage changed during diagnosis; mixed evidence was withheld. Retry against the current source and scope.",
+                ]
+                : []),
+            ...(missingQueryCoverage
+                ? [
+                    "Some adapter queries omit per-operation coverage; surrounding status observations cannot detect a scope change that is restored entirely within such a query.",
+                ]
+                : []),
+        ],
     };
 }

package/dist/src/file-dependency.js

@@ -0,0 +1,35 @@
+// Dependency rows also contain resource names and bundle directories. Only
+// positively identified file relationships may select source for disclosure.
+export function isFileRelationship(kind, file, incoming) {
+    if (kind === "import" || kind === "lsif_import" || kind === "scip_import")
+        return true;
+    if (kind === "flow_apex_action")
+        return incoming ? file.endsWith(".flow-meta.xml") : file.endsWith(".cls");
+    if (kind === "flow_screen_component")
+        return incoming ? file.endsWith(".flow-meta.xml") : /\.(?:cmp|js)$/.test(file);
+    if (kind === "aura_resource_component")
+        return incoming ? file.endsWith(".app") : /\.(?:cmp|js)$/.test(file);
+    if (kind === "visualforce_lightning_out")
+        return incoming ? file.endsWith(".page") : file.endsWith(".app");
+    if (kind === "weblink_visualforce_page")
+        return incoming ? file.endsWith(".webLink-meta.xml") : file.endsWith(".page");
+    if (kind === "quickaction_lightning_component")
+        return incoming ? file.endsWith(".quickAction-meta.xml") : file.endsWith(".cmp");
+    if (kind === "appbuilder_apex_datasource")
+        return incoming ? /(?:\.js-meta\.xml|\.design)$/.test(file) : file.endsWith(".cls");
+    if (kind === "aura_component")
+        return incoming ? /\.(?:cmp|app)$/.test(file) : file.endsWith(".cmp");
+    if (kind === "lwc_template_component")
+        return incoming ? file.endsWith(".html") : file.endsWith(".js");
+    if (kind === "flexipage_component")
+        return incoming ? file.endsWith(".flexipage-meta.xml") : /\.(?:cmp|js)$/.test(file);
+    if (kind === "flexipage_template")
+        return incoming ? file.endsWith(".flexipage-meta.xml") : file.endsWith(".cmp");
+    if (kind === "aura_lwc_component" && incoming && file.endsWith(".app"))
+        return true;
+    if (kind === "apex_method" || kind === "aura_apex_controller" || kind === "controller")
+        return incoming ? /\.(?:js|ts|cmp|page|component)$/.test(file) : file.endsWith(".cls");
+    if (kind === "lwc_component" || kind === "aura_lwc_component")
+        return /\.(?:js|ts|html|cmp)$/.test(file);
+    return false;
+}

package/dist/src/graph-query-health.js

@@ -1,3 +1,4 @@
+import { indexCoverageCore, indexCoverageNotice, indexCoverageSnapshot, } from "./index-coverage-read.js";
 function hasNonReconciliableDamage(graph) {
     if (Object.values(graph.orphaned).some((count) => count > 0))
         return true;
@@ -17,6 +18,14 @@ function unavailableState(graph) {
         return "indexing";
     if (graph.status === "indexing")
         return "indexing";
+    if (graph.indexCoverage?.origin === "invalid")
+        return "repair-needed";
+    if (graph.coverage.sourceFiles === 0 &&
+        graph.indexCoverage &&
+        (graph.indexCoverage.intentState !== "complete" || graph.indexCoverage.mode === "unknown"))
+        return "unknown";
+    if (graph.coverage.sourceFiles === 0 && graph.indexCoverage?.mode === "scoped")
+        return "empty-scope";
     if (graph.schemaVersion === 0)
         return graph.coverage.sourceFiles === 0 ? "empty-repository" : "not-initialized";
     if (graph.coverage.sourceFiles === 0)
@@ -44,6 +53,7 @@ export async function inspectGraphQueryHealth(repo, status) {
             status: "unavailable",
             state,
             graph,
+            ...(graph.indexCoverage ? { indexCoverage: graph.indexCoverage } : {}),
             remediation: graph.repairSteps,
         };
     }
@@ -72,9 +82,40 @@ function hasNoMatches(value) {
     return false;
 }
 /** Add an explicit healthy/no-match outcome without replacing operation data. */
-export function decorateGraphQueryResult(value, graphState = "healthy", freshness) {
+export function decorateGraphQueryResult(value, graphState = "healthy", freshness, ...coverageObservations) {
+    const [indexCoverage, initialCoverage] = coverageObservations;
+    const ownCoverage = value && typeof value === "object" && !Array.isArray(value)
+        ? value.indexCoverage
+        : undefined;
+    const readCoverage = ownCoverage ?? initialCoverage;
+    // Omitted observations on legacy callers are not the same as an explicit
+    // post-read observation that lost coverage metadata. A result's own scope
+    // belongs to its read lease and supersedes an older preflight observation.
+    if (coverageObservations.length >= 1 &&
+        (ownCoverage !== undefined || coverageObservations.length >= 2) &&
+        indexCoverageSnapshot(readCoverage) !== indexCoverageSnapshot(indexCoverage))
+        return {
+            available: false,
+            status: "unavailable",
+            state: "changed-during-read",
+            indexCoverage,
+            indexCoverageAtRead: indexCoverageCore(readCoverage),
+            remediation: [
+                "Index coverage changed during the read; results were withheld. Retry against the current coverage.",
+            ],
+        };
+    const selectedCoverage = ownCoverage ?? indexCoverage;
+    const coverageFields = selectedCoverage
+        ? {
+            indexCoverage: selectedCoverage,
+            ...(indexCoverageNotice(selectedCoverage)
+                ? { coverageNotice: indexCoverageNotice(selectedCoverage) }
+                : {}),
+        }
+        : {};
     if (value === null || value === undefined) {
         return {
+            ...coverageFields,
             status: "no-match",
             result: value ?? null,
             ...(freshness ? { freshness } : {}),
@@ -83,6 +124,7 @@ export function decorateGraphQueryResult(value, graphState = "healthy", freshnes
     }
     if (Array.isArray(value)) {
         return {
+            ...coverageFields,
             status: value.length === 0 ? "no-match" : "ok",
             results: value,
             ...(freshness ? { freshness } : {}),
@@ -95,12 +137,15 @@ export function decorateGraphQueryResult(value, graphState = "healthy", freshnes
     }
     if (typeof value !== "object") {
         return {
+            ...coverageFields,
             result: value,
             ...(freshness ? { freshness } : {}),
             availability: { state: graphState, outcome: "complete" },
         };
     }
     const root = value;
+    if (root.available === false || root.status === "unavailable")
+        return { ...root, ...coverageFields };
     // An unresolved target is not a no-match: nothing was searched for. Calling
     // it `no-match` is what let a misspelled symbol read as proof that nothing
     // calls it (KNODIN-28). Ambiguity is exempted for the same reason.
@@ -109,6 +154,7 @@ export function decorateGraphQueryResult(value, graphState = "healthy", freshnes
     const state = notFound ? "target-not-found" : noMatch ? "no-match" : graphState;
     return {
         ...root,
+        ...coverageFields,
         ...(freshness ? { freshness } : {}),
         ...(notFound && root.status === undefined ? { status: "target-not-found" } : {}),
         ...(noMatch && root.status === undefined ? { status: "no-match" } : {}),

package/dist/src/implementation-search.js

@@ -0,0 +1,69 @@
+/** An explicit discovery lens, never the default for general symbol search. */
+export const IMPLEMENTATION_KINDS = ["function", "method", "class", "constructor"];
+/** Rank possible implementations without choosing one or turning relevance into proof. */
+export async function findImplementationCandidates(engine, repo, request) {
+    const task = request.task.trim();
+    if (!task)
+        throw new Error("Implementation discovery requires a task");
+    const limit = request.limit ?? 10;
+    const offset = request.offset ?? 0;
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 50)
+        throw new Error("Implementation discovery limit must be an integer from 1 to 50");
+    if (!Number.isSafeInteger(offset) || offset < 0)
+        throw new Error("Implementation discovery offset must be a nonnegative integer");
+    const page = await engine.search(task, repo, limit, {
+        kinds: [...IMPLEMENTATION_KINDS],
+        federate: false,
+        includeSource: false,
+        offset,
+    });
+    const unresolved = [];
+    if (page.semanticReadiness !== "ready")
+        unresolved.push(`Semantic evidence is ${page.semanticReadiness}; implementations may be missing.`);
+    if (page.results.some((row) => row.staleness !== "fresh" && row.staleness !== "reconciled"))
+        unresolved.push("Some candidate evidence is stale or has unknown freshness.");
+    return {
+        mode: "implementation-discovery",
+        repoPath: repo,
+        task,
+        status: unresolved.length ? "partial" : page.results.length ? "candidates" : "no-candidates",
+        candidates: page.results.map((row) => ({
+            identity: row.identity,
+            symbol: row.symbol,
+            file: row.filePath,
+            kind: row.kind,
+            rankScore: row.rrfScore,
+            staleness: row.staleness,
+            followup: {
+                operation: "context",
+                repoPath: repo,
+                task,
+                symbol: row.symbol,
+                identity: row.identity,
+                file: row.filePath,
+            },
+        })),
+        offset: page.offset,
+        limit: page.limit,
+        hasMore: page.hasMore,
+        continuation: page.hasMore
+            ? {
+                operation: "context",
+                contextMode: "implementation",
+                repoPath: repo,
+                task,
+                offset: page.offset + page.results.length,
+                limit,
+            }
+            : null,
+        retrieval: page.retrieval,
+        semanticReadiness: page.semanticReadiness,
+        unresolved,
+        bounds: {
+            includedKinds: [...IMPLEMENTATION_KINDS],
+            localRepositoryOnly: true,
+            automaticSelection: false,
+            note: "Ranked candidates require inspection. Types, interfaces, constants and other kinds are intentionally excluded; use ordinary search to find them. No completeness or implementation-correctness claim.",
+        },
+    };
+}

package/dist/src/index-coverage-read.js

@@ -0,0 +1,33 @@
+/** Bounded, semantic coverage state. Previews are presentation, not snapshot identity. */
+export function indexCoverageCore(coverage) {
+    if (!coverage)
+        return undefined;
+    const { version, mode, revision, digest, origin, prefixCount, fileCount, intentState, repositoryComplete, negativeScope, } = coverage;
+    return {
+        version,
+        mode,
+        revision,
+        digest,
+        origin,
+        prefixCount,
+        fileCount,
+        intentState,
+        repositoryComplete,
+        negativeScope,
+    };
+}
+export function indexCoverageSnapshot(coverage) {
+    return JSON.stringify(indexCoverageCore(coverage) ?? null);
+}
+/** Inventory coverage cannot certify complete static relationships or runtime nonuse. */
+export function indexCoverageNotice(coverage) {
+    if (!coverage)
+        return undefined;
+    if (coverage.intentState !== "complete" || coverage.negativeScope === "unknown")
+        return "Index coverage completeness is unverified, including within any declared scope; a negative graph answer does not establish absence.";
+    if (coverage.mode === "scoped")
+        return "Indexed graph evidence is limited to the declared index scope; repository-wide completeness is not established. This does not describe separate source, language-server or federated coverage.";
+    if (coverage.mode === "unknown" || !coverage.repositoryComplete)
+        return "Index coverage completeness is unverified; a negative answer does not establish repository-wide absence.";
+    return undefined;
+}