# req-108: 차단형 reconcile 비기능 요건 — 내구성·회귀 방지·자동 정정 금지·wire 계약 최소 침습

- Status: Implemented
- Type: Non-Functional
- Priority: High
- Owner: trex-core-dev

## Intent
- dcy-034 NFR-1~4를 단일 REQ로 통합해, 차단형 reconcile 기능 전반에 걸쳐 적용되는 비기능 요건을 명시한다.
- 주요 불변식: (1) warning은 durable해야 함, (2) 단기 인스턴스 오발동 없음, (3) 자동 정정·자동 청산 금지, (4) wire 계약(slots RPC 스키마) 최소 침습.

## Requirement
- [NFR-1 내구성] reconcile-warning 차단 상태는 데몬 재시작 후에도 유지되어야 한다. in-memory overlay만으로 저장하지 않는다.
- [NFR-2 회귀 방지] 단기 인스턴스(M1/M2 라이브 orb+tsl) 정상(일치) 운영에서 신규 reconcile-warning 차단이 오발동하지 않아야 한다. 차단은 실제 수량 불일치가 있을 때만 발생한다.
- [NFR-3 자동 정정 금지] reconcile는 탐지+차단까지만 자동이고, 슬롯 수량·원장 변경은 운영자 명령(`sync`/`verify`)으로만 일어난다. 자동 무음 정정·자동 청산을 하지 않는다(issue #15 기조).
- [NFR-4 wire 계약 최소 침습] `SlotState` enum, `ALLOWED_TRANSITIONS`, slots RPC(`trex.slots.req`) 기존 필드는 변경하지 않는다. 신규 노출(`reconcile_warned` 필드)은 additive only로 추가하며, 기존 클라이언트(trex-orb-v1, trex-tsl-v1)가 신규 필드를 무시해도 동작이 깨지지 않아야 한다.

## Acceptance Criteria
1. Given reconcile-warning이 기록된 상태에서 데몬을 재시작하면, When `ReconcileWarningStore.is_warned(slot_id)` 를 조회하면, Then True가 반환된다(NFR-1, durable).
2. Given 단기 인스턴스의 슬롯 qty == 브로커 qty인 정상 시나리오에서, When boot/일일 reconcile가 실행되면, Then ReconcileWarningStore에 신규 행이 생기지 않는다(NFR-2, 회귀 0, S-4).
3. Given 불일치 탐지(B 또는 C) 후, When reconcile가 자동 실행되면, Then 슬롯 qty, 원장 레코드, 브로커 포지션에 자동 변경이 없다(NFR-3, 탐지+차단만 자동).
4. Given 기존 trex-orb-v1 또는 trex-tsl-v1 클라이언트가 `trex.slots.req` 응답에서 `reconcile_warned` 필드를 수신할 때, When 클라이언트가 해당 필드를 무시하면, Then 기존 동작이 유지된다(NFR-4, additive 하위 호환).
5. Given `domain/slot/state.py`에 새 SlotState 또는 새 전이가 추가되지 않으면, When slots RPC 응답을 생성하면, Then 기존 `status` 필드 값 집합이 유지된다(NFR-4, enum 불변).
6. Given 기존 `ALLOWED_TRANSITIONS`에 없는 전이를 `transit_slot`으로 시도하면, When SlotService가 처리하면, Then 기존 예외(InvalidTransitionError 등)가 발생한다(전이표 불변 확인).

## Impacted Area
- Docs: `docs/interface-contract.md` (additive 필드 명시, enum 불변 확인)
- Modules:
  - `trex_core/domain/slot/state.py` (변경 없음 — 불변 확인 테스트)
  - `trex_core/adapters/persistence/` (reconcile_warning_store durable 검증)
- Tests:
  - `tests/domain/test_slot_state.py` (SlotState enum 불변, ALLOWED_TRANSITIONS 불변 회귀)
  - `tests/application/test_reconciliation.py` (정상 케이스 오발동 없음 회귀, 자동 정정 없음 검증)
  - `tests/application/test_messaging_handlers.py` (reconcile_warned additive 필드 하위 호환)

## Notes
- NFR-4의 slots RPC wire 계약 additive 변경은 REQ-104와 함께 delivery된다. 두 REQ의 AC가 일관되는지 batch design에서 확인한다.
- 단기 인스턴스 회귀(NFR-2/S-4)는 별도 픽스처를 사용한 통합 테스트로 검증한다: 단기 인스턴스 시나리오(당일 슬롯, 슬롯 qty == 브로커 qty)에서 boot reconcile를 실행하고 ReconcileWarningStore가 빈 상태임을 확인.
- dcy-034 NFR-1~4, S-4 대응.

## Change Log

### CHG-20260626-01
- Date: 2026-06-26
- Author: trex-core-dev
- Status: Approved → Implemented
- Summary: BAT-050/051(PR #31/#32) origin/main 머지 완료. QC(opus) PASS + 팀장 confirm-batch-verification. durable 검증, 정상 단기 오발동 없음, 자동 정정 금지, SlotState enum 불변, ALLOWED_TRANSITIONS 불변(+1 sync 전이), additive 하위 호환 전 AC 검증 완료.

#### Acceptance Criteria Delta
- 없음

#### Impacted Area Delta
- 없음

#### Delivery Trace Delta
- Batches: BAT-050 (core-A, AC-1~6), BAT-051 (core-B, ALLOWED_TRANSITIONS 14개 반영)
- Releases: M3 (배포 대기)

#### Revalidation Impact
- Reverification Needed: no
- Existing Implementation Invalidated: no
- Status Recommendation: Implemented
- Follow-up Action: 없음.

#### Validation Plan
- BAT-050/051 verification.md AC 매핑 전항목 PASS 확인됨.

### CHG-20260625-02
- Date: 2026-06-25
- Author: trex-core-dev

#### Change Summary
- REQ-108 **Proposed → Approved** (confirm-req, 팀장 2026-06-25).

#### Intent
- 팀장 confirm-req로 상태 승인. 내용 변경 없음(초안 그대로 승인).

#### Acceptance Criteria Delta
- Added: 없음.
- Updated: 없음.
- Removed: 없음.

#### Impacted Area Delta
- 없음.

#### Delivery Trace Delta
- Batches: 미정 (suggest-batch-reqs 이후)
- Releases: 미정

#### Revalidation Impact
- Reverification Needed: no
- Existing Implementation Invalidated: no
- Status Recommendation: Approved
- Follow-up Action: batch 편성 후 구현.

#### Validation Plan
- durable 재시작 검증 / 정상 케이스 오발동 없음 회귀 / SlotState enum+전이표 불변 회귀 / additive 하위 호환 테스트 pass.

### CHG-20260625-01
- Date: 2026-06-25
- Author: trex-core-dev

#### Change Summary
- REQ-108 신규 생성 (Proposed) — dcy-034 NFR-1~4 대응, draft-req 단계.

#### Intent
- 차단형 reconcile 도입이 기존 시스템(단기 인스턴스, wire 계약, 도메인 불변식)에 의도치 않은 영향을 주지 않도록 비기능 요건을 명시하고 검증 기준을 확정.

#### Acceptance Criteria Delta
- Added: AC-1~6 전부 신규.
- Updated: 없음.
- Removed: 없음.

#### Impacted Area Delta
- Docs: interface-contract.md 갱신 예정.
- Modules: 변경 없음(불변 확인 목적).
- Tests: 불변 회귀 테스트 신규.

#### Delivery Trace Delta
- Batches: 미정
- Releases: 미정

#### Revalidation Impact
- Reverification Needed: no (신규 REQ)
- Existing Implementation Invalidated: no
- Status Recommendation: keep-current
- Follow-up Action: confirm-req 후 REQ-102~107과 동일 batch 편성.

#### Validation Plan
- durable 재시작 검증 / 정상 케이스 오발동 없음 회귀 / SlotState enum+전이표 불변 회귀 / additive 하위 호환 테스트 pass.