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

{matrx_orm-3.1.136 → matrx_orm-3.1.138}/.gitignore

@@ -301,3 +301,6 @@ apps/shared/*/*.tgz
 # capturing one mid-run.
 _kind_boundary_scratch*/
 _kind_marker_law_scratch*/
+
+# packed npm tarballs are build output, never source (doctrine: typescript-package-standard)
+*.tgz

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

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

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

@@ -118,9 +118,13 @@
   the authoritative outcome channel.
 - 2026-08-21 — NO NULL ORG on the capture lane (db-rules §2). Both capture
   writers now stamp `organization_id` (`_capture_org()`); `ops.system_error` and
-  `ops.system_write_failure` are `NOT NULL` with backstop trigger
-  `_120_stamp_capture_org` (aidream migration 0443). `ops.system_error` left the
-  `known_null_org_writers` allowlist in both ratchet baselines.
+  `ops.system_write_failure` are `NOT NULL`. Their historical assignment
+  attachment is migration debt, never a valid fallback for a missing org.
+- 2026-09-12 — Replaced the old `org_backstop_coverage` health-shaped catalog
+  helper with `organization_assignment_inventory`. It reports the eight
+  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-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.136 → matrx_orm-3.1.138}/matrx_orm/__init__.py

@@ -241,8 +241,18 @@ from .core.registry import (
 from .core.relations import ManyToManyField
 from .core.rls_session import rls_session
 from .core.session_context import (
+    ACTOR_SYSTEM_GUC,
+    ACTOR_TIER_GUC,
+    VALID_TIERS,
+    ActorRef,
+    ActorTier,
     SessionContextProvider,
     configure_session_context,
+    current_actor,
+    current_tier,
+    declared_actor,
+    declared_actor_gucs,
+    declaring_actor,
     session_context_gucs,
 )
 from .core.signals import (
@@ -638,7 +648,17 @@ __all__ = [
     "acquire_connection",
     "set_local_guc",
     "SessionContextProvider",
+    "ACTOR_SYSTEM_GUC",
+    "ACTOR_TIER_GUC",
+    "VALID_TIERS",
+    "ActorRef",
+    "ActorTier",
     "configure_session_context",
+    "current_actor",
+    "current_tier",
+    "declared_actor",
+    "declared_actor_gucs",
+    "declaring_actor",
     "session_context_gucs",
     "advisory_xact_lock",
     "try_advisory_xact_lock",

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

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import asyncio
 from typing import Any
 
 from .catalog_sql import PG_CATALOG_COLUMNS_CTE, PG_CATALOG_TABLES_CTE
@@ -19,7 +20,7 @@ __all__ = [
     "relation_column_counts",
     "relation_check_constraints",
     "relation_schemas",
-    "org_backstop_coverage",
+    "organization_assignment_inventory",
     "publication_column_status",
     "relation_privileges",
     "role_service_state",
@@ -480,60 +481,60 @@ async def publication_column_status(
     return None if not rows else bool(rows[0]["published"])
 
 
-async def org_backstop_coverage(database: str) -> list[dict[str, Any]]:
-    """Return required org-id relations with owner/backstop booleans."""
-    return await _query(
-        database,
-        f"""
-        WITH {PG_CATALOG_COLUMNS_CTE.strip()},
-             {PG_CATALOG_TABLES_CTE.strip()}
-        SELECT c.table_schema AS schema, c.table_name,
-          EXISTS (SELECT 1 FROM pg_catalog_columns o
-            WHERE o.table_schema=c.table_schema AND o.table_name=c.table_name
-              AND o.column_name IN ('created_by','user_id','owner_id')) AS has_owner,
-          EXISTS (SELECT 1 FROM pg_trigger t
-            JOIN pg_class cl ON cl.oid=t.tgrelid
-            JOIN pg_namespace n ON n.oid=cl.relnamespace
-            JOIN pg_proc bp ON bp.oid=t.tgfoid
-            WHERE n.nspname=c.table_schema AND cl.relname=c.table_name
-              AND NOT t.tgisinternal
-              -- Match the FUNCTION, not the trigger name: db-rules FEATURE.md
-              -- §2 names THREE legal org backstops, and only the first is
-              -- conventionally called `_stamp_org_default`. A child entity's
-              -- backstop is `platform.inherit_org_from_parent` (trigger
-              -- `_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',
-                                 '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
-          AND tb.table_type='BASE TABLE'
-        WHERE c.column_name='organization_id' AND c.is_nullable='NO'
-          AND c.column_default IS NULL
-        ORDER BY c.table_schema, c.table_name
-        """,
+async def organization_assignment_inventory(
+    database: str,
+    *,
+    function_identities: list[tuple[str, str]],
+) -> dict[str, list[dict[str, Any]]]:
+    """Inventory known database organization assigners and column defaults.
+
+    This is an inventory of migration debt, never a health check.  A writer
+    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(
+        _query(
+            database,
+            """
+            WITH requested AS (
+              SELECT function_schema, function_name
+              FROM unnest($1::text[], $2::text[])
+                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
+            FROM pg_trigger t
+            JOIN pg_class c ON c.oid = t.tgrelid
+            JOIN pg_namespace tns ON tns.oid = c.relnamespace
+            JOIN pg_proc p ON p.oid = t.tgfoid
+            JOIN pg_namespace pns ON pns.oid = p.pronamespace
+            JOIN requested r ON r.function_schema = pns.nspname
+              AND r.function_name = p.proname
+            WHERE NOT t.tgisinternal
+            ORDER BY pns.nspname, p.proname, tns.nspname, c.relname, t.tgname
+            """,
+            schemas,
+            names,
+        ),
+        _query(
+            database,
+            """
+            SELECT n.nspname AS schema, c.relname AS table,
+                   pg_get_expr(ad.adbin, ad.adrelid) AS default
+            FROM pg_attribute a
+            JOIN pg_class c ON c.oid = a.attrelid
+            JOIN pg_namespace n ON n.oid = c.relnamespace
+            JOIN pg_attrdef ad ON ad.adrelid = a.attrelid AND ad.adnum = a.attnum
+            WHERE a.attname = 'organization_id'
+              AND a.attnum > 0 AND NOT a.attisdropped
+              AND c.relkind = ANY ('{r,p}')
+            ORDER BY n.nspname, c.relname
+            """,
+        ),
     )
+    return {"triggers": trigger_rows, "defaults": default_rows}
 
 
 async def trigger_function_usage(

{matrx_orm-3.1.136 → matrx_orm-3.1.138}/matrx_orm/core/FEATURE.md

@@ -65,6 +65,12 @@ for scalar, row-set, discarded-result, and active-transaction calls. Callers can
 therefore distinguish an ambiguous in-flight RPC from a pool-acquire failure and
 must choose replay policy explicitly.
 
+**Opt-in transient retries can be bounded and desynchronized.**
+`retry_on_transient(..., jitter_ratio=...)` retains deterministic exponential
+backoff by default; a caller recovering a replay-safe lock conflict can add at
+most `jitter_ratio * base_delay` to each retry without changing its retry count
+or exception classification.
+
 **Read-side connection loss retries once on a fresh checkout.** A read-only SQL
 statement is safe to repeat after `ConnectionDoesNotExistError`. The same retry
 applies when empty-read reproof loses its connection and transaction teardown

{matrx_orm-3.1.136 → matrx_orm-3.1.138}/matrx_orm/core/expressions.py

@@ -237,13 +237,35 @@ class Q:
 
     # -- Boolean operators --------------------------------------------------
 
+    @staticmethod
+    def _require_q(other: Any, op: str) -> None:
+        """Q composes with Q; Predicate composes with Predicate. Never mixed.
+
+        ``Q(a=1) | Is(F("x"), None)`` used to build a Q holding a Predicate
+        child and then die inside key validation with *\'Is\' object has no
+        attribute \'kwargs\'* — which is how GET /rag/admin/overview 500'd.
+        """
+        if isinstance(other, Q):
+            return
+        if isinstance(other, Predicate):
+            raise TypeError(
+                f"Q {op} {type(other).__name__}: a typed Predicate cannot be "
+                "combined with Q. Express the whole condition in ONE family — "
+                'Compare(F("field"), "=", value) '
+                f"{op} {type(other).__name__}(...) — and pass that predicate "
+                "to filter()."
+            )
+        raise TypeError(f"Q {op} requires another Q, got {type(other).__name__}")
+
     def __and__(self, other: Q) -> Q:
+        self._require_q(other, "&")
         node = Q()
         node.connector = self.AND
         node.children = [self, other]
         return node
 
     def __or__(self, other: Q) -> Q:
+        self._require_q(other, "|")
         node = Q()
         node.connector = self.OR
         node.children = [self, other]
@@ -866,9 +888,7 @@ def _render_subquery_condition(
             expr_sql = value.as_sql(combined)
             sql_operator = _SUBQUERY_COMPARISON_OPERATORS.get(operator)
             if sql_operator is None:
-                raise ValueError(
-                    f"Lookup {operator!r} is not supported with a database expression"
-                )
+                raise ValueError(f"Lookup {operator!r} is not supported with a database expression")
             condition = f"{field_name} {sql_operator} {expr_sql}"
         elif isinstance(value, Exists):
             condition = value.as_sql(
@@ -879,9 +899,7 @@ def _render_subquery_condition(
         else:
             sub_sql = value.as_sql(current_table, combined)
             condition = (
-                f"{field_name} IN {sub_sql}"
-                if operator == "in"
-                else f"{field_name} = {sub_sql}"
+                f"{field_name} IN {sub_sql}" if operator == "in" else f"{field_name} = {sub_sql}"
             )
         sub_params.extend(combined[already_bound:])
         return condition
@@ -1613,9 +1631,14 @@ def _describe_literal(value: Any) -> str:
         suffix = "," if len(value) == 1 else ""
         return "(" + ", ".join(_describe_literal(item) for item in value) + suffix + ")"
     if isinstance(value, dict):
-        return "{" + ", ".join(
-            f"{_describe_literal(key)}: {_describe_literal(item)}" for key, item in value.items()
-        ) + "}"
+        return (
+            "{"
+            + ", ".join(
+                f"{_describe_literal(key)}: {_describe_literal(item)}"
+                for key, item in value.items()
+            )
+            + "}"
+        )
     if isinstance(value, datetime | date):
         return value.isoformat()
     if isinstance(value, Decimal | UUID | str | int | float | bool) or value is None:
@@ -1653,9 +1676,13 @@ def _describe_expression(value: Any) -> str:
 def _describe_predicate(predicate: Predicate) -> str:
     """Render every built-in predicate form without SQL placeholders or object reprs."""
     if isinstance(predicate, CompoundPredicate):
-        return "(" + f" {predicate.connector} ".join(
-            _describe_predicate(child) for child in predicate.children
-        ) + ")"
+        return (
+            "("
+            + f" {predicate.connector} ".join(
+                _describe_predicate(child) for child in predicate.children
+            )
+            + ")"
+        )
     if isinstance(predicate, NegatedPredicate):
         return f"NOT ({_describe_predicate(predicate.predicate)})"
     if isinstance(predicate, Compare):
@@ -1962,6 +1989,24 @@ class Filter:
             raise TypeError("Filter aggregate requires a typed SQL expression")
         if not isinstance(condition, Predicate):
             raise TypeError("Filter condition requires a typed Predicate")
+        # Postgres attaches FILTER to an aggregate CALL and nothing else, so
+        # ``Filter(ArrayIndex(ArrayAgg(x), 1), cond)`` emits
+        # ``(array_agg(x))[1] FILTER (WHERE …)`` — *syntax error at or near
+        # "FILTER"*. It shipped that way and 500'd GET /rag/admin/sources.
+        # Refuse it here, where the remedy is obvious, instead of at the wire.
+        # JsonbObjectAgg is also a PostgreSQL aggregate call, but it has two
+        # positional expressions so it cannot inherit Aggregate's single-field
+        # renderer. Keep the accepted set explicit rather than accepting any
+        # Func wrapper (which would reintroduce invalid SQL at the wire).
+        if not isinstance(agg, (Aggregate, JsonbObjectAgg)):
+            raise TypeError(
+                "Filter() attaches FILTER (WHERE ...) to an AGGREGATE CALL; "
+                f"got {type(agg).__name__}, which Postgres rejects with "
+                "'syntax error at or near \"FILTER\"'. Wrap the aggregate "
+                "itself and apply the outer expression around the Filter — "
+                "ArrayIndex(Filter(ArrayAgg(x), cond), 1), not "
+                "Filter(ArrayIndex(ArrayAgg(x), 1), cond)."
+            )
         self.agg = agg
         self.condition = condition
 

{matrx_orm-3.1.136 → matrx_orm-3.1.138}/matrx_orm/core/resilience.py

@@ -29,6 +29,7 @@ from __future__ import annotations
 
 import asyncio
 import logging
+import random
 import re
 from typing import Awaitable, Callable, TypeVar
 
@@ -52,6 +53,7 @@ async def retry_on_transient(
     *,
     attempts: int = 3,
     base_backoff: float = 0.25,
+    jitter_ratio: float = 0.0,
     retry_on: tuple[type[BaseException], ...] = DEFAULT_TRANSIENT,
     label: str = "db-unit",
 ) -> T:
@@ -59,13 +61,17 @@ async def retry_on_transient(
 
     ``factory`` is a zero-arg async callable invoked fresh on every attempt, so
     it must (re)open its own transaction/connection — a rolled-back attempt
-    leaves nothing behind. Backoff is exponential from ``base_backoff``. On the
-    final attempt the original exception propagates unchanged.
+    leaves nothing behind. Backoff is exponential from ``base_backoff``. An
+    optional positive ``jitter_ratio`` adds up to that fraction of each base
+    delay, so callers recovering lock contention need not retry in lockstep.
+    On the final attempt the original exception propagates unchanged.
 
     Loud on every retry AND on heal, so a masked slow-query/contention problem
     is never silent — it shows up as a WARNING you can grep, not a swallowed
     hiccup.
     """
+    if jitter_ratio < 0:
+        raise ValueError("jitter_ratio must be non-negative")
     last_exc: BaseException | None = None
     for attempt in range(1, attempts + 1):
         try:
@@ -91,6 +97,8 @@ async def retry_on_transient(
                 )
                 raise
             backoff = base_backoff * (2 ** (attempt - 1))
+            if jitter_ratio:
+                backoff += random.uniform(0.0, backoff * jitter_ratio)  # noqa: S311 -- retry desynchronization
             logger.warning(
                 "[resilience] %s attempt %d/%d hit transient DB failure (%s) — "
                 "retrying in %.2fs (rolled back, safe to re-run).",

matrx_orm-3.1.138/matrx_orm/core/session_context.py

@@ -0,0 +1,222 @@
+"""The host's DECLARED session context — GUCs every transaction opens with.
+
+Some facts about a block of work are known by the application and readable only
+by the database: *which tier of actor* is authoring these writes, for instance.
+Postgres learns them through transaction-local GUCs (``set_config(..., true)``),
+and a GUC set outside a transaction has no meaning — so the ONE place that can
+reliably apply them is the moment this package opens a transaction.
+
+The host declares a provider once at startup::
+
+    from matrx_orm import configure_session_context
+    configure_session_context(lambda: {"app.actor_tier": "ai", "app.actor_system": "x"})
+
+and from then on every TOP-LEVEL ``transaction()`` (which includes the one
+``rls_session`` opens, before it drops to the restricted role) emits whatever
+the provider returns at that instant. A savepoint (nested transaction) emits
+nothing: it is already inside the transaction the GUCs were set on.
+
+Why a provider and not a value: what is true changes per task — the provider is
+normally a ContextVar read, so a block that declares "an AI is writing this"
+affects exactly the work inside it and nothing running beside it.
+
+The package NEVER imports the host: no provider configured ⇒ no GUCs, which is
+exactly how matrx-orm behaves standalone. A provider that raises is a host bug
+and it surfaces — the transaction fails loudly rather than silently committing
+writes whose provenance is a lie.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from collections.abc import AsyncIterator, Callable, Iterator, Mapping
+from contextlib import asynccontextmanager, contextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass
+from typing import Any, Literal
+
+logger = logging.getLogger("matrx_orm.core.session_context")
+
+# Same shape matrx_orm.core.transaction.set_local_guc accepts.
+_GUC_NAME_RE = re.compile(r"^[a-z_][a-z0-9_.]*$")
+
+SessionContextProvider = Callable[[], Mapping[str, str] | None]
+
+_provider: SessionContextProvider | None = None
+
+
+def configure_session_context(provider: SessionContextProvider | None) -> None:
+    """Bind (or with ``None``, unbind) the host's session-context provider.
+
+    Call once at startup, alongside the other package ``configure_*`` calls.
+    ``provider`` is invoked on every top-level transaction open and must return
+    a mapping of GUC name → value (or ``None`` / ``{}`` for "nothing to say").
+    """
+    global _provider
+    if provider is not None and not callable(provider):
+        raise TypeError("configure_session_context(provider) requires a callable or None")
+    _provider = provider
+
+
+def session_context_gucs() -> dict[str, str]:
+    """The GUCs to set on a transaction being opened right now.
+
+    Empty when no provider is configured. Raises when a configured provider
+    returns something unusable — a malformed declaration is a host defect, and
+    writing rows with a wrong (or absent) provenance stamp is worse than a loud
+    failure at BEGIN.
+    """
+    provider = _provider
+    if provider is None:
+        return {}
+    declared = provider()
+    if not declared:
+        return {}
+    if not isinstance(declared, Mapping):
+        raise TypeError(
+            "the session-context provider must return a mapping of GUC name → value; "
+            f"got {type(declared).__name__}"
+        )
+    out: dict[str, str] = {}
+    for name, value in declared.items():
+        if not isinstance(name, str) or not _GUC_NAME_RE.match(name):
+            raise ValueError(f"invalid session-context GUC name: {name!r}")
+        out[name] = "" if value is None else str(value)
+    return out
+
+
+async def apply_session_context(connection: Any) -> None:
+    """Emit the declared GUCs on ``connection`` (already inside a BEGIN)."""
+    for name, value in session_context_gucs().items():
+        await connection.execute("SELECT set_config($1, $2, true)", name, value)
+
+
+# ---------------------------------------------------------------------------
+# THE ACTOR DECLARATION — who authored the writes in a block.
+#
+# This lives HERE, beside the provider that emits it, because the declaration
+# is only useful to a package that can never import the host: the chat door in
+# matrx-ai declares "a person typed this row" / "the model produced this row",
+# and matrx-orm is the common floor both the host and that package stand on.
+# The host (aidream) re-exports these names and wires ``declared_actor_gucs``
+# into ``configure_session_context`` at startup.
+#
+# CONVERGE: actor tier literal code|ai|human; target vocabulary
+# system|agent|user - declared 2026-09-10, Data Doctrine 1.5/7.
+# ---------------------------------------------------------------------------
+
+ActorTier = Literal["code", "ai", "human"]
+
+ACTOR_TIER_GUC = "app.actor_tier"
+ACTOR_SYSTEM_GUC = "app.actor_system"
+
+VALID_TIERS: frozenset[str] = frozenset({"code", "ai", "human"})
+
+
+@dataclass(frozen=True, slots=True)
+class ActorRef:
+    """The actor a block of DB work is attributed to."""
+
+    tier: ActorTier
+    system: str | None = None
+
+    def as_gucs(self) -> dict[str, str]:
+        """The two session GUCs this actor implies."""
+        return {ACTOR_TIER_GUC: self.tier, ACTOR_SYSTEM_GUC: self.system or ""}
+
+
+_current_actor: ContextVar[ActorRef | None] = ContextVar("_provenance_actor", default=None)
+
+
+def current_actor() -> ActorRef | None:
+    """The actor declared by the innermost open declaration, if any."""
+    return _current_actor.get()
+
+
+def current_tier() -> ActorTier | None:
+    """The declared tier, or None when nothing declared one."""
+    actor = _current_actor.get()
+    return actor.tier if actor else None
+
+
+def declared_actor_gucs() -> dict[str, str]:
+    """The session GUCs the currently declared actor implies.
+
+    This is the provider a host passes to :func:`configure_session_context`.
+    Empty when nothing declared an actor: the DB resolver then applies its
+    documented default (``human`` with an identity present, ``code`` without)
+    and logs that it did.
+    """
+    actor = _current_actor.get()
+    if actor is None:
+        return {}
+    return actor.as_gucs()
+
+
+def _validated_actor(tier: str, system: str, *, caller: str) -> ActorRef:
+    if tier not in VALID_TIERS:
+        raise ValueError(f"{caller} tier must be one of {sorted(VALID_TIERS)}; got {tier!r}")
+    if not system or not system.strip():
+        raise ValueError(f"{caller} requires a non-empty system (who specifically)")
+    return ActorRef(tier=tier, system=system.strip())  # type: ignore[arg-type]
+
+
+@contextmanager
+def declaring_actor(tier: ActorTier, system: str) -> Iterator[ActorRef]:
+    """Synchronous form of :func:`declared_actor` - same ContextVar, no await.
+
+    A write door is often a plain function (``queue_message_create``), and the
+    thing that must carry the declaration is the SYNCHRONOUS act of queueing
+    the op: a deferred write commits later, inside a flush that ran long after
+    this block closed, so the op itself captures the actor declared here
+    (``matrx_orm.session.op``) and the flush re-declares it per row. Nothing
+    here touches a connection.
+    """
+    actor = _validated_actor(tier, system, caller="declaring_actor")
+    token = _current_actor.set(actor)
+    try:
+        yield actor
+    finally:
+        _current_actor.reset(token)
+
+
+@asynccontextmanager
+async def declared_actor(tier: ActorTier, system: str) -> AsyncIterator[ActorRef]:
+    """Declare the actor for the block WITHOUT opening a transaction.
+
+    The declaration is a ContextVar, so the GUCs land when the work inside
+    opens its own transaction (this module's provider is asked at every
+    top-level BEGIN, ``rls_session`` included) - or, for a write deferred onto
+    a Session, when the op that captured this declaration is executed at flush.
+
+    That is what makes it usable at a DISPATCHER, above code whose write paths
+    are its own business: ``rls_session`` refuses to nest inside an existing
+    transaction, so a chokepoint that opened one would break every handler that
+    acts as the user.
+    """
+    actor = _validated_actor(tier, system, caller="declared_actor")
+    token = _current_actor.set(actor)
+    logger.debug("provenance: declared tier=%s system=%s", actor.tier, actor.system)
+    try:
+        yield actor
+    finally:
+        _current_actor.reset(token)
+
+
+__all__ = [
+    "ACTOR_SYSTEM_GUC",
+    "ACTOR_TIER_GUC",
+    "VALID_TIERS",
+    "ActorRef",
+    "ActorTier",
+    "SessionContextProvider",
+    "apply_session_context",
+    "configure_session_context",
+    "current_actor",
+    "current_tier",
+    "declared_actor",
+    "declared_actor_gucs",
+    "declaring_actor",
+    "session_context_gucs",
+]

{matrx_orm-3.1.136 → matrx_orm-3.1.138}/matrx_orm/operations/catalog_select.py

@@ -238,7 +238,9 @@ async def catalog_select(
         parts = []
         for field in order_by:
             descending = field.startswith("-")
-            parts.append(f"{_quote(field.removeprefix('-'))} {'DESC' if descending else 'ASC'}")
+            # "-col" = largest/newest first; a NULL is never the newest, so DESC
+            # gets NULLS LAST (Postgres' default for DESC is NULLS FIRST).
+            parts.append(f"{_quote(field.removeprefix('-'))} {'DESC NULLS LAST' if descending else 'ASC'}")
         sql += " ORDER BY " + ", ".join(parts)
 
     if limit is not None: