matrx-orm 3.1.134__tar.gz → 3.1.136__tar.gz

{matrx_orm-3.1.134 → matrx_orm-3.1.136}/CLAUDE.md

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

{matrx_orm-3.1.134 → matrx_orm-3.1.136}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matrx-orm
-Version: 3.1.134
+Version: 3.1.136
 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
@@ -25,7 +25,7 @@ Requires-Python: >=3.13
 Requires-Dist: asyncpg>=0.31.0
 Requires-Dist: cryptography>=43.0
 Requires-Dist: gitpython>=3.1.40
-Requires-Dist: matrx-utils>=2.0.34
+Requires-Dist: matrx-utils>=2.0.36
 Requires-Dist: psycopg-pool>=3.2.5
 Requires-Dist: psycopg[binary]>=3.2.5
 Requires-Dist: python-dotenv>=1.0

{matrx_orm-3.1.134 → matrx_orm-3.1.136}/matrx_orm/__init__.py

@@ -240,6 +240,11 @@ from .core.registry import (
 )
 from .core.relations import ManyToManyField
 from .core.rls_session import rls_session
+from .core.session_context import (
+    SessionContextProvider,
+    configure_session_context,
+    session_context_gucs,
+)
 from .core.signals import (
     Signal,
     post_create,
@@ -632,6 +637,9 @@ __all__ = [
     "transaction",
     "acquire_connection",
     "set_local_guc",
+    "SessionContextProvider",
+    "configure_session_context",
+    "session_context_gucs",
     "advisory_xact_lock",
     "try_advisory_xact_lock",
     "advisory_lock",

{matrx_orm-3.1.134 → matrx_orm-3.1.136}/matrx_orm/adapters/__init__.py

@@ -30,8 +30,6 @@ Register any ``BaseAdapter`` subclass before the first query::
 from __future__ import annotations
 
 import logging
-import importlib.util
-import sys
 
 from matrx_orm.adapters.base_adapter import BaseAdapter
 from matrx_orm.adapters.async_postgresql import AsyncPostgreSQLAdapter
@@ -143,35 +141,13 @@ class AdapterRegistry:
             raise ValueError(f"Invalid dotted adapter path: {dotted_path!r}")
 
         # A custom adapter is an extension seam, not a closed list of built-in
-        # modules.  Resolve it through the import spec protocol so an unloaded
-        # third-party adapter remains supported without an opaque dynamic
-        # ``import_module(module_path)`` call that static provider scans cannot
-        # inspect.
-        module = sys.modules.get(module_path)
-        if module is None:
-            spec = importlib.util.find_spec(module_path)
-            # find_spec() imports the PARENT package, and a parent __init__ that
-            # re-exports this child imports it as a side effect. Re-read the
-            # cache: executing the spec now would install a SECOND module object
-            # over the real one, so the adapter class taken from it would be a
-            # different class than the one everyone else imported.
-            module = sys.modules.get(module_path)
-        if module is None:
-            if spec is None or spec.loader is None:
-                raise ModuleNotFoundError(f"No importable adapter module named {module_path!r}")
-            module = importlib.util.module_from_spec(spec)
-            sys.modules[module_path] = module
-            try:
-                spec.loader.exec_module(module)
-            except Exception:
-                if sys.modules.get(module_path) is module:
-                    sys.modules.pop(module_path, None)
-                raise
-            parent_path, _, child_name = module_path.rpartition(".")
-            if parent_path:
-                parent = sys.modules.get(parent_path)
-                if parent is not None:
-                    setattr(parent, child_name, module)
+        # modules. It loads through THE declared-module seam
+        # (matrx_utils.module_loading): an unloaded third-party adapter stays
+        # supported, a provider SDK name is refused, and the mandate/provider
+        # scan sees a fact instead of an opaque computed import.
+        from matrx_utils.module_loading import load_declared_module
+
+        module = load_declared_module(module_path)
         klass = getattr(module, class_name)
         instance = klass(config_name)
         if not isinstance(instance, BaseAdapter):

{matrx_orm-3.1.134 → matrx_orm-3.1.136}/matrx_orm/adapters/async_postgresql.py

@@ -41,11 +41,17 @@ class AsyncPostgreSQLAdapter(BaseAdapter):
         *args: Any,
         timeout: float = 10.0,
         statement_timeout: float | None = None,
+        verify_empty: bool = True,
     ) -> list[dict[str, Any]]:
         from matrx_orm.core.async_db_manager import AsyncDatabaseManager
 
         return await AsyncDatabaseManager.execute_query(
-            self._config_name, sql, *args, timeout=timeout, statement_timeout=statement_timeout
+            self._config_name,
+            sql,
+            *args,
+            timeout=timeout,
+            statement_timeout=statement_timeout,
+            verify_empty=verify_empty,
         )
 
     async def execute_write(

{matrx_orm-3.1.134 → matrx_orm-3.1.136}/matrx_orm/adapters/base_adapter.py

@@ -33,12 +33,14 @@ class BaseAdapter(ABC):
         *args: Any,
         timeout: float = 10.0,
         statement_timeout: float | None = None,
+        verify_empty: bool = True,
     ) -> list[dict[str, Any]]:
         """Execute a read (SELECT) query and return rows as dicts.
 
         ``timeout`` is the connection-acquire timeout; ``statement_timeout``
         (when set) overrides the pool's ``command_timeout`` for this statement
-        only (QueryBuilder.timeout()).
+        only (QueryBuilder.timeout()). ``verify_empty=False`` is reserved for
+        replay-safe polling reads whose cursor does not advance on an empty page.
         """
 
     @abstractmethod

{matrx_orm-3.1.134 → matrx_orm-3.1.136}/matrx_orm/adapters/postgrest_client_adapter.py

@@ -313,6 +313,7 @@ class PostgRESTClientAdapter(BaseAdapter):
         *args: Any,
         timeout: float = 10.0,
         statement_timeout: float | None = None,
+        verify_empty: bool = True,
     ) -> list[dict[str, Any]]:
         """Raw SQL is not supported via PostgREST.
 

{matrx_orm-3.1.134 → matrx_orm-3.1.136}/matrx_orm/adapters/supabase_adapter.py

@@ -103,11 +103,17 @@ class SupabaseAdapter(BaseAdapter):
         *args: Any,
         timeout: float = 10.0,
         statement_timeout: float | None = None,
+        verify_empty: bool = True,
     ) -> list[dict[str, Any]]:
         from matrx_orm.core.async_db_manager import AsyncDatabaseManager
 
         return await AsyncDatabaseManager.execute_query(
-            self._config_name, sql, *args, timeout=timeout, statement_timeout=statement_timeout
+            self._config_name,
+            sql,
+            *args,
+            timeout=timeout,
+            statement_timeout=statement_timeout,
+            verify_empty=verify_empty,
         )
 
     async def execute_write(

{matrx_orm-3.1.134 → matrx_orm-3.1.136}/matrx_orm/core/FEATURE.md

@@ -221,6 +221,10 @@ Verified against the live database: 2026-08-21.
   interface errors.
 - 2026-08-22: Retried read-only mid-query connection loss once on a fresh
   checkout while preserving no-retry write semantics.
+- 2026-09-11: Replay-safe polling reads may explicitly skip empty-result
+  reproof; their unchanged cursor makes an empty-to-nonempty race recover on
+  the next poll, avoiding the transaction-pool reproof convoy without relaxing
+  the default integrity guard for ordinary reads.
 - 2026-08-22: Preserved the deepest Postgres SQLSTATE on `AppError` as a
   lightweight classification (without retaining traceback frames), so an
   idempotent transactional owner can recover from a database role transition

{matrx_orm-3.1.134 → matrx_orm-3.1.136}/matrx_orm/core/MODULE_README.md

@@ -617,6 +617,7 @@ Filepath: src/matrx_orm/core/async_db_manager.py  [python]
 
   class AsyncDatabaseManager:
       def __new__(cls)
+      def pool_snapshot(cls, config_name: str) -> dict[str, int] | None  # {size, idle, max, min} of an EXISTING pool; never creates, never awaits — for error paths
       async def get_pool(cls, config_name)
       async def get_connection(cls, config_name, timeout = 10.0)
       async def execute_query(cls, config_name: str, query: str, *args: Any, timeout: float = 10.0) -> list[dict[str, Any]]

{matrx_orm-3.1.134 → matrx_orm-3.1.136}/matrx_orm/core/async_db_manager.py

@@ -427,6 +427,29 @@ class AsyncDatabaseManager:
             cls._instance = super().__new__(cls)
         return cls._instance
 
+    @classmethod
+    def pool_snapshot(cls, config_name: str) -> dict[str, int] | None:
+        """Read-only sizing of an EXISTING pool: ``{"size", "idle", "max", "min"}``.
+
+        Never creates a pool (unlike :meth:`get_pool`) and never awaits — safe
+        to call from an error path while a deadline is already blown. ``None``
+        when no pool exists for the (alias-resolved) name, so a caller can say
+        "no pool" instead of inventing zeros.
+        """
+        name = resolve_database_name(config_name)
+        pool = cls._pools.get(name)
+        if pool is None:
+            return None
+        try:
+            return {
+                "size": int(pool.get_size()),
+                "idle": int(pool.get_idle_size()),
+                "max": int(pool.get_max_size()),
+                "min": int(pool.get_min_size()),
+            }
+        except Exception:  # noqa: BLE001 — a half-closed pool answers nothing, not a lie
+            return None
+
     @classmethod
     async def get_pool(cls, config_name):
         """Get or create a connection pool for the specified database with error handling.
@@ -1153,6 +1176,7 @@ class AsyncDatabaseManager:
         *args: Any,
         timeout: float = 10.0,
         statement_timeout: float | None = None,
+        verify_empty: bool = True,
     ) -> list[dict[str, Any]]:
         """Execute a query and return results with error handling.
 
@@ -1274,7 +1298,12 @@ class AsyncDatabaseManager:
                                 read_attempt + 1,
                                 query[:120],
                             )
-                        if not results and read_only and cls._verifies_empty_reads(config_name):
+                        if (
+                            not results
+                            and verify_empty
+                            and read_only
+                            and cls._verifies_empty_reads(config_name)
+                        ):
                             # Layer 2: an empty result from a pooled connection is
                             # unproven until a session that can state its own role
                             # says so. A borrowed `authenticated` role returns ZERO

matrx_orm-3.1.136/matrx_orm/core/session_context.py

@@ -0,0 +1,94 @@
+"""The host's DECLARED session context — GUCs every transaction opens with.
+
+Some facts about a block of work are known by the application and readable only
+by the database: *which tier of actor* is authoring these writes, for instance.
+Postgres learns them through transaction-local GUCs (``set_config(..., true)``),
+and a GUC set outside a transaction has no meaning — so the ONE place that can
+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"})
+
+and from then on every TOP-LEVEL ``transaction()`` (which includes the one
+``rls_session`` opens, before it drops to the restricted role) emits whatever
+the provider returns at that instant. A savepoint (nested transaction) emits
+nothing: it is already inside the transaction the GUCs were set on.
+
+Why a provider and not a value: what is true changes per task — the provider is
+normally a ContextVar read, so a block that declares "an AI is writing this"
+affects exactly the work inside it and nothing running beside it.
+
+The package NEVER imports the host: no provider configured ⇒ no GUCs, which is
+exactly how matrx-orm behaves standalone. A provider that raises is a host bug
+and it surfaces — the transaction fails loudly rather than silently committing
+writes whose provenance is a lie.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable, Mapping
+from typing import Any
+
+# Same shape matrx_orm.core.transaction.set_local_guc accepts.
+_GUC_NAME_RE = re.compile(r"^[a-z_][a-z0-9_.]*$")
+
+SessionContextProvider = Callable[[], Mapping[str, str] | None]
+
+_provider: SessionContextProvider | None = None
+
+
+def configure_session_context(provider: SessionContextProvider | None) -> None:
+    """Bind (or with ``None``, unbind) the host's session-context provider.
+
+    Call once at startup, alongside the other package ``configure_*`` calls.
+    ``provider`` is invoked on every top-level transaction open and must return
+    a mapping of GUC name → value (or ``None`` / ``{}`` for "nothing to say").
+    """
+    global _provider
+    if provider is not None and not callable(provider):
+        raise TypeError("configure_session_context(provider) requires a callable or None")
+    _provider = provider
+
+
+def session_context_gucs() -> dict[str, str]:
+    """The GUCs to set on a transaction being opened right now.
+
+    Empty when no provider is configured. Raises when a configured provider
+    returns something unusable — a malformed declaration is a host defect, and
+    writing rows with a wrong (or absent) provenance stamp is worse than a loud
+    failure at BEGIN.
+    """
+    provider = _provider
+    if provider is None:
+        return {}
+    declared = provider()
+    if not declared:
+        return {}
+    if not isinstance(declared, Mapping):
+        raise TypeError(
+            "the session-context provider must return a mapping of GUC name → value; "
+            f"got {type(declared).__name__}"
+        )
+    out: dict[str, str] = {}
+    for name, value in declared.items():
+        if not isinstance(name, str) or not _GUC_NAME_RE.match(name):
+            raise ValueError(f"invalid session-context GUC name: {name!r}")
+        out[name] = "" if value is None else str(value)
+    return out
+
+
+async def apply_session_context(connection: Any) -> None:
+    """Emit the declared GUCs on ``connection`` (already inside a BEGIN)."""
+    for name, value in session_context_gucs().items():
+        await connection.execute("SELECT set_config($1, $2, true)", name, value)
+
+
+__all__ = [
+    "SessionContextProvider",
+    "apply_session_context",
+    "configure_session_context",
+    "session_context_gucs",
+]

{matrx_orm-3.1.134 → matrx_orm-3.1.136}/matrx_orm/core/transaction.py

@@ -249,6 +249,23 @@ class TransactionContext:
                 ) from e
             self._conn_token = _active_connection.set(conn)
             self._depth_token = _savepoint_depth.set(0)
+            # THE HOST'S DECLARED SESSION CONTEXT (provenance and friends). A
+            # transaction-local GUC only has meaning inside a transaction, so
+            # this — the moment one opens — is the only place a declaration made
+            # in application code can reach Postgres. Set while still the
+            # privileged role: `rls_session` opens through here and drops to the
+            # restricted role afterwards. Nested entries are savepoints inside a
+            # transaction that already carries them, so they emit nothing.
+            from matrx_orm.core.session_context import apply_session_context
+
+            try:
+                await apply_session_context(conn)
+            except Exception as e:
+                await self.__aexit__(type(e), e, e.__traceback__)
+                raise DatabaseError(
+                    message=f"Failed to apply the declared session context: {e}",
+                    details={"database": self.database},
+                ) from e
         return self
 
     async def __aexit__(

{matrx_orm-3.1.134 → matrx_orm-3.1.136}/matrx_orm/migrations/loader.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import importlib.util
 import re
 from dataclasses import dataclass
 from pathlib import Path
@@ -124,15 +123,17 @@ class MigrationLoader:
 
     def _load_module(self, filepath: Path, name: str) -> Any:
         """Dynamically import a migration file as a module."""
-        spec = importlib.util.spec_from_file_location(f"matrx_migrations.{name}", filepath)
-        if spec is None or spec.loader is None:
+        from matrx_utils.module_loading import ProviderModuleRefused, load_module_from_path
+
+        # Only "no such file" / "refused" become MigrationError; an error the
+        # migration raises while executing propagates raw, exactly as before.
+        try:
+            return load_module_from_path(filepath, module_name=f"matrx_migrations.{name}")
+        except (FileNotFoundError, ProviderModuleRefused) as exc:
             raise MigrationError(
                 migration=name,
-                original_error=f"Could not load migration file: {filepath}",
-            )
-        module = importlib.util.module_from_spec(spec)
-        spec.loader.exec_module(module)
-        return module
+                original_error=f"Could not load migration file: {filepath} ({exc})",
+            ) from exc
 
     def _validate_graph(self) -> None:
         """Ensure all declared dependencies exist."""

matrx_orm-3.1.136/matrx_orm/pytest_plugin.py

@@ -0,0 +1,200 @@
+"""Session-wide guard: a test that reaches the durable-write spill lane.
+
+Registered as a ``pytest11`` entry point so pytest auto-loads it in every suite
+**regardless of rootdir** — same mechanism, same reason, as
+``matrx_connect.pytest_plugin`` and ``matrx_utils.pytest_plugin``.
+
+WHY IT EXISTS. The write-durability chain is: Session flush → on failure
+``record_failures`` → on failure ``_spill_ops_to_disk``. The spill directory is
+resolved from ``MATRX_SPILL_DIR`` → a packaged default → the OS temp dir, and
+that last rung is SHARED by every process on the machine — including the local
+API server, whose auto-replay loop drains it every minute back into
+``ops.system_write_failure`` and then re-applies the rows to the real tables.
+
+Measured 2026-09-11: a matrx-ai unit test drove the orchestrator with a
+fabricated user and conversation. Its collaborators were doubled, but the
+coordinator queue helpers were not, and another suite in the same process had
+already registered REAL database credentials and left a request lane open. The
+flush hit production Postgres, the ``_stamp_org_default`` trigger refused the
+row (the user does not exist), the failure capture itself failed (the same
+user is a foreign key on the capture table), the rows were spilled to
+``$TMPDIR/matrx-write-spill`` — and the developer's local server drained them
+into the live failure table and tried to replay test fixtures against
+production forty times, landing a ``system_error`` row per attempt.
+
+THE CONTRACT. No automated test may spill. Under pytest this plugin:
+
+1. points ``MATRX_SPILL_DIR`` at a fresh, session-private temp dir BEFORE any
+   test runs, so a spill can never reach a directory another process drains;
+2. FAILS the session if anything was spilled there, naming every file — a
+   spill under pytest is proof that a test wrote through to a real database
+   and could not even record its failure. Fix the test's isolation (double the
+   write seam, or install ``aidream.testing.offline`` placeholders); never
+   delete the evidence to make the run green;
+3. re-confines the cascade after EVERY test: a test that assigns
+   ``MATRX_SPILL_DIR`` or ``fallback._spill_dir_cache`` directly (no
+   monkeypatch revert) would otherwise leave every later spill landing in its
+   directory, unseen. Such a test is named in the summary and its directory is
+   swept too (hole found by the adversarial review of the first version).
+
+Suites that exercise the spill lane on purpose (``matrx-orm``'s
+``test_disk_spill_fallback``) point the cascade at their own ``tmp_path`` via
+``monkeypatch`` and reset the cache; those files never land in the session dir
+and the revert happens before this plugin looks.
+
+Opt out for one run with ``-p no:matrx_write_spill_guard``.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+
+import pytest
+
+_SESSION_SPILL_DIR: Path | None = None
+_PREVIOUS_ENV: str | None = None
+# Tests that repointed the spill cascade (env var or the module cache) and left
+# it repointed. Each is re-confined at its teardown; its directory is still
+# swept for spills at session end, so hijacking the cascade cannot hide one.
+_HIJACKS: dict[str, Path] = {}
+
+
+def session_spill_dir() -> Path | None:
+    """The directory this session's spills are confined to (None if not configured)."""
+    return _SESSION_SPILL_DIR
+
+
+def spilled_files() -> list[Path]:
+    """Every op spilled to disk during this session, oldest first — in the
+    session dir and in any directory a test repointed the cascade to."""
+    if _SESSION_SPILL_DIR is None:
+        return []
+    seen: set[Path] = set()
+    files: list[Path] = []
+    for directory in (_SESSION_SPILL_DIR, *_HIJACKS.values()):
+        if directory in seen or not directory.exists():
+            continue
+        seen.add(directory)
+        files.extend(directory.glob("*.json"))
+    return sorted(files, key=lambda f: (f.stat().st_mtime, f.name))
+
+
+def _describe(path: Path) -> str:
+    try:
+        row = json.loads(path.read_text())
+    except Exception:  # noqa: BLE001 — a half-written file is still evidence
+        return f"{path.name}: (unreadable)"
+    return (
+        f"{path.name}: {row.get('table_target')} {row.get('op_type')} "
+        f"request_id={row.get('request_id')} user_id={row.get('user_id')} "
+        f"error={str(row.get('error_text') or '')[:160]!r}"
+    )
+
+
+def _reconfine(nodeid: str) -> None:
+    """After a test: if it left the cascade pointing elsewhere, record where and
+    point it back at the session dir. A test that repoints via ``monkeypatch``
+    (auto-reverted before this runs) is never recorded; one that assigns
+    ``os.environ`` or the module cache directly is."""
+    if _SESSION_SPILL_DIR is None:
+        return
+    try:
+        from matrx_orm.session import fallback
+    except Exception:  # noqa: BLE001 — the ORM is not imported in every suite
+        return
+    cache: Path | None = fallback._spill_dir_cache
+    env = os.environ.get("MATRX_SPILL_DIR")
+    hijacked: Path | None = None
+    if cache is not None and cache != _SESSION_SPILL_DIR:
+        hijacked = cache
+    elif env != str(_SESSION_SPILL_DIR):
+        hijacked = Path(env) if env else None
+    if hijacked is not None:
+        _HIJACKS.setdefault(nodeid, hijacked)
+    if hijacked is not None or env != str(_SESSION_SPILL_DIR):
+        fallback._spill_dir_cache = None
+        os.environ["MATRX_SPILL_DIR"] = str(_SESSION_SPILL_DIR)
+
+
+def pytest_configure(config: pytest.Config) -> None:  # noqa: ARG001 — hook signature
+    global _SESSION_SPILL_DIR, _PREVIOUS_ENV
+    _PREVIOUS_ENV = os.environ.get("MATRX_SPILL_DIR")
+    _SESSION_SPILL_DIR = Path(tempfile.mkdtemp(prefix="matrx-test-spill-"))
+    os.environ["MATRX_SPILL_DIR"] = str(_SESSION_SPILL_DIR)
+    # The cascade caches its first resolution for the life of the process. If
+    # something already resolved it (a conftest that imported the ORM and
+    # spilled at import time would be its own scandal), drop the cache so the
+    # session dir wins from here on.
+    try:
+        from matrx_orm.session import fallback
+
+        fallback._spill_dir_cache = None
+    except Exception:  # noqa: BLE001 — never block a session over the guard's own import
+        pass
+
+
+@pytest.hookimpl(hookwrapper=True, trylast=True)
+def pytest_runtest_teardown(item: pytest.Item):
+    # Runs after every fixture finalizer (monkeypatch reverts included), so what
+    # is left pointing elsewhere is what the test itself leaked.
+    yield
+    _reconfine(item.nodeid)
+
+
+def pytest_sessionfinish(session: pytest.Session, exitstatus: int) -> None:  # noqa: ARG001
+    files = spilled_files()
+    if not files:
+        return
+    # A spilled op means a real database write was attempted AND failed AND the
+    # failure could not even be recorded. That is never what a test meant to do.
+    if session.exitstatus in (pytest.ExitCode.OK, pytest.ExitCode.NO_TESTS_COLLECTED):
+        session.exitstatus = pytest.ExitCode.TESTS_FAILED
+
+
+def pytest_terminal_summary(terminalreporter, exitstatus: int, config: pytest.Config) -> None:  # noqa: ARG001
+    files = spilled_files()
+    if not files:
+        return
+    lines = [
+        f"{len(files)} durable-write op(s) were SPILLED TO DISK during this test run.",
+        "A test wrote through to a real database, the write was refused, and the",
+        "failure capture itself failed — so the fallback chain parked the rows on",
+        "disk. Under pytest that is a test-isolation defect, not a persistence event:",
+        "double the coordinator/queue seam the test reaches, or install",
+        "aidream.testing.offline placeholders in the suite's conftest.",
+        f"Evidence (left in place, in {_SESSION_SPILL_DIR}):",
+    ]
+    lines.extend(f"  - {_describe(path)}" for path in files[:20])
+    if len(files) > 20:
+        lines.append(f"  ... and {len(files) - 20} more")
+    if _HIJACKS:
+        lines.append(
+            "These tests repointed the spill cascade (MATRX_SPILL_DIR or the module "
+            "cache) without reverting it; each was re-confined at its teardown and "
+            "its directory swept — use monkeypatch so the change reverts itself:"
+        )
+        lines.extend(f"  - {nodeid} -> {path}" for nodeid, path in _HIJACKS.items())
+    lines.append("The session is marked FAILED. Opt out once with -p no:matrx_write_spill_guard.")
+    terminalreporter.write_sep("=", "matrx write-spill guard", red=True, bold=True)
+    for line in lines:
+        terminalreporter.write_line(line, red=True)
+
+
+def pytest_unconfigure(config: pytest.Config) -> None:  # noqa: ARG001
+    global _SESSION_SPILL_DIR, _PREVIOUS_ENV
+    if _PREVIOUS_ENV is None:
+        os.environ.pop("MATRX_SPILL_DIR", None)
+    else:
+        os.environ["MATRX_SPILL_DIR"] = _PREVIOUS_ENV
+    # Remove ONLY an empty session dir; spilled evidence is left for the human.
+    if _SESSION_SPILL_DIR is not None and not spilled_files():
+        try:
+            _SESSION_SPILL_DIR.rmdir()
+        except OSError:
+            pass
+    _SESSION_SPILL_DIR = None
+    _PREVIOUS_ENV = None
+    _HIJACKS.clear()

{matrx_orm-3.1.134 → matrx_orm-3.1.136}/matrx_orm/query/builder.py

@@ -213,6 +213,7 @@ class QueryBuilder(Generic[ModelT]):
     vector_null_guard: bool  # auto-add IS NOT NULL guard for vector column
     from_subquery_builder: QueryBuilder[Any] | None
     timeout_val: float | None  # timeout() — per-query statement timeout override (seconds)
+    verify_empty_val: bool
 
     def __init__(self, model_cls: type[ModelT], database: str | None = None) -> None:
         self.model = model_cls
@@ -239,6 +240,7 @@ class QueryBuilder(Generic[ModelT]):
         self.from_subquery_builder = None
         self.from_alias_name: str | None = None
         self.timeout_val: float | None = None
+        self.verify_empty_val = True
 
     def _set_database(self, model_cls: type[ModelT]) -> str:
         if hasattr(model_cls, "_database") and model_cls._database:
@@ -566,6 +568,12 @@ class QueryBuilder(Generic[ModelT]):
         new.timeout_val = seconds
         return new
 
+    def replay_safe_empty(self) -> QueryBuilder[ModelT]:
+        """Skip empty-read reproof for a replay-safe poll whose cursor does not advance on empty."""
+        new = self._clone()
+        new.verify_empty_val = False
+        return new
+
     def from_alias(self, alias: str) -> QueryBuilder[ModelT]:
         """Alias the base (FROM) table — renders ``FROM <table> AS <alias>``.
 
@@ -737,6 +745,7 @@ class QueryBuilder(Generic[ModelT]):
             "from_subquery": self.from_subquery_builder,
             "from_alias": self.from_alias_name,
             "timeout": self.timeout_val,
+            "verify_empty": self.verify_empty_val,
         }
         return query
 

{matrx_orm-3.1.134 → matrx_orm-3.1.136}/matrx_orm/query/executor.py

@@ -1028,10 +1028,17 @@ class QueryExecutor:
             # Passed only when set so adapters that don't accept the kwarg
             # keep working for un-overridden queries.
             statement_timeout = self._full_query_dict.get("timeout")
-            if statement_timeout is not None:
+            verify_empty = self._full_query_dict.get("verify_empty", True)
+            if statement_timeout is not None and not verify_empty:
+                results = await self.db.execute_query(
+                    self.query, *self.params, statement_timeout=statement_timeout, verify_empty=verify_empty
+                )
+            elif statement_timeout is not None:
                 results = await self.db.execute_query(
                     self.query, *self.params, statement_timeout=statement_timeout
                 )
+            elif not verify_empty:
+                results = await self.db.execute_query(self.query, *self.params, verify_empty=False)
             else:
                 results = await self.db.execute_query(self.query, *self.params)
             return results