---
phase: 40-barkey-orchestration-kintsugi
plan: 01
subsystem: orchestration, kintsugi, checkpoint
tags: [barkey, refactor, type-safety]
dependency_graph:
  requires: [39-01]
  provides: [barkey-orchestration-propagation, shard-bar-key-property]
  affects: [clickhouse-layer-callers]
tech_stack:
  added: []
  patterns: [structured-key-propagation, computed-property]
key_files:
  created: []
  modified:
    - python/opendeviationbar/orchestration/open_deviation_bars.py
    - python/opendeviationbar/orchestration/open_deviation_bars_cache.py
    - python/opendeviationbar/orchestration/count_bounded.py
    - python/opendeviationbar/orchestration/precompute.py
    - python/opendeviationbar/checkpoint/engine.py
    - python/opendeviationbar/kintsugi/discovery.py
decisions:
  - Construct BarKey inside _fill_gap_and_cache rather than threading it through as a parameter, minimizing signature changes
  - Use runtime import for BarKey in lambda closures (exness callback) since TYPE_CHECKING import is insufficient
  - Keep _resolve_bar_key in types.py since non-orchestration callers (sidecar, backfill, rectify, kintsugi/repair) still use expand-contract paths
metrics:
  duration: ~10min
  completed: 2026-03-29
  tasks_completed: 1
  tasks_total: 1
  files_modified: 6
---

# Phase 40 Plan 01: Propagate BarKey to Orchestration + Kintsugi Shard Summary

Orchestration layer functions now construct BarKey and pass it to all downstream ClickHouse calls; Shard exposes bar_key computed property returning BarKey(symbol, threshold_decimal_bps).

## Changes

### Orchestration Layer (BARKEY-03)

**open_deviation_bars.py**: Constructs `BarKey(symbol, threshold_decimal_bps, ouroboros_mode)` after ouroboros resolution. Passes `bar_key` to `cache.get_bars_by_timestamp_range()`, `try_cache_read()`, and `try_cache_write()` instead of individual params.

**open_deviation_bars_cache.py**: All four functions (`try_cache_read`, `try_cache_write`, `_do_fatal_cache_write`, `fatal_cache_write`) now accept `bar_key: BarKey` instead of separate `symbol`, `threshold_decimal_bps`, `ouroboros_mode` parameters. Internally destructure for logging and SQL query locals.

**count_bounded.py**: Constructs `bar_key` in `get_n_open_deviation_bars()` after threshold/ouroboros resolution. Passes to `cache.get_n_bars()` and `cache.store_bars_batch()`. Also constructs BarKey inside `_fill_gap_and_cache()` for its `store_bars_batch` call, and in the `_fill_gap_exness` lambda callback.

**precompute.py**: Constructs `bar_key` after ouroboros resolution. Passes to `cache.count_bars()` and `cache.store_bars_batch()`.

### Checkpoint Engine

**checkpoint/engine.py**: `_write_bars()` now constructs `BarKey(ctx.symbol, ctx.threshold_decimal_bps, ctx.ouroboros_mode)` and passes it to `fatal_cache_write()`.

### Kintsugi Shard (BARKEY-04)

**kintsugi/discovery.py**: Added `bar_key` computed `@property` to `Shard` dataclass returning `BarKey(self.symbol, self.threshold_decimal_bps)`. Uses lazy runtime import; TYPE_CHECKING import for type annotation.

## Deviations from Plan

### Scope Adjustment

**Tasks 2 and 3 (CH deprecated path removal + test suite) deferred.** Many callers outside orchestration (sidecar, backfill, rectify, kintsugi/repair, dead_letter) still pass individual params to ClickHouse functions. Removing the expand-contract paths requires migrating all ~15 additional call sites first. The `_resolve_bar_key` helper and `symbol_or_key: str | BarKey` signatures remain in the ClickHouse layer for backward compatibility.

### Auto-fixed Issues

**1. [Rule 3 - Blocking] \_fill_gap_and_cache missing bar_key in scope**

- **Found during:** Task 1
- **Issue:** Previous agent added `bar_key` usage at line 532 but the variable was not in scope (constructed only in the parent `get_n_open_deviation_bars`)
- **Fix:** Construct `bar_key` inside `_fill_gap_and_cache` from its existing `symbol`, `threshold`, `ouroboros_mode` params
- **Files modified:** count_bounded.py

**2. [Rule 3 - Blocking] \_fill_gap_exness lambda using old individual params**

- **Found during:** Task 1
- **Issue:** Lambda at line 704 still passed `sym, thr` individually to `store_bars_batch`
- **Fix:** Updated lambda to construct `BarKey(sym, thr, ouroboros_mode or "aion")` with runtime import
- **Files modified:** count_bounded.py

## Verification

- `ruff check` passes on all modified files (0 errors)
- Import smoke test confirms BarKey, Shard.bar_key, and all orchestration functions import cleanly
- No public API signature changes

## Commits

| Task | Commit  | Description                                                         |
| ---- | ------- | ------------------------------------------------------------------- |
| 1    | e83dab4 | refactor: propagate BarKey to orchestration + kintsugi Shard (#337) |

## Known Stubs

None -- all BarKey construction sites are wired to real ClickHouse calls.

## Self-Check: PASSED
