diff --git a/docs/research/phase-0.md b/docs/research/phase-0.md index b9f9687..a6f0383 100644 --- a/docs/research/phase-0.md +++ b/docs/research/phase-0.md @@ -1,7 +1,7 @@ --- status: draft -last_updated: 2026-09-14 (post-POC #2 review: OQ-SK-08 BIND, OQ-SK-09 -capacity, OQ-SK-05 virtual-subnet addendum, POC #5) +last_updated: 2026-09-15 (consistency pass: POC register in OQ-SK-07, +client-wrapper transfer residue cleaned, convergence checklist fixed) --- # alksocks — Phase 0 (Exploration) @@ -51,8 +51,9 @@ purposes and were at risk of being conflated):** channels. Components 1+2 form the producer/consumer protocol pair (channels in, -RFC 1928 inside); component 3 is standalone and composes with any -RFC 1928 server. Keep them structurally separate in the crate layout. +RFC 1928 inside). Keep them structurally separate in the crate layout. +(Component 3's standalone-client posture was the reason it transferred +cleanly to alknet — see the scope resolution below.) **Scope resolution (2026-09-14, post-POC): component 3 moves to the alknet rewrite.** The QUIC-runtime client wrapper's natural home is @@ -302,12 +303,21 @@ there, likely inherited: ECN is lost through the SOCKS5 header; the proxy must support UDP ASSOCIATE; `may_fragment() == true` disables path MTU discovery. -This crate's client half rehomes that work (cleaned up, `ClientDialError` -→ thiserror types, and the datagram codec sourced from fast-socks5 -rather than hand-rolled inline). The open question is noq (OQ-SK-06). +Historical note: this section originally framed the client work as +"this crate's client half" — the 2026-09-14 scope decision (§Vision) +moved it to the alknet rewrite, where the same cleanup applies +(`ClientDialError` → thiserror types; the datagram codec sourced from +fast-socks5 rather than hand-rolled inline). The open question that +remained here was noq (OQ-SK-06, now also transferred). ### noq — the quinn fork the client story must also fit +> **Transferred to the alknet rewrite (2026-09-14, the scope decision, +> §Vision).** The client wrapper is component 3 of the original +> three-component split; it moves to alknet wholesale, so this section +> is retained as background research for *alknet's* Phase 0, not as +> live scope here. See OQ-SK-06 for the transfer rationale. + `/workspace/noq` (v1.2.0; iroh's fork of quinn — iroh depends on `noq = "1.2.0"`). Surface verified: @@ -329,8 +339,9 @@ rather than hand-rolled inline). The open question is noq (OQ-SK-06). `Arc`→`Box` change ripples into construction. Whether one crate can serve both quinn and noq behind feature flags (shared core, two thin trait-impl shells) or whether the shapes have diverged enough to - justify two impls is the research question (OQ-SK-06). iroh's own - adoption makes noq support the practically-important target. + justify two impls is the research question (OQ-SK-06 — transferred + to the alknet rewrite; iroh's own adoption keeps noq support + practically important wherever the client wrapper lands). ### Anti-prior-art (what NOT to carry over) @@ -403,8 +414,12 @@ own optional username/password auth (RFC 1929). Questions: consults the alkcall `AuthContext`/`Identity` (filed upstream if the hook shape doesn't fit — AGENTS.md convention 17)? -(Answered in direction by the 2026-09-13 posture statement below: -yes / planes-don't-compare / probably-not — Phase 1 formalizes.) +(Answered in direction by the 2026-09-13 posture statement below — the +three answers map to the three bullets above: yes, the identity seam is +the only auth story on the producer side; planes-don't-compare, so the +"replace or second-gate" sub-question dissolves; probably-not, no +`AuthMethod` impl needed — the door checks credentials itself. Phase 1 +formalizes.) **Posture — settled direction (2026-09-13 discussion): "both," split by the door.** The planned end-to-end story is the vpn-like @@ -656,8 +671,11 @@ for the decision: odd standalone (no kernel egress) but composes — its dialer can open alktunnels channels further downstream, which is the hub story. - **What wasm would not serve:** component 3 (the quinn/noq client - wrapper) is native-only in practice — it wraps kernel UDP sockets for - UDP ASSOCIATE; no wasm story is expected there regardless. + wrapper — since transferred to the alknet rewrite) is native-only in + practice — it wraps kernel UDP sockets for UDP ASSOCIATE; no wasm + story is expected there regardless. (The transfer does not change + this OQ's inputs: components 1+2 were always the wasm-relevant + surface.) - **The alkhttp contrast, honestly weighed:** for alkhttp, "an HTTP client accessed over a channel" was judged weird, and the crate ships native-only. alksocks differs structurally: its protocol @@ -737,6 +755,11 @@ policy. ### OQ-SK-06: noq client support (and the quinn/noq shape split) +> **Resolved by transfer (2026-09-14, the scope decision, §Vision).** +> Everything below is retained as the question record for *alknet's* +> Phase 0; it is no longer this crate's scope. The transfer rationale +> is at the end of this section. + **Scope clarification (2026-09-12):** the SOCKS client wrapper is component 3 of the three-component split (§Vision) — a standalone client library for downstream users (alknet) that must work with *any* @@ -789,8 +812,23 @@ this crate's POC list accordingly. ### OQ-SK-07: POC scope for what remains unvalidated -Candidates, in rough priority order (per the SDD process's "validate -promising approaches"): +**POC register (2026-09-15 consolidation).** The list below grew +iteratively (a POC was added, dropped, and folded), so here is the +one-place accounting of all numbered POCs: + +| # | What | Status | Where | +|---|------|--------|-------| +| 1 | Channels-native SOCKS5 CONNECT | **Passed 2026-09-13** | `poc-connect-wasm-findings.md` | +| 2 | UDP ASSOCIATE (handle-swap shape) | **Passed 2026-09-14** | `poc-udp-associate-findings.md` | +| 3 | noq `AsyncUdpSocket` impl | **Dropped 2026-09-14** — transferred to alknet with OQ-SK-06 | — | +| 4 | fast-socks5 wasm fork-minimality | **Passed 2026-09-13** — folded into #1's worktree, shares #1's findings file | `poc-connect-wasm-findings.md` §POC #4 | +| 5 | BIND (accept-side command) | **Added 2026-09-14 with OQ-SK-08 — pending** | (OQ-SK-08) | + +Numbering is historical (do not renumber — findings files and commit +messages reference these numbers). Detailed descriptions follow. + +Candidates, originally in rough priority order (the order is historical +— #3 was dropped and #5 appended after the fact): 1. **Channels-native SOCKS5 CONNECT POC** — the producer half over a real alkcall channels connection: consumer opens a SOCKS5 channel, @@ -841,8 +879,9 @@ promising approaches"): POC — re-validating it here is optional.) **Dropped from this crate (2026-09-14, the scope decision):** the client wrapper transfers to the alknet rewrite (§Vision) — OQ-SK-06 - and this POC go with it. (At the time of the decision the list was - #1, #2, #4 — all passed; #5 (BIND) was added later with OQ-SK-08.) + and this POC go with it. (Before the decision the list was + #1–#4; after dropping #3 it was #1/#2/#4 — all passed. #5 (BIND) + was added later with OQ-SK-08.) 4. **fast-socks5 wasm check** — minimal crate, `cargo check --target wasm32-unknown-unknown`, confirm/inflect OQ-SK-04. Cheap; can fold into #1's worktree. **Run 2026-09-13 — fork-minimality verified** @@ -1043,7 +1082,9 @@ Candidate reading for the research specialist (to be expanded): - noq — `/workspace/noq`: `noq/src/runtime/mod.rs` (`AsyncUdpSocket`, `UdpSender`), `noq/src/endpoint.rs` (`new_with_abstract_socket`), `noq-udp/src/lib.rs` (`RecvMeta`, `Transmit`), `Cargo.toml` (workspace - versioning / publication posture). + versioning / publication posture). (Research transferred to the + alknet rewrite with OQ-SK-06 — retained here as alknet-facing + background.) - alktty — backend inversion point (`TtyBackend`), `TTY_OPEN_SCOPE` scope-gating shape, feature-gated `local` backend, wasm-clean default-crate verification commands. @@ -1059,8 +1100,9 @@ Candidate reading for the research specialist (to be expanded): as the "wasm-clean is preferred, not mandatory" escape hatch. - iroh — `/workspace/iroh` `iroh/Cargo.toml` (the noq dependency posture: `noq = "1.2.0"` from the n0 workspace) — context for - OQ-SK-06's dependency question; also the privacy motivation for the - client wrapper (relays/peers see the real IP). + OQ-SK-06's dependency question (transferred to the alknet rewrite); + also the privacy motivation that originally motivated the client + wrapper (relays/peers see the real IP). ## Convergence checklist (what Phase 0 must produce) @@ -1115,11 +1157,13 @@ Candidate reading for the research specialist (to be expanded): consumes no channels, has no consumers planned here); its research questions move to alknet's Phase 0; this crate's channels-native client story is POC-complete without it -- [x] Targeted POC(s) run + summaries in `docs/research/` - (three complete: #1 + #4 in `poc-connect-wasm-findings.md`, - #2 in `poc-udp-associate-findings.md`; #3 dropped with the - scope decision; **#5 (BIND) added 2026-09-14 with OQ-SK-08 — - pending**) +- [ ] Targeted POC(s) run + summaries in `docs/research/` + (the convergence-blocking POCs are complete — see the OQ-SK-07 + register: #1 + #4 in `poc-connect-wasm-findings.md`, #2 in + `poc-udp-associate-findings.md`; #3 dropped with the scope + decision. Left unchecked because **#5 (BIND), added 2026-09-14 + with OQ-SK-08, is still pending** — it gates Phase 1's BIND ADR, + not Phase 0's convergence.) - [x] Converge: recommended approach written up, ready to hand to the Architect for Phase 1 (§Convergence, 2026-09-14)