Merge pull request #13 from SHOGGOTH-SECTOR/claude/economy-organ-docs-review-li41bm

Add M0-M7 economy organ plan specs

.claude/devCorrectionLog.md

@@ -0,0 +1,33 @@
+# devCorrectionLog
+
+⊳ User gives **additive** clarifications. Only an explicit "no" is a replacement.
+⊳ Don't rewrite — append. Don't guess — ask or research first.
+⊳ Don't idle while subagents run.
+
+```yml
+corrections:
+  - epoch: 1783985662
+    failcase: "rewrote L3 seven times"
+    identifyBy: "treating every clarification as a full replacement"
+    instead: "append the new detail to existing text, preserve prior content"
+
+  - epoch: 1783985662
+    failcase: "idle during foreground subagent"
+    identifyBy: "ran research agent synchronously, did nothing while waiting"
+    instead: "run agents in background, continue editing other files"
+
+  - epoch: 1783985662
+    failcase: "guessed sim speed without research"
+    identifyBy: "accepted 360:1 then 3600:1 then 86400:1 without pushback"
+    instead: "research comparable systems before committing a number"
+
+  - epoch: 1783985662
+    failcase: "5 commits on one parameter"
+    identifyBy: "each clarification triggered a commit-push cycle"
+    instead: "accumulate related changes, commit once when stable"
+
+  - epoch: 1783985662
+    failcase: "never asked what economy organ was"
+    identifyBy: "wrote 8 wrong specs (text digestion) without asking"
+    instead: "ask what the thing is before designing it"
+```

CLAUDE.md

@@ -2,5 +2,6 @@
 
 Working agreements, build/run, and the invariants (S1/S2/S3) for sica-fondt now
 live in [`core/CLAUDE.md`](core/CLAUDE.md). This root file is only a pin.
+Correction log: [`.claude/devCorrectionLog.md`](.claude/devCorrectionLog.md).
 
 @core/CLAUDE.md

core/AGENTS.md

@@ -1,7 +1,7 @@
 # AGENTS.md — Ada border (D1) + invariant vault
 
 Local guide for `mafiabot_core`. Repo-wide map and rules: [`../AGENTS.md`](../AGENTS.md);
-working agreements: [`../CLAUDE.md`](../CLAUDE.md).
+working agreements: [`../CLAUDE.md`](../CLAUDE.md). Correction log: [`../.claude/devCorrectionLog.md`](../.claude/devCorrectionLog.md).
 
 ## What this is
 

core/CLAUDE.md

@@ -28,6 +28,12 @@ Per-unit commands and gotchas live in that unit's `AGENTS.md`. Toolchains (ponyc
 - **S2:** never reclassify a message's provenance.
 - **S3 / vault:** the COBOL invariant-law vault (Invariant 0, the culpability anchor; 01, "harm" "less";) is immutable at runtime — don't edit it unless explicitly directed and only as such.
 
+## Subagents
+
+When spawning background agents (Haiku for research, etc.), **keep working on the main task while they run**. Don't wait idle — fold in results as they arrive, edit other files, or advance unrelated build steps. Background agents are cheap parallelism; wasting the main context window on waiting defeats the purpose.
+
+Correction log at `.claude/devCorrectionLog.md`.
+
 ## Docs map
 
 - `README.md` — the project and its intent.

core/docs/bus-topology.md

@@ -84,4 +84,6 @@ blocking in a protected action), **tasks = workers** that call into the organs
   structure that isn't a lookup "store"?
 - **MoRAG / GoDAGRAG language** (Haskell vs Crystal vs other).
 - Each outer organ's hand-off shape to Ada.
-- The stomach/economy organ's exact placement + which small model runs it.
+- ~~The stomach/economy organ's exact placement + which small model runs it.~~
+  **→ placed:** M-series (M0–M7) in `docs/plans/`. Outer organ on Ichor; data feeds via M2 (Data Feeds).
+  See M0 (hub), M6 (Conductor — orchestration, provenance chain, S1/S2 compliance).

core/docs/plans/M0-economy-organ-hub.md

@@ -0,0 +1,76 @@
+# M0 — Economy organ hub (the stomach)
+
+## 1. Component
+The economy organ — the organism's **stomach**. An **independent, self-governing system**: a
+multi-agentic market prediction oracle and cryptocurrency trading engine. Houses the Marketplace
+(M1), Data Feeds (M2), Sims (M3), Wallets (M4), Traders (M5), Conductor (M6), and SAE monitor
+(M7). Communicates with the rest of the organism **via Ichor only** — reward signals back to the
+organism are TBD and out of scope.
+
+"A stomach rarely consults a brain for permission to digest." The economy organ operates with
+**scoped autonomy** and **multiple layers of failsafe braking** — it does not ask the organism's
+Brain for permission to trade.
+
+## 2. Status / certainty
+DESIGN-FIRST · ABSENT. A `Stomach` primitive exists in Ichor (`src/ichor/envelope.pony:20`) with
+one smoke-test wire (`main.pony:29`), but no dedicated organ code. Role C4; implementation C1.
+
+## 3. Language & location
+TBD · new location e.g. `src/economy/`. The organ is polyglot by nature: trading infrastructure
+(APIs, wallets) may differ in language from simulations (numerical computing) and the conductor
+(AI supervision). Pony actors provide the Ichor-facing facade.
+
+## 4. Does / does-not
+- **Does:** host crypto/NFT trading via the Marketplace (M1); run always-on market prediction
+  Sims (M3) fed by live Data Feeds (M2); manage sovereign-custody Wallets (M4); supervise
+  Traders (M5) via a Conductor (M6); guard against anomalies via SAE monitor (M7); collect taxes
+  on trader income and stub transfer to Verschwörern Veregeister wallets; maintain a **ledger of
+  economy-related memories and patterns** (trade history, learned market patterns, calibration
+  state).
+- **Does-not:** consult the organism's Brain for trade decisions (scoped autonomy); route around
+  Ada for organism-bound messages (S1); store **organism** memories (E*) — economy-specific
+  memories stay local; act as the organism's conscience (that's Eth-Int / A6).
+
+## 5. Interface contract
+- **Ichor interface (outbound):** `Envelope(Stomach, AdaBorder, OrganSecretion, payload)` — market
+  state summaries, prediction digests, and tax receipts cross Ada to reach the inner brain.
+- **Ichor interface (inbound):** organism directives arrive via Ichor (e.g. risk posture changes,
+  budget adjustments from A2 energy).
+- **Internal wiring:** Marketplace (M1) ↔ Data Feeds (M2) ↔ Sims (M3). Wallets (M4) bind to
+  Traders (M5). Conductor (M6) supervises Traders (M5). SAE (M7) acts as an independent
+  antivirus / guarddog / alarm bell — monitors via Ichor-routed messages and alerts M6.
+  All trader actions route through Marketplace.
+- **Tax stub:** `transfer_tax(amount, source_wallet, dest_wallet) -> receipt` — automation hook
+  for Verschwörern Veregeister internal wallet-to-wallet transfer. **Out of scope** — stub only.
+
+## 6. Dependencies & stubs
+- Ichor bus (D2) — existing `Broker` + `Envelope`.
+- Ada border (D1) — outbound economy envelopes cross here (S1); *stub:* Ichor `Barrier`.
+- A2 energy — potential consumer of economic signals; *stub:* no integration initially.
+- Verschwörern Veregeister wallets — tax destination; *stub:* log transfer, no real wallet.
+
+## 7. Invariants / laws
+- **L1 (C5):** the stomach is an **OUTER** organ — it rides Ichor, never the inner bus.
+- **L2 (C5):** **scoped autonomy** — the organ trades without Brain permission, but within
+  deterministic law constraints (M1) and Conductor oversight (M6).
+- **L3 (C4):** **all market actions route through the Marketplace** (M1) — no trader may
+  execute directly on-chain without the Marketplace harness.
+- **L4 (C4):** **sovereign custody only** — all wallets are local-hosted, our keys, never
+  delegated to exchanges or third parties (M4).
+- **L5 (C4):** **multi-layered braking** — deterministic law script (M1), Conductor veto (M6),
+  SAE surveillance (M7), and wallet-level limits (M4) each independently constrain risk.
+
+## 8. Build steps
+1. Build sub-components (M1–M7) individually — each with defined success criteria and ablative tests.
+2. Extend the existing `Stomach` primitive in Ichor to carry the hub facade.
+3. Define internal wiring topology and connect tested sub-components.
+4. Implement tax stub and Verschwörern Veregeister transfer last.
+
+## 9. Tests
+Hub smoke: Marketplace reachable; Sims running and queryable; Wallet bound to Trader; Conductor
+receives SAE reports; tax stub logs transfer. Ichor: outbound envelope reaches Ada stub.
+
+## 10. Open items
+- Reward signal protocol from economy organ to organism (TBD, out of scope).
+- Internal communication bus (reuse Ichor internally? separate actor topology?).
+- Language choices per sub-component.

core/docs/plans/M1-marketplace.md

@@ -0,0 +1,79 @@
+# M1 — Marketplace (multi-trader harness)
+
+## 1. Component
+The economy organ's trading floor: a **multi-trader harness** through which **all market actions
+must route**. No trader may buy, sell, mint, or interact with any on-chain protocol except through
+the Marketplace. Enforces a **deterministic law script** (scoped invariants — the marketplace's
+own constitution) and integrates the **Conductor's veto** (M6) before execution.
+
+## 2. Status / certainty
+DESIGN-FIRST · ABSENT. Role C4; implementation C1.
+
+## 3. Language & location
+TBD · `src/economy/marketplace/`. Needs to interface with blockchain APIs (RPC/REST), wallet
+signing (M4), and the Conductor (M6). Deterministic law script must be auditable and non-Turing
+(no unbounded loops — it's a constitution, not a program).
+
+## 4. Does / does-not
+- **Does:** receive trade requests from Traders (M5); validate against the deterministic law
+  script (scoped invariants); check Conductor veto (M6); verify trader-wallet binding (no wallet
+  = no access); execute approved actions on-chain via the bound wallet's API; record all actions
+  for SAE (M7) monitoring; collect tax on realized income → Verschwörern Veregeister stub (M0).
+- **Does-not:** decide *what* to trade (Traders decide); predict markets (Sims do); hold keys
+  (Wallets do); supervise behavior (Conductor + SAE do).
+
+## 5. Interface contract
+- `submit_action(trader_id, action: MarketAction, wallet_id) -> { succeeded | failed }`.
+  Diagnostic reasons (law violation, veto, missing wallet) are internal — routed to Conductor
+  (M6) for upstream output. Immune system is a separate organ (out of scope here).
+  `MarketAction` ∈ { `buy`, `sell`, `mint`, `provide_liquidity`, `withdraw_liquidity`, `claim_rewards`, … }.
+- `law_check(action: MarketAction) -> { pass | violation(rule_id, reason) }` — deterministic,
+  pure function. The law script is loaded at startup and **immutable at runtime** (mirrors S3 /
+  the COBOL vault pattern).
+- `veto_check(action: MarketAction, trader_id) -> { approved | vetoed(reason) }` — calls M6
+  Conductor.
+- `execute(action: MarketAction, wallet_id) -> { tx_hash | error }` — on-chain execution via
+  wallet API.
+- `tax_event(trader_id, income_amount) -> receipt` — triggers tax collection.
+
+## 6. Dependencies & stubs
+- M4 Wallets — signing + execution; *stub:* "if finished, would sign and broadcast tx [details]".
+- M5 Traders — action source; *stub:* "if finished, would submit [action] for [asset] at [price]".
+- M6 Conductor — veto authority; *stub:* "if finished, would evaluate [action] against risk policy; approving".
+- M7 SAE — action log consumer; *stub:* "if finished, would analyze [action] for behavioral anomalies".
+- Blockchain RPCs — on-chain execution; *stub:* "if finished, would execute [action] on [chain], returning tx_hash".
+
+## 7. Invariants / laws
+- **L1 (C5):** **all market actions route through the Marketplace** — no direct on-chain
+  execution by any trader. This is the economy organ's S1.
+- **L2 (C5):** the **deterministic law script is immutable at runtime** — loaded at startup,
+  never modified by traders, conductor, or sims. Changes require a restart with a new script
+  version **and a pair of signatures from the operator and the Homunculus**. Mirrors the COBOL
+  vault (S3).
+- **L3 (C4):** **no wallet, no access** — a trader without a bound wallet cannot submit actions.
+  The Marketplace enforces this before any other check.
+- **L4 (C4):** **veto is checked after law, before execution** — law violations are rejected
+  outright; Conductor veto applies only to law-passing actions. The law is above the Conductor.
+- **L5 (C4):** **every action is logged** — SAE (M7) receives a record of every submitted
+  action (including rejected ones) for behavioral analysis.
+
+## 8. Build steps
+1. Define `MarketAction` types and the law script format.
+2. Implement the law checker (deterministic, pure, non-Turing).
+3. Wire veto check to M6 Conductor.
+4. Wire execution to M4 Wallet API.
+5. Wire action logging to M7 SAE.
+6. Implement tax collection on realized income.
+
+## 9. Tests
+Law enforcement: known violations rejected; valid actions pass. Veto: conductor veto blocks
+execution. Wallet binding: walletless trader rejected. Logging: every action (pass + fail) logged.
+Tax: income event triggers tax stub. Immutability: law script cannot be modified at runtime.
+
+## 10. Open items
+- The law script language/format (DSL? declarative rules? S-expressions?).
+- Which blockchain protocols/RPCs to support initially.
+- Position limits, drawdown stops, and other risk parameters — live in the law script or in the
+  Conductor's judgment?
+- Tax rate / calculation method (fixed %, tiered, per-asset?).
+- Non-Turing law script design — to discuss (format, expressiveness, bounds).

core/docs/plans/M2-data-feeds.md

@@ -0,0 +1,70 @@
+# M2 — Data feeds (market data pipeline)
+
+## 1. Component
+The economy organ's sensory nervous system: **live RSS feeds, price streams, and on-chain data**
+flowing into both the Marketplace (M1) and the Sims (M3). Sits between them — the Marketplace
+produces execution data (fills, positions, P&L) that feeds back into Sims, and Sims produce
+predictions that inform Traders operating through the Marketplace. Data Feeds is the bridge.
+
+## 2. Status / certainty
+DESIGN-FIRST · ABSENT. Role C3; implementation C1.
+
+## 3. Language & location
+TBD · `src/economy/feeds/`. Needs async I/O for streaming data (WebSockets, SSE, RSS polling).
+Pony actors are a natural fit (async, backpressure-aware).
+
+## 4. Does / does-not
+- **Does:** ingest live market data from external sources (RSS, price APIs, DEX subgraphs,
+  on-chain event logs); normalize heterogeneous data into a common internal format; distribute
+  to Sims (M3) for prediction and to Traders (M5) for decision-making; ingest Marketplace (M1)
+  execution data (fills, portfolio state) and feed it back into Sims for calibration; maintain
+  time-series history within session (ring buffer).
+- **Does-not:** predict (Sims do); trade (Marketplace does); filter or editorialize data — it
+  delivers raw, normalized feeds. Interpretation is the consumer's job.
+
+## 5. Interface contract
+- `subscribe(feed_type: FeedType, consumer_id) -> subscription_handle`.
+  `FeedType` ∈ { `price_tick`, `rss_news`, `on_chain_event`, `dex_pool_state`, `execution_fill`,
+  `portfolio_state` }.
+- `publish(feed_type, data_point: NormalizedDatum)` — internal; sources push into the pipeline.
+- `query_history(feed_type, time_range) -> [NormalizedDatum]` — sims and traders can pull
+  historical data within the session window.
+- `NormalizedDatum { feed_type, source, timestamp, payload, confidence }` — common shape.
+  `confidence` ∈ [0.0, 10.0] — data source reliability per position produced (exchange-reported
+  price = high; RSS sentiment = lower). Sims produce even finer-grained confidence.
+
+## 6. Dependencies & stubs
+- External data sources (price APIs, RSS, RPC nodes) — *stub:* canned market data replay.
+- M1 Marketplace — execution data source (fills, positions); *stub:* canned fills.
+- M3 Sims — primary consumer; *stub:* print data points.
+- M5 Traders — secondary consumer; *stub:* print data points.
+
+## 7. Invariants / laws
+- **L1 (C4):** data feeds are **raw and unnormalized in meaning** — the pipeline normalizes
+  *format* (schema, timestamps, units) but never interprets, filters, or editorialize content.
+- **L2 (C4):** **bidirectional flow** — external data flows in (market → sims/traders), and
+  internal execution data flows back (marketplace → sims). Both directions use the same
+  `NormalizedDatum` shape.
+- **L3 (C3):** **backpressure, not drop** — if a consumer is slow, buffer up to a cap, then
+  apply backpressure to the source. Never silently drop data points.
+- **L4 (C3):** every datum carries a **source and timestamp** — consumers can always trace
+  where data came from and when.
+
+## 8. Build steps
+1. Define `NormalizedDatum` and `FeedType` shapes.
+2. Implement the pub/sub pipeline (subscribe, publish, distribute).
+3. Wire external source adapters (start with one price API + one RSS feed).
+4. Wire M1 execution data feedback loop.
+5. Implement session-scoped time-series history (ring buffer).
+
+## 9. Tests
+Normalization: heterogeneous inputs produce uniform `NormalizedDatum` output. Pub/sub: subscriber
+receives published data. History: query returns correct time range. Backpressure: slow consumer
+does not cause data loss. Bidirectional: marketplace fills reach sims via the feed.
+
+## 10. Open items
+- Which price APIs / RSS sources to support initially (CoinGecko? DeFiLlama? specific DEX
+  subgraphs?).
+- History buffer size / eviction policy.
+- Whether feeds need authentication / rate limiting management.
+- Latency requirements (how fresh must data be for each consumer type?).

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

@@ -0,0 +1,94 @@
+# 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).

core/docs/plans/M3a-statistical-sims.md

@@ -0,0 +1,110 @@
+# M3a — Statistical & quantitative sims
+
+## 1. Component
+Pure statistical simulation: **Monte Carlo methods, Bayesian inference, time-series forecasting,
+stochastic volatility, regime detection, and cross-asset correlation**. The mathematical backbone
+— no game theory, no sociology, just the numbers. Operates across **six concurrent time horizons**
+(tick/hourly → daily → weekly → monthly → annual → 5-year). Pops in this sim represent
+**stochastic sample paths**, not behavioral agents.
+
+## 2. Status / certainty
+DESIGN-FIRST · ABSENT. Core quant methods C5 (GBM, GARCH, ARIMA — textbook). Heston stochastic
+volatility C5 (closed-form characteristic function; industry standard since 1993). Rough
+volatility C4 (Gatheral et al. 2018, heavily cited; crypto implementations exist). HMM regime
+detection C4 (established; crypto-specific copula hybrids emerging 2023–2024). Almgren-Chriss
+execution C5 (industry standard since 2001). Jump-diffusion C5 (Merton 1976). Parameterization
+for crypto markets C1.
+
+## 3. Language & location
+TBD · `src/economy/sims/statistical/`. Julia, R, Fortran, or Octave for numerical computing.
+Needs efficient matrix operations, SDE solvers, and distribution sampling. Fractional Brownian
+motion generation uses spectral methods (Hosking 1984, Wood & Chan 1994) or Cholesky
+decomposition of the covariance matrix.
+
+## 4. Does / does-not
+- **Does:** run Monte Carlo price simulations (GBM, Merton jump-diffusion, Heston stochastic
+  volatility); model volatility surface via **Heston SDE**:
+  $dS_t = \mu S_t dt + \sqrt{\nu_t} S_t dW_t^S$,
+  $d\nu_t = \kappa(\theta - \nu_t)dt + \xi\sqrt{\nu_t} dW_t^\nu$
+  with $\text{corr}(dW^S, dW^\nu) = \rho$ (mean-reversion speed $\kappa$, long-run variance
+  $\theta$, vol-of-vol $\xi$); model **rough volatility** via fractional Brownian motion
+  $dS_t = \mu dt + \sigma_t dB_t^H$ with Hurst exponent $H \approx 0.4$ capturing
+  antipersistent microstructure (Gatheral et al. 2018); detect **regime transitions** via
+  Hidden Markov Model: $r_t | s_t \sim \mathcal{N}(\mu_{s_t}, \sigma^2_{s_t})$,
+  $s_t \in \{\text{Bull, Neutral, Bear}\}$ with Viterbi filter updating in <5ms per tick;
+  model **cross-asset tail dependence** via DCC-GARCH copula hybrid:
+  $dQ_t/dt = a \cdot (\bar{S} - Q_t) + b \cdot (\varepsilon_t \varepsilon_t^T - Q_t)$
+  with $t$-Copula for fat-tailed spillovers (BTC→alts); Bayesian parameter estimation from
+  live data (M2); time-series forecasting (ARIMA, GARCH for volatility clustering); Value-at-Risk
+  and Expected Shortfall; produce bounded predictions with confidence intervals.
+- **Does-not:** model human behavior (M3b does); model protocol mechanics (M3c–M3f do);
+  trade or recommend (Traders do); optimize execution routing (M3g does using our vol estimates).
+
+## 5. Interface contract
+- Implements `query(PredictionQuery) -> BoundedPrediction` per M3 hub.
+- **Output bounds:** statistical confidence intervals (CI from Monte Carlo), Heston variance
+  bands (from $\nu_t$ process), rough-vol forecast cones, regime-conditional intervals.
+- **Time-horizon mapping** (all run concurrently):
+  | Horizon | Primary models | Update cadence |
+  |---------|---------------|----------------|
+  | Tick–hourly | Rough vol ($H \approx 0.4$), HMM regime filter, realized variance | Every tick |
+  | Daily | Heston vol surface, GARCH, DCC correlation | Every bar close |
+  | Weekly–monthly | Jump-diffusion Monte Carlo, regime-conditional forecasts | Hourly roll |
+  | Annual–5yr | SDE mean-reversion long-run $\theta$, macro regime priors | Daily roll |
+- Examples:
+  `{ value: 1847.30, lower_bound: 1790.15, upper_bound: 1905.60, confidence: 9.50,
+  time_horizon: "24h", sim_type: "statistical" }` — 95% CI on ETH price.
+  `{ value: 0.72, lower_bound: 0.58, upper_bound: 0.89, confidence: 9.00,
+  time_horizon: "1h", sim_type: "statistical" }` — Heston instantaneous vol $\sqrt{\nu_t}$.
+  `{ value: "bear", lower_bound: null, upper_bound: null, confidence: 8.30,
+  time_horizon: "current", sim_type: "statistical" }` — HMM regime state.
+- **Prediction types:** `price_forecast`, `volatility_surface`, `var_calculation`,
+  `correlation_matrix`, `regime_state`, `rough_vol_estimate`, `jump_intensity`.
+- Calibration: ingests `price_tick` and `dex_pool_state` from M2 Data Feeds.
+
+## 6. Dependencies & stubs
+- M2 Data Feeds — price history for calibration; *stub:* canned price series.
+- M3 Sims hub — lifecycle management; *stub:* manual init.
+
+## 7. Invariants / laws
+- **L1 (C5):** bounds are **statistical confidence intervals** — derived from the model's
+  distribution, not hand-picked. Three distinct metrics in every output: **confidence** (how sure
+  the model is of this prediction), **correctness** (how accurate the model has been historically),
+  and **certainty** (how stable the estimate is across perturbations). All on the 0.00–10.00 scale.
+- **L2 (C5):** **six time horizons run concurrently** — models span multiple horizons (e.g.
+  Monte Carlo runs daily and annual, rough vol runs tick and hourly, Heston runs daily and
+  weekly). All coexist; none blocks the others.
+- **L3 (C4):** model parameters are **re-estimated on each calibration** from live data — no
+  stale parameters carried across regime changes. Regime transitions trigger immediate
+  re-estimation of conditional parameters.
+- **L4 (C4):** the **Heston correlation $\rho$ between price and vol** is a fitted parameter,
+  never assumed — crypto assets exhibit leverage effects different from equities.
+- **L5 (C4):** rough volatility Hurst exponent $H$ is **estimated from realized variance**, not
+  fixed — $H$ varies across assets and regimes (Gatheral et al. 2018).
+
+## 8. Build steps
+1. Implement geometric Brownian motion Monte Carlo (simplest price sim).
+2. Add GARCH volatility estimation.
+3. Implement Heston SDE solver (Euler-Maruyama with full truncation for $\nu_t \geq 0$).
+4. Add Merton jump-diffusion (Poisson jumps + GBM).
+5. Implement rough volatility via fractional BM with rolling Hurst estimator.
+6. Implement HMM regime detector (3-state Viterbi filter).
+7. Add DCC-GARCH copula for cross-asset correlation.
+8. Wire M2 price data → Bayesian parameter re-estimation.
+9. Implement multi-horizon `BoundedPrediction` output with CIs.
+
+## 9. Tests
+Monte Carlo: N sample paths produce a distribution with correct mean/variance. CI: 95% interval
+contains true value ≥ 95% of the time on historical backtest. GARCH: volatility clusters detected
+in synthetic data. Heston: implied vol smile reproduced for known parameters. Rough vol: Hurst
+exponent recovered from synthetic fBM paths. HMM: regime transitions detected within 15–60s on
+synthetic regime-switching data. Copula: tail dependence captured (BTC crash → alt crash
+correlation spike). Jump-diffusion: fat tails reproduced. Calibration: new data shifts parameter
+estimates. Multi-horizon: all six horizons produce concurrent outputs.
+
+## 10. Open items
+- Heston calibration method (characteristic function inversion? particle filter?).
+- Rough vol computational cost (fBM generation is O(N²) naively; FFT methods needed).
+- HMM state count (3 sufficient? 4+ for crypto with "mania" regime?).
+- Which copula family for tail dependence ($t$-copula? Clayton? Joe?).
+- Computational budget per horizon (GPU for Monte Carlo paths?).

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

@@ -0,0 +1,121 @@
+# M3b — Sociological & population dynamics sims
+
+## 1. Component
+Sociological simulation: **evolutionary game theory, bounded rationality, opinion dynamics,
+complex contagion, adaptive learning populations, and Mean-Field Game equilibria** among market
+participants. Pops here are **behavioral archetypes** — retail herd followers, contrarian whales,
+MEV searchers, passive LPs, pump-and-dump manipulators — whose strategies evolve under selection
+pressure across **six concurrent time horizons**. Grounded in evolutionary consensus game models
+[8,9], Hegselmann-Krause opinion dynamics (2002), complex contagion theory (Centola & Macy 2007),
+MFG theory (Lasry & Lions 2007), and crypto manipulation ABMs.
+
+## 2. Status / certainty
+DESIGN-FIRST · ABSENT. Evolutionary game theory C4 (Cornell [8]). Hegselmann-Krause bounded
+confidence C5 (established 2002). Complex contagion C4 (Centola & Macy 2007; crypto applications
+C3). Bandit-replicator hybrid C3 (emerging). Mean-Field Games C4 (Lasry & Lions 2007; tensor-train
+solvers C3). Crypto pump-and-dump ABM C3 (3-agent protocol validated on historical data).
+Pop behavioral models C1.
+
+## 3. Language & location
+TBD · `src/economy/sims/sociological/`. Agent-based modeling frameworks (NetLogo, or custom).
+Needs efficient population iteration, strategy mutation, PDE solvers for MFG (HJB +
+Fokker-Planck), and bandit algorithms (UCB/Thompson). Julia, R, or Fortran.
+
+## 4. Does / does-not
+- **Does:** simulate populations of behavioral archetypes competing in a market; apply
+  **replicator dynamics** $dx_i/dt = x_i(\pi_i(x) - \bar{\pi}(x))$ to strategy distributions;
+  model **opinion clustering** via Hegselmann-Krause bounded confidence:
+  $x_i(t+1) = x_i(t) + \mu(x_j(t) - x_i(t))$ for $|x_i - x_j| \leq d$ — agents only update
+  toward neighbors within confidence bound $d$, creating natural clustering and trend-reversal
+  thresholds; model **complex contagion** with heterogeneous thresholds: adoption probability
+  $P_i = f(n_i / k_i)$ where multiple exposures amplify adoption non-linearly (captures meme-coin
+  rallies and narrative-driven pumps); implement **bandit-replicator hybrid** where pops use
+  UCB or Thompson Sampling to estimate strategy payoffs:
+  $x_i'(t) = x_i(t)[\lambda_i(t) - \bar{\lambda}(t)]$ with $\lambda_i = \text{UCB}(\theta_i)$
+  — bridges replicator dynamics with multi-armed bandit learning; solve **Mean-Field Game
+  equilibria** via coupled HJB + Fokker-Planck PDEs for large-population limits:
+  $-\partial_t u + H(x, \nabla u) = F(x, m)$ (HJB, individual optimization),
+  $\partial_t m - \nabla \cdot (m \nabla_p H) = 0$ (Fokker-Planck, population density) — Newton
+  iteration with tensor-train decomposition reduces $O(N^d)$ to $O(dNr^2)$ for high-dimensional
+  state spaces; simulate **crypto pump-and-dump protocol** with 3 pop types: Normal traders,
+  Market Analysts (MA, information-advantaged), Market Players (MP, manipulators) in a 4-phase
+  cycle (accumulation → promotion → distribution → collapse); model sentiment cascades
+  (fear/greed contagion across pop clusters); model bounded rationality (pops satisfice, not
+  optimize — heuristics, not perfect strategies); produce bounded predictions across all six
+  time horizons.
+- **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, sentiment scales, MFG equilibrium stability.
+- **Time-horizon mapping** (all run concurrently):
+  | Horizon | Primary models | Update cadence |
+  |---------|---------------|----------------|
+  | Hourly | Hegselmann-Krause opinion clusters, bandit-replicator | Every data tick |
+  | Daily | Complex contagion cascades, pump-and-dump phase detection | Hourly roll |
+  | Weekly | Replicator dynamics strategy evolution, MFG equilibrium | Daily roll |
+  | Monthly | Population archetype composition, narrative regime shifts | Weekly roll |
+  | Annual | Long-run evolutionary stable strategies (ESS) | Monthly roll |
+  | 5-year | MFG stationary equilibria, structural population shifts | Quarterly roll |
+- Examples:
+  `{ value: 7.3, lower_bound: 5.0, upper_bound: 9.1, confidence: 6.80,
+  time_horizon: "12h", sim_type: "sociological" }` — herd-panic index (0–10).
+  `{ value: 0.42, lower_bound: 0.31, upper_bound: 0.55, confidence: 7.20,
+  time_horizon: "1w", sim_type: "sociological" }` — fraction of pops in "contrarian" strategy.
+  `{ value: "promotion", lower_bound: null, upper_bound: null, confidence: 6.10,
+  time_horizon: "current", sim_type: "sociological" }` — pump-and-dump phase detection.
+  `{ value: 0.78, lower_bound: 0.65, upper_bound: 0.88, confidence: 7.00,
+  time_horizon: "30d", sim_type: "sociological" }` — MFG equilibrium stability index.
+  Models span multiple horizons — e.g. replicator dynamics runs hourly through annual; MFG
+  produces weekly equilibria and 5-year stationary states. The table shows primary assignments.
+- **Prediction types:** `sentiment_index`, `herd_threshold`, `strategy_distribution`,
+  `cascade_probability`, `coordination_stability`, `opinion_cluster_count`,
+  `pump_dump_phase`, `mfg_equilibrium_stability`, `narrative_regime`.
+- 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 (C5):** pops are **archetypes, not individuals** — no attempt to model or track real
+  market participants. The sim models emergent behavior from strategy populations.
+- **L2 (C5):** strategies **evolve** — the population distribution shifts over time via
+  replicator dynamics. No fixed strategy ratios.
+- **L3 (C4):** bounded rationality is the **default** — pops satisfice with heuristics, not
+  optimize with perfect information. Rational-agent models are a special case, not the baseline.
+- **L4 (C4):** **complex contagion requires multiple exposures** — adoption is non-linear in
+  neighbor count, not simple diffusion. Single-exposure models undercount threshold effects.
+- **L5 (C4):** the MFG limit is **valid only for large populations** — below ~100 pops, use
+  discrete replicator dynamics; above, the continuum HJB+FP approximation applies.
+- **L6 (C3):** pump-and-dump detection is **phase-based** — the 4-phase cycle (accumulate →
+  promote → distribute → collapse) has distinct statistical signatures in volume and price.
+
+## 8. Build steps
+1. Define pop archetypes and their heuristic strategies.
+2. Implement replicator dynamics (strategy evolution over generations).
+3. Implement Hegselmann-Krause bounded confidence opinion model.
+4. Implement complex contagion with heterogeneous thresholds.
+5. Implement bandit-replicator hybrid (UCB payoff estimation + replicator selection).
+6. Implement MFG solver (HJB + Fokker-Planck with Newton iteration).
+7. Implement pump-and-dump 3-type ABM (Normal, MA, MP) with 4-phase protocol.
+8. Wire M2 news/price data → calibration of pop parameters.
+9. Implement multi-horizon `BoundedPrediction` output.
+
+## 9. Tests
+Evolution: dominant strategy shifts when payoff landscape changes. Cascade: sentiment shock
+propagates through pop network above threshold, not below. Bounded confidence: opinion clusters
+form at predicted cluster count for given $d$. Complex contagion: multiple-exposure requirement
+produces slower but more robust adoption than simple contagion. Bandit: explore-exploit tradeoff
+produces adapting populations. MFG: equilibrium converges for large N; matches discrete sim for
+small N. Pump-dump: 4-phase cycle detected on synthetic manipulation data. 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.
+- MFG tensor-train rank $r$ (accuracy vs. compute tradeoff).
+- Hegselmann-Krause confidence bound $d$ — fixed or adaptive?
+- Cross-sim interaction: do sociological predictions feed into M3c (AMM) or M3d (MEV)?

core/docs/plans/M3c-amm-liquidity-sims.md

@@ -0,0 +1,76 @@
+# M3c — AMM & liquidity pool sims
+
+## 1. Component
+Automated Market Maker simulation: models **constant-product invariant mechanics, impermanent
+loss, and the non-cooperative game between liquidity providers and arbitrageurs**. Pops here are
+**LP positions and arbitrage bots** operating on the $x \cdot y = k$ curve. Grounded in the DEX/AMM
+literature [1,2].
+
+## 2. Status / certainty
+DESIGN-FIRST · ABSENT. Mathematical foundations C5 (constant product invariant is proven);
+impermanent loss formula C5 (closed-form: $\text{IL}(r) = \frac{2\sqrt{r}}{1+r} - 1$);
+simulation parameterization C1.
+
+## 3. Language & location
+TBD · `src/economy/sims/amm/`. Needs precise fixed-point or arbitrary-precision arithmetic for
+invariant calculations. Solidity for on-chain-equivalent precision; Julia or Octave for
+analytical models.
+
+## 4. Does / does-not
+- **Does:** simulate constant-product pools with fee parameter $\gamma$:
+  $(x + \gamma \Delta x)(y - \Delta y) = k$; model impermanent loss as a function of price ratio
+  shift $r$; simulate LP strategies (provide, withdraw, rebalance) against arbitrageur behavior;
+  model non-linear price slippage from the curve geometry; produce bounded predictions on pool
+  profitability, IL risk, and optimal LP ranges.
+- **Does-not:** model consensus mechanics (M3f); model social behavior (M3b); execute real swaps
+  (Marketplace does).
+
+## 5. Interface contract
+- Implements `query(PredictionQuery) -> BoundedPrediction` per M3 hub.
+- **Output bounds:** IL ranges and pool return intervals.
+  Example: `{ value: -0.034, lower_bound: -0.058, upper_bound: -0.012, confidence: 9.00,
+  time_horizon: "7d", sim_type: "amm_liquidity" }` — projected impermanent loss for ETH/USDC pool.
+  Example: `{ value: 0.082, lower_bound: 0.041, upper_bound: 0.127, confidence: 8.50,
+  time_horizon: "30d", sim_type: "amm_liquidity" }` — net LP return (fees − IL).
+- **Time-horizon mapping** (all run concurrently, tick-advanced, 90:1 (1s wall = 90s sim)):
+  | Horizon | Primary models | Update cadence |
+  |---------|---------------|----------------|
+  | Tick–hourly | Slippage curves, invariant state, JIT liquidity | Every swap event |
+  | Daily | IL accumulation, fee income, LP profitability | Hourly roll |
+  | Weekly | Optimal LP range recalculation, pool composition | Daily roll |
+  | Monthly | LP strategy evolution (passive vs. active rebalance) | Weekly roll |
+  | Annual | Pool lifecycle, fee tier competitiveness | Monthly roll |
+  | 5-year | AMM design evolution, concentrated liquidity adoption | Quarterly roll |
+- **Prediction types:** `impermanent_loss`, `pool_return`, `optimal_range`, `slippage_estimate`,
+  `lp_withdrawal_threshold`.
+- Calibration: ingests `dex_pool_state` and `price_tick` from M2.
+
+## 6. Dependencies & stubs
+- M2 Data Feeds — pool state and price data; *stub:* canned pool snapshots.
+- M3 Sims hub — lifecycle management; *stub:* manual init.
+
+## 7. Invariants / laws
+- **L1 (C5):** the **constant product invariant** $x \cdot y = k$ (adjusted for fees $\gamma$)
+  is the ground truth — all pool state transitions must satisfy the invariant or the sim is wrong.
+- **L2 (C5):** **impermanent loss** follows the proven formula
+  $\text{IL}(r) = \frac{2\sqrt{r}}{1+r} - 1$ — the sim must reproduce this exactly for the
+  base case (no fees, no concentrated liquidity).
+- **L3 (C4):** LP withdrawal thresholds are **derived from IL, not hardcoded** — the sim
+  calculates at what price ratio a rational LP withdraws, based on the IL formula and fee income.
+
+## 8. Build steps
+1. Implement the constant-product pool simulator with fee parameter.
+2. Verify IL formula reproduction against known inputs.
+3. Add LP pop strategies (passive hold, active rebalance, just-in-time liquidity).
+4. Add arbitrageur pops (sandwich, backrun).
+5. Wire M2 pool state data → calibration.
+
+## 9. Tests
+Invariant: every swap satisfies $(x + \gamma \Delta x)(y - \Delta y) = k$. IL formula: matches
+closed-form for known price ratios. Slippage: large swaps produce greater slippage than small.
+LP threshold: LP withdraws when IL exceeds fee income. Bounds: all outputs bounded.
+
+## 10. Open items
+- Concentrated liquidity (Uniswap v3 style) — extends the base model significantly.
+- Multi-pool routing (split swaps across pools).
+- Which specific pools to simulate (ETH/USDC? stablecoin pairs?).

core/docs/plans/M3d-mev-adversarial-sims.md

@@ -0,0 +1,114 @@
+# M3d — MEV & adversarial extraction sims
+
+## 1. Component
+Maximal Extractable Value and adversarial simulation: models **transaction ordering as an
+optimization problem**, **Priority Gas Auctions (PGA) as all-pay auctions**, **block building as a
+multidimensional knapsack problem**, **cross-chain adversarial arbitrage**, and **Dynamic
+Stackelberg Mean-Field Games (DSMFG) for protocol-level adversarial policy**. Pops here are
+**searcher bots, block builders, validators, cross-chain arbitrageurs, and adversarial
+manipulators** competing for extractable value across **six concurrent time horizons**.
+
+Grounded in ACM MEV game theory [3], knapsack auction literature [4,5], Kolokoltsov adversarial
+dynamics (non-linear Fokker-Planck with WENO shock capturing), and DSMFG bilevel optimization
+(leader policy + follower MFG equilibrium).
+
+## 2. Status / certainty
+DESIGN-FIRST · ABSENT. PGA-as-all-pay-auction C4 (ACM [3]); knapsack formulation C4 (Cornell
+[4,5]); cross-chain arbitrage C4 (ACM SIGMETRICS 2025, 5.5x growth since Dencun); DSMFG bilevel
+optimization C3 (emerging — SMFRL solvers); Kolokoltsov adversarial C3 (non-linear Fokker-Planck;
+WENO discretization established but crypto application novel). Parameterization C1.
+
+## 3. Language & location
+TBD · `src/economy/sims/mev/`. Needs combinatorial optimization (OR-Tools for knapsack),
+continuous-time auction modeling, PDE solvers (WENO for shock-capturing in adversarial dynamics),
+and bilevel optimization (DSMFG). Julia or Fortran.
+
+## 4. Does / does-not
+- **Does:** simulate Priority Gas Auctions where multiple searcher bots compete for the same
+  arbitrage opportunity $V$ by bidding gas fees $g$ in a continuous-time all-pay auction; model
+  block building as a multidimensional knapsack problem (scarce block space, heterogeneous
+  transaction values/sizes); simulate endogenous selection cutoffs under paid-priority ordering;
+  model **cross-chain adversarial arbitrage** with inventory vs. bridge execution trade-off:
+  $\pi_{\text{inv}} = (P_{\text{src}} - P_{\text{dst}} - \text{slippage} - \text{gas}) \times q$
+  vs. $\pi_{\text{bridge}} = (P_{\text{src}} - P_{\text{dst}} - \text{fee} -
+  \text{depreciation}(\Delta t)) \times q$ where bridge latency $\Delta t \approx 242$s vs.
+  inventory $\Delta t \approx 9$s; solve **Dynamic Stackelberg MFG** for adversarial policy
+  design — bilevel optimization where a leader (protocol/regulator) sets policy and followers
+  (searchers) respond as an MFG equilibrium: the leader solves
+  $\min_\alpha J_L(\alpha, m^*(\alpha))$ subject to $m^*(\alpha)$ being the MFG Nash equilibrium
+  of followers under policy $\alpha$; model **Kolokoltsov adversarial dynamics** via non-linear
+  Fokker-Planck: $\partial_t m + \nabla \cdot (b(x,m)m) = \frac{1}{2}\nabla^2(\sigma^2 m)$
+  with WENO shock-capturing for discontinuous adversarial strategies; predict MEV exposure for
+  proposed trades; produce bounded predictions on extraction risk across all six time horizons.
+- **Does-not:** extract MEV itself (simulator, not a searcher); model AMM pool math (M3c);
+  model social dynamics (M3b); execute cross-chain bridges (Marketplace does).
+
+## 5. Interface contract
+- Implements `query(PredictionQuery) -> BoundedPrediction` per M3 hub.
+- **Output bounds:** extraction probability ranges, gas cost intervals, cross-chain profit
+  bounds, DSMFG equilibrium stability ranges.
+- **Time-horizon mapping** (all run concurrently, tick-advanced, 90:1 (1s wall = 90s sim)):
+  | Horizon | Primary models | Update cadence |
+  |---------|---------------|----------------|
+  | Tick–hourly | PGA auctions, sandwich detection, cross-chain arb | Every block |
+  | Daily | Knapsack builder strategies, MEV landscape | Hourly roll |
+  | Weekly | Searcher population dynamics, cross-chain flow patterns | Daily roll |
+  | Monthly | DSMFG policy equilibria, adversarial strategy evolution | Weekly roll |
+  | Annual | Kolokoltsov adversarial long-run dynamics | Monthly roll |
+  | 5-year | Structural MEV regime shifts, protocol-level policy effects | Quarterly roll |
+- Examples:
+  `{ value: 0.23, lower_bound: 0.11, upper_bound: 0.38, confidence: 8.00,
+  time_horizon: "next_block", sim_type: "mev_adversarial" }` — sandwich probability.
+  `{ value: 14.7, lower_bound: 8.2, upper_bound: 22.5, confidence: 7.50,
+  time_horizon: "next_block", sim_type: "mev_adversarial" }` — optimal gas bid (gwei).
+  `{ value: 0.034, lower_bound: 0.018, upper_bound: 0.052, confidence: 8.20,
+  time_horizon: "1h", sim_type: "mev_adversarial" }` — cross-chain arb profit (ETH).
+- **Prediction types:** `sandwich_probability`, `frontrun_risk`, `optimal_gas_bid`,
+  `block_inclusion_probability`, `mev_exposure`, `cross_chain_arb_profit`,
+  `adversarial_policy_stability`, `searcher_population_shift`.
+- Calibration: ingests `on_chain_event` (mempool-like data), `price_tick`, and cross-chain
+  bridge state from M2.
+
+## 6. Dependencies & stubs
+- M2 Data Feeds — on-chain events, gas data, cross-chain state; *stub:* canned snapshots.
+- M3 Sims hub — lifecycle management; *stub:* manual init.
+- M3c AMM sims — pool state for arbitrage opportunity detection; *stub:* fixed pool state.
+
+## 7. Invariants / laws
+- **L1 (C5):** PGA is modeled as an **all-pay auction** — all bidders pay their gas whether they
+  win or not. The sim must capture this cost structure (not winner-pays-only).
+- **L2 (C5):** block building is a **knapsack problem, not a queue** — builders optimize for
+  total extracted value subject to gas limit constraints, not first-come-first-served.
+- **L3 (C4):** MEV exposure predictions are **pre-trade** — traders query this sim *before*
+  submitting to the Marketplace to understand their extraction risk.
+- **L4 (C4):** cross-chain arb models **both execution paths** — inventory (fast, capital-
+  intensive) and bridge (slow, capital-light) — never assumes one dominates.
+- **L5 (C3):** DSMFG solutions are **bilevel** — the leader's optimal policy depends on the
+  followers' MFG equilibrium, which itself depends on the leader's policy. Fixed-point iteration
+  or SMFRL solvers required.
+
+## 8. Build steps
+1. Implement the PGA all-pay auction model (N searchers, opportunity value V, gas bids).
+2. Implement the block-building knapsack solver.
+3. Add sandwich/frontrun detection heuristics.
+4. Implement cross-chain arb model (inventory vs. bridge, latency, MEV exposure).
+5. Implement Kolokoltsov non-linear Fokker-Planck with WENO discretization.
+6. Implement DSMFG bilevel solver (leader policy + follower MFG equilibrium).
+7. Wire M2 on-chain + cross-chain data → calibration.
+8. Wire pre-trade query interface for Traders.
+
+## 9. Tests
+All-pay: losing bidders still pay gas cost. Knapsack: builder selects optimal transaction set
+under gas limit. Sandwich: known sandwich-vulnerable trade flagged; non-vulnerable trade clear.
+Cross-chain: inventory path preferred when latency advantage exceeds capital cost. DSMFG: leader
+policy converges to fixed point with follower equilibrium. Kolokoltsov: WENO captures shock
+discontinuities in adversarial strategy distribution. Bounds: all outputs bounded. Pre-trade:
+query does not submit any transaction. Speed: sim tick-advances at 90:1.
+
+## 10. Open items
+- Mempool data access (public mempool? private order flow?).
+- Which MEV types to model initially (sandwich, backrun, liquidation, JIT?).
+- Multi-block MEV (cross-block extraction strategies).
+- DSMFG solver choice (SMFRL? fictitious play? direct bilevel optimization?).
+- WENO order for Kolokoltsov (3rd? 5th? tradeoff with compute budget).
+- Which L2s/bridges to model for cross-chain (Arbitrum? Optimism? Base?).

core/docs/plans/M3e-tokenomics-macro-sims.md

@@ -0,0 +1,118 @@
+# M3e — Tokenomics & macro-state sims
+
+## 1. Component
+Macro-level token economy simulation: models **token supply dynamics, monetary policy (halvings,
+burns, inflation), lending protocol dynamics, DeFi systemic risk, and stock-flow balances** using
+stochastic differential equations (SDEs), state-space models, kinked interest rate curves, and
+inter-protocol credit exposure networks. Pops here are **aggregate behavioral cohorts**
+(miners/validators, holders, speculators, protocol treasuries, borrowers/lenders) whose collective
+behavior drives token-level dynamics across **six concurrent time horizons** at tick-advanced, 90:1 (1s wall = 90s sim).
+
+Grounded in Vienna complex-systems token modeling [7], ResearchGate engineering token economy
+frameworks [6], Aave/Compound kinked interest rate models (industry standard), and DeXposure
+inter-protocol credit propagation (Matzakos et al. 2025).
+
+## 2. Status / certainty
+DESIGN-FIRST · ABSENT. SDE state-space framework C4 (Vienna [7]); stock-flow modeling C4
+(ResearchGate [6]); kinked interest rate model C5 (Aave/Compound production standard);
+DeXposure inter-protocol credit propagation C3 (emerging, 2025 — high DeFi specificity);
+composable yield optimization C4 (Yearn v3, Beefy, production-validated). Specific parameters C1.
+
+## 3. Language & location
+TBD · `src/economy/sims/tokenomics/`. Needs SDE solvers (Euler-Maruyama, Milstein),
+state-space estimation, and VAR (vector autoregression) for credit exposure impulse responses.
+Julia (DifferentialEquations.jl) or Octave.
+
+## 4. Does / does-not
+- **Does:** simulate token state dynamics via the SDE framework:
+  $dX_t = f(X_t, u(X_t, t), t)dt + \sigma(X_t, t)dW_t$ where $X_t$ is the system state vector,
+  $u$ is the behavioral policy function, deterministic drift captures programmatic parameters
+  (halvings, burns), and Brownian motion $\sigma dW_t$ captures stochastic behavioral shocks;
+  model stock-flow balances (circulating supply, staked, locked, burned); simulate monetary
+  policy impacts (halving events, fee burns, treasury emissions); model **lending protocol
+  dynamics** via kinked interest rate curves:
+  $R = R_0 + R_{\text{slope1}} \times U$ if $U \leq U_{\text{opt}}$,
+  $R = R_0 + R_{\text{slope1}} \times U_{\text{opt}} + R_{\text{slope2}} \times
+  (U - U_{\text{opt}})$ if $U > U_{\text{opt}}$ where $U = \text{Borrowed}/(\text{Supplied} +
+  \text{Borrowed})$, $U_{\text{opt}} \approx 0.8$ — cascade liquidations when
+  $\text{collateral} \times \text{LTV} < \text{borrowed}$; model **DeFi systemic risk** via
+  DeXposure inter-protocol credit propagation:
+  $E_{ij}(t) = \sum_{\text{tokens}} [\text{TVL}_j(\text{token}) \times
+  \text{ownership}_i(\text{token})]$ with VAR impulse responses for shock contagion across
+  protocols sharing collateral; model **composable yield optimization**:
+  $\max \sum_i w_i(t) \cdot \text{APY}_i(t) - \lambda \sum_i w_i(t)^2 \sigma_i^2(t)$
+  subject to $\sum_i w_i = 1$ — dynamic rebalancing across lending, LP, and staking strategies;
+  produce bounded predictions on token supply, protocol health, yield, and systemic risk.
+- **Does-not:** model individual transactions (M3c/M3d); model social sentiment (M3b);
+  model consensus mechanics (M3f); execute yield strategies (Traders/Marketplace do).
+
+## 5. Interface contract
+- Implements `query(PredictionQuery) -> BoundedPrediction` per M3 hub.
+- **Output bounds:** SDE confidence bands, utilization rate ranges, contagion impact intervals.
+- **Time-horizon mapping** (all run concurrently, tick-advanced, 90:1 (1s wall = 90s sim)):
+  | Horizon | Primary models | Update cadence |
+  |---------|---------------|----------------|
+  | Hourly | Lending rates, utilization, liquidation risk | Every block |
+  | Daily | Yield optimization, protocol TVL flows | Hourly roll |
+  | Weekly | SDE supply trajectory, stock-flow balances | Daily roll |
+  | Monthly | DeXposure credit contagion, systemic risk | Weekly roll |
+  | Annual | Halving/burn policy impacts, inflation trajectory | Monthly roll |
+  | 5-year | Token supply long-run equilibrium, protocol lifecycle | Quarterly roll |
+- Examples:
+  `{ value: 2.1, lower_bound: 1.4, upper_bound: 3.2, confidence: 9.00,
+  time_horizon: "90d", sim_type: "tokenomics_macro" }` — annualized inflation rate (%).
+  `{ value: 0.67, lower_bound: 0.58, upper_bound: 0.74, confidence: 8.50,
+  time_horizon: "30d", sim_type: "tokenomics_macro" }` — staking ratio.
+  `{ value: 0.83, lower_bound: 0.78, upper_bound: 0.91, confidence: 8.80,
+  time_horizon: "1h", sim_type: "tokenomics_macro" }` — Aave ETH utilization rate.
+  `{ value: 0.12, lower_bound: 0.04, upper_bound: 0.25, confidence: 7.20,
+  time_horizon: "7d", sim_type: "tokenomics_macro" }` — systemic contagion risk index.
+- **Prediction types:** `supply_trajectory`, `inflation_rate`, `staking_ratio`,
+  `velocity_estimate`, `halving_impact`, `treasury_runway`, `utilization_rate`,
+  `liquidation_cascade_risk`, `systemic_contagion_index`, `optimal_yield_allocation`.
+- Calibration: ingests `on_chain_event` (supply metrics, staking data, lending protocol state,
+  TVL) from M2.
+
+## 6. Dependencies & stubs
+- M2 Data Feeds — on-chain supply/staking/lending data; *stub:* canned supply snapshots.
+- M3 Sims hub — lifecycle management; *stub:* manual init.
+
+## 7. Invariants / laws
+- **L1 (C5):** the SDE framework is the **canonical representation** — all token dynamics are
+  expressed as drift + diffusion. Deterministic policy (halvings, burns) lives in the drift $f$;
+  behavioral uncertainty lives in the diffusion $\sigma dW_t$.
+- **L2 (C5):** **stock-flow conservation** — tokens are never created or destroyed outside the
+  protocol's defined mechanisms. circulating + staked + locked + burned = total ever minted.
+- **L3 (C5):** lending rate curves are **kinked at $U_{\text{opt}}$** — the steep slope above
+  optimal utilization is a design invariant of Aave/Compound, not a parameter to smooth.
+- **L4 (C4):** macro sims operate on **aggregate cohorts, not individuals** — the state vector
+  $X_t$ tracks population-level quantities (total staked, total circulating), not per-wallet.
+- **L5 (C4):** DeXposure contagion is **directional** — protocol A's exposure to protocol B
+  is not symmetric. The exposure matrix $E_{ij}$ is not assumed symmetric.
+
+## 8. Build steps
+1. Implement Euler-Maruyama SDE solver for a simple token model (supply + staking).
+2. Define the state vector $X_t$ and drift/diffusion functions for a reference token.
+3. Add stock-flow accounting (verify conservation).
+4. Implement kinked lending rate model (Aave-style) with liquidation cascade simulation.
+5. Implement DeXposure credit propagation network with VAR impulse responses.
+6. Implement composable yield optimizer (risk-adjusted return maximization).
+7. Wire M2 on-chain data → state estimation / calibration.
+8. Add monetary policy events (halving, burn) as drift discontinuities.
+
+## 9. Tests
+SDE: sample paths have correct mean (matches drift) and variance (matches diffusion). Stock-flow:
+conservation holds across all time steps. Halving: supply growth rate drops at halving event.
+Lending: rate curve exhibits kink at $U_{\text{opt}}$; liquidation cascades triggered when
+collateral ratio breached. DeXposure: shock to protocol A propagates to protocol B through shared
+collateral; isolated protocols unaffected. Yield: optimizer rebalances toward highest risk-adjusted
+APY. Calibration: state estimate converges to observed data. Bounds: SDE confidence bands cover
+realized paths on backtest. Speed: sim tick-advances at 90:1.
+
+## 10. Open items
+- Which tokens to model initially (ETH? BTC? a specific alt?).
+- State vector dimensionality (how many state variables per token model?).
+- Behavioral policy function $u(X_t, t)$ — how to parameterize aggregate cohort behavior.
+- Multi-token interactions (correlated diffusions across tokens?).
+- DeXposure graph granularity (how many protocols? top-10 by TVL?).
+- Lending model extensions (Morpho AdaptiveCurveIRM? variable kink parameters?).

core/docs/plans/M3f-consensus-staking-sims.md

@@ -0,0 +1,88 @@
+# M3f — Consensus & staking game sims
+
+## 1. Component
+Consensus-layer simulation: models **Proof-of-Stake validation dynamics, staking pool game theory,
+and Byzantine fault tolerance** using evolutionary games and Markov chains. Pops here are
+**validators and staking pool operators** whose honesty is a dynamic, evolving strategy under
+financial incentives. Grounded in Cornell evolutionary consensus [8,9], ACM staking pool risk
+theorems [10], and Monash dynamic PBFT modeling [11].
+
+## 2. Status / certainty
+DESIGN-FIRST · ABSENT. Evolutionary PoS game theory C4 (Cornell [8]); staking pool Nash
+equilibrium proofs C4 (ACM [10]); Markov chain throughput models C4 (Monash [11]); MFG for
+validator populations C4 (Lasry & Lions 2007; validator-specific application C3);
+simulation parameterization C1.
+
+## 3. Language & location
+TBD · `src/economy/sims/consensus/`. Needs Markov chain solvers and game-theoretic equilibrium
+computation. Julia, R, or Fortran.
+
+## 4. Does / does-not
+- **Does:** simulate validator populations where honesty evolves via **evolutionary game theory**
+  under bounded rationality [8]; model staking pool delegation as a game with proven reward-
+  parameter thresholds enforcing subgame-perfect Nash equilibria favoring honest validation over
+  malicious slashing [10]; simulate **throughput stability under shifting validator states** via
+  Markov chains [11]; solve **Mean-Field Game equilibria for large validator populations** —
+  coupled HJB (individual validator optimization) + Fokker-Planck (population density):
+  $-\partial_t u + H(x, \nabla u) = F(x, m)$, $\partial_t m - \nabla \cdot (m \nabla_p H) = 0$
+  — captures emergent staking coordination without enumerating every validator; predict slashing
+  risk, validator set stability, and staking yield across **six concurrent time horizons** at
+  tick-advanced, 90:1 (1s wall = 90s sim); produce bounded predictions on consensus health and staking returns.
+- **Does-not:** validate blocks (this is a simulator); model AMM pools (M3c); model token supply
+  (M3e — but consumes staking ratio from M3e as input).
+
+## 5. Interface contract
+- Implements `query(PredictionQuery) -> BoundedPrediction` per M3 hub.
+- **Output bounds:** equilibrium stability ranges and yield intervals.
+  Example: `{ value: 0.89, lower_bound: 0.82, upper_bound: 0.94, confidence: 8.80,
+  time_horizon: "7d", sim_type: "consensus_staking" }` — fraction of validators honest in
+  equilibrium.
+  Example: `{ value: 4.2, lower_bound: 3.6, upper_bound: 5.1, confidence: 8.20,
+  time_horizon: "30d", sim_type: "consensus_staking" }` — annualized staking yield (%).
+- **Time-horizon mapping** (all run concurrently, tick-advanced, 90:1 (1s wall = 90s sim)):
+  | Horizon | Primary models | Update cadence |
+  |---------|---------------|----------------|
+  | Hourly | Markov chain validator state transitions | Every epoch |
+  | Daily | Replicator dynamics strategy shifts, slashing events | Hourly roll |
+  | Weekly | Staking pool Nash equilibrium recalculation | Daily roll |
+  | Monthly | MFG equilibrium for validator population | Weekly roll |
+  | Annual | Evolutionary stable strategies, yield trajectory | Monthly roll |
+  | 5-year | Consensus mechanism structural evolution | Quarterly roll |
+- **Prediction types:** `validator_honesty_fraction`, `slashing_probability`, `staking_yield`,
+  `pool_delegation_equilibrium`, `throughput_stability`, `consensus_liveness`,
+  `mfg_validator_equilibrium`.
+- Calibration: ingests `on_chain_event` (validator set changes, slashing events) from M2.
+
+## 6. Dependencies & stubs
+- M2 Data Feeds — validator/staking on-chain data; *stub:* canned validator snapshots.
+- M3e Tokenomics — staking ratio as macro input; *stub:* fixed ratio.
+- M3 Sims hub — lifecycle management; *stub:* manual init.
+
+## 7. Invariants / laws
+- **L1 (C4):** validator honesty is a **dynamic equilibrium, not a fixed parameter** — it evolves
+  via replicator dynamics as payoffs change. The sim must not assume fixed honesty rates.
+- **L2 (C4):** the staking pool reward threshold is **mathematically derived** — the sim must
+  reproduce the subgame-perfect Nash equilibrium from the ACM proofs [10], not use ad-hoc
+  thresholds.
+- **L3 (C4):** throughput is modeled as a **Markov chain** over validator states (active, pending,
+  slashed, exited) — transitions are stochastic with rates calibrated from on-chain data [11].
+
+## 8. Build steps
+1. Implement the evolutionary honesty game (replicator dynamics, bounded rationality).
+2. Implement the Markov chain validator-state model.
+3. Reproduce the staking pool Nash equilibrium reward threshold from [10].
+4. Implement MFG solver (HJB + Fokker-Planck) for large validator populations.
+5. Wire M2 validator data → calibration of transition rates.
+6. Wire M3e staking ratio input.
+
+## 9. Tests
+Equilibrium: honesty fraction converges to Nash equilibrium under stable payoffs. Markov:
+stationary distribution matches expected validator state proportions. Threshold: pool delegation
+equilibrium matches the ACM proof for test parameters. Bounds: all outputs bounded. Liveness:
+throughput degrades when honest fraction drops below threshold.
+
+## 10. Open items
+- Which PoS protocol to model initially (Ethereum? a specific L2?).
+- Bounded rationality implementation (noisy best-response? epsilon-greedy? logit?).
+- Slashing severity parameterization.
+- Cross-sim: does consensus instability feed into M3b sociological panic signals?

core/docs/plans/M3g-market-microstructure-sims.md

@@ -0,0 +1,100 @@
+# M3g — Market microstructure sims
+
+## 1. Component
+Market microstructure simulation: models **order flow, liquidity depth, slippage, spread dynamics,
+optimal execution, and cross-exchange arbitrage** at the fastest time scales. Pops here are
+**market makers, takers, and arbitrageurs** interacting across multiple venues. Includes the
+**Almgren-Chriss optimal execution framework** for minimizing market impact of large orders.
+Operates at the highest temporal resolution — where M3a provides statistical forecasts and M3c
+models pool mechanics, M3g models the *plumbing* of how orders actually execute, across **six
+concurrent time horizons** at tick-advanced, 90:1 (1s wall = 90s sim).
+
+## 2. Status / certainty
+DESIGN-FIRST · ABSENT. Order-book microstructure theory C4 (established). Almgren-Chriss
+optimal execution C5 (industry standard since 2001; crypto adaptations validated 2023–2024,
+Kurz CMC thesis). DEX-specific microstructure C2 (emerging). Implementation C1.
+
+## 3. Language & location
+TBD · `src/economy/sims/microstructure/`. Needs high-frequency data handling, event-driven
+simulation, and Riccati equation solvers for optimal execution trajectories. Fortran or Julia.
+
+## 4. Does / does-not
+- **Does:** simulate order flow across venues (DEXs and CEXs); model bid-ask spread dynamics as a
+  function of inventory risk and adverse selection; simulate slippage curves for various order
+  sizes; solve **Almgren-Chriss optimal execution**:
+  $\min \int_0^T [\lambda \cdot x(t) \cdot \dot{x}(t) + \eta \cdot \dot{x}(t)^2] \, dt$
+  where $\lambda$ = permanent impact, $\eta$ = temporary impact, $x(t)$ = remaining order —
+  splits large orders across time to minimize market impact + timing risk; impact parameters
+  $\lambda, \eta$ re-estimated from order-flow streams every 10–30s; execution trajectory solved
+  via Riccati equations in <100ms; model cross-exchange arbitrage opportunities and their decay;
+  operate at **tick-level resolution** (sub-second to minute); produce bounded predictions on
+  execution quality, optimal routing, and liquidity conditions.
+- **Does-not:** model protocol consensus (M3f); model macro token supply (M3e); model social
+  behavior (M3b); execute trades (Marketplace does).
+
+## 5. Interface contract
+- Implements `query(PredictionQuery) -> BoundedPrediction` per M3 hub.
+- **Output bounds:** execution cost ranges, liquidity intervals, optimal trajectory envelopes.
+- **Time-horizon mapping** (all run concurrently, tick-advanced, 90:1 (1s wall = 90s sim)):
+  | Horizon | Primary models | Update cadence |
+  |---------|---------------|----------------|
+  | Tick–hourly | Almgren-Chriss execution, slippage, spread, arb decay | Every tick |
+  | Daily | Liquidity regime, venue depth profiles | Hourly roll |
+  | Weekly | Cross-venue flow patterns, impact parameter drift | Daily roll |
+  | Monthly | Structural liquidity shifts, venue market share | Weekly roll |
+  | Annual | Microstructure regime (DEX vs CEX share evolution) | Monthly roll |
+  | 5-year | Venue topology evolution, structural impact trends | Quarterly roll |
+- Examples:
+  `{ value: 0.0034, lower_bound: 0.0018, upper_bound: 0.0052, confidence: 8.50,
+  time_horizon: "next_trade", sim_type: "market_microstructure" }` — slippage (%) for 10 ETH.
+  `{ value: 12400, lower_bound: 8200, upper_bound: 18600, confidence: 7.80,
+  time_horizon: "1h", sim_type: "market_microstructure" }` — depth (USD) within 50bps.
+  `{ value: [0.3, 0.3, 0.2, 0.1, 0.1], lower_bound: null, upper_bound: null, confidence: 8.00,
+  time_horizon: "30min", sim_type: "market_microstructure" }` — Almgren-Chriss optimal execution
+  schedule (fraction per 6-min bucket for 100 ETH sell).
+- **Prediction types:** `slippage_estimate`, `spread_forecast`, `depth_profile`,
+  `cross_venue_arb`, `optimal_execution_schedule`, `optimal_execution_route`,
+  `liquidity_score`, `impact_estimate`.
+- Calibration: ingests `price_tick`, `dex_pool_state`, and `execution_fill` from M2.
+
+## 6. Dependencies & stubs
+- M2 Data Feeds — tick data and pool state; *stub:* canned order book snapshots.
+- M3a Statistical — volatility estimates for Almgren-Chriss timing risk; *stub:* fixed vol.
+- M3c AMM sims — pool mechanics for DEX venues; *stub:* fixed pool state.
+- M3 Sims hub — lifecycle management; *stub:* manual init.
+
+## 7. Invariants / laws
+- **L1 (C5):** microstructure operates at the **highest temporal resolution** — predictions are
+  valid for seconds to hours, not days. Stale microstructure data is worse than no data.
+- **L2 (C5):** slippage is a **function of order size and current depth** — not a fixed
+  percentage. The sim must model the non-linear relationship.
+- **L3 (C5):** Almgren-Chriss impact parameters $\lambda, \eta$ are **estimated from live data**,
+  never hardcoded — crypto impact dynamics differ by asset, venue, and time-of-day.
+- **L4 (C4):** cross-venue arbitrage opportunities **decay** — the sim models the time-to-close
+  of an arb opportunity, not just its existence.
+- **L5 (C4):** optimal execution trajectories are **re-solved on every significant state change**
+  (vol spike, depth drop, regime transition) — a stale trajectory is worse than naive execution.
+
+## 8. Build steps
+1. Implement a simplified order-book simulator (limit orders, market orders, cancels).
+2. Add spread dynamics (inventory-based market maker model).
+3. Add slippage curves (order size → execution cost).
+4. Implement Almgren-Chriss optimal execution (Riccati solver, impact estimation).
+5. Add cross-venue arb detection and decay modeling.
+6. Wire M2 tick data → calibration of impact parameters.
+7. Wire M3a vol estimates → Almgren-Chriss timing risk component.
+
+## 9. Tests
+Slippage: larger orders produce greater slippage. Spread: spread widens under adverse selection.
+Almgren-Chriss: optimal trajectory minimizes total cost vs. naive execution on backtest; impact
+parameters update when market conditions change. Arb decay: detected arb opportunity closes over
+time. Depth: depth profile matches order book state. Bounds: all outputs bounded. Resolution:
+predictions update at tick frequency. Speed: sim tick-advances at 90:1.
+
+## 10. Open items
+- CEX order book data access (API limitations, costs).
+- DEX-specific microstructure (AMM pools don't have order books — translate pool state to
+  equivalent depth/spread).
+- Latency modeling (how fast can our traders actually reach an arb?).
+- Almgren-Chriss extensions for crypto (volume-dependent variant? discrete block propagation?).
+- Which venues to model initially.

core/docs/plans/M4-wallets.md

@@ -0,0 +1,74 @@
+# M4 — Wallets (sovereign custody)
+
+## 1. Component
+The economy organ's vault: **sovereign, local-hosted, our-custody-only cryptocurrency wallets**.
+Each wallet binds to exactly one Trader (M5) — a trader without a wallet cannot access the
+Marketplace (M1). Wallets hold keys, sign transactions, and enforce wallet-level spending limits.
+Tax is collected on trader income and routed to the Verschwörern Veregeister wallets (stub — M0).
+
+## 2. Status / certainty
+DESIGN-FIRST · ABSENT. Role C4 (sovereign custody is a hard requirement); implementation C1.
+
+## 3. Language & location
+TBD · `src/economy/wallets/`. Needs cryptographic key management (secp256k1 for EVM, ed25519 for
+Solana, etc.), HD derivation, and transaction signing. Rust or Go for crypto primitives; Python
+with web3 libs for prototyping.
+
+## 4. Does / does-not
+- **Does:** generate and store private keys locally (never transmitted); sign transactions on
+  behalf of the bound trader; enforce per-wallet spending limits (daily, per-transaction);
+  track wallet balance and transaction history; collect tax on realized income and stage for
+  transfer to Verschwörern Veregeister wallets; bind 1:1 to a Trader (M5).
+- **Does-not:** decide what to trade (Trader decides); route to chain (Marketplace does);
+  hold keys for the organism's other wallets (Verschwörern Veregeister are separate); delegate
+  custody to any third party — ever.
+
+## 5. Interface contract
+- `create_wallet(chain: Chain, trader_id) -> wallet_id` — generates keys, binds to trader.
+- `sign(wallet_id, tx: UnsignedTransaction) -> SignedTransaction` — signs with the wallet's key.
+  Only the bound trader (via Marketplace) can request signing.
+- `balance(wallet_id) -> { chain, assets: [{ token, amount }] }`.
+- `spending_check(wallet_id, amount) -> { allowed:bool, remaining_daily:num }`.
+- `tax_collect(wallet_id, income_amount) -> { tax_amount, receipt }` — computes and stages tax.
+- `transfer_tax_stub(source_wallet, dest_wallet, amount) -> receipt` — **STUB** for future
+  Verschwörern Veregeister internal transfer. Logs only; does not execute.
+- `Chain` ∈ { `evm`, `solana`, `bitcoin`, … } — extensible.
+
+## 6. Dependencies & stubs
+- M5 Traders — 1:1 binding; *stub:* canned trader ID.
+- M1 Marketplace — signing requests come through marketplace only; *stub:* direct sign call.
+- Blockchain nodes — balance queries and tx broadcast; *stub:* simulated chain state.
+- Verschwörern Veregeister wallets — tax destination; *stub:* log transfer.
+
+## 7. Invariants / laws
+- **L1 (C5):** **sovereign custody only** — private keys are generated locally, stored locally,
+  and **never leave the wallet**. No custodial service, no exchange deposit, no MPC with external
+  parties. Our keys, our coins.
+- **L2 (C5):** **1:1 trader binding** — each wallet is bound to exactly one trader. A trader
+  cannot use another trader's wallet. The Marketplace enforces this.
+- **L3 (C4):** **signing requires Marketplace routing** — a wallet will not sign a transaction
+  that didn't come through the Marketplace harness (M1-L1). No direct signing API for traders.
+- **L4 (C4):** **spending limits are wallet-level** — independent of Conductor or Marketplace
+  limits. Defense in depth: even if other controls fail, the wallet itself caps exposure.
+- **L5 (C4):** **tax collection is automatic** — realized income triggers tax staging. The trader
+  cannot opt out.
+
+## 8. Build steps
+1. Implement key generation and secure local storage (encrypted keystore).
+2. Implement transaction signing for one chain (start with EVM/secp256k1).
+3. Implement trader binding and Marketplace-only signing enforcement.
+4. Implement spending limits (daily cap, per-tx cap).
+5. Implement tax calculation and staging stub.
+
+## 9. Tests
+Custody: private key never appears in any API response or log. Binding: wrong trader cannot
+sign. Marketplace-only: direct sign request (not via Marketplace) rejected. Spending limit:
+over-limit transaction rejected. Tax: income event triggers correct tax amount. Multi-chain:
+EVM and one other chain produce valid signatures.
+
+## 10. Open items
+- Key storage format (encrypted JSON keystore? OS keyring? HSM for production?).
+- Which chains to support initially.
+- Spending limit configuration (hardcoded? per-trader? adjustable by Conductor?).
+- Tax rate and calculation method.
+- Key rotation / backup strategy.

core/docs/plans/M5-traders.md

@@ -0,0 +1,78 @@
+# M5 — Traders (AI actors)
+
+## 1. Component
+The economy organ's hands: **specialized AI actors** that buy, sell, and mint cryptocurrency and
+NFTs. Each trader is bound to a Wallet (M4), operates through the Marketplace (M1), queries Sims
+(M3) for predictions, and has all tool calls monitored by the SAE (M7). Multiple traders may
+operate concurrently with **different specializations** (DeFi yield, NFT minting, arbitrage,
+long-term holding, etc.).
+
+## 2. Status / certainty
+DESIGN-FIRST · ABSENT. Role C3; implementation C1.
+
+## 3. Language & location
+TBD · `src/economy/traders/`. Each trader is an AI actor — likely LLM-based (small models for
+speed) or hybrid (LLM for strategy + deterministic execution logic). The harness managing
+multiple traders may be Pony actors or a Python async framework.
+
+## 4. Does / does-not
+- **Does:** query Sims (M3) for market predictions (bounded, multi-domain); consume Data Feeds
+  (M2) for real-time market state; formulate trade decisions based on predictions + data +
+  specialization; submit `MarketAction` requests to the Marketplace (M1) via bound wallet (M4);
+  operate with **scoped autonomy** — trades within law/budget constraints don't need Brain or
+  Conductor approval.
+- **Does-not:** execute on-chain directly (Marketplace does); hold keys (Wallet does); supervise
+  other traders (Conductor does); modify the law script (immutable — M1-L2); bypass the
+  Marketplace (M1-L1).
+
+## 5. Interface contract
+- `init_trader(specialization, wallet_id, config) -> trader_id`.
+  `specialization` ∈ { `defi_yield`, `nft_minter`, `arbitrageur`, `trend_follower`,
+  `market_maker`, … } — extensible.
+- `decide(market_state, predictions: [BoundedPrediction]) -> MarketAction?` — the trader's core
+  loop. May return no action (waiting is a valid decision).
+- `tool_call(tool_name, args) -> result` — every tool call is intercepted and logged to SAE (M7)
+  before execution. Includes Marketplace submissions, Sim queries, and Data Feed reads.
+- `pause() / resume()` — Conductor (M6) can pause a trader pending investigation.
+- `status() -> { active | paused | investigating, wallet_id, specialization, position_summary }`.
+
+## 6. Dependencies & stubs
+- M1 Marketplace — action submission; *stub:* mock marketplace that logs actions.
+- M2 Data Feeds — market data; *stub:* canned data.
+- M3 Sims — predictions; *stub:* fixed predictions.
+- M4 Wallet — bound 1:1; *stub:* mock wallet.
+- M6 Conductor — supervision; *stub:* no supervision.
+- M7 SAE — monitors all tool calls; *stub:* print calls.
+
+## 7. Invariants / laws
+- **L1 (C5):** **all market actions go through the Marketplace** — a trader cannot interact with
+  any chain or protocol except via `MarketAction` → Marketplace (M1). Enforced by architecture
+  (no direct RPC access), not just policy.
+- **L2 (C5):** **all tool calls are monitored** — every tool invocation (Marketplace, Sims,
+  Feeds, internal) is logged to SAE (M7). No unmonitored trader action.
+- **L3 (C4):** **wallet binding is irrevocable within a session** — a trader's wallet cannot be
+  reassigned to another trader at runtime.
+- **L4 (C4):** **Conductor can pause** — a paused trader cannot submit actions, query sims, or
+  read feeds until resumed by the Conductor (M6).
+- **L5 (C3):** trader specialization constrains strategy but not the interface — all traders use
+  the same `MarketAction` vocabulary regardless of specialization.
+
+## 8. Build steps
+1. Define the trader agent architecture (LLM-based? hybrid? rule-based for v1?).
+2. Implement the `decide` loop (observe market state + predictions → action).
+3. Wire tool-call interception → M7 SAE.
+4. Wire Marketplace submission → M1.
+5. Implement pause/resume for Conductor control.
+6. Build at least two specializations to test multi-trader dynamics.
+
+## 9. Tests
+Marketplace-only: trader cannot call chain RPC directly. Monitoring: every tool call appears in
+SAE log. Wallet binding: trader uses only its bound wallet. Pause: paused trader cannot submit
+actions. Specialization: different specializations produce different action patterns on identical
+market state.
+
+## 10. Open items
+- Trader agent architecture (which LLM? how much deterministic logic vs. model inference?).
+- Number of concurrent traders and resource allocation per trader.
+- Specialization catalog (which types, and how do they differ in strategy?).
+- Inter-trader coordination (do traders see each other's positions? shared state? isolated?).

core/docs/plans/M6-conductor.md

@@ -0,0 +1,79 @@
+# M6 — Conductor (supervisory AI)
+
+## 1. Component
+The economy organ's supervisor: a **specialist-trained AI** with authority to **veto Marketplace
+actions and pause/investigate individual Traders**. Receives suspicious-behavior reports from the
+SAE (M7) and acts on them. The Conductor is the stomach's own judgment — it does not consult the
+organism's Brain for trade-level decisions. It supervises; the deterministic law script (M1)
+constrains; together they form the multi-layered braking system.
+
+## 2. Status / certainty
+DESIGN-FIRST · ABSENT. Role C4 (supervision architecture is clear); implementation C1 (model
+selection, training, authority scope).
+
+## 3. Language & location
+TBD · `src/economy/conductor/`. The Conductor is an AI actor — likely a fine-tuned LLM with
+specialist training in market risk, trader behavior analysis, and anomaly response. The
+inference wrapper sits alongside the Marketplace.
+
+## 4. Does / does-not
+- **Does:** receive SAE (M7) anomaly reports on trader behavior; **pause** a flagged trader's
+  actions to investigate; **veto** a Marketplace action if investigation reveals risk; **resume**
+  a cleared trader; review Marketplace actions pre-execution when the law check passes (M1-L4:
+  veto is checked after law, before execution); maintain an audit log of all veto/pause/resume
+  decisions.
+- **Does-not:** trade (Traders do); execute on-chain (Marketplace does); modify the law script
+  (immutable — M1-L2); detect anomalies directly (SAE does — the Conductor *responds* to SAE
+  reports, it doesn't watch raw data); consult the organism's Brain.
+
+## 5. Interface contract
+- `veto_check(action: MarketAction, trader_id) -> { approved | vetoed(reason) }` — called by
+  Marketplace (M1) for every law-passing action before execution.
+- `receive_alert(alert: SAEAlert) -> { pause(trader_id) | dismiss | escalate }`.
+  `SAEAlert { trader_id, alert_type, evidence, severity, timestamp }`.
+- `investigate(trader_id) -> { clear(resume) | veto_pending_actions | restrict(new_limits) }`.
+- `decision_log() -> [ConductorDecision]` — full audit trail of all veto/pause/resume/dismiss.
+- **SAE/Brain message format compatibility:** the Conductor's incoming alert format is
+  **identical in structure and signature** to Brain messages — SAE reports to the Conductor in
+  the same shape it would report to the Brain. This means the Conductor can be swapped for Brain
+  oversight without protocol changes (though the stomach normally operates autonomously).
+
+## 6. Dependencies & stubs
+- M7 SAE — anomaly reports; *stub:* no alerts (all clear).
+- M1 Marketplace — veto check integration; *stub:* always-approve.
+- M5 Traders — pause/resume control; *stub:* print pause/resume.
+
+## 7. Invariants / laws
+- **L1 (C5):** the Conductor **can veto, but cannot trade** — it has no wallet, no Marketplace
+  access as a trader. It supervises from outside the trading loop.
+- **L2 (C5):** the **law script is above the Conductor** — the Conductor vetoes actions that
+  *pass* the law check but seem strategically risky. It cannot override a law violation (those
+  are rejected before reaching the Conductor — M1-L4).
+- **L3 (C4):** **pause is reversible** — a paused trader can always be resumed after
+  investigation. Pause is a breaker, not a sentence (echoes A2-L3).
+- **L4 (C4):** every Conductor decision is **logged** — vetoes, pauses, resumes, dismissals.
+  The audit log is append-only (echoes M1-L2 / S3).
+- **L5 (C4):** SAE alert format and Brain message format are **structurally identical** — same
+  fields, same signatures. The Conductor processes them the same way the Brain would.
+
+## 8. Build steps
+1. Define the Conductor's decision model (rule-based for v1? fine-tuned LLM for v2?).
+2. Wire SAE alert intake (M7 → M6).
+3. Wire Marketplace veto check (M1 → M6 → approve/veto).
+4. Implement trader pause/investigate/resume flow.
+5. Implement append-only decision log.
+
+## 9. Tests
+Veto: flagged action is vetoed; unflagged action approved. Pause: paused trader cannot submit
+actions. Resume: cleared trader resumes normal operation. No trading: Conductor cannot submit
+`MarketAction`. Law supremacy: Conductor cannot override a law violation (never reaches
+Conductor). Audit: every decision appears in the log. Alert format: SAE alert parses identically
+to Brain message structure.
+
+## 10. Open items
+- Conductor AI model selection and training data (what does "specialist training" look like?).
+- Veto criteria beyond SAE alerts (does the Conductor have independent judgment, or only
+  responds to SAE reports?).
+- Escalation path — if the Conductor is uncertain, does it escalate to the organism's Brain?
+  Or is the stomach fully autonomous? (Current design: fully autonomous.)
+- Multiple Conductors for redundancy?

core/docs/plans/M7-sae-monitor.md

@@ -0,0 +1,83 @@
+# M7 — SAE monitor (trader surveillance)
+
+## 1. Component
+The economy organ's internal watchdog: a **sparse autoencoder pointed at every trader tool call**.
+Monitors all Trader (M5) actions — Marketplace submissions, Sim queries, Data Feed reads, and
+any other tool invocation — and reports **suspicious behavior** to the Conductor (M6). Messages
+from the SAE share **identical format and signatures** with Brain messages, so the Conductor
+processes them through the same pathway.
+
+Extends the F2 (SAE monitor) pattern to the economy organ's internal domain. F2 watches
+subagents at the organism level; M7 watches traders at the stomach level.
+
+## 2. Status / certainty
+DESIGN-FIRST · ABSENT. F2 SAE monitor provides the architectural pattern (watch the machinery,
+never the homunculus — F2-L1). M7 adapts this: watch the **traders** (the machinery), never the
+**Conductor** (the stomach's judgment). Role C3; implementation C1.
+
+## 3. Language & location
+TBD · `src/economy/sae/`. ML interpretability (sparse autoencoder over trader action embeddings).
+Shares the architectural pattern with F2 but is a separate instance scoped to the economy organ.
+
+## 4. Does / does-not
+- **Does:** intercept and log **every trader tool call** (Marketplace, Sims, Feeds, internal);
+  embed trader action sequences; run SAE anomaly detection over action embeddings; flag suspicious
+  patterns (unusual trading frequency, outsized positions, coordinated behavior across traders,
+  repeated failed actions, unusual Sim query patterns); report alerts to the Conductor (M6) with
+  evidence; format alerts **identically to Brain messages** (same structure, same signatures).
+- **Does-not:** block actions directly (Conductor decides); watch the Conductor (the stomach's
+  "homunculus" — echoes F2-L1); correct trader behavior (detection only — F2-L2: no closed
+  elimination loop); trade or access wallets.
+
+## 5. Interface contract
+- `log_tool_call(trader_id, tool_name, args, result, timestamp)` — called on every trader tool
+  invocation. Synchronous interception (the call is logged before execution proceeds).
+- `alert(trader_id, alert_type, evidence, severity) -> SAEAlert`.
+  `alert_type` ∈ { `unusual_frequency`, `outsized_position`, `coordinated_behavior`,
+  `repeated_failures`, `anomalous_queries`, `pattern_deviation` }.
+  `severity` ∈ { `low`, `medium`, `high`, `critical` }.
+- `SAEAlert` structure is **identical to Brain message structure** — same fields, same
+  signature scheme. The Conductor (M6) processes SAE alerts and Brain messages through the
+  same intake (M6-L5).
+- `status() -> { active, traders_monitored, alerts_pending, model_freshness }`.
+
+## 6. Dependencies & stubs
+- M5 Traders — tool call source; *stub:* canned tool call log.
+- M6 Conductor — alert consumer; *stub:* print alerts.
+- F2 SAE monitor (organism-level) — architectural pattern; no runtime dependency.
+
+## 7. Invariants / laws
+- **L1 (C5):** the SAE watches **traders, never the Conductor** — the Conductor is the
+  stomach's judgment; the SAE monitors the machinery. Echoes F2-L1 (watch the machinery, never
+  the homunculus).
+- **L2 (C5):** **every tool call is logged** — no trader action escapes monitoring. This is
+  enforced architecturally (tool call interception), not by policy.
+- **L3 (C4):** **detection only, no enforcement** — the SAE reports to the Conductor; it never
+  blocks, pauses, or modifies trader actions itself. Echoes F2-L2 (no closed elimination loop).
+- **L4 (C4):** **alert format = Brain message format** — structurally identical, same signatures.
+  This is not coincidental; it ensures the Conductor can be supervised by the Brain using the
+  same protocol if the organism ever needs to override stomach autonomy.
+- **L5 (C3):** the SAE model is **trained on normal trader behavior** — anomalies are deviations
+  from the learned normal, not violations of predefined rules (those are the law script's job
+  in M1).
+
+## 8. Build steps
+1. Implement tool-call interception in the trader harness (M5).
+2. Define the action embedding scheme (how tool calls are vectorized).
+3. Train the SAE on normal trader behavior (bootstrapped from simulated trading).
+4. Implement anomaly scoring and alert threshold.
+5. Wire alerts to Conductor (M6) in Brain-compatible message format.
+
+## 9. Tests
+Interception: every tool call produces a log entry. Anomaly: known-suspicious patterns (e.g.
+100x normal frequency) trigger alert. Normal: baseline behavior does not trigger alert.
+No enforcement: SAE cannot pause or block a trader (only Conductor can). Alert format: SAE
+alert parses as valid Brain message. Conductor-blind: no Conductor action appears in SAE logs.
+
+## 10. Open items
+- SAE architecture (how many features? reconstruction vs. classification?).
+- Training data bootstrapping (simulated trading or historical data?).
+- Alert threshold tuning (too sensitive = alert fatigue; too lax = missed anomalies).
+- Whether M7 should also monitor Marketplace execution outcomes (fills, slippage) in addition
+  to tool calls.
+- Relationship to F2: shared model? shared training pipeline? or fully independent?

core/docs/plans/README.md

@@ -49,6 +49,21 @@ Every `NN-<organ>.md` has the same 10 sections:
 | G1 | Stress-loop contract | Cross-cut | C1/C2 | — | _wave 2_ |
 | G2 | Governance | Cross-cut | DESIGN-FIRST (C2) | TBD | _wave 2_ |
 | G3 | Defense model | Cross-cut | emergent | — | _wave 2_ |
+| M0 | Economy organ hub (stomach) | Economy | DESIGN-FIRST | TBD | [M0](M0-economy-organ-hub.md) |
+| M1 | Marketplace (multi-trader harness) | Economy | DESIGN-FIRST | TBD | [M1](M1-marketplace.md) |
+| M2 | Data feeds (market data pipeline) | Economy | DESIGN-FIRST | TBD | [M2](M2-data-feeds.md) |
+| M3 | Sims hub (market prediction) | Economy | DESIGN-FIRST | TBD | [M3](M3-sims-hub.md) |
+| M3a | Statistical & quantitative sims | Economy/Sims | DESIGN-FIRST | TBD | [M3a](M3a-statistical-sims.md) |
+| M3b | Sociological & population sims | Economy/Sims | DESIGN-FIRST | TBD | [M3b](M3b-sociological-sims.md) |
+| M3c | AMM & liquidity pool sims | Economy/Sims | DESIGN-FIRST | TBD | [M3c](M3c-amm-liquidity-sims.md) |
+| M3d | MEV & adversarial extraction sims | Economy/Sims | DESIGN-FIRST | TBD | [M3d](M3d-mev-adversarial-sims.md) |
+| M3e | Tokenomics & macro-state sims | Economy/Sims | DESIGN-FIRST | TBD | [M3e](M3e-tokenomics-macro-sims.md) |
+| M3f | Consensus & staking game sims | Economy/Sims | DESIGN-FIRST | TBD | [M3f](M3f-consensus-staking-sims.md) |
+| M3g | Market microstructure sims | Economy/Sims | DESIGN-FIRST | TBD | [M3g](M3g-market-microstructure-sims.md) |
+| M4 | Wallets (sovereign custody) | Economy | DESIGN-FIRST | TBD | [M4](M4-wallets.md) |
+| M5 | Traders (AI actors) | Economy | DESIGN-FIRST | TBD | [M5](M5-traders.md) |
+| M6 | Conductor (supervisory AI) | Economy | DESIGN-FIRST | TBD | [M6](M6-conductor.md) |
+| M7 | SAE monitor (trader surveillance) | Economy | DESIGN-FIRST | TBD | [M7](M7-sae-monitor.md) |
 
 ## Integration DAG (who feeds whom)
 ```
@@ -62,10 +77,15 @@ Hermes ──> [C1] ──> Inference cycle [C3] ──┬─ pulls Drive-Box sn
                                             └─ Ada routes tools [D1]
 SAE [F2] watches Subagents [F3];  stress-loop [G1]: F2 → A7 (EthInt) → stress endomotiv (A4) → A8 drift + full reshuffle (B2)
 Storage: INVARIANT [E1] / VARIANT [E2] / RAG+cross-store [E3] sit behind D1.  Medium [D2] = the perfusion bus (unnamed).
+Economy (stomach — independent, scoped autonomy):
+  Marketplace [M1] ← Traders [M5] (bound to Wallets [M4]) submit actions; law script + Conductor [M6] veto gate execution.
+  Data Feeds [M2] ↔ Sims [M3: M3a stat, M3b socio, M3c AMM, M3d MEV, M3e tokenomics, M3f consensus, M3g microstructure].
+  SAE [M7] monitors all Trader tool calls → alerts Conductor [M6].  Tax → Verschwörern Veregeister wallets (stub).
+  Stomach [M0] ↔ organism via Ichor; reward signals TBD.
 ```
 
 ## Build waves
 - **Wave 0** — this README + **C1** (priority).
 - **Wave 1 (buildable-now)** — A1–A8, B1–B3, C2–C4, D1, D3.
-- **Wave 2 (design-first)** — D2, E1–E3, F1–F3, G1–G3.
+- **Wave 2 (design-first)** — D2, E1–E3, F1–F3, G1–G3, M0–M7 (+ M3a–M3g sim sub-specs).
 Each spec is independent; review as they land.

core/src/endocrine/AGENTS.md

@@ -1,7 +1,7 @@
 # AGENTS.md — endocrine organs (R / Octave)
 
 Local guide for `src/endocrine`. Repo-wide map and rules: [`../../AGENTS.md`](../../AGENTS.md);
-working agreements: [`../../CLAUDE.md`](../../CLAUDE.md).
+working agreements: [`../../CLAUDE.md`](../../CLAUDE.md). Correction log: [`../../../.claude/devCorrectionLog.md`](../../../.claude/devCorrectionLog.md).
 
 ## What this is
 

core/src/ichor/AGENTS.md

@@ -1,7 +1,7 @@
 # AGENTS.md — Ichor bus (Pony)
 
 Local guide for `src/ichor`. Repo-wide map and rules: [`../../AGENTS.md`](../../AGENTS.md);
-working agreements: [`../../CLAUDE.md`](../../CLAUDE.md).
+working agreements: [`../../CLAUDE.md`](../../CLAUDE.md). Correction log: [`../../../.claude/devCorrectionLog.md`](../../../.claude/devCorrectionLog.md).
 
 ## What this is