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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matrx-orm
-Version: 3.1.165
+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.165 → 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.165 → 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.165 → 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.165 → matrx_orm-3.1.166}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.165"
+version = "3.1.166"
 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.165 → matrx_orm-3.1.166}/tests/level1/test_pool_holder_census.py

@@ -1,13 +1,16 @@
 from __future__ import annotations
 
 import asyncio
+from types import SimpleNamespace
 from typing import Any
 
 import pytest
 
 import matrx_orm.core.async_db_manager as manager_module
+import matrx_orm.core.pool_watch as pool_watch
 from matrx_orm.core.async_db_manager import AsyncDatabaseManager
 from matrx_orm.core.pool_watch import (
+    PoolHolderProvenance,
     PoolSaturationEvent,
     emit_first_pool_timeout,
     note_pool_recovered,
@@ -47,6 +50,16 @@ class _OneSlotPool:
         return 1
 
 
+def test_holder_provenance_refuses_unbounded_text() -> None:
+    provenance = PoolHolderProvenance(
+        request_id="request-ok",
+        source_feature="not safe; contains request payload",
+    )
+
+    assert provenance.request_id == "request-ok"
+    assert provenance.source_feature is None
+
+
 @pytest.mark.asyncio
 async def test_first_acquire_timeout_names_deliberate_long_holder(monkeypatch: Any) -> None:
     """Reproduce the wedge: a holder waits forever while the next acquire times out."""
@@ -81,6 +94,19 @@ async def test_first_acquire_timeout_names_deliberate_long_holder(monkeypatch: A
     monkeypatch.setattr(manager_module, "resolve_database_name", lambda name: name)
     monkeypatch.setattr(manager_module, "get_database_config", lambda _name: {"pool_min": 1})
     monkeypatch.setattr(manager_module, "POOL_ACQUIRE_RETRIES", 0)
+    monkeypatch.setattr(
+        pool_watch,
+        "get_active_context",
+        lambda: SimpleNamespace(
+            request_id="req-opaque-exists",
+            source_app="aidream-api",
+            source_feature="opaque-exists-probe",
+            origin_class="api",
+            execution_kind=None,
+            execution_id=None,
+            metadata={"never": "captured"},
+        ),
+    )
 
     async def deliberate_long_holder() -> None:
         async with AsyncDatabaseManager.get_connection("repro", timeout=0.01):
@@ -102,6 +128,9 @@ async def test_first_acquire_timeout_names_deliberate_long_holder(monkeypatch: A
         holder = event.holders[0]
         assert holder.task_name == "deliberate-long-holder"
         assert "deliberate_long_holder" in holder.checkout_site
+        assert holder.provenance.request_id == "req-opaque-exists"
+        assert holder.provenance.source_feature == "opaque-exists-probe"
+        assert holder.provenance.origin_class == "api"
         assert holder.current_site is not None
         assert "deliberate_long_holder" in holder.current_site
         assert holder.age_seconds >= 0.0