matrx-orm 3.1.155__tar.gz → 3.1.157__tar.gz

{matrx_orm-3.1.155 → matrx_orm-3.1.157}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matrx-orm
-Version: 3.1.155
+Version: 3.1.157
 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.43
+Requires-Dist: matrx-utils>=2.0.45
 Requires-Dist: psycopg-pool>=3.2.5
 Requires-Dist: psycopg[binary]>=3.2.5
 Requires-Dist: python-dotenv>=1.0

{matrx_orm-3.1.155 → matrx_orm-3.1.157}/matrx_orm/__init__.py

@@ -40,10 +40,17 @@ from .entity import EntityCapabilityError, MatrxEntity
 from .platform_access import (
     ACCESS_POLICY_FUNCTION,
     ACCESS_POLICY_SCHEMA,
+    DB_PERMISSION_LEVELS,
+    PERMISSION_LEVEL_LABELS,
+    PERMISSION_LEVEL_RANK,
+    PERMISSION_LEVELS,
     EdgeAccessRequirement,
+    PermissionLevel,
     configure_platform_access,
+    permission_level_rank,
     platform_access_check,
     platform_edge_requirement,
+    to_db_permission_level,
     verify_platform_access_wiring,
 )
 from .platform_db import (
@@ -301,6 +308,7 @@ from .exceptions import (
     ORMException,
     ParameterError,
     PermissionDeniedError,
+    RecordNotAvailableError,
     PoolAcquireTimeoutError,
     LockContentionError,
     ReadOnlyTransactionError,
@@ -408,6 +416,13 @@ __all__ = [
     "EdgeAccessRequirement",
     "ACCESS_POLICY_SCHEMA",
     "ACCESS_POLICY_FUNCTION",
+    "PERMISSION_LEVELS",
+    "PERMISSION_LEVEL_RANK",
+    "PERMISSION_LEVEL_LABELS",
+    "DB_PERMISSION_LEVELS",
+    "PermissionLevel",
+    "permission_level_rank",
+    "to_db_permission_level",
     "host_db_config_name",
     "HOST_DB_CONFIG_NAME_ENV",
     "platform_connection_url",
@@ -746,6 +761,7 @@ __all__ = [
     "MigrationError",
     "ParameterError",
     "PermissionDeniedError",
+    "RecordNotAvailableError",
     "SchemaMismatchError",
     "format_db_failure_banner",
     "parse_undefined_identifier",

{matrx_orm-3.1.155 → matrx_orm-3.1.157}/matrx_orm/core/async_db_manager.py

@@ -39,6 +39,7 @@ from matrx_orm.exceptions import (
     QueryError,
     QueryTimeoutError,
     ReadOnlyTransactionError,
+    RecordNotAvailableError,
     SchemaMismatchError,
     StateError,
     UnknownDatabaseError,
@@ -1286,6 +1287,10 @@ class AsyncDatabaseManager:
                 raise PermissionDeniedError(
                     original_error=e, query=query, args=args, config_name=config_name
                 ) from None
+            except asyncpg.exceptions.NoDataFoundError as e:
+                raise RecordNotAvailableError(
+                    original_error=e, query=query, args=args, config_name=config_name
+                ) from None
             except asyncpg.exceptions.ReadOnlySQLTransactionError as e:
                 raise ReadOnlyTransactionError(original_error=e) from None
             except TimeoutError as e:
@@ -1487,6 +1492,10 @@ class AsyncDatabaseManager:
                         raise PermissionDeniedError(
                             original_error=e, query=query, args=args, config_name=config_name
                         ) from None
+                    except asyncpg.exceptions.NoDataFoundError as e:
+                        raise RecordNotAvailableError(
+                            original_error=e, query=query, args=args, config_name=config_name
+                        ) from None
                     except TimeoutError as e:
                         # asyncpg's command_timeout fired — query held a
                         # connection but didn't return in time. See the twin

{matrx_orm-3.1.155 → matrx_orm-3.1.157}/matrx_orm/exceptions.py

@@ -1946,6 +1946,93 @@ class PermissionDeniedError(DatabaseError):
         return f"{_RED}{body}{_RESET}"
 
 
+class RecordNotAvailableError(DatabaseError):
+    """The database refused the statement with SQLSTATE ``P0002`` (no_data_found).
+
+    Our SECURITY INVOKER functions and triggers raise ``P0002`` as the platform's
+    HONEST ACCESS REFUSAL: "dataset <id> is not available to this account — it
+    may not exist, or your access may not reach it" (the D167 class; see
+    matrx-frontend ``migrations/invoker_fns_honest_access_error.sql``). That
+    sentence is written for a person. Before 2026-09-17 it fell through to
+    ``UnknownDatabaseError`` and a Studio user saw the whole terminal banner —
+    SQL, bound args and ORM-maintainer hints — instead of it.
+
+    ``person_message`` is the sentence a client may show (plus a remedy);
+    ``str(exc)`` stays the developer banner for logs. Not retryable: access does
+    not change between attempts.
+    """
+
+    #: The honest-refusal wording our functions use. Anything else raised under
+    #: P0002 (``SELECT … INTO STRICT`` finding no row) is ours to word.
+    _HONEST_REFUSAL = "is not available to this account"
+
+    def __init__(
+        self,
+        *,
+        original_error: BaseException | None = None,
+        query: str | None = None,
+        args: Any = None,
+        config_name: str | None = None,
+    ) -> None:
+        info = describe_db_exception(original_error)
+        details: dict[str, Any] = {
+            "query": query,
+            "args": args if args is not None else [],
+            "config_name": config_name,
+            "sqlstate": info.sqlstate,
+            "db_error": info.as_text(),
+            "db_hint": info.hint,
+        }
+        self.db_message = info.message
+        super().__init__(
+            message=f"Record not available to this account: {info.message}",
+            model=None,
+            details=details,
+        )
+
+    @property
+    def person_message(self) -> str:
+        """One plain sentence with a remedy. Never SQL, args, or ids of other rows."""
+        reason = (self.db_message or "").strip().rstrip(".")
+        if self._HONEST_REFUSAL in reason:
+            first = reason[0].upper() + reason[1:]
+            return (
+                f"{first}. Choose one this account can open, or ask its owner to share it."
+            )
+        return (
+            "Something this step needs is not available to this account — it may not "
+            "exist, or your access may not reach it. Check the step's selection, or ask "
+            "its owner to share it."
+        )
+
+    def format_message(self) -> str:
+        sqlstate = self._str("sqlstate")
+        db_error = self._str("db_error")
+        query = self._str("query")
+        args = self.details.get("args", [])
+        lines = ["\n" + "-" * 80]
+        lines.append("Matrx ORM  |  RecordNotAvailableError")
+        lines.append("")
+        lines.append(self.message)
+        if sqlstate:
+            lines.append(f"  SQLSTATE:  {sqlstate}")
+        if db_error:
+            lines.append(f"  DB error:  {db_error}")
+        if query:
+            short_query = str(query)[:300] + ("..." if len(str(query)) > 300 else "")
+            lines.append(f"  Query:     {short_query}")
+        if args:
+            lines.append(f"  Args:      {args}")
+        lines.append("")
+        lines.append("Hint:")
+        lines.append("  - A database function refused this with P0002 — usually the honest access")
+        lines.append("    refusal: RLS hides the row from this caller, or it does not exist.")
+        lines.append("  - Not retryable. The person-facing sentence is ``person_message``.")
+        lines.append("-" * 80 + "\n")
+        body = "\n".join(lines)
+        return f"{_RED}{body}{_RESET}"
+
+
 class UnknownDatabaseError(ORMException):
     """Raised when an unexpected database error occurs, capturing full context.
 

{matrx_orm-3.1.155 → matrx_orm-3.1.157}/matrx_orm/platform_access.py

@@ -39,7 +39,79 @@ from __future__ import annotations
 from dataclasses import dataclass
 from typing import Literal
 
-PermissionLevel = Literal["viewer", "editor", "admin"]
+# ── THE LADDER ────────────────────────────────────────────────────────────────
+#
+# The access levels are ``viewer`` · ``commenter`` · ``editor`` · ``admin``
+# (AI Matrx Data Doctrine R18, 2026-09-10; see
+# common-docs/systems/platform/access/DECISIONS.md). This is THE ONE PLACE they
+# are declared on the Python side — every rank map, label map and level tuple in
+# aidream derives from it, so a level cannot be present in one ladder and absent
+# from another.
+#
+# It matters because the failure is SILENT. A rank map that omits a level hands
+# a ``dict.get(level, 0)`` caller a 0, the comparison is ``False``, and the
+# holder is refused with nothing written anywhere. A ``not in {...}`` validation
+# set that omits one rejects a legitimate grant as "unsupported".
+#
+# ``PERMISSION_LEVELS`` (the CODE ladder) deliberately runs WIDER than
+# ``DB_PERMISSION_LEVELS`` (what ``public.permission_level`` holds today):
+# ``commenter`` is not in the database enum yet. Reading, ranking and labelling
+# always use the code ladder, so nothing needs an edit the day the enum gains
+# it; nothing breaks meanwhile, because the value simply never arrives. WRITING
+# a level to the database narrows through ``to_db_permission_level`` first.
+PERMISSION_LEVELS: tuple[str, ...] = ("viewer", "commenter", "editor", "admin")
+
+PermissionLevel = Literal["viewer", "commenter", "editor", "admin"]
+
+#: Ordinal rank, 1-based, derived from the ladder so it can never drift out of step.
+PERMISSION_LEVEL_RANK: dict[str, int] = {level: index + 1 for index, level in enumerate(PERMISSION_LEVELS)}
+
+#: Human labels — a level that reaches a screen or a log is never rendered blank.
+PERMISSION_LEVEL_LABELS: dict[str, str] = {
+    "viewer": "Viewer",
+    "commenter": "Commenter",
+    "editor": "Editor",
+    "admin": "Full access",
+}
+
+#: What ``public.permission_level`` accepts RIGHT NOW. Widen this the same
+#: migration that runs
+#: ``ALTER TYPE public.permission_level ADD VALUE 'commenter' BEFORE 'editor'``.
+DB_PERMISSION_LEVELS: tuple[str, ...] = ("viewer", "editor", "admin")
+
+
+def permission_level_rank(level: str) -> int:
+    """Rank a level, refusing to answer silently for one off the ladder.
+
+    The old shape — ``LEVEL_ORDER.get(level, 0)`` — quietly ranked an unknown
+    level at the bottom and denied it with no trace. This raises by name with
+    the remedy instead.
+    """
+    try:
+        return PERMISSION_LEVEL_RANK[level]
+    except KeyError:
+        raise ValueError(
+            f"Unknown permission level {level!r}. Known levels are "
+            f"{', '.join(PERMISSION_LEVELS)} — add it to PERMISSION_LEVELS in "
+            "matrx_orm.platform_access if the database gained a new value."
+        ) from None
+
+
+def to_db_permission_level(level: str) -> str:
+    """Narrow a code-ladder level to one the database can actually store.
+
+    Refuses by name with the remedy rather than letting Postgres answer with an
+    opaque ``invalid input value for enum public.permission_level``.
+    """
+    permission_level_rank(level)  # rejects an off-ladder level first
+    if level not in DB_PERMISSION_LEVELS:
+        raise ValueError(
+            f"Permission level {level!r} is not in the database enum "
+            f"public.permission_level (it holds {', '.join(DB_PERMISSION_LEVELS)}). "
+            f"Apply ALTER TYPE public.permission_level ADD VALUE '{level}' before "
+            "granting this level."
+        )
+    return level
 
 #: The canonical policy function: ``iam.has_access_for(uuid, text, uuid, permission_level)``.
 ACCESS_POLICY_SCHEMA = "iam"

{matrx_orm-3.1.155 → matrx_orm-3.1.157}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.155"
+version = "3.1.157"
 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.43",
+    "matrx-utils>=2.0.45",
     "pyyaml>=6.0.3",
     "python-dotenv>=1.0",
     "cryptography>=43.0",

matrx_orm-3.1.157/tests/level1/test_orm_banners_are_client_safe.py

@@ -0,0 +1,73 @@
+"""Every ORM error a client might be shown reduces to its reason — never SQL,
+bound args, ANSI, a traceback or maintainer hints — and the P0002 honest access
+refusal is its own class with a person-facing sentence.
+
+Live 2026-09-17: a Studio user saw ``UnknownDatabaseError``'s full banner (the
+INSERT and its Args: their user id and row data) because asyncpg's
+``NoDataFoundError`` had no catch and the engine rendered ``str(exc)``.
+"""
+
+from __future__ import annotations
+
+import asyncpg
+import pytest
+from matrx_utils import client_error_text
+
+from matrx_orm.exceptions import (
+    PermissionDeniedError,
+    QueryTimeoutError,
+    RecordNotAvailableError,
+    UnknownDatabaseError,
+)
+
+_SECRET = "4cf62e4e-2679-484c-a1ab-0e62d4e1c3aa"
+_QUERY = "INSERT INTO workbench.udt_dataset_rows (data, user_id) VALUES ($1, $2)"
+_ARGS = ['{"note": "private row"}', _SECRET]
+_REFUSAL = "dataset d-1 is not available to this account — it may not exist, or your access may not reach it"
+_LEAKS = ("\x1b", "[91m", "Args:", "Query:", "INSERT", _SECRET, "private row", "Traceback", "Hint:", "Matrx ORM", "-" * 20)
+
+
+def _banners() -> list[BaseException]:
+    return [
+        UnknownDatabaseError(
+            operation="execute_query",
+            query=_QUERY,
+            args=_ARGS,
+            traceback='Traceback (most recent call last):\n  File "x.py", line 1\n',
+            original_error=asyncpg.exceptions.NoDataFoundError(_REFUSAL),
+        ),
+        PermissionDeniedError(
+            original_error=asyncpg.exceptions.InsufficientPrivilegeError("permission denied for table t"),
+            query=_QUERY,
+            args=_ARGS,
+        ),
+        RecordNotAvailableError(
+            original_error=asyncpg.exceptions.NoDataFoundError(_REFUSAL), query=_QUERY, args=_ARGS
+        ),
+        QueryTimeoutError(operation="execute_query", query=_QUERY, args=_ARGS, original_error=TimeoutError()),
+    ]
+
+
+@pytest.mark.parametrize("exc", _banners(), ids=lambda e: type(e).__name__)
+def test_real_orm_banner_reduces_to_its_reason(exc: BaseException) -> None:
+    raw = str(exc)
+    assert "Args:" in raw  # the render really carries the bound args
+    out = client_error_text(raw)
+    assert out.strip()
+    for leak in _LEAKS:
+        assert leak not in out, f"{type(exc).__name__} leaks {leak!r}:\n{out}"
+
+
+def test_honest_refusal_has_a_person_sentence_with_a_remedy() -> None:
+    exc = RecordNotAvailableError(original_error=asyncpg.exceptions.NoDataFoundError(_REFUSAL), query=_QUERY, args=_ARGS)
+    msg = exc.person_message
+    assert msg.startswith("Dataset d-1 is not available to this account")
+    assert "ask its owner to share it" in msg
+    for leak in _LEAKS:
+        assert leak not in msg
+
+
+def test_other_p0002_gets_a_generic_honest_sentence() -> None:
+    exc = RecordNotAvailableError(original_error=asyncpg.exceptions.NoDataFoundError("query returned no rows"))
+    assert "not available to this account" in exc.person_message
+    assert "query returned no rows" not in exc.person_message