matrx-orm 3.1.119__tar.gz → 3.1.121__tar.gz

{matrx_orm-3.1.119 → matrx_orm-3.1.121}/.gitignore

@@ -293,5 +293,5 @@ apps/shared/matrx-agents/*.tgz
 # the real tree the guard scans (a temp dir would prove nothing) and delete
 # them in teardown — ignoring them keeps the auto-commit tooling from
 # capturing one mid-run.
-_kind_boundary_scratch/
-_kind_marker_law_scratch/
+_kind_boundary_scratch*/
+_kind_marker_law_scratch*/

{matrx_orm-3.1.119 → matrx_orm-3.1.121}/PKG-INFO

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

@@ -74,6 +74,15 @@ connection and can strand old holders in release/reset.
 
 Pinned by `tests/level1/test_pool_maintenance.py`.
 
+**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
+`AsyncDatabaseManager.get_connection`. No caller SQL was sent, so an explicitly
+replay-safe owner can use `retry_on_transient`; the failure never falls through
+as an unrelated `CacheError`.
+
+Pinned by `tests/level1/test_pool_maintenance.py`.
+
 **Every checkout is attributable.** `AsyncDatabaseManager.get_connection` and
 the sanctioned caller-supplied-pool helper register the holder's asyncio task,
 checkout call site/stack, current suspended call site/stack, and age. On the
@@ -177,6 +186,8 @@ can never disagree about who the blocker was.
 Verified against the live database: 2026-08-21.
 
 ## Change log
+- 2026-08-30: Classified server restart/failover rejection during pool checkout
+  as retryable connection failure before any caller SQL is sent.
 - 2026-08-24: Recovered read-only disconnects masked by empty-read reproof's
   transaction teardown, while preserving diagnostic handling for unrelated
   interface errors.

{matrx_orm-3.1.119 → matrx_orm-3.1.121}/matrx_orm/core/async_db_manager.py

@@ -71,6 +71,15 @@ _SCHEMA_MISMATCH_EXC = (
     asyncpg.exceptions.InvalidSchemaNameError,
 )
 
+# PostgreSQL emits these SQLSTATE class-57 errors while asyncpg is opening a
+# physical connection during a server restart/failover.  They happen before a
+# checkout exists, so no caller SQL was sent and a replay-safe owner may retry.
+_ACQUIRE_SERVER_TRANSIENT_EXC = (
+    asyncpg.exceptions.AdminShutdownError,
+    asyncpg.exceptions.CrashShutdownError,
+    asyncpg.exceptions.CannotConnectNowError,
+)
+
 
 def _integrity_constraint_kind(exc: asyncpg.exceptions.IntegrityConstraintViolationError) -> str:
     if isinstance(exc, asyncpg.exceptions.CheckViolationError):
@@ -822,6 +831,22 @@ class AsyncDatabaseManager:
                     async with asyncio.timeout(timeout):
                         conn = await cls._acquire_bounded_growth(config_name, pool)
                     break
+                except asyncpg.exceptions.AdminShutdownError as exc:
+                    # Caught before a connection reaches the caller: no SQL was sent.
+                    if _acquire_attempt >= POOL_ACQUIRE_RETRIES:
+                        raise
+                    backoff = POOL_ACQUIRE_RETRY_BASE_BACKOFF * (2**_acquire_attempt)
+                    logger.warning(
+                        "[matrx_orm] PostgreSQL administrator shutdown while acquiring "
+                        "'%s' (attempt %d/%d) — retrying in %.2fs (no SQL sent, safe): %s",
+                        config_name,
+                        _acquire_attempt + 1,
+                        1 + POOL_ACQUIRE_RETRIES,
+                        backoff,
+                        type(exc).__name__,
+                    )
+                    await asyncio.sleep(backoff)
+                    continue
                 except TimeoutError:
                     from matrx_orm.core.pool_watch import emit_first_pool_timeout
 
@@ -961,6 +986,16 @@ class AsyncDatabaseManager:
                     timeout=timeout,
                 ):
                     raise _timeout_err from None
+        except _ACQUIRE_SERVER_TRANSIENT_EXC as e:
+            # A server restart can reject asyncpg's lazy replacement handshake
+            # from inside pool.acquire(). Classify it at the checkout boundary;
+            # otherwise handle_orm_operation wraps it as CacheError and hides
+            # the transient connection identity from retry_on_transient.
+            raise ConnectionError(
+                model=None,
+                db_url=config_name,
+                original_error=e,
+            ) from e
         except asyncpg.exceptions.InterfaceError as e:
             async with handle_orm_operation(
                 operation_name="acquire_connection",

{matrx_orm-3.1.119 → matrx_orm-3.1.121}/matrx_orm/core/base.py

@@ -923,14 +923,20 @@ class Model(RuntimeMixin, metaclass=ModelMeta):
         )
 
     @classmethod
-    async def count(cls, **kwargs: Any) -> int:
+    async def count(cls, *, include_pending: bool = True, **kwargs: Any) -> int:
         """Lightweight row count without full model hydration.
 
         Usage:
             total = await MyModel.count()
             active = await MyModel.count(status="active")
+
+        Pass ``include_pending=False`` for persisted-state telemetry and
+        inventory reads that must remain a database aggregate inside a
+        request Session with queued writes.
         """
-        return await QueryBuilder(cls).filter(**kwargs).count()
+        return await QueryBuilder(cls).filter(**kwargs).count(
+            include_pending=include_pending
+        )
 
     @classmethod
     def count_sync(cls, **kwargs: Any) -> int:

{matrx_orm-3.1.119 → matrx_orm-3.1.121}/matrx_orm/query/FEATURE.md

@@ -44,8 +44,18 @@ explicit `.values(...)` projects the grouped columns plus its aggregate
 expressions. These shapes keep every generated aggregate valid in PostgreSQL
 without forcing callers to add a redundant projection.
 
+## Persisted-state counts
+
+`count()` remains session-aware by default: when the active Session stack has
+pending writes for the model, it merges those writes so business decisions see
+read-your-own-writes state. Telemetry and inventory callers that explicitly
+want persisted database state call `count(include_pending=False)`. That opt-out
+always uses the database aggregate and never hydrates or serializes every
+matching model merely because a request Coordinator has queued a write.
+
 ## Change log
 
+- 2026-08-28 — Added persisted-state counts that bypass pending-row hydration.
 - 2026-08-18 — Moved async terminal SQL compilation off the event loop.
 - 2026-08-15 — Moved bulk hydration off the event loop, made complete-primary-key
   misses constant-time, and documented cache bypass for request-local scans.

{matrx_orm-3.1.119 → matrx_orm-3.1.121}/matrx_orm/query/builder.py

@@ -953,15 +953,19 @@ class QueryBuilder(Generic[ModelT]):
             return False
         return has_pending_in_stack(self.model)
 
-    async def count(self) -> int:
+    async def count(self, *, include_pending: bool = True) -> int:
         """Count matching records.
 
         Session-aware: when the Session stack has pending writes for this
         Model, count() reflects the merged (DB + pending) result so a nested
-        Session never under/over-counts rows an ancestor queued.
+        Session never under/over-counts rows an ancestor queued. Callers doing
+        telemetry or inventory over persisted state may pass
+        ``include_pending=False`` to keep the database aggregate path even
+        when the request Session has queued writes; this avoids hydrating and
+        serializing an arbitrarily large table just to obtain its row count.
         """
         try:
-            if self._stack_has_pending():
+            if include_pending and self._stack_has_pending():
                 return len(await self.all())
             executor = await self._get_executor_async()
             return await executor.count()

{matrx_orm-3.1.119 → matrx_orm-3.1.121}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.119"
+version = "3.1.121"
 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.121/tests/level1/test_persisted_count.py

@@ -0,0 +1,33 @@
+"""Persisted counts stay aggregate-only inside a pending-write Session."""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock
+
+import pytest
+
+from matrx_orm.query.builder import QueryBuilder
+
+
+@pytest.mark.asyncio
+async def test_count_can_bypass_pending_model_hydration(monkeypatch):
+    builder = QueryBuilder(AsyncMock())
+    executor = AsyncMock()
+    executor.count.return_value = 41
+    monkeypatch.setattr(builder, "_stack_has_pending", lambda: True)
+    monkeypatch.setattr(builder, "_get_executor_async", AsyncMock(return_value=executor))
+    all_rows = AsyncMock(return_value=[object()] * 1000)
+    monkeypatch.setattr(builder, "all", all_rows)
+
+    assert await builder.count(include_pending=False) == 41
+    executor.count.assert_awaited_once_with()
+    all_rows.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_count_preserves_read_your_own_writes_by_default(monkeypatch):
+    builder = QueryBuilder(AsyncMock())
+    monkeypatch.setattr(builder, "_stack_has_pending", lambda: True)
+    monkeypatch.setattr(builder, "all", AsyncMock(return_value=[object(), object()]))
+
+    assert await builder.count() == 2

{matrx_orm-3.1.119 → matrx_orm-3.1.121}/tests/level1/test_pool_maintenance.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import asyncio
 
+import asyncpg
 import pytest
 from matrx_orm.core.async_db_manager import AsyncDatabaseManager
 from matrx_orm.core.pool_maintenance import (
@@ -9,6 +10,7 @@ from matrx_orm.core.pool_maintenance import (
     acquire_connected_holder,
     maintain_one_connection,
 )
+from matrx_orm.exceptions import ConnectionError as OrmConnectionError
 
 
 class FakeProxy:
@@ -85,6 +87,33 @@ class FakePool:
         self._queue.put_nowait(proxy.holder)
 
 
+@pytest.mark.asyncio
+async def test_get_connection_classifies_admin_shutdown_during_acquire(monkeypatch) -> None:
+    class RestartingPool:
+        async def acquire(self) -> None:
+            raise asyncpg.exceptions.AdminShutdownError(
+                "terminating connection due to administrator command"
+            )
+
+    config_name = "restart-handshake"
+    pool = RestartingPool()
+
+    async def fake_get_pool(cls: type[AsyncDatabaseManager], name: str) -> object:
+        return pool
+
+    monkeypatch.setattr(
+        AsyncDatabaseManager,
+        "get_pool",
+        classmethod(fake_get_pool),
+    )
+
+    with pytest.raises(OrmConnectionError) as caught:
+        async with AsyncDatabaseManager.get_connection(config_name, timeout=0.01):
+            pass
+
+    assert isinstance(caught.value.__cause__, asyncpg.exceptions.AdminShutdownError)
+    assert "administrator command" in str(caught.value)
+
 @pytest.mark.asyncio
 async def test_maintenance_grows_exactly_one_disconnected_holder() -> None:
     pool = FakePool(connected=7, maximum=20)