matrx-orm 3.1.174__tar.gz → 3.1.182__tar.gz

{matrx_orm-3.1.174 → matrx_orm-3.1.182}/.gitignore

@@ -197,6 +197,14 @@ cython_debug/
 # Frontend pnpm workspace (apps/) — node_modules at the workspace root and any
 # member, plus Vite caches and build output. The unified lockfile (apps/pnpm-lock.yaml)
 # IS committed; everything below is regenerated.
+#
+# 🚨 BOTH SPELLINGS. `node_modules/` with the slash matches a DIRECTORY only, so
+# a SYMLINK named `node_modules` slipped straight past it: five of them — each
+# an absolute path into one machine's checkout — were committed on main and
+# broke `pnpm install --frozen-lockfile` on every CI runner, where the symlink
+# is dangling and pnpm's `mkdir` of it answers ENOENT. Every package release was
+# blocked by it. The bare spelling below matches the symlink too.
+node_modules
 node_modules/
 apps/**/.vite/
 apps/**/dist/
@@ -328,3 +336,5 @@ apps/shared/.kit-*-witness.*/
 # They live at .wt/<slug> (disk-groom). Committing the folder would add a
 # second copy of the entire tree and a symlink into common-docs.
 .wt/
+.matrx/fixer-dispatch.json
+.matrx/fixer-ledger.json

matrx_orm-3.1.182/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## 3.1.182
+
+- 3.1.181 was tagged against a commit that did not carry the version and never
+  published; 3.1.182 is the same code plus everything since.

{matrx_orm-3.1.174 → matrx_orm-3.1.182}/PKG-INFO

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

{matrx_orm-3.1.174 → matrx_orm-3.1.182}/matrx_orm/__init__.py

@@ -72,7 +72,13 @@ from .core.diagnostics import (
     long_transactions,
     long_transactions_sql,
 )
-from .core.introspection import introspect_columns, introspect_rls_policies, schema_exists
+from .core.introspection import (
+    introspect_column_shapes,
+    introspect_columns,
+    introspect_function_privileges,
+    introspect_rls_policies,
+    schema_exists,
+)
 from .core.one_database import OneDatabaseReport, PoolIdentity, audit_one_database
 from .core.listen import notify, ping
 from .core.tls import resolve_asyncpg_ssl, resolve_asyncpg_ssl_from_dsn
@@ -249,6 +255,7 @@ from .core.registry import (
     validate_relation_resolution,
 )
 from .core.relations import ManyToManyField
+from .core.admin_lane import ADMIN_LANE_GUC, admin_lane
 from .core.rls_session import rls_session
 from .core.session_context import (
     ACTOR_AGENT_GUC,
@@ -472,7 +479,9 @@ __all__ = [
     "audit_one_database",
     "OneDatabaseReport",
     "PoolIdentity",
+    "introspect_column_shapes",
     "introspect_columns",
+    "introspect_function_privileges",
     "introspect_lock_waits",
     "introspect_rls_policies",
     "schema_exists",
@@ -709,6 +718,8 @@ __all__ = [
     "try_advisory_lock",
     "advisory_unlock",
     "rls_session",
+    "admin_lane",
+    "ADMIN_LANE_GUC",
     # ── Resilience (opt-in transient-failure retry) ──────────────────────────
     "retry_on_transient",
     "is_read_only_sql",

{matrx_orm-3.1.174 → matrx_orm-3.1.182}/matrx_orm/catalog_sql.py

@@ -113,3 +113,43 @@ SELECT c.relname AS table_name, a.attname AS column_name
    AND NOT a.attisdropped
    AND c.relkind = ANY ('{r,p,v,m,f}')
 """
+
+# The same catalog read, plus the two facts a drift guard actually argues about:
+# whether a column may be empty, and what Postgres puts there when a writer says
+# nothing. A NOT NULL column with a DEFAULT manufactures a value that reads,
+# downstream, exactly like something a person chose — so "is there a default"
+# is a question the ORM must be able to answer without a host hand-rolling SQL.
+COLUMN_SHAPES_FOR_TABLE_SQL = """
+SELECT a.attname                                        AS column_name,
+       NOT a.attnotnull                                 AS is_nullable,
+       pg_get_expr(d.adbin, d.adrelid)                  AS column_default
+  FROM pg_attribute a
+  JOIN pg_class     c ON c.oid = a.attrelid
+  JOIN pg_namespace n ON n.oid = c.relnamespace
+  LEFT JOIN pg_attrdef d ON d.adrelid = a.attrelid AND d.adnum = a.attnum
+ WHERE n.nspname = $1
+   AND c.relname = $2
+   AND a.attnum > 0
+   AND NOT a.attisdropped
+   AND c.relkind = ANY ('{r,p,v,m,f}')
+"""
+
+
+# "Who may CALL this function?" is the other half of the definer question. A
+# SECURITY DEFINER function runs as the owner with BYPASSRLS, so the set of
+# roles holding EXECUTE on it IS its access control — and a grant that quietly
+# includes `anon` or `authenticated` hands a browser the owner's privileges.
+# Like COLUMN_SHAPES_FOR_TABLE_SQL, this is a catalog question with no Model to
+# bind it to, so the ORM answers it rather than every guard hand-rolling SQL.
+FUNCTION_PRIVILEGES_SQL = """
+SELECT p.oid::regprocedure::text                          AS signature,
+       p.prosecdef                                        AS is_security_definer,
+       role_name                                          AS role,
+       has_function_privilege(role_name, p.oid, 'EXECUTE') AS can_execute
+  FROM pg_proc p
+  JOIN pg_namespace n ON n.oid = p.pronamespace
+  CROSS JOIN unnest($3::text[]) AS role_name
+ WHERE n.nspname = $1
+   AND p.proname = $2
+   AND EXISTS (SELECT 1 FROM pg_roles r WHERE r.rolname = role_name)
+"""

matrx_orm-3.1.182/matrx_orm/core/admin_lane.py

@@ -0,0 +1,47 @@
+"""THE ADMIN LANE — the one door that lets a platform admin's database powers work.
+
+Our database's admin arms (``is_platform_admin()``, ``is_super_admin()``, ``is_admin()``,
+``is_super_admin_for(uuid)``, ``is_platform_admin_for(uuid)`` and the kernel's admin rung)
+answer yes only while ``platform.admin_lane_open()`` is true: the request carried the
+admin-app lane header, or the current TRANSACTION set ``matrx.admin_lane`` to ``on``.
+A process on a pooled connection never forwards request headers, so on the server the
+lane is closed unless code opens it here.
+
+Law (Arman, 2026-09-25): an admin on a normal user page sees nothing more than anyone
+else; admin powers work only in the admin sections. The lane opens ARMS; it grants
+nothing to a non-admin — the database still checks identity. It is transaction-local,
+so it can never survive onto another client's pooled connection.
+
+Only admin surfaces may open it (host guard: ``scripts/check_admin_lane_scope.py``).
+"""
+
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from typing import AsyncIterator
+
+from matrx_orm.core.transaction import get_active_connection, set_local_guc, transaction
+
+#: The transaction-local GUC ``platform.admin_lane_open()`` reads. The database names
+#: it; a constant, never configuration — a drift would silently close every lane.
+ADMIN_LANE_GUC = "matrx.admin_lane"
+
+
+@asynccontextmanager
+async def admin_lane(*, database: str) -> AsyncIterator[None]:
+    """Open the admin lane for every database call inside the block.
+
+    Inside an open transaction (``rls_session`` / ``transaction()``) the lane is switched
+    on for THAT transaction; otherwise a transaction is opened so the setting and the
+    work share one connection. Either way it resets when the transaction ends.
+    """
+    if get_active_connection() is not None:
+        await set_local_guc(ADMIN_LANE_GUC, "on")
+        yield
+        return
+    async with transaction(database=database):
+        await set_local_guc(ADMIN_LANE_GUC, "on")
+        yield
+
+
+__all__ = ["ADMIN_LANE_GUC", "admin_lane"]

{matrx_orm-3.1.174 → matrx_orm-3.1.182}/matrx_orm/core/expressions.py

@@ -1081,7 +1081,16 @@ def _render_subquery(
         else:
             join_clauses.append(f"{j_type} JOIN {j_table} ON {j_on_sql}")
 
+    # ``from_alias`` is the name every inner column and every nested OuterRef was
+    # just resolved against (``current_table`` above), so the FROM must DECLARE it —
+    # the same contract the top-level executor keeps. Rendering the alias for
+    # resolution but not in FROM produced "missing FROM-clause entry for table
+    # <alias>" on any nested Exists that correlated to an aliased subquery
+    # (search lab inventory, 2026-09-25).
+    from_alias = query_dict.get("from_alias")
     sql = f"SELECT {select_clause} FROM {table}"
+    if from_alias and from_alias != table:
+        sql += f" AS {from_alias}"
     if join_clauses:
         sql += " " + " ".join(join_clauses)
     if where_conditions:

{matrx_orm-3.1.174 → matrx_orm-3.1.182}/matrx_orm/core/fields.py

@@ -1596,18 +1596,39 @@ class ForeignKey(Field):
                     self.db_type = self._target_field.db_type
         return self._target_field
 
+    def _terminal_field(self) -> Field | None:
+        """The concrete (non-FK) column at the end of this FK's target chain.
+
+        A target column may itself be a ForeignKey, so the chain is followed hop
+        by hop with a visited set. A chain that loops back on itself — a real
+        schema shape: ``content.document.id`` -> ``content.document_version.
+        document_id`` -> ``content.document.id`` — has no concrete column to
+        mirror, so it terminates at ``None`` and every caller takes the same
+        documented UUID fallback an unresolvable target takes. Without the
+        visited set every type read on such a column recursed forever.
+        """
+        visited: set[int] = {id(self)}
+        current: Field = self
+        while isinstance(current, ForeignKey):
+            target = current._get_target_field()
+            if target is None or id(target) in visited:
+                return None
+            visited.add(id(target))
+            current = target
+        return current
+
     def python_type(self) -> type:
-        target = self._get_target_field()
+        target = self._terminal_field()
         return target.python_type() if target is not None else str
 
     def to_python(self, value):
-        target = self._get_target_field()
+        target = self._terminal_field()
         if target is not None:
             return target.to_python(value)
         return str(value) if value else None
 
     def from_db_value(self, value):
-        target = self._get_target_field()
+        target = self._terminal_field()
         if target is not None:
             return target.from_db_value(value)
         return str(value) if value else None
@@ -1616,7 +1637,7 @@ class ForeignKey(Field):
         if value is None:
             return None
         _reject_blank_uuid(self.name, value, "ForeignKey")
-        target = self._get_target_field()
+        target = self._terminal_field()
         if target is not None:
             return target.get_db_prep_value(value)
         return str(value)
@@ -1625,7 +1646,7 @@ class ForeignKey(Field):
         await super().validate(value)
         if value is None:
             return
-        target = self._get_target_field()
+        target = self._terminal_field()
         if target is None:
             # No resolved target — keep the historical UUID format check.
             try:

{matrx_orm-3.1.174 → matrx_orm-3.1.182}/matrx_orm/core/introspection.py

@@ -17,11 +17,21 @@ from __future__ import annotations
 
 from typing import Any
 
-from matrx_orm.catalog_sql import COLUMNS_FOR_TABLES_SQL, SCHEMA_EXISTS_SQL
+from matrx_orm.catalog_sql import (
+    COLUMN_SHAPES_FOR_TABLE_SQL,
+    COLUMNS_FOR_TABLES_SQL,
+    FUNCTION_PRIVILEGES_SQL,
+    SCHEMA_EXISTS_SQL,
+)
 from matrx_orm.core.async_db_manager import AsyncDatabaseManager
 from matrx_orm.core.transaction import get_active_connection
 
-__all__ = ["introspect_rls_policies", "introspect_columns", "schema_exists"]
+__all__ = [
+    "introspect_function_privileges",
+    "introspect_rls_policies",
+    "introspect_columns",
+    "schema_exists",
+]
 
 _RLS_AUDIT_SQL = """
 select
@@ -77,6 +87,7 @@ async def introspect_rls_policies(
 # we assume, present columns read as absent and the drift guard reports the code
 # as wrong about the schema. See matrx_orm/catalog_sql.py.
 _COLUMNS_SQL = COLUMNS_FOR_TABLES_SQL
+_COLUMN_SHAPES_SQL = COLUMN_SHAPES_FOR_TABLE_SQL
 
 
 async def introspect_columns(database: str, schema: str, tables: list[str]) -> dict[str, list[str]]:
@@ -120,3 +131,66 @@ async def schema_exists(database: str, schema: str) -> bool:
 
     async with AsyncDatabaseManager.get_connection(database) as conn:
         return bool(await conn.fetchval(sql, schema))
+
+
+async def introspect_column_shapes(
+    database: str, schema: str, table: str
+) -> dict[str, dict[str, object]]:
+    """Live nullability and default per column — ``{column: {...}}``.
+
+    ``introspect_columns`` answers "does this column exist"; this answers "what
+    will Postgres do when a writer says nothing about it". A NOT NULL column
+    with a DEFAULT does not leave a hole — it FILLS one, and every reader
+    downstream sees a value indistinguishable from a deliberate choice. On
+    2026-09-22 that shape on one column
+    (``communication.sms_notification_preferences.timezone``) made an entire
+    feature a no-op in production. A guard must be able to see it without
+    hand-rolling SQL.
+
+    Each value is ``{"is_nullable": bool, "column_default": str | None}``.
+    ``schema``/``table`` are bound as parameters, never interpolated.
+    """
+    rows = await AsyncDatabaseManager.execute_query(database, _COLUMN_SHAPES_SQL, schema, table)
+    return {
+        str(r["column_name"]): {
+            "is_nullable": bool(r["is_nullable"]),
+            "column_default": (
+                str(r["column_default"]) if r["column_default"] is not None else None
+            ),
+        }
+        for r in rows
+    }
+
+
+async def introspect_function_privileges(
+    database: str, schema: str, name: str, roles: list[str]
+) -> list[dict[str, Any]]:
+    """Which of ``roles`` can EXECUTE ``schema.name`` — one row per overload/role.
+
+    ``introspect_column_shapes`` answers "what will Postgres do when a writer
+    says nothing"; this answers "who can call this door". A SECURITY DEFINER
+    function runs as its owner with BYPASSRLS, so the roles holding EXECUTE on
+    it ARE its access control: if ``anon`` or ``authenticated`` is among them,
+    a browser holds the owner's privileges. A guard has to be able to see that
+    without hand-rolling a catalog query, which is why this lives here.
+
+    Each row is ``{"signature": str, "is_security_definer": bool, "role": str,
+    "can_execute": bool}``. An overload that exists yields one row per role in
+    ``roles``; a function that does not exist yields no rows at all, which is
+    how a caller tells "missing" from "locked". A name in ``roles`` that is not
+    a role on this server is skipped rather than raising — a server without a
+    ``supabase_auth_admin`` is a different deployment, not a violation.
+    ``schema``, ``name`` and ``roles`` are bound parameters, never interpolated.
+    """
+    rows = await AsyncDatabaseManager.execute_query(
+        database, FUNCTION_PRIVILEGES_SQL, schema, name, list(roles)
+    )
+    return [
+        {
+            "signature": str(r["signature"]),
+            "is_security_definer": bool(r["is_security_definer"]),
+            "role": str(r["role"]),
+            "can_execute": bool(r["can_execute"]),
+        }
+        for r in rows
+    ]

{matrx_orm-3.1.174 → matrx_orm-3.1.182}/matrx_orm/core/pooler_role.py

@@ -203,6 +203,7 @@ async def emit_contamination(event: EmptyReadContaminationEvent) -> None:
             ),
             kind="pooler_role_contamination",
             source_app="matrx-orm",
+            source_feature="system",
             route=f"orm:{event.config_name}",
             payload={
                 "config_name": event.config_name,

{matrx_orm-3.1.174 → matrx_orm-3.1.182}/matrx_orm/core/rls_session.py

@@ -51,6 +51,23 @@ _ROLE_RE = re.compile(r"^[a-z_][a-z0-9_]*$")
 # agent query holding a pooled connection. Callers may override or disable (None).
 DEFAULT_STATEMENT_TIMEOUT_MS = 30_000
 
+# Default ceiling on how long an RLS session may sit IDLE INSIDE ITS TRANSACTION before
+# Postgres ends it. Measured on the main database 2026-09-20, lane TIDY: one backend sat
+# `idle in transaction` on `Client/ClientRead` for 89.7 seconds holding AccessShareLock on
+# every partition and index of `custom.record`, `custom.merge_field_provenance` and
+# `custom.anon_form`. A campaign suite then asked for AccessExclusiveLock on one of those
+# relations and queued behind it — and because Postgres's lock queue is FIFO, every
+# ordinary reader that arrived after that queued behind the DDL, four backends deep within
+# seconds, none of which conflicted with the lock actually being held.
+#
+# Nothing legitimate is idle inside a transaction for thirty seconds: the whole point of
+# holding a session open for a turn is that work is happening in it. What IS idle that long
+# is a turn whose caller is waiting on a model, a network hop or a person — and a
+# connection holding store locks while it waits is a stall for everybody else. This ends
+# such a session instead, releasing every lock; the caller sees a named error rather than
+# the rest of the platform seeing a mystery.
+DEFAULT_IDLE_IN_TRANSACTION_TIMEOUT_MS = 30_000
+
 
 @asynccontextmanager
 async def rls_session(
@@ -60,6 +77,7 @@ async def rls_session(
     database: str | None = None,
     statement_timeout_ms: int | None = DEFAULT_STATEMENT_TIMEOUT_MS,
     lock_timeout_ms: int | None = None,
+    idle_in_transaction_timeout_ms: int | None = DEFAULT_IDLE_IN_TRANSACTION_TIMEOUT_MS,
 ) -> AsyncIterator[None]:
     """Run the enclosed block as ``role`` with ``request.jwt.claims`` set to ``claims``.
 
@@ -72,6 +90,13 @@ async def rls_session(
     ``statement_timeout`` does not bound it, and an unbounded waiter queues behind the
     dump or sweep that is already running while blocking everyone behind it. Like the
     role and the claims it is ``SET LOCAL`` — it cannot outlive the transaction.
+
+    ``idle_in_transaction_timeout_ms`` bounds how long this session may sit idle INSIDE
+    its transaction while holding every lock it has taken. It rides the same one round
+    trip as the other three settings, so it is free, and it is what stops one waiting
+    caller becoming a stall for every reader of the relations it touched — see
+    :data:`DEFAULT_IDLE_IN_TRANSACTION_TIMEOUT_MS` for the 89.7-second case that put it
+    here. ``None`` leaves the server default alone.
     """
     if not _ROLE_RE.match(role):
         raise DatabaseError(
@@ -119,6 +144,11 @@ async def rls_session(
         if lock_timeout_ms is not None:
             bound.append(str(int(lock_timeout_ms)))
             settings.append(f"set_config('lock_timeout', ${len(bound)}, true)")
+        if idle_in_transaction_timeout_ms is not None:
+            bound.append(str(int(idle_in_transaction_timeout_ms)))
+            settings.append(
+                f"set_config('idle_in_transaction_session_timeout', ${len(bound)}, true)"
+            )
         bound.append(role)
         settings.append(f"set_config('role', ${len(bound)}, true)")
         await conn.execute("select " + ", ".join(settings), *bound)

{matrx_orm-3.1.174 → matrx_orm-3.1.182}/matrx_orm/migrations/diff.py

@@ -236,6 +236,21 @@ SELECT
         WHERE fk.conrelid = a.attrelid
           AND fk.contype = 'f'
           AND array_position(fk.conkey, a.attnum) IS NOT NULL
+          -- The SAME rule the model generator uses (python_sql/db_objects.py): a
+          -- composite FK's column is a reference only when its target column is
+          -- unique alone. Diverging would make the diff propose dropping an FK
+          -- the models "lost" under a constraint name that does not exist.
+          AND (
+              cardinality(fk.conkey) = 1
+              OR EXISTS (
+                  SELECT 1 FROM pg_index ri
+                  WHERE ri.indrelid = fk.confrelid
+                    AND ri.indisunique AND ri.indpred IS NULL
+                    AND ri.indnkeyatts = 1
+                    AND ri.indkey[0] = fk.confkey[array_position(fk.conkey, a.attnum)]
+              )
+          )
+        ORDER BY cardinality(fk.conkey), fk.conname
         LIMIT 1
     ) AS fk_ref
 FROM pg_attribute a

matrx_orm-3.1.182/matrx_orm/pytest_live_db_guard.py

@@ -0,0 +1,190 @@
+"""Session-wide guard: a test run never reaches the LIVE platform database by accident.
+
+Registered as a ``pytest11`` entry point, so pytest loads it in every suite regardless of
+rootdir — the same mechanism as the spill guard (``matrx_orm.pytest_plugin``) and the lock
+guard (``matrx_orm.pytest_lock_guard``). This is the SEVENTH cross-suite hazard; the other six
+are catalogued in the aidream repo-root ``conftest.py``.
+
+WHY IT EXISTS (lane INTEG-SERVER, 2026-09-24). A developer's ``.env`` holds the five
+``SUPABASE_MATRIX_*`` variables for the LIVE database, because that is what the server runs
+on. Those variables SELECT a connection; they never AUTHORISED one. So every suite that
+imports the host's ``db`` package — ``aidream/services/agent_data/tests/test_rls_data_access.py``
+creates, edits and HARD-deletes notes — ran against production whenever it was collected,
+with nobody having decided that. The matrx-records suite closed this for itself on 2026-09-22
+(a declared target, default the rehearsal branch, main behind three locked doors); this closes
+it for every suite, once, in the package that owns the connection.
+
+THE RULE. Before any test module is imported, the connection the five variables (or the
+``.env`` that will supply them) resolve to is compared with the live database's identity —
+its project ref in the pooler user (``postgres.<ref>``) or a live host. When it IS the live
+database:
+
+* **Default:** the five variables are REPOINTED, in this process only, to the rehearsal
+  branch — ``MATRX_TEST_DATABASE_URL`` when set (any declared non-live target, e.g. the dev
+  clone), else ``SUPABASE_BRANCH_DATABASE_URL``. With neither, they point at an unreachable
+  placeholder (``127.0.0.1:1``), so a live test FAILS to connect instead of writing to
+  production. The banner says which, once.
+* **Live, on purpose:** ``--live-db --live-db-reason "<why>"`` inside the 1–4 AM Pacific
+  maintenance window leaves them alone and prints the reason. The environment cannot open
+  this door (an exported variable outlives the shell that set it); a missing reason or a
+  time outside the window is a usage error that stops the session.
+
+A connection that is NOT the live database — a local Postgres in CI, the branch, the clone —
+is never touched. Values are never printed.
+"""
+
+from __future__ import annotations
+
+import os
+from datetime import datetime
+from urllib.parse import unquote, urlsplit
+from zoneinfo import ZoneInfo
+
+import pytest
+
+#: The ONE live database (aidream CLAUDE.md), by the identities a connection can carry.
+LIVE_PROJECT_REFS = frozenset({"brsgrqvjdzwihsvnfqkf"})
+LIVE_HOSTS = frozenset({"db.matrxserver.com", "db.brsgrqvjdzwihsvnfqkf.supabase.co"})
+
+DB_VARS = (
+    "SUPABASE_MATRIX_HOST",
+    "SUPABASE_MATRIX_PORT",
+    "SUPABASE_MATRIX_USER",
+    "SUPABASE_MATRIX_PASSWORD",
+    "SUPABASE_MATRIX_DATABASE_NAME",
+)
+TARGET_URL_VARS = ("MATRX_TEST_DATABASE_URL", "SUPABASE_BRANCH_DATABASE_URL")
+WINDOW_TZ, WINDOW_START, WINDOW_END = "America/Los_Angeles", 1, 4
+PLACEHOLDER = {
+    "SUPABASE_MATRIX_HOST": "127.0.0.1",
+    "SUPABASE_MATRIX_PORT": "1",
+    "SUPABASE_MATRIX_USER": "live-db-refused-under-pytest",
+    "SUPABASE_MATRIX_PASSWORD": "refused",
+    "SUPABASE_MATRIX_DATABASE_NAME": "refused",
+}
+
+#: The ONLY accounts a test may act as (workspace law: "use ONLY admin@admin.com, never Arman's
+#: personal account"; test@test.com is the non-admin seat). By id, because an id is what a test
+#: reads from ``TEST_USER_ID`` and an id cannot be mistaken for a similar email.
+TEST_ACCOUNT_IDS = {
+    "87a6e699-3622-4869-8843-d0867456c0dd": "admin@admin.com",
+    "4060701e-706a-4c76-b3ca-0bbc69fa5a14": "test@test.com",
+}
+
+
+def refuse_a_real_person(env: dict[str, str], dotenv: dict[str, str]) -> None:
+    """``TEST_USER_ID`` must be one of the test accounts, or the session does not start."""
+    user = (env.get("TEST_USER_ID") or dotenv.get("TEST_USER_ID") or "").strip()
+    if user and user not in TEST_ACCOUNT_IDS:
+        raise pytest.UsageError(
+            "REFUSED: TEST_USER_ID is not a test account. Tests act ONLY as admin@admin.com "
+            "(or test@test.com for a non-admin seat) — never a real person's account, and never "
+            "the owner's personal one. Set TEST_USER_ID to admin@admin.com's user id. Nothing ran."
+        )
+
+
+#: What this session decided, for tests and banners: "untouched" | "live" | "repointed:<var>"
+#: | "placeholder".
+DECISION: str = "untouched"
+
+
+def is_live(user: str, host: str) -> bool:
+    """Does this connection identity name the live database?"""
+    ref = user.split(".", 1)[1] if "." in (user or "") else ""
+    return ref in LIVE_PROJECT_REFS or (host or "").strip().lower() in LIVE_HOSTS
+
+
+def _dotenv_values() -> dict[str, str]:
+    """The ``.env`` a later ``load_dotenv()`` would read — it never overrides what is set here."""
+    try:
+        from dotenv import dotenv_values, find_dotenv
+    except ImportError:  # pragma: no cover — python-dotenv absent: env only
+        return {}
+    path = find_dotenv(usecwd=True)
+    return {k: v for k, v in (dotenv_values(path) if path else {}).items() if v is not None}
+
+
+def _five_from_url(url: str) -> dict[str, str]:
+    parts = urlsplit(url)
+    return {
+        "SUPABASE_MATRIX_HOST": parts.hostname or "",
+        "SUPABASE_MATRIX_PORT": str(parts.port or 5432),
+        "SUPABASE_MATRIX_USER": unquote(parts.username or ""),
+        "SUPABASE_MATRIX_PASSWORD": unquote(parts.password or ""),
+        "SUPABASE_MATRIX_DATABASE_NAME": (parts.path or "/postgres").lstrip("/") or "postgres",
+    }
+
+
+def decide(
+    env: dict[str, str],
+    dotenv: dict[str, str],
+    *,
+    live_flag: bool,
+    reason: str,
+    now: datetime,
+) -> tuple[str, dict[str, str] | None, str]:
+    """``(decision, five variables to set or None, banner)``. Pure — the hook applies it."""
+    effective = {k: env.get(k) or dotenv.get(k, "") for k in DB_VARS}
+    if not is_live(effective["SUPABASE_MATRIX_USER"], effective["SUPABASE_MATRIX_HOST"]):
+        return "untouched", None, ""
+    if live_flag:
+        if not reason.strip():
+            raise pytest.UsageError(
+                "--live-db needs --live-db-reason \"<why>\": nothing else records why a test run "
+                "touched the live database."
+            )
+        local = now.astimezone(ZoneInfo(WINDOW_TZ))
+        if not (WINDOW_START <= local.hour < WINDOW_END):
+            raise pytest.UsageError(
+                f"--live-db refused: it is {local:%H:%M} Pacific, and the live database is open "
+                f"to test runs only {WINDOW_START:02d}:00–{WINDOW_END:02d}:00 Pacific."
+            )
+        return "live", None, f"── LIVE DATABASE under pytest · reason: {reason.strip()}"
+    for var in TARGET_URL_VARS:
+        url = env.get(var) or dotenv.get(var, "")
+        if url:
+            five = _five_from_url(url)
+            if is_live(five["SUPABASE_MATRIX_USER"], five["SUPABASE_MATRIX_HOST"]):
+                raise pytest.UsageError(f"{var} names the LIVE database; it cannot be a test target.")
+            return (
+                f"repointed:{var}",
+                five,
+                f"── the live database was configured; this test run uses {var} instead "
+                "(pass --live-db --live-db-reason inside 1–4 AM Pacific to reach live on purpose).",
+            )
+    return (
+        "placeholder",
+        dict(PLACEHOLDER),
+        "── the live database was configured and no test target is set "
+        "(MATRX_TEST_DATABASE_URL / SUPABASE_BRANCH_DATABASE_URL); database connections in this "
+        "run go to an unreachable placeholder and FAIL instead of reaching production.",
+    )
+
+
+def pytest_addoption(parser: pytest.Parser) -> None:
+    group = parser.getgroup("matrx-live-db", "the live platform database under pytest")
+    group.addoption("--live-db", action="store_true", default=False,
+                    help="reach the LIVE database on purpose (needs --live-db-reason and 1-4 AM Pacific)")
+    group.addoption("--live-db-reason", action="store", default="",
+                    help="why this run needs the live database")
+
+
+@pytest.hookimpl(tryfirst=True)
+def pytest_configure(config: pytest.Config) -> None:
+    global DECISION
+    refuse_a_real_person(dict(os.environ), _dotenv_values())
+    decision, five, banner = decide(
+        dict(os.environ),
+        _dotenv_values(),
+        live_flag=bool(config.getoption("--live-db", default=False)),
+        reason=str(config.getoption("--live-db-reason", default="") or ""),
+        now=datetime.now(ZoneInfo(WINDOW_TZ)),
+    )
+    DECISION = decision
+    if five is not None:
+        os.environ.update(five)
+    if banner:
+        print(banner)
+
+
+__all__ = ["DECISION", "TEST_ACCOUNT_IDS", "refuse_a_real_person", "LIVE_HOSTS", "LIVE_PROJECT_REFS", "decide", "is_live"]