matrx-orm 3.1.74__tar.gz → 3.1.75__tar.gz

{matrx_orm-3.1.74 → matrx_orm-3.1.75}/CLAUDE.md

@@ -23,7 +23,7 @@ Every table that becomes a Model needs row identity: a single-column primary key
 - 🚨 **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`).
-- **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` with `current_version` + `current_row` if changed); `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/optimistic-concurrency/FEATURE.md`.
+- **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/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`.
 - **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).
@@ -98,7 +98,7 @@ If the admin router ever needs auth beyond token-based, inject a `resolve_user`
 
 - Full type hints — the ORM's contract with callers is very type-heavy and IDE discoverability matters.
 - No docstrings except on public API (Model, QueryBuilder, field classes, migration entry points). One line.
-- Hot paths (`QueryBuilder.execute`, adapter fetches, dict→dataclass transforms) must stay allocation-light. Favor slotted dataclasses / `__slots__`.
+- Hot paths (`QueryBuilder.execute`, adapter fetches, dict→dataclass transforms) must stay allocation-light. Favor mandated dataclasses / `__slots__`.
 - Explicit exception handling — never swallow `asyncpg` errors.
 
 ---

{matrx_orm-3.1.74 → matrx_orm-3.1.75}/PKG-INFO

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

{matrx_orm-3.1.74 → matrx_orm-3.1.75}/matrx_orm/exceptions.py

@@ -5,7 +5,10 @@ import ssl
 import traceback as _tb
 from collections.abc import Mapping
 from dataclasses import dataclass
+from datetime import date, datetime, time
+from decimal import Decimal
 from typing import Any
+from uuid import UUID
 
 from matrx_utils import vcprint
 
@@ -1899,11 +1902,49 @@ class UnknownDatabaseError(ORMException):
         return f"{_RED}{body}{_RESET}"
 
 
+def jsonable(value: object) -> object:
+    """Coerce a DB value into something JSON-serializable, losslessly where we can.
+
+    Error payloads cross the wire (the platform 409 `version_conflict` body is
+    typed `JsonValue`), so a datetime / UUID / Decimal in a conflict's contested
+    fields must not be what turns a conflict into a 500. Unknown types degrade
+    to `str()` — a display value is always better than a crash inside an error
+    handler.
+    """
+    if value is None or isinstance(value, bool | int | float | str):
+        return value
+    if isinstance(value, datetime | date | time):
+        return value.isoformat()
+    if isinstance(value, Decimal):
+        return float(value)
+    if isinstance(value, UUID):
+        return str(value)
+    if isinstance(value, Mapping):
+        return {str(k): jsonable(v) for k, v in value.items()}
+    if isinstance(value, list | tuple | set | frozenset):
+        return [jsonable(v) for v in value]
+    return str(value)
+
+
 class OptimisticLockError(ORMException):
     """Raised when an optimistic-lock version conflict is detected.
 
-    This means another process has updated the row since it was last fetched.
-    Re-fetch the record and retry the operation.
+    THE LOSER GETS A DECISION, NOT AN ERROR (platform ruling 2026-08-10, item 3).
+    A caller that lost a compare-and-swap already holds "proposed" (its own
+    payload); this exception carries everything else it needs to RESOLVE rather
+    than blindly retry:
+
+      ``expected_version``  — the revision the caller wrote against
+      ``current_version``   — the revision that actually won
+      ``contested_fields``  — {field: current value} for ONLY the fields this
+                              write attempted (never the whole row)
+      ``changed_by`` / ``changed_at`` — who moved the row and when, from
+                              ``history.row_versions``; None on an unversioned
+                              entity or when the lookup found nothing
+      ``current_row``       — the live instance, for a merge UI without a re-read
+
+    Resolution is just another write: keep-mine / keep-theirs / merged, resubmitted
+    against ``current_version``. No queue, no resolution endpoint.
     """
 
     def __init__(
@@ -1914,13 +1955,29 @@ class OptimisticLockError(ORMException):
         message: str | None = None,
         current_version: int | None = None,
         current_row=None,
+        contested_fields: Mapping[str, object] | None = None,
+        changed_by: object = None,
+        changed_at: object = None,
     ) -> None:
         msg = message or (
             f"Optimistic lock conflict on {getattr(model, '__name__', model)} "
             f"(pk={pk}, expected version={expected_version}"
             + (f", current version={current_version}" if current_version is not None else "")
+            + (f", contested fields={sorted(contested_fields)}" if contested_fields else "")
+            + (f", changed by {changed_by}" if changed_by else "")
             + "). The record was modified by another process — re-fetch and retry."
         )
+        # Stored already-jsonable: this is a decision package for a human or a
+        # wire payload, not a data-access path (that is `current_row`).
+        self.contested_fields: dict[str, object] | None = (
+            {str(k): jsonable(v) for k, v in contested_fields.items()}
+            if contested_fields is not None
+            else None
+        )
+        self.changed_by: str | None = str(changed_by) if changed_by is not None else None
+        self.changed_at: str | None = (
+            jsonable(changed_at) if changed_at is not None else None  # type: ignore[assignment]
+        )
         super().__init__(
             message=msg,
             model=model,
@@ -1928,6 +1985,9 @@ class OptimisticLockError(ORMException):
                 "pk": pk,
                 "expected_version": expected_version,
                 "current_version": current_version,
+                "contested_fields": self.contested_fields,
+                "changed_by": self.changed_by,
+                "changed_at": self.changed_at,
             },
         )
         self.expected_version = expected_version

{matrx_orm-3.1.74 → matrx_orm-3.1.75}/matrx_orm/operations/update.py

@@ -37,36 +37,129 @@ def _require_version_column(model_cls: type[Model], version_column: str) -> None
         )
 
 
+def _contested_values(
+    model_cls: type[Model],
+    current: Model,
+    attempted_fields: Iterable[str] | None,
+    version_column: str,
+) -> dict[str, Any] | None:
+    """The CURRENT values of just the fields the losing write attempted.
+
+    Only the contested fields — never a dump of the whole row (a conflict body
+    is not a read endpoint, and the row may carry columns the caller is not
+    entitled to see). The version column and any primary key are excluded: the
+    revisions travel as their own fields and the pk was never in contest.
+    """
+    if not attempted_fields:
+        return None
+    pks = set(model_cls._meta.primary_keys or [])
+    return {
+        name: getattr(current, name, None)
+        for name in attempted_fields
+        if name != version_column and name not in pks and name in model_cls._fields
+    }
+
+
+async def _conflict_actor(
+    model_cls: type[Model],
+    pk_filter: dict[str, Any],
+    current_version: int | None,
+) -> tuple[Any, Any]:
+    """(changed_by, changed_at) for the winning revision, from history.row_versions.
+
+    Best-effort by construction: absent (None, None) on an unversioned entity, a
+    composite-PK table (the version log keys on a single ``row_id``), a missing
+    snapshot, or any failure reading the log. A conflict must NEVER be turned
+    into a different error because the courtesy lookup did not work out.
+    """
+    from matrx_orm.entity import MatrxEntity
+
+    if not isinstance(model_cls, type) or not issubclass(model_cls, MatrxEntity):
+        return (None, None)
+    if not (model_cls._is_versioned and model_cls._entity_token) or current_version is None:
+        return (None, None)
+    if len(pk_filter) != 1:
+        return (None, None)
+    row_id = next(iter(pk_filter.values()))
+    try:
+        log = model_cls._version_log()
+        snapshots = (
+            await log.filter(
+                entity_type=model_cls._entity_token,
+                row_id=str(row_id),
+                version=int(current_version),
+            )
+            .order_by("-id")
+            .limit(1)
+            .all()
+        )
+    except Exception as exc:
+        vcprint(
+            f"[matrx-orm] conflict actor lookup failed for {model_cls.__name__} "
+            f"{row_id} v{current_version} ({type(exc).__name__}: {exc}) — the "
+            f"conflict still carries its versions and contested fields.",
+            color="yellow",
+            log_level="WARNING",
+        )
+        return (None, None)
+    if not snapshots:
+        return (None, None)
+    snapshot = snapshots[0]
+    return (getattr(snapshot, "actor_id", None), getattr(snapshot, "occurred_at", None))
+
+
+async def _build_conflict(
+    model_cls: type[Model],
+    pk_filter: dict[str, Any],
+    version_column: str,
+    expected_version: int | None,
+    current: Model,
+    attempted_fields: Iterable[str] | None,
+) -> Any:
+    """Assemble the full decision package for a lost compare-and-swap."""
+    from matrx_orm.exceptions import OptimisticLockError
+
+    current_version = getattr(current, version_column, None)
+    changed_by, changed_at = await _conflict_actor(model_cls, pk_filter, current_version)
+    return OptimisticLockError(
+        model=model_cls,
+        pk=pk_filter if len(pk_filter) > 1 else next(iter(pk_filter.values())),
+        expected_version=expected_version,
+        current_version=current_version,
+        current_row=current,
+        contested_fields=_contested_values(model_cls, current, attempted_fields, version_column),
+        changed_by=changed_by,
+        changed_at=changed_at,
+    )
+
+
 async def _raise_stale_write(
     model_cls: type[Model],
     pk_filter: dict[str, Any],
     version_column: str,
     expected_version: int | None,
+    attempted_fields: Iterable[str] | None = None,
 ) -> None:
     """Classify a guarded UPDATE that hit 0 rows: gone vs. changed.
 
     Re-reads by primary key alone (no version filter, no cache). Row absent →
     DoesNotExist (deleted concurrently, or never existed). Row present → its
-    version no longer matches → OptimisticLockError carrying the live row.
+    version no longer matches → OptimisticLockError carrying the live row and
+    the decision package (contested field values + who changed it, when).
     """
-    from matrx_orm.exceptions import DoesNotExist, OptimisticLockError
+    from matrx_orm.exceptions import DoesNotExist
 
     # Note: inside an open Session the re-read merges PENDING (uncommitted)
     # writes for this row — a CAS should run on the direct write paths, not
     # Coordinator-adjacent code (see the contract's session-plane exclusion).
     current = await QueryBuilder(model_cls).filter(**pk_filter).get_or_none()
-    pk_value = pk_filter if len(pk_filter) > 1 else next(iter(pk_filter.values()))
     if current is None or getattr(current, "deleted_at", None) is not None:
         # Hard-gone or soft-deleted: for conflict classification a soft-deleted
         # row IS gone — reporting it as "changed by someone else, refresh and
         # re-apply" would send the user chasing a record that no longer exists.
         raise DoesNotExist(model=model_cls, filters=pk_filter)
-    raise OptimisticLockError(
-        model=model_cls,
-        pk=pk_value,
-        expected_version=expected_version,
-        current_version=getattr(current, version_column, None),
-        current_row=current,
+    raise await _build_conflict(
+        model_cls, pk_filter, version_column, expected_version, current, attempted_fields
     )
 
 
@@ -91,17 +184,21 @@ async def guarded_update(
     (e.g. `version=F("version") + 1`), as matrx-graph's DefinitionStore does.
 
     0 rows affected raises: DoesNotExist when the row is gone,
-    OptimisticLockError (with current_version + current_row) when it changed.
-    The gone-vs-changed re-read uses the PRIMARY-KEY columns only, so an extra
+    OptimisticLockError (with current_version, current_row, the contested
+    fields' current values and who changed them) when it changed. The
+    gone-vs-changed re-read uses the PRIMARY-KEY columns only, so an extra
     narrowing filter that stopped matching still classifies as a conflict.
     """
     _require_version_column(model_cls, version_column)
     data = dict(update_data)
+    attempted_fields = list(data)
     data.setdefault(version_column, expected_version + 1)
     result = await update(model_cls, {**filters, version_column: expected_version}, **data)
     if result.rows_affected == 0:
         pk_filter = {pk: filters[pk] for pk in model_cls._meta.primary_keys}
-        await _raise_stale_write(model_cls, pk_filter, version_column, expected_version)
+        await _raise_stale_write(
+            model_cls, pk_filter, version_column, expected_version, attempted_fields
+        )
     return result
 
 
@@ -183,7 +280,11 @@ async def bulk_update(
                 result = await QueryBuilder(model_cls).filter(**row_filter).update(**update_data)
                 if check_version and result.rows_affected == 0:
                     await _raise_stale_write(
-                        model_cls, pk_filter, VERSION_COLUMN, getattr(obj, VERSION_COLUMN, None)
+                        model_cls,
+                        pk_filter,
+                        VERSION_COLUMN,
+                        getattr(obj, VERSION_COLUMN, None),
+                        fields,
                     )
                 if result.rows_affected > 0:
                     rows_affected += 1
@@ -271,8 +372,6 @@ async def guarded_delete(
     version → OptimisticLockError (someone rewrote what the caller decided to
     delete; deleting it anyway would discard their work unseen).
     """
-    from matrx_orm.exceptions import OptimisticLockError
-
     _require_version_column(model_cls, version_column)
     deleted = (
         await QueryBuilder(model_cls)
@@ -284,12 +383,10 @@ async def guarded_delete(
         current = await QueryBuilder(model_cls).filter(**pk_filter).get_or_none()
         # Soft-deleted counts as already gone — idempotent 0, not a conflict.
         if current is not None and getattr(current, "deleted_at", None) is None:
-            raise OptimisticLockError(
-                model=model_cls,
-                pk=pk_filter if len(pk_filter) > 1 else next(iter(pk_filter.values())),
-                expected_version=expected_version,
-                current_version=getattr(current, version_column, None),
-                current_row=current,
+            # A delete contests no individual field (it contests the whole row),
+            # so contested_fields stays absent; the actor half still applies.
+            raise await _build_conflict(
+                model_cls, pk_filter, version_column, expected_version, current, None
             )
     return deleted
 
@@ -377,8 +474,16 @@ async def update_instance(
 
     if result.rows_affected == 0:
         if version_field_name is not None and current_version is not None:
-            # Guarded write: classify gone-vs-changed and raise accordingly.
-            await _raise_stale_write(model_cls, pk_filter, version_field_name, current_version)
+            # Guarded write: classify gone-vs-changed and raise accordingly. The
+            # contested fields are exactly what this write attempted, minus the
+            # version bump the guard itself added.
+            await _raise_stale_write(
+                model_cls,
+                pk_filter,
+                version_field_name,
+                current_version,
+                [f for f in update_data if f != version_field_name],
+            )
         raise ValueError(f"No rows were updated for {model_cls.__name__} with {pk_filter}")
 
     if result.updated_rows:

{matrx_orm-3.1.74 → matrx_orm-3.1.75}/matrx_orm/schema_builder/package_wiring.py

@@ -329,8 +329,7 @@ _HEADER = '''\
 # because it imports db.models.* / db.managers.* — forbidden inside packages/.
 """AUTO-GENERATED host->package DB wiring. Do not edit."""
 
-from __future__ import annotations
-'''
+from __future__ import annotations'''
 
 
 def _bucket_order(bucket: str) -> int:
@@ -360,6 +359,10 @@ def render_wiring_module(output_module: str, packages: list[ResolvedPackage]) ->
         for (module, symbol), local in sorted(local_for.items(), key=lambda kv: int(kv[1][2:])):
             lines.append(f"    from {module} import {symbol} as {local}")
         lines.append(f"    import {pkg.configure_import} as _target")
+        # Blank line after the import block: keeps the emitted file byte-identical
+        # to `ruff format` output, so the wiring drift gate and the formatter can
+        # never fight over this file.
+        lines.append("")
 
         # Build the kwargs.
         buckets: dict[str, list[Assignment]] = {}

{matrx_orm-3.1.74 → matrx_orm-3.1.75}/matrx_orm/session/README.md

@@ -110,7 +110,12 @@ and:
 2. Registers a `WatchedLifecycleConfig` with `WatchedLifecycleRegistry`.
 
 The sweeper (started by the host app at startup) iterates the registry
-on its periodic tick.
+on its periodic tick. A watchdog that automatically transitions rows reports
+every sweep in which it finds work. An alert-only watchdog reports immediately,
+again whenever its stuck-row count changes, after recovery if the condition
+returns, and once per hour while an unchanged condition persists. This keeps a
+durable operational problem visible without emitting the same ERROR every
+minute forever.
 
 ## Pending-aware reads
 

{matrx_orm-3.1.74 → matrx_orm-3.1.75}/matrx_orm/session/lifecycle.py

@@ -37,6 +37,7 @@ import asyncio
 import inspect
 import logging
 import re
+import time
 import traceback as _tb
 from collections.abc import Sequence
 from dataclasses import dataclass, replace
@@ -284,6 +285,13 @@ WatchedLifecycleRegistry = _Registry()
 
 SWEEP_INTERVAL_SECS_DEFAULT = 60.0
 SWEEP_LIMIT_DEFAULT = 100
+ALERT_ONLY_REMINDER_SECS = 3600.0
+
+# Alert-only watches intentionally leave rows untouched, so the same persistent
+# condition can remain visible for days. Remember the last emitted state in this
+# process: alert immediately, alert again when the count changes, and otherwise
+# emit one hourly reminder instead of one ERROR per sweep tick.
+_alert_only_emissions: dict[str, tuple[int, float]] = {}
 
 
 def _alert_color(channel: AlertChannel) -> str:
@@ -313,6 +321,35 @@ def _emit_stuck_rows_summary(summary: str, *, color: str) -> None:
     cool_print(text=f"\n{summary}", color=color)
 
 
+def _should_emit_stuck_rows_alert(
+    cfg: WatchedLifecycleConfig,
+    *,
+    stuck_count: int,
+    monotonic_now: float | None = None,
+) -> bool:
+    """Return whether this sweep should emit the human + structured alert."""
+    if cfg.transition_to_on_timeout is not None:
+        return True
+
+    key = f"{cfg.schema}.{cfg.table}"
+    if stuck_count == 0:
+        _alert_only_emissions.pop(key, None)
+        return False
+
+    now_value = time.monotonic() if monotonic_now is None else monotonic_now
+    previous = _alert_only_emissions.get(key)
+    if previous is not None:
+        previous_count, previous_emitted_at = previous
+        if (
+            previous_count == stuck_count
+            and now_value - previous_emitted_at < ALERT_ONLY_REMINDER_SECS
+        ):
+            return False
+
+    _alert_only_emissions[key] = (stuck_count, now_value)
+    return True
+
+
 def _build_select_query(cfg: WatchedLifecycleConfig, limit: int) -> tuple[str, list[Any]]:
     params: list[Any] = []
     predicate_sql = cfg.predicate.as_sql(params)
@@ -547,6 +584,7 @@ async def sweep_once(
         stuck_count = len(rows)
         out[f"{cfg.schema}.{cfg.table}"] = stuck_count
         if stuck_count == 0:
+            _should_emit_stuck_rows_alert(cfg, stuck_count=0)
             continue
 
         color = _alert_color(cfg.alert_channel)
@@ -561,29 +599,30 @@ async def sweep_once(
                 pass
         max_age_seen = max(ages_seconds) if ages_seconds else 0
 
-        _emit_stuck_rows_summary(
-            _format_stuck_rows_summary(
-                cfg,
-                stuck_count=stuck_count,
-                max_age_seen=max_age_seen,
-            ),
-            color=color,
-        )
-        logger.error(
-            "watchdog_stuck_rows",
-            extra={
-                "matrx_watchdog": {
-                    "table": cfg.table,
-                    "schema": cfg.schema,
-                    "stuck_count": stuck_count,
-                    "predicate": repr(cfg.predicate),
-                    "max_age_secs": cfg.max_age_secs,
-                    "alert_channel": cfg.alert_channel,
-                    "transition_to": cfg.transition_to_on_timeout,
-                    "extra_fields_on_timeout": dict(cfg.extra_fields_on_timeout),
+        if _should_emit_stuck_rows_alert(cfg, stuck_count=stuck_count):
+            _emit_stuck_rows_summary(
+                _format_stuck_rows_summary(
+                    cfg,
+                    stuck_count=stuck_count,
+                    max_age_seen=max_age_seen,
+                ),
+                color=color,
+            )
+            logger.error(
+                "watchdog_stuck_rows",
+                extra={
+                    "matrx_watchdog": {
+                        "table": cfg.table,
+                        "schema": cfg.schema,
+                        "stuck_count": stuck_count,
+                        "predicate": repr(cfg.predicate),
+                        "max_age_secs": cfg.max_age_secs,
+                        "alert_channel": cfg.alert_channel,
+                        "transition_to": cfg.transition_to_on_timeout,
+                        "extra_fields_on_timeout": dict(cfg.extra_fields_on_timeout),
+                    }
                 }
-            },
-        )
+            )
 
         for row in rows:
             try:

{matrx_orm-3.1.74 → matrx_orm-3.1.75}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.74"
+version = "3.1.75"
 description = "Async-first PostgreSQL ORM with bidirectional migrations, schema introspection, many-to-many relationships, and built-in state caching"
 readme = "README.md"
 license = { text = "MIT" }
@@ -41,7 +41,7 @@ dependencies = [
     "gitpython>=3.1.40",
     "psycopg[binary]>=3.2.5",
     "psycopg-pool>=3.2.5",
-    "matrx-utils>=2.0.15",
+    "matrx-utils>=2.0.16",
     "pyyaml>=6.0.3",
     "python-dotenv>=1.0",
     "cryptography>=43.0",