sica-fondt/core/docs/plans/M3-sims-hub.md

# M3 — Sims hub (market prediction simulations)

## 1. Component
The economy organ's prediction engine: **always-running simulations** ("Sims") populated by
autonomous simulation agents ("Pops") that model market dynamics across multiple mathematical
domains and time scales. Sims are **queryable at any time** by Traders (M5) — they produce
**predictions with explicit upper and lower bounds** on every output value. This is the hub spec;
individual sim types have dedicated sub-specs (M3a–M3g).

The academic foundations span AMM mechanism design [1,2], MEV game theory [3,4,5], macro
tokenomics via SDEs [6,7], and evolutionary consensus games [8–11].

## 2. Status / certainty
DESIGN-FIRST · ABSENT. Role C3; implementation C1. Mathematical foundations C4 (literature
established); specific model parameters C1.

## 3. Language & location
TBD · `src/economy/sims/`. Numerical computing (Julia, Octave, Fortran, R, or Solidity)
for the simulation cores. A query facade accessible to Traders. Each sim type (M3a–M3g) may use
a different runtime suited to its math.

## 4. Does / does-not
- **Does:** tick-advance continuously at **90:1** (1 wall-second = 90 simulated seconds)
  across **six concurrent time horizons** — tick/hourly, daily, weekly, monthly, annual, and
  5-year forecast windows; every tick advances every sim; maintain populations of Pops whose
  behaviors emerge from the sim's mathematical model; ingest live data from Data Feeds (M2)
  for calibration; respond to Trader queries with bounded predictions; produce outputs with
  **explicit upper/lower bounds** on every prediction value.
  | Horizon | Window | Tick step | Effective ratio | Wall time for window |
  |---------|--------|-----------|-----------------|---------------------|
  | Tick–hourly | Next 1–60 min | 1s | 90:1 | ~40s |
  | Daily | Next 24h | 24s | 2,160:1 | ~40s |
  | Weekly | Next 7d | ~3 min | 15,120:1 | ~40s |
  | Monthly | Next 30d | 12 min | 64,800:1 | ~40s |
  | Annual | Next 365d | ~2.5 hr | ~788,000:1 | ~40s |
  | 5-year | Next 1825d | 12 hr | ~3,942,000:1 | ~40s |
- **Does-not:** trade (Traders/Marketplace do); make decisions for traders (it informs, they
  decide); enforce laws (Marketplace does); supervise behavior (Conductor/SAE do); skip ticks;
  run slower than 90:1.

## 5. Interface contract
- `query(sim_type: SimType, query: PredictionQuery) -> BoundedPrediction`.
  `SimType` ∈ { `statistical`, `sociological`, `amm_liquidity`, `mev_adversarial`,
  `tokenomics_macro`, `consensus_staking`, `market_microstructure` } (M3a–M3g).
- `BoundedPrediction { value, lower_bound, upper_bound, confidence, time_horizon, sim_type, timestamp }`.
  Every output is bounded — no point estimates without uncertainty ranges.
  `confidence` ∈ [0.00, 10.00] — printed as `7.62/10.00`. Gain rates print as
  `lower - value - upper / 10.00` (e.g. `2.31 - 4.44 - 7.11 / 10.00 gain over next 30 days`);
  the denominator aids legibility — gain is not capped at 10.00.
  Example: `{ value: 7.2, lower_bound: 5.8, upper_bound: 8.9, confidence: 7.30,
  time_horizon: "4h", sim_type: "amm_liquidity" }`.
- `status(sim_type?) -> { running, pop_count, last_calibration, data_freshness }` — health check.
- `calibrate(sim_type, feed_data: [NormalizedDatum])` — Data Feeds (M2) pushes live data for
  model recalibration.

## 6. Dependencies & stubs
- M2 Data Feeds — calibration data source; *stub:* canned market data.
- M5 Traders — query consumers; *stub:* canned queries.
- M3a–M3g sub-specs — individual sim implementations; *stub:* each returns fixed predictions.

## 7. Invariants / laws
- **L1 (C5):** sims are **always running** — they are not invoked on demand. Traders query
  current state; they don't trigger computation.
- **L2 (C5):** every prediction output includes **explicit upper and lower bounds** — no
  unbounded point estimates. Uncertainty is a first-class value, not an afterthought.
- **L3 (C5):** all sims are **tick-advanced and continuous** — fine-grained ticks (RTS-style).
  Base speed **90:1** (1s wall = 90s sim). Longer horizons run at higher velocity with coarser
  steps and update less frequently. Each horizon completes its forecast window in **~40s wall
  time**. Each horizon runs **in parallel** — they are concurrent, not sequential. No horizon
  runs slower than 90:1.
- **L4 (C4):** sims are **read-only from traders' perspective** — a query never mutates sim
  state. Calibration happens only from Data Feeds (M2).
- **L5 (C4):** each sim type is **independent** — failure in one sim does not cascade to others.
  Degraded sims report their status; traders handle missing predictions.
- **L6 (C3):** Pops are **simulation constructs, not AI actors** — they follow mathematical
  rules within the sim. Traders (M5) are the AI actors.

## 8. Build steps
1. Define `BoundedPrediction` shape and query protocol.
2. Build the sim runner (lifecycle management for always-on sims).
3. Wire M2 Data Feeds → calibration pipeline.
4. Implement sub-specs M3a–M3g as they land.
5. Wire trader query interface.

## 9. Tests
Always-on: sim running after init without external trigger. Bounded output: every prediction has
lower ≤ value ≤ upper. Query: trader receives prediction without mutating sim. Independence:
one sim's failure doesn't affect others. Calibration: new data updates model state.

## 10. Open items
- Pop lifecycle (birth/death/mutation within sims, or fixed populations?).
- Cross-sim aggregation (do traders query individual sims, or is there a meta-prediction layer?).
- Calibration frequency per sim type.
- Computational budget per sim (how much CPU/GPU each can consume).