alt/agent-ops/rules/project/domain/contracts/rules.md

domain	last_rule_review_commit	last_rule_updated_at
contracts	704f1eb232	2026-06-24

contracts

목적 / 책임

ALT 애플리케이션 레벨 protobuf 계약을 정의한다. proto-socket은 전송 계층으로 두고, ALT 메시지는 PacketBase.data에 실릴 payload schema로 관리한다. Market read/import/aggregation/scheduler, backtest lifecycle/analysis, paper trading, and live trading payloads are versioned here.

포함 경로

• packages/contracts/README.md - contract direction and compatibility notes
• packages/contracts/gen/go/ - generated Go protobuf module for ALT contracts
• packages/contracts/proto/alt/v1/ - versioned protobuf schema source

제외 경로

• packages/domain/ - internal Go domain types
• services/api/ - runtime socket server implementation
• apps/client/ - generated or consumed client-side integration

주요 구성 요소

• common.proto - shared enums, decimal, handshake, and error messages
• market.proto - instrument, price, quantity, bar, market query, daily import, monthly aggregation, and scheduler refresh status messages
• backtest.proto - backtest run spec, lifecycle, analysis result, list/detail/compare requests, and responses
• paper_trading.proto - paper trading account state and virtual order lifecycle request/response messages
• live_trading.proto - live broker capability, order lifecycle, risk/kill switch, account snapshot, and audit query request/response messages
• BacktestTrade, BacktestPosition, BacktestSummaryMetrics, BacktestEquityPoint, BacktestResult - backtest analysis result payloads
• ListBacktestRunsRequest, GetBacktestRunDetailRequest, GetBacktestResultRequest, CompareBacktestRunsRequest - backtest analysis query request surface
• ImportDailyBarsRequest, AggregateMonthlyBarsRequest, SchedulerRefreshStatusRequest - market data operations and scheduler query request surface
• StartPaperTradingRequest, SubmitPaperOrderRequest, FillPaperOrderRequest - paper trading command surface
• SubmitLiveOrderRequest, SetLiveKillSwitchRequest, SyncLiveAccountRequest, ListLiveAuditEventsRequest - live trading control and audit surface
• gen/go/alt/v1/*.pb.go - generated Go message types consumed by Go services

유지할 패턴

• Prefer additive protobuf changes and reserve removal/renaming for explicit compatibility work.
• Keep schema package under alt.v1 until a deliberate version bump is planned.
• Keep option go_package aligned with the generated Go package path.
• Keep generated Go module path aligned with git.toki-labs.com/toki/alt/packages/contracts/gen/go.
• Use explicit version/handshake messages because proto-socket protocol 0.1 does not carry an ALT application version field.
• Keep request/response contracts additive and update API, worker, and client parser maps when a new ALT protobuf message becomes part of the runtime surface.
• Keep market/venue/currency/timeframe enums broad enough for KR and US surfaces, but add provider-specific details in adapter/domain layers rather than hard-coding one broker into core contract names unless the message is explicitly broker-neutral.
• Keep live trading contracts sanitized: expose operator account aliases and broker-neutral status fields, not raw account numbers, tokens, or provider response bodies.

다른 도메인과의 경계

• api: contracts define payload shape and generated Go message types; API decides transport/session behavior and owns API-local parser registration.
• domain-model: contracts are wire format; domain-model is internal business vocabulary.
• client: client consumes generated or mapped contracts; schema source remains here.
• worker: worker maps domain/storage/provider objects into generated contract payloads at socket adapter boundaries.

금지 사항

• Do not hand-edit generated outputs.
• Do not encode runtime server behavior or database concerns in .proto comments or fields.
• Do not change field numbers for existing protobuf fields.
• Do not place provider credentials, raw account identifiers, or raw external API payloads in contract messages.