# Requirements: opendeviationbar-py v10.0

**Defined:** 2026-03-30
**Core Value:** Clean API surface — structured types replace parameter soup, breaking changes done once in a major version

## Goal

Two breaking refactors: extract BarKey dataclass (#337) and consolidate boolean params into option objects (#338). Both identified by PMD CPD clone detection + refactoring guide scan.

## Requirements

### BARKEY: Extract BarKey Dataclass (#337)

| ID        | Requirement                                                                                   | Priority |
| --------- | --------------------------------------------------------------------------------------------- | -------- |
| BARKEY-01 | Create frozen `BarKey(symbol, threshold_decimal_bps, ouroboros_mode)` dataclass in `types.py` | P0       |
| BARKEY-02 | Update 27 ClickHouse layer functions to accept `BarKey`                                       | P0       |
| BARKEY-03 | Update 10 orchestration layer functions to construct/pass `BarKey`                            | P0       |
| BARKEY-04 | Add `bar_key` property to kintsugi `Shard` dataclass                                          | P1       |
| BARKEY-05 | All existing tests pass (expand-contract migration)                                           | P0       |

### OPTS: Boolean Parameter Consolidation (#338)

| ID      | Requirement                                                                     | Priority |
| ------- | ------------------------------------------------------------------------------- | -------- |
| OPTS-01 | Create `ProcessingOptions` dataclass (5 bool fields, matching current defaults) | P0       |
| OPTS-02 | Create `CacheOptions` dataclass (4 bool fields, matching current defaults)      | P0       |
| OPTS-03 | Update `get_open_deviation_bars()` to accept option objects                     | P0       |
| OPTS-04 | Update `get_n_open_deviation_bars()` and `get_open_deviation_bars_pandas()`     | P0       |
| OPTS-05 | Update `.pyi` type stubs                                                        | P0       |

### CLEANUP: Migration Completion

| ID         | Requirement                                         | Priority |
| ---------- | --------------------------------------------------- | -------- |
| CLEANUP-01 | Remove deprecated individual-param signatures       | P0       |
| CLEANUP-02 | Update CLAUDE.md and API docs                       | P1       |
| CLEANUP-03 | Bump to v10.0.0 (major version for breaking change) | P0       |

## Success Criteria

- Zero test regressions
- `ruff check` + `cargo clippy` clean
- Data clump clone (63-line/167-token) eliminated from PMD CPD scan
- Public API uses structured types
