chore: sync submodule state (parent ref update)

Made-with: Cursor

spec/13-minimal-router-sim.md

@@ -0,0 +1,54 @@
+# Minimal Router Simulator Architecture
+
+Lightweight simulator to make routing/DeFi effects on single-sided PMM **measurable** before building an on-chain-accurate engine. No exact DODO math required; need **routing selection + flow splitting + inventory updates**.
+
+---
+
+## 1. Build supergraph
+
+- **Nodes:** `(chain, token)` from scenario `chainsIncluded` × `tokensIncluded` plus anchor stables per chain.
+- **Edges:**
+  - **PMM edges:** from `deployment-status.json` (deployed) or from design + `simulation-params.json` (design). One edge per pool `(c, T) ↔ (c, Q)`.
+  - **AMM “background”:** anchor stable conversions (e.g. USDC↔USDT) — model as deep constant-product or fixed spread so PMM is not the only path.
+  - **Bridge edges:** (c_i, cW*) → (c_j, cW*) with cost `y = x(1−β) − γ − ρ(Δt)·x` (β, γ, ρ from scenario latencyModel / params).
+
+---
+
+## 2. Epoch loop
+
+For each epoch:
+
+1. **Sample N trades** from `orderflowModel` (source chain, target chain, token, size).
+2. **Compute candidate paths** (e.g. k-shortest paths or enumerate swap+bridge combos).
+3. **Allocate flow** by marginal-equalization heuristic (waterfilling): split volume across paths so marginal output equalizes.
+4. **Update PMM inventories** and implied prices (use inventory-sensitive depth D = D_0·min(1, I_T/I_T^*)).
+5. **Arb step (optional):** agents that trade toward oracle when profitable; update inventories again.
+6. **Bot intervention step:** apply policy from config (or keep exogenous); record intervention cost.
+7. **Emit scorecard** (or accumulate for end-of-run scorecard).
+
+---
+
+## 3. What this shows immediately
+
+- **Inventory mining:** routers drain PMM until marginal rate worsens.
+- **Reflexive multi-hop:** route cycles through multiple PMM pools (count as `reflexive_route_count`).
+- **Full-quote vs hub churn:** compare churn_mean and churn_max across scenarios.
+
+AMM edges can be mocked (e.g. fixed 5 bps spread); relative behavior of PMM vs alternatives is still correct.
+
+---
+
+## 4. Implementation status
+
+`scripts/run-scenario.cjs` implements the **real** pipeline (PR#1 + PR#2):
+
+- **Graph:** Nodes `(chainId, token)`; PMM edges from scenario + `simulation-params` + `pool-matrix` (hub + optional full-quote); AMM background edges (anchor↔anchor, fee-only); bridge edges wired (cost used for bot intervention; cross-chain routing optional later).
+- **PMM state:** Per-pool `I_T`, `D = D_0·min(1, I_T/I_T^*)`, sell/buy with documented formula; routing controls applied.
+- **Routing:** Candidate paths (same-chain, length ≤3), top-K by cost; waterfilling by chunk (5%), marginal-equalization.
+- **Arb step (PR#2):** Implied price (sell/buy probe) vs oracle P; deviation δ; if |δ| > DELTA_ARB_BPS, trade in corrective direction with size min(x_max, α·|δ|·I_T^*); profit gate (skip if profit ≤ 0). Tuning: `DELTA_ARB_BPS`, `ARB_ALPHA`, `ARB_MAX_FRACTION_OF_TARGET`.
+- **Bot step (PR#2):** If I_T < 0.5·I_T^* inject; if I_T > 1.5·I_T^* withdraw; action clipped to `BOT_MAX_FRACTION_OF_TARGET`·I_T^*; intervention cost = |u|·(β+ρ)+γ (bridge params + latency ρ from scenario `latencyModel`).
+- **Bridge shock:** When `scenario.bridgeShock` is set, extra trades (sell cW on fromChain, buy cW on toChain) over `durationEpochs` at `magnitudeFraction` of baseline.
+- **Determinism:** RNG seeded from `scenario.seed` or hash of scenario name.
+- **Scorecard:** All PR#1 metrics plus `peak_deviation_bps`, `intervention_cost_*`, `arb_volume_total`, `arb_profit_total`.
+
+Tuning: see constants in script and [scripts/README.md](../scripts/README.md).