@intentius/sql-yodeler 0.0.0-stage → 0.1.0

package/dist/versioned/postgres/executor.js

@@ -0,0 +1,172 @@
+/**
+ * Sending one migration statement to Postgres, the way chant's applier does
+ * (`postgres/apply/apply.ts`), with the history row that says it succeeded.
+ *
+ * ## Timeouts and retries
+ *
+ * Every statement runs with its own `lock_timeout` (default 5 s, the
+ * profile's `lockTimeoutMs`) and `statement_timeout` (the profile's
+ * `statementTimeoutMs`, default 60 s, for a catalog change; `scanTimeoutMs`,
+ * default none, for one that reads or rewrites rows). A statement blocked
+ * behind another session's lock gives up when the lock timeout passes
+ * (SQLSTATE 55P03) instead of queueing every later query on the table
+ * behind it, and is tried again after a pause that doubles each time (250
+ * ms, 500 ms, ...), up to `retries` more times (default 5). Any other error
+ * fails it at once.
+ *
+ * ## Transactions
+ *
+ * A statement chant marks `transactional` runs in a transaction of its own:
+ *
+ *     BEGIN; SET LOCAL lock_timeout ...; SET LOCAL statement_timeout ...;
+ *     <statement>; INSERT INTO <history> (... 'succeeded' ...); COMMIT
+ *
+ * so the statement and its `succeeded` row commit together or not at all.
+ * A runner killed anywhere in it leaves either both or neither: a statement
+ * whose latest row is `started` did not commit, and is sent again safely.
+ *
+ * A statement that may not run in a transaction block (`CREATE INDEX
+ * CONCURRENTLY`, `DROP INDEX CONCURRENTLY`) or that chant keeps out of one
+ * (`ALTER TYPE ... ADD VALUE`, whose label cannot be used in the transaction
+ * that adds it) runs alone, with `SET` for the session first; its
+ * `succeeded` row is written right after it, in a transaction of its own.
+ * A runner killed between the two leaves the statement run and its latest
+ * row `started`, and the next run sends it again.
+ *
+ * ## A failed CONCURRENTLY build
+ *
+ * `CREATE INDEX CONCURRENTLY` that fails (a lock timeout, a duplicate on a
+ * unique index, a cancel) leaves the index behind, INVALID: it is in the
+ * catalog, is maintained on every write, and is never used, and the next
+ * `CREATE INDEX` of that name fails because it exists. So before every
+ * attempt, the first, a retry, or a resume in a later run, and after every
+ * failure, an INVALID index of that name is dropped (`DROP INDEX
+ * CONCURRENTLY IF EXISTS`), and only an INVALID one: a valid index of that
+ * name is never touched.
+ */
+import { YodelError } from "../../project.js";
+import { pgIdent } from "../../history/postgres/index.js";
+/** SQLSTATE lock_not_available: the lock timeout passed. */
+export const LOCK_NOT_AVAILABLE = "55P03";
+export const DEFAULT_PG_TIMEOUTS = { lockTimeoutMs: 5_000, statementTimeoutMs: 60_000, scanTimeoutMs: 0 };
+export const DEFAULT_LOCK_RETRIES = 5;
+export const DEFAULT_RETRY_BASE_MS = 250;
+/** A statement failed; `error` is the server's message. */
+export class PgStatementError extends YodelError {
+    error;
+    code;
+    attempts;
+    constructor(error, code, attempts) {
+        super(error, 1);
+        this.error = error;
+        this.code = code;
+        this.attempts = attempts;
+        this.name = "PgStatementError";
+    }
+}
+const sqlstate = (e) => e && typeof e === "object" && "code" in e && typeof e.code === "string" ? e.code : undefined;
+const messageOf = (e) => (e instanceof Error ? e.message : String(e));
+const ms = (n) => `'${String(Math.max(0, Math.floor(n)))}ms'`;
+/** Whether a statement of `cls` reads or rewrites rows (chant's `scansRows`), so it runs with the scan timeout. */
+export const scansRows = (cls) => cls === "rewrite" || cls === "validate" || cls === "concurrently";
+const IDENT = String.raw `(?:"(?:[^"]|"")+"|[A-Za-z_][A-Za-z0-9_$]*)`;
+const CONCURRENT_INDEX = new RegExp(String.raw `^\s*CREATE\s+(?:UNIQUE\s+)?INDEX\s+CONCURRENTLY\s+(?:IF\s+NOT\s+EXISTS\s+)?(${IDENT})\s+ON\s+(?:ONLY\s+)?(?:(${IDENT})\s*\.\s*)?${IDENT}`, "i");
+const unquote = (id) => (id.startsWith('"') ? id.slice(1, -1).replace(/""/g, '"') : id.toLowerCase());
+/** The index a `CREATE INDEX CONCURRENTLY` builds, `schema.name` quoted, when the statement names its table's schema. */
+export function concurrentIndex(sql) {
+    const m = CONCURRENT_INDEX.exec(sql);
+    if (!m?.[1] || !m[2])
+        return undefined;
+    return `${pgIdent(unquote(m[2]))}.${pgIdent(unquote(m[1]))}`;
+}
+/** Drops `index` when it is there and INVALID. Returns whether it dropped it. */
+export async function dropInvalidIndex(client, index, timeouts, log) {
+    const [row] = await client.query("SELECT NOT i.indisvalid AS invalid FROM pg_catalog.pg_index i WHERE i.indexrelid = pg_catalog.to_regclass($1)", [index]);
+    if (row?.invalid !== true)
+        return false;
+    log(`  ${index} is INVALID, left by a CONCURRENTLY build that failed; dropping it before the build`);
+    await client.query(`SET lock_timeout = ${ms(timeouts.lockTimeoutMs)}`);
+    await client.query(`DROP INDEX CONCURRENTLY IF EXISTS ${index}`);
+    return true;
+}
+const defaultSleep = (n) => new Promise((r) => setTimeout(r, n));
+/** Runs one statement to success or failure; see the module comment. */
+export async function runPgStatement(client, step, options) {
+    const { timeouts, log } = options;
+    const sleep = options.sleep ?? defaultSleep;
+    const base = options.retryBaseMs ?? DEFAULT_RETRY_BASE_MS;
+    const statementTimeout = scansRows(step.class) ? timeouts.scanTimeoutMs : timeouts.statementTimeoutMs;
+    const index = step.transactional ? undefined : concurrentIndex(step.sql);
+    const droppedInvalid = [];
+    const lockWaits = [];
+    const note = () => {
+        const parts = [];
+        if (lockWaits.length > 0)
+            parts.push(`lock_timeout ${String(timeouts.lockTimeoutMs)}ms hit ${String(lockWaits.length)} time(s); succeeded on attempt ${String(lockWaits.length + 1)}`);
+        if (droppedInvalid.length > 0)
+            parts.push(`dropped INVALID index ${droppedInvalid.join(", ")} before building it again`);
+        return parts.join("; ");
+    };
+    const cleanIndex = async () => {
+        if (index === undefined)
+            return;
+        try {
+            if (await dropInvalidIndex(client, index, timeouts, log))
+                droppedInvalid.push(index);
+        }
+        catch (e) {
+            log(`  could not drop the INVALID index ${index}: ${messageOf(e)}; the next run tries again`);
+        }
+    };
+    for (let attempt = 1;; attempt++) {
+        try {
+            if (step.transactional) {
+                await client.query("BEGIN");
+                try {
+                    await client.query(`SET LOCAL lock_timeout = ${ms(timeouts.lockTimeoutMs)}`);
+                    await client.query(`SET LOCAL statement_timeout = ${ms(statementTimeout)}`);
+                    await client.query(step.sql);
+                    await options.succeeded(note());
+                    await client.query("COMMIT");
+                }
+                catch (e) {
+                    await client.query("ROLLBACK").catch(() => undefined);
+                    throw e;
+                }
+            }
+            else {
+                await cleanIndex();
+                try {
+                    await client.query(`SET lock_timeout = ${ms(timeouts.lockTimeoutMs)}`);
+                    await client.query(`SET statement_timeout = ${ms(statementTimeout)}`);
+                    await client.query(step.sql);
+                }
+                catch (e) {
+                    await cleanIndex();
+                    throw e;
+                }
+                finally {
+                    await client.query("SET lock_timeout TO DEFAULT").catch(() => undefined);
+                    await client.query("SET statement_timeout TO DEFAULT").catch(() => undefined);
+                }
+                await options.succeeded(note());
+            }
+            return { attempts: attempt, droppedInvalid, note: note() };
+        }
+        catch (e) {
+            const code = sqlstate(e);
+            if (code === LOCK_NOT_AVAILABLE && attempt <= options.retries) {
+                lockWaits.push(attempt);
+                const wait = base * 2 ** (attempt - 1);
+                log(`  lock_timeout ${String(timeouts.lockTimeoutMs)}ms: another session holds a lock this statement needs; trying again in ${String(wait)}ms (${String(attempt)}/${String(options.retries)})`);
+                await sleep(wait);
+                continue;
+            }
+            const message = messageOf(e);
+            throw new PgStatementError(code === LOCK_NOT_AVAILABLE
+                ? `${message} (lock_timeout ${String(timeouts.lockTimeoutMs)}ms, tried ${String(attempt)} times: another session kept a lock this statement needs; SQLSTATE 55P03)`
+                : message, code, attempt);
+        }
+    }
+}
+//# sourceMappingURL=executor.js.map

package/dist/versioned/postgres/executor.js.map

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

package/dist/versioned/postgres/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The versioned path on Postgres (#13): the driver the engine runs, and its
+ * parts.
+ *
+ *   openPostgres(project, env)   the server, the history store, the driver
+ *   runPgStatement(client, step) one statement under lock_timeout, retried, with its row
+ *   readPgCatalog / pgCatalogFingerprint  the live schema the plan digest covers
+ */
+export * from "./catalog.js";
+export * from "./driver.js";
+export * from "./executor.js";

package/dist/versioned/postgres/index.js

@@ -0,0 +1,12 @@
+/**
+ * The versioned path on Postgres (#13): the driver the engine runs, and its
+ * parts.
+ *
+ *   openPostgres(project, env)   the server, the history store, the driver
+ *   runPgStatement(client, step) one statement under lock_timeout, retried, with its row
+ *   readPgCatalog / pgCatalogFingerprint  the live schema the plan digest covers
+ */
+export * from "./catalog.js";
+export * from "./driver.js";
+export * from "./executor.js";
+//# sourceMappingURL=index.js.map

package/dist/versioned/postgres/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/versioned/postgres/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC"}

package/dist/versioned/report.d.ts

@@ -0,0 +1,22 @@
+/** The versioned status as text and as JSON, for `yodel status` and `yodel apply --plan`. */
+import type { SqlDialect } from "../project.js";
+import { type HistoryLocation } from "../history/index.js";
+import { type VersionedStatus } from "./state.js";
+export interface StatusReport {
+    environment: string;
+    /** Postgres has no topology: its report leaves it out. Default ClickHouse. */
+    dialect?: SqlDialect | undefined;
+    location: HistoryLocation;
+    /** The topology statements are rendered for, and where it came from: `cluster:main (yodel.config.ts)`. Default: the history's. */
+    topology?: string | undefined;
+    status: VersionedStatus;
+    /** The digest `yodel apply` would ask approval for, when it would not refuse. */
+    digest?: string | undefined;
+    /** Why `yodel apply` would refuse, with its exit code. */
+    refusal?: {
+        exitCode: number;
+        message: string;
+    } | undefined;
+}
+export declare function statusJson(r: StatusReport): Record<string, unknown>;
+export declare function renderStatus(r: StatusReport): string;

package/dist/versioned/report.js

@@ -0,0 +1,81 @@
+/** The versioned status as text and as JSON, for `yodel status` and `yodel apply --plan`. */
+import { describeTopology } from "../history/index.js";
+import { describeStep } from "../steps/index.js";
+import { outOfOrder, partWay } from "./state.js";
+export function statusJson(r) {
+    const { status } = r;
+    return {
+        environment: r.environment,
+        ...(r.dialect === "postgres"
+            ? { history: { database: r.location.database } }
+            : { history: { database: r.location.database, topology: describeTopology(r.location.topology) }, topology: r.topology ?? describeTopology(r.location.topology) }),
+        applied: status.applied.map((a) => ({
+            id: a.id,
+            checksum: a.checksum,
+            appliedBy: a.appliedBy,
+            recordedAt: a.recordedAt,
+            planDigest: a.planDigest,
+            inDirectory: a.index !== undefined,
+            ...(a.repairs ? { repairs: a.repairs.map((r) => ({ checksum: r.checksum, by: r.by, at: r.at, reason: r.reason })) } : {}),
+        })),
+        pending: status.pending.map((p) => ({
+            id: p.id,
+            checksum: p.checksum,
+            outOfOrder: p.outOfOrder,
+            partWay: p.partWay ?? null,
+            opSteps: p.opSteps.map(({ index, step }) => ({ index, kind: step.kind, object: step.object, name: step.name, ...(step.kind === "op" ? { op: step.op } : {}) })),
+            refusedSteps: p.refusedSteps.map(({ index, step, reason }) => ({ index, kind: step.kind, object: step.object, name: step.name, ...(step.kind === "op" ? { op: step.op } : {}), reason })),
+        })),
+        outOfOrder: outOfOrder(status).map((p) => p.id),
+        partWay: partWay(status).map((p) => ({ id: p.id, resumeAt: p.partWay?.resumeAt, failedStatement: p.partWay?.failedStatement ?? null })),
+        mismatches: status.mismatches,
+        ...(r.digest ? { planDigest: r.digest } : {}),
+        ...(r.refusal ? { refusal: r.refusal } : {}),
+    };
+}
+export function renderStatus(r) {
+    const { status } = r;
+    const topology = r.dialect === "postgres" ? "" : `, topology ${r.topology ?? describeTopology(r.location.topology)}`;
+    const lines = [`Migrations in ${r.environment} (history ${r.location.database}.history${topology})`, ""];
+    lines.push(status.applied.length === 0 ? "Applied: none" : `Applied (${String(status.applied.length)}):`);
+    for (const a of status.applied) {
+        lines.push(`  ${a.id}${a.index === undefined ? "  (not in the directory)" : ""}  ${a.recordedAt} by ${a.appliedBy}`);
+        for (const r of a.repairs ?? [])
+            lines.push(`      repaired ${r.at} by ${r.by}: ${r.reason}`);
+    }
+    lines.push("", status.pending.length === 0 ? "Pending: none" : `Pending (${String(status.pending.length)}):`);
+    for (const p of status.pending) {
+        const marks = [];
+        if (p.outOfOrder)
+            marks.push("out of order");
+        if (p.partWay) {
+            const pw = p.partWay;
+            marks.push(pw.status === "failed"
+                ? `failed part way at statement ${String(pw.failedStatement ?? pw.resumeAt)}; resumes at statement ${String(pw.resumeAt)}`
+                : `stopped part way; resumes at statement ${String(pw.resumeAt)}`);
+            if (pw.edited)
+                marks.push("edited since; the statements that ran are unchanged");
+        }
+        if (p.opSteps.length > 0)
+            marks.push(p.opSteps.map(({ index, step }) => `step ${String(index)}: ${describeStep(step)}`).join(", "));
+        if (p.refusedSteps.length > 0)
+            marks.push(`${String(p.refusedSteps.length)} step(s) yodel apply does not run`);
+        lines.push(`  ${p.id}${marks.length > 0 ? `  (${marks.join("; ")})` : ""}`);
+        if (p.partWay?.error)
+            lines.push(`      error: ${p.partWay.error.split("\n")[0] ?? ""}`);
+    }
+    const late = outOfOrder(status);
+    if (late.length > 0)
+        lines.push("", `Out of order (${String(late.length)}): ${late.map((p) => p.id).join(", ")}; apply with --allow-out-of-order`);
+    if (status.mismatches.length > 0) {
+        lines.push("", `Checksum mismatches (${String(status.mismatches.length)}):`);
+        for (const m of status.mismatches)
+            lines.push(`  ${m.message}`);
+    }
+    if (r.digest)
+        lines.push("", `Plan digest: ${r.digest}`);
+    if (r.refusal)
+        lines.push("", r.refusal.message);
+    return `${lines.join("\n")}\n`;
+}
+//# sourceMappingURL=report.js.map

package/dist/versioned/report.js.map

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

package/dist/versioned/state.d.ts

@@ -0,0 +1,108 @@
+/**
+ * The migrations directory against the history: what is applied, pending,
+ * out of order, part way, or changed since it ran. Pure.
+ *
+ * ## Order, and "out of order"
+ *
+ * The order is the chain `readMigrations` returns: parent links from the
+ * first migration to the newest, never the ids' timestamps. A pending
+ * migration is out of order when the chain puts it before a migration the
+ * history records applied: it was merged (or rebased into place) after a
+ * migration that follows it had already run here. It is reported, refused
+ * unless the run passes `--allow-out-of-order`, and never skipped: with the
+ * flag it runs, in chain order with the other pending ones.
+ *
+ * ## Checksums
+ *
+ * Every applied migration's checksum in the history is compared with its
+ * files' checksum, recomputed, on every run; a mismatch refuses (`yodel
+ * repair`, #15, records an intended edit). A migration the history records
+ * applied that is gone from the directory refuses the same way. A
+ * migration that failed part way may be edited before it resumes (to fix
+ * the statement that failed), as long as every statement that already
+ * succeeded is unchanged: those are compared statement by statement.
+ */
+import type { MigrationStep } from "@intentius/chant-lexicon-sql/migration-statements";
+import { type Migration } from "../migrations/index.js";
+import { type HistoryState, type Repair } from "../history/index.js";
+export interface AppliedMigration {
+    id: string;
+    checksum: string;
+    appliedBy: string;
+    /** When it was applied; a later repair does not change it. */
+    recordedAt: string;
+    planDigest: string;
+    /** Its position in the chain; `undefined` when the directory no longer has it. */
+    index: number | undefined;
+    /** `yodel repair` records since it was applied, oldest first. */
+    repairs?: Repair[] | undefined;
+}
+export interface PartWay {
+    /** The latest migration row's status: `failed` (a statement failed) or `started` (the runner stopped). */
+    status: "failed" | "started";
+    /** The index (in `steps`) of the first statement that has not succeeded: where it resumes. */
+    resumeAt: number;
+    /** The statement that failed, when one did. */
+    failedStatement: number | undefined;
+    error: string;
+    /** The indexes of the statements that succeeded and are never sent again. */
+    done: number[];
+    /** Its files changed since it ran part way (only statements not yet run). */
+    edited: boolean;
+}
+export interface PendingMigration {
+    id: string;
+    /** Its position in the chain. */
+    index: number;
+    /** The checksum of its files, recomputed. */
+    checksum: string;
+    /** Before a migration the history records applied. */
+    outOfOrder: boolean;
+    partWay: PartWay | undefined;
+    /** Its Op steps `apply` runs: a ClickHouse rebuild, a backfill (#12). */
+    opSteps: Array<{
+        index: number;
+        step: Exclude<MigrationStep, {
+            kind: "statement";
+        }>;
+    }>;
+    /** Its steps `apply` does not run (a manual step, an Op it does not run), each with why. Any of them refuses the run. */
+    refusedSteps: Array<{
+        index: number;
+        step: Exclude<MigrationStep, {
+            kind: "statement";
+        }>;
+        reason: string;
+    }>;
+    migration: Migration;
+}
+export type Mismatch = {
+    kind: "applied";
+    id: string;
+    recorded: string;
+    actual: string;
+    message: string;
+} | {
+    kind: "part-way";
+    id: string;
+    statement: number;
+    message: string;
+} | {
+    kind: "missing";
+    id: string;
+    recorded: string;
+    message: string;
+};
+export interface VersionedStatus {
+    /** In chain order; then any the directory no longer has, in the order they were applied. */
+    applied: AppliedMigration[];
+    /** In chain order. */
+    pending: PendingMigration[];
+    mismatches: Mismatch[];
+}
+export declare const outOfOrder: (s: VersionedStatus) => PendingMigration[];
+export declare const partWay: (s: VersionedStatus) => PendingMigration[];
+/** A migration's Op steps, split into the ones apply runs and the ones it refuses. A backfill step whose module is not among the migration's files is refused. */
+export declare function classifySteps(m: Migration): Pick<PendingMigration, "opSteps" | "refusedSteps">;
+/** Compares the chain with the history. */
+export declare function compareHistory(ordered: readonly Migration[], state: HistoryState): VersionedStatus;

package/dist/versioned/state.js

@@ -0,0 +1,153 @@
+/**
+ * The migrations directory against the history: what is applied, pending,
+ * out of order, part way, or changed since it ran. Pure.
+ *
+ * ## Order, and "out of order"
+ *
+ * The order is the chain `readMigrations` returns: parent links from the
+ * first migration to the newest, never the ids' timestamps. A pending
+ * migration is out of order when the chain puts it before a migration the
+ * history records applied: it was merged (or rebased into place) after a
+ * migration that follows it had already run here. It is reported, refused
+ * unless the run passes `--allow-out-of-order`, and never skipped: with the
+ * flag it runs, in chain order with the other pending ones.
+ *
+ * ## Checksums
+ *
+ * Every applied migration's checksum in the history is compared with its
+ * files' checksum, recomputed, on every run; a mismatch refuses (`yodel
+ * repair`, #15, records an intended edit). A migration the history records
+ * applied that is gone from the directory refuses the same way. A
+ * migration that failed part way may be edited before it resumes (to fix
+ * the statement that failed), as long as every statement that already
+ * succeeded is unchanged: those are compared statement by statement.
+ */
+import { computeChecksum } from "../migrations/index.js";
+import { isApplied, statementDone } from "../history/index.js";
+import { planStep, stepSha } from "../steps/index.js";
+export const outOfOrder = (s) => s.pending.filter((p) => p.outOfOrder);
+export const partWay = (s) => s.pending.filter((p) => p.partWay !== undefined);
+/** How to record an intended edit of migration `id`. */
+const repair = (id) => `if the edit is intended, record it with yodel repair ${id} --reason ... <env>`;
+function partWayOf(m, rec, actual) {
+    const done = [];
+    let resumeAt = m.document.steps.length;
+    let mismatch;
+    m.document.steps.forEach((step, i) => {
+        if (statementDone(rec, i)) {
+            done.push(i);
+            const sha = stepSha(step, m.files);
+            if (!mismatch && rec.statements.get(i)?.sha !== sha) {
+                mismatch = {
+                    kind: "part-way",
+                    id: m.id,
+                    statement: i,
+                    message: `${m.id} ran part way, and statement ${String(i)}, which succeeded, has changed in its files since; ${repair(m.id)}`,
+                };
+            }
+        }
+        else if (resumeAt === m.document.steps.length) {
+            resumeAt = i;
+        }
+    });
+    const failed = [...rec.statements.values()].filter((s) => s.status === "failed").sort((a, b) => b.seq - a.seq)[0];
+    return {
+        partWay: {
+            status: rec.status === "failed" ? "failed" : "started",
+            resumeAt,
+            failedStatement: failed && !statementDone(rec, failed.index) ? failed.index : undefined,
+            error: rec.error || failed?.error || "",
+            done,
+            edited: rec.checksum !== actual,
+        },
+        ...(mismatch ? { mismatch } : {}),
+    };
+}
+/** Why a step apply runs on one dialect is refused in a migration of the other, or `undefined`. */
+function dialectRefusal(run, dialect) {
+    if (run === "rebuild" && dialect !== "clickhouse")
+        return `a ClickHouseRebuildOp step in a ${dialect} migration`;
+    if (run === "pgMigration" && dialect !== "postgres")
+        return `a PostgresMigrationOp step in a ${dialect} migration`;
+    return undefined;
+}
+/** A migration's Op steps, split into the ones apply runs and the ones it refuses. A backfill step whose module is not among the migration's files is refused. */
+export function classifySteps(m) {
+    const opSteps = [];
+    const refusedSteps = [];
+    m.document.steps.forEach((step, index) => {
+        if (step.kind === "statement")
+            return;
+        const plan = planStep(step);
+        const wrongDialect = dialectRefusal(plan.run, m.document.dialect);
+        if (plan.run === "refused")
+            refusedSteps.push({ index, step, reason: plan.reason });
+        else if (wrongDialect)
+            refusedSteps.push({ index, step, reason: wrongDialect });
+        else if (plan.run === "backfill" && m.files.extra?.[plan.file] === undefined) {
+            refusedSteps.push({ index, step, reason: `a backfill step whose module ${plan.file} is not in ${m.id}'s directory` });
+        }
+        else
+            opSteps.push({ index, step });
+    });
+    return { opSteps, refusedSteps };
+}
+/** Compares the chain with the history. */
+export function compareHistory(ordered, state) {
+    const position = new Map(ordered.map((m, i) => [m.id, i]));
+    const mismatches = [];
+    const applied = [];
+    let lastApplied = -1;
+    for (const [i, m] of ordered.entries()) {
+        const rec = state.byId.get(m.id);
+        if (!rec || !isApplied(rec))
+            continue;
+        lastApplied = i;
+        const actual = computeChecksum(m.files);
+        applied.push({ id: m.id, checksum: rec.checksum, appliedBy: rec.appliedBy, recordedAt: rec.recordedAt, planDigest: rec.planDigest, index: i, ...(rec.repairs.length > 0 ? { repairs: rec.repairs } : {}) });
+        if (rec.checksum !== actual) {
+            mismatches.push({
+                kind: "applied",
+                id: m.id,
+                recorded: rec.checksum,
+                actual,
+                message: `${m.id} was applied with checksum ${rec.checksum}, but its files now hash to ${actual}; ${repair(m.id)}`,
+            });
+        }
+    }
+    const gone = state.migrations.filter((r) => isApplied(r) && !position.has(r.id)).sort((a, b) => (a.appliedSeq ?? 0) - (b.appliedSeq ?? 0));
+    for (const r of gone) {
+        applied.push({ id: r.id, checksum: r.checksum, appliedBy: r.appliedBy, recordedAt: r.recordedAt, planDigest: r.planDigest, index: undefined, ...(r.repairs.length > 0 ? { repairs: r.repairs } : {}) });
+        mismatches.push({
+            kind: "missing",
+            id: r.id,
+            recorded: r.checksum,
+            message: `${r.id} is recorded applied, but the migrations directory no longer has it; restore it, or ${repair(r.id)}`,
+        });
+    }
+    const pending = [];
+    for (const [i, m] of ordered.entries()) {
+        const rec = state.byId.get(m.id);
+        if (isApplied(rec))
+            continue;
+        const actual = computeChecksum(m.files);
+        let pw;
+        if (rec) {
+            const r = partWayOf(m, rec, actual);
+            pw = r.partWay;
+            if (r.mismatch)
+                mismatches.push(r.mismatch);
+        }
+        pending.push({
+            id: m.id,
+            index: i,
+            checksum: actual,
+            outOfOrder: i < lastApplied,
+            partWay: pw,
+            ...classifySteps(m),
+            migration: m,
+        });
+    }
+    return { applied, pending, mismatches };
+}
+//# sourceMappingURL=state.js.map

package/dist/versioned/state.js.map

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