feat(persistence): repository interface + in-memory & SQLite adapters

Slice 1, PR 2 of 4 — the persistence boundary.

- panopticon.core.repository: the Repository ABC (the interface, ADR 0001/0006) plus
  shared integrity checks (non-empty consistent history; append-only history).
- panopticon.taskservice.repository_memory.InMemoryRepository: dict-backed adapter
  (stores deep copies) for tests and the walking-skeleton runner.
- panopticon.taskservice.repository_sqlite.SqliteRepository: SQLite adapter with
  user_version migrations; persists the per-turn settled responsibilities in a
  child table tied to each history row.
- Contract tests parametrized over BOTH backends — proving the interface is genuinely
  backend-agnostic and that both enforce identical integrity rules.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: tildesrc

src/panopticon/core/repository.py

@@ -0,0 +1,98 @@
+"""The repository interface: the abstraction over persisted task state.
+
+A backend-agnostic interface (ADR 0001/0006). The task service is its sole owner and the
+single writer; adapters implement it (in-memory and SQLite in this slice; Postgres later).
+
+Integrity rules every adapter must enforce — the "transition enforcement at the boundary":
+
+* ``create_task`` — the task id is unique, its ``repo_id`` exists, its history is
+  non-empty, and ``state`` equals the last history entry's ``to_state``.
+* ``save_task`` — the task exists, its history is **append-only** (the stored history is a
+  prefix of the supplied one), and ``state`` equals the last history entry's ``to_state``.
+
+The *legality* of a transition (which state may follow which) is decided by the engine
+before save; the repository guarantees the persisted record stays internally consistent.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+
+from panopticon.core.models import HistoryEntry, Repo, Task
+
+
+class RepositoryError(Exception):
+    """Base class for repository failures."""
+
+
+class NotFound(RepositoryError):
+    """Raised when an entity referenced by id does not exist."""
+
+
+class AlreadyExists(RepositoryError):
+    """Raised when creating an entity whose id is already taken."""
+
+
+class IntegrityError(RepositoryError):
+    """Raised when a write would violate an integrity rule (e.g. non-append-only history)."""
+
+
+class Repository(ABC):
+    """Persistence boundary for repos and tasks."""
+
+    # -- repos --------------------------------------------------------------------
+
+    @abstractmethod
+    def create_repo(self, repo: Repo) -> None:
+        """Persist a new repo. Raises :class:`AlreadyExists` if its id is taken."""
+
+    @abstractmethod
+    def get_repo(self, repo_id: str) -> Repo | None:
+        """Return the repo, or ``None`` if it does not exist."""
+
+    @abstractmethod
+    def list_repos(self) -> list[Repo]:
+        """Return all repos."""
+
+    # -- tasks --------------------------------------------------------------------
+
+    @abstractmethod
+    def create_task(self, task: Task) -> None:
+        """Persist a new task and its initial history. Enforces the create-time rules."""
+
+    @abstractmethod
+    def get_task(self, task_id: str) -> Task | None:
+        """Return the task (with full history), or ``None`` if it does not exist."""
+
+    @abstractmethod
+    def list_tasks(self) -> list[Task]:
+        """Return all tasks (with full history)."""
+
+    @abstractmethod
+    def save_task(self, task: Task) -> None:
+        """Persist an updated task. Enforces the append-only and consistency rules."""
+
+
+# -- Shared integrity checks (adapters call these so the rules live in one place) --------
+
+
+def validate_task_invariants(task: Task) -> None:
+    """Check a task is internally consistent: non-empty history, state matches its tail."""
+    if not task.history:
+        raise IntegrityError(f"task {task.id!r} has empty history")
+    if task.state != task.history[-1].to_state:
+        raise IntegrityError(
+            f"task {task.id!r}: state {task.state!r} != last history to_state "
+            f"{task.history[-1].to_state!r}"
+        )
+
+
+def validate_append_only(
+    stored: Sequence[HistoryEntry], incoming: Sequence[HistoryEntry]
+) -> None:
+    """Check ``incoming`` history only extends ``stored`` (no edits, no shrink)."""
+    if len(incoming) < len(stored):
+        raise IntegrityError("history shrank (not append-only)")
+    if list(stored) != list(incoming[: len(stored)]):
+        raise IntegrityError("existing history was modified (not append-only)")

src/panopticon/taskservice/__init__.py

@@ -0,0 +1,5 @@
+"""The task service: the deterministic control plane.
+
+Owns the repository (the sole DB authority, ADR 0006), hosts the workflow registry, and
+drives task lifecycle. This package must remain LLM-free (enforced by a determinism test).
+"""

src/panopticon/taskservice/repository_memory.py

@@ -0,0 +1,66 @@
+"""In-memory repository adapter.
+
+Useful for tests and the walking-skeleton runner, and — together with the SQLite
+adapter — proof that the repository interface is genuinely backend-agnostic (ADR 0006).
+Stores deep copies so callers can't mutate persisted state by holding a reference.
+"""
+
+from __future__ import annotations
+
+import copy
+
+from panopticon.core.models import Repo, Task
+from panopticon.core.repository import (
+    AlreadyExists,
+    NotFound,
+    Repository,
+    validate_append_only,
+    validate_task_invariants,
+)
+
+
+class InMemoryRepository(Repository):
+    """A dict-backed :class:`~panopticon.core.repository.Repository`."""
+
+    def __init__(self) -> None:
+        self._repos: dict[str, Repo] = {}
+        self._tasks: dict[str, Task] = {}
+
+    # -- repos --------------------------------------------------------------------
+
+    def create_repo(self, repo: Repo) -> None:
+        if repo.id in self._repos:
+            raise AlreadyExists(f"repo {repo.id!r} already exists")
+        self._repos[repo.id] = copy.deepcopy(repo)
+
+    def get_repo(self, repo_id: str) -> Repo | None:
+        repo = self._repos.get(repo_id)
+        return copy.deepcopy(repo) if repo is not None else None
+
+    def list_repos(self) -> list[Repo]:
+        return [copy.deepcopy(r) for r in self._repos.values()]
+
+    # -- tasks --------------------------------------------------------------------
+
+    def create_task(self, task: Task) -> None:
+        if task.id in self._tasks:
+            raise AlreadyExists(f"task {task.id!r} already exists")
+        if task.repo_id not in self._repos:
+            raise NotFound(f"repo {task.repo_id!r} does not exist")
+        validate_task_invariants(task)
+        self._tasks[task.id] = copy.deepcopy(task)
+
+    def get_task(self, task_id: str) -> Task | None:
+        task = self._tasks.get(task_id)
+        return copy.deepcopy(task) if task is not None else None
+
+    def list_tasks(self) -> list[Task]:
+        return [copy.deepcopy(t) for t in self._tasks.values()]
+
+    def save_task(self, task: Task) -> None:
+        stored = self._tasks.get(task.id)
+        if stored is None:
+            raise NotFound(f"task {task.id!r} does not exist")
+        validate_task_invariants(task)
+        validate_append_only(stored.history, task.history)
+        self._tasks[task.id] = copy.deepcopy(task)