Alerting on Good-Standing Status Changes Across a Portfolio #

This guide is part of the Good-Standing Certificate Automation area within the Secretary of State Portal & API Ingestion framework. It takes the typed StatusChange events produced by the portfolio diff and turns them into routed alerts: a regression to not-in-good-standing pages counsel within minutes, a lapse into delinquency opens a ticket, and a benign reinstatement lands quietly in a weekly digest — with flapping suppressed and a defined escalation ladder so the right person is woken at the right severity and no one else is.

Scope of This Page #

This page covers the alert router: severity classification (mapping a change’s direction and destination status to a rank), deduplication and flap suppression (collapsing repeat and oscillating events so a single lapse is not paged five times), and channel routing with an escalation ladder (page, ticket, or digest, with unacknowledged criticals climbing the ladder). It deliberately excludes the upstream detection — computing the change set is owned by Bulk Good-Standing Certificate Polling and Status Diffing — and the downstream transport of a message once a channel is chosen, which is owned by Calendar Sync & Notification Pipelines. Here we assume a stream of typed StatusChange events and decide what each one is worth and where it goes.

The Constraint That Forces Severity Ranking #

Not every status change carries the same legal weight, and treating them uniformly is its own failure: page counsel for every event and the pages become noise that gets muted; digest every event and a genuine emergency waits a week. The severity of a good-standing change is a function of the destination status and its statutory consequence. A California entity moving to suspended under Cal. Corp. Code § 2205 has lost the capacity to prosecute or defend a lawsuit — that is an operational emergency measured in hours, not days. A Delaware corporation declared void under 8 Del. C. § 510 cannot close a financing. By contrast, a move from good standing to delinquent under a curable grace window — a late New York biennial statement under N.Y. BCL § 408, or a Texas franchise-tax delinquency still inside its cure period under Tex. Tax Code § 171 — is urgent but recoverable, and a recovery back to good standing after a reinstatement is informational. The router must therefore encode the same consequence hierarchy the compliance organisation already uses for deadlines, which is why its severity mapping is aligned with the Priority Scoring Algorithms that rank filing obligations: the two systems agree that statutory consequence, not event frequency, sets the rank.

Prerequisites #

• Python 3.10+ — for match on the change kind and destination status, X | Y unions, and enum severities.
• A stream of typed StatusChange events — emitted per run by the portfolio differ, each carrying the previous and current canonical status.
• A monotonic clock and short-lived state — an in-process cache (or Redis for a multi-worker fleet) keyed by a change fingerprint, holding a last-emitted timestamp and a flap window per entity.
• A channel abstraction — a thin sink that accepts (channel, alert) and hands off to the actual page/ticket/digest transport; this module chooses the channel, it does not send the message.
• Standard library — collections.deque, dataclasses, enum, json, logging, time for the dedupe cache, flap tracker, and structured logging.

Implementation: A Severity-Ranked Alert Router with Suppression #

The router classifies each StatusChange into a severity, fingerprints it to drop exact duplicates inside a dedupe window, checks a per-entity flap tracker to suppress an oscillating entity, and routes the survivor to a channel — paging for critical, a ticket for high, a digest for informational — with an escalation note attached to unacknowledged criticals. Comments mark the compliance-critical lines.

from __future__ import annotations

import enum
import json
import logging
import time
from collections import deque
from dataclasses import dataclass, field
from datetime import datetime, timezone

logging.basicConfig(level=logging.INFO, format="%(message)s")
logger = logging.getLogger("good_standing.alerting")


class GoodStandingStatus(enum.IntEnum):
    NOT_IN_GOOD_STANDING = 0
    DELINQUENT = 1
    GOOD_STANDING = 2


class Severity(enum.IntEnum):
    INFO = 0
    HIGH = 1
    CRITICAL = 2


class Channel(str, enum.Enum):
    PAGE = "page"      # wakes counsel — reserved for CRITICAL regressions
    TICKET = "ticket"  # same-business-day queue for HIGH, curable lapses
    DIGEST = "digest"  # periodic roll-up for INFO recoveries and renewals


@dataclass(frozen=True)
class StatusChange:
    entity_id: str
    jurisdiction: str
    previous: GoodStandingStatus
    current: GoodStandingStatus
    observed_at: datetime


@dataclass(frozen=True)
class Alert:
    entity_id: str
    jurisdiction: str
    severity: Severity
    channel: Channel
    headline: str
    escalates: bool  # a CRITICAL that climbs the ladder if unacknowledged


def classify(change: StatusChange) -> Severity:
    """Severity is a function of the destination status and direction, not frequency."""
    if change.current > change.previous:
        return Severity.INFO  # a recovery / reinstatement is never an emergency
    match change.current:
        case GoodStandingStatus.NOT_IN_GOOD_STANDING:
            return Severity.CRITICAL  # suspended/void — capacity to sue or close is lost
        case GoodStandingStatus.DELINQUENT:
            return Severity.HIGH      # past due but inside a curable grace window
        case _:
            return Severity.INFO


_CHANNEL_FOR: dict[Severity, Channel] = {
    Severity.CRITICAL: Channel.PAGE,
    Severity.HIGH: Channel.TICKET,
    Severity.INFO: Channel.DIGEST,
}


class AlertRouter:
    """Classify, deduplicate, flap-suppress, and route good-standing status changes."""

    def __init__(self, dedupe_ttl_s: float = 3600.0,
                 flap_threshold: int = 3, flap_window_s: float = 86_400.0) -> None:
        self._dedupe_ttl = dedupe_ttl_s          # exact-duplicate window
        self._flap_threshold = flap_threshold    # changes within window that mark flapping
        self._flap_window = flap_window_s
        self._last_emitted: dict[str, float] = {}       # fingerprint -> monotonic ts
        self._flaps: dict[str, deque[float]] = {}       # entity -> recent change times

    @staticmethod
    def _fingerprint(change: StatusChange, severity: Severity) -> str:
        # Same entity + same destination severity within TTL is the "same" alert.
        return f"{change.entity_id}|{change.jurisdiction}|{severity.name}"

    def _is_duplicate(self, fp: str, now: float) -> bool:
        last = self._last_emitted.get(fp)
        return last is not None and (now - last) < self._dedupe_ttl

    def _is_flapping(self, entity_id: str, now: float) -> bool:
        window = self._flaps.setdefault(entity_id, deque())
        window.append(now)
        while window and (now - window[0]) > self._flap_window:
            window.popleft()  # evict observations older than the flap window
        return len(window) >= self._flap_threshold

    def route(self, change: StatusChange) -> Alert | None:
        now = time.monotonic()
        severity = classify(change)
        fp = self._fingerprint(change, severity)

        # Suppression 1: an exact repeat inside the dedupe window is counted, not re-sent.
        if self._is_duplicate(fp, now):
            logger.info(json.dumps({"event": "alert_deduped", "fingerprint": fp}))
            return None

        # Suppression 2: an oscillating entity is collapsed — but never a CRITICAL, because
        # a real loss of good standing must page even if the entity has been noisy.
        if severity is not Severity.CRITICAL and self._is_flapping(change.entity_id, now):
            logger.warning(json.dumps({
                "event": "alert_suppressed_flapping",
                "entity_id": change.entity_id, "severity": severity.name,
            }))
            return None

        self._last_emitted[fp] = now
        channel = _CHANNEL_FOR[severity]
        alert = Alert(
            entity_id=change.entity_id, jurisdiction=change.jurisdiction,
            severity=severity, channel=channel,
            headline=f"{change.entity_id} ({change.jurisdiction}): "
                     f"{change.previous.name} -> {change.current.name}",
            escalates=severity is Severity.CRITICAL,  # criticals climb the ladder on no-ack
        )
        logger.info(json.dumps({
            "event": "alert_routed", "entity_id": alert.entity_id,
            "severity": alert.severity.name, "channel": alert.channel.value,
            "escalates": alert.escalates,
        }))
        return alert


def route_batch(router: AlertRouter, changes: list[StatusChange]) -> list[Alert]:
    """Route a run's worth of status changes; suppressed events return no alert."""
    alerts = [a for c in changes if (a := router.route(c)) is not None]
    logger.info(json.dumps({
        "event": "batch_routed", "changes": len(changes), "alerts": len(alerts),
        "paged": sum(a.channel is Channel.PAGE for a in alerts),
    }))
    return alerts

The router is intentionally stateful but bounded: its only memory is the dedupe cache and the per-entity flap window, both self-evicting, so it does not accumulate unbounded state across runs. Crucially, flap suppression never applies to a CRITICAL — an entity that has been noisy can still genuinely lose good standing, and swallowing that page to reduce noise would be exactly the wrong trade. Suppression buys quiet on the recoverable events and spends none of that budget on the emergency.

Configuration Reference #

These parameters govern severity and suppression behaviour and are configuration data owned by compliance, not branches in the routing loop.

Failure Modes and Fallback Routing #

Each fault maps onto the four-tier scheme in the parent framework’s error categorization & retry logic — transient, statutory, data-validation, and system — and the router responds to each differently.

1. An unstable read oscillates an entity between good and delinquent (transient). The flap tracker counts the changes in the window and, once past flap_threshold, suppresses the HIGH/INFO churn while still counting it, so a genuinely flaky portal produces one suppression record instead of a dozen tickets. If any oscillation lands on not-in-good-standing, the CRITICAL bypasses suppression and pages regardless.
2. A real regression re-fires every sweep because the entity stays delinquent (statutory). The dedupe window collapses the repeats into a single alert per TTL, so counsel is not re-paged hourly for a known-open lapse; the ticket remains open and the escalation ladder, not a new alert, drives urgency. Tune dedupe_ttl_s shorter than the statutory cure window so a lapse that persists past cure re-alerts.
3. The channel sink is unreachable when a CRITICAL is routed (system). The router’s job ends at choosing the channel; delivery is owned by Calendar Sync & Notification Pipelines, which must treat a failed page delivery as its own retryable event. A routed-but-undelivered CRITICAL should never be silently dropped — the escalates flag exists so the delivery layer climbs the ladder on no-acknowledgement.
4. A malformed change with an impossible transition arrives (data-validation). A change whose current equals previous should never reach the router — the differ drops unchanged reads — but if one does, classify treats a same-rank move as INFO rather than crashing, and the anomaly is logged for the upstream differ to investigate instead of paging counsel over a non-event.

Frequently Asked Questions #

Related #

• Good-Standing Certificate Automation
• Bulk Good-Standing Certificate Polling and Status Diffing
• Calendar Sync & Notification Pipelines
• Priority Scoring Algorithms
• Secretary of State Portal & API Ingestion