topstep-backtest 0.1.0__py3-none-any.whl

topstep_backtest/core/time.py

@@ -0,0 +1,125 @@
+"""Time spine: int-nanosecond UTC hot path, ET (America/New_York) boundaries.
+
+The engine's hot path stores time as ``int`` nanoseconds since the UTC epoch.
+The project's canonical timezone is **ET** — every session boundary below is
+defined in ET and converted tz-aware (Topstep publishes rules in CT, but
+ET = CT + 1h always; the two share the identical US DST schedule).
+
+Topstep session boundaries (ET):
+    - Globex open:        18:00 previous calendar day (Sun 18:00 for Monday)
+    - auto-flatten start: 16:08
+    - flatten deadline:   16:10  (positions & working orders force-closed)
+    - Globex close:       17:00  (EOD balance snapshot for the MLL ratchet)
+    - day reset:          18:00  (DLL reset; next trading day begins)
+
+A bar timestamped at/after 18:00 ET belongs to the *next* trading day.
+"""
+
+from __future__ import annotations
+
+from datetime import date, datetime, time, timedelta
+from zoneinfo import ZoneInfo
+
+import msgspec
+
+__all__ = [
+    "ET",
+    "NS_PER_MIN",
+    "NS_PER_SEC",
+    "TOPSTEP_SESSION",
+    "SessionTimes",
+    "dt_to_ns",
+    "et_time_of",
+    "ns_to_dt",
+    "ns_to_et",
+    "trading_day_of",
+]
+
+ET = ZoneInfo("America/New_York")
+UTC = ZoneInfo("UTC")
+
+NS_PER_SEC = 1_000_000_000
+NS_PER_MIN = 60 * NS_PER_SEC
+
+
+_EPOCH = datetime(1970, 1, 1, tzinfo=UTC)
+
+
+def dt_to_ns(dt: datetime) -> int:
+    """tz-aware datetime -> int UTC nanoseconds. Naive datetimes are rejected.
+
+    Computed with exact integer arithmetic (datetime carries microseconds);
+    a float round-trip would lose sub-microsecond exactness at 2026 epochs.
+    """
+    if dt.tzinfo is None:
+        raise ValueError(f"naive datetime {dt!r}: all engine datetimes must be tz-aware")
+    delta = dt.astimezone(UTC) - _EPOCH
+    return ((delta.days * 86_400 + delta.seconds) * NS_PER_SEC) + delta.microseconds * 1_000
+
+
+def ns_to_dt(ns: int) -> datetime:
+    """int UTC nanoseconds -> tz-aware UTC datetime.
+
+    Exact integer arithmetic, truncating sub-microsecond remainders toward the
+    past (datetime resolution is 1 us). Truncation — never float rounding — so
+    an instant strictly before a boundary (e.g. 17:59:59.999999999 ET) can
+    never classify as at/after it (the 18:00 trading-day boundary hinges on this).
+    """
+    seconds, rem = divmod(ns, NS_PER_SEC)
+    return datetime.fromtimestamp(seconds, tz=UTC) + timedelta(microseconds=rem // 1_000)
+
+
+def ns_to_et(ns: int) -> datetime:
+    """int UTC nanoseconds -> tz-aware ET datetime."""
+    return ns_to_dt(ns).astimezone(ET)
+
+
+def et_time_of(d: date, t: time) -> int:
+    """An ET wall-clock instant on calendar date ``d`` -> int UTC nanoseconds."""
+    return dt_to_ns(datetime.combine(d, t, tzinfo=ET))
+
+
+def trading_day_of(ns: int) -> date:
+    """The Topstep trading day containing UTC-ns instant ``ns``.
+
+    The day boundary is 18:00 ET: at/after 18:00 the instant belongs to the
+    next calendar day's session (Sunday 18:00+ belongs to Monday).
+    """
+    local = ns_to_et(ns)
+    if local.time() >= time(18, 0):
+        return local.date() + timedelta(days=1)
+    return local.date()
+
+
+class SessionTimes(msgspec.Struct, frozen=True):
+    """The ET wall-clock boundaries of a Topstep trading day (all `datetime.time`)."""
+
+    open_prev_day: time = time(18, 0)  # on the PREVIOUS calendar day
+    auto_flatten: time = time(16, 8)
+    flatten: time = time(16, 10)
+    close: time = time(17, 0)  # Globex close; EOD-MLL snapshot instant
+    reset: time = time(18, 0)  # next trading day begins
+
+    def open_ns(self, day: date) -> int:
+        """Session open (18:00 ET on the previous calendar day)."""
+        return et_time_of(day - timedelta(days=1), self.open_prev_day)
+
+    def auto_flatten_ns(self, day: date) -> int:
+        return et_time_of(day, self.auto_flatten)
+
+    def flatten_ns(self, day: date) -> int:
+        return et_time_of(day, self.flatten)
+
+    def close_ns(self, day: date) -> int:
+        return et_time_of(day, self.close)
+
+    def reset_ns(self, day: date) -> int:
+        return et_time_of(day, self.reset)
+
+    def in_no_trade_window(self, ns: int) -> bool:
+        """True inside the daily no-trade window [flatten, reset) = [16:10, 18:00) ET."""
+        t = ns_to_et(ns).time()
+        return self.flatten <= t < self.reset
+
+
+TOPSTEP_SESSION = SessionTimes()

topstep_backtest/data/__init__.py

@@ -0,0 +1 @@
+"""topstep_backtest.data"""

topstep_backtest/data/clean.py

@@ -0,0 +1,86 @@
+"""Pre-run input hygiene: filename symbol inference.
+
+``infer_symbol_from_filename`` guards the boundary where user files meet the
+engine, powering the examples' ``--symbol`` cross-check. Feeding one product's
+file under another's tick economics passes every price-grid check and silently
+scales P&L (an ES file run as MNQ is exactly 25x wrong).
+
+This module used to also ship ``drop_closed_session_bars``, which discarded
+bars the CME calendar said could not be a real session. It was removed along
+with the holiday calendar itself (see ``core/time.py``): the table it consulted
+was known to disagree with CME on several dates a year, so it silently deleted
+tradable sessions. Filter exchange holidays upstream, in whatever produces your
+bar files.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import PurePath
+
+from ..core.instruments import SPECS
+
+__all__ = [
+    "AmbiguousSymbolError",
+    "infer_symbol_from_filename",
+]
+
+_TOKEN_SPLIT = re.compile(r"[^A-Za-z0-9]+")
+# Delivery-month code + 1-, 2-, or 4-digit year: the tail of a separator-free
+# vendor contract-code basename (MNQZ25, esu6, gcm2026). Three digits is no
+# known convention and stays unmatched.
+_MONTH_YEAR = re.compile(r"[FGHJKMNQUVXZ](?:\d{1,2}|\d{4})")
+
+
+class AmbiguousSymbolError(ValueError):
+    """Distinct product symbols matched distinct tokens of one filename."""
+
+    def __init__(self, name: str, symbols: tuple[str, ...]) -> None:
+        self.symbols = symbols
+        super().__init__(
+            f"filename {name!r} names several known products {list(symbols)} — "
+            "cannot infer which one the file contains"
+        )
+
+
+def _token_symbols(token: str) -> frozenset[str]:
+    """SPECS symbols evidenced by one uppercased token: an exact symbol, or a
+    contract code (symbol + delivery-month code + year digits, e.g. MNQZ25)."""
+    if token in SPECS:
+        return frozenset((token,))
+    return frozenset(
+        symbol
+        for symbol in SPECS
+        if token.startswith(symbol) and _MONTH_YEAR.fullmatch(token, len(symbol))
+    )
+
+
+def infer_symbol_from_filename(name: str) -> str | None:
+    """The unique SPECS product symbol evidenced by ``name``'s basename.
+
+    Token-aware, never substring: the basename splits on non-alphanumeric
+    boundaries and each token compares uppercased, matching either a bare
+    symbol by EXACT equality (``"sample_mnq_1m.csv"`` matches MNQ, never NQ)
+    or a contract code — symbol + delivery-month code + 1/2/4-digit year, the
+    separator-free shape vendor exports use (``"MNQZ25.csv"`` matches MNQ,
+    ``"esu6.parquet"`` matches ES). Both anchor at the token's start, so a
+    micro's code can never be misread as its mini's (``"MESU6.csv"`` is MES,
+    not ES) and ``"esoteric.csv"`` matches nothing. Only the basename is
+    inspected — directory names carry no evidence about the file's contents.
+
+    Returns ``None`` when no token carries evidence.
+
+    Raises:
+        AmbiguousSymbolError: several DISTINCT symbols matched (e.g.
+            ``"es_nq_spread.csv"``) — the caller must name the product
+            explicitly instead of trusting a guess.
+    """
+    basename = PurePath(name).name
+    tokens = {token.upper() for token in _TOKEN_SPLIT.split(basename) if token}
+    found: set[str] = set()
+    for token in tokens:
+        found |= _token_symbols(token)
+    matches = tuple(sorted(found))
+    if len(matches) > 1:
+        raise AmbiguousSymbolError(basename, matches)
+    return matches[0] if matches else None

topstep_backtest/data/feed.py

@@ -0,0 +1,56 @@
+"""In-memory bar feed with the ordering invariant enforced at construction.
+
+``ListBarFeed`` is the Tier-0 backtest feed: a pre-built sequence of bars,
+validated once up front so the engine can trust the ``DataFeed`` contract —
+non-decreasing ``ts_init`` across the merged stream, strictly increasing
+``ts_init`` per instrument (equal timestamps across DIFFERENT instruments are
+legal and expected; duplicate bars for the same instrument are data corruption
+and rejected loudly).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ..protocols import Bar
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator, Sequence
+
+__all__ = ["ListBarFeed"]
+
+
+class ListBarFeed:
+    """A validated, time-ordered in-memory ``DataFeed`` over a bar sequence."""
+
+    def __init__(self, bars: Sequence[Bar]) -> None:
+        self._bars: tuple[Bar, ...] = tuple(bars)
+        last_ts: int | None = None
+        last_per_instrument: dict[str, int] = {}
+        for index, bar in enumerate(self._bars):
+            if last_ts is not None and bar.ts_init < last_ts:
+                raise ValueError(
+                    f"bars out of order at index {index}: ts_init {bar.ts_init} < "
+                    f"previous {last_ts} (feed must be non-decreasing in ts_init)"
+                )
+            contract_id = bar.bar_type.contract_id
+            prev = last_per_instrument.get(contract_id)
+            if prev is not None and bar.ts_init <= prev:
+                raise ValueError(
+                    f"duplicate ts_init {bar.ts_init} for instrument {contract_id} at "
+                    f"index {index}: per-instrument ts_init must be strictly increasing"
+                )
+            last_per_instrument[contract_id] = bar.ts_init
+            last_ts = bar.ts_init
+        # dict preserves insertion order -> instruments in first-appearance order.
+        self._instruments: tuple[str, ...] = tuple(last_per_instrument)
+
+    def __iter__(self) -> Iterator[Bar]:
+        return iter(self._bars)
+
+    def __len__(self) -> int:
+        return len(self._bars)
+
+    def instruments(self) -> Sequence[str]:
+        """The contract ids this feed emits, in first-appearance order."""
+        return self._instruments

topstep_backtest/data/synthetic.py

@@ -0,0 +1,137 @@
+"""Deterministic synthetic OHLCV bars for examples and tests.
+
+A seeded ``random.Random`` walk in INTEGER TICKS — prices are reconstructed
+via ``from_ticks`` so every value is exactly on the instrument's grid and no
+float ever touches a price. Bars are stamped in ET regular trading hours
+starting 09:30 (one per ``unit x unit_number`` step), weekends are skipped,
+and the same seed always reproduces the identical bar tuple.
+
+Exchange holidays are NOT skipped — this package ships no holiday calendar
+(see ``core/time.py``). A synthetic tape spanning a market holiday will emit
+a session that would not exist in real data.
+
+``days`` counts WEEKDAYS emitted: the generator scans forward from
+``start_day`` and skips Sat/Sun until ``days`` sessions exist.
+``bars_per_day`` is capped at 450 so the last one-minute bar closes at
+17:00 ET — no synthetic bar can ever sit inside the 17:00-18:00 ET
+maintenance halt.
+"""
+
+from __future__ import annotations
+
+from datetime import time, timedelta
+from decimal import Decimal
+from random import Random
+from typing import TYPE_CHECKING
+
+from topstep_sdk import AggregateBarUnit
+
+from ..core.money import from_ticks, to_ticks
+from ..core.time import et_time_of
+from ..protocols import Bar, BarType
+from .wrangler import step_ns
+
+if TYPE_CHECKING:
+    from datetime import date
+
+    from ..core.instruments import InstrumentSpec
+
+__all__ = ["synthetic_bars"]
+
+_RTH_OPEN = time(9, 30)
+# 09:30 ET + 450 one-minute bars = 17:00 ET, the start of the 17:00-18:00 ET
+# maintenance halt. More bars would land inside the halt and be rejected by
+# this package's own validator (``in_maintenance_halt``).
+_MAX_BARS_PER_DAY = 450
+_MIN_VOLUME = 100
+_MAX_VOLUME = 5_000
+
+
+def synthetic_bars(
+    *,
+    contract_id: str,
+    spec: InstrumentSpec,
+    start_day: date,
+    days: int,
+    seed: int,
+    start_price: Decimal,
+    bars_per_day: int = 390,
+    unit: AggregateBarUnit = AggregateBarUnit.MINUTE,
+    unit_number: int = 1,
+    drift_ticks_per_day: int = 0,
+    vol_ticks: int = 8,
+) -> tuple[Bar, ...]:
+    """Generate ``days`` trading sessions of consistent, on-grid OHLCV bars.
+
+    ``start_price`` must lie on ``spec.tick_size`` (raises ``OffGridError``
+    otherwise) and be comfortably above zero for the chosen ``vol_ticks``.
+    ``drift_ticks_per_day`` is distributed across the day's bars in exact
+    integer ticks; ``vol_ticks`` bounds the per-bar random move.
+    ``bars_per_day`` must be <= 450 (09:30 + 450 minutes = 17:00 ET) so no
+    bar lands inside the 17:00-18:00 ET maintenance halt.
+    """
+    if days < 0:
+        raise ValueError(f"days must be >= 0, got {days}")
+    if bars_per_day < 1:
+        raise ValueError(f"bars_per_day must be >= 1, got {bars_per_day}")
+    if bars_per_day > _MAX_BARS_PER_DAY:
+        raise ValueError(
+            f"bars_per_day must be <= {_MAX_BARS_PER_DAY}, got {bars_per_day}: bars "
+            "are stamped from the 09:30 ET session open and 09:30 + 450 minutes = "
+            "17:00 ET, the start of the 17:00-18:00 ET maintenance halt — extra "
+            "bars would land inside the halt and fail validation"
+        )
+    if vol_ticks < 0:
+        raise ValueError(f"vol_ticks must be >= 0, got {vol_ticks}")
+
+    step = step_ns(unit, unit_number)
+    tick = spec.tick_size
+    start_ticks = to_ticks(start_price, tick)  # raises OffGridError off-grid
+
+    wick_max = max(1, vol_ticks // 2)
+    # Keep the walk high enough that low = min(o, c) - wick stays positive.
+    floor_ticks = vol_ticks + wick_max + 1
+    if start_ticks < floor_ticks:
+        raise ValueError(
+            f"start_price {start_price} ({start_ticks} ticks) is too low for "
+            f"vol_ticks={vol_ticks}; need at least {floor_ticks} ticks"
+        )
+
+    rng = Random(seed)
+    bar_type = BarType(contract_id=contract_id, unit=unit, unit_number=unit_number)
+    # Exact integer split of the daily drift across bars (works for negatives).
+    base_drift, extra_drift_bars = divmod(drift_ticks_per_day, bars_per_day)
+
+    bars: list[Bar] = []
+    current = start_ticks
+    day = start_day
+    emitted = 0
+    while emitted < days:
+        if day.weekday() >= 5:
+            day += timedelta(days=1)
+            continue
+        session_open_ns = et_time_of(day, _RTH_OPEN)
+        for i in range(bars_per_day):
+            open_ticks = current
+            delta = base_drift + (1 if i < extra_drift_bars else 0)
+            delta += rng.randint(-vol_ticks, vol_ticks)
+            close_ticks = max(open_ticks + delta, floor_ticks)
+            high_ticks = max(open_ticks, close_ticks) + rng.randint(0, wick_max)
+            low_ticks = min(open_ticks, close_ticks) - rng.randint(0, wick_max)
+            ts_event = session_open_ns + i * step
+            bars.append(
+                Bar(
+                    bar_type=bar_type,
+                    ts_event=ts_event,
+                    ts_init=ts_event + step,
+                    open=from_ticks(open_ticks, tick),
+                    high=from_ticks(high_ticks, tick),
+                    low=from_ticks(low_ticks, tick),
+                    close=from_ticks(close_ticks, tick),
+                    volume=rng.randint(_MIN_VOLUME, _MAX_VOLUME),
+                )
+            )
+            current = close_ticks
+        emitted += 1
+        day += timedelta(days=1)
+    return tuple(bars)

topstep_backtest/data/validator.py

@@ -0,0 +1,215 @@
+"""Bar-stream sanity validation: catch bad data BEFORE it reaches the engine.
+
+Severity encoding (documented contract): severity is derived from the issue
+``code`` — codes in ``INFO_CODES`` (currently only ``"session_gap"``) are
+informational; every other code is an ERROR. ``ValidationReport.ok`` is True
+iff no ERROR-severity issue is present.
+
+Codes emitted:
+  - ``ohlc_inconsistent``   ERROR  high < max(open, close) or low > min(open, close)
+  - ``stamp_inverted``      ERROR  ``ts_event`` >= ``ts_init`` — the bar's open
+                                   does not precede its close (the classic
+                                   off-by-one look-ahead stamp bug)
+  - ``negative_volume``     ERROR  volume < 0
+  - ``duplicate_ts``        ERROR  same instrument, repeated ``ts_init``
+  - ``non_monotonic``       ERROR  ``ts_init`` decreases along the sequence
+  - ``off_grid``            ERROR  a price off the instrument's tick grid
+  - ``in_maintenance_halt`` ERROR  ``ts_event`` inside the 17:00-18:00 ET halt
+  - ``weekend_bar``         ERROR  bar's trading day falls on Sat/Sun
+  - ``session_gap``         INFO   > 3x step missing between consecutive bars of
+                                   the same instrument within one trading day
+
+Ordering checks (``duplicate_ts``, ``non_monotonic``) anchor ``ts_ns`` to the
+bar's ``ts_init``; event-time checks (halt/weekend) anchor to ``ts_event``.
+
+There is deliberately no exchange-holiday check: this package ships no holiday
+calendar (see the note in ``core/time.py``), so a bar landing on a market
+holiday is indistinguishable from any other weekday bar here.
+"""
+
+from __future__ import annotations
+
+from datetime import time
+from typing import TYPE_CHECKING
+
+import msgspec
+
+from ..core.money import is_on_grid
+from ..core.time import ns_to_et, trading_day_of
+from .wrangler import step_ns
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from ..core.instruments import InstrumentSpec
+    from ..protocols import Bar, BarType
+
+__all__ = ["INFO_CODES", "ValidationIssue", "ValidationReport", "validate_bars"]
+
+INFO_CODES: frozenset[str] = frozenset({"session_gap"})
+
+_HALT_START = time(17, 0)
+_HALT_END = time(18, 0)
+
+
+class ValidationIssue(msgspec.Struct, frozen=True):
+    """One finding; severity is derived from ``code`` (see module docstring)."""
+
+    code: str
+    message: str
+    ts_ns: int | None = None
+
+
+class ValidationReport(msgspec.Struct, frozen=True):
+    """All findings for a bar sequence; ``ok`` means no ERROR-severity issues."""
+
+    issues: tuple[ValidationIssue, ...]
+
+    @property
+    def ok(self) -> bool:
+        return all(issue.code in INFO_CODES for issue in self.issues)
+
+
+def _bar_step_ns(bar_type: BarType, cache: dict[BarType, int | None]) -> int | None:
+    """Step in ns for a bar type, or None if the unit has no fixed step."""
+    if bar_type not in cache:
+        try:
+            cache[bar_type] = step_ns(bar_type.unit, bar_type.unit_number)
+        except ValueError:
+            cache[bar_type] = None
+    return cache[bar_type]
+
+
+def validate_bars(bars: Sequence[Bar], spec: InstrumentSpec) -> ValidationReport:
+    """Run every check over ``bars`` and return the full report (never raises)."""
+    issues: list[ValidationIssue] = []
+    last_ts_init: int | None = None
+    last_per_instrument: dict[str, Bar] = {}
+    step_cache: dict[BarType, int | None] = {}
+
+    for index, bar in enumerate(bars):
+        # --- stamp sanity: open must strictly precede close ----------------
+        if bar.ts_event >= bar.ts_init:
+            issues.append(
+                ValidationIssue(
+                    code="stamp_inverted",
+                    message=(
+                        f"bar {index}: ts_event {bar.ts_event} >= ts_init "
+                        f"{bar.ts_init} — the bar's open does not precede its "
+                        "close (stamp-inverted bar; acting on it hands the "
+                        "strategy one bar of the future)"
+                    ),
+                    ts_ns=bar.ts_init,
+                )
+            )
+
+        # --- volume sanity -------------------------------------------------
+        if bar.volume < 0:
+            issues.append(
+                ValidationIssue(
+                    code="negative_volume",
+                    message=f"bar {index}: volume {bar.volume} is negative",
+                    ts_ns=bar.ts_init,
+                )
+            )
+
+        # --- OHLC internal consistency -----------------------------------
+        if bar.high < max(bar.open, bar.close) or bar.low > min(bar.open, bar.close):
+            issues.append(
+                ValidationIssue(
+                    code="ohlc_inconsistent",
+                    message=(
+                        f"bar {index}: OHLC inconsistent (o={bar.open} h={bar.high} "
+                        f"l={bar.low} c={bar.close})"
+                    ),
+                    ts_ns=bar.ts_init,
+                )
+            )
+
+        # --- tick grid ----------------------------------------------------
+        for field, price in (
+            ("open", bar.open),
+            ("high", bar.high),
+            ("low", bar.low),
+            ("close", bar.close),
+        ):
+            if not is_on_grid(price, spec.tick_size):
+                issues.append(
+                    ValidationIssue(
+                        code="off_grid",
+                        message=(
+                            f"bar {index}: {field}={price} is not on the {spec.tick_size} tick grid"
+                        ),
+                        ts_ns=bar.ts_init,
+                    )
+                )
+
+        # --- ordering (global) and per-instrument duplicates/gaps ---------
+        if last_ts_init is not None and bar.ts_init < last_ts_init:
+            issues.append(
+                ValidationIssue(
+                    code="non_monotonic",
+                    message=(f"bar {index}: ts_init {bar.ts_init} < previous {last_ts_init}"),
+                    ts_ns=bar.ts_init,
+                )
+            )
+        last_ts_init = bar.ts_init
+
+        contract_id = bar.bar_type.contract_id
+        prev = last_per_instrument.get(contract_id)
+        if prev is not None:
+            if bar.ts_init == prev.ts_init:
+                issues.append(
+                    ValidationIssue(
+                        code="duplicate_ts",
+                        message=(
+                            f"bar {index}: duplicate ts_init {bar.ts_init} for "
+                            f"instrument {contract_id}"
+                        ),
+                        ts_ns=bar.ts_init,
+                    )
+                )
+            else:
+                step = _bar_step_ns(bar.bar_type, step_cache)
+                same_day = trading_day_of(prev.ts_init) == trading_day_of(bar.ts_init)
+                if step is not None and same_day and bar.ts_init - prev.ts_init > 3 * step:
+                    missing = (bar.ts_init - prev.ts_init) // step - 1
+                    issues.append(
+                        ValidationIssue(
+                            code="session_gap",
+                            message=(
+                                f"bar {index}: ~{missing} bars missing before ts_init "
+                                f"{bar.ts_init} for {contract_id} (intraday gap > 3x step)"
+                            ),
+                            ts_ns=bar.ts_init,
+                        )
+                    )
+        last_per_instrument[contract_id] = bar
+
+        # --- calendar / session placement (keyed off ts_event) ------------
+        event_et = ns_to_et(bar.ts_event)
+        if _HALT_START <= event_et.time() < _HALT_END:
+            issues.append(
+                ValidationIssue(
+                    code="in_maintenance_halt",
+                    message=(
+                        f"bar {index}: ts_event {event_et:%Y-%m-%d %H:%M:%S %Z} is "
+                        "inside the 17:00-18:00 ET maintenance halt"
+                    ),
+                    ts_ns=bar.ts_event,
+                )
+            )
+        session_day = trading_day_of(bar.ts_event)
+        if session_day.weekday() >= 5:
+            issues.append(
+                ValidationIssue(
+                    code="weekend_bar",
+                    message=(
+                        f"bar {index}: ts_event {event_et:%Y-%m-%d %H:%M:%S %Z} falls "
+                        f"in the weekend session gap (trading day {session_day})"
+                    ),
+                    ts_ns=bar.ts_event,
+                )
+            )
+
+    return ValidationReport(issues=tuple(issues))