# v1.1 — Overlap Prevention (Belt + Suspenders)

## What This Is

A defense-in-depth fix that makes bar overlaps impossible at the code level and self-healing at the operations level. Born from the v13.30.0 deploy incident (2026-03-20) where 3 WLDUSDT@250 overlaps were created by a stale wheel + wrong deploy directory + kintsugi racing the sidecar.

## Core Value

Zero overlaps, ever — even during botched deploys, concurrent writer races, or operational mistakes. The single-writer assumption is no longer sufficient; the code must be self-protecting.

## Requirements

### Validated

- ✓ `store_bars_replacing()` exists in `maintenance.py:266` — atomic DELETE+INSERT by trade-ID range
- ✓ `_do_replace()` exists in `maintenance.py:370` — lightweight DELETE
- ✓ `_cleanup_stale_left_straddle()` exists in `maintenance.py:434` — async DELETE race cleanup
- ✓ `cache_write_lock()` exists in `write_lock.py:81` — Redis distributed lock
- ✓ Stathera overlap query exists in `scripts/heartbeat/checks/stathera.py:36-55`
- ✓ `_repair_under_lock()` exists in `kintsugi.py:1319` — day-recompute repair
- ✓ Sidecar idle loop has Charon block at `sidecar.py:2431-2449` — natural insertion point

### Active

- [ ] Auto-delete+rewrite guard: change sidecar's `overlap_strategy` from `"off"` to `"replace"`
- [ ] Sidecar overlap self-heal: detect today's overlaps, trigger targeted repair in periodic cycle
- [ ] Deploy hardening: build time assertion, directory resolution, telemetry gate, git hash embedding

### Out of Scope

- Kintsugi changes — writer ownership model is stable
- Heartbeat repair triggers — heartbeat is detection only, not repair
- Asclepius reactivation — permanently disabled (#284)
- New symbol onboarding — current 18 symbols are the target

## Context

**Root cause chain (v13.30.0):**

| #   | Failure                          | Impact                                    |
| --- | -------------------------------- | ----------------------------------------- |
| 1   | Stale cached wheel (1.67s build) | Wrong code running                        |
| 2   | Wrong directory (~/eon/ vs ~/)   | systemd ran old code                      |
| 3   | No telemetry verification gate   | Started kintsugi before verifying sidecar |
| 4   | Kintsugi raced sidecar           | Concurrent writers → 3 overlaps           |
| 5   | No pre-write overlap rejection   | Overlaps persisted silently               |

**Today-guard gap:** Kintsugi defers today's repairs (writer ownership). Puck can't see overlaps. Heartbeat detects but doesn't act. Today's overlaps have NO automated repair path until tomorrow.

**Fix:** The guard prevents overlap creation (Component 1). The self-heal repairs any that slip through on today (Component 2). Deploy hardening prevents the root cause (Component 3).

## Constraints

- Changes to sidecar.py must be backward-compatible (no new env vars required)
- overlap_strategy="replace" adds ~5ms per batch write — negligible at ~50 bars/min
- Self-heal must hold Redis write lock during repair
- Python 3.13 only
- Deploy hardening must not break existing `mise run release:*` workflow

## Key Decisions

| Decision                              | Rationale                                                                     | Outcome   |
| ------------------------------------- | ----------------------------------------------------------------------------- | --------- |
| Use existing `store_bars_replacing()` | Already battle-tested, atomic DELETE+INSERT, handles race conditions          | — Pending |
| Self-heal in sidecar, not heartbeat   | Sidecar owns today — it should fix today. Heartbeat is detection-only oneshot | — Pending |
| Build time >30s assertion             | 1.67s build = stale cached wheel. Real builds take 60s+                       | — Pending |

---

_Last updated: 2026-03-19 — initialized v1.1 milestone_
