fix: sort hybrid migrations after their target to prevent multiple heads (#14)

When two branches fork from the same dynamic head and one adds a
dynamic migration while the other adds a hybrid (static with hardcoded
down_revision), the first-merged dynamic and the later-merged hybrid
both pointed to the same predecessor, creating a fork and MultipleHeads.

Fix by sorting hybrids by their target's git_sequence instead of their
own, placing them immediately after their target in the chain.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: jd

alembic_git_revisions/_chain.py

@@ -215,20 +215,40 @@ def _build_dynamic_chain(
     """Build ``{revision: down_revision}`` for dynamic migrations.
 
     Dynamic files are sorted by ``(git_sequence, filename)`` and chained
-    linearly after *static_head*.
-
-    Hybrid files (static files whose ``down_revision`` points to a
-    dynamic revision) participate in the ordering so that subsequent
-    dynamic files chain after them, but they don't get entries in the
-    returned dict since they already have a hardcoded ``down_revision``.
+    linearly after *static_head*.  Hybrid files (static files whose
+    ``down_revision`` points to a dynamic revision) are placed
+    immediately after their target so that dynamic migrations added by
+    concurrent branches chain after the hybrid, not to the same target
+    (which would create a fork / multiple heads).
+
+    Hybrids don't get entries in the returned dict since they already
+    have a hardcoded ``down_revision``.
     """
     dynamic_revisions = {f.revision for f in files if f.is_dynamic}
 
     dynamic_participants: list[MigrationFile] = [
         f for f in files if f.is_dynamic or f.static_down_revision in dynamic_revisions
     ]
 
-    dynamic_participants.sort(key=lambda f: (f.git_sequence, f.filename))
+    # O(1) lookup for each participant's git_sequence by revision.
+    seq_by_rev = {f.revision: f.git_sequence for f in dynamic_participants}
+
+    # Map each hybrid's target revision to that target's git_sequence so
+    # the hybrid sorts right after its target (not at its own commit time).
+    target_seq = {
+        f.static_down_revision: seq_by_rev.get(f.static_down_revision, f.git_sequence)
+        for f in dynamic_participants
+        if not f.is_dynamic and f.static_down_revision
+    }
+
+    def _sort_key(f: MigrationFile) -> tuple[int, int, str]:
+        if not f.is_dynamic and f.static_down_revision in target_seq:
+            # Place hybrid right after its target (the 1 ensures it
+            # sorts after the target itself at the same git_sequence).
+            return (target_seq[f.static_down_revision], 1, f.filename)
+        return (f.git_sequence, 0, f.filename)
+
+    dynamic_participants.sort(key=_sort_key)
 
     chain: dict[str, str] = {}
     prev_revision = static_head

tests/test_chain.py

@@ -407,6 +407,64 @@ def test_git_commit_order_with_relative_nested_path(
     assert result.index("aaaa_first.py") < result.index("bbbb_second.py")
 
 
+def test_dynamic_inserted_before_hybrid_no_multiple_heads(
+    tmp_path: pathlib.Path,
+) -> None:
+    """A dynamic migration added before a hybrid must not create multiple heads.
+
+    Reproduces a production failure: two branches fork from the same dynamic
+    head.  Branch A adds a dynamic migration; branch B adds a static
+    migration (hybrid) pointing to the same head.  Branch A merges first,
+    so the new dynamic migration appears *before* the hybrid in git order.
+
+    Without a fix, both the new dynamic migration and the hybrid point to
+    the same predecessor, creating a fork and ``MultipleHeads``.
+    """
+    versions_dir = tmp_path / "versions"
+    versions_dir.mkdir()
+
+    # Static root
+    (versions_dir / "aaaa_root.py").write_text(
+        'revision = "aaaa"\ndown_revision = None\n',
+    )
+    # Dynamic migration (the previous head before the two branches)
+    (versions_dir / "bbbb_dynamic.py").write_text(
+        "from alembic_git_revisions import get_down_revision\n"
+        'revision = "bbbb"\n'
+        "down_revision = get_down_revision(revision)\n",
+    )
+    # Dynamic migration added on branch A (merged first)
+    (versions_dir / "cccc_dynamic.py").write_text(
+        "from alembic_git_revisions import get_down_revision\n"
+        'revision = "cccc"\n'
+        "down_revision = get_down_revision(revision)\n",
+    )
+    # Hybrid: static migration added on branch B, hardcoded to the old head.
+    # Merged *after* branch A, so it appears last in git order.
+    (versions_dir / "dddd_hybrid.py").write_text(
+        'revision = "dddd"\ndown_revision = "bbbb"\n',
+    )
+
+    git_order = [
+        "aaaa_root.py",
+        "bbbb_dynamic.py",
+        "cccc_dynamic.py",  # branch A merged first
+        "dddd_hybrid.py",  # branch B merged second
+    ]
+
+    with mock.patch.object(
+        _chain,
+        "_get_git_commit_order",
+        return_value=git_order,
+    ):
+        chain = _chain._build_chain_from_git(versions_dir)
+
+    # dddd hardcodes down_revision="bbbb", so it doesn't need a chain entry.
+    # cccc must chain AFTER dddd (not to bbbb) to avoid multiple heads.
+    # Correct chain: aaaa -> bbbb -> dddd(hybrid) -> cccc
+    assert chain == {"bbbb": "aaaa", "cccc": "dddd"}
+
+
 def test_auto_discover_versions_dir(tmp_path: pathlib.Path) -> None:
     """get_down_revision auto-discovers versions_dir from caller's location."""
     versions_dir = tmp_path / "versions"