@descryy/mcp 0.11.5 → 0.11.7

package/dist/tools/analyze.js

@@ -0,0 +1,724 @@
+/** `analyze` — the only tool that writes to the graph. Disclosures matter most: a
+ *  query can't report a gap it wasn't told about. Discloses: sources that failed or
+ *  didn't claim the repo (§20.2 — not-analysable ≠ clean), each source's resolution
+ *  reached (caps reliability, rule 3), id collisions (DEC-024), evicted files, and the
+ *  cross-repo join count. No config → `repo` defaults to dir name, hashed into every id (DEC-004). */
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { isStructuredSkipEntry } from "@descryy/ir";
+import { applyConfirmedFacts, buildGraph, CONFIRMED_INCIDENT_SOURCE_ID, CONFIRMED_INCIDENT_SOURCE_VERSION, counts, createConfirmedIncidentSource, createGitSource, evictStaleConfirmedIncidentNodes, FILELESS_CACHE_KEY, getCachedFiles, listWorkingTreeFiles, mintEdgesFromConfirmedFacts, MINT_PRODUCED_BY, partitionBatchByFile, persistGraph, planIncrementalReuse, replaceCachedFiles, summariseRefusals, } from "@descryy/core";
+import { answer, optionalBoolean, ToolInputError } from "./kit.js";
+import { heapGuard, readHeap } from "../heap.js";
+import { withHeartbeat } from "../heartbeat.js";
+import { detectSources, loadSources } from "../registry.js";
+// Re-exported for `analyze.test.ts`, which covers this pure helper in isolation.
+// The check itself now runs centrally in `server.ts` (13.3.16 / N2 steps 2-3) —
+// every reply discloses a stale config, not only this tool's.
+export { configDriftNote } from "../session.js";
+/** `skippedFiles`/`unresolved`: absent means an adapter compiled against an older
+ *  `@descryy/ir`, not malformed — a real adapter once crashed here on `.length` of
+ *  undefined despite returning 1000+ good nodes. Absent ⇒ old producer; wrong type ⇒ broken, never defaulted away. */
+export function optionalBatchLists(batch) {
+    const read = (value, field) => {
+        if (value === undefined || value === null)
+            return [];
+        if (!Array.isArray(value)) {
+            throw new TypeError(`${field} must be an array when present, got ${typeof value}`);
+        }
+        return value;
+    };
+    return {
+        skippedFiles: read(batch.skippedFiles, "skippedFiles"),
+        unresolved: read(batch.unresolved, "unresolved"),
+    };
+}
+/** Distinguishes "the adapter failed" from "Descry's own code broke handling its
+ *  output" — before this, a `TypeError` thrown in this file was reported as the
+ *  adapter failing, sending users to debug working code instead of reporting our bug. */
+/**
+ * F2 (UAT phase 4 F3 / Part 13 §13.3.2): which build actually ran. A bare
+ * specifier can resolve to more than one installed copy with the same
+ * name — CJS resolution walks upward through `node_modules`, so a stray
+ * install above the repository silently wins over the intended one, and
+ * `producedBy` alone cannot tell them apart (it carries the module's own
+ * self-declared version, which can drift from what actually shipped).
+ * This is the disclosure that makes "why are my results different from
+ * yours" answerable instead of a debugging session.
+ */
+export function sourceProvenanceNote(entry) {
+    const version = entry.packageVersion ?? "unknown version";
+    const location = entry.resolvedPath !== null
+        ? `resolved from ${entry.resolvedPath} (${entry.via === "repo" ? "the scanned repository" : "this server's own module closure"})`
+        : "resolved via this server's own module closure (the exact path could not be determined)";
+    // UAT phase 5 §1b: the winning path alone does not explain why a repo whose
+    // adapter should be repo-local keeps getting the server's own copy instead —
+    // naming the candidate that was found and rejected is what makes that
+    // answerable without a debugging session.
+    const rejected = entry.rejectedRepoCandidate === null ? "" : ` A repo-local candidate was rejected: ${entry.rejectedRepoCandidate}`;
+    return `${entry.source.id} — ${entry.spec.module}@${version}, ${location}.${rejected}`;
+}
+export function sourceFailureNote(sourceId, error, phase) {
+    const message = error instanceof Error ? error.message : String(error);
+    return phase === "emit"
+        ? `${sourceId} failed while reading this repository (${message}). ` +
+            "Everything it covers is not analysable."
+        : `Descry itself failed while processing ${sourceId}'s output (${message}). This is a ` +
+            "defect in Descry, not in that adapter and not in your code — the adapter returned " +
+            "successfully and its results were dropped for this run. Everything it covers is not " +
+            "analysable until this is fixed.";
+}
+const SCHEMA = {
+    type: "object",
+    properties: {
+        includeHistory: {
+            type: "boolean",
+            description: "Read git history for co-change coupling (CHANGES_WITH edges). Default true. " +
+                "Costs a few seconds on a large repository.",
+        },
+        maxCommits: {
+            type: "integer",
+            minimum: 1,
+            description: "Cap on commits read from history. Default 2000.",
+        },
+        reload: {
+            type: "boolean",
+            description: "Re-read .descry/config.json from disk before this run, rather than using the " +
+                "configuration this server started with. Configuration is otherwise read once per " +
+                "process — a plain edit to the file, including its \"sources\" list, does nothing until " +
+                "either the server restarts or a call passes this. Every trust check on the new " +
+                "specifiers (module-trust.ts) runs again as part of loading them, exactly as it would on " +
+                "a fresh start; this is not a way around that gate.",
+        },
+    },
+    additionalProperties: false,
+};
+/** §5.4's `refusals` field for this run only, not the graph's whole ledger
+ *  (`refusal_fetch`'s job) — a fresh population per call, honestly scoped to what
+ *  this run found. `undefined` on zero rows so `refusals` stays `null`, not an empty summary. */
+async function hashFileContent(absolutePath) {
+    try {
+        return createHash("sha256").update(await readFile(absolutePath)).digest("hex");
+    }
+    catch {
+        // Deleted, unreadable, or otherwise gone — left absent so the caller's
+        // hash lookup mismatches the cached value and correctly reports "changed".
+        return null;
+    }
+}
+/** Gap 6 step 3: attempts whole-producer cache reuse for one `LanguageAdapter`
+ *  source, so a repeat `analyze` run can skip `emit()` (and the re-parse inside
+ *  it) entirely when nothing this producer read has changed. Every failure path
+ *  here returns `{ reused: false }` rather than throwing — declining to reuse is
+ *  always safe, and the caller's normal `emit()` path is the fallback. See
+ *  `planIncrementalReuse`'s doc (`@descryy/core`) for why this is whole-producer,
+ *  never per-file. */
+export async function attemptIncrementalReuse(params) {
+    const cache = getCachedFiles(params.driver, params.producedBy, params.repo);
+    const cachedPaths = [...cache.files.keys()].filter((path) => path !== FILELESS_CACHE_KEY);
+    const cachedHashes = new Map(cachedPaths.map((path) => [path, cache.files.get(path).contentHash]));
+    const currentHashes = new Map();
+    for (const path of cachedPaths) {
+        const hash = await hashFileContent(join(params.repoPath, path));
+        if (hash !== null)
+            currentHashes.set(path, hash);
+    }
+    const decision = planIncrementalReuse({
+        cachedPaths,
+        repoPaths: params.repoFileListing,
+        currentHashes,
+        cachedHashes,
+    });
+    if (!decision.canReuse)
+        return { reused: false, reason: decision.reason };
+    const nodes = [];
+    const edges = [];
+    const unresolved = [];
+    for (const entry of cache.files.values()) {
+        nodes.push(...entry.nodes);
+        edges.push(...entry.edges);
+        unresolved.push(...entry.unresolved);
+    }
+    const batch = {
+        repo: params.repo,
+        ...(params.workspace === undefined ? {} : { workspace: params.workspace }),
+        commitSha: params.commitSha,
+        producedBy: params.producedBy,
+        sourceFiles: cachedPaths,
+        skippedFiles: cache.skippedFiles,
+        reachedResolution: (cache.reachedResolution ?? 0),
+        nodes,
+        edges,
+        unresolved,
+    };
+    return { reused: true, batch };
+}
+export function refusalSummaryField(unresolved) {
+    const summary = summariseRefusals(unresolved);
+    if (summary.count === 0 || summary.exemplar === null || summary.handle === null)
+        return undefined;
+    return { count: summary.count, exemplar: summary.exemplar, handle: summary.handle };
+}
+/** Single-repo half of the joins disclosure. In the ordinary case — one repo in scope —
+ *  every join metric's `suppliedByTwoOrMoreRepos: 0` looks like `NO_CROSS_REPO_JOIN`'s
+ *  failure case; this states outright it's just scope, not a failed join. */
+export function crossRepoJoinNote(joins) {
+    const singleRepo = joins.filter((j) => !j.crossRepoJoinPossible);
+    if (singleRepo.length === 0)
+        return undefined;
+    return (`${singleRepo.length} of ${joins.length} join metric(s) — ` +
+        `${singleRepo.map((j) => j.type).join(", ")} — reflect one repository in this build's scope. ` +
+        "A cross-repo join is not possible here, so 0 is the only value suppliedByTwoOrMoreRepos could " +
+        "take for them; this is not the NO_CROSS_REPO_JOIN warning, which is for two or more " +
+        "repositories that failed to join.");
+}
+/** Turns one adapter's `DetectionResult.evidence` into the same kind of disclosed note the
+ *  `skippedFiles` rollup below builds — grouped by `reason` where an entry is a
+ *  `StructuredSkipEntry`, left under an "other" bucket, verbatim, where it is still the
+ *  legacy plain-string shape (`isStructuredSkipEntry`, `@descryy/ir`). `null` on an empty
+ *  list — nothing to disclose, not a note saying so. */
+export function summariseDetectionEvidence(evidence) {
+    if (evidence.entries.length === 0)
+        return null;
+    const byReason = new Map();
+    const legacy = [];
+    for (const entry of evidence.entries) {
+        if (isStructuredSkipEntry(entry)) {
+            byReason.set(entry.reason, (byReason.get(entry.reason) ?? 0) + 1);
+        }
+        else {
+            legacy.push(entry);
+        }
+    }
+    const parts = [...byReason.entries()].map(([reason, count]) => `${count} ${reason}`);
+    if (legacy.length > 0)
+        parts.push(`${legacy.length} other (${legacy.join("; ")})`);
+    return (`${evidence.source} reported ${evidence.entries.length} detection note(s) for this ` +
+        `repository (${parts.join(", ")}).`);
+}
+async function run(args, ctx) {
+    const { session } = ctx;
+    const includeHistory = args["includeHistory"] !== false;
+    const maxCommits = args["maxCommits"];
+    if (maxCommits !== undefined && (typeof maxCommits !== "number" || !Number.isInteger(maxCommits) || maxCommits < 1)) {
+        throw new ToolInputError('"maxCommits" must be a positive integer');
+    }
+    const notes = [];
+    // §0 gap 2 (UAT phase 5): configuration is otherwise read once per process.
+    // Explicit and caller-initiated, never a file watcher — see `reloadConfig`'s
+    // own doc for why. Before `session.root()`, so a changed "repo"/"workspace"
+    // is reflected in this very run rather than the one after.
+    if (optionalBoolean(args, "reload") === true) {
+        const { changed } = await session.reloadConfig();
+        notes.push(changed.length > 0
+            ? `Reloaded .descry/config.json from disk before this run (changed: ${changed.join(", ")}).`
+            : "Reloaded .descry/config.json from disk before this run — nothing had actually changed.");
+    }
+    const root = await session.root();
+    // MK-4: analyze rebuilds from source regardless, so a stale IR schema is repaired
+    // here rather than refused — see `Session.repairStaleGraph` for why only this tool does this.
+    const { rebuilt } = session.repairStaleGraph();
+    if (rebuilt) {
+        notes.push("The stored graph was written under an older IR schema version. Its derived tables were " +
+            "dropped and are rebuilt by this run; earned data (R4 observations, edge corrections, " +
+            "incident links) was not affected.");
+    }
+    // Config drift is now checked centrally in server.ts for every tool (13.3.16 /
+    // N2 steps 2-3), not just this one — see `checkConfigDrift` in session.ts.
+    if (session.config.configPath === null) {
+        notes.push(`No ${".descry/config.json"} was found, so the repository identity defaults to the ` +
+            `directory name ("${session.config.repo}"). Every repo-scoped node id is a hash over that ` +
+            "string: cloning into a differently-named folder produces a different graph, and incident " +
+            "links and co-change weights do not survive the change. Set \"repo\" explicitly.");
+    }
+    if (session.config.workspace === undefined) {
+        notes.push("No workspace is configured, so this repository is its own contract boundary. Endpoints, " +
+            "tables and incidents will not join with any other repository's (DEC-054). If there is a " +
+            'sibling repository this one should join — a frontend to this backend, for example — ask ' +
+            'whether they should share a workspace, and call "link_workspace" once confirmed. Never ' +
+            "call it on a guess: a directory sitting next to another is a suggestion, not evidence.");
+    }
+    // --- sources -------------------------------------------------------------
+    const registry = await loadSources(session.config.sources, session.repoPath);
+    for (const failure of registry.failed) {
+        notes.push(`The source "${failure.spec.module}" could not be loaded (${failure.reason}). Anything it ` +
+            "would have read is not analysable — not clean.");
+    }
+    for (const entry of registry.loaded) {
+        notes.push(sourceProvenanceNote(entry));
+    }
+    if (session.config.sources.length === 0) {
+        notes.push(
+        // No example package name here — naming one would leak a specific language into
+        // this engine, the inversion `registry.ts` exists to prevent (rule 1: IR boundary).
+        "No language adapters are configured, so nothing was read from source. Add a \"sources\" " +
+            `array to ${".descry/config.json"} listing the adapter packages to load, as module ` +
+            "specifiers. This engine does not know the name of any adapter: the IR boundary is a " +
+            "dependency direction, so the list has to come from configuration.");
+    }
+    const { applicable, skipped, evidence } = await detectSources(registry.loaded, root);
+    for (const entry of skipped) {
+        notes.push(`${entry.source.source.id} did not run: it ${entry.reason}. Any code only that adapter ` +
+            "could read is not analysable.");
+    }
+    for (const item of evidence) {
+        const note = summariseDetectionEvidence(item);
+        if (note !== null)
+            notes.push(note);
+    }
+    // --- emit ----------------------------------------------------------------
+    const context = {
+        root,
+        prepareTimeoutMs: 300_000,
+        signal: ctx.signal,
+    };
+    const batches = [];
+    const perSource = [];
+    /** Resolution floor comes from code-reading sources only — git history is always R0
+     *  by nature, not degradation; folding it in would cap every reply at class C. DEC-058:
+     *  an edge carries its own evidence's resolution, not the run's; each source still reported individually. */
+    const codeResolutions = [];
+    const total = applicable.length + (includeHistory ? 1 : 0);
+    let done = 0;
+    const driver = session.store().driver;
+    // Computed once for the whole run, not per source: every `LanguageAdapter`
+    // source's Gap 6 reuse check needs the same "what does the working tree have
+    // right now" answer, and it is meaningless to ask git for it twice. `null`
+    // when it cannot be determined at all (no git, or git unavailable) — every
+    // incremental check below then conservatively declines to reuse anything.
+    const repoFileListing = await listWorkingTreeFiles(session.repoPath).catch(() => null);
+    /**
+     * P6-B1. The fence, at the two points where this tool's memory actually
+     * peaks: before an adapter is asked to read the repository (its batch is
+     * retained for the whole run), and before the merge, which holds every
+     * batch and the built graph live at once. A V8 heap abort cannot be caught
+     * — this is the only place the failure can be turned into a reply.
+     *
+     * `sourcesRead` reports what had already emitted, because those batches are
+     * discarded unwritten: without it the reply would be silent about work that
+     * did happen and produced nothing.
+     */
+    const halted = (phase) => {
+        const reading = readHeap();
+        const note = heapGuard(reading, phase);
+        if (note === null)
+            return null;
+        const base = session.provider().baseStamp();
+        return answer({
+            headline: `Analysis of ${session.config.repo} stopped at the heap ceiling before "${phase}". ` +
+                "Nothing was written to the graph.",
+            state: "failed",
+            nameLevel: true,
+            resolutionFloor: 0,
+            commitSha: root.commitSha,
+            graphBuiltAt: base.graphBuiltAt,
+            irSchemaVersion: base.irSchemaVersion,
+            commitSpread: base.commitSpread,
+            repoCount: base.repoCount,
+            notes: [...notes, note],
+            data: {
+                halted: "heap",
+                phase,
+                heapUsedMib: Math.round(reading.usedBytes / (1024 * 1024)),
+                heapLimitMib: Math.round(reading.limitBytes / (1024 * 1024)),
+                sourcesRead: perSource,
+            },
+        });
+    };
+    for (const entry of applicable) {
+        const fence = halted(`Reading ${entry.source.id}`);
+        if (fence !== null)
+            return fence;
+        ctx.progress(`Reading ${entry.source.id}`, done, total);
+        const started = Date.now();
+        // Gap 6: only `LanguageAdapter` sources pay the re-parse cost this exists
+        // to avoid — the git-history/confirmed-incidents/mint sources below are
+        // already cheap and deterministic and are out of scope for this cache.
+        if (entry.adapter !== null) {
+            const expectedProducedBy = `${entry.source.id}@${entry.source.version}`;
+            const reuse = await attemptIncrementalReuse({
+                driver,
+                producedBy: expectedProducedBy,
+                repo: session.config.repo,
+                repoPath: session.repoPath,
+                repoFileListing,
+                commitSha: root.commitSha,
+                workspace: session.config.workspace,
+            });
+            if (reuse.reused) {
+                const batch = reuse.batch;
+                batches.push(batch);
+                perSource.push({
+                    source: batch.producedBy,
+                    installedVersion: entry.packageVersion,
+                    files: batch.sourceFiles.length,
+                    nodes: batch.nodes.length,
+                    edges: batch.edges.length,
+                    unresolved: batch.unresolved.length,
+                    skippedFiles: batch.skippedFiles.length,
+                    reachedResolution: batch.reachedResolution,
+                    ms: 0,
+                });
+                const ceiling = entry.adapter.capabilities().maxResolution;
+                codeResolutions.push(batch.reachedResolution);
+                notes.push(`${entry.source.id}: reused ${String(batch.sourceFiles.length)} cached file(s) from the ` +
+                    "previous run, unchanged since — not re-parsed this run (Gap 6 incremental indexing). " +
+                    "Cross-file effects (a change in one file altering another file's resolved edges) are " +
+                    "not re-checked by this cache; see documents/plans/site-claims-closure-production-plan.md Gap 6.");
+                if (batch.reachedResolution < ceiling) {
+                    notes.push(`${entry.source.id} reached R${String(batch.reachedResolution)} where it is capable of ` +
+                        `R${String(ceiling)} (cached from its last real run). Findings resting on its edges are ` +
+                        "capped accordingly, and shape-level checks (contract matching, field propagation) need R3.");
+                }
+                done += 1;
+                continue;
+            }
+        }
+        // Adapter's own work and Descry's handling of its output are separate phases with
+        // separate blame — folding them into one `try` let a `TypeError` here be blamed on the adapter.
+        let batch;
+        try {
+            // P6-B2. An adapter reading a large repository can hold this await for
+            // minutes, and until now that was the whole gap between two progress
+            // frames — long enough for the client's timeout to fire on a run that
+            // was working. The beat keeps the request visibly alive; it does not
+            // claim to know how far through the adapter is, because this side
+            // cannot see that and will not invent it.
+            batch = await withHeartbeat(`Reading ${entry.source.id}`, (message) => ctx.progress(message, done, total), () => entry.source.emit(context));
+        }
+        catch (error) {
+            notes.push(sourceFailureNote(entry.source.id, error, "emit"));
+            await entry.adapter?.dispose();
+            done += 1;
+            continue;
+        }
+        try {
+            const { skippedFiles, unresolved } = optionalBatchLists(batch);
+            batches.push(batch);
+            perSource.push({
+                source: batch.producedBy,
+                installedVersion: entry.packageVersion,
+                files: batch.sourceFiles.length,
+                nodes: batch.nodes.length,
+                edges: batch.edges.length,
+                unresolved: unresolved.length,
+                skippedFiles: skippedFiles.length,
+                reachedResolution: batch.reachedResolution,
+                ms: Date.now() - started,
+            });
+            // Gap 6 step 3: this was a real parse (reuse would have `continue`d above),
+            // so refresh the per-file cache from its output — the only place the
+            // cache is ever written. A producer whose declared `id@version` drifted
+            // from its self-declared `producedBy` (see `sourceProvenanceNote`) simply
+            // caches under the real `producedBy`; the next run's reuse check looks
+            // for `${id}@${version}` and will not find a mismatched entry, which is
+            // the safe direction for this to fail (always falls back to full reparse).
+            try {
+                const partitioned = partitionBatchByFile(batch);
+                const cacheEntries = [];
+                for (const [filePath, contribution] of partitioned) {
+                    const contentHash = filePath === FILELESS_CACHE_KEY
+                        ? "fileless"
+                        : (await hashFileContent(join(session.repoPath, filePath))) ?? "unreadable";
+                    cacheEntries.push({ filePath, contentHash, ...contribution });
+                }
+                replaceCachedFiles(driver, batch.producedBy, session.config.repo, cacheEntries, batch.reachedResolution, skippedFiles, Date.now());
+            }
+            catch {
+                // Caching is an optimisation, never a correctness requirement — a
+                // failure here must not fail the run or lose the batch already pushed
+                // above. Worst case: the next run finds no cache and reparses fully.
+            }
+            // Declared ceiling vs what this run reached — a gap is honest degradation (rule 7):
+            // the adapter can do better but something in this repo stopped it.
+            const ceiling = entry.adapter?.capabilities().maxResolution;
+            if (ceiling !== undefined)
+                codeResolutions.push(batch.reachedResolution);
+            if (ceiling !== undefined && batch.reachedResolution < ceiling) {
+                notes.push(`${entry.source.id} reached R${batch.reachedResolution} where it is capable of ` +
+                    `R${ceiling}. Findings resting on its edges are capped accordingly, and shape-level ` +
+                    "checks (contract matching, field propagation) need R3.");
+            }
+            if (skippedFiles.length > 0) {
+                const byReason = new Map();
+                for (const skipped of skippedFiles) {
+                    byReason.set(skipped.reason, (byReason.get(skipped.reason) ?? 0) + 1);
+                }
+                const summary = [...byReason.entries()].map(([reason, count]) => `${count} ${reason}`).join(", ");
+                notes.push(`${entry.source.id} could not analyse ${skippedFiles.length} file(s) it attempted ` +
+                    `(${summary}). Not analysable — absent from the graph, not confirmed clean.`);
+            }
+        }
+        catch (error) {
+            // Reached only when Descry's own handling threw — the adapter already returned successfully.
+            notes.push(sourceFailureNote(entry.source.id, error, "engine"));
+        }
+        finally {
+            // `dispose` is a `LanguageAdapter` obligation, not `IRSource`'s — a leaked language
+            // server costs hundreds of MB per repo. Sources with none to release (git reader) need no method.
+            await entry.adapter?.dispose();
+            done += 1;
+        }
+    }
+    if (includeHistory) {
+        ctx.progress("Reading git history", done, total);
+        const historyStarted = Date.now();
+        try {
+            // P6-B2, same reason as the adapter read above: `maxCommits` defaults to
+            // 2000, and walking that much history on a large repository is its own
+            // multi-minute silence.
+            const history = await withHeartbeat("Reading git history", (message) => ctx.progress(message, done, total), () => createGitSource({
+                repo: root.repo,
+                cwd: session.repoPath,
+                ...(typeof maxCommits === "number" ? { maxCommits } : {}),
+            }).emit(context));
+            batches.push(history);
+            perSource.push({
+                source: history.producedBy,
+                // Built into this engine, not a loaded adapter module — there is no separate
+                // "installed artifact" to disagree with its own self-declared version.
+                installedVersion: null,
+                files: history.sourceFiles.length,
+                nodes: history.nodes.length,
+                edges: history.edges.length,
+                unresolved: history.unresolved.length,
+                skippedFiles: history.skippedFiles.length,
+                reachedResolution: history.reachedResolution,
+                ms: Date.now() - historyStarted,
+            });
+        }
+        catch (error) {
+            notes.push(`Git history was not read (${error.message}), so co-change coupling is absent ` +
+                "and blast radii will not include historically coupled files.");
+        }
+        done += 1;
+    }
+    else {
+        notes.push("Git history was skipped by request, so no CHANGES_WITH edges were produced and the blast " +
+            "radius will miss files that historically change together.");
+    }
+    // Developer-confirmed incidents, re-projected every analyze run. The record lives in
+    // `.descry/config.json` (testimony, DEC-223) — the graph only holds a derived projection,
+    // dropped on every schema bump, so re-emitting here is what keeps a rebuild from losing it.
+    const confirmedIncidents = session.config.confirmedIncidents ?? [];
+    if (confirmedIncidents.length > 0) {
+        const projected = await createConfirmedIncidentSource({
+            repo: root.repo,
+            incidents: confirmedIncidents,
+        }).emit(context);
+        batches.push(projected);
+        perSource.push({
+            source: projected.producedBy,
+            // Same reasoning as the git-history source above: this is a re-projection of
+            // testimony already in .descry/config.json, not a loaded adapter module.
+            installedVersion: null,
+            files: projected.sourceFiles.length,
+            nodes: projected.nodes.length,
+            edges: projected.edges.length,
+            unresolved: projected.unresolved.length,
+            skippedFiles: 0,
+            reachedResolution: projected.reachedResolution,
+            ms: 0,
+        });
+        notes.push(`${confirmedIncidents.length} developer-confirmed incident(s) were re-projected into the ` +
+            "graph from .descry/config.json. They are testimony, not a reading of this repository — " +
+            "an edge resting on one is capped at reliability class B (DEC-223).");
+    }
+    // --- build and store -----------------------------------------------------
+    // The real peak: every batch is live here and `buildGraph` allocates the
+    // merged graph beside them. This is the checkpoint the field report needed.
+    const mergeFence = halted("Merging into the graph");
+    if (mergeFence !== null)
+        return mergeFence;
+    ctx.progress("Merging into the graph", done, total);
+    const built = buildGraph(batches, {
+        nodeExists: (id) => session.provider().node(id) !== undefined,
+    });
+    const persisted = persistGraph(session.store().driver, batches, built);
+    // confirmed-incidents' output is a small, fully-specified list re-derived from
+    // config every run — a deleted incident whose files aren't referenced by any
+    // surviving incident shares no file with the prior run, so the eviction above
+    // (file-overlap keyed) never retires its INCIDENT/FIX_PATTERN nodes. This
+    // fires unconditionally, even when `confirmedIncidents` is now empty and no
+    // `projected` batch was built this run — that emptiness IS the current node
+    // set to evict everything else against.
+    const confirmedIncidentsProducedBy = `${CONFIRMED_INCIDENT_SOURCE_ID}@${CONFIRMED_INCIDENT_SOURCE_VERSION}`;
+    evictStaleConfirmedIncidentNodes(session.store().driver, confirmedIncidentsProducedBy, new Set(built.nodes.filter((n) => n.producedBy === confirmedIncidentsProducedBy).map((n) => n.id)));
+    for (const collision of built.collisions) {
+        notes.push(`Two different things claimed node id ${collision.nodeId}: a ${collision.kept.type} from ` +
+            `${collision.kept.producedBy} and a ${collision.discarded.type} from ` +
+            `${collision.discarded.producedBy}. They are not the same symbol and there is no correct ` +
+            "merge, so the second was discarded (DEC-024).");
+    }
+    if (built.droppedEdges > 0) {
+        notes.push(`${built.droppedEdges} edge(s) were dropped because an endpoint did not resolve to a real ` +
+            "node. They are never stubbed into existence — a name-matched guess belongs in the " +
+            "unresolved-reference ledger, not in the graph.");
+    }
+    if (built.rejections.length > 0) {
+        notes.push(`${built.rejections.length} item(s) were turned away at the IR boundary as malformed. They ` +
+            "are not in the graph and nothing above will see them.");
+    }
+    if (persisted.evictedFiles.length > 0) {
+        notes.push(`${persisted.evictedFiles.length} file(s) covered by a previous run were not re-supplied by ` +
+            "this one; their rows have been removed. A query about them will now find nothing because " +
+            "nothing is stored, not because there is nothing there.");
+    }
+    for (const warning of built.warnings)
+        notes.push(warning.detail);
+    const joinNote = crossRepoJoinNote(built.crossRepoJoins);
+    if (joinNote !== undefined)
+        notes.push(joinNote);
+    if (built.unresolved.length > 0) {
+        notes.push(`${built.unresolved.length} reference(s) could not be resolved to a target and are recorded ` +
+            "in the ledger rather than guessed at. They are the measured recall gap, not an error.");
+    }
+    // --- mint edges from confirmed facts --------------------------------------
+    //
+    // DEC-223/DEC-138 minting, sequenced after the graph is persisted: a confirmed answer
+    // joins against a stored `API_ENDPOINT` row via the SQL-backed `EndpointLookup`, not
+    // `built`'s in-memory result, so the row must already exist for the lookup to find it.
+    ctx.progress("Minting edges from confirmed facts", done, total);
+    const provider = session.provider();
+    const { refs: ledgerRefs } = provider.unresolvedRefs();
+    const { answered } = applyConfirmedFacts(ledgerRefs, session.config.confirmedFacts, session.config.repo);
+    const scope = {
+        repo: session.config.repo,
+        ...(session.config.workspace === undefined ? {} : { workspace: session.config.workspace }),
+    };
+    const mintResult = mintEdgesFromConfirmedFacts(answered, provider, scope, MINT_PRODUCED_BY, root.commitSha);
+    // Invalidation key (DEC-015: producedBy+sourceFiles), scoped to every *askable* file this
+    // run, not just answered ones — else a file dropping its one answer would vanish from
+    // sourceFiles and its stale edge could never be found by the writer's self-clean pass to retire.
+    const mintFiles = [
+        ...new Set(ledgerRefs.flatMap((ref) => ref.attrs?.["refusalClass"] === "value-unknown" && typeof ref.file === "string" ? [ref.file] : [])),
+    ].sort();
+    const mintBatch = {
+        repo: session.config.repo,
+        ...(session.config.workspace === undefined ? {} : { workspace: session.config.workspace }),
+        commitSha: root.commitSha,
+        producedBy: MINT_PRODUCED_BY,
+        sourceFiles: mintFiles,
+        skippedFiles: [],
+        reachedResolution: 2,
+        nodes: [],
+        edges: mintResult.minted.map((m) => m.edge),
+        unresolved: [],
+    };
+    const mintBuilt = buildGraph([mintBatch], {
+        nodeExists: (id) => provider.node(id) !== undefined,
+    });
+    const mintPersisted = persistGraph(session.store().driver, [mintBatch], mintBuilt);
+    const stored = counts(session.store().driver);
+    if (mintResult.minted.length > 0) {
+        notes.push(`${mintResult.minted.length} human-confirmed answer(s) minted a USES_API edge this run. Every ` +
+            "one is capped at reliability class B regardless of the resolution it would otherwise earn " +
+            "(DEC-223) — a confirmed value is testimony, not a structural read.");
+        const stale = mintResult.minted.filter((m) => m.edge.attrs?.["staleFact"] === true).length;
+        if (stale > 0) {
+            notes.push(`${stale} of those edge(s) rest on an answer not affirmatively current for this commit — either ` +
+                "given against a different commit, or given before this system recorded which commit an answer " +
+                "was confirmed against. Not re-verified against live code (there is no live re-verification " +
+                "mechanism yet); disclosed on the edge's attrs.confirmedFacts[].staleness so a consumer can see " +
+                "it rather than treat an old answer as unconditionally current.");
+        }
+    }
+    if (mintResult.orphaned.length > 0) {
+        notes.push(`${mintResult.orphaned.length} confirmed answer(s) named a path/method that matches no known ` +
+            "endpoint, so no edge was minted for them — never guessed into existence: " +
+            mintResult.orphaned.map((o) => `${o.method} ${o.path}`).join(", ") +
+            ".");
+    }
+    if (mintResult.unjoinable.length > 0) {
+        notes.push(`${mintResult.unjoinable.length} confirmed answer(s) apply to a row with no resolved ` +
+            "path/method to join against at all, so no edge was minted for those either.");
+    }
+    if (mintPersisted.evictedFiles.length > 0) {
+        notes.push(`${mintPersisted.evictedFiles.length} file(s) that previously grounded a minted edge were not ` +
+            "in this run's askable set (their confirmed answer was removed, or the row it answered " +
+            "changed) — the edges they previously grounded have been retired, not left to coexist with " +
+            "whatever this run minted instead.");
+    }
+    // No code-reading source ran — R0, not a cheerful default.
+    const floor = (codeResolutions.length === 0
+        ? 0
+        : Math.min(...codeResolutions));
+    if (codeResolutions.length > 1 && new Set(codeResolutions).size > 1) {
+        notes.push(`Sources reached different resolution levels (R${Math.min(...codeResolutions)}-` +
+            `R${Math.max(...codeResolutions)}). The floor quoted here is the lowest of them, but an ` +
+            "individual answer computes its own from the edges it actually traversed, so a query " +
+            "confined to well-resolved code is not capped by the weakest source in the graph.");
+    }
+    // Report what THIS run wrote, never the store's whole cumulative total as if it
+    // were this call's own output — `stored` is every row the store holds across every
+    // past run (and, in a shared workspace, possibly other repos too), so a repo
+    // re-analysed many times would otherwise headline a number this call never touched.
+    // The cumulative total is still a genuinely useful fact, so it stays in the headline
+    // as a second, clearly-labelled clause rather than being dropped (rule 7).
+    const headline = batches.length === 0
+        ? `Nothing was read from ${session.config.repo}.`
+        : `Analysed ${session.config.repo} at ${root.commitSha.slice(0, 12)}: wrote ` +
+            `${persisted.nodesWritten} nodes, ${persisted.edgesWritten} edges, ` +
+            `${persisted.unresolvedWritten} disclosed gaps this run across ${batches.length} source(s); ` +
+            `the graph now holds ${stored.nodes} nodes, ${stored.edges} edges, ` +
+            `${stored.unresolvedRefs} disclosed gaps total.`;
+    const refusalSummary = refusalSummaryField(built.unresolved);
+    return answer({
+        headline,
+        state: batches.length === 0 ? "refused" : "ok",
+        nameLevel: true,
+        resolutionFloor: floor,
+        commitSha: root.commitSha,
+        graphBuiltAt: Date.now(),
+        irSchemaVersion: session.provider().baseStamp().irSchemaVersion,
+        commitSpread: session.provider().baseStamp().commitSpread,
+        repoCount: session.provider().baseStamp().repoCount,
+        notes,
+        ...(refusalSummary === undefined ? {} : { refusalSummary }),
+        data: {
+            repo: session.config.repo,
+            workspace: session.config.workspace ?? null,
+            commitSha: root.commitSha,
+            graphPath: session.graphPath,
+            sources: perSource,
+            sourcesFailed: registry.failed.map((f) => ({ module: f.spec.module, reason: f.reason })),
+            sourcesSkipped: skipped.map((s) => ({ source: s.source.source.id, reason: s.reason })),
+            stored,
+            merge: {
+                mergedNodes: built.mergedNodes,
+                mergedEdges: built.mergedEdges,
+                collisions: built.collisions.length,
+                droppedEdges: built.droppedEdges,
+                rejections: built.rejections.length,
+            },
+            crossRepoJoins: built.crossRepoJoins,
+            written: {
+                nodes: persisted.nodesWritten,
+                edges: persisted.edgesWritten,
+                unresolved: persisted.unresolvedWritten,
+                orphanedEdges: persisted.orphanedEdges,
+                evictedFiles: persisted.evictedFiles.length,
+            },
+            minted: {
+                edges: mintResult.minted.length,
+                orphaned: mintResult.orphaned.length,
+                unjoinable: mintResult.unjoinable.length,
+                evictedFiles: mintPersisted.evictedFiles.length,
+            },
+        },
+    });
+}
+export const analyzeTool = {
+    name: "analyze",
+    class: "stateful-read",
+    tier: "evidence",
+    version: "1.0.0",
+    title: "Analyse a repository into the code graph",
+    description: "Read the repository with every configured adapter and store the result as a code graph. " +
+        "Run this before any other Descry tool, and again after the working tree changes. Reports " +
+        "what it read, what it could not read, and the resolution level each adapter reached — the " +
+        "last one caps how strongly anything built on this graph may be stated.",
+    inputSchema: SCHEMA,
+    run,
+};
+//# sourceMappingURL=analyze.js.map