Append reuse: skip unchanged traces in encode and on the wire (protocol v6)

[Alek99]

Stacked on #178 (base: fix/append-single-send). Part of #163 — implements the append-path half of per-column reuse.

What

An append tick previously re-emitted every trace and shipped every byte. Now it costs O(affected trace), not O(figure), in both CPU and wire bytes:

• Emit cache (encode skip). Unchanged traces splice their cached spec fragment and encoded chunks — no gathers, no f64→f32 re-encode, no density re-bin. The cache keys on an emit key: trace data_rev (new, bumped per append), px, drill state, and the axis ranges only for range-dependent tiers — so a neighbor's growing axis correctly busts M4/density traces while direct traces keep hitting (verified per emitter). The splice is positional; any column-table drift (e.g. the affected trace crossing the density threshold) busts the whole build back to a fresh full emission — correctness never rides the cache.
• Wire reuse (cid). Split columns now carry a deterministic content identity (t<trace>.<emit-key digest>.<ordinal>). A cid in the client baseline (reset by every full split build) ships as addressing only — no buffer. The client resolves cid-only entries from the payload it last applied via payloadResolve, then normalizes the table back to buf: i, so _columnView, GL context restore, and the animation path see one uniform per-column array, unchanged.
• Recovery. A client that can't resolve a cid (missed push, mounted mid-stream) never applies a torn table: it sends one refresh request (new request kind, §2) answered with a complete append-shaped payload.
• Widget transport. The per-tick push is a small custom message again; the synced traits become debounced notebook-reopen state — always a complete payload, re-synced at most once per second with a trailing sync via the running event loop (inline when headless). The v5 trait-listener and its torn-pair machinery are removed: traits no longer carry pushes, so the hazard class is gone rather than defended.

Protocol bumps to v6 — a pre-v6 bundle would fail loudly on a cid-only column; the first-paint handshake catches cached bundles instead.

Measured

Same bench as #178 (median per tick, data-level wire accounting):

Case	vs #178	Wire KiB/tick	Kernel ms/tick
10×50k dashboard, 1 trace appended	3912 → 397 (−90%)	397	0.52 → 0.27
direct scatter 100k, 1 trace	unchanged	783	0.19
decimated line 2M, 1 trace	unchanged	15	0.52

The single-trace rows are the affected trace itself re-shipping — that's the O(K) delta-frames follow-up, not this PR.

Spec

wire-protocol.md: §2 refresh row + description, §4 rewritten (partial buffers, emit cache, per-host delivery, reopen-state debounce), §5 cid field, §7 v6 note; rust-engine.md §5 updated. CHANGELOG under Unreleased → Changed.

Verification

• Full suite: 2198 passed (5 new tests: buffer omission, emit-cache object-identity hit, baseline reset survival, tier-flip bust correctness, range-growth busting range-dependent neighbors only; plus refresh contract).
• Browser probe (built ESM bundle, real kernel payloads, two-trace figure): partial append A ships 2/4 buffers and applies by resolving cid-only columns from the first paint; append B applies from A's reseeded cache; a wiped cache triggers exactly one refresh without applying a torn table; the refresh reply repairs and re-arms. All green.
• ruff / ruff format / pre-commit / ty (25 diagnostics — pre-existing baseline, none new) / node js/build.mjs.

🤖 Generated with Claude Code

[codspeed-hq]

Merging this PR will not alter performance

✅ 97 untouched benchmarks
⏩ 1 skipped benchmark¹

---

_{Comparing feat/append-skip-unchanged (fdd7ffc) with fix/append-single-send (6fb41fd)}

Footnotes

1. 1 benchmark was skipped, so the baseline result was used instead. If it was deleted from the codebase, click here and archive it to remove it from the performance reports. ↩

[greptile-apps]

Greptile Summary

This PR makes streaming appends reuse unchanged trace data across encoding and transport. The main changes are:

• Adds per-trace emit caching for unchanged traces.
• Adds content IDs for reusing client-side column buffers.
• Adds refresh recovery when cached column data is unavailable.
• Moves widget append pushes to custom messages with debounced reopen state.
• Bumps the wire protocol to version 6.

Confidence Score: 5/5

This looks safe to merge.

The updated resolver now routes undersized split buffers through refresh recovery.

No distinct blocking issue remains in the reviewed fix path.

T-Rex Logs

What T-Rex did

• Baseline video was reviewed and confirms the initial chart at first paint with four cached column buffers.
• A subsequent review traces the sequence of partial appends, deliberate cache loss, a single refresh, and the re-armed final partial append.
• Browser traces were examined and show HTTP 200 responses for the repository ESM bundle and the generated payload fixture, with payload counts per phase and the flags untorn:true, refreshRequests:1, renderedIntact:true, and final passed:true.
• Payload-generation traces were reviewed to identify the Python/kernel APIs used and to confirm all wire-buffer/cid-only counts.

_{Ran code and verified through T-Rex}

Important Files Changed

Filename	Overview
js/src/00_header.ts	Adds protocol-v6 split-payload resolution and validates declared column extents before applying an append.
js/src/54_kernel.ts	Resolves reused columns, requests a full refresh on cache misses, and reseeds the client baseline after successful updates.
js/src/50_chartview.ts	Tracks content IDs for column spans in the currently applied payload.
python/xy/_payload.py	Adds deterministic column identities, per-trace emission caching, positional cache invalidation, and partial buffer delivery.
python/xy/widget.py	Uses custom messages for live append pushes and keeps complete synced state on a debounce.

_{Reviews (3): Last reviewed commit: "Pin the range-free emitter list and the ..." | Re-trigger Greptile}

[FarhanAliRaza]

Reviewed the full diff and verified the claims empirically on this branch — the headline number reproduces: 10×50k dashboard streaming one trace, measured against the merge-base with fix/append-single-send (same venv, same native core, only PYTHONPATH differs): 3,911 KiB → 396 KiB per tick (−89.9%, 9.9×), kernel 3.64 → 0.75 ms. Targeted suites (test_streaming / test_widget / test_figure, 177 tests) pass. The architecture is sound: the positional-splice guard fails toward full rebuilds, the v5 torn-trait hazard is deleted rather than defended, and payloadResolve validates before mutating. Findings below were each verified with runtime probes, not just read off the diff.

Asks before merge (both small)

1. Pin the range-free emitter list with a test. _trace_emit_key omits axis ranges for kinds asserted range-free, so the emit cache serves cached bytes across range changes for them. I probed every listed kind (direct scatter, direct line, area, hexbin, histogram, heatmap, segments, bar): all currently emit byte-identical chunks under disjoint range pairs — the list is correct today. But nothing enforces it: if any of these emitters later gains range dependence (a windowed gather, a view-clipped optimization), appends silently splice stale geometry — exactly the silent-decision class §28 exists to prevent. A parametrized test that emits each range-free kind under two disjoint range pairs and asserts byte-identical chunks (~40 lines) makes the list unable to rot. Unknown kinds already default to range-dependent, which is the safe direction.

2. One sentence in wire-protocol.md §5: cid cross-build stability is a requirement, not an accident. Verified: two consecutive full builds derive identical cids for unchanged data — which is the only reason baseline resets (reopen sync, new subscriber, refresh) don't break reuse, and the only reason a client mounted from ≤1 s-stale reopen state can resolve the next push's cid-only entries. Today that stability falls out of the digest construction; if anyone ever salts the digest or adds a build-dependent input, multi-client streams degrade to refresh storms with no test failing. Worth stating explicitly in the spec.

Follow-ups (non-blocking, all confirmed by probe)

• Reopen sync clears the emit cache every interval. _sync_reopen_state → build_payload_split() → _append_emit_cache = {}, so at 60 ticks/s every ~60th append re-emits all traces (wire reuse survives via stable cids; the CPU win doesn't). The reset's px-mismatch rationale doesn't apply to the widget reopen path — preserving the cache when the resolved px matches would remove a periodic latency spike on exactly the hot path this PR optimizes.
• Appends without a running event loop silently lose the debounce. Probe: 5 appends with no loop → 5 inline full trait syncs (with a loop: 0 immediate, trailing timer armed — correct). A user streaming from a worker thread pays the full v5 trait-sync cost per tick without knowing, and loop.call_later from a non-loop thread would be unsafe if a loop were reachable. Deserves at least a docstring note; call_soon_threadsafe scheduling if threaded producers are meant to be supported.
• The JS resolve path has no automated coverage. No test anywhere references payloadResolve / _requestRefresh / _reseedCidSpans; the browser probe is manual. Python-side coverage is well chosen (buffer omission, object-identity cache hit, baseline-reset survival, tier-flip bust, range-growth busting range-dependent neighbors only). An automated headless test for resolve-miss → exactly-one-refresh → repair would protect the trickiest client logic — and the O(K) delta follow-up leans on this same machinery, so it pays for itself across the stack.