---
phase: 32-historical-gap-cleanup
plan: 01
subsystem: scripts
tags: [pueue, aion, stathera, repair, parquet, bigblack]

requires:
  - phase: none
    provides: repair_direct_parquet.py and detect_gaps.py already exist
provides:
  - Bulk Aion repair orchestration script for bigblack pueue execution
affects: [32-historical-gap-cleanup]

tech-stack:
  added: []
  patterns: [3-stage pipeline: dry-run + execute + audit]

key-files:
  created: [scripts/bulk_aion_repair.sh]
  modified: []

key-decisions:
  - "24 workers matches bigblack optimal capacity (ClickHouse bottleneck at higher values)"
  - "Stathera audit PASS threshold set at <100 gaps (exchange gaps only)"
  - "JSON gap count parsed with python3 inline for portability"

patterns-established:
  - "Pueue batch scripts: dry-run first, execute, then audit with PASS/FAIL"

requirements-completed: [CLEANUP-01]

duration: 3min
completed: 2026-03-28
---

# Phase 32 Plan 01: Bulk Aion Repair Orchestration Summary

**3-stage bash script for bulk Aion repair: dry-run gap scan, parallel reprocessing (24 workers), Stathera audit with PASS/FAIL**

## Performance

- **Duration:** 3 min
- **Started:** 2026-03-28T08:41:03Z
- **Completed:** 2026-03-28T08:44:00Z
- **Tasks:** 1
- **Files modified:** 1

## Accomplishments

- Created `scripts/bulk_aion_repair.sh` orchestration script for bulk Aion repair on bigblack
- Script runs 3 stages: pre-flight dry run, execute with 24 workers, post-repair Stathera audit
- All Python calls use `uv run --python 3.13` per project policy
- Output tee'd to timestamped `/tmp/bulk_aion_repair_YYYYMMDD_HHMMSS.log`
- PASS/FAIL summary based on <100 remaining gaps after repair

## Task Commits

Each task was committed atomically:

1. **Task 1: Create bulk_aion_repair.sh orchestration script** - `b292957` (feat)

## Files Created/Modified

- `scripts/bulk_aion_repair.sh` - 3-stage pueue orchestration: dry-run, execute (--all --execute --workers 24), Stathera audit

## Decisions Made

- Used 24 workers per bigblack capacity envelope (ClickHouse soft cap ~143 qps, contention collapse at 32)
- PASS threshold <100 gaps aligns with plan expectation that remaining gaps are exchange-origin only
- Trap on EXIT for cleanup logging on failure
- Stathera JSON parsing via inline python3 for robust key extraction

## Deviations from Plan

None - plan executed exactly as written.

## Issues Encountered

None

## User Setup Required

None - no external service configuration required.

## Next Phase Readiness

- Script ready to rsync to bigblack and run via `pueue add -- bash scripts/bulk_aion_repair.sh`
- After execution, Stathera audit results determine if additional gap-specific repairs are needed

## Self-Check: PASSED

- FOUND: scripts/bulk_aion_repair.sh
- FOUND: commit b292957

---

_Phase: 32-historical-gap-cleanup_
_Completed: 2026-03-28_
