matrx-orm 3.1.10__tar.gz → 3.1.11__tar.gz

{matrx_orm-3.1.10 → matrx_orm-3.1.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matrx-orm
-Version: 3.1.10
+Version: 3.1.11
 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.10 → matrx_orm-3.1.11}/matrx_orm/__init__.py

@@ -282,13 +282,16 @@ from matrx_orm.session import (
     SessionPhase,
     WatchedLifecycleConfig,
     WatchedLifecycleRegistry,
-    allow_direct_managed_write,
+    COORDINATOR_BYPASS_ACKNOWLEDGEMENT,
+    allow_direct_coordinator_write,
+    coordinator_policy_tables,
     current_session,
     declare_managed,
     drain_spilled_ops,
     is_in_session,
     record_error,
     record_failures,
+    register_coordinator_owned_model,
 )
 from matrx_orm.session import (
     run_sweeper as run_lifecycle_sweeper,
@@ -299,7 +302,10 @@ from matrx_orm.session import (
 
 __all__ = [
     "CoordinatorWriteViolation",
-    "allow_direct_managed_write",
+    "COORDINATOR_BYPASS_ACKNOWLEDGEMENT",
+    "allow_direct_coordinator_write",
+    "coordinator_policy_tables",
+    "register_coordinator_owned_model",
     # ── Configuration ──────────────────────────────────────────────────────────
     "DatabaseProjectConfig",
     "register_database",

{matrx_orm-3.1.10 → matrx_orm-3.1.11}/matrx_orm/query/executor.py

@@ -957,6 +957,12 @@ class QueryExecutor:
         (default ``BaseAdapter`` behaviour) so callers can fall through to the
         SQL path.
         """
+        from matrx_orm.session.managed import assert_model_write_allowed
+
+        assert_model_write_allowed(
+            self.model,
+            str(query.get("operation") or "adapter write"),
+        )
         return await self.db.execute_write_dict(query)
 
     async def insert(self, query: dict[str, Any]) -> dict[str, Any]:

{matrx_orm-3.1.10 → matrx_orm-3.1.11}/matrx_orm/session/__init__.py

@@ -67,9 +67,12 @@ from matrx_orm.session.lifecycle import (
     sweep_once,
 )
 from matrx_orm.session.managed import (
-    allow_direct_managed_write,
+    COORDINATOR_BYPASS_ACKNOWLEDGEMENT,
+    allow_direct_coordinator_write,
+    coordinator_policy_tables,
     declare_managed,
     install_managed_writes,
+    register_coordinator_owned_model,
 )
 from matrx_orm.session.op import (
     OpType,
@@ -112,10 +115,13 @@ __all__ = [
     "coalesce_ops",
     "config_from_meta",
     "current_session",
-    "allow_direct_managed_write",
+    "COORDINATOR_BYPASS_ACKNOWLEDGEMENT",
+    "allow_direct_coordinator_write",
+    "coordinator_policy_tables",
     "declare_managed",
     "has_pending_in_stack",
     "install_managed_writes",
+    "register_coordinator_owned_model",
     "is_in_session",
     "pending_ops_across_stack",
     "make_delete",

{matrx_orm-3.1.10 → matrx_orm-3.1.11}/matrx_orm/session/errors.py

@@ -66,7 +66,9 @@ class CoordinatorWriteViolation(ManagedWriteViolation):
             f"Session scope is {actual_scope!r}. Queue this write through its "
             "Coordinator so parent and child rows share one transactional DAG. "
             "For a genuine out-of-request maintenance operation, use "
-            "allow_direct_managed_write(model, reason='...') explicitly.",
+            "allow_direct_coordinator_write(model, reason='...', "
+            "acknowledgement="
+            "'YES_I_KNOW_I_AM_SKIPPING_THE_COORDINATOR_ON_PURPOSE') explicitly.",
         )
         self.model_name = model_name
         self.op_kind = op_kind

{matrx_orm-3.1.10 → matrx_orm-3.1.11}/matrx_orm/session/managed.py

@@ -11,7 +11,7 @@ A Model opts into Session-aware writes by declaring
             # OR
             managed_writes = "strict"    # raise ManagedWriteViolation if no Session
             # OR
-            managed_writes = "coordinator"  # require a named owner Session
+            managed_writes = "coordinator"  # audit writes lacking owner authority
 
 When the Model's ``create`` / ``update`` / ``delete`` / ``bulk_*`` /
 ``upsert`` methods are called:
@@ -24,6 +24,9 @@ When the Model's ``create`` / ``update`` / ``delete`` / ``bulk_*`` /
        was a direct write.
     3. If NO active Session AND mode == ``"strict"``, raise
        :class:`ManagedWriteViolation` — loud red banner, full stack trace.
+    4. Coordinator mode never blocks a write. A write without the Coordinator's
+       opaque authority (or an acknowledged exact-model override) continues and
+       emits a large red ERROR diagnostic. Authorized writes are silent.
 
 For backward compatibility, this layer activates only when
 ``managed_writes`` is truthy. Unmanaged Models keep their current
@@ -61,7 +64,6 @@ from matrx_utils import vcprint
 
 from matrx_orm.session.errors import (
     MANAGED_WRITE_SKILL_HINT,
-    CoordinatorWriteViolation,
     ManagedWriteViolation,
 )
 from matrx_orm.session.session import Session, SessionPhase, session_stack
@@ -95,10 +97,16 @@ _STRICT_TABLES: set[str] = set()
 # merely opening a Session/transaction is not authority to write the table.
 _COORDINATOR_TABLES: dict[str, str] = {}
 
+_COORDINATOR_AUTHORITY = object()
+
+COORDINATOR_BYPASS_ACKNOWLEDGEMENT = (
+    "YES_I_KNOW_I_AM_SKIPPING_THE_COORDINATOR_ON_PURPOSE"
+)
+
 
 @dataclass(frozen=True, slots=True)
 class DirectWriteException:
-    model_name: str
+    model_cls: type
     reason: str
 
 
@@ -109,22 +117,23 @@ _direct_write_exceptions: ContextVar[tuple[DirectWriteException, ...]] = Context
 
 
 @contextmanager
-def allow_direct_managed_write(model_cls: type, *, reason: str) -> Iterator[None]:
-    """Explicit, scoped escape hatch for coordinator-owned maintenance writes.
-
-    ``reason`` is mandatory and appears in logs. This is intentionally not a
-    boolean flag: exceptional code must state why it cannot use the owner.
-    """
+def allow_direct_coordinator_write(
+    model_cls: type,
+    *,
+    reason: str,
+    acknowledgement: str,
+) -> Iterator[None]:
+    """Temporarily acknowledge one model's intentional Coordinator bypass."""
     cleaned = reason.strip()
     if not cleaned:
-        raise ValueError("allow_direct_managed_write requires a non-empty reason")
-    exception = DirectWriteException(model_cls.__name__, cleaned)
+        raise ValueError("allow_direct_coordinator_write requires a non-empty reason")
+    if acknowledgement != COORDINATOR_BYPASS_ACKNOWLEDGEMENT:
+        raise ValueError(
+            "allow_direct_coordinator_write requires acknowledgement="
+            f"{COORDINATOR_BYPASS_ACKNOWLEDGEMENT!r}"
+        )
+    exception = DirectWriteException(model_cls, cleaned)
     token = _direct_write_exceptions.set(_direct_write_exceptions.get() + (exception,))
-    logger.warning(
-        "DIRECT WRITE EXCEPTION entered for %s: %s",
-        model_cls.__name__,
-        cleaned,
-    )
     try:
         yield
     finally:
@@ -132,7 +141,22 @@ def allow_direct_managed_write(model_cls: type, *, reason: str) -> Iterator[None
 
 
 def _has_direct_exception(model_cls: type) -> bool:
-    return any(item.model_name == model_cls.__name__ for item in _direct_write_exceptions.get())
+    return any(item.model_cls is model_cls for item in _direct_write_exceptions.get())
+
+
+def _coordinator_session(*, database: str | None = None) -> Session:
+    """Create the Session capability reserved for matrx-ai's Coordinator."""
+    from matrx_orm.session.session import Session as SessionClass
+
+    return SessionClass(
+        database=database,
+        write_scope="coordinator",
+        _write_authority=_COORDINATOR_AUTHORITY,
+    )
+
+
+def _has_coordinator_authority(session: Session | None) -> bool:
+    return session is not None and session._has_write_authority(_COORDINATOR_AUTHORITY)
 
 # Leading INSERT INTO / UPDATE / DELETE FROM target — ORM-generated SQL only.
 _WRITE_TARGET_RE = re.compile(
@@ -162,7 +186,20 @@ def _register_coordinator_table(model_cls: type, required_scope: str) -> None:
         getattr(meta, "table_name", None),
     ):
         if name:
-            _COORDINATOR_TABLES[str(name).strip('"')] = required_scope
+            normalized = str(name).strip('"')
+            _COORDINATOR_TABLES[normalized] = required_scope
+            _STRICT_TABLES.discard(normalized)
+
+
+def register_coordinator_owned_model(entry: Any) -> None:
+    """Host registrar consumed by matrx-ai's package-independent registry."""
+    model_cls = entry.model_cls
+    declare_managed(model_cls, mode="coordinator", write_scope="coordinator")
+
+
+def coordinator_policy_tables() -> dict[str, str]:
+    """Return installed table policies for startup/release diagnostics."""
+    return dict(_COORDINATOR_TABLES)
 
 
 def _coordinator_scope_for_model(model_cls: type) -> str | None:
@@ -183,11 +220,11 @@ def assert_model_write_allowed(
     op_kind: str,
     *,
     session: Session | None = None,
-) -> None:
-    """Reject a coordinator-owned Model write without its owner Session."""
+) -> bool:
+    """Warn on a Coordinator-owned Model write without Coordinator authority."""
     required_scope = _coordinator_scope_for_model(model_cls)
     if required_scope is None or _has_direct_exception(model_cls):
-        return
+        return True
     active = session
     if active is None:
         for candidate in reversed(session_stack()):
@@ -195,19 +232,14 @@ def assert_model_write_allowed(
                 active = candidate
                 break
     actual_scope = active.write_scope if active is not None else None
-    if actual_scope == required_scope:
-        return
+    if _has_coordinator_authority(active):
+        return True
     banner = _format_coordinator_banner(
         model_cls.__name__, op_kind, required_scope, actual_scope
     )
     vcprint(banner, color="red")
     logger.error("CoordinatorWriteViolation: %s", banner)
-    raise CoordinatorWriteViolation(
-        model_cls.__name__,
-        op_kind,
-        required_scope=required_scope,
-        actual_scope=actual_scope,
-    )
+    return False
 
 
 def _has_active_open_session() -> bool:
@@ -248,9 +280,11 @@ def assert_managed_write_allowed(query: str) -> None:
         else:
             actual = _active_write_scope()
             if actual != required_scope:
-                raise CoordinatorWriteViolation(
-                    token, "write", required_scope=required_scope, actual_scope=actual
+                banner = _format_coordinator_banner(
+                    token, "write", required_scope, actual
                 )
+                vcprint(banner, color="red", log_level="ERROR")
+                logger.error("CoordinatorWriteViolation: %s", banner)
         return
     # Governed contexts — always allowed:
     if _has_active_open_session():
@@ -529,6 +563,7 @@ def _wrap_classmethod(model_cls: type, method_name: str, original: Any, mode: st
 
     @functools.wraps(original_func)
     async def wrapped(cls, *args, **kwargs):
+        active_mode = _managed_mode(cls) or mode
         # Reentrancy guard: when the flush executor calls bulk_create /
         # bulk_update / bulk_delete to actually write rows, those calls
         # must pass through unchanged. Without this check we'd recurse
@@ -552,7 +587,7 @@ def _wrap_classmethod(model_cls: type, method_name: str, original: Any, mode: st
                 session = candidate
                 break
         if session is not None:
-            if mode == "coordinator":
+            if active_mode == "coordinator":
                 assert_model_write_allowed(cls, method_name, session=session)
             # Defer to the active Session.
             return await _defer_to_session(
@@ -565,10 +600,10 @@ def _wrap_classmethod(model_cls: type, method_name: str, original: Any, mode: st
             )
 
         # No active Session.
-        if mode == "coordinator":
+        if active_mode == "coordinator":
             assert_model_write_allowed(cls, method_name)
 
-        if mode == "strict":
+        if active_mode == "strict":
             banner = _format_violation_banner(cls.__name__, method_name)
             vcprint(banner, color="red")
             logger.error(
@@ -750,15 +785,20 @@ def _format_coordinator_banner(
     return (
         "\n"
         "████████████████████████████████████████████████████████████████████\n"
-        "██  COORDINATOR-OWNED TABLE — DIRECT WRITE FORBIDDEN              ██\n"
+        "██  COORDINATOR OWNERSHIP BYPASS — WRITE CONTINUED               ██\n"
         "████████████████████████████████████████████████████████████████████\n"
         f"  Model       : {model_name}\n"
         f"  Operation   : {op_kind}\n"
         f"  Required    : Session(write_scope={required_scope!r})\n"
         f"  Actual      : Session(write_scope={actual_scope!r})\n"
+        "  Result      : the write was NOT blocked, but bypassed its owner.\n"
         "  Fix         : queue this write through the registered Coordinator.\n"
-        "  Exception   : allow_direct_managed_write(Model, reason='...')\n"
-        "                is reserved for genuine out-of-request maintenance.\n"
+        "  Override    : allow_direct_coordinator_write(\n"
+        "                    Model, reason='...',\n"
+        "                    acknowledgement=\n"
+        f"                    {COORDINATOR_BYPASS_ACKNOWLEDGEMENT!r},\n"
+        "                )\n"
+        "                is reserved for intentional out-of-request writes.\n"
         "████████████████████████████████████████████████████████████████████\n"
     )
 

{matrx_orm-3.1.10 → matrx_orm-3.1.11}/matrx_orm/session/session.py

@@ -233,6 +233,7 @@ class Session:
         "_opened_at",
         "_stack_token",
         "_write_scope",
+        "_write_authority",
     )
 
     def __init__(
@@ -243,6 +244,7 @@ class Session:
         expected_writes: int | None = None,
         max_age_secs: int | None = None,
         write_scope: str | None = None,
+        _write_authority: object | None = None,
     ) -> None:
         self._id = str(uuid.uuid4())
         self._database = database
@@ -256,6 +258,7 @@ class Session:
         self._opened_at = datetime.now(UTC)
         self._stack_token: Any = None
         self._write_scope = write_scope
+        self._write_authority = _write_authority
 
     # ---------------------- properties / introspection -------------------
 
@@ -285,6 +288,9 @@ class Session:
         """
         return self._write_scope
 
+    def _has_write_authority(self, authority: object) -> bool:
+        return self._write_authority is authority
+
     @property
     def report(self) -> FlushReport | None:
         return self._report

{matrx_orm-3.1.10 → matrx_orm-3.1.11}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.10"
+version = "3.1.11"
 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.10 → matrx_orm-3.1.11}/tests/level1/test_managed_write_guard.py

@@ -109,7 +109,7 @@ class TestDeclareManagedRegistersStrictTable:
 
 
 class TestCoordinatorOwnedGuard:
-    def test_plain_session_cannot_defer_to_owned_model(self):
+    def test_plain_session_warns_but_still_defers(self, caplog):
         model = _make_model(
             "OwnedThing",
             {"id": UUIDField(primary_key=True), "_table_name": "owned_thing"},
@@ -117,12 +117,12 @@ class TestCoordinatorOwnedGuard:
         M.declare_managed(model, mode="coordinator", write_scope="request_writer")
 
         from matrx_orm import Session
-        from matrx_orm.session.errors import CoordinatorWriteViolation
-
-        with pytest.raises(CoordinatorWriteViolation):
-            Session().defer_insert(model, {"id": "abc"})
+        session = Session()
+        session.defer_insert(model, {"id": "abc"})
+        assert session.ops_count == 1
+        assert "COORDINATOR OWNERSHIP BYPASS" in caplog.text
 
-    def test_matching_session_scope_can_defer(self):
+    def test_forged_scope_warns_but_still_defers(self, caplog):
         model = _make_model(
             "OwnedThing",
             {"id": UUIDField(primary_key=True), "_table_name": "owned_thing"},
@@ -134,8 +134,22 @@ class TestCoordinatorOwnedGuard:
         session = Session(write_scope="request_writer")
         session.defer_insert(model, {"id": "abc"})
         assert session.ops_count == 1
+        assert "COORDINATOR OWNERSHIP BYPASS" in caplog.text
+
+    def test_real_coordinator_authority_is_silent(self, caplog):
+        model = _make_model(
+            "OwnedThing",
+            {"id": UUIDField(primary_key=True), "_table_name": "owned_thing"},
+        )
+        M.declare_managed(model, mode="coordinator")
+
+        caplog.clear()
+        session = M._coordinator_session()
+        session.defer_insert(model, {"id": "abc"})
+        assert session.ops_count == 1
+        assert not [r for r in caplog.records if r.name == "matrx_orm.session.managed"]
 
-    def test_reason_bearing_exception_allows_plain_session(self):
+    def test_acknowledged_exception_is_silent(self, caplog):
         model = _make_model(
             "OwnedThing",
             {"id": UUIDField(primary_key=True), "_table_name": "owned_thing"},
@@ -144,8 +158,37 @@ class TestCoordinatorOwnedGuard:
 
         from matrx_orm import Session
 
-        with M.allow_direct_managed_write(model, reason="repair migration 0044"):
+        caplog.clear()
+        with M.allow_direct_coordinator_write(
+            model,
+            reason="repair migration 0044",
+            acknowledgement=M.COORDINATOR_BYPASS_ACKNOWLEDGEMENT,
+        ):
             Session().defer_insert(model, {"id": "abc"})
+        assert not [r for r in caplog.records if r.name == "matrx_orm.session.managed"]
+
+    def test_override_does_not_authorize_another_model(self, caplog):
+        allowed_model = _make_model(
+            "AllowedThing",
+            {"id": UUIDField(primary_key=True), "_table_name": "allowed_thing"},
+        )
+        other_model = _make_model(
+            "OtherThing",
+            {"id": UUIDField(primary_key=True), "_table_name": "other_thing"},
+        )
+        M.declare_managed(allowed_model, mode="coordinator")
+        M.declare_managed(other_model, mode="coordinator")
+
+        from matrx_orm import Session
+
+        caplog.clear()
+        with M.allow_direct_coordinator_write(
+            allowed_model,
+            reason="one-model maintenance",
+            acknowledgement=M.COORDINATOR_BYPASS_ACKNOWLEDGEMENT,
+        ):
+            Session().defer_insert(other_model, {"id": "abc"})
+        assert "COORDINATOR OWNERSHIP BYPASS" in caplog.text
 
     def test_empty_exception_reason_is_rejected(self):
         model = _make_model(
@@ -153,5 +196,31 @@ class TestCoordinatorOwnedGuard:
             {"id": UUIDField(primary_key=True), "_table_name": "owned_thing"},
         )
         with pytest.raises(ValueError):
-            with M.allow_direct_managed_write(model, reason="   "):
+            with M.allow_direct_coordinator_write(
+                model,
+                reason="   ",
+                acknowledgement=M.COORDINATOR_BYPASS_ACKNOWLEDGEMENT,
+            ):
+                pass
+
+    def test_wrong_acknowledgement_is_rejected(self):
+        model = _make_model(
+            "OwnedThing",
+            {"id": UUIDField(primary_key=True), "_table_name": "owned_thing"},
+        )
+        with pytest.raises(ValueError):
+            with M.allow_direct_coordinator_write(
+                model,
+                reason="repair migration 0044",
+                acknowledgement="yes",
+            ):
                 pass
+
+    def test_raw_write_warns_but_does_not_raise(self, caplog):
+        model = _make_model(
+            "OwnedThing",
+            {"id": UUIDField(primary_key=True), "_table_name": "owned_thing"},
+        )
+        M.declare_managed(model, mode="coordinator")
+        M.assert_managed_write_allowed("UPDATE owned_thing SET x=1")
+        assert "COORDINATOR OWNERSHIP BYPASS" in caplog.text