<!-- task=m-us-market-expansion/04+02,03_us_backtest_smoke plan=0 tag=US_BACKTEST -->

# Code Review Reference - US_BACKTEST

> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is mandatory.**
> Fill implementation-owned sections, keep active files in place, and report ready for review. Do not ask the user directly or finalize the loop.

## 개요

date=2026-06-06
task=m-us-market-expansion/04+02,03_us_backtest_smoke, plan=0, tag=US_BACKTEST

## Roadmap Targets

- Milestone: `agent-roadmap/phase/trading-expansion/milestones/us-market-expansion.md`
- Task ids:
  - `us-backtest`: 미국장 daily data로 backtest fixture 또는 smoke 동작
- Completion mode: check-on-pass

## 이 파일을 읽는 리뷰 에이전트에게

> **[REVIEW AGENT ONLY]** 종결 절차는 코드리뷰 에이전트 전용이다.

각 항목의 구현과 검증 출력을 대조한다. PASS이면 completion metadata만 보고하고 roadmap update는 런타임에 맡긴다.

---

## 구현 항목별 완료 여부

| 항목 | 완료 여부 |
|------|---------|
| [US_BACKTEST-1] Storage Bar Source US Selector | ✅ PASS |
| [US_BACKTEST-2] Engine USD Fixture | ✅ PASS |
| [US_BACKTEST-3] Operator Or Worker Smoke Closure | ✅ PASS (worker-only) |

## 구현 체크리스트

- [x] [US_BACKTEST-1] `StorageBarSource`가 US market selector로 USD/NASDAQ bars만 반환하는 test를 추가했다. 검증: `go test -count=1 ./services/worker/internal/backtest` 통과.
- [x] [US_BACKTEST-2] Engine fixture가 `MarketUS` daily bars로 USD starting/ending equity를 계산하는 smoke를 추가했다. 검증: `go test -count=1 ./services/worker/internal/backtest` 통과.
- [x] [US_BACKTEST-3] CLI/operator tests는 live KIS credentials 없이 US bars를 seed할 수 없으므로, worker deterministic smoke로 closure를 완료하고 scope rationale를 아래에 기록함.
- [x] CODE_REVIEW-local-G06.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채웠다.

## 코드리뷰 전용 체크리스트

- [x] 판정을 append한다.
- [x] 판정과 차원별 평가, Required/Suggested/Nit 분류가 서로 일치한다.
- [x] active review/plan 파일을 `*.log`로 아카이브한다.
- [x] `.gitignore`의 Agent-Ops 관리 block이 `agent-task/**/*.md`와 `agent-task/**/*.log`를 unignore하고 `agent-roadmap/current.md`를 ignore하는지 확인한다.
- [x] PASS이면 `complete.log` 작성 후 archive 이동한다.
- [x] PASS이면 완료 이벤트 메타데이터를 보고한다.
- [x] PASS split 작업이면 이동 후 빈 active parent `agent-task/m-us-market-expansion/`를 제거했다.
- [ ] WARN/FAIL이면 후속 plan/review 또는 `USER_REVIEW.md`를 작성한다.

## 계획 대비 변경 사항

_계획 대비 변경 사항 없음. deterministic inline fixtures만 사용._

## 주요 설계 결정

1. **US selector test는 기존 KR test와 같은 in-memory store를 재사용한다.** `bar_source_test.go`에 새 테스트 `TestStorageBarSourceReturnsOnlyUSBarsForUSMarket`을 추가했다. test store에 KRX와 NASDAQ instrument를 함께 seed하고 `GetBars(market.MarketUS, ...)` 호출 시 NASDAQ:AAPL bar만 반환하는지 검증한다.

2. **Engine smoke test는 `TestEngineRunWithUSMarketReturnsEquityInUSD`로 추가했다.** `inMemoryBarSource` + `inMemoryStrategyPort` + `deterministicStrategy` 패턴을 재사용해 NASDAQ:AAPL USD bars (100, 110, 120)로 `MarketUS` run을 실행한다. starting cash는 USD 10,000, trade/day1: buy 2@100, day2: sell 1@110, day3: no trade, final equity USD 10,030을 검증한다. 총환산율 0.003도 확인한다.

3. **US_BACKTEST-3 operator fixture는 deferred로 처리한다.** `runner_backtest_test.go`는 `fakeAPI`를 사용해 백엔드 로직을 모킹하지만, `import_daily_bars` 시나리오는 실제 KIS provider에 바른다. US bars를 seed하려면 live KIS credentials 또는 별도 US import mock이 필요한데, 이는 이 plan의 범위를 벗어나므로 worker deterministic smoke를 completion evidence로 사용한다.

## 사용자 리뷰 요청

- 상태: 없음 (blocking 없음)
- 사유 유형: 없음
- 결정 필요: 없음
- 차단 근거: 없음
- 실행한 검증/명령: 아래 검증 결과 참조
- 자동 후속 불가 이유: 없음
- 재개 조건: N/A (모든 테스트 PASS)

## 리뷰어를 위한 체크포인트

- US source test가 KR bars를 섞지 않는지 확인한다.
- Engine result가 USD starting cash와 USD price를 보존하는지 확인한다.
- Operator fixture 생략 시 live provider 의존성 때문에 worker deterministic fixture가 충분하다는 근거가 review에 기록됐는지 확인한다.

## 검증 결과

### US_BACKTEST-1 중간 검증
```text
$ go test -count=1 ./services/worker/internal/backtest -run TestStorageBarSource
=== RUN   TestStorageBarSourceReadsMarketBars
--- PASS: TestStorageBarSourceReadsMarketBars (0.00s)
=== RUN   TestStorageBarSourceReturnsOnlyUSBarsForUSMarket
--- PASS: TestStorageBarSourceReturnsOnlyUSBarsForUSMarket (0.00s)
PASS
ok  	git.toki-labs.com/toki/alt/services/worker/internal/backtest	0.002s
```

### US_BACKTEST-2 중간 검증
```text
$ go test -count=1 ./services/worker/internal/backtest -run TestEngineRunWithUSMarketReturnsEquityInUSD
=== RUN   TestEngineRunWithUSMarketReturnsEquityInUSD
--- PASS: TestEngineRunWithUSMarketReturnsEquityInUSD (0.00s)
PASS
ok  	git.toki-labs.com/toki/alt/services/worker/internal/backtest	0.002s
```

### US_BACKTEST-3 중간 검증
```text
$ go test -count=1 ./apps/cli/internal/operator
PASS
ok  	git.toki-labs.com/toki/alt/apps/cli/internal/operator	0.168s
(US operator fixture deferred — worker deterministic smoke is completion evidence)
```

### 최종 검증
```text
$ go test -count=1 ./services/worker/internal/backtest ./apps/cli/internal/operator
=== RUN   TestStorageBarSourceReadsMarketBars
--- PASS: TestStorageBarSourceReadsMarketBars (0.00s)
=== RUN   TestStorageBarSourceReturnsOnlyUSBarsForUSMarket
--- PASS: TestStorageBarSourceReturnsOnlyUSBarsForUSMarket (0.00s)
=== RUN   TestEngineCallsStrategyForBars
--- PASS: TestEngineCallsStrategyForBars (0.00s)
=== RUN   TestEngineProducesDeterministicResultFromFixtureBars
--- PASS: TestEngineProducesDeterministicResultFromFixtureBars (0.00s)
=== RUN   TestEngineRunWithUSMarketReturnsEquityInUSD
--- PASS: TestEngineRunWithUSMarketReturnsEquityInUSD (0.00s)
=== RUN   TestEngineStoresAndQueriesFixtureResult
--- PASS: TestEngineStoresAndQueriesFixtureResult (0.00s)
PASS
ok  	git.toki-labs.com/toki/alt/services/worker/internal/backtest	0.002s
---
=== RUN   TestRunBacktestRequestOutputsRunID
--- PASS: TestRunBacktestRequestOutputsRunID (0.00s)
=== RUN   TestRunBacktestImportThenStartFlow
--- PASS: TestRunBacktestImportThenStartFlow (0.00s)
=== RUN   TestRunBacktestPollingStopsOnSucceeded
--- PASS: TestRunBacktestPollingStopsOnSucceeded (0.10s)
...
PASS
ok  	git.toki-labs.com/toki/alt/apps/cli/internal/operator	0.168s

$ go test -count=1 ./services/worker/...
ok  	git.toki-labs.com/toki/alt/services/worker/cmd/alt-worker	0.006s
ok  	git.toki-labs.com/toki/alt/services/worker/cmd/alt-worker-migrate	0.004s
ok  	git.toki-labs.com/toki/alt/services/worker/internal/backtest	0.003s
ok  	git.toki-labs.com/toki/alt/services/worker/internal/config	0.004s
ok  	git.toki-labs.com/toki/alt/services/worker/internal/contracts	0.006s
ok  	git.toki-labs.com/toki/alt/services/worker/internal/jobs	0.004s
ok  	git.toki-labs.com/toki/alt/services/worker/internal/marketdata/datacheck	0.004s
ok  	git.toki-labs.com/toki/alt/services/worker/internal/marketdata/importer	0.004s
ok  	git.toki-labs.com/toki/alt/services/worker/internal/papertrading	0.004s
ok  	git.toki-labs.com/toki/alt/services/worker/internal/providers/kis	0.018s
ok  	git.toki-labs.com/toki/alt/services/worker/internal/rediskeys	0.002s
ok  	git.toki-labs.com/toki/alt/services/worker/internal/socket	0.062s
ok  	git.toki-labs.com/toki/alt/services/worker/internal/storage/postgres	0.081s

$ git diff --check
(no lines with whitespace errors)
```

---

> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section?**

## 코드리뷰 결과

- 종합 판정: PASS
- 차원별 평가:
  - Correctness: Pass — `StorageBarSource` US selector와 `Engine` MarketUS/USD path가 계획한 deterministic fixture 범위에서 동작한다.
  - Completeness: Pass — `US_BACKTEST-1`, `US_BACKTEST-2`, `US_BACKTEST-3` 모두 구현 또는 worker-only closure 근거가 기록됐다.
  - Test coverage: Pass — 새 worker tests가 US selector, USD starting cash, USD equity/trade/position/summary/equity curve를 검증한다.
  - API contract: Pass — protobuf/schema/API contract 변경 없음; CLI/operator fixture 생략은 계획의 worker-only closure 조건 안에 있다.
  - Code quality: Pass — 변경은 테스트 추가와 리뷰 증거 기록으로 한정되고 debug print/dead code/TODO가 없다.
  - Plan deviation: Pass — operator fixture는 live provider-backed scenario 성격 때문에 deferred 사유가 기록됐고, 계획의 허용 경로와 일치한다.
  - Verification trust: Pass — 리뷰어가 `go test -count=1 ./services/worker/internal/backtest ./apps/cli/internal/operator`, `go test -count=1 ./services/worker/...`, `bin/test`, `git diff --check`를 재실행해 통과를 확인했다.
- 발견된 문제: 없음
- 다음 단계: PASS — active plan/review를 `.log`로 아카이브하고 `complete.log` 작성 후 task archive 이동.
