Adopt the alk*/fuzzing posture (alkcall 0.8.1 + alktunnels 0.2.1
precedent) before the v0.1 publish — the cheapest moment this crate
will ever have for it:
- alkcall 0.8.1 + alktunnels 0.2.1: the duplicate-adopt/open fix is
directly relevant to this crate's consumer open/adopt paths
- fuzz/ workspace (the sibling layout): nightly-pinned subtree, stable
fuzz/shared library (corpus replay = the fuzz gate), detached runner,
JSON dict, deterministic seed generator; 129 committed seeds
- three wave-1 targets over already-pub APIs: datagram_codec (the
ASSOCIATE frame codec — the alkcall-fuzz-doc-assigned downstream
target), rfc1928_codec (the forked RFC 1928 core's handshake state
machines, both protocol directions), params_parse (the wire-stable
open-op surface)
- one diagnostic: DatagramReader::retained_bytes() (the decoder-state
bound's assertion target, the alktunnels retained_bytes() posture)
- docs/research/fuzzing.md: the scoped plan + implementation log;
AGENTS.md gains the corpus-replay verification line
- campaigns: 3 × 10-min detached runs exited 0 (datagram ~1.9M execs,
rfc1928 ~2.0M, params ~3.1M; oom/timeout/crash 0/0/0 on all 33 fork
jobs per target; coverage saturated on both codec targets). No crate
bugs; three harness-model defects found + fixed (2 pre-campaign by
corpus replay, 2 campaign-found, crash inputs promoted as seeds 900/
901): the len==0 well-framed decode partition, the fieldless-struct
serde-seq form, the BadAtyp re-frame arm, the short-domain count-walk
gate
- wave 2 (session_pumps stateful target) deferred to post-0.1 — the
byte-level targets carry the attacker-reachable load for the publish
Verification: cargo test (15 suites ok, default + all-features), clippy
(all-targets + wasm + fuzz/shared), fmt, cargo doc, publish --dry-run,
corpus replay 129 seeds green, cargo fuzz build clean.
Refs: alkcall docs/research/fuzzing.md (§7.9 posture), alktunnels
docs/research/fuzzing.md; docs/research/fuzzing.md (this crate's copy)
Complete the ADR-011 §Amendment (extraction, not wholesale-copy-plus-
gate) across every doc that stated the pre-amendment posture:
- ADR-011: add the two extraction-recipe exclusions the amendment
missed (the socks4 module — upstream's separate default-off cargo
feature, out of RFC 1928 scope; the legacy Config/Authentication
auth layer — ungated but consumed only by the cut region) and the
dependency-surface adjustments (log -> tracing, anyhow dropped,
async-trait dropped with its legacy-layer uses)
- ADR-009: amend — the vendor's net gate dissolves; features collapse
to local + composed; local carries tokio/net + socket2 itself
- vendor.md: replace the contradictory old "four carried changes"
section with the two-change reading + extraction-time adjustments;
extend the cut table (socks4 row, legacy auth layer)
- overview.md: dependency diagram + feature table drop the net
feature; module map reflects two carried changes
- README.md: principles 7/8 + doc/ADR tables updated
- ADR-002/012, open-questions.md (OQ-SK-04), phase-0.md current-state
sections, AGENTS.md conventions 4/17 + stale wasm-caveat sentence,
POC findings posture notes: aligned with the extraction
Verification: repo-wide grep for stale "four carried"/default-on net/
implies-net statements returns only amendment-context matches;
extraction recipe re-verified against POC #4's gate map and the
fast-socks5 v1.0.0 source (async-trait usage confined to the cut
legacy layer; AuthMethod<T> traits are native async-fn-in-trait).
The ownership premise ('we own fast-socks5') was wrong — it is
third-party upstream and has not been forked. The corrected posture
resolves OQ-SK-04: inline vendor. The wrapper's needs exceed the wasm
gate regardless (BIND absent upstream — POC #5 proved the wrapper
drives it; the run_udp_proxy_custom bind seam; private new_reply), so
carrying the T-generic subset (~120 cfg lines, POC #4-verified) pays
for itself independent of the adapter story.
AGENTS.md:
- convention 17 rewritten: 'Upstream: alkcall is ours to shape;
fast-socks5 is inlined' — the ownership split stated plainly, the
inline vendor + its four carried changes named, the courtesy PR
kept optional/never-waited-on, the vendor point (v1.0.0) noted
- convention 4: wasm posture note updated to the resolved vendor
- prior-art entry: fast-socks5 marked third-party/NOT ours
phase-0.md:
- OQ-SK-04 RESOLVED (2026-09-20): resolution note headers the OQ (the
two settling facts: wrong ownership premise; needs exceed the gate);
decision tree retained as reasoning trail with both legs annotated
(Case 2's premise falsified by the BIND need); the root question
reframed as retrospective; checklist item checked
- §Prior art fast-socks5: header + run_udp_proxy_custom caveat
reworded from 'fileable ask' to in-tree change
- settled-foundations wasm caveat resolved; survey + checklist
prior-art entries marked; 'What Phase 0 could NOT answer' wasm item
struck as resolved; convergence Layering bullet now enumerates the
four in-tree carried changes; upstream-asks bullet: fast-socks5
items are no longer asks
poc-connect-wasm-findings.md / poc-bind-findings.md /
iroh-socks5-eval.md: 'we own it' ask sections corrected to
in-tree-vendor changes (dangling fragment from an earlier edit also
fixed); ledger item 3 annotated
Verified: fast-socks5 upstream still 1.0.0, no net feature, BIND
refused (lib.rs:384-386/server.rs:813-816) — the needs-are-real facts
stand. Docs-only change; no build surface affected.
The ask ledger's two alktunnels items landed 2026-09-18/20 — superseded
in shape, not implemented as posed. The graduation (alktunnels
tunnels-graduation.md -> ADRs 007/008) adopted the ssh
forwarded-tcpip-shaped alternative over the per-ask carriers.
phase-0.md:
- settled-foundations: establishment gains the reply-projection note
(ADR-049 amendment 3); the relay/hub note records the in-tree
ChannelRelay/HubLegTemplate (ADR-051); identity-seam note marked
current at 0.8.0
- OQ-SK-01: Option A updated — the direct op (channels/tunnel/direct,
ADR-007) is the dynamic-target channel; POC #5's scope-gate +
ADR-007 rationale point the same way (separation lives at the ACL)
- OQ-SK-03: composed egress's vehicle is open_direct +
Substrate::Udp; the ~0.8 ms measurement carries over; the stale
POC-candidate hunch paragraph updated
- OQ-SK-08: the landed note — ask #1 dissolved (bind-first establisher;
the real bound rides the open reply; POC #5's open-rides-the-accept
workaround + the 10s-bound finding retire), ask #2 landed at the
wire's native moment (forwarded op's {listen, substrate, peer}
params), correlation token per ADR-008 Amendment 1
- convergence: egress seam composes against 0.2.0; the upstream-asks
bullet records the landing per crate; the BIND hand-off bullet notes
variant 2 is now fully vanilla-fidelity
- checklist OQ-SK-08 item + POC #5 register entry point at the landed
note
poc-bind-findings.md: ledger statuses appended (superseded in shape;
evidence stands as the alktunnels-0.1.0 record)
AGENTS.md: alkcall pin 0.7.1 -> 0.8.0 (reply projection noted);
architecture context: alktunnels v0.2.0 entry added, alkcall 0.8.0
surface listed
Verified against the repos: alkcall 0.8.0 changelog (U-1/U-2/ADR-051),
alktunnels 0.2.0 changelog + ADR-007/008 + exports
(bindfirst_establisher producer.rs:641, register_tunnel_bindfirst_
openable :924), fast-socks5 still 1.0.0 with no net feature (the
courtesy tail). Docs-only change; no build surface affected.
channel_id is u32 on the wire (~4B ids, monotonic counter, ADR-040);
256 is the default per-connection max_channels (memory bound, 256x1MiB
reassembly buffers) and the default per-identity DoS cap (ADR-041) —
both configurable without a wire change. AGENTS.md convention 10 and
the OQ-SK-03 composed-egress note now carry the qualifier.
The root question is 'does wasm make sense for alksocks?', not 'how
do we get wasm': Case 1 (wasm wanted) -> fork-first, PR as courtesy,
carry regardless; Case 2 (wasm unwanted) -> plain dependency on the
router.rs native path, no fork (the alkhttp precedent, strictly
better when its premise holds). Decision inputs written: (a) is
there a planned sandboxed (wasm) consumer of the SOCKS5 service,
(b) is the fork genuinely minimal (POC #4 checks). Fork-first is a
conditional preference, not a general one — do not carry a fork for
an invariant's sake. AGENTS.md conventions 4/17 aligned.
- phase-0 vision: components split — (1) producer half (expose the
SOCKS5 service over channels), (2) consumer half (consume it,
optionally bind it locally — the ssh -D front door + tun2proxy
path), (3) standalone SOCKS client wrapper for quinn/noq that must
work with any RFC 1928 server (iroh relay/peer IP-leak motivation,
alknet ADR-090 generalized); the earlier docs conflated the
consumer-side bind with the producer-side local backend
- principle 6: the vpn-like endgame — tunnel a produced SOCKS5
resource to a local port, point tun2proxy (--proxy socks5://
natively) at it; verified tun2proxy src/args.rs
- OQ-SK-04 resolved as fork-first: 'fork' = vendor-and-vet inline in
the crate (minimal diff, feature-gate native-net), PR upstream as
courtesy, never wait on approval; wasm-drop (alkhttp precedent) is
the escape hatch, not the plan
- AGENTS.md conventions 4/9/17 aligned (fork-first, binds on either
side, wasm posture)
glm-5.3-flash