matrx-orm 3.1.236__tar.gz → 3.1.238__tar.gz

{matrx_orm-3.1.236 → matrx_orm-3.1.238}/BASE_CLASS_METHODS.md

@@ -508,7 +508,7 @@ for want of this (`packages/matrx-rag/matrx_rag/search.py::_entity_recall` /
   `ArrayAny`, `Exists`, or an `&` / `|` / `~` composition).
 - `then=` / `default=` — a bound literal or typed expression (`F`, another
   `Func`, a nested `Case`, ...). `default=None` omits the `ELSE` clause entirely
-  (Postgres already evaluates an unmatched `CASE` to `NULL` — behaviourally identical to
+  (Postgres already evaluates an unmatched `CASE` to `NULL` — behaviorally identical to
   an explicit `ELSE NULL`, so there's no ambiguity with "no default supplied").
 
 Composable anywhere an expression with `.as_sql(params)` is accepted:

{matrx_orm-3.1.236 → matrx_orm-3.1.238}/CLAUDE.md

@@ -52,7 +52,7 @@ Every table that becomes a Model needs row identity: a single-column primary key
 - **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.
-- **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 behaviour unchanged); a provider that raises fails the transaction loudly rather than committing rows with a false provenance.
+- **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.
 
 Public API is defined explicitly in `matrx_orm/__init__.py` (100+ exports). Treat changes there as semver-breaking.

{matrx_orm-3.1.236 → matrx_orm-3.1.238}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matrx-orm
-Version: 3.1.236
+Version: 3.1.238
 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
@@ -26,7 +26,7 @@ Requires-Dist: asyncpg>=0.31.0
 Requires-Dist: cbor2<7,>=6.1.3
 Requires-Dist: cryptography>=43.0
 Requires-Dist: gitpython>=3.1.40
-Requires-Dist: matrx-utils>=2.0.77
+Requires-Dist: matrx-utils>=2.0.78
 Requires-Dist: psycopg-pool>=3.2.5
 Requires-Dist: psycopg[binary]>=3.2.5
 Requires-Dist: python-dotenv>=1.0

{matrx_orm-3.1.236 → matrx_orm-3.1.238}/matrx_orm/adapters/async_postgresql.py

@@ -7,7 +7,7 @@ explicit adapter is registered for a given database project.
 
 All the real work (pool creation, write-queue routing, exponential-backoff retry,
 pgvector codec registration, event-loop lifecycle) stays in ``AsyncDatabaseManager``
-so existing behaviour is 100% preserved. This class is a thin, config-scoped
+so existing behavior is 100% preserved. This class is a thin, config-scoped
 delegation layer.
 """
 

{matrx_orm-3.1.236 → matrx_orm-3.1.238}/matrx_orm/associations.py

@@ -53,7 +53,7 @@ because the upload had silently landed in an organization picked for him while t
 conversation was in a team org. Both rows were his; the platform policy said yes
 to both; the edge write said no.)
 
-Hosts without an ``access_check`` wired keep the legacy org-equality behaviour
+Hosts without an ``access_check`` wired keep the legacy org-equality behavior
 for UNATTENDED writes only (no actor in context) — those are trusted server
 paths where the check was never an authorization decision to begin with.
 
@@ -278,7 +278,7 @@ class Associations:
         # restore brings exactly those edges back. Where the column exists EVERY
         # read here is live-only — a tombstoned edge conveys nothing, so handing
         # one back is an access leak. A minimal host edge table without the
-        # column keeps the old unfiltered behaviour.
+        # column keeps the old unfiltered behavior.
         self._soft_delete = soft_delete_field
         self._soft_delete_available = False  # refined by _validate_field_bindings
         # Optional edge-document columns (platform.associations carries them;
@@ -697,7 +697,7 @@ class Associations:
         round trips: measured 2026-09-18 against the live database on a
         3-connection pool, one Library of 533 YouTube sources spent **177 s in
         533 identical single-row SELECTs** out of a 182 s call — and the media
-        catalogue makes that call three times per selection job. The gate
+        catalog makes that call three times per selection job. The gate
         itself is unchanged and still runs per row; only the FETCH is batched,
         so nothing about what survives this method moved. Guard:
         ``packages/matrx-orm/tests/level1/test_associations.py::

{matrx_orm-3.1.236 → matrx_orm-3.1.238}/matrx_orm/core/FEATURE.md

@@ -60,7 +60,7 @@ Added 2026-09-12 after a 1.1 MB `workflow.checkpoint` row timed out at 10s under
 load and killed a paid-for workflow run. Guard:
 `tests/level1/test_query_timeout.py::TestInsertStatementTimeout`.
 
-**A statement the SERVER cancelled to break a lock collision is re-issued — the
+**A statement the SERVER canceled to break a lock collision is re-issued — the
 second and last replay-safe failure, and it covers READS.** SQLSTATE `40P01`
 (`deadlock_detected`), `40001` (`serialization_failure`) and `55P03`
 (`lock_not_available`) are the statuses where Postgres aborted the statement IN
@@ -69,7 +69,7 @@ at-least-once hazard that makes a statement timeout or a mid-query disconnect
 unretryable. Class-40 siblings stay out by name — `40003`
 (`StatementCompletionUnknownError`) is literally "the server cannot say whether
 this completed", and `40002` is a constraint failure wearing a class-40 code.
-The victim is often innocent of any write: a multi-table READ is cancelled
+The victim is often innocent of any write: a multi-table READ is canceled
 whenever a concurrent DDL session wants AccessExclusiveLock on a table it already
 holds a lock on, which reached a person as "listConversations: deadlock detected"
 on /chat.
@@ -401,7 +401,7 @@ what is exhausted or hung when a watchdog needs to speak.
 - 2026-10-01: `ReadWriteConnection` rolls back a stranger's open transaction it was handed (statement reply or 25001 on BEGIN), re-runs our statement in its own transaction, and names a repeat `InheritedTransactionError`.
 - 2026-10-01: `ReadWriteConnection` for transaction-mode pools — every BEGIN declares READ WRITE and a read-only-refused autocommit statement re-runs once in one; a pooled backend another client left read-only at session level no longer fails the platform's writes.
 - 2026-09-30: Fewer round trips per request (agent-launch latency, lane deep): one-statement proof of a clean empty read; ceilings + declared context + `rls_session` settings in ONE BEGIN-time `set_config` statement (`transaction(opening_gucs=)`, `set_local_gucs`, `emit_local_gucs`); transaction-mode pools release with no reset statement. 435 → ~200 round trips on a flashcard launch.
-- 2026-09-30: `statement_ceiling.py` — a driver timeout above the server's statement ceiling is logged once per call site; `SERVER_CEILING` sentinel. ~19 callers passed 60-600 s under the 30 s `postgres` ceiling (the nightly keyword classifier was cancelled at 30 s for eight days).
+- 2026-09-30: `statement_ceiling.py` — a driver timeout above the server's statement ceiling is logged once per call site; `SERVER_CEILING` sentinel. ~19 callers passed 60-600 s under the 30 s `postgres` ceiling (the nightly keyword classifier was canceled at 30 s for eight days).
 - 2026-09-12 (later): ONE retry mechanism. Two independent lock-retry
   implementations for the same class landed hours apart — a `LockContentionError`
   + constant-budget loop inside `execute_query`, and a `TransientTransactionError`
@@ -410,7 +410,7 @@ what is exhausted or hung when a watchdog needs to speak.
   55P03 too), the loop lives once in `write_retry.run_with_lock_retry` and is used
   by `execute_query` AND `call_function`, its budget is the `orm.write_retry`
   knob rows (never a constant), and `TransientTransactionError` is deleted.
-- 2026-09-12: A statement Postgres cancelled to break a lock collision
+- 2026-09-12: A statement Postgres canceled to break a lock collision
   (40P01/40001/55P03) is re-issued on a fresh connection instead of failing the
   caller. Before this it fell to the catch-all as `UnknownDatabaseError` and
   killed the request: four parallel `ai.agent.start` invocations deadlocked on

{matrx_orm-3.1.236 → matrx_orm-3.1.238}/matrx_orm/core/TASKS.md

@@ -3,7 +3,7 @@
 ## Done (this session)
 - Added `TYPE_CHECKING`-guarded `__get__` overloads to all major field classes so that
   accessing a field on a model instance returns the correct Python type to static
-  analysers (pyright, mypy) without any runtime behaviour change:
+  analyzers (pyright, mypy) without any runtime behavior change:
   - `Field` → `Any`
   - `CharField`, `TextField` → `str | None`
   - `UUIDField` → `str | None`

{matrx_orm-3.1.236 → matrx_orm-3.1.238}/matrx_orm/core/async_db_manager.py

@@ -144,8 +144,8 @@ READ_TIMEOUT_RETRIES = 1  # extra attempts for a timed-out read; total = 1 + thi
 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
+# Postgres breaks a lock cycle by CANCELING one party, and the victim is rolled
+# back IN FULL — no part of the canceled 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.
 #
@@ -437,7 +437,7 @@ async def _transaction_pool_release(_conn: Any) -> None:
     laptop's 170 ms). asyncpg still rolls back an open transaction before this
     hook (``Connection._reset``), and a session-mode pool keeps the full default
     reset. ``RESET ALL`` never reset a borrowed ROLE either (``role`` is
-    ``GUC_NO_RESET_ALL``) — that defence is ``pooler_role``.
+    ``GUC_NO_RESET_ALL``) — that defense is ``pooler_role``.
     """
     return None
 
@@ -562,7 +562,7 @@ class AsyncDatabaseManager:
 
                 if pool_loop_id != current_loop_id:
                     # Pool is from a different event loop. It cannot be awaited
-                    # or directly cancelled from this loop; stop its controller
+                    # or directly canceled from this loop; stop its controller
                     # on the owner loop when possible, then terminate the pool.
                     old_pool = cls._pools[config_name]
                     old_task = cls._keepalive_tasks.pop(config_name, None)
@@ -1200,7 +1200,7 @@ class AsyncDatabaseManager:
         #
         # POISON-GUARD: a connection must NEVER be handed out while it is still
         # inside a transaction. If a prior holder's teardown was interrupted (a
-        # cancelled task can skip its ROLLBACK, and asyncpg's reset-on-release
+        # canceled task can skip its ROLLBACK, and asyncpg's reset-on-release
         # can itself be skipped under cancellation), the connection comes back
         # "poisoned" — its server-side transaction still open/aborted. The next
         # consumer's very FIRST statement then fails with
@@ -1326,7 +1326,7 @@ class AsyncDatabaseManager:
         still cancels at its ceiling, and a value above it is logged once per
         call site (``matrx_orm.core.statement_ceiling``).
         """
-        # Layer 1 of the pooler-role defence: SQL that would leave a borrowed role
+        # Layer 1 of the pooler-role defense: SQL that would leave a borrowed role
         # on a shared server connection never reaches Postgres. See
         # matrx_orm/core/pooler_role.py for what that contamination does to reads.
         assert_no_session_role_change(query)

{matrx_orm-3.1.236 → matrx_orm-3.1.238}/matrx_orm/core/base.py

@@ -201,7 +201,7 @@ class ModelMeta(type):
         # `_abstract = True` — otherwise a future `if model._abstract: skip` silently
         # drops every entity. Stamp the real answer on the class.
         attrs["_abstract"] = is_abstract
-        # Also honour abstract declared on a parent's Meta
+        # Also honor abstract declared on a parent's Meta
         for base in bases:
             base_meta = getattr(base, "_meta", None)
             if base_meta is None:

{matrx_orm-3.1.236 → matrx_orm-3.1.238}/matrx_orm/core/config.py

@@ -670,7 +670,7 @@ def get_code_config(
     # Schema-aware Python output paths.
     #
     # ``public`` keeps the canonical single-schema paths so the generated
-    # artifacts stay byte-identical to the historical behaviour. Any non-public
+    # artifacts stay byte-identical to the historical behavior. Any non-public
     # schema (e.g. ``rag``) is written to namespaced files / subpackages so
     # multiple schemas of the SAME database can be generated without clobbering
     # each other's ``db/models.py`` and ``db/managers/`` output:

{matrx_orm-3.1.236 → matrx_orm-3.1.238}/matrx_orm/core/diagnostics.py

@@ -246,7 +246,7 @@ def describe_transactions(rows: list[dict[str, Any]]) -> str:
 # HERE — one fixed, parametrized statement in the ORM — rather than as a SQL
 # literal in the aidream service that consumes it. aidream keeps ZERO raw SQL
 # outside db/migrations; a missing capability is a todo for the ORM, never a
-# licence to write SQL in application code.
+# license to write SQL in application code.
 #
 # clock_timestamp(), not now(): `now()` is frozen at transaction start, so a
 # backend whose `state_change` lands after our snapshot reports a NEGATIVE age.

{matrx_orm-3.1.236 → matrx_orm-3.1.238}/matrx_orm/core/expressions.py

@@ -1395,7 +1395,7 @@ class Case:
     expression composition.
 
     ``default=None`` omits the ``ELSE`` clause entirely (Postgres already
-    evaluates an unmatched CASE to NULL, so this is behaviourally identical
+    evaluates an unmatched CASE to NULL, so this is behaviorally identical
     to an explicit ``ELSE NULL`` — no ambiguity with "no default").
 
     Usage::

{matrx_orm-3.1.236 → matrx_orm-3.1.238}/matrx_orm/core/extended.py

@@ -36,6 +36,9 @@ class BaseManager(Generic[ModelT]):
     # for that manager.  Has no effect when Pydantic is not installed.
     validate_input: bool = True
 
+    # Knob: hard ceiling for fetch-on-init (rows). Reaching it raises; never truncates.
+    fetch_on_init_max_rows: int = 50_000
+
     def __init__(
         self,
         model: type[ModelT],
@@ -1744,6 +1747,43 @@ class BaseManager(Generic[ModelT]):
 
         run_sync(self._auto_fetch_on_init_async())
 
+    async def _fetch_whole_table(self) -> list[ModelT]:
+        """Return EVERY row of the table, never a truncated prefix.
+
+        ``fetch_on_init_limit`` is the PAGE SIZE (a knob), not a cap: a
+        fetch-on-init cache that claims to hold the table must hold all of it
+        (2026-10 defect: a 300 cap silently dropped 84 of 384 ai.model_definition
+        rows). Single-PK tables page by keyset (``pk > last``); composite-PK
+        tables page by offset over a full-PK order. Past
+        ``fetch_on_init_max_rows`` the fetch RAISES (loud at boot) instead of
+        continuing with partial data — switch such a manager to load-on-miss.
+        """
+        page = int(self.fetch_on_init_limit)
+        pks = list(self.model._meta.primary_keys or ["id"])
+        ceiling = int(self.fetch_on_init_max_rows)
+        rows: list[ModelT] = []
+        last: Any = None
+        while True:
+            qb = self.model.filter()
+            if len(pks) == 1:
+                if last is not None:
+                    qb = qb.filter(**{f"{pks[0]}__gt": last})
+                qb = qb.order_by(pks[0]).limit(page)
+            else:
+                qb = qb.order_by(*pks).limit(page).offset(len(rows))
+            batch = await qb.all()
+            rows.extend(batch)
+            if len(rows) > ceiling:
+                raise RuntimeError(
+                    f"[{self.model.__name__}] fetch-on-init exceeded fetch_on_init_max_rows="
+                    f"{ceiling}; this table is too large to cache whole — make the manager "
+                    "load-on-miss (fetch_on_init_limit=0) or raise the knob deliberately."
+                )
+            if len(batch) < page:
+                return rows
+            if len(pks) == 1:
+                last = getattr(batch[-1], pks[0])
+
     async def _auto_fetch_on_init_async(self) -> None:
         """Fetch items on initialization (async version with full DTO support)."""
         if int(self.fetch_on_init_limit) <= 0:
@@ -1751,7 +1791,7 @@ class BaseManager(Generic[ModelT]):
 
         start_time = time.perf_counter()
 
-        items = await self.model.filter().limit(self.fetch_on_init_limit).all()
+        items = await self._fetch_whole_table()
         initialized_items: list[ModelT] = []
         for item in items:
             result = await self._initialize_item_runtime(item)
@@ -1797,9 +1837,6 @@ class BaseManager(Generic[ModelT]):
                         color="red",
                     )
 
-        if count >= (self.fetch_on_init_limit - 5):
-            self._trigger_limit_reached_warning(count, initialized_items)
-
         if not warnings_suppressed and count > warning_limit_threshold:
             self._trigger_fetch_warnings(count, initialized_items, warning_limit_threshold)
 

{matrx_orm-3.1.236 → matrx_orm-3.1.238}/matrx_orm/core/fields.py

@@ -1016,7 +1016,7 @@ class JSONBField(Field, Generic[_JT]):
     automatically deserialized to that model on load and serialized back to a
     dict on write.  Pydantic validates structure and types at both boundaries.
 
-    Without ``schema``, behaviour is identical to the original implementation —
+    Without ``schema``, behavior is identical to the original implementation —
     Pydantic is not required and this field remains a zero-dependency passthrough.
 
     Example::
@@ -1294,7 +1294,7 @@ class JSONBField(Field, Generic[_JT]):
         if isinstance(value, str):
             if not value.strip():
                 return None
-            # If the string is already valid JSON, round-trip it to normalise
+            # If the string is already valid JSON, round-trip it to normalize
             # formatting.  If it is not (e.g. a bare string value stored in a
             # JSONB column), encode it as a JSON string so Postgres accepts it.
             try:

{matrx_orm-3.1.236 → matrx_orm-3.1.238}/matrx_orm/core/foreign_session_state.py

@@ -15,7 +15,7 @@ Measured 2026-10-05 05:49-09:04 UTC: ~50 platform errors (SEO runs list, mandate
 resolution, membership checks, file downloads), each pinned to a few poisoned
 backends that kept failing for minutes.
 
-THE DEFENCE (two halves, both here so they cannot drift apart):
+THE DEFENSE (two halves, both here so they cannot drift apart):
 
 1. Every ORM transaction clears the setting transaction-locally at BEGIN
    (:data:`CLEARED_GUCS`, merged into ``transaction._opening_statement_gucs``).

{matrx_orm-3.1.236 → matrx_orm-3.1.238}/matrx_orm/core/model_view.py

@@ -130,7 +130,7 @@ class ModelView(Generic[ModelT], metaclass=ModelViewMeta):
           2. Run all computed-field coroutines concurrently.
           3. Apply inline_fk substitutions.
           4. Register exclude / inline_fk metadata on the model so to_dict()
-             can honour them without re-reading the view class.
+             can honor them without re-reading the view class.
 
         Returns the same model instance for convenience (chainable).
         """

{matrx_orm-3.1.236 → matrx_orm-3.1.238}/matrx_orm/core/pooler_role.py

@@ -21,7 +21,7 @@ reconciler, digest and monitor in the platform: a broken read reports a quiet we
 forever and every scheduled run stays green. ``db/pooler_session.py`` already says
 it for the migration tools — **a privilege error must never be recorded as
 absence** — and this module extends that to every ORM read, because a per-caller
-defence does not scale.
+defense does not scale.
 
 TWO INDEPENDENT LAYERS, each sufficient alone, each screaming when it fires:
 

{matrx_orm-3.1.236 → matrx_orm-3.1.238}/matrx_orm/core/resilience.py

@@ -8,7 +8,7 @@ read-mostly transaction, a batch flush) and have it survive a transient DB
 hiccup — a command-timeout under event-loop/pool starvation, a pool-acquire
 timeout under saturation — instead of crashing a 500-item job on the first blip.
 
-This is CALLER-OPT-IN by design. It does NOT change the behaviour of any query.
+This is CALLER-OPT-IN by design. It does NOT change the behavior of any query.
 The caller asserts, by wrapping, that re-running the factory is safe:
 
     from matrx_orm import retry_on_transient, transaction

{matrx_orm-3.1.236 → matrx_orm-3.1.238}/matrx_orm/core/session_context.py

@@ -146,7 +146,7 @@ ACTOR_SYSTEM_GUC = "app.actor_system"
 # through ``platform.declared_actor_agent()`` and names the ``agent`` rung when
 # it resolves ``records.confirmation.agent_write_born_confirmed`` -- which is
 # what makes a per-agent born-confirmed exception a real setting instead of a
-# control that saves a value nothing honours.
+# control that saves a value nothing honors.
 ACTOR_AGENT_GUC = "app.actor_agent"
 
 VALID_TIERS: frozenset[str] = frozenset({"system", "agent", "user"})

{matrx_orm-3.1.236 → matrx_orm-3.1.238}/matrx_orm/core/transaction.py

@@ -30,7 +30,7 @@ supports ``.execute(sql)`` and ``.fetch(sql, *args)``.
 The ``_active_connection`` ContextVar is typed as ``Any`` so the rest of the
 ORM can hold a reference to the active connection without depending on asyncpg.
 ``AsyncDatabaseManager.execute_query`` reads ``get_active_connection()`` and
-reuses the connection when present — this behaviour is unchanged.
+reuses the connection when present — this behavior is unchanged.
 """
 
 from __future__ import annotations
@@ -408,7 +408,7 @@ class TransactionContext:
             # SHIELD the teardown so an in-flight cancellation (hard-deadline,
             # client disconnect, shutdown) can never SKIP the ROLLBACK and leak a
             # poisoned (in-transaction) connection back to the pool. The shielded
-            # teardown runs to completion even when the outer await is cancelled.
+            # teardown runs to completion even when the outer await is canceled.
             try:
                 await asyncio.shield(_teardown())
             except Exception:

{matrx_orm-3.1.236 → matrx_orm-3.1.238}/matrx_orm/core/write_retry.py

@@ -1,4 +1,4 @@
-"""The retry policy for a statement Postgres cancelled to break a lock collision.
+"""The retry policy for a statement Postgres canceled to break a lock collision.
 
 ONE place owns "how hard do we re-issue a statement Postgres rolled back for
 contention": the knob read here plus the ONE loop (``run_with_lock_retry``) that
@@ -229,7 +229,7 @@ async def run_with_lock_retry[T](
     query: str,
     args: Any = None,
 ) -> T:
-    """Re-issue ``attempt`` when Postgres cancelled it to break a lock collision.
+    """Re-issue ``attempt`` when Postgres canceled it to break a lock collision.
 
     THE one lock-retry loop. Both doors into the database use it —
     ``AsyncDatabaseManager.execute_query`` (every statement, read or write) and
@@ -274,7 +274,7 @@ async def run_with_lock_retry[T](
                 ) from None
             backoff = policy.backoff_seconds(attempts)
             logger.warning(
-                "[lock-retry] attempt %d/%d cancelled by a lock collision "
+                "[lock-retry] attempt %d/%d canceled by a lock collision "
                 "(SQLSTATE %s) on '%s' — rolled back in full, re-issuing in "
                 "%.3fs: %s",
                 attempts + 1,
@@ -289,7 +289,7 @@ async def run_with_lock_retry[T](
         else:
             if attempts:
                 logger.warning(
-                    "[lock-retry] HEALED on attempt %d after Postgres cancelled the "
+                    "[lock-retry] HEALED on attempt %d after Postgres canceled the "
                     "statement to break a lock collision: %s",
                     attempts + 1,
                     query[:120],

{matrx_orm-3.1.236 → matrx_orm-3.1.238}/matrx_orm/exceptions.py

@@ -1123,7 +1123,7 @@ class PoolAcquireTimeoutError(DatabaseError):
     One of exactly TWO transient database errors that are provably safe to
     retry for write operations: by definition no connection was acquired and
     no SQL was sent to the server. (The other is a lock collision Postgres
-    cancelled — SQLSTATE 40P01/40001/55P03 — where the server itself rolled
+    canceled — SQLSTATE 40P01/40001/55P03 — where the server itself rolled
     the statement back in full; that one is retried a layer lower, inside
     ``execute_query``, and surfaces as :class:`LockContentionError` only once
     its budget is spent.) Any other "transient-looking" error
@@ -1189,11 +1189,11 @@ class PoolAcquireTimeoutError(DatabaseError):
 
 
 class LockContentionError(DatabaseError):
-    """Raised when Postgres cancelled a statement to break a lock collision.
+    """Raised when Postgres canceled 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
+    canceled statement survives — so a single statement outside a
     caller-managed transaction is provably safe to re-issue, reads AND writes,
     and THE ONE retry loop (``matrx_orm.core.write_retry.run_with_lock_retry``,
     used by ``AsyncDatabaseManager.execute_query`` and by ``call_function``)
@@ -1243,7 +1243,7 @@ class LockContentionError(DatabaseError):
         )
         super().__init__(
             message=(
-                f"Postgres cancelled this statement to break a lock collision "
+                f"Postgres canceled this statement to break a lock collision "
                 f"({sqlstate or 'lock contention'}) {where}: {original_error}"
             ),
             model=None,
@@ -1258,7 +1258,7 @@ class LockContentionError(DatabaseError):
         lines.append(self.message)
         lines.append("")
         lines.append("Hint:")
-        lines.append("  - NOTHING of the cancelled statement committed; re-running is safe.")
+        lines.append("  - NOTHING of the canceled 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")

{matrx_orm-3.1.236 → matrx_orm-3.1.238}/matrx_orm/operations/conflict.py

@@ -52,7 +52,7 @@ class ConflictTarget:
     _typed_token: object | None = field(default=None, repr=False, compare=False)
 
     def __post_init__(self) -> None:
-        # Normalise to a tuple so the dataclass stays hashable + immutable.
+        # Normalize to a tuple so the dataclass stays hashable + immutable.
         if not isinstance(self.expressions, tuple):
             object.__setattr__(self, "expressions", tuple(self.expressions))
         if not self.expressions:

{matrx_orm-3.1.236 → matrx_orm-3.1.238}/matrx_orm/operations/conflict_writes.py

@@ -445,7 +445,7 @@ async def upsert_with_conflict(
             value is dropped from the INSERT column list (falls back to the
             column's default) — Postgres still resolves ``EXCLUDED.<col>``
             for an omitted column to that same default/NULL, so omitting a
-            ``None`` field here is behaviourally identical to inserting it
+            ``None`` field here is behaviorally identical to inserting it
             explicitly.
         on_conflict: plain column list OR a :class:`ConflictTarget`
             (required for an expression/partial-index target).

{matrx_orm-3.1.236 → matrx_orm-3.1.238}/matrx_orm/operations/create.py

@@ -16,7 +16,7 @@ if TYPE_CHECKING:
 
 
 # The ``on_conflict`` parameter accepts either form:
-#   * ``list[str]`` of plain column names (the original, unchanged behaviour)
+#   * ``list[str]`` of plain column names (the original, unchanged behavior)
 #   * ``ConflictTarget`` with ``expressions`` (+ optional ``where``) for
 #     expression / partial unique indexes
 OnConflictArg = Union[list[str], "ConflictTarget"]
@@ -255,7 +255,7 @@ async def upsert(
     """INSERT ... ON CONFLICT (...) DO UPDATE SET ... RETURNING *
 
     ``on_conflict`` accepts either a ``list[str]`` of column names (the
-    original behaviour) OR a :class:`ConflictTarget` describing an
+    original behavior) OR a :class:`ConflictTarget` describing an
     expression / partial unique index.
 
     ``returning`` names the only columns read back: the instance then carries
@@ -316,7 +316,7 @@ async def bulk_upsert(
     """Bulk INSERT ... ON CONFLICT DO UPDATE for multiple rows.
 
     ``on_conflict`` accepts either a ``list[str]`` of column names (the
-    original behaviour) OR a :class:`ConflictTarget` describing an
+    original behavior) OR a :class:`ConflictTarget` describing an
     expression / partial unique index.
     """
     if not objects_data:

{matrx_orm-3.1.236 → matrx_orm-3.1.238}/matrx_orm/platform_access.py

@@ -55,7 +55,7 @@ from typing import Literal
 #
 # ``PERMISSION_LEVELS`` (the CODE ladder) deliberately runs WIDER than
 # ``DB_PERMISSION_LEVELS`` (what ``public.permission_level`` holds today):
-# ``commenter`` is not in the database enum yet. Reading, ranking and labelling
+# ``commenter`` is not in the database enum yet. Reading, ranking and labeling
 # always use the code ladder, so nothing needs an edit the day the enum gains
 # it; nothing breaks meanwhile, because the value simply never arrives. WRITING
 # a level to the database narrows through ``to_db_permission_level`` first.
@@ -310,7 +310,7 @@ async def verify_platform_access_wiring(*, probe_user_id: str | None = None) ->
 # 🚨 Creating an edge is not always a read. Some edges CONVEY access: the
 # ``trg_associations_reachability`` trigger on ``platform.associations`` writes
 # ``platform.reachability`` rows for them, and ``iam.has_access_for_base``
-# honours those rows. Writing such an edge therefore GRANTS other people read
+# honors those rows. Writing such an edge therefore GRANTS other people read
 # access to the attached row — a permission-granting act performed by whoever
 # wrote the edge.
 #
@@ -354,7 +354,7 @@ CONVEYING_EDGE = EdgeAccessRequirement((("editor", "editor"),))
 NON_CONVEYING_EDGE = EdgeAccessRequirement((("editor", "viewer"), ("viewer", "editor")))
 
 #: Fail-safe for an unregistered pair: assume it conveys. An edge type nobody
-#: declared is not a licence to be lenient.
+#: declared is not a license to be lenient.
 UNKNOWN_EDGE = CONVEYING_EDGE
 
 _container_side_cache: dict[tuple[str, str], str | None] = {}

{matrx_orm-3.1.236 → matrx_orm-3.1.238}/matrx_orm/pytest_lock_guard.py

@@ -4,7 +4,7 @@ Registered as a ``pytest11`` entry point so pytest auto-loads it in every suite
 **regardless of rootdir** — same mechanism, same reason, as
 ``matrx_orm.pytest_plugin`` (the spill guard), ``matrx_connect.pytest_plugin``
 and ``matrx_utils.pytest_plugin``. This is the SIXTH cross-suite hazard; the
-other five are catalogued in the repo-root ``conftest.py``.
+other five are cataloged in the repo-root ``conftest.py``.
 
 WHY IT EXISTS — production chat outage, 2026-09-15 23:45–23:52 UTC.
 ------------------------------------------------------------------
@@ -137,7 +137,7 @@ def mask_dsn_password(text: str) -> str:
 
     Used both to build ``RedactedDSN.__repr__`` and, in the pytest hooks below, as
     a blanket backstop over captured tracebacks and stdout — belt AND suspenders,
-    because a backstop that only fires on a type it recognises is not a backstop.
+    because a backstop that only fires on a type it recognizes is not a backstop.
     """
     return _DSN_PASSWORD_RE.sub(r"\1***\3", text)
 
@@ -162,7 +162,7 @@ class RedactedDSN(str):
 # this repo bans).
 
 #: How long a reader-blocking lock on a pre-existing relation may be held before
-#: the holder is cancelled and the test is failed. 2s is far longer than any
+#: the holder is canceled and the test is failed. 2s is far longer than any
 #: legitimate test DDL on a shared object, and far shorter than a user notices.
 HOLD_CEILING_SECONDS = 2.0
 
@@ -170,7 +170,7 @@ HOLD_CEILING_SECONDS = 2.0
 #: to ``pg_terminate_backend`` at this age.
 TERMINATE_AFTER_SECONDS = 10.0
 
-#: Sampling interval. One tiny catalogue query per tick, on one connection.
+#: Sampling interval. One tiny catalog query per tick, on one connection.
 SAMPLE_INTERVAL_SECONDS = 1.0
 
 #: Ceilings emitted as ``SET LOCAL`` on every transaction this pytest process
@@ -454,7 +454,7 @@ def pytest_addoption(parser: pytest.Parser) -> None:
         metavar="SECONDS",
         help=(
             "Seconds a test may hold a reader-blocking lock on a pre-existing "
-            f"relation before it is cancelled and failed (default {HOLD_CEILING_SECONDS})."
+            f"relation before it is canceled and failed (default {HOLD_CEILING_SECONDS})."
         ),
     )
     group.addoption(
@@ -532,7 +532,7 @@ def pytest_runtest_call(item: pytest.Item):
     new = offenses()[before:]
     if not new:
         return
-    # Do not mask a real failure the cancelled statement already produced — but a
+    # Do not mask a real failure the canceled statement already produced — but a
     # test that swallowed the cancellation and passed must still go red.
     if outcome.excinfo is None:
         pytest.fail(

{matrx_orm-3.1.236 → matrx_orm-3.1.238}/matrx_orm/query/executor.py

@@ -1182,7 +1182,7 @@ class QueryExecutor:
         """Call execute_write_dict on the adapter.
 
         Returns ``NotImplemented`` if the adapter does not override the hook
-        (default ``BaseAdapter`` behaviour) so callers can fall through to the
+        (default ``BaseAdapter`` behavior) so callers can fall through to the
         SQL path.
         """
         from matrx_orm.session.managed import assert_model_write_allowed

{matrx_orm-3.1.236 → matrx_orm-3.1.238}/matrx_orm/schema_builder/columns.py

@@ -1174,7 +1174,7 @@ class Column:
             # Both are the same question — "what list does this default mean?" —
             # so both go through one parser that answers it. Anything it cannot
             # confidently parse returns an EMPTY list rather than a guess, which
-            # is the pre-existing (conservative) behaviour, never a syntax error.
+            # is the pre-existing (conservative) behavior, never a syntax error.
             elif value.startswith("ARRAY[") or (
                 value.startswith("'{") and "}'::" in value and value.endswith("[]")
             ):

{matrx_orm-3.1.236 → matrx_orm-3.1.238}/matrx_orm/schema_builder/runner.py

@@ -361,7 +361,7 @@ def run_schema_generation(
 
         # skip_unchanged_managers: when True, manager files for tables whose
         # model definition has not changed are not rewritten. Default False
-        # preserves the existing behaviour of regenerating everything.
+        # preserves the existing behavior of regenerating everything.
         skip_unchanged_managers = bool(entry.get("skip_unchanged_managers", False))
 
         # output: per-entry overrides so generation can target a package tree

{matrx_orm-3.1.236 → matrx_orm-3.1.238}/matrx_orm/schema_builder/schema.py

@@ -978,7 +978,7 @@ class Schema:
         # Apply table filter at the last possible moment — all dependency resolution
         # and topological sorting above ran on the full table set so relationships are
         # always correct.  When no filter is configured this block is a no-op and the
-        # behaviour is 100% identical to an unfiltered run.
+        # behavior is 100% identical to an unfiltered run.
         if self._include_tables is not None:
             sorted_tables = [t for t in sorted_tables if t in self._include_tables]
         elif self._exclude_tables is not None: