docs: implementation plan (TTY precedents folded in); task decomposition (17 tasks)

Plan updated with the alknet-tty findings: the drainer pattern
(single ordered writer) makes outbound chunk-boundary parsing sound;
TestStdinSink's try_send→Full→Pending is the inbound backpressure
precedent; OQ-01(a) now cites the reference.

Task graph (taskgraph-validated, 17 tasks, 6 generations, no cycles):
- tasks/server/: core-types, auth, healthz-decoy, adapter
- tasks/gateway/: dispatch, routes, publish
- tasks/websocket/: byte-adapter (research POC), upgrade-session, overlay-ops
- tasks/adapters/: from-openapi, from-jsonschema, to-openapi, from-wss, mcp
- tasks/client/: http-host
- tasks/infra/: integration-suite (phase 4)

Critical path runs through server core → adapter → WS session →
overlay tests → integration suite. High-risk tasks are the three WS
tasks, de-risked by the ws-byte-adapter POC blocking upgrade-session.
This commit is contained in:
2026-08-28 06:05:45 +00:00
parent eaf1a203bc
commit 63dc4b6d06
19 changed files with 784 additions and 4 deletions
+19 -2
View File
@@ -39,10 +39,27 @@ unknowns that would have shaped tasks incorrectly:
EOF → all channels cleared. The adapter maps WS close to transport
EOF and lets alkcall's invariants do the rest.
5. **`Dispatcher::run_loop_single_stream` exists** and is the channel-0
dispatch loop — no new dispatch code is needed anywhere in alkhttp.
dispatch loop — no dispatch code is needed anywhere in alkhttp.
6. **The alknet-tty crates provide the precedents for the adapter.**
The channels protocol was abstracted from TTY's earlier 5-byte
demux work, and `alknet-tty`'s adapter embodies the two patterns
OQ-01 needed:
- **The drainer pattern** (`pump_session`): all producer pumps feed
one bounded mpsc; a single drainer writes chunks in arrival
order. The transport write side is therefore sequential — a
boundary-parsing state machine in the WS adapter's write path is
sound (no interleaving to handle).
- **Bounded backpressure** (`TestStdinSink::poll_write`):
`try_send``Full``Poll::Pending` — the inbound buffer
pattern for the WS→bytes direction.
This de-risks the two "high" tasks (WS adapter, WS session) from
"unknown design" to "known shape, careful implementation."
"unknown design" to "known shape, careful implementation." A targeted
POC (research task) still validates the full loop — axum WS ↔ adapter
↔ alkcall ChannelsAdapter + channel-0 dispatcher over duplex — before
the production implementation builds on it, since axum's WS API
specifics (message sizing, backpressure interplay) are the one part
neither the specs nor the TTY precedent exercise.
## Build order (dependency spine)