a9c7aaf8
docs: roadmap.md — the forward view in one file
a73x 2026-08-08 14:20
Commit message
README.md
| Old | New | ||
|---|---|---|---|
| @@ -105,7 +105,8 @@ can. Transport is deliberately dumb: the same frames ride a unix socket, an | |||
| 105 | ssh pipe (`muxd proxy` is a byte pump with zero protocol knowledge), or a | 105 | ssh pipe (`muxd proxy` is a byte pump with zero protocol knowledge), or a |
| 106 | QUIC stream, and the wire protocol has survived all three without changing. | 106 | QUIC stream, and the wire protocol has survived all three without changing. |
| 107 | 107 | ||
| 108 | Design: `docs/handoff.md`. Every decision and measurement: `docs/decisions.md`. | 108 | Design: `docs/handoff.md`. Every decision and measurement: |
| 109 | `docs/decisions.md`. What's next: `docs/roadmap.md`. | ||
| 109 | 110 | ||
| 110 | ## Status | 111 | ## Status |
| 111 | 112 | ||
docs/roadmap.md
| Old | New | ||
|---|---|---|---|
| @@ -0,0 +1,69 @@ | |||
| 1 | # Roadmap | ||
| 2 | |||
| 3 | The forward view, one item per line, ranked. History and evidence live in | ||
| 4 | `decisions.md` — every item here points back at its entry there. Update | ||
| 5 | this file at each milestone close and whenever the queue reorders; the | ||
| 6 | queue's order is set by the user, not by this file. | ||
| 7 | |||
| 8 | **Now:** `v0.0.1-1` tagged; M1–M8 complete; in field trial on real VMs. | ||
| 9 | Trial feedback outranks everything below — what actually hurts in use is | ||
| 10 | better data than any of this ranking. | ||
| 11 | |||
| 12 | ## M9 — prediction (speculative local echo) — queued | ||
| 13 | |||
| 14 | The client paints predicted echo for printable keystrokes immediately and | ||
| 15 | reconciles against the daemon's authoritative delta when it arrives. | ||
| 16 | Sequencing set 2026-08-07: reconnect → QUIC → prediction. Only pays on | ||
| 17 | high-RTT links — the protocol itself costs ~4ms over baseline, so LAN | ||
| 18 | users will never see the difference (decisions.md, M6 verdict). | ||
| 19 | |||
| 20 | Scope per handoff §5: conservative, line-mode only, printable chars, | ||
| 21 | unconfirmed text visually distinguished, instant fallback on anything | ||
| 22 | unpredictable. Design sketch discussed 2026-08-08: prediction is an | ||
| 23 | *overlay* on the replica, never fed into it; daemon ships pty mode bits | ||
| 24 | (echo/icanon) so disabled contexts are known, not guessed. | ||
| 25 | |||
| 26 | **Pre-requisite, blocking:** rewrite the RTT-multiple kill-criterion form | ||
| 27 | — two milestones' criteria (M6 reattach gate, M8 leg 2) failed on fast | ||
| 28 | hardware for the same structural reason; a threshold needs a floor term or | ||
| 29 | a stated minimum RTT before M9 writes another one (decisions.md, "Banked | ||
| 30 | by M8"). | ||
| 31 | |||
| 32 | **Hazard carried in:** speculative buffers held across callbacks are the | ||
| 33 | habitat of the UAF-that-never-crashes (decisions.md, M8 egress/teardown | ||
| 34 | records). | ||
| 35 | |||
| 36 | ## Trial friction, likely next after (or before) M9 | ||
| 37 | |||
| 38 | - **Daemon lifecycle**: attach does not auto-start `muxd run`; no install | ||
| 39 | script; systemd user units exist in `contrib/` but are not the deployed | ||
| 40 | recipe. First annoyance any trial hits. | ||
| 41 | - **First-backoff tuning**: a reconnect after a tear can pay a 200ms–2s | ||
| 42 | backoff step; measured ~4x win available on fast links, ~2x on slow | ||
| 43 | (decisions.md, M7). | ||
| 44 | |||
| 45 | ## Banked, ranked by expected win | ||
| 46 | |||
| 47 | 1. **Retry-skip via NEW_TOKEN** — ~1 RTT off QUIC cold attach, which is | ||
| 48 | most of QUIC's remaining margin over ssh-via. Not "skip Retry": token | ||
| 49 | for validated clients, RFC 9000 3x anti-amplification for the rest — | ||
| 50 | dropping validation without one of those is a regression wearing a | ||
| 51 | performance win's clothes (decisions.md, "Banked by M8"). | ||
| 52 | 2. **Half-open reaping policy** — handshake-without-attach holds a slot | ||
| 53 | until idle timeout; bounded, measured at 0 held under a ten-tear loop; | ||
| 54 | `muxd stats clients=N` is the instrument for deciding the policy. | ||
| 55 | 3. **`idle_ms` split three ways** — death detection, handshake bound, | ||
| 56 | half-open reaping are one knob doing three jobs. | ||
| 57 | 4. **`timeoutMs` buffered-frame short-circuit** — a whole frame already | ||
| 58 | buffered can wait out the poll, up to ~100ms of render lag; one line if | ||
| 59 | it ever shows against a real RTT. | ||
| 60 | 5. **Protocol criterion restatement + dedup pass** — leg 4's "protocol.zig | ||
| 61 | unchanged" restated as "no transport may need a protocol change", and a | ||
| 62 | dedup across the three transport arms now that there are three. | ||
| 63 | 6. **`addCSourceFiles` for the QUIC deps**, replacing the build script. | ||
| 64 | 7. **Autotools wolfSSL + ticket resumption** — the only route to 0-RTT. | ||
| 65 | 8. **Certificates / TOFU · QUIC datagrams for input · multi-session per | ||
| 66 | connection · NAT traversal** — parked as a group. | ||
| 67 | 9. **Scrollback retention tuning** — policy decided (engine-native 10k | ||
| 68 | ring); making the limit configurable is what remains, and nobody has | ||
| 69 | hit the ceiling. | ||