matrx-orm 3.1.253__tar.gz → 3.1.255__tar.gz

{matrx_orm-3.1.253 → matrx_orm-3.1.255}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matrx-orm
-Version: 3.1.253
+Version: 3.1.255
 Summary: Async-first PostgreSQL ORM with bidirectional migrations, schema introspection, many-to-many relationships, and built-in state caching
 Project-URL: Homepage, https://github.com/AI-Matrix-Engine/aidream-current
 Project-URL: Repository, https://github.com/AI-Matrix-Engine/aidream-current
@@ -26,7 +26,7 @@ Requires-Dist: asyncpg>=0.31.0
 Requires-Dist: cbor2<7,>=6.1.3
 Requires-Dist: cryptography>=43.0
 Requires-Dist: gitpython>=3.1.40
-Requires-Dist: matrx-utils>=2.0.87
+Requires-Dist: matrx-utils>=2.0.89
 Requires-Dist: psycopg-pool>=3.2.5
 Requires-Dist: psycopg[binary]>=3.2.5
 Requires-Dist: python-dotenv>=1.0

{matrx_orm-3.1.253 → matrx_orm-3.1.255}/matrx_orm/core/FEATURE.md

@@ -289,6 +289,28 @@ trip from a laptop): 435 → ~200 round trips. Pinned by
 `tests/level1/test_transaction_pool_release_sends_nothing.py` and
 `tests/level1/test_rls_session_scope.py`.
 
+**Snapshot isolation is selected only at the canonical transaction boundary.**
+`transaction(isolation=…)` accepts `read_committed`, `repeatable_read`, or
+`serializable` and emits the corresponding fixed `BEGIN ISOLATION LEVEL` clause;
+omitting it preserves plain `BEGIN`. Unknown values fail before connection
+acquisition. An explicit mode inside an existing transaction refuses before any
+savepoint or depth mutation because a savepoint cannot change the outer isolation;
+an ordinary nested transaction remains a savepoint. Opening GUCs still follow the
+BEGIN in their one ordered round trip. Pinned by
+`tests/level1/test_transaction_isolation.py`.
+
+**A top-level transaction does not outlive its physical cleanup.** COMMIT or
+ROLLBACK and adapter release run in one retained task; caller cancellation is
+remembered while repeated cancellation is consumed and the task is shielded and
+joined. Precedence is caller cancellation, then the original body error, then a
+cleanup error. Command and release faults are observed separately using only a
+fixed code, phase, exception type, and database alias; an unknown release fault
+terminates only an asyncpg proxy that still owns its backend. A successful COMMIT
+whose bounded pool reset times out remains successful because asyncpg has already
+discarded that backend; its diagnostic is metadata-only. Pinned by
+`tests/level1/test_transaction_top_level_cleanup.py` and
+`tests/level1/test_connection_poison_guard.py`.
+
 **A backend another client left read-only never refuses our writes.** A transaction
 pooler shares server connections with every client of the same login and never resets
 one between clients, so a session-level `SET default_transaction_read_only = on` (or

{matrx_orm-3.1.253 → matrx_orm-3.1.255}/matrx_orm/core/async_db_manager.py

@@ -64,6 +64,24 @@ from matrx_orm.core.write_retry import (
 logger = logging.getLogger("matrx_orm.async_db_manager")
 
 
+def _log_connection_release_failure(
+    *, config_name: str, code: str, error: BaseException
+) -> None:
+    error_type = type(error).__name__
+    logger.error(
+        "matrx_orm_connection_release_failed code=%s phase=release error_type=%s database=%s",
+        code,
+        error_type,
+        config_name,
+        extra={
+            "code": code,
+            "phase": "release",
+            "error_type": error_type,
+            "database": config_name,
+        },
+    )
+
+
 def _terminate_pool_after_loop_change(pool: Any, config_name: str) -> None:
     try:
         pool.terminate()
@@ -1271,10 +1289,10 @@ class AsyncDatabaseManager:
                     return
                 release_exc = task.exception()
                 if release_exc is not None:
-                    logger.error(
-                        "[matrx_orm] Connection release failed for '%s': %s",
-                        config_name,
-                        release_exc,
+                    _log_connection_release_failure(
+                        config_name=config_name,
+                        code="connection_release_failed",
+                        error=release_exc,
                     )
                     return
                 try:
@@ -1295,11 +1313,10 @@ class AsyncDatabaseManager:
                 # release timeout. The query already completed successfully, so
                 # this cleanup failure must not replace its result with a false
                 # request crash. Keep the pool-health signal loud.
-                logger.error(
-                    "[matrx_orm] Connection release timed out for '%s'; "
-                    "asyncpg discarded the connection: %s",
-                    config_name,
-                    release_exc,
+                _log_connection_release_failure(
+                    config_name=config_name,
+                    code="connection_release_timeout_discarded",
+                    error=release_exc,
                 )
             else:
                 try:

{matrx_orm-3.1.253 → matrx_orm-3.1.255}/matrx_orm/core/pooler_role.py

@@ -294,7 +294,7 @@ async def learn_login_role(conn: Any) -> str:
     both resets put a borrowed role back before ``session_user`` is read, so the
     answer is the role the backend authenticated as — never a borrowed one.
     """
-    async with conn.transaction():
+    async with conn.transaction(readonly=True):
         await conn.execute("RESET SESSION AUTHORIZATION")
         await conn.execute("RESET ROLE")
         row = await conn.fetchrow("SELECT session_user AS login_, current_user AS current_")
@@ -463,7 +463,7 @@ async def _pinned_reread(
     """
     last_role: tuple[str, str] | None = None
     for _ in range(REPROVE_ATTEMPTS):
-        async with conn.transaction():
+        async with conn.transaction(readonly=True):
             before = await conn.fetchrow("SELECT current_user, session_user")
             before_current = before["current_user"]
             before_session = before["session_user"]

{matrx_orm-3.1.253 → matrx_orm-3.1.255}/matrx_orm/core/transaction.py

@@ -21,11 +21,12 @@ automatically uses the same connection without any manual passing.
 
 Adapter decoupling
 ------------------
-The ``TransactionContext`` no longer imports asyncpg directly.  Instead it
-obtains its connection through ``AdapterRegistry.get(database).get_connection()``,
-which returns a raw asyncpg pool connection for the default adapter but can
-return any connection object for custom adapters, as long as that object
-supports ``.execute(sql)`` and ``.fetch(sql, *args)``.
+``TransactionContext`` obtains its connection through
+``AdapterRegistry.get(database).get_connection()``, which returns an asyncpg
+pool proxy for the default adapter but can return any connection object for
+custom adapters, as long as that object supports ``.execute(sql)`` and
+``.fetch(sql, *args)``. The one driver-specific check is the failed-release
+discard boundary: only an attached ``PoolConnectionProxy`` may be terminated.
 
 The ``_active_connection`` ContextVar is typed as ``Any`` so the rest of the
 ORM can hold a reference to the active connection without depending on asyncpg.
@@ -37,17 +38,71 @@ from __future__ import annotations
 
 import asyncio
 import contextvars
+import logging
 import os
 import re
 import uuid
 from collections.abc import AsyncIterator, Awaitable, Callable
 from contextlib import asynccontextmanager
 from contextvars import ContextVar, Token
-from typing import Any, TypeVar
+from typing import Any, Literal
+
+from asyncpg.pool import PoolConnectionProxy
 
 from matrx_orm.exceptions import DatabaseError
 
-_T = TypeVar("_T")
+logger = logging.getLogger("matrx_orm.transaction")
+
+type TransactionIsolation = Literal[
+    "read_committed", "repeatable_read", "serializable"
+]
+
+_ISOLATION_BEGIN_STATEMENTS: dict[TransactionIsolation, str] = {
+    "read_committed": "BEGIN ISOLATION LEVEL READ COMMITTED",
+    "repeatable_read": "BEGIN ISOLATION LEVEL REPEATABLE READ",
+    "serializable": "BEGIN ISOLATION LEVEL SERIALIZABLE",
+}
+
+
+def _begin_statement(isolation: TransactionIsolation | None) -> str:
+    if isolation is None:
+        return "BEGIN"
+    try:
+        return _ISOLATION_BEGIN_STATEMENTS[isolation]
+    except (KeyError, TypeError):
+        accepted = ", ".join(_ISOLATION_BEGIN_STATEMENTS)
+        raise ValueError(
+            f"Unsupported transaction isolation {isolation!r}; expected one of: {accepted}"
+        ) from None
+
+
+def _log_cleanup_failure(*, database: str, phase: str, error: BaseException) -> None:
+    error_type = type(error).__name__
+    logger.error(
+        "matrx_orm_transaction_cleanup_failed code=%s phase=%s error_type=%s database=%s",
+        "transaction_cleanup_failed",
+        phase,
+        error_type,
+        database,
+        extra={
+            "code": "transaction_cleanup_failed",
+            "phase": phase,
+            "error_type": error_type,
+            "database": database,
+        },
+    )
+
+
+def _discard_still_owned_asyncpg_proxy(connection: Any) -> None:
+    # asyncpg detaches a PoolConnectionProxy by clearing ``_con`` before that
+    # pool slot can be borrowed again. Only terminate while this exact proxy
+    # still owns its backend; never chase a holder or a later borrower.
+    if not isinstance(connection, PoolConnectionProxy) or connection._con is None:
+        return
+    try:
+        connection.terminate()
+    except Exception:
+        pass
 
 # ContextVar holding the active connection (if any) for the current task tree.
 _active_connection: ContextVar[Any | None] = ContextVar("_active_connection", default=None)
@@ -72,7 +127,7 @@ def in_person_scoped_session() -> bool:
 _savepoint_depth: ContextVar[int] = ContextVar("_savepoint_depth", default=0)
 
 
-async def outside_transaction(fn: Callable[[], Awaitable[_T]]) -> _T:
+async def outside_transaction[T](fn: Callable[[], Awaitable[T]]) -> T:
     """Await ``fn()`` on the process's own connection, outside the caller's transaction.
 
     For process-wide VOCABULARY reads (the entity-type registry) whose answer must not
@@ -278,8 +333,16 @@ class TransactionContext:
     On nested entry (active connection exists): creates a SAVEPOINT instead.
     """
 
-    def __init__(self, database: str, opening_gucs: dict[str, str] | None = None) -> None:
+    def __init__(
+        self,
+        database: str,
+        opening_gucs: dict[str, str] | None = None,
+        *,
+        isolation: TransactionIsolation | None = None,
+    ) -> None:
         self.database = database
+        self._isolation = isolation
+        self._begin_sql = _begin_statement(isolation)
         # Transaction-local GUCs the OPENER needs set at BEGIN (``rls_session``'s
         # claims + role), emitted in the same statement as the ceilings and the
         # declared session context — one round trip for all of them. Top-level only.
@@ -295,6 +358,14 @@ class TransactionContext:
     async def __aenter__(self) -> TransactionContext:
         existing = _active_connection.get()
         if existing is not None:
+            if self._isolation is not None:
+                raise DatabaseError(
+                    message=(
+                        "transaction(isolation=...) must open a TOP-LEVEL transaction: "
+                        "a nested savepoint cannot change the outer transaction's isolation."
+                    ),
+                    details={"database": self.database, "isolation": self._isolation},
+                )
             if self._opening_gucs:
                 raise DatabaseError(
                     message=(
@@ -329,7 +400,7 @@ class TransactionContext:
             conn = await self._adapter_cm.__aenter__()
             self._raw_conn = conn
             try:
-                await conn.execute("BEGIN")
+                await conn.execute(self._begin_sql)
             except BaseException as e:
                 await self._adapter_cm.__aexit__(type(e), e, e.__traceback__)
                 self._raw_conn = None
@@ -414,35 +485,72 @@ class TransactionContext:
                 # pool poisoned (an in-transaction connection causes the next
                 # consumer's first statement to fail with "transaction is
                 # aborted" and lose that request's data).
+                command_error: BaseException | None = None
+                release_error: BaseException | None = None
                 try:
                     if exc_type is None:
                         await conn_to_use.execute("COMMIT")
                     else:
                         await conn_to_use.execute("ROLLBACK")
-                except BaseException:
+                except BaseException as error:
+                    command_error = error
+                    _log_cleanup_failure(database=self.database, phase="command", error=error)
                     try:
                         conn_to_use.terminate()
                     except Exception:
                         pass
-                    raise
-                finally:
-                    if adapter_cm is not None:
+                if adapter_cm is not None:
+                    try:
                         await adapter_cm.__aexit__(exc_type, exc_val, exc_tb)
+                    except BaseException as error:
+                        release_error = error
+                        _log_cleanup_failure(database=self.database, phase="release", error=error)
+                        _discard_still_owned_asyncpg_proxy(conn_to_use)
+
+                if command_error is not None:
+                    raise command_error
+                if release_error is not None:
+                    raise release_error
+
+            # One retained task owns command + release. Caller cancellation is
+            # remembered and temporarily consumed while this task is shielded and
+            # joined; repeated cancellation cannot let the async-with frame escape
+            # with locks or a checkout still held. A child that cancels itself is
+            # distinguished by its completed/cancelled state, so it cannot spin.
+            teardown_task = asyncio.create_task(
+                _teardown(), name=f"matrx-orm-transaction-cleanup:{self.database}"
+            )
+            caller_cancelled = False
+            current_task = asyncio.current_task()
+            while not teardown_task.done():
+                try:
+                    await asyncio.shield(teardown_task)
+                except asyncio.CancelledError:
+                    if current_task is not None and current_task.cancelling():
+                        caller_cancelled = True
+                        current_task.uncancel()
+                        continue
+                    if teardown_task.done() and teardown_task.cancelled():
+                        break
+                    raise
+                except BaseException:
+                    if teardown_task.done():
+                        break
+                    raise
 
-            # SHIELD the teardown so an in-flight cancellation (hard-deadline,
-            # client disconnect, shutdown) can never SKIP the ROLLBACK and leak a
-            # poisoned (in-transaction) connection back to the pool. The shielded
-            # teardown runs to completion even when the outer await is canceled.
+            cleanup_error: BaseException | None = None
             try:
-                await asyncio.shield(_teardown())
-            except Exception:
-                # A teardown failure (e.g. COMMIT failed) must surface on the
-                # success path; on the error path the original exception wins.
-                if exc_type is None:
-                    raise
+                teardown_task.result()
+            except BaseException as error:
+                cleanup_error = error
+
+            if caller_cancelled:
+                raise asyncio.CancelledError
 
             if exc_type is not None:
                 return False  # re-raise the original exception
+            if cleanup_error is not None:
+                raise cleanup_error
 
         return False  # never suppress exceptions
 
@@ -497,17 +605,23 @@ def _opening_statement_gucs(opening_gucs: dict[str, str]) -> dict[str, str]:
 
 
 def transaction(
-    database: str | None = None, *, opening_gucs: dict[str, str] | None = None
+    database: str | None = None,
+    *,
+    opening_gucs: dict[str, str] | None = None,
+    isolation: TransactionIsolation | None = None,
 ) -> TransactionContext:
     """Return a ``TransactionContext`` async context manager.
 
     ``database`` defaults to the first configured database when omitted.
     ``opening_gucs`` are transaction-local settings the opener needs at BEGIN;
     they ride the one opening statement (top-level transactions only).
+    ``isolation`` selects one of the fixed PostgreSQL isolation clauses; an
+    explicit mode is top-level only.
     """
+    _begin_statement(isolation)
     if database is None:
         database = _get_default_database()
-    return TransactionContext(database, opening_gucs)
+    return TransactionContext(database, opening_gucs, isolation=isolation)
 
 
 def _get_default_database() -> str:

{matrx_orm-3.1.253 → matrx_orm-3.1.255}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.253"
+version = "3.1.255"
 description = "Async-first PostgreSQL ORM with bidirectional migrations, schema introspection, many-to-many relationships, and built-in state caching"
 readme = "README.md"
 license = { text = "MIT" }
@@ -41,7 +41,7 @@ dependencies = [
     "gitpython>=3.1.40",
     "psycopg[binary]>=3.2.5",
     "psycopg-pool>=3.2.5",
-    "matrx-utils>=2.0.87",
+    "matrx-utils>=2.0.89",
     "pyyaml>=6.0.3",
     "python-dotenv>=1.0",
     "cryptography>=43.0",

{matrx_orm-3.1.253 → matrx_orm-3.1.255}/tests/level1/test_connection_poison_guard.py

@@ -14,6 +14,8 @@ connection is terminated (never reused).
 
 from __future__ import annotations
 
+import asyncio
+
 import pytest
 from matrx_orm.core.async_db_manager import AsyncDatabaseManager
 from matrx_orm.exceptions import StateError
@@ -84,13 +86,35 @@ class _FakePool:
 
 
 class _ReleaseTimeoutPool(_FakePool):
+    async def release(
+        self,
+        conn: _FakeConn,
+        timeout: float | None = None,  # noqa: ASYNC109 - mirrors asyncpg
+    ) -> None:
+        del timeout
+        # Installed asyncpg discards the physical backend before surfacing a
+        # reset timeout from Pool.release(). This fake owns that network edge.
+        conn.terminate()
+        raise TimeoutError("private reset payload exceeded release budget")
+
+
+class _GatedReleaseFailurePool(_FakePool):
+    def __init__(self, conn: _FakeConn) -> None:
+        super().__init__(conn)
+        self.release_started = asyncio.Event()
+        self.release_gate = asyncio.Event()
+        self.release_finished = asyncio.Event()
+
     async def release(
         self,
         conn: _FakeConn,
         timeout: float | None = None,  # noqa: ASYNC109 - mirrors asyncpg
     ) -> None:
         del conn, timeout
-        raise TimeoutError("reset exceeded release budget")
+        self.release_started.set()
+        await self.release_gate.wait()
+        self.release_finished.set()
+        raise RuntimeError("private delayed release payload")
 
 
 def _patch_pool(monkeypatch, pool: _FakePool) -> None:
@@ -146,4 +170,55 @@ async def test_release_timeout_does_not_replace_successful_query_result(monkeypa
     result = await AsyncDatabaseManager.execute_query("x", "SELECT 1 AS value")
 
     assert result == [{"value": 1}]
-    assert "Connection release timed out for 'x'" in caplog.text
+    assert "TERMINATE" in conn.calls
+    records = [
+        record
+        for record in caplog.records
+        if record.name == "matrx_orm.async_db_manager"
+        and getattr(record, "code", None) == "connection_release_timeout_discarded"
+    ]
+    assert len(records) == 1
+    record = records[0]
+    assert record.phase == "release"
+    assert record.error_type == "TimeoutError"
+    assert record.database == "x"
+    assert record.exc_info is None and record.stack_info is None
+    assert not any(isinstance(arg, BaseException) for arg in record.args)
+    assert "private reset payload" not in record.getMessage()
+
+
+async def test_cancelled_holder_observes_late_release_failure_without_private_text(
+    monkeypatch, caplog
+):
+    conn = _FakeConn(in_tx=False)
+    pool = _GatedReleaseFailurePool(conn)
+    _patch_pool(monkeypatch, pool)
+
+    async def use_connection() -> None:
+        async with AsyncDatabaseManager.get_connection("x"):
+            pass
+
+    with caplog.at_level("ERROR", logger="matrx_orm.async_db_manager"):
+        caller = asyncio.create_task(use_connection())
+        await pool.release_started.wait()
+        caller.cancel()
+        with pytest.raises(asyncio.CancelledError):
+            await caller
+        pool.release_gate.set()
+        await pool.release_finished.wait()
+        await asyncio.sleep(0)
+
+    records = [
+        record
+        for record in caplog.records
+        if record.name == "matrx_orm.async_db_manager"
+        and getattr(record, "code", None) == "connection_release_failed"
+    ]
+    assert len(records) == 1
+    record = records[0]
+    assert record.phase == "release"
+    assert record.error_type == "RuntimeError"
+    assert record.database == "x"
+    assert record.exc_info is None and record.stack_info is None
+    assert not any(isinstance(arg, BaseException) for arg in record.args)
+    assert "private delayed release payload" not in record.getMessage()

{matrx_orm-3.1.253 → matrx_orm-3.1.255}/tests/level1/test_guarded_read_never_reruns_empty.py

@@ -47,7 +47,8 @@ class _Conn:
         self.borrowed = borrowed
         self.log: list[str] = []
 
-    def transaction(self) -> _Tx:
+    def transaction(self, *, readonly: bool = False) -> _Tx:
+        assert readonly is True
         return _Tx(self)
 
     async def execute(self, sql: str, *_a: object, **_k: object) -> None:

{matrx_orm-3.1.253 → matrx_orm-3.1.255}/tests/level1/test_read_connection_retry.py

@@ -71,7 +71,8 @@ async def test_read_retries_disconnect_masked_by_reproof_transaction(monkeypatch
                 "connection was closed in the middle of operation"
             )
 
-        def transaction(self):
+        def transaction(self, *, readonly: bool = False):
+            assert readonly is True
             return MaskingTransaction()
 
         def is_closed(self) -> bool:
@@ -91,7 +92,8 @@ async def test_read_retries_disconnect_masked_by_reproof_transaction(monkeypatch
         async def fetchrow(self, *_args, **_kwargs):
             return {"login_": "postgres", "current_": "postgres"}
 
-        def transaction(self):
+        def transaction(self, *, readonly: bool = False):
+            assert readonly is True
             class _Tx:
                 async def __aenter__(self):
                     return self