docs: correct WS framing claims from spike; add implementation plan

Spike against alkcall source resolved ADR-067 assumptions:
- write_chunk issues header+payload as separate write_alls; channel
  0's write_frame issues prefix+body separately — a logical write can
  surface as multiple chunks, so the WS adapter must parse outgoing
  chunk boundaries (byte-stream treatment both directions), not assume
  write-per-chunk or message-per-chunk
- MAX_CHUNK_LEN is 16 MiB; the WS path needs a practical message cap
  with oversized chunks split across messages
- install_channel_zero + run_loop_single_stream confirmed as the exact
  server-side seam; EOF/teardown invariants already specified by
  alkcall (REQ-CH-01/02)

Corrections applied to websocket.md, ADR-067, OQ-01.

docs/plans/implementation.md: scoped plan guiding task decomposition —
spike findings, 4-phase build order, OQ dispositions, task conventions.
This commit is contained in:
2026-08-28 05:55:03 +00:00
parent 320ea87b08
commit eaf1a203bc
4 changed files with 160 additions and 24 deletions
+14 -7
View File
@@ -22,15 +22,22 @@ with their resolutions; new alkhttp OQs start at OQ-01.
needs nailing down before implementation:
(a) inbound buffer bound (bounded channel between the WS read task
and the `AsyncRead` half — what bound, what policy on overflow);
(b) write-side chunk completeness (the adapter assumes the mux emits
each chunk as one contiguous `write_all` — verify against alkcall's
`MuxRunner` and codify, or add an internal chunking layer);
(b) write-side chunk boundary parsing (verified against alkcall
source: the mux emits one mpsc payload per chunk, but a logical
write above the mux — e.g. channel 0's `write_frame`, which issues
prefix and body as separate `write_all`s — can surface as multiple
chunks; the adapter must parse outgoing chunk headers rather than
assume write-per-chunk; also confirm the WS-message cap policy for
chunks up to `MAX_CHUNK_LEN` = 16 MiB — split across messages, and
what the practical cap is for browser stacks);
(c) flush mapping (`AsyncWrite::flush` → WS message emission point);
(d) close mapping (WS close code → transport EOF → REQ-CH-02
teardown; and does `AsyncWrite::shutdown` map to a WS Close frame or
to a zero-length chunk sentinel?).
- **Blocked on**: nothing (implementation-blocking, not
decision-blocking — resolve during implementation of the WS adapter)
teardown; `AsyncWrite::shutdown` maps to the zero-length EOF
sentinel (REQ-CH-01) then a WS Close frame — confirm this ordering
against the mux's pump-exit behavior).
- **Blocked on**: nothing (the spike resolved the factual
sub-questions; the remaining items are implementation decisions to
lock during the WS adapter task)
### OQ-02: `/publish` body framing details