matrx-orm 3.1.233__tar.gz → 3.1.235__tar.gz

{matrx_orm-3.1.233 → matrx_orm-3.1.235}/.gitignore

@@ -349,3 +349,9 @@ apps/shared/.kit-*-witness.*/
 .matrx/release-repeats.json.tmp
 .matrx/fixer-ledger.json
 /.config-manifest.json
+
+# Agents' scratch "proof" copies of shared packages — never tracked (they break the npm planner and the frozen lockfile)
+apps/shared/zz-proof-*/
+
+# tsup writes this temp file while it builds a config; never commit it
+tsup.config.bundled_*.mjs

{matrx_orm-3.1.233 → matrx_orm-3.1.235}/PKG-INFO

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

matrx_orm-3.1.235/matrx_orm/core/foreign_session_state.py

@@ -0,0 +1,194 @@
+"""Session state another client left on a shared server connection.
+
+WHY THIS EXISTS. We reach Postgres through Supavisor in TRANSACTION mode: every
+client shares the same pool of server connections, and Supavisor does not reset
+session state between clients. ``pg_dump`` (17.x) begins every run with a
+SESSION-level ``SET restrict_nonsystem_relation_kind = 'view, foreign-table'``.
+A dump pointed at the transaction pooler (port 6543) leaves that setting on
+whichever server connection the ``SET`` landed on, and every later statement of
+ours that touches a view through that connection is refused at parse time::
+
+    55000 ObjectNotInPrerequisiteStateError:
+        access to non-system view "organization_member" is restricted
+
+Measured 2026-10-05 05:49-09:04 UTC: ~50 platform errors (SEO runs list, mandate
+resolution, membership checks, file downloads), each pinned to a few poisoned
+backends that kept failing for minutes.
+
+THE DEFENCE (two halves, both here so they cannot drift apart):
+
+1. Every ORM transaction clears the setting transaction-locally at BEGIN
+   (:data:`CLEARED_GUCS`, merged into ``transaction._opening_statement_gucs``).
+   It rides the one opening statement, so it costs nothing.
+2. A statement OUTSIDE a transaction cannot carry a ``SET LOCAL`` in the same
+   round trip. When one is refused with exactly this parse-time error, it is
+   re-run ONCE inside a transaction that clears the setting first. The refusal
+   happens during parse/rewrite, before anything executes, so the re-run is
+   side-effect free. The cause is logged as a WARNING once per connection so it
+   never hides.
+
+A BORROWED ROLE IS THE SAME CLASS (2026-10-18). Another client of the tenant ran
+``set_config('role', 'authenticated', false)`` through the transaction pooler (236
+times, per pg_stat_statements) — session scope, so the server connection went back to
+the shared pool still wearing ``authenticated``. Every server statement routed to it
+ran as a person: ~100 ``permission denied for function claim_*`` /
+``record_changes_drain`` / ``resolve_full_context`` errors across every worker in three
+bursts. Same two halves:
+
+1. Every ORM transaction opens as OUR login role: ``role = 'none'`` rides the opening
+   statement (``set_config('role', 'none', true)`` = ``SET LOCAL ROLE NONE``).
+   ``rls_session`` still replaces it with the person's role, and that is LOCAL too.
+2. A statement outside a transaction refused with 42501 (insufficient privilege) is
+   re-run ONCE inside a transaction that resets the role first. A privilege refusal
+   rolls the whole single-statement transaction back, so the re-run is side-effect
+   free. A borrowed role it observes is logged as an ERROR and recorded durably
+   (``pooler_role_contamination``); a genuine denial fails the re-run and propagates.
+
+A checkout-time assertion cannot work on this path: in transaction mode each statement
+may land on a different server connection, so the only place a role can be asserted is
+inside the transaction (or single statement) that uses it — which is exactly here.
+"""
+
+from __future__ import annotations
+
+import logging
+import weakref
+from typing import Any, Awaitable, Callable, TypeVar
+
+logger = logging.getLogger(__name__)
+
+RESTRICT_GUC = "restrict_nonsystem_relation_kind"
+
+# Merged into every top-level transaction's opening GUCs. '' = no restriction
+# (the server default); set_config(..., true) scopes it to the transaction.
+# ``role`` = 'none' resets a borrowed role to the session's login role for the
+# transaction (``transaction._opening_statement_gucs`` always emits ``role`` last, and
+# an opener's own ``role`` — rls_session — replaces it).
+CLEARED_GUCS: dict[str, str] = {RESTRICT_GUC: "", "role": "none"}
+
+_OBJECT_NOT_IN_PREREQUISITE_STATE = "55000"
+_INSUFFICIENT_PRIVILEGE = "42501"
+
+T = TypeVar("T")
+
+_warned: "weakref.WeakSet[Any]" = weakref.WeakSet()
+_warned_ids: set[int] = set()
+
+
+def is_foreign_restrict_refusal(exc: BaseException) -> bool:
+    """True iff ``exc`` is the parse-time refusal caused by a leaked restrict GUC."""
+    if getattr(exc, "sqlstate", None) != _OBJECT_NOT_IN_PREREQUISITE_STATE:
+        return False
+    text = str(exc)
+    return "access to non-system" in text and "is restricted" in text
+
+
+def is_privilege_refusal(exc: BaseException) -> bool:
+    """True iff ``exc`` is a 42501 — possibly a borrowed role on a shared connection."""
+    return getattr(exc, "sqlstate", None) == _INSUFFICIENT_PRIVILEGE
+
+
+def _warn_once(conn: Any, exc: BaseException, what: str) -> None:
+    try:
+        if conn in _warned:
+            return
+        _warned.add(conn)
+    except TypeError:  # not weak-referenceable
+        if id(conn) in _warned_ids:
+            return
+        _warned_ids.add(id(conn))
+    logger.warning(
+        "[foreign-session-state] %s was refused because the shared server connection "
+        "carries %s from another client (a pg_dump through the transaction pooler sets it "
+        "session-wide and Supavisor does not reset it): %s — re-running once in a "
+        "transaction that clears it",
+        what,
+        RESTRICT_GUC,
+        exc,
+    )
+
+
+async def clear_in_transaction(conn: Any) -> None:
+    """Clear the restrict GUC and any borrowed role for the current transaction on ``conn``."""
+    await conn.execute(
+        "SELECT set_config($1, $2, true), set_config($3, $4, true)",
+        RESTRICT_GUC,
+        "",
+        "role",
+        "none",
+    )
+
+
+async def _report_borrowed_role(borrowed: str, login: str, what: str) -> None:
+    logger.error(
+        "[foreign-session-state] %s ran on a shared server connection wearing role '%s' "
+        "(login role '%s') left by another pooler client's session-scoped role change — "
+        "re-ran it as '%s' in a transaction that reset the role",
+        what,
+        borrowed,
+        login,
+        login,
+    )
+    try:
+        from matrx_orm.session.fallback import record_error
+
+        await record_error(
+            RuntimeError(
+                f"pooled server connection carried borrowed role '{borrowed}' "
+                f"(login '{login}'); {what} re-ran as '{login}'"
+            ),
+            kind="pooler_role_contamination",
+            source_app="matrx-orm",
+            source_feature="system",
+            route="orm:foreign_session_state",
+            payload={"borrowed_role": borrowed, "login_role": login, "what": what[:500]},
+        )
+    except Exception:  # noqa: BLE001 — the alarm must never cost the healed call
+        logger.exception("[foreign-session-state] could not durably record the borrowed role")
+
+
+async def run_clearing_foreign_restrict(
+    conn: Any, run: Callable[[], Awaitable[T]], *, what: str = "statement"
+) -> T:
+    """Run ``run()`` (one statement on ``conn``, outside any transaction).
+
+    On the leaked-restrict refusal, or a privilege refusal (a borrowed role), run it
+    once more inside a transaction on the same client connection that clears the
+    restrict setting and resets the role first. Any other error, or a second
+    refusal, propagates unchanged.
+    """
+    try:
+        return await run()
+    except Exception as exc:
+        privilege = is_privilege_refusal(exc)
+        if not privilege and not is_foreign_restrict_refusal(exc):
+            raise
+        if not privilege:
+            _warn_once(conn, exc, what)
+    if not privilege:
+        async with conn.transaction():
+            await clear_in_transaction(conn)
+            return await run()
+    async with conn.transaction():
+        # The transaction pins ONE server connection: read the role it carries, then
+        # reset it — both before the re-run, on that same backend.
+        row = await conn.fetchrow(
+            "SELECT current_user::text AS borrowed, session_user::text AS login"
+        )
+        await clear_in_transaction(conn)
+        result = await run()
+    borrowed = row["borrowed"] if row is not None else None
+    login = row["login"] if row is not None else None
+    if borrowed and login and borrowed != login:
+        await _report_borrowed_role(borrowed, login, what)
+    return result
+
+
+__all__ = [
+    "CLEARED_GUCS",
+    "RESTRICT_GUC",
+    "clear_in_transaction",
+    "is_foreign_restrict_refusal",
+    "is_privilege_refusal",
+    "run_clearing_foreign_restrict",
+]

{matrx_orm-3.1.233 → matrx_orm-3.1.235}/matrx_orm/pytest_plugin.py

@@ -198,3 +198,25 @@ def pytest_unconfigure(config: pytest.Config) -> None:  # noqa: ARG001
     _SESSION_SPILL_DIR = None
     _PREVIOUS_ENV = None
     _HIJACKS.clear()
+
+
+@pytest.fixture(autouse=True)
+def _no_live_system_error_rows():
+    """Under pytest ``record_error`` never inserts into the live ``ops.system_error``
+    (see ``fallback.CAPTURED_UNDER_TEST``); start every test with an empty capture."""
+    try:
+        from matrx_orm.session import fallback
+    except Exception:  # noqa: BLE001 — the ORM is not importable in every suite
+        yield
+        return
+    fallback.CAPTURED_UNDER_TEST.clear()
+    yield
+    fallback.CAPTURED_UNDER_TEST.clear()
+
+
+@pytest.fixture
+def captured_system_errors() -> list:
+    """The ``record_error`` calls this test made, withheld from the live database."""
+    from matrx_orm.session import fallback
+
+    return fallback.CAPTURED_UNDER_TEST

{matrx_orm-3.1.233 → matrx_orm-3.1.235}/matrx_orm/query/builder.py

@@ -48,6 +48,15 @@ async def _evict_updated_rows(model_cls: type, rows: list[Any]) -> None:
         await StateManager.clear_cache(model_cls)
 
 
+def _has_pending_in_stack(model_cls: type) -> bool:
+    """True when any Session on the stack holds unflushed writes for this model."""
+    try:
+        from matrx_orm.session import has_pending_in_stack
+    except ImportError:
+        return False
+    return has_pending_in_stack(model_cls)
+
+
 def _merge_pending_into_models(model_cls: type, db_models: list, filters: dict[str, Any]) -> list:
     """Apply pending Session state to a list of Model instances from DB.
 
@@ -945,9 +954,14 @@ class QueryBuilder(Generic[ModelT]):
     async def first(self) -> ModelT | None:
         """Get the first matching record.
 
-        Session-aware via the same merge pathway as :meth:`all`."""
+        Session-aware via the same merge pathway as :meth:`all`. With no pending
+        Session writes for this model the database is asked for one row
+        (``LIMIT 1``); fetching every row cost the DB host recorder a 50 MB,
+        780 ms read of its whole history every minute (2026-10-17)."""
         try:
             executor = await self._get_executor_async()
+            if not _has_pending_in_stack(self.model):
+                return await executor.first()
             results = await executor.all()
             merged = _merge_pending_into_models(
                 self.model,

{matrx_orm-3.1.233 → matrx_orm-3.1.235}/matrx_orm/session/fallback.py

@@ -651,6 +651,14 @@ async def _bulk_insert_failures(
     return failed
 
 
+#: Every ``record_error`` call made under pytest whose real insert was withheld.
+CAPTURED_UNDER_TEST: list[dict[str, Any]] = []
+
+
+def under_pytest() -> bool:
+    return "PYTEST_CURRENT_TEST" in os.environ
+
+
 async def record_error(
     exc: BaseException,
     *,
@@ -756,6 +764,29 @@ async def record_error(
             },
         }
 
+    if _insert_error is _LIVE_INSERT_ERROR and under_pytest():
+        # THE LIVE ERROR LOG IS NOT A TEST FIXTURE (2026-10-17). Unit tests with fake
+        # cleaners filed 14 real ``rag_page_clean_degraded`` rows into ops.system_error
+        # through this door. Under pytest the real insert never runs: the call is kept
+        # in ``CAPTURED_UNDER_TEST`` (the ``captured_system_errors`` fixture reads it).
+        # A test that patches ``_insert_error`` itself is isolated by its own double and
+        # still reaches it; ``_insert_error`` called directly still takes its own adapter.
+        CAPTURED_UNDER_TEST.append(
+            {
+                "kind": kind,
+                "error_type": resolved_error_type,
+                "error_text": resolved_error_text,
+                "user_id": user_id,
+                "organization_id": organization_id,
+                "source_app": source_app,
+                "source_feature": source_feature,
+                "route": route,
+                "context": context,
+                "payload": payload,
+            }
+        )
+        return
+
     try:
         await _insert_error(
             kind=kind,
@@ -915,6 +946,9 @@ async def _insert_error(
             )
 
 
+
+_LIVE_INSERT_ERROR = _insert_error
+
 async def _execute_error_insert(
     conn: Any,
     *,

{matrx_orm-3.1.233 → matrx_orm-3.1.235}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.233"
+version = "3.1.235"
 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.75",
+    "matrx-utils>=2.0.77",
     "pyyaml>=6.0.3",
     "python-dotenv>=1.0",
     "cryptography>=43.0",

matrx_orm-3.1.235/tests/level1/test_borrowed_role_never_reaches_server_calls.py

@@ -0,0 +1,279 @@
+"""A pooled server connection left wearing a person's role never runs our server calls.
+
+THE LIVE DEFECT (2026-10-18, bursts 04:58, 05:54, 07:49 UTC). ~100 ops.system_error rows
+across every worker at once — sms_dispatcher, notification_dispatcher, record-changes
+drain, workflow lease reaper, request audit, and an Agent run (``call_function
+resolve_full_context`` via ``run_clearing_foreign_restrict``) — all
+``permission denied for function ...`` on functions whose EXECUTE only postgres /
+service_role hold. pg_stat_statements named the source: a client of the same tenant ran
+
+    select set_config('request.jwt.claims', ..., false), ...,
+           set_config('role', 'authenticated', false)
+
+236 times through the TRANSACTION pooler. ``false`` = session scope: Supavisor hands that
+server connection back to the shared pool still wearing ``authenticated``, and our next
+statement routed to it runs as a person.
+
+THE CLASS: any server-role statement (a statement outside a transaction, or a top-level
+transaction without ``rls_session``) inherits whatever role the shared backend carries.
+The ORM's own scopes are transaction-local and cannot leak (proved below too); the
+defence must hold against a backend another client dirtied.
+
+``ServerBackend`` models one Supavisor server connection with real Postgres semantics:
+session-scope vs transaction-local ``role``, ``none`` = the login role, a server-only
+function that refuses every role but ``postgres``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import re
+from contextlib import asynccontextmanager
+from typing import Any
+
+import asyncpg
+import pytest
+
+from matrx_orm.adapters import AdapterRegistry
+from matrx_orm.core import db_function
+from matrx_orm.core import foreign_session_state as fss
+from matrx_orm.core.async_db_manager import AsyncDatabaseManager
+from matrx_orm.core.rls_session import rls_session
+from matrx_orm.core.session_context import configure_session_context
+from matrx_orm.core.transaction import _opening_statement_gucs, transaction
+
+LOGIN = "postgres"
+SERVER_ONLY = "claim_pending_sms_outbound_attempts"
+
+
+def _denied(fn: str) -> Exception:
+    exc = asyncpg.exceptions.InsufficientPrivilegeError(f"permission denied for function {fn}")
+    exc.sqlstate = "42501"
+    return exc
+
+
+class ServerBackend:
+    """One shared pooler server connection, as Postgres would behave."""
+
+    def __init__(self) -> None:
+        self.session_role: str | None = None  # None = login role
+        self.local_role: str | None = None
+        self.in_tx = False
+        self.server_calls = 0
+        self.denials = 0
+        self.statements: list[str] = []
+
+    # --- Postgres semantics -------------------------------------------------
+    @property
+    def current_user(self) -> str:
+        role = self.local_role if self.local_role is not None else self.session_role
+        return LOGIN if role in (None, "none") else role
+
+    def _apply_set_config(self, sql: str, args: tuple[Any, ...]) -> None:
+        pairs: list[tuple[str, str, bool]] = []
+        # bound pairs: set_config($n, $m, true)
+        bound = re.findall(r"set_config\(\$(\d+),\s*\$(\d+),\s*(true|false)\)", sql)
+        for name_i, value_i, local in bound:
+            pairs.append((args[int(name_i) - 1], args[int(value_i) - 1], local == "true"))
+        literal = re.findall(r"set_config\('([^']+)',\s*'([^']*)',\s*(true|false)\)", sql)
+        for name, value, local in literal:
+            pairs.append((name, value, local == "true"))
+        for name, value, is_local in pairs:
+            if name != "role":
+                continue
+            if is_local:
+                if self.in_tx:  # outside a transaction a LOCAL set dies with the statement
+                    self.local_role = value
+            else:
+                self.session_role = value
+
+    def _end_tx(self) -> None:
+        self.in_tx = False
+        self.local_role = None
+
+    async def execute(self, sql: str, *args: Any, timeout: Any = None) -> str:  # noqa: ASYNC109 — mirrors asyncpg's connection signature
+        self.statements.append(sql)
+        s = sql.strip().upper()
+        if s == "BEGIN":
+            self.in_tx = True
+        elif s in ("COMMIT", "ROLLBACK"):
+            self._end_tx()
+        elif "SET_CONFIG" in s:
+            self._apply_set_config(sql, args)
+        elif SERVER_ONLY in sql:
+            self._server_only()
+        return "OK"
+
+    def _server_only(self) -> list[dict[str, Any]]:
+        if self.current_user != LOGIN:
+            self.denials += 1
+            raise _denied(SERVER_ONLY)
+        self.server_calls += 1
+        return [{"id": "row-1"}]
+
+    async def fetch(self, sql: str, *args: Any, timeout: Any = None) -> list[dict[str, Any]]:  # noqa: ASYNC109 — mirrors asyncpg's connection signature
+        self.statements.append(sql)
+        if "set_config" in sql:
+            self._apply_set_config(sql, args)
+            return [{}]
+        if SERVER_ONLY in sql:
+            return self._server_only()
+        return []
+
+    async def fetchval(self, sql: str, *args: Any, timeout: Any = None) -> Any:  # noqa: ASYNC109 — mirrors asyncpg's connection signature
+        self.statements.append(sql)
+        if "current_user" in sql:
+            return self.current_user
+        if "set_config" in sql:
+            self._apply_set_config(sql, args)
+            return ""
+        if SERVER_ONLY in sql:
+            return self._server_only()[0]["id"]
+        return None
+
+    async def fetchrow(self, sql: str, *args: Any, timeout: Any = None) -> Any:  # noqa: ASYNC109 — mirrors asyncpg's connection signature
+        if "set_config" in sql:
+            self._apply_set_config(sql, args)
+        if "current_user" in sql:
+            return {
+                "current_user": self.current_user,
+                "session_user": LOGIN,
+                "borrowed": self.current_user,
+                "login": LOGIN,
+            }
+        return {}
+
+    @asynccontextmanager
+    async def transaction(self):  # asyncpg Connection.transaction()
+        self.in_tx = True
+        try:
+            yield
+        finally:
+            self._end_tx()
+
+    def terminate(self) -> None:
+        pass
+
+    # --- the foreign client -------------------------------------------------
+    def foreign_client_leaks_person_role(self) -> None:
+        """What pg_stat_statements caught: set_config('role','authenticated',false)."""
+        self._apply_set_config("select set_config('role','authenticated',false)", ())
+
+
+@pytest.fixture
+def backend(monkeypatch) -> ServerBackend:
+    b = ServerBackend()
+
+    @asynccontextmanager
+    async def get_connection(_config_name: Any, _timeout: Any = 10.0):
+        yield b
+
+    class _Adapter:
+        def get_connection(self):
+            return get_connection(None)
+
+    async def no_driver_timeout(_conn, **_kw):
+        return None
+
+    monkeypatch.setattr(AsyncDatabaseManager, "get_connection", get_connection)
+    monkeypatch.setattr(AdapterRegistry, "get", lambda _db: _Adapter())
+    monkeypatch.setattr(db_function, "resolve_driver_timeout", no_driver_timeout)
+    configure_session_context(None)
+    return b
+
+
+async def _server_call() -> Any:
+    return await db_function.call_function("platform", "communication", SERVER_ONLY, "w1", mode="rows")
+
+
+# ---------------------------------------------------------------------------
+# RED before the fix: a server call outside a transaction on a dirtied backend.
+# ---------------------------------------------------------------------------
+async def test_server_call_on_a_backend_left_wearing_a_person_role_runs_as_the_server(backend) -> None:
+    backend.foreign_client_leaks_person_role()
+    assert backend.current_user == "authenticated"
+
+    rows = await _server_call()
+
+    assert rows == [{"id": "row-1"}]
+    assert backend.server_calls == 1
+    # Repaired transaction-locally only — the session role is not ours to change.
+    assert backend.session_role == "authenticated"
+
+
+async def test_server_transaction_on_a_dirtied_backend_runs_as_the_login_role(backend) -> None:
+    backend.foreign_client_leaks_person_role()
+    async with transaction("platform"):
+        rows = await _server_call()
+    assert rows == [{"id": "row-1"}]
+    assert backend.denials == 0  # the BEGIN itself reset the borrowed role
+
+
+def test_every_transaction_opens_as_the_login_role_unless_rls_session_says_otherwise() -> None:
+    gucs = _opening_statement_gucs({})
+    assert gucs["role"] == "none"
+    assert list(gucs)[-1] == "role"
+    assert _opening_statement_gucs({"role": "authenticated"})["role"] == "authenticated"
+
+
+# ---------------------------------------------------------------------------
+# The person scope ending abnormally never leaves its role behind (our own scope).
+# ---------------------------------------------------------------------------
+async def test_rls_session_ended_by_an_exception_leaves_no_role(backend) -> None:
+    with pytest.raises(RuntimeError):
+        async with rls_session({"sub": "u1", "role": "authenticated"}, role="authenticated", database="platform"):
+            assert backend.current_user == "authenticated"
+            raise RuntimeError("boom")
+    assert backend.current_user == LOGIN
+    assert await _server_call() == [{"id": "row-1"}]
+    assert backend.denials == 0
+
+
+async def test_rls_session_ended_by_cancellation_leaves_no_role(backend) -> None:
+    entered = asyncio.Event()
+
+    async def person_work() -> None:
+        async with rls_session({"sub": "u1", "role": "authenticated"}, role="authenticated", database="platform"):
+            entered.set()
+            await asyncio.sleep(10)
+
+    task = asyncio.create_task(person_work())
+    await entered.wait()
+    task.cancel()
+    with pytest.raises(asyncio.CancelledError):
+        await task
+    assert backend.current_user == LOGIN
+    assert await _server_call() == [{"id": "row-1"}]
+    assert backend.denials == 0
+
+
+async def test_the_foreign_restrict_path_then_a_borrowed_role_still_heals(backend) -> None:
+    """The live Agent traceback went through run_clearing_foreign_restrict."""
+    backend.foreign_client_leaks_person_role()
+    value = await fss.run_clearing_foreign_restrict(
+        backend, lambda: backend.fetchval(f"select {SERVER_ONLY}()"), what="t"
+    )
+    assert value == "row-1"
+
+
+# ---------------------------------------------------------------------------
+# Never hides a real denial; always loud when it repairs.
+# ---------------------------------------------------------------------------
+async def test_a_genuine_denial_still_raises_after_one_rerun(backend) -> None:
+    calls = 0
+
+    async def run() -> Any:
+        nonlocal calls
+        calls += 1
+        raise _denied("auth_secret")
+
+    with pytest.raises(asyncpg.exceptions.InsufficientPrivilegeError):
+        await fss.run_clearing_foreign_restrict(backend, run)
+    assert calls == 2
+
+
+async def test_the_repair_is_loud(backend, caplog) -> None:
+    backend.foreign_client_leaks_person_role()
+    with caplog.at_level("ERROR"):
+        await _server_call()
+    assert any("authenticated" in r.getMessage() for r in caplog.records)

matrx_orm-3.1.235/tests/session/test_tests_never_write_live_system_error.py

@@ -0,0 +1,37 @@
+"""Guard: a test run must never file a row in the live ops.system_error.
+
+Incident 2026-10-16/17: 14 ``rag_page_clean_degraded`` rows landed in the live error
+log from unit tests with fake cleaners, via ``matrx_orm.record_error``.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from matrx_orm.session import fallback
+
+
+@pytest.mark.asyncio
+async def test_record_error_under_pytest_never_reaches_the_database(monkeypatch, captured_system_errors):
+    def _boom(*a, **k):
+        raise AssertionError("record_error reached the live database path under pytest")
+
+    # If the guard failed, the real _insert_error would resolve an adapter first.
+    monkeypatch.setattr("matrx_orm.adapters.AdapterRegistry.get", _boom)
+    await fallback.record_error(
+        RuntimeError("synthetic"), kind="guard_probe", source_feature="tests.guard"
+    )
+    assert [c["kind"] for c in captured_system_errors] == ["guard_probe"]
+
+
+@pytest.mark.asyncio
+async def test_the_guard_is_falsifiable_a_patched_insert_is_still_reached(monkeypatch, captured_system_errors):
+    seen = []
+
+    async def _fake(**kw):
+        seen.append(kw["kind"])
+
+    monkeypatch.setattr(fallback, "_insert_error", _fake)
+    await fallback.record_error(RuntimeError("x"), kind="patched_probe")
+    assert seen == ["patched_probe"]
+    assert captured_system_errors == []