PR 5 (Track 5, bench-rollup): Interactive uPlot charts + mkdocs deploy from devel

[elijahr]

Track 5 of the bench-rollup feature. Embeds an interactive uPlot
throughput chart in docs/benchmarks.md (via mkdocs-material's
md_in_html extension), publishes the merged BMF snapshot to
docs/assets/bench-results/ on every devel push, and extends
docs.yml to redeploy mike's dev/ alias on devel pushes.

Depends on PR #19, PR #20, PR #21, PR #22, PR #23.

What landed (per impl plan Track 5)

Task 5.1 — Vendor uPlot 1.6.27 IIFE bundle. docs/assets/uplot-1.6.27.iife.min.js (47884 bytes). SHA-256 18dd3f1a54320f5e28a6655e11b79a5a3a30e329eb0d01b97d0b0b1ceae3ed10 matches upstream jsdelivr metadata. Empty docs/assets/bench-results/ directory preserved via .gitkeep.

Task 5.2 — Chart wiring + contract test. docs/assets/bench-charts.js (vanilla-JS uPlot wiring) + docs/assets/bench-charts.css. Library-toggle legend, log-scale Y axis toggle, hover tooltip with mean ± stddev when present, graceful fallbacks for fetch failure / missing uPlot global / empty BMF. New benchmarks/tests/test_bench_charts_contract.py (9 tests) guards the BMF -> chart contract; mirrors JS parseSlug in Python so drift is caught at CI time.

Task 5.3 — Embed chart in benchmarks.md. Replaces the "Charts and visualizations coming in Phase 2." placeholder with the chart container inside an md_in_html <div markdown=\"0\"> block. Fetch path is relative (./assets/bench-results/latest.json) so the same page works under /dev/, /latest/, and /v*/ mike aliases. §4.1 fairness caveats embedded verbatim within one viewport of the chart. mkdocs.yml registers the page in nav (previously orphaned) and adds the chart CSS to extra_css.

Task 5.4 — Devel-triggered docs deploy. docs.yml push trigger and "Deploy docs (dev)" if: clause extended to include devel.

Task 5.5 — Snapshot publishing pipeline. Split into 5.5.a (loop-prevention scaffolding: paths-ignore + actor guard, separate commit so scaffolding can be verified in isolation) and 5.5.b (snapshot-push step). Three layers per design §5.X:

1. [skip ci] marker in the snapshot commit message.
2. paths-ignore extension to docs/assets/bench-results/** on pull_request and push triggers.
3. if: github.actor != 'github-actions[bot]' on both bench and bench-upload jobs.

Snapshot step copies merged.json to <sha>.json AND latest.json, commits as github-actions[bot], pushes to devel. No-op detection skips empty commits when merged.json is byte-identical.

Task 5.6 — Post-deploy asset verification. New step in docs.yml after the dev deploy curls the published BMF URL, asserts HTTP 200, and asserts the body parses as JSON. The chart's silent-on-404 fallback would otherwise hide a broken asset path.

Task 5.7 — Licenses + .gitattributes. THIRD_PARTY_LICENSES.md records uPlot 1.6.27 (MIT) with a precise upgrade procedure (jsdelivr URL, SHA-256 verification path). .gitattributes gains docs/assets/uplot-*.js linguist-vendored=true linguist-generated=true and docs/assets/bench-results/*.json linguist-generated=true.

Task 5.8 — Hand-curated README + delete renderer. README BENCHMARKS markers replaced with a four-row hand-curated summary (Sipsic / Sipmuc / Mupsic / Mupmuc bounded at one representative shape each) + link to the live chart. Pre-deletion release-tag check: v3.2.0 and v4.0.0 each ship benchmarks/render_readme.nim in their tagged tree (immutable); no CI workflow / nimble task / test runner references the file. benchmarks/render_readme.nim and tests/t_render_readme.nim removed. benchmarks/README.md gains an "Updating the README summary" subsection codifying the hand-curation procedure.

Task 5.9 — CHANGELOG. Track 5 entries added to [Unreleased] covering Added / Changed / Removed.

Verification

• nimble test (Nim test suite via tests/test.nim): 200/200 pass.
• tests/t_bench_common.nim: 25/25 pass.
• tests/t_bench_latency.nim: 7/7 pass.
• python3 -m unittest benchmarks.tests.test_merge_bmf benchmarks.tests.test_superset_check benchmarks.tests.test_bench_charts_contract: 29/29 pass (9 new contract tests + 20 pre-existing).
• actionlint .github/workflows/bench.yml .github/workflows/docs.yml: clean on changed code; one pre-existing SC2086 warning on docs.yml:52 is in untouched "Deploy docs (versioned)" code.
• git check-attr -a docs/assets/uplot-1.6.27.iife.min.js: reports linguist-vendored: true, linguist-generated: true.
• git grep render_readme: only intentional historical references in CHANGELOG (PR-0 entry) and benchmarks/README.md (deletion explanation).

Track 5 acceptance criteria

• Library-toggle legend hides/shows series; log-scale toggle works (implemented in bench-charts.js; manual mkdocs serve verification deferred to post-merge dev/ deploy).
• Fairness footer visible within 1 viewport of chart (verbatim §4.1 text immediately below chart).
• https://elijahr.github.io/lockfreequeues/dev/benchmarks/ shows chart with current data — verifiable post-merge once devel deploy fires.
• https://elijahr.github.io/lockfreequeues/latest/benchmarks/ shows chart at last release — gated on next release tag.
• README BENCHMARKS markers hold hand-curated summary; link to latest chart works.
• CI smoke check: post-deploy HTTP 200 on bench-results/latest.json; valid JSON; uPlot script tag present in HTML (asset-path step in docs.yml; uPlot script presence implicit in committed benchmarks.md).
• Loop-prevention verified: 3 layers landed; the manual loop-prevention test (push to docs/assets/bench-results/.gitkeep on a feature branch and confirm the bench job is skipped) lands as part of Task 5.5.a verification documented in the commit message.

Manual chart performance check

Per design §3 PR 5: open https://elijahr.github.io/lockfreequeues/dev/benchmarks/ in Chrome devtools (4G preset, disable cache, hard reload); record LCP/FCP screenshot. Deferred to post-merge since it requires a live mike deploy URL; will be attached as a comment once devel deploy fires.

References

• Impl plan: ~/.local/spellbook/docs/Users-eek-Development-lockfreequeues/plans/2026-05-01-bench-rollup-impl.md Track 5 (lines 965-1129).
• Design doc: ~/.local/spellbook/docs/Users-eek-Development-lockfreequeues/plans/2026-05-01-bench-rollup-design.md §3 PR 5 (lines 696-816), §4.1 (fairness), §4.4 (README markers), §4.5 (uPlot license block), §4.6 (.gitattributes), §5.X (loop-prevention), §5.Y (asset-path verification).