# Fuzzing alktunnels: Proposal and Plan

**Status:** adopted — wave-1 complete (`datagram_codec` +
`params_parse` implemented, seeds committed, two 10-min campaigns
clean, two harness-model findings fixed — see §7); wave-2
(`session_pumps`) implemented and campaigning — see §3.3/§7.
Campaigns run via the detached runner (§6) — **never as a foreground
child of an agent session** (§5).
**Date:** 2026-09-28
**Upstream precedent:** `/workspace/@alkdev/alkcall/docs/research/fuzzing.md`
(0.8.0 — 0.8.1 campaign; one real finding: duplicate adopt/open destroying
the live channel, fixed in 0.8.1). Tooling, corpus policy, runner, and the
no-hosted-CI posture are inherited from that doc wholesale — this doc does
not re-litigate them; it scopes them to this crate.

---

## 1. Should this crate be fuzzed?

**Yes — but scoped smaller than alkcall's.** The decision follows from
three lines, all pointing the same way:

1. **alkcall's fuzz doc already assigned this to us.** Its §5
   "non-surfaces (deliberately)" note ends: *the channels layer carries
   opaque `Bytes` and the handler owns sub-stream framing (ADR-035) —
   those downstream parsers are downstream crates' fuzz targets.* Our
   `wire.rs` datagram codec IS that named downstream target. Fuzzing it
   completes alkcall's fuzz scope rather than duplicating it.

2. **We own one hand-rolled parse surface of exactly the covered class.**
   `DatagramReader::feed` (`src/wire.rs:100`) is an incremental
   length-prefix state machine reassembling `[len: u16 BE][payload]`
   frames across arbitrary chunk boundaries — length arithmetic and
   boundary handling, the dominant rust-fuzz trophy-case classes. It is
   sync, pure, allocation-light, and infallible **by contract** (the
   decode direction cannot fail; oversize is rejected at frame time) —
   a fuzz target is how that contract is *demonstrated* rather than
   believed.

3. **The stateful DoS class applies to us directly.** One pre-fuzz
   code-review candidate, the analog of alkcall §6.2-1 (the
   early-arrival key-space): `DatagramHalves.pending`
   (`src/consumer.rs:78`) queues every datagram decoded from a chunk
   beyond the one returned to the caller. A single 16 MiB chunk of
   `[00 00]` pairs = ~8.4 M empty datagrams → ~8.4 M `VecDeque`
   entries (≈ 400+ MiB) from ONE peer chunk — a ~25–50× memory
   amplification riding a bounded channel buffer. Example-based tests
   structurally cannot find this; a byte-sequence target with a
   pending-bytes assertion will.

**The honest caveat** (mirroring alkcall §1): the highest-value alkcall
targets — envelope framing, chunk header, demux, manager — are upstream
and now fuzzed (0.8.1). Our params parsing is serde + registry-side
jsonschema (upstream's `spec_parse` target covers attacker-shaped
schemas compiling at registration). Expected yield here: datagram-codec
pathologies, the pending-queue bound (§1.3), serde/untagged-enum edge
cases in params, and lifecycle invariants in the two-pump shape. That
is worthwhile, not five-targets-worth of new machinery on day one —
hence the two-wave scope in §4. If the first campaigns find nothing,
that is the successful-negative-result posture alkcall's §1 codified:
"we think the codec is robust" becomes a demonstrated property, and the
targets become regression protection for a wire-stable format
(ADR-003).

## 2. Toolchain (inherited, not re-decided)

Identical to alkcall §4: **cargo-fuzz 0.13.2 + `arbitrary` 1.4.x**,
nightly confined to the `fuzz/` subtree via `fuzz/rust-toolchain.toml`,
the crate itself stays stable at MSRV 1.88. AFL optional/deferred;
bolero deferred (same async-friction argument); libafl/honggfuzz/OSS-Fuzz
not adopted. Sanitizer: `--sanitizer=address` with debug assertions
(cargo-fuzz defaults) — no MSAN (no `unsafe` in this crate).

**Layout (the alkcall pattern, load-bearing):**

```
fuzz/
├── Cargo.toml            alktunnels-fuzz (nightly-only bins; own [workspace])
├── rust-toolchain.toml   pins nightly for this subtree only
├── fuzz_targets/         thin fuzz_target! wrappers (3-line each)
│   ├── datagram_codec.rs
│   ├── params_parse.rs
│   └── session_pumps.rs
├── shared/               alktunnels-fuzz-shared — STABLE-toolchain library
│   └── src/…             invariant logic + corpus replay (§3)
├── corpus/<target>/      committed hand-made seeds (§3)
├── gen_fuzz_seeds.py     deterministic seed generator (quiche pattern)
├── run-detached.sh       §6 detached runner (CWD-independent)
└── README.md
```

- **Invariant logic lives in `fuzz/shared/`**, not inline in the target
  binaries — the stable-toolchain corpus replay
  (`cargo test --manifest-path fuzz/shared/Cargo.toml`) runs the SAME
  invariant functions the fuzzer runs, on stable, in the release
  verification checklist. This is CI tier-3's deliverable (alkcall
  §7.2) minus automation; per alkcall §7.9 this repo has no hosted CI
  and will not get one (same gitea posture) — corpus replay as plain
  `cargo test` is the fuzz gate.
- **Root `Cargo.toml` needs the explicit `[workspace]` table**
  (`members = ["."]`, `exclude = ["fuzz"]`) and `"fuzz/"` on the
  publish exclude list — without it cargo auto-discovers `fuzz/shared/`
  into the main workspace and the MSRV toolchain tries to build the
  nightly-consumed dev-deps (the exact failure alkcall hit).
- **Corpus policy:** commit hand-made seeds, gitignore grown corpora
  (quinn/h2 model). Seeds per target: valid frames, truncation at every
  short prefix length, `len = 0` / `len = MAX` / `len = MAX+1`, empty
  datagrams, batching (two frames per chunk), splitting (one frame per
  many chunks), and for params: every substrate value, unknown
  substrate, unknown/missing fields, `listen: 0`, malformed reply
  shapes, untagged cross-shape targets, deep/invalid JSON.

## 3. Invariants by target

### 3.1 `datagram_codec` (wave 1)

Input: raw `&[u8]` (and in the shared logic, chunk-slice parameter
arbitrary). Drives `DatagramReader::feed` + `frame_datagram`
(`src/wire.rs`). Invariants:

- **no-panic on any byte sequence** (the baseline; the one
  `unreachable!` in `feed` is a structural invariant of the state
  machine — the target is how it stays true).
- **infallibility**: `feed` never errors (contract — oversize is
  rejected at frame time; the decode direction is infallible by
  design, `src/wire.rs` docs).
- **datagram-size bound**: every yielded datagram is
  `<= MAX_DATAGRAM_LEN` (u16 frame field makes this structural — the
  target pins it against future refactors).
- **no partial yields**: a datagram completes only when exactly
  `declared` payload bytes are buffered (`is_mid_datagram` observable
  consistency); `feed(&[])` never yields anything and never clears
  mid-datagram state.
- **round-trip**: `feed(frame_datagram(x)) == [x]` for any x; the
  reverse direction `write(feed-parse(x))` re-frames to the same
  frame for any well-framed input.
- **F-2 sentinel layering**: `len == 0` is a legal empty datagram,
  never EOF; the codec never emits zero-length datagrams for non-empty
  frames and never treats an empty datagram as stream end.
- **consumption accounting**: re-framing all consumed bytes and
  feeding the byte-level remainder yields the same datagram stream
  (splitting a feed at any boundary is transparent).
- **oversize frame rejection**: `frame_datagram` errors iff payload >
  `MAX_DATAGRAM_LEN`, echoing the sizes.
- **pending-queue bound (the §1.3 finding-class assertion)**: total
  bytes retained across `buf` + `current` + `pending` after a feed is
  bounded by the fed chunk size plus the one in-flight frame —
  an adversarial peer chunk cannot force unbounded queue growth in
  the decoder state. (NOTE: this is the *decoder-state* bound; the
  consumer-side `DatagramHalves.pending` backlog between chunk-read
  and `recv_datagram` pulls is a session-shape question tracked in
  §4/§8 — the wave-2 stateful target, or a code fix if the bound is
  judged unacceptable. The fuzzer documents the amplification factor;
  the remediation decision is ours. **Wave-2 resolution (§3.3):** the
  session-shape backlog is now an asserted invariant — the harness's
  per-op drain holds the pending queue to the routed-batch remainder
  (≤ one chunk's worth of batched datagrams, drained by
  `recv_datagram` pulls), so the amplification question is bounded
  by construction + assertion rather than remediated; the
  `datagram_backlog()` diagnostic exposes the live count.)

### 3.2 `params_parse` (wave 1)

Input: raw bytes → `serde_json` (with alkcall's bounded
`arbitrary_value` approach — depth/width-capped `Value` generation) →
`TunnelParams` / `TunnelDirectParams` / `TunnelForwardedParams` /
`SubstrateAddr` deserialization + `parse_listen_reply` /
`listen_reply_fields` (`src/params.rs`). Invariants:

- **no-panic on any JSON-shaped input** (untagged-enum serde dispatch,
  `deny_unknown_fields`, the `positive_u32` pin).
- **clean failure only**: parse failures are `Err`, never panics;
  `parse_listen_reply` returns `TunnelError::MalformedReply` on
  malformed shapes.
- **round-trip for valid params**: `from_json(to_json(p)) == p` for
  constructed params of every substrate.
- **deny-unknown posture**: unknown top-level fields reject;
  untagged-variant leniency (extra fields inside a `SubstrateAddr`
  variant) is the documented asymmetry — asserted, not "fixed".
- **the `listen: 0` pin**: zero rejects at serde level.
- **projection agreement**: `listen_reply_fields` yields both-`Some`
  iff `parse_listen_reply` is `Ok`; it never panics and never refuses
  construction (the lenient view projects malformed to both-`None`).
- **establishment-reason surface**: `establishment_reason` never
  panics on arbitrary `ChannelOpenError` shapes.

### 3.3 `session_pumps` (wave 2)

Input: op sequences (`#[derive(Arbitrary)]` `SessionSequence` — the
`manager_routing` pattern) over one live channels stack per exec:
MuxRunner → raw chunk stream → the real `run_demux_loop_for_client`
demux → `ChannelManager` per side (producer Connect / consumer
Accept over one duplex transport — the reverse POC's topology). Ops:
`Route` (producer→consumer framed datagrams / raw stream bytes via
`route_payload`), `AdoptDatagram` / `AdoptStream` (the
`TunnelSession` data-plane mirrors — codec reader + `pending`, and
`pump_bidi` against in-process peer halves), `Pump` (peer→channel;
`len == 0` drops the p2c source — the EOF path), `Teardown`,
`ClearAll`. Invariants:

- **no-panic / no-wedge on any op sequence** (the baseline; the
  harness's 5 s reconcile bound turns a wedged pump into a finding,
  and §5's `-timeout=25` fork containment is the outer net).
- **two-pump shutdown-on-completion (convention 8)**: after the p2c
  source drops, the pump's channel-side shutdown must propagate and
  the pump must complete once the teardown EOFs the c2p source —
  pinned by the `reconcile` join with the 5 s bound.
- **lossless p2c copy**: the pump's `p2c` count equals exactly what
  the harness pushed into the peer half (copy never truncates).
- **EOF-sentinel teardown semantics**: after a sentinel (teardown /
  `clear_all`), the reassembled stream drains its queue before
  reporting EOF — every routed datagram consumable, nothing lost;
  the consumer map empties; the codec's `len == 0` sentinel layering
  holds at the session layer (a routed empty datagram is data; the
  channels EOF is a separate mechanism).
- **FIFO reconciliation**: every complete frame routed through the
  real demux path arrives as exactly one datagram of the declared
  length, in order (the model walks the framing as the codec does —
  the wave-1 F-2 walk, reused at the session layer).
- **pending-queue bound (the §1.3 finding-class assertion)**: the
  session-shape `DatagramHalves.pending` backlog never exceeds the
  unrouted remainder — i.e. the backlog holds only datagrams decoded
  from routed chunks beyond the ones consumed; with the harness's
  per-op drain the queue returns to zero after every op, so an
  amplification factor > 1× chunk size would trip the assert. (The
  wave-1 decoder-state bound re-asserted per op alongside.)
- **monotonicity**: the manager's early-arrival / dropped counters
  survive `clear_all` (the alkcall §7.7 pattern), and the consumer
  map empties on the transport-EOF path.

Bounds: 128 ops, ≤ 512-byte payloads (generator-clamped; the codec's
`MAX_DATAGRAM_LEN` stays the wire bound). Even-id masking (ADR-047
§5 — the consumer is the Accept side; the producer allocates even).

## 4. Scope: two waves

**Wave 1 (complete):** the two targets above. Both drive already-
`pub` APIs — no `#[cfg(fuzzing)]` exposure needed (matching alkcall's
experience where none of five targets needed it).

**Wave 2 (this session):** `session_pumps`, the stateful op-sequence
target over the two-pump tunnel shape in the alkcall `manager_routing`
style (`#[derive(Arbitrary)]` op enum; live mux + demux runners; the
alkcall harness lessons applied: even-id masking, drained-state
asserts). Drives: the `TunnelSession` data-plane shapes (the datagram
codec plane + the `pump_bidi` stream plane) over a REAL channels
stack — the two-pump shutdown-on-completion contract (AGENTS.md
convention 8), the EOF-sentinel teardown semantics, and the §1.3
backlog bound as byte-accounting invariants (§3.3). The
`forwarded_routing` correlation target stays deferred until the
assembly-side correlation registry (ADR-008 §3, assembly
bookkeeping) grows into this crate.

Sequencing mirrors alkcall §7.4: init + wave-1 targets → 10–30 min
campaigns per target via the detached runner → fix anything found →
wave 2 (`session_pumps`) → further targets when justified.

## 5. Operational isolation: campaigns never share fate with the agent session

**This is an environment constraint, not a nice-to-have** (upstream
doc §7.6, adopted verbatim as policy here). Agent sessions (opencode)
run fuzzer builds/campaigns through a bash tool that spawns the fuzzer
as a **child of the session's own process tree and cgroup**. A fuzz
run is precisely the workload shape that kills its own host:

- **OOM-killer shared fate**: the target's worst case IS unbounded
  allocation. If libFuzzer's soft RSS guard loses the race with the
  kernel, the OOM killer fires — and it picks the largest-RSS process
  in the cgroup, which can be the opencode server hosting the session.
  That is *recoverable* (sessions are recorded in a DB) but hugely
  derailing — the session's live environment access dies mid-task.
  An OOM in a fuzz target must cost the fuzzer, never the session.
- **Fork bombs / CPU saturation**: `-fork=N` workers; a runaway
  campaign starves the session host.
- **Wedged targets**: a deadlock in an async harness would hang a
  foreground bash call forever.

Three layers of defense, cheapest first — **all mandatory**:

1. **libFuzzer soft limits (always on)**: `-rss_limit_mb=2048`
   `-malloc_limit_mb=2048` make libFuzzer exit cleanly (artifact
   recorded) before the kernel gets involved. Note the RSS limit is
   *soft* (polls `/proc/self/statm`); a fast huge allocation can beat
   it — that is what layers 2–3 are for. Never `ulimit -v` with ASAN
   (it reserves terabytes of virtual address space); the ASAN-safe
   hard-limit recipe is `-fork=1`.
2. **Fork mode as blast-radius containment (default)**: `-fork=1`
   (or a small number) runs each input in a short-lived child — a
   crash/timeout/OOM/leak kills only that child; the harness survives,
   records the artifact, keeps fuzzing. Also the deadlock answer: the
   per-input timeout kills the child, not the session's bash call.
3. **Process detachment from the session tree (MANDATORY for agent-run
   campaigns)**: never run fuzzing as a foreground child of the
   session. The runner script wraps `cargo fuzz run` in `setsid` +
   `nohup` + full redirection to a log file: (a) removes the fuzzer
   from the session's controlling terminal and signal relation, (b)
   survives the session ending, (c) gives the agent a pollable log +
   artifact directory instead of a blocking call. Combined with fork
   mode, an OOM-class finding costs one child process.

**The runner** (`fuzz/run-detached.sh`, CWD-independent — resolves its
own repo root):

```bash
#!/usr/bin/env bash
# Detached fuzzing runner for agent sessions: the campaign never runs
# as a foreground child of the session (an OOM in a target must cost
# the fuzzer, never the agent host), and survives the session ending.
set -euo pipefail
target="${1:?usage: run-detached.sh <target> [extra libfuzzer args...]}"
shift
runtime="${FUZZ_RUNTIME_SECS:-600}"
root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
log_dir="$root/fuzz/artifacts"
mkdir -p "$log_dir"
log="$log_dir/${target}-$(date -u +%Y%m%d-%H%M%S).log"
cd "$root"
setsid nohup cargo fuzz run "$target" -- \
  -fork=1 -rss_limit_mb=2048 -malloc_limit_mb=2048 -timeout=25 \
  -max_total_time="$runtime" "$@" \
  >"$log" 2>&1 < /dev/null &
echo "pid=$! log=$log"
```

**Agent polling protocol** (never `wait` on the detached process from a
tool call — poll instead):

- `tail -n 50 fuzz/artifacts/<target>-*.log` — campaign progress.
- `ls fuzz/artifacts/` — `crash-*` / `oom-*` / `timeout-*` / `leak-*`
  artifacts are the findings.
- `pgrep -f "cargo fuzz run <target>"` — still running?
- One detached campaign per target at a time; log filenames carry the
  UTC timestamp.

**Flags worth pinning beyond the runner defaults**: `-max_len=65536`
on the codec target; `-use_value_profile=1`; a JSON token `-dict` for
the params target (alkcall's `json.dict` transfers as-is).

## 6. No hosted CI

Per alkcall §7.9 — the standing policy applies to this repo identically:
no hosted CI will exist; do not add Actions/Gitea-Actions workflow
files. **Corpus replay is the fuzz gate as plain `cargo test`**:
`cargo test --manifest-path fuzz/shared/Cargo.toml` replays every
committed seed through the invariant functions — add it to the release
verification checklist (AGENTS.md). Campaigns run manually via the
detached runner (§6) — e.g. before a release, or after touching
`src/wire.rs`, the consumer data planes, or `src/params.rs`.

## 7. Implementation log

- **2026-09-28 — proposal adopted** (this doc). Wave-1 targets
  `datagram_codec` + `params_parse`; wave-2 deferred (§4).
- **2026-09-28 — `alkcall` bumped 0.8.0 → 0.8.1.** Bug-fix release, no
  API/wire change; the fix (duplicate adopt/open no longer destroying
  the live channel) is directly relevant to this crate's
  `TunnelSession::adopt` path — the changelog's "open-op response
  replayed / id re-announced" scenario is our reverse path. Verification:
  full suite (135 passed), clippy, fmt, wasm check (§8 commands).
- **2026-09-28 — wave-1 implemented.** `fuzz/` workspace laid out per
  §2 (nightly-pinned subtree, stable `fuzz/shared` library, runner,
  dict, generator); `datagram_codec` + `params_parse` targets over
  already-`pub` APIs — no `#[cfg(fuzzing)]` exposure needed. One new
  public diagnostic: `DatagramReader::retained_bytes()` (the
  decoder-state byte count the §3.1 bound asserts against, in the
  `is_mid_datagram` diagnostic style). Seeds committed: 27 +
  69 generated (fuzz/gen_fuzz_seeds.py) + 1 campaign-found crash
  input promoted to `datagram_codec/seed-900` (see the finding below).
  Stable side: corpus replay green, shared crate clippy/fmt clean;
  main suite untouched and green; `cargo fuzz build` clean.
- **2026-09-28 — first campaign finding: a HARNESS-model bug, not a
  crate bug.** The `datagram_codec` campaign crashed in its first
  minute on input `00 2b 01 00 00 05` (`fuzz/artifacts/datagram_codec/
  crash-e9ba284e…`, exit 77, fork-mode containment worked as
  designed — the harness parent survived and persisted the artifact).
  Analysis: the codec is CORRECT — `00 2b` declares a 43-byte
  datagram; `01 00 00 05` is its in-flight payload; nothing is
  yielded. The invariant that tripped ("an empty datagram must come
  only from a [00 00] length header") was mis-modeled: it counted
  `00 00` byte pairs anywhere in the RAW stream, but a `00 00` pair
  sitting INSIDE a frame's payload region is payload, not a length
  header — exactly the same class as alkcall §7.7's probe (the
  harness claimed `4 + len` when the prefix counts only the body).
  Fix: the count now walks the framing as the decoder does (complete
  frames from the start; the walk stops where the decoder would be
  stuck mid-frame). The crash input is committed as seed-900 and
  replays clean; the campaign relaunched clean.
- **2026-09-28 — second harness finding (caught by corpus replay,
  pre-campaign): `establishment_reason` is a pass-through extractor,
  not a validated table.** The params.rs doc names the pinned reason
  strings, but the upstream implementation (alkcall
  `channels/client.rs` `establishment_reason`) extracts
  `details.reason` AS-IS whenever the code is `channel:open_failed` —
  a made-up reason is surfaced as-is by design, and validation is the
  consumer's job. The harness first asserted a closed set of reason
  strings and corpus replay tripped it on `made_up_reason` before any
  campaign ran. Invariant corrected to assert the extraction shape
  (Some iff code == `channel:open_failed` and reason is a string).
- **2026-09-28 — second harness finding (same replay pass):
  `is_mid_datagram` means a partial DATAGRAM, not buffered header
  bytes.** A dangling 1-byte length prefix at input end is buffered
  header state (no frame in flight, `is_mid_datagram == false`);
  the harness first asserted `true` for that case. Corrected:
  mid-datagram iff the framing walk leaves a remainder ≥ 2 bytes
  (a parsed-but-unfinished payload), not `!= 0`.
- **2026-09-28 — wave-1 campaigns run (10-min detached runs, §6 runner;
  `-fork=1 -rss_limit_mb=2048 -malloc_limit_mb=2048 -timeout=25`;
  codec with `-max_len=65536`, params with `-dict=json.dict
  -use_value_profile=1`). Both exited 0.**
  - `params_parse` — 3.14M execs (~5.3k exec/s), 33 fork jobs,
    `oom/timeout/crash: 0/0/0` throughout. Coverage 2049 edges /
    15.6k features; in-memory corpus 69 committed seeds → 3018
    entries — the serde/untagged-enum shape space was still expanding
    at budget end, so longer campaigns keep paying here.
  - `datagram_codec` (post-harness-fix) — 827k execs, 33 fork jobs,
    `oom/timeout/crash: 0/0/0` throughout. Coverage saturated at 221
    edges (ft 1198) — the 2-byte-header state machine is fully
    enumerated, matching alkcall §7.7's `chunk_header` saturation
    profile. Exec/s reads low (~400) because each exec replays the
    input through a ~35-feed 3-byte-sliced sequence alongside the
    whole-input feed; the state space is small and exhausted early.
  - The pre-fix `datagram_codec` run (the §7 finding above) crashed at
    job 4 and exited 77; fork-mode containment behaved as designed —
    the harness survived, persisted the artifact, and the run wrapped
    up. That artifact is the promoted seed-900.
  - Grown corpora (3018 params entries) were **not** merged into the
    committed seeds — per the §2 policy, grown corpora stay
    gitignored.
  - Operational note for future sessions: `cargo fuzz run` returns
    before its last fork-mode children fully exit; a `pkill -f
    "cargo fuzz run <target>"` followed immediately by another
    `pgrep` of the same pattern can wedge a bash tool call on its own
    process match — prefer `pgrep -af` to LIST, kill by explicit pid
    from the runner's echoed `pid=`, and never pattern-kill-and-recheck
    in one call.
- **NO crate bugs found by wave 1.** The two findings this session
  were both harness-model defects (§7 above), each invisible to
  example-based review and caught by fuzzing/replay — the alkcall §7.7
  "fuzzer as a harness-checker" pattern, confirmed. The §1.3
  decoder-state bound held everywhere: `retained_bytes()` never
  exceeded fed + one frame on any adversarial input. The session-shape
  `DatagramHalves.pending` amplification remains a documented
  §1.3/§4 note (wave-2's motivation), not a campaign finding — the
  wave-1 targets assert the decoder, not the session pump.
- **2026-09-28 — wave-2 implemented: `session_pumps` (the stateful
  two-pump/EOF-sentinel target, §3.3).** The harness mirrors
  `TunnelSession`'s data-plane shapes over one REAL channels stack
  per exec (MuxRunner → raw chunk stream → the real
  `run_demux_loop_for_client` demux → `ChannelManager` per side over
  one duplex transport; producer Connect / consumer Accept — the
  reverse POC's topology). Ops: Route/AdoptDatagram/AdoptStream/
  Pump/Teardown/ClearAll; invariants per §3.3. One diagnostic
  addition to the crate: `TunnelSession::datagram_backlog()` (the
  `DatagramHalves.pending` count the §3.3 bound asserts against, in
  the `retained_bytes()` diagnostic style) + a suite test pinning
  its rest states. Seeds: 8 committed (deterministic decode-scan
  hex patterns, the `manager_routing` precedent — arbitrary ships
  no encoder) + 2 in-source semantic fixtures (the §1.3 batched-
  backlog probe; the W4 half-close shape). Two harness-model
  findings caught by corpus replay pre-campaign:
  - **the p2c-EOF pump-join wedge is the DESIGNED half-close
    shape, not a wedge.** The first `reconcile` draft awaited the
    pump after dropping only the p2c source — but the c2p pump's
    source (the channel read half) EOFs only via teardown, so the
    join legitimately blocked (the 5 s bound tripped). `pump_bidi`
    completes when BOTH pumps finish; the half-close contract is
    that the p2c completion shuts the channel side down (the
    observable), and the pump completes once the c2p source EOFs
    too. The harness now models exactly that: drop p2c source →
    teardown the entry → join with the 5 s bound. (The alkcall §7.7
    harness-checker pattern again — the fuzzer harness's first
    campaign-found crash in wave 1 and this replay catch are both
    harness-model defects, not crate bugs.)
  - **the stream-plane c2p accounting is asynchronous** — the pump
    writes channel→peer into the peer duplex while a far-end reader
    task counts; the reconcile join (after the pump completes) is
    when the count is final. First draft read it early. Fixed by
    reading after the reader task's join.
- **2026-09-28 — third harness finding (campaign-found, fork-mode
  containment as designed): duplicate adopt is a LEGAL manager
  outcome, not a finding.** The first campaign crashed at ~49 s on
  `AdoptDatagram { channel_id: 0 }` after the id had already been
  adopted — `ChannelExists` is the manager's documented
  id-collision error, and my adopt arms treated every error as a
  finding. Fix: both adopt arms model the documented error table
  (`ChannelExists` / `TooManyChannels` are no-ops, exactly the
  alkcall `manager_routing` harness's treatment). The crash input
  is committed as seed-900 and replays clean; the campaign
  relaunched clean.
- **2026-09-28 — fourth harness finding (second campaign): the
  harness modeled the producer→consumer path through the WRONG
  primitive.** The second campaign crashed at ~5 s on `Route`:
  raw-id addressing (`even_id` masked arbitrary ids; collisions +
  an `UnknownChannel`-class state the model didn't track), `len ==
  0` raw routes doubling as EOF sentinels mid-model, and — the
  structural one — `route_payload` was used as the producer's
  forward write. `route_payload` routes into the LOCAL manager's
  channel entry (the demux direction); the producer pump handler
  writes the channel's SEND half (the mux pump frames onto the
  transport). Bytes never reached the consumer. Rewrite (the real
  protocol shape, matching `manager_routing`'s op-vocabulary
  lesson): producer `Open` (`open_channel` allocates the id, the
  harness holds the send half — the pump handler's write side), 
  session-INDEX addressing (no masking, no collisions), `Adopt`
  consumes the producer-allocated id (the early-arrival drain is
  the real adopt-race path), `Route` writes the producer send half
  (the real wire path: mux pump → transport → consumer demux →
  reassembly), `Pull` (the `recv_datagram` pull pops the backlog +
  the model), and a STATEFUL framing model (partial frames persist
  across ops — the wave-1 walk carried across ops). EOF sentinels
  now arise only from teardown/sender-drop (the real mechanisms),
  never from `len == 0` routes (F-2: a routed empty datagram is
  DATA). All committed session_pumps seeds regenerated by the
  rewrite (the old hex patterns decode against the new op enum);
  the semantic fixtures re-pinned. Verification of the fix: the
  campaign's 0-exec crash went away; batched frames now reconcile
  FIFO through the real two-manager stack.
- **2026-09-28 — fifth + sixth harness findings (third campaign's
  first minutes): the two ClearAll modeling defects.** (5) A
  double-adopt of a live session panicked the harness's own guard —
  but a re-adopt of a LIVE id is the manager's documented
  `ChannelExists` outcome (a legal no-op; alkcall 0.8.1's
  insert-replace fix leaves the live entry intact). Modeled as a
  no-op. (6) A `ClearAll` followed by `Route` on the same session
  tripped the backlog reconciliation — the harness retired only the
  sessions whose ids appeared in `clear_all`'s RETURN value, but
  that value is the OPENER-LEDGER records (ADR-047 §7): adopted
  channels carry no ledger entry, so the set is empty while the map
  itself empties. The alkcall §7.7 lesson ("`drained.len() ==
  open_count()` is not an invariant"), learned again at this
  crate's layer — the map-empties assert is the ground truth; the
  harness now retires EVERY session on `ClearAll`.
- **2026-09-28 — wave-2 campaign run (10-min detached run, §6
  runner; `-fork=1 -rss_limit_mb=2048 -malloc_limit_mb=2048
  -timeout=25 -max_len=4096 -use_value_profile=1`): exited 0.**
  228,676 execs (~380 exec/s; each exec replays up to 128 ops on a
  live two-manager stack with real mux/demux tasks), 32 fork jobs,
  `oom/timeout/crash: 0/0/0` throughout. Coverage 3427 edges /
  17,529 features / 1184 in-memory corpus entries and STILL
  EXPANDING at budget end (the op-interleaving space is much larger
  than the parser targets') — longer campaigns keep paying. The
  two-pump contract held across every adversarial sequence: no
  wedged pump (the 5 s reconcile join), no lost datagram (the
  FIFO/backlog reconciliation), no premature EOF (the sentinel
  layering). The §1.3 backlog bound held everywhere: the
  `DatagramHalves.pending` queue never exceeded the
  routed-but-unpulled remainder.
- **NO crate bugs found by wave 2.** All six findings across waves
  1–2 were harness-model defects (four this session), each
  invisible to example-based review and caught by fuzzing/replay —
  the alkcall §7.7 "fuzzer as a harness-checker" pattern,
  re-confirmed. The stateful thesis is validated from the harness
  side: the harness defects themselves (double-adopt semantics, the
  clear_all ledger/map distinction, the route_payload direction)
  are exactly the interleaving-shape mistakes the alkcall §7.8
  campaigns caught in their own drivers.
- (progress appended as implementation proceeds — see git log)

## 8. Verification commands

```bash
cargo test                                    # main suite (stable)
cargo test --manifest-path fuzz/shared/Cargo.toml   # corpus replay (fuzz gate)
cargo fuzz build                              # in fuzz/ (nightly, ASAN)
fuzz/run-detached.sh <target>                 # campaigns (never foreground)
cargo clippy --all-targets -- -D warnings
cargo fmt --check
cargo clippy --manifest-path fuzz/shared/Cargo.toml --all-targets -- -D warnings
cargo fmt --manifest-path fuzz/shared/Cargo.toml --check
cargo check --target wasm32-unknown-unknown   # default crate stays wasm-clean
```

Campaign flags per target: `datagram_codec -max_len=65536`;
`params_parse -dict=json.dict -use_value_profile=1`;
`session_pumps -max_len=4096 -use_value_profile=1`.

## 9. References

- Upstream campaign + operational model (authoritative for tooling,
  runner, corpus policy, no-CI posture):
  `/workspace/@alkdev/alkcall/docs/research/fuzzing.md`
- alkcall 0.8.1 changelog — the finding our adopt path is exposed to
- This crate: ADR-003 (codec framing), ADR-002 (ALPN), ADR-007/008
  (direct/forwarded ops), `docs/architecture/wire.md`
- External: RUSTSEC-2026-0037 (quinn-proto — the maintainers'
  fuzzing-coverage statement), rust-fuzz trophy case, cargo-fuzz Rust
  Fuzz Book (all linked from the upstream doc's §9)