fix: require base_version on page content edits; add migration ledger.

Optimistic lock previously accepted updates with no base_version as a
"legacy client" escape hatch — which meant the check could be silently
bypassed. Now required whenever the payload touches content_md or title;
metadata-only edits (is_public toggle, parent/sort moves) still bypass.

Migrations move from ad-hoc ALTER-on-startup to a versioned ledger
(schema_migrations) with legacy-DB backfill by column inference. Partial
indexes move out of migration bodies into post-run invariants so fresh DBs
— where all migrations skip as "already applied" — still get them.

Bump VERSION to 0.0.3.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: PttCodingMan

VERSION

@@ -1 +1 @@
-0.0.2
+0.0.3

backend/app/database.py

@@ -1089,37 +1089,12 @@ async def init_db():
             await db.execute(statement)
     await db.commit()
 
-    # Migrate: add new user columns if missing
-    cols = await db.execute_fetchall("PRAGMA table_info(users)")
-    col_names = {c["name"] for c in cols}
-    if "display_name" not in col_names:
-        await db.execute("ALTER TABLE users ADD COLUMN display_name TEXT DEFAULT ''")
-    if "email" not in col_names:
-        await db.execute("ALTER TABLE users ADD COLUMN email TEXT DEFAULT ''")
-    if "deleted_at" not in col_names:
-        await db.execute("ALTER TABLE users ADD COLUMN deleted_at TIMESTAMP")
-    if "original_username" not in col_names:
-        await db.execute("ALTER TABLE users ADD COLUMN original_username TEXT")
-    await db.execute("CREATE INDEX IF NOT EXISTS idx_users_deleted ON users(deleted_at)")
-    await db.commit()
-
-    # Migrate: add new page columns if missing
-    page_cols = await db.execute_fetchall("PRAGMA table_info(pages)")
-    page_col_names = {c["name"] for c in page_cols}
-    if "version" not in page_col_names:
-        await db.execute("ALTER TABLE pages ADD COLUMN version INTEGER NOT NULL DEFAULT 1")
-    if "deleted_at" not in page_col_names:
-        await db.execute("ALTER TABLE pages ADD COLUMN deleted_at TIMESTAMP")
-        await db.execute("CREATE INDEX IF NOT EXISTS idx_pages_deleted ON pages(deleted_at)")
-    if "is_public" not in page_col_names:
-        await db.execute("ALTER TABLE pages ADD COLUMN is_public INTEGER NOT NULL DEFAULT 0")
-    # Create the partial index regardless — fresh DBs also need it, and
-    # we can't put it in SCHEMA_SQL because upgrading DBs run SCHEMA_SQL
-    # before the ALTER TABLE above.
-    await db.execute(
-        "CREATE INDEX IF NOT EXISTS idx_pages_public ON pages(slug) WHERE is_public = 1"
-    )
-    await db.commit()
+    # Versioned schema migrations. Handles both fresh DBs (nothing to do,
+    # SCHEMA_SQL already created everything) and upgrades from pre-migration
+    # deployments (backfills the ledger from observed schema). See
+    # app/migrations.py for the list and the rules for adding new ones.
+    from app.migrations import run_migrations
+    await run_migrations(db)
 
     # Ensure FTS5 index exists with the best available tokenizer.
     # If the tokenizer changed (e.g. unicode61 → trigram), the table is

backend/app/migrations.py

@@ -0,0 +1,196 @@
+"""Versioned schema migrations for JustWiki.
+
+Why not Alembic: JustWiki's core pitch is "single SQLite file, no external
+deps." Alembic would add a CLI, a versions/ directory, an alembic.ini, and a
+separate `alembic upgrade head` step in every deploy — extra weight that buys
+us very little on a schema this small. Instead we keep the work in-process:
+migrations are plain async functions in this module, identified by a
+monotonically increasing integer version, recorded in `schema_migrations`,
+and run once on startup by init_db().
+
+Ground rules:
+  * Append-only. Never renumber or rewrite a shipped migration — existing
+    deployments have already recorded the version.
+  * Each migration must be idempotent at the SQL level (IF NOT EXISTS, column
+    probes, etc.) so partial re-runs are safe if a crash happens mid-run.
+  * Use `run_migrations` as the single entry point. It returns the list of
+    versions applied in this invocation; callers can use that signal to
+    decide whether expensive follow-up work (full-text rebuild etc.) is
+    needed.
+"""
+import logging
+from typing import Awaitable, Callable
+
+import aiosqlite
+
+logger = logging.getLogger(__name__)
+
+MigrationFn = Callable[[aiosqlite.Connection], Awaitable[None]]
+Migration = tuple[int, str, MigrationFn]
+
+
+async def _column_exists(db: aiosqlite.Connection, table: str, col: str) -> bool:
+    rows = await db.execute_fetchall(f"PRAGMA table_info({table})")
+    return any(r["name"] == col for r in rows)
+
+
+# ── Migration functions ────────────────────────────────────────────────────
+# New migrations go at the bottom. Never renumber or edit a shipped migration.
+
+
+async def _m001_user_profile_columns(db: aiosqlite.Connection) -> None:
+    if not await _column_exists(db, "users", "display_name"):
+        await db.execute("ALTER TABLE users ADD COLUMN display_name TEXT DEFAULT ''")
+    if not await _column_exists(db, "users", "email"):
+        await db.execute("ALTER TABLE users ADD COLUMN email TEXT DEFAULT ''")
+
+
+async def _m002_user_soft_delete(db: aiosqlite.Connection) -> None:
+    if not await _column_exists(db, "users", "deleted_at"):
+        await db.execute("ALTER TABLE users ADD COLUMN deleted_at TIMESTAMP")
+    if not await _column_exists(db, "users", "original_username"):
+        await db.execute("ALTER TABLE users ADD COLUMN original_username TEXT")
+
+
+async def _m003_page_version_counter(db: aiosqlite.Connection) -> None:
+    if not await _column_exists(db, "pages", "version"):
+        await db.execute(
+            "ALTER TABLE pages ADD COLUMN version INTEGER NOT NULL DEFAULT 1"
+        )
+
+
+async def _m004_page_soft_delete(db: aiosqlite.Connection) -> None:
+    if not await _column_exists(db, "pages", "deleted_at"):
+        await db.execute("ALTER TABLE pages ADD COLUMN deleted_at TIMESTAMP")
+
+
+async def _m005_page_is_public(db: aiosqlite.Connection) -> None:
+    if not await _column_exists(db, "pages", "is_public"):
+        await db.execute(
+            "ALTER TABLE pages ADD COLUMN is_public INTEGER NOT NULL DEFAULT 0"
+        )
+
+
+MIGRATIONS: list[Migration] = [
+    (1, "user_profile_columns", _m001_user_profile_columns),
+    (2, "user_soft_delete", _m002_user_soft_delete),
+    (3, "page_version_counter", _m003_page_version_counter),
+    (4, "page_soft_delete", _m004_page_soft_delete),
+    (5, "page_is_public", _m005_page_is_public),
+]
+
+
+# ── Post-migration index invariants ────────────────────────────────────────
+# These indexes reference columns added by migrations, so they can't live in
+# SCHEMA_SQL (which runs first and would hit "no such column" on an upgrade).
+# They can't live in the migration bodies either: when a fresh DB boots,
+# every migration is detected as pre-applied and skipped, so an index baked
+# into a migration body would never run. Treating them as always-ensure
+# invariants after migrations is idempotent and covers both paths.
+_INDEX_INVARIANTS = (
+    "CREATE INDEX IF NOT EXISTS idx_users_deleted ON users(deleted_at)",
+    "CREATE INDEX IF NOT EXISTS idx_pages_deleted ON pages(deleted_at)",
+    "CREATE INDEX IF NOT EXISTS idx_pages_public ON pages(slug) WHERE is_public = 1",
+)
+
+
+async def _ensure_indexes(db: aiosqlite.Connection) -> None:
+    for stmt in _INDEX_INVARIANTS:
+        await db.execute(stmt)
+    await db.commit()
+
+
+# ── Runner ─────────────────────────────────────────────────────────────────
+
+
+async def _ensure_ledger(db: aiosqlite.Connection) -> None:
+    await db.execute(
+        """
+        CREATE TABLE IF NOT EXISTS schema_migrations (
+            version    INTEGER PRIMARY KEY,
+            name       TEXT    NOT NULL,
+            applied_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
+        )
+        """
+    )
+    await db.commit()
+
+
+async def _applied_versions(db: aiosqlite.Connection) -> set[int]:
+    rows = await db.execute_fetchall("SELECT version FROM schema_migrations")
+    return {r["version"] for r in rows}
+
+
+async def _detect_preexisting(db: aiosqlite.Connection) -> set[int]:
+    """Infer which shipped migrations are already effectively applied.
+
+    Needed for databases created before this module existed: the schema may
+    already carry columns added by earlier in-place ALTERs. Backfilling the
+    ledger here keeps the upgrade silent — no re-running of idempotent DDL,
+    no spurious log lines about "applying migration v3".
+
+    Only probes for artifacts the migration actually creates; anything more
+    ambitious (row counts, index options) gets fragile fast.
+    """
+    applied: set[int] = set()
+    if await _column_exists(db, "users", "display_name") and await _column_exists(
+        db, "users", "email"
+    ):
+        applied.add(1)
+    if await _column_exists(db, "users", "deleted_at") and await _column_exists(
+        db, "users", "original_username"
+    ):
+        applied.add(2)
+    if await _column_exists(db, "pages", "version"):
+        applied.add(3)
+    if await _column_exists(db, "pages", "deleted_at"):
+        applied.add(4)
+    if await _column_exists(db, "pages", "is_public"):
+        applied.add(5)
+    return applied
+
+
+async def run_migrations(db: aiosqlite.Connection) -> list[int]:
+    """Apply any pending migrations. Returns the versions applied this run.
+
+    Also ensures schema-invariant indexes (see `_INDEX_INVARIANTS`) regardless
+    of whether any migration ran, so fresh DBs get them too.
+    """
+    await _ensure_ledger(db)
+
+    applied = await _applied_versions(db)
+    # First run against a pre-existing DB: backfill the ledger from what's
+    # observable in the schema, so we don't re-announce "applying v1…v5".
+    if not applied:
+        inferred = await _detect_preexisting(db)
+        for v in sorted(inferred):
+            name = next((n for (ver, n, _) in MIGRATIONS if ver == v), f"legacy_{v}")
+            await db.execute(
+                "INSERT OR IGNORE INTO schema_migrations (version, name) VALUES (?, ?)",
+                (v, name),
+            )
+        if inferred:
+            await db.commit()
+        applied = inferred
+
+    just_applied: list[int] = []
+    for version, name, fn in MIGRATIONS:
+        if version in applied:
+            continue
+        logger.info("Applying schema migration %03d: %s", version, name)
+        try:
+            await fn(db)
+            await db.execute(
+                "INSERT INTO schema_migrations (version, name) VALUES (?, ?)",
+                (version, name),
+            )
+            await db.commit()
+        except Exception:
+            # Leave the half-applied state on disk so an operator can inspect
+            # it. The next startup will retry from this same migration.
+            logger.exception("Schema migration %03d (%s) failed", version, name)
+            raise
+        just_applied.append(version)
+
+    await _ensure_indexes(db)
+    return just_applied

backend/app/routers/pages.py

@@ -355,18 +355,32 @@ async def update_page(slug: str, body: PageUpdate, user=Depends(get_current_user
             detail="You do not have write permission on this page",
         )
 
-    # Optimistic lock: if the client sent a base_version, it must match.
-    # Missing base_version is allowed for legacy API clients, but logged.
-    if body.base_version is not None and body.base_version != current["version"]:
-        raise HTTPException(
-            status_code=409,
-            detail={
-                "error": "conflict",
-                "message": "This page was modified by someone else. Reload to see the latest version.",
-                "current_version": current["version"],
-                "your_version": body.base_version,
-            },
-        )
+    # Optimistic lock. Required whenever the payload includes a content_md or
+    # title change — those are the only edits that bump the version counter
+    # and therefore the only ones that can silently clobber someone else's
+    # work. Metadata-only edits (is_public toggle, parent/sort moves) don't
+    # need it: they don't race against an open editor.
+    touches_content = body.content_md is not None or body.title is not None
+    if touches_content:
+        if body.base_version is None:
+            raise HTTPException(
+                status_code=400,
+                detail={
+                    "error": "base_version_required",
+                    "message": "base_version is required on content or title edits.",
+                    "current_version": current["version"],
+                },
+            )
+        if body.base_version != current["version"]:
+            raise HTTPException(
+                status_code=409,
+                detail={
+                    "error": "conflict",
+                    "message": "This page was modified by someone else. Reload to see the latest version.",
+                    "current_version": current["version"],
+                    "your_version": body.base_version,
+                },
+            )
 
     title = body.title if body.title is not None else current["title"]
     content = body.content_md if body.content_md is not None else current["content_md"]

backend/tests/test_diagrams.py

@@ -207,7 +207,9 @@ async def test_diagrams_delete_blocked_when_referenced(admin_client):
     assert blocked.status_code == 409
 
     # Remove the reference and delete should succeed.
-    await admin_client.put(f"/api/pages/{slug}", json={"content_md": "no ref"})
+    await admin_client.put(
+        f"/api/pages/{slug}", json={"content_md": "no ref", "base_version": 1}
+    )
     ok = await admin_client.delete(f"/api/diagrams/{diagram_id}")
     assert ok.status_code == 204
 

backend/tests/test_media.py

@@ -94,7 +94,7 @@ async def test_media_reference_tracking_and_delete(admin_client):
     # Remove the reference by updating the page
     upd = await admin_client.put(
         f"/api/pages/{page['slug']}",
-        json={"content_md": "No media anymore"},
+        json={"content_md": "No media anymore", "base_version": 1},
     )
     assert upd.status_code == 200
 

backend/tests/test_optimistic_lock.py

@@ -20,21 +20,53 @@ async def test_version_bumps_on_content_change(auth_client):
         "content_md": "one",
         "slug": "lock-bump",
     })
-    # Update with no base_version (legacy client) still works
     res = await auth_client.put("/api/pages/lock-bump", json={
         "content_md": "two",
+        "base_version": 1,
     })
     assert res.status_code == 200
     assert res.json()["version"] == 2
 
     # Another update bumps again
     res = await auth_client.put("/api/pages/lock-bump", json={
         "content_md": "three",
+        "base_version": 2,
     })
     assert res.status_code == 200
     assert res.json()["version"] == 3
 
 
+@pytest.mark.asyncio
+async def test_content_edit_requires_base_version(auth_client):
+    # A client that forgets base_version on a content edit must be rejected
+    # outright — a silent pass here is exactly the "legacy client loophole"
+    # that caused this check to be tightened.
+    await auth_client.post("/api/pages", json={
+        "title": "Lock Required",
+        "content_md": "hi",
+        "slug": "lock-required",
+    })
+    res = await auth_client.put("/api/pages/lock-required", json={
+        "content_md": "bye",
+    })
+    assert res.status_code == 400
+    assert res.json()["detail"]["error"] == "base_version_required"
+
+
+@pytest.mark.asyncio
+async def test_metadata_edit_does_not_require_base_version(auth_client):
+    # Visibility toggles and sort/parent moves don't bump version and can't
+    # clobber an editor's draft, so they skip the check by design.
+    await auth_client.post("/api/pages", json={
+        "title": "Lock Meta",
+        "content_md": "body",
+        "slug": "lock-meta",
+    })
+    res = await auth_client.put("/api/pages/lock-meta", json={"is_public": True})
+    assert res.status_code == 200
+    assert res.json()["version"] == 1
+
+
 @pytest.mark.asyncio
 async def test_version_does_not_bump_on_noop_update(auth_client):
     await auth_client.post("/api/pages", json={

backend/tests/test_pages.py

@@ -35,7 +35,8 @@ async def test_update_page(auth_client):
 
     response = await auth_client.put("/api/pages/update-me", json={
         "title": "Updated Title",
-        "content_md": "New content"
+        "content_md": "New content",
+        "base_version": 1,
     })
     assert response.status_code == 200
     assert response.json()["title"] == "Updated Title"

backend/tests/test_versions.py

@@ -12,7 +12,8 @@ async def test_versions(auth_client):
     # Update page to create a version
     await auth_client.put("/api/pages/version-page", json={
         "title": "Updated Title",
-        "content_md": "New content"
+        "content_md": "New content",
+        "base_version": 1,
     })
 
     # List versions