@danypops/jittor 0.5.1 → 0.7.0

package/extension/src/usage.ts

@@ -1,28 +1,65 @@
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
-import { USAGE_CHART_HEIGHT, USAGE_TOKEN_QUERY_LIMIT, USAGE_Y_AXIS_WIDTH } from "../../src/constants.ts";
-import type { StoredMetricObservation } from "../../src/domain/metric.ts";
+import { HUMAN_TEXT_FIELD_MAX_CHARACTERS, USAGE_CHART_HEIGHT, USAGE_MAX_DISTINCT_SCOPES, USAGE_RENDER_MAX_SERIES, USAGE_Y_AXIS_WIDTH } from "../../src/constants.ts";
 import {
+	buildCostGraph,
 	buildUsageGraph,
+	resolveUsageWindow,
 	USAGE_PERIODS,
 	usagePeriod,
-	usagePeriodStart,
-	type UsageBucket,
+	type CostGraph,
+	type UsageAggregateRow,
 	type UsageGraph,
 	type UsagePeriod,
 } from "../../src/domain/usage.ts";
 import type { UsageBudgetControl } from "./settings.ts";
 import type { JittorPanelClient } from "./tui.ts";
 
-type UsageAction = "period-prev" | "period-next" | "refresh" | "close";
-type UsageColor = "accent" | "success" | "warning" | "error" | "thinkingText" | "muted" | "dim" | "borderMuted";
+type UsageAction = "period-prev" | "period-next" | "view-next" | "refresh" | "close";
+type UsageColor =
+	| "accent" | "success" | "warning" | "error" | "thinkingText" | "muted" | "dim" | "borderMuted"
+	| "syntaxKeyword" | "syntaxFunction" | "syntaxVariable" | "syntaxString" | "syntaxNumber" | "syntaxType" | "syntaxOperator";
 
 export interface UsageTheme {
 	fg(color: UsageColor, text: string): string;
 	bold(text: string): string;
 }
 
-const SERIES_COLORS: UsageColor[] = ["accent", "success", "warning", "thinkingText", "error"];
+/**
+ * Categorical palette for per-provider/model series. Deliberately excludes "success"/"warning"/
+ * "error": those already carry a fixed status meaning elsewhere in this same panel (the budget
+ * threshold line, freshness state), so reusing them for arbitrary model identity would make a
+ * model's bar segment look like a warning or a failure to a pre-attentive reader — a real
+ * categorical-color-design pitfall (see e.g. ColorBrewer/Okabe-Ito guidance on qualitative
+ * palettes: colors for nominal categories should not imply an order, magnitude, or judgment).
+ *
+ * Instead this reuses the syntax-highlighting color roles, because theme authors already tune
+ * those specifically to be simultaneously distinguishable on screen — that is the same design
+ * problem as a categorical data palette (many hues coexisting in one view that all need to read
+ * as different from each other). The order below interleaves the hue families syntax themes
+ * conventionally assign to keyword/function/string/number/type/variable/operator (violet, blue,
+ * green, orange, teal, cyan, neutral) so the first colors used are spread around the hue wheel
+ * rather than clustered, which is the standard categorical-palette heuristic for maximizing
+ * perceptual separation between adjacent categories.
+ *
+ * Terminal foreground color is a single channel with a hard ceiling on how many hues stay mutually
+ * distinguishable (most qualitative-palette guidance caps around 8–12). Once the hue palette is
+ * exhausted, seriesStyle adds bold as a second, independent visual channel before any exact
+ * color+weight combination repeats — a standard visualization technique (encode extra categories
+ * on an additional channel rather than silently reusing an indistinguishable color).
+ */
+const SERIES_HUES: UsageColor[] = [
+	"accent", "syntaxFunction", "syntaxString", "syntaxNumber",
+	"syntaxKeyword", "syntaxType", "thinkingText", "syntaxVariable", "syntaxOperator",
+];
+
+/** Returns a style function for the Nth series: cycles hue, then adds bold once the palette wraps. */
+function seriesStyle(index: number, theme: UsageTheme): (text: string) => string {
+	const hue = SERIES_HUES[index % SERIES_HUES.length]!;
+	const useBold = Math.floor(index / SERIES_HUES.length) % 2 === 1;
+	return (text: string) => useBold ? theme.bold(theme.fg(hue, text)) : theme.fg(hue, text);
+}
+
 const PARTIAL_BLOCKS = ["▁", "▂", "▃", "▄", "▅", "▆", "▇", "█"];
 
 function compact(value: number): string {
@@ -32,9 +69,13 @@ function compact(value: number): string {
 	return String(Math.round(value));
 }
 
-function mergeBuckets(buckets: UsageBucket[], maximum: number): UsageBucket[] {
+interface RenderableSeries { key: string; provider: string; model: string; total: number }
+interface RenderableBucket { start: number; end: number; total: number; series: Record<string, number> }
+interface RenderableChart { period: UsagePeriod; start: number; end: number; buckets: RenderableBucket[]; series: RenderableSeries[]; total: number; truncated: boolean }
+
+function mergeBuckets(buckets: RenderableBucket[], maximum: number): RenderableBucket[] {
 	if (buckets.length <= maximum) return buckets;
-	const result: UsageBucket[] = [];
+	const result: RenderableBucket[] = [];
 	for (let index = 0; index < maximum; index += 1) {
 		const from = Math.floor(index * buckets.length / maximum);
 		const to = Math.max(from + 1, Math.floor((index + 1) * buckets.length / maximum));
@@ -53,15 +94,24 @@ function mergeBuckets(buckets: UsageBucket[], maximum: number): UsageBucket[] {
 	return result;
 }
 
-function seriesAt(bucket: UsageBucket, chart: UsageGraph, tokenHeight: number): number {
+function seriesAt(bucket: RenderableBucket, chart: RenderableChart, valueHeight: number): number {
 	let cumulative = 0;
 	for (let index = 0; index < chart.series.length; index += 1) {
 		cumulative += bucket.series[chart.series[index]!.key] ?? 0;
-		if (tokenHeight <= cumulative) return index;
+		if (valueHeight <= cumulative) return index;
 	}
 	return Math.max(0, chart.series.length - 1);
 }
 
+/** Compact USD formatter: full cents below $1k, then the same k/M suffix convention as compact(). */
+function formatUsd(value: number): string {
+	const magnitude = Math.abs(value);
+	if (magnitude === 0) return "$0";
+	if (magnitude < 1_000) return `$${value.toFixed(magnitude < 0.01 ? 4 : 2)}`;
+	if (magnitude < 1_000_000) return `$${(value / 1_000).toFixed(1)}k`;
+	return `$${(value / 1_000_000).toFixed(1)}M`;
+}
+
 function formatPeriodPoint(value: number, period: UsagePeriod): string {
 	const date = new Date(value);
 	if (period === "hourly" || period === "daily") return date.toLocaleTimeString(undefined, { hour: "2-digit", minute: "2-digit" });
@@ -80,11 +130,27 @@ function axisLabels(start: number, end: number, period: UsagePeriod, width: numb
 	return characters.join("");
 }
 
+function displayIdentity(value: string): string {
+	return value.replace(/[\r\n\t]/g, " ").replace(/ +/g, " ").trim().slice(0, HUMAN_TEXT_FIELD_MAX_CHARACTERS);
+}
+
 function plainTheme(): UsageTheme {
 	return { fg: (_color, text) => text, bold: (text) => text };
 }
 
-export function renderUsageGraph(chart: UsageGraph, width: number, theme: UsageTheme, tokenBudget?: number): string[] {
+interface ChartRenderOptions {
+	title: string;
+	formatValue: (value: number) => string;
+	/** Appended after the observed/budget amount, e.g. " tokens"; empty when formatValue already carries a unit prefix like "$". */
+	unitSuffix: string;
+	subtitle?: string;
+	budget?: number;
+	noDataText: string;
+}
+
+/** Shared cumulative bar-chart renderer behind renderUsageGraph and renderCostGraph. */
+function renderChart(chart: RenderableChart, width: number, theme: UsageTheme, options: ChartRenderOptions): string[] {
+	const { formatValue, unitSuffix } = options;
 	const safeWidth = Math.max(20, width);
 	const chartColumns = Math.max(1, Math.floor((safeWidth - USAGE_Y_AXIS_WIDTH - 1) / 2));
 	const increments = mergeBuckets(chart.buckets, chartColumns);
@@ -97,24 +163,24 @@ export function renderUsageGraph(chart: UsageGraph, width: number, theme: UsageT
 	});
 	const barStep = buckets.length * 2 <= safeWidth - USAGE_Y_AXIS_WIDTH ? 2 : 1;
 	const plotWidth = buckets.length * barStep;
-	const budget = typeof tokenBudget === "number" && Number.isFinite(tokenBudget) && tokenBudget > 0 ? tokenBudget : undefined;
-	const maximum = Math.max(chart.totalTokens, budget ?? 0);
-	const observed = chart.truncated ? `at least ${compact(chart.totalTokens)}` : compact(chart.totalTokens);
+	const budget = typeof options.budget === "number" && Number.isFinite(options.budget) && options.budget > 0 ? options.budget : undefined;
+	const maximum = Math.max(chart.total, budget ?? 0);
+	const observed = chart.truncated ? `at least ${formatValue(chart.total)}` : formatValue(chart.total);
 	const budgetState = budget === undefined
-		? `${observed} tokens · budget not configured${chart.truncated ? " · query limit reached" : ""}`
-		: chart.totalTokens > budget
-			? `${observed} / ${compact(budget)} budget · OVER BUDGET by ${chart.truncated ? "at least " : ""}${compact(chart.totalTokens - budget)}`
+		? `${observed}${unitSuffix} · budget not configured${chart.truncated ? " · query limit reached" : ""}`
+		: chart.total > budget
+			? `${observed}${unitSuffix} / ${formatValue(budget)} budget · OVER BUDGET by ${chart.truncated ? "at least " : ""}${formatValue(chart.total - budget)}`
 			: chart.truncated
-				? `${observed} / ${compact(budget)} budget · state unknown · query limit reached`
-				: `${observed} / ${compact(budget)} budget · ${compact(budget - chart.totalTokens)} remaining`;
+				? `${observed}${unitSuffix} / ${formatValue(budget)} budget · state unknown · query limit reached`
+				: `${observed}${unitSuffix} / ${formatValue(budget)} budget · ${formatValue(budget - chart.total)} remaining`;
 	const lines = [
-		truncateToWidth(theme.bold(`${usagePeriod(chart.period).label} token usage`), safeWidth, ""),
+		truncateToWidth(theme.bold(options.title), safeWidth, ""),
 		truncateToWidth(budgetState, safeWidth, "…"),
-		truncateToWidth(`input ${compact(chart.breakdown.input)} · output ${compact(chart.breakdown.output)} · cache ${compact(chart.breakdown.cacheRead + chart.breakdown.cacheWrite)}`, safeWidth, "…"),
+		...(options.subtitle ? [truncateToWidth(options.subtitle, safeWidth, "…")] : []),
 		"",
 	];
 	if (maximum === 0) {
-		lines.push(theme.fg("dim", "No recorded Pi token usage in this period."));
+		lines.push(theme.fg("dim", options.noDataText));
 		return lines.map((line) => truncateToWidth(line, safeWidth, "…"));
 	}
 
@@ -123,9 +189,9 @@ export function renderUsageGraph(chart: UsageGraph, width: number, theme: UsageT
 		const lower = maximum * fromBottom / USAGE_CHART_HEIGHT;
 		const upper = maximum * (fromBottom + 1) / USAGE_CHART_HEIGHT;
 		const thresholdRow = budget !== undefined && budget > lower && budget <= upper;
-		const label = thresholdRow ? compact(budget) : row === 0 ? compact(maximum) : row === Math.floor(USAGE_CHART_HEIGHT / 2) ? compact(maximum / 2) : "";
+		const label = thresholdRow ? formatValue(budget) : row === 0 ? formatValue(maximum) : row === Math.floor(USAGE_CHART_HEIGHT / 2) ? formatValue(maximum / 2) : "";
 		if (thresholdRow) {
-			const color = chart.totalTokens > budget ? "error" : "warning";
+			const color = chart.total > budget ? "error" : "warning";
 			lines.push(`${label.padStart(USAGE_Y_AXIS_WIDTH - 2)} ${theme.fg("borderMuted", "│")}${theme.fg(color, "┄".repeat(plotWidth))}`);
 			continue;
 		}
@@ -138,32 +204,73 @@ export function renderUsageGraph(chart: UsageGraph, width: number, theme: UsageT
 				continue;
 			}
 			const block = PARTIAL_BLOCKS[Math.max(0, Math.ceil(occupancy * PARTIAL_BLOCKS.length) - 1)]!;
-			const tokenHeight = Math.min(bucket.total, maximum * (fromBottom + Math.min(occupancy, 0.5)) / USAGE_CHART_HEIGHT);
-			const color = SERIES_COLORS[seriesAt(bucket, chart, tokenHeight) % SERIES_COLORS.length]!;
-			plot += theme.fg(color, block) + (barStep === 2 ? " " : "");
+			const valueHeight = Math.min(bucket.total, maximum * (fromBottom + Math.min(occupancy, 0.5)) / USAGE_CHART_HEIGHT);
+			plot += seriesStyle(seriesAt(bucket, chart, valueHeight), theme)(block) + (barStep === 2 ? " " : "");
 		}
 		lines.push(`${label.padStart(USAGE_Y_AXIS_WIDTH - 2)} ${theme.fg("borderMuted", "│")}${plot}`);
 	}
 	lines.push(`${"0".padStart(USAGE_Y_AXIS_WIDTH - 2)} ${theme.fg("borderMuted", `└${"─".repeat(plotWidth)}`)}`);
 	lines.push(`${" ".repeat(USAGE_Y_AXIS_WIDTH)}${axisLabels(chart.start, chart.end, chart.period, plotWidth)}`);
 	lines.push("");
-	for (let index = 0; index < chart.series.length; index += 1) {
-		const series = chart.series[index]!;
-		const bullet = theme.fg(SERIES_COLORS[index % SERIES_COLORS.length]!, "■");
-		lines.push(truncateToWidth(`${bullet} ${series.provider}/${series.model}  ${compact(series.total)}`, safeWidth, "…"));
+	const displayedSeries = chart.series.slice(0, USAGE_RENDER_MAX_SERIES);
+	for (let index = 0; index < displayedSeries.length; index += 1) {
+		const series = displayedSeries[index]!;
+		const bullet = seriesStyle(index, theme)("■");
+		lines.push(truncateToWidth(`${bullet} ${displayIdentity(series.provider)}/${displayIdentity(series.model)}  ${formatValue(series.total)}`, safeWidth, "…"));
 	}
+	if (chart.series.length > displayedSeries.length) lines.push(truncateToWidth(theme.fg("muted", `… ${chart.series.length - displayedSeries.length} more series omitted`), safeWidth, "…"));
 	return lines.map((line) => visibleWidth(line) <= safeWidth ? line : truncateToWidth(line, safeWidth, "…"));
 }
 
-async function loadUsage(client: JittorPanelClient, period: UsagePeriod, now: number): Promise<UsageGraph> {
-	const rows = await client.call("metrics.query", {
-		source: "pi",
-		since: usagePeriodStart(period, now),
-		until: now,
-		order: "desc",
-		limit: USAGE_TOKEN_QUERY_LIMIT,
-	}) as StoredMetricObservation[];
-	return buildUsageGraph(rows, { period, now, truncated: rows.length >= USAGE_TOKEN_QUERY_LIMIT });
+export function renderUsageGraph(chart: UsageGraph, width: number, theme: UsageTheme, tokenBudget?: number): string[] {
+	return renderChart(
+		{ period: chart.period, start: chart.start, end: chart.end, buckets: chart.buckets, series: chart.series, total: chart.totalTokens, truncated: chart.truncated },
+		width, theme,
+		{
+			title: `${usagePeriod(chart.period).label} token usage`,
+			formatValue: compact,
+			unitSuffix: " tokens",
+			subtitle: `input ${compact(chart.breakdown.input)} · output ${compact(chart.breakdown.output)} · cache ${compact(chart.breakdown.cacheRead + chart.breakdown.cacheWrite)}`,
+			budget: tokenBudget,
+			noDataText: "No recorded Pi token usage in this period.",
+		},
+	);
+}
+
+export function renderCostGraph(chart: CostGraph, width: number, theme: UsageTheme, costBudget?: number): string[] {
+	return renderChart(
+		{ period: chart.period, start: chart.start, end: chart.end, buckets: chart.buckets, series: chart.series, total: chart.totalUsd, truncated: chart.truncated },
+		width, theme,
+		{
+			title: `${usagePeriod(chart.period).label} cost`,
+			formatValue: formatUsd,
+			unitSuffix: "",
+			budget: costBudget,
+			noDataText: "No recorded Pi cost in this period.",
+		},
+	);
+}
+
+export type UsageViewKind = "tokens" | "cost";
+const USAGE_VIEWS: UsageViewKind[] = ["tokens", "cost"];
+
+/**
+ * One bounded round trip: the daemon discovers distinct scopes (still capped at
+ * USAGE_MAX_DISTINCT_SCOPES -- more scopes than that is still a real, honestly-reported
+ * truncation) and SQL-side aggregates every matching observation into (scope, metric, bucket)
+ * sums for the exact window this panel renders. Replaces a per-scope fetch of up to
+ * USAGE_PER_SCOPE_QUERY_LIMIT raw rows each, which fixed a *different* problem (one heavy scope
+ * starving *other* scopes out of a shared row budget) but could still silently truncate a single
+ * heavy scope's *own* older history within the same window -- a real incident: a scope logging
+ * tens of thousands of rows a week had its "weekly" chart built from a few minutes of its most
+ * recent rows alone. Aggregation has no such failure mode: result size scales with (scopes x
+ * metrics x buckets), never with raw event count.
+ */
+async function loadPiMetrics(client: JittorPanelClient, window: ReturnType<typeof resolveUsageWindow>): Promise<{ rows: UsageAggregateRow[]; truncated: boolean }> {
+	const result = await client.call("metrics.usage_series", {
+		source: "pi", since: window.start, until: window.end, bucketSizeMs: window.bucketSizeMs, bucketCount: window.bucketCount, scopeLimit: USAGE_MAX_DISTINCT_SCOPES,
+	}) as { rows: UsageAggregateRow[]; truncated: boolean };
+	return result;
 }
 
 export async function showUsagePanel(
@@ -171,32 +278,43 @@ export async function showUsagePanel(
 	client: JittorPanelClient,
 	budgets: Pick<UsageBudgetControl, "getUsageTokenBudget">,
 	now = Date.now(),
+	initialView: UsageViewKind = "tokens",
 ): Promise<void> {
 	let periodIndex = 0;
+	let viewIndex = Math.max(0, USAGE_VIEWS.indexOf(initialView));
 	for (;;) {
 		const period = USAGE_PERIODS[periodIndex]!.id;
-		const chart = await loadUsage(client, period, now);
+		const window = resolveUsageWindow(period, now);
+		// One bounded query serves both views: token and cost metrics share the same "pi" source rows.
+		const { rows, truncated } = await loadPiMetrics(client, window);
+		const view = USAGE_VIEWS[viewIndex]!;
+		const tokenChart = buildUsageGraph(rows, window, { period, truncated });
+		const costChart = buildCostGraph(rows, window, { period, truncated });
 		const tokenBudget = budgets.getUsageTokenBudget(period);
+		const renderActive = (width: number, theme: UsageTheme): string[] =>
+			view === "tokens" ? renderUsageGraph(tokenChart, width, theme, tokenBudget) : renderCostGraph(costChart, width, theme);
 		if (ctx.mode !== "tui") {
-			ctx.ui.notify(renderUsageGraph(chart, 80, plainTheme(), tokenBudget).join("\n"), "info");
+			ctx.ui.notify(renderActive(80, plainTheme()).join("\n"), "info");
 			return;
 		}
 		const action = await ctx.ui.custom<UsageAction>((_tui, theme, _keybindings, done) => ({
 			invalidate() {},
 			render(width: number): string[] {
-				const lines = renderUsageGraph(chart, width, theme, tokenBudget);
-				const controls = theme.fg("dim", "←/→ period · r refresh · Esc close");
+				const lines = renderActive(width, theme);
+				const controls = theme.fg("dim", "←/→/Tab period · v view · r refresh · Esc close");
 				return [...lines, "", truncateToWidth(controls, width, "…")];
 			},
 			handleInput(data: string): void {
 				if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c") || data === "q") done("close");
-				else if (matchesKey(data, "left")) done("period-prev");
-				else if (matchesKey(data, "right")) done("period-next");
+				else if (matchesKey(data, "left") || matchesKey(data, "shift+tab")) done("period-prev");
+				else if (matchesKey(data, "right") || matchesKey(data, "tab")) done("period-next");
+				else if (data === "v") done("view-next");
 				else if (data === "r") done("refresh");
 			},
 		}));
 		if (!action || action === "close") return;
 		if (action === "period-prev") periodIndex = (periodIndex - 1 + USAGE_PERIODS.length) % USAGE_PERIODS.length;
 		if (action === "period-next") periodIndex = (periodIndex + 1) % USAGE_PERIODS.length;
+		if (action === "view-next") viewIndex = (viewIndex + 1) % USAGE_VIEWS.length;
 	}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/jittor",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "Just-in-Time Token Optimizing Router for Pi",
   "type": "module",
   "keywords": ["pi-package", "llm-router", "token-budget"],
@@ -22,6 +22,10 @@
     "@earendil-works/pi-tui": "*",
     "typebox": "*"
   },
+  "dependencies": {
+    "@danypops/daemon-kit": "^0.3.1",
+    "google-auth-library": "^10.9.0"
+  },
   "devDependencies": {
     "bun-types": "latest"
   },

package/src/adapters/metric-benchmark-store.ts

@@ -0,0 +1,99 @@
+import {
+	BENCHMARK_MAX_OBSERVATIONS_PER_SNAPSHOT,
+	BENCHMARK_STORE_QUERY_LIMIT,
+} from "../constants.ts";
+import {
+	validateBenchmarkObservation,
+	type BenchmarkObservation,
+	type BenchmarkSnapshot,
+} from "../domain/benchmark.ts";
+import type { StoredMetricObservation } from "../domain/metric.ts";
+import type { BenchmarkStore } from "../ports/benchmark-store.ts";
+import type { MetricStore } from "../ports/metric-store.ts";
+
+const COMPLETE_METRIC = "snapshot-complete";
+const SNAPSHOT_SCOPE = "snapshot";
+
+function metricSource(sourceId: string): string {
+	return `benchmark:${sourceId}`;
+}
+
+function observationAttributes(snapshotId: string, observation: BenchmarkObservation): Record<string, unknown> {
+	return {
+		snapshotId,
+		model: observation.model,
+		provenance: observation.provenance,
+		methodology: observation.methodology,
+	};
+}
+
+function decodeObservation(row: StoredMetricObservation): BenchmarkObservation {
+	return validateBenchmarkObservation({
+		model: row.attributes["model"],
+		dimension: row.metric,
+		value: row.value,
+		unit: row.unit,
+		provenance: row.attributes["provenance"],
+		methodology: row.attributes["methodology"],
+	});
+}
+
+export class MetricBenchmarkStore implements BenchmarkStore {
+	constructor(private readonly metrics: MetricStore) {}
+
+	publish(sourceId: string, snapshotId: string, input: BenchmarkObservation[]): BenchmarkSnapshot {
+		if (input.length > BENCHMARK_MAX_OBSERVATIONS_PER_SNAPSHOT) throw new Error("benchmark snapshot exceeds the observation limit");
+		const observations = input.map(validateBenchmarkObservation);
+		const existing = this.latest(sourceId);
+		if (existing?.snapshotId === snapshotId) return existing;
+		const retrievedAt = observations[0]?.provenance.retrievedAt;
+		if (retrievedAt === undefined || observations.some((observation) => observation.provenance.sourceId !== sourceId || observation.provenance.retrievedAt !== retrievedAt)) {
+			throw new Error("benchmark snapshot provenance mismatch");
+		}
+		for (const observation of observations) {
+			this.metrics.record({
+				source: metricSource(sourceId),
+				scope: observation.model.canonical,
+				metric: observation.dimension,
+				value: observation.value,
+				unit: observation.unit,
+				observedAt: retrievedAt,
+				attributes: observationAttributes(snapshotId, observation),
+			});
+		}
+		this.metrics.record({
+			source: metricSource(sourceId),
+			scope: SNAPSHOT_SCOPE,
+			metric: COMPLETE_METRIC,
+			value: observations.length,
+			unit: "count",
+			observedAt: retrievedAt,
+			attributes: { snapshotId, sourceId, retrievedAt },
+		});
+		return { sourceId, snapshotId, retrievedAt, publishedAt: retrievedAt, observations: structuredClone(observations) };
+	}
+
+	latest(sourceId: string): BenchmarkSnapshot | null {
+		const marker = this.metrics.query({ source: metricSource(sourceId), scope: SNAPSHOT_SCOPE, metric: COMPLETE_METRIC, order: "desc", limit: 1 })[0];
+		if (!marker) return null;
+		const rows = this.metrics.query({ source: metricSource(sourceId), until: marker.observedAt, order: "desc", limit: BENCHMARK_STORE_QUERY_LIMIT });
+		const markerIndex = rows.findIndex((row) => row.id === marker.id);
+		if (markerIndex < 0) return null;
+		const snapshotId = marker.attributes["snapshotId"];
+		const expectedCount = marker.value;
+		if (typeof snapshotId !== "string" || typeof expectedCount !== "number" || !Number.isSafeInteger(expectedCount) || expectedCount < 0) return null;
+		const matching = rows.slice(markerIndex + 1).filter((row) => row.attributes["snapshotId"] === snapshotId).slice(0, expectedCount);
+		if (matching.length !== expectedCount) return null;
+		try {
+			return {
+				sourceId,
+				snapshotId,
+				retrievedAt: marker.observedAt,
+				publishedAt: marker.observedAt,
+				observations: matching.reverse().map(decodeObservation),
+			};
+		} catch {
+			return null;
+		}
+	}
+}

package/src/adapters/openrouter-benchmark-index-source.ts

@@ -0,0 +1,94 @@
+import {
+	BENCHMARK_MAX_MODELS_PER_SOURCE,
+	BENCHMARK_REFRESH_INTERVAL_MS,
+	BENCHMARK_SOURCE_MAX_RESPONSE_BYTES,
+} from "../constants.ts";
+import { normalizeModelIdentity, validateBenchmarkObservation, type BenchmarkObservation, type BenchmarkSourceSnapshot } from "../domain/benchmark.ts";
+import type { BenchmarkSource } from "../ports/benchmark-source.ts";
+import { contractRecord } from "../providers/openrouter-contracts.ts";
+import type { OpenRouterBenchmarkTransport } from "./openrouter-benchmark-source.ts";
+
+const SOURCE_ID = "openrouter-artificial-analysis";
+const ENDPOINT = `https://openrouter.ai/api/v1/benchmarks?source=artificial-analysis&task_type=coding&max_results=${BENCHMARK_MAX_MODELS_PER_SOURCE}`;
+
+function requiredText(value: unknown, name: string): string {
+	if (typeof value !== "string" || value.length === 0 || value.length > 500) throw new Error(`OpenRouter benchmark ${name} schema changed`);
+	return value;
+}
+
+function requiredNumber(value: unknown, name: string): number {
+	if (typeof value !== "number" || !Number.isFinite(value)) throw new Error(`OpenRouter benchmark ${name} schema changed`);
+	return value;
+}
+
+function price(value: unknown, name: string): number {
+	const parsed = Number(requiredText(value, name));
+	if (!Number.isFinite(parsed) || parsed < 0) throw new Error(`OpenRouter benchmark ${name} schema changed`);
+	return parsed;
+}
+
+export class OpenRouterBenchmarkIndexSource implements BenchmarkSource {
+	readonly id = SOURCE_ID;
+
+	constructor(
+		private readonly apiKey: string,
+		private readonly transport: OpenRouterBenchmarkTransport = fetch,
+		private readonly clock: () => number = Date.now,
+	) {
+		if (apiKey.length === 0) throw new Error("OpenRouter API key is required for benchmark indices");
+	}
+
+	async fetch(): Promise<BenchmarkSourceSnapshot> {
+		const response = await this.transport(new Request(ENDPOINT, { headers: { authorization: `Bearer ${this.apiKey}` } }));
+		if (!response.ok) throw new Error(`OpenRouter benchmarks failed with HTTP ${response.status}`);
+		const text = await response.text();
+		if (new TextEncoder().encode(text).byteLength > BENCHMARK_SOURCE_MAX_RESPONSE_BYTES) throw new Error("OpenRouter benchmark response exceeds the size limit");
+		let payload: unknown;
+		try { payload = JSON.parse(text); } catch { throw new Error("OpenRouter benchmark response is not valid JSON"); }
+		const root = contractRecord(payload, "benchmark response");
+		const meta = contractRecord(root["meta"], "benchmark metadata");
+		if (!Array.isArray(root["data"]) || root["data"].length === 0 || root["data"].length > BENCHMARK_MAX_MODELS_PER_SOURCE) throw new Error("OpenRouter benchmark result count is invalid");
+		if (requiredText(meta["source"], "source") !== "artificial-analysis") throw new Error("OpenRouter benchmark source schema changed");
+		const version = requiredText(meta["version"], "version");
+		const asOf = requiredText(meta["as_of"], "as-of date");
+		const publishedAt = Date.parse(asOf);
+		if (!Number.isSafeInteger(publishedAt) || publishedAt <= 0) throw new Error("OpenRouter benchmark publication date schema changed");
+		const upstreamUrl = new URL(requiredText(meta["source_url"], "source URL"));
+		if (upstreamUrl.protocol !== "https:") throw new Error("OpenRouter benchmark source URL must use HTTPS");
+		const retrievedAt = this.clock();
+		if (!Number.isSafeInteger(retrievedAt) || retrievedAt <= 0) throw new Error("benchmark retrieval time is invalid");
+		const revision = `${version}:${asOf}`;
+		const observations = root["data"].flatMap((value): BenchmarkObservation[] => {
+			const row = contractRecord(value, "benchmark row");
+			if (requiredText(row["source"], "row source") !== "artificial-analysis") throw new Error("OpenRouter benchmark row source schema changed");
+			const permaslug = requiredText(row["model_permaslug"], "model permaslug");
+			const separator = permaslug.indexOf("/");
+			if (separator <= 0 || separator === permaslug.length - 1) throw new Error("OpenRouter benchmark model identity schema changed");
+			const model = normalizeModelIdentity(permaslug.slice(0, separator), permaslug.slice(separator + 1), [`openrouter/${permaslug}`]);
+			const pricing = contractRecord(row["pricing"], "benchmark pricing");
+			const provenance = {
+				sourceId: SOURCE_ID,
+				sourceType: "independent" as const,
+				publisher: "Artificial Analysis via OpenRouter",
+				url: ENDPOINT,
+				revision,
+				publishedAt,
+				retrievedAt,
+				freshUntil: retrievedAt + BENCHMARK_REFRESH_INTERVAL_MS,
+				license: "OpenRouter API terms; upstream terms apply",
+				confidence: 0.8,
+			};
+			const common = { model, provenance };
+			const methodology = { basis: "Artificial Analysis index via OpenRouter", upstreamUrl: upstreamUrl.toString(), version, asOf };
+			return [
+				validateBenchmarkObservation({ ...common, dimension: "quality-coding", value: requiredNumber(row["coding_index"], "coding index"), unit: "ratio", methodology }),
+				validateBenchmarkObservation({ ...common, dimension: "quality-general", value: requiredNumber(row["intelligence_index"], "intelligence index"), unit: "ratio", methodology }),
+				// agentic_index measures tool-use/agentic execution style, an activity (type), not a subject-matter domain.
+				validateBenchmarkObservation({ ...common, dimension: "quality-type-planning", value: requiredNumber(row["agentic_index"], "agentic index"), unit: "ratio", methodology }),
+				validateBenchmarkObservation({ ...common, dimension: "price-input", value: price(pricing["prompt"], "prompt pricing"), unit: "usd", methodology: { ...methodology, basis: "OpenRouter USD per input token" } }),
+				validateBenchmarkObservation({ ...common, dimension: "price-output", value: price(pricing["completion"], "completion pricing"), unit: "usd", methodology: { ...methodology, basis: "OpenRouter USD per output token" } }),
+			];
+		});
+		return { sourceId: this.id, snapshotId: `${this.id}:${revision}`, retrievedAt, observations };
+	}
+}