@descryy/mcp 0.1.0

package/dist/tools/contracts.js

@@ -0,0 +1,141 @@
+/**
+ * `contracts` — "does the caller agree with the thing it is calling?"
+ *
+ * §13, in two halves that fail independently.
+ *
+ * **The path half runs today.** A call that reaches no route, a route nothing
+ * calls. Name-level facts, so R2 evidence supports them at class A.
+ *
+ * **The shape half needs both producers to attach something they do not attach
+ * yet**, and it names exactly what — see `engine.ts`. It reports
+ * `refused` with those names rather than an empty mismatch list, because
+ * "no contract mismatches found" is a false statement when nothing was compared.
+ *
+ * ## Why the tool is `ok` when only the path half ran
+ *
+ * The path half produced a real answer over real evidence. Marking the whole
+ * call `refused` because a second check did not run would hide a genuine
+ * finding behind a caveat about a different question. The shape half's status is
+ * carried in `data.shapes.ran` and in the blockers, where a reader can act on it.
+ *
+ * The one case that *is* `refused` outright: no endpoints in the graph.
+ * Then neither half looked at anything.
+ */
+import { checkContracts } from "@descryy/core";
+import { briefNode, optionalInteger, optionalStringArray, } from "./kit.js";
+const SCHEMA = {
+    type: "object",
+    properties: {
+        paths: {
+            type: "array",
+            items: { type: "string" },
+            description: "Restrict the report to endpoints whose normalised path template contains one of these " +
+                "substrings, e.g. \"/orders\".",
+        },
+        pathsOnly: {
+            type: "boolean",
+            description: "Skip the shape comparison. Faster, and the honest choice for a pre-push run on a graph " +
+                "with no type checker behind it.",
+        },
+        maxFindings: {
+            type: "integer",
+            minimum: 1,
+            description: "Cap on path findings returned. Default 25; overflow is disclosed, not dropped.",
+        },
+    },
+    additionalProperties: false,
+};
+async function run(args, ctx) {
+    const filters = optionalStringArray(args, "paths");
+    const maxFindings = optionalInteger(args, "maxFindings", 1);
+    const pathsOnly = args["pathsOnly"] === true;
+    ctx.progress("Matching callers against routes");
+    const checked = checkContracts(ctx.session.provider(), {
+        ...(maxFindings === undefined ? {} : { maxFindings }),
+        ...(pathsOnly ? { pathsOnly: true } : {}),
+    });
+    const { paths, shapes } = checked.data;
+    const notes = [...checked.notes];
+    // Filtering happens after the check rather than before it, so the counts a
+    // reader sees — how many endpoints exist, how many joined — describe the whole
+    // graph. A denominator that silently shrinks with the filter would make a
+    // narrow query look like a healthy repository.
+    const matches = (template) => filters === undefined || filters.some((f) => template.includes(f));
+    const findings = paths.findings.filter((f) => matches(f.pathTemplate));
+    const mismatches = shapes.mismatches.filter((m) => matches(String(m.endpoint.attrs["pathTemplate"] ?? m.endpoint.name)));
+    if (filters !== undefined) {
+        notes.push(`Filtered to endpoints matching ${filters.map((f) => `"${f}"`).join(", ")}. The counts ` +
+            "below describe the whole graph; the lists describe the filter.");
+    }
+    const total = findings.length + mismatches.length;
+    const nothingToCheck = paths.checked.endpoints === 0;
+    // MK-7: the leading clause. Every path finding and shape mismatch here is a
+    // real defect — `contracts.ts`'s own header on `nearMiss` is what keeps a
+    // mere typo-shaped call out of this count, so a nonzero total is never a
+    // "maybe".
+    const verdict = total === 0 ? "Clean at path level" : `${total} contract mismatch(es) found`;
+    return {
+        result: {
+            ...checked,
+            data: {
+                findings: findings.map((f) => ({
+                    kind: f.kind,
+                    method: f.method,
+                    path: f.pathTemplate,
+                    detail: f.detail,
+                    resolution: f.resolution,
+                    ...(f.nearMiss === null
+                        ? {}
+                        : { nearMiss: { kind: f.nearMiss.kind, against: f.nearMiss.against } }),
+                    callers: f.callers.slice(0, 5).map(briefNode),
+                    routes: f.routes.slice(0, 5).map(briefNode),
+                })),
+                shapeMismatches: mismatches.map((m) => ({
+                    endpoint: m.endpoint.name,
+                    direction: m.direction,
+                    reader: briefNode(m.reader),
+                    writer: briefNode(m.writer),
+                    differences: m.differences,
+                    resolution: m.resolution,
+                })),
+                checked: paths.checked,
+                shapes: {
+                    ran: shapes.ran,
+                    comparable: shapes.comparable,
+                    consumerOnly: shapes.consumerOnly,
+                    providerOnly: shapes.providerOnly,
+                    unroledDtos: shapes.unroledDtos,
+                    blockers: shapes.blockers,
+                },
+                unmatchedWithoutNearMiss: paths.unmatchedWithoutNearMiss,
+            },
+            notes,
+        },
+        // A path finding is a claim about names — this route exists, that one does
+        // not — which R2 fully supports. A shape mismatch is not, and `engine.ts`
+        // caps each one individually; this flag governs the answer's own headline
+        // claim, which is the path half.
+        nameLevel: true,
+        ...(nothingToCheck ? { state: "refused" } : {}),
+        headline: nothingToCheck
+            ? "No API endpoints are in the graph, so there is no contract to check."
+            : `${verdict}. ${paths.checked.joined} of ${paths.checked.endpoints} endpoint(s) have both ` +
+                `a caller and a route${shapes.ran ? "" : "; request and response shapes were not compared"}.`,
+    };
+}
+export const contractsTool = {
+    name: "contracts",
+    class: "read",
+    tier: "conclusion",
+    version: "1.0.0",
+    title: "Frontend/backend contract mismatches",
+    description: "Match every API caller against the route that serves it. Reports calls that reach no route " +
+        "and routes nothing calls, and — when both sides declare a shape — fields one side reads that " +
+        "the other does not send. A call with nothing resembling it on the provider side is disclosed " +
+        "as unanalysed rather than reported as broken, because the usual cause is a service outside " +
+        "this graph. Shape comparison requires R3 and is reported as not-run, with the reason, when " +
+        "the producers do not supply shapes.",
+    inputSchema: SCHEMA,
+    run,
+};
+//# sourceMappingURL=contracts.js.map

package/dist/tools/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../../src/tools/contracts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAW/C,OAAO,EACL,SAAS,EACT,eAAe,EACf,mBAAmB,GAIpB,MAAM,UAAU,CAAC;AAiFlB,MAAM,MAAM,GAAG;IACb,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE;QACV,KAAK,EAAE;YACL,IAAI,EAAE,OAAO;YACb,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;YACzB,WAAW,EACT,wFAAwF;gBACxF,+BAA+B;SAClC;QACD,SAAS,EAAE;YACT,IAAI,EAAE,SAAS;YACf,WAAW,EACT,yFAAyF;gBACzF,iCAAiC;SACpC;QACD,WAAW,EAAE;YACX,IAAI,EAAE,SAAS;YACf,OAAO,EAAE,CAAC;YACV,WAAW,EAAE,gFAAgF;SAC9F;KACF;IACD,oBAAoB,EAAE,KAAK;CACnB,CAAC;AAEX,KAAK,UAAU,GAAG,CAChB,IAA6B,EAC7B,GAAgB;IAEhB,MAAM,OAAO,GAAG,mBAAmB,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACnD,MAAM,WAAW,GAAG,eAAe,CAAC,IAAI,EAAE,aAAa,EAAE,CAAC,CAAC,CAAC;IAC5D,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;IAE7C,GAAG,CAAC,QAAQ,CAAC,iCAAiC,CAAC,CAAC;IAChD,MAAM,OAAO,GAAG,cAAc,CAAC,GAAG,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE;QACrD,GAAG,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC;QACrD,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC1C,CAAC,CAAC;IAEH,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IACvC,MAAM,KAAK,GAAG,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAEjC,2EAA2E;IAC3E,+EAA+E;IAC/E,0EAA0E;IAC1E,+CAA+C;IAC/C,MAAM,OAAO,GAAG,CAAC,QAAgB,EAAW,EAAE,CAC5C,OAAO,KAAK,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IAErE,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC;IACvE,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAChD,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CACrE,CAAC;IAEF,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,KAAK,CAAC,IAAI,CACR,kCAAkC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,eAAe;YACtF,gEAAgE,CACnE,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC;IAClD,MAAM,cAAc,GAAG,KAAK,CAAC,OAAO,CAAC,SAAS,KAAK,CAAC,CAAC;IAErD,4EAA4E;IAC5E,0EAA0E;IAC1E,yEAAyE;IACzE,WAAW;IACX,MAAM,OAAO,GAAG,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,GAAG,KAAK,8BAA8B,CAAC;IAE7F,OAAO;QACL,MAAM,EAAE;YACN,GAAG,OAAO;YACV,IAAI,EAAE;gBACJ,QAAQ,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;oBAC7B,IAAI,EAAE,CAAC,CAAC,IAAI;oBACZ,MAAM,EAAE,CAAC,CAAC,MAAM;oBAChB,IAAI,EAAE,CAAC,CAAC,YAAY;oBACpB,MAAM,EAAE,CAAC,CAAC,MAAM;oBAChB,UAAU,EAAE,CAAC,CAAC,UAAU;oBACxB,GAAG,CAAC,CAAC,CAAC,QAAQ,KAAK,IAAI;wBACrB,CAAC,CAAC,EAAE;wBACJ,CAAC,CAAC,EAAE,QAAQ,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC;oBACzE,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC;oBAC7C,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC;iBAC5C,CAAC,CAAC;gBACH,eAAe,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;oBACtC,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,IAAI;oBACzB,SAAS,EAAE,CAAC,CAAC,SAAS;oBACtB,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC;oBAC3B,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC;oBAC3B,WAAW,EAAE,CAAC,CAAC,WAAW;oBAC1B,UAAU,EAAE,CAAC,CAAC,UAAU;iBACzB,CAAC,CAAC;gBACH,OAAO,EAAE,KAAK,CAAC,OAAO;gBACtB,MAAM,EAAE;oBACN,GAAG,EAAE,MAAM,CAAC,GAAG;oBACf,UAAU,EAAE,MAAM,CAAC,UAAU;oBAC7B,YAAY,EAAE,MAAM,CAAC,YAAY;oBACjC,YAAY,EAAE,MAAM,CAAC,YAAY;oBACjC,WAAW,EAAE,MAAM,CAAC,WAAW;oBAC/B,QAAQ,EAAE,MAAM,CAAC,QAAQ;iBAC1B;gBACD,wBAAwB,EAAE,KAAK,CAAC,wBAAwB;aACzD;YACD,KAAK;SACN;QACD,2EAA2E;QAC3E,0EAA0E;QAC1E,0EAA0E;QAC1E,iCAAiC;QACjC,SAAS,EAAE,IAAI;QACf,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,SAAkB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACxD,QAAQ,EAAE,cAAc;YACtB,CAAC,CAAC,sEAAsE;YACxE,CAAC,CAAC,GAAG,OAAO,KAAK,KAAK,CAAC,OAAO,CAAC,MAAM,OAAO,KAAK,CAAC,OAAO,CAAC,SAAS,yBAAyB;gBAC1F,uBAAuB,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,iDAAiD,GAAG;KAClG,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,MAAM,aAAa,GAAmB;IAC3C,IAAI,EAAE,WAAW;IACjB,KAAK,EAAE,MAAM;IACb,IAAI,EAAE,YAAY;IAClB,OAAO,EAAE,OAAO;IAChB,KAAK,EAAE,sCAAsC;IAC7C,WAAW,EACT,6FAA6F;QAC7F,+FAA+F;QAC/F,+FAA+F;QAC/F,6FAA6F;QAC7F,6FAA6F;QAC7F,qCAAqC;IACvC,WAAW,EAAE,MAA4C;IACzD,GAAG;CACJ,CAAC"}

package/dist/tools/cross-pr.d.ts

@@ -0,0 +1,137 @@
+/**
+ * `cross-pr` — "what does this change collide with, that reading the diff alone
+ * would not show?"
+ *
+ * §14's multi-PR engine, at the protocol level. Four checks exist behind it and
+ * **two of them can run today**, for a reason worth stating rather than
+ * discovering: a check is available exactly when something already produces its
+ * input.
+ *
+ * | check | § | input | today |
+ * | --- | --- | --- | --- |
+ * | hidden dependency | 14.8 | `CHANGES_WITH` edges, already in the graph | **runs** |
+ * | overlap scoring | 14.3 | stored PR scopes | **runs, over whatever is stored** |
+ * | superseded | 14.5 | git blob ids at head and at base's tip | **runs** |
+ * | migration heads | 14.6 | migration revision + parents | needs a producer |
+ *
+ * §14.8 is first because it is the one that costs nothing: the edges already
+ * exist, it needs no per-PR storage, and it works at R0 in any language with no
+ * adapter beyond file paths. For a repository whose language has no adapter at
+ * all, this is the check that still fires.
+ *
+ * ## Why the two that cannot run are declared rather than omitted
+ *
+ * `contracts.ts` set this precedent and the reasoning transfers unchanged: a
+ * tool that silently offers three of five checks lets a caller read "nothing
+ * found" as "nothing there". Both blocked checks name the producer they are
+ * waiting for, so the gap is actionable rather than mysterious.
+ *
+ * ## Everything here is Class C and that is not a defect to be fixed
+ *
+ * Co-change is evidence about **people**, not program structure — a pair that
+ * moved together two hundred times is a stronger hint and is still a hint. The
+ * checks compute their own reliability rather than being told it, and each
+ * finding carries the sentence that must travel with it. A caller rendering
+ * these as defects has broken principle 4 at the last gate.
+ */
+import type { DiffType, HiddenDependencyReport, IncomparablePair, NodeVerdict, OverlapFinding, SupersededReport } from "@descryy/core";
+import type { ReliabilityClass } from "@descryy/ir";
+import { type BriefNode, type ToolDefinition } from "./kit.ts";
+/**
+ * A check whose input no producer writes yet.
+ *
+ * Declared rather than omitted, and `needs` says what would have to exist —
+ * a tool silently offering three of four checks lets a caller read "nothing
+ * found" as "nothing there".
+ */
+export interface BlockedCheck {
+    readonly check: string;
+    /** The architecture section that specifies it. */
+    readonly section: string;
+    readonly question: string;
+    readonly needs: string;
+}
+/**
+ * A file that historically moves with the change and was not touched this time.
+ *
+ * Class C, always, and `disclosure` is the sentence that must travel with it:
+ * co-change is evidence about **people**, not program structure. A caller
+ * rendering this as a defect has broken principle 4 at the last gate.
+ */
+export interface HiddenDependencyFinding extends BriefNode {
+    readonly coupledTo: readonly {
+        readonly file: string | null;
+        readonly support: number;
+    }[];
+    readonly strongestSupport: number;
+    readonly reliability: ReliabilityClass;
+    readonly disclosure: string;
+}
+export interface HiddenDependencyCheck {
+    /** False when no changed file had a single CHANGES_WITH edge: the history was not read. */
+    readonly ran: boolean;
+    readonly findings: readonly HiddenDependencyFinding[];
+    /** The count before `limit` capped it — P27's disclosed remainder (§4 technique 5). */
+    readonly findingsTotal: number;
+    readonly checked: HiddenDependencyReport["checked"];
+    /** Changed paths with no FILE node. Nothing looked at them. */
+    readonly unresolvedChanged: readonly string[];
+}
+export interface OverlapCheck {
+    /** False when fewer than two stored scopes exist: no pair could be compared. */
+    readonly ran: boolean;
+    readonly scopesCompared: number;
+    readonly findings: readonly OverlapFinding[];
+    /** The count before `limit` capped it — P27's disclosed remainder (§4 technique 5). */
+    readonly findingsTotal: number;
+    /** Pairs refused before comparison. An incomparable pair and a clean pair look identical otherwise. */
+    readonly incomparable: readonly IncomparablePair[];
+    readonly checked: OverlapReportChecked;
+}
+/** Named separately because `OverlapReport` itself is not re-exported field by field. */
+export type OverlapReportChecked = {
+    readonly scopes: number;
+    readonly pairs: number;
+    readonly pairsOverlapping: number;
+    readonly belowThreshold: number;
+    readonly incomparable: number;
+};
+export interface SupersededCheck {
+    /** False when there was nothing to compare — not the same as "not superseded". */
+    readonly ran: boolean;
+    readonly verdict: boolean;
+    readonly counts: SupersededReport["counts"];
+    readonly reliability: ReliabilityClass;
+    readonly disclosure: string;
+    /** Everything not already on base, so a reader sees what is left rather than what matched. */
+    readonly remaining: readonly {
+        /** Undefined for a comparison whose candidate carried no path. */
+        readonly file: string | undefined;
+        readonly diffType: DiffType;
+        readonly verdict: NodeVerdict;
+    }[];
+}
+/** git rejected the range: no check ran, and `blocked` is all there is to say. */
+export interface CrossPrGitFailure {
+    readonly blocked: readonly BlockedCheck[];
+}
+/** The diff is empty. A real answer: there is nothing to collide with. */
+export interface CrossPrEmptyDiff extends CrossPrGitFailure {
+    readonly changedFiles: number;
+}
+/**
+ * The full answer — three checks that can run, one that cannot.
+ *
+ * Each check carries its own `ran`, because one check producing a real answer
+ * is a real answer and burying it behind a caveat about a different question
+ * is what `contracts.ts` refuses for the same reason.
+ */
+export interface CrossPrReport extends CrossPrEmptyDiff {
+    readonly resolvedNodes: number;
+    readonly hiddenDependencies: HiddenDependencyCheck;
+    readonly overlaps: OverlapCheck;
+    readonly superseded: SupersededCheck;
+}
+export type CrossPrData = CrossPrGitFailure | CrossPrEmptyDiff | CrossPrReport;
+export declare const crossPrTool: ToolDefinition;
+//# sourceMappingURL=cross-pr.d.ts.map

package/dist/tools/cross-pr.d.ts.map

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

package/dist/tools/cross-pr.js

@@ -0,0 +1,216 @@
+/**
+ * `cross-pr` — "what does this change collide with, that reading the diff alone
+ * would not show?"
+ *
+ * §14's multi-PR engine, at the protocol level. Four checks exist behind it and
+ * **two of them can run today**, for a reason worth stating rather than
+ * discovering: a check is available exactly when something already produces its
+ * input.
+ *
+ * | check | § | input | today |
+ * | --- | --- | --- | --- |
+ * | hidden dependency | 14.8 | `CHANGES_WITH` edges, already in the graph | **runs** |
+ * | overlap scoring | 14.3 | stored PR scopes | **runs, over whatever is stored** |
+ * | superseded | 14.5 | git blob ids at head and at base's tip | **runs** |
+ * | migration heads | 14.6 | migration revision + parents | needs a producer |
+ *
+ * §14.8 is first because it is the one that costs nothing: the edges already
+ * exist, it needs no per-PR storage, and it works at R0 in any language with no
+ * adapter beyond file paths. For a repository whose language has no adapter at
+ * all, this is the check that still fires.
+ *
+ * ## Why the two that cannot run are declared rather than omitted
+ *
+ * `contracts.ts` set this precedent and the reasoning transfers unchanged: a
+ * tool that silently offers three of five checks lets a caller read "nothing
+ * found" as "nothing there". Both blocked checks name the producer they are
+ * waiting for, so the gap is actionable rather than mysterious.
+ *
+ * ## Everything here is Class C and that is not a defect to be fixed
+ *
+ * Co-change is evidence about **people**, not program structure — a pair that
+ * moved together two hundred times is a stronger hint and is still a hint. The
+ * checks compute their own reliability rather than being told it, and each
+ * finding carries the sentence that must travel with it. A caller rendering
+ * these as defects has broken principle 4 at the last gate.
+ */
+import { changedFiles, findHiddenDependencies, findOverlaps, findSuperseded, nodesInFiles, ScopeStore, supersededCandidates, } from "@descryy/core";
+import { answer, briefNode, optionalInteger, optionalString, requiredString, } from "./kit.js";
+const SCHEMA = {
+    type: "object",
+    properties: {
+        base: {
+            type: "string",
+            description: "The branch this change would merge into. Required — there is no defensible default, and " +
+                "guessing one silently changes which diff the answer describes.",
+        },
+        head: { type: "string", description: "The tip being reviewed. Default HEAD." },
+        limit: { type: "integer", minimum: 1, description: "Cap on findings per check. Default 10." },
+    },
+    required: ["base"],
+    additionalProperties: false,
+};
+/**
+ * Checks whose input no producer writes yet.
+ *
+ * Named here rather than in prose so the reply carries them as data a caller
+ * can act on. Each says what would have to exist, not merely that it does not.
+ */
+const BLOCKED = [
+    {
+        check: "migration-heads",
+        section: "14.6",
+        question: "Would merging these changes leave more than one migration head?",
+        needs: "a producer emitting each migration's revision and declared parents. The check is " +
+            "framework-agnostic by design — a revision, its parents and which change adds it is the " +
+            "shape every migration tool has — so this is one adapter, not one per framework.",
+    },
+];
+async function run(args, ctx) {
+    const base = requiredString(args, "base");
+    const head = optionalString(args, "head") ?? "HEAD";
+    const limit = optionalInteger(args, "limit", 1) ?? 10;
+    const { session } = ctx;
+    const stamp = session.provider().baseStamp();
+    const envelope = {
+        resolutionFloor: 0,
+        commitSha: stamp.commitSha,
+        graphBuiltAt: stamp.graphBuiltAt,
+        irSchemaVersion: stamp.irSchemaVersion,
+        // A file's presence or absence in a diff, and which symbols two changes both
+        // name, are name-level facts. Both still cap at C on R0 evidence — the
+        // carve-out that lifts a name-level fact to A begins at R2.
+        nameLevel: true,
+    };
+    ctx.progress(`Diffing ${base}...${head}`, 1, 3);
+    let files;
+    try {
+        files = await changedFiles(session.repoPath, base, head);
+    }
+    catch (error) {
+        return answer({
+            ...envelope,
+            headline: `Could not diff ${base}...${head}.`,
+            state: "refused",
+            data: { blocked: BLOCKED },
+            notes: [
+                `git rejected the range: ${error.message.trim()}.`,
+                "No check ran, which is not a finding that this change collides with nothing.",
+            ],
+        });
+    }
+    if (files.length === 0) {
+        return answer({
+            ...envelope,
+            headline: "The diff is empty.",
+            data: { changedFiles: 0, blocked: BLOCKED },
+            notes: ["An empty diff is a real answer: there is nothing to collide with."],
+        });
+    }
+    ctx.progress(`Resolving ${files.length} changed file(s)`, 2, 3);
+    const resolved = nodesInFiles(session.store().driver, files);
+    // §14.8 — the historically coupled file that was NOT touched.
+    ctx.progress("Reading co-change history", 3, 3);
+    const hidden = findHiddenDependencies(session.provider(), resolved.nodes.map((n) => n.id), resolved.missing, { limit });
+    // §14.3 — overlap against every scope computed on this same graph. Nothing
+    // writes `pr_scopes` yet, so this ordinarily finds fewer than two and says so;
+    // the check reports that as "no pair could be compared", never as "no
+    // conflicts", which is the distinction it exists to hold.
+    const scopes = stamp.commitSha === null
+        ? []
+        : new ScopeStore(session.store().driver).loadForGraph(session.config.repo, stamp.commitSha);
+    const overlaps = findOverlaps(scopes, { limit });
+    // §14.5 — is this work already on base? Producer and check both in core: git
+    // computes the content hashes, so nothing here reads code.
+    ctx.progress("Comparing against base");
+    const produced = await supersededCandidates(session.repoPath, base, head);
+    const superseded = findSuperseded(produced.candidates, {
+        fingerprintBasis: produced.fingerprintBasis,
+    });
+    const notes = [...hidden.notes, ...overlaps.notes, ...produced.notes, ...superseded.notes];
+    if (stamp.commitSha === null) {
+        notes.push("The graph carries no commit sha, so no stored PR scope could be matched to it. Overlap " +
+            "scoring did not run — scopes are only comparable against the graph they were computed on.");
+    }
+    notes.push(`${BLOCKED.length} of the four multi-PR checks did not run because nothing produces their ` +
+        `input yet: ${BLOCKED.map((b) => b.check).join(", ")}. Each is listed in "blocked" with ` +
+        "what it is waiting for. Their absence is not a clean result.");
+    // `refused` only when NOTHING looked at anything. One check producing a
+    // real answer is a real answer, and burying it behind a caveat about a
+    // different question is what `contracts.ts` refuses for the same reason.
+    const anythingRan = hidden.data.analysed || scopes.length >= 2 || superseded.analysed;
+    // MK-7: the leading clause, worded to never read as a defect claim — this
+    // file's own header is explicit that every finding here is Class C evidence
+    // about people, not program structure, and "N found" would read exactly
+    // like the graded verdict `validate`/`contracts` give their real defects.
+    const hintCount = hidden.data.findings.length + overlaps.findings.length;
+    const verdict = hintCount === 0 ? "No collisions detected" : `${hintCount} potential collision(s) to review`;
+    return {
+        result: {
+            data: {
+                changedFiles: files.length,
+                resolvedNodes: resolved.nodes.length,
+                hiddenDependencies: {
+                    ran: hidden.data.analysed,
+                    findings: hidden.data.findings.map((f) => ({
+                        ...briefNode(f.node),
+                        coupledTo: f.coupledTo.map((c) => ({ file: c.node.file, support: c.support })),
+                        strongestSupport: f.strongestSupport,
+                        reliability: f.reliability,
+                        disclosure: f.disclosure,
+                    })),
+                    findingsTotal: hidden.data.findingsTotal,
+                    checked: hidden.data.checked,
+                    unresolvedChanged: hidden.data.unresolvedChanged,
+                },
+                overlaps: {
+                    ran: scopes.length >= 2,
+                    scopesCompared: scopes.length,
+                    findings: overlaps.findings,
+                    findingsTotal: overlaps.findingsTotal,
+                    incomparable: overlaps.incomparable,
+                    checked: overlaps.checked,
+                },
+                superseded: {
+                    ran: superseded.analysed,
+                    verdict: superseded.superseded,
+                    counts: superseded.counts,
+                    reliability: superseded.reliability,
+                    disclosure: superseded.disclosure,
+                    remaining: superseded.comparisons
+                        .filter((c) => c.verdict !== "already-in-base")
+                        .map((c) => ({ file: c.file, diffType: c.diffType, verdict: c.verdict })),
+                },
+                blocked: BLOCKED,
+            },
+            stamp: hidden.stamp,
+            truncated: hidden.truncated,
+            notes,
+        },
+        ...(anythingRan ? {} : { state: "refused" }),
+        nameLevel: true,
+        headline: anythingRan
+            ? `${verdict}. ${hidden.data.findings.length} historically coupled file(s) were not touched; ` +
+                `${overlaps.findings.length} overlapping change pair(s) scored above the conflict ` +
+                `threshold; ${superseded.superseded ? "this change's work is already on base" : `${superseded.counts.alreadyInBase} of ${superseded.counts.total} touched file(s) already match base`}. ` +
+                `${BLOCKED.length} of four checks could not run.`
+            : "No multi-PR check was able to run on this change. That is a statement about the " +
+                "evidence available, not about the change.",
+    };
+}
+export const crossPrTool = {
+    name: "cross_pr",
+    class: "read",
+    tier: "conclusion",
+    version: "1.0.0",
+    title: "Cross-change collisions",
+    description: "What this change collides with that reading its diff alone would not show: files it " +
+        "historically moves with and did not touch this time (§14.8), other in-flight changes " +
+        "editing the same important nodes (§14.3), and whether the work is already on base by " +
+        "another route (§14.5). Findings are Class C hints about how people edit this repository, " +
+        "never claims about what breaks. The remaining check — migration head conflicts — is " +
+        "declared with what it is waiting for rather than silently omitted.",
+    inputSchema: SCHEMA,
+    run,
+};
+//# sourceMappingURL=cross-pr.js.map

package/dist/tools/cross-pr.js.map

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

package/dist/tools/git-diff.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `get_git_diff` — §18's "other useful Git tool": a live textual diff
+ * between two refs. P27's disclosed remainder — `ai-layer-plan.md` §3's
+ * re-derivation found `history.ts`'s own header already stating why it
+ * cannot be stretched into this shape: it is scoped to the stored
+ * `CHANGES_WITH` ledger, not a live `git diff`. `changedFiles`
+ * (`cross-pr.ts`) answers "which files changed" as a bare path list; this
+ * answers "what changed in them" — per-file status and line counts always,
+ * plus the unified-diff patch text when it is cheap enough to hand to a
+ * model (§4: the client's context window is not this tool's to spend).
+ */
+import type { GitDiffFile } from "@descryy/core";
+import { type ToolDefinition } from "./kit.ts";
+export type GitDiffEntry = GitDiffFile;
+/**
+ * One shape for all three states (`ok` / `empty` / `refused`) — unlike
+ * `cross-pr`'s union, a git-rejected range and a genuinely empty diff carry
+ * the identical fields here (`files: []`, `filesTotal: 0`); `state` and
+ * `disclosures` are what tell them apart, not the payload's shape.
+ */
+export interface GitDiffData {
+    readonly base: string;
+    readonly head: string;
+    /** Capped by `limit`; `filesTotal` is the uncapped count. Empty on a git failure. */
+    readonly files: readonly GitDiffEntry[];
+    readonly filesTotal: number;
+}
+export declare const gitDiffTool: ToolDefinition;
+//# sourceMappingURL=git-diff.d.ts.map

package/dist/tools/git-diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-diff.d.ts","sourceRoot":"","sources":["../../src/tools/git-diff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD,OAAO,EAOL,KAAK,cAAc,EACpB,MAAM,UAAU,CAAC;AAKlB,MAAM,MAAM,YAAY,GAAG,WAAW,CAAC;AAEvC;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,qFAAqF;IACrF,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,CAAC;IACxC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAsGD,eAAO,MAAM,WAAW,EAAE,cAczB,CAAC"}