devmem-agents 0.1.0__py3-none-any.whl

devmem/storage/record_store.py

@@ -0,0 +1,974 @@
+"""Persistent record store for devmem sessions, artifacts, decisions, etc.
+
+Two backends:
+
+- `MemoryRecordStore`: process-local lists. Default when no DSN is configured.
+  Fine for tests; loses all state on restart.
+- `SqlRecordStore`: SQLAlchemy-backed persistence (Postgres/Aurora, SQLite).
+  Used when `DEVMEM_RECORD_STORE_DSN` is set. Survives restarts.
+
+Both implement the same interface so `DevMemService` is agnostic to the backend.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import threading
+from abc import ABC, abstractmethod
+from datetime import datetime, timezone
+from typing import Any
+
+from devmem.embeddings import cosine_similarity, embed_one
+
+logger = logging.getLogger(__name__)
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _iso_to_ts(value: str | None) -> float:
+    if not value:
+        return 0.0
+    try:
+        return datetime.fromisoformat(value.replace("Z", "+00:00")).timestamp()
+    except Exception:
+        return 0.0
+
+
+class RecordStore(ABC):
+    """Abstract persistence layer for session-scoped records."""
+
+    # ---- sessions --------------------------------------------------------
+
+    @abstractmethod
+    def create_session(
+        self,
+        *,
+        session_id: str,
+        namespace: str,
+        project: str,
+        repo: str,
+        branch: str,
+        agent: str,
+        task: str,
+        started_at: str,
+        task_embedding: list[float] | None,
+    ) -> None:
+        ...
+
+    @abstractmethod
+    def list_sessions(
+        self,
+        *,
+        namespace: str,
+        project: str | None = None,
+        repo: str | None = None,
+        limit: int = 100,
+    ) -> list[dict[str, Any]]:
+        ...
+
+    # ---- artifacts -------------------------------------------------------
+
+    @abstractmethod
+    def insert_artifact(self, *, namespace: str, payload: dict[str, Any]) -> dict[str, Any]:
+        ...
+
+    @abstractmethod
+    def query_artifacts(
+        self,
+        *,
+        namespace: str,
+        project: str | None = None,
+        repo: str | None = None,
+        session_id: str | None = None,
+        artifact_type: str | None = None,
+        since: str | None = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> list[dict[str, Any]]:
+        ...
+
+    # ---- decisions -------------------------------------------------------
+
+    @abstractmethod
+    def insert_decision(self, *, namespace: str, payload: dict[str, Any]) -> dict[str, Any]:
+        ...
+
+    @abstractmethod
+    def query_decisions(
+        self,
+        *,
+        namespace: str,
+        project: str | None = None,
+        repo: str | None = None,
+        session_id: str | None = None,
+        since: str | None = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> list[dict[str, Any]]:
+        ...
+
+    # ---- handoffs --------------------------------------------------------
+
+    @abstractmethod
+    def insert_handoff(self, *, namespace: str, payload: dict[str, Any]) -> dict[str, Any]:
+        ...
+
+    @abstractmethod
+    def query_handoffs(
+        self,
+        *,
+        namespace: str,
+        project: str | None = None,
+        repo: str | None = None,
+        session_id: str | None = None,
+        since: str | None = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> list[dict[str, Any]]:
+        ...
+
+    # ---- misc write endpoints -------------------------------------------
+
+    @abstractmethod
+    def insert_fact(self, *, namespace: str, payload: dict[str, Any]) -> dict[str, Any]:
+        ...
+
+    @abstractmethod
+    def insert_task_update(self, *, namespace: str, payload: dict[str, Any]) -> dict[str, Any]:
+        ...
+
+    @abstractmethod
+    def insert_feedback(self, *, namespace: str, payload: dict[str, Any]) -> dict[str, Any]:
+        ...
+
+    # ---- similarity ------------------------------------------------------
+
+    @abstractmethod
+    def similar_tasks(
+        self,
+        *,
+        namespace: str,
+        task_embedding: list[float],
+        project: str | None = None,
+        repo: str | None = None,
+        top_k: int = 5,
+    ) -> list[dict[str, Any]]:
+        ...
+
+    # ---- atomic commit ---------------------------------------------------
+
+    @abstractmethod
+    def commit_session(
+        self,
+        *,
+        namespace: str,
+        session_id: str,
+        artifacts: list[dict[str, Any]],
+        decisions: list[dict[str, Any]],
+        handoff: dict[str, Any] | None,
+        task_update: dict[str, Any] | None,
+        client_commit_id: str | None,
+    ) -> dict[str, Any]:
+        """Atomically insert all session artifacts/decisions/handoff/task_update.
+
+        If `client_commit_id` is provided and was previously committed in this
+        namespace, return the cached result WITHOUT re-inserting (idempotent
+        retry). If any insert raises, the entire batch rolls back.
+        """
+        ...
+
+
+# --------------------------------------------------------------------------
+# In-memory backend
+# --------------------------------------------------------------------------
+
+
+class MemoryRecordStore(RecordStore):
+    """Process-local store. Thread-safe; loses data on restart."""
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._sessions: dict[str, dict[str, Any]] = {}
+        self._artifacts: list[dict[str, Any]] = []
+        self._facts: list[dict[str, Any]] = []
+        self._decisions: list[dict[str, Any]] = []
+        self._handoffs: list[dict[str, Any]] = []
+        self._updates: list[dict[str, Any]] = []
+        self._feedback: list[dict[str, Any]] = []
+        # (namespace, client_commit_id) -> cached commit response
+        self._commit_cache: dict[tuple[str, str], dict[str, Any]] = {}
+
+    # ---- sessions --------------------------------------------------------
+
+    def create_session(
+        self,
+        *,
+        session_id: str,
+        namespace: str,
+        project: str,
+        repo: str,
+        branch: str,
+        agent: str,
+        task: str,
+        started_at: str,
+        task_embedding: list[float] | None,
+    ) -> None:
+        with self._lock:
+            self._sessions[session_id] = {
+                "session_id": session_id,
+                "namespace": namespace,
+                "project": project,
+                "repo": repo,
+                "branch": branch,
+                "agent": agent,
+                "task": task,
+                "started_at": started_at,
+                "task_embedding": task_embedding,
+            }
+
+    def list_sessions(
+        self,
+        *,
+        namespace: str,
+        project: str | None = None,
+        repo: str | None = None,
+        limit: int = 100,
+    ) -> list[dict[str, Any]]:
+        with self._lock:
+            rows = [
+                {k: v for k, v in s.items() if k != "task_embedding"}
+                for s in self._sessions.values()
+                if s["namespace"] == namespace
+                and (project is None or s["project"] == project)
+                and (repo is None or s["repo"] == repo)
+            ]
+        rows.sort(key=lambda r: _iso_to_ts(r.get("started_at")), reverse=True)
+        return rows[:limit]
+
+    # ---- artifacts -------------------------------------------------------
+
+    def insert_artifact(self, *, namespace: str, payload: dict[str, Any]) -> dict[str, Any]:
+        with self._lock:
+            record = {**payload, "namespace": namespace, "created_at": _now_iso()}
+            self._artifacts.append(record)
+            record_with_id = {"artifact_id": len(self._artifacts), "record": record}
+            record["artifact_id"] = record_with_id["artifact_id"]
+            return record_with_id
+
+    def query_artifacts(
+        self,
+        *,
+        namespace: str,
+        project: str | None = None,
+        repo: str | None = None,
+        session_id: str | None = None,
+        artifact_type: str | None = None,
+        since: str | None = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> list[dict[str, Any]]:
+        since_ts = _iso_to_ts(since) if since else 0.0
+        with self._lock:
+            rows = [
+                r
+                for r in self._artifacts
+                if r.get("namespace") == namespace
+                and (project is None or r.get("project") == project)
+                and (repo is None or r.get("repo") == repo)
+                and (session_id is None or r.get("session_id") == session_id)
+                and (artifact_type is None or r.get("artifact_type") == artifact_type)
+                and (not since_ts or _iso_to_ts(r.get("created_at")) >= since_ts)
+            ]
+        rows.sort(key=lambda r: _iso_to_ts(r.get("created_at")), reverse=True)
+        return rows[offset : offset + limit]
+
+    # ---- decisions -------------------------------------------------------
+
+    def insert_decision(self, *, namespace: str, payload: dict[str, Any]) -> dict[str, Any]:
+        with self._lock:
+            record = {**payload, "namespace": namespace, "created_at": _now_iso()}
+            self._decisions.append(record)
+            record_with_id = {"decision_id": len(self._decisions), "record": record}
+            record["decision_id"] = record_with_id["decision_id"]
+            return record_with_id
+
+    def query_decisions(
+        self,
+        *,
+        namespace: str,
+        project: str | None = None,
+        repo: str | None = None,
+        session_id: str | None = None,
+        since: str | None = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> list[dict[str, Any]]:
+        since_ts = _iso_to_ts(since) if since else 0.0
+        with self._lock:
+            rows = [
+                r
+                for r in self._decisions
+                if r.get("namespace") == namespace
+                and (project is None or r.get("project") == project)
+                and (repo is None or r.get("repo") == repo)
+                and (session_id is None or r.get("session_id") == session_id)
+                and (not since_ts or _iso_to_ts(r.get("created_at")) >= since_ts)
+            ]
+        rows.sort(key=lambda r: _iso_to_ts(r.get("created_at")), reverse=True)
+        return rows[offset : offset + limit]
+
+    # ---- handoffs --------------------------------------------------------
+
+    def insert_handoff(self, *, namespace: str, payload: dict[str, Any]) -> dict[str, Any]:
+        with self._lock:
+            record = {**payload, "namespace": namespace, "created_at": _now_iso()}
+            self._handoffs.append(record)
+            record_with_id = {"handoff_id": len(self._handoffs), "record": record}
+            record["handoff_id"] = record_with_id["handoff_id"]
+            return record_with_id
+
+    def query_handoffs(
+        self,
+        *,
+        namespace: str,
+        project: str | None = None,
+        repo: str | None = None,
+        session_id: str | None = None,
+        since: str | None = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> list[dict[str, Any]]:
+        since_ts = _iso_to_ts(since) if since else 0.0
+        with self._lock:
+            rows = [
+                r
+                for r in self._handoffs
+                if r.get("namespace") == namespace
+                and (project is None or r.get("project") == project)
+                and (repo is None or r.get("repo") == repo)
+                and (session_id is None or r.get("session_id") == session_id)
+                and (not since_ts or _iso_to_ts(r.get("created_at")) >= since_ts)
+            ]
+        rows.sort(key=lambda r: _iso_to_ts(r.get("created_at")), reverse=True)
+        return rows[offset : offset + limit]
+
+    # ---- misc ------------------------------------------------------------
+
+    def insert_fact(self, *, namespace: str, payload: dict[str, Any]) -> dict[str, Any]:
+        with self._lock:
+            record = {**payload, "namespace": namespace, "created_at": _now_iso()}
+            self._facts.append(record)
+            return {"fact_id": len(self._facts), "record": record}
+
+    def insert_task_update(self, *, namespace: str, payload: dict[str, Any]) -> dict[str, Any]:
+        with self._lock:
+            record = {**payload, "namespace": namespace, "updated_at": _now_iso()}
+            self._updates.append(record)
+            return {"update_id": len(self._updates), "record": record}
+
+    def insert_feedback(self, *, namespace: str, payload: dict[str, Any]) -> dict[str, Any]:
+        with self._lock:
+            record = {**payload, "namespace": namespace, "created_at": _now_iso()}
+            self._feedback.append(record)
+            return {"feedback_id": len(self._feedback), "record": record}
+
+    def similar_tasks(
+        self,
+        *,
+        namespace: str,
+        task_embedding: list[float],
+        project: str | None = None,
+        repo: str | None = None,
+        top_k: int = 5,
+    ) -> list[dict[str, Any]]:
+        with self._lock:
+            candidates = [
+                s
+                for s in self._sessions.values()
+                if s["namespace"] == namespace
+                and (project is None or s["project"] == project)
+                and (repo is None or s["repo"] == repo)
+                and s.get("task_embedding")
+            ]
+        scored = [
+            (cosine_similarity(task_embedding, s["task_embedding"]), s) for s in candidates
+        ]
+        scored.sort(key=lambda x: x[0], reverse=True)
+        return [
+            {
+                "score": float(score),
+                "session_id": s["session_id"],
+                "project": s["project"],
+                "repo": s["repo"],
+                "branch": s["branch"],
+                "agent": s["agent"],
+                "task": s["task"],
+                "started_at": s["started_at"],
+            }
+            for score, s in scored[:top_k]
+        ]
+
+    # ---- atomic commit ---------------------------------------------------
+
+    def commit_session(
+        self,
+        *,
+        namespace: str,
+        session_id: str,
+        artifacts: list[dict[str, Any]],
+        decisions: list[dict[str, Any]],
+        handoff: dict[str, Any] | None,
+        task_update: dict[str, Any] | None,
+        client_commit_id: str | None,
+    ) -> dict[str, Any]:
+        cache_key = (namespace, client_commit_id) if client_commit_id else None
+
+        with self._lock:
+            if cache_key and cache_key in self._commit_cache:
+                return {**self._commit_cache[cache_key], "idempotent_replay": True}
+
+            # Snapshot list lengths for rollback on failure. Since list.append
+            # is nothrow in CPython, rollback is a safety belt for unexpected
+            # errors (e.g. KeyboardInterrupt).
+            snapshot = (
+                len(self._artifacts),
+                len(self._decisions),
+                len(self._handoffs),
+                len(self._updates),
+            )
+            try:
+                artifact_ids: list[int] = []
+                for a in artifacts:
+                    payload = {**a, "session_id": session_id}
+                    rec = {**payload, "namespace": namespace, "created_at": _now_iso()}
+                    self._artifacts.append(rec)
+                    new_id = len(self._artifacts)
+                    rec["artifact_id"] = new_id
+                    artifact_ids.append(new_id)
+
+                decision_ids: list[int] = []
+                for d in decisions:
+                    payload = {**d, "session_id": session_id}
+                    rec = {**payload, "namespace": namespace, "created_at": _now_iso()}
+                    self._decisions.append(rec)
+                    new_id = len(self._decisions)
+                    rec["decision_id"] = new_id
+                    decision_ids.append(new_id)
+
+                handoff_id: int | None = None
+                if handoff:
+                    payload = {**handoff, "session_id": session_id}
+                    rec = {**payload, "namespace": namespace, "created_at": _now_iso()}
+                    self._handoffs.append(rec)
+                    handoff_id = len(self._handoffs)
+                    rec["handoff_id"] = handoff_id
+
+                task_update_id: int | None = None
+                status = None
+                if task_update:
+                    status = task_update.get("status")
+                    payload = {**task_update, "session_id": session_id}
+                    rec = {**payload, "namespace": namespace, "updated_at": _now_iso()}
+                    self._updates.append(rec)
+                    task_update_id = len(self._updates)
+            except Exception:
+                # Roll back partial inserts.
+                a0, d0, h0, u0 = snapshot
+                del self._artifacts[a0:]
+                del self._decisions[d0:]
+                del self._handoffs[h0:]
+                del self._updates[u0:]
+                raise
+
+            result = {
+                "session_id": session_id,
+                "artifact_ids": artifact_ids,
+                "decision_ids": decision_ids,
+                "handoff_id": handoff_id,
+                "task_update_id": task_update_id,
+                "status": status,
+                "idempotent_replay": False,
+            }
+            if cache_key:
+                # Cache the "not-a-replay" variant so the replay flag flips
+                # correctly on retries.
+                self._commit_cache[cache_key] = {**result, "idempotent_replay": False}
+            return result
+
+
+# --------------------------------------------------------------------------
+# SQLAlchemy backend (Aurora / Postgres / SQLite)
+# --------------------------------------------------------------------------
+
+
+class SqlRecordStore(RecordStore):
+    """SQLAlchemy-backed persistence for devmem records."""
+
+    def __init__(self, dsn: str) -> None:
+        from sqlalchemy import (
+            JSON,
+            Column,
+            DateTime,
+            Integer,
+            MetaData,
+            String,
+            Table,
+            Text,
+            create_engine,
+            select,
+        )
+
+        self._sa_select = select
+        self.engine = create_engine(dsn, future=True, pool_pre_ping=True)
+        self.metadata = MetaData()
+
+        self.sessions = Table(
+            "devmem_sessions",
+            self.metadata,
+            Column("session_id", String(64), primary_key=True),
+            Column("namespace", String(128), index=True, nullable=False),
+            Column("project", String(256), index=True, nullable=False),
+            Column("repo", String(256), index=True, nullable=False),
+            Column("branch", String(256), nullable=False),
+            Column("agent", String(64), nullable=False),
+            Column("task", Text, nullable=False),
+            Column("task_embedding", JSON, nullable=True),
+            Column("started_at", DateTime(timezone=True), nullable=False),
+        )
+
+        def record_table(name: str) -> Table:
+            return Table(
+                name,
+                self.metadata,
+                Column("id", Integer, primary_key=True, autoincrement=True),
+                Column("namespace", String(128), index=True, nullable=False),
+                Column("session_id", String(64), index=True, nullable=True),
+                Column("project", String(256), index=True, nullable=True),
+                Column("repo", String(256), index=True, nullable=True),
+                Column("created_at", DateTime(timezone=True), index=True, nullable=False),
+                Column("payload", JSON, nullable=False),
+            )
+
+        self.artifacts = record_table("devmem_artifacts")
+        self.decisions = record_table("devmem_decisions")
+        self.handoffs = record_table("devmem_handoffs")
+        self.facts = record_table("devmem_facts")
+        self.task_updates = record_table("devmem_task_updates")
+        self.feedback = record_table("devmem_feedback")
+
+        from sqlalchemy import UniqueConstraint
+
+        self.commits = Table(
+            "devmem_commits",
+            self.metadata,
+            Column("id", Integer, primary_key=True, autoincrement=True),
+            Column("namespace", String(128), index=True, nullable=False),
+            Column("client_commit_id", String(128), nullable=False),
+            Column("session_id", String(64), index=True, nullable=False),
+            Column("created_at", DateTime(timezone=True), nullable=False),
+            Column("result", JSON, nullable=False),
+            UniqueConstraint("namespace", "client_commit_id", name="uq_devmem_commit_idem"),
+        )
+
+        self.metadata.create_all(self.engine)
+
+    # ---- helpers ---------------------------------------------------------
+
+    def _insert_record(
+        self,
+        table,
+        *,
+        namespace: str,
+        payload: dict[str, Any],
+    ) -> dict[str, Any]:
+        now = datetime.now(timezone.utc)
+        row = {
+            "namespace": namespace,
+            "session_id": payload.get("session_id"),
+            "project": payload.get("project"),
+            "repo": payload.get("repo"),
+            "created_at": now,
+            "payload": payload,
+        }
+        with self.engine.begin() as conn:
+            result = conn.execute(table.insert().values(**row))
+            new_id = result.inserted_primary_key[0]
+        record = {**payload, "namespace": namespace, "created_at": now.isoformat()}
+        return new_id, record
+
+    def _query_records(
+        self,
+        table,
+        *,
+        namespace: str,
+        project: str | None,
+        repo: str | None,
+        session_id: str | None,
+        since: str | None,
+        limit: int,
+        offset: int,
+        extra_filters: dict[str, Any] | None = None,
+    ) -> list[dict[str, Any]]:
+        stmt = self._sa_select(table).where(table.c.namespace == namespace)
+        if project is not None:
+            stmt = stmt.where(table.c.project == project)
+        if repo is not None:
+            stmt = stmt.where(table.c.repo == repo)
+        if session_id is not None:
+            stmt = stmt.where(table.c.session_id == session_id)
+        if since:
+            try:
+                since_dt = datetime.fromisoformat(since.replace("Z", "+00:00"))
+                stmt = stmt.where(table.c.created_at >= since_dt)
+            except Exception:
+                logger.debug("invalid since filter: %s", since)
+        stmt = stmt.order_by(table.c.created_at.desc()).limit(limit).offset(offset)
+        with self.engine.connect() as conn:
+            rows = list(conn.execute(stmt))
+        out = []
+        for r in rows:
+            payload = dict(r.payload) if r.payload else {}
+            payload["created_at"] = r.created_at.isoformat()
+            payload["namespace"] = r.namespace
+            if extra_filters and not all(payload.get(k) == v for k, v in extra_filters.items()):
+                continue
+            out.append(payload)
+        return out
+
+    # ---- sessions --------------------------------------------------------
+
+    def create_session(
+        self,
+        *,
+        session_id: str,
+        namespace: str,
+        project: str,
+        repo: str,
+        branch: str,
+        agent: str,
+        task: str,
+        started_at: str,
+        task_embedding: list[float] | None,
+    ) -> None:
+        try:
+            started_dt = datetime.fromisoformat(started_at.replace("Z", "+00:00"))
+        except Exception:
+            started_dt = datetime.now(timezone.utc)
+        with self.engine.begin() as conn:
+            conn.execute(
+                self.sessions.insert().values(
+                    session_id=session_id,
+                    namespace=namespace,
+                    project=project,
+                    repo=repo,
+                    branch=branch,
+                    agent=agent,
+                    task=task,
+                    task_embedding=task_embedding,
+                    started_at=started_dt,
+                )
+            )
+
+    def list_sessions(
+        self,
+        *,
+        namespace: str,
+        project: str | None = None,
+        repo: str | None = None,
+        limit: int = 100,
+    ) -> list[dict[str, Any]]:
+        stmt = self._sa_select(self.sessions).where(self.sessions.c.namespace == namespace)
+        if project is not None:
+            stmt = stmt.where(self.sessions.c.project == project)
+        if repo is not None:
+            stmt = stmt.where(self.sessions.c.repo == repo)
+        stmt = stmt.order_by(self.sessions.c.started_at.desc()).limit(limit)
+        with self.engine.connect() as conn:
+            rows = list(conn.execute(stmt))
+        return [
+            {
+                "session_id": r.session_id,
+                "namespace": r.namespace,
+                "project": r.project,
+                "repo": r.repo,
+                "branch": r.branch,
+                "agent": r.agent,
+                "task": r.task,
+                "started_at": r.started_at.isoformat(),
+            }
+            for r in rows
+        ]
+
+    # ---- artifact/decision/handoff/fact/update/feedback ------------------
+
+    def insert_artifact(self, *, namespace: str, payload: dict[str, Any]) -> dict[str, Any]:
+        new_id, record = self._insert_record(self.artifacts, namespace=namespace, payload=payload)
+        return {"artifact_id": new_id, "record": record}
+
+    def query_artifacts(
+        self,
+        *,
+        namespace: str,
+        project: str | None = None,
+        repo: str | None = None,
+        session_id: str | None = None,
+        artifact_type: str | None = None,
+        since: str | None = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> list[dict[str, Any]]:
+        extra = {"artifact_type": artifact_type} if artifact_type else None
+        return self._query_records(
+            self.artifacts,
+            namespace=namespace,
+            project=project,
+            repo=repo,
+            session_id=session_id,
+            since=since,
+            limit=limit,
+            offset=offset,
+            extra_filters=extra,
+        )
+
+    def insert_decision(self, *, namespace: str, payload: dict[str, Any]) -> dict[str, Any]:
+        new_id, record = self._insert_record(self.decisions, namespace=namespace, payload=payload)
+        return {"decision_id": new_id, "record": record}
+
+    def query_decisions(
+        self,
+        *,
+        namespace: str,
+        project: str | None = None,
+        repo: str | None = None,
+        session_id: str | None = None,
+        since: str | None = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> list[dict[str, Any]]:
+        return self._query_records(
+            self.decisions,
+            namespace=namespace,
+            project=project,
+            repo=repo,
+            session_id=session_id,
+            since=since,
+            limit=limit,
+            offset=offset,
+        )
+
+    def insert_handoff(self, *, namespace: str, payload: dict[str, Any]) -> dict[str, Any]:
+        new_id, record = self._insert_record(self.handoffs, namespace=namespace, payload=payload)
+        return {"handoff_id": new_id, "record": record}
+
+    def query_handoffs(
+        self,
+        *,
+        namespace: str,
+        project: str | None = None,
+        repo: str | None = None,
+        session_id: str | None = None,
+        since: str | None = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> list[dict[str, Any]]:
+        return self._query_records(
+            self.handoffs,
+            namespace=namespace,
+            project=project,
+            repo=repo,
+            session_id=session_id,
+            since=since,
+            limit=limit,
+            offset=offset,
+        )
+
+    def insert_fact(self, *, namespace: str, payload: dict[str, Any]) -> dict[str, Any]:
+        new_id, record = self._insert_record(self.facts, namespace=namespace, payload=payload)
+        return {"fact_id": new_id, "record": record}
+
+    def insert_task_update(self, *, namespace: str, payload: dict[str, Any]) -> dict[str, Any]:
+        new_id, record = self._insert_record(self.task_updates, namespace=namespace, payload=payload)
+        return {"update_id": new_id, "record": record}
+
+    def insert_feedback(self, *, namespace: str, payload: dict[str, Any]) -> dict[str, Any]:
+        new_id, record = self._insert_record(self.feedback, namespace=namespace, payload=payload)
+        return {"feedback_id": new_id, "record": record}
+
+    def similar_tasks(
+        self,
+        *,
+        namespace: str,
+        task_embedding: list[float],
+        project: str | None = None,
+        repo: str | None = None,
+        top_k: int = 5,
+    ) -> list[dict[str, Any]]:
+        stmt = self._sa_select(self.sessions).where(
+            self.sessions.c.namespace == namespace,
+            self.sessions.c.task_embedding.is_not(None),
+        )
+        if project is not None:
+            stmt = stmt.where(self.sessions.c.project == project)
+        if repo is not None:
+            stmt = stmt.where(self.sessions.c.repo == repo)
+        with self.engine.connect() as conn:
+            rows = list(conn.execute(stmt))
+        scored: list[tuple[float, Any]] = []
+        for r in rows:
+            emb = r.task_embedding
+            if not emb:
+                continue
+            scored.append((cosine_similarity(task_embedding, emb), r))
+        scored.sort(key=lambda x: x[0], reverse=True)
+        return [
+            {
+                "score": float(score),
+                "session_id": r.session_id,
+                "project": r.project,
+                "repo": r.repo,
+                "branch": r.branch,
+                "agent": r.agent,
+                "task": r.task,
+                "started_at": r.started_at.isoformat(),
+            }
+            for score, r in scored[:top_k]
+        ]
+
+    # ---- atomic commit ---------------------------------------------------
+
+    def commit_session(
+        self,
+        *,
+        namespace: str,
+        session_id: str,
+        artifacts: list[dict[str, Any]],
+        decisions: list[dict[str, Any]],
+        handoff: dict[str, Any] | None,
+        task_update: dict[str, Any] | None,
+        client_commit_id: str | None,
+    ) -> dict[str, Any]:
+        now = datetime.now(timezone.utc)
+
+        # Idempotency check (pre-transaction): cheaper to short-circuit before
+        # opening a write transaction.
+        if client_commit_id:
+            stmt = self._sa_select(self.commits).where(
+                self.commits.c.namespace == namespace,
+                self.commits.c.client_commit_id == client_commit_id,
+            )
+            with self.engine.connect() as conn:
+                existing = conn.execute(stmt).first()
+            if existing is not None:
+                cached = dict(existing.result)
+                return {**cached, "idempotent_replay": True}
+
+        with self.engine.begin() as conn:
+            artifact_ids: list[int] = []
+            for a in artifacts:
+                payload = {**a, "session_id": session_id}
+                row = {
+                    "namespace": namespace,
+                    "session_id": session_id,
+                    "project": payload.get("project"),
+                    "repo": payload.get("repo"),
+                    "created_at": now,
+                    "payload": payload,
+                }
+                res = conn.execute(self.artifacts.insert().values(**row))
+                artifact_ids.append(res.inserted_primary_key[0])
+
+            decision_ids: list[int] = []
+            for d in decisions:
+                payload = {**d, "session_id": session_id}
+                row = {
+                    "namespace": namespace,
+                    "session_id": session_id,
+                    "project": payload.get("project"),
+                    "repo": payload.get("repo"),
+                    "created_at": now,
+                    "payload": payload,
+                }
+                res = conn.execute(self.decisions.insert().values(**row))
+                decision_ids.append(res.inserted_primary_key[0])
+
+            handoff_id: int | None = None
+            if handoff:
+                payload = {**handoff, "session_id": session_id}
+                row = {
+                    "namespace": namespace,
+                    "session_id": session_id,
+                    "project": payload.get("project"),
+                    "repo": payload.get("repo"),
+                    "created_at": now,
+                    "payload": payload,
+                }
+                res = conn.execute(self.handoffs.insert().values(**row))
+                handoff_id = res.inserted_primary_key[0]
+
+            task_update_id: int | None = None
+            status = None
+            if task_update:
+                status = task_update.get("status")
+                payload = {**task_update, "session_id": session_id}
+                row = {
+                    "namespace": namespace,
+                    "session_id": session_id,
+                    "project": None,
+                    "repo": None,
+                    "created_at": now,
+                    "payload": payload,
+                }
+                res = conn.execute(self.task_updates.insert().values(**row))
+                task_update_id = res.inserted_primary_key[0]
+
+            result = {
+                "session_id": session_id,
+                "artifact_ids": artifact_ids,
+                "decision_ids": decision_ids,
+                "handoff_id": handoff_id,
+                "task_update_id": task_update_id,
+                "status": status,
+                "idempotent_replay": False,
+            }
+
+            if client_commit_id:
+                # Racing clients may both attempt to insert the same commit
+                # key; the UNIQUE constraint turns the loser into an
+                # IntegrityError that rolls back the whole transaction.
+                conn.execute(
+                    self.commits.insert().values(
+                        namespace=namespace,
+                        client_commit_id=client_commit_id,
+                        session_id=session_id,
+                        created_at=now,
+                        result=result,
+                    )
+                )
+
+            return result
+
+
+# --------------------------------------------------------------------------
+# Factory
+# --------------------------------------------------------------------------
+
+
+def build_record_store(dsn: str | None) -> RecordStore:
+    """Return a SqlRecordStore if DSN is set, else in-memory."""
+    if not dsn:
+        return MemoryRecordStore()
+    try:
+        store = SqlRecordStore(dsn)
+        logger.info("Using SQL record store dsn=<redacted>")
+        return store
+    except Exception as exc:
+        logger.error(
+            "Failed to initialize SQL record store (%s); falling back to in-memory. "
+            "Data will NOT persist across restarts.",
+            exc,
+            exc_info=True,
+        )
+        return MemoryRecordStore()