@descryy/core 0.1.0

package/dist/contracts/paths.js

@@ -0,0 +1,245 @@
+/**
+ * Comparing two endpoint paths, and knowing when not to.
+ *
+ * This file is small and is the most dangerous part of the contract engine, so
+ * it is separate and tested on its own.
+ *
+ * ## The problem it exists to solve
+ *
+ * A caller reaching an endpoint no route serves is *sometimes* a bug and
+ * *usually* not. Measured on two real repositories: 117 callers, 24 routes, 16
+ * joined. The other 101 are overwhelmingly calls to services that are simply not
+ * in this graph — a third-party API, a backend nobody has analysed. Reporting
+ * all 101 as "no route serves this" would be 101 confident wrong statements, and
+ * would bury the handful that are real.
+ *
+ * So an unmatched caller is only a **finding** when a served route exists that
+ * it nearly matches. Nothing similar on the provider side means the provider was
+ * probably never analysed, which belongs in §20.2's *not analysable* category
+ * and is disclosed as a count rather than enumerated as defects.
+ *
+ * ## The near-miss rules are deliberately narrow
+ *
+ * Each one describes a specific, common, *mechanical* mistake. None of them is a
+ * similarity score, because a threshold on a score is a knob that turns "is this
+ * a bug" into "how high did we set it".
+ *
+ * | rule | example | why it is a real mistake |
+ * | --- | --- | --- |
+ * | method differs, path identical | `POST /orders` vs `GET /orders` | someone changed the verb on one side |
+ * | exactly one **literal** segment differs, **and the two differ by a typo's worth of characters** | `/order/{param}/items` vs `/orders/{param}/items` | a typo or a rename applied on one side |
+ *
+ * ## Rule 2's similarity floor, and the measurement that set it
+ *
+ * That second clause was missing for the whole life of this file, and its
+ * absence was not a small thing. "Exactly one segment differs" says nothing at
+ * all about *how* it differs: `/api/hmac` and `/api/novu-agent` differ in
+ * exactly one segment, share a method and share arity. Precision came only
+ * incidentally, from `{param}` segments happening to sit where the paths
+ * diverge.
+ *
+ * `DEC-317` found this from the GraphQL side — every operation path is arity-2
+ * with no `{param}` and a first segment drawn from a set of size three, so the
+ * whole GraphQL surface of a repository collapsed into three buckets in which
+ * every member near-missed every other — and gated it rather than fixing it,
+ * because a threshold chosen carelessly costs the near-typo detections this
+ * rule exists for, and costs them invisibly.
+ *
+ * So it was measured, against 3,524 routes from 27 real repositories, by
+ * `bench/near-miss-similarity.mjs` — which pre-registers the metric, the
+ * candidate thresholds and the decision rule in its header, and was committed
+ * before it was run. What it found:
+ *
+ * - **The rule was not a precision rule.** Treating each real route as an
+ *   unmatched caller against the rest of its own application's table, it
+ *   reported a `ONE_SEGMENT` near miss for **1,796 of 3,524 routes — 51%.**
+ *   Every one is a false positive by construction: both sides are real,
+ *   deliberately distinct routes of the same service.
+ * - **On the genuinely reachable population it was worse.** Across every
+ *   unmatched `USES_API` caller in the corpus, the rule emitted **18 findings,
+ *   and all 18 were nonsense** — 15 of them naming the same `/api/novu-agent`
+ *   route from callers like `/api/hmac` and `/api/send-email`. There were no
+ *   true positives to lose.
+ *
+ * The floor is `1 - distance / max(len) >= 0.4`, with any distance of 1 or less
+ * admitted outright so that a one-character mistake in a short segment (`/v1`
+ * against `/v2`) is not scored away. It rejects **87.4%** of those 1,796 and
+ * retains **100%** of a seeded near-typo population of 49,405 — real route
+ * segments mutated by transposition, deletion, insertion, substitution,
+ * singular/plural and separator variance. Not one seeded typo is lost, in any
+ * class.
+ *
+ * **The distance counts an adjacent transposition as one edit, not two, and
+ * that is load-bearing.** With plain Levenshtein a swap costs two, so `api` →
+ * `aip` scores `1 - 2/3 = 0.33` and every candidate threshold silently deleted
+ * the entire transposition class — 2,916 real detections, all on segments of
+ * three characters. The first measurement pass rejected every threshold for
+ * exactly this reason, and the reason was a defect in the metric rather than a
+ * fact about the corpus.
+ *
+ * **What the floor is not.** It is a similarity test, not an oracle. `activate`
+ * and `deactivate` are two real routes in one API and score 0.80, so they are
+ * still reported. Nothing here can distinguish a two-character prefix from a
+ * typo, and this does not claim to — it buys precision against *unrelated*
+ * words, which is what the corpus says the problem was.
+ *
+ * **A trailing-slash rule was written and then deleted, and the reason is worth
+ * keeping.** `/orders/` and `/orders` look like the classic contract mismatch,
+ * but `normaliseEndpointPath` strips the trailing slash *before hashing*, so the
+ * two sides mint the **same `API_ENDPOINT` id** and join correctly. The rule
+ * could never fire. It was caught by a test that asserted it would.
+ *
+ * That unification is the right default — the two paths mean the same endpoint
+ * to everyone who writes them — but it does make one real class of bug
+ * invisible here: a framework configured for strict routing genuinely serves
+ * only one of them. Whether it does depends on router configuration this graph
+ * does not read, so the limit is stated rather than papered over with a rule
+ * that fires on nothing.
+ *
+ * **Deliberately not a rule: a parameter where the other side has a literal.**
+ * `/orders/{param}` and `/orders/recent` legitimately coexist in every routing
+ * framework on earth — the literal is matched first and the parameter catches
+ * the rest. Treating that as a near miss would report the single most common
+ * correct pattern in REST routing as a defect.
+ *
+ * Segment counts must be equal for the segment rule. `/orders` and
+ * `/orders/{param}` are two different endpoints, not a near miss, and a rule
+ * that ignored length would pair every collection route with its item route.
+ */
+/** The normalised placeholder every adapter writes. See `normaliseEndpointPath`. */
+const PARAM = "{param}";
+/**
+ * How alike rule 2's two differing segments must be, as a fraction of the
+ * longer one's length. **Measured, not chosen** — see the module header, and
+ * `bench/near-miss-similarity.mjs` for the pre-registered decision rule that
+ * selected it: the lowest candidate that keeps 100% of a 49,405-case seeded
+ * near-typo population, which it does while rejecting 87.4% of the false
+ * positives the unguarded rule produced on 3,524 real routes.
+ */
+const SEGMENT_SIMILARITY_FLOOR = 0.4;
+/**
+ * Damerau-Levenshtein distance, optimal string alignment.
+ *
+ * **An adjacent transposition costs one edit, not two**, and that is the whole
+ * reason this is not the three-line Levenshtein. A swapped pair of characters
+ * is a single keystroke mistake and the single most common way a path is
+ * typo'd; charging it two edits puts `api`/`aip` at 0.33 and deletes the entire
+ * class from what rule 2 can report.
+ */
+function editDistance(a, b) {
+    if (a === b)
+        return 0;
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    const rows = [];
+    for (let i = 0; i <= a.length; i += 1)
+        rows.push(new Array(b.length + 1).fill(0));
+    for (let i = 0; i <= a.length; i += 1)
+        rows[i][0] = i;
+    for (let j = 0; j <= b.length; j += 1)
+        rows[0][j] = j;
+    for (let i = 1; i <= a.length; i += 1) {
+        for (let j = 1; j <= b.length; j += 1) {
+            const substitution = a[i - 1] === b[j - 1] ? 0 : 1;
+            let best = Math.min(rows[i - 1][j] + 1, rows[i][j - 1] + 1, rows[i - 1][j - 1] + substitution);
+            if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+                best = Math.min(best, rows[i - 2][j - 2] + 1);
+            }
+            rows[i][j] = best;
+        }
+    }
+    return rows[a.length][b.length];
+}
+/**
+ * Are these two segments close enough that one could be a mistyping of the
+ * other, rather than simply a different word?
+ *
+ * A distance of one is admitted whatever the lengths, because on a short
+ * segment a single edit is a large fraction of the string and normalising it
+ * away would reject `/v1` against `/v2` — the most mechanical mismatch there
+ * is.
+ */
+function nearlyTheSameWord(a, b) {
+    const distance = editDistance(a, b);
+    if (distance <= 1)
+        return true;
+    return 1 - distance / Math.max(a.length, b.length) >= SEGMENT_SIMILARITY_FLOOR;
+}
+function segments(path) {
+    return path.split("/").filter((s) => s !== "");
+}
+/** Trailing slash removed, so `/orders/` and `/orders` compare as one shape. */
+function trimmed(path) {
+    return path.length > 1 && path.endsWith("/") ? path.slice(0, -1) : path;
+}
+export function sameEndpoint(a, b) {
+    return a.method === b.method && a.pathTemplate === b.pathTemplate;
+}
+/**
+ * The closest served endpoint to `wanted`, or null if nothing is close enough.
+ *
+ * Rules are tried in order of how certain they are, and the first hit wins —
+ * a method mismatch on an otherwise identical path is a better explanation than
+ * a one-segment difference somewhere else, and reporting both would be reporting
+ * one mistake twice.
+ */
+export function nearestMiss(wanted, served) {
+    const wantedPath = trimmed(wanted.pathTemplate);
+    const wantedSegments = segments(wantedPath);
+    // 1. Same path, different method.
+    for (const candidate of served) {
+        if (trimmed(candidate.pathTemplate) === wantedPath && candidate.method !== wanted.method) {
+            return {
+                kind: "METHOD",
+                against: candidate,
+                detail: `the path is served, but as ${candidate.method} rather than ${wanted.method}. ` +
+                    "One side changed the verb.",
+            };
+        }
+    }
+    // 2. Same method, same segment count, exactly one segment differs, and both
+    //    sides of that segment are literals.
+    for (const candidate of served) {
+        if (candidate.method !== wanted.method)
+            continue;
+        const candidateSegments = segments(trimmed(candidate.pathTemplate));
+        if (candidateSegments.length !== wantedSegments.length)
+            continue;
+        let differing = -1;
+        let count = 0;
+        for (let i = 0; i < wantedSegments.length; i += 1) {
+            if (wantedSegments[i] !== candidateSegments[i]) {
+                differing = i;
+                count += 1;
+                if (count > 1)
+                    break;
+            }
+        }
+        if (count !== 1)
+            continue;
+        const mine = wantedSegments[differing];
+        const theirs = candidateSegments[differing];
+        // A parameter opposite a literal is the correct, universal REST pattern —
+        // the literal is matched first and the parameter catches the rest. Calling
+        // it a near miss would report `/orders/{param}` and `/orders/recent` as a
+        // defect in every codebase.
+        if (mine === PARAM || theirs === PARAM)
+            continue;
+        // Two different words are not a near miss, and without this the rule fired
+        // on 51% of every real route table it was measured against. `continue`, not
+        // `return null`: a dissimilar candidate must not hide a similar one later
+        // in the list, which is how the rule used to name the wrong route.
+        if (!nearlyTheSameWord(mine, theirs))
+            continue;
+        return {
+            kind: "ONE_SEGMENT",
+            against: candidate,
+            detail: `a route differs from this call in exactly one segment: "${theirs}" where the call says ` +
+                `"${mine}". Everything else about the path and the method matches.`,
+        };
+    }
+    return null;
+}
+//# sourceMappingURL=paths.js.map

package/dist/contracts/paths.js.map

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

package/dist/contracts/shapes.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Comparing two declared shapes — the R3 half of §13.
+ *
+ * Everything here is a pure function over `attrs`, and that is the design rather
+ * than an accident. §13.2's mechanism is **shape comparison, not identifier
+ * matching**, and a shape reaches this file as a list of fields with optional
+ * per-field detail. No type here names a language, and nothing branches on one:
+ * a Pydantic model, an OpenAPI schema and a TypeScript interface arrive
+ * identically or they do not arrive at all.
+ *
+ * ## Direction is not symmetric, and getting that wrong produces noise
+ *
+ * A consumer that ignores a field the provider sends is **fine** — that is how
+ * every API client on earth works. A consumer that reads a field the provider
+ * does not send is **broken**. So the comparison takes an *expected* side and a
+ * *provided* side, and a field present only in `provided` is not a finding.
+ *
+ * A symmetric diff would report every unused response field in every codebase,
+ * which is both enormous and wrong.
+ *
+ * ## Detail is compared only when both sides have it
+ *
+ * A shape read from `attrs.fields` is a list of names — R2-grade evidence, good
+ * enough to say *this field is missing* and nothing else. A shape read from
+ * `attrs.fieldDetail` carries type, nullability and requiredness, which is what
+ * a type checker buys.
+ *
+ * When either side lacks detail, `comparedDetail` comes back false and **no type
+ * or nullability differences are emitted**. That flag is load-bearing: an empty
+ * difference list is otherwise indistinguishable from "the types agree", and
+ * reporting "no type mismatches" after comparing two lists of names is exactly
+ * the overstatement principle 3 exists to stop.
+ */
+import type { IRNode } from "@descryy/ir";
+export interface ShapeField {
+    readonly name: string;
+    readonly type?: string | undefined;
+    readonly nullable?: boolean | undefined;
+    readonly required?: boolean | undefined;
+    /**
+     * The field holds *many* of `type`, not one.
+     *
+     * **A separate flag rather than part of the type string, and that is rule 1.**
+     * The same field is written `Foo[]` by one producer, `List[Foo]` by another and
+     * `array` with an `items` schema by a third. Comparing those as strings is an
+     * engine above the IR deciding what a language's array syntax looks like, which
+     * is the leak the boundary exists to stop — and it fails in both directions at
+     * once: `Foo[]` vs `List[Foo]` reports a mismatch that is not there, while
+     * `Foo` vs `Foo` with one side an array reports nothing when the consumer is
+     * about to iterate an object.
+     *
+     * Producers put the **element** type in `type` and the cardinality here.
+     */
+    readonly list?: boolean | undefined;
+}
+export interface Shape {
+    /** The node this was read from, so a finding can point at a file and a line. */
+    readonly source: IRNode;
+    readonly fields: readonly ShapeField[];
+    /** True when per-field type/nullability/requiredness is present — R3-grade. */
+    readonly detailed: boolean;
+}
+/**
+ * Read a shape out of a node's `attrs`, or return null if it declares none.
+ *
+ * Two forms, in order of richness. `fieldDetail` is what a producer emits when a
+ * type checker or a schema gave it per-field facts; `fields` is the name-level
+ * fallback. Anything else is not a shape and is not guessed at.
+ */
+export declare function readShape(node: IRNode): Shape | null;
+export type ShapeDifferenceKind = "FIELD_MISSING" | "TYPE_DIFFERS" | "NULLABILITY_DIFFERS" | "REQUIREDNESS_DIFFERS" | "LIST_DIFFERS";
+export interface ShapeDifference {
+    readonly kind: ShapeDifferenceKind;
+    readonly field: string;
+    /** What the consuming side expects. */
+    readonly expected: string;
+    /** What the providing side declares. */
+    readonly provided: string;
+    readonly detail: string;
+}
+export interface ShapeComparison {
+    readonly differences: readonly ShapeDifference[];
+    /**
+     * True only when **both** sides carried per-field detail.
+     *
+     * When false, an empty `differences` means "no field is missing", not "the
+     * types agree" — and every consumer of this result has to say so.
+     */
+    readonly comparedDetail: boolean;
+    readonly fieldsCompared: number;
+}
+/**
+ * What the consuming side asks for that the providing side does not deliver.
+ *
+ * @param expected the shape the consumer reads
+ * @param provided the shape the producer declares
+ */
+export declare function compareShapes(expected: Shape, provided: Shape): ShapeComparison;
+//# sourceMappingURL=shapes.d.ts.map

package/dist/contracts/shapes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shapes.d.ts","sourceRoot":"","sources":["../../src/contracts/shapes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACxC;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACrC;AAED,MAAM,WAAW,KAAK;IACpB,gFAAgF;IAChF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,CAAC;IACvC,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI,CAUpD;AAwDD,MAAM,MAAM,mBAAmB,GAC3B,eAAe,GACf,cAAc,GACd,qBAAqB,GACrB,sBAAsB,GACtB,cAAc,CAAC;AAEnB,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,uCAAuC;IACvC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,wCAAwC;IACxC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,WAAW,EAAE,SAAS,eAAe,EAAE,CAAC;IACjD;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,GAAG,eAAe,CAoG/E"}

package/dist/contracts/shapes.js

@@ -0,0 +1,196 @@
+/**
+ * Comparing two declared shapes — the R3 half of §13.
+ *
+ * Everything here is a pure function over `attrs`, and that is the design rather
+ * than an accident. §13.2's mechanism is **shape comparison, not identifier
+ * matching**, and a shape reaches this file as a list of fields with optional
+ * per-field detail. No type here names a language, and nothing branches on one:
+ * a Pydantic model, an OpenAPI schema and a TypeScript interface arrive
+ * identically or they do not arrive at all.
+ *
+ * ## Direction is not symmetric, and getting that wrong produces noise
+ *
+ * A consumer that ignores a field the provider sends is **fine** — that is how
+ * every API client on earth works. A consumer that reads a field the provider
+ * does not send is **broken**. So the comparison takes an *expected* side and a
+ * *provided* side, and a field present only in `provided` is not a finding.
+ *
+ * A symmetric diff would report every unused response field in every codebase,
+ * which is both enormous and wrong.
+ *
+ * ## Detail is compared only when both sides have it
+ *
+ * A shape read from `attrs.fields` is a list of names — R2-grade evidence, good
+ * enough to say *this field is missing* and nothing else. A shape read from
+ * `attrs.fieldDetail` carries type, nullability and requiredness, which is what
+ * a type checker buys.
+ *
+ * When either side lacks detail, `comparedDetail` comes back false and **no type
+ * or nullability differences are emitted**. That flag is load-bearing: an empty
+ * difference list is otherwise indistinguishable from "the types agree", and
+ * reporting "no type mismatches" after comparing two lists of names is exactly
+ * the overstatement principle 3 exists to stop.
+ */
+/**
+ * Read a shape out of a node's `attrs`, or return null if it declares none.
+ *
+ * Two forms, in order of richness. `fieldDetail` is what a producer emits when a
+ * type checker or a schema gave it per-field facts; `fields` is the name-level
+ * fallback. Anything else is not a shape and is not guessed at.
+ */
+export function readShape(node) {
+    const detail = readEntries(node.attrs["fieldDetail"]);
+    if (detail !== null && detail.fields.length > 0) {
+        return { source: node, fields: detail.fields, detailed: true };
+    }
+    const fields = readEntries(node.attrs["fields"]);
+    if (fields !== null && fields.fields.length > 0) {
+        return { source: node, fields: fields.fields, detailed: fields.detailed };
+    }
+    return null;
+}
+/**
+ * Read a field list in either spelling a producer actually uses.
+ *
+ * **Measured, not anticipated.** Two shipped adapters both write
+ * `attrs.fields` and disagree on what it holds: the contract reader writes a
+ * list of **names** with per-field detail alongside in `fieldDetail`, and the
+ * TypeScript adapter writes a list of **objects** (`{ name, nullable }`) under
+ * the same key. On real repositories, **77 of 77** shape pointers resolved to a
+ * node that plainly declared its fields, and every one read as *no shape at
+ * all*, because the reader filtered for strings and found none.
+ *
+ * The silence is the part worth fixing: a reader that cannot read a node which
+ * visibly declares fields, and says nothing, answers "no" where it should
+ * answer "I could not tell".
+ *
+ * Reading both beats forcing one spelling on two adapters. `attrs` is where
+ * language-specific detail lives and nothing above the IR may demand a single
+ * form of it. Neither adapter changed.
+ *
+ * `detailed` is derived rather than declared: an entry carrying anything beyond
+ * a name is per-field evidence. A producer emitting `{ name, nullable }` gets
+ * nullability compared and nothing else — exactly what it supplied.
+ */
+function readEntries(raw) {
+    if (!Array.isArray(raw))
+        return null;
+    const fields = [];
+    let detailed = false;
+    for (const entry of raw) {
+        if (typeof entry === "string") {
+            fields.push({ name: entry });
+            continue;
+        }
+        if (typeof entry !== "object" || entry === null)
+            continue;
+        const record = entry;
+        const name = record["name"];
+        if (typeof name !== "string")
+            continue;
+        const field = {
+            name,
+            ...(typeof record["type"] === "string" ? { type: record["type"] } : {}),
+            ...(typeof record["nullable"] === "boolean" ? { nullable: record["nullable"] } : {}),
+            ...(typeof record["required"] === "boolean" ? { required: record["required"] } : {}),
+            ...(typeof record["list"] === "boolean" ? { list: record["list"] } : {}),
+        };
+        if (Object.keys(field).length > 1)
+            detailed = true;
+        fields.push(field);
+    }
+    return { fields, detailed };
+}
+/**
+ * What the consuming side asks for that the providing side does not deliver.
+ *
+ * @param expected the shape the consumer reads
+ * @param provided the shape the producer declares
+ */
+export function compareShapes(expected, provided) {
+    const byName = new Map(provided.fields.map((f) => [f.name, f]));
+    const comparedDetail = expected.detailed && provided.detailed;
+    const differences = [];
+    for (const want of expected.fields) {
+        const have = byName.get(want.name);
+        if (have === undefined) {
+            differences.push({
+                kind: "FIELD_MISSING",
+                field: want.name,
+                expected: "present",
+                provided: "absent",
+                detail: `"${want.name}" is read from ${expected.source.name} and is not declared by ` +
+                    `${provided.source.name}.`,
+            });
+            continue;
+        }
+        // Below here every claim is about a *shape*, which no amount of name
+        // resolution establishes. Skipped entirely rather than compared against
+        // undefined — `undefined !== "string"` would report a type mismatch on every
+        // field of every name-level shape.
+        if (!comparedDetail)
+            continue;
+        if (want.type !== undefined && have.type !== undefined && want.type !== have.type) {
+            differences.push({
+                kind: "TYPE_DIFFERS",
+                field: want.name,
+                expected: want.type,
+                provided: have.type,
+                detail: `"${want.name}" is read as ${want.type} and declared as ${have.type}.`,
+            });
+        }
+        // Cardinality, and **unlike nullability this one is symmetric**. A consumer
+        // that iterates what the provider sends as a single object breaks, and a
+        // consumer that reads fields off what the provider sends as an array breaks
+        // too. Neither direction is the safe one, so both are reported.
+        //
+        // Compared only when **both sides say**. An absent `list` is *unknown*, not
+        // `false`. A producer that never emits the flag would otherwise read as
+        // declaring every field singular, and every array field on the other side
+        // would come back as a finding — the 77-of-77 conflation running the other
+        // way. There the reader saw no shape and answered "no fields"; here it
+        // would see no flag and answer "not a list". Absence of evidence is allowed
+        // to stay absence of evidence.
+        if (want.list !== undefined && have.list !== undefined && want.list !== have.list) {
+            const asRead = want.list ? "a list" : "a single value";
+            const asDeclared = have.list ? "a list" : "a single value";
+            differences.push({
+                kind: "LIST_DIFFERS",
+                field: want.name,
+                expected: asRead,
+                provided: asDeclared,
+                detail: `"${want.name}" is read from ${expected.source.name} as ${asRead} and declared by ` +
+                    `${provided.source.name} as ${asDeclared}.`,
+            });
+        }
+        // A field the provider may return as null and the consumer does not expect
+        // to be null. The reverse — consumer tolerates null, provider never sends it
+        // — is safe and is not reported.
+        if (want.nullable === false && have.nullable === true) {
+            differences.push({
+                kind: "NULLABILITY_DIFFERS",
+                field: want.name,
+                expected: "not null",
+                provided: "nullable",
+                detail: `"${want.name}" may be null according to ${provided.source.name}, and ` +
+                    `${expected.source.name} reads it as though it never is.`,
+            });
+        }
+        // A field the consumer requires and the provider may omit. `required` and
+        // `nullable` assert different things — a field absent from `required` may be
+        // *omitted*, not set to null — so they are checked apart.
+        if (want.required === true && have.required === false) {
+            differences.push({
+                kind: "REQUIREDNESS_DIFFERS",
+                field: want.name,
+                expected: "always present",
+                provided: "optional",
+                detail: `"${want.name}" is required by ${expected.source.name} and optional in ` +
+                    `${provided.source.name}, so it may be absent entirely.`,
+            });
+        }
+    }
+    differences.sort((a, b) => a.field.localeCompare(b.field) || a.kind.localeCompare(b.kind));
+    return { differences, comparedDetail, fieldsCompared: expected.fields.length };
+}
+//# sourceMappingURL=shapes.js.map

package/dist/contracts/shapes.js.map

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

package/dist/governance/budget.d.ts

@@ -0,0 +1,89 @@
+/**
+ * The hard per-run budget — §41 rule 16, `ai-layer-plan.md` §11 (Phase 4,
+ * P17/P18). `ai-governance-spec.md` §8 names this explicitly as *not* its
+ * document's job: *"a property of the harness (Phase 4, P17/P18), not of a
+ * per-finding gate... Full spec: Phase 4 (P17), not this document."* This
+ * module is that property.
+ *
+ * *"Enforced by the runtime harness, not by the AI's own judgment of when to
+ * stop"* (`descry-ai-layer.md`, "Execution budget"). A cap the model can
+ * reason its way past is not a cap (§41 rule 16's own words) — so, same as
+ * G1–G4, this is a pure function the pipeline calls, never a prompt
+ * instruction.
+ *
+ * ## Four caps, two scopes
+ *
+ * `ai-layer-plan.md` §11 names four: *"max turns per investigation · max
+ * cost per run · max concurrent open hypotheses · max tool calls per
+ * hypothesis."* Two are per-run (cost, concurrency); two are per-hypothesis
+ * (turns, tool calls) and are checked against every currently-open
+ * hypothesis independently — one hypothesis running long does not budget-fail
+ * a sibling that has spent nothing.
+ *
+ * ## The default values
+ *
+ * `documents/architecture/investigation-budget-spec.md` (P17) is where these
+ * are ruled and justified; this module imports them from there in spirit —
+ * they are declared once, here, because the spec document is prose and this
+ * is the value the harness actually reads. A caller may always supply its
+ * own {@link InvestigationBudget}; the exported default is a starting point,
+ * tuned from data, the same convention `CLAUDE.md` already applies to node
+ * budgets.
+ */
+/** The four caps, `ai-layer-plan.md` §11's own names. */
+export interface InvestigationBudget {
+    /** Loop iterations spent investigating one hypothesis before it is forced to a terminal state. */
+    readonly maxTurnsPerInvestigation: number;
+    /** Tool calls issued investigating one hypothesis. */
+    readonly maxToolCallsPerHypothesis: number;
+    /** Hypotheses allowed in `investigating` or `supported` at once, run-wide. */
+    readonly maxConcurrentOpenHypotheses: number;
+    /** Total spend for the whole run, in USD. */
+    readonly costCeilingPerRunUsd: number;
+}
+/**
+ * P17's ruled starting values — `documents/architecture/investigation-budget-spec.md`.
+ * Not a measurement; a starting point to tune from real runs, same as the
+ * node budgets `CLAUDE.md` already treats this way.
+ */
+export declare const DEFAULT_INVESTIGATION_BUDGET: InvestigationBudget;
+/** Usage accumulated for one open hypothesis. */
+export interface HypothesisBudgetUsage {
+    readonly hypothesisId: string;
+    readonly turnsSpent: number;
+    readonly toolCallsSpent: number;
+}
+/** Usage accumulated for the whole run, as of the moment this is checked. */
+export interface RunBudgetUsage {
+    readonly costSpentUsd: number;
+    /** Every hypothesis currently `investigating` or `supported` — not `candidate`, and not a terminal state. */
+    readonly openHypotheses: readonly HypothesisBudgetUsage[];
+}
+export declare const BUDGET_CAP_NAMES: readonly ["maxTurnsPerInvestigation", "maxToolCallsPerHypothesis", "maxConcurrentOpenHypotheses", "costCeilingPerRunUsd"];
+export type BudgetCapName = (typeof BUDGET_CAP_NAMES)[number];
+export interface BudgetCapExceeded {
+    readonly cap: BudgetCapName;
+    readonly limit: number;
+    readonly actual: number;
+    /** Which hypothesis this violation belongs to — absent for the two run-level caps. */
+    readonly hypothesisId?: string;
+}
+export interface BudgetCheckResult {
+    readonly withinBudget: boolean;
+    /** Every cap currently exceeded — empty when `withinBudget`. More than one may fire at once. */
+    readonly exceeded: readonly BudgetCapExceeded[];
+}
+/**
+ * Check `usage` against `budget`. Never throws — this is a check, not an
+ * execution of the thing it is checking, same posture as G1–G4.
+ */
+export declare function checkRunBudget(budget: InvestigationBudget, usage: RunBudgetUsage): BudgetCheckResult;
+/**
+ * Whether a specific hypothesis has reached its per-hypothesis round limit —
+ * the input `../../ir/src/hypothesis.ts`'s `deriveHypothesisState` needs for
+ * its `roundLimitReached` field. A thin, named convenience over
+ * {@link checkRunBudget} so a caller does not have to re-derive "does this
+ * one hypothesis's own cap show up in `exceeded`" by hand.
+ */
+export declare function hypothesisRoundLimitReached(budget: InvestigationBudget, usage: HypothesisBudgetUsage): boolean;
+//# sourceMappingURL=budget.d.ts.map

package/dist/governance/budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.d.ts","sourceRoot":"","sources":["../../src/governance/budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,yDAAyD;AACzD,MAAM,WAAW,mBAAmB;IAClC,kGAAkG;IAClG,QAAQ,CAAC,wBAAwB,EAAE,MAAM,CAAC;IAC1C,sDAAsD;IACtD,QAAQ,CAAC,yBAAyB,EAAE,MAAM,CAAC;IAC3C,8EAA8E;IAC9E,QAAQ,CAAC,2BAA2B,EAAE,MAAM,CAAC;IAC7C,6CAA6C;IAC7C,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;CACvC;AAED;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,EAAE,mBAK1C,CAAC;AAEF,iDAAiD;AACjD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,6EAA6E;AAC7E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,6GAA6G;IAC7G,QAAQ,CAAC,cAAc,EAAE,SAAS,qBAAqB,EAAE,CAAC;CAC3D;AAED,eAAO,MAAM,gBAAgB,2HAKnB,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9D,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,GAAG,EAAE,aAAa,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,sFAAsF;IACtF,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,gGAAgG;IAChG,QAAQ,CAAC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACjD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,mBAAmB,EAAE,KAAK,EAAE,cAAc,GAAG,iBAAiB,CAuCpG;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,mBAAmB,EAC3B,KAAK,EAAE,qBAAqB,GAC3B,OAAO,CAKT"}