<!-- task=m-us-market-expansion/03+01_shared_query_surface plan=0 tag=US_QUERY -->

# Code Review Reference - US_QUERY

> **[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/03+01_shared_query_surface, plan=0, tag=US_QUERY

## Roadmap Targets

- Milestone: `agent-roadmap/phase/trading-expansion/milestones/us-market-expansion.md`
- Task ids:
  - `shared-query`: 한국장과 미국장이 같은 query/contract pattern을 공유
- Completion mode: check-on-pass

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

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

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

---

## 구현 항목별 완료 여부

| 항목 | 완료 여부 |
|------|---------|
| [US_QUERY-1] API And Worker US Query Contract Tests | [x] |
| [US_QUERY-2] Operator US Headless Query Fixture | [x] |

## 구현 체크리스트

- [x] [US_QUERY-1] API/worker socket tests가 `Market_US`와 provider filter로 US instruments를 같은 ListInstruments contract에서 조회하는지 검증한다. 검증: market selector만 바꿔도 공통 query path를 사용한다.
- [x] [US_QUERY-2] CLI headless fixture에 US market data status query를 추가하고 expected JSONL을 잠근다.
- [x] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

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

- [x] 판정을 append한다.
- [x] active review/plan 파일을 `*.log`로 아카이브한다.
- [x] PASS이면 `complete.log` 작성 후 archive 이동한다.
- [x] PASS이면 완료 이벤트 메타데이터를 보고한다.
- [ ] WARN/FAIL이면 후속 plan/review 또는 `USER_REVIEW.md`를 작성한다.

## 계획 대비 변경 사항

- 없음. 계획대로 API 및 Worker 소켓 테스트에 미국장(US) 케이스를 추가하고, CLI 헤드리스 피쳐에 미국장 시나리오 파일과 기대 JSONL 출력을 보강하여 정상 검증을 마쳤습니다.

## 주요 설계 결정

- 미국장 instrument mapping 및 bar query에 기존과 동일한 Protobuf Contract 및 Query Path를 재사용하도록 설계하여 shared-query 마일스톤 목적을 온전히 달성했습니다.
- CLI 헤드리스 검증 시나리오에 미국(US) 시장과 나스닥(NASDAQ) 거래소 설정을 반영하여 KR/US 시장이 일관성 있게 공통 커맨드로 동작함을 검증하였습니다.

## 사용자 리뷰 요청

- 상태: 없음
- 사유 유형: 없음
- 결정 필요: 없음
- 차단 근거: 없음
- 실행한 검증/명령: 없음
- 자동 후속 불가 이유: 없음
- 재개 조건: 없음

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

- 새 query API를 만들지 않고 기존 contract path를 쓰는지 확인한다.
- `market: us`만 바꿔 동일한 operator workflow가 실행되는지 확인한다.
- expected JSONL이 실제 runner output과 일치하는지 확인한다.

## 검증 결과

### US_QUERY-1 중간 검증
```text
$ go test -count=1 ./services/api/internal/socket ./services/worker/internal/socket
ok      git.toki-labs.com/toki/alt/services/api/internal/socket 0.014s
ok      git.toki-labs.com/toki/alt/services/worker/internal/socket      0.059s
```

### US_QUERY-2 중간 검증
```text
$ go test -count=1 ./apps/cli/internal/operator
ok      git.toki-labs.com/toki/alt/apps/cli/internal/operator   0.170s
```

### 최종 검증
```text
$ go test -count=1 ./services/api/internal/socket ./services/worker/internal/socket ./apps/cli/internal/operator
ok      git.toki-labs.com/toki/alt/services/api/internal/socket 0.014s
ok      git.toki-labs.com/toki/alt/services/worker/internal/socket      0.059s
ok      git.toki-labs.com/toki/alt/apps/cli/internal/operator   0.170s

$ go test -count=1 ./services/api/... ./services/worker/...
?       git.toki-labs.com/toki/alt/services/api/cmd/alt-api     [no test files]
ok      git.toki-labs.com/toki/alt/services/api/internal/config 0.003s
ok      git.toki-labs.com/toki/alt/services/api/internal/contracts      0.005s
ok      git.toki-labs.com/toki/alt/services/api/internal/socket 0.011s
ok      git.toki-labs.com/toki/alt/services/api/internal/workerclient   0.414s
ok      git.toki-labs.com/toki/alt/services/worker/cmd/alt-worker       0.008s
?       git.toki-labs.com/toki/alt/services/worker/cmd/alt-worker-data-check   [no test files]
ok      git.toki-labs.com/toki/alt/services/worker/cmd/alt-worker-migrate      0.007s
ok      git.toki-labs.com/toki/alt/services/worker/internal/backtest    0.007s
ok      git.toki-labs.com/toki/alt/services/worker/internal/config      0.005s
ok      git.toki-labs.com/toki/alt/services/worker/internal/contracts   0.010s
ok      git.toki-labs.com/toki/alt/services/worker/internal/jobs        0.007s
ok      git.toki-labs.com/toki/alt/services/worker/internal/marketdata/datacheck0.007s
ok      git.toki-labs.com/toki/alt/services/worker/internal/marketdata/importer0.005s
ok      git.toki-labs.com/toki/alt/services/worker/internal/papertrading       0.003s
ok      git.toki-labs.com/toki/alt/services/worker/internal/providers/kis      0.013s
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.060s
?       git.toki-labs.com/toki/alt/services/worker/internal/storage     [no test files]
ok      git.toki-labs.com/toki/alt/services/worker/internal/storage/postgres   0.061s
?       git.toki-labs.com/toki/alt/services/worker/internal/storage/postgres/sqlc       [no test files]

$ bin/test
All tests passed!

$ git diff --check
(no output)
```

---

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

## 코드리뷰 결과

- 종합 판정: PASS
- 차원별 평가:
  - Correctness: Pass
  - Completeness: Pass
  - Test coverage: Pass
  - API contract: Pass
  - Code quality: Pass
  - Plan deviation: Pass
  - Verification trust: Pass
- 발견된 문제: 없음
- 리뷰어 검증:
  - `gofmt` 필요 파일 1개(`apps/cli/internal/operator/handoff_test.go`)는 동작 변경 없이 정리했다.
  - `go test -count=1 ./services/api/internal/socket ./services/worker/internal/socket ./apps/cli/internal/operator` PASS
  - `go test -count=1 ./services/api/... ./services/worker/...` PASS
  - `bin/test` PASS
  - `git diff --check` PASS
  - `git diff --name-only -- '*.go' | xargs -r gofmt -l` PASS
- 다음 단계: PASS이므로 `complete.log` 작성 후 task archive로 이동하고, `m-us-market-expansion` 완료 이벤트 메타데이터를 보고한다.
