Skip to content

getting-started.md

Latest commit

 

History

History
106 lines (73 loc) · 3.39 KB

getting-started.md

File metadata and controls

106 lines (73 loc) · 3.39 KB
Raw

Getting Started

This guide takes you from zero to your first passing simulation.

Prerequisites

  • Rust 1.90 or newer. The repo pins 1.97 via rust-toolchain.toml.
  • cargo on your PATH.
  • A clone of the ldgr repository.

Build

git clone https://github.com/ldgr-rs/ldgr && cd ldgr
cargo build -p ledger-cli

The binary is named ledger. You can also install it to your cargo bin:

cargo install --path crates/ledger-cli

Check it works:

cargo run -p ledger-cli -- --help
# or, if installed:
ledger --help

You should see the ledger help text and the list of subcommands.

Run your first campaign

Run a short deterministic campaign with an explicit seed:

cargo run -p ledger-cli -- sim --seed 42 --runs 10

What happens:

  • ldgr runs the built-in mini key-value workload 10 times.
  • Each run uses a different schedule derived from the seed.
  • Each run journals effects and checks the oracle.

On first run you will likely see a violation (the built-in workload is intentionally buggy for the demo):

Violation detected: read of k returned 100, expected 42
Journal root: eaddfb60... (64 hex chars)
Steps executed: 10

A passing run looks like Simulation passed (10 runs evaluated, zero violations). With the same build, configuration, seed, and inputs, the output is deterministic. JSON violation records include steps and journal_root. NDJSON emits those fields for every attempt; a passing whole-campaign JSON result contains only status and runs.

See a violation

Some seeds and workloads produce violations. A violation looks like this:

Violation detected: read of k returned 100, expected 42
Journal root: a1b2c3... (64 hex chars)
Steps executed: 42
  • Violation detected is the oracle reason.
  • Journal root is the hash of the causal DAG for that run. The same build, configuration, seed, and inputs give the same root, byte for byte.
  • Steps executed is how many simulated instructions ran before the check.

The in-memory finding carries the seed and decisions that produced the violation. The current CLI repro path reruns a configured seed and verifies its replay internally. See Replay and Minimize.

What to do next

Common flags you will use soon

All sim-family commands accept these:

ledger sim --seed 42 --runs 100 --max-steps 256 --policy bandit
  • --seed sets the root seed.
  • --runs sets how many attempts to run.
  • --max-steps caps instructions per run.
  • --policy picks the scheduler: random, bandit, pct, replay.

Global flags work on every command:

ledger --deadline-ms 5000 sim --seed 42 --runs 100
ledger --json sim --seed 42 --runs 10
ledger -v sim --seed 42 --runs 10
  • --deadline-ms exits with code 2 if the whole command exceeds that wall-clock budget.
  • --json and --ndjson switch to machine-readable output.
  • -v / -q control verbosity.

Exit codes: 0 the command completed (a campaign that found a violation also exits 0 - check the output), 1 the command failed, 2 deadline exceeded. See FAQ and CLI Reference.