# Requirements: v1.1 — Overlap Prevention

**Defined:** 2026-03-19
**Core Value:** Zero overlaps, ever — even during botched deploys or operational mistakes

## v1 Requirements

### Auto-Delete+Rewrite Guard

- [ ] **GARD-01**: Sidecar `_write_bars_batch_to_clickhouse()` uses `overlap_strategy="replace"` instead of `"off"` for ALL writes
- [ ] **GARD-02**: Both code paths in `_write_bars_batch_to_clickhouse()` (cache-provided and fresh-cache) use `"replace"`
- [ ] **GARD-03**: Existing tests pass unchanged — `store_bars_replacing()` is a superset of `store_bars_batch()` with `"off"`

### Sidecar Overlap Self-Heal

- [ ] **HEAL-01**: Sidecar periodic cycle queries ClickHouse for today's overlaps (reuses Stathera overlap query)
- [ ] **HEAL-02**: If overlaps found for streaming pairs, trigger targeted `_repair_under_lock()` for just that (symbol, threshold, day)
- [ ] **HEAL-03**: Self-heal holds Redis write lock during repair via `cache_write_lock()`
- [ ] **HEAL-04**: Self-heal runs on a configurable interval (default 300s), independent of Charon interval
- [ ] **HEAL-05**: Self-heal is non-fatal — exceptions are logged and suppressed (same pattern as Charon)
- [ ] **HEAL-06**: Self-heal logs repair actions at INFO level with symbol, threshold, overlap count, repair duration

### Deploy Hardening

- [ ] **DEPL-01**: Build time assertion: if maturin build completes in <30s, ABORT and force clean rebuild
- [ ] **DEPL-02**: Directory resolution: deploy script reads systemd `WorkingDirectory` and deploys THERE
- [ ] **DEPL-03**: Post-start telemetry gate: grep expected log markers (e.g., "StreamManager started") before starting kintsugi
- [ ] **DEPL-04**: Git hash embedding: `vergen` crate emits `env!("VERGEN_GIT_SHA")` in Rust binary, logged at sidecar startup

## v2 Requirements

- **GARD-10**: Prometheus counter for overlap-replaced events (tracks how often the guard fires)
- **HEAL-10**: Overlap self-heal statistics in heartbeat report (repairs triggered, symbols affected)
- **DEPL-10**: Automated deploy script that encapsulates the full Stop→Verify→Deploy→Start→Verify cycle

## Out of Scope

| Feature                       | Reason                                     |
| ----------------------------- | ------------------------------------------ |
| Kintsugi changes              | Writer ownership model is stable           |
| Heartbeat repair triggers     | Detection only, writer ownership violation |
| Asclepius reactivation        | Permanently disabled (#284)                |
| New overlap detection queries | Existing Stathera query is sufficient      |

## Traceability

| Requirement | Phase                               | Status  |
| ----------- | ----------------------------------- | ------- |
| GARD-01     | Phase 1 — Auto-Delete+Rewrite Guard | Pending |
| GARD-02     | Phase 1 — Auto-Delete+Rewrite Guard | Pending |
| GARD-03     | Phase 1 — Auto-Delete+Rewrite Guard | Pending |
| HEAL-01     | Phase 2 — Sidecar Overlap Self-Heal | Pending |
| HEAL-02     | Phase 2 — Sidecar Overlap Self-Heal | Pending |
| HEAL-03     | Phase 2 — Sidecar Overlap Self-Heal | Pending |
| HEAL-04     | Phase 2 — Sidecar Overlap Self-Heal | Pending |
| HEAL-05     | Phase 2 — Sidecar Overlap Self-Heal | Pending |
| HEAL-06     | Phase 2 — Sidecar Overlap Self-Heal | Pending |
| DEPL-01     | Phase 3 — Deploy Hardening          | Pending |
| DEPL-02     | Phase 3 — Deploy Hardening          | Pending |
| DEPL-03     | Phase 3 — Deploy Hardening          | Pending |
| DEPL-04     | Phase 3 — Deploy Hardening          | Pending |

**Coverage:**

- v1 requirements: 13 total
- Mapped to phases: 13/13
- Unmapped: 0

---

_Requirements defined: 2026-03-19_
