[hmdsefi]

The docs on main still describe v0.1.2 and say that goroutine, net and os code cannot run. This updates them for v0.2.0: goroutine mode, shims/netsim with its net/http helpers, the shims/grpcsim module, shims/fsx, and exact replay through the toolexec backend. AI coding agents stay the first audience.

New pages:

• docs/guides/goroutine-mode.md: an HTTP key-value store on p.Net and p.FS, crashed and restarted by a fault planner; what a crash does to a process; a gRPC health service with grpcsim; fsx.OS and fsx.Sim; the goroutine-mode options; stall and leak reports; limits.
• docs/guides/exact-replay.md: setting up faultline-toolexec, a failing seed under it, a test that becomes exact, what the wrapper rewrites, coverage gaps, Procs and FAULTLINE_EXACT, what stays outside the scheduler, the measured cost, CI steps.
• docs/reference/toolexec.md: the command, its state and variables, the rewrite set, every coverage gap kind, its error messages.

Changed pages: README, llms.txt, the docs index, ai-agents.md (a goroutine-mode section and rules in the instruction block), the FAQ, how-it-works.md (a goroutine-mode section, rules per mode), architecture.md (packages, diagram, the driver and the rewriter as design choices), the determinism, CI, replay and artifact guides, and the artifact, environment and CLI references (determinism_level, exact_backend, leaks, the leak kind, goroutine-mode options and record kinds, goroutines.txt, toolexec-gaps.txt, stall.txt). The doc comments of ModeGoroutine and the package now say that a toolexec build replays exactly.

The setup installs the wrapper and passes it by name, go test -toolexec=faultline-toolexec. The form in the wrapper's doc comment, -toolexec="go tool faultline-toolexec", fails with go: no such tool "faultline-toolexec": go test -x shows the go command running asm for standard-library packages with assembly files (sync/atomic, internal/cpu) in their GOROOT directory, outside the module. #584 fixes the doc comment.

The ai-agents.md sentence on the plugin's flaky-test answer describes the plugin of #586; both merge before the tag. An independent review of this change checked about 250 sentences against the code; its findings are applied (request ordering with equal keys, which file operations reach the trace, the Procs condition for exact replay, and wording).

How it was checked: every output block on the new pages comes from runs of this branch's code in a scratch module through replace, go1.27.1 on darwin/arm64:

• the store, plain and through the wrapper: seed 0x6e1023a46368738d fails the same final check, trace hash 0xe22ed0d233124725 in both, determinism: exact (toolexec backend) and a replay command with -toolexec=faultline-toolexec through the wrapper; the fixed store passes 100 seeds with -race and FAULTLINE_CHECK_DETERMINISM=1;
• a client drawing from global math/rand/v2: a determinism failure in the plain build, 5 of 5 seeds pass the check through the wrapper;
• a map with pointer keys: one coverage gap, toolexec-gaps.txt, and the toolexec determinism message;
• FAULTLINE_EXACT=1 without the wrapper: the setup error;
• the gRPC health test: 20 seeds pass with -race and the determinism check.

The cost numbers come from the backend's own measurements (Apple M4 Max, go1.27.3). tech-writing/lint.sh is clean on every page. The @v0.2.0 install commands resolve once the tags exist; this PR merges before the tag.

[coderabbitai]

Important

• Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

Run configuration

• Source mode: Auto
• Repository: hmdsefi/faultline
• Branch: release-0.2.0-docs
• File: .coderabbit.yaml
• Commit: c175a60
• Layers: Repository YAML
• Review profile: CHILL
• Plan: Advanced
• Run ID: 842422fe-f34b-4daa-a9d1-14f817c6c901

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

• X
• Mastodon
• Reddit
• LinkedIn