The roc-fuzz manual

A fuzz target is a small Roc application that connects roc-fuzz to one behavior in your code. It contains three essential ideas:

The target is necessary because roc-fuzz cannot infer what correctness means for your application. It can explore inputs and notice crashes, hangs, leaks, and new behavior in the compiled program, but only you can state application rules such as:

A target is development and test code. It is separate from the application you ship, and it normally imports the module it exercises. Start with one operation and one property per target so failures remain easy to understand.

Unit tests and fuzzing answer different questions and work best together.

After roc-fuzz finds a bug, fix the code and keep the minimized case as a normal regression test. The unit test prevents that exact bug from returning. Future fuzzing continues searching for cases nobody has named yet.

Typed means the test receives ordinary Roc values rather than making every target decode an arbitrary byte array itself. A generator can produce a U64, a Str, or a record such as { delimiter : Str, value : Str }. You choose the useful ranges and shapes. roc-fuzz does not automatically know your application’s domain rules.

Coverage-guided describes how the search chooses where to spend effort. roc-fuzz observes which parts of the compiled program each input reaches. When an input reaches behavior not seen before, it retains that input and creates further variations from it. This feedback makes the search more purposeful than independent random samples.

The retained useful inputs form a corpus. A later run can reuse that corpus to resume from behavior already discovered. Coverage here is search feedback, not a percentage and not proof that the program is correct.

roc-fuzz embeds a mature native fuzzing engine in the executable built by Roc. Normal users interact with roc-fuzz commands and Roc values; knowledge of that engine is needed only for the expert escape hatch described later.

For a Roc application author, the platform supplies:

A target builds into one self-contained executable:

The normal workflow needs no separate native project or fuzzing tool installation.

Good first targets are fast, deterministic operations over in-memory values with a rule that is easy to state.

A target is a poor fit when one input performs slow network, filesystem, UI, or database work; depends on nondeterministic external state; can legitimately run without a practical time or memory bound; or deliberately terminates the process for ordinary invalid input. Prefer unit, integration, end-to-end, or benchmark tests for those jobs.

Fuzzing consumes CPU time and stores a corpus and failure artifacts. More time can explore more behavior, but a clean run means only that no failure was found during that search. It never proves the absence of bugs.

roc-fuzz currently supports Linux x86-64 with musl and Apple Silicon macOS 11 or newer. Continue with Fuzz your first function to build a target against a small application module and work through a failure.

Create fuzz/stack/Stack.roc:

This version contains a plausible implementation mistake: push appends the new item to the end, while pop removes an item from the front. A test using only an empty stack would pass, so the defect is easy to overlook.

The fuzz target is a separate development application that imports this module; the shipped application does not need to depend on roc-fuzz.

Create fuzz/stack/main.roc:

The target connects the three ideas from the previous chapter:

Fuzz.keep means the generated case completed normally and satisfied the property. crash means roc-fuzz must save the case as a failure. show tells roc-fuzz how to render the generated value for a person.

The application header selects an immutable roc-fuzz release and its compatible Roc compiler. For another project, select a release from GitHub Releases and use the compiler documented with that release. Roc obtains the platform through its normal package mechanism; there is no separate roc-fuzz installer.

Build a self-contained fuzzing executable:

Start with the bounded default run:

roc-fuzz generates initial stacks and repeatedly runs the property. An empty stack passes even with the bug, while a non-empty stack can expose the mismatch between the two ends. The exact status lines and saved hash vary, but the end of the output includes commands shaped like these:

The saved file contains the reproducible input used by the generator. It is an implementation format for roc-fuzz, so inspect it with show instead of opening it as text:

For this target, show prints the generated initial stack. Reproduce the failure in a fresh process:

Then ask roc-fuzz for a smaller reproducing input:

Minimization is most useful for structured or long inputs, but using the same workflow here establishes the habit.

The two stack operations disagree about which end is the top. Fix push in Stack.roc:

Rebuild the executable and replay the minimized input. It should now complete without a failed property:

Append a normal regression test using the minimized non-empty stack to Stack.roc:

Run it with the rest of the module’s tests:

Use the actual value printed by show if minimization found a different one-element list. The regression test protects this known case on every test run; the fuzz target continues exploring other values and future implementation changes.

A bounded run that finds no failure is still a successful run. It means the property held for the cases explored during that run, not that the operation is proved correct.

By default, run stops after 60 seconds, keeps useful inputs under .roc-fuzz/corpus, and saves failures under .roc-fuzz/. The corpus is a set of inputs that reached behavior worth revisiting; later runs reuse it and continue searching from those discoveries.

During a clean run, NEW means the engine retained an input that reached new behavior and DONE means the configured bound was reached. The campaign status glossary explains the remaining fields and tuning options.

Choose one fast application operation and one rule that should hold for every input. Common property shapes include:

Generate useful values directly. If a parser accepts bytes of any shape, arbitrary bytes may be appropriate. If an operation requires a bounded port number or a non-empty list, express that rule in the generator so most search effort reaches the behavior you care about. Use Fuzz.reject only when a generated case lies outside the property; do not use crash to reject an ordinary invalid input.

Keep unrelated operations and properties in separate targets. A practical first set might include one target per parser, encoder/decoder pair, state transition, or important business invariant. There is no need to fuzz every function.

The campaign guide explains corpora, tuning, and unstable failures. The advanced guide covers generator dispatch, allocation assertions, and the low-level engine interface. Run TARGET --help for the command summary and browse the generated API reference for generator, combinator, and target signatures.

The repository’s examples/ applications use relative paths to the local platform; prepare its native inputs before building them. Published releases provide a roc-fuzz-examples-VERSION.zip download containing complete runnable applications with that release’s content-addressed platform URL and publication compiler. The platform does not constrain consumers to that compiler: nightly compatibility checks exercise each release’s frozen examples with newer compilers.

Choose a function that is fast, deterministic, and easy to call in memory. Write the property in one sentence before choosing a generator. If the sentence needs several unrelated “and” clauses, make separate targets.

Examples include:

A generator explores only the cases the property can observe. Calling an operation without checking its result finds crashes and resource failures, but cannot find an ordinary wrong answer.

roc-fuzz provides generators for numeric values, strings, bytes, and collections. Use a bounded generator when the full type includes values that are irrelevant or too expensive for this target:

Fuzz.list(item_generator, maximum_length) generates a list whose elements come from item_generator. The maximum is a test-design bound, so choose a size that reaches meaningful behavior without making each case slow.

Use Fuzz.map when the domain value can be constructed from one generated value, and Fuzz.map2 when it needs two:

Constructing valid values directly gives the search more useful executions than generating a broad value and rejecting most cases.

Roc’s record-builder syntax can combine a generator for each field:

Use the resulting generator with Fuzz.target_with:

This explicit form is a good default for a generator used by one target. When a named input type owns a reusable generation policy, define its generator_for method and use Fuzz.target:

Both forms produce the same kind of typed target. The advanced explanation describes how Roc resolves generator_for; using the pattern does not require knowing its implementation.

An ordinary invalid input is not automatically a fuzzing failure. A parser may return Err for malformed text and still satisfy a robustness property. Return Fuzz.keep when the observed result is allowed.

Prefer a generator that creates valid domain values. Return Fuzz.reject when a precondition is awkward to encode and the generated case is outside the property you are testing. Do not use crash or expect to reject such a case; those mean roc-fuzz found a failure worth saving.

Watch the rejection rate as tooling adds support for it. If most inputs are rejected, redesign the generator so the campaign spends more time in the code that matters.

A saved file is decoded by the target’s generator. Changing that generator can make an old file produce a different typed value. Keep generators stable when a corpus or failure matters, and retain the matching executable when exact historical reproduction is important.

The generated API reference lists all generators and combinators. Continue with Run and maintain fuzzing campaigns when the target produces useful values and passes a short smoke run.

The examples/builtins/arctangentDec.roc, arctangentF32.roc, and arctangentF64.roc targets check atan and atan2 with composed numeric generators. They also assert that the numeric checks allocate no heap memory; input generation and diagnostic rendering are outside that measurement.

The float targets check NaN propagation, signed zeros, infinities, range, quadrants, and odd symmetry. F32 results are compared with F64 results rounded to F32, allowing two ULP. F64 angles are checked against normalized input coordinates using sine and cosine, with absolute tolerance 3e-15. Quadrant checks allow two ULP at the rounded half-pi boundary, while zero and infinity cases require exact result bits.

The Dec generator composes two U64 values into a signed 128-bit attosecond payload and varies its magnitude with a shift. It checks axes, range, symmetry, and agreement between atan(y) and atan2({ x: 1, y }), allowing 128 attoseconds. Comparison with the separate F64 implementation allows 4e-15 for conversion and floating-point error. Dec.lowest is tested but excluded from negation checks because its negation overflows.

These checks supplement the compiler’s high-precision unit tests; shared algorithms and finite tolerances mean they do not prove correct rounding. To run just these inventory entries with a compiler that includes the atan2 builtins:

Use the normal runner’s show, replay, and minimize commands to investigate saved failures, as described in the campaign chapter.

Give every new target a short, bounded smoke run before a long campaign:

The most useful limits are:

--max-input-size limits the generator’s raw input, not necessarily every typed list or string it produces. Put bounds in the generator as well when a typed value could become expensive.

Do not confuse the campaign seed with a saved input. Different engine builds, coverage layouts, or configurations may generate different mutation sequences from --seed. Reproduce a failure with its saved artifact and replay, not with the campaign seed alone.

The runner reports compact status fields:

Coverage growth shows that the fuzzer is exploring. A plateau is a reason to inspect the target, generator, seeds, and dictionary, not proof that the code has no bugs. Very low exec/s, steadily growing rss, or repeated timeouts usually calls for a narrower target or tighter bounds.

A corpus is a collection of small raw inputs that collectively reach useful code. It is not a directory of every attempted input. Use a stable corpus directory across campaigns:

Seed a target with a few small examples that reach meaningfully different behavior, then let the fuzzer extend them. Because roc-fuzz decodes raw entropy into typed values, a seed file’s bytes may not resemble the value printed by show. Check manually created seeds with the target executable.

Reduce a large corpus into a new, initially empty directory while preserving coverage:

Keep valuable seeds and fixed crash inputs with the target in version control. Use a deliberate directory such as fuzz/corpus/<target>/, document why each seed matters, and replay it in tests. Generated .roc-fuzz/ directories are ignored at every depth; keep evolving campaign corpora in local storage or CI caches, and preserve findings as CI artifacts until reduced to regressions. Run them after code changes so the target does not silently stop compiling or exercising the intended behavior.

Dictionaries are most effective when recognizable bytes flow fairly directly into a parser. They may help less when a structural generator heavily transforms the raw input.

Changing a generator can make old corpus and crash files decode to different typed values. The generator is part of the target’s input format. Keep it stable when practical and use show to check saved inputs after a change.

Always replay a saved failure in a fresh process. If it does not reproduce, investigate:

Treat the failure as actionable once its conditions are understood and, ideally, it reproduces from a clean process.

Coverage feedback tells the engine which inputs explore new behavior; it does not tell the runner whether a result is correct. The property in the target is the correctness oracle.

roc-fuzz saves explicit Roc crash and failed expect calls, per-input timeouts, and process memory-limit failures. A wrong answer that does not break the target’s property is invisible to the fuzzer, which is why choosing a strong property matters more than simply calling the function under test.

Before committing substantial CPU time, check that:

Run TARGET --help for the executable’s own summary.

The stable run and ci options are:

The ci command also accepts provenance fields including --source-revision, --roc-version, --platform-release, and --platform-sha256. See Add fuzzing to CI for their use and the report layout. The raw engine command is an advanced escape hatch rather than part of the normal interface.

The host operates one compiled target. A downstream repository remains responsible for:

This is important for targets such as Unicode conformance fuzzers, whose seed corpora are derived from versioned data files. A generic host cannot infer that application policy. A checked-in script or CI matrix should enumerate targets and invoke each resulting binary’s ci command.

Leak checks remain enabled by default. --no-detect-leaks is available for a documented exceptional campaign, and the report records that it was used. Projects testing allocation-sensitive operations should also place Fuzz.expect_allocs_at_most! or Fuzz.expect_allocs_at_least! around the exact operation whose cost is an invariant.

The following complete pattern assumes one target file per fuzz/TARGET.roc and optional checked-in seeds under fuzz/corpus/TARGET/. Repositories with generated seeds should replace only the seed-preparation step with their own script.

Pull requests therefore get a one-minute bounded campaign per target, while the scheduled workflow gives each target fifteen minutes. Keep normal unit and regression tests on every change as well; a fuzz corpus is not a correctness oracle by itself.

These artifacts provide reviewable evidence that dynamic analysis ran with explicit bounds and assertions, and that findings were retained. They do not measure source coverage.

The runner’s cov and ft values are search-feedback counts from LLVM SanitizerCoverage. They have no source denominator and are not statement or branch percentages. Do not report them as either kind of percentage.

True Roc source coverage requires the Roc compiler to emit LLVM profile instrumentation and coverage mappings, link the matching profile runtime, and preserve stable source paths. Until that compiler work ships, roc-fuzz can report search progress and retained evidence but cannot provide a Roc source-coverage percentage.

Download a bundle from the GitHub release, then run:

Verification checks the bundle digest, Sigstore signature, certificate and repository identity, and transparency information. This project does not claim a particular SLSA level; the attestation establishes the workflow and revision that produced the released bundle.

For offline or archived verification, download the matching <bundle>.intoto.jsonl asset and pass it to GitHub CLI:

The adjacent .spdx.json file is human- and machine-readable release inventory. Its root package checksum must equal the SHA-256 of the downloaded bundle.

The embedded libFuzzer calls a target thousands of times in the same process. It does not start a clean executable for every generated input. This is what makes it fast. Roc’s purity means target calls cannot leak application state or background work into later calls, and determinism makes saved inputs reliable with the same target and generator.

A reliable target still needs all of the following properties:

The runner is a poor fit when one test takes a significant fraction of a second, can grow without a practical memory bound, or is expected to terminate the process for invalid input. If a crash, timeout, or memory blow-up would be a bug, it remains a useful fuzzing failure.

A saved raw input produces the same typed value and result when the target and generator are unchanged. Keep the executable alongside important failure artifacts when exact historical reproduction matters.

generator_for uses Roc’s ordinary static dispatch. It is a method associated with the target’s input type, not a runtime interface, registry, or callback table. Package APIs can require their own methods with where clauses, so the method does not need to be a compiler-defined name.

The pattern deliberately mirrors Json.parser_for:

Conceptually, Fuzz.target has this requirement:

FuzzEncoding currently contains the Default policy. Passing a policy value follows the same shape as JsonEncoding and leaves room for additional generation policies without changing the method pattern.

Use Fuzz.target when generation is part of a reusable named input type. Use Fuzz.target_with with an explicit Generator(a) for a local structural input or when choosing between generators for the same type in different targets.

A property can check what a builtin computes but not what it costs. A builtin that stops mutating a uniquely owned value in place and starts copying it still produces correct answers, so no content-based property will notice the regression. Fuzz exposes the platform’s allocation counters so a target can assert on cost as well as correctness:

alloc_count! and live_alloc_count! are process-wide and monotonic, and libFuzzer reuses one process across millions of inputs, so never assert on a raw value. Always read the counter before and after the region you care about and assert on the difference; measure_allocs! and expect_allocs_at_most! and expect_allocs_at_least! do this for you.

Only assert zero allocations for a value that is genuinely uniquely owned and pre-sized. If the value is aliased anywhere, copy-on-write allocation is correct behavior, not a regression. Measure only the region you mean to check: a constructor call such as Dict.with_capacity allocates the entries and bucket lists, so keep it outside the measured window.

Allocation assertions need an effectful test, so build the target with Fuzz.target_with! or Fuzz.from_bytes! instead of their pure counterparts. target_with! takes test! : a ⇒ Outcome; from_bytes! takes test! : List(U8) ⇒ U8.

These constructors exist because the runner calls a target through the widened run! : List(U8) ⇒ U8, not the older pure run : List(U8) → U8. This is a backward-compatible change: a pure function body already satisfies an effectful signature, so every existing target keeps compiling and running unchanged. Keep targets pure unless the property itself needs one of the allocation combinators above — a pure target is deterministic, and libFuzzer’s crash replay and minimization rely on that determinism to reproduce and shrink a saved failure.

TARGET raw [LIBFUZZER_ARG…​] passes arguments directly to the embedded libFuzzer CLI. Run this for its complete option list:

Prefer run, show, replay, minimize, and reduce-corpus for the normal workflow. Low-level flags such as -max_total_time and -max_len belong behind raw; run accepts the stable friendly options listed above. raw is an escape hatch for libFuzzer features the friendly command layer does not yet expose directly.

Normal documentation, Roc source validation, target builds, and packaging require only:

Linker inputs have an independent, content-addressed release cycle; libhost.a is deliberately outside that cycle and is built with each platform update. This separation means a host or Roc source change does not rebuild large, stable runtime inputs. Source development and the explicitly dispatched producer require Zig 0.16.0. The builder uses zig ar.

The setup action installs separate roc-stable and roc-nightly executables. The local setup-workspace-roc action reads their exact selections from workspace metadata and checks the installed versions. Tooling has its own fixed roc_stable selection; it does not advance with routine project nightly updates. ROC_STABLE and ROC_NIGHTLY allow explicit local overrides.

The shared nightly updater resolves the latest published compiler once, tests that exact candidate on both hosts, then advances only roc_nightly after all required checks pass. The platform and local examples contain no compiler pins. This metadata records a tested compiler, not an exclusive compatibility claim for a released platform.

Repository examples use relative paths to the working-tree platform. Each new release provides roc-fuzz-examples-VERSION.zip with complete applications, supporting modules, seeds/test inventory, an exact platform release URL, and the publication compiler in application headers. Newer compilers are checked against that frozen suite, independently of APIs added to the current repository examples. Only temporary application compiler pins are updated for these compatibility runs; the released platform bytes and URLs remain unchanged.

Repository-owned automation is written in Roc. Put executable entry points in scripts/.roc and reusable logic in scripts/src/.roc. Use the existing shared modules for commands, paths, hashing, source edits, archives, and release metadata. Do not add Python scripts, shell launchers, or build-before-run wrappers to work around compiler behavior. Keep workflow YAML limited to job orchestration and small environment/output plumbing; substantive automation belongs in Roc.

Run scripts directly with roc-stable scripts/NAME.roc — ARGUMENTS, or their #!/usr/bin/env roc-stable shebang. Nested tooling calls use ROC_STABLE through Script.roc_stable!; project validation uses ROC_NIGHTLY separately. The fixed roc_stable selection must execute the tooling and its dependencies without warning-exit workarounds. Upgrade it deliberately when a compatible compiler and dependencies are available. A successful script must return zero, and a failed script must remain a failure.

Roc scripts may invoke standard tools such as Git, curl, tar, zip, and unzip via argument lists, without shell evaluation. Roc owns selection, validation, and control flow. Pinned external tools and shared actions remain external dependencies; for example, the shared documentation builder currently uses Python internally. That does not justify adding repository-owned Python orchestration.

Pure regression checks belong in shared-module expect`s imported by `scripts/tooling_tests.roc. Filesystem and process checks belong in scripts/tooling_integration_tests.roc; both run from scripts/check_all.roc. The archive tools require Git, curl, tar, zip, and unzip on local and CI hosts.

Generate the current host’s ignored inputs with:

Pass --target x64musl or --target arm64mac explicitly in automation. The default restores the archives selected by native-libraries.lock.json, rehashes their manifest and target archive even on a cache hit, validates the complete archive inventory, builds the current host, and writes local SHA256SUMS. The archive digest is the reviewed authorization for routine use; the cache key only locates likely bytes. This is why cache hits are still hashed and why a cache miss downloads the exact locked release rather than rebuilding. It avoids repeat network traffic without allowing a poisoned or truncated cache entry to become trusted. Routine restoration does not query GitHub’s attestation service. Never commit generated archives, objects, or manifests.

The workflow-dispatch-only Linker inputs producer packages both targets without libhost.a, tests each candidate through a fresh host and final bundle, emits a canonical aggregate manifest, and attests that manifest and both archives. It has no publication authority. Release new inputs for changes to their sources, runtimes/toolchains, flags, targets, security fixes, or the macOS adapter compiled into libfuzzer.a. The macOS coverage shim stays with libhost.a.

Publish linker inputs runs trusted controller code pinned to a reviewed full roc-automation commit. It dispatches the producer at the exact same-repository PR head, verifies the workflow/ref/SHA, hashes and attestations, publishes an immutable release named from the aggregate manifest hash, and adds only the lock in a lease-guarded GitHub-signed commit. Candidate code cannot publish, while the privileged job never executes candidate code. The PR-built release remains the permanent dependency after merge; rebuilding it would break the evidence-to-byte identity that the review admitted.

GitHub immutable releases must be enabled before the first publication. The controller checks the resulting release state and refuses to adopt a lock when the hosting policy does not enforce immutability; a content-derived name alone cannot prevent an administrator from replacing assets.

Before adopting a release, review its producer changes, exact source revision, input fingerprint, manifest and archive digests, sizes, target coverage, native link tests, and workflow attestations. Merge with a merge commit so the attested producer SHA and signed lock commit remain reachable. Ordinary PRs and nightly updates then know only the reviewed lock, cache, verifier, and target files; they never dispatch or reproduce linker inputs.

When the linker-input fingerprint changes, use this sequence:

The optional preview in step 2 does not replace the producer run performed by the trusted publisher in step 3. The publisher is the release operation; stop before that dispatch when only candidate validation is authorized.

The fully static build excludes FuzzerInterceptors.cpp. Its wrappers locate libc functions through dlsym, which is not usable in the static musl executable. The standard libFuzzer scheduler, mutators, corpus engine, crash handling, minimizer, and merge engine remain unchanged. Roc’s compare and switch instrumentation still supplies value feedback.

The macOS target includes FuzzerInterceptors.cpp: its dlsym lookups work with macOS’s dynamic libSystem. Its deployment target is macOS 11.0, and its only allowed dynamic dependencies are system libraries.

src/macos_sancov.c supplies the public TLS slot required by Roc’s macOS stack-depth coverage instrumentation. src/macos_fuzzer_ext_functions.cpp binds the standalone runner hooks directly because upstream libFuzzer’s Darwin dlsym lookup requires -export_dynamic, which Roc does not pass. Both files are repository-owned platform glue covered by the project license; the native build, show/replay, fuzz, failure-artifact, and packaged-bundle smoke tests exercise them on Apple Silicon.

Regenerate glue only when the Roc natural ABI changes:

Review the generated Zig diff and rebuild every example after regeneration.

Every bug fix and significant new behavior should include an automated test at the narrowest useful layer. Changes to public behavior also update the relevant examples, interface documentation, or report schema. A pull request should explain the behavior changed and the validation performed.

Use the compiler under development through ROC_NIGHTLY:

After native inputs are prepared, check_all.roc validates the working-tree platform and every example. test_targets.roc provides the focused operations shown above. Checked-in examples use the local platform. The published compatibility lane uses the selected release’s own frozen examples and immutable bundle. Validation checks the exact example inventory, Roc formatting and types. After generating the current host inputs, building creates every self-contained executable and verifies a static x86-64 ELF on Linux or an arm64 Mach-O with system-only dynamic dependencies on macOS. Seed validation renders and replays each deterministic input. The fuzz operation runs short campaigns and verifies that an intentional Roc failure is saved byte-for-byte with follow-up commands.

Build the HTML manual, PDF, and generated API reference with:

The command fetches the immutable shared renderer from roc-automation, uses Docker for the Asciidoctor toolchain, and writes the complete publication under .docs-out/. Set ROC_AUTOMATION_ROOT to a local checkout while developing the shared action. The final API audit fails if an exposed module or public entry has no rendered documentation. The documentation and release workflows run the same build and audit.

Every example runs the check, test, build, seed, and fuzz stages by default. A temporary exception must use a skip entry in tests/targets.json with both a concrete reason and a full GitHub issue URL. The driver rejects unexplained skips; skipping a prerequisite also requires skipping its dependent stages.

CI separates published compatibility, working-tree execution and packaged-platform execution. Published checks use the selected release’s frozen suite on fresh runners; development checks use local examples and current source. Both run on every PR and manual/nightly dispatch; there is no change classifier or migration exception. The release workflow additionally tests the exact candidate archives. nightly_validation: true never publishes or deploys.

Linux CI also rebuilds the checksum-pinned libFuzzer sources with AddressSanitizer and runs a short native smoke campaign. This detects heap, stack, use-after-free, and leak errors in the embedded C++ fuzzing engine on every pull request, every trunk update, and before release publication. Run the same check locally with roc-stable scripts/test_native_sanitizers.roc; it requires Clang, curl, and tar. The sanitizer executable is CI-only and does not change the static release artifacts.

The Roc driver runs on Linux and Apple Silicon without platform skips. Scripts execute directly with the fixed tooling compiler; compilation errors, warnings, and application failures retain their normal Roc exit status.

Use --suite-root PATH to run a frozen examples tree containing examples/ and tests/targets.json. Each invocation has fresh temporary executables and corpora. Fuzz smoke tests pass corpus directories to libFuzzer; passing an individual seed file would only replay it. Repository formatting is checked separately, not against an older release’s frozen source.

Published compatibility selects the highest stable semantic-version platform release, ignoring native-library releases and RCs. Both hosts consume the same selection and verify asset hashes. Releases through 0.4.1 use examples from the exact tag commit, rebound to that release’s own bundle (the old manual URL follow-up could occur after tagging). Newer releases must include the examples archive. The compatibility artifact records the release, source commit, compiler and asset identities used; a missing archive or failed download cannot become a passing test.

Every target asserts on allocation behaviour as well as on results. A property can check what an operation computes but not what it costs, so a builtin that stops mutating a uniquely owned value in place and starts copying it still returns the right answer and no content property notices. Pin the cost with Fuzz.expect_allocs_at_most! or Fuzz.expect_allocs_at_least!, and build the target with Fuzz.target_with! or Fuzz.from_bytes! so the property may perform effects. The check stage requires one of those assertion helpers; raw counter reads, measurements, and leak-only checks do not satisfy the policy. A target that genuinely cannot assert on cost belongs in the allocation-assertion exemptions in scripts/test_targets.roc with a concrete reason.

Assert on a difference between two counter reads, never on a raw value: the counter is process-wide and libFuzzer reuses one process across millions of inputs. Only assert zero for a value that is uniquely owned and pre-sized, because copy-on-write allocation is correct when a value is aliased.

Separately, the runner checks after every input that the target freed everything it allocated, and fails the input otherwise. Pass --no-detect-leaks to a run to turn that off.

The former byte-oriented builtin targets live under examples/builtins/ and use Fuzz.from_bytes. This keeps their existing properties in the regression matrix. Top-level examples are an end-user gallery and should prefer Fuzz.target, typed generators, and the .Fuzz record builder. A multi-file example must live in its own directory with main.roc as its app root; the test driver enforces this so editor tooling can discover the project naturally.

Create a Roc platform bundle after generating both target input sets with:

build_bundle.roc verifies every generated input checksum, then includes the archives and license notices in roc bundle. Production release jobs build both hosts on native hosted runners before bundling. Test the resulting bundle from an external target with:

Production releases use the Release workflow. From the repository’s Actions tab, run it on the default branch with an X.Y.Z version (or an X.Y.Z-rcN release candidate). Pull requests run the same workflow in dry-run mode. Before dispatching any publication, add a non-empty docs/releases/X.Y.Z.adoc or docs/releases/X.Y.Z-rcN.adoc. The first heading must be = roc-fuzz VERSION. Release notes are reviewed as documentation and should explain the release to users: lead with the theme, show notable features and compatibility changes, name the supported hosts and Roc compiler, link to verification material, and give upgrade or feedback guidance.

Use {platform-url} where the copyable app header needs the content-addressed bundle URL and {manual-url} for the release’s PDF. The workflow resolves both after packaging, translates the note’s headings and source blocks to GitHub Markdown with scripts/render_release_notes.roc, and uses that result as the description for stable releases and release candidates. A missing or mismatched note stops publication. A real release:

Pages is independent of a release and always tracks trunk. Pull requests build the same site without deploying it.

The bump check requires a version increment from the previous platform release. The release policy explicitly permits exact-nightly bootstrap on trunk; no stable compiler compatibility or maintenance branch is implied.

To unblock a source PR before stable bootstrap, dispatch Release on that branch with release_candidate=true, a new X.Y.Z-rcN version, and the full source SHA in expected_sha. Both target bundles must pass before the workflow attests and publishes the RC. Only this explicit RC path permits source-built libraries. It preserves the latest stable release and the trunk-tracking Pages site, and does not create a default-branch URL follow-up. Verify the published archive and its frozen examples before use. Stable releases still require the independent library lock.

Release preparation generates and tests the examples archive against the exact candidate bundle, then publishes and attests those same bytes. It does not rewrite repository example URLs. Download the examples asset when using a published release; cloning the repository gives examples for local platform development.

A routine nightly update never fixes or publishes a platform. If a new compiler breaks the latest release, the updater reports the failure on its pull request and leaves the accepted compiler unchanged. GitHub check notifications (according to each maintainer’s notification settings) and the PR report flag the failure. Maintainers manually investigate, fix, and release the platform. After that manual intervention, retry the nightly updater against the newly released suite. The updater records the new compiler only after validation passes; there is no automated platform-repair or release-recovery workflow.

A tooling/compiler-recipe migration can require a one-time linker-input publication through the existing reviewed PR publisher. The linker fingerprint includes the fixed tooling compiler and recipe, but excludes roc_nightly: subsequent project compiler-only updates reuse the admitted native libraries.

Inspect partial publication before recovery; never replace existing tags or assets or rebuild an already-published release from a moving branch. Preserve the exact tested artifacts, tag SHA and uploaded digests. No changes to historical releases are required to adopt this workflow.

Static dispatch happens while Fuzz.target is specialized for the app’s input type. Target then erases that type, preventing the native ABI from depending on every app record or tag-union layout.

The platform supports x64-musl and Apple Silicon macOS. Keep native calls behind generated glue so compiler ABI changes are caught by regeneration and compilation.

Use GitHub issues for reproducible bugs and enhancement requests. Include the roc-fuzz release, Roc compiler version, operating system and architecture, target source or a minimal reproduction, and the relevant command output. Proposed changes use pull requests and follow the contributor guide.

Suspected vulnerabilities follow the private security reporting process and must not be disclosed in a public issue. Published bundles, PDF manuals, documentation archives, checksums, provenance, and human-readable release notes are available from GitHub Releases.

The foundational and exploratory work for roc-fuzz was created by Brendan Hansknecht. Brendan established the original Roc fuzzing integration, arbitrary input machinery, quality-target suite, and the early trophy case demonstrating the bugs this approach could find.

The platform in this repository extends Brendan’s experiment into a modern Roc workflow with typed generators, reusable target construction, and a self-contained executable built directly with roc build --fuzz. This work would not exist without the foundation he developed.