matrx-orm 3.1.75__tar.gz → 3.1.76__tar.gz

{matrx_orm-3.1.75 → matrx_orm-3.1.76}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matrx-orm
-Version: 3.1.75
+Version: 3.1.76
 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
@@ -25,7 +25,7 @@ Requires-Python: >=3.13
 Requires-Dist: asyncpg>=0.31.0
 Requires-Dist: cryptography>=43.0
 Requires-Dist: gitpython>=3.1.40
-Requires-Dist: matrx-utils>=2.0.16
+Requires-Dist: matrx-utils>=2.0.17
 Requires-Dist: psycopg-pool>=3.2.5
 Requires-Dist: psycopg[binary]>=3.2.5
 Requires-Dist: python-dotenv>=1.0

{matrx_orm-3.1.75 → matrx_orm-3.1.76}/matrx_orm/core/FEATURE.md

@@ -82,13 +82,36 @@ commit; exceptions roll back; cancellation-shielded teardown finishes before
 the connection returns to the pool. No path can leave `authenticated` on a
 reused server connection.
 
+**Empty-to-nonempty is not contamination proof.** A READ COMMITTED row can be
+created between the original empty query and its reproof (`guest_executions`
+does this under concurrent first requests). `reprove_empty_read` captures the
+pinned server session's identity before and after `RESET SESSION AUTHORIZATION`
++ `RESET ROLE`, returns any newly visible rows, and emits
+`pooler_role_contamination` only when that identity change directly proves a
+borrowed role. This also repairs both `SET ROLE` and `SET SESSION AUTHORIZATION`;
+`RESET ROLE` alone does not repair the latter.
+
+**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
+deliberately contaminates server connections; repeated `RESET ROLE` statements are
+probabilistic cleanup on a transaction pooler, never isolation. Run it only by
+pointing the existing `SUPABASE_MATRIX_*` values at a loopback Postgres +
+transaction-pooler test stack.
+
 Pinned by `tests/level1/test_rls_session_scope.py` and
-`tests/level1/test_connection_poison_guard.py`.
+`tests/level1/test_connection_poison_guard.py`, plus
+`tests/test_pooler_role_guard.py` for the live-proof boundary.
 
-Verified against code: 2026-08-15.
+Verified against code: 2026-08-17.
 
 ## Change log
 
+- 2026-08-17: Required direct before/after role evidence before recording
+  contamination; concurrent empty-to-nonempty reads reconcile without a false
+  repair-queue row, and session-authorization contamination is reset too.
+- 2026-08-17: Refused destructive pooler-role verification against shared or
+  remote databases before any connection is opened.
 - 2026-08-16: Kept the destructive transaction-pool contamination proof out of
   the installable runtime package and isolated it under package tests; the
   operator wrapper is SQL-free and runtime prose no longer resembles an

{matrx_orm-3.1.75 → matrx_orm-3.1.76}/matrx_orm/core/pooler_role.py

@@ -37,10 +37,12 @@ TWO INDEPENDENT LAYERS, each sufficient alone, each screaming when it fires:
 
 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)
-   that starts with ``RESET ROLE``. If the rows are really there, the caller gets
-   the TRUE rows and the lie is reported through every registered sink. If the
-   session cannot be made clean, it RAISES rather than handing back an absence.
+   is 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
+   observed. If the session cannot be made clean, it RAISES rather than handing
+   back an absence.
 
 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
@@ -98,7 +100,7 @@ class PoolerRoleContamination(RuntimeError):
 
 
 class EmptyReadContaminationEvent(BaseModel):
-    """A read returned zero rows because the session was wearing a borrowed role."""
+    """An empty-read reproof directly observed and repaired a borrowed role."""
 
     model_config = ConfigDict(extra="forbid", frozen=True)
 
@@ -166,14 +168,14 @@ def assert_no_session_role_change(query: str) -> None:
 
 
 async def emit_contamination(event: EmptyReadContaminationEvent) -> None:
-    """Scream about a proven silent-empty read, durably record it, fan out to sinks."""
+    """Scream about a directly observed borrowed role and fan out to sinks."""
     vcprint(
-        "POOLER ROLE CONTAMINATION — an ORM read returned ZERO ROWS that were "
-        "really there.\n"
+        "POOLER ROLE CONTAMINATION — an empty-read reproof directly observed "
+        "and repaired a borrowed server role.\n"
         f"  config: {event.config_name}\n"
-        f"  session ran as: {event.contaminated_role} (login role "
+        f"  pooled session was: {event.contaminated_role} (clean login role "
         f"{event.login_role})\n"
-        f"  true row count on a clean session: {event.true_row_count}\n"
+        f"  cleaned query row count: {event.true_row_count}\n"
         f"  query: {event.query[:300]}\n"
         "  The caller has been given the TRUE rows. Something on this Postgres "
         "tenant issued a non-LOCAL SET ROLE; every other client is exposed until "
@@ -182,7 +184,7 @@ async def emit_contamination(event: EmptyReadContaminationEvent) -> None:
         style="bold",
     )
     logger.error(
-        "[pooler-role] silent empty read repaired on %s (ran as %s, %d true rows): %s",
+        "[pooler-role] borrowed pooled role repaired on %s (observed %s, %d clean rows): %s",
         event.config_name,
         event.contaminated_role,
         event.true_row_count,
@@ -195,8 +197,9 @@ async def emit_contamination(event: EmptyReadContaminationEvent) -> None:
 
         await record_error(
             PoolerRoleContamination(
-                f"read returned 0 rows as '{event.contaminated_role}'; "
-                f"{event.true_row_count} rows were really there"
+                f"reproof observed pooled role '{event.contaminated_role}' "
+                f"(login role '{event.login_role}'); cleaned read returned "
+                f"{event.true_row_count} rows"
             ),
             kind="pooler_role_contamination",
             source_app="matrx-orm",
@@ -241,10 +244,18 @@ async def reprove_empty_read(
     last_role: tuple[str, str] | None = None
     for _ in range(REPROVE_ATTEMPTS):
         async with conn.transaction():
+            before = await conn.fetchrow("SELECT current_user, session_user")
+            before_current = before["current_user"]
+            before_session = before["session_user"]
+
+            # RESET ROLE alone cannot repair SET SESSION AUTHORIZATION: in that
+            # state current_user and session_user can agree on the WRONG identity.
+            # Reset both while this transaction pins the exact server connection.
+            await conn.execute("RESET SESSION AUTHORIZATION")
             await conn.execute("RESET ROLE")
-            identity = await conn.fetchrow("SELECT current_user, session_user")
-            current = identity["current_user"]
-            login = identity["session_user"]
+            after = await conn.fetchrow("SELECT current_user, session_user")
+            current = after["current_user"]
+            login = after["session_user"]
             if current != login:
                 last_role = (current, login)
                 continue
@@ -253,18 +264,24 @@ async def reprove_empty_read(
                 return None
             true_rows = [normalize(r) for r in rows]
 
-        await emit_contamination(
-            EmptyReadContaminationEvent(
-                config_name=config_name,
-                query=query,
-                # The first read ran on a session we could not observe directly;
-                # what we can state is the role it was NOT running as.
-                contaminated_role="<not the login role>" if last_role is None else last_role[0],
-                login_role=login,
-                true_row_count=len(true_rows),
-                occurred_at=datetime.now(UTC),
+            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),
+                )
             )
-        )
         return true_rows
 
     current, login = last_role if last_role is not None else ("<unknown>", "<unknown>")

{matrx_orm-3.1.75 → matrx_orm-3.1.76}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.75"
+version = "3.1.76"
 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.16",
+    "matrx-utils>=2.0.17",
     "pyyaml>=6.0.3",
     "python-dotenv>=1.0",
     "cryptography>=43.0",

{matrx_orm-3.1.75 → matrx_orm-3.1.76}/tests/live_pooler_role.py

@@ -2,19 +2,46 @@
 
 from __future__ import annotations
 
+from ipaddress import ip_address
 from typing import Any
 
 from matrx_orm.core import pooler_role
 from matrx_orm.core.async_db_manager import AsyncDatabaseManager
+from matrx_orm.core.config import get_database_config
 from matrx_orm.core.pooler_role import SessionRoleChangeRefused, register_contamination_sink
 from matrx_orm.core.tls import resolve_asyncpg_ssl_from_dsn
 from matrx_orm.platform_db import platform_connection_url
 
 
+class UnsafePoolerVerificationTarget(RuntimeError):
+    pass
+
+
+def assert_isolated_pooler_target(config_name: str) -> None:
+    config = get_database_config(config_name)
+    host = str(config.get("host") or "").strip().lower().rstrip(".")
+    address = host[1:-1] if host.startswith("[") and host.endswith("]") else host
+    try:
+        is_loopback = ip_address(address).is_loopback
+    except ValueError:
+        is_loopback = address == "localhost"
+    if is_loopback:
+        return
+    raise UnsafePoolerVerificationTarget(
+        "DESTRUCTIVE pooler-role verification REFUSED: the configured database host "
+        f"{host!r} is not loopback. This proof deliberately leaves server connections "
+        "wearing a borrowed role; a best-effort RESET ROLE sweep cannot make a shared "
+        "or remote transaction pool safe again. Point the existing SUPABASE_MATRIX_* "
+        "values at a local Postgres + transaction-pooler test stack, then retry."
+    )
+
+
 async def run_live_verification(
     *, config_name: str, table: str, contaminate: int, iterations: int, baseline: bool
 ) -> int:
-    """Contaminate a shared pool deliberately, prove both guards, then scrub it."""
+    """Contaminate an isolated local pool, prove both guards, then scrub it."""
+    assert_isolated_pooler_target(config_name)
+
     import asyncpg
 
     dsn = platform_connection_url(package="verify_pooler_role_guard")

{matrx_orm-3.1.75 → matrx_orm-3.1.76}/tests/test_pooler_role_guard.py

@@ -19,6 +19,7 @@ from matrx_orm.core.pooler_role import (
     reprove_empty_read,
     reset_contamination_sinks,
 )
+from . import live_pooler_role
 
 REFUSED = [
     "SET ROLE authenticated",
@@ -104,26 +105,62 @@ async def test_genuinely_empty_read_stays_empty_and_is_silent() -> None:
     events: list[EmptyReadContaminationEvent] = []
     register_contamination_sink(events.append)
 
-    conn = _FakeConn(identities=[("postgres", "postgres")], rows=[])
+    conn = _FakeConn(
+        identities=[("postgres", "postgres"), ("postgres", "postgres")],
+        rows=[],
+    )
     assert await _reprove(conn) is None
     assert events == []
+    assert "RESET SESSION AUTHORIZATION" in conn.log
     assert "RESET ROLE" in conn.log
     reset_contamination_sinks()
 
 
 @pytest.mark.asyncio
-async def test_empty_read_that_was_a_lie_returns_the_true_rows_and_screams() -> None:
+async def test_concurrent_insert_is_reconciled_without_a_false_contamination_alarm() -> None:
+    reset_contamination_sinks()
+    events: list[EmptyReadContaminationEvent] = []
+    register_contamination_sink(events.append)
+
+    conn = _FakeConn(
+        identities=[("postgres", "postgres"), ("postgres", "postgres")],
+        rows=[{"id": "guest-row"}],
+    )
+    rows = await _reprove(conn)
+
+    assert rows == [{"id": "guest-row"}]
+    assert events == []
+    reset_contamination_sinks()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "before",
+    [
+        ("authenticated", "postgres"),
+        ("authenticated", "authenticated"),
+    ],
+    ids=["set-role", "set-session-authorization"],
+)
+async def test_observed_role_contamination_returns_true_rows_and_screams(
+    before: tuple[str, str],
+) -> None:
     reset_contamination_sinks()
     events: list[EmptyReadContaminationEvent] = []
     register_contamination_sink(events.append)
 
-    conn = _FakeConn(identities=[("postgres", "postgres")], rows=[{"id": "a"}, {"id": "b"}])
+    conn = _FakeConn(
+        identities=[before, ("postgres", "postgres")],
+        rows=[{"id": "a"}, {"id": "b"}],
+    )
     rows = await _reprove(conn)
 
     assert rows == [{"id": "a"}, {"id": "b"}]
     assert len(events) == 1
     assert events[0].true_row_count == 2
     assert events[0].config_name == "test_db"
+    assert events[0].contaminated_role == "authenticated"
+    assert events[0].login_role == "postgres"
     reset_contamination_sinks()
 
 
@@ -131,7 +168,11 @@ async def test_empty_read_that_was_a_lie_returns_the_true_rows_and_screams() ->
 async def test_a_session_that_never_comes_clean_raises_instead_of_reporting_absence() -> None:
     reset_contamination_sinks()
     conn = _FakeConn(
-        identities=[("authenticated", "postgres")] * 5,
+        identities=[
+            identity
+            for _ in range(5)
+            for identity in (("authenticated", "postgres"), ("authenticated", "postgres"))
+        ],
         rows=[],
     )
     with pytest.raises(PoolerRoleContamination) as excinfo:
@@ -140,3 +181,44 @@ async def test_a_session_that_never_comes_clean_raises_instead_of_reporting_abse
     # failure, never data.
     assert "not absence" in str(excinfo.value)
     reset_contamination_sinks()
+
+
+@pytest.mark.parametrize("host", ["localhost", "localhost.", "127.0.0.1", "::1", "[::1]"])
+def test_destructive_live_proof_accepts_only_loopback_hosts(
+    host: str, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setattr(
+        live_pooler_role,
+        "get_database_config",
+        lambda _name: {"host": host},
+    )
+
+    live_pooler_role.assert_isolated_pooler_target("test_db")
+
+
+@pytest.mark.asyncio
+async def test_destructive_live_proof_refuses_remote_before_connecting(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(
+        live_pooler_role,
+        "get_database_config",
+        lambda _name: {"host": "aws-1-us-west-1.pooler.supabase.com"},
+    )
+
+    def unexpected_dsn(**_kwargs: object) -> str:
+        pytest.fail("the verifier tried to build a DSN for a remote target")
+
+    monkeypatch.setattr(live_pooler_role, "platform_connection_url", unexpected_dsn)
+
+    with pytest.raises(
+        live_pooler_role.UnsafePoolerVerificationTarget,
+        match="DESTRUCTIVE pooler-role verification REFUSED",
+    ):
+        await live_pooler_role.run_live_verification(
+            config_name="test_db",
+            table="public.example",
+            contaminate=1,
+            iterations=1,
+            baseline=False,
+        )