alkdev/alkcall
6
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

base: alkdev/alkcall:v0.7.1
alkdev/alkcall:main
alkdev/alkcall:v0.8.1 alkdev/alkcall:v0.8.0 alkdev/alkcall:v0.7.1 alkdev/alkcall:v0.7.0 alkdev/alkcall:v0.6.0 alkdev/alkcall:v0.5.0 alkdev/alkcall:v0.4.1 alkdev/alkcall:v0.4.0 alkdev/alkcall:v0.3.1 alkdev/alkcall:v0.3.0 alkdev/alkcall:v0.2.0 alkdev/alkcall:v0.1.1
..
compare: alkdev/alkcall:main
alkdev/alkcall:main
alkdev/alkcall:v0.8.1 alkdev/alkcall:v0.8.0 alkdev/alkcall:v0.7.1 alkdev/alkcall:v0.7.0 alkdev/alkcall:v0.6.0 alkdev/alkcall:v0.5.0 alkdev/alkcall:v0.4.1 alkdev/alkcall:v0.4.0 alkdev/alkcall:v0.3.1 alkdev/alkcall:v0.3.0 alkdev/alkcall:v0.2.0 alkdev/alkcall:v0.1.1
18 Commits
v0.7.1 .. main
Author SHA1 Message Date
glm-5.3-flash 3bda29c419 chore(release): 0.8.1 — duplicate adopt/open fix + fuzz harness bookkeeping 
- version 0.8.0 -> 0.8.1 (bug-fix release; semver-checks 196 pass vs 0.8.0)
- CHANGELOG 0.8.1: the manager_routing-found duplicate adopt/open fix,
  the fuzz harness, and the verification summary
- publish exclude gains docs/research/ (internal research notes;
  fuzz/ was already excluded — package verified clean of both)
- fuzzing.md §7.9: standing no-hosted-CI policy — corpus replay is the
  release-verification fuzz gate; campaigns manual via the detached
  runner; OSS-Fuzz out; no workflow files in this repo
- AGENTS.md: corpus replay added to the verification checklist
- lockfiles: alkcall 0.8.1 (root + fuzz)

Verification: 684 tests; clippy -D warnings (main, wasm, fuzz/shared);
fmt clean; doc clean; wasm32-unknown-unknown check+clippy clean;
semver-checks 196 pass; publish --dry-run 116 files (no fuzz/research/
reviews/sdd/AGENTS in the tarball); fuzz corpus replay 5/5 green
 2026-09-28 06:56:11 +00:00
glm-5.3-flash 77f7006e2e docs(research): fuzzing steps 1-3 complete; 10-min campaigns clean on all five targets 
\u00a77.8 campaign results: manager_routing 1.06M execs (exact-counter and
parked-bytes invariants held across every adversarial sequence),
envelope_semantic 2.44M execs (coverage saturated, all event kinds
round-trip), spec_parse 10.8M execs (registry compiled every
attacker-shaped schema or rejected cleanly). All exited 0, zero
artifacts.

Also records the two harness-model defects the fuzzer caught in the
interim (per-receiver EOF-sentinel latch; odd/even Adopt range per
ADR-047 \u00a75). Doc-only + harness fixes; no crate changes.
 2026-09-27 23:52:45 +00:00
glm-5.3-flash a1f257757b fix(channels): duplicate adopt/open must not destroy the live channel; fuzz targets 3-5 
Found by the manager_routing fuzz target (docs/research/fuzzing.md \u00a77.8):

- ChannelManager::open_channel / adopt_channel used
  HashMap::insert(...).is_some() as a collision check \u2014 insert REPLACES
  the existing entry, so a duplicate adopt/open installed the new state,
  dropped the live channel's demux_sender (spurious EOF to its readers,
  subsequently routed chunks lost) and still returned
  Err(ChannelExists). Fixed with contains_key pre-check; map untouched
  on collision. Regression tests: adopt_channel_duplicate_id_leaves_
  live_channel_intact, open_channel_duplicate_id_leaves_live_channel_
  intact.

New fuzz targets (\u00a77.4 step 3):
- manager_routing: Arbitrary op sequences over ChannelManager; exact
  counter models (parked/dropped must equal the manager's monotonic
  counters), parked-bytes bound per \u00a76.2-1, clear_all ledger-vs-map
  semantics, drainer-byte reconciliation (lossless routing)
- envelope_semantic: constructors -> serde -> write_frame/read_frame
  structural round-trip; event-type constants; call.error parse-back
- spec_parse: OpRegisterRequest::from_json -> rebuild -> registry
  registration (attacker schemas compile at register, CF-003)
- fuzz/shared/src/arbitrary_value.rs: bounded Arbitrary for
  serde_json::Value; 20 spec_parse + 4 manager_routing seeds
- corpus replay for the new targets in fuzz/shared tests

Verification: cargo test 684 passed (682 + 2 regression); clippy
-D warnings clean (main + fuzz/shared); fmt clean (main + fuzz);
cargo fuzz build clean; 20 s smoke on all three new targets clean
(manager_routing 79k, envelope_semantic 141k, spec_parse 517k runs);
crash input replays clean post-fix
 2026-09-27 23:19:18 +00:00
glm-5.3-flash c211c163fd docs(research): fuzzing step 1 complete — campaigns ran clean (fuzzing.md \u00a77.7) 
chunk_header: saturated (203.9M execs, ~350k exec/s, 33 fork jobs clean);
envelope_frame: 2119 edges/1664 corpus entries, still growing at budget
end, 7.08M execs, 33 fork jobs clean. No crash/OOM/timeout artifacts in
either 10-min detached campaign; exit 0 both. Grown corpus not merged
(per \u00a77.1 corpus policy). Doc-only change.
 2026-09-27 21:27:58 +00:00
glm-5.3-flash 80a37e94ab feat(fuzz): cargo-fuzz workspace, chunk_header + envelope_frame targets (fuzzing.md step 1) 
- fuzz/ workspace (nightly-pinned via rust-toolchain.toml, excluded from
  the main workspace and the published package): chunk_header and
  envelope_frame targets per fuzzing.md \u00a77.1
- invariant logic in fuzz/shared (stable-toolchain crate): committed
  corpus replay as plain cargo test (quinn CI pattern, \u00a77.2 tier 3)
- envelope target adds FrameError shape-partition asserts, exact
  consumption accounting, structural write_frame round-trip, serde
  key-contract, and a trailing-byte probe (prefix counts body only)
- chunk_header target adds round-trip identity, TooLarge/short error
  shape, is_eof, 8-byte consumption, input-never-mutated
- committed seed corpora: 245 deterministic seeds via
  fuzz/gen_fuzz_seeds.py (truncations, len=0/MAX+1/u32::MAX, channel 0,
  invalid UTF-8, deep nesting); grown corpora + artifacts gitignored
- fuzz/run-detached.sh: \u00a77.6 detached runner (setsid+nohup+log, fork
  mode, rss/malloc limits) \u2014 campaigns never share fate with a session
- fuzz/json.dict; README; research doc \u00a77.7 records step-1 status

Verification: cargo fuzz build clean; stable side green (cargo test 682
passed, clippy -D warnings, fmt --check incl. fuzz/shared); corpus
replay 245 seeds green; detached 10-min campaigns on both targets
completed with zero crashes/OOMs/timeouts
 2026-09-27 21:14:35 +00:00
glm-5.3-flash 7ae0315f19 docs(research): fuzzing must not share fate with agent sessions (detached runner) 
- OOM in a fuzz target must cost the fuzzer, never the opencode host
- three defense layers: soft rss/malloc limits, fork-mode blast radius,
  setsid+nohup detachment with log-file polling (fuzz/run-detached.sh)
- no ulimit -v with ASAN; corpus replay + CI flag parity notes
- sequencing and summary updated to make the detached runner mandatory
 2026-09-27 20:13:35 +00:00
glm-5.3-flash 791eea7298 docs(research): fuzzing evaluation — adopt cargo-fuzz, five targets, two-tier CI 
- web survey of 2025/2026 Rust fuzzing tooling (cargo-fuzz/afl/bolero/libafl)
- practice survey: rustls, quinn, quiche, h2, prost, s2n-quic, yamux/libp2p
- parse-surface inventory of this crate (both wire formats, dispatch, manager)
- pre-fuzz code-review findings: unbounded early-arrival key-space
  (manager.rs early_arrivals), unbounded spawned-JoinHandle growth
  (dispatch.rs), 64 MiB pre-payload allocation window, O(n^2) abort cascade
- recommendation: cargo-fuzz + arbitrary, 5 targets (chunk_header,
  envelope_frame, manager_routing, envelope_semantic, spec_parse),
  committed seeds only, 10s/target smoke CI, OSS-Fuzz after stabilization
 2026-09-27 20:01:29 +00:00
glm-5.3-flash 7bb76cd2b5 docs: fold [Unreleased] into [0.8.0] for publish 
The post-landing-audit fixes (relay plan Drop guard, empty-ALPN
guards, reserved-reply-key message/log corrections) and the review
009 coverage work were recorded under [Unreleased] after the 0.8.0
section was written, but 0.8.0 has not shipped — folded both into
the release entry with proper Added/Changed/Fixed/Testing/Verified
ordering. Verified test count corrected 669 → 682 (the audit and
coverage commits added 13 tests after that count was recorded).
Bottom link refs gained the missing [0.8.0] and [0.7.1] entries.

Verification: cargo test 682 passed; clippy --all-targets -D
warnings clean; fmt --check clean; doc --no-deps clean; semver-checks
(no update required, 0.7.1 baseline); wasm32 check + clippy clean;
test --all-features 699 passed; publish --dry-run packaged and
verified clean.
 2026-09-18 13:23:56 +00:00
glm-5.3-flash 9620ee7b2a test(review 009): all seven coverage findings; errata on three as-filed claims 
Review 009's coverage debt in full — the paths the review-008 gates
never walk. No wire or API changes.

- C-1: pin the plain-bundle install-failure arm (un-compilable
  input_schema; the as-filed duplicate-name route does not fail
  registration) — the install task ends before the dispatch loop,
  channel 0 never dispatches. ADR-051 §5 gains the loud-install
  coverage note: relay-openable + plain-bundle arms pinned,
  generic-ops + bootstrap-discovery arms documented as
  best-effort-loud (crate-internal specs compile by construction).
- C-2: the HubLegImports filter — filtered closure path + only
  partition unit-tested (errata: only was already pinned at filing);
  the empty-stash e2e gate (generic ops + discovery only, dropped
  ops resolve NOT_FOUND).
- C-3: the batch-form reserved-reply-key rejection pinned (reason
  handler_error, teardown, ledger decrement, no pump spawn).
- C-4: open_channel_with_reply's failure path pinned e2e (the typed
  error carries the channel:open_failed code + details reason/message).
- C-5: both byte-identical claims golden-pinned — the no-fields reply
  against {"channel_id": 2} and the standard-shape wire payload
  against the full 9-key literal.
- C-6: derivation edge shapes pinned — channels//sub, channels//direct,
  channels → None; the 4-segment strict superset annotated as the
  pre-amendment behavior change (errata: actual is Some("x/sub"), the
  multi-segment-ALPN rule, not the as-filed Some("alk/x/sub")).
- C-7: builder overwrite pinned last-win (single + batch) with the
  doc sentence on with_reply_field.

Verification: 682 tests pass, clippy -D warnings clean, fmt clean,
doc clean, wasm32 check clean.

File: docs/reviews/009 (resolved; errata marked per finding)
 2026-09-18 08:02:13 +00:00
glm-5.3-flash 54c2a3f941 fix(review-008 audit): adopted-entry drop guard; explicit-ALPN guards; review 009 
Post-landing audit of the 0.7.1 -> 0.8.0 remediation diff: two
hardening guards, one rejection-posture fix, two log/message
corrections, and the deferred coverage debt filed as review 009.

- RelayPlan owns the producer-leg ChannelManager and reclaims the
  adopted spoke channel_id via a Drop guard (replaces the pump
  handler's post-pump_bidi explicit reclaim). Closes the leak
  windows the pump's normal path cannot reach: the wrapper's
  establishment bound expiring after the adopt, and the pump
  handler's early-return arms (plan absent, downcast failure,
  try_unwrap failure, accept_bi failure). The send-half drop still
  EOFs the spoke leg via the mux pump's implicit-EOF sentinel, so
  the spoke-side cascade is unchanged. ADR-051 §6 documents the
  closed post-adopt window (the pre-adopt §6 window and the
  inside-adopt_channel cancellation point stay as documented).
- rebuild_spec_for trims and rejects empty/whitespace
  channel_open_alpn strings — an empty explicit string previously
  overrode a sane name-derived ALPN.
- op_name_is_standard_channel_open_shape applies the same
  empty-segment guard as the derivation: channels//sub no longer
  serializes boolean-only and then reconstructs unmarked (silent
  stub for a marked op); the explicit string rides instead.
- reserved_reply_key_call_error interpolates RESERVED_REPLY_KEY;
  the establisher-bug log fires at warn! (programming error).
- Regression tests: the plan drop guard, the empty-ALPN fallback,
  the empty-segment shape check (672 tests, 3 new).
- CHANGELOG [Unreleased] entry for the audit fixes.
- docs/reviews/009 — the audit's deferred test-coverage gaps
  (template failure arms, filtered/only, batch reserved key,
  wire failure path, golden pins, derivation edge shapes, builder
  overwrite semantics), each with the test to add and gates.

Verification: cargo test 672 passed; clippy --all-targets -D
warnings clean; fmt --check clean; doc --no-deps clean; wasm32
check clean.
 2026-09-18 06:19:56 +00:00
glm-5.3-flash 50182d7298 feat(review 008 Unit 3c): the gate-2 e2e harness; 0.8.0 release bookkeeping 
- src/channels/gate2_tests.rs (ADR-051 gates 6/7, review 008 gate 2):
  the full consumer -> hub (HubLegTemplate) -> spoke relay e2e —
  the open resolves with the hub-allocated channel_id, `bound`
  survives the relay, data flows both directions with a fake 8-byte
  chunk header riding verbatim (the hub never parses the data plane,
  ADR-034/035), spoke-side close cascades to clean reclaim on both
  legs; hub-side disconnect (the consumer's duplex end dropped via a
  killable transport proxy) tears down both legs with the ledger
  decremented; the mid-establishment window (ADR-051 §6) pinned with
  its two reclaim signals — the consumer leg reclaims at its own
  transport EOF, the spoke channel (allocated before the establisher
  replied) is the honest residual, reclaimed when the spoke-leg
  transport ends; the channels/tty/sub standard-shape companion pins
  no derivation regression.
- src/channels/relay.rs: the relay's adopted producer-leg channel
  entry now reclaims when the relayed pump completes (teardown after
  pump_bidi) — the consumer-leg wrapper's teardown cannot see the
  producer leg's manager; the RelayPlan carries the spoke id for the
  reclaim.
- Release bookkeeping: 0.7.1 -> 0.8.0, the CHANGELOG entry covering
  Units 1-3 (Establishment reply projection, open_channel_with_reply,
  flavor-form discovery derivation, ChannelRelay, HubLegTemplate,
  gate-2 harness); review 008 Status -> Resolved with the U-1/U-2
  commit refs and the 955->945 errata note; ADR-051 Status ->
  all units landed + the §6 mid-establishment residual expanded to
  the two-reclaim-signal shape the gate pins; the stale "0.7.2"
  version mentions in ADR-047/049 corrected to 0.8.0 (the units land
  unreleased).

Verification: cargo test 669 passed / 0 failed; clippy --all-targets
-- -D warnings clean; fmt --check clean; cargo doc --no-deps clean;
cargo check + clippy on wasm32-unknown-unknown clean;
cargo publish --dry-run --allow-dirty passed.
 2026-09-18 05:15:29 +00:00
glm-5.3-flash 4e52bd496c feat(review 008 Unit 3b): the hub-leg install template (ADR-051 §5) 
- src/channels/hub_leg.rs: HubLegImports (the Clone discover/stash,
  bundles split by the channel_open marker, with the per-consumer
  filter) and HubLegTemplate (the hub-leg install hook: per-connection
  fork + generic channel ops + plain bundles as-is + marked specs via
  ChannelRelay::register_relay_openable + bootstrap discovery closed
  over the fork (review 004 F-06) + serving-identity resolution
  (CF-005) + the single-stream dispatch loop).
- The loud assembly posture holds at install: a Pub-typed (or
  unregistrable) marked spec ends the leg's install task — channel 0
  never dispatches, never a silent stub (ADR-051 §6).
- Assembly rule surfaced by the gate e2e: from_call discovers the
  spoke's bootstrap discovery ops like any plain op; the template
  skips BOOTSTRAP_DISCOVERY_OPS (new pub const, discovery.rs) when
  re-registering plain bundles — the template's own install, closed
  over the fork, supersedes the imported copies.
- Gate tests (7): stash split + filter, the full template e2e
  (services/list shows the re-exposed ops, a plain imported op
  round-trips through the hub, the marked op opens through the relay
  with bound surviving, data both directions), serving-identity
  precedence (scope-bearing override resolves, scope-less fails
  closed), the loud Pub-typed posture, and the filtered-stash subset
  run (NOT_FOUND for the filtered-out marked op).
- Docs: ADR-051 status (3a + 3b implemented, 3c remains); review 008
  Unit 3b landed note (the bootstrap-op skip rule).

Verification: cargo test (665 passed), clippy --all-targets
-D warnings, fmt --check, doc --no-deps — all clean.
 2026-09-18 03:48:52 +00:00
glm-5.3-flash 90c182039e feat(review 008 Unit 3a): in-tree ChannelRelay (ADR-051, ADR-042 amendment) 
- src/channels/relay.rs: ChannelRelay::register_relay_openable —
  registers a from_call-imported marked spec on a consumer-leg
  channel-0 registry via the full open-op wrapper (translate hop =
  the ADR-049 establisher calling the producer leg with the
  forwarded payload; byte-forward hop = pump_bidi, awaited inline).
  The relay map dissolves (implicit per-channel mapping; ids are
  per-connection), the spoke reply's channel_id is stripped, the
  reply's other fields ride with_reply_fields (bound flows
  end-to-end), reason mapping per ADR-051 §3 (spoke code+message
  preserved; timeout → dial_failed).
- Rejection postures (ADR-051 §6): unmarked and Pub-typed marked
  specs are loud assembly errors.
- Gate tests (9): registration rejections, reason mapping,
  forwarded_for payload shape, the real-wire consumer → hub → spoke
  round trip (bound survives, data both directions, the hub never
  parses the data plane), spoke-failure teardown (ledger
  decremented, no spoke channel leak), and a channels/tty/sub
  standard-shape run pinning no regression.

Verification: cargo test (658 passed), clippy --all-targets
-D warnings, fmt --check, doc --no-deps — all clean.
 2026-09-17 23:27:17 +00:00
glm-5.3-flash 91765446b7 docs(review 008 Unit 3 planning): ADR-051 — in-tree ChannelRelay + hub-leg assembly; plan split into 3a/3b/3c 
Design session outcome for the relay unit. The hub/spoke family (hub
or spoke may relay; the hub re-exposes spoke services by ACL without
binding ports) needs the call-half support too, so the unit's scope
grew beyond the as-pinned sketch and is now three sub-units.

- ADR-051 (new): the relay is the wrapper composition — translate hop
  = the ADR-049 establisher shape, byte-forward hop = pump_bidi per
  ADR-050; the relay holds Arc<CallConnection> + ChannelManager per
  producer leg (not a ChannelClient — take_call_connection's detach
  is wrong for a hub with three CallConnection claimants); the reason
  mapping preserves the spoke's code+message (timeout is the one
  non-1:1 case, mapping to dial_failed); the registration seam is
  two-phase (discover/stash → per-connection fork-register — the
  ADR-047 §4 fork mechanism makes a one-call import impossible); the
  ADR-042 relay map dissolves (implicit per-channel mapping) and
  channel/close needs no translation surface (EOF cascade propagates
  with correct ledger accounting on both legs); Pub-typed marked
  specs are a loud assembly error; establishment bounds compound per
  hop (noted, no fix); the ACL layering note is pinned (the spoke's
  AccessControl sees only the hub identity; forwarded_for is never
  checked).
- ADR-042 amended: the §Scope note is revised (implementation is an
  alkcall export; hub crates compose it) and the two mechanism
  supersessions are recorded — the contract and auth-model rationale
  unchanged.
- ADR-047 amendment 3's forward reference and the README ADR index
  updated (001..051).
- Review 008 remediation plan: Unit 3 split into 3a (ChannelRelay
  component + gates), 3b (hub-leg install template — the call-half
  support), 3c (gate-2 e2e incl. the mid-establishment disconnect
  window); sequencing note updated; adoption note records the
  session's decisions.

Verified: cargo doc --no-deps (markdown-only change).
 2026-09-17 06:47:48 +00:00
glm-5.3-flash 620180d615 feat(review 008 Unit 2): flavor-form open-op ids in discovery (U-1, ADR-047 amendment 3) 
Flavor-form open op ids (channels/tunnel/direct, channels/tunnel/
forwarded — alktunnels ADR-007/008) now survive discovery + the
op/register announce path: the marker reconstructs, so a hub consuming
through discovery wraps the op with relay machinery instead of the
silent plain-forwarding-stub failure.

Per the review-008 plan's combined (b)+(c) shape:

- derive_alpn_from_op_name generalizes from strip-/sub|/pub to
  strip-last-segment (rsplit_once) — a strict superset: standard
  two-suffix shapes derive identically, multi-segment ALPNs survive
  the same way, and the flavor form derives. The boolean marker
  remains the gate (consulted only for marked ops in
  rebuild_spec_for) — a plain op named channels/tty/query is
  unaffected.
- spec_to_json_pub emits channel_open_alpn (the explicit string)
  beside the boolean when the op name is not the standard
  channels/<seg>/(sub|pub) shape; standard shapes stay byte-identical
  to the pre-amendment payload. The advertised operation_spec_schema
  documents the optional ["string","null"] property.
- rebuild_spec_for prefers the explicit string, else boolean →
  generalized derivation. Both wire consumers (from_call import,
  op/register announce) parse through the same parser, so one change
  covers both. A channel_open_alpn without the boolean never marks an
  op (the boolean is the dispatch hint).

Residual ambiguity pinned in the ADR: an ALPN segment colliding with
a flavor name (channels/x/direct → alk/x vs alk/x/direct) is
undecidable from the name alone; the explicit string is the
disambiguator.

Tests (review gates 1 + 3; gate 2 lands with the Unit 3 relay):
- channels/tunnel/direct reconstructs WITH channel_open = alk/tunnel,
  both via the explicit string and via the boolean alone (the
  deployment-skew case: old producer, new consumer)
- standard shapes (channels/tty/sub, multi-segment
  channels/custom/proto/sub) round-trip byte-stable — no new key
- explicit string overrides a colliding derivation; string without
  boolean is ignored
- op/register announced flavor-form spec round-trips with the marker
- derivation unit tests: flavor form, non-op-type suffix not
  special-cased, prior shapes unchanged

Docs: ADR-047 amendment 3 — the convention sentence (mirroring
alktunnels ADR-002 Amendment 1: flavors are new op ids, additive, the
.../sub op is never reused), the wire shape, the preference order,
the residual-ambiguity note, one-way-door timing.

Verification: cargo test 649 passed (12 new); clippy -D warnings
clean; cargo fmt --check clean; cargo doc --no-deps clean.
 2026-09-16 10:34:45 +00:00
glm-5.3-flash 82ddddf986 feat(review 008 Unit 1): establisher reply projection (U-2, ADR-049 amendment 3) 
The establisher can now contribute to the open-op success reply — the
establisher → opener direction amendment 2 left empty. First consumer:
alktunnels ADR-008's bind-first listen establisher, whose observed
OS-chosen bound address rides the reply as an additive `bound` field
(the SOCKS5 BIND reply#1 BND.ADDR fidelity ask).

- Establishment gains reply_fields (private, builder-constructed):
  with_reply_field / with_reply_fields / reply_fields. The map shape
  generalizes beyond `bound` without a fourth amendment; the
  #[non_exhaustive] carrier (amendment 2) makes the extension additive
  — no construction-site break.
- run_open_wrapper merges contributed fields into the success output
  after reserving `channel_id`. The key is wrapper-owned: an
  establisher supplying it fails the open loudly
  (channel:open_failed, reason handler_error, message naming the
  reserved key), tearing the just-allocated channel down — never
  shadowing. Absent fields leave the reply byte-identical to the
  pre-amendment shape (asserted exactly).
- ChannelClient::open_channel_with_reply returns
  (channel_id, reply, send, recv) — the full success output — so
  consumers read `bound` first-class; open_channel delegates and
  discards the fields, signature unchanged.

Tests (all gates from the review + plan):
- projection produces { channel_id, bound } on the wire; no-fields
  replies are byte-identical (establisher and no-establisher shapes)
- reserved-key establisher fails with reason handler_error; channel
  torn down, ledger decremented, pump handler never spawned
- registry-level register_openable_with_establisher projects fields
- e2e over a real channels connection: bound reaches
  open_channel_with_reply; open_channel unchanged against the same
  accept side
- existing establishment tests (establisher-success round-trip,
  plan-flow, no-establisher compat) pass unchanged

Docs: ADR-049 amendment 3 (projection, reservation, read path,
compatibility posture, door type).

Verification: cargo test 637 passed; clippy -D warnings clean;
cargo fmt --check clean; cargo doc --no-deps clean.
 2026-09-16 10:27:12 +00:00
glm-5.3-flash 1bc937c061 docs(review 008): remediation plan — findings verified, three units pinned 
Both findings verified against HEAD 3b36b40 (0.7.1); all citations
check out (one line drift: U-2 reply construction is operations.rs:945,
errata noted rather than silently edited).

Plan decisions recorded above the as-filed option lists:

- U-1 shape: combined (b)+(c) — explicit channel_open_alpn string for
  non-standard shapes; derivation generalized to strip-last-segment,
  gated on the boolean marker. As-filed option (a) is unsound (the
  derivation runs consumer-side; a registration-threaded allowlist has
  no path to rebuild_spec_for).
- U-1 gate 2 escalated to an in-tree relay component (src/channels/
  relay.rs), amending ADR-042's downstream-implementation scope note —
  the re-produce/relay shape is general (alkhttp fallback hub, alknodes)
  and a real consumer now requires it.
- U-2 adds open_channel_with_reply (ergonomic read path for `bound`);
  open_channel unchanged.

Units, sequenced 1 -> 2 -> 3, one minor release:
1. U-2 reply projection (ADR-049 am. 3) — lands first; the relay's
   establisher projects spoke reply fields through it.
2. U-1 derivation + wire field (ADR-047 am.) — standard shapes
   byte-stable; round-trip gates for flavor-form and boolean shapes.
3. Relay component + gate-2 e2e (ADR-042 am.) — establisher = translate
   hop (forwarded_for, adopt_channel, reason-code mapping, bound
   projection), OpenHandler = inline-await byte-forward hop;
   consumer -> hub -> producer e2e asserting bound survives the relay.

As-filed findings retained untouched above the divider (the review-007
pattern).

Verification: docs-only change; no build/lint/test impact.
 2026-09-16 09:58:17 +00:00
glm-5.3-flash 3b36b4074f docs: review 008 — graduation upstream asks (flavor-form discovery derivation; establisher reply projection) 
Filed from the alktunnels graduation spec work (ADRs 007/008):
U-1 extends ADR-047's op-name → ALPN derivation to flavor-form open
op ids (channels/tunnel/direct, channels/tunnel/forwarded) so the
marker survives discovery and hub relay wraps them as channels, not
plain forwarding stubs; U-2 (ADR-049 amendment 3 sketch) gives the
establisher a path to contribute additive reply fields (the bind-first
listen 'bound' address — BND.ADDR fidelity). Both additive; data
plane untouched. alktunnels implementation is sequenced after these
land.
 2026-09-16 08:32:19 +00:00
1483 changed files with 9763 additions and 45 deletions
Expand all files Collapse all files

No files matched your search

AGENTS.md
+1
View File
@@ -194,6 +194,7 @@ Run these before committing. All must pass.
```bash
cargo test # full suite
cargo test --manifest-path fuzz/shared/Cargo.toml # fuzz corpus replay (stable)
cargo clippy --all-targets -- -D warnings
cargo fmt --check
cargo doc --no-deps # if docs changed
CHANGELOG.md
+221
View File
@@ -4,6 +4,224 @@ All notable changes to this crate are documented here. The format is
based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
this crate adheres to [Semantic Versioning](https://semver.org/).
## [0.8.1] - 2026-09-28
Bug-fix release: a duplicate `adopt_channel`/`open_channel` no longer
destroys the live channel it collided with, found by the crate's new
fuzzing harness (`fuzz/` workspace — five cargo-fuzz targets, committed
seed corpora, three 10-minute campaigns clean). No API or wire-format
change; the error is still `Err(ChannelExists)` — the difference is
entirely in what the collision leaves behind.
### Fixed
- **Duplicate adopt/open no longer replaces the live channel's state
(found by the `manager_routing` fuzz target,
`docs/research/fuzzing.md` §7.8).** `ChannelManager::open_channel`
and `adopt_channel` used `HashMap::insert(...).is_some()` as the
collision check — but `insert` *replaces* an occupied entry and
returns the old value, so a duplicate on an in-use id installed the
new `ChannelState`, dropped the live channel's `demux_sender`
(spurious EOF to its readers; all subsequently routed chunks lost),
and *still* returned `Err(ChannelExists)`. The mux write half kept
framing onto the transport for a channel the demux no longer fed.
Both functions now check `contains_key` and return before any map
mutation — the live channel's routing state is untouched on
collision. Reachable whenever an open-op response is replayed or a
connection-owner race re-announces an id. Regression tests:
`adopt_channel_duplicate_id_leaves_live_channel_intact`,
`open_channel_duplicate_id_leaves_live_channel_intact` (both verify
routing survives a rejected duplicate; the first also verifies the
EOF sentinel remains the only EOF source).
### Added (development)
- **Fuzzing harness (`fuzz/` workspace, `docs/research/fuzzing.md`).**
Five cargo-fuzz targets over the two attacker-reachable wire formats
and the stateful channel-routing surface: `chunk_header` (8-byte
header no-panic/round-trip/accounting), `envelope_frame` (frame
decode error-shape partition + allocation bound), `manager_routing`
(`Arbitrary` op sequences over `ChannelManager` with exact counter
models and the parked-bytes bound), `envelope_semantic` (all six
event kinds: constructors → serde → framing round-trip), and
`spec_parse` (attacker-shaped op-register schemas compile or reject
cleanly at registration). Invariant logic lives in
`fuzz/shared/` — a stable-toolchain crate replayed as plain
`cargo test`, so the committed corpora stay executable without
nightly. Campaigns (10 min per target, detached runner): ~25M
executions total, zero crashes/hangs/OOMs. The `manager_routing`
campaign found the 0.8.1 fix above within minutes — exactly the
stateful interleaving class example-based tests cannot reach.
`fuzz/` is excluded from the workspace and from the published
package.
### Verified
- 684 tests pass; `clippy --all-targets -- -D warnings`, `fmt --check`,
`cargo doc`, wasm32-unknown-unknown check, `cargo semver-checks`
(no API changes vs 0.8.0), and `cargo publish --dry-run` clean;
corpus replay (`cargo test --manifest-path fuzz/shared/Cargo.toml`)
green.
## [0.8.0] - 2026-09-18
Review 008's remediation lands in full — the graduation upstream asks
(U-1 flavor-form open-op ids in discovery; U-2 the establisher → reply
projection) plus the in-tree channel relay they demanded
(`ChannelRelay`, the hub-leg install template, and the review's gate-2
e2e harness). A post-landing audit of that diff hardened the relay's
adopted-entry teardown and the discovery ALPN guards, corrected two
log/error messages, and review 009's coverage debt is paid in full —
all failure-path; no wire or API changes. The channels data plane is
untouched (ADR-034/035's one-way doors stay closed); the new surfaces
are additive on the call-plane JSON and the registry seams.
### Added
- **`Establishment` reply projection (review 008 U-2, ADR-049
amendment 3)** — `Establishment::with_reply_field` /
`with_reply_fields` / `reply_fields()` (an optional map riding the
typed-opaque plan carrier). The open-op wrapper merges the fields
into the success output after reserving `channel_id` — an
establisher supplying the reserved key fails loudly
(`channel:open_failed`, reason `handler_error`), never shadows.
Absent fields leave the reply byte-identical to the pre-amendment
shape.
- **`ChannelClient::open_channel_with_reply` (review 008 U-2)** — the
full open-op success output (the extra reply fields, e.g. a
bind-first listener's `bound`) alongside the streams;
`open_channel` delegates with the fields discarded, its signature
unchanged.
- **Flavor-form open-op ids in discovery (review 008 U-1, ADR-047
amendment 3)** — `spec_to_json_pub` emits an explicit
`channel_open_alpn` string alongside the boolean marker when the op
name is not a standard `channels/<seg>/(sub|pub)` shape (standard
shapes stay byte-stable); `rebuild_spec_for` prefers the explicit
string and generalizes the derivation to strip the LAST path
segment when the marker is present. `channels/tunnel/direct`-shaped
ops now reconstruct WITH the `channel_open` marker through
discovery — hubs relaying through `from_call` never see them as
plain forwarding stubs.
- **`ChannelRelay` (review 008 Unit 3a, ADR-042 as amended by
ADR-051)** — the in-tree relay component:
`ProducerLeg` (`Arc<CallConnection>` + producer-leg
`ChannelManager` — not a `ChannelClient`, whose `take_call_
connection` detach is wrong for a hub with multiple connection
claimants) and `ChannelRelay::register_relay_openable` (registers a
from_call-imported marked spec on a consumer-leg registry via the
full open-op wrapper: ACL, per-identity cap/ledger, establishment
bound, teardown). The translate hop calls the producer leg with the
forwarded payload (`forwarded_for` from the consumer's per-call
identity, ADR-026 §3) and adopts the spoke-allocated id; the
byte-forward hop is `pump_bidi` awaited inline — the hub never
parses chunk framing, ids are per-connection (no rewrite exists).
The spoke reply's `channel_id` is stripped (the consumer reply
carries the hub-allocated id); the reply's other fields ride
through (`bound` flows end-to-end, per-hop truthful). Reason
mapping per ADR-051 §3 — the spoke's code and message are preserved
(`timeout` maps to `dial_failed`, the one non-1:1 row). The
adopted producer-leg channel entry reclaims when the relayed pump
completes. Rejection postures are loud: unmarked and Pub-typed
marked specs fail registration (`RelayError`), never silent stubs.
- **`HubLegImports` + `HubLegTemplate` (review 008 Unit 3b, ADR-051
§5)** — the hub-leg install template as an in-tree export: the
`Clone` discover/stash (from_call bundles split by the marker, with
the per-consumer `filtered`/`only` subset filter) and the
`install_channel_zero` hook composing fork + generic channel ops +
bootstrap discovery closed over the fork (review 004 F-06) + plain
bundles as-is + relay openables + serving-identity resolution
(CF-005 precedence) + the single-stream dispatch loop. A
Pub-typed (or unregistrable) marked spec ends the leg's install
task — channel 0 never dispatches. Discovered bootstrap-discovery
op names are skipped on re-registration (the template's own
install supersedes the imported copies).
### Changed
- **New module `src/channels/relay.rs` and `src/channels/hub_leg.rs`
re-exported from `channels`**; the relay's teardown fix is part of
this landing (no pre-relay behavior to preserve).
### Fixed
Post-landing audit of the remediation diff — hardening guards,
message corrections, and one rejection-posture fix; all failure-path.
- **Adopted-entry teardown on every relay plan path** (ADR-051 §6) —
the relay's `RelayPlan` now owns the producer-leg
`ChannelManager` and reclaims the adopted spoke `channel_id` via a
`Drop` guard, instead of the pump handler's post-`pump_bidi`
explicit reclaim. This closes the leak windows the pump's normal
path cannot reach: the open wrapper's establishment bound expiring
after the adopt (the plan dropped before the pump ever spawns) and
the pump handler's early-return arms (plan absent, downcast
failure, `try_unwrap` failure, `accept_bi` failure). Dropping the
plan's send half still EOFs the spoke side via the mux pump's
implicit-EOF sentinel, so the spoke handler reclaims through the
same cascade as before. Regression test:
`relay_plan_drop_reclaims_the_adopted_producer_leg_entry`.
- **Empty/whitespace `channel_open_alpn` rejected at rebuild** — an
explicit string of `""` (or whitespace-only) previously overrode a
sane name-derived ALPN, poisoning the marker for every consumer
from one misconfigured producer; `rebuild_spec_for` now trims and
rejects empties, falling back to the derivation.
- **Empty-segment standard-shape names** — `channels//sub` was
serialized boolean-only (the standard-shape check saw flavor
`sub`) but reconstructed UNMARKED (the derivation's empty-segment
guard returned `None`) — a silent stub for a marked op. The
standard-shape check now applies the same empty-segment guard, so
the explicit `channel_open_alpn` string rides the wire and the
marker reconstructs.
- **Reserved-reply-key error text and log level** — the
`channel:open_failed` message interpolates `RESERVED_REPLY_KEY`
instead of hardcoding `"channel_id"` (the two could drift), and the
establisher-bug log fires at `warn!` (a programming error), not
`debug!`.
### Testing
Review 009's coverage debt (all seven findings, no wire or API
changes; three as-filed errata recorded in the review):
- **C-1** — the template's plain-bundle install-failure arm is pinned
(un-compilable `input_schema` → the install task ends before the
dispatch loop, channel 0 never dispatches); ADR-051 §5 carries the
loud-install coverage note (relay-openable + plain-bundle arms
pinned; generic-ops + bootstrap-discovery arms documented as
best-effort-loud).
- **C-2** — the `HubLegImports` filter: the `filtered` closure path
and the `only` marked/plain partition unit-tested; the empty-stash
e2e gate (serves only the generic ops + discovery, dropped ops
resolve `NOT_FOUND`).
- **C-3** — the batch-form reserved-reply-key rejection
(`with_reply_fields` smuggling `channel_id`) pinned: reason
`handler_error`, channel torn down, ledger decremented, pump never
spawns.
- **C-4** — `open_channel_with_reply`'s failure path pinned e2e: the
typed error carries the `channel:open_failed` code and the full
`details` shape (`reason` + `message`) through the new API.
- **C-5** — both "byte-identical" claims are golden-pinned: the
no-fields reply against the exact `{"channel_id": 2}` literal, and
the standard-shape wire payload against the full 9-key literal.
- **C-6** — the derivation's edge shapes pinned: `channels//sub` /
`channels//direct` / `channels` → `None`; the 4-segment strict
superset (`channels/x/sub/extra` → `Some("x/sub")`) annotated as the
pre-amendment behavior change; the verbatim `channels/alk/tty/sub`
case.
- **C-7** — the builder's overwrite semantics pinned last-win (single
and batch forms) with the doc sentence on `with_reply_field`.
### Verified
- 682 tests pass (`cargo test`), `clippy --all-targets -- -D warnings`
and `fmt --check` clean. The gate-2 e2e harness
(`src/channels/gate2_tests.rs`) pins the review's gate 2: the full
consumer → hub → producer relay through the template (hub-allocated
id, `bound` surviving, data both directions with a fake 8-byte
chunk header riding verbatim), hub-side disconnect tearing down
both legs, the mid-establishment window's two reclaim signals
(ADR-051 §6), and the `channels/tty/sub` standard-shape companion.
## [0.7.1] - 2026-09-09
The MSRV floor becomes honest: `rust-version` raises from 1.85 to
@@ -519,6 +737,9 @@ Vendored core types (`Connection`, `ProtocolHandler`, `BiStream`,
(ADR-046), the channels protocol with openable-ALPNs-as-operations
(ADR-047), and the `ChannelClient` transport-agnostic client.
[0.8.1]: https://git.alk.dev/alkdev/alkcall/releases/tag/v0.8.1
[0.8.0]: https://git.alk.dev/alkdev/alkcall/releases/tag/v0.8.0
[0.7.1]: https://git.alk.dev/alkdev/alkcall/releases/tag/v0.7.1
[0.7.0]: https://git.alk.dev/alkdev/alkcall/releases/tag/v0.7.0
[0.6.0]: https://git.alk.dev/alkdev/alkcall/releases/tag/v0.6.0
[0.5.0]: https://git.alk.dev/alkdev/alkcall/releases/tag/v0.5.0
Cargo.lock
Generated
+1 -1
View File
@@ -27,7 +27,7 @@ dependencies = [
[[package]]
name = "alkcall"
version = "0.7.1"
version = "0.8.1"
dependencies = [
"async-trait",
"bytes",
Cargo.toml
+6 -2
View File
@@ -1,6 +1,6 @@
[package]
name = "alkcall"
version = "0.7.1"
version = "0.8.1"
edition = "2021"
rust-version = "1.88"
license = "MIT OR Apache-2.0"
@@ -9,7 +9,11 @@ readme = "README.md"
repository = "https://git.alk.dev/alkdev/alkcall"
keywords = ["rpc", "json-rpc", "multiplexing", "wire-format", "alpn"]
categories = ["network-programming", "asynchronous", "encoding"]
exclude = [".opencode/", "AGENTS.md", "docs/reviews/", "docs/sdd_process.md"]
exclude = [".opencode/", "AGENTS.md", "docs/reviews/", "docs/sdd_process.md", "docs/research/", "fuzz/"]
[workspace]
members = ["."]
exclude = ["fuzz"]
[lib]
name = "alkcall"
docs/architecture/README.md
+2 -1
View File
@@ -13,7 +13,7 @@ This crate unifies `alknet-call` and `alknet-channels` from the alknet
mono-repo, plus the vendored core types formerly in `alknet-core`. The
source architecture docs were ported from
`/workspace/@alkdev/alknet/docs/architecture/` and renumbered as alkcall
ADRs (ADR-001..050). The ALPN strings (`alk/call`, `alk/channels`)
ADRs (ADR-001..051). The ALPN strings (`alk/call`, `alk/channels`)
are wire-stable and unchanged — see ADR-004.
## Documents
@@ -103,6 +103,7 @@ are wire-stable and unchanged — see ADR-004.
| [048](decisions/048-dispatch-spine-gateway-module.md) | Dispatch Spine (feature-gated `gateway` module) | `alkcall::gateway` behind the `gateway` feature; `GatewayDispatch` invoke spine (deadline knob, re-rooted context) + `schema_disclosure_denial` (FORBIDDEN for ACL deny, spec-404 for Internal); promoted from alkhttp for hub/spoke reuse |
| [049](decisions/049-channel-open-establishment-phase.md) | Channel-Open Establishment Phase | `OpenEstablisher` + `register_openable_with_establisher` (awaited, bounded); typed `channel:open_failed` with `details.reason`; `Establishment.plan` (`ChannelPlan`) threaded to the `OpenHandler` (amendment 2); the `JoinHandle` data-plane lifetime contract |
| [050](decisions/050-pump-bidi-two-pump-helper.md) | `pump_bidi` Two-Pump Helper | `channels::pump_bidi` — shutdown-on-completion two-pump data plane pinned in one place (alknet ADR-078) |
| [051](decisions/051-channel-relay-and-hub-leg.md) | In-Tree Channel Relay (`ChannelRelay`) and the Hub-Leg Assembly | ADR-042 amended — the relay implementation is an alkcall export; translate hop = ADR-049 establisher (`register_relay_openable`), byte-forward hop = `pump_bidi`; implicit per-channel id mapping; two-phase registration (discover/stash → fork-register); hub-leg install template; ACL layering note |
## Relevant Open Questions
docs/architecture/decisions/042-hub-relay-translate-not-forward.md
+46 -1
View File
@@ -2,7 +2,52 @@
## Status
Accepted
Accepted (amended 2026-09-17, ADR-051 — the relay implementation is an
alkcall export (`ChannelRelay`), not downstream-only code; the §"Scope
note" below is revised, and the §`channel_id` mapping / close-translation
mechanism is superseded by an implicit-per-channel shape — see
"Amendment (ADR-051, in-tree relay export, 2026-09-17)" below;
the translate-not-forward contract and the auth-model rationale are
unchanged)
## Amendment (ADR-051, in-tree relay export, 2026-09-17)
The relay implementation moved into alkcall as a reusable export
(`ChannelRelay`, ADR-051) — consumers that exist (alktunnels'
graduation, alkhttp's fallback hub, alknodes) all need the same shape,
so the §"Scope note" decision ("the relay implementation lives in
`alknet-hub`/downstream") is revised: hub crates COMPOSE the export.
Two implementation findings supersede mechanism text above, both
within the two-way door this ADR already marked:
1. **The `channel_id` mapping dissolves.** §`channel_id` mapping
pinned a `HashMap<channel_id, channel_id>` per (browser, spoke)
pair. The implementation needs no map: each leg's `ChannelManager`
holds its own id → routing state, and the per-channel pump closure
binds both legs. The mapping is implicit-per-channel — a
`channel_id` never crosses legs, so the translate hop produces
per-leg-truthful ids (this also refines alktunnels ADR-008 §Hub
re-produce's "re-map the id at their re-produce hop naturally":
the re-map is two independent allocations, not a rewrite).
2. **`channel/close` needs no translation surface.** The §mapping
bullet's "On `channel/close` (translated the same way), the mapping
is removed" assumed the map; without it, close propagates through
the EOF cascade (consumer-side close → open-op wrapper teardown →
pump abort → send-half drop → EOF chunk → spoke handler exits →
spoke's own wrapper decrements its ledger) with correct accounting
on both legs. The hub never sees a `channel/close` to translate.
`channel/control` stays per-leg (OQ-39 — a hub wanting cross-leg
control translation composes it downstream), unchanged.
The byte-forward layer is ADR-050's `pump_bidi` per channel (the
hub never parses chunk framing — stronger than §"Data-channel layer"'s
rewrite phrasing, which assumed the map-based rewrite shape). The
translate layer is the ADR-049 establisher shape
(`register_relay_openable`), keeping the consumer leg's full wrapper
machinery (registry ACL, per-identity cap/ledger, establishment bound,
teardown-on-failure) — the auth-model rationale above is unchanged and
now has a concrete in-tree carrier.
## Context
docs/architecture/decisions/047-openable-alpns-are-operations.md
+89 -1
View File
@@ -11,7 +11,95 @@ base registry installed as the session's dispatch registry**, not the
connection overlay — see "Amendment (§4 mechanism, 2026-09-03)" below;
§6 amended 2026-09-06 — the static half of discovery gains an additive
per-op `description` on the listing, the dynamic half stays deferred
— see "Amendment (§6 listing enrichment, 2026-09-06)" below)
— see "Amendment (§6 listing enrichment, 2026-09-06)" below;
amendment 3 (2026-09-16, review 008 U-1) — the op-name convention
extends to the flavor form and discovery carries an explicit
`channel_open_alpn` for non-derivable names — see "Amendment 3" below)
## Amendment 3 (flavor-form open-op ids + explicit `channel_open_alpn`, 2026-09-16 — review 008 U-1)
alktunnels' graduation (ADR-002 Amendment 1 at
`/workspace/@alkdev/alktunnels/docs/architecture/decisions/002-alpn-strategy.md`)
pins two NEW `Sub`-typed open ops on the existing `alk/tunnel` ALPN
with flavor-form op ids (`channels/tunnel/direct`,
`channels/tunnel/forwarded`) — the ssh
`direct-tcpip`/`forwarded-tcpip` shape: one ALPN, several channel
flavors, one open op per flavor. §1 pinned the open-op naming to
exactly two shapes per ALPN (`channels/<alpn>/sub`,
`channels/<alpn>/pub`), and Gap F's marker reconstruction derived the
ALPN by stripping exactly those two suffixes — so a flavor-form op id
failed the derivation and a hub consuming through discovery rebuilt
the spec WITHOUT the marker (the silent plain-forwarding-stub failure,
the worst mode for a relay). Runtime was never blocked (registration
sets the ALPN explicitly; `open_channel` takes it as an argument);
discovery + hub relay are the re-produce path that must survive.
**The convention sentence (mirroring alktunnels ADR-002 Amendment 1):**
`channels/<alpn>/<flavor>` is a valid open-op name where `<flavor>`
is a bare path segment (no `/`), `Sub`-typed, served through the same
establishment wrapper and relay path as `…/sub`. New flavors are new
op ids — additive; the `…/sub` op is never reused for a different
meaning. `OperationType` (`Sub`/`Pub`) continues to carry the
direction; the flavor is the channel-type discriminator the producing
crate owns (per-ALPN params semantics, per alktunnels ADR-001
Amendment 1).
**The wire shape (Gap F refinement):** the boolean marker's
round-trip is derivable only for the standard shapes. The rule:
- `spec_to_json_pub` keeps emitting `"channel_open": true` for every
marked op (unchanged). When the op name is NOT the standard
`channels/<segment>/(sub|pub)` shape, it ALSO emits
`"channel_open_alpn": "<alpn>"` — the explicit string rides beside
the boolean. Standard shapes stay byte-identical to the
pre-amendment payload (no new key).
- `rebuild_spec_for` prefers the explicit string when present; else
(the boolean alone — the deployment-skew case of an old producer)
the derivation generalizes from "strip `/sub`|`/pub`" to "strip the
LAST path segment." The boolean marker remains the gate: the
derivation is consulted only for marked ops, so a plain op named
`channels/tty/query` is unaffected, and a `channel_open_alpn`
string without the boolean never marks an op.
- `services/schema`'s advertised `operation_spec_schema` documents
`channel_open_alpn` as an optional `["string", "null"]` property
(schema-type widening, additive — old consumers ignore unknown
properties).
- Both wire consumers of the shape — the `from_call` import and the
`op/register` announced-spec path — parse through the same
`rebuild_spec_for`, so one parser change covers both.
**Residual ambiguity, pinned:** an op name whose ALPN segment itself
ends in a flavor-like name (`channels/x/direct` where the intended
ALPN is `alk/x/direct`-shaped) is undecidable from the name alone —
strip-last reads `alk/x`, and the true ALPN is unknowable from the
name. The explicit `channel_open_alpn` string is the disambiguator:
producing crates with non-`alk/*`-derivable names set it; the
derivation is the fallback for derivable shapes. Old producers
(alkcall ≤ 0.7.1) cannot serve flavor-form marked ops discoverably
until upgraded — the review's one-way-door timing note.
Door type: the flavor-form names and the additive
`channel_open_alpn` key are wire-stable from the first consumer
(alksocks composes against them); the boolean's meaning for
standard-shape ops is unchanged (the pre-amendment byte-stability is
pinned by test). The `op_name_is_standard_channel_open_shape` helper
and the strip-last derivation are two-way-door implementation details
within the one-way wire shape.
Implemented surface (alkcall 0.8.0): the generalized
`derive_alpn_from_op_name` (strip-last), the explicit-field emission
(`spec_to_json_pub` + the advertised schema property), and the
preference order in `rebuild_spec_for`. Verification gates landed as
tests: `channels/tunnel/direct` reconstructs WITH
`channel_open = alk/tunnel` (gate 1, both the explicit-string and the
skew-case paths); standard boolean ops (`channels/tty/sub`,
multi-segment `channels/custom/proto/sub`) round-trip byte-stable
(gate 3); the explicit string overrides a colliding derivation; a
string without the boolean never marks; `op/register` announced
flavor-form specs round-trip with the marker. Gate 2 (the hub-relay
round trip) lands with the in-tree relay component (review 008
remediation plan Unit 3c, amending ADR-042 — the relay export is
ADR-051).
## Amendment (§6 listing enrichment, 2026-09-06)
docs/architecture/decisions/049-channel-open-establishment-phase.md
+68 -4
View File
@@ -6,7 +6,8 @@ Accepted — implemented in alkcall 0.5.0 (Unit 1: E-01 + N-1; see the
"Amendment (Unit 1 implementation, 2026-09-06)" at the bottom).
Amends ADR-047 §3 — the open-op wrapper gains an awaited
establishment phase ahead of the spawned pump handler; resolves review
006 E-01 and N-1
006 E-01 and N-1. Amendment 3 (2026-09-16, review 008 U-2) adds the
establisher reply projection — see "Amendment 3" below.
## Context
@@ -379,8 +380,8 @@ is unfixable within that shape; alktty documented the same wall
(backend `allocate` cannot cross, so failure classes stayed in-band —
the phantom-channel shape ADR-049 removed, alive one layer down).
The plan is now real: `Establishment { plan: Option<ChannelPlan> }`
with `ChannelPlan = Arc<dyn Any + Send + Sync>` — **typed-opaque, not
The plan is now real: `Establishment { plan: Option<ChannelPlan> }` with
`ChannelPlan = Arc<dyn Any + Send + Sync>` — **typed-opaque, not
`serde_json::Value`**. The review's `Option<Value>` sketch could not
satisfy its own verification gate ("establisher dials, `plan` carries
the handle"): the payloads establishers actually hand off are live
@@ -414,4 +415,67 @@ and the registration entry points, plus a `debug!` telemetry line in
`run_open_wrapper` when a handler exits without having accepted the
channel's `BiStream` (the birth-teardown hint; the accept is
observable in-process via the yield-once source). §6's pinned
EOF-shaped panic semantics are unchanged.
EOF-shaped panic semantics are unchanged.
## Amendment 3 (establisher reply projection, 2026-09-16 — review 008 U-2)
Amendment 2 filled the establisher → handler direction (the plan);
the establisher → opener direction stayed empty — the wrapper
hardcodes the success reply to `channel_id`
(`run_open_wrapper`'s `ResponseEnvelope::ok`). alktunnels ADR-008's
bind-first listen establisher ends establishment at bind time, and the
observed OS-chosen bound address must ride the open-op reply as an
additive `"bound"` field (the SOCKS5 BIND reply#1 `BND.ADDR` fidelity
ask) — the alternative (an out-of-band query op) is a new wire
surface, strictly worse than an optional reply field.
**The decision: `Establishment` gains optional reply fields the
wrapper merges into the success output.**
- The carrier: `Establishment.reply_fields: Option<Map<String,
Value>>` (private, builder-constructed) —
`Establishment::new(plan).with_reply_field("bound", json!({...}))`,
plus `with_reply_fields(map)` (batch) and `reply_fields()` (read).
The map shape generalizes beyond `bound` without a fourth
amendment; `#[non_exhaustive]` (amendment 2) made the carrier
extension additive — no construction-site break.
- The merge: on establisher success the wrapper extends the success
output with the contributed fields AFTER reserving `channel_id`.
**The `channel_id` reservation:** the key is wrapper-owned; an
establisher supplying it is an establisher bug — the wrapper fails
the open loudly (`channel:open_failed`, reason `handler_error`,
message naming the reserved key) and tears the just-allocated
channel down, never silently shadowing its own value. Contributed
fields otherwise merge flat; the output schema remains the op's own
concern (the producing crate documents its optional fields —
alktunnels' listen-op spec documents `bound`).
- The client read path: `ChannelClient::open_channel_with_reply`
returns `(channel_id, reply, send, recv)` — the full success
output — so a consumer reads `bound` without dropping to
`call_open_op` + manual `adopt_channel`;
`open_channel` delegates and discards the extra fields, signature
unchanged.
- Compatibility: absent reply fields leave the reply byte-identical
to the pre-amendment shape (`{ channel_id }`) — verified by test.
Old consumers (`open_channel` extracting `channel_id`, ignoring
unknown fields) are unaffected by a NEW field; new consumers reading
`bound` against an OLD alkcall see the field absent — the additive
posture alktunnels ADR-008 §2 pins.
Door type: the reply fields are an additive call-plane JSON surface
(like `channel:open_failed`'s `details` in §3 — consumers ignore
unknown fields by the envelope's own parse posture); the field set an
op may contribute is the producing crate's schema concern, not a
protocol vocabulary. No data-plane change.
Implemented surface (alkcall 0.8.0): `Establishment::with_reply_field`
/ `with_reply_fields` / `reply_fields`, the wrapper's
reservation check (`RESERVED_REPLY_KEY` = `channel_id`) +
`merge_reply_fields`, `ChannelClient::open_channel_with_reply`.
Verification gates landed as tests: the projection produces
`{ channel_id, bound }` on the wire; no-fields (establisher or not)
produces exactly `{ channel_id }` (byte-identical); the reserved-key
establisher fails with reason `handler_error`, channel torn down,
ledger decremented, handler never spawned; the e2e gate carries
`bound` through a real channels connection to
`open_channel_with_reply` while `open_channel` stays unchanged.
docs/architecture/decisions/051-channel-relay-and-hub-leg.md
+343
View File
@@ -0,0 +1,343 @@
# ADR-051: In-Tree Channel Relay (`ChannelRelay`) and the Hub-Leg Assembly
## Status
Accepted (2026-09-17) — amends ADR-042 (the relay contract's
implementation home moves into alkcall; the translate-not-forward
contract is unchanged). Sequenced after review 008 remediation Units 1
and 2 (both landed, alkcall 0.8.0): the relay's establisher projects
the spoke reply's extra fields via `Establishment` reply fields
(ADR-049 amendment 3), and the spoke's flavor-form open ops arrive
reconstructed WITH the `channel_open` marker through discovery
(ADR-047 amendment 3). All three implementation units are landed:
Unit 3a (the `ChannelRelay` component, §1–§4, §6) in
`src/channels/relay.rs`, Unit 3b (the hub-leg install template, §5) in
`src/channels/hub_leg.rs`, and Unit 3c (the review's gate-2 e2e
harness, gates 6/7) in `src/channels/gate2_tests.rs` — alkcall 0.8.0.
## Context
Review 008's remediation plan (Unit 3) pinned the in-tree relay as the
implementation of the review's U-1 gate 2 — the hub-relay round trip
that proves flavor-form marked ops survive discovery into a genuine
relay. The as-filed ADR-042 §"Scope note" put the relay implementation
in `alknet-hub`/downstream; the consumers that now exist (alktunnels'
graduation, alkhttp's fallback hub, alknodes, and the hub/spoke family
behind them) all need the same shape, so the implementation moves into
alkcall as a reusable export.
The consumer family the relay must serve is the hub/spoke composition:
spokes connect to a hub and expose services; the hub re-exposes those
services to other spokes (and consumers) based on ACL. Both a hub and
a spoke can be a relay depending on the setup. A canonical example:
spoke A exposes `channels/tunnel/direct`; the hub imports it via
`from_call`, gates it with its own ACL, and re-exposes it on its
consumer-leg channel-0 registries; spoke B opens through the hub and
the hub relays the channel to spoke A. The hub performs no port
binding and no protocol work on the data plane — the property that
makes the hub-acl-relay role cheap (alktunnels' no-bind posture, the
same property ADR-042 §What the hub runs pins: "the hub never runs a
handler for `alk/tty`, `alk/ssh`, or `alk/tunnel`").
Two implementation surfaces were evaluated for the data plane; the
decision records why the wrapper-composition shape wins over
byte-forward-with-rewrite.
## Decision
### 1. The relay is the wrapper composition — translate-not-forward, implemented with the existing open-op machinery
ADR-042's two-layer contract is implemented as composition of pieces
this crate already has:
- **Layer 1 (call-protocol translate)** is the ADR-049 establisher:
the hub's consumer-leg open op resolves through the full open-op
wrapper (registry ACL → per-identity cap → allocation), then the
establisher calls the producer leg's open op, adopts the returned
spoke channel id into the producer-leg `ChannelManager`, and returns
`Establishment::new(plan)` whose plan carries the spoke-leg streams.
The hub allocates its own consumer-leg `channel_id`; the spoke
allocated its own producer-leg id; the two ids never appear in each
other's namespaces.
- **Layer 2 (byte-forward)** is the ADR-050 `OpenHandler`:
`pump_bidi(consumer_leg_bistream, spoke_recv, spoke_send)` — the
pump's generic bounds already match the relay's two legs. The relay
never parses chunk framing on either leg; the mux/demux on each leg
absorbs the 8-byte header (ADR-034) and the channel-id namespaces
are per-connection, so no header rewrite exists. Awaited inline per
the R-02 lifetime contract; on completion both legs tear down (the
wrapper's handler-exit teardown covers the consumer leg; the pump's
send/recv drops EOF the spoke leg).
**The relay map dissolves.** ADR-042 §`channel_id` mapping pinned a
`HashMap<channel_id, channel_id>` per (browser, spoke) pair maintained
by the hub. The implementation needs no map: each leg's `ChannelManager`
already holds its own id → routing state, and the per-channel pump
closure binds both legs' streams. The mapping is implicit-per-channel.
This is a two-way-door implementation detail within ADR-042's contract
(the ADR itself marked the mapping strategy two-way).
**`channel/close` and `channel/control` need no translation surface.**
Consumer-side close → wrapper teardown → pump abort → send-half drop →
EOF chunk → spoke handler exits → spoke's own wrapper decrements its
ledger. Close propagates through the EOF cascade with correct ledger
accounting on both legs; the hub never sees a `channel/close` to
translate. Control stays per-leg (`channel/control` is not implemented
upstream, OQ-39 — a hub wanting cross-leg control translation composes
it downstream). This supersedes the ADR-042 §mapping bullet's
close-translation sentence as an implementation matter: the mapping
entry the sentence's removal depended on does not exist.
### 2. What the relay holds on the producer leg: `CallConnection` + `ChannelManager`
The relay's producer-leg surface is `Arc<CallConnection>` (for the
translate hop's open call) plus the producer-leg `ChannelManager` (for
`adopt_channel` and teardown visibility) — not a `ChannelClient`.
Rationale: `ChannelClient`'s calling surface detaches on
`take_call_connection` (the hub needs the connection for `from_call`
import AND for the relay's establisher AND possibly its own ops —
three claimants), while `Arc<CallConnection>` is `Clone` and the
client's manager accessor yields the same `ChannelManager` the relay
needs. A hub that dials the spoke with `ChannelClient::from_connection`
and then tears the client down after import keeps the relay alive on
the `Arc`s. The establisher builds its forwarded payload directly
(`build_forwarded_payload` semantics — the hub as caller, the consumer
as `forwarded_for`, ADR-026 §3) rather than through
`call_open_op`, which carries no payload variant.
The spoke reply's `channel_id` is stripped before projection (the
consumer-leg reply carries the hub-allocated id, not the spoke's);
the spoke reply's other fields ride through `with_reply_fields` —
`bound` flows end-to-end with per-hop truthfulness (a hub re-producing
a listen resource binds its own listener and contributes its own
`bound`; alktunnels ADR-008 §Hub re-produce).
### 3. Reason-code mapping (spoke `CallError` → `EstablishmentError`)
The spoke's open can fail with the full call-error vocabulary; the
establisher maps it into `EstablishmentError` by class:
| Spoke failure | `EstablishmentError` variant | Wire reason |
|---|---|---|
| `channel:open_failed` with a typed reason | the same class — `DialFailed` for `dial_failed`/`timeout`, `UnknownResource` for `unknown_resource`, `ResourceShortage` for `resource_shortage`, `HandlerError` for `handler_error` | the mapped reason |
| `channel:open_failed` reason `timeout` | `DialFailed` (the spoke establishment exceeded the spoke bound — from the consumer's side it is unreachable-target-shaped) | `dial_failed`, spoke message preserved |
| `NOT_FOUND` (spoke predates the op) | `HandlerError` carrying the code | `handler_error` |
| `FORBIDDEN` (hub lacks the spoke grant) | `HandlerError` carrying the code | `handler_error` |
| other `CallError` | `HandlerError` carrying the code | `handler_error` |
The spoke's original code and message are preserved in the mapped
variant's `message` (never discarded — a consumer debugging a
FORBIDDEN-through-relay must see the spoke's grant failure, not a bare
`handler_error`). The `timeout` mapping is the one non-1:1 case: the
consumer-visible reason is `dial_failed` because establishment
timeouts are wrapper-generated (ADR-049 §3) and not an establisher
vocabulary word; the spoke's message carries the truth.
### 4. The registration seam: two phases, fork-registry registration
Openable ops register on a **per-connection fork of the hub's base
registry** installed as the consumer leg's dispatch registry (the
ADR-047 §4 amendment mechanism). Discovery of the producer leg's ops
happens once (hub startup or reconnect); registration happens per
consumer-leg connection inside the `install_channel_zero` hook. The
one-call signature the review sketched cannot exist without adapter
changes — the two phases are the API:
1. **Discover/stash** — `from_call` against the producer leg returns
the imported `HandlerRegistration` bundles. Marked specs (rebuilt
WITH the `channel_open` marker, ADR-047 amendment 3) are separated
from plain bundles by the marker. The stash is a `Clone`able
template: `HandlerRegistration` and `HandlerKind` are `Clone`, and
`OperationRegistry::fork` deep-copies registrations, so one
discovered set serves any number of consumer legs.
2. **Register per connection** — the hub-leg install hook forks the
base registry, registers the generic channel ops
(`ChannelOperations::register_on`), registers the stashed plain
bundles as-is (the existing forwarding handlers), and registers
each stashed marked spec via the relay's
`register_relay_openable` (the fork is the `consumer_registry`
argument), then dispatches channel 0 over the fork.
Per-consumer ACL differentiation is a composition consequence, not a
mechanism: the fork is per consumer leg, so a hub re-exposing
different op subsets to different consumers filters the stash per
fork. The imported spec's own `access_control` remains the gate for
the re-exposed op; the hub composes additional ACL at its assembly
layer.
### 5. The hub-leg install hook is an in-tree export (the call-half support)
Every existing test hand-rolls the hub-side install hook
(`make_install_channel_zero`-shaped); the hub/spoke family all need
the same composition. The relay lands with a documented hub-leg
template — fork, generic ops, bootstrap discovery, stashed bundles
(plain + relay), per-call identity resolution (`ServingConfig`-shaped),
single-stream dispatch loop — as an in-tree composition (unit-scoped:
Unit 3b). This is composition of existing pieces, not a new protocol
surface; its exact API shape is a two-way-door implementation detail.
The spoke side needs nothing new: a spoke serving ops through a hub is
the existing connect-side serving shape (`from_connection_with_serving`)
plus the producer-leg registration it already does.
**ACL layering note (pinned, because it surprises):** the spoke's
`AccessControl` sees only the hub's identity — the end consumer's
identity rides `forwarded_for` as metadata and is never consulted by
any `AccessControl::check` (ADR-024/ADR-026). "The hub re-exposes
based on ACL" therefore means: the hub-side gate is the imported
spec's ACL (+ hub policy) on the consumer leg; the spoke-side grant
goes to the hub identity, which needs scopes on every spoke op it
relays. The end consumer never authenticates to the spoke directly.
**Loud-install coverage note (review 009 C-1):** the template's four
install-failure arms all end the install task before the dispatch
loop (channel 0 never dispatches — never a silent stub). Two arms are
unit-test-pinned: the relay-openable registration failure (the
Pub-typed marked spec gate) and the plain-bundle registration failure
(an un-compilable schema — the registry's fail-closed rule). The
other two arms — generic channel-ops registration and bootstrap
discovery install — are best-effort-loud: both register
crate-internal specs whose schemas compile by construction, so
failure is not reachable through any public path and an injectable
failure seam would test the seam, not the arm. This note is the
contract: if a future change makes either arm reachable, it gets the
same pin.
### 6. Bounds: rejected shapes and residual notes
- **Pub-typed open ops** — rejected loudly (`channel:pub_open_not_implemented`,
the C-08 blocker). The relay registers only `Query`/`Mutation`-typed
ops (plain forwarding) and `Sub`-typed marked ops (relay openables);
a discovered `Pub`-typed marked spec is an assembly error, not a
silent stub.
- **Compounding establishment bounds** — each hop's establisher is
bounded independently (ADR-049 §2); an N-hop chain adds N bounds.
The consumer's dispatch deadline (`min(deadline, 10s)` per hop)
bounds each hop, not the chain. No fix — noted for capacity
planning.
- **Mid-establishment consumer disconnect** — the one teardown window
with a delay, with two reclaim signals pinned by the Unit 3c gate
(`gate2_mid_establishment_disconnect_reclaims_without_leak`): (a)
the consumer leg's just-allocated channel reclaims at the leg's own
transport EOF (`clear_all` + ledger decrement) — the hub has not
adopted, so the producer leg stays clean; (b) the spoke's channel —
the spoke allocates before its establisher replies — is the honest
residual: it cannot be reclaimed by the hub (no adoption exists),
so it lingers until a spoke-side teardown signal (the spoke↔hub leg
ending, or the spoke's own establishment bound). The gate bounds
the window deterministically by severing the spoke leg and asserts
the spoke-side reclaim + ledger decrement. A channel never outlives
its leg lifetimes; never a leak past the connection's lifetime.
- **Adopted-entry teardown on every plan path** — the hub's
producer-leg entry (the `adopt_channel` state) is owned by the
relay's `RelayPlan` via a `Drop` guard, so it reclaims whenever the
plan dies: the normal pump completion, the pump handler's
early-return arms (plan absent, downcast failure, `try_unwrap`
failure, `accept_bi` failure), and the wrapper's establishment
bound expiring after the adopt (the plan dropped before the pump
ever spawns). Dropping the plan's send half also EOFs the spoke
side through the mux pump's implicit-EOF sentinel (REQ-CH-01), so
the spoke handler reclaims through the same cascade the normal
path uses. This closes the adopt-then-timeout window the landing
review surfaced (the §6 window above is the *pre-adopt* window;
this is the *post-adopt* one, now closed by construction). The
one remaining cancellation point *inside* `adopt_channel`'s own
await is the same pre-existing client-side window
(`ChannelClient::open_channel`'s adopt has it too) — bounded by
the leg's transport-EOF `clear_all`, not by the plan.
- **Multi-hop relays** — a chain of relays composes (each hop is a
hub leg pair), with the compounding-bound note above. No special
machinery.
## Consequences
**Positive:**
- The relay is O(1) new machinery: an establisher closure, a
`pump_bidi` handler, and a registration entry point. No parallel
auth path (the consumer leg's full wrapper machinery applies), no
new wire surface (the relay speaks only already-stable ops), no
data-plane parsing (ADR-034's one-way door stays closed).
- `from_call` gains a real in-tree consumer for the marker-branching
seam Gap C named (ADR-047 §Gap C): downstream crates compose
`ChannelRelay` instead of re-deriving the hub shape.
- U-1's gate 2 (the review's silent-failure scenario — flavor-form ops
relaying as plain forwarding stubs) becomes a permanent e2e gate.
**Negative:**
- New pub API (`ChannelRelay`, the registration entry point, the
hub-leg template) — minor bump, one release with the review's other
units, review-007 precedent.
- The two-phase discover/stash-then-register shape is more assembly
code for a trivial hub than a one-call import would be. The fork
mechanism forces it; the stash being `Clone` keeps the per-connection
work cheap.
- The hub holds `Arc<CallConnection>` + `ChannelManager` per spoke leg
for the connection's lifetime — per-leg state, bounded by the spoke
count.
## Door type
**Two-way (implementation shape) within a one-way posture.** The
translate-not-forward contract (ADR-042) and the ACL layering are
unchanged one-way decisions; the in-tree export, the implicit-mapping
implementation, and the two-phase registration shape are revisable
implementation details — downstream crates compose the export, not the
internals. The rejection posture for Pub-typed marked ops is loud (an
assembly error), so a future implementation of the Pub path is
additive.
## Verification gates (implementation units)
Unit 3a (the relay component):
1. `register_relay_openable` on a forked consumer-leg registry
resolves the open op end-to-end; the establisher populates
`forwarded_for` from the consumer's per-call identity (ADR-026 §3)
and strips the spoke reply's `channel_id`.
2. A spoke `channel:open_failed` maps to the consumer-leg
`channel:open_failed` with the mapped reason (the §3 table) and the
spoke's message preserved; the consumer leg tears down (ledger
decremented); no spoke channel leaks.
3. `bound` (Unit 1's reply projection) survives the relay to the
consumer reply.
4. Pub-typed marked specs are rejected at registration.
Unit 3b (the hub-leg template):
5. The template composes fork + generic ops + bootstrap discovery +
plain bundles + relay openables + serving identity and dispatches
channel 0; `services/list` on the consumer leg shows the
re-exposed ops.
Unit 3c (the gate-2 e2e):
6. The review's full harness: consumer → hub (forked channel-0
registry + relay) → producer, opening `channels/tunnel/direct` end
to end: the open resolves with the hub-allocated `channel_id`, the
establisher-contributed `bound` field survives to the consumer
reply, data flows both directions (the hub never parses it), and
hub-side disconnect / spoke-side close tears down both legs
(including the mid-establishment window from §6).
7. A companion `channels/tty/sub` relay run pins no regression on
standard shapes.
## References
- ADR-042 (amended by this ADR — the implementation home; the
contract unchanged; the relay map and close-translation bullets
superseded by the implicit-per-channel shape)
- ADR-047 amendment 3 (flavor-form ops reconstruct WITH the marker —
the discovery input this relay consumes), §Gap C (the
marker-branching seam), §4 amendment (the fork mechanism Unit 3b
composes)
- ADR-049 amendments 2/3 (the plan payload the relay's establisher
carries; the reply projection `bound` rides through)
- ADR-026 §3 (forwarded_for on the translate hop), ADR-050
(`pump_bidi` — the byte-forward hop), ADR-040/041 (the caps the
consumer leg keeps enforcing)
- alktunnels ADR-007/008 (the first consumers: the direct op's relay
and the listen `bound` field's per-hop truthfulness)
- Review 008 remediation plan Units 1–3 (the sequencing this ADR
lands inside)
docs/research/fuzzing.md
+814
View File
@@ -0,0 +1,814 @@
# Fuzzing alkcall: Research and Recommendation
**Status:** steps 1–3 of §7.4 adopted — `fuzz/` workspace, five targets,
committed seeds, detached runner, two-tier campaigns run; one real
finding (duplicate adopt/open destroying the live channel) fixed with
regression tests. §7.2/§7.4's CI tiers are **not planned** — this repo
will not run hosted CI (the git host is a minimal gitea that serves git
only; see §7.9). CI's two deliverables are covered instead: the stable
side's corpus replay (`cargo test --manifest-path fuzz/shared/Cargo.toml`)
runs as part of every release's verification checklist (AGENTS.md), and
campaigns run manually via the detached runner (§7.6)
**Date:** 2026-09-27
**Research inputs:** web survey of the 2025–2026 Rust fuzzing ecosystem, survey
of fuzzing practice in comparable Rust protocol crates (rustls, quinn, quiche,
h2, prost, s2n-quic, yamux/libp2p, serde_json), and a first-hand inventory of
alkcall's untrusted-input parse surfaces (§5, verified against the code in
this repo).
---
## 1. Should this crate be fuzzed?
**Yes.** Three independent lines of argument converge:
1. **Position in the dependency graph.** alkcall is the substrate crate:
vendored core types, the call protocol, and the channels demux/mux all
live here, and downstream crates consume the wire formats rather than
re-implementing them (ADR-031 crate decomposition, ADR-007/008/009
vendored types). A parser bug here propagates everywhere; a fuzzed
parser here protects the whole stack. Fuzzing "at this level and working
down" is the right order — it is exactly what rustls did (fuzz the
deframer at the bottom, then the state machines).
2. **Wire formats are stable and attacker-reachable by design.** The
`EventEnvelope` framing (`{ type, id, payload: serde_json::Value }`
behind a 4-byte BE length prefix, ADR-014) and the channels 8-byte chunk
header (`[channel_id:u32 BE][len:u32 BE][payload]`, ADR-034) are
one-way doors. Both are parsed from bytes produced by *arbitrary peers*
— including relayed peers in the ADR-042 hub topology, where the hub
forwards bytes it never validated. The `payload` field is deliberately
schema-free JSON, so serde is on the attacker-controlled path with no
type-level defense.
3. **The failure classes that dominate real-world findings in Rust are
present in this codebase's shape, and several already have concrete
candidate findings.** The rust-fuzz trophy case (250+ entries) shows
that for Rust protocol crates the dominant bug classes are not memory
unsafety but: panics on untrusted input, integer/length arithmetic
errors, OOM via length-prefix-driven allocation, and unbounded state
growth. alkcall is safe Rust end-to-end (zero `unsafe` blocks —
verified), which means **no memory-corruption class at all**, but every
other class maps directly onto code in `src/` (see §5 and §6.2).
The strongest single datapoint: **RUSTSEC-2026-0037 / CVE-2026-31812
(quinn-proto, March 2026, CVSS 8.7)** — a remote DoS via `unwrap()` in
transport-parameter parsing. The maintainers' post-incident statement was
explicit: *"we did not have sufficient fuzzing coverage to find this issue.
We have since added a fuzzing target to cover this code path."* quinn-proto
is structurally very close to alkcall (async Rust RPC-ish protocol crate,
safe Rust, peers on the wire). A panic on attacker wire bytes in this crate
would be the same CVE class — and "the code is well tested" did not save
quinn, because conventional tests do not randomly explore malformed inputs.
**The honest caveat (why this was not obviously required before):** alkcall
has no `unsafe`, uses serde_json (whose 128-depth recursion limit and
non-panicking parser absorb most JSON pathology), bounds both length
prefixes before allocating (64 MiB frame cap, 16 MiB chunk cap — both
verified), and has solid round-trip unit tests. So the *expected* yield is
not memory-safety bugs; it is (a) panic-class bugs in hand-rolled dispatch
parsing, (b) the DoS-class findings in §6.2 which no amount of
example-based testing would have caught, and (c) regression protection for
two stable wire formats. If the campaign's first months find nothing, that
is a successful negative result, not a wasted one — it converts "we think
the parsers are robust" into a demonstrated property.
---
## 2. Tool landscape (2025–2026 snapshot)
| Tool | Version (date) | Engine | Toolchain | Status / verdict for alkcall |
|---|---|---|---|---|
| `cargo-fuzz` | 0.13.2 (2026-06) | libFuzzer | nightly required | **Recommended primary.** Actively maintained (rust-fuzz org), 3 releases since mid-2025, the de-facto standard; every surveyed protocol crate uses it. |
| `libfuzzer-sys` | 0.4.13 (2026-06) | libFuzzer runtime | via cargo-fuzz | Re-exports `arbitrary`; `fuzz_target!` accepts any `Arbitrary` type. |
| `arbitrary` | 1.4.2 (2025-08) | bytes → structured values | stable | **Recommended for structured targets.** `#[derive(Arbitrary)]`; 1.4.x brought notable fuzzing-speed wins. |
| `afl` (afl.rs, wraps AFL++) | 0.18.2 (2026-05) | AFL++ | **stable OK** | Recommended secondary/optional engine — long campaigns, multi-core, no nightly needed. CMPLOG on by default. |
| `honggfuzz` | 0.5.62 (2026-08) | honggfuzz | stable OK | Usable but upstream quiet since mid-2024; no reason to prefer over the above. |
| `bolero` | 0.13.4 (2025-07) | front-end: libfuzzer/AFL/honggfuzz/**Kani**/plain `cargo test` | stable for test/random | Attractive "same test, both engines" model, production-proven at s2n-quic. Considered and **deferred** (§7). |
| `libafl` | 0.16.1 (2025-08) | library for building fuzzers | stable | State of the art but a framework, not a tool; overkill for byte-buffer parser targets. Revisit only for stateful connection fuzzing. |
| OSS-Fuzz | — | hosted service | nightly (provided) | Free continuous fuzzing; expects exactly the cargo-fuzz layout (`libfuzzer` + `address` only). Adopt after targets stabilize. |
| `proptest` / quickcheck | mature | random generation + shrinking | stable | Complement, not replacement: no coverage guidance. Good for round-trip properties in the normal suite. |
Corroborating detail on cargo-fuzz status: published on crates.io, install
via `cargo install cargo-fuzz`; subcommands `init`, `add`, `run`, `fmt`,
`tmin`, `cmin`, `coverage`; recent releases added `--fuzz-engine`,
`--disable-branch-folding`, codegen-units tuning, Windows/MSVC support.
libFuzzer itself is upstream-maintenance-mode (its authors moved to
Centipede), which is irrelevant in practice for Rust app crates —
cargo-fuzz remains the recommended path in the Rust Fuzz Book.
---
## 3. What comparable crates actually do
Full details in the research notes; the load-bearing patterns:
- **rustls** (the reference model): `fuzz/` workspace, 8 targets spanning
byte-parsers *and* full state machines; internals exposed to targets via
`#[cfg(fuzzing)] pub mod fuzzing` (targets get access without widening
the public API); invariants include consumption accounting
(`assert!(processed <= buf.len())`) and re-encode round-trips; fuzz
functions additionally exercised from plain unit tests; corpora in a
dedicated repo; CI runs **10 s per target on every push** + OSS-Fuzz
CIFuzz at 150 s on PRs.
- **quinn**: `#[derive(Arbitrary)]` structured inputs; the `packet.rs`
target asserts the decoder consumed exactly the input
(`assert_eq!(len, decoded.0.len() + rest)`); a stateful target replays
`Vec<Op>` op sequences against `StreamsState`. Post-CVE, this is the
closest structural analogue to alkcall.
- **quiche**: fuzzes the *whole* protocol handler with committed test
certs; 1800+ committed seed corpus files generated by a seed script; Mayhem for continuous fuzzing.
- **h2**: the standout e2e pattern — fuzz input interpreted as a *script*
for mock I/O (length-prefixed chunks drive every socket read/write), so
libFuzzer explores partial-write/partial-read interleavings through the
full tokio state machine.
- **prost**: libFuzzer + AFL side by side; decode-then-re-encode round-trip
invariant; committed seed corpus for the AFL side.
- **yamux / libp2p** (no fuzz targets — the cautionary example): rely on
quickcheck only; their hand-rolled length-prefix handling shows the
defensive patterns fuzzing would police — `MAX_FRAME_BODY_LEN` checked
**before** `vec![0; body_len]` (yamux `frame/io.rs`), "validate RPC
limits by parsing the wire format without allocating" (libp2p gossipsub
`validate_rpc_limits`).
- **s2n-quic**: bolero's flagship consumer — fuzz checks live as ordinary
`#[cfg(test)]` functions, run in normal CI as `cargo test` (corpus
committed as tarball per test), long-run under libFuzzer out-of-band,
and the same properties carry Kani proof attributes.
**Invariant taxonomy observed across all repos** (in ascending strength):
1. **No-panic** — baseline; `drop(result)` suffices because libFuzzer +
ASan + debug assertions catch panics.
2. **Consumption accounting** — decoder consumed exactly the expected
bytes; nothing lost or duplicated (quinn packet, rustls deframer).
3. **Round-trip** — `decode(encode(x)) == x` or `encode(decode(bytes))`
prefix-match (yamux, quiche qpack, s2n-quic, prost).
4. **Resource bounds** — attacker-controlled lengths rejected (or skipped
without allocating) before allocation; bounded map growth.
5. **Stateful op sequences** — structured `Vec<Op>` replay against
internal state machines (quinn streams, h2 MockIo).
CI is universal but budgeted: the norm is a short per-push smoke run
(10–300 s) plus a longer scheduled campaign; crash artifacts uploaded via
`actions/upload-artifact` on failure. Cargo corpora are committed by
quiche/rustls/s2n-quic, gitignored by quinn/h2.
---
## 4. Toolchain decision: cargo-fuzz + arbitrary, AFL optional, bolero deferred
**Primary: `cargo-fuzz` + `arbitrary`.** Rationale: it is what every
surveyed crate uses, so patterns and CI templates transfer directly; the
`fuzz_target!` macro accepts both raw `&[u8]` and `Arbitrary`-derived
types, which maps onto alkcall's two input shapes (malformed-byte hunting
vs. structured logic replay); OSS-Fuzz compatibility for free; nightly
requirement is confined to the fuzz job (a pinned nightly toolchain for
the `fuzz/` workspace only — the crate itself stays stable at MSRV 1.88
and the fuzz crate is excluded from publishing via `exclude` in
`Cargo.toml`).
**Secondary (optional, later): `afl` (AFL++).** Stable-toolchain, good for
long multi-core campaigns and as an independent engine to cross-check
findings (prost runs exactly this pairing). Not needed for the initial
rollout.
**Deferred: bolero.** The s2n-quic model (fuzz check colocated as a normal
unit test, replayed in CI with a committed corpus, long-run out-of-band)
has a real advantage for this repo specifically — alkcall has *no* `fuzz/`
workspace today and its tests are inline `#[cfg(test)]` modules, so
colocated checks fit the house style. But it adds a dependency and an
engine-selection layer between the code and cargo-fuzz, and none of the
RPC-protocol crates surveyed (quinn, rustls, prost, h2) use it. The
deciding factor: alkcall's highest-value targets are *async* (the framing
reader and demux loop are tokio-generic), and bolero's in-process test
form adds friction there (`#[tokio::test]` cannot drive `bolero::check!`
iteration without shims). Recommendation: start with a standard `fuzz/`
workspace; if corpus-replay-as-unit-test proves valuable later, adopting
bolero's pattern (or just hand-rolling a corpus-replay test, which quinn
does in plain `cargo test`) is a cheap follow-up. Note quinn's CI already
does plain corpus replay without bolero — that pattern is available
without any new dependency.
**Not adopted: libafl, honggfuzz, OSS-Fuzz (initially).** libafl is a
framework for bespoke fuzzers — unnecessary for parser targets. honggfuzz
is superseded. OSS-Fuzz is a strong *later* step once targets exist and
have been stable for a while (it is free continuous fuzzing and expects
exactly this target layout; both rustls and prost are on it).
**Sanitizer choice:** default `--sanitizer=address` with debug assertions
(cargo-fuzz's default config, `-O1`). MSAN is not warranted — with zero
`unsafe` there is no uninitialized-memory class; ASAN mainly adds
heap-buffer-overflow detection for slice math in hand-rolled framing and
double-free-style issues in vendored types, plus the debug-assertions
panic tripwire, which is the real detector here.
---
## 5. alkcall's untrusted-input parse surfaces (inventory)
Verified against the code (file:line as of 0.8.0). The crate is safe Rust
end-to-end: **zero `unsafe` blocks** (grep-verified). Two wire formats,
plus JSON-based op payloads:
| # | Surface | Location | Sync? | Notes |
|---|---|---|---|---|
| 1 | `EventEnvelope` framing decode | `src/protocol/wire.rs:204-232` | async (`read_frame`, generic over `AsyncRead`; tests already drive it with `std::io::Cursor`) | 4-byte BE length prefix; rejects len 0 and len > `MAX_FRAME_SIZE` (64 MiB) **before** `vec![0u8; length]` at `:221`; partial prefix/body handled (`ConnectionClosed`); serde_json parse of up to 64 MiB body. |
| 2 | Channels chunk header | `src/channels/wire.rs:96-112` (`parse_header`) | **sync, pure, no allocation** | `len >= 8` check, `length > MAX_CHUNK_LEN` (16 MiB) rejected before payload exists. `write_header` at `:123`. |
| 3 | Demux loop | `src/channels/adapter.rs:126-222` (`run_demux_loop_for_client`, pub) | async | `parse_header` → bounded alloc (`:181`) → `route_payload`; `TooLarge` branch skips in 64 KiB reads with a cumulative 256 MiB budget (`:137`, `:153-170`) instead of allocating; EOF → `clear_all`. |
| 4 | `ChannelManager` routing | `src/channels/manager.rs:439-457` (`route_payload`), `:463-485` (`park_early_arrival`) | async (bounded send await) | Unknown ids park up to `EARLY_ARRIVAL_CAP = 64` chunks per id; **the map's key-space is unbounded** (see §6.2). |
| 5 | Spec rebuild from wire | `src/client/from_call.rs:209-310` (`rebuild_spec_for`, `pub(crate)`, sync pure) | sync | Remote-announced op specs: op_type/visibility/access_control/error_schemas/`publish_schema` — attacker-shaped JSON becomes compiled `jsonschema` validators at registration. |
| 6 | `op/register` DTO | `src/registry/op_register.rs:66-84` (`OpRegisterRequest::from_json`, `pub`, sync pure) | sync | Wraps `rebuild_spec_for` + replace flag. |
| 7 | Pending-request state machine | `src/protocol/pending.rs:111-229` (sync, `pub`) | sync | `handle_responded/completed/aborted/error`, eviction. |
| 8 | Abort cascade | `src/protocol/abort.rs:46` (`cascade_abort`, sync pure) | sync | Tree walk; O(n²) descendant search (§6.2). |
| 9 | Dispatch payload parsing | `src/protocol/dispatch.rs:341-412` (`dispatch_start`), `:646-770` (`pump_sink`), `:897-1027` / `:1120-1250` (single-stream loops) | sync-prefix / async | `payload.get(...)` extraction, `forwarded_for` as `serde_json::from_value::<Identity>`, `call.error` → `CallError`, jsonschema validation of published chunks. |
| 10 | Client-side envelope pump | `src/protocol/connection.rs:693-741` (`read_single_stream_until_closed`, `dispatch_envelope`) | async | pub; decode → pending-resolution pump. |
| 11 | Channel lifecycle ops | `src/channels/operations.rs:182-272` (close/control handlers) | async | `as_u64` → `as u32` cast truncation on `channel_id`. |
| 12 | Relay reply parsing | `src/channels/relay.rs:239-297` (`open_on_producer_leg`), `:308-335` (`map_spoke_error`) | async | reply `channel_id` extraction, `details.reason/message`. |
Also relevant: **`jsonschema` is compiled from schemas that arrive from
the wire** (`from_call.rs:299-303` announced `publish_schema` /
`input_schema`; enforced per chunk at `dispatch.rs:706-718`,
`registration.rs:257-274`) — a compilable-but-pathological remote schema
is a CPU-amplification class the fuzz campaign can probe.
Non-surfaces (deliberately): no TTY/SFTP/varint parsers in this crate; the
channels layer carries opaque `Bytes` and the handler owns sub-stream
framing (ADR-035) — those downstream parsers are downstream crates' fuzz
targets.
---
## 6. Findings the campaign should target (candidate issues in current code)
These are pre-fuzzing code-review findings (mine, verified at 0.8.0) that
define what the fuzz targets must encode as invariants. They are also, in
effect, the first candidates for the fuzzer to confirm or refute.
### 6.1 Framing and parse invariants (encode as assertions in targets)
1. **No-panic on any byte sequence** for both framing paths and all sync
pure parsers — the baseline every target asserts by existing.
2. **Consumption accounting** — `read_frame` consumes exactly
`4 + length` bytes for a valid frame; `parse_header` reads exactly 8.
3. **Round-trip** — envelope encode→decode (structural equality; note
serde_json runs **without** `preserve_order` in this crate's dep tree,
so `Value` object key order is not preserved — byte-identity round-trip
asserts are invalid for envelopes; use structural equality); chunk
header encode→decode identity.
4. **Allocation bounds** — decode paths never allocate more than
`MAX_FRAME_SIZE` / `MAX_CHUNK_LEN` for any input.
5. **Termination** — demux skip loop obeys the 256 MiB budget and always
terminates on a trickle-feed peer.
### 6.2 DoS-class candidate findings (pre-fuzz code review)
1. **Unbounded early-arrival key-space** — `ChannelManager.early_arrivals`
(`src/channels/manager.rs:102`, `park_early_arrival` `:463-485`) caps
parked chunks **per key** at 64, but nothing bounds the number of
distinct never-adopted `channel_id` keys. A peer spraying unknown ids
parks up to 64 chunks × up to 16 MiB *per distinct id* until
`clear_all` at EOF — an OOM class on a long-lived connection. A fuzz
target driving `route_payload` with arbitrary ids and payloads, with a
total-bytes-parked assertion, will find this class immediately.
2. **Unbounded per-connection task accumulation** — `spawned: Vec<JoinHandle>`
(`src/protocol/dispatch.rs:894-895`, pushed at `:914`, drained only at
loop end `:1030-1032`, and the channel-0 twin `:1115-1118`,
`:1253-1255`): one task per inbound `call.requested`, no cap on
concurrent requests per connection. Cheap-request spam grows the
vector unboundedly for the connection's life.
3. **64 MiB pre-payload allocation window** — `read_frame` allocates
`vec![0u8; length]` after validating ≤ 64 MiB but *before reading any
payload byte* (`src/protocol/wire.rs:217-221`): repeated 4-byte
headers force repeated 64-MiB zeroing (allocation-rate pressure).
Bounded per frame, but worth a target asserting decode never
allocates beyond the cap and exploring whether a read-into-capped-
buffer refactor (libp2p gossipsub's validate-without-allocating
pattern) is warranted.
4. **O(n²) abort cascade** — `find_descendants` scans the full pending map
per frontier step (`src/protocol/abort.rs:80-104`); many pendings + an
abort = quadratic CPU. An op-sequence target on `PendingRequestMap` +
`AbortCascade` with many registered requests will surface it.
5. **Remote-schema CPU amplification** — compiled-from-wire jsonschema
validators applied per published chunk (§5); pathological-schema
generation is a semantic fuzz target.
Items 1 and 2 are the strongest arguments that fuzzing (specifically
*stateful*, not just parser-level fuzzing) is warranted here: they are
resource-bound bugs in correct-looking safe Rust that example-based tests
structurally cannot find, in code paths every downstream consumer exposes
to peers.
---
## 7. Recommendation
### 7.1 Adopt fuzzing; scope it to the wire surface
Create `fuzz/` via `cargo fuzz init` (cargo-fuzz ≥ 0.13; keep the fuzz
crate in the main workspace, its default since 0.11.4), add `fuzz/` and
`fuzz/artifacts/` to `.gitignore`, add `"fuzz"` handling to the publish
exclude list if needed (cargo-fuzz's generated layout is already
workspace-compatible). Add five targets, in priority order:
| # | Target | Input style | Drives | Invariants |
|---|---|---|---|---|
| 1 | `chunk_header` | raw `&[u8]` | `parse_header` / `write_header` (`channels/wire.rs`) | no-panic; round-trip identity; `TooLarge` iff `len > MAX_CHUNK_LEN`; consumption accounting (8 bytes) |
| 2 | `envelope_frame` | raw `&[u8]` | `FrameFramedReader::new(Cursor::new(bytes)).read_frame()` under a current-thread runtime's `block_on` (tests already use `Cursor`, `wire.rs:534`) | no-panic; never allocates > `MAX_FRAME_SIZE`; clean `FrameError` on truncation/oversize/zero-length; consumption accounting |
| 3 | `manager_routing` | op-sequence: `#[derive(Arbitrary)]` enum over `{ route_payload(id, bytes), adopt, teardown, clear_all, … }` | `ChannelManager` | **total parked-bytes bound** (§6.2-1); no-panic; id-uniqueness invariants |
| 4 | `envelope_semantic` | `#[derive(Arbitrary)]` envelope-shaped input | constructors → `write_frame` → `read_frame` round-trip | structural round-trip; `CallError` payload parse never panics |
| 5 | `spec_parse` | raw bytes → `serde_json::Value` → `rebuild_spec_for` / `OpRegisterRequest::from_json` | sync pure parsers | no-panic; registration always `Result`; round-trip vs `spec_to_json_pub` |
Second wave (after the first five stabilize, roughly in quinn's
`streams.rs` style): a pending-map/abort op-sequence target (§6.2-4), a
demux-loop byte-sequence target through `run_demux_loop_for_client`
(needs a small current-thread runtime and a spawned mux runner), and a
client-pump target on `read_single_stream_until_closed`.
**Corpus policy: commit hand-made seeds, gitignore grown corpora** (the
quinn/h2 pattern). Seeds per target: valid frame/header, truncation at
every prefix length, `length = 0`, `length = MAX+1`, `length = u32::MAX`,
channel 0, invalid UTF-8 in JSON, deep-ish nesting. libFuzzer runs fine
without seeds but is far more efficient on structured inputs. Seed
generation can be scripted from existing unit tests (quiche's
`gen_fuzz_seeds.sh` pattern).
**Where internals need exposure:** follow quinn/rustls — `#[cfg(fuzzing)]
pub mod fuzzing` modules re-exporting `pub(crate)` items
(`rebuild_spec_for`) rather than widening the public API. The crate
already has `pub` sync parsers (`parse_header`, `from_json`,
`PendingRequestMap`), so exposure needs are small.
### 7.2 CI: two-tier, rustls-style
1. **Per-push smoke** (cheap, catches build rot and shallow bugs): pinned
nightly toolchain + pinned cargo-fuzz; `cargo fuzz build`; then per
target `cargo fuzz run <t> -- -max_total_time=10` (rustls's exact
budget) in a small matrix; upload `fuzz/artifacts` on failure.
2. **Scheduled campaign** (weekly at first; cron-driven Actions workflow):
`-max_total_time=1800` (30 min) per target with a cached corpus
(Actions cache, `restore-keys` prefix matching) and `-fork=$(nproc)`;
grow corpora incrementally. This is the depot.dev pattern; adopt it
only after the smoke tier is green for a while.
3. **No-cargo-fuzz fallback for PRs**: since nightly is a dedicated-job
concern, an even cheaper PR gate is `cargo test --manifest-path
fuzz/Cargo.toml` (replays the committed corpus through the targets as
plain unit tests — quinn's CI does this; corpus replay costs nothing
and prevents seed rot).
libFuzzer flags worth pinning in the targets' run configs:
`-rss_limit_mb=2048` (the OOM tripwire — directly relevant to §6.2-1/3),
`-max_len=65536` on framing targets, `-timeout=25` (well under CI job
limits), `-use_value_profile=1` (helps get past length/JSON-prefix
comparisons), and a `-dict` of JSON tokens for the envelope targets.
### 7.3 What not to do
- **Do not** gate regular development on nightly: fuzz tooling lives
entirely in `fuzz/` + the fuzz CI job; `cargo test` / MSRV / wasm
targets are untouched.
- **Do not** assert byte-identity round-trips for `Value` payloads
(serde_json without `preserve_order` sorts object keys — structural
equality only). This would generate false positives from day one.
- **Do not** commit grown corpora to git at first (quinn/h2 model);
revisit if the scheduled campaign produces inputs worth curating.
- **Do not** reach for libafl/OSS-Fuzz/Mayhem until the five initial
targets are stable; OSS-Fuzz onboarding is the natural next step after
that (free continuous fuzzing, expects exactly this layout).
### 7.4 Sequencing
1. `cargo fuzz init` + first two targets (`chunk_header`, `envelope_frame`)
— highest value, lowest setup (both are thin wrappers over existing
sync/`Cursor`-drivable APIs). **Done — see §7.7.**
2. Run a local 10–30 min campaign per target **via the detached runner
(§7.6 — never in the foreground of an agent session)**; fix anything
found; triage §6.2 candidates with targeted corpus entries.
**Done for targets 1–2 — see §7.7.**
3. Add targets 3–5, the smoke CI job, and `.gitignore` entries.
**Targets 3–5 done, campaigns clean — see §7.8. The CI job will not
exist — see §7.9 (no hosted CI policy); the stable-side corpus
replay `cargo test --manifest-path fuzz/shared/Cargo.toml` is in
the release verification checklist instead (AGENTS.md).**
4. ~~Scheduled campaign tier; then OSS-Fuzz application.~~ **Not
planned — see §7.9.** Long campaigns are run manually via the
detached runner (§7.6) when wanted; OSS-Fuzz is out (it requires
hosted infrastructure and a public repo posture this project does
not have).
### 7.5 Relationship to existing tests
The existing suite is strong on *valid-input* round-trips and documented
error paths (framing tests at `wire.rs:262-588`, demux skip tests at
`adapter.rs:279-693`, spec round-trips at `from_call.rs:634-1053`). What
no example-based suite provides, and what fuzzing adds:
- random *malformed* input exploration (the quinn CVE class),
- stateful interleavings (many ids × many ops, the §6.2-1/2 classes),
- resource-bound assertions under unbounded adversarial sequences.
Two zero-cost complements, available without any new toolchain: (a) replay
committed corpora as unit tests in normal CI (quinn's pattern — add it
from day one, it is two lines of CI); (b) a quickcheck-style round-trip
property test for the chunk header (yamux's pattern) if the team wants
in-suite fuzz-adjacent coverage without nightly. Both are optional
nice-to-haves; the core recommendation is the `fuzz/` workspace.
### 7.6 Operational isolation: fuzzing must never share fate with the agent session
This one is an environment constraint, not a nice-to-have. 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 (that's what §6.2-1/3 look for). If libFuzzer's own RSS guard
is miscalibrated or races the kernel, the kernel OOM killer fires — and
it picks the largest-RSS process in the *cgroup*, which can be the
opencode server hosting the session, killing the agent mid-run. An
OOM in a fuzz target must cost the fuzzer, never the session.
- **Fork bombs and CPU saturation**: `-fork=N` mode spawns many workers;
a runaway campaign or a buggy target with unbounded task spawning can
starve the session host's CPU/IO.
- **Interactive-shell edge cases**: libFuzzer prints status lines that
confuse non-TTY shells; a crashed fuzzer must never leave the tool's
bash session hanging.
Three layers of defense, all standard, cheapest first:
1. **libFuzzer's own soft limits (always on)**: `-rss_limit_mb=2048` +
`-malloc_limit_mb=2048` make libFuzzer *exit cleanly* (report the
input as OOM-class artifact) when the target exceeds the budget, before
the kernel gets involved. This is the primary defense and it is
already part of the §7.2 flag set. Note the libFuzzer RSS limit is
**soft** (it polls `/proc/self/statm` in a background thread and
exits), not a hard rlimit — a fast single huge allocation can still
beat it; that's what layers 2–3 are for. Do **not** use `ulimit -v`
with ASAN/MSAN (the sanitizer reserves terabytes of virtual address
space; the classic failure mode is immediate `MmapAlloc` death) — the
equivalent knob under ASAN is `malloc_limit_mb`, and libFuzzer's
documented recipe for hard-limiting RSS under sanitizers is `-fork=1`
(see next item).
2. **Fork mode as the blast-radius containment (default for local
campaigns)**: `-fork=1` (or `$(nproc)`) runs each input in a short-
lived child process. A target crash, timeout, OOM, or leak kills only
that one-shot child; the parent harness survives, records the artifact,
and keeps fuzzing. This is libFuzzer's own documented containment
model — and it is mutually exclusive with in-process ASAN crash
reporting (the child still detects, the parent persists the evidence).
Fork mode also solves the *other* shared-fate trap: a target that
deadlocks no longer hangs the campaign (per-input timeout kills the
child, not the session's bash call).
3. **Process detachment from the session tree (mandatory for agent-run
campaigns)**: agent sessions must never run fuzzing as a foreground
child. The runner script below wraps `cargo fuzz run` in
`setsid` + `nohup` + stdin/stdout/stderr redirection to a log file,
which (a) removes the fuzzer from the session's controlling terminal
and signal-relation, (b) makes the run survive the session ending, and
(c) gives the agent a pollable log/artifact tail instead of a blocking
call. Combined with fork mode, an OOM-class finding costs one child
process; combined with the soft RSS limit, the kernel OOM killer should
never be the discovery mechanism at all.
The detached-runner recipe for agent sessions (write as
`fuzz/run-detached.sh` in the implementation step, not inline in a tool
call):
```bash
#!/usr/bin/env bash
# Detached fuzzing runner for agent sessions: the fuzz campaign never
# runs as a foreground child of the session (OOM in a target must not
# take down 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}"
log="fuzz/artifacts/${target}-$(date -u +%Y%m%d-%H%M%S).log"
mkdir -p fuzz/artifacts
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"
```
Polling protocol for the agent: `tail -n 50 fuzz/artifacts/<target>-*.log`
and check `fuzz/artifacts/` for `crash-*`/`oom-*`/`timeout-*` files
periodically; `pgrep -f "cargo fuzz run <target>"` to see if it is still
running. Never `wait` on the detached process from a tool call — poll
instead. One session can hold one detached campaign per target; the log
filename carries the UTC timestamp.
**For CI the constraint does not apply** (the runner *is* the job), but
the same flags apply everywhere: `-rss_limit_mb`/`-malloc_limit_mb` and
`-fork=1` should be pinned in the target run configs in both the smoke
tier and the scheduled campaign. For the scheduled campaign tier, also
cap concurrency (`-fork=$(nproc)` is fine on CI runners; locally prefer
an explicit number well below core count) and keep the Actions-job
timeout above the `-max_total_time` budget so a wedged harness is killed
by the runner, not the host.
---
## 7.7 Implementation status (step 1 of §7.4, 2026-09-27)
**Adopted.** The `fuzz/` workspace exists with targets 1 and 2 from
§7.1, committed seed corpora, the detached runner, and stable-side
corpus replay. Everything below is verified in-tree.
### Layout (as implemented)
```
fuzz/
├── Cargo.toml alkcall-fuzz (nightly-only bins; own [workspace])
├── rust-toolchain.toml pins nightly for this subtree only
├── fuzz_targets/
│ ├── chunk_header.rs thin fuzz_target! wrapper
│ └── envelope_frame.rs thin fuzz_target! wrapper
├── shared/ alkcall-fuzz-shared — STABLE-toolchain library
│ └── src/{chunk_header,envelope_frame}.rs invariant logic + corpus replay
├── corpus/{chunk_header,envelope_frame}/ committed seeds (245 total)
├── gen_fuzz_seeds.py deterministic seed generator (quiche pattern)
├── run-detached.sh §7.6 detached runner (CWD-independent)
├── json.dict JSON token dictionary for envelope targets
└── README.md
```
Deviations from the §7.1 sketch, all load-bearing:
- **The invariant logic lives in `fuzz/shared/` (a separate
stable-toolchain crate), not inline in the target binaries.** This
makes §7.2's tier-3 fallback (corpus replay as plain `cargo test`)
real from day one: `cargo test --manifest-path fuzz/shared/Cargo.toml`
replays every committed seed through the identical invariant functions
the fuzzer runs, on stable, in normal CI. The `fuzz_target!` binaries
are three-line wrappers.
- **The root `Cargo.toml` gained a `[workspace]` table
(`members = ["."]`, `exclude = ["fuzz"]`)** and `"fuzz/"` joined the
publish `exclude` list. Without the explicit workspace table, cargo
auto-discovers `fuzz/shared/` into the main workspace and the MSRV
toolchain tries to build the nightly-consumed dev-deps.
- **`fuzz/rust-toolchain.toml` pins `nightly`** for the fuzz subtree so
`cargo fuzz build` works from any CWD (rustup resolves toolchains per
directory; the initial build attempt from the repo root picked the
stable toolchain and failed on `-Zsanitizer`). Nightly remains
confined to `fuzz/` — the crate itself stays stable at MSRV 1.88.
- **No `#[cfg(fuzzing)]` exposure was needed.** Both target APIs were
already `pub`: `parse_header`/`write_header` (`channels/wire.rs`) and
`FrameFramedReader`/`FrameFramedWriter` (`protocol/wire.rs`). The one
private item, `MAX_FRAME_SIZE` (`wire.rs:20`), is a wire-stable
constant (ADR-014), so the shared crate carries its own copy
(16 MiB/64 MiB are one-way-door values; a drift would be caught by the
shape invariants, which assert the rejection boundary).
- **Seeds are committed** (245 files), gitignored artifacts/corpus-grown
per the generated `fuzz/.gitignore`; the generator script
(`gen_fuzz_seeds.py`) is committed next to them.
### Invariants encoded (beyond the §7.1 table)
`chunk_header`:
- no-panic; round-trip identity (`write_header(parse_header(x)) ==
x[..8]`); `TooLarge` iff `length > MAX_CHUNK_LEN` with the parsed
`length` echoed in the error; `HeaderTooShort` iff `< 8` bytes with
exact `need`/`have`; `is_eof() == (length == 0)`; consumption
accounting (8 bytes); **input buffer never mutated**.
`envelope_frame`:
- no-panic; clean error classes with **shape assertions** on each
`FrameError` variant: `ConnectionClosed` only when the prefix is
truncated or the body is short (a complete body must never yield it);
`InvalidFrame` only for `len == 0` or `len > MAX_FRAME_SIZE`;
`Json` only when the full body was present; `Io` impossible on a
Cursor; Ok only when `len > 0`, `len <= MAX`, body complete.
- allocation bound: the reader never allocates for `len > MAX_FRAME_SIZE`
or `len == 0` (rejection precedes `vec![0u8; length]` — verified by the
`InvalidFrame`/Ok shape partition).
- exact consumption accounting (4 + len bytes read for a valid frame).
- structural round-trip: every decodable envelope re-encodes via
`write_frame` and re-decodes to an equal envelope (structural —
serde_json without `preserve_order` does not preserve key order).
- serde contract: the decoded envelope serializes with `type`/`id`/
`payload` keys intact (`type` survives the rename).
- **trailing-byte probe**: for any input ending in a complete JSON
object body, a copy with one extra byte appended *and counted in the
length prefix* must fail with a `Json` error (serde_json's
from_slice rejects trailing non-whitespace) — catching any future
switch to a streaming/tolerant reader that would silently accept
junk after the JSON document.
Note on the probe: the length prefix counts **only the body**, not the
4-byte prefix — the first probe draft claimed `4 + len + 1` and tripped
its own shape assert (`ConnectionClosed`). The fuzzer would have found
that instantly; corpus replay found it first.
### Verification at adoption
- `cargo fuzz build` clean (nightly-1.95.0-nightly, cargo-fuzz 0.13.2,
libfuzzer-sys 0.4.13).
- Stable side untouched and green: `cargo test` 682 passed / 0 failed;
`cargo clippy --all-targets -- -D warnings` clean; `cargo fmt --check`
clean (main crate, fuzz workspace, and fuzz/shared).
- Corpus replay (`cargo test --manifest-path fuzz/shared/Cargo.toml`):
245 committed seeds through both invariant sets, green.
Commit: 80a37e9 (step-1 implementation, before the campaigns below ran).
### Campaign results (10-min detached runs per target, §7.6 runner)
**No crashes, no hangs, no leak/OOM findings.** Both campaigns ran to
their time budget via `run-detached.sh` and exited 0 (`-fork=1
-rss_limit_mb=2048 -malloc_limit_mb=2048 -timeout=25`;
`-max_len=65536 -dict=json.dict` for the envelope target); artifact
directories empty after both.
- `chunk_header` — saturated its state space in the first seconds and
spent the remaining ~10 min confirming stability: flat
`cov: 51 ft: 54` from job ~5 onward, 203.9M execs at ~350k exec/s,
`oom/timeout/crash: 0/0/0` on all 33 fork jobs. The pure-8-byte-parser
ceiling is fully enumerated.
- `envelope_frame` — still finding coverage when the budget ended:
2119 edges / 7246 features / 1664 in-memory corpus entries
(from the 245 committed seeds), ~7.08M execs at ~12k exec/s,
`oom/timeout/crash: 0/0/0` on all 33 fork jobs. Growth was still
positive (JSON structure exploration), so longer campaigns keep
paying; the 25 s timeout and both memory tripwires never fired.
The grown envelope corpus (1631 new entries) was **not** merged into
the committed seeds — per the §7.1 policy, grown corpora stay
gitignored; worth revisiting if a future scheduled campaign produces
inputs worth curating. §6.2-3 (pre-payload allocation window) remains
bounded as designed. §6.2 items 1/2/4/5 are stateful targets
(§7.4 step 3) and were not exercised by these parser-level campaigns.
---
## 7.8 Step 3: targets 3–5 (2026-09-27)
**Adopted.** Three more targets, all over already-`pub` APIs (the
`#[cfg(fuzzing)]` exposure never materialized — quinn/rustls-style
exposure has not been needed for any of the five targets):
| Target | Drives | Invariants |
|---|---|---|
| `manager_routing` | `ChannelManager` under `#[derive(Arbitrary)]` op sequences (`Route`/`Open`/`Adopt`/`Teardown`/`ClearAll`), 256 ops × 4 KiB payloads, live mux runner, drainer tasks | no-panic; **exact counter models**: harness parked/dropped counters must equal the manager's monotonic `early_arrival_count`/`dropped_unknown_chunks` after every op; parked bytes ≤ distinct-ids × 64 × 16 MiB (the documented per-channel bound, §6.2-1); post-sequence `clear_all` reconciles every routed byte against the drainers' totals (lossless bounded-buffer routing, sentinel semantics included) |
| `envelope_semantic` | `#[derive(Arbitrary)]` `EnvelopeKind` → the six `EventEnvelope` constructors → serde round-trip → `write_frame`/`read_frame` | no-panic; constructors emit exactly the wire-stable event-type constants; any `Value` payload survives a serde round-trip; `call.error` payloads always parse back as `CallError` (ADR-016 closed schema); structural `write_frame`/`read_frame` round-trip |
| `spec_parse` | raw bytes → `serde_json` → `OpRegisterRequest::from_json` (the `pub` wrapper over `rebuild_spec_for`) → `OperationRegistry::register` (attacker-shaped schemas **compile at registration**, CF-003) | no-panic; parse failures are clean `INVALID_INPUT`; `spec_to_json_pub` → `from_json` round-trips the rebuilt spec; registration is always `Result` (uncompilable schema = compile error, never silent); registry bookkeeping survives repeated attacker-shaped inserts |
New supporting pieces: `fuzz/shared/src/arbitrary_value.rs` (a bounded
`Arbitrary` impl for `serde_json::Value` — depth 6, width 6, sized
strings/keys), and 20 `spec_parse` + 4 `manager_routing` committed
seeds (the op-sequence corpus is tiny because structured `Arbitrary`
inputs self-generate; the four committed seeds are semantic fixtures
including the duplicate-adopt sequence that pinned the bug below).
### First real finding: duplicate adopt/open destroyed the live channel
The `manager_routing` campaign found it in its first minutes — the
§6.2 stateful thesis, confirmed: **the bug is invisible to
example-based tests** because it needs an *interleaving* (adopt → drop
write half → duplicate adopt → route) that no unit test thinks to
replay.
**Mechanism** (`src/channels/manager.rs`, `open_channel` and
`adopt_channel`, pre-fix):
```rust
if channels.insert(channel_id, state).is_some() {
return Err(ManagerError::ChannelExists(channel_id));
}
```
`HashMap::insert` **replaces** an occupied entry and returns the old
value — so the collision-detection idiom silently *installed the new
state and dropped the old `ChannelState`*, whose `demux_sender` was
the live channel's read half. A duplicate `adopt_channel`/`open_channel`
on an in-use id returned `Err(ChannelExists)` (correct) **while
destroying the live channel** (incorrect): readers saw a spurious EOF,
subsequently routed chunks were lost, and the mux write half kept
framing onto the transport for a channel the demux no longer fed.
Reproducibility: a failed adopt on a live channel whose mux pump had
finished (the write half dropped — as any caller does) re-registered a
pump, succeeded through `mux.register`, and hit the replacing insert.
The duplicate-adopt path is reachable whenever an open-op response is
replayed or a connection-owner race re-announces an id.
**Fix** (this commit): check `channels.contains_key(&channel_id)` and
return before any insert — the map is never touched on collision in
either `open_channel` or `adopt_channel`. Regression tests:
`adopt_channel_duplicate_id_leaves_live_channel_intact`,
`open_channel_duplicate_id_leaves_live_channel_intact` (both verify
routing survives a rejected duplicate; the first also verifies the
EOF sentinel remains the only EOF source).
**Also fixed in the harness** (fuzzer-vs-harness findings, not crate
bugs): `clear_all` returns the opener-ledger entries (ADR-047 §7),
not channel-map entries — adopted channels carry no ledger entry, so
`drained.len() == open_count()` is *not* an invariant; the monotonic
counters survive `clear_all`; and drainer-byte reconciliation needs
per-id supersession when a fresh stream replaces a drained one.
### Campaign results (10-min detached runs per target, §7.6 runner)
The smoke-tier runs above surfaced two harness-model defects worth
recording (the fuzzer as a harness-checker), fixed before the long
runs: the op-sequence driver's EOF-sentinel latch is **per-receiver,
not per-channel-id** — a fresh adopt installs a fresh reassembled
stream with no latched EOF, while a sentinel inside a *drained
early-arrival queue* latches the new receiver too
(`drain_early_arrivals` delivers it); and `Adopt` ops must respect
ADR-047 §5's odd/even split (an Accept-side manager adopts the peer's
odd ids; its own `Open` allocates even — a cross-range adopt/open
collision is a protocol violation, not a manager bug).
**Final 10-minute detached campaigns, all three targets (post-fixes,
post the `insert`-replace fix): every run exited 0 with an empty
artifacts directory — no crashes, hangs, OOMs, or leaks.**
- `manager_routing` — 1.06M execs (~1.9k exec/s; each exec replays up
to 256 manager ops on a live runtime), 33 fork jobs clean,
`oom/timeout/crash: 0/0/0` throughout. Final coverage 2499 edges /
11332 features / 461 in-memory corpus entries. The exact-counter and
parked-bytes invariants held across every adversarial sequence.
- `envelope_semantic` — 2.44M execs (~4.4k exec/s), 33 fork jobs
clean, coverage saturated at 1669 edges (constructor × payload shape
space is finite), corpus 765. All six event kinds round-tripped
structurally; `CallError` parse-back never failed.
- `spec_parse` — 10.8M execs (~19k exec/s), 33 fork jobs clean,
coverage 978 edges / corpus 1267. The registry compiled every
attacker-shaped schema it was handed (or rejected cleanly); the
`spec_to_json_pub` → `from_json` round-trip never diverged.
§6.2-1 (parked-bytes bound) is now encoded as an exact counter model
and held; §6.2-3 confirmed bounded at the parser level (§7.7). The
stateful coverage §7.4 step 3 called for exists and is clean.
---
## 7.9 No hosted CI — the standing policy (2026-09-28)
§7.2's two CI tiers (per-push smoke, scheduled campaign) and the
OSS-Fuzz step assume a hosted CI platform. This repo has none and will
not get one: the git host is a minimal gitea that serves git and
nothing else, deliberately — gitea/gitlab have had full-compromise CVEs
(app.ini and any plaintext DB tokens exfiltrated in one real incident
elsewhere), so the attack surface stays minimal. All verification and
campaigns are **manual, run from the separate publishing server**:
- **Corpus replay is the fuzz gate, as plain `cargo test`:**
`cargo test --manifest-path fuzz/shared/Cargo.toml` replays every
committed seed through the same invariant functions the fuzzer runs
— on stable, no nightly, no cargo-fuzz. It is part of the release
verification checklist (AGENTS.md). This is CI tier 3's deliverable
(§7.2), minus the automation.
- **Campaigns** run via the detached runner (§7.6) when wanted —
e.g. before a release, or after touching `src/protocol/wire.rs`,
`src/channels/wire.rs`, the demux loop, or `ChannelManager`.
- **OSS-Fuzz is out**: it requires hosted infrastructure and a public
repo posture this project does not have.
- Do not add Actions/Gitea-Actions/workflow files anywhere in this
repo, and do not reintroduce "when CI exists" language into docs —
point at this section instead.
## 8. Answering the "if / how" directly
- **If?** Yes — justified by position in the dependency graph, two stable
attacker-reachable wire formats, and two concrete DoS-class findings a
fuzz campaign would have caught (§6.2). The expected bug classes here
are panics and resource exhaustion, not memory unsafety (no `unsafe`
exists), which is precisely the profile where cheap fuzzing pays off.
- **How?** `cargo-fuzz` + `arbitrary`, a standard `fuzz/` workspace with
five targets (§7.1), committed seed corpora only, `#[cfg(fuzzing)]`
internals exposure where needed, two-tier CI with a 10 s-per-target
smoke on every push (§7.2), nightly confined to the fuzz job, AFL as an
optional secondary engine, bolero deferred, OSS-Fuzz after
stabilization. **Locally (agent sessions), campaigns always run via the
detached runner (§7.6): `setsid` + `nohup` + log file + poll, fork mode
on, soft RSS/malloc limits pinned — an OOM in a fuzz target must cost
the fuzzer, never the agent session.**
## 9. References
- RUSTSEC-2026-0037 / CVE-2026-31812 (quinn-proto remote DoS; maintainers'
fuzzing-coverage statement) — https://rustsec.org/advisories/RUSTSEC-2026-0037.html
- cargo-fuzz releases / Rust Fuzz Book — https://github.com/rust-fuzz/cargo-fuzz ·
https://rust-fuzz.github.io/book/
- arbitrary 1.4.2 and the 2025 speed analysis —
https://nnethercote.github.io/2025/08/16/speed-wins-when-fuzzing-rust-code-with-derive-arbitrary.html
- rustls fuzz targets + CI — https://github.com/rustls/rustls/tree/main/fuzz ·
https://github.com/rustls/rustls-fuzzing-corpora
- quinn fuzz targets (packet/streams/params) — https://github.com/quinn-rs/quinn/tree/main/fuzz
- quiche fuzzing + seed generation — https://github.com/cloudflare/quiche/tree/master/fuzz
- h2 MockIo e2e target — https://github.com/hyperium/h2/tree/master/fuzz
- prost fuzz (libfuzzer + AFL, FUZZING.md) — https://github.com/tokio-rs/prost/tree/master/fuzz
- s2n-quic bolero corpus-per-test pattern — https://github.com/aws/s2n-quic
- yamux allocation guard / libp2p validate-without-allocating —
https://github.com/libp2p/rust-yamux ·
https://github.com/libp2p/rust-libp2p (gossipsub `validate_rpc_limits`)
- rust-fuzz trophy case (finding-class taxonomy) — https://github.com/rust-fuzz/trophy-case
- OSS-Fuzz Rust integration — https://google.github.io/oss-fuzz/getting-started/new-project-guide/rust-lang/
- Scheduled CI fuzzing with cached corpora — https://depot.dev/blog/distributed-rust-fuzzing
Internal: ADR-014 (envelope framing), ADR-034 (chunk header), ADR-040
(backpressure/limits), ADR-042 (hub relay), ADR-031 (crate
decomposition); review 006 E-04 (early-arrival cap sizing note,
`src/channels/manager.rs:106-121`).
docs/reviews/008-tunnels-graduation-upstream-review.md
+519
View File
@@ -0,0 +1,519 @@
# Review 008 — Graduation Upstream Asks (from the alktunnels graduation)
## Status
Resolved — all three remediation units landed in alkcall 0.8.0
(2026-09-18): Unit 1 `82ddddf` (U-2, ADR-049 amendment 3), Unit 2
`620180d` (U-1, ADR-047 amendment 3), Unit 3a `90c1820` (the in-tree
`ChannelRelay`, ADR-051), Unit 3b `4e52bd4` (the hub-leg install
template, ADR-051 §5), Unit 3c (the gate-2 e2e harness in
`src/channels/gate2_tests.rs` + the relay's producer-leg teardown +
this release's bookkeeping). Two notes on the as-filed text: the U-2
line citation is 945, not 955 (see Errata), and U-1's gate 2 landed as
an in-tree relay component plus a permanent e2e gate rather than a
test-only harness (the escalation the remediation plan pinned above).
Original findings below, retained as filed (verified against tree
`3b36b40`, 0.7.1).
> **Errata (post-landing):** U-2 cites the reply construction at
> `src/channels/operations.rs:955`; the cf-006/007 commit had already
> shifted it to 945 by filing time. The citation in the finding below
> is left as filed; the verified line is 945.
Open — filed 2026-09-16 from the alktunnels graduation spec work
(ADRs 007/008 at
`/workspace/@alkdev/alktunnels/docs/architecture/decisions/`;
research record at
`/workspace/@alkdev/alktunnels/docs/research/tunnels-graduation.md`).
Both asks are prerequisites for the alktunnels graduation
implementation (the direct op + the listen-metadata shape), which is
deliberately sequenced AFTER these land — alksocks (the first
consumer) composes against the graduated surface, so the discovery
and reply shapes must be final before it pins them. Verified against
alkcall tree @ HEAD, 0.7.1 (all code references below cite current
files/lines).
Findings continue the review numbering with prefix `U`.
## Scope
The two wire-adjacent surfaces the graduation's ADRs depend on:
(1) the open-op ↔ discovery relationship (alkcall ADR-047's op-name →
ALPN derivation and its relay reconstruction), which flavor-form open
op ids must survive; (2) the establishment → reply boundary
(alkcall ADR-049's wrapper), which a bind-first listen establisher
must be able to project metadata into. Both are additive; neither
changes the channels data-plane wire format (ADR-034/071 untouched).
## U-1: Flavor-form open-op ids in discovery derivation
**Finding.** *(Resolved — ADR-047 amendment 3, Unit 2 `620180d`; the
explicit `channel_open_alpn` field plus the last-segment derivation,
exactly the pinned (b)+(c) shape. Gate 2 landed as the in-tree relay +
`src/channels/gate2_tests.rs`, Unit 3.)* ADR-047 §1 pins the open-op
naming to exactly two shapes
per ALPN — `channels/<alpn>/sub` and `channels/<alpn>/pub` — and Gap
F's marker derivation (`rebuild_spec_for`,
`src/client/from_call.rs:209` + `derive_alpn_from_op_name`,
`src/client/from_call.rs:305`) parses exactly those suffixes to
reconstruct the `channel_open` marker after discovery
(`spec_to_json` serializes the marker as a boolean,
`src/registry/discovery.rs:244` — the ALPN string itself does not
survive the round trip). alktunnels' graduation pins two NEW
`Sub`-typed open ops on the existing `alk/tunnel` ALPN with
flavor-form op ids:
- `channels/tunnel/direct` (ADR-007 — dynamic-target egress; the
ssh `direct-tcpip` capability, scope `tunnel:direct`)
- `channels/tunnel/forwarded` (ADR-008 — accept-as-open toward the
listen-opener side; the ssh `forwarded-tcpip` capability, scope
`tunnel:forwarded`)
Runtime is NOT blocked today: registration sets the ALPN marker
explicitly (`with_channel_open`), dispatch never parses the op name
(`register_openable_with_establisher` accepts any spec name with a
marker — verified, `src/channels/operations.rs:596`), and the client
takes the ALPN as an argument (`open_channel(op_id, params, alpn)`).
The gap is **discovery + hub relay**: a flavor-form op id fails
`derive_alpn_from_op_name`'s suffix match, so `rebuild_spec_for`
rebuilds the spec WITHOUT the `channel_open` marker, so a hub
consuming through discovery (the `from_call` relay path, ADR-047 Gap
C — the alknodes re-produce shape) treats the open op as a plain
forwarding stub instead of wrapping it with relay machinery.
**Prior art in-tree.** `derive_alpn_from_op_name` already tolerates
multi-segment ALPNs (`segment.contains('/')` → used verbatim, so
`channels/x-y/sub` → `alk/x-y`); the shape is one suffix away from
flavor support.
**Requested change.** Extend the op-name convention (ADR-047
amendment): `channels/<alpn>/<flavor>` is a valid open-op name where
`<flavor>` is a bare path segment (no `/`); the derivation generalizes
from "strip `/sub` or `/pub`" to "strip the LAST segment when it is a
known op-type marker (`sub`, `pub`) or a flavor registered with an
explicit ALPN marker." Two viable implementation shapes, either
acceptable:
- **(a) Suffix-set extension** — `strip_suffix` against
`["/sub", "/pub"]` extended with a flavor allowlist threaded from
registration. Minimal, but couples discovery to a registry.
- **(b) Wire the flavor op's ALPN explicitly through discovery** —
add an optional `channel_open_alpn` string field to the
`services/schema` payload (`spec_to_json` emits the ALPN string
instead of `true` when the op name is not a standard `…/sub`/`…/pub`
shape; `rebuild_spec_for` prefers the explicit string). This also
future-proofs the boolean-only marker (Gap F) whose round-trip is
lossy by construction for any non-derivable name.
alktunnels ADR-002 Amendment 1 pins the convention sentence ("new
flavors are new op ids — additive; the `…/sub` op is never reused for
a different meaning"); alkcall's amendment should mirror it. The
boolean marker's wire meaning for standard-shape ops is unchanged.
**Why one-way-door timing:** the op ids are wire-stable from the
first consumer (alksocks). If discovery's derivation ships after
consumers exist, hubs deployed in between cannot relay the new ops —
the failure is silent (plain forwarding stub instead of channel
relay), which is the worst failure mode for a relay.
**Verification gates:**
1. `rebuild_spec_for("channels/tunnel/direct" summary)` reconstructs
the spec WITH `channel_open = alk/tunnel`.
2. A hub-relay round trip over a real channels connection: consumer →
hub (`from_call` + relay wrapper) → producer, opening
`channels/tunnel/direct` end to end, the hub forwarding the
channel (the ADR-042 relay path riding the reconstructed marker).
3. Old boolean-marker ops (`channels/tty/sub`) round-trip unchanged
(no regression on the existing derivation).
## U-2: Establisher → reply projection (`Establishment` contributing reply fields)
**Finding.** *(Resolved — ADR-049 amendment 3, Unit 1 `82ddddf`: the
`reply_fields` carrier, the `channel_id` reservation failing loudly,
`open_channel_with_reply` on the client.)* The open-op success reply
is constructed by the wrapper
and hardcoded to the channel id:
`ResponseEnvelope::ok(request_id, json!({ "channel_id": channel_id }))`
(`src/channels/operations.rs:955` in `run_open_wrapper`). ADR-049 §1
explicitly reserved the establishment phase as the wire's pre-data
moment and ADR-049 amendment 2 landed the typed-opaque plan
(`Establishment { plan }`) for the establisher → handler direction —
but the establisher has no path to contribute to the REPLY (the
establisher → opener direction). alktunnels ADR-008's bind-first
listen establisher needs exactly that: establishment ends at bind
time, and the observed OS-chosen bound address must ride the open-op
reply as an additive `"bound"` field (the SOCKS5 BIND reply#1
`BND.ADDR` fidelity ask; the alternative — an out-of-band query op —
is a new wire surface, strictly worse than an optional reply field).
**Shape note.** `#[non_exhaustive]` on `Establishment`
(ADR-049 amendment 2) anticipated exactly this carrier change. The
sketch:
- `Establishment` gains optional reply fields — e.g.
`Establishment::new(plan).with_reply_field("bound", json!({...}))`
or `reply_fields: Option<Map<String, Value>>` (bikeshed: builder
vs struct field; the map shape generalizes beyond `bound` without
a second amendment).
- The wrapper merges them into the success output AFTER reserving
`channel_id` (wrapper-owned key: an establisher-provided
`channel_id` key is an establisher bug — reject or
`handler_error`-class it loudly rather than shadowing).
- Absent fields → the reply is byte-identical to today's; no schema
change on the wrapper side (the output schema is the op's own
concern — alktunnels' listen-op spec documents `bound` as an
optional output field).
**Consumer-compat check:** `open_channel` extracts `channel_id` from
the response and ignores unknown fields (the client-side parse,
`src/channels/client.rs:932`'s contract: "respond `{ channel_id }` —
asserts the response carries a channel_id"), so old consumers are
unaffected by a NEW field; new consumers reading `bound` against an
OLD alkcall simply see the field absent — the additive posture
alktunnels ADR-008 §2 pins ("until upstream lands, the field is
simply absent").
**Requested change (ADR-049 amendment 3):** the reply projection as
sketched above, with the `channel_id` reservation documented.
**Verification gates:**
1. An establisher returning a reply field produces
`{ channel_id, bound }` on the wire; one returning none produces
`{ channel_id }` (byte-identical to today's).
2. An establisher attempting to set `channel_id` fails loudly (the
reservation holds).
3. The existing establishment tests (establisher-success pump
round-trip, no-establisher compat) pass unchanged.
## Non-asks (recorded to bound the review)
- **The channels data plane is untouched** — the forwarded op's data
plane is the existing `BiStream` + `pump_bidi`; the `bound` field
is call-plane JSON. ADR-034/071's one-way doors stay closed.
- **No new alkcall op types** — both new tunnel ops are `Sub`-typed
open ops (the existing `HandlerKind::Stream` wrapper path).
- **No identity/ACL changes** — the new scopes (`tunnel:direct`,
`tunnel:forwarded`) ride the existing op-spec `required_scopes`;
the per-call opener identity (CF-005/CF-006) is the only identity
surface the establisher/handler need (the forwarded op's `peer`
param is producer-asserted data, not transport truth — alkcall need
not validate it).
## References
- alktunnels ADR-007 (`docs/architecture/decisions/007-direct-open-op.md`),
ADR-008 (`008-listen-metadata-forwarded-op.md`) — the consumers of
both asks, with the full context and alternatives
- alktunnels ADR-002 Amendment 1 — the flavor-form op-id convention
sentence
- alkcall ADR-047 (open ops, Gap F, the derivation),
ADR-049 (establishment; amendment 2 — the plan payload whose
`#[non_exhaustive]` anticipates this carrier), ADR-042 (hub relay —
the relay path U-1's gate 2 exercises)
- alksocks `poc-bind-findings.md` (the two fidelity asks with
evidence; the upstream-ask ledger this review retires)
- Review 007 (the precedent for this filing: POC-driven upstream asks
before the dependent implementation)
---
# Remediation plan (adopted 2026-09-16 — findings verified, plan pinned)
Both findings verified against HEAD `3b36b40` (0.7.1) — all code
citations check out, with one line drift: U-2's reply construction is
`src/channels/operations.rs:945` (review cites 955; the cf-006/007
commit shifted the wrapper down ten lines). One review-scope deviation
from the as-filed text, adopted in planning:
- **U-1's gate 2 escalates from "test harness" to an in-tree relay
component.** The as-filed review treated ADR-042's relay wrapper as
consumer-side code (the ADR's §Scope note pins the implementation
downstream). The consumer decision is that the re-produce/relay shape
is general (alkhttp's fallback hub, alknodes, the vpn-like endgame all
compose it), and a real consumer now requires it — so ADR-042 is
amended: the relay implementation moves into alkcall as a reusable
component, and gate 2 becomes a genuine in-tree e2e.
Design decisions pinned above the as-filed option lists:
- **2026-09-17 (Unit 3 planning session): Unit 3 split into 3a/3b/3c
and design pinned in ADR-051** (`docs/architecture/decisions/
051-channel-relay-and-hub-leg.md`) — the session's discussion
expanded the unit's scope beyond the as-pinned sketch: the hub/spoke
family (hub or spoke may relay; the hub re-exposes spoke services by
ACL without binding ports) needs the call-half support too (the
hub-leg install template — now Unit 3b). Key decisions, all in
ADR-051: the relay holds `Arc<CallConnection>` + `ChannelManager`
per producer leg (not a `ChannelClient` — `take_call_connection`'s
detach is wrong for a hub with three `CallConnection` claimants);
the reason mapping preserves the spoke's code+message (`timeout` is
the one non-1:1 case — it maps to `dial_failed`); the registration
seam is two-phase (fork mechanism, §4); the relay map and
`channel/close` translation dissolve (implicit mapping + EOF
cascade, recorded as the ADR-042 amendment's mechanism supersessions);
Pub-typed marked specs are a loud assembly error; establishment
bounds compound per hop (noted, no fix).
- **U-1 shape: combined (b) + (c).** The as-filed option (a) is
unsound as stated — the derivation runs consumer-side against a wire
JSON payload, so an allowlist "threaded from registration" has no
path to `rebuild_spec_for` (both its consumers — `from_call`,
`op/register` — are wire-fed). The pinned shape: `spec_to_json_pub`
emits an explicit `channel_open_alpn` string alongside the boolean
when the op name is not a standard `…/sub`/`…/pub` shape (standard
shapes stay byte-identical); `rebuild_spec_for` prefers the explicit
string, else generalizes the derivation to strip the LAST segment
when the boolean marker is present (the marker is the gate, so any
bare-segment flavor works; `op/register` is fixed by the same
parser).
- **U-2 client read path: add the ergonomic accessor now** —
`open_channel_with_reply` returning the extra reply fields alongside
the streams; `open_channel` unchanged. Keeps alkcall's primary
surface intact while giving alktunnels' `TunnelListener::open` a
first-class way to read `bound`.
## Unit 1 — U-2: establisher reply projection (ADR-049 amendment 3)
Land first: the relay component (Unit 3a) projects a spoke's extra reply
fields through `Establishment`, so the projection must exist before the
e2e can assert `bound` flowing through a relay.
1. `Establishment` gains `reply_fields: Option<Map<String, Value>>` +
builder (`Establishment::new(plan).with_reply_field("bound",
json!({...}))`; also `with_reply_fields(map)` / `reply_fields()`
accessor). `#[non_exhaustive]` holds; additive, no break.
2. `run_open_wrapper`: on establisher success, merge
`reply_fields` into the success output AFTER reserving
`channel_id`. An establisher-supplied `channel_id` key is an
establisher bug — fail loudly as
`EstablishmentError::HandlerError` (reason `handler_error`, message
naming the reserved key), tearing the channel down (the wrapper's
existing failure path). No silent shadowing.
3. Client: `ChannelClient::open_channel_with_reply(operation_id, input,
alpn) -> Result<(u32, Value, MpscSendStream, MpscRecvStream),
ChannelOpenError>` — the full success output (the consumer reads
`bound` from it); `open_channel` delegates with the fields
discarded. Additive; no signature change.
4. Doc: ADR-049 amendment 3 (the projection, the `channel_id`
reservation, the accessor). The output schema remains the op's own
concern (alktunnels' listen-op spec documents `bound` as optional).
Verification gates (from the review, tightened):
- Establisher returning a reply field produces `{ channel_id, bound }`
on the wire; one returning none produces `{ channel_id }`
(byte-identical to today's — assert exact JSON).
- Establisher attempting `channel_id` → `channel:open_failed` with
reason `handler_error`; channel torn down; ledger decremented.
- The existing establishment tests (establisher-success pump
round-trip, plan-flow, no-establisher compat) pass unchanged.
- `open_channel_with_reply` returns the extra fields end-to-end over a
real channels connection; `open_channel` behavior unchanged.
## Unit 2 — U-1: flavor-form derivation + explicit ALPN field (ADR-047 amendment)
1. `derive_alpn_from_op_name` (`src/client/from_call.rs:305`)
generalizes from strip-`/sub`|`/pub` to strip the LAST path segment
(`rsplit_once('/')`), which is a strict superset of today's behavior
(standard two-suffix shapes derive identically; multi-segment ALPNs
survive the same way). The marker boolean remains the gate in
`rebuild_spec_for` — the derivation is only consulted for marked
ops, so plain ops named `channels/x/y` are unaffected (the
`channels/tty/query`-returns-None unit test moves from the function
to the marker-gated rebuild level).
2. `spec_to_json_pub` (`src/registry/discovery.rs:222`): when
`channel_open` is set and the op name is NOT a standard
`channels/<seg>/(sub|pub)` shape, emit `"channel_open": true` PLUS
`"channel_open_alpn": "<alpn>"`. Standard shapes keep the boolean
only — byte-stable for every existing consumer. The advertised
`operation_spec_schema` (`discovery.rs:159`) gains the optional
string property (schema-type widening, additive).
3. `rebuild_spec_for` (`from_call.rs:209`): prefer the explicit
`channel_open_alpn` string; else boolean → generalized derivation.
Covers both wire consumers (`from_call`, `op/register`) by
construction.
4. Doc: ADR-047 amendment — the convention sentence mirroring
alktunnels ADR-002 Amendment 1 (`channels/<alpn>/<flavor>` is a
valid open-op name, `<flavor>` a bare segment; flavors are additive,
the `…/sub` op is never reused), the explicit-field wire shape, and
the one-way-door note (the field joins the stable
`services/schema` payload; the boolean's meaning for standard-shape
ops is unchanged). Record the residual ambiguity: an ALPN segment
that itself collides with a flavor name (`channels/x/direct` where
the ALPN is `alk/x/direct`-shaped) is undecidable from the name
alone — the explicit field is the disambiguator.
Verification gates:
- Review gates 1 and 3 as unit/round-trip tests:
`rebuild_spec_for("channels/tunnel/direct" summary)` reconstructs
WITH `channel_open = alk/tunnel`; `channels/tty/sub` (boolean) and
`channels/custom/proto/sub` (multi-segment) round-trip unchanged;
flavor-form spec serializes with the explicit string and rebuilds
from it; `op/register` announced flavor-form spec round-trips with
the marker.
- Review gate 2 (hub-relay e2e) lands with Unit 3c.
## Unit 3 — the in-tree relay component (ADR-042 amendment, ADR-051) + gate 2 e2e
Adopted 2026-09-17, design pinned in ADR-051 (`docs/architecture/
decisions/051-channel-relay-and-hub-leg.md`): the relay is the wrapper
composition (translate hop = the ADR-049 establisher shape; byte-
forward hop = `pump_bidi` per ADR-050), the ADR-042 relay map
dissolves (implicit per-channel mapping), `channel/close` needs no
translation surface (the EOF cascade propagates with correct ledger
accounting on both legs), and the registration seam is two-phase
(discover/stash → per-connection fork-register — the ADR-047 §4
amendment's fork mechanism makes a one-call import impossible without
adapter changes). The call-half support the hub/spoke family needs is
the hub-leg install template (Unit 3b) — composition of existing
pieces, not a new protocol surface. Three sub-units, three sessions'
scope:
### Unit 3a — `ChannelRelay` (the relay component)
New module `src/channels/relay.rs`:
1. `ChannelRelay::register_relay_openable(consumer_registry, spec,
producer_leg)` — for a from_call-imported spec with `channel_open`
set, registers on the hub's consumer-leg channel-0 fork registry
via `register_openable_with_establisher`, where:
- **`producer_leg`** is `Arc<CallConnection>` +
producer-leg `ChannelManager` (ADR-051 §2 — not a
`ChannelClient`: the hub's `CallConnection` is shared by import,
relay establisher, and hub ops, so `take_call_connection`'s
detach is wrong; the establisher builds its forwarded payload
directly — the hub as caller, the consumer as `forwarded_for`
from the per-call identity, ADR-026 §3).
- The **establisher** (the translate hop, ADR-042 layer 1): calls
the producer leg's open op with the forwarded payload, adopts the
returned spoke `channel_id` into the producer-leg manager, and
returns `Establishment::new(plan)` whose plan carries the
spoke-leg streams. The spoke reply's `channel_id` is stripped;
the reply's other fields ride `with_reply_fields` (`bound`
flows end-to-end, per-hop truthful). Failure mapping per
ADR-051 §3 (the reason table; spoke `CallError` code + message
preserved in the mapped variant).
- The **OpenHandler** (the byte-forward hop, ADR-042 layer 2):
`pump_bidi(consumer_leg_bistream, spoke_recv, spoke_send)` —
the relay never parses chunk framing (per-leg mux/demux absorbs
the 8-byte header; no ID rewrite exists — ids are
per-connection). Awaited inline (R-02); on completion both legs
tear down (the wrapper's handler-exit teardown covers the
consumer leg; the pump's drops EOF the spoke leg).
- The consumer leg keeps the full wrapper machinery: ACL,
per-identity cap/ledger, establishment bound (bounds the spoke
dial round-trip), teardown-on-failure — no parallel
authorization path.
2. Rejection postures (ADR-051 §6): a `Pub`-typed marked spec is an
assembly error at registration (`channel:pub_open_not_implemented`
class, C-08 blocker) — never a silent stub; an unmarked spec
passed to the relay registration is likewise an error (branch on
the marker before calling).
Verification gates:
- The establisher populates `forwarded_for` from the consumer's
per-call identity; the spoke reply's `channel_id` is stripped (the
consumer reply carries the hub-allocated id).
- A spoke `channel:open_failed` maps to the consumer-leg
`channel:open_failed` with the mapped reason and the spoke's
message preserved; consumer leg tears down (ledger decremented);
no spoke channel leaks (the adopt-then-fail window is covered).
- `bound` (Unit 1's projection) survives the relay to the consumer
reply.
- Pub-typed and unmarked specs are rejected at registration.
### Unit 3b — the hub-leg install template (the call-half support)
Landed (2026-09-17): `src/channels/hub_leg.rs` — `HubLegImports`
(the `Clone` stash split by the marker) and `HubLegTemplate`
(the §5 composition exported as the `InstallChannelZero` hook;
`serving identity` via the CF-005 seam). One assembly rule the
planning sketch missed, surfaced by the template's gate e2e:
`from_call` discovers the spoke's bootstrap discovery ops like any
plain op, so the template skips
`registry::discovery::BOOTSTRAP_DISCOVERY_OPS` when re-registering
plain bundles — the template's own install (closed over the fork,
review 004 F-06) supersedes the imported copies. Unit 3c (the
gate-2 e2e) remains.
The hub-side composition every test hand-rolls
(`make_install_channel_zero`-shaped), exported in-tree (ADR-051 §5 —
two-way-door API shape):
1. Fork the hub's base registry (ADR-047 §4 amendment mechanism).
2. Register the generic channel ops (`ChannelOperations::register_on`)
and the bootstrap discovery ops (closed over the fork, so
`services/list` sees the fork's ops — review 004 F-06).
3. Register the stashed plain bundles as-is (the existing forwarding
handlers) and the marked specs via Unit 3a's relay registration.
The stash is the `Clone`able `Vec<HandlerRegistration>` `from_call`
returned (registrations and `HandlerKind` are `Clone`; one
discovered set serves any number of consumer legs).
4. Per-call identity resolution for the serving dispatch
(`ServingConfig`-shaped precedence: payload token → explicit
override → transport identity), then the single-stream dispatch
loop.
5. Per-consumer op-subset filtering composes here (the fork is per
consumer leg — ADR-051 §4's composition note). ACL layering is
pinned in ADR-051 §5: the spoke's `AccessControl` sees only the
hub identity; the end consumer's identity is `forwarded_for`
metadata, never checked by any `AccessControl::check`.
Verification gates:
- The template composes fork + generic ops + bootstrap discovery +
plain bundles + relay openables + serving identity and dispatches
channel 0; `services/list` on the consumer leg shows the
re-exposed ops; a plain imported op round-trips through the hub
(the call-half forwarding path exercised for real).
### Unit 3c — gate 2, the review's full e2e harness
The review's verification gate 2, now with the in-tree components:
1. Consumer → hub (Unit 3b's template on the consumer leg;
`ChannelsAdapter` both legs) → producer, opening
`channels/tunnel/direct` end to end: the open resolves on the
consumer with the hub-allocated `channel_id`, the
establisher-contributed `bound` field (Unit 1) survives the relay
to the consumer reply, data flows both directions on the data
channel (the hub never parses it), and hub-side disconnect /
spoke-side close tears down both legs' channels.
2. The mid-establishment disconnect window (ADR-051 §6): consumer
leg dies between spoke open and pump spawn — the spoke channel is
reclaimed when the pumps run (EOF cascade), both ledgers
decremented, no leak.
3. A companion `channels/tty/sub` relay run pins no regression on
standard shapes.
Remaining bookkeeping for the final unit: ADR-042 amendment (landed
with ADR-051 — the §Scope-note revision and the two mechanism
supersessions), changelog + minor version bump (new pub API:
`ChannelRelay`, `register_relay_openable`, the hub-leg template;
`open_channel_with_reply` and `Establishment::with_reply_field*`
landed with Units 1–2).
## Sequencing and non-goals
Order: Unit 1 → Unit 2 → Unit 3a → Unit 3b → Unit 3c (Unit 3a is the
component; 3b the assembly; 3c the e2e gate asserting `bound` through
the relay — Units 1–2 are prerequisites of 3a; 3b and 3c of each
other). One release (minor bump), matching the review-007 precedent.
Not in scope (extends the review's non-asks): the data-plane wire
format (untouched — the relay rides `MpscSendStream`/`MpscRecvStream`
and `pump_bidi`; no header rewrite exists — ids are per-connection,
ADR-051), any `channel/control` translation surface (close propagates
through the EOF cascade; control is per-leg, OQ-39 — a hub wanting
cross-leg control translation composes it downstream), the Pub-typed
open path (rejected loudly; C-08 blocker), and the alktunnels-side
work (the bind-first establisher, the listen-op spec's `bound`
documentation, ADR-007/008 implementation) which sequences AFTER these
land.
Review-008 status updates when units land: mark U-1/U-2 resolved with
commit refs (the review-007 Status pattern), and correct the U-2 line
citation (955 → 945) in an errata note rather than silently editing the
as-filed text.
docs/reviews/009-post-landing-audit-coverage-gaps.md
+247
View File
@@ -0,0 +1,247 @@
# Review 009 — Post-landing audit of the review-008 remediation (0.7.1 → 0.8.0)
## Status
Resolved — all seven findings landed in alkcall 0.8.0 (2026-09-18,
same working tree as the audit's inline fixes): C-1 (plain-bundle arm
pinned + the ADR-051 §5 coverage note), C-2 (`filtered` closure unit +
the empty-stash e2e gate), C-3 (the batch-form reserved key), C-4
(the `open_channel_with_reply` failure path), C-5 (both golden pins),
C-6 (the derivation edge shapes), C-7 (last-win pinned + the doc
sentence). Three errata on the as-filed text (marked per finding).
No wire or API changes were needed. Verified at resolution: 680
tests pass, clippy/fmt clean, wasm check clean.
Open — filed 2026-09-18 from the post-landing audit of the six commits
`82ddddf..50182d7` (review 008's three units). Scope: correctness
review of the full diff, test-coverage mapping, and the classic
implementation-issue sweep. Verified against HEAD at filing (0.8.0 +
the audit's inline hardening commit): 672 tests pass, clippy/fmt/doc
clean, wasm check clean.
The audit's code findings were fixed inline at filing time (see the
CHANGELOG [Unreleased] entry): the adopted-entry leak windows
(audit F-1/F-2 — `RelayPlan` drop guard), the empty explicit
`channel_open_alpn` (audit F-3), the `channels//sub` silent-stub
shape (audit N-4), and the reserved-key message/log-level nits
(audit N-1/N-2). ADR-051 §6 documents the closed post-adopt window.
What remains from the audit is the **test-coverage debt** below —
deliberately deferred to this review so the fix commit stayed small.
Findings continue the review numbering with prefix `C` (coverage).
## Scope
Test-coverage gaps in the 0.8.0 surface: the Unit 3 modules
(`src/channels/relay.rs`, `src/channels/hub_leg.rs`) and the Unit 1/2
diff surfaces (`src/channels/operations.rs`, `src/channels/client.rs`,
`src/client/from_call.rs`, `src/registry/discovery.rs`). No production
code changes are requested by this review unless a gap's write-up
says otherwise; each finding names the test(s) to add and what they
pin. None block a consumer — the e2e gates the review-008 plan pinned
are all landed and passing; these gaps are the paths the gates never
walk.
## C-1: `HubLegTemplate::install_hook` failure arms are loud-only-in-code
**Errata (2026-09-18, at resolution).** The as-filed route (a) —
"a duplicate name between a plain bundle and the generic channel ops"
— does not fail `OperationRegistry::register` (same-name registration
overwrites; the map is an insert). The honest failure mechanism used
is the registry's other fail-closed rule: an un-compilable
`input_schema` (`{"type": "object", "required": "not-an-array"}`,
the CF-003 shape). Resolved with route (c)'s documentation half for
the generic-ops/bootstrap-discovery arms: ADR-051 §5 now carries the
loud-install coverage note (two arms pinned, two arms
best-effort-loud — the crate-internal specs compile by construction,
so an injectable seam would test the seam, not the arm).
**Finding.** `src/channels/hub_leg.rs:232-275` — four install arms end
the leg with only a `tracing::warn!`: generic channel ops registration
failure, plain-bundle registration failure, relay-openable
registration failure, bootstrap-discovery install failure. ADR-051 §6
pins the posture as "loud, never a silent stub" and only the
relay-openable arm is test-pinned
(`hub_leg_tests.rs` `template_pub_typed_marked_spec_is_loud_at_install`).
The other three are near-unreachable (generic ops and bootstrap
discovery cannot realistically fail; plain bundles were already
registered on the producing side) — but the ADR's posture claim rests
on code that no test walks.
**Requested change.** Unit-test the three unpinned arms. The plain
routes: (a) a plain bundle that fails registration — e.g. a duplicate
name between a plain bundle and the generic channel ops — asserts the
install task ends before `run_loop_single_stream`; (b) the same shape
for a relay-openable failure is already pinned; (c) the
generic-ops/bootstrap-discovery arms need an injectable failure seam
if they are to be tested honestly — if that is disproportionate,
instead demote the claim: document in ADR-051 §5 that only the
relay-openable arm is test-pinned and the others are
best-effort-loud, so the ADR and the code say the same thing.
**Verification gates:**
1. The template's install task provably ends (channel 0 never
dispatches) on each exercised failure arm.
2. The ADR-051 §5/§6 text matches what is actually pinned.
## C-2: `HubLegImports::filtered` / `only` have no test
**Errata (2026-09-18, at resolution).** The as-filed "no unit test"
overstated: `stash_filter_keeps_named_ops_only` (landed with Unit 3b)
already exercised `only` at filing time. The real gaps — the
`filtered` closure path and the empty-filter e2e shape — are what
landed (`stash_only_keeps_the_marked_direct_spec_and_drops_the_rest`,
`stash_filtered_closure_partitions_both_halves`,
`template_empty_only_stash_installs_generic_ops_and_discovery_only`).
**Finding.** `src/channels/hub_leg.rs:91-111` — the per-consumer
op-subset filter, the mechanism behind ADR-051 §4's "per-consumer ACL
differentiation is a composition consequence" note, has no unit test.
Trivial code, but it is exported pub API (`HubLegImports` is a crate
export) and the filter story is load-bearing for the hub/spoke family.
**Requested change.** Unit tests: `from_bundles` splits by marker;
`filtered`/`only` partition both halves; a `#[must_use]` misuse
compiles with a warning (already enforced by the attribute — just
exercise the two builders).
**Verification gates:**
1. `only(&["channels/tunnel/direct"])` keeps the marked direct spec,
drops everything else, plain bundle untouched by the marked list.
2. An empty `only` stash installs a leg that serves only the generic
ops + discovery (no re-exposed ops in `services/list`).
## C-3: Batch-form reserved reply key
**Finding.** `src/channels/operations.rs` — the reserved-key teardown
test (`with_reply_field("channel_id", …)`, `operations.rs:~2606`)
covers only the builder form. The wrapper's check inspects the merged
map, so `with_reply_fields(map)` smuggling `channel_id` is covered by
construction — but the batch path is the shape a hub's
`Establishment::with_reply_fields(relay_map)` will actually use, and
it is unasserted.
**Requested change.** One-line extension of the existing test (or a
sibling): the batch form fails with reason `handler_error`, channel
torn down, ledger decremented.
**Verification gates:**
1. `Establishment::default().with_reply_fields(json_map_containing_channel_id)`
→ `channel:open_failed` / `handler_error`; `count_for == 0` after.
## C-4: `open_channel_with_reply` wire failure path
**Finding.** `src/channels/client.rs:1654` — the new client API's e2e
test covers the success path only. The failure path (a
`channel:open_failed` resolving through `open_channel_with_reply`) is
covered only indirectly (wrapper-level test + the generic
`establisher_failure_resolves_typed_open_failed_on_the_client`).
Low risk — the parse path is shared with `open_channel` — but the new
pub API's error path has no direct pin.
**Requested change.** One e2e test against the existing
establisher-always-fails harness: `open_channel_with_reply` resolves
`Err(ChannelOpenError::CallFailed)` with the `channel:open_failed`
code and details intact.
**Verification gates:**
1. The full reply shape (`reason`, `message` in `details`) is
assertable by the caller through the new API.
## C-5: Byte-identical claims are shape-pinned, not golden-pinned
**Finding.** Two "byte-identical" claims are pinned structurally
(key-set equality), not by literal:
- `run_open_wrapper_without_reply_fields_is_byte_identical_to_pre_amendment`
(`operations.rs:2553`) asserts `v == json!({"channel_id":
v["channel_id"]})` — pins the exact key set but builds the expected
from the actual (a wrong-typed `channel_id` value would pass).
- The Unit-2 standard-shape wire payload
(`spec_standard_shape_channel_open_stays_boolean_only`) pins the
key *absence* of `channel_open_alpn` (the real pin, solid) but not
the payload's full key set.
**Requested change.** Golden-pin both: assert serialized bytes or a
literal `json!` against the actual for the no-fields reply, and a
full-object comparison for the standard-shape payload. Cheap, and it
converts "structurally equal" into "these exact bytes" for the two
claims the ADRs advertise as wire-stable.
**Verification gates:**
1. The no-fields open reply equals `json!({"channel_id": <exact
literal>})` — not a self-referential compare.
2. The standard-shape `services/schema` payload compares equal to a
literal object including key order (serde_json default map).
## C-6: `derive_alpn_from_op_name` edge shapes unpinned
**Errata (2026-09-18, at resolution).** The as-filed expectation
`"channels/x/sub/extra"` → `Some("alk/x/sub")` mis-stated the actual
behavior: the last-segment strip yields `rest = "x/sub/extra"`, and
`x/sub` (multi-segment, non-`alk/*`) rides as a full ALPN per the
ALPNs-without-the-prefix rule — `Some("x/sub")`, the same rule the
existing 5-segment test (`vendor/service/run`) pins. The landed test
asserts the actual behavior with the behavior-change-vs-pre-amendment
annotation.
**Finding.** `src/client/from_call.rs:326-337` — the empty-segment
guard (`segment.is_empty()`) and the bare-no-slash name have no unit
test, and the 4-segment name behavior *changed* (pre-amendment:
`None`; now: `Some("x/sub")`) without any test noticing. The audit
closed the `channels//sub` serialization half (N-4); the derivation
function's own edge-shape unit tests remain unlanded.
**Requested change.** Unit tests over the derivation directly:
`"channels//sub"` → `None`; `"channels//direct"` → `None`;
`"channels"` → `None`; `"channels/x/sub/extra"` → `Some("alk/x/sub")`
(the deliberate strict-superset behavior, worth pinning as intended);
`"channels/alk/tty/sub"` → `Some("alk/tty")` (the verbatim case).
**Verification gates:**
1. All five shapes assert as above; the 4-segment case is annotated
as a behavior change vs the pre-amendment derivation.
## C-7: Builder overwrite semantics unpinned
**Finding.** `src/channels/operations.rs:420-434` — two
`with_reply_field("same-key", …)` calls silently last-win; the batch
form extends (also last-win). Establisher-own concern, nit-level, but
it is pub-API behavior a consumer will rely on or be confused by.
**Requested change.** Either pin last-win with a test (and one doc
sentence on `with_reply_field`), or reject duplicates loudly at
build time. Prefer pinning: rejection adds a failure mode with no
consumer ask behind it.
**Verification gates:**
1. `.with_reply_field("k", v1).with_reply_field("k", v2)` →
`reply_fields()["k"] == v2`.
## Non-goals (recorded to bound the review)
- **No wire-format or API changes** — everything above is tests plus
at most doc text. The audit's code findings are already landed;
they are not re-opened here.
- **No new ADRs** — C-1's documentation route (if chosen) edits
ADR-051 §5/§6 text only.
- **alktunnels-side work** (the bind-first establisher, the listen-op
spec) sequences after this review as planned; nothing here blocks
it.
## References
- ADR-051 §6 (the post-adopt teardown bullet the drop guard landed;
C-1 pins its assembly-arm siblings)
- ADR-047 amendment 3 (C-6's derivation shapes), ADR-049 amendment 3
(C-3/C-7's reply projection), ADR-047 (C-5's wire-stability claims)
- CHANGELOG [Unreleased] — the audit's inline fixes this review
complements
- Review 008 — the remediation whose surface this review audits
fuzz/.gitignore
+6
View File
@@ -0,0 +1,6 @@
target
corpus/*
!corpus/chunk_header
!corpus/envelope_frame
artifacts
coverage
fuzz/Cargo.lock
Generated
+1280
View File
File diff suppressed because it is too large. Load diff
fuzz/Cargo.toml
+52
View File
@@ -0,0 +1,52 @@
[package]
name = "alkcall-fuzz"
version = "0.0.0"
publish = false
edition = "2021"
[package.metadata]
cargo-fuzz = true
[dependencies]
libfuzzer-sys = "0.4"
alkcall-fuzz-shared = { path = "shared" }
[dependencies.alkcall]
path = ".."
[[bin]]
name = "chunk_header"
path = "fuzz_targets/chunk_header.rs"
test = false
doc = false
bench = false
[[bin]]
name = "envelope_frame"
path = "fuzz_targets/envelope_frame.rs"
test = false
doc = false
bench = false
[[bin]]
name = "manager_routing"
path = "fuzz_targets/manager_routing.rs"
test = false
doc = false
bench = false
[[bin]]
name = "envelope_semantic"
path = "fuzz_targets/envelope_semantic.rs"
test = false
doc = false
bench = false
[[bin]]
name = "spec_parse"
path = "fuzz_targets/spec_parse.rs"
test = false
doc = false
bench = false
[workspace]
fuzz/README.md
+53
View File
@@ -0,0 +1,53 @@
# alkcall fuzzing
libFuzzer targets for alkcall's wire formats (see
`docs/research/fuzzing.md` for the full rationale and campaign plan).
## Layout
- `fuzz_targets/` — one binary per target; thin `fuzz_target!` wrappers.
- `shared/` — the invariant logic, as a plain library so normal
`cargo test` (stable toolchain) can replay the committed corpora
through the same invariants (`fuzz/shared/src/*.rs` `#[cfg(test)]`
modules; quinn's CI pattern). The fuzz binaries are nightly-only;
the shared crate is stable-clean.
- `corpus/<target>/` — committed hand-made seeds (regenerate with
`python3 fuzz/gen_fuzz_seeds.py` from the repo root). Grown corpora
and artifacts are gitignored.
- `run-detached.sh` — mandatory runner for agent sessions: wraps
`cargo fuzz run` in `setsid` + `nohup` + log redirection so an OOM
in a target can never take down the agent host (research doc §7.6).
- `json.dict` — JSON token dictionary for the envelope targets.
## Targets
| Target | Drives | Invariants |
|---|---|---|
| `chunk_header` | `parse_header` / `write_header` (`channels/wire.rs`) | no-panic; round-trip identity; `TooLarge` iff `length > MAX_CHUNK_LEN`; consumption accounting (8 bytes); input never mutated |
| `envelope_frame` | `FrameFramedReader::new(Cursor).read_frame()` on a current-thread runtime | no-panic; never allocates > `MAX_FRAME_SIZE`; clean `FrameError` on truncation/oversize/zero-length; exact consumption; structural `write_frame` round-trip |
## Commands
`cargo fuzz build` and `cargo fuzz run` must be executed with `fuzz/`
(or deeper) as the working directory so rustup selects the pinned
nightly toolchain — the detached runner handles that itself.
```sh
# build (nightly, pinned by rust-toolchain.toml inside fuzz/; run from fuzz/)
cargo fuzz build
# agent sessions: detached campaign (never foreground; CWD-independent)
FUZZ_RUNTIME_SECS=600 fuzz/run-detached.sh chunk_header
FUZZ_RUNTIME_SECS=600 fuzz/run-detached.sh envelope_frame -max_len=65536 -dict=json.dict
# corpus replay through the invariants (stable toolchain, no nightly)
cargo test --manifest-path fuzz/shared/Cargo.toml
# coverage
cargo fuzz coverage <target>
```
The fuzz workspace is excluded from the main workspace and from the
published package (`exclude` in the root `Cargo.toml`); it pins its own
nightly toolchain via `rust-toolchain.toml` and does not affect the
crate's stable MSRV.
fuzz/corpus/chunk_header/seed-000
BIN
View File
Binary file not shown.
fuzz/corpus/chunk_header/seed-001
BIN
View File
Binary file not shown.
fuzz/corpus/chunk_header/seed-002
BIN
View File
Binary file not shown.
fuzz/corpus/chunk_header/seed-003
BIN
View File
Binary file not shown.
fuzz/corpus/chunk_header/seed-004
BIN
View File
Binary file not shown.
fuzz/corpus/chunk_header/seed-005
BIN
View File
Binary file not shown.
fuzz/corpus/chunk_header/seed-006
BIN
View File
Binary file not shown.
fuzz/corpus/chunk_header/seed-007
BIN
View File
Binary file not shown.
fuzz/corpus/chunk_header/seed-008
BIN
View File
Binary file not shown.
fuzz/corpus/chunk_header/seed-009
BIN
View File
Binary file not shown.
fuzz/corpus/chunk_header/seed-010
BIN
View File
Binary file not shown.
fuzz/corpus/chunk_header/seed-011
BIN
View File
Binary file not shown.
fuzz/corpus/chunk_header/seed-012
BIN
View File
Binary file not shown.
fuzz/corpus/chunk_header/seed-013
BIN
View File
Binary file not shown.
fuzz/corpus/chunk_header/seed-014
BIN
View File
Binary file not shown.
fuzz/corpus/chunk_header/seed-015
BIN
View File
Binary file not shown.
fuzz/corpus/chunk_header/seed-016
BIN
View File
Binary file not shown.
fuzz/corpus/chunk_header/seed-017
BIN
View File
Binary file not shown.
fuzz/corpus/chunk_header/seed-018
BIN
View File
Binary file not shown.
fuzz/corpus/chunk_header/seed-019
BIN
View File
Binary file not shown.
fuzz/corpus/chunk_header/seed-020
BIN
View File
Binary file not shown.
fuzz/corpus/chunk_header/seed-021
BIN
View File
Binary file not shown.
fuzz/corpus/chunk_header/seed-022
BIN
View File
Binary file not shown.
fuzz/corpus/chunk_header/seed-023
+1
View File
@@ -0,0 +1 @@
��������
fuzz/corpus/chunk_header/seed-024
View File
Whitespace-only changes.
fuzz/corpus/chunk_header/seed-025
+1
View File
@@ -0,0 +1 @@

fuzz/corpus/chunk_header/seed-026
+1
View File
@@ -0,0 +1 @@

fuzz/corpus/chunk_header/seed-027
+1
View File
@@ -0,0 +1 @@

fuzz/corpus/chunk_header/seed-028
+1
View File
@@ -0,0 +1 @@

fuzz/corpus/chunk_header/seed-029
+1
View File
@@ -0,0 +1 @@

fuzz/corpus/chunk_header/seed-030
+1
View File
@@ -0,0 +1 @@

fuzz/corpus/chunk_header/seed-031
+1
View File
@@ -0,0 +1 @@

fuzz/corpus/chunk_header/seed-032
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/002a50e5a23efb9058be3963d8cee9a3d3fae207
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/00350d5a13e27894078dbffc9c4e9bb734011abd
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/003c24faba840f3c011962c1fb976a37507d3df1
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/00470e5adf2e49df3fd2978e2ea0a050e13c9340
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/0062e9ac9e7f8a0114e2d9c6cc41137698f8971f
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/0092bffc8b2d16f273592c1bd4b7d2cb575f2f80
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/00b6e2fb9e9207730d58293a348b6b89ff3ad138
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/00e0cbe988aa55ae5e4c5d35815556c4e38d970b
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/00ee7e51b853d82a99187a5d5cfe5f5bbdd9c89b
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/0104a863b178a8c5c7db9217e42d03a0c0b11b1d
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/011987e6abe4582d24cf6288e96a1d77ee22f88d
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/0127f1f77af88fa5e0730bff82e54c3ec53e4489
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/015eb04ee4663bd4ce848d1dffaef3d3869e0864
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/01a87a8f670e391e2539615943555df1f2878ec1
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/01adcb34d3d39f2ee613ab9c0aafc19bae944d0c
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/024cd35bab3b688c9411566bc95bdd7a09802fb7
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/024da66095ef56337eaa9afc95249eea17cbe533
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/02f924ca2c523a73a5a8f5edd9e11507a2df70b4
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/03151400d8ea08fb5cc10791c0baf19a53a820b0
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/0317a2cfbdd0a7921b74e972cb96c3996df47a68
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/032fa6ccbd41b45e02c452391dde99983ec1c879
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/0352d75a53f568fa29b1f73e673ac70ef1154d94
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/0365ec22a142f6d28e3aca51835481c227cc51e2
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/0367b0ed25803b20dc5fedae1bd7bbfeb7c7a079
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/03c1685e220eda208760344efc7fc6764ec7d3e0
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/041f24e71e73e7d2967015268899835cd86fb3ba
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/04204406882d2a6508bb80c140fde10ae8e335a1
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/046cf8280d0ee7cb242ad1f18b229a3411ee193b
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/046f9711580a6dbcc4f2879533a2dff5de92032d
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/04cd19b4c1223c470c8235e8fd40d7fcd1d4b363
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/04e29b4ceacdb443c5c32135e7407202f6b3ccd2
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/04faae024102681809d8592121894ba8dae22149
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/054207b8a0dc9e07744957be95d3cd4064897bce
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/055de3735a2e90e01dc9cd0da1ba300c914868ef
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/057cfd1917171dc44168dd110c7f6bf8867ae49d
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/058ee3a09155edc998f4b1ffbd5130381bd0cc37
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/05db05499c89700d6eb8d1e51c6e3691ace344fe
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/0624e7cbfd7f8458cfecb36e16c51ed5c141cdc8
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/062bd0e69fad29b94bfe7e0998bf79053ff59522
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/066bce0fc541ed3da2f85b5fe475702135986c27
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/067e543557500424a46cf3dd28aecc146453d95b
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/06a59977291cf0105f475f7ef9fb3b474b2435a8
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/06b3d654a9232d200dec8f27826ad6e07d95f901
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/075a341cef20415575bba7271c1d68c39dd4b873
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/07854c5950be55b7f86c256c01613cfdb09733ce
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/0795a9c73b74819dbd5b987c6b17aecf4b83cc8e
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/07e0db84b710db9732384beaf1ab8436687bc3b1
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/07faee78cebd597e95031181ff0fd92c23dc4a8b
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/083b52dd2234d0eed33ef8e12e874094087cfc2d
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/089549cab1dbfd3599d3e6f1e3c72ae80b1bc359
BIN
View File
Binary file not shown.
fuzz/corpus/envelope_frame/08a8171f7b213db2b5bd36f49f9b8f3de38cbcfd
BIN
View File
Binary file not shown.
Loaded 100 of 1483 files, more files were not shown because too many files have changed in this diff. Show more