# Roadmap: v1.1 — Overlap Prevention

**Created:** 2026-03-19
**Phases:** 4
**Requirements:** 13/13 mapped
**Granularity:** Fine (config.json)

---

## Phase 1: Auto-Delete+Rewrite Guard

**Goal:** Make every sidecar write self-protecting against overlaps by using `overlap_strategy="replace"`.

**Requirements:**

- GARD-01: Use `overlap_strategy="replace"` instead of `"off"` for ALL sidecar writes
- GARD-02: Both code paths in `_write_bars_batch_to_clickhouse()` use `"replace"`
- GARD-03: Existing tests pass unchanged

**Location:** `python/opendeviationbar/sidecar.py` lines 169 and 178. Change `overlap_strategy="off"` to `overlap_strategy="replace"`. ~2 lines changed.

**Success Criteria:**

1. Both `store_bars_batch()` calls in `_write_bars_batch_to_clickhouse()` pass `overlap_strategy="replace"`
2. All existing sidecar tests pass without modification
3. Each batch write now goes through `store_bars_replacing()` → atomic DELETE+INSERT for overlapping trade-ID ranges

**Parallelism:** Independent. Can be done in same session as Phase 2.

---

## Phase 2: Sidecar Overlap Self-Heal

**Goal:** Close the today-guard gap — detect and repair today's overlaps in the sidecar's periodic cycle.

**Requirements:**

- HEAL-01: Query ClickHouse for today's overlaps (reuse Stathera query)
- HEAL-02: Trigger targeted `_repair_under_lock()` for overlapping (symbol, threshold, day)
- HEAL-03: Hold Redis write lock during repair
- HEAL-04: Configurable interval (default 300s)
- HEAL-05: Non-fatal — exceptions logged and suppressed
- HEAL-06: INFO-level logging of repair actions

**Location:** `python/opendeviationbar/sidecar.py` after the Charon block (lines 2431-2447), before `continue` at line 2449. ~40 lines.

**Success Criteria:**

1. New `_check_and_heal_overlaps()` function queries today's overlaps using existing Stathera query
2. For each overlapping (symbol, threshold) pair, calls `_repair_under_lock()` with today's date
3. Repair holds `cache_write_lock()` for the duration
4. Timer-guarded at 300s intervals (same pattern as `charon_last_replay`)
5. Exceptions caught and logged — never crashes the sidecar
6. Journal output shows: `overlap_heal: symbol=WLDUSDT threshold=250 overlaps=3 repaired_in_ms=1234`

**Parallelism:** Independent of Phase 1. Can be done in same session.

---

## Phase 3: Deploy Hardening

**Goal:** Prevent the root cause chain that led to the v13.30.0 incident.

**Requirements:**

- DEPL-01: Build time assertion (>30s or ABORT)
- DEPL-02: Directory resolution from systemd
- DEPL-03: Post-start telemetry gate
- DEPL-04: Git hash embedding via vergen

**Location:** Multiple files:

- DEPL-01: `scripts/deploy.sh` or mise deploy task — add build time check (~5 lines)
- DEPL-02: Deploy script — read `systemctl show -p WorkingDirectory` (~3 lines)
- DEPL-03: Deploy script — `journalctl --since "30s ago" | grep "StreamManager started"` (~5 lines)
- DEPL-04: `Cargo.toml` (add vergen dep) + `src/lib.rs` (log git SHA at init) (~10 lines)

**Success Criteria:**

1. `mise run deploy:bigblack` aborts if build time <30s with clear error message
2. Deploy script reads systemd WorkingDirectory and deploys to that path
3. After sidecar start, script waits up to 60s for "StreamManager started" in journal before proceeding
4. Sidecar startup log includes `git_sha=abc1234` field
5. Existing `mise run release:*` workflow unchanged

**Parallelism:** DEPL-04 (vergen) independent. DEPL-01-03 depend on each other.

---

## Phase 4: Verification + Deploy

**Goal:** Deploy v1.1 to bigblack and verify zero overlaps.

**Success Criteria:**

1. Build + deploy using the hardened deploy script
2. ClickHouse query confirms 0 overlaps across all 18 symbols for 24h+
3. If synthetic overlaps are injected (test), self-heal detects and repairs within 5 minutes
4. Journal logs confirm guard and self-heal are operational
5. Heartbeat reports HEALTHY with no overlap alerts

**Parallelism:** Depends on Phases 1-3.

---

## Dependency Graph

```
Phase 1 (Guard) ────────┐
Phase 2 (Self-Heal) ────┤── Phase 4 (Verify + Deploy)
Phase 3 (Deploy Harden) ┘
```

**Fast path:** Phases 1+2 in one session (~50 lines total). Phase 3 in parallel or same session. Phase 4 after release.

---

## Coverage Verification

| Category  | Requirements              | Count  | Phases |
| --------- | ------------------------- | ------ | ------ |
| Guard     | GARD-01, GARD-02, GARD-03 | 3      | 1      |
| Self-Heal | HEAL-01..06               | 6      | 2      |
| Deploy    | DEPL-01..04               | 4      | 3      |
| **Total** |                           | **13** | 1-3    |

**v1 requirements mapped: 13/13. Zero unmapped.**

---

_Roadmap created: 2026-03-19_
