@supabase/pg-delta 1.0.0-alpha.20 → 1.0.0-alpha.22

package/dist/core/post-diff-normalization.js

@@ -0,0 +1,202 @@
+import { CreateIndex } from "./objects/index/changes/index.create.js";
+import { DropIndex } from "./objects/index/changes/index.drop.js";
+import { AlterTableAddConstraint, AlterTableDropColumn, AlterTableDropConstraint, AlterTableSetReplicaIdentity, AlterTableValidateConstraint, } from "./objects/table/changes/table.alter.js";
+import { CreateCommentOnConstraint } from "./objects/table/changes/table.comment.js";
+import { stableId } from "./objects/utils.js";
+function constraintStableId(table, constraintName) {
+    return stableId.constraint(table.schema, table.name, constraintName);
+}
+function isSupersededByTableReplacement(change, replacedTableIds) {
+    if (!(change instanceof AlterTableDropColumn) &&
+        !(change instanceof AlterTableDropConstraint)) {
+        return false;
+    }
+    return replacedTableIds.has(change.table.stableId);
+}
+/**
+ * Drop earlier duplicates of `AlterTableAddConstraint` /
+ * `AlterTableValidateConstraint` / `CreateCommentOnConstraint` targeting
+ * replaced tables, keeping only the last occurrence of each
+ * `(changeType, table.stableId, constraint.name)`.
+ *
+ * When `expandReplaceDependencies()` promotes a table to a full
+ * `DropTable + CreateTable` pair, it also emits one
+ * `AlterTableAddConstraint` (plus optional `VALIDATE CONSTRAINT` /
+ * `COMMENT ON CONSTRAINT`) per branch constraint. If `diffTables()` already
+ * emitted the same change for a shape flip or a new constraint on that
+ * table, the plan ends up with two identical `ALTER TABLE ... ADD
+ * CONSTRAINT ...` statements and PostgreSQL fails at apply time with
+ * `constraint "..." for relation "..." already exists`. Because
+ * `expandReplaceDependencies()` appends its additions after the original
+ * `diffTables()` output, the last occurrence is the expansion's emission —
+ * keeping it preserves correctness while removing the duplicate.
+ */
+function dropReplacedTableDuplicateConstraintChanges(changes, replacedTableIds) {
+    if (replacedTableIds.size === 0)
+        return changes;
+    const keyFor = (change) => {
+        if (!(change instanceof AlterTableAddConstraint) &&
+            !(change instanceof AlterTableValidateConstraint) &&
+            !(change instanceof CreateCommentOnConstraint)) {
+            return null;
+        }
+        if (!replacedTableIds.has(change.table.stableId))
+            return null;
+        const tag = change instanceof AlterTableAddConstraint
+            ? "add"
+            : change instanceof AlterTableValidateConstraint
+                ? "validate"
+                : "comment";
+        return `${tag}:${constraintStableId(change.table, change.constraint.name)}`;
+    };
+    const seen = new Set();
+    const reversedKept = [];
+    let mutated = false;
+    // Walk backwards: the first encounter of each key corresponds to its LAST
+    // occurrence in the original order. `expandReplaceDependencies()` appends
+    // additions after the original changes, so "last wins" keeps the
+    // expansion's emission and drops the earlier diffTables duplicate.
+    for (let i = changes.length - 1; i >= 0; i--) {
+        const change = changes[i];
+        const key = keyFor(change);
+        if (key !== null) {
+            if (seen.has(key)) {
+                mutated = true;
+                continue;
+            }
+            seen.add(key);
+        }
+        reversedKept.push(change);
+    }
+    return mutated ? reversedKept.reverse() : changes;
+}
+/**
+ * Re-emit `ALTER TABLE ... REPLICA IDENTITY USING INDEX <idx>` after any
+ * `DropIndex(idx) + CreateIndex(idx)` pair where `idx` is the replica-identity
+ * index of a branch table.
+ *
+ * Background: PostgreSQL silently flips a table's `relreplident` to `'d'`
+ * (DEFAULT) when the index it points to is dropped. `CREATE INDEX` cannot
+ * restore the marker — only `ALTER TABLE ... REPLICA IDENTITY USING INDEX`
+ * can. When both main and branch carry `replica_identity = 'i'` pointing at
+ * the same index name, `diffTables()` emits no replica-identity change of its
+ * own, so the marker would be lost on apply.
+ *
+ * This is a whole-plan interaction: `diffTables()` cannot detect it without
+ * also looking at index changes. Per the "whole-plan interactions belong in
+ * post-diff normalization" rule in the package CLAUDE.md, the restoration
+ * lives here.
+ *
+ * Insertion is idempotent: if `diffTables()` already emitted the same
+ * `AlterTableSetReplicaIdentity` for this table (e.g. when the user is also
+ * switching the replica-identity index name in the same migration), no
+ * duplicate is added.
+ */
+function restoreReplicaIdentityAfterIndexReplace(changes, branchTables) {
+    // Build the index-stable-id → owning-table map from branch state. Only
+    // tables in 'i' mode contribute, and only those whose configured index name
+    // is non-null (the extractor returns null for any other mode).
+    const replicaIdentityIndexToTable = new Map();
+    for (const table of Object.values(branchTables)) {
+        if (table.replica_identity !== "i" || !table.replica_identity_index) {
+            continue;
+        }
+        const indexId = stableId.index(table.schema, table.name, table.replica_identity_index);
+        replicaIdentityIndexToTable.set(indexId, table);
+    }
+    if (replicaIdentityIndexToTable.size === 0)
+        return changes;
+    // Find the indexes that are both dropped AND created in this plan. A pure
+    // drop or a pure create is handled by `diffTables()` directly (the table's
+    // replica_identity / replica_identity_index fields will have changed). The
+    // hole is specifically the drop+create pair that recreates the same name.
+    const droppedIndexIds = new Set();
+    const createdIndexIds = new Set();
+    for (const change of changes) {
+        if (change instanceof DropIndex) {
+            droppedIndexIds.add(change.index.stableId);
+        }
+        else if (change instanceof CreateIndex) {
+            createdIndexIds.add(change.index.stableId);
+        }
+    }
+    const replacedIndexIds = new Set();
+    for (const id of droppedIndexIds) {
+        if (createdIndexIds.has(id) && replicaIdentityIndexToTable.has(id)) {
+            replacedIndexIds.add(id);
+        }
+    }
+    if (replacedIndexIds.size === 0)
+        return changes;
+    // Skip tables for which `diffTables()` already emitted a replica-identity
+    // setter — re-emitting would produce a redundant ALTER TABLE (harmless on
+    // apply, but noisy in plan output).
+    const tablesWithExistingReplicaIdentitySetter = new Set();
+    for (const change of changes) {
+        if (change instanceof AlterTableSetReplicaIdentity) {
+            tablesWithExistingReplicaIdentitySetter.add(change.table.stableId);
+        }
+    }
+    // Insert one `AlterTableSetReplicaIdentity` per replaced index, immediately
+    // after the matching `CreateIndex`. The change's `requires` already names
+    // both the table and the recreated index, so the topo sort orders it
+    // correctly relative to the surrounding DDL.
+    const result = [];
+    for (const change of changes) {
+        result.push(change);
+        if (!(change instanceof CreateIndex) ||
+            !replacedIndexIds.has(change.index.stableId)) {
+            continue;
+        }
+        const table = replicaIdentityIndexToTable.get(change.index.stableId);
+        if (!table)
+            continue;
+        if (tablesWithExistingReplicaIdentitySetter.has(table.stableId))
+            continue;
+        result.push(new AlterTableSetReplicaIdentity({
+            table,
+            mode: "i",
+            indexName: table.replica_identity_index,
+        }));
+        // Mark as emitted so a second replaced index on the same table — if that
+        // ever arises — doesn't double-emit.
+        tablesWithExistingReplicaIdentitySetter.add(table.stableId);
+    }
+    return result;
+}
+/**
+ * Apply structural rewrites to the change list that are only obvious once
+ * every object diff has been collected. This pass does NOT prevent dependency
+ * cycles — that responsibility now lives in the sort phase, where
+ * `sortPhaseChanges` invokes `tryBreakCycleByChangeInjection` lazily on cycles
+ * that edge filtering can't break (FK SCC of dropped tables,
+ * AlterPublicationDropTables ↔ AlterTableDropColumn, …).
+ *
+ * Concretely, this pass:
+ *
+ * - Prunes `AlterTableDropColumn(T.*)` / `AlterTableDropConstraint(T.*)`
+ *   changes that are made redundant by an expansion-emitted
+ *   `DropTable(T) + CreateTable(T)` pair. Without this, the apply phase
+ *   would try to drop a column that no longer exists in the freshly
+ *   recreated table.
+ * - Dedupes duplicate `AlterTableAddConstraint` /
+ *   `AlterTableValidateConstraint` / `CreateCommentOnConstraint` changes
+ *   produced when `diffTables()` and `expandReplaceDependencies()` both
+ *   emit the same constraint operation for a replaced table. Last write
+ *   wins so the expansion's emission survives.
+ * - Re-emits `ALTER TABLE ... REPLICA IDENTITY USING INDEX <idx>` after any
+ *   `DropIndex(idx) + CreateIndex(idx)` pair where `idx` is the replica
+ *   identity index of a branch table — Postgres silently clears the marker
+ *   when the underlying index is dropped, and `CREATE INDEX` cannot restore
+ *   it.
+ *
+ * Object-local PostgreSQL semantics (for example owned-sequence cascades)
+ * stay in the corresponding `diff*` function instead of this pass.
+ */
+export function normalizePostDiffChanges({ changes, replacedTableIds = new Set(), branchTables = {}, }) {
+    const restoredChanges = restoreReplicaIdentityAfterIndexReplace(changes, branchTables);
+    const dedupedChanges = dropReplacedTableDuplicateConstraintChanges(restoredChanges, replacedTableIds);
+    if (replacedTableIds.size === 0)
+        return dedupedChanges;
+    return dedupedChanges.filter((change) => !isSupersededByTableReplacement(change, replacedTableIds));
+}

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-normalization.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/sort-changes.js

@@ -12,6 +12,7 @@
  */
 import debug from "debug";
 import { generateCustomConstraints } from "./custom-constraints.js";
+import { tryBreakCycleByChangeInjection } from "./cycle-breakers.js";
 import { printDebugGraph } from "./debug-visualization.js";
 const debugGraph = debug("pg-delta:graph");
 import { filterEdgesForCycleBreaking, getEdgesInCycle, } from "./dependency-filter.js";
@@ -20,6 +21,13 @@ import { dedupeEdges } from "./graph-utils.js";
 import { logicalSort } from "./logical-sort.js";
 import { findCycle, formatCycleError, performStableTopologicalSort, } from "./topological-sort.js";
 import { getExecutionPhase } from "./utils.js";
+// `sortPhaseChanges` caps the change-injection breaker at one round per
+// node in the initial phase: there can never be more disjoint unbreakable
+// cycles than there are change nodes (each cycle has ≥ 2 distinct nodes).
+// The cap exists only to surface a buggy breaker as `CycleError` instead
+// of an infinite loop — the actual loop-protection guarantee comes from
+// `breakerRoundSignatures`, which throws the moment the same cycle
+// reappears after a break.
 /**
  * Sort changes using dependency information from catalogs and custom constraints.
  *
@@ -63,20 +71,38 @@ function sortChangesByPhasedGraph(catalogContext, changeList) {
     return [...sortedDropPhase, ...sortedCreateAlterPhase];
 }
 /**
- * Sort changes within a phase using Constraints derived from all dependency sources.
+ * Normalize a cycle by rotating it to start with the smallest node index, so
+ * cycles that loop through the same nodes in the same direction compare equal
+ * regardless of where DFS happened to enter them.
+ */
+function normalizeCycle(cycleNodeIndexes) {
+    if (cycleNodeIndexes.length === 0)
+        return "";
+    const minIndex = Math.min(...cycleNodeIndexes);
+    const minIndexPos = cycleNodeIndexes.indexOf(minIndex);
+    const rotated = [
+        ...cycleNodeIndexes.slice(minIndexPos),
+        ...cycleNodeIndexes.slice(0, minIndexPos),
+    ];
+    return rotated.join(",");
+}
+/**
+ * One attempt at sorting `phaseChanges`. Builds the graph from scratch,
+ * runs the iterative edge-removal cycle handler, and either returns a
+ * topologically sorted list or reports an unbreakable cycle so the caller
+ * can decide whether to dispatch a change-injection breaker.
  *
  * Algorithm:
- * 1. Build graph data (change sets and reverse indexes)
- * 2. Convert all sources to Constraints (catalog, explicit, custom constraints)
- * 3. Convert Constraints to edges
- * 4. Iteratively detect and break cycles (deduplicate edges, detect cycles, filter problematic edges)
- * 5. Perform stable topological sort on the acyclic graph
+ * 1. Build graph data (change sets and reverse indexes).
+ * 2. Convert all sources to Constraints (catalog, explicit, custom).
+ * 3. Convert Constraints to edges.
+ * 4. Iteratively detect and break cycles by removing weak edges.
+ * 5. Perform stable topological sort on the acyclic graph.
  *
- * In DROP phase, edges are inverted so drops run in reverse dependency order.
+ * In DROP phase, edges are inverted so drops run in reverse dependency
+ * order.
  */
-function sortPhaseChanges(phaseChanges, dependencyRows, options = {}) {
-    if (phaseChanges.length <= 1)
-        return phaseChanges;
+function attemptSortRound(phaseChanges, dependencyRows, options) {
     // Step 1: Build graph data structures
     const graphData = buildGraphData(phaseChanges, options);
     // Step 2: Convert all sources to Constraints
@@ -90,50 +116,31 @@ function sortPhaseChanges(phaseChanges, dependencyRows, options = {}) {
     ];
     // Step 3: Convert constraints to edges and deduplicate immediately
     let edges = dedupeEdges(convertConstraintsToEdges(allConstraints, options));
-    // Step 4: Iteratively detect and break cycles
-    // Track cycles we've seen to detect when filtering fails to break a cycle.
-    // The only way we loop indefinitely is if we encounter a cycle we've already seen,
-    // which means filtering didn't break it. Otherwise, we continue until all cycles are broken.
+    // Step 4: Iteratively detect and break cycles by edge filtering.
+    // We loop until no cycles remain OR we see the same cycle twice — the
+    // latter signals that edge filtering exhausted itself. At that point
+    // the caller may dispatch a change-injection breaker; if no breaker
+    // matches, the original throw path runs.
     const seenCycles = new Set();
-    /**
-     * Normalize a cycle by rotating it to start with the smallest node index.
-     * This allows us to compare cycles regardless of where they start.
-     */
-    function normalizeCycle(cycleNodeIndexes) {
-        if (cycleNodeIndexes.length === 0)
-            return "";
-        const minIndex = Math.min(...cycleNodeIndexes);
-        const minIndexPos = cycleNodeIndexes.indexOf(minIndex);
-        const rotated = [
-            ...cycleNodeIndexes.slice(minIndexPos),
-            ...cycleNodeIndexes.slice(0, minIndexPos),
-        ];
-        return rotated.join(",");
-    }
     while (true) {
-        // Edge deduplication moved outside loop
         const edgePairs = edgesToPairs(edges);
-        // Detect cycles
         const cycleNodeIndexes = findCycle(phaseChanges.length, edgePairs);
-        if (!cycleNodeIndexes) {
-            // No cycles found, we're done
+        if (!cycleNodeIndexes)
             break;
-        }
-        // Normalize cycle to check if we've seen it before
         const cycleSignature = normalizeCycle(cycleNodeIndexes);
         if (seenCycles.has(cycleSignature)) {
-            // We've seen this cycle before - filtering didn't break it
-            // Get edges involved in the cycle for detailed error message
-            const cycleEdges = getEdgesInCycle(cycleNodeIndexes, edges);
-            throw new Error(formatCycleError(cycleNodeIndexes, phaseChanges, cycleEdges));
+            // Edge filtering can't break this cycle. Report it back to the
+            // caller so it can try change-injection before throwing.
+            return {
+                kind: "unbreakable",
+                cycleNodeIndexes,
+                cycleEdges: getEdgesInCycle(cycleNodeIndexes, edges),
+            };
         }
-        // Track this cycle
         seenCycles.add(cycleSignature);
-        // Filter only edges involved in the cycle to break it
         edges = filterEdgesForCycleBreaking(edges, cycleNodeIndexes, phaseChanges, graphData);
     }
     const finalEdgePairs = edgesToPairs(edges);
-    // Debug visualization
     if (debugGraph.enabled) {
         printDebugGraph(phaseChanges, graphData, finalEdgePairs, dependencyRows, allConstraints);
     }
@@ -143,5 +150,52 @@ function sortPhaseChanges(phaseChanges, dependencyRows, options = {}) {
         // This should never happen if findCycle returned null, but guard anyway
         throw new Error("CycleError: dependency graph contains a cycle");
     }
-    return topologicalOrder.map((changeIndex) => phaseChanges[changeIndex]);
+    return {
+        kind: "sorted",
+        sorted: topologicalOrder.map((changeIndex) => phaseChanges[changeIndex]),
+    };
+}
+/**
+ * Sort changes within a phase. Tries `attemptSortRound`; on an unbreakable
+ * cycle, dispatches to `tryBreakCycleByChangeInjection`, retries with the
+ * rewritten changes, and bails after `MAX_CYCLE_BREAKER_ROUNDS` to surface
+ * a buggy breaker as `CycleError` instead of an infinite loop.
+ *
+ * Best case (no cycles, the vast majority of plans): one round, no
+ * change-injection breaker code runs at all.
+ */
+function sortPhaseChanges(initialPhaseChanges, dependencyRows, options = {}) {
+    if (initialPhaseChanges.length <= 1)
+        return initialPhaseChanges;
+    let phaseChanges = initialPhaseChanges;
+    const breakerRoundSignatures = new Set();
+    // `attemptSortRound` returns at most one unbreakable cycle per call,
+    // so a phase with K independent unbreakable cycles needs K+1 rounds.
+    // Every cycle contains ≥ 2 distinct change nodes, so the maximum
+    // possible value of K is `floor(initialPhaseChanges.length / 2)` —
+    // using `initialPhaseChanges.length` itself is therefore a real upper
+    // bound with one round of slack (and matches the early-return guard
+    // above, which already excluded length-0 and length-1 phases).
+    const maxRounds = initialPhaseChanges.length;
+    for (let round = 0; round <= maxRounds; round++) {
+        const result = attemptSortRound(phaseChanges, dependencyRows, options);
+        if (result.kind === "sorted")
+            return result.sorted;
+        // Edge filtering hit an unbreakable cycle. Try the change-injection
+        // breakers (FK pattern, publication↔column pattern). If none matches,
+        // throw with the same diagnostic the original code emitted.
+        const broken = tryBreakCycleByChangeInjection(result.cycleNodeIndexes, phaseChanges);
+        if (broken === null) {
+            throw new Error(formatCycleError(result.cycleNodeIndexes, phaseChanges, result.cycleEdges));
+        }
+        // Loop guard: if the same cycle node-set re-appears after a break,
+        // the breaker isn't making progress. Throw with full context.
+        const signature = normalizeCycle(result.cycleNodeIndexes);
+        if (breakerRoundSignatures.has(signature)) {
+            throw new Error(formatCycleError(result.cycleNodeIndexes, phaseChanges, result.cycleEdges));
+        }
+        breakerRoundSignatures.add(signature);
+        phaseChanges = broken;
+    }
+    throw new Error(`CycleError: change-injection breaker exceeded ${maxRounds} rounds (one per node in the phase) — likely a buggy breaker rule`);
 }