docs(benchmarks-website): refresh planning docs after UI + perf merges

claude · claude · commit ab5592f9983d · 2026-05-01T01:36:51.000Z
Brings AGENTS.md and README.md in line with what's actually on ct/benchmarks-v3 after the four UI workstreams (tooltip-pr-link, range-scrollbar, global-filters, full-history) and the perf pass (CompressionLayer, LANDING_INLINE_N) landed. AGENTS.md: - Bullet 1: note the tower-http CompressionLayer. - Bullet 7: rewrite. No more 1000-commit cap; fetch is `?n=all`, visual downsampling is client-side LTTB on the visible range, range-scrollbar drives rebuilds in lockstep with the toolbar. - Bullet 8: groups are all collapsed by default; first group's payloads are inlined at LANDING_INLINE_N=100 commits with lazy-fetch on zoom-out. - Bullet 9: the URL params are `?n=&engine=&format=` (not `?y=&mode=&hidden=`); per-chart toolbar state is local-only. - Code map: fix LANDING_INLINE_N name/value; refresh chart-init.js description (LTTB rebuild, range strip, filter chips, click-to-PR); add rows for app.rs and migrate/src/verify.rs; note the new range-strip/filter-chip CSS selectors. - Things to avoid: nuance the "don't refetch on scope change" rule (the inline-payload zoom-out path is a one-time exception); add the predecessor-walk lesson from PR #7723 review (commits[] is oldest-first by SQL); add the "no server-side commit cap" rule; clarify that the global filter bar is a visibility driver, not a forbidden page-level toolbar. README.md: - Status: list the recent merges (LTTB UI, compression, inline trim). - Item 1 (secrets): mark done. - Item 2 (CI wiring): note the f7fd270 dual-write commit; flag end-to-end verification as the still-open subtask. - Item 3 (test deployment): bump the host DNS to the current EC2 box; mention the c6a.4xlarge build-on-box path. - Item 4 (smoke test): mark in-progress; record the Random Access recovery so future agents see the regression class to watch for. - Deferred UI follow-ups: drop client-side LTTB (now done); refresh the collect_group_charts N+1 line range (1131-1162 → 1202-1233); expand the mobile legend item with the actual cause (matchMedia is read once at construction). Signed-off-by: Claude <noreply@anthropic.com>
diff --git a/benchmarks-website/planning/AGENTS.md b/benchmarks-website/planning/AGENTS.md
@@ -24,6 +24,7 @@ it as `vortex-bench-server` at `benchmarks-website/server/`.
 
 - Single Rust binary: `axum` (HTTP) + `maud` (SSR HTML) + embedded `duckdb-rs`. All static assets
   (`chart.umd.js`, `chart-init.js`, `style.css`) are `include_bytes!`'d into the binary. No CDN.
+  A `tower-http` `CompressionLayer` wraps every response (gzip/brotli).
 - One DuckDB file on local disk holds five fact tables (compression time, query measurement, vector
   search, RAG, random access) plus a `commits` dim table. Schema in
   [`01-schema.md`](./01-schema.md).
@@ -37,13 +38,23 @@ it as `vortex-bench-server` at `benchmarks-website/server/`.
 - Charts render inline on the landing page. Each `<canvas>` is paired with a
   `<script id="chart-data-N">` JSON payload that `chart-init.js` hydrates lazily via
   `IntersectionObserver`.
-- Per-chart toolbar with zoom-as-scope: each chart fetches up to 1000 commits once, then the Show /
-  Y / Mode buttons and slider adjust the visible range via `chart.update("none")`. Mouse wheel pans
-  history. Slider uses `input` events with a 16ms throttle + 150ms debounce.
+- Per-chart toolbar with zoom-as-scope. Each chart fetches its full raw history once
+  (`?n=all`); visual downsampling is **client-side LTTB** in `chart-init.js`
+  (`MAX_VISIBLE_POINTS = 500`, applied only to the currently visible commit range — zoomed-in
+  views render raw). Drag-pan, drag-rectangle-zoom, wheel-pan, the toolbar slider, and a
+  horizontal range-scrollbar strip below each chart all drive the same `rebuildVisibleAndUpdate`
+  so LTTB and the strip stay in lockstep. A "downsampled · K / N" badge surfaces when LTTB is
+  active.
 - Group ordering is hard-coded to match v2's `origin/ct/vfvb:benchmarks-website/index.html` order.
-  Each group is wrapped in a `<details>`; only the first is open by default.
-- URL state (`?n=&y=&mode=&hidden=`) is honored only on permalink pages (`/chart`, `/group`).
-  Landing page resets to defaults on open; users customize per-chart in place.
+  Every group is wrapped in a `<details>`, all collapsed by default. The first group's chart
+  payloads are still inlined (capped at `LANDING_INLINE_N = 100` commits) so opening it skips a
+  fetch round-trip; `chart-init.js` lazy-fetches `?n=all` once when the user zooms past the
+  inlined window.
+- A sticky filter bar at the top of every page exposes engine/format chips that drive series
+  visibility across every chart at once. Clicking a data point opens that commit's PR (parsed
+  from `(#NNNN)` in the message; falls back to the commit URL). URL params `?engine=&format=&n=`
+  survive permalink shares and refreshes; per-chart toolbar state (Y axis, slider) is
+  intentionally local-only.
 - `vortex-bench-migrate` reads v2 records, runs each through a classifier in
   `migrate/src/classifier.rs`, and either routes the record into one of the five fact tables or
   marks it `Skip(reason)` with a typed reason. The run **fails if more than 5% of records come back
@@ -54,13 +65,15 @@ it as `vortex-bench-server` at `benchmarks-website/server/`.
 | Path                                             | What lives here                                                                                                                                                                                                            |
 | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `benchmarks-website/server/src/main.rs`          | Binary entrypoint. Reads `INGEST_BEARER_TOKEN`, `VORTEX_BENCH_BIND` (default `127.0.0.1:3000`), `VORTEX_BENCH_DB` (default `./bench.duckdb`), `VORTEX_BENCH_LOG`.                                                          |
+| `benchmarks-website/server/src/app.rs`           | `AppState` (DB handle + bearer + path) and the `Router` composition. `CompressionLayer` wraps every response.                                                                                                              |
 | `benchmarks-website/server/src/api.rs`           | `chart_payload(conn, &ChartKey, &CommitWindow)` — the shared implementation behind `/api/chart/{slug}`, the inline `<script>` JSON, and `collect_group_charts`. Known N+1 in `collect_group_charts` — flagged with a TODO. |
-| `benchmarks-website/server/src/html.rs`          | Three HTML routes and the `<details>`-per-group landing page. `LANDING_DEFAULT_N: u32 = 50`. `UiQuery` parses `?n=&y=&mode=&hidden=` on permalink routes.                                                                  |
+| `benchmarks-website/server/src/html.rs`          | Three HTML routes and the `<details>`-per-group landing page. `LANDING_INLINE_N: u32 = 100` caps the first group's inlined chart JSON; HTML routes default to `CommitWindow::All`. `UiQuery` parses `?n=&engine=&format=`. |
 | `benchmarks-website/server/src/slug.rs`          | `ChartKey` / `GroupKey` enums and `to_slug` / `from_slug` round-trip.                                                                                                                                                      |
-| `benchmarks-website/server/static/chart-init.js` | Hydration, `IntersectionObserver`, custom external tooltip with delta rows, inline `afterDatasetsDraw` plugin for the dashed crosshair.                                                                                    |
-| `benchmarks-website/server/static/style.css`     | `.chart-tooltip-host` is `position: absolute; pointer-events: none;` (do not change — fixes the flicker). `.chart-card` is `position: relative`.                                                                           |
+| `benchmarks-website/server/static/chart-init.js` | Hydration, `IntersectionObserver`, lazy-fetch on `<details>` toggle, `rebuildVisibleAndUpdate` (client-side LTTB on the visible range, `MAX_VISIBLE_POINTS = 500`), custom external tooltip + delta rows + click-to-PR, range-scrollbar strip, global filter chips, inline crosshair plugin. |
+| `benchmarks-website/server/static/style.css`     | `.chart-tooltip-host` is `position: absolute; pointer-events: none;` (do not change — fixes the flicker). `.chart-card` is `position: relative`. `.chart-range-strip*` and `.filter-*` selectors back the range scrollbar and global filter chips. |
 | `benchmarks-website/server/tests/web_ui.rs`      | `insta` snapshot tests, seeded by POSTing to `/api/ingest`. No external fixtures.                                                                                                                                          |
 | `benchmarks-website/migrate/src/classifier.rs`   | `classify_outcome` routes records into a fact table, `Skip(reason)`, or `Unknown`. >5% Unknown gates the run.                                                                                                              |
+| `benchmarks-website/migrate/src/verify.rs`       | Structural diff between a migrated DuckDB and v2's live `/api/metadata`. Exits non-zero if any v2 group is missing in v3 — gates a CI step.                                                                                |
 
 ## Local dev / smoke test
 
@@ -111,13 +124,25 @@ See the root [`CLAUDE.md`](/CLAUDE.md) for Rust style, test layout, and CI norms
   [`README.md`](./README.md) first — it is almost certainly already deferred.
 - **Don't write a server-side classifier for live ingest.** The emitter is responsible for v3-shape
   records. The migrator's classifier exists only to translate v2 records once.
-- **Don't rebuild a global page-level toolbar.** Controls are per-chart. This was a real failure
-  mode the first time around — the page-level toolbar drove every chart together, which is not what
-  users want.
+- **Don't rebuild a global page-level toolbar with chart-state controls.** Per-chart controls
+  (slider, Y-axis, scope) stay per-chart. The sticky filter bar at the top of every page is the
+  exception — it drives series *visibility* across every chart at once, which is what users want
+  for the engine/format dimension. Don't extend it with per-chart settings.
 - **Don't bind a slider's reactive logic to `change` events.** Use `input` events with a small
   throttle + debounce, otherwise the slider only updates on release and feels broken.
-- **Don't refetch on scope change.** Each chart fetches a generous window once; scope buttons +
-  slider operate on that buffer via `chart.update("none")`.
+- **Don't refetch every time the scope changes.** The chart fetches its full history once; scope
+  buttons, slider, drag-pan, wheel-pan, and the range strip all rebuild via the in-memory LTTB
+  pass on the cached payload. The one exception is the inline-payload zoom-out path: when the user
+  zooms past the first group's inlined `LANDING_INLINE_N` window for the first time,
+  `chart-init.js` lazy-fetches `?n=all` once and replaces the payload.
+- **Don't re-introduce a server-side commit cap.** `?n=all` is the default for HTML routes and the
+  upper bound is unbounded everywhere. Visual downsampling lives client-side in `chart-init.js`,
+  not on the wire.
+- **Don't reverse the predecessor walk in the tooltip.** The chart payload's `commits[]` is sorted
+  oldest-first by SQL — `commits[0]` is the oldest commit, `commits[N-1]` is the newest. For
+  per-row delta the chronological predecessor of `commits[idx]` lives at `idx - 1`. We caught a
+  regression where a "fix" flipped this to `idx + 1`; the original walk-backward direction was
+  right.
 - **Don't re-introduce `pointer-events: auto` on the tooltip host.** The tooltip is positioned at
   the cursor; making it pointer-interactive causes a flicker loop. Keep it `pointer-events: none`
   and offset via `transform: translate(12px, 12px)`.
diff --git a/benchmarks-website/planning/README.md b/benchmarks-website/planning/README.md
@@ -10,9 +10,11 @@ the v2 Node/React stack.
 
 ## Status
 
-- **Alpha shipped** to `ct/benchmarks-v3`. Server, migrator, and inline-charts UI are merged.
-- **In production-readiness phase.** v2 is still serving `bench.vortex.dev`. v3 has not been
-  deployed publicly yet.
+- **Alpha shipped** to `ct/benchmarks-v3`. Server, migrator, full-history UI (client-side LTTB,
+  range scrollbar, global filter chips, click-to-PR tooltip), response compression, and the
+  `LANDING_INLINE_N` cold-load trim are all merged.
+- **In production-readiness phase.** v2 is still serving `bench.vortex.dev`. v3 runs on a
+  throwaway EC2 host for smoke-testing; not deployed publicly yet.
 - **UI follow-ups** are owned by the user, not by agents (see "Deferred UI follow-ups" below).
 
 A 10-bullet architecture summary lives at the top of [`AGENTS.md`](./AGENTS.md). Use that for
@@ -22,34 +24,33 @@ handoffs and external sharing.
 
 In rough order. Each item is a separate task; do not bundle.
 
-### 1. Repo secrets
+### 1. Repo secrets — done
 
-Two GitHub repository secrets on `vortex-data/vortex` (admins only):
+`INGEST_BEARER_TOKEN` and `V3_INGEST_URL` are set as repo-level secrets on `vortex-data/vortex`.
+They're fine at this scope for the test phase. Move to an Environment-scoped secret (gated to
+`ct/benchmarks-v3` / protected branches) before prod. Rotate `INGEST_BEARER_TOKEN` if the test
+value was ever shared in a comment / Slack / PR review.
 
-- `INGEST_BEARER_TOKEN` — random 32+ byte token. Same value gets set as the `INGEST_BEARER_TOKEN`
-  env var on whatever host runs the v3 server. Generate with `openssl rand -hex 32`.
-- `V3_INGEST_URL` — full URL of the v3 ingest endpoint, e.g. `http://<host>:3000/api/ingest` for
-  the test box, or `https://bench.vortex.dev/api/ingest` for prod.
+### 2. CI ingestion wiring — partial
 
-Repo-level secrets are fine for the test phase. Move to an Environment-scoped secret (gated to
-`ct/benchmarks-v3` / protected branches) before prod.
-
-### 2. CI ingestion wiring
-
-Confirm whichever workflow runs the benchmark suites and pushes results uses
-`secrets.INGEST_BEARER_TOKEN` and `secrets.V3_INGEST_URL`, and POSTs the versioned envelope shape
-defined in [`02-contracts.md`](./02-contracts.md). The current workflow targets the v2 endpoint;
-needs to either dual-write or flip.
+The dual-write step is wired into `bench.yml` and `sql-benchmarks.yml` via commit `f7fd270`. Still
+to do: an end-to-end run that triggers the workflow on a feature branch, POSTs to the EC2 box, and
+confirms the envelope lands in DuckDB intact. Outbox-style retry on failed POSTs is a follow-up;
+not built until we observe a failure.
 
 ### 3. Test deployment
 
 Currently a manual EC2 box for smoke-testing. Latest test host:
 
-- DNS: `ec2-18-116-241-0.us-east-2.compute.amazonaws.com`
+- DNS: `ec2-18-219-54-101.us-east-2.compute.amazonaws.com` (changes on stop/start unless an Elastic
+  IP is associated)
 - Port: `3000` (open to `0.0.0.0/0` in the security group)
 - Bind: `VORTEX_BENCH_BIND=0.0.0.0:3000` (default `127.0.0.1` does not work for external access)
-- HTTP only, no TLS. Public IP changes on stop/start unless an Elastic IP is associated. Throwaway
-  token only — don't reuse for prod.
+- HTTP only, no TLS. Throwaway bearer token only — don't reuse for prod.
+
+Build path: build narrow on the box itself (it's a `c6a.4xlarge` to avoid local-vs-EC2 arch
+mismatches). The v2 migration source is fetched directly from the public S3 bucket; no AWS creds
+needed.
 
 Smoke test from a laptop:
 
@@ -59,10 +60,12 @@ curl -i http://<host>:3000/
 
 Should return HTTP 200 with the landing HTML.
 
-### 4. Smoke test with migrated data
+### 4. Smoke test with migrated data — in progress
 
-Run `vortex-bench-migrate` against the v2 source, copy the resulting `bench.duckdb` to the deployed
-host, point `VORTEX_BENCH_DB` at it, and walk every group's charts in a browser.
+Run `vortex-bench-migrate` against the v2 source, point `VORTEX_BENCH_DB` at the result, walk every
+group's charts in a browser. Done so far: Random Access (caught and fixed a missing-chart
+regression — see `1228e530`); LTTB downsampling, range scrollbar, filter chips, and click-to-PR
+all behave on real data. Still to walk: every other group at least once.
 
 ### 5. Operational hygiene (not yet done)
 
@@ -123,10 +126,10 @@ These are user/owner decisions, not agent decisions.
   display-name map. Cosmetic but visible.
 - **Deferred UI follow-ups.** The user is handling these directly; agents should not pre-empt
   them:
-  - `collect_group_charts` N+1 refactor in `api.rs:1131-1162`.
-  - Mobile legend resize handler.
+  - `collect_group_charts` N+1 refactor in `api.rs:1202-1233`.
+  - Mobile legend resize handler. The position is picked once at chart construction via
+    `matchMedia("(max-width: 768px)")`; it doesn't update if the viewport crosses the breakpoint.
   - Zoom-sync within a group.
-  - LTTB downsampling for very long histories.
   - Swap the inline crosshair plugin for `chartjs-plugin-crosshair`.
 
 ## Reading order (alpha-era reference)
