@voyant-travel/framework-migrations 0.1.0

package/dist/bundle.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The framework-shipped standard-profile migration bundle (D.1). Loads this
+ * package's `migrations/` folder as the `framework` collector source (priority
+ * 0 — applied before the deployment's own migrations).
+ *
+ * Generated by `scripts/generate-framework-migration-bundle.mjs` from the
+ * standard-profile aggregate schema. See `docs/architecture/migration-collector-d1.md`.
+ */
+import type { MigrationSource } from "./collector.js";
+/** Absolute path to the shipped bundle folder (resolved relative to this module). */
+export declare function frameworkBundleDir(): string;
+/**
+ * The framework bundle as a collector source. `priority: 0` so it applies
+ * before deployment migrations (their link tables FK into framework tables).
+ */
+export declare function loadFrameworkBundleSource(dir?: string): Promise<MigrationSource>;
+//# sourceMappingURL=bundle.d.ts.map

package/dist/bundle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle.d.ts","sourceRoot":"","sources":["../src/bundle.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAGrD,qFAAqF;AACrF,wBAAgB,kBAAkB,IAAI,MAAM,CAG3C;AAED;;;GAGG;AACH,wBAAsB,yBAAyB,CAC7C,GAAG,GAAE,MAA6B,GACjC,OAAO,CAAC,eAAe,CAAC,CAM1B"}

package/dist/bundle.js

@@ -0,0 +1,27 @@
+/**
+ * The framework-shipped standard-profile migration bundle (D.1). Loads this
+ * package's `migrations/` folder as the `framework` collector source (priority
+ * 0 — applied before the deployment's own migrations).
+ *
+ * Generated by `scripts/generate-framework-migration-bundle.mjs` from the
+ * standard-profile aggregate schema. See `docs/architecture/migration-collector-d1.md`.
+ */
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadMigrationFolder } from "./load-folder.js";
+/** Absolute path to the shipped bundle folder (resolved relative to this module). */
+export function frameworkBundleDir() {
+    // src/bundle.ts → package root → migrations/  (dist/bundle.js → package root → migrations/)
+    return join(dirname(fileURLToPath(import.meta.url)), "..", "migrations");
+}
+/**
+ * The framework bundle as a collector source. `priority: 0` so it applies
+ * before deployment migrations (their link tables FK into framework tables).
+ */
+export async function loadFrameworkBundleSource(dir = frameworkBundleDir()) {
+    return {
+        name: "framework",
+        priority: 0,
+        migrations: await loadMigrationFolder(dir),
+    };
+}

package/dist/bundle.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=bundle.test.d.ts.map

package/dist/bundle.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle.test.d.ts","sourceRoot":"","sources":["../src/bundle.test.ts"],"names":[],"mappings":""}

package/dist/bundle.test.js

@@ -0,0 +1,18 @@
+import { describe, expect, it } from "vitest";
+import { frameworkBundleDir, loadFrameworkBundleSource } from "./bundle.js";
+describe("framework bundle", () => {
+    it("loads the shipped bundle as the framework collector source", async () => {
+        const source = await loadFrameworkBundleSource();
+        expect(source.name).toBe("framework");
+        // priority 0 — applies before deployment migrations (their links FK into
+        // framework tables).
+        expect(source.priority).toBe(0);
+        expect(source.migrations.length).toBeGreaterThan(0);
+        // The frozen baseline is first.
+        expect(source.migrations[0]?.tag).toBe("0000_framework_baseline");
+        expect(source.migrations[0]?.sql).toContain("CREATE TABLE");
+    });
+    it("resolves a bundle dir ending in /migrations", () => {
+        expect(frameworkBundleDir().endsWith("/migrations")).toBe(true);
+    });
+});

package/dist/collector.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Multi-source migration collector (consolidated-deployments RFC, Workstream
+ * D.1). Applies migrations from ordered sources — the framework-shipped bundle
+ * first, then the deployment's own migrations — recording each in a single
+ * version-independent ledger keyed by `(source, tag, content_hash)`.
+ *
+ * Properties (validated in `spikes/d1-migration-collector` + the integration
+ * tests): framework-first ordering, idempotent re-runs, an upgrade applies only
+ * the new migrations, and a shipped migration is immutable once applied (a
+ * content-hash change is a hard error). See `docs/architecture/migration-collector-d1.md`.
+ */
+/** One migration: a tag unique within its source + raw SQL. */
+export interface MigrationStatement {
+    /** Unique-within-source tag, e.g. `0001_init`. */
+    tag: string;
+    /** Raw SQL; drizzle `--> statement-breakpoint` separators are honored. */
+    sql: string;
+}
+/** An ordered migration source (e.g. the framework bundle, or the deployment). */
+export interface MigrationSource {
+    /** Name recorded in the ledger, e.g. `framework` / `deployment`. */
+    name: string;
+    /**
+     * Apply order across sources within a run (lower first). Framework < deployment
+     * is load-bearing — deployment link tables FK into framework tables.
+     */
+    priority: number;
+    /** Migrations in their in-source apply order. */
+    migrations: MigrationStatement[];
+}
+export interface PlannedMigration {
+    source: string;
+    tag: string;
+    sql: string;
+    /** sha256 of the raw SQL (immutability key). */
+    contentHash: string;
+}
+/** Minimal pg-compatible client (keeps this package free of a `pg` dependency). */
+export interface MigrationClient {
+    query(sql: string, params?: unknown[]): Promise<{
+        rows: Array<Record<string, unknown>>;
+    }>;
+}
+export interface ApplyMigrationsOptions {
+    /** Ledger schema (default `drizzle`). */
+    ledgerSchema?: string;
+    /** Ledger table (default `_voyant_migrations`). */
+    ledgerTable?: string;
+    /** Called with `"{source}/{tag}"` after each migration is applied. */
+    onApplied?: (id: string) => void;
+}
+/** Thrown when an already-applied `(source, tag)` arrives with changed SQL. */
+export declare class MigrationImmutabilityError extends Error {
+    readonly source: string;
+    readonly tag: string;
+    readonly ledgerHash: string;
+    readonly currentHash: string;
+    constructor(source: string, tag: string, ledgerHash: string, currentHash: string);
+}
+/**
+ * Deterministic apply order across sources: `(source.priority, in-source index)`.
+ * Mutating a source's `migrations` order is significant — keep them append-only.
+ */
+export declare function planMigrations(sources: MigrationSource[]): PlannedMigration[];
+/**
+ * Baseline an EXISTING deployment onto the collector ledger: record every
+ * planned migration as already-applied **without executing its SQL** — for a DB
+ * whose schema already matches `sources` (materialised by the legacy runner +
+ * `drizzle-kit push`). Idempotent (`ON CONFLICT DO NOTHING`); the caller MUST
+ * have verified schema parity first, since this asserts "the schema is already
+ * here" without checking. Returns the `"{source}/{tag}"` ids newly recorded.
+ *
+ * See the cutover section of docs/architecture/migration-collector-d1.md.
+ */
+export declare function importBaseline(client: MigrationClient, sources: MigrationSource[], options?: ApplyMigrationsOptions): Promise<string[]>;
+/**
+ * Apply every pending migration across `sources` in plan order, recording each
+ * in the ledger. Idempotent (already-applied identical migrations are skipped);
+ * throws {@link MigrationImmutabilityError} if an applied migration's SQL
+ * changed. Each migration + its ledger row commit atomically. Returns the list
+ * of `"{source}/{tag}"` applied this run, in apply order.
+ */
+export declare function applyMigrations(client: MigrationClient, sources: MigrationSource[], options?: ApplyMigrationsOptions): Promise<string[]>;
+//# sourceMappingURL=collector.d.ts.map

package/dist/collector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collector.d.ts","sourceRoot":"","sources":["../src/collector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,+DAA+D;AAC/D,MAAM,WAAW,kBAAkB;IACjC,kDAAkD;IAClD,GAAG,EAAE,MAAM,CAAA;IACX,0EAA0E;IAC1E,GAAG,EAAE,MAAM,CAAA;CACZ;AAED,kFAAkF;AAClF,MAAM,WAAW,eAAe;IAC9B,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAA;IACZ;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB,iDAAiD;IACjD,UAAU,EAAE,kBAAkB,EAAE,CAAA;CACjC;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAA;IACd,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,gDAAgD;IAChD,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,mFAAmF;AACnF,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;KAAE,CAAC,CAAA;CAC1F;AAED,MAAM,WAAW,sBAAsB;IACrC,yCAAyC;IACzC,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,mDAAmD;IACnD,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,sEAAsE;IACtE,SAAS,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAA;CACjC;AAED,+EAA+E;AAC/E,qBAAa,0BAA2B,SAAQ,KAAK;IAEjD,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM;IACpB,QAAQ,CAAC,UAAU,EAAE,MAAM;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM;gBAHnB,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM;CAS/B;AAYD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,gBAAgB,EAAE,CAc7E;AA4BD;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,eAAe,EACvB,OAAO,EAAE,eAAe,EAAE,EAC1B,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,MAAM,EAAE,CAAC,CAkBnB;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,eAAe,EACvB,OAAO,EAAE,eAAe,EAAE,EAC1B,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,MAAM,EAAE,CAAC,CAsCnB"}

package/dist/collector.js

@@ -0,0 +1,136 @@
+/**
+ * Multi-source migration collector (consolidated-deployments RFC, Workstream
+ * D.1). Applies migrations from ordered sources — the framework-shipped bundle
+ * first, then the deployment's own migrations — recording each in a single
+ * version-independent ledger keyed by `(source, tag, content_hash)`.
+ *
+ * Properties (validated in `spikes/d1-migration-collector` + the integration
+ * tests): framework-first ordering, idempotent re-runs, an upgrade applies only
+ * the new migrations, and a shipped migration is immutable once applied (a
+ * content-hash change is a hard error). See `docs/architecture/migration-collector-d1.md`.
+ */
+import { createHash } from "node:crypto";
+/** Thrown when an already-applied `(source, tag)` arrives with changed SQL. */
+export class MigrationImmutabilityError extends Error {
+    source;
+    tag;
+    ledgerHash;
+    currentHash;
+    constructor(source, tag, ledgerHash, currentHash) {
+        super(`migration immutability violation: ${source}/${tag} changed after it was applied ` +
+            `(ledger ${ledgerHash.slice(0, 12)}… != current ${currentHash.slice(0, 12)}…). ` +
+            "Shipped migrations are immutable — add a new migration instead of editing an applied one.");
+        this.source = source;
+        this.tag = tag;
+        this.ledgerHash = ledgerHash;
+        this.currentHash = currentHash;
+        this.name = "MigrationImmutabilityError";
+    }
+}
+const contentHash = (sql) => createHash("sha256").update(sql).digest("hex");
+/** Split a drizzle migration's SQL into individual statements. */
+function splitStatements(sql) {
+    return sql
+        .split("--> statement-breakpoint")
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+/**
+ * Deterministic apply order across sources: `(source.priority, in-source index)`.
+ * Mutating a source's `migrations` order is significant — keep them append-only.
+ */
+export function planMigrations(sources) {
+    return sources
+        .flatMap((source) => source.migrations.map((m, seq) => ({
+        source: source.name,
+        priority: source.priority,
+        seq,
+        tag: m.tag,
+        sql: m.sql,
+        contentHash: contentHash(m.sql),
+    })))
+        .sort((a, b) => a.priority - b.priority || a.seq - b.seq)
+        .map(({ source, tag, sql, contentHash: hash }) => ({ source, tag, sql, contentHash: hash }));
+}
+function qualifiedLedger(options) {
+    const schema = options?.ledgerSchema ?? "drizzle";
+    const table = options?.ledgerTable ?? "_voyant_migrations";
+    return `"${schema}"."${table}"`;
+}
+/** Create the ledger schema + table if absent. Shared by apply + baseline. */
+async function ensureLedger(client, options) {
+    const ledger = qualifiedLedger(options);
+    const schema = options?.ledgerSchema ?? "drizzle";
+    await client.query(`CREATE SCHEMA IF NOT EXISTS "${schema}"`);
+    await client.query(`CREATE TABLE IF NOT EXISTS ${ledger} (
+       "source" text NOT NULL,
+       "tag" text NOT NULL,
+       "content_hash" text NOT NULL,
+       "applied_at" timestamptz NOT NULL DEFAULT now(),
+       PRIMARY KEY ("source", "tag")
+     )`);
+    return ledger;
+}
+/**
+ * Baseline an EXISTING deployment onto the collector ledger: record every
+ * planned migration as already-applied **without executing its SQL** — for a DB
+ * whose schema already matches `sources` (materialised by the legacy runner +
+ * `drizzle-kit push`). Idempotent (`ON CONFLICT DO NOTHING`); the caller MUST
+ * have verified schema parity first, since this asserts "the schema is already
+ * here" without checking. Returns the `"{source}/{tag}"` ids newly recorded.
+ *
+ * See the cutover section of docs/architecture/migration-collector-d1.md.
+ */
+export async function importBaseline(client, sources, options) {
+    const ledger = await ensureLedger(client, options);
+    const imported = [];
+    for (const m of planMigrations(sources)) {
+        const res = await client.query(`INSERT INTO ${ledger} ("source", "tag", "content_hash") VALUES ($1, $2, $3)
+       ON CONFLICT ("source", "tag") DO NOTHING`, [m.source, m.tag, m.contentHash]);
+        // node-postgres exposes rowCount; treat absent (0/undefined) as "already there".
+        const inserted = res.rowCount ?? 0;
+        if (inserted > 0) {
+            const id = `${m.source}/${m.tag}`;
+            imported.push(id);
+            options?.onApplied?.(id);
+        }
+    }
+    return imported;
+}
+/**
+ * Apply every pending migration across `sources` in plan order, recording each
+ * in the ledger. Idempotent (already-applied identical migrations are skipped);
+ * throws {@link MigrationImmutabilityError} if an applied migration's SQL
+ * changed. Each migration + its ledger row commit atomically. Returns the list
+ * of `"{source}/{tag}"` applied this run, in apply order.
+ */
+export async function applyMigrations(client, sources, options) {
+    const ledger = await ensureLedger(client, options);
+    const applied = [];
+    for (const m of planMigrations(sources)) {
+        const seen = await client.query(`SELECT "content_hash" FROM ${ledger} WHERE "source" = $1 AND "tag" = $2`, [m.source, m.tag]);
+        if (seen.rows.length > 0) {
+            const ledgerHash = String(seen.rows[0]?.content_hash ?? "");
+            if (ledgerHash !== m.contentHash) {
+                throw new MigrationImmutabilityError(m.source, m.tag, ledgerHash, m.contentHash);
+            }
+            continue; // already applied, identical → no-op
+        }
+        await client.query("BEGIN");
+        try {
+            for (const statement of splitStatements(m.sql)) {
+                await client.query(statement);
+            }
+            await client.query(`INSERT INTO ${ledger} ("source", "tag", "content_hash") VALUES ($1, $2, $3)`, [m.source, m.tag, m.contentHash]);
+            await client.query("COMMIT");
+        }
+        catch (error) {
+            await client.query("ROLLBACK");
+            throw error;
+        }
+        const id = `${m.source}/${m.tag}`;
+        applied.push(id);
+        options?.onApplied?.(id);
+    }
+    return applied;
+}

package/dist/collector.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=collector.test.d.ts.map

package/dist/collector.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collector.test.d.ts","sourceRoot":"","sources":["../src/collector.test.ts"],"names":[],"mappings":""}

package/dist/collector.test.js

@@ -0,0 +1,167 @@
+import { Client } from "pg";
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import { applyMigrations, importBaseline, MigrationImmutabilityError, planMigrations, } from "./collector.js";
+const DB_URL = process.env.TEST_DATABASE_URL;
+const SCHEMA = "voyant_fwmig_test";
+// ---- planMigrations: pure, no DB --------------------------------------------
+describe("planMigrations", () => {
+    it("orders by (source priority, in-source sequence)", () => {
+        const plan = planMigrations([
+            { name: "deployment", priority: 1, migrations: [{ tag: "d0", sql: "select 1" }] },
+            {
+                name: "framework",
+                priority: 0,
+                migrations: [
+                    { tag: "f0", sql: "select 1" },
+                    { tag: "f1", sql: "select 2" },
+                ],
+            },
+        ]);
+        expect(plan.map((p) => `${p.source}/${p.tag}`)).toEqual([
+            "framework/f0",
+            "framework/f1",
+            "deployment/d0",
+        ]);
+    });
+    it("hashes by SQL content (different SQL → different hash)", () => {
+        const [a] = planMigrations([{ name: "x", priority: 0, migrations: [{ tag: "t", sql: "A" }] }]);
+        const [b] = planMigrations([{ name: "x", priority: 0, migrations: [{ tag: "t", sql: "B" }] }]);
+        expect(a?.contentHash).toBeTypeOf("string");
+        expect(a?.contentHash).not.toBe(b?.contentHash);
+    });
+});
+// ---- applyMigrations: integration (the spike's scenarios) -------------------
+function sources() {
+    return {
+        framework: {
+            name: "framework",
+            priority: 0,
+            migrations: [
+                { tag: "0001_init", sql: `CREATE TABLE ${SCHEMA}.bookings (id text PRIMARY KEY);` },
+                { tag: "0002_add_status", sql: `ALTER TABLE ${SCHEMA}.bookings ADD COLUMN status text;` },
+            ],
+        },
+        deployment: {
+            name: "deployment",
+            priority: 1,
+            // FK into a framework table — fails outright if applied before framework.
+            migrations: [
+                {
+                    tag: "0001_acme_notes",
+                    sql: `CREATE TABLE ${SCHEMA}.acme_notes (id text PRIMARY KEY, booking_id text REFERENCES ${SCHEMA}.bookings(id));`,
+                },
+            ],
+        },
+    };
+}
+const ledgerOpts = { ledgerSchema: SCHEMA, ledgerTable: "_voyant_migrations" };
+describe.skipIf(!DB_URL)("applyMigrations (integration)", () => {
+    let client;
+    beforeAll(async () => {
+        client = new Client({ connectionString: DB_URL });
+        await client.connect();
+    });
+    afterAll(async () => {
+        if (client) {
+            await client.query(`DROP SCHEMA IF EXISTS ${SCHEMA} CASCADE`);
+            await client.end();
+        }
+    });
+    beforeEach(async () => {
+        await client.query(`DROP SCHEMA IF EXISTS ${SCHEMA} CASCADE`);
+        await client.query(`CREATE SCHEMA ${SCHEMA}`);
+    });
+    async function tableExists(name) {
+        const r = await client.query("SELECT 1 FROM information_schema.tables WHERE table_schema = $1 AND table_name = $2", [SCHEMA, name]);
+        return r.rows.length > 0;
+    }
+    it("scenario 1+5 — fresh apply is framework-first; deployment FK resolves", async () => {
+        const s = sources();
+        const applied = await applyMigrations(client, [s.framework, s.deployment], ledgerOpts);
+        expect(applied).toEqual([
+            "framework/0001_init",
+            "framework/0002_add_status",
+            "deployment/0001_acme_notes",
+        ]);
+        expect(await tableExists("bookings")).toBe(true);
+        // The deployment table FKs into the framework table — exists only because
+        // framework was applied first (ordering is load-bearing).
+        expect(await tableExists("acme_notes")).toBe(true);
+    });
+    it("scenario 2 — re-run is idempotent (applies nothing)", async () => {
+        const s = sources();
+        await applyMigrations(client, [s.framework, s.deployment], ledgerOpts);
+        const second = await applyMigrations(client, [s.framework, s.deployment], ledgerOpts);
+        expect(second).toEqual([]);
+    });
+    it("scenario 3 — a framework upgrade applies only the new migration", async () => {
+        const s = sources();
+        await applyMigrations(client, [s.framework, s.deployment], ledgerOpts);
+        const upgraded = sources();
+        upgraded.framework.migrations.push({
+            tag: "0003_add_index",
+            sql: `CREATE INDEX bookings_status_idx ON ${SCHEMA}.bookings (status);`,
+        });
+        const applied = await applyMigrations(client, [upgraded.framework, upgraded.deployment], ledgerOpts);
+        expect(applied).toEqual(["framework/0003_add_index"]);
+    });
+    it("scenario 4 — editing an applied migration is a hard error", async () => {
+        const s = sources();
+        await applyMigrations(client, [s.framework, s.deployment], ledgerOpts);
+        const tampered = sources();
+        tampered.framework.migrations[0].sql =
+            `CREATE TABLE ${SCHEMA}.bookings (id text PRIMARY KEY, tampered boolean);`;
+        await expect(applyMigrations(client, [tampered.framework, tampered.deployment], ledgerOpts)).rejects.toBeInstanceOf(MigrationImmutabilityError);
+    });
+    it("splits drizzle statement-breakpoints within one migration", async () => {
+        const multi = {
+            name: "framework",
+            priority: 0,
+            migrations: [
+                {
+                    tag: "0001_multi",
+                    sql: `CREATE TABLE ${SCHEMA}.a (id text);\n--> statement-breakpoint\nCREATE TABLE ${SCHEMA}.b (id text);`,
+                },
+            ],
+        };
+        await applyMigrations(client, [multi], ledgerOpts);
+        expect(await tableExists("a")).toBe(true);
+        expect(await tableExists("b")).toBe(true);
+    });
+    // ---- importBaseline: record an existing schema without re-executing --------
+    it("baseline records the ledger WITHOUT executing any SQL", async () => {
+        const s = sources();
+        const imported = await importBaseline(client, [s.framework, s.deployment], ledgerOpts);
+        // Every planned migration is recorded …
+        expect(imported).toEqual([
+            "framework/0001_init",
+            "framework/0002_add_status",
+            "deployment/0001_acme_notes",
+        ]);
+        // … but none of their SQL ran (the schema is assumed already present).
+        expect(await tableExists("bookings")).toBe(false);
+        expect(await tableExists("acme_notes")).toBe(false);
+    });
+    it("a baselined deployment then applies nothing (ledger interop with applyMigrations)", async () => {
+        const s = sources();
+        await importBaseline(client, [s.framework, s.deployment], ledgerOpts);
+        // applyMigrations sees the baselined (source, tag) rows and skips them —
+        // so it does NOT try to re-create the already-existing schema.
+        const applied = await applyMigrations(client, [s.framework, s.deployment], ledgerOpts);
+        expect(applied).toEqual([]);
+        // A genuinely new migration still applies after a baseline.
+        const upgraded = sources();
+        upgraded.framework.migrations.push({
+            tag: "0003_add_index",
+            sql: `CREATE TABLE ${SCHEMA}.bookings (id text PRIMARY KEY); CREATE INDEX bookings_status_idx ON ${SCHEMA}.bookings (id);`,
+        });
+        const next = await applyMigrations(client, [upgraded.framework, upgraded.deployment], ledgerOpts);
+        expect(next).toEqual(["framework/0003_add_index"]);
+    });
+    it("baseline is idempotent (re-run records nothing new)", async () => {
+        const s = sources();
+        await importBaseline(client, [s.framework, s.deployment], ledgerOpts);
+        const second = await importBaseline(client, [s.framework, s.deployment], ledgerOpts);
+        expect(second).toEqual([]);
+    });
+});

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `@voyant-travel/framework-migrations` — the D.1 multi-source migration
+ * collector + (in a later slice) the framework-shipped standard-profile bundle.
+ *
+ * See `docs/architecture/migration-collector-d1.md`.
+ */
+export { frameworkBundleDir, loadFrameworkBundleSource } from "./bundle.js";
+export { type ApplyMigrationsOptions, applyMigrations, importBaseline, type MigrationClient, MigrationImmutabilityError, type MigrationSource, type MigrationStatement, type PlannedMigration, planMigrations, } from "./collector.js";
+export { loadMigrationFolder } from "./load-folder.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,kBAAkB,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAA;AAC3E,OAAO,EACL,KAAK,sBAAsB,EAC3B,eAAe,EACf,cAAc,EACd,KAAK,eAAe,EACpB,0BAA0B,EAC1B,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,cAAc,GACf,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * `@voyant-travel/framework-migrations` — the D.1 multi-source migration
+ * collector + (in a later slice) the framework-shipped standard-profile bundle.
+ *
+ * See `docs/architecture/migration-collector-d1.md`.
+ */
+export { frameworkBundleDir, loadFrameworkBundleSource } from "./bundle.js";
+export { applyMigrations, importBaseline, MigrationImmutabilityError, planMigrations, } from "./collector.js";
+export { loadMigrationFolder } from "./load-folder.js";

package/dist/load-folder.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Load a drizzle migrations folder (`meta/_journal.json` + `*.sql`) into the
+ * ordered `MigrationStatement[]` the collector consumes. The framework bundle
+ * and the deployment's own `migrations/` are both drizzle folders, so the same
+ * loader reads either.
+ */
+import type { MigrationStatement } from "./collector.js";
+/**
+ * Read `<folder>/meta/_journal.json` and each `<folder>/<tag>.sql`, returning
+ * statements in journal order (ascending `when`). Throws if a referenced SQL
+ * file is missing — a journal/file mismatch is a packaging error, not something
+ * to apply partially.
+ */
+export declare function loadMigrationFolder(folder: string): Promise<MigrationStatement[]>;
+//# sourceMappingURL=load-folder.d.ts.map

package/dist/load-folder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-folder.d.ts","sourceRoot":"","sources":["../src/load-folder.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AAWxD;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAWvF"}

package/dist/load-folder.js

@@ -0,0 +1,25 @@
+/**
+ * Load a drizzle migrations folder (`meta/_journal.json` + `*.sql`) into the
+ * ordered `MigrationStatement[]` the collector consumes. The framework bundle
+ * and the deployment's own `migrations/` are both drizzle folders, so the same
+ * loader reads either.
+ */
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+/**
+ * Read `<folder>/meta/_journal.json` and each `<folder>/<tag>.sql`, returning
+ * statements in journal order (ascending `when`). Throws if a referenced SQL
+ * file is missing — a journal/file mismatch is a packaging error, not something
+ * to apply partially.
+ */
+export async function loadMigrationFolder(folder) {
+    const journalRaw = await readFile(join(folder, "meta", "_journal.json"), "utf8");
+    const journal = JSON.parse(journalRaw);
+    const entries = [...journal.entries].sort((a, b) => a.when - b.when);
+    const statements = [];
+    for (const entry of entries) {
+        const sql = await readFile(join(folder, `${entry.tag}.sql`), "utf8");
+        statements.push({ tag: entry.tag, sql });
+    }
+    return statements;
+}