matrx-orm 3.1.138__tar.gz → 3.1.140__tar.gz

{matrx_orm-3.1.138 → matrx_orm-3.1.140}/PKG-INFO

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

{matrx_orm-3.1.138 → matrx_orm-3.1.140}/matrx_orm/FEATURE.md

@@ -96,8 +96,31 @@
   structured error context stay usable even when their caller has only the
   typed predicate object.
 
+## Organization-assignment retirements are reviewed proposals
+
+- **The packaged genesis remains immutable.**
+  `scripts/validate_org_backstop_coverage.py` reads the digest-pinned package
+  resource; it never writes an installed wheel or the source resource in place.
+- **A verified removal writes an explicit proposal.** Run
+  `--update-baseline --baseline-output <new-path>` only after the authenticated
+  inventory has no additions. The command refuses growth, bad database/function
+  evidence, and an existing output path.
+- **A function retirement needs review evidence.** The immutable 16-root census
+  always returns every requested identity; an absent row is eligible only with
+  `--function-retirement-evidence <json>` mapping that exact qualified root to
+  a nonempty review reference and no live attachments.
+- **Review and commit the proposal before packaging it.** Replace
+  `resources/org_assignment_trigger_baseline.json` in a normal source commit,
+  then build the wheel so standalone installs consume the reviewed retirement.
+
 ## Change Log
 
+- 2026-09-12 — Made organization-assignment retirement output an explicit,
+  non-overwriting review proposal; a checked-in resource update is required
+  before the next standalone wheel carries a retirement.
+- 2026-09-12 — Preserved every requested assignment-function row through the
+  catalog gate so an evidence-backed, attachment-free function retirement can
+  be proposed without weakening the immutable 16-root census.
 - 2026-09-11 — Made disk-spill recovery tolerate deleted actors without losing
   the spill, its original actor evidence, or system ownership.
 - 2026-09-10 — Added stable semantic `Predicate.describe()` rendering for
@@ -125,6 +148,18 @@
   schema-qualified known assigner functions and every `organization_id` column
   default so the release ratchet can block growth without treating an automatic
   assignment as protection.
+- 2026-09-12 — Hardened the assignment inventory contract with the measured
+  database identity and all eight requested function roots. The ratchet retains
+  its captured genesis list and digest; verified removals are ledger entries, so
+  a same-count baseline edit cannot replace historical debt.
+- 2026-09-12 — Added a second digest-pinned census for eight later-discovered
+  assigner roots and 32 attachments. The original genesis is untouched; exact
+  function and trigger evidence is measured, and only recorded retirements can
+  reduce the known debt.
+- 2026-09-12 — Made `matrx_orm.resources` the canonical distributable owner of
+  both assignment-debt ledgers. `no_org_assignment` resolves them through
+  `importlib.resources`, so the 16-root catalog contract and its source-gate
+  wrapper work from a wheel without a sibling repository.
 - 2026-08-21 — Fixed the `ON CONFLICT` retry counter in `_bulk_insert_failures`:
   it qualified the target as `public.system_write_failure`, which no longer
   exists, so every retry-conflict capture raised `UndefinedTableError` and

{matrx_orm-3.1.138 → matrx_orm-3.1.140}/matrx_orm/__init__.py

@@ -300,6 +300,7 @@ from .exceptions import (
     ParameterError,
     PermissionDeniedError,
     PoolAcquireTimeoutError,
+    LockContentionError,
     ReadOnlyTransactionError,
     QueryError,
     QueryTimeoutError,
@@ -718,6 +719,7 @@ __all__ = [
     "ConnectionError",
     "IntegrityError",
     "PoolAcquireTimeoutError",
+    "LockContentionError",
     "ReadOnlyTransactionError",
     "QueryTimeoutError",
     "TransactionError",

{matrx_orm-3.1.138 → matrx_orm-3.1.140}/matrx_orm/catalog.py

@@ -5,8 +5,9 @@ from __future__ import annotations
 import asyncio
 from typing import Any
 
-from .catalog_sql import PG_CATALOG_COLUMNS_CTE, PG_CATALOG_TABLES_CTE
+from .catalog_sql import PG_CATALOG_TABLES_CTE
 from .core.async_db_manager import AsyncDatabaseManager
+from .no_org_assignment import organization_assignment_function_identities
 
 __all__ = [
     "actor_stamp_column_drift",
@@ -484,7 +485,7 @@ async def publication_column_status(
 async def organization_assignment_inventory(
     database: str,
     *,
-    function_identities: list[tuple[str, str]],
+    function_identities: list[tuple[str, str]] | None = None,
 ) -> dict[str, list[dict[str, Any]]]:
     """Inventory known database organization assigners and column defaults.
 
@@ -492,9 +493,36 @@ async def organization_assignment_inventory(
     must provide ``organization_id`` itself; discovering one of these rows is
     evidence to remove, not a reason to permit a missing value.
     """
-    schemas = [schema for schema, _ in function_identities]
-    names = [name for _, name in function_identities]
-    trigger_rows, default_rows = await asyncio.gather(
+    identities = function_identities or list(organization_assignment_function_identities())
+    schemas = [schema for schema, _ in identities]
+    names = [name for _, name in identities]
+    metadata_rows, function_rows, trigger_rows, default_rows = await asyncio.gather(
+        _query(
+            database,
+            "SELECT current_database() AS database_name",
+        ),
+        _query(
+            database,
+            """
+            WITH requested AS (
+              SELECT function_schema, function_name
+              FROM unnest($1::text[], $2::text[])
+                AS requested(function_schema, function_name)
+            )
+            SELECT r.function_schema, r.function_name,
+                   p.oid::text AS function_oid,
+                   pg_get_function_identity_arguments(p.oid) AS identity_arguments,
+                   md5(pg_get_functiondef(p.oid)) AS definition_md5,
+                   p.oid IS NOT NULL AS present
+            FROM requested r
+            LEFT JOIN pg_namespace n ON n.nspname = r.function_schema
+            LEFT JOIN pg_proc p ON p.pronamespace = n.oid
+              AND p.proname = r.function_name
+            ORDER BY r.function_schema, r.function_name
+            """,
+            schemas,
+            names,
+        ),
         _query(
             database,
             """
@@ -504,7 +532,9 @@ async def organization_assignment_inventory(
                 AS requested(function_schema, function_name)
             )
             SELECT pns.nspname AS function_schema, p.proname AS function_name,
-                   tns.nspname AS schema, c.relname AS table, t.tgname AS trigger
+                   tns.nspname AS schema, c.relname AS table, t.tgname AS trigger,
+                   t.tgenabled::text AS enabled, t.oid::text AS trigger_oid,
+                   pg_get_triggerdef(t.oid) AS definition
             FROM pg_trigger t
             JOIN pg_class c ON c.oid = t.tgrelid
             JOIN pg_namespace tns ON tns.oid = c.relnamespace
@@ -534,7 +564,12 @@ async def organization_assignment_inventory(
             """,
         ),
     )
-    return {"triggers": trigger_rows, "defaults": default_rows}
+    return {
+        "metadata": metadata_rows,
+        "functions": function_rows,
+        "triggers": trigger_rows,
+        "defaults": default_rows,
+    }
 
 
 async def trigger_function_usage(

{matrx_orm-3.1.138 → matrx_orm-3.1.140}/matrx_orm/core/async_db_manager.py

@@ -5,6 +5,7 @@ from dataclasses import dataclass
 import json
 import logging
 import os
+import random
 import traceback
 from contextlib import asynccontextmanager
 from typing import Any
@@ -31,6 +32,7 @@ from matrx_orm.exceptions import (
     DatabaseConnectError,
     DatabaseError,
     IntegrityError,
+    LockContentionError,
     ParameterError,
     PermissionDeniedError,
     PoolAcquireTimeoutError,
@@ -72,6 +74,24 @@ _SCHEMA_MISMATCH_EXC = (
     asyncpg.exceptions.InvalidSchemaNameError,
 )
 
+# Cancelled to break a lock collision. ``TransactionRollbackError`` is an
+# umbrella for every SQLSTATE 40xxx, including 40003 (completion unknown) and
+# 40002 (transaction integrity constraint violation). Only the three explicit
+# statuses below establish that PostgreSQL aborted this statement in full.
+_CONTENTION_EXC = (
+    asyncpg.exceptions.TransactionRollbackError,
+    asyncpg.exceptions.LockNotAvailableError,
+)
+_CONTENTION_SQLSTATES = frozenset({"40P01", "40001", "55P03"})
+
+
+def _is_confidently_aborted_lock_contention(exc: BaseException) -> bool:
+    """Whether ``exc`` proves a standalone statement can be re-issued."""
+    return (
+        isinstance(exc, _CONTENTION_EXC)
+        and getattr(exc, "sqlstate", None) in _CONTENTION_SQLSTATES
+    )
+
 # PostgreSQL emits these SQLSTATE class-57 errors while asyncpg is opening a
 # physical connection during a server restart/failover.  They happen before a
 # checkout exists, so no caller SQL was sent and a replay-safe owner may retry.
@@ -123,6 +143,22 @@ POOL_RELEASE_TIMEOUT_SECONDS = 10.0
 READ_TIMEOUT_RETRIES = 1  # extra attempts for a timed-out read; total = 1 + this
 READ_TIMEOUT_RETRY_BACKOFF = 0.25  # seconds before the read retry
 
+# ── lock collisions (40P01 / 40001 / 55P03) ──────────────────────────────────
+# Postgres breaks a lock cycle by CANCELLING one party, and the victim is rolled
+# back IN FULL — no part of the cancelled statement survives. That makes a single
+# statement (outside a caller-managed transaction) provably safe to re-issue,
+# writes included, and re-issuing it is what every serious ORM does.
+#
+# The victim is very often innocent: a multi-table READ holding AccessShareLocks
+# is killed because a concurrent DDL session wants AccessExclusiveLock on one of
+# the same tables, which is an everyday event here (migrations apply against live
+# traffic). On 2026-09-12 that reached a person as the banner
+# "listConversations: deadlock detected" on /chat, and ops.app_log shows the same
+# class crashing POST /coding-sessions/bridge with a 500. Bounded and LOUD: real
+# contention still surfaces, it just costs two extra attempts first.
+CONTENTION_RETRIES = 2  # extra attempts for a cancelled statement; total = 1 + this
+CONTENTION_BACKOFF = 0.06  # seconds before the first re-issue; doubled each time
+
 # ── idle-in-transaction ceiling (the platform-wide DDL blocker) ───────────────
 # A session that BEGINs and then goes quiet is the single most expensive thing a
 # client can do to a shared Postgres: it holds every lock it took (so DDL —
@@ -1208,6 +1244,21 @@ class AsyncDatabaseManager:
             try:
                 results = await tx_conn.fetch(query, *args, timeout=statement_timeout)
                 return [dict(r) for r in results]
+            except _CONTENTION_EXC as e:
+                if not _is_confidently_aborted_lock_contention(e):
+                    raise
+                # NEVER re-run inside a caller-managed transaction. The whole
+                # atomic block is dead once Postgres cancels one of its
+                # statements, and the work already done in it is the caller's to
+                # decide about — ``retry_on_transient`` wraps the TRANSACTION.
+                raise LockContentionError(
+                    original_error=e,
+                    query=query,
+                    args=args,
+                    config_name=config_name,
+                    attempts=1,
+                    in_transaction=True,
+                ) from None
             except asyncpg.exceptions.PostgresSyntaxError as e:
                 raise QueryError(
                     model=None,
@@ -1287,7 +1338,13 @@ class AsyncDatabaseManager:
             # A timed-out READ retries ONCE on a fresh connection (self-heal for
             # a starvation-induced command_timeout). Each iteration re-acquires,
             # so a poisoned connection is never reused. Writes never loop here.
-            for read_attempt in range(1 + READ_TIMEOUT_RETRIES):
+            # Two independent budgets, each re-acquiring a FRESH connection: a
+            # timed-out read (below) and a statement Postgres cancelled to break
+            # a lock collision (which applies to writes too — the victim is
+            # rolled back in full).
+            read_attempt = 0
+            contention_attempt = 0
+            while True:
                 async with cls.get_connection(config_name, timeout) as conn:
                     try:
                         results = await conn.fetch(query, *args, timeout=statement_timeout)
@@ -1298,6 +1355,14 @@ class AsyncDatabaseManager:
                                 read_attempt + 1,
                                 query[:120],
                             )
+                        if contention_attempt > 0:
+                            logger.warning(
+                                "[lock-retry] HEALED on attempt %d after Postgres "
+                                "cancelled the statement to break a lock collision "
+                                "(rolled back, safe to re-run): %s",
+                                contention_attempt + 1,
+                                query[:120],
+                            )
                         if (
                             not results
                             and verify_empty
@@ -1319,6 +1384,36 @@ class AsyncDatabaseManager:
                             if true_rows is not None:
                                 return true_rows
                         return [_normalize_record(r) for r in results]
+                    except _CONTENTION_EXC as e:
+                        if not _is_confidently_aborted_lock_contention(e):
+                            raise
+                        # Rolled back in full → the SAME statement is re-issued
+                        # on a fresh connection, writes included. Jittered so N
+                        # tasks cancelled by ONE collision do not collide again
+                        # in lockstep. Announced every time: a masked contention
+                        # problem is the thing this must never become.
+                        if contention_attempt < CONTENTION_RETRIES:
+                            delay = CONTENTION_BACKOFF * (2**contention_attempt)
+                            delay += random.random() * delay * 0.5
+                            logger.warning(
+                                "[lock-retry] attempt %d/%d cancelled by a lock "
+                                "collision (%s) — re-running in %.3fs: %s",
+                                contention_attempt + 1,
+                                1 + CONTENTION_RETRIES,
+                                getattr(e, "sqlstate", None) or e.__class__.__name__,
+                                delay,
+                                query[:120],
+                            )
+                            await asyncio.sleep(delay)
+                            contention_attempt += 1
+                            continue
+                        raise LockContentionError(
+                            original_error=e,
+                            query=query,
+                            args=args,
+                            config_name=config_name,
+                            attempts=1 + contention_attempt,
+                        ) from None
                     except asyncpg.exceptions.PostgresSyntaxError as e:
                         raise QueryError(
                             model=None,
@@ -1367,6 +1462,7 @@ class AsyncDatabaseManager:
                                 query[:120],
                             )
                             await asyncio.sleep(READ_TIMEOUT_RETRY_BACKOFF)
+                            read_attempt += 1
                             continue
                         raise ConnectionError(
                             model=None,
@@ -1403,6 +1499,7 @@ class AsyncDatabaseManager:
                                 query[:120],
                             )
                             await asyncio.sleep(READ_TIMEOUT_RETRY_BACKOFF)
+                            read_attempt += 1
                             continue
                         if connection_closed:
                             raise ConnectionError(
@@ -1441,6 +1538,7 @@ class AsyncDatabaseManager:
                                 query[:120],
                             )
                             await asyncio.sleep(READ_TIMEOUT_RETRY_BACKOFF)
+                            read_attempt += 1
                             continue
                         raise QueryTimeoutError(
                             operation="execute_query",
@@ -1507,6 +1605,21 @@ class AsyncDatabaseManager:
         except ImportError:
             pass
 
+        # A declared host session context (notably actor provenance) is made of
+        # transaction-local GUCs. A plain standalone write used to skip BEGIN,
+        # so its trigger saw the database default even though the caller had
+        # explicitly declared an actor. Keep the declaration in the caller's
+        # task (the write-queue drain has a different ContextVar context) and
+        # use the canonical transaction path for this one write.
+        from matrx_orm.core.session_context import session_context_gucs
+
+        if session_context_gucs():
+            from matrx_orm.core.transaction import transaction
+
+            config_name = resolve_database_name(config_name)
+            async with transaction(config_name):
+                return await cls.execute_query(config_name, query, *args, timeout=timeout)
+
         from matrx_orm.core.write_queue import get_write_queue_registry
 
         config_name = resolve_database_name(config_name)

{matrx_orm-3.1.138 → matrx_orm-3.1.140}/matrx_orm/exceptions.py

@@ -1183,6 +1183,81 @@ class PoolAcquireTimeoutError(DatabaseError):
         return f"{_RED}{body}{_RESET}"
 
 
+class LockContentionError(DatabaseError):
+    """Raised when Postgres cancelled a statement to break a lock collision.
+
+    SQLSTATE 40P01 (deadlock_detected), 40001 (serialization_failure) and 55P03
+    (lock_not_available). The victim is rolled back IN FULL — no part of the
+    cancelled statement survives — so a single statement outside a
+    caller-managed transaction is provably safe to re-issue, and
+    ``AsyncDatabaseManager.execute_query`` re-issues it a bounded number of
+    times with jittered backoff, announcing every heal. This exception means
+    either that budget was exhausted, or that the statement ran INSIDE an
+    explicit ``transaction()`` where the partial work is the caller's to decide
+    about (wrap the whole transaction in ``retry_on_transient`` if re-running it
+    is safe).
+
+    The usual cause is not the caller: a multi-table statement becomes a
+    deadlock victim whenever a concurrent DDL session wants AccessExclusiveLock
+    on a table the statement already holds a lock on. Migrations applied against
+    live traffic produce exactly this (2026-09-12: a frontend conversation-list
+    READ, which writes nothing, surfaced "deadlock detected" to a person).
+    """
+
+    def __init__(
+        self,
+        original_error=None,
+        query: str | None = None,
+        args=None,
+        config_name: str | None = None,
+        attempts: int = 1,
+        in_transaction: bool = False,
+    ):
+        sqlstate = getattr(original_error, "sqlstate", None)
+        details = {
+            "query": query,
+            "args": args,
+            "config_name": config_name,
+            "sqlstate": sqlstate,
+            "attempts": attempts,
+            "in_transaction": in_transaction,
+        }
+        where = (
+            "inside a caller-managed transaction, so nothing was re-run"
+            if in_transaction
+            else f"after {attempts} attempt(s)"
+        )
+        super().__init__(
+            message=(
+                f"Postgres cancelled this statement to break a lock collision "
+                f"({sqlstate or 'lock contention'}) {where}: {original_error}"
+            ),
+            model=None,
+            details=details,
+        )
+
+    def format_message(self):
+        details = self.details or {}
+        lines = ["\n" + "-" * 80]
+        lines.append("Matrx ORM  |  LockContentionError")
+        lines.append("")
+        lines.append(self.message)
+        lines.append("")
+        lines.append("Hint:")
+        lines.append("  - NOTHING of the cancelled statement committed; re-running is safe.")
+        if details.get("in_transaction"):
+            lines.append("  - It ran inside an explicit transaction(), so the ORM did NOT")
+            lines.append("    re-run it: the rest of the transaction is yours. Wrap the whole")
+            lines.append("    transaction in `retry_on_transient` when re-running it is safe.")
+        else:
+            lines.append(f"  - The ORM already re-ran it {details.get('attempts', '?')} time(s).")
+            lines.append("    Repeated failures mean REAL contention on these tables — look at")
+            lines.append("    what else held a lock (DDL applied against live traffic is the")
+            lines.append("    usual partner), not at this caller.")
+        lines.append("-" * 80 + "\n")
+        return f"{_RED}" + "\n".join(lines) + f"{_RESET}"
+
+
 class IntegrityError(DatabaseError):
     """Raised for database integrity violations."""
 

matrx_orm-3.1.140/matrx_orm/no_org_assignment.py

@@ -0,0 +1,79 @@
+"""Standalone organization-assignment debt inventory and provenance pins."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from functools import lru_cache
+from importlib.resources import files
+from typing import Any
+
+_RESOURCE_PACKAGE = "matrx_orm.resources"
+_ORIGINAL_RESOURCE = "org_assignment_trigger_baseline.json"
+_DISCOVERY_RESOURCE = "additional-assigners-2026-09-12.json"
+
+ORIGINAL_GENESIS_SHA256 = "859df77f01d30ef745fd6724d7152a349ccb900b61c33772fe89d678714895ae"
+DISCOVERY_GENESIS_SHA256 = "1f66a51b072918d998e25ad46a0e659229c19f1eb2069e499aa2450eb3f8b0c4"
+DISCOVERY_PROJECT_ID = "brsgrqvjdzwihsvnfqkf"
+
+
+def resource_text(name: str) -> str:
+    """Read a packaged inventory without relying on a sibling checkout."""
+    return files(_RESOURCE_PACKAGE).joinpath(name).read_text(encoding="utf-8")
+
+
+def original_baseline_payload() -> dict[str, Any]:
+    """Return the canonical mutable-retirement ledger from package data."""
+    payload = json.loads(resource_text(_ORIGINAL_RESOURCE))
+    if not isinstance(payload, dict):
+        raise ValueError("organization assignment baseline must be an object")
+    genesis = {
+        key: payload.get(key)
+        for key in (
+            "historical_four_family_triggers",
+            "historical_specialized_triggers",
+            "historical_organization_defaults",
+        )
+    }
+    digest = hashlib.sha256(
+        json.dumps(genesis, sort_keys=True, separators=(",", ":")).encode()
+    ).hexdigest()
+    if payload.get("genesis_sha256") != ORIGINAL_GENESIS_SHA256 or digest != ORIGINAL_GENESIS_SHA256:
+        raise ValueError("organization assignment baseline digest mismatch")
+    return payload
+
+
+def discovery_genesis_payload() -> dict[str, Any]:
+    """Return the separately captured additional-debt census from package data."""
+    payload = json.loads(resource_text(_DISCOVERY_RESOURCE))
+    if not isinstance(payload, dict):
+        raise ValueError("organization assignment discovery must be an object")
+    canonical = json.dumps(payload, sort_keys=True, separators=(",", ":")).encode()
+    if hashlib.sha256(canonical).hexdigest() != DISCOVERY_GENESIS_SHA256:
+        raise ValueError("organization assignment discovery digest mismatch")
+    return payload
+
+
+@lru_cache(maxsize=1)
+def organization_assignment_function_identities() -> tuple[tuple[str, str], ...]:
+    """Return every exact function root covered by the packaged gate."""
+    original = original_baseline_payload().get("function_identities")
+    discovery = discovery_genesis_payload().get("items")
+    if not isinstance(original, list) or not isinstance(discovery, list):
+        raise ValueError("organization assignment function inventory is incomplete")
+    identities: list[tuple[str, str]] = []
+    for identity in original:
+        if not isinstance(identity, str) or identity.count(".") != 1:
+            raise ValueError("organization assignment function identity is invalid")
+        identities.append(tuple(identity.split(".", 1)))
+    for item in discovery:
+        if not isinstance(item, dict):
+            raise ValueError("organization assignment discovery item is invalid")
+        schema = item.get("schema_name")
+        name = item.get("function_name")
+        if not isinstance(schema, str) or not isinstance(name, str):
+            raise ValueError("organization assignment discovery root is invalid")
+        identities.append((schema, name))
+    if len(identities) != 16 or len(set(identities)) != 16:
+        raise ValueError("organization assignment root count is invalid")
+    return tuple(identities)

matrx_orm-3.1.140/matrx_orm/resources/__init__.py

@@ -0,0 +1 @@
+"""Immutable machine-readable inventories shipped with matrx-orm."""