<!-- task=m-backtest-multi-timeframe-coverage/01_monthly_worker_core plan=1 tag=REVIEW_API -->
# Plan - REVIEW_API

## Meta

- Task: m-backtest-multi-timeframe-coverage/01_monthly_worker_core
- Milestone: agent-roadmap/phase/backtest-loop/milestones/backtest-multi-timeframe-coverage.md
- Lane: local
- Gate: G07
- Tag: REVIEW_API
- Status: planned
- Scope: monthly-bars worker/API core follow-up
- Parent: API

## Context

The first review found that the monthly aggregation implementation compiles and targeted Go checks pass, but the runtime contract and regression surface are incomplete. The follow-up must close only the Required findings from the archived review: provenance contract drift, parser-map/runtime registration tests, client parser registration, aggregator no-data/error/selector behavior, persistence/API forwarding tests, and missing implementation evidence.

## Archive Evidence Snapshot

- Archived plan: `agent-task/m-backtest-multi-timeframe-coverage/01_monthly_worker_core/plan_local_G07_0.log`
- Archived review: `agent-task/m-backtest-multi-timeframe-coverage/01_monthly_worker_core/code_review_local_G07_0.log`
- Verdict: FAIL
- Required summary:
  - `MonthlyProvenance` omits source/target timeframe even though the plan requires provenance entries with source/target timeframe.
  - Client `altParserMap()` does not register `AggregateMonthlyBarsRequest`, `AggregateMonthlyBarsResponse`, or `MonthlyProvenance`.
  - API/worker parser-map required-message tests and API session handler registration tests do not independently require the new monthly surface.
  - `Aggregator.AggregateMonthlyBars` silently skips `GetBars` errors and returns 0-count success for matching instruments with no daily bars.
  - Provider-specific symbol matching checks `inst.ProviderSymbols[requestedSymbol]` instead of comparing the requested symbols with `inst.ProviderSymbols[string(req.Provider)]`.
  - Tests do not prove the real aggregator persists `TimeframeMonthly` bars and keeps them queryable/separate through the existing bar path.
  - API monthly forwarding lacks success, typed validation/error, nil response, and registration regression tests.
  - The implementation-owned review sections were left as implementation-before placeholders with no command output.
- Suggested summary:
  - Consider moving aggregation request/result DTOs out of `services/worker/internal/socket` so `marketdata/aggregation` does not depend on socket handler package types.
- Verification evidence collected by review:
  - `go test ./services/worker/internal/marketdata/aggregation ./services/worker/internal/socket ./services/worker/internal/contracts` passed.
  - `go test ./services/api/internal/socket ./services/api/internal/workerclient ./services/api/internal/contracts` passed.
  - `git diff --check` passed.
  - `bin/contracts-check` passed.
  - `go test ./packages/contracts/gen/go/...` passed with no test files.
  - `go test ./services/worker/internal/storage/postgres -run 'Test.*Bar'` passed.
  - `go test ./services/worker/internal/marketdata/aggregation -run 'TestAggregateDailyToMonthlyFixtureComparison|TestAggregateDailyToMonthlyDeterministicOHLCV'` passed.
  - `bin/lint` exited 0 with pre-existing Flutter `avoid_print` info diagnostics in `mattermost_auth_service.dart`.
- Affected files to inspect first:
  - `packages/contracts/proto/alt/v1/market.proto`
  - `apps/client/lib/src/contracts/alt_contracts.dart`
  - `services/api/internal/contracts/parser_map_test.go`
  - `services/worker/internal/contracts/parser_map_test.go`
  - `services/api/internal/socket/market.go`
  - `services/api/internal/socket/market_test.go`
  - `services/api/internal/workerclient/client.go`
  - `services/api/internal/workerclient/client_test.go`
  - `services/worker/internal/marketdata/aggregation/aggregator.go`
  - `services/worker/internal/socket/market.go`
  - `services/worker/internal/socket/market_test.go`

## Scope

In scope:

- Add source/target timeframe provenance fields to the monthly aggregation contract and regenerate Go/Dart outputs.
- Register new monthly messages in client parser map and add parser-map coverage where local patterns exist.
- Update API/worker parser-map required-message tests and API session registration tests to independently require the new monthly surface.
- Fix real aggregator behavior for storage read errors, no-data results, and provider-specific symbol matching.
- Add focused tests for real aggregator persistence/query separation and API monthly forwarding success/error behavior.
- Fill the follow-up review artifact with actual implementation evidence and command stdout/stderr.

Out of scope:

- Operator YAML/JSONL handoff and final roadmap checkbox mutation; those remain with `02+01_monthly_operator_handoff`.
- New provider fetches or provider-native monthly bars.
- Flutter UI screens.
- Broad DTO/package refactor beyond what is needed to fix the Required findings.

## Work Items

1. Contract/provenance repair:
   - Add `Timeframe source_timeframe` and `Timeframe target_timeframe` to `MonthlyProvenance` with new field numbers.
   - Regenerate Go and Dart contract outputs through the repo generator/check path.
   - Populate the fields from worker monthly provenance mapping.

2. Parser map and registration coverage:
   - Add monthly request/response/provenance to `apps/client/lib/src/contracts/alt_contracts.dart`.
   - Add or update client parser-map tests if an existing parser-map test pattern is present.
   - Add monthly request/response/provenance to API and worker parser-map test required lists.
   - Add `AggregateMonthlyBarsRequest` to API session handler registration coverage.

3. Aggregator behavior repair:
   - Return a deterministic error when `GetBars` fails for a selected instrument.
   - Define and implement no-data behavior as a typed worker/backend error rather than silent 0-count success, unless a stronger existing contract says zero success is required; if so, document and test that contract.
   - Compare requested symbols against both `inst.Symbol` and `inst.ProviderSymbols[string(req.Provider)]`.
   - Avoid partial writes where feasible by collecting aggregation results before issuing writes, or add explicit tests proving current write behavior is acceptable and typed.

4. Regression tests:
   - Add a real aggregator test that starts with stored daily bars, runs `AggregateMonthlyBars`, asserts monthly bars use `market.TimeframeMonthly`, and reads monthly/daily bars separately through `GetBars`.
   - Add no-data and storage read error tests for the real aggregator.
   - Add API `handleAggregateMonthlyBars` tests for success, validation, worker error mapping, nil response, connect failure, and socket/handler registration.
   - Keep existing daily import/list behavior covered.

5. Evidence:
   - Fill every implementation-owned section in `CODE_REVIEW-local-G07.md`.
   - Paste actual stdout/stderr for all verification commands below.
   - Do not ask the user directly. If implementation is blocked by a selected SDD decision or selected Milestone lock item, fill `사용자 리뷰 요청` in the review file and stop for code-review.

## 구현 체크리스트

- [ ] Monthly provenance contract includes source and target timeframe fields, generated Go/Dart outputs are updated, and worker response mapping populates them.
- [ ] Client/API/worker parser maps and independent parser/session registration tests cover `AggregateMonthlyBarsRequest`, `AggregateMonthlyBarsResponse`, and `MonthlyProvenance`.
- [ ] Real aggregator returns deterministic errors for selected-instrument storage read failure and no-data cases, and provider-specific symbol matching uses the provider key correctly.
- [ ] Real aggregator tests prove monthly bars are persisted as `TimeframeMonthly` and remain queryable separately from daily bars through the existing bar store path.
- [ ] API monthly forwarding tests cover success, validation, worker errors, nil response, connect failure, and handler registration.
- [ ] `CODE_REVIEW-local-G07.md` is filled with implementation status, design decisions, plan deviations, actual verification stdout/stderr, and this final checklist item checked before review.

## Verification

- `bin/contracts-check`
- `go test ./packages/contracts/gen/go/...`
- `go test ./services/worker/internal/marketdata/aggregation ./services/worker/internal/socket ./services/worker/internal/contracts`
- `go test ./services/api/internal/socket ./services/api/internal/workerclient ./services/api/internal/contracts`
- `go test ./services/worker/internal/storage/postgres -run 'Test.*Bar'`
- `cd apps/client && flutter test`
- `bin/lint`
- `git diff --check`

## 범위 결정 근거

- This follow-up remains under the same milestone task group because it repairs Required findings in the monthly-bars worker/API core path.
- No `Roadmap Targets` or `Spec Targets` section is claimed here because the archived parent plan did not include those sections and final operator handoff evidence is explicitly assigned to `02+01_monthly_operator_handoff`.
