matrx-orm 3.1.208__tar.gz → 3.1.210__tar.gz

{matrx_orm-3.1.208 → matrx_orm-3.1.210}/.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.208 → matrx_orm-3.1.210}/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.208 → matrx_orm-3.1.210}/CLAUDE.md

@@ -1,6 +1,6 @@
 # CLAUDE.md — matrx-orm
 
-> 🟢 **RETIREMENT DECIDED 2026-08-22:** this package is being replaced by SQLAlchemy 2 + Alembic under a thin opinion layer and extracted to its own repo. Cross-repo system-of-record: /Users/armanisadeghi/code/common-docs/projects/orm-switch/PLAN.md — read it before touching this feature in ANY repo.
+> 🟢 **RETIREMENT DECIDED 2026-08-22:** this package is being replaced by SQLAlchemy 2 + Alembic under a thin opinion layer and extracted to its own repo. Cross-repo system-of-record: /Users/armanisadeghi/code/common-docs/systems/architecture/database/orm-persistence/projects/orm-switch/PLAN.md — read it before touching this feature in ANY repo.
 
 > **Operating Principle: Build the platform, not the artifact.** Every task is a probe that exposes a missing capability — build it, then consume it. Code that only serves one artifact is forbidden. Full doctrine: [/PRINCIPLES.md](../../PRINCIPLES.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.208 → matrx_orm-3.1.210}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matrx-orm
-Version: 3.1.208
+Version: 3.1.210
 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.62
+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.208 → matrx_orm-3.1.210}/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.208 → matrx_orm-3.1.210}/matrx_orm/secrets_battery/FEATURE.md

@@ -1,6 +1,6 @@
 # matrx-orm secrets battery — the ONE credential vault
 
-> Cross-repo plan (implementation authority): `/Users/armanisadeghi/code/common-docs/projects/unified-credential-vault/PLAN.md` — read it before expanding credential storage or package resolution in any repository. Phase 1 (schema) + Phase 2 (this battery's item layer, rotation script, unified aidream service) are live.
+> Cross-repo plan (implementation authority): `/Users/armanisadeghi/code/common-docs/systems/account/vault-secrets/FEATURE.md` — read it before expanding credential storage or package resolution in any repository. Phase 1 (schema) + Phase 2 (this battery's item layer, rotation script, unified aidream service) are live.
 
 **One table, one key, everywhere.** Every platform credential — personal AND
 organizational — lives in `users.user_secrets` (Fernet-encrypted). Every package
@@ -84,7 +84,7 @@ ownership/shape helper and does not decrypt.
 
 **Native source admission (`native_source.py`).** `validate_native_source` is the server reader of the provider's exact source-v1 byte format; Rust remains the encoder and authenticator. It requires an explicit positive source-size limit, preserves nullable names and bytes, rejects duplicate/noncanonical JSON and COSE, and derives public metadata only after maintained P-256 key-pair validation. The result is provider-custody data, never a response model or generic field. `repr` and fixed failures omit material. `scripts/check_native_source_parity.py --rust-core <native-vault-provider/core>` compares the real compiled Rust reader against the server corpus; no mocked oracle. This prerequisite adds no creator, materializer, database row or native readiness. Verified September19 against132 focused tests and525 cross-language cases.
 
-**Native lifecycle component (`native_lifecycle.py`).** The shared coordinator must supply locked parent/child projections from the exported field constants, current host management authority and its active transaction. Inspection locks the exact native metadata child; component delete/restore mutate only that child's tombstone and lifecycle. Deletion accepts active and restored-quarantined sources; recovery compares aware ISO manifest timestamps to database timestamps, then parses the already-validated manifest instant only at the typed native restore mutation boundary. Personal metadata provenance is enforced by the database guard, never inferred from the request scope. Coordinator/preview integration and actual aggregate database acceptance remain pending; these helpers alone do not enable protected recovery. Contract: [native lifecycle](../../../../../common-docs/projects/credential-sharing-browser-login/NATIVE-LIFECYCLE.md).
+**Native lifecycle component (`native_lifecycle.py`).** The shared coordinator must supply locked parent/child projections from the exported field constants, current host management authority and its active transaction. Inspection locks the exact native metadata child; component delete/restore mutate only that child's tombstone and lifecycle. Deletion accepts active and restored-quarantined sources; recovery compares aware ISO manifest timestamps to database timestamps, then parses the already-validated manifest instant only at the typed native restore mutation boundary. Personal metadata provenance is enforced by the database guard, never inferred from the request scope. Coordinator/preview integration and actual aggregate database acceptance remain pending; these helpers alone do not enable protected recovery. Contract: [native lifecycle](../../../../../common-docs/projects/credential-sharing-browser-login/REGISTER.md).
 
 **`inject_into_sandbox=true` REQUIRES an env alias — refused otherwise.** A
 container environment is a NAME→value map, so a field with `key IS NULL` has

{matrx_orm-3.1.208 → matrx_orm-3.1.210}/matrx_orm/secrets_battery/items.py

@@ -55,7 +55,7 @@ copied into a fork.
 A field lands here when possessing it MINTS future access rather than merely
 holding a value someone already gave you — an authenticator seed generates
 every future code for the account, forever, with nothing recording it. D-15
-(``common-docs/projects/persistent-cloud-browser/DECISIONS.md``) ruled that a
+(``common-docs/systems/architecture/persistent-cloud-browser/VISION.md``) ruled that a
 seed does not travel with an account handover: the new owner enrols again.
 
 🚨 This is deliberately NOT "every ``sealed`` field". Sealed also covers OAuth

{matrx_orm-3.1.208 → matrx_orm-3.1.210}/pyproject.toml

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

{matrx_orm-3.1.208 → matrx_orm-3.1.210}/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"]

{matrx_orm-3.1.208 → matrx_orm-3.1.210}/tests/test_secrets_minting_keys.py

@@ -1,6 +1,6 @@
 """Minting keys never change hands — D-15, enforced in the battery (no DB).
 
-``common-docs/projects/persistent-cloud-browser/DECISIONS.md`` D-15: *"A seed
+``common-docs/systems/architecture/persistent-cloud-browser/VISION.md`` D-15: *"A seed
 does NOT transfer with an account handover — the new owner enrolls again.
 Otherwise two people generate valid codes forever with nothing recording it."*