@descryy/mcp 0.1.0

package/dist/tools/similar-incidents.js

@@ -0,0 +1,228 @@
+/**
+ * `similar_incidents` — "have we seen this failure before?", asked about a
+ * failure that is **not yet in the graph**.
+ *
+ * ## Why this is a separate tool from `impact`'s `related` field
+ *
+ * `rootCauseSearch` — the `related` list every `impact` reply carries — walks
+ * `INCIDENT_CORRELATED`/`FIXED_BY` edges out of a node that already exists.
+ * It cannot help with a failure observed a moment ago: a stack trace and a set
+ * of touched files have no node, so there is nothing to walk from. This tool
+ * is the other direction. It takes the failure as a description and ranks the
+ * `INCIDENT` nodes the graph already holds against it, using the two signals
+ * `similarIncidents` (`@descryy/core`, DEC-274 step 2) computes from data the
+ * graph already has: file-set Jaccard over `INCIDENT_CORRELATED`, and
+ * token-set Jaccard over the incident's own text. Deterministic, no vector
+ * store, no model call.
+ *
+ * ## The disclosure this tool exists to carry, and it is not optional
+ *
+ * DEC-279 makes one sentence mandatory here, and DEC-274 is why. That
+ * measurement ran the correlation machinery over `descry-core`,
+ * `descry-runtime` and `descry-adapters` — 734, 459 and 203 commits — and
+ * found **zero `INCIDENT` nodes in all three**. Not few: zero. Only an
+ * explicit `git revert` mints an `INCIDENT` today; a fix-forward commit, which
+ * is how almost every real bug is actually fixed, mints nothing at all.
+ *
+ * So this matcher's **recall is not computable — 0/0, not 0%**. It has never
+ * been handed a real incident to find, and no number describes how many it
+ * would miss. An empty result therefore means *"no linked incident in this
+ * graph, and this graph has few or no incidents"* and must never be read as
+ * *"no similar incident exists."* That is the same *absence is not evidence*
+ * obligation `impact` already carries on every reply, and `similar-incidents.test.ts`
+ * fails if it goes missing from either the empty or the non-empty branch.
+ *
+ * ## Two different absences, and they are not the same result
+ *
+ * `ai-tool-contract.md` §1.3a splits them, and the split is the whole reason
+ * this endpoint is interesting:
+ *
+ * - **Incidents exist and none matched.** The denominator is real, the tool
+ *   looked completely, and the absence is a fact about the code. `state:
+ *   "empty"`, per §1.1's split.
+ * - **The graph holds zero `INCIDENT` nodes.** There is no denominator.
+ *   Nothing was looked at, and the reason is Descry's producer coverage
+ *   rather than anything about this repository: only `git revert` mints an
+ *   `INCIDENT` and fix-forward mints nothing. Answering "empty" there would
+ *   say *"this code has no similar incidents"* when the true statement is
+ *   *"Descry cannot see most incidents in any codebase"* — the
+ *   empty-denominator defect inside the endpoint written to demonstrate the
+ *   rule against it. So it is a refusal, carried as `state: "refused"` (§1.1:
+ *   `refused` is a result state, and `not analysable` is a report category —
+ *   different axes, never this).
+ *
+ * §1.3a generalises it past this tool: **when a query's population is itself
+ * zero, the answer is a refusal, never an empty result.** That puts this in
+ * line with its siblings rather than apart from them — `contracts` refuses on
+ * a graph with no endpoint, `propagation` when no walked edge type touches
+ * the start node.
+ *
+ * The denominator travels in the payload either way. `incidentsInGraph` is
+ * the population and `analysed` is false only when it is zero, so a caller
+ * can tell the two absences apart **from the payload alone, with no string
+ * matching on prose** — §1's distinguishability requirement, satisfied
+ * without waiting for the wider envelope.
+ */
+import { similarIncidents } from "@descryy/core";
+import { answer, briefNode, optionalInteger, optionalString, optionalStringArray, ToolInputError, } from "./kit.js";
+const SCHEMA = {
+    type: "object",
+    properties: {
+        touchedFiles: {
+            type: "array",
+            items: { type: "string" },
+            description: "Repository-relative paths the failure touched — from a stack trace, a failing test's " +
+                "imports, or the diff being investigated. Matched against each incident's own correlated " +
+                "file set.",
+        },
+        errorMessage: {
+            type: "string",
+            description: "The failure's error or exception text. Matched against each incident's text, which today " +
+                "is always a commit subject line — real signal, but thin.",
+        },
+        minScore: {
+            type: "number",
+            minimum: 0,
+            maximum: 1,
+            description: "Drop candidates scoring below this. Default 0, meaning any signal that fired at all is " +
+                "returned — ranked, so a weak match is visible as a weak match rather than hidden.",
+        },
+        limit: { type: "integer", minimum: 1, description: "Cap on matches in the reply. Default 20." },
+    },
+    additionalProperties: false,
+};
+/**
+ * The mandatory sentence, in the form that fits each branch.
+ *
+ * Written once here rather than inline at three return sites, because the one
+ * failure mode this tool has is a branch that forgets it.
+ */
+function recallDisclosure(incidentsInGraph) {
+    return ((incidentsInGraph === 0
+        ? "This graph holds no INCIDENT node at all, so nothing was compared. "
+        : `${incidentsInGraph} INCIDENT node(s) were available to compare against. `) +
+        "Absence is not evidence here, and the reason is measured rather than assumed: only an " +
+        "explicit git revert mints an INCIDENT, and a fix-forward commit — how almost every real bug " +
+        "is actually fixed — mints nothing. DEC-274 found zero INCIDENT nodes across three real " +
+        "repositories of 734, 459 and 203 commits. This matcher's recall is therefore not computable " +
+        "(0/0), not 0%: it has never been given a real incident to find. A failure this repository " +
+        "has genuinely hit before can be absent from these results entirely.");
+}
+async function run(args, ctx) {
+    const touchedFiles = optionalStringArray(args, "touchedFiles") ?? [];
+    const errorMessage = optionalString(args, "errorMessage");
+    const limit = optionalInteger(args, "limit", 1) ?? 20;
+    const rawMinScore = args["minScore"];
+    if (rawMinScore !== undefined && rawMinScore !== null) {
+        if (typeof rawMinScore !== "number" || rawMinScore < 0 || rawMinScore > 1) {
+            throw new ToolInputError('"minScore" must be a number between 0 and 1');
+        }
+    }
+    const minScore = typeof rawMinScore === "number" ? rawMinScore : undefined;
+    // Describing nothing and being told "0 matches" is the empty-denominator
+    // defect at the input side: the reply would be indistinguishable from a real
+    // search that found nothing.
+    if (touchedFiles.length === 0 && (errorMessage === undefined || errorMessage === "")) {
+        throw new ToolInputError('give at least one of "touchedFiles" or "errorMessage" — with neither, there is nothing to ' +
+            "compare an incident against, and an empty answer would look like a search that ran");
+    }
+    const provider = ctx.session.provider();
+    // The population, read for its own sake. `similarIncidents` scans the same
+    // set internally but returns only what matched, and the count of what did
+    // *not* match is the number this tool's honesty rests on.
+    ctx.progress("Reading the incident population");
+    const population = provider.nodesOfType("INCIDENT");
+    const incidentsInGraph = population.nodes.length;
+    const base = provider.baseStamp();
+    if (incidentsInGraph === 0) {
+        return answer({
+            headline: "No incident is recorded in this graph, so nothing was compared against the failure you " +
+                "described. This is not a finding that the failure is new.",
+            // A refusal, not an empty result — §1.3a. `not_analysable` is the value
+            // today's envelope has for it; §1.1 renames it `refused` in P2.
+            state: "refused",
+            // Whether an incident resembles a failure is a claim about names and
+            // paths, not about shapes — the same class as `history`'s co-change
+            // rows. R0 is the honest floor: an INCIDENT is minted from a commit
+            // log, which is R0 by nature rather than by degradation.
+            nameLevel: true,
+            resolutionFloor: 0,
+            commitSha: base.commitSha,
+            graphBuiltAt: base.graphBuiltAt,
+            irSchemaVersion: base.irSchemaVersion,
+            notes: [recallDisclosure(0)],
+            data: {
+                query: { touchedFiles, errorMessage: errorMessage ?? null },
+                matches: [],
+                matchesTotal: 0,
+                incidentsInGraph: 0,
+                analysed: false,
+            },
+        });
+    }
+    ctx.progress(`Ranking ${incidentsInGraph} incident(s) against the failure`);
+    const ranked = similarIncidents(provider, {
+        ...(touchedFiles.length === 0 ? {} : { touchedFiles }),
+        ...(errorMessage === undefined ? {} : { errorMessage }),
+    }, { ...(minScore === undefined ? {} : { minScore }) });
+    const shown = ranked.data.slice(0, limit);
+    const notes = [...ranked.notes, recallDisclosure(incidentsInGraph)];
+    if (shown.length < ranked.data.length) {
+        notes.push(`${ranked.data.length - shown.length} further match(es) scored above the threshold but are ` +
+            `not listed — the reply is capped at ${limit}.`);
+    }
+    if (population.truncated) {
+        notes.push("The incident read was capped, so some INCIDENT nodes were never scored. The counts here " +
+            "are a lower bound.");
+    }
+    return {
+        result: {
+            data: {
+                query: { touchedFiles, errorMessage: errorMessage ?? null },
+                matches: shown.map((match) => ({
+                    incident: briefNode(match.incident),
+                    fix: match.fix === null ? null : briefNode(match.fix),
+                    signals: match.signals.map((s) => ({ kind: s.kind, score: Number(s.score.toFixed(4)) })),
+                    score: Number(match.combinedScore.toFixed(4)),
+                })),
+                matchesTotal: ranked.data.length,
+                incidentsInGraph,
+                analysed: true,
+            },
+            stamp: ranked.stamp,
+            truncated: ranked.truncated || shown.length < ranked.data.length || population.truncated,
+            notes,
+        },
+        ...(ranked.data.length === 0 ? { state: "empty" } : {}),
+        ...(shown.length < ranked.data.length
+            ? { truncatedDetail: { shown: shown.length, total: ranked.data.length, more: null } }
+            : {}),
+        nameLevel: true,
+        headline: ranked.data.length === 0
+            ? `None of the ${incidentsInGraph} incident(s) in this graph share a file or a phrase with ` +
+                "the failure you described. That is a statement about this graph's incident record, not " +
+                "about the failure."
+            : `${ranked.data.length} of ${incidentsInGraph} recorded incident(s) resemble this failure; ` +
+                `closest: ${shown[0].incident.name}` +
+                `${shown[0].fix === null ? "" : ` (fixed by: ${shown[0].fix.name})`}.`,
+    };
+}
+export const similarIncidentsTool = {
+    name: "similar_incidents",
+    class: "read",
+    tier: "evidence",
+    version: "1.0.0",
+    title: "Past incidents that resemble a failure happening now",
+    description: "Given the files a failure touched and/or its error text, rank the incidents already recorded " +
+        "in the graph by how much they resemble it, and name which signal fired for each — file " +
+        "overlap, message similarity, or both. Use this for a failure that has no graph node yet (a " +
+        "stack trace, a red test); use \"impact\" instead for incidents linked to a symbol that " +
+        "already exists. Deterministic graph and text matching only; no embedding search runs. Two " +
+        "absences and they are different answers: an empty result means this graph's recorded " +
+        "incidents were compared and none matched, while a refusal means the graph holds no incident " +
+        "at all — common, because only an explicit git revert mints one and a fix-forward commit " +
+        "mints nothing. Neither is evidence that the failure is new.",
+    inputSchema: SCHEMA,
+    run,
+};
+//# sourceMappingURL=similar-incidents.js.map

package/dist/tools/similar-incidents.js.map

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

package/dist/tools/validate.d.ts

@@ -0,0 +1,103 @@
+/**
+ * `validate` — §15's static validation engine, currently its env/config check.
+ *
+ * The architecture calls this one *"cheapest and most reliable — ship first"*,
+ * and it is the first tool here whose output is a statement about the user's
+ * code rather than a measurement of the graph.
+ *
+ * ## Two things this tool refuses to do, and both are the point
+ *
+ * 1. **It does not report a variable that is read and never declared, by
+ *    default.** Measured on two real repositories, that rule produces 18 wrong
+ *    findings on one and 107 on the other. A finding needs a read that asserts
+ *    *requirement* — no fallback at the read site — and a declaration surface
+ *    complete enough for an absence to mean something. See `validation/env.ts`.
+ *
+ * 2. **It does not return `ok` with an empty list when no adapter supplied
+ *    reads.** That is `refused` with the reason and the exact `attrs` key
+ *    it needs, because "no missing variables" is a false statement when the code
+ *    was never read.
+ *
+ * The declaration half runs regardless: configuration files are read straight
+ * from the repository, which needs no adapter and no resolution.
+ */
+import type { ConfigGraph, ConfigReadSite, EnvClaim, EnvEvidence, EnvFindingKind, EnvReport, RollbackFinding, RollbackReport } from "@descryy/core";
+import type { ResolutionLevel } from "@descryy/ir";
+import { type ToolDefinition } from "./kit.ts";
+/**
+ * One environment/configuration finding.
+ *
+ * `claim` is the axis that matters: a `defect` is a statement about the code, a
+ * `lead` is something to look at. A variable read with no fallback and
+ * declared nowhere is the first; a variable set in one file and documented in
+ * no example file is the second, and reporting it as the first is how this
+ * check produced 18 and 107 wrong findings on two real repositories before the
+ * distinction existed.
+ */
+export interface EnvFindingReport {
+    readonly kind: EnvFindingKind;
+    readonly name: string;
+    readonly claim: EnvClaim;
+    readonly detail: string;
+    /** Every location the finding rests on. Never empty. */
+    readonly evidence: readonly EnvEvidence[];
+    readonly resolution: ResolutionLevel;
+}
+/**
+ * A variable and how much of the repository stands behind it.
+ *
+ * Only variables whose dependent set could actually be computed appear —
+ * §15.3's third check feeding the first. An unknown count is not a zero, so it
+ * is left out rather than reported as none.
+ */
+export interface ConfigDependencyReport {
+    readonly name: string;
+    /** A lower bound, never a total. */
+    readonly dependents: number | null;
+    /** True when the traversal's budget stopped it short. */
+    readonly truncated: boolean;
+    /** Up to three read sites. */
+    readonly readAt: readonly ConfigReadSite[];
+    /** A few dependent files, for a reader who wants to look. */
+    readonly sample: readonly string[];
+}
+export interface ValidateData {
+    readonly findings: readonly EnvFindingReport[];
+    /** The count before `maxFindings` capped it — P27's disclosed remainder (§4 technique 5). */
+    readonly findingsTotal: number;
+    readonly surfaces: EnvReport["surfaces"];
+    readonly reads: EnvReport["reads"];
+    /** Null when no read existed at all, so the coverage guard could not be evaluated. */
+    readonly coverage: EnvReport["coverage"];
+    /** Declared and read nowhere. A dead-configuration lead, not a finding. */
+    readonly declaredNeverRead: number;
+    /**
+     * False when no adapter supplied environment reads.
+     *
+     * The whole point of the field: with it false, "no missing variables" would
+     * be a statement about code that was never read, so the call is degraded
+     * rather than clean.
+     */
+    readonly readsAvailable: boolean;
+    readonly configGraph: {
+        readonly counts: ConfigGraph["counts"];
+        /** True when the graph carried at least one resolved import edge. */
+        readonly importsAvailable: boolean;
+        /** The ten most-depended-on variables that had a computable dependent set. */
+        readonly mostDependedOn: readonly ConfigDependencyReport[];
+    };
+    readonly rollback: {
+        readonly findings: readonly RollbackFinding[];
+        /** The count before `maxFindings` capped it — P27's disclosed remainder (§4 technique 5). */
+        readonly findingsTotal: number;
+        readonly examined: RollbackReport["examined"];
+        /** Operations this check declined to report, by reason. The size of what it did not say. */
+        readonly withheld: RollbackReport["withheld"];
+        /** False when no source supplied migration operations. */
+        readonly ran: boolean;
+        /** Named in plain words when `ran` is false. */
+        readonly blockers: readonly string[];
+    };
+}
+export declare const validateTool: ToolDefinition;
+//# sourceMappingURL=validate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/tools/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAUH,OAAO,KAAK,EACV,WAAW,EACX,cAAc,EACd,QAAQ,EACR,WAAW,EACX,cAAc,EACd,SAAS,EACT,eAAe,EACf,cAAc,EACf,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,OAAO,EAA0D,KAAK,cAAc,EAAE,MAAM,UAAU,CAAC;AAGvG;;;;;;;;;GASG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,CAAC;IAC1C,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;CACtC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oCAAoC;IACpC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,yDAAyD;IACzD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,8BAA8B;IAC9B,QAAQ,CAAC,MAAM,EAAE,SAAS,cAAc,EAAE,CAAC;IAC3C,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC/C,6FAA6F;IAC7F,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC,UAAU,CAAC,CAAC;IACzC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,OAAO,CAAC,CAAC;IACnC,sFAAsF;IACtF,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC,UAAU,CAAC,CAAC;IACzC,2EAA2E;IAC3E,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC;;;;;;OAMG;IACH,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,WAAW,EAAE;QACpB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAC;QACvC,qEAAqE;QACrE,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;QACnC,8EAA8E;QAC9E,QAAQ,CAAC,cAAc,EAAE,SAAS,sBAAsB,EAAE,CAAC;KAC5D,CAAC;IACF,QAAQ,CAAC,QAAQ,EAAE;QACjB,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;QAC9C,6FAA6F;QAC7F,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;QAC/B,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;QAC9C,4FAA4F;QAC5F,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;QAC9C,0DAA0D;QAC1D,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;QACtB,gDAAgD;QAChD,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;KACtC,CAAC;CACH;AA4JD,eAAO,MAAM,YAAY,EAAE,cAgB1B,CAAC"}

package/dist/tools/validate.js

@@ -0,0 +1,176 @@
+/**
+ * `validate` — §15's static validation engine, currently its env/config check.
+ *
+ * The architecture calls this one *"cheapest and most reliable — ship first"*,
+ * and it is the first tool here whose output is a statement about the user's
+ * code rather than a measurement of the graph.
+ *
+ * ## Two things this tool refuses to do, and both are the point
+ *
+ * 1. **It does not report a variable that is read and never declared, by
+ *    default.** Measured on two real repositories, that rule produces 18 wrong
+ *    findings on one and 107 on the other. A finding needs a read that asserts
+ *    *requirement* — no fallback at the read site — and a declaration surface
+ *    complete enough for an absence to mean something. See `validation/env.ts`.
+ *
+ * 2. **It does not return `ok` with an empty list when no adapter supplied
+ *    reads.** That is `refused` with the reason and the exact `attrs` key
+ *    it needs, because "no missing variables" is a false statement when the code
+ *    was never read.
+ *
+ * The declaration half runs regardless: configuration files are read straight
+ * from the repository, which needs no adapter and no resolution.
+ */
+import { buildConfigGraph, checkEnvironment, checkRollbackReadiness, scanConfigSurfaces, scanMigrations, } from "@descryy/core";
+import { optionalInteger, optionalStringArray } from "./kit.js";
+const SCHEMA = {
+    type: "object",
+    properties: {
+        files: {
+            type: "array",
+            items: { type: "string" },
+            description: "Restrict the code side to these repo-relative files — the scoped-subgraph run. " +
+                "Configuration files are always read in full, because a declaration is repository-wide.",
+        },
+        coverageFloor: {
+            type: "number",
+            minimum: 0,
+            maximum: 1,
+            description: "Fraction of required variables the repository must declare somewhere before any " +
+                "missing-variable finding is emitted. Default 0.6. Lowering it trades precision for " +
+                "recall on a repository whose configuration lives outside the code.",
+        },
+        maxFindings: {
+            type: "integer",
+            minimum: 1,
+            description: "Cap on findings returned. Default 25; overflow is disclosed, not dropped.",
+        },
+    },
+    additionalProperties: false,
+};
+async function run(args, ctx) {
+    const files = optionalStringArray(args, "files");
+    const maxFindings = optionalInteger(args, "maxFindings", 1);
+    const rawFloor = args["coverageFloor"];
+    const coverageFloor = typeof rawFloor === "number" && rawFloor >= 0 && rawFloor <= 1 ? rawFloor : undefined;
+    ctx.progress("Reading configuration files");
+    const scan = scanConfigSurfaces(ctx.session.repoPath);
+    ctx.progress("Cross-checking against environment reads in the graph");
+    const provider = ctx.session.provider();
+    const checked = checkEnvironment(provider, scan, {
+        ...(files === undefined ? {} : { files }),
+        ...(maxFindings === undefined ? {} : { maxFindings }),
+        ...(coverageFloor === undefined ? {} : { coverageFloor }),
+    });
+    ctx.progress("Tracing what depends on each configuration variable");
+    const configGraph = buildConfigGraph(provider, scan);
+    ctx.progress("Reading migrations for destructive operations");
+    const rollback = checkRollbackReadiness(provider, scanMigrations(ctx.session.repoPath), {
+        ...(files === undefined ? {} : { files }),
+        ...(maxFindings === undefined ? {} : { maxFindings }),
+    });
+    const report = checked.data;
+    const defects = report.findings.filter((f) => f.claim === "defect").length;
+    const leads = report.findings.length - defects;
+    // Nothing was compared at all: no configuration files, no reads, and no
+    // migration. Any one of them alone is a real answer; none of them is not.
+    const nothingToCheck = report.surfaces.length === 0 && !report.readsAvailable && !rollback.data.ran;
+    // MK-7: the leading clause a caller reads first, graded on the axis that
+    // actually matters — `claim`. A lead or a rollback finding is worth a look;
+    // a defect is the thing this tool exists to catch. Never blur the two into
+    // one count, the exact failure `EnvFindingReport.claim`'s own doc names.
+    const otherFindings = leads + rollback.data.findings.length;
+    const verdict = defects > 0
+        ? `${defects} defect(s) found`
+        : otherFindings > 0
+            ? `No defects; ${otherFindings} lead(s)/rollback finding(s) to review`
+            : "Clean";
+    return {
+        result: {
+            ...checked,
+            data: {
+                findings: report.findings.map((f) => ({
+                    kind: f.kind,
+                    name: f.name,
+                    claim: f.claim,
+                    detail: f.detail,
+                    evidence: f.evidence,
+                    resolution: f.resolution,
+                })),
+                findingsTotal: report.findingsTotal,
+                surfaces: report.surfaces,
+                reads: report.reads,
+                coverage: report.coverage,
+                declaredNeverRead: report.declaredNeverRead,
+                readsAvailable: report.readsAvailable,
+                // §15.3's third check feeds the first: a variable read by a module forty
+                // others import is a different sentence from one read by a single
+                // script. Only variables whose dependent set could be computed are
+                // carried — an unknown count is not a zero and is not worth a row.
+                configGraph: {
+                    counts: configGraph.data.counts,
+                    importsAvailable: configGraph.data.importsAvailable,
+                    mostDependedOn: configGraph.data.variables
+                        .filter((v) => v.dependents !== null && v.dependents > 0)
+                        .slice(0, 10)
+                        .map((v) => ({
+                        name: v.name,
+                        dependents: v.dependents,
+                        truncated: v.dependentsTruncated,
+                        readAt: v.readAt.slice(0, 3),
+                        sample: v.dependentSample,
+                    })),
+                },
+                rollback: {
+                    findings: rollback.data.findings,
+                    findingsTotal: rollback.data.findingsTotal,
+                    examined: rollback.data.examined,
+                    withheld: rollback.data.withheld,
+                    ran: rollback.data.ran,
+                    blockers: rollback.data.blockers,
+                },
+            },
+            // Both checks' disclosures reach the reader. Dropping one half's notes
+            // because the other half had something to say is the silent-degradation
+            // failure rule 7 exists to prevent.
+            notes: [...checked.notes, ...rollback.notes, ...configGraph.notes],
+            truncated: checked.truncated || rollback.truncated || configGraph.truncated,
+            stamp: {
+                ...checked.stamp,
+                resolutionFloor: Math.min(checked.stamp.resolutionFloor, rollback.stamp.resolutionFloor, configGraph.stamp.resolutionFloor),
+            },
+        },
+        // A missing environment variable is §11A.5's canonical name-level fact —
+        // the variable exists or it does not — which is the one claim R2 supports at
+        // class A. The shape of its value is never asserted here.
+        nameLevel: true,
+        ...(nothingToCheck ? { state: "refused" } : {}),
+        headline: nothingToCheck
+            ? "No configuration files, environment reads or migrations were found, so there was " +
+                "nothing to check."
+            : `${verdict}. ${report.surfaces.length} configuration file(s) declare ` +
+                `${countDeclared(report.surfaces)} variable(s); ` +
+                `${report.reads.required} variable(s) are read through an accessor that fails when unset; ` +
+                `${rollback.data.examined.operations} destructive migration operation(s) examined.`,
+    };
+}
+function countDeclared(surfaces) {
+    return surfaces.reduce((total, s) => total + s.declared, 0);
+}
+export const validateTool = {
+    name: "validate",
+    class: "read",
+    tier: "conclusion",
+    version: "1.0.0",
+    title: "Environment and configuration checks",
+    description: "Cross-check the environment variables the code requires against the ones this repository " +
+        "declares. Reports a variable only when the code reads it with no fallback and no " +
+        "configuration file declares it, and only when the repository's declaration surface is " +
+        "complete enough for that absence to mean something — a variable supplied by a secrets " +
+        "manager or a platform is disclosed with a count, never reported as missing. Also reports " +
+        "variables set in one configuration file and documented in no example file, stated as a lead " +
+        "rather than a defect.",
+    inputSchema: SCHEMA,
+    run,
+};
+//# sourceMappingURL=validate.js.map

package/dist/tools/validate.js.map

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

package/dist/tools/verification-status.d.ts

@@ -0,0 +1,68 @@
+/**
+ * `verification_status` — §4 technique 6: *"Coverage is a separate axis and
+ * a separate call. Appending it everywhere pays on every call; a tool pays
+ * once, when the client is actually reporting."*
+ *
+ * Wraps `packages/core/src/query/verification-status.ts`'s
+ * `computeVerificationStatus` — the module's own header calls itself "the
+ * static half only" and says building the `ScopeItem[]` from a caller's refs
+ * is "the caller's job, done above this boundary." This tool is that caller.
+ *
+ * ## Real capability lookup, without ever naming a language up here
+ *
+ * `computeVerificationStatus`'s `ScopeItem.capabilities`, when supplied,
+ * lets a `notExercised` reason describe a real declared gap rather than a
+ * generic absence. The first design attempted here guessed a language from
+ * a ref's file extension and matched it against a `language` tag on a
+ * configured source — and `npm run lint` caught it immediately:
+ * `descry-boundary/no-language-vocabulary` and `no-language-branch` both
+ * fired, because `packages/*\/src/**` (this file included, not just
+ * `packages/core`) is bound by architecture principle 7 — nothing above the
+ * Canonical IR may name or dispatch on a language, full stop. A hardcoded
+ * extension table and a `.get(guessedLanguage)` lookup are exactly the
+ * "lookup dispatch" shape that rule exists to catch, not a false positive.
+ *
+ * The fix moves the decision below the boundary, where it belongs:
+ * `LanguageAdapter` (`@descryy/ir`) gained an optional
+ * `ownsPath(path): boolean` — the adapter decides, using whatever
+ * language-specific logic it wants, entirely inside `descry-adapters`,
+ * which is not bound by this repo's lint. This tool never sees or compares
+ * a language string; it just asks every loaded, configured adapter "do you
+ * own this path," and attaches whichever one says yes. An unresolved ref's
+ * `language` therefore stays `null` here always — this tool does not
+ * determine one, and does not need to: `computeVerificationStatus`'s reason
+ * text already reads correctly either way (see its own module header),
+ * naming an adapter as registered without ever naming which language it is
+ * for.
+ *
+ * A configured source that fails to import cannot be asked at all — this
+ * tool's own `notes` disclose that plainly, the same register `analyze.ts`
+ * already uses for a source that will not import.
+ *
+ * ## Resolving a ref: node id first, then file
+ *
+ * A ref that is a real node id resolves directly (`getNode`). Otherwise it
+ * is tried as a file path (`findNodes({ file: ref })`, the same reader
+ * `lookup.ts`'s `resolveOneNode` already uses for symbol/file matching): the
+ * file's own `FILE`-typed node stands in when one exists, else the node
+ * with the *weakest* resolution in that file — the same "report the
+ * weakest link" convention `resolutionFloor` uses elsewhere in this
+ * package, since a file is only as verified as its least-resolved member.
+ * A ref that resolves neither way is `notExercised`.
+ */
+import type { ResolutionLevel } from "@descryy/ir";
+import { type ToolDefinition } from "./kit.ts";
+export interface VerificationStatusExercisedItem {
+    readonly ref: string;
+    readonly resolution: ResolutionLevel;
+}
+export interface VerificationStatusData {
+    readonly checked: readonly string[];
+    readonly exercised: readonly VerificationStatusExercisedItem[];
+    readonly notExercised: readonly {
+        readonly scope: string;
+        readonly reason: string;
+    }[];
+}
+export declare const verificationStatusTool: ToolDefinition;
+//# sourceMappingURL=verification-status.d.ts.map

package/dist/tools/verification-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verification-status.d.ts","sourceRoot":"","sources":["../../src/tools/verification-status.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAIH,OAAO,KAAK,EAA4B,eAAe,EAAE,MAAM,aAAa,CAAC;AAE7E,OAAO,EAKL,KAAK,cAAc,EACpB,MAAM,UAAU,CAAC;AAqBlB,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;CACtC;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,SAAS,EAAE,SAAS,+BAA+B,EAAE,CAAC;IAC/D,QAAQ,CAAC,YAAY,EAAE,SAAS;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACvF;AAoHD,eAAO,MAAM,sBAAsB,EAAE,cAgBpC,CAAC"}