14ffe9c4

docs: record the selection lane's totality and history watermark

a73x 2026-08-18 12:27

Commit message

docs: record the selection lane's totality and history watermark

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

docs/decisions.md

+maps to the OSC 52 browser clipboard path, and `ee062dd9` to the shared mode
+semantics and DEC 2004 browser paste path; the mouse-mirroring half of the
+latter remains separate. No issue is closed by this record.
+## 2026-08-18 (selection review: totality, the history watermark, intent)
+**A request the daemon could decode leaves with an answer.** The selection
+lane is request/reply, and the only thing a requester can do with silence is
+wait out its timeout. So the decode now happens BEFORE the session lookup,
+and the two orderings mean different things: a malformed payload carries no
+id to correlate, and silence is the only honest response to it — but a
+well-formed request from a slot with no session (promoted by a QUIC
+handshake, never attached) does carry one, and answering `unavailable` costs
+a frame where dropping it cost the client five seconds. The same rule
+governs the encode: `unavailable` with no text is the one reply that cannot
+fail validation, so a failed encode of anything else falls back to it, and
+the capacity that fallback needs is reserved before the attempt that can
+fail. Totality is a property of the lane, not a property of the happy path.
+**Absolute screen rows are not a name for a line, so the reply carries the
+watermark that says so.** Row zero is the OLDEST RETAINED row, not the
+oldest row the session ever had. When the page list evicts a page every
+absolute row shifts underneath a request already in flight, and the reply
+that comes back is `ok`, valid UTF-8, and text the user never highlighted —
+the worst shape a bug can take, because nothing about it looks wrong.
+`selection_reply` therefore carries the daemon's `history_rows` sampled at
+extraction time, and the requester compares it with the reading it took when
+its own request became authoritative.
+The comparison is deliberately `lower means discard`, not `different means
+discard`, and that is the whole subtlety. Ordinary output RAISES the retained
+count without renaming a single row, because new rows are appended below the
+ones already there; demanding equality would make every selection taken
+during output unusable, which is most of the selections anyone wants. Only
+eviction lowers it. Measured on a five-column grid: the count climbed to
+, dropped to 5214 in one step, and absolute row zero changed identity at
+exactly that drop — page-sized jumps, never a slow drift.
+What this buys is a watermark, not a lease, and the difference is the point:
+the daemon holds no per-client selection state and gains none here. The
+residual hole is that an eviction followed by a whole page of fresh output
+INSIDE one round trip would read as a rise. That needs thousands of rows
+between the client's last applied frame and the extraction, and closing it
+would mean the daemon remembering who asked for what — a trade this feature
+has refused from the start.
+**User intent beats arrival order on the clipboard.** An explicit copy is the
+newest statement of what the human wants, so it retires the automatic OSC 52
+lane rather than racing it. A write already handed to the browser genuinely
+cannot be cancelled and that limit still stands — but the re-dispatch such a
+write performs when it settles is ours to start, and starting it put terminal
+text on the system clipboard after the gesture that asked for something else,
+with the UI still reading "Copied" for the selection. Retiring the version and
+the queued value together is what suppresses it. The rule is about which
+writes we choose to begin, and it does not pretend to own the ones already
+in the browser's hands.
+**The browser honours one OSC 52 target.** The protocol still accepts every
+Pc xterm defines, because the native client can route them: `p` is PRIMARY,
+`s` the selection, `0`-`7` the cut buffers. A browser tile has one
+destination and no way to reach the others, and writing them all to the
+system clipboard meant that an ordinary mouse drag inside the session — which
+is exactly what emits `ESC]52;p;…` in many X11 applications — silently
+clobbered whatever the human last copied on their own machine. Narrowing the
+web path to `c` is a loss of nothing anybody asked for. Non-`c` targets
+remain valid on the wire and are simply not this tile's business.
+**Validation run for this round.** `make build` and `make test` both exit 0,
+and `web/verify.js` reports 704/704 against `zig-out/bin/mux_core.wasm`, run
+directly as well as through the build graph. Every new assertion was watched
+failing first, against the mutation or the bug it exists for.
+The cross-version gate ran too, containerised, with this tree against
+v0.0.1-5 in both directions: 9 passed, 0 failed, 1 skipped, the skip being
+the agent surface the old ref predates. What it measures about the wire
+change is the general property and not the specific frame — an old client
+ignores daemon-to-client frames it has no arm for and keeps parsing past
+them, because they are length-prefixed and its dispatch ends in
+`else => {}`. It could not be made to measure `selection_reply` itself,
+and that is a fact about the protocol rather than a gap in the rig: nothing
+can make a daemon send one to a client that never asks.