gdmcode 0.1.0__py3-none-any.whl

src/memory/db.py

@@ -0,0 +1,1119 @@
+"""GdmDatabase — SQLite wrapper around .context-memory/gdm.db.
+
+Single point of access for all persistent state. Creates the schema on first
+init. Thread-safe via connection-per-call pattern. Use as a context manager
+or call close() explicitly.
+"""
+from __future__ import annotations
+
+import logging
+import sqlite3
+import threading
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Callable
+
+from src._internal.constants import _CONTEXT_MEMORY_DIR, _DB_FILENAME
+from src.exceptions import DatabaseError
+
+__all__ = ["GdmDatabase"]
+
+log = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Schema DDL — bump _SCHEMA_VERSION in constants.py when adding tables/columns
+# ---------------------------------------------------------------------------
+
+_DDL = """
+PRAGMA journal_mode=WAL;
+PRAGMA foreign_keys=ON;
+
+CREATE TABLE IF NOT EXISTS schema_version (
+    version  INTEGER PRIMARY KEY
+);
+
+CREATE TABLE IF NOT EXISTS projects (
+    project_id   TEXT PRIMARY KEY,
+    root_path    TEXT UNIQUE NOT NULL,
+    name         TEXT NOT NULL,
+    tech_stack   TEXT NOT NULL DEFAULT '[]',
+    last_seen    TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE TABLE IF NOT EXISTS sessions (
+    session_id   TEXT PRIMARY KEY,
+    project_id   TEXT NOT NULL REFERENCES projects(project_id),
+    created_at   TEXT NOT NULL,
+    updated_at   TEXT NOT NULL,
+    cost_usd     REAL NOT NULL DEFAULT 0.0,
+    turn_count   INTEGER NOT NULL DEFAULT 0,
+    status       TEXT NOT NULL DEFAULT 'active'
+                     CHECK(status IN ('active', 'complete', 'crashed'))
+);
+
+CREATE TABLE IF NOT EXISTS memory (
+    id           INTEGER PRIMARY KEY AUTOINCREMENT,
+    session_id   TEXT NOT NULL REFERENCES sessions(session_id),
+    turn_index   INTEGER NOT NULL DEFAULT 0,
+    role         TEXT NOT NULL CHECK(role IN ('user','assistant','tool','system')),
+    content      TEXT NOT NULL,
+    tokens       INTEGER NOT NULL DEFAULT 0,
+    tool_name    TEXT,
+    tool_call_id TEXT,
+    tool_calls_json TEXT,
+    UNIQUE(session_id, turn_index)
+);
+CREATE INDEX IF NOT EXISTS idx_memory_session ON memory(session_id);
+
+CREATE TABLE IF NOT EXISTS file_cache (
+    id           INTEGER PRIMARY KEY AUTOINCREMENT,
+    project_id   TEXT NOT NULL REFERENCES projects(project_id),
+    path         TEXT NOT NULL,
+    mtime        REAL NOT NULL,
+    summary      TEXT,
+    last_read_at TEXT NOT NULL,
+    UNIQUE(project_id, path)
+);
+
+CREATE TABLE IF NOT EXISTS conventions (
+    id           INTEGER PRIMARY KEY AUTOINCREMENT,
+    project_id   TEXT NOT NULL REFERENCES projects(project_id),
+    key          TEXT NOT NULL,
+    value        TEXT NOT NULL,
+    confidence   REAL NOT NULL DEFAULT 1.0,
+    last_updated TEXT NOT NULL,
+    UNIQUE(project_id, key)
+);
+
+CREATE TABLE IF NOT EXISTS code_index (
+    id           INTEGER PRIMARY KEY AUTOINCREMENT,
+    project_id   TEXT NOT NULL REFERENCES projects(project_id),
+    file         TEXT NOT NULL,
+    symbol       TEXT NOT NULL,
+    kind         TEXT NOT NULL,
+    line         INTEGER NOT NULL,
+    signature    TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_code_index_project ON code_index(project_id);
+CREATE INDEX IF NOT EXISTS idx_code_index_symbol  ON code_index(symbol);
+
+CREATE TABLE IF NOT EXISTS errors (
+    id           INTEGER PRIMARY KEY AUTOINCREMENT,
+    project_id   TEXT NOT NULL REFERENCES projects(project_id),
+    pattern      TEXT NOT NULL,
+    fix          TEXT NOT NULL,
+    seen_count   INTEGER NOT NULL DEFAULT 1,
+    last_seen    TEXT NOT NULL,
+    UNIQUE(project_id, pattern)
+);
+
+CREATE TABLE IF NOT EXISTS permissions (
+    id           INTEGER PRIMARY KEY AUTOINCREMENT,
+    session_id   TEXT REFERENCES sessions(session_id),
+    tool         TEXT NOT NULL UNIQUE,
+    path_glob    TEXT,
+    decision     TEXT NOT NULL CHECK(decision IN ('allow','deny','allow_session','allow_always','deny_session')),
+    expires_at   TEXT
+);
+
+CREATE TABLE IF NOT EXISTS checkpoints (
+    id           INTEGER PRIMARY KEY AUTOINCREMENT,
+    session_id   TEXT NOT NULL REFERENCES sessions(session_id),
+    branch       TEXT NOT NULL,
+    sha          TEXT NOT NULL,
+    files_json   TEXT NOT NULL DEFAULT '[]',
+    cost_usd     REAL NOT NULL DEFAULT 0.0,
+    ts           TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS tasks (
+    task_id      TEXT PRIMARY KEY,
+    session_id   TEXT NOT NULL REFERENCES sessions(session_id),
+    title        TEXT NOT NULL,
+    status       TEXT NOT NULL DEFAULT 'pending'
+        CHECK(status IN ('pending','in_progress','done','blocked')),
+    subtasks     TEXT NOT NULL DEFAULT '[]'
+);
+
+CREATE TABLE IF NOT EXISTS audit_log (
+    id           INTEGER PRIMARY KEY AUTOINCREMENT,
+    session_id   TEXT NOT NULL REFERENCES sessions(session_id),
+    ts           TEXT NOT NULL,
+    tool         TEXT NOT NULL,
+    args         TEXT NOT NULL DEFAULT '{}',
+    model        TEXT,
+    decision     TEXT NOT NULL DEFAULT 'allowed'
+);
+CREATE INDEX IF NOT EXISTS idx_audit_session ON audit_log(session_id);
+
+CREATE TABLE IF NOT EXISTS btw_queue (
+    id           INTEGER PRIMARY KEY AUTOINCREMENT,
+    session_id   TEXT NOT NULL REFERENCES sessions(session_id),
+    message      TEXT NOT NULL,
+    created_at   TEXT NOT NULL DEFAULT (datetime('now')),
+    read_at      TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_btw_session ON btw_queue(session_id, read_at);
+
+CREATE TABLE IF NOT EXISTS spinner_state (
+    key          TEXT PRIMARY KEY,
+    value        TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS session_events (
+    event_id        TEXT PRIMARY KEY,
+    session_id      TEXT NOT NULL REFERENCES sessions(session_id) ON DELETE CASCADE,
+    turn_index      INTEGER NOT NULL,
+    checkpoint_id   INTEGER REFERENCES checkpoints(id),
+    model           TEXT NOT NULL,
+    provider        TEXT NOT NULL,
+    tier            TEXT NOT NULL,
+    input_tokens    INTEGER NOT NULL DEFAULT 0,
+    output_tokens   INTEGER NOT NULL DEFAULT 0,
+    cached_tokens   INTEGER NOT NULL DEFAULT 0,
+    cost_usd        REAL    NOT NULL DEFAULT 0.0,
+    user_message    TEXT,
+    assistant_text  TEXT,
+    annotation      TEXT,
+    ts              TEXT NOT NULL DEFAULT (datetime('now')),
+    UNIQUE(session_id, turn_index)
+);
+CREATE INDEX IF NOT EXISTS idx_session_events_session ON session_events(session_id, turn_index);
+
+CREATE TABLE IF NOT EXISTS tool_call_log (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    event_id        TEXT NOT NULL REFERENCES session_events(event_id) ON DELETE CASCADE,
+    call_index      INTEGER NOT NULL,
+    tool_name       TEXT NOT NULL,
+    call_id         TEXT NOT NULL,
+    args_json       TEXT NOT NULL DEFAULT '{}',
+    result_json     TEXT,
+    duration_ms     INTEGER,
+    ok              INTEGER NOT NULL DEFAULT 1 CHECK(ok IN (0, 1)),
+    error           TEXT,
+    ts              TEXT NOT NULL DEFAULT (datetime('now'))
+);
+CREATE INDEX IF NOT EXISTS idx_tool_call_log_event ON tool_call_log(event_id, call_index);
+
+CREATE TABLE IF NOT EXISTS patch_log (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    event_id        TEXT NOT NULL REFERENCES session_events(event_id) ON DELETE CASCADE,
+    file_path       TEXT NOT NULL,
+    patch_text      TEXT NOT NULL,
+    before_sha      TEXT,
+    after_sha       TEXT,
+    lines_added     INTEGER NOT NULL DEFAULT 0,
+    lines_removed   INTEGER NOT NULL DEFAULT 0,
+    ts              TEXT NOT NULL DEFAULT (datetime('now'))
+);
+CREATE INDEX IF NOT EXISTS idx_patch_log_event ON patch_log(event_id);
+CREATE INDEX IF NOT EXISTS idx_patch_log_file  ON patch_log(file_path);
+
+CREATE TABLE IF NOT EXISTS cost_events (
+    id            INTEGER PRIMARY KEY AUTOINCREMENT,
+    session_id    TEXT    NOT NULL REFERENCES sessions(session_id),
+    event_id      TEXT    REFERENCES session_events(event_id),
+    ts            TEXT    NOT NULL DEFAULT (datetime('now')),
+    provider      TEXT    NOT NULL,
+    tier          TEXT    NOT NULL,
+    input_tokens  INTEGER NOT NULL DEFAULT 0,
+    output_tokens INTEGER NOT NULL DEFAULT 0,
+    cached_tokens INTEGER NOT NULL DEFAULT 0,
+    tool_calls_json TEXT  NOT NULL DEFAULT '{}',
+    cost_usd      REAL    NOT NULL DEFAULT 0.0,
+    scope_project TEXT,
+    scope_team    TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_cost_events_session ON cost_events(session_id, ts);
+CREATE INDEX IF NOT EXISTS idx_cost_events_ts      ON cost_events(ts);
+
+CREATE TABLE IF NOT EXISTS budget_limits (
+    id            INTEGER PRIMARY KEY AUTOINCREMENT,
+    scope_type    TEXT NOT NULL CHECK(scope_type IN ('session','project','user-global','team')),
+    scope_id      TEXT NOT NULL,
+    period        TEXT NOT NULL CHECK(period IN ('session','daily','monthly','total')),
+    limit_usd     REAL NOT NULL,
+    alert_pct_50  INTEGER NOT NULL DEFAULT 1 CHECK(alert_pct_50 IN (0,1)),
+    alert_pct_80  INTEGER NOT NULL DEFAULT 1 CHECK(alert_pct_80 IN (0,1)),
+    hard_stop     INTEGER NOT NULL DEFAULT 1 CHECK(hard_stop IN (0,1)),
+    UNIQUE(scope_type, scope_id, period)
+);
+
+CREATE TABLE IF NOT EXISTS budget_usage (
+    id            INTEGER PRIMARY KEY AUTOINCREMENT,
+    scope_type    TEXT NOT NULL,
+    scope_id      TEXT NOT NULL,
+    period_start  TEXT NOT NULL,
+    period_end    TEXT NOT NULL,
+    spent_usd     REAL NOT NULL DEFAULT 0.0,
+    last_updated  TEXT NOT NULL DEFAULT (datetime('now')),
+    UNIQUE(scope_type, scope_id, period_start)
+);
+
+CREATE TABLE IF NOT EXISTS daemon_jobs (
+    job_id       TEXT PRIMARY KEY,
+    job_type     TEXT NOT NULL,
+    payload_json TEXT NOT NULL DEFAULT '{}',
+    status       TEXT NOT NULL DEFAULT 'pending'
+                 CHECK(status IN ('pending','claimed','done','failed','dead')),
+    retry_count  INTEGER NOT NULL DEFAULT 0,
+    max_retries  INTEGER NOT NULL DEFAULT 3,
+    lease_until  TEXT,
+    result_json  TEXT,
+    created_at   TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at   TEXT NOT NULL DEFAULT (datetime('now')),
+    error        TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_daemon_jobs_status ON daemon_jobs(status, created_at);
+
+CREATE TABLE IF NOT EXISTS developer_decisions (
+    id            INTEGER PRIMARY KEY AUTOINCREMENT,
+    session_id    TEXT NOT NULL,
+    file_context  TEXT,
+    decision_type TEXT NOT NULL,
+    value         TEXT NOT NULL,
+    turn_index    INTEGER,
+    created_at    TEXT DEFAULT (datetime('now'))
+);
+CREATE INDEX IF NOT EXISTS idx_decisions_file ON developer_decisions (file_context);
+
+CREATE TABLE IF NOT EXISTS file_hotspots (
+    file_path          TEXT NOT NULL,
+    project_id         TEXT NOT NULL,
+    edit_session_count INTEGER DEFAULT 1,
+    total_edit_count   INTEGER DEFAULT 1,
+    last_edited_at     TEXT,
+    PRIMARY KEY (file_path, project_id)
+);
+
+CREATE TABLE IF NOT EXISTS batch_jobs (
+    id             TEXT PRIMARY KEY,
+    provider       TEXT NOT NULL,
+    batch_id       TEXT,
+    job_type       TEXT NOT NULL,
+    status         TEXT NOT NULL DEFAULT 'queued',
+    request_count  INTEGER NOT NULL DEFAULT 0,
+    created_at     TEXT NOT NULL,
+    submitted_at   TEXT,
+    completed_at   TEXT,
+    error          TEXT,
+    result_path    TEXT
+);
+"""
+
+
+class GdmDatabase:
+    """Manages the SQLite database at `.context-memory/gdm.db`.
+
+    Usage::
+
+        db = GdmDatabase(project_root=Path("."))
+        with db:
+            db.upsert_convention(project_id, "naming", "snake_case", 0.95)
+
+    Or without context manager::
+
+        db = GdmDatabase(project_root=Path("."))
+        db.spinner_state_mark_seen("2026-04-08", "Gedeoning")
+        db.close()
+    """
+
+    def __init__(self, project_root: Path) -> None:
+        self._db_path = project_root / _CONTEXT_MEMORY_DIR / _DB_FILENAME
+        self._db_path.parent.mkdir(parents=True, exist_ok=True)
+        self._lock = threading.RLock()  # serialise cross-thread access to _conn
+        self._conn: sqlite3.Connection = self._connect()
+        self._ensure_schema()
+
+    # ------------------------------------------------------------------
+    # Connection management
+    # ------------------------------------------------------------------
+
+    def _connect(self) -> sqlite3.Connection:
+        try:
+            conn = sqlite3.connect(self._db_path, check_same_thread=False)
+            conn.row_factory = sqlite3.Row
+            conn.execute("PRAGMA busy_timeout = 2000")
+            return conn
+        except sqlite3.Error as exc:
+            raise DatabaseError(f"Cannot open database at {self._db_path}: {exc}") from exc
+
+    def _ensure_schema(self) -> None:
+        from src.db.migrations import registry  # local import avoids circular at module level
+        try:
+            self._conn.executescript(_DDL)
+            registry.apply_pending(self._conn)
+        except sqlite3.Error as exc:
+            raise DatabaseError(f"Schema init failed: {exc}") from exc
+
+    def close(self) -> None:
+        """Close the database connection."""
+        self._conn.close()
+
+    def __enter__(self) -> GdmDatabase:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    from contextlib import contextmanager
+
+    @contextmanager  # type: ignore[misc]
+    def transaction(self):  # type: ignore[return]
+        """Context manager for an explicit SQLite transaction.
+
+        All statements inside the block run in one atomic transaction.
+        Rolls back on any exception.  Thread-safe: acquires _lock for the
+        full duration so concurrent threads cannot interleave statements.
+        """
+        with self._lock:
+            try:
+                self._conn.execute("BEGIN")
+                yield
+                self._conn.execute("COMMIT")
+            except Exception:
+                try:
+                    self._conn.execute("ROLLBACK")
+                except Exception:
+                    pass
+                raise
+
+    # ------------------------------------------------------------------
+    # Spinner state
+    # ------------------------------------------------------------------
+
+    def spinner_state_get(self, date: str) -> list[str]:
+        """Return list of priority verbs already seen on `date`."""
+        cur = self._conn.execute(
+            "SELECT value FROM spinner_state WHERE key = ?", (f"seen:{date}",)
+        )
+        row = cur.fetchone()
+        if row is None:
+            return []
+        import json
+        return json.loads(row["value"])
+
+    def spinner_state_mark_seen(self, date: str, verb: str) -> None:
+        """Record that `verb` was shown on `date`."""
+        import json
+        seen = self.spinner_state_get(date)
+        if verb not in seen:
+            seen.append(verb)
+        self._conn.execute(
+            "INSERT OR REPLACE INTO spinner_state (key, value) VALUES (?, ?)",
+            (f"seen:{date}", json.dumps(seen)),
+        )
+        self._conn.commit()
+
+    # ------------------------------------------------------------------
+    # Audit log
+    # ------------------------------------------------------------------
+
+    def audit_log_write(
+        self,
+        session_id: str,
+        tool: str,
+        args: dict,  # type: ignore[type-arg]
+        model: str | None = None,
+        decision: str = "allowed",
+    ) -> None:
+        """Append an entry to the audit log."""
+        import json
+        from datetime import datetime, timezone
+        ts = datetime.now(timezone.utc).isoformat()
+        try:
+            self._conn.execute(
+                "INSERT INTO audit_log (session_id, ts, tool, args, model, decision) "
+                "VALUES (?, ?, ?, ?, ?, ?)",
+                (session_id, ts, tool, json.dumps(args), model, decision),
+            )
+            self._conn.commit()
+        except sqlite3.Error as exc:
+            raise DatabaseError(f"audit_log write failed: {exc}") from exc
+
+    # ------------------------------------------------------------------
+    # Conventions
+    # ------------------------------------------------------------------
+
+    def upsert_convention(
+        self, project_id: str, key: str, value: str, confidence: float = 1.0
+    ) -> None:
+        from datetime import datetime, timezone
+        ts = datetime.now(timezone.utc).isoformat()
+        try:
+            self._conn.execute(
+                """
+                INSERT INTO conventions (project_id, key, value, confidence, last_updated)
+                VALUES (?, ?, ?, ?, ?)
+                ON CONFLICT(project_id, key) DO UPDATE SET
+                    value = excluded.value,
+                    confidence = excluded.confidence,
+                    last_updated = excluded.last_updated
+                """,
+                (project_id, key, value, confidence, ts),
+            )
+            self._conn.commit()
+        except sqlite3.Error as exc:
+            raise DatabaseError(f"upsert_convention failed: {exc}") from exc
+
+    def get_conventions(self, project_id: str) -> list[sqlite3.Row]:
+        cur = self._conn.execute(
+            "SELECT key, value, confidence FROM conventions WHERE project_id = ? "
+            "ORDER BY confidence DESC",
+            (project_id,),
+        )
+        return cur.fetchall()
+
+    # ------------------------------------------------------------------
+    # File cache
+    # ------------------------------------------------------------------
+
+    def upsert_file_cache(
+        self, project_id: str, path: str, mtime: float, summary: str | None
+    ) -> None:
+        from datetime import datetime, timezone
+        ts = datetime.now(timezone.utc).isoformat()
+        try:
+            self._conn.execute(
+                """
+                INSERT INTO file_cache (project_id, path, mtime, summary, last_read_at)
+                VALUES (?, ?, ?, ?, ?)
+                ON CONFLICT(project_id, path) DO UPDATE SET
+                    mtime = excluded.mtime,
+                    summary = excluded.summary,
+                    last_read_at = excluded.last_read_at
+                """,
+                (project_id, path, mtime, summary, ts),
+            )
+            self._conn.commit()
+        except sqlite3.Error as exc:
+            raise DatabaseError(f"upsert_file_cache failed: {exc}") from exc
+
+    def get_file_cache(self, project_id: str, path: str) -> sqlite3.Row | None:
+        cur = self._conn.execute(
+            "SELECT mtime, summary, last_read_at FROM file_cache "
+            "WHERE project_id = ? AND path = ?",
+            (project_id, path),
+        )
+        return cur.fetchone()
+
+    # ------------------------------------------------------------------
+    # Memory / transcript persistence (crash recovery)
+    # ------------------------------------------------------------------
+
+    def memory_save_turns(
+        self, session_id: str, turns: list[dict]  # type: ignore[type-arg]
+    ) -> None:
+        """Replace all persisted turns for a session (idempotent checkpoint).
+
+        Enumerates turns to write a stable ``turn_index`` so the UNIQUE
+        constraint on ``(session_id, turn_index)`` prevents duplicate rows.
+        The DELETE step cleans up any stale rows beyond the current transcript
+        length (e.g. after eviction/compression shortened the history).
+
+        Args:
+            session_id: active session identifier
+            turns: list of turn dicts with keys role/content/tokens/
+                   tool_name/tool_call_id/tool_calls
+        """
+        import json as _json
+        try:
+            with self.transaction():
+                # Remove rows beyond the new transcript length (eviction shrinkage).
+                self._conn.execute(
+                    "DELETE FROM memory WHERE session_id = ? AND turn_index >= ?",
+                    (session_id, len(turns)),
+                )
+                for idx, t in enumerate(turns):
+                    self._conn.execute(
+                        "INSERT OR REPLACE INTO memory "
+                        "(session_id, turn_index, role, content, tokens, "
+                        "tool_name, tool_call_id, tool_calls_json) "
+                        "VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+                        (
+                            session_id,
+                            idx,
+                            t["role"],
+                            t.get("content") or "",
+                            t.get("tokens", 0),
+                            t.get("tool_name"),
+                            t.get("tool_call_id"),
+                            _json.dumps(t["tool_calls"]) if t.get("tool_calls") else None,
+                        ),
+                    )
+        except sqlite3.Error as exc:
+            raise DatabaseError(f"memory_save_turns failed: {exc}") from exc
+
+    def memory_load_turns(
+        self, session_id: str
+    ) -> list[dict]:  # type: ignore[type-arg]
+        """Load persisted transcript turns for session restore.
+
+        Returns:
+            List of turn dicts ordered by ``turn_index``, ready for
+            ``Turn.from_message()`` or ``TranscriptStore.from_turns()``.
+        """
+        import json as _json
+        try:
+            cur = self._conn.execute(
+                "SELECT role, content, tokens, tool_name, tool_call_id, tool_calls_json "
+                "FROM memory WHERE session_id = ? ORDER BY turn_index",
+                (session_id,),
+            )
+            return [
+                {
+                    "role": r["role"],
+                    "content": r["content"],
+                    "tokens": r["tokens"],
+                    "tool_name": r["tool_name"],
+                    "tool_call_id": r["tool_call_id"],
+                    "tool_calls": _json.loads(r["tool_calls_json"])
+                    if r["tool_calls_json"]
+                    else None,
+                }
+                for r in cur.fetchall()
+            ]
+        except sqlite3.Error as exc:
+            raise DatabaseError(f"memory_load_turns failed: {exc}") from exc
+
+    def session_set_status(self, session_id: str, status: str) -> None:
+        """Update the lifecycle status of a session.
+
+        Args:
+            session_id: session to update
+            status: one of 'active', 'complete', 'crashed'
+        """
+        try:
+            self._conn.execute(
+                "UPDATE sessions SET status = ?, updated_at = datetime('now') "
+                "WHERE session_id = ?",
+                (status, session_id),
+            )
+            self._conn.commit()
+        except sqlite3.Error as exc:
+            raise DatabaseError(f"session_set_status failed: {exc}") from exc
+
+    def list_incomplete_sessions(
+        self, limit: int = 10
+    ) -> list[dict]:  # type: ignore[type-arg]
+        """Return active sessions that have at least one turn, most recently updated first.
+
+        Returns an empty list if the sessions table predates core-002
+        migration (no ``status`` column) — callers should handle empty gracefully.
+
+        Each dict has keys: ``session_id``, ``created_at``, ``updated_at``,
+        ``turn_count``, ``cost_usd``, ``status``.
+        """
+        try:
+            with self._lock:
+                rows = self._conn.execute(
+                    "SELECT session_id, created_at, updated_at, turn_count, cost_usd, status "
+                    "FROM sessions WHERE status = 'active' AND turn_count > 0 "
+                    "ORDER BY updated_at DESC LIMIT ?",
+                    (limit,),
+                ).fetchall()
+            return [dict(r) for r in rows]
+        except sqlite3.OperationalError:
+            # Pre-migration: sessions table may not have the status column yet.
+            return []
+        except sqlite3.Error as exc:
+            raise DatabaseError(f"list_incomplete_sessions failed: {exc}") from exc
+
+    # ------------------------------------------------------------------
+    # Raw access for advanced queries
+    # ------------------------------------------------------------------
+
+    _MAX_RETRY: int = 5
+    _RETRY_BASE_MS: float = 50.0
+
+    def _execute_with_retry(self, fn: "Callable[[], Any]", sql: str = "") -> "Any":
+        """Run fn with exponential backoff on SQLITE_BUSY / 'database is locked'."""
+        import time as _time
+        for attempt in range(self._MAX_RETRY):
+            try:
+                return fn()
+            except sqlite3.OperationalError as exc:
+                if "database is locked" not in str(exc).lower() or attempt == self._MAX_RETRY - 1:
+                    raise DatabaseError(str(exc) + (f"\nSQL: {sql}" if sql else "")) from exc
+                wait = self._RETRY_BASE_MS * (2 ** attempt) / 1000.0
+                log.debug("SQLITE_BUSY attempt %d/%d, sleeping %.3fs", attempt + 1, self._MAX_RETRY, wait)
+                _time.sleep(wait)
+        raise DatabaseError("Unreachable")  # mypy guard
+
+    def execute(self, sql: str, params: tuple = ()) -> sqlite3.Cursor:
+        """Execute raw SQL. Use sparingly — prefer typed methods above."""
+        def _run() -> sqlite3.Cursor:
+            with self._lock:
+                cur = self._conn.execute(sql, params)
+                self._conn.commit()
+                return cur
+        return self._execute_with_retry(_run, sql)
+
+    def execute_one(self, sql: str, params: tuple = ()) -> "sqlite3.Row | None":
+        """Execute a SELECT and return at most one row, or None."""
+        def _run() -> "sqlite3.Row | None":
+            with self._lock:
+                cur = self._conn.execute(sql, params)
+                return cur.fetchone()
+        return self._execute_with_retry(_run, sql)
+
+    def execute_all(self, sql: str, params: tuple = ()) -> "list[sqlite3.Row]":
+        """Execute a SELECT and return all rows."""
+        def _run() -> "list[sqlite3.Row]":
+            with self._lock:
+                cur = self._conn.execute(sql, params)
+                return cur.fetchall()
+        return self._execute_with_retry(_run, sql)
+
+    # ------------------------------------------------------------------
+    # Event log (session_events / tool_call_log / patch_log)
+    # ------------------------------------------------------------------
+
+    def event_log_begin_turn(
+        self,
+        session_id: str,
+        turn_index: int,
+        model: str,
+        provider: str,
+        tier: str,
+        user_message: str | None = None,
+    ) -> str:
+        """Insert a session_events row for a new turn; returns event_id (UUID)."""
+        import uuid as _uuid
+        from datetime import datetime, timezone
+        event_id = str(_uuid.uuid4())
+        ts = datetime.now(timezone.utc).isoformat()
+        self.execute(
+            """
+            INSERT INTO session_events
+                (event_id, session_id, turn_index, model, provider, tier, user_message, ts)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+            """,
+            (event_id, session_id, turn_index, model, provider, tier, user_message, ts),
+        )
+        return event_id
+
+    def event_log_complete_turn(
+        self,
+        event_id: str,
+        assistant_text: str | None,
+        input_tokens: int,
+        output_tokens: int,
+        cached_tokens: int,
+        cost_usd: float,
+        checkpoint_id: int | None = None,
+    ) -> None:
+        """Update session_events row with turn completion data."""
+        self.execute(
+            """
+            UPDATE session_events
+            SET assistant_text=?, input_tokens=?, output_tokens=?, cached_tokens=?,
+                cost_usd=?, checkpoint_id=?
+            WHERE event_id=?
+            """,
+            (assistant_text, input_tokens, output_tokens, cached_tokens,
+             cost_usd, checkpoint_id, event_id),
+        )
+
+    def event_log_record_tool_call(
+        self,
+        event_id: str,
+        call_index: int,
+        tool_name: str,
+        call_id: str,
+        args: dict,
+        result: dict | None = None,
+        duration_ms: int | None = None,
+        ok: bool = True,
+        error: str | None = None,
+    ) -> None:
+        """Insert one tool_call_log row."""
+        import json as _json
+        self.execute(
+            """
+            INSERT INTO tool_call_log
+                (event_id, call_index, tool_name, call_id, args_json,
+                 result_json, duration_ms, ok, error)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+            """,
+            (event_id, call_index, tool_name, call_id,
+             _json.dumps(args),
+             _json.dumps(result) if result is not None else None,
+             duration_ms, int(ok), error),
+        )
+
+    def event_log_record_patch(
+        self,
+        event_id: str,
+        file_path: str,
+        patch_text: str,
+        before_sha: str | None = None,
+        after_sha: str | None = None,
+    ) -> None:
+        """Insert one patch_log row with line-count computed from unified diff."""
+        added = max(0, patch_text.count("\n+") - patch_text.count("\n+++"))
+        removed = max(0, patch_text.count("\n-") - patch_text.count("\n---"))
+        self.execute(
+            """
+            INSERT INTO patch_log
+                (event_id, file_path, patch_text, before_sha, after_sha,
+                 lines_added, lines_removed)
+            VALUES (?, ?, ?, ?, ?, ?, ?)
+            """,
+            (event_id, file_path, patch_text, before_sha, after_sha, added, removed),
+        )
+
+    def event_log_load_session(self, session_id: str) -> list[dict]:
+        """Load full event log for a session ordered by turn_index.
+
+        Returns list of dicts with keys: event_id, turn_index, model, provider,
+        tier, input_tokens, output_tokens, cached_tokens, cost_usd, user_message,
+        assistant_text, ts, checkpoint_id, tool_calls, patches.
+        """
+        import json as _json
+        events = self.execute_all(
+            "SELECT * FROM session_events WHERE session_id=? ORDER BY turn_index",
+            (session_id,),
+        )
+        result = []
+        for ev in events:
+            ev_dict = dict(ev)
+            tc_rows = self.execute_all(
+                "SELECT * FROM tool_call_log WHERE event_id=? ORDER BY call_index",
+                (ev["event_id"],),
+            )
+            ev_dict["tool_calls"] = [
+                {**dict(r),
+                 "args": _json.loads(r["args_json"]) if r["args_json"] else {},
+                 "result": _json.loads(r["result_json"]) if r["result_json"] else None}
+                for r in tc_rows
+            ]
+            ev_dict["patches"] = [
+                dict(r) for r in self.execute_all(
+                    "SELECT * FROM patch_log WHERE event_id=? ORDER BY id",
+                    (ev["event_id"],),
+                )
+            ]
+            result.append(ev_dict)
+        return result
+
+    # ------------------------------------------------------------------
+    # Cost events
+    # ------------------------------------------------------------------
+
+    def cost_event_insert(
+        self,
+        session_id: str,
+        provider: str,
+        tier: str,
+        input_tokens: int,
+        output_tokens: int,
+        cached_tokens: int,
+        cost_usd: float,
+        tool_calls_json: str = "{}",
+        event_id: str | None = None,
+        scope_project: str | None = None,
+        scope_team: str | None = None,
+    ) -> None:
+        """Append one row to the cost_events append-only ledger."""
+        from datetime import datetime, timezone
+        ts = datetime.now(timezone.utc).isoformat()
+        self.execute(
+            """
+            INSERT INTO cost_events
+                (session_id, event_id, ts, provider, tier,
+                 input_tokens, output_tokens, cached_tokens,
+                 tool_calls_json, cost_usd, scope_project, scope_team)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            """,
+            (session_id, event_id, ts, provider, tier,
+             input_tokens, output_tokens, cached_tokens,
+             tool_calls_json, cost_usd, scope_project, scope_team),
+        )
+
+    def cost_monthly_spend(
+        self, project_id: str | None = None
+    ) -> float:
+        """Sum cost_usd for the rolling 30-day window ending now."""
+        from datetime import datetime, timedelta, timezone
+        cutoff = (datetime.now(timezone.utc) - timedelta(days=30)).isoformat()
+        if project_id:
+            row = self.execute_one(
+                """
+                SELECT COALESCE(SUM(ce.cost_usd), 0.0) AS total
+                FROM cost_events ce
+                JOIN sessions s ON ce.session_id = s.session_id
+                WHERE s.project_id = ? AND ce.ts >= ?
+                """,
+                (project_id, cutoff),
+            )
+        else:
+            row = self.execute_one(
+                "SELECT COALESCE(SUM(cost_usd), 0.0) AS total FROM cost_events WHERE ts >= ?",
+                (cutoff,),
+            )
+        return float(row["total"]) if row else 0.0
+
+    # ------------------------------------------------------------------
+    # Daemon job queue
+    # ------------------------------------------------------------------
+
+    def daemon_job_submit(
+        self, job_type: str, payload: dict, max_retries: int = 3
+    ) -> str:
+        """Insert a new pending daemon job; return job_id."""
+        import json as _json
+        import uuid as _uuid
+        job_id = str(_uuid.uuid4())[:8]
+        self.execute(
+            """
+            INSERT INTO daemon_jobs (job_id, job_type, payload_json, max_retries)
+            VALUES (?, ?, ?, ?)
+            """,
+            (job_id, job_type, _json.dumps(payload), max_retries),
+        )
+        return job_id
+
+    def daemon_job_claim(self, lease_secs: float = 120.0) -> "sqlite3.Row | None":
+        """Atomically claim the oldest pending/expired job. Returns full row or None."""
+        from datetime import datetime, timedelta, timezone
+        now = datetime.now(timezone.utc)
+        expires = (now + timedelta(seconds=lease_secs)).isoformat()
+        now_iso = now.isoformat()
+        try:
+            with self.transaction():
+                row = self.execute_one(
+                    """
+                    SELECT job_id FROM daemon_jobs
+                    WHERE status = 'pending'
+                       OR (status = 'claimed' AND lease_until < ?)
+                    ORDER BY created_at ASC
+                    LIMIT 1
+                    """,
+                    (now_iso,),
+                )
+                if row is None:
+                    return None
+                self._conn.execute(
+                    """
+                    UPDATE daemon_jobs
+                    SET status='claimed', lease_until=?, updated_at=?
+                    WHERE job_id=?
+                    """,
+                    (expires, now_iso, row["job_id"]),
+                )
+                return self.execute_one(
+                    "SELECT * FROM daemon_jobs WHERE job_id=?", (row["job_id"],)
+                )
+        except Exception as exc:
+            raise DatabaseError(f"daemon_job_claim failed: {exc}") from exc
+
+    def daemon_job_complete(self, job_id: str, result: dict) -> None:
+        """Mark job as done and store result."""
+        import json as _json
+        from datetime import datetime, timezone
+        self.execute(
+            "UPDATE daemon_jobs SET status='done', result_json=?, updated_at=? WHERE job_id=?",
+            (_json.dumps(result), datetime.now(timezone.utc).isoformat(), job_id),
+        )
+
+    def daemon_job_fail(self, job_id: str, error: str) -> None:
+        """Increment retry_count; promote to 'dead' when max_retries exhausted."""
+        from datetime import datetime, timezone
+        try:
+            with self.transaction():
+                row = self.execute_one(
+                    "SELECT retry_count, max_retries FROM daemon_jobs WHERE job_id=?", (job_id,)
+                )
+                if row is None:
+                    return
+                new_count = row["retry_count"] + 1
+                new_status = "dead" if new_count >= row["max_retries"] else "pending"
+                self._conn.execute(
+                    """
+                    UPDATE daemon_jobs
+                    SET status=?, retry_count=?, error=?, lease_until=NULL, updated_at=?
+                    WHERE job_id=?
+                    """,
+                    (new_status, new_count, error, datetime.now(timezone.utc).isoformat(), job_id),
+                )
+        except Exception as exc:
+            raise DatabaseError(f"daemon_job_fail failed: {exc}") from exc
+
+    def daemon_job_result(self, job_id: str) -> "dict | None":
+        """Return result dict for a done/dead job, or None if still pending/claimed."""
+        import json as _json
+        row = self.execute_one(
+            "SELECT result_json, status, error FROM daemon_jobs WHERE job_id=?", (job_id,)
+        )
+        if row is None or row["status"] not in ("done", "dead"):
+            return None
+        if row["result_json"]:
+            return _json.loads(row["result_json"])
+        return {"ok": False, "error": row["error"]}
+
+    def daemon_job_pending_count(self) -> int:
+        """Count pending daemon jobs."""
+        row = self.execute_one("SELECT COUNT(*) AS n FROM daemon_jobs WHERE status='pending'")
+        return int(row["n"]) if row else 0
+
+    def daemon_job_failed_count(self) -> int:
+        """Count dead (permanently failed) daemon jobs."""
+        row = self.execute_one("SELECT COUNT(*) AS n FROM daemon_jobs WHERE status='dead'")
+        return int(row["n"]) if row else 0
+
+    def commit(self) -> None:
+        self._conn.commit()
+
+    # ------------------------------------------------------------------
+    # BTW (out-of-band) queue
+    # ------------------------------------------------------------------
+
+    def btw_dequeue_pending(self, session_id: str) -> list[dict]:  # type: ignore[type-arg]
+        """Return all unread BTW messages for *session_id*.
+
+        Does NOT mark them as read — call :meth:`btw_mark_delivered` after
+        injecting them into the agent transcript.
+
+        Returns:
+            List of dicts with keys: ``id``, ``message``, ``created_at``.
+        """
+        try:
+            rows = self.execute_all(
+                "SELECT id, message, created_at FROM btw_queue "
+                "WHERE session_id = ? AND read_at IS NULL "
+                "ORDER BY created_at ASC",
+                (session_id,),
+            )
+            return [dict(r) for r in rows]
+        except sqlite3.Error as exc:
+            raise DatabaseError(f"btw_dequeue_pending failed: {exc}") from exc
+
+    def btw_mark_delivered(self, ids: list[int]) -> None:
+        """Mark BTW messages as delivered (sets ``read_at`` to now).
+
+        Args:
+            ids: list of ``btw_queue.id`` values to mark.
+        """
+        if not ids:
+            return
+        from datetime import datetime, timezone
+        now = datetime.now(timezone.utc).isoformat()
+        placeholders = ",".join("?" * len(ids))
+        try:
+            self.execute(
+                f"UPDATE btw_queue SET read_at = ? WHERE id IN ({placeholders})",
+                (now, *ids),
+            )
+        except sqlite3.Error as exc:
+            raise DatabaseError(f"btw_mark_delivered failed: {exc}") from exc
+
+
+
+    # --- VerificationGraph helpers (v9) ---
+
+    def add_edit_node(self, session_id, turn_index, file_path, patch_ref=None):
+        import uuid as _u; from datetime import datetime, timezone
+        from src.artifacts.verification_graph import EditNode
+        nid = str(_u.uuid4()); ts = datetime.now(timezone.utc).isoformat()
+        self.execute(
+            "INSERT INTO edit_nodes (node_id,session_id,turn_index,file_path,patch_ref,created_at) VALUES (?,?,?,?,?,?)",
+            (nid, session_id, turn_index, str(file_path), patch_ref, ts))
+        return EditNode(node_id=nid, session_id=session_id, turn_index=turn_index,
+                        file_path=str(file_path), patch_ref=patch_ref, created_at=ts)
+
+    def add_evidence_node(self, node_id, kind, verdict, detail=None, tool=None, duration_ms=None):
+        import json as _j, uuid as _u; from datetime import datetime, timezone
+        from src.artifacts.verification_graph import EvidenceKind, EvidenceNode, Verdict
+        eid = str(_u.uuid4()); ts = datetime.now(timezone.utc).isoformat()
+        kv = kind.value if isinstance(kind, EvidenceKind) else str(kind)
+        vv = verdict.value if isinstance(verdict, Verdict) else str(verdict)
+        dj = _j.dumps(detail if isinstance(detail, dict) else {})
+        self.execute(
+            "INSERT INTO evidence_nodes (evidence_id,node_id,kind,verdict,detail_json,tool,duration_ms,created_at) VALUES (?,?,?,?,?,?,?,?)",
+            (eid, node_id, kv, vv, dj, tool, duration_ms, ts))
+        return EvidenceNode(evidence_id=eid, node_id=node_id, kind=EvidenceKind(kv),
+                            verdict=Verdict(vv), detail=_j.loads(dj),
+                            tool=tool, duration_ms=duration_ms, created_at=ts)
+
+    def add_graph_edge(self, from_node_id, to_node_id):
+        self.execute("INSERT OR IGNORE INTO graph_edges (from_node_id,to_node_id) VALUES (?,?)",
+                     (from_node_id, to_node_id))
+
+    def get_edit_node(self, node_id):
+        from src.artifacts.verification_graph import EditNode
+        r = self.execute_one("SELECT * FROM edit_nodes WHERE node_id=?", (node_id,))
+        if r is None: return None
+        return EditNode(node_id=r["node_id"], session_id=r["session_id"],
+                        turn_index=r["turn_index"], file_path=r["file_path"],
+                        patch_ref=r["patch_ref"], created_at=r["created_at"])
+
+    def get_evidence_for_node(self, node_id):
+        import json as _j
+        from src.artifacts.verification_graph import EvidenceKind, EvidenceNode, Verdict
+        rows = self.execute_all(
+            "SELECT * FROM evidence_nodes WHERE node_id=? ORDER BY created_at ASC", (node_id,))
+        return [EvidenceNode(evidence_id=r["evidence_id"], node_id=r["node_id"],
+                             kind=EvidenceKind(r["kind"]), verdict=Verdict(r["verdict"]),
+                             detail=_j.loads(r["detail_json"]),
+                             tool=r["tool"], duration_ms=r["duration_ms"],
+                             created_at=r["created_at"]) for r in rows]
+
+    def get_dependents(self, node_id):
+        rows = self.execute_all(
+            "SELECT to_node_id FROM graph_edges WHERE from_node_id=?", (node_id,))
+        return [r["to_node_id"] for r in rows]
+
+    def get_edit_nodes_for_session_file(self, session_id, file_path):
+        from src.artifacts.verification_graph import EditNode
+        rows = self.execute_all(
+            "SELECT * FROM edit_nodes WHERE session_id=? AND file_path=? ORDER BY created_at ASC",
+            (session_id, str(file_path)))
+        return [EditNode(node_id=r["node_id"], session_id=r["session_id"],
+                         turn_index=r["turn_index"], file_path=r["file_path"],
+                         patch_ref=r["patch_ref"], created_at=r["created_at"]) for r in rows]
+
+    # --- Confidence outcomes (v11 / ide-003) ---
+
+    def confidence_outcome_insert(
+        self,
+        session_id: str,
+        hunk_hash: str,
+        score: int,
+        reasons: list,
+        verified: bool = False,
+    ) -> int:
+        """Insert a confidence outcome record and return its row id."""
+        import json as _j
+        from datetime import datetime, timezone
+
+        now = datetime.now(timezone.utc).isoformat()
+        self.execute(
+            "INSERT INTO confidence_outcomes "
+            "(session_id, hunk_hash, score, reasons_json, verified, created_at) "
+            "VALUES (?, ?, ?, ?, ?, ?)",
+            (session_id, hunk_hash, score, _j.dumps(reasons), int(verified), now),
+        )
+        row = self.execute_one("SELECT last_insert_rowid() AS rid")
+        return int(row["rid"]) if row else -1
+
+    def confidence_outcomes_for_session(self, session_id: str) -> list:
+        """Return all confidence outcomes for *session_id*, newest first."""
+        import json as _j
+
+        rows = self.execute_all(
+            "SELECT id, session_id, hunk_hash, score, reasons_json, verified, created_at "
+            "FROM confidence_outcomes WHERE session_id = ? ORDER BY id DESC",
+            (session_id,),
+        )
+        result = []
+        for r in rows:
+            result.append({
+                "id": r["id"],
+                "session_id": r["session_id"],
+                "hunk_hash": r["hunk_hash"],
+                "score": r["score"],
+                "reasons": _j.loads(r["reasons_json"]),
+                "verified": bool(r["verified"]),
+                "created_at": r["created_at"],
+            })
+        return result