matrx-orm 3.1.182__tar.gz → 3.1.183__tar.gz

matrx_orm-3.1.183/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## Unreleased
+
+- Pool creation always ends. A pool `init` failure now aborts the connection
+  (asyncpg's own failure path awaited an untimed graceful close), and
+  `asyncpg.create_pool` runs under one deadline (`pool_create_timeout`, default
+  30 s; `connect_timeout`, default 10 s, both on `DatabaseProjectConfig`), with
+  the half-built pool terminated on failure. Before this, a database that hung
+  mid-handshake held the per-config pool lock forever: files.matrxserver.com
+  answered nothing that touched the database for 4.5 h on 2026-09-25.
+  Guard: `tests/level1/test_pool_create_never_wedges.py`.
+
+## 3.1.182
+
+- 3.1.181 was tagged against a commit that did not carry the version and never
+  published; 3.1.182 is the same code plus everything since.

{matrx_orm-3.1.182 → matrx_orm-3.1.183}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matrx-orm
-Version: 3.1.182
+Version: 3.1.183
 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.182 → matrx_orm-3.1.183}/matrx_orm/core/FEATURE.md

@@ -169,6 +169,20 @@ connection and can strand old holders in release/reset.
 
 Pinned by `tests/level1/test_pool_maintenance.py`.
 
+**Pool creation always ends.** `get_pool` creates under the config's lock, so an
+unbounded creation wedges every caller of that config. Two layers: (1) the
+`init` callback (`_init_connection_default`) ABORTS its connection on any
+failure or cancellation — asyncpg's own failure path awaits `con.close()` with
+no timeout, after the one cancellation an outer timeout could deliver was
+already spent, and against a hung database that close never ends; (2)
+`asyncpg.create_pool` runs under `pool_create_timeout` (default 30 s) with
+`connect_timeout` (default 10 s), and the half-built pool is terminated on
+failure. Incident 2026-09-25: the zero-connection replacement ran while the
+database machine was hung and held `_locks['matrx_files']` for 4.5 h (the same
+close wedged matrx-seo's keepalive). Pinned by
+`tests/level1/test_pool_create_never_wedges.py` (a fake PostgreSQL that
+handshakes, then goes silent).
+
 **A server restart rejected during checkout is a connection failure.** PostgreSQL
 `AdminShutdownError`, `CrashShutdownError`, and `CannotConnectNowError` raised
 while `pool.acquire()` opens a physical connection become `ConnectionError` at
@@ -370,5 +384,6 @@ Verified against the live database: 2026-08-21.
 - 2026-08-14: Public models now render `public.table` SQL targets; bare public
   relation names can no longer disable application logs or write-failure capture.
 - 2026-08-13: Registry, admin, recovery, catalog, and diagnostic identities are now exact `schema.table`; bare names are accepted only as uncached discovery terms and ambiguity fails loudly.
+- 2026-09-25: Pool creation is bounded and a failed connection init aborts instead of awaiting an untimed close.
 - 2026-08-13: Added atomic recovery from a pool left at zero connections after an upstream database restart.
 - 2026-08-09: Pinned positional-mapping hydration for parameter-shaped column names.

{matrx_orm-3.1.182 → matrx_orm-3.1.183}/matrx_orm/core/async_db_manager.py

@@ -119,6 +119,11 @@ def _integrity_constraint_kind(exc: asyncpg.exceptions.IntegrityConstraintViolat
 POOL_ACQUIRE_RETRIES = 2  # total acquire attempts = 1 + POOL_ACQUIRE_RETRIES
 POOL_ACQUIRE_RETRY_BASE_BACKOFF = 0.25  # seconds; doubled per attempt
 POOL_RELEASE_TIMEOUT_SECONDS = 10.0
+# Pool-creation bounds (per-config overrides: ``connect_timeout`` /
+# ``pool_create_timeout`` on DatabaseProjectConfig). Creation runs under the
+# config's pool lock, so it must always end — see _init_connection_default.
+DEFAULT_CONNECT_TIMEOUT_SECONDS = 10.0
+DEFAULT_POOL_CREATE_TIMEOUT_SECONDS = 30.0
 
 # ── read-statement retry (command-timeout self-heal) ──────────────────────────
 # A ``command_timeout`` on a READ (SELECT) is provably side-effect-free to retry
@@ -257,6 +262,30 @@ def _encode_json(value: Any) -> str:
 
 
 async def _init_connection_default(conn: asyncpg.Connection) -> None:
+    """Register the codecs on a new connection; a failure ABORTS it.
+
+    🚨 THE 2026-09-25 FILES OUTAGE. When a pool ``init`` callback raises,
+    asyncpg's ``Pool._get_new_connection`` runs ``await con.close()`` with NO
+    timeout before re-raising. Against a database that has stopped answering
+    (a hung machine: handshake done, then silence, no FIN, no RST) that graceful
+    close never finishes — and when it happens inside ``asyncpg.create_pool``,
+    matrx-orm's per-config pool-creation lock is held forever and every later
+    request queues behind it without a log line. files.matrxserver.com sat
+    exactly there for 4.5 hours. Aborting the transport here makes the
+    connection already closed, so asyncpg's ``close()`` returns at once and the
+    original error reaches the caller.
+    """
+    try:
+        await _register_connection_codecs(conn)
+    except BaseException:
+        try:
+            conn.terminate()
+        except Exception:  # noqa: BLE001 — abort is best-effort; the original error wins
+            pass
+        raise
+
+
+async def _register_connection_codecs(conn: asyncpg.Connection) -> None:
     """Register custom type codecs on each new connection.
 
     UUID codec — makes asyncpg decode PostgreSQL uuid columns directly as Python
@@ -610,7 +639,21 @@ class AsyncDatabaseManager:
                         # Bootstrap exactly one connection; the bounded
                         # maintenance controller ramps toward the desired floor.
                         bootstrap_min = min(desired_pool_min, 1)
-                        pool = await asyncpg.create_pool(
+                        connect_timeout = float(
+                            config.get("connect_timeout") or DEFAULT_CONNECT_TIMEOUT_SECONDS
+                        )
+                        create_timeout = float(
+                            config.get("pool_create_timeout")
+                            or DEFAULT_POOL_CREATE_TIMEOUT_SECONDS
+                        )
+                        # 🚨 Pool creation runs under this config's lock, so it
+                        # must END. asyncpg bounds the connect itself
+                        # (``timeout=``) but not the ``init`` callback's failure
+                        # path nor the pool as a whole; a hung database once held
+                        # this lock for 4.5 hours (see _init_connection_default).
+                        # Build the pool object, await it under one deadline,
+                        # and terminate whatever it half-built on any failure.
+                        new_pool = asyncpg.create_pool(
                             host=config["host"],
                             port=config["port"],
                             database=config["database_name"],
@@ -624,7 +667,29 @@ class AsyncDatabaseManager:
                             statement_cache_size=statement_cache_size,
                             server_settings=server_settings,
                             init=_init_connection_default,
+                            timeout=connect_timeout,
                         )
+                        try:
+                            async with asyncio.timeout(create_timeout):
+                                pool = await new_pool
+                        except BaseException as create_exc:
+                            try:
+                                new_pool.terminate()
+                            except Exception:  # noqa: BLE001 — a pool that never initialised has nothing to abort
+                                pass
+                            if isinstance(create_exc, TimeoutError):
+                                logger.error(
+                                    "[matrx_orm] Pool creation for '%s' did not finish within "
+                                    "%.1fs (connect timeout %.1fs) — the database accepted "
+                                    "the connection but stopped answering. The half-built "
+                                    "pool was terminated; the next request tries again.",
+                                    config_name,
+                                    create_timeout,
+                                    connect_timeout,
+                                )
+                            # A TimeoutError is classified below as a transport
+                            # timeout (DatabaseConnectError) — one honest banner.
+                            raise
                         cls._pools[config_name] = pool
 
                         logger.info(

{matrx_orm-3.1.182 → matrx_orm-3.1.183}/matrx_orm/core/config.py

@@ -53,6 +53,13 @@ class DatabaseProjectConfig:
     pool_min: int = 5
     pool_max: int = 30
     command_timeout: int = 10
+    # Bounds on opening a pool. ``connect_timeout`` is asyncpg's per-connection
+    # connect deadline; ``pool_create_timeout`` bounds the whole creation
+    # (connect + the init callback + asyncpg's own cleanup). Creation holds the
+    # config's pool lock, so an unbounded creation wedges every caller: the
+    # 2026-09-25 files.matrxserver.com outage (4.5 h behind one stuck create).
+    connect_timeout: float = 10.0
+    pool_create_timeout: float = 30.0
 
     # Maximum seconds an idle connection may sit in the pool before it is
     # closed and replaced. asyncpg's own default is 300s, which is *longer*
@@ -240,6 +247,8 @@ class DatabaseRegistry:
             "pool_min": config.pool_min,
             "pool_max": config.pool_max,
             "command_timeout": config.command_timeout,
+            "connect_timeout": config.connect_timeout,
+            "pool_create_timeout": config.pool_create_timeout,
             "max_inactive_connection_lifetime": config.max_inactive_connection_lifetime,
             "server_settings": dict(config.server_settings),
             "ssl": config.ssl,

{matrx_orm-3.1.182 → matrx_orm-3.1.183}/matrx_orm/secrets_battery/FEATURE.md

@@ -43,8 +43,12 @@ keys, typed identifiers and timestamp, locked original ownership, and empty
 component arrays. Organization-owned history refuses until the host supplies the
 grant/offboarding parent-lock contract. Future aggregate capture may use the
 revision-1/revision-2 bootstrap only after its producer, authority, retention,
-rotation, and reader gates are independently accepted. Gate B must freeze and
-validate the encrypted component shape before the writer can accept a snapshot.
+rotation, and reader gates are independently accepted. Gate B's source-only
+1047 validator freezes one personal, active ordinary password field shape: its
+first recorded update is an A=A bootstrap followed by A→B, and later records
+are one prior-after-matched delta each. Application capture is explicitly off
+until every producer and reader gate is accepted; 1047 is never applied outside
+the named runner's reviewed rehearsal.
 
 Items may also own N encrypted **file attachments**
 (`users.credential_attachments`). An attachment has its own stable id,
@@ -156,6 +160,8 @@ drops every grantee when `access_mode='all_members'` — it survives for the org
 access-mode flip, but building new callers on it is how a share edit silently
 revokes someone. `list_granted_credential_items(user_id)` is the
 "shared with me" read.
+`set_item_grants` locks the live parent before deleting or replacing grants;
+host readers and revokers therefore serialize parent-first.
 
 `transfer_credential_item` clears prior grants by default (`clear_grants=True`)
 and writes BOTH `item_transferred` and `item_transferred_out`, so the losing
@@ -381,6 +387,10 @@ delete).
 
 ## Change Log
 
+- **2026-09-25** — `set_item_grants` now locks the live parent before grant
+  replacement, matching the host bulk reader's revocation order. A focused
+  ordering test fails if deletion moves ahead of the parent lock.
+
 - **2026-09-24** — Migration 1036 closes the personal-only Vault revision envelope and refuses organization history pending the canonical grant/offboarding parent lock; capture remains disabled.
 
 - **2026-09-24** — Kept the history counter out of the ORM until migrations are installed; the branch database lacks the column and a premature model mapping broke ordinary Vault creation. Capture remains disabled.

{matrx_orm-3.1.182 → matrx_orm-3.1.183}/matrx_orm/secrets_battery/items.py

@@ -1327,7 +1327,7 @@ async def update_credential_field_value(
             _PASSWORD_HISTORY_CAPTURE_ENABLED and not system_rotation
             and item_raw is not None and item_raw.get("user_id") is not None
             and raw.get("field_key") == "password" and raw.get("handling") in {"visible", "revealable"}
-            and raw.get("execution_purpose") == GENERAL_EXECUTION_PURPOSE
+            and raw.get("execution_purpose") == GENERAL_EXECUTION_PURPOSE and raw.get("is_active") is True
         )
         history_revision: int | None = None
         capture_started_at = datetime.now(UTC)
@@ -1335,17 +1335,18 @@ async def update_credential_field_value(
             if not actor_id or not audit_organization_id:
                 raise VaultHistorySnapshotError("personal password history requires actor and admitted audit organization")
             history_revision = await locked_history_revision(str(item_raw["id"]))
-            before = password_field_update_snapshot(
-                item_id=str(item_raw["id"]), item_user_id=str(item_raw["user_id"]),
-                audit_organization_id=audit_organization_id, field_id=field_id,
-                field_key=str(raw["field_key"]), handling=str(raw["handling"]),
-                execution_purpose=str(raw["execution_purpose"]), before_encrypted=raw["value_encrypted"],
-                after_encrypted=raw["value_encrypted"], capture_started_at=capture_started_at,
-            )
-            history_revision = await write_password_field_update_snapshot(
-                item_id=str(item_raw["id"]), actor_id=actor_id, audit_organization_id=audit_organization_id,
-                expected_revision=history_revision, snapshot=before,
-            )
+            if history_revision == 0:
+                before = password_field_update_snapshot(
+                    item_id=str(item_raw["id"]), item_user_id=str(item_raw["user_id"]),
+                    audit_organization_id=audit_organization_id, field_id=field_id,
+                    field_key=str(raw["field_key"]), handling=str(raw["handling"]),
+                    execution_purpose=str(raw["execution_purpose"]), before_encrypted=raw["value_encrypted"],
+                    after_encrypted=raw["value_encrypted"], capture_started_at=capture_started_at,
+                )
+                history_revision = await write_password_field_update_snapshot(
+                    item_id=str(item_raw["id"]), actor_id=actor_id, audit_organization_id=audit_organization_id,
+                    expected_revision=history_revision, snapshot=before,
+                )
         encrypted_value = encrypt_value(value)
         await UserSecret.update_where(
             {"id": field_id, "deleted_at__isnull": True},
@@ -1800,7 +1801,6 @@ async def set_item_grants(
     recipient is a legitimate member first."""
     if access_mode not in ("all_members", "restricted"):
         raise ValueError(f"access_mode must be all_members|restricted; got {access_mode!r}")
-    item_raw = await _require_item_raw(item_id)
     # Dedup by user_id, last spec wins.
     deduped: dict[str, ItemGrantSpec] = {}
     if access_mode == "restricted":
@@ -1810,6 +1810,10 @@ async def set_item_grants(
             deduped[g.user_id] = g
     recipients = [deduped[uid] for uid in sorted(deduped)]
     async with transaction(PACKAGE_DB_NAME):
+        # Readers and revokers share parent-first serialization. Deleting grant
+        # rows before this lock inverts the order and can deadlock with a
+        # plaintext reader holding the parent while acquiring its grant.
+        item_raw = await _lock_item_raw(item_id)
         await UserSecretGrant.delete_where(credential_item_id=item_id)
         for g in recipients:
             await UserSecretGrant.create(

{matrx_orm-3.1.182 → matrx_orm-3.1.183}/matrx_orm/secrets_battery/vault_history.py

@@ -121,12 +121,25 @@ def validate_snapshot_v1(snapshot: dict[str, Any]) -> None:
             raise VaultHistorySnapshotError("Vault history state is not valid encrypted v1 data")
 
 
+def validate_snapshot_revision(snapshot: dict[str, Any], expected_revision: int) -> None:
+    """Bind the bootstrap shape to revision zero and every later shape to a delta."""
+    validate_snapshot_v1(snapshot)
+    if expected_revision < 0:
+        raise VaultHistorySnapshotError("Vault history revision must be non-negative")
+    change = snapshot["changed_components"][0]
+    same_state = change["before"] == change["after"]
+    if expected_revision == 0 and not same_state:
+        raise VaultHistorySnapshotError("Vault history revision one must be the A=A bootstrap")
+    if expected_revision > 0 and same_state:
+        raise VaultHistorySnapshotError("Vault history revisions after bootstrap must be deltas")
+
+
 async def write_password_field_update_snapshot(
     *, item_id: str, actor_id: str, audit_organization_id: str, expected_revision: int,
     snapshot: dict[str, Any],
 ) -> int:
     """Call the 1034 private writer inside the caller's active transaction."""
-    validate_snapshot_v1(snapshot)
+    validate_snapshot_revision(snapshot, expected_revision)
     rows = await call_function(
         PACKAGE_DB_NAME, "history", "vault_write_revision", item_id, actor_id,
         audit_organization_id, expected_revision, snapshot, mode="rows",

{matrx_orm-3.1.182 → matrx_orm-3.1.183}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.182"
+version = "3.1.183"
 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.183/tests/level1/test_pool_create_never_wedges.py

@@ -0,0 +1,194 @@
+"""A pool created against a database that stops answering must fail in bounded time.
+
+Incident 2026-09-25 (files.matrxserver.com): the production database machine hung
+14:30–14:38 UTC. matrx-orm's zero-connection self-heal replaced the dead pool and
+called ``asyncpg.create_pool`` while the database was still hung. The new
+connection completed its handshake, then the pool ``init`` callback
+(``_init_connection_default`` -> ``set_type_codec`` introspection) timed out, and
+asyncpg's failure path ran ``await con.close()`` with NO timeout. The graceful
+close never finished, ``create_pool`` never returned, and the per-config
+pool-creation lock stayed held for 4.5 hours: every request queued behind it with
+no log and no socket, until the container was restarted.
+
+This test reproduces that exact wire situation with a fake PostgreSQL server
+that completes the startup handshake and then goes silent forever (it never
+answers a query and never closes the socket — what a hung machine looks like to
+a client). It drives the REAL ``AsyncDatabaseManager.get_connection`` ->
+``get_pool`` -> ``asyncpg.create_pool`` path with the real ``init`` callback.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import struct
+import time
+
+import pytest
+from matrx_orm.core.async_db_manager import AsyncDatabaseManager
+from matrx_orm.core.config import DatabaseProjectConfig, register_database, registry
+
+
+def _msg(kind: bytes, payload: bytes) -> bytes:
+    return kind + struct.pack("!I", len(payload) + 4) + payload
+
+
+def _param(name: str, value: str) -> bytes:
+    return _msg(b"S", name.encode() + b"\0" + value.encode() + b"\0")
+
+
+class HungAfterHandshakeServer:
+    """Speaks the PostgreSQL startup protocol, then never answers again."""
+
+    def __init__(self) -> None:
+        self.connections = 0
+        self.writers: list[asyncio.StreamWriter] = []
+        self.server: asyncio.base_events.Server | None = None
+        self.port = 0
+
+    async def start(self) -> None:
+        self.server = await asyncio.start_server(self._handle, "127.0.0.1", 0)
+        self.port = self.server.sockets[0].getsockname()[1]
+
+    async def _handle(self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None:
+        self.connections += 1
+        self.writers.append(writer)
+        try:
+            (length,) = struct.unpack("!I", await reader.readexactly(4))
+            await reader.readexactly(length - 4)  # StartupMessage (ssl disabled)
+            writer.write(
+                _msg(b"R", struct.pack("!I", 0))  # AuthenticationOk
+                + _param("server_version", "17.0")
+                + _param("server_encoding", "UTF8")
+                + _param("client_encoding", "UTF8")
+                + _param("DateStyle", "ISO, MDY")
+                + _param("integer_datetimes", "on")
+                + _param("standard_conforming_strings", "on")
+                + _msg(b"K", struct.pack("!II", 1234, 5678))  # BackendKeyData
+                + _msg(b"Z", b"I")  # ReadyForQuery
+            )
+            await writer.drain()
+            # Hung machine: read and drop everything (queries, Sync, Terminate);
+            # never reply, never close.
+            while await reader.read(65536):
+                pass
+        except (asyncio.IncompleteReadError, ConnectionError):
+            pass
+        # Peer closed: stay silent, keep our side open until the test ends.
+        await asyncio.Event().wait()
+
+    async def stop(self) -> None:
+        for w in self.writers:
+            w.transport.abort()
+        if self.server is not None:
+            self.server.close()
+
+
+def _register(name: str, port: int, *, command_timeout: int = 1, create_timeout: float = 4.0) -> None:
+    registry._configs.pop(name, None)
+    register_database(
+        DatabaseProjectConfig(
+            name=name,
+            alias=f"{name}_alias",
+            host="127.0.0.1",
+            port=str(port),
+            database_name="postgres",
+            user="postgres",
+            password="unused",
+            pool_min=1,
+            pool_max=2,
+            command_timeout=command_timeout,
+            ssl=False,
+            write_queue_enabled=False,
+            connect_timeout=2.0,
+            pool_create_timeout=create_timeout,
+        )
+    )
+
+
+def _forget(name: str) -> None:
+    pool = AsyncDatabaseManager._pools.pop(name, None)
+    if pool is not None:
+        try:
+            pool.terminate()
+        except Exception:
+            pass
+    AsyncDatabaseManager._pool_loops.pop(name, None)
+    AsyncDatabaseManager._locks.pop(name, None)
+    AsyncDatabaseManager._growth_locks.pop(name, None)
+    task = AsyncDatabaseManager._keepalive_tasks.pop(name, None)
+    if task is not None:
+        task.cancel()
+    registry._configs.pop(name, None)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    ("command_timeout", "create_timeout"),
+    [
+        # init's introspection times out first (files.matrxserver.com, 14:32 UTC)
+        (1, 4.0),
+        # the outer deadline CANCELS init first. asyncpg then awaits its cleanup
+        # close() after the one cancellation was already spent — the trap that
+        # also wedged matrx-seo's keepalive (maintain_one_connection's 5 s timeout
+        # cancelled init; the close that followed hung for 4.5 h).
+        (30, 2.0),
+    ],
+    ids=["init-times-out", "deadline-cancels-init"],
+)
+async def test_pool_creation_against_a_hung_database_fails_in_bounded_time_and_releases_the_lock(
+    command_timeout: int, create_timeout: float
+):
+    name = f"hung_after_handshake_{command_timeout}"
+    server = HungAfterHandshakeServer()
+    await server.start()
+    _register(name, server.port, command_timeout=command_timeout, create_timeout=create_timeout)
+    try:
+        # First caller: must FAIL (not hang) well inside the create deadline + slack.
+        started = time.monotonic()
+        with pytest.raises(Exception):
+            async with asyncio.timeout(15):  # the test's own backstop, far above the knob
+                async with AsyncDatabaseManager.get_connection(name, timeout=1.0):
+                    pass
+        first_elapsed = time.monotonic() - started
+        assert first_elapsed < 10, f"pool creation took {first_elapsed:.1f}s against a hung DB"
+
+        # The pool-creation lock must be free again: a wedged lock is the outage.
+        lock = AsyncDatabaseManager._locks.get(name)
+        assert lock is not None and not lock.locked(), "pool-creation lock left held"
+        assert name not in AsyncDatabaseManager._pools, "a half-initialised pool was kept"
+
+        # Second caller reaches the database again (a new connection attempt), and
+        # also fails in bounded time — nobody queues forever behind the first.
+        before = server.connections
+        started = time.monotonic()
+        with pytest.raises(Exception):
+            async with asyncio.timeout(15):
+                async with AsyncDatabaseManager.get_connection(name, timeout=1.0):
+                    pass
+        assert time.monotonic() - started < 10
+        assert server.connections > before, "second caller never reached the database"
+    finally:
+        _forget(name)
+        await server.stop()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("failure", [TimeoutError, asyncio.CancelledError])
+async def test_failed_init_aborts_the_connection_instead_of_a_graceful_close_that_can_hang(failure):
+    """The init callback's own failure — or its cancellation — leaves asyncpg nothing to wait on."""
+    from matrx_orm.core.async_db_manager import _init_connection_default
+
+    class _Conn:
+        def __init__(self) -> None:
+            self.terminated = False
+
+        async def set_type_codec(self, *_a, **_k):
+            raise failure("introspection timed out on a hung database")
+
+        def terminate(self) -> None:
+            self.terminated = True
+
+    conn = _Conn()
+    with pytest.raises(failure):
+        await _init_connection_default(conn)  # type: ignore[arg-type]
+    assert conn.terminated, "a failed init must abort the connection"

{matrx_orm-3.1.182 → matrx_orm-3.1.183}/tests/test_secrets_battery.py

@@ -11,6 +11,7 @@ from __future__ import annotations
 
 import base64
 import hashlib
+from contextlib import asynccontextmanager
 from datetime import UTC, datetime
 
 import pytest
@@ -880,6 +881,35 @@ async def test_set_item_grants_validates_access_mode_before_touching_db():
         await items.set_item_grants("i1", actor_id="u1", access_mode="nope", grants=[])
 
 
+@pytest.mark.asyncio
+async def test_set_item_grants_locks_parent_before_deleting_grants(monkeypatch):
+    from matrx_orm.secrets_battery import items
+
+    events: list[str] = []
+
+    @asynccontextmanager
+    async def fake_transaction(_database):
+        yield
+
+    async def lock_parent(_item_id):
+        events.append("parent")
+        return {"id": "i1"}
+
+    async def delete_grants(**_filters):
+        events.append("grant_delete")
+        raise RuntimeError("stop after order proof")
+
+    monkeypatch.setattr(items, "transaction", fake_transaction)
+    monkeypatch.setattr(items, "_lock_item_raw", lock_parent)
+    monkeypatch.setattr(items.UserSecretGrant, "delete_where", delete_grants)
+
+    with pytest.raises(RuntimeError, match="order proof"):
+        await items.set_item_grants(
+            "i1", actor_id="u1", access_mode="restricted", grants=[]
+        )
+    assert events == ["parent", "grant_delete"]
+
+
 # ── Rotation primitives (I-7) ─────────────────────────────────────────────
 
 
@@ -1145,7 +1175,10 @@ def test_password_history_snapshot_v1_excludes_plaintext_and_hints(monkeypatch):
         vault_history.validate_snapshot_v1(snapshot)
 
 
-def _history_update_fakes(monkeypatch, *, writer_error: Exception | None = None):
+def _history_update_fakes(
+    monkeypatch, *, writer_error: Exception | None = None, writer_error_call: int | None = None,
+    revision: int = 0,
+):
     from matrx_orm.secrets_battery import items
 
     old_ciphertext = _history_ciphertext()
@@ -1179,7 +1212,7 @@ def _history_update_fakes(monkeypatch, *, writer_error: Exception | None = None)
 
     async def _writer(**kwargs):
         snapshots.append(kwargs["snapshot"])
-        if writer_error:
+        if writer_error and (writer_error_call is None or len(snapshots) == writer_error_call):
             raise writer_error
         return kwargs["expected_revision"] + 1
 
@@ -1189,7 +1222,7 @@ def _history_update_fakes(monkeypatch, *, writer_error: Exception | None = None)
     monkeypatch.setattr(items, "transaction", _FakeTxn())
     monkeypatch.setattr(items, "write_password_field_update_snapshot", _writer)
     async def _revision(_item_id):
-        return 0
+        return revision
     monkeypatch.setattr(items, "locked_history_revision", _revision)
     monkeypatch.setattr(items, "record_secret_audit", _noop_audit)
     return items, updates, snapshots
@@ -1220,3 +1253,66 @@ async def test_password_update_does_not_mutate_when_history_write_fails(monkeypa
             audit_organization_id="00000000-0000-0000-0000-000000000003",
         )
     assert updates == []
+
+
+def test_password_history_revision_shape_allows_only_one_bootstrap(monkeypatch):
+    from matrx_orm.secrets_battery import vault_history
+
+    monkeypatch.setenv("CREDENTIALS_ENCRYPTION_KEY", _fernet_key())
+    ciphertext = _history_ciphertext()
+    bootstrap = vault_history.password_field_update_snapshot(
+        item_id="00000000-0000-0000-0000-000000000001", item_user_id="00000000-0000-0000-0000-000000000002",
+        audit_organization_id="00000000-0000-0000-0000-000000000003", field_id="00000000-0000-0000-0000-000000000004",
+        field_key="password", handling="revealable", execution_purpose="general", before_encrypted=ciphertext,
+        after_encrypted=ciphertext, capture_started_at=datetime.now(UTC),
+    )
+    vault_history.validate_snapshot_revision(bootstrap, 0)
+    with pytest.raises(vault_history.VaultHistorySnapshotError, match="must be deltas"):
+        vault_history.validate_snapshot_revision(bootstrap, 2)
+
+
+@pytest.mark.asyncio
+async def test_password_update_after_bootstrap_writes_one_delta(monkeypatch):
+    monkeypatch.setenv("CREDENTIALS_ENCRYPTION_KEY", _fernet_key())
+    items, _updates, snapshots = _history_update_fakes(monkeypatch, revision=2)
+    await items.update_credential_field_value(
+        "00000000-0000-0000-0000-000000000004", "synthetic-password-c", actor_id="00000000-0000-0000-0000-000000000002",
+        audit_organization_id="00000000-0000-0000-0000-000000000003",
+    )
+    assert len(snapshots) == 1
+    assert snapshots[0]["changed_components"][0]["before"] != snapshots[0]["changed_components"][0]["after"]
+
+
+@pytest.mark.asyncio
+async def test_second_history_write_failure_propagates_from_atomic_transaction(monkeypatch):
+    monkeypatch.setenv("CREDENTIALS_ENCRYPTION_KEY", _fernet_key())
+    items, updates, snapshots = _history_update_fakes(
+        monkeypatch, writer_error=RuntimeError("history unavailable"), writer_error_call=2,
+    )
+    with pytest.raises(RuntimeError, match="history unavailable"):
+        await items.update_credential_field_value(
+            "00000000-0000-0000-0000-000000000004", "synthetic-password-b", actor_id="00000000-0000-0000-0000-000000000002",
+            audit_organization_id="00000000-0000-0000-0000-000000000003",
+        )
+    assert len(snapshots) == 2
+    assert updates  # The real transaction owns this statement and rolls it back on the propagated failure.
+
+
+@pytest.mark.asyncio
+async def test_inactive_password_never_enters_history_capture(monkeypatch):
+    monkeypatch.setenv("CREDENTIALS_ENCRYPTION_KEY", _fernet_key())
+    items, updates, snapshots = _history_update_fakes(monkeypatch)
+    original = items.UserSecret
+
+    class _InactiveSecrets(original):
+        @classmethod
+        def filter(cls, **_kw):
+            return _FakeQB([dict(_FIELD_RAW, id="00000000-0000-0000-0000-000000000004", field_key="password", editable=True, is_active=False, value_encrypted=_history_ciphertext())])
+
+    monkeypatch.setattr(items, "UserSecret", _InactiveSecrets)
+    await items.update_credential_field_value(
+        "00000000-0000-0000-0000-000000000004", "synthetic-password-b", actor_id="00000000-0000-0000-0000-000000000002",
+        audit_organization_id="00000000-0000-0000-0000-000000000003",
+    )
+    assert snapshots == []
+    assert updates

matrx_orm-3.1.182/CHANGELOG.md

@@ -1,6 +0,0 @@
-# Changelog
-
-## 3.1.182
-
-- 3.1.181 was tagged against a commit that did not carry the version and never
-  published; 3.1.182 is the same code plus everything since.