# Phase 1: Crossover TID Utility - Context

**Gathered:** 2026-03-25
**Status:** Ready for planning
**Mode:** Auto-generated (infrastructure phase)

<domain>
## Phase Boundary

Extract `_get_midnight_crossover_tid()` and `_verify_crossover_from_seed()` from `sidecar/midnight.py` into a shared module so seeder, kintsugi, and heartbeat can call them without importing sidecar internals. The sidecar continues to use the same functions via the new shared module.

</domain>

<decisions>
## Implementation Decisions

### Claude's Discretion

Key constraints:

- `_get_midnight_crossover_tid(symbol)` at `sidecar/midnight.py:17` — fetches crossover TID from Binance REST
- `_verify_crossover_from_seed(symbol, seed_tid, midnight_ms)` — validates crossover properties
- Both use `fetch_aggtrades_rest` (Rust PyO3 binding) underneath — Rust-first is maintained
- New location: `python/opendeviationbar/crossover.py` (or similar shared module)
- Sidecar `midnight.py` should import from the new module (backward compatible)
- Function signatures should accept a `date` parameter (not just "today's midnight") for flexibility
- Keep the self-validation logic intact — it prevents silent crossover errors

</decisions>

<canonical_refs>

## Canonical References

- `python/opendeviationbar/sidecar/midnight.py:17-145` — current crossover TID functions
- `src/binance_bindings.rs` — `fetch_aggtrades_rest` PyO3 binding
- `scripts/heartbeat/checks/yesterday.py` — current consumer (reimplements crossover lookup)
- `scripts/tick_cache_seeder.py` — future consumer (seeder)
- `python/opendeviationbar/kintsugi/repair.py` — future consumer (kintsugi)
  </canonical_refs>

<code_context>

## Existing Code Insights

- The function does 1-2 REST API calls per symbol (lightweight)
- Self-validation checks 3 properties: predecessor < midnight, crossover >= midnight, consecutive TIDs
- The heartbeat `yesterday.py` has its own crossover lookup — should be replaced by the shared utility
  </code_context>

<specifics>
No specific requirements.
</specifics>

<deferred>
None.
</deferred>

---

_Phase: 01-crossover-tid-utility_
_Context gathered: 2026-03-25_
