fix: handle newer db revisions during init

- detect when the installed shellbrain package is older than the database revision\n- report a clean blocked conflict from init and a friendly admin migrate error\n- bump version to 0.1.24

Author: cucupac

app/boot/migrations.py

@@ -3,9 +3,12 @@
 from __future__ import annotations
 
 from importlib.resources import as_file, files
+import importlib.metadata
 
 from alembic import command
 from alembic.config import Config
+from alembic.script import ScriptDirectory
+from alembic.script.revision import ResolutionError
 
 from app.boot.admin_db import get_admin_db_dsn, get_backup_dir, get_backup_mirror_dir, get_instance_mode_default
 from app.boot.db import get_optional_db_dsn
@@ -14,20 +17,26 @@
 from app.periphery.admin.privileges import reconcile_app_role_privileges
 
 
+class DatabaseRevisionAheadOfInstalledPackageError(RuntimeError):
+    """Raised when the target database revision is newer than the installed package knows about."""
+
+
 def upgrade_database(revision: str = "head") -> None:
     """Apply packaged Alembic migrations to the configured database."""
 
     config = Config()
     admin_dsn = get_admin_db_dsn()
-    if _database_has_shellbrain_objects(admin_dsn):
-        backup_and_verify_before_destructive_action(
-            admin_dsn=admin_dsn,
-            backup_root=get_backup_dir(),
-            mirror_root=get_backup_mirror_dir(),
-        )
-    config.set_main_option("sqlalchemy.url", admin_dsn)
     with as_file(files("app").joinpath("migrations")) as migrations_path:
         config.set_main_option("script_location", str(migrations_path))
+        script = ScriptDirectory.from_config(config)
+        if _database_has_shellbrain_objects(admin_dsn):
+            _assert_database_revision_is_known(admin_dsn=admin_dsn, script=script)
+            backup_and_verify_before_destructive_action(
+                admin_dsn=admin_dsn,
+                backup_root=get_backup_dir(),
+                mirror_root=get_backup_mirror_dir(),
+            )
+        config.set_main_option("sqlalchemy.url", admin_dsn)
         command.upgrade(config, revision)
     if fetch_instance_metadata(admin_dsn) is None:
         ensure_instance_metadata(
@@ -59,3 +68,48 @@ def _database_has_shellbrain_objects(admin_dsn: str) -> bool:
                 """
             )
             return bool(cur.fetchone()[0])
+
+
+def _assert_database_revision_is_known(*, admin_dsn: str, script: ScriptDirectory) -> None:
+    """Fail early with a user-facing error when the database revision is newer than this package."""
+
+    current_revision = _fetch_database_revision(admin_dsn)
+    if current_revision is None:
+        return
+    try:
+        script.get_revision(current_revision)
+    except ResolutionError as exc:
+        installed_version = _installed_shellbrain_version()
+        raise DatabaseRevisionAheadOfInstalledPackageError(
+            "Installed Shellbrain package "
+            f"({installed_version}) cannot manage database revision {current_revision}. "
+            "This database was likely migrated by a newer Shellbrain release than the one currently installed. "
+            "Upgrade Shellbrain to a build that includes this revision, then rerun `shellbrain init` or "
+            "`shellbrain admin migrate`."
+        ) from exc
+
+
+def _fetch_database_revision(admin_dsn: str) -> str | None:
+    """Return the current alembic revision when present."""
+
+    import psycopg
+
+    try:
+        with psycopg.connect(admin_dsn.replace("+psycopg", "")) as conn:
+            with conn.cursor() as cur:
+                cur.execute("SELECT version_num FROM alembic_version")
+                row = cur.fetchone()
+    except psycopg.Error:
+        return None
+    if row is None or row[0] is None:
+        return None
+    return str(row[0])
+
+
+def _installed_shellbrain_version() -> str:
+    """Return the installed Shellbrain package version when available."""
+
+    try:
+        return importlib.metadata.version("shellbrain")
+    except importlib.metadata.PackageNotFoundError:
+        return "dev"

app/periphery/admin/init.py

@@ -469,10 +469,13 @@ def _reconcile_database(config: MachineConfig) -> tuple[bool, MachineConfig]:
 def _apply_schema_migrations(config: MachineConfig) -> bool:
     """Apply packaged schema migrations to the configured Shellbrain database."""
 
-    from app.boot.migrations import upgrade_database
+    from app.boot.migrations import DatabaseRevisionAheadOfInstalledPackageError, upgrade_database
 
     before_revision = _fetch_schema_revision(config.database.admin_dsn)
-    upgrade_database()
+    try:
+        upgrade_database()
+    except DatabaseRevisionAheadOfInstalledPackageError as exc:
+        raise InitConflictError(str(exc)) from exc
     after_revision = _fetch_schema_revision(config.database.admin_dsn)
     return before_revision != after_revision
 

app/periphery/cli/main.py

@@ -714,9 +714,13 @@ def _run_admin_command(args: argparse.Namespace) -> int:
     """Execute one admin command."""
 
     if args.admin_command == "migrate":
-        from app.boot.migrations import upgrade_database
+        from app.boot.migrations import DatabaseRevisionAheadOfInstalledPackageError, upgrade_database
 
-        upgrade_database()
+        try:
+            upgrade_database()
+        except DatabaseRevisionAheadOfInstalledPackageError as exc:
+            print(str(exc), file=sys.stderr)
+            return 1
         print("Applied shellbrain schema migrations to head.")
         return 0
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "shellbrain"
-version = "0.1.23"
+version = "0.1.24"
 description = "Repo-scoped Shellbrain CLI with explicit evidence-backed writes."
 readme = "README.md"
 requires-python = ">=3.11"

tests/config/test_cli_surface.py

@@ -566,6 +566,27 @@ def test_admin_migrate_should_invoke_packaged_migration_runner(
     assert "Applied shellbrain schema migrations to head." in capsys.readouterr().out
 
 
+def test_admin_migrate_should_fail_cleanly_when_installed_package_is_older_than_database_revision(
+    monkeypatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """admin migrate should print one clear message when the database revision is newer than this package."""
+
+    from app.boot.migrations import DatabaseRevisionAheadOfInstalledPackageError
+
+    monkeypatch.setattr(
+        "app.boot.migrations.upgrade_database",
+        lambda: (_ for _ in ()).throw(
+            DatabaseRevisionAheadOfInstalledPackageError("Installed Shellbrain package (0.1.22) cannot manage database revision 20260415_0012.")
+        ),
+    )
+
+    exit_code = cli_main.main(["admin", "migrate"])
+
+    assert exit_code == 1
+    assert "cannot manage database revision 20260415_0012" in capsys.readouterr().err
+
+
 def test_operational_command_should_fail_cleanly_when_app_role_is_unsafe(
     monkeypatch,
     tmp_path: Path,

tests/operations/recovery/execution/test_init_bootstrap.py

@@ -131,6 +131,53 @@ def test_run_init_should_mark_repair_needed_when_blocked_by_conflict(tmp_path: P
     assert marked == ["managed port already claimed"]
 
 
+def test_run_init_should_block_cleanly_when_installed_package_is_older_than_database_revision(
+    tmp_path: Path,
+    monkeypatch,
+) -> None:
+    """init should report one blocked conflict instead of leaking an Alembic traceback on schema-version mismatch."""
+
+    from app.boot.migrations import DatabaseRevisionAheadOfInstalledPackageError
+
+    repo_root = tmp_path / "repo"
+    repo_root.mkdir()
+    home_root = tmp_path / "home"
+    initial_config = _machine_config(bootstrap_state="provisioning", last_error=None)
+    marked: list[str] = []
+
+    monkeypatch.setattr(init_module, "get_shellbrain_home", lambda: home_root)
+    monkeypatch.setattr(init_module, "_acquire_init_lock", lambda: nullcontext())
+    monkeypatch.setattr(init_module, "_ensure_dependencies", lambda: None)
+    monkeypatch.setattr(init_module, "try_load_machine_config", lambda: (initial_config, None))
+    monkeypatch.setattr(init_module, "save_machine_config", lambda config: None)
+    monkeypatch.setattr(init_module, "_migrate_machine_config", lambda config: config)
+    monkeypatch.setattr(init_module, "_ensure_managed_dependencies", lambda: None)
+    monkeypatch.setattr(init_module, "_ensure_managed_container", lambda config: False)
+    monkeypatch.setattr(init_module, "_wait_for_postgres", lambda admin_dsn: None)
+    monkeypatch.setattr(init_module, "_reconcile_database", lambda config: (False, config))
+    monkeypatch.setattr(
+        "app.boot.migrations.upgrade_database",
+        lambda: (_ for _ in ()).throw(
+            DatabaseRevisionAheadOfInstalledPackageError(
+                "Installed Shellbrain package (0.1.22) cannot manage database revision 20260415_0012."
+            )
+        ),
+    )
+    monkeypatch.setattr(init_module, "_mark_repair_needed", lambda message: marked.append(message))
+
+    result = init_module.run_init(
+        repo_root=repo_root,
+        repo_id_override=None,
+        register_repo_now=False,
+        skip_model_download=False,
+        skip_host_assets=True,
+    )
+
+    assert result.outcome == init_module.INIT_OUTCOME_BLOCKED_CONFLICT
+    assert result.lines == ["Installed Shellbrain package (0.1.22) cannot manage database revision 20260415_0012."]
+    assert marked == ["Installed Shellbrain package (0.1.22) cannot manage database revision 20260415_0012."]
+
+
 def test_run_init_should_defer_repo_registration_outside_any_repo(tmp_path: Path, monkeypatch) -> None:
     """plain init should succeed outside a repo and defer repo registration until first use."""