docs(evalboard): trim the comments added by this branch

Comment-only. Cuts the narration of what the code used to do and the
restatements of what it now does, keeping the reasons that aren't
recoverable from reading it: why the per-run cache is keyed per run
rather than per source, why the ad-hoc load key and the sort key differ,
why hover moved to a marker class, and why the model vote normalizes.

Net 57 lines. No behavior change.

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

Author: bai-uipath

evalboard/app/_components/harness-selector.tsx

@@ -42,14 +42,13 @@ export function HarnessSelector({
         const qs = p.toString();
         router.replace(qs ? `${pathname}?${qs}` : pathname, { scroll: false });
     };
-    // Every known harness always gets a segment, whether or not it turned up in
-    // the discovery window. A weekly harness (delegate) drops out of that window
-    // between firings, and a control that quietly loses an option reads as "this
-    // harness was removed" rather than "it hasn't run lately". Scoping to one
-    // with no runs in the window shows an empty result, which is honest and one
-    // click from recoverable; a missing segment is neither. `current` is unioned
-    // in too, so a deep-linked `?h=` outside the known set still reads as
-    // selected. orderHarnesses fixes the order, so segments never reshuffle.
+    // Every known harness gets a segment whether or not it turned up in the
+    // discovery window. A weekly harness (delegate) drops out of that window
+    // between firings, and a control that quietly loses an option reads as
+    // "removed" rather than "hasn't run lately"; an empty result is honest and
+    // one click from recoverable. `current` is unioned in so a deep-linked `?h=`
+    // outside the known set still reads as selected, and orderHarnesses fixes
+    // the order so segments never reshuffle.
     const opts = orderHarnesses([
         ...KNOWN_HARNESSES,
         ...harnesses,

evalboard/app/api/download/route.ts

@@ -14,11 +14,9 @@ export const dynamic = "force-dynamic";
 // blobs first, so this mirrors what the page would load.
 //
 // `task` is REQUIRED. Omitting it used to mean "zip the whole run", which for a
-// nightly meant ~10k blobs / ~400 MB: an uncapped fan-out of blob downloads, a
-// stat-per-file walk over Azure Files, and the entire archive buffered in
-// memory before any of it was sent. That path is gone, along with the run
-// page's button for it — a task folder is a handful of files and returns in
-// well under a second. To inspect a whole run, use the blob container directly.
+// nightly meant ~10k blobs / ~400 MB fetched uncapped and buffered in memory
+// before any of it was sent. That path and its button are gone; to inspect a
+// whole run, use the blob container.
 export async function GET(req: Request) {
     const url = new URL(req.url);
     const runId = url.searchParams.get("run");

evalboard/app/api/refresh/__tests__/route.test.ts

@@ -128,10 +128,8 @@ describe("POST /api/refresh", () => {
             await expect(fs.access(runDir)).rejects.toThrow();
         });
 
-        // Evicting only the on-disk copy is not enough: the front page reads a
-        // memoized projection of run.json that a settled run holds for a day
-        // (lib/overview.ts::perRunRevalidate), so without this the refresh
-        // button is a no-op for anything older than 24h.
+        // Without this the button is a no-op for a settled run, whose
+        // projection is held for a day (lib/overview.ts::perRunRevalidate).
         test("valid run -> the memoized projection is invalidated too", async () => {
             const POST = await loadPost();
             await POST(post("2026-06-01_04-04-22"));

evalboard/app/api/refresh/route.ts

@@ -40,9 +40,8 @@ export async function POST(req: Request) {
         return NextResponse.json({ error: "invalid run" }, { status: 400 });
     }
     // Evicting the on-disk copy is only half the job: the front page reads a
-    // memoized PROJECTION of it (lib/overview.ts::cachedLoadPerRunFor), and a
-    // settled run's projection is held for a day. Drop that entry too, or the
-    // refresh silently does nothing for every run older than 24h.
+    // memoized projection of it (lib/overview.ts::cachedLoadPerRunFor), held for
+    // a day on a settled run. Without this the refresh would no-op for those.
     revalidateTag(runCacheTag(source.id, runId));
     // Re-download is lazy on next render. The run page is force-dynamic and
     // reads the sidecars straight from disk, so it is fresh immediately.

evalboard/app/globals.css

@@ -42,11 +42,9 @@ details[open] > summary .group-chevron {
 }
 
 /* Filter/tag chips (app/runs/[id]/chips.tsx). The composed utility string was
-   ~130 chars and rendered ~11k times on a nightly run page (and ~6k on
-   /trends): 1.4 MB of identical class text in one response, from 120 distinct
-   values across 56k attributes. The utilities live here now so the emitted
-   attribute is four short tokens. The component still decides WHICH tokens to
-   emit; the variant/state matrix is carried by compound selectors below. */
+   ~130 chars and rendered ~11k times on a nightly run page: 1.4 MB of identical
+   class text in one response. Emitting four short tokens instead moves it here,
+   where the browser parses it once and caches it across navigations. */
 @layer components {
     .chip {
         @apply rounded border transition-colors;
@@ -57,8 +55,8 @@ details[open] > summary .group-chevron {
     .chip-md {
         @apply text-xs px-2 py-0.5;
     }
-    /* Idle. Exactly one of idle/selected is ever emitted, so these never
-       collide and neither needs to out-specify the other. */
+    /* Idle. Exactly one of idle/selected is ever emitted, so neither needs to
+       out-specify the other. */
     .chip-skill {
         @apply bg-indigo-50 text-indigo-700 border-indigo-200 font-medium;
     }
@@ -69,8 +67,7 @@ details[open] > summary .group-chevron {
         @apply bg-gray-50 text-gray-500 border-gray-200;
     }
     /* Hover rides on .chip-act, which only the interactive (button) branch
-       emits — a non-clickable span must not show an affordance it can't
-       honor. Replaces the old runtime hover-utility strip. */
+       emits, so a non-clickable span shows no affordance it can't honor. */
     .chip-act.chip-skill:hover {
         @apply bg-indigo-100;
     }
@@ -96,17 +93,16 @@ details[open] > summary .group-chevron {
         @apply bg-studio-blue text-white border-studio-blue;
     }
 
-    /* Per-row stat key in the grid's stacked card layout — 5.2k renders on a
-       nightly run page at 49 chars each. */
+    /* Per-row stat key in the grid's stacked card layout; 5.2k renders. */
     .stat-k {
         @apply text-[10px] uppercase tracking-wide text-gray-400;
     }
-    /* Numeric table cell on /trends — 5.4k renders at 47 chars each. */
+    /* Numeric table cell on /trends; 5.4k renders. */
     .num-cell {
         @apply py-2 px-3 tabular-nums text-right text-gray-700;
     }
-    /* One bar of a /trends sparkline — 9.9k renders. The status color stays a
-       utility on the element; only the geometry is shared. */
+    /* One bar of a /trends sparkline; 9.9k renders. The status color stays a
+       utility on the element, so only the geometry is shared. */
     .spark-bar {
         @apply w-[6px] h-full rounded-sm;
     }

evalboard/app/runs/[id]/chips.tsx

@@ -9,11 +9,9 @@ export type ChipVariant = "skill" | "review" | "tag";
 export type ChipSize = "sm" | "md";
 
 // The colour/size utilities behind these tokens live in app/globals.css under
-// `@layer components`. A chip renders ~11k times on a nightly run page, so the
-// composed utility string (~130 chars each) was the single largest contributor
-// to that page's HTML — 1.4 MB of identical class text. Emitting short tokens
-// instead moves that text into the stylesheet, where the browser parses it once
-// and caches it across navigations.
+// `@layer components`. A chip renders ~11k times on a nightly run page, and the
+// composed utility string (~130 chars each) was 1.4 MB of identical class text
+// in one response; short tokens move it into the cached stylesheet.
 const STYLES: Record<
     ChipVariant,
     {
@@ -76,9 +74,8 @@ export function ChipButton({
     const s = STYLES[variant];
     const activeCls =
         variant === "tag" && size === "md" ? TAG_MD_ACTIVE : s.active;
-    // `chip-act` arms the hover rules, and only the interactive branch gets it —
-    // otherwise the non-interactive <span> shows a hover affordance it can't
-    // honor. (This replaces stripping `hover:` utilities out of the string.)
+    // `chip-act` arms the hover rules, and only the interactive branch gets it:
+    // a non-clickable <span> must not show an affordance it can't honor.
     const idleCls = onClick ? `${s.idle} chip-act` : s.idle;
     const stateCls = active ? activeCls : idleCls;
     const baseCls = `chip ${SIZE_CLS[size]} ${stateCls}`;

evalboard/app/runs/[id]/run-view.tsx

@@ -296,14 +296,10 @@ export function RunView({
 
     // Commit a filter change to the URL WITHOUT a server round-trip.
     //
-    // Every reader of `tags` / `rtags` / `q` on this page is client-side — the
-    // grid is filtered by `filtered` below, out of rows the server already
-    // sent. The page's server component reads only `src`. So `router.replace`
-    // bought nothing and cost a full re-render of a force-dynamic route: two
-    // separate parses of the same multi-MB run.json (readRunSummary and
-    // readRunTasks each read it), the activation sub-run, the review index, and
-    // the mature-source scan's serial walk back through earlier runs — all to
-    // return markup this component recomputes locally anyway.
+    // Every reader of `tags` / `rtags` / `q` on this page is client-side (see
+    // `filtered` below); the server component reads only `src`. So
+    // `router.replace` bought nothing and cost a full re-render of a
+    // force-dynamic route to return markup this component recomputes anyway.
     //
     // The native History API keeps the URL shareable and the back button
     // working; Next syncs `useSearchParams` off pushState/replaceState, so this

evalboard/lib/blob.ts

@@ -297,11 +297,9 @@ export async function ensureRunReviewIndex(
     });
 }
 
-// NOTE: there is deliberately no whole-run fetch. `ensureRunDir` used to exist
-// for the run page's download-as-zip button and pulled EVERY blob under the run
-// prefix with no concurrency cap — ~10k blobs / ~400 MB for a nightly, issued as
-// one unbounded Promise.all. Both it and the button are gone; per-task download
-// (below) is the supported shape.
+// There is deliberately no whole-run fetch. `ensureRunDir` used to pull EVERY
+// blob under the run prefix with no concurrency cap (~10k blobs / ~400 MB for a
+// nightly). Per-task download, below, is the supported shape.
 
 // Narrow fetch: run.json + just one task subdir. Used by the per-task
 // detail page so opening a deep link to a 50-task run doesn't pull every

evalboard/lib/overview.ts

@@ -325,14 +325,13 @@ async function loadPerRunForId(
 }
 
 // First `YYYY-MM-DD` (optionally `_HH-MM-SS`) anywhere in a run id. Ad-hoc ids
-// are not date-SHAPED — `parseRunIdDate` anchors, so it rejects them — but
-// almost all of them still CARRY their date: `adhoc-2026-09-02_21-59-13`,
-// `2026-05-28_skills-full-codex-gpt54`, `haiku45-skills-suite-2026-05-28`.
+// aren't date-SHAPED (parseRunIdDate anchors, so it rejects them) but almost all
+// still carry their date: `adhoc-2026-09-02_21-59-13`, `skills-2026-05-28`.
 const ADHOC_DATE_RE = /(\d{4})-(\d{2})-(\d{2})(?:_(\d{2})-(\d{2})-(\d{2}))?/;
 
-// Cheap, id-only start date for an ad-hoc run; null when the id carries no date.
-// A date-only id resolves to the start of its day, which is right for "which
-// runs are newest" and can only lose a same-day tie-break. Exported for testing.
+// Id-only start date for an ad-hoc run; null when the id carries no date. A
+// date-only id resolves to the start of its day, which can only lose a same-day
+// tie-break.
 export function adhocRunDate(id: string): Date | null {
     const m = ADHOC_DATE_RE.exec(id);
     if (!m) return null;
@@ -362,43 +361,33 @@ export function adhocRunDate(id: string): Date | null {
 // `YYYY-MM-DD_HH-MM-SS`, so a source-blind key would let a Scribe run and a
 // skills run with the same id serve each other's projection.
 //
-// Per-RUN rather than one loader per source, because `unstable_cache` fixes its
-// revalidate and tags at construction: a shared loader can only hold one TTL
-// for every run, and cannot carry a per-run tag for the refresh button to
-// invalidate. Both of those matter — see `perRunRevalidate` below.
+// Per-run rather than per-source because `unstable_cache` fixes revalidate and
+// tags at construction: one shared loader can hold neither a per-run TTL nor a
+// per-run tag for the refresh button to evict.
 type PerRunLoader = (id: string) => Promise<PerRun>;
 
-// Keyed `<source>:<run>`. Bounded by the run count of every container the
-// process has served, so it grows with history rather than with traffic.
+// Keyed `<source>:<run>`; grows with history, not with traffic.
 const perRunLoaders = new Map<string, () => Promise<PerRun>>();
 
-// A run's run.json is written once, at the end of the run (the upload is the
-// last thing the runner does), so a run that finished yesterday is immutable.
-// Its SIDECARS are not — meta.json (title/description), reviews and analysis can
-// be edited in blob afterwards — which is what `runCacheTag` is for.
+// A run.json is written once, at the end of the run, so a finished run is
+// immutable. Its sidecars (meta.json, reviews, analysis) are not, which is what
+// `runCacheTag` is for.
 const SETTLED_AFTER_MS = 24 * 60 * 60 * 1000;
-// A run whose id says it is still recent. Re-read often, because it may be
-// today's nightly landing while the page is open.
+// Recent enough that today's nightly may still be landing.
 const FRESH_REVALIDATE_SECONDS = 300;
-// Everything older. The read this avoids is a multi-MB run.json off an Azure
-// Files mount, and its content cannot change on its own.
+// Older than that: the read this avoids is a multi-MB run.json off Azure Files.
 const SETTLED_REVALIDATE_SECONDS = 24 * 60 * 60;
 
-// Cache tag for one run's projection, so POST /api/refresh can evict it. Without
-// this, a settled run edited in blob would keep serving a stale projection to
-// the front page for a day.
+// Cache tag for one run's projection, so POST /api/refresh can evict it;
+// without it the button would no-op for anything past SETTLED_AFTER_MS.
 export function runCacheTag(sourceId: string, runId: string): string {
     return `evalboard-run:${sourceId}:${runId}`;
 }
 
-// Settled runs are cached for a day, everything else for 5 minutes. An id that
-// carries no date at all is treated as fresh: those are hand-uploaded ad-hoc
-// runs, re-uploaded far more often than pipeline runs, and there are a handful.
-//
-// Evaluated once per run per process, when the loader is first built, so a run
-// that settles while the process is up keeps the 5-minute TTL until the next
-// restart. That is the safe direction (it is today's behavior) and not worth a
-// timer to correct.
+// Settled runs cache for a day, everything else for 5 minutes. An id carrying no
+// date at all is treated as fresh: those are hand-uploaded and re-uploaded far
+// more often than pipeline runs. Evaluated once per run per process, so a run
+// that settles while the process is up keeps the short TTL until restart.
 function perRunRevalidate(id: string): number {
     const started = parseRunIdDate(id) ?? adhocRunDate(id);
     if (started == null) return FRESH_REVALIDATE_SECONDS;
@@ -1234,28 +1223,19 @@ export function buildAdhocRows(
     };
 }
 
-// Extra candidates loaded beyond `limit`, to cover ids that turn out to have no
-// readable overview (aborted uploads, and the `deploys/` prefix, which is not a
-// run at all) and so get dropped from the rows.
+// Extra candidates loaded beyond `limit`, covering ids with no readable overview
+// (aborted uploads, the `deploys/` prefix) that then drop out of the rows.
 const ADHOC_LOAD_SLACK = 10;
 
 // The Ad-hoc runs section (front page, below the daily listing). "Ad-hoc" here
 // means "not a daily-pipeline run" — i.e. the id isn't date-shaped, which is
 // exactly the set listRunIdsInWindow excludes from the chart and main table.
 //
 // Only the newest `limit + ADHOC_LOAD_SLACK` candidates are loaded, ordered by
-// the date in the id. This section used to load EVERY ad-hoc candidate before
-// sorting, on the premise that the set was "small by construction (manual
-// uploads only)". That premise expired: nothing expires the ad-hoc prefixes in
-// the `runs` container (unlike `runs-gha`'s 14-day rule), so the set had grown
-// to 165 runs / ~294 MB of run.json read on every cold front-page render, to
-// show ten rows.
-//
-// The authoritative sort key stays run.json's `start_time` — the id key only
-// decides what to LOAD, and the two can only disagree for a run whose id date
-// contradicts its own start_time. Ids carrying no date at all are always loaded
-// (there are a handful, e.g. `sdk-live-r2-final`), so they can never be ordered
-// out of the section by a key they don't have.
+// the date in the id; loading all 165 to show ten rows cost ~294 MB per cold
+// render. run.json's `start_time` stays the authoritative sort, so the id only
+// decides what to READ. Ids with no date are always loaded, so they can never be
+// ordered out by a key they don't have.
 export async function getAdhocRunListing(
     limit: number | null,
     source: Source = DEFAULT_SOURCE,
@@ -1271,8 +1251,7 @@ export async function getAdhocRunListing(
         else dated.push({ id, at: at.getTime() });
     }
     dated.sort((a, b) => b.at - a.at);
-    // null limit = "load everything", which the page never asks for but the
-    // signature allows; a finite limit takes the newest slice plus slack.
+    // null limit = "load everything": allowed by the signature, never used.
     const budget = limit == null ? dated.length : limit + ADHOC_LOAD_SLACK;
     const loadedAll = budget >= dated.length;
     const toLoad = [...undated, ...dated.slice(0, budget).map((d) => d.id)];
@@ -1282,9 +1261,7 @@ export async function getAdhocRunListing(
         cachedLoadPerRunFor(source),
     );
     const listing = buildAdhocRows(perRun, limit);
-    // `total` drives the "Show more" affordance, so while the load is truncated
-    // it has to report the candidate count rather than what we happened to read
-    // — otherwise the section caps itself at the first page. Once everything is
-    // loaded it reverts to the exact readable-row count.
+    // `total` drives "Show more", so a truncated load must report the candidate
+    // count or the section caps itself at the first page.
     return loadedAll ? listing : { ...listing, total: ids.length };
 }

evalboard/lib/pricing.ts

@@ -128,9 +128,8 @@ const _ROUTING_PREFIXES = [
     "openrouter/",
 ];
 const _REGION_PREFIXES = ["eu.", "us.", "apac.", "global."];
-// Exported so the run header's model tally can group on the same key pricing
-// looks up on. Without it a single row that recorded the qualified id counts
-// as a second model and the header claims a mixed-model run.
+// Exported so the run header's model tally groups on the same key pricing looks
+// up on (lib/runs.ts::tallyModels).
 export function normalizeModel(model: string): string {
     let m = model.trim();
     for (const pre of _ROUTING_PREFIXES) {