<!-- task=m-contract-codegen-baseline/01_schema_docs plan=0 tag=API -->

# Plan - API Schema Docs

## 이 파일을 읽는 구현 에이전트에게

`CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 반드시 채운다. 검증 명령을 실행하고 실제 stdout/stderr를 기록한 뒤 active 파일을 그대로 두고 리뷰 준비를 보고한다. 최종화는 code-review 스킬 전용이다.

## 배경

`Contract and Codegen Baseline`의 첫 작업은 ALT application protobuf가 후속 Go/Dart codegen의 흔들리지 않는 입력이 되도록 schema와 compatibility 기준을 고정하는 것이다. 현재 `.proto` 초안은 있지만 market bar 조회와 backtest result 조회 payload가 빠져 있고, README의 compatibility note도 초기 방향 네 줄에 머물러 있다. 이 subtask는 생성 도구를 만들기 전에 source schema와 책임 분리 문서를 먼저 닫는다.

## 분석 결과

### 읽은 파일

- `agent-roadmap/current.md`
- `agent-roadmap/phase/foundation-alignment/PHASE.md`
- `agent-roadmap/phase/foundation-alignment/milestones/contract-codegen-baseline.md`
- `agent-ops/rules/project/domain/contracts/rules.md`
- `packages/contracts/README.md`
- `packages/contracts/proto/alt/v1/common.proto`
- `packages/contracts/proto/alt/v1/market.proto`
- `packages/contracts/proto/alt/v1/backtest.proto`
- `bin/test`
- `bin/lint`
- `apps/client/test/widget_test.dart`

### 테스트 커버리지 공백

- `ListBarsRequest/ListBarsResponse` 추가: 기존 테스트 없음. `protoc` descriptor generation으로 schema compile을 검증한다.
- `GetBacktestResultRequest/GetBacktestResultResponse` 추가: 기존 테스트 없음. `protoc` descriptor generation으로 schema compile을 검증한다.
- compatibility/responsibility README 보강: 기존 테스트 없음. `rg --sort path`로 새 문서 앵커를 확인한다.

### 심볼 참조

- renamed/removed symbols: none.

### 분할 판단

분할 정책을 먼저 평가했다. `m-contract-codegen-baseline`은 protocol/schema, shell codegen, API parser map, Flutter parser map 경계가 분명해서 split이 필요하다.

- `01_schema_docs`: schema와 compatibility note. 선행 의존 없음.
- `02+01_codegen_check`: `01_schema_docs` 완료 후 Go/Dart codegen과 drift check.
- `03+02_api_parser_map`: `02+01_codegen_check` 완료 후 API parser map.
- `04+02_client_parser_map`: `02+01_codegen_check` 완료 후 client parser map.

### 범위 결정 근거

이 subtask는 `packages/contracts/**`만 다룬다. generated output, `bin/*`, `go.work`, `services/api/**`, `apps/client/**` 변경은 후속 subtask가 맡는다.

### 빌드 등급

build=`cloud-G06`, review=`cloud-G06`. Public protobuf schema 변경이고 기존 schema 테스트가 없어서 protocol/schema 리뷰가 필요하다.

## 구현 체크리스트

- [ ] [API-1] Market/backtest MVP 조회 payload를 additive protobuf change로 보강하고 descriptor compile로 검증한다.
- [ ] [API-2] contracts README에 compatibility, field number, versioning, proto-socket transport 책임 분리를 문서화한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

### [API-1] Market/backtest MVP 조회 payload

#### 문제

`packages/contracts/proto/alt/v1/market.proto:28`에는 `Bar` payload가 있지만 `packages/contracts/proto/alt/v1/market.proto:39` 이후 조회 request/response가 instruments에만 있다. `packages/contracts/proto/alt/v1/backtest.proto:51`에는 `BacktestResult`가 있지만 result 조회 request/response가 없다.

Before:

```proto
// packages/contracts/proto/alt/v1/market.proto:39
message ListInstrumentsRequest {
  Market market = 1;
  string provider = 2;
}

message ListInstrumentsResponse {
  repeated Instrument instruments = 1;
}
```

```proto
// packages/contracts/proto/alt/v1/backtest.proto:51
message BacktestResult {
  string run_id = 1;
  Price starting_cash = 2;
  Price ending_equity = 3;
}
```

해결 후 형태:

```proto
message ListBarsRequest {
  string instrument_id = 1;
  Timeframe timeframe = 2;
  int64 from_unix_ms = 3;
  int64 to_unix_ms = 4;
}

message ListBarsResponse {
  repeated Bar bars = 1;
}

message GetBacktestResultRequest {
  string run_id = 1;
}

message GetBacktestResultResponse {
  BacktestResult result = 1;
}
```

#### 해결 방법

기존 field number는 변경하지 않는다. 새 메시지는 additive로 추가하고 package/go_package는 `alt.v1`과 `git.toki-labs.com/toki/alt/packages/contracts/gen/go/alt/v1;altv1`를 유지한다.

#### 수정 파일 및 체크리스트

- [ ] `packages/contracts/proto/alt/v1/market.proto`: `ListBarsRequest`, `ListBarsResponse` 추가.
- [ ] `packages/contracts/proto/alt/v1/backtest.proto`: `GetBacktestResultRequest`, `GetBacktestResultResponse` 추가.

#### 테스트 작성

별도 테스트 파일은 작성하지 않는다. 아직 generated output이 없으므로 schema compile을 중간 검증으로 사용한다.

#### 중간 검증

```bash
protoc -I packages/contracts/proto --descriptor_set_out=/tmp/alt-contracts-schema.pb --include_imports packages/contracts/proto/alt/v1/common.proto packages/contracts/proto/alt/v1/market.proto packages/contracts/proto/alt/v1/backtest.proto
```

기대 결과: exit 0, `/tmp/alt-contracts-schema.pb` 생성.

### [API-2] Compatibility and transport responsibility note

#### 문제

`packages/contracts/README.md:7`의 `Initial contract direction`은 방향만 있고, additive change, field number, versioning, proto-socket transport proto와 ALT application proto 책임 분리 기준이 실행 규칙으로 정리되어 있지 않다.

Before:

```markdown
<!-- packages/contracts/README.md:7 -->
Initial contract direction:

- additive protobuf changes first
- explicit handshake/version messages because proto-socket protocol `0.1` does not carry an application version field
- market-neutral models with Korea market daily bars as the MVP path
- generated clients should be derived from `proto/` sources, not edited by hand
```

해결 후 형태:

```markdown
## Compatibility

- Prefer additive fields and messages.
- Never renumber existing fields.
- Reserve removals or semantic rewrites for an explicit version bump.

## Transport Boundary

- `proto-socket` owns `PacketBase`, heartbeat, nonce, and transport framing.
- ALT `alt.v1` messages are application payloads carried in `PacketBase.data`.
```

#### 해결 방법

README를 짧은 운영 규칙으로 보강한다. codegen 명령 문서는 후속 `02+01_codegen_check`에서 실제 script와 함께 추가한다.

#### 수정 파일 및 체크리스트

- [ ] `packages/contracts/README.md`: `Compatibility` 섹션 추가.
- [ ] `packages/contracts/README.md`: `Transport Boundary` 섹션 추가.
- [ ] `packages/contracts/README.md`: MVP schema 목록에 `ListBars*`, `GetBacktestResult*`를 포함.

#### 테스트 작성

문서 변경이므로 테스트 파일은 작성하지 않는다. deterministic search로 앵커 존재를 확인한다.

#### 중간 검증

```bash
rg --sort path -n "Compatibility|Transport Boundary|ListBarsRequest|GetBacktestResultRequest" packages/contracts
```

기대 결과: README와 proto 파일에서 모든 앵커가 검색된다.

## 수정 파일 요약

| 파일 | 항목 |
|------|------|
| `packages/contracts/proto/alt/v1/market.proto` | API-1 |
| `packages/contracts/proto/alt/v1/backtest.proto` | API-1 |
| `packages/contracts/README.md` | API-2 |

## 최종 검증

```bash
protoc -I packages/contracts/proto --descriptor_set_out=/tmp/alt-contracts-schema.pb --include_imports packages/contracts/proto/alt/v1/common.proto packages/contracts/proto/alt/v1/market.proto packages/contracts/proto/alt/v1/backtest.proto
rg --sort path -n "Compatibility|Transport Boundary|ListBarsRequest|GetBacktestResultRequest" packages/contracts
bin/test
```

기대 결과: 모든 명령 exit 0. `bin/test`의 Go test cache output은 이 subtask에서 허용한다.

모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.
