cortex-loop 0.1.0a1__py3-none-any.whl

cortex/store.py

@@ -0,0 +1,793 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import sqlite3
+import time
+from contextlib import contextmanager
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Callable, Iterator
+from uuid import uuid4
+
+DB_SCHEMA_VERSION = 2
+
+
+def _utc_now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+_FTS_TOKEN_RE = re.compile(r"^[a-z0-9_]+$")
+_COMPACT_TEXT_FIELDS = ("last_assistant_message", "stdout", "stderr", "output", "message")
+_COMPACT_TEXT_MAX_LEN = 2048
+
+
+@dataclass(slots=True)
+class SQLiteStore:
+    db_path: Path
+    lock_retry_attempts: int = 3
+    lock_retry_backoff_ms: int = 25
+    busy_timeout_ms: int = 5000
+
+    def initialize(self) -> None:
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+        with self.connection() as conn:
+            conn.execute("PRAGMA journal_mode = WAL")
+            conn.execute("PRAGMA foreign_keys = ON")
+            conn.execute(f"PRAGMA user_version = {DB_SCHEMA_VERSION}")
+            conn.executescript(
+                """
+                CREATE TABLE IF NOT EXISTS sessions (
+                  session_id TEXT PRIMARY KEY,
+                  started_at TEXT NOT NULL,
+                  ended_at TEXT,
+                  status TEXT NOT NULL,
+                  genome_path TEXT,
+                  metadata_json TEXT NOT NULL
+                );
+
+                CREATE TABLE IF NOT EXISTS graveyard (
+                  id INTEGER PRIMARY KEY AUTOINCREMENT,
+                  session_id TEXT,
+                  summary TEXT NOT NULL,
+                  reason TEXT NOT NULL,
+                  files_json TEXT NOT NULL,
+                  keywords_json TEXT NOT NULL,
+                  created_at TEXT NOT NULL
+                );
+
+                CREATE TABLE IF NOT EXISTS invariants (
+                  id INTEGER PRIMARY KEY AUTOINCREMENT,
+                  session_id TEXT NOT NULL,
+                  test_path TEXT NOT NULL,
+                  status TEXT NOT NULL,
+                  duration_ms INTEGER NOT NULL,
+                  stdout TEXT NOT NULL,
+                  stderr TEXT NOT NULL,
+                  graduated_from TEXT,
+                  created_at TEXT NOT NULL
+                );
+
+                CREATE TABLE IF NOT EXISTS challenge_results (
+                  id INTEGER PRIMARY KEY AUTOINCREMENT,
+                  session_id TEXT NOT NULL,
+                  category TEXT NOT NULL,
+                  covered INTEGER NOT NULL,
+                  evidence_json TEXT NOT NULL,
+                  created_at TEXT NOT NULL
+                );
+
+                CREATE TABLE IF NOT EXISTS events (
+                  id INTEGER PRIMARY KEY AUTOINCREMENT,
+                  session_id TEXT NOT NULL,
+                  hook TEXT NOT NULL,
+                  tool_name TEXT,
+                  status TEXT,
+                  payload_json TEXT NOT NULL,
+                  created_at TEXT NOT NULL
+                );
+
+                CREATE TABLE IF NOT EXISTS retry_budget (
+                  session_id TEXT PRIMARY KEY,
+                  attempts INTEGER NOT NULL DEFAULT 0,
+                  updated_at TEXT NOT NULL
+                );
+
+                CREATE TABLE IF NOT EXISTS retry_reason_budget (
+                  session_id TEXT NOT NULL,
+                  reason TEXT NOT NULL,
+                  attempts INTEGER NOT NULL DEFAULT 0,
+                  updated_at TEXT NOT NULL,
+                  PRIMARY KEY (session_id, reason)
+                );
+
+                CREATE TABLE IF NOT EXISTS retry_delta_state (
+                  session_id TEXT NOT NULL,
+                  reason TEXT NOT NULL,
+                  failure_signature TEXT NOT NULL,
+                  last_delta_hash TEXT NOT NULL,
+                  updated_at TEXT NOT NULL,
+                  PRIMARY KEY (session_id, reason, failure_signature)
+                );
+
+                CREATE TABLE IF NOT EXISTS cortex_meta (
+                  key TEXT PRIMARY KEY,
+                  value_text TEXT NOT NULL
+                );
+
+                CREATE TABLE IF NOT EXISTS executive_memory (
+                  id TEXT PRIMARY KEY,
+                  type TEXT NOT NULL,
+                  trigger_pattern TEXT NOT NULL,
+                  error_pattern TEXT NOT NULL,
+                  resolution TEXT NOT NULL,
+                  strength INTEGER NOT NULL DEFAULT 1,
+                  created_at_session INTEGER NOT NULL,
+                  last_accessed_at_session INTEGER NOT NULL,
+                  source_session_id TEXT NOT NULL
+                );
+
+                CREATE TABLE IF NOT EXISTS session_counter_allocations (
+                  session_id TEXT PRIMARY KEY,
+                  counter INTEGER NOT NULL
+                );
+
+                CREATE TABLE IF NOT EXISTS executive_stop_signatures (
+                  session_id TEXT PRIMARY KEY,
+                  signature TEXT NOT NULL,
+                  updated_at TEXT NOT NULL
+                );
+
+                CREATE INDEX IF NOT EXISTS idx_events_session_hook ON events(session_id, hook);
+                CREATE INDEX IF NOT EXISTS idx_graveyard_session ON graveyard(session_id);
+                CREATE INDEX IF NOT EXISTS idx_challenge_results_session_category
+                  ON challenge_results(session_id, category);
+                CREATE INDEX IF NOT EXISTS idx_invariants_session_status
+                  ON invariants(session_id, status);
+                CREATE INDEX IF NOT EXISTS idx_executive_memory_type_strength
+                  ON executive_memory(type, strength DESC);
+                """
+            )
+            self._purge_transient_session_state(conn)
+
+    @contextmanager
+    def connection(self) -> Iterator[sqlite3.Connection]:
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+        conn = sqlite3.connect(self.db_path, timeout=5.0)
+        conn.row_factory = sqlite3.Row
+        conn.execute(f"PRAGMA busy_timeout = {max(0, int(self.busy_timeout_ms))}")
+        try:
+            yield conn
+            conn.commit()
+        finally:
+            conn.close()
+
+    def _run_write(self, operation: Callable[[sqlite3.Connection], None]) -> None:
+        attempts = max(0, int(self.lock_retry_attempts)) + 1
+        backoff = max(0, int(self.lock_retry_backoff_ms)) / 1000.0
+        for attempt in range(attempts):
+            try:
+                with self.connection() as conn:
+                    operation(conn)
+                return
+            except sqlite3.OperationalError as exc:
+                if not self._is_lock_error(exc) or attempt >= attempts - 1:
+                    raise
+                if backoff > 0:
+                    time.sleep(backoff * (2**attempt))
+
+    @staticmethod
+    def _is_lock_error(exc: sqlite3.OperationalError) -> bool:
+        return any(msg in str(exc).lower() for msg in ("database is locked", "database table is locked"))
+
+    def upsert_session_start(
+        self, session_id: str, status: str, genome_path: str | None, metadata: dict[str, Any] | None = None
+    ) -> None:
+        self._execute_write(
+            """
+            INSERT INTO sessions (session_id, started_at, status, genome_path, metadata_json)
+            VALUES (?, ?, ?, ?, ?)
+            ON CONFLICT(session_id) DO UPDATE SET
+              status=excluded.status,
+              genome_path=excluded.genome_path,
+              metadata_json=excluded.metadata_json
+            """,
+            (
+                session_id,
+                _utc_now(),
+                status,
+                genome_path,
+                json.dumps(metadata or {}, sort_keys=True),
+            ),
+        )
+
+    def ensure_session_start(
+        self, session_id: str, status: str, genome_path: str | None, metadata: dict[str, Any] | None = None
+    ) -> None:
+        self._execute_write(
+            """
+            INSERT OR IGNORE INTO sessions (session_id, started_at, status, genome_path, metadata_json)
+            VALUES (?, ?, ?, ?, ?)
+            """,
+            (
+                session_id,
+                _utc_now(),
+                status,
+                genome_path,
+                json.dumps(metadata or {}, sort_keys=True),
+            ),
+        )
+
+    def close_session(self, session_id: str, status: str, metadata: dict[str, Any] | None = None) -> None:
+        now = _utc_now()
+        closed_filter = "session_id IN (SELECT session_id FROM sessions WHERE status != 'running' OR ended_at IS NOT NULL)"
+
+        def _op(conn: sqlite3.Connection) -> None:
+            conn.execute("BEGIN IMMEDIATE")
+            conn.execute(
+                """
+                UPDATE sessions
+                SET ended_at = ?, status = ?, metadata_json = ?
+                WHERE session_id = ?
+                """,
+                (
+                    now,
+                    status,
+                    json.dumps(metadata or {}, sort_keys=True),
+                    session_id,
+                ),
+            )
+            conn.execute(f"DELETE FROM session_counter_allocations WHERE {closed_filter}")
+            conn.execute(
+                f"DELETE FROM executive_stop_signatures WHERE session_id <> ? AND {closed_filter}",
+                (session_id,),
+            )
+
+        self._run_write(_op)
+
+    def record_event(
+        self,
+        session_id: str,
+        hook: str,
+        payload: dict[str, Any],
+        tool_name: str | None = None,
+        status: str | None = None,
+    ) -> None:
+        compacted_payload = self._compact_event_payload(payload)
+        self._execute_write(
+            """
+            INSERT INTO events (session_id, hook, tool_name, status, payload_json, created_at)
+            VALUES (?, ?, ?, ?, ?, ?)
+            """,
+            (
+                session_id,
+                hook,
+                tool_name,
+                status,
+                json.dumps(compacted_payload, sort_keys=True),
+                _utc_now(),
+            ),
+        )
+
+    def get_retry_delta_hash(self, session_id: str, reason: str, failure_signature: str) -> str | None:
+        reason_token = str(reason or "").strip()
+        signature_token = str(failure_signature or "").strip()
+        if not reason_token or not signature_token:
+            return None
+        with self.connection() as conn:
+            row = conn.execute(
+                """
+                SELECT last_delta_hash
+                FROM retry_delta_state
+                WHERE session_id = ? AND reason = ? AND failure_signature = ?
+                LIMIT 1
+                """,
+                (session_id, reason_token, signature_token),
+            ).fetchone()
+        if row is None:
+            return None
+        return str(row["last_delta_hash"] or "")
+
+    def upsert_retry_delta_hash(
+        self,
+        session_id: str,
+        *,
+        reason: str,
+        failure_signature: str,
+        delta_hash: str,
+    ) -> None:
+        reason_token = str(reason or "").strip()
+        signature_token = str(failure_signature or "").strip()
+        if not reason_token or not signature_token:
+            return
+        self._execute_write(
+            """
+            INSERT INTO retry_delta_state (session_id, reason, failure_signature, last_delta_hash, updated_at)
+            VALUES (?, ?, ?, ?, ?)
+            ON CONFLICT(session_id, reason, failure_signature) DO UPDATE SET
+              last_delta_hash = excluded.last_delta_hash,
+              updated_at = excluded.updated_at
+            """,
+            (
+                session_id,
+                reason_token,
+                signature_token,
+                str(delta_hash or ""),
+                _utc_now(),
+            ),
+        )
+
+    def get_retry_attempts(self, session_id: str, *, reason: str) -> dict[str, int]:
+        reason_token = str(reason or "").strip()
+        if not reason_token:
+            return {"attempts": 0, "reason_attempts": 0}
+        with self.connection() as conn:
+            session_row = conn.execute(
+                "SELECT attempts FROM retry_budget WHERE session_id = ?",
+                (session_id,),
+            ).fetchone()
+            reason_row = conn.execute(
+                "SELECT attempts FROM retry_reason_budget WHERE session_id = ? AND reason = ?",
+                (session_id, reason_token),
+            ).fetchone()
+        return {
+            "attempts": int(session_row["attempts"]) if session_row is not None else 0,
+            "reason_attempts": int(reason_row["attempts"]) if reason_row is not None else 0,
+        }
+
+    def try_increment_retry_attempts(
+        self,
+        session_id: str,
+        *,
+        reason: str,
+        expected_attempts: int,
+        expected_reason_attempts: int,
+    ) -> dict[str, int | bool]:
+        reason_token = str(reason or "").strip()
+        outcome: dict[str, int | bool] = {
+            "consumed": False,
+            "attempts": max(0, int(expected_attempts)),
+            "reason_attempts": max(0, int(expected_reason_attempts)),
+        }
+        if not reason_token:
+            return outcome
+
+        def _op(conn: sqlite3.Connection) -> None:
+            now = _utc_now()
+            conn.execute("BEGIN IMMEDIATE")
+            self._ensure_retry_budget_rows(conn, session_id=session_id, reason=reason_token, now=now)
+            session_row = conn.execute(
+                "SELECT attempts FROM retry_budget WHERE session_id = ?",
+                (session_id,),
+            ).fetchone()
+            reason_row = conn.execute(
+                "SELECT attempts FROM retry_reason_budget WHERE session_id = ? AND reason = ?",
+                (session_id, reason_token),
+            ).fetchone()
+            session_attempts = int(session_row["attempts"]) if session_row is not None else 0
+            reason_attempts = int(reason_row["attempts"]) if reason_row is not None else 0
+
+            if (
+                session_attempts == max(0, int(expected_attempts))
+                and reason_attempts == max(0, int(expected_reason_attempts))
+            ):
+                conn.execute(
+                    """
+                    UPDATE retry_budget
+                    SET attempts = attempts + 1, updated_at = ?
+                    WHERE session_id = ?
+                    """,
+                    (now, session_id),
+                )
+                conn.execute(
+                    """
+                    UPDATE retry_reason_budget
+                    SET attempts = attempts + 1, updated_at = ?
+                    WHERE session_id = ? AND reason = ?
+                    """,
+                    (now, session_id, reason_token),
+                )
+                session_attempts += 1
+                reason_attempts += 1
+                outcome["consumed"] = True
+
+            outcome["attempts"] = session_attempts
+            outcome["reason_attempts"] = reason_attempts
+
+        self._run_write(_op)
+        return outcome
+
+    def insert_graveyard(
+        self,
+        session_id: str | None,
+        summary: str,
+        reason: str,
+        files: list[str],
+        keywords: list[str],
+    ) -> None:
+        self._execute_write(
+            """
+            INSERT INTO graveyard (session_id, summary, reason, files_json, keywords_json, created_at)
+            VALUES (?, ?, ?, ?, ?, ?)
+            """,
+            (
+                session_id,
+                summary,
+                reason,
+                json.dumps(files, sort_keys=True),
+                json.dumps(keywords, sort_keys=True),
+                _utc_now(),
+            ),
+        )
+
+    def list_graveyard(self, limit: int = 100) -> list[dict[str, Any]]:
+        rows = self._list_graveyard_rows(limit)
+        return [self._graveyard_row_to_item(row) for row in rows]
+
+    def list_graveyard_fts_candidates(
+        self,
+        *,
+        tokens: list[str],
+        limit: int = 200,
+        candidate_limit: int = 80,
+    ) -> list[dict[str, Any]] | None:
+        terms = [t for t in tokens if _FTS_TOKEN_RE.match(t)]
+        if not terms or not (rows := self._list_graveyard_rows(limit)):
+            return []
+        with self.connection() as conn:
+            try:
+                conn.execute(
+                    "CREATE TEMP VIRTUAL TABLE IF NOT EXISTS _cortex_graveyard_fts "
+                    "USING fts5(entry_id UNINDEXED, text)"
+                )
+                conn.execute("DELETE FROM _cortex_graveyard_fts")
+            except sqlite3.OperationalError:
+                return None
+
+            conn.executemany(
+                "INSERT INTO _cortex_graveyard_fts(entry_id, text) VALUES (?, ?)",
+                [
+                    (
+                        str(row["id"]),
+                        f"{row['summary']} {row['reason']} {row['keywords_json']}",
+                    )
+                    for row in rows
+                ],
+            )
+            match_query = " OR ".join(terms[:12])
+            matched = conn.execute(
+                """
+                SELECT entry_id
+                FROM _cortex_graveyard_fts
+                WHERE _cortex_graveyard_fts MATCH ?
+                ORDER BY bm25(_cortex_graveyard_fts), CAST(entry_id AS INTEGER) DESC
+                LIMIT ?
+                """,
+                (match_query, max(1, int(candidate_limit))),
+            ).fetchall()
+
+        if not matched:
+            return []
+        row_map = {int(row["id"]): row for row in rows}
+        ordered_ids = [int(row["entry_id"]) for row in matched]
+        return [self._graveyard_row_to_item(row_map[eid]) for eid in ordered_ids if eid in row_map]
+
+    def record_invariant_result(
+        self,
+        session_id: str,
+        test_path: str,
+        status: str,
+        duration_ms: int,
+        stdout: str,
+        stderr: str,
+        graduated_from: str | None = None,
+    ) -> None:
+        self._execute_write(
+            """
+            INSERT INTO invariants
+              (session_id, test_path, status, duration_ms, stdout, stderr, graduated_from, created_at)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+            """,
+            (
+                session_id,
+                test_path,
+                status,
+                duration_ms,
+                stdout,
+                stderr,
+                graduated_from,
+                _utc_now(),
+            ),
+        )
+
+    def record_challenge_result(
+        self, session_id: str, category: str, covered: bool, evidence: dict[str, Any] | None = None
+    ) -> None:
+        self._execute_write(
+            """
+            INSERT INTO challenge_results (session_id, category, covered, evidence_json, created_at)
+            VALUES (?, ?, ?, ?, ?)
+            """,
+            (
+                session_id,
+                category,
+                1 if covered else 0,
+                json.dumps(evidence or {}, sort_keys=True),
+                _utc_now(),
+            ),
+        )
+
+    def _execute_write(self, sql: str, params: tuple[Any, ...]) -> None:
+        self._run_write(lambda conn: conn.execute(sql, params))
+
+    def increment_session_counter(self) -> int:
+        result = {"value": 0}
+
+        def _op(conn: sqlite3.Connection) -> None:
+            conn.execute("BEGIN IMMEDIATE")
+            conn.execute("INSERT INTO cortex_meta (key, value_text) VALUES ('session_counter', '0') ON CONFLICT(key) DO NOTHING")
+            conn.execute("UPDATE cortex_meta SET value_text = CAST(COALESCE(value_text, '0') AS INTEGER) + 1 WHERE key = 'session_counter'")
+            row = conn.execute("SELECT value_text FROM cortex_meta WHERE key = 'session_counter'").fetchone()
+            result["value"] = int(row["value_text"]) if row is not None else 0
+
+        self._run_write(_op)
+        return int(result["value"])
+
+    def allocate_session_counter(self, session_id: str) -> int:
+        token = str(session_id or "").strip()
+        if not token:
+            return self.increment_session_counter()
+        result = {"value": 0}
+
+        def _op(conn: sqlite3.Connection) -> None:
+            conn.execute("BEGIN IMMEDIATE")
+            existing = conn.execute(
+                "SELECT counter FROM session_counter_allocations WHERE session_id = ? LIMIT 1",
+                (token,),
+            ).fetchone()
+            if existing is not None:
+                result["value"] = int(existing["counter"])
+                return
+            conn.execute("INSERT INTO cortex_meta (key, value_text) VALUES ('session_counter', '0') ON CONFLICT(key) DO NOTHING")
+            conn.execute("UPDATE cortex_meta SET value_text = CAST(COALESCE(value_text, '0') AS INTEGER) + 1 WHERE key = 'session_counter'")
+            counter = conn.execute("SELECT value_text FROM cortex_meta WHERE key = 'session_counter'").fetchone()
+            allocated = int(counter["value_text"]) if counter is not None else 0
+            conn.execute(
+                """
+                INSERT INTO session_counter_allocations (session_id, counter)
+                VALUES (?, ?)
+                ON CONFLICT(session_id) DO NOTHING
+                """,
+                (token, allocated),
+            )
+            row = conn.execute(
+                "SELECT counter FROM session_counter_allocations WHERE session_id = ? LIMIT 1",
+                (token,),
+            ).fetchone()
+            result["value"] = int(row["counter"]) if row is not None else allocated
+
+        self._run_write(_op)
+        return int(result["value"])
+
+    def claim_executive_stop_signature(self, session_id: str, signature: str) -> bool:
+        sid = str(session_id or "").strip()
+        sig = str(signature or "").strip()
+        if not sid or not sig:
+            return False
+        claimed = {"value": False}
+
+        def _op(conn: sqlite3.Connection) -> None:
+            conn.execute("BEGIN IMMEDIATE")
+            row = conn.execute(
+                "SELECT signature FROM executive_stop_signatures WHERE session_id = ? LIMIT 1",
+                (sid,),
+            ).fetchone()
+            if row is not None and str(row["signature"] or "") == sig:
+                claimed["value"] = False
+                return
+            conn.execute(
+                """
+                INSERT INTO executive_stop_signatures (session_id, signature, updated_at)
+                VALUES (?, ?, ?)
+                ON CONFLICT(session_id) DO UPDATE SET
+                  signature = excluded.signature,
+                  updated_at = excluded.updated_at
+                """,
+                (sid, sig, _utc_now()),
+            )
+            claimed["value"] = True
+
+        self._run_write(_op)
+        return bool(claimed["value"])
+
+    def get_session_count(self) -> int:
+        with self.connection() as conn:
+            row = conn.execute(
+                "SELECT value_text FROM cortex_meta WHERE key = 'session_counter' LIMIT 1"
+            ).fetchone()
+        if row is None:
+            return 0
+        try:
+            return int(row["value_text"])
+        except (TypeError, ValueError):
+            return 0
+
+    def claim_meta_once(self, key: str, value: str = "1") -> bool:
+        token = str(key or "").strip()
+        if not token:
+            return False
+        claimed = {"value": False}
+
+        def _op(conn: sqlite3.Connection) -> None:
+            conn.execute("BEGIN IMMEDIATE")
+            existing = conn.execute(
+                "SELECT 1 FROM cortex_meta WHERE key = ? LIMIT 1",
+                (token,),
+            ).fetchone()
+            if existing is not None:
+                claimed["value"] = False
+                return
+            conn.execute(
+                "INSERT INTO cortex_meta (key, value_text) VALUES (?, ?)",
+                (token, str(value)),
+            )
+            claimed["value"] = True
+
+        self._run_write(_op)
+        return bool(claimed["value"])
+
+    def record_executive_event(
+        self,
+        event_type: str,
+        trigger: str,
+        error: str,
+        resolution: str,
+        session_id: str,
+    ) -> dict[str, Any]:
+        current_session = self.get_session_count()
+        row = {
+            "id": f"exec-{uuid4().hex}",
+            "type": str(event_type),
+            "trigger_pattern": str(trigger),
+            "error_pattern": str(error),
+            "resolution": str(resolution),
+            "strength": 1,
+            "created_at_session": current_session,
+            "last_accessed_at_session": current_session,
+            "source_session_id": str(session_id),
+        }
+        self._execute_write(
+            "INSERT INTO executive_memory (id, type, trigger_pattern, error_pattern, resolution, strength, created_at_session, last_accessed_at_session, source_session_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
+            (
+                row["id"],
+                row["type"],
+                row["trigger_pattern"],
+                row["error_pattern"],
+                row["resolution"],
+                row["strength"],
+                row["created_at_session"],
+                row["last_accessed_at_session"],
+                row["source_session_id"],
+            ),
+        )
+        return row
+
+    def get_executive_memory(self) -> list[dict[str, Any]]:
+        with self.connection() as conn:
+            rows = conn.execute("SELECT id, type, trigger_pattern, error_pattern, resolution, strength, created_at_session, last_accessed_at_session, source_session_id FROM executive_memory ORDER BY created_at_session DESC, id ASC").fetchall()
+        return [
+            {
+                "id": str(row["id"]),
+                "type": str(row["type"]),
+                "trigger_pattern": str(row["trigger_pattern"]),
+                "error_pattern": str(row["error_pattern"]),
+                "resolution": str(row["resolution"]),
+                "strength": int(row["strength"]),
+                "created_at_session": int(row["created_at_session"]),
+                "last_accessed_at_session": int(row["last_accessed_at_session"]),
+                "source_session_id": str(row["source_session_id"]),
+            }
+            for row in rows
+        ]
+
+    def update_executive_entry(
+        self,
+        entry_id: str,
+        *,
+        strength: int | None = None,
+        last_accessed_at_session: int | None = None,
+    ) -> None:
+        updates: list[str] = []
+        params: list[Any] = []
+        if strength is not None:
+            updates.append("strength = ?")
+            params.append(max(1, int(strength)))
+        if last_accessed_at_session is not None:
+            updates.append("last_accessed_at_session = ?")
+            params.append(max(0, int(last_accessed_at_session)))
+        if not updates:
+            return
+        params.append(str(entry_id))
+        self._execute_write(
+            f"UPDATE executive_memory SET {', '.join(updates)} WHERE id = ?",
+            tuple(params),
+        )
+
+    def delete_executive_entries(self, ids: list[str]) -> None:
+        tokens = [str(item).strip() for item in ids if str(item).strip()]
+        if not tokens:
+            return
+        placeholders = ",".join(["?"] * len(tokens))
+        self._execute_write(
+            f"DELETE FROM executive_memory WHERE id IN ({placeholders})",
+            tuple(tokens),
+        )
+
+    @staticmethod
+    def _ensure_retry_budget_rows(conn: sqlite3.Connection, *, session_id: str, reason: str, now: str) -> None:
+        conn.execute(
+            """
+            INSERT INTO retry_budget (session_id, attempts, updated_at)
+            VALUES (?, 0, ?)
+            ON CONFLICT(session_id) DO NOTHING
+            """,
+            (session_id, now),
+        )
+        conn.execute(
+            """
+            INSERT INTO retry_reason_budget (session_id, reason, attempts, updated_at)
+            VALUES (?, ?, 0, ?)
+            ON CONFLICT(session_id, reason) DO NOTHING
+            """,
+            (session_id, reason, now),
+        )
+
+    @staticmethod
+    def _purge_transient_session_state(conn: sqlite3.Connection) -> None:
+        running = "session_id IN (SELECT session_id FROM sessions WHERE status = 'running' AND ended_at IS NULL)"
+        conn.execute(f"DELETE FROM session_counter_allocations WHERE NOT ({running})")
+        conn.execute(f"DELETE FROM executive_stop_signatures WHERE NOT ({running})")
+
+    def _list_graveyard_rows(self, limit: int) -> list[sqlite3.Row]:
+        with self.connection() as conn:
+            return conn.execute(
+                """
+                SELECT id, session_id, summary, reason, files_json, keywords_json, created_at
+                FROM graveyard
+                ORDER BY id DESC
+                LIMIT ?
+                """,
+                (limit,),
+            ).fetchall()
+
+    @staticmethod
+    def _graveyard_row_to_item(row: sqlite3.Row) -> dict[str, Any]:
+        return {
+            "id": row["id"],
+            "session_id": row["session_id"],
+            "summary": row["summary"],
+            "reason": row["reason"],
+            "files": json.loads(row["files_json"]),
+            "keywords": json.loads(row["keywords_json"]),
+            "created_at": row["created_at"],
+        }
+
+    @staticmethod
+    def _compact_event_payload(payload: dict[str, Any]) -> dict[str, Any]:
+        compacted = dict(payload)
+        meta: dict[str, dict[str, Any]] = {}
+        for field in _COMPACT_TEXT_FIELDS:
+            value = compacted.get(field)
+            if not isinstance(value, str) or len(value) <= _COMPACT_TEXT_MAX_LEN:
+                continue
+            meta[field] = {
+                "original_len": len(value),
+                "truncated": True,
+                "sha256": hashlib.sha256(value.encode("utf-8")).hexdigest(),
+            }
+            compacted[field] = value[:_COMPACT_TEXT_MAX_LEN]
+        if meta:
+            compacted["_payload_compaction"] = meta
+        return compacted