fix: sort hybrid migrations after their target to prevent multiple heads

[jd]

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

[mergify]

Merge Protections

Your pull request matches the following merge protections and will not be merged until they are valid.

🟢 🤖 Continuous Integration

Wonderful, this rule succeeded.

• all of:
  • check-success=all-greens

🟢 👀 Review Requirements

Wonderful, this rule succeeded.

• any of:
  • #approved-reviews-by>=1
  • author = dependabot[bot]
  • author = mergify-ci-bot

🟢 Enforce conventional commit

Wonderful, this rule succeeded.

Make sure that we follow https://www.conventionalcommits.org/en/v1.0.0/

• title ~= ^(fix|feat|docs|style|refactor|perf|test|build|ci|chore|revert)(?:\(.+\))?:

🟢 🔎 Reviews

Wonderful, this rule succeeded.

• #changes-requested-reviews-by = 0
• #review-requested = 0
• #review-threads-unresolved = 0

🟢 📕 PR description

Wonderful, this rule succeeded.

• body ~= (?ms:.{48,})

[Copilot]

Pull request overview

This PR fixes an Alembic migration ordering edge case where a later-merged “hybrid” (static down_revision pointing to a dynamic revision) could cause the dynamic chain builder to produce multiple heads. The fix adjusts ordering so hybrids are placed immediately after their dynamic target, preventing concurrent-branch insertions from forking the chain.

Changes:

• Add a regression test covering the “dynamic inserted before hybrid” multiple-heads scenario.
• Update dynamic participant sorting so hybrids are ordered by their target’s git_sequence rather than their own.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
alembic_git_revisions/_chain.py	Changes sort order in _build_dynamic_chain to place hybrid migrations right after their dynamic target revision.
tests/test_chain.py	Adds a regression test ensuring the chain avoids multiple heads when a dynamic migration appears in git order before a later-merged hybrid.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[mergify]

Merge Queue Status

Rule: default

---

• ✅ Entered queue — 2026-03-03 16:58 UTC
• ✅ Checks passed · in-place
• ✅ Merged — 2026-03-03 16:58 UTC · at 74e157cdecbc90f6ffe97abad30a26dac0d2f216

This pull request spent 8 seconds in the queue, with no time running CI.

Required conditions to merge

• all of [🛡 Merge Protections rule Enforce conventional commit]:
  • title ~= ^(fix|feat|docs|style|refactor|perf|test|build|ci|chore|revert)(?:\(.+\))?:
    • fix: sort hybrid migrations after their target to prevent multiple heads #14
• all of [🛡 Merge Protections rule 👀 Review Requirements]:
  • any of:
    • #approved-reviews-by>=1
      • fix: sort hybrid migrations after their target to prevent multiple heads #14
    • author = dependabot[bot]
      • fix: sort hybrid migrations after their target to prevent multiple heads #14
    • author = mergify-ci-bot
      • fix: sort hybrid migrations after their target to prevent multiple heads #14
• all of [🛡 Merge Protections rule 📕 PR description]:
  • body ~= (?ms:.{48,})
    • fix: sort hybrid migrations after their target to prevent multiple heads #14
• all of [🛡 Merge Protections rule 🔎 Reviews]:
  • #changes-requested-reviews-by = 0
    • fix: sort hybrid migrations after their target to prevent multiple heads #14
  • #review-requested = 0
    • fix: sort hybrid migrations after their target to prevent multiple heads #14
  • #review-threads-unresolved = 0
    • fix: sort hybrid migrations after their target to prevent multiple heads #14
• all of [🛡 Merge Protections rule 🤖 Continuous Integration]:
  • all of:
    • check-success=all-greens