11 · Data Contracts
Contracts prevent vendor, runtime and UI shapes from leaking across authority boundaries. Each schema names its owner, producer, consumer, persistence and versioning responsibility.
Version at boundaries; migrate explicitly
- Module boundaries use explicit TypeScript types and runtime validation.
- Financial quantities are decimal strings; timestamps are Unix milliseconds; IDs are opaque stable strings.
- Additive optional fields may share a version only when old consumers remain correct. Breaking semantic/required-field changes increment the version and provide a migrator.
- Unknown fields are ignored only where declared; unknown enum values fail safely.
- Persistence records the schema/formula/policy version used to interpret the event.
Fourteen canonical contracts
MarketFrame
Producer
Hyperliquid adapter
Consumer
Context builder, risk kernel
Persistence
R2 replay artifact; latest in match/session state
{ version: 1; frameId: string; network: 'testnet'|'mainnet'; capturedAtMs: number; instruments: InstrumentQuote[]; freshnessMs: number }TradeIntent
Producer
Validated model tool call or human command
Consumer
Risk kernel
Persistence
Append-only replay event
{ version: 1; intentId: string; actor: 'model'|'human'; sessionId: string; instrument: InstrumentRef; action: 'open'|'increase'|'reduce'|'close'|'cancel'|'flatten'; side?: 'buy'|'sell'; size?: string; limitPrice?: string; reduceOnly: boolean; rationaleSummary?: string; createdAtMs: number }RiskVerdict
Producer
Deterministic risk kernel
Consumer
Execution boundary, UI, replay
Persistence
Append-only replay and audit record
{ version: 1; verdictId: string; intentId: string; decision: 'accept'|'clamp'|'reject'; policyVersion: string; reasons: RiskReason[]; approved?: ApprovedOrder; evaluatedAtMs: number }ExecutionRequest
Producer
Execution boundary after accepted verdict
Consumer
Signing service
Persistence
Idempotency/audit record
{ version: 1; requestId: string; idempotencyKey: string; accountId: string; signerRef: string; verdictId: string; action: ExchangeAction; deadlineMs: number }ExecutionResult
Producer
Hyperliquid adapter
Consumer
Agent tool, reconciler, replay
Persistence
Audit and replay record
{ version: 1; requestId: string; status: 'accepted'|'rejected'|'unknown'; exchangeResponse?: unknown; error?: ErrorEnvelope; submittedAtMs: number }OrderUpdate
Producer
WebSocket/info reconciliation
Consumer
Portfolio projection, replay, UI
Persistence
D1 indexed event; R2 replay
{ version: 1; accountId: string; orderId: string; clientOrderId?: string; instrument: InstrumentRef; state: 'open'|'filled'|'canceled'|'rejected'|'unknown'; remainingSize: string; observedAtMs: number; source: 'stream'|'reconcile' }FillUpdate
Producer
WebSocket/info reconciliation
Consumer
Portfolio projection, settlement evidence
Persistence
D1 unique exchange fill ID; R2 replay
{ version: 1; accountId: string; tradeId: string; orderId: string; instrument: InstrumentRef; side: 'buy'|'sell'; price: string; size: string; fee: string; feeToken: string; closedPnl: string; exchangeTimeMs: number }PortfolioSnapshot
Producer
Reconciler
Consumer
Agent context, risk, Self/VS UI
Persistence
D1 snapshots; terminal artifact in R2
{ version: 1; snapshotId: string; accountId: string; equityUsd: string; withdrawableUsd: string; positions: Position[]; openOrders: OrderRef[]; cumulativeFeesUsd: string; cumulativeFundingUsd: string; capturedAtMs: number; freshnessMs: number }MatchState
Producer
State machine
Consumer
Clients, orchestration, settlement
Persistence
Authoritative DO SQLite storage
{ version: 1; matchId: string; state: MatchPhase; revision: number; playerIds: [string,string]; acceptedAtMs?: number; startsAtMs?: number; lockAtMs?: number; snapshotAtMs?: number; terminalReason?: string }MatchEvent
Producer
State transition/effect handlers
Consumer
Clients, replay, operations
Persistence
DO transition log; D1 index; R2 replay
{ version: 1; eventId: string; matchId: string; revision: number; type: string; commandId: string; payload: unknown; occurredAtMs: number }EquitySnapshot
Producer
Deadline snapshot coordinator
Consumer
Settlement decision
Persistence
Immutable R2 artifact + D1 hash/index
{ version: 1; snapshotId: string; matchId: string; deadlineMs: number; referencePrices: ReferencePrice[]; players: PlayerEquityInput[]; sourceHashes: string[]; capturedAtMs: number }SettlementDecision
Producer
Pure settlement calculator
Consumer
Payout/refund workflow, replay
Persistence
Immutable D1 record + R2 evidence
{ version: 1; decisionId: string; matchId: string; snapshotId: string; outcome: 'player_1'|'player_2'|'tie'|'refund'|'manual_review'; scores: [string,string]; payoutPlan: Payout[]; formulaVersion: string; decidedAtMs: number }ReplayEvent
Producer
All domain boundaries
Consumer
Replay UI, audit export
Persistence
Append-only R2 segments with manifest checksum
{ version: 1; replayId: string; eventId: string; sequence: number; category: 'intent'|'risk'|'execution'|'order'|'fill'|'equity'|'match'|'settlement'; display: unknown; privateFieldsOmitted: true; occurredAtMs: number }ErrorEnvelope
Producer
Every boundary
Consumer
Caller, telemetry, UI mapper
Persistence
Structured logs; replay only when user-relevant
{ version: 1; code: string; category: 'validation'|'authorization'|'stale_state'|'exchange'|'signing'|'timeout'|'conflict'|'internal'; retryable: boolean; safeMessage: string; correlationId: string; details?: Record<string, unknown> }