chore(fuzz): add cargo-fuzz suite and untrusted-input coverage gate

[crowecawcaw]

Summary

Adds a coverage-guided libFuzzer suite (via cargo-fuzz) over the crates that parse, decode, or evaluate untrusted input, a CI workflow that runs it on PRs and merges to main, and a hard "all untrusted inputs are fuzzed" gate.

Why: the reports/*-quality-evaluation-report.md cycle keeps re-discovering the same class of defect by hand — arithmetic overflow and char-boundary panics reachable from attacker-controlled expression text, templates, and manifests. Encoding that class as executable checks stops it from being re-litigated every review cycle.

Fuzz targets (12)

Each asserts the same invariant: any input returns Ok or Err — never panics, aborts, or hangs.

Target	Entry point
expr_parse	ParsedExpression::new / with_profile
expr_evaluate	parse + evaluate under both POSIX and Windows path formats
range_expr	RangeExpr::from_str + len/get/iter
int_range_new	IntRange::new with arbitrary i64 triples
range_expr_slice	RangeExpr::slice with arbitrary i64 indices
expr_type_parse	ExprType::parse
format_string	FormatString::new + resolve_string_with
copy_symbol_value	copy_symbol_value dotted-name walk
model_decode	document_string_to_object + decode_{job,environment,}_template
model_create_job	preprocess_job_parameters + create_job (instantiation — one layer past decode)
snapshot_decode	decode_manifest + Manifest::validate
snapshot_ops	diff/compose/partition/subtree/filter over decoded manifests

The fuzz crate lives outside the root workspace (its own empty [workspace] table), so the stable build/test/clippy/MSRV jobs are untouched. It builds only under a pinned nightly with AddressSanitizer, overflow-checks, and debug-assertions on.

Coverage gate (the hard check)

scripts/check_fuzz_coverage.py + fuzz/fuzz_coverage.toml, wired into the Compliance CI job — pure source+manifest analysis on stable Python, no Rust build, no nightly. Every public function taking a &str / &[u8] / serde_json::Value / &Path parameter must be classified in the registry as either fuzzed-by-a-target or explicitly not-untrusted-with-a-reason. The check enforces:

• no orphan targets (a fuzz_targets/*.rs missing from the registry),
• no phantom targets (a registry entry with no target file),
• no dangling classifications (a classified fn that was renamed/removed/made private), and
• the ratchet — a newly-added untrusted-input entry point fails CI until a human triages it.

108 input-shaped public functions are classified today (69 fuzzed, 39 not-untrusted). All four failure modes were verified to fail CI.

CI / running

• One job, short smoke run (FUZZ_SECONDS=10 per target) on PRs and merges to main. scripts/run_fuzz.sh derives the target list from cargo fuzz list, so new targets are picked up automatically — nothing to maintain in YAML.
• Locally: scripts/run_fuzz.sh (all targets), FUZZ_SECONDS=300 scripts/run_fuzz.sh (deeper), or name specific targets. See fuzz/README.md.

Seeds

Curated, per-file, one per structurally-distinct input shape plus deliberate edge cases (multibyte strings, i64 boundaries, symbol-table-prefixed expressions) — 189 files total, in the typical range for committed fuzz seeds. .gitignore excludes libFuzzer's SHA-named discovered inputs so they can't leak into the tree.

Bug found & fixed

path_starts_with under the Windows path format sliced a path by the base string's byte length, panicking when that offset fell inside a multibyte char (expr report finding X8) — surfaced once expr_evaluate exercised the Windows path format. Fixed with a byte-slice comparison (equivalent for ASCII case-folding, boundary-safe), plus a regression test.

Rebase note

Earlier revisions of this branch also fixed RangeExpr/IntRange integer overflows the fuzzer found. Those are now superseded by upstream #276 (bounded range values), so this branch is rebased onto it and drops the redundant range changes — keeping the fuzz targets (int_range_new, range_expr_slice) that guard the area.

All openjd-expr tests pass; cargo clippy -D warnings is clean workspace-wide.

🤖 Draft — opened for review, not yet marked ready.

[mwiebe]

Is there a way to do this that puts these into one file instead of hundreds of tiny files?

[crowecawcaw]

The fuzzer needs separate files. We could combine them in a txt file and the split them at runtime, but its another step. I thinned out the starting seed cases instead.

[mwiebe]

The report https://github.com/OpenJobDescription/openjd-rs/blob/main/reports/expr-quality-evaluation-report.md#priority-4--tests-and-robustness notes the lack of fuzz testing, which this PR addresses. Can you update that per how AGENTS.md recommends, and also scan for where it might be worth updating the specs/ for this change?

[crowecawcaw]

Done in 7f2d995. Struck through the resolved report items: the expr report's recommendation 20 (fuzz harness), the §4 no-fuzz structural gap, the §5 test_fuzz.py parity gap, and the X8 path_starts_with char-boundary panic that this PR fixes; and the model report's gap 5 / recommendation 12 (the model_decode/model_create_job targets cover it). The sessions report's directive-parsing fuzz note stays open since the suite doesn't cover openjd-sessions.

For specs/docs, I scanned specs/ and documented the suite where it's cross-cutting rather than per-crate: specs/architecture.md now shows fuzz/ in the project layout and has a Key Design Decisions entry for the fuzzing approach and the coverage gate. AGENTS.md gets the fuzz scripts in the quick reference, the Fuzz workflow + Compliance-job gate in the CI table, and a note that any new untrusted-input public fn must be classified in fuzz/fuzz_coverage.toml before CI passes. The per-crate specs describe language/model semantics, not test infrastructure, so I left those alone — fuzz/README.md remains the detailed doc for the suite itself.

[github-actions]

The private-module regex only recognizes bare mod foo;; it misses restricted-visibility declarations like pub(crate) mod / pub(super) mod / pub(in path) mod. For pub(crate) mod budgeted_vec;, the (pub\s+)? group fails to match (there is no whitespace after pub), so the group matches empty and then mod fails against pub — the module is not added to private_tops.

Consequence: pub fns inside crate-private modules are scanned as "input-shaped public functions" even though they are not part of the crate’s public API. This is exactly what happens with crates/openjd-expr/src/edit_distance.rs::edit_distance / suggest_closest (a pub(crate) mod), which the docstring here says "must not count toward the untrusted surface" yet are forced into [[fuzzed]] at fuzz_coverage.toml:197-201.

The direction is safe (over-inclusion never lets a real entry point escape the ratchet), but it contradicts the documented contract and inflates the classified-surface count with crate-internal functions. Consider matching pub\s*(\([^)]*\))?\s+mod and treating any non-pub (i.e. anything with a (...) visibility restriction) as private.