A what-if engine for conflict simulation. Users supply scenario configurations — factions, force compositions, institutional loyalties, political climates, technology modifiers, geographic constraints — and the engine simulates the logical consequences across many runs, producing probability distributions of outcomes.
Faultline is not a predictive model. It is a tool for exploring the consequence space of user-defined assumptions.
Primary interface: WASM app hosted on GitHub Pages (interactive scenario editor + visualization). Secondary interface: Headless CLI for batch Monte Carlo evaluation (JSON/CSV output).
Prerequisites: Rust toolchain (edition 2024) or Docker (v20.10+)
git clone https://github.com/AndrewAltimit/faultline
cd faultline
# Run directly (requires local Rust toolchain)
cargo test
cargo build --release
# Run a single simulation
cargo run -p faultline-cli -- scenarios/tutorial_symmetric.toml --single-run
# Run 1000 Monte Carlo simulations
cargo run -p faultline-cli -- scenarios/tutorial_symmetric.toml -n 1000
# Counterfactual: re-run with a parameter overridden, get a delta report
cargo run -p faultline-cli -- scenarios/persistent_covert_surveillance.toml -n 1000 \
--counterfactual "kill_chain.covsurv.phase.covsurv_dwell.detection_probability_per_tick=0.05"
# Side-by-side: run two scenarios with the same seed and report deltas
cargo run -p faultline-cli -- scenarios/tutorial_symmetric.toml -n 1000 \
--compare scenarios/tutorial_asymmetric.toml
# Or run CI pipeline in Docker (matches GitHub Actions exactly)
docker compose --profile ci run --rm rust-ci cargo fmt --all -- --check
docker compose --profile ci run --rm rust-ci cargo clippy --all-targets -- -D warnings
docker compose --profile ci run --rm rust-ci cargo test
docker compose --profile ci run --rm rust-ci cargo build --release
docker compose --profile ci run --rm rust-ci cargo deny checkCI pipeline order: fmt → clippy → test → build → cargo-deny → grep-guard → verify-bundled → verify-migration → verify-robustness → js-tests. See docs/testing-and-ci.md for what each stage does.
faultline-types (shared data structures — no logic, no deps)
|
+-- faultline-geo (geography, maps, terrain)
+-- faultline-tech (technology capability cards)
+-- faultline-politics(political climate, loyalty, defection)
+-- faultline-events (event triggers, effects, chains)
|
+-- faultline-engine (core simulation loop — depends on all above)
|
+-- faultline-stats (Monte Carlo runner, statistics)
+-- faultline-backend-wasm (browser WASM frontend)
+-- faultline-cli (headless batch runner)
| Crate | Purpose |
|---|---|
faultline-types |
Shared data structures (Scenario, Faction, TechCard, etc.) |
faultline-geo |
Map loading, terrain modifiers, adjacency graph |
faultline-tech |
Technology card effect resolution with terrain modifiers |
faultline-politics |
Political climate, institutional loyalty, civilian activation |
faultline-events |
Conditional event triggers, effect application, event chains |
faultline-engine |
Deterministic tick loop: events, AI, movement, combat, politics |
faultline-stats |
Monte Carlo runner, win probabilities, distribution stats |
faultline-backend-wasm |
WASM API (load, validate, explain, run scenarios from browser) |
faultline-cli |
Headless CLI with rayon parallelism for batch runs |
- AGENTS.md — canonical project guide (build, code style, architecture, data policy, CI) with a map of the docs below.
- docs/cli.md — full CLI reference: every flag, run mode, and bundled-archetype demo.
- docs/engine-model.md — the per-tick simulation model and engine mechanics.
- docs/analytics.md — Monte Carlo report sections, search/robustness/co-evolution, calibration.
- docs/scenario_schema.md — the scenario TOML schema reference.
- docs/testing-and-ci.md — test suites and the CI pipeline.
- Config-as-input. Scenarios are declarative TOML files — shareable, forkable, diffable.
- Monte Carlo first. Single runs tell stories. Thousands of runs give distributions.
- Technology as capability cards. Named bundles of statistical effects, not simulated hardware.
- Deterministic. Same config + same seed = identical output on native and WASM.
Faultline is an analytical research tool. All scenario data is derived from publicly available open-source intelligence (OSINT). The software models aggregate statistical effects of military systems — it does not implement, simulate, or contain any controlled defense technology, classified information, or export-restricted algorithms. See LEGAL.md for full details.
OpenAI/Google integrations are disabled within PR reviews. OpenAI/Google permits government partners unrestricted use of their models. We only allow models with explicit prohibitions on mass surveillance and autonomous weapons.
| Repository | Description |
|---|---|
| template-repo | Agent orchestration, MCP servers, CI/CD templates, security tooling |