# Phase 1: Modularize long files: live_engine.rs, checkpoint.py, backfill.py - Context

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

<domain>
## Phase Boundary

Modularize the 3 longest files in the codebase for maintainability without any behavioral changes:

1. **live_engine.rs** (2,436 lines) — Extract types, trade dispatch, puck gap-fill, and symbol_task into submodules
2. **checkpoint.py** (2,188 lines) — Split into checkpoint/ package with models, storage, and engine submodules
3. **backfill.py** (1,423 lines) — Extract bar rectification, memory guard, and Vision negative cache

Regression-free: all public symbols re-exported, all existing tests pass unchanged, no behavioral changes.

</domain>

<decisions>
## Implementation Decisions

### Claude's Discretion

All implementation choices are at Claude's discretion — pure infrastructure phase. Key constraints:

- Re-export all public symbols from original module paths (backward compatibility)
- No behavioral changes — pure code movement
- All existing tests must pass without modification
- Follow existing modularization patterns (interbar.rs → interbar_types.rs/interbar_math/ precedent for Rust; sidecar/ package precedent for Python)

</decisions>

<code_context>

## Existing Code Insights

### Reusable Assets

- Rust: `interbar.rs` already extracted to `interbar_types.rs`, `interbar_math/`, `interbar_cache.rs` — proven pattern for module extraction
- Python: `sidecar/` already converted from monolith `sidecar.py` to package with `__init__.py`, `midnight.py` — proven pattern for Python package conversion
- Python: `orchestration/` is a package with `helpers.py`, `count_bounded.py`, `open_deviation_bars.py`

### Established Patterns

- Rust: sibling modules in same crate directory, re-exported via `mod` + `pub use` in parent
- Python: package with `__init__.py` re-exporting all public symbols for backward compatibility
- Python: `.pyi` stub files exist for `checkpoint.py` and `backfill.py` — may need updating

### Integration Points

- `live_engine.rs`: imported by `streaming_bindings.rs` (PyO3), `stream_manager.rs`, tests
- `checkpoint.py`: imported by `orchestration/`, `backfill.py`, `sidecar/`, CLI scripts
- `backfill.py`: imported by `kintsugi/`, CLI scripts, `sidecar_api.py`

</code_context>

<specifics>
## Specific Ideas

No specific requirements — infrastructure phase. Follow the split plans identified in the analysis:

**live_engine.rs splits:**

- `types.rs` — CompletedBar, FormingBar, LiveEngineMetrics, LiveEngineMetricsSnapshot, LiveEngineConfig (~200L)
- `trade_dispatch.rs` — process_trade_through_processors(), maybe_reset_at_midnight() (~130L)
- `puck.rs` — puck_fill() (~150L)
- `symbol_task.rs` — symbol_task() (~425L)

**checkpoint.py splits:**

- `checkpoint/models.py` — PopulationContext, PopulationCheckpoint (~220L)
- `checkpoint/storage.py` — checkpoint path, CH load/save, provenance (~160L)
- `checkpoint/engine.py` — \_process_day, \_process_day_multi_threshold, \_write_bars (~500L)
- `checkpoint/__init__.py` — public orchestrators + re-exports (~1200L)

**backfill.py splits:**

- `rectify.py` — rectify_recent_bars, \_delete_ghost_bar,\_fetch_trades_for_bar (~320L)
- `memory_guard.py` — \_force_allocator_purge,\_check_memory_watermark (~80L)
- `vision_cache.py` — Redis negative cache for Vision 404s (~50L)

</specifics>

<deferred>
## Deferred Ideas

- interbar.rs (2,654L) and intrabar/features.rs (1,929L) were analyzed but explicitly deferred — interbar has inline tests for pub(crate) access, features.rs has FILE-SIZE-OK marker
- Further splitting of the remaining checkpoint/**init**.py (~1200L) orchestrators into separate files

</deferred>
