matrx-orm 3.1.174__tar.gz → 3.1.176__tar.gz

{matrx_orm-3.1.174 → matrx_orm-3.1.176}/.gitignore

@@ -197,6 +197,14 @@ cython_debug/
 # Frontend pnpm workspace (apps/) — node_modules at the workspace root and any
 # member, plus Vite caches and build output. The unified lockfile (apps/pnpm-lock.yaml)
 # IS committed; everything below is regenerated.
+#
+# 🚨 BOTH SPELLINGS. `node_modules/` with the slash matches a DIRECTORY only, so
+# a SYMLINK named `node_modules` slipped straight past it: five of them — each
+# an absolute path into one machine's checkout — were committed on main and
+# broke `pnpm install --frozen-lockfile` on every CI runner, where the symlink
+# is dangling and pnpm's `mkdir` of it answers ENOENT. Every package release was
+# blocked by it. The bare spelling below matches the symlink too.
+node_modules
 node_modules/
 apps/**/.vite/
 apps/**/dist/
@@ -328,3 +336,5 @@ apps/shared/.kit-*-witness.*/
 # They live at .wt/<slug> (disk-groom). Committing the folder would add a
 # second copy of the entire tree and a symlink into common-docs.
 .wt/
+.matrx/fixer-dispatch.json
+.matrx/fixer-ledger.json

{matrx_orm-3.1.174 → matrx_orm-3.1.176}/PKG-INFO

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

{matrx_orm-3.1.174 → matrx_orm-3.1.176}/matrx_orm/core/pooler_role.py

@@ -203,6 +203,7 @@ async def emit_contamination(event: EmptyReadContaminationEvent) -> None:
             ),
             kind="pooler_role_contamination",
             source_app="matrx-orm",
+            source_feature="system",
             route=f"orm:{event.config_name}",
             payload={
                 "config_name": event.config_name,

{matrx_orm-3.1.174 → matrx_orm-3.1.176}/matrx_orm/core/rls_session.py

@@ -51,6 +51,23 @@ _ROLE_RE = re.compile(r"^[a-z_][a-z0-9_]*$")
 # agent query holding a pooled connection. Callers may override or disable (None).
 DEFAULT_STATEMENT_TIMEOUT_MS = 30_000
 
+# Default ceiling on how long an RLS session may sit IDLE INSIDE ITS TRANSACTION before
+# Postgres ends it. Measured on the main database 2026-09-20, lane TIDY: one backend sat
+# `idle in transaction` on `Client/ClientRead` for 89.7 seconds holding AccessShareLock on
+# every partition and index of `custom.record`, `custom.merge_field_provenance` and
+# `custom.anon_form`. A campaign suite then asked for AccessExclusiveLock on one of those
+# relations and queued behind it — and because Postgres's lock queue is FIFO, every
+# ordinary reader that arrived after that queued behind the DDL, four backends deep within
+# seconds, none of which conflicted with the lock actually being held.
+#
+# Nothing legitimate is idle inside a transaction for thirty seconds: the whole point of
+# holding a session open for a turn is that work is happening in it. What IS idle that long
+# is a turn whose caller is waiting on a model, a network hop or a person — and a
+# connection holding store locks while it waits is a stall for everybody else. This ends
+# such a session instead, releasing every lock; the caller sees a named error rather than
+# the rest of the platform seeing a mystery.
+DEFAULT_IDLE_IN_TRANSACTION_TIMEOUT_MS = 30_000
+
 
 @asynccontextmanager
 async def rls_session(
@@ -60,6 +77,7 @@ async def rls_session(
     database: str | None = None,
     statement_timeout_ms: int | None = DEFAULT_STATEMENT_TIMEOUT_MS,
     lock_timeout_ms: int | None = None,
+    idle_in_transaction_timeout_ms: int | None = DEFAULT_IDLE_IN_TRANSACTION_TIMEOUT_MS,
 ) -> AsyncIterator[None]:
     """Run the enclosed block as ``role`` with ``request.jwt.claims`` set to ``claims``.
 
@@ -72,6 +90,13 @@ async def rls_session(
     ``statement_timeout`` does not bound it, and an unbounded waiter queues behind the
     dump or sweep that is already running while blocking everyone behind it. Like the
     role and the claims it is ``SET LOCAL`` — it cannot outlive the transaction.
+
+    ``idle_in_transaction_timeout_ms`` bounds how long this session may sit idle INSIDE
+    its transaction while holding every lock it has taken. It rides the same one round
+    trip as the other three settings, so it is free, and it is what stops one waiting
+    caller becoming a stall for every reader of the relations it touched — see
+    :data:`DEFAULT_IDLE_IN_TRANSACTION_TIMEOUT_MS` for the 89.7-second case that put it
+    here. ``None`` leaves the server default alone.
     """
     if not _ROLE_RE.match(role):
         raise DatabaseError(
@@ -119,6 +144,11 @@ async def rls_session(
         if lock_timeout_ms is not None:
             bound.append(str(int(lock_timeout_ms)))
             settings.append(f"set_config('lock_timeout', ${len(bound)}, true)")
+        if idle_in_transaction_timeout_ms is not None:
+            bound.append(str(int(idle_in_transaction_timeout_ms)))
+            settings.append(
+                f"set_config('idle_in_transaction_session_timeout', ${len(bound)}, true)"
+            )
         bound.append(role)
         settings.append(f"set_config('role', ${len(bound)}, true)")
         await conn.execute("select " + ", ".join(settings), *bound)

{matrx_orm-3.1.174 → matrx_orm-3.1.176}/matrx_orm/secrets_battery/__init__.py

@@ -167,6 +167,15 @@ from .service import (
 )
 
 
+from .backup_restore import (
+    BackupAttachmentSpec,
+    BackupRestoreAliasConflictError,
+    BackupRestoreResult,
+    create_backup_record_quarantined,
+)
+from .mutation_receipts import complete_backup_restore_receipt, reserve_backup_restore_receipt
+
+
 def configure_secrets(
     *,
     db_config_name: str | None = None,
@@ -192,6 +201,12 @@ def configure_secrets(
 
 
 __all__ = [
+    "BackupAttachmentSpec",
+    "BackupRestoreResult",
+    "BackupRestoreAliasConflictError",
+    "create_backup_record_quarantined",
+    "complete_backup_restore_receipt",
+    "reserve_backup_restore_receipt",
     "configure_secrets",
     "configure_encryption",
     "fernet_for_key",

matrx_orm-3.1.176/matrx_orm/secrets_battery/backup_restore.py

@@ -0,0 +1,286 @@
+"""Atomic personal backup restoration with execution disabled from insertion."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from typing import Literal
+from uuid import UUID
+
+from matrx_orm import transaction
+from matrx_orm.exceptions import describe_db_exception
+
+from .attachments import _validate_content, _validate_text
+from .crypto import encrypt_bytes, encrypt_value, mask_value
+from .items import (
+    NON_TRANSFERABLE_FIELD_KEYS,
+    FieldSpec,
+    _metadata_kwargs,
+    _refuse_reserved_generic_definition,
+    _refuse_reserved_generic_field,
+    _validate_field_key,
+)
+from .model import (
+    PACKAGE_DB_NAME,
+    CredentialAttachment,
+    CredentialItem,
+    PasskeyCredential,
+    UserSecret,
+    UserSecretGrant,
+)
+from .mutation_receipts import (
+    complete_backup_restore_receipt,
+    reserve_backup_restore_receipt,
+)
+from .org_service import record_secret_audit
+
+
+@dataclass(frozen=True, repr=False)
+class BackupAttachmentSpec:
+    """Portable file content; never rendered into logs or exception messages."""
+
+    label: str
+    description: str | None
+    file_name: str
+    media_type: str
+    content: bytes
+    source_handling: Literal["visible", "revealable"]
+
+
+@dataclass(frozen=True)
+class BackupRestoreResult:
+    item_id: str
+    replayed: bool
+
+
+class BackupRestoreAliasConflictError(Exception):
+    """A restored alias is reserved; the entire record was rolled back."""
+
+
+@asynccontextmanager
+async def _restore_transaction() -> AsyncIterator[None]:
+    try:
+        async with transaction(PACKAGE_DB_NAME):
+            yield
+    except Exception as error:
+        # Translate only after rollback; never expose value-bearing DB diagnostics.
+        info = describe_db_exception(error)
+        if info.sqlstate == "23505" and info.constraint == "user_secrets_unique_personal_key":
+            raise BackupRestoreAliasConflictError(
+                "An environment alias from this backup is already in use."
+            ) from None
+        raise
+
+
+async def create_backup_record_quarantined(
+    *,
+    actor_id: str,
+    audit_organization_id: str,
+    mutation_id: str,
+    request_fingerprint: bytes,
+    display_name: str,
+    definition_key: str,
+    definition_version: int,
+    provider_key: str | None,
+    description: str | None,
+    tags: list[str],
+    login_urls: list[str],
+    uri_match_mode: str | None,
+    notes: str | None,
+    non_secret_fields: list[dict[str, str]],
+    fields: list[FieldSpec],
+    attachments: list[BackupAttachmentSpec],
+) -> BackupRestoreResult:
+    """Restore one host-authorized personal aggregate and receipt in one transaction."""
+    # The host supplies verified actor/context and computes the binding fingerprint.
+    # No destination owner, access grant, lifecycle or execution flag is accepted.
+    try:
+        actor_id = str(UUID(actor_id))
+        audit_organization_id = str(UUID(audit_organization_id))
+        mutation_id = str(UUID(mutation_id))
+        if not isinstance(display_name, str) or not display_name:
+            raise ValueError("backup display name is required")
+        if type(definition_version) is not int or definition_version <= 0:
+            raise ValueError("invalid backup definition version")
+        _refuse_reserved_generic_definition(definition_key)
+        metadata = _metadata_kwargs(
+            login_urls=login_urls,
+            uri_match_mode=uri_match_mode,
+            notes=notes,
+            non_secret_fields=non_secret_fields,
+            browser_fill_enabled=False,
+        )
+        # Validation is shared, but restoration must not silently normalize source text.
+        metadata["login_urls"] = login_urls
+        seen: set[str] = set()
+        for field in fields:
+            _validate_field_key(field.field_key)
+            _refuse_reserved_generic_field(field.field_key)
+            if field.field_key in NON_TRANSFERABLE_FIELD_KEYS or field.field_key in seen:
+                raise ValueError("backup contains an unsupported or duplicate field")
+            if field.handling not in {"visible", "revealable"} or not isinstance(field.value, str):
+                raise ValueError("backup field is not portable")
+            if field.inject_into_sandbox:
+                raise ValueError("backup cannot enable sandbox injection")
+            seen.add(field.field_key)
+        for attachment in attachments:
+            if attachment.source_handling not in {"visible", "revealable"}:
+                raise ValueError("backup attachment is not portable")
+            _validate_content(attachment.content)
+            _validate_text(attachment.label, name="attachment label", maximum=200)
+            _validate_text(attachment.file_name, name="attachment filename", maximum=512)
+            _validate_text(attachment.media_type, name="attachment media type", maximum=255)
+            if attachment.description is not None and len(attachment.description) > 2000:
+                raise ValueError("attachment description is too long")
+    except (TypeError, ValueError, AttributeError):
+        raise ValueError("Invalid backup restore record.") from None
+
+    async with _restore_transaction():
+        receipt, replayed = await reserve_backup_restore_receipt(
+            actor_id=actor_id,
+            organization_id=audit_organization_id,
+            mutation_id=mutation_id,
+            request_fingerprint=request_fingerprint,
+        )
+        if replayed:
+            if receipt.completed_at is None or receipt.result_item_id is None:
+                raise RuntimeError("backup restore receipt is incomplete")
+            await _validate_replay(receipt.result_item_id, actor_id)
+            return BackupRestoreResult(receipt.result_item_id, True)
+        item = await CredentialItem.create(
+            user_id=actor_id,
+            organization_id=None,
+            definition_key=definition_key,
+            definition_version=definition_version,
+            provider_key=provider_key,
+            display_name=display_name,
+            description=description,
+            tags=tags,
+            status="disabled",
+            source="migration",
+            access_mode="restricted",
+            lifecycle={},
+            **metadata,
+            created_by=actor_id,
+            updated_by=actor_id,
+        )
+        for field in fields:
+            await UserSecret.create(
+                user_id=actor_id,
+                organization_id=None,
+                credential_item_id=item.id,
+                field_key=field.field_key,
+                key=field.env_key,
+                value_encrypted=encrypt_value(field.value),
+                value_hint=mask_value(field.value),
+                handling=field.handling,
+                editable=field.editable,
+                is_active=False,
+                inject_into_sandbox=False,
+                execution_purpose="general",
+                description=field.description,
+                access_mode="restricted",
+                created_by=actor_id,
+                updated_by=actor_id,
+            )
+        for attachment in attachments:
+            await CredentialAttachment.create(
+                credential_item_id=item.id,
+                label=attachment.label,
+                description=attachment.description,
+                file_name=attachment.file_name,
+                media_type=attachment.media_type,
+                size_bytes=len(attachment.content),
+                value_encrypted=encrypt_bytes(attachment.content),
+                handling=attachment.source_handling,
+                created_by=actor_id,
+                updated_by=actor_id,
+            )
+        await record_secret_audit(
+            action="item_created",
+            fail_closed=True,
+            actor_id=actor_id,
+            organization_id=audit_organization_id,
+            user_id=actor_id,
+            metadata={
+                "credential_item_id": str(item.id),
+                "source": "backup_restore",
+                "field_count": len(fields),
+                "attachment_count": len(attachments),
+                "quarantined": True,
+            },
+        )
+        await complete_backup_restore_receipt(receipt.id, result_item_id=str(item.id))
+        return BackupRestoreResult(str(item.id), False)
+
+
+async def _validate_replay(item_id: str, actor_id: str) -> None:
+    rows = (
+        await CredentialItem.filter(id=item_id, deleted_at__isnull=True)
+        .select_for_update()
+        .values(
+            "user_id",
+            "organization_id",
+            "status",
+            "access_mode",
+            "browser_fill_enabled",
+            "definition_key",
+        )
+    )
+    valid = bool(rows)
+    if rows:
+        item = rows[0]
+        valid = (
+            str(item["user_id"]) == actor_id
+            and item["organization_id"] is None
+            and item["status"] == "disabled"
+            and item["access_mode"] == "restricted"
+            and item["browser_fill_enabled"] is False
+            and item["definition_key"] not in {"native_passkey", "passkey_private"}
+        )
+    fields = await UserSecret.filter(credential_item_id=item_id).values(
+        "id",
+        "user_id",
+        "organization_id",
+        "deleted_at",
+        "is_active",
+        "access_mode",
+        "inject_into_sandbox",
+        "execution_purpose",
+        "handling",
+        "field_key",
+    )
+    for field in fields:
+        if field["deleted_at"] is None:
+            valid = valid and (
+                str(field["user_id"]) == actor_id
+                and field["organization_id"] is None
+                and field["is_active"] is False
+                and field["access_mode"] == "restricted"
+                and field["inject_into_sandbox"] is False
+                and field["execution_purpose"] == "general"
+                and field["handling"] in {"visible", "revealable"}
+                and field["field_key"] not in NON_TRANSFERABLE_FIELD_KEYS | {"passkey_private"}
+            )
+    granted = await UserSecretGrant.filter(credential_item_id=item_id).exists()
+    if fields:
+        granted = (
+            granted
+            or await UserSecretGrant.filter(user_secret_id__in=[f["id"] for f in fields]).exists()
+        )
+    protected = await PasskeyCredential.filter(
+        credential_item_id=item_id, deleted_at__isnull=True
+    ).exists()
+    files = await CredentialAttachment.filter(
+        credential_item_id=item_id, deleted_at__isnull=True
+    ).values("handling")
+    if (
+        not valid
+        or granted
+        or protected
+        or any(f["handling"] not in {"visible", "revealable"} for f in files)
+    ):
+        raise PermissionError(
+            "Restored credential has changed; retry cannot confirm its quarantine."
+        )

{matrx_orm-3.1.174 → matrx_orm-3.1.176}/matrx_orm/secrets_battery/mutation_receipts.py

@@ -15,7 +15,10 @@ from matrx_orm import transaction
 
 from .model import PACKAGE_DB_NAME, CredentialMutationReceipt
 
-MutationOperation = Literal["create_item", "add_field", "update_field", "native_passkey_create"]
+MutationOperation = Literal[
+    "create_item", "add_field", "update_field", "native_passkey_create", "native_passkey_import",
+    "backup_restore_item",
+]
 PrincipalKind = Literal["user", "organization"]
 
 
@@ -242,6 +245,7 @@ async def reserve_native_passkey_receipt(
     principal_type: PrincipalKind,
     principal_id: str,
     request_fingerprint: bytes,
+    operation: Literal["native_passkey_create", "native_passkey_import"] = "native_passkey_create",
 ) -> tuple[MutationReceipt, bool]:
     """Reserve the native-only receipt shape without exposing generic targets.
 
@@ -255,7 +259,7 @@ async def reserve_native_passkey_receipt(
         actor_id=actor_id,
         organization_id=organization_id,
         mutation_id=mutation_id,
-        operation="native_passkey_create",
+        operation=operation,
         principal_type=principal_type,
         principal_id=principal_id,
         target_item_id=None,
@@ -279,3 +283,36 @@ async def complete_native_passkey_receipt(
         result_value_version=1,
         result_passkey_id=result_passkey_id,
     )
+
+
+async def reserve_backup_restore_receipt(
+    *,
+    actor_id: str,
+    organization_id: str,
+    mutation_id: str,
+    request_fingerprint: bytes,
+) -> tuple[MutationReceipt, bool]:
+    """Bind a personal restore retry to a server-computed encrypted-envelope digest."""
+    if not isinstance(request_fingerprint, bytes) or len(request_fingerprint) != 32:
+        raise ValueError("backup restore fingerprint must be 32 bytes")
+    return await reserve_mutation_receipt(
+        actor_id=actor_id,
+        organization_id=organization_id,
+        mutation_id=mutation_id,
+        operation="backup_restore_item",
+        principal_type="user",
+        principal_id=actor_id,
+        target_item_id=None,
+        target_field_id=None,
+        request_fingerprint=request_fingerprint,
+    )
+
+
+async def complete_backup_restore_receipt(receipt_id: str, *, result_item_id: str) -> None:
+    """Complete the item-only result inside the aggregate restore transaction."""
+    await complete_mutation_receipt(
+        receipt_id,
+        result_item_id=result_item_id,
+        result_field_id=None,
+        result_value_version=None,
+    )

{matrx_orm-3.1.174 → matrx_orm-3.1.176}/matrx_orm/secrets_battery/org_service.py

@@ -200,12 +200,13 @@ async def record_secret_audit(
     user_secret_id: str | None = None,
     user_id: str | None = None,
     metadata: dict[str, Any] | None = None,
+    fail_closed: bool = False,
 ) -> None:
     """Append one audit row. Records the ACTION and metadata — NEVER a value.
 
-    Audit is a trail, not a transaction: a failed audit write is logged loudly
-    but never propagates, because losing the trail must not also lose the
-    operation the user asked for.
+    By default audit failures are logged without failing the operation.
+    Security-sensitive aggregate writes pass fail_closed=True so a failed
+    audit aborts their outer transaction with a value-free error.
 
     ``organization_id`` is REQUIRED and refused when empty. ``users
     .user_secret_audit.organization_id`` has been NOT NULL since migration 0444,
@@ -242,7 +243,9 @@ async def record_secret_audit(
                 action=action,
                 metadata=metadata or {},
             )
-    except Exception as exc:  # noqa: BLE001 — trail loss must not fail the op
+    except Exception as exc:  # noqa: BLE001 — explicit fail-closed or best-effort policy
+        if fail_closed:
+            raise RuntimeError("required credential audit failed") from None
         logger.error(
             "secrets audit write FAILED (action=%s secret=%s org=%s): %s",
             action,

{matrx_orm-3.1.174 → matrx_orm-3.1.176}/matrx_orm/session/README.md

@@ -223,7 +223,17 @@ behavior with structurally-correct one-shot writes.
 
 ## Fallback / replay
 
-When `Session.flush()` raises, every dropped op is captured to
+For an all-or-nothing copy, construct `Session(recover_individually=False)`
+through an atomic Coordinator. A batch failure then rolls back the whole
+transaction and reports the original cause without individual write recovery;
+the enclosing operation captures the failure. `Session.abort()` discards
+queued rows when the copy body fails before flush.
+
+Error-capture rows use the caller's explicit organization. When no organization
+is available, they use the operator SYSTEM organization on their fresh
+connection; a user ID alone cannot supply the missing actor context there.
+
+When a regular `Session.flush()` raises, every dropped op is captured to
 `ops.system_write_failure` on a fresh asyncpg connection (bypasses
 the failed transaction's pool slot). The recovery tool
 (`scripts/replay_write_failures.py` in aidream) can replay them