@cosmicdrift/kumiko-framework 0.391.0 → 0.392.0

package/dist/db/entity-table-meta.js

@@ -17,6 +17,7 @@
 //      `store_` table name — `read_` is reserved for managed projections (#1208/#1220).
 import { collectPiiEncryptedFields, isRecordKeyedField } from "../crypto/index.js";
 import { isSqlExpression } from "./dialect.js";
+import { fieldToColumnMeta } from "./entity-column-meta.js";
 import { READ_MODEL_PREFIX, SOFT_DELETE_LIVE_ROW_PREDICATE, toSnakeCase, toTableName, } from "./table-builder.js";
 import { brandWritable } from "./table-introspection.js";
 // Standard base columns for event-sourced read-model tables. Mirrors
@@ -45,159 +46,6 @@ function fullBaseColumns(idType, softDelete) {
     }
     return cols;
 }
-function quoteSql(literal) {
-    return `'${literal.replace(/'/g, "''")}'`;
-}
-function fieldDefaultLiteral(field) {
-    if (!("default" in field) || field.default === undefined)
-        return undefined;
-    const v = field.default;
-    if (typeof v === "string")
-        return quoteSql(v);
-    if (typeof v === "number")
-        return String(v);
-    if (typeof v === "boolean")
-        return v ? "true" : "false";
-    return undefined;
-}
-// Mirrors `fieldToColumns()` from table-builder.ts (drizzle variant).
-// Lock-step: every field type must produce the same PG columns as today.
-function fieldToColumnMeta(name, field, entity) {
-    const snake = toSnakeCase(name);
-    switch (field.type) {
-        case "text":
-        case "longText": {
-            const def = fieldDefaultLiteral(field);
-            const cols = [
-                {
-                    name: snake,
-                    pgType: "text",
-                    notNull: field.required === true,
-                    ...(def !== undefined && { defaultSql: def }),
-                },
-            ];
-            // lookupable → HMAC blind-index counterpart. Nullable is mandatory:
-            // managedChangeRequiresRecreate would diff a NOT-NULL column without
-            // a default on existing tables as DROP+rebuild.
-            if (field.type === "text" && field.lookupable === true) {
-                cols.push({ name: `${snake}_bidx`, pgType: "text", notNull: false });
-            }
-            return cols;
-        }
-        case "boolean": {
-            const def = fieldDefaultLiteral(field);
-            const hasDefault = def !== undefined;
-            return [
-                {
-                    name: snake,
-                    pgType: "boolean",
-                    notNull: hasDefault || field.required === true,
-                    ...(hasDefault && { defaultSql: def }),
-                },
-            ];
-        }
-        case "select": {
-            const def = fieldDefaultLiteral(field);
-            return [
-                {
-                    name: snake,
-                    pgType: "text",
-                    notNull: field.required === true,
-                    ...(def !== undefined && { defaultSql: def }),
-                },
-            ];
-        }
-        case "multiSelect":
-            return [{ name: snake, pgType: "jsonb", notNull: true, defaultSql: "'[]'::jsonb" }];
-        case "number": {
-            const def = fieldDefaultLiteral(field);
-            return [
-                {
-                    name: snake,
-                    pgType: field.integer === true ? "integer" : "double precision",
-                    notNull: field.required === true,
-                    ...(def !== undefined && { defaultSql: def }),
-                },
-            ];
-        }
-        case "bigInt": {
-            const def = fieldDefaultLiteral(field);
-            return [
-                {
-                    name: snake,
-                    pgType: "bigint",
-                    notNull: field.required === true,
-                    bigintJsMode: "number",
-                    ...(def !== undefined && { defaultSql: def }),
-                },
-            ];
-        }
-        case "decimal": {
-            const def = fieldDefaultLiteral(field);
-            return [
-                {
-                    name: snake,
-                    pgType: `numeric(${field.precision},${field.scale})`,
-                    notNull: field.required === true,
-                    ...(def !== undefined && { defaultSql: def }),
-                },
-            ];
-        }
-        case "reference":
-            if (field.multiple === true) {
-                return [{ name: snake, pgType: "jsonb", notNull: true, defaultSql: "'[]'::jsonb" }];
-            }
-            return [{ name: snake, pgType: "uuid", notNull: field.required === true }];
-        case "money": {
-            const cur = entity.defaultCurrency ?? "EUR";
-            return [
-                { name: snake, pgType: "bigint", notNull: field.required === true, bigintJsMode: "bigint" },
-                {
-                    name: `${snake}_currency`,
-                    pgType: "text",
-                    notNull: true,
-                    defaultSql: quoteSql(cur),
-                },
-            ];
-        }
-        case "embedded":
-            return [
-                {
-                    name: snake,
-                    pgType: "jsonb",
-                    notNull: true,
-                    defaultSql: field.multiple === true ? "'[]'::jsonb" : "'{}'::jsonb",
-                },
-            ];
-        case "jsonb":
-            return [{ name: snake, pgType: "jsonb", notNull: true, defaultSql: "'{}'::jsonb" }];
-        case "date":
-            // Real PG `date` — Temporal.PlainDate, no time-of-day/timezone
-            // component. See plainDate() in dialect.ts.
-            return [{ name: snake, pgType: "date", notNull: field.required === true }];
-        case "timestamp":
-            return [{ name: snake, pgType: "timestamptz", notNull: field.required === true }];
-        case "tz":
-            return [{ name: snake, pgType: "text", notNull: field.required === true }];
-        case "locatedTimestamp":
-            return [
-                {
-                    name: `${snake}_utc`,
-                    pgType: "timestamptz",
-                    notNull: field.required === true,
-                },
-                { name: `${snake}_tz`, pgType: "text", notNull: field.required === true },
-            ];
-        case "file":
-        case "image":
-            return [{ name: snake, pgType: "uuid", notNull: field.required === true }];
-        case "files":
-        case "images":
-            return [{ name: snake, pgType: "jsonb", notNull: true, defaultSql: "'[]'::jsonb" }];
-        default:
-            return [];
-    }
-}
 export function resolveTableName(entityName, entity, featureName) {
     const baseName = entity.table ?? toTableName(entityName);
     if (!featureName)

package/dist/db/migrate-change-render.d.ts

@@ -0,0 +1,40 @@
+import type { ColumnMeta } from "./entity-table-meta.ts";
+export type ColumnChange = {
+    readonly name: string;
+    readonly nullabilityChanged?: {
+        readonly from: boolean;
+        readonly to: boolean;
+    };
+    readonly defaultChanged?: {
+        readonly from: string | undefined;
+        readonly to: string | undefined;
+    };
+    readonly typeChanged?: {
+        readonly from: string;
+        readonly to: string;
+    };
+};
+export type IndexChange = {
+    readonly name: string;
+    readonly columnsChanged?: {
+        readonly from: readonly string[];
+        readonly to: readonly string[];
+    };
+    readonly uniqueChanged?: {
+        readonly from: boolean;
+        readonly to: boolean;
+    };
+    readonly whereSqlChanged?: {
+        readonly from: string | undefined;
+        readonly to: string | undefined;
+    };
+    readonly needsManualWhereChanged?: {
+        readonly from: boolean;
+        readonly to: boolean;
+    };
+};
+export declare function renderAddColumn(tableName: string, col: ColumnMeta): string;
+export declare function renderColumnChange(tableName: string, change: ColumnChange): readonly string[];
+export declare function toSingleLine(text: string): string;
+export declare function whereSqlEqual(a: string | undefined, b: string | undefined): boolean;
+export declare function describeIndexChange(change: IndexChange): string;

package/dist/db/migrate-change-render.js

@@ -0,0 +1,89 @@
+// Pure SQL fragments of a schema diff: column/index change shapes and their
+// reviewer-facing rendering. Kept free of the diff logic so migrate-generator
+// can import it without a cycle.
+import { quoteIdent } from "./sql-identifier.js";
+function renderColumnInline(col) {
+    const parts = [quoteIdent(col.name), col.pgType];
+    if (col.defaultSql !== undefined)
+        parts.push(`DEFAULT ${col.defaultSql}`);
+    if (col.notNull)
+        parts.push("NOT NULL");
+    return parts.join(" ");
+}
+export function renderAddColumn(tableName, col) {
+    return `ALTER TABLE ${quoteIdent(tableName)} ADD COLUMN ${renderColumnInline(col)};`;
+}
+export function renderColumnChange(tableName, change) {
+    const out = [];
+    const col = quoteIdent(change.name);
+    const tbl = quoteIdent(tableName);
+    if (change.nullabilityChanged) {
+        const op = change.nullabilityChanged.to ? "SET NOT NULL" : "DROP NOT NULL";
+        out.push(`ALTER TABLE ${tbl} ALTER COLUMN ${col} ${op};`);
+    }
+    if (change.defaultChanged) {
+        if (change.defaultChanged.to !== undefined) {
+            out.push(`ALTER TABLE ${tbl} ALTER COLUMN ${col} SET DEFAULT ${change.defaultChanged.to};`);
+        }
+        else {
+            out.push(`ALTER TABLE ${tbl} ALTER COLUMN ${col} DROP DEFAULT;`);
+        }
+    }
+    if (change.typeChanged) {
+        const { from, to } = change.typeChanged;
+        // timestamptz → date: PG's implicit ::date cast (what a bare ALTER ...
+        // TYPE without USING falls back to) reads the session TimeZone, so the
+        // same row migrates to a different calendar day depending on who/where
+        // runs it. Anchor explicitly at UTC instead of trusting the session.
+        if ((from === "timestamptz" || from === "timestamptz(3)") && to === "date") {
+            out.push(`-- ${from} → date: explicit UTC anchor — a bare cast would use the session TimeZone (non-deterministic).`);
+            out.push(`ALTER TABLE ${tbl} ALTER COLUMN ${col} TYPE date USING (${col} AT TIME ZONE 'UTC')::date;`);
+        }
+        else if (from === "date" && (to === "timestamptz" || to === "timestamptz(3)")) {
+            // Same non-determinism, reversed: a bare `date → timestamptz` cast
+            // interprets the calendar date at session-TimeZone midnight. Anchor
+            // explicitly at UTC midnight instead.
+            out.push(`-- date → ${to}: explicit UTC anchor — a bare cast would use the session TimeZone (non-deterministic).`);
+            out.push(`ALTER TABLE ${tbl} ALTER COLUMN ${col} TYPE ${to} USING (${col}::timestamp AT TIME ZONE 'UTC');`);
+        }
+        else {
+            // pg ALTER TYPE often needs a USING clause for non-implicitly-castable
+            // type changes. Emitted as a reviewer comment + raw cast — the app
+            // author has to confirm it's intended.
+            out.push(`-- WARN: column-type-change ${from} → ${to}. Review USING-clause if needed.`);
+            out.push(`ALTER TABLE ${tbl} ALTER COLUMN ${col} TYPE ${to};`);
+        }
+    }
+    return out;
+}
+// Collapses whitespace so a multi-line whereSql (e.g. a two-condition
+// drizzle sql`…` predicate) can't inject a newline into this `--` comment
+// line and escape into the executable body of the generated migration.
+export function toSingleLine(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+export function whereSqlEqual(a, b) {
+    if (a === undefined || b === undefined)
+        return a === b;
+    return toSingleLine(a) === toSingleLine(b);
+}
+export function describeIndexChange(change) {
+    const parts = [];
+    if (change.columnsChanged) {
+        parts.push(`columns (${change.columnsChanged.from.join(", ")}) → (${change.columnsChanged.to.join(", ")})`);
+    }
+    if (change.uniqueChanged) {
+        parts.push(`unique ${change.uniqueChanged.from} → ${change.uniqueChanged.to}`);
+    }
+    if (change.whereSqlChanged) {
+        const from = change.whereSqlChanged.from !== undefined
+            ? toSingleLine(change.whereSqlChanged.from)
+            : "<none>";
+        const to = change.whereSqlChanged.to !== undefined ? toSingleLine(change.whereSqlChanged.to) : "<none>";
+        parts.push(`where ${from} → ${to}`);
+    }
+    if (change.needsManualWhereChanged) {
+        parts.push(`needs-manual-where ${change.needsManualWhereChanged.from} → ${change.needsManualWhereChanged.to}`);
+    }
+    return parts.join("; ");
+}

package/dist/db/migrate-generator.d.ts

@@ -1,4 +1,5 @@
 import type { ColumnMeta, EntityTableMeta, IndexMeta } from "./entity-table-meta.ts";
+import { type ColumnChange, type IndexChange } from "./migrate-change-render.ts";
 import { type PrimaryKeyChange } from "./migrate-primary-key.ts";
 import { type RowLevelSecurityChange } from "./migrate-rls-diff.ts";
 import { type RowLevelSecurityMode, type TableRowLevelSecurity } from "./render-rls-ddl.ts";
@@ -10,40 +11,7 @@ export type Snapshot = {
     readonly tables: readonly EntityTableMeta[];
     readonly rowLevelSecurity?: Readonly<Record<string, TableRowLevelSecurity>>;
 };
-export type ColumnChange = {
-    readonly name: string;
-    readonly nullabilityChanged?: {
-        readonly from: boolean;
-        readonly to: boolean;
-    };
-    readonly defaultChanged?: {
-        readonly from: string | undefined;
-        readonly to: string | undefined;
-    };
-    readonly typeChanged?: {
-        readonly from: string;
-        readonly to: string;
-    };
-};
-export type IndexChange = {
-    readonly name: string;
-    readonly columnsChanged?: {
-        readonly from: readonly string[];
-        readonly to: readonly string[];
-    };
-    readonly uniqueChanged?: {
-        readonly from: boolean;
-        readonly to: boolean;
-    };
-    readonly whereSqlChanged?: {
-        readonly from: string | undefined;
-        readonly to: string | undefined;
-    };
-    readonly needsManualWhereChanged?: {
-        readonly from: boolean;
-        readonly to: boolean;
-    };
-};
+export type { ColumnChange, IndexChange };
 export type TableDiff = {
     readonly tableName: string;
     readonly newColumns: readonly ColumnMeta[];
@@ -73,12 +41,13 @@ export declare function hasNoSchemaChanges(input: {
     readonly retiredDrops: readonly RetiredFrameworkTable[];
     readonly rowLevelSecurityChanges: readonly RowLevelSecurityChange[];
 }): boolean;
-export declare function renderMigrationSql(diff: SchemaDiff, options: {
+type MigrationSqlOptions = {
     readonly name: string;
     readonly sequenceNumber: number;
     readonly retiredDrops?: readonly RetiredFrameworkTable[];
     readonly rowLevelSecurityChanges?: readonly RowLevelSecurityChange[];
-}): string;
+};
+export declare function renderMigrationSql(diff: SchemaDiff, options: MigrationSqlOptions): string;
 export type GenerateMigrationInput = {
     readonly metas: readonly EntityTableMeta[];
     readonly prevSnapshot: Snapshot | null;
@@ -101,4 +70,3 @@ export declare const MIGRATION_NAME_RE: RegExp;
 export declare function assertValidMigrationName(name: string): void;
 export declare function assertUniqueTableNames(metas: readonly EntityTableMeta[]): void;
 export declare function generateMigration(input: GenerateMigrationInput): GenerateMigrationOutput;
-export {};

package/dist/db/migrate-generator.js

@@ -16,6 +16,7 @@
 import { readFileSync, writeFileSync } from "node:fs";
 import { errorCodeOf, isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import { compareByCodepoint } from "../utils/compare.js";
+import { describeIndexChange, renderAddColumn, renderColumnChange, whereSqlEqual, } from "./migrate-change-render.js";
 import { diffPrimaryKey, renderPrimaryKeyChange, } from "./migrate-primary-key.js";
 import { diffRowLevelSecurity, renderRowLevelSecurityChanges, } from "./migrate-rls-diff.js";
 import { renderIndex, renderTableDdl } from "./render-ddl.js";
@@ -256,91 +257,95 @@ export function hasNoSchemaChanges(input) {
         input.retiredDrops.length === 0 &&
         input.rowLevelSecurityChanges.length === 0);
 }
-// --- SQL-Render ---------------------------------------------------------
-function renderColumnInline(col) {
-    const parts = [quoteIdent(col.name), col.pgType];
-    if (col.defaultSql !== undefined)
-        parts.push(`DEFAULT ${col.defaultSql}`);
-    if (col.notNull)
-        parts.push("NOT NULL");
-    return parts.join(" ");
-}
-function renderAddColumn(tableName, col) {
-    return `ALTER TABLE ${quoteIdent(tableName)} ADD COLUMN ${renderColumnInline(col)};`;
-}
-function renderColumnChange(tableName, change) {
-    const out = [];
-    const col = quoteIdent(change.name);
-    const tbl = quoteIdent(tableName);
-    if (change.nullabilityChanged) {
-        const op = change.nullabilityChanged.to ? "SET NOT NULL" : "DROP NOT NULL";
-        out.push(`ALTER TABLE ${tbl} ALTER COLUMN ${col} ${op};`);
-    }
-    if (change.defaultChanged) {
-        if (change.defaultChanged.to !== undefined) {
-            out.push(`ALTER TABLE ${tbl} ALTER COLUMN ${col} SET DEFAULT ${change.defaultChanged.to};`);
-        }
-        else {
-            out.push(`ALTER TABLE ${tbl} ALTER COLUMN ${col} DROP DEFAULT;`);
-        }
-    }
-    if (change.typeChanged) {
-        const { from, to } = change.typeChanged;
-        // timestamptz → date: PG's implicit ::date cast (what a bare ALTER ...
-        // TYPE without USING falls back to) reads the session TimeZone, so the
-        // same row migrates to a different calendar day depending on who/where
-        // runs it. Anchor explicitly at UTC instead of trusting the session.
-        if ((from === "timestamptz" || from === "timestamptz(3)") && to === "date") {
-            out.push(`-- ${from} → date: explicit UTC anchor — a bare cast would use the session TimeZone (non-deterministic).`);
-            out.push(`ALTER TABLE ${tbl} ALTER COLUMN ${col} TYPE date USING (${col} AT TIME ZONE 'UTC')::date;`);
-        }
-        else if (from === "date" && (to === "timestamptz" || to === "timestamptz(3)")) {
-            // Same non-determinism, reversed: a bare `date → timestamptz` cast
-            // interprets the calendar date at session-TimeZone midnight. Anchor
-            // explicitly at UTC midnight instead.
-            out.push(`-- date → ${to}: explicit UTC anchor — a bare cast would use the session TimeZone (non-deterministic).`);
-            out.push(`ALTER TABLE ${tbl} ALTER COLUMN ${col} TYPE ${to} USING (${col}::timestamp AT TIME ZONE 'UTC');`);
-        }
-        else {
-            // pg ALTER TYPE often needs a USING clause for non-implicitly-castable
-            // type changes. Emitted as a reviewer comment + raw cast — the app
-            // author has to confirm it's intended.
-            out.push(`-- WARN: column-type-change ${from} → ${to}. Review USING-clause if needed.`);
-            out.push(`ALTER TABLE ${tbl} ALTER COLUMN ${col} TYPE ${to};`);
-        }
-    }
-    return out;
-}
-// Collapses whitespace so a multi-line whereSql (e.g. a two-condition
-// drizzle sql`…` predicate) can't inject a newline into this `--` comment
-// line and escape into the executable body of the generated migration.
-function toSingleLine(text) {
-    return text.replace(/\s+/g, " ").trim();
-}
-function whereSqlEqual(a, b) {
-    if (a === undefined || b === undefined)
-        return a === b;
-    return toSingleLine(a) === toSingleLine(b);
-}
-function describeIndexChange(change) {
-    const parts = [];
-    if (change.columnsChanged) {
-        parts.push(`columns (${change.columnsChanged.from.join(", ")}) → (${change.columnsChanged.to.join(", ")})`);
-    }
-    if (change.uniqueChanged) {
-        parts.push(`unique ${change.uniqueChanged.from} → ${change.uniqueChanged.to}`);
-    }
-    if (change.whereSqlChanged) {
-        const from = change.whereSqlChanged.from !== undefined
-            ? toSingleLine(change.whereSqlChanged.from)
-            : "<none>";
-        const to = change.whereSqlChanged.to !== undefined ? toSingleLine(change.whereSqlChanged.to) : "<none>";
-        parts.push(`where ${from} → ${to}`);
-    }
-    if (change.needsManualWhereChanged) {
-        parts.push(`needs-manual-where ${change.needsManualWhereChanged.from} → ${change.needsManualWhereChanged.to}`);
+function renderMigrationHeader(options) {
+    const seq = options.sequenceNumber.toString().padStart(4, "0");
+    return [
+        `-- Migration ${seq}_${options.name}`,
+        `-- Generated: ${new Date().toISOString()}`,
+        "-- ",
+        "-- This file is generated by `kumiko-schema generate`. You may",
+        "-- hand-edit it before committing — add partial-indexes, BRIN-",
+        "-- variants, performance-tuning. After commit + apply, NEVER edit",
+        "-- this file again (production-DBs already ran it). Write a new",
+        "-- migration instead.",
+        "",
+    ];
+}
+function renderNewTables(newTables) {
+    if (newTables.length === 0)
+        return [];
+    return ["-- === New tables ===", ...newTables.flatMap((tbl) => [...renderTableDdl(tbl), ""])];
+}
+function renderRecreatedTable(td) {
+    return [
+        "-- managed projection — recreated + rebuilt from events (see .rebuild.json)",
+        `-- WARN: destructive change (${describeRecreateReasons(td).join("; ")}) forces DROP+CREATE + full event replay.`,
+        "-- Consider an Expand/Contract split across two releases to avoid the rebuild — see docs/guides/expand-contract-managed-projections.md.",
+        `DROP TABLE IF EXISTS ${quoteIdent(td.tableName)};`,
+        ...renderTableDdl(td.nextMeta),
+        "",
+    ];
+}
+function renderChangedIndex(td, idxChange) {
+    const nextIdxMeta = td.nextMeta.indexes.find((i) => i.name === idxChange.name);
+    if (!nextIdxMeta) {
+        throw new Error(`Index "${idxChange.name}" changed but is missing from the next table meta — generator bug in diffOneTable.`);
     }
-    return parts.join("; ");
+    return [
+        `-- index ${quoteIdent(idxChange.name)} changed (${describeIndexChange(idxChange)}) — recreated`,
+        // needsManualWhere renders CREATE as a commented WARN (renderIndex),
+        // since the generator can't express the new WHERE — the DROP has to
+        // stay commented too, or the live index gets dropped with no
+        // executable replacement.
+        nextIdxMeta.needsManualWhere === true
+            ? `-- (review) DROP INDEX IF EXISTS ${quoteIdent(idxChange.name)};`
+            : `DROP INDEX IF EXISTS ${quoteIdent(idxChange.name)};`,
+        renderIndex(td.tableName, nextIdxMeta),
+    ];
+}
+function renderInPlaceTableChanges(td) {
+    return [
+        ...td.newColumns.map((col) => renderAddColumn(td.tableName, col)),
+        ...td.changedColumns.flatMap((ch) => renderColumnChange(td.tableName, ch)),
+        ...renderPrimaryKeyChange(td.tableName, td.primaryKeyChanged),
+        ...td.newIndexes.map((idx) => renderIndex(td.tableName, idx)),
+        ...td.changedIndexes.flatMap((idxChange) => renderChangedIndex(td, idxChange)),
+        ...td.droppedIndexes.map((name) => `-- (review) DROP INDEX IF EXISTS ${quoteIdent(name)};`),
+        ...td.droppedColumns.map((colName) => `-- DESTRUCTIVE: ALTER TABLE ${quoteIdent(td.tableName)} DROP COLUMN ${quoteIdent(colName)};  -- uncomment + ensure backup`),
+        "",
+    ];
+}
+function renderChangedTables(changedTables) {
+    if (changedTables.length === 0)
+        return [];
+    return [
+        "-- === Changed tables ===",
+        ...changedTables.flatMap((td) => [
+            `-- ${td.tableName}`,
+            ...(isRecreatedManagedTable(td) ? renderRecreatedTable(td) : renderInPlaceTableChanges(td)),
+        ]),
+    ];
+}
+function renderDroppedTables(droppedTables) {
+    if (droppedTables.length === 0)
+        return [];
+    return [
+        "-- === Dropped tables ===",
+        ...droppedTables.map((name) => `-- DESTRUCTIVE: DROP TABLE IF EXISTS ${quoteIdent(name)};  -- uncomment + ensure backup + run during maintenance window`),
+        "",
+    ];
+}
+function renderRetiredDrops(retiredDrops) {
+    if (retiredDrops.length === 0)
+        return [];
+    return [
+        "-- === Retired framework tables ===",
+        ...retiredDrops.flatMap((retired) => [
+            `-- ${retired.tableName}: retired since framework ${retired.sinceVersion} — ${retired.explanation}`,
+            `DROP TABLE IF EXISTS ${quoteIdent(retired.tableName)};`,
+        ]),
+        "",
+    ];
 }
 // Render the diff as a SQL-file content with header-comment + grouped
 // statements. Destructive operations (DROP TABLE/COLUMN, DROP INDEX where
@@ -348,93 +353,16 @@ function describeIndexChange(change) {
 // for explicit reviewer-action.
 export function renderMigrationSql(diff, options) {
     const retiredDrops = options.retiredDrops ?? [];
-    const lines = [];
-    const seq = options.sequenceNumber.toString().padStart(4, "0");
-    lines.push(`-- Migration ${seq}_${options.name}`);
-    lines.push(`-- Generated: ${new Date().toISOString()}`);
-    lines.push("-- ");
-    lines.push("-- This file is generated by `kumiko-schema generate`. You may");
-    lines.push("-- hand-edit it before committing — add partial-indexes, BRIN-");
-    lines.push("-- variants, performance-tuning. After commit + apply, NEVER edit");
-    lines.push("-- this file again (production-DBs already ran it). Write a new");
-    lines.push("-- migration instead.");
-    lines.push("");
-    if (diff.newTables.length > 0) {
-        lines.push("-- === New tables ===");
-        for (const tbl of diff.newTables) {
-            lines.push(...renderTableDdl(tbl));
-            lines.push("");
-        }
-    }
-    if (diff.changedTables.length > 0) {
-        lines.push("-- === Changed tables ===");
-        for (const td of diff.changedTables) {
-            lines.push(`-- ${td.tableName}`);
-            if (isRecreatedManagedTable(td)) {
-                lines.push("-- managed projection — recreated + rebuilt from events (see .rebuild.json)");
-                lines.push(`-- WARN: destructive change (${describeRecreateReasons(td).join("; ")}) forces DROP+CREATE + full event replay.`);
-                lines.push("-- Consider an Expand/Contract split across two releases to avoid the rebuild — see docs/guides/expand-contract-managed-projections.md.");
-                lines.push(`DROP TABLE IF EXISTS ${quoteIdent(td.tableName)};`);
-                lines.push(...renderTableDdl(td.nextMeta));
-                lines.push("");
-                continue;
-            }
-            for (const col of td.newColumns) {
-                lines.push(renderAddColumn(td.tableName, col));
-            }
-            for (const ch of td.changedColumns) {
-                for (const stmt of renderColumnChange(td.tableName, ch))
-                    lines.push(stmt);
-            }
-            lines.push(...renderPrimaryKeyChange(td.tableName, td.primaryKeyChanged));
-            for (const idx of td.newIndexes) {
-                lines.push(renderIndex(td.tableName, idx));
-            }
-            for (const idxChange of td.changedIndexes) {
-                const nextIdxMeta = td.nextMeta.indexes.find((i) => i.name === idxChange.name);
-                if (!nextIdxMeta) {
-                    throw new Error(`Index "${idxChange.name}" changed but is missing from the next table meta — generator bug in diffOneTable.`);
-                }
-                lines.push(`-- index ${quoteIdent(idxChange.name)} changed (${describeIndexChange(idxChange)}) — recreated`);
-                // needsManualWhere renders CREATE as a commented WARN (renderIndex),
-                // since the generator can't express the new WHERE — the DROP has to
-                // stay commented too, or the live index gets dropped with no
-                // executable replacement.
-                lines.push(nextIdxMeta.needsManualWhere === true
-                    ? `-- (review) DROP INDEX IF EXISTS ${quoteIdent(idxChange.name)};`
-                    : `DROP INDEX IF EXISTS ${quoteIdent(idxChange.name)};`);
-                lines.push(renderIndex(td.tableName, nextIdxMeta));
-            }
-            for (const name of td.droppedIndexes) {
-                lines.push(`-- (review) DROP INDEX IF EXISTS ${quoteIdent(name)};`);
-            }
-            for (const colName of td.droppedColumns) {
-                lines.push(`-- DESTRUCTIVE: ALTER TABLE ${quoteIdent(td.tableName)} DROP COLUMN ${quoteIdent(colName)};  -- uncomment + ensure backup`);
-            }
-            lines.push("");
-        }
-    }
-    lines.push(...renderRowLevelSecurityChanges(options.rowLevelSecurityChanges));
-    if (diff.droppedTables.length > 0) {
-        lines.push("-- === Dropped tables ===");
-        for (const name of diff.droppedTables) {
-            lines.push(`-- DESTRUCTIVE: DROP TABLE IF EXISTS ${quoteIdent(name)};  -- uncomment + ensure backup + run during maintenance window`);
-        }
-        lines.push("");
-    }
-    if (retiredDrops.length > 0) {
-        lines.push("-- === Retired framework tables ===");
-        for (const retired of retiredDrops) {
-            lines.push(`-- ${retired.tableName}: retired since framework ${retired.sinceVersion} — ${retired.explanation}`);
-            lines.push(`DROP TABLE IF EXISTS ${quoteIdent(retired.tableName)};`);
-        }
-        lines.push("");
-    }
-    if (hasNoSchemaChanges({
-        diff,
-        retiredDrops,
-        rowLevelSecurityChanges: options.rowLevelSecurityChanges ?? [],
-    })) {
+    const rowLevelSecurityChanges = options.rowLevelSecurityChanges ?? [];
+    const lines = [
+        ...renderMigrationHeader(options),
+        ...renderNewTables(diff.newTables),
+        ...renderChangedTables(diff.changedTables),
+        ...renderRowLevelSecurityChanges(options.rowLevelSecurityChanges),
+        ...renderDroppedTables(diff.droppedTables),
+        ...renderRetiredDrops(retiredDrops),
+    ];
+    if (hasNoSchemaChanges({ diff, retiredDrops, rowLevelSecurityChanges })) {
         lines.push("-- No schema changes detected.");
     }
     return lines.join("\n");