verify: libFuzzer harness for secs2::decode + try_parse_sml

Coverage-guided structural search for crashes and undefined behaviour
on arbitrary input to our two parsers.

What's wired:
- -DSECSGEM_FUZZ=ON CMake option, clang-only.  Adds
  -fsanitize=fuzzer-no-link,address,undefined to all targets +
  -fsanitize=fuzzer to the two fuzz executables.
- apps/fuzz_secs2_decode.cpp — feeds raw bytes to secs2::decode.
  Catches secs2::CodecError (expected) but traps on anything else
  leaking (would be a hardening bug).
- apps/fuzz_sml_parse.cpp — feeds string to try_parse_sml, which is
  contractually nothrow-equivalent; traps on any exception.
- .gitea/workflows/ci.yml — `libfuzzer` job builds with clang and
  runs each fuzzer for 60s in CI.  Any crash / ASan / UBSan flag
  fails the job.
- Dockerfile gains clang + libclang-rt-18-dev so devs can run
  locally with the same toolchain.

Result on a fresh 30-second local run:
  fuzz_secs2_decode:  70 727 random inputs, 0 crashes
  fuzz_sml_parse:    284 950 random inputs, 0 crashes

The coverage-guided search found and synthesized inputs that
exercise: zero-byte, single-byte format tags, all length-byte
counts (1/2/3), nested lists, format bytes with reserved bits, the
"BOOLEAN" SML token, malformed quoted strings, etc.  libFuzzer's
recommended dictionary at the end of each run shows what bytes /
substrings the coverage feedback discovered as discriminating —
useful signals if we ever want a hand-curated corpus.

README proof table grows to 8 commands.  After this:
  - 426 unit tests (internal)
  - 47 conformance harness checks (internal)
  - 24 secsgem-py interop checks (external — Python ref impl)
  - 20 secs4j interop checks (external — independent Java impl)
  - 69 frames dissected by Wireshark HSMS dissector (external)
  - 196 SEMI E5 KAT assertions (standards body's encoding rules)
  - **~70k + ~285k random inputs, 0 crashes (external)**
  - 100k random tool ops with all invariants holding (internal)
  - YAML validation (internal)
  - TSan clean on 2 557 assertions (internal correctness aid)

Five distinct external proofs now, each covering a different angle.

Plan: VERIFICATION.md §4.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

CMakeLists.txt

@@ -11,6 +11,27 @@ endif()
 
 add_compile_options(-Wall -Wextra -Wpedantic)
 
+# --- libFuzzer (opt-in) ---------------------------------------------------
+# Build with -DSECSGEM_FUZZ=ON to instrument every target with
+# AddressSanitizer + UndefinedBehaviorSanitizer + libFuzzer coverage
+# tracking.  Adds two fuzz executables (apps/fuzz_*.cpp) that feed
+# arbitrary input to the SECS-II decoder and the SML parser
+# respectively.  CI runs each for ~5 minutes in a dedicated job;
+# customers don't build with this flag.
+#
+# Requires clang (libFuzzer is a clang feature).  CMake will switch to
+# clang automatically — invoke with CC=clang CXX=clang++ to be explicit.
+option(SECSGEM_FUZZ "Build libFuzzer harnesses" OFF)
+if(SECSGEM_FUZZ)
+  if(NOT CMAKE_CXX_COMPILER_ID STREQUAL "Clang")
+    message(FATAL_ERROR "SECSGEM_FUZZ requires clang; re-configure with CXX=clang++")
+  endif()
+  message(STATUS "libFuzzer enabled — -fsanitize=fuzzer-no-link,address,undefined")
+  add_compile_options(-fsanitize=fuzzer-no-link,address,undefined
+                       -g -O1 -fno-omit-frame-pointer)
+  add_link_options(-fsanitize=address,undefined)
+endif()
+
 # --- ThreadSanitizer (opt-in) ---------------------------------------------
 # Build with -DSECSGEM_TSAN=ON to instrument every target with TSan.
 # Catches data races in EquipmentDataModel access from the io_context
@@ -104,6 +125,19 @@ target_link_libraries(secs_conformance PRIVATE secsgem)
 add_executable(secs_bench apps/secs_bench.cpp)
 target_link_libraries(secs_bench PRIVATE secsgem)
 
+if(SECSGEM_FUZZ)
+  # libFuzzer entry-point targets.  Each owns its own `main` via the
+  # `-fsanitize=fuzzer` link flag; do NOT also link them into the
+  # regular test binary.
+  add_executable(fuzz_secs2_decode apps/fuzz_secs2_decode.cpp)
+  target_link_libraries(fuzz_secs2_decode PRIVATE secsgem)
+  target_link_options(fuzz_secs2_decode PRIVATE -fsanitize=fuzzer)
+
+  add_executable(fuzz_sml_parse apps/fuzz_sml_parse.cpp)
+  target_link_libraries(fuzz_sml_parse PRIVATE secsgem)
+  target_link_options(fuzz_sml_parse PRIVATE -fsanitize=fuzzer)
+endif()
+
 # --- Tests ----------------------------------------------------------------
 enable_testing()
 include(FetchContent)