matrx-orm 3.1.145__tar.gz → 3.1.147__tar.gz

{matrx_orm-3.1.145 → matrx_orm-3.1.147}/.gitignore

@@ -304,3 +304,12 @@ _kind_marker_law_scratch*/
 
 # packed npm tarballs are build output, never source (doctrine: typescript-package-standard)
 *.tgz
+
+# Peers' kit scratch witnesses. A `.kit-<name>-witness.XXXXXX/` directory is a
+# full COPY of kit/src planted inside the packages tree — three of them held a
+# duplicate `format.ts` on 2026-09-12 — and it sits in the `check:package-twins`
+# scan ROOT. `git ls-files` only reaches TRACKED files, so the guard never saw
+# them; the risk was a broad `git add` committing three formatter twins in one
+# stroke, which is the exact class that guard exists to stop. Ignored, never
+# deleted: they are another agent's evidence.
+apps/shared/.kit-*-witness.*/

{matrx_orm-3.1.145 → matrx_orm-3.1.147}/BASE_CLASS_METHODS.md

@@ -59,9 +59,21 @@ The following methods are available directly from all manager classes:
 - `upsert_item(data, conflict_fields, update_fields=None)`
 - `upsert_items(items_data, conflict_fields, update_fields=None)`
 - `count(**filters)`
-- `update_where(filters, *, expected_version=None, **updates)`
+- `update_where(filters, *, expected_version=None, lock_rows_in_pk_order=False, **updates)`
 - `delete_where(*, expected_version=None, **filters)`
 
+### A multi-row UPDATE that racing callers share — `lock_rows_in_pk_order=True`
+
+Pass it whenever concurrent callers can run the SAME multi-row `update_where`
+over an **overlapping** row set. The statement then takes its row locks
+ascending by primary key (`WHERE pk IN (SELECT pk ... ORDER BY pk FOR UPDATE)`)
+instead of in plan-scan order, which is what stops two copies of one statement
+from deadlocking each other (SQLSTATE 40P01). Sorting the id list yourself does
+NOT do this — the plan decides lock order, not the array. Needs a single-column
+primary key; contradictory with `expected_version=` (that addresses ONE row, so
+there is no order to fix) and refused. Full reasoning and the incident:
+`matrx_orm/query/FEATURE.md` § A multi-row UPDATE can pin its lock ORDER.
+
 ### Optimistic concurrency — `expected_version=`
 
 **Opt-in compare-and-swap on the canonical `version` int column.** Pass

{matrx_orm-3.1.145 → matrx_orm-3.1.147}/PKG-INFO

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

{matrx_orm-3.1.145 → matrx_orm-3.1.147}/matrx_orm/adapters/async_postgresql.py

@@ -60,11 +60,17 @@ class AsyncPostgreSQLAdapter(BaseAdapter):
         *args: Any,
         timeout: float = 10.0,
         max_retries: int = 2,
+        statement_timeout: float | None = None,
     ) -> list[dict[str, Any]]:
         from matrx_orm.core.async_db_manager import AsyncDatabaseManager
 
         return await AsyncDatabaseManager.execute_write(
-            self._config_name, sql, *args, timeout=timeout, max_retries=max_retries
+            self._config_name,
+            sql,
+            *args,
+            timeout=timeout,
+            max_retries=max_retries,
+            statement_timeout=statement_timeout,
         )
 
     # ------------------------------------------------------------------

{matrx_orm-3.1.145 → matrx_orm-3.1.147}/matrx_orm/adapters/base_adapter.py

@@ -50,10 +50,16 @@ class BaseAdapter(ABC):
         *args: Any,
         timeout: float = 10.0,
         max_retries: int = 2,
+        statement_timeout: float | None = None,
     ) -> list[dict[str, Any]]:
         """Execute a write (INSERT/UPDATE/DELETE) query and return rows as dicts.
 
         Implementations should handle retries and write-queue routing as needed.
+        ``timeout`` is the connection-acquire timeout; ``statement_timeout``
+        (when set) overrides the pool's ``command_timeout`` for THIS statement
+        only — the write-side twin of ``QueryBuilder.timeout()``, for a write
+        whose size is known to need longer than the pool default (a workflow
+        checkpoint carrying a fan-out's inline payloads).
         """
 
     # ------------------------------------------------------------------

{matrx_orm-3.1.145 → matrx_orm-3.1.147}/matrx_orm/adapters/postgrest_client_adapter.py

@@ -338,6 +338,7 @@ class PostgRESTClientAdapter(BaseAdapter):
         *args: Any,
         timeout: float = 10.0,
         max_retries: int = 2,
+        statement_timeout: float | None = None,
     ) -> list[dict[str, Any]]:
         """Raw SQL writes are not supported via PostgREST."""
         raise NotImplementedError(

{matrx_orm-3.1.145 → matrx_orm-3.1.147}/matrx_orm/adapters/supabase_adapter.py

@@ -122,11 +122,17 @@ class SupabaseAdapter(BaseAdapter):
         *args: Any,
         timeout: float = 10.0,
         max_retries: int = 2,
+        statement_timeout: float | None = None,
     ) -> list[dict[str, Any]]:
         from matrx_orm.core.async_db_manager import AsyncDatabaseManager
 
         return await AsyncDatabaseManager.execute_write(
-            self._config_name, sql, *args, timeout=timeout, max_retries=max_retries
+            self._config_name,
+            sql,
+            *args,
+            timeout=timeout,
+            max_retries=max_retries,
+            statement_timeout=statement_timeout,
         )
 
     # ------------------------------------------------------------------

{matrx_orm-3.1.145 → matrx_orm-3.1.147}/matrx_orm/core/FEATURE.md

@@ -45,6 +45,67 @@ Guard: `tests/level1/test_read_connection_retry.py`.
 rejects the statement before execution, so this narrow failure is replay-safe;
 ambiguous write failures remain single-attempt.
 
+**A write may set its own statement ceiling — `Model.create(statement_timeout=…)`
+(seconds, keyword-only).** The read side has had `QueryBuilder.timeout()` for a
+while; the write door had nothing, so the pool's `command_timeout` (10s) was the
+only ceiling any INSERT could have. It threads
+`Model.create` → `operations/create` → `query["statement_timeout"]` →
+`QueryExecutor.insert` → `adapter.execute_write(statement_timeout=)` →
+`execute_query(statement_timeout=)` → asyncpg `fetch(..., timeout=)`, so it
+overrides — never widens — anything else: pool-acquire timeout and every other
+statement are untouched. It raises no retry rights: an ambiguous write is still
+single-attempt HERE, and a caller that re-issues one must own an idempotency key
+(matrx-graph's checkpoint INSERT is keyed by checkpoint id and reads the row back).
+Added 2026-09-12 after a 1.1 MB `workflow.checkpoint` row timed out at 10s under
+load and killed a paid-for workflow run. Guard:
+`tests/level1/test_query_timeout.py::TestInsertStatementTimeout`.
+
+**A statement the SERVER cancelled to break a lock collision is re-issued — the
+second and last replay-safe failure, and it covers READS.** SQLSTATE `40P01`
+(`deadlock_detected`), `40001` (`serialization_failure`) and `55P03`
+(`lock_not_available`) are the statuses where Postgres aborted the statement IN
+FULL: the effects are gone with certainty, so a replay is exactly-once, not the
+at-least-once hazard that makes a statement timeout or a mid-query disconnect
+unretryable. Class-40 siblings stay out by name — `40003`
+(`StatementCompletionUnknownError`) is literally "the server cannot say whether
+this completed", and `40002` is a constraint failure wearing a class-40 code.
+The victim is often innocent of any write: a multi-table READ is cancelled
+whenever a concurrent DDL session wants AccessExclusiveLock on a table it already
+holds a lock on, which reached a person as "listConversations: deadlock detected"
+on /chat.
+
+🚨 **THERE IS ONE LOOP AND ONE BUDGET.** `matrx_orm/core/write_retry.py` owns the
+classification (`is_confidently_aborted_lock_contention`), the knob policy, and
+the loop (`run_with_lock_retry`); both doors into the database run through it —
+`execute_query` for every statement and `call_function` for RPCs (an RPC reaches
+Postgres on a raw connection, bypassing `execute_query` entirely, so before this a
+deadlock inside any `SECURITY DEFINER` write RPC failed its caller outright).
+`_execute_with_retry` retries only the nothing-was-sent classes above it and must
+never grow a lock budget of its own: on 2026-09-12 two independent lock-retry
+mechanisms landed within hours and nested, making the real ceiling the product of
+two budgets nobody had chosen. Statement-level replay is sound only because both
+doors return early when a `transaction()` is active: every attempt the loop
+retries WAS its own transaction. Inside a caller's transaction the rollback took
+the whole block and only that transaction's owner can redo the unit, so the
+refusal is typed `LockContentionError(in_transaction=True)`.
+
+The budget is `platform.feature_knob` feature `orm.write_retry`
+(`deadlock_max_retries` 4, `deadlock_backoff_base_ms` 25,
+`deadlock_backoff_max_ms` 400 — seeded by
+`db/migrations/0647_orm_write_retry_knobs.sql`, re-read every 60s, not
+org-overridable). Backoff is FULL jitter: the victims are N invocations that
+started together, so a fixed sleep re-collides them in lockstep. Every retry and
+every heal is logged `[lock-retry]`, and when the budget is spent the
+`LockContentionError` NAMES the attempts — and points at the lock ORDER
+(`Model.update_where(..., lock_rows_in_pk_order=True)`) rather than a bigger
+retry count. A database whose knob rows cannot be read (a standalone install on a
+bare Postgres) runs on the recorded starting values and logs one ERROR naming the
+remedy — a raise here would turn a survivable deadlock into a hard failure on the
+very path that exists to survive it. Guards:
+`tests/level1/test_lock_contention_retry.py` (the loop's semantics per statement)
++ `tests/level1/test_deadlock_retry.py` (the knob budget, the RPC door, the lock
+order).
+
 `AsyncDatabaseManager.execute_query` must classify every PostgreSQL integrity
 constraint violation as `IntegrityError`. Known categories retain their useful
 labels (`unique`, `foreign_key`, `not_null`, `check`, `exclusion`, and
@@ -220,6 +281,20 @@ can never disagree about who the blocker was.
 Verified against the live database: 2026-08-21.
 
 ## Change log
+- 2026-09-12 (later): ONE retry mechanism. Two independent lock-retry
+  implementations for the same class landed hours apart — a `LockContentionError`
+  + constant-budget loop inside `execute_query`, and a `TransientTransactionError`
+  + knob-budget loop wrapped around `_execute_with_retry` — and merged into
+  nesting. Reconciled to: `LockContentionError` survives (it covers reads and
+  55P03 too), the loop lives once in `write_retry.run_with_lock_retry` and is used
+  by `execute_query` AND `call_function`, its budget is the `orm.write_retry`
+  knob rows (never a constant), and `TransientTransactionError` is deleted.
+- 2026-09-12: A statement Postgres cancelled to break a lock collision
+  (40P01/40001/55P03) is re-issued on a fresh connection instead of failing the
+  caller. Before this it fell to the catch-all as `UnknownDatabaseError` and
+  killed the request: four parallel `ai.agent.start` invocations deadlocked on
+  `users.user_secrets` and errored a whole workflow run, and a pure `/chat`
+  conversation-list READ showed "deadlock detected" to a person.
 - 2026-08-30: Classified server restart/failover rejection during pool checkout
   as retryable connection failure before any caller SQL is sent.
 - 2026-08-24: Recovered read-only disconnects masked by empty-read reproof's

{matrx_orm-3.1.145 → matrx_orm-3.1.147}/matrx_orm/core/async_db_manager.py

@@ -6,7 +6,6 @@ from dataclasses import dataclass
 import json
 import logging
 import os
-import random
 import traceback
 from contextlib import asynccontextmanager
 from typing import Any
@@ -44,6 +43,15 @@ from matrx_orm.exceptions import (
     StateError,
     UnknownDatabaseError,
 )
+from matrx_orm.core.write_retry import (
+    CONTENTION_EXC as _CONTENTION_EXC,
+)
+from matrx_orm.core.write_retry import (
+    is_confidently_aborted_lock_contention as _is_confidently_aborted_lock_contention,
+)
+from matrx_orm.core.write_retry import (
+    run_with_lock_retry,
+)
 
 logger = logging.getLogger("matrx_orm.async_db_manager")
 
@@ -75,24 +83,6 @@ _SCHEMA_MISMATCH_EXC = (
     asyncpg.exceptions.InvalidSchemaNameError,
 )
 
-# Cancelled to break a lock collision. ``TransactionRollbackError`` is an
-# umbrella for every SQLSTATE 40xxx, including 40003 (completion unknown) and
-# 40002 (transaction integrity constraint violation). Only the three explicit
-# statuses below establish that PostgreSQL aborted this statement in full.
-_CONTENTION_EXC = (
-    asyncpg.exceptions.TransactionRollbackError,
-    asyncpg.exceptions.LockNotAvailableError,
-)
-_CONTENTION_SQLSTATES = frozenset({"40P01", "40001", "55P03"})
-
-
-def _is_confidently_aborted_lock_contention(exc: BaseException) -> bool:
-    """Whether ``exc`` proves a standalone statement can be re-issued."""
-    return (
-        isinstance(exc, _CONTENTION_EXC)
-        and getattr(exc, "sqlstate", None) in _CONTENTION_SQLSTATES
-    )
-
 # PostgreSQL emits these SQLSTATE class-57 errors while asyncpg is opening a
 # physical connection during a server restart/failover.  They happen before a
 # checkout exists, so no caller SQL was sent and a replay-safe owner may retry.
@@ -156,11 +146,13 @@ READ_TIMEOUT_RETRY_BACKOFF = 0.25  # seconds before the read retry
 # traffic). On 2026-09-12 that reached a person as the banner
 # "listConversations: deadlock detected" on /chat, and ops.app_log shows the same
 # class crashing POST /coding-sessions/bridge with a 500. Bounded and LOUD: real
-# contention still surfaces, it just costs two extra attempts first.
-# KNOB MIRROR of platform.feature_knob "orm.write_retry" "contention_retries" — the database
-# manager cannot read the database to configure itself; change the row, then re-mirror here.
-CONTENTION_RETRIES = 2  # extra attempts for a cancelled statement; total = 1 + this
-CONTENTION_BACKOFF = 0.06  # seconds before the first re-issue; doubled each time
+# contention still surfaces, it just costs extra attempts first.
+#
+# The budget is NOT a constant here: it is the ``orm.write_retry``
+# ``platform.feature_knob`` rows an admin turns, read by
+# ``matrx_orm.core.write_retry``, which also owns THE ONE retry loop
+# (``run_with_lock_retry``) that this door and the RPC door (``call_function``)
+# both run through. Never grow a second loop or a second budget.
 
 # ── idle-in-transaction ceiling (the platform-wide DDL blocker) ───────────────
 # A session that BEGINs and then goes quiet is the single most expensive thing a
@@ -1330,23 +1322,18 @@ class AsyncDatabaseManager:
 
         read_only = is_read_only_sql(query)
 
-        async with handle_orm_operation(
-            operation_name="execute_query",
-            model=None,
-            config_name=config_name,
-            query=query,
-            args=args,
-            timeout=timeout,
-        ):
+        async def _attempt() -> list[dict[str, Any]]:
+            """One full try of this statement, on its own fresh connection.
+
+            Re-issuing it after a lock collision is NOT decided here: a raw
+            asyncpg contention error escapes unwrapped so THE ONE retry loop
+            (``run_with_lock_retry``, knob-driven) owns that budget for this door
+            and the RPC door alike.
+            """
             # A timed-out READ retries ONCE on a fresh connection (self-heal for
             # a starvation-induced command_timeout). Each iteration re-acquires,
             # so a poisoned connection is never reused. Writes never loop here.
-            # Two independent budgets, each re-acquiring a FRESH connection: a
-            # timed-out read (below) and a statement Postgres cancelled to break
-            # a lock collision (which applies to writes too — the victim is
-            # rolled back in full).
             read_attempt = 0
-            contention_attempt = 0
             while True:
                 async with cls.get_connection(config_name, timeout) as conn:
                     try:
@@ -1358,14 +1345,6 @@ class AsyncDatabaseManager:
                                 read_attempt + 1,
                                 query[:120],
                             )
-                        if contention_attempt > 0:
-                            logger.warning(
-                                "[lock-retry] HEALED on attempt %d after Postgres "
-                                "cancelled the statement to break a lock collision "
-                                "(rolled back, safe to re-run): %s",
-                                contention_attempt + 1,
-                                query[:120],
-                            )
                         if (
                             not results
                             and verify_empty
@@ -1387,36 +1366,19 @@ class AsyncDatabaseManager:
                             if true_rows is not None:
                                 return true_rows
                         return [_normalize_record(r) for r in results]
-                    except _CONTENTION_EXC as e:
-                        if not _is_confidently_aborted_lock_contention(e):
-                            raise
-                        # Rolled back in full → the SAME statement is re-issued
-                        # on a fresh connection, writes included. Jittered so N
-                        # tasks cancelled by ONE collision do not collide again
-                        # in lockstep. Announced every time: a masked contention
-                        # problem is the thing this must never become.
-                        if contention_attempt < CONTENTION_RETRIES:
-                            delay = CONTENTION_BACKOFF * (2**contention_attempt)
-                            delay += random.random() * delay * 0.5
-                            logger.warning(
-                                "[lock-retry] attempt %d/%d cancelled by a lock "
-                                "collision (%s) — re-running in %.3fs: %s",
-                                contention_attempt + 1,
-                                1 + CONTENTION_RETRIES,
-                                getattr(e, "sqlstate", None) or e.__class__.__name__,
-                                delay,
-                                query[:120],
-                            )
-                            await asyncio.sleep(delay)
-                            contention_attempt += 1
-                            continue
-                        raise LockContentionError(
-                            original_error=e,
-                            query=query,
-                            args=args,
-                            config_name=config_name,
-                            attempts=1 + contention_attempt,
-                        ) from None
+                    except _CONTENTION_EXC:
+                        # Rolled back in full (40P01/40001/55P03) → the SAME
+                        # statement is provably safe to re-issue, writes
+                        # included, and ``run_with_lock_retry`` around this
+                        # attempt does it on a FRESH connection with the knob
+                        # budget and full jitter. Raised RAW on purpose: this
+                        # clause exists only to keep the catch-all below from
+                        # wrapping it as UnknownDatabaseError, which is what made
+                        # the class unretryable and cost a live workflow run
+                        # ($0.35, Newsroom Desk, 2026-09-12). An ambiguous
+                        # class-40 status (40002/40003) leaves here the same way
+                        # and the loop declines to retry it.
+                        raise
                     except asyncpg.exceptions.PostgresSyntaxError as e:
                         raise QueryError(
                             model=None,
@@ -1565,6 +1527,21 @@ class AsyncDatabaseManager:
                             original_error=e,
                         ) from e
 
+        # handle_orm_operation stays OUTSIDE the retry loop: it wraps a non-ORM
+        # exception as CacheError, which would hide the raw asyncpg contention
+        # error the loop classifies on.
+        async with handle_orm_operation(
+            operation_name="execute_query",
+            model=None,
+            config_name=config_name,
+            query=query,
+            args=args,
+            timeout=timeout,
+        ):
+            return await run_with_lock_retry(
+                _attempt, config_name=config_name, query=query, args=args
+            )
+
     @classmethod
     async def execute_write(
         cls,
@@ -1573,6 +1550,7 @@ class AsyncDatabaseManager:
         *args: Any,
         timeout: float = 10.0,
         max_retries: int = 2,
+        statement_timeout: float | None = None,
     ) -> list[dict[str, Any]]:
         """Execute a write query, routing through the write queue when enabled.
 
@@ -1604,7 +1582,13 @@ class AsyncDatabaseManager:
             from matrx_orm.core.transaction import get_active_connection
 
             if get_active_connection() is not None:
-                return await cls.execute_query(config_name, query, *args, timeout=timeout)
+                return await cls.execute_query(
+                    config_name,
+                    query,
+                    *args,
+                    timeout=timeout,
+                    statement_timeout=statement_timeout,
+                )
         except ImportError:
             pass
 
@@ -1633,9 +1617,17 @@ class AsyncDatabaseManager:
         if session_context_gucs():
             from matrx_orm.core.transaction import transaction
 
+            config_name = resolve_database_name(config_name)
+
             async def _declared_write() -> list[dict[str, Any]]:
                 async with transaction(config_name):
-                    return await cls.execute_query(config_name, query, *args, timeout=timeout)
+                    return await cls.execute_query(
+                        config_name,
+                        query,
+                        *args,
+                        timeout=timeout,
+                        statement_timeout=statement_timeout,
+                    )
 
             if wq is None:
                 return await _declared_write()
@@ -1652,11 +1644,18 @@ class AsyncDatabaseManager:
         if wq is not None:
             return await wq.submit(
                 lambda: cls._execute_with_retry(
-                    config_name, query, *args, timeout=timeout, max_retries=max_retries
+                    config_name,
+                    query,
+                    *args,
+                    timeout=timeout,
+                    max_retries=max_retries,
+                    statement_timeout=statement_timeout,
                 )
             )
 
-        return await cls.execute_query(config_name, query, *args, timeout=timeout)
+        return await cls.execute_query(
+            config_name, query, *args, timeout=timeout, statement_timeout=statement_timeout
+        )
 
     @classmethod
     async def _execute_with_retry(
@@ -1666,12 +1665,21 @@ class AsyncDatabaseManager:
         *args: Any,
         timeout: float = 10.0,
         max_retries: int = 2,
+        statement_timeout: float | None = None,
     ) -> list[dict[str, Any]]:
         """Execute a query with exponential-backoff retry — write-safe.
 
-        Retries only failures proven to happen before write execution:
-        ``PoolAcquireTimeoutError`` (no connection acquired) and
-        ``ReadOnlyTransactionError`` (PostgreSQL refused the statement).
+        Retries exactly ONE class here — **nothing was sent**:
+        ``PoolAcquireTimeoutError`` (no connection was ever acquired) and
+        ``ReadOnlyTransactionError`` (PostgreSQL refused the statement before
+        executing it). Both leave the database provably untouched.
+
+        The other provably-safe class — **the server rolled it back itself**
+        (SQLSTATE 40P01 / 40001 / 55P03) — is retried ONE LAYER DOWN, inside
+        ``execute_query``, by THE ONE lock-retry loop on the ``orm.write_retry``
+        knob budget (:mod:`matrx_orm.core.write_retry`); it covers reads as well
+        as writes and surfaces as ``LockContentionError`` when spent. This loop
+        must never grow a second budget for it.
 
         Every other transient-looking error is propagated immediately:
 
@@ -1692,18 +1700,29 @@ class AsyncDatabaseManager:
         ``"timeout" in str(exc).lower() or isinstance(exc, ConnectionError)``
         treated all four classes above as "transient" and retried them,
         which silently produced cx_request_pkey / cx_message_pkey
-        duplicate-key errors under burst load. The class of failure is now
-        structurally extinct because retries can only fire when no SQL was
-        sent — see ``PoolAcquireTimeoutError`` for the contract.
+        duplicate-key errors under burst load. That class of failure is now
+        structurally extinct: a retry fires only when no SQL was sent
+        (``PoolAcquireTimeoutError`` — see its docstring for the contract), or,
+        a layer down, when the server states it rolled the statement back.
+        Never on "the error message contains the word timeout".
         """
-        last_exc: BaseException | None = None
         for attempt in range(1 + max_retries):
             try:
-                return await cls.execute_query(config_name, query, *args, timeout=timeout)
+                # A lock collision is NOT retried here: ``execute_query`` already
+                # re-issues the statement on the ONE knob-driven loop
+                # (``run_with_lock_retry``), one layer down and for reads too. A
+                # second budget living here is the duplicate this was reconciled
+                # out of.
+                return await cls.execute_query(
+                    config_name,
+                    query,
+                    *args,
+                    timeout=timeout,
+                    statement_timeout=statement_timeout,
+                )
             except (PoolAcquireTimeoutError, ReadOnlyTransactionError) as exc:
                 if attempt >= max_retries:
                     raise
-                last_exc = exc
                 backoff = 0.5 * (2**attempt)
                 logger.info(
                     "[matrx_orm] Write retry %d/%d for '%s' after %s (backoff %.1fs)",
@@ -1715,9 +1734,10 @@ class AsyncDatabaseManager:
                 )
                 await asyncio.sleep(backoff)
 
-        if last_exc is not None:
-            raise last_exc
-        return []
+        # Unreachable: the handler above re-raises on its last attempt rather than
+        # falling through. Kept explicit so no future edit can turn a spent retry
+        # budget into an empty result that reads as "the UPDATE matched no rows".
+        raise AssertionError("write retry loop fell through without a result")
 
     @classmethod
     async def cleanup(cls):

{matrx_orm-3.1.145 → matrx_orm-3.1.147}/matrx_orm/core/base.py

@@ -658,8 +658,18 @@ class Model(RuntimeMixin, metaclass=ModelMeta):
             )
 
     @classmethod
-    async def create(cls, **kwargs: Any) -> Self:
-        instance = await create.create_instance(model_cls=cls, **kwargs)
+    async def create(cls, *, statement_timeout: float | None = None, **kwargs: Any) -> Self:
+        """INSERT one row.
+
+        ``statement_timeout`` (seconds, keyword-only) overrides the pool's
+        ``command_timeout`` for THIS insert only — the write-side twin of
+        ``QueryBuilder.timeout()``. Use it when the row's size is known to need
+        longer than the pool default; it never widens the pool-acquire timeout
+        and never affects another statement.
+        """
+        instance = await create.create_instance(
+            model_cls=cls, statement_timeout=statement_timeout, **kwargs
+        )
         await StateManager.cache(cls, instance)
         return cast(Self, instance)
 
@@ -980,12 +990,22 @@ class Model(RuntimeMixin, metaclass=ModelMeta):
         filters: dict[str, Any],
         *,
         expected_version: int | None = None,
+        lock_rows_in_pk_order: bool = False,
         **updates: Any,
     ) -> UpdateResult:
         """Bulk-update rows matching filters without fetching them first.
 
         Args:
             filters: Lookup kwargs (same syntax as filter()).
+            lock_rows_in_pk_order: take the row locks ascending by primary key
+                instead of in plan-scan order, by routing the WHERE through
+                ``... IN (SELECT pk ... ORDER BY pk FOR UPDATE)``. Pass it on
+                any multi-row UPDATE that concurrent callers can run over an
+                OVERLAPPING row set — without it the lock order is whatever the
+                plan scans (and heap order moves as the updates themselves
+                rewrite rows), which is how two identical statements deadlock
+                (SQLSTATE 40P01). Needs a single-column primary key. Details
+                and the incident: ``QueryBuilder.lock_rows_in_pk_order``.
             expected_version: opt-in optimistic concurrency — compare-and-swap
                 against the canonical ``version`` column. Requires the filters
                 to address ONE row (every primary-key column present as a plain
@@ -1006,6 +1026,13 @@ class Model(RuntimeMixin, metaclass=ModelMeta):
             print(result.rows_affected)
         """
         if expected_version is not None:
+            if lock_rows_in_pk_order:
+                raise ValueError(
+                    f"{cls.__name__}.update_where(expected_version=..., "
+                    f"lock_rows_in_pk_order=True) is contradictory: a "
+                    f"compare-and-swap already addresses exactly ONE row, so "
+                    f"there is no lock ORDER to fix."
+                )
             missing = [pk for pk in cls._meta.primary_keys if pk not in filters]
             if missing:
                 raise ValueError(
@@ -1016,7 +1043,10 @@ class Model(RuntimeMixin, metaclass=ModelMeta):
             return await update.guarded_update(
                 cls, dict(filters), dict(updates), expected_version=expected_version
             )
-        return await QueryBuilder(cls).filter(**filters).update(**updates)
+        qb = QueryBuilder(cls).filter(**filters)
+        if lock_rows_in_pk_order:
+            qb = qb.lock_rows_in_pk_order()
+        return await qb.update(**updates)
 
     @classmethod
     async def delete_where(cls, *, expected_version: int | None = None, **filters: Any) -> int:

{matrx_orm-3.1.145 → matrx_orm-3.1.147}/matrx_orm/core/db_function.py

@@ -69,7 +69,11 @@ from typing import Any, Literal
 
 from matrx_orm.core.async_db_manager import AsyncDatabaseManager
 from matrx_orm.core.transaction import get_active_connection
-from matrx_orm.exceptions import QueryTimeoutError
+from matrx_orm.core.write_retry import (
+    is_confidently_aborted_lock_contention,
+    run_with_lock_retry,
+)
+from matrx_orm.exceptions import LockContentionError, QueryTimeoutError
 
 __all__ = ["call_function", "call_function_sync", "ArrayArg"]
 
@@ -263,10 +267,33 @@ async def call_function(  # noqa: ASYNC109 — maps onto asyncpg's per-call time
 
     active_conn = get_active_connection()
     if active_conn is not None:
-        return await invoke(active_conn)
+        # Inside a caller's transaction a rollback took the whole block; only the
+        # transaction's owner can redo the unit, so no retry here — the refusal is
+        # typed the same way ``execute_query``'s transaction branch types it.
+        try:
+            return await invoke(active_conn)
+        except Exception as exc:
+            if not is_confidently_aborted_lock_contention(exc):
+                raise
+            raise LockContentionError(
+                original_error=exc,
+                query=sql,
+                args=bound_args,
+                config_name=database,
+                attempts=1,
+                in_transaction=True,
+            ) from None
+
+    async def _attempt() -> Any:
+        async with AsyncDatabaseManager.get_connection(database) as conn:
+            return await invoke(conn)
 
-    async with AsyncDatabaseManager.get_connection(database) as conn:
-        return await invoke(conn)
+    # An RPC reaches Postgres on a RAW connection, bypassing execute_query
+    # entirely, so it needs THE ONE loop explicitly — otherwise a deadlock inside
+    # any SECURITY DEFINER write RPC still costs the caller its request.
+    return await run_with_lock_retry(
+        _attempt, config_name=database, query=sql, args=bound_args
+    )
 
 
 def call_function_sync(