matrx-orm 3.1.203__tar.gz → 3.1.205__tar.gz

{matrx_orm-3.1.203 → matrx_orm-3.1.205}/BASE_CLASS_METHODS.md

@@ -92,7 +92,7 @@ returned count. Omit the parameter → exact legacy last-write-wins.
 `MatrxEntity.update_with_rebase(id, expected_version=N, **fields)` additionally
 auto-rebases past conflicts whose intervening writes were DISJOINT from the
 written fields (proven from `history.row_versions` snapshots). Cross-repo
-contract: `common-docs/systems/platform/optimistic-concurrency/FEATURE.md`.
+contract: `common-docs/systems/architecture/optimistic-concurrency/FEATURE.md`.
 
 ### Atomic queue claims
 

{matrx_orm-3.1.203 → matrx_orm-3.1.205}/CLAUDE.md

@@ -25,7 +25,7 @@ Every table that becomes a Model needs row identity: a single-column primary key
 - 🚨 **ONE CONNECTION, REQUIRED** (`matrx_orm.platform_db`): `register_platform_db(name, ...)` + `platform_connection_url()` — the ONLY sanctioned way any Matrx service or package turns env vars into a pool. One set of variables (`SUPABASE_MATRIX_*`), owned here; TLS is a deployment input (`SUPABASE_MATRIX_SSL`), never hardcoded; **RAISES** if it isn't given a database — no degraded mode. Every package's `bootstrap_db()` is one call to it. A package may absolutely run on its OWN Postgres — that is a change of VALUES, never a new variable name; what it may never have is a *second candidate* or a fallback chain. `register_database_from_env` is the low-level primitive underneath — **application and package code must not call it directly** (guard: `scripts/check_one_database.py`, blocking in release).
 - **Core model layer**: `Model`, `BaseManager`, `BaseDTO`, `ModelView`, `model_registry`, plus 50+ field types (`CharField`, `IntegerField`, `ForeignKey`, `ManyToManyField`, `JSONField`, …).
 - **`MatrxEntity`** (`matrx_orm/entity.py`) — **the platform entity contract as an ORM primitive.** A table registered in `platform.entity_types` generates as a `MatrxEntity` (everything else stays a plain `Model`) and gets the behavior instead of every consumer hand-wiring it: `await page.versions()` (not a query on `history.row_versions`), `await page.restore(3)` (not a `version_restore` RPC + a cache bust — `restore()` busts the cache itself), `Note.alive()` / `.dead()` / `.soft_delete()` / `.undelete()`, and `Page.capabilities()`. Capability flags (`_entity_token`, `_is_versioned`, `_has_soft_delete`, `_is_org_scoped`, `_rls_variant`) are **stamped by the generator from the LIVE DATABASE** (does the table really carry the `_version_capture` trigger? a `deleted_at` column?) — never from `entity_types`' own flags, which are wrong on 61 of its 242 rows. **The database is truth; a flag is a claim.** Using a capability an entity does not declare RAISES (`EntityCapabilityError`) and names the fix — it never returns silently-wrong data, and `is_deleted` refuses to answer from a column a partial fetch never loaded. Drift guard: `scripts/check_entity_drift.py` (loud, non-blocking, in `release.sh`).
-- **Optimistic concurrency (`expected_version=`)** — opt-in compare-and-swap on the canonical `version` int column: `update_where` / `update_item` / instance `update()` take `expected_version=N` (`WHERE version = N`, `SET version = N + 1`; 0 rows → `DoesNotExist` if gone, `OptimisticLockError` if changed — carrying the **decision package**: `current_version`, `current_row`, `contested_fields` (current values of ONLY the fields this write attempted), and `changed_by`/`changed_at` from `history.row_versions` where versioned); `bulk_update(..., check_version=True)` guards per row; `MatrxEntity.update_with_rebase` auto-rebases past DISJOINT concurrent writes using `history.row_versions` snapshots. **Never automatic** — an unguarded write stays last-write-wins (the `_touch_row` trigger bumps `version` on every update, so auto-guarding would raise spurious conflicts). Contract: `common-docs/systems/platform/optimistic-concurrency/FEATURE.md`.
+- **Optimistic concurrency (`expected_version=`)** — opt-in compare-and-swap on the canonical `version` int column: `update_where` / `update_item` / instance `update()` take `expected_version=N` (`WHERE version = N`, `SET version = N + 1`; 0 rows → `DoesNotExist` if gone, `OptimisticLockError` if changed — carrying the **decision package**: `current_version`, `current_row`, `contested_fields` (current values of ONLY the fields this write attempted), and `changed_by`/`changed_at` from `history.row_versions` where versioned); `bulk_update(..., check_version=True)` guards per row; `MatrxEntity.update_with_rebase` auto-rebases past DISJOINT concurrent writes using `history.row_versions` snapshots. **Never automatic** — an unguarded write stays last-write-wins (the `_touch_row` trigger bumps `version` on every update, so auto-guarding would raise spurious conflicts). Contract: `common-docs/systems/architecture/optimistic-concurrency/FEATURE.md`.
 - **Change tracking** — every instance records which columns were **loaded** (a SELECTed row, or the caller's kwargs) and which were **changed**. `save()` writes only those, so `.only("id","email")` + `save()` can never NULL the columns it never fetched (it used to — silent data loss). Mutable containers (jsonb/arrays) are always rewritten when loaded, because `obj.metadata["k"]=1` cannot be seen by `__setattr__`; **reassigning** (`obj.metadata = {...}`) is tracked precisely and is the sanctioned way. `Model._hydrate()` is the ONE row→model entry point.
 - **Upsert writes only what the caller supplied.** `upsert` / `bulk_upsert` / `upsert_with_conflict` materialize every field's Python default so the **INSERT** half is complete — but `ON CONFLICT DO UPDATE SET` covers **only the columns present in the caller's `data`** (an explicit `update_fields` still wins). Letting defaults reach the UPDATE half silently RESET every defaulted column on each re-upsert of an existing row: it once reset scraped-and-analyzed `research.rs_source` rows to `scrape_status='pending', server_attempts=0` (a watchdog then finalized them `'failed'`) and undid users' manual `is_included=false`. A caller-supplied `None` is excluded too — it is dropped from the INSERT, and `EXCLUDED.<col>` on an omitted column resolves to that column's **DEFAULT**. An upsert of only conflict keys means "ensure this row exists" and reconciles to a no-op self-assignment, never a raise (a bare `DO NOTHING` would break `RETURNING *`). Pinned by `tests/level1/test_upsert_default_leak.py`.
 - **Read-only models** (`_read_only = True`): a model that can be queried but NEVER written through the ORM — every write path raises `ReadOnlyModelError` (enforced at `QueryExecutor.insert/bulk_insert/upsert/update/delete`, so it covers all of `create`/`save`/`update`/`delete`/`update_where`/`delete_where`/`upsert`/`bulk_*`). Used for DB-managed tables the app must not mutate. The canonical **`auth.users`** model is baked into the schema generator (`get_string_user_model`) as the full, curated Supabase auth schema (safe columns only — no password/token fields), `_read_only`, bound per-database. Read a user's profile/metadata there; mutate users only through Supabase Auth (GoTrue).

{matrx_orm-3.1.203 → matrx_orm-3.1.205}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matrx-orm
-Version: 3.1.203
+Version: 3.1.205
 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.59
+Requires-Dist: matrx-utils>=2.0.60
 Requires-Dist: psycopg-pool>=3.2.5
 Requires-Dist: psycopg[binary]>=3.2.5
 Requires-Dist: python-dotenv>=1.0

{matrx_orm-3.1.203 → matrx_orm-3.1.205}/matrx_orm/__init__.py

@@ -263,10 +263,12 @@ from .core.session_context import (
     ACTOR_AGENT_GUC,
     ACTOR_SYSTEM_GUC,
     ACTOR_TIER_GUC,
+    RETIRED_TIER_WORDS,
     VALID_TIERS,
     ActorRef,
     ActorTier,
     SessionContextProvider,
+    canonical_actor_tier,
     configure_session_context,
     current_actor,
     current_tier,
@@ -703,9 +705,11 @@ __all__ = [
     "ACTOR_AGENT_GUC",
     "ACTOR_SYSTEM_GUC",
     "ACTOR_TIER_GUC",
+    "RETIRED_TIER_WORDS",
     "VALID_TIERS",
     "ActorRef",
     "ActorTier",
+    "canonical_actor_tier",
     "configure_session_context",
     "current_actor",
     "current_tier",

{matrx_orm-3.1.203 → matrx_orm-3.1.205}/matrx_orm/core/db_function.py

@@ -150,6 +150,29 @@ class TypedArg:
         return ".".join(f'"{seg}"' for seg in str(self.pg_type).split("."))
 
 
+def uuid_list_kind(value: list[Any]) -> bool:
+    """``True`` when ``value`` is a non-empty list of ``uuid.UUID`` — a ``uuid[]`` argument.
+
+    A list holding ONLY ``uuid.UUID`` objects can never be a jsonb argument (``json.dumps``
+    cannot encode one), so it can only mean a native ``uuid[]`` parameter; it binds as one,
+    with the explicit cast :class:`ArrayArg` would give it. A list MIXING ``uuid.UUID`` with
+    other values is ambiguous and is refused by name (VISION-REACH W2, 2026-10-02: the
+    records tool's roll-up raised ``Object of type UUID is not JSON serializable`` on every
+    call because a list of UUIDs was taken for jsonb).
+    """
+    import uuid as _uuid
+
+    if not value or not any(isinstance(v, _uuid.UUID) for v in value):
+        return False
+    if all(isinstance(v, _uuid.UUID) for v in value):
+        return True
+    raise TypeError(
+        "call_function: a list mixes uuid.UUID objects with other values, so it is neither a "
+        "uuid[] nor a jsonb argument. Pass ArrayArg(values, \"uuid\") with every element a "
+        "UUID (or its text), or a list of plain JSON values for a jsonb parameter."
+    )
+
+
 def _bind_args(args: tuple[Any, ...]) -> tuple[str, list[Any]]:
     """Build the ``$1, $2, ...`` placeholder list + bound values.
 
@@ -175,6 +198,9 @@ def _bind_args(args: tuple[Any, ...]) -> tuple[str, list[Any]]:
             suffix = f"::{value.element_type}[]" if value.element_type else ""
             placeholders.append(f"${idx}{suffix}")
             bound.append(value.value)
+        elif isinstance(value, list) and uuid_list_kind(value):
+            placeholders.append(f"${idx}::uuid[]")
+            bound.append(value)
         elif isinstance(value, dict | list):
             placeholders.append(f"${idx}::jsonb")
             bound.append(json.dumps(value))

{matrx_orm-3.1.203 → matrx_orm-3.1.205}/matrx_orm/core/introspection.py

@@ -64,7 +64,7 @@ async def introspect_rls_policies(
     ``schemas``/``relnames`` are PARALLEL arrays (zipped server-side via
     ``unnest``) — e.g. ``schemas=["public","workspace"],
     relnames=["notes","tasks"]`` audits ``public.notes`` and
-    ``workspace.tasks``. Both are bound array parameters, never
+    ``projects.tasks``. Both are bound array parameters, never
     string-interpolated. Returns one row per table that actually exists
     (callers should treat a missing pair as "table not found").
 

{matrx_orm-3.1.203 → matrx_orm-3.1.205}/matrx_orm/core/session_context.py

@@ -9,7 +9,7 @@ reliably apply them is the moment this package opens a transaction.
 The host declares a provider once at startup::
 
     from matrx_orm import configure_session_context
-    configure_session_context(lambda: {"app.actor_tier": "ai", "app.actor_system": "x"})
+    configure_session_context(lambda: {"app.actor_tier": "agent", "app.actor_system": "x"})
 
 and from then on every TOP-LEVEL ``transaction()`` (which includes the one
 ``rls_session`` opens, before it drops to the restricted role) emits whatever
@@ -134,11 +134,11 @@ async def apply_session_context(connection: Any) -> None:
 # The host (aidream) re-exports these names and wires ``declared_actor_gucs``
 # into ``configure_session_context`` at startup.
 #
-# CONVERGE: actor tier literal code|ai|human; target vocabulary
-# system|agent|user - declared 2026-09-10, Data Doctrine 1.5/7.
+# Tier words (DD-064): ``system`` (the platform's own machinery), ``agent`` (an
+# agent's turn), ``user`` (a person's own action).
 # ---------------------------------------------------------------------------
 
-ActorTier = Literal["code", "ai", "human"]
+ActorTier = Literal["system", "agent", "user"]
 
 ACTOR_TIER_GUC = "app.actor_tier"
 ACTOR_SYSTEM_GUC = "app.actor_system"
@@ -149,7 +149,24 @@ ACTOR_SYSTEM_GUC = "app.actor_system"
 # control that saves a value nothing honours.
 ACTOR_AGENT_GUC = "app.actor_agent"
 
-VALID_TIERS: frozenset[str] = frozenset({"code", "ai", "human"})
+VALID_TIERS: frozenset[str] = frozenset({"system", "agent", "user"})
+
+#: DD-064 transition: the retired spellings and the word each became. The
+#: database accepts both on every channel and answers in the new words, but
+#: ``history.row_versions.actor_tier`` keeps the old words on rows written
+#: before the rename, so every reader of a stored tier normalizes through
+#: :func:`canonical_actor_tier` (mirrors ``platform.canonical_actor_tier``).
+RETIRED_TIER_WORDS: Mapping[str, str] = {"code": "system", "ai": "agent", "human": "user"}
+
+
+def canonical_actor_tier(value: object) -> ActorTier | None:
+    """The tier in the current words: old -> new, new passes through, else None."""
+    if not isinstance(value, str):
+        return None
+    word = value.strip().lower()
+    if word in VALID_TIERS:
+        return word  # type: ignore[return-value]
+    return RETIRED_TIER_WORDS.get(word)  # type: ignore[return-value]
 
 
 @dataclass(frozen=True, slots=True)
@@ -160,7 +177,7 @@ class ActorRef:
     system: str | None = None
     #: The agent definition id, when the writer IS an agent (DD-211). A
     #: person's write never carries one -- the database refuses the pair
-    #: ``tier="human"`` + an agent, because "a person did this" and "agent X
+    #: ``tier="user"`` + an agent, because "a person did this" and "agent X
     #: did this" are two different authors.
     agent: str | None = None
 
@@ -198,7 +215,7 @@ def declared_actor_gucs() -> dict[str, str]:
 
     This is the provider a host passes to :func:`configure_session_context`.
     Empty when nothing declared an actor: the DB resolver then applies its
-    documented default (``human`` with an identity present, ``code`` without)
+    documented default (``user`` with an identity present, ``system`` without)
     and logs that it did.
 
     The WORKFLOW CHAIN rides the same provider (it is part of "who is writing":
@@ -278,20 +295,22 @@ def declaring_workflow_chain(chain: WorkflowChain | None) -> Iterator[WorkflowCh
 
 
 def _validated_actor(tier: str, system: str, agent: str | None, *, caller: str) -> ActorRef:
-    if tier not in VALID_TIERS:
+    canonical = canonical_actor_tier(tier)
+    if canonical is None:
         raise ValueError(f"{caller} tier must be one of {sorted(VALID_TIERS)}; got {tier!r}")
+    tier = canonical
     if not system or not system.strip():
         raise ValueError(f"{caller} requires a non-empty system (who specifically)")
     cleaned = (agent or "").strip() or None
     if cleaned is not None:
-        if tier == "human":
+        if tier == "user":
             # The database refuses this pair outright (23514). Refusing it here
             # too means the door that made the mistake learns at the call site
             # rather than on whichever write happens to land first.
             raise ValueError(
-                f"{caller} was given tier='human' AND agent={cleaned!r}. A person's write carries "
+                f"{caller} was given tier='user' AND agent={cleaned!r}. A person's write carries "
                 "no agent: either the person is the author (drop the agent) or the agent is "
-                "(declare tier='ai' and the agent that is running)."
+                "(declare tier='agent' and the agent that is running)."
             )
         try:
             UUID(cleaned)
@@ -357,11 +376,13 @@ __all__ = [
     "ACTOR_AGENT_GUC",
     "ACTOR_SYSTEM_GUC",
     "ACTOR_TIER_GUC",
+    "RETIRED_TIER_WORDS",
     "VALID_TIERS",
     "ActorRef",
     "ActorTier",
     "SessionContextProvider",
     "apply_session_context",
+    "canonical_actor_tier",
     "emit_local_gucs",
     "local_gucs_statement",
     "configure_session_context",

matrx_orm-3.1.205/matrx_orm/matrx_orm_production_door.pth

@@ -0,0 +1,3 @@
+# Installed by matrx-orm: in a process whose environment carries MATRX_PRODUCTION_DOOR=1 (exported by the
+# pytest plugin matrx_orm.pytest_production_door), install the same production door before any user code.
+import os; exec("import sys, importlib.util as u, importlib.machinery as m\ns = m.PathFinder.find_spec('matrx_orm')\nif s and s.submodule_search_locations and 'matrx_orm.pytest_production_door' not in sys.modules:\n    sp = u.spec_from_file_location('matrx_orm.pytest_production_door', list(s.submodule_search_locations)[0] + '/pytest_production_door.py')\n    mod = u.module_from_spec(sp); sys.modules[sp.name] = mod; sp.loader.exec_module(mod); mod.install()") if os.environ.get("MATRX_PRODUCTION_DOOR") == "1" else None

{matrx_orm-3.1.203 → matrx_orm-3.1.205}/matrx_orm/operations/db_functions.py

@@ -24,6 +24,8 @@ import json
 import re
 from typing import TYPE_CHECKING, Any
 
+from matrx_orm.core.db_function import uuid_list_kind
+
 if TYPE_CHECKING:  # pragma: no cover
     from matrx_orm.core.base import Model
 
@@ -38,7 +40,12 @@ def _render_call(function_name: str, args: tuple[Any, ...]) -> tuple[str, list[A
     placeholders: list[str] = []
     values: list[Any] = []
     for index, arg in enumerate(args, start=1):
-        if isinstance(arg, dict | list):
+        if isinstance(arg, list) and uuid_list_kind(arg):
+            # A list of uuid.UUID is a uuid[] argument; `default=str` below would have
+            # turned it into a jsonb array of text and missed the uuid[] overload.
+            placeholders.append(f"${index}::uuid[]")
+            values.append(arg)
+        elif isinstance(arg, dict | list):
             placeholders.append(f"${index}::jsonb")
             values.append(json.dumps(arg, ensure_ascii=False, default=str))
         else:

{matrx_orm-3.1.203 → matrx_orm-3.1.205}/matrx_orm/pytest_production_door.py

@@ -21,9 +21,21 @@ and every ``psycopg_pool`` pool), ``psycopg2.connect``, ``asyncpg.connect`` / ``
 plugin loads is patched on import.
 
 THE ONE EXCEPTION: ``db.pooled_read.read_only("production")`` opens its connection inside
-:func:`production_read_only` and then runs ``begin read only`` before handing out a cursor, so a production
-read in a test is a transaction that cannot write. Nothing else — no flag, no environment variable — opens
-this door. Not covered: a libpq service file or ``~/.pgpass`` host that the environment does not name.
+:func:`production_read_only`, and that connection is the least-privilege role ``matrx_reader`` (``pg_read_all_data``
+only, no write grant) — the role is the door; the read-only transaction and statement check there are defence in
+depth. Nothing else — no flag, no environment variable — opens this door. Designed doors the reader role leaves
+open (accepted 2026-10-02): ``lo_create`` and the SECURITY DEFINER functions granted to PUBLIC, which write as
+their owner once a session turns its read-only default off. Child Python processes carry it too: the plugin exports ``MATRX_PRODUCTION_DOOR=1`` and the
+``matrx_orm_production_door.pth`` this package installs puts the same door in any process started with it.
+``psql`` / ``pg_dump`` / ``pg_dumpall`` / ``pg_restore`` are matched anywhere in a command line (argv, ``bash -c`` /
+``sh -c`` strings, ``shell=True``, ``os.system``) after ``$VAR`` / ``${VAR}`` are resolved against the child's environment.
+
+The door stops ACCIDENTAL production writes by tests, not a determined insider. Residual, deliberately not closed:
+- the public exception helpers and module flag (``production_read_only``, ``_READ_ONLY_PRODUCTION``) are a deliberate bypass;
+- ``-p no:matrx_production_door`` or ``PYTEST_DISABLE_PLUGIN_AUTOLOAD`` from a package root (no root conftest) skips it;
+- private driver internals (``pgconn``, ``asyncpg.connect_utils``) and ``importlib.reload`` of a driver bypass the wrappers;
+- a host given only as an IP address or ``hostaddr`` (no ref, no production name) is not recognized;
+- raw sockets, and a libpq service file or ``~/.pgpass`` host the environment does not name.
 
 Guard: ``aidream/tests/test_tests_never_write_production.py`` (plants per bypass class).
 """
@@ -34,6 +46,7 @@ import contextvars
 import importlib.abc
 import importlib.util
 import os
+import re
 import subprocess
 import sys
 from collections.abc import Iterator
@@ -55,7 +68,7 @@ class ProductionDoorRefusal(RuntimeError):
 
 @contextmanager
 def production_read_only() -> Iterator[None]:
-    """Open ONE production connection that the caller turns into ``begin read only`` before any statement."""
+    """Admit ONE production connection: the read-only helper's, made as the least-privilege reader role."""
     token = _READ_ONLY_PRODUCTION.set(True)
     try:
         yield
@@ -252,40 +265,75 @@ def _patch_orm_registry(mod: Any) -> None:
     registry_cls.register = register
 
 
-def _psql_argv(args: Any, shell: bool) -> list[str] | None:
-    """The command line as words when it runs ``psql`` (directly or inside a shell string), else None."""
-    words = args.split() if isinstance(args, str | bytes) else [str(a) for a in args] if args else []
-    words = [w.decode() if isinstance(w, bytes) else w for w in words]
-    if any(os.path.basename(w) == "psql" for w in words):
-        return words
-    return None
+#: The libpq command-line clients that open a database connection.
+_PG_CLIENT = re.compile(r"(?:^|[\s/;&|(`'\"])(psql|pg_dump|pg_dumpall|pg_restore)(?=$|[\s;&|)`'\"])")
+_VAR = re.compile(r"\$\{(\w+)\}|\$(\w+)")
+_FLAGS = {"-h": "host", "--host": "host", "-U": "user", "--username": "user", "-d": "dbname", "--dbname": "dbname"}
+
+
+def _command_text(args: Any) -> str:
+    """The whole command line as one string: a shell string as given, an argv joined (so ``bash -c "…"`` shows)."""
+    if isinstance(args, bytes):
+        return args.decode(errors="replace")
+    if isinstance(args, str):
+        return args
+    try:
+        return " ".join(a.decode(errors="replace") if isinstance(a, bytes) else str(a) for a in args)
+    except TypeError:
+        return str(args)
+
+
+def check_command(what: str, args: Any, env: Any = None) -> None:
+    """Refuse a psql / pg_dump / pg_dumpall / pg_restore command line whose target names production.
+
+    ``$VAR`` and ``${VAR}`` are resolved against the environment the child will see, and the child's ``PG*``
+    variables count as libpq defaults, exactly as the client would read them.
+    """
+    text = _command_text(args)
+    match = _PG_CLIENT.search(text)
+    if match is None:
+        return
+    child_env = {str(k): str(v) for k, v in (env if env is not None else os.environ).items()}
+    expanded = _VAR.sub(lambda m: child_env.get(m.group(1) or m.group(2), m.group(0)), text)
+    words = expanded.split()
+    kwargs: dict[str, str] = {}
+    for i, w in enumerate(words):
+        key, sep, value = w.partition("=")
+        if key in _FLAGS and sep:
+            kwargs[_FLAGS[key]] = value
+        elif w in _FLAGS and i + 1 < len(words):
+            kwargs[_FLAGS[w]] = words[i + 1]
+    saved = dict(os.environ)
+    try:
+        if env is not None:  # the client sees the child's environment, not ours
+            os.environ.clear()
+            os.environ.update(child_env)
+        check(f"{match.group(1)} ({what})", expanded, **kwargs)
+    finally:
+        if env is not None:
+            os.environ.clear()
+            os.environ.update(saved)
 
 
 def _patch_subprocess() -> None:
     original = subprocess.Popen.__init__
-    if getattr(original, "_production_door", False):
-        return
+    if not getattr(original, "_production_door", False):
 
-    def __init__(self: Any, args: Any, *a: Any, **kw: Any) -> None:
-        words = _psql_argv(args, bool(kw.get("shell")))
-        if words is not None:
-            env = kw.get("env")
-            saved = dict(os.environ)
-            try:
-                if env is not None:  # psql sees the child's environment, not ours
-                    os.environ.clear()
-                    os.environ.update({str(k): str(v) for k, v in env.items()})
-                flags = {"-h": "host", "--host": "host", "-U": "user", "--username": "user", "-d": "dbname", "--dbname": "dbname"}
-                kwargs = {flags[w]: words[i + 1] for i, w in enumerate(words[:-1]) if w in flags}
-                check("psql (subprocess)", " ".join(words), **kwargs)
-            finally:
-                if env is not None:
-                    os.environ.clear()
-                    os.environ.update(saved)
-        original(self, args, *a, **kw)
-
-    __init__._production_door = True  # type: ignore[attr-defined]
-    subprocess.Popen.__init__ = __init__  # type: ignore[method-assign]
+        def __init__(self: Any, args: Any, *a: Any, **kw: Any) -> None:
+            check_command("subprocess", args, kw.get("env"))
+            original(self, args, *a, **kw)
+
+        __init__._production_door = True  # type: ignore[attr-defined]
+        subprocess.Popen.__init__ = __init__  # type: ignore[method-assign]
+    original_system = os.system
+    if not getattr(original_system, "_production_door", False):
+
+        def system(command: Any) -> int:
+            check_command("os.system", command)
+            return original_system(command)
+
+        system._production_door = True  # type: ignore[attr-defined]
+        os.system = system
 
 
 _PATCHERS = {
@@ -326,8 +374,33 @@ class _PatchOnImport(importlib.abc.MetaPathFinder, importlib.abc.Loader):
         return spec
 
 
+#: Exported into the environment so every child Python process installs the same door (see the .pth below).
+CHILD_MARKER = "MATRX_PRODUCTION_DOOR"
+_PTH_NAME = "matrx_orm_production_door.pth"
+
+
+def ensure_child_hook() -> None:
+    """Make sure the interpreter's site-packages carries the .pth that installs this door in a child process.
+
+    The matrx-orm wheel ships it (hatch force-include); an editable or stale install may not, so the plugin
+    writes the packaged copy beside the other .pth files on first use. Idempotent; a read-only site is left alone.
+    """
+    import sysconfig
+
+    source = os.path.join(os.path.dirname(__file__), _PTH_NAME)
+    target = os.path.join(sysconfig.get_paths()["purelib"], _PTH_NAME)
+    try:
+        wanted = open(source, encoding="utf-8").read()
+        if not os.path.exists(target) or open(target, encoding="utf-8").read() != wanted:
+            with open(target, "w", encoding="utf-8") as fh:
+                fh.write(wanted)
+    except OSError:
+        pass
+
+
 def install() -> None:
     """Wrap every driver already imported, and every one imported later. Idempotent."""
+    os.environ[CHILD_MARKER] = "1"
     _patch_subprocess()
     for name, patch in _PATCHERS.items():
         if name in sys.modules:
@@ -346,8 +419,10 @@ def install() -> None:
 
 
 def pytest_load_initial_conftests(early_config: Any, parser: Any, args: Any) -> None:
+    ensure_child_hook()
     install()
 
 
 def pytest_configure(config: Any) -> None:
+    ensure_child_hook()
     install()  # idempotent: covers a registration through the root conftest's fallback

{matrx_orm-3.1.203 → matrx_orm-3.1.205}/matrx_orm/schema_builder/excluded_targets.py

@@ -11,8 +11,8 @@ The excluded set is qualified (``schema.table``) and spans every ``generate[]``
 database, because the referencing table usually lives in another schema's run.
 
 The same holds for a table in a schema the host never models: a foreign key follows its table's
-oid, so once a retired table moves to ``graveyard`` every reference to it reads
-``to_schema='graveyard'`` — a class the registry can never hold. A reference whose target schema
+oid, so once a retired table moves to ``deprecated`` every reference to it reads
+``to_schema='deprecated'`` — a class the registry can never hold. A reference whose target schema
 is neither generated nor one of the database's ``additional_schemas`` is dropped the same way.
 """
 

{matrx_orm-3.1.203 → matrx_orm-3.1.205}/matrx_orm/schema_builder/schema_manager.py

@@ -98,7 +98,7 @@ class SchemaManager:
         #: ``schema.table`` names excluded from generation in ANY generate[] entry of this database:
         #: a reference to one is dropped at load (``excluded_targets.drop_references_to``).
         self._excluded_fk_targets: frozenset[str] = frozenset(excluded_fk_targets or ())
-        #: Schemas the host models; a reference into any other (``graveyard``) is dropped the same way.
+        #: Schemas the host models; a reference into any other (``deprecated``) is dropped the same way.
         self._modeled_schemas: frozenset[str] | None = (
             frozenset(modeled_schemas) if modeled_schemas is not None else None
         )

{matrx_orm-3.1.203 → matrx_orm-3.1.205}/matrx_orm/session/dag.py

@@ -136,7 +136,7 @@ def _resolve_fk_deps(
             continue
         # Resolving a bare-name FK reference can RAISE (ambiguous across
         # databases, or a target whose model set was never imported — e.g. the
-        # `graveyard` schema). Neither is a reason to fail a WRITE: an
+        # `deprecated` schema). Neither is a reason to fail a WRITE: an
         # unresolvable target cannot be a parent row in THIS flush, so it
         # contributes no ordering constraint. Letting the raise escape is what
         # detonated the 2026-07-11 'Users' persistence outage — an ambiguous

{matrx_orm-3.1.203 → matrx_orm-3.1.205}/matrx_orm/write_actor.py

@@ -1,7 +1,7 @@
 """ONE DOOR: a write to a table that refuses an unnamed actor names one here.
 
 🚨 THE CLASS THIS CLOSES (2026-09-17). ``platform.associations`` refuses a write
-that declares ``actor_tier=code`` and names no system — "an AI did it" with no
+that declares ``actor_tier=system`` and names no system — "an AI did it" with no
 name is not provenance — and it reads that name from ``SET LOCAL`` GUCs, which
 exist only inside a transaction that declared them.
 
@@ -58,7 +58,7 @@ __all__ = [
 ]
 
 #: ``(schema, table)`` pairs whose database-side rule refuses a write that
-#: declares ``actor_tier=code`` and names no system. Membership is what makes
+#: declares ``actor_tier=system`` and names no system. Membership is what makes
 #: the seam speak; every other table's writes are untouched (no extra
 #: transaction, no extra round trip).
 ACTOR_REQUIRED_TABLES: frozenset[tuple[str, str]] = frozenset(
@@ -180,7 +180,7 @@ def writing_system() -> str:
         "A write to an actor-required table could not name the code making it. "
         f"The outermost frame the seam could read was {where}, and every frame above "
         "it belongs to the ORM or to async plumbing. Declare the actor at the call "
-        "site — `async with actor_session('code', '<your system>'):` — rather than "
+        "site — `async with actor_session('system', '<your system>'):` — rather than "
         "letting an unnamed write reach the database, which would be refused there "
         "anyway, at CASCADE time, nowhere near here."
     )
@@ -225,7 +225,7 @@ async def actor_named_for_write(database: str) -> AsyncIterator[None]:
     # the enclosing transaction — which is correct: the enclosing work had no
     # actor either.
     async with transaction(database=database):
-        with declaring_actor("code", system) as actor:
+        with declaring_actor("system", system) as actor:
             await set_local_gucs(actor.as_gucs())
             yield
 

{matrx_orm-3.1.203 → matrx_orm-3.1.205}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.203"
+version = "3.1.205"
 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.59",
+    "matrx-utils>=2.0.60",
     "pyyaml>=6.0.3",
     "python-dotenv>=1.0",
     "cryptography>=43.0",
@@ -84,6 +84,9 @@ dev = [
 packages = ["matrx_orm"]
 include = ["matrx_orm/py.typed", "matrx_orm/resources/*.json"]
 
+[tool.hatch.build.targets.wheel.force-include]
+"matrx_orm/matrx_orm_production_door.pth" = "matrx_orm_production_door.pth"
+
 [tool.hatch.metadata]
 allow-direct-references = true
 

{matrx_orm-3.1.203 → matrx_orm-3.1.205}/tests/level1/test_association_trigger_actor_naming.py

@@ -33,6 +33,7 @@ from contextlib import asynccontextmanager
 
 import pytest
 from matrx_orm.core.session_context import (
+    canonical_actor_tier,
     configure_session_context,
     current_actor,
     declared_actor_gucs,
@@ -44,11 +45,11 @@ from matrx_orm.write_actor import actor_named_for_write
 def _would_the_database_refuse(gucs: dict[str, str]) -> bool:
     """``platform._stamp_actor_tier()``'s refusal clause (``wf_051``): an
     unset or empty ``app.actor_system`` GUC is NULL to the database, and a
-    ``code``/``ai`` tier with a NULL system is refused. A ``human`` write (or
+    ``system``/``agent`` tier with a NULL system is refused. A ``user`` write (or
     one with a real name) is not."""
-    tier = gucs.get("app.actor_tier") or "code"
+    tier = canonical_actor_tier(gucs.get("app.actor_tier") or "") or "system"
     system = (gucs.get("app.actor_system") or "").strip() or None
-    return tier in ("ai", "code") and system is None
+    return tier in ("agent", "system") and system is None
 
 
 @pytest.fixture(autouse=True)
@@ -121,7 +122,7 @@ async def test_actor_named_for_write_names_the_actor_the_trigger_needs(monkeypat
     seen_gucs = set_gucs
 
     assert not _would_the_database_refuse(seen_gucs), seen_gucs
-    assert seen_gucs["app.actor_tier"] == "code"
+    assert seen_gucs["app.actor_tier"] == "system"
     # The calling frame (this test module), never a hand-typed constant.
     assert seen_gucs["app.actor_system"] == "level1.test_association_trigger_actor_naming"
     assert current_actor() is None, "the declaration must not outlive the block"
@@ -145,9 +146,9 @@ async def test_actor_named_for_write_passes_through_an_existing_declaration(monk
 
     monkeypatch.setattr(transaction_module, "transaction", fake_transaction)
 
-    async with declared_actor("human", "user-42"):
+    async with declared_actor("user", "user-42"):
         async with actor_named_for_write("main"):
-            assert current_actor().tier == "human"
+            assert current_actor().tier == "user"
             assert current_actor().system == "user-42"
 
     assert opened is False, "a caller that already declared an actor is trusted as-is"

{matrx_orm-3.1.203 → matrx_orm-3.1.205}/tests/level1/test_catalog.py

@@ -22,7 +22,7 @@ async def test_list_relations_binds_all_filters(query_spy):
         "main",
         schemas=["public"],
         kinds=("BASE TABLE",),
-        exclude_schemas=["graveyard"],
+        exclude_schemas=["deprecated"],
     ) == []
     database, sql, schemas, kinds, excluded = query_spy[0]
     assert database == "main"
@@ -32,21 +32,21 @@ async def test_list_relations_binds_all_filters(query_spy):
     assert "information_schema" not in sql
     assert schemas == ["public"]
     assert kinds == ["BASE TABLE"]
-    assert excluded == ["graveyard"]
+    assert excluded == ["deprecated"]
 
 
 @pytest.mark.asyncio
 async def test_relation_discovery_and_description_bind_values(query_spy):
     await catalog.application_schemas("main", exclude_schemas=["pg_catalog"])
     await catalog.relation_schemas(
-        "main", table="message", exclude_schemas=["graveyard"]
+        "main", table="message", exclude_schemas=["deprecated"]
     )
     await catalog.describe_relation_columns(
         "main", schema="chat", table="message"
     )
 
     assert query_spy[0][2:] == (["pg_catalog"],)
-    assert query_spy[1][2:] == ("message", ["graveyard"])
+    assert query_spy[1][2:] == ("message", ["deprecated"])
     assert query_spy[2][2:] == ("chat", "message")
     # These decide EXISTENCE, so they must be privilege-independent.
     assert "pg_namespace" in query_spy[0][1]

{matrx_orm-3.1.203 → matrx_orm-3.1.205}/tests/level1/test_rls_session_scope.py

@@ -164,7 +164,7 @@ async def test_declared_context_and_rls_settings_share_one_round_trip_role_last(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
     """The host's declared context, the ceilings and the RLS settings: ONE statement."""
-    monkeypatch.setattr(session_context, "_provider", lambda: {"app.actor_tier": "human"})
+    monkeypatch.setattr(session_context, "_provider", lambda: {"app.actor_tier": "user"})
     monkeypatch.setattr(transaction_module, "_TRANSACTION_CEILINGS", {"lock_timeout": "5000"})
     conn, _adapter = _install_adapter(monkeypatch)