# Seed corpora

Hand-written and real starting inputs, one directory per fuzz target. These are
committed; `corpus/` is not.

The split follows `astra-soak-overview`, which calls a minimized corpus
"accumulated compute, not a build artifact":

- **These seeds are human intent.** The `doc-` files are the protocol
  documentation's own examples. The `real-` files are genuine transmissions: a
  48x48 PNG off this machine sent both single-shot and in the 4096-character
  chunks a client actually uses, and raw RGB and RGBA frames whose dimensions
  agree with their payloads. Three are transmissions long enough to be chunked
  in earnest: a 64x64 RGBA frame in twenty-two 1024-character chunks, two
  chunked transmissions under different `i=` values sent back to back, and an
  animation that transmits a root frame, appends to it, composes and deletes.
  Chunk equivalence is the
  property with teeth in this oracle, and a corpus whose every payload fits in
  one body never reaches it. The rest is one file per shape worth reaching in
  the first second rather than the first hour: each medium a query can ask
  about, each way a chunked transfer is keyed, and the malformed bodies that
  sit one mutation away from a valid one.
- **`corpus/` is machine output and lives on astra**, under the soak runner's
  persistent directory. Minimize with `cargo +nightly fuzz cmin apc` and commit
  it once it represents real soak hours, not before.

## Input format

The input is split on ESC and each piece has a leading `_` and a trailing `\`
stripped, so a seed is what a client writes to the terminal, verbatim. A file
holding several APCs is one session through one parser, which is how chunked
transfers and the never-evicted partial state get reached at all.

Run against these on a machine with no corpus:

    mkdir -p fuzz/corpus/apc
    cargo +nightly fuzz run apc fuzz/corpus/apc fuzz/seeds/apc

The `mkdir` is needed once. `cargo fuzz` creates the default corpus directory
for you only when you name no directories at all; pass them explicitly and
libFuzzer requires every one to exist already.

**Name the corpus directory first and this one second.** libFuzzer writes new
inputs into whichever directory it is given first and treats the rest as
read-only. Passing `fuzz/seeds/apc` alone dumps thousands of machine-generated
files in here and buries the hand-written ones, which is exactly the split this
directory exists to keep.

## Where real payloads come from

Not from `kitten icat`: headless it cannot open a controlling terminal, and
under `script(1)` it refuses because the terminal reports no pixel size. There
is no kitty graphics test corpus in the Debian package either. The two routes
that work are building the payloads from a real image, which is what the
`real-` seeds are, and recording a live client with `shop --record PATH`, which
tees the PTY byte stream through `Pty::set_recorder`.

## Crash seeds

An input that once found a bug stays here forever, and also becomes a file
under `fuzz/regressions/`, which `tests/regressions.rs` replays on stable. None
yet.