# Phase 3: Parquet-First Catchup - Context

**Gathered:** 2026-03-24
**Status:** Ready for planning
**Mode:** Auto-generated (infrastructure phase — smart discuss skipped)

<domain>
## Phase Boundary

Sidecar startup leverages the local Parquet tick cache to minimize REST API calls during fill_from_rest. On startup, reads max(agg_trade_id) from today's Parquet per symbol, then only fetches the gap between Parquet's last trade and WS buffer start via REST. Falls back to full fill_from_rest if Parquet is stale (>10 min) or missing.

</domain>

<decisions>
## Implementation Decisions

### Claude's Discretion

All implementation choices are at Claude's discretion — pure infrastructure phase. Use ROADMAP phase goal, success criteria, and codebase conventions to guide decisions.

Key technical constraints:

- SEED-001 already committed (sidecar reads Parquet cache before REST) — check if implementation exists
- `TickStorage` class in `python/opendeviationbar/storage/parquet.py` provides `has_ticks()` and `read_ticks()`
- Parquet tick cache path: `~/.cache/opendeviationbar/ticks/{SYMBOL}/YYYY-MM-DD.parquet`
- Seeder populates Parquet ticks every 5 min (Binance) / 15 min (Exness)
- `fill_from_rest` in `sidecar/midnight.py` is the integration point
- Writer ownership: sidecar owns today, kintsugi owns yesterday+older

### Carrying forward from Phase 2

- `fill_from_rest` returns bars (not trades) — Phase 2 confirmed this
- Stathera continuity validation added to `_sync_flush_rest_bars`
- Junction telemetry (`rest_first_tid`, `rest_last_tid`, `ws_first_tid`) available in `/status`

</decisions>

<canonical_refs>

## Canonical References

**Downstream agents MUST read these before planning or implementing.**

### Parquet tick cache

- `python/opendeviationbar/storage/CLAUDE.md` — TickStorage class, daily partitions, MEM guards
- `python/opendeviationbar/storage/parquet.py` — `TickStorage`, `has_ticks()`, `read_ticks()`

### Sidecar fill pipeline

- `python/opendeviationbar/sidecar/midnight.py` — `fill_from_rest()` implementation
- `python/opendeviationbar/sidecar/CLAUDE.md` — sidecar module map, startup sequence

### SEED-001 (prior work)

- Commit `d2dacc5` — "seed(001): sidecar Parquet-first catchup — read seeder cache before REST"

</canonical_refs>

<code_context>

## Existing Code Insights

### Reusable Assets

- `TickStorage` class — Parquet tick cache reader
- `fill_from_rest()` — existing integration point in midnight.py
- Rate limit coordinator — tracks REST API weight consumption

### Established Patterns

- Seeder writes Parquet ticks → sidecar can read them
- `has_ticks()` check before download (used by `populate_cache_resumable`)
- Daily Parquet files: `{SYMBOL}/YYYY-MM-DD.parquet`

### Integration Points

- `midnight.py:fill_from_rest()` — where Parquet read should be inserted
- `storage/parquet.py:TickStorage` — provides the Parquet interface
- Rate limit coordinator logs — for measuring REST weight reduction

</code_context>

<specifics>
## Specific Ideas

No specific requirements — infrastructure phase.

</specifics>

<deferred>
## Deferred Ideas

None — infrastructure phase.

</deferred>

---

_Phase: 03-parquet-first-catchup_
_Context gathered: 2026-03-24_
