<!-- task=m-backtest-multi-timeframe-coverage/01_monthly_worker_core plan=0 tag=API -->
# Plan - 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: API
- Status: planned
- Scope: monthly-bars worker/API core
- Predecessor: none

## Context

The monthly aggregation library already exists and has deterministic fixture coverage, but the current runtime boundary stops before a persisted monthly bar flow. The milestone task `monthly-bars` still needs a path that reads stored daily bars, aggregates them into monthly bars, stores the result with provenance, and exposes the operation through the API/worker socket boundary.

## Scope

In scope:

- Add a contract-level monthly aggregation request/response with provenance fields and regenerate contract outputs.
- Register the new request/response in API and worker parser maps.
- Add a worker monthly aggregation service that reads existing daily bars, calls `marketdata/aggregation.AggregateDailyToMonthly`, upserts `TimeframeMonthly` bars through the existing bar store, and returns deterministic counts/provenance.
- Add a worker socket handler and capability wiring for monthly aggregation.
- Add API worker-client and socket forwarding for the new operation.
- Add focused contract/parser, worker service/socket, API forwarding, and capability tests.

Out of scope:

- Operator scenario YAML, JSONL output, and human-facing handoff evidence. That is handled by `02+01_monthly_operator_handoff`.
- Fetching fresh provider data during monthly aggregation. This task uses daily bars already present in storage.
- Roadmap checkbox mutation for `monthly-bars`; the final handoff task owns that checkbox after operator evidence exists.

## Work Items

1. Extend `packages/contracts/proto/alt/v1/market.proto` with `AggregateMonthlyBarsRequest`, `AggregateMonthlyBarsResponse`, and a provenance message.
2. Regenerate contract code with the repo contract generation path and update parser-map registrations/tests in API and worker.
3. Implement a worker aggregation service near `services/worker/internal/marketdata/aggregation` that accepts market/venue/provider/symbol/range inputs, selects daily bars, aggregates by instrument, stores monthly bars, and returns counts plus provenance.
4. Add a worker socket handler for the new request, including typed validation errors for invalid market, venue, provider, symbols, and time ranges.
5. Wire the service in worker startup and expose a capability only when its dependencies are available.
6. Add API forwarding through `services/api/internal/workerclient` and `services/api/internal/socket/market.go`.
7. Add regression tests that prove monthly bars are stored with monthly timeframe and remain queryable through the existing bar query path.

## Acceptance Criteria

- A monthly aggregation request can be sent through API to worker and returns a success response when matching stored daily bars exist.
- The response includes instrument count, source daily bar count, monthly bar count, and provenance entries with source/target timeframe, source range, source count, and aggregation rule id.
- Aggregated monthly bars are persisted with `TimeframeMonthly` and can be read through the existing list/get bars flow without mixing with daily bars.
- Invalid inputs return typed contract errors instead of partial writes.
- Existing daily import and list bars behavior remains unchanged.

## Verification

- `bin/contracts-check`
- `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'`
- `git diff --check`

## Notes

- Reuse `AggregateDailyToMonthly` as the source of truth for OHLCV and provenance math.
- Prefer the existing `BarStore` timeframe separation over adding a new monthly-specific storage table.
- Keep the contract minimal: expose enough provenance for SDD S04 evidence, but avoid leaking worker-only implementation details.
