matrx-orm 3.1.112__tar.gz → 3.1.114__tar.gz

{matrx_orm-3.1.112 → matrx_orm-3.1.114}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matrx-orm
-Version: 3.1.112
+Version: 3.1.114
 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
@@ -25,7 +25,7 @@ Requires-Python: >=3.13
 Requires-Dist: asyncpg>=0.31.0
 Requires-Dist: cryptography>=43.0
 Requires-Dist: gitpython>=3.1.40
-Requires-Dist: matrx-utils>=2.0.27
+Requires-Dist: matrx-utils>=2.0.28
 Requires-Dist: psycopg-pool>=3.2.5
 Requires-Dist: psycopg[binary]>=3.2.5
 Requires-Dist: python-dotenv>=1.0

{matrx_orm-3.1.112 → matrx_orm-3.1.114}/matrx_orm/FEATURE.md

@@ -34,10 +34,22 @@
 
 - Runtime hierarchy and formatting: `exceptions.py`
 - Failure capture + org stamping: `session/fallback.py`
-- Focused unit coverage: `tests/level1/test_exceptions.py`
+- Watched-lifecycle recovery: `session/lifecycle.py`
+- Focused unit coverage: `tests/level1/test_exceptions.py`,
+  `tests/level1/test_watched_lifecycle.py`
+
+## Watchdog reads use the resilient SELECT boundary
+
+- **Lifecycle SELECTs call `adapter.execute_query`.** They inherit the ORM's
+  bounded retry for one transient command timeout on a fresh connection.
+- **Raw borrowed-connection reads are forbidden here.** A direct `conn.fetch`
+  bypasses read recovery and turns a healthy table's transient timeout into a
+  `lifecycle_watchdog_query_failure`.
 
 ## Change Log
 
+- 2026-08-26 — Routed watched-lifecycle SELECTs through the resilient adapter
+  read boundary so one transient command timeout retries on a fresh connection.
 - 2026-08-24 — Lifecycle watchdog ERROR boundaries now call `record_error` so
   stuck rows plus SELECT/transition failures reach `ops.system_error` instead
   of existing only in `app_log`.

{matrx_orm-3.1.112 → matrx_orm-3.1.114}/matrx_orm/session/lifecycle.py

@@ -415,8 +415,11 @@ async def _fetch_stuck_rows(
 
     adapter = AdapterRegistry.get(database)
     sql, params = _build_select_query(cfg, limit)
-    async with adapter.get_connection() as conn:
-        return await conn.fetch(sql, *params)
+    # Route watchdog reads through the adapter's normal SELECT boundary. That
+    # path retries one transient command timeout on a fresh connection; using
+    # a raw borrowed connection here bypassed that recovery and emitted a
+    # lifecycle_watchdog_query_failure for an otherwise healthy table.
+    return await adapter.execute_query(sql, *params)
 
 
 async def _transition_stuck_row(

{matrx_orm-3.1.112 → matrx_orm-3.1.114}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.112"
+version = "3.1.114"
 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.27",
+    "matrx-utils>=2.0.28",
     "pyyaml>=6.0.3",
     "python-dotenv>=1.0",
     "cryptography>=43.0",

{matrx_orm-3.1.112 → matrx_orm-3.1.114}/tests/level1/test_watched_lifecycle.py

@@ -138,6 +138,37 @@ async def test_timeout_update_stamps_extra_fields(captured_update):
     )
 
 
+@pytest.mark.asyncio
+async def test_stuck_row_select_uses_resilient_adapter_read(monkeypatch):
+    captured: dict[str, object] = {}
+
+    class _Adapter:
+        async def execute_query(self, sql, *params):
+            captured["sql"] = sql
+            captured["params"] = params
+            return [{"pk": "call-1", "aged": lc.datetime.now(lc.UTC)}]
+
+        def get_connection(self):
+            raise AssertionError("watchdog SELECT bypassed the resilient read boundary")
+
+    fake_adapters = types.ModuleType("matrx_orm.adapters")
+    fake_adapters.AdapterRegistry = types.SimpleNamespace(get=lambda db: _Adapter())
+    monkeypatch.setitem(sys.modules, "matrx_orm.adapters", fake_adapters)
+
+    cfg = lc.WatchedLifecycleConfig(
+        schema="chat",
+        table="tool_call",
+        predicate=ArrayAny(F("status"), ["pending", "running"]),
+        max_age_secs=1800,
+    )
+
+    rows = await lc._fetch_stuck_rows(cfg, "matrx", 500)
+
+    assert rows[0]["pk"] == "call-1"
+    assert "FROM chat.tool_call" in str(captured["sql"])
+    assert captured["params"] == (["pending", "running"], 1800)
+
+
 @pytest.mark.asyncio
 async def test_extra_fields_only_without_status_transition(captured_update):
     cfg = lc.WatchedLifecycleConfig(