# BAT-025 Planning

## Objective

REQ-057의 명시 Alembic migration과 운영 runbook을 구현·검증한다. BAT-024의 API 계약과 Implemented 상태는 변경하지 않는다.

## Delivery sequence

1. **Preflight** — `uv run alembic heads`, `uv run alembic history`, revision graph 및 `ensure_schema()` DDL 소유 경계를 확인하고 실제 head를 evidence로 고정한다.
2. **Migration** — 실제 head를 parent로 하는 신규 revision을 작성한다. fresh/기존/runtime-precreated schema에서 중복 DDL 없이 네 컬럼, source backfill, NOT NULL/default를 보장한다.
3. **Runtime compatibility** — `ensure_schema()` 선행 생성 경로와 Alembic version tracking의 상호작용을 테스트한다. 임의 stamp는 schema/version evidence와 승인된 절차 없이 사용하지 않는다.
4. **Regression tests** — 기존 broker ledger write, manual ledger API, row/data preservation, schema metadata/current 정합을 검증한다.
5. **Runbook** — backup, current, schema/row count, active query/lock, upgrade, post-check, smoke, 실패 대응 및 forward-only recovery를 문서화하고 dry-run 검토한다.
6. **Independent QC** — dev-qc가 committed diff를 직접 검토하고 표준 테스트 및 migration-focused 테스트를 재실행한다.

## Work packets

### WP-1: Batch artifacts (lead)

- 이 문서와 `design.md`, `index.md`를 confirmed 상태로 작성한다.
- `docs/batches/index.md`에 BAT-025를 `confirmed`로 등록한다.
- local main에 docs-only commit을 남긴다.

### WP-2: Implementation (dev-impl)

- 신규 Alembic revision, 필요한 runtime compatibility 수정, tests, `docs/runbooks/` runbook을 작성한다.
- implementation log와 실행 명령/결과를 기록하고 implementation commit을 반환한다.
- 운영 DB나 서비스 activation은 실행하지 않는다.

### WP-3: QC (dev-qc)

- dev-impl committed diff와 문서/REQ 정합성을 독립 검토한다.
- `uv run pytest` 및 가능한 migration-focused checks를 재실행한다.
- blocker가 있으면 PASS가 아닌 명시적 finding으로 반환한다.

## Acceptance evidence targets

- AC-1: head/graph preflight 출력
- AC-2~5: fresh/legacy/runtime-precreated schema upgrade와 source backfill/중복 오류 부재
- AC-6: `alembic current`, information_schema, row count 결과
- AC-7~9: runbook preflight/실패 대응/forward-only recovery 검토 evidence
- AC-10: 운영 실행을 하지 않았다는 scope evidence 및 release gate 기록
- AC-11: implementation + tests + QC committed evidence

## Risks / blockers

- local repository의 schema graph와 runtime-created schema가 서로 다른 시작 상태를 가질 수 있다.
- `ensure_schema()`와 Alembic 양쪽 소유 경계 변경은 기존 broker flow 회귀 위험이 있다.
- 실제 PostgreSQL 운영 DB evidence는 이번 batch 밖이며 M5 Release 승인 없이는 확보하지 않는다.