matrx-orm 3.1.207__tar.gz → 3.1.209__tar.gz

{matrx_orm-3.1.207 → matrx_orm-3.1.209}/.gitignore

@@ -338,3 +338,8 @@ apps/shared/.kit-*-witness.*/
 .wt/
 .matrx/fixer-dispatch.json
 .matrx/fixer-ledger.json
+
+# Release streak ledger (scripts/release_repeats.py): per-machine state, never committed
+.matrx/release-repeats.json
+.matrx/release-repeats.json.tmp
+.matrx/fixer-ledger.json

{matrx_orm-3.1.207 → matrx_orm-3.1.209}/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+- **Feature: entity doors in the associations engine.** A registry token may resolve to a
+  *door* (`__entity_door__ = True`, `async load_by_ids(ids, *, actor_id) -> {id: row}`) instead of
+  a Model, for nouns whose rows live behind the host's read doors (a record store). The engine
+  reads a door's rows AS THE ACTOR for the write-side existence gate and for `targets_from` /
+  `sources_to`; the access policy still decides on top; with no actor a door finds nothing and the
+  write is refused as not found. New export `matrx_orm.associations.is_entity_door`. Guard:
+  `tests/level1/test_associations.py` (door tests).
 - **Fix: the shared-lock sampler no longer leaves its timeouts on a pooled backend.**
   `pytest_lock_guard` sent session-level `set lock_timeout` / `set statement_timeout`
   through the transaction pooler, where they stay on the backend for the next client

{matrx_orm-3.1.207 → matrx_orm-3.1.209}/CLAUDE.md

@@ -51,7 +51,7 @@ Every table that becomes a Model needs row identity: a single-column primary key
 - **Signals**: `pre_create`, `post_create`, `pre_save`, `post_save`, `pre_delete`, `post_delete`.
 - **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.
+- **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. A token whose rows have no Model (a record store's Records) resolves to an **entity door** (`is_entity_door`: `load_by_ids(ids, *, actor_id)`), read as the actor — never by a service identity.
 - **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.
 

{matrx_orm-3.1.207 → matrx_orm-3.1.209}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matrx-orm
-Version: 3.1.207
+Version: 3.1.209
 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
@@ -26,7 +26,7 @@ Requires-Dist: asyncpg>=0.31.0
 Requires-Dist: cbor2<7,>=6.1.3
 Requires-Dist: cryptography>=43.0
 Requires-Dist: gitpython>=3.1.40
-Requires-Dist: matrx-utils>=2.0.61
+Requires-Dist: matrx-utils>=2.0.63
 Requires-Dist: psycopg-pool>=3.2.5
 Requires-Dist: psycopg[binary]>=3.2.5
 Requires-Dist: python-dotenv>=1.0

{matrx_orm-3.1.207 → matrx_orm-3.1.209}/matrx_orm/associations.py

@@ -79,6 +79,7 @@ __all__ = [
     "EntityRegistry",
     "Associations",
     "UnknownEntityType",
+    "is_entity_door",
     "CrossOrgAssociationError",
     "EntityAccessError",
     "AccessCheck",
@@ -131,6 +132,24 @@ class EntityRef:
     id: str
 
 
+def is_entity_door(endpoint: Any) -> bool:
+    """True when a registry token resolves to an ENTITY DOOR rather than a Model.
+
+    Some nouns a host registers have no table a Model could be generated over — their rows live
+    behind the host's own read doors (a record store's RPCs, a remote service). Such a token
+    resolves to a *door*: any object with ``__entity_door__ = True`` and::
+
+        async def load_by_ids(ids: list[str], *, actor_id: str) -> dict[str, Any]
+
+    returning ``{str(id): row}`` for the ids the ACTOR can open (each row exposes ``id`` and, when
+    it has one, the host's org field as attributes). The engine treats a door exactly like a
+    Model — existence, the access policy, the org fast path — except that the read is made AS
+    the actor, so with no actor (an unattended write) a door finds nothing and the write is
+    refused as not found, never authorized by a service identity.
+    """
+    return bool(getattr(endpoint, "__entity_door__", False))
+
+
 def _registry_model_lookup(schema: str, table: str) -> type[Model] | None:
     """Default ``(schema, table) -> Model`` resolver: scan matrx-orm's model_registry."""
     from matrx_orm.core.registry import model_registry
@@ -578,7 +597,10 @@ class Associations:
         With an actor present and NO policy wired, we refuse rather than fall
         back to org-equality — a host that authorizes user writes must say how.
         """
-        entity = await model.load_by_id_or_none(ref.id)
+        if is_entity_door(model):
+            entity = (await model.load_by_ids([str(ref.id)], actor_id=actor_id)).get(str(ref.id))
+        else:
+            entity = await model.load_by_id_or_none(ref.id)
         if entity is None:
             raise CrossOrgAssociationError(
                 f"cannot associate {ref.type}:{ref.id} — not found or not accessible"
@@ -621,7 +643,9 @@ class Associations:
     _FETCH_CHUNK = 500
 
     @classmethod
-    async def _fetch_many(cls, model: type[Model], ids: list[Any]) -> dict[str, Any]:
+    async def _fetch_many(
+        cls, model: type[Model], ids: list[Any], actor_id: str = ""
+    ) -> 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
@@ -631,9 +655,12 @@ class Associations:
         it falls back to per-id loads — no association endpoint uses one today,
         and this keeps the helper honest if one ever does.
         """
+        unique = list(dict.fromkeys(str(i) for i in ids))
+        if is_entity_door(model):
+            # A door reads as the actor (see ``is_entity_door``); it batches on its own side.
+            return await model.load_by_ids(unique, actor_id=actor_id)
         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 {
@@ -681,7 +708,7 @@ class Associations:
         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)
+        by_id = await self._fetch_many(model, ids, actor)
         out: list[Any] = []
         for rid in ids:
             entity = by_id.get(str(rid))

{matrx_orm-3.1.207 → matrx_orm-3.1.209}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.207"
+version = "3.1.209"
 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.61",
+    "matrx-utils>=2.0.63",
     "pyyaml>=6.0.3",
     "python-dotenv>=1.0",
     "cryptography>=43.0",

{matrx_orm-3.1.207 → matrx_orm-3.1.209}/tests/level1/test_associations.py

@@ -811,3 +811,81 @@ async def test_batched_fetch_chunks_and_still_drops_what_the_gate_refuses():
         f"{total} targets took {ProjectModel.filter_calls} statements; it must take one "
         "per chunk."
     )
+
+
+# --------------------------------------------------------------------------- #
+# Entity doors — a noun whose rows live behind the host's read doors, not a Model
+# --------------------------------------------------------------------------- #
+
+
+class _ScopeDoor:
+    """A noun with no Model (a record store's Records): rows are read AS the actor."""
+
+    __entity_door__ = True
+    rows = {"s1": {"id": "s1", "org_id": "org1", "owner": "alice"}}
+    calls: list = []
+
+    @classmethod
+    async def load_by_ids(cls, ids, *, actor_id):
+        from types import SimpleNamespace
+
+        cls.calls.append((tuple(ids), actor_id))
+        return {
+            i: SimpleNamespace(**cls.rows[i])
+            for i in ids
+            if i in cls.rows and cls.rows[i]["owner"] == actor_id
+        }
+
+
+def _door_assoc(policy):
+    reg = EntityRegistry(token_map={"note": NoteModel, "scope": _ScopeDoor})
+    return Associations(association_model=AssociationRow, registry=reg, access_check=policy)
+
+
+@pytest.mark.asyncio
+async def test_a_door_endpoint_is_filed_when_the_actor_opens_it():
+    """b9cf9424d7 dropped the scope model and every scope endpoint raised UnknownEntityType;
+    a door resolves the noun and reads its row as the actor."""
+    _ScopeDoor.calls = []
+    NoteModel.seed(id="n1", org_id="org1")
+
+    async def policy(actor, token, rid, level):
+        return actor == "alice"
+
+    edge = await _door_assoc(policy).associate(
+        EntityRef("note", "n1"), EntityRef("scope", "s1"), org_id="org1", actor_id="alice"
+    )
+    assert edge.target_type == "scope" and edge.target_id == "s1"
+    assert _ScopeDoor.calls == [(("s1",), "alice")]
+
+
+@pytest.mark.asyncio
+async def test_a_door_endpoint_the_actor_cannot_open_is_refused_and_unattended_finds_nothing():
+    NoteModel.seed(id="n1", org_id="org1")
+
+    async def policy(actor, token, rid, level):
+        return True  # the door's own read is what refuses
+
+    with pytest.raises(CrossOrgAssociationError, match="not found"):
+        await _door_assoc(policy).associate(
+            EntityRef("note", "n1"), EntityRef("scope", "s1"), org_id="org1", actor_id="mallory"
+        )
+    with pytest.raises(CrossOrgAssociationError, match="not found"):
+        await _door_assoc(policy).associate(
+            EntityRef("note", "n1"), EntityRef("scope", "s1"), org_id="org1"
+        )
+
+
+@pytest.mark.asyncio
+async def test_a_door_endpoint_reads_back_through_the_door():
+    AssociationRow.seed(
+        source_type="note", source_id="n1", target_type="scope", target_id="s1", org_id="org1"
+    )
+
+    async def policy(actor, token, rid, level):
+        return True
+
+    rows = await _door_assoc(policy).targets_from(
+        EntityRef("note", "n1"), "scope", org_id="org1", actor_id="alice"
+    )
+    assert [r.id for r in rows] == ["s1"]