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

{matrx_orm-3.1.73 → matrx_orm-3.1.75}/.gitignore

@@ -248,6 +248,7 @@ requirements_filtered.txt
 
 # Claude Code local worktrees and per-user settings
 .claude/worktrees/
+.worktrees/
 .claude/settings.local.json
 
 # Append-only snapshots from matrx_utils.update_history (unbounded; do not commit)
@@ -283,3 +284,4 @@ db/evidence/
 
 # Pooler contamination evidence — machine-local forensic capture, not source
 db/evidence/
+db/mirror/.env.mirror

{matrx_orm-3.1.73 → matrx_orm-3.1.75}/CLAUDE.md

@@ -23,7 +23,7 @@ Every table that becomes a Model needs row identity: a single-column primary key
 - 🚨 **ONE CONNECTION, REQUIRED** (`matrx_orm.platform_db`): `register_platform_db(name, ...)` + `platform_connection_url()` — the ONLY sanctioned way any Matrx service or package turns env vars into a pool. One set of variables (`SUPABASE_MATRIX_*`), owned here; TLS is a deployment input (`SUPABASE_MATRIX_SSL`), never hardcoded; **RAISES** if it isn't given a database — no degraded mode. Every package's `bootstrap_db()` is one call to it. A package may absolutely run on its OWN Postgres — that is a change of VALUES, never a new variable name; what it may never have is a *second candidate* or a fallback chain. `register_database_from_env` is the low-level primitive underneath — **application and package code must not call it directly** (guard: `scripts/check_one_database.py`, blocking in release).
 - **Core model layer**: `Model`, `BaseManager`, `BaseDTO`, `ModelView`, `model_registry`, plus 50+ field types (`CharField`, `IntegerField`, `ForeignKey`, `ManyToManyField`, `JSONField`, …).
 - **`MatrxEntity`** (`matrx_orm/entity.py`) — **the platform entity contract as an ORM primitive.** A table registered in `platform.entity_types` generates as a `MatrxEntity` (everything else stays a plain `Model`) and gets the behavior instead of every consumer hand-wiring it: `await page.versions()` (not a query on `history.row_versions`), `await page.restore(3)` (not a `version_restore` RPC + a cache bust — `restore()` busts the cache itself), `Note.alive()` / `.dead()` / `.soft_delete()` / `.undelete()`, and `Page.capabilities()`. Capability flags (`_entity_token`, `_is_versioned`, `_has_soft_delete`, `_is_org_scoped`, `_rls_variant`) are **stamped by the generator from the LIVE DATABASE** (does the table really carry the `_version_capture` trigger? a `deleted_at` column?) — never from `entity_types`' own flags, which are wrong on 61 of its 242 rows. **The database is truth; a flag is a claim.** Using a capability an entity does not declare RAISES (`EntityCapabilityError`) and names the fix — it never returns silently-wrong data, and `is_deleted` refuses to answer from a column a partial fetch never loaded. Drift guard: `scripts/check_entity_drift.py` (loud, non-blocking, in `release.sh`).
-- **Optimistic concurrency (`expected_version=`)** — opt-in compare-and-swap on the canonical `version` int column: `update_where` / `update_item` / instance `update()` take `expected_version=N` (`WHERE version = N`, `SET version = N + 1`; 0 rows → `DoesNotExist` if gone, `OptimisticLockError` with `current_version` + `current_row` if changed); `bulk_update(..., check_version=True)` guards per row; `MatrxEntity.update_with_rebase` auto-rebases past DISJOINT concurrent writes using `history.row_versions` snapshots. **Never automatic** — an unguarded write stays last-write-wins (the `_touch_row` trigger bumps `version` on every update, so auto-guarding would raise spurious conflicts). Contract: `common-docs/systems/optimistic-concurrency/FEATURE.md`.
+- **Optimistic concurrency (`expected_version=`)** — opt-in compare-and-swap on the canonical `version` int column: `update_where` / `update_item` / instance `update()` take `expected_version=N` (`WHERE version = N`, `SET version = N + 1`; 0 rows → `DoesNotExist` if gone, `OptimisticLockError` if changed — carrying the **decision package**: `current_version`, `current_row`, `contested_fields` (current values of ONLY the fields this write attempted), and `changed_by`/`changed_at` from `history.row_versions` where versioned); `bulk_update(..., check_version=True)` guards per row; `MatrxEntity.update_with_rebase` auto-rebases past DISJOINT concurrent writes using `history.row_versions` snapshots. **Never automatic** — an unguarded write stays last-write-wins (the `_touch_row` trigger bumps `version` on every update, so auto-guarding would raise spurious conflicts). Contract: `common-docs/systems/optimistic-concurrency/FEATURE.md`.
 - **Change tracking** — every instance records which columns were **loaded** (a SELECTed row, or the caller's kwargs) and which were **changed**. `save()` writes only those, so `.only("id","email")` + `save()` can never NULL the columns it never fetched (it used to — silent data loss). Mutable containers (jsonb/arrays) are always rewritten when loaded, because `obj.metadata["k"]=1` cannot be seen by `__setattr__`; **reassigning** (`obj.metadata = {...}`) is tracked precisely and is the sanctioned way. `Model._hydrate()` is the ONE row→model entry point.
 - **Upsert writes only what the caller supplied.** `upsert` / `bulk_upsert` / `upsert_with_conflict` materialize every field's Python default so the **INSERT** half is complete — but `ON CONFLICT DO UPDATE SET` covers **only the columns present in the caller's `data`** (an explicit `update_fields` still wins). Letting defaults reach the UPDATE half silently RESET every defaulted column on each re-upsert of an existing row: it once reset scraped-and-analyzed `research.rs_source` rows to `scrape_status='pending', server_attempts=0` (a watchdog then finalized them `'failed'`) and undid users' manual `is_included=false`. A caller-supplied `None` is excluded too — it is dropped from the INSERT, and `EXCLUDED.<col>` on an omitted column resolves to that column's **DEFAULT**. An upsert of only conflict keys means "ensure this row exists" and reconciles to a no-op self-assignment, never a raise (a bare `DO NOTHING` would break `RETURNING *`). Pinned by `tests/level1/test_upsert_default_leak.py`.
 - **Read-only models** (`_read_only = True`): a model that can be queried but NEVER written through the ORM — every write path raises `ReadOnlyModelError` (enforced at `QueryExecutor.insert/bulk_insert/upsert/update/delete`, so it covers all of `create`/`save`/`update`/`delete`/`update_where`/`delete_where`/`upsert`/`bulk_*`). Used for DB-managed tables the app must not mutate. The canonical **`auth.users`** model is baked into the schema generator (`get_string_user_model`) as the full, curated Supabase auth schema (safe columns only — no password/token fields), `_read_only`, bound per-database. Read a user's profile/metadata there; mutate users only through Supabase Auth (GoTrue).
@@ -98,7 +98,7 @@ If the admin router ever needs auth beyond token-based, inject a `resolve_user`
 
 - Full type hints — the ORM's contract with callers is very type-heavy and IDE discoverability matters.
 - No docstrings except on public API (Model, QueryBuilder, field classes, migration entry points). One line.
-- Hot paths (`QueryBuilder.execute`, adapter fetches, dict→dataclass transforms) must stay allocation-light. Favor slotted dataclasses / `__slots__`.
+- Hot paths (`QueryBuilder.execute`, adapter fetches, dict→dataclass transforms) must stay allocation-light. Favor mandated dataclasses / `__slots__`.
 - Explicit exception handling — never swallow `asyncpg` errors.
 
 ---

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

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

{matrx_orm-3.1.73 → matrx_orm-3.1.75}/matrx_orm/__init__.py

@@ -203,6 +203,12 @@ from .core.pool_watch import (
     connection_holder_census,
     register_pool_saturation_sink,
 )
+from .core.pooler_role import (
+    EmptyReadContaminationEvent,
+    PoolerRoleContamination,
+    SessionRoleChangeRefused,
+    register_contamination_sink,
+)
 from .core.pydantic_bridge import (
     validate_input as validate_model_input,
 )
@@ -573,6 +579,11 @@ __all__ = [
     "PoolSaturationEvent",
     "connection_holder_census",
     "register_pool_saturation_sink",
+    # ── Pooler role contamination ──────────────────────────────────────────────
+    "EmptyReadContaminationEvent",
+    "PoolerRoleContamination",
+    "SessionRoleChangeRefused",
+    "register_contamination_sink",
     # ── Signals ────────────────────────────────────────────────────────────────
     "Signal",
     "pre_create",

{matrx_orm-3.1.73 → matrx_orm-3.1.75}/matrx_orm/catalog.py

@@ -26,6 +26,7 @@ __all__ = [
     "softdelete_unique_conflicts",
     "qualified_relation_names",
     "trigger_function_usage",
+    "trigger_column_coverage",
     "column_privileges",
     "entity_capability_state",
 ]
@@ -487,6 +488,51 @@ async def trigger_function_usage(
     )
 
 
+async def trigger_column_coverage(
+    database: str,
+    *,
+    function_name: str,
+    column_names: list[str],
+) -> list[dict[str, Any]]:
+    """Return relations carrying any named column or the named trigger function."""
+    return await _query(
+        database,
+        """
+        WITH column_relations AS (
+          SELECT DISTINCT c.oid,
+                 n.nspname AS schema,
+                 c.relname AS table_name
+          FROM pg_attribute a
+          JOIN pg_class c ON c.oid = a.attrelid
+          JOIN pg_namespace n ON n.oid = c.relnamespace
+          WHERE a.attname = ANY($2::text[])
+            AND a.attnum > 0
+            AND NOT a.attisdropped
+            AND c.relkind = 'r'
+        ), trigger_relations AS (
+          SELECT DISTINCT t.tgrelid AS oid,
+                 n.nspname AS schema,
+                 c.relname AS table_name
+          FROM pg_trigger t
+          JOIN pg_class c ON c.oid = t.tgrelid
+          JOIN pg_namespace n ON n.oid = c.relnamespace
+          JOIN pg_proc p ON p.oid = t.tgfoid
+          WHERE NOT t.tgisinternal
+            AND p.proname = $1
+        )
+        SELECT COALESCE(cols.schema, triggers.schema) AS schema,
+               COALESCE(cols.table_name, triggers.table_name) AS table_name,
+               (cols.oid IS NOT NULL) AS has_columns,
+               (triggers.oid IS NOT NULL) AS has_trigger
+        FROM column_relations cols
+        FULL OUTER JOIN trigger_relations triggers ON cols.oid = triggers.oid
+        ORDER BY 1, 2
+        """,
+        function_name,
+        column_names,
+    )
+
+
 async def foreign_keys_to_relation(
     database: str,
     *,

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

@@ -89,6 +89,10 @@ Verified against code: 2026-08-15.
 
 ## Change log
 
+- 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
+  executable non-local role mutation.
 - 2026-08-15: Pinned transaction-local RLS role cleanup across success,
   exception, and early-return paths.
 - 2026-08-15: Added first-timeout pool holder census, host alarm seam, tracked raw-pool helper, and bounded cancellation-safe release.

{matrx_orm-3.1.73 → matrx_orm-3.1.75}/matrx_orm/core/async_db_manager.py

@@ -18,6 +18,11 @@ from matrx_orm.core.config import (
     resolve_pool_mode,
 )
 from matrx_orm.error_handling import handle_orm_operation
+from matrx_orm.core.pooler_role import (
+    VERIFY_EMPTY_READS,
+    assert_no_session_role_change,
+    reprove_empty_read,
+)
 from matrx_orm.core.tls import resolve_asyncpg_ssl
 from matrx_orm.exceptions import (
     AdapterError,
@@ -327,6 +332,25 @@ class AsyncDatabaseManager:
     _keepalive_tasks: dict[str, asyncio.Task] = {}  # per-config pool warmer
     _growth_locks: dict[str, asyncio.Lock] = {}
 
+    # Config names already resolved as "does an empty read need proving here?".
+    # 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] = {}
+
+    @classmethod
+    def _verifies_empty_reads(cls, config_name: str) -> bool:
+        if not VERIFY_EMPTY_READS:
+            return False
+        cached = cls._empty_read_verification.get(config_name)
+        if cached is not None:
+            return cached
+        try:
+            verifies = resolve_pool_mode(get_database_config(config_name)) == "transaction"
+        except Exception:
+            verifies = False
+        cls._empty_read_verification[config_name] = verifies
+        return verifies
+
     @classmethod
     async def _replace_zero_connection_pool(cls, config_name: str, failed_pool: Any) -> bool:
         """Atomically discard a pool that has lost every physical connection."""
@@ -1025,6 +1049,11 @@ class AsyncDatabaseManager:
         ``.timeout()`` seam for known-long reads. ``None`` keeps the pool
         default.
         """
+        # Layer 1 of the pooler-role defence: SQL that would leave a borrowed role
+        # on a shared server connection never reaches Postgres. See
+        # matrx_orm/core/pooler_role.py for what that contamination does to reads.
+        assert_no_session_role_change(query)
+
         # Reuse the active transaction connection when available
         try:
             from matrx_orm.core.transaction import get_active_connection
@@ -1124,6 +1153,21 @@ class AsyncDatabaseManager:
                                 read_attempt + 1,
                                 query[:120],
                             )
+                        if not results 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.
+                            true_rows = await reprove_empty_read(
+                                conn,
+                                config_name=config_name,
+                                query=query,
+                                args=args,
+                                statement_timeout=statement_timeout,
+                                normalize=_normalize_record,
+                            )
+                            if true_rows is not None:
+                                return true_rows
                         return [_normalize_record(r) for r in results]
                     except asyncpg.exceptions.PostgresSyntaxError as e:
                         raise QueryError(

matrx_orm-3.1.75/matrx_orm/core/pooler_role.py

@@ -0,0 +1,290 @@
+"""Pooler role contamination — the ORM's two layers against a SILENT empty read.
+
+WHY THIS EXISTS (reproduced 2026-08-15, FOUND_DEFECTS "An ORM read returned ZERO
+ROWS against a table holding 4,060"):
+
+On a transaction-mode pooler (Supavisor / PgBouncer) routing is *per transaction*,
+so consecutive statements from ONE client connection execute on DIFFERENT server
+connections. A server connection that any client on the tenant left with a
+non-LOCAL ``SET ROLE`` comes back out of the shared pool still wearing that role.
+Our statement then runs as ``authenticated`` instead of ``postgres``.
+
+**On an RLS table that GRANTs SELECT to ``authenticated``, that does not raise —
+it returns ZERO ROWS.** Measured live against the platform pooler: a bare
+``SET ROLE authenticated`` issued on 8 connections made 22 of 40 subsequent ORM
+reads of ``seo.backlink_observation`` (4,060 rows) come back empty, with no
+exception, while an identity probe interleaved on the same pool reported
+``current_user=authenticated, session_user=postgres`` on 21 of 40 samples.
+
+Silent emptiness is indistinguishable from "there is no data" for every sweep,
+reconciler, digest and monitor in the platform: a broken read reports a quiet week
+forever and every scheduled run stays green. ``db/pooler_session.py`` already says
+it for the migration tools — **a privilege error must never be recorded as
+absence** — and this module extends that to every ORM read, because a per-caller
+defence does not scale.
+
+TWO INDEPENDENT LAYERS, each sufficient alone, each screaming when it fires:
+
+1. **Prevention — the ORM refuses to emit a session-scoped role change.**
+   ``assert_no_session_role_change`` rejects a bare ``SET ROLE`` /
+   ``SET SESSION AUTHORIZATION`` / ``set_config('role', …, false)`` on every query
+   that goes through the ORM. This closes the one source class the 2026-08-14
+   investigation could never catch statically: SQL authored at RUNTIME — the
+   admin ``sql`` tool, ``db_admin``, registered ``SQLQuery`` objects, agent
+   scratch scripts. ``scripts/check_pooler_role_scope.py`` guards committed code;
+   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)
+   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.
+
+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.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from collections.abc import Callable
+from datetime import UTC, datetime
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict
+
+from matrx_utils import vcprint
+
+logger = logging.getLogger("matrx_orm.pooler_role")
+
+# Turning this off re-arms a silent-data-loss class platform-wide. It exists so a
+# deployment on a genuinely unshared Postgres can skip the work, and so the cost
+# is a code change (reviewable) rather than an env var (invisible).
+VERIFY_EMPTY_READS = True
+
+# How many times a re-proof may try to obtain a session running as our own login
+# role before it gives up and raises. A contaminated server connection is repaired
+# in-transaction, so one retry is almost always enough.
+REPROVE_ATTEMPTS = 3
+
+# A role change that is NOT scoped to a transaction. ``SET LOCAL ROLE`` and
+# ``set_config('role', …, true)`` are safe and deliberately not matched.
+_NON_LOCAL_SET_ROLE = re.compile(r"(?im)(?:^|;)\s*SET\s+(?!LOCAL\b)ROLE\b")
+_NON_LOCAL_SET_AUTHORIZATION = re.compile(
+    r"(?im)(?:^|;)\s*SET\s+(?!LOCAL\b)SESSION\s+AUTHORIZATION\b"
+)
+_NON_LOCAL_SET_CONFIG_ROLE = re.compile(
+    r"(?is)set_config\s*\(\s*['\"]role['\"]\s*,.*?,\s*(?:false|'false'|\"false\")\s*\)"
+)
+
+# Cheap pre-filter so the overwhelming majority of queries pay a substring scan
+# rather than three regexes. Deliberately loose — a false hint costs microseconds,
+# a missed one costs the platform a silent empty read.
+_ROLE_HINTS = ("role", "authorization", "set_config")
+
+
+class SessionRoleChangeRefused(RuntimeError):
+    """A query tried to change the Postgres role for the whole session."""
+
+
+class PoolerRoleContamination(RuntimeError):
+    """A statement could not be pinned to a session running as our own login role."""
+
+
+class EmptyReadContaminationEvent(BaseModel):
+    """A read returned zero rows because the session was wearing a borrowed role."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    config_name: str
+    query: str
+    contaminated_role: str
+    login_role: str
+    true_row_count: int
+    occurred_at: datetime
+
+
+ContaminationSink = Callable[[EmptyReadContaminationEvent], None]
+
+_sinks: list[ContaminationSink] = []
+
+
+def register_contamination_sink(sink: ContaminationSink) -> None:
+    """Register a durable observer for proven silent-empty reads."""
+    if sink not in _sinks:
+        _sinks.append(sink)
+
+
+def reset_contamination_sinks() -> None:
+    """Clear process state for isolated tests."""
+    _sinks.clear()
+
+
+def assert_no_session_role_change(query: str) -> None:
+    """Refuse SQL that would leave a borrowed role on a pooled server connection.
+
+    Layer 1. Raises ``SessionRoleChangeRefused`` and names the sanctioned path;
+    it never rewrites the caller's SQL, because guessing which role a caller meant
+    is exactly the ambiguity a guard must not resolve on its own.
+    """
+    if not query:
+        return
+    lowered = query.lower()
+    if not any(hint in lowered for hint in _ROLE_HINTS):
+        return
+    if (
+        _NON_LOCAL_SET_ROLE.search(query)
+        or _NON_LOCAL_SET_AUTHORIZATION.search(query)
+        or _NON_LOCAL_SET_CONFIG_ROLE.search(query)
+    ):
+        vcprint(
+            "REFUSED: a session-scoped role change reached the ORM.\n"
+            f"  query: {query[:300]}\n"
+            "  On a transaction pooler this role rides the SHARED server connection "
+            "back into the pool, and the next client — any service on this tenant — "
+            "silently runs as that role. On an RLS table it does not error: it "
+            "returns ZERO ROWS, and absence gets recorded as fact.\n"
+            "  Use `async with rls_session(claims, role=...)` (ORM) or "
+            "`impersonate(conn, role)` (db/pooler_session.py). Both use SET LOCAL "
+            "ROLE inside a transaction and cannot leak.",
+            color="red",
+            style="bold",
+        )
+        raise SessionRoleChangeRefused(
+            "A session-scoped role change (SET ROLE / SET SESSION AUTHORIZATION / "
+            "a non-local set_config role change) may never be executed through the ORM — it "
+            "contaminates the shared pooler and turns other services' reads into "
+            "silent empty results. Use rls_session(...) / impersonate(...), which "
+            "issue SET LOCAL ROLE inside a transaction."
+        )
+
+
+async def emit_contamination(event: EmptyReadContaminationEvent) -> None:
+    """Scream about a proven silent-empty read, durably record it, fan out to sinks."""
+    vcprint(
+        "POOLER ROLE CONTAMINATION — an ORM read returned ZERO ROWS that were "
+        "really there.\n"
+        f"  config: {event.config_name}\n"
+        f"  session ran as: {event.contaminated_role} (login role "
+        f"{event.login_role})\n"
+        f"  true row count on a clean session: {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 "
+        "those server connections cycle.",
+        color="red",
+        style="bold",
+    )
+    logger.error(
+        "[pooler-role] silent empty read repaired on %s (ran as %s, %d true rows): %s",
+        event.config_name,
+        event.contaminated_role,
+        event.true_row_count,
+        event.query[:200],
+    )
+    # Durable by default — a host should not have to wire anything for the
+    # platform's loudest data-integrity alarm to survive the process.
+    try:
+        from matrx_orm.session.fallback import record_error
+
+        await record_error(
+            PoolerRoleContamination(
+                f"read returned 0 rows as '{event.contaminated_role}'; "
+                f"{event.true_row_count} rows were really there"
+            ),
+            kind="pooler_role_contamination",
+            source_app="matrx-orm",
+            route=f"orm:{event.config_name}",
+            payload={
+                "config_name": event.config_name,
+                "query": event.query[:2000],
+                "contaminated_role": event.contaminated_role,
+                "login_role": event.login_role,
+                "true_row_count": event.true_row_count,
+            },
+        )
+    except Exception:
+        logger.exception("[pooler-role] could not durably record the contamination event")
+
+    for sink in list(_sinks):
+        try:
+            sink(event)
+        except Exception:
+            logger.exception("[pooler-role] contamination sink raised")
+
+
+async def reprove_empty_read(
+    conn: Any,
+    *,
+    config_name: str,
+    query: str,
+    args: tuple[Any, ...],
+    statement_timeout: float | None,
+    normalize: Callable[[Any], dict[str, Any]],
+) -> list[dict[str, Any]] | None:
+    """Re-run an empty read on a session proven to be running as US.
+
+    Layer 2. Returns the TRUE rows when the empty result was a lie, ``None`` when
+    the read was genuinely empty. Raises ``PoolerRoleContamination`` when a clean
+    session cannot be obtained at all — an unprovable absence is never a result.
+
+    ``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.
+    """
+    last_role: tuple[str, str] | None = None
+    for _ in range(REPROVE_ATTEMPTS):
+        async with conn.transaction():
+            await conn.execute("RESET ROLE")
+            identity = await conn.fetchrow("SELECT current_user, session_user")
+            current = identity["current_user"]
+            login = identity["session_user"]
+            if current != login:
+                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]
+
+        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),
+            )
+        )
+        return true_rows
+
+    current, login = last_role if last_role is not None else ("<unknown>", "<unknown>")
+    raise PoolerRoleContamination(
+        f"an empty read could not be proved: every attempt to pin a clean session "
+        f"landed as '{current}' (login role '{login}'). Anything this session could "
+        f"not see is a PRIVILEGE failure, not absence. Query: {query[:200]}"
+    )
+
+
+__all__ = [
+    "ContaminationSink",
+    "EmptyReadContaminationEvent",
+    "PoolerRoleContamination",
+    "REPROVE_ATTEMPTS",
+    "SessionRoleChangeRefused",
+    "VERIFY_EMPTY_READS",
+    "assert_no_session_role_change",
+    "emit_contamination",
+    "register_contamination_sink",
+    "reprove_empty_read",
+    "reset_contamination_sinks",
+]

{matrx_orm-3.1.73 → matrx_orm-3.1.75}/matrx_orm/exceptions.py

@@ -5,7 +5,10 @@ import ssl
 import traceback as _tb
 from collections.abc import Mapping
 from dataclasses import dataclass
+from datetime import date, datetime, time
+from decimal import Decimal
 from typing import Any
+from uuid import UUID
 
 from matrx_utils import vcprint
 
@@ -1899,11 +1902,49 @@ class UnknownDatabaseError(ORMException):
         return f"{_RED}{body}{_RESET}"
 
 
+def jsonable(value: object) -> object:
+    """Coerce a DB value into something JSON-serializable, losslessly where we can.
+
+    Error payloads cross the wire (the platform 409 `version_conflict` body is
+    typed `JsonValue`), so a datetime / UUID / Decimal in a conflict's contested
+    fields must not be what turns a conflict into a 500. Unknown types degrade
+    to `str()` — a display value is always better than a crash inside an error
+    handler.
+    """
+    if value is None or isinstance(value, bool | int | float | str):
+        return value
+    if isinstance(value, datetime | date | time):
+        return value.isoformat()
+    if isinstance(value, Decimal):
+        return float(value)
+    if isinstance(value, UUID):
+        return str(value)
+    if isinstance(value, Mapping):
+        return {str(k): jsonable(v) for k, v in value.items()}
+    if isinstance(value, list | tuple | set | frozenset):
+        return [jsonable(v) for v in value]
+    return str(value)
+
+
 class OptimisticLockError(ORMException):
     """Raised when an optimistic-lock version conflict is detected.
 
-    This means another process has updated the row since it was last fetched.
-    Re-fetch the record and retry the operation.
+    THE LOSER GETS A DECISION, NOT AN ERROR (platform ruling 2026-08-10, item 3).
+    A caller that lost a compare-and-swap already holds "proposed" (its own
+    payload); this exception carries everything else it needs to RESOLVE rather
+    than blindly retry:
+
+      ``expected_version``  — the revision the caller wrote against
+      ``current_version``   — the revision that actually won
+      ``contested_fields``  — {field: current value} for ONLY the fields this
+                              write attempted (never the whole row)
+      ``changed_by`` / ``changed_at`` — who moved the row and when, from
+                              ``history.row_versions``; None on an unversioned
+                              entity or when the lookup found nothing
+      ``current_row``       — the live instance, for a merge UI without a re-read
+
+    Resolution is just another write: keep-mine / keep-theirs / merged, resubmitted
+    against ``current_version``. No queue, no resolution endpoint.
     """
 
     def __init__(
@@ -1914,13 +1955,29 @@ class OptimisticLockError(ORMException):
         message: str | None = None,
         current_version: int | None = None,
         current_row=None,
+        contested_fields: Mapping[str, object] | None = None,
+        changed_by: object = None,
+        changed_at: object = None,
     ) -> None:
         msg = message or (
             f"Optimistic lock conflict on {getattr(model, '__name__', model)} "
             f"(pk={pk}, expected version={expected_version}"
             + (f", current version={current_version}" if current_version is not None else "")
+            + (f", contested fields={sorted(contested_fields)}" if contested_fields else "")
+            + (f", changed by {changed_by}" if changed_by else "")
             + "). The record was modified by another process — re-fetch and retry."
         )
+        # Stored already-jsonable: this is a decision package for a human or a
+        # wire payload, not a data-access path (that is `current_row`).
+        self.contested_fields: dict[str, object] | None = (
+            {str(k): jsonable(v) for k, v in contested_fields.items()}
+            if contested_fields is not None
+            else None
+        )
+        self.changed_by: str | None = str(changed_by) if changed_by is not None else None
+        self.changed_at: str | None = (
+            jsonable(changed_at) if changed_at is not None else None  # type: ignore[assignment]
+        )
         super().__init__(
             message=msg,
             model=model,
@@ -1928,6 +1985,9 @@ class OptimisticLockError(ORMException):
                 "pk": pk,
                 "expected_version": expected_version,
                 "current_version": current_version,
+                "contested_fields": self.contested_fields,
+                "changed_by": self.changed_by,
+                "changed_at": self.changed_at,
             },
         )
         self.expected_version = expected_version