ADR-010: Alembic Retention Through 0.6.x and Rust Schema Cutover

Status: accepted. The schema-cutover mechanism is to be built and made opt-in during the 0.6.x point releases (epic 2Z3Y46); retiring the Alembic dependency and the legacy conversion is gated to a 0.7 release.

Partially superseded: the 0.6.x retention posture was retired 2026-09-15 by ADR-052

Context

degenbot’s database schema is, today, Alembic-owned: the canonical schema lives in src/degenbot/migrations/versions/, alembic_version is the authority table, and production databases are stamped at an Alembic revision. The Rust core (degenbot-db) reads these databases but does not write schema to them — DegenbotDb::open reports one of four states (migrate.rs::ensure_schema):

• AlembicCurrent — alembic_version.version_num == ALEMBIC_HEAD. The Rust core honors PRAGMA query_only=on and reads.

• AlembicStale { head, expected } — older revision. Refuse; the Python Alembic path must advance the stamp.

• FreshStandalone { schema_version } — empty file. Apply the embedded SCHEMA_HEAD DDL, stamp _degenbot_db_schema_version with RUST_SCHEMA_VERSION.

• Unrecognized — has tables, no alembic_version. Refuse (a foreign SQLite file passed by mistake).

This hybrid period is deliberate (migrate.rs doc comment): the Rust core never downgrades or forwards an Alembic DB. The end state, however, is that the schema is Rust-owned: future schema bumps are Rust ALTER scripts tracked by RUST_SCHEMA_VERSION, and the alembic_version table is gone.

The problem is that there is no path from Alembic ownership to Rust ownership. A DB that has crossed the boundary (tables present, alembic_version dropped, _degenbot_db_schema_version stamped) is — under today’s ensure_schema — indistinguishable from a foreign SQLite file: alembic_version is absent, table_count > 0, so it returns Unrecognized and DegenbotDb::open refuses. Worse, even a FreshStandalone DB created by the Rust core cannot be re-opened: the second open sees no alembic_version, table_count > 0, and also returns Unrecognized.

Closing this gap is not a local fix; it is a schema-ownership transition that must be coordinated with releases, because pip users on production Alembic-stamped databases must be able to upgrade through the final Alembic revision before ownership flips. Dropping the Alembic dependency prematurely strands those users on a database the Rust core refuses to open.

Decision

Two end-states, version-gated, with the cutover mechanism built and proven during 0.6.x and the Alembic retirement executed only in 0.7.

1. During 0.6.x — Alembic retained, cutover opt-in

• The DB stays Alembic-stamped by default; the Rust core continues to read via query_only=on on the AlembicCurrent path.

• The schema-cutover operation is built in degenbot-db and surfaced as an explicit, opt-in CLI command, degenbot database cutover. Nothing auto-runs cutover on DegenbotDb::open. Rationale: a one-way schema- ownership flip on first open is surprising and hard to roll back; an explicit command lets users cutover deliberately, and lets a pytest prove the boundary deterministically.

• ensure_schema gains a fifth state, RustOwned { schema_version }, for a DB with tables present, no alembic_version, and a stamped _degenbot_db_schema_version. This subsumes the re-opened FreshStandalone case (it now reads back as RustOwned rather than Unrecognized) and covers the post-cutover state. A foreign SQLite file (tables, no alembic, no _degenbot_db_schema_version) remains Unrecognized.

• convert_alembic_to_rust_owned(conn) is the one operation that writes schema to an otherwise-Alembic DB, and only because the DB is leaving Alembic ownership: verify alembic_version.version_num == ALEMBIC_HEAD, drop the alembic_version table, stamp _degenbot_db_schema_version with RUST_SCHEMA_VERSION. Refuse AlembicStale (upgrade via Alembic first) and Unrecognized.

2. The cutover state machine

ensure_schema decisions, enumerated exhaustively over the three observable predicates (tables_present?, alembic_version?, _degenbot_db_schema_version?):

tables	alembic_version	_degenbot_db_schema_version	state
0	—	—	FreshStandalone (apply DDL + stamp; returns FreshStandalone)
>0	at ALEMBIC_HEAD	—	AlembicCurrent
>0	older than head	—	AlembicStale
>0	absent	present	RustOwned
>0	absent	absent	Unrecognized
0	present	—	Unrecognized (alembic_version with no tables — foreign)

The predicate tables_present? counts non-sqlite_% tables. The _degenbot_db_schema_version table is private to the Rust core and is not counted as a content table (it is filtered, like sqlite_%).

After FreshStandalone applies its DDL on first open, the next open of that file reads back as RustOwned (tables present, no alembic, version table stamped) — FreshStandalone is the one-shot “I just created this” report; RustOwned is the steady state for any Rust-owned DB thereafter.

3. Several 0.6.x point releases ship the cutover path

The cutover command and the RustOwned branch ship across 0.6.x point releases so that every pip user can upgrade a stale database through the final Alembic revision and then cutover at a time of their choosing. No 0.6.x release removes Alembic or forces cutover.

4. 0.7 — retirement

The actual retirement is gated to a 0.7 release and tracked as the blocked task JFFQV2. Only in 0.7 may an agent touch the forbidden-until-0.7 kill list (below). The retirement:

• drops the alembic and (if nothing else uses it) sqlalchemy dependencies from pyproject.toml;

• deletes src/degenbot/migrations/;

• removes the ALEMBIC_HEAD constant in rust/crates/foundation/degenbot-db/src/schema.rs and the alembic_version-reading branch of ensure_schema;

• removes the database upgrade Alembic fall-back path (the DatabaseSchemaStale → alembic.command.upgrade shell);

• decides whether DegenbotDb::open auto-converts a stale-but-recognized legacy shape or refuses (resolved at 0.7 design time).

Forbidden-until-0.7 kill list

No change before the 0.7 retirement task (JFFQV2) may delete or stub any of:

• src/degenbot/migrations/ (the Alembic migration scripts);

• the alembic and sqlalchemy entries in pyproject.toml;

• DatabaseSessionManager and the SQLAlchemy src/degenbot/database/models/ package;

• the ALEMBIC_HEAD constant in rust/crates/foundation/degenbot-db/src/schema.rs;

• the alembic_version-reading branch of rust/crates/foundation/degenbot-db/src/migrate.rs::ensure_schema;

• the PRAGMA query_only=on setting on the AlembicCurrent path in DegenbotDb::open.

An import falling out of use is not permission to delete it. If a 0.6.x task makes an Alembic/SQLAlchemy symbol unused, the task leaves it in place and notes the orphaned symbol in its completion summary; removal is the 0.7 retirement task’s exclusive responsibility.

Considered options (rejected alternatives)

• Auto-cutover on open during 0.6.x. Have DegenbotDb::open silently convert an AlembicCurrent DB to RustOwned on first open. Rejected: a one-way schema-ownership flip (drops alembic_version, switches the authority table) is surprising, hard to roll back, and impossible for a pytest to exercise deterministically against an arbitrary production DB. An explicit degenbot database cutover command makes the transition a deliberate user action and a precisely testable boundary.

• Retire Alembic in 0.6.x (skip the hybrid releases). Build the cutover and drop Alembic in the same release train. Rejected: pip users on production Alembic-stamped databases need at least one release that ships both the cutover path and the Alembic upgrade path, so they can move a stale database to ALEMBIC_HEAD and then cutover. Removing Alembic in the same release that introduces the cutover strands anyone whose database is not yet at head.

• Keep Alembic indefinitely. Treat the hybrid period as permanent. Rejected: the long-term vision (AGENTS.md) is that the Rust core owns everything a bot needs, including schema. Alembic is a Python build/runtime concern; a standalone cargo add degenbot consumer has no Alembic. The cutover mechanism is how the project gets to that end state without stranding existing databases.

Consequences

• 0.6.x releases are dual-path. Both the Alembic upgrade path and the Rust cutover path ship. Users may upgrade through the final Alembic revision and cutover to Rust ownership, in either order across releases.

• ensure_schema gains RustOwned. Both the post-cutover DB and the re-opened FreshStandalone DB report RustOwned; FreshStandalone remains the one-shot “just created” report. Unrecognized is now unambiguous: tables, no alembic, no _degenbot_db_schema_version.

• The cutover is the one Rust-writes-schema-to-an-Alembic-DB operation. Documented as an exception in convert_alembic_to_rust_owned’s doc comment; it is bounded to the boundary-crossing moment and never runs on the AlembicCurrent read path.

• 0.7 retirement is the only deletion point. Mid-0.6.x cleanups observe the forbidden-until-0.7 kill list; an orphaned-but-still-needed import stays until 0.7.

• The cutover boundary is pytest-proven. A test migrates a stale Alembic-tagged database through ALEMBIC_HEAD to RustOwned, asserting no alembic_version table remains and the data round-trips. That test is the contract artifact for the whole transition.

Related

• ADR-005 (Polars-inspired three-layer architecture) — the standalone- Rust-core constraint that makes Rust-owned schema a first-class requirement; a cargo add degenbot consumer has no Alembic by construction.

• docs/adr/ADR-003-botcore-state-layer.md — Bot as the single Rust state owner; schema ownership is the persistence half of the same principle.

• rust/crates/foundation/degenbot-db/src/migrate.rs — ensure_schema and the state machine this ADR extends; the doc comment there already names the hybrid period as a “HARD REQUIREMENT.”

• Epic 2Z3Y46 (its .ergo/plan-cli-db-migration.md plan file has since been removed) — the task graph that builds and proves the cutover path during 0.6.x; the forbidden-until-0.7 kill list above is mirrored in that epic’s body and in AGENTS.md.