@supabase/pg-delta 1.0.0-alpha.2 → 1.0.0-alpha.21

package/dist/core/postgres-config.js

@@ -1,7 +1,9 @@
 /**
  * PostgreSQL connection configuration with custom type handlers.
  */
-import { Pool, types } from "pg";
+import { escapeIdentifier, Pool, types } from "pg";
+import { normalizeConnectionUrl } from "./connection-url.js";
+import { parseSslConfig } from "./plan/ssl-config.js";
 // ============================================================================
 // Array Parser
 // ============================================================================
@@ -92,14 +94,152 @@ types.setTypeParser(1005, (val) => parseArray(val, parseIntElement)); // int2[]
 types.setTypeParser(1007, (val) => parseArray(val, parseIntElement)); // int4[]
 // @ts-expect-error - pg types expects TypeId but raw OID numbers work fine
 types.setTypeParser(1016, (val) => parseArray(val, parseIntElement)); // int8[]
+const DEFAULT_POOL_MAX = Number(process.env.PGDELTA_POOL_MAX) || 5;
+const DEFAULT_CONNECTION_TIMEOUT_MS = Number(process.env.PGDELTA_CONNECTION_TIMEOUT_MS) || 3_000;
+const DEFAULT_CONNECT_TIMEOUT_MS = Number(process.env.PGDELTA_CONNECT_TIMEOUT_MS) || 2_500;
+const DEFAULT_CONNECT_MAX_ATTEMPTS = Number(process.env.PGDELTA_CONNECT_MAX_ATTEMPTS) || 3;
+const DEFAULT_CONNECT_BASE_BACKOFF_MS = Number(process.env.PGDELTA_CONNECT_BASE_BACKOFF_MS) || 250;
+const DEFAULT_CONNECT_MAX_BACKOFF_MS = Number(process.env.PGDELTA_CONNECT_MAX_BACKOFF_MS) || 1_000;
+// PostgreSQL auth-class SQLSTATE codes: not retryable.
+const NON_RETRYABLE_PG_CODES = new Set([
+    "28000", // invalid_authorization_specification
+    "28P01", // invalid_password
+    "28P02", // pgdelta: alias reserved here to future-proof against new auth codes
+]);
+// Non-retryable TLS/SSL markers. The `pg` driver surfaces TLS failures as
+// either plain Node `Error` instances with a code on `ERR_TLS_*` or error
+// messages that include well-known cert/TLS terminology; we match both
+// because node-pg normalises some of these.
+const TLS_MESSAGE_MARKERS = [
+    "self-signed certificate",
+    "self signed certificate",
+    "unable to verify the first certificate",
+    "certificate has expired",
+    "tls",
+    "ssl",
+];
+/**
+ * Return true when `err` represents a transient connect failure that makes
+ * sense to retry with backoff (e.g. refused connections, DNS blips, our own
+ * eager-connect timeout wrapper). Returns false for permanent failures such
+ * as authentication errors, TLS negotiation errors, and `ENOTFOUND`.
+ *
+ * Unknown errors are treated as retryable on purpose: transient-by-default
+ * is safer here because a duplicated retry is strictly cheaper than a spurious
+ * hard failure during catalog extraction.
+ */
+export function isRetryableConnectError(err) {
+    if (!(err instanceof Error))
+        return true;
+    const code = err.code;
+    if (code && NON_RETRYABLE_PG_CODES.has(code))
+        return false;
+    if (code === "ENOTFOUND")
+        return false;
+    if (code && typeof code === "string" && code.startsWith("ERR_TLS")) {
+        return false;
+    }
+    const message = err.message?.toLowerCase() ?? "";
+    // Our own eager-connect timeout wrapper is retryable (flaky network).
+    if (message.includes("timed out after"))
+        return true;
+    for (const marker of TLS_MESSAGE_MARKERS) {
+        if (message.includes(marker))
+            return false;
+    }
+    return true;
+}
+/**
+ * Retry an async `connect` operation with bounded exponential backoff.
+ * Stops immediately on a non-retryable error. On exhausted attempts, throws
+ * the last observed error.
+ *
+ * Exposed for testing — production call sites always go through
+ * {@link createManagedPool}.
+ */
+export async function connectWithRetry(opts) {
+    const maxAttempts = opts.maxAttempts ?? DEFAULT_CONNECT_MAX_ATTEMPTS;
+    const baseBackoffMs = opts.baseBackoffMs ?? DEFAULT_CONNECT_BASE_BACKOFF_MS;
+    const maxBackoffMs = opts.maxBackoffMs ?? DEFAULT_CONNECT_MAX_BACKOFF_MS;
+    const isRetryable = opts.isRetryable ?? isRetryableConnectError;
+    const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            return await opts.connect(attempt);
+        }
+        catch (err) {
+            lastError = err;
+            if (attempt >= maxAttempts || !isRetryable(err)) {
+                throw err;
+            }
+            const backoff = Math.min(baseBackoffMs * 2 ** (attempt - 1), maxBackoffMs);
+            await sleep(backoff);
+        }
+    }
+    // Unreachable: loop either returns or throws.
+    throw lastError;
+}
 /**
  * Create a Pool with custom type handlers and optional event listeners.
+ *
+ * `connectionString` may be `undefined` when the caller needs pg to rely on
+ * explicit `host`/`port`/`user`/... fields from `options` instead — notably
+ * the bracketed-IPv6 workaround in {@link poolConfigFromUrl}, where passing
+ * the connection string would cause `pg-connection-string` to re-inject the
+ * bracketed host that breaks `getaddrinfo`.
  */
 export function createPool(connectionString, options) {
     const { onConnect, onError, onAcquire, onRemove, ...config } = options ?? {};
-    const pool = new Pool({ connectionString, ...config });
-    if (onConnect)
-        pool.on("connect", onConnect);
+    const pool = new Pool({
+        ...(connectionString ? { connectionString } : {}),
+        max: DEFAULT_POOL_MAX,
+        connectionTimeoutMillis: DEFAULT_CONNECTION_TIMEOUT_MS,
+        ...config,
+    });
+    if (onConnect) {
+        const pendingClientSetup = new WeakMap();
+        const waitForClientSetup = async (client) => {
+            const setup = pendingClientSetup.get(client);
+            if (setup) {
+                await setup;
+                return;
+            }
+            throw new Error("Internal error: pool client was acquired before async onConnect setup was registered. This indicates a bug in the pool wrapper logic; please report it with reproduction steps.");
+        };
+        const originalConnect = pool.connect.bind(pool);
+        pool.on("connect", (client) => {
+            pendingClientSetup.set(client, Promise.resolve().then(() => onConnect(client)));
+        });
+        pool.connect = ((callback) => {
+            if (!callback) {
+                return originalConnect().then(async (client) => {
+                    try {
+                        await waitForClientSetup(client);
+                        return client;
+                    }
+                    catch (setupError) {
+                        client.release?.(setupError);
+                        throw setupError;
+                    }
+                });
+            }
+            return originalConnect(async (err, client, release) => {
+                if (err || !client) {
+                    callback(err, client, release);
+                    return;
+                }
+                try {
+                    await waitForClientSetup(client);
+                    callback(err, client, release);
+                }
+                catch (setupError) {
+                    release(setupError);
+                    callback(setupError, undefined, () => { });
+                }
+            });
+        });
+    }
     if (onError)
         pool.on("error", onError);
     if (onAcquire)
@@ -108,3 +248,132 @@ export function createPool(connectionString, options) {
         pool.on("remove", onRemove);
     return pool;
 }
+/**
+ * Build a pg {@link PoolConfig} from a cleaned connection URL.
+ *
+ * For most URLs this just returns `{ connectionString }` and pg does its
+ * normal parsing. But for URLs whose hostname is a bracketed IPv6 literal
+ * (e.g. `postgresql://user@[::1]:5432/db`, as produced by
+ * {@link normalizeConnectionUrl}), we expand the URL into explicit
+ * `host`/`port`/`user`/`password`/`database` fields with a **bare** IPv6
+ * host — no brackets.
+ *
+ * This works around a `pg-connection-string` quirk: its parser sets
+ * `config.host` to the WHATWG `URL.hostname`, which keeps the surrounding
+ * `[...]` for IPv6 literals. That bracketed value is then passed verbatim to
+ * `getaddrinfo`, which rejects it with `ENOTFOUND`. Since
+ * `pg`'s connection-parameters module does
+ * `Object.assign({}, config, parse(connectionString))`, any `host` we pass
+ * alongside `connectionString` gets clobbered — so we drop `connectionString`
+ * entirely on this path and hand pg the parsed fields directly.
+ *
+ * Remaining query parameters (e.g. `application_name`, `options`,
+ * `connect_timeout`) are forwarded as top-level config keys, mirroring how
+ * `pg-connection-string` would normally surface them.
+ */
+export function poolConfigFromUrl(cleanedUrl) {
+    const urlObj = new URL(cleanedUrl);
+    if (!urlObj.hostname.startsWith("[")) {
+        return { connectionString: cleanedUrl };
+    }
+    const config = {
+        host: urlObj.hostname.slice(1, -1),
+    };
+    if (urlObj.port)
+        config.port = Number(urlObj.port);
+    if (urlObj.username)
+        config.user = decodeURIComponent(urlObj.username);
+    if (urlObj.password)
+        config.password = decodeURIComponent(urlObj.password);
+    if (urlObj.pathname.length > 1) {
+        config.database = decodeURIComponent(urlObj.pathname.slice(1));
+    }
+    for (const [key, value] of urlObj.searchParams) {
+        config[key] = value;
+    }
+    return config;
+}
+/**
+ * End a pool and wait for all client sockets to fully close.
+ *
+ * pg-pool's `pool.end()` resolves once clients are removed from its
+ * internal bookkeeping, but the underlying `client.end()` calls (which
+ * close the TCP/TLS sockets) are fired asynchronously *after* that.
+ * If the server (e.g. a test container) is stopped right after
+ * `pool.end()` resolves, the still-open sockets receive an unexpected
+ * RST and emit unhandled "Connection terminated unexpectedly" errors.
+ *
+ * This helper waits for every `remove` event — which pg-pool emits
+ * inside each `client.end()` callback — ensuring all sockets are
+ * truly closed before it resolves.
+ */
+/**
+ * Create a pool from a connection URL with standard session setup:
+ * SSL parsing, search_path isolation, optional SET ROLE, and 57P01 suppression.
+ *
+ * Returns the pool and a `close` function that properly waits for all sockets
+ * to close (via {@link endPool}).
+ */
+export async function createManagedPool(url, options) {
+    // Normalize percent-encoded IPv6 hosts (e.g. `2406%3A...%3Ab3c9`) into the
+    // canonical bracketed form before the URL reaches `parseSslConfig` or pg.
+    // Non-IPv6 hosts are returned unchanged.
+    const normalizedUrl = normalizeConnectionUrl(url);
+    const sslConfig = await parseSslConfig(normalizedUrl, options?.label ?? "target");
+    // Expand bracketed-IPv6 URLs into explicit pg fields so the brackets never
+    // reach `getaddrinfo` — see `poolConfigFromUrl` for the full rationale.
+    const connectionConfig = poolConfigFromUrl(sslConfig.cleanedUrl);
+    const pool = createPool(connectionConfig.connectionString, {
+        ...connectionConfig,
+        ...(sslConfig.ssl !== undefined ? { ssl: sslConfig.ssl } : {}),
+        onError: (err) => {
+            if (err.code !== "57P01") {
+                console.error("Pool error:", err);
+            }
+        },
+        onConnect: async (client) => {
+            await client.query("SET search_path = ''");
+            if (options?.role) {
+                await client.query(`SET ROLE ${escapeIdentifier(options.role)}`);
+            }
+        },
+    });
+    // Eagerly validate connectivity so SSL/auth failures surface immediately
+    // instead of hanging on the first real query. node-pg's connectionTimeoutMillis
+    // is not reliably enforced under Bun when SSL negotiation hangs. Transient
+    // failures (refused connections, flaky DNS, our own timeout wrapper) are
+    // retried with bounded exponential backoff; auth/TLS/ENOTFOUND fail fast.
+    const label = options?.label ?? "target";
+    const timeoutMs = DEFAULT_CONNECT_TIMEOUT_MS;
+    try {
+        const client = await connectWithRetry({
+            connect: () => Promise.race([
+                pool.connect(),
+                new Promise((_, reject) => setTimeout(() => reject(new Error(`Connection to ${label} database timed out after ${timeoutMs}ms. ` +
+                    `The server may require SSL, use an invalid certificate, or be unreachable.`)), timeoutMs)),
+            ]),
+        });
+        client.release();
+    }
+    catch (err) {
+        await pool.end().catch(() => { });
+        throw err;
+    }
+    return { pool, close: () => endPool(pool) };
+}
+export function endPool(pool) {
+    const clientCount = pool.totalCount;
+    if (clientCount === 0) {
+        return pool.end();
+    }
+    return new Promise((resolve, reject) => {
+        let removed = 0;
+        pool.on("remove", function onRemove() {
+            if (++removed >= clientCount) {
+                pool.removeListener("remove", onRemove);
+                resolve();
+            }
+        });
+        pool.end().catch(reject);
+    });
+}

package/dist/core/sort/custom-constraints.js

@@ -1,5 +1,6 @@
-import { getSchema } from "../integrations/filter/extractors.js";
+import { getSchema } from "../change-utils.js";
 import { GrantRoleDefaultPrivileges, RevokeRoleDefaultPrivileges, } from "../objects/role/changes/role.privilege.js";
+import { AlterTableAlterColumnAddIdentity, AlterTableAlterColumnDropDefault, AlterTableAlterColumnDropIdentity, AlterTableAlterColumnSetDefault, } from "../objects/table/changes/table.alter.js";
 /**
  * Maps object type names to PostgreSQL default privilege objtype codes.
  * This mirrors the mapping in base.default-privileges.ts.
@@ -116,11 +117,74 @@ function generateDefaultPrivilegeConstraints(changes) {
     }
     return constraints;
 }
+function generateIdentityTransitionConstraints(changes) {
+    const constraints = [];
+    const dropDefaultByColumn = new Map();
+    const dropIdentityByColumn = new Map();
+    const addIdentityByColumn = new Map();
+    const setDefaultByColumn = new Map();
+    for (let i = 0; i < changes.length; i++) {
+        const change = changes[i];
+        const columnKey = "table" in change && "column" in change
+            ? `${change.table.schema}.${change.table.name}.${change.column.name}`
+            : null;
+        if (!columnKey)
+            continue;
+        if (change instanceof AlterTableAlterColumnDropDefault) {
+            const entries = dropDefaultByColumn.get(columnKey) ?? [];
+            entries.push(i);
+            dropDefaultByColumn.set(columnKey, entries);
+        }
+        else if (change instanceof AlterTableAlterColumnAddIdentity) {
+            const entries = addIdentityByColumn.get(columnKey) ?? [];
+            entries.push(i);
+            addIdentityByColumn.set(columnKey, entries);
+        }
+        else if (change instanceof AlterTableAlterColumnDropIdentity) {
+            const entries = dropIdentityByColumn.get(columnKey) ?? [];
+            entries.push(i);
+            dropIdentityByColumn.set(columnKey, entries);
+        }
+        else if (change instanceof AlterTableAlterColumnSetDefault) {
+            const entries = setDefaultByColumn.get(columnKey) ?? [];
+            entries.push(i);
+            setDefaultByColumn.set(columnKey, entries);
+        }
+    }
+    // These rules only order same-column ALTERs inside the create/alter phase.
+    // Sequence drops are handled separately in the earlier drop phase.
+    for (const [columnKey, dropDefaultIndexes] of dropDefaultByColumn) {
+        const addIdentityIndexes = addIdentityByColumn.get(columnKey) ?? [];
+        for (const sourceIndex of dropDefaultIndexes) {
+            for (const targetIndex of addIdentityIndexes) {
+                constraints.push({
+                    sourceChangeIndex: sourceIndex,
+                    targetChangeIndex: targetIndex,
+                    source: "custom",
+                });
+            }
+        }
+    }
+    for (const [columnKey, dropIdentityIndexes] of dropIdentityByColumn) {
+        const setDefaultIndexes = setDefaultByColumn.get(columnKey) ?? [];
+        for (const sourceIndex of dropIdentityIndexes) {
+            for (const targetIndex of setDefaultIndexes) {
+                constraints.push({
+                    sourceChangeIndex: sourceIndex,
+                    targetChangeIndex: targetIndex,
+                    source: "custom",
+                });
+            }
+        }
+    }
+    return constraints;
+}
 /**
  * All custom constraint generators.
  */
 const customConstraintGenerators = [
     generateDefaultPrivilegeConstraints,
+    generateIdentityTransitionConstraints,
 ];
 /**
  * Generate Constraints from custom constraint generators.

package/dist/core/sort/cycle-breakers.d.ts

@@ -0,0 +1,15 @@
+import type { Change } from "../change.types.ts";
+/**
+ * Try to break an unbreakable cycle by INJECTING NEW CHANGES or REWRITING
+ * existing ones (rather than removing graph edges).
+ *
+ * Called by `sortPhaseChanges` when its edge-removal cycle handler has seen
+ * the same cycle twice — i.e. weak-edge filtering exhausted itself but the
+ * cycle is still there. At that point we know the cycle is composed of
+ * "hard" edges (explicit `requires` or pg_depend rows) that can only be
+ * broken by changing the change list itself.
+ *
+ * Returns a rewritten `phaseChanges` array, or `null` if no breaker matches
+ * (in which case the caller throws the existing CycleError).
+ */
+export declare function tryBreakCycleByChangeInjection(cycleNodeIndexes: readonly number[], phaseChanges: readonly Change[]): Change[] | null;

package/dist/core/sort/cycle-breakers.js

@@ -0,0 +1,269 @@
+import { AlterPublicationDropTables } from "../objects/publication/changes/publication.alter.js";
+import { AlterTableDropColumn, AlterTableDropConstraint, } from "../objects/table/changes/table.alter.js";
+import { DropTable } from "../objects/table/changes/table.drop.js";
+import { stableId } from "../objects/utils.js";
+/**
+ * Try to break an unbreakable cycle by INJECTING NEW CHANGES or REWRITING
+ * existing ones (rather than removing graph edges).
+ *
+ * Called by `sortPhaseChanges` when its edge-removal cycle handler has seen
+ * the same cycle twice — i.e. weak-edge filtering exhausted itself but the
+ * cycle is still there. At that point we know the cycle is composed of
+ * "hard" edges (explicit `requires` or pg_depend rows) that can only be
+ * broken by changing the change list itself.
+ *
+ * Returns a rewritten `phaseChanges` array, or `null` if no breaker matches
+ * (in which case the caller throws the existing CycleError).
+ */
+export function tryBreakCycleByChangeInjection(cycleNodeIndexes, phaseChanges) {
+    // ─── Branch A: FK cycle among DropTable changes ──────────────────────
+    // Triggered when N≥2 dropped tables reference each other via foreign
+    // keys. With no surviving table on either side, every FK constraint
+    // stable-id ends up tied back to a DropTable node, and every
+    // pg_depend row produces a hard explicit edge between two DropTables.
+    // Edge filtering can't break it — the edges are not weak.
+    //
+    // Example (3-cycle):
+    //   DROP TABLE a; DROP TABLE b; DROP TABLE c;
+    //   where  a.b_id REFERENCES b,  b.c_id REFERENCES c,  c.a_id REFERENCES a
+    //
+    // Fix: inject a dedicated `ALTER TABLE ... DROP CONSTRAINT fk` ahead of
+    // each DropTable in the cycle, and mark the constraint name on
+    // `DropTable.externallyDroppedConstraints` so the table drop won't try
+    // to re-claim the same constraint stable-id. The injected drops have
+    // their own stable-id ownership and run before any DropTable, breaking
+    // the cycle.
+    //
+    // This naturally handles any N (2-cycle, 3-cycle, …) because
+    // `findCycle` already gave us the full member list — no separate SCC
+    // enumeration needed.
+    const fkBroken = tryBreakFkCycle(cycleNodeIndexes, phaseChanges);
+    if (fkBroken)
+        return fkBroken;
+    // ─── Branch B: Publication ↔ Column on a surviving table ─────────────
+    // Triggered when a publication has an explicit column list and one of
+    // those columns is dropped on a table that itself is NOT being dropped
+    // (the table just loses one column).
+    //
+    // Example:
+    //   CREATE PUBLICATION p FOR TABLE lab_results (id, flash_summary);
+    //   ALTER TABLE lab_results DROP COLUMN flash_summary;
+    //
+    // Diff emits two drop-phase changes:
+    //   AlterPublicationDropTables(p, [lab_results])
+    //   AlterTableDropColumn(lab_results.flash_summary)
+    //
+    // The cycle:
+    //   pub:p → col:lab_results.flash_summary  (catalog, pg_depend)
+    //   col:lab_results.flash_summary → table:lab_results
+    //                                         (explicit, AlterTableDropColumn.requires)
+    //
+    // Fix: rebuild the AlterTableDropColumn with `omitTableRequirement=true`
+    // so it no longer requires `table:lab_results`. Safe because
+    // `lab_results` survives the migration; its lifetime trivially covers
+    // the column drop. The catalog edge `pub → col` correctly orders the
+    // publication drop before the column drop.
+    const pubColBroken = tryBreakPublicationColumnCycle(cycleNodeIndexes, phaseChanges);
+    if (pubColBroken)
+        return pubColBroken;
+    // No known pattern. Returning null lets sortPhaseChanges throw the
+    // formatted CycleError with full diagnostic — better a clear bug
+    // report than silently shipping a broken plan.
+    return null;
+}
+/**
+ * Branch A worker — inject `AlterTableDropConstraint` for every FK linking
+ * two DropTables in the cycle.
+ *
+ * Returns the rewritten changes array, or `null` if the cycle does not
+ * match (e.g. mixed types, or no cross-cycle FK exists).
+ */
+function tryBreakFkCycle(cycleNodeIndexes, phaseChanges) {
+    // Guard: every member of the cycle must be a DropTable. Mixed cycles
+    // (e.g. DropTable + DropView, or DropTable + DropMaterializedView) are
+    // out of scope — they need a different breaker.
+    const cycleDropTables = [];
+    for (const nodeIndex of cycleNodeIndexes) {
+        const change = phaseChanges[nodeIndex];
+        if (!(change instanceof DropTable))
+            return null;
+        cycleDropTables.push(change);
+    }
+    const cycleTableIds = new Set(cycleDropTables.map((change) => change.table.stableId));
+    // For each DropTable in the cycle, find every FK whose referenced table
+    // is also in the cycle. Each such FK becomes one injected
+    // `AlterTableDropConstraint` and one entry on the source table's
+    // `externallyDroppedConstraints`.
+    //
+    // 2-cycle example: { A→B, B→A } — two FKs, two injected drops.
+    // 3-cycle example: { A→B, B→C, C→A } — three FKs, three injected drops.
+    const injectedDropsByTableId = new Map();
+    const updatedExternalsByTableId = new Map();
+    let didMutate = false;
+    for (const dropTable of cycleDropTables) {
+        const tableId = dropTable.table.stableId;
+        const existingExternals = new Set(dropTable.externallyDroppedConstraints);
+        let tableMutated = false;
+        for (const fk of iterCrossCycleFkConstraints(dropTable.table.constraints, tableId, cycleTableIds)) {
+            // Skip if a same-table `AlterTableDropConstraint` is already in the
+            // change list — could happen if a previous breaker iteration
+            // injected one, or the diff layer emitted one explicitly.
+            if (existingExternals.has(fk.name))
+                continue;
+            if (alreadyHasExplicitDrop(phaseChanges, tableId, fk.name))
+                continue;
+            const injected = new AlterTableDropConstraint({
+                table: dropTable.table,
+                constraint: fk,
+            });
+            const list = injectedDropsByTableId.get(tableId) ?? [];
+            list.push(injected);
+            injectedDropsByTableId.set(tableId, list);
+            existingExternals.add(fk.name);
+            tableMutated = true;
+            didMutate = true;
+        }
+        if (tableMutated) {
+            updatedExternalsByTableId.set(tableId, existingExternals);
+        }
+    }
+    if (!didMutate)
+        return null;
+    // Rebuild phaseChanges: keep all non-DropTable changes in place. For
+    // each DropTable in the cycle that gained injected drops, emit the
+    // injected drops first, then a fresh DropTable carrying the updated
+    // `externallyDroppedConstraints` so it stops claiming the FK
+    // stable-ids.
+    const rewritten = [];
+    for (const change of phaseChanges) {
+        if (!(change instanceof DropTable)) {
+            rewritten.push(change);
+            continue;
+        }
+        const tableId = change.table.stableId;
+        const injected = injectedDropsByTableId.get(tableId);
+        if (injected) {
+            rewritten.push(...injected);
+        }
+        const updatedExternals = updatedExternalsByTableId.get(tableId);
+        if (updatedExternals) {
+            rewritten.push(new DropTable({
+                table: change.table,
+                externallyDroppedConstraints: updatedExternals,
+            }));
+        }
+        else {
+            rewritten.push(change);
+        }
+    }
+    return rewritten;
+}
+/**
+ * Yield FK constraints on `constraints` whose referenced table is also a
+ * member of the cycle (i.e. an FK strictly between two cycle DropTables).
+ *
+ * Self-referencing FKs are skipped — they create a self-loop in the
+ * dependency graph which the existing sort-phase handler resolves on its
+ * own; injecting an `AlterTableDropConstraint` for a self-FK would just
+ * add noise.
+ */
+function* iterCrossCycleFkConstraints(constraints, ownTableId, cycleTableIds) {
+    for (const constraint of constraints) {
+        if (constraint.constraint_type !== "f")
+            continue;
+        if (constraint.is_partition_clone)
+            continue;
+        if (!constraint.foreign_key_schema || !constraint.foreign_key_table) {
+            continue;
+        }
+        const referencedId = stableId.table(constraint.foreign_key_schema, constraint.foreign_key_table);
+        if (referencedId === ownTableId)
+            continue;
+        if (!cycleTableIds.has(referencedId))
+            continue;
+        yield constraint;
+    }
+}
+/**
+ * True iff `phaseChanges` already contains an explicit
+ * `AlterTableDropConstraint(table, constraint)` for the given pair —
+ * either emitted by the diff layer or by a previous breaker iteration.
+ * Avoids duplicate constraint drops.
+ */
+function alreadyHasExplicitDrop(phaseChanges, tableId, constraintName) {
+    for (const change of phaseChanges) {
+        if (!(change instanceof AlterTableDropConstraint))
+            continue;
+        if (change.table.stableId !== tableId)
+            continue;
+        if (change.constraint.name === constraintName)
+            return true;
+    }
+    return false;
+}
+/**
+ * Branch B worker — break the publication↔column cycle by rebuilding the
+ * `AlterTableDropColumn` change with `omitTableRequirement=true`.
+ *
+ * Returns the rewritten changes array, or `null` if the cycle does not
+ * match (e.g. table is also being dropped, or no `AlterPublicationDropTables`
+ * references the table).
+ */
+function tryBreakPublicationColumnCycle(cycleNodeIndexes, phaseChanges) {
+    // Find an `AlterTableDropColumn` and an `AlterPublicationDropTables` in
+    // the cycle that reference the same table. Both must be present —
+    // otherwise this is a different cycle shape.
+    let dropColumnIndex = -1;
+    let dropColumnChange = null;
+    let pubMatchesTable = false;
+    let pubChange = null;
+    for (const nodeIndex of cycleNodeIndexes) {
+        const change = phaseChanges[nodeIndex];
+        if (change instanceof AlterTableDropColumn &&
+            !change.omitTableRequirement) {
+            dropColumnIndex = nodeIndex;
+            dropColumnChange = change;
+        }
+        else if (change instanceof AlterPublicationDropTables) {
+            pubChange = change;
+        }
+    }
+    if (dropColumnChange === null || pubChange === null)
+        return null;
+    // Verify the publication is actually dropping membership for the same
+    // table whose column is being dropped. Without this check we'd risk
+    // rewriting an unrelated AlterTableDropColumn that happens to share a
+    // cycle with some other publication change.
+    const targetTableId = dropColumnChange.table.stableId;
+    for (const t of pubChange.tables) {
+        if (stableId.table(t.schema, t.name) === targetTableId) {
+            pubMatchesTable = true;
+            break;
+        }
+    }
+    if (!pubMatchesTable)
+        return null;
+    // Verify the table is NOT itself being dropped. If `DropTable(T)` is in
+    // the same phase, the existing structural rewrites in
+    // `post-diff-cycle-breaking.ts` (replace-expansion superseded filter)
+    // already prune the redundant `AlterTableDropColumn`, so we should not
+    // see this combination here. Be defensive and bail anyway — flipping
+    // `omitTableRequirement` when T is being dropped would let the column
+    // drop reorder against the table drop, which is unsafe.
+    for (const change of phaseChanges) {
+        if (change instanceof DropTable &&
+            change.table.stableId === targetTableId) {
+            return null;
+        }
+    }
+    // Replace the AlterTableDropColumn with a fresh instance carrying
+    // `omitTableRequirement=true`. All other changes pass through
+    // unchanged.
+    const rewritten = phaseChanges.slice();
+    rewritten[dropColumnIndex] = new AlterTableDropColumn({
+        table: dropColumnChange.table,
+        column: dropColumnChange.column,
+        omitTableRequirement: true,
+    });
+    return rewritten;
+}

package/dist/core/sort/graph-builder.js

@@ -56,7 +56,17 @@ export function convertExplicitRequirementsToConstraints(phaseChanges, graphData
         const requiredIds = graphData.explicitRequirementSets[consumerIndex];
         if (requiredIds.size === 0)
             continue;
+        // Collect dropped IDs for this change so we can skip requirements
+        // for stableIds that this change also drops.  A change that drops a
+        // stableId should not depend on another change that creates the same
+        // stableId, because the entity already exists in the source database.
+        // This prevents false ordering constraints such as Grant → Revoke
+        // when both operate on the same ACL stableId.
+        const droppedIds = new Set(phaseChanges[consumerIndex].drops);
         for (const requiredId of requiredIds) {
+            if (droppedIds.has(requiredId)) {
+                continue;
+            }
             const producerIndexes = graphData.changeIndexesByCreatedId.get(requiredId);
             if (!producerIndexes || producerIndexes.size === 0)
                 continue;