@descryy/core 0.3.0 → 0.5.0

package/dist/validation/join-substitution.js

@@ -1,86 +1,17 @@
 /**
- * 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.
+ * DEC-166's join/identity control for `USES_API` (distinct from source fidelity in `bench/precision-adjudicate.mjs`, NOTE-C).
+ * Substitutes an independent route, keyed by the fixed engine identity — never `options.identity` under test — and expects refusal always.
+ * Threshold 0%: a DEC-097 normalisation regression detector, not a dial.
  */
 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.
- */
+/** Runs the control over one repository's joined edges and route table.
+ *  Deterministic and exhaustive — every candidate is drawn for every caller,
+ *  never a fixed-N sample (axum shipped 18/18, full population). */
 export function runJoinSubstitutionControl(callers, routes, options = {}) {
     const identity = options.identity ?? endpointQsp;
-    // Step 1 — the population, deduplicated by the engine's own identity.
+    // Population, deduplicated by the engine's own identity.
     const population = new Map();
     for (const route of routes) {
         const key = groupKey(route.method, route.path);
@@ -96,9 +27,7 @@ export function runJoinSubstitutionControl(callers, routes, options = {}) {
         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.
+    // Route legs checked before caller leg, per DEC-166's order.
     if (population.size === 0) {
         return {
             controllable: false,
@@ -137,12 +66,10 @@ export function runJoinSubstitutionControl(callers, routes, options = {}) {
     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.
+        // Caller's raw evidence, recomposed per DEC-097; DEC-170/DEC-163 are inside `identity`.
         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.
+        // 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 });
@@ -151,8 +78,7 @@ export function runJoinSubstitutionControl(callers, routes, options = {}) {
             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.
+            // Hold the caller's evidence fixed, re-run against the substituted target.
             if (identity(route.method, route.path) === derived) {
                 accepted += 1;
                 flagged.push({
@@ -165,11 +91,8 @@ export function runJoinSubstitutionControl(callers, routes, options = {}) {
         }
     }
     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.
+        // population >= 2 guarantees substitutions > 0 structurally; asserted via
+        // the returned flag so a future arithmetic change can't silently pass.
         controllable: substitutions > 0,
         ...(substitutions > 0
             ? {}

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

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

package/dist/validation/migration-integrity.d.ts

@@ -0,0 +1,72 @@
+/** Migration-integrity: location + revision-chain findings from migrationRevision/
+ *  migrationDownRevision/migrationDir (UAT round 3's 3rd of 4 missed defects). Migrations
+ *  directory is inferred by graph consensus, never hardcoded; `"unknown"` downRevision is refused, never null. */
+import type { ResolutionLevel } from "@descryy/ir";
+import type { AdjacencyProvider, QueryResult } from "../query/provider.ts";
+/** null = declared root. string = single parent. array = merge revision. "unknown" = unreadable
+ *  as any of the three — refused, never a synonym for null. */
+export type MigrationDownRevision = string | readonly string[] | null | "unknown";
+export interface MigrationRevisionInfo {
+    readonly revision: string;
+    readonly downRevision: MigrationDownRevision;
+    /** This file's own containing directory. `""` for the repository root. */
+    readonly dir: string;
+    readonly file: string;
+    readonly resolution: ResolutionLevel;
+}
+export type MigrationIntegrityFindingKind = "MIGRATION_OUTSIDE_DIRECTORY" | "BROKEN_REVISION_CHAIN";
+export interface MigrationIntegrityFinding {
+    readonly kind: MigrationIntegrityFindingKind;
+    readonly file: string;
+    readonly revision: string;
+    /** The sentence a developer reads. */
+    readonly detail: string;
+    readonly resolution: ResolutionLevel;
+}
+export interface MigrationIntegrityReport {
+    readonly findings: readonly MigrationIntegrityFinding[];
+    /** The count before `maxFindings` capped it — P27's disclosed remainder: a structured field, not only a prose note. */
+    readonly findingsTotal: number;
+    readonly examined: {
+        /** Modules carrying a well-formed migrationRevision/migrationDownRevision/migrationDir triple. */
+        readonly modulesWithRevision: number;
+    };
+    /** The directory this run inferred as the project's migrations directory. Null when no consensus could be established. */
+    readonly migrationsDirectory: string | null;
+    /** True when at least one module in the graph carried migration revision attrs. */
+    readonly ran: boolean;
+    readonly withheld: {
+        /** Declared roots — never a finding. Counted for the same reason `rollback.ts` counts its refusals. */
+        readonly root: number;
+        /** downRevision recorded as "unknown" — refused, never reported as broken. */
+        readonly unreadable: number;
+    };
+}
+export interface MigrationIntegrityOptions {
+    /** Restrict findings to these repo-relative files. The revision registry itself always spans the whole graph — see the header. */
+    readonly files?: readonly string[];
+    readonly maxFindings?: number;
+    /** Cap on file-scoped nodes enumerated. Truncation is reported. */
+    readonly limit?: number;
+}
+/** Pulls migrationRevision/migrationDownRevision/migrationDir off a node, refusing anything
+ *  malformed. A downRevision that isn't null/"unknown"/a non-empty string or string array is
+ *  dropped, not guessed at — defaulting it would manufacture a chain claim never made. */
+export declare function readMigrationRevision(attrs: Readonly<Record<string, unknown>> | undefined, file: string, resolution: ResolutionLevel): MigrationRevisionInfo | null;
+export declare function checkMigrationIntegrity(provider: AdjacencyProvider, options?: MigrationIntegrityOptions): QueryResult<MigrationIntegrityReport>;
+/** `cross_pr`'s migration-heads check: would merging these leave more than one head? Computed
+ *  over the graph as built, not base-vs-head separately. An unreadable ("unknown") down-revision
+ *  is counted and disclosed, never treated as absent — that could wrongly promote a revision with an unread child. */
+export interface MigrationHeadsReport {
+    /** Revisions with no other migration in this graph declaring them as a parent. More than one means a fork. */
+    readonly heads: readonly string[];
+    readonly examined: {
+        readonly modulesWithRevision: number;
+    };
+    /** True when at least one module in the graph carried a migration revision. */
+    readonly ran: boolean;
+    /** Down-revisions recorded as "unknown" — a head count computed alongside these is a lower bound. */
+    readonly unreadableChains: number;
+}
+export declare function checkMigrationHeads(provider: AdjacencyProvider, options?: Pick<MigrationIntegrityOptions, "limit">): QueryResult<MigrationHeadsReport>;
+//# sourceMappingURL=migration-integrity.d.ts.map

package/dist/validation/migration-integrity.d.ts.map

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

package/dist/validation/migration-integrity.js

@@ -0,0 +1,238 @@
+/** Migration-integrity: location + revision-chain findings from migrationRevision/
+ *  migrationDownRevision/migrationDir (UAT round 3's 3rd of 4 missed defects). Migrations
+ *  directory is inferred by graph consensus, never hardcoded; `"unknown"` downRevision is refused, never null. */
+import { fileScopedNodes } from "./nodes.js";
+import { MIGRATION_DIRECTORY } from "./migrations.js";
+const DEFAULT_MAX_FINDINGS = 25;
+/** Below this many modules, a directory count isn't a consensus — one migration can't disagree
+ *  with itself, and two tied at one apiece isn't a majority either way. */
+const MIN_MODULES_FOR_CONSENSUS = 2;
+function isNonEmptyStringArray(value) {
+    return Array.isArray(value) && value.length > 0 && value.every((v) => typeof v === "string" && v !== "");
+}
+/** Pulls migrationRevision/migrationDownRevision/migrationDir off a node, refusing anything
+ *  malformed. A downRevision that isn't null/"unknown"/a non-empty string or string array is
+ *  dropped, not guessed at — defaulting it would manufacture a chain claim never made. */
+export function readMigrationRevision(attrs, file, resolution) {
+    if (attrs === undefined)
+        return null;
+    const revision = attrs["migrationRevision"];
+    const downRevision = attrs["migrationDownRevision"];
+    const dir = attrs["migrationDir"];
+    if (typeof revision !== "string" || revision === "")
+        return null;
+    if (typeof dir !== "string")
+        return null;
+    let parsedDown;
+    if (downRevision === null)
+        parsedDown = null;
+    else if (downRevision === "unknown")
+        parsedDown = "unknown";
+    else if (typeof downRevision === "string" && downRevision !== "")
+        parsedDown = downRevision;
+    else if (isNonEmptyStringArray(downRevision))
+        parsedDown = downRevision;
+    else
+        return null;
+    return { revision, downRevision: parsedDown, dir, file, resolution };
+}
+/** Human-readable name for a directory, the root included. */
+function nameDir(dir) {
+    return dir === "" ? "the repository root" : dir;
+}
+/** The directory most modules agree on. A tie is broken toward one matching migrations.ts's
+ *  generic directory shape (a shape check, not a guess). A tie surviving that is genuinely
+ *  ambiguous — refused and disclosed, never guessed. */
+function consensusDirectory(infos) {
+    if (infos.length < MIN_MODULES_FOR_CONSENSUS) {
+        return {
+            dir: null,
+            note: `Only ${infos.length} module(s) in the graph carry a migration revision, which is not ` +
+                "enough to establish which directory this project keeps its migrations in. " +
+                "MIGRATION_OUTSIDE_DIRECTORY did not run.",
+        };
+    }
+    const counts = new Map();
+    for (const info of infos)
+        counts.set(info.dir, (counts.get(info.dir) ?? 0) + 1);
+    const sorted = [...counts.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+    const top = sorted[0];
+    const tied = sorted.filter(([, count]) => count === top[1]);
+    if (tied.length === 1)
+        return { dir: top[0], note: null };
+    const matching = tied.filter(([dir]) => MIGRATION_DIRECTORY.test(dir));
+    if (matching.length === 1)
+        return { dir: matching[0][0], note: null };
+    return {
+        dir: null,
+        note: `${tied.length} director(ies) are equally common among the migration-revision-carrying ` +
+            `module(s) this run saw (${tied.map(([dir]) => nameDir(dir)).join(", ")}), so no single ` +
+            "directory could be established as the project's migrations directory. " +
+            "MIGRATION_OUTSIDE_DIRECTORY did not run.",
+    };
+}
+/** Every well-formed migration triple in the graph — shared by `checkMigrationIntegrity` and
+ *  `checkMigrationHeads` so the two checks can't disagree on what counts as a migration node. */
+function collectMigrationRevisions(provider, limit) {
+    const nodes = fileScopedNodes(provider, limit);
+    const infos = [];
+    for (const node of nodes.nodes) {
+        const path = node.file;
+        if (path === null)
+            continue;
+        const info = readMigrationRevision(node.attrs, path, node.resolution);
+        if (info !== null)
+            infos.push(info);
+    }
+    infos.sort((a, b) => a.file.localeCompare(b.file));
+    return { infos, truncated: nodes.truncated };
+}
+export function checkMigrationIntegrity(provider, options = {}) {
+    const maxFindings = options.maxFindings ?? DEFAULT_MAX_FINDINGS;
+    const scoped = options.files === undefined ? null : new Set(options.files);
+    const notes = [];
+    // The revision registry spans the whole graph even when scoped to a diff — a down_revision
+    // often names a migration outside the diff, and directory consensus is a whole-repo fact.
+    const { infos, truncated: nodesTruncated } = collectMigrationRevisions(provider, options.limit);
+    const ran = infos.length > 0;
+    const revisionProvidedBy = new Map();
+    for (const info of infos) {
+        // First file wins for a stable answer between runs — same precedent as env.ts's requiredReads.
+        const existing = revisionProvidedBy.get(info.revision);
+        if (existing === undefined || info.file < existing.file)
+            revisionProvidedBy.set(info.revision, info);
+    }
+    const { dir: migrationsDirectory, note: consensusNote } = consensusDirectory(infos);
+    if (consensusNote !== null)
+        notes.push(consensusNote);
+    const findings = [];
+    const withheld = { root: 0, unreadable: 0 };
+    for (const info of infos) {
+        if (scoped !== null && !scoped.has(info.file))
+            continue;
+        if (migrationsDirectory !== null && info.dir !== migrationsDirectory) {
+            const peers = infos.filter((i) => i.dir === migrationsDirectory).length;
+            findings.push({
+                kind: "MIGRATION_OUTSIDE_DIRECTORY",
+                file: info.file,
+                revision: info.revision,
+                detail: `${info.file} carries a migration revision (${info.revision}) but sits in ` +
+                    `${nameDir(info.dir)}, not ${nameDir(migrationsDirectory)} — where ${peers} of the ` +
+                    `${infos.length} migration(s) this run saw live. A migration tool that only looks in ` +
+                    "one directory never reaches this file.",
+                resolution: info.resolution,
+            });
+        }
+        if (info.downRevision === null) {
+            withheld.root += 1;
+            continue;
+        }
+        if (info.downRevision === "unknown") {
+            withheld.unreadable += 1;
+            continue;
+        }
+        const parents = typeof info.downRevision === "string" ? [info.downRevision] : info.downRevision;
+        for (const parent of parents) {
+            if (revisionProvidedBy.has(parent))
+                continue;
+            findings.push({
+                kind: "BROKEN_REVISION_CHAIN",
+                file: info.file,
+                revision: info.revision,
+                detail: `${info.file}'s revision ${info.revision} names ${parent} as its parent, and no module ` +
+                    "in this graph provides a migration with that revision. Either the parent was never " +
+                    "read into this graph, or the chain is genuinely broken.",
+                resolution: info.resolution,
+            });
+        }
+    }
+    findings.sort((a, b) => a.file.localeCompare(b.file) || a.kind.localeCompare(b.kind) || a.revision.localeCompare(b.revision));
+    const kept = findings.slice(0, maxFindings);
+    if (!ran) {
+        notes.push("No module in the graph carries a migration revision. This check reads " +
+            "attrs.migrationRevision, attrs.migrationDownRevision and attrs.migrationDir on a " +
+            "file-scoped node, and no adapter supplied them on this run. This is not a result of the " +
+            "migration chain being intact.");
+    }
+    if (withheld.unreadable > 0) {
+        notes.push(`${withheld.unreadable} migration(s)' down-revision could not be read as a single parent, a ` +
+            'merge tuple or a declared root — recorded as "unknown" by the producer. Not reported: a ' +
+            "chain this run cannot read is not evidence that it is broken.");
+    }
+    if (scoped !== null) {
+        notes.push(`Findings were restricted to ${scoped.size} scoped file(s). The revision registry itself was ` +
+            "built from every migration-revision-carrying module in the graph, because a down_revision " +
+            "commonly names a parent outside the diff, and the migrations-directory consensus is a " +
+            "fact about the whole repository.");
+    }
+    if (kept.length < findings.length) {
+        notes.push(`${findings.length - kept.length} further finding(s) were withheld: a report is capped at ` +
+            `${maxFindings} so a short list stays worth reading. They were found, not missed.`);
+    }
+    if (nodesTruncated) {
+        notes.push("More files exist in the graph than were enumerated, so this check covers a prefix of the " +
+            "repository rather than all of it.");
+    }
+    let resolutionFloor = 4;
+    for (const finding of kept)
+        if (finding.resolution < resolutionFloor)
+            resolutionFloor = finding.resolution;
+    const stamp = { ...provider.baseStamp(), resolutionFloor };
+    return {
+        data: {
+            findings: kept,
+            findingsTotal: findings.length,
+            examined: { modulesWithRevision: infos.length },
+            migrationsDirectory,
+            ran,
+            withheld,
+        },
+        stamp,
+        truncated: nodesTruncated || kept.length < findings.length,
+        notes,
+    };
+}
+export function checkMigrationHeads(provider, options = {}) {
+    const { infos, truncated } = collectMigrationRevisions(provider, options.limit);
+    const notes = [];
+    const ran = infos.length > 0;
+    const namedAsParent = new Set();
+    let unreadableChains = 0;
+    for (const info of infos) {
+        if (info.downRevision === null)
+            continue;
+        if (info.downRevision === "unknown") {
+            unreadableChains += 1;
+            continue;
+        }
+        const parents = typeof info.downRevision === "string" ? [info.downRevision] : info.downRevision;
+        for (const parent of parents)
+            namedAsParent.add(parent);
+    }
+    const heads = infos.map((i) => i.revision).filter((r) => !namedAsParent.has(r)).sort();
+    if (!ran) {
+        notes.push("No module in the graph carries a migration revision, so migration heads could not be " +
+            "counted. This is not a result of the chain having exactly one head.");
+    }
+    if (unreadableChains > 0) {
+        notes.push(`${unreadableChains} migration(s)' parent could not be read as any of the four recognised ` +
+            'shapes ("unknown"), so this head count is a lower bound: one of the listed heads may in ' +
+            "fact have a child this run could not identify.");
+    }
+    if (truncated) {
+        notes.push("More files exist in the graph than were enumerated, so this head count covers a prefix of " +
+            "the repository rather than all of it.");
+    }
+    let resolutionFloor = 4;
+    for (const info of infos)
+        if (info.resolution < resolutionFloor)
+            resolutionFloor = info.resolution;
+    const stamp = { ...provider.baseStamp(), resolutionFloor };
+    return {
+        data: { heads, examined: { modulesWithRevision: infos.length }, ran, unreadableChains },
+        stamp,
+        truncated,
+        notes,
+    };
+}
+//# sourceMappingURL=migration-integrity.js.map

package/dist/validation/migration-integrity.js.map

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

package/dist/validation/migrations.d.ts

@@ -1,61 +1,14 @@
-/**
- * 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.
- */
+/** §15.3's rollback-readiness check, format half — DDL is a format, not a
+ *  language, so it stays below the IR boundary. DEC-122: zero `.sql` files
+ *  across 15 repos vs 3,301 migrations as code (adapter's territory).
+ *  Class A (Appx B.3): reports only "this drops data", never the inference
+ *  "unsafe to roll back". Section markers matched by shape, not tool name. */
+/** What an operation does to data. `RENAME` is separate — rows survive,
+ *  but every reader of the old name breaks. */
 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.
- */
+/** Which half of a directional migration a statement sits in. `reverse` is
+ *  supposed to contain drops (undoing forward). `unknown` ≠ `forward` — no
+ *  declared direction, and DEC-122 refuses to report on it. */
 export type MigrationSection = "forward" | "reverse" | "unknown";
 export interface MigrationOp {
     readonly kind: DestructiveKind;
@@ -69,12 +22,8 @@ export interface MigrationOp {
 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.
-     */
+    /** Objects this file creates, with line — so a later drop of one can be
+     *  discounted. Create-then-drop is temporary; drop-then-create is idempotent setup. */
     readonly creates: readonly {
         readonly name: string;
         readonly line: number;
@@ -92,38 +41,24 @@ export interface MigrationScan {
 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.
-     */
+    /** Adapters' declared noise dirs (DEC-110); shared with the config-surface
+     *  walk via `skipDirectory` so the two can't disagree. */
     readonly noiseDirectories?: readonly string[];
 }
+/** A directory holding migrations — path-based, not content-based, so a
+ *  `.sql` file in `schema/` (a definition, not a change) isn't misread.
+ *  Exported for `migration-integrity.ts`'s tie-break: a generic shape, no tool/framework name. */
+export declare const MIGRATION_DIRECTORY: RegExp;
 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`.
- */
+/** Splits DDL on `;`, skipping separators inside strings/identifiers/comments.
+ *  Duplicates `adapter-sql`'s splitter (core can't depend on an adapter,
+ *  DEC-122) — a third caller should move this to `@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.
- */
+/** Classifies one statement; `null` for unrecognised (the majority) is
+ *  correct — the caller counts and discloses it, not a silent pass. */
 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">;