Weft reference

The complete user-facing surface: CLI commands and flags, exit codes, environment variables, the network-condition spec, the scenario DSL, the fuzz config, and the recording format. If behavior differs from this document, one of the two is a bug.

Compatibility policy for everything on this page: ../VERSIONING.md.

1. CLI

weft <COMMAND> [OPTIONS]

1.1 weft run

weft run --seed <N> [OPTIONS] -- <program> [args...]

Exit code: the target’s exit status passes through (single-process runs exec the target, so the status is the target’s). Cluster runs combine node statuses — 0 iff every node exited 0, otherwise a failing node’s status clamped to 1–255. Weft’s own failures print weft run: <message> and exit 1. Windowed runs exit 3 (discard) when the run is invalid rather than failed: a node crashed (killed by a signal, or its connection ended without the shim’s clean goodbye), the cluster deadlocked, a protocol violation was latched, or the --watchdog fired.

1.2 weft replay

weft replay <LOG> [--until <OP>] [--check <LIST>]

Exit codes: 0 replay identical and invariants hold · 2 invariant violation · 1 unreadable log / replay divergence.

On success prints replay identical: N op(s), stream digest %016x — the digest is deterministic and safe to compare across runs and machines.

1.3 weft fuzz

weft fuzz --config <FILE> [OPTIONS]

Exit codes (CI contract): 0 no violations · 2 violations found, reproducers + report written · 1 configuration or setup error.

1.4 Case-study checkers (chord-check, chord-trace, raft-check)

Standalone binaries from weft-chord / weft-raft; they scan a recording:

chord-check <recording.weftlog> <M>     # M = identifier bits (ring size 2^M)
chord-trace <recording.weftlog> <M>     # per-node pointer-state timeline
raft-check  <recording.weftlog>

Exit codes (shared contract): 0 invariant holds · 2 VIOLATION · 3 DISCARD · 1 unreadable recording. The meaning of DISCARD differs: for raft-check the seed exercised nothing (no leader was ever elected — uninformative); for chord-check the scenario violated the papers’ failure precondition (a failure stranded some node with no live successor), so the run cannot count against Chord.

2. Environment variables

All canonical names live in crates/weft-abi/src/lib.rs. weft run sets the starred ones for you; you only set them yourself when bypassing the CLI.

3. Network-condition spec (--net, WEFT_NET)

Comma-separated key=value clauses; all keys optional; empty spec = reliable network. Grammar implemented in crates/weft-net/src/config.rs.

Example: latency=uniform:1000-5000,loss=0.1,bw=2000000,partition=0+1|2

Every fate (delay, drop, order) is a pure function of (seed, src, dst, seq) — the same seed deals every message the same fate on every platform.

4. Scenario DSL (JSON)

Parsed and validated by weft-scenario (Scenario::from_json). Format is JSON only (YAML is not supported). Runnable examples: examples/scenarios/*.json.

{
  "name": "string (required)",
  "description": "string | null",
  "seed": 42,
  "nodes": [
    {"node_id": 0, "program": "./path", "args": ["--flag"]}
  ],
  "network": {
    "latency": "uniform:500-10000",
    "loss": 0.0,
    "bandwidth": null,
    "partitions": "0+1|2"
  },
  "filesystem": {
    "0": {"fsync_lies": true, "enospc_after_bytes": null, "torn_write_probability": 0.0}
  },
  "time_skew": { "0": 0 },
  "events": [
    {"time_ns": 1000000, "action": {"type": "crash", "node_id": 0}},
    {"time_ns": 2000000, "action": {"type": "start", "node_id": 0}},
    {"time_ns": 3000000, "action": {"type": "activate_partition", "spec": "0|1"}},
    {"time_ns": 4000000, "action": {"type": "clear_partition"}}
  ]
}

Validation rules (all violations produce a specific ScenarioError):

• nodes[*].node_id must be sequential from 0.
• events, filesystem, time_skew may only reference existing node ids.
• network.latency must parse per §3; loss and torn_write_probability must be in [0.0, 1.0]; bandwidth must be > 0 if present.
• partitions must match the 0+1|2 grammar; empty string clears.
• Events are sorted by time_ns during parsing.

Event actions: crash, start, activate_partition (takes spec), clear_partition.

5. Fuzz config (JSON)

Full semantics in fuzzing.md. Unknown fields are rejected (typos fail loudly), except the "//" comment slot.

6. Recording format (weft-log v2)

Full specification: recording-format.md. Essentials:

• Line-oriented JSON; line 1 is the header: {"format":"weft-log","version":2,"seed":…,"net":"…","window_ns":0,"meta":{…}}.
• Readers MUST reject unknown version values; v1 logs are rejected (their latency-only deliveries predate send-time anchoring). meta is informational only and MUST be ignored for replay purposes.
• Gzip is detected by content (magic bytes), never by file extension.
• The log records the broker linearization order and each send’s send_vt (the two non-seed inputs) — so seed + log reconstructs the run exactly; replay verifies a FNV-1a chain digest over every record.

7. Rust API (crates)

Published entry points a test harness is expected to use — everything else is implementation detail:

• weft_scenario::Scenario::from_json / ::validate, weft_scenario::parse_scenario, LatencyDistribution::parse, ScenarioError.
• weft_replay::Log::read, invariants (fifo, dup) via weft replay --check.
• weft_chord (report parsing + log-scanning verdict types) and weft_raft::{check, parse_report, Verdict} — models for writing your own recording checkers (scan log.records, parse your protocol’s state reports, accumulate a verdict; ~150 lines each).
• weft_abi::ENV_* constants — the canonical env-var names.