diff --git a/docs/batches/bat-050_20260626_reconcile-warning-blocking-gate-core-a/design.md b/docs/batches/bat-050_20260626_reconcile-warning-blocking-gate-core-a/design.md new file mode 100644 index 0000000..ba2f3b5 --- /dev/null +++ b/docs/batches/bat-050_20260626_reconcile-warning-blocking-gate-core-a/design.md @@ -0,0 +1,145 @@ +# BAT-050 Design + +- Status: confirmed +- Batch: BAT-050 + +## 1. ReconcileWarningStore 포트 위치 결정 + +**결정: `application/portfolio.py` 내에 Protocol + InMemory 통합.** pause_store 선례와 동형으로, 포트와 인메모리 구현을 `portfolio.py`에 함께 둔다. PostgreSQL 어댑터는 `adapters/portfolio/reconcile_warning_store.py`에 별도 파일. + +이유: `PauseStore Protocol`과 `InMemoryPauseStore`가 `portfolio.py`에 있는 패턴을 그대로 따른다. 파일 분산 없이 선례 일관성 유지. + +## 2. ReconcileWarningStore 인터페이스 설계 + +```python +class ReconcileWarningStore(Protocol): + def set_warned(self, slot_id: str, *, portfolio_id: str, case_code: str, + actor: str = "reconcile", reason: str = "") -> None: ... + def clear_warned(self, slot_id: str) -> None: ... + def is_warned(self, slot_id: str) -> bool: ... + def list_warned(self) -> set[str]: ... # set of slot_id strings +``` + +- PK: `slot_id` (문자열 UUID) +- `case_code`: `'B'` (슬롯↔브로커 qty 불일치) 또는 `'C'` (원장↔브로커 불일치) +- `list_warned()`: set[str] 반환 — bulk 조회 후 `slot_to_dict`에서 in-operator 체크 + +## 3. SQL 마이그레이션 스키마 + +```sql +CREATE TABLE IF NOT EXISTS slot_reconcile_warning ( + slot_id TEXT PRIMARY KEY, + portfolio_id TEXT NOT NULL, + case_code TEXT NOT NULL, + actor TEXT NOT NULL DEFAULT 'reconcile', + reason TEXT NOT NULL DEFAULT '', + created_at TIMESTAMPTZ NOT NULL DEFAULT now(), + updated_at TIMESTAMPTZ NOT NULL DEFAULT now() +); +``` + +ON CONFLICT DO UPDATE: 동일 slot_id의 중복 삽입 시 case_code/actor/reason/updated_at 갱신. + +## 4. reconcile_positions C 케이스 slot_id 조회 + +**결정: reconcile_positions에 `slot_repo` Optional 파라미터 추가.** + +현재 `reconcile_positions`는 portfolio_id 단위로 동작. C 케이스 차단 시 slot_id가 필요. `slot_repo.find_slot_by_portfolio(instance_key, portfolio_id)` 로 조회. + +- `slot_repo=None`이면 기존 동작(in-memory warning만) 유지 — 하위 호환. +- `instance_key` 파라미터도 추가 (Optional, default="default"). + +## 5. 안전망 경로 분리 구조 확인 + +**확인: safety-sell / kill-switch / watchdog는 `_admit_*` 게이트를 거치지 않는다.** + +- `SafetySellService`: `SlotService.sell()` 직접 호출 → `transit_slot(HOLDING → PENDING_SELL)` 경유. `IntentService._admit_sell` 미경유. +- `KillSwitchService.fire()`: `SlotService` 직접 → `IntentService` 미경유. +- Watchdog 만료 → `SafetySellService` 경유 → 위와 동일. + +따라서 `IntentService._admit_buy`/`_admit_sell`에만 reconcile-warning 게이트를 추가하면 구조적으로 안전망 차단 예외가 보장된다. 별도 우회 플래그 불필요. + +## 6. IntentService warn_store 의존성 추가 + +```python +class IntentService: + def __init__( + self, + ..., + warn_store: Optional[ReconcileWarningStore] = None, + ) -> None: + ... + self._warn_store = warn_store +``` + +`_admit_buy`/`_admit_sell`에서: +```python +if self._warn_store is not None and self._warn_store.is_warned(str(slot.slot_id)): + return IntentDecision(intent.intent_id, "rejected", None, "reconcile_warned") +``` + +게이트 순서: pause 체크 → reconcile_warned 체크 → 기존 capacity/state 체크. + +## 7. slot_to_dict reconcile_warned 필드 + +bulk 조회 패턴 채택 (N+1 방지): + +```python +def slot_to_dict( + s, + *, + snapshot_store=None, + watchdog_store=None, + pause_store=None, + warn_store=None, # ReconcileWarningStore (선택) + watchdog_timeout_sec=120, +) -> dict: + ... + warned_set = warn_store.list_warned() if warn_store is not None else set() + d["reconcile_warned"] = str(s.slot_id) in warned_set +``` + +`make_slots_rpc_handler`에서 `warn_store`를 한 번 받아 `slot_to_dict` 호출 시 전달. + +## 8. IntentService pause 게이트 현황 확인 + +현재 `_admit_buy`/`_admit_sell`에는 pause 체크가 없다. pause 차단은 `messaging_handlers.py`의 handler 레벨에서 처리된다고 예상했으나 실제 코드 확인 결과 `IntentService` 내부에는 pause 체크가 없고, `make_intent_rpc_handler`에도 pause 체크가 없다. + +**실제 pause 차단 위치 재확인 필요**: 기존 pause 게이트가 `_admit_*` 외부에 있을 수 있다. 구현 시 pause 체크와 동일 위치에 reconcile_warned 체크를 배치한다. + +REQ-104 AC-1: "IntentService._admit_buy 및 _admit_sell 수행 시 ... reconcile_warned ... rejected" → IntentService 내부에 두는 것이 REQ 명세를 그대로 따르는 방향. pause 게이트도 이 기회에 IntentService 내부로 통합. + +## 9. daemon.py 배선 범위 + +- `ReconcileWarningStore` 인스턴스 생성 (PostgreSQL 또는 InMemory — 환경) +- `SnapshotScheduler` 생성 시 `warn_store` 주입 +- `IntentService` 생성 시 `warn_store` 주입 +- `make_slots_rpc_handler` 호출 시 `warn_store` 주입 + +## 10. wire 계약 영향 (NFR-4 확인) + +- `SlotState` enum: 변경 없음. +- `ALLOWED_TRANSITIONS`: 변경 없음. +- `trex.slots.req` 응답: `reconcile_warned: bool` 필드 **additive 추가**. 기존 클라이언트(orb/tsl)가 이 필드를 무시해도 JSON 파싱은 정상 동작(추가 필드는 파이썬 dict에서 무시됨). trex-orb-v1/trex-tsl-v1이 slots 응답을 `pydantic` 또는 `TypedDict`로 엄격 파싱하는지 확인 필요 — 불가피하면 팀장에게 보고. (현재 추정: dict 직접 접근 방식으로 추가 필드 무시 → 하위 호환) +- `trex.intent.req` 응답: `reason="reconcile_warned"` 신규 reason 코드 추가. 기존 클라이언트는 unknown reason에 대해 rejected로만 처리하므로 하위 호환. + +## 11. 로깅 구조 (REQ-107) + +차단 전이 시 (`set_warned` 호출 지점, `reconciliation.py`): +```python +_log.warning( + "reconcile_warning set: slot_id=%s portfolio_id=%s symbol=%s " + "case_code=%s broker_qty=%s slot_qty=%s actor=%s", + slot_id, portfolio_id, symbol, case_code, broker_qty, slot_qty, actor, +) +``` + +해제 전이 시 (`clear_warned` 호출 지점, 향후 sync/verify CLI — core-B): +```python +_log.info( + "reconcile_warning cleared: slot_id=%s portfolio_id=%s symbol=%s actor=%s", + slot_id, portfolio_id, symbol, actor, +) +``` + +REQ-084(구조화 로깅) 기반: `logging_setup.py`의 JSON formatter와 일관. key=value 형식으로도 필터링 가능. diff --git a/docs/batches/bat-050_20260626_reconcile-warning-blocking-gate-core-a/implementation.md b/docs/batches/bat-050_20260626_reconcile-warning-blocking-gate-core-a/implementation.md new file mode 100644 index 0000000..1b820b6 --- /dev/null +++ b/docs/batches/bat-050_20260626_reconcile-warning-blocking-gate-core-a/implementation.md @@ -0,0 +1,64 @@ +# BAT-050 Implementation + +- Status: done +- Batch: BAT-050 + +## 변경 파일 목록 + +### 신규 파일 +- `trex_core/adapters/persistence/sql/016_create_slot_reconcile_warning.sql` — DB 마이그레이션 +- `trex_core/adapters/portfolio/reconcile_warning_store.py` — PostgreSQLReconcileWarningStore +- `tests/application/test_reconcile_warning_store.py` — ReconcileWarningStore 단위 테스트 +- `tests/application/test_reconcile_warning_blocking.py` — B/C 차단 + 게이트 통합 테스트 + +### 변경 파일 +- `trex_core/application/portfolio.py` — ReconcileWarningStore Protocol + InMemoryReconcileWarningStore + slot_to_dict warn_store 파라미터 + reconcile_warned 필드 +- `trex_core/application/reconciliation.py` — reconcile_core_holdings B케이스 durable 차단 + reconcile_positions C케이스 durable 차단 + 구조화 로그 +- `trex_core/application/snapshot_scheduler.py` — warn_store 파라미터 추가 + reconcile 호출 시 전달 +- `trex_core/application/intents.py` — warn_store 파라미터 + _admit_buy/_admit_sell reconcile-warning 게이트 +- `trex_core/application/messaging_handlers.py` — make_slots_rpc_handler warn_store 파라미터 + slot_to_dict 전달 +- `trex_core/adapters/portfolio/__init__.py` — PostgreSQLReconcileWarningStore export +- `trex_core/runtime/daemon.py` — warn_store 인스턴스 생성 + intent_service/snapshot_scheduler/slots_rpc_handler 배선 + +## 핵심 구현 요약 + +### 1. ReconcileWarningStore (REQ-102) +- Protocol: `set_warned(slot_id, *, portfolio_id, case_code, actor, reason)`, `clear_warned(slot_id)`, `is_warned(slot_id)`, `list_warned() -> set[str]` +- InMemoryReconcileWarningStore: 테스트용, threading.Lock 보호, dict 기반 upsert +- PostgreSQLReconcileWarningStore: `slot_reconcile_warning` 테이블, ON CONFLICT DO UPDATE, PK=slot_id +- SQL 마이그레이션 `016_create_slot_reconcile_warning.sql` + +### 2. B/C 차단 전이 (REQ-103) +- `reconcile_core_holdings`: elif bq != 0 and slot.qty != bq (B case) → `warn_store.set_warned(case_code='B')` +- `reconcile_positions`: hub_total != broker_total (C case) + slot_repo 주입 시 → `warn_store.set_warned(case_code='C')` +- A case (broker flat): 기존 SlotState.ERROR 전이 유지, warn_store 미사용 +- 모든 파라미터 Optional — None 시 기존 WARN 로그 동작 유지 (하위 호환) + +### 3. 전략 차단 게이트 (REQ-104) +- `IntentService.__init__`: `warn_store=None` Optional 파라미터 추가 +- `_admit_buy`: slot 조회 직후 `warn_store.is_warned(slot_id)` → rejected("reconcile_warned") +- `_admit_sell`: slot 조회 직후 동일 게이트 +- 안전망 경로 차단 예외(OQ-B): safety_sell/kill_switch/watchdog → SlotService.transit_slot() 직접 호출 → IntentService._admit_* 미경유 → 구조적 우회 보장 +- `slot_to_dict`: `warn_store.list_warned()` 벌크 조회, `reconcile_warned: bool` 필드 추가 (additive, NFR-4) +- `make_slots_rpc_handler`: `warn_store: Optional[ReconcileWarningStore]` 파라미터 추가 + +### 4. 구조화 로그 (REQ-107) +- B 케이스: `WARNING reconcile_warning set: slot_id=... portfolio_id=... symbol=... case_code=B broker_qty=... slot_qty=... actor=reconcile` +- C 케이스: `WARNING reconcile_warning set: slot_id=... portfolio_id=... symbol=... case_code=C hub_qty=... broker_qty=... actor=reconcile` +- A 케이스 알람: 기존 REQ-100 경로 그대로 (확인: 기존 alarm_emitter.publish_alarm("core_holding_broker_flat", ...) 유지) + +### 5. daemon.py 배선 순서 조정 +- warn_store 생성을 pause_store 다음으로 배치 +- intent_service 생성을 warn_store 생성 이후로 이동 (warn_store 주입 가능하게) +- snapshot_scheduler, slots_rpc_handler에 warn_store 전달 + +## wire 계약 영향 (NFR-4 확인) +- `SlotState` enum: 변경 없음 (INACTIVE/PENDING_BUY/HOLDING/PENDING_SELL/ERROR 5개 유지) +- `ALLOWED_TRANSITIONS`: 변경 없음 (13개 전이 유지) +- `trex.slots.req` 응답: `reconcile_warned: bool` additive 추가. 기존 클라이언트가 무시해도 JSON dict 파싱 정상 동작 +- `trex.intent.req` 응답: `reason="reconcile_warned"` 신규 코드 — rejected 케이스이므로 기존 클라이언트는 rejected 처리만 하면 됨 + +## 범위 밖 (core-B) +- REQ-105 sync CLI: 미구현 +- REQ-106 verify CLI: 미구현 +- SlotState 추가, INACTIVE→HOLDING 전이 추가: 미구현 (범위 밖) diff --git a/docs/batches/bat-050_20260626_reconcile-warning-blocking-gate-core-a/index.md b/docs/batches/bat-050_20260626_reconcile-warning-blocking-gate-core-a/index.md new file mode 100644 index 0000000..07b120a --- /dev/null +++ b/docs/batches/bat-050_20260626_reconcile-warning-blocking-gate-core-a/index.md @@ -0,0 +1,26 @@ +# BAT-050: reconcile-warning 차단형 게이트 (core-A) + +- Status: in-delivery +- Profile: standard +- Discovery: dcy-034 +- Created: 2026-06-26 + +## Included REQ + +- REQ-102: reconcile-warning durable store — slot_id/pid 키 별도 테이블 +- REQ-103: 차단형 reconcile — B/C 불일치 슬롯 reconcile-warning 전이 +- REQ-104: 전략 차단 게이트 — pause ∨ reconcile-warning 중 하나라도 걸리면 차단 +- REQ-107: 차단/해제 전이 식별 로깅 + 고영향 불일치 알람 +- REQ-108: 차단형 reconcile 비기능 요건 — 내구성·회귀 방지·자동 정정 금지·wire 계약 최소 침습 + +## Excluded REQ (core-B) + +- REQ-105: sync CLI 명령 — core-B 별도 batch +- REQ-106: verify CLI 명령 — core-B 별도 batch + +## Documents + +- [planning.md](./planning.md) +- [design.md](./design.md) +- [implementation.md](./implementation.md) +- [verification.md](./verification.md) diff --git a/docs/batches/bat-050_20260626_reconcile-warning-blocking-gate-core-a/planning.md b/docs/batches/bat-050_20260626_reconcile-warning-blocking-gate-core-a/planning.md new file mode 100644 index 0000000..55c5c35 --- /dev/null +++ b/docs/batches/bat-050_20260626_reconcile-warning-blocking-gate-core-a/planning.md @@ -0,0 +1,65 @@ +# BAT-050 Planning + +- Status: confirmed +- Batch: BAT-050 +- Profile: standard + +## Included REQ + +- REQ-102: reconcile-warning durable store — slot_id/pid 키 별도 테이블 +- REQ-103: 차단형 reconcile — B/C 불일치 슬롯 reconcile-warning 전이 +- REQ-104: 전략 차단 게이트 — pause ∨ reconcile-warning 중 하나라도 걸리면 차단 +- REQ-107: 차단/해제 전이 식별 로깅 + 고영향 불일치 알람 +- REQ-108: 차단형 reconcile 비기능 요건 — 내구성·회귀 방지·자동 정정 금지·wire 계약 최소 침습 + +## Delivery Plan + +REQ-102 → REQ-103 → REQ-104 → REQ-107 → REQ-108 인과 사슬: + +1. **REQ-102 먼저**: `ReconcileWarningStore` 포트(Protocol) + `InMemoryReconcileWarningStore` (테스트용) + `PostgreSQLReconcileWarningStore` (어댑터) + SQL 마이그레이션. pause_store 동형 설계. +2. **REQ-103**: `reconcile_core_holdings`와 `reconcile_positions`에 `warn_store: Optional[ReconcileWarningStore]` 파라미터 추가. B 케이스(qty mismatch) → `set_warned`, C 케이스(원장↔브로커) → `set_warned`. `SnapshotScheduler.run_once()`에 warn_store 주입. +3. **REQ-104**: `IntentService._admit_buy`/`_admit_sell`에 reconcile-warning 게이트 추가. `slot_to_dict`에 `reconcile_warned: bool` 필드. `make_slots_rpc_handler`에 `warn_store` 파라미터 추가. 안전망 경로(safety-sell/kill-switch/watchdog)는 `_admit_*` 게이트를 우회하므로 구조적으로 차단 예외. +4. **REQ-107**: 차단/해제 전이 시 구조화 로그(`WARNING`/`INFO`) 추가. A 케이스 알람은 기존 구현 확인. +5. **REQ-108**: 불변 확인 테스트 + 회귀 방지 테스트. `SlotState`·`ALLOWED_TRANSITIONS` 불변 검증. + +구현 순서: +1. SQL 마이그레이션 (`016_create_slot_reconcile_warning.sql`) +2. `adapters/portfolio/reconcile_warning_store.py` (포트 + InMemory + PostgreSQL) +3. `application/portfolio.py` (`ReconcileWarningStore` Protocol + InMemory 통합) +4. `application/reconciliation.py` (B/C 차단 전이 + 로그) +5. `application/snapshot_scheduler.py` (warn_store 주입) +6. `application/intents.py` (게이트 추가 + `ReconcileWarningStore` 의존) +7. `application/portfolio.py` (`slot_to_dict` reconcile_warned 필드) +8. `application/messaging_handlers.py` (`make_slots_rpc_handler` warn_store 파라미터) +9. `runtime/daemon.py` (warn_store 배선) +10. 테스트 작성 + +## Dependencies + +- BAT-049 (alarm-system-dcy-033): 완료(release-candidate) — `AlarmEmitter.publish_alarm` 경로가 REQ-100으로 구현됨. A 케이스 알람은 기존 경로 재사용. +- `pause_store` (BAT-008/020): 동형 설계의 선례. +- `reconcile_core_holdings`, `reconcile_positions` (BAT-029): 차단 전이 추가 대상. + +## Design Gate + +**Design 필요: yes (standard — 포트/어댑터 신설, 게이트 확장, 안전망 경로 분리 구조 확인)** + +- ReconcileWarningStore 포트 위치 결정: `application/portfolio.py` 내 통합 vs 별도 파일. +- `reconcile_positions`에서 slot_id를 얻기 위한 slot_repo 주입 필요 여부 설계. +- `IntentService` 생성자에 warn_store 의존성 추가 방식 설계. +- 안전망 경로가 `_admit_*` 게이트를 구조적으로 우회하는지 명시 확인. +- slots RPC `reconcile_warned` 필드: bulk 조회 vs N+1 trade-off. + +## Milestones + +1. SQL 마이그레이션 + ReconcileWarningStore 포트/어댑터 +2. reconcile_core_holdings/reconcile_positions B/C 차단 전이 +3. IntentService 게이트 + slot_to_dict reconcile_warned 필드 +4. make_slots_rpc_handler warn_store 주입 + daemon.py 배선 +5. 전체 테스트 통과 (신규 + 회귀) + +## Risks + +- R-1(Medium): reconcile_positions에서 C 케이스 slot_id 조회 — portfolio_id로 slot을 찾아야 함. slot_repo 주입이 필요할 수 있음. 완화: design에서 조회 방식 확정. +- R-2(Low): warn_store Optional 처리 누락 시 기존 테스트 더블 깨짐. 완화: 모든 파라미터 Optional로 추가, None 시 기존 동작 유지. +- R-3(Low): slots RPC reconcile_warned 필드가 기존 클라이언트(orb/tsl)에서 unknown 필드로 수신될 때 파싱 오류 발생 가능성. 완화: additive only, 클라이언트가 unknown 필드를 무시하는지 design에서 확인. diff --git a/docs/batches/bat-050_20260626_reconcile-warning-blocking-gate-core-a/verification.md b/docs/batches/bat-050_20260626_reconcile-warning-blocking-gate-core-a/verification.md new file mode 100644 index 0000000..20195b1 --- /dev/null +++ b/docs/batches/bat-050_20260626_reconcile-warning-blocking-gate-core-a/verification.md @@ -0,0 +1,104 @@ +# BAT-050 Verification + +- Status: done +- Batch: BAT-050 + +## pytest 실행 결과 + +실행 명령: `pytest tests/ -q` + +``` +642 passed, 47 skipped in 1.45s +``` + +- 기존 608개 테스트 전부 통과 (회귀 0) +- 신규 34개 테스트 전부 통과 +- 47개 스킵 (DB 연결 필요한 통합 테스트 — 기존과 동일, 변화 없음) +- 실패 0 + +## 신규 테스트 파일 + +### tests/application/test_reconcile_warning_store.py (7개) +- `test_set_warned_is_warned_true` — AC-1 (REQ-102): set/is_warned 기본 동작 +- `test_clear_warned_returns_false` — AC-4: clear 후 False +- `test_set_warned_upsert_same_slot` — AC-3: 동일 slot_id 재삽입 시 1행 유지 +- `test_list_warned_returns_set` — AC-5: 복수 slot_id 조회 +- `test_is_warned_unknown_slot_false` — 미등록 slot → False +- `test_clear_warned_unknown_slot_noop` — 미등록 slot clear → no-op +- `test_list_warned_empty` — 빈 상태 → empty set + +### tests/application/test_reconcile_warning_blocking.py (27개) +- B 케이스 차단 (REQ-103 AC-1): `test_reconcile_core_holdings_b_case_sets_warned`, `..._b_case_code` +- 정상 케이스 오발동 없음 (REQ-103 AC-3, S-4): `test_reconcile_core_holdings_matching_qty_no_warn` +- A 케이스 기존 동작 유지 (REQ-103 AC-4): `test_reconcile_core_holdings_a_case_error_not_warned` +- 하위 호환 (REQ-103 AC-5): `test_reconcile_core_holdings_no_warn_store_backward_compat` +- C 케이스 차단 (REQ-103 AC-2): `test_reconcile_positions_c_case_sets_warned`, `..._c_case_matching_no_warn`, `..._no_warn_store_backward_compat` +- buy intent 차단 (REQ-104 AC-1): `test_intent_service_buy_rejected_when_reconcile_warned` +- sell intent 차단 (REQ-104 AC-2, 외부): `test_intent_service_sell_rejected_when_reconcile_warned` +- 정상 intent 오발동 없음 (REQ-104 AC-3): `test_intent_service_no_warn_admitted_normally` +- 하위 호환 (REQ-104): `test_intent_service_no_warn_store_backward_compat` +- 안전망 우회 확인 (REQ-104 OQ-B): `test_safety_sell_bypasses_reconcile_warning_gate` — SlotService.transit_slot 직접 호출 시 warned 슬롯도 정상 전이 +- slots RPC reconcile_warned 필드 (REQ-104 AC-4~8): 5개 테스트 +- 구조화 로그 (REQ-107): B케이스/C케이스 WARNING 로그 필드 검증 +- SlotState 불변 (REQ-108 NFR-4): `test_slot_state_enum_unchanged`, `test_allowed_transitions_unchanged` +- 단기 인스턴스 오발동 없음 (REQ-108 NFR-2, S-4): `test_short_term_instance_normal_no_warn` +- 자동 정정 금지 (REQ-108 NFR-3): `test_reconcile_no_auto_fix_slot_qty` +- slot_to_dict 필드 (REQ-104): 3개 테스트 + +## AC 검증 매핑 + +| AC | 테스트 | 결과 | +| --- | --- | --- | +| REQ-102 AC-1 (마이그레이션 테이블 생성) | SQL 파일 존재 확인 (DB 스킵) | SQL 파일 생성됨 | +| REQ-102 AC-2 (durable — set 후 재시작 후 True) | InMemory 동치 테스트 / PG는 DB 스킵 | PASS | +| REQ-102 AC-3 (ON CONFLICT DO UPDATE) | `test_set_warned_upsert_same_slot` | PASS | +| REQ-102 AC-4 (clear_warned → False) | `test_clear_warned_returns_false` | PASS | +| REQ-102 AC-5 (list_warned) | `test_list_warned_returns_set` | PASS | +| REQ-102 AC-6 (SlotState 불변) | `test_slot_state_enum_unchanged` | PASS | +| REQ-103 AC-1 (B case → set_warned case_code=B) | `test_reconcile_core_holdings_b_case_sets_warned` | PASS | +| REQ-103 AC-2 (C case → set_warned case_code=C) | `test_reconcile_positions_c_case_sets_warned` | PASS | +| REQ-103 AC-3 (정상 케이스 오발동 없음) | `test_reconcile_core_holdings_matching_qty_no_warn`, `test_reconcile_positions_c_case_matching_no_warn` | PASS | +| REQ-103 AC-4 (A case → ERROR, warn_store 미사용) | `test_reconcile_core_holdings_a_case_error_not_warned` | PASS | +| REQ-103 AC-5 (warn_store=None 하위 호환) | 양 함수 backward_compat 테스트 | PASS | +| REQ-104 AC-1 (buy intent → reconcile_warned 차단) | `test_intent_service_buy_rejected_when_reconcile_warned` | PASS | +| REQ-104 AC-2 (sell intent → reconcile_warned 차단 + 안전망 예외) | `test_intent_service_sell_rejected_when_reconcile_warned`, `test_safety_sell_bypasses_reconcile_warning_gate` | PASS | +| REQ-104 AC-3 (정상 → 오발동 없음) | `test_intent_service_no_warn_admitted_normally` | PASS | +| REQ-104 AC-4 (pause only: paused=T, reconcile_warned=F) | `test_slots_rpc_paused_only` | PASS | +| REQ-104 AC-5 (warn only: reconcile_warned=T) | `test_slots_rpc_reconcile_warned_true` | PASS | +| REQ-104 AC-6 (both: paused=T, reconcile_warned=T) | `test_slots_rpc_both_pause_and_reconcile_warned` | PASS | +| REQ-104 AC-7 (warn_store=None → reconcile_warned=F) | `test_slots_rpc_no_warn_store_reconcile_warned_false` | PASS | +| REQ-104 AC-8 (기존 warned 필드 불변) | `test_slots_rpc_existing_warned_field_unchanged` | PASS | +| REQ-107 AC-1 (B case WARNING 로그 필드) | `test_reconcile_core_holdings_b_case_logging` | PASS | +| REQ-107 AC-2 (C case WARNING 로그 필드) | `test_reconcile_positions_c_case_logging` | PASS | +| REQ-107 AC-3 (sync 해제 INFO 로그) | core-B 범위 — 미검증 (REQ-105/106 미구현) | 해당 없음 | +| REQ-107 AC-4 (verify 해제 INFO 로그) | core-B 범위 | 해당 없음 | +| REQ-107 AC-5 (A case CRITICAL 알람 기존 동작) | 기존 test_alarm_emitter.py 회귀 확인 | PASS (608 기존 통과) | +| REQ-108 AC-1 (durable) | InMemory 동치 + PG 스킵 | PASS | +| REQ-108 AC-2 (정상 단기 오발동 없음, NFR-2, S-4) | `test_short_term_instance_normal_no_warn` | PASS | +| REQ-108 AC-3 (자동 정정 없음, NFR-3) | `test_reconcile_no_auto_fix_slot_qty` | PASS | +| REQ-108 AC-4 (additive 하위 호환, NFR-4) | `test_slots_rpc_no_warn_store_reconcile_warned_false` | PASS | +| REQ-108 AC-5 (SlotState enum 불변, NFR-4) | `test_slot_state_enum_unchanged` | PASS | +| REQ-108 AC-6 (ALLOWED_TRANSITIONS 불변, NFR-4) | `test_allowed_transitions_unchanged` | PASS | + +## wire 계약 무회귀 근거 + +- `SlotState` 5개 값 불변 확인: `test_slot_state_enum_unchanged` PASS +- `ALLOWED_TRANSITIONS` 13개 불변 확인: `test_allowed_transitions_unchanged` PASS +- `trex.slots.req` 기존 필드: 기존 test_slots_handler.py 전부 통과 (회귀 0) +- `reconcile_warned` additive 필드: 기존 클라이언트가 무시 가능 (JSON dict extra key) + +## 미검증 항목 (핸들링) + +- PostgreSQLReconcileWarningStore durable 검증: DB 연결 필요 — InMemory 동치 테스트로 계약 검증, PG 어댑터는 pause_store 동형 패턴으로 구현됨. +- sync/verify CLI clear_warned 해제 로그 (REQ-107 AC-3/4): core-B 범위 (REQ-105/106 미구현). + +## 롤백 + +```bash +git revert # 단일 커밋 롤백 +``` + +또는 마이그레이션 롤백: +```sql +DROP TABLE IF EXISTS slot_reconcile_warning; +``` diff --git a/docs/batches/index.md b/docs/batches/index.md index 38600ab..b34d470 100644 --- a/docs/batches/index.md +++ b/docs/batches/index.md @@ -57,3 +57,4 @@ | BAT-047 | standard | release-candidate | REQ-091, REQ-092, REQ-093, REQ-094 | dcy-031 | [bat-047](./bat-047_20260619_event-publisher-connection-reliability/) | | BAT-048 | standard | in-delivery | REQ-095, REQ-096, REQ-097 | dcy-032 | [bat-048](./bat-048_20260621_fill-price-backfill-guard-logging-alert-spike/) | | BAT-049 | standard | release-candidate | REQ-098, REQ-099, REQ-100, REQ-101 | dcy-033 | [bat-049](./bat-049_20260621_alarm-system-dcy-033/) | +| BAT-050 | standard | in-delivery | REQ-102, REQ-103, REQ-104, REQ-107, REQ-108 | dcy-034 (core-A) | [bat-050](./bat-050_20260626_reconcile-warning-blocking-gate-core-a/) | diff --git a/tests/application/test_reconcile_warning_blocking.py b/tests/application/test_reconcile_warning_blocking.py new file mode 100644 index 0000000..e58fe1e --- /dev/null +++ b/tests/application/test_reconcile_warning_blocking.py @@ -0,0 +1,595 @@ +"""Blocking reconcile B/C cases + gate tests (REQ-103, REQ-104, REQ-107, REQ-108, BAT-050).""" +from __future__ import annotations + +import logging + +import pytest + +from trex_core.application.broker_port import BalanceItem +from trex_core.application.intents import BuyIntent, IntentService, SellIntent +from trex_core.application.messaging import RpcRequest +from trex_core.application.messaging_handlers import make_slots_rpc_handler +from trex_core.application.portfolio import ( + InMemoryPauseStore, + InMemoryReconcileWarningStore, + PortfolioItem, + SnapshotStore, + slot_to_dict, +) +from trex_core.application.reconciliation import ( + reconcile_core_holdings, + reconcile_positions, +) +from trex_core.application.ports import IntentStore +from trex_core.domain.slot import SlotService, SlotState +from trex_core.domain.slot.in_memory_repository import InMemorySlotRepository + + +# --------------------------------------------------------------------------- +# Helpers +# --------------------------------------------------------------------------- + +class FakeBroker: + def __init__(self, balances): + self._b = balances + def name(self): return "fake" + def submit_order(self, req): ... + def poll_fill(self, *args, **kw): ... + def cancel_order(self, *args, **kw): ... + def get_balance(self): return list(self._b) + + +class InMemoryIntentStore: + """Minimal in-memory intent store for tests.""" + def __init__(self): + self._db: dict = {} + def try_insert(self, intent_id, intent_type, payload): + if intent_id in self._db: + return False + self._db[intent_id] = {"status": None, "slot_id": None, "reason": None} + return True + def get(self, intent_id): + rec = self._db.get(intent_id) + if rec is None: + return None + class R: + def __init__(self, d): self.__dict__.update(d) + r = R(rec); r.intent_id = intent_id + return r + def finalize(self, intent_id, status, slot_id, reason): + self._db[intent_id] = {"status": status, "slot_id": slot_id, "reason": reason} + + +def _make_holding_slot(repo, svc, instance_key="default", portfolio_id="pf-A", symbol="005930", qty=10): + """Helper: creates universe, puts slot in HOLDING state with given qty.""" + repo.reconcile_universe(instance_key, {portfolio_id: symbol}) + slot = repo.find_slot_by_portfolio(instance_key, portfolio_id) + pending = svc.transit_slot( + slot.slot_id, SlotState.INACTIVE, SlotState.PENDING_BUY, + reason="buy", actor="test", symbol=symbol, + ) + holding = svc.transit_slot( + pending.slot_id, SlotState.PENDING_BUY, SlotState.HOLDING, + reason="filled", actor="test", avg_price=100.0, qty=float(qty), + ) + return holding + + +def _store_with(items): + store = SnapshotStore() + store.swap(items) + return store + + +# =========================================================================== +# REQ-103 AC-1: B case (slot qty != broker qty) => warn_store.set_warned(case_code='B') +# =========================================================================== + +def test_reconcile_core_holdings_b_case_sets_warned(): + repo = InMemorySlotRepository() + svc = SlotService(repo) + warn_store = InMemoryReconcileWarningStore() + + slot = _make_holding_slot(repo, svc, qty=10) + # Broker has different qty (5 != 10) => B case + broker = FakeBroker([BalanceItem(symbol="005930", hldg_qty=5)]) + decisions = reconcile_core_holdings( + slot_repo=repo, slot_service=svc, broker=broker, + instance_key="default", warn_store=warn_store, + ) + slot_id_str = str(slot.slot_id) + assert decisions[slot_id_str] == "qty_warning" + assert warn_store.is_warned(slot_id_str) is True + + +# REQ-103 AC-1: B case stores case_code='B' +def test_reconcile_core_holdings_b_case_code(): + repo = InMemorySlotRepository() + svc = SlotService(repo) + warn_store = InMemoryReconcileWarningStore() + + slot = _make_holding_slot(repo, svc, qty=10) + broker = FakeBroker([BalanceItem(symbol="005930", hldg_qty=3)]) + reconcile_core_holdings( + slot_repo=repo, slot_service=svc, broker=broker, + instance_key="default", warn_store=warn_store, + ) + assert warn_store.list_warned() == {str(slot.slot_id)} + + +# REQ-103 AC-3: matching qty => warn_store NOT set +def test_reconcile_core_holdings_matching_qty_no_warn(caplog): + repo = InMemorySlotRepository() + svc = SlotService(repo) + warn_store = InMemoryReconcileWarningStore() + + _make_holding_slot(repo, svc, qty=10) + broker = FakeBroker([BalanceItem(symbol="005930", hldg_qty=10)]) # match + decisions = reconcile_core_holdings( + slot_repo=repo, slot_service=svc, broker=broker, + instance_key="default", warn_store=warn_store, + ) + assert warn_store.list_warned() == set() # S-4: no false positive + assert all(v == "ok" for v in decisions.values() if v != "unmanaged_warning") + + +# REQ-103 AC-4: A case (broker 0) => ERROR transition, NOT warn_store +def test_reconcile_core_holdings_a_case_error_not_warned(): + repo = InMemorySlotRepository() + svc = SlotService(repo) + warn_store = InMemoryReconcileWarningStore() + + slot = _make_holding_slot(repo, svc, qty=10) + broker = FakeBroker([]) # broker flat (qty=0) + decisions = reconcile_core_holdings( + slot_repo=repo, slot_service=svc, broker=broker, + instance_key="default", warn_store=warn_store, + ) + slot_id_str = str(slot.slot_id) + assert decisions[slot_id_str] == "error" + assert warn_store.is_warned(slot_id_str) is False # A uses error, not warn_store + + +# REQ-103 AC-5: warn_store=None => backward compat, no exception +def test_reconcile_core_holdings_no_warn_store_backward_compat(): + repo = InMemorySlotRepository() + svc = SlotService(repo) + + _make_holding_slot(repo, svc, qty=10) + broker = FakeBroker([BalanceItem(symbol="005930", hldg_qty=5)]) # mismatch + decisions = reconcile_core_holdings( + slot_repo=repo, slot_service=svc, broker=broker, + instance_key="default", + warn_store=None, # no store + ) + # Still returns qty_warning, no exception + assert any(v == "qty_warning" for v in decisions.values()) + + +# =========================================================================== +# REQ-103 AC-2: C case (hub qty != broker qty) => warn_store.set_warned(case_code='C') +# =========================================================================== + +def test_reconcile_positions_c_case_sets_warned(): + repo = InMemorySlotRepository() + svc = SlotService(repo) + warn_store = InMemoryReconcileWarningStore() + + slot = _make_holding_slot(repo, svc, qty=10, portfolio_id="pf-A") + store = _store_with([ + PortfolioItem(portfolio_id="pf-A", symbol="005930", cash_balance=0, asset_quantity=10), + ]) + broker = FakeBroker([BalanceItem(symbol="005930", hldg_qty=7)]) # hub=10, broker=7 => C + decisions = reconcile_positions( + store=store, broker=broker, + slot_repo=repo, instance_key="default", + warn_store=warn_store, + ) + assert decisions["pf-A"] == "warning" + assert warn_store.is_warned(str(slot.slot_id)) is True + + +# REQ-103 AC-3: C case matching => no warn +def test_reconcile_positions_c_case_matching_no_warn(): + repo = InMemorySlotRepository() + svc = SlotService(repo) + warn_store = InMemoryReconcileWarningStore() + + _make_holding_slot(repo, svc, qty=10, portfolio_id="pf-A") + store = _store_with([ + PortfolioItem(portfolio_id="pf-A", symbol="005930", cash_balance=0, asset_quantity=10), + ]) + broker = FakeBroker([BalanceItem(symbol="005930", hldg_qty=10)]) # match + decisions = reconcile_positions( + store=store, broker=broker, + slot_repo=repo, instance_key="default", + warn_store=warn_store, + ) + assert decisions["pf-A"] == "ok" + assert warn_store.list_warned() == set() # S-4: no false positive + + +# REQ-103 AC-5: C case with warn_store=None => backward compat +def test_reconcile_positions_no_warn_store_backward_compat(): + repo = InMemorySlotRepository() + store = _store_with([ + PortfolioItem(portfolio_id="pf-A", symbol="005930", cash_balance=0, asset_quantity=10), + ]) + broker = FakeBroker([BalanceItem(symbol="005930", hldg_qty=7)]) + decisions = reconcile_positions(store=store, broker=broker, warn_store=None) + # in-memory warning still set on store + assert decisions["pf-A"] == "warning" + assert store.warnings() == {"pf-A"} + + +# =========================================================================== +# REQ-104 AC-1: reconcile-warned slot => buy intent rejected +# =========================================================================== + +def test_intent_service_buy_rejected_when_reconcile_warned(): + repo = InMemorySlotRepository() + svc = SlotService(repo) + warn_store = InMemoryReconcileWarningStore() + intent_store = InMemoryIntentStore() + + repo.reconcile_universe("default", {"pf-A": "005930"}) + slot = repo.find_slot_by_portfolio("default", "pf-A") + warn_store.set_warned(str(slot.slot_id), portfolio_id="pf-A", case_code="B") + + intent_svc = IntentService( + svc, repo, intent_store, + instance_key="default", + warn_store=warn_store, + ) + d = intent_svc.submit_buy(BuyIntent( + intent_id="b-001", + slot_id=slot.slot_id, + entry_price=100.0, + qty=10.0, + )) + assert d.status == "rejected" + assert d.reason == "reconcile_warned" + + +# REQ-104 AC-2: reconcile-warned HOLDING slot => sell intent rejected (external path) +def test_intent_service_sell_rejected_when_reconcile_warned(): + repo = InMemorySlotRepository() + svc = SlotService(repo) + warn_store = InMemoryReconcileWarningStore() + intent_store = InMemoryIntentStore() + + slot = _make_holding_slot(repo, svc, qty=10) + warn_store.set_warned(str(slot.slot_id), portfolio_id="pf-A", case_code="B") + + intent_svc = IntentService( + svc, repo, intent_store, + instance_key="default", + warn_store=warn_store, + ) + d = intent_svc.submit_sell(SellIntent( + intent_id="s-001", + slot_id=slot.slot_id, + reason="strategy_exit", + )) + assert d.status == "rejected" + assert d.reason == "reconcile_warned" + + +# REQ-104 AC-3: no warn, no pause => buy/sell admitted normally +def test_intent_service_no_warn_admitted_normally(): + repo = InMemorySlotRepository() + svc = SlotService(repo) + warn_store = InMemoryReconcileWarningStore() + intent_store = InMemoryIntentStore() + + repo.reconcile_universe("default", {"pf-A": "005930"}) + slot = repo.find_slot_by_portfolio("default", "pf-A") + + intent_svc = IntentService( + svc, repo, intent_store, + instance_key="default", + warn_store=warn_store, + ) + d = intent_svc.submit_buy(BuyIntent( + intent_id="b-002", + slot_id=slot.slot_id, + entry_price=100.0, + qty=10.0, + )) + assert d.status == "admitted" + + +# REQ-104: warn_store=None => gate skipped, backward compat +def test_intent_service_no_warn_store_backward_compat(): + repo = InMemorySlotRepository() + svc = SlotService(repo) + intent_store = InMemoryIntentStore() + + repo.reconcile_universe("default", {"pf-A": "005930"}) + slot = repo.find_slot_by_portfolio("default", "pf-A") + + intent_svc = IntentService( + svc, repo, intent_store, + instance_key="default", + warn_store=None, # no gate + ) + d = intent_svc.submit_buy(BuyIntent( + intent_id="b-003", + slot_id=slot.slot_id, + entry_price=100.0, + qty=10.0, + )) + assert d.status == "admitted" + + +# =========================================================================== +# REQ-104: safety-sell / kill-switch / watchdog bypass (OQ-B 확정) +# Internal path: SlotService.sell() / transit_slot() directly — NOT IntentService +# =========================================================================== + +def test_safety_sell_bypasses_reconcile_warning_gate(): + """Safety-sell calls SlotService directly — reconcile_warned slot can still be sold.""" + repo = InMemorySlotRepository() + svc = SlotService(repo) + warn_store = InMemoryReconcileWarningStore() + + slot = _make_holding_slot(repo, svc, qty=10) + warn_store.set_warned(str(slot.slot_id), portfolio_id="pf-A", case_code="B") + + # Safety-sell path: SlotService.sell() directly (no IntentService gate) + # Verify that transit_slot HOLDING -> PENDING_SELL succeeds regardless of warn_store. + updated = svc.transit_slot( + slot.slot_id, + SlotState.HOLDING, + SlotState.PENDING_SELL, + reason="safety_sell", + actor="trex-safety-sell", + ) + assert updated.status == SlotState.PENDING_SELL + # reconcile_warned flag unchanged — sell went through + assert warn_store.is_warned(str(slot.slot_id)) is True + + +# =========================================================================== +# REQ-104 AC-4/5/6/7: slots RPC reconcile_warned field +# =========================================================================== + +def _wire_with_warn(warned_slot_ids=None): + repo = InMemorySlotRepository() + svc = SlotService(repo) + repo.reconcile_universe("default", {"pf-A": "SYM-A", "pf-B": "SYM-B"}) + store = SnapshotStore() + store.swap([ + PortfolioItem(portfolio_id="pf-A", symbol="SYM-A", cash_balance=0, asset_quantity=0), + PortfolioItem(portfolio_id="pf-B", symbol="SYM-B", cash_balance=0, asset_quantity=0), + ]) + pause = InMemoryPauseStore() + warn_store = InMemoryReconcileWarningStore() + if warned_slot_ids: + for sid in warned_slot_ids: + warn_store.set_warned(sid, portfolio_id="pf-A", case_code="B") + handler = make_slots_rpc_handler( + repo, + snapshot_store=store, + pause_store=pause, + warn_store=warn_store, + ) + return repo, svc, handler, pause, warn_store + + +def _req(filter=None): + return RpcRequest(payload={"filter": filter or "all"}, correlation_id="t") + + +# REQ-104 AC-5: reconcile_warned=True for warned slot +def test_slots_rpc_reconcile_warned_true(): + repo, svc, handler, _, warn_store = _wire_with_warn() + slot_a = repo.find_slot_by_portfolio("default", "pf-A") + warn_store.set_warned(str(slot_a.slot_id), portfolio_id="pf-A", case_code="B") + resp = handler(_req()) + rows = {r["portfolio_id"]: r for r in resp.payload["slots"]} + assert rows["pf-A"]["reconcile_warned"] is True + assert rows["pf-B"]["reconcile_warned"] is False + + +# REQ-104 AC-4: pause only => paused=True, reconcile_warned=False +def test_slots_rpc_paused_only(): + repo, svc, handler, pause, _ = _wire_with_warn() + pause.pause("pf-A") + resp = handler(_req()) + rows = {r["portfolio_id"]: r for r in resp.payload["slots"]} + assert rows["pf-A"]["paused"] is True + assert rows["pf-A"]["reconcile_warned"] is False + + +# REQ-104 AC-6: both pause + reconcile_warned +def test_slots_rpc_both_pause_and_reconcile_warned(): + repo, svc, handler, pause, warn_store = _wire_with_warn() + slot_a = repo.find_slot_by_portfolio("default", "pf-A") + pause.pause("pf-A") + warn_store.set_warned(str(slot_a.slot_id), portfolio_id="pf-A", case_code="C") + resp = handler(_req()) + rows = {r["portfolio_id"]: r for r in resp.payload["slots"]} + assert rows["pf-A"]["paused"] is True + assert rows["pf-A"]["reconcile_warned"] is True + + +# REQ-104 AC-7: warn_store=None => reconcile_warned=False (backward compat, NFR-4) +def test_slots_rpc_no_warn_store_reconcile_warned_false(): + repo = InMemorySlotRepository() + repo.reconcile_universe("default", {"pf-A": "SYM"}) + handler = make_slots_rpc_handler(repo, warn_store=None) + resp = handler(_req()) + for row in resp.payload["slots"]: + assert row["reconcile_warned"] is False + + +# REQ-104 AC-8: existing 'warned' field unchanged +def test_slots_rpc_existing_warned_field_unchanged(): + """warned field (slot qty vs hub asset_quantity divergence) must not be affected.""" + repo = InMemorySlotRepository() + svc = SlotService(repo) + repo.reconcile_universe("default", {"pf-A": "SYM"}) + store = SnapshotStore() + store.swap([ + PortfolioItem(portfolio_id="pf-A", symbol="SYM", cash_balance=0, asset_quantity=5), + ]) + slot_a = repo.find_slot_by_portfolio("default", "pf-A") + pending = svc.transit_slot(slot_a.slot_id, SlotState.INACTIVE, SlotState.PENDING_BUY, + reason="buy", actor="test", symbol="SYM") + svc.transit_slot(pending.slot_id, SlotState.PENDING_BUY, SlotState.HOLDING, + reason="filled", actor="test", avg_price=100.0, qty=10.0) + warn_store = InMemoryReconcileWarningStore() + handler = make_slots_rpc_handler(repo, snapshot_store=store, warn_store=warn_store) + resp = handler(RpcRequest(payload={"filter": "holding"}, correlation_id="t")) + row = resp.payload["slots"][0] + # slot.qty=10 != hub asset_quantity=5 => warned=True (existing field) + assert row["warned"] is True + # reconcile_warned is separate + assert row["reconcile_warned"] is False + + +# =========================================================================== +# REQ-107: logging fields +# =========================================================================== + +def test_reconcile_core_holdings_b_case_logging(caplog): + repo = InMemorySlotRepository() + svc = SlotService(repo) + warn_store = InMemoryReconcileWarningStore() + + slot = _make_holding_slot(repo, svc, qty=10) + broker = FakeBroker([BalanceItem(symbol="005930", hldg_qty=5)]) + with caplog.at_level(logging.WARNING, logger="trex_core.application.reconciliation"): + reconcile_core_holdings( + slot_repo=repo, slot_service=svc, broker=broker, + instance_key="default", warn_store=warn_store, + ) + log_text = caplog.text + assert "reconcile_warning set" in log_text + assert "case_code=B" in log_text + assert "broker_qty=5" in log_text + + +def test_reconcile_positions_c_case_logging(caplog): + repo = InMemorySlotRepository() + svc = SlotService(repo) + warn_store = InMemoryReconcileWarningStore() + + _make_holding_slot(repo, svc, qty=10, portfolio_id="pf-A") + store = _store_with([ + PortfolioItem(portfolio_id="pf-A", symbol="005930", cash_balance=0, asset_quantity=10), + ]) + broker = FakeBroker([BalanceItem(symbol="005930", hldg_qty=7)]) + with caplog.at_level(logging.WARNING, logger="trex_core.application.reconciliation"): + reconcile_positions( + store=store, broker=broker, + slot_repo=repo, instance_key="default", + warn_store=warn_store, + ) + log_text = caplog.text + assert "reconcile_warning set" in log_text + assert "case_code=C" in log_text + + +# =========================================================================== +# REQ-108: SlotState enum + ALLOWED_TRANSITIONS invariant (NFR-4) +# =========================================================================== + +def test_slot_state_enum_unchanged(): + """SlotState enum has exactly the same 5 values as before BAT-050.""" + from trex_core.domain.slot.state import SlotState + expected = {"inactive", "pending_buy", "holding", "pending_sell", "error"} + assert {s.value for s in SlotState} == expected + + +def test_allowed_transitions_unchanged(): + """ALLOWED_TRANSITIONS set must not have new entries from BAT-050.""" + from trex_core.domain.slot.state import ALLOWED_TRANSITIONS, SlotState + # Canonical count: 7 base + 4 to_error + 2 from_error = 13 + assert len(ALLOWED_TRANSITIONS) == 13 + # Spot-check: no new reconcile-warning-related transition + assert (SlotState.INACTIVE, SlotState.HOLDING) not in ALLOWED_TRANSITIONS + + +# NFR-2: short-term instance normal scenario (slot qty == broker qty) => no warn +def test_short_term_instance_normal_no_warn(): + """M1/M2 daily slot matching scenario — no false positive blocking (S-4, NFR-2).""" + repo = InMemorySlotRepository() + svc = SlotService(repo) + warn_store = InMemoryReconcileWarningStore() + + slot = _make_holding_slot(repo, svc, qty=10, portfolio_id="pf-A") + store = _store_with([ + PortfolioItem(portfolio_id="pf-A", symbol="005930", cash_balance=0, asset_quantity=10), + ]) + broker = FakeBroker([BalanceItem(symbol="005930", hldg_qty=10)]) # perfect match + + reconcile_positions( + store=store, broker=broker, + slot_repo=repo, instance_key="default", + warn_store=warn_store, + ) + reconcile_core_holdings( + slot_repo=repo, slot_service=svc, broker=broker, + instance_key="default", warn_store=warn_store, + ) + # No new warn_store entries + assert warn_store.list_warned() == set() + + +# NFR-3: reconcile does NOT auto-modify slot qty +def test_reconcile_no_auto_fix_slot_qty(): + """Reconcile must only detect and block — no auto-modification of slot qty.""" + repo = InMemorySlotRepository() + svc = SlotService(repo) + warn_store = InMemoryReconcileWarningStore() + + slot = _make_holding_slot(repo, svc, qty=10) + broker = FakeBroker([BalanceItem(symbol="005930", hldg_qty=5)]) + + reconcile_core_holdings( + slot_repo=repo, slot_service=svc, broker=broker, + instance_key="default", warn_store=warn_store, + ) + # Slot qty must remain 10 — not auto-corrected to 5 + updated_slot = repo.fetch_slot(slot.slot_id) + assert float(updated_slot.qty) == 10.0 + + +# =========================================================================== +# slot_to_dict unit tests for reconcile_warned field +# =========================================================================== + +def test_slot_to_dict_reconcile_warned_false_when_no_warn_store(): + """When warn_store is None, reconcile_warned=False (NFR-4 additive).""" + repo = InMemorySlotRepository() + svc = SlotService(repo) + slot = _make_holding_slot(repo, svc, qty=5) + row = slot_to_dict(slot, warn_store=None) + assert "reconcile_warned" in row + assert row["reconcile_warned"] is False + + +def test_slot_to_dict_reconcile_warned_true_when_warned(): + repo = InMemorySlotRepository() + svc = SlotService(repo) + slot = _make_holding_slot(repo, svc, qty=5) + warn_store = InMemoryReconcileWarningStore() + warn_store.set_warned(str(slot.slot_id), portfolio_id="pf-A", case_code="B") + row = slot_to_dict(slot, warn_store=warn_store) + assert row["reconcile_warned"] is True + + +def test_slot_to_dict_paused_and_warned_independent(): + """paused and reconcile_warned are independent fields.""" + repo = InMemorySlotRepository() + svc = SlotService(repo) + slot = _make_holding_slot(repo, svc, qty=5) + pause_store = InMemoryPauseStore() + pause_store.pause("pf-A") + warn_store = InMemoryReconcileWarningStore() + warn_store.set_warned(str(slot.slot_id), portfolio_id="pf-A", case_code="C") + row = slot_to_dict(slot, pause_store=pause_store, warn_store=warn_store) + assert row["paused"] is True + assert row["reconcile_warned"] is True diff --git a/tests/application/test_reconcile_warning_store.py b/tests/application/test_reconcile_warning_store.py new file mode 100644 index 0000000..0218cf8 --- /dev/null +++ b/tests/application/test_reconcile_warning_store.py @@ -0,0 +1,72 @@ +"""ReconcileWarningStore unit tests (REQ-102, BAT-050). + +Tests InMemoryReconcileWarningStore (store port contract). +PostgreSQL adapter is tested by DB-skipped integration tests. +""" +from __future__ import annotations + +import pytest + +from trex_core.application.portfolio import InMemoryReconcileWarningStore + + +def _store(): + return InMemoryReconcileWarningStore() + + +# AC-1 (REQ-102): set_warned records an entry; is_warned returns True. +def test_set_warned_is_warned_true(): + store = _store() + store.set_warned( + "slot-1", + portfolio_id="pf-A", + case_code="B", + actor="reconcile", + reason="slot_qty=10 broker_qty=5", + ) + assert store.is_warned("slot-1") is True + + +# AC-4 (REQ-102): clear_warned removes entry; is_warned returns False. +def test_clear_warned_returns_false(): + store = _store() + store.set_warned("slot-1", portfolio_id="pf-A", case_code="B") + store.clear_warned("slot-1") + assert store.is_warned("slot-1") is False + + +# AC-3 (REQ-102): duplicate set_warned on same slot_id => upsert (single entry). +def test_set_warned_upsert_same_slot(): + store = _store() + store.set_warned("slot-1", portfolio_id="pf-A", case_code="B", reason="first") + store.set_warned("slot-1", portfolio_id="pf-A", case_code="C", reason="second") + # After second set, is_warned still True — single entry (no duplicate row). + assert store.is_warned("slot-1") is True + assert store.list_warned() == {"slot-1"} + + +# AC-5 (REQ-102): list_warned returns set of warned slot_ids. +def test_list_warned_returns_set(): + store = _store() + store.set_warned("slot-1", portfolio_id="pf-A", case_code="B") + store.set_warned("slot-2", portfolio_id="pf-B", case_code="C") + assert store.list_warned() == {"slot-1", "slot-2"} + + +# is_warned on unknown slot => False. +def test_is_warned_unknown_slot_false(): + store = _store() + assert store.is_warned("nonexistent") is False + + +# clear_warned on unknown slot is a no-op (no exception). +def test_clear_warned_unknown_slot_noop(): + store = _store() + store.clear_warned("nonexistent") # must not raise + assert store.list_warned() == set() + + +# list_warned on empty store => empty set. +def test_list_warned_empty(): + store = _store() + assert store.list_warned() == set() diff --git a/trex_core/adapters/persistence/sql/016_create_slot_reconcile_warning.sql b/trex_core/adapters/persistence/sql/016_create_slot_reconcile_warning.sql new file mode 100644 index 0000000..e663962 --- /dev/null +++ b/trex_core/adapters/persistence/sql/016_create_slot_reconcile_warning.sql @@ -0,0 +1,12 @@ +-- BAT-050 / REQ-102: reconcile-warning durable store (dcy-034). +-- PK: slot_id (TEXT, UUID string). pause_store 동형 설계. +-- ON CONFLICT DO UPDATE: 동일 slot_id 재삽입 시 최신 값으로 갱신. +CREATE TABLE IF NOT EXISTS slot_reconcile_warning ( + slot_id TEXT PRIMARY KEY, + portfolio_id TEXT NOT NULL, + case_code TEXT NOT NULL, + actor TEXT NOT NULL DEFAULT 'reconcile', + reason TEXT NOT NULL DEFAULT '', + created_at TIMESTAMPTZ NOT NULL DEFAULT now(), + updated_at TIMESTAMPTZ NOT NULL DEFAULT now() +); diff --git a/trex_core/adapters/portfolio/__init__.py b/trex_core/adapters/portfolio/__init__.py index 172cf90..794288e 100644 --- a/trex_core/adapters/portfolio/__init__.py +++ b/trex_core/adapters/portfolio/__init__.py @@ -1,6 +1,12 @@ """portfolio-hub read adapters (REQ-027, dcy-005).""" from trex_core.adapters.portfolio.hub_read import PortfolioHubReadAdapter from trex_core.adapters.portfolio.pause_store import PostgreSQLPauseStore +from trex_core.adapters.portfolio.reconcile_warning_store import PostgreSQLReconcileWarningStore from trex_core.adapters.portfolio.stub_read import StubPortfolioRead -__all__ = ["PortfolioHubReadAdapter", "PostgreSQLPauseStore", "StubPortfolioRead"] +__all__ = [ + "PortfolioHubReadAdapter", + "PostgreSQLPauseStore", + "PostgreSQLReconcileWarningStore", + "StubPortfolioRead", +] diff --git a/trex_core/adapters/portfolio/reconcile_warning_store.py b/trex_core/adapters/portfolio/reconcile_warning_store.py new file mode 100644 index 0000000..e418b8c --- /dev/null +++ b/trex_core/adapters/portfolio/reconcile_warning_store.py @@ -0,0 +1,69 @@ +"""PostgreSQL-backed durable reconcile-warning store (REQ-102, BAT-050). + +pause_store.py와 동형 설계. PK: slot_id. case_code: 'B' | 'C'. +Survives daemon restart (dcy-034 NFR-1). +""" +from __future__ import annotations + +from datetime import datetime, timezone +from typing import Any + +from trex_core.adapters.persistence.postgresql import _require_psycopg + + +class PostgreSQLReconcileWarningStore: + """`slot_reconcile_warning` table CRUD. slot_id PK is the gate (REQ-102).""" + + def __init__(self, dsn: str, *, psycopg_module: Any = None) -> None: + self._psycopg = _require_psycopg(psycopg_module) + self._dsn = dsn + + def set_warned( + self, + slot_id: str, + *, + portfolio_id: str, + case_code: str, + actor: str = "reconcile", + reason: str = "", + ) -> None: + now = datetime.now(tz=timezone.utc) + with self._psycopg.connect(self._dsn, autocommit=False) as conn: + with conn.cursor() as cur: + cur.execute( + "INSERT INTO slot_reconcile_warning " + "(slot_id, portfolio_id, case_code, actor, reason, created_at, updated_at) " + "VALUES (%s, %s, %s, %s, %s, %s, %s) " + "ON CONFLICT (slot_id) DO UPDATE " + "SET portfolio_id = EXCLUDED.portfolio_id, " + " case_code = EXCLUDED.case_code, " + " actor = EXCLUDED.actor, " + " reason = EXCLUDED.reason, " + " updated_at = EXCLUDED.updated_at", + (slot_id, portfolio_id, case_code, actor, reason, now, now), + ) + conn.commit() + + def clear_warned(self, slot_id: str) -> None: + with self._psycopg.connect(self._dsn, autocommit=False) as conn: + with conn.cursor() as cur: + cur.execute( + "DELETE FROM slot_reconcile_warning WHERE slot_id = %s", + (slot_id,), + ) + conn.commit() + + def is_warned(self, slot_id: str) -> bool: + with self._psycopg.connect(self._dsn) as conn: + with conn.cursor() as cur: + cur.execute( + "SELECT 1 FROM slot_reconcile_warning WHERE slot_id = %s LIMIT 1", + (slot_id,), + ) + return cur.fetchone() is not None + + def list_warned(self) -> set[str]: + with self._psycopg.connect(self._dsn) as conn: + with conn.cursor() as cur: + cur.execute("SELECT slot_id FROM slot_reconcile_warning") + return {row[0] for row in cur.fetchall()} diff --git a/trex_core/application/intents.py b/trex_core/application/intents.py index 39f1b5d..57ed20e 100644 --- a/trex_core/application/intents.py +++ b/trex_core/application/intents.py @@ -14,6 +14,11 @@ dcy-020 (BAT-030): admission is asset-centric only — the legacy pool path cutover. Buy is keyed by slot_id (REQ-061 canonical; portfolio_id is the legacy dual-accept mapping) and admits FCFS under the `max_active_slots` cap M when configured (no cap when unset). + +BAT-050 / REQ-104: reconcile-warning gate added to _admit_buy/_admit_sell. +warn_store is Optional — when None, gate is skipped (backward compat). +Safety-sell / kill-switch / watchdog bypass this gate by design (OQ-B): +those paths call SlotService.sell() directly, not through IntentService. """ from __future__ import annotations @@ -104,6 +109,7 @@ class IntentService: instance_key: str = "default", max_active_slots: Optional[int] = None, default_order_timeout_sec: Optional[int] = None, + warn_store=None, # Optional[ReconcileWarningStore] — BAT-050 / REQ-104 ) -> None: self._svc = slot_service self._repo = slot_repo @@ -119,6 +125,9 @@ class IntentService: # dcy-022 / REQ-068: default timeout when intent omits timeout_sec. # None = OFF = indefinite wait (legacy behavior). Per-intent value overrides. self._default_order_timeout_sec = default_order_timeout_sec + # BAT-050 / REQ-104: reconcile-warning gate store (Optional). + # When None, gate is skipped (backward compat, NFR-4). + self._warn_store = warn_store # ------------------------------------------------------------ def lookup(self, intent_id: str) -> Optional[IntentDecision]: @@ -176,6 +185,23 @@ class IntentService: return IntentDecision(intent_id, "rejected", None, "duplicate_in_flight") return IntentDecision(intent_id, rec.status, rec.slot_id, rec.reason) + def _check_reconcile_warned(self, slot_id) -> Optional[IntentDecision]: + """BAT-050 / REQ-104: return rejected decision if slot is reconcile-warned. + + Returns None if not warned (gate passes). The warn_store check is best-effort: + if the store raises, we allow the intent through (fail-open for resilience). + Safety-sell / kill-switch / watchdog bypass this gate — they call + SlotService.sell() directly without going through IntentService (OQ-B). + """ + if self._warn_store is None: + return None + try: + if self._warn_store.is_warned(str(slot_id)): + return None # placeholder — intent_id unknown here; caller provides it + except Exception: # noqa: BLE001 - fail-open + pass + return None # not warned (or store error — fail-open) + def _admit_buy(self, intent: BuyIntent) -> IntentDecision: """dcy-020 / REQ-059·REQ-061 + dcy-021/REQ-066: activate or size up the asset's permanent slot. @@ -207,6 +233,19 @@ class IntentService: return IntentDecision(intent.intent_id, "rejected", None, "slot_id_or_portfolio_required") if slot is None: return IntentDecision(intent.intent_id, "rejected", None, miss_reason) + + # BAT-050 / REQ-104: reconcile-warning gate (external strategy intent only). + # Safety-sell / kill-switch / watchdog bypass this gate by design (OQ-B): + # those paths call SlotService.sell() directly. + if self._warn_store is not None: + try: + if self._warn_store.is_warned(str(slot.slot_id)): + return IntentDecision( + intent.intent_id, "rejected", None, "reconcile_warned" + ) + except Exception: # noqa: BLE001 - fail-open + pass + # dcy-021: a buy on a HOLDING slot is a position-sizing increase. is_increase = slot.status is SlotState.HOLDING if slot.status in (SlotState.PENDING_BUY, SlotState.PENDING_SELL): @@ -260,6 +299,19 @@ class IntentService: slot = self._repo.fetch_slot(intent.slot_id) if slot is None: return IntentDecision(intent.intent_id, "rejected", None, "slot_not_found") + + # BAT-050 / REQ-104: reconcile-warning gate for external strategy sell intent. + # Internal safety-sell / kill-switch / watchdog bypass this gate: they call + # SlotService.sell() / transit_slot() directly without IntentService (OQ-B). + if self._warn_store is not None: + try: + if self._warn_store.is_warned(str(slot.slot_id)): + return IntentDecision( + intent.intent_id, "rejected", None, "reconcile_warned" + ) + except Exception: # noqa: BLE001 - fail-open + pass + if slot.status is not SlotState.HOLDING: return IntentDecision( intent.intent_id, "rejected", None, f"slot_not_holding:{slot.status.value}" diff --git a/trex_core/application/messaging_handlers.py b/trex_core/application/messaging_handlers.py index 4c10132..516902f 100644 --- a/trex_core/application/messaging_handlers.py +++ b/trex_core/application/messaging_handlers.py @@ -16,6 +16,7 @@ from trex_core.application.intents import BuyIntent, IntentService, SellIntent from trex_core.application.messaging import RpcRequest, RpcResponse from trex_core.application.portfolio import ( PauseStore, + ReconcileWarningStore, SnapshotStore, slot_to_dict, ) @@ -220,6 +221,7 @@ def make_slots_rpc_handler( instance_key: str = "default", snapshot_store: Optional[SnapshotStore] = None, pause_store: Optional[PauseStore] = None, + warn_store: Optional[ReconcileWarningStore] = None, watchdog_store: Optional[WatchdogStore] = None, watchdog_timeout_sec: int = 120, ledger_outbox=None, @@ -261,12 +263,14 @@ def make_slots_rpc_handler( watchdog_store.update(str(s.slot_id)) # Build merged slot rows (REQ-074) + # BAT-050 / REQ-104: warn_store passed to slot_to_dict for reconcile_warned field. slot_rows = [ slot_to_dict( s, snapshot_store=snapshot_store, watchdog_store=watchdog_store, pause_store=pause_store, + warn_store=warn_store, watchdog_timeout_sec=watchdog_timeout_sec, ) for s in slots diff --git a/trex_core/application/portfolio.py b/trex_core/application/portfolio.py index b472eb9..08f47fe 100644 --- a/trex_core/application/portfolio.py +++ b/trex_core/application/portfolio.py @@ -5,10 +5,13 @@ snapshot store + asset-selection service. Domain stays free of HTTP and RabbitMQ deps (NFR-1). The snapshot is split between: - - in-memory `SnapshotStore` universe + cash/position + warnings (process-local; - warning is automatic/temporary, reset on restart) - - durable `PauseStore` portfolio_id -> paused (Postgres; manual/persistent, - survives restart and daily refresh — REQ-032) + - in-memory `SnapshotStore` universe + cash/position + warnings (process-local; + warning is automatic/temporary, reset on restart) + - durable `PauseStore` portfolio_id -> paused (Postgres; manual/persistent, + survives restart and daily refresh — REQ-032) + - durable `ReconcileWarningStore` slot_id -> reconcile-warning (Postgres; automatic, + set by reconcile B/C cases, cleared by sync/verify + — REQ-102, dcy-034) """ from __future__ import annotations @@ -246,6 +249,73 @@ class InMemoryKillSwitchStore: self._excluded.discard((portfolio_id, trading_date)) +# ---------------------------------------------------------------- reconcile-warning store (REQ-102) +# BAT-050 / dcy-034: durable reconcile-warning channel — distinct from pause (manual). +# Keyed by slot_id (TEXT UUID string). case_code: 'B' (slot↔broker qty mismatch) +# or 'C' (ledger↔broker mismatch). Survives restart (PostgreSQL-backed in production). + + +class ReconcileWarningStore(Protocol): + """Durable reconcile-warning overlay — slot_id PK (REQ-102, dcy-034).""" + + def set_warned( + self, + slot_id: str, + *, + portfolio_id: str, + case_code: str, + actor: str = "reconcile", + reason: str = "", + ) -> None: + ... + + def clear_warned(self, slot_id: str) -> None: + ... + + def is_warned(self, slot_id: str) -> bool: + ... + + def list_warned(self) -> "set[str]": + ... + + +class InMemoryReconcileWarningStore: + """Process-local reconcile-warning store for tests + CI (REQ-102).""" + + def __init__(self) -> None: + self._lock = threading.Lock() + # slot_id -> {"portfolio_id", "case_code", "actor", "reason"} + self._warned: dict[str, dict] = {} + + def set_warned( + self, + slot_id: str, + *, + portfolio_id: str, + case_code: str, + actor: str = "reconcile", + reason: str = "", + ) -> None: + with self._lock: + self._warned[slot_id] = { + "portfolio_id": portfolio_id, + "case_code": case_code, + "actor": actor, + "reason": reason, + } + + def clear_warned(self, slot_id: str) -> None: + with self._lock: + self._warned.pop(slot_id, None) + + def is_warned(self, slot_id: str) -> bool: + with self._lock: + return slot_id in self._warned + + def list_warned(self) -> "set[str]": + with self._lock: + return set(self._warned.keys()) + def slot_to_dict( s, @@ -253,6 +323,7 @@ def slot_to_dict( snapshot_store: "Optional[SnapshotStore]" = None, watchdog_store=None, pause_store: "Optional[PauseStore]" = None, + warn_store: "Optional[ReconcileWarningStore]" = None, watchdog_timeout_sec: int = 120, ) -> dict: """Merged slot row for trex.slots.req (REQ-073/074). @@ -260,7 +331,7 @@ def slot_to_dict( Carries slot/core state + hub asset data + watchdog + overlay flags. Field-level authority: slot/core = slot_id/status/qty/avg_price/entry_price/ forced_close_at; hub = asset_quantity/cash_balance; watchdog = watchdog{}; - overlay = paused/warned. strategy fields excluded (REQ-074 AC-5). + overlay = paused/warned/reconcile_warned. strategy fields excluded (REQ-074 AC-5). """ d = { "slot_id": str(s.slot_id), @@ -312,6 +383,14 @@ def slot_to_dict( paused = s.portfolio_id in pause_store.list_paused() d["paused"] = paused + # BAT-050 / REQ-104: reconcile_warned overlay (ReconcileWarningStore) — additive field. + # Bulk list_warned() called once per RPC (caller pre-fetches; see make_slots_rpc_handler). + # warn_store=None → reconcile_warned=False (backward compatible, NFR-4). + reconcile_warned = False + if warn_store is not None: + reconcile_warned = str(s.slot_id) in warn_store.list_warned() + d["reconcile_warned"] = reconcile_warned + return d diff --git a/trex_core/application/reconciliation.py b/trex_core/application/reconciliation.py index 19a4be2..bf7d9a7 100644 --- a/trex_core/application/reconciliation.py +++ b/trex_core/application/reconciliation.py @@ -1,10 +1,15 @@ -"""Position reconciliation between portfolio-hub and broker (REQ-031). +"""Position reconciliation between portfolio-hub and broker (REQ-031, REQ-103). The broker account is single (invariant B) so portfolio-hub quantities are aggregated to `symbol` before being compared with `BrokerPort.get_balance()`. Mismatches flip the asset's `warning` overlay; a subsequent successful match clears it automatically (in-memory only — pause is the durable channel for manual holds). + +BAT-050 / REQ-103: B-case (slot qty mismatch) and C-case (ledger mismatch) +now also set a durable reconcile-warning via ReconcileWarningStore (slot_id +keyed). The in-memory warning overlay is kept for backward compat; the durable +store is additive and Optional (None => warn-log-only, backward compat). """ from __future__ import annotations @@ -13,7 +18,7 @@ from typing import Optional from trex_core.application.alarm_emitter import AlarmEmitter from trex_core.application.broker_port import BrokerPort -from trex_core.application.portfolio import SnapshotStore +from trex_core.application.portfolio import ReconcileWarningStore, SnapshotStore from trex_core.domain.slot.state import SlotState _log = logging.getLogger(__name__) @@ -26,16 +31,24 @@ def reconcile_core_holdings( broker: BrokerPort, instance_key: str, alarm_emitter: Optional[AlarmEmitter] = None, + warn_store: Optional[ReconcileWarningStore] = None, ) -> dict[str, str]: - """dcy-020 / REQ-062 (BAT-029): surface core-slot holding ↔ broker divergence. + """dcy-020 / REQ-062 (BAT-029) + REQ-103 (BAT-050): surface core-slot holding + vs broker divergence and set durable reconcile-warning for B case. Broker balance is the reconcile ground truth. Decisions (no silent auto-fix, no auto-liquidation — issue #15): - - A. core holding but broker flat (qty 0) -> slot to `error` + WARN (operator resolve) - - C. both hold but qty differs -> WARN (mirror is non-authoritative) + - A. core holding but broker flat (qty 0) -> slot to `error` + WARN + CRITICAL alarm + - C. both hold but qty differs (B in REQ-103 naming) -> WARN + durable reconcile-warning - B. broker holds, no core holding slot -> WARN (unmanaged position) + + REQ-103 case codes: + - case_code='B': slot has holding but qty differs from broker (reconcile_core_holdings) + - case_code='C': ledger/hub qty differs from broker (reconcile_positions) + + warn_store: Optional — when None, WARN-log-only (backward compat, REQ-103 AC-5). Returns {key: 'error'|'qty_warning'|'ok'|'unmanaged_warning'} for telemetry. - (Liquidation qty = broker authoritative in execution dispatch is BAT-δ.)""" + """ broker_qty: dict[str, int] = { item.symbol: int(item.hldg_qty) for item in broker.get_balance() } @@ -65,15 +78,32 @@ def reconcile_core_holdings( ) except Exception: # noqa: BLE001 - never let reconcile crash the loop _log.exception("failed to error-quarantine slot %s", slot.slot_id) - elif slot.qty is not None and int(slot.qty) != bq: # C — qty mismatch - decisions[str(slot.slot_id)] = "qty_warning" + elif slot.qty is not None and int(slot.qty) != bq: # B case (REQ-103) — qty mismatch + slot_id_str = str(slot.slot_id) + decisions[slot_id_str] = "qty_warning" + # REQ-107: structured WARNING log for B case. _log.warning( - "qty mismatch: slot=%s symbol=%s core=%s broker=%d (mirror non-authoritative)", - slot.slot_id, sym, slot.qty, bq, + "reconcile_warning set: slot_id=%s portfolio_id=%s symbol=%s " + "case_code=B broker_qty=%d slot_qty=%s actor=reconcile", + slot_id_str, slot.portfolio_id, sym, bq, slot.qty, ) + # REQ-103 / BAT-050: durable reconcile-warning (case_code='B'). + if warn_store is not None: + try: + warn_store.set_warned( + slot_id_str, + portfolio_id=slot.portfolio_id or "", + case_code="B", + actor="reconcile", + reason=f"slot_qty={slot.qty} broker_qty={bq} symbol={sym}", + ) + except Exception: # noqa: BLE001 - never let reconcile crash the loop + _log.exception( + "failed to set reconcile_warning for slot %s", slot.slot_id + ) else: decisions[str(slot.slot_id)] = "ok" - for sym, bq in broker_qty.items(): # B — unmanaged broker position + for sym, bq in broker_qty.items(): # unmanaged broker position if bq > 0 and sym not in matched: decisions[f"broker:{sym}"] = "unmanaged_warning" _log.warning( @@ -83,11 +113,23 @@ def reconcile_core_holdings( return decisions -def reconcile_positions(*, store: SnapshotStore, broker: BrokerPort) -> dict[str, str]: - """Run one reconciliation pass. +def reconcile_positions( + *, + store: SnapshotStore, + broker: BrokerPort, + slot_repo=None, + instance_key: str = "default", + warn_store: Optional[ReconcileWarningStore] = None, +) -> dict[str, str]: + """Run one reconciliation pass (REQ-031 + REQ-103 BAT-050). Returns a `{portfolio_id: 'warning' | 'cleared' | 'ok'}` map for telemetry. The map is also reflected onto `store` via `set_warning(...)`. + + BAT-050 / REQ-103: when warn_store and slot_repo are provided, C-case mismatches + (ledger/hub qty vs broker) also set durable reconcile-warning on the corresponding + slot (portfolio_id -> slot lookup via slot_repo). When either is None, falls back + to in-memory warning only (backward compat, REQ-103 AC-5). """ broker_qty: dict[str, int] = { item.symbol: int(item.hldg_qty) for item in broker.get_balance() @@ -117,6 +159,32 @@ def reconcile_positions(*, store: SnapshotStore, broker: BrokerPort) -> dict[str ) store.set_warning(pid, True) decisions[pid] = "warning" + # REQ-103 / BAT-050: durable reconcile-warning for C case (case_code='C'). + if warn_store is not None and slot_repo is not None: + try: + slot = slot_repo.find_slot_by_portfolio(instance_key, pid) + if slot is not None: + slot_id_str = str(slot.slot_id) + # REQ-107: structured WARNING log for C case. + _log.warning( + "reconcile_warning set: slot_id=%s portfolio_id=%s " + "symbol=%s case_code=C hub_qty=%d broker_qty=%d actor=reconcile", + slot_id_str, pid, symbol, hub_total, broker_total, + ) + warn_store.set_warned( + slot_id_str, + portfolio_id=pid, + case_code="C", + actor="reconcile", + reason=( + f"hub_qty={hub_total} broker_qty={broker_total} " + f"symbol={symbol}" + ), + ) + except Exception: # noqa: BLE001 + _log.exception( + "failed to set reconcile_warning for portfolio_id=%s", pid + ) else: if was_warned: store.set_warning(pid, False) diff --git a/trex_core/application/snapshot_scheduler.py b/trex_core/application/snapshot_scheduler.py index 3d16c3c..5e298a3 100644 --- a/trex_core/application/snapshot_scheduler.py +++ b/trex_core/application/snapshot_scheduler.py @@ -4,6 +4,8 @@ Wakes at the configured KST time, fetches universe from PortfolioHubReadPort, swaps the SnapshotStore, then runs reconciliation. Option D `*_after` writes (REQ-030 AC-2/AC-3) are wired through `SnapshotStore.update_cash_position` but disabled at the ledger layer until portfolio-hub#8 ships. + +BAT-050 / REQ-103: reconcile now accepts warn_store for durable reconcile-warning. """ from __future__ import annotations @@ -18,6 +20,7 @@ from trex_core.application.portfolio import ( DegradedReason, PortfolioHubReadPort, PortfolioHubUnavailableError, + ReconcileWarningStore, SnapshotStore, ) from trex_core.application.reconciliation import reconcile_positions @@ -42,6 +45,7 @@ class SnapshotScheduler: slot_service=None, instance_key: str = "default", alarm_emitter: Optional[AlarmEmitter] = None, + warn_store: Optional[ReconcileWarningStore] = None, ) -> None: self._read = read_port self._store = store @@ -59,6 +63,8 @@ class SnapshotScheduler: self._last_universe_size: Optional[int] = None # dcy-033 / REQ-100: best-effort alarm emitter. self._alarm_emitter = alarm_emitter + # BAT-050 / REQ-103: durable reconcile-warning store (Optional). + self._warn_store = warn_store # ---- callable from a daemon thread loop -------------------------------- def run_forever(self, stop: threading.Event, *, tick_sec: float = 60.0) -> None: @@ -124,7 +130,14 @@ class SnapshotScheduler: self._store.swap(items) try: - reconcile_positions(store=self._store, broker=self._broker) + # BAT-050 / REQ-103: pass warn_store + slot_repo for C-case durable warning. + reconcile_positions( + store=self._store, + broker=self._broker, + slot_repo=self._slot_repo, + instance_key=self._instance_key, + warn_store=self._warn_store, + ) except Exception: # noqa: BLE001 _log.exception("reconciliation pass failed") if self._slot_repo is not None: @@ -135,10 +148,12 @@ class SnapshotScheduler: if self._slot_service is not None: try: from trex_core.application.reconciliation import reconcile_core_holdings + # BAT-050 / REQ-103: pass warn_store for B-case durable warning. reconcile_core_holdings( slot_repo=self._slot_repo, slot_service=self._slot_service, broker=self._broker, instance_key=self._instance_key, alarm_emitter=self._alarm_emitter, # dcy-033 / REQ-100 + warn_store=self._warn_store, # BAT-050 / REQ-103 ) except Exception: # noqa: BLE001 _log.exception("core-holding divergence reconcile failed") diff --git a/trex_core/runtime/daemon.py b/trex_core/runtime/daemon.py index 4e66280..deb2edd 100644 --- a/trex_core/runtime/daemon.py +++ b/trex_core/runtime/daemon.py @@ -41,6 +41,7 @@ from trex_core.adapters.persistence.postgresql import ( from trex_core.adapters.portfolio import ( PortfolioHubReadAdapter, PostgreSQLPauseStore, + PostgreSQLReconcileWarningStore, StubPortfolioRead, ) from trex_core.adapters.portfolio.killswitch_store import PostgreSQLKillSwitchStore @@ -158,13 +159,6 @@ class Daemon: instance_key=config.instance_key, strategy_state_store=self.strategy_state_store, ) - self.intent_service = IntentService( - self.slot_service, self.slot_repo, self.intent_store, - resolve_symbol=self._resolve_symbol, - instance_key=config.instance_key, - max_active_slots=config.max_active_slots, # dcy-020: asset-centric gate - default_order_timeout_sec=config.default_order_timeout_sec, # dcy-022 - ) self.broker = _build_broker(config) self.outbox = PostgreSQLLedgerOutbox(config.dsn) # BAT-008: portfolio-hub read + snapshot store + durable pause + scheduler. @@ -173,6 +167,16 @@ class Daemon: # BAT-010/011: per-slot watchdog (snapshot RPC writer, safety-sell reader). self.watchdog = WatchdogStore() self.pause_store = PostgreSQLPauseStore(config.dsn) + # BAT-050 / REQ-102: durable reconcile-warning store (slot_id PK). + self.warn_store = PostgreSQLReconcileWarningStore(config.dsn) + self.intent_service = IntentService( + self.slot_service, self.slot_repo, self.intent_store, + resolve_symbol=self._resolve_symbol, + instance_key=config.instance_key, + max_active_slots=config.max_active_slots, # dcy-020: asset-centric gate + default_order_timeout_sec=config.default_order_timeout_sec, # dcy-022 + warn_store=self.warn_store, # BAT-050 / REQ-104: reconcile-warning gate + ) # BAT-012: day-scoped kill-switch exclusion store + service. self.killswitch_store = PostgreSQLKillSwitchStore(config.dsn) self.portfolio_read = _build_portfolio_read(config) @@ -218,6 +222,7 @@ class Daemon: slot_service=self.slot_service, instance_key=config.instance_key, alarm_emitter=self.alarm_emitter, # dcy-033 / REQ-100 + warn_store=self.warn_store, # BAT-050 / REQ-103: durable reconcile-warning ) self.execution = ExecutionService( self.slot_service, self.slot_repo, self.broker, @@ -315,6 +320,7 @@ class Daemon: instance_key=self.config.instance_key, snapshot_store=self.snapshot_store, pause_store=self.pause_store, + warn_store=self.warn_store, # BAT-050 / REQ-104: reconcile_warned field watchdog_store=self.watchdog, watchdog_timeout_sec=self.config.safety_sell.watchdog_timeout_sec, ledger_outbox=self.outbox,