detectkit 0.53.3__tar.gz → 0.54.0__tar.gz

{detectkit-0.53.3/detectkit.egg-info → detectkit-0.54.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: detectkit
-Version: 0.53.3
+Version: 0.54.0
 Summary: Metric monitoring with automatic anomaly detection
 Author: detectkit team
 License: MIT

{detectkit-0.53.3 → detectkit-0.54.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.53.3"
+__version__ = "0.54.0"
 
 from detectkit.core.interval import Interval
 from detectkit.core.models import ColumnDefinition, TableModel

{detectkit-0.53.3 → detectkit-0.54.0}/detectkit/alerting/channels/base.py

@@ -121,6 +121,13 @@ class AlertData:
     window_matched: int | None = None
     min_anomaly_share: float | None = None
     fired_by_share: bool = False
+    # Data-maturity delay (``loading_delay``, resolved metric → project). Exposed
+    # to message templates as the OPT-IN ``{data_delay_display}`` /
+    # ``{data_delay_line}`` variables only — the default rendering deliberately
+    # does NOT show it, so existing alerts stay byte-identical. Lets a custom
+    # template disclose that every timestamp in the message deliberately trails
+    # wall-clock by the configured delay. ``None``/0 renders unchanged.
+    loading_delay_seconds: int | None = None
 
 
 def format_rule_display(
@@ -463,8 +470,10 @@ class BaseAlertChannel(ABC):
         # "Alert fired" — the on-grid moment the rule's consecutive threshold was
         # first met: onset + (consecutive_required - 1) * interval. Recovery
         # messages render it as the middle of the "anomaly began → alert fired →
-        # recovered" timeline so a stakeholder can tell the onset apart from when
-        # detectkit actually notified. Skipped when the run is capped (onset is
+        # recovered" timeline so a stakeholder can tell the onset apart from the
+        # moment the rule tripped. It is a data-grid instant, not a dispatch
+        # timestamp: with a ``loading_delay`` (and run cadence) the actual
+        # notification goes out later. Skipped when the run is capped (onset is
         # only a lower bound, so the fire time is unknown) or timing isn't wired
         # in (direct-API callers). The firing message doesn't show it: there it
         # coincides with the latest point the alert is firing on.
@@ -520,6 +529,20 @@ class BaseAlertChannel(ABC):
         synonyms = ", ".join(alert_data.ai_synonyms) if alert_data.ai_synonyms else ""
         synonyms_line = f"Also known as: {synonyms}\n" if synonyms else ""
 
+        # Data-maturity delay (``loading_delay``) — OPT-IN template variables
+        # only (``{data_delay_display}`` / ``{data_delay_line}``), same contract
+        # as ``{synonyms_line}``: the default templates never reference them, so
+        # every existing alert renders byte-identical. A custom template can
+        # disclose that the message's timestamps deliberately trail wall-clock.
+        delay_seconds = alert_data.loading_delay_seconds or 0
+        data_delay_display = format_duration(delay_seconds) if delay_seconds else ""
+        data_delay_line = (
+            f"Data maturity delay: {data_delay_display} "
+            "(timestamps intentionally trail real time)\n"
+            if delay_seconds
+            else ""
+        )
+
         # Format mentions
         mentions_str = self.format_mentions(alert_data.mentions)
         mentions_line = f"\n{mentions_str}" if mentions_str else ""
@@ -605,6 +628,8 @@ class BaseAlertChannel(ABC):
             "description_line": description_line,
             "synonyms": synonyms,
             "synonyms_line": synonyms_line,
+            "data_delay_display": data_delay_display,
+            "data_delay_line": data_delay_line,
             "dashboard_url": dashboard_url,
             "dashboard_line": dashboard_line,
             "help_url": help_url,

{detectkit-0.53.3 → detectkit-0.54.0}/detectkit/alerting/orchestrator/_base.py

@@ -37,6 +37,7 @@ class _OrchestratorBase:
         project_name: str | None = None,
         help_url: str | None = None,
         ai_synonyms: list[str] | None = None,
+        loading_delay_seconds: int = 0,
     ):
         self.metric_name = metric_name
         self.interval = interval
@@ -62,6 +63,12 @@ class _OrchestratorBase:
         # every AlertData so channels can render an "Also known as" identity line.
         # Empty list when the metric has no ai_context — renders unchanged.
         self.ai_synonyms = ai_synonyms or []
+        # Resolved data-maturity delay (``loading_delay``, metric → project → 0).
+        # Constructor state — not a per-call argument — so every internal
+        # ``get_last_complete_point()`` call site (the no-data check in the alert
+        # step AND the recovery mixin's own fetch bound) computes the same
+        # delay-aware boundary as the load step's maturity cut-off.
+        self.loading_delay_seconds = int(loading_delay_seconds or 0)
 
     @staticmethod
     def _group_by_timestamp(

{detectkit-0.53.3 → detectkit-0.54.0}/detectkit/alerting/orchestrator/_decision.py

@@ -410,6 +410,7 @@ class _DecisionMixin(_OrchestratorBase):
             min_anomaly_share=self.conditions.min_anomaly_share,
             window_matched=window_matched,
             fired_by_share=fired_by_share,
+            loading_delay_seconds=self.loading_delay_seconds or None,
         )
 
     def should_alert_no_data(
@@ -467,15 +468,29 @@ class _DecisionMixin(_OrchestratorBase):
             project_name=self.project_name,
             help_url=self.help_url,
             interval_seconds=self.interval.seconds,
+            loading_delay_seconds=self.loading_delay_seconds or None,
         )
 
     def get_last_complete_point(self, now: datetime | None = None) -> datetime:
-        """Floor ``now`` to the previous fully completed interval boundary."""
+        """Floor ``now`` to the previous fully completed *mature* interval boundary.
+
+        With a ``loading_delay`` configured, the loader only trusts
+        ``[t, t+interval)`` once ``now >= t + interval + delay`` — so the same
+        delay shifts the effective now back here BEFORE flooring, keeping the
+        no-data expectation (an exact-timestamp lookup) in lockstep with what
+        the load step has actually had a chance to persist. Without this, a
+        delayed metric would fire a false no-data alert on every run while the
+        newest interval is deliberately still in flight.
+        """
         if now is None:
             now = now_utc()
         now = to_aware_utc(now)
 
         interval_seconds = self.interval.seconds
-        floored = (int(now.timestamp()) // interval_seconds) * interval_seconds
+        # Shift the effective now back by the maturity delay BEFORE flooring
+        # (subtract-then-floor keeps the boundary correct for delays that
+        # aren't a multiple of the interval).
+        effective_epoch = int(now.timestamp()) - self.loading_delay_seconds
+        floored = (effective_epoch // interval_seconds) * interval_seconds
         last_complete = floored - interval_seconds
         return datetime.fromtimestamp(last_complete, tz=timezone.utc)

{detectkit-0.53.3 → detectkit-0.54.0}/detectkit/alerting/orchestrator/_recovery.py

@@ -234,6 +234,7 @@ class _RecoveryMixin(_OrchestratorBase):
             interval_seconds=self.interval.seconds,
             onset_timestamp=onset_ts,
             streak_capped=capped,
+            loading_delay_seconds=self.loading_delay_seconds or None,
         )
 
     def _resolve_incident(

{detectkit-0.53.3 → detectkit-0.54.0}/detectkit/cli/assets/claude/rules/alerting.md

@@ -169,7 +169,10 @@ interval) has no datapoint, or the row's value is `NULL`/`NaN`. `min_detectors`
 and `consecutive_anomalies` do **not** apply (it's a single binary signal).
 Honors `alert_cooldown` and `suppress_until`. Webhook channels render it amber.
 Use for cron loaders where source absence is a real failure; **don't** enable on
-naturally sparse metrics.
+naturally sparse metrics. With a `loading_delay` configured (`metrics.md`), the
+"last complete interval" shifts back by that same delay, so the deliberately
+withheld newest interval never trips a false no-data alert while it's still in
+flight upstream.
 
 ## Temporary suppression
 

{detectkit-0.53.3 → detectkit-0.54.0}/detectkit/cli/assets/claude/rules/cli.md

@@ -49,7 +49,10 @@ dtk run --select <sel> [--steps load,detect,alert] [--from DATE] [--to DATE] \
   query), `--steps detect` (rerun detection only), `--steps detect,alert` (skip load).
 - `--from DATE` / `--to DATE` — `YYYY-MM-DD` or `YYYY-MM-DD HH:MM:SS`, UTC.
   Affects only the `load` step. `--from` overrides the metric's
-  `loading_start_time`; `--to` defaults to now.
+  `loading_start_time`; `--to` defaults to now. An explicit `--to` bypasses a
+  configured `loading_delay` (trusted verbatim); to fix a bucket already
+  loaded before `loading_delay` was set, `dtk run --from <date before it>`
+  reloads and overwrites it.
 - `--full-refresh` — **destructive**: deletes the metric's datapoints and
   detections, then reloads from `loading_start_time`/`--from`. Use after
   changing the query or to recompute detections over history.

{detectkit-0.53.3 → detectkit-0.54.0}/detectkit/cli/assets/claude/rules/metrics.md

@@ -38,6 +38,7 @@ query_columns:                 # optional — map query columns to internal name
 
 loading_start_time: "2024-01-01 00:00:00"   # optional — initial load start (UTC)
 loading_batch_size: 2160       # optional — points per load batch
+loading_delay: "10min"         # optional — data-maturity delay (see below)
 
 seasonality_columns: [hour, day_of_week]    # optional — auto-extracted features
 
@@ -129,6 +130,16 @@ columns and bakes the best grouping into the tuned config (see `autotune.md`).
   saved timestamp and this is ignored.
 - `loading_batch_size` is the number of points loaded per batch (rule of thumb:
   7–30 days of points). E.g. 10-min interval → `2160` ≈ 15 days.
+- `loading_delay` (duration string or seconds) withholds the newest interval
+  until `now >= interval_end + loading_delay`, so a source that finishes
+  writing *after* the interval closes (a dbt model, say) never gets a
+  partial bucket persisted forever (load only resumes forward). The no-data
+  alert expectation shifts back in lockstep. Resolves **metric → project →
+  0** (`project.md`); `loading_delay: 0` on the metric opts out of a
+  project-wide default. Only affects the implicit "now" bound — an explicit
+  `--to` bypasses it. Trade-off: every second of delay adds the same to
+  real-outage detection time, and it reduces but doesn't eliminate the race
+  (repair a bucket that slipped through with `dtk run --from <date>`).
 
 ## Editing a metric that already has data
 

{detectkit-0.53.3 → detectkit-0.54.0}/detectkit/cli/assets/claude/rules/overview.md

@@ -103,9 +103,10 @@ series, watch the band recompute live, then write the config back into the metri
 
 For a **live**, project-wide view instead of a one-off file, run `dtk ui`: the
 same reports in a browser overlay plus an overview table (alert frequency,
-freshness, quality when incidents are labeled), a panel that drives
-`dtk run` / `dtk autotune` / `dtk unlock`, and an in-browser editor to create,
-edit and delete metric YAML files. See `cli.md`.
+freshness — netting out any configured `loading_delay` so a deliberately
+delayed metric doesn't read as stale — quality when incidents are labeled), a
+panel that drives `dtk run` / `dtk autotune` / `dtk unlock`, and an in-browser
+editor to create, edit and delete metric YAML files. See `cli.md`.
 
 ## Glossary
 

{detectkit-0.53.3 → detectkit-0.54.0}/detectkit/cli/assets/claude/rules/project.md

@@ -32,6 +32,7 @@ timeouts:                      # per-step, seconds
 
 alert_help_url: null           # optional, see below — "How to read this alert" link
 false_alert_budget: null       # optional — `dtk tune` target FDR (0,1]; per-metric override wins
+loading_delay: null            # optional — default data-maturity delay; per-metric override wins
 
 error_alerting:                # optional, see below
   enabled: false
@@ -42,6 +43,13 @@ error_alerting:                # optional, see below
 metric when its false-alert rate exceeds it. A per-metric `false_alert_budget`
 overrides it; unset → a built-in `0.5`. Tuning-only — it never touches the pipeline.
 
+`loading_delay` is a project-wide default **data-maturity delay** (duration string
+or seconds), useful when every metric reads from one upstream pipeline that
+finishes a few minutes after each interval closes. A per-metric `loading_delay`
+overrides it (`0` opts that metric out); see `metrics.md` for the full
+load/no-data behavior and the detection-latency trade-off. Only set this
+project-wide when your metrics genuinely share the same upstream schedule.
+
 ### `alert_help_url` — "How to read this alert" link
 
 Every default-rendered alert on every channel carries a `How to read this alert`

{detectkit-0.53.3 → detectkit-0.54.0}/detectkit/cli/assets/claude/skills/dtk-new-metric/SKILL.md

@@ -62,6 +62,12 @@ Use `{{ interval_seconds }}` if you need to bucket
 For long/complex SQL, offer to put it in `sql/<name>.sql` and use `query_file:`
 instead of inline `query:`.
 
+Also ask: **does this source finish writing after the interval closes** (a dbt
+model or other batch job that lands a few minutes late)? If so, set
+`loading_delay` (e.g. `"10min"`) so `dtk run` doesn't load and permanently
+persist a partially-written bucket right at the boundary — see `metrics.md`
+for the full behavior and its detection-latency trade-off.
+
 ## Step 3 — Interval
 
 Ask for the point spacing and set `interval` (`"1min"`, `"5min"`, `"10min"`,

{detectkit-0.53.3 → detectkit-0.54.0}/detectkit/cli/commands/autotune.py

@@ -275,6 +275,7 @@ def run_autotune(
             dry_run=dry_run,
             report_path=report_path,
             project_name=project_name,
+            project_loading_delay=getattr(_project_config, "loading_delay", None),
         )
         if ok:
             succeeded += 1
@@ -296,6 +297,7 @@ def _tune_one(
     dry_run: bool,
     report_path: str | None = None,
     project_name: str | None = None,
+    project_loading_delay: str | int | None = None,
 ) -> bool:
     """Tune one metric end to end; return True on success."""
     name = config.name
@@ -370,6 +372,7 @@ def _tune_one(
             config=config,
             report_path=report_path,
             project_name=project_name,
+            project_loading_delay=project_loading_delay,
         )
         internal_manager.release_lock(name, "pipeline", "pipeline", status="completed")
         return True
@@ -406,6 +409,7 @@ def _finalize(
     config: MetricConfig | None = None,
     report_path: str | None = None,
     project_name: str | None = None,
+    project_loading_delay: str | int | None = None,
 ) -> None:
     """Persist run + winner detections + tuned config, prune prior winners, render RESULT."""
     folds = " ".join(f"{f:.2f}" for f in result.cv_per_fold) or "—"
@@ -486,6 +490,7 @@ def _finalize(
                 end=end,
                 project_name=project_name,
                 generated_at=now_utc_naive().strftime("%Y-%m-%d %H:%M UTC"),
+                project_loading_delay=project_loading_delay,
             )
             if payload["points"]:
                 report_out = _resolve_report_path(report_path, project_root, out_path.stem)

{detectkit-0.53.3 → detectkit-0.54.0}/detectkit/cli/commands/run.py

@@ -245,6 +245,7 @@ def run_command(
                     internal_manager=internal_manager,
                     report_path=report_path,
                     project_name=getattr(project_config, "name", None),
+                    project_loading_delay=getattr(project_config, "loading_delay", None),
                     from_dt=from_dt,
                     to_dt=to_dt,
                 )
@@ -275,6 +276,7 @@ def emit_metric_report(
     project_name: str | None,
     from_dt: datetime | None,
     to_dt: datetime | None,
+    project_loading_delay: str | int | None = None,
 ) -> None:
     """Build and write the HTML report for one metric (best-effort)."""
     from detectkit.reporting import build_report_payload, render_report_html
@@ -287,6 +289,7 @@ def emit_metric_report(
         end=to_dt,
         project_name=project_name,
         generated_at=now_utc_naive().strftime("%Y-%m-%d %H:%M UTC"),
+        project_loading_delay=project_loading_delay,
     )
     if not payload["points"]:
         click.echo("  │ Report: no datapoints in window, skipped")

{detectkit-0.53.3 → detectkit-0.54.0}/detectkit/config/metric_config.py

@@ -4,6 +4,7 @@ Metric configuration models.
 Defines configuration structure for individual metrics loaded from YAML files.
 """
 
+import re
 from pathlib import Path
 from typing import Any
 
@@ -696,6 +697,23 @@ class MetricConfig(BaseModel):
         default_factory=list, description="Seasonality features to extract"
     )
     loading_batch_size: int = Field(default=10000, description="Batch size for loading")
+    # Data-maturity delay: how long after an interval closes the upstream source
+    # (e.g. a dbt model) needs before its data for that interval is complete.
+    # The loader treats [t, t+interval) as loadable only once
+    # now >= t + interval + loading_delay, and the no-data alert expectation
+    # shifts in lockstep — so a run scheduled right after the interval boundary
+    # never persists a partially-written bucket (which would otherwise stay
+    # wrong forever and skew trailing windows). Overrides the project-wide
+    # ``loading_delay``; an explicit 0 opts a metric out of the project default.
+    loading_delay: str | int | None = Field(
+        default=None,
+        description=(
+            "Data-maturity delay before the newest interval is trusted as "
+            "complete (duration string like '10min' or seconds). Use when the "
+            "upstream table finishes writing after the interval closes; "
+            "overrides the project-wide loading_delay, 0 opts out."
+        ),
+    )
     detectors: list[DetectorConfig] = Field(
         default_factory=list, description="Detector configurations"
     )
@@ -845,6 +863,12 @@ class MetricConfig(BaseModel):
 
         return v
 
+    @field_validator("loading_delay")
+    @classmethod
+    def validate_loading_delay(cls, v: str | int | None) -> str | int | None:
+        """A delay, if set, must parse as a duration (any zero form = opt out)."""
+        return validate_loading_delay_value(v)
+
     @field_validator("loading_batch_size")
     @classmethod
     def validate_batch_size(cls, v: int) -> int:
@@ -976,3 +1000,54 @@ class MetricConfig(BaseModel):
         data = unwrap_metric_mapping(data)
 
         return cls.model_validate(data)
+
+
+def loading_delay_to_seconds(value: str | int) -> int:
+    """Seconds for one ``loading_delay`` value.
+
+    Any zero-valued form — ``0``, ``"0"``, ``"0s"``, ``"0min"`` — means
+    "no delay" (the explicit opt-out from a project-wide default).
+    ``Interval`` itself rejects zero, so the zero forms are special-cased
+    before parsing; everything else must parse as a positive duration.
+    """
+    if isinstance(value, int):
+        return 0 if value == 0 else Interval(value).seconds
+    if re.fullmatch(r"0+\s*[A-Za-z]*", str(value).strip()):
+        return 0
+    return Interval(value).seconds
+
+
+def validate_loading_delay_value(v: str | int | None) -> str | int | None:
+    """Shared ``loading_delay`` field-validator body (MetricConfig + ProjectConfig).
+
+    One implementation so the accepted grammar and the error message can't
+    drift between the metric-level and project-level fields.
+    """
+    if v is None:
+        return v
+    try:
+        loading_delay_to_seconds(v)
+    except (ValueError, TypeError) as exc:
+        raise ValueError(
+            f"loading_delay must be a duration string ('10min', '1h') or "
+            f"seconds (0 opts out of a project-level delay): {exc}"
+        ) from exc
+    return v
+
+
+def resolve_loading_delay_seconds(
+    metric_delay: str | int | None, project_delay: str | int | None
+) -> int:
+    """Resolve the effective data-maturity delay: metric → project → 0.
+
+    The first configured value wins, so a per-metric ``loading_delay: 0``
+    (or ``"0"`` / ``"0min"``) explicitly opts that metric out of a
+    project-wide delay. Shared by the load step, the alert step (no-data
+    expectation), alert replay and the ``dtk ui`` overview so every consumer
+    agrees on the same maturity cut-off.
+    """
+    for value in (metric_delay, project_delay):
+        if value is None:
+            continue
+        return loading_delay_to_seconds(value)
+    return 0

{detectkit-0.53.3 → detectkit-0.54.0}/detectkit/config/project_config.py

@@ -210,6 +210,31 @@ class ProjectConfig(BaseModel):
             "`false_alert_budget` takes priority; unset → a built-in default."
         ),
     )
+    # Project-wide default data-maturity delay. Useful when every metric reads
+    # from the same upstream pipeline (e.g. one dbt project that finishes a few
+    # minutes after each interval closes). A per-metric ``loading_delay``
+    # overrides it; ``loading_delay: 0`` on a metric opts that metric out.
+    # Only sensible project-wide when the metrics genuinely share the upstream
+    # schedule — otherwise set it per metric.
+    loading_delay: str | int | None = Field(
+        default=None,
+        description=(
+            "Default data-maturity delay before the newest interval is trusted "
+            "as complete (duration string like '10min' or seconds). Per-metric "
+            "loading_delay overrides it; 0 on a metric opts out."
+        ),
+    )
+
+    @field_validator("loading_delay")
+    @classmethod
+    def validate_loading_delay(cls, v: "str | int | None") -> "str | int | None":
+        """A delay, if set, must parse as a duration (any zero form = no delay)."""
+        # Shared with MetricConfig.loading_delay so the accepted grammar and
+        # error message can't drift between the two levels. Imported lazily to
+        # keep this module import-light (no cycle exists either way).
+        from detectkit.config.metric_config import validate_loading_delay_value
+
+        return validate_loading_delay_value(v)
 
     @field_validator("false_alert_budget")
     @classmethod

{detectkit-0.53.3 → detectkit-0.54.0}/detectkit/orchestration/task_manager/_alert_step.py

@@ -29,6 +29,10 @@ class _AlertStepMixin(_TaskManagerBase):
 
         interval = config.get_interval()
         multi = len(active_configs) > 1
+        # Same maturity cut-off as the load step: the no-data expectation (and
+        # every other last-complete-point computation) must not run ahead of
+        # what load has had a chance to persist under a loading_delay.
+        loading_delay_seconds = self._loading_delay_seconds(config)
 
         for i, alerting_config in enumerate(active_configs):
             if multi:
@@ -70,6 +74,7 @@ class _AlertStepMixin(_TaskManagerBase):
                 links=alerting_config.links,
                 project_name=getattr(self.project_config, "name", None),
                 help_url=help_url,
+                loading_delay_seconds=loading_delay_seconds,
             )
 
             last_point = orchestrator.get_last_complete_point()

{detectkit-0.53.3 → detectkit-0.54.0}/detectkit/orchestration/task_manager/_base.py

@@ -7,6 +7,7 @@ from datetime import datetime
 from detectkit.alerting.channels.base import BaseAlertChannel
 from detectkit.alerting.channels.factory import AlertChannelFactory
 from detectkit.alerting.orchestrator import DetectionRecord, hydrate_detection_records
+from detectkit.config.metric_config import MetricConfig, resolve_loading_delay_seconds
 from detectkit.database.internal_tables import InternalTablesManager
 
 
@@ -28,6 +29,17 @@ class _TaskManagerBase:
         # per run. Abort propagation is signalled via result["abort_run"].
         self._error_alert_sent_in_run = False
 
+    def _loading_delay_seconds(self, config: MetricConfig) -> int:
+        """Effective data-maturity delay for *config* (metric → project → 0).
+
+        One resolution seam for the load step's end bound and the alert
+        step's no-data expectation, so the two can't drift apart.
+        """
+        return resolve_loading_delay_seconds(
+            config.loading_delay,
+            getattr(self.project_config, "loading_delay", None),
+        )
+
     def _load_recent_detections(
         self,
         metric_name: str,

{detectkit-0.53.3 → detectkit-0.54.0}/detectkit/orchestration/task_manager/_load_step.py

@@ -9,7 +9,7 @@ import click
 from detectkit.config.metric_config import MetricConfig
 from detectkit.loaders.metric_loader import MetricLoader
 from detectkit.orchestration.task_manager._base import _TaskManagerBase
-from detectkit.utils.datetime_utils import now_utc_naive, to_naive_utc
+from detectkit.utils.datetime_utils import format_duration, now_utc_naive, to_naive_utc
 
 
 class _LoadStepMixin(_TaskManagerBase):
@@ -57,7 +57,24 @@ class _LoadStepMixin(_TaskManagerBase):
                     "Please specify from_date or set loading_start_time in config."
                 )
 
-        actual_to = to_naive_utc(actual_to) if actual_to is not None else now_utc_naive()
+        if actual_to is not None:
+            actual_to = to_naive_utc(actual_to)
+        else:
+            # Data-maturity delay (loading_delay): shift the effective "now"
+            # back BEFORE the interval snap below, so [t, t+I) is only loaded
+            # once now >= t + I + delay — a bucket the upstream ETL is still
+            # writing is withheld instead of being persisted half-full forever
+            # (resume never re-reads it). Subtract-then-snap is what keeps the
+            # boundary on the metric's grid for delays that aren't a multiple
+            # of the interval; snapping first and subtracting after would land
+            # off-grid. An explicit --to is trusted verbatim (no delay).
+            delay_seconds = self._loading_delay_seconds(config)
+            actual_to = now_utc_naive() - timedelta(seconds=delay_seconds)
+            if delay_seconds:
+                click.echo(
+                    f"  │ Holding back {format_duration(delay_seconds)} "
+                    "for data maturity (loading_delay)"
+                )
         actual_from = to_naive_utc(actual_from)
 
         if actual_from >= actual_to:

{detectkit-0.53.3 → detectkit-0.54.0}/detectkit/reporting/builder.py

@@ -24,7 +24,7 @@ from detectkit.alerting.orchestrator._types import (
     _direction_from_metadata,
     _parse_detection_metadata,
 )
-from detectkit.config.metric_config import MetricConfig
+from detectkit.config.metric_config import MetricConfig, resolve_loading_delay_seconds
 from detectkit.database.internal_tables import InternalTablesManager
 from detectkit.orchestration.task_manager import make_alert_config_id
 from detectkit.utils.datetime_utils import to_naive_utc
@@ -226,6 +226,7 @@ def replay_alert_events(
     start: datetime,
     end: datetime,
     project_name: str | None,
+    loading_delay_seconds: int = 0,
 ) -> list[tuple[str, ReplayedEvent]]:
     """Replay every *enabled* alerting config over ``[start, end]``.
 
@@ -263,6 +264,9 @@ def replay_alert_events(
             links=cfg.links,
             project_name=project_name,
             help_url=None,
+            # Constructor parity with the live path: replayed AlertData carries
+            # the same resolved data-maturity delay the dispatching run stamps.
+            loading_delay_seconds=loading_delay_seconds,
         )
         for event in orchestrator.replay(records, value_at, start, end):
             out.append((config_id, event))
@@ -305,11 +309,14 @@ def build_report_payload(
     end: datetime | None = None,
     project_name: str | None = None,
     generated_at: str | None = None,
+    project_loading_delay: str | int | None = None,
 ) -> dict:
     """Read the internal tables for one metric and assemble the report payload.
 
     ``start`` / ``end`` bound the report window (inclusive of both grid points);
-    when omitted they default via :func:`resolve_window`.
+    when omitted they default via :func:`resolve_window`. ``project_loading_delay``
+    is the project-wide ``loading_delay`` fallback, so replayed alerts carry the
+    same resolved data-maturity delay the live pipeline stamps.
     """
     name = metric_config.name
     interval = metric_config.get_interval()
@@ -418,7 +425,16 @@ def build_report_payload(
     alerts: list[dict] = [
         _event_to_payload(event, config_id)
         for config_id, event in replay_alert_events(
-            metric_config, internal, records, value_at, start, end, project_name
+            metric_config,
+            internal,
+            records,
+            value_at,
+            start,
+            end,
+            project_name,
+            loading_delay_seconds=resolve_loading_delay_seconds(
+                metric_config.loading_delay, project_loading_delay
+            ),
         )
     ]
     alerts.sort(key=lambda a: a["t"])