Execution Engine

// packages/execution-engine/src/index.ts
import type { Skill, ProposedAction } from '@repo/skill-schema';
import type { BrokerAdapter } from '@repo/brokers';

export type ProcessInput = {
  skill: Skill;
  deploymentId: string;
  proposedAction: ProposedAction | null;   // null = no-op tick
  broker: BrokerAdapter;
  portfolioSnapshot: PortfolioSnapshot;
};

export type EngineResult =
  | { kind: 'noop'; reason: 'agent_proposed_nothing' }
  | { kind: 'rejected'; rule: RuleId; detail: string }
  | { kind: 'executed'; orderId: string; fill: Fill | null };

export async function process(input: ProcessInput): Promise<EngineResult>;

ProposedAction
   │
   ▼
1. SHAPE      — zod schema valid? required fields present?
   │
   ▼
2. SCOPE      — symbol allowed by Skill? action type allowed?
   │
   ▼
3. POSITION   — resulting NOTIONAL exceed max_position_pct (per-symbol) or
                max_total_exposure_pct? below venue min? (measures resulting
                notionals, so scale-ins are checked correctly)
   │
   ▼
4. LEVERAGE   — resulting leverage exceeds max_leverage / exchange per-symbol cap?
   │
   ▼
5. RATE       — orders-per-DAY backstop exceeded for this deployment?
   │
   ▼
6. HALT       — daily loss halt tripped? deployment paused/stopped?
   │
   ▼
7. SANITY     — wildly off-market limit price? inverted protective order
                (long stop above price / short stop below, validated against
                the broker's current mark + stop-vs-TP ordering)?
   │
   ▼
8. RECORD     — write decision snapshot intent
   │
   ▼
9. EXECUTE    — call broker adapter. A broker-ledger rejection (insufficient
                margin, missing mark, malformed bracket) throws a
                BrokerRejectionError → caught and recorded as R9_BROKER_REJECT,
                never an uncaught throw that aborts the run. (Leverage is
                position state: scale-ins / flips inherit the position's
                leverage; only a fresh open sets it.)
   │
   ▼
10. RECORD    — write engine result + fill

// packages/skill-schema/src/proposed-action.ts
export const ProposedAction = z.discriminatedUnion('action', [
  z.object({
    action: z.literal('open_long'),
    symbol: z.string(),
    sizeUsd: z.number().positive(),     // notional in USD
    leverage: z.number().min(1).optional(),  // defaults to skill default
    orderType: z.enum(['market', 'limit']).default('market'),
    limitPrice: z.number().positive().optional(),
    reason: z.string().max(500),
    confidence: z.number().min(0).max(1).optional(),
  }),
  z.object({
    action: z.literal('open_short'),
    /* same shape */
  }),
  z.object({
    action: z.literal('close_position'),
    symbol: z.string(),
    fraction: z.number().min(0).max(1).default(1),  // partial close support
    reason: z.string().max(500),
  }),
  z.object({
    action: z.literal('adjust_position'),
    symbol: z.string(),
    targetSizeUsd: z.number(),          // signed; negative = short
    reason: z.string().max(500),
  }),
  z.object({
    action: z.literal('cancel_order'),
    orderId: z.string(),
    reason: z.string().max(500),
  }),
  z.object({
    action: z.literal('no_op'),
    reason: z.string().max(500),
  }),
]);

type RiskCaps = {
  // Position sizing — both NOTIONAL (notional / equity), leverage-independent
  maxPositionPct: number;          // single position notional % of equity (per-symbol concentration, ≤ maxTotalExposurePct)
  maxTotalExposurePct: number;     // sum of all open position notionals
  maxLeverage: number;             // hard cap regardless of agent request
  minOrderUsd: number;             // skip tiny orders (fee drag)
  // Rate limiting — daily backstop only (runaway-loop circuit breaker;
  // per-order size and intra-hour cadence are the agent's job, not engine caps)
  maxOrdersPerDay: number;
  // Loss management
  dailyLossHaltPct: number;        // halt + flatten if daily PnL drops below -X%
  maxDrawdownHaltPct: number;      // halt + flatten if equity drops X% from peak
  // Symbol allowlist
  allowedSymbols: string[];
};

// packages/brokers/src/types.ts
export interface BrokerAdapter {
  readonly kind: 'paper' | 'hyperliquid-mainnet';

  placeOrder(req: PlaceOrderRequest): Promise<PlaceOrderResponse>;
  cancelOrder(orderId: string): Promise<CancelResponse>;
  getPositions(): Promise<Position[]>;
  getOpenOrders(): Promise<Order[]>;
  getEquity(): Promise<EquitySnapshot>;
}

decision_snapshots (
  id              uuid pk,
  deployment_id   uuid,
  sim_run_id      uuid null,
  tick_at         timestamptz,
  context_json    jsonb,
  steps_json      jsonb,        -- model's tool-call sequence
  final_text      text,
  proposed_action jsonb null,
  engine_rule     text null,    -- e.g. 'R3_POSITION_CAP' if rejected
  engine_result   jsonb,        -- {kind, orderId?, fill?, rejectDetail?}
  cost_usd        numeric,
  created_at      timestamptz
)