# Phase 35: Dead-Letter Resilience - Context

**Gathered:** 2026-03-29
**Status:** Ready for planning
**Mode:** Auto-generated (infrastructure phase — discuss skipped)

<domain>
## Phase Boundary

When ClickHouse is unreachable or the flush thread falls behind, bars are serialized to Parquet dead-letter files that Python's Charon can replay without modification.

Requirements: RESIL-01 through RESIL-05

</domain>

<decisions>
## Implementation Decisions

### Claude's Discretion

All implementation choices are at Claude's discretion — pure infrastructure phase. Use ROADMAP phase goal, success criteria, and codebase conventions to guide decisions.

Key guidance from research:

- Dead-letter directory: `/tmp/opendeviationbar-dead-letter/`
- Filename pattern: `{symbol}_{threshold}_{timestamp}.parquet`
- Use `parquet` crate (arrow-rs ecosystem, version 58) for Parquet serialization
- Dead-letter schema must match Python Charon replay expectations
- Niffler immediate replay pattern: scan dead-letter dir on flush thread recovery
- Backpressure: on_bar() already returns SinkError::Recoverable on channel full — extend to dead-letter overflow bars
- Cross-language round-trip test: Rust writes Parquet, Python reads via polars/pyarrow

</decisions>

<code_context>

## Existing Code Insights

### Reusable Assets

- `ClickHouseBarRow` from Phase 34 — all fields already mapped
- `ClickHouseWriterSink` with bounded SyncSender channel
- `flush_thread.rs` with `do_flush()` and `FlushCommand` enum
- Python `dead_letter.py` — reference implementation for naming/schema
- Python `replay_dead_letters()` — Charon replay function

### Established Patterns

- FlushCommand enum for thread control (Bars, Flush, Shutdown)
- SinkError::Recoverable for non-fatal failures
- Parquet serialization via arrow-rs ecosystem

### Integration Points

- `flush_thread.rs` — add dead-letter on flush failure
- `sink.rs` — extend backpressure handling to dead-letter
- Python `dead_letter.py` — schema compatibility target
- Python `kintsugi/` — Charon replay consumer

</code_context>

<specifics>
## Specific Ideas

No specific requirements — infrastructure phase. Refer to ROADMAP phase description and success criteria.

</specifics>

<deferred>
## Deferred Ideas

None — infrastructure phase.

</deferred>
