@descryy/mcp 0.5.0 → 0.7.0

package/dist/tools/similar-incidents.d.ts

@@ -1,68 +1,8 @@
-/**
- * `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.
- */
+/** `similar_incidents` ranks existing `INCIDENT` nodes against a failure with no graph node yet,
+ *  deterministically (file/token Jaccard, no vector store). DEC-274 found zero `INCIDENT` nodes
+ *  across three repos (734/459/203 commits): recall is 0/0, not 0% — an empty result never means
+ *  "no similar incident exists" (DEC-279). §1.3a: a zero-incident graph is `refused`, never `empty`
+ *  — the same split `contracts` and `propagation` apply to their own zero-population case. */
 import { type SimilarIncidentSignalKind } from "@descryy/core";
 import { type BriefNode, type ToolDefinition } from "./kit.ts";
 /** One signal that fired for a candidate — the "why", never a bare score. */
@@ -75,32 +15,17 @@ export interface SimilarIncidentReport {
     readonly incident: BriefNode;
     /** The `FIX_PATTERN` this incident resolved to, when a `FIXED_BY` edge exists. */
     readonly fix: BriefNode | null;
-    /**
-     * How this incident came to exist — the `INCIDENT` node's own
-     * `attrs.detectedVia`.
-     *
-     * Reported per match rather than folded away, because the mechanisms are not
-     * interchangeable and a ranked list that hides the difference is not
-     * reportable. `explicit-revert` and `manual-revert` rest on a revert somebody
-     * wrote; `issue-reference` on a developer's `Fixes #123`; `runtime-observed`
-     * on a process that really died; `developer-confirmed` on a person saying so,
-     * which is testimony and capped at reliability class B by DEC-223 wherever it
-     * is used. `null` for an incident minted before this field existed.
-     */
+    /** How this incident was detected (`attrs.detectedVia`) — reported per match since the
+     *  mechanisms differ: revert, `Fixes #123`, a process dying at runtime, or `developer-confirmed`
+     *  testimony (capped at reliability B, DEC-223). `null` for incidents minted before this field. */
     readonly detectedVia: string | null;
     readonly signals: readonly SimilarIncidentSignalReport[];
     /** Weighted combination of every signal the query attempted, 0..1. */
     readonly score: number;
 }
-/**
- * One shape, both branches.
- *
- * `analysed: false` with `incidentsInGraph: 0` is the zero-denominator case
- * and arrives with `state: "refused"`; every other reply is `ok`.
- * The two counts are in the payload rather than only in the prose because a
- * caller deciding what to say about an empty list needs the denominator, and
- * a sentence it has to parse is not a denominator.
- */
+/** One shape, both branches: `analysed: false` with `incidentsInGraph: 0` is the zero-denominator
+ *  case, `state: "refused"`. Counts live in the payload, not just prose, so a caller can read the
+ *  denominator without parsing a sentence. */
 export interface SimilarIncidentsData {
     readonly query: {
         readonly touchedFiles: readonly string[];

package/dist/tools/similar-incidents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"similar-incidents.d.ts","sourceRoot":"","sources":["../../src/tools/similar-incidents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AAEH,OAAO,EAAoB,KAAK,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAEjF,OAAO,EAOL,KAAK,SAAS,EAEd,KAAK,cAAc,EACpB,MAAM,UAAU,CAAC;AAiClB,6EAA6E;AAC7E,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,IAAI,EAAE,yBAAyB,CAAC;IACzC,sDAAsD;IACtD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;IAC7B,kFAAkF;IAClF,QAAQ,CAAC,GAAG,EAAE,SAAS,GAAG,IAAI,CAAC;IAC/B;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,SAAS,2BAA2B,EAAE,CAAC;IACzD,sEAAsE;IACtE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;QACzC,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;KACtC,CAAC;IACF,QAAQ,CAAC,OAAO,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACnD,2DAA2D;IAC3D,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,8FAA8F;IAC9F,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AA6JD,eAAO,MAAM,oBAAoB,EAAE,cAqBlC,CAAC"}
+{"version":3,"file":"similar-incidents.d.ts","sourceRoot":"","sources":["../../src/tools/similar-incidents.ts"],"names":[],"mappings":"AAAA;;;;8FAI8F;AAE9F,OAAO,EAAoB,KAAK,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAEjF,OAAO,EAOL,KAAK,SAAS,EAEd,KAAK,cAAc,EACpB,MAAM,UAAU,CAAC;AAiClB,6EAA6E;AAC7E,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,IAAI,EAAE,yBAAyB,CAAC;IACzC,sDAAsD;IACtD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;IAC7B,kFAAkF;IAClF,QAAQ,CAAC,GAAG,EAAE,SAAS,GAAG,IAAI,CAAC;IAC/B;;uGAEmG;IACnG,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,SAAS,2BAA2B,EAAE,CAAC;IACzD,sEAAsE;IACtE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;8CAE8C;AAC9C,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;QACzC,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;KACtC,CAAC;IACF,QAAQ,CAAC,OAAO,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACnD,2DAA2D;IAC3D,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,8FAA8F;IAC9F,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAyJD,eAAO,MAAM,oBAAoB,EAAE,cAqBlC,CAAC"}

package/dist/tools/similar-incidents.js

@@ -1,68 +1,8 @@
-/**
- * `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.
- */
+/** `similar_incidents` ranks existing `INCIDENT` nodes against a failure with no graph node yet,
+ *  deterministically (file/token Jaccard, no vector store). DEC-274 found zero `INCIDENT` nodes
+ *  across three repos (734/459/203 commits): recall is 0/0, not 0% — an empty result never means
+ *  "no similar incident exists" (DEC-279). §1.3a: a zero-incident graph is `refused`, never `empty`
+ *  — the same split `contracts` and `propagation` apply to their own zero-population case. */
 import { similarIncidents } from "@descryy/core";
 import { answer, briefNode, optionalInteger, optionalString, optionalStringArray, ToolInputError, } from "./kit.js";
 const SCHEMA = {
@@ -91,12 +31,8 @@ const SCHEMA = {
     },
     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.
- */
+/** The mandatory disclosure sentence, shaped per branch. Written once here rather than inline at
+ *  three return sites, so no branch can forget it. */
 function recallDisclosure(incidentsInGraph) {
     return ((incidentsInGraph === 0
         ? "This graph holds no INCIDENT node at all, so nothing was compared. "

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

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

@@ -1,39 +1,13 @@
 /**
- * `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";
+ * `validate` — §15 static validation: env/config checks.
+ * Omits a var unless its read fails-on-absence AND declaration surface is complete
+ * (18/107 wrong findings measured otherwise); refuses rather than `ok` when no reads
+ * exist. Pass `files` for NEW_READ_UNDECLARED — catches accessor-shape-independent reads. */
+import type { AttributeFinding, AttributeReport, ConfigGraph, ConfigReadSite, EnvClaim, EnvEvidence, EnvFindingKind, EnvReport, MigrationIntegrityFinding, MigrationIntegrityReport, 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.
- */
+/** One env/config finding. `claim` distinguishes `defect` (code contradiction) from
+ *  `lead` (worth a look) — conflating them caused 18/107 wrong findings on two repos. */
 export interface EnvFindingReport {
     readonly kind: EnvFindingKind;
     readonly name: string;
@@ -43,13 +17,8 @@ export interface EnvFindingReport {
     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.
- */
+/** A variable and how much of the repo depends on it (§15.3's third check feeding
+ *  the first). Only variables with a computable dependent set appear — unknown ≠ zero. */
 export interface ConfigDependencyReport {
     readonly name: string;
     /** A lower bound, never a total. */
@@ -71,13 +40,8 @@ export interface ValidateData {
     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.
-     */
+    /** False when no adapter supplied environment reads — otherwise "no missing
+     *  variables" would misstate code that was never read as clean. */
     readonly readsAvailable: boolean;
     readonly configGraph: {
         readonly counts: ConfigGraph["counts"];
@@ -98,6 +62,26 @@ export interface ValidateData {
         /** Named in plain words when `ran` is false. */
         readonly blockers: readonly string[];
     };
+    /** §"attribute read, type doesn't declare it" — always a defect (graph-provable
+     *  contradiction between two producers), never a lead. */
+    readonly attributeExistence: {
+        readonly findings: readonly AttributeFinding[];
+        readonly findingsTotal: number;
+        readonly examined: AttributeReport["examined"];
+        /** False when no READS edge onto a type-like node carried field-existence info at all. */
+        readonly ran: boolean;
+    };
+    /** §"migration outside its directory, or broken revision chain" — both always
+     *  defects, both graph-provable. */
+    readonly migrationIntegrity: {
+        readonly findings: readonly MigrationIntegrityFinding[];
+        readonly findingsTotal: number;
+        readonly examined: MigrationIntegrityReport["examined"];
+        readonly migrationsDirectory: string | null;
+        /** False when no module in the graph carried migration revision attrs. */
+        readonly ran: boolean;
+        readonly withheld: MigrationIntegrityReport["withheld"];
+    };
 }
 export declare const validateTool: ToolDefinition;
 //# sourceMappingURL=validate.d.ts.map

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

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

package/dist/tools/validate.js

@@ -1,27 +1,9 @@
 /**
- * `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";
+ * `validate` — §15 static validation: env/config checks.
+ * Omits a var unless its read fails-on-absence AND declaration surface is complete
+ * (18/107 wrong findings measured otherwise); refuses rather than `ok` when no reads
+ * exist. Pass `files` for NEW_READ_UNDECLARED — catches accessor-shape-independent reads. */
+import { buildConfigGraph, checkAttributeExistence, checkEnvironment, checkMigrationIntegrity, checkRollbackReadiness, scanConfigSurfaces, scanMigrations, } from "@descryy/core";
 import { optionalInteger, optionalStringArray } from "./kit.js";
 const SCHEMA = {
     type: "object",
@@ -30,7 +12,10 @@ const SCHEMA = {
             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.",
+                "Configuration files are always read in full, because a declaration is repository-wide. " +
+                "Also enables a second, stronger env-var rule (NEW_READ_UNDECLARED): a variable read in " +
+                "one of these files and declared nowhere is reported regardless of whether the accessor " +
+                "fails on absence, catching a case the default rule structurally cannot.",
         },
         coverageFloor: {
             type: "number",
@@ -69,22 +54,73 @@ async function run(args, ctx) {
         ...(files === undefined ? {} : { files }),
         ...(maxFindings === undefined ? {} : { maxFindings }),
     });
+    ctx.progress("Checking attribute reads against declared types");
+    const attributeExistence = checkAttributeExistence(provider, {
+        ...(files === undefined ? {} : { files }),
+        ...(maxFindings === undefined ? {} : { maxFindings }),
+    });
+    ctx.progress("Checking migration location and revision chain");
+    const migrationIntegrity = checkMigrationIntegrity(provider, {
+        ...(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 defects = report.findings.filter((f) => f.claim === "defect").length +
+        attributeExistence.data.findings.length +
+        migrationIntegrity.data.findings.length;
+    const leads = report.findings.length - report.findings.filter((f) => f.claim === "defect").length;
+    // Nothing compared at all: no config files, reads, migrations, attribute reads,
+    // or migration revisions — any one alone is a real answer, none of them is not.
+    const nothingToCheck = report.surfaces.length === 0 &&
+        !report.readsAvailable &&
+        !rollback.data.ran &&
+        !attributeExistence.data.ran &&
+        !migrationIntegrity.data.ran;
+    // A `files` scope matching zero FILE nodes means those files were never read into
+    // the graph (bad path, or unparsed) — not "read and clean". Same collapse as
+    // `contracts(paths)`, one level down.
+    const filesMatchedNothing = files !== undefined && report.reads.filesWithReads + report.reads.filesWithoutReads === 0;
+    // Leads and rollback findings are worth a look; defects are what this tool exists
+    // to catch. Never blur the two into one count (see EnvFindingReport.claim).
     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";
+    // A "Clean" verdict from a files scope matching nothing would misreport "checked,
+    // fine" when nothing was read. Only pure-Clean is downgraded — real findings from
+    // unscoped checks still surface.
+    const falseClean = filesMatchedNothing && defects === 0 && otherFindings === 0;
+    const verdict = falseClean
+        ? "not checked"
+        : defects > 0
+            ? `${defects} defect(s) found`
+            : otherFindings > 0
+                ? `No defects; ${otherFindings} lead(s)/rollback finding(s) to review`
+                : "Clean";
+    const scopeNotes = filesMatchedNothing
+        ? [
+            `0 of the ${(files ?? []).length} named file(s) matched a FILE node this graph's read side ` +
+                "considered — either the path is wrong, or the file was never read into the graph. The " +
+                "environment-read half of this report has nothing to say about them; it is not evidence " +
+                "they are clean.",
+        ]
+        : [];
+    // render.ts requires truncatedDetail whenever truncated=true. `truncated` folds 5
+    // independently-truncatable sources; shown/total cover only the 4 finding lists a
+    // maxFindings cap acts on — configGraph's own truncation stays prose-only.
+    const shown = report.findings.length +
+        rollback.data.findings.length +
+        attributeExistence.data.findings.length +
+        migrationIntegrity.data.findings.length;
+    const total = report.findingsTotal +
+        rollback.data.findingsTotal +
+        attributeExistence.data.findingsTotal +
+        migrationIntegrity.data.findingsTotal;
+    const truncated = checked.truncated ||
+        rollback.truncated ||
+        attributeExistence.truncated ||
+        migrationIntegrity.truncated ||
+        configGraph.truncated;
+    const truncatedDetail = truncated
+        ? { shown, total: Math.max(total, shown), more: null }
+        : undefined;
     return {
         result: {
             ...checked,
@@ -103,10 +139,8 @@ async function run(args, ctx) {
                 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.
+                // §15.3's third check feeds the first. Only variables with a computable
+                // dependent set are carried — unknown count is not a zero, not worth a row.
                 configGraph: {
                     counts: configGraph.data.counts,
                     importsAvailable: configGraph.data.importsAvailable,
@@ -129,29 +163,59 @@ async function run(args, ctx) {
                     ran: rollback.data.ran,
                     blockers: rollback.data.blockers,
                 },
+                attributeExistence: {
+                    findings: attributeExistence.data.findings,
+                    findingsTotal: attributeExistence.data.findingsTotal,
+                    examined: attributeExistence.data.examined,
+                    ran: attributeExistence.data.ran,
+                },
+                migrationIntegrity: {
+                    findings: migrationIntegrity.data.findings,
+                    findingsTotal: migrationIntegrity.data.findingsTotal,
+                    examined: migrationIntegrity.data.examined,
+                    migrationsDirectory: migrationIntegrity.data.migrationsDirectory,
+                    ran: migrationIntegrity.data.ran,
+                    withheld: migrationIntegrity.data.withheld,
+                },
             },
-            // 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,
+            // Every check's disclosures reach the reader — dropping one half silently
+            // is the degradation rule 7 exists to prevent.
+            notes: [
+                ...scopeNotes,
+                ...checked.notes,
+                ...rollback.notes,
+                ...attributeExistence.notes,
+                ...migrationIntegrity.notes,
+                ...configGraph.notes,
+            ],
+            truncated,
             stamp: {
                 ...checked.stamp,
-                resolutionFloor: Math.min(checked.stamp.resolutionFloor, rollback.stamp.resolutionFloor, configGraph.stamp.resolutionFloor),
+                resolutionFloor: Math.min(checked.stamp.resolutionFloor, rollback.stamp.resolutionFloor, attributeExistence.stamp.resolutionFloor, migrationIntegrity.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.
+        // §11A.5's canonical name-level fact (exists or not) — the one claim R2 supports
+        // at class A. Value shape is never asserted here.
         nameLevel: true,
-        ...(nothingToCheck ? { state: "refused" } : {}),
+        ...(truncatedDetail === undefined ? {} : { truncatedDetail }),
+        ...(nothingToCheck
+            ? { state: "refused" }
+            : falseClean
+                ? { state: "empty" }
+                : {}),
         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.`,
+            ? "No configuration files, environment reads, migrations or attribute reads were found, so " +
+                "there was nothing to check."
+            : falseClean
+                ? `0 of the ${(files ?? []).length} named file(s) matched anything on the read side. Not ` +
+                    "checked, not clean."
+                : `${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; ` +
+                    `${attributeExistence.data.examined.readEdgesExamined} attribute read(s) checked against ` +
+                    `a declared type; ${migrationIntegrity.data.examined.modulesWithRevision} migration(s) ` +
+                    "checked for location and revision-chain integrity.",
     };
 }
 function countDeclared(surfaces) {
@@ -167,9 +231,17 @@ export const validateTool = {
         "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.",
+        "manager or a platform is disclosed with a count, never reported as missing. Pass \"files\" " +
+        "(the diff you are about to push) to also catch a variable your change reads that no " +
+        "declaration surface declares, regardless of whether the accessor fails on absence — the " +
+        "usual shape on a codebase where almost no read is required. Also reports variables set in " +
+        "one configuration file and documented in no example file, stated as a lead rather than a " +
+        "defect. Two further checks, both always defects because both are provable from the graph " +
+        "alone: an attribute read on a value whose declared type does not name it (from a READS " +
+        "edge's attrs.unresolvedFields), and a migration whose location or declared parent revision " +
+        "disagrees with the rest of the project's migrations (from attrs.migrationRevision, " +
+        "migrationDownRevision and migrationDir). Both are silent wherever the producer supplied no " +
+        "signal — absence of the attrs key is never read as a clean result.",
     inputSchema: SCHEMA,
     run,
 };