@descryy/core 0.1.0

package/dist/validation/join-substitution.d.ts

@@ -0,0 +1,186 @@
+/**
+ * DEC-166 — the join/identity substitution control for `USES_API`.
+ *
+ * There are two different things called "`USES_API` control" and conflating
+ * them is why the row looked unreachable. **Source fidelity** — does a call
+ * site's text really support the edge's claim — is
+ * `bench/precision-adjudicate.mjs`'s job and is almost entirely
+ * `null`-producing (NOTE-C). **Join / identity fidelity** — does the endpoint
+ * id a caller's edge targets correspond, and *only* correspond, to the route
+ * an independent producer says is served there — is this file's job, and it
+ * is the layer the numbers this project publishes are actually made of.
+ *
+ * ## The instrument
+ *
+ * For every joined `USES_API` edge:
+ *
+ * 1. Take the **population** — every `SERVES_API`-linked route in the same
+ *    repository, deduplicated by (method, normalised template). A fact
+ *    produced by a *different pass* than the one under test.
+ * 2. **Exclude** any route identical in (method, template) to the edge's true
+ *    target. A group of one substitutes onto itself, which is not a wrong
+ *    target. This exclusion is load-bearing: without it every draw would match
+ *    by construction and the control would manufacture false acceptances.
+ * 3. Substitute a different route from that population, holding the caller's
+ *    raw evidence fixed.
+ * 4. Re-run the same identity computation against the substituted target.
+ * 5. **Expect refusal, always.** The substituted target's identity did not
+ *    come from the rule under test and did not come from the caller — it came
+ *    from an independent producer, so the harness can say why the seeded value
+ *    is wrong without consulting the rule being tested. That is precisely what
+ *    NOTE-C limit (a) requires and address-keyed source rules could not give.
+ *
+ * **Threshold 0%, and it is not a dial.** Wrongness here is established by an
+ * independent producer, so 0% is the honest floor rather than a number picked
+ * to accommodate anything. A non-zero acceptance is a row to read, never a
+ * ceiling to raise.
+ *
+ * ## What this control is, honestly, and what it is not
+ *
+ * On a correct implementation this control is **structurally** 0%: the
+ * caller's evidence normalises onto its own target, the population is
+ * deduplicated by that same identity, and every other group is by definition
+ * a different string. That is not a weakness dressed up as a floor — it is
+ * what a 0% floor *means*, and it is why the number is not a dial. Its value
+ * is as a **regression detector over the normalisation layer**: change
+ * `normaliseEndpointPath` (or the DEC-097 base composition, or the method
+ * half of the identity) so that it discards discriminating information, and
+ * two genuinely distinct routes collapse onto one string — at which point the
+ * caller's evidence supports a route it never called and the acceptance rate
+ * leaves zero. It is a detector for the *class* of suspect join, not a rule
+ * that says which flagged rows are wrong; a flagged row still needs a
+ * decision, the same way DEC-163's own open question does.
+ *
+ * ## Why the exclusion key is fixed while the identity under test is not
+ *
+ * `options.identity` exists so a deliberately degraded identity can be run
+ * through the same instrument and the control observed to fire — this repo's
+ * standing bar for an instrument (DEC-162's seeded-grader work): a control
+ * that has never been seen to fire proves nothing. The population's dedup and
+ * step 2's exclusion deliberately do **not** use it. They use the engine's
+ * fixed `endpointQsp`, because they are arithmetic over an independently
+ * produced route table, not the thing under test. If the exclusion used the
+ * identity under test, a degraded identity would collapse the whole
+ * population into the target's own group, every candidate would be excluded,
+ * and the run would report `UNCONTROLLABLE` — the defect hiding inside the
+ * one state that is explicitly not a pass. `join-substitution.test.ts` pins
+ * exactly that.
+ */
+/**
+ * One route from the independently-produced side: a `SERVES_API`-linked
+ * route's own declared method and path template.
+ */
+export interface SubstitutionRoute {
+    readonly method: string;
+    readonly path: string;
+    /** Reporting only — never part of any key. */
+    readonly label?: string;
+}
+/**
+ * One joined `USES_API` edge, reduced to the caller's own raw evidence plus
+ * the target it actually joined to.
+ *
+ * `basePath` is DEC-097's base with the origin already stripped and the path
+ * prefix kept; `written` is the path exactly as it appears at the call site.
+ * The composition is `basePath + written` and nothing else — re-implementing
+ * it here is how the instrument and the engine drift into disagreeing about
+ * what a join even is.
+ */
+export interface SubstitutionCaller {
+    /** Where the call site is, for reporting only. */
+    readonly at: string;
+    readonly method: string;
+    readonly basePath: string;
+    readonly written: string;
+    /** The joined endpoint's own (method, template), as the graph stores it. */
+    readonly targetMethod: string;
+    readonly targetPath: string;
+}
+/**
+ * The three states in which the control has no material to run against.
+ *
+ * Same third-state discipline as DEC-162: none of these counts toward a
+ * numerator or a denominator, and a repository reporting one has said nothing
+ * about whether its join logic is sound — it has said it has no material to
+ * test it against, which is a fact about the corpus, not the engine.
+ */
+export type SubstitutionUncontrollable = {
+    readonly code: "POPULATION_ZERO";
+    readonly detail: string;
+} | {
+    readonly code: "POPULATION_UNDER_TWO";
+    readonly detail: string;
+} | {
+    readonly code: "NO_JOINED_EDGES";
+    readonly detail: string;
+};
+/**
+ * A substituted route the caller's own evidence accepted. Must never happen.
+ *
+ * `trueTarget` and `substituted` are the **fixed** group keys, not the
+ * identity under test — a flagged row has to name two routes a human can go
+ * and read, and under a degraded identity the string under test is precisely
+ * the one that no longer distinguishes them. `collapsedTo` is that string:
+ * the value both the caller's evidence and the substituted route produced.
+ */
+export interface FlaggedSubstitution {
+    readonly at: string;
+    /** The route the edge actually joined to, by fixed group key. */
+    readonly trueTarget: string;
+    /** The independently-real route substituted in, by fixed group key. */
+    readonly substituted: string;
+    /** The identity string the caller's evidence and the substitute both produced. */
+    readonly collapsedTo: string;
+}
+/**
+ * A joined edge whose stored target its own raw evidence does not rebuild.
+ *
+ * Reported separately from an acceptance because it is a different statement:
+ * an acceptance says the evidence supports more than one route, this says the
+ * evidence does not support the route the edge claims. Both are defects; only
+ * the first is what the substitution draw measures.
+ */
+export interface UnreproducibleJoin {
+    readonly at: string;
+    /** What the caller's own raw evidence produced, under the identity in force. */
+    readonly derived: string;
+    /** The route the edge claims, by fixed group key. */
+    readonly trueTarget: string;
+}
+export interface JoinSubstitutionReport {
+    /** True only when a substitution was actually drawn. `UNCONTROLLABLE` is never a pass. */
+    readonly controllable: boolean;
+    readonly uncontrollable?: SubstitutionUncontrollable;
+    /** Distinct routes after dedup by (method, normalised template). */
+    readonly population: number;
+    /** Joined `USES_API` edges considered. */
+    readonly callers: number;
+    /** The denominator: the sum over callers of that caller's own candidate count. */
+    readonly substitutions: number;
+    /** The numerator. The floor is 0 and it is not a dial. */
+    readonly accepted: number;
+    /** `null` rather than 0 when nothing was drawn — 0/0 is not 0%. */
+    readonly acceptanceRate: number | null;
+    readonly flagged: readonly FlaggedSubstitution[];
+    readonly unreproducible: readonly UnreproducibleJoin[];
+}
+export interface JoinSubstitutionOptions {
+    /**
+     * The identity computation under test. Defaults to the engine's own
+     * `endpointQsp`, which is the only value any real run should use — see this
+     * file's header for why the seam exists and why the exclusion key does not
+     * share it.
+     */
+    readonly identity?: (method: string, path: string) => string;
+}
+/**
+ * Run the control over one repository's joined edges and route table.
+ *
+ * Deterministic and exhaustive: every candidate in the population is drawn for
+ * every caller, never a fixed-N sample. Route tables are frequently far below
+ * any fixed draw size — axum shipped 18/18, full population — and a fixed-N
+ * bar would make this layer structurally uncontrollable for exactly the
+ * repositories with the smallest, most auditable route tables.
+ */
+export declare function runJoinSubstitutionControl(callers: readonly SubstitutionCaller[], routes: readonly SubstitutionRoute[], options?: JoinSubstitutionOptions): JoinSubstitutionReport;
+//# sourceMappingURL=join-substitution.d.ts.map

package/dist/validation/join-substitution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"join-substitution.d.ts","sourceRoot":"","sources":["../../src/validation/join-substitution.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AAIH;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,kBAAkB;IACjC,kDAAkD;IAClD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,4EAA4E;IAC5E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,0BAA0B,GAClC;IAAE,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC7D;IAAE,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAClE;IAAE,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAElE;;;;;;;;GAQG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,uEAAuE;IACvE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,kFAAkF;IAClF,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,gFAAgF;IAChF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,qDAAqD;IACrD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,sBAAsB;IACrC,0FAA0F;IAC1F,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,cAAc,CAAC,EAAE,0BAA0B,CAAC;IACrD,oEAAoE;IACpE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,0CAA0C;IAC1C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,kFAAkF;IAClF,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,0DAA0D;IAC1D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,mEAAmE;IACnE,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACjD,QAAQ,CAAC,cAAc,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACxD;AAED,MAAM,WAAW,uBAAuB;IACtC;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;CAC9D;AAKD;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,SAAS,kBAAkB,EAAE,EACtC,MAAM,EAAE,SAAS,iBAAiB,EAAE,EACpC,OAAO,GAAE,uBAA4B,GACpC,sBAAsB,CAwHxB"}

package/dist/validation/join-substitution.js

@@ -0,0 +1,191 @@
+/**
+ * DEC-166 — the join/identity substitution control for `USES_API`.
+ *
+ * There are two different things called "`USES_API` control" and conflating
+ * them is why the row looked unreachable. **Source fidelity** — does a call
+ * site's text really support the edge's claim — is
+ * `bench/precision-adjudicate.mjs`'s job and is almost entirely
+ * `null`-producing (NOTE-C). **Join / identity fidelity** — does the endpoint
+ * id a caller's edge targets correspond, and *only* correspond, to the route
+ * an independent producer says is served there — is this file's job, and it
+ * is the layer the numbers this project publishes are actually made of.
+ *
+ * ## The instrument
+ *
+ * For every joined `USES_API` edge:
+ *
+ * 1. Take the **population** — every `SERVES_API`-linked route in the same
+ *    repository, deduplicated by (method, normalised template). A fact
+ *    produced by a *different pass* than the one under test.
+ * 2. **Exclude** any route identical in (method, template) to the edge's true
+ *    target. A group of one substitutes onto itself, which is not a wrong
+ *    target. This exclusion is load-bearing: without it every draw would match
+ *    by construction and the control would manufacture false acceptances.
+ * 3. Substitute a different route from that population, holding the caller's
+ *    raw evidence fixed.
+ * 4. Re-run the same identity computation against the substituted target.
+ * 5. **Expect refusal, always.** The substituted target's identity did not
+ *    come from the rule under test and did not come from the caller — it came
+ *    from an independent producer, so the harness can say why the seeded value
+ *    is wrong without consulting the rule being tested. That is precisely what
+ *    NOTE-C limit (a) requires and address-keyed source rules could not give.
+ *
+ * **Threshold 0%, and it is not a dial.** Wrongness here is established by an
+ * independent producer, so 0% is the honest floor rather than a number picked
+ * to accommodate anything. A non-zero acceptance is a row to read, never a
+ * ceiling to raise.
+ *
+ * ## What this control is, honestly, and what it is not
+ *
+ * On a correct implementation this control is **structurally** 0%: the
+ * caller's evidence normalises onto its own target, the population is
+ * deduplicated by that same identity, and every other group is by definition
+ * a different string. That is not a weakness dressed up as a floor — it is
+ * what a 0% floor *means*, and it is why the number is not a dial. Its value
+ * is as a **regression detector over the normalisation layer**: change
+ * `normaliseEndpointPath` (or the DEC-097 base composition, or the method
+ * half of the identity) so that it discards discriminating information, and
+ * two genuinely distinct routes collapse onto one string — at which point the
+ * caller's evidence supports a route it never called and the acceptance rate
+ * leaves zero. It is a detector for the *class* of suspect join, not a rule
+ * that says which flagged rows are wrong; a flagged row still needs a
+ * decision, the same way DEC-163's own open question does.
+ *
+ * ## Why the exclusion key is fixed while the identity under test is not
+ *
+ * `options.identity` exists so a deliberately degraded identity can be run
+ * through the same instrument and the control observed to fire — this repo's
+ * standing bar for an instrument (DEC-162's seeded-grader work): a control
+ * that has never been seen to fire proves nothing. The population's dedup and
+ * step 2's exclusion deliberately do **not** use it. They use the engine's
+ * fixed `endpointQsp`, because they are arithmetic over an independently
+ * produced route table, not the thing under test. If the exclusion used the
+ * identity under test, a degraded identity would collapse the whole
+ * population into the target's own group, every candidate would be excluded,
+ * and the run would report `UNCONTROLLABLE` — the defect hiding inside the
+ * one state that is explicitly not a pass. `join-substitution.test.ts` pins
+ * exactly that.
+ */
+import { endpointQsp } from "@descryy/ir";
+/** The fixed key: the engine's identity, never the one under test. */
+const groupKey = (method, path) => endpointQsp(method, path);
+/**
+ * Run the control over one repository's joined edges and route table.
+ *
+ * Deterministic and exhaustive: every candidate in the population is drawn for
+ * every caller, never a fixed-N sample. Route tables are frequently far below
+ * any fixed draw size — axum shipped 18/18, full population — and a fixed-N
+ * bar would make this layer structurally uncontrollable for exactly the
+ * repositories with the smallest, most auditable route tables.
+ */
+export function runJoinSubstitutionControl(callers, routes, options = {}) {
+    const identity = options.identity ?? endpointQsp;
+    // Step 1 — the population, deduplicated by the engine's own identity.
+    const population = new Map();
+    for (const route of routes) {
+        const key = groupKey(route.method, route.path);
+        if (!population.has(key))
+            population.set(key, route);
+    }
+    const empty = {
+        population: population.size,
+        callers: callers.length,
+        substitutions: 0,
+        accepted: 0,
+        acceptanceRate: null,
+        flagged: [],
+        unreproducible: [],
+    };
+    // The route legs are checked before the caller leg, in the order DEC-166
+    // names them: a repository with neither routes nor callers is first of all a
+    // repository that serves nothing.
+    if (population.size === 0) {
+        return {
+            controllable: false,
+            uncontrollable: {
+                code: "POPULATION_ZERO",
+                detail: "no SERVES_API-linked route in this repository — either no route producer ran, or the " +
+                    "repository is a pure consumer. Nothing independently produced to substitute.",
+            },
+            ...empty,
+        };
+    }
+    if (population.size < 2) {
+        return {
+            controllable: false,
+            uncontrollable: {
+                code: "POPULATION_UNDER_TWO",
+                detail: `${population.size} distinct route after dedup by (method, normalised template) — no ` +
+                    "candidate exists that is not the true target's own group.",
+            },
+            ...empty,
+        };
+    }
+    if (callers.length === 0) {
+        return {
+            controllable: false,
+            uncontrollable: {
+                code: "NO_JOINED_EDGES",
+                detail: `${population.size} routes served and zero USES_API edges joined — a pure-provider ` +
+                    "repository. Nothing to substitute *for*; not a vacuous pass.",
+            },
+            ...empty,
+        };
+    }
+    const flagged = [];
+    const unreproducible = [];
+    let substitutions = 0;
+    let accepted = 0;
+    for (const caller of callers) {
+        // The caller's raw evidence, re-composed and re-normalised. DEC-097's
+        // composition is `basePath + written`; DEC-170's query strip and DEC-163's
+        // method+template identity are inside `identity` itself.
+        const derived = identity(caller.method, `${caller.basePath}${caller.written}`);
+        const trueIdentity = identity(caller.targetMethod, caller.targetPath);
+        // Step 2 — exclude the true target's own group, under the fixed key.
+        const excluded = groupKey(caller.targetMethod, caller.targetPath);
+        if (derived !== trueIdentity) {
+            unreproducible.push({ at: caller.at, derived, trueTarget: excluded });
+        }
+        for (const [key, route] of population) {
+            if (key === excluded)
+                continue;
+            substitutions += 1;
+            // Steps 3-5 — hold the caller's evidence fixed, re-run the identity
+            // against the substituted target, expect refusal.
+            if (identity(route.method, route.path) === derived) {
+                accepted += 1;
+                flagged.push({
+                    at: caller.at,
+                    trueTarget: excluded,
+                    substituted: key,
+                    collapsedTo: derived,
+                });
+            }
+        }
+    }
+    return {
+        // `population >= 2` guarantees every caller keeps at least one candidate —
+        // the target's group is at most one of them — so `substitutions > 0` here
+        // is structural rather than hoped for. Asserted through the returned flag
+        // anyway, so a future change to the population arithmetic cannot turn an
+        // empty draw into a silent pass.
+        controllable: substitutions > 0,
+        ...(substitutions > 0
+            ? {}
+            : {
+                uncontrollable: {
+                    code: "POPULATION_UNDER_TWO",
+                    detail: "every candidate was excluded as the true target's own group",
+                },
+            }),
+        population: population.size,
+        callers: callers.length,
+        substitutions,
+        accepted,
+        acceptanceRate: substitutions === 0 ? null : accepted / substitutions,
+        flagged,
+        unreproducible,
+    };
+}
+//# sourceMappingURL=join-substitution.js.map

package/dist/validation/join-substitution.js.map

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

package/dist/validation/migrations.d.ts

@@ -0,0 +1,133 @@
+/**
+ * The format half of §15.3's rollback-readiness check — migrations read from the
+ * repository as text.
+ *
+ * Same argument as `sources.ts`: DDL is a **format, not a language**, so reading
+ * it names nothing the Canonical IR boundary forbids. Same limit, too — this half
+ * sees only what is written as DDL, and DEC-122 measured exactly how little that
+ * is: **zero `.sql` files inside a migration directory across fifteen reference
+ * repositories**, against 3,301 migrations written as program code. The code half
+ * arrives through `attrs.migrationOps` and is an adapter's to produce.
+ *
+ * ## The scope fence, which is what makes this Class A
+ *
+ * Appendix B.3 settles rollback readiness as Class A against two sources that
+ * called it B, and the resolution turns entirely on what is claimed:
+ *
+ * > **"this migration contains a destructive operation"** — a fact, and a
+ * > deterministic pattern match establishes it.
+ * >
+ * > **"this migration is unsafe to roll back"** — an inference, requiring the
+ * > consumer-impact analysis §15.3 explicitly separates this check from.
+ *
+ * Every sentence produced here is written to stay behind that fence. The finding
+ * names the operation, the object and the line; it does not characterise risk.
+ *
+ * ## What counts as destructive, and the things deliberately left out
+ *
+ * Only operations that **destroy data**. `DROP INDEX`, `DROP CONSTRAINT`,
+ * `DROP VIEW`, `DROP TRIGGER` and `DROP FUNCTION` are all recoverable by
+ * re-running the definition and none of them loses a row, so including them
+ * would triple the finding count with statements nobody needs to see. A rename
+ * is carried separately: the data survives, so it is not the same claim as a
+ * drop, but every reader of the old name breaks.
+ *
+ * ## Section detection is tool-blind on purpose
+ *
+ * Directional migrations mark their halves with a comment directive. Matching a
+ * specific tool's spelling would put that tool's name in engine code — rule 1,
+ * the violation the boundary lint already caught once in this directory. So the
+ * **shape** is matched instead: a comment carrying a directive word followed by
+ * an up/down keyword, in either the `+name Up` form or a bare `-- Up`. Any tool
+ * using that shape works; none of them is named.
+ */
+/**
+ * What an operation does to data.
+ *
+ * `RENAME` is separate because it is a different claim: the rows survive, and
+ * what breaks is every reader of the old name.
+ */
+export type DestructiveKind = "DROP_TABLE" | "DROP_COLUMN" | "DROP_SCHEMA" | "TRUNCATE" | "RENAME";
+/**
+ * Which half of a directional migration a statement sits in.
+ *
+ * `reverse` is the whole reason this field exists — a drop there undoes the
+ * forward migration and is supposed to be present. `unknown` is not a synonym
+ * for `forward`: it means the file declares no direction, and DEC-122 refuses to
+ * report on it.
+ */
+export type MigrationSection = "forward" | "reverse" | "unknown";
+export interface MigrationOp {
+    readonly kind: DestructiveKind;
+    /** The table, column or schema named by the statement, as written. */
+    readonly target: string;
+    readonly line: number;
+    readonly section: MigrationSection;
+    /** `DROP … IF EXISTS` — an idempotent guard rather than an intentional drop. */
+    readonly guarded: boolean;
+}
+export interface MigrationFile {
+    readonly file: string;
+    readonly ops: readonly MigrationOp[];
+    /**
+     * Objects this file creates, with the line, so a drop of one of them can be
+     * discounted — and so the *order* is known. Create-then-drop is a temporary
+     * object; drop-then-create is an idempotent setup script. Different reasons,
+     * and without the line they are indistinguishable.
+     */
+    readonly creates: readonly {
+        readonly name: string;
+        readonly line: number;
+    }[];
+    /** True when the file marks a forward/reverse split at all. */
+    readonly directional: boolean;
+}
+export interface MigrationScan {
+    readonly files: readonly MigrationFile[];
+    readonly unreadable: readonly string[];
+    readonly truncated: boolean;
+    /** Files that looked like migrations and held no recognised statement. */
+    readonly unparsed: number;
+}
+export interface MigrationScanOptions {
+    readonly maxDepth?: number;
+    readonly maxFiles?: number;
+    /**
+     * The active adapters' declared noise directories (DEC-110). Shared with the
+     * config-surface walk through `skipDirectory`, so the two cannot disagree about
+     * what counts as vendored.
+     */
+    readonly noiseDirectories?: readonly string[];
+}
+interface Statement {
+    readonly text: string;
+    readonly line: number;
+}
+/**
+ * Split DDL on `;`, ignoring separators inside strings, quoted identifiers and
+ * comments.
+ *
+ * A plain split would cut a statement in half at the first semicolon inside a
+ * default value, which is a real thing to find in a migration.
+ *
+ * **This duplicates the splitter in `adapter-sql`, deliberately and with the
+ * cost recorded** (DEC-122). `@descryy/core` cannot depend on an adapter —
+ * adapters depend on core — so the alternative to a second copy is inverting the
+ * boundary the repository split exists to hold. If a third caller appears, the
+ * right home is `@descryy/ir`.
+ */
+export declare function statements(sql: string): readonly Statement[];
+/**
+ * Classify one statement.
+ *
+ * Returns `null` for everything unrecognised, which is the overwhelming
+ * majority and is correct: an unclassified statement is not a silent pass, it is
+ * counted by the caller and disclosed.
+ */
+export declare function classifyStatement(text: string, line: number, section: MigrationSection): MigrationOp | null;
+/** Read one migration file's operations, tracking which section each sits in. */
+export declare function readMigration(text: string): Omit<MigrationFile, "file">;
+/** Walk the repository for migration files written as DDL. */
+export declare function scanMigrations(root: string, options?: MigrationScanOptions): MigrationScan;
+export {};
+//# sourceMappingURL=migrations.d.ts.map

package/dist/validation/migrations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrations.d.ts","sourceRoot":"","sources":["../../src/validation/migrations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAOH;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GACvB,YAAY,GACZ,aAAa,GACb,aAAa,GACb,UAAU,GACV,QAAQ,CAAC;AAEb;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAEjE,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,sEAAsE;IACtE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;IACnC,gFAAgF;IAChF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,SAAS,WAAW,EAAE,CAAC;IACrC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,SAAS;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC9E,+DAA+D;IAC/D,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;CAC/B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IACzC,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC/C;AAkBD,UAAU,SAAS;IACjB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,SAAS,EAAE,CA6D5D;AAMD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,gBAAgB,GACxB,WAAW,GAAG,IAAI,CA2DpB;AAYD,iFAAiF;AACjF,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC,aAAa,EAAE,MAAM,CAAC,CAwCvE;AAED,8DAA8D;AAC9D,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,oBAAyB,GAAG,aAAa,CA6D9F"}