Docs & Knowledge

# Kalshi Execution Layer (Scaffold)

## Modules
- `execution/config.mjs` – safeguards + config (paper mode on, live off, max size 1, cooldown 60 m, market ticker).
- `execution/stateStore.mjs` – reads/writes `data/execution/state.json`.
- `execution/signalReader.mjs` – pulls the latest row from `data/logs/signal-log.jsonl`.
- `execution/marketData.mjs` – fetches Kalshi market + order book snapshots for the configured ticker.
- `execution/executionService.mjs` – translates a signal into orders, enforces safeguards, compares against live pricing, updates state/`data/logs/trade-log.jsonl`.
- `execution/kalshiClient.mjs` – REST client (Basic auth, real endpoints).

## Commands
- `npm run trade:dry-run` – read the latest signal, optionally include live market snapshot, print the decision (no state/log writes).
- `npm run trade:paper` – run the execution service in paper mode (updates state + trade log, no API orders).
- `npm run market:compare` – log model probability vs live Kalshi price + computed edge.
- `npm run kalshi:test-client` – credential sanity check (calls `/trade-api/v2/markets?limit=1`).

## Files
- `.env.execution.example` – template for `KALSHI_API_KEY`, `KALSHI_API_SECRET`, `KALSHI_BASE_URL`, `KALSHI_MARKET_TICKER`.
- `data/execution/state.json` – persisted execution state (created on first paper run).
- `data/logs/trade-log.jsonl` – append-only log of paper/dry decisions + market snapshots.

## Safeguards (default)
- `paperTradeMode = true`, `liveTradingEnabled = false`.
- `killSwitch = false` – flip to true to block all actions.
- `maxPositionSize = 1`, `allowMultiplePositions = false`.
- `cooldownMinutes = 60` between actions.
- Duplicate detection via `lastSignalRunAt` + `lastActionAt`.

## Flow
1. Signal log updated by modeling pipeline (currently paused).
2. Execution scripts read the latest signal via `executionService`.
3. Market snapshot (if reachable) is fetched through the Kalshi client.
4. Decision builder maps posture/action → desired position, computes model vs market edge, applies safeguards.
5. Paper mode updates state/logs only. Live mode remains disabled until explicitly flipped.