matrx-orm 3.1.141__tar.gz → 3.1.142__tar.gz

{matrx_orm-3.1.141 → matrx_orm-3.1.142}/CLAUDE.md

@@ -52,7 +52,7 @@ Every table that becomes a Model needs row identity: a single-column primary key
 - **Schema builder** (`matrx_orm.schema_builder`): code generation for Python + TypeScript type definitions from the DB schema. Postgres **VIEWs** are emitted as **read-only `Model` classes** into the same schema models file (on by default; per-entry `output.include_views: false` opts a schema out, `output.exclude_views: [...]` skips individual views). View models get no manager/DTO/base-class/auto_config (views are not writable), synthesize `_primary_keys` from an `id` column (else the first column, for cache-key/`load_by_id` only), and emit plain typed fields with **no `ForeignKey`** (views carry no FK metadata — nothing cross-schema to resolve). Never hand-write a view model again.
 - **Secrets battery** (`matrx_orm.secrets_battery`): the ONE canonical user-credential vault — `users.user_secrets` CRUD + the platform's single Fernet primitive, keyed by `CREDENTIALS_ENCRYPTION_KEY`. Any package: `configure_secrets(db_config_name=...)` once, then `await require_user_secret(user_id, key)`. No package ever calls another service to resolve a credential. Contract: [`matrx_orm/secrets_battery/FEATURE.md`](matrx_orm/secrets_battery/FEATURE.md).
 - **Polymorphic associations** (`matrx_orm.associations`): `EntityRegistry` (token→Model) + `Associations` — a registry-driven, **access-gated** edge engine over a host's polymorphic edge table. Every `source→target` hop is org-scoped *and* each resolved endpoint is re-authorized against the ACTOR (fail-closed, screams on a genuine leak), so a hop can't widen access past what the actor may reach. 🚨 **The gate is `access_check` (wire `matrx_orm.platform_access_check` → `iam.has_access_for`), NEVER an org-column comparison** — a person belongs to several orgs on purpose, so org-equality denies her own data across her own workspaces (2026-08-30 incident) while granting any co-member of a private row. The edge's `org_id` is a TENANCY stamp, not a permission. Org-equality survives only for UNATTENDED writes (no actor) as an integrity guard, and **system vocabulary is exempt entirely** (existence still required): a model generated with `_rls_variant="system"` is platform-shared dictionary data (seo.keyword/topic) every tenant legitimately links to. Hardcodes no table names — the host wires its own edge + token-registry models.
-- **The host's declared session context** (`matrx_orm.core.session_context`): `configure_session_context(provider)` once at startup, and every **top-level** `transaction()` — including the one `rls_session` opens, before it drops to the restricted role — emits whatever the provider returns as transaction-local GUCs. This is how an application-level declaration reaches Postgres at all: a GUC set outside a transaction has no meaning, so the BEGIN is the only place it can land. aidream wires it to its provenance declaration (`app.actor_tier` / `app.actor_system`, read by `platform.actor_tier()`, the history capture and the tier rule). A nested entry is a savepoint inside a transaction that already carries them and emits nothing — and a write made **outside** any transaction carries no declaration at all, which is why a single-row write that must record its author still opens one. No provider configured ⇒ no GUCs (standalone behaviour unchanged); a provider that raises fails the transaction loudly rather than committing rows with a false provenance.
+- **The host's declared session context** (`matrx_orm.core.session_context`): `configure_session_context(provider)` once at startup, and every **top-level** `transaction()` — including the one `rls_session` opens, before it drops to the restricted role — emits whatever the provider returns as transaction-local GUCs. This is how an application-level declaration reaches Postgres at all: a GUC set outside a transaction has no meaning, so the BEGIN is the only place it can land. aidream wires it to its provenance declaration (`app.actor_tier` / `app.actor_system`, read by `platform.actor_tier()`, the history capture and the tier rule). A nested entry is a savepoint inside a transaction that already carries them and emits nothing. A standalone write (`execute_write` outside any transaction) made while the provider has something to say opens its own transaction for that one statement — and still goes through the write queue, inside a copy of the caller's context, so the queue's concurrency gate is kept and the drain task's foreign context cannot hide the declaration (`tests/level1/test_standalone_write_session_context.py`). No provider configured ⇒ no GUCs (standalone behaviour unchanged); a provider that raises fails the transaction loudly rather than committing rows with a false provenance.
 - **The platform access policy** (`matrx_orm.platform_access`): `platform_access_check(actor, token, id, level)` → `iam.has_access_for`. The ONE answer to "may this actor touch this row?", shared with RLS and the file-access gate. Fails closed. Never re-derive it from `organization_id` or `created_by` — both are strict subsets that deny legitimate access.
 
 Public API is defined explicitly in `matrx_orm/__init__.py` (100+ exports). Treat changes there as semver-breaking.

{matrx_orm-3.1.141 → matrx_orm-3.1.142}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matrx-orm
-Version: 3.1.141
+Version: 3.1.142
 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.141 → matrx_orm-3.1.142}/matrx_orm/core/async_db_manager.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import asyncio
+import contextvars
 from dataclasses import dataclass
 import json
 import logging
@@ -1605,25 +1606,46 @@ class AsyncDatabaseManager:
         except ImportError:
             pass
 
+        from matrx_orm.core.write_queue import get_write_queue_registry
+
+        config_name = resolve_database_name(config_name)
+        wq = get_write_queue_registry().get(config_name)
+
         # A declared host session context (notably actor provenance) is made of
         # transaction-local GUCs. A plain standalone write used to skip BEGIN,
         # so its trigger saw the database default even though the caller had
-        # explicitly declared an actor. Keep the declaration in the caller's
-        # task (the write-queue drain has a different ContextVar context) and
-        # use the canonical transaction path for this one write.
+        # explicitly declared an actor — so a declared write takes the
+        # canonical transaction path (BEGIN → GUCs → statement → COMMIT).
+        #
+        # It still goes through the write queue. The queue's drain executes
+        # each item in a task forked from the DRAIN's context, where the
+        # caller's ContextVar declaration is invisible; so the item is run
+        # inside a copy of the caller's context instead of skipping the
+        # queue. Skipping was the first fix (2026-09-12) and it was fine while
+        # only a few doors declared; once the request boundary declares for
+        # EVERY authenticated request, skipping would have moved every
+        # request write off the queue's concurrency gate and onto raw pool
+        # acquires — the pool-storm class the queue exists to prevent.
         from matrx_orm.core.session_context import session_context_gucs
 
         if session_context_gucs():
             from matrx_orm.core.transaction import transaction
 
-            config_name = resolve_database_name(config_name)
-            async with transaction(config_name):
-                return await cls.execute_query(config_name, query, *args, timeout=timeout)
+            async def _declared_write() -> list[dict[str, Any]]:
+                async with transaction(config_name):
+                    return await cls.execute_query(config_name, query, *args, timeout=timeout)
 
-        from matrx_orm.core.write_queue import get_write_queue_registry
+            if wq is None:
+                return await _declared_write()
 
-        config_name = resolve_database_name(config_name)
-        wq = get_write_queue_registry().get(config_name)
+            caller_context = contextvars.copy_context()
+
+            async def _in_caller_context() -> list[dict[str, Any]]:
+                # Awaited by the drain's item task; the inner task carries the
+                # caller's context so the session provider sees the declaration.
+                return await asyncio.create_task(_declared_write(), context=caller_context)
+
+            return await wq.submit(_in_caller_context)
 
         if wq is not None:
             return await wq.submit(

{matrx_orm-3.1.141 → matrx_orm-3.1.142}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.141"
+version = "3.1.142"
 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.142/tests/level1/test_standalone_write_session_context.py

@@ -0,0 +1,139 @@
+"""A declared session context reaches a standalone write's transaction —
+THROUGH the write queue, not around it.
+
+History: the first fix (2026-09-12 12:36) bypassed the queue for a declared
+write because the drain's task cannot see the caller's ContextVar. Once the
+request boundary declares an actor for every authenticated request, that
+bypass would have taken every request write off the queue's concurrency gate.
+The queue is kept and the item runs in a copy of the caller's context.
+"""
+
+from __future__ import annotations
+
+import contextvars
+from contextlib import asynccontextmanager
+
+import asyncio
+import pytest
+
+from matrx_orm.core.async_db_manager import AsyncDatabaseManager
+from matrx_orm.core.session_context import (
+    configure_session_context,
+    declared_actor,
+    declared_actor_gucs,
+    session_context_gucs,
+)
+
+
+class _DrainLikeQueue:
+    """Executes the factory the way the real drain does: in a task forked from
+    a FOREIGN context (one with no declaration), so a factory that relies on
+    the submitter's context being ambient would see nothing."""
+
+    def __init__(self) -> None:
+        self.submitted = 0
+
+    async def submit(self, coro_factory):
+        self.submitted += 1
+        foreign = contextvars.Context()  # empty: no actor declared here
+        task = asyncio.create_task(coro_factory(), context=foreign)
+        return await task
+
+
+@pytest.mark.asyncio
+async def test_declared_write_keeps_the_queue_and_lands_gucs_in_its_transaction(
+    monkeypatch,
+) -> None:
+    events: list[object] = []
+    queue = _DrainLikeQueue()
+
+    @asynccontextmanager
+    async def fake_transaction(database: str):
+        # What the real TransactionContext does at BEGIN: ask the provider.
+        events.append(("begin", database, dict(session_context_gucs())))
+        yield
+        events.append(("commit", database))
+
+    async def fake_execute_query(_cls, config_name: str, query: str, *args, **kwargs):
+        events.append(("write", config_name, query))
+        return [{"id": 1}]
+
+    monkeypatch.setattr("matrx_orm.core.transaction.transaction", fake_transaction)
+    monkeypatch.setattr(AsyncDatabaseManager, "execute_query", classmethod(fake_execute_query))
+    monkeypatch.setattr(
+        "matrx_orm.core.write_queue.get_write_queue_registry",
+        lambda: {"test": queue},
+    )
+    configure_session_context(declared_actor_gucs)
+    try:
+        async with declared_actor("ai", "tool:instance_create"):
+            rows = await AsyncDatabaseManager.execute_write(
+                "test", "INSERT INTO content_ir.kind_instance DEFAULT VALUES RETURNING id"
+            )
+    finally:
+        configure_session_context(None)
+
+    assert rows == [{"id": 1}]
+    assert queue.submitted == 1, "a declared write must still be admitted through the queue"
+    assert events == [
+        (
+            "begin",
+            "test",
+            {"app.actor_tier": "ai", "app.actor_system": "tool:instance_create"},
+        ),
+        ("write", "test", "INSERT INTO content_ir.kind_instance DEFAULT VALUES RETURNING id"),
+        ("commit", "test"),
+    ]
+
+
+@pytest.mark.asyncio
+async def test_declared_write_without_a_queue_opens_its_own_transaction(monkeypatch) -> None:
+    events: list[object] = []
+
+    @asynccontextmanager
+    async def fake_transaction(database: str):
+        events.append(("begin", database, dict(session_context_gucs())))
+        yield
+        events.append(("commit", database))
+
+    async def fake_execute_query(_cls, config_name: str, query: str, *args, **kwargs):
+        events.append(("write", config_name, query))
+        return [{"id": 3}]
+
+    monkeypatch.setattr("matrx_orm.core.transaction.transaction", fake_transaction)
+    monkeypatch.setattr(AsyncDatabaseManager, "execute_query", classmethod(fake_execute_query))
+    monkeypatch.setattr("matrx_orm.core.write_queue.get_write_queue_registry", lambda: {})
+    configure_session_context(declared_actor_gucs)
+    try:
+        async with declared_actor("human", "user-1"):
+            rows = await AsyncDatabaseManager.execute_write("test", "UPDATE t SET x = 1")
+    finally:
+        configure_session_context(None)
+
+    assert rows == [{"id": 3}]
+    assert events[0] == ("begin", "test", {"app.actor_tier": "human", "app.actor_system": "user-1"})
+    assert events[-1] == ("commit", "test")
+
+
+@pytest.mark.asyncio
+async def test_write_without_session_context_keeps_queue_path(monkeypatch) -> None:
+    submitted = False
+
+    class Queue:
+        async def submit(self, _operation):
+            nonlocal submitted
+            submitted = True
+            return [{"id": 2}]
+
+    monkeypatch.setattr(
+        "matrx_orm.core.write_queue.get_write_queue_registry",
+        lambda: {"test": Queue()},
+    )
+    configure_session_context(None)
+
+    rows = await AsyncDatabaseManager.execute_write(
+        "test", "INSERT INTO public.example DEFAULT VALUES"
+    )
+
+    assert rows == [{"id": 2}]
+    assert submitted is True

matrx_orm-3.1.141/tests/level1/test_standalone_write_session_context.py

@@ -1,81 +0,0 @@
-from __future__ import annotations
-
-from contextlib import asynccontextmanager
-
-import pytest
-
-from matrx_orm.core.async_db_manager import AsyncDatabaseManager
-from matrx_orm.core.session_context import configure_session_context
-
-
-@pytest.mark.asyncio
-async def test_declared_session_context_bypasses_queue_and_opens_transaction(monkeypatch) -> None:
-    events: list[object] = []
-
-    class Queue:
-        async def submit(self, _operation):
-            raise AssertionError("declared context must not move to the queue drain task")
-
-    @asynccontextmanager
-    async def fake_transaction(database: str):
-        events.append(("begin", database))
-        yield
-        events.append(("commit", database))
-
-    async def fake_execute_query(_cls, config_name: str, query: str, *args, **kwargs):
-        timeout = kwargs.get("timeout", 10.0)
-        events.append(("write", config_name, query, args, timeout))
-        return [{"id": 1}]
-
-    monkeypatch.setattr("matrx_orm.core.transaction.transaction", fake_transaction)
-    monkeypatch.setattr(AsyncDatabaseManager, "execute_query", classmethod(fake_execute_query))
-    monkeypatch.setattr(
-        "matrx_orm.core.write_queue.get_write_queue_registry",
-        lambda: {"test": Queue()},
-    )
-    configure_session_context(
-        lambda: {"app.actor_tier": "ai", "app.actor_system": "tool:instance_create"}
-    )
-    try:
-        rows = await AsyncDatabaseManager.execute_write(
-            "test", "INSERT INTO content_ir.kind_instance DEFAULT VALUES RETURNING id"
-        )
-    finally:
-        configure_session_context(None)
-
-    assert rows == [{"id": 1}]
-    assert events == [
-        ("begin", "test"),
-        (
-            "write",
-            "test",
-            "INSERT INTO content_ir.kind_instance DEFAULT VALUES RETURNING id",
-            (),
-            10.0,
-        ),
-        ("commit", "test"),
-    ]
-
-
-@pytest.mark.asyncio
-async def test_write_without_session_context_keeps_queue_path(monkeypatch) -> None:
-    submitted = False
-
-    class Queue:
-        async def submit(self, _operation):
-            nonlocal submitted
-            submitted = True
-            return [{"id": 2}]
-
-    monkeypatch.setattr(
-        "matrx_orm.core.write_queue.get_write_queue_registry",
-        lambda: {"test": Queue()},
-    )
-    configure_session_context(None)
-
-    rows = await AsyncDatabaseManager.execute_write(
-        "test", "INSERT INTO public.example DEFAULT VALUES"
-    )
-
-    assert rows == [{"id": 2}]
-    assert submitted is True