matrx-orm 3.1.0__tar.gz → 3.1.2__tar.gz

{matrx_orm-3.1.0 → matrx_orm-3.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matrx-orm
-Version: 3.1.0
+Version: 3.1.2
 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

{matrx_orm-3.1.0 → matrx_orm-3.1.2}/matrx_orm/session/dag.py

@@ -46,6 +46,9 @@ from matrx_orm.session.op import SessionOp
 
 logger = logging.getLogger("matrx_orm.session.dag")
 
+# (model, field) pairs already reported as unresolvable — see _resolve_fk_deps.
+_WARNED_UNRESOLVED_FKS: set[tuple[str, str]] = set()
+
 
 class DependencyCycleError(RuntimeError):
     """Raised when the Session ops describe a cyclic write dependency."""
@@ -131,7 +134,36 @@ def _resolve_fk_deps(
         fk_value = op.payload.get(fk_field_name)
         if fk_value is None:
             continue
-        related_model = getattr(fk_ref, "related_model", None)
+        # Resolving a bare-name FK reference can RAISE (ambiguous across
+        # databases, or a target whose model set was never imported — e.g. the
+        # `graveyard` schema). Neither is a reason to fail a WRITE: an
+        # unresolvable target cannot be a parent row in THIS flush, so it
+        # contributes no ordering constraint. Letting the raise escape is what
+        # detonated the 2026-07-11 'Users' persistence outage — an ambiguous
+        # NAME killed every write on the request. Ordering degrades to "no dep",
+        # which is exactly the on-disk-parent case this module already handles.
+        # The boot-time audit (assert_relations_resolvable) is what catches a
+        # genuinely broken reference — loudly, before any user request runs.
+        try:
+            related_model = fk_ref.related_model
+        except ValueError as exc:
+            # Warn ONCE per (model, field). `related_model` is a cached_property and
+            # exceptions are not cached, so it re-raises on every op of every flush —
+            # an unresolvable FK on a hot table would otherwise flood app_log forever
+            # and bury the signal it exists to raise.
+            key = (getattr(op.model_cls, "__name__", "?"), fk_field_name)
+            if key not in _WARNED_UNRESOLVED_FKS:
+                _WARNED_UNRESOLVED_FKS.add(key)
+                logger.warning(
+                    "[matrx_orm.session] FK '%s.%s' did not resolve (%s) — no in-flush "
+                    "dependency inferred for it. The write proceeds; fix the reference "
+                    "(regenerate models) so the boot audit stays clean. This warns once "
+                    "per process.",
+                    key[0],
+                    key[1],
+                    exc,
+                )
+            continue
         if related_model is None:
             continue
         # Resolve the related model's PK field name.

{matrx_orm-3.1.0 → matrx_orm-3.1.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.0"
+version = "3.1.2"
 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" }

{matrx_orm-3.1.0 → matrx_orm-3.1.2}/tests/session/test_dag.py

@@ -79,3 +79,45 @@ def test_tier_summary_counts(FakeConversation, FakeMessage):
     tiers = tier_ops(ops)
     summary = tier_summary(tiers)
     assert summary == [{"cx_conversation": 1}, {"cx_message": 2}]
+
+
+class _UnresolvableFK:
+    """A ForeignKeyReference whose bare-name target does not resolve — the
+    shape that caused the 2026-07-11 'Users' outage ('ambiguous across
+    databases') and the one that a dropped/ungenerated target still produces
+    ('Model X not found in schema graveyard')."""
+
+    def __init__(self, message: str) -> None:
+        self._message = message
+
+    @property
+    def related_model(self):
+        raise ValueError(self._message)
+
+
+@pytest.mark.parametrize(
+    "message",
+    [
+        "Model name 'Users' is ambiguous across ['cms.auth', 'main.auth'].",
+        "Model CompiledRecipe not found in schema 'graveyard'",
+    ],
+)
+def test_unresolvable_fk_reference_does_not_kill_the_write(FakeMessage, message):
+    from matrx_orm.session.dag import _WARNED_UNRESOLVED_FKS
+
+    _WARNED_UNRESOLVED_FKS.clear()
+    """A NAME that won't resolve must never fail a WRITE.
+
+    An unresolvable target cannot be a parent row in THIS flush, so it carries
+    no ordering constraint — the op still lands. Letting the ValueError escape
+    is what aborted every persisted write on the request during the outage.
+    """
+    FakeMessage._meta.foreign_keys = {"user_id": _UnresolvableFK(message)}
+    try:
+        ops = [make_insert(FakeMessage, {"id": "m1", "user_id": "u1"})]
+        tiers = tier_ops(ops)
+    finally:
+        FakeMessage._meta.foreign_keys = {}
+
+    assert len(tiers) == 1
+    assert tiers[0][0].pk_value == "m1"