matrx-orm 3.1.161__tar.gz → 3.1.162__tar.gz

{matrx_orm-3.1.161 → matrx_orm-3.1.162}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matrx-orm
-Version: 3.1.161
+Version: 3.1.162
 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.161 → matrx_orm-3.1.162}/matrx_orm/associations.py

@@ -614,6 +614,39 @@ class Associations:
                 f"can decide."
             )
 
+    #: How many endpoint ids go into one ``pk IN (...)`` fetch. Bounded so a
+    #: Library of 5,810 sources does not build one statement with 5,810 bind
+    #: parameters; 500 is the same chunk the rest of this codebase uses for
+    #: set-based reads and writes.
+    _FETCH_CHUNK = 500
+
+    @classmethod
+    async def _fetch_many(cls, model: type[Model], ids: list[Any]) -> dict[str, Any]:
+        """``{str(pk): row}`` for ``ids``, in a BOUNDED number of round trips.
+
+        One statement per :attr:`_FETCH_CHUNK` ids, through the same Model (so
+        the same RLS session, the same soft-delete filter and the same row
+        shape as a per-id load). Duplicate ids in the edge list cost nothing
+        extra. A composite-primary-key endpoint has no single-column ``IN``, so
+        it falls back to per-id loads — no association endpoint uses one today,
+        and this keeps the helper honest if one ever does.
+        """
+        meta = getattr(model, "_meta", None)
+        pks = list(getattr(meta, "primary_keys", None) or ["id"])
+        unique = list(dict.fromkeys(str(i) for i in ids))
+        if len(pks) > 1:
+            found = [await model.load_by_id_or_none(i) for i in unique]
+            return {
+                str(getattr(row, pks[0])): row for row in found if row is not None
+            }
+        pk = pks[0]
+        out: dict[str, Any] = {}
+        for start in range(0, len(unique), cls._FETCH_CHUNK):
+            chunk = unique[start : start + cls._FETCH_CHUNK]
+            for row in await model.filter_items(**{f"{pk}__in": chunk}):
+                out[str(getattr(row, pk))] = row
+        return out
+
     async def _load_gated(
         self, token: str, ids: list[Any], org_id: str, actor_id: str | None = None
     ) -> list[Any]:
@@ -631,13 +664,27 @@ class Associations:
 
         A row that fails BOTH is dropped and SCREAMS: with the edge org-scoped
         by layer 1, reaching here means RLS or the edge filter already leaked.
+
+        🚨 THE ROWS ARE FETCHED IN BULK, NEVER ONE PER EDGE. This loop used to
+        call ``load_by_id_or_none`` per id, so a read of N targets cost N
+        round trips: measured 2026-09-18 against the live database on a
+        3-connection pool, one Library of 533 YouTube sources spent **177 s in
+        533 identical single-row SELECTs** out of a 182 s call — and the media
+        catalogue makes that call three times per selection job. The gate
+        itself is unchanged and still runs per row; only the FETCH is batched,
+        so nothing about what survives this method moved. Guard:
+        ``packages/matrx-orm/tests/level1/test_associations.py::
+        test_load_gated_batches_the_fetch_instead_of_one_query_per_edge``.
         """
+        if not ids:
+            return []
         model = await self._reg.require(token)
         actor = self._resolve_actor(actor_id)
         is_system = getattr(model, "_rls_variant", None) == "system"  # orm-getattr-ok: generator-stamped capability flag
+        by_id = await self._fetch_many(model, ids)
         out: list[Any] = []
         for rid in ids:
-            entity = await model.load_by_id_or_none(rid)
+            entity = by_id.get(str(rid))
             if entity is None:
                 continue  # layer 1: RLS-filtered, soft-deleted, or absent
             if is_system:

{matrx_orm-3.1.161 → matrx_orm-3.1.162}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.161"
+version = "3.1.162"
 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.161 → matrx_orm-3.1.162}/tests/level1/test_associations.py

@@ -64,9 +64,20 @@ class _FakeBase:
         cls._rows[row.id] = row
         return row, True
 
+    @classmethod
+    def _matches(cls, row, key, value):
+        if key.endswith("__in"):
+            return getattr(row, key[:-4], None) in value
+        return getattr(row, key, None) == value
+
     @classmethod
     async def filter_items(cls, **filters):
-        return [r for r in cls._rows.values() if all(getattr(r, k, None) == v for k, v in filters.items())]
+        cls.filter_calls = getattr(cls, "filter_calls", 0) + 1
+        return [
+            r
+            for r in cls._rows.values()
+            if all(cls._matches(r, k, v) for k, v in filters.items())
+        ]
 
     @classmethod
     async def load_by_id_or_none(cls, item_id):
@@ -721,3 +732,82 @@ async def test_verify_false_skips_the_policy_entirely():
     )
     assert edge.org_id == "org1"
     assert policy.calls == []
+
+
+# --------------------------------------------------------------------------- #
+# Reads must cost a BOUNDED number of round trips, never one per edge
+# --------------------------------------------------------------------------- #
+
+@pytest.mark.asyncio
+async def test_load_gated_batches_the_fetch_instead_of_one_query_per_edge():
+    """500 targets must cost a handful of statements, not 500.
+
+    Run against the per-id loop this replaced, it fails with `500` — which is
+    exactly what it cost in production: measured 2026-09-18 on the live
+    database at a 3-connection pool, one Library of 533 YouTube sources spent
+    **177 s inside 533 identical single-row SELECTs**, and the media catalogue
+    reads that list three times per selection job.
+    """
+    a = _assoc()
+    NoteModel.seed(id="n1", org_id="org1")
+    for i in range(500):
+        ProjectModel.seed(id=f"p{i}", org_id="org1")
+        AssociationRow.seed(
+            source_type="note", source_id="n1", target_type="project",
+            target_id=f"p{i}", org_id="org1",
+        )
+
+    ProjectModel.filter_calls = 0
+    per_row_loads = 0
+    original = ProjectModel.load_by_id_or_none.__func__
+
+    @classmethod
+    async def _counted(cls, item_id):
+        nonlocal per_row_loads
+        per_row_loads += 1
+        return await original(cls, item_id)
+
+    ProjectModel.load_by_id_or_none = _counted
+    try:
+        loaded = await a.targets_from(EntityRef("note", "n1"), "project", org_id="org1")
+    finally:
+        ProjectModel.load_by_id_or_none = classmethod(original)
+
+    assert len(loaded) == 500, "the batched fetch must return every gated row"
+    assert per_row_loads == 0, (
+        f"Reading 500 targets issued {per_row_loads} single-row loads. A read of N "
+        "targets must not cost N round trips — batch the fetch and keep the gate."
+    )
+    assert ProjectModel.filter_calls <= 5, (
+        f"Reading 500 targets took {ProjectModel.filter_calls} statements against the "
+        "target table; it must take at most 5."
+    )
+
+
+@pytest.mark.asyncio
+async def test_batched_fetch_chunks_and_still_drops_what_the_gate_refuses():
+    """More rows than one chunk, and the gate's verdicts are unchanged by batching."""
+    a = _assoc()
+    NoteModel.seed(id="n1", org_id="org1")
+    total = Associations._FETCH_CHUNK * 2 + 3
+    for i in range(total):
+        # Every tenth row is cross-org, and one id has no row at all.
+        if i % 10 != 0:
+            ProjectModel.seed(id=f"p{i}", org_id="org2" if i % 10 == 5 else "org1")
+        AssociationRow.seed(
+            source_type="note", source_id="n1", target_type="project",
+            target_id=f"p{i}", org_id="org1",
+        )
+
+    ProjectModel.filter_calls = 0
+    loaded = await a.targets_from(EntityRef("note", "n1"), "project", org_id="org1")
+
+    expected = {f"p{i}" for i in range(total) if i % 10 not in (0, 5)}
+    assert {p.id for p in loaded} == expected, (
+        "batching the fetch changed WHICH rows survive the ownership gate"
+    )
+    import math
+    assert ProjectModel.filter_calls == math.ceil(total / Associations._FETCH_CHUNK), (
+        f"{total} targets took {ProjectModel.filter_calls} statements; it must take one "
+        "per chunk."
+    )