matrx-orm 3.1.242__tar.gz → 3.1.244__tar.gz

{matrx_orm-3.1.242 → matrx_orm-3.1.244}/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## Unreleased
 
+- **Fix: an instance `update()` / `save()` runs a SQL expression instead of storing it.**
+  `row.update(metadata=JsonbMerge("metadata", {...}))` sent the expression through
+  `JSONField.get_db_prep_value`, and `json.dumps` wrote its attribute dict over the
+  column (1,328 live rows lost their metadata, 2026-10-22); a text column stored
+  `str(expression)`. `update_instance` and `bulk_update` now hand every expression to
+  the executor's SET compiler exactly as `update_where` does, and the instance ends
+  holding the computed value (re-read when RETURNING did not carry it). `F("col")` is
+  now a valid SET value. Every serialising path refuses an expression loudly with the
+  new `ExpressionAsDataError` (a `TypeError`): all `Field.get_db_prep_value`
+  implementations (wrapped per subclass), the json encoders (nested expressions), json
+  function arguments, and PostgREST adapter writes. New export `is_sql_expression`.
+  Guard: `tests/test_instance_update_runs_expressions.py` (9 live round trips; all 9
+  red on the prior code).
+
 - **Feature: entity doors in the associations engine.** A registry token may resolve to a
   *door* (`__entity_door__ = True`, `async load_by_ids(ids, *, actor_id) -> {id: row}`) instead of
   a Model, for nouns whose rows live behind the host's read doors (a record store). The engine

{matrx_orm-3.1.242 → matrx_orm-3.1.244}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matrx-orm
-Version: 3.1.242
+Version: 3.1.244
 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.242 → matrx_orm-3.1.244}/matrx_orm/__init__.py

@@ -129,7 +129,10 @@ from .core.expressions import (
     Like,
     Regex,
     JsonbConcat,
+    ExpressionAsDataError,
     JsonbMerge,
+    JsonbRemoveKeys,
+    is_sql_expression,
     JsonbObjectAgg,
     Lag,
     LastValue,
@@ -645,7 +648,10 @@ __all__ = [
     "ArrayIndex",
     "JsonText",
     "JsonbConcat",
+    "ExpressionAsDataError",
     "JsonbMerge",
+    "JsonbRemoveKeys",
+    "is_sql_expression",
     "JsonbObjectAgg",
     "Filter",
     "Case",

{matrx_orm-3.1.242 → matrx_orm-3.1.244}/matrx_orm/adapters/postgrest_client_adapter.py

@@ -225,6 +225,15 @@ class PostgRESTClientAdapter(BaseAdapter):
         filters = self._translate_filters(query_dict.get("filters", {}))
         data: dict | list = query_dict.get("data", {})
 
+        # PostgREST takes JSON rows, not SQL: an expression object here would be
+        # serialised as data. Refuse before anything is sent.
+        from matrx_orm.core.expressions import ExpressionAsDataError, is_sql_expression
+
+        for row in data if isinstance(data, list) else [data]:
+            for column, value in (row or {}).items():
+                if is_sql_expression(value):
+                    raise ExpressionAsDataError(column, value)
+
         logger.debug("[PostgRESTClientAdapter] %s %s", operation.upper(), table)
 
         try:

{matrx_orm-3.1.242 → matrx_orm-3.1.244}/matrx_orm/core/FEATURE.md

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

{matrx_orm-3.1.242 → matrx_orm-3.1.244}/matrx_orm/core/async_db_manager.py

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

{matrx_orm-3.1.242 → matrx_orm-3.1.244}/matrx_orm/core/expressions.py

@@ -1575,6 +1575,34 @@ class JsonbMerge(Func):
         return f"JsonbMerge({self.args[0]!r}, {self.value!r})"
 
 
+class JsonbRemoveKeys(Func):
+    """``COALESCE(field, '{}'::jsonb) - $keys::text[]`` — atomically drop top-level
+    keys from a JSONB column (the removal sibling of :class:`JsonbMerge`), for use as
+    an ``.update()`` / ``update_where()`` SET value. Every other key is untouched;
+    a key that is absent is a no-op.
+
+    Usage::
+
+        await SiteKeywordValue.update_where(
+            {"id__in": ids}, metadata=JsonbRemoveKeys("metadata", ["serp_cluster"])
+        )
+    """
+
+    function = "JSONB_REMOVE_KEYS"
+
+    def __init__(self, field: str, keys: list[str] | tuple[str, ...]) -> None:
+        super().__init__(field)
+        self.keys = [str(k) for k in keys]
+
+    def as_sql(self, params: list[Any]) -> str:
+        inner = _render_func_arg(self.args[0], params)
+        params.append(self.keys)
+        return f"COALESCE({inner}, '{{}}'::jsonb) - ${len(params)}::text[]"
+
+    def __repr__(self) -> str:
+        return f"JsonbRemoveKeys({self.args[0]!r}, {self.keys!r})"
+
+
 class JsonbConcat(Func):
     """``a || b`` — jsonb concat of two RENDERABLE expressions (columns,
     ``F()``/``Excluded()`` references, or nested ``Func``s), top-level keys
@@ -2566,3 +2594,51 @@ class TsMatch:
             f"TsMatch({self.column!r}, config={self.config!r}, "
             f"column_is_tsvector={self.column_is_tsvector})"
         )
+
+
+# ---------------------------------------------------------------------------
+# Expression-as-data guard
+# ---------------------------------------------------------------------------
+
+# Expression types that carry no ``as_sql`` of their own (they are rendered by
+# their consumers) — listed so the predicate below still recognises them.
+_EXPRESSION_TYPES_WITHOUT_AS_SQL: tuple[type, ...] = (F, Q, OuterRef)
+
+
+def is_sql_expression(value: Any) -> bool:
+    """True when *value* is a SQL expression object, never a storable value.
+
+    Every class in this module is SQL: either it renders itself through
+    ``as_sql`` (``Func`` and all its subclasses — ``JsonbMerge``, ``Now``,
+    ``Coalesce``…, ``Expression``/``BinaryExpr`` increments, ``Case``,
+    ``Subquery``, ``Value``, ``Excluded``, predicates, ``Window``…) or it is
+    one of the few renderer-side references (``F``, ``Q``, ``OuterRef``).
+    ``as_sql`` is looked up on the CLASS, so a test double whose instance
+    answers every attribute (``MagicMock``) is not mistaken for SQL.
+    """
+    if value is None or isinstance(value, type):
+        return False
+    if isinstance(value, _EXPRESSION_TYPES_WITHOUT_AS_SQL):
+        return True
+    return any("as_sql" in vars(klass) for klass in type(value).__mro__)
+
+
+class ExpressionAsDataError(TypeError):
+    """A SQL expression object reached a path that would store it as data.
+
+    Raised instead of serialising the object (a jsonb column used to receive
+    ``{"args": [...], "value": ...}`` — the 2026-10-22 metadata loss on 1,328
+    rows). Expressions are compiled to SQL by ``Model.update_where`` /
+    ``QueryBuilder.update`` and by instance ``update()`` / ``save()``; every
+    other write path (INSERT, upsert data, filters) refuses them here.
+    """
+
+    def __init__(self, field_name: str | None, value: Any) -> None:
+        self.field_name = field_name
+        self.value = value
+        super().__init__(
+            f"{type(value).__name__} is a SQL expression, not a value — refusing to "
+            f"serialise {value!r} into field {field_name!r}. Expressions run as SQL only "
+            f"in an UPDATE SET: use Model.update_where(filters, {field_name}=...) or "
+            f"instance.update({field_name}=...)."
+        )

{matrx_orm-3.1.242 → matrx_orm-3.1.244}/matrx_orm/core/fields.py

@@ -44,7 +44,35 @@ def _strip_nul_bytes(value: Any) -> Any:
     return value
 
 
+def _refuse_expression_as_data(prep: Any) -> Any:
+    """Wrap a ``get_db_prep_value`` so a SQL expression object can never be
+    serialised as a stored value (``json.dumps`` / ``str()`` of a ``JsonbMerge``
+    wrote its attribute dict into live jsonb columns). Every Field subclass is
+    wrapped at class creation, so a new field type cannot forget the check."""
+    import functools
+
+    if getattr(prep, "_refuses_expressions", False):
+        return prep
+
+    @functools.wraps(prep)
+    def guarded(self: Any, value: Any, *args: Any, **kwargs: Any) -> Any:
+        from matrx_orm.core.expressions import ExpressionAsDataError, is_sql_expression
+
+        if is_sql_expression(value):
+            raise ExpressionAsDataError(getattr(self, "name", None), value)
+        return prep(self, value, *args, **kwargs)
+
+    guarded._refuses_expressions = True  # type: ignore[attr-defined]
+    return guarded
+
+
 class Field:
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        own = cls.__dict__.get("get_db_prep_value")
+        if own is not None:
+            cls.get_db_prep_value = _refuse_expression_as_data(own)  # type: ignore[method-assign]
+
     if TYPE_CHECKING:
 
         @overload
@@ -147,6 +175,8 @@ class Field:
             return None
         return value
 
+    get_db_prep_value = _refuse_expression_as_data(get_db_prep_value)
+
     def desc(self):
         """Mark this field for descending order."""
         self._order_direction = "DESC"
@@ -1166,6 +1196,13 @@ class JSONBField(Field, Generic[_JT]):
         import uuid as _uuid
         from decimal import Decimal as _Decimal
 
+        from matrx_orm.core.expressions import ExpressionAsDataError, is_sql_expression
+
+        # A SQL expression nested inside a json value is never data — degrading
+        # it to its attribute dict is exactly how JsonbMerge objects were stored.
+        if is_sql_expression(obj):
+            raise ExpressionAsDataError(None, obj)
+
         # Pydantic v2 — preferred for the JSON-mode dump that handles nested
         # exotic types correctly.
         model_dump = getattr(obj, "model_dump", None)

{matrx_orm-3.1.242 → matrx_orm-3.1.244}/matrx_orm/core/pooler_role.py

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

{matrx_orm-3.1.242 → matrx_orm-3.1.244}/matrx_orm/operations/FEATURE.md

@@ -34,6 +34,21 @@ READ depends on the database, not on the deploy. `catalog_select`:
 Guard: `tests/test_dynamic_select_unregistered.py` (failing before the fallback
 existed), plus `tests/level1/test_dynamic_crud.py` for the write-side refusals.
 
+## SQL expressions are compiled, never stored
+
+An expression object (`JsonbMerge`, `F(...) + 1`, `Coalesce`, `Now()`, `Case`,
+`Subquery`, `Value`, `Excluded`, any `Func` or class with `as_sql`, plus `F`/`Q`/
+`OuterRef`) is SQL, never data. `update_where`, `QueryBuilder.update`, instance
+`update()`/`save()` (`update_instance`) and `bulk_update` all hand it to the
+executor's SET compiler; the instance ends holding the database-computed value.
+Every other path that would serialise one — INSERT data, upsert rows, a json
+value nesting one, a json function argument, a PostgREST write — raises
+`ExpressionAsDataError` before anything is written (`Field.get_db_prep_value` is
+wrapped for every Field subclass, and the json encoders refuse nested ones).
+Predicate: `matrx_orm.is_sql_expression`. Guard:
+`tests/test_instance_update_runs_expressions.py` (live round trip on a disposable
+loopback Postgres, `ISOLATED_PG17_DSN`; red on the prior code).
+
 ## Event-loop safety
 
 - **Bulk row coercion never runs on the event loop.** `bulk_insert_ignore` and
@@ -51,6 +66,9 @@ Verified against `conflict_writes.py` and
 
 ## Change Log
 
+- 2026-10-22 — Instance `update()`/`save()`/`bulk_update` compile SQL expressions;
+  every serialising path refuses them (`ExpressionAsDataError`).
+
 - 2026-09-26 — Added the typed `update_where` guard to `upsert_with_conflict`.
 
 - 2026-09-11 — Added the live-catalog read fallback so an unregistered view or a

{matrx_orm-3.1.242 → matrx_orm-3.1.244}/matrx_orm/operations/db_functions.py

@@ -34,6 +34,16 @@ if TYPE_CHECKING:  # pragma: no cover
 _FUNCTION_NAME_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)?$")
 
 
+def _json_arg_default(obj: Any) -> str:
+    """``default=str`` for json-bound function args — except a SQL expression,
+    which must never be stringified into data."""
+    from matrx_orm.core.expressions import ExpressionAsDataError, is_sql_expression
+
+    if is_sql_expression(obj):
+        raise ExpressionAsDataError(None, obj)
+    return str(obj)
+
+
 def _render_call(function_name: str, args: tuple[Any, ...]) -> tuple[str, list[Any]]:
     if not _FUNCTION_NAME_RE.match(function_name):
         raise ValueError(f"call_db_function: invalid function name {function_name!r}")
@@ -47,7 +57,7 @@ def _render_call(function_name: str, args: tuple[Any, ...]) -> tuple[str, list[A
             values.append(arg)
         elif isinstance(arg, dict | list):
             placeholders.append(f"${index}::jsonb")
-            values.append(json.dumps(arg, ensure_ascii=False, default=str))
+            values.append(json.dumps(arg, ensure_ascii=False, default=_json_arg_default))
         else:
             placeholders.append(f"${index}")
             values.append(arg)