sica-fondt/core/docs/plans/M3b-sociological-sims.md

M3b — Sociological & population dynamics sims

1. Component

Sociological simulation: evolutionary game theory, bounded rationality, sentiment cascades, and population dynamics among market participants. Pops here are behavioral archetypes — retail herd followers, contrarian whales, MEV searchers, passive LPs — whose strategies evolve under selection pressure. Grounded in evolutionary consensus game models [8,9] and bounded-rationality coordination frameworks.

2. Status / certainty

DESIGN-FIRST · ABSENT. Evolutionary game-theory foundations C4 (Cornell blockchain cooperation literature [8]); pop behavioral models C1.

3. Language & location

TBD · src/economy/sims/sociological/. Agent-based modeling frameworks (Mesa/Python, NetLogo, or custom). Needs efficient population iteration and strategy mutation.

4. Does / does-not

• Does: simulate populations of behavioral archetypes competing in a market; apply evolutionary dynamics (replicator equation, mutation, selection) to strategy distributions; model sentiment cascades (fear/greed contagion across pop clusters); model bounded rationality (pops satisfice, not optimize — they follow heuristics, not perfect strategies); produce bounded predictions on market sentiment, herd behavior thresholds, and coordination breakdowns.
• Does-not: model protocol mechanics (M3c–M3f); compute statistical forecasts (M3a); represent real individuals (pops are archetypes, not profiles).

5. Interface contract

• Implements query(PredictionQuery) -> BoundedPrediction per M3 hub.
• Output bounds: population-fraction ranges and sentiment scales. Example: { value: 7.3, lower_bound: 5.0, upper_bound: 9.1, confidence: 0.68, time_horizon: "12h", sim_type: "sociological" } — herd-panic index on a 0–10 scale. Example: { value: 0.42, lower_bound: 0.31, upper_bound: 0.55, confidence: 0.72, time_horizon: "1w", sim_type: "sociological" } — fraction of pops in "contrarian" strategy.
• Prediction types: sentiment_index, herd_threshold, strategy_distribution, cascade_probability, coordination_stability.
• Calibration: ingests rss_news (sentiment signal) and price_tick (realized behavior) from M2.

6. Dependencies & stubs

• M2 Data Feeds — sentiment and price data for calibration; stub: canned sentiment series.
• M3 Sims hub — lifecycle management; stub: manual init.

7. Invariants / laws

• L1 (C4): pops are archetypes, not individuals — no attempt to model or track real market participants. The sim models emergent behavior from strategy populations.
• L2 (C4): strategies evolve — the population distribution shifts over time via replicator dynamics. No fixed strategy ratios.
• L3 (C3): bounded rationality is the default — pops satisfice with heuristics, not optimize with perfect information. Rational-agent models are a special case, not the baseline.

8. Build steps

1. Define pop archetypes and their heuristic strategies.
2. Implement replicator dynamics (strategy evolution over generations).
3. Implement sentiment contagion model (network-based cascade).
4. Wire M2 news/price data → calibration of pop parameters.
5. Implement BoundedPrediction output with population-fraction CIs.

9. Tests

Evolution: dominant strategy shifts when payoff landscape changes. Cascade: sentiment shock propagates through pop network above threshold, not below. Bounded rationality: satisficing pop underperforms optimizer in simple games but outperforms in noisy environments. Bounds: all outputs include upper/lower.

10. Open items

• Pop archetype catalog (which behavioral types? how many?).
• Network topology for sentiment contagion (small-world? scale-free?).
• Calibration from real market data — how to infer pop distribution from observable price action.
• Cross-sim interaction: do sociological predictions feed into M3c (AMM) or M3d (MEV)?