detectkit 0.51.0__tar.gz → 0.52.0__tar.gz

{detectkit-0.51.0/detectkit.egg-info → detectkit-0.52.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: detectkit
-Version: 0.51.0
+Version: 0.52.0
 Summary: Metric monitoring with automatic anomaly detection
 Author: detectkit team
 License: MIT
@@ -91,11 +91,11 @@ Dynamic: license-file
 ## Features
 
 - **Pure numpy arrays** — no pandas dependency in core logic
-- **Statistical detectors** — Z-Score, MAD, IQR, Manual Bounds
+- **Statistical detectors** — Z-Score, MAD, IQR, Manual Bounds, and a prediction-based Autoreg (AR) detector for fast-moving, non-seasonal metrics
 - **Trend & seasonality handling** — seasonality grouping, recency weighting (`half_life`), robust linear detrending for slowly drifting metrics
 - **Multi-channel alerting** — Mattermost, Slack, Telegram, Email, Webhook
 - **@mentions** — tag users/groups in alerts, each channel formats natively
-- **Alert lifecycle** — consecutive anomalies, cooldown, recovery notifications, no-data alerts
+- **Alert lifecycle** — consecutive anomalies, fraction-of-window rule (`anomaly_window` + `min_anomaly_share`), cooldown, recovery notifications, no-data alerts
 - **Project-level error alerts** — catch DB outages and pipeline crashes once per run
 - **Database agnostic** — ClickHouse, PostgreSQL, MySQL
 - **Idempotent** — resume from interruptions, no duplicate processing

{detectkit-0.51.0 → detectkit-0.52.0}/README.md

@@ -18,11 +18,11 @@
 ## Features
 
 - **Pure numpy arrays** — no pandas dependency in core logic
-- **Statistical detectors** — Z-Score, MAD, IQR, Manual Bounds
+- **Statistical detectors** — Z-Score, MAD, IQR, Manual Bounds, and a prediction-based Autoreg (AR) detector for fast-moving, non-seasonal metrics
 - **Trend & seasonality handling** — seasonality grouping, recency weighting (`half_life`), robust linear detrending for slowly drifting metrics
 - **Multi-channel alerting** — Mattermost, Slack, Telegram, Email, Webhook
 - **@mentions** — tag users/groups in alerts, each channel formats natively
-- **Alert lifecycle** — consecutive anomalies, cooldown, recovery notifications, no-data alerts
+- **Alert lifecycle** — consecutive anomalies, fraction-of-window rule (`anomaly_window` + `min_anomaly_share`), cooldown, recovery notifications, no-data alerts
 - **Project-level error alerts** — catch DB outages and pipeline crashes once per run
 - **Database agnostic** — ClickHouse, PostgreSQL, MySQL
 - **Idempotent** — resume from interruptions, no duplicate processing

{detectkit-0.51.0 → detectkit-0.52.0}/detectkit/__init__.py

@@ -4,7 +4,7 @@ detectk - Anomaly Detection for Time-Series Metrics
 A Python library for data analysts and engineers to monitor metrics with automatic anomaly detection.
 """
 
-__version__ = "0.51.0"
+__version__ = "0.52.0"
 
 from detectkit.core.interval import Interval
 from detectkit.core.models import ColumnDefinition, TableModel

{detectkit-0.51.0 → detectkit-0.52.0}/detectkit/alerting/channels/base.py

@@ -111,6 +111,49 @@ class AlertData:
     interval_seconds: int | None = None
     onset_timestamp: Any | None = None
     streak_capped: bool = False
+    # Fraction alert rule (``anomaly_window`` + ``min_anomaly_share``).
+    # ``window_points`` / ``min_anomaly_share`` carry the CONFIGURED rule (set on
+    # every alert of a share-configured config so the rule chip can name it);
+    # ``window_matched`` + ``fired_by_share`` are set only when the fraction rule
+    # (not the consecutive rule) actually fired, switching the lead sentence to
+    # the window story. All default off, so existing alerts render byte-identical.
+    window_points: int | None = None
+    window_matched: int | None = None
+    min_anomaly_share: float | None = None
+    fired_by_share: bool = False
+
+
+def format_rule_display(
+    *,
+    min_detectors: Any,
+    direction_policy: Any,
+    consecutive_required: Any,
+    window_points: int | None = None,
+    min_anomaly_share: float | None = None,
+    fired_by_share: bool = False,
+    interval_seconds: int | None = None,
+) -> str:
+    """The alert-rule chip content, shared by every rendering surface.
+
+    Legacy configs (no fraction rule) render the exact historical chip —
+    ``min_detectors=… · direction=… · consecutive=…`` — byte-identical. A
+    share-configured config names both OR-ed rules; a share-FIRED alert leads
+    with the share rule (the one that actually tripped).
+    """
+    from detectkit.utils.datetime_utils import format_duration
+
+    base = f"min_detectors={min_detectors} · direction={direction_policy}"
+    if window_points and min_anomaly_share is not None:
+        pct = f"{min_anomaly_share * 100:g}%"
+        if interval_seconds:
+            span = format_duration(window_points * interval_seconds)
+        else:
+            span = f"{window_points} points"
+        share_rule = f"share>={pct} over {span}"
+        if fired_by_share:
+            return f"{base} · {share_rule}"
+        return f"{base} · consecutive={consecutive_required} (or {share_rule})"
+    return f"{base} · consecutive={consecutive_required}"
 
 
 class BaseAlertChannel(ABC):
@@ -187,6 +230,10 @@ class BaseAlertChannel(ABC):
         - {consecutive_count} — true consecutive streak length (resolved at
           fire time, not capped at the rule's threshold)
         - {consecutive_required} — configured consecutive threshold (rule)
+        - {rule_display} — the full alert-rule chip content (consecutive
+          and/or the fraction rule, whichever is configured/fired)
+        - {window_points} / {window_matched} — fraction-rule window size and
+          matched count (empty when the fraction rule isn't configured/fired)
         - {interval_display} — metric interval as a string (e.g. "10min")
         - {duration_display} — how long the streak/incident lasted
           (e.g. "2h 30m"; "over …" when it predates the lookback window)
@@ -349,7 +396,42 @@ class BaseAlertChannel(ABC):
         capped = alert_data.streak_capped
         interval_display = str(Interval(interval_seconds)) if interval_seconds else ""
 
-        if interval_seconds and streak >= 1:
+        if (
+            alert_data.fired_by_share
+            and alert_data.window_points
+            and alert_data.window_matched is not None
+        ):
+            # Fraction-rule story: a share alert has scattered matches, not a
+            # contiguous streak, so the lead reports the window share instead
+            # of a consecutive-run duration.
+            window = alert_data.window_points
+            matched = alert_data.window_matched
+            observed_pct = f"{matched / window * 100:.0f}%"
+            threshold_pct = (
+                f"{alert_data.min_anomaly_share * 100:g}%"
+                if alert_data.min_anomaly_share is not None
+                else ""
+            )
+            streak_display = f"{matched}/{window}"
+            started_display = onset_str
+            if interval_seconds:
+                duration_display = format_duration(window * interval_seconds)
+                anomaly_lead = (
+                    f"{matched} of the last {window} {interval_display} intervals were "
+                    f"anomalous ({observed_pct}) — at or above the {threshold_pct} share "
+                    f"threshold over {duration_display}."
+                )
+            else:
+                duration_display = ""
+                anomaly_lead = (
+                    f"{matched} of the last {window} intervals were anomalous "
+                    f"({observed_pct}) — at or above the {threshold_pct} share threshold."
+                )
+            recovery_lead = (
+                "The alert condition no longer holds — the metric is back within "
+                "expected bounds."
+            )
+        elif interval_seconds and streak >= 1:
             duration_display = format_duration(streak * interval_seconds)
             if capped:
                 duration_display = f"over {duration_display}"
@@ -387,7 +469,14 @@ class BaseAlertChannel(ABC):
         # in (direct-API callers). The firing message doesn't show it: there it
         # coincides with the latest point the alert is firing on.
         fired_display = ""
-        if alert_data.onset_timestamp is not None and interval_seconds and not capped:
+        if (
+            alert_data.onset_timestamp is not None
+            and interval_seconds
+            and not capped
+            # A share-fired alert's onset is the first matched point in the
+            # window; onset + consecutive math doesn't describe its fire time.
+            and not alert_data.fired_by_share
+        ):
             req = (
                 consecutive_required if (consecutive_required and consecutive_required >= 1) else 1
             )
@@ -451,6 +540,20 @@ class BaseAlertChannel(ABC):
         project_name = alert_data.project_name or ""
         project_name_prefix = f"[{alert_data.project_name}] " if alert_data.project_name else ""
 
+        # Alert-rule chip content — the single shared string every surface
+        # renders (default templates, webhook attachment, Telegram HTML, email).
+        # Built from the SAME fallback-resolved values as the individual keys,
+        # so legacy configs render the historical chip byte-identically.
+        rule_display = format_rule_display(
+            min_detectors=min_detectors,
+            direction_policy=direction_policy,
+            consecutive_required=consecutive_required,
+            window_points=alert_data.window_points,
+            min_anomaly_share=alert_data.min_anomaly_share,
+            fired_by_share=alert_data.fired_by_share,
+            interval_seconds=interval_seconds,
+        )
+
         # Status keyword
         if alert_data.is_error:
             status = "ERROR"
@@ -482,6 +585,9 @@ class BaseAlertChannel(ABC):
             "severity": alert_data.severity,
             "consecutive_count": alert_data.consecutive_count,
             "consecutive_required": consecutive_required,
+            "rule_display": rule_display,
+            "window_points": alert_data.window_points or "",
+            "window_matched": alert_data.window_matched or "",
             "interval_display": interval_display,
             "duration_display": duration_display,
             "streak_display": streak_display,
@@ -617,8 +723,7 @@ class BaseAlertChannel(ABC):
             "🔴 {project_name_prefix}Alert: {metric_name}\n"
             "{description_line}"
             "{anomaly_lead}\n"
-            "Rule: min_detectors={min_detectors} · "
-            "direction={direction_policy} · consecutive={consecutive_required}\n"
+            "Rule: {rule_display}\n"
             "\n"
             "Value: {value_display} | Expected: {expected_range}\n"
             "Quorum: {detector_count}/{min_detectors} · {direction}\n"
@@ -642,8 +747,7 @@ class BaseAlertChannel(ABC):
             "🟢 {project_name_prefix}Alert cleared: {metric_name}\n"
             "{description_line}"
             "{recovery_lead}\n"
-            "Rule: min_detectors={min_detectors} · "
-            "direction={direction_policy} · consecutive={consecutive_required}\n"
+            "Rule: {rule_display}\n"
             "\n"
             "Value: {value_display} | Expected: {expected_range}\n"
             "{window_line}"

{detectkit-0.51.0 → detectkit-0.52.0}/detectkit/alerting/channels/email.py

@@ -385,11 +385,9 @@ class EmailChannel(BaseAlertChannel):
         Mirrors the inline-code "Rule chip" the webhook/Telegram channels render,
         so the same firing rule reads the same way in every channel.
         """
-        expr = (
-            f"min_detectors={ctx['min_detectors']} · "
-            f"direction={html.escape(str(ctx['direction_policy']))} · "
-            f"consecutive={ctx['consecutive_required']}"
-        )
+        # Keep the middot as the ``·`` entity the chip has always used,
+        # so legacy (consecutive-only) configs render byte-identical HTML.
+        expr = html.escape(str(ctx["rule_display"])).replace("·", "·")
         return (
             f'<tr><td style="padding:0 24px 14px 24px;font-family:{_SANS};font-size:13px;'
             f'color:{_MUTED};mso-line-height-rule:exactly;line-height:22px;">'

{detectkit-0.51.0 → detectkit-0.52.0}/detectkit/alerting/channels/telegram.py

@@ -165,11 +165,7 @@ class TelegramChannel(BaseAlertChannel):
             # Description (how long it's been going on) leads; the Rule chip sits
             # right above the evidence it explains.
             lines.append(esc(ctx["anomaly_lead"]))
-            lines.append(
-                f"<b>Rule</b> <code>min_detectors={ctx['min_detectors']} · "
-                f"direction={esc(ctx['direction_policy'])} · "
-                f"consecutive={ctx['consecutive_required']}</code>"
-            )
+            lines.append(f"<b>Rule</b> <code>{esc(ctx['rule_display'])}</code>")
             lines.append("")
             lines.append(
                 f"• Value: <code>{esc(ctx['value_display'])}</code> · "
@@ -193,11 +189,7 @@ class TelegramChannel(BaseAlertChannel):
                 lines.append(f"• Parameters: <code>{esc(params)}</code>")
         elif kind == "recovery":
             lines.append(esc(ctx["recovery_lead"]))
-            lines.append(
-                f"<b>Rule</b> <code>min_detectors={ctx['min_detectors']} · "
-                f"direction={esc(ctx['direction_policy'])} · "
-                f"consecutive={ctx['consecutive_required']}</code>"
-            )
+            lines.append(f"<b>Rule</b> <code>{esc(ctx['rule_display'])}</code>")
             lines.append("")
             lines.append(
                 f"• Value: <code>{esc(ctx['value_display'])}</code> · "

{detectkit-0.51.0 → detectkit-0.52.0}/detectkit/alerting/channels/webhook.py

@@ -291,11 +291,7 @@ class WebhookChannel(BaseAlertChannel):
         # inline-code chip so it reads as "this is the config that fired" at a
         # glance. Backticks render identically on Slack and Mattermost; the bold
         # label is platform-aware (see ``_bold``). Leads the body, above the fold.
-        rule_chip = f"{self._bold('Rule')} " + code(
-            f"min_detectors={ctx['min_detectors']} · "
-            f"direction={ctx['direction_policy']} · "
-            f"consecutive={ctx['consecutive_required']}"
-        )
+        rule_chip = f"{self._bold('Rule')} " + code(ctx["rule_display"])
 
         # Links — compact clickable labels (never raw URL strings: a Grafana URL
         # can be a paragraph long once it carries variables), rendered in the
@@ -458,8 +454,7 @@ class WebhookChannel(BaseAlertChannel):
         return (
             "{description_line}"
             "{anomaly_lead}\n"
-            "Rule: min_detectors={min_detectors} · "
-            "direction={direction_policy} · consecutive={consecutive_required}\n"
+            "Rule: {rule_display}\n"
             "\n"
             "Value: {value_display} | Expected: {expected_range}\n"
             "Quorum: {detector_count}/{min_detectors} · {direction}\n"
@@ -479,8 +474,7 @@ class WebhookChannel(BaseAlertChannel):
         return (
             "{description_line}"
             "{recovery_lead}\n"
-            "Rule: min_detectors={min_detectors} · "
-            "direction={direction_policy} · consecutive={consecutive_required}\n"
+            "Rule: {rule_display}\n"
             "\n"
             "Value: {value_display} | Expected: {expected_range}\n"
             "{window_line}"

{detectkit-0.51.0 → detectkit-0.52.0}/detectkit/alerting/orchestrator/_decision.py

@@ -68,14 +68,96 @@ class _DecisionMixin(_OrchestratorBase):
         consecutive, latest_quorum, direction = self._count_consecutive_anomalies(
             detections_by_time, timestamps_sorted
         )
-        if not latest_quorum or consecutive < self.conditions.consecutive_anomalies:
-            return False, None
+        if latest_quorum and consecutive >= self.conditions.consecutive_anomalies:
+            # The decision is made; now resolve the *true* streak length/onset
+            # for the message (the shallow alert window caps ``consecutive`` at
+            # the rule threshold, which can't answer "how long has this been
+            # going on").
+            streak, onset_ts, capped = self._resolve_streak(latest_quorum[0].timestamp)
+            return True, self._build_alert_data(latest_quorum, streak, direction, onset_ts, capped)
+
+        # The consecutive rule didn't fire; try the fraction rule (OR-ed).
+        share_fire = self._share_fire(detections_by_time, timestamps_sorted)
+        if share_fire is not None:
+            matched, onset_ts, quorum, share_direction = share_fire
+            return True, self._build_alert_data(
+                quorum,
+                matched,
+                share_direction,
+                onset_ts,
+                False,
+                window_matched=matched,
+                fired_by_share=True,
+            )
+        return False, None
 
-        # The decision is made; now resolve the *true* streak length/onset for
-        # the message (the shallow alert window caps ``consecutive`` at the rule
-        # threshold, which can't answer "how long has this been going on").
-        streak, onset_ts, capped = self._resolve_streak(latest_quorum[0].timestamp)
-        return True, self._build_alert_data(latest_quorum, streak, direction, onset_ts, capped)
+    def _share_fire(
+        self,
+        detections_by_time: dict[np.datetime64, list[DetectionRecord]],
+        timestamps_sorted: Sequence[np.datetime64],
+    ) -> tuple[int, np.datetime64, list[DetectionRecord], str | None] | None:
+        """Evaluate the fraction rule at the latest point.
+
+        Fires when the latest point itself meets the direction-aware quorum
+        (so an alert never fires on a stale window whose newest point is
+        already clean) AND at least ``min_anomaly_share`` of the trailing
+        ``window_points`` grid slots meet the quorum. Grid slots with no
+        detections (gaps, outages) count in the denominator but never in the
+        numerator — missing data makes the rule harder to fire, not easier.
+
+        Returns ``(matched, onset_ts, latest_quorum, direction)`` or ``None``.
+        For ``"same"`` the direction is locked from the latest quorum, exactly
+        like the consecutive walk.
+        """
+        window = self.conditions.window_points or 0
+        share_required = self.conditions.min_anomaly_share
+        if window <= 0 or share_required is None or not timestamps_sorted:
+            return None
+
+        latest_ts = timestamps_sorted[0]
+        latest_anomalies = [d for d in detections_by_time[latest_ts] if d.is_anomaly]
+        quorum, direction = self._quorum_at(latest_anomalies, None)
+        if quorum is None:
+            return None
+
+        locked = direction if self.conditions.direction == "same" else None
+        matched, _total, onset_ts = self._window_share_counts(detections_by_time, latest_ts, locked)
+        if matched / window < share_required:
+            return None
+        return matched, onset_ts, quorum, direction
+
+    def _window_share_counts(
+        self,
+        detections_by_time: dict[np.datetime64, list[DetectionRecord]],
+        latest_ts: np.datetime64,
+        locked_direction: str | None,
+    ) -> tuple[int, int, np.datetime64]:
+        """Count quorum-meeting grid slots in the window ending at *latest_ts*.
+
+        Walks the ``window_points`` grid slots ``latest_ts, latest_ts - step,
+        …`` looking each up in *detections_by_time* (an absent slot counts only
+        in the denominator). Returns ``(matched, window_points, onset_ts)``
+        where ``onset_ts`` is the oldest matching slot (the incident onset as
+        far as the window can see; falls back to *latest_ts* when only the
+        latest matches).
+        """
+        window = self.conditions.window_points or 0
+        step = np.timedelta64(self.interval.seconds, "s")
+        matched = 0
+        onset_ts = latest_ts
+        for k in range(window):
+            ts = latest_ts - step * k
+            records = detections_by_time.get(ts)
+            if not records:
+                continue
+            anomalies = [d for d in records if d.is_anomaly]
+            if not anomalies:
+                continue
+            quorum, _ = self._quorum_at(anomalies, locked_direction)
+            if quorum is not None:
+                matched += 1
+                onset_ts = ts
+        return matched, window, onset_ts
 
     def _resolve_streak(self, latest_ts: np.datetime64) -> tuple[int, np.datetime64, bool]:
         """Resolve the full anomalous run ending at *latest_ts*.
@@ -164,6 +246,29 @@ class _DecisionMixin(_OrchestratorBase):
             return anomalies, None
         return None, None
 
+    def _share_still_elevated(
+        self,
+        detections_by_time: dict[np.datetime64, list[DetectionRecord]],
+        latest_ts: np.datetime64,
+        locked_direction: str | None,
+    ) -> bool:
+        """Fraction-rule recovery hysteresis.
+
+        ``True`` while the window share stays at or above **half** the firing
+        threshold — a share hovering right at the threshold would otherwise
+        flap alert/recover on every boundary crossing. Always ``False`` when
+        the fraction rule isn't configured, so consecutive-only configs
+        recover exactly as before.
+        """
+        window = self.conditions.window_points or 0
+        share_required = self.conditions.min_anomaly_share
+        if window <= 0 or share_required is None:
+            return False
+        matched, total, _onset = self._window_share_counts(
+            detections_by_time, latest_ts, locked_direction
+        )
+        return total > 0 and matched / total >= share_required / 2.0
+
     def _count_consecutive_anomalies(
         self,
         detections_by_time: dict[np.datetime64, list[DetectionRecord]],
@@ -227,6 +332,8 @@ class _DecisionMixin(_OrchestratorBase):
         direction: str | None,
         onset_timestamp: np.datetime64 | None = None,
         streak_capped: bool = False,
+        window_matched: int | None = None,
+        fired_by_share: bool = False,
     ) -> AlertData:
         primary = self._primary_record(anomalies)
 
@@ -296,6 +403,13 @@ class _DecisionMixin(_OrchestratorBase):
             interval_seconds=self.interval.seconds,
             onset_timestamp=onset_timestamp,
             streak_capped=streak_capped,
+            # Fraction rule: the configured window/share ride on every alert of
+            # a share-configured config (so the rule chip can name both rules);
+            # the matched count + flag only on a share-fired one.
+            window_points=self.conditions.window_points,
+            min_anomaly_share=self.conditions.min_anomaly_share,
+            window_matched=window_matched,
+            fired_by_share=fired_by_share,
         )
 
     def should_alert_no_data(

{detectkit-0.51.0 → detectkit-0.52.0}/detectkit/alerting/orchestrator/_recovery.py

@@ -58,8 +58,9 @@ class _RecoveryMixin(_OrchestratorBase):
             return False
 
         last_point = self.get_last_complete_point()
-        # +5 for safety margin so we don't truncate the consecutive window.
-        num_points = self.conditions.consecutive_anomalies + 5
+        # The wider of the two rules' windows, +5 safety margin so we don't
+        # truncate the consecutive/fraction window.
+        num_points = self.conditions.lookback_points + 5
 
         recent_detections = self.internal.get_recent_detections(
             metric_name=self.metric_name,
@@ -78,20 +79,48 @@ class _RecoveryMixin(_OrchestratorBase):
         latest_anomalies = [d for d in detections_by_time[timestamps_sorted[0]] if d.is_anomaly]
 
         direction_condition = self.conditions.direction
+        locked_direction: str | None = None
         if direction_condition == "down":
             blocking = [d for d in latest_anomalies if d.direction == "down"]
+            locked_direction = "down"
         elif direction_condition == "up":
             blocking = [d for d in latest_anomalies if d.direction == "up"]
+            locked_direction = "up"
         elif direction_condition == "same":
             trigger_direction = self._get_alert_trigger_direction(last_alert_timestamp)
             if trigger_direction is None:
                 blocking = latest_anomalies  # conservative fallback
             else:
                 blocking = [d for d in latest_anomalies if d.direction == trigger_direction]
+            locked_direction = trigger_direction
         else:  # "any" / unknown — preserve historical behaviour
             blocking = latest_anomalies
 
-        return len(blocking) == 0
+        if blocking:
+            return False
+        # Fraction-rule hysteresis: with the share rule configured, a clean
+        # latest point isn't enough — the window share must also drop below
+        # half the firing threshold, or the alert would flap around it.
+        # The share is computed over an UNFILTERED fetch: ``recent_detections``
+        # above is ``created_after``-filtered (only rows persisted after the
+        # alert), which is right for the freshness check but would make almost
+        # every window slot look empty and defeat the hysteresis — the window
+        # walk needs the full stored history, whenever it was written.
+        # ``_share_still_elevated`` lives in _DecisionMixin; both mixins compose
+        # into AlertOrchestrator so the call resolves at runtime.
+        if self.conditions.min_anomaly_share is None or not self.conditions.window_points:
+            return True
+        window_rows = self.internal.get_recent_detections(
+            metric_name=self.metric_name,
+            last_point=last_point,
+            num_points=num_points,
+        )
+        window_records = hydrate_detection_records(window_rows)
+        if not window_records:
+            return True
+        window_by_time = self._group_by_timestamp(window_records)
+        latest_window_ts = max(window_by_time.keys())
+        return not self._share_still_elevated(window_by_time, latest_window_ts, locked_direction)
 
     def _get_alert_trigger_direction(self, last_alert_timestamp: datetime) -> str | None:
         """Return the direction of the anomaly that triggered the last alert.
@@ -194,10 +223,13 @@ class _RecoveryMixin(_OrchestratorBase):
             project_name=self.project_name,
             help_url=self.help_url,
             # Echo the rule that had fired so the recovery message names the
-            # same alert condition that just cleared.
+            # same alert condition that just cleared (including the fraction
+            # rule when configured, so fire and recovery render one chip).
             min_detectors=self.conditions.min_detectors,
             direction_policy=self.conditions.direction,
             consecutive_required=self.conditions.consecutive_anomalies,
+            window_points=self.conditions.window_points,
+            min_anomaly_share=self.conditions.min_anomaly_share,
             # Incident timing for the "Incident lasted …" line.
             interval_seconds=self.interval.seconds,
             onset_timestamp=onset_ts,

{detectkit-0.51.0 → detectkit-0.52.0}/detectkit/alerting/orchestrator/_replay.py

@@ -114,16 +114,34 @@ class _ReplayMixin(_OrchestratorBase):
             consecutive, latest_quorum, direction = self._count_consecutive_anomalies(
                 causal, ts_desc
             )
-            fired = (
-                latest_quorum is not None
-                and consecutive >= self.conditions.consecutive_anomalies
-                and not self._replay_in_cooldown(t, sim_last_alert, sim_last_recovery)
+            fired_consecutive = (
+                latest_quorum is not None and consecutive >= self.conditions.consecutive_anomalies
+            )
+            # The fraction rule is OR-ed, exactly like the live path — only
+            # evaluated when the consecutive rule didn't fire (and only when
+            # configured; ``_share_fire`` returns None otherwise).
+            share_fire = None if fired_consecutive else self._share_fire(causal, ts_desc)
+            fired = (fired_consecutive or share_fire is not None) and not self._replay_in_cooldown(
+                t, sim_last_alert, sim_last_recovery
             )
 
             if fired:
-                assert latest_quorum is not None  # narrowed by ``fired``
-                streak, onset, capped = self._replay_streak(causal, ts_desc)
-                ad = self._build_alert_data(latest_quorum, streak, direction, onset, capped)
+                if fired_consecutive:
+                    assert latest_quorum is not None  # narrowed by ``fired_consecutive``
+                    streak, onset, capped = self._replay_streak(causal, ts_desc)
+                    ad = self._build_alert_data(latest_quorum, streak, direction, onset, capped)
+                else:
+                    assert share_fire is not None  # narrowed by ``fired``
+                    matched, onset, quorum, share_direction = share_fire
+                    ad = self._build_alert_data(
+                        quorum,
+                        matched,
+                        share_direction,
+                        onset,
+                        False,
+                        window_matched=matched,
+                        fired_by_share=True,
+                    )
                 events.append(ReplayedEvent("anomaly", t, ad))
                 sim_last_alert = t
             elif (
@@ -209,20 +227,29 @@ class _ReplayMixin(_OrchestratorBase):
         latest_anomalies = [d for d in causal[latest_ts] if d.is_anomaly]
 
         policy = self.conditions.direction
+        locked_direction: str | None = None
         if policy == "down":
             blocking = [d for d in latest_anomalies if d.direction == "down"]
+            locked_direction = "down"
         elif policy == "up":
             blocking = [d for d in latest_anomalies if d.direction == "up"]
+            locked_direction = "up"
         elif policy == "same":
             trigger_direction = self._replay_trigger_direction(causal, sim_last_alert)
             if trigger_direction is None:
                 blocking = latest_anomalies  # conservative fallback
             else:
                 blocking = [d for d in latest_anomalies if d.direction == trigger_direction]
+            locked_direction = trigger_direction
         else:  # "any" / unknown — preserve historical behaviour
             blocking = latest_anomalies
 
-        return len(blocking) == 0
+        if blocking:
+            return False
+        # Fraction-rule hysteresis (in-memory analog of the live check): a share
+        # hovering at the threshold would flap alert/recover, so recovery also
+        # requires the window share to drop below half the firing threshold.
+        return not self._share_still_elevated(causal, latest_ts, locked_direction)
 
     def _replay_trigger_direction(
         self,

{detectkit-0.51.0 → detectkit-0.52.0}/detectkit/alerting/orchestrator/_types.py

@@ -23,7 +23,7 @@ def _parse_detection_metadata(metadata: Any) -> dict:
         return {}
     if isinstance(metadata, dict):
         return metadata
-    if isinstance(metadata, (bytes, bytearray)):
+    if isinstance(metadata, bytes | bytearray):
         try:
             metadata = metadata.decode("utf-8")
         except Exception:
@@ -64,11 +64,47 @@ class AlertConditions:
 
     Defaults mirror :class:`detectkit.config.metric_config.AlertConfig`
     so direct API users get the same behavior as YAML users.
+
+    ``window_points`` / ``min_anomaly_share`` carry the optional fraction rule
+    (``AlertConfig.anomaly_window`` resolved to grid points): fire when the
+    share of quorum-meeting points over the trailing window reaches the
+    threshold AND the latest point itself meets the quorum. OR-ed with the
+    consecutive rule; both unset (the default) leaves behavior unchanged.
     """
 
     min_detectors: int = 1
     direction: str = "same"  # "any", "same", "up", "down"
     consecutive_anomalies: int = 3
+    window_points: int | None = None
+    min_anomaly_share: float | None = None
+
+    @property
+    def lookback_points(self) -> int:
+        """Detection points the decision needs: the wider of the two rules."""
+        return max(self.consecutive_anomalies, self.window_points or 0)
+
+    @classmethod
+    def from_alert_config(cls, alert_config: Any, interval_seconds: int) -> AlertConditions:
+        """Build conditions from an ``AlertConfig``, resolving the window to points.
+
+        The single seam shared by the live alert step and the replay callers, so
+        the fraction-rule resolution (duration → grid points) can never drift
+        between them. ``getattr`` keeps duck-typed test stubs working.
+        """
+        from detectkit.core.interval import Interval
+
+        window_points: int | None = None
+        window = getattr(alert_config, "anomaly_window", None)
+        share = getattr(alert_config, "min_anomaly_share", None)
+        if window is not None and share is not None and interval_seconds > 0:
+            window_points = max(1, Interval(window).seconds // interval_seconds)
+        return cls(
+            min_detectors=alert_config.min_detectors,
+            direction=alert_config.direction,
+            consecutive_anomalies=alert_config.consecutive_anomalies,
+            window_points=window_points,
+            min_anomaly_share=share if window_points is not None else None,
+        )
 
 
 @dataclass