matrx-orm 3.1.36__tar.gz → 3.1.37__tar.gz

{matrx_orm-3.1.36 → matrx_orm-3.1.37}/CLAUDE.md

@@ -116,6 +116,31 @@ the target and those explicitly named cross-schema FK dependencies.
 
 ---
 
+## 🚨 THE IDENTITY CACHE MUST NEVER LIE (read before touching any write path)
+
+`StateManager` keeps a process-local per-model identity cache (default
+SHORT_TERM = **10 minutes**). Cached reads are the default (`use_cache=True`), so
+anything wrong in that cache is served as truth for ten minutes. Three rules, all
+enforced in code:
+
+1. **No downgrades.** A cache entry may only be replaced by a record at least as
+   informed. Instances built from a column SUBSET must call
+   `matrx_orm.state.mark_partial(...)` — `ModelState.cache` evicts them instead
+   of storing them. An undeclared downgrade evicts AND screams.
+2. **Writes refresh or evict — never leave a pre-write copy.** `QueryBuilder.update`
+   refreshes from its own `RETURNING *` rows; `QueryBuilder.delete` evicts the
+   affected PKs (or clears the model when the filter isn't PK-shaped).
+3. **Identity reads are authoritative.** Any read that decides ownership, org
+   attribution, or whether a request may run at all passes `use_cache=False`
+   (`load_by_id(id, use_cache=False)`). Fast is not a reason to guess.
+
+This is not theoretical hygiene. On 2026-07-25 rule 1 was missing: `session/flush.py`
+builds a `{pk + payload}` stub per queued UPDATE and `bulk_update` cached it, so a
+chat conversation read back with `organization_id = None` right after its own
+turn-1 title/`message_count` UPDATE flushed — and aidream stopped the user's next
+turn on a value Postgres had held correctly the entire time. Guards:
+`tests/session/test_cache_no_downgrade.py`.
+
 ## Known issues
 
 - **No CLAUDE.md existed before this commit** — that was the main gap.

{matrx_orm-3.1.36 → matrx_orm-3.1.37}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matrx-orm
-Version: 3.1.36
+Version: 3.1.37
 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.36 → matrx_orm-3.1.37}/matrx_orm/operations/update.py

@@ -64,8 +64,14 @@ async def bulk_update(model_cls: type[Model], objects: Sequence[Model], fields:
                 result = await QueryBuilder(model_cls).filter(**pk_filter).update(**update_data)
                 if result.rows_affected > 0:
                     rows_affected += 1
-
-                    await StateManager.cache(model_cls, obj)
+                    # Do NOT cache `obj` here. It is the CALLER's instance and is
+                    # routinely a partial {pk + payload} stub (see
+                    # session/flush.py), so writing it into the identity cache
+                    # blanked every column the update didn't touch — the
+                    # 2026-07-25 "conversation has no durable organization_id"
+                    # bug. QueryBuilder.update already refreshed the cache from
+                    # the statement's own RETURNING * rows, which is the
+                    # authoritative post-write state.
 
             if debug and (i + 1) % 10 == 0:
                 vcprint(f"Processed {i + 1}/{len(valid_objects)} updates...", color="cyan")

{matrx_orm-3.1.36 → matrx_orm-3.1.37}/matrx_orm/query/builder.py

@@ -765,6 +765,30 @@ class QueryBuilder(Generic[ModelT]):
                 combined[f"exclude__{k}"] = v
         return combined
 
+    def _invalidate_cache_for_filters(self) -> None:
+        """Evict the rows this statement affected from the identity cache.
+
+        Precise when the filter is a plain primary-key match (``pk=`` or
+        ``pk__in=``) — the common case by far. Anything else (multi-column
+        predicate, operator suffix, excludes) means the affected ids are unknown,
+        so the model's cache is cleared. Correctness over warmth.
+        """
+        pks = self.model._meta.primary_keys or ["id"]
+        combined = self._merge_filters_excludes()
+        if len(pks) == 1 and not self.excludes and set(combined) <= {pks[0], f"{pks[0]}__in"}:
+            values = combined.get(pks[0])
+            in_values = combined.get(f"{pks[0]}__in")
+            targets = list(in_values) if isinstance(in_values, (list, tuple, set)) else []
+            if values is not None:
+                targets.append(values)
+            if targets and StateManager.is_registered(self.model):
+                database = self.model.get_database_name()
+                state = StateManager._states[(database, self.model.__name__)]
+                for value in targets:
+                    state.evict_by_id(value)
+                return
+        StateManager.clear_model(self.model)
+
     def _merge_having(self) -> dict[str, Any]:
         combined: dict[str, Any] = {}
         for h in self.having_filters:
@@ -862,11 +886,19 @@ class QueryBuilder(Generic[ModelT]):
             return None
 
     async def update(self, **kwargs: Any) -> UpdateResult:
-        """Update matching records."""
+        """Update matching records.
+
+        The identity cache is refreshed from the statement's own
+        ``RETURNING *`` rows — an UPDATE here used to leave the PRE-write copy
+        cached and readable for the rest of the TTL (SHORT_TERM = 10 min), so a
+        row could be read back with values Postgres no longer held.
+        """
         try:
             if not kwargs:
                 raise ValidationError(model=self.model, reason="No update data provided")
-            return await self._get_executor().update(**kwargs)
+            result = await self._get_executor().update(**kwargs)
+            await StateManager.refresh_from_rows(self.model, result.updated_rows)
+            return result
         except ValidationError:
             raise
         except ORMException as e:
@@ -874,9 +906,19 @@ class QueryBuilder(Generic[ModelT]):
             raise
 
     async def delete(self) -> int:
-        """Delete matching records."""
+        """Delete matching records.
+
+        Evicts the deleted rows from the identity cache — a filtered DELETE used
+        to leave them cached and readable for the rest of the TTL. When the
+        filter isn't a plain primary-key match the affected ids are unknown, so
+        the model's cache is cleared outright: losing warmth for one model is
+        free, serving a deleted row for 10 minutes is not.
+        """
         try:
-            return await self._get_executor().delete()
+            deleted = await self._get_executor().delete()
+            if deleted:
+                self._invalidate_cache_for_filters()
+            return deleted
         except ORMException as e:
             e.enrich(model=self.model, operation="delete", filters=self._merge_filters_excludes())
             raise

{matrx_orm-3.1.36 → matrx_orm-3.1.37}/matrx_orm/state.py

@@ -555,6 +555,59 @@ class StateManager:
                 original_error=e,
             ) from e
 
+    @classmethod
+    async def refresh_from_rows(cls, model_class, rows, *, max_rows: int = 200) -> None:
+        """Write authoritative post-write rows over whatever is cached.
+
+        For write paths that already have the true row in hand (``UPDATE …
+        RETURNING *``). Unlike :meth:`cache_bulk` this OVERWRITES an existing
+        entry — that is the point: a targeted UPDATE otherwise left the pre-write
+        copy cached and readable for the rest of the TTL.
+
+        Above ``max_rows`` the rows are evicted instead of cached, so a mass
+        UPDATE can't flood the cache with rows nobody asked for. Never raises —
+        a cache refresh must not fail the write that already committed.
+        """
+        if not rows or not cls.is_registered(model_class):
+            return
+        database = model_class.get_database_name()
+        state = cls._states[(database, model_class.__name__)]
+        pks = model_class._meta.primary_keys or ["id"]
+        evict_only = len(rows) > max_rows
+        for row in rows:
+            try:
+                if evict_only:
+                    values = [row.get(pk) if isinstance(row, dict) else getattr(row, pk, None) for pk in pks]
+                    if all(v is not None for v in values):
+                        state.evict_by_id(*values)
+                    continue
+                record = row if not isinstance(row, dict) else model_class.from_db_result(row)
+                await state.cache(record)
+            except Exception as exc:  # noqa: BLE001 — never fail a committed write
+                vcprint(
+                    f"[matrx_orm.state] refresh_from_rows skipped one "
+                    f"{model_class.__name__} row ({type(exc).__name__}: {exc})",
+                    color="yellow",
+                )
+
+    @classmethod
+    def clear_model(cls, model_class) -> int:
+        """Drop every cached record for a model. Returns the count dropped.
+
+        The correctness fallback for a write whose affected PKs are unknown
+        (a filtered DELETE). Losing cache warmth for one model is free; serving
+        a deleted row for 10 minutes is not.
+        """
+        if not cls.is_registered(model_class):
+            return 0
+        database = model_class.get_database_name()
+        state = cls._states[(database, model_class.__name__)]
+        dropped = len(state._cache)
+        state._cache.clear()
+        state._cache_times.clear()
+        state._subscriptions.clear()
+        return dropped
+
     @classmethod
     async def remove(cls, model_class, record):
         """Removes a specific record from the cache."""

{matrx_orm-3.1.36 → matrx_orm-3.1.37}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.36"
+version = "3.1.37"
 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" }

{matrx_orm-3.1.36 → matrx_orm-3.1.37}/tests/session/test_cache_no_downgrade.py

@@ -95,3 +95,42 @@ async def test_equally_informed_record_still_replaces():
     assert cached is fresh
     assert cached.title == "Renamed"
     assert cached.organization_id == "org-1"
+
+
+@pytest.mark.asyncio
+async def test_refresh_from_rows_overwrites_a_stale_entry():
+    """A targeted UPDATE has the true post-write row in hand (RETURNING *), so the
+    cache is refreshed with it — cache_bulk's "only if absent" rule would have
+    left the PRE-write copy readable for the rest of the TTL."""
+    state = _state()
+    await state.cache(_full_row())
+
+    from matrx_orm.state import StateManager
+
+    StateManager._states[("test_db", "_Conversation")] = state
+    _Conversation.from_db_result = classmethod(lambda cls, row: cls(**row))
+    try:
+        await StateManager.refresh_from_rows(
+            _Conversation,
+            [{"id": "c1", "organization_id": "org-1", "title": "Renamed", "message_count": 4}],
+        )
+        cached = await state.get(id="c1")
+        assert cached.title == "Renamed"
+        assert cached.organization_id == "org-1"
+    finally:
+        StateManager._states.pop(("test_db", "_Conversation"), None)
+
+
+@pytest.mark.asyncio
+async def test_clear_model_drops_every_entry():
+    state = _state()
+    await state.cache(_full_row())
+
+    from matrx_orm.state import StateManager
+
+    StateManager._states[("test_db", "_Conversation")] = state
+    try:
+        assert StateManager.clear_model(_Conversation) == 1
+        assert await state.get(id="c1") is None
+    finally:
+        StateManager._states.pop(("test_db", "_Conversation"), None)