@descryy/mcp 0.6.0 → 0.7.1

package/dist/tools/analyze.d.ts

@@ -1,48 +1,15 @@
-/**
- * `analyze` — read the repository into the graph.
- *
- * The only tool that writes. Everything else queries what this produced, so its
- * disclosures are the ones that matter most: a query cannot report a gap it was
- * never told about, and this is where the gaps become known.
- *
- * ## What is disclosed, and why each one earns its line
- *
- * - **Sources that would not load.** "No problem found in your Python service"
- *   and "your Python adapter did not import" are different statements (§20.2).
- * - **Sources that loaded and did not claim the repository.** The same
- *   distinction, one level up: an unanalysed language is *not analysable*, not
- *   clean.
- * - **The resolution each source reached.** A run that degraded to R0 because a
- *   virtualenv was missing produces a graph that looks identical to a healthy
- *   one until you read this number. Principle 3 then caps everything above it.
- * - **Identity collisions.** Two things arrived under one id. There is no
- *   correct merge, so the builder reports rather than picks (DEC-024).
- * - **Evicted files.** Rows a previous run owned and this one did not re-supply.
- *   They are gone from the graph; a query over them will now find nothing, and
- *   nothing would otherwise say why.
- * - **The workspace join.** Zero cross-repo joins looks exactly like success — and, on the ordinary
- *   single-repository run every shipped call actually makes, is the *only* value possible, which is
- *   narrated too (`crossRepoJoinNote`) rather than left for a reader to infer from `repos.length`.
- *
- * ## The repo identity warning
- *
- * With no `.descry/config.json`, `repo` defaults to the directory name — and
- * every repo-scoped node id is a hash over it. Clone into a differently-named
- * folder and every id changes, which silently destroys incident links and
- * `CHANGES_WITH` weights. That is DEC-004's failure arriving through the one
- * field a default cannot get right, so it is stated on every unconfigured run.
- */
+/** `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 type { IRBatch, UnresolvedRef } from "@descryy/ir";
 import type { BuildResult, JoinMetric, StoreCounts } from "@descryy/core";
 import { type ToolDefinition } from "./kit.ts";
-import { type DescryConfig } from "../session.ts";
-/**
- * What one source read, and how well.
- *
- * `reachedResolution` is the number principle 3 caps everything above it by. A
- * run that degraded to R0 because a dependency was missing produces a graph
- * that looks identical to a healthy one until this field is read.
- */
+import { type LoadedSource } from "../registry.ts";
+export { configDriftNote } from "../session.ts";
+/** What one source read, and how well. `reachedResolution` is what rule 3 caps everything
+ *  above it by — a run degraded to R0 looks identical to a healthy one until this is read. */
 export interface SourceRun {
     readonly source: string;
     readonly files: number;
@@ -50,55 +17,34 @@ export interface SourceRun {
     readonly edges: number;
     /** Refusal-ledger rows: gaps this source disclosed rather than guessed at. */
     readonly unresolved: number;
-    /**
-     * Files this source attempted but could not parse — absent from the graph
-     * entirely, not confirmed clean. Never counted in `files`; see
-     * `IRBatch.skippedFiles`.
-     */
+    /** Files attempted but not parsed — absent from the graph, not confirmed clean. Never
+     *  counted in `files`; see `IRBatch.skippedFiles`. */
     readonly skippedFiles: number;
     readonly reachedResolution: number;
     /** Wall-clock time this source took, including the git-history reader. */
     readonly ms: number;
 }
-/**
- * The two batch fields a producer is allowed not to have heard of.
- *
- * `normaliseBatch` — every batch's gatekeeper on the way to the store — treats
- * `skippedFiles` and `unresolved` as absent-means-none, and says why in its own
- * comment: absent is what a producer not yet updated to report them sends. That
- * is a deliberate compatibility promise to adapters compiled against an older
- * `@descryy/ir`, and adapters are versioned and released on their own cadence
- * precisely so that can happen.
- *
- * This function is that promise, applied one layer earlier. `analyze` used to
- * read `.length` off both directly, which meant an adapter the Normaliser would
- * have happily accepted crashed the run before it ever got there — reported as
- * the *adapter* failing, taking a whole language into "not analysable". A real
- * shipped adapter did exactly that while returning over a thousand perfectly
- * good nodes.
- *
- * Absent and malformed stay different, which is the line the Normaliser draws
- * too: a missing field is an older producer, a field holding a string is a
- * broken one, and defaulting the second away would hide a real defect.
- */
+/** `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 declare function optionalBatchLists(batch: IRBatch): {
     readonly skippedFiles: IRBatch["skippedFiles"];
     readonly unresolved: IRBatch["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. */
 /**
- * What went wrong, and — the part that was missing — *whose* fault it was.
- *
- * The original note said "<source> failed while reading this repository" for
- * anything thrown anywhere in the loop, including inside Descry's own code
- * after the adapter had returned successfully. That is how a `TypeError` thrown
- * in this very file came to be reported as an adapter failing: a developer
- * reading it would go and debug an adapter that worked.
- *
- * The distinction is not cosmetic. "That adapter could not read this" tells a
- * user to look at their own toolchain; "Descry broke" tells them to report a
- * bug. Sending the second as the first spends the user's time on the wrong
- * thing and hides the defect from us.
+ * 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 declare function sourceProvenanceNote(entry: LoadedSource): string;
 export declare function sourceFailureNote(sourceId: string, error: unknown, phase: "emit" | "engine"): string;
 export interface AnalyzeData {
     readonly repo: string;
@@ -147,49 +93,17 @@ export interface AnalyzeData {
         readonly evictedFiles: number;
     };
 }
-/**
- * §5.4's `refusals` field, for this run only — never the graph's whole
- * stored ledger (`refusal_fetch`'s job). `built.unresolved` is what the
- * sources this call just read could not resolve, so it is a fresh
- * population every run rather than accumulated history, and honestly
- * scoped to "what this call found" the way the field's own contract asks.
- *
- * `undefined` on zero rows — the envelope's `refusals` stays `null` rather
- * than carrying a summary with no exemplar or handle to show (matching
- * `summariseRefusals`'s own `count === 0` shape one level up).
- */
+/** §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. */
 export declare function refusalSummaryField(unresolved: readonly UnresolvedRef[]): {
     readonly count: number;
     readonly exemplar: string;
     readonly handle: string;
 } | undefined;
-/**
- * `Session.config` is read once at process startup and held for the process's
- * whole life (session.ts's own header). A write tool — `link_workspace`, or a
- * hand edit — changes the file on disk without this process ever knowing, and
- * without this check the notes below would tell the agent to add a "sources"
- * array that the file has actually had since the write. Comparing the two
- * turns a misleading "still not configured" into an accurate "restart to pick
- * this up".
- */
-export declare function configDriftNote(onDisk: DescryConfig | null, loaded: DescryConfig): string | undefined;
-/**
- * The single-repo half of the joins disclosure — UAT round 3, second-look
- * item's other half.
- *
- * `build.ts`'s own `NO_CROSS_REPO_JOIN` warning (folded into `notes` just
- * above this function's call site) already narrates the alarming case: two
- * or more repositories that emitted a workspace-scoped type and none of it
- * joined. What it does not narrate is the ordinary case — every `analyze`
- * call in the shipped product passes exactly one repository's batches, so
- * every entry in `built.crossRepoJoins` has `crossRepoJoinPossible: false`
- * and `suppliedByTwoOrMoreRepos: 0` by construction, not by failure. Left
- * un-narrated, `{ total: 48, suppliedByTwoOrMoreRepos: 0 }` sitting beside a
- * disclosure about 55 unrelated within-repo edges having just succeeded
- * reads as a failure of the very thing that disclosure said worked. This
- * states outright that one repository was in scope, so a reader is not left
- * to infer it from `repos.length` themselves.
- */
+/** 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 declare function crossRepoJoinNote(joins: readonly JoinMetric[]): string | undefined;
 export declare const analyzeTool: ToolDefinition;
 //# sourceMappingURL=analyze.d.ts.map

package/dist/tools/analyze.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../../src/tools/analyze.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../../src/tools/analyze.ts"],"names":[],"mappings":"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"}

package/dist/tools/analyze.js

@@ -1,63 +1,18 @@
-/**
- * `analyze` — read the repository into the graph.
- *
- * The only tool that writes. Everything else queries what this produced, so its
- * disclosures are the ones that matter most: a query cannot report a gap it was
- * never told about, and this is where the gaps become known.
- *
- * ## What is disclosed, and why each one earns its line
- *
- * - **Sources that would not load.** "No problem found in your Python service"
- *   and "your Python adapter did not import" are different statements (§20.2).
- * - **Sources that loaded and did not claim the repository.** The same
- *   distinction, one level up: an unanalysed language is *not analysable*, not
- *   clean.
- * - **The resolution each source reached.** A run that degraded to R0 because a
- *   virtualenv was missing produces a graph that looks identical to a healthy
- *   one until you read this number. Principle 3 then caps everything above it.
- * - **Identity collisions.** Two things arrived under one id. There is no
- *   correct merge, so the builder reports rather than picks (DEC-024).
- * - **Evicted files.** Rows a previous run owned and this one did not re-supply.
- *   They are gone from the graph; a query over them will now find nothing, and
- *   nothing would otherwise say why.
- * - **The workspace join.** Zero cross-repo joins looks exactly like success — and, on the ordinary
- *   single-repository run every shipped call actually makes, is the *only* value possible, which is
- *   narrated too (`crossRepoJoinNote`) rather than left for a reader to infer from `repos.length`.
- *
- * ## The repo identity warning
- *
- * With no `.descry/config.json`, `repo` defaults to the directory name — and
- * every repo-scoped node id is a hash over it. Clone into a differently-named
- * folder and every id changes, which silently destroys incident links and
- * `CHANGES_WITH` weights. That is DEC-004's failure arriving through the one
- * field a default cannot get right, so it is stated on every unconfigured run.
- */
-import { existsSync } from "node:fs";
+/** `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 { applyConfirmedFacts, buildGraph, counts, createConfirmedIncidentSource, createGitSource, mintEdgesFromConfirmedFacts, MINT_PRODUCED_BY, persistGraph, summariseRefusals, } from "@descryy/core";
 import { answer, ToolInputError } from "./kit.js";
 import { detectSources, loadSources } from "../registry.js";
-import { loadConfig } from "../session.js";
-/**
- * The two batch fields a producer is allowed not to have heard of.
- *
- * `normaliseBatch` — every batch's gatekeeper on the way to the store — treats
- * `skippedFiles` and `unresolved` as absent-means-none, and says why in its own
- * comment: absent is what a producer not yet updated to report them sends. That
- * is a deliberate compatibility promise to adapters compiled against an older
- * `@descryy/ir`, and adapters are versioned and released on their own cadence
- * precisely so that can happen.
- *
- * This function is that promise, applied one layer earlier. `analyze` used to
- * read `.length` off both directly, which meant an adapter the Normaliser would
- * have happily accepted crashed the run before it ever got there — reported as
- * the *adapter* failing, taking a whole language into "not analysable". A real
- * shipped adapter did exactly that while returning over a thousand perfectly
- * good nodes.
- *
- * Absent and malformed stay different, which is the line the Normaliser draws
- * too: a missing field is an older producer, a field holding a string is a
- * broken one, and defaulting the second away would hide a real defect.
- */
+// 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)
@@ -72,20 +27,26 @@ export function optionalBatchLists(batch) {
         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. */
 /**
- * What went wrong, and — the part that was missing — *whose* fault it was.
- *
- * The original note said "<source> failed while reading this repository" for
- * anything thrown anywhere in the loop, including inside Descry's own code
- * after the adapter had returned successfully. That is how a `TypeError` thrown
- * in this very file came to be reported as an adapter failing: a developer
- * reading it would go and debug an adapter that worked.
- *
- * The distinction is not cosmetic. "That adapter could not read this" tells a
- * user to look at their own toolchain; "Descry broke" tells them to report a
- * bug. Sending the second as the first spends the user's time on the wrong
- * thing and hides the defect from us.
+ * 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)";
+    return `${entry.source.id} — ${entry.spec.module}@${version}, ${location}.`;
+}
 export function sourceFailureNote(sourceId, error, phase) {
     const message = error instanceof Error ? error.message : String(error);
     return phase === "emit"
@@ -112,63 +73,18 @@ const SCHEMA = {
     },
     additionalProperties: false,
 };
-/**
- * §5.4's `refusals` field, for this run only — never the graph's whole
- * stored ledger (`refusal_fetch`'s job). `built.unresolved` is what the
- * sources this call just read could not resolve, so it is a fresh
- * population every run rather than accumulated history, and honestly
- * scoped to "what this call found" the way the field's own contract asks.
- *
- * `undefined` on zero rows — the envelope's `refusals` stays `null` rather
- * than carrying a summary with no exemplar or handle to show (matching
- * `summariseRefusals`'s own `count === 0` shape one level up).
- */
+/** §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. */
 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 };
 }
-/**
- * `Session.config` is read once at process startup and held for the process's
- * whole life (session.ts's own header). A write tool — `link_workspace`, or a
- * hand edit — changes the file on disk without this process ever knowing, and
- * without this check the notes below would tell the agent to add a "sources"
- * array that the file has actually had since the write. Comparing the two
- * turns a misleading "still not configured" into an accurate "restart to pick
- * this up".
- */
-export function configDriftNote(onDisk, loaded) {
-    if (onDisk === null)
-        return undefined;
-    const changed = onDisk.configPath !== loaded.configPath ||
-        onDisk.workspace !== loaded.workspace ||
-        onDisk.sources.length !== loaded.sources.length;
-    if (!changed)
-        return undefined;
-    return ("The on-disk .descry/config.json no longer matches what this server loaded at startup. " +
-        "Configuration is read once per process, not on every call (session.ts) — this run is still " +
-        "using the configuration this server started with, not the current file. Restart the MCP " +
-        "server for on-disk changes to take effect; the notes below describe the stale, running " +
-        "configuration, not what is actually on disk now.");
-}
-/**
- * The single-repo half of the joins disclosure — UAT round 3, second-look
- * item's other half.
- *
- * `build.ts`'s own `NO_CROSS_REPO_JOIN` warning (folded into `notes` just
- * above this function's call site) already narrates the alarming case: two
- * or more repositories that emitted a workspace-scoped type and none of it
- * joined. What it does not narrate is the ordinary case — every `analyze`
- * call in the shipped product passes exactly one repository's batches, so
- * every entry in `built.crossRepoJoins` has `crossRepoJoinPossible: false`
- * and `suppliedByTwoOrMoreRepos: 0` by construction, not by failure. Left
- * un-narrated, `{ total: 48, suppliedByTwoOrMoreRepos: 0 }` sitting beside a
- * disclosure about 55 unrelated within-repo edges having just succeeded
- * reads as a failure of the very thing that disclosure said worked. This
- * states outright that one repository was in scope, so a reader is not left
- * to infer it from `repos.length` themselves.
- */
+/** 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)
@@ -188,21 +104,16 @@ async function run(args, ctx) {
     }
     const root = await session.root();
     const notes = [];
-    // MK-4: analyze is about to rebuild the graph from source regardless, so a
-    // stale IR schema version is repaired here rather than left to refuse —
-    // see Session.repairStaleGraph's own doc for why only this tool does this.
+    // 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.");
     }
-    if (existsSync(session.repoPath)) {
-        const onDisk = await loadConfig(session.repoPath).catch(() => null);
-        const drift = configDriftNote(onDisk, session.config);
-        if (drift !== undefined)
-            notes.push(drift);
-    }
+    // 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 ` +
@@ -222,12 +133,13 @@ async function run(args, ctx) {
         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, deliberately, and the boundary lint
-        // enforces it. Naming one would make this engine know about a specific
-        // language — the exact inversion `registry.ts` exists to prevent — and the
-        // list of installed adapters is not something this process can see.
+        // 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 " +
@@ -246,30 +158,17 @@ async function run(args, ctx) {
     };
     const batches = [];
     const perSource = [];
-    /**
-     * Resolution levels reached by sources that read **source code**.
-     *
-     * The floor is drawn from these alone, and the git-history reader is why. It
-     * reaches R0 and always will: R0 is what reading a commit log *is*, not a
-     * degradation of it. Folding it into a single graph-wide minimum pinned every
-     * analyse reply at R0 and therefore at reliability class C — which then
-     * described a set of directly counted rows as "a behavioural prediction".
-     *
-     * DEC-058 already settled the general form of this: an edge carries the
-     * resolution of *its own evidence*, not of the run, so a graph has no single
-     * floor and each answer computes its own. This is that rule applied one level
-     * up. Every source's level is still reported individually in `sources`, and a
-     * source that fell short of its own declared ceiling is disclosed separately.
-     */
+    /** 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;
     for (const entry of applicable) {
         ctx.progress(`Reading ${entry.source.id}`, done, total);
         const started = Date.now();
-        // The adapter's own work and Descry's handling of its result are separate
-        // phases with separate blame. Folding them into one `try` is what let a
-        // TypeError in the lines below be reported as the adapter failing.
+        // 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 {
             batch = await entry.source.emit(context);
@@ -293,9 +192,8 @@ async function run(args, ctx) {
                 reachedResolution: batch.reachedResolution,
                 ms: Date.now() - started,
             });
-            // The declared ceiling versus what this run actually reached. A gap is the
-            // honest-degradation case: the adapter can do better and something in this
-            // repository stopped it.
+            // 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);
@@ -315,15 +213,12 @@ async function run(args, ctx) {
             }
         }
         catch (error) {
-            // Reached only when Descry's own handling threw. The adapter already
-            // returned, so blaming it here would send the user to debug working code.
+            // 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 an `IRSource` one — a
-            // language server is a long-lived child process and leaking one costs
-            // hundreds of megabytes per repo. Sources with no processes to release
-            // (the git reader) have no method and need none.
+            // `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;
         }
@@ -359,13 +254,9 @@ async function run(args, ctx) {
         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 on every analyze.
-    //
-    // The record lives in `.descry/config.json` because it is testimony that
-    // exists nowhere else (DEC-223's storage decision); the graph holds a
-    // projection. Re-emitting it here is what makes "a rebuild never loses it"
-    // true rather than merely intended — a store is derived data and every
-    // derived table is dropped on a schema bump.
+    // 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({
@@ -424,11 +315,9 @@ async function run(args, ctx) {
     }
     // --- mint edges from confirmed facts --------------------------------------
     //
-    // DEC-223's answer half, minting side (DEC-138) — sequenced after the base
-    // graph above is already persisted, because a confirmed answer joins
-    // against a real, stored `API_ENDPOINT` row: `EndpointLookup.node(id)` is
-    // backed by the SQL reader, not by `built`'s in-memory result, so the
-    // endpoint has to already exist as a row for the lookup to find it.
+    // 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();
@@ -438,18 +327,9 @@ async function run(args, ctx) {
         ...(session.config.workspace === undefined ? {} : { workspace: session.config.workspace }),
     };
     const mintResult = mintEdgesFromConfirmedFacts(answered, provider, scope, MINT_PRODUCED_BY, root.commitSha);
-    // The invalidation key (DEC-015: "producedBy + sourceFiles"). Scoped to
-    // every file carrying an *askable* ("value-unknown") row this run, not
-    // only the files a fact happened to answer. That distinction is what makes
-    // a re-run after a changed or removed answer safe: the run id is derived
-    // from (producedBy, repo, commitSha, sourceFiles), so a re-run at the same
-    // commit with the same askable domain lands on the *same* run id, and the
-    // writer's own self-clean pass (`writer.ts` rule 3) retires whatever this
-    // run no longer supplies — the edge from a superseded answer does not
-    // survive next to a new one. Scoping to the *answered* subset instead
-    // would let a file drop out of `sourceFiles` the moment its one answer was
-    // removed, and a stale edge for it would then never be found as a
-    // prior-run to retire at all.
+    // 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();
@@ -499,8 +379,7 @@ async function run(args, ctx) {
             "changed) — the edges they previously grounded have been retired, not left to coexist with " +
             "whatever this run minted instead.");
     }
-    // No code-reading source ran, so there is no level to report and nothing to
-    // rest a claim on. R0 rather than a cheerful default.
+    // No code-reading source ran — R0, not a cheerful default.
     const floor = (codeResolutions.length === 0
         ? 0
         : Math.min(...codeResolutions));