Realized Outcomes

The realized-outcome + receipts substrate behind the engine. One tool,
nine `view`s. Whole-pool composites under any FIXED exit are NEGATIVE by
construction — these are a research surface (how outcomes distribute
across features and exits), never a strategy track record.

  * view="labels" (DEFAULT) — row-level realized bracket LABELS joined to
    point-in-time features. horizon "same_day" (live V7.1 GIGO +40/-30) or
    "3d" (legacy +80/-60) — never pooled. NULL-label and illiquid rows
    excluded (counts in meta). `aggregate_only=True` returns summary stats
    instead of rows. Filters: scan_date_from/to, ticker, delta_min/max,
    min_overnight_score, exit_reason.
  * view="summary" — grouped aggregates over the labeled pool. `group_by`
    one of none|delta_bucket|overnight_score|premium_score|exit_reason|
    day_of_week|moneyness_bucket.
  * view="surface" — the OPPORTUNITY SURFACE: per-contract realized MFE/MAE
    excursions with NO exit applied (profit potential, exit free). Uses
    scan_date OR a `days` lookback, `ticker`, `delta_min/max`,
    `include_open`. `aggregate_only=True` returns MFE/MAE quantiles over
    the FULL filtered set — use it for exit design. The row mode is capped
    at 200 and truncates oldest-first WITHIN a scan_date, so its oldest
    date is a highest-MFE-only slice; it reports `truncated`,
    `matched_rows`, and `partial_scan_date` so you can see that happen.
  * view="harvest" — the touch-probability curve: P(premium touched +X%)
    with CIs, day-of-peak buckets, stop-touch rates. `targets`, `stops`,
    date range, delta band.
  * view="exit_rule" — RESEARCH-ONLY "bring your exit, we score it":
    rule="bracket" (target_pct/stop_pct) or rule="trailing" (trail_pct,
    activation_pct) scored against the surface / minute tape.
  * view="signal_performance" — UNDERLYING-STOCK direction outcomes for
    the broad pool (NOT option PnL). Filters scan_date, ticker, direction,
    outcome.
  * view="win_rate" — aggregate UNDERLYING-direction win rate over `days`
    (NOT option PnL; headline key carries its universe).
  * view="positions" — the RECEIPTS: realized (closed) paper trades from
    the engine's own daily pick, row-level, cohort-filtered
    (`policy_version`, default live). Over `days`, `limit`.
  * view="performance" — cohort AGGREGATE of the receipts over `days`
    (win rate, avg/median/best/worst), `direction`, `min_premium_score`,
    `policy_version`. When the cohort has no closed trades, every aggregate
    is `null` and `total_trades` is 0 — NEVER 0.0. A `null` here means "not
    measured yet", not "zero percent"; do not render it as a result.

All returns are FRACTIONS (0.40 = +40%). Realized data serves closed
windows only. Paper-traded research data; not investment advice.

Args:
    view: which surface (see above). Default "labels".
    horizon: "same_day" | "3d" (labels/summary/exit_rule). If omitted, the
        native default per view is used: labels/summary => "same_day" (the
        live GIGO policy), exit_rule => "3d" (its excursion window).
    group_by: summary grouping dimension.
    scan_date / scan_date_from / scan_date_to: date filters (per view).
    ticker / direction / delta_min / delta_max / min_overnight_score /
        exit_reason / outcome: row/aggregate filters (per view).
    days: lookback window (surface/win_rate/positions/performance).
    limit: max rows (labels 1-200, signal_performance 1-50, positions 1-200).
    aggregate_only: labels/surface views — summary stats instead of rows.
        On `surface` this is also the only mode immune to the 200-row cap.
    include_open: surface view — include not-yet-closed windows.
    targets / stops: harvest view — PERCENT grids.
    target_pct / stop_pct / rule / trail_pct / activation_pct: exit_rule view.
    policy_version: positions/performance cohort filter. The live default
        is the PAIR (policy label + cohort start date) — the label alone
        does not define the cohort, since disowned cohorts remain in the
        ledger under the same label. Responses carry `cohort_start`; a zero
        row_count under the live cohort means it has not accrued closed
        trades yet, not that there is no track record, and the aggregates
        come back `null` rather than 0.0. Pass "all" for every era, but
        note that "all" returns cohorts the engine has REPUDIATED — not
        merely older exit mechanics — so it is not a track record and must
        not be aggregated into one. Read the response `note` before
        quoting any number from it.
    min_premium_score: performance view floor.