matrx-orm 3.1.255__tar.gz → 3.1.256__tar.gz

{matrx_orm-3.1.255 → matrx_orm-3.1.256}/CLAUDE.md

@@ -11,11 +11,11 @@
 
 ## Read this first
 
-matrx-orm is a standalone async Postgres ORM (`Model`, `QueryBuilder`, migrations, admin router, multi-project registry). It has been the cleanest of the Matrx packages and we intend to keep it that way. Before adding *any* import, verify it resolves in a fresh venv that only has matrx-orm + matrx-utils.
+matrx-orm is a standalone async Postgres ORM (`Model`, `QueryBuilder`, migrations, admin router, multi-project registry). Before adding *any* import, verify it resolves in a fresh venv that only has matrx-orm + matrx-utils.
 
 ### Row identity
 
-Every table that becomes a Model needs row identity: a single-column primary key (usually `id`) or a composite primary key. Intentionally PK-less tables (backup, staging, scratch) belong in the host's `matrx_orm.yaml` `exclude_tables` — do not invent a PK. Tables named with an archival prefix (`_bak_*` / `_backup_*`) are auto-skipped at schema discovery (`is_archival_table_name`) and never need an exclude entry — a live backup table can no longer kill a full generation run. Never add a surrogate `id` only to satisfy codegen when a natural or composite key already exists. Canonical copy + error text: [`matrx_orm/identity_rule.py`](matrx_orm/identity_rule.py).
+Every table that becomes a Model needs row identity: a single-column primary key (usually `id`) or a composite primary key. Intentionally PK-less tables (backup, staging, scratch) belong in the host's `matrx_orm.yaml` `exclude_tables` — do not invent a PK. Tables named with an archival prefix (`_bak_*` / `_backup_*`) are auto-skipped at schema discovery (`is_archival_table_name`) and never need an exclude entry. Never add a surrogate `id` only to satisfy codegen when a natural or composite key already exists. Canonical copy + error text: [`matrx_orm/identity_rule.py`](matrx_orm/identity_rule.py).
 
 ---
 
@@ -24,12 +24,12 @@ Every table that becomes a Model needs row identity: a single-column primary key
 - **Config / project registry** (`matrx_orm.core.config`): `DatabaseProjectConfig`, `register_database`, `register_database_from_env`, `get_database_config`, `get_manager_config`, `DatabaseRegistry`. A single process can run multiple named database projects concurrently.
 - 🚨 **ONE CONNECTION, REQUIRED** (`matrx_orm.platform_db`): `register_platform_db(name, ...)` + `platform_connection_url()` — the ONLY sanctioned way any Matrx service or package turns env vars into a pool. One set of variables (`SUPABASE_MATRIX_*`), owned here; TLS is a deployment input (`SUPABASE_MATRIX_SSL`), never hardcoded; **RAISES** if it isn't given a database — no degraded mode. Every package's `bootstrap_db()` is one call to it. A package may absolutely run on its OWN Postgres — that is a change of VALUES, never a new variable name; what it may never have is a *second candidate* or a fallback chain. `register_database_from_env` is the low-level primitive underneath — **application and package code must not call it directly** (guard: `scripts/check_one_database.py`, blocking in release).
 - **Core model layer**: `Model`, `BaseManager`, `BaseDTO`, `ModelView`, `model_registry`, plus 50+ field types (`CharField`, `IntegerField`, `ForeignKey`, `ManyToManyField`, `JSONField`, …).
-- **`MatrxEntity`** (`matrx_orm/entity.py`) — **the platform entity contract as an ORM primitive.** A table registered in `platform.entity_types` generates as a `MatrxEntity` (everything else stays a plain `Model`) and gets the behavior instead of every consumer hand-wiring it: `await page.versions()` (not a query on `history.row_versions`), `await page.restore(3)` (not a `version_restore` RPC + a cache bust — `restore()` busts the cache itself), `Note.alive()` / `.dead()` / `.soft_delete()` / `.undelete()`, and `Page.capabilities()`. Capability flags (`_entity_token`, `_is_versioned`, `_has_soft_delete`, `_is_org_scoped`, `_rls_variant`) are **stamped by the generator from the LIVE DATABASE** (does the table really carry the `_version_capture` trigger? a `deleted_at` column?) — never from `entity_types`' own flags, which are wrong on 61 of its 242 rows. **The database is truth; a flag is a claim.** Using a capability an entity does not declare RAISES (`EntityCapabilityError`) and names the fix — it never returns silently-wrong data, and `is_deleted` refuses to answer from a column a partial fetch never loaded. Drift guard: `scripts/check_entity_drift.py` (loud, non-blocking, in `release.sh`).
+- **`MatrxEntity`** (`matrx_orm/entity.py`) — **the platform entity contract as an ORM primitive.** A table registered in `platform.entity_types` generates as a `MatrxEntity` (everything else stays a plain `Model`) and gets the behavior instead of every consumer hand-wiring it: `await page.versions()` (not a query on `history.row_versions`), `await page.restore(3)` (not a `version_restore` RPC + a cache bust — `restore()` busts the cache itself), `Note.alive()` / `.dead()` / `.soft_delete()` / `.undelete()`, and `Page.capabilities()`. Capability flags (`_entity_token`, `_is_versioned`, `_has_soft_delete`, `_is_org_scoped`, `_rls_variant`) are **stamped by the generator from the LIVE DATABASE** (does the table really carry the `_version_capture` trigger? a `deleted_at` column?) — never from `entity_types`' own flags. **The database is truth; a flag is a claim.** Using a capability an entity does not declare RAISES (`EntityCapabilityError`) and names the fix — it never returns silently-wrong data, and `is_deleted` refuses to answer from a column a partial fetch never loaded. Drift guard: `scripts/check_entity_drift.py` (loud, non-blocking, in `release.sh`).
 - **Optimistic concurrency (`expected_version=`)** — opt-in compare-and-swap on the canonical `version` int column: `update_where` / `update_item` / instance `update()` take `expected_version=N` (`WHERE version = N`, `SET version = N + 1`; 0 rows → `DoesNotExist` if gone, `OptimisticLockError` if changed — carrying the **decision package**: `current_version`, `current_row`, `contested_fields` (current values of ONLY the fields this write attempted), and `changed_by`/`changed_at` from `history.row_versions` where versioned); `bulk_update(..., check_version=True)` guards per row; `MatrxEntity.update_with_rebase` auto-rebases past DISJOINT concurrent writes using `history.row_versions` snapshots. **Never automatic** — an unguarded write stays last-write-wins (the `_touch_row` trigger bumps `version` on every update, so auto-guarding would raise spurious conflicts). Contract: `common-docs/systems/architecture/optimistic-concurrency/FEATURE.md`.
-- **Change tracking** — every instance records which columns were **loaded** (a SELECTed row, or the caller's kwargs) and which were **changed**. `save()` writes only those, so `.only("id","email")` + `save()` can never NULL the columns it never fetched (it used to — silent data loss). Mutable containers (jsonb/arrays) are always rewritten when loaded, because `obj.metadata["k"]=1` cannot be seen by `__setattr__`; **reassigning** (`obj.metadata = {...}`) is tracked precisely and is the sanctioned way. `Model._hydrate()` is the ONE row→model entry point.
-- **Upsert writes only what the caller supplied.** `upsert` / `bulk_upsert` / `upsert_with_conflict` materialize every field's Python default so the **INSERT** half is complete — but `ON CONFLICT DO UPDATE SET` covers **only the columns present in the caller's `data`** (an explicit `update_fields` still wins). Letting defaults reach the UPDATE half silently RESET every defaulted column on each re-upsert of an existing row: it once reset scraped-and-analyzed `research.rs_source` rows to `scrape_status='pending', server_attempts=0` (a watchdog then finalized them `'failed'`) and undid users' manual `is_included=false`. A caller-supplied `None` is excluded too — it is dropped from the INSERT, and `EXCLUDED.<col>` on an omitted column resolves to that column's **DEFAULT**. An upsert of only conflict keys means "ensure this row exists" and reconciles to a no-op self-assignment, never a raise (a bare `DO NOTHING` would break `RETURNING *`). Pinned by `tests/level1/test_upsert_default_leak.py`.
+- **Change tracking** — every instance records which columns were **loaded** (a SELECTed row, or the caller's kwargs) and which were **changed**. `save()` writes only those, so `.only("id","email")` + `save()` can never NULL the columns it never fetched. Mutable containers (jsonb/arrays) are always rewritten when loaded, because `obj.metadata["k"]=1` cannot be seen by `__setattr__`; **reassigning** (`obj.metadata = {...}`) is tracked precisely and is the sanctioned way. `Model._hydrate()` is the ONE row→model entry point.
+- **Upsert writes only what the caller supplied.** `upsert` / `bulk_upsert` / `upsert_with_conflict` materialize every field's Python default so the **INSERT** half is complete — but `ON CONFLICT DO UPDATE SET` covers **only the columns present in the caller's `data`** (an explicit `update_fields` still wins). A caller-supplied `None` is excluded too — it is dropped from the INSERT, and `EXCLUDED.<col>` on an omitted column resolves to that column's **DEFAULT**. An upsert of only conflict keys means "ensure this row exists" and reconciles to a no-op self-assignment, never a raise (a bare `DO NOTHING` would break `RETURNING *`). Pinned by `tests/level1/test_upsert_default_leak.py`.
 - **Read-only models** (`_read_only = True`): a model that can be queried but NEVER written through the ORM — every write path raises `ReadOnlyModelError` (enforced at `QueryExecutor.insert/bulk_insert/upsert/update/delete`, so it covers all of `create`/`save`/`update`/`delete`/`update_where`/`delete_where`/`upsert`/`bulk_*`). Used for DB-managed tables the app must not mutate. The canonical **`auth.users`** model is baked into the schema generator (`get_string_user_model`) as the full, curated Supabase auth schema (safe columns only — no password/token fields), `_read_only`, bound per-database. Read a user's profile/metadata there; mutate users only through Supabase Auth (GoTrue).
-- **Connection-level type codecs** (`async_db_manager._init_connection_default`): every pooled connection decodes **uuid → `str`**, **vector → `list[float]`**, and **json/jsonb → `dict`/`list`** at the driver boundary — the TYPE decides the decode, never the call path. So `call_function` scalar/rows, raw fetches, and field hydration all agree; a caller must **never `json.loads` a fetched json/jsonb value** (it's already decoded; the 2026-07-13 `build_agent_context` crash was a jsonb RPC fetched pre-codec as a raw string). Encoding: a pre-serialised JSON `str` passes through untouched; a native dict/list is dumped (`_encode_json`). Pinned by `tests/level1/test_connection_codecs.py`.
+- **Connection-level type codecs** (`async_db_manager._init_connection_default`): every pooled connection decodes **uuid → `str`**, **vector → `list[float]`**, and **json/jsonb → `dict`/`list`** at the driver boundary — the TYPE decides the decode, never the call path. So `call_function` scalar/rows, raw fetches, and field hydration all agree; a caller must **never `json.loads` a fetched json/jsonb value** (it's already decoded). Encoding: a pre-serialised JSON `str` passes through untouched; a native dict/list is dumped (`_encode_json`). Pinned by `tests/level1/test_connection_codecs.py`.
 - **Connection pools are event-loop-owned.** `AsyncDatabaseManager.get_pool()` recreates a pool when a caller arrives on a different loop. If the former owner loop is already closed, stale-pool termination and cleanup discard that pool without trying to schedule callbacks onto the dead loop; unrelated runtime errors still raise. Pinned by `tests/level1/test_pool_loop_recreation.py`.
 - **Exception diagnostics never read source files.** `ORMException` captures compact caller metadata by walking live frames; `traceback.extract_stack()` is forbidden because its `linecache` filesystem checks can stall an async server. Contract: [`matrx_orm/FEATURE.md`](matrx_orm/FEATURE.md).
 - **A zero-connection pool is dead, not busy.** After bounded SQL-safe acquire retries, `AsyncDatabaseManager.get_connection()` atomically replaces a pool whose physical size is still zero, then tries once against the replacement. It never replaces a busy `size > 0` pool. Contract: [`matrx_orm/core/FEATURE.md`](matrx_orm/core/FEATURE.md).
@@ -51,9 +51,9 @@ Every table that becomes a Model needs row identity: a single-column primary key
 - **Signals**: `pre_create`, `post_create`, `pre_save`, `post_save`, `pre_delete`, `post_delete`.
 - **Schema builder** (`matrx_orm.schema_builder`): code generation for Python + TypeScript type definitions from the DB schema. Postgres **VIEWs** are emitted as **read-only `Model` classes** into the same schema models file (on by default; per-entry `output.include_views: false` opts a schema out, `output.exclude_views: [...]` skips individual views). View models get no manager/DTO/base-class/auto_config (views are not writable), synthesize `_primary_keys` from an `id` column (else the first column, for cache-key/`load_by_id` only), and emit plain typed fields with **no `ForeignKey`** (views carry no FK metadata — nothing cross-schema to resolve). Never hand-write a view model again.
 - **Secrets battery** (`matrx_orm.secrets_battery`): the ONE canonical user-credential vault — `users.user_secrets` CRUD + the platform's single Fernet primitive, keyed by `CREDENTIALS_ENCRYPTION_KEY`. Any package: `configure_secrets(db_config_name=...)` once, then `await require_user_secret(user_id, key)`. No package ever calls another service to resolve a credential. Contract: [`matrx_orm/secrets_battery/FEATURE.md`](matrx_orm/secrets_battery/FEATURE.md).
-- **Polymorphic associations** (`matrx_orm.associations`): `EntityRegistry` (token→Model) + `Associations` — a registry-driven, **access-gated** edge engine over a host's polymorphic edge table. Every `source→target` hop is org-scoped *and* each resolved endpoint is re-authorized against the ACTOR (fail-closed, screams on a genuine leak), so a hop can't widen access past what the actor may reach. 🚨 **The gate is `access_check` (wire `matrx_orm.platform_access_check` → `iam.has_access_for`), NEVER an org-column comparison** — a person belongs to several orgs on purpose, so org-equality denies her own data across her own workspaces (2026-08-30 incident) while granting any co-member of a private row. The edge's `org_id` is a TENANCY stamp, not a permission. Org-equality survives only for UNATTENDED writes (no actor) as an integrity guard, and **system vocabulary is exempt entirely** (existence still required): a model generated with `_rls_variant="system"` is platform-shared dictionary data (seo.keyword/topic) every tenant legitimately links to. Hardcodes no table names — the host wires its own edge + token-registry models. A token whose rows have no Model (a record store's Records) resolves to an **entity door** (`is_entity_door`: `load_by_ids(ids, *, actor_id)`), read as the actor — never by a service identity.
+- **Polymorphic associations** (`matrx_orm.associations`): `EntityRegistry` (token→Model) + `Associations` — a registry-driven, **access-gated** edge engine over a host's polymorphic edge table. Every `source→target` hop is org-scoped *and* each resolved endpoint is re-authorized against the ACTOR (fail-closed, screams on a genuine leak), so a hop can't widen access past what the actor may reach. 🚨 **The gate is `access_check` (wire `matrx_orm.platform_access_check` → `iam.has_access_for`), NEVER an org-column comparison** — a person belongs to several orgs on purpose, so org-equality denies her own data across her own workspaces while granting any co-member of a private row. The edge's `org_id` is a TENANCY stamp, not a permission. Org-equality survives only for UNATTENDED writes (no actor) as an integrity guard, and **system vocabulary is exempt entirely** (existence still required): a model generated with `_rls_variant="system"` is platform-shared dictionary data (seo.keyword/topic) every tenant legitimately links to. Hardcodes no table names — the host wires its own edge + token-registry models. A token whose rows have no Model (a record store's Records) resolves to an **entity door** (`is_entity_door`: `load_by_ids(ids, *, actor_id)`), read as the actor — never by a service identity.
 - **The host's declared session context** (`matrx_orm.core.session_context`): `configure_session_context(provider)` once at startup, and every **top-level** `transaction()` — including the one `rls_session` opens, before it drops to the restricted role — emits whatever the provider returns as transaction-local GUCs. This is how an application-level declaration reaches Postgres at all: a GUC set outside a transaction has no meaning, so the BEGIN is the only place it can land. aidream wires it to its provenance declaration (`app.actor_tier` / `app.actor_system`, read by `platform.actor_tier()`, the history capture and the tier rule). A nested entry is a savepoint inside a transaction that already carries them and emits nothing. A standalone write (`execute_write` outside any transaction) made while the provider has something to say opens its own transaction for that one statement — and still goes through the write queue, inside a copy of the caller's context, so the queue's concurrency gate is kept and the drain task's foreign context cannot hide the declaration (`tests/level1/test_standalone_write_session_context.py`). No provider configured ⇒ no GUCs (standalone behavior unchanged); a provider that raises fails the transaction loudly rather than committing rows with a false provenance.
-- **The platform access policy** (`matrx_orm.platform_access`): `platform_access_check(actor, token, id, level)` → `iam.has_access_for`. The ONE answer to "may this actor touch this row?", shared with RLS and the file-access gate. Fails closed. Never re-derive it from `organization_id` or `created_by` — both are strict subsets that deny legitimate access.
+- **The platform access policy** (`matrx_orm.platform_access`): `platform_access_check(actor, token, id, level)` → `iam.has_access_for`. The ONE answer to "may this actor touch this row?", shared with RLS and the file-access gate. Fails closed by default; `raise_on_error=True` keeps genuine denial false but raises `PlatformAccessUnavailableError` when the policy cannot be called. Never re-derive it from `organization_id` or `created_by` — both are strict subsets that deny legitimate access.
 
 Public API is defined explicitly in `matrx_orm/__init__.py` (100+ exports). Treat changes there as semver-breaking.
 
@@ -126,9 +126,7 @@ command is `uv run python db/generate.py --schema <schema> --models-only`.
 is the entire `from db.models import X` surface; it is always written from the FULL,
 unfiltered `generate[]` list, never from the `only_schemas` subset — and model names for
 schemas the run did not regenerate are read back from their modules on disk (AST, no
-import) so cross-schema collision de-flattening stays complete. Writing it from a subset
-once truncated it to one schema and broke imports repo-wide, silently at generation time
-(hand-repaired in 79505fee8). `_write_host_models_aggregator` now RAISES
+import) so cross-schema collision de-flattening stays complete. `_write_host_models_aggregator` now RAISES
 `AggregatorShrinkError` naming every schema that would be lost, and writes nothing.
 Guard: `tests/schema_builder/test_host_models_aggregator.py`.
 
@@ -162,22 +160,13 @@ enforced in code:
    as stale (`ModelState.sweep_stale`, every `STALE_SWEEP_EVERY_WRITES`); an
    append-only writer of big JSON passes `returning=[...]` to `upsert` /
    `bulk_create` (or uses `insert_returning`) so its rows are neither read back
-   nor cached. Before this an unread entry lived for the whole process, and a
-   workflow worker's checkpoints/outcomes/events grew it until ECS killed the
-   task for memory (MKT-111, 2026-10-15). The sweep pops oldest-first and stops at
+   nor cached. The sweep pops oldest-first and stops at
    the first fresh entry, and `cache_bulk` yields the loop once per sweep window, so
-   caching a big read never stalls the server (a full-scan sweep froze it 2-6 s on a
-   21k-row read, 2026-10-17). Guards: `tests/test_state_cache_sweeps_stale.py`,
+   caching a big read never stalls the server. Guards: `tests/test_state_cache_sweeps_stale.py`,
    `tests/test_a_bulk_cache_never_stalls_the_loop.py`.
 
-This is not theoretical hygiene. On 2026-07-25 rule 1 was missing: `session/flush.py`
-builds a `{pk + payload}` stub per queued UPDATE and `bulk_update` cached it, so a
-chat conversation read back with `organization_id = None` right after its own
-turn-1 title/`message_count` UPDATE flushed — and aidream stopped the user's next
-turn on a value Postgres had held correctly the entire time. Guards:
-`tests/session/test_cache_no_downgrade.py`.
+The no-downgrade guard is `tests/session/test_cache_no_downgrade.py`.
 
 ## Known issues
 
-- **No CLAUDE.md existed before this commit** — that was the main gap.
-- Otherwise this package is the reference-quality standalone package in the monorepo. See root `PACKAGES_MIGRATION_PLAN.md` if any new gaps emerge.
+Package migration gaps are tracked in the root `PACKAGES_MIGRATION_PLAN.md`.

{matrx_orm-3.1.255 → matrx_orm-3.1.256}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matrx-orm
-Version: 3.1.255
+Version: 3.1.256
 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.255 → matrx_orm-3.1.256}/matrx_orm/__init__.py

@@ -49,6 +49,7 @@ from .platform_access import (
     PermissionLevel,
     configure_platform_access,
     permission_level_rank,
+    PlatformAccessUnavailableError,
     platform_access_check,
     platform_accessible_ids,
     platform_edge_requirement,
@@ -439,6 +440,7 @@ __all__ = [
     "register_database",
     "register_database_from_env",
     "register_platform_db",
+    "PlatformAccessUnavailableError",
     "platform_access_check",
     "platform_accessible_ids",
     "configure_platform_access",

{matrx_orm-3.1.255 → matrx_orm-3.1.256}/matrx_orm/platform_access.py

@@ -169,11 +169,17 @@ def _resolve_database() -> str:
         raise
 
 
+class PlatformAccessUnavailableError(RuntimeError):
+    """The canonical policy could not be evaluated."""
+
+
 async def platform_access_check(
     actor_id: str,
     entity_token: str,
     entity_id: str,
     required_level: str = "viewer",
+    *,
+    raise_on_error: bool = False,
 ) -> bool:
     """Return whether ``actor_id`` may reach ``entity_token:entity_id``.
 
@@ -190,7 +196,8 @@ async def platform_access_check(
     raise escapes them as a 500 on an unrelated code path. The FIRST failure
     screams (a wiring bug must never be quiet), and
     :func:`verify_platform_access_wiring` exists so startup catches it before a
-    user does.
+    user does. ``raise_on_error=True`` preserves a policy False but raises a fixed
+    unavailable error when the policy cannot be evaluated.
     """
     if not actor_id or not entity_token or not entity_id:
         return False
@@ -227,6 +234,8 @@ async def platform_access_check(
                 "This message prints once per process.",
                 color="red",
             )
+        if raise_on_error:
+            raise PlatformAccessUnavailableError("Access policy is temporarily unavailable.") from None
         return False
 
 

{matrx_orm-3.1.255 → matrx_orm-3.1.256}/matrx_orm/query/FEATURE.md

@@ -15,6 +15,16 @@ request in the process.
 
 `compile()` remains deliberately synchronous for synchronous callers.
 
+## Row-lock strength
+
+`Model.filter(...).select_for_update()` retains `FOR UPDATE` by default;
+`select_for_update(mode="SHARE")` emits `FOR SHARE` through the same query and
+terminal paths. The keyword-only mode accepts only `UPDATE` or `SHARE`;
+`of`, `nowait`, and `skip_locked` apply to either mode. Use row locks inside
+the transaction that consumes the protected rows. SQL compilation checks are
+in `tests/level1/test_row_lock_modes.py`; they do not establish database lock
+compatibility or transaction lifetime.
+
 ## Large scans and the identity cache
 
 `.all()` populates `StateManager` by default so ordinary repeated identity reads
@@ -85,20 +95,15 @@ resource authorization; ordinary `get()` remains read-your-own-writes.
 `count()`, `update()` and `delete()` rebuild SQL from the WHERE tail that
 `_extract_where_clause` peels off the built SELECT. That peel drops the
 SELECT's trailing clauses, so `_prune_param_refs` drops the binds that belonged
-to them and renumbers the survivors `$1..$k`. Without it,
-`Model.filter().limit(1).count()` shipped `SELECT COUNT(*) …` (no placeholders)
-with LIMIT's bind still attached and asyncpg raised *the server expects 0
-arguments for this query, 1 was passed* — surfaced as `CacheError`, and it
-hard-500'd `GET /rag/admin/overview` until 2026-09-12. Invariant:
+to them and renumbers the survivors `$1..$k`. Invariant:
 `_max_param_ref(sql) == len(params)` for every emitted statement
 (`tests/level1/test_count_limit_param_leak.py`).
 
 ## One predicate family per expression
 
 `Q` composes with `Q`; a typed `Predicate` composes with a `Predicate`. Mixing
-them (`Q(a=1) | Is(F("x"), None)`) raises `TypeError` naming the remedy — it
-used to build a Q holding a Predicate child and die later with `'Is' object has
-no attribute 'kwargs'`. `Filter` accepts direct aggregate calls only:
+them (`Q(a=1) | Is(F("x"), None)`) raises `TypeError` naming the remedy.
+`Filter` accepts direct aggregate calls only:
 `Aggregate` subclasses and the explicit two-expression `JsonbObjectAgg`.
 `JsonbObjectAgg` is accepted because PostgreSQL permits
 `jsonb_object_agg(...) FILTER (WHERE ...)`, even though it cannot inherit the
@@ -116,31 +121,10 @@ rewrites the next `update()` to `WHERE pk IN (SELECT pk FROM t WHERE <filters>
 ORDER BY pk FOR UPDATE)`. Use it on any multi-row UPDATE that concurrent callers
 can run over an OVERLAPPING row set.
 
-Sorting the id array the caller passed does NOT fix this — the PLAN decides lock
-order, not the array. `= ANY($1)` may become a seq scan, which locks in heap
-order, and heap order MOVES because these very updates rewrite the rows they
-scan. Two copies of the same statement then take the same locks in opposite
-orders and Postgres kills one (40P01): four parallel `ai.agent.start`
-invocations stamping `last_used_at` on one org's ~185 `users.user_secrets` rows
-errored a live workflow run on 2026-09-12. Ordering inside a `FOR UPDATE`
-sub-select is the only form that pins acquisition order (`LockRows` sits above
-the `Sort`), and it stays ONE statement — a 185-row telemetry write does not
-become 185 round trips. Requires a single-column primary key and an unaliased
-target; both refuse loudly. A non-SQL adapter cannot express it and says so
-rather than dropping the guard silently. Guard:
-`tests/level1/test_deadlock_retry.py`.
-
-## Change log
-
-- 2026-09-12 — Added `lock_rows_in_pk_order()`: a multi-row UPDATE can take its
-  row locks ascending by primary key instead of in plan-scan order.
-- 2026-09-12 — Rebuilt statements prune unreferenced binds; Q/Predicate mixing
-  and invalid wrapped `Filter` targets are refused at construction, while
-  direct `JsonbObjectAgg` FILTER expressions remain valid.
-- 2026-09-10 — Projection follows caller order: `select`/`values` no longer
-  reversed, `only()` no longer hash-ordered.
-- 2026-08-31 — Kept tuple-valued collection lookups as one array bind parameter.
-- 2026-08-28 — Added persisted-state counts that bypass pending-row hydration.
-- 2026-08-18 — Moved async terminal SQL compilation off the event loop.
-- 2026-08-15 — Moved bulk hydration off the event loop, made complete-primary-key
-  misses constant-time, and documented cache bypass for request-local scans.
+Sorting the caller's id array does not control lock order: the query plan does.
+A sequential scan locks in heap order, which updates can change. Concurrent
+statements can acquire overlapping locks in opposite orders and deadlock
+(40P01). Ordering inside a `FOR UPDATE` sub-select pins acquisition order
+(`LockRows` sits above `Sort`) in one statement. Requires a single-column
+primary key and an unaliased target; unsupported targets and adapters fail
+explicitly. Guard: `tests/level1/test_deadlock_retry.py`.

{matrx_orm-3.1.255 → matrx_orm-3.1.256}/matrx_orm/query/builder.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import asyncio
 import re
-from typing import TYPE_CHECKING, Any, Generic, TypeVar
+from typing import TYPE_CHECKING, Any, Generic, Literal, TypeVar
 
 from matrx_utils import vcprint
 
@@ -550,13 +550,22 @@ class QueryBuilder(Generic[ModelT]):
         nowait: bool = False,
         skip_locked: bool = False,
         of: list[str] | None = None,
+        *,
+        mode: Literal["UPDATE", "SHARE"] = "UPDATE",
     ) -> QueryBuilder[ModelT]:
-        """Append ``FOR UPDATE [NOWAIT | SKIP LOCKED] [OF ...]`` to the query.
+        """Append ``FOR UPDATE|SHARE [OF ...] [NOWAIT | SKIP LOCKED]`` to the query.
 
         Must be used inside a transaction.
         """
+        if mode not in ("UPDATE", "SHARE"):
+            raise ValueError("Row-lock mode must be UPDATE or SHARE")
         new = self._clone()
-        new.for_update_opts = {"nowait": nowait, "skip_locked": skip_locked, "of": of or []}
+        new.for_update_opts = {
+            "nowait": nowait,
+            "skip_locked": skip_locked,
+            "of": of or [],
+            "mode": mode,
+        }
         return new
 
     def lock_rows_in_pk_order(self) -> QueryBuilder[ModelT]:

{matrx_orm-3.1.255 → matrx_orm-3.1.256}/matrx_orm/query/executor.py

@@ -51,6 +51,7 @@ _TOP_LEVEL_WHERE_STOPPERS = (
     "LIMIT",
     "OFFSET",
     "FOR UPDATE",
+    "FOR SHARE",
 )
 
 
@@ -937,19 +938,22 @@ class QueryExecutor:
             sql += f" OFFSET ${len(params) + 1}"
             params.append(self._full_query_dict["offset"])
 
-        # -- FOR UPDATE -------------------------------------------------
+        # -- Row locks --------------------------------------------------
         for_update = self._full_query_dict.get("for_update")
         if for_update:
-            clause = " FOR UPDATE"
-            if for_update.get("nowait"):
-                clause += " NOWAIT"
-            elif for_update.get("skip_locked"):
-                clause += " SKIP LOCKED"
+            mode = for_update.get("mode", "UPDATE")
+            if mode not in ("UPDATE", "SHARE"):
+                raise ValueError("Row-lock mode must be UPDATE or SHARE")
+            clause = " FOR " + mode
             of_tables = for_update.get("of", [])
             if of_tables:
                 from matrx_orm.core.expressions import F
 
                 clause += " OF " + ", ".join(F(table).field_name for table in of_tables)
+            if for_update.get("nowait"):
+                clause += " NOWAIT"
+            elif for_update.get("skip_locked"):
+                clause += " SKIP LOCKED"
             sql += clause
 
         if debug:

{matrx_orm-3.1.255 → matrx_orm-3.1.256}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.255"
+version = "3.1.256"
 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.256/tests/level1/test_row_lock_modes.py

@@ -0,0 +1,138 @@
+"""The public model query must carry its chosen lock mode to the SQL adapter.
+
+Only the external database is replaced. SQL compilation, cloning, async terminals
+and model hydration remain real; literal SQL is the independent oracle.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+from matrx_orm.adapters import AdapterRegistry
+from matrx_orm.core.base import Model, ModelMeta
+from matrx_orm.core.fields import IntegerField, TextField
+from matrx_orm.query.executor import QueryExecutor
+
+
+class _CapturingDatabase:
+    def __init__(self) -> None:
+        self.calls: list[tuple[str, tuple[Any, ...]]] = []
+
+    async def execute_query_dict(self, query: dict[str, Any]) -> Any:
+        return NotImplemented
+
+    async def execute_query(self, sql: str, *params: Any) -> list[dict[str, Any]]:
+        self.calls.append((sql, params))
+        if sql.startswith("SELECT COUNT(*)"):
+            return [{"count": 2}]
+        return [{"id": 17, "name": "Harbor Dental"}]
+
+
+@pytest.fixture
+def query_surface(monkeypatch: pytest.MonkeyPatch) -> tuple[type[Model], _CapturingDatabase]:
+    model = ModelMeta("RowLockPractice", (Model,), {
+        "id": IntegerField(primary_key=True),
+        "name": TextField(),
+        "_database": "row_lock_offline",
+        "_table_name": "practice",
+    })
+    database = _CapturingDatabase()
+    monkeypatch.setattr(AdapterRegistry, "get", classmethod(lambda cls, name: database))
+    return model, database
+
+
+@pytest.mark.parametrize(("options", "suffix"), [
+    ({}, "FOR UPDATE"),
+    ({"mode": "UPDATE"}, "FOR UPDATE"),
+    ({"mode": "SHARE"}, "FOR SHARE"),
+    ({"mode": "SHARE", "nowait": True}, "FOR SHARE NOWAIT"),
+    ({"mode": "UPDATE", "skip_locked": True}, "FOR UPDATE SKIP LOCKED"),
+    ({"mode": "SHARE", "skip_locked": True}, "FOR SHARE SKIP LOCKED"),
+    ({"mode": "UPDATE", "of": ["practice"], "nowait": True}, "FOR UPDATE OF practice NOWAIT"),
+    ({"mode": "SHARE", "of": ["practice"], "nowait": True}, "FOR SHARE OF practice NOWAIT"),
+    ({"mode": "SHARE", "of": ["practice"], "skip_locked": True}, "FOR SHARE OF practice SKIP LOCKED"),
+    # Existing precedence is retained when both wait options are supplied.
+    ({"mode": "SHARE", "nowait": True, "skip_locked": True}, "FOR SHARE NOWAIT"),
+])
+def test_compile_preserves_selected_mode_and_wait_options(query_surface, options, suffix):
+    model, _ = query_surface
+    query = model.filter(id=17).select_for_update(**options).order_by("id").limit(2)
+    assert query.compile("id") == (
+        "SELECT id FROM public.practice WHERE id = $1 ORDER BY id ASC LIMIT $2 " + suffix,
+        [17, 2],
+    )
+
+
+def test_existing_positional_lock_options_still_compile(query_surface):
+    model, _ = query_surface
+    assert model.filter().select_for_update(True, False, ["practice"]).compile() == (
+        "SELECT * FROM public.practice FOR UPDATE OF practice NOWAIT", [],
+    )
+
+
+def test_lock_branches_do_not_change_the_base_or_each_other(query_surface):
+    model, _ = query_surface
+    base = model.filter(id=17)
+    shared = base.select_for_update(mode="SHARE")
+    updated = shared.select_for_update().order_by("id")
+    assert base.compile() == ("SELECT * FROM public.practice WHERE id = $1", [17])
+    assert shared.compile() == ("SELECT * FROM public.practice WHERE id = $1 FOR SHARE", [17])
+    assert updated.compile() == (
+        "SELECT * FROM public.practice WHERE id = $1 ORDER BY id ASC FOR UPDATE", [17],
+    )
+
+
+@pytest.mark.parametrize("mode", ["SHARE", "UPDATE"])
+@pytest.mark.parametrize("terminal", ["values", "all"])
+async def test_async_terminal_sends_lock_to_database(query_surface, mode, terminal):
+    model, database = query_surface
+    query = model.filter(id=17).select_for_update(mode=mode).order_by("id")
+    if terminal == "values":
+        assert await query.values("id", "name") == [{"id": 17, "name": "Harbor Dental"}]
+        projection = "id, name"
+    else:
+        rows = await query.all(use_cache=False)
+        assert [(row.id, row.name) for row in rows] == [(17, "Harbor Dental")]
+        projection = "*"
+    assert database.calls == [(
+        f"SELECT {projection} FROM public.practice WHERE id = $1 ORDER BY id ASC FOR {mode}",
+        (17,),
+    )]
+
+
+@pytest.mark.parametrize("mode", ["SHARE", "UPDATE"])
+async def test_count_rebuild_drops_lock_suffix_without_leaking_params(query_surface, mode):
+    model, database = query_surface
+    result = await model.filter(id=17).select_for_update(mode=mode).count()
+    assert result == 2
+    assert database.calls == [("SELECT COUNT(*) as count FROM public.practice WHERE id = $1", (17,))]
+
+
+@pytest.mark.parametrize("mode", ["share", "NO KEY UPDATE", "SHARE; SELECT 1", "", None, 1])
+def test_builder_refuses_unrecognized_lock_mode(query_surface, mode):
+    model, _ = query_surface
+    with pytest.raises(ValueError, match="Row-lock mode must be UPDATE or SHARE"):
+        model.filter().select_for_update(mode=mode)
+
+
+def test_executor_refuses_mode_injected_through_query_dictionary(query_surface):
+    model, database = query_surface
+    query = model.filter().select_for_update()._build_query()
+    query["for_update"]["mode"] = "SHARE; SELECT 1"
+    with pytest.raises(ValueError, match="Row-lock mode must be UPDATE or SHARE"):
+        QueryExecutor(query)
+    assert database.calls == []
+
+
+def test_legacy_query_dictionary_defaults_to_update(query_surface):
+    model, _ = query_surface
+    query = model.filter()._build_query()
+    query["for_update"] = {"nowait": True}
+    assert QueryExecutor(query).query == "SELECT * FROM public.practice FOR UPDATE NOWAIT"
+
+
+def test_lock_table_identifier_is_validated(query_surface):
+    model, _ = query_surface
+    with pytest.raises(ValueError, match="Unsafe field reference"):
+        model.filter().select_for_update(mode="SHARE", of=["practice; SELECT 1"]).compile()

matrx_orm-3.1.256/tests/test_platform_access_strict.py

@@ -0,0 +1,38 @@
+"""The strict opt-in distinguishes policy denial from unavailable authority."""
+
+import asyncio
+from unittest.mock import AsyncMock
+
+import pytest
+from matrx_orm import PlatformAccessUnavailableError
+from matrx_orm import platform_access as access
+from matrx_orm.core import db_function
+
+
+@pytest.mark.parametrize("strict", [False, True])
+async def test_real_policy_false_is_denial(monkeypatch, strict):
+    monkeypatch.setattr(access, "_resolve_database", lambda: "test")
+    call = AsyncMock(return_value=False)
+    monkeypatch.setattr(db_function, "call_function", call)
+    assert not await access.platform_access_check("actor", "record", "id", raise_on_error=strict)
+    assert call.await_count == 1
+
+
+async def test_actual_invocation_failure_raises_only_for_strict(monkeypatch):
+    monkeypatch.setattr(access, "_resolve_database", lambda: "test")
+    monkeypatch.setattr(access, "_policy_failure_announced", True)
+    call = AsyncMock(side_effect=ConnectionError("private transport diagnostic"))
+    monkeypatch.setattr(db_function, "call_function", call)
+    assert not await access.platform_access_check("actor", "record", "id")
+    with pytest.raises(
+        PlatformAccessUnavailableError, match="^Access policy is temporarily unavailable.$"
+    ):
+        await access.platform_access_check("actor", "record", "id", raise_on_error=True)
+    assert call.await_count == 2
+
+
+async def test_cancel_propagates(monkeypatch):
+    monkeypatch.setattr(access, "_resolve_database", lambda: "test")
+    monkeypatch.setattr(db_function, "call_function", AsyncMock(side_effect=asyncio.CancelledError))
+    with pytest.raises(asyncio.CancelledError):
+        await access.platform_access_check("actor", "record", "id", raise_on_error=True)