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, Python/NumPy, Octave, or Rust) 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: run continuously across multiple time scales (tick-level, hourly, daily, weekly); 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.
• Does-not: trade (Traders/Marketplace do); make decisions for traders (it informs, they decide); enforce laws (Marketplace does); supervise behavior (Conductor/SAE do).

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. Example: { value: 7.2, lower_bound: 5.8, upper_bound: 8.9, confidence: 0.73, 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 (C4): sims are read-only from traders' perspective — a query never mutates sim state. Calibration happens only from Data Feeds (M2).
• L4 (C4): each sim type is independent — failure in one sim does not cascade to others. Degraded sims report their status; traders handle missing predictions.
• L5 (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).