feat: export the fuzzer input layout

[N3ur0sis]

Closes #12

The offsets absolution uses to fill globals were only recoverable by reading the
generated fuzzer.c, so a harness run against a corpus had no supported way to
address a specific global.

--offsets exports the layout two ways:

• constants in the generated C — absolution_globals_size, plus one
  absolution_offset_<global> per global (a static uses the mangled name it
  gets after objcopy renaming, since that's what it links as)
• a sidecar file — line-oriented like .redef, with a version directive

Offsets reuse the same per-global byte accounting that sizes the seed file, so
the exported total can't drift from what the sampler consumes.

Opt-in: without the flag the generated output is byte-identical to before.
absolution_add_fuzzer() always requests it and exports ${NAME}_OFFSETS_FILE.

Tests: 132 unit (13 new) + 22 integration — offsets are now requested for every
fixture, so all of them also check the emitted constants compile, and the new
exported_input_offsets fixture pins exact values. Both release modes and the
CMake example verified.

[Copilot]

Pull request overview

Adds a supported way to export the fuzzer input layout (per-global byte offsets and total sampled prefix size) so harnesses and corpus tooling can address specific globals without parsing generated fuzzer.c. This extends the CLI/codegen pipeline and updates the CMake + test harnesses to consistently request (and optionally pin) the exported layout.

Changes:

• Introduces --offsets <path> to emit (1) linkable size_t offset constants in generated C and (2) a line-oriented .offsets sidecar file.
• Refactors byte accounting into shared IR helpers (fieldInputBytes / globalInputBytes) and reuses it for both seed sizing and offset export.
• Extends integration/unit tests and fixtures to validate compilation of emitted constants and optionally compare .offsets goldens.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
USAGE.md	Documents --offsets outputs (C constants + sidecar format) and intended consumption patterns.
README.md	Updates feature list and CLI example to include optional input-layout export.
CONTRIBUTING.md	Documents .c.offsets golden files and the new input-layout export entrypoint.
src/seed.zig	Reuses shared IR byte accounting for seed sizing to prevent drift.
src/main.zig	Adds --offsets CLI option and forwards it into code generation.
src/cgen/ir.zig	Adds fieldInputBytes/globalInputBytes helpers to centralize input-byte accounting.
src/cgen/emit.zig	Implements layout computation, emits offset constants + sidecar when --offsets is set, adds unit tests.
scripts/integration.zig	Always requests offsets during integration runs; compares .offsets to golden when present.
scripts/gen-golden.sh	Generates offsets output and refreshes .offsets goldens only when fixtures include them.
cmake/RunAbsolution.cmake	Adds optional OFFSETS argument and passes -m/--offsets to the CLI.
cmake/AbsolutionFuzzer.cmake	Makes absolution_add_fuzzer() always generate/export the offsets sidecar and expose ${NAME}_OFFSETS_FILE.
tests/exported_input_offsets/target.c	New integration fixture covering contiguous bytes, interior padding, arrays, and static mangling.
tests/exported_input_offsets/target.c.zon	Golden parsed-module output for the new offsets-focused fixture.
tests/exported_input_offsets/target.c.offsets	Golden offsets sidecar output pinned for the new fixture.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.