matrx-orm 3.1.51__tar.gz → 3.1.52__tar.gz

{matrx_orm-3.1.51 → matrx_orm-3.1.52}/BASE_CLASS_METHODS.md

@@ -49,7 +49,7 @@ The following methods are available directly from all manager classes:
 ### CRUD & Bulk
 - `create_item(**data)`
 - `create_items(items_data, batch_size=1000, ignore_conflicts=False)`
-- `update_item(item_id, **updates)`
+- `update_item(item_id, *, expected_version=None, **updates)`
 - `update_item_fields(item_id, **updates)`
 - `update_items(objects, fields, batch_size=1000)`
 - `delete_item(item_id)`
@@ -59,8 +59,27 @@ 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, **updates)`
-- `delete_where(**filters)`
+- `update_where(filters, *, expected_version=None, **updates)`
+- `delete_where(*, expected_version=None, **filters)`
+
+### Optimistic concurrency — `expected_version=`
+
+**Opt-in compare-and-swap on the canonical `version` int column.** Pass
+`expected_version=N` to `update_where` / `update_item` / instance `update()` /
+`delete_where`: the statement gains `WHERE version = N` (updates also
+`SET version = N + 1`). **Single-row paths raise on 0 rows** — updates:
+`DoesNotExist` when the row is gone, `OptimisticLockError` (with
+`current_version` + `current_row`) when it changed; guarded `delete_where`:
+gone → returns 0 (idempotent), changed → `OptimisticLockError`. Guarded
+`update_where`/`delete_where` require every PK column in the filters
+(single-row addressing). **Bulk is different:** `bulk_update(...,
+check_version=True)` guards each row on its loaded `version` but NEVER raises
+to the caller — a conflicting row is logged loudly and excluded from the
+returned count. Omit the parameter → exact legacy last-write-wins.
+`MatrxEntity.update_with_rebase(id, expected_version=N, **fields)` additionally
+auto-rebases past conflicts whose intervening writes were DISJOINT from the
+written fields (proven from `history.row_versions` snapshots). Cross-repo
+contract: `common-docs/systems/optimistic-concurrency/FEATURE.md`.
 
 ### Atomic queue claims
 

{matrx_orm-3.1.51 → matrx_orm-3.1.52}/CLAUDE.md

@@ -23,6 +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`.
 - **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).

{matrx_orm-3.1.51 → matrx_orm-3.1.52}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matrx-orm
-Version: 3.1.51
+Version: 3.1.52
 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.51 → matrx_orm-3.1.52}/matrx_orm/core/base.py

@@ -971,11 +971,24 @@ class Model(RuntimeMixin, metaclass=ModelMeta):
         return run_sync(cls.exists(**kwargs))
 
     @classmethod
-    async def update_where(cls, filters: dict[str, Any], **updates: Any) -> UpdateResult:
+    async def update_where(
+        cls,
+        filters: dict[str, Any],
+        *,
+        expected_version: int | None = None,
+        **updates: Any,
+    ) -> UpdateResult:
         """Bulk-update rows matching filters without fetching them first.
 
         Args:
             filters: Lookup kwargs (same syntax as filter()).
+            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
+                equality). 0 rows then RAISES: DoesNotExist when the row is
+                gone, OptimisticLockError (with ``current_version`` and
+                ``current_row``) when it changed since the declared revision.
+                Omitted → exact legacy behavior (last-write-wins, no raise).
             **updates: Field=value pairs to SET.
 
         Returns:
@@ -988,13 +1001,30 @@ class Model(RuntimeMixin, metaclass=ModelMeta):
             )
             print(result.rows_affected)
         """
+        if expected_version is not None:
+            missing = [pk for pk in cls._meta.primary_keys if pk not in filters]
+            if missing:
+                raise ValueError(
+                    f"{cls.__name__}.update_where(expected_version=...) is a "
+                    f"single-row compare-and-swap: the filters must contain every "
+                    f"primary-key column as a plain equality (missing: {missing})."
+                )
+            return await update.guarded_update(
+                cls, dict(filters), dict(updates), expected_version=expected_version
+            )
         return await QueryBuilder(cls).filter(**filters).update(**updates)
 
     @classmethod
-    async def delete_where(cls, **filters: Any) -> int:
+    async def delete_where(cls, *, expected_version: int | None = None, **filters: Any) -> int:
         """Delete rows matching filters without fetching them first.
 
         Args:
+            expected_version: opt-in optimistic concurrency — only delete if the
+                canonical ``version`` column still matches. Requires every
+                primary-key column in the filters (single-row addressing). Row
+                already gone → returns 0 (idempotent); row present at a
+                different version → OptimisticLockError (someone rewrote what
+                the caller decided to delete). Omitted → legacy behavior.
             **filters: Lookup kwargs (same syntax as filter()).
 
         Returns:
@@ -1003,6 +1033,17 @@ class Model(RuntimeMixin, metaclass=ModelMeta):
         Usage:
             deleted = await MyModel.delete_where(status="expired")
         """
+        if expected_version is not None:
+            missing = [pk for pk in cls._meta.primary_keys if pk not in filters]
+            if missing:
+                raise ValueError(
+                    f"{cls.__name__}.delete_where(expected_version=...) is a "
+                    f"single-row compare-and-swap: the filters must contain every "
+                    f"primary-key column as a plain equality (missing: {missing})."
+                )
+            return await update.guarded_delete(
+                cls, dict(filters), expected_version=expected_version
+            )
         return await QueryBuilder(cls).filter(**filters).delete()
 
     @classmethod
@@ -1191,15 +1232,18 @@ class Model(RuntimeMixin, metaclass=ModelMeta):
         return await cls.create(**data)
 
     @classmethod
-    async def update_item(cls, item_id: Any, **updates: Any) -> Self:
+    async def update_item(
+        cls, item_id: Any, *, expected_version: int | None = None, **updates: Any
+    ) -> Self:
         """Update a row by primary key and return it. Raises DoesNotExist if absent.
 
         Mirrors ``BaseManager.update_item``: SELECT by pk, then UPDATE. When the
         returned instance isn't needed, prefer ``update_where({pk: id}, ...)``
-        (a single statement).
+        (a single statement). ``expected_version`` opts into optimistic
+        concurrency — see :meth:`update`.
         """
         instance = await cls.get(**cls._build_pk_filter(item_id))
-        return await instance.update(**updates)
+        return await instance.update(expected_version=expected_version, **updates)
 
     @classmethod
     async def get_or_create(
@@ -1264,7 +1308,13 @@ class Model(RuntimeMixin, metaclass=ModelMeta):
         return run_sync(cls.upsert(data, conflict_fields, update_fields, on_conflict=on_conflict))
 
     @classmethod
-    def update_where_sync(cls, filters: dict[str, Any], **updates: Any) -> UpdateResult:
+    def update_where_sync(
+        cls,
+        filters: dict[str, Any],
+        *,
+        expected_version: int | None = None,
+        **updates: Any,
+    ) -> UpdateResult:
         """Synchronous twin of update_where(). Sync contexts only."""
         try:
             asyncio.get_running_loop()
@@ -1275,10 +1325,10 @@ class Model(RuntimeMixin, metaclass=ModelMeta):
             if "no running event loop" not in str(e):
                 raise
 
-        return run_sync(cls.update_where(filters, **updates))
+        return run_sync(cls.update_where(filters, expected_version=expected_version, **updates))
 
     @classmethod
-    def delete_where_sync(cls, **filters: Any) -> int:
+    def delete_where_sync(cls, *, expected_version: int | None = None, **filters: Any) -> int:
         """Synchronous twin of delete_where(). Sync contexts only."""
         try:
             asyncio.get_running_loop()
@@ -1289,7 +1339,7 @@ class Model(RuntimeMixin, metaclass=ModelMeta):
             if "no running event loop" not in str(e):
                 raise
 
-        return run_sync(cls.delete_where(**filters))
+        return run_sync(cls.delete_where(expected_version=expected_version, **filters))
 
     @classmethod
     async def all(cls, *, use_cache: bool = True) -> list[Self]:
@@ -1373,9 +1423,15 @@ class Model(RuntimeMixin, metaclass=ModelMeta):
             e.enrich(model=self.__class__, operation="save")
             raise
 
-    async def update(self, **kwargs: Any) -> Self:
+    async def update(self, *, expected_version: int | None = None, **kwargs: Any) -> Self:
         """Update specific fields and save in one operation.
 
+        ``expected_version`` opts into optimistic concurrency: the UPDATE becomes
+        a compare-and-swap on the canonical ``version`` column against the
+        declared base revision, raising OptimisticLockError (with the live row)
+        on a mismatch and DoesNotExist when the row is gone. Omitted → exact
+        legacy behavior.
+
         Returns the same instance with updated fields.
         """
         invalid_fields = [k for k in kwargs if k not in self._fields]
@@ -1394,7 +1450,9 @@ class Model(RuntimeMixin, metaclass=ModelMeta):
             for field, value in kwargs.items():
                 setattr(self, field, value)
 
-            await update.update_instance(self, fields=kwargs.keys())
+            await update.update_instance(
+                self, fields=kwargs.keys(), expected_version=expected_version
+            )
             # Clear ONLY what was actually written. _mark_clean() here would wipe
             # unrelated pending edits: `m.purpose = "x"` (dirty, unsaved) followed by
             # `await m.update(status="y")` would drop `purpose` from _dirty, and the

{matrx_orm-3.1.51 → matrx_orm-3.1.52}/matrx_orm/core/extended.py

@@ -375,7 +375,9 @@ class BaseManager(Generic[ModelT]):
         return initialized_items
 
     @handle_errors
-    async def _update_item(self, item: ModelT, **updates: Any) -> ModelT:
+    async def _update_item(
+        self, item: ModelT, *, expected_version: int | None = None, **updates: Any
+    ) -> ModelT:
         """Update an existing item."""
         if not item:
             raise AppError(
@@ -384,7 +386,7 @@ class BaseManager(Generic[ModelT]):
                 client_visible="The item to update could not be found.",
             )
         updates = self._validate_input_data(updates, partial=True)
-        await item.update(**updates)
+        await item.update(expected_version=expected_version, **updates)
         return await self._initialize_item_runtime(item)
 
     @handle_errors
@@ -613,17 +615,22 @@ class BaseManager(Generic[ModelT]):
                 items_data, batch_size=batch_size, ignore_conflicts=ignore_conflicts
             )
 
-    async def update_item(self, item_id: Any, **updates: Any) -> ModelT:
+    async def update_item(
+        self, item_id: Any, *, expected_version: int | None = None, **updates: Any
+    ) -> ModelT:
         """Update an item by primary key.
 
         Uses ``self._pk_name`` so models whose primary key is NOT named ``id``
         (e.g. ``FileAnalysis`` whose PK is ``file_id``) work correctly.
         Sibling methods like ``update_item_fields`` and ``remove_active_by_id``
         already use this pattern — ``update_item`` was the historical outlier.
+
+        ``expected_version`` opts into optimistic concurrency (compare-and-swap
+        on the canonical ``version`` column) — see ``Model.update``.
         """
         async with self._governed_write():
             item = await self._get_item_or_raise(**self._pk_filter(item_id))
-            return await self._update_item(item, **updates)
+            return await self._update_item(item, expected_version=expected_version, **updates)
 
     async def update_item_fields(self, item_id: Any, **updates: Any) -> int:
         """Update an item by ID via a single ``UPDATE … WHERE id=$1`` statement.

{matrx_orm-3.1.51 → matrx_orm-3.1.52}/matrx_orm/entity.py

@@ -232,3 +232,83 @@ class MatrxEntity(Model):
         # Refresh through the ORM so the short-term cache holds the RESTORED row.
         await cls.get_or_none(id=str(self.id), use_cache=False)
         return int(new_version)
+
+    @classmethod
+    async def update_with_rebase(
+        cls,
+        item_id: Any,
+        *,
+        expected_version: int,
+        max_attempts: int = 3,
+        **updates: Any,
+    ) -> Self:
+        """Optimistically update, auto-rebasing past DISJOINT concurrent writes.
+
+        The platform conflict policy for field-scoped edits: a version conflict
+        where the intervening writes did not touch any of the fields being
+        written here is not a real conflict — rebase onto the head revision and
+        retry. Decided from the version SNAPSHOTS (``history.row_versions``):
+        for each field in ``updates``, compare its value at the caller's base
+        revision against its value at the head revision. Any difference means a
+        genuine overlapping edit → OptimisticLockError propagates (with
+        ``current_version`` + ``current_row`` for the caller's own merge UI).
+
+        Requires the entity to be versioned (snapshots are the evidence);
+        a jsonb column counts as ONE field — no intra-JSON merging.
+        """
+        from matrx_orm.exceptions import OptimisticLockError
+
+        cls._require(
+            "versioning",
+            cls._is_versioned,
+            "update_with_rebase needs version snapshots to prove the concurrent "
+            "writes were disjoint. Use update_item(expected_version=...) and "
+            "handle the conflict yourself.",
+        )
+        token = cls._require_token()
+        log = cls._version_log()
+
+        base_version = int(expected_version)
+        for _ in range(max(1, max_attempts)):
+            try:
+                return await cls.update_item(
+                    item_id, expected_version=base_version, **updates
+                )
+            except OptimisticLockError as exc:
+                head_version = exc.current_version
+                if head_version is None:
+                    raise
+                # Newest snapshot per version (a DELETE reuses the prior version
+                # number, so order by id — the log's own monotonic identity).
+                snapshots = (
+                    await log.filter(
+                        entity_type=token,
+                        row_id=str(item_id),
+                        version__in=[base_version, int(head_version)],
+                    )
+                    .order_by("-id")
+                    .all()
+                )
+                base = next((s for s in snapshots if s.version == base_version), None)
+                head = next((s for s in snapshots if s.version == int(head_version)), None)
+                if base is None or head is None:
+                    raise  # no evidence → never guess; surface the conflict
+                overlapping = [
+                    f
+                    for f in updates
+                    if (base.row_data or {}).get(f) != (head.row_data or {}).get(f)
+                ]
+                if overlapping:
+                    raise  # a field we are writing really changed underneath us
+                base_version = int(head_version)
+        # Retries exhausted under sustained contention — surface the live state.
+        raise OptimisticLockError(
+            model=cls,
+            pk=item_id,
+            expected_version=base_version,
+            message=(
+                f"update_with_rebase gave up after {max_attempts} attempts on "
+                f"{cls.__name__} {item_id} — sustained concurrent writes. "
+                f"Re-fetch and retry."
+            ),
+        )

{matrx_orm-3.1.51 → matrx_orm-3.1.52}/matrx_orm/exceptions.py

@@ -1912,17 +1912,30 @@ class OptimisticLockError(ORMException):
         pk=None,
         expected_version: int | None = None,
         message: str | None = None,
+        current_version: int | None = None,
+        current_row=None,
     ) -> None:
         msg = message or (
             f"Optimistic lock conflict on {getattr(model, '__name__', model)} "
-            f"(pk={pk}, expected version={expected_version}). "
-            "The record was modified by another process — re-fetch and retry."
+            f"(pk={pk}, expected version={expected_version}"
+            + (f", current version={current_version}" if current_version is not None else "")
+            + "). The record was modified by another process — re-fetch and retry."
         )
         super().__init__(
             message=msg,
             model=model,
-            details={"pk": pk, "expected_version": expected_version},
+            details={
+                "pk": pk,
+                "expected_version": expected_version,
+                "current_version": current_version,
+            },
         )
+        self.expected_version = expected_version
+        self.current_version = current_version
+        # The live row as re-read at conflict time (a Model instance), so the
+        # caller can merge/rebase without a second fetch. May be None when the
+        # raiser could not re-read.
+        self.current_row = current_row
 
 
 class WriteQueueFullError(DatabaseError):

{matrx_orm-3.1.51 → matrx_orm-3.1.52}/matrx_orm/operations/update.py

@@ -22,14 +22,124 @@ async def update(model_cls: type[Model], filters: dict[str, Any], **kwargs: Any)
     return await QueryBuilder(model_cls).filter(**filters).update(**kwargs)
 
 
-async def bulk_update(model_cls: type[Model], objects: Sequence[Model], fields: list[str]) -> int:
+# The canonical revision column of the platform entity contract. `platform._touch_row`
+# bumps it on every UPDATE; optimistic concurrency compares-and-swaps against it.
+VERSION_COLUMN = "version"
+
+
+def _require_version_column(model_cls: type[Model], version_column: str) -> None:
+    if version_column not in model_cls._fields:
+        raise ValueError(
+            f"{model_cls.__name__} has no '{version_column}' column — optimistic "
+            f"concurrency (expected_version=) requires the canonical integer "
+            f"version column maintained by platform._touch_row. Either the table "
+            f"is not a canonical entity, or the model is stale (rerun generation)."
+        )
+
+
+async def _raise_stale_write(
+    model_cls: type[Model],
+    pk_filter: dict[str, Any],
+    version_column: str,
+    expected_version: int | 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.
+    """
+    from matrx_orm.exceptions import DoesNotExist, OptimisticLockError
+
+    # 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,
+    )
+
+
+async def guarded_update(
+    model_cls: type[Model],
+    filters: dict[str, Any],
+    update_data: dict[str, Any],
+    *,
+    expected_version: int,
+    version_column: str = VERSION_COLUMN,
+) -> UpdateResult:
+    """Compare-and-swap UPDATE: WHERE <filters> AND version = expected_version.
+
+    ``filters`` must address one row (every primary-key column as a plain
+    equality; extra narrowing filters are allowed). The version column is also
+    SET to expected_version + 1 so the CAS observes GUARDED writes on tables
+    without the `_touch_row` trigger; where the trigger exists it recomputes
+    the same value (OLD.version + 1) and wins — identical result. NOTE: on
+    trigger-less tables the CAS is sound only among writers that bump the
+    version column — an unguarded UPDATE that leaves `version` untouched is
+    invisible to it. Every content-write path on such a table must bump
+    (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
+    narrowing filter that stopped matching still classifies as a conflict.
+    """
+    _require_version_column(model_cls, version_column)
+    data = dict(update_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)
+    return result
+
+
+async def bulk_update(
+    model_cls: type[Model],
+    objects: Sequence[Model],
+    fields: list[str],
+    *,
+    check_version: bool = False,
+) -> int:
     """
     Enhanced bulk_update that works within the current ORM limitations.
     Uses controlled batch processing for individual per-row updates.
+
+    ``check_version=True`` turns each row's write into a compare-and-swap on the
+    canonical ``version`` column, using the version each instance was LOADED
+    with. Rows whose stored version moved are counted as failures (reported
+    loudly in the summary), never silently overwritten and never raised to the
+    caller — compare the returned count to ``len(objects)`` to detect losses.
+    Every instance must carry a loaded ``version`` value; a batch containing a
+    version-less stub raises ValueError BEFORE any row is written.
     """
     if not objects or not fields:
         return 0
 
+    if check_version:
+        _require_version_column(model_cls, VERSION_COLUMN)
+        stubs = [
+            obj for obj in objects if getattr(obj, VERSION_COLUMN, None) is None
+        ]
+        if stubs:
+            raise ValueError(
+                f"bulk_update(check_version=True) on {model_cls.__name__}: "
+                f"{len(stubs)} instance(s) have no loaded '{VERSION_COLUMN}' "
+                f"(partial stubs?). Load rows with their version, or drop the "
+                f"guard. No rows were written."
+            )
+
     invalid_fields = [k for k in fields if k not in model_cls._fields]
     if invalid_fields:
         vcprint(model_cls._fields, "Model Fields", color="yellow")
@@ -60,8 +170,21 @@ async def bulk_update(model_cls: type[Model], objects: Sequence[Model], fields:
                     if value is not None:
                         update_data[field_name] = field.get_db_prep_value(value)
 
+            row_filter = dict(pk_filter)
+            if check_version:
+                base_version = int(getattr(obj, VERSION_COLUMN))
+                row_filter[VERSION_COLUMN] = base_version
+                # Unconditional: even if 'version' is in `fields`, the guarded
+                # write owns the bump — keeping a caller-supplied base value
+                # would let a same-base CAS keep passing on trigger-less tables.
+                update_data[VERSION_COLUMN] = base_version + 1
+
             if update_data:
-                result = await QueryBuilder(model_cls).filter(**pk_filter).update(**update_data)
+                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)
+                    )
                 if result.rows_affected > 0:
                     rows_affected += 1
                     # Do NOT cache `obj` here. It is the CALLER's instance and is
@@ -133,10 +256,52 @@ async def decrement(model_cls: type[Model], filters: dict[str, Any], **kwargs: A
     return await update(model_cls, filters, **updates)
 
 
-async def update_instance(instance: Model, fields: Iterable[str] | None = None) -> Model:
-    from matrx_orm.core.signals import post_save, pre_save
+async def guarded_delete(
+    model_cls: type[Model],
+    filters: dict[str, Any],
+    *,
+    expected_version: int,
+    version_column: str = VERSION_COLUMN,
+) -> int:
+    """Compare-and-swap DELETE: WHERE <filters> AND version = expected_version.
+
+    ``filters`` must address one row (every primary-key column as a plain
+    equality). 0 rows deleted: row already gone → returns 0 (a delete is
+    idempotent — the desired end state holds); row present with a different
+    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)
+        .filter(**{**filters, version_column: expected_version})
+        .delete()
+    )
+    if deleted == 0:
+        pk_filter = {pk: filters[pk] for pk in model_cls._meta.primary_keys}
+        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,
+            )
+    return deleted
+
+
+async def update_instance(
+    instance: Model,
+    fields: Iterable[str] | None = None,
+    *,
+    expected_version: int | None = None,
+) -> Model:
+    from matrx_orm.core.signals import post_save, pre_save
+
     model_cls = instance.__class__
     await pre_save.send(model_cls, instance=instance)
 
@@ -163,6 +328,16 @@ async def update_instance(instance: Model, fields: Iterable[str] | None = None)
             current_version = getattr(instance, fname, None)
             break
 
+    # Explicit caller-declared base revision (the platform optimistic-concurrency
+    # contract). Targets the canonical `version` column unless the model declares
+    # a VersionField under another name; the explicit value always wins over the
+    # instance's in-memory copy.
+    if expected_version is not None:
+        if version_field_name is None:
+            _require_version_column(model_cls, VERSION_COLUMN)
+            version_field_name = VERSION_COLUMN
+        current_version = expected_version
+
     update_data: dict[str, Any] = {}
     field_names: Iterable[str] = (
         fields if fields is not None else [f for f in model_cls._fields if f not in pk_filter]
@@ -201,12 +376,9 @@ async def update_instance(instance: Model, fields: Iterable[str] | None = None)
     result = await update(model_cls, filters, **update_data)
 
     if result.rows_affected == 0:
-        if version_field_name is not None:
-            raise OptimisticLockError(
-                model=model_cls,
-                pk=pk_filter if len(pk_filter) > 1 else next(iter(pk_filter.values())),
-                expected_version=current_version,
-            )
+        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)
         raise ValueError(f"No rows were updated for {model_cls.__name__} with {pk_filter}")
 
     if result.updated_rows:

{matrx_orm-3.1.51 → matrx_orm-3.1.52}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.51"
+version = "3.1.52"
 description = "Async-first PostgreSQL ORM with bidirectional migrations, schema introspection, many-to-many relationships, and built-in state caching"
 readme = "README.md"
 license = { text = "MIT" }