pg-admin-mcp 0.0.0-stage → 0.1.0

package/dist/snapshot/migrate.js

@@ -0,0 +1,1596 @@
+import { quoteIdent } from '../core/identifiers.js';
+import { functionKey } from './model.js';
+/** Thrown by {@link topoSort} when the graph cannot be linearized — see the module doc's "What happens on a genuine cycle" section. */
+export class DependencyCycleError extends Error {
+    cycle;
+    constructor(cycle) {
+        super(`dependency cycle detected — these nodes can never become ready: ${cycle.join(', ')}`);
+        this.name = 'DependencyCycleError';
+        this.cycle = cycle;
+    }
+}
+/**
+ * Plain Kahn's algorithm: repeatedly emit a node with no remaining
+ * unsatisfied dependency, lowest `(sortKey, id)` first among ties. Anything
+ * left when the ready queue runs dry is, by definition, part of (or depends
+ * on) a cycle.
+ */
+export function topoSort(nodes) {
+    const byId = new Map(nodes.map((n) => [n.id, n]));
+    const inDegree = new Map();
+    const dependents = new Map();
+    for (const n of nodes) {
+        inDegree.set(n.id, 0);
+        dependents.set(n.id, []);
+    }
+    for (const n of nodes) {
+        let degree = 0;
+        for (const dep of n.dependsOn) {
+            if (!byId.has(dep))
+                continue; // outside this graph — see the field doc
+            degree++;
+            dependents.get(dep)?.push(n.id);
+        }
+        inDegree.set(n.id, degree);
+    }
+    const bySort = (a, b) => {
+        const na = byId.get(a);
+        const nb = byId.get(b);
+        const ka = na?.sortKey ?? 0;
+        const kb = nb?.sortKey ?? 0;
+        if (ka !== kb)
+            return ka - kb;
+        return a < b ? -1 : a > b ? 1 : 0;
+    };
+    const ready = [...inDegree.entries()].filter(([, d]) => d === 0).map(([id]) => id);
+    ready.sort(bySort);
+    const order = [];
+    const seen = new Set();
+    while (ready.length > 0) {
+        // Small graphs (a schema diff is at most a few hundred statements) — a
+        // sorted-insert into an array is simpler than a real priority queue and
+        // fast enough here.
+        const id = ready.shift();
+        if (id === undefined)
+            break;
+        seen.add(id);
+        const node = byId.get(id);
+        if (node !== undefined)
+            order.push(node.value);
+        for (const dep of dependents.get(id) ?? []) {
+            const remaining = (inDegree.get(dep) ?? 0) - 1;
+            inDegree.set(dep, remaining);
+            if (remaining === 0) {
+                const idx = ready.findIndex((r) => bySort(dep, r) < 0);
+                if (idx === -1)
+                    ready.push(dep);
+                else
+                    ready.splice(idx, 0, dep);
+            }
+        }
+    }
+    if (order.length < nodes.length) {
+        const stuck = nodes.filter((n) => !seen.has(n.id)).map((n) => n.id);
+        throw new DependencyCycleError(stuck);
+    }
+    return order;
+}
+// ---------------------------------------------------------------------------
+// Small SQL-building helpers.
+// ---------------------------------------------------------------------------
+function qualify(schema, name) {
+    return `${quoteIdent(schema)}.${quoteIdent(name)}`;
+}
+/** Quotes each dot-separated segment of an already-qualified catalog name (e.g. an `inherits` entry). */
+function quoteQualifiedName(qualified) {
+    return qualified
+        .split('.')
+        .map((seg) => quoteIdent(seg))
+        .join('.');
+}
+function splitFirstDot(path) {
+    const i = path.indexOf('.');
+    if (i === -1)
+        return { schema: path, rest: '' };
+    return { schema: path.slice(0, i), rest: path.slice(i + 1) };
+}
+/** `schema.table.leaf` — takes the *last* segment as the leaf and the *second-to-last* as the table, so a schema name is never mistaken for one. Inherits the same "no literal dots in names" assumption `diff.ts#diffList`'s own `path` building already makes; not a new limitation introduced here. */
+function splitTablePath(path) {
+    const segs = path.split('.');
+    const leaf = segs.pop() ?? '';
+    const table = segs.pop() ?? '';
+    return { schema: segs.join('.'), table, leaf };
+}
+/** `name(args)` -> `{ name, args }`. Functions do not legally contain `(` in an unquoted name; the rare quoted-name case with a literal `(` is not handled. */
+function splitFunctionKey(key) {
+    const i = key.indexOf('(');
+    if (i === -1)
+        return { name: key, args: '' };
+    return { name: key.slice(0, i), args: key.slice(i + 1, -1) };
+}
+const VOLATILE_DEFAULT = /\b(now|clock_timestamp|statement_timestamp|transaction_timestamp|random|gen_random_uuid|uuid_generate_v4|txid_current)\s*\(|nextval\s*\(/i;
+function columnDefClause(col) {
+    const parts = [`${quoteIdent(col.name)} ${col.type}`];
+    if (col.generated === 'stored') {
+        // ponytail: a collation on a generated column is vanishingly rare and not
+        // representable alongside GENERATED ... STORED in the same clause; not handled.
+        parts.push(`GENERATED ALWAYS AS (${col.default ?? 'NULL'}) STORED`);
+    }
+    else {
+        if (col.collation !== null)
+            parts.push(`COLLATE ${quoteIdent(col.collation)}`);
+        if (col.identity !== null)
+            parts.push(`GENERATED ${col.identity === 'always' ? 'ALWAYS' : 'BY DEFAULT'} AS IDENTITY`);
+        if (col.default !== null)
+            parts.push(`DEFAULT ${col.default}`);
+    }
+    if (!col.nullable)
+        parts.push('NOT NULL');
+    return parts.join(' ');
+}
+function field(fields, name) {
+    return fields.find((f) => f.field === name);
+}
+/**
+ * `diffSnapshots` only calls its per-object-type `nested` diff (columns,
+ * constraints, indexes, …) when an object exists on *both* sides — an object
+ * that is wholly added or removed instead carries its full nested content as
+ * `object` and relies on the consumer to walk it (`diff.ts`'s own header
+ * comment: "migrate.ts needs it to emit the CREATE/DROP"). A table already
+ * carries everything it needs flat on one object (columns, keys, indexes,
+ * triggers, policies — see `handleTable`'s `added` branch). A whole *schema*
+ * does not: `SnapshotSchema` nests tables/views/materialized views/
+ * sequences/functions/enums, each of which is its own top-level object type
+ * with its own handler. This expands a wholly added/removed `schema` change
+ * into that schema change *plus* one added/removed change per nested object,
+ * so the existing per-object-type handlers below build every one of them
+ * without duplicating their logic.
+ */
+function expandSchemaChanges(changes) {
+    const out = [];
+    for (const c of changes) {
+        out.push(c);
+        if (c.objectType !== 'schema' || c.kind === 'modified')
+            continue;
+        const schema = c.object;
+        const schemaName = c.path;
+        for (const t of schema.tables)
+            out.push({ kind: c.kind, objectType: 'table', path: `${schemaName}.${t.name}`, object: t });
+        for (const v of schema.views)
+            out.push({ kind: c.kind, objectType: 'view', path: `${schemaName}.${v.name}`, object: v });
+        for (const mv of schema.materializedViews)
+            out.push({ kind: c.kind, objectType: 'materialized_view', path: `${schemaName}.${mv.name}`, object: mv });
+        for (const s of schema.sequences)
+            out.push({ kind: c.kind, objectType: 'sequence', path: `${schemaName}.${s.name}`, object: s });
+        for (const fn of schema.functions)
+            out.push({ kind: c.kind, objectType: 'function', path: `${schemaName}.${functionKey(fn)}`, object: fn });
+        for (const e of schema.enums)
+            out.push({ kind: c.kind, objectType: 'enum', path: `${schemaName}.${e.name}`, object: e });
+    }
+    return out;
+}
+const PHASE = {
+    SCHEMA_CREATE: 0,
+    ENUM_CREATE: 10,
+    ENUM_ALTER: 11,
+    EXTENSION_CREATE: 12,
+    EXTENSION_ALTER: 13,
+    SEQUENCE_CREATE: 20,
+    SEQUENCE_ALTER: 21,
+    TABLE_CREATE: 30,
+    TABLE_ALTER: 31,
+    VIEW_CREATE: 40,
+    VIEW_ALTER: 41,
+    FUNCTION_CREATE: 50,
+    FUNCTION_ALTER: 51,
+    COLUMN_ADD: 60,
+    COLUMN_ALTER: 61,
+    INDEX_CREATE: 70,
+    CONSTRAINT_ADD: 80,
+    FK_ADD: 90,
+    TRIGGER_CREATE: 100,
+    POLICY_CREATE: 110,
+    RLS_ALTER: 111,
+    RLS_DISABLE: 200,
+    POLICY_DROP: 201,
+    TRIGGER_DROP: 202,
+    FK_DROP: 203,
+    INDEX_DROP: 204,
+    CONSTRAINT_DROP: 205,
+    COLUMN_DROP: 206,
+    VIEW_DROP: 207,
+    TABLE_DROP: 208,
+    SEQUENCE_DROP: 209,
+    FUNCTION_DROP: 210,
+    ENUM_DROP: 211,
+    EXTENSION_DROP: 212,
+    SCHEMA_DROP: 213,
+};
+class Builder {
+    drafts = [];
+    unsupported = [];
+    extraDeps = new Map();
+    tableCreateIds;
+    tableDropIds;
+    enumCreateIds;
+    /** Schema names being wholly dropped in this plan — every nested object's drop statement must land before that schema's DROP SCHEMA, so it does not fail with "schema not empty". See `expandSchemaChanges`. */
+    schemaDropNames;
+    /** `schema\0name` -> the statements that create something under that name. See {@link claimName}. */
+    nameClaims = new Map();
+    /** `schema\0name` -> the statements that free that name. See {@link claimName}. */
+    nameReleases = new Map();
+    constructor(changes) {
+        // Pre-scan so any later edge check ("does this table also get created in
+        // this plan?") is order-independent — see the module doc, rule 6.
+        this.tableCreateIds = new Set(changes.filter((c) => c.objectType === 'table' && c.kind === 'added').map((c) => `table:${c.path}`));
+        this.tableDropIds = new Set(changes.filter((c) => c.objectType === 'table' && c.kind === 'removed').map((c) => `tableDrop:${c.path}`));
+        this.enumCreateIds = new Set(changes.filter((c) => c.objectType === 'enum' && c.kind === 'added').map((c) => `enum:${c.path}`));
+        this.schemaDropNames = new Set(changes.filter((c) => c.objectType === 'schema' && c.kind === 'removed').map((c) => c.path));
+    }
+    /** Wires `dropId` to finish before its owning schema's DROP SCHEMA, when that schema is itself being dropped in this plan. */
+    linkToSchemaDrop(schema, dropId) {
+        if (this.schemaDropNames.has(schema))
+            this.addExtraDep(`schemaDrop:${schema}`, dropId);
+    }
+    has(id) {
+        return this.tableCreateIds.has(id) || this.tableDropIds.has(id) || this.enumCreateIds.has(id) || this.drafts.some((d) => d.id === id);
+    }
+    emit(id, deps, sortKey, stmt) {
+        this.drafts.push({ id, deps: new Set(deps), sortKey, stmt });
+    }
+    /** Adds a dependency edge from `targetId` onto `dependsOnId`, applied even if `targetId` has not been emitted yet. */
+    addExtraDep(targetId, dependsOnId) {
+        const set = this.extraDeps.get(targetId) ?? new Set();
+        set.add(dependsOnId);
+        this.extraDeps.set(targetId, set);
+    }
+    markUnsupported(objectType, path, changeKind, reason) {
+        this.unsupported.push({ objectType, path, changeKind, reason });
+    }
+    /**
+     * Records that `claim.id` will occupy `name` in `schema`. Tables, views,
+     * materialized views, sequences, indexes and the indexes behind PRIMARY
+     * KEY/UNIQUE constraints all share one per-schema namespace (`pg_class`), and
+     * an enum's type name collides with a table's there too (every table gets a
+     * composite type of the same name). See {@link resolveNameCollisions}.
+     */
+    claimName(schema, name, claim) {
+        const key = `${schema}\u0000${name}`;
+        const list = this.nameClaims.get(key) ?? [];
+        list.push(claim);
+        this.nameClaims.set(key, list);
+    }
+    /** Records that `dropId` frees `name` in `schema`. Counterpart of {@link claimName}. */
+    releaseName(schema, name, dropId) {
+        const key = `${schema}\u0000${name}`;
+        const list = this.nameReleases.get(key) ?? [];
+        list.push(dropId);
+        this.nameReleases.set(key, list);
+    }
+    /** True when `from` already (transitively) depends on `to`. Used only to refuse an edge that would close a cycle. */
+    dependsOn(from, to) {
+        const seen = new Set();
+        const stack = [from];
+        while (stack.length > 0) {
+            const id = stack.pop();
+            if (id === undefined || seen.has(id))
+                continue;
+            seen.add(id);
+            if (id === to)
+                return true;
+            const draft = this.drafts.find((d) => d.id === id);
+            if (draft !== undefined)
+                stack.push(...draft.deps);
+            const extra = this.extraDeps.get(id);
+            if (extra !== undefined)
+                stack.push(...extra);
+        }
+        return false;
+    }
+    /**
+     * A rename is drop + create in the snapshot model, and the phase numbers put
+     * every create before every drop — so a `CREATE` reusing a name the plan has
+     * not dropped yet fails ("relation … already exists"), mid-run in a large
+     * plan. PostgreSQL preserves constraint and index names across `ALTER TABLE
+     * … RENAME`, so this bites even when the two relation names differ: the old
+     * table's `widgets_pkey` index is still there when the new table declares
+     * its own `widgets_pkey`.
+     *
+     * Every create that claims a name some drop in the same schema frees gets an
+     * explicit edge onto that drop, which overrides the phase ordering (the
+     * phase number is a tie-break, never a dependency — see the module doc).
+     */
+    resolveNameCollisions() {
+        for (const [key, claims] of this.nameClaims) {
+            const drops = this.nameReleases.get(key);
+            if (drops === undefined)
+                continue;
+            const name = key.slice(key.indexOf('\u0000') + 1);
+            for (const claim of claims) {
+                for (const dropId of drops) {
+                    if (this.dependsOn(dropId, claim.id)) {
+                        this.markUnsupported(claim.objectType, claim.path, claim.changeKind, `this statement needs the name "${name}" freed by another statement in this plan that in turn depends on this one — a rename cannot be expressed as drop+create without a name collision. Rename manually with ALTER TABLE ... RENAME (which preserves the data, unlike drop+create) and re-diff.`);
+                        continue;
+                    }
+                    this.addExtraDep(claim.id, dropId);
+                }
+            }
+        }
+    }
+    toGraph() {
+        return this.drafts.map((d) => {
+            const extra = this.extraDeps.get(d.id);
+            const deps = extra === undefined ? [...d.deps] : [...d.deps, ...extra];
+            return { id: d.id, value: d.stmt, dependsOn: deps, sortKey: d.sortKey };
+        });
+    }
+}
+// ---------------------------------------------------------------------------
+// Per-object-type handlers.
+// ---------------------------------------------------------------------------
+function handleSchema(b, c) {
+    const name = c.path;
+    if (c.kind === 'added') {
+        b.emit(`schema:${name}`, [], PHASE.SCHEMA_CREATE, {
+            sql: `CREATE SCHEMA ${quoteIdent(name)};`,
+            objectType: 'schema',
+            path: name,
+            changeKind: 'added',
+            risk: 'safe',
+            riskNote: 'creates an empty namespace — nothing else in the database is affected.',
+            reversible: true,
+            down: `DROP SCHEMA ${quoteIdent(name)};`,
+        });
+        return;
+    }
+    if (c.kind === 'removed') {
+        b.emit(`schemaDrop:${name}`, [], PHASE.SCHEMA_DROP, {
+            sql: `DROP SCHEMA ${quoteIdent(name)};`,
+            objectType: 'schema',
+            path: name,
+            changeKind: 'removed',
+            risk: 'high',
+            riskNote: 'fails outright if the schema still contains anything (this plan drops its contents first via their own statements); once it succeeds, the schema and every object it owned are gone.',
+            reversible: false,
+            downNote: 'cannot restore: the schema and everything it owned (tables, data, functions, …) are gone once this runs.',
+        });
+        return;
+    }
+    const owner = field(c.fields, 'owner');
+    if (owner !== undefined) {
+        b.emit(`schemaOwner:${name}`, [], PHASE.SCHEMA_CREATE, {
+            sql: `ALTER SCHEMA ${quoteIdent(name)} OWNER TO ${quoteIdent(String(owner.after))};`,
+            objectType: 'schema',
+            path: name,
+            changeKind: 'modified',
+            risk: 'low',
+            riskNote: 'metadata-only ownership change; grants and object contents are untouched.',
+            reversible: true,
+            down: `ALTER SCHEMA ${quoteIdent(name)} OWNER TO ${quoteIdent(String(owner.before))};`,
+        });
+    }
+}
+function handleExtension(b, c) {
+    const name = c.path;
+    if (c.kind === 'added') {
+        const obj = c.object;
+        b.emit(`extension:${name}`, [], PHASE.EXTENSION_CREATE, {
+            sql: `CREATE EXTENSION ${quoteIdent(name)} VERSION '${obj.version}';`,
+            objectType: 'extension',
+            path: name,
+            changeKind: 'added',
+            risk: 'moderate',
+            riskNote: 'runs the extension\'s own install script, which can create arbitrary objects (types, functions, operators) with the privileges of the installing role — review what the extension installs before applying.',
+            reversible: true,
+            down: `DROP EXTENSION ${quoteIdent(name)};`,
+        });
+        return;
+    }
+    if (c.kind === 'removed') {
+        b.emit(`extensionDrop:${name}`, [], PHASE.EXTENSION_DROP, {
+            sql: `DROP EXTENSION ${quoteIdent(name)};`,
+            objectType: 'extension',
+            path: name,
+            changeKind: 'removed',
+            risk: 'high',
+            riskNote: 'drops every object the extension owns (its functions, types, operators); anything a table or view built on top of those becomes broken unless it is also being dropped in this same plan.',
+            reversible: false,
+            downNote: 'cannot restore: any object that depended on what the extension provided, and was dropped along with it, is not recoverable by reinstalling the extension.',
+        });
+        return;
+    }
+    const version = field(c.fields, 'version');
+    if (version !== undefined) {
+        b.emit(`extensionAlter:${name}`, [], PHASE.EXTENSION_ALTER, {
+            sql: `ALTER EXTENSION ${quoteIdent(name)} UPDATE TO '${String(version.after)}';`,
+            objectType: 'extension',
+            path: name,
+            changeKind: 'modified',
+            risk: 'moderate',
+            riskNote: 'runs the extension\'s own update script for every version step between the old and new version — review the extension\'s changelog first.',
+            reversible: true,
+            down: `ALTER EXTENSION ${quoteIdent(name)} UPDATE TO '${String(version.before)}';`,
+            downNote: 'downgrade support depends entirely on the extension itself; not every extension ships a script for moving backward.',
+        });
+    }
+}
+function handleEnum(b, c) {
+    const { schema, rest: enumName } = splitFirstDot(c.path);
+    const id = `enum:${c.path}`;
+    if (c.kind === 'added') {
+        const obj = c.object;
+        const labelList = obj.labels.map((l) => `'${l.replace(/'/g, "''")}'`).join(', ');
+        b.claimName(schema, enumName, { id, objectType: 'enum', path: c.path, changeKind: 'added' });
+        b.emit(id, [`schema:${schema}`], PHASE.ENUM_CREATE, {
+            sql: `CREATE TYPE ${qualify(schema, enumName)} AS ENUM (${labelList});`,
+            objectType: 'enum',
+            path: c.path,
+            changeKind: 'added',
+            risk: 'safe',
+            riskNote: 'creates a new type; nothing references it yet.',
+            reversible: true,
+            down: `DROP TYPE ${qualify(schema, enumName)};`,
+        });
+        return;
+    }
+    if (c.kind === 'removed') {
+        const enumDropId = `enumDrop:${c.path}`;
+        b.releaseName(schema, enumName, enumDropId);
+        b.emit(enumDropId, [], PHASE.ENUM_DROP, {
+            sql: `DROP TYPE ${qualify(schema, enumName)};`,
+            objectType: 'enum',
+            path: c.path,
+            changeKind: 'removed',
+            risk: 'high',
+            riskNote: 'fails if any column still uses this type — every such column must already have been changed to a different type earlier in this plan (or dropped) before this statement can succeed.',
+            reversible: false,
+            downNote: 'cannot restore: recreating the type does not restore the columns that used to reference it, or their data.',
+        });
+        b.linkToSchemaDrop(schema, enumDropId);
+        return;
+    }
+    const labels = field(c.fields, 'labels');
+    if (labels !== undefined) {
+        const before = labels.before;
+        const after = labels.after;
+        if (isPureInsertion(before, after)) {
+            let prevId;
+            let cursor = 0;
+            for (let i = 0; i < after.length; i++) {
+                const label = after[i];
+                if (cursor < before.length && before[cursor] === label) {
+                    cursor++;
+                    continue;
+                }
+                // `ADD VALUE ... BEFORE x` requires x to *already exist* — so the
+                // anchor must be the next label that was in `before`, not merely the
+                // next one in `after` (which can itself be another new label this same
+                // loop has not added yet: ['a','d'] -> ['a','b','c','d'] would anchor
+                // 'b' on 'c'). With no such label left, there is nothing after this
+                // one that already exists, so appending is exactly right. Successive
+                // new labels sharing one anchor each land immediately before it, in
+                // loop order, which reproduces `after`.
+                const anchor = after.slice(i + 1).find((l) => before.includes(l));
+                const stmtId = `enumAlter:${c.path}:${i}`;
+                const clause = anchor === undefined ? '' : ` BEFORE '${anchor.replace(/'/g, "''")}'`;
+                b.emit(stmtId, prevId === undefined ? [] : [prevId], PHASE.ENUM_ALTER, {
+                    sql: `ALTER TYPE ${qualify(schema, enumName)} ADD VALUE '${label.replace(/'/g, "''")}'${clause};`,
+                    objectType: 'enum',
+                    path: c.path,
+                    changeKind: 'modified',
+                    risk: 'low',
+                    riskNote: 'appends (or inserts) one label; existing rows and existing labels are untouched. PostgreSQL cannot run this inside the same transaction as a statement that already used the type in this session — apply it as its own statement.',
+                    reversible: false,
+                    downNote: 'cannot restore: PostgreSQL has no ALTER TYPE ... DROP VALUE — removing an enum label requires recreating the type and rewriting every column that uses it.',
+                });
+                prevId = stmtId;
+            }
+        }
+        else {
+            b.markUnsupported('enum', c.path, 'modified', 'labels were removed or reordered without a pure insertion — PostgreSQL cannot drop or reorder enum labels without recreating the type and rewriting every column that uses it; not attempted.');
+        }
+    }
+    const comment = field(c.fields, 'comment');
+    if (comment !== undefined) {
+        b.emit(`enumComment:${c.path}`, [], PHASE.ENUM_ALTER, commentStatement('enum', c.path, `TYPE ${qualify(schema, enumName)}`, comment));
+    }
+}
+/** True when `after` equals `before` with zero or more labels inserted, in order — i.e. `before` is a subsequence of `after`. */
+function isPureInsertion(before, after) {
+    let i = 0;
+    for (const label of after) {
+        if (i < before.length && before[i] === label)
+            i++;
+    }
+    return i === before.length;
+}
+function commentStatement(objectType, path, onClause, change) {
+    const after = change.after === null ? 'NULL' : `'${String(change.after).replace(/'/g, "''")}'`;
+    const before = change.before === null ? 'NULL' : `'${String(change.before).replace(/'/g, "''")}'`;
+    return {
+        sql: `COMMENT ON ${onClause} IS ${after};`,
+        objectType,
+        path,
+        changeKind: 'modified',
+        risk: 'safe',
+        riskNote: 'documentation only — no effect on data, access, or behaviour.',
+        reversible: true,
+        down: `COMMENT ON ${onClause} IS ${before};`,
+    };
+}
+function handleSequence(b, c) {
+    const { schema: sSchema, rest: sName } = splitFirstDot(c.path);
+    if (c.kind === 'added') {
+        const s = c.object;
+        b.claimName(sSchema, sName, { id: `sequence:${c.path}`, objectType: 'sequence', path: c.path, changeKind: 'added' });
+        b.emit(`sequence:${c.path}`, [`schema:${sSchema}`], PHASE.SEQUENCE_CREATE, {
+            sql: `CREATE SEQUENCE ${qualify(sSchema, sName)} AS ${s.dataType} INCREMENT BY ${s.incrementBy} ` +
+                `MINVALUE ${s.minValue} MAXVALUE ${s.maxValue} START WITH ${s.startValue} CACHE ${s.cacheSize} ${s.cycle ? 'CYCLE' : 'NO CYCLE'};`,
+            objectType: 'sequence',
+            path: c.path,
+            changeKind: 'added',
+            risk: 'safe',
+            riskNote: 'creates a new counter; nothing depends on it yet.',
+            reversible: true,
+            down: `DROP SEQUENCE ${qualify(sSchema, sName)};`,
+        });
+        return;
+    }
+    if (c.kind === 'removed') {
+        const sequenceDropId = `sequenceDrop:${c.path}`;
+        b.releaseName(sSchema, sName, sequenceDropId);
+        b.emit(sequenceDropId, [], PHASE.SEQUENCE_DROP, {
+            sql: `DROP SEQUENCE ${qualify(sSchema, sName)};`,
+            objectType: 'sequence',
+            path: c.path,
+            changeKind: 'removed',
+            risk: 'high',
+            riskNote: 'fails if a column default still calls nextval() on it; that default must already be dropped or changed earlier in this plan. Any column whose identity/default depended on it stops working once this runs.',
+            reversible: false,
+            downNote: 'the sequence itself was deliberately never captured with its current counter position (model.ts: "a sequence\'s last_value is data, not schema") — recreating it restores the structure (increment, bounds, cycle) but not the exact value it was at when dropped.',
+        });
+        b.linkToSchemaDrop(sSchema, sequenceDropId);
+        return;
+    }
+    const clauses = [];
+    const down = [];
+    const map = {
+        dataType: 'AS',
+        incrementBy: 'INCREMENT BY',
+        minValue: 'MINVALUE',
+        maxValue: 'MAXVALUE',
+        startValue: 'START WITH',
+        cacheSize: 'CACHE',
+    };
+    for (const [f, keyword] of Object.entries(map)) {
+        const ch = field(c.fields, f);
+        if (ch !== undefined) {
+            clauses.push(`${keyword} ${String(ch.after)}`);
+            down.push(`${keyword} ${String(ch.before)}`);
+        }
+    }
+    const cycle = field(c.fields, 'cycle');
+    if (cycle !== undefined) {
+        clauses.push(cycle.after === true ? 'CYCLE' : 'NO CYCLE');
+        down.push(cycle.before === true ? 'CYCLE' : 'NO CYCLE');
+    }
+    if (clauses.length > 0) {
+        b.emit(`sequenceAlter:${c.path}`, [], PHASE.SEQUENCE_ALTER, {
+            sql: `ALTER SEQUENCE ${qualify(sSchema, sName)} ${clauses.join(' ')};`,
+            objectType: 'sequence',
+            path: c.path,
+            changeKind: 'modified',
+            risk: field(c.fields, 'dataType') === undefined ? 'low' : 'moderate',
+            riskNote: field(c.fields, 'dataType') === undefined
+                ? 'metadata-only; does not move the current counter position.'
+                : 'changing the underlying data type fails if the sequence\'s current value is out of range for the new type.',
+            reversible: true,
+            down: `ALTER SEQUENCE ${qualify(sSchema, sName)} ${down.join(' ')};`,
+        });
+    }
+    const owner = field(c.fields, 'owner');
+    if (owner !== undefined) {
+        b.emit(`sequenceOwner:${c.path}`, [], PHASE.SEQUENCE_ALTER, {
+            sql: `ALTER SEQUENCE ${qualify(sSchema, sName)} OWNER TO ${quoteIdent(String(owner.after))};`,
+            objectType: 'sequence',
+            path: c.path,
+            changeKind: 'modified',
+            risk: 'low',
+            riskNote: 'metadata-only ownership change.',
+            reversible: true,
+            down: `ALTER SEQUENCE ${qualify(sSchema, sName)} OWNER TO ${quoteIdent(String(owner.before))};`,
+        });
+    }
+    const comment = field(c.fields, 'comment');
+    if (comment !== undefined) {
+        b.emit(`sequenceComment:${c.path}`, [], PHASE.SEQUENCE_ALTER, commentStatement('sequence', c.path, `SEQUENCE ${qualify(sSchema, sName)}`, comment));
+    }
+}
+function handleFunction(b, c) {
+    const { schema } = splitFirstDot(c.path);
+    const key = splitFirstDot(c.path).rest;
+    const { name, args } = splitFunctionKey(key);
+    if (c.kind === 'added') {
+        const f = c.object;
+        if (f.kind !== 'f') {
+            b.markUnsupported('function', c.path, 'added', `pg_proc.prokind = '${f.kind}' (procedure/aggregate/window) — only a plain function's body/return type/language is captured; recreating one of these needs attributes (strictness, volatility, argument defaults, transition/final functions, …) this server does not capture. Not attempted.`);
+            return;
+        }
+        if (f.body === null) {
+            b.markUnsupported('function', c.path, 'added', 'the function body was not captured (NULL prosrc — likely a C/internal-language function); nothing to recreate from.');
+            return;
+        }
+        b.emit(`function:${c.path}`, [`schema:${schema}`], PHASE.FUNCTION_CREATE, {
+            sql: `CREATE FUNCTION ${qualify(schema, f.name)}(${f.arguments}) RETURNS ${f.returns} LANGUAGE ${quoteIdent(f.language)} AS $migrate$${f.body}$migrate$;`,
+            objectType: 'function',
+            path: c.path,
+            changeKind: 'added',
+            risk: 'moderate',
+            riskNote: 'best-effort: recreates the body, return type and language only — volatility, strictness, security definer, cost/rows estimates and argument defaults are not captured by a snapshot and are not reproduced here. Review the created function\'s attributes if any of those matter.',
+            reversible: true,
+            down: `DROP FUNCTION ${qualify(schema, f.name)}(${f.arguments});`,
+        });
+        return;
+    }
+    if (c.kind === 'removed') {
+        const functionDropId = `functionDrop:${c.path}`;
+        b.emit(functionDropId, [], PHASE.FUNCTION_DROP, {
+            sql: `DROP FUNCTION ${qualify(schema, name)}(${args});`,
+            objectType: 'function',
+            path: c.path,
+            changeKind: 'removed',
+            risk: 'high',
+            riskNote: 'fails if anything still depends on it (a trigger, a view, another function) — those must already be handled earlier in this plan. Anything that called it stops working once this runs.',
+            reversible: false,
+            downNote: 'recreating a dropped function from this diff alone would need its full definition (attributes this server does not capture — see the module\'s header comment); not attempted.',
+        });
+        b.linkToSchemaDrop(schema, functionDropId);
+        return;
+    }
+    const changedFields = c.fields.map((f) => f.field);
+    const onlyComment = changedFields.length === 1 && changedFields[0] === 'comment';
+    const comment = field(c.fields, 'comment');
+    if (onlyComment && comment !== undefined) {
+        b.emit(`functionComment:${c.path}`, [], PHASE.FUNCTION_ALTER, commentStatement('function', c.path, `FUNCTION ${qualify(schema, name)}(${args})`, comment));
+        return;
+    }
+    b.markUnsupported('function', c.path, 'modified', 'the diff carries only the fields that changed, not the function\'s full definition — CREATE OR REPLACE FUNCTION needs the complete signature restated even for the fields that did not change, and that is not recoverable from a diff alone. Not attempted (a comment-only change is the sole exception).');
+}
+// --- Constraints (primary_key / unique_constraint / check_constraint) ------
+function handleGenericConstraint(b, c, dropPhase, addPhase) {
+    const { schema, table, leaf: name } = splitTablePath(c.path);
+    const tableQualified = qualify(schema, table);
+    const tableCreateId = `table:${schema}.${table}`;
+    const tableDropId = `tableDrop:${schema}.${table}`;
+    // A PRIMARY KEY/UNIQUE constraint creates a backing index of the same name,
+    // which lives in the schema-wide pg_class namespace; a CHECK creates nothing.
+    const claimsIndexName = c.objectType === 'primary_key' || c.objectType === 'unique_constraint';
+    if (c.kind === 'added') {
+        const obj = c.object;
+        const columns = extractColumnList(obj.definition);
+        if (claimsIndexName)
+            b.claimName(schema, name, { id: `constraint:${c.path}`, objectType: c.objectType, path: c.path, changeKind: 'added' });
+        const deps = [b.has(tableCreateId) ? tableCreateId : undefined, ...columns.map((col) => `column:${schema}.${table}.${col}`)].filter((x) => x !== undefined);
+        b.emit(`constraint:${c.path}`, deps, addPhase, {
+            sql: `ALTER TABLE ${tableQualified} ADD CONSTRAINT ${quoteIdent(name)} ${obj.definition};`,
+            objectType: c.objectType,
+            path: c.path,
+            changeKind: 'added',
+            risk: 'moderate',
+            riskNote: c.objectType === 'check_constraint'
+                ? 'validates every existing row against the check expression (a full table scan) and takes a lock for the duration. For a large table, add it as NOT VALID and run VALIDATE CONSTRAINT separately instead — this statement does not do that split.'
+                : 'builds a unique index to enforce the constraint, holding an ACCESS EXCLUSIVE lock on the table for the whole build — reads are blocked as well as writes (unlike a plain CREATE INDEX). For a large table, CREATE UNIQUE INDEX CONCURRENTLY followed by ADD CONSTRAINT ... UNIQUE USING INDEX is the safer two-step alternative — this statement does not do that split.',
+            reversible: true,
+            down: `ALTER TABLE ${tableQualified} DROP CONSTRAINT ${quoteIdent(name)};`,
+        });
+        return;
+    }
+    if (c.kind === 'removed') {
+        const obj = c.object;
+        if (claimsIndexName)
+            b.releaseName(schema, name, `constraintDrop:${c.path}`);
+        b.emit(`constraintDrop:${c.path}`, [], dropPhase, {
+            sql: `ALTER TABLE ${tableQualified} DROP CONSTRAINT ${quoteIdent(name)};`,
+            objectType: c.objectType,
+            path: c.path,
+            changeKind: 'removed',
+            risk: c.objectType === 'primary_key' ? 'high' : 'moderate',
+            riskNote: c.objectType === 'primary_key'
+                ? 'drops the primary key and its backing index; any foreign key elsewhere that references it must already be dropped earlier in this plan, or this fails.'
+                : 'removes the enforcement (and, for a unique constraint, its backing index); existing rows are untouched.',
+            reversible: true,
+            down: `ALTER TABLE ${tableQualified} ADD CONSTRAINT ${quoteIdent(name)} ${obj.definition};`,
+        });
+        if (b.has(tableDropId))
+            b.addExtraDep(tableDropId, `constraintDrop:${c.path}`);
+        return;
+    }
+    const def = field(c.fields, 'definition');
+    if (def === undefined)
+        return;
+    const dropId = `constraintDropM:${c.path}`;
+    const addId = `constraintAddM:${c.path}`;
+    b.emit(dropId, [], dropPhase, {
+        sql: `ALTER TABLE ${tableQualified} DROP CONSTRAINT ${quoteIdent(name)};`,
+        objectType: c.objectType,
+        path: c.path,
+        changeKind: 'modified',
+        risk: 'moderate',
+        riskNote: 'a constraint cannot be altered in place — this drops the old definition immediately before the next statement adds the new one.',
+        reversible: true,
+        down: `ALTER TABLE ${tableQualified} ADD CONSTRAINT ${quoteIdent(name)} ${String(def.before)};`,
+    });
+    b.emit(addId, [dropId], addPhase, {
+        sql: `ALTER TABLE ${tableQualified} ADD CONSTRAINT ${quoteIdent(name)} ${String(def.after)};`,
+        objectType: c.objectType,
+        path: c.path,
+        changeKind: 'modified',
+        risk: 'moderate',
+        riskNote: 'rebuilds the constraint (and, for a unique/primary-key constraint, its backing index) — same lock/scan cost as adding it fresh.',
+        reversible: true,
+        down: `ALTER TABLE ${tableQualified} DROP CONSTRAINT ${quoteIdent(name)};`,
+    });
+}
+/** Best-effort extraction of a simple `(col1, col2)` column list from a PRIMARY KEY/UNIQUE constraint definition. Returns `[]` for anything else rather than guessing — notably a CHECK, whose parenthesised *expression* would otherwise yield pseudo-columns like `qty > 0` that match no real column id. */
+export function extractColumnList(definition) {
+    // `UNIQUE NULLS NOT DISTINCT (...)` (PG15+) puts words between the keyword
+    // and the list, so allow them — but nothing that opens a paren of its own.
+    if (!/^\s*(PRIMARY\s+KEY|UNIQUE)[^(]*\(/i.test(definition))
+        return [];
+    const m = /\(([^()]*)\)/.exec(definition);
+    if (m?.[1] === undefined)
+        return [];
+    return m[1]
+        .split(',')
+        .map((s) => s.trim().replace(/^"(.*)"$/, '$1'))
+        .filter((s) => s.length > 0 && !s.includes('('));
+}
+// --- Foreign keys -----------------------------------------------------------
+function handleForeignKey(b, c) {
+    const { schema, table, leaf: name } = splitTablePath(c.path);
+    const tableQualified = qualify(schema, table);
+    const tableCreateId = `table:${schema}.${table}`;
+    const tableDropId = `tableDrop:${schema}.${table}`;
+    if (c.kind === 'added') {
+        const fk = c.object;
+        const refTableCreateId = `table:${fk.refSchema}.${fk.refTable}`;
+        const deps = [b.has(tableCreateId) ? tableCreateId : undefined, b.has(refTableCreateId) ? refTableCreateId : undefined].filter((x) => x !== undefined);
+        b.emit(`fk:${c.path}`, deps, PHASE.FK_ADD, {
+            sql: `ALTER TABLE ${tableQualified} ADD CONSTRAINT ${quoteIdent(name)} ${fk.definition};`,
+            objectType: 'foreign_key',
+            path: c.path,
+            changeKind: 'added',
+            risk: 'moderate',
+            riskNote: 'validates every existing row in this table against the referenced table (a full scan of this table, plus a lock on both while it runs). For a large table, add it as NOT VALID and run VALIDATE CONSTRAINT separately — this statement does not do that split.',
+            reversible: true,
+            down: `ALTER TABLE ${tableQualified} DROP CONSTRAINT ${quoteIdent(name)};`,
+        });
+        return;
+    }
+    if (c.kind === 'removed') {
+        const fk = c.object;
+        const dropId = `fkDrop:${c.path}`;
+        b.emit(dropId, [], PHASE.FK_DROP, {
+            sql: `ALTER TABLE ${tableQualified} DROP CONSTRAINT ${quoteIdent(name)};`,
+            objectType: 'foreign_key',
+            path: c.path,
+            changeKind: 'removed',
+            risk: 'low',
+            riskNote: 'removes referential enforcement only — no data on either table is touched.',
+            reversible: true,
+            down: `ALTER TABLE ${tableQualified} ADD CONSTRAINT ${quoteIdent(name)} ${fk.definition};`,
+        });
+        const refDropId = `tableDrop:${fk.refSchema}.${fk.refTable}`;
+        if (b.has(refDropId))
+            b.addExtraDep(refDropId, dropId);
+        if (b.has(tableDropId))
+            b.addExtraDep(tableDropId, dropId);
+        return;
+    }
+    const def = field(c.fields, 'definition');
+    if (def === undefined)
+        return;
+    // refSchema/refTable changes always accompany a `definition` change (the
+    // rendered clause embeds the reference), so `definition` alone is enough
+    // to rebuild both the drop's down-statement and the add's new clause.
+    const dropId = `fkDropM:${c.path}`;
+    const addId = `fkAddM:${c.path}`;
+    b.emit(dropId, [], PHASE.FK_DROP, {
+        sql: `ALTER TABLE ${tableQualified} DROP CONSTRAINT ${quoteIdent(name)};`,
+        objectType: 'foreign_key',
+        path: c.path,
+        changeKind: 'modified',
+        risk: 'moderate',
+        riskNote: 'a foreign key cannot be altered in place — this drops the old definition immediately before the next statement adds the new one.',
+        reversible: true,
+        down: `ALTER TABLE ${tableQualified} ADD CONSTRAINT ${quoteIdent(name)} ${String(def.before)};`,
+    });
+    b.emit(addId, [dropId], PHASE.FK_ADD, {
+        sql: `ALTER TABLE ${tableQualified} ADD CONSTRAINT ${quoteIdent(name)} ${String(def.after)};`,
+        objectType: 'foreign_key',
+        path: c.path,
+        changeKind: 'modified',
+        risk: 'moderate',
+        riskNote: 'revalidates every existing row against the (possibly new) referenced table — same cost as adding it fresh.',
+        reversible: true,
+        down: `ALTER TABLE ${tableQualified} DROP CONSTRAINT ${quoteIdent(name)};`,
+    });
+}
+// --- Indexes -----------------------------------------------------------------
+function withConcurrently(createStmt, concurrently) {
+    if (!concurrently)
+        return createStmt;
+    return createStmt.replace(/^CREATE\s+(UNIQUE\s+)?INDEX\s+/i, (m) => `${m.trimEnd()} CONCURRENTLY `);
+}
+function handleIndex(b, c, opts) {
+    const { schema, table, leaf: name } = splitTablePath(c.path);
+    const indexQualified = qualify(schema, name);
+    const tableCreateId = `table:${schema}.${table}`;
+    const tableDropId = `tableDrop:${schema}.${table}`;
+    // CONCURRENTLY is only meaningful (and only necessary) once the table
+    // already exists with other traffic on it — a table this same plan just
+    // created has no concurrent readers/writers to protect yet, and
+    // CONCURRENTLY cannot run in the same transaction as the CREATE TABLE that
+    // precedes it anyway.
+    const tableIsNew = b.has(tableCreateId);
+    const concurrently = opts.concurrentIndexes && !tableIsNew;
+    if (c.kind === 'added') {
+        const idx = c.object;
+        const cols = idx.columns.filter((col) => !col.includes('('));
+        const deps = [tableIsNew ? tableCreateId : undefined, ...cols.map((col) => `column:${schema}.${table}.${col}`)].filter((x) => x !== undefined);
+        b.claimName(schema, name, { id: `index:${c.path}`, objectType: 'index', path: c.path, changeKind: 'added' });
+        b.emit(`index:${c.path}`, deps, PHASE.INDEX_CREATE, {
+            sql: `${withConcurrently(idx.definition, concurrently)};`,
+            objectType: 'index',
+            path: c.path,
+            changeKind: 'added',
+            risk: concurrently ? 'low' : 'moderate',
+            riskNote: concurrently
+                ? 'CONCURRENTLY avoids blocking reads or writes, at the cost of a slower build and two full table scans; if it fails partway it leaves an INVALID index behind that must be dropped and retried — check for that before assuming success.'
+                : 'takes a SHARE lock for the duration, which blocks writes to the table (reads are unaffected) until the index finishes building.',
+            reversible: true,
+            down: `DROP INDEX ${concurrently ? 'CONCURRENTLY ' : ''}${indexQualified};`,
+        });
+        return;
+    }
+    if (c.kind === 'removed') {
+        const idx = c.object;
+        const dropId = `indexDrop:${c.path}`;
+        b.releaseName(schema, name, dropId);
+        b.emit(dropId, [], PHASE.INDEX_DROP, {
+            sql: `DROP INDEX ${concurrently ? 'CONCURRENTLY ' : ''}${indexQualified};`,
+            objectType: 'index',
+            path: c.path,
+            changeKind: 'removed',
+            risk: 'low',
+            riskNote: 'removes an access path only — no data loss. Query plans that relied on it may get slower.',
+            reversible: true,
+            down: `${idx.definition};`,
+        });
+        if (b.has(tableDropId))
+            b.addExtraDep(tableDropId, dropId);
+        return;
+    }
+    const def = field(c.fields, 'definition');
+    if (def === undefined)
+        return;
+    const dropId = `indexDropM:${c.path}`;
+    const addId = `indexAddM:${c.path}`;
+    b.emit(dropId, [], PHASE.INDEX_DROP, {
+        sql: `DROP INDEX ${concurrently ? 'CONCURRENTLY ' : ''}${indexQualified};`,
+        objectType: 'index',
+        path: c.path,
+        changeKind: 'modified',
+        risk: 'moderate',
+        riskNote: 'an index cannot be altered structurally — this drops it immediately before the next statement rebuilds it. The table has no index covering this access path in between; for a large or hot table, build the new index under a temporary name with CREATE INDEX CONCURRENTLY and ALTER INDEX ... RENAME TO instead of this drop-then-create pair.',
+        reversible: true,
+        down: `${String(def.before)};`,
+    });
+    b.emit(addId, [dropId], PHASE.INDEX_CREATE, {
+        sql: `${withConcurrently(String(def.after), concurrently)};`,
+        objectType: 'index',
+        path: c.path,
+        changeKind: 'modified',
+        risk: concurrently ? 'low' : 'moderate',
+        riskNote: concurrently
+            ? 'CONCURRENTLY avoids blocking reads or writes while rebuilding; check for an INVALID index afterward if it failed partway.'
+            : 'takes a SHARE lock for the duration, blocking writes until the rebuild finishes.',
+        reversible: true,
+        down: `DROP INDEX ${concurrently ? 'CONCURRENTLY ' : ''}${indexQualified};`,
+    });
+}
+// --- Triggers ------------------------------------------------------------
+function handleTrigger(b, c) {
+    const { schema, table, leaf: name } = splitTablePath(c.path);
+    const tableQualified = qualify(schema, table);
+    const tableCreateId = `table:${schema}.${table}`;
+    const tableDropId = `tableDrop:${schema}.${table}`;
+    if (c.kind === 'added') {
+        const t = c.object;
+        b.emit(`trigger:${c.path}`, [b.has(tableCreateId) ? tableCreateId : undefined].filter((x) => x !== undefined), PHASE.TRIGGER_CREATE, {
+            sql: `${t.definition};`,
+            objectType: 'trigger',
+            path: c.path,
+            changeKind: 'added',
+            risk: 'moderate',
+            riskNote: 'changes behaviour for every future write that matches it — review the trigger function\'s body; existing rows are untouched.',
+            reversible: true,
+            down: `DROP TRIGGER ${quoteIdent(name)} ON ${tableQualified};`,
+        });
+        return;
+    }
+    if (c.kind === 'removed') {
+        const t = c.object;
+        const dropId = `triggerDrop:${c.path}`;
+        b.emit(dropId, [], PHASE.TRIGGER_DROP, {
+            sql: `DROP TRIGGER ${quoteIdent(name)} ON ${tableQualified};`,
+            objectType: 'trigger',
+            path: c.path,
+            changeKind: 'removed',
+            risk: 'moderate',
+            riskNote: 'silently changes application behaviour — anything that relied on this trigger firing (e.g. an updated_at maintenance trigger) stops working. Existing data is untouched.',
+            reversible: true,
+            down: `${t.definition};`,
+        });
+        if (b.has(tableDropId))
+            b.addExtraDep(tableDropId, dropId);
+        return;
+    }
+    const def = field(c.fields, 'definition');
+    if (def === undefined)
+        return;
+    const dropId = `triggerDropM:${c.path}`;
+    const addId = `triggerAddM:${c.path}`;
+    b.emit(dropId, [], PHASE.TRIGGER_DROP, {
+        sql: `DROP TRIGGER ${quoteIdent(name)} ON ${tableQualified};`,
+        objectType: 'trigger',
+        path: c.path,
+        changeKind: 'modified',
+        risk: 'moderate',
+        riskNote: 'a trigger\'s timing/events/function cannot be altered in place — this drops it immediately before the next statement recreates it. Writes between the two statements do not fire this trigger at all.',
+        reversible: true,
+        down: `${String(def.before)};`,
+    });
+    b.emit(addId, [dropId], PHASE.TRIGGER_CREATE, {
+        sql: `${String(def.after)};`,
+        objectType: 'trigger',
+        path: c.path,
+        changeKind: 'modified',
+        risk: 'moderate',
+        riskNote: 'review the new trigger function\'s body before applying.',
+        reversible: true,
+        down: `DROP TRIGGER ${quoteIdent(name)} ON ${tableQualified};`,
+    });
+}
+// --- Policies (added/removed only — see the module doc for `modified`) ---
+function policyClause(p, schema, table) {
+    const parts = [`CREATE POLICY ${quoteIdent(p.name)} ON ${qualify(schema, table)}`];
+    parts.push(`AS ${p.permissive ? 'PERMISSIVE' : 'RESTRICTIVE'}`);
+    parts.push(`FOR ${p.command}`);
+    parts.push(`TO ${p.roles.length === 0 ? 'PUBLIC' : p.roles.map((r) => quoteIdent(r)).join(', ')}`);
+    if (p.using !== null)
+        parts.push(`USING (${p.using})`);
+    if (p.withCheck !== null)
+        parts.push(`WITH CHECK (${p.withCheck})`);
+    return `${parts.join(' ')};`;
+}
+function handlePolicy(b, c) {
+    const { schema, table, leaf: name } = splitTablePath(c.path);
+    const tableCreateId = `table:${schema}.${table}`;
+    const tableDropId = `tableDrop:${schema}.${table}`;
+    if (c.kind === 'added') {
+        const p = c.object;
+        b.emit(`policy:${c.path}`, [b.has(tableCreateId) ? tableCreateId : undefined].filter((x) => x !== undefined), PHASE.POLICY_CREATE, {
+            sql: policyClause(p, schema, table),
+            objectType: 'policy',
+            path: c.path,
+            changeKind: 'added',
+            risk: 'moderate',
+            riskNote: 'row-level security policies gate which rows a role can see or write — a wrong USING/WITH CHECK expression can silently hide or expose rows. Test as the target roles before relying on it.',
+            reversible: true,
+            down: `DROP POLICY ${quoteIdent(name)} ON ${qualify(schema, table)};`,
+        });
+        return;
+    }
+    if (c.kind === 'removed') {
+        const p = c.object;
+        const dropId = `policyDrop:${c.path}`;
+        b.emit(dropId, [], PHASE.POLICY_DROP, {
+            sql: `DROP POLICY ${quoteIdent(name)} ON ${qualify(schema, table)};`,
+            objectType: 'policy',
+            path: c.path,
+            changeKind: 'removed',
+            risk: 'moderate',
+            riskNote: 'if row-level security is (or stays) enabled and forced on this table, removing this policy can immediately change which rows matching roles can see or write.',
+            reversible: true,
+            down: policyClause(p, schema, table),
+        });
+        if (b.has(tableDropId))
+            b.addExtraDep(tableDropId, dropId);
+        return;
+    }
+    b.markUnsupported('policy', c.path, 'modified', 'the diff carries only the fields that changed (e.g. just USING), not the policy\'s full definition (command, roles, permissive, WITH CHECK) — CREATE POLICY needs the whole statement restated even for fields that did not change, and that is not recoverable from a diff alone. Not attempted; drop and recreate the policy manually.');
+}
+// --- Views / materialized views -------------------------------------------
+/** `pg_get_viewdef` — what `capture.ts` stores verbatim — already ends in `;`. Every site here appends its own terminator, so strip the captured one rather than emit `…;;`, which is two statements to any applier that splits on `;`. */
+function viewBody(definition) {
+    return definition.replace(/;\s*$/, '');
+}
+function handleView(b, c, isMaterialized) {
+    const kw = isMaterialized ? 'MATERIALIZED VIEW' : 'VIEW';
+    const { schema, rest: name } = splitFirstDot(c.path);
+    const viewQualified = qualify(schema, name);
+    const createId = `${isMaterialized ? 'matview' : 'view'}:${c.path}`;
+    if (c.kind === 'added') {
+        const v = c.object;
+        if (v.definition === null) {
+            b.markUnsupported(isMaterialized ? 'materialized_view' : 'view', c.path, 'added', 'no SELECT definition was captured for this view (an unusual state) — nothing to recreate from.');
+            return;
+        }
+        b.claimName(schema, name, { id: createId, objectType: isMaterialized ? 'materialized_view' : 'view', path: c.path, changeKind: 'added' });
+        b.emit(createId, [`schema:${schema}`], PHASE.VIEW_CREATE, {
+            sql: `CREATE ${kw} ${viewQualified} AS ${viewBody(v.definition)};`,
+            objectType: isMaterialized ? 'materialized_view' : 'view',
+            path: c.path,
+            changeKind: 'added',
+            risk: isMaterialized ? 'moderate' : 'safe',
+            riskNote: isMaterialized
+                ? 'creates the view but does not populate it — it starts unscannable until the first REFRESH MATERIALIZED VIEW.'
+                : 'a view stores no data of its own; this only fails if the underlying query is invalid or references something not yet created.',
+            reversible: true,
+            down: `DROP ${kw} ${viewQualified};`,
+        });
+        // Only a materialized view can carry indexes; only INSTEAD OF triggers
+        // land on a plain view — both empty lists for the common case, but the
+        // object already carries them (see `expandSchemaChanges`'s header doc on
+        // why `added` gets the full nested object rather than separate entries).
+        for (const idx of v.indexes) {
+            b.claimName(schema, idx.name, { id: `index:${c.path}.${idx.name}`, objectType: 'index', path: `${c.path}.${idx.name}`, changeKind: 'added' });
+            b.emit(`index:${c.path}.${idx.name}`, [createId], PHASE.INDEX_CREATE, {
+                sql: `${idx.definition};`,
+                objectType: 'index',
+                path: `${c.path}.${idx.name}`,
+                changeKind: 'added',
+                risk: 'moderate',
+                riskNote: 'built on a materialized view that has no rows yet (empty until REFRESH MATERIALIZED VIEW) — cheap now, but the view must be refreshed before this index means anything.',
+                reversible: true,
+                down: `DROP INDEX ${qualify(schema, idx.name)};`,
+            });
+        }
+        for (const trg of v.triggers) {
+            b.emit(`trigger:${c.path}.${trg.name}`, [createId], PHASE.TRIGGER_CREATE, {
+                sql: `${trg.definition};`,
+                objectType: 'trigger',
+                path: `${c.path}.${trg.name}`,
+                changeKind: 'added',
+                risk: 'moderate',
+                riskNote: 'an INSTEAD OF trigger changes what writes against this view actually do — review its function\'s body.',
+                reversible: true,
+                down: `DROP TRIGGER ${quoteIdent(trg.name)} ON ${viewQualified};`,
+            });
+        }
+        return;
+    }
+    if (c.kind === 'removed') {
+        const v = c.object;
+        const dropId = `${isMaterialized ? 'matviewDrop' : 'viewDrop'}:${c.path}`;
+        b.releaseName(schema, name, dropId);
+        for (const idx of v.indexes ?? [])
+            b.releaseName(schema, idx.name, dropId);
+        b.emit(dropId, [], PHASE.VIEW_DROP, {
+            sql: `DROP ${kw} ${viewQualified};`,
+            objectType: isMaterialized ? 'materialized_view' : 'view',
+            path: c.path,
+            changeKind: 'removed',
+            risk: isMaterialized ? 'high' : 'low',
+            riskNote: isMaterialized
+                ? 'discards the materialized (stored) result rows permanently, in addition to the view definition.'
+                : 'a view holds no data of its own — this only removes the saved query.',
+            reversible: v.definition !== null,
+            ...(v.definition === null
+                ? { downNote: 'no SELECT definition was captured to recreate it from.' }
+                : {
+                    down: `CREATE ${kw} ${viewQualified} AS ${viewBody(v.definition)};`,
+                    ...(isMaterialized ? { downNote: 'restores the definition only — the recreated materialized view is empty until REFRESH MATERIALIZED VIEW is run.' } : {}),
+                }),
+        });
+        b.linkToSchemaDrop(schema, dropId);
+        return;
+    }
+    const definition = field(c.fields, 'definition');
+    if (definition !== undefined) {
+        if (isMaterialized) {
+            b.markUnsupported('materialized_view', c.path, 'modified', 'changing a materialized view\'s definition needs DROP + CREATE MATERIALIZED VIEW, which discards its stored rows and can fail against anything that depends on it — not attempted automatically. Drop and recreate it manually, then REFRESH it.');
+        }
+        else {
+            b.emit(`viewAlter:${c.path}`, [], PHASE.VIEW_ALTER, {
+                sql: `CREATE OR REPLACE VIEW ${viewQualified} AS ${viewBody(String(definition.after))};`,
+                objectType: 'view',
+                path: c.path,
+                changeKind: 'modified',
+                risk: 'moderate',
+                riskNote: 'PostgreSQL only allows CREATE OR REPLACE VIEW to add new output columns at the end, or change an expression\'s text without changing its name/type — removing, reordering or retyping an existing output column fails outright and needs DROP + CREATE instead.',
+                reversible: true,
+                down: `CREATE OR REPLACE VIEW ${viewQualified} AS ${viewBody(String(definition.before))};`,
+            });
+        }
+    }
+    const owner = field(c.fields, 'owner');
+    if (owner !== undefined) {
+        b.emit(`viewOwner:${c.path}`, [], PHASE.VIEW_ALTER, {
+            sql: `ALTER ${kw} ${viewQualified} OWNER TO ${quoteIdent(String(owner.after))};`,
+            objectType: isMaterialized ? 'materialized_view' : 'view',
+            path: c.path,
+            changeKind: 'modified',
+            risk: 'low',
+            riskNote: 'metadata-only ownership change.',
+            reversible: true,
+            down: `ALTER ${kw} ${viewQualified} OWNER TO ${quoteIdent(String(owner.before))};`,
+        });
+    }
+    const comment = field(c.fields, 'comment');
+    if (comment !== undefined) {
+        b.emit(`viewComment:${c.path}`, [], PHASE.VIEW_ALTER, commentStatement(isMaterialized ? 'materialized_view' : 'view', c.path, `${kw} ${viewQualified}`, comment));
+    }
+}
+// --- Columns ------------------------------------------------------------
+function handleColumn(b, c) {
+    const { schema, table, leaf: name } = splitTablePath(c.path);
+    const tableQualified = qualify(schema, table);
+    const tableCreateId = `table:${schema}.${table}`;
+    const tableDropId = `tableDrop:${schema}.${table}`;
+    if (c.kind === 'added') {
+        const col = c.object;
+        const volatile = col.default !== null && VOLATILE_DEFAULT.test(col.default);
+        const rewrite = volatile || col.generated === 'stored';
+        b.emit(`column:${c.path}`, [b.has(tableCreateId) ? tableCreateId : undefined].filter((x) => x !== undefined), PHASE.COLUMN_ADD, {
+            sql: `ALTER TABLE ${tableQualified} ADD COLUMN ${columnDefClause(col)};`,
+            objectType: 'column',
+            path: c.path,
+            changeKind: 'added',
+            risk: !col.nullable && col.default === null ? 'high' : rewrite ? 'moderate' : 'low',
+            riskNote: !col.nullable && col.default === null
+                ? 'NOT NULL with no default fails outright on any table that already has rows — this only works on an empty table, or needs a default added first.'
+                : rewrite
+                    ? `${col.generated === 'stored' ? 'a STORED generated column computes its expression for every existing row' : 'a volatile default (e.g. now()/random()/nextval()) is evaluated per row rather than once'} — this rewrites the entire table, taking an ACCESS EXCLUSIVE lock for the duration, even on PostgreSQL 11+.`
+                    : col.default === null
+                        ? 'no default and no generation expression, so every existing row simply reads as NULL — a catalog-only change with no table rewrite.'
+                        : 'a constant default is stored in the catalog and read back for existing rows rather than written to them (PostgreSQL 11+ fast path) — no table rewrite.',
+            reversible: true,
+            down: `ALTER TABLE ${tableQualified} DROP COLUMN ${quoteIdent(name)};`,
+        });
+        return;
+    }
+    if (c.kind === 'removed') {
+        const dropId = `columnDrop:${c.path}`;
+        b.emit(dropId, [], PHASE.COLUMN_DROP, {
+            sql: `ALTER TABLE ${tableQualified} DROP COLUMN ${quoteIdent(name)};`,
+            objectType: 'column',
+            path: c.path,
+            changeKind: 'removed',
+            risk: 'high',
+            riskNote: 'discards every existing value in this column, for every row, irreversibly. Also drops any default, NOT NULL, and (with a NOTICE) any index or constraint still referencing only this column that was not already dropped earlier in this plan.',
+            reversible: false,
+            downNote: 'cannot restore: the column\'s data is gone once this runs. Recreating an empty column of the same name and type is not a real undo and is deliberately not emitted.',
+        });
+        if (b.has(tableDropId))
+            b.addExtraDep(tableDropId, dropId);
+        return;
+    }
+    const type = field(c.fields, 'type');
+    const collation = field(c.fields, 'collation');
+    const nullable = field(c.fields, 'nullable');
+    const dflt = field(c.fields, 'default');
+    const identity = field(c.fields, 'identity');
+    const generated = field(c.fields, 'generated');
+    const comment = field(c.fields, 'comment');
+    if (type !== undefined) {
+        const collationClause = collation !== undefined && collation.after !== null ? ` COLLATE ${quoteIdent(String(collation.after))}` : '';
+        const usingClause = `USING ${quoteIdent(name)}::${String(type.after)}`;
+        b.emit(`columnType:${c.path}`, [], PHASE.COLUMN_ALTER, {
+            sql: `ALTER TABLE ${tableQualified} ALTER COLUMN ${quoteIdent(name)} TYPE ${String(type.after)}${collationClause} ${usingClause};`,
+            objectType: 'column',
+            path: c.path,
+            changeKind: 'modified',
+            risk: 'high',
+            riskNote: 'takes an ACCESS EXCLUSIVE lock and rewrites the entire table (the table is unavailable for reads and writes for the duration). The USING clause is a plain cast — review it against the real data first; some conversions fail outright or silently truncate/round.',
+            reversible: true,
+            down: `ALTER TABLE ${tableQualified} ALTER COLUMN ${quoteIdent(name)} TYPE ${String(type.before)} USING ${quoteIdent(name)}::${String(type.before)};`,
+            downNote: 'the reverse cast has the exact same rewrite/lock cost, and the same risk of losing precision if the forward cast already did.',
+        });
+    }
+    else if (collation !== undefined) {
+        b.markUnsupported('column', c.path, 'modified', 'collation changed with no accompanying type change — ALTER COLUMN ... TYPE <type> COLLATE <collation> needs the column\'s current type restated, which is not present in the diff when only collation differs. Not attempted.');
+    }
+    if (nullable !== undefined) {
+        if (nullable.after === true) {
+            b.emit(`columnNullable:${c.path}`, [], PHASE.COLUMN_ALTER, {
+                sql: `ALTER TABLE ${tableQualified} ALTER COLUMN ${quoteIdent(name)} DROP NOT NULL;`,
+                objectType: 'column',
+                path: c.path,
+                changeKind: 'modified',
+                risk: 'safe',
+                riskNote: 'metadata-only — no scan, no lock beyond the brief catalog update.',
+                reversible: true,
+                down: `ALTER TABLE ${tableQualified} ALTER COLUMN ${quoteIdent(name)} SET NOT NULL;`,
+                downNote: 'the reverse direction re-adds NOT NULL and carries the same precondition as adding it fresh: it fails if any row already has NULL here.',
+            });
+        }
+        else {
+            b.emit(`columnNullable:${c.path}`, [], PHASE.COLUMN_ALTER, {
+                sql: `ALTER TABLE ${tableQualified} ALTER COLUMN ${quoteIdent(name)} SET NOT NULL;`,
+                objectType: 'column',
+                path: c.path,
+                changeKind: 'modified',
+                risk: 'moderate',
+                riskNote: 'scans the whole table to verify no existing row is NULL here, and fails outright if one is — run the precondition query first.',
+                precondition: `SELECT count(*) FROM ${tableQualified} WHERE ${quoteIdent(name)} IS NULL; -- expect 0`,
+                reversible: true,
+                down: `ALTER TABLE ${tableQualified} ALTER COLUMN ${quoteIdent(name)} DROP NOT NULL;`,
+            });
+        }
+    }
+    if (dflt !== undefined) {
+        const after = dflt.after === null ? 'DROP DEFAULT' : `SET DEFAULT ${String(dflt.after)}`;
+        const before = dflt.before === null ? 'DROP DEFAULT' : `SET DEFAULT ${String(dflt.before)}`;
+        b.emit(`columnDefault:${c.path}`, [], PHASE.COLUMN_ALTER, {
+            sql: `ALTER TABLE ${tableQualified} ALTER COLUMN ${quoteIdent(name)} ${after};`,
+            objectType: 'column',
+            path: c.path,
+            changeKind: 'modified',
+            risk: 'safe',
+            riskNote: 'metadata-only — applies only to rows written after this runs; existing rows keep whatever value they already have.',
+            reversible: true,
+            down: `ALTER TABLE ${tableQualified} ALTER COLUMN ${quoteIdent(name)} ${before};`,
+        });
+    }
+    if (identity !== undefined) {
+        const toClause = (v) => {
+            if (v === null)
+                return `ALTER TABLE ${tableQualified} ALTER COLUMN ${quoteIdent(name)} DROP IDENTITY IF EXISTS;`;
+            const kind = v === 'always' ? 'ALWAYS' : 'BY DEFAULT';
+            return identity.before === null
+                ? `ALTER TABLE ${tableQualified} ALTER COLUMN ${quoteIdent(name)} ADD GENERATED ${kind} AS IDENTITY;`
+                : `ALTER TABLE ${tableQualified} ALTER COLUMN ${quoteIdent(name)} SET GENERATED ${kind};`;
+        };
+        b.emit(`columnIdentity:${c.path}`, [], PHASE.COLUMN_ALTER, {
+            sql: toClause(identity.after),
+            objectType: 'column',
+            path: c.path,
+            changeKind: 'modified',
+            risk: 'moderate',
+            riskNote: identity.before === null
+                ? 'ADD GENERATED ... AS IDENTITY fails if the column already has an ordinary default — that default must be dropped first.'
+                : 'metadata-only toggle between ALWAYS and BY DEFAULT (or dropping identity outright).',
+            reversible: true,
+            down: toClause(identity.before),
+        });
+    }
+    if (generated !== undefined) {
+        if (generated.before === null && generated.after === 'stored') {
+            b.markUnsupported('column', c.path, 'modified', 'PostgreSQL has no ALTER COLUMN ... ADD GENERATED for a value-generation expression (only for identity) — adding one to an existing column needs DROP + ADD COLUMN GENERATED ..., which discards the column\'s current data. Not attempted automatically.');
+        }
+        else if (generated.before === 'stored' && generated.after === null) {
+            b.emit(`columnGenerated:${c.path}`, [], PHASE.COLUMN_ALTER, {
+                sql: `ALTER TABLE ${tableQualified} ALTER COLUMN ${quoteIdent(name)} DROP EXPRESSION;`,
+                objectType: 'column',
+                path: c.path,
+                changeKind: 'modified',
+                risk: 'moderate',
+                riskNote: 'the column keeps whatever value it last computed as an ordinary stored value; future writes must now supply it explicitly (or it becomes NULL/default) since it is no longer computed automatically.',
+                reversible: false,
+                downNote: 'cannot restore: the original generation expression is not recoverable without recreating the column, and even then would need to recompute over current (possibly since-changed) data.',
+            });
+        }
+    }
+    if (comment !== undefined) {
+        b.emit(`columnComment:${c.path}`, [], PHASE.COLUMN_ALTER, commentStatement('column', c.path, `COLUMN ${tableQualified}.${quoteIdent(name)}`, comment));
+    }
+}
+// --- Tables ---------------------------------------------------------------
+function handleTable(b, c) {
+    const { schema, rest: name } = splitFirstDot(c.path);
+    const tableQualified = qualify(schema, name);
+    if (c.kind === 'added') {
+        const t = c.object;
+        if (t.partitionBound !== null) {
+            b.markUnsupported('table', c.path, 'added', 'this table is a declarative partition (PARTITION OF) — that CREATE TABLE form inherits its columns from the parent rather than declaring them, a materially different statement this generator does not build. Create it manually with CREATE TABLE ... PARTITION OF ... FOR VALUES ...');
+            return;
+        }
+        if (t.kind !== 'table') {
+            b.markUnsupported('table', c.path, 'added', `relation kind "${t.kind}" (partitioned/foreign table) needs its own CREATE TABLE form (PARTITION BY / FOREIGN TABLE ... SERVER ...) that this generator does not build. Not attempted.`);
+            return;
+        }
+        const columnClauses = t.columns.map((col) => columnDefClause(col));
+        if (t.primaryKey !== null)
+            columnClauses.push(`CONSTRAINT ${quoteIdent(t.primaryKey.name)} ${t.primaryKey.definition}`);
+        for (const uq of t.uniqueConstraints)
+            columnClauses.push(`CONSTRAINT ${quoteIdent(uq.name)} ${uq.definition}`);
+        for (const ck of t.checkConstraints)
+            columnClauses.push(`CONSTRAINT ${quoteIdent(ck.name)} ${ck.definition}`);
+        const inheritsClause = t.inherits.length === 0 ? '' : ` INHERITS (${t.inherits.map(quoteQualifiedName).join(', ')})`;
+        const tableId = `table:${c.path}`;
+        b.emit(tableId, [`schema:${schema}`], PHASE.TABLE_CREATE, {
+            sql: `CREATE TABLE ${tableQualified} (\n  ${columnClauses.join(',\n  ')}\n)${inheritsClause};`,
+            objectType: 'table',
+            path: c.path,
+            changeKind: 'added',
+            risk: 'safe',
+            riskNote: 'creates an empty table — no existing data anywhere is touched. Foreign keys owned by this table are scheduled as separate statements after every table in this plan exists, deliberately, so two new tables with mutual foreign keys never need each other mid-creation.',
+            reversible: true,
+            down: `DROP TABLE ${tableQualified};`,
+        });
+        // Everything CREATE TABLE itself puts into the schema's pg_class namespace
+        // — the table, plus the index behind each PRIMARY KEY/UNIQUE constraint
+        // declared inline. See `Builder.resolveNameCollisions`.
+        const tableClaim = { id: tableId, objectType: 'table', path: c.path, changeKind: 'added' };
+        b.claimName(schema, name, tableClaim);
+        if (t.primaryKey !== null)
+            b.claimName(schema, t.primaryKey.name, tableClaim);
+        for (const uq of t.uniqueConstraints)
+            b.claimName(schema, uq.name, tableClaim);
+        for (const idx of t.indexes) {
+            b.claimName(schema, idx.name, { id: `index:${c.path}.${idx.name}`, objectType: 'index', path: `${c.path}.${idx.name}`, changeKind: 'added' });
+            b.emit(`index:${c.path}.${idx.name}`, [tableId], PHASE.INDEX_CREATE, {
+                sql: `${idx.definition};`,
+                objectType: 'index',
+                path: `${c.path}.${idx.name}`,
+                changeKind: 'added',
+                risk: 'safe',
+                riskNote: 'built on a brand-new, empty table — no lock contention with any other session is possible.',
+                reversible: true,
+                down: `DROP INDEX ${qualify(schema, idx.name)};`,
+            });
+        }
+        for (const trg of t.triggers) {
+            b.emit(`trigger:${c.path}.${trg.name}`, [tableId], PHASE.TRIGGER_CREATE, {
+                sql: `${trg.definition};`,
+                objectType: 'trigger',
+                path: `${c.path}.${trg.name}`,
+                changeKind: 'added',
+                risk: 'low',
+                riskNote: 'applies to writes against a table that has no rows yet.',
+                reversible: true,
+                down: `DROP TRIGGER ${quoteIdent(trg.name)} ON ${tableQualified};`,
+            });
+        }
+        for (const fk of t.foreignKeys) {
+            const refTableCreateId = `table:${fk.refSchema}.${fk.refTable}`;
+            const deps = [tableId, b.has(refTableCreateId) ? refTableCreateId : undefined].filter((x) => x !== undefined);
+            b.emit(`fk:${c.path}.${fk.name}`, deps, PHASE.FK_ADD, {
+                sql: `ALTER TABLE ${tableQualified} ADD CONSTRAINT ${quoteIdent(fk.name)} ${fk.definition};`,
+                objectType: 'foreign_key',
+                path: `${c.path}.${fk.name}`,
+                changeKind: 'added',
+                risk: 'safe',
+                riskNote: 'validates zero existing rows — the table is brand new and empty.',
+                reversible: true,
+                down: `ALTER TABLE ${tableQualified} DROP CONSTRAINT ${quoteIdent(fk.name)};`,
+            });
+        }
+        // One PlannedStatement is exactly one statement — the plan is meant to be
+        // applied statement by statement (postgres_execute_sql refuses a
+        // multi-statement string outright), so ENABLE and FORCE are two nodes, and
+        // FORCE is emitted only when it is actually forced: NO FORCE is the
+        // default a fresh CREATE TABLE already has.
+        if (t.rowSecurity.enabled) {
+            b.emit(`rls:${c.path}`, [tableId], PHASE.RLS_ALTER, {
+                sql: `ALTER TABLE ${tableQualified} ENABLE ROW LEVEL SECURITY;`,
+                objectType: 'table',
+                path: c.path,
+                changeKind: 'added',
+                risk: 'moderate',
+                riskNote: 'once enabled, every role without BYPASSRLS sees only rows a policy allows — with no policies yet, that means no rows at all until the policies below are also applied.',
+                reversible: true,
+                down: `ALTER TABLE ${tableQualified} DISABLE ROW LEVEL SECURITY;`,
+            });
+            if (t.rowSecurity.forced) {
+                b.emit(`rlsForce:${c.path}`, [`rls:${c.path}`], PHASE.RLS_ALTER, {
+                    sql: `ALTER TABLE ${tableQualified} FORCE ROW LEVEL SECURITY;`,
+                    objectType: 'table',
+                    path: c.path,
+                    changeKind: 'added',
+                    risk: 'moderate',
+                    riskNote: 'the table owner stops being exempt from its own row-level security policies — a role that could previously see every row now sees only what a policy allows.',
+                    reversible: true,
+                    down: `ALTER TABLE ${tableQualified} NO FORCE ROW LEVEL SECURITY;`,
+                });
+            }
+        }
+        for (const p of t.rowSecurity.policies) {
+            b.emit(`policy:${c.path}.${p.name}`, [tableId], PHASE.POLICY_CREATE, {
+                sql: policyClause(p, schema, name),
+                objectType: 'policy',
+                path: `${c.path}.${p.name}`,
+                changeKind: 'added',
+                risk: 'moderate',
+                riskNote: 'row-level security policies gate row visibility/writes for matching roles — test as those roles before relying on it.',
+                reversible: true,
+                down: `DROP POLICY ${quoteIdent(p.name)} ON ${tableQualified};`,
+            });
+        }
+        return;
+    }
+    if (c.kind === 'removed') {
+        const dropId = `tableDrop:${c.path}`;
+        // DROP TABLE frees the table's own name and, in the same statement, every
+        // index name it owned — including the ones behind its constraints, which
+        // survive an ALTER TABLE ... RENAME and so are exactly what a renamed
+        // table's re-created twin collides with.
+        const t = c.object;
+        b.releaseName(schema, name, dropId);
+        if (t.primaryKey != null)
+            b.releaseName(schema, t.primaryKey.name, dropId);
+        for (const uq of t.uniqueConstraints ?? [])
+            b.releaseName(schema, uq.name, dropId);
+        for (const idx of t.indexes ?? [])
+            b.releaseName(schema, idx.name, dropId);
+        b.emit(dropId, [], PHASE.TABLE_DROP, {
+            sql: `DROP TABLE ${tableQualified};`,
+            objectType: 'table',
+            path: c.path,
+            changeKind: 'removed',
+            risk: 'high',
+            riskNote: 'discards every row in the table, plus every index, constraint, trigger, and policy it owned, irreversibly. Fails if another table still has a foreign key pointing at this one — that foreign key must already be dropped earlier in this plan (this plan does that automatically whenever the diff shows it).',
+            reversible: false,
+            downNote: 'cannot restore: the table\'s definition and every row it held are gone once this runs. Recreate it from a snapshot taken before this change and restore data from a backup.',
+        });
+        b.linkToSchemaDrop(schema, dropId);
+        return;
+    }
+    const owner = field(c.fields, 'owner');
+    if (owner !== undefined) {
+        b.emit(`tableOwner:${c.path}`, [], PHASE.TABLE_ALTER, {
+            sql: `ALTER TABLE ${tableQualified} OWNER TO ${quoteIdent(String(owner.after))};`,
+            objectType: 'table',
+            path: c.path,
+            changeKind: 'modified',
+            risk: 'low',
+            riskNote: 'metadata-only ownership change.',
+            reversible: true,
+            down: `ALTER TABLE ${tableQualified} OWNER TO ${quoteIdent(String(owner.before))};`,
+        });
+    }
+    const comment = field(c.fields, 'comment');
+    if (comment !== undefined) {
+        b.emit(`tableComment:${c.path}`, [], PHASE.TABLE_ALTER, commentStatement('table', c.path, `TABLE ${tableQualified}`, comment));
+    }
+    const kind = field(c.fields, 'kind');
+    if (kind !== undefined) {
+        b.markUnsupported('table', c.path, 'modified', `relation kind changed from "${String(kind.before)}" to "${String(kind.after)}" — ALTER TABLE cannot convert between a plain, partitioned, or foreign table. Recreate it explicitly.`);
+    }
+    const partitionBound = field(c.fields, 'partitionBound');
+    if (partitionBound !== undefined) {
+        b.markUnsupported('table', c.path, 'modified', 'a partition\'s bound changed — moving it needs the parent table\'s name (a separate, possibly-unchanged field not in this diff entry) and is a DETACH PARTITION + ATTACH PARTITION pair with its own window where the partition is attached to neither bound. Not attempted; do this manually.');
+    }
+    const inherits = field(c.fields, 'inherits');
+    if (inherits !== undefined) {
+        const before = new Set(inherits.before);
+        const after = new Set(inherits.after);
+        for (const parent of after) {
+            if (before.has(parent))
+                continue;
+            b.emit(`tableInherit:${c.path}:${parent}`, [], PHASE.TABLE_ALTER, {
+                sql: `ALTER TABLE ${tableQualified} INHERIT ${quoteQualifiedName(parent)};`,
+                objectType: 'table',
+                path: c.path,
+                changeKind: 'modified',
+                risk: 'moderate',
+                riskNote: 'requires every row already in this table to satisfy the parent\'s constraints (scanned to verify) and changes what queries against the parent return.',
+                reversible: true,
+                down: `ALTER TABLE ${tableQualified} NO INHERIT ${quoteQualifiedName(parent)};`,
+            });
+        }
+        for (const parent of before) {
+            if (after.has(parent))
+                continue;
+            b.emit(`tableNoInherit:${c.path}:${parent}`, [], PHASE.TABLE_ALTER, {
+                sql: `ALTER TABLE ${tableQualified} NO INHERIT ${quoteQualifiedName(parent)};`,
+                objectType: 'table',
+                path: c.path,
+                changeKind: 'modified',
+                risk: 'low',
+                riskNote: 'metadata-only — rows stay exactly as they are; only whether a parent-table query includes them changes.',
+                reversible: true,
+                down: `ALTER TABLE ${tableQualified} INHERIT ${quoteQualifiedName(parent)};`,
+            });
+        }
+    }
+    for (const [f, sql] of [
+        ['rowSecurity.enabled', 'ROW LEVEL SECURITY'],
+        ['rowSecurity.forced', 'FORCE ROW LEVEL SECURITY'],
+    ]) {
+        const ch = field(c.fields, f);
+        if (ch === undefined)
+            continue;
+        const enable = ch.after === true;
+        const verb = f === 'rowSecurity.enabled' ? (enable ? 'ENABLE' : 'DISABLE') : enable ? 'FORCE' : 'NO FORCE';
+        const downVerb = f === 'rowSecurity.enabled' ? (enable ? 'DISABLE' : 'ENABLE') : enable ? 'NO FORCE' : 'FORCE';
+        b.emit(`table${f}:${c.path}`, [], PHASE.RLS_ALTER, {
+            sql: `ALTER TABLE ${tableQualified} ${verb} ${sql === 'ROW LEVEL SECURITY' ? sql : sql};`,
+            objectType: 'table',
+            path: c.path,
+            changeKind: 'modified',
+            risk: f === 'rowSecurity.enabled' && enable ? 'moderate' : 'low',
+            riskNote: f === 'rowSecurity.enabled' && enable
+                ? 'once enabled, every role without BYPASSRLS immediately sees only rows the existing policies allow — if there are no policies, that means no rows at all.'
+                : 'metadata-only toggle.',
+            reversible: true,
+            down: `ALTER TABLE ${tableQualified} ${downVerb} ${sql};`,
+        });
+    }
+}
+// --- Database (never actionable) ------------------------------------------
+function handleDatabase(b, c) {
+    b.markUnsupported('database', c.path, c.kind, 'the two snapshots were captured from differently-named databases — that is not a schema change to plan a migration for. Make sure both snapshots come from the same database.');
+}
+// ---------------------------------------------------------------------------
+// Entry point.
+// ---------------------------------------------------------------------------
+export function planMigration(rawChanges, opts = {}) {
+    const resolved = { concurrentIndexes: opts.concurrentIndexes ?? true };
+    const changes = expandSchemaChanges(rawChanges);
+    const b = new Builder(changes);
+    for (const c of changes) {
+        switch (c.objectType) {
+            case 'database':
+                handleDatabase(b, c);
+                break;
+            case 'schema':
+                handleSchema(b, c);
+                break;
+            case 'extension':
+                handleExtension(b, c);
+                break;
+            case 'enum':
+                handleEnum(b, c);
+                break;
+            case 'sequence':
+                handleSequence(b, c);
+                break;
+            case 'function':
+                handleFunction(b, c);
+                break;
+            case 'table':
+                handleTable(b, c);
+                break;
+            case 'view':
+                handleView(b, c, false);
+                break;
+            case 'materialized_view':
+                handleView(b, c, true);
+                break;
+            case 'column':
+                handleColumn(b, c);
+                break;
+            case 'primary_key':
+                handleGenericConstraint(b, c, PHASE.CONSTRAINT_DROP, PHASE.CONSTRAINT_ADD);
+                break;
+            case 'unique_constraint':
+                handleGenericConstraint(b, c, PHASE.CONSTRAINT_DROP, PHASE.CONSTRAINT_ADD);
+                break;
+            case 'check_constraint':
+                handleGenericConstraint(b, c, PHASE.CONSTRAINT_DROP, PHASE.CONSTRAINT_ADD);
+                break;
+            case 'foreign_key':
+                handleForeignKey(b, c);
+                break;
+            case 'index':
+                handleIndex(b, c, resolved);
+                break;
+            case 'trigger':
+                handleTrigger(b, c);
+                break;
+            case 'policy':
+                handlePolicy(b, c);
+                break;
+            default:
+                b.markUnsupported(c.objectType, c.path, c.kind, `no handler registered for object type "${c.objectType}".`);
+        }
+    }
+    b.resolveNameCollisions();
+    const graph = b.toGraph();
+    const statements = topoSort(graph);
+    return { statements, unsupported: b.unsupported };
+}
+//# sourceMappingURL=migrate.js.map