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

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

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

@@ -270,6 +270,7 @@ def _lazy_api():
 # ordering, coalescing, pending-aware reads, managed-write enforcement,
 # transactional flush, watchdog integration. See matrx_orm/session/.
 from matrx_orm.session import (
+    CoordinatorWriteViolation,
     DependencyCycleError,
     FlushError,
     FlushReport,
@@ -281,12 +282,16 @@ from matrx_orm.session import (
     SessionPhase,
     WatchedLifecycleConfig,
     WatchedLifecycleRegistry,
+    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,
@@ -296,6 +301,11 @@ from matrx_orm.session import (
 )
 
 __all__ = [
+    "CoordinatorWriteViolation",
+    "COORDINATOR_BYPASS_ACKNOWLEDGEMENT",
+    "allow_direct_coordinator_write",
+    "coordinator_policy_tables",
+    "register_coordinator_owned_model",
     # ── Configuration ──────────────────────────────────────────────────────────
     "DatabaseProjectConfig",
     "register_database",

{matrx_orm-3.1.9 → matrx_orm-3.1.11}/matrx_orm/core/async_db_manager.py

@@ -36,6 +36,20 @@ from matrx_orm.exceptions import (
 
 logger = logging.getLogger("matrx_orm.async_db_manager")
 
+
+def _resolve_ssl(value: Any) -> Any:
+    """Normalize DatabaseProjectConfig.ssl for asyncpg's ``ssl=`` kwarg.
+
+    ``False`` / ``"disable"`` / ``"off"`` → no TLS (Coolify / local Postgres).
+    Everything else is passed through (default ``"require"`` for Supabase).
+    """
+    if value is False or value is None:
+        return False
+    if isinstance(value, str) and value.strip().lower() in {"disable", "off", "false", "0"}:
+        return False
+    return value
+
+
 # asyncpg SQLSTATE class 42 "undefined …" — the SQL named something the live DB
 # does not have. All siblings of SyntaxOrAccessError; PostgresSyntaxError is
 # caught separately (it's an ORM-bug shape, not a schema-drift shape). These map
@@ -409,7 +423,7 @@ class AsyncDatabaseManager:
                             max_size=config.get("pool_max", 30),
                             command_timeout=config.get("command_timeout", 10),
                             max_inactive_connection_lifetime=max_inactive_connection_lifetime,
-                            ssl="require",
+                            ssl=_resolve_ssl(config.get("ssl", "require")),
                             statement_cache_size=statement_cache_size,
                             server_settings=server_settings,
                             init=init_callback,

{matrx_orm-3.1.9 → matrx_orm-3.1.11}/matrx_orm/core/config.py

@@ -83,6 +83,14 @@ class DatabaseProjectConfig:
     # Supabase compute can spike first-query latency on cold connections).
     server_settings: dict[str, str] = field(default_factory=dict)
 
+    # TLS for the asyncpg pool. Default ``"require"`` matches Supabase /
+    # managed Postgres (which reject plaintext). Direct Coolify / local
+    # Postgres images typically have ``ssl=off`` — set ``ssl=False`` (or
+    # ``"disable"``) for those. Accepted values are whatever asyncpg accepts
+    # for its ``ssl=`` kwarg (``False``, ``True``, ``"require"``, an
+    # ``ssl.SSLContext``, …).
+    ssl: Any = "require"
+
     # Write queue — gates write operations behind an async queue so they wait in
     # order instead of racing for pool connections and timing out under load.
     write_queue_enabled: bool = True
@@ -242,6 +250,7 @@ class DatabaseRegistry:
             "command_timeout": config.command_timeout,
             "session_init_sql": list(config.session_init_sql),
             "server_settings": dict(config.server_settings),
+            "ssl": config.ssl,
             "write_queue_enabled": config.write_queue_enabled,
             "write_concurrency": config.write_concurrency,
             "write_queue_size": config.write_queue_size,
@@ -408,6 +417,7 @@ def register_database_from_env(
     command_timeout: int | None = None,
     session_init_sql: list[str] | None = None,
     server_settings: dict[str, str] | None = None,
+    ssl: Any = None,
     write_queue_enabled: bool | None = None,
     write_concurrency: int | None = None,
     write_queue_size: int | None = None,
@@ -562,6 +572,13 @@ def register_database_from_env(
         supabase_secret_key or os.environ.get(_supabase_secret_env, "").strip()
     )
 
+    _ssl_env = _overrides.get("SSL", f"{env_prefix}_SSL")
+    if ssl is not None:
+        _resolved_ssl: Any = ssl
+    else:
+        _ssl_raw = os.environ.get(_ssl_env, "").strip()
+        _resolved_ssl = _ssl_raw if _ssl_raw else "require"
+
     try:
         config = DatabaseProjectConfig(
             name=name,
@@ -582,6 +599,7 @@ def register_database_from_env(
             supabase_secret_key=_resolved_supabase_secret_key,
             session_init_sql=list(session_init_sql or []),
             server_settings=dict(server_settings or {}),
+            ssl=_resolved_ssl,
             **pool_kwargs,
         )
         registry.register(config)

{matrx_orm-3.1.9 → 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.9 → matrx_orm-3.1.11}/matrx_orm/session/__init__.py

@@ -50,6 +50,7 @@ Usage:
 from matrx_orm.session.coalesce import coalesce_ops, summarize
 from matrx_orm.session.dag import DependencyCycleError, tier_ops, tier_summary
 from matrx_orm.session.errors import (
+    CoordinatorWriteViolation,
     FlushError,
     ManagedWriteViolation,
     SessionClosedError,
@@ -65,7 +66,14 @@ from matrx_orm.session.lifecycle import (
     run_sweeper,
     sweep_once,
 )
-from matrx_orm.session.managed import declare_managed, install_managed_writes
+from matrx_orm.session.managed import (
+    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,
     SessionOp,
@@ -90,6 +98,7 @@ from matrx_orm.session.session import (
 
 __all__ = [
     "DependencyCycleError",
+    "CoordinatorWriteViolation",
     "FlushError",
     "FlushReport",
     "ManagedWriteViolation",
@@ -106,9 +115,13 @@ __all__ = [
     "coalesce_ops",
     "config_from_meta",
     "current_session",
+    "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.9 → matrx_orm-3.1.11}/matrx_orm/session/errors.py

@@ -48,6 +48,34 @@ class ManagedWriteViolation(SessionError):
         self.op_kind = op_kind
 
 
+class CoordinatorWriteViolation(ManagedWriteViolation):
+    """Raised when a coordinator-owned Model is written by another path."""
+
+    def __init__(
+        self,
+        model_name: str,
+        op_kind: str,
+        *,
+        required_scope: str,
+        actual_scope: str | None,
+    ) -> None:
+        SessionError.__init__(
+            self,
+            f"{model_name} is coordinator-owned (required write scope: "
+            f"{required_scope!r}). Direct {op_kind} is forbidden; the active "
+            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_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
+        self.required_scope = required_scope
+        self.actual_scope = actual_scope
+
+
 class SessionClosedError(SessionError):
     """Raised when an op is queued onto a Session that has already flushed
     or errored. Generally callers should use ``async with Session():`` so

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

@@ -1,8 +1,8 @@
 """Managed Model write interception — the runtime enforcement layer.
 
 A Model opts into Session-aware writes by declaring
-``Meta.managed_writes`` as either ``"elevate"`` (default behavior when
-``True``) or ``"strict"``::
+``Meta.managed_writes`` as ``"elevate"`` (default behavior when ``True``),
+``"strict"``, or ``"coordinator"``::
 
     class Conversation(Model):
         ...
@@ -10,6 +10,8 @@ A Model opts into Session-aware writes by declaring
             managed_writes = "elevate"   # auto-open one-shot if no Session
             # OR
             managed_writes = "strict"    # raise ManagedWriteViolation if no Session
+            # OR
+            managed_writes = "coordinator"  # audit writes lacking owner authority
 
 When the Model's ``create`` / ``update`` / ``delete`` / ``bulk_*`` /
 ``upsert`` methods are called:
@@ -22,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
@@ -49,12 +54,18 @@ from __future__ import annotations
 import functools
 import logging
 import re
-from contextlib import asynccontextmanager
+from contextlib import asynccontextmanager, contextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass
+from collections.abc import Iterator
 from typing import Any
 
 from matrx_utils import vcprint
 
-from matrx_orm.session.errors import MANAGED_WRITE_SKILL_HINT, ManagedWriteViolation
+from matrx_orm.session.errors import (
+    MANAGED_WRITE_SKILL_HINT,
+    ManagedWriteViolation,
+)
 from matrx_orm.session.session import Session, SessionPhase, session_stack
 
 logger = logging.getLogger("matrx_orm.session.managed")
@@ -82,6 +93,71 @@ logger = logging.getLogger("matrx_orm.session.managed")
 
 _STRICT_TABLES: set[str] = set()
 
+# table token -> required Session.write_scope. This is stronger than strict:
+# 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_cls: type
+    reason: str
+
+
+_direct_write_exceptions: ContextVar[tuple[DirectWriteException, ...]] = ContextVar(
+    "matrx_orm_direct_write_exceptions",
+    default=(),
+)
+
+
+@contextmanager
+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_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,))
+    try:
+        yield
+    finally:
+        _direct_write_exceptions.reset(token)
+
+
+def _has_direct_exception(model_cls: type) -> bool:
+    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(
     r"^\s*(?:INSERT\s+INTO|UPDATE|DELETE\s+FROM)\s+([^\s(]+)",
@@ -101,6 +177,71 @@ def _register_strict_table(model_cls: type) -> None:
             _STRICT_TABLES.add(str(name).strip('"'))
 
 
+def _register_coordinator_table(model_cls: type, required_scope: str) -> None:
+    meta = getattr(model_cls, "_meta", None)
+    if meta is None:
+        return
+    for name in (
+        getattr(meta, "qualified_table_name", None),
+        getattr(meta, "table_name", None),
+    ):
+        if name:
+            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:
+    meta = getattr(model_cls, "_meta", None)
+    if meta is None:
+        return None
+    for name in (
+        getattr(meta, "qualified_table_name", None),
+        getattr(meta, "table_name", None),
+    ):
+        if name and (scope := _COORDINATOR_TABLES.get(str(name).strip('"'))):
+            return scope
+    return None
+
+
+def assert_model_write_allowed(
+    model_cls: type,
+    op_kind: str,
+    *,
+    session: Session | None = None,
+) -> 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 True
+    active = session
+    if active is None:
+        for candidate in reversed(session_stack()):
+            if candidate.phase is SessionPhase.OPEN:
+                active = candidate
+                break
+    actual_scope = active.write_scope if active is not None else None
+    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)
+    return False
+
+
 def _has_active_open_session() -> bool:
     for candidate in reversed(session_stack()):
         if candidate.phase is SessionPhase.OPEN:
@@ -116,12 +257,37 @@ def assert_managed_write_allowed(query: str) -> None:
     — when no strict table exists. Best-effort table parsing: ORM-generated DML
     only; a query we can't parse is allowed through (the wrappers + the strict
     create path remain the first line of defense)."""
-    if not _STRICT_TABLES:
+    if not _STRICT_TABLES and not _COORDINATOR_TABLES:
         return
-    # Governed contexts — always allowed:
+    # Session.defer_* is authority-checked before an op can enter a flush.
+    # The flush may run in a deliberately detached context where its Session
+    # stack is absent, so the internal execution phase is trusted here.
     from matrx_orm.session.flush import is_flushing
 
-    if is_flushing() or _has_active_open_session():
+    if is_flushing():
+        return
+    m = _WRITE_TARGET_RE.match(query)
+    if not m:
+        return
+    token = m.group(1).strip().strip('"')
+    bare_token = token.split(".")[-1].strip('"')
+
+    required_scope = _COORDINATOR_TABLES.get(token) or _COORDINATOR_TABLES.get(bare_token)
+    if required_scope is not None:
+        model_cls = _model_for_coordinator_table(token, bare_token)
+        if model_cls is not None:
+            assert_model_write_allowed(model_cls, "write")
+        else:
+            actual = _active_write_scope()
+            if actual != required_scope:
+                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():
         return
     try:
         from matrx_orm.core.transaction import get_active_connection
@@ -131,10 +297,6 @@ def assert_managed_write_allowed(query: str) -> None:
     except ImportError:
         pass
 
-    m = _WRITE_TARGET_RE.match(query)
-    if not m:
-        return
-    token = m.group(1).strip().strip('"')
     if token in _STRICT_TABLES or token.split(".")[-1].strip('"') in _STRICT_TABLES:
         banner = _format_chokepoint_banner(token)
         vcprint(banner, color="red")
@@ -146,6 +308,33 @@ def assert_managed_write_allowed(query: str) -> None:
         raise ManagedWriteViolation(token, "write (ungoverned)")
 
 
+def _active_write_scope() -> str | None:
+    for candidate in reversed(session_stack()):
+        if candidate.phase is SessionPhase.OPEN:
+            return candidate.write_scope
+    return None
+
+
+def _model_for_coordinator_table(token: str, bare_token: str) -> type | None:
+    from matrx_orm.core.registry import ModelRegistry
+
+    for model_cls in ModelRegistry.all_models().values():
+        meta = getattr(model_cls, "_meta", None)
+        if meta is None:
+            continue
+        names = {
+            str(name).strip('"')
+            for name in (
+                getattr(meta, "qualified_table_name", None),
+                getattr(meta, "table_name", None),
+            )
+            if name
+        }
+        if token in names or bare_token in names:
+            return model_cls
+    return None
+
+
 def is_strict_table(model_cls: type) -> bool:
     """True if ``model_cls``'s table is registered ``strict`` (execute_write-guarded).
 
@@ -235,6 +424,13 @@ def _apply_wrapping(model_cls: type, mode: str) -> None:
         # Register for the universal execute_write guard so update/delete/
         # QueryBuilder/raw-SQL paths are enforced too, not just create/bulk_*.
         _register_strict_table(model_cls)
+    elif mode == "coordinator":
+        required_scope = getattr(
+            getattr(model_cls, "_meta", None),
+            "managed_write_scope",
+            "coordinator",
+        )
+        _register_coordinator_table(model_cls, str(required_scope))
     for method_name in _WRITE_METHODS:
         original = getattr(model_cls, method_name, None)
         if original is None:
@@ -251,6 +447,7 @@ def declare_managed(
     model_cls: type,
     *,
     mode: str = "elevate",
+    write_scope: str = "coordinator",
     watched_lifecycle: dict | None = None,
 ) -> None:
     """Programmatic equivalent of declaring ``Meta.managed_writes`` /
@@ -281,15 +478,19 @@ def declare_managed(
 
     Args:
         model_cls: a matrx-orm Model class.
-        mode: ``"elevate"`` (default — auto-open one-shot Session if
-            none is active) or ``"strict"`` (raise
-            ``ManagedWriteViolation`` outside any Session).
+        mode: ``"elevate"`` (auto-open a one-shot), ``"strict"`` (require
+            any governed Session), or ``"coordinator"`` (require the named
+            owner Session and reject ordinary Session-of-one writes).
+        write_scope: authority required by coordinator mode.
         watched_lifecycle: optional dict matching the
             :class:`WatchedLifecycleConfig` fields (``predicate``,
             ``max_age_secs``, ``transition_to_on_timeout``, etc.).
     """
-    if mode not in ("strict", "elevate"):
-        raise ValueError(f"declare_managed: mode must be 'strict' or 'elevate', got {mode!r}")
+    if mode not in ("strict", "elevate", "coordinator"):
+        raise ValueError(
+            "declare_managed: mode must be 'strict', 'elevate', or "
+            f"'coordinator', got {mode!r}"
+        )
     meta = getattr(model_cls, "_meta", None)
     if meta is None:
         raise ValueError(
@@ -304,6 +505,10 @@ def declare_managed(
         object.__setattr__(meta, "managed_writes", mode)
 
     _apply_wrapping(model_cls, mode)
+    if mode == "coordinator":
+        if not write_scope.strip():
+            raise ValueError("declare_managed coordinator mode requires write_scope")
+        _register_coordinator_table(model_cls, write_scope.strip())
 
     if watched_lifecycle is not None:
         try:
@@ -337,7 +542,7 @@ def _managed_mode(model_cls: type) -> str | None:
         return None
     if declared is True:
         return "elevate"
-    if isinstance(declared, str) and declared in ("strict", "elevate"):
+    if isinstance(declared, str) and declared in ("strict", "elevate", "coordinator"):
         return declared
     logger.warning(
         "managed_writes on %s must be True | 'strict' | 'elevate' — got %r. Treating as 'elevate'.",
@@ -358,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
@@ -381,6 +587,8 @@ def _wrap_classmethod(model_cls: type, method_name: str, original: Any, mode: st
                 session = candidate
                 break
         if session is not None:
+            if active_mode == "coordinator":
+                assert_model_write_allowed(cls, method_name, session=session)
             # Defer to the active Session.
             return await _defer_to_session(
                 session,
@@ -392,7 +600,10 @@ def _wrap_classmethod(model_cls: type, method_name: str, original: Any, mode: st
             )
 
         # No active Session.
-        if mode == "strict":
+        if active_mode == "coordinator":
+            assert_model_write_allowed(cls, method_name)
+
+        if active_mode == "strict":
             banner = _format_violation_banner(cls.__name__, method_name)
             vcprint(banner, color="red")
             logger.error(
@@ -565,6 +776,33 @@ def _format_chokepoint_banner(table: str) -> str:
     )
 
 
+def _format_coordinator_banner(
+    model_name: str,
+    op_kind: str,
+    required_scope: str,
+    actual_scope: str | None,
+) -> str:
+    return (
+        "\n"
+        "████████████████████████████████████████████████████████████████████\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"
+        "  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"
+    )
+
+
 def _format_violation_banner(model_name: str, op_kind: str) -> str:
     return (
         "\n"