---
id: ws-byte-adapter
name: WS ↔ byte-stream adapter (research POC → production shape)
status: pending
depends_on: []
scope: moderate
risk: high
impact: phase
level: research
tags: [websocket, phase-2, poc]
---

## Description

Targeted POC validating the WS↔byte-stream adapter contract (OQ-01)
before the production implementation: wrap axum's `WebSocket` as
`AsyncRead + AsyncWrite` such that alkcall's `ChannelsAdapter` demux
and mux run over it correctly.

Inbound: axum WS messages → shared bounded buffer → `AsyncRead` drains
(backpressure via the alknet-tty precedent: try_send → Full → Pending).
Outbound: `AsyncWrite` accumulates into a pending buffer; a task parses
outgoing 8-byte chunk headers (verified: header+payload are separate
writes; channel 0's write_frame is prefix+body separately) and emits
each complete chunk as one WS binary message; chunks over the WS
message cap (~1 MiB default) split across messages. Close: WS close →
transport EOF (REQ-CH-02); `AsyncWrite::shutdown` → zero-length
sentinel then Close frame (REQ-CH-01).

## Acceptance Criteria

- [ ] POC: adapter + ChannelsAdapter + channel-0 Dispatcher over `tokio::io::DuplexStream` pairs — call round-trip works
- [ ] POC test: 16 MiB chunk splits across WS messages and reassembles
- [ ] POC test: interleaved channel writes preserve chunk integrity (no torn chunks)
- [ ] OQ-01 sub-items (a)-(d) resolved with concrete values, written back into open-questions.md
- [ ] Findings + go/pivot recommendation recorded in this task's Summary

## References

- docs/architecture/websocket.md (§The WS ↔ byte-stream adapter)
- docs/plans/implementation.md (§What the spike established, point 6)
- alknet-tty precedent: `src/adapter.rs` `pump_session` drainer pattern + `TestStdinSink` backpressure
- alkcall: `channels::wire::write_chunk`, `channels::mux::MuxRunner`, REQ-CH-01/02 in `channels-wire.md`

## Notes

> Agent fills during implementation. This is a research task: the POC
> code lands under `.worktrees/research/` or a `#[cfg(test)]` module —
> not as final production code — but the production adapter may grow
> directly from it if the shape holds.

## Summary

> Agent fills on completion.