milestone-2 spec and api notes: as-built sync

specs/research/zig-0.16-api-notes.md

@@ -136,6 +136,26 @@ changed most of these APIs.
 - No MIME table, no etag: set `content-type`/`cache-control` manually via extra_headers.
   BodyWriter supports sendFile (contentLengthSendFile/chunkedSendFile).
 
+## std.testing.fuzz (0.16)
+
+- `std.testing.fuzz(context, testOne, options)` where `testOne: fn(ctx, smith: *std.testing.Smith) anyerror!void` —
+  the input is a `*Smith` structured generator, NOT a raw `[]const u8` slice (pre-0.16 form is gone).
+- `FuzzInputOptions{ .corpus: []const []const u8 }` seeds the corpus.
+- Smith surface (lib/std/testing/Smith.zig): `valueWithHash`, `valueRangeAtMostWithHash`,
+  `bytesWithHash`, `sliceWithHash(buf, hash) u32` (fills buf, returns length), `eosWithHash`, etc.
+  For raw-bytes parsers: fill a buffer via `sliceWithHash` and feed the prefix to the parser.
+- Plain `zig build test` replays each corpus entry once + one empty input (deterministic).
+  `--fuzz=<n>` = iterations PER TEST (K/M/G suffixes); bare `--fuzz` = forever + webui;
+  no time bound exists; `--fuzz=<n>` conflicts with `--webui`.
+- Corpus entries are Smith byte streams (slice = u32-LE length + bytes), not raw inputs.
+- STOCK 0.16.0 CANNOT RUN `--fuzz`: (A) fuzz-mode test_runner.zig:566 has a type error
+  (needs patched --zig-lib-dir); (B) the self-hosted x86_64 backend emits no coverage
+  PCs — set `.use_llvm = true` on the fuzz test artifact.
+- `zig test` collects tests ONLY from the root module — moving files into a named module
+  silently drops their tests. A file belongs to exactly one module per compilation, and
+  imports cannot escape the module root directory. Hence: aggregator imports files
+  directly; separate artifacts import a module-root file (e.g. src/dns/dns.zig).
+
 ## std.zon
 
 - Parse: `std.zon.parse.fromSlice(T, gpa, src_z, ?*Diagnostics, .{})` for pointer-free T