What (One-liner)

N agents each run the 4D ODE with w coupled toward the group mean → compute herding_index and flash_crash_score → events at score ≥ 70. Detects strategy homophily and flash-crash risk. Seed=42 hard-coded.

How to use

macro_snapshot_v1 → strategy_homophily_v1 (n_agents=20, coupling=0.05, shocks=[...])
                    → final_metrics {peak_herding, max_crash_score, total_flash_crash_events}
                    → flash_crash_events timeline

Core formulas

See frontmatter formula. Three key elements:

1. Seed=42 initialization: rng.normal gives each agent its initial state (agent_diversity controls w spread)
2. Coupling: coupling_strength × (mean_w − w_i) added to w after the RK4 step
3. Scoring: herding_score (40%) + collapse_score (35%) + level_score (25%) → min(100, sum)

Assumptions & applicability

Assumptions: seed=42 + synchronous shocks + coupling formula bound to the 4D ODE + pinned numpy.

Applies to: AI-agent herding stress tests (BoE / FSB framework alignment), Canvas cross-strategy herding observation, flash-crash counterfactuals.

Does not apply to: live trading, single-agent studies, non-reflexivity dynamics, requests beyond the caps.

Known limitations

See frontmatter limitations. Seven key items: hard-coded seed / caps / synchronous shocks / no coupling damping / fixed x/y/z dispersion / fixed scoring weights / rounding locked.

References

• Soros (1987) Alchemy of Finance — reflexivity
• FSB (2024-11) AI Financial Stability Report — herding stress-test framework
• BoE (2025-04) FS in Focus: AI — regulator stress-test requirements

Golden Test

tests/golden/fixtures/tier4/strategy_homophily/ — captured_snapshot (seed=42 deterministic), 1e-8 tolerance. 11 tests:

5 Scenarios

• canvas_defaults / small_tight_group / large_loose_group / with_shock_crash / custom_ode_params

6 Contract tests

• result_structure (top-level + per-step metrics key set)
• determinism (3 reruns byte-identical)
• n_agents_cap (500 → clamps to 200)
• n_steps_cap (1000 → clamps to 500)
• flash_crash_threshold (events set = trajectory steps with score ≥ 70)
• final_metrics_roll_up (max_crash_score = max(events) or 0.0)

Changelog

• 1.0.0 (2026-04-21) — First Active (Tier 4 batch 2.2)