purra-sqlite 0.5.0__py3-none-any.whl

purra_sqlite/__init__.py

@@ -0,0 +1,289 @@
+"""SQLite transactions around PurrA's canonical storage state machines."""
+import asyncio
+import os
+from inspect import signature
+from contextlib import asynccontextmanager
+from dataclasses import replace
+import sqlite3
+import time
+from uuid import uuid4
+
+from purra.adapters.memory import InMemoryAgentAdapters
+from purra.contracts import ToolHandlerResult, RunExecutionLease, RunStatus
+from purra.execution.ownership import execution_owner, execution_claim
+from purra.errors import ContractViolationError
+from .codec import dumps, loads
+from .journal import JOURNAL_FIELDS, STORAGE_VERSION, OutputJournal
+
+
+_READ_METHODS = {
+    "runs": frozenset({"get"}),
+    "outputs": frozenset({"list_events", "list_root_events", "load_validated_result"}),
+}
+_INDEPENDENT_PORTS = frozenset({"run_tree", "artifacts", "artifact_claims", "artifact_maintenance", "long_tasks"})
+
+
+def _journal_run(arguments):
+    for name in ("run_id", "root_run_id"):
+        if isinstance(arguments.get(name), str):
+            return arguments[name]
+    for name in ("draft", "spec"):
+        run_id = getattr(arguments.get(name), "run_id", None)
+        if isinstance(run_id, str):
+            return run_id
+    drafts = arguments.get("drafts")
+    if isinstance(drafts, (tuple, list)) and drafts:
+        ids = {getattr(draft, "run_id", None) for draft in drafts}
+        if len(ids) == 1 and isinstance(next(iter(ids)), str):
+            return next(iter(ids))
+    return None
+
+
+class _Port:
+    def __init__(self, store, name):
+        self.store, self.name = store, name
+        template = getattr(InMemoryAgentAdapters(), name)
+        self._methods = {key for key in dir(template) if not key.startswith("_") and callable(getattr(template, key))}
+        self._signatures = {key: signature(getattr(template, key)) for key in self._methods} if name in ("runs", "outputs") else {}
+
+    def __getattr__(self, method):
+        if method not in self._methods: raise AttributeError(method)
+        async def call(*args, **kwargs):
+            if self.name == "outputs" and method in ("list_events", "list_root_events"):
+                return await getattr(self.store, "_" + method)(*args, **kwargs)
+            read_only = method in _READ_METHODS.get(self.name, ())
+            arguments = self._signatures[method].bind(*args, **kwargs).arguments if method in self._signatures else {}
+            journal_run_id = _journal_run(arguments)
+            stream_id = arguments.get("output_stream_id")
+            async with self.store._transaction(read_only=read_only, with_journal=self.name not in _INDEPENDENT_PORTS, journal_run_id=journal_run_id, journal_stream_id=stream_id, lazy_journal=not read_only) as adapters:
+                if self.name in ("runs", "outputs") and method not in ("get", "list_events", "list_root_events", "load_validated_result"):
+                    first = args[0] if args else None
+                    stream = adapters.runs._state.streams.get(stream_id) if isinstance(stream_id, str) else None
+                    run_id = journal_run_id or (stream.spec.run_id if stream is not None else None)
+                    if run_id is None:
+                        run_id = first if isinstance(first, str) else getattr(first, "run_id", None)
+                    if run_id:
+                        self.store._guard(run_id)
+                return await getattr(getattr(adapters, self.name), method)(*args, **kwargs)
+        return call
+
+
+class _Publisher:
+    def __init__(self, store): self.store = store
+
+    async def publish_committed(self, event):
+        rows = await self.store.outputs.list_events(event.run_id, after_sequence=event.sequence - 1, limit=1)
+        if not rows or rows[0] != event:
+            raise ValueError("only persisted output can be published")
+
+    async def wait_for_sequence(self, run_id, *, after_sequence):
+        while not await self.store.outputs.list_events(run_id, after_sequence=after_sequence, limit=1):
+            await asyncio.sleep(0.05)
+
+
+class _Idempotency:
+    def __init__(self, store): self.store = store
+
+    async def execute_once(self, run_id, tool_call, operation):
+        key = (run_id, tool_call.id)
+        async with self.store._transaction(with_journal=False) as adapters:
+            state = adapters.runs._state
+            receipt = state.tool_receipts.get(key)
+            if receipt is not None:
+                if receipt[0] != tool_call: raise ValueError("tool_idempotency_conflict")
+                return replace(receipt[1], from_cache=True)
+            claimed = self.store._claims.get(key)
+            if claimed is not None:
+                raise ContractViolationError("Reconcile the previous tool attempt before retrying", code="tool_effect_unknown")
+            self.store._claims[key] = tool_call
+        # External work is never performed while holding a SQLite transaction.
+        result = await operation()
+        if not isinstance(result, ToolHandlerResult): raise TypeError("invalid tool result")
+        async with self.store._transaction(with_journal=False) as adapters:
+            adapters.runs._state.tool_receipts[key] = (tool_call, result)
+            del self.store._claims[key]
+        return result
+
+
+class SqliteAgentAdapters:
+    """Scoped, restartable Run/output, tree, Artifact and Long Task adapters.
+
+    All state-machine mutations commit atomically. Each namespace is intended for
+    a bounded local project; use separate scopes for independent projects.
+    """
+    def __init__(self, path, *, scope, busy_timeout=5):
+        if not isinstance(scope, str) or not scope.strip(): raise ValueError("scope is required")
+        self.scope, self.busy_timeout = scope, busy_timeout
+        if os.fspath(path) != ":memory:":
+            try: os.close(os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600))
+            except FileExistsError: pass
+        self._lock = asyncio.Lock()
+        self._db = sqlite3.connect(path, timeout=0, isolation_level=None)
+        self._db.execute("PRAGMA journal_mode=WAL")
+        self._db.execute("PRAGMA synchronous=FULL")
+        self._db.execute("PRAGMA foreign_keys=ON")
+        self._db.execute("CREATE TABLE IF NOT EXISTS purra_state (scope TEXT NOT NULL, sdk TEXT NOT NULL, version INTEGER NOT NULL, body TEXT NOT NULL, PRIMARY KEY(scope,sdk))")
+        self._journal = OutputJournal(self._db, scope)
+        self._claims = {}
+        self._leases = {}
+        self.extra = {}
+        for name in ("runs", "outputs", "run_tree", "artifacts", "artifact_claims", "artifact_maintenance", "long_tasks"):
+            setattr(self, name, _Port(self, name))
+        self.publisher = _Publisher(self)
+        self.idempotency = _Idempotency(self)
+        self.leases = _Leases(self)
+
+    def _guard(self, run_id):
+        lease = self._leases.get(run_id)
+        owner = execution_owner.get()
+        claim = execution_claim.get()
+        if lease is not None and owner is not None and (
+            lease.owner_id != owner or (lease.expires_at_ms or 0) <= int(time.time() * 1000)
+            or (claim is not None and claim[0] == run_id and claim[2] != lease.attempt)
+        ):
+            raise ContractViolationError("Execution lease was lost", code="run_lease_lost")
+
+    def transaction(self):
+        return self._transaction()
+
+    @asynccontextmanager
+    async def _connection(self, *, read_only=False):
+        async with self._lock:
+            deadline = time.monotonic() + self.busy_timeout
+            while True:
+                try:
+                    self._db.execute("BEGIN" if read_only else "BEGIN IMMEDIATE")
+                    break
+                except sqlite3.OperationalError as error:
+                    if "locked" not in str(error) or time.monotonic() >= deadline: raise
+                    await asyncio.sleep(0.01)
+            try:
+                yield
+                self._db.execute("COMMIT")
+            except BaseException:
+                self._db.execute("ROLLBACK")
+                raise
+
+    @asynccontextmanager
+    async def _transaction(self, *, read_only=False, with_journal=True, journal_run_id=None, journal_stream_id=None, lazy_journal=False):
+        async with self._connection(read_only=read_only):
+            adapters = InMemoryAgentAdapters()
+            groups = {
+                "run": (adapters.runs._state, {"lock", "changed", "tool_inflight", "run_tree_authority"}),
+                "tree": (adapters.run_tree, {"_lock", "_clock_ms"}),
+                "artifact": (adapters.artifacts, {"_lock", "_clock_ms", "_run_is_available"}),
+                "task": (adapters.long_tasks, {"_lock", "_clock_ms"}),
+            }
+            row = self._db.execute("SELECT version,body FROM purra_state WHERE scope=? AND sdk='python'", (self.scope,)).fetchone()
+            if row:
+                if row[0] != STORAGE_VERSION: raise ValueError("unsupported SQLite storage version")
+                saved = loads(row[1])
+                for name, (obj, excluded) in groups.items():
+                    for key, value in saved[name].items():
+                        if key in excluded or key not in vars(obj) or (name == "run" and key in JOURNAL_FIELDS): raise ValueError("invalid storage field")
+                        setattr(obj, key, value)
+                self._claims = saved["claims"]
+                self._leases = saved.get("leases", {})
+                self.extra = saved.get("extra", {})
+            else:
+                self._claims = {}
+                self._leases = {}
+                self.extra = {}
+            if with_journal:
+                stream = adapters.runs._state.streams.get(journal_stream_id) if isinstance(journal_stream_id, str) else None
+                if journal_run_id is None and stream is not None:
+                    journal_run_id = stream.spec.run_id
+                record = adapters.runs._state.runs.get(journal_run_id)
+                root_run_id = (record.params.root_run_id or journal_run_id) if record is not None else None
+                self._journal.restore(adapters.runs._state, root_run_id=root_run_id, lazy=lazy_journal)
+            prior_sequences = dict(adapters.runs._state.sequences)
+            prior_runs = set(adapters.runs._state.runs)
+            yield adapters
+            if not read_only:
+                saved = {name: {k: v for k, v in vars(obj).items() if k not in excluded and not (name == "run" and k in JOURNAL_FIELDS)}
+                         for name, (obj, excluded) in groups.items()}
+                saved["claims"] = self._claims
+                saved["leases"] = self._leases
+                saved["extra"] = self.extra
+                # Snapshot writes scale with project history.
+                body = dumps(saved)
+                if row is None or row[1] != body:
+                    self._db.execute("INSERT INTO purra_state VALUES(?, 'python', 3, ?) ON CONFLICT(scope,sdk) DO UPDATE SET version=excluded.version,body=excluded.body", (self.scope, body))
+                if with_journal:
+                    self._journal.append(adapters.runs._state, prior_sequences, prior_runs)
+
+    async def _list_events(self, run_id, *, after_sequence, limit=200):
+        async with self._connection(read_only=True):
+            return self._journal.read(run_id, after_sequence, limit)
+
+    async def _list_root_events(self, root_run_id, *, after_root_sequence, limit=200):
+        async with self._connection(read_only=True):
+            return self._journal.read(root_run_id, after_root_sequence, limit, root=True)
+
+    async def reconcile_tool(self, run_id, tool_call, *, result=None, not_executed=False):
+        if (result is None) == (not_executed is False): raise ValueError("supply result or proof of non-execution")
+        async with self._transaction(with_journal=False) as adapters:
+            key = (run_id, tool_call.id)
+            if self._claims.get(key) != tool_call: raise ValueError("tool_claim_conflict")
+            if result is not None:
+                if not isinstance(result, ToolHandlerResult): raise TypeError("invalid tool result")
+                adapters.runs._state.tool_receipts[key] = (tool_call, result)
+            del self._claims[key]
+
+    async def list_running(self):
+        async with self._transaction(read_only=True, with_journal=False) as adapters:
+            return tuple(key for key, run in adapters.runs._state.runs.items() if run.status.value == "running")
+
+    def close(self):
+        if self._lock.locked(): raise RuntimeError("storage transaction is active")
+        self._db.close()
+
+
+__all__ = ["SqliteAgentAdapters"]
+
+
+class _Leases:
+    def __init__(self, store): self.store = store
+
+    async def get(self, run_id):
+        async with self.store._transaction(read_only=True, with_journal=False) as adapters:
+            run = adapters.runs._state.runs.get(run_id)
+            if run is None: return None
+            return replace(self.store._leases.get(run_id, RunExecutionLease(run_id, run.status)), status=run.status)
+
+    async def claim(self, run_id, owner_id, *, lease_duration_ms):
+        if not owner_id or lease_duration_ms <= 0: raise ValueError("invalid lease")
+        async with self.store.transaction() as adapters:
+            now = int(time.time() * 1000)
+            run = adapters.runs._state.runs[run_id]
+            old = self.store._leases.get(run_id, RunExecutionLease(run_id, run.status))
+            if run.status is not RunStatus.RUNNING or old.cancellation_requested_at_ms is not None: return False
+            if old.owner_id is not None and (old.expires_at_ms or 0) > now: return False
+            if run.execution_checkpoint is not None and len(run.model_attempt_ids) != run.checkpoint_attempt_count:
+                raise ContractViolationError("The last model/tool attempt needs reconciliation", code="run_recovery_requires_reconciliation")
+            self.store._leases[run_id] = replace(old, owner_id=owner_id, expires_at_ms=now + lease_duration_ms, heartbeat_at_ms=now, attempt=old.attempt + 1)
+            return True
+
+    async def renew(self, run_id, owner_id, *, lease_duration_ms):
+        async with self.store._transaction(with_journal=False):
+            now = int(time.time() * 1000)
+            old = self.store._leases.get(run_id)
+            if old is None or old.owner_id != owner_id or (old.expires_at_ms or 0) <= now: return False
+            self.store._leases[run_id] = replace(old, expires_at_ms=now + lease_duration_ms, heartbeat_at_ms=now)
+            return True
+
+    async def release(self, run_id, owner_id):
+        async with self.store._transaction(with_journal=False):
+            old = self.store._leases.get(run_id)
+            if old is None or old.owner_id != owner_id: return False
+            self.store._leases[run_id] = replace(old, owner_id=None, expires_at_ms=None)
+            return True
+
+    async def request_cancellation(self, run_id):
+        async with self.store._transaction(with_journal=False) as adapters:
+            run = adapters.runs._state.runs.get(run_id)
+            if run is None or run.status is not RunStatus.RUNNING: return False
+            old = self.store._leases.get(run_id, RunExecutionLease(run_id, run.status))
+            if old.cancellation_requested_at_ms is not None: return False
+            self.store._leases[run_id] = replace(old, cancellation_requested_at_ms=int(time.time() * 1000))
+            return True

purra_sqlite/codec.py

@@ -0,0 +1,63 @@
+"""Data-only encoding of the version-pinned Core storage records."""
+from collections.abc import Mapping, Sequence
+from dataclasses import fields, is_dataclass
+from datetime import datetime
+from enum import Enum
+import json
+import math
+import sys
+
+
+def _types():
+    # Only already imported Core record classes are allowed; data cannot import code.
+    return {f"{value.__module__}.{value.__qualname__}": value
+            for name, module in tuple(sys.modules.items()) if name.startswith("purra.")
+            for value in tuple(vars(module).values())
+            if isinstance(value, type) and value.__module__.startswith("purra.")
+            and (is_dataclass(value) or issubclass(value, Enum))}
+
+
+def encode(value):
+    if isinstance(value, Enum):
+        return ["enum", f"{type(value).__module__}.{type(value).__qualname__}", value.value]
+    if value is None or type(value) in (str, int, bool):
+        return ["value", value]
+    if type(value) is float and math.isfinite(value):
+        return ["value", value]
+    if isinstance(value, datetime):
+        return ["datetime", value.isoformat()]
+    if is_dataclass(value) and not isinstance(value, type):
+        return ["record", f"{type(value).__module__}.{type(value).__qualname__}",
+                {f.name: encode(getattr(value, f.name)) for f in fields(value) if f.init}]
+    if isinstance(value, Mapping):
+        return ["map", [[encode(k), encode(v)] for k, v in value.items()]]
+    if isinstance(value, (list, tuple, set, frozenset)):
+        return [type(value).__name__, [encode(v) for v in value]]
+    if isinstance(value, Sequence):
+        return ["list", [encode(v) for v in value]]
+    raise TypeError(f"Unsupported durable value: {type(value).__name__}")
+
+
+def dumps(value):
+    return json.dumps(encode(value), ensure_ascii=False, allow_nan=False, separators=(",", ":"))
+
+
+def loads(text):
+    return next(load_many((text,)))
+
+
+def load_many(texts):
+    registry = None
+    def decode(row):
+        kind = row[0]
+        if kind == "value": return row[1]
+        if kind == "datetime": return datetime.fromisoformat(row[1])
+        if kind == "enum": return registry[row[1]](row[2])
+        if kind == "record": return registry[row[1]](**{k: decode(v) for k, v in row[2].items()})
+        if kind == "map": return {decode(k): decode(v) for k, v in row[1]}
+        constructors = {"list": list, "tuple": tuple, "set": set, "frozenset": frozenset}
+        return constructors[kind](decode(v) for v in row[1])
+    for text in texts:
+        if registry is None:
+            registry = _types()
+        yield decode(json.loads(text))

purra_sqlite/journal.py

@@ -0,0 +1,231 @@
+"""Indexed canonical output journal, committed with the execution snapshot."""
+
+import operator
+from collections.abc import Sequence
+from itertools import tee
+
+from purra.errors import ContractViolationError
+from purra.output.contracts import AgentOutputEvent
+from .codec import dumps, load_many, loads
+
+STORAGE_VERSION = 3
+JOURNAL_FIELDS = {"output_events", "root_output_events", "events_by_source_key"}
+
+
+def _validate_row(event, row):
+    if (not isinstance(event, AgentOutputEvent)
+            or (event.run_id, event.root_run_id, event.sequence, event.root_sequence) != row[:4]):
+        raise ValueError("invalid output journal identity or sequence")
+    return event
+
+
+def _load_rows(rows):
+    metadata, bodies = tee(rows)
+    for row, event in zip(metadata, load_many(row[4] for row in bodies), strict=True):
+        yield _validate_row(event, row)
+
+
+class _BufferedEvents(Sequence):
+    """Transaction-local history with an append buffer and deferred evidence reads."""
+
+    def __init__(self, count, load):
+        self.count, self.load = count, load
+        self.pending = []
+        self.history = None
+
+    def __len__(self):
+        return self.count + len(self.pending)
+
+    def _history(self):
+        if self.history is None:
+            self.history = tuple(self.load())
+            if len(self.history) != self.count:
+                raise ValueError("incomplete output journal")
+        return self.history
+
+    def __iter__(self):
+        yield from self._history()
+        yield from self.pending
+
+    def __getitem__(self, index):
+        if isinstance(index, slice):
+            start, stop, step = index.indices(len(self))
+            if step > 0 and start >= self.count:
+                return self.pending[start - self.count:stop - self.count:step]
+            return tuple(self)[index]
+        index = operator.index(index)
+        if index < 0:
+            index += len(self)
+        if index < 0 or index >= len(self):
+            raise IndexError(index)
+        return self.pending[index - self.count] if index >= self.count else self._history()[index]
+
+    def append(self, event):
+        self.pending.append(event)
+
+
+class _SourceEvents(dict):
+    def __init__(self, journal):
+        super().__init__()
+        self.journal = journal
+
+    def __missing__(self, key):
+        event = self._load(key)
+        if event is None:
+            raise KeyError(key)
+        return event
+
+    def _load(self, key):
+        row = self.journal.db.execute(
+            "SELECT run_id,root_run_id,sequence,root_sequence,body FROM purra_output_events WHERE scope=? AND sdk='python' AND json_extract(body, '$[2].source_event_key[1]')=?",
+            (self.journal.scope, key),
+        ).fetchone()
+        if row is None:
+            return None
+        event = _validate_row(loads(row[4]), row)
+        if event.source_event_key != key:
+            raise ValueError("invalid output journal source key")
+        self[key] = event
+        return event
+
+    def get(self, key, default=None):
+        if key in self:
+            return self[key]
+        event = self._load(key)
+        return default if event is None else event
+
+
+class OutputJournal:
+    def __init__(self, db, scope):
+        self.db, self.scope = db, scope
+        db.execute("""CREATE TABLE IF NOT EXISTS purra_journal_runs (
+            scope TEXT NOT NULL, sdk TEXT NOT NULL, run_id TEXT NOT NULL,
+            root_run_id TEXT NOT NULL, PRIMARY KEY(scope,sdk,run_id),
+            FOREIGN KEY(scope,sdk) REFERENCES purra_state(scope,sdk) ON DELETE CASCADE)""")
+        db.execute("""CREATE TABLE IF NOT EXISTS purra_output_events (
+            scope TEXT NOT NULL, sdk TEXT NOT NULL, run_id TEXT NOT NULL,
+            sequence INTEGER NOT NULL, root_run_id TEXT NOT NULL,
+            root_sequence INTEGER NOT NULL, body TEXT NOT NULL,
+            PRIMARY KEY(scope,sdk,run_id,sequence),
+            UNIQUE(scope,sdk,root_run_id,root_sequence),
+            FOREIGN KEY(scope,sdk,run_id) REFERENCES purra_journal_runs(scope,sdk,run_id)
+                ON DELETE CASCADE)""")
+        db.execute("""CREATE UNIQUE INDEX IF NOT EXISTS purra_python_output_source
+            ON purra_output_events(scope, json_extract(body, '$[2].source_event_key[1]'))
+            WHERE sdk='python'""")
+        db.execute("""CREATE INDEX IF NOT EXISTS purra_output_sequence_cover
+            ON purra_output_events(scope,sdk,root_run_id,run_id,sequence,root_sequence)""")
+        db.execute("""CREATE INDEX IF NOT EXISTS purra_journal_roots
+            ON purra_journal_runs(scope,sdk,root_run_id,run_id)""")
+
+    def restore(self, state, *, root_run_id=None, lazy=False):
+        if lazy and root_run_id is not None:
+            self._restore_deferred(state, root_run_id)
+            return
+        if root_run_id is not None:
+            state.events_by_source_key = _SourceEvents(self)
+        rows = self.db.execute(
+            "SELECT run_id,root_run_id,sequence,root_sequence,body FROM purra_output_events WHERE scope=? AND sdk='python'"
+            + (" AND root_run_id=?" if root_run_id is not None else "")
+            + " ORDER BY root_run_id,root_sequence",
+            (self.scope, root_run_id) if root_run_id is not None else (self.scope,),
+        )
+        for event in _load_rows(rows):
+            if event.run_id not in state.runs:
+                raise ValueError("output journal references a missing Run")
+            if event.sequence != len(state.output_events.get(event.run_id, ())) + 1 or event.root_sequence != len(state.root_output_events.get(event.root_run_id, ())) + 1:
+                raise ValueError("invalid output journal sequence")
+            state.output_events.setdefault(event.run_id, []).append(event)
+            state.root_output_events.setdefault(event.root_run_id, []).append(event)
+            state.events_by_source_key[event.source_event_key] = event
+        if any(len(state.output_events.get(run_id, ())) != sequence
+               for run_id, sequence in state.sequences.items()
+               if root_run_id is None or (state.runs[run_id].params.root_run_id or run_id) == root_run_id):
+            raise ValueError("incomplete output journal")
+
+    def _restore_deferred(self, state, root_run_id):
+        # Check sequence completeness using indexed columns before accepting writes.
+        # Event bodies remain in SQLite until a Core rule asks for history evidence.
+        rows = self.db.execute(
+            "SELECT run_id,COUNT(*),MIN(sequence),MAX(sequence),MIN(root_sequence),MAX(root_sequence) "
+            "FROM purra_output_events WHERE scope=? AND sdk='python' AND root_run_id=? GROUP BY run_id",
+            (self.scope, root_run_id),
+        ).fetchall()
+        counts = {}
+        for run_id, count, first, last, _, _ in rows:
+            record = state.runs.get(run_id)
+            if record is None or (record.params.root_run_id or run_id) != root_run_id:
+                raise ValueError("output journal references a missing Run or wrong Root")
+            if first != 1 or last != count:
+                raise ValueError("invalid output journal sequence")
+            counts[run_id] = count
+        total = sum(counts.values())
+        if (total != state.root_sequences.get(root_run_id, 0)
+                or (rows and (min(row[4] for row in rows) != 1 or max(row[5] for row in rows) != total))):
+            raise ValueError("incomplete output journal")
+        for run_id, record in state.runs.items():
+            if (record.params.root_run_id or run_id) != root_run_id:
+                continue
+            count = counts.get(run_id, 0)
+            if count != state.sequences.get(run_id, 0):
+                raise ValueError("incomplete output journal")
+            state.output_events[run_id] = _BufferedEvents(
+                count, lambda run_id=run_id: self._load_history(run_id, root_run_id),
+            )
+        state.root_output_events[root_run_id] = _BufferedEvents(
+            total, lambda: self._load_history(root_run_id, root_run_id, root=True),
+        )
+        state.events_by_source_key = _SourceEvents(self)
+
+    def _load_history(self, run_id, root_run_id, *, root=False):
+        identity, sequence = ("root_run_id", "root_sequence") if root else ("run_id", "sequence")
+        rows = self.db.execute(
+            f"SELECT run_id,root_run_id,sequence,root_sequence,body FROM purra_output_events WHERE scope=? AND sdk='python' AND {identity}=? ORDER BY {sequence}",
+            (self.scope, run_id),
+        )
+        for expected, event in enumerate(_load_rows(rows), 1):
+            if (event.root_run_id != root_run_id or (not root and event.run_id != run_id)
+                    or (event.root_sequence if root else event.sequence) != expected):
+                raise ValueError("invalid output journal sequence")
+            yield event
+
+    def append(self, state, prior_sequences, prior_runs):
+        for run_id in state.runs.keys() - prior_runs:
+            record = state.runs[run_id]
+            self.db.execute(
+                "INSERT INTO purra_journal_runs VALUES (?, 'python', ?, ?)",
+                (self.scope, run_id, record.params.root_run_id or run_id),
+            )
+        for run_id, events in state.output_events.items():
+            self.db.executemany(
+                "INSERT INTO purra_output_events VALUES (?, 'python', ?, ?, ?, ?, ?)",
+                ((self.scope, run_id, event.sequence, event.root_run_id,
+                  event.root_sequence, dumps(event))
+                 for event in events[prior_sequences.get(run_id, 0):]),
+            )
+
+    def read(self, run_id, after, limit, *, root=False):
+        if after < 0:
+            raise ValueError("after root sequence must be non-negative" if root else "after sequence must be non-negative")
+        if limit <= 0:
+            raise ValueError("limit must be positive")
+        limit = operator.index(limit)
+        row = self.db.execute(
+            "SELECT version FROM purra_state WHERE scope=? AND sdk='python'", (self.scope,),
+        ).fetchone()
+        if row and row[0] != STORAGE_VERSION:
+            raise ValueError("unsupported SQLite storage version")
+        run = self.db.execute(
+            "SELECT root_run_id FROM purra_journal_runs WHERE scope=? AND sdk='python' AND run_id=?",
+            (self.scope, run_id),
+        ).fetchone() if row else None
+        if run is None:
+            raise ContractViolationError(f"run {run_id!r} does not exist", code="run_not_found")
+        if root and run[0] != run_id:
+            raise ContractViolationError("Root journal query requires a Root Run", code="run_scope_conflict")
+        identity, sequence = ("root_run_id", "root_sequence") if root else ("run_id", "sequence")
+        rows = self.db.execute(
+            f"SELECT run_id,root_run_id,sequence,root_sequence,body FROM purra_output_events WHERE scope=? AND sdk='python' AND {identity}=? AND {sequence}>? ORDER BY {sequence} LIMIT ?",
+            (self.scope, run_id, min(after, 2**63 - 1), min(limit, 2**63 - 1)),
+        )
+        return tuple(_load_rows(rows))

purra_sqlite-0.5.0.dist-info/METADATA

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: purra-sqlite
+Version: 0.5.0
+Summary: SQLite persistence for PurrA
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: purra==0.5.0
+Dynamic: license-file
+
+# purra-sqlite · Python
+
+English | [简体中文](README.zh-CN.md)
+
+SQLite persistence for PurrA Runs, events, operations, budgets, checkpoints, and
+tool receipts. Uses Python's standard library and requires Python 3.11+.
+
+## Install
+
+From the repository root:
+
+```sh
+python -m pip install . ./integrations/sqlite/python
+```
+
+## Configure
+
+Given your model `gateway` and Agent `preset`:
+
+```python
+from purra.api import AgentCore
+from purra_sqlite import SqliteAgentAdapters
+
+storage = SqliteAgentAdapters("agent.db", scope="user-1/project-1")
+core = AgentCore(
+    model_gateway=gateway,
+    preset=preset,
+    run_repository=storage.runs,
+    output_repository=storage.outputs,
+    output_publisher=storage.publisher,
+    execution_lease_store=storage.leases,
+)
+```
+
+Select `scope` from the application's authenticated user/project binding.
+The bundle also exposes `idempotency`, `run_tree`, `artifacts`,
+and `long_tasks` for the corresponding Core ports.
+
+## Recovery
+
+Use `storage.list_running()` to find interrupted Runs and
+`core.resume(run_id, request, options=...)` to resume an eligible checkpoint.
+Restore the original Agent configuration. Execution leases prevent concurrent owners.
+
+An interrupted external tool call may already have taken effect. Use
+`storage.reconcile_tool(...)` with its result or evidence that it did not execute
+before retrying. For persisted questions and answers, use
+[SqliteClarification](../../interaction/python/README.md).
+
+## Storage and shutdown
+
+Canonical output events are appended as rows with Run and Root sequence indexes.
+Event additions and the execution snapshot commit in one transaction. Output
+pagination and subscription polling neither load the execution snapshot nor
+acquire a writer lock. Run queries, lease lookup and `list_running()` remain
+read-only. Tool receipts, lease renewal/release, cancellation requests, Agent
+tree, Artifact and Long Task repository operations skip journal hydration and
+flushing. Writes with an identifiable Run or output stream validate the Root
+tree's sequence counts in SQL and buffer new events without decoding its history.
+Core rules that inspect history (including planning projections and terminal
+operation settlement) load the required Run's original events on demand.
+Shared budgets still use all sibling Run counters; event-key replay uses indexed
+lookups. Run reads retain complete Root journal hydration.
+Cross-Root event keys use an index; Python SQLite requires `json_extract`, and
+opening an existing v3 database creates this index on first use. Lease acquisition,
+public `transaction()` and operations without an identifiable Run still validate
+the full scope. Execution snapshots retain Run history,
+checkpoints and receipts and are still loaded and saved at scope granularity.
+This adapter therefore still suits bounded local workloads.
+Storage v3 rejects v1/v2 data without automatic migration; existing databases
+cannot be resumed directly.
+Python and TypeScript execution snapshots are not interchangeable.
+Both SDKs defer history loading for Run-scoped writes. SQL sequence checks scan the
+selected Root's covering index without fetching event body rows or sorting by
+Run. Root headers also have a covering index. Existing v3 databases build these
+indexes on opening; this takes time and disk space, and inserts maintain them.
+Metadata snapshots remain scope-sized, so these writes are
+not constant-cost. Event bodies are validated when read; lease acquisition and
+public transactions continue to decode the full journal.
+Body Run/Root ids and sequence values must match their SQL columns on every
+event read, including indexed replay and pagination. Inconsistent rows raise
+`ValueError` and roll back the current transaction; they are not automatically
+repaired. Unread event bodies remain deferred.
+
+From the repository root, measure empty output polling and tail pagination with
+100, 1,000 and 5,000 historical events:
+
+```sh
+PYTHONPATH=src:integrations/sqlite/python/src .venv/bin/python integrations/sqlite/python/scripts/benchmark_reads.py
+```
+
+This temporary-database benchmark reports warm median read latency, not
+concurrent throughput or real-model end-to-end performance.
+
+Measure tool receipt writes at the same journal sizes, including both claim and
+result-commit transactions:
+
+```sh
+PYTHONPATH=src:integrations/sqlite/python/src .venv/bin/python integrations/sqlite/python/scripts/benchmark_writes.py
+```
+
+The tool callback is local and has no external side effect; this excludes real
+business-tool and model latency.
+
+Measure active Run event writes beside a growing unrelated Root:
+
+```sh
+PYTHONPATH=src:integrations/sqlite/python/src .venv/bin/python integrations/sqlite/python/scripts/benchmark_run_writes.py
+```
+
+This measures isolation from other Roots, not scaling within a single growing Root.
+
+Measure appends, model-attempt reservations and checkpoint commits within the same
+growing Root (two warmups and ten measured writes per operation):
+
+```sh
+PYTHONPATH=src:integrations/sqlite/python/src .venv/bin/python integrations/sqlite/python/scripts/benchmark_execution_writes.py
+```
+
+The history consists of private domain events. This excludes planning evidence
+replay, concurrent throughput and real Provider latency.
+Add `--profile` to report journal preparation, execution-state encoding/decoding
+and the remaining transaction time separately. Phase medians are calculated
+independently and need not sum to the total median.
+
+The application owns database access, backups, and retention. Checkpoints contain
+private model data. Call `await core.close()` before `storage.close()`.
+
+## Opt-in closeout verification
+
+After building TypeScript Core and SQLite, run both SDKs through separate writer
+processes, transaction termination, tool-receipt reconciliation and checkpoint
+reopening. The default fixture has 20 Roots, 60 Runs, 20,000 events and 64 KiB
+checkpoint messages per Root; all databases and effect markers are temporary.
+
+```sh
+PYTHONPATH=src:integrations/sqlite/python/src .venv/bin/python integrations/sqlite/python/scripts/verify_load.py --output /tmp/purra-load.json
+```
+
+`scripts/verify_provider.py` additionally runs a synthetic lookup task against a
+user-selected DeepSeek configuration in a PurrTypos settings database. It requires
+network access and consumes real API tokens. Supply `--config-db`, `--config-id`
+and `--output`; add `.:integrations/openai/python/src` to `PYTHONPATH` and install
+the OpenAI SDK. Credentials are read in memory, never written to the report.
+Its explicit test transport maps `max_completion_tokens` to `max_tokens`, disables
+thinking, drops OpenAI-only options, and maps `developer` messages to `system`.
+This does not certify unmodified OpenAI transport compatibility with DeepSeek.
+The eager reference is current code with deferred hydration disabled, not a
+historical release. One paired run is functional evidence, not a latency SLA.

purra_sqlite-0.5.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+purra_sqlite/__init__.py,sha256=URe_F4wov4l-psxWF3qhnu7D1LNx-5eOLwGq2CDMH7I,15336
+purra_sqlite/codec.py,sha256=brnPcjmddLNOj3AtfSvuw_8Ozcs1CDA7eIjA6bhF2uw,2608
+purra_sqlite/journal.py,sha256=dFuVS-CdhMQ57z-Zg7i33yd0-VXC2jalw8dEAptcvbw,11046
+purra_sqlite-0.5.0.dist-info/licenses/LICENSE,sha256=WDxSqXCQAO9tUJEUbz6KLAOUqPg28NjIiLOxRn9XySI,1065
+purra_sqlite-0.5.0.dist-info/METADATA,sha256=EVO7Jc7us4Ygxw5YwZZ2X88sslUqwBC21Lxrt2HQQY0,7181
+purra_sqlite-0.5.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+purra_sqlite-0.5.0.dist-info/top_level.txt,sha256=XR4yWQgf1X7cFattGsdSmMbefT-3LUFDx7o6Xk4c9sM,13
+purra_sqlite-0.5.0.dist-info/RECORD,,

purra_sqlite-0.5.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

purra_sqlite-0.5.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lybrands
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

purra_sqlite-0.5.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+purra_sqlite