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

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

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

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

@@ -200,11 +200,81 @@ def declared_actor_gucs() -> dict[str, str]:
     Empty when nothing declared an actor: the DB resolver then applies its
     documented default (``human`` with an identity present, ``code`` without)
     and logs that it did.
+
+    The WORKFLOW CHAIN rides the same provider (it is part of "who is writing":
+    the store copies it onto every record-changed event's ``actor.chain``), so a
+    host that wired this provider stamps run writes with no second wiring.
     """
     actor = _current_actor.get()
-    if actor is None:
-        return {}
-    return actor.as_gucs()
+    out = actor.as_gucs() if actor is not None else {}
+    chain = _current_chain.get()
+    if chain is not None:
+        out[WORKFLOW_CHAIN_GUC] = chain.as_json()
+    return out
+
+
+# ---------------------------------------------------------------------------
+# THE WORKFLOW CHAIN — which workflow run is writing (lane CHAIR-RECORD-CHANGED).
+#
+# A record write made by a workflow run's step carries ``{run_id, root_run, depth}``
+# in the transaction-local GUC ``custom.workflow_chain``; the store's record-changed
+# emitter copies it onto the event (``actor.chain``). A run started BY such an event
+# declares the event's chain one level deeper, so a consumer can cap a chain's depth
+# and see a loop (the same root_run coming back) without reading run history.
+# ---------------------------------------------------------------------------
+
+WORKFLOW_CHAIN_GUC = "custom.workflow_chain"
+
+
+@dataclass(frozen=True, slots=True)
+class WorkflowChain:
+    """The workflow run writing now, the run that started the chain, and how deep it is."""
+
+    run_id: str
+    root_run: str
+    depth: int = 1
+
+    def as_json(self) -> str:
+        import json
+
+        return json.dumps(
+            {"run_id": self.run_id, "root_run": self.root_run, "depth": self.depth},
+            separators=(",", ":"),
+        )
+
+
+def workflow_chain_for_run(run_id: str, caused_by: Mapping[str, Any] | None = None) -> WorkflowChain:
+    """The chain a run declares: one level below the change that started it, else a new root."""
+    if caused_by:
+        root = str(caused_by.get("root_run") or caused_by.get("run_id") or run_id)
+        try:
+            depth = int(caused_by.get("depth") or 0) + 1
+        except (TypeError, ValueError):
+            depth = 1
+        return WorkflowChain(run_id=str(run_id), root_run=root, depth=depth)
+    return WorkflowChain(run_id=str(run_id), root_run=str(run_id), depth=1)
+
+
+_current_chain: ContextVar[WorkflowChain | None] = ContextVar("_workflow_chain", default=None)
+
+
+def current_workflow_chain() -> WorkflowChain | None:
+    """The workflow chain declared by the innermost open declaration, if any."""
+    return _current_chain.get()
+
+
+@contextmanager
+def declaring_workflow_chain(chain: WorkflowChain | None) -> Iterator[WorkflowChain | None]:
+    """Every transaction opened inside this block stamps its writes with ``chain``.
+
+    A ContextVar, like the actor: tasks spawned inside the block inherit it, work
+    running beside it does not. ``None`` clears an outer declaration for the block.
+    """
+    token = _current_chain.set(chain)
+    try:
+        yield chain
+    finally:
+        _current_chain.reset(token)
 
 
 def _validated_actor(tier: str, system: str, agent: str | None, *, caller: str) -> ActorRef:
@@ -279,6 +349,11 @@ async def declared_actor(
 
 
 __all__ = [
+    "WORKFLOW_CHAIN_GUC",
+    "WorkflowChain",
+    "current_workflow_chain",
+    "declaring_workflow_chain",
+    "workflow_chain_for_run",
     "ACTOR_AGENT_GUC",
     "ACTOR_SYSTEM_GUC",
     "ACTOR_TIER_GUC",

matrx_orm-3.1.203/matrx_orm/pytest_production_door.py

@@ -0,0 +1,353 @@
+"""Session-wide door: a pytest process never opens a connection to PRODUCTION (lane ONE-HOME, 2026-10-02).
+
+Registered as a ``pytest11`` entry point (``matrx_production_door``), so pytest loads it in every suite
+regardless of rootdir — the same mechanism as this package's spill, lock and live-db guards; the aidream
+root ``conftest.py`` also registers it when the entry point is missing (stale install metadata). This is the
+NINTH cross-suite hazard; the others are catalogued in the aidream repo-root ``conftest.py``.
+
+WHY A DRIVER-LEVEL DOOR. A static census of test sources cannot win: a production ref split in two and
+concatenated, a DSN read from JSON or a dotenv file, libpq's own ``PG*`` environment behind a no-argument
+``connect()``, asyncpg keyword arguments, sqlalchemy URLs, SQL read from a file, writing functions called
+through ``select``, aliased imports and ``psql`` in a subprocess all slip past every pattern. Every one of them
+reaches a driver. So the driver is the door: at CONNECT time the effective host, user and database — the DSN
+text, the keyword arguments and libpq's environment defaults merged the way libpq merges them — are compared
+with production's identity (ref ``brsgrqvjdzwihsvnfqkf`` in the pooler user or host, or
+``db.matrxserver.com``), and a production connection is refused by name.
+
+WHAT IS WRAPPED: ``psycopg.Connection.connect`` / ``psycopg.AsyncConnection.connect`` (so ``psycopg.connect``
+and every ``psycopg_pool`` pool), ``psycopg2.connect``, ``asyncpg.connect`` / ``create_pool`` (and the
+``asyncpg.connection.connect`` a pool dials), sqlalchemy ``create_engine`` / ``create_async_engine``,
+``matrx_orm``'s database registration, and ``subprocess.Popen`` of ``psql``. A module imported after this
+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.
+
+Guard: ``aidream/tests/test_tests_never_write_production.py`` (plants per bypass class).
+"""
+
+from __future__ import annotations
+
+import contextvars
+import importlib.abc
+import importlib.util
+import os
+import subprocess
+import sys
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import Any
+from urllib.parse import parse_qs, unquote, urlsplit
+
+PRODUCTION_REF = "brsgrqvjdzwihsvnfqkf"
+PRODUCTION_MARKERS = (PRODUCTION_REF, "db.matrxserver.com")
+#: libpq's environment defaults, by the connection parameter each one supplies.
+LIBPQ_ENV = {"host": "PGHOST", "hostaddr": "PGHOSTADDR", "user": "PGUSER", "dbname": "PGDATABASE", "service": "PGSERVICE"}
+
+_READ_ONLY_PRODUCTION: contextvars.ContextVar[bool] = contextvars.ContextVar("production_read_only", default=False)
+
+
+class ProductionDoorRefusal(RuntimeError):
+    """A connection opened under pytest named the production database."""
+
+
+@contextmanager
+def production_read_only() -> Iterator[None]:
+    """Open ONE production connection that the caller turns into ``begin read only`` before any statement."""
+    token = _READ_ONLY_PRODUCTION.set(True)
+    try:
+        yield
+    finally:
+        _READ_ONLY_PRODUCTION.reset(token)
+
+
+def _parse_dsn(text: str) -> dict[str, str]:
+    """Connection parameters from a URL (any ``scheme://``) or a libpq ``key=value`` string."""
+    text = (text or "").strip()
+    if not text:
+        return {}
+    if "://" in text:
+        try:
+            u = urlsplit(text)
+            out = {"host": u.hostname or "", "user": unquote(u.username or ""), "dbname": (u.path or "").lstrip("/")}
+            for k, v in parse_qs(u.query).items():
+                out[k] = v[0]
+            return {k: v for k, v in out.items() if v}
+        except ValueError:
+            return {}
+    out: dict[str, str] = {}
+    for part in text.split():
+        k, sep, v = part.partition("=")
+        if sep:
+            out[k.strip()] = v.strip().strip("'\"")
+    return out
+
+
+def effective_identity(dsn: Any = None, **kwargs: Any) -> dict[str, str]:
+    """What libpq would connect to: environment defaults, overlaid by the DSN, overlaid by keyword arguments."""
+    params = {k: os.environ[v] for k, v in LIBPQ_ENV.items() if os.environ.get(v)}
+    params.update(_parse_dsn(str(dsn)) if dsn else {})
+    for k in ("host", "hostaddr", "user", "dbname", "database", "service"):
+        if kwargs.get(k):
+            params["dbname" if k == "database" else k] = str(kwargs[k])
+    return params
+
+
+def names_production(dsn: Any = None, **kwargs: Any) -> str | None:
+    """The production marker this connection carries (in the DSN text or its effective identity), else None."""
+    texts = [str(dsn or "")] + list(effective_identity(dsn, **kwargs).values())
+    blob = " ".join(texts).lower()
+    return next((m for m in PRODUCTION_MARKERS if m in blob), None)
+
+
+def check(what: str, dsn: Any = None, **kwargs: Any) -> None:
+    """Refuse a production connection unless it is the read-only one :func:`production_read_only` opens."""
+    if _READ_ONLY_PRODUCTION.get():
+        return
+    marker = names_production(dsn, **kwargs)
+    if marker:
+        raise ProductionDoorRefusal(
+            f"refused under pytest: {what} reaches the PRODUCTION database ({marker}). Tests never write "
+            "production — open the nightly clone (db.pooled_read.clone_writer_dsn()); a read-only production "
+            "check goes through db.pooled_read.read_only('production')."
+        )
+
+
+# ── the wrappers ─────────────────────────────────────────────────────────────────────────────────────
+
+
+def _patch_psycopg(mod: Any) -> None:
+    for cls_name in ("Connection", "AsyncConnection"):
+        cls = getattr(mod, cls_name, None)
+        if cls is None or getattr(cls.connect, "_production_door", False):
+            continue
+        original = cls.__dict__["connect"].__func__
+        if cls_name == "Connection":
+
+            def connect(cls: Any, conninfo: str = "", _o: Any = original, **kw: Any) -> Any:
+                check("psycopg.connect", conninfo, **kw)
+                return _o(cls, conninfo, **kw)
+        else:
+
+            async def connect(cls: Any, conninfo: str = "", _o: Any = original, **kw: Any) -> Any:  # type: ignore[misc]
+                check("psycopg.AsyncConnection.connect", conninfo, **kw)
+                return await _o(cls, conninfo, **kw)
+
+        connect._production_door = True  # type: ignore[attr-defined]
+        cls.connect = classmethod(connect)
+    mod.connect = mod.Connection.connect
+
+
+def _patch_psycopg2(mod: Any) -> None:
+    original = mod.connect
+    if getattr(original, "_production_door", False):
+        return
+
+    def connect(dsn: Any = None, connection_factory: Any = None, cursor_factory: Any = None, **kw: Any) -> Any:
+        check("psycopg2.connect", dsn, **kw)
+        return original(dsn, connection_factory, cursor_factory, **kw)
+
+    connect._production_door = True  # type: ignore[attr-defined]
+    mod.connect = connect
+
+
+def _patch_asyncpg(mod: Any) -> None:
+    import asyncpg.connection as connection_mod
+    import asyncpg.pool as pool_mod
+
+    original = connection_mod.connect
+    if getattr(original, "_production_door", False):
+        return
+
+    async def connect(dsn: Any = None, *args: Any, **kw: Any) -> Any:
+        check("asyncpg.connect", dsn, **kw)
+        return await original(dsn, *args, **kw)
+
+    original_pool = pool_mod.create_pool
+
+    def create_pool(dsn: Any = None, *args: Any, **kw: Any) -> Any:
+        check("asyncpg.create_pool", dsn, **kw)
+        return original_pool(dsn, *args, **kw)
+
+    connect._production_door = True  # type: ignore[attr-defined]
+    create_pool._production_door = True  # type: ignore[attr-defined]
+    connection_mod.connect = connect
+    mod.connect = connect
+    pool_mod.create_pool = create_pool
+    mod.create_pool = create_pool
+
+
+def _patch_sqlalchemy(mod: Any) -> None:
+    import sqlalchemy.engine as engine_mod
+
+    original = engine_mod.create_engine
+    if getattr(original, "_production_door", False):
+        return
+
+    def create_engine(url: Any, *args: Any, **kw: Any) -> Any:
+        check("sqlalchemy.create_engine", _render_url(url))
+        return original(url, *args, **kw)
+
+    create_engine._production_door = True  # type: ignore[attr-defined]
+    engine_mod.create_engine = create_engine
+    mod.create_engine = create_engine
+
+
+def _patch_sqlalchemy_asyncio(mod: Any) -> None:
+    original = mod.create_async_engine
+    if getattr(original, "_production_door", False):
+        return
+
+    def create_async_engine(url: Any, *args: Any, **kw: Any) -> Any:
+        check("sqlalchemy.create_async_engine", _render_url(url))
+        return original(url, *args, **kw)
+
+    create_async_engine._production_door = True  # type: ignore[attr-defined]
+    mod.create_async_engine = create_async_engine
+    engine = sys.modules.get("sqlalchemy.ext.asyncio.engine")
+    if engine is not None:
+        engine.create_async_engine = create_async_engine
+
+
+def _patch_psycopg_pool(mod: Any) -> None:
+    # A pool's worker swallows a connect error into retries; refuse at construction so the refusal is said.
+    for cls_name in ("ConnectionPool", "AsyncConnectionPool", "NullConnectionPool", "AsyncNullConnectionPool"):
+        cls = getattr(mod, cls_name, None)
+        if cls is None or getattr(cls.__init__, "_production_door", False):
+            continue
+        original = cls.__init__
+
+        def __init__(self: Any, conninfo: str = "", *a: Any, _o: Any = original, _n: str = cls_name, **kw: Any) -> None:
+            check(f"psycopg_pool.{_n}", conninfo, **(kw.get("kwargs") or {}))
+            _o(self, conninfo, *a, **kw)
+
+        __init__._production_door = True  # type: ignore[attr-defined]
+        cls.__init__ = __init__
+
+
+def _render_url(url: Any) -> str:
+    render = getattr(url, "render_as_string", None)
+    return render(hide_password=True) if callable(render) else str(url)
+
+
+def _patch_orm_registry(mod: Any) -> None:
+    registry_cls = getattr(mod, "DatabaseRegistry", None) or type(getattr(mod, "_registry", None) or object())
+    original = getattr(registry_cls, "register", None)
+    if original is None or getattr(original, "_production_door", False):
+        return
+
+    def register(self: Any, config: Any) -> None:
+        check(
+            f"matrx_orm database registration {getattr(config, 'name', '?')!r}",
+            None,
+            host=getattr(config, "host", None),
+            user=getattr(config, "user", None),
+            dbname=getattr(config, "database_name", None),
+        )
+        return original(self, config)
+
+    register._production_door = True  # type: ignore[attr-defined]
+    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
+
+
+def _patch_subprocess() -> None:
+    original = subprocess.Popen.__init__
+    if getattr(original, "_production_door", False):
+        return
+
+    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]
+
+
+_PATCHERS = {
+    "psycopg": _patch_psycopg,
+    "psycopg_pool": _patch_psycopg_pool,
+    "psycopg2": _patch_psycopg2,
+    "asyncpg": _patch_asyncpg,
+    "sqlalchemy": _patch_sqlalchemy,
+    "sqlalchemy.ext.asyncio": _patch_sqlalchemy_asyncio,
+    "matrx_orm.core.config": _patch_orm_registry,
+}
+
+
+class _PatchOnImport(importlib.abc.MetaPathFinder, importlib.abc.Loader):
+    """Patch a driver the moment it is first imported (for drivers this plugin did not import itself)."""
+
+    def find_spec(self, fullname: str, path: Any, target: Any = None) -> Any:
+        if fullname not in _PATCHERS or fullname in sys.modules:
+            return None
+        sys.meta_path.remove(self)
+        try:
+            spec = importlib.util.find_spec(fullname)
+        finally:
+            sys.meta_path.insert(0, self)
+        if spec is None or spec.loader is None:
+            return None
+        loader = spec.loader
+
+        class _Loader(importlib.abc.Loader):
+            def create_module(self, s: Any) -> Any:
+                return loader.create_module(s)
+
+            def exec_module(self, module: Any) -> None:
+                loader.exec_module(module)
+                _PATCHERS[fullname](module)
+
+        spec.loader = _Loader()
+        return spec
+
+
+def install() -> None:
+    """Wrap every driver already imported, and every one imported later. Idempotent."""
+    _patch_subprocess()
+    for name, patch in _PATCHERS.items():
+        if name in sys.modules:
+            patch(sys.modules[name])
+    if not any(isinstance(f, _PatchOnImport) for f in sys.meta_path):
+        sys.meta_path.insert(0, _PatchOnImport())
+    for name in ("psycopg", "asyncpg"):  # the two drivers every suite has: patch them now
+        try:
+            importlib.import_module(name)
+        except ImportError:
+            pass
+
+
+
+# ── pytest hooks: install before any conftest or test module is imported ─────────────────────────────
+
+
+def pytest_load_initial_conftests(early_config: Any, parser: Any, args: Any) -> None:
+    install()
+
+
+def pytest_configure(config: Any) -> None:
+    install()  # idempotent: covers a registration through the root conftest's fallback

{matrx_orm-3.1.201 → matrx_orm-3.1.203}/matrx_orm/schema_builder/diff_preview.py

@@ -725,6 +725,7 @@ def preview_schema_changes(
     from matrx_orm.core.config import register_database_from_env
     from matrx_orm.schema_builder.common import DEBUG_CONFIG, OutputConfig
     from matrx_orm.schema_builder.schema import entry_manager_flags
+    from matrx_orm.schema_builder.excluded_targets import excluded_targets, modeled_schemas
     from matrx_orm.schema_builder.schema_manager import SchemaManager
 
     caller_dir = Path(sys.argv[0]).parent.resolve()
@@ -804,6 +805,12 @@ def preview_schema_changes(
             include_tables=include_tables,
             exclude_tables=exclude_tables,
             manager_flags=manager_flags,
+            excluded_fk_targets=excluded_targets(cfg.get("generate", []), db_name),
+            modeled_schemas=modeled_schemas(
+                cfg.get("generate", []),
+                db_name,
+                next((d.get("additional_schemas") or [] for d in cfg.get("databases", []) if d.get("name") == db_name), []),
+            ),
         )
         manager.initialize()
 

matrx_orm-3.1.203/matrx_orm/schema_builder/excluded_targets.py

@@ -0,0 +1,93 @@
+"""A table excluded from generation is excluded as a REFERENCE target too.
+
+``exclude_tables`` under a schema's ``generate[]`` entry keeps that table's model out of the
+schema's file. A table in ANOTHER schema (or the same one) whose foreign key points at it would
+still emit ``ForeignKey(to_model='<Excluded>')`` and a ``get_*_with_related('<schema>.<table>')``
+manager method — a lazy reference that resolves to nothing at runtime and a relation that reads a
+table the host chose not to model. So every reference to an excluded table is dropped at load:
+the column generates as its plain type, and the relation (both directions) is not emitted.
+
+The excluded set is qualified (``schema.table``) and spans every ``generate[]`` entry of the same
+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
+is neither generated nor one of the database's ``additional_schemas`` is dropped the same way.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any
+
+
+def excluded_targets(generate_list: Iterable[dict[str, Any]], database: str) -> frozenset[str]:
+    """Every ``schema.table`` an ``exclude_tables`` list names for ``database``."""
+    out: set[str] = set()
+    for entry in generate_list:
+        if entry.get("database") != database:
+            continue
+        schema = entry.get("schema") or "public"
+        for table in entry.get("exclude_tables") or ():
+            out.add(f"{schema}.{table}")
+    return frozenset(out)
+
+
+def modeled_schemas(
+    generate_list: Iterable[dict[str, Any]], database: str, additional_schemas: Iterable[str] = ()
+) -> frozenset[str]:
+    """Every schema the host models for ``database``: the generated ones and its additional schemas."""
+    out = {"public", *additional_schemas}
+    out.update(e.get("schema") or "public" for e in generate_list if e.get("database") == database)
+    return frozenset(out)
+
+
+def drop_references_to(
+    excluded: frozenset[str] | set[str],
+    *,
+    schema: str,
+    processed_objects: list[dict[str, Any]],
+    full_relationships: list[dict[str, Any]],
+    modeled: frozenset[str] | set[str] | None = None,
+) -> list[str]:
+    """Remove every reference to an excluded table, or into a schema outside ``modeled``, in place.
+
+    Returns what was dropped, for the log. ``modeled=None`` keeps every schema.
+    """
+    if not excluded and modeled is None:
+        return []
+
+    def gone(target_schema: str, table: str) -> bool:
+        return f"{target_schema}.{table}" in excluded or (modeled is not None and target_schema not in modeled)
+
+    dropped: list[str] = []
+    for obj in processed_objects:
+        for column in obj.get("table_columns") or ():
+            fk = column.get("foreign_key_reference")
+            if not isinstance(fk, dict) or not fk.get("table"):
+                continue
+            target_schema = fk.get("schema") or "public"
+            if gone(target_schema, fk["table"]):
+                column["foreign_key_reference"] = None
+                dropped.append(
+                    f"{obj.get('schema')}.{obj.get('name')}.{column.get('name')} -> {target_schema}.{fk['table']}"
+                )
+    for rel in full_relationships:
+        fks = rel.get("foreign_keys")
+        if isinstance(fks, dict):
+            for key in [
+                k
+                for k, v in fks.items()
+                if isinstance(v, dict) and gone(v.get("foreign_schema") or schema, v.get("foreign_table") or k)
+            ]:
+                fks.pop(key)
+        refs = rel.get("referenced_by")
+        if isinstance(refs, dict):
+            # Keys of referenced_by are always tables of THIS schema (bare names).
+            for key in [k for k in refs if f"{schema}.{k}" in excluded]:
+                refs.pop(key)
+    return dropped
+
+
+__all__ = ["drop_references_to", "excluded_targets", "modeled_schemas"]

{matrx_orm-3.1.201 → matrx_orm-3.1.203}/matrx_orm/schema_builder/runner.py

@@ -19,6 +19,7 @@ from dotenv import load_dotenv
 from matrx_utils import vcprint
 
 from matrx_orm.core.config import DatabaseConfigError, register_database_from_env
+from matrx_orm.schema_builder.excluded_targets import excluded_targets, modeled_schemas
 from matrx_orm.schema_builder.common import (
     DEBUG_CONFIG,
     GenerationOutputOverrides,
@@ -386,6 +387,12 @@ def run_schema_generation(
                 output_config=output_config,
                 include_tables=include_tables,
                 exclude_tables=exclude_tables,
+                excluded_fk_targets=excluded_targets(cfg.get("generate", []), db_name),
+                modeled_schemas=modeled_schemas(
+                    cfg.get("generate", []),
+                    db_name,
+                    next((d.get("additional_schemas") or [] for d in cfg.get("databases", []) if d.get("name") == db_name), []),
+                ),
                 manager_flags=manager_flags,
                 skip_unchanged_managers=skip_unchanged_managers,
                 output_overrides=output_overrides,

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

@@ -39,6 +39,8 @@ class SchemaManager:
         manager_flags: dict | None = None,
         skip_unchanged_managers: bool = False,
         output_overrides: GenerationOutputOverrides | None = None,
+        excluded_fk_targets: frozenset[str] | set[str] | None = None,
+        modeled_schemas: frozenset[str] | set[str] | None = None,
     ):
         if additional_schemas is None:
             # Read from the registered database config if a project name is provided;
@@ -93,6 +95,13 @@ class SchemaManager:
         self._exclude_tables: set[str] | None = (
             set(exclude_tables) if exclude_tables is not None else None
         )
+        #: ``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.
+        self._modeled_schemas: frozenset[str] | None = (
+            frozenset(modeled_schemas) if modeled_schemas is not None else None
+        )
 
         vcprint(
             self.schema, title="SCHEMA MANAGER] with schema", verbose=self.verbose, color="blue"
@@ -160,6 +169,23 @@ class SchemaManager:
             self.overview_analysis,
         ) = get_db_objects(self.schema.name, self.database_project)
 
+        if self._excluded_fk_targets or self._modeled_schemas is not None:
+            from matrx_orm.schema_builder.excluded_targets import drop_references_to
+
+            dropped = drop_references_to(
+                self._excluded_fk_targets,
+                schema=self.schema.name or "public",
+                processed_objects=self.processed_objects,
+                full_relationships=self.full_relationships,
+                modeled=self._modeled_schemas,
+            )
+            if dropped:
+                vcprint(
+                    f"[MATRX ORM] {len(dropped)} reference(s) to an excluded or unmodeled table generate as plain "
+                    f"columns: {', '.join(dropped)}",
+                    color="yellow",
+                )
+
         # NOTE: no filtering here — all relationship/overview data loads in full so
         # that topological sort, FK resolution, and relationship analysis are always
         # correct.  The filter is applied in Schema.generate_models() just before

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

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.201"
+version = "3.1.203"
 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.58",
+    "matrx-utils>=2.0.59",
     "pyyaml>=6.0.3",
     "python-dotenv>=1.0",
     "cryptography>=43.0",
@@ -52,6 +52,7 @@ dependencies = [
 matrx_write_spill_guard = "matrx_orm.pytest_plugin"
 matrx_shared_lock_guard = "matrx_orm.pytest_lock_guard"
 matrx_live_db_guard = "matrx_orm.pytest_live_db_guard"
+matrx_production_door = "matrx_orm.pytest_production_door"
 
 [project.urls]
 Homepage = "https://github.com/AI-Matrix-Engine/aidream-current"