Startup contract fuzzing¶

catch2_startup_replay and fuzz_startup use the same replay support in tools/fuzzing/startup_fuzz_support.h. The harness drives the real ServiceManagerFsm, the real DeferralGate with virtual time, and the production semantic-score helpers. It never starts a daemon, opens a corpus, loads a model, changes host pressure, or sleeps.

Fast regression and seed replay¶

After configuring the usual Debug test build:

meson compile -C build/debug -j2 catch2_startup_replay catch2_embedding_service_timing
build/debug/tests/catch2_startup_replay --rng-seed 42
build/debug/tests/catch2_embedding_service_timing '[semantic-startup],[startup-eligibility]'

The seeded case tests 1,024 traces of 256 actions and float bit patterns per run. Failures report the Catch2 root seed, round and action offset. Re-running with that root seed reproduces the entire deterministic campaign. Named cases cover pressure deadlines before readiness, optional vector initialization, failure, shutdown, cancellation and explicit restart/reset. A separate real vector/KG fixture covers both streamed backfill and corpus-rebuild edge weights.

Coverage-guided campaign¶

Use the existing fuzz build configuration. ./setup.sh Fuzzing sets -Dbuild-fuzzers=true -Db_lundef=false and selects AFL++ or libFuzzer (tools/fuzzing/meson.build). It defaults TSan off: the harnesses link -fsanitize=fuzzer,address,undefined, so combining fuzzing with --tsan is rejected rather than producing a binary that cannot start.

A plain Meson configure also works and avoids Conan re-resolution:

CC=clang CXX=clang++ meson setup build/fuzzing \
  --native-file build/release/build-release/conan/conan_meson_native.ini \
  --wrap-mode=nofallback --buildtype=debug -Db_lundef=false \
  -Dbuild-fuzzers=true -Dbuild-tests=false -Dbuild-cli=false \
  -Dbuild-plugins=false -Dbuild-benchmarks=false

Every project object is then rebuilt with -fsanitize=fuzzer-no-link plus ASan/UBSan, so the first build of this lane is expensive. meson compile accepts either the executable name or its output path; raw ninja needs the path:

meson compile -C build/fuzzing -j4 fuzz_startup        # same as tools/fuzzing/fuzz_startup
python3 tools/fuzzing/startup_seeds.py /tmp/yams-startup-corpus
build/fuzzing/tools/fuzzing/fuzz_startup /tmp/yams-startup-corpus -seed=42 -max_total_time=60
build/fuzzing/tools/fuzzing/fuzz_startup /tmp/yams-startup-corpus/pressure-before-ready

Keep failing raw input files as regression corpus artifacts. The low seven bits of each byte select StartupAction modulo its count; the high bit selects the optional-vector branch for an advance action. Processing is bounded to 512 actions and 32 float-component pairs. A deadline action advances virtual time past the pressure starvation deadline; elapsed time cannot supply missing startup readiness. Seed generation refuses to overwrite different existing files.

Scope¶

This is a contract-valid, single-owner state-machine/data fuzzer, not a full startup or concurrency proof. tinyfsm state is process-global, so do not run multiple replay instances concurrently in one process. Independent fuzz worker processes are fine. The Catch2 smoke target also compiles and invokes the actual coverage-fuzzer entry point without claiming coverage-guided instrumentation.

Known coverage limit: the replay asserts that ineligible work leaves the real DeferralGate untouched, but that ordering lives in the harness. A regression that moved ResourceGovernor::admitDeferrable() ahead of the readiness check inside EmbeddingService::channelPoller would not fail the replay. The service-level [startup-eligibility] test covers the production predicate (semanticBackfillEligible) and its stop/idle behavior, not the governor call order; covering that needs an injectable admission seam.

Arbitrary late callbacks, real executor interleavings, concurrent FSM instances, filesystem/model/plugin faults, migrations and cold-start resource KPIs need additional production seams and separate integration campaigns. Do not infer live startup speed, sanitizer-engine coverage or end-to-end recovery from a passing replay test.