migration: establish exact preserved app baseline

app/backend/database/__init__.py

@@ -0,0 +1,11 @@
+from .connection import ManagedConnection, SQLiteConnectionFactory
+from .migrations import MIGRATIONS, Migration, MigrationError, MigrationRunner
+
+__all__ = [
+    "MIGRATIONS",
+    "ManagedConnection",
+    "Migration",
+    "MigrationError",
+    "MigrationRunner",
+    "SQLiteConnectionFactory",
+]

app/backend/database/connection.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import sqlite3
+from dataclasses import dataclass
+from pathlib import Path
+
+
+class ManagedConnection(sqlite3.Connection):
+    """Commit or roll back, then release the SQLite handle on context exit."""
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        try:
+            return super().__exit__(exc_type, exc_value, traceback)
+        finally:
+            self.close()
+
+
+@dataclass(frozen=True)
+class SQLiteConnectionFactory:
+    path: Path
+    timeout_seconds: float = 20
+
+    def connect(self) -> sqlite3.Connection:
+        connection = sqlite3.connect(
+            self.path,
+            timeout=self.timeout_seconds,
+            factory=ManagedConnection,
+        )
+        connection.row_factory = sqlite3.Row
+        connection.execute("PRAGMA journal_mode=WAL")
+        connection.execute("PRAGMA foreign_keys=ON")
+        connection.execute("PRAGMA busy_timeout=20000")
+        return connection

app/backend/database/migrations/__init__.py

@@ -0,0 +1,8 @@
+from .m0001_adopt_legacy import MIGRATION as M0001_ADOPT_LEGACY
+from .m0002_job_runs import MIGRATION as M0002_JOB_RUNS
+from .m0003_llm_audit import MIGRATION as M0003_LLM_AUDIT
+from .runner import Migration, MigrationError, MigrationRunner
+
+MIGRATIONS = (M0001_ADOPT_LEGACY, M0002_JOB_RUNS, M0003_LLM_AUDIT)
+
+__all__ = ["MIGRATIONS", "Migration", "MigrationError", "MigrationRunner"]

app/backend/database/migrations/m0001_adopt_legacy.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+import sqlite3
+
+from backend.database.migrations.runner import Migration, MigrationError
+
+
+REQUIRED_TABLES = frozenset(
+    {
+        "users",
+        "user_sessions",
+        "dashboard_snapshots",
+        "watchlist",
+        "review_notes",
+        "stock_master",
+        "daily_bars",
+        "screener_runs",
+        "mentor_messages",
+        "trade_entries",
+        "heaven_readings",
+    }
+)
+
+
+def adopt_legacy_schema(connection: sqlite3.Connection) -> None:
+    tables = {
+        str(row["name"])
+        for row in connection.execute(
+            "SELECT name FROM sqlite_master WHERE type = 'table'"
+        )
+    }
+    missing = sorted(REQUIRED_TABLES - tables)
+    if missing:
+        raise MigrationError(f"Legacy schema is incomplete: {', '.join(missing)}")
+
+
+MIGRATION = Migration(
+    version="0001",
+    name="adopt_legacy_schema",
+    action=adopt_legacy_schema,
+    signature="required-tables:v1:" + ",".join(sorted(REQUIRED_TABLES)),
+)

app/backend/database/migrations/m0002_job_runs.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+import sqlite3
+
+from backend.database.migrations.runner import Migration
+
+
+def create_job_runs(connection: sqlite3.Connection) -> None:
+    connection.execute(
+        """
+        CREATE TABLE IF NOT EXISTS job_runs (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            job_id TEXT NOT NULL,
+            idempotency_key TEXT NOT NULL,
+            status TEXT NOT NULL,
+            attempt INTEGER NOT NULL DEFAULT 1,
+            started_at TEXT NOT NULL,
+            finished_at TEXT,
+            elapsed_ms INTEGER NOT NULL DEFAULT 0,
+            error_code TEXT NOT NULL DEFAULT '',
+            message TEXT NOT NULL DEFAULT '',
+            output_version TEXT NOT NULL DEFAULT '',
+            metadata TEXT NOT NULL DEFAULT '{}',
+            UNIQUE(job_id, idempotency_key, attempt)
+        )
+        """
+    )
+    connection.execute(
+        """
+        CREATE INDEX IF NOT EXISTS idx_job_runs_job_started
+        ON job_runs(job_id, started_at DESC, id DESC)
+        """
+    )
+    connection.execute(
+        """
+        CREATE INDEX IF NOT EXISTS idx_job_runs_status
+        ON job_runs(status, started_at DESC, id DESC)
+        """
+    )
+
+
+MIGRATION = Migration(
+    version="0002",
+    name="create_job_runs",
+    action=create_job_runs,
+    signature="job-runs:v1:id,job,key,status,attempt,times,elapsed,error,output,metadata",
+)

app/backend/database/migrations/m0003_llm_audit.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import sqlite3
+
+from backend.database.migrations.runner import Migration
+
+
+def extend_llm_audit(connection: sqlite3.Connection) -> None:
+    columns = {
+        str(row["name"])
+        for row in connection.execute("PRAGMA table_info(llm_usage)")
+    }
+    additions = (
+        ("role", "TEXT NOT NULL DEFAULT ''"),
+        ("prompt_version", "TEXT NOT NULL DEFAULT ''"),
+        ("error_code", "TEXT NOT NULL DEFAULT ''"),
+        ("input_tokens", "INTEGER NOT NULL DEFAULT 0"),
+        ("output_tokens", "INTEGER NOT NULL DEFAULT 0"),
+    )
+    for name, declaration in additions:
+        if name not in columns:
+            connection.execute(
+                f"ALTER TABLE llm_usage ADD COLUMN {name} {declaration}"
+            )
+
+
+MIGRATION = Migration(
+    version="0003",
+    name="extend_llm_audit",
+    action=extend_llm_audit,
+    signature="llm-audit:v1:role,prompt-version,error-code,input-tokens,output-tokens",
+)

app/backend/database/migrations/runner.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+import hashlib
+import sqlite3
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+
+MigrationAction = Callable[[sqlite3.Connection], None]
+
+
+class MigrationError(RuntimeError):
+    pass
+
+
+@dataclass(frozen=True)
+class Migration:
+    version: str
+    name: str
+    action: MigrationAction
+    signature: str
+
+    @property
+    def checksum(self) -> str:
+        return hashlib.sha256(self.signature.encode("utf-8")).hexdigest()
+
+
+class MigrationRunner:
+    def apply(
+        self,
+        connection: sqlite3.Connection,
+        migrations: Iterable[Migration],
+    ) -> tuple[str, ...]:
+        ordered = sorted(migrations, key=lambda item: item.version)
+        versions = [item.version for item in ordered]
+        if versions != sorted(set(versions)):
+            raise MigrationError("Migration versions must be unique and ordered")
+        self._ensure_ledger(connection)
+        applied = {
+            str(row["version"]): str(row["checksum"])
+            for row in connection.execute(
+                "SELECT version, checksum FROM schema_migrations ORDER BY version"
+            )
+        }
+        known = set(versions)
+        unknown = sorted(set(applied) - known)
+        if unknown:
+            raise MigrationError(f"Database contains unknown migrations: {', '.join(unknown)}")
+
+        completed: list[str] = []
+        for migration in ordered:
+            existing = applied.get(migration.version)
+            if existing:
+                if existing != migration.checksum:
+                    raise MigrationError(
+                        f"Migration checksum changed: {migration.version} {migration.name}"
+                    )
+                continue
+            savepoint = f"migration_{migration.version.replace('-', '_')}"
+            connection.execute(f"SAVEPOINT {savepoint}")
+            try:
+                migration.action(connection)
+                connection.execute(
+                    """
+                    INSERT INTO schema_migrations
+                        (version, name, checksum, applied_at)
+                    VALUES (?, ?, ?, ?)
+                    """,
+                    (
+                        migration.version,
+                        migration.name,
+                        migration.checksum,
+                        datetime.now(timezone.utc).isoformat(),
+                    ),
+                )
+                connection.execute(f"RELEASE SAVEPOINT {savepoint}")
+            except Exception as exc:
+                connection.execute(f"ROLLBACK TO SAVEPOINT {savepoint}")
+                connection.execute(f"RELEASE SAVEPOINT {savepoint}")
+                raise MigrationError(
+                    f"Migration failed: {migration.version} {migration.name}"
+                ) from exc
+            completed.append(migration.version)
+        return tuple(completed)
+
+    @staticmethod
+    def _ensure_ledger(connection: sqlite3.Connection) -> None:
+        connection.execute(
+            """
+            CREATE TABLE IF NOT EXISTS schema_migrations (
+                version TEXT PRIMARY KEY,
+                name TEXT NOT NULL,
+                checksum TEXT NOT NULL,
+                applied_at TEXT NOT NULL
+            )
+            """
+        )

app/backend/database/repositories/__init__.py

@@ -0,0 +1,21 @@
+from .ports import AlertRepository, StrategyTrackingRepository, TradeJournalRepository
+from .sqlite import (
+    RepositoryBundle,
+    SQLiteAlertRepository,
+    SQLiteStrategyTrackingRepository,
+    SQLiteTradeJournalRepository,
+    build_repository_bundle,
+    require_user_id,
+)
+
+__all__ = [
+    "AlertRepository",
+    "RepositoryBundle",
+    "SQLiteAlertRepository",
+    "SQLiteStrategyTrackingRepository",
+    "SQLiteTradeJournalRepository",
+    "StrategyTrackingRepository",
+    "TradeJournalRepository",
+    "build_repository_bundle",
+    "require_user_id",
+]

app/backend/database/repositories/ports.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+
+class AlertRepository(Protocol):
+    def save_alert(
+        self, user_id: int, kind: str, title: str, content: str,
+        available_date: str, code: str, dedupe_key: str,
+    ) -> int: ...
+
+    def list_alerts(
+        self, user_id: int, as_of: str, unread_only: bool = False, limit: int = 100,
+    ) -> list[dict[str, Any]]: ...
+
+    def count_unread_alerts(self, user_id: int, as_of: str) -> int: ...
+
+    def mark_alert_read(self, user_id: int, alert_id: int) -> bool: ...
+
+    def mark_all_alerts_read(self, user_id: int, as_of: str) -> int: ...
+
+    def delete_alert(self, user_id: int, alert_id: int) -> bool: ...
+
+
+class TradeJournalRepository(Protocol):
+    def save_trade_entry(self, *args: Any, **kwargs: Any) -> int: ...
+
+    def list_trade_entries(
+        self, user_id: int, start_date: str = "", end_date: str = "",
+        code: str = "", limit: int = 300,
+    ) -> list[dict[str, Any]]: ...
+
+    def delete_trade_entry(self, user_id: int, trade_id: int) -> bool: ...
+
+
+class StrategyTrackingRepository(Protocol):
+    def save_strategy_tracks(
+        self, user_id: int, run_id: int, selection_date: str,
+        strategy_name: str, candidates: list[dict[str, Any]],
+    ) -> int: ...
+
+    def get_screener_run(self, user_id: int, run_id: int) -> dict[str, Any] | None: ...
+
+    def delete_strategy_track(self, user_id: int, track_id: int) -> bool: ...
+
+    def list_strategy_tracks(
+        self, user_id: int, limit_batches: int = 12,
+    ) -> list[dict[str, Any]]: ...
+
+    def load_tracking_bars(
+        self, targets: list[tuple[str, str]], limit: int = 5,
+    ) -> dict[tuple[str, str], list[dict[str, Any]]]: ...

app/backend/database/repositories/sqlite.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from database import ReviewDatabase
+
+
+def require_user_id(value: int) -> int:
+    user_id = int(value)
+    if user_id <= 0:
+        raise ValueError("A positive account owner is required")
+    return user_id
+
+
+@dataclass(frozen=True)
+class SQLiteAlertRepository:
+    database: ReviewDatabase
+
+    def save_alert(self, user_id: int, *args: Any, **kwargs: Any) -> int:
+        return self.database.save_alert(require_user_id(user_id), *args, **kwargs)
+
+    def list_alerts(
+        self, user_id: int, as_of: str, unread_only: bool = False, limit: int = 100,
+    ) -> list[dict[str, Any]]:
+        return self.database.list_alerts(
+            require_user_id(user_id), as_of, unread_only, limit
+        )
+
+    def count_unread_alerts(self, user_id: int, as_of: str) -> int:
+        return self.database.count_unread_alerts(require_user_id(user_id), as_of)
+
+    def mark_alert_read(self, user_id: int, alert_id: int) -> bool:
+        return self.database.mark_alert_read(require_user_id(user_id), alert_id)
+
+    def mark_all_alerts_read(self, user_id: int, as_of: str) -> int:
+        return self.database.mark_all_alerts_read(require_user_id(user_id), as_of)
+
+    def delete_alert(self, user_id: int, alert_id: int) -> bool:
+        return self.database.delete_alert(require_user_id(user_id), alert_id)
+
+
+@dataclass(frozen=True)
+class SQLiteTradeJournalRepository:
+    database: ReviewDatabase
+
+    def save_trade_entry(self, user_id: int, *args: Any, **kwargs: Any) -> int:
+        return self.database.save_trade_entry(require_user_id(user_id), *args, **kwargs)
+
+    def list_trade_entries(
+        self, user_id: int, start_date: str = "", end_date: str = "",
+        code: str = "", limit: int = 300,
+    ) -> list[dict[str, Any]]:
+        return self.database.list_trade_entries(
+            require_user_id(user_id), start_date, end_date, code, limit
+        )
+
+    def delete_trade_entry(self, user_id: int, trade_id: int) -> bool:
+        return self.database.delete_trade_entry(require_user_id(user_id), trade_id)
+
+
+@dataclass(frozen=True)
+class SQLiteStrategyTrackingRepository:
+    database: ReviewDatabase
+
+    def save_strategy_tracks(
+        self, user_id: int, run_id: int, selection_date: str,
+        strategy_name: str, candidates: list[dict[str, Any]],
+    ) -> int:
+        return self.database.save_strategy_tracks(
+            require_user_id(user_id), run_id, selection_date, strategy_name, candidates
+        )
+
+    def get_screener_run(self, user_id: int, run_id: int) -> dict[str, Any] | None:
+        owner_id = int(user_id)
+        if owner_id < 0:
+            raise ValueError("Account owner cannot be negative")
+        return self.database.get_screener_run(owner_id, run_id)
+
+    def delete_strategy_track(self, user_id: int, track_id: int) -> bool:
+        return self.database.delete_strategy_track(require_user_id(user_id), track_id)
+
+    def list_strategy_tracks(
+        self, user_id: int, limit_batches: int = 12,
+    ) -> list[dict[str, Any]]:
+        return self.database.list_strategy_tracks(
+            require_user_id(user_id), limit_batches
+        )
+
+    def load_tracking_bars(
+        self, targets: list[tuple[str, str]], limit: int = 5,
+    ) -> dict[tuple[str, str], list[dict[str, Any]]]:
+        return self.database.load_tracking_bars(targets, limit)
+
+
+@dataclass(frozen=True)
+class RepositoryBundle:
+    alerts: SQLiteAlertRepository
+    trades: SQLiteTradeJournalRepository
+    strategy_tracking: SQLiteStrategyTrackingRepository
+
+
+def build_repository_bundle(database: ReviewDatabase) -> RepositoryBundle:
+    return RepositoryBundle(
+        alerts=SQLiteAlertRepository(database),
+        trades=SQLiteTradeJournalRepository(database),
+        strategy_tracking=SQLiteStrategyTrackingRepository(database),
+    )