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

{matrx_orm-3.1.135 → 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.135 → matrx_orm-3.1.136}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matrx-orm
-Version: 3.1.135
+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.35
+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.135 → 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.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.135 → 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.135 → 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.135 → matrx_orm-3.1.136}/matrx_orm/schema_builder/common.py

@@ -117,15 +117,26 @@ class GenerationOutputOverrides:
 
 
 # Central debug configuration for the entire schema builder.
-# Values can be overridden at runtime by run_schema_generation() from the yaml
-# debug section, or by setting env vars MATRX_DEBUG, MATRX_VERBOSE, MATRX_INFO.
+#
+# Values are set at runtime by run_schema_generation(), from its `info=` /
+# `debug=` / `verbose=` arguments when given and otherwise from the yaml `debug`
+# section. The defaults below are OFF, which is what every deployed and local
+# run already produced: run_schema_generation() has always overwritten all three
+# unconditionally, so the retired env vars could only ever have spoken to a
+# direct importer.
+#
+# They were MATRX_INFO / MATRX_DEBUG / MATRX_VERBOSE until 2026-09-11. USD-5
+# (Arman, 2026-09-10): "Never an env var. Env values are only for secrets, not
+# for controlling behavior." Those three names are also generic enough to be set
+# in a shell for something else entirely and silently turn a code generator
+# chatty — the exact machine-disagrees-with-machine failure the law names.
 DEBUG_CONFIG = {
     "tables": [],
     "columns": [],
     "base_type": [],
-    "info": os.getenv("MATRX_INFO", "").lower() in ("1", "true"),
-    "debug": os.getenv("MATRX_DEBUG", "").lower() in ("1", "true"),
-    "verbose": os.getenv("MATRX_VERBOSE", "").lower() in ("1", "true"),
+    "info": False,
+    "debug": False,
+    "verbose": False,
 }
 
 # Names a generated model class can NEVER take, because the models file imports

{matrx_orm-3.1.135 → matrx_orm-3.1.136}/matrx_orm/schema_builder/package_wiring.py

@@ -41,7 +41,6 @@ Manifest schema (``DB_REQUIREMENTS`` dict in the package's manifest file):
 from __future__ import annotations
 
 import ast
-import importlib.util
 import os
 import re
 from dataclasses import dataclass, field
@@ -149,13 +148,16 @@ def _load_manifest(manifest_abs: Path) -> dict[str, Any]:
     import) so no package __init__ side effects run during generation."""
     if not manifest_abs.is_file():
         raise PackageWiringError(f"package_wiring: manifest not found: {manifest_abs}")
-    spec = importlib.util.spec_from_file_location(
-        f"_pkg_wiring_manifest_{manifest_abs.stem}", manifest_abs
-    )
-    if spec is None or spec.loader is None:
-        raise PackageWiringError(f"package_wiring: cannot load manifest: {manifest_abs}")
-    mod = importlib.util.module_from_spec(spec)
-    spec.loader.exec_module(mod)
+    from matrx_utils.module_loading import ProviderModuleRefused, load_module_from_path
+
+    try:
+        mod = load_module_from_path(
+            manifest_abs, module_name=f"_pkg_wiring_manifest_{manifest_abs.stem}"
+        )
+    except (FileNotFoundError, ProviderModuleRefused) as exc:
+        raise PackageWiringError(
+            f"package_wiring: cannot load manifest: {manifest_abs} ({exc})"
+        ) from exc
     req = getattr(mod, "DB_REQUIREMENTS", None)
     if not isinstance(req, dict):
         raise PackageWiringError(

{matrx_orm-3.1.135 → matrx_orm-3.1.136}/matrx_orm/schema_builder/runner.py

@@ -112,6 +112,9 @@ def run_schema_generation(
     *,
     only_schemas: set[str] | None = None,
     models_only: bool = False,
+    info: bool | None = None,
+    debug: bool | None = None,
+    verbose: bool | None = None,
 ) -> None:
     """
     Read a matrx_orm.yaml config file, register all databases, apply debug
@@ -168,10 +171,17 @@ def run_schema_generation(
     # -------------------------------------------------------------------------
     # Debug settings
     # -------------------------------------------------------------------------
+    # An explicit argument wins over the yaml, so a generate.py can expose
+    # --info/--debug/--verbose on its own command line for one run without
+    # editing the committed config. These were MATRX_INFO/MATRX_DEBUG/
+    # MATRX_VERBOSE until 2026-09-11 (USD-5): a caller's argument, never the
+    # environment.
     debug_cfg = cfg.get("debug", {})
-    DEBUG_CONFIG["info"] = bool(debug_cfg.get("info", False))
-    DEBUG_CONFIG["debug"] = bool(debug_cfg.get("debug", False))
-    DEBUG_CONFIG["verbose"] = bool(debug_cfg.get("verbose", False))
+    DEBUG_CONFIG["info"] = bool(debug_cfg.get("info", False)) if info is None else info
+    DEBUG_CONFIG["debug"] = bool(debug_cfg.get("debug", False)) if debug is None else debug
+    DEBUG_CONFIG["verbose"] = (
+        bool(debug_cfg.get("verbose", False)) if verbose is None else verbose
+    )
 
     # -------------------------------------------------------------------------
     # Output config — all paths come from .env only, never from the yaml.

{matrx_orm-3.1.135 → matrx_orm-3.1.136}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.135"
+version = "3.1.136"
 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.35",
+    "matrx-utils>=2.0.36",
     "pyyaml>=6.0.3",
     "python-dotenv>=1.0",
     "cryptography>=43.0",