# 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로 재검증한다.