@danypops/jittor 0.5.0 → 0.6.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 { HUMAN_TEXT_FIELD_MAX_CHARACTERS, USAGE_CHART_HEIGHT, USAGE_RENDER_MAX_SERIES, USAGE_TOKEN_QUERY_LIMIT, USAGE_Y_AXIS_WIDTH } from "../../src/constants.ts";
 import type { StoredMetricObservation } from "../../src/domain/metric.ts";
 import {
+	buildCostGraph,
 	buildUsageGraph,
 	USAGE_PERIODS,
 	usagePeriod,
 	usagePeriodStart,
-	type UsageBucket,
+	type CostGraph,
 	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,24 +204,57 @@ 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> {
+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"];
+
+async function loadPiMetrics(client: JittorPanelClient, period: UsagePeriod, now: number): Promise<{ rows: StoredMetricObservation[]; truncated: boolean }> {
 	const rows = await client.call("metrics.query", {
 		source: "pi",
 		since: usagePeriodStart(period, now),
@@ -163,7 +262,7 @@ async function loadUsage(client: JittorPanelClient, period: UsagePeriod, now: nu
 		order: "desc",
 		limit: USAGE_TOKEN_QUERY_LIMIT,
 	}) as StoredMetricObservation[];
-	return buildUsageGraph(rows, { period, now, truncated: rows.length >= USAGE_TOKEN_QUERY_LIMIT });
+	return { rows, truncated: rows.length >= USAGE_TOKEN_QUERY_LIMIT };
 }
 
 export async function showUsagePanel(
@@ -171,32 +270,42 @@ 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);
+		// One bounded query serves both views: token and cost metrics share the same "pi" source rows.
+		const { rows, truncated } = await loadPiMetrics(client, period, now);
+		const view = USAGE_VIEWS[viewIndex]!;
+		const tokenChart = buildUsageGraph(rows, { period, now, truncated });
+		const costChart = buildCostGraph(rows, { period, now, 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,9 +1,12 @@
 {
   "name": "@danypops/jittor",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Just-in-Time Token Optimizing Router for Pi",
   "type": "module",
   "keywords": ["pi-package", "llm-router", "token-budget"],
+  "bin": {
+    "jittor": "src/cli.ts"
+  },
   "scripts": {
     "test": "bun test",
     "typecheck": "tsc --noEmit",

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,93 @@
+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 }),
+				validateBenchmarkObservation({ ...common, dimension: "quality-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 };
+	}
+}

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

@@ -0,0 +1,109 @@
+import {
+	BENCHMARK_MAX_MODELS_PER_SOURCE,
+	BENCHMARK_REFRESH_INTERVAL_MS,
+	BENCHMARK_SOURCE_MAX_RESPONSE_BYTES,
+	BENCHMARK_SOURCE_MAX_TOTAL_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, parseOpenRouterModels, type OpenRouterModel } from "../providers/openrouter-contracts.ts";
+
+const OPENROUTER_MODELS_BASE_URL = "https://openrouter.ai/api/v1/models";
+const OPENROUTER_MODELS_URL = `${OPENROUTER_MODELS_BASE_URL}?limit=${BENCHMARK_MAX_MODELS_PER_SOURCE}`;
+const OPENROUTER_LATENCY_URL = `${OPENROUTER_MODELS_URL}&sort=latency-low-to-high`;
+const OPENROUTER_THROUGHPUT_URL = `${OPENROUTER_MODELS_URL}&sort=throughput-high-to-low`;
+const SOURCE_ID = "openrouter-models";
+
+export type OpenRouterBenchmarkTransport = (request: Request) => Promise<Response>;
+
+function identity(model: OpenRouterModel) {
+	const separator = model.id.indexOf("/");
+	if (separator <= 0 || separator === model.id.length - 1) throw new Error("OpenRouter model identity schema changed");
+	const provider = model.id.slice(0, separator);
+	const modelId = model.id.slice(separator + 1);
+	const aliases = [`openrouter/${model.id}`, ...(model.canonicalSlug === model.id ? [] : [model.canonicalSlug])];
+	return normalizeModelIdentity(provider, modelId, aliases);
+}
+
+function provenance(retrievedAt: number, revision: string, url: string, confidence: number) {
+	return {
+		sourceId: SOURCE_ID,
+		sourceType: "marketplace" as const,
+		publisher: "OpenRouter",
+		url,
+		revision,
+		publishedAt: null,
+		retrievedAt,
+		freshUntil: retrievedAt + BENCHMARK_REFRESH_INTERVAL_MS,
+		license: "OpenRouter API terms",
+		confidence,
+	};
+}
+
+function modelObservations(model: OpenRouterModel, retrievedAt: number, revision: string): BenchmarkObservation[] {
+	const common = { model: identity(model), provenance: provenance(retrievedAt, revision, OPENROUTER_MODELS_URL, 0.9) };
+	return [
+		validateBenchmarkObservation({ ...common, dimension: "context-window", value: model.contextLength, unit: "tokens", methodology: { basis: "OpenRouter model context_length" } }),
+		...(model.maxCompletionTokens === null ? [] : [validateBenchmarkObservation({ ...common, dimension: "max-output", value: model.maxCompletionTokens, unit: "tokens", methodology: { basis: "OpenRouter top_provider max_completion_tokens" } })]),
+		validateBenchmarkObservation({ ...common, dimension: "price-input", value: model.pricing.prompt, unit: "usd", methodology: { basis: "USD per input token" } }),
+		validateBenchmarkObservation({ ...common, dimension: "price-output", value: model.pricing.completion, unit: "usd", methodology: { basis: "USD per output token" } }),
+		validateBenchmarkObservation({ ...common, dimension: "parameter-count", value: model.supportedParameters.length, unit: "count", methodology: { basis: "OpenRouter supported_parameters", parameters: [...model.supportedParameters].sort() } }),
+	];
+}
+
+function rankObservations(models: OpenRouterModel[], dimension: "latency-rank" | "throughput-rank", retrievedAt: number, revision: string, url: string): BenchmarkObservation[] {
+	return models.map((model, index) => validateBenchmarkObservation({
+		model: identity(model),
+		dimension,
+		value: index + 1,
+		unit: "count",
+		provenance: provenance(retrievedAt, revision, url, 0.7),
+		methodology: { basis: dimension === "latency-rank" ? "OpenRouter p50 TTFT server-side ordering" : "OpenRouter p50 throughput server-side ordering", rank: index + 1 },
+	}));
+}
+
+interface ModelResponse {
+	models: OpenRouterModel[];
+	etag: string | null;
+	bytes: number;
+}
+
+export class OpenRouterBenchmarkSource implements BenchmarkSource {
+	readonly id = SOURCE_ID;
+
+	constructor(
+		private readonly transport: OpenRouterBenchmarkTransport = fetch,
+		private readonly clock: () => number = Date.now,
+	) {}
+
+	private async readModels(url: string): Promise<ModelResponse> {
+		const response = await this.transport(new Request(url));
+		if (!response.ok) throw new Error(`OpenRouter models failed with HTTP ${response.status}`);
+		const text = await response.text();
+		const bytes = new TextEncoder().encode(text).byteLength;
+		if (bytes > BENCHMARK_SOURCE_MAX_RESPONSE_BYTES) throw new Error("OpenRouter models response exceeds the size limit");
+		let payload: unknown;
+		try { payload = JSON.parse(text); } catch { throw new Error("OpenRouter models response is not valid JSON"); }
+		const root = contractRecord(payload, "models response");
+		if (!Array.isArray(root["data"]) || root["data"].length === 0 || root["data"].length > BENCHMARK_MAX_MODELS_PER_SOURCE) throw new Error("OpenRouter models response exceeds the model limit");
+		return { models: parseOpenRouterModels(payload), etag: response.headers.get("etag")?.slice(0, 120) ?? null, bytes };
+	}
+
+	async fetch(): Promise<BenchmarkSourceSnapshot> {
+		const [catalog, latency, throughput] = await Promise.all([
+			this.readModels(OPENROUTER_MODELS_URL),
+			this.readModels(OPENROUTER_LATENCY_URL),
+			this.readModels(OPENROUTER_THROUGHPUT_URL),
+		]);
+		if (catalog.bytes + latency.bytes + throughput.bytes > BENCHMARK_SOURCE_MAX_TOTAL_RESPONSE_BYTES) throw new Error("OpenRouter model evidence exceeds the total size limit");
+		const retrievedAt = this.clock();
+		if (!Number.isSafeInteger(retrievedAt) || retrievedAt <= 0) throw new Error("benchmark retrieval time is invalid");
+		const revision = catalog.etag || latency.etag || throughput.etag || `retrieved:${retrievedAt}`;
+		const observations = [
+			...catalog.models.flatMap((model) => modelObservations(model, retrievedAt, revision)),
+			...rankObservations(latency.models, "latency-rank", retrievedAt, revision, OPENROUTER_LATENCY_URL),
+			...rankObservations(throughput.models, "throughput-rank", retrievedAt, revision, OPENROUTER_THROUGHPUT_URL),
+		];
+		return { sourceId: this.id, snapshotId: `${this.id}:${revision}`, retrievedAt, observations };
+	}
+}