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

{matrx_orm-3.1.74 → matrx_orm-3.1.76}/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.74 → matrx_orm-3.1.76}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matrx-orm
-Version: 3.1.74
+Version: 3.1.76
 Summary: Async-first PostgreSQL ORM with bidirectional migrations, schema introspection, many-to-many relationships, and built-in state caching
 Project-URL: Homepage, https://github.com/AI-Matrix-Engine/aidream-current
 Project-URL: Repository, https://github.com/AI-Matrix-Engine/aidream-current
@@ -25,7 +25,7 @@ Requires-Python: >=3.13
 Requires-Dist: asyncpg>=0.31.0
 Requires-Dist: cryptography>=43.0
 Requires-Dist: gitpython>=3.1.40
-Requires-Dist: matrx-utils>=2.0.15
+Requires-Dist: matrx-utils>=2.0.17
 Requires-Dist: psycopg-pool>=3.2.5
 Requires-Dist: psycopg[binary]>=3.2.5
 Requires-Dist: python-dotenv>=1.0

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

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

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

@@ -37,10 +37,12 @@ TWO INDEPENDENT LAYERS, each sufficient alone, each screaming when it fires:
 
 2. **Reconciliation — an empty read is re-proved on a session that can prove its
    role.** A zero-row result from a read-only query on a transaction-pool config
-   is re-run inside an explicit transaction (pinned to ONE server connection)
-   that starts with ``RESET ROLE``. If the rows are really there, the caller gets
-   the TRUE rows and the lie is reported through every registered sink. If the
-   session cannot be made clean, it RAISES rather than handing back an absence.
+   is re-run inside an explicit transaction (pinned to ONE server connection).
+   The pinned session's identity is captured before and after resetting session
+   authorization and role. The caller gets any rows that appeared, but a
+   contamination alarm is emitted only when the role change was directly
+   observed. If the session cannot be made clean, it RAISES rather than handing
+   back an absence.
 
 Layer 2 follows the repo's guard doctrine: a guard that CAN reconcile MUST
 reconcile — we hold the correct answer, so killing the caller's request would be
@@ -98,7 +100,7 @@ class PoolerRoleContamination(RuntimeError):
 
 
 class EmptyReadContaminationEvent(BaseModel):
-    """A read returned zero rows because the session was wearing a borrowed role."""
+    """An empty-read reproof directly observed and repaired a borrowed role."""
 
     model_config = ConfigDict(extra="forbid", frozen=True)
 
@@ -166,14 +168,14 @@ def assert_no_session_role_change(query: str) -> None:
 
 
 async def emit_contamination(event: EmptyReadContaminationEvent) -> None:
-    """Scream about a proven silent-empty read, durably record it, fan out to sinks."""
+    """Scream about a directly observed borrowed role and fan out to sinks."""
     vcprint(
-        "POOLER ROLE CONTAMINATION — an ORM read returned ZERO ROWS that were "
-        "really there.\n"
+        "POOLER ROLE CONTAMINATION — an empty-read reproof directly observed "
+        "and repaired a borrowed server role.\n"
         f"  config: {event.config_name}\n"
-        f"  session ran as: {event.contaminated_role} (login role "
+        f"  pooled session was: {event.contaminated_role} (clean login role "
         f"{event.login_role})\n"
-        f"  true row count on a clean session: {event.true_row_count}\n"
+        f"  cleaned query row count: {event.true_row_count}\n"
         f"  query: {event.query[:300]}\n"
         "  The caller has been given the TRUE rows. Something on this Postgres "
         "tenant issued a non-LOCAL SET ROLE; every other client is exposed until "
@@ -182,7 +184,7 @@ async def emit_contamination(event: EmptyReadContaminationEvent) -> None:
         style="bold",
     )
     logger.error(
-        "[pooler-role] silent empty read repaired on %s (ran as %s, %d true rows): %s",
+        "[pooler-role] borrowed pooled role repaired on %s (observed %s, %d clean rows): %s",
         event.config_name,
         event.contaminated_role,
         event.true_row_count,
@@ -195,8 +197,9 @@ async def emit_contamination(event: EmptyReadContaminationEvent) -> None:
 
         await record_error(
             PoolerRoleContamination(
-                f"read returned 0 rows as '{event.contaminated_role}'; "
-                f"{event.true_row_count} rows were really there"
+                f"reproof observed pooled role '{event.contaminated_role}' "
+                f"(login role '{event.login_role}'); cleaned read returned "
+                f"{event.true_row_count} rows"
             ),
             kind="pooler_role_contamination",
             source_app="matrx-orm",
@@ -241,10 +244,18 @@ async def reprove_empty_read(
     last_role: tuple[str, str] | None = None
     for _ in range(REPROVE_ATTEMPTS):
         async with conn.transaction():
+            before = await conn.fetchrow("SELECT current_user, session_user")
+            before_current = before["current_user"]
+            before_session = before["session_user"]
+
+            # RESET ROLE alone cannot repair SET SESSION AUTHORIZATION: in that
+            # state current_user and session_user can agree on the WRONG identity.
+            # Reset both while this transaction pins the exact server connection.
+            await conn.execute("RESET SESSION AUTHORIZATION")
             await conn.execute("RESET ROLE")
-            identity = await conn.fetchrow("SELECT current_user, session_user")
-            current = identity["current_user"]
-            login = identity["session_user"]
+            after = await conn.fetchrow("SELECT current_user, session_user")
+            current = after["current_user"]
+            login = after["session_user"]
             if current != login:
                 last_role = (current, login)
                 continue
@@ -253,18 +264,24 @@ async def reprove_empty_read(
                 return None
             true_rows = [normalize(r) for r in rows]
 
-        await emit_contamination(
-            EmptyReadContaminationEvent(
-                config_name=config_name,
-                query=query,
-                # The first read ran on a session we could not observe directly;
-                # what we can state is the role it was NOT running as.
-                contaminated_role="<not the login role>" if last_role is None else last_role[0],
-                login_role=login,
-                true_row_count=len(true_rows),
-                occurred_at=datetime.now(UTC),
+            observed_contamination = (before_current, before_session) != (current, login)
+
+        # Rows may legitimately appear between two READ COMMITTED statements.
+        # guest_executions is the canonical example: concurrent first requests
+        # for one fingerprint race a lookup against creation. Empty -> non-empty
+        # is reconciliation, not proof of pool contamination. Only the captured
+        # before/after identity change can put this class in the repair queue.
+        if observed_contamination:
+            await emit_contamination(
+                EmptyReadContaminationEvent(
+                    config_name=config_name,
+                    query=query,
+                    contaminated_role=before_current,
+                    login_role=login,
+                    true_row_count=len(true_rows),
+                    occurred_at=datetime.now(UTC),
+                )
             )
-        )
         return true_rows
 
     current, login = last_role if last_role is not None else ("<unknown>", "<unknown>")

{matrx_orm-3.1.74 → matrx_orm-3.1.76}/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

{matrx_orm-3.1.74 → matrx_orm-3.1.76}/matrx_orm/operations/update.py

@@ -37,36 +37,129 @@ def _require_version_column(model_cls: type[Model], version_column: str) -> None
         )
 
 
+def _contested_values(
+    model_cls: type[Model],
+    current: Model,
+    attempted_fields: Iterable[str] | None,
+    version_column: str,
+) -> dict[str, Any] | None:
+    """The CURRENT values of just the fields the losing write attempted.
+
+    Only the contested fields — never a dump of the whole row (a conflict body
+    is not a read endpoint, and the row may carry columns the caller is not
+    entitled to see). The version column and any primary key are excluded: the
+    revisions travel as their own fields and the pk was never in contest.
+    """
+    if not attempted_fields:
+        return None
+    pks = set(model_cls._meta.primary_keys or [])
+    return {
+        name: getattr(current, name, None)
+        for name in attempted_fields
+        if name != version_column and name not in pks and name in model_cls._fields
+    }
+
+
+async def _conflict_actor(
+    model_cls: type[Model],
+    pk_filter: dict[str, Any],
+    current_version: int | None,
+) -> tuple[Any, Any]:
+    """(changed_by, changed_at) for the winning revision, from history.row_versions.
+
+    Best-effort by construction: absent (None, None) on an unversioned entity, a
+    composite-PK table (the version log keys on a single ``row_id``), a missing
+    snapshot, or any failure reading the log. A conflict must NEVER be turned
+    into a different error because the courtesy lookup did not work out.
+    """
+    from matrx_orm.entity import MatrxEntity
+
+    if not isinstance(model_cls, type) or not issubclass(model_cls, MatrxEntity):
+        return (None, None)
+    if not (model_cls._is_versioned and model_cls._entity_token) or current_version is None:
+        return (None, None)
+    if len(pk_filter) != 1:
+        return (None, None)
+    row_id = next(iter(pk_filter.values()))
+    try:
+        log = model_cls._version_log()
+        snapshots = (
+            await log.filter(
+                entity_type=model_cls._entity_token,
+                row_id=str(row_id),
+                version=int(current_version),
+            )
+            .order_by("-id")
+            .limit(1)
+            .all()
+        )
+    except Exception as exc:
+        vcprint(
+            f"[matrx-orm] conflict actor lookup failed for {model_cls.__name__} "
+            f"{row_id} v{current_version} ({type(exc).__name__}: {exc}) — the "
+            f"conflict still carries its versions and contested fields.",
+            color="yellow",
+            log_level="WARNING",
+        )
+        return (None, None)
+    if not snapshots:
+        return (None, None)
+    snapshot = snapshots[0]
+    return (getattr(snapshot, "actor_id", None), getattr(snapshot, "occurred_at", None))
+
+
+async def _build_conflict(
+    model_cls: type[Model],
+    pk_filter: dict[str, Any],
+    version_column: str,
+    expected_version: int | None,
+    current: Model,
+    attempted_fields: Iterable[str] | None,
+) -> Any:
+    """Assemble the full decision package for a lost compare-and-swap."""
+    from matrx_orm.exceptions import OptimisticLockError
+
+    current_version = getattr(current, version_column, None)
+    changed_by, changed_at = await _conflict_actor(model_cls, pk_filter, current_version)
+    return OptimisticLockError(
+        model=model_cls,
+        pk=pk_filter if len(pk_filter) > 1 else next(iter(pk_filter.values())),
+        expected_version=expected_version,
+        current_version=current_version,
+        current_row=current,
+        contested_fields=_contested_values(model_cls, current, attempted_fields, version_column),
+        changed_by=changed_by,
+        changed_at=changed_at,
+    )
+
+
 async def _raise_stale_write(
     model_cls: type[Model],
     pk_filter: dict[str, Any],
     version_column: str,
     expected_version: int | None,
+    attempted_fields: Iterable[str] | None = None,
 ) -> None:
     """Classify a guarded UPDATE that hit 0 rows: gone vs. changed.
 
     Re-reads by primary key alone (no version filter, no cache). Row absent →
     DoesNotExist (deleted concurrently, or never existed). Row present → its
-    version no longer matches → OptimisticLockError carrying the live row.
+    version no longer matches → OptimisticLockError carrying the live row and
+    the decision package (contested field values + who changed it, when).
     """
-    from matrx_orm.exceptions import DoesNotExist, OptimisticLockError
+    from matrx_orm.exceptions import DoesNotExist
 
     # Note: inside an open Session the re-read merges PENDING (uncommitted)
     # writes for this row — a CAS should run on the direct write paths, not
     # Coordinator-adjacent code (see the contract's session-plane exclusion).
     current = await QueryBuilder(model_cls).filter(**pk_filter).get_or_none()
-    pk_value = pk_filter if len(pk_filter) > 1 else next(iter(pk_filter.values()))
     if current is None or getattr(current, "deleted_at", None) is not None:
         # Hard-gone or soft-deleted: for conflict classification a soft-deleted
         # row IS gone — reporting it as "changed by someone else, refresh and
         # re-apply" would send the user chasing a record that no longer exists.
         raise DoesNotExist(model=model_cls, filters=pk_filter)
-    raise OptimisticLockError(
-        model=model_cls,
-        pk=pk_value,
-        expected_version=expected_version,
-        current_version=getattr(current, version_column, None),
-        current_row=current,
+    raise await _build_conflict(
+        model_cls, pk_filter, version_column, expected_version, current, attempted_fields
     )
 
 
@@ -91,17 +184,21 @@ async def guarded_update(
     (e.g. `version=F("version") + 1`), as matrx-graph's DefinitionStore does.
 
     0 rows affected raises: DoesNotExist when the row is gone,
-    OptimisticLockError (with current_version + current_row) when it changed.
-    The gone-vs-changed re-read uses the PRIMARY-KEY columns only, so an extra
+    OptimisticLockError (with current_version, current_row, the contested
+    fields' current values and who changed them) when it changed. The
+    gone-vs-changed re-read uses the PRIMARY-KEY columns only, so an extra
     narrowing filter that stopped matching still classifies as a conflict.
     """
     _require_version_column(model_cls, version_column)
     data = dict(update_data)
+    attempted_fields = list(data)
     data.setdefault(version_column, expected_version + 1)
     result = await update(model_cls, {**filters, version_column: expected_version}, **data)
     if result.rows_affected == 0:
         pk_filter = {pk: filters[pk] for pk in model_cls._meta.primary_keys}
-        await _raise_stale_write(model_cls, pk_filter, version_column, expected_version)
+        await _raise_stale_write(
+            model_cls, pk_filter, version_column, expected_version, attempted_fields
+        )
     return result
 
 
@@ -183,7 +280,11 @@ async def bulk_update(
                 result = await QueryBuilder(model_cls).filter(**row_filter).update(**update_data)
                 if check_version and result.rows_affected == 0:
                     await _raise_stale_write(
-                        model_cls, pk_filter, VERSION_COLUMN, getattr(obj, VERSION_COLUMN, None)
+                        model_cls,
+                        pk_filter,
+                        VERSION_COLUMN,
+                        getattr(obj, VERSION_COLUMN, None),
+                        fields,
                     )
                 if result.rows_affected > 0:
                     rows_affected += 1
@@ -271,8 +372,6 @@ async def guarded_delete(
     version → OptimisticLockError (someone rewrote what the caller decided to
     delete; deleting it anyway would discard their work unseen).
     """
-    from matrx_orm.exceptions import OptimisticLockError
-
     _require_version_column(model_cls, version_column)
     deleted = (
         await QueryBuilder(model_cls)
@@ -284,12 +383,10 @@ async def guarded_delete(
         current = await QueryBuilder(model_cls).filter(**pk_filter).get_or_none()
         # Soft-deleted counts as already gone — idempotent 0, not a conflict.
         if current is not None and getattr(current, "deleted_at", None) is None:
-            raise OptimisticLockError(
-                model=model_cls,
-                pk=pk_filter if len(pk_filter) > 1 else next(iter(pk_filter.values())),
-                expected_version=expected_version,
-                current_version=getattr(current, version_column, None),
-                current_row=current,
+            # A delete contests no individual field (it contests the whole row),
+            # so contested_fields stays absent; the actor half still applies.
+            raise await _build_conflict(
+                model_cls, pk_filter, version_column, expected_version, current, None
             )
     return deleted
 
@@ -377,8 +474,16 @@ async def update_instance(
 
     if result.rows_affected == 0:
         if version_field_name is not None and current_version is not None:
-            # Guarded write: classify gone-vs-changed and raise accordingly.
-            await _raise_stale_write(model_cls, pk_filter, version_field_name, current_version)
+            # Guarded write: classify gone-vs-changed and raise accordingly. The
+            # contested fields are exactly what this write attempted, minus the
+            # version bump the guard itself added.
+            await _raise_stale_write(
+                model_cls,
+                pk_filter,
+                version_field_name,
+                current_version,
+                [f for f in update_data if f != version_field_name],
+            )
         raise ValueError(f"No rows were updated for {model_cls.__name__} with {pk_filter}")
 
     if result.updated_rows:

{matrx_orm-3.1.74 → matrx_orm-3.1.76}/matrx_orm/schema_builder/package_wiring.py

@@ -329,8 +329,7 @@ _HEADER = '''\
 # because it imports db.models.* / db.managers.* — forbidden inside packages/.
 """AUTO-GENERATED host->package DB wiring. Do not edit."""
 
-from __future__ import annotations
-'''
+from __future__ import annotations'''
 
 
 def _bucket_order(bucket: str) -> int:
@@ -360,6 +359,10 @@ def render_wiring_module(output_module: str, packages: list[ResolvedPackage]) ->
         for (module, symbol), local in sorted(local_for.items(), key=lambda kv: int(kv[1][2:])):
             lines.append(f"    from {module} import {symbol} as {local}")
         lines.append(f"    import {pkg.configure_import} as _target")
+        # Blank line after the import block: keeps the emitted file byte-identical
+        # to `ruff format` output, so the wiring drift gate and the formatter can
+        # never fight over this file.
+        lines.append("")
 
         # Build the kwargs.
         buckets: dict[str, list[Assignment]] = {}

{matrx_orm-3.1.74 → matrx_orm-3.1.76}/matrx_orm/session/README.md

@@ -110,7 +110,12 @@ and:
 2. Registers a `WatchedLifecycleConfig` with `WatchedLifecycleRegistry`.
 
 The sweeper (started by the host app at startup) iterates the registry
-on its periodic tick.
+on its periodic tick. A watchdog that automatically transitions rows reports
+every sweep in which it finds work. An alert-only watchdog reports immediately,
+again whenever its stuck-row count changes, after recovery if the condition
+returns, and once per hour while an unchanged condition persists. This keeps a
+durable operational problem visible without emitting the same ERROR every
+minute forever.
 
 ## Pending-aware reads