The batch-1 gate review (tasks/implementation/review-protocol-core.md):
all eight criteria examined (seam contracts, wire fidelity, access
control, teardown/lifecycle, conventions, wasm, POC fidelity, docs
sync); the gate to batch 2 opens. Findings R-1/R-2 were corrected in
the review change; R-3..R-5 are doc residues fixed in the same change;
R-6 is accepted with rationale.
- R-1 (major): the datagram stage's Ok(None) re-park is unsafe against
a zero-yield egress — a next_reply that is a pure instantly-ready
Ok(None) with no await wins every select! poll and livelocks the
stage on a current-thread runtime (empirically reproduced; the
landed unit test's mutex masked the hazard at its lock's yield
boundary; multi-thread survives). Fix: the Ok(None) handler yields
before re-parking; a pinning unit test drives the strictest
zero-yield violator.
- R-2: the two into_inner expect()s (consumer sessions) become typed
Result<_, SpentSessionError> — convention 2's no-panic rule; spent-
session unit tests pin the shape; test call sites updated.
- R-3/R-4/R-5: doc residues — stale task-time phrasings in
egress.rs/producer.rs, producer.md's register() sketch reconciled
to the landed signature, the establishment-bound test doc reworded
to what the substrate-free probe actually pins.
- R-6 (accepted): the wasm gate rides a transitive getrandom/wasm_js
feature unification (alkcall -> jsonschema/referencing -> ahash) —
verified compiling clean today; noted for OQ-SK2-06.
Verified: cargo test 348 green; --all-features green; clippy
--all-targets -D warnings clean; fmt --check clean; both wasm checks
clean (from a clean wasm target dir); cargo doc --no-deps clean.
The bind-only-identity reconciliation from the integration session
was independently verified as correct (ADR-006 as landed; the suite
pins it). Batch boundary holds: no local/composed code exists.
The batch-1 closing task: nine cross-cutting integration tests
(tests/core-integration.rs) pinning the whole protocol core end to
end over the channels harness, plus the architecture-sync docs pass.
Tests:
- One registration, all three commands: CONNECT + ASSOCIATE + BIND
interleaved live on the one channels/socks5/sub op; a teardown
ends only its own session (mux/demux isolation) — the POC #2/#5
regression guard, complete.
- Concurrency: nine concurrent mixed-command sessions (raw topology)
and six through the typed consumer sessions (consumer-side
topology) — the mux/demux pinned in both channel-id allocation
directions; fresh round-trips after the burst; no channel leaks.
- Teardown matrix (wire.md §Sentinels and lifecycle): CONNECT
half-close, ASSOCIATE EOF, BIND client-gone (a parked accept so
the quiet-wait exit is deterministic) — each followed by fresh
sessions of every command (no connection poisoning).
- Identity/scope matrix (ADR-006 end to end): open-only (CONNECT +
ASSOCIATE serve, BIND refused 0x02 at the command gate), bind-only
fail-closed at the open gate for all commands (the spec drift the
task's phrasing carried, reconciled — ADR-006's open gate requires
socks5:open unconditionally), both-scopes (everything, granted
explicitly); the CF-006 witness asserted per row.
- The readiness contract re-pinned under concurrent load: a
hot-Ok(None) egress across concurrent associations does not starve
the datagram stage's channel branch.
Docs sync: README Current State ("the protocol core is implemented"
+ the landed inventory; the decomposition residue gone); consumer.md
§Wiring reconciled to the landed session signatures; ADR-006
§Consequences states the grant asymmetry explicitly; lib.rs crate
docs describe the landed surface.
Verification: cargo test 302 green; --all-features green; clippy
--all-targets -D warnings clean; fmt --check clean; both wasm checks
clean; cargo doc --no-deps clean. Batch boundary holds: no
local/composed code, the default crate is protocol-only.
- frame(addr, payload): [len: u16 BE][addr + data] over
TargetAddr::to_be_bytes() + payload; the joint bound enforced at
frame time (checked_add; 65507 + 255-char domain = 65766 > 65535 →
Oversize) with addr_encoding_len exposed (7 v4 / 19 v6 / 259 max
domain) and MAX_INNER_LEN pinned
- DatagramReader: incremental reassembly across chunk boundaries
(split frames, batched frames, partial headers), infallible,
returning per-frame Results; the addr sub-layout decoded by hand
(ATYP-keyed, UTF-8-validated) with typed decode errors —
BadAtyp / ShortAddress / DomainNotUtf8 / EmptyFrame — so the
producer stage fails the association loud on protocol garbage
(udp_undecodable_frame_ends_association, POC #2)
- module docs state the framing-once invariant (the egress speaks
inner bytes; this layer owns the single length prefix — the
double-framing bug class POC #2 caught), the F-2 invariant at
payload level (a zero-length payload is a legal empty datagram,
never EOF; wire len == 0 is unreachable garbage), and the EOF
layering (the channels-level sentinel, outside the codec)
- doc-sync: wire.md + bast.md residue corrected — "len == 0 is a
legal empty datagram" replaced with the payload-level F-2
statement (len == 0 unreachable since addr >= 7 bytes)
- lib.rs re-exports frame, DatagramReader, addr_encoding_len,
MAX_INNER_LEN, WireError (convention 15)
Verification: cargo test (58 lib + 37 differential), clippy
--all-targets -- -D warnings, fmt --check, doc --no-deps, and both
wasm checks (check + clippy on wasm32-unknown-unknown) — all clean.
The mechanical half of the posture change: src/vendor/ ->
src/rfc1928/ (module alksocks::rfc1928), tests/vendor-differential.rs
-> tests/rfc1928-differential.rs (git mv — history preserved).
- Fork point pinned: the tree as of 5b18d4d (the extraction review's
gate commit); provenance permanent in the module docs and the
extended LICENSE notice (upstream MIT preserved, fork-point +
post-fork modification statement added — extend, never replace)
- The lint-allow posture dissolved: all module-level #[allow]s
removed and the suppressed smells fixed (u8::max_value() ->
u8::MAX, needless lifetimes elided, match_like_matches_macro
applied, io::Error::new(Other) -> io::Error::other, the
AuthMethod::new self-taking signature renamed
into_starting_state, the F-4 ToSocketAddrs string re-worded — it
no longer names the cut resolve_dns(), the unused ready! macro
and dead AuthenticationMethod::from_u8 removed, the upstream
commented-out async-std note folded into the impl doc)
- Module docs rewritten: ownership statement (project conventions
apply unconditionally), extraction provenance (ADR-011) +
ownership (ADR-013) + maintenance posture (behavioral reference,
hand-port path)
- Differential suite survives the rename untouched (32 tests pin
bytes, not upstream text)
Verification: cargo test (38+32 green), cargo clippy --all-targets
-D warnings, cargo fmt --check, cargo check/clippy
--target wasm32-unknown-unknown, cargo test --all-features, cargo
doc --no-deps — all pass.
The extraction review against vendor.md's cut table, ADR-011
§Amendment, and AGENTS.md conventions. All five file diffs vs the
fast-socks5 v1.0.0 reference checkout read hunk-by-hunk and
categorized (cut / carried changes / adjustments / provenance /
tests); wasm, clippy, fmt, doc all green; RFC 1928 spot-checks
(reply form, method order, UDP zero fallback, domain cap, FRAG
split) independently verified against the RFC text.
F-1 (critical, resolved here): ReplyError::from_u8 kept upstream's
unreachable!("ReplyError code unsupported.") arm while being
wire-reachable — Socks5Stream::read_request_reply feeds the raw
reply byte from the wire into it, and RFC 1928 §6 marks 0x09-0xFF
unassigned, so a misbehaving peer would panic the consumer task.
Unassigned codes now map to GeneralFailure (the RFC's catch-all),
pinned by a new test, and the panic-translation adjustment is
recorded in vendor.md's adjustment list (with the Config-Default
and write_all notes) in the same change.
Findings F-2..F-4 (dead commented code dropped with its region;
Cargo.toml feature-layout comments; the preserved resolve_dns error
string) reviewed and accepted. Review task file carries the full
record; the gate to the downstream task groups is open.
Verified: cargo test (38 + 32), cargo test --all-features, clippy
--all-targets and --target wasm32-unknown-unknown (-D warnings),
cargo check --target wasm32-unknown-unknown, cargo fmt --check,
cargo doc --no-deps.
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).
glm-5.3-flash