matrx-orm 3.1.154__tar.gz → 3.1.156__tar.gz

{matrx_orm-3.1.154 → matrx_orm-3.1.156}/PKG-INFO

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

{matrx_orm-3.1.154 → matrx_orm-3.1.156}/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 (
@@ -408,6 +415,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",

{matrx_orm-3.1.154 → matrx_orm-3.1.156}/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.154 → matrx_orm-3.1.156}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.154"
+version = "3.1.156"
 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.42",
+    "matrx-utils>=2.0.44",
     "pyyaml>=6.0.3",
     "python-dotenv>=1.0",
     "cryptography>=43.0",