trex-core/docs/srs/Non-Functional/req-108_reconcile-blocking-regression-and-nfr.md

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

• Status: Approved
• 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-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.