---
phase: 13-registry-mode-enum
plan: 02
type: execute
wave: 2
depends_on: ["13-01"]
files_modified:
  - python/opendeviationbar/orchestration/open_deviation_bars.py
  - python/opendeviationbar/orchestration/open_deviation_bars.pyi
  - python/opendeviationbar/orchestration/count_bounded.py
  - python/opendeviationbar/orchestration/precompute.py
  - python/opendeviationbar/checkpoint/__init__.py
  - python/opendeviationbar/checkpoint/__init__.pyi
autonomous: true
requirements: [REG-04]

must_haves:
  truths:
    - "get_open_deviation_bars('BTCUSDT', ..., ouroboros_mode='aion') accepts without error"
    - "get_n_open_deviation_bars('BTCUSDT', ..., ouroboros_mode='aion') accepts without error"
    - "populate_cache_resumable('BTCUSDT', ..., ouroboros_mode='aion') accepts without error"
    - "precompute_open_deviation_bars('BTCUSDT', ..., ouroboros_mode='aion') accepts without error"
    - "Type stubs reflect Literal['day', 'aion'] for all ouroboros_mode parameters"
  artifacts:
    - path: "python/opendeviationbar/orchestration/open_deviation_bars.py"
      provides: "get_open_deviation_bars with expanded ouroboros_mode type"
      contains: 'Literal["day", "aion"]'
    - path: "python/opendeviationbar/orchestration/open_deviation_bars.pyi"
      provides: "Type stubs with Literal['day', 'aion']"
      contains: 'Literal["day", "aion"]'
    - path: "python/opendeviationbar/checkpoint/__init__.pyi"
      provides: "populate_cache_resumable stubs with Literal['day', 'aion']"
      contains: 'Literal["day", "aion"]'
  key_links:
    - from: "python/opendeviationbar/orchestration/open_deviation_bars.py"
      to: "python/opendeviationbar/ouroboros.py"
      via: "validate_ouroboros_mode call"
      pattern: "validate_ouroboros_mode"
    - from: "python/opendeviationbar/orchestration/open_deviation_bars.pyi"
      to: "python/opendeviationbar/orchestration/open_deviation_bars.py"
      via: "type stubs match implementation"
      pattern: "Literal.*aion"
---

<objective>
Expand all public Python API function signatures to accept ouroboros_mode="aion" alongside "day".

Purpose: Consumers can pass ouroboros_mode="aion" to any public API function without type errors.
Output: Updated function signatures and type stubs across orchestration and checkpoint modules.
</objective>

<execution_context>
@$HOME/.claude/get-shit-done/workflows/execute-plan.md
@$HOME/.claude/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/13-registry-mode-enum/13-01-SUMMARY.md

@python/opendeviationbar/orchestration/open_deviation_bars.py
@python/opendeviationbar/orchestration/open_deviation_bars.pyi
@python/opendeviationbar/orchestration/count_bounded.py
@python/opendeviationbar/orchestration/precompute.py
@python/opendeviationbar/checkpoint/**init**.py
@python/opendeviationbar/checkpoint/**init**.pyi

<interfaces>
<!-- From Plan 01: OuroborosMode enum now has both variants -->
```python
class OuroborosMode(str, Enum):
    DAY = "day"
    AION = "aion"

def validate_ouroboros_mode(mode: str) -> Literal["day", "aion"]: ...

```

<!-- Current signatures to update (all use Literal["day"]) -->

# orchestration/open_deviation_bars.py line 44:
ouroboros_mode: Literal["day"] | None = None

# orchestration/open_deviation_bars.pyi (3 overloads + impl):
ouroboros: Literal["day"] = ...
ouroboros_mode: Literal["day"] | None = None

# checkpoint/__init__.py line 69:
ouroboros_mode: str | None = None

# checkpoint/__init__.pyi lines 12, 31:
ouroboros_mode: Literal["day"] | None = None
</interfaces>
</context>

<tasks>

<task type="auto">
  <name>Task 1: Expand Literal["day"] to Literal["day", "aion"] in all API signatures and stubs</name>
  <files>
    python/opendeviationbar/orchestration/open_deviation_bars.py,
    python/opendeviationbar/orchestration/open_deviation_bars.pyi,
    python/opendeviationbar/orchestration/count_bounded.py,
    python/opendeviationbar/orchestration/precompute.py,
    python/opendeviationbar/checkpoint/__init__.py,
    python/opendeviationbar/checkpoint/__init__.pyi
  </files>
  <read_first>
    - python/opendeviationbar/orchestration/open_deviation_bars.py
    - python/opendeviationbar/orchestration/open_deviation_bars.pyi
    - python/opendeviationbar/orchestration/count_bounded.py
    - python/opendeviationbar/orchestration/precompute.py
    - python/opendeviationbar/checkpoint/__init__.py
    - python/opendeviationbar/checkpoint/__init__.pyi
  </read_first>
  <action>
    Systematic find-and-replace across 6 files. For each file:

    1. **orchestration/open_deviation_bars.py** (line ~44):
       - Change `ouroboros_mode: Literal["day"] | None = None` to `ouroboros_mode: Literal["day", "aion"] | None = None`
       - Update docstring for ouroboros_mode parameter: `ouroboros_mode : {"day", "aion"}, default=None (resolved from config)`

    2. **orchestration/open_deviation_bars.pyi** (lines ~16, ~44, ~71):
       - Change ALL occurrences of `Literal["day"]` related to ouroboros to `Literal["day", "aion"]`
       - The file has 2 overloads with `ouroboros: Literal["day"]` and 1 impl with `ouroboros_mode: Literal["day"] | None`
       - Update all 3 to use `Literal["day", "aion"]`

    3. **orchestration/count_bounded.py** (line ~69):
       - `ouroboros_mode: str | None = None` — this is already `str` so no Literal change needed
       - But if there's a docstring saying "day", update it to say "day" or "aion"

    4. **orchestration/precompute.py** (line ~74):
       - `ouroboros_mode: str | None = None` — already `str`, same treatment as count_bounded
       - Update docstring if present

    5. **checkpoint/__init__.py** (line ~69):
       - `ouroboros_mode: str | None = None` — already `str`, update docstring

    6. **checkpoint/__init__.pyi** (lines ~12, ~31):
       - Change `ouroboros_mode: Literal["day"] | None = None` to `ouroboros_mode: Literal["day", "aion"] | None = None`
       - Apply to both `populate_cache_resumable` and `populate_cache_multi_threshold` stubs

    Do NOT modify any function bodies — only type annotations and docstrings. The runtime behavior change (accepting "aion") was already done in Plan 01 via validate_ouroboros_mode().
  </action>
  <verify>
    <automated>cd /Users/terryli/eon/opendeviationbar-py && uv run --python 3.13 python -c "
from opendeviationbar.orchestration.open_deviation_bars import get_open_deviation_bars
import inspect
sig = inspect.signature(get_open_deviation_bars)
p = sig.parameters['ouroboros_mode']
ann = str(p.annotation)
assert 'aion' in ann, f'ouroboros_mode annotation missing aion: {ann}'
print(f'OK: ouroboros_mode annotation = {ann}')
" 2>&1</automated>
  </verify>
  <acceptance_criteria>
    - grep -q 'Literal\["day", "aion"\]' python/opendeviationbar/orchestration/open_deviation_bars.py
    - grep -c 'Literal\["day", "aion"\]' python/opendeviationbar/orchestration/open_deviation_bars.pyi returns at least 3
    - grep -q 'Literal\["day", "aion"\]' python/opendeviationbar/checkpoint/__init__.pyi
    - No remaining solo Literal["day"] related to ouroboros in modified files (grep -c 'ouroboros.*Literal\["day"\]' should be 0)
  </acceptance_criteria>
  <done>All public API signatures and type stubs accept ouroboros_mode="aion", backward compatible with "day" default, no runtime behavior changes in this plan</done>
</task>

</tasks>

<verification>
1. Type check: `grep -rn 'Literal\["day"\]' python/opendeviationbar/orchestration/open_deviation_bars.pyi python/opendeviationbar/checkpoint/__init__.pyi` should return 0 ouroboros-related matches
2. Smoke test: `uv run --python 3.13 python -c "from opendeviationbar import get_open_deviation_bars; import inspect; print(inspect.signature(get_open_deviation_bars))"`
3. Full test suite: `uv run --python 3.13 pytest tests/ -x -q --tb=short 2>&1 | tail -10`
</verification>

<success_criteria>
- All public API signatures accept Literal["day", "aion"] for ouroboros_mode
- Type stubs (.pyi files) match implementation signatures
- All existing tests still pass (no behavioral changes in this plan)
- Default remains "day" everywhere (backward compatible)
</success_criteria>

<output>
After completion, create `.planning/phases/13-registry-mode-enum/13-02-SUMMARY.md`
</output>
```
