@earendil-works/chord 1.4.0 → 1.5.0

package/docs/next/flow-control/book.md

@@ -0,0 +1,333 @@
+---
+title: Flow control for Chord links
+cover: Slow / Links
+kicker: A design note · Chord v2 slice 4 · 2026-10-22
+subtitle: How a phone on a bad train connection keeps seeing the newest state of a streamed reply, and why the transport's own backpressure cannot do that
+stats:
+  - 9.4 s | how old the newest state was with transport backpressure only
+  - 0.0 s | with an acknowledged window of two messages
+  - 345 ms | another client's p95 during a call flood, without a call window
+  - ~200 | lines for the converged design
+note: |
+  Written from the measurements and the cross-checked reports of the reviewers Astra and Fable (2026-10-22): Node 24.4.1,
+  `ws` 8.22, separate server and client processes, a throttling proxy at 64 KiB/s. The numbers are single synthetic
+  runs: they show failure modes, not production capacity. Relays: first decided as per-hop acknowledgements (b) on
+  2026-10-23, then replaced by flow control per origin on 2026-10-24 after the slice 4a benchmarks (chapter VI).
+colophon: Flow control for Chord links · fourth edition · 2026-10-24 · based on the reviewers' experiments and design §3, §22
+---
+
+# Before we begin {.preface}
+
+Mario is on a train. His phone shows a p3 session in which the agent is writing a long reply. Every token is a small
+state change: the worker commits it, the server relays it, the phone applies it. The train enters a tunnel and the
+phone's link drops to a trickle, 64 KB per second. The worker keeps producing tokens at full speed.
+
+Without flow control, every token still gets sent. The bytes pile up somewhere between the worker and the phone, and
+when the train leaves the tunnel the phone has to work through a backlog of old tokens before it sees the current text.
+It is not only slow: what it shows is minutes old, and nothing tells it so.
+
+This note explains what keeps the phone current, why the obvious answer (let the transport push back) fails, and the
+design Astra and Fable converged on after measuring it.
+
+## Six things to know
+
+:::findings
+1. **Transport backpressure arrives too late.** The kernel's and a proxy's buffers take megabytes before a WebSocket
+   reports anything buffered; the phone sees state 4 to 10 seconds old.
+2. **Acknowledgements keep state fresh.** The receiving application acknowledges each message; at most two are in
+   flight; the newest state was 0.0 seconds old on the same 64 KB/s link.
+3. **Count messages, not bytes.** Each message carries everything that piled up since the last acknowledgement, so
+   throughput adapts to the link by itself.
+4. **Merge ops first, snapshot last.** 2,000 merged token appends cost 26 KB, sent one by one 46 KB; a snapshot of a
+   member with 500 KB of history would cost 508 KB.
+5. **Calls need their own window.** A tab firing 100,000 calls pushed another client's p95 to 345 ms; with a window of
+   64 respected by the caller it stayed at 0.66 ms and the flood waited in the buggy tab.
+6. **Nothing is refused for being too many** (decision K16): extra state is merged, extra calls wait.
+:::
+
+## Words used throughout
+
+A **link** connects two hosts. The **provider** owns an object and sends its state; the **consumer** holds a
+reference to it. A **hold** is one reference over a link, with its own stream of **ops** (Delta's changes). A
+**snapshot** is a hold's whole state. An **acknowledgement** (`ack`) is a tiny message the consumer sends after it
+applied a state message. **In flight** means sent and not yet acknowledged. **Coalescing** means merging the ops that
+wait to be sent. A **relay** is a host in the middle (the server between worker and tab).
+
+# Where the Bytes Hide {#hidden lede="Why the sender cannot see a slow phone."}
+
+A WebSocket in Node reports `bufferedAmount`: bytes the library still holds. It looks like the perfect signal: stop
+sending when it grows. The experiment says otherwise.
+
+:::sequence animate | A flood of state messages to a slow phone through a proxy. The sender's buffer stays small; the kernel's and the proxy's do not.
+actor worker "worker" "commits tokens" accent
+actor ws "server WebSocket" "bufferedAmount"
+actor kernel "kernel + proxy buffers" muted
+actor phone "phone" "64 KB/s" blue
+worker -> ws: token 1 … token 9,000
+ws -> kernel: written at once (bufferedAmount stays near 0)
+kernel -> phone: drains at 64 KB/s
+note kernel: megabytes waiting
+worker -> ws: token 9,001 (the newest)
+ws -> kernel: queued behind everything
+kernel --> phone: arrives seconds later
+:::
+
+| Flood, ~9,800 × 128 B per second, 64 KB/s link | Sender memory | Newest state the phone saw |
+| --- | --- | --- |
+| no flow control | 7.0 MB queued in the WebSocket, heap +18.5 MB | 9.4 s old |
+| cap `bufferedAmount` at 64 KiB, merge pending state | +0.46 MB | **still 9.4 s old** |
+| cap at 1 MiB (Fable's rerun) | small | 3.8 s, growing to 10.4 s |
+| at most 1 to 4 acknowledged messages in flight, merge pending state | +0.4 MB | **0.0 s** |
+
+The transport's backpressure protects the sender's memory, but freshness depends on buffers the sender cannot see:
+the operating system's socket buffer, autotuned to hundreds of kilobytes, and every proxy on the way. A normal
+streamed reply (50 tokens per second, 23 bytes each) never fills them; a burst or a tunnel does. Only the receiving
+application knows what it has applied.
+
+# Acknowledged Messages {#acks lede="A window of two messages in flight, and why it adapts to any link."}
+
+The rule: a provider has at most **K = 2** state messages in flight per link. The consumer sends `ack` (three bytes in
+the binary codec) after it applied one. While two are in flight, new commits do not produce messages; their ops wait,
+merged per hold, and go out in the next message once an `ack` arrives.
+
+:::steps | Two messages in flight on a slow link
++++ Fast link
+Commits 1, 2, 3 each become a message; each is acknowledged before the next commit. Nothing waits: the window never
+fills, so a normal stream behaves exactly as without flow control.
++++ The link slows
+Messages 1 and 2 are in flight. Commits 3 to 400 arrive; their ops are folded into the pending queue of each member
+they touch (chapter III). Memory: the net change, not the history; at most 10,000 ops per member.
++++ An ack arrives
+`ack` for message 1. The provider sends message 3, carrying the folded ops of commits 3 to 400, encoded once.
+The phone applies them as one batch and shows the newest text.
++++ Self-clocking
+The slower the link, the more each message carries; the faster, the smaller and more frequent. Nobody measures
+bandwidth: the acknowledgements pace the sender.
+:::
+
+:::raw
+<div id="fc-sim" style="font-family: var(--sans, system-ui); margin: 1.5rem 0; padding: 1rem; border: 1px solid #d8d2c6; border-radius: 6px; background: #fbf9f4;">
+  <div style="display:flex; gap:1rem; flex-wrap:wrap; align-items:center; font-size:0.9rem;">
+    <label>Link <input id="fc-rate" type="range" min="2" max="60" value="8"> <span id="fc-rate-v"></span> msgs/s</label>
+    <label>Commits <input id="fc-prod" type="range" min="5" max="120" value="60"> <span id="fc-prod-v"></span> /s</label>
+    <button id="fc-reset" style="font:inherit; padding:0.2rem 0.6rem;">Restart</button>
+  </div>
+  <canvas id="fc-canvas" width="640" height="220" style="width:100%; max-width:640px; display:block; margin-top:0.8rem;"></canvas>
+  <div id="fc-stats" style="font-size:0.85rem; margin-top:0.4rem; color:#444;"></div>
+</div>
+<script>
+(() => {
+  const c = document.getElementById("fc-canvas"), g = c.getContext("2d");
+  const rate = document.getElementById("fc-rate"), prod = document.getElementById("fc-prod");
+  const rv = document.getElementById("fc-rate-v"), pv = document.getElementById("fc-prod-v");
+  const stats = document.getElementById("fc-stats");
+  let s;
+  function reset() {
+    s = { t: 0, commit: 0, naive: { queue: [], shown: 0, sent: 0 }, ack: { inflight: [], pending: 0, shown: 0, sent: 0, merged: 0 } };
+  }
+  function step(dt) {
+    const r = +rate.value, p = +prod.value; rv.textContent = r; pv.textContent = p;
+    s.t += dt;
+    const commits = Math.floor((s.t) * p) - s.commit;
+    for (let i = 0; i < commits; i++) {
+      s.commit++;
+      s.naive.queue.push(s.commit);
+      s.ack.pending = s.commit;
+    }
+    // link capacity: r messages per second, shared model: each delivers one message per 1/r s
+    s.naive.budget = (s.naive.budget || 0) + dt * r;
+    while (s.naive.budget >= 1 && s.naive.queue.length) { s.naive.budget -= 1; s.naive.shown = s.naive.queue.shift(); s.naive.sent++; }
+    s.ack.budget = (s.ack.budget || 0) + dt * r;
+    while (s.ack.budget >= 1 && s.ack.inflight.length) { s.ack.budget -= 1; s.ack.shown = s.ack.inflight.shift(); }
+    while (s.ack.inflight.length < 2 && s.ack.pending > (s.ack.inflight.at(-1) ?? s.ack.shown)) {
+      s.ack.merged += s.ack.pending - (s.ack.inflight.at(-1) ?? s.ack.shown) - 1;
+      s.ack.inflight.push(s.ack.pending); s.ack.sent++;
+    }
+  }
+  function lane(y, label, queue, shown, color) {
+    g.fillStyle = "#222"; g.font = "13px system-ui"; g.fillText(label, 8, y - 26);
+    g.fillStyle = "#e9e3d6"; g.fillRect(8, y - 18, 520, 26);
+    const n = Math.min(queue, 130);
+    g.fillStyle = color;
+    for (let i = 0; i < n; i++) g.fillRect(10 + i * 4, y - 15, 3, 20);
+    g.fillStyle = "#222"; g.fillText(`waiting: ${queue}`, 540, y);
+    const age = s.commit - shown;
+    g.fillText(`phone shows commit ${shown}, ${age} behind`, 8, y + 28);
+  }
+  function draw() {
+    g.clearRect(0, 0, c.width, c.height);
+    lane(48, "No flow control: every commit is sent and queued", s.naive.queue.length, s.naive.shown, "#b5523b");
+    lane(150, "Acknowledged window (K = 2), pending ops merged", s.ack.inflight.length, s.ack.shown, "#3b6fb5");
+    stats.textContent = `newest commit ${s.commit} · window: ${s.ack.sent} messages carried ${s.commit} commits (${s.ack.merged} merged)`;
+  }
+  let last = performance.now();
+  function frame(now) { step(Math.min((now - last) / 1000, 0.1)); last = now; draw(); requestAnimationFrame(frame); }
+  document.getElementById("fc-reset").onclick = reset;
+  reset(); requestAnimationFrame(frame);
+})();
+</script>
+:::
+
+The simulation above shows the same effect in miniature. Drag the link below the commit rate: the upper lane's queue
+grows without bound and the phone falls further behind every second; the lower lane never has more than two messages
+waiting, and the phone is at most a message behind.
+
+# Fold the Backlog {#merge lede="What a waiting hold keeps while the window is full, and why it never measures sizes."}
+
+While messages are in flight, each hold member keeps the ops of new commits in a **pending queue** and **folds** them:
+a new op merges into the last pending op on the same path when that is safe, so a backlog keeps the net change, not
+the history. When an acknowledgement frees a slot, the queue is encoded once into one message.
+
+| Last pending op | New op | Kept |
+| --- | --- | --- |
+| `a text "Hel"` | `a text "lo"` | one `a text "Hello"` |
+| `s count 41` or an append | `s count 42` | the `s`: it overwrites what came before |
+| anything | `r value` | only the `r`: a replacement makes everything before it moot |
+| anything on a path in the index | a structural op (`p`, `m`, `d`, `t`, `s` of an object) | appended; the index is cleared |
+
+The merge partner is found through a **leaf index**: a map from path to the last pending append or primitive set on
+that path. Leaf ops on different paths commute, so a new op may merge into an earlier one, not only into its
+neighbour; a status field changing between two tokens no longer stops the reply from folding. Any structural op
+clears the index, because after a splice `entries[7]` may name another entry. Past 10,000 pending ops the queue keeps
+only "replace with the current value", which then costs nothing while the consumer stays slow.
+
+**Why no size rule.** The first idea was to send a snapshot once the merged ops outgrow the member. The reviewers
+measured it on real p2 data and it failed three ways: "snapshot bytes plus sent op bytes" is no bound (an interned path
+lets a value grow faster than its ops: 5,404 B of snapshot after 832 B of ops), it drifts 1,254 times too high under
+churn, and an exact size needs a size on every node of the value. Folding alone came within about 10% of an exact
+oracle, with no measuring at all.
+
+| 60 s stall, all workloads | Uncompressed | Compressed |
+| --- | --- | --- |
+| merged ops, no folding | 466 KB | 166 KB |
+| adjacent folding | 399 KB | 147 KB |
+| leaf index (the decision) | 372 KB | 145 KB |
+| exact oracle (not buildable) | 335 KB | 136 KB |
+
+**One queue for every slow consumer.** The same queue serves Chord's shared watch handle: a listener still busy with
+the last frame gets the commits made meanwhile as one call with the newest value and the folded ops, instead of
+today's "after 100 frames, replace everything". With a listener taking one second, a conversation view's watch went
+from 402 calls and 17.9 MB of ops to 312 calls and 257 KB. Durable's event stream keeps a queue of its own, because
+events are not state: folding would drop them.
+
+:::raw
+<p>Animation of the fold: <a href="https://radius.earendil.com/artifact/01m5nc9s24e9kscppen2fxgwye">How folding works</a>.</p>
+:::
+
+# Calls Get Their Own Window {#calls lede="Why acknowledged state does not protect against a call flood."}
+
+Calls are small and the provider acknowledges nothing until they finish, so a byte or message window on state says
+nothing about how many handlers run. A tab with a bug:
+
+```ts
+for (const note of notes) ref.add(note, ctx);   // 100,000 calls, none awaited
+```
+
+| 100,000 calls, handlers awaiting 10 ms | Finished in | Provider memory | Another client's p95 round trip |
+| --- | --- | --- | --- |
+| no limit | 0.66 s | +56.5 MB, 43,824 running | 129 ms (345 ms with trivial handlers) |
+| provider-side semaphore of 64 | 15.9 s | +42.5 MB, 96,736 queued on the provider | 0.38 ms |
+| caller-side window of 64 | 17.1 s | **+4 MB, nothing queued on the provider** | 0.66 ms |
+| handlers doing 10 ms of CPU work | | | blocked about 1 s, with or without a limit |
+
+The provider's `hello` announces a call window **N** (256 by default) per origin (chapter VI). A consumer keeps at
+most N of its own calls unanswered per link; further calls wait in the link's call queue, in order. Nothing is refused (K16); a peer that sends
+more than N is a protocol error. The flood waits in the tab that caused it. CPU-heavy handlers block the event loop
+whatever the window: that stays the handler author's responsibility.
+
+# Relays {#relays lede="One link to a worker carries many tabs. Decided: flow control per origin."}
+
+The server relays every tab's holds to a session's worker over one link. Three ways to apply the acknowledged window
+across that hop were considered:
+
+:::flow wide animate | (a) End-to-end acknowledgements: the server acknowledges the worker only after the tab did.
+row "Worker" accent
+box w "worker" "K = 2 per link"
+row "Server" muted
+box s "server" "acks upstream after downstream"
+row "Tabs" blue
+box fast "fast tab" "desktop"
+box slow "slow tab" "phone in a tunnel" dashed
+arrow w -> s "state"
+arrow s -> fast "state"
+arrow s -> slow "state, slow"
+arrow slow -> s "ack (late)" dashed
+arrow s -> w "ack only when every tab acked" accent
+note "Simplest, but the slow phone holds the worker's one window, so the fast tab's updates arrive in coarser, later batches too."
+:::
+
+:::flow wide animate | (b) Acknowledgements per hop: the server acknowledges at once and resets a slow tab.
+row "Worker" accent
+box w2 "worker" "K = 2 per link"
+row "Server" muted
+box s2 "server" "acks at once; window per tab"
+row "Tabs" blue
+box fast2 "fast tab" "desktop"
+box slow2 "slow tab" "phone in a tunnel" dashed
+arrow w2 -> s2 "state"
+arrow s2 -> w2 "ack at once" accent
+arrow s2 -> fast2 "state, current"
+arrow s2 -> slow2 "window full: its parts dropped" dashed
+arrow s2 -> w2 "reset: fresh snapshots" accent
+note "The server cannot fold opaque parts, so it drops them and asks for snapshots. Built and measured in slice 4a: a 1 s stall cost three full snapshots (~1.5 MiB) and ~24 s to catch up under streaming."
+:::
+
+:::flow wide animate | (c) Flow control per origin (decided 2026-10-24): the worker keeps a window per tab; the relay only forwards.
+row "Worker" accent
+box w3 "worker" "K = 2 per (link, origin)"
+row "Server" muted
+box s3 "server" "forwards; FIFO of senders"
+row "Tabs" blue
+box fast3 "fast tab" "origin 1"
+box slow3 "slow tab" "origin 2, in a tunnel" dashed
+arrow w3 -> s3 "state @1, state @2"
+arrow s3 -> fast3 "state, current"
+arrow s3 -> slow3 "state, slow" dashed
+arrow slow3 -> s3 "ack (late)" dashed
+arrow s3 -> w3 "ack @2 when the tab acked" accent
+note "The relay numbers each tab (an origin) and forwards at once; each tab's ack goes back to the worker that sent the message. The worker folds the slow tab's commits in that origin's pending queues, exactly as for a direct tab; the fast tab is another origin with its own window."
+:::
+
+How (c) works:
+
+- **Origins.** The relay gives each downstream link a number, never reused; every message upstream carries it
+  (`origin`), and the worker keys holds, calls, windows and acks by (link, origin, id). Ids are not renumbered.
+- **What the relay keeps.** Per relayed hold its upstream link and its original `hold` message (to route calls and
+  hold again after a worker restart); per tab a FIFO of which worker sent each message in flight, so each in-order
+  `ack` goes back to the right worker. Nothing is parsed, folded, dropped or reset.
+- **Calls.** N is per origin at the worker; the relay forwards calls at once, each tab bounded by its own window.
+- **A tab leaves.** Its link closes; the relay sends `closed { origin }` to each worker it relayed to, which releases
+  that origin's holds and aborts its calls.
+- **Cost.** A tab served by W workers may have 2W messages in flight (plus the relay's own 2). Two bytes of origin per
+  message on the worker link.
+
+# What Changes in the Design {.epilogue lede="The converged scheme, what it replaces, and the relay decision."}
+
+**Converged** (Astra and Fable, after cross-checking each other's experiments): at most K = 2 acknowledged state
+messages in flight; pending ops folded per hold member through a leaf index, capped at 10,000; a call window N
+announced in `hello`, extra calls queued by the caller; holds unlimited; size limits stay a separate check.
+
+**Replaced** from the design (§3, §22): the byte window and its credit messages, snapshot admission and debt (R19, Q3),
+cut C12's call-credit accounting, any adapter backlog API. IPC and WebSocket behave the same, because acknowledgements
+are messages.
+
+**Relays (owner):** per-hop acknowledgements (b) were decided on 2026-10-23 and built in slice 4a; the benchmarks
+showed a slow tab recovering through resets far worse than a direct tab (24 s and three snapshots after a 1 s stall).
+On 2026-10-24 they were replaced by **flow control per origin** (c): the worker keeps window, pending queues and calls
+per (link, origin), the relay only forwards and returns acks. Measured after the rework: a slow tab through the relay
+catches up exactly like a direct one. The circuit breaker stayed undecided; the heartbeat (15 s ping, 30 s close)
+was built instead.
+
+# Measurements {.appendix}
+
+| Experiment | Setup | Result |
+| --- | --- | --- |
+| normal stream | 50 × 23 B/s through 64 KiB/s | no buffering, frames ≤ 2 ms old |
+| flood, no control | ~9,800 × 128 B/s, 10 s | 7.0 MB in `bufferedAmount`, heap +18.5 MB, newest state 9.4 s old |
+| flood, `bufferedAmount` ≤ 64 KiB + merging | same | heap +0.46 MB, newest state 9.4 s old |
+| flood, 1 to 4 acked messages + merging | same | heap +0.4 MB, newest state 0.0 s old, 98 % fewer messages |
+| client stops reading (loopback) | 20k × 90 B/s, 15 s | 23.4 MiB buffered, RSS +121 MB; merging above 1 MiB: flat |
+| IPC to a busy child | 623k sends | `send()` false from ~64 KB, parent +1,035 MB; the callback acknowledges the write, not the handler |
+| call flood | 100,000 calls, see chapter IV | caller-side window: +4 MB, other client p95 0.66 ms |
+| slow tab through a relay, (b) resets | 64 KiB/s, 100 tokens/s into a 500 KB view, 1 s stall | ~24 s to catch up, three full snapshots (~1.5 MiB) |
+| slow tab through a relay, (c) per origin | same, 1 s / 10 s / 60 s stall | caught up after 0.02 / 0.08 / 0.38 s, 485 B / 4.1 KiB / 23.7 KiB (same as direct) |

package/docs/next/flow-control/fold/index.html

@@ -0,0 +1,265 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>How folding works</title>
+<style>
+  :root {
+    --bg: #faf8f4; --ink: #222; --muted: #777; --line: #ddd6ca;
+    --a: #2f6fb3; --s: #b5562b; --p: #4f8a3c; --snap: #7a4fb0; --ack: #2a9d8f;
+  }
+  * { box-sizing: border-box; }
+  body { margin: 0; background: var(--bg); color: var(--ink); font: 16px/1.45 Georgia, "Times New Roman", serif; }
+  main { max-width: 760px; margin: 0 auto; padding: 20px 16px 60px; }
+  h1 { font-size: 26px; margin: 8px 0 4px; }
+  .lede { color: var(--muted); margin: 0 0 18px; }
+  h2 { font-size: 19px; margin: 28px 0 8px; }
+  p { margin: 8px 0; }
+  code { font: 13px/1.3 ui-monospace, Menlo, Consolas, monospace; background: #efe9de; padding: 1px 4px; border-radius: 3px; }
+  .stage { background: #fff; border: 1px solid var(--line); border-radius: 10px; padding: 12px; margin: 12px 0; }
+  .controls { display: flex; flex-wrap: wrap; gap: 6px; margin-bottom: 10px; }
+  button { font: 14px system-ui, sans-serif; border: 1px solid var(--line); background: #f4efe6; border-radius: 6px; padding: 6px 10px; cursor: pointer; }
+  button.on { background: var(--ink); color: #fff; border-color: var(--ink); }
+  .lanes { display: grid; grid-template-columns: 92px 1fr; gap: 8px 10px; align-items: center; font: 13px system-ui, sans-serif; }
+  .label { color: var(--muted); text-align: right; }
+  .lanes > div { min-width: 0; }
+  .lane { min-height: 44px; border: 1px dashed var(--line); border-radius: 8px; padding: 6px; display: flex; flex-wrap: wrap; gap: 5px; align-items: center; position: relative; }
+  .chip { font: 12px/1.2 ui-monospace, Menlo, Consolas, monospace; color: #fff; border-radius: 5px; padding: 4px 6px; white-space: nowrap; max-width: 100%; overflow: hidden; text-overflow: ellipsis;
+          transition: transform .35s ease, opacity .35s ease, background-color .3s; }
+  .chip.a { background: var(--a); } .chip.s { background: var(--s); } .chip.p { background: var(--p); } .chip.snap { background: var(--snap); }
+  .chip.enter { transform: translateY(-14px) scale(.8); opacity: 0; }
+  .chip.merge { transform: translateX(-26px) scale(.6); opacity: 0; }
+  .chip.flash { box-shadow: 0 0 0 3px #ffd36b; }
+  .msg { font: 12px ui-monospace, Menlo, Consolas, monospace; border: 1px solid #c9c0b0; background: #f7f3ec; border-radius: 6px; padding: 4px 6px; }
+  .msg.fly { animation: fly 1.2s ease-in forwards; }
+  @keyframes fly { to { transform: translateX(240px); opacity: 0; } }
+  .stats { display: flex; flex-wrap: wrap; gap: 14px; margin-top: 10px; font: 13px system-ui, sans-serif; color: var(--muted); }
+  .stats b { color: var(--ink); font-weight: 600; }
+  .note { font: 13px system-ui, sans-serif; color: var(--muted); margin-top: 8px; min-height: 2.6em; }
+  .tunnel { display: inline-block; padding: 1px 6px; border-radius: 4px; background: #333; color: #fff; font: 12px system-ui, sans-serif; }
+  .free { display: inline-block; padding: 1px 6px; border-radius: 4px; background: var(--ack); color: #fff; font: 12px system-ui, sans-serif; }
+  table { border-collapse: collapse; font: 14px system-ui, sans-serif; margin: 8px 0; width: 100%; }
+  td, th { border-bottom: 1px solid var(--line); padding: 5px 6px; text-align: left; vertical-align: top; }
+  th { color: var(--muted); font-weight: 600; }
+  .legend { display: flex; gap: 10px; flex-wrap: wrap; font: 12px system-ui, sans-serif; color: var(--muted); margin: 6px 0 2px; }
+  .legend span.chip { display: inline-block; }
+</style>
+</head>
+<body>
+<main>
+  <h1>How folding works</h1>
+  <p class="lede">What a hold does with commits while its link's window is full (two messages unacknowledged), and why folding needs no size measuring.</p>
+
+  <h2>The rule</h2>
+  <p>While the window is full, a hold keeps the ops of each new commit <b>raw</b> in a pending list. Before appending an op, it looks at the <b>last pending op only</b>:</p>
+  <table>
+    <tr><th>last pending</th><th>new op</th><th>result</th></tr>
+    <tr><td><code>a path "Hel"</code></td><td><code>a path "lo"</code></td><td>one <code>a path "Hello"</code> (text joined)</td></tr>
+    <tr><td><code>s path 41</code> or <code>a path …</code></td><td><code>s path 42</code></td><td>one <code>s path 42</code> (the set overwrites what came before)</td></tr>
+    <tr><td>anything on another path</td><td>anything</td><td>appended as it is</td></tr>
+  </table>
+  <p>Applied in order, the folded list gives the same value as the unfolded one: only neighbours on the same path merge, so no op in between can see the difference. Cost: one path comparison per op. When an ack frees a slot, the pending list is encoded <b>once</b> into one message.</p>
+  <div class="legend"><span class="chip a">a = append text</span><span class="chip s">s = set value</span><span class="chip p">p = insert into list</span><span class="chip snap">snapshot</span></div>
+
+  <div class="stage">
+    <div class="controls" id="scenarios">
+      <button data-s="stream" class="on">streamed reply</button>
+      <button data-s="counter">counter, 100k sets</button>
+      <button data-s="interleaved">reply + status, interleaved</button>
+      <button data-s="list">new list items</button>
+    </div>
+    <div class="controls">
+      <button id="play">play</button>
+      <button id="step">one commit</button>
+      <button id="ack">ack arrives</button>
+      <button id="reset">reset</button>
+    </div>
+    <div class="lanes">
+      <div class="label">link</div><div><span id="linkState" class="tunnel">window full: 2 unacked (tunnel)</span></div>
+      <div class="label">commits</div><div class="lane" id="incoming"></div>
+      <div class="label">pending (raw)</div><div class="lane" id="pending"></div>
+      <div class="label">sent</div><div class="lane" id="sent"></div>
+    </div>
+    <div class="stats">
+      <span>commits <b id="commits">0</b></span>
+      <span>pending ops <b id="pendingOps">0</b></span>
+      <span>merged or dropped <b id="folded">0</b></span>
+      <span>encodes <b id="encodes">0</b></span>
+    </div>
+    <div class="note" id="note"></div>
+  </div>
+
+  <h2>What the four cases show</h2>
+  <table>
+    <tr><th>case</th><th>pending after the stall</th><th>why</th></tr>
+    <tr><td>streamed reply</td><td>1 op</td><td>every token appends to the same path</td></tr>
+    <tr><td>counter, 100,000 sets</td><td>1 op</td><td>each set overwrites the previous one</td></tr>
+    <tr><td>reply + status, interleaved</td><td>grows</td><td>the neighbour is always on the other path: adjacent-only folding cannot merge</td></tr>
+    <tr><td>new list items</td><td>grows</td><td>inserts carry new data: nothing to fold, this is the real change</td></tr>
+  </table>
+  <p>The last two cases are why a memory bound is still needed. It can be a plain count of pending ops after folding (say 1,000): past it the hold drops its list and marks “send the current value”, which then costs nothing more while the stall lasts.</p>
+
+  <h2>Why not time since the last ack?</h2>
+  <p>A time trigger (“no ack for T seconds: drop the list, send a snapshot later”) punishes the most common case: a phone in a tunnel while a reply streams into a long conversation. Folded, the 60 s stall costs one append of about 12 KB; a snapshot of the conversation costs its whole size (Astra's corpus: 4.6 KB of updates against 168 KB, recovery 0.2 s against 2.7 s). And before T, a fast producer on many paths still piles up rate × T ops: time bounds duration, not memory. With folding, the counter case (100,000 sets) is one op whatever the time, so time adds nothing there.</p>
+</main>
+
+<script>
+const scenarios = {
+  stream: {
+    note: "Every token is an append to the same path: each new chip melts into the one before it.",
+    make: (i) => ({ verb: "a", path: "entries[7].text", value: ["The", " stall", " is", " over", " and", " the", " phone", " gets", " one", " append", "."][i % 11] }),
+  },
+  counter: {
+    note: "100,000 sets of one field: each set overwrites the previous one, so the list never holds more than one op.",
+    make: (i) => ({ verb: "s", path: "count", value: String(41 + i) }),
+  },
+  interleaved: {
+    note: "Tokens and a status field alternate: the last pending op is always on the other path, so adjacent-only folding cannot merge anything.",
+    make: (i) => i % 2 === 0
+      ? { verb: "a", path: "entries[7].text", value: [" one", " two", " three", " four", " five", " six"][(i / 2) % 6] }
+      : { verb: "s", path: "status", value: i % 4 === 1 ? '"typing"' : '"tool"' },
+  },
+  list: {
+    note: "Each commit inserts a new item: that is new data, nothing to fold. A count bound turns a long list into “send the current value”.",
+    make: (i) => ({ verb: "p", path: "sessions", value: `+{id:${100 + i}}` }),
+  },
+};
+
+const $ = (id) => document.getElementById(id);
+let scenario = "stream", pending = [], commits = 0, folded = 0, encodes = 0, timer = undefined, windowFull = true;
+const CAP = 12; // shown small; the proposal is about 1,000
+
+function label(op) {
+  const text = op.value.length > 22 ? `…${op.value.slice(-22)}` : op.value;
+  return op.verb === "a" ? `a ${op.path} "${text}"` : `${op.verb} ${op.path} ${op.value}`;
+}
+
+function chip(op, cls = "") {
+  const el = document.createElement("span");
+  el.className = `chip ${op.verb} ${cls}`;
+  el.textContent = op.verb === "snap" ? "snapshot needed" : label(op);
+  return el;
+}
+
+function render() {
+  $("commits").textContent = commits;
+  $("pendingOps").textContent = pending.filter((op) => op.verb !== "snap").length;
+  $("folded").textContent = folded;
+  $("encodes").textContent = encodes;
+  $("linkState").className = windowFull ? "tunnel" : "free";
+  $("linkState").textContent = windowFull ? "window full: 2 unacked (tunnel)" : "window open";
+}
+
+function step() {
+  const op = scenarios[scenario].make(commits);
+  commits++;
+  const incoming = $("incoming");
+  const shown = chip(op, "enter");
+  incoming.replaceChildren(shown);
+  requestAnimationFrame(() => shown.classList.remove("enter"));
+  if (!windowFull) {
+    encodes++;
+    send([op]);
+    render();
+    return;
+  }
+  setTimeout(() => enqueue(op), 380);
+}
+
+function enqueue(op) {
+  const lane = $("pending");
+  const last = pending.at(-1);
+  if (last?.verb === "snap") {
+    folded++;
+    render();
+    return;
+  }
+  if (last && last.path === op.path && ((last.verb === "a" && op.verb === "a") || ((last.verb === "a" || last.verb === "s") && op.verb === "s"))) {
+    const next = op.verb === "a" ? { ...last, value: last.value + op.value } : op;
+    pending[pending.length - 1] = next;
+    folded++;
+    const ghost = chip(op, "flash");
+    lane.appendChild(ghost);
+    requestAnimationFrame(() => ghost.classList.add("merge"));
+    setTimeout(() => {
+      ghost.remove();
+      const target = lane.lastElementChild;
+      if (target) {
+        target.textContent = label(next);
+        target.className = `chip ${next.verb} flash`;
+        setTimeout(() => target.classList.remove("flash"), 300);
+      }
+    }, 350);
+  } else if (pending.length >= CAP) {
+    folded += pending.length;
+    pending = [{ verb: "snap", path: "", value: "" }];
+    lane.replaceChildren(chip(pending[0], "flash"));
+    $("note").textContent = `Past the bound (${CAP} here, about 1,000 in the proposal): the list is dropped and the hold only remembers “send the current value”. Later commits cost nothing until the window opens.`;
+  } else {
+    pending.push(op);
+    const el = chip(op, "enter");
+    lane.appendChild(el);
+    requestAnimationFrame(() => el.classList.remove("enter"));
+  }
+  render();
+}
+
+function send(ops) {
+  const sentLane = $("sent");
+  const msg = document.createElement("span");
+  msg.className = "msg";
+  msg.textContent = ops[0]?.verb === "snap" ? "1 message: snapshot of the current value" : `1 message: ${ops.length} op${ops.length === 1 ? "" : "s"}`;
+  sentLane.replaceChildren(msg);
+  requestAnimationFrame(() => msg.classList.add("fly"));
+}
+
+function ack() {
+  stop();
+  if (pending.length > 0) {
+    encodes++;
+    send(pending);
+    $("note").textContent = `The ack frees a slot: the pending list is encoded once, as one message (${commits} commits, ${pending[0].verb === "snap" ? "one snapshot" : pending.length + " op(s)"}).`;
+  } else {
+    $("note").textContent = "The ack frees a slot; nothing was pending.";
+  }
+  pending = [];
+  $("pending").replaceChildren();
+  windowFull = false;
+  render();
+  setTimeout(() => { windowFull = true; render(); }, 1600);
+}
+
+function stop() {
+  clearInterval(timer);
+  timer = undefined;
+  $("play").textContent = "play";
+}
+
+function reset() {
+  stop();
+  pending = []; commits = 0; folded = 0; encodes = 0; windowFull = true;
+  for (const id of ["incoming", "pending", "sent"]) $(id).replaceChildren();
+  $("note").textContent = scenarios[scenario].note;
+  render();
+}
+
+$("play").onclick = () => {
+  if (timer) return stop();
+  $("play").textContent = "pause";
+  timer = setInterval(step, 700);
+};
+$("step").onclick = () => { stop(); step(); };
+$("ack").onclick = ack;
+$("reset").onclick = reset;
+for (const button of document.querySelectorAll("#scenarios button")) {
+  button.onclick = () => {
+    for (const other of document.querySelectorAll("#scenarios button")) other.classList.toggle("on", other === button);
+    scenario = button.dataset.s;
+    reset();
+  };
+}
+reset();
+</script>
+</body>
+</html>