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

domain	last_rule_review_commit	last_rule_updated_at
contracts	1f1527d7c6	2026-06-01

contracts

목적 / 책임

ALT 애플리케이션 레벨 protobuf 계약을 정의한다. proto-socket은 전송 계층으로 두고, ALT 메시지는 PacketBase.data에 실릴 payload schema로 관리한다. market read, backtest lifecycle, and backtest analysis query 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, and market query messages
• backtest.proto - backtest run spec, lifecycle, analysis result, list/detail/compare requests, and responses
• BacktestTrade, BacktestPosition, BacktestSummaryMetrics, BacktestEquityPoint, BacktestResult - backtest analysis result payloads
• ListBacktestRunsRequest, GetBacktestRunDetailRequest, GetBacktestResultRequest, CompareBacktestRunsRequest - backtest analysis query request 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.

다른 도메인과의 경계

• 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.

금지 사항

• 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.