---
phase: quick
plan: 260321-n48
subsystem: streaming
tags: [clickhouse, sidecar, ring-buffer, heartbeat, diagnostics]

provides:
  - "Synchronous DELETE in _delete_today_bars via mutations_sync=1"
  - "Drain diagnostics logging in _sync_flush_rest_bars"
  - "fill_from_rest ring buffer overflow logging and metrics"
  - "Heartbeat restart diagnostic hint for sidecar uptime < 30min"
affects: [sidecar, heartbeat, streaming]

tech-stack:
  added: []
  patterns: ["mutations_sync=1 for race-free lightweight DELETE"]

key-files:
  created: []
  modified:
    - python/opendeviationbar/sidecar.py
    - crates/opendeviationbar-streaming/src/live_engine.rs
    - scripts/heartbeat/formatter.py

key-decisions:
  - "mutations_sync=1 chosen over application-level sleep/retry for DELETE synchronization"
  - "Drain diagnostics placed before drained==0 early-return to capture all-filtered cases"

requirements-completed: [N48-01, N48-02, N48-03, N48-04]

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

# Quick Task 260321-n48: Fix Async DELETE Race Summary

**Synchronous DELETE via mutations_sync=1 in \_delete_today_bars, plus drain diagnostics, ring buffer overflow logging, and heartbeat restart hints**

## Performance

- **Duration:** 2 min
- **Started:** 2026-03-21T23:42:26Z
- **Completed:** 2026-03-21T23:44:15Z
- **Tasks:** 4
- **Files modified:** 3

## Accomplishments

- Fixed async DELETE race in \_delete_today_bars that caused fill_from_rest bars to vanish after INSERT
- Added drain diagnostics logging (raw/valid/cross_midnight/invalid_pair breakdown) in \_sync_flush_rest_bars
- Both fill_from_rest ring buffer push sites now log warnings and increment dropped_bars on overflow
- Heartbeat formatter shows actionable journalctl command when sidecar uptime is under 30 minutes

## Task Commits

1. **Task 1: Make \_delete_today_bars DELETE synchronous** - `941aabc` (fix)
2. **Task 2: Add diagnostic logging to \_sync_flush_rest_bars** - `b98cfad` (feat)
3. **Task 3: Add overflow logging to fill_from_rest ring buffer pushes** - `33009a9` (fix)
4. **Task 4: Add restart diagnostic hint in heartbeat formatter** - `23afaca` (feat)

## Files Created/Modified

- `python/opendeviationbar/sidecar.py` - mutations_sync=1 on DELETE, drain diagnostics logging
- `crates/opendeviationbar-streaming/src/live_engine.rs` - Ring buffer overflow logging at both push sites
- `scripts/heartbeat/formatter.py` - Restart diagnostic hint with journalctl grep command

## Decisions Made

- Used mutations_sync=1 ClickHouse SETTINGS parameter for synchronous DELETE (simplest, no application-level polling)
- Placed drain diagnostics log before the drained==0 early-return so it captures cases where all bars were filtered

## Deviations from Plan

None - plan executed exactly as written.

## Issues Encountered

None.

## User Setup Required

None - no external service configuration required.

---

_Plan: 260321-n48_
_Completed: 2026-03-21_
