feat(bench/dashboard): capacity headline, honest outcomes, group-scoped fairness

bench/dashboard/src/lib/compare.ts

@@ -11,7 +11,7 @@ export const compareCategoryOptions = [
 
 export const compareMetricOptions = [
 	{ value: 'rps.avg', label: 'RPS (median across trials)' },
-	{ value: 'rps.peak', label: 'RPS (peak bucket)' },
+	{ value: 'rps.peak', label: 'RPS (busiest second)' },
 	{ value: 'latency.avg', label: 'Latency (mean)' },
 	{ value: 'latency.p50', label: 'Latency (p50)' },
 	{ value: 'latency.p90', label: 'Latency (p90)' },
@@ -67,8 +67,19 @@ const CROSS_TRIAL_MEDIAN = 'median across trials (summary aggregate)';
  */
 export const compareCategoryColumns: Record<CompareCategory, CompareCategoryColumn[]> = {
 	rps: [
-		{ key: 'avg', label: 'median', hint: `requests/second, ${CROSS_TRIAL_MEDIAN}` },
-		{ key: 'peak', label: 'peak', hint: 'highest single sample bucket across trials' },
+		{
+			key: 'avg',
+			label: 'median',
+			hint: `requests/second at the paced suite's fixed offered load, ${CROSS_TRIAL_MEDIAN}. Not a capacity figure — see "peak throughput" on the ranking for that.`,
+		},
+		// Named "busiest second" rather than "peak" everywhere it appears. "Peak throughput" is now
+		// the saturation suite's capacity figure, and this is a momentary rate inside a fixed-load
+		// run — the two must not share a word.
+		{
+			key: 'peak',
+			label: 'busiest second',
+			hint: 'highest single sample bucket across trials, within the paced run',
+		},
 	],
 	latency: [
 		{ key: 'avg', label: 'mean', hint: `mean latency per trial, ${CROSS_TRIAL_MEDIAN}` },

bench/dashboard/src/lib/components/CapacityFigure.svelte

@@ -0,0 +1,88 @@
+<script lang="ts">
+	import Hint from './Hint.svelte';
+	import { cn } from '#lib/utils.js';
+	import type { CapacityView } from '#lib/saturation';
+
+	/**
+	 * The only component on this site that draws a peak-throughput number.
+	 *
+	 * That is the whole point of it existing. The number and the objective it was measured against
+	 * are one value in `CapacityView` and one component here, so there is no call site that can
+	 * print "12.5k" on its own — and a reader can never mistake a capacity figure for the paced
+	 * "throughput at fixed load" number sitting next to it, because a capacity figure always arrives
+	 * with "at p99 < 50 ms" attached.
+	 *
+	 * The three states that carry no number carry words instead, in the same slot, at the same size:
+	 * "knee not reached", "never met the p99 target", "not measured". Nothing is left blank and
+	 * nothing is filled in from elsewhere.
+	 */
+	let {
+		capacity,
+		/** `lead` is the headline treatment on a detail page; `inline` fits a table cell. */
+		size = 'inline',
+		align = 'left',
+		active = false,
+	}: {
+		capacity: CapacityView;
+		size?: 'lead' | 'inline';
+		align?: 'left' | 'right';
+		/**
+		 * True when this is the column the table is currently sorted by, which lifts the number to
+		 * full-strength ink. An explicit prop rather than the caller reaching in with a descendant
+		 * selector: the emphasis rule has to survive this component changing its own type classes,
+		 * and a `[&_.text-lead]` from outside would silently stop matching the day it did.
+		 */
+		active?: boolean;
+	} = $props();
+
+	const figure = $derived(capacity.figure);
+	const right = $derived(align === 'right');
+</script>
+
+<span class={cn('block', right && 'text-right')}>
+	{#if figure}
+		<span
+			class={cn(
+				'block font-mono tabular-nums',
+				size === 'lead' ? 'text-metric font-medium' : 'text-lead font-medium',
+				// A lower bound is deliberately not given the full-strength ink a measurement gets. It is
+				// a floor, and it should not read as the same kind of fact as the row above it — so the
+				// active-column emphasis lifts a measurement and deliberately leaves a bound where it is.
+				figure.lowerBound
+					? 'text-foreground-secondary'
+					: active || size === 'lead'
+						? 'text-foreground'
+						: 'text-foreground-secondary',
+			)}
+		>
+			<!--
+				The words carry the lower bound, not a glyph. `figure.text` already reads "at least 48.9k";
+				prefixing a "≥" on top of that says the same thing twice, and a reader who meets the
+				symbol first has to work out which of the two is the qualifier. The visual marking is
+				carried instead by the muted ink here, the italic line below, and the open-ended bar in
+				the table — none of which duplicate the sentence.
+			-->
+			{figure.text}
+		</span>
+		<span
+			class={cn(
+				'text-meta text-muted-foreground mt-1 block',
+				size === 'lead' && 'text-body',
+				figure.lowerBound && 'italic',
+			)}
+		>
+			<Hint hint={capacity.detail}>{figure.qualifier}</Hint>
+			<span class="text-foreground-faint" aria-hidden="true">·</span>
+			{capacity.note}
+		</span>
+	{:else}
+		<span
+			class={cn(
+				'text-muted-foreground block',
+				size === 'lead' ? 'text-lead font-medium' : 'text-body',
+			)}
+		>
+			<Hint hint={capacity.detail}>{capacity.note}</Hint>
+		</span>
+	{/if}
+</span>

bench/dashboard/src/lib/components/HarnessStrip.svelte

@@ -0,0 +1,82 @@
+<script lang="ts">
+	import Hint from './Hint.svelte';
+	import { cn } from '#lib/utils.js';
+	import type { HarnessRow } from '#lib/harness';
+
+	/**
+	 * What each database's rows ran under, above the one global table.
+	 *
+	 * This exists so that the table can stay a single list. Sectioning by family would make the
+	 * harness legible by construction — one heading, one config — but it also buries the rows a
+	 * reader came for and hides the cross-database comparison that is the point of the page. So the
+	 * harness moves out of the layout and onto its own strip: same three facts, stated once per
+	 * database, above the rows they govern.
+	 *
+	 * The two readings it has to support are opposite ones. Two rows on the *same* database share
+	 * every line here, so their gap is the libraries. Two rows on *different* databases share none
+	 * of it, so their gap includes the stacks. A family that declared nothing says so in the same
+	 * slot, because "we did not record it" is a third answer and not a quiet version of the first.
+	 */
+	let { rows }: { rows: HarnessRow[] } = $props();
+
+	const anyUnverified = $derived(rows.some((row) => row.identical === false));
+	const anyUndeclared = $derived(rows.some((row) => row.summary === null));
+</script>
+
+{#if rows.length > 0}
+	<section class="mt-6" aria-labelledby="harness-strip-label">
+		<h2 id="harness-strip-label" class="text-micro text-muted-foreground font-mono uppercase">
+			harness by comparison group
+		</h2>
+		<ul class="mt-2 flex flex-wrap gap-2">
+			{#each rows as row (row.family)}
+				<li
+					title={row.detail}
+					class={cn(
+						'border-border flex items-baseline gap-x-2.5 border px-3 py-1.5',
+						// A family whose targets did not all share a harness is the one case where this
+						// strip is reporting a problem rather than a fact, so it is the one case that
+						// borrows the negative rule.
+						row.identical === false && 'border-l-negative border-l-[3px]',
+					)}
+				>
+					<span class="text-meta text-foreground-secondary">{row.label}</span>
+					{#if row.summary}
+						<span class="text-meta text-foreground font-mono">{row.summary}</span>
+						{#if row.identical === false}
+							<span class="text-meta text-negative">not identical within family</span>
+						{:else if row.exempt.length > 0}
+							<!-- "Verified identical" alongside an exemption is a narrower claim than the tick
+							     reads as, so the exemption travels with it rather than living only in the
+							     manifest. -->
+							<span class="text-meta text-warning-foreground">{row.exempt.length} exempt</span>
+						{/if}
+					{:else}
+						<span class="text-meta text-muted-foreground italic">harness not declared</span>
+					{/if}
+				</li>
+			{/each}
+		</ul>
+
+		<p class="text-meta text-muted-foreground mt-2">
+			<Hint
+				hint="A comparison group is the set of targets claiming to be directly comparable. Inside one the harness is enforced identical, so a difference between two of its rows is a difference between the libraries. Across groups the harness deliberately differs — each stack runs in the shape it is actually deployed in — so a difference between rows in different groups includes the stack, not just the library. A group is usually a database, and splits where the harness genuinely cannot be equalised: a single-threaded runtime cannot be given the same connection pool as a threaded one without the number becoming fiction."
+			>
+				rows in one group share this configuration; rows in different groups do not
+			</Hint>
+		</p>
+
+		{#if anyUnverified}
+			<p class="text-meta text-negative mt-1.5">
+				At least one group's targets did not all declare the same harness, so a comparison between
+				those rows is not a like-for-like library comparison.
+			</p>
+		{/if}
+		{#if anyUndeclared}
+			<p class="text-meta text-muted-foreground mt-1.5">
+				Groups marked "harness not declared" come from runs published before the runner recorded it;
+				nothing here confirms their rows ran under identical conditions.
+			</p>
+		{/if}
+	</section>
+{/if}