matrx-orm 3.1.99__tar.gz → 3.1.100__tar.gz

{matrx_orm-3.1.99 → matrx_orm-3.1.100}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matrx-orm
-Version: 3.1.99
+Version: 3.1.100
 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.99 → matrx_orm-3.1.100}/matrx_orm/catalog.py

@@ -30,6 +30,7 @@ __all__ = [
     "column_privileges",
     "entity_capability_state",
     "event_trigger_state",
+    "function_source",
 ]
 
 
@@ -320,6 +321,47 @@ async def first_party_function_bodies(
     return [{"name": str(row["name"]), "source": str(row["source"] or "")} for row in rows]
 
 
+async def function_source(
+    database: str,
+    *,
+    schema: str,
+    name: str,
+) -> str | None:
+    """Return one function's live ``prosrc``, or ``None`` when it does not exist.
+
+    The single-function twin of :func:`first_party_function_bodies`, which only
+    answers "give me everything". A truth-vs-code guard almost always wants ONE
+    named function — "is the floor constant in the trigger still the one Python
+    believes?" — and every such guard was hand-writing the same `pg_proc` join
+    outside the ORM to get it (`aidream/scripts/check_crawl_cadence_floor_parity.py`
+    was doing exactly that, over its own raw `asyncpg.connect`).
+
+    ``None`` distinguishes "not installed" from "installed and empty", which is
+    the distinction those guards act on: a missing enforcement function is a
+    louder finding than a disagreeing one.
+
+    Overloads: returns the FIRST body by ``oid``. A guard that cares about a
+    specific overload should assert on the signature separately — this helper
+    deliberately does not try to encode overload resolution.
+    """
+    rows = await _query(
+        database,
+        """
+        SELECT p.prosrc AS source
+        FROM pg_proc p
+        JOIN pg_namespace n ON n.oid = p.pronamespace
+        WHERE n.nspname = $1 AND p.proname = $2
+        ORDER BY p.oid
+        LIMIT 1
+        """,
+        schema,
+        name,
+    )
+    if not rows:
+        return None
+    return str(rows[0]["source"] or "")
+
+
 async def first_party_view_definitions(
     database: str,
     *,
@@ -462,9 +504,27 @@ async def org_backstop_coverage(database: str) -> list[dict[str, Any]]:
               -- `_inherit_org`), and `plan` uses `_stamp_from_node`. Keying on
               -- the trigger name reported correctly-backstopped children as
               -- DRIFT (D232 §C, 2026-08-21).
+              --
+              -- FOUR, not three: `platform.stamp_run_org` (10 run tables) is a
+              -- real backstop -- owner -> personal org, unattended -> SYSTEM
+              -- org, else RAISE -- so it cannot leave organization_id NULL. It
+              -- was missing here, and this gate is BLOCKING. Green only by
+              -- luck: 8 of its 10 tables also carry `_stamp_org_default`, and
+              -- the 2 that rely on it alone (docproc.page_extraction_runs,
+              -- legal.ingest_runs) have no owner column, so has_owner is false
+              -- and the gate skips them. Add a `created_by` to either and this
+              -- gate would have blocked every release over a correctly
+              -- backstopped table (matrx-frontend D241, 2026-08-21).
+              --
+              -- Adding a name here is a RULING, not housekeeping: read the
+              -- function body first and confirm it cannot RETURN with a NULL
+              -- organization_id. An accept-list that is too short blocks good
+              -- releases; one that is too long silently passes a table whose
+              -- org-forgetting write will 500 in production.
               AND bp.proname IN ('_stamp_org_default',
                                  'inherit_org_from_parent',
-                                 '_stamp_from_node')) AS has_backstop
+                                 '_stamp_from_node',
+                                 'stamp_run_org')) AS has_backstop
         FROM pg_catalog_columns c
         JOIN pg_catalog_tables tb
           ON tb.table_schema=c.table_schema AND tb.table_name=c.table_name

{matrx_orm-3.1.99 → matrx_orm-3.1.100}/matrx_orm/core/FEATURE.md

@@ -170,6 +170,10 @@ can never disagree about who the blocker was.
 Verified against the live database: 2026-08-21.
 
 ## Change log
+- 2026-08-22: Preserved the deepest Postgres SQLSTATE on `AppError` as a
+  lightweight classification (without retaining traceback frames), so an
+  idempotent transactional owner can recover from a database role transition
+  without parsing rendered error prose.
 - 2026-08-21: Added the idle-in-transaction ceiling on every pool and the
   `long_transactions` blocker-naming primitive (feedback c72a32ac).
 

{matrx_orm-3.1.99 → matrx_orm-3.1.100}/matrx_orm/extended/app_error_handler.py

@@ -1,9 +1,9 @@
-from collections.abc import Mapping
+from collections.abc import Callable, Mapping
 from functools import wraps
 import inspect
 import sys
 import traceback
-from typing import Callable, Protocol, TypeVar, runtime_checkable
+from typing import Protocol, TypeVar, runtime_checkable
 
 DEFAULT_CLIENT_MESSAGE = "Oops. Something went wrong. Please reload the page and try again."
 
@@ -85,6 +85,16 @@ class AppError(Exception):
         self._inner_banner: str | None = (
             str(original) if _inner_has_custom_banner(original) else None
         )
+        # Keep the stable Postgres classification without retaining the
+        # frame-heavy exception object. Callers that own an idempotent,
+        # transactional unit can use this to recover from a database role
+        # transition (for example SQLSTATE 25006) without parsing prose.
+        if original is not None:
+            from matrx_orm.exceptions import describe_db_exception
+
+            self.db_sqlstate: str | None = describe_db_exception(original).sqlstate
+        else:
+            self.db_sqlstate = None
         super().__init__(message)
 
     def __str__(self) -> str:

{matrx_orm-3.1.99 → matrx_orm-3.1.100}/matrx_orm/query/executor.py

@@ -1527,11 +1527,18 @@ class QueryExecutor:
         # report "0 deleted" even when rows were removed.
         sql += " RETURNING 1"
 
-        try:
-            result = await self.db.execute_write(sql, *where_params)
-            return len(result)
-        except DatabaseError as e:
-            raise DatabaseError(f"Delete failed: {str(e)}") from e
+        # A DatabaseError from execute_write is ALREADY the typed, formatted ORM
+        # error (PermissionDeniedError, ForeignKeyViolationError, ...). Catching
+        # it here and re-raising the BASE class downgraded every one of them to a
+        # generic DatabaseError, so a caller could no longer tell "permission
+        # denied" from "a child row still references this" — and `str(e)` folded
+        # the original's ANSI-coloured multi-line block into a message. Found by
+        # `scripts/_verify_batch_access_model.py`, whose whole job is asserting a
+        # user's DELETE is refused for the RIGHT reason: `except
+        # PermissionDeniedError` silently missed it and the probe reported the
+        # write had SUCCEEDED. Let the typed error through untouched.
+        result = await self.db.execute_write(sql, *where_params)
+        return len(result)
 
     # ------------------------------------------------------------------
     # SELECT terminal methods
@@ -1592,17 +1599,17 @@ class QueryExecutor:
         """COUNT(*) for the current WHERE clause."""
         count_sql, params = self._build_count_query()
 
-        try:
-            statement_timeout = self._full_query_dict.get("timeout")
-            if statement_timeout is not None:
-                result = await self.db.execute_query(
-                    count_sql, *params, statement_timeout=statement_timeout
-                )
-            else:
-                result = await self.db.execute_query(count_sql, *params)
-            return result[0]["count"] if result else 0
-        except DatabaseError as e:
-            raise DatabaseError(f"Count query failed: {str(e)}") from e
+        # Same downgrade as delete() above: the DatabaseError arriving here is
+        # already the typed, formatted ORM error, and re-raising the base class
+        # destroyed that type for every caller. Let it through untouched.
+        statement_timeout = self._full_query_dict.get("timeout")
+        if statement_timeout is not None:
+            result = await self.db.execute_query(
+                count_sql, *params, statement_timeout=statement_timeout
+            )
+        else:
+            result = await self.db.execute_query(count_sql, *params)
+        return result[0]["count"] if result else 0
 
     async def exists(self) -> bool:
         """EXISTS check for the current WHERE clause."""

{matrx_orm-3.1.99 → matrx_orm-3.1.100}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.99"
+version = "3.1.100"
 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.99 → matrx_orm-3.1.100}/tests/level1/test_exceptions.py

@@ -2,6 +2,7 @@
 
 import matrx_orm.exceptions as exceptions_module
 
+from matrx_orm.extended.app_error_handler import AppError
 from matrx_orm.exceptions import (
     AdapterError,
     CacheError,
@@ -43,6 +44,20 @@ class _FakePgError(Exception):
         return {"code": self.sqlstate, **self._fields}
 
 
+def test_app_error_preserves_sqlstate_without_retaining_original() -> None:
+    driver_error = _FakePgError("25006", {"message": "read only"})
+    wrapped = QueryError(
+        message="write failed",
+        details={"operation": "update", "error": "read only"},
+    )
+    wrapped.__cause__ = driver_error
+
+    error = AppError(message="write failed", original=wrapped)
+
+    assert error.db_sqlstate == "25006"
+    assert not hasattr(error, "original")
+
+
 class TestORMExceptionBase:
     def test_caller_capture_never_reads_source_files(self, monkeypatch):
         def fail_if_called():