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

{matrx_orm-3.1.36 → matrx_orm-3.1.38}/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.38}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matrx-orm
-Version: 3.1.36
+Version: 3.1.38
 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.38}/matrx_orm/associations.py

@@ -196,6 +196,15 @@ class Associations:
         self._org = org_field
         self._role = role_field
         self._role_available = True  # refined by _validate_field_bindings when introspectable
+        # Optional edge-document columns (platform.associations carries them;
+        # a minimal host edge table may not). Passing the kwarg against a
+        # table without the column raises loudly at call time.
+        self._optional_cols: dict[str, bool] = {
+            "payload_kind": True,
+            "payload": True,
+            "label": True,
+            "position": True,
+        }
         self._validate_field_bindings()
 
     def _validate_field_bindings(self) -> None:
@@ -230,6 +239,8 @@ class Associations:
         # role is OPTIONAL on the edge table — engines over role-less edge
         # tables keep working; passing a role against one raises at call time.
         self._role_available = self._role in fields
+        for col in self._optional_cols:
+            self._optional_cols[col] = col in fields
 
     # ---- writes ----------------------------------------------------------
 
@@ -257,6 +268,10 @@ class Associations:
         metadata: dict[str, Any] | None = None,
         created_by: str | None = None,
         verify: bool = True,
+        payload_kind: str | None = None,
+        payload: dict[str, Any] | None = None,
+        label: str | None = None,
+        position: int | None = None,
     ) -> Any:
         """Idempotently create the ``source -> target`` edge in ``org_id``.
 
@@ -288,6 +303,17 @@ class Associations:
             defaults["metadata"] = metadata
         if created_by is not None:
             defaults["created_by"] = created_by
+        extras = {"payload_kind": payload_kind, "payload": payload, "label": label, "position": position}
+        for col, value in extras.items():
+            if value is None:
+                continue
+            if not self._optional_cols.get(col, True):
+                model_name = getattr(self._assoc, "__name__", str(self._assoc))
+                raise ValueError(
+                    f"{col}={value!r} was passed but edge model {model_name} has no "
+                    f"{col!r} column — add the column or drop the argument."
+                )
+            defaults[col] = value
         lookup = {
             self._st: source.type,
             self._si: source.id,
@@ -300,8 +326,14 @@ class Associations:
         elif role is not None:
             self._role_filter(role)  # raises with the loud config message
         edge, created = await self._assoc.get_or_create(defaults=defaults, **lookup)
-        if not created and metadata is not None and getattr(edge, "metadata", None) != metadata:
-            edge = await edge.update(metadata=metadata)
+        if not created:
+            updates = {
+                col: value
+                for col, value in {"metadata": metadata, **extras}.items()
+                if value is not None and getattr(edge, col, None) != value
+            }
+            if updates:
+                edge = await edge.update(**updates)
         return edge
 
     async def dissociate(

{matrx_orm-3.1.36 → matrx_orm-3.1.38}/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.38}/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.38}/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.38}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.36"
+version = "3.1.38"
 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.38}/tests/level1/test_associations.py

@@ -262,6 +262,45 @@ async def test_load_gated_returns_system_vocabulary_cross_org():
     assert [t.id for t in targets] == ["k1"]
 
 
+@pytest.mark.asyncio
+async def test_associate_writes_and_replaces_payload_document():
+    a = _assoc()
+    _seed_n1_p1()
+    src, tgt = EntityRef("note", "n1"), EntityRef("project", "p1")
+    e1 = await a.associate(
+        src, tgt, org_id="org1", role="reviewed_by",
+        payload_kind="plan_review", payload={"review_date": "2026-07-25"},
+        label="Review", position=1,
+    )
+    assert e1.payload_kind == "plan_review" and e1.payload == {"review_date": "2026-07-25"}
+    assert e1.label == "Review" and e1.position == 1
+    # repeat call: passed values full-replace; omitted (None) stay untouched
+    e2 = await a.associate(
+        src, tgt, org_id="org1", role="reviewed_by",
+        payload={"review_date": "2026-07-26", "notes": "x"},
+    )
+    assert e2 is e1 and e2.payload == {"review_date": "2026-07-26", "notes": "x"}
+    assert e2.payload_kind == "plan_review" and e2.label == "Review"
+    assert len(AssociationRow._rows) == 1
+
+
+@pytest.mark.asyncio
+async def test_associate_payload_against_payloadless_table_raises():
+    from types import SimpleNamespace
+
+    cols = ("source_type", "source_id", "target_type", "target_id", "org_id", "role", "metadata")
+    model = type(
+        "_MiniEdge", (_FakeBase,), {"_meta": SimpleNamespace(fields={c: object() for c in cols})}
+    )
+    a = Associations(association_model=model, registry=_token_registry())
+    _seed_n1_p1()
+    with pytest.raises(ValueError, match="payload_kind"):
+        await a.associate(
+            EntityRef("note", "n1"), EntityRef("project", "p1"),
+            org_id="org1", payload_kind="plan_review",
+        )
+
+
 @pytest.mark.asyncio
 async def test_associate_verify_false_skips_endpoint_check():
     a = _assoc()  # no endpoints seeded at all

{matrx_orm-3.1.36 → matrx_orm-3.1.38}/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)