feat(core): name new Alembic revisions by sequential schema version

[phernandez]

Why

basicmachines-co/basic-memory-cloud#2355 moves tenant migrations out of band, and each tenant records an ordered schema version. Random hex revision IDs only say "different". A sequential number says which schema is newer.

What

• Every revision after z9a0b1c2d3e4 is named by its schema version, zero-padded to four digits: "0040", "0041", and so on, so migration files sort in version order. Each one revises the previous one.
• migrations.schema_version(revision) returns the number of revisions applied up to and including that revision. z9a0b1c2d3e4 is 39. For numbered revisions it equals int(revision) ("0040" is 40). It raises ValueError for unknown IDs, including prefixes such as "z9a" that Alembic would otherwise resolve.
• migrations.next_revision_id(script) returns head + 1 and raises if the graph has more than one head.
• env.py sets the revision ID through Alembic's process_revision_directives hook (assign_sequential_revision_ids), in both the online and offline context.configure calls. alembic.ini sets revision_environment = true, because without it a plain alembic revision (no --autogenerate) never runs env.py (alembic/command.py) and writes a random ID. Both just migration and hand-written revisions therefore get the next number.
• LAST_UNNUMBERED_REVISION = "z9a0b1c2d3e4" marks where numbering starts. The older IDs are not all hex; many were hand-picked.
• Two open PRs off the same head both generate the same ID. A probe with two 0040 files shows Alembic warns Revision 0040 is present more than once and reports heads ['0040', '0040'], so the second PR fails the one-head test. The rule, now in AGENTS.md and the just migration comment, is to renumber your revision to the next ID and point its down_revision at the new head. Never add a merge revision once numbered revisions start; the tail test requires a linear chain. The one-head test and next_revision_id errors now give that advice instead of "add a merge revision".

Verification

• Probe run against the current Alembic: alembic revision --autogenerate on a temp database generated 0040_probe_padded_id.py with Revision ID: 0040, Revises: z9a0b1c2d3e4. A plain alembic revision -m ... also generated 0040. Without revision_environment it generated e1245b8670f9. Probe files were deleted.
• tests/test_migration_graph.py covers the hook: it assigns the next version on a real MigrationContext and fails fast without a script directory. It also covers the graph: one head, a contiguous, linear tail of exactly-four-digit IDs after z9a0b1c2d3e4, helper values, unknown IDs, a forked graph, and that alembic.ini keeps revision_environment on.
• just lint and just typecheck pass. tests/test_migration_graph.py + tests/test_alembic_env.py: 19 passed; alembic/migrations.py at 100% coverage.

Note: future migration modules start with a digit, so tests must load them with importlib.import_module rather than from basic_memory.alembic.versions import ....

🤖 Generated with Claude Code

https://claude.ai/code/session_01D36TJNafZfpQh99hu9JkTF

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-06T16:36:11.245853Z	8ad0230	New commits

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 29e2df7161

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Reject revisions that do not extend the sole head

When a developer uses the supported alembic revision --head <older-revision> --splice path, this hook assigns the next global schema ID without validating the generated directive's parent. alembic revision --help documents --head as selecting the base revision and --splice as allowing a non-head base; reproducing this with --head y8f9a0b1c2d3 --splice creates revision 0040 with down_revision = 'y8f9a0b1c2d3', leaving both 0040 and z9a0b1c2d3e4 as heads and violating the required linear numbered tail. Validate that each directive extends the sole current head and fail before writing the file.

AGENTS.md reference: AGENTS.md:L291-L296

Useful? React with 👍 / 👎.

[phernandez]

Confirmed and fixed in 8ad0230.

Probe before the fix: alembic revision -m x --head y8f9a0b1c2d3 --splice wrote 0040 revising y8f9a0b1c2d3, and alembic heads listed 0040 and z9a0b1c2d3e4.

assign_sequential_revision_ids now resolves each directive's head and raises ValueError before Alembic writes the file unless it is the single current head. The error tells you to build on the head. The CLI passes head=None when --head is omitted, and ScriptDirectory.generate_revision reads that as "head", so the hook resolves it the same way.

Probes after the fix: the splice is refused with no file written; plain alembic revision and --autogenerate still produce 0040 on z9a0b1c2d3e4. New tests cover the splice (y8f9a0b1c2d3) and base cases, and the accepted None / "head" / explicit-head cases. just lint, just typecheck and the migration tests (23) pass.