nlalpha-performance 0.6.0__py3-none-any.whl

nlalpha_performance/__init__.py

@@ -0,0 +1,55 @@
+"""Register the performance analytics provider through capability entry points."""
+
+from importlib.metadata import version as _distribution_version
+
+from nlalpha.core.capabilities.manifest import ProviderManifest
+from nlalpha.core.capabilities.plugin.protocol import BaseCapabilityPlugin
+
+
+class PerformancePlugin(BaseCapabilityPlugin):
+    """Expose the performance analytics capability provider."""
+
+    plugin_name = "nlalpha_performance"
+    plugin_version = _distribution_version("nlalpha_performance")
+
+
+    def __init__(self) -> None:
+        self._provider = None
+
+    def is_available(self) -> bool:
+        """Check whether the empyrical dependency is installed."""
+        try:
+            __import__("empyrical")
+            return True
+        except ImportError:
+            return False
+
+    def get_provider(self):
+        """Return the cached performance analytics provider."""
+        if self._provider is None:
+            from .provider import PerformanceProvider
+            self._provider = PerformanceProvider()
+        return self._provider
+
+    def get_manifest(self) -> dict:
+        """Return the provider runtime manifest."""
+        if self.is_available():
+            provider = self.get_provider()
+            manifest = provider.manifest().to_dict()
+            manifest["domains"] = ["performance"]
+            return manifest
+        return ProviderManifest(
+            provider_id="performance",
+            provider_name="PerformancePlugin",
+            available=False,
+            unavailable_reason="empyrical-reloaded not installed",
+            domains=["performance"],
+        ).to_dict()
+
+    def get_helpers(self) -> list[dict]:
+        """Return the capability helper declarations."""
+        return []
+
+    def get_prompt_path(self) -> str | None:
+        """Return the optional capability prompt path."""
+        return None

nlalpha_performance/basic_statistics.py

@@ -0,0 +1,222 @@
+"""Calculate basic annualized statistics from net account equity moments."""
+
+import math
+from numbers import Real
+
+from nlalpha.core.errors import StrategyRuntimeError
+
+
+def _error(field: str, message: str) -> StrategyRuntimeError:
+    """Create a statistics input error."""
+    return StrategyRuntimeError(
+        message, details={"reason": "invalid_statistics_input", "field": field}
+    )
+
+
+def _finite_number(value: object, field: str) -> float:
+    """Validate a finite real number."""
+    if isinstance(value, bool) or not isinstance(value, Real):
+        raise _error(field, f"{field} must be a finite number")
+    try:
+        number = float(value)
+    except (OverflowError, ValueError) as exc:
+        raise _error(field, f"{field} must be a finite number") from exc
+    if not math.isfinite(number):
+        raise _error(field, f"{field} must be a finite number")
+    return number
+
+
+def _positive_annualization(value: object) -> int:
+    """Validate an explicit observations-per-year count."""
+    if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
+        raise _error("annualization", "annualization must be a positive integer")
+    return value
+
+
+def _risk_free_rate(value: object) -> float:
+    """Validate an annual risk-free rate."""
+    rate = _finite_number(value, "risk_free_rate")
+    if rate <= -1.0:
+        raise _error("risk_free_rate", "risk_free_rate must be greater than -1")
+    return rate
+
+
+def validate_statistics_settings(execution: dict) -> dict:
+    """Validate explicit annualization and annual risk-free execution settings."""
+    if not isinstance(execution, dict):
+        raise _error("execution", "execution must be a dictionary")
+    annualization = None
+    if "annualization" in execution:
+        annualization = _positive_annualization(execution["annualization"])
+    configured_rate = "risk_free_rate" in execution
+    return {
+        "annualization": annualization,
+        "annualization_source": "configured" if annualization is not None else "not_provided",
+        "risk_free_rate": _risk_free_rate(execution["risk_free_rate"]) if configured_rate else 0.0,
+        "risk_free_rate_source": "configured" if configured_rate else "engine_default",
+    }
+
+
+def _validated_settings(settings: dict) -> dict:
+    """Validate normalized settings and their source labels."""
+    if not isinstance(settings, dict):
+        raise _error("settings", "settings must be a dictionary")
+    for field in ("annualization", "annualization_source", "risk_free_rate", "risk_free_rate_source"):
+        if field not in settings:
+            raise _error(field, f"normalized settings must include {field}")
+    annualization = settings["annualization"]
+    if annualization is not None:
+        annualization = _positive_annualization(annualization)
+    annualization_source = settings["annualization_source"]
+    expected_source = "configured" if annualization is not None else "not_provided"
+    if annualization_source != expected_source:
+        raise _error("annualization_source", "annualization_source must match annualization")
+    rate = _risk_free_rate(settings["risk_free_rate"])
+    rate_source = settings["risk_free_rate_source"]
+    if rate_source not in ("configured", "engine_default"):
+        raise _error("risk_free_rate_source", "risk_free_rate_source is invalid")
+    if rate_source == "engine_default" and rate != 0.0:
+        raise _error("risk_free_rate_source", "the engine default risk-free rate must be zero")
+    return {
+        "annualization": annualization,
+        "annualization_source": annualization_source,
+        "risk_free_rate": rate,
+        "risk_free_rate_source": rate_source,
+    }
+
+
+class ReturnMoments:
+    """Accumulate simple return moments from successive net equity observations."""
+
+    def __init__(self, initial_equity: float):
+        self._previous_equity = _finite_number(initial_equity, "initial_equity")
+        self.count = 0
+        self.mean = 0.0
+        self.m2 = 0.0
+        self.invalid_reason = "non_positive_equity" if self._previous_equity <= 0 else None
+
+    def observe(self, equity: float) -> None:
+        """Observe one account equity and retain only finite return moments."""
+        current_equity = _finite_number(equity, "equity")
+        if self.invalid_reason is not None:
+            return
+        if current_equity <= 0:
+            self.invalid_reason = "non_positive_equity"
+            return
+        period_return = current_equity / self._previous_equity - 1.0
+        count = self.count + 1
+        delta = period_return - self.mean
+        mean = self.mean + delta / count
+        m2 = self.m2 + delta * (period_return - mean)
+        if not all(math.isfinite(value) for value in (period_return, mean, m2)):
+            self.invalid_reason = "numerical_overflow"
+            return
+        if m2 < 0:
+            raise _error("return_m2", "return_m2 must be non-negative")
+        self.count = count
+        self.mean = mean
+        self.m2 = m2
+        self._previous_equity = current_equity
+
+
+def calculate_basic_statistics(
+    *,
+    initial_equity: float,
+    final_equity: float,
+    return_count: int,
+    return_mean: float,
+    return_m2: float,
+    settings: dict,
+    invalid_reason: str | None = None,
+) -> dict:
+    """Calculate observation-based annual return, sample annual volatility, and Sharpe."""
+    initial = _finite_number(initial_equity, "initial_equity")
+    final = _finite_number(final_equity, "final_equity")
+    mean = _finite_number(return_mean, "return_mean")
+    m2 = _finite_number(return_m2, "return_m2")
+    if isinstance(return_count, bool) or not isinstance(return_count, int) or return_count < 0:
+        raise _error("return_count", "return_count must be a non-negative integer")
+    if m2 < 0:
+        raise _error("return_m2", "return_m2 must be non-negative")
+    if invalid_reason is not None and (not isinstance(invalid_reason, str) or not invalid_reason):
+        raise _error("invalid_reason", "invalid_reason must be a non-empty string or None")
+    normalized = _validated_settings(settings)
+    annualization = normalized["annualization"]
+    rate = normalized["risk_free_rate"]
+    period_rate = None
+    if annualization is not None:
+        try:
+            period_rate = math.expm1(math.log1p(rate) / annualization)
+        except OverflowError:
+            pass
+    values = {"annual_return": None, "annual_volatility": None, "sharpe_ratio": None}
+    unavailable = {}
+    diagnostics = {
+        "return_count": return_count,
+        "annualization": annualization,
+        "annualization_source": normalized["annualization_source"],
+        "annual_risk_free_rate": rate,
+        "risk_free_rate_source": normalized["risk_free_rate_source"],
+        "period_risk_free_rate": period_rate,
+        "variance_ddof": 1,
+        "returns_basis": "net_account_equity_simple_returns",
+        "annualization_basis": "observations_per_year_no_calendar_resampling",
+        "unavailable": unavailable,
+    }
+    reason = invalid_reason
+    if reason is None and (initial <= 0 or final <= 0):
+        reason = "non_positive_equity"
+    if reason is None and annualization is None:
+        reason = "annualization_not_provided"
+    if reason is None and return_count == 0:
+        reason = "insufficient_observations"
+    if reason is not None:
+        unavailable.update({metric: reason for metric in values})
+    else:
+        try:
+            annual_return = math.expm1(
+                (math.log(final) - math.log(initial)) * annualization / return_count
+            )
+            if math.isfinite(annual_return):
+                values["annual_return"] = annual_return
+            else:
+                unavailable["annual_return"] = "numerical_overflow"
+        except OverflowError:
+            unavailable["annual_return"] = "numerical_overflow"
+        if return_count < 2:
+            unavailable.update({
+                metric: "insufficient_observations"
+                for metric in ("annual_volatility", "sharpe_ratio")
+            })
+        elif m2 == 0:
+            values["annual_volatility"] = 0.0
+            unavailable["sharpe_ratio"] = "zero_volatility"
+        else:
+            try:
+                deviation = math.sqrt(m2 / (return_count - 1))
+                annual_factor = math.sqrt(annualization)
+                volatility = deviation * annual_factor
+                if math.isfinite(volatility):
+                    values["annual_volatility"] = volatility
+                else:
+                    unavailable["annual_volatility"] = "numerical_overflow"
+                if deviation == 0:
+                    unavailable["sharpe_ratio"] = "zero_volatility"
+                elif period_rate is None:
+                    unavailable["sharpe_ratio"] = "numerical_overflow"
+                else:
+                    sharpe = (mean - period_rate) / deviation * annual_factor
+                    if math.isfinite(sharpe):
+                        values["sharpe_ratio"] = sharpe
+                    else:
+                        unavailable["sharpe_ratio"] = "numerical_overflow"
+            except OverflowError:
+                unavailable.update({
+                    metric: "numerical_overflow"
+                    for metric in ("annual_volatility", "sharpe_ratio")
+                })
+    return {
+        "performance": {"annual_return": values["annual_return"]},
+        "risk": {metric: values[metric] for metric in ("annual_volatility", "sharpe_ratio")},
+        "diagnostics": diagnostics,
+    }

nlalpha_performance/drawdowns.py

@@ -0,0 +1,307 @@
+"""Track drawdown episodes from completed-close net account equity observations."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+from nlalpha.core.telemetry import get_meter, start_span
+
+from .basic_statistics import _error, _finite_number
+
+
+DRAWDOWN_COLUMNS = [
+    "episode_id", "status", "peak_equity", "peak_timestamp_ns", "peak_observation_index",
+    "peak_is_initial", "start_timestamp_ns", "start_observation_index", "trough_equity",
+    "trough_timestamp_ns", "trough_observation_index", "recovery_equity", "recovery_timestamp_ns",
+    "recovery_observation_index", "end_timestamp_ns", "end_observation_index", "depth",
+    "decline_duration_ns", "recovery_duration_ns", "duration_ns", "observed_duration_ns",
+    "duration_is_lower_bound", "decline_observations", "recovery_observations", "duration_observations",
+]
+_SUMMARY_FIELDS = {
+    "episode_count", "recovered_episode_count", "unrecovered_episode_count", "deepest", "longest", "current",
+}
+_evidence_counter = get_meter().create_counter(
+    "nlalpha.empyrical.drawdown_evidence", description="Drawdown evidence envelopes built"
+)
+
+
+def _integer(value: object, field: str, *, nullable: bool = False) -> int | None:
+    """Validate exact integer timestamps and counts."""
+    if nullable and value is None:
+        return None
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise _error(field, f"{field} must be an integer")
+    return value
+
+
+@dataclass
+class _Episode:
+    """Maintain one peak-to-recovery or peak-to-sample-end drawdown."""
+
+    episode_id: int
+    peak_equity: float
+    peak_timestamp_ns: int | None
+    peak_observation_index: int
+    start_timestamp_ns: int
+    start_observation_index: int
+    trough_equity: float
+    trough_timestamp_ns: int
+    trough_observation_index: int
+    end_timestamp_ns: int
+    end_observation_index: int
+    depth: float
+    recovery_equity: float | None = None
+    recovery_timestamp_ns: int | None = None
+    recovery_observation_index: int | None = None
+
+    @property
+    def observed_duration_ns(self) -> int:
+        """Return the known elapsed duration for this episode."""
+        start = self.start_timestamp_ns if self.peak_timestamp_ns is None else self.peak_timestamp_ns
+        return self.end_timestamp_ns - start
+
+    @property
+    def duration_observations(self) -> int:
+        """Return the number of observation intervals since its reference peak."""
+        return self.end_observation_index - self.peak_observation_index
+
+    def row(self) -> dict:
+        """Materialize one episode using exact observation timestamps and indices."""
+        initial = self.peak_timestamp_ns is None
+        recovered = self.recovery_timestamp_ns is not None
+        return {
+            "episode_id": self.episode_id,
+            "status": "recovered" if recovered else "unrecovered",
+            "peak_equity": self.peak_equity,
+            "peak_timestamp_ns": self.peak_timestamp_ns,
+            "peak_observation_index": self.peak_observation_index,
+            "peak_is_initial": initial,
+            "start_timestamp_ns": self.start_timestamp_ns,
+            "start_observation_index": self.start_observation_index,
+            "trough_equity": self.trough_equity,
+            "trough_timestamp_ns": self.trough_timestamp_ns,
+            "trough_observation_index": self.trough_observation_index,
+            "recovery_equity": self.recovery_equity,
+            "recovery_timestamp_ns": self.recovery_timestamp_ns,
+            "recovery_observation_index": self.recovery_observation_index,
+            "end_timestamp_ns": self.end_timestamp_ns,
+            "end_observation_index": self.end_observation_index,
+            "depth": self.depth,
+            "decline_duration_ns": None if initial else self.trough_timestamp_ns - self.peak_timestamp_ns,
+            "recovery_duration_ns": self.recovery_timestamp_ns - self.trough_timestamp_ns if recovered else None,
+            "duration_ns": None if initial else self.end_timestamp_ns - self.peak_timestamp_ns,
+            "observed_duration_ns": self.observed_duration_ns,
+            "duration_is_lower_bound": initial,
+            "decline_observations": self.trough_observation_index - self.peak_observation_index,
+            "recovery_observations": self.recovery_observation_index - self.trough_observation_index if recovered else None,
+            "duration_observations": self.duration_observations,
+        }
+
+
+def _longer(candidate: _Episode, previous: _Episode | None) -> bool:
+    """Select the longest observed duration with deterministic tie rules."""
+    return previous is None or (
+        candidate.observed_duration_ns, candidate.duration_observations, -candidate.episode_id
+    ) > (
+        previous.observed_duration_ns, previous.duration_observations, -previous.episode_id
+    )
+
+
+class DrawdownTracker:
+    """Track peaks, troughs and recoveries while retaining bounded summary state."""
+
+    def __init__(self, initial_equity: float, *, record_history: bool = True):
+        self._peak_equity = _finite_number(initial_equity, "initial_equity")
+        if self._peak_equity <= 0:
+            raise _error("initial_equity", "initial_equity must be greater than zero")
+        if not isinstance(record_history, bool):
+            raise _error("record_history", "record_history must be a boolean")
+        self._peak_timestamp_ns = None
+        self._peak_observation_index = 0
+        self._observation_count = 0
+        self._last_timestamp_ns = None
+        self._episode_count = 0
+        self._recovered_count = 0
+        self._current = None
+        self._deepest = None
+        self._longest_recovered = None
+        self._history = [] if record_history else None
+
+    def observe(self, timestamp_ns: int, equity: float) -> None:
+        """Observe one strictly ordered completed-close equity value."""
+        timestamp = _integer(timestamp_ns, "timestamp_ns")
+        if self._last_timestamp_ns is not None and timestamp <= self._last_timestamp_ns:
+            raise _error("timestamp_ns", "observation timestamps must be strictly increasing")
+        equity = _finite_number(equity, "equity")
+        underwater = equity < self._peak_equity
+        depth = 0.0
+        if underwater:
+            depth = 1.0 - equity / self._peak_equity if equity < 0 else (self._peak_equity - equity) / self._peak_equity
+        if not math.isfinite(depth):
+            raise _error("depth", "drawdown depth must be finite")
+        index = self._observation_count + 1
+        if underwater:
+            if self._current is None:
+                self._episode_count += 1
+                self._current = _Episode(
+                    self._episode_count, self._peak_equity, self._peak_timestamp_ns,
+                    self._peak_observation_index, timestamp, index, equity, timestamp, index,
+                    timestamp, index, depth,
+                )
+            else:
+                self._current.end_timestamp_ns = timestamp
+                self._current.end_observation_index = index
+                if equity < self._current.trough_equity:
+                    self._current.trough_equity = equity
+                    self._current.trough_timestamp_ns = timestamp
+                    self._current.trough_observation_index = index
+                    self._current.depth = depth
+            if self._deepest is None or self._current.depth > self._deepest.depth:
+                self._deepest = self._current
+        else:
+            if self._current is not None:
+                self._current.end_timestamp_ns = timestamp
+                self._current.end_observation_index = index
+                self._current.recovery_equity = equity
+                self._current.recovery_timestamp_ns = timestamp
+                self._current.recovery_observation_index = index
+                self._recovered_count += 1
+                if _longer(self._current, self._longest_recovered):
+                    self._longest_recovered = self._current
+                if self._history is not None:
+                    self._history.append(self._current)
+                self._current = None
+            self._peak_equity = equity
+            self._peak_timestamp_ns = timestamp
+            self._peak_observation_index = index
+        self._observation_count = index
+        self._last_timestamp_ns = timestamp
+
+    def finish(self) -> tuple[dict, list[dict]]:
+        """Return an independent summary and recorded rows without mutating tracker state."""
+        longest = self._longest_recovered
+        if self._current is not None and _longer(self._current, longest):
+            longest = self._current
+        summary = {
+            "episode_count": self._episode_count,
+            "recovered_episode_count": self._recovered_count,
+            "unrecovered_episode_count": int(self._current is not None),
+            "deepest": self._deepest.row() if self._deepest is not None else None,
+            "longest": longest.row() if longest is not None else None,
+            "current": self._current.row() if self._current is not None else None,
+        }
+        rows = []
+        if self._history is not None:
+            rows = [episode.row() for episode in self._history]
+            if self._current is not None:
+                rows.append(self._current.row())
+        return summary, rows
+
+
+def build_drawdown_evidence(
+    *,
+    summary: dict,
+    rows: list[dict],
+    record_mode: str,
+    source: str,
+    schema_id: str,
+    observation_count: int,
+    first_observation_timestamp_ns: int | None,
+    last_observation_timestamp_ns: int | None,
+    initial_reference_timestamp_ns: int | None,
+) -> tuple[dict, dict]:
+    """Build a drawdown report envelope and explain its sampling and unavailable values."""
+    if not isinstance(summary, dict) or set(summary) != _SUMMARY_FIELDS:
+        raise _error("summary", "drawdown summary must contain the declared summary fields")
+    if not isinstance(rows, list):
+        raise _error("rows", "drawdown rows must be a list")
+    if not isinstance(record_mode, str) or record_mode not in {"full", "summary"}:
+        raise _error("record_mode", "record_mode must be full or summary")
+    for field, value in (("source", source), ("schema_id", schema_id)):
+        if not isinstance(value, str) or not value or value != value.strip():
+            raise _error(field, f"{field} must be a non-empty trimmed string")
+    count = _integer(observation_count, "observation_count")
+    first = _integer(first_observation_timestamp_ns, "first_observation_timestamp_ns", nullable=True)
+    last = _integer(last_observation_timestamp_ns, "last_observation_timestamp_ns", nullable=True)
+    reference = _integer(initial_reference_timestamp_ns, "initial_reference_timestamp_ns", nullable=True)
+    if count < 0:
+        raise _error("observation_count", "observation_count must be non-negative")
+    if count == 0 and (first is not None or last is not None):
+        raise _error("observation_count", "empty observations require null observation timestamps")
+    if count > 0 and (first is None or last is None or first > last or (count == 1 and first != last) or (count > 1 and first == last)):
+        raise _error("observation_timestamps", "observation count must agree with ordered timestamp bounds")
+    for field in ("episode_count", "recovered_episode_count", "unrecovered_episode_count"):
+        if _integer(summary[field], field) < 0:
+            raise _error(field, f"{field} must be non-negative")
+    episodes = summary["episode_count"]
+    unrecovered = summary["unrecovered_episode_count"]
+    if episodes != summary["recovered_episode_count"] + unrecovered or unrecovered > 1 or episodes > count:
+        raise _error("summary", "drawdown episode counts are inconsistent")
+    for field in ("deepest", "longest", "current"):
+        row = summary[field]
+        expected = bool(unrecovered) if field == "current" else bool(episodes)
+        if expected != (row is not None) or (row is not None and (not isinstance(row, dict) or set(row) != set(DRAWDOWN_COLUMNS))):
+            raise _error(field, f"{field} must agree with episode counts and declared row fields")
+    if record_mode == "summary" and rows:
+        raise _error("rows", "summary mode must not contain recorded drawdown rows")
+    if record_mode == "full" and len(rows) != episodes:
+        raise _error("rows", "recorded drawdown row count must match episode_count")
+    unavailable = {key: "no_equity_observations" for key in ("max_drawdown", "drawdowns")} if count == 0 else {}
+    with start_span("empyrical.build_drawdown_evidence", attributes={"observation_count": count, "episode_count": episodes}):
+        diagnostics = {
+            "sampling": "completed_bar_close_net_equity",
+            "fee_treatment": "already_reflected_in_net_equity",
+            "timestamp_unit": "ns",
+            "timestamp_timezone": "UTC",
+            "timestamp_columns": [field for field in DRAWDOWN_COLUMNS if field.endswith("timestamp_ns")],
+            "depth_unit": "proportion",
+            "depth_definition": "(peak_equity-trough_equity)/peak_equity",
+            "peak_rule": "most_recent_greater_or_equal_equity",
+            "trough_rule": "earliest_equal_trough_only_strictly_lower_equity_updates",
+            "episode_start_rule": "first_equity_strictly_below_high_water_mark",
+            "recovery_rule": "first_observation_greater_or_equal_episode_peak_equity",
+            "deepest_selection": "largest_depth_then_earlier_episode_id",
+            "longest_selection": "largest_observed_duration_ns_then_duration_observations_then_earlier_episode_id",
+            "longest_duration_basis": "observed_duration_not_unknown_total_duration",
+            "initial_peak_duration_rule": "unknown_total_duration_observed_duration_is_lower_bound_from_first_underwater_observation",
+            "observed_peak_duration_rule": "duration_from_observed_peak_to_recovery_or_sample_end",
+            "observation_interval_rule": "index_difference_initial_reference_to_first_observation_counts_as_one_interval",
+            "initial_reference_timestamp_role": "informational_only_not_a_duration_endpoint",
+            "nullable_field_reasons": {
+                "peak_timestamp_ns": "initial_capital_has_no_economic_timestamp",
+                "decline_duration_ns": "initial_peak_has_unknown_economic_start",
+                "duration_ns": "initial_peak_has_unknown_economic_start",
+                "recovery_equity": "episode_unrecovered_at_sample_end",
+                "recovery_timestamp_ns": "episode_unrecovered_at_sample_end",
+                "recovery_observation_index": "episode_unrecovered_at_sample_end",
+                "recovery_duration_ns": "episode_unrecovered_at_sample_end",
+                "recovery_observations": "episode_unrecovered_at_sample_end",
+                "initial_reference_timestamp_ns": "reference_timestamp_not_provided",
+                "first_observation_timestamp_ns": "no_equity_observations",
+                "last_observation_timestamp_ns": "no_equity_observations",
+                "deepest": "no_drawdown_episodes_or_no_equity_observations",
+                "longest": "no_drawdown_episodes_or_no_equity_observations",
+                "current": "no_active_drawdown_episode",
+            },
+            "observation_count": count,
+            "first_observation_timestamp_ns": first,
+            "last_observation_timestamp_ns": last,
+            "initial_reference_timestamp_ns": reference,
+            "record_mode": record_mode,
+            "unavailable": unavailable,
+        }
+        status = "unavailable" if count == 0 else ("available" if record_mode == "full" else "not_recorded")
+        reason = "no_equity_observations" if count == 0 else (None if record_mode == "full" else "record_mode_summary")
+        report = {
+            "schema_id": schema_id,
+            "source": source,
+            "status": status,
+            "reason": reason,
+            "row_count": None if count == 0 else episodes,
+            "columns": list(DRAWDOWN_COLUMNS),
+            "rows": rows,
+            "metadata": dict(diagnostics),
+        }
+        _evidence_counter.add(1, {"source": source, "record_mode": record_mode})
+        return report, diagnostics