feat(reset): cutover 도구 폐기 → trex-core-reset(DB 재초기화) 대체 (REQ-064 CHG-20260610-03)

실 DB 점검 중 마이그레이션 009 부분 유니크 인덱스가 legacy 풀 데이터(같은
자산이 closed+재진입 holding 으로 portfolio_id 중복)에 적용 불가 → cutover·
데몬 부팅 모두 차단되는 결함 확인. 데이터 보존 cutover 를 폐기하고 DB wipe +
자산 중심 재초기화로 전환(사용자 결정). 빈 테이블에는 009 인덱스가 정상
생성되고 자산 중심에서 (instance_key, portfolio_id)는 설계상 유일.

- trex_core/runtime/reset.py 신규(trex-core-reset): slot-core 7테이블 wipe +
  apply_migrations 재적용 → 자산 중심 스키마 착지 검증. dry-run 기본/--yes 적용,
  파괴적·DB 전역. 보유 carry-over 없음(재초기화 후 reconcile_core_holdings 재편입).
- runtime/cutover.py + trex-core-cutover console script + test_cutover_rehearsal.py 삭제.
- pyproject: trex-core-reset 등록.
- tests/runtime/test_reset.py 신규 5건(PG-gated): wipe+착지·dry-run 무변경·멱등·
  wipe 후 admission·테이블 커버리지.
- change-req REQ-064 CHG-20260610-03(cutover→재초기화 재정의) + srs index 갱신.
- baseline 4문서(data-model/runtime-flows/project-structure/interface-contract)
  + BAT-030 design/planning/index/implementation/verification 도구 서술 reset 으로 교체.

검증: ruff clean, 단위 367 passed, PG+RabbitMQ 통합 411 passed/1 skip(KIS sandbox).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
2026-06-10 16:08:05 +09:00
co-authored by Claude Opus 4.8
parent 5330f32247
commit c04fd276b3
15 changed files with 335 additions and 405 deletions
@@ -1,4 +1,4 @@
# req-064: 풀 모델 → 영구 자산 슬롯 cutover 마이그레이션
# req-064: 풀 모델 → 자산 중심 DB 재초기화 (구 cutover 마이그레이션)
- Status: Implemented
- Type: Migration
@@ -6,25 +6,26 @@
- Owner: project maintainers
## Intent
- 출시·운영 중인 익명 풀 모델(일일 daily_slot 행) 데이터를 자산 영구 슬롯 모델로 안전하게 이행한다. 라이브 트레이딩 데이터(보유 포지션)를 잃지 않고 cutover 한다. (dcy-020 NFR-2/R-1)
- 익명 풀 모델(일일 daily_slot 행) 데이터베이스를 자산 중심 영구 슬롯 substrate 로 전환한다. **데이터 보존 cutover 는 폐기**(CHG-20260610-03): 마이그레이션 009 의 부분 유니크 인덱스가 legacy 풀 데이터(같은 자산이 closed+재진입 holding 으로 portfolio_id 중복)에 적용 불가한 결함 + dev/페이퍼 컨텍스트로, **DB wipe + 자산 중심 재초기화**로 전환한다. (dcy-020 NFR-2/R-1; 결함 출처는 실 DB 점검 2026-06-10)
## Requirement
- 기존 일일 `daily_slot` 행을 **자산당 영구 1행**으로 전환하고, 현재 보유(holding) 포지션을 새 영구 슬롯으로 **carry-over** 한다. 기존 slot-scoped 행(slot_transition_log/intent_log/ledger_outbox 등)에 `instance_key` 를 태깅한다. cutover 는 거래 세션 외 시간에 수행하고, 롤백 계획(역마이그레이션 또는 스냅샷 복원)을 갖춘다. 단계적 전환(읽기 정합 → 모델 전환)을 우선 검토하고, cutover 전후 보유 포지션·safety-sell 보호가 끊기지 않음을 검증한다.
- `trex-core-reset` 도구로 slot-core 테이블(daily_slot/daily_symbol_entries/slot_transition_log/intent_log/ledger_outbox/snapshot_pause/killswitch_exclusion)을 **wipe** 한 뒤 마이그레이션을 재적용해 DB 가 깨끗한 자산 중심 스키마(009 부분 유니크 인덱스·010 inactive CHECK·011 컬럼 drop)에 착지하게 한다. 빈 테이블에는 인덱스가 정상 생성되고, 자산 중심에서 (instance_key, portfolio_id)는 universe reconcile 가 항상 채우므로 설계상 유일하다. 파괴적·DB 전역이며 dry-run 기본 + `--yes` 적용, 실행 전 백업을 전제로 한다. 보유 포지션 carry-over 는 하지 않으며, 재초기화 후 universe reconcile(REQ-058) + `reconcile_core_holdings`(REQ-062)로 운영자가 재편입한다.
## Acceptance Criteria
1. Given 기존 풀 모델 데이터(보유 N개 포함), When cutover 적용, Then 각 보유 자산이 영구 슬롯 1행(holding)으로 보존되고 수량/임계값 등 보호 컨텍스트가 유실되지 않는다.
2. Given cutover 후, When 데몬 기동, Then universe reconcile(REQ-058)·admission(REQ-059)·safety-sell 이 회귀 없이 동작한다.
3. Given cutover 실패, When 롤백, Then 직전 released 리비전/스키마로 복원 가능하다(롤백 계획 검증).
4. Given slot-scoped 기존 행, When cutover, Then `instance_key` 태깅이 적용되어 인스턴스 스코프 쿼리가 정확하다.
1. Given 기존 풀 모델(또는 임의 상태) DB, When `trex-core-reset --yes`, Then slot-core 테이블이 wipe 되고 `daily_slot` 컬럼셋이 `EXPECTED_SLOT_FIELDS`(자산 중심)와 일치하며 부분 유니크 인덱스·inactive CHECK 가 존재한다.
2. Given 재초기화 후, When 데몬 기동, Then universe reconcile(REQ-058)·admission(REQ-059)·safety-sell 이 회귀 없이 동작한다.
3. Given 안전성, When dry-run 실행, Then 어떤 행도 변경되지 않고 wipe 대상 행수만 보고된다. 재초기화는 멱등이다(2회차도 0행·schema_ok).
4. Given 보유 포지션, When 재초기화(데이터 보존 폐기), Then 보유는 소실되며 재초기화 후 브로커 보유가 `reconcile_core_holdings`(REQ-062)의 unmanaged 경로로 표면화되어 운영자가 재편입한다. 롤백 = 사전 백업 복원.
## Impacted Area
- Docs: docs/runtime-flows.md(cutover 절차), 릴리즈 Rollback Plan
- Modules: trex_core/adapters/persistence/sql/(cutover 마이그레이션), 이행 스크립트
- Tests: tests/adapters/persistence/(cutover round-trip), 회귀 스위트
- Docs: docs/runtime-flows.md(재초기화 절차), 릴리즈 Rollback Plan(백업 복원)
- Modules: trex_core/runtime/reset.py, trex_core/adapters/persistence/sql/(009~011)
- Tests: tests/runtime/test_reset.py(PG-gated), 회귀 스위트
## Notes
- 라이브 데이터 영향 — 배포 게이트·운영자 입회 권장. 실행은 별도 배치(BAT-δ)로 분리하고 confirm-release 전 run-the-app/cutover 리허설 evidence 필요.
- 출처: dcy-020 NFR-2, R-1.
- 라이브 데이터 영향 — 파괴적·DB 전역. 배포 게이트·운영자 입회·**사전 백업 필수**. 실행은 release(REL) 단계 운영자 작업으로 confirm-release 전 백업 evidence 필요.
- 구 cutover 도구(`trex-core-cutover`/`runtime/cutover.py`)는 폐기·삭제(CHG-20260610-03).
- 출처: dcy-020 NFR-2, R-1 + 마이그레이션 009 legacy 충돌 결함.
## Change Log
@@ -86,8 +87,40 @@
#### Validation Plan
- 승인 후 cutover 배치 planning 에서 본 REQ AC 를 검증 기준으로 사용.
### CHG-20260610-03
- Date: 2026-06-10
- Author: Justin Ko
#### Change Summary
- **데이터 보존 cutover → DB 재초기화로 재정의.** BAT-030 구현 중 실 DB 점검에서 마이그레이션 009 부분 유니크 인덱스가 legacy 풀 중복 데이터(같은 portfolio_id 가 closed+holding 2행)에 적용 불가 → cutover·데몬 부팅 모두 차단되는 결함 확인. 사용자 결정으로 데이터 보존 마이그레이션을 폐기하고 `trex-core-reset`(wipe+재초기화)로 대체. 구 `trex-core-cutover` 도구·테스트 삭제.
#### Intent
- 빈 테이블에 자산 중심 스키마를 깨끗이 착지시켜 009 결함을 코드 수정 없이 우회하고, 전환 절차를 단순화(데이터 보존 불요 — dev/페이퍼·신규 인스턴스 컨텍스트).
#### Acceptance Criteria Delta
- Updated: AC-1~4 를 cutover(보유 carry-over/롤백 역마이그레이션) → 재초기화(wipe+스키마 착지/기동 회귀/dry-run·멱등/보유 재편입+백업 복원) 기준으로 재정의
- Removed: 보유 무손실 carry-over, instance_key 태깅(전역 wipe 라 불필요), 역마이그레이션 롤백
#### Impacted Area Delta
- Modules: trex_core/runtime/reset.py(신규), runtime/cutover.py(삭제)
- Tests: tests/runtime/test_reset.py(신규), test_cutover_rehearsal.py(삭제)
- Docs: data-model/runtime-flows/project-structure(도구 서술 교체)
#### Delivery Trace Delta
- Batches: BAT-030
- Releases: none (실 재초기화는 REL 단계)
#### Revalidation Impact
- Reverification Needed: yes (reset 도구 PG 테스트로 충족)
- Existing Implementation Invalidated: yes (cutover 도구 폐기)
- Status Recommendation: keep-current (Implemented — reset evidence 로 대체 충족)
- Follow-up Action: 실 DB 재초기화는 REL 단계 운영자(백업 선행).
#### Validation Plan
- tests/runtime/test_reset.py(wipe+스키마 착지·dry-run·멱등·재편입 가능) + run-the-app e2e.
### CHG-20260610-IMPL
- Date: 2026-06-10
- Author: Justin Ko
- Type: status
- Summary: Approved → Implemented (confirm-req-implemented). 근거: BAT-030(cutover 도구+PG 리허설 8건; 실 cutover 는 REL 운영자) — 모든 AC 가 release-candidate 배치 verification 의 evidence 와 연결됨(단위 367/PG 29/MQ 21 passed + run-the-app 자산 중심 e2e). Blocking Issues 없음.
- Summary: Approved → Implemented (confirm-req-implemented), 이후 CHG-20260610-03 으로 재정의 반영. 근거: BAT-030(`trex-core-reset` 도구 + PG reset 테스트 5건; 실 재초기화는 REL 운영자) — 재정의 AC 가 release-candidate 배치 verification 의 evidence 와 연결됨(단위 367/PG 26/MQ 21 passed + run-the-app 자산 중심 e2e). Blocking Issues 없음.
+2 -1
View File
@@ -144,7 +144,7 @@
| REQ-061 | intent 계약 자산(portfolio_id) 키 통일 + 중복/무효 규칙 | Interface | Implemented | High | project maintainers | [req-061](./Interface/req-061_asset-keyed-intent-contract.md) |
| REQ-062 | 수량 hub 정본+로컬 미러 + holding↔broker/hub 불일치 해소 | Integration | Implemented | High | project maintainers | [req-062](./Integration/req-062_quantity-hub-authority-and-divergence.md) |
| REQ-063 | 운영자 표면 단일화 — slots = 자산 포지션 단일 뷰 | Interface | Implemented | Medium | project maintainers | [req-063](./Interface/req-063_unified-operator-slot-view.md) |
| REQ-064 | 풀 모델 → 영구 자산 슬롯 cutover 마이그레이션 | Migration | Implemented | High | project maintainers | [req-064](./Migration/req-064_pool-to-permanent-slot-cutover.md) |
| REQ-064 | 풀 모델 → 자산 중심 DB 재초기화 (구 cutover) | Migration | Implemented | High | project maintainers | [req-064](./Migration/req-064_pool-to-permanent-slot-cutover.md) |
| REQ-065 | 자산 중심 모델 baseline 문서 정합 + 풀 모델 폐기 명시 | Documentation | Implemented | Medium | project maintainers | [req-065](./Documentation/req-065_asset-centric-baseline-alignment.md) |
## Recent Change Log Summary
@@ -155,3 +155,4 @@
- 2026-06-09 :: REQ-032 change-req→Implemented (CHG-20260609-01/02, issue #17, BAT-024): `trex-core enter` 에 `--forced-close-at <ISO8601>` (절대시간) 옵션 추가 — 운영자가 매수 진입 명령 하나로 시간 기반 자동청산(forced_close) 시각 지정. CLI 가 buy intent payload 의 기존 `forced_close_at` 필드에 매핑(계약 REQ-007/021·도메인 REQ-066·forced-close 루프 REQ-037 이미 구현·불변, CLI 노출 갭만 보완). 잘못된 형식 제출 전 거부, 미지정 시 미포함(하위호환). 상대시간(`--hold-minutes`) 미채택. AC-5/6 신규. batch-lite(BAT-024) 단위 검증 → **Implemented**. 단위 353 passed, ruff clean. (change-req/confirm-req-implemented)
- 2026-06-08 :: REQ-017/019/029 change-req + REQ-030 Approved→Implemented (dcy-018, BAT-023): ledger write 응답의 권위 cash/quantity 를 portfolio 스냅샷에 write-back(option D 활성화) — 매수/매도 직후 "수량 live·현금 stale" 비대칭 제거. `record_trade`→`LedgerWriteOutcome{result, *_after}`+어댑터 `cash_balance_after`/`asset_quantity_after` 파싱(new+duplicate)(REQ-017), `LedgerWriter` SnapshotStore write-back best-effort+`pending_cash_delta`(REQ-019), 추정 현금 오버레이(`cash_estimated` 라벨)+슬롯 오버레이 유지(REQ-029, OQ-1 B/OQ-4 i), option D 활성화로 REQ-030 Approved→Implemented. 전부 change-req(신규 REQ 없음, OQ-3 a). portfolio-hub#8(`*_after`) 동작 중. 단위 350 passed, 인프라 게이트 385 passed, ruff clean. (change-req/confirm-req-implemented)
- 2026-06-10 :: REQ-056~065 Approved → Implemented (confirm-req-implemented): dcy-020 자산 중심 슬롯 모델 4개 배치(BAT-027 α/BAT-028 β/BAT-029 γ/BAT-030 δ, 전부 release-candidate) verification evidence 기준. BAT-030 에서 literal inactive·컬럼 drop·매도 수량 브로커 정본·cutover 도구·baseline 마감 완성, run-the-app 자산 중심 e2e green. 실 운영 cutover(REQ-064)는 REL 단계 운영자 실행.
- 2026-06-10 :: REQ-064 재정의 (change-req CHG-20260610-03): 데이터 보존 cutover → DB 재초기화(`trex-core-reset`). 마이그레이션 009 부분 유니크 인덱스가 legacy 풀 중복 데이터에 적용 불가한 결함 + dev/페이퍼 컨텍스트 → wipe+자산 중심 재초기화로 대체. 구 `trex-core-cutover` 도구·테스트 삭제, `tests/runtime/test_reset.py` 신규. Status Implemented 유지(reset evidence). (BAT-030)