matrx-orm 3.1.244__tar.gz → 3.1.246__tar.gz

{matrx_orm-3.1.244 → matrx_orm-3.1.246}/PKG-INFO

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

{matrx_orm-3.1.244 → matrx_orm-3.1.246}/matrx_orm/associations.py

@@ -71,6 +71,8 @@ from collections.abc import Awaitable, Callable
 
 from matrx_utils import vcprint
 
+from matrx_orm.core.transaction import outside_transaction
+
 if TYPE_CHECKING:
     from matrx_orm.core.base import Model
 
@@ -209,7 +211,10 @@ class EntityRegistry:
             return self._cache[token]
         model: type[Model] | None = None
         if self._etype_model is not None:
-            row = await self._etype_model.get_or_none(**{self._token_field: token})
+            # Vocabulary, never person data: read off the caller's session, or a person's RLS
+            # hides the row and the miss below is cached for every later caller.
+            etype_model = self._etype_model
+            row = await outside_transaction(lambda: etype_model.get_or_none(**{self._token_field: token}))
             active = self._active_field is None or getattr(row, self._active_field, True)
             if row is not None and active:
                 schema = getattr(row, self._schema_field, None)

{matrx_orm-3.1.244 → matrx_orm-3.1.246}/matrx_orm/core/transaction.py

@@ -36,16 +36,19 @@ reuses the connection when present — this behavior is unchanged.
 from __future__ import annotations
 
 import asyncio
+import contextvars
 import os
 import re
 import uuid
-from collections.abc import AsyncIterator
+from collections.abc import AsyncIterator, Awaitable, Callable
 from contextlib import asynccontextmanager
 from contextvars import ContextVar, Token
-from typing import Any
+from typing import Any, TypeVar
 
 from matrx_orm.exceptions import DatabaseError
 
+_T = TypeVar("_T")
+
 # 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
@@ -69,6 +72,27 @@ def in_person_scoped_session() -> bool:
 _savepoint_depth: ContextVar[int] = ContextVar("_savepoint_depth", default=0)
 
 
+async def outside_transaction(fn: Callable[[], Awaitable[_T]]) -> _T:
+    """Await ``fn()`` on the process's own connection, outside the caller's transaction.
+
+    For process-wide VOCABULARY reads (the entity-type registry) whose answer must not
+    depend on who is acting: inside ``rls_session`` a person's RLS may hide the row, and a
+    cached answer outlives the person. The read runs as its own task with every transaction
+    ContextVar at its default, so it never touches (or ends) the caller's pinned connection,
+    and the caller's session is unchanged when it returns. Never use it for person data.
+    """
+    ctx = contextvars.copy_context()
+
+    def _clear() -> None:
+        _active_connection.set(None)
+        _active_database.set(None)
+        _person_scoped.set(False)
+        _savepoint_depth.set(0)
+
+    ctx.run(_clear)
+    return await asyncio.get_running_loop().create_task(fn(), context=ctx)
+
+
 def get_active_connection() -> Any | None:
     """Return the connection bound to the current transaction context, or None."""
     return _active_connection.get()

{matrx_orm-3.1.244 → matrx_orm-3.1.246}/matrx_orm/entity.py

@@ -40,7 +40,8 @@ if TYPE_CHECKING:
 # The canonical version log + restore function. Identical in every Matrx database
 # (verified live on both the main and CMS projects):
 #   history.row_versions(entity_type, row_id, version, operation, row_data, actor_id, occurred_at)
-#   public.version_restore(token text, id uuid, version int) -> int  (the new version)
+#   public.version_restore(token text, id uuid, version int) -> int  (the new version) —
+#   a thin SQL wrapper over platform.version_restore; both exist live, the ORM calls the public door
 VERSION_LOG_SCHEMA = "history"
 VERSION_LOG_MODEL = "RowVersions"
 VERSION_RESTORE_SCHEMA = "public"

{matrx_orm-3.1.244 → matrx_orm-3.1.246}/matrx_orm/platform_access.py

@@ -379,7 +379,7 @@ async def platform_edge_requirement(
 
             rows = await call_function(
                 host_db_config_name(who="matrx-orm edge policy"),
-                "public",
+                "platform",
                 "assoc_container_side",
                 key[0],
                 key[1],

{matrx_orm-3.1.244 → matrx_orm-3.1.246}/matrx_orm/secrets_battery/items.py

@@ -1745,7 +1745,9 @@ async def resolve_field_by_id(field_id: str) -> str:
             f"credential field {field_id} exists but does not decrypt with the "
             "configured CREDENTIALS_ENCRYPTION_KEY (key drift)"
         ) from exc
-    await UserSecret.update_where({"id": field_id}, last_used_at=datetime.now(UTC))
+    from .use_stamp import stamp_last_used
+
+    await stamp_last_used(UserSecret, {"id": field_id})
     return value
 
 

{matrx_orm-3.1.244 → matrx_orm-3.1.246}/matrx_orm/secrets_battery/org_service.py

@@ -753,11 +753,9 @@ async def resolve_org_secrets(
         # the same row locks in opposite orders and Postgres kills one as a
         # deadlock victim (40P01) — four ``ai.agent.start`` invocations over 185
         # rows of one org killed a live workflow run on 2026-09-12.
-        await UserSecret.update_where(
-            {"id__in": sorted(used_ids)},
-            lock_rows_in_pk_order=True,
-            last_used_at=datetime.now(UTC),
-        )
+        from .use_stamp import stamp_last_used
+
+        await stamp_last_used(UserSecret, {"id__in": sorted(used_ids)}, lock_rows_in_pk_order=True)
     return resolved
 
 

{matrx_orm-3.1.244 → matrx_orm-3.1.246}/matrx_orm/secrets_battery/service.py

@@ -21,6 +21,7 @@ from typing import Any
 
 from .crypto import decrypt_value, encrypt_value, mask_value
 from .model import CredentialItem, UserSecret, UserSecretGrant
+from .use_stamp import stamp_last_used
 
 logger = logging.getLogger(__name__)
 
@@ -243,7 +244,7 @@ async def get_user_secret(
             )
             plaintext = None
     if touch_last_used:
-        await UserSecret.update_where({"id": row["id"]}, last_used_at=datetime.now(UTC))
+        await stamp_last_used(UserSecret, {"id": row["id"]})
     return _row_to_dataclass(row, decrypted_value=plaintext)
 
 
@@ -312,7 +313,7 @@ async def get_org_secret(
             )
             plaintext = None
     if touch_last_used:
-        await UserSecret.update_where({"id": row["id"]}, last_used_at=datetime.now(UTC))
+        await stamp_last_used(UserSecret, {"id": row["id"]})
     return _row_to_dataclass(row, decrypted_value=plaintext)
 
 

matrx_orm-3.1.246/matrx_orm/secrets_battery/use_stamp.py

@@ -0,0 +1,27 @@
+"""``last_used_at`` stamps are telemetry: a failed stamp never fails the read that used the secret."""
+
+from __future__ import annotations
+
+import logging
+from datetime import UTC, datetime
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+async def stamp_last_used(model: Any, filters: dict[str, Any], **options: Any) -> bool:
+    """Stamp ``last_used_at`` on the rows ``filters`` names; announce and drop any failure.
+
+    A timeout or lock collision on this bookkeeping UPDATE once ended a whole Notion import
+    (2026-10-22). The caller already holds the value it read, so losing the stamp loses
+    nothing a person needs. Returns whether the stamp landed.
+    """
+    try:
+        await model.update_where(filters, last_used_at=datetime.now(UTC), **options)
+        return True
+    except Exception as exc:
+        logger.warning(
+            "[secrets] last_used_at stamp on %s skipped (%s: %s); the read continues",
+            getattr(model, "__name__", model), type(exc).__name__, exc,
+        )
+        return False

{matrx_orm-3.1.244 → matrx_orm-3.1.246}/matrx_orm/session/fallback.py

@@ -269,6 +269,16 @@ def _op_user_id(op: SessionOp, safe_user_id: str | None) -> str | None:
     return None
 
 
+#: The refusal text of the database's confidential-content guard (chat.refuse_sealed_content).
+CONFIDENTIAL_REFUSAL_MARK = "may not be stored on the server (chat.confidential)"
+_CONFIDENTIAL_KEPT_KEYS = ("id", "conversation_id", "user_request_id", "message_id", "role", "position")
+
+
+def _confidential_payload(payload: Any) -> Any:
+    kept = {k: payload.get(k) for k in _CONFIDENTIAL_KEPT_KEYS if isinstance(payload, dict) and k in payload}
+    return _serialize_payload({**kept, "redacted": "confidential conversation: content refused, not kept"})
+
+
 def _op_failure_row(
     op: SessionOp,
     *,
@@ -285,6 +295,12 @@ def _op_failure_row(
     values. Used by BOTH the DB insert and the disk spill, so a spilled file is
     byte-identical in shape to a table row (drain re-inserts it verbatim)."""
     row_user_id = _op_user_id(op, safe_user_id)
+    payload = _serialize_payload(op.payload)
+    if CONFIDENTIAL_REFUSAL_MARK in (error_text or ""):
+        # The database refused this row because its conversation is CONFIDENTIAL
+        # (trigger chat.refuse_sealed_content): its content must never land on our
+        # server, so the failure record keeps the row's identity, never its values.
+        payload = _confidential_payload(op.payload)
     return {
         "op_id": op.op_id,
         "request_id": request_id or session_id,
@@ -294,7 +310,7 @@ def _op_failure_row(
         "table_target": op.table,
         "op_type": op.op_type,
         "primary_key": _serialize_primary_key(op.pk_field, op.pk_value),
-        "payload": _serialize_payload(op.payload),
+        "payload": payload,
         "depends_on": json.dumps([]),  # FK-inferred deps aren't tracked on the op
         "error_text": error_text,
         "traceback": tb_text,
@@ -677,6 +693,7 @@ async def record_error(
     payload: Any | None = None,
     context: dict[str, Any] | None = None,
     database: str | None = None,
+    group_open: bool = False,
 ) -> None:
     """Universal failure capture for NON-write errors → ``system_error``.
 
@@ -721,6 +738,16 @@ async def record_error(
             indistinguishable from a Codex one.
         payload: request args/body to capture (jsonb). Serialized defensively.
         context: free-form context (debug_label, task_name, partial cost, …).
+        group_open: ONE OPEN ROW PER SIGNATURE (error-capture rule "a count is a
+            number on an existing row, never a new row"). When True, a capture whose
+            ``(kind, route, error_type)`` already has an UNRESOLVED row bumps that row's
+            ``context.occurrences`` (exact, atomic, across every process and deploy) and
+            ``context.last_seen_at`` instead of filing a new row; with none open it files
+            the row with ``occurrences=1``. Resolving the row zeroes the count — the next
+            occurrence reopens as one new row. For announcements that are a COUNT of a
+            known condition per site (legacy lanes, runtime bypasses), never for a crash
+            whose every instance carries its own inputs. The storm budget does not apply
+            (the grouping is the budget).
     """
     # Both attribution halves ride the carried request context; a capture site
     # that declared neither still files a fully categorized row.
@@ -739,7 +766,7 @@ async def record_error(
     else:
         tb_text = "".join(_tb.format_exception(type(exc), exc, exc.__traceback__))
 
-    admitted, folded = _storm_admit(kind, resolved_error_type, route)
+    admitted, folded = (True, 0) if group_open else _storm_admit(kind, resolved_error_type, route)
     if not admitted:
         # Counted, never silent: the next admitted row for this signature
         # carries the total. ONE stdout line per window (the first fold) — a line per
@@ -787,12 +814,14 @@ async def record_error(
                 "route": route,
                 "context": context,
                 "payload": payload,
+                **({"group_open": True} if group_open else {}),
             }
         )
         return
 
     try:
         await _insert_error(
+            **({"group_open": True} if group_open else {}),
             kind=kind,
             request_id=request_id,
             user_id=user_id,
@@ -896,6 +925,7 @@ async def _insert_error(
     payload: Any | None,
     context: dict[str, Any] | None,
     database: str | None,
+    group_open: bool = False,
 ) -> None:
     from matrx_orm.adapters import AdapterRegistry
     from matrx_orm.core.config import get_all_database_project_names
@@ -931,6 +961,13 @@ async def _insert_error(
             # capture fast instead of parking a pool slot behind it.
             await conn.execute(f"SET LOCAL lock_timeout = '{CAPTURE_LOCK_TIMEOUT_MS}ms'")
             await conn.execute(f"SET LOCAL statement_timeout = '{CAPTURE_STATEMENT_TIMEOUT_MS}ms'")
+            if group_open:
+                if await _bump_open_error(conn, kind=kind, route=route, error_type=error_type):
+                    return
+                context_json = json.dumps(
+                    {**(context or {}), "occurrences": 1, "grouped": GROUPED_NOTE},
+                    default=_json_default,
+                )
             await _execute_error_insert(
                 conn,
                 kind=kind,
@@ -951,6 +988,39 @@ async def _insert_error(
 
 
 
+#: Stamped on a grouped row (``record_error(group_open=True)``) so a reader knows what the count means.
+GROUPED_NOTE = (
+    "one open row per kind+route+error_type; context.occurrences counts every capture since the row "
+    "was last resolved (all processes), context.last_seen_at the latest"
+)
+
+# The bump is ONE statement under a transaction-scoped advisory lock on the signature, so two
+# processes seeing the same site at once neither lose a count nor both file a row.
+_GROUP_LOCK_SQL = "SELECT pg_advisory_xact_lock(hashtextextended($1::text, 0))"
+_GROUP_BUMP_SQL = """
+UPDATE ops.system_error
+   SET context = coalesce(context, '{}'::jsonb) || jsonb_build_object(
+         'occurrences', coalesce((context->>'occurrences')::bigint, 1) + 1,
+         'last_seen_at', now())
+ WHERE id = (
+       SELECT id FROM ops.system_error
+        WHERE kind = $1::text
+          AND route IS NOT DISTINCT FROM $2::text
+          AND error_type IS NOT DISTINCT FROM $3::text
+          AND resolved_at IS NULL
+        ORDER BY occurred_at
+        LIMIT 1)
+RETURNING id
+"""
+
+
+async def _bump_open_error(conn: Any, *, kind: str, route: str | None, error_type: str | None) -> bool:
+    """Count this capture on the signature's open row; False when none is open (file one)."""
+    await conn.fetch(_GROUP_LOCK_SQL, f"system_error:{kind}|{route or ''}|{error_type or ''}")
+    rows = await conn.fetch(_GROUP_BUMP_SQL, kind, route, error_type)
+    return bool(rows)
+
+
 _LIVE_INSERT_ERROR = _insert_error
 
 async def _execute_error_insert(

{matrx_orm-3.1.244 → matrx_orm-3.1.246}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.244"
+version = "3.1.246"
 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.83",
+    "matrx-utils>=2.0.84",
     "pyyaml>=6.0.3",
     "python-dotenv>=1.0",
     "cryptography>=43.0",

{matrx_orm-3.1.244 → matrx_orm-3.1.246}/tests/level1/test_call_function.py

@@ -159,11 +159,11 @@ class TestArrayArgBinding:
             lambda database: _FakeConnCtx(conn),
         )
         result = await call_function(
-            "db", "public", "resolve_full_context", "user-id", ArrayArg(["scope-1", "scope-2"])
+            "db", "context", "resolve_full_context", "user-id", ArrayArg(["scope-1", "scope-2"])
         )
         assert result == "ok"
         conn.fetchval.assert_awaited_once_with(
-            'SELECT "public"."resolve_full_context"($1, $2)',
+            'SELECT "context"."resolve_full_context"($1, $2)',
             "user-id",
             ["scope-1", "scope-2"], timeout=None
         )
@@ -174,9 +174,9 @@ class TestArrayArgBinding:
             "matrx_orm.core.db_function.AsyncDatabaseManager.get_connection",
             lambda database: _FakeConnCtx(conn),
         )
-        await call_function("db", "public", "resolve_full_context", "user-id", ArrayArg(None))
+        await call_function("db", "context", "resolve_full_context", "user-id", ArrayArg(None))
         conn.fetchval.assert_awaited_once_with(
-            'SELECT "public"."resolve_full_context"($1, $2)', "user-id", None, timeout=None
+            'SELECT "context"."resolve_full_context"($1, $2)', "user-id", None, timeout=None
         )
 
     async def test_array_arg_distinct_from_plain_list_jsonb_cast(self, monkeypatch) -> None:

{matrx_orm-3.1.244 → matrx_orm-3.1.246}/tests/level1/test_db_function_field.py

@@ -110,11 +110,11 @@ class TestCallFunctionRows:
         )
 
         result = await call_function(
-            "main", "public", "dict_list_entries_for", "user-1", "user", None, mode="rows"
+            "main", "dictionary", "dict_list_entries_for", "user-1", "user", None, mode="rows"
         )
         assert result == [{"id": "1", "term": "foo"}, {"id": "2", "term": "bar"}]
         assert conn.calls[0]["sql"] == (
-            'SELECT * FROM "public"."dict_list_entries_for"($1, $2, $3)'
+            'SELECT * FROM "dictionary"."dict_list_entries_for"($1, $2, $3)'
         )
         assert conn.calls[0]["args"] == ("user-1", "user", None)
 

{matrx_orm-3.1.244 → matrx_orm-3.1.246}/tests/level1/test_deadlock_retry.py

@@ -328,7 +328,7 @@ async def test_call_function_retries_a_rolled_back_rpc(monkeypatch):
     monkeypatch.setattr("matrx_orm.core.write_retry.resolve_policy", _fake_policy)
     clear_policy_cache()
 
-    await db_function.call_function("test", "public", "library_revoke", "g1", mode="none")
+    await db_function.call_function("test", "rag", "library_revoke", "g1", mode="none")
 
     assert calls[0] == 2, (
         f"A deadlocked RPC must be retried on its own fresh connection. Got {calls[0]} attempts."
@@ -352,7 +352,7 @@ async def test_call_function_inside_a_transaction_does_not_retry(monkeypatch):
     clear_policy_cache()
 
     with pytest.raises(LockContentionError) as caught:
-        await db_function.call_function("test", "public", "library_revoke", "g1", mode="none")
+        await db_function.call_function("test", "rag", "library_revoke", "g1", mode="none")
     assert calls[0] == 1, f"expected exactly one attempt inside a transaction, got {calls[0]}"
     assert caught.value.details["in_transaction"] is True
 

matrx_orm-3.1.246/tests/level1/test_registry_reads_outside_the_person_session.py

@@ -0,0 +1,49 @@
+"""Level 1: a noun lookup never depends on who is acting.
+
+``platform.entity_types`` is vocabulary, and a non-admin person's RLS hides it (a restrictive
+``platform_admin_only`` policy). ``EntityRegistry.resolve`` read it on whatever connection the
+caller held, so inside ``acting_as_user`` it found no row, answered ``None`` and CACHED that
+miss for the life of the process: every later ``sources_to(..., "fc_card")`` raised
+``UnknownEntityType('fc_card')`` — the Education Guide lost a study-media record's source (a
+flashcard deck) on 2026-10-22. The registry now reads the noun outside the caller's session.
+"""
+
+import pytest
+
+from matrx_orm.associations import EntityRegistry
+from matrx_orm.core import transaction as tx
+
+
+class _Card:
+    pass
+
+
+class _HiddenUnderRls:
+    """An entity_types stand-in that answers only off the person's session, like the live table."""
+
+    seen: list[tuple[bool, object]] = []
+
+    @classmethod
+    async def get_or_none(cls, **filters):
+        cls.seen.append((tx.in_person_scoped_session(), tx.get_active_connection()))
+        if tx.in_person_scoped_session() or tx.get_active_connection() is not None:
+            return None
+        row = type("Row", (), {})()
+        row.schema_name, row.table_name, row.is_active = "education", "fc_card", True
+        return row if filters.get("token") == "fc_card" else None
+
+
+@pytest.mark.asyncio
+async def test_a_person_session_never_hides_a_registered_noun() -> None:
+    reg = EntityRegistry(entity_type_model=_HiddenUnderRls,
+                         model_lookup=lambda s, t: _Card if (s, t) == ("education", "fc_card") else None)
+    marks = (tx._active_connection.set(object()), tx._person_scoped.set(True))
+    try:
+        assert await reg.resolve("fc_card") is _Card
+        assert await reg.require("fc_card") is _Card
+    finally:
+        tx._person_scoped.reset(marks[1])
+        tx._active_connection.reset(marks[0])
+    assert _HiddenUnderRls.seen and all(scoped is False and conn is None for scoped, conn in _HiddenUnderRls.seen)
+    # the caller's session is untouched by the lookup
+    assert tx.in_person_scoped_session() is False and tx.get_active_connection() is None

matrx_orm-3.1.246/tests/session/test_record_error_group_open.py

@@ -0,0 +1,152 @@
+"""ONE OPEN ROW PER SIGNATURE: ``record_error(group_open=True)`` counts on the existing row.
+
+SUT: :func:`matrx_orm.session.fallback.record_error` with ``group_open=True`` (and ``_insert_error``).
+
+2026-10-22: the mandate runner's legacy-lane announcements were "announced once per site" with a
+per-PROCESS set, so every process and every 30-minute deploy re-filed the same site: 413
+``mandate_offer_eager_legacy`` rows for ~60 sites, 56 ``mandate_bypass_runtime`` rows for 2 lines, in
+12 hours. The error-capture rule: "a count is a number on an existing row, never a new row".
+
+Breaks these tests name: a second capture of an open signature filing a new row, the count not being
+exact across "processes" (fresh storm state, fresh per-process sets), a resolved row swallowing a
+recurrence instead of reopening as one, or distinct sites collapsing into one row.
+"""
+
+from __future__ import annotations
+
+import json
+import uuid
+from typing import Any
+
+import pytest
+from matrx_orm.session import fallback
+
+
+class _Table:
+    """``ops.system_error`` as far as the grouped door touches it."""
+
+    def __init__(self) -> None:
+        self.rows: list[dict[str, Any]] = []
+
+    def open_row(self, kind: str, route: str | None, error_type: str | None) -> dict[str, Any] | None:
+        for row in self.rows:
+            if (row["kind"], row["route"], row["error_type"]) == (kind, route, error_type) and row["resolved_at"] is None:
+                return row
+        return None
+
+
+class _Txn:
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *exc):
+        return False
+
+
+class _Conn:
+    def __init__(self, table: _Table) -> None:
+        self.table = table
+
+    def transaction(self):
+        return _Txn()
+
+    async def execute(self, sql: str, *args: Any) -> None:
+        if "ops.record_system_error" in sql:
+            self.table.rows.append(
+                {
+                    "id": str(uuid.uuid4()),
+                    "kind": args[0],
+                    "route": args[8],
+                    "error_type": args[9],
+                    "context": json.loads(args[13]) if args[13] else {},
+                    "resolved_at": None,
+                }
+            )
+
+    async def fetch(self, sql: str, *args: Any) -> list[dict[str, Any]]:
+        if "UPDATE ops.system_error" in sql:
+            row = self.table.open_row(*args)
+            if row is None:
+                return []
+            row["context"]["occurrences"] = int(row["context"].get("occurrences", 1)) + 1
+            row["context"]["last_seen_at"] = "now"
+            return [{"id": row["id"]}]
+        return []
+
+
+class _Adapter:
+    def __init__(self, table: _Table) -> None:
+        self.table = table
+
+    def get_connection(self, timeout: float = 10.0):
+        conn = _Conn(self.table)
+
+        class _Ctx:
+            async def __aenter__(self_inner):
+                return conn
+
+            async def __aexit__(self_inner, *exc):
+                return False
+
+        return _Ctx()
+
+
+@pytest.fixture
+def table(monkeypatch) -> _Table:
+    table = _Table()
+    monkeypatch.setattr("matrx_orm.adapters.AdapterRegistry.get", lambda name: _Adapter(table))
+
+    async def live(**kwargs: Any) -> None:  # the real insert path, against the fake table
+        await fallback._LIVE_INSERT_ERROR(**kwargs)
+
+    monkeypatch.setattr(fallback, "_insert_error", live)
+    fallback.reset_capture_storm_state()
+    yield table
+    fallback.reset_capture_storm_state()
+
+
+async def _sighting(site: str, kind: str = "mandate_offer_eager_legacy") -> None:
+    fallback.reset_capture_storm_state()  # every sighting may be a different process / deploy
+    await fallback.record_error(
+        RuntimeError(f"legacy at {site}"), kind=kind, route=site, context={"site": site},
+        database="t", group_open=True,
+    )
+
+
+@pytest.mark.asyncio
+async def test_one_open_row_per_site_with_an_exact_count(table: _Table) -> None:
+    for _ in range(7):
+        await _sighting("seo.job @ aidream/services/seo/run.py:12")
+    assert len(table.rows) == 1, "seven sightings of one site are ONE open row"
+    assert table.rows[0]["context"]["occurrences"] == 7, "and the row counts every one of them"
+    assert table.rows[0]["context"]["site"] == "seo.job @ aidream/services/seo/run.py:12"
+
+
+@pytest.mark.asyncio
+async def test_distinct_sites_and_kinds_stay_distinct_rows(table: _Table) -> None:
+    await _sighting("a.job @ x.py:1")
+    await _sighting("a.job @ x.py:2")
+    await _sighting("a.job @ x.py:1", kind="mandate_by_name_legacy")
+    await _sighting("a.job @ x.py:1")
+    assert len(table.rows) == 3, "never merge genuinely distinct signatures"
+    counts = sorted(r["context"]["occurrences"] for r in table.rows)
+    assert counts == [1, 1, 2]
+
+
+@pytest.mark.asyncio
+async def test_a_recurrence_after_resolve_reopens_as_one_new_row(table: _Table) -> None:
+    await _sighting("b.job @ y.py:9")
+    await _sighting("b.job @ y.py:9")
+    table.rows[0]["resolved_at"] = "2026-10-22T23:00:00Z"
+    await _sighting("b.job @ y.py:9")
+    await _sighting("b.job @ y.py:9")
+    assert len(table.rows) == 2
+    assert [r["context"]["occurrences"] for r in table.rows] == [2, 2], "resolve zeroes the count"
+
+
+@pytest.mark.asyncio
+async def test_without_group_open_every_capture_is_still_its_own_row(table: _Table) -> None:
+    for _ in range(2):
+        fallback.reset_capture_storm_state()
+        await fallback.record_error(RuntimeError("crash"), kind="request_crash", route="/r", database="t")
+    assert len(table.rows) == 2, "grouping is opt-in: a crash keeps its own inputs per row"