matrx-orm 3.1.164__tar.gz → 3.1.166__tar.gz

{matrx_orm-3.1.164 → matrx_orm-3.1.166}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matrx-orm
-Version: 3.1.164
+Version: 3.1.166
 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.164 → matrx_orm-3.1.166}/matrx_orm/__init__.py

@@ -226,6 +226,7 @@ from .core.pydantic_bridge import (
     model_json_schema,
 )
 from .core.pool_watch import (
+    PoolHolderProvenance,
     PoolHolderSnapshot,
     PoolSaturationEvent,
     connection_holder_census,
@@ -657,6 +658,7 @@ __all__ = [
     "Paginator",
     "Page",
     # ── Pool saturation observability ───────────────────────────────────────────
+    "PoolHolderProvenance",
     "PoolHolderSnapshot",
     "PoolSaturationEvent",
     "connection_holder_census",

{matrx_orm-3.1.164 → matrx_orm-3.1.166}/matrx_orm/core/FEATURE.md

@@ -186,6 +186,11 @@ and invokes host sinks; subsequent retry timeouts do not spam another incident.
 Once a release returns an idle slot, the alarm re-arms. The final
 `PoolAcquireTimeoutError.details` carries both the first snapshot and the current
 census, so retry/persistence casualties preserve the diagnosis.
+The census also carries only identifier-validated request provenance from the
+host-injected context (`request_id`, source/execution labels). It deliberately
+excludes route text, users, arguments, SQL, and arbitrary metadata, so an opaque
+ORM operation can be tied to its producer without turning the saturation sink
+into a request-payload recorder.
 
 **Release is bounded and cancellation-safe.** Return/reset runs in a dedicated,
 shielded task with a 10-second asyncpg release timeout. A holder remains visible

{matrx_orm-3.1.164 → matrx_orm-3.1.166}/matrx_orm/core/pool_watch.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import asyncio
 import logging
+import re
 import time
 import traceback
 from collections.abc import AsyncIterator, Callable
@@ -10,14 +11,41 @@ from dataclasses import dataclass
 from datetime import UTC, datetime
 from typing import Any, Literal
 
-from pydantic import BaseModel, ConfigDict
+from pydantic import BaseModel, ConfigDict, field_validator
 
-from matrx_utils import vcprint
+from matrx_utils import get_active_context, vcprint
 
 logger = logging.getLogger("matrx_orm.pool_watch")
 
 _STACK_LIMIT = 24
 _DISPLAY_STACK_LIMIT = 8
+_PROVENANCE_TEXT = re.compile(r"^[A-Za-z0-9_.:/-]{1,128}$")
+
+
+class PoolHolderProvenance(BaseModel):
+    """Bounded, request-scoped producer identity safe for durable capture."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    request_id: str | None = None
+    source_app: str | None = None
+    source_feature: str | None = None
+    origin_class: str | None = None
+    execution_kind: str | None = None
+    execution_id: str | None = None
+
+    @field_validator(
+        "request_id",
+        "source_app",
+        "source_feature",
+        "origin_class",
+        "execution_kind",
+        "execution_id",
+        mode="before",
+    )
+    @classmethod
+    def _only_bounded_identifiers(cls, value: Any) -> str | None:
+        return value if isinstance(value, str) and _PROVENANCE_TEXT.fullmatch(value) else None
 
 
 class PoolHolderSnapshot(BaseModel):
@@ -32,6 +60,7 @@ class PoolHolderSnapshot(BaseModel):
     acquired_at: datetime
     checkout_site: str
     checkout_stack: tuple[str, ...]
+    provenance: PoolHolderProvenance = PoolHolderProvenance()
     current_site: str | None
     current_stack: tuple[str, ...]
     task_done: bool
@@ -68,6 +97,7 @@ class _TrackedHolder:
     acquired_at: datetime
     checkout_site: str
     checkout_stack: tuple[str, ...]
+    provenance: PoolHolderProvenance
     state: Literal["held", "releasing"] = "held"
 
 
@@ -105,6 +135,26 @@ def _capture_checkout_stack() -> tuple[str, tuple[str, ...]]:
     return site, formatted
 
 
+def _safe_provenance_text(value: Any) -> str | None:
+    """Keep only bounded identifier vocabulary; never persist context payloads."""
+    return value if isinstance(value, str) and _PROVENANCE_TEXT.fullmatch(value) else None
+
+
+def _capture_provenance() -> PoolHolderProvenance:
+    """Project host request context without coupling this package to that host."""
+    context = get_active_context()
+    if context is None:
+        return PoolHolderProvenance()
+    return PoolHolderProvenance(
+        request_id=_safe_provenance_text(getattr(context, "request_id", None)),
+        source_app=_safe_provenance_text(getattr(context, "source_app", None)),
+        source_feature=_safe_provenance_text(getattr(context, "source_feature", None)),
+        origin_class=_safe_provenance_text(getattr(context, "origin_class", None)),
+        execution_kind=_safe_provenance_text(getattr(context, "execution_kind", None)),
+        execution_id=_safe_provenance_text(getattr(context, "execution_id", None)),
+    )
+
+
 def _task_stack(task: asyncio.Task[Any]) -> tuple[str | None, tuple[str, ...]]:
     try:
         frames = task.get_stack(limit=_DISPLAY_STACK_LIMIT)
@@ -122,6 +172,7 @@ def track_connection_holder(config_name: str, connection: Any) -> None:
     if task is None:
         return
     checkout_site, checkout_stack = _capture_checkout_stack()
+    provenance = _capture_provenance()
     tracked = _TrackedHolder(
         config_name=config_name,
         connection=connection,
@@ -130,6 +181,7 @@ def track_connection_holder(config_name: str, connection: Any) -> None:
         acquired_at=datetime.now(UTC),
         checkout_site=checkout_site,
         checkout_stack=checkout_stack,
+        provenance=provenance,
     )
     _holders.setdefault(config_name, {})[id(connection)] = tracked
 
@@ -166,6 +218,7 @@ def connection_holder_census(config_name: str) -> tuple[PoolHolderSnapshot, ...]
                 acquired_at=tracked.acquired_at,
                 checkout_site=tracked.checkout_site,
                 checkout_stack=tracked.checkout_stack,
+                provenance=tracked.provenance,
                 current_site=current_site,
                 current_stack=current_stack,
                 task_done=tracked.task.done(),
@@ -304,6 +357,7 @@ def emit_first_pool_timeout(
 
 
 __all__ = [
+    "PoolHolderProvenance",
     "PoolHolderSnapshot",
     "PoolSaturationEvent",
     "connection_holder_census",

{matrx_orm-3.1.164 → matrx_orm-3.1.166}/matrx_orm/secrets_battery/FEATURE.md

@@ -328,6 +328,22 @@ delete).
 
 ## Change Log
 
+- **2026-09-17 (3.1.160)** — **An audit row NAMES its organization, or nothing is
+  written.** `record_secret_audit(organization_id=...)` is REQUIRED and refuses an
+  empty value by name; it used to default to `None` "for legacy callers", and 51 of
+  its 72 call sites passed nothing, so the database's resolver chain
+  (`users._stamp_secret_audit_org`, migration 0444) stamped whichever personal
+  organization it could reach and a team credential's trail landed in one person's
+  workspace, silently. The new `audit_organization(record_organization_id=...,
+  request_organization_id=...)` picks the value: the AUDITED RECORD's organization
+  wins (a child row takes its parent's tenancy), a PERSONAL record — whose
+  `organization_id` IS NULL by `credential_items_one_owner_check` — is filed in the
+  organization the HOST carried in, and with neither it REFUSES naming the site.
+  Every write/reveal/grant/transfer/fork/attachment entry point therefore takes an
+  optional `audit_organization_id` (the admitted request organization); the battery
+  still has no tenancy model and never resolves one. Pinned by
+  `tests/test_secret_audit_names_its_organization.py`. Law:
+  `common-docs/policies/context-is-carried-never-rebuilt.md`.
 - **2026-09-12** — `resolve_org_secrets`' `last_used_at` telemetry write now
   locks its rows ascending by primary key (`lock_rows_in_pk_order=True`). As an
   unordered multi-row UPDATE it deadlocked against itself under parallel agent

{matrx_orm-3.1.164 → matrx_orm-3.1.166}/matrx_orm/secrets_battery/__init__.py

@@ -132,6 +132,7 @@ from .org_service import (
     delete_org_secret,
     get_org_secret_row,
     list_org_secrets,
+    audit_organization,
     record_secret_audit,
     resolve_effective_secrets,
     resolve_org_secrets,
@@ -282,6 +283,7 @@ __all__ = [
     "delete_org_secret",
     "get_org_secret_row",
     "list_org_secrets",
+    "audit_organization",
     "record_secret_audit",
     "resolve_effective_secrets",
     "resolve_org_secrets",

{matrx_orm-3.1.164 → matrx_orm-3.1.166}/matrx_orm/secrets_battery/attachments.py

@@ -15,7 +15,7 @@ from typing import Any
 from .crypto import decrypt_bytes, encrypt_bytes
 from .items import CredentialItemNotFoundError, HANDLING_MODES, SealedFieldError
 from .model import CredentialAttachment, CredentialItem
-from .org_service import record_secret_audit
+from .org_service import audit_organization, record_secret_audit
 from .service import SecretDecryptError
 
 MAX_VAULT_ATTACHMENT_BYTES = 25 * 1024 * 1024
@@ -85,6 +85,23 @@ async def _require_item(item_id: str) -> None:
         raise CredentialItemNotFoundError(f"credential item {item_id} not found")
 
 
+async def _parent_item_organization(item_id: str) -> str | None:
+    """The organization of the item an attachment hangs off.
+
+    An attachment is a CHILD of the credential item — ownership and sharing
+    live exclusively on the parent — so its audit row belongs in the PARENT's
+    organization (THE REQUEST CONTEXT IS CARRIED, NEVER REBUILT, rule 4). A
+    PERSONAL parent has ``organization_id IS NULL`` by constraint; the host's
+    request organization answers for it, through :func:`audit_organization`.
+    """
+    rows = await CredentialItem.filter(id=item_id, deleted_at__isnull=True).values(
+        "organization_id"
+    )
+    if not rows:
+        raise CredentialItemNotFoundError(f"credential item {item_id} not found")
+    return rows[0].get("organization_id")
+
+
 async def _require_raw(attachment_id: str) -> dict[str, Any]:
     rows = await CredentialAttachment.filter(id=attachment_id, deleted_at__isnull=True).values(
         *_ATTACHMENT_FIELDS, "value_encrypted"
@@ -157,9 +174,11 @@ async def add_credential_attachment(
     content: bytes,
     handling: str = "revealable",
     actor_id: str | None = None,
+    audit_organization_id: str | None = None,
 ) -> CredentialAttachmentRow:
     """Encrypt and attach one file to an existing credential item."""
     await _require_item(item_id)
+    parent_org = await _parent_item_organization(item_id)
     _validate_content(content)
     _validate_handling(handling)
     clean_label = _validate_text(label, name="label", maximum=200)
@@ -184,6 +203,11 @@ async def add_credential_attachment(
     await record_secret_audit(
         action="attachment_added",
         actor_id=actor_id,
+        organization_id=audit_organization(
+            record_organization_id=parent_org,
+            request_organization_id=audit_organization_id,
+            what=f"add_credential_attachment(item_id={item_id})",
+        ),
         metadata={
             "credential_item_id": item_id,
             "attachment_id": str(instance.id),
@@ -209,9 +233,11 @@ async def update_credential_attachment_metadata(
     file_name: str | None = None,
     handling: str | None = None,
     actor_id: str | None = None,
+    audit_organization_id: str | None = None,
 ) -> CredentialAttachmentRow:
     """Patch safe metadata without touching bytes or ``value_version``."""
     raw = await _require_raw(attachment_id)
+    parent_org = await _parent_item_organization(str(raw["credential_item_id"]))
     if handling is not None:
         _validate_handling(handling)
         if str(raw["handling"]) == "sealed" and handling != "sealed":
@@ -238,6 +264,11 @@ async def update_credential_attachment_metadata(
     await record_secret_audit(
         action="attachment_updated",
         actor_id=actor_id,
+        organization_id=audit_organization(
+            record_organization_id=parent_org,
+            request_organization_id=audit_organization_id,
+            what=f"update_credential_attachment_metadata(attachment_id={attachment_id})",
+        ),
         metadata={
             "credential_item_id": str(raw["credential_item_id"]),
             "attachment_id": attachment_id,
@@ -257,9 +288,11 @@ async def replace_credential_attachment(
     media_type: str | None,
     content: bytes,
     actor_id: str | None = None,
+    audit_organization_id: str | None = None,
 ) -> CredentialAttachmentRow:
     """Atomically replace the encrypted bytes and file metadata."""
     raw = await _require_raw(attachment_id)
+    parent_org = await _parent_item_organization(str(raw["credential_item_id"]))
     _validate_content(content)
     clean_name = _validate_text(file_name, name="file_name", maximum=512)
     await CredentialAttachment.update_where(
@@ -274,6 +307,11 @@ async def replace_credential_attachment(
     await record_secret_audit(
         action="attachment_replaced",
         actor_id=actor_id,
+        organization_id=audit_organization(
+            record_organization_id=parent_org,
+            request_organization_id=audit_organization_id,
+            what=f"replace_credential_attachment(attachment_id={attachment_id})",
+        ),
         metadata={
             "credential_item_id": str(raw["credential_item_id"]),
             "attachment_id": attachment_id,
@@ -287,8 +325,14 @@ async def replace_credential_attachment(
     return row
 
 
-async def delete_credential_attachment(attachment_id: str, *, actor_id: str | None = None) -> bool:
+async def delete_credential_attachment(
+    attachment_id: str,
+    *,
+    actor_id: str | None = None,
+    audit_organization_id: str | None = None,
+) -> bool:
     raw = await _require_raw(attachment_id)
+    parent_org = await _parent_item_organization(str(raw["credential_item_id"]))
     now = datetime.now(UTC)
     result = await CredentialAttachment.update_where(
         {"id": attachment_id, "deleted_at__isnull": True},
@@ -300,6 +344,11 @@ async def delete_credential_attachment(attachment_id: str, *, actor_id: str | No
         await record_secret_audit(
             action="attachment_deleted",
             actor_id=actor_id,
+            organization_id=audit_organization(
+                record_organization_id=parent_org,
+                request_organization_id=audit_organization_id,
+                what=f"delete_credential_attachment(attachment_id={attachment_id})",
+            ),
             metadata={
                 "credential_item_id": str(raw["credential_item_id"]),
                 "attachment_id": attachment_id,
@@ -310,14 +359,23 @@ async def delete_credential_attachment(attachment_id: str, *, actor_id: str | No
 
 
 async def reveal_credential_attachment(
-    attachment_id: str, *, actor_id: str | None = None
+    attachment_id: str,
+    *,
+    actor_id: str | None = None,
+    audit_organization_id: str | None = None,
 ) -> tuple[CredentialAttachmentRow, bytes]:
     """Human download path. Sealed bytes are structurally refused."""
     raw = await _require_raw(attachment_id)
+    parent_org = await _parent_item_organization(str(raw["credential_item_id"]))
     if str(raw["handling"]) == "sealed":
         await record_secret_audit(
             action="attachment_download_denied",
             actor_id=actor_id,
+            organization_id=audit_organization(
+                record_organization_id=parent_org,
+                request_organization_id=audit_organization_id,
+                what=f"reveal_credential_attachment(attachment_id={attachment_id})",
+            ),
             metadata={
                 "credential_item_id": str(raw["credential_item_id"]),
                 "attachment_id": attachment_id,
@@ -337,6 +395,11 @@ async def reveal_credential_attachment(
     await record_secret_audit(
         action="attachment_downloaded",
         actor_id=actor_id,
+        organization_id=audit_organization(
+            record_organization_id=parent_org,
+            request_organization_id=audit_organization_id,
+            what=f"reveal_credential_attachment(attachment_id={attachment_id})",
+        ),
         metadata={
             "credential_item_id": str(raw["credential_item_id"]),
             "attachment_id": attachment_id,

{matrx_orm-3.1.164 → matrx_orm-3.1.166}/matrx_orm/secrets_battery/host_authorization.py

@@ -131,6 +131,7 @@ async def require_host_authorization(
     *,
     capability: str,
     operation: str,
+    audit_organization_id: str | None = None,
 ) -> None:
     """Refuse a privileged write unless the host recorded ``capability`` for
     this (item, actor). Screams and writes a durable ``denied`` audit row
@@ -149,12 +150,24 @@ async def require_host_authorization(
         capability,
         sorted(caps) or "nothing",
     )
-    from .org_service import record_secret_audit
+    from .model import CredentialItem
+    from .org_service import audit_organization, record_secret_audit
 
     try:
+        # The denial row is a child of the ITEM, so it is filed in the item's
+        # organization; a PERSONAL item names none by constraint and the host's
+        # request organization answers for it.
+        item_rows = await CredentialItem.filter(id=item_id).values("organization_id")
         await record_secret_audit(
             action="denied",
             actor_id=actor_id,
+            organization_id=audit_organization(
+                record_organization_id=(
+                    item_rows[0].get("organization_id") if item_rows else None
+                ),
+                request_organization_id=audit_organization_id,
+                what=f"require_host_authorization(item_id={item_id})",
+            ),
             metadata={
                 "credential_item_id": str(item_id),
                 "operation": operation,