# Phase 1: Yesterday Integrity Check + Signal File - Context

**Gathered:** 2026-03-23
**Status:** Ready for planning
**Mode:** From session discussion (milestone v1.5 planning)

<domain>
## Phase Boundary

Replace `_repair_yesterday_if_needed()` (4h sequential repair of 64 pairs) with:

1. Fast integrity check (~3s): crossover TID alignment + Stathera audit
2. Signal file for broken symbols → kintsugi picks up on next pass

Requirements: STARTUP-01 (integrity check), STARTUP-02 (signal file)

</domain>

<decisions>
## Implementation Decisions

### Yesterday Integrity Check (STARTUP-01)

**Decision:** Two-step verification per symbol:

1. Crossover TID alignment: CH orphan bar `last_agg_trade_id` == `crossover_tid - 1`
   - Already have `_self_validate_crossover()` in midnight.py that proves this
   - Reuse the 3-property proof (pred < midnight, cross >= midnight, consecutive)
2. Stathera audit: single CH query per symbol checking zero gaps AND zero overlaps on yesterday

**Decision:** If BOTH pass → skip repair, log "yesterday clean". If EITHER fails → flag symbol with reason.

**Decision:** CH unavailable → graceful fallback (defer all to kintsugi, don't block startup).

### Signal File (STARTUP-02)

**Decision:** Write to `/var/tmp/opendeviationbar-yesterday-repair.json`

- Atomic write (tempfile + os.rename)
- Format: `{"symbols": {"AVAXUSDT": "orphan_misaligned", "FILUSDT": "stathera_gap"}, "timestamp": "ISO8601", "sidecar_pid": N}`
- Kintsugi reads and clears on next pass (Phase 2)

**Decision:** `_repair_yesterday_if_needed()` in sidecar/midnight.py is REPLACED (not removed — the function body changes from repair to check+signal).

### Claude's Discretion

- Exact CH query for Stathera audit (single query vs per-threshold)
- Whether to batch all 16 symbols into one CH query or iterate
- Signal file location (suggested /var/tmp/ but any persistent path works)
- Log levels for clean vs broken vs CH-unavailable outcomes

</decisions>

<code_context>

## Existing Code Insights

- `sidecar/midnight.py` already has `_get_midnight_crossover_tid()` with self-validation
- `_self_validate_crossover()` proves 3 properties per symbol (1 REST call)
- `_repair_yesterday_if_needed()` at line 278 is the function to replace
- `_verify_yesterday_orphan()` at line 231 already checks orphan alignment
- Kintsugi's `_discover_shards_stathera()` in `kintsugi/discovery.py` has the Stathera gap/overlap query pattern

</code_context>

<specifics>
## Specific Ideas

- The self-validator already runs during preflight — its result can feed directly into the integrity check (no extra REST calls needed)
- The Stathera audit query should match the heartbeat's pattern for consistency
- Signal file should be human-readable JSON for debugging

</specifics>

<deferred>
## Deferred Ideas

- Today-seeding in Parquet (seeder seeds yesterday only, separate initiative)
- Kintsugi overlap_strategy optimization (already changed to "warn" for REST path)

</deferred>
