pascal-agent 0.3.0__py3-none-any.whl

pascal/state.py

@@ -0,0 +1,790 @@
+"""Pascal state -- SQLite store for the working-document loop.
+
+8 tables + 1 migration:
+  tasks, notifications, rules, run_lock, history, context, todos, memories
+  + checkpoints (created via migration)
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sqlite3
+import uuid
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any
+
+
+_SCHEMA = """
+PRAGMA journal_mode = WAL;
+
+CREATE TABLE IF NOT EXISTS tasks (
+    id TEXT PRIMARY KEY,
+    goal TEXT NOT NULL,
+    status TEXT NOT NULL DEFAULT 'pending'
+        CHECK (status IN ('pending', 'active', 'paused', 'blocked', 'done', 'failed')),
+    progress TEXT DEFAULT '',
+    result TEXT,
+    priority TEXT DEFAULT 'normal' CHECK (priority IN ('urgent', 'normal', 'low')),
+    source TEXT DEFAULT 'human',
+    created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now')),
+    updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
+);
+
+CREATE TABLE IF NOT EXISTS notifications (
+    id TEXT PRIMARY KEY,
+    source TEXT NOT NULL,
+    message TEXT NOT NULL,
+    priority TEXT DEFAULT 'normal' CHECK (priority IN ('urgent', 'normal', 'low')),
+    metadata TEXT DEFAULT '{}',
+    status TEXT DEFAULT 'pending' CHECK (status IN ('pending', 'handled', 'dismissed')),
+    received_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now')),
+    handled_at TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_notif_status ON notifications(status, received_at);
+
+CREATE TABLE IF NOT EXISTS rules (
+    id TEXT PRIMARY KEY,
+    rule TEXT NOT NULL,
+    tier TEXT NOT NULL DEFAULT 'learned'
+        CHECK (tier IN ('policy', 'operator', 'learned', 'ephemeral')),
+    mutable INTEGER NOT NULL DEFAULT 1 CHECK (mutable IN (0, 1)),
+    added_by TEXT NOT NULL DEFAULT 'human' CHECK (added_by IN ('human', 'agent')),
+    expires_at TEXT,
+    created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
+);
+
+-- Concurrency: single-run lock
+CREATE TABLE IF NOT EXISTS run_lock (
+    singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+    locked_by TEXT NOT NULL,
+    locked_at TEXT NOT NULL,
+    expires_at TEXT NOT NULL
+);
+
+
+CREATE TABLE IF NOT EXISTS history (
+    id TEXT PRIMARY KEY,
+    summary TEXT NOT NULL,
+    task_id TEXT REFERENCES tasks(id),
+    details TEXT DEFAULT '{}',
+    idem_key TEXT,
+    action_status TEXT DEFAULT 'ok' CHECK (action_status IN ('ok', 'error', 'unknown')),
+    created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_history_time ON history(created_at);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_history_idem ON history(idem_key) WHERE idem_key IS NOT NULL;
+
+CREATE TRIGGER IF NOT EXISTS history_no_update
+BEFORE UPDATE ON history BEGIN
+    SELECT RAISE(ABORT, 'history is append-only: updates not allowed');
+END;
+
+CREATE TRIGGER IF NOT EXISTS history_no_delete
+BEFORE DELETE ON history BEGIN
+    SELECT RAISE(ABORT, 'history is append-only: deletes not allowed');
+END;
+
+CREATE TABLE IF NOT EXISTS context (
+    key TEXT PRIMARY KEY,
+    value TEXT NOT NULL,
+    updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
+);
+
+CREATE TABLE IF NOT EXISTS todos (
+    id TEXT PRIMARY KEY,
+    task_id TEXT NOT NULL REFERENCES tasks(id),
+    title TEXT NOT NULL,
+    status TEXT NOT NULL DEFAULT 'pending'
+        CHECK (status IN ('pending', 'done', 'skipped')),
+    ordinal INTEGER NOT NULL DEFAULT 0,
+    created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_todos_task ON todos(task_id, ordinal);
+
+CREATE TABLE IF NOT EXISTS memories (
+    id TEXT PRIMARY KEY,
+    kind TEXT NOT NULL CHECK (kind IN ('fact', 'lesson', 'preference', 'procedure')),
+    content TEXT NOT NULL,
+    source_task_id TEXT REFERENCES tasks(id),
+    created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_memories_kind ON memories(kind, created_at);
+
+CREATE TABLE IF NOT EXISTS conversations (
+    id TEXT PRIMARY KEY,
+    channel TEXT NOT NULL,
+    role TEXT NOT NULL CHECK (role IN ('user', 'assistant')),
+    content TEXT NOT NULL,
+    created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_convo_channel ON conversations(channel, created_at DESC);
+
+"""
+
+
+class PascalStore:
+    """Minimal persistence for the Pascal loop."""
+
+    def __init__(self, db_path: str) -> None:
+        path = Path(db_path).expanduser()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        self._conn = sqlite3.connect(str(path))
+        self._conn.row_factory = sqlite3.Row
+        self._conn.execute("PRAGMA foreign_keys = ON")
+        self._conn.executescript(_SCHEMA)
+        self._conn.commit()
+        self._migrate_commitments()
+        self._migrate_context_ttl()
+        self._migrate_checkpoints()
+        self._migrate_memory_fts()
+        self._migrate_memory_decay()
+        self._migrate_task_hierarchy()
+        self._migrate_plan_json()
+
+    @property
+    def connection(self) -> sqlite3.Connection:
+        return self._conn
+
+    def close(self) -> None:
+        self._conn.close()
+
+    # ── Run lock (concurrency) ───────────────────────────────────
+
+    _LOCK_TTL_SECONDS = 600  # 10 minutes (was 5; must exceed _DELEGATE_MAX_TIMEOUT=600s)
+    _lock_owner: str = ""
+
+    def acquire_lock(self, run_id: str) -> bool:
+        """Try to acquire the single-run lock. Returns True if acquired."""
+        now = datetime.now(timezone.utc)
+        expires = now.strftime("%Y-%m-%dT%H:%M:%S.%fZ")
+        new_expires = (now + timedelta(seconds=self._LOCK_TTL_SECONDS)).strftime(
+            "%Y-%m-%dT%H:%M:%S.%fZ"
+        )
+        # Clear expired locks
+        self._conn.execute(
+            "DELETE FROM run_lock WHERE expires_at < ?", (expires,),
+        )
+        try:
+            self._conn.execute(
+                "INSERT INTO run_lock (singleton, locked_by, locked_at, expires_at) VALUES (1, ?, ?, ?)",
+                (run_id, expires, new_expires),
+            )
+            self._conn.commit()
+            self._lock_owner = run_id
+            return True
+        except sqlite3.IntegrityError:
+            return False
+
+    def refresh_lock(self) -> None:
+        """Extend the lock TTL. Only the lock owner can refresh."""
+        if not self._lock_owner:
+            return
+        new_expires = (
+            datetime.now(timezone.utc) + timedelta(seconds=self._LOCK_TTL_SECONDS)
+        ).strftime("%Y-%m-%dT%H:%M:%S.%fZ")
+        self._conn.execute(
+            "UPDATE run_lock SET expires_at = ? WHERE singleton = 1 AND locked_by = ?",
+            (new_expires, self._lock_owner),
+        )
+        self._conn.commit()
+
+    def release_lock(self, force: bool = False) -> None:
+        """Release the lock. Only the lock owner can release, unless force=True."""
+        if self._lock_owner:
+            self._conn.execute(
+                "DELETE FROM run_lock WHERE singleton = 1 AND locked_by = ?",
+                (self._lock_owner,),
+            )
+        elif force:
+            # Daemon startup: clear stale/expired locks from previous crash
+            now = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%fZ")
+            self._conn.execute(
+                "DELETE FROM run_lock WHERE singleton = 1 AND expires_at < ?",
+                (now,),
+            )
+        self._conn.commit()
+        self._lock_owner = ""
+
+    # ── Tasks ────────────────────────────────────────────────────
+
+    # Valid state transitions -- any transition not here is rejected
+    _TASK_TRANSITIONS: dict[str, set[str]] = {
+        "pending": {"active", "blocked", "done", "failed"},
+        "active": {"paused", "blocked", "done", "failed"},
+        "paused": {"active", "done", "failed"},
+        "blocked": {"active", "done", "failed"},
+        "done": set(),      # terminal
+        "failed": {"active", "pending"},  # can retry
+    }
+
+    def add_task(
+        self,
+        goal: str,
+        *,
+        priority: str = "normal",
+        source: str = "human",
+        promised_to: list[str] | None = None,
+        due_at: str | None = None,
+        proof_required: list[str] | None = None,
+        depends_on: list[str] | None = None,
+        parent_id: str | None = None,
+    ) -> str:
+        task_id = _make_id("task")
+        self._conn.execute(
+            "INSERT INTO tasks (id, goal, priority, source, promised_to, due_at, proof_required, depends_on, parent_id) "
+            "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
+            (task_id, goal, priority, source,
+             json.dumps(promised_to) if promised_to else None,
+             due_at,
+             json.dumps(proof_required) if proof_required else None,
+             json.dumps(depends_on) if depends_on else None,
+             parent_id),
+        )
+        self._conn.commit()
+        return task_id
+
+    def get_active_task(self) -> dict[str, Any] | None:
+        row = self._conn.execute(
+            "SELECT * FROM tasks WHERE status = 'active' ORDER BY updated_at DESC LIMIT 1",
+        ).fetchone()
+        return dict(row) if row else None
+
+    def get_pending_tasks(self) -> list[dict[str, Any]]:
+        rows = self._conn.execute(
+            """SELECT * FROM tasks WHERE status = 'pending'
+               ORDER BY CASE priority WHEN 'urgent' THEN 0 WHEN 'normal' THEN 1 ELSE 2 END,
+                        created_at ASC""",
+        ).fetchall()
+        return [dict(r) for r in rows]
+
+    def activate_task(self, task_id: str) -> None:
+        task = self._conn.execute("SELECT status FROM tasks WHERE id = ?", (task_id,)).fetchone()
+        if task is None:
+            raise KeyError(f"Unknown task: {task_id}")
+        allowed = self._TASK_TRANSITIONS.get(task["status"], set())
+        if "active" not in allowed:
+            raise ValueError(f"Cannot activate task in '{task['status']}' state (allowed: {allowed})")
+        # Ensure single active task invariant
+        self._conn.execute(
+            "UPDATE tasks SET status = 'paused', updated_at = strftime('%Y-%m-%dT%H:%M:%fZ','now') "
+            "WHERE status = 'active' AND id != ?",
+            (task_id,),
+        )
+        self._conn.execute(
+            "UPDATE tasks SET status = 'active', updated_at = strftime('%Y-%m-%dT%H:%M:%fZ','now') WHERE id = ?",
+            (task_id,),
+        )
+        self._conn.commit()
+
+    def update_task(self, task_id: str, *, status: str | None = None, progress: str | None = None, result: str | None = None) -> None:
+        task = self._conn.execute("SELECT * FROM tasks WHERE id = ?", (task_id,)).fetchone()
+        if task is None:
+            raise KeyError(f"Unknown task: {task_id}")
+        # Enforce valid state transitions
+        if status is not None and status != task["status"]:
+            allowed = self._TASK_TRANSITIONS.get(task["status"], set())
+            if status not in allowed:
+                raise ValueError(
+                    f"Invalid task transition: {task['status']} → {status} "
+                    f"(allowed: {allowed or 'none -- terminal state'})"
+                )
+        self._conn.execute(
+            """UPDATE tasks SET status = ?, progress = ?, result = ?,
+               updated_at = strftime('%Y-%m-%dT%H:%M:%fZ','now') WHERE id = ?""",
+            (
+                status if status is not None else task["status"],
+                progress if progress is not None else task["progress"],
+                result if result is not None else task["result"],
+                task_id,
+            ),
+        )
+        self._conn.commit()
+
+    def pause_active_task(self, reason: str = "") -> str | None:
+        """Pause the current active task. Returns task_id if paused."""
+        active = self.get_active_task()
+        if active is None:
+            return None
+        self.update_task(active["id"], status="paused", progress=f"Paused: {reason}")
+        return active["id"]
+
+    # ── Plan Tree ─────────────────────────────────────────────────
+
+    def get_task_plan(self, task_id: str) -> dict[str, Any] | None:
+        """Get the plan tree for a task. Returns raw dict or None."""
+        row = self._conn.execute(
+            "SELECT plan_json FROM tasks WHERE id = ?", (task_id,),
+        ).fetchone()
+        if row is None or not row["plan_json"]:
+            return None
+        try:
+            return json.loads(row["plan_json"])
+        except (json.JSONDecodeError, TypeError):
+            return None
+
+    def set_task_plan(self, task_id: str, plan: dict[str, Any]) -> None:
+        """Store/update the plan tree for a task."""
+        self._conn.execute(
+            "UPDATE tasks SET plan_json = ?, updated_at = strftime('%Y-%m-%dT%H:%M:%fZ','now') WHERE id = ?",
+            (json.dumps(plan, ensure_ascii=False, default=_json_safe), task_id),
+        )
+        self._conn.commit()
+
+    def clear_task_plan(self, task_id: str) -> None:
+        """Remove the plan tree from a task."""
+        self._conn.execute(
+            "UPDATE tasks SET plan_json = NULL, updated_at = strftime('%Y-%m-%dT%H:%M:%fZ','now') WHERE id = ?",
+            (task_id,),
+        )
+        self._conn.commit()
+
+    # ── Notifications ────────────────────────────────────────────
+
+    def push_notification(self, *, source: str, message: str, priority: str = "normal", metadata: dict[str, Any] | None = None) -> str:
+        notif_id = _make_id("notif")
+        self._conn.execute(
+            "INSERT INTO notifications (id, source, message, priority, metadata) VALUES (?, ?, ?, ?, ?)",
+            (notif_id, source, message, priority, json.dumps(metadata or {}, ensure_ascii=False, default=_json_safe)),
+        )
+        self._conn.commit()
+        return notif_id
+
+    def get_pending_notifications(self) -> list[dict[str, Any]]:
+        rows = self._conn.execute(
+            """SELECT * FROM notifications WHERE status = 'pending'
+               ORDER BY CASE priority WHEN 'urgent' THEN 0 WHEN 'normal' THEN 1 ELSE 2 END,
+                        received_at ASC""",
+        ).fetchall()
+        return [dict(r) for r in rows]
+
+    def handle_notification(self, notif_id: str) -> None:
+        self._conn.execute(
+            "UPDATE notifications SET status = 'handled', handled_at = strftime('%Y-%m-%dT%H:%M:%fZ','now') WHERE id = ?",
+            (notif_id,),
+        )
+        self._conn.commit()
+
+    def dismiss_notification(self, notif_id: str) -> None:
+        self._conn.execute(
+            "UPDATE notifications SET status = 'dismissed', handled_at = strftime('%Y-%m-%dT%H:%M:%fZ','now') WHERE id = ?",
+            (notif_id,),
+        )
+        self._conn.commit()
+
+    # ── Rules ────────────────────────────────────────────────────
+
+    _RULE_TIERS = ("policy", "operator", "learned", "ephemeral")
+
+    def add_rule(self, rule: str, *, tier: str = "learned", mutable: bool = True, added_by: str = "human", ttl_hours: int | None = None) -> str:
+        if tier not in self._RULE_TIERS:
+            tier = "learned"
+        # policy tier is always immutable, agent cannot add policy/operator
+        if tier == "policy":
+            mutable = False
+            added_by = "human"
+        if tier == "operator" and added_by == "agent":
+            tier = "learned"  # agent can't escalate to operator tier
+        expires_at = None
+        if tier == "ephemeral" or ttl_hours is not None:
+            hours = ttl_hours if ttl_hours is not None else 24
+            expires_at = (datetime.now(timezone.utc) + timedelta(hours=hours)).strftime(
+                "%Y-%m-%dT%H:%M:%S.%fZ"
+            )
+        rule_id = _make_id("rule")
+        self._conn.execute(
+            "INSERT INTO rules (id, rule, tier, mutable, added_by, expires_at) VALUES (?, ?, ?, ?, ?, ?)",
+            (rule_id, rule, tier, int(mutable), added_by, expires_at),
+        )
+        self._conn.commit()
+        return rule_id
+
+    def get_rules(self) -> list[dict[str, Any]]:
+        # Clean expired ephemeral rules
+        now = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%fZ")
+        self._conn.execute(
+            "DELETE FROM rules WHERE expires_at IS NOT NULL AND expires_at < ?", (now,),
+        )
+        self._conn.commit()
+        # Return sorted by tier priority: policy > operator > learned > ephemeral
+        rows = self._conn.execute(
+            """SELECT * FROM rules ORDER BY
+               CASE tier WHEN 'policy' THEN 0 WHEN 'operator' THEN 1
+                         WHEN 'learned' THEN 2 WHEN 'ephemeral' THEN 3 END,
+               created_at ASC""",
+        ).fetchall()
+        return [dict(r) for r in rows]
+
+    def remove_rule(self, rule_id: str) -> bool:
+        """Remove a mutable rule. Returns False if rule is immutable."""
+        rule = self._conn.execute("SELECT mutable FROM rules WHERE id = ?", (rule_id,)).fetchone()
+        if rule is None:
+            return False
+        if not rule["mutable"]:
+            return False
+        self._conn.execute("DELETE FROM rules WHERE id = ?", (rule_id,))
+        self._conn.commit()
+        return True
+
+    # ── History ──────────────────────────────────────────────────
+
+    def record(
+        self,
+        summary: str,
+        *,
+        task_id: str | None = None,
+        details: dict[str, Any] | None = None,
+        idem_key: str | None = None,
+        action_status: str = "ok",
+    ) -> None:
+        if action_status not in ("ok", "error", "unknown"):
+            action_status = "ok"
+        try:
+            self._conn.execute(
+                "INSERT OR IGNORE INTO history (id, summary, task_id, details, idem_key, action_status) "
+                "VALUES (?, ?, ?, ?, ?, ?)",
+                (_make_id("hist"), summary, task_id, json.dumps(details or {}, ensure_ascii=False, default=_json_safe),
+                 idem_key, action_status),
+            )
+            self._conn.commit()
+        except sqlite3.IntegrityError:
+            pass  # duplicate idem_key
+
+    def get_recent_history(self, limit: int = 10) -> list[dict[str, Any]]:
+        rows = self._conn.execute(
+            "SELECT * FROM history ORDER BY created_at DESC LIMIT ?", (limit,),
+        ).fetchall()
+        return [dict(r) for r in reversed(rows)]
+
+    def get_context(self, key: str) -> Any | None:
+        row = self._conn.execute("SELECT value FROM context WHERE key = ?", (key,)).fetchone()
+        if row is None:
+            return None
+        try:
+            return json.loads(row["value"])
+        except (json.JSONDecodeError, TypeError):
+            return row["value"]
+
+    # ── TODOs ─────────────────────────────────────────────────────
+
+    def add_todo(self, *, task_id: str, title: str) -> str:
+        todo_id = _make_id("todo")
+        max_ord = self._conn.execute(
+            "SELECT COALESCE(MAX(ordinal), 0) AS m FROM todos WHERE task_id = ?",
+            (task_id,),
+        ).fetchone()["m"]
+        self._conn.execute(
+            "INSERT INTO todos (id, task_id, title, ordinal) VALUES (?, ?, ?, ?)",
+            (todo_id, task_id, title, max_ord + 1),
+        )
+        self._conn.commit()
+        return todo_id
+
+    def complete_todo(self, todo_id: str) -> None:
+        self._conn.execute(
+            "UPDATE todos SET status = 'done' WHERE id = ?", (todo_id,),
+        )
+        self._conn.commit()
+
+    def get_todos(self, task_id: str) -> list[dict[str, Any]]:
+        rows = self._conn.execute(
+            "SELECT * FROM todos WHERE task_id = ? ORDER BY ordinal ASC",
+            (task_id,),
+        ).fetchall()
+        return [dict(r) for r in rows]
+
+    # ── Memories ─────────────────────────────────────────────────
+
+    def add_memory(self, *, kind: str, content: str, source_task_id: str | None = None) -> str:
+        # Dedup: skip if identical memory already exists
+        existing = self._conn.execute(
+            "SELECT id FROM memories WHERE kind = ? AND content = ? LIMIT 1",
+            (kind, content.strip()),
+        ).fetchone()
+        if existing:
+            return existing["id"]
+
+        mem_id = _make_id("mem")
+        self._conn.execute(
+            "INSERT INTO memories (id, kind, content, source_task_id) VALUES (?, ?, ?, ?)",
+            (mem_id, kind, content, source_task_id),
+        )
+        # Update FTS index
+        try:
+            rowid = self._conn.execute("SELECT rowid FROM memories WHERE id = ?", (mem_id,)).fetchone()
+            if rowid:
+                self._conn.execute(
+                    "INSERT INTO memories_fts(rowid, content, kind) VALUES (?, ?, ?)",
+                    (rowid[0], content, kind),
+                )
+        except Exception:
+            pass  # FTS update failure is non-fatal
+        self._conn.commit()
+        return mem_id
+
+    def delete_memory(self, mem_id: str) -> bool:
+        """Delete a memory and its FTS5 index entry. Returns True if deleted."""
+        row = self._conn.execute(
+            "SELECT rowid, content, kind FROM memories WHERE id = ?", (mem_id,),
+        ).fetchone()
+        if not row:
+            return False
+        # Remove from FTS5 content-synced table (requires explicit delete command)
+        try:
+            self._conn.execute(
+                "INSERT INTO memories_fts(memories_fts, rowid, content, kind) VALUES('delete', ?, ?, ?)",
+                (row["rowid"], row["content"], row["kind"]),
+            )
+        except Exception:
+            pass  # FTS cleanup failure is non-fatal
+        self._conn.execute("DELETE FROM memories WHERE id = ?", (mem_id,))
+        self._conn.commit()
+        return True
+
+    def get_memories(self, *, kind: str | None = None, limit: int = 20) -> list[dict[str, Any]]:
+        if kind:
+            rows = self._conn.execute(
+                "SELECT * FROM memories WHERE kind = ? ORDER BY created_at DESC LIMIT ?",
+                (kind, limit),
+            ).fetchall()
+        else:
+            rows = self._conn.execute(
+                "SELECT * FROM memories ORDER BY created_at DESC LIMIT ?",
+                (limit,),
+            ).fetchall()
+        return [dict(r) for r in rows]
+
+    def search_memories(self, query: str, *, limit: int = 8) -> list[dict[str, Any]]:
+        """Search memories by relevance using FTS5. Falls back to recent if no match."""
+        if not query or not query.strip():
+            return self.get_memories(limit=limit)
+        try:
+            # Sanitize: keep only alphanumeric + spaces, strip FTS5 special chars
+            import re as _re
+            clean = _re.sub(r'[^\w\s]', ' ', query)
+            tokens = [t for t in clean.split() if t.strip() and len(t) > 1]
+            if not tokens:
+                return self.get_memories(limit=limit)
+            fts_query = " OR ".join(f'"{t}"*' for t in tokens[:10])  # quoted + prefix
+            rows = self._conn.execute(
+                """SELECT m.* FROM memories m
+                   JOIN memories_fts f ON m.rowid = f.rowid
+                   WHERE memories_fts MATCH ?
+                   ORDER BY rank
+                   LIMIT ?""",
+                (fts_query, limit),
+            ).fetchall()
+            if rows:
+                return [dict(r) for r in rows]
+        except Exception:
+            pass
+        # Fallback: recent memories
+        return self.get_memories(limit=limit)
+
+    # ── Conversations ─────────────────────────────────────────────
+
+    def push_conversation_turn(self, channel: str, role: str, content: str) -> str:
+        turn_id = _make_id("conv")
+        self._conn.execute(
+            "INSERT INTO conversations (id, channel, role, content) VALUES (?, ?, ?, ?)",
+            (turn_id, channel, role, content),
+        )
+        self._conn.commit()
+        return turn_id
+
+    def get_recent_conversation(self, channel: str, limit: int = 10) -> list[dict[str, Any]]:
+        rows = self._conn.execute(
+            "SELECT * FROM conversations WHERE channel = ? ORDER BY created_at DESC LIMIT ?",
+            (channel, limit),
+        ).fetchall()
+        return [dict(r) for r in reversed(rows)]  # oldest first for natural reading
+
+    # ── Context (with TTL) ───────────────────────────────────────
+
+    def set_context(self, key: str, value: Any, ttl_hours: int | None = None) -> None:
+        expires_at = None
+        if ttl_hours is not None and ttl_hours > 0:
+            expires_at = (datetime.now(timezone.utc) + timedelta(hours=ttl_hours)).strftime(
+                "%Y-%m-%dT%H:%M:%S.%fZ"
+            )
+        val = json.dumps(value, ensure_ascii=False, default=_json_safe) if not isinstance(value, str) else value
+        self._conn.execute(
+            """INSERT INTO context (key, value, expires_at, updated_at)
+               VALUES (?, ?, ?, strftime('%Y-%m-%dT%H:%M:%fZ','now'))
+               ON CONFLICT(key) DO UPDATE SET value=excluded.value, expires_at=excluded.expires_at,
+               updated_at=strftime('%Y-%m-%dT%H:%M:%fZ','now')""",
+            (key, val, expires_at),
+        )
+        self._conn.commit()
+        self._enforce_context_limit()
+
+    def get_all_context(self) -> dict[str, Any]:
+        self.cleanup_expired_context()
+        rows = self._conn.execute("SELECT key, value FROM context ORDER BY key").fetchall()
+        result = {}
+        for row in rows:
+            try:
+                result[row["key"]] = json.loads(row["value"])
+            except (json.JSONDecodeError, TypeError):
+                result[row["key"]] = row["value"]
+        return result
+
+    def cleanup_expired_context(self) -> int:
+        now = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%fZ")
+        cursor = self._conn.execute(
+            "DELETE FROM context WHERE expires_at IS NOT NULL AND expires_at < ?", (now,),
+        )
+        self._conn.commit()
+        return cursor.rowcount
+
+    def _enforce_context_limit(self, max_entries: int = 100) -> None:
+        count = self._conn.execute("SELECT COUNT(*) FROM context").fetchone()[0]
+        if count <= max_entries:
+            return
+        to_delete = count - max_entries
+        self._conn.execute(
+            "DELETE FROM context WHERE key IN "
+            "(SELECT key FROM context ORDER BY updated_at ASC LIMIT ?)",
+            (to_delete,),
+        )
+        self._conn.commit()
+
+    # ── Checkpoints ──────────────────────────────────────────────
+
+    def save_checkpoint(self, task_id: str, iteration: int, loop_state: dict[str, Any]) -> str:
+        cp_id = _make_id("cp")
+        pending_notifs = [r["id"] for r in self._conn.execute(
+            "SELECT id FROM notifications WHERE status = 'pending'"
+        ).fetchall()]
+        recent_hist = [r["id"] for r in self._conn.execute(
+            "SELECT id FROM history ORDER BY created_at DESC LIMIT 5"
+        ).fetchall()]
+        ctx_keys = [r["key"] for r in self._conn.execute("SELECT key FROM context").fetchall()]
+        task = self.get_active_task() or {}
+        snapshot = {
+            "task_id": task_id,
+            "task_status": task.get("status"),
+            "task_progress": task.get("progress"),
+            "iteration": iteration,
+            "has_unknown_step": loop_state.get("has_unknown_step", False),
+            "thought_buffer": loop_state.get("thought_buffer", []),
+            "error_feedback": loop_state.get("error_feedback", ""),
+            "active_context_keys": ctx_keys,
+            "pending_notification_ids": pending_notifs,
+            "recent_history_ids": recent_hist,
+        }
+        self._conn.execute(
+            "INSERT INTO checkpoints (id, task_id, iteration, snapshot_json) VALUES (?, ?, ?, ?)",
+            (cp_id, task_id, iteration, json.dumps(snapshot, ensure_ascii=False, default=_json_safe)),
+        )
+        self._conn.commit()
+        self._prune_checkpoints(task_id)
+        return cp_id
+
+    def get_latest_checkpoint(self, task_id: str) -> dict[str, Any] | None:
+        row = self._conn.execute(
+            "SELECT * FROM checkpoints WHERE task_id = ? ORDER BY iteration DESC, created_at DESC LIMIT 1",
+            (task_id,),
+        ).fetchone()
+        if not row:
+            return None
+        return {
+            "id": row["id"], "task_id": row["task_id"],
+            "iteration": row["iteration"],
+            "snapshot": json.loads(row["snapshot_json"]),
+            "created_at": row["created_at"],
+        }
+
+    def _prune_checkpoints(self, task_id: str, keep: int = 10) -> None:
+        self._conn.execute(
+            "DELETE FROM checkpoints WHERE task_id = ? AND id NOT IN "
+            "(SELECT id FROM checkpoints WHERE task_id = ? ORDER BY created_at DESC LIMIT ?)",
+            (task_id, task_id, keep),
+        )
+        self._conn.commit()
+
+    # ── Migrations ───────────────────────────────────────────────
+
+    # Whitelist of valid identifiers for dynamic SQL in migrations
+    _VALID_TABLES = frozenset({"tasks", "context", "memories", "checkpoints", "notifications", "rules", "history", "conversations", "todos"})
+    _VALID_COL_TYPES = frozenset({"TEXT", "INTEGER", "REAL", "BLOB", "INTEGER DEFAULT 0"})
+    _IDENT_RE = re.compile(r"^[a-zA-Z_][a-zA-Z0-9_]*$")
+
+    def _ensure_column(self, table: str, column: str, col_type: str = "TEXT") -> None:
+        # Validate identifiers to prevent SQL injection (defense-in-depth)
+        if table not in self._VALID_TABLES:
+            raise ValueError(f"Invalid table name for migration: {table}")
+        if not self._IDENT_RE.match(column):
+            raise ValueError(f"Invalid column name for migration: {column}")
+        if col_type not in self._VALID_COL_TYPES:
+            raise ValueError(f"Invalid column type for migration: {col_type}")
+        try:
+            self._conn.execute(f"ALTER TABLE {table} ADD COLUMN {column} {col_type}")
+            self._conn.commit()
+        except sqlite3.OperationalError:
+            pass
+
+    def _migrate_commitments(self) -> None:
+        for col in ("promised_to", "due_at", "proof_required", "depends_on"):
+            self._ensure_column("tasks", col)
+
+    def _migrate_context_ttl(self) -> None:
+        self._ensure_column("context", "expires_at")
+
+    def _migrate_checkpoints(self) -> None:
+        self._conn.executescript("""
+            CREATE TABLE IF NOT EXISTS checkpoints (
+                id TEXT PRIMARY KEY,
+                task_id TEXT NOT NULL REFERENCES tasks(id),
+                iteration INTEGER NOT NULL,
+                snapshot_json TEXT NOT NULL,
+                created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
+            );
+            CREATE INDEX IF NOT EXISTS idx_checkpoints_task
+                ON checkpoints(task_id, created_at DESC);
+        """)
+        self._conn.commit()
+
+    def _migrate_memory_fts(self) -> None:
+        """Create FTS5 virtual table for memory search."""
+        self._conn.executescript("""
+            CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts
+                USING fts5(content, kind, content=memories, content_rowid=rowid);
+        """)
+        # Populate FTS from existing data (skip rows already indexed)
+        self._conn.execute("""
+            INSERT INTO memories_fts(rowid, content, kind)
+            SELECT m.rowid, m.content, m.kind FROM memories m
+            WHERE m.rowid NOT IN (SELECT rowid FROM memories_fts)
+        """)
+        self._conn.commit()
+
+    def _migrate_memory_decay(self) -> None:
+        """Add access tracking for memory decay."""
+        self._ensure_column("memories", "access_count", "INTEGER DEFAULT 0")
+        self._ensure_column("memories", "last_accessed", "TEXT")
+
+    def _migrate_task_hierarchy(self) -> None:
+        """Add parent_id for hierarchical task decomposition."""
+        self._ensure_column("tasks", "parent_id", "TEXT")
+
+    def _migrate_plan_json(self) -> None:
+        """Add plan_json for plan tree storage."""
+        self._ensure_column("tasks", "plan_json", "TEXT")
+
+
+def _json_safe(obj):
+    """Handle non-serializable objects in json.dumps (ContentBlock, etc.)."""
+    if hasattr(obj, '__dataclass_fields__'):
+        return {k: getattr(obj, k) for k in obj.__dataclass_fields__ if k != 'data'}
+    return f"<{type(obj).__name__}>"
+
+
+def _make_id(prefix: str) -> str:
+    return f"{prefix}_{uuid.uuid4().hex[:10]}"