matrx-orm 3.1.69__tar.gz → 3.1.71__tar.gz

{matrx_orm-3.1.69 → matrx_orm-3.1.71}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matrx-orm
-Version: 3.1.69
+Version: 3.1.71
 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
@@ -25,7 +25,7 @@ Requires-Python: >=3.13
 Requires-Dist: asyncpg>=0.31.0
 Requires-Dist: cryptography>=43.0
 Requires-Dist: gitpython>=3.1.40
-Requires-Dist: matrx-utils>=2.0.13
+Requires-Dist: matrx-utils>=2.0.14
 Requires-Dist: psycopg-pool>=3.2.5
 Requires-Dist: psycopg[binary]>=3.2.5
 Requires-Dist: python-dotenv>=1.0

{matrx_orm-3.1.69 → matrx_orm-3.1.71}/matrx_orm/core/FEATURE.md

@@ -55,8 +55,24 @@ Pinned by `tests/level1/test_pool_maintenance.py`.
 
 Verified against code: 2026-08-13.
 
+## Transaction-pooled role scope
+
+**A restricted role is always transaction-local.** `rls_session()` opens the
+outermost `transaction()` before it sets JWT claims with
+`set_config(..., true)` and issues `SET LOCAL ROLE`. Success and early return
+commit; exceptions roll back; cancellation-shielded teardown finishes before
+the connection returns to the pool. No path can leave `authenticated` on a
+reused server connection.
+
+Pinned by `tests/level1/test_rls_session_scope.py` and
+`tests/level1/test_connection_poison_guard.py`.
+
+Verified against code: 2026-08-15.
+
 ## Change log
 
+- 2026-08-15: Pinned transaction-local RLS role cleanup across success,
+  exception, and early-return paths.
 - 2026-08-14: Public models now render `public.table` SQL targets; bare public
   relation names can no longer disable application logs or write-failure capture.
 - 2026-08-13: Registry, admin, recovery, catalog, and diagnostic identities are now exact `schema.table`; bare names are accepted only as uncached discovery terms and ambiguity fails loudly.

{matrx_orm-3.1.69 → matrx_orm-3.1.71}/matrx_orm/query/FEATURE.md

@@ -11,6 +11,14 @@ remain fast. A large reconciliation, export, or historical scan must call
 merges pending session state, but it does not insert every result into the
 process identity cache.
 
+Hydration of 200 or more rows runs in a worker thread. Model construction,
+relationship attachment, and identity-cache insertion are synchronous Python
+work and must not monopolize an API event loop for a large result set. Complete
+primary-key cache misses are O(1): after the direct dictionary lookup misses,
+the state manager never scans the cache for an identity it already knows is
+absent. Historical/request-local scans should still use `use_cache=False` so
+they do not grow the process cache with rows that will not be reused.
+
 `Model.all(use_cache=False)` exposes the same behavior. The default remains
 `True` for compatibility. The cache bypass controls only cache population; it
 does not weaken database authorization, filters, hydration, or transaction
@@ -23,3 +31,8 @@ inherits the model query's default `*` projection. A grouped aggregate with no
 explicit `.values(...)` projects the grouped columns plus its aggregate
 expressions. These shapes keep every generated aggregate valid in PostgreSQL
 without forcing callers to add a redundant projection.
+
+## Change log
+
+- 2026-08-15 — Moved bulk hydration off the event loop, made complete-primary-key
+  misses constant-time, and documented cache bypass for request-local scans.

{matrx_orm-3.1.69 → matrx_orm-3.1.71}/matrx_orm/query/executor.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import asyncio
 import json
 import re
 from types import NotImplementedType
@@ -24,6 +25,11 @@ if TYPE_CHECKING:
 
 debug = False
 
+# Model hydration is synchronous Python work. Small result sets stay inline;
+# large sets move to a worker thread so one read cannot freeze every coroutine
+# on the process event loop.
+_BULK_HYDRATION_THREAD_THRESHOLD = 200
+
 _SKIP_PARAM = object()
 
 _PARAM_RE = re.compile(r"\$(\d+)")
@@ -264,6 +270,9 @@ class QueryExecutor:
         hydrate = getattr(self.model, "_hydrate", None)
         return hydrate(row) if hydrate is not None else self.model(**row)
 
+    def _hydrate_rows(self, rows: list[dict[str, Any]]) -> list[Any]:
+        return [self._make(row) for row in rows]
+
     def _decode_row_dict(self, row: dict[str, Any]) -> dict[str, Any]:
         """Apply field ``from_db_value`` so ``.values()`` matches Model hydration.
 
@@ -1521,8 +1530,12 @@ class QueryExecutor:
             return []
         select_related = self._full_query_dict.get("select_related", [])
         if select_related:
+            if len(results) >= _BULK_HYDRATION_THREAD_THRESHOLD:
+                return await asyncio.to_thread(self._hydrate_with_select_related, results)
             return self._hydrate_with_select_related(results)
-        return [self._make(row) for row in results]
+        if len(results) >= _BULK_HYDRATION_THREAD_THRESHOLD:
+            return await asyncio.to_thread(self._hydrate_rows, results)
+        return self._hydrate_rows(results)
 
     async def first(self) -> Any:
         """Fetch the first matching row as a model instance."""

{matrx_orm-3.1.69 → matrx_orm-3.1.71}/matrx_orm/state.py

@@ -154,6 +154,14 @@ class ModelState:
                             original_error=e,
                         ) from e
 
+                # A complete primary-key lookup has exactly one possible
+                # cache slot. If that direct key missed (or was stale), a
+                # full scan cannot find a different valid match. Falling
+                # through to _find_in_cache made cache_bulk O(n²): every new
+                # row scanned every row already cached for the model.
+                if cache_key is not None:
+                    return None
+
                 # Try finding by criteria if direct lookup fails
                 try:
                     cached_record = self._find_in_cache(**kwargs)

{matrx_orm-3.1.69 → matrx_orm-3.1.71}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.69"
+version = "3.1.71"
 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" }
@@ -41,7 +41,7 @@ dependencies = [
     "gitpython>=3.1.40",
     "psycopg[binary]>=3.2.5",
     "psycopg-pool>=3.2.5",
-    "matrx-utils>=2.0.13",
+    "matrx-utils>=2.0.14",
     "pyyaml>=6.0.3",
     "python-dotenv>=1.0",
     "cryptography>=43.0",

matrx_orm-3.1.71/tests/level1/test_bulk_hydration_offload.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+import asyncio
+import threading
+
+import pytest
+
+from matrx_orm.query.executor import (
+    _BULK_HYDRATION_THREAD_THRESHOLD,
+    QueryExecutor,
+)
+
+
+@pytest.mark.asyncio
+async def test_large_result_hydration_runs_off_the_event_loop() -> None:
+    loop_thread = threading.get_ident()
+    hydration_threads: list[int] = []
+
+    class ModelStub:
+        @staticmethod
+        def _hydrate(row):
+            hydration_threads.append(threading.get_ident())
+            return row
+
+    executor = object.__new__(QueryExecutor)
+    executor.model = ModelStub
+    executor._full_query_dict = {}
+    rows = [{"id": index} for index in range(_BULK_HYDRATION_THREAD_THRESHOLD)]
+
+    async def execute():
+        await asyncio.sleep(0)
+        return rows
+
+    executor._execute = execute
+
+    assert await executor.all() == rows
+    assert hydration_threads
+    assert loop_thread not in hydration_threads

{matrx_orm-3.1.69 → matrx_orm-3.1.71}/tests/level1/test_managed_write_guard.py

@@ -77,8 +77,8 @@ class TestStrictGuard:
             M.assert_managed_write_allowed("INSERT INTO public.cx_message (id) VALUES ($1)")
 
     def test_same_bare_name_in_another_schema_does_not_match(self):
-        M._STRICT_TABLES.add("chat.message")
-        M.assert_managed_write_allowed("UPDATE public.message SET x=1")
+        M._STRICT_TABLES.add("agent.definition")
+        M.assert_managed_write_allowed("UPDATE tool.definition SET x=1")
 
     def test_quoted_qualified_target_matches_exact_key(self):
         M._STRICT_TABLES.add("chat.message")

matrx_orm-3.1.71/tests/level1/test_rls_session_scope.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+
+from matrx_orm.adapters import AdapterRegistry
+from matrx_orm.core.rls_session import rls_session
+
+
+class _Connection:
+    def __init__(self) -> None:
+        self.calls: list[tuple[str, tuple[Any, ...]]] = []
+        self.terminated = False
+
+    async def execute(self, sql: str, *args: Any) -> None:
+        self.calls.append((sql, args))
+
+    def terminate(self) -> None:
+        self.terminated = True
+
+
+class _ConnectionContext:
+    def __init__(self, conn: _Connection) -> None:
+        self.conn = conn
+        self.exited = False
+
+    async def __aenter__(self) -> _Connection:
+        return self.conn
+
+    async def __aexit__(self, *_exc: Any) -> None:
+        self.exited = True
+
+
+class _Adapter:
+    def __init__(self, conn: _Connection) -> None:
+        self.context = _ConnectionContext(conn)
+
+    def get_connection(self) -> _ConnectionContext:
+        return self.context
+
+
+def _install_adapter(monkeypatch: pytest.MonkeyPatch) -> tuple[_Connection, _Adapter]:
+    conn = _Connection()
+    adapter = _Adapter(conn)
+    monkeypatch.setattr(AdapterRegistry, "get", lambda _database: adapter)
+    return conn, adapter
+
+
+@pytest.mark.asyncio
+async def test_rls_session_commits_transaction_local_role(monkeypatch: pytest.MonkeyPatch) -> None:
+    conn, adapter = _install_adapter(monkeypatch)
+
+    async with rls_session(
+        {"sub": "user-id", "role": "authenticated"},
+        role="authenticated",
+        database="test",
+    ):
+        pass
+
+    assert [sql for sql, _args in conn.calls] == [
+        "BEGIN",
+        "select set_config('request.jwt.claims', $1, true)",
+        "SET LOCAL statement_timeout = 30000",
+        "SET LOCAL ROLE authenticated",
+        "COMMIT",
+    ]
+    assert adapter.context.exited is True
+    assert conn.terminated is False
+
+
+@pytest.mark.asyncio
+async def test_rls_session_rolls_back_on_exception(monkeypatch: pytest.MonkeyPatch) -> None:
+    conn, adapter = _install_adapter(monkeypatch)
+
+    with pytest.raises(LookupError):
+        async with rls_session(
+            {"sub": "user-id", "role": "authenticated"},
+            role="authenticated",
+            database="test",
+        ):
+            raise LookupError("abort")
+
+    assert conn.calls[-1][0] == "ROLLBACK"
+    assert all(sql != "COMMIT" for sql, _args in conn.calls)
+    assert adapter.context.exited is True
+
+
+@pytest.mark.asyncio
+async def test_rls_session_early_return_still_closes_scope(monkeypatch: pytest.MonkeyPatch) -> None:
+    conn, adapter = _install_adapter(monkeypatch)
+
+    async def return_from_inside_scope() -> str:
+        async with rls_session(
+            {"sub": "user-id", "role": "authenticated"},
+            role="authenticated",
+            database="test",
+        ):
+            return "done"
+
+    assert await return_from_inside_scope() == "done"
+    assert conn.calls[-1][0] == "COMMIT"
+    assert adapter.context.exited is True

{matrx_orm-3.1.69 → matrx_orm-3.1.71}/tests/level1/test_state_cache.py

@@ -176,6 +176,17 @@ class TestStaleness:
 
 
 class TestFindInCache:
+    def test_complete_primary_key_miss_never_scans_the_whole_cache(self):
+        M = _make_model("FICPK")
+        state = ModelState(M)
+        _run(state.cache(M(id=str(uuid4()), name="cached")))
+
+        def fail_if_scanned(**_kwargs):
+            raise AssertionError("complete PK misses must stay O(1)")
+
+        state._find_in_cache = fail_if_scanned
+        assert _run(state.get(id=str(uuid4()))) is None
+
     def test_find_by_criteria(self):
         M = _make_model("FIC")
         state = ModelState(M)