matrx-orm 3.1.142__tar.gz → 3.1.144__tar.gz

{matrx_orm-3.1.142 → matrx_orm-3.1.144}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matrx-orm
-Version: 3.1.142
+Version: 3.1.144
 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.142 → matrx_orm-3.1.144}/matrx_orm/FEATURE.md

@@ -11,7 +11,7 @@
 
 `session/fallback.py` owns both failure-capture tables — `ops.system_error`
 (`record_error`) and `ops.system_write_failure` (`record_failures`,
-`drain_spilled_ops`, `create_or_capture`). Both carry `organization_id NOT NULL`.
+`drain_spilled_ops`, `immutable_insert_or_exact_verify`). Both carry `organization_id NOT NULL`.
 
 - **Every capture row is org-stamped by `_capture_org()`.** Three rungs: an org
   the caller passed, else `None` — handing the row to the DB's
@@ -115,6 +115,9 @@
 
 ## Change Log
 
+- 2026-09-12 — Added `immutable_insert_or_exact_verify`: immutable direct writes
+  normalize timestamps/JSON, verify the full row after ambiguous acknowledgements,
+  preserve absent intent under a distinct replay marker, and refuse conflicts.
 - 2026-09-12 — Made organization-assignment retirement output an explicit,
   non-overwriting review proposal; a checked-in resource update is required
   before the next standalone wheel carries a retirement.

{matrx_orm-3.1.142 → matrx_orm-3.1.144}/matrx_orm/__init__.py

@@ -356,6 +356,7 @@ from matrx_orm.session import (
     FlushError,
     FlushReport,
     ManagedWriteViolation,
+    PendingRowOperationError,
     Session,
     SessionClosedError,
     SessionError,
@@ -367,11 +368,15 @@ from matrx_orm.session import (
     allow_direct_coordinator_write,
     coordinator_policy_tables,
     create_or_capture,
+    immutable_insert_or_exact_verify,
+    immutable_row_differences,
     current_session,
+    assert_no_pending_row,
     declare_managed,
     drain_spilled_ops,
     is_in_session,
     WritePreservedError,
+    ImmutableWriteConflictError,
     record_error,
     record_failures,
     register_coordinator_owned_model,
@@ -675,6 +680,7 @@ __all__ = [
     "FlushError",
     "FlushReport",
     "ManagedWriteViolation",
+    "PendingRowOperationError",
     "Session",
     "SessionClosedError",
     "SessionError",
@@ -683,13 +689,17 @@ __all__ = [
     "WatchedLifecycleConfig",
     "WatchedLifecycleRegistry",
     "current_session",
+    "assert_no_pending_row",
     "declare_managed",
     "is_in_session",
     "record_error",
     "record_failures",
     "drain_spilled_ops",
     "create_or_capture",
+    "immutable_insert_or_exact_verify",
+    "immutable_row_differences",
     "WritePreservedError",
+    "ImmutableWriteConflictError",
     "run_lifecycle_sweeper",
     "sweep_lifecycle_once",
     # ── Adapter layer ──────────────────────────────────────────────────────────

{matrx_orm-3.1.142 → matrx_orm-3.1.144}/matrx_orm/core/async_db_manager.py

@@ -157,6 +157,8 @@ READ_TIMEOUT_RETRY_BACKOFF = 0.25  # seconds before the read retry
 # "listConversations: deadlock detected" on /chat, and ops.app_log shows the same
 # class crashing POST /coding-sessions/bridge with a 500. Bounded and LOUD: real
 # contention still surfaces, it just costs two extra attempts first.
+# KNOB MIRROR of platform.feature_knob "orm.write_retry" "contention_retries" — the database
+# manager cannot read the database to configure itself; change the row, then re-mirror here.
 CONTENTION_RETRIES = 2  # extra attempts for a cancelled statement; total = 1 + this
 CONTENTION_BACKOFF = 0.06  # seconds before the first re-issue; doubled each time
 

{matrx_orm-3.1.142 → matrx_orm-3.1.144}/matrx_orm/core/transaction.py

@@ -48,6 +48,10 @@ from matrx_orm.exceptions import DatabaseError
 
 # ContextVar holding the active connection (if any) for the current task tree.
 _active_connection: ContextVar[Any | None] = ContextVar("_active_connection", default=None)
+# The canonical registered database that owns ``_active_connection``.  A raw
+# connection has no portable database identity, so callers that need routing
+# truth must use this ContextVar rather than infer it from connection details.
+_active_database: ContextVar[str | None] = ContextVar("_active_database", default=None)
 # ContextVar tracking savepoint depth (0 = top-level transaction)
 _savepoint_depth: ContextVar[int] = ContextVar("_savepoint_depth", default=0)
 
@@ -57,6 +61,11 @@ def get_active_connection() -> Any | None:
     return _active_connection.get()
 
 
+def get_active_database_name() -> str | None:
+    """Return the canonical database identity of the active transaction."""
+    return _active_database.get()
+
+
 async def advisory_xact_lock(key: str | int, *, connection: Any = None) -> None:
     """Acquire a transaction-scoped Postgres advisory lock
     (``pg_advisory_xact_lock``) keyed on ``key``. Auto-released at
@@ -213,6 +222,7 @@ class TransactionContext:
     def __init__(self, database: str) -> None:
         self.database = database
         self._conn_token: Token[Any | None] | None = None
+        self._database_token: Token[str | None] | None = None
         self._depth_token: Token[int] | None = None
         self._is_savepoint: bool = False
         self._savepoint_name: str = ""
@@ -227,7 +237,16 @@ class TransactionContext:
             self._savepoint_name = f"sp_{uuid.uuid4().hex[:12]}"
             depth = _savepoint_depth.get()
             self._depth_token = _savepoint_depth.set(depth + 1)
-            await existing.execute(f"SAVEPOINT {self._savepoint_name}")
+            try:
+                await existing.execute(f"SAVEPOINT {self._savepoint_name}")
+            except BaseException:
+                # Entry never completed, so __aexit__ will not run.  Restore
+                # only this attempted savepoint's depth; the outer transaction
+                # owns its connection, database identity and eventual cleanup.
+                _savepoint_depth.reset(self._depth_token)
+                self._depth_token = None
+                self._is_savepoint = False
+                raise
         else:
             # Top-level → BEGIN
             self._is_savepoint = False
@@ -239,15 +258,24 @@ class TransactionContext:
             self._raw_conn = conn
             try:
                 await conn.execute("BEGIN")
-            except Exception as e:
+            except BaseException as e:
                 await self._adapter_cm.__aexit__(type(e), e, e.__traceback__)
                 self._raw_conn = None
                 self._adapter_cm = None
+                if not isinstance(e, Exception):
+                    raise
                 raise DatabaseError(
                     message=f"Failed to begin transaction: {e}",
                     details={"database": self.database},
                 ) from e
+            # Keep the connection and its canonical database identity bound as
+            # one top-level transaction fact.  Nested transactions are
+            # savepoints and deliberately retain the outer identity.
+            from matrx_orm.core.config import resolve_database_name
+
+            canonical_database = resolve_database_name(self.database)
             self._conn_token = _active_connection.set(conn)
+            self._database_token = _active_database.set(canonical_database)
             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
@@ -260,8 +288,10 @@ class TransactionContext:
 
             try:
                 await apply_session_context(conn)
-            except Exception as e:
+            except BaseException as e:
                 await self.__aexit__(type(e), e, e.__traceback__)
+                if not isinstance(e, Exception):
+                    raise
                 raise DatabaseError(
                     message=f"Failed to apply the declared session context: {e}",
                     details={"database": self.database},
@@ -290,6 +320,8 @@ class TransactionContext:
             # Top-level: restore ContextVars before touching the connection
             if self._conn_token is not None:
                 _active_connection.reset(self._conn_token)
+            if self._database_token is not None:
+                _active_database.reset(self._database_token)
             if self._depth_token is not None:
                 _savepoint_depth.reset(self._depth_token)
 

{matrx_orm-3.1.142 → matrx_orm-3.1.144}/matrx_orm/operations/update.py

@@ -91,7 +91,7 @@ async def _conflict_actor(
             )
             .order_by("-id")
             .limit(1)
-            .all()
+            .get_committed()
         )
     except Exception as exc:
         vcprint(
@@ -102,10 +102,9 @@ async def _conflict_actor(
             log_level="WARNING",
         )
         return (None, None)
-    if not snapshots:
+    if snapshots is None:
         return (None, None)
-    snapshot = snapshots[0]
-    return (getattr(snapshot, "actor_id", None), getattr(snapshot, "occurred_at", None))
+    return (getattr(snapshots, "actor_id", None), getattr(snapshots, "occurred_at", None))
 
 
 async def _build_conflict(
@@ -149,10 +148,7 @@ async def _raise_stale_write(
     """
     from matrx_orm.exceptions import DoesNotExist
 
-    # Note: inside an open Session the re-read merges PENDING (uncommitted)
-    # writes for this row — a CAS should run on the direct write paths, not
-    # Coordinator-adjacent code (see the contract's session-plane exclusion).
-    current = await QueryBuilder(model_cls).filter(**pk_filter).get_or_none()
+    current = await QueryBuilder(model_cls).filter(**pk_filter).get_committed_or_none()
     if current is None or getattr(current, "deleted_at", None) is not None:
         # Hard-gone or soft-deleted: for conflict classification a soft-deleted
         # row IS gone — reporting it as "changed by someone else, refresh and
@@ -190,12 +186,15 @@ async def guarded_update(
     narrowing filter that stopped matching still classifies as a conflict.
     """
     _require_version_column(model_cls, version_column)
+    from matrx_orm.session import assert_no_pending_row
+
+    pk_filter = {pk: filters[pk] for pk in model_cls._meta.primary_keys}
+    assert_no_pending_row(model_cls, pk_filter)
     data = dict(update_data)
     attempted_fields = list(data)
     data.setdefault(version_column, expected_version + 1)
     result = await update(model_cls, {**filters, version_column: expected_version}, **data)
     if result.rows_affected == 0:
-        pk_filter = {pk: filters[pk] for pk in model_cls._meta.primary_keys}
         await _raise_stale_write(
             model_cls, pk_filter, version_column, expected_version, attempted_fields
         )
@@ -373,14 +372,17 @@ async def guarded_delete(
     delete; deleting it anyway would discard their work unseen).
     """
     _require_version_column(model_cls, version_column)
+    from matrx_orm.session import assert_no_pending_row
+
+    pk_filter = {pk: filters[pk] for pk in model_cls._meta.primary_keys}
+    assert_no_pending_row(model_cls, pk_filter)
     deleted = (
         await QueryBuilder(model_cls)
         .filter(**{**filters, version_column: expected_version})
         .delete()
     )
     if deleted == 0:
-        pk_filter = {pk: filters[pk] for pk in model_cls._meta.primary_keys}
-        current = await QueryBuilder(model_cls).filter(**pk_filter).get_or_none()
+        current = await QueryBuilder(model_cls).filter(**pk_filter).get_committed_or_none()
         # Soft-deleted counts as already gone — idempotent 0, not a conflict.
         if current is not None and getattr(current, "deleted_at", None) is None:
             # A delete contests no individual field (it contests the whole row),

{matrx_orm-3.1.142 → matrx_orm-3.1.144}/matrx_orm/query/FEATURE.md

@@ -70,6 +70,16 @@ want persisted database state call `count(include_pending=False)`. That opt-out
 always uses the database aggregate and never hydrates or serializes every
 matching model merely because a request Coordinator has queued a write.
 
+## Committed-row evidence
+
+`get_committed()` and `get_committed_or_none()` execute the current query through
+the normal executor and current transaction/RLS identity, then hydrate returned
+columns through the canonical model path. They never consult or update
+`StateManager`, and never merge the Session stack. They retain the builder's
+filters, projection, ordering, and ordinary zero/one/many semantics. Use them
+only where database evidence is required, such as stale CAS diagnostics and
+resource authorization; ordinary `get()` remains read-your-own-writes.
+
 ## A rebuilt statement binds only the params it references
 
 `count()`, `update()` and `delete()` rebuild SQL from the WHERE tail that

{matrx_orm-3.1.142 → matrx_orm-3.1.144}/matrx_orm/query/builder.py

@@ -909,6 +909,28 @@ class QueryBuilder(Generic[ModelT]):
         except DoesNotExist:
             return None
 
+    async def get_committed(self) -> ModelT:
+        """Retrieve exactly one database row, ignoring Session and identity-cache state."""
+        filters = self._merge_filters_excludes()
+        try:
+            executor = await self._get_executor_async()
+            results = await executor.all()
+            if not results:
+                raise DoesNotExist(model=self.model, filters=filters)
+            if len(results) > 1:
+                raise MultipleObjectsReturned(model=self.model, count=len(results), filters=filters)
+            return results[0]
+        except ORMException as e:
+            e.enrich(model=self.model, operation="get_committed", filters=filters)
+            raise
+
+    async def get_committed_or_none(self) -> ModelT | None:
+        """Return a committed database row or ``None`` without Session merging."""
+        try:
+            return await self.get_committed()
+        except DoesNotExist:
+            return None
+
     async def update(self, **kwargs: Any) -> UpdateResult:
         """Update matching records.
 

{matrx_orm-3.1.142 → matrx_orm-3.1.144}/matrx_orm/session/README.md

@@ -154,6 +154,21 @@ Complex predicates (operator suffixes, JSON paths, joins) only match
 DB rows — the pending state is assumed safe (the DB still applies the
 predicate on its side).
 
+## Guarded committed operations beside a Session
+
+`assert_no_pending_row(model, primary_key)` is the narrow door used by
+synchronous guarded writes and committed-resource authorization. It refuses
+only an exact schema/table and complete ordered primary-key collision; it
+never flushes, drops, reorders, or otherwise changes a Session. The comparison
+uses canonical database aliases and checks both places a queued operation can
+land: the current transaction's database when one is active, and the owning
+Session's explicit database (or normal transaction default) when it later
+flushes standalone. A raw active connection without the ORM's canonical
+database identity refuses action rather than guessing. A malformed queued
+identity refuses only after its database destination matches; other databases,
+rows and tables remain valid. This is not a blanket Session exclusion or a
+SessionOp CAS.
+
 ## 🚨 Flush stubs are PARTIAL — they never enter the identity cache
 
 `flush._execute_group` turns each queued UPDATE into a lightweight

{matrx_orm-3.1.142 → matrx_orm-3.1.144}/matrx_orm/session/__init__.py

@@ -53,10 +53,14 @@ from matrx_orm.session.errors import (
     CoordinatorWriteViolation,
     FlushError,
     ManagedWriteViolation,
+    PendingRowOperationError,
     SessionClosedError,
     SessionError,
 )
 from matrx_orm.session.fallback import (
+    ImmutableWriteConflictError,
+    immutable_insert_or_exact_verify,
+    immutable_row_differences,
     WritePreservedError,
     create_or_capture,
     drain_spilled_ops,
@@ -92,6 +96,7 @@ from matrx_orm.session.reads import (
     merge_pending_with_db_one,
 )
 from matrx_orm.session.session import (
+    assert_no_pending_row,
     FlushReport,
     Session,
     SessionPhase,
@@ -108,6 +113,7 @@ __all__ = [
     "FlushError",
     "FlushReport",
     "ManagedWriteViolation",
+    "PendingRowOperationError",
     "OpType",
     "SWEEP_INTERVAL_SECS_DEFAULT",
     "SWEEP_LIMIT_DEFAULT",
@@ -121,6 +127,7 @@ __all__ = [
     "coalesce_ops",
     "config_from_meta",
     "current_session",
+    "assert_no_pending_row",
     "COORDINATOR_BYPASS_ACKNOWLEDGEMENT",
     "allow_direct_coordinator_write",
     "coordinator_policy_tables",
@@ -139,6 +146,9 @@ __all__ = [
     "drain_spilled_ops",
     "create_or_capture",
     "WritePreservedError",
+    "ImmutableWriteConflictError",
+    "immutable_insert_or_exact_verify",
+    "immutable_row_differences",
     "merge_pending_with_db_one",
     "run_sweeper",
     "session_stack",

{matrx_orm-3.1.142 → matrx_orm-3.1.144}/matrx_orm/session/errors.py

@@ -11,6 +11,17 @@ class SessionError(Exception):
     """Base class for all Session exceptions."""
 
 
+class PendingRowOperationError(SessionError):
+    """An authoritative operation targets a row with queued Session work."""
+
+    def __init__(self, table: str) -> None:
+        super().__init__(
+            f"{table} has a pending Session operation for this exact row. "
+            "Finish the current operation before authorizing or mutating this resource."
+        )
+        self.table = table
+
+
 class LifecycleWatchdogAlarm(SessionError):
     """A watched lifecycle crossed its SLA and requires operator attention."""
 

{matrx_orm-3.1.142 → matrx_orm-3.1.144}/matrx_orm/session/fallback.py

@@ -17,6 +17,7 @@ from __future__ import annotations
 import json
 import logging
 import os
+import re
 import tempfile
 import traceback as _tb
 import uuid as _uuid
@@ -116,6 +117,7 @@ DISK_SPILL_RECOVERED_MARKER = "DiskSpillRecovered"
 # matrx-ai's replay loop adds this to its RECOVERABLE_RETRY_ERRORS set — keep
 # the string in lockstep.
 DIRECT_WRITE_PRESERVED_MARKER = "DirectWritePreserved"
+IMMUTABLE_WRITE_PRESERVED_MARKER = "ImmutableWritePreserved"
 # Resolved-writable spill dir, cached after first success so we don't re-probe
 # the cascade on every failure. None until first resolution.
 _spill_dir_cache: Path | None = None
@@ -535,10 +537,13 @@ async def record_failures(
             spilled=spilled,
             total=len(failed_rows),
         )
-    # A spilled op is still preserved (drain_spilled_ops re-lands it), so it
-    # counts as captured. Only ops that reached neither the table nor the disk
-    # are lost, and those already screamed above.
-    return [op.op_id for op in ops]
+    # A spill is durable only when every failed row reached disk.  Never return
+    # a handle for the DB+disk-loss case: callers use the receipt to tell a
+    # human whether the final utterance is actually recoverable.
+    if spilled == len(failed_rows):
+        return [op.op_id for op in ops]
+    failed_ids = {str(row["op_id"]) for row in failed_rows}
+    return [op.op_id for op in ops if op.op_id not in failed_ids]
 
 
 async def _bulk_insert_failures(
@@ -901,6 +906,67 @@ def _scream_to_stdout(
 # ── Keep-the-work tier: DIRECT writes that must never lose their payload ─────
 
 
+class ImmutableWriteConflictError(RuntimeError):
+    """An immutable row id exists, but its stored value differs from the intent."""
+
+
+def _canonical_immutable_value(value: Any, *, parse_iso_timestamp: bool = False) -> Any:
+    """Normalize JSON and timestamps before comparing immutable write intent."""
+    if isinstance(value, datetime):
+        if value.tzinfo is None:
+            value = value.replace(tzinfo=UTC)
+        return value.astimezone(UTC).isoformat().replace("+00:00", "Z")
+    if isinstance(value, _uuid.UUID):
+        return str(value)
+    if parse_iso_timestamp and isinstance(value, str) and re.fullmatch(
+        r"\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})", value
+    ):
+        try:
+            parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+        except ValueError:
+            pass
+        else:
+            return _canonical_immutable_value(parsed)
+    if hasattr(value, "model_dump"):
+        value = value.model_dump()
+    if isinstance(value, dict):
+        return {str(key): _canonical_immutable_value(item) for key, item in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_canonical_immutable_value(item) for item in value]
+    return value
+
+
+def _row_value(row: Any, field: str) -> Any:
+    if isinstance(row, dict):
+        return row.get(field)
+    return getattr(row, field, None)
+
+
+async def _load_immutable_row(model_cls: type, pk_field: str, pk_value: Any) -> Any | None:
+    rows = await model_cls.filter(**{pk_field: pk_value}).limit(1).all()
+    return rows[0] if rows else None
+
+
+def _immutable_differences(row: Any, payload: dict[str, Any]) -> dict[str, dict[str, Any]]:
+    differences: dict[str, dict[str, Any]] = {}
+    for field, expected in payload.items():
+        actual = _row_value(row, field)
+        # ISO parsing is field-aware: transcript content may legitimately be a
+        # date-looking literal, while *_at columns are actual instants.
+        parse_iso_timestamp = field.endswith("_at") or field.endswith("_timestamp")
+        if _canonical_immutable_value(actual, parse_iso_timestamp=parse_iso_timestamp) != _canonical_immutable_value(expected, parse_iso_timestamp=parse_iso_timestamp):
+            differences[field] = {
+                "expected": _canonical_immutable_value(expected, parse_iso_timestamp=parse_iso_timestamp),
+                "actual": _canonical_immutable_value(actual, parse_iso_timestamp=parse_iso_timestamp),
+            }
+    return differences
+
+
+def immutable_row_differences(row: Any, payload: dict[str, Any]) -> dict[str, dict[str, Any]]:
+    """Public exact-comparison contract for immutable insert/replay consumers."""
+    return _immutable_differences(row, payload)
+
+
 class WritePreservedError(RuntimeError):
     """A direct write failed, but its payload was PRESERVED for replay.
 
@@ -1004,11 +1070,9 @@ async def create_or_capture(
         row[pk_field] = str(_uuid.uuid4())
     pk_value = row[pk_field]
     table = f"{getattr(model_cls._meta, 'schema', 'public')}.{model_cls._meta.table_name}"
-
     try:
         return await model_cls.create_item(**row)
     except Exception as exc:
-        # (3) The attempt failing is NOT proof the row is missing.
         try:
             landed = await model_cls.filter(**{pk_field: pk_value}).limit(1).all()
         except Exception:
@@ -1018,11 +1082,79 @@ async def create_or_capture(
                 f"[matrx_orm.create_or_capture] {table} {pk_value} raised "
                 f"{type(exc).__name__} but the row IS committed — the write "
                 f"succeeded and the error was the acknowledgement, not the write. "
-                f"Investigate: this means a client gave up on a landed write.",
+                "Investigate: this means a client gave up on a landed write.",
                 color="yellow",
             )
             logger.warning("create_or_capture_landed_despite_error", exc_info=exc)
             return landed[0]
+        op = make_insert(model_cls, row, pk_value=pk_value)
+        op_ids = await record_failures(
+            [op], exc, request_id=request_id, user_id=user_id,
+            conversation_id=conversation_id,
+            organization_id=organization_id or payload.get("organization_id"), database=database,
+            error_prefix=DIRECT_WRITE_PRESERVED_MARKER,
+        )
+        op_id = op_ids[0] if op_ids else None
+        vcprint(
+            f"[matrx_orm.create_or_capture] {table} {pk_value} FAILED "
+            f"({type(exc).__name__}) — payload preserved as system_write_failure "
+            f"op {op_id}; the auto-replay loop will re-apply it.",
+            color="yellow",
+        )
+        raise WritePreservedError(
+            f"{table} write failed ({type(exc).__name__}: {exc}); the payload was preserved for automatic replay",
+            table=table, pk_value=pk_value, op_id=op_id, captured=op_id is not None, cause=exc,
+        ) from exc
+
+
+async def immutable_insert_or_exact_verify(
+    model_cls: type,
+    payload: dict[str, Any],
+    *,
+    pk_field: str = "id",
+    request_id: str | None = None,
+    user_id: str | None = None,
+    conversation_id: str | None = None,
+    organization_id: str | None = None,
+    database: str | None = None,
+) -> Any:
+    """Insert an immutable row, or verify the complete intended row exactly.
+
+    A failed acknowledgement is ambiguous: a fresh read either proves the exact
+    row landed, proves a conflict, or preserves the complete insert for replay.
+    """
+    from matrx_orm.session.op import make_insert
+
+    row = dict(payload)
+    if not row.get(pk_field):
+        row[pk_field] = str(_uuid.uuid4())
+    pk_value = row[pk_field]
+    table = f"{getattr(model_cls._meta, 'schema', 'public')}.{model_cls._meta.table_name}"
+
+    try:
+        # Deliberately no Session: this primitive owns one direct write boundary.
+        return await model_cls.create_item(**row)
+    except Exception as exc:
+        # (3) The attempt failing is NOT proof the row is missing.
+        try:
+            landed = await _load_immutable_row(model_cls, pk_field, pk_value)
+        except Exception:
+            landed = None
+        if landed:
+            differences = _immutable_differences(landed, row)
+            if differences:
+                raise ImmutableWriteConflictError(
+                    f"immutable write conflict for {table} {pk_value}: {sorted(differences)}"
+                ) from exc
+            vcprint(
+                f"[matrx_orm.create_or_capture] {table} {pk_value} raised "
+                f"{type(exc).__name__} but the row IS committed — the write "
+                f"succeeded and the error was the acknowledgement, not the write. "
+                f"Investigate: this means a client gave up on a landed write.",
+                color="yellow",
+            )
+            logger.warning("create_or_capture_landed_despite_error", exc_info=exc)
+            return landed
 
         # (4) Preserve the payload where the replay loop will find it.
         op = make_insert(model_cls, row, pk_value=pk_value)
@@ -1034,7 +1166,7 @@ async def create_or_capture(
             conversation_id=conversation_id,
             organization_id=organization_id or payload.get("organization_id"),
             database=database,
-            error_prefix=DIRECT_WRITE_PRESERVED_MARKER,
+            error_prefix=IMMUTABLE_WRITE_PRESERVED_MARKER,
         )
         op_id = op_ids[0] if op_ids else None
         vcprint(