Rulepath

A Rust-first, rule-enforcing, replayable, testable card/board-game platform. Rust owns all behavior; TypeScript/React only presents it.

Rulepath builds polished, public, browser-playable card and board games on a deterministic Rust engine. Every legal action, validation, effect, view, bot decision, and replay comes from Rust compiled to WebAssembly — the web shell renders what Rust says and never decides game legality itself. The result is a platform where games are replayable from a deterministic command log, testable end to end, and safe against hidden-information leaks by construction.

Status

Gates 0-14 complete; event-deck complexity capstone proof accepted — Rulepath now ships nineteen local-playable official games: Race to 21 (race_to_n), Three Marks (three_marks), Column Four (column_four), Directional Flip (directional_flip), Draughts Lite (draughts_lite), High Card Duel (high_card_duel), Token Bazaar (token_bazaar), and Veiled Draft (secret_draft), Crest Ledger (poker_lite), and Plain Tricks (plain_tricks), Masked Claims (masked_claims), and Flood Watch (flood_watch), Frontier Control (frontier_control), Event Frontier (event_frontier), River Ledger (river_ledger), Briar Circuit (briar_circuit), Vow Tide (vow_tide), and Blackglass Pact (blackglass_pact), Meldfall Ledger (meldfall_ledger), and Starbridge Crossing (starbridge_crossing). Gate 9 is complete with Token Bazaar as the accepted public resource/economy proof, Gate 9.1 adds the accepted simultaneous commitment/reveal proof, Gate 10 adds the accepted betting/showdown proof, and Gate 10.1 adds the accepted trick-taking proof, and Gate 11 adds the accepted claims/challenges/reaction-window hidden-information proof, and Gate 12 adds the accepted cooperative event-pressure proof, Gate 13 adds the accepted asymmetric graph-map area-control proof, and Gate 14 adds the accepted event-deck complexity capstone proof. blackjack_lite is deferred by ADR 0006 and does not block later gates. See specs/README.md for the live gate-by-gate progress tracker and docs/ROADMAP.md for the full staged ladder.

Play it locally

Prerequisites

• A stable Rust toolchain with the WebAssembly target:

  rustup target add wasm32-unknown-unknown

• Node.js 20.19+ (or 22.12+) and npm.

Run the web shell

npm --prefix apps/web install
npm --prefix apps/web run build
npm --prefix apps/web run preview

Then open http://127.0.0.1:4173 and play. There is no backend, account, or database — match state lives entirely in the in-memory Rust/WASM store.

build first compiles crates/wasm-api to wasm32-unknown-unknown, copies the artifact into apps/web/public/, typechecks, and emits the static Vite bundle. preview serves that bundle. (There is no dev-server script — the app always runs against a real compiled WASM artifact.)

More detail on the shell, its smoke layers, and static serving lives in apps/web/README.md.

How it works

• Rust owns behavior. engine-core is a generic, noun-free contract kernel; typed game rules live in games/*; bots live in ai-core.
• WASM is the boundary. crates/wasm-api is a JSON bridge that hands the browser legal actions, views, effects, diagnostics, bot turns, and replay projections.
• TypeScript/React only presents. The shell renders Rust output and submits actions; it never validates moves or computes legality.
• Determinism is law. Replays, hashes, RNG, serialization order, and traces are deterministic unless explicitly migrated.

The authoritative rules are in docs/FOUNDATIONS.md (the constitution) and the ordered foundation set indexed by docs/README.md.

Develop & verify

Rust hygiene

cargo fmt --all --check
cargo clippy --workspace --all-targets -- -D warnings
cargo build --workspace
cargo test --workspace

Per-game checks (replace the game id as needed; current official games are race_to_n, three_marks, column_four, directional_flip, draughts_lite, high_card_duel, token_bazaar, secret_draft, poker_lite, plain_tricks, masked_claims, flood_watch, frontier_control, event_frontier, river_ledger, briar_circuit, vow_tide, blackglass_pact, meldfall_ledger, and starbridge_crossing)

cargo run -p simulate      -- --game race_to_n --games 1000
cargo run -p replay-check  -- --game race_to_n --all
cargo run -p fixture-check -- --game race_to_n
cargo run -p rule-coverage -- --game race_to_n
bash scripts/boundary-check.sh        # engine-core stays noun-free
node scripts/check-doc-links.mjs      # doc link integrity

Web checks

npm --prefix apps/web run smoke:wasm     # raw WASM ABI coverage
npm --prefix apps/web run smoke:ui       # Node/WASM shell-state smoke
npm --prefix apps/web run smoke:e2e      # built-bundle browser + no-leak smoke

The Puppeteer E2E smoke uses system Chrome at /usr/bin/google-chrome; set PUPPETEER_EXECUTABLE_PATH to override.

Workspace map

Path	What it is
crates/engine-core	Generic contract kernel (noun-free).
crates/game-stdlib	Earned shared helpers (via the mechanic atlas).
crates/ai-core	Bot infrastructure.
crates/wasm-api	Rust ↔ browser JSON bridge.
games/*	Typed Rust game modules (rules, traces, bots, docs).
tools/*	simulate, replay-check, fixture-check, rule-coverage, and more.
apps/web	TypeScript/React presentation shell.

Documentation

Document	Purpose
docs/README.md	Ordered index of the foundation doc set.
docs/FOUNDATIONS.md	The constitution: priority, invariants, stop conditions.
docs/ARCHITECTURE.md	Workspace shape and the Rust/WASM boundary.
docs/ROADMAP.md	Prescriptive staged ladder and build gates.
specs/README.md	Living per-gate progress tracker.
apps/web/README.md	Web shell commands, smoke layers, static serving.
CLAUDE.md / AGENTS.md	Coding-agent orientation and workflow.

License

GNU General Public License v3.0.