matrx-orm 3.1.197__tar.gz → 3.1.199__tar.gz

{matrx_orm-3.1.197 → matrx_orm-3.1.199}/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+- **Fix: a driver timeout longer than the server's statement ceiling screams.**
+  `call_function` / `call_function_as` / `execute_query` read the connection's
+  effective `statement_timeout` and log one WARNING per call site when the
+  `timeout=` passed is longer (Postgres cancels at the ceiling regardless). New
+  `SERVER_CEILING` sentinel: `timeout=SERVER_CEILING` waits the connection's
+  ceiling + 1 s. Guard: `tests/test_statement_ceiling_warning.py`.
 - **Fix (security): the by-id cache never answers inside `rls_session`.** The
   StateManager cache is shared process-wide and keyed by primary key alone, so a
   row fetched for one person (or the privileged process) was served to another

{matrx_orm-3.1.197 → matrx_orm-3.1.199}/PKG-INFO

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

@@ -31,6 +31,7 @@ from .core.config import (
     resolve_pool_mode,
 )
 from .core.db_function import ArrayArg, TypedArg, call_function, call_function_as, call_function_sync
+from .core.statement_ceiling import SERVER_CEILING
 from .core.connections import (
     create_external_pool,
     get_registered_pool,
@@ -472,6 +473,7 @@ __all__ = [
     "install_asyncpg_idle_close_filter",
     # ── DB-side function calls (RPC) ──────────────────────────────────────────
     "call_function",
+    "SERVER_CEILING",
     "call_function_as",
     "call_function_sync",
     "MatrxEntity",

{matrx_orm-3.1.197 → matrx_orm-3.1.199}/matrx_orm/core/FEATURE.md

@@ -126,6 +126,16 @@ for scalar, row-set, discarded-result, and active-transaction calls. Callers can
 therefore distinguish an ambiguous in-flight RPC from a pool-acquire failure and
 must choose replay policy explicitly.
 
+**A driver `timeout=` never outlives the server's statement ceiling silently.**
+`call_function(..., timeout=N)` / `call_function_as` / `execute_query(statement_timeout=N)`
+set only asyncpg's wait; Postgres still cancels at the connection's `statement_timeout`
+(the `postgres` role carries 30 s since aidream migration 0919, or a `SET LOCAL` from
+`rls_session`). `core/statement_ceiling.py` reads that ceiling from the connection
+(`pg_settings`, once per database for pool connections, live inside a transaction) and
+logs one WARNING per call site when N exceeds it. `timeout=SERVER_CEILING` resolves to
+the ceiling + 1 s, for a bounded statement that needs more than the pool's 10 s default.
+Static twin: aidream `scripts/check_driver_timeout_vs_statement_ceiling.py`.
+
 **Opt-in transient retries can be bounded and desynchronized.**
 `retry_on_transient(..., jitter_ratio=...)` retains deterministic exponential
 backoff by default; a caller recovering a replay-safe lock conflict can add at
@@ -329,6 +339,7 @@ can never disagree about who the blocker was.
 Verified against the live database: 2026-08-21.
 
 ## Change log
+- 2026-09-30: `statement_ceiling.py` — a driver timeout above the server's statement ceiling is logged once per call site; `SERVER_CEILING` sentinel. ~19 callers passed 60-600 s under the 30 s `postgres` ceiling (the nightly keyword classifier was cancelled at 30 s for eight days).
 - 2026-09-12 (later): ONE retry mechanism. Two independent lock-retry
   implementations for the same class landed hours apart — a `LockContentionError`
   + constant-budget loop inside `execute_query`, and a `TransientTransactionError`

{matrx_orm-3.1.197 → matrx_orm-3.1.199}/matrx_orm/core/async_db_manager.py

@@ -24,6 +24,7 @@ from matrx_orm.core.pooler_role import (
     assert_no_session_role_change,
     reprove_empty_read,
 )
+from matrx_orm.core.statement_ceiling import resolve_driver_timeout
 from matrx_orm.core.tls import resolve_asyncpg_ssl
 from matrx_orm.exceptions import (
     AdapterError,
@@ -1286,7 +1287,9 @@ class AsyncDatabaseManager:
         per-call ``fetch(..., timeout=)`` and overrides the pool's
         ``command_timeout`` for this statement only — the QueryBuilder
         ``.timeout()`` seam for known-long reads. ``None`` keeps the pool
-        default.
+        default. It is a DRIVER timeout: the server's own statement_timeout
+        still cancels at its ceiling, and a value above it is logged once per
+        call site (``matrx_orm.core.statement_ceiling``).
         """
         # Layer 1 of the pooler-role defence: SQL that would leave a borrowed role
         # on a shared server connection never reaches Postgres. See
@@ -1302,6 +1305,13 @@ class AsyncDatabaseManager:
             tx_conn = None
 
         if tx_conn is not None:
+            statement_timeout = await resolve_driver_timeout(
+                tx_conn,
+                database=config_name,
+                timeout=statement_timeout,
+                operation="execute_query",
+                in_transaction=True,
+            )
             try:
                 results = await tx_conn.fetch(query, *args, timeout=statement_timeout)
                 return [dict(r) for r in results]
@@ -1411,8 +1421,15 @@ class AsyncDatabaseManager:
             read_attempt = 0
             while True:
                 async with cls.get_connection(config_name, timeout) as conn:
+                    driver_timeout = await resolve_driver_timeout(
+                        conn,
+                        database=config_name,
+                        timeout=statement_timeout,
+                        operation="execute_query",
+                        in_transaction=False,
+                    )
                     try:
-                        results = await conn.fetch(query, *args, timeout=statement_timeout)
+                        results = await conn.fetch(query, *args, timeout=driver_timeout)
                         if read_attempt > 0:
                             logger.warning(
                                 "[read-retry] SELECT HEALED on attempt %d after a "
@@ -1435,7 +1452,7 @@ class AsyncDatabaseManager:
                                 config_name=config_name,
                                 query=query,
                                 args=args,
-                                statement_timeout=statement_timeout,
+                                statement_timeout=driver_timeout,
                                 normalize=_normalize_record,
                             )
                             if true_rows is not None:

{matrx_orm-3.1.197 → matrx_orm-3.1.199}/matrx_orm/core/db_function.py

@@ -69,6 +69,7 @@ from dataclasses import dataclass
 from typing import Any, Literal
 
 from matrx_orm.core.async_db_manager import AsyncDatabaseManager
+from matrx_orm.core.statement_ceiling import DriverTimeout, resolve_driver_timeout
 from matrx_orm.core.transaction import get_active_connection
 from matrx_orm.core.write_retry import (
     is_confidently_aborted_lock_contention,
@@ -191,14 +192,14 @@ def _validate_identifier(name: str, kind: str) -> None:
         )
 
 
-async def call_function(  # noqa: ASYNC109 — maps onto asyncpg's per-call timeout
+async def call_function(
     database: str,
     schema: str,
     function: str,
     *args: Any,
     mode: Literal["scalar", "none", "rows"] = "scalar",
     field: str | None = None,
-    timeout: float | None = None,
+    timeout: DriverTimeout = None,  # noqa: ASYNC109 — maps onto asyncpg's per-call timeout
 ) -> Any:
     """Call ``schema.function(args...)`` and return its value.
 
@@ -222,9 +223,15 @@ async def call_function(  # noqa: ASYNC109 — maps onto asyncpg's per-call time
         timeout: per-call driver timeout in seconds, overriding the pool's
             ``command_timeout`` (default 10s). Use for known-slow analytical
             functions (aggregation RPCs) that legitimately exceed the pool
-            default; ``None`` keeps the pool's setting. A server-side
-            ``statement_timeout`` (e.g. from ``rls_session``) still applies
-            independently.
+            default; ``None`` keeps the pool's setting. It does NOT lengthen
+            the server's ``statement_timeout`` (the role default — 30 s for
+            ``postgres`` since aidream migration 0919 — or a ``SET LOCAL`` from
+            ``rls_session``): Postgres still cancels at that ceiling, and a
+            timeout above it is logged once per call site as a WARNING
+            (``matrx_orm.core.statement_ceiling``). Pass
+            ``timeout=SERVER_CEILING`` for a bounded statement that needs more
+            than the pool default: it waits exactly as long as the server
+            allows, read from the connection.
 
     Returns:
         The scalar value (mode="scalar"), ``None`` (mode="none"), or
@@ -257,21 +264,28 @@ async def call_function(  # noqa: ASYNC109 — maps onto asyncpg's per-call time
     else:
         sql = f"SELECT {call}"
 
-    async def invoke(conn: Any) -> Any:
+    async def invoke(conn: Any, *, in_transaction: bool = False) -> Any:
+        driver_timeout = await resolve_driver_timeout(
+            conn,
+            database=database,
+            timeout=timeout,
+            operation=f"call_function {schema}.{function}",
+            in_transaction=in_transaction,
+        )
         try:
             if mode == "none":
-                await conn.execute(sql, *bound_args, timeout=timeout)
+                await conn.execute(sql, *bound_args, timeout=driver_timeout)
                 return None
             if mode == "rows":
-                rows = await conn.fetch(sql, *bound_args, timeout=timeout)
+                rows = await conn.fetch(sql, *bound_args, timeout=driver_timeout)
                 return [dict(r) for r in rows]
-            return await conn.fetchval(sql, *bound_args, timeout=timeout)
+            return await conn.fetchval(sql, *bound_args, timeout=driver_timeout)
         except TimeoutError as exc:
             raise QueryTimeoutError(
                 operation=f"call_function:{schema}.{function}",
                 query=sql,
                 args=bound_args,
-                timeout=timeout,
+                timeout=driver_timeout,
                 original_error=exc,
             ) from None
 
@@ -281,7 +295,7 @@ async def call_function(  # noqa: ASYNC109 — maps onto asyncpg's per-call time
         # transaction's owner can redo the unit, so no retry here — the refusal is
         # typed the same way ``execute_query``'s transaction branch types it.
         try:
-            return await invoke(active_conn)
+            return await invoke(active_conn, in_transaction=True)
         except Exception as exc:
             if not is_confidently_aborted_lock_contention(exc):
                 raise
@@ -306,14 +320,14 @@ async def call_function(  # noqa: ASYNC109 — maps onto asyncpg's per-call time
     )
 
 
-async def call_function_as(  # noqa: ASYNC109 — maps onto asyncpg's per-call timeout
+async def call_function_as(
     actor_id: str,
     database: str,
     schema: str,
     function: str,
     *args: Any,
     mode: Literal["scalar", "none", "rows"] = "scalar",
-    timeout: float | None = None,
+    timeout: DriverTimeout = None,  # noqa: ASYNC109 — maps onto asyncpg's per-call timeout
 ) -> Any:
     """Call ``schema.function(args...)`` on the server connection AS ``actor_id``.
 
@@ -354,13 +368,20 @@ async def call_function_as(  # noqa: ASYNC109 — maps onto asyncpg's per-call t
 
     async def _attempt() -> Any:
         async with AsyncDatabaseManager.get_connection(database) as conn:
+            driver_timeout = await resolve_driver_timeout(
+                conn,
+                database=database,
+                timeout=timeout,
+                operation=f"call_function_as {schema}.{function}",
+                in_transaction=False,
+            )
             if mode == "none":
-                await conn.execute(sql, *bound_args, timeout=timeout)
+                await conn.execute(sql, *bound_args, timeout=driver_timeout)
                 return None
             if mode == "rows":
-                rows = await conn.fetch(sql, *bound_args, timeout=timeout)
+                rows = await conn.fetch(sql, *bound_args, timeout=driver_timeout)
                 return [dict(r) for r in rows]
-            return await conn.fetchval(sql, *bound_args, timeout=timeout)
+            return await conn.fetchval(sql, *bound_args, timeout=driver_timeout)
 
     return await run_with_lock_retry(_attempt, config_name=database, query=sql, args=bound_args)
 
@@ -372,7 +393,7 @@ def call_function_sync(
     *args: Any,
     mode: Literal["scalar", "none", "rows"] = "scalar",
     field: str | None = None,
-    timeout: float | None = None,
+    timeout: DriverTimeout = None,
 ) -> Any:
     """Synchronous twin of :func:`call_function`. Sync contexts only."""
     import asyncio

matrx_orm-3.1.199/matrx_orm/core/statement_ceiling.py

@@ -0,0 +1,170 @@
+"""A driver ``timeout=`` longer than the server's statement ceiling is a lie — say so.
+
+``call_function(..., timeout=300)`` and ``execute_query(..., statement_timeout=300)`` set
+the DRIVER's (asyncpg's) per-call timeout. They do not, and cannot, lengthen the
+server's own ``statement_timeout``: that comes from the connecting role's default
+(``ALTER ROLE … SET statement_timeout``), the pool's server settings, or a
+``SET [LOCAL] statement_timeout`` issued as its own statement before the call
+(``rls_session`` / ``acting_as_user(statement_timeout_ms=…)``). When the driver
+timeout is the longer of the two, the caller believes it has minutes and Postgres
+cancels it at the ceiling (``57014 canceling statement due to statement timeout``).
+
+That is what froze the approved nightly keyword classifier for eight days in
+September 2026: aidream migration 0919 capped the ``postgres`` role at 30 s on
+purpose, and a job that passed ``timeout=300`` for a 55–128 s statement was cut at
+30 s every night.
+
+This module reads the ceiling from its one source of truth — the connection's own
+effective ``statement_timeout`` (``pg_settings.setting``, milliseconds), which already
+folds in the role default, the pool settings and any ``SET LOCAL`` — and logs a
+WARNING, once per call site, when the driver timeout exceeds it. It never blocks the
+call: the statement still runs exactly as before. The static twin is
+``aidream/scripts/check_driver_timeout_vs_statement_ceiling.py``.
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+from typing import Any
+
+logger = logging.getLogger("matrx_orm.statement_ceiling")
+
+_CEILING_SQL = "SELECT setting::bigint FROM pg_settings WHERE name = 'statement_timeout'"
+
+#: Pool connections share one effective ceiling per database (role default + pool
+#: settings), so it is read once per database. A transaction connection may carry a
+#: ``SET LOCAL``, so it is always read live.
+_POOL_CEILING_MS: dict[str, int] = {}
+_WARNED: set[tuple[str, str, int]] = set()
+_UNREADABLE_WARNED: set[str] = set()
+
+_ORM_PACKAGE_MARKER = "/matrx_orm/"
+
+
+def _caller_site() -> str:
+    """The first frame outside matrx_orm — the code that chose the timeout."""
+    frame = sys._getframe(1)
+    while frame is not None:
+        filename = frame.f_code.co_filename
+        if _ORM_PACKAGE_MARKER not in filename.replace("\\", "/") and "/asyncio/" not in filename:
+            return f"{filename}:{frame.f_lineno} ({frame.f_code.co_name})"
+        frame = frame.f_back
+    return "<unknown caller>"
+
+
+async def _read_ceiling_ms(conn: Any, *, database: str, in_transaction: bool) -> int | None:
+    if not in_transaction and database in _POOL_CEILING_MS:
+        return _POOL_CEILING_MS[database]
+    try:
+        value = await conn.fetchval(_CEILING_SQL)
+        ceiling_ms = int(value)
+    except Exception as exc:  # noqa: BLE001 — the check must never break the call it guards
+        if database not in _UNREADABLE_WARNED:
+            _UNREADABLE_WARNED.add(database)
+            logger.warning(
+                "[matrx-orm] statement-ceiling check could not read statement_timeout on %r "
+                "(%s: %s); driver timeouts on this database are unchecked until it can. "
+                "Remedy: make pg_settings readable to the pool role.",
+                database,
+                type(exc).__name__,
+                exc,
+            )
+        return None
+    if not in_transaction:
+        _POOL_CEILING_MS[database] = ceiling_ms
+    return ceiling_ms
+
+
+class ServerCeiling:
+    """Sentinel for ``timeout=``: wait exactly as long as the server itself allows.
+
+    For a statement that legitimately needs more than the pool's driver default
+    (``command_timeout``, 10 s) but is bounded under the server's ceiling: the driver
+    timeout is resolved per call from the connection's own ``statement_timeout`` plus
+    :data:`SERVER_CEILING_MARGIN_SECONDS`, so Postgres's ``57014`` — the true answer —
+    always arrives before the driver gives up, and no caller carries a second copy of
+    the ceiling as a number.
+    """
+
+    _instance: ServerCeiling | None = None
+
+    def __new__(cls) -> ServerCeiling:
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __repr__(self) -> str:
+        return "SERVER_CEILING"
+
+
+SERVER_CEILING = ServerCeiling()
+
+#: How much longer than the server's ceiling the driver waits under ``SERVER_CEILING``,
+#: so the server's cancellation (with its real error) is what the caller sees.
+SERVER_CEILING_MARGIN_SECONDS = 1.0
+
+DriverTimeout = float | ServerCeiling | None
+
+
+async def resolve_driver_timeout(
+    conn: Any,
+    *,
+    database: str,
+    timeout: DriverTimeout,  # noqa: ASYNC109 — the caller's asyncpg timeout, inspected, never awaited
+    operation: str,
+    in_transaction: bool,
+) -> float | None:
+    """The driver timeout to pass to asyncpg for this call — and a scream when it lies.
+
+    ``SERVER_CEILING`` resolves to the connection's ceiling plus the margin. A number
+    larger than the ceiling is passed through unchanged (the call is never blocked) and
+    logged once per call site as a WARNING naming the caller and the ceiling.
+    """
+    if timeout is None:
+        return None
+    if isinstance(timeout, ServerCeiling):
+        ceiling_ms = await _read_ceiling_ms(conn, database=database, in_transaction=in_transaction)
+        if ceiling_ms is None:
+            return None  # unreadable — already announced by _read_ceiling_ms
+        if ceiling_ms <= 0:
+            key = ("<server-ceiling-unbounded>", database, 0)
+            if key not in _WARNED:
+                _WARNED.add(key)
+                logger.warning(
+                    "[matrx-orm] %s asked for timeout=SERVER_CEILING on %r but this connection has "
+                    "no statement_timeout (0); the pool's driver default applies instead. Remedy: "
+                    "give the role or the session a statement_timeout.",
+                    _caller_site(),
+                    database,
+                )
+            return None
+        return ceiling_ms / 1000 + SERVER_CEILING_MARGIN_SECONDS
+    if timeout <= 0:
+        return timeout
+    ceiling_ms = await _read_ceiling_ms(conn, database=database, in_transaction=in_transaction)
+    if not ceiling_ms or ceiling_ms <= 0:
+        # 0 means Postgres enforces no statement ceiling on this connection.
+        return timeout
+    if timeout * 1000 <= ceiling_ms:
+        return timeout
+    site = _caller_site()
+    key = (site, database, ceiling_ms)
+    if key not in _WARNED:
+        _WARNED.add(key)
+        logger.warning(
+            f"[matrx-orm] DRIVER TIMEOUT OUTLIVES THE SERVER CEILING: {site} passes timeout={timeout:g}s "
+            f"to {operation} on {database!r}, but this connection's statement_timeout is "
+            f"{ceiling_ms / 1000:g}s — Postgres cancels the statement at {ceiling_ms / 1000:g}s "
+            f"(57014) no matter what the driver waits for. Remedy: bound the statement below the "
+            f"ceiling (split it per site/span) and pass timeout=SERVER_CEILING, or declare the "
+            f"server clock with rls_session/acting_as_user(statement_timeout_ms=...)."
+        )
+    return timeout
+
+
+def reset_statement_ceiling_cache() -> None:
+    """Test seam: forget cached ceilings and already-warned call sites."""
+    _POOL_CEILING_MS.clear()
+    _WARNED.clear()
+    _UNREADABLE_WARNED.clear()

{matrx_orm-3.1.197 → matrx_orm-3.1.199}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.197"
+version = "3.1.199"
 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.197 → matrx_orm-3.1.199}/tests/level1/test_call_function.py

@@ -9,7 +9,7 @@ they ever reach a query string; arguments are always bound parameters.
 
 from __future__ import annotations
 
-from unittest.mock import AsyncMock
+from unittest.mock import AsyncMock, call
 
 import pytest
 from matrx_orm.core import transaction as tx_module
@@ -268,11 +268,29 @@ class TestConnectionAndDriverOptions:
         assert pool.databases == ["analytics"]
 
     async def test_per_call_timeout_reaches_the_driver(self, pool) -> None:
+        # A numeric timeout must inspect the server ceiling once per pooled
+        # database, then pass the caller's requested timeout through unchanged.
+        # Keep the ceiling lookup separate from the RPC assertion: both queries
+        # are required, but only the latter is the operation under test.
+        from matrx_orm.core.statement_ceiling import _CEILING_SQL, reset_statement_ceiling_cache
+
+        reset_statement_ceiling_cache()
+
+        async def fetchval(sql, *args, timeout=None):
+            if sql == _CEILING_SQL:
+                return 30_000
+            return "ok"
+
+        pool.conn.fetchval.side_effect = fetchval
         await call_function("db", "public", "slow_rollup", "org-1", timeout=45.0)
         await call_function("db", "public", "slow_reconcile", "org-1", mode="none", timeout=90.0)
-        pool.conn.fetchval.assert_awaited_once_with(
-            'SELECT "public"."slow_rollup"($1)', "org-1", timeout=45.0
+        pool.conn.fetchval.assert_has_awaits(
+            [
+                call(_CEILING_SQL),
+                call('SELECT "public"."slow_rollup"($1)', "org-1", timeout=45.0),
+            ]
         )
+        assert pool.conn.fetchval.await_count == 2  # one cached ceiling read, one RPC
         pool.conn.execute.assert_awaited_once_with(
             'SELECT count(*) FROM "public"."slow_reconcile"($1)', "org-1", timeout=90.0
         )

matrx_orm-3.1.199/tests/test_statement_ceiling_warning.py

@@ -0,0 +1,128 @@
+"""A driver ``timeout=`` above the server's statement ceiling must scream, once per site.
+
+``call_function(..., timeout=300)`` only sets asyncpg's wait. The 30 s role ceiling
+(aidream migration 0919) still cancels the statement, which is how the nightly keyword
+classifier froze for eight days in September 2026 without a word in any log.
+"""
+
+from __future__ import annotations
+
+import logging
+from contextlib import asynccontextmanager
+
+import pytest
+
+from matrx_orm.core import db_function
+from matrx_orm.core.statement_ceiling import reset_statement_ceiling_cache
+
+
+class _Conn:
+    def __init__(self, ceiling_ms: int) -> None:
+        self.ceiling_ms = ceiling_ms
+        self.ceiling_reads = 0
+        self.calls: list[str] = []
+
+    async def fetchval(self, sql, *args, timeout=None):
+        if "pg_settings" in sql:
+            self.ceiling_reads += 1
+            return self.ceiling_ms
+        self.calls.append(sql)
+        return 1
+
+
+@pytest.fixture(autouse=True)
+def _fresh_cache():
+    reset_statement_ceiling_cache()
+    yield
+    reset_statement_ceiling_cache()
+
+
+def _patch(monkeypatch, conn: _Conn, *, active: bool = False) -> None:
+    @asynccontextmanager
+    async def _get_connection(database, timeout=10.0):
+        yield conn
+
+    monkeypatch.setattr(db_function, "get_active_connection", lambda: conn if active else None)
+    monkeypatch.setattr(db_function.AsyncDatabaseManager, "get_connection", _get_connection)
+
+
+def _ceiling_warnings(caplog) -> list[str]:
+    return [r.getMessage() for r in caplog.records if "OUTLIVES THE SERVER CEILING" in r.getMessage()]
+
+
+async def test_timeout_above_the_ceiling_warns_once_naming_caller_and_ceiling(monkeypatch, caplog):
+    conn = _Conn(ceiling_ms=30_000)
+    _patch(monkeypatch, conn)
+    caplog.set_level(logging.WARNING, logger="matrx_orm.statement_ceiling")
+
+    for _ in range(3):
+        assert await db_function.call_function("db", "seo", "slow_fn", timeout=300) == 1
+
+    warnings = _ceiling_warnings(caplog)
+    assert len(warnings) == 1, warnings
+    assert "test_statement_ceiling_warning.py" in warnings[0]
+    assert "timeout=300s" in warnings[0] and "statement_timeout is 30s" in warnings[0]
+    assert "seo.slow_fn" in warnings[0]
+    # The pool ceiling is read once per database, not once per call.
+    assert conn.ceiling_reads == 1
+    # The call itself still ran every time — the check never blocks.
+    assert len(conn.calls) == 3
+
+
+async def test_timeout_within_the_ceiling_is_silent(monkeypatch, caplog):
+    conn = _Conn(ceiling_ms=30_000)
+    _patch(monkeypatch, conn)
+    caplog.set_level(logging.WARNING, logger="matrx_orm.statement_ceiling")
+
+    await db_function.call_function("db", "seo", "fast_fn", timeout=25)
+    await db_function.call_function("db", "seo", "fast_fn")  # no timeout: nothing to read
+
+    assert _ceiling_warnings(caplog) == []
+    assert conn.ceiling_reads == 1
+
+
+async def test_a_declared_server_clock_in_the_transaction_is_honoured(monkeypatch, caplog):
+    # rls_session/acting_as_user(statement_timeout_ms=120_000) issued SET LOCAL: the
+    # connection's live ceiling is 120 s, so a 120 s driver timeout is honest.
+    conn = _Conn(ceiling_ms=120_000)
+    _patch(monkeypatch, conn, active=True)
+    caplog.set_level(logging.WARNING, logger="matrx_orm.statement_ceiling")
+
+    await db_function.call_function("db", "seo", "long_fn", timeout=120)
+    await db_function.call_function("db", "seo", "long_fn", timeout=120)
+
+    assert _ceiling_warnings(caplog) == []
+    # A transaction connection may carry SET LOCAL, so it is read live every call.
+    assert conn.ceiling_reads == 2
+
+
+async def test_zero_ceiling_means_unbounded_and_is_silent(monkeypatch, caplog):
+    conn = _Conn(ceiling_ms=0)
+    _patch(monkeypatch, conn)
+    caplog.set_level(logging.WARNING, logger="matrx_orm.statement_ceiling")
+
+    await db_function.call_function("db", "ops", "fn", timeout=600)
+
+    assert _ceiling_warnings(caplog) == []
+
+
+async def test_server_ceiling_waits_exactly_as_long_as_the_server_allows(monkeypatch, caplog):
+    from matrx_orm import SERVER_CEILING
+    from matrx_orm.core.statement_ceiling import SERVER_CEILING_MARGIN_SECONDS
+
+    seen: list[float | None] = []
+
+    class _TimedConn(_Conn):
+        async def fetchval(self, sql, *args, timeout=None):
+            if "pg_settings" not in sql:
+                seen.append(timeout)
+            return await super().fetchval(sql, *args, timeout=timeout)
+
+    conn = _TimedConn(ceiling_ms=30_000)
+    _patch(monkeypatch, conn)
+    caplog.set_level(logging.WARNING, logger="matrx_orm.statement_ceiling")
+
+    await db_function.call_function("db", "seo", "bounded_fn", timeout=SERVER_CEILING)
+
+    assert seen == [30 + SERVER_CEILING_MARGIN_SECONDS]
+    assert _ceiling_warnings(caplog) == []