learning_ai_invt_trdg/web/dashboard-metrics-contract.md

# Dashboard Metrics Contract

This contract formalizes each surface-level metric on the dashboard so that engineers and future agents can recompute and validate them without inspecting implementation details. Each definition below derives directly from the authoritative Dashboard Metric Validation Table you provided.

## System Status (RUNNING/DEGRADED/UNHEALTHY)
- **Metric Name:** System Status (RUNNING/DEGRADED/UNHEALTHY)
- **Business Definition:** Signals the operational health tier of the bot service by combining capital invariants with the trading and reconciliation loop statuses so stakeholders immediately know whether the system is fully operational.
- **Canonical Source of Truth:** `botState.health`
- **Exact Formula:** `const h = botState.health; status = h.capitalInvariantViolations > 0 ? 'Unhealthy' : (!h.tradingLoopHealthy || !h.reconciliationLoopHealthy) ? 'Degraded' : 'Running'`
- **Lifecycle Boundary:** Considered final once the latest `botState.health` payload is read and evaluated; the value stays fixed until the next health payload arrives.
- **Update Frequency:** Per bot health emission (each trading/reconciliation loop that pushes `botState.health`).
- **Confidence Level:** MEDIUM

## Mode (Paper/Live)
- **Metric Name:** Mode (Paper / Live)
- **Business Definition:** Identifies whether the dashboard-connected bot is executing in sandbox/paper-trading or live-trading environments so users know what kind of capital interaction they are viewing.
- **Canonical Source of Truth:** `botState.settings.executionMode`
- **Exact Formula:** Direct reflection (value = `botState.settings.executionMode`).
- **Lifecycle Boundary:** Final once the latest `executionMode` value is received; inferred to remain unchanged until an update arrives (typically when configuration changes or a reconnect occurs).
- **Update Frequency:** Per bot loop (whenever `botState.settings` is refreshed during the websocket heartbeat).
- **Confidence Level:** HIGH

## Allocated Capital
- **Metric Name:** Allocated Capital
- **Business Definition:** Total capital that has been committed across every enabled profile, representing the supply ceiling before new exposures are permitted.
- **Canonical Source of Truth:** `capital_ledgers.allocated_capital`
- **Exact Formula:** `SUM(allocated_capital)` across every enabled profile row in `capital_ledgers`.
- **Lifecycle Boundary:** Final once the latest capital ledger snapshot (reconciliation) completes; remains until the next ledger write.
- **Update Frequency:** Per reconciliation (capital ledger refreshes when allocations change or on ledger rebuild).
- **Confidence Level:** HIGH

## Capital Used
- **Metric Name:** Capital Used
- **Business Definition:** Tracks working capital that is currently reserved either for pending exchange orders or for filled positions, reflecting locked-up funds.
- **Canonical Source of Truth:** `capital_ledgers.reserved_for_orders` + `capital_ledgers.reserved_for_positions`
- **Exact Formula:** `SELECT SUM(reserved_for_orders + reserved_for_positions) FROM capital_ledgers`.
- **Lifecycle Boundary:** Final when the reconciliation cycle records the latest reservations; usage may change after order fills or cancellations update the ledger.
- **Update Frequency:** Per reconciliation cycle (order/reservation adjustments persisted to `capital_ledgers`).
- **Confidence Level:** HIGH

## Remaining Capital
- **Metric Name:** Remaining Capital
- **Business Definition:** Represents the liquidity still available for new trades after subtracting both order reservations and filled exposure, while including realized profits/losses.
- **Canonical Source of Truth:** Derived from the capital ledger invariant: allocated capital, current reservations, and realized P&L.
- **Exact Formula:** `SELECT SUM(allocated_capital - reserved_for_orders - reserved_for_positions + realized_pnl) FROM capital_ledgers`.
- **Lifecycle Boundary:** Final once the reconciliation writes the invariant for the latest ledger state; recalculated whenever capital reservation or realized P&L changes.
- **Update Frequency:** Per reconciliation cycle (ledger snapshot update).
- **Confidence Level:** HIGH

## Realized P&L
- **Metric Name:** Realized P&L
- **Business Definition:** Cumulative profit and loss from exits that have already settled, indicating completed trade performance.
- **Canonical Source of Truth:** `capital_ledgers.realized_pnl` (backed by `trade_history`).
- **Exact Formula:** `SUM(realized_pnl)` from `trade_history` rows where `state = 'EXIT_FILLED'` (or using the mirrored ledger column).
- **Lifecycle Boundary:** Final at the moment an `EXIT_FILLED` record is persisted; accumulates with each valid exit.
- **Update Frequency:** Per trade exit (each reconciliation that records a filled exit).
- **Confidence Level:** MEDIUM

## Net P&L
- **Metric Name:** Net P&L
- **Business Definition:** Aggregates both realized gains/losses and current unrealized exposure so operators can assess total equity change in real time.
- **Canonical Source of Truth:** Combination of `capital_ledgers.realized_pnl` and live `botState.positions` (unrealized data).
- **Exact Formula:** `realized_pnl (capital_ledgers.realized_pnl snapshot) + SUM(unrealizedPnl from botState.positions)`.
- **Lifecycle Boundary:** Final when the latest ledger snapshot and position updates are combined; refreshed on every position update or reconciliation.
- **Update Frequency:** Real-time (whenever position unrealized P&L or ledger realized P&L changes).
- **Confidence Level:** MEDIUM

## Win Rate (7D)
- **Metric Name:** Win Rate (7D)
- **Business Definition:** Percentage of profitable exits in the trailing 7-day window, helping teams evaluate recent execution effectiveness.
- **Canonical Source of Truth:** `trade_history` (filtered to exits within the last 7 days).
- **Exact Formula:** `SUM(CASE WHEN pnl > 0 THEN 1 ELSE 0 END)::float / COUNT(*)` over `trade_history` rows where `state = 'EXIT_FILLED' AND ts >= NOW() - INTERVAL '7 days'`.
- **Lifecycle Boundary:** Final once a trade exit row is persisted; each exit event extends/updates the 7-day window.
- **Update Frequency:** Per trade exit (or each time the 7-day slice is recalculated during reconciliation).
- **Confidence Level:** MEDIUM

## Trade Count
- **Metric Name:** Trade Count
- **Business Definition:** Total number of uniquely identified trades that have passed through the lifecycle pipeline, independent of wins or losses.
- **Canonical Source of Truth:** `trade_lifecycle`
- **Exact Formula:** `SELECT COUNT(DISTINCT trade_id) FROM trade_lifecycle`.
- **Lifecycle Boundary:** Final once the lifecycle record for a trade is written; duplicates are deduped via `trade_id`.
- **Update Frequency:** Per trade lifecycle update (entries written as trades progress).
- **Confidence Level:** LOW

## P&L Duration
- **Metric Name:** P&L Duration
- **Business Definition:** Timespan between the earliest entry and latest exit in the ledger, serving as a sanity check on the historical trade window that contributes to displayed P&L.
- **Canonical Source of Truth:** `trade_history` timestamps (`entry_ts`, `exit_ts`).
- **Exact Formula:** `MAX(exit_ts) - MIN(entry_ts)` over `trade_history` rows considered in the dashboard (typically the global scope used for realized P&L).
- **Lifecycle Boundary:** Final when the latest exit timestamp is committed; extends as newer trade history data arrives.
- **Update Frequency:** Per reconciliation (when trade history is aggregated for metrics).
- **Confidence Level:** LOW

## Uptime
- **Metric Name:** Uptime
- **Business Definition:** Measures how long the bot service has been running without a restart so users can correlate stability with performance.
- **Canonical Source of Truth:** `botState.uptime`
- **Exact Formula:** Direct reflection of `botState.uptime` (milliseconds since last restart or health reset).
- **Lifecycle Boundary:** Final upon receipt of the latest uptime value; resets when the bot restarts or websocket reinitializes.
- **Update Frequency:** Real-time (updated as the bot increments its uptime counter).
- **Confidence Level:** MEDIUM

## Broker Balance (Alpaca)
- **Metric Name:** Broker Balance (Alpaca)
- **Business Definition:** The actual cash and buying power reported by the Alpaca brokerage account. This is the source of truth for real-world liquidity and may differ from the bot’s internal allocated capital ledger.
- **Canonical Source of Truth:** `botState.accountSnapshot` (from Alpaca API `GET /v2/account`).
- **Exact Formula:** Display `buying_power` and `cash` fields directly from the snapshot.
- **Lifecycle Boundary:** Updates whenever the bot polls Alpaca (typically on order fills or periodic syncs).
- **Update Frequency:** Real-time (approx. every minute or on event).
- **Confidence Level:** HIGH (Third-party authoritative).

## Capital Coverage Status (Per Profile)
- **Metric Name:** Capital Coverage (LP Health)
- **Business Definition:** A health check comparison between a profile’s internal `allocated_capital` and the broker’s actual `buying_power`.
- **Display:**
  - **Covered (Green):** `allocated_capital <= buying_power`
  - **Insufficient Funds (Orange/Red):** `allocated_capital > buying_power`
- **Canonical Source of Truth:** Comparison of `botState.accountSnapshot.buying_power` vs `profile.allocated_capital`.
- **Exact Formula:** `IF (allocated <= buying_power) THEN 'Covered' ELSE 'Insufficient'`
- **Lifecycle Boundary:** Re-evaluated on every state update.
- **Update Frequency:** Real-time.
- **Confidence Level:** HIGH

## Recent Order Failures
- **Metric Name:** Recent Order Failures
- **Business Definition:** A list of recent order rejections from the broker (e.g., "insufficient buying power", "pattern day trader protection").
- **Canonical Source of Truth:** `botState.orderFailures` (in-memory circular buffer, capped at 30).
- **Exact Formula:** Display list of `{timestamp, symbol, reason}`.
- **Lifecycle Boundary:** Ephemeral; preserved in memory while bot is running. Cleared on restart.
- **Update Frequency:** Event-driven (emitted immediately upon rejection).
- **Confidence Level:** HIGH