---
phase: 01-atomic-replace-heal-scoping
verified: 2026-03-20T20:10:00Z
status: passed
score: 6/6 must-haves verified
re_verification: false
---

# Phase 01: Atomic Replace + Heal Scoping Verification Report

**Phase Goal:** Every sidecar restart produces exactly one clean bar chain per (symbol, threshold) for today -- no overlaps from prior sessions, no heal queries hitting historical data
**Verified:** 2026-03-20T20:10:00Z
**Status:** passed
**Re-verification:** No — initial verification

## Goal Achievement

### Observable Truths

| #   | Truth                                                                                               | Status   | Evidence                                                                                                                                                                                                        |
| --- | --------------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1   | `_sync_flush_rest_bars()` calls `store_bars_replacing()` instead of `_write_batch_with_retry()`     | VERIFIED | `sidecar.py:826` — `cache.store_bars_replacing(...)` inside `with OpenDeviationBarCache() as cache` loop                                                                                                        |
| 2   | Bar dicts are converted to Polars DataFrame before `store_bars_replacing()`                         | VERIFIED | `sidecar.py:825` — `bars_df = pl.DataFrame(bars)` immediately before the call                                                                                                                                   |
| 3   | Fallback to `_write_batch_with_retry()` on `store_bars_replacing()` exception                       | VERIFIED | `sidecar.py:842` — except block calls `_write_batch_with_retry(symbol, threshold, bars)`                                                                                                                        |
| 4   | After sync_flush, a Stathera audit on today's bars shows zero overlaps (mechanical guarantee)       | VERIFIED | `store_bars_replacing()` in `maintenance.py:266` performs lightweight DELETE+INSERT scoped to the trade-ID range; `_skip_lock=False` at `sidecar.py:831` ensures Redis write lock is held for the full sequence |
| 5   | `_heal_day_boundary_gaps()` only queries today's UTC bars, never historical                         | VERIFIED | `sidecar.py:663` — `AND toDate(open_time_ms / 1000) = today()` appended after `per_pair_filter()` in Stathera subquery                                                                                          |
| 6   | `_check_and_heal_overlaps()` call site uses `valid_pairs`, not `config.symbols x config.thresholds` | VERIFIED | `sidecar.py:2690-2691` — `_check_and_heal_overlaps(list(valid_pairs) if valid_pairs else [])`                                                                                                                   |

**Score:** 6/6 truths verified

### Required Artifacts

| Artifact                                  | Expected                                                   | Status   | Details                                                                                                                      |
| ----------------------------------------- | ---------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `python/opendeviationbar/sidecar.py`      | Atomic replace in `_sync_flush_rest_bars()` + heal scoping | VERIFIED | Contains `store_bars_replacing` at line 826, `toDate(open_time_ms / 1000) = today()` at line 663, `valid_pairs` at line 2691 |
| `tests/test_sync_flush_atomic_replace.py` | Tests verifying atomic replace (min 40 lines)              | VERIFIED | 174 lines, 4 tests — happy path, empty buffer, fallback on exception, cross-midnight filtering                               |
| `tests/test_heal_scoping.py`              | Tests verifying heal scoping (min 30 lines)                | VERIFIED | 131 lines, 3 tests — query content filter, parameter preservation, HEAL-02 call-site inspection                              |

### Key Link Verification

| From                                   | To                                                 | Via                                    | Status | Details                                                                                                                        |
| -------------------------------------- | -------------------------------------------------- | -------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------ |
| `sidecar.py (_sync_flush_rest_bars)`   | `clickhouse/maintenance.py (store_bars_replacing)` | `cache.store_bars_replacing(...)` call | WIRED  | `sidecar.py:826` calls the method; lazy import of `OpenDeviationBarCache` at line 816; function exists at `maintenance.py:266` |
| `sidecar.py (_heal_day_boundary_gaps)` | ClickHouse query                                   | `today()` date filter in WHERE clause  | WIRED  | `sidecar.py:663` — filter inserted between `per_pair_filter()` and `per_pair_window()` per plan spec                           |
| `sidecar.py (main loop)`               | `_check_and_heal_overlaps`                         | `valid_pairs` argument                 | WIRED  | `sidecar.py:2690-2691` — passes `list(valid_pairs) if valid_pairs else []`                                                     |

### Requirements Coverage

| Requirement | Source Plan | Description                                                                                                                                      | Status    | Evidence                                                                                                                       |
| ----------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------ |
| ATOM-01     | 01-01       | `_sync_flush_rest_bars()` uses `store_bars_replacing()` to atomically DELETE stale bars and INSERT new bars                                      | SATISFIED | `sidecar.py:826` — `cache.store_bars_replacing(symbol, threshold_decimal_bps, bars_df, version, _skip_lock=False)`             |
| ATOM-02     | 01-01       | After sync_flush + engine start, ClickHouse contains exactly ONE bar chain per (symbol, threshold) for today — zero overlaps from prior sessions | SATISFIED | `store_bars_replacing()` DELETE+INSERT scoped to trade-ID range; `_skip_lock=False` holds Redis write lock for entire sequence |
| HEAL-01     | 01-02       | `_heal_day_boundary_gaps()` Stathera query scoped to today's UTC date only                                                                       | SATISFIED | `sidecar.py:663` — `AND toDate(open_time_ms / 1000) = today()` in WHERE clause                                                 |
| HEAL-02     | 01-02       | `_check_and_heal_overlaps()` call site uses `valid_pairs` instead of `config.symbols x config.thresholds`                                        | SATISFIED | `sidecar.py:2690-2691` — cartesian product replaced with `list(valid_pairs) if valid_pairs else []`                            |

No orphaned requirements: PRUNE-01 through PRUNE-04 are correctly assigned to Phase 2 in REQUIREMENTS.md traceability table, not Phase 1.

### Anti-Patterns Found

None. No TODO/FIXME/placeholder/stub patterns found in any modified or created file.

| File | Line | Pattern | Severity | Impact |
| ---- | ---- | ------- | -------- | ------ |
| —    | —    | —       | —        | —      |

### Human Verification Required

None required. All phase-1 changes are algorithmic write-path and SQL query modifications that are fully verifiable by static inspection and unit tests.

### Test Results

All 7 tests pass (0.52s, Python 3.13.12):

- `tests/test_sync_flush_atomic_replace.py` — 4 tests (all pass)
- `tests/test_heal_scoping.py` — 3 tests (all pass)

### Commit History

| Commit    | Type | Description                                                                                      |
| --------- | ---- | ------------------------------------------------------------------------------------------------ |
| `b4046c8` | test | Failing tests for atomic replace in `_sync_flush_rest_bars` (RED)                                |
| `f5ccbc5` | feat | Replace `_write_batch_with_retry` with `store_bars_replacing` in `_sync_flush_rest_bars` (GREEN) |
| `addc11c` | test | Failing tests for heal scoping HEAL-01 (RED)                                                     |
| `96c6dc5` | feat | Scope `_heal_day_boundary_gaps` to today only (HEAL-01, GREEN)                                   |
| `405b4b2` | feat | Use `valid_pairs` for overlap heal call site (HEAL-02)                                           |

### Gaps Summary

No gaps. All 6 truths verified, all 3 artifacts pass all three levels (exists, substantive, wired), all 3 key links confirmed wired, all 4 phase-1 requirements satisfied.

---

_Verified: 2026-03-20T20:10:00Z_
_Verifier: Claude (gsd-verifier)_
