docs: phase-0 consistency pass — POC register + client-wrapper transfer residue

- OQ-SK-07: add a POC register table (one-place accounting of all five numbered POCs: #1/#2/#4 passed, #3 dropped, #5 pending); mark the priority order as historical; note numbering must not be renumbered - §Vision: fix the components 1+2 layout sentence now that component 3 transferred; keep the transfer reasoning - alknet-client ancestor section: replace the stale 'this crate's client half rehomes that work' sentence with a historical note (the rehoming is alknet's, per the 2026-09-14 scope decision) - noq prior-art section + OQ-SK-06: add transfer banners so ~25 lines of transferred research are not read as live scope - OQ-SK-02: spell out what the 'yes / planes-don't-compare / probably-not' shorthand maps to - OQ-SK-04: note the component-3 transfer does not change the wasm decision inputs - OQ-SK-07 #3: rewrite the ambiguous 'at the time of the decision' parenthetical as before/after - Survey list: mark noq and iroh entries as alknet-facing background - Convergence checklist: uncheck the POC item (BIND POC still pending) and explain the checkbox semantics Verified against the repo: findings files, POC crates (alksocks-connect-poc 8 tests, alksocks-udp-poc 11 tests, alksocks-fs5-wasm-poc exists), upstream line refs (fast-socks5 lib.rs:384-386 / server.rs:813-816 / 1195, noq runtime/mod.rs:44 / endpoint.rs:162, alktunnels producer.rs:207,392), op name channels/socks5/sub in both POC crates. Verification: docs-only change; no build/test surface affected.
2026-09-15 04:07:42 +00:00
1 parent 601afa3922
commit aac63d17fc
@@ -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)