trex-core/docs/srs/Exception/req-120_kis-balance-auth-failure-fail-loud-lifecycle-policy.md

REQ-120: KIS balance 인증 실패 fail-loud 및 broker/token lifecycle 정책

• Status: Approved
• Type: Exception
• Priority: High
• Owner: trex-core-dev

Intent

• 현재 KIS balance 조회의 token/auth/transport 실패가 빈 잔고와 같은 []로 해석되면 broker_qty_zero, sync skip 또는 잘못된 reconcile 판단으로 이어질 수 있다.
• 실제 empty holdings와 broker-read 실패를 명확히 분리하고, fetched credential operator 경로의 token/broker lifecycle을 throttle-safe·secret-safe 제약 아래 설계 가능하게 한다.

Requirement

• 시스템은 KIS token issuance, authentication/authorization, HTTP transport 및 malformed balance response 실패를 성공적인 empty balance와 구별되는 typed 또는 동등하게 식별 가능한 sanitized failure로 표면화해야 한다.
• sync/verify를 포함한 operator broker-read 경로는 이러한 실패 시 비0 종료하고 broker_qty_zero, sync skip, verify success 또는 slot state write를 생성하지 않아야 한다.
• fetched credential broker/token lifecycle의 구현 설계는 다음 제약을 충족해야 한다: ownership 경계와 재사용 범위가 명시될 것, 반복 read가 매번 fresh broker/token을 강제해 throttle을 유발하지 않을 것, retry 여부·횟수·backoff/즉시 실패 기준이 failure class별로 문서화될 것, token/credential은 로그·CLI JSON·fixture에 기록되지 않을 것.

Acceptance Criteria

1. Given KIS token issuance, auth/authorization, transport 또는 malformed response failure fixture, When get_balance()와 sync --dry-run 또는 verify를 실행하면, Then 성공 empty balance와 구별되는 sanitized failure가 반환되고 CLI는 비0으로 종료한다.
2. Given AC-1의 각 failure, When 결과와 persistence/log side effect를 검사하면, Then broker_qty_zero, sync skip, verify success, slot state write 또는 empty-holdings 판정이 생성되지 않는다.
3. Given 정상적으로 성공한 KIS balance response가 실제로 holdings 없이 반환됨, When 동일 경로를 실행하면, Then success empty balance semantics는 auth/transport failure와 구별되어 기존 정상 판단이 유지된다.
4. Given 반복 fetched-credential broker read와 token throttle 재현 fixture, When 구현된 lifecycle 정책을 적용해 읽기를 수행하면, Then fresh-object 생성이 반복되어 throttle을 유발하는 경로에 의존하지 않고, throttle이 발생해도 fail-loud semantics가 유지된다.
5. Given lifecycle 설계 검토, When implementation-ready decision을 기록하면, Then ownership/reuse scope, cache 또는 reuse 무효화 조건, failure class별 retry/no-retry 정책 및 regression test seam이 명시되며 process-local reuse, shared cache 또는 다른 공통 provider 중 특정 방식을 사전 근거 없이 요구하지 않는다.
6. Given 오류 출력, 구조화 로그 및 테스트 artifact, When auth/token failure를 검증하면, Then token, authorization header, app key/app secret, raw credential payload 및 raw account number가 노출되지 않는다.

Impacted Area

• Docs: docs/runtime-flows.md, docs/interface-contract.md, docs/operations.md, docs/srs/Non-Functional/req-115_daystart-intraday-resilience-credential-cache.md
• Modules: trex_core/adapters/broker/kis.py, trex_core/runtime/cli.py, trex_core/runtime/daemon.py, 공통 broker provider/factory
• Tests: KIS adapter unit tests; CLI failure/no-write tests; lifecycle/throttle regression fixture; sanitized logging/JSON assertions

Notes

• Source Discovery: docs/discovery/dcy-037_20260714_operator-broker-truth-and-managed-slot-divergence-hotfix.md (FR-2~3, OQ-2; GitHub #40).
• REQ-115의 day-start/intraday cache 목표와 충돌하지 않아야 한다. 본 REQ는 OQ-2의 구현 방식을 확정하지 않고, 설계 선택의 안전 제약과 검증 가능한 결과를 고정한다.
• Production live sync target 또는 실행은 OQ-3 release gate로서 범위 밖이다.

Change Log

CHG-20260714-01

• Date: 2026-07-14
• Author: delivery-runner

Change Summary

• dcy-037 #40의 auth/token failure empty-balance masking과 OQ-2 lifecycle 제약을 Proposed REQ로 초안화했다.

Intent

• false-zero 기반 상태 수렴을 막고 lifecycle 구현 선택을 근거 기반 설계 단계로 남긴다.

Acceptance Criteria Delta

• Added:
  • fail-loud/no-write, true-empty 분리, throttle 회귀, lifecycle decision constraints 및 secret-safe 증거.
• Updated:
  • 없음.
• Removed:
  • 없음.

Impacted Area Delta

• Docs:
  • runtime/interface/operations 및 REQ-115 정합 대상.
• Modules:
  • KIS adapter와 daemon/CLI broker-read 경계.
• Tests:
  • failure injection, no-write, throttle 및 redaction regression.

Delivery Trace Delta

• Batches:
  • none (draft only; dcy-037 emergency scope의 향후 입력).
• Releases:
  • none (production 접근 또는 live sync 실행 없음).

Revalidation Impact

• Reverification Needed: yes
• Existing Implementation Invalidated: no
• Status Recommendation: keep-current
• Follow-up Action: confirm-req 전 현재 KIS token cache와 daemon/CLI lifetime evidence를 설계 결정에 연결한다.

Validation Plan

• mocked KIS failure classes와 repeated-read throttle fixture에서 exit code, semantic result, no-write 및 artifact redaction을 확인한다.

CHG-20260714-02

• Date: 2026-07-14
• Author: Justin (TREX lead)

Change Summary

• Proposed에서 Approved로 승인했다.

Intent

• dcy-037 #40의 false-zero 방지와 OQ-2 lifecycle 설계 제약을 구현 가능한 safety contract로 확정한다.

Acceptance Criteria Delta

• Added:
  • 없음.
• Updated:
  • 없음.
• Removed:
  • 없음.

Impacted Area Delta

• Docs:
  • 없음.
• Modules:
  • 없음.
• Tests:
  • 없음.

Delivery Trace Delta

• Batches:
  • dcy-037의 #39/#40/#41 단일 emergency batch (아직 미생성).
• Releases:
  • none; sync --live는 별도 release approval gate 유지.

Revalidation Impact

• Reverification Needed: yes
• Existing Implementation Invalidated: no
• Status Recommendation: keep-current
• Follow-up Action: batch design에서 lifecycle ownership/reuse와 failure-class별 retry 정책을 code evidence로 결정한다.

Validation Plan

• batch verification과 독립 QC에서 failure/no-write·true-empty·throttle·redaction AC를 실제 fixture로 재검증한다.