messagefoundry 0.1.0__py3-none-any.whl

messagefoundry/pipeline/retention.py

@@ -0,0 +1,289 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""Data-retention + store-maintenance worker (PHI.md §8, ASVS 14.2.x).
+
+Without enforcement, PHI accumulates in the message store indefinitely — including dead-lettered
+raw bodies. :class:`RetentionRunner` is the single background task that enforces the ``[retention]``
+service settings: past the configured windows it **nulls message/dead-letter bodies while keeping
+their metadata rows** (the Mirth Data-Pruner pattern — counts, disposition, and the audit trail stay
+intact; nothing is deleted), checkpoints the WAL, and ``VACUUM``s on a daily off-peak schedule. Each
+pass that does real work writes **one** ``audit_log`` entry recording the cutoffs + counts (never any
+message content). When the store outgrows ``max_db_mb`` it raises an advisory ``storage_threshold``
+alert.
+
+It is owned by the :class:`~messagefoundry.pipeline.engine.Engine` (started in ``start``, cancelled in
+``stop``) rather than the per-graph runner, so it is independent of config reloads and runs once per
+process. The clock is injected so the windows and the daily VACUUM time are deterministically testable
+(``run_once`` performs a full pass for a given ``now``); the loop only governs cadence.
+
+Engine-side and dependency-light (stdlib + the store/alert seams only), so it never pulls the API or
+console into the engine.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from messagefoundry.config.settings import RetentionSettings
+from messagefoundry.pipeline.alerts import AlertSink, LoggingAlertSink
+from messagefoundry.pipeline.cluster import ClusterCoordinator, NullCoordinator
+from messagefoundry.store import Store
+
+__all__ = ["RetentionRunner", "RetentionPass"]
+
+log = logging.getLogger(__name__)
+
+_SECONDS_PER_DAY = 86_400
+_BYTES_PER_MB = 1_000_000
+
+
+@dataclass(frozen=True)
+class RetentionPass:
+    """What one :meth:`RetentionRunner.run_once` pass did — returned for the audit entry + tests."""
+
+    messages_purged: int
+    dead_purged: int
+    state_purged: int
+    wal_checkpointed: bool
+    vacuumed: bool
+    size_bytes: int
+    over_limit: bool
+
+    @property
+    def did_work(self) -> bool:
+        """Whether the pass changed anything worth an audit row (a routine WAL checkpoint alone
+        isn't — it leaves no data trace and would otherwise spam the audit log every pass)."""
+        return (
+            self.messages_purged > 0
+            or self.dead_purged > 0
+            or self.state_purged > 0
+            or self.vacuumed
+            or self.over_limit
+        )
+
+
+class RetentionRunner:
+    """Enforces ``[retention]`` on the message store: body-purge + WAL checkpoint + VACUUM + a size
+    alert, audited per pass. Construct with the store + settings; call :meth:`start`/:meth:`stop` for
+    the supervised loop, or :meth:`run_once` to perform a single deterministic pass (tests)."""
+
+    def __init__(
+        self,
+        store: Store,
+        settings: RetentionSettings,
+        *,
+        alert_sink: AlertSink | None = None,
+        clock: Callable[[], float] = time.time,
+        coordinator: ClusterCoordinator | None = None,
+    ) -> None:
+        self._store = store
+        self._settings = settings
+        # Default to the logging sink so an over-limit store is at least visible without a notifier.
+        self._alert_sink: AlertSink = alert_sink or LoggingAlertSink()
+        self._clock = clock
+        # Retention is a leader-only WRITE singleton (it purges PHI bodies + writes audit rows), so in
+        # a cluster it must run on exactly one node. Default NullCoordinator → always leader → always
+        # runs, so an existing caller/test that passes no coordinator is byte-identical (Track B Step 4).
+        self._coordinator: ClusterCoordinator = coordinator or NullCoordinator()
+        self._stop = asyncio.Event()
+        self._task: asyncio.Task[None] | None = None
+        # Maintenance cadence state (loop-driven; only read/written on the single task).
+        self._last_wal = 0.0
+        self._last_vacuum_day: str | None = None
+
+    @property
+    def enabled(self) -> bool:
+        """True when any window/threshold/maintenance knob is configured. When False, :meth:`start`
+        spawns no task — retention is entirely off by default."""
+        s = self._settings
+        return bool(
+            s.messages_days
+            or s.dead_letter_days
+            or s.state_max_age_days
+            or s.max_db_mb
+            or s.wal_checkpoint_seconds
+            or s.vacuum_time() is not None
+        )
+
+    # --- lifecycle -----------------------------------------------------------
+
+    def start(self) -> None:
+        """Spawn the supervised purge/maintenance loop (no-op when nothing is configured)."""
+        if self._task is not None:
+            return
+        if not self.enabled:
+            log.debug("retention disabled (no [retention] windows configured); not starting")
+            return
+        self._stop.clear()
+        self._task = asyncio.create_task(self._run())
+        log.info(
+            "retention enabled: messages_days=%d dead_letter_days=%d max_db_mb=%d "
+            "wal_checkpoint_seconds=%g vacuum_at=%r (every %gs)",
+            self._settings.messages_days,
+            self._settings.dead_letter_days,
+            self._settings.max_db_mb,
+            self._settings.wal_checkpoint_seconds,
+            self._settings.vacuum_at,
+            self._settings.purge_interval_seconds,
+        )
+
+    async def stop(self) -> None:
+        """Signal the loop and await its exit (idempotent)."""
+        self._stop.set()
+        task = self._task
+        self._task = None
+        if task is not None:
+            task.cancel()
+            try:
+                await task
+            except asyncio.CancelledError:
+                pass
+
+    async def _run(self) -> None:
+        # One isolated pass per interval; an error in a pass is logged and the loop continues (a
+        # retention hiccup must never take the engine down). Cooperatively cancellable via _stop.
+        while not self._stop.is_set():
+            try:
+                await self.run_once()
+            except asyncio.CancelledError:
+                raise
+            except Exception:
+                log.exception("retention pass failed; will retry next interval")
+            await self._sleep(self._settings.purge_interval_seconds)
+
+    async def _sleep(self, delay: float) -> None:
+        """Sleep up to ``delay``, waking immediately on stop (so shutdown isn't held by the interval)."""
+        try:
+            await asyncio.wait_for(self._stop.wait(), delay)
+        except asyncio.TimeoutError:
+            pass
+
+    # --- one pass ------------------------------------------------------------
+
+    async def run_once(self, now: float | None = None) -> RetentionPass:
+        """Run a full retention pass for ``now`` (default: the injected clock): purge bodies past the
+        configured windows, checkpoint the WAL / VACUUM if due, check the size threshold, and write a
+        single ``audit_log`` entry when the pass did real work. Returns a :class:`RetentionPass`.
+
+        Leader-gated (Track B Step 4): a non-leader node returns a did-nothing pass without touching the
+        store, so in a cluster exactly one node purges. The loop keeps ticking on followers
+        (reactive-by-polling), so when a follower becomes leader the very next pass acts. A follower
+        never advances its WAL/VACUUM cadence state (the gate returns before those timers update), so a
+        newly-promoted leader runs any due WAL checkpoint / daily VACUUM on its first acting pass — which
+        is the correct behavior (the new leader picks up the maintenance the cluster owes). Single-node
+        (the NullCoordinator default) is always leader, so this is byte-identical there."""
+        if not self._coordinator.is_leader():
+            return RetentionPass(
+                messages_purged=0,
+                dead_purged=0,
+                state_purged=0,
+                wal_checkpointed=False,
+                vacuumed=False,
+                size_bytes=0,
+                over_limit=False,
+            )
+        now = self._clock() if now is None else now
+        s = self._settings
+
+        messages_purged = 0
+        if s.messages_days > 0:
+            messages_purged = await self._store.purge_message_bodies(
+                older_than=now - s.messages_days * _SECONDS_PER_DAY, now=now
+            )
+        dead_purged = 0
+        if s.dead_letter_days > 0:
+            dead_purged = await self._store.purge_dead_letters(
+                older_than=now - s.dead_letter_days * _SECONDS_PER_DAY, now=now
+            )
+        state_purged = 0
+        if s.state_max_age_days > 0:
+            state_purged = await self._store.purge_state(
+                older_than=now - s.state_max_age_days * _SECONDS_PER_DAY, now=now
+            )
+
+        wal_checkpointed = False
+        if s.wal_checkpoint_seconds > 0 and now - self._last_wal >= s.wal_checkpoint_seconds:
+            await self._store.wal_checkpoint()
+            self._last_wal = now
+            wal_checkpointed = True
+
+        vacuumed = False
+        if self._vacuum_due(now):
+            await self._store.vacuum()
+            self._last_vacuum_day = self._day_key(now)
+            vacuumed = True
+
+        size_bytes, over_limit = await self._check_size()
+
+        result = RetentionPass(
+            messages_purged=messages_purged,
+            dead_purged=dead_purged,
+            state_purged=state_purged,
+            wal_checkpointed=wal_checkpointed,
+            vacuumed=vacuumed,
+            size_bytes=size_bytes,
+            over_limit=over_limit,
+        )
+        if result.did_work:
+            await self._audit(result)
+        return result
+
+    async def _check_size(self) -> tuple[int, bool]:
+        """Return ``(db_size_bytes, over_limit)``, emitting the advisory alert when over. Skips the
+        size query entirely when ``max_db_mb`` is off."""
+        if self._settings.max_db_mb <= 0:
+            return 0, False
+        size_bytes = (await self._store.db_status()).size_bytes
+        limit_bytes = self._settings.max_db_mb * _BYTES_PER_MB
+        over = size_bytes > limit_bytes
+        if over:
+            # The sink never raises (contract), but be defensive — an alert failure must not abort
+            # the purge pass that produced it.
+            try:
+                self._alert_sink.storage_threshold(
+                    self._store.path, size_bytes=size_bytes, limit_bytes=limit_bytes
+                )
+            except Exception:
+                log.warning("storage_threshold alert sink failed", exc_info=True)
+        return size_bytes, over
+
+    async def _audit(self, result: RetentionPass) -> None:
+        """Append one audit row recording the cutoffs + counts (no message content — no PHI)."""
+        detail = json.dumps(
+            {
+                "messages_days": self._settings.messages_days,
+                "messages_purged": result.messages_purged,
+                "dead_letter_days": self._settings.dead_letter_days,
+                "dead_purged": result.dead_purged,
+                "state_max_age_days": self._settings.state_max_age_days,
+                "state_purged": result.state_purged,
+                "vacuumed": result.vacuumed,
+                "db_size_bytes": result.size_bytes,
+                "max_db_mb": self._settings.max_db_mb,
+                "over_limit": result.over_limit,
+            },
+            sort_keys=True,
+        )
+        await self._store.record_audit("retention_purge", actor="system", detail=detail)
+
+    # --- daily VACUUM schedule ----------------------------------------------
+
+    def _vacuum_due(self, now: float) -> bool:
+        """True when a daily VACUUM time is configured, the local clock has reached it, and we haven't
+        already vacuumed today. (At-most-once per local day; a late start that day still catches up.)"""
+        target = self._settings.vacuum_time()
+        if target is None:
+            return False
+        lt = time.localtime(now)
+        reached = (lt.tm_hour, lt.tm_min) >= target
+        return reached and self._last_vacuum_day != self._day_key(now)
+
+    @staticmethod
+    def _day_key(now: float) -> str:
+        lt = time.localtime(now)
+        return f"{lt.tm_year:04d}-{lt.tm_mon:02d}-{lt.tm_mday:02d}"

messagefoundry/pipeline/security_notify.py

@@ -0,0 +1,168 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""Per-user security-event email notifier (ASVS 6.3.5 / 6.3.7).
+
+The concrete :class:`~messagefoundry.auth.notifications.SecurityNotifier` the API lifespan injects into
+:class:`~messagefoundry.auth.service.AuthService`. It turns a
+:class:`~messagefoundry.auth.notifications.SecurityEvent` into a short plain-text email to the
+**affected user's own address** — distinct from the operator alert distribution list — over the
+``[alerts]`` SMTP transport. Dispatch runs on a bounded background queue so a notification never blocks
+the login / admin path, and every send is best-effort (a failure is logged, never raised).
+
+Lives in ``pipeline/`` (next to the operator alert plumbing it reuses) and imports the contract from
+``auth/`` — one-way ``pipeline → auth``, never the reverse (CLAUDE.md §4).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+
+from messagefoundry.auth.notifications import (
+    ACCOUNT_DISABLED,
+    ACCOUNT_LOCKED,
+    ADMIN_NEW_IP,
+    EMAIL_CHANGED,
+    LOGIN_AFTER_FAILURES,
+    MFA_DISABLED,
+    MFA_ENABLED,
+    PASSWORD_CHANGED,
+    PASSWORD_RESET,
+    ROLES_CHANGED,
+    SecurityEvent,
+)
+from messagefoundry.config.settings import AlertsSettings
+from messagefoundry.pipeline.alert_sinks import _BackgroundDispatcher, send_plain_email
+
+log = logging.getLogger(__name__)
+
+_SUBJECTS = {
+    ACCOUNT_LOCKED: "Your MessageFoundry account was locked",
+    LOGIN_AFTER_FAILURES: "New MessageFoundry sign-in after failed attempts",
+    PASSWORD_CHANGED: "Your MessageFoundry password was changed",
+    PASSWORD_RESET: "Your MessageFoundry password was reset",
+    EMAIL_CHANGED: "Your MessageFoundry account email was changed",
+    ROLES_CHANGED: "Your MessageFoundry account roles were changed",
+    ACCOUNT_DISABLED: "Your MessageFoundry account was disabled",
+    MFA_ENABLED: "Two-factor authentication was enabled on your MessageFoundry account",
+    MFA_DISABLED: "Two-factor authentication was disabled on your MessageFoundry account",
+    ADMIN_NEW_IP: "A sensitive action on your MessageFoundry account from a new location",
+}
+
+_DESCRIPTIONS = {
+    ACCOUNT_LOCKED: "Your account was locked after repeated failed sign-in attempts.",
+    LOGIN_AFTER_FAILURES: "A sign-in to your account succeeded after several failed attempts.",
+    PASSWORD_CHANGED: "Your account password was changed.",
+    PASSWORD_RESET: "Your account password was reset by an administrator.",
+    EMAIL_CHANGED: "Your account's email address was changed.",
+    ROLES_CHANGED: "Your account's roles were changed by an administrator.",
+    ACCOUNT_DISABLED: "Your account was disabled by an administrator.",
+    MFA_ENABLED: "A two-factor authenticator (TOTP) was enrolled on your account.",
+    MFA_DISABLED: "Two-factor authentication was removed from your account.",
+    ADMIN_NEW_IP: (
+        "A sensitive administrative action on your account was attempted from a client address that "
+        "differs from your session's last verified address. It was required to re-verify before "
+        "proceeding."
+    ),
+}
+
+
+def _build_body(event: SecurityEvent) -> str:
+    """A short, PHI-free notice. The recipient is the account owner, so naming their own account /
+    source IP / new email is appropriate; no message data or secrets ever appear here."""
+    lines = [
+        f"A security-relevant change occurred on your MessageFoundry account ({event.username}).",
+        "",
+        _DESCRIPTIONS.get(event.event_type, "A security event occurred on your account."),
+    ]
+    failed = event.detail.get("failed_attempts")
+    if event.event_type in (ACCOUNT_LOCKED, LOGIN_AFTER_FAILURES) and failed:
+        lines.append(f"Failed attempts: {failed}")
+    if event.event_type == EMAIL_CHANGED and event.detail.get("new_email"):
+        lines.append(f"New email on file: {event.detail['new_email']}")
+    if event.client_ip:
+        lines.append(f"Source IP: {event.client_ip}")
+    lines += [
+        "",
+        "If this was you, no action is needed. If not, contact your MessageFoundry administrator.",
+    ]
+    return "\n".join(lines)
+
+
+class SecurityEventNotifier(_BackgroundDispatcher[SecurityEvent]):
+    """Emails the affected user about a security event, on a bounded background queue."""
+
+    def __init__(
+        self,
+        *,
+        host: str,
+        port: int,
+        sender: str,
+        use_tls: bool = True,
+        username: str | None = None,
+        password: str | None = None,
+        timeout: float = 30.0,
+        allowed_hosts: tuple[str, ...] = (),
+    ) -> None:
+        super().__init__()
+        self._host = host
+        self._port = port
+        self._sender = sender
+        self._use_tls = use_tls
+        self._username = username
+        self._password = password
+        self._timeout = timeout
+        self._allowed_hosts = allowed_hosts
+
+    async def notify(self, event: SecurityEvent) -> None:
+        # No deliverable address (common for local accounts / unset email) → nothing to email; the
+        # audited /me/security-events feed still records it. Non-blocking enqueue.
+        if not event.email:
+            return
+        self._enqueue(event, dropped=f"{event.event_type} for {event.username}")
+
+    async def _handle(self, event: SecurityEvent) -> None:
+        try:
+            await asyncio.to_thread(self._send, event)
+        except Exception:
+            # Best-effort: a failed send must never propagate. The event is also in the audit log.
+            log.warning(
+                "security-event email failed for %s (%s)",
+                event.username,
+                event.event_type,
+                exc_info=True,
+            )
+
+    def _send(self, event: SecurityEvent) -> None:
+        if not event.email:  # narrowed for mypy; notify() already filtered these out
+            return
+        send_plain_email(
+            host=self._host,
+            port=self._port,
+            sender=self._sender,
+            recipients=[event.email],
+            subject=_SUBJECTS.get(event.event_type, "MessageFoundry security alert"),
+            body=_build_body(event),
+            use_tls=self._use_tls,
+            username=self._username,
+            password=self._password,
+            timeout=self._timeout,
+            allowed_hosts=self._allowed_hosts,
+        )
+
+
+def security_notifier_from_settings(alerts: AlertsSettings) -> SecurityEventNotifier | None:
+    """Build the per-user security notifier from ``[alerts]`` SMTP settings, or ``None`` when no SMTP
+    server/sender is configured (then only the ``/me/security-events`` feed records events)."""
+    if not (alerts.email_smtp_host and alerts.email_from):
+        return None
+    return SecurityEventNotifier(
+        host=alerts.email_smtp_host,
+        port=alerts.email_smtp_port,
+        sender=alerts.email_from,
+        use_tls=alerts.email_use_tls,
+        username=alerts.email_username,
+        password=alerts.email_password,
+        timeout=alerts.email_timeout,
+        allowed_hosts=tuple(alerts.smtp_allowed_hosts),
+    )

messagefoundry/pipeline/state_convergence.py

@@ -0,0 +1,143 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""Cluster-wide transform-state read-through convergence (Track B Step 6b).
+
+Transform state (ADR 0005) is written inside ``PostgresStore.transform_handoff`` and published into the
+**writing node's** own ``_state_cache`` only. A sibling node never sees it, so ``state_get(ns, key)`` on a
+follower returns stale/missing data for keys another node wrote. ``state_get`` is on the hot path of
+**every** transform and must stay a pure synchronous dict lookup (no ``await``, no per-read DB), so
+convergence is a background, off-path refresh of the local cache — exactly mirroring the reference-cache
+convergence Step 6 ships (:class:`~messagefoundry.pipeline.reference_sync.ReferenceSyncRunner`).
+
+:class:`StateConvergenceRunner` is the engine-owned background loop on every clustered node that, each
+interval, calls a converge callable (``store.converge_state_cache``) which read-throughs any namespace
+whose shared per-namespace version is newer than the one this node reflects, and logs the refreshed
+namespace **names** (never keys/values — those may be PHI). The engine only spawns it in clustered mode
+(``coordinator.is_clustered()``), so single-node / SQLite never pays for it.
+
+It mirrors :class:`~messagefoundry.pipeline.config_convergence.ConfigConvergenceRunner`'s shape
+(``start``/``stop``/``_run``/``_sleep``/``converge_once``, supervised + cooperatively cancellable) and
+copies the **PHI/error discipline** of
+:class:`~messagefoundry.pipeline.reference_sync.ReferenceSyncRunner`: on a convergence/decrypt failure log
+the exception **class only** (``type(exc).__name__``), NEVER ``str(exc)`` and NEVER ``log.exception`` (a
+decrypt failure can carry snapshot bytes / a PHI-bearing key), keep the last-good cache, retry next
+interval, and alert via the AlertSink.
+
+Decoupled from the store: it takes a plain converge callback (like
+:class:`~messagefoundry.pipeline.config_convergence.ConfigConvergenceRunner` takes ``reload``) so the
+dependency direction stays one-way (pipeline only — it never pulls the API or console into the engine).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Awaitable, Callable
+
+from messagefoundry.pipeline.alerts import AlertSink, LoggingAlertSink
+
+__all__ = ["StateConvergenceRunner"]
+
+log = logging.getLogger(__name__)
+
+
+class StateConvergenceRunner:
+    """Polls the shared transform-state versions each tick and read-throughs newer namespaces locally.
+
+    Construct with ``converge`` (an awaitable that read-throughs any newer shared state into this node's
+    local cache and returns the refreshed namespace names, e.g. ``store.converge_state_cache``) and the
+    poll ``interval_seconds``. The runner never imports the store — it takes ``converge`` as a plain
+    callback so the dependency direction stays one-way (pipeline only).
+    """
+
+    def __init__(
+        self,
+        *,
+        converge: Callable[[], Awaitable[list[str]]],
+        interval_seconds: float,
+        alert_sink: AlertSink | None = None,
+    ) -> None:
+        self._converge = converge
+        self._interval_seconds = interval_seconds
+        self._alert_sink: AlertSink = alert_sink or LoggingAlertSink()
+        self._stop = asyncio.Event()
+        self._task: asyncio.Task[None] | None = None
+
+    # --- lifecycle -----------------------------------------------------------
+
+    def start(self) -> None:
+        """Spawn the supervised convergence loop (idempotent: a second call while running is a no-op)."""
+        if self._task is not None:
+            return
+        self._stop.clear()
+        self._task = asyncio.create_task(self._run())
+        log.info(
+            "cluster transform-state convergence enabled: read-through every %gs",
+            self._interval_seconds,
+        )
+
+    async def stop(self) -> None:
+        """Signal the loop and await its exit (idempotent)."""
+        self._stop.set()
+        task = self._task
+        self._task = None
+        if task is not None:
+            task.cancel()
+            try:
+                await task
+            except asyncio.CancelledError:
+                pass
+
+    async def _run(self) -> None:
+        # One isolated pass per interval; converge_once already swallows + alerts a pass error (NOT
+        # log.exception — a decrypt failure can carry PHI), so the loop just keeps going. Cooperatively
+        # cancellable via _stop.
+        while not self._stop.is_set():
+            await self.converge_once()
+            await self._sleep(self._interval_seconds)
+
+    async def _sleep(self, delay: float) -> None:
+        """Sleep up to ``delay``, waking immediately on stop (so shutdown isn't held by the interval)."""
+        try:
+            await asyncio.wait_for(self._stop.wait(), delay)
+        except asyncio.TimeoutError:
+            pass
+
+    # --- one pass ------------------------------------------------------------
+
+    async def converge_once(self) -> list[str]:
+        """Read-through any newer shared transform-state into this node's local cache. Returns the
+        refreshed namespace names (``[]`` when nothing advanced).
+
+        Errors are isolated: on any ``Exception`` (but ``CancelledError`` re-raises so shutdown isn't
+        swallowed) log the error CLASS only — never ``str(exc)`` and never ``log.exception`` (a decrypt
+        failure can carry snapshot bytes / a PHI-bearing key, CLAUDE.md §9) — alert, keep the last-good
+        cache, and return ``[]`` so the loop retries next interval rather than dying."""
+        try:
+            refreshed = await self._converge()
+        except asyncio.CancelledError:
+            raise
+        except Exception as exc:
+            kind = type(exc).__name__
+            log.warning(
+                "cluster: transform-state cache convergence failed (keeping current): %s", kind
+            )
+            self._alert(f"state cache convergence failed ({kind})")
+            return []
+        if refreshed:
+            # Names only (a namespace name is operator config, not PHI) at INFO so an operator can see a
+            # follower converge; never the keys/values (which may be PHI).
+            log.info(
+                "cluster: transform-state cache converged %d namespace(s): %s",
+                len(refreshed),
+                ", ".join(refreshed),
+            )
+        return refreshed
+
+    def _alert(self, detail: str) -> None:
+        # The AlertSink has no state-specific event; reuse connection_stopped as the generic "a named
+        # component degraded" signal (never raises — be defensive anyway).
+        try:
+            self._alert_sink.connection_stopped("transform-state", detail=detail)
+        except Exception:
+            log.warning("transform-state convergence alert sink failed", exc_info=True)