---
phase: 01-atomic-replace-heal-scoping
plan: 02
subsystem: streaming
tags: [clickhouse, heal-scoping, sidecar, stathera, today-guard]

requires:
  - phase: 01-01
    provides: "Atomic replace in _sync_flush_rest_bars() via store_bars_replacing()"
provides:
  - "Today-only scoping for _heal_day_boundary_gaps() Stathera query"
  - "valid_pairs-based overlap heal call site (no cartesian product)"
  - "Tests verifying heal scoping (3 tests)"
affects: [legacy-pruning]

tech-stack:
  added: []
  patterns:
    - "toDate(open_time_ms / 1000) = today() filter for sidecar heal queries"
    - "valid_pairs passthrough to _check_and_heal_overlaps instead of config.symbols x config.thresholds"

key-files:
  created:
    - tests/test_heal_scoping.py
  modified:
    - python/opendeviationbar/sidecar.py

key-decisions:
  - "Source-level inspection test for HEAL-02 (grep-style, not mock-based) since call site is deep in event loop"

patterns-established:
  - "Heal operations scoped to today only (kintsugi owns history)"
  - "All sidecar heal/overlap call sites pass valid_pairs, not cartesian product"

requirements-completed: [HEAL-01, HEAL-02]

duration: 2min
completed: 2026-03-20
---

# Phase 01 Plan 02: Heal Scoping Summary

**Today-only date filter on \_heal_day_boundary_gaps() Stathera query and valid_pairs passthrough for overlap heal call site**

## Performance

- **Duration:** 2 min
- **Started:** 2026-03-20T19:42:16Z
- **Completed:** 2026-03-20T19:44:14Z
- **Tasks:** 2 (Task 1: TDD RED->GREEN, Task 2: auto)
- **Files modified:** 2

## Accomplishments

- \_heal_day_boundary_gaps() Stathera query now includes `AND toDate(open_time_ms / 1000) = today()` -- historical bars excluded from heal detection
- \_check_and_heal_overlaps() call site replaced cartesian product (config.symbols x config.thresholds) with valid_pairs
- 3 tests verify both scoping changes: query content, parameter preservation, and source-level call site inspection

## Task Commits

Each task was committed atomically:

1. **Task 1 (RED): Failing tests for heal query scoping** - `addc11c` (test)
2. **Task 1 (GREEN): Add today() filter to Stathera query** - `96c6dc5` (feat)
3. **Task 2: Replace cartesian product with valid_pairs** - `405b4b2` (feat)

## Files Created/Modified

- `tests/test_heal_scoping.py` - 3 tests verifying heal scoping (HEAL-01 query filter + HEAL-02 call site)
- `python/opendeviationbar/sidecar.py` - Today-only filter in \_heal_day_boundary_gaps, valid_pairs in overlap heal

## Decisions Made

- Used source-level inspection test (inspect.getsource + regex) for HEAL-02 since the \_check_and_heal_overlaps call site is deep in the event loop and would require extensive mock setup to unit test directly

## Deviations from Plan

None - plan executed exactly as written.

## Issues Encountered

None.

## User Setup Required

None - no external service configuration required.

## Next Phase Readiness

- Phase 01 complete (both plans 01 and 02 done)
- Phase 02 (legacy pruning) can proceed -- heal operations now correctly scoped to today and valid pairs
- Writer ownership model (#280) fully enforced: sidecar heals today only, kintsugi owns history

---

_Phase: 01-atomic-replace-heal-scoping_
_Completed: 2026-03-20_
