matrx-orm 3.1.227__tar.gz → 3.1.229__tar.gz

{matrx_orm-3.1.227 → matrx_orm-3.1.229}/CLAUDE.md

@@ -158,6 +158,14 @@ enforced in code:
    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.
 
+4. **Entries die with their age.** Writes sweep entries the policy already treats
+   as stale (`ModelState.sweep_stale`, every `STALE_SWEEP_EVERY_WRITES`); an
+   append-only writer of big JSON passes `returning=[...]` to `upsert` /
+   `bulk_create` (or uses `insert_returning`) so its rows are neither read back
+   nor cached. Before this an unread entry lived for the whole process, and a
+   workflow worker's checkpoints/outcomes/events grew it until ECS killed the
+   task for memory (MKT-111, 2026-10-15). Guard: `tests/test_state_cache_sweeps_stale.py`.
+
 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

{matrx_orm-3.1.227 → matrx_orm-3.1.229}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matrx-orm
-Version: 3.1.227
+Version: 3.1.229
 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.227 → matrx_orm-3.1.229}/matrx_orm/core/base.py

@@ -693,14 +693,19 @@ class Model(RuntimeMixin, metaclass=ModelMeta):
         )
 
     @classmethod
-    async def bulk_create(cls, objects_data: list[dict[str, Any]]) -> list[Self]:
+    async def bulk_create(
+        cls, objects_data: list[dict[str, Any]], *, returning: Sequence[str] | None = None
+    ) -> list[Self]:
         """
         Bulk create multiple instances using enhanced bulk operations.
         Follows the same data processing pipeline as individual create().
+
+        ``returning``: hand back only these columns, as plain dicts, uncached —
+        for append-only writers that must not read large rows back.
         """
         from matrx_orm.operations.create import bulk_create
 
-        return cast(list[Self], await bulk_create(cls, objects_data))
+        return cast(list[Self], await bulk_create(cls, objects_data, returning=returning))
 
     @classmethod
     async def bulk_update(cls, objects: Sequence[Model], fields: list[str]) -> int:
@@ -728,6 +733,7 @@ class Model(RuntimeMixin, metaclass=ModelMeta):
         update_fields: list[str] | None = None,
         *,
         on_conflict: list[str] | ConflictTarget | None = None,  # noqa: F821
+        returning: Sequence[str] | None = None,
     ) -> Self:
         """INSERT ... ON CONFLICT (...) DO UPDATE SET ... RETURNING *
 
@@ -744,11 +750,14 @@ class Model(RuntimeMixin, metaclass=ModelMeta):
                          partial unique index. Preferred over
                          ``conflict_fields``; exactly one of the two must be
                          provided.
+            returning: Only these columns are read back; the instance is then
+                       not cached (it is not a row snapshot). For append-only
+                       writers of large JSON.
         """
         from matrx_orm.operations.create import upsert
 
         target = _resolve_on_conflict(conflict_fields, on_conflict)
-        return cast(Self, await upsert(cls, data, target, update_fields))
+        return cast(Self, await upsert(cls, data, target, update_fields, returning=returning))
 
     @classmethod
     async def bulk_upsert(

{matrx_orm-3.1.227 → matrx_orm-3.1.229}/matrx_orm/operations/create.py

@@ -168,8 +168,19 @@ async def insert_returning(
     }
 
 
-async def bulk_create(model_cls: type[Model], objects_data: list[dict[str, Any]]) -> list[Model]:
-    """Bulk insert with field coercion. Returns hydrated model instances."""
+async def bulk_create(
+    model_cls: type[Model],
+    objects_data: list[dict[str, Any]],
+    *,
+    returning: Sequence[str] | None = None,
+) -> list[Any]:
+    """Bulk insert with field coercion. Returns hydrated model instances.
+
+    ``returning`` names the only columns handed back: the result is then a list
+    of plain dicts and nothing is cached. An append-only writer of large JSON
+    (workflow events) uses it so its rows are not read back over the wire,
+    decoded, and kept in the process cache.
+    """
     if not objects_data:
         return []
 
@@ -192,6 +203,9 @@ async def bulk_create(model_cls: type[Model], objects_data: list[dict[str, Any]]
 
     query = QueryBuilder(model_cls)._build_query()
     query["data"] = data_list
+    if returning:
+        query["returning"] = [getattr(model_cls._fields[k], "field_name", k) for k in returning]
+        return await QueryExecutor(query).bulk_insert(query)
 
     executor = QueryExecutor(query)
     created_instances = await executor.bulk_insert(query)
@@ -236,12 +250,17 @@ async def upsert(
     data: dict[str, Any],
     on_conflict: OnConflictArg,
     update_fields: list[str] | None = None,
+    returning: Sequence[str] | None = None,
 ) -> Model:
     """INSERT ... ON CONFLICT (...) DO UPDATE SET ... RETURNING *
 
     ``on_conflict`` accepts either a ``list[str]`` of column names (the
     original behaviour) OR a :class:`ConflictTarget` describing an
     expression / partial unique index.
+
+    ``returning`` names the only columns read back: the instance then carries
+    the caller's values plus those columns, and is NOT cached (it is not a row
+    snapshot). For append-only writers of large JSON.
     """
     conflict_fields, target = _normalise_on_conflict(on_conflict)
     instance = model_cls(**data)
@@ -271,6 +290,9 @@ async def upsert(
         conflict_fields,
     )
 
+    if returning:
+        query["returning"] = [getattr(model_cls._fields[k], "field_name", k) for k in returning]
+
     executor = QueryExecutor(query)
     result = await executor.upsert(query)
 
@@ -280,7 +302,8 @@ async def upsert(
             value = field.to_python(value)
         setattr(instance, key, value)
 
-    await StateManager.cache(model_cls, instance)
+    if not returning:
+        await StateManager.cache(model_cls, instance)
     return instance
 
 

{matrx_orm-3.1.227 → matrx_orm-3.1.229}/matrx_orm/query/executor.py

@@ -1296,13 +1296,19 @@ class QueryExecutor:
                         chunk_values.append(row_data.get(col))
                         param_index += 1
                     placeholders_list.append(f"({', '.join(row_phs)})")
+                named = query.get("returning")
                 sql = (
                     f"INSERT INTO {table} ({', '.join(columns)}) "
                     f"VALUES {', '.join(placeholders_list)} "
-                    f"RETURNING *"
+                    f"RETURNING {', '.join(named) if named else '*'}"
                 )
                 chunk_rows = await self.db.execute_write(sql, *chunk_values)
-                results.extend(self._make(row) for row in chunk_rows)
+                if named:
+                    # Plain dicts of the named columns: a partial row is never
+                    # hydrated into a Model (and so never cached as one).
+                    results.extend(dict(row) for row in chunk_rows)  # type: ignore[misc]
+                else:
+                    results.extend(self._make(row) for row in chunk_rows)
             return results
         except DatabaseError:
             # Already classified upstream — see note on single-insert.
@@ -1371,11 +1377,16 @@ class QueryExecutor:
             )
 
         set_clause = ", ".join(f"{f} = EXCLUDED.{f}" for f in fields_to_update)
+        # ``returning`` (Model.upsert(returning=...)) names the columns handed
+        # back. An append-only writer of big JSON (a workflow node outcome)
+        # must not read its own megabytes back over the wire and decode them.
+        named = query.get("returning")
+        returning_clause = ", ".join(named) if named else "*"
         sql = (
             f"INSERT INTO {table} ({', '.join(columns)}) "
             f"VALUES ({', '.join(placeholders)}) "
             f"ON CONFLICT {target_clause} DO UPDATE SET {set_clause} "
-            f"RETURNING *"
+            f"RETURNING {returning_clause}"
         )
 
         try:

{matrx_orm-3.1.227 → matrx_orm-3.1.229}/matrx_orm/schema_builder/common.py

@@ -141,66 +141,9 @@ DEBUG_CONFIG = {
     "verbose": False,
 }
 
-# Names a generated model class can NEVER take, because the models file imports
-# or defines them at module scope — a model class shadowing one of these either
-# breaks the module (e.g. a class named `Model` is special-cased by ModelMeta as
-# the abstract base and never gets its table wired) or silently rebinds a field
-# type. A table whose PascalCase lands on one of these is renamed deterministically
-# by safe_model_class_name() to <Schema><Pascal> (e.g. ai.model -> AiModel). This
-# is the ONLY place a name still carries a schema, and only for a true collision.
-RESERVED_MODEL_NAMES: frozenset[str] = frozenset(
-    {
-        "Model",
-        "BaseManager",
-        "BaseDTO",
-        "ModelView",
-        "model_registry",
-        "Enum",
-        "dataclass",
-        "ClassVar",
-        "Field",
-        "CharField",
-        "TextField",
-        "IntegerField",
-        "BigIntegerField",
-        "SmallIntegerField",
-        "BooleanField",
-        "FloatField",
-        "DecimalField",
-        "DateTimeField",
-        "DateField",
-        "TimeField",
-        "UUIDField",
-        "JSONField",
-        "JSONBField",
-        "EnumField",
-        "ForeignKey",
-        "ObjectField",
-        "BinaryField",
-        "IPAddressField",
-        "RangeField",
-        "VectorField",
-        "TextArrayField",
-        "IntegerArrayField",
-        "UUIDArrayField",
-        "FloatArrayField",
-    }
-)
-
-
-def safe_model_class_name(table_name: str, schema: str | None, to_pascal_case) -> str:
-    """PascalCase class name for *table_name*, schema-prefixed ONLY if the bare
-    PascalCase collides with a framework-reserved symbol (see RESERVED_MODEL_NAMES).
-
-    e.g. ``ai.model`` -> ``AiModel`` (a class literally named ``Model`` is
-    unusable), while every non-reserved table keeps its clean, prefix-free name.
-    The same (table, schema) always yields the same name, so a FK target and the
-    target's own class agree.
-    """
-    base = to_pascal_case(table_name)
-    if base in RESERVED_MODEL_NAMES:
-        return f"{to_pascal_case(schema or 'public')}{base}"
-    return base
+# RESERVED_MODEL_NAMES / safe_model_class_name live in package_wiring.py (stdlib-only, so the
+# package-wiring drift gate can name view classes without importing matrx_orm); re-exported here.
+from matrx_orm.schema_builder.package_wiring import RESERVED_MODEL_NAMES, safe_model_class_name  # noqa: E402,F401
 
 
 def resolve_fk_related_model_name(

{matrx_orm-3.1.227 → matrx_orm-3.1.229}/matrx_orm/schema_builder/package_wiring.py

@@ -179,6 +179,79 @@ def _lookup(inventory: dict[tuple[str, str], TableInfo], table: str) -> TableInf
     return info
 
 
+# Names a generated model class can NEVER take, because the models file imports
+# or defines them at module scope — a model class shadowing one of these either
+# breaks the module (e.g. a class named `Model` is special-cased by ModelMeta as
+# the abstract base and never gets its table wired) or silently rebinds a field
+# type. A table whose PascalCase lands on one of these is renamed deterministically
+# by safe_model_class_name() to <Schema><Pascal> (e.g. ai.model -> AiModel). This
+# is the ONLY place a name still carries a schema, and only for a true collision.
+RESERVED_MODEL_NAMES: frozenset[str] = frozenset(
+    {
+        "Model",
+        "BaseManager",
+        "BaseDTO",
+        "ModelView",
+        "model_registry",
+        "Enum",
+        "dataclass",
+        "ClassVar",
+        "Field",
+        "CharField",
+        "TextField",
+        "IntegerField",
+        "BigIntegerField",
+        "SmallIntegerField",
+        "BooleanField",
+        "FloatField",
+        "DecimalField",
+        "DateTimeField",
+        "DateField",
+        "TimeField",
+        "UUIDField",
+        "JSONField",
+        "JSONBField",
+        "EnumField",
+        "ForeignKey",
+        "ObjectField",
+        "BinaryField",
+        "IPAddressField",
+        "RangeField",
+        "VectorField",
+        "TextArrayField",
+        "IntegerArrayField",
+        "UUIDArrayField",
+        "FloatArrayField",
+    }
+)
+
+
+def safe_model_class_name(table_name: str, schema: str | None, to_pascal_case) -> str:
+    """PascalCase class name for *table_name*, schema-prefixed ONLY if the bare
+    PascalCase collides with a framework-reserved symbol (see RESERVED_MODEL_NAMES).
+
+    e.g. ``ai.model`` -> ``AiModel`` (a class literally named ``Model`` is
+    unusable), while every non-reserved table keeps its clean, prefix-free name.
+    The same (table, schema) always yields the same name, so a FK target and the
+    target's own class agree.
+    """
+    base = to_pascal_case(table_name)
+    if base in RESERVED_MODEL_NAMES:
+        return f"{to_pascal_case(schema or 'public')}{base}"
+    return base
+
+
+def _pascal_case(s: str) -> str:
+    """Stdlib twin of ``DataTransformer.to_pascal_case`` (matrx_utils): snake-normalize, then title each part.
+
+    Kept stdlib-only so the wiring gate needs neither matrx_orm nor matrx_utils's runtime deps; a drift
+    from the generator's naming fails the gate loudly (the class is checked against the models file).
+    """
+    s = re.sub(r"(?<!^)(?=[A-Z])", "_", s)
+    s = re.sub(r"[^a-zA-Z0-9]+", "_", s).lower()
+    return "".join(x.title() for x in s.split("_"))
+
+
 def _lookup_view(
     inventory: dict[tuple[str, str], TableInfo], view: str, python_root: str | Path | None
 ) -> TableInfo:
@@ -190,9 +263,7 @@ def _lookup_view(
         raise PackageWiringError(
             f"package_wiring: view '{view}' — schema '{schema}' has no generated models module"
         )
-    from matrx_orm.schema_builder.common import dt_utils, safe_model_class_name
-
-    pascal = safe_model_class_name(snake, schema, dt_utils.to_pascal_case)
+    pascal = safe_model_class_name(snake, schema, _pascal_case)
     if python_root is not None:
         models_file = Path(python_root) / (sibling.models_module.replace(".", "/") + ".py")
         tree = ast.parse(models_file.read_text(), filename=str(models_file))

{matrx_orm-3.1.227 → matrx_orm-3.1.229}/matrx_orm/state.py

@@ -57,6 +57,12 @@ def _scream_downgrade(model_class, blanked: list[str]) -> None:
     )
 
 
+#: Every this-many cache writes on one model, entries the policy already treats
+#: as stale are dropped (``ModelState.sweep_stale``). Bounds the identity cache
+#: by time instead of letting it grow for the life of the process.
+STALE_SWEEP_EVERY_WRITES = 200
+
+
 class CachePolicy(Enum):
     PERMANENT = "permanent"
     LONG_TERM = "long_term"
@@ -75,6 +81,7 @@ class ModelState:
             self._cache_times = {}
             self._subscriptions = set()
             self._locks = {}
+            self._writes_since_sweep = 0
         except Exception as e:
             raise ConfigurationError(
                 model=model_class,
@@ -330,6 +337,9 @@ class ModelState:
 
             self._cache[cache_key] = record
             self._cache_times[cache_key] = datetime.now()
+            self._writes_since_sweep = getattr(self, "_writes_since_sweep", 0) + 1
+            if self._writes_since_sweep >= STALE_SWEEP_EVERY_WRITES:
+                self.sweep_stale()
 
             if self.realtime and self.policy in (
                 CachePolicy.PERMANENT,
@@ -346,6 +356,30 @@ class ModelState:
                 original_error=e,
             ) from e
 
+    def sweep_stale(self) -> int:
+        """Drop every entry its policy already treats as stale. Returns how many.
+
+        THE LEAK THIS CLOSES (MKT-111, 2026-10-15): staleness was only ever
+        checked on READ, so an entry nobody read again stayed forever. Every
+        append-only row a process creates (each workflow checkpoint, node
+        outcome and event — fresh primary keys, never re-read through the
+        cache) accumulated for the life of the process, multi-megabyte JSON
+        included, until ECS killed the task for memory. A stale entry is
+        already a miss, so dropping it changes no read.
+        """
+        self._writes_since_sweep = 0
+        dropped = 0
+        for key in list(self._cache_times):
+            record = self._cache.get(key)
+            if record is None or self._is_stale(record):
+                self._cache.pop(key, None)
+                self._cache_times.pop(key, None)
+                lock = self._locks.get(key)
+                if lock is not None and not lock.locked():
+                    self._locks.pop(key, None)
+                dropped += 1
+        return dropped
+
     def _downgraded_fields(self, existing, incoming) -> list[str]:
         """Column names the incoming record would blank on the cached one."""
         blanked: list[str] = []

{matrx_orm-3.1.227 → matrx_orm-3.1.229}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.227"
+version = "3.1.229"
 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.229/tests/test_state_cache_sweeps_stale.py

@@ -0,0 +1,52 @@
+"""The identity cache never keeps a row past its policy's age (MKT-111).
+
+Staleness used to be checked only on READ, so an entry nobody read again stayed for
+the life of the process: every append-only row a worker created (workflow
+checkpoints, node outcomes, events — fresh keys, multi-megabyte JSON) piled up
+until ECS killed the task for memory. Writes now sweep stale entries.
+"""
+
+from __future__ import annotations
+
+import types
+from datetime import datetime, timedelta
+
+import pytest
+
+from matrx_orm import state as state_module
+from matrx_orm.state import CachePolicy, ModelState
+
+
+class _Model:
+    _cache_policy = CachePolicy.SHORT_TERM
+    _fields: dict = {}
+    _meta = types.SimpleNamespace(primary_keys=["id"])
+
+
+def _record(i: int) -> object:
+    rec = types.SimpleNamespace(id=f"row-{i}", payload="x" * 10)
+    rec._meta = _Model._meta
+    return rec
+
+
+@pytest.mark.asyncio
+async def test_rows_past_their_age_are_dropped_by_later_writes(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(state_module, "STALE_SWEEP_EVERY_WRITES", 10)
+    state = ModelState(_Model)
+    for i in range(5):
+        await state.cache(_record(i))
+    old = datetime.now() - timedelta(minutes=11)  # SHORT_TERM is 10 minutes
+    for key in list(state._cache_times):
+        state._cache_times[key] = old
+    for i in range(5, 15):
+        await state.cache(_record(i))
+    assert not any(f"row-{i}" in state._cache for i in range(5)), sorted(state._cache)
+    assert all(f"row-{i}" in state._cache for i in range(5, 15))
+
+
+@pytest.mark.asyncio
+async def test_a_fresh_row_is_never_swept() -> None:
+    state = ModelState(_Model)
+    await state.cache(_record(1))
+    assert state.sweep_stale() == 0
+    assert "row-1" in state._cache