---
phase: 02-sidecar-fill-pipeline
plan: 01
subsystem: sidecar
tags: [stathera, ring-buffer, telemetry, diagnostics]

# Dependency graph
requires:
  - phase: 01-mutation-safety
    provides: partition-scoped DELETE for clean-slate startup
provides:
  - Stathera continuity validation in REST batch before CH write
  - dropped_bars diagnostic after fill_from_rest
  - Junction telemetry with rest_first_tid + rest_last_tid per symbol
  - STREAM-01 contract documentation (no trade DataFrame in Python)
affects: [03-parquet-first-catchup, sidecar-monitoring]

# Tech tracking
tech-stack:
  added: []
  patterns:
    - "Diagnostic-only validation: log WARNING but never block writes"
    - "Sort-then-check Stathera: sort by first_agg_trade_id, detect gaps and overlaps"

key-files:
  created: []
  modified:
    - python/opendeviationbar/sidecar/__init__.py
    - python/opendeviationbar/sidecar/midnight.py
    - tests/test_sync_flush_atomic_replace.py

key-decisions:
  - "Stathera validation is diagnostic-only (WARNING log, never blocks CH write)"
  - "Non-monotonic detection uses sorted-then-overlap check (curr_first <= prev_last after sort)"

patterns-established:
  - "Diagnostic validation pattern: validate before write, log warning, never block"

requirements-completed: [STREAM-01, STREAM-02]

# Metrics
duration: 4min
completed: 2026-03-24
---

# Phase 02 Plan 01: Pipeline Hardening Summary

**Stathera continuity validation and dropped_bars diagnostic in sidecar fill pipeline, with junction telemetry enrichment and STREAM-01 contract documentation**

## Performance

- **Duration:** 4 min
- **Started:** 2026-03-24T19:35:40Z
- **Completed:** 2026-03-24T19:39:40Z
- **Tasks:** 2
- **Files modified:** 3

## Accomplishments

- Stathera continuity check runs on every REST batch in \_sync_flush_rest_bars (detects gaps and non-monotonic TID ordering)
- dropped_bars checked after fill_from_rest with LOUD WARNING on ring buffer overflow
- Junction telemetry enriched with both rest_first_tid and rest_last_tid per symbol
- Code audit confirms no trade DataFrame exists in the Python fill path (STREAM-01)
- 3 new tests covering valid ordering, gap detection, and non-monotonic detection

## Task Commits

Each task was committed atomically:

1. **Task 1: Add dropped_bars diagnostic and Stathera ordering validation** - `f6e4160` (test: RED), `69f3e26` (feat: GREEN)
2. **Task 2: Code audit — verify no trade DataFrame in Python fill path** - `476b115` (docs)

## Files Created/Modified

- `python/opendeviationbar/sidecar/__init__.py` - dropped_bars check after fill_from_rest, STREAM-01 contract comment
- `python/opendeviationbar/sidecar/midnight.py` - Stathera continuity validation in \_sync_flush_rest_bars, rest_first_tid telemetry
- `tests/test_sync_flush_atomic_replace.py` - 3 new tests for Stathera ordering validation

## Decisions Made

- Stathera validation is diagnostic-only: logs WARNING but never blocks CH write (non-fatal)
- Non-monotonic detection uses sort-then-overlap check: after sorting by first_agg_trade_id, bars where curr_first <= prev_last indicate overlapping TID ranges

## Deviations from Plan

None - plan executed exactly as written.

## Known Pre-existing Test Failures

Two pre-existing test failures discovered (not caused by this plan's changes):

1. `test_cross_midnight_bars_filtered`: Key mismatch between `_make_bar` (`open_time_us`/`close_time_us`) and midnight.py L1 filter (`open_time_ms`/`close_time_ms`)
2. `test_get_midnight_crossover_tid_success`: Calls real Binance REST API without mocking

Logged to `deferred-items.md` for future fix.

## Issues Encountered

None

## User Setup Required

None - no external service configuration required.

## Next Phase Readiness

- Pipeline hardening complete, sidecar fill path now has runtime assertions for both STREAM-01 and STREAM-02
- Junction telemetry enriched for heartbeat monitoring to use

## Self-Check: PASSED

---

_Phase: 02-sidecar-fill-pipeline_
_Completed: 2026-03-24_
