matrx-orm 3.1.176__tar.gz → 3.1.178__tar.gz

{matrx_orm-3.1.176 → matrx_orm-3.1.178}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matrx-orm
-Version: 3.1.176
+Version: 3.1.178
 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
@@ -26,7 +26,7 @@ Requires-Dist: asyncpg>=0.31.0
 Requires-Dist: cbor2<7,>=6.1.3
 Requires-Dist: cryptography>=43.0
 Requires-Dist: gitpython>=3.1.40
-Requires-Dist: matrx-utils>=2.0.51
+Requires-Dist: matrx-utils>=2.0.53
 Requires-Dist: psycopg-pool>=3.2.5
 Requires-Dist: psycopg[binary]>=3.2.5
 Requires-Dist: python-dotenv>=1.0

{matrx_orm-3.1.176 → matrx_orm-3.1.178}/matrx_orm/__init__.py

@@ -72,7 +72,13 @@ from .core.diagnostics import (
     long_transactions,
     long_transactions_sql,
 )
-from .core.introspection import introspect_columns, introspect_rls_policies, schema_exists
+from .core.introspection import (
+    introspect_column_shapes,
+    introspect_columns,
+    introspect_function_privileges,
+    introspect_rls_policies,
+    schema_exists,
+)
 from .core.one_database import OneDatabaseReport, PoolIdentity, audit_one_database
 from .core.listen import notify, ping
 from .core.tls import resolve_asyncpg_ssl, resolve_asyncpg_ssl_from_dsn
@@ -472,7 +478,9 @@ __all__ = [
     "audit_one_database",
     "OneDatabaseReport",
     "PoolIdentity",
+    "introspect_column_shapes",
     "introspect_columns",
+    "introspect_function_privileges",
     "introspect_lock_waits",
     "introspect_rls_policies",
     "schema_exists",

{matrx_orm-3.1.176 → matrx_orm-3.1.178}/matrx_orm/catalog_sql.py

@@ -113,3 +113,43 @@ SELECT c.relname AS table_name, a.attname AS column_name
    AND NOT a.attisdropped
    AND c.relkind = ANY ('{r,p,v,m,f}')
 """
+
+# The same catalog read, plus the two facts a drift guard actually argues about:
+# whether a column may be empty, and what Postgres puts there when a writer says
+# nothing. A NOT NULL column with a DEFAULT manufactures a value that reads,
+# downstream, exactly like something a person chose — so "is there a default"
+# is a question the ORM must be able to answer without a host hand-rolling SQL.
+COLUMN_SHAPES_FOR_TABLE_SQL = """
+SELECT a.attname                                        AS column_name,
+       NOT a.attnotnull                                 AS is_nullable,
+       pg_get_expr(d.adbin, d.adrelid)                  AS column_default
+  FROM pg_attribute a
+  JOIN pg_class     c ON c.oid = a.attrelid
+  JOIN pg_namespace n ON n.oid = c.relnamespace
+  LEFT JOIN pg_attrdef d ON d.adrelid = a.attrelid AND d.adnum = a.attnum
+ WHERE n.nspname = $1
+   AND c.relname = $2
+   AND a.attnum > 0
+   AND NOT a.attisdropped
+   AND c.relkind = ANY ('{r,p,v,m,f}')
+"""
+
+
+# "Who may CALL this function?" is the other half of the definer question. A
+# SECURITY DEFINER function runs as the owner with BYPASSRLS, so the set of
+# roles holding EXECUTE on it IS its access control — and a grant that quietly
+# includes `anon` or `authenticated` hands a browser the owner's privileges.
+# Like COLUMN_SHAPES_FOR_TABLE_SQL, this is a catalog question with no Model to
+# bind it to, so the ORM answers it rather than every guard hand-rolling SQL.
+FUNCTION_PRIVILEGES_SQL = """
+SELECT p.oid::regprocedure::text                          AS signature,
+       p.prosecdef                                        AS is_security_definer,
+       role_name                                          AS role,
+       has_function_privilege(role_name, p.oid, 'EXECUTE') AS can_execute
+  FROM pg_proc p
+  JOIN pg_namespace n ON n.oid = p.pronamespace
+  CROSS JOIN unnest($3::text[]) AS role_name
+ WHERE n.nspname = $1
+   AND p.proname = $2
+   AND EXISTS (SELECT 1 FROM pg_roles r WHERE r.rolname = role_name)
+"""

{matrx_orm-3.1.176 → matrx_orm-3.1.178}/matrx_orm/core/introspection.py

@@ -17,11 +17,21 @@ from __future__ import annotations
 
 from typing import Any
 
-from matrx_orm.catalog_sql import COLUMNS_FOR_TABLES_SQL, SCHEMA_EXISTS_SQL
+from matrx_orm.catalog_sql import (
+    COLUMN_SHAPES_FOR_TABLE_SQL,
+    COLUMNS_FOR_TABLES_SQL,
+    FUNCTION_PRIVILEGES_SQL,
+    SCHEMA_EXISTS_SQL,
+)
 from matrx_orm.core.async_db_manager import AsyncDatabaseManager
 from matrx_orm.core.transaction import get_active_connection
 
-__all__ = ["introspect_rls_policies", "introspect_columns", "schema_exists"]
+__all__ = [
+    "introspect_function_privileges",
+    "introspect_rls_policies",
+    "introspect_columns",
+    "schema_exists",
+]
 
 _RLS_AUDIT_SQL = """
 select
@@ -77,6 +87,7 @@ async def introspect_rls_policies(
 # we assume, present columns read as absent and the drift guard reports the code
 # as wrong about the schema. See matrx_orm/catalog_sql.py.
 _COLUMNS_SQL = COLUMNS_FOR_TABLES_SQL
+_COLUMN_SHAPES_SQL = COLUMN_SHAPES_FOR_TABLE_SQL
 
 
 async def introspect_columns(database: str, schema: str, tables: list[str]) -> dict[str, list[str]]:
@@ -120,3 +131,66 @@ async def schema_exists(database: str, schema: str) -> bool:
 
     async with AsyncDatabaseManager.get_connection(database) as conn:
         return bool(await conn.fetchval(sql, schema))
+
+
+async def introspect_column_shapes(
+    database: str, schema: str, table: str
+) -> dict[str, dict[str, object]]:
+    """Live nullability and default per column — ``{column: {...}}``.
+
+    ``introspect_columns`` answers "does this column exist"; this answers "what
+    will Postgres do when a writer says nothing about it". A NOT NULL column
+    with a DEFAULT does not leave a hole — it FILLS one, and every reader
+    downstream sees a value indistinguishable from a deliberate choice. On
+    2026-09-22 that shape on one column
+    (``communication.sms_notification_preferences.timezone``) made an entire
+    feature a no-op in production. A guard must be able to see it without
+    hand-rolling SQL.
+
+    Each value is ``{"is_nullable": bool, "column_default": str | None}``.
+    ``schema``/``table`` are bound as parameters, never interpolated.
+    """
+    rows = await AsyncDatabaseManager.execute_query(database, _COLUMN_SHAPES_SQL, schema, table)
+    return {
+        str(r["column_name"]): {
+            "is_nullable": bool(r["is_nullable"]),
+            "column_default": (
+                str(r["column_default"]) if r["column_default"] is not None else None
+            ),
+        }
+        for r in rows
+    }
+
+
+async def introspect_function_privileges(
+    database: str, schema: str, name: str, roles: list[str]
+) -> list[dict[str, Any]]:
+    """Which of ``roles`` can EXECUTE ``schema.name`` — one row per overload/role.
+
+    ``introspect_column_shapes`` answers "what will Postgres do when a writer
+    says nothing"; this answers "who can call this door". A SECURITY DEFINER
+    function runs as its owner with BYPASSRLS, so the roles holding EXECUTE on
+    it ARE its access control: if ``anon`` or ``authenticated`` is among them,
+    a browser holds the owner's privileges. A guard has to be able to see that
+    without hand-rolling a catalog query, which is why this lives here.
+
+    Each row is ``{"signature": str, "is_security_definer": bool, "role": str,
+    "can_execute": bool}``. An overload that exists yields one row per role in
+    ``roles``; a function that does not exist yields no rows at all, which is
+    how a caller tells "missing" from "locked". A name in ``roles`` that is not
+    a role on this server is skipped rather than raising — a server without a
+    ``supabase_auth_admin`` is a different deployment, not a violation.
+    ``schema``, ``name`` and ``roles`` are bound parameters, never interpolated.
+    """
+    rows = await AsyncDatabaseManager.execute_query(
+        database, FUNCTION_PRIVILEGES_SQL, schema, name, list(roles)
+    )
+    return [
+        {
+            "signature": str(r["signature"]),
+            "is_security_definer": bool(r["is_security_definer"]),
+            "role": str(r["role"]),
+            "can_execute": bool(r["can_execute"]),
+        }
+        for r in rows
+    ]

{matrx_orm-3.1.176 → matrx_orm-3.1.178}/matrx_orm/session/fallback.py

@@ -18,6 +18,7 @@ import json
 import logging
 import os
 import re
+import sys
 import tempfile
 import traceback as _tb
 import uuid as _uuid
@@ -778,13 +779,50 @@ async def record_error(
             color="yellow",
         )
     except Exception as capture_exc:
+        # 🚨 THE ANNOUNCEMENT MUST SURVIVE THE OUTAGE IT DESCRIBES (2026-09-21).
+        #
+        # Every field below used to ride ONLY in ``extra``, and the log MESSAGE
+        # was the bare token ``matrx_orm_system_error_capture_failed``. ``extra``
+        # is read by exactly one consumer — the app_log handler, which inserts
+        # into the SAME Postgres this capture just failed against. So the one
+        # class of failure that kills the capture (a lock wave, a stalled
+        # trigger, a pool starve) killed its own announcement too, and stdout
+        # got a token with no route, no request id and no exception.
+        #
+        # Verified in production: 2026-09-21 18:48–18:51 UTC, a 48 s
+        # ``platform.provision_restricted(...)`` held a relation lock; SIX
+        # ``POST /browser-manager/profiles`` requests answered 500
+        # LockContentionError; exactly ONE reached ``ops.system_error``
+        # (request_id 5c4f84d9f19a4503ba127f3d8228d420, 18:50:45). The other
+        # five left 27 bare ``matrx_orm_system_error_capture_failed`` tokens in
+        # CloudWatch beside ``[app_log] drain insert failed, dropped 200 row(s):
+        # <LockContentionError>`` — both durable lanes died together and the
+        # surviving line named nothing.
+        #
+        # So the message itself is now SELF-CONTAINED: whoever reads the plain
+        # log stream gets the kind, the route, the request id, the real
+        # exception and why the capture failed, with no DB and no structured
+        # sink required. ``extra`` is unchanged for the queryable lane.
+        summary = (
+            "matrx_orm_system_error_capture_failed "
+            f"kind={kind} error_type={resolved_error_type} "
+            f"route={route or '-'} request_id={request_id or '-'} "
+            f"user_id={user_id or '-'} "
+            f"capture_failed_with={type(capture_exc).__name__}: "
+            f"{_capture_failure_diagnostic(capture_exc)} | "
+            f"UNRECORDED FAILURE: {_capture_failure_diagnostic(resolved_error_text)}"
+        )
+        # stdout FIRST and unconditionally: the logging tree can be
+        # misconfigured, filtered, or draining into the dead database, and this
+        # is the last place the failure can still be seen.
+        print(f"[matrx_orm.session.fallback] {summary}", file=sys.stdout, flush=True)
         # ``vcprint(..., color="red")`` is itself a logger call.  Emitting it
         # beside this structured event made ONE failed capture appear as TWO
         # unrelated ERROR families in ``app_log``.  Keep one ERROR so the
         # durable log has an exact, queryable incident without concealing the
         # original failure or the bounded-capture refusal.
         logger.error(
-            "matrx_orm_system_error_capture_failed",
+            summary,
             extra={
                 "matrx_system_error": {
                     "kind": kind,

{matrx_orm-3.1.176 → matrx_orm-3.1.178}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.176"
+version = "3.1.178"
 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.51",
+    "matrx-utils>=2.0.53",
     "pyyaml>=6.0.3",
     "python-dotenv>=1.0",
     "cryptography>=43.0",

matrx_orm-3.1.178/tests/session/test_a_failed_capture_still_names_the_failure.py

@@ -0,0 +1,144 @@
+"""A capture that cannot reach the database still SAYS what it lost.
+
+SUT: the failure branch of :func:`matrx_orm.session.fallback.record_error`.
+
+🚨 THE INCIDENT THIS GUARDS (production, 2026-09-21 18:48–18:51 UTC). A single
+48-second ``platform.provision_restricted(...)`` held a relation lock. SIX
+``POST /browser-manager/profiles`` requests answered
+``500 Internal server error: LockContentionError``. Exactly ONE of them reached
+``ops.system_error`` (request_id 5c4f84d9f19a4503ba127f3d8228d420, 18:50:45) —
+the one that happened to fall in a gap between lock waves. The other five were
+silent, because:
+
+  1. ``record_error``'s INSERT goes to the SAME Postgres that is stalled, so it
+     fails exactly when the failure most needs recording; and
+  2. its fallback announcement was ``logger.error("matrx_orm_system_error_...")``
+     with EVERY field — route, request id, the real exception — riding in
+     ``extra``, which only the app_log handler reads, and that handler inserts
+     into the same dead database (``[app_log] drain insert failed, dropped 200
+     row(s): <LockContentionError>``).
+
+Both durable lanes died together and the only line that survived named nothing.
+
+Breaks this test: moving any of kind / route / request id / the original error
+text back out of the log MESSAGE and into ``extra`` alone; dropping the direct
+stdout write; or making the announcement depend on the logging tree being
+alive.
+"""
+
+from __future__ import annotations
+
+import logging
+
+import pytest
+from matrx_orm.session import fallback
+
+
+class _StalledDatabase(Exception):
+    """Stands in for the lock-timeout the capture INSERT hit in production."""
+
+
+# Two real jobs on the platform, so no single hard-coded announcement can
+# satisfy both (forcing-function-tests §3).
+_INCIDENTS = [
+    pytest.param(
+        # All Green Recycling: an operator starting a cloud browser to file a
+        # pickup manifest with the county portal.
+        {
+            "kind": "request_crash",
+            "route": "POST /browser-manager/profiles",
+            "request_id": "5c4f84d9f19a4503ba127f3d8228d420",
+            "user_id": "9f1c7b64-2b3a-4d51-8d9c-1e2f3a4b5c6d",
+            "error_type": "LockContentionError",
+            "error_text": "LockContentionError: canceling statement due to lock timeout",
+            "capture_failure": "canceling statement due to lock timeout on ops.system_error",
+        },
+        id="all_green_recycling_browser_profile",
+    ),
+    pytest.param(
+        # Harbor Dental: a front-desk save on the new-patient intake form.
+        {
+            "kind": "request_crash",
+            "route": "POST /forms/new-patient-intake/submissions",
+            "request_id": "a71e0d3c88f2427b93cc10b4d6e5f207",
+            "user_id": "3c8d2e17-90ab-4f66-b2e1-77d0c4a95b38",
+            "error_type": "DeadlockDetectedError",
+            "error_text": "DeadlockDetectedError: deadlock detected on intake_submission",
+            "capture_failure": "pool acquire timed out after 2.0s",
+        },
+        id="harbor_dental_intake_submission",
+    ),
+]
+
+
+def _fail_the_capture(monkeypatch: pytest.MonkeyPatch, reason: str) -> None:
+    async def _boom(**_kwargs):
+        raise _StalledDatabase(reason)
+
+    monkeypatch.setattr(fallback, "_insert_error", _boom)
+
+
+@pytest.mark.parametrize("incident", _INCIDENTS)
+@pytest.mark.asyncio
+async def test_a_failed_capture_names_route_request_id_and_the_real_exception(
+    incident: dict[str, str],
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    fallback.reset_capture_storm_state()
+    _fail_the_capture(monkeypatch, incident["capture_failure"])
+
+    await fallback.record_error(
+        _StalledDatabase(incident["error_text"]),
+        kind=incident["kind"],
+        error_type=incident["error_type"],
+        error_text=incident["error_text"],
+        request_id=incident["request_id"],
+        user_id=incident["user_id"],
+        route=incident["route"],
+    )
+
+    announced = capsys.readouterr().out
+    # Everything an operator needs to act, in ONE line, with no database and no
+    # structured sink required to read it.
+    assert incident["route"] in announced
+    assert incident["request_id"] in announced
+    assert incident["error_type"] in announced
+    assert incident["error_text"] in announced
+    assert incident["capture_failure"] in announced
+    assert "_StalledDatabase" in announced, "the capture's own failure must be named"
+
+
+@pytest.mark.parametrize("incident", _INCIDENTS)
+@pytest.mark.asyncio
+async def test_the_announcement_survives_a_dead_logging_tree(
+    incident: dict[str, str],
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """The one lane that outlives the outage must not go through logging.
+
+    In the incident the logging tree WAS the dead lane: its only durable
+    consumer inserted into the stalled database. An announcement that exists
+    only as a ``logger`` call is therefore no announcement at all.
+    """
+    fallback.reset_capture_storm_state()
+    _fail_the_capture(monkeypatch, incident["capture_failure"])
+
+    logging.disable(logging.CRITICAL)
+    try:
+        await fallback.record_error(
+            _StalledDatabase(incident["error_text"]),
+            kind=incident["kind"],
+            error_type=incident["error_type"],
+            error_text=incident["error_text"],
+            request_id=incident["request_id"],
+            route=incident["route"],
+        )
+    finally:
+        logging.disable(logging.NOTSET)
+
+    announced = capsys.readouterr().out
+    assert incident["request_id"] in announced
+    assert incident["route"] in announced
+    assert incident["error_text"] in announced

{matrx_orm-3.1.176 → matrx_orm-3.1.178}/tests/session/test_record_error_bounded_insert.py

@@ -93,7 +93,7 @@ async def test_capture_insert_is_bounded_before_it_touches_the_table(monkeypatch
 def test_error_capture_with_user_but_no_org_stamps_system_org() -> None:
     # A fresh capture connection has no request actor GUC. The user id alone
     # cannot trigger a personal-org stamp and used to cause NOT NULL failure.
-    user_id = "4cf62e4e-2679-484f-b652-034e697418df"
+    user_id = "22222222-3333-4444-8555-666666666666"
     assert fallback._capture_org(None, user_id) == fallback.SYSTEM_ORGANIZATION_ID
     org_id = "bfe0205b-24c6-4ae9-9262-2fe2169fe10d"
     assert fallback._capture_org(org_id, user_id) == org_id
@@ -129,13 +129,25 @@ async def test_failed_capture_emits_one_structured_error_not_a_banner_twin(
             context={"credential": capture_secret},
         )
 
+    # 2026-09-21: the message is now SELF-CONTAINED (kind / route / request id /
+    # the real exception ride IN it, not only in ``extra``) because the app_log
+    # handler that reads ``extra`` inserts into the very database a failed
+    # capture means is unreachable. The invariant this guard was written for is
+    # unchanged and still asserted: ONE ERROR record, never a vcprint banner
+    # twin — so it matches the incident PREFIX instead of the whole line.
     records = [
         record
         for record in caplog.records
         if record.name == "matrx_orm.session.fallback"
-        and record.getMessage() == "matrx_orm_system_error_capture_failed"
+        and record.getMessage().startswith("matrx_orm_system_error_capture_failed")
     ]
     assert len(records) == 1
+    # The self-contained half: readable with no database and no structured sink.
+    message = records[0].getMessage()
+    assert "route=/api/cloud-files/changes" in message
+    assert "request_id=request-1" in message
+    assert "ValueError: shed" in message
+    assert capture_secret not in message
     captured = records[0].matrx_system_error
     assert captured == {
         "kind": "cloud_file_change_feed_shed",