matrx-orm 3.1.241__tar.gz → 3.1.243__tar.gz

{matrx_orm-3.1.241 → matrx_orm-3.1.243}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matrx-orm
-Version: 3.1.241
+Version: 3.1.243
 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.80
+Requires-Dist: matrx-utils>=2.0.83
 Requires-Dist: psycopg-pool>=3.2.5
 Requires-Dist: psycopg[binary]>=3.2.5
 Requires-Dist: python-dotenv>=1.0

{matrx_orm-3.1.241 → matrx_orm-3.1.243}/matrx_orm/core/FEATURE.md

@@ -261,14 +261,21 @@ pinned server session's identity before and after `RESET SESSION AUTHORIZATION`
 borrowed role. This also repairs both `SET ROLE` and `SET SESSION AUTHORIZATION`;
 `RESET ROLE` alone does not repair the latter.
 
-**A clean, genuinely empty read is proved in ONE statement.** Before the pinned
-re-proof, `prove_empty_in_one_statement` runs `current_user`, `session_user`, the
-backend's login role (`pg_stat_activity.usename`, which `SET SESSION AUTHORIZATION`
-does not change) and `EXISTS (<query>)` as one statement — one server connection,
-one role. All three identities equal and no row: proven empty, one round trip
-instead of seven. Any other outcome (borrowed role, session-authorization swap,
-unreadable login, rows that appeared, a query that cannot embed, any error) runs
-the full repairing re-proof unchanged. Pinned by `tests/test_pooler_role_guard.py`.
+**A read proves its own role; an empty result is never re-run** (2026-10-21). On a
+transaction pool every single SELECT/WITH read is sent as `guarded_read_sql(query,
+login)`: `SELECT * FROM (<query>) _matrx_guarded_read WHERE CASE WHEN current_user =
+<login> AND session_user = <login> THEN true ELSE ('matrx_orm_borrowed_role:' ||
+current_user)::int > 0 END`. The guard has no column references, so Postgres runs it
+as a one-time filter before the scan (verified live with EXPLAIN; order and duplicate
+column names preserved). A clean answer, empty or not, is proven by that one
+statement; a borrowed role RAISES (22P02 naming the role), and only then does
+`repair_guarded_read` emit the contamination alarm and re-read on a pinned, reset
+session. `<login>` is learned once per pool by `learn_login_role` (pinned transaction,
+both resets, `session_user`). Before this, every zero-row read was re-run as an
+`EXISTS` proof: 3.5M extra statements in 5.7 h on the live database. A query that
+cannot be wrapped (multi-statement, SHOW, VALUES) keeps the old path
+(`prove_empty_in_one_statement`, then the pinned re-proof). Pinned by
+`tests/level1/test_guarded_read_never_reruns_empty.py` and `tests/test_pooler_role_guard.py`.
 
 **Round trips are the launch cost on a remote pooler.** Every top-level BEGIN sets
 its ceilings, the host's declared session context and the opener's own settings

{matrx_orm-3.1.241 → matrx_orm-3.1.243}/matrx_orm/core/async_db_manager.py

@@ -23,6 +23,10 @@ from matrx_orm.core.foreign_session_state import run_clearing_foreign_restrict
 from matrx_orm.core.pooler_role import (
     VERIFY_EMPTY_READS,
     assert_no_session_role_change,
+    borrowed_role_from_error,
+    guarded_read_sql,
+    learn_login_role,
+    repair_guarded_read,
     reprove_empty_read,
 )
 from matrx_orm.core.statement_ceiling import resolve_driver_timeout
@@ -454,6 +458,9 @@ class AsyncDatabaseManager:
     # Only a transaction-mode pool can be handed a server connection another
     # client left wearing a role, so a direct Postgres pays nothing.
     _empty_read_verification: dict[str, bool] = {}
+    # Our own login role per transaction-pool config, learned ONCE on a pinned,
+    # reset session; every guarded read compares the backend's identity to it.
+    _login_roles: dict[str, str] = {}
 
     @classmethod
     def _verifies_empty_reads(cls, config_name: str) -> bool:
@@ -1464,11 +1471,56 @@ class AsyncDatabaseManager:
                         in_transaction=False,
                     )
                     try:
+                        # Layer 2: on a transaction pool the read carries its own
+                        # role proof (pooler_role.guarded_read_sql). A clean result —
+                        # empty or not — is proven by this one statement; the guard
+                        # RAISES on a borrowed role, and only then is the read repaired.
+                        guarded_sql: str | None = None
+                        login_role: str | None = None
+                        if (
+                            verify_empty
+                            and read_only
+                            and cls._verifies_empty_reads(config_name)
+                        ):
+                            login_role = cls._login_roles.get(config_name)
+                            if login_role is None:
+                                login_role = await learn_login_role(conn)
+                                cls._login_roles[config_name] = login_role
+                            guarded_sql = guarded_read_sql(query, login_role)
+                        repaired: list[list[dict[str, Any]]] = []
+
+                        async def _fetch() -> list[Any]:
+                            if guarded_sql is None:
+                                return await conn.fetch(query, *args, timeout=driver_timeout)
+                            try:
+                                return await conn.fetch(
+                                    guarded_sql, *args, timeout=driver_timeout
+                                )
+                            except asyncpg.exceptions.InvalidTextRepresentationError as exc:
+                                borrowed = borrowed_role_from_error(exc)
+                                if borrowed is None:
+                                    raise
+                                repaired.append(
+                                    await repair_guarded_read(
+                                        conn,
+                                        config_name=config_name,
+                                        query=query,
+                                        args=args,
+                                        statement_timeout=driver_timeout,
+                                        normalize=_normalize_record,
+                                        borrowed_role=borrowed,
+                                        login_role=login_role or "<unknown>",
+                                    )
+                                )
+                                return []
+
                         results = await run_clearing_foreign_restrict(
                             conn,
-                            lambda: conn.fetch(query, *args, timeout=driver_timeout),
+                            _fetch,
                             what=f"execute_query {query[:80]!r}",
                         )
+                        if repaired:
+                            return repaired[0]
                         if read_attempt > 0:
                             logger.warning(
                                 "[read-retry] SELECT HEALED on attempt %d after a "
@@ -1478,14 +1530,16 @@ class AsyncDatabaseManager:
                             )
                         if (
                             not results
+                            and guarded_sql is None
                             and verify_empty
                             and read_only
                             and cls._verifies_empty_reads(config_name)
                         ):
-                            # Layer 2: an empty result from a pooled connection is
-                            # unproven until a session that can state its own role
-                            # says so. A borrowed `authenticated` role returns ZERO
-                            # ROWS on an RLS table instead of raising.
+                            # A read that could not carry its own guard (not one
+                            # SELECT/WITH statement): an empty result from a pooled
+                            # connection is unproven until a session that can state
+                            # its own role says so. A borrowed `authenticated` role
+                            # returns ZERO ROWS on an RLS table instead of raising.
                             true_rows = await reprove_empty_read(
                                 conn,
                                 config_name=config_name,

{matrx_orm-3.1.241 → matrx_orm-3.1.243}/matrx_orm/core/pooler_role.py

@@ -35,9 +35,17 @@ TWO INDEPENDENT LAYERS, each sufficient alone, each screaming when it fires:
    this guards everything else. The sanctioned ways to change role remain
    ``matrx_orm.rls_session`` and ``db/pooler_session.py::impersonate``.
 
-2. **Reconciliation — an empty read is re-proved on a session that can prove its
-   role.** A zero-row result from a read-only query on a transaction-pool config
-   is re-run inside an explicit transaction (pinned to ONE server connection).
+2. **Proof in the read itself, repair only when it fires.** On a transaction-pool
+   config every read-only query is sent wrapped by ``guarded_read_sql``: the
+   statement carries a one-time filter that RAISES when the backend's
+   ``current_user``/``session_user`` is not our login role (learned once per pool
+   by ``learn_login_role``). One statement runs on one server connection, so a
+   clean answer — rows or no rows — is proven by the same round trip that read
+   it; nothing is ever re-run because a result was empty (2026-10-21: the old
+   per-empty-result re-proof was 3.5M extra statements in 5.7 h). Only when the
+   guard fires, or a query cannot be wrapped (multi-statement), does the
+   repairing re-read below run: re-run inside an explicit transaction (pinned to
+   ONE server connection).
    The pinned session's identity is captured before and after resetting session
    authorization and role. The caller gets any rows that appeared, but a
    contamination alarm is emitted only when the role change was directly
@@ -46,9 +54,9 @@ TWO INDEPENDENT LAYERS, each sufficient alone, each screaming when it fires:
 
 Layer 2 follows the repo's guard doctrine: a guard that CAN reconcile MUST
 reconcile — we hold the correct answer, so killing the caller's request would be
-strictly worse than returning it loudly. It costs nothing on a non-empty read and
-nothing at all on a direct (session-mode) Postgres connection, where cross-client
-contamination cannot happen.
+strictly worse than returning it loudly. A clean read pays one constant
+one-time filter; a direct (session-mode) Postgres connection pays nothing at all,
+because cross-client contamination cannot happen there.
 """
 
 from __future__ import annotations
@@ -223,6 +231,115 @@ async def emit_contamination(event: EmptyReadContaminationEvent) -> None:
             logger.exception("[pooler-role] contamination sink raised")
 
 
+# The text the guard's one-time filter raises with. ``('<sentinel>' || role)::int``
+# fails with 22P02 and names the borrowed role; nothing else in a read produces it.
+BORROWED_ROLE_SENTINEL = "matrx_orm_borrowed_role:"
+_SENTINEL_IN_ERROR = re.compile(re.escape(BORROWED_ROLE_SENTINEL) + r"([^\"']*)")
+
+
+def _sql_literal(value: str) -> str:
+    return "'" + value.replace("'", "''") + "'"
+
+
+def guarded_read_sql(query: str, login_role: str | None) -> str | None:
+    """``query`` wrapped so the read proves its own role, or ``None`` if it cannot be.
+
+    ``SELECT * FROM (<query>) _q WHERE <guard>``: the guard has no column
+    references, so Postgres plans it as a ONE-TIME FILTER evaluated once before
+    the scan (measured live 2026-10-21 — ``Result / One-Time Filter`` over the
+    original plan, order and duplicate column names preserved). On our login
+    role it is ``true``; on any other ``current_user`` or ``session_user`` it
+    casts ``BORROWED_ROLE_SENTINEL || current_user`` to int and RAISES, so a
+    borrowed role can never come back as an empty or partial result. Comparing
+    both identities against the login role learned for this pool also catches a
+    ``SET SESSION AUTHORIZATION`` swap, where the two agree on the wrong name.
+
+    Returns ``None`` (caller falls back to the repairing re-proof on empty) for
+    a query that is not a single SELECT/WITH statement or when the login role is
+    not yet known.
+    """
+    if not login_role:
+        return None
+    body = query.strip().rstrip(";").strip()
+    if not body or ";" in body:
+        return None
+    head = body.lstrip("( \n\t")[:6].lower()
+    if not (head.startswith("select") or head.startswith("with")):
+        # A leading comment, VALUES, TABLE, SHOW, EXPLAIN: not provably embeddable.
+        return None
+    role = _sql_literal(login_role)
+    # Newlines around the body: a trailing ``-- comment`` must not swallow the
+    # closing parenthesis.
+    return (
+        "SELECT * FROM (\n"
+        f"{body}\n"
+        ") _matrx_guarded_read WHERE CASE WHEN current_user = "
+        f"{role} AND session_user = {role} THEN true "
+        f"ELSE ({_sql_literal(BORROWED_ROLE_SENTINEL)} || current_user)::int > 0 END"
+    )
+
+
+def borrowed_role_from_error(exc: BaseException) -> str | None:
+    """The role named by a fired read guard, or ``None`` for any other error."""
+    match = _SENTINEL_IN_ERROR.search(str(exc))
+    if match is None:
+        return None
+    return match.group(1) or "<unknown>"
+
+
+async def learn_login_role(conn: Any) -> str:
+    """Our own login role, read on a pinned, reset session (once per pool).
+
+    The explicit transaction pins every statement to one server connection, and
+    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():
+        await conn.execute("RESET SESSION AUTHORIZATION")
+        await conn.execute("RESET ROLE")
+        row = await conn.fetchrow("SELECT session_user AS login_, current_user AS current_")
+    login = row["login_"]
+    if not login or row["current_"] != login:
+        raise PoolerRoleContamination(
+            f"could not learn the login role: a reset session still runs as "
+            f"'{row['current_']}' (session user '{login}')"
+        )
+    return str(login)
+
+
+async def repair_guarded_read(
+    conn: Any,
+    *,
+    config_name: str,
+    query: str,
+    args: tuple[Any, ...],
+    statement_timeout: float | None,
+    normalize: Callable[[Any], dict[str, Any]],
+    borrowed_role: str,
+    login_role: str,
+) -> list[dict[str, Any]]:
+    """The read guard fired: scream, then re-read on a pinned, repaired session.
+
+    The guard's raise IS direct observation of a borrowed role on the backend
+    that served the read, so the contamination alarm is emitted unconditionally.
+    The caller gets the true rows (``[]`` when the clean read is empty).
+    """
+    rows, _observed = await _pinned_reread(
+        conn, query=query, args=args, statement_timeout=statement_timeout, normalize=normalize
+    )
+    await emit_contamination(
+        EmptyReadContaminationEvent(
+            config_name=config_name,
+            query=query,
+            contaminated_role=borrowed_role,
+            login_role=login_role,
+            true_row_count=len(rows or []),
+            occurred_at=datetime.now(UTC),
+        )
+    )
+    return rows or []
+
+
 def _single_statement_proof_sql(query: str) -> str | None:
     """The one-statement absence proof for ``query``, or ``None`` if it cannot embed.
 
@@ -306,6 +423,44 @@ async def reprove_empty_read(
     ):
         return None
 
+    rows, observed = await _pinned_reread(
+        conn, query=query, args=args, statement_timeout=statement_timeout, normalize=normalize
+    )
+    if rows is None:
+        return None
+    # Rows may legitimately appear between two READ COMMITTED statements.
+    # guest_executions is the canonical example: concurrent first requests
+    # for one fingerprint race a lookup against creation. Empty -> non-empty
+    # is reconciliation, not proof of pool contamination. Only the captured
+    # before/after identity change can put this class in the repair queue.
+    if observed is not None:
+        await emit_contamination(
+            EmptyReadContaminationEvent(
+                config_name=config_name,
+                query=query,
+                contaminated_role=observed[0],
+                login_role=observed[1],
+                true_row_count=len(rows),
+                occurred_at=datetime.now(UTC),
+            )
+        )
+    return rows
+
+
+async def _pinned_reread(
+    conn: Any,
+    *,
+    query: str,
+    args: tuple[Any, ...],
+    statement_timeout: float | None,
+    normalize: Callable[[Any], dict[str, Any]],
+) -> tuple[list[dict[str, Any]] | None, tuple[str, str] | None]:
+    """Re-read on ONE server connection after resetting both identities.
+
+    Returns ``(rows or None when empty, (borrowed, login) when the reset was seen
+    to change the identity else None)``. Raises ``PoolerRoleContamination`` when
+    no attempt lands on a clean session.
+    """
     last_role: tuple[str, str] | None = None
     for _ in range(REPROVE_ATTEMPTS):
         async with conn.transaction():
@@ -325,29 +480,14 @@ async def reprove_empty_read(
                 last_role = (current, login)
                 continue
             rows = await conn.fetch(query, *args, timeout=statement_timeout)
-            if not rows:
-                return None
-            true_rows = [normalize(r) for r in rows]
-
-            observed_contamination = (before_current, before_session) != (current, login)
-
-        # Rows may legitimately appear between two READ COMMITTED statements.
-        # guest_executions is the canonical example: concurrent first requests
-        # for one fingerprint race a lookup against creation. Empty -> non-empty
-        # is reconciliation, not proof of pool contamination. Only the captured
-        # before/after identity change can put this class in the repair queue.
-        if observed_contamination:
-            await emit_contamination(
-                EmptyReadContaminationEvent(
-                    config_name=config_name,
-                    query=query,
-                    contaminated_role=before_current,
-                    login_role=login,
-                    true_row_count=len(true_rows),
-                    occurred_at=datetime.now(UTC),
-                )
+            observed = (
+                (before_current, login)
+                if (before_current, before_session) != (current, login)
+                else None
             )
-        return true_rows
+            if not rows:
+                return None, observed
+            return [normalize(r) for r in rows], observed
 
     current, login = last_role if last_role is not None else ("<unknown>", "<unknown>")
     raise PoolerRoleContamination(
@@ -358,6 +498,7 @@ async def reprove_empty_read(
 
 
 __all__ = [
+    "BORROWED_ROLE_SENTINEL",
     "ContaminationSink",
     "EmptyReadContaminationEvent",
     "PoolerRoleContamination",
@@ -365,8 +506,12 @@ __all__ = [
     "SessionRoleChangeRefused",
     "VERIFY_EMPTY_READS",
     "assert_no_session_role_change",
+    "borrowed_role_from_error",
     "emit_contamination",
+    "guarded_read_sql",
+    "learn_login_role",
     "register_contamination_sink",
+    "repair_guarded_read",
     "reprove_empty_read",
     "reset_contamination_sinks",
 ]

{matrx_orm-3.1.241 → matrx_orm-3.1.243}/matrx_orm/query/executor.py

@@ -1722,7 +1722,7 @@ class QueryExecutor:
         # it here and re-raising the BASE class downgraded every one of them to a
         # generic DatabaseError, so a caller could no longer tell "permission
         # denied" from "a child row still references this" — and `str(e)` folded
-        # the original's ANSI-coloured multi-line block into a message. Found by
+        # the original's ANSI-colored multi-line block into a message. Found by
         # `scripts/_verify_batch_access_model.py`, whose whole job is asserting a
         # user's DELETE is refused for the RIGHT reason: `except
         # PermissionDeniedError` silently missed it and the probe reported the

{matrx_orm-3.1.241 → matrx_orm-3.1.243}/matrx_orm/session/fallback.py

@@ -742,11 +742,15 @@ async def record_error(
     admitted, folded = _storm_admit(kind, resolved_error_type, route)
     if not admitted:
         # Counted, never silent: the next admitted row for this signature
-        # carries the total; the stdout line keeps each one greppable.
+        # carries the total. ONE stdout line per window (the first fold) — a line per
+        # folded row re-created the storm in ops.app_log (1,044 lines in 6 h, DB lane C
+        # 2026-10-21), which is the volume this budget exists to stop.
+        if folded != 1:
+            return
         vcprint(
             f"[matrx_orm.session] storm: {kind}/{resolved_error_type} on {route or '-'} "
-            f"({folded} suppressed this {STORM_WINDOW_SECONDS:.0f}s window after "
-            f"{STORM_ROW_BUDGET} rows) — folded into the next captured row, not filed",
+            f"(budget of {STORM_ROW_BUDGET} rows spent; further captures this "
+            f"{STORM_WINDOW_SECONDS:.0f}s window are counted and folded into the next captured row, not filed)",
             color="yellow",
         )
         return

{matrx_orm-3.1.241 → matrx_orm-3.1.243}/matrx_orm/session/lifecycle.py

@@ -416,7 +416,8 @@ def _should_emit_stuck_rows_alert(
 
 def _build_select_query(cfg: WatchedLifecycleConfig, limit: int) -> tuple[str, list[Any]]:
     params: list[Any] = []
-    predicate_sql = cfg.predicate.as_sql(params)
+    # The watched table is the predicate's outer table, so an Exists(... OuterRef(...)) can name it.
+    predicate_sql = cfg.predicate.as_sql(params, current_table=f"{cfg.schema}.{cfg.table}")
     params.append(cfg.max_age_secs)
     diagnostics = "".join(
         f", {col} AS diagnostic_{index}"
@@ -524,7 +525,8 @@ async def _transition_stuck_row(
     if not set_clauses:
         return False
 
-    predicate_sql = cfg.predicate.as_sql(params)
+    # The watched table is the predicate's outer table, so an Exists(... OuterRef(...)) can name it.
+    predicate_sql = cfg.predicate.as_sql(params, current_table=f"{cfg.schema}.{cfg.table}")
     params.append(pk_value)
     pk_param = len(params)
     params.append(cfg.max_age_secs)

{matrx_orm-3.1.241 → matrx_orm-3.1.243}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.241"
+version = "3.1.243"
 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.80",
+    "matrx-utils>=2.0.83",
     "pyyaml>=6.0.3",
     "python-dotenv>=1.0",
     "cryptography>=43.0",

matrx_orm-3.1.243/tests/level1/test_guarded_read_never_reruns_empty.py

@@ -0,0 +1,142 @@
+"""Forcing function: an empty read is proven by the read itself, never re-run.
+
+2026-10-21 census: re-proving every zero-row read was 3.5M extra statements in
+5.7 h on the live database (the operation-stream reaper's empty lookups alone
+were 2.48M). The fix moves the role proof INTO the read (``guarded_read_sql``),
+so these tests fail if any path goes back to a second statement per empty
+result — and fail just as hard if a borrowed role could slip through silently.
+"""
+
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from typing import Any
+
+import asyncpg
+import pytest
+
+from matrx_orm.core.async_db_manager import AsyncDatabaseManager
+from matrx_orm.core.pooler_role import (
+    BORROWED_ROLE_SENTINEL,
+    EmptyReadContaminationEvent,
+    guarded_read_sql,
+    register_contamination_sink,
+    reset_contamination_sinks,
+)
+
+_GUARDED_PREFIX = "SELECT * FROM (\n"
+
+
+class _Tx:
+    def __init__(self, conn: _Conn) -> None:
+        self._conn = conn
+
+    async def __aenter__(self) -> None:
+        self._conn.log.append("BEGIN")
+
+    async def __aexit__(self, *_exc: object) -> bool:
+        self._conn.log.append("COMMIT")
+        return False
+
+
+class _Conn:
+    """A pooled connection whose backend may be wearing a borrowed role."""
+
+    def __init__(self, *, rows: list[dict[str, Any]], borrowed: str | None = None) -> None:
+        self.rows = rows
+        self.borrowed = borrowed
+        self.log: list[str] = []
+
+    def transaction(self) -> _Tx:
+        return _Tx(self)
+
+    async def execute(self, sql: str, *_a: object, **_k: object) -> None:
+        self.log.append(sql)
+
+    async def fetchrow(self, sql: str, *_a: object, **_k: object) -> dict[str, Any]:
+        self.log.append(sql)
+        if "login_" in sql:
+            return {"login_": "postgres", "current_": "postgres"}
+        return {"current_user": "postgres", "session_user": "postgres"}
+
+    async def fetch(self, sql: str, *_a: object, **_k: object) -> list[dict[str, Any]]:
+        self.log.append(sql)
+        if sql.startswith(_GUARDED_PREFIX):
+            if self.borrowed is not None:
+                # What Postgres raises when the guard's one-time filter fires.
+                raise asyncpg.exceptions.InvalidTextRepresentationError(
+                    f'invalid input syntax for type integer: "{BORROWED_ROLE_SENTINEL}{self.borrowed}"'
+                )
+            return list(self.rows)
+        # The unguarded text only runs inside the pinned repair transaction.
+        return list(self.rows)
+
+
+def _install(monkeypatch: pytest.MonkeyPatch, conn: _Conn) -> None:
+    @asynccontextmanager
+    async def checkout(_cls: object, _config_name: str, _timeout: object):
+        yield conn
+
+    monkeypatch.setattr(AsyncDatabaseManager, "get_connection", classmethod(checkout))
+    monkeypatch.setattr(
+        AsyncDatabaseManager, "_verifies_empty_reads", classmethod(lambda _c, _n: True)
+    )
+    monkeypatch.setattr(AsyncDatabaseManager, "_login_roles", {})
+
+
+_QUERY = "SELECT id FROM runtime.global_execution WHERE request_id = $1"
+
+
+@pytest.mark.asyncio
+async def test_empty_read_on_transaction_pool_is_one_guarded_statement(monkeypatch) -> None:
+    conn = _Conn(rows=[])
+    _install(monkeypatch, conn)
+
+    for _ in range(5):
+        rows = await AsyncDatabaseManager.execute_query("test", _QUERY, "00000000")
+        assert rows == []
+
+    reads = [s for s in conn.log if s.startswith("SELECT") and "runtime.global_execution" in s]
+    # Five empty reads = five statements, each carrying its own role proof.
+    assert len(reads) == 5, conn.log
+    assert all(s.startswith(_GUARDED_PREFIX) for s in reads), reads
+    # The login role is learned once per pool, not once per read.
+    assert conn.log.count("RESET ROLE") == 1, conn.log
+    assert not any("EXISTS (" in s for s in conn.log), "empty read was re-proved"
+
+
+@pytest.mark.asyncio
+async def test_a_borrowed_role_never_comes_back_empty(monkeypatch) -> None:
+    reset_contamination_sinks()
+    events: list[EmptyReadContaminationEvent] = []
+    register_contamination_sink(events.append)
+    monkeypatch.setattr("matrx_orm.session.fallback.record_error", _noop_record, raising=False)
+
+    conn = _Conn(rows=[{"id": "x1"}], borrowed="authenticated")
+    _install(monkeypatch, conn)
+
+    rows = await AsyncDatabaseManager.execute_query("test", _QUERY, "00000000")
+
+    assert rows == [{"id": "x1"}]
+    assert len(events) == 1
+    assert events[0].contaminated_role == "authenticated"
+    assert events[0].login_role == "postgres"
+    reset_contamination_sinks()
+
+
+async def _noop_record(*_a: object, **_k: object) -> None:
+    return None
+
+
+def test_guard_wraps_single_reads_and_refuses_the_rest() -> None:
+    wrapped = guarded_read_sql("SELECT 1 -- trailing comment", "postgres")
+    assert wrapped is not None
+    assert wrapped.startswith(_GUARDED_PREFIX)
+    # A trailing line comment must not swallow the closing parenthesis.
+    assert "-- trailing comment\n)" in wrapped
+    assert "current_user = 'postgres' AND session_user = 'postgres'" in wrapped
+    assert guarded_read_sql("WITH t AS (SELECT 1) SELECT * FROM t;", "postgres") is not None
+    assert guarded_read_sql("SELECT 1; SELECT 2", "postgres") is None
+    assert guarded_read_sql("SHOW search_path", "postgres") is None
+    assert guarded_read_sql("SELECT 1", None) is None
+    assert "'o''brien'" in (guarded_read_sql("SELECT 1", "o'brien") or "")

{matrx_orm-3.1.241 → matrx_orm-3.1.243}/tests/level1/test_read_connection_retry.py

@@ -56,9 +56,16 @@ async def test_read_retries_disconnect_masked_by_reproof_transaction(monkeypatch
             )
 
     class ClosedConnection:
+        # The pinned transaction is now the once-per-pool login-role read
+        # (pooler_role.learn_login_role) rather than a per-empty-read re-proof.
         async def fetch(self, *_args, **_kwargs):
             return []
 
+        async def execute(self, *_args, **_kwargs):
+            raise asyncpg.exceptions.ConnectionDoesNotExistError(
+                "connection was closed in the middle of operation"
+            )
+
         async def fetchrow(self, *_args, **_kwargs):
             raise asyncpg.exceptions.ConnectionDoesNotExistError(
                 "connection was closed in the middle of operation"
@@ -78,6 +85,22 @@ async def test_read_retries_disconnect_masked_by_reproof_transaction(monkeypatch
         async def fetch(self, *_args, **_kwargs):
             return [{"value": 1}]
 
+        async def execute(self, *_args, **_kwargs):
+            return None
+
+        async def fetchrow(self, *_args, **_kwargs):
+            return {"login_": "postgres", "current_": "postgres"}
+
+        def transaction(self):
+            class _Tx:
+                async def __aenter__(self):
+                    return self
+
+                async def __aexit__(self, *_a):
+                    return False
+
+            return _Tx()
+
         def is_closed(self) -> bool:
             return False
 
@@ -89,6 +112,7 @@ async def test_read_retries_disconnect_masked_by_reproof_transaction(monkeypatch
 
     monkeypatch.setattr(AsyncDatabaseManager, "get_connection", classmethod(checkout))
     monkeypatch.setattr(AsyncDatabaseManager, "_verifies_empty_reads", lambda *_: True)
+    monkeypatch.setattr(AsyncDatabaseManager, "_login_roles", {})
     monkeypatch.setattr(
         "matrx_orm.core.async_db_manager.READ_TIMEOUT_RETRY_BACKOFF", 0
     )