matrx-orm 3.1.199__tar.gz → 3.1.201__tar.gz

{matrx_orm-3.1.199 → matrx_orm-3.1.201}/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+- **Fix: the shared-lock sampler no longer leaves its timeouts on a pooled backend.**
+  `pytest_lock_guard` sent session-level `set lock_timeout` / `set statement_timeout`
+  through the transaction pooler, where they stay on the backend for the next client
+  (both found leaked on the clone's pool, 2026-10-01). It now uses `SET LOCAL` inside
+  each sample's own transaction.
 - **Fix: a driver timeout longer than the server's statement ceiling screams.**
   `call_function` / `call_function_as` / `execute_query` read the connection's
   effective `statement_timeout` and log one WARNING per call site when the

{matrx_orm-3.1.199 → matrx_orm-3.1.201}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matrx-orm
-Version: 3.1.199
+Version: 3.1.201
 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

{matrx_orm-3.1.199 → matrx_orm-3.1.201}/matrx_orm/__init__.py

@@ -298,6 +298,7 @@ from .core.transaction import (
     advisory_unlock,
     advisory_xact_lock,
     set_local_guc,
+    set_local_gucs,
     transaction,
     try_advisory_lock,
     try_advisory_xact_lock,
@@ -697,6 +698,7 @@ __all__ = [
     "transaction",
     "acquire_connection",
     "set_local_guc",
+    "set_local_gucs",
     "SessionContextProvider",
     "ACTOR_AGENT_GUC",
     "ACTOR_SYSTEM_GUC",

{matrx_orm-3.1.199 → matrx_orm-3.1.201}/matrx_orm/core/FEATURE.md

@@ -261,6 +261,55 @@ 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`.
+
+**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
+(`transaction(opening_gucs=…)`; `rls_session` passes claims + timeouts + role,
+role LAST) in ONE `set_config` statement; `set_local_gucs` does the same inside a
+transaction. A transaction-mode pool releases connections with no reset statement
+(`_transaction_pool_release`); a session-mode pool keeps asyncpg's full reset.
+Measured on one agent launch against the clone through the pooler (170 ms per round
+trip from a laptop): 435 → ~200 round trips. Pinned by
+`tests/level1/test_transaction_gucs_one_round_trip.py`,
+`tests/level1/test_transaction_pool_release_sends_nothing.py` and
+`tests/level1/test_rls_session_scope.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
+`SET SESSION CHARACTERISTICS AS TRANSACTION READ ONLY`) sent outside a transaction — the
+shape of an ad-hoc "read-only production" helper — leaves that backend read-only for
+everyone (2026-10-01 incident: dispatchers, workflow claims, request audit, chat writes;
+recurring since 2026-09-12). A transaction-mode pool's connections are
+`ReadWriteConnection` (`read_write.py`): every top-level BEGIN naming no access mode is
+sent as `... READ WRITE` (zero extra round trips), and an autocommit statement refused as
+read-only re-runs once inside `BEGIN READ WRITE` with a WARNING naming the cause. An
+explicit `READ ONLY` is kept; the session is never rewritten. Read-only work through the
+pooler belongs in `BEGIN READ ONLY`, never a session SET. Pinned by
+`tests/test_a_read_only_backend_never_refuses_our_writes.py` (loopback `ISOLATED_PG17_DSN`)
+and `tests/level1/test_read_write_declared.py`.
+
+**A backend handed over inside another client's transaction never takes our writes.** The
+second shape of the same incident: a probe sent `begin read only; …; rollback;` through the
+pooler, an error or timeout skipped the `rollback`, and the pooler handed the open READ ONLY
+transaction to the server. The pooler answers our handshake "idle", so asyncpg learns of it
+only from the reply. A statement that comes back inside a transaction this connection never
+opened is the stranger's: rolled back, logged at ERROR with the remedy, re-run once in our own
+`BEGIN READ WRITE … COMMIT` (the rollback undid it, so exactly once). A top-level BEGIN answered
+with 25001 is the same: rolled back and begun again; a second stranger raises
+`InheritedTransactionError` by name. Pinned by
+`tests/test_a_backend_handed_over_mid_transaction_never_takes_our_writes.py`, which runs an
+in-process transaction pooler that never resets its one server connection (loopback
+`ISOLATED_PG17_DSN`; 4 of 5 fail on the code before it).
+
 **The destructive live proof is loopback-only.**
 `tests/live_pooler_role.py::assert_isolated_pooler_target` runs before DSN
 construction or connection and refuses every shared or remote database. The proof
@@ -339,6 +388,9 @@ can never disagree about who the blocker was.
 Verified against the live database: 2026-08-21.
 
 ## Change log
+- 2026-10-01: `ReadWriteConnection` rolls back a stranger's open transaction it was handed (statement reply or 25001 on BEGIN), re-runs our statement in its own transaction, and names a repeat `InheritedTransactionError`.
+- 2026-10-01: `ReadWriteConnection` for transaction-mode pools — every BEGIN declares READ WRITE and a read-only-refused autocommit statement re-runs once in one; a pooled backend another client left read-only at session level no longer fails the platform's writes.
+- 2026-09-30: Fewer round trips per request (agent-launch latency, lane deep): one-statement proof of a clean empty read; ceilings + declared context + `rls_session` settings in ONE BEGIN-time `set_config` statement (`transaction(opening_gucs=)`, `set_local_gucs`, `emit_local_gucs`); transaction-mode pools release with no reset statement. 435 → ~200 round trips on a flashcard launch.
 - 2026-09-30: `statement_ceiling.py` — a driver timeout above the server's statement ceiling is logged once per call site; `SERVER_CEILING` sentinel. ~19 callers passed 60-600 s under the 30 s `postgres` ceiling (the nightly keyword classifier was cancelled at 30 s for eight days).
 - 2026-09-12 (later): ONE retry mechanism. Two independent lock-retry
   implementations for the same class landed hours apart — a `LockContentionError`

{matrx_orm-3.1.199 → matrx_orm-3.1.201}/matrx_orm/core/async_db_manager.py

@@ -25,6 +25,7 @@ from matrx_orm.core.pooler_role import (
     reprove_empty_read,
 )
 from matrx_orm.core.statement_ceiling import resolve_driver_timeout
+from matrx_orm.core.read_write import ReadWriteConnection
 from matrx_orm.core.tls import resolve_asyncpg_ssl
 from matrx_orm.exceptions import (
     AdapterError,
@@ -421,6 +422,25 @@ class ConnectionIdentity:
         return f"{cluster}/{self.database}"
 
 
+async def _transaction_pool_release(_conn: Any) -> None:
+    """Release a transaction-pooler connection with NO session reset statement.
+
+    asyncpg's default release runs ``pg_advisory_unlock_all(); CLOSE ALL;
+    UNLISTEN *; RESET ALL`` — one round trip on EVERY release. Behind a
+    transaction-mode pooler (Supavisor / PgBouncer, port 6543) that statement
+    lands on whichever server connection the pooler picks, so it cannot reset
+    anything the next statement from this client will see: there is no session
+    state of ours to reset (every GUC here is ``SET LOCAL``, LISTEN rides its own
+    session connection, cursors die with their transaction). It cost ~88 of the
+    ~435 round trips of one agent launch (measured 2026-09-30, ~15 s at a
+    laptop's 170 ms). asyncpg still rolls back an open transaction before this
+    hook (``Connection._reset``), and a session-mode pool keeps the full default
+    reset. ``RESET ALL`` never reset a borrowed ROLE either (``role`` is
+    ``GUC_NO_RESET_ALL``) — that defence is ``pooler_role``.
+    """
+    return None
+
+
 class AsyncDatabaseManager:
     _instance = None
     _pools = {}
@@ -669,6 +689,20 @@ class AsyncDatabaseManager:
                             server_settings=server_settings,
                             init=_init_connection_default,
                             timeout=connect_timeout,
+                            reset=(
+                                _transaction_pool_release
+                                if effective_mode == "transaction"
+                                else None
+                            ),
+                            # A transaction pooler hands us server connections other
+                            # clients may have left read-only at SESSION level; every
+                            # BEGIN declares READ WRITE and a refused autocommit
+                            # statement re-runs once in one (core/read_write.py).
+                            connection_class=(
+                                ReadWriteConnection
+                                if effective_mode == "transaction"
+                                else asyncpg.Connection
+                            ),
                         )
                         try:
                             async with asyncio.timeout(create_timeout):

{matrx_orm-3.1.199 → matrx_orm-3.1.201}/matrx_orm/core/pooler_role.py

@@ -223,6 +223,61 @@ async def emit_contamination(event: EmptyReadContaminationEvent) -> None:
             logger.exception("[pooler-role] contamination sink raised")
 
 
+def _single_statement_proof_sql(query: str) -> str | None:
+    """The one-statement absence proof for ``query``, or ``None`` if it cannot embed.
+
+    One statement executes on ONE server connection, so the identity columns and
+    the ``EXISTS`` are evaluated by the same backend under the same role. The
+    login column comes from ``pg_stat_activity`` (the role the backend
+    authenticated as), which ``SET SESSION AUTHORIZATION`` does not change — so a
+    session-authorization swap, where ``current_user`` and ``session_user`` agree
+    on the WRONG identity, still fails the proof.
+    """
+    body = query.strip().rstrip(";").strip()
+    if not body or ";" in body:
+        return None
+    return (
+        "SELECT current_user AS current_user_, session_user AS session_user_, "
+        "(SELECT usename FROM pg_catalog.pg_stat_activity WHERE pid = pg_backend_pid()) "
+        "AS login_user_, "
+        f"EXISTS ({body}) AS has_rows_"
+    )
+
+
+async def prove_empty_in_one_statement(
+    conn: Any,
+    *,
+    query: str,
+    args: tuple[Any, ...],
+    statement_timeout: float | None,
+) -> bool:
+    """True only when ONE statement proves the read is genuinely empty.
+
+    The fast path of Layer 2. A clean session (``current_user`` = ``session_user``
+    = the backend's login role) that finds no row IS the proof the full re-proof
+    would reach — in one round trip instead of seven (BEGIN, two identity reads,
+    two resets, the re-read, COMMIT). Every other outcome — a borrowed role, a
+    session-authorization swap, rows that appeared since, a query that cannot be
+    embedded, any error — returns False and the full repairing re-proof runs, so
+    no contaminated or unprovable read ever short-circuits here.
+    """
+    sql = _single_statement_proof_sql(query)
+    if sql is None:
+        return False
+    try:
+        row = await conn.fetchrow(sql, *args, timeout=statement_timeout)
+    except Exception:  # noqa: BLE001 — any failure means "not proven"; the full path decides
+        return False
+    if row is None:
+        return False
+    current = row["current_user_"]
+    session = row["session_user_"]
+    login = row["login_user_"]
+    if not current or current != session or current != login:
+        return False
+    return row["has_rows_"] is False
+
+
 async def reprove_empty_read(
     conn: Any,
     *,
@@ -238,10 +293,19 @@ async def reprove_empty_read(
     the read was genuinely empty. Raises ``PoolerRoleContamination`` when a clean
     session cannot be obtained at all — an unprovable absence is never a result.
 
+    The common case — a genuinely empty read on a clean pool — is settled by
+    ``prove_empty_in_one_statement`` in one round trip. Anything it cannot prove
+    falls through to the pinned, repairing re-proof below.
+
     ``conn`` must be a connection not currently inside a transaction; the explicit
     transaction opened here is what pins every statement below to ONE server
     connection, which is the only thing that makes ``RESET ROLE`` meaningful.
     """
+    if await prove_empty_in_one_statement(
+        conn, query=query, args=args, statement_timeout=statement_timeout
+    ):
+        return None
+
     last_role: tuple[str, str] | None = None
     for _ in range(REPROVE_ATTEMPTS):
         async with conn.transaction():

matrx_orm-3.1.201/matrx_orm/core/read_write.py

@@ -0,0 +1,221 @@
+"""A pooled backend another client left read-only never refuses our writes.
+
+A transaction-mode pooler (Supavisor / PgBouncer, port 6543) shares its server
+connections between EVERY client that logs in as the same user, and never resets
+one between clients. A client that runs a session-level read-only setting outside a
+transaction — ``SET default_transaction_read_only = on``,
+``SET SESSION CHARACTERISTICS AS TRANSACTION READ ONLY`` (the shape of an ad-hoc
+"read-only production" helper) — leaves it on whichever server connection the pooler
+handed it. Every later transaction routed there starts read-only, and every write
+fails with ``cannot execute ... in a read-only transaction`` while the database is
+writable. (2026-10-01: SMS and notification dispatchers, workflow claims, the request
+audit and chat writes; recurring since at least 2026-09-12. Proven live: one of 21
+pooled backends carried ``default_transaction_read_only = on``, ``source = session``.)
+
+``ReadWriteConnection`` is the connection class of every transaction-mode pool:
+
+* every top-level ``BEGIN`` that names no access mode is sent as ``BEGIN ... READ
+  WRITE`` — the ORM's own ``transaction()`` and any raw ``conn.transaction()``
+  alike, at no extra round trip. An explicit ``READ ONLY`` is kept.
+* an AUTOCOMMIT statement the backend refuses as read-only (SQLSTATE 25006) is re-run
+  once inside one explicit ``BEGIN READ WRITE`` transaction, and the event is logged
+  with its remedy. The refusal proves the statement never ran: Postgres checks the
+  access mode before a statement modifies anything, and an implicit transaction
+  rolls back whole.
+
+THE SECOND SHAPE — a server connection handed over INSIDE another client's transaction
+(2026-10-01: live probes sent ``begin read only; …; rollback;`` as one string through the
+pooler; an error or timeout skipped the ``rollback`` and the open READ ONLY transaction went to
+the platform server). A transaction pooler answers our handshake with "idle" itself, so asyncpg
+only learns of the stranger's transaction from the reply to our next statement:
+
+* a statement that comes back inside a transaction this connection never opened (asyncpg's
+  ``_top_xact`` unset, no BEGIN of ours open) ran inside a STRANGER's transaction: that
+  transaction is rolled back, logged at ERROR with its remedy, and the statement re-runs once in
+  our own ``BEGIN READ WRITE … COMMIT``. The rollback undid whatever the statement did, so the
+  re-run is exactly once.
+* a top-level ``BEGIN`` the server answers with SQLSTATE 25001 ("there is already a transaction
+  in progress" / "read-write mode must be set before any query") is the same stranger: rolled
+  back, begun again once; a second stranger raises ``InheritedTransactionError`` by name —
+  never a bare 25006 three statements later.
+
+It never touches the session it was handed — the poison stays visible to whoever
+investigates (``SHOW default_transaction_read_only``) and the guard stays per
+transaction. Session-mode pools keep the plain asyncpg connection: their server
+connection is ours alone and asyncpg's release reset clears it.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+import asyncpg
+
+logger = logging.getLogger(__name__)
+
+# One statement that opens a top-level transaction: BEGIN / BEGIN WORK / BEGIN
+# TRANSACTION / START TRANSACTION, optionally with modes and one trailing ';'.
+_BEGIN_STATEMENT = re.compile(
+    r"^\s*(?:BEGIN|START\s+TRANSACTION)\b(?P<modes>[^;]*?)\s*;?\s*$",
+    re.IGNORECASE | re.DOTALL,
+)
+_ACCESS_MODE = re.compile(r"\bREAD\s+(?:ONLY|WRITE)\b", re.IGNORECASE)
+# A statement that ends the top-level transaction (not ROLLBACK TO / RELEASE a savepoint).
+_END_STATEMENT = re.compile(
+    r"^\s*(?:COMMIT|END|ABORT|ROLLBACK)\b(?!\s+(?:TO|PREPARED)\b)(?!\s+(?:WORK|TRANSACTION)\s+TO\b)",
+    re.IGNORECASE,
+)
+_ACTIVE_SQL_TRANSACTION = "25001"
+
+
+def declare_read_write(query: str) -> str:
+    """``query`` with ``READ WRITE`` declared when it is a BEGIN naming no access mode.
+
+    Anything else — a savepoint, a multi-statement script, a BEGIN that already says
+    ``READ ONLY`` or ``READ WRITE`` — is returned unchanged.
+    """
+    match = _BEGIN_STATEMENT.match(query)
+    if match is None or _ACCESS_MODE.search(match.group("modes")):
+        return query
+    return query.strip().rstrip(";").rstrip() + " READ WRITE"
+
+
+_REFUSED_REMEDY = (
+    "[matrx_orm] A pooled server connection refused an autocommit statement as "
+    "read-only: another client of the transaction pooler left a SESSION-level "
+    "read-only default on it (SET default_transaction_read_only / SET SESSION "
+    "CHARACTERISTICS AS TRANSACTION READ ONLY sent outside a transaction). The "
+    "statement never ran and was re-run inside BEGIN READ WRITE. Remedy: find the "
+    "client sending that SET through the pooler — read-only work belongs in "
+    "BEGIN READ ONLY, one transaction at a time. Statement: %s"
+)
+
+
+_STRANGER_REMEDY = (
+    "[matrx_orm] The pooler handed this connection a server connection still inside "
+    "another client's open transaction (a client of the transaction pooler left without "
+    "COMMIT/ROLLBACK, e.g. a 'begin read only; ...; rollback;' probe that errored or timed "
+    "out). That transaction was rolled back and our statement re-runs in its own "
+    "transaction. Remedy: find the client — probes belong on a DIRECT connection (:5432) "
+    "with ROLLBACK in a finally. Statement: %s"
+)
+
+
+class InheritedTransactionError(RuntimeError):
+    """Every server connection the pooler offered was inside another client's transaction."""
+
+
+class ReadWriteConnection(asyncpg.Connection):  # type: ignore[misc]
+    """The connection class of a transaction-mode pool (see module docstring)."""
+
+    _matrx_own_xact = False  # a top-level BEGIN of ours is open
+    _matrx_saw_25001 = False  # the server warned "already a transaction in progress"
+
+    def _process_log_message(self, fields: Any, last_query: Any) -> None:
+        if fields.get("C") == _ACTIVE_SQL_TRANSACTION:
+            self._matrx_saw_25001 = True
+        super()._process_log_message(fields, last_query)
+
+    async def _reset(self) -> None:
+        self._matrx_own_xact = False
+        await super()._reset()
+
+    def _in_strangers_transaction(self) -> bool:
+        return self.is_in_transaction() and self._top_xact is None and not self._matrx_own_xact
+
+    async def _drop_strangers_transaction(self, query: str) -> None:
+        logger.error(_STRANGER_REMEDY, " ".join(str(query).split())[:160])
+        self._matrx_own_xact = False
+        await asyncpg.Connection.execute(self, "ROLLBACK")
+
+    async def _begin(self, query: str) -> str:
+        """A top-level BEGIN that never silently joins a stranger's transaction."""
+        if self._in_strangers_transaction():
+            await self._drop_strangers_transaction(query)
+        for _ in range(2):
+            self._matrx_saw_25001 = False
+            try:
+                result = await asyncpg.Connection.execute(self, query)
+            except asyncpg.exceptions.ActiveSQLTransactionError:
+                pass
+            else:
+                if not self._matrx_saw_25001:
+                    self._matrx_own_xact = True
+                    return result
+            await self._drop_strangers_transaction(query)
+        raise InheritedTransactionError(
+            "Two server connections in a row were inside another client's open transaction; "
+            "nothing was written. A client of the transaction pooler is leaving transactions "
+            "open (see matrx_orm/core/read_write.py)."
+        )
+
+    async def _in_own_transaction(
+        self, call: Callable[..., Awaitable[Any]], query: str, args: tuple[Any, ...], kwargs: dict[str, Any]
+    ) -> Any:
+        await self._begin("BEGIN READ WRITE")
+        try:
+            result = await call(query, *args, **kwargs)
+        except BaseException:
+            self._matrx_own_xact = False
+            try:
+                await asyncpg.Connection.execute(self, "ROLLBACK")
+            except Exception:  # noqa: BLE001 — the pool's release rolls back what this cannot
+                pass
+            raise
+        self._matrx_own_xact = False
+        await asyncpg.Connection.execute(self, "COMMIT")
+        return result
+
+    async def _healed(
+        self, call: Callable[..., Awaitable[Any]], query: str, args: tuple[Any, ...], kwargs: dict[str, Any]
+    ) -> Any:
+        if self._in_strangers_transaction():
+            await self._drop_strangers_transaction(query)
+        if self.is_in_transaction():
+            result = await call(query, *args, **kwargs)
+            if self._top_xact is None and _END_STATEMENT.match(str(query)):
+                self._matrx_own_xact = False
+            return result
+        try:
+            result = await call(query, *args, **kwargs)
+        except asyncpg.exceptions.ReadOnlySQLTransactionError:
+            if self.is_in_transaction():
+                await self._drop_strangers_transaction(query)
+            else:
+                logger.warning(_REFUSED_REMEDY, " ".join(str(query).split())[:160])
+        except Exception:
+            if not self._in_strangers_transaction():
+                raise
+            await self._drop_strangers_transaction(query)
+        else:
+            if not self._in_strangers_transaction():
+                return result
+            # The reply came from inside a stranger's transaction; rolling it back undid it.
+            await self._drop_strangers_transaction(query)
+        return await self._in_own_transaction(call, query, args, kwargs)
+
+    async def execute(self, query: str, *args: Any, **kwargs: Any) -> str:
+        if not args:
+            declared = declare_read_write(query)
+            if _BEGIN_STATEMENT.match(declared) and not (self.is_in_transaction() and not self._in_strangers_transaction()):
+                return await self._begin(declared)
+            query = declared
+        return await self._healed(super().execute, query, args, kwargs)
+
+    async def fetch(self, query: str, *args: Any, **kwargs: Any) -> list[Any]:
+        return await self._healed(super().fetch, query, args, kwargs)
+
+    async def fetchrow(self, query: str, *args: Any, **kwargs: Any) -> Any:
+        return await self._healed(super().fetchrow, query, args, kwargs)
+
+    async def fetchval(self, query: str, *args: Any, **kwargs: Any) -> Any:
+        return await self._healed(super().fetchval, query, args, kwargs)
+
+    async def executemany(self, command: str, args: Any, **kwargs: Any) -> None:
+        return await self._healed(super().executemany, command, (args,), kwargs)
+
+
+__all__ = ["InheritedTransactionError", "ReadWriteConnection", "declare_read_write"]

{matrx_orm-3.1.199 → matrx_orm-3.1.201}/matrx_orm/core/rls_session.py

@@ -115,43 +115,34 @@ async def rls_session(
 
     claims_json = json.dumps(claims, separators=(",", ":"))
 
-    async with transaction(database=database):
+    # Set the verified claims FIRST (while still the privileged role), then drop to
+    # the restricted role. Order mirrors PostgREST; all of them are transaction-local
+    # (`set_config(..., true)` IS `SET LOCAL`) and survive the role switch within the
+    # same transaction.
+    #
+    # ONE ROUND TRIP FOR THE WHOLE OPENING. 2026-09-19 folded these four settings
+    # into one statement (0.437 s -> 0.192 s against the main database); 2026-09-30
+    # folded that statement into the BEGIN-time one that already carries the
+    # ceilings and the declared session context (`transaction(opening_gucs=...)`),
+    # saving one more round trip on every RLS session. `role` stays LAST — the
+    # opening statement always emits it last — so the claims land before the role
+    # drops, and the role still changes here and nowhere else.
+    gucs: dict[str, str] = {"request.jwt.claims": claims_json}
+    if statement_timeout_ms is not None:
+        gucs["statement_timeout"] = str(int(statement_timeout_ms))
+    if lock_timeout_ms is not None:
+        gucs["lock_timeout"] = str(int(lock_timeout_ms))
+    if idle_in_transaction_timeout_ms is not None:
+        gucs["idle_in_transaction_session_timeout"] = str(int(idle_in_transaction_timeout_ms))
+    gucs["role"] = role
+
+    async with transaction(database=database, opening_gucs=gucs):
         conn = get_active_connection()
         if conn is None:  # pragma: no cover - transaction always sets it on first entry
             raise DatabaseError(
                 message="rls_session: no active connection after opening transaction",
                 details={"role": role},
             )
-        # Set the verified claims FIRST (while still the privileged role), then drop to
-        # the restricted role. Order mirrors PostgREST; all of them are transaction-local
-        # (`set_config(..., true)` IS `SET LOCAL`) and survive the role switch within the
-        # same transaction.
-        #
-        # ONE ROUND TRIP, NOT FOUR. These were four sequential `execute` calls, and a
-        # round trip to a hosted pooler is not free: measured 2026-09-19 against the main
-        # database, the three that always run cost 0.247 + 0.085 + 0.105 = 0.437 s
-        # separately and 0.192 s as one statement — so every RLS session on the platform
-        # paid a quarter of a second to say three things it could say at once. They are
-        # emitted in the SAME ORDER inside one target list, which is the order that
-        # matters: the claims land before the role drops. `SET LOCAL ROLE x` and
-        # `set_config('role', 'x', true)` are the same GUC write, so the role still
-        # changes here and nowhere else, and `role` stays LAST.
-        settings: list[str] = ["set_config('request.jwt.claims', $1, true)"]
-        bound: list[str] = [claims_json]
-        if statement_timeout_ms is not None:
-            bound.append(str(int(statement_timeout_ms)))
-            settings.append(f"set_config('statement_timeout', ${len(bound)}, true)")
-        if lock_timeout_ms is not None:
-            bound.append(str(int(lock_timeout_ms)))
-            settings.append(f"set_config('lock_timeout', ${len(bound)}, true)")
-        if idle_in_transaction_timeout_ms is not None:
-            bound.append(str(int(idle_in_transaction_timeout_ms)))
-            settings.append(
-                f"set_config('idle_in_transaction_session_timeout', ${len(bound)}, true)"
-            )
-        bound.append(role)
-        settings.append(f"set_config('role', ${len(bound)}, true)")
-        await conn.execute("select " + ", ".join(settings), *bound)
         # RLS decides every read in this block, so the process-wide by-id cache
         # (keyed by primary key alone) is bypassed both ways — see
         # ``transaction.in_person_scoped_session``.

{matrx_orm-3.1.199 → matrx_orm-3.1.201}/matrx_orm/core/session_context.py

@@ -87,10 +87,41 @@ def session_context_gucs() -> dict[str, str]:
     return out
 
 
+def local_gucs_statement(gucs: Mapping[str, str]) -> tuple[str, tuple[str, ...]] | None:
+    """ONE statement that sets every GUC in ``gucs`` transaction-locally.
+
+    ``None`` when there is nothing to set. Names are validated like
+    ``set_local_guc`` validates them; values travel as bind parameters.
+    """
+    if not gucs:
+        return None
+    targets: list[str] = []
+    args: list[str] = []
+    for name, value in gucs.items():
+        if not isinstance(name, str) or not _GUC_NAME_RE.match(name):
+            raise ValueError(f"invalid transaction-local GUC name: {name!r}")
+        targets.append(f"set_config(${len(args) + 1}, ${len(args) + 2}, true)")
+        args.extend((name, "" if value is None else str(value)))
+    return "SELECT " + ", ".join(targets), tuple(args)
+
+
+async def emit_local_gucs(connection: Any, gucs: Mapping[str, str]) -> None:
+    """Set every GUC in ``gucs`` on ``connection`` (inside a BEGIN) in ONE round trip.
+
+    One ``set_config`` statement per GUC cost a round trip each on EVERY top-level
+    transaction — three per BEGIN once the actor declaration landed, ~45 per agent
+    launch, ~7.5 s at a laptop's 170 ms to the pooler (measured 2026-09-30).
+    """
+    statement = local_gucs_statement(gucs)
+    if statement is None:
+        return
+    sql, args = statement
+    await connection.execute(sql, *args)
+
+
 async def apply_session_context(connection: Any) -> None:
     """Emit the declared GUCs on ``connection`` (already inside a BEGIN)."""
-    for name, value in session_context_gucs().items():
-        await connection.execute("SELECT set_config($1, $2, true)", name, value)
+    await emit_local_gucs(connection, session_context_gucs())
 
 
 # ---------------------------------------------------------------------------
@@ -256,6 +287,8 @@ __all__ = [
     "ActorTier",
     "SessionContextProvider",
     "apply_session_context",
+    "emit_local_gucs",
+    "local_gucs_statement",
     "configure_session_context",
     "current_actor",
     "current_tier",