alksocks/docs/architecture/decisions/013-targeted-fork.md

ADR-013: The Targeted Fork: fast-socks5's T-Generic Subset Is Owned, Not Vendored

Status

Accepted (2026-09-22, post-extraction-review; supersedes the ADR-011 maintenance posture; ADR-011 stays for the extraction mechanics and the cut table; the ADR-011 §Amendment is subsumed here)

Context

ADR-011 pinned the inline-vendor posture as extraction (the T-generic subset copied in-tree, kernel-net region not copied; the net gate dissolving), and the vendor group (five implementation tasks plus the review gate) landed it in commits 57b107b..5b18d4d, with the review (tasks/implementation/ review-vendor-extraction.md) as the fidelity gate: the file-by-file diff vs /workspace/fast-socks5 v1.0.0 categorizes every hunk, and every review criterion passed.

The review also made the maintenance posture's cost visible. The tree is now permanently diverged from upstream in five categories:

1. The extraction cut: the kernel-net region, socks4, the legacy Config/Authentication layer, Socks5Datagram, the convenience dialers, the DNS helper: gone.
2. The carried changes: BIND's reply surface, the published new_reply.
3. The panic translations: ReplyError::from_u8 (the review's F-1), use_password_auth, reply_error's parse.
4. The error-pruning adjustments: anyhow/log/async-trait out, error variants pruned, MissingTargetAddr added.
5. The lint-allow posture: module-level #[allow]s preserving upstream style (u8::max_value(), needless lifetimes, match_like_matches_macro, io_other_error, wrong_self_ convention, the F-4 verbatim string) to keep the diff mechanical.

Category 5 exists solely to keep categories 1–4 reconcilable by a line-based diff. But a future re-base against an upstream release was never going to be a clean mechanical diff again; it was always going to be manual reconciliation across all five categories. The vendor posture's maintenance apparatus (verbatim preservation, the lint allows, the re-vendor/adjustment-list discipline) pays a permanent tax to serve a re-base path that would never be used.

The "vendor" framing also produced a real defect: the review's F-1 (ReplyError::from_u8's upstream unreachable!() arm kept verbatim; wire-reachable, a misbehaving peer could panic the consumer task) escaped precisely because the vendor posture maintained a second, weaker instruction set ("verbatim + adjustments list" instead of "project conventions, unconditionally"). The fidelity-vs-conventions tension is structural to the vendor framing; the review caught the escape, but the seam itself was the vendor framing's.

The fork point is now, post-review and post-F-1, the cleanest line the tree will ever present: the extraction provenance is in git history (57b107b..5b18d4d), the review is the recorded fidelity gate, and the five divergence categories are documented in ADR-011, vendor.md, and the review task. "The tree as of the review commit (5b18d4d) is the fork point" is a trivially defensible line.

Decision

• The extracted region is a targeted fork, fully owned by this crate. The "vendor" framing is retired: there is no upstream tree to stay reconcilable with, no re-vendor, no adjustment-list apparatus, no second instruction set. Project conventions (the AGENTS.md set) apply unconditionally to the forked code.
• The fork point is the tree as of commit 5b18d4d (the extraction review's gate commit). The extraction provenance is carried in git history (57b107b..5b18d4d), the module docs, and the extended LICENSE notice; the review task is the recorded fidelity gate.
• Module naming: the forked core is src/rfc1928/, re-exported as alksocks::rfc1928. "vendor" names an ownership relation (now gone); "socks5" would stutter with the crate name (alksocks::socks5) and collide with the future module structure (the producer/consumer/adapter layers are also SOCKS5-shaped). rfc1928 names what the module is (the RFC 1928 wire vocabulary and the state machines), permanent and collision-free.
• The lint-allow posture dissolves. The module-level #[allow]s and the "verbatim lint posture" module-doc paragraphs are removed; the suppressed smells are fixed per project conventions: u8::max_value() → u8::MAX, needless lifetimes elided, match_like_matches_macro applied, io::Error::new(Other) → io::Error::other, wrong_self_convention fixed on AuthMethod:: new(self, ..), the F-4 string re-worded (it no longer names a cut function), and the #[allow(dead_code)] on AuthenticationMethod swept with actual usage. Upstream's commented-out dead code stays dropped (F-2).
• The license mechanics: MIT permits sublicensing, so modifications after the fork point are this project's under the crate license (MIT OR Apache-2.0, per Cargo.toml). The bundled notice is extended, not replaced: upstream MIT text + copyright (the notice-preservation obligation, perpetual) + a fork-point statement + the modification note.
• The reference checkout survives as a behavioral reference. /workspace/fast-socks5 stays for differential testing of RFC edge cases; the differential suite (tests/rfc1928-differential.rs) pins bytes, not upstream text, so it survives the rename untouched. Textual-diff discipline is retired; behavioral differential testing is retained.
• The cut table is re-read as the not-forked inventory, the map of what to hand-port if a future need surfaces (e.g. the kernel-net region for a standalone vanilla-server example). The hand-port path replaces the re-vendor path: port against the reference checkout, adapt to the crate's conventions, and let the suite guard it.
• The honest cost: the cheap upstream-fix path closes. A future fast-socks5 fix (a reply-code mapping correction, a codec fix) arrives as a hand-port against the reference checkout, not a diff absorb. Risk is assessed low; fast-socks5 is a quiet project, and the extracted surface is the well-trodden RFC 1928 path.

Consequences

• Positive: one instruction set (project conventions, unconditionally); the lint-allow tax and the adjustment-list apparatus dissolve; smells are fixed at the only cost that matters: a one-time cleanup verified by the existing suite. The F-1 seam class (conventions-vs-fidelity gaps) is closed structurally.
• Positive: the module name is stable for the crate's future (no alksocks::socks5 stutter, no socks5::producer collision pressure).
• Negative (accepted): the cheap upstream-fix path closes; a future upstream fix is a hand-port against the reference checkout, guarded by the differential suite. Assessed low-risk (quiet upstream, well-trodden RFC surface).
• Neutral: the differential suite survives the rename untouched (it pins bytes, not upstream text). /workspace/fast-socks5 keeps its role as the behavioral reference; the only thing it loses is being the target of a line-based diff.
• Neutral: the fork-point line (5b18d4d) is recorded in git history, the module docs, and the extended LICENSE notice; the extraction provenance (the ADR-011 trail) remains readable.

References

• ADR-011 (the extraction mechanics, the cut table, the carried changes; the mechanics remain authoritative), ADR-002 (the protocol base), ADR-009 (feature gates, no net feature)
• tasks/implementation/review-vendor-extraction.md (the fidelity gate + F-1), docs/architecture/rfc1928.md (the owned-core spec)
• /workspace/fast-socks5 (v1.0.0, MIT, the behavioral reference for differential testing)