loopiter 0.2.0a1__py3-none-any.whl

loopiter/postgres.py

@@ -0,0 +1,161 @@
+"""Optional psycopg 3 adapter. Importing loopiter does not import a database driver."""
+
+import asyncio
+from contextlib import asynccontextmanager
+from importlib.resources import files
+from typing import TYPE_CHECKING
+
+from . import _validation as v
+from .store import page_options
+
+if TYPE_CHECKING:
+    from psycopg_pool import AsyncConnectionPool
+
+
+def migration_sql() -> str:
+    """Return versioned SQL for the application's migration process; execute explicitly."""
+    return files("loopiter").joinpath("migrations/001-python-store.sql").read_text(encoding="utf-8")
+
+
+class PostgresTransaction:
+    def __init__(self, namespace, connection):
+        self.namespace, self.connection, self.active = namespace, connection, True
+        self.owner = asyncio.current_task()
+
+    def _check(self, kind):
+        if not self.active or asyncio.current_task() is not self.owner:
+            v.fail("transaction_closed", "Transaction closed or used from a different task.")
+        v.enum(kind, v.COLLECTIONS, "collection")
+
+    async def _query(self, sql, params):
+        # Use explicit row factory even when the application configures a different default.
+        from psycopg.rows import tuple_row
+
+        async with self.connection.cursor(row_factory=tuple_row) as cur:
+            await cur.execute(sql, params)
+            return await cur.fetchall()
+
+    async def get(self, collection, key):
+        self._check(collection)
+        v.nonempty(key, "id")
+        rows = await self._query(
+            "SELECT body FROM loopiter_python_records WHERE namespace=%s AND collection=%s AND id=%s",
+            (self.namespace, collection, key),
+        )
+        return rows[0][0] if rows else None
+
+    async def list(self, collection, *, limit=100, cursor=None, window=None):
+        self._check(collection)
+        page_options(limit, cursor, window)
+        window = window or {}
+        rows = await self._query(
+            "SELECT body FROM loopiter_python_records WHERE namespace=%s AND collection=%s "
+            'AND (%s::text IS NULL OR id > %s COLLATE "C") '
+            "AND (%s::timestamptz IS NULL OR event_time >= %s::timestamptz) "
+            "AND (%s::timestamptz IS NULL OR event_time < %s::timestamptz) ORDER BY id LIMIT %s",
+            (
+                self.namespace,
+                collection,
+                cursor,
+                cursor,
+                window.get("from"),
+                window.get("from"),
+                window.get("to"),
+                window.get("to"),
+                limit + 1,
+            ),
+        )
+        result = {"items": [r[0] for r in rows[:limit]]}
+        if len(rows) > limit:
+            result["next_cursor"] = result["items"][-1]["id"]
+        return result
+
+    async def insert(self, collection, record):
+        from psycopg.types.json import Jsonb
+
+        self._check(collection)
+        v.stored(collection, record, self.namespace)
+        if record["revision"] != 1:
+            v.fail("conflict", "Insert requires revision 1.")
+        rows = await self._query(
+            "INSERT INTO loopiter_python_records(namespace,collection,id,revision,event_time,body) "
+            "VALUES (%s,%s,%s,%s,%s,%s) ON CONFLICT DO NOTHING RETURNING id",
+            (
+                self.namespace,
+                collection,
+                record["id"],
+                1,
+                record.get("observed_at", record.get("started_at", record["created_at"])),
+                Jsonb(record),
+            ),
+        )
+        if not rows:
+            v.fail("conflict", "Record already exists.")
+
+    async def replace(self, collection, record, expected_revision):
+        from psycopg.types.json import Jsonb
+
+        self._check(collection)
+        v.stored(collection, record, self.namespace)
+        v.integer(expected_revision, "expected_revision")
+        if collection in ("signals", "events"):
+            v.fail("immutable_record", "Collection is insert-only.")
+        if record["revision"] != expected_revision + 1:
+            v.fail("conflict", "Replacement revision must increment by one.")
+        rows = await self._query(
+            "UPDATE loopiter_python_records SET revision=%s, event_time=%s, body=%s "
+            "WHERE namespace=%s AND collection=%s AND id=%s AND revision=%s RETURNING id",
+            (
+                record["revision"],
+                record.get("observed_at", record.get("started_at", record["created_at"])),
+                Jsonb(record),
+                self.namespace,
+                collection,
+                record["id"],
+                expected_revision,
+            ),
+        )
+        if not rows:
+            v.fail("conflict", "Revision conflict.")
+
+
+class PostgresStore:
+    """Developer-owned AsyncConnectionPool. Does not migrate or close the supplied pool.
+
+    Namespace advisory locking serializes ALL conforming writers. Use this adapter
+    for every write; do not mutate records directly. Separate namespaces can progress
+    concurrently. Configure pool timeouts/TLS/DB statement limits in your app.
+    """
+
+    version = 1
+
+    def __init__(self, pool: "AsyncConnectionPool"):
+        if not callable(getattr(pool, "connection", None)):
+            v.fail("invalid_input", "Expected a developer-owned async psycopg pool.")
+        self.pool = pool
+
+    @asynccontextmanager
+    async def transaction(self, namespace):
+        v.nonempty(namespace, "namespace")
+        async with self.pool.connection() as connection:
+            async with connection.transaction():
+                # READ COMMITTED refreshes snapshot after a contended lock is acquired.
+                await connection.execute("SET TRANSACTION ISOLATION LEVEL READ COMMITTED")
+                await connection.execute(
+                    "SELECT pg_advisory_xact_lock(hashtextextended(%s, 0))",
+                    ("loopiter/python/v1/" + namespace,),
+                )
+                tx = PostgresTransaction(namespace, connection)
+                try:
+                    yield tx
+                finally:
+                    tx.active = False
+
+    async def delete_namespace(self, namespace):
+        async with self.transaction(namespace) as tx:
+            await tx.connection.execute(
+                "DELETE FROM loopiter_python_records WHERE namespace=%s", (namespace,)
+            )
+
+    async def close(self):
+        pass  # Application owns the pool's lifecycle.

loopiter/store.py

@@ -0,0 +1,143 @@
+"""Python store contract v1. Namespace-serializable, atomic, short transactions."""
+
+import asyncio
+from contextlib import AbstractAsyncContextManager, asynccontextmanager
+from copy import deepcopy
+from typing import Protocol
+
+from ._validation import (
+    COLLECTIONS,
+    Record,
+    enum,
+    fail,
+    in_window,
+    integer,
+    nonempty,
+    stored,
+    window_valid,
+)
+
+
+class StoreTransaction(Protocol):
+    async def get(self, collection: str, key: str) -> Record | None: ...
+    async def list(
+        self,
+        collection: str,
+        *,
+        limit: int = 100,
+        cursor: str | None = None,
+        window: Record | None = None,
+    ) -> Record: ...
+    async def insert(self, collection: str, record: Record) -> None: ...
+    async def replace(self, collection: str, record: Record, expected_revision: int) -> None: ...
+
+
+class FeedbackStore(Protocol):
+    version: int
+
+    def transaction(self, namespace: str) -> AbstractAsyncContextManager[StoreTransaction]: ...
+    async def delete_namespace(self, namespace: str) -> None: ...
+    async def close(self) -> None: ...
+
+
+def page_options(limit: int, cursor: str | None, window: Record | None) -> None:
+    integer(limit, "page limit")
+    if limit > 1000:
+        fail("query_limit", "Page limit cannot exceed 1000.")
+    if cursor is not None:
+        nonempty(cursor, "cursor")
+    window_valid({} if window is None else window)
+
+
+class MemoryTransaction:
+    def __init__(self, namespace: str, state: Record):
+        self.namespace, self.state, self.active = namespace, state, True
+        self.owner = asyncio.current_task()
+
+    def check(self, collection: str) -> None:
+        if not self.active or asyncio.current_task() is not self.owner:
+            fail("transaction_closed", "Transaction closed or used from a different task.")
+        enum(collection, COLLECTIONS, "collection")
+
+    async def get(self, collection: str, key: str) -> Record | None:
+        self.check(collection)
+        nonempty(key, "id")
+        return deepcopy(self.state.get(collection, {}).get(key))
+
+    async def list(
+        self,
+        collection: str,
+        *,
+        limit: int = 100,
+        cursor: str | None = None,
+        window: Record | None = None,
+    ) -> Record:
+        self.check(collection)
+        page_options(limit, cursor, window)
+        rows = sorted(
+            (
+                row
+                for row in self.state.get(collection, {}).values()
+                if (cursor is None or row["id"] > cursor)
+                and in_window(
+                    row.get("observed_at", row.get("started_at", row["created_at"])), window or {}
+                )
+            ),
+            key=lambda row: row["id"],
+        )
+        page = {"items": deepcopy(rows[:limit])}
+        if len(rows) > limit:
+            page["next_cursor"] = rows[limit - 1]["id"]
+        return page
+
+    async def insert(self, collection: str, record: Record) -> None:
+        self.check(collection)
+        stored(collection, record, self.namespace)
+        bucket = self.state.setdefault(collection, {})
+        if record["id"] in bucket or record["revision"] != 1:
+            fail("conflict", "Insert requires a new ID and revision 1.")
+        bucket[record["id"]] = deepcopy(record)
+
+    async def replace(self, collection: str, record: Record, expected_revision: int) -> None:
+        self.check(collection)
+        stored(collection, record, self.namespace)
+        integer(expected_revision, "expected_revision")
+        if collection in ("signals", "events"):
+            fail("immutable_record", "Collection is insert-only.")
+        previous = self.state.get(collection, {}).get(record["id"])
+        if (
+            not previous
+            or previous["revision"] != expected_revision
+            or record["revision"] != expected_revision + 1
+        ):
+            fail("conflict", "Revision conflict.")
+        self.state[collection][record["id"]] = deepcopy(record)
+
+
+class InMemoryStore:
+    """Development only. One asyncio event loop; no multi-process durability."""
+
+    version = 1
+
+    def __init__(self) -> None:
+        self._state: Record = {}
+        self._lock = asyncio.Lock()
+
+    @asynccontextmanager
+    async def transaction(self, namespace: str):
+        nonempty(namespace, "namespace")
+        async with self._lock:
+            tx = MemoryTransaction(namespace, deepcopy(self._state.get(namespace, {})))
+            try:
+                yield tx
+                self._state[namespace] = deepcopy(tx.state)
+            finally:
+                tx.active = False
+
+    async def delete_namespace(self, namespace: str) -> None:
+        nonempty(namespace, "namespace")
+        async with self._lock:
+            self._state.pop(namespace, None)
+
+    async def close(self) -> None:
+        pass

loopiter/testing.py

@@ -0,0 +1,95 @@
+"""Executable adapter conformance checks. Use only an explicitly disposable namespace."""
+
+import asyncio
+from copy import deepcopy
+from uuid import uuid4
+
+from . import FeedbackLoop, LoopiterError
+from .store import FeedbackStore
+
+
+async def run_store_conformance(store: FeedbackStore, *, namespace: str | None = None) -> None:
+    """Asserts transaction, revision, idempotency, isolation and pagination guarantees.
+
+    Creates/deletes its own unique namespaces. Supplying a namespace is an explicit
+    request to clear that namespace; never pass a production namespace.
+    Does not close the developer-owned store/pool. Raises AssertionError on failure.
+    """
+    namespace = namespace or f"loopiter-conformance/{uuid4()}"
+    other = namespace + "/isolated"
+    loop = FeedbackLoop(store=store, namespace=namespace)
+    isolated = FeedbackLoop(store=store, namespace=other)
+    try:
+        first = await loop.record_execution(id="a", kind="prediction")
+        assert await loop.record_execution(id="a", kind="prediction") == first
+        assert await isolated.get_execution("a") is None
+        await isolated.record_execution(id="a", kind="tool")
+        try:
+            await loop.record_execution(id="a", kind="tool")
+        except LoopiterError as e:
+            assert e.code == "conflict"
+        else:
+            raise AssertionError("Conflicting insert overwrote an existing record")
+        results = await asyncio.gather(
+            *(
+                loop.complete_execution("a", expected_revision=1, output={"attempt": i})
+                for i in range(2)
+            ),
+            return_exceptions=True,
+        )
+        assert sum(isinstance(r, dict) for r in results) == 1
+        assert sum(isinstance(r, LoopiterError) and r.code == "conflict" for r in results) == 1
+        current = await loop.get_execution("a")
+        async with store.transaction(namespace) as tx:
+            leaked = tx
+            record = deepcopy(current)
+            record.update(id="b", revision=1)
+            await tx.insert("executions", record)
+        try:
+            await leaked.get("executions", "a")
+        except LoopiterError as e:
+            assert e.code == "transaction_closed"
+        else:
+            raise AssertionError("Completed transaction remained usable")
+        try:
+            async with store.transaction(namespace) as tx:
+                record = deepcopy(first)
+                record["id"] = "rolled-back"
+                await tx.insert("executions", record)
+                raise RuntimeError("injected rollback")
+        except RuntimeError:
+            pass
+        assert await loop.get_execution("rolled-back") is None
+        async with store.transaction(namespace) as tx:
+            returned = await tx.get("executions", "a")
+            returned["kind"] = "custom"
+        assert (await loop.get_execution("a"))["kind"] == "prediction"
+        page = await loop.list("executions", limit=1)
+        assert [r["id"] for r in page["items"]] == ["a"]
+        assert [
+            r["id"] for r in (await loop.list("executions", cursor=page["next_cursor"]))["items"]
+        ] == ["b"]
+        signal = await loop.record_signal(
+            id="signal", execution_id="a", kind="rating", name="correct", value=True, source="test"
+        )
+        try:
+            async with store.transaction(namespace) as tx:
+                signal["revision"] += 1
+                await tx.replace("signals", signal, 1)
+        except LoopiterError as e:
+            assert e.code == "immutable_record"
+        else:
+            raise AssertionError("Signal was mutable")
+        try:
+            async with store.transaction(other) as tx:
+                await tx.insert("executions", first)
+        except LoopiterError as e:
+            assert e.code == "namespace_mismatch"
+        else:
+            raise AssertionError("Cross-namespace write accepted")
+        await loop.delete_namespace(confirmation=namespace)
+        assert await loop.get_execution("a") is None
+        assert (await isolated.get_execution("a"))["kind"] == "tool"
+    finally:
+        await store.delete_namespace(namespace)
+        await store.delete_namespace(other)