---
phase: 02-junction-telemetry-audit-items
plan: "02-02"
subsystem: streaming
tags: [ring-buffer, backpressure, capacity-analysis, fill_from_rest, phase4]

# Dependency graph
requires:
  - phase: 02-junction-telemetry-audit-items
    provides: TELE-05 bars_produced telemetry (Plan 02-01) used to validate estimates

provides:
  - Written analysis of ring buffer capacity vs worst-case bar production rate for 18 symbols × 4 thresholds
  - Recommendation to set OPENDEVIATIONBAR_MAX_PENDING_BARS=100000 before Phase 4

affects:
  - phase4-parallel-fill (must increase OPENDEVIATIONBAR_MAX_PENDING_BARS before enabling)
  - deploy (env var change in opendeviationbar.env)

# Tech tracking
tech-stack:
  added: []
  patterns:
    - "Ring buffer sizing: capacity must cover total bars produced during fill_from_rest, not just steady-state WS throughput"
    - "Python cannot drain ring buffer during synchronous fill_from_rest — all bars accumulate until Python resumes"

key-files:
  created:
    - .planning/phases/02-junction-telemetry-audit-items/RING-BUFFER-ANALYSIS.md
  modified: []

key-decisions:
  - "Recommend OPENDEVIATIONBAR_MAX_PENDING_BARS=100000 for Phase 4 (18-symbol deployment)"
  - "Full-day cold restart of 18 symbols exceeds even 100K capacity (~1.7M bars) — kintsugi:catchup is the correct tool for that case"
  - "10K is sufficient for normal short restarts with 2 symbols but overflows on any extended outage"

patterns-established:
  - "Ring buffer analysis pattern: compute total bars produced during fill_from_rest (not steady-state WS rate)"

requirements-completed:
  - AUDT-01

# Metrics
duration: 2min
completed: "2026-03-19"
---

# Phase 02 Plan 02: Ring Buffer Capacity Analysis Summary

**Ring buffer capacity analysis: 10K default is insufficient for Phase 4 (18-symbol deployment); recommend OPENDEVIATIONBAR_MAX_PENDING_BARS=100000 as prerequisite**

## Performance

- **Duration:** 2 min
- **Started:** 2026-03-19T21:58:20Z
- **Completed:** 2026-03-19T21:59:55Z
- **Tasks:** 1
- **Files modified:** 1

## Accomplishments

- Documented ring buffer drop-on-full semantics (`ConcurrentRingBuffer<CompletedBar>`, `parking_lot::Mutex`)
- Identified critical architectural gap: Python is blocked during synchronous `fill_from_rest()` PyO3 call, so bars accumulate without being drained — the buffer must hold **all** bars from the entire fill
- Computed worst-case bar production: 18 symbols × 4 thresholds, various gap durations (5 min, 1 hour, full day)
- Found 10K is safe for normal 2-symbol short restarts but overflows at ~16× for full-day restart even with 2 symbols
- Provided clear Phase 4 prerequisite: set `OPENDEVIATIONBAR_MAX_PENDING_BARS=100000`

## Task Commits

Each task was committed atomically:

1. **Task 1: Compute worst-case bar production and document analysis (AUDT-01)** - `e53e445` (docs)

**Plan metadata:** _(committed with plan metadata below)_

## Files Created/Modified

- `.planning/phases/02-junction-telemetry-audit-items/RING-BUFFER-ANALYSIS.md` - Full ring buffer capacity analysis: current config, drop semantics, worst-case estimates, production risk table, recommendation

## Decisions Made

- **10K → 100K for Phase 4**: Env var already supported since Issue #96, no code change required
- **Full-day restarts → kintsugi**: Even 100K overflows for full-day cold restart of all 18 symbols (~1.7M bars); correct tool is `kintsugi:catchup`, not `fill_from_rest`
- **Validate with TELE-05**: Real `bars_produced` metrics from Plan 02-01 telemetry will validate these estimates in production

## 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 2 is now complete (both plans have SUMMARY files):

- TELE-01..05 and AUDT-01..05 all complete
- Phase 3 (Rate Limiter Ceiling, PARA-03) is ready to begin
- **Phase 4 prerequisite documented**: `OPENDEVIATIONBAR_MAX_PENDING_BARS=100000` must be set in `deploy/opendeviationbar.env` before enabling 18-symbol streaming

---

_Phase: 02-junction-telemetry-audit-items_
_Completed: 2026-03-19_
