knodin 0.12.2 → 0.13.0

package/dist/src/evidence-bundle.js

@@ -0,0 +1,283 @@
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+import fs from "node:fs";
+import { compareBytes } from "./compare.js";
+import { indexCoverageCore } from "./index-coverage-read.js";
+import { evidenceHandleSecret, normalizeEvidenceFile } from "./progressive-evidence.js";
+const hash = (value) => createHash("sha256").update(value).digest("hex");
+const MAX_FILES = 32;
+const MAX_SOURCE_BYTES = 8 * 1024 * 1024;
+/** This text protocol must not certify replacement characters for malformed disk bytes. */
+export function readEvidenceUtf8(absolute) {
+    if (fs.statSync(absolute).size > MAX_SOURCE_BYTES)
+        throw new RangeError("evidence bundle source exceeds 8 MiB; narrow the selection");
+    const raw = fs.readFileSync(absolute);
+    if (raw.length > MAX_SOURCE_BYTES)
+        throw new RangeError("evidence bundle source exceeds 8 MiB; narrow the selection");
+    const source = raw.toString("utf8");
+    if (!Buffer.from(source, "utf8").equals(raw))
+        throw new Error("evidence bundle requires valid UTF-8 source");
+    return { source, bytes: raw.length };
+}
+function sign(value, secret) {
+    const body = Buffer.from(JSON.stringify(value)).toString("base64url");
+    return `peb1.${body}.${createHmac("sha256", secret).update(body).digest("hex")}`;
+}
+function verify(value, secret) {
+    if (typeof value !== "string" || value.length > 4096)
+        throw new Error("invalid evidence bundle handle");
+    const [prefix, body, signature, extra] = value.split(".");
+    if (prefix !== "peb1" || !body || !signature || extra !== undefined)
+        throw new Error("invalid evidence bundle handle");
+    const expected = Buffer.from(createHmac("sha256", secret).update(body).digest("hex"));
+    const actual = Buffer.from(signature);
+    if (actual.length !== expected.length || !timingSafeEqual(actual, expected))
+        throw new Error("invalid evidence bundle handle");
+    let parsed;
+    try {
+        parsed = JSON.parse(Buffer.from(body, "base64url").toString("utf8"));
+    }
+    catch {
+        throw new Error("invalid evidence bundle handle");
+    }
+    if (!parsed || typeof parsed !== "object")
+        throw new Error("invalid evidence bundle handle");
+    if (parsed.type === "file-complete" &&
+        typeof parsed.file === "string" &&
+        /^[a-f0-9]{64}$/.test(parsed.hash) &&
+        Number.isSafeInteger(parsed.bytes) &&
+        parsed.bytes >= 0)
+        return parsed;
+    if (parsed.type === "cursor" &&
+        /^[a-f0-9]{64}$/.test(parsed.digest) &&
+        Number.isSafeInteger(parsed.fileIndex) &&
+        parsed.fileIndex >= 0 &&
+        Number.isSafeInteger(parsed.lineIndex) &&
+        parsed.lineIndex >= 0)
+        return parsed;
+    throw new Error("invalid evidence bundle handle");
+}
+function limit(value, fallback) {
+    const result = value ?? fallback;
+    if (!Number.isSafeInteger(result) || result < 1)
+        throw new Error("evidence bundle budgets must be positive integers");
+    return result;
+}
+/** Graph associations come only from the injected adapter; source is always reread locally. */
+export async function deliverEvidenceBundle(request, adapter) {
+    if (!Array.isArray(request.files) ||
+        request.files.length === 0 ||
+        request.files.length > MAX_FILES)
+        throw new Error(`evidence bundle requires 1-${MAX_FILES} files`);
+    if (request.level !== undefined && request.level !== "evidence" && request.level !== "expand")
+        throw new Error("invalid evidence bundle level");
+    if ((request.alreadyPresent?.length ?? 0) > MAX_FILES)
+        throw new Error("too many already-present evidence handles");
+    const initial = request.files.map((file) => normalizeEvidenceFile(request.repo, file));
+    const root = initial[0].root;
+    const requested = [...new Set(initial.map((file) => file.relative))].sort(compareBytes);
+    const graph = request.level === "expand" && adapter
+        ? await adapter.relatedFiles(root, requested)
+        : {
+            files: [],
+            freshness: "unknown",
+            indexCoverage: undefined,
+            coverageNotice: undefined,
+            sourceHashes: undefined,
+            validate: undefined,
+            omissions: request.level === "expand"
+                ? ["Graph adapter unavailable; related files were not selected."]
+                : [],
+        };
+    const omissions = [...graph.omissions];
+    const relations = graph.freshness === "fresh" ? graph.files : [];
+    if (graph.freshness !== "fresh" && graph.files.length)
+        omissions.push("Related files omitted because graph evidence is not fresh.");
+    const candidates = [...requested];
+    for (const relation of relations) {
+        const normalized = normalizeEvidenceFile(root, relation.file).relative;
+        if (!candidates.includes(normalized))
+            candidates.push(normalized);
+    }
+    if (candidates.length > MAX_FILES)
+        throw new RangeError(`evidence bundle exceeds ${MAX_FILES} files; narrow the selected graph scope`);
+    const key = evidenceHandleSecret(root);
+    const keyStat = fs.statSync(key.path);
+    let totalBytes = 0;
+    const contents = candidates.map((file) => {
+        const normalized = normalizeEvidenceFile(root, file);
+        const stat = fs.statSync(normalized.absolute);
+        if (stat.dev === keyStat.dev && stat.ino === keyStat.ino)
+            throw new Error("evidence bundle refuses an alias of internal knodin state");
+        totalBytes += stat.size;
+        if (totalBytes > MAX_SOURCE_BYTES)
+            throw new RangeError("evidence bundle source exceeds 8 MiB; narrow the selection");
+        const { source, bytes } = readEvidenceUtf8(normalized.absolute);
+        const contentHash = hash(source);
+        if (graph.sourceHashes && graph.sourceHashes[file] !== contentHash)
+            throw new Error("evidence bundle source changed after graph selection; restart the bundle");
+        // A concurrent append may outgrow the pre-read stat; account actual returned bytes too.
+        totalBytes += bytes - stat.size;
+        if (totalBytes > MAX_SOURCE_BYTES)
+            throw new RangeError("evidence bundle source exceeds 8 MiB; narrow the selection");
+        return {
+            file,
+            source,
+            stat,
+            lines: source.split("\n"),
+            hash: contentHash,
+            bytes,
+        };
+    });
+    const manifest = contents.map((file) => ({
+        file: file.file,
+        contentHash: file.hash,
+        contentBytes: file.bytes,
+        evidenceHandle: null,
+        relations: relations.filter((relation) => normalizeEvidenceFile(root, relation.file).relative === file.file),
+    }));
+    const receipts = (request.alreadyPresent ?? []).map((value) => {
+        const receipt = verify(value, key.secret);
+        if (receipt.type !== "file-complete")
+            throw new Error("alreadyPresent requires per-file evidence handles");
+        return receipt;
+    });
+    const invalidated = receipts
+        .filter((receipt) => !contents.some((file) => file.file === receipt.file &&
+        file.hash === receipt.hash &&
+        file.bytes === receipt.bytes))
+        .map((receipt) => receipt.file);
+    const present = new Set(contents
+        .filter((file) => receipts.some((receipt) => file.file === receipt.file &&
+        file.hash === receipt.hash &&
+        file.bytes === receipt.bytes))
+        .map((file) => file.file));
+    // Bind membership, provenance, content and reuse assertions, so a cursor cannot silently skip changed evidence.
+    const manifestHash = hash(JSON.stringify({
+        requested,
+        level: request.level ?? "evidence",
+        manifest,
+        present: [...present],
+        freshness: graph.freshness,
+        indexCoverage: indexCoverageCore(graph.indexCoverage),
+        omissions,
+    }));
+    const cursor = request.continuation ? verify(request.continuation, key.secret) : undefined;
+    if (cursor && (cursor.type !== "cursor" || cursor.digest !== manifestHash))
+        throw new Error("stale or changed evidence bundle continuation; restart the bundle");
+    let fileIndex = cursor?.type === "cursor" ? cursor.fileIndex : 0;
+    let lineIndex = cursor?.type === "cursor" ? cursor.lineIndex : 0;
+    if (fileIndex > contents.length ||
+        (fileIndex < contents.length && lineIndex >= contents[fileIndex].lines.length))
+        throw new Error("invalid evidence bundle cursor range");
+    const tokenLimit = limit(request.tokenLimit, 16384);
+    const byteLimit = Math.min(limit(request.byteLimit, 65536), tokenLimit * 4);
+    const itemLimit = limit(request.itemLimit, 100);
+    const response = {
+        protocol: "knodin-evidence-bundle-v1",
+        manifest,
+        manifestHash,
+        files: [],
+        reused: [],
+        invalidated,
+        graphFreshness: graph.freshness,
+        ...(graph.indexCoverage ? { indexCoverage: indexCoverageCore(graph.indexCoverage) } : {}),
+        ...(graph.coverageNotice ? { coverageNotice: graph.coverageNotice } : {}),
+        sourceFreshness: "fresh",
+        omissions,
+        more: fileIndex < contents.length,
+        continuation: null,
+        budget: {
+            byteLimit,
+            tokenLimit,
+            itemLimit,
+            serializedBytes: 0,
+            estimatedTokens: 0,
+            returnedItems: 0,
+            truncated: false,
+        },
+    };
+    const refresh = () => {
+        for (const [index, entry] of manifest.entries()) {
+            entry.evidenceHandle =
+                index < fileIndex || present.has(entry.file)
+                    ? sign({
+                        type: "file-complete",
+                        file: entry.file,
+                        hash: entry.contentHash,
+                        bytes: entry.contentBytes,
+                    }, key.secret)
+                    : null;
+        }
+        response.more = fileIndex < contents.length;
+        response.continuation = response.more
+            ? sign({ type: "cursor", digest: manifestHash, fileIndex, lineIndex }, key.secret)
+            : null;
+        response.budget.truncated = response.more || omissions.length > 0;
+        for (let iteration = 0; iteration < 6; iteration++) {
+            response.budget.serializedBytes = Buffer.byteLength(JSON.stringify(response));
+            response.budget.estimatedTokens = Math.ceil(response.budget.serializedBytes / 4);
+        }
+    };
+    refresh();
+    if (response.budget.serializedBytes > byteLimit)
+        throw new RangeError("evidence bundle manifest exceeds hard byte/token budget; increase budget or narrow files");
+    while (fileIndex < contents.length && response.budget.returnedItems < itemLimit) {
+        const file = contents[fileIndex];
+        const previousFile = fileIndex;
+        const previousLine = lineIndex;
+        const previousFiles = response.files.map((entry) => ({
+            ...entry,
+            sourceRange: { ...entry.sourceRange },
+        }));
+        const previousReused = [...response.reused];
+        if (present.has(file.file)) {
+            response.reused.push(file.file);
+            fileIndex++;
+            lineIndex = 0;
+        }
+        else {
+            let delivered = response.files.at(-1);
+            if (!delivered || delivered.file !== file.file) {
+                delivered = {
+                    file: file.file,
+                    source: file.lines[lineIndex],
+                    sourceRange: { startLine: lineIndex + 1, endLine: lineIndex + 1 },
+                };
+                response.files.push(delivered);
+            }
+            else {
+                delivered.source += `\n${file.lines[lineIndex]}`;
+                delivered.sourceRange.endLine = lineIndex + 1;
+            }
+            lineIndex++;
+            if (lineIndex === file.lines.length) {
+                fileIndex++;
+                lineIndex = 0;
+            }
+        }
+        response.budget.returnedItems++;
+        refresh();
+        if (response.budget.serializedBytes > byteLimit) {
+            fileIndex = previousFile;
+            lineIndex = previousLine;
+            response.files = previousFiles;
+            response.reused = previousReused;
+            response.budget.returnedItems--;
+            refresh();
+            break;
+        }
+    }
+    // Rendering can overlap external edits. Never return fresh source or reusable
+    // completion receipts for a selection that changed while this page was built.
+    await graph.validate?.();
+    for (const file of contents) {
+        const normalized = normalizeEvidenceFile(root, file.file);
+        const stat = fs.statSync(normalized.absolute);
+        if (stat.dev !== file.stat.dev ||
+            stat.ino !== file.stat.ino ||
+            stat.size !== file.stat.size ||
+            hash(readEvidenceUtf8(normalized.absolute).source) !== file.hash)
+            throw new Error("evidence bundle source changed during delivery; restart the bundle");
+    }
+    return response;
+}

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;
+}