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

{matrx_orm-3.1.35 → 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.35 → matrx_orm-3.1.37}/PKG-INFO

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

@@ -1155,24 +1155,30 @@ class Model(RuntimeMixin, metaclass=ModelMeta):
         return pks[0]
 
     @classmethod
-    async def load_by_id(cls, item_id: Any) -> Self:
+    async def load_by_id(cls, item_id: Any, use_cache: bool = True) -> Self:
         """Load a row by its primary key. Raises DoesNotExist if absent.
 
         Alias for ``get(**{pk: item_id})`` — mirrors ``BaseManager.load_by_id``.
         Composite-PK models accept a dict ``{pk: val}`` or a PK-ordered
         tuple/list (a bare scalar raises — see ``_build_pk_filter``).
         For a None-returning lookup use :meth:`load_by_id_or_none`.
+
+        ``use_cache=False`` is the AUTHORITATIVE read: pass it whenever the row
+        decides identity, ownership, or whether the request may run at all. It
+        also refreshes the cache with what it read, so a bypass never leaves a
+        stale entry behind.
         """
-        return await cls.get(**cls._build_pk_filter(item_id))
+        return await cls.get(use_cache=use_cache, **cls._build_pk_filter(item_id))
 
     @classmethod
-    async def load_by_id_or_none(cls, item_id: Any) -> Self | None:
+    async def load_by_id_or_none(cls, item_id: Any, use_cache: bool = True) -> Self | None:
         """Load a row by its primary key, or None if absent.
 
         Alias for ``get_or_none(**{pk: item_id})``. Composite-PK models accept
-        a dict / PK-ordered tuple, same as :meth:`load_by_id`.
+        a dict / PK-ordered tuple, same as :meth:`load_by_id`. See
+        :meth:`load_by_id` for when to pass ``use_cache=False``.
         """
-        return await cls.get_or_none(**cls._build_pk_filter(item_id))
+        return await cls.get_or_none(use_cache=use_cache, **cls._build_pk_filter(item_id))
 
     @classmethod
     async def filter_items(cls, *args: Any, **kwargs: Any) -> list[Self]:

{matrx_orm-3.1.35 → 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.35 → 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.35 → matrx_orm-3.1.37}/matrx_orm/session/README.md

@@ -134,6 +134,24 @@ Complex predicates (operator suffixes, JSON paths, joins) only match
 DB rows — the pending state is assumed safe (the DB still applies the
 predicate on its side).
 
+## 🚨 Flush stubs are PARTIAL — they never enter the identity cache
+
+`flush._execute_group` turns each queued UPDATE into a lightweight
+`model_cls(**{pk, **payload})` instance so `bulk_update` can build per-row SQL.
+That instance is **not a row snapshot**: every column outside the payload holds a
+model default (usually `None`). Each one is therefore stamped by
+`matrx_orm.state.mark_partial(...)`, and `ModelState.cache` **evicts** instead of
+storing any partial — the next read refetches the whole row.
+
+This is load-bearing, not hygiene. `bulk_update` write-through used to install
+those stubs as the row's cache entry, so for the whole cache TTL (SHORT_TERM = 10
+min) a freshly-updated row read back with NULLs in every untouched column. On
+2026-07-25 that made a saved conversation read back with no `organization_id`
+seconds after its own turn-1 title/`message_count` UPDATE flushed, and aidream's
+identity guard hard-stopped the next turn. Any new code path that builds a model
+instance from a column subset MUST call `mark_partial` — an undeclared downgrade
+is evicted anyway and SCREAMS (see `state._scream_downgrade`).
+
 ## Nested Sessions
 
 Sub-agents, parallel-execute branches, workflow super-steps — every

{matrx_orm-3.1.35 → matrx_orm-3.1.37}/matrx_orm/session/flush.py

@@ -29,6 +29,7 @@ from collections.abc import Sequence
 from contextvars import ContextVar
 
 from matrx_orm.session.op import SessionOp
+from matrx_orm.state import mark_partial
 
 logger = logging.getLogger("matrx_orm.session.flush")
 
@@ -122,7 +123,13 @@ async def _execute_group(
         for op in ops:
             kwargs = {pk_field: op.pk_value}
             kwargs.update(op.payload)
-            instances.append(model_cls(**kwargs))
+            # These are stubs, NOT row snapshots: every column outside `kwargs`
+            # is a model default (None), not the row's value. Declare that, or
+            # bulk_update's write-through would install one as the row's cache
+            # entry and blank every other column for the TTL (this is the bug
+            # that made a saved conversation read back with no organization_id
+            # on its next turn). See matrx_orm.state.mark_partial.
+            instances.append(mark_partial(model_cls(**kwargs), kwargs))
 
         await model_cls.bulk_update(instances, fields=all_fields)
         return len(instances)
@@ -132,7 +139,9 @@ async def _execute_group(
         pks = getattr(meta, "primary_keys", None) if meta else None
         pk_field = pks[0] if pks else ops[0].pk_field
 
-        instances = [model_cls(**{pk_field: op.pk_value}) for op in ops]
+        instances = [
+            mark_partial(model_cls(**{pk_field: op.pk_value}), (pk_field,)) for op in ops
+        ]
         await model_cls.bulk_delete(instances)
         return len(instances)
 

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

@@ -15,6 +15,48 @@ from matrx_orm.exceptions import (
 )
 
 
+# Attribute a write-through instance sets to declare "I am a {pk + payload}
+# stub, not a row snapshot". Set by matrx_orm.session.flush; honored by
+# ModelState.cache (evict, never store) and by mark_partial() below.
+PARTIAL_FIELDS_ATTR = "_matrx_partial_fields"
+
+# One scream per (model, blanked-field-set) — a downgrade is a code defect, so
+# it must be visible, but it must not drown a hot loop in identical banners.
+_SCREAMED_DOWNGRADES: set[tuple[str, tuple[str, ...]]] = set()
+
+
+def mark_partial(instance, fields):
+    """Declare ``instance`` a partial write-through stub of its row.
+
+    Every caller that builds a model instance from a PK plus a subset of
+    columns (session flush, targeted bulk_update) MUST call this. Undeclared
+    partials trip the no-downgrade scream in :meth:`ModelState.cache`.
+    """
+    setattr(instance, PARTIAL_FIELDS_ATTR, frozenset(fields))
+    return instance
+
+
+def _scream_downgrade(model_class, blanked: list[str]) -> None:
+    signature = (model_class.__name__, tuple(sorted(blanked)))
+    if signature in _SCREAMED_DOWNGRADES:
+        return
+    _SCREAMED_DOWNGRADES.add(signature)
+    vcprint(
+        "\n"
+        "══════════════════════════════════════════════════════════════════════\n"
+        "  MATRX ORM — CACHE DOWNGRADE BLOCKED (no-downgrade law)\n"
+        "══════════════════════════════════════════════════════════════════════\n"
+        f"  model:    {model_class.__name__}\n"
+        f"  would blank: {', '.join(sorted(blanked))}\n"
+        "  action:   cache entry EVICTED (next read refetches the full row).\n"
+        "            Nothing was lost, but a PARTIAL model instance reached a\n"
+        "            write-through cache path without calling\n"
+        "            matrx_orm.state.mark_partial() — fix the writer.\n"
+        "══════════════════════════════════════════════════════════════════════",
+        color="red",
+    )
+
+
 class CachePolicy(Enum):
     PERMANENT = "permanent"
     LONG_TERM = "long_term"
@@ -192,7 +234,26 @@ class ModelState:
         return True
 
     async def cache(self, record):
-        """Cache a record with proper error handling."""
+        """Cache a record with proper error handling.
+
+        THE NO-DOWNGRADE LAW: a cache entry may only ever be REPLACED by a
+        record that is at least as informed as the one already there. A
+        write-through instance built from ``{pk, **payload}`` is NOT a row
+        snapshot — every column outside the payload holds a model default
+        (usually ``None``), not the row's real value. Storing one blanks the
+        row for every cached reader until the TTL expires.
+
+        That is exactly how a conversation with a perfectly good
+        ``organization_id`` in Postgres read back as org-less for 10 minutes
+        after its own turn-1 title/message_count UPDATE flushed
+        (``session/flush.py`` builds partial instances; ``bulk_update`` cached
+        them), which then hard-failed the next turn's identity restore.
+
+        So: partial records EVICT instead of caching (the next read refetches
+        the whole row), and an unflagged record that would blank a populated
+        field evicts + SCREAMS — a downgrade means a partial instance reached
+        a write-through path without declaring itself.
+        """
         try:
             if not record:
                 raise ValidationError(model=self.model_class, reason="Cannot cache None record")
@@ -204,6 +265,20 @@ class ModelState:
                     reason="Could not generate cache key for record",
                 )
 
+            if getattr(record, PARTIAL_FIELDS_ATTR, None) is not None:
+                # Declared partial (session flush write-through). Designed
+                # path — evict silently so the next read hits the DB.
+                self.evict_by_id(cache_key)
+                return
+
+            existing = self._cache.get(cache_key)
+            if existing is not None and existing is not record:
+                blanked = self._downgraded_fields(existing, record)
+                if blanked:
+                    self.evict_by_id(cache_key)
+                    _scream_downgrade(self.model_class, blanked)
+                    return
+
             self._cache[cache_key] = record
             self._cache_times[cache_key] = datetime.now()
 
@@ -222,6 +297,14 @@ class ModelState:
                 original_error=e,
             ) from e
 
+    def _downgraded_fields(self, existing, incoming) -> list[str]:
+        """Column names the incoming record would blank on the cached one."""
+        blanked: list[str] = []
+        for name in getattr(self.model_class, "_fields", {}):
+            if getattr(existing, name, None) is not None and getattr(incoming, name, None) is None:
+                blanked.append(name)
+        return blanked
+
     async def remove(self, record):
         cache_key = self._get_record_cache_key(record)
         self._cache.pop(cache_key, None)
@@ -472,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.35 → matrx_orm-3.1.37}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.35"
+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.37/tests/session/test_cache_no_downgrade.py

@@ -0,0 +1,136 @@
+"""THE NO-DOWNGRADE LAW — a cache entry may never lose information.
+
+Regression guard for the 2026-07-25 incident: a conversation with a correct
+``organization_id`` in Postgres read back org-less for the whole 10-minute
+cache TTL, because ``session/flush.py`` builds ``{pk + payload}`` stubs for
+queued UPDATEs and ``operations/update.py::bulk_update`` wrote them straight
+into the identity cache. The next turn's identity restore then STOPPED the
+request on data that did not exist.
+
+Two independent guarantees are locked in here:
+  1. flush declares its stubs partial (``mark_partial``).
+  2. ``ModelState.cache`` never stores a partial or downgrading record — it
+     evicts, so the next read refetches the whole row.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from matrx_orm.state import PARTIAL_FIELDS_ATTR, CachePolicy, ModelState, mark_partial
+
+
+class _Conversation:
+    """Minimal Model stand-in with the fields the incident turned on."""
+
+    _fields = {
+        "id": object(),
+        "organization_id": object(),
+        "title": object(),
+        "message_count": object(),
+    }
+
+    class _Meta:
+        primary_keys = ["id"]
+
+    _meta = _Meta()
+
+    def __init__(self, **kwargs):
+        for name in self._fields:
+            setattr(self, name, kwargs.get(name))
+
+    @classmethod
+    def get_database_name(cls):
+        return "test_db"
+
+
+def _state() -> ModelState:
+    state = ModelState(_Conversation)
+    state.policy = CachePolicy.SHORT_TERM
+    return state
+
+
+def _full_row() -> _Conversation:
+    return _Conversation(
+        id="c1", organization_id="org-1", title="Anthropic Model Sync", message_count=3
+    )
+
+
+@pytest.mark.asyncio
+async def test_flush_update_stub_is_declared_partial():
+    stub = mark_partial(_Conversation(id="c1", message_count=5), {"id", "message_count"})
+    assert getattr(stub, PARTIAL_FIELDS_ATTR) == frozenset({"id", "message_count"})
+
+
+@pytest.mark.asyncio
+async def test_partial_stub_evicts_instead_of_blanking_the_row():
+    state = _state()
+    await state.cache(_full_row())
+    assert (await state.get(id="c1")).organization_id == "org-1"
+
+    # Exactly what a queued conversation UPDATE flush produces on turn 1.
+    await state.cache(mark_partial(_Conversation(id="c1", message_count=5), {"id", "message_count"}))
+
+    # The org-less stub must NOT be servable. Cache miss → caller refetches.
+    assert await state.get(id="c1") is None
+
+
+@pytest.mark.asyncio
+async def test_undeclared_downgrade_is_refused_too():
+    state = _state()
+    await state.cache(_full_row())
+    await state.cache(_Conversation(id="c1", message_count=7))  # no mark_partial
+    assert await state.get(id="c1") is None
+
+
+@pytest.mark.asyncio
+async def test_equally_informed_record_still_replaces():
+    state = _state()
+    await state.cache(_full_row())
+    fresh = _Conversation(
+        id="c1", organization_id="org-1", title="Renamed", message_count=9
+    )
+    await state.cache(fresh)
+    cached = await state.get(id="c1")
+    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)