# Roadmap: opendeviationbar-py v10.0

## Milestone: v10.0 API Refactoring (#337, #338)

**Goal:** Clean API surface — structured types replace parameter soup.
**Breaking:** Yes — major version bump required.

## Phases

### Phase 39: BarKey Dataclass + ClickHouse Layer (BARKEY-01, BARKEY-02, BARKEY-05)

**Goal:** Create `BarKey` type and migrate all 27 ClickHouse layer functions.

**Scope:**

- Create `python/opendeviationbar/types.py` with frozen `BarKey` dataclass
- Update `clickhouse/bulk_operations.py` (6 functions)
- Update `clickhouse/query_operations.py` (6 functions)
- Update `clickhouse/maintenance.py` (6 functions)
- Update `clickhouse/bar_count_api.py` (3 functions)
- Update `clickhouse/checkpoint_operations.py` (4 functions)
- Update `clickhouse/cache.py` (1 function)
- Update `clickhouse/write_lock.py` (1 function)
- Expand-contract: accept both `BarKey` and individual params during transition

**Requirements:** BARKEY-01, BARKEY-02, BARKEY-05
**Estimated complexity:** Medium (27 functions, mechanical update)

Plans:

- [x] 39-01-PLAN.md — BarKey dataclass + 27 ClickHouse function expand-contract

### Phase 40: Orchestration Layer + Kintsugi (BARKEY-03, BARKEY-04)

**Goal:** Propagate `BarKey` to orchestration and kintsugi callers.

**Scope:**

- Update `orchestration/open_deviation_bars.py` (2 functions)
- Update `orchestration/count_bounded.py` (1 function)
- Update `orchestration/precompute.py` (1 function)
- Update `orchestration/open_deviation_bars_cache.py` (4 functions)
- Update `orchestration/helpers.py` (2 functions)
- Add `bar_key` property to `kintsugi/discovery.py::Shard`
- Remove deprecated individual-param paths from ClickHouse layer

**Requirements:** BARKEY-03, BARKEY-04
**Depends on:** Phase 39
**Plans:** 1 plan

Plans:

- [ ] 40-01-PLAN.md — Orchestration BarKey propagation + Shard.bar_key + CH cleanup

### Phase 40.1: Kintsugi 3-Bar Merge for Writer-Boundary Orphans (#339)

**Goal:** Fix misclassification of writer-boundary orphans as `forming_boundary`.

**Problem:** When gap trades produce 0 bars with a fresh processor, kintsugi permanently dismisses them. But a continuous processor (carrying forming bar from the left bar) WOULD produce bars because the cumulative deviation through the gap into the right bar exceeds the threshold.

**Scope:**

- `python/opendeviationbar/kintsugi/repair.py` — when `trades_df.is_empty()` after TID filter AND it's an interior shard, attempt 3-bar merge: widen range to `[left_bar.first_tid, right_bar.last_tid]`, reprocess as single continuous run
- DELETE both flanking bars + any bars in between, INSERT reprocessed result
- Only attempt when `left_bar.version != right_bar.version` (different writers) OR when cumulative deviation from forming open to right bar's extreme exceeds threshold
- Purge stale `forming_boundary` entries from `kintsugi_log` for the healed shards

**Requirements:** #339 (data integrity bug)
**Depends on:** Phase 40
**Estimated complexity:** Medium (focused change in repair.py, but careful edge case handling)

### Phase 41: Option Objects + Public API (OPTS-01..05)

**Goal:** Consolidate boolean params into `ProcessingOptions` and `CacheOptions`.

**Scope:**

- Create `ProcessingOptions` and `CacheOptions` dataclasses in `types.py`
- Update `get_open_deviation_bars()` signature
- Update `get_n_open_deviation_bars()` signature
- Update `get_open_deviation_bars_pandas()` signature
- Update all `.pyi` type stubs
- Update `__init__.py` re-exports

**Requirements:** OPTS-01..05
**Depends on:** Phase 40.1

### Phase 42: Cleanup + Ship (CLEANUP-01..03)

**Goal:** Remove deprecated paths, update docs, release v10.0.0.

**Scope:**

- Remove all backward-compat shims (individual params, old signatures)
- Update CLAUDE.md hub + spoke docs with new patterns
- Update `docs/api/` with BarKey and option object usage
- Run full PMD CPD scan to verify data clump eliminated
- Semantic release v10.0.0

**Requirements:** CLEANUP-01..03
**Depends on:** Phase 41

## Coverage Matrix

| Requirement | Phase  |
| ----------- | ------ |
| BARKEY-01   | 39     |
| BARKEY-02   | 39     |
| BARKEY-03   | 40     |
| BARKEY-04   | 40     |
| BARKEY-05   | 39, 40 |
| OPTS-01     | 41     |
| OPTS-02     | 41     |
| OPTS-03     | 41     |
| OPTS-04     | 41     |
| OPTS-05     | 41     |
| CLEANUP-01  | 42     |
| CLEANUP-02  | 42     |
| CLEANUP-03  | 42     |
