@danypops/jittor 0.5.1 → 0.7.0

package/src/domain/context-telemetry.ts

@@ -1,4 +1,6 @@
 import {
+	COMPACTION_DURATION_ESTIMATE_MAX_SAMPLES,
+	COMPACTION_DURATION_ESTIMATE_MIN_SAMPLES,
 	CONTEXT_OBSERVATION_MAX_AGE_MS,
 	CONTEXT_OBSERVATION_MAX_CHARACTERS,
 	MILLISECONDS_PER_HOUR,
@@ -278,3 +280,32 @@ export function assessContextTelemetry(
 		},
 	};
 }
+
+export interface CompactionDurationEstimate {
+	ms: number | null;
+	confidence: "cold-start" | "learned";
+	sampleSize: number;
+	observedAt: number;
+}
+
+/**
+ * Learns a bounded duration estimate from the most recent completed Pi compactions so the drain
+ * animation can show an approximate time-to-completion instead of a fixed-rate guess. Reads only
+ * the numeric `compaction-duration` value already recorded content-free by CompactionTelemetry
+ * (never transcript content, credentials, or attributes) and is bounded to the caller-provided
+ * rows — callers must query with `limit: COMPACTION_DURATION_ESTIMATE_MAX_SAMPLES` so retention is
+ * bounded at the query layer, not just here. Below COMPACTION_DURATION_ESTIMATE_MIN_SAMPLES samples
+ * the estimate stays explicit cold-start uncertainty rather than a guess from too little evidence.
+ */
+export function estimateCompactionDuration(compactions: StoredMetricObservation[], now = Date.now()): CompactionDurationEstimate {
+	const durations = compactions
+		.filter((row) => row.source === "pi-context" && row.scope === "compaction" && row.metric === "compaction-duration")
+		.sort((left, right) => right.observedAt - left.observedAt || right.id - left.id)
+		.slice(0, COMPACTION_DURATION_ESTIMATE_MAX_SAMPLES)
+		.flatMap((row) => typeof row.value === "number" && Number.isFinite(row.value) && row.value >= 0 ? [row.value] : []);
+	if (durations.length < COMPACTION_DURATION_ESTIMATE_MIN_SAMPLES) {
+		return { ms: null, confidence: "cold-start", sampleSize: durations.length, observedAt: now };
+	}
+	const median = percentile(durations, 0.5);
+	return { ms: median === null ? null : Math.round(median), confidence: "learned", sampleSize: durations.length, observedAt: now };
+}

package/src/domain/metric.ts

@@ -1,4 +1,6 @@
-export const METRIC_UNITS = ["ratio", "usd", "tokens", "requests", "milliseconds", "count"] as const;
+import { METRIC_ATTRIBUTES_MAX_DEPTH, METRIC_ATTRIBUTES_MAX_SERIALIZED_CHARACTERS, METRIC_IDENTITY_MAX_CHARACTERS } from "../constants.ts";
+
+export const METRIC_UNITS = ["ratio", "usd", "tokens", "tokens-per-second", "requests", "milliseconds", "count"] as const;
 export type MetricUnit = typeof METRIC_UNITS[number];
 
 export interface MetricObservation {
@@ -26,11 +28,52 @@ export interface MetricQuery {
 	order?: "asc" | "desc";
 }
 
+const SENSITIVE_ATTRIBUTE_KEYS = new Set([
+	"accesstoken",
+	"refreshtoken",
+	"authorization",
+	"apikey",
+	"secret",
+	"password",
+	"cookie",
+	"credential",
+	"otpseed",
+]);
+
+function assertCredentialSafeAttributes(value: unknown, depth = 0): void {
+	if (depth > METRIC_ATTRIBUTES_MAX_DEPTH) throw new Error("attributes exceed the nesting depth limit");
+	if (Array.isArray(value)) {
+		for (const item of value) assertCredentialSafeAttributes(item, depth + 1);
+		return;
+	}
+	if (typeof value !== "object" || value === null) return;
+	for (const [key, nested] of Object.entries(value)) {
+		const normalized = key.toLowerCase().replace(/[^a-z0-9]/g, "");
+		if (SENSITIVE_ATTRIBUTE_KEYS.has(normalized)) throw new Error("attributes contain a sensitive field");
+		assertCredentialSafeAttributes(nested, depth + 1);
+	}
+}
+
+function validateAttributes(value: unknown): Record<string, unknown> {
+	if (value === undefined) return {};
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("attributes must be an object");
+	let serialized: string;
+	try {
+		serialized = JSON.stringify(value);
+	} catch {
+		throw new Error("attributes must be JSON serializable");
+	}
+	if (serialized.length > METRIC_ATTRIBUTES_MAX_SERIALIZED_CHARACTERS) throw new Error("attributes exceed the serialized size limit");
+	assertCredentialSafeAttributes(value);
+	return value as Record<string, unknown>;
+}
+
 export function validateMetricObservation(value: unknown): MetricObservation {
 	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("metric observation must be an object");
 	const input = value as Record<string, unknown>;
 	for (const key of ["source", "scope", "metric", "unit"] as const) {
 		if (typeof input[key] !== "string" || input[key].trim().length === 0) throw new Error(`${key} is required`);
+		if (input[key].length > METRIC_IDENTITY_MAX_CHARACTERS) throw new Error(`${key} exceeds the length limit`);
 	}
 	if (!METRIC_UNITS.includes(input["unit"] as MetricUnit)) throw new Error("unit is not supported");
 	if (input["value"] !== null && (typeof input["value"] !== "number" || !Number.isFinite(input["value"]))) {
@@ -39,9 +82,7 @@ export function validateMetricObservation(value: unknown): MetricObservation {
 	if (typeof input["observedAt"] !== "number" || !Number.isSafeInteger(input["observedAt"]) || input["observedAt"] < 0) {
 		throw new Error("observedAt must be a non-negative integer timestamp");
 	}
-	if (input["attributes"] !== undefined && (typeof input["attributes"] !== "object" || input["attributes"] === null || Array.isArray(input["attributes"]))) {
-		throw new Error("attributes must be an object");
-	}
+	const attributes = validateAttributes(input["attributes"]);
 	return {
 		source: input["source"] as string,
 		scope: input["scope"] as string,
@@ -49,6 +90,6 @@ export function validateMetricObservation(value: unknown): MetricObservation {
 		value: input["value"] as number | null,
 		unit: input["unit"] as MetricUnit,
 		observedAt: input["observedAt"] as number,
-		attributes: (input["attributes"] as Record<string, unknown> | undefined) ?? {},
+		attributes,
 	};
 }

package/src/domain/model-observation.ts

@@ -0,0 +1,203 @@
+import {
+	MODEL_AGGREGATE_MAX_GROUPS,
+	MODEL_AGGREGATE_MAX_ROWS,
+	MODEL_OBSERVATION_FRESH_MS,
+	MODEL_OBSERVATION_IDENTITY_MAX_CHARACTERS,
+} from "../constants.ts";
+import { normalizeModelIdentity } from "./benchmark.ts";
+import type { MetricObservation, MetricUnit, StoredMetricObservation } from "./metric.ts";
+
+/**
+ * Two independent axes, not one flat class: "coding" is a subject-matter domain (which
+ * benchmark quality evidence applies), while "research"/"planning" are activities that can
+ * happen inside any domain (which predict how much reasoning effort a task needs). The prior
+ * single ModelTaskClass conflated them -- an agentic/tool-use benchmark (a type signal) was
+ * being read as if it were a domain-quality signal. Both axes default to "general" when tool
+ * usage carries no distinguishing signal for that axis; a run can score coding on domain and
+ * research on type simultaneously (e.g. reading a file, then searching the web in one turn).
+ */
+export const TASK_DOMAINS = ["coding", "general"] as const;
+export type ModelTaskDomain = typeof TASK_DOMAINS[number];
+export const TASK_TYPES = ["research", "planning", "general"] as const;
+export type ModelTaskType = typeof TASK_TYPES[number];
+export type ExplicitOutcome = "accepted" | "rejected" | "unknown";
+
+export interface ModelRunObservation {
+	runId: string;
+	provider: string;
+	model: string;
+	thinking: string;
+	domain: ModelTaskDomain;
+	type: ModelTaskType;
+	startedAt: number;
+	firstTokenAt: number | null;
+	completedAt: number;
+	inputTokens: number;
+	outputTokens: number;
+	cacheReadTokens: number;
+	cacheWriteTokens: number;
+	costUsd: number;
+	providerResponses: number;
+	toolCalls: number;
+	toolFailures: number;
+	stopReason: "stop" | "length" | "toolUse" | "error" | "aborted" | "unknown";
+	explicitOutcome: ExplicitOutcome;
+}
+
+export interface ModelMetricAggregate {
+	provider: string;
+	model: string;
+	thinking: string;
+	domain: ModelTaskDomain;
+	type: ModelTaskType;
+	dimension: string;
+	unit: MetricUnit;
+	sampleSize: number;
+	median: number;
+	p90: number;
+	medianAbsoluteDeviation: number;
+	latestAt: number;
+	freshness: "fresh" | "stale";
+	confidence: number;
+}
+
+export interface ModelAggregateOptions {
+	now?: number;
+	freshForMs?: number;
+}
+
+const ALLOWED_FIELDS = new Set<keyof ModelRunObservation>([
+	"runId", "provider", "model", "thinking", "domain", "type", "startedAt", "firstTokenAt", "completedAt",
+	"inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "costUsd", "providerResponses",
+	"toolCalls", "toolFailures", "stopReason", "explicitOutcome",
+]);
+const STOP_REASONS = new Set<ModelRunObservation["stopReason"]>(["stop", "length", "toolUse", "error", "aborted", "unknown"]);
+const OUTCOMES = new Set<ExplicitOutcome>(["accepted", "rejected", "unknown"]);
+
+function text(value: unknown, name: string): string {
+	if (typeof value !== "string" || value.length === 0 || value.length > MODEL_OBSERVATION_IDENTITY_MAX_CHARACTERS || /\p{Cc}/u.test(value)) throw new Error(`${name} is invalid`);
+	return value;
+}
+
+function nonNegative(value: unknown, name: string, integer = false): number {
+	if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || (integer && !Number.isSafeInteger(value))) throw new Error(`${name} is invalid`);
+	return value;
+}
+
+export function validateModelRunObservation(value: unknown): ModelRunObservation {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("model run observation must be an object");
+	const input = value as Record<string, unknown>;
+	for (const key of Object.keys(input)) if (!ALLOWED_FIELDS.has(key as keyof ModelRunObservation)) throw new Error(`unsupported field: ${key}`);
+	const identity = normalizeModelIdentity(text(input["provider"], "provider"), text(input["model"], "model"));
+	const startedAt = nonNegative(input["startedAt"], "start time", true);
+	const completedAt = nonNegative(input["completedAt"], "completion time", true);
+	const firstTokenAt = input["firstTokenAt"] === null ? null : nonNegative(input["firstTokenAt"], "first-token time", true);
+	if (completedAt < startedAt || (firstTokenAt !== null && (firstTokenAt < startedAt || firstTokenAt > completedAt))) throw new Error("model run timestamps are not ordered");
+	if (!TASK_DOMAINS.includes(input["domain"] as ModelTaskDomain)) throw new Error("task domain is invalid");
+	if (!TASK_TYPES.includes(input["type"] as ModelTaskType)) throw new Error("task type is invalid");
+	if (!STOP_REASONS.has(input["stopReason"] as ModelRunObservation["stopReason"])) throw new Error("stop reason is invalid");
+	if (!OUTCOMES.has(input["explicitOutcome"] as ExplicitOutcome)) throw new Error("explicit outcome is invalid");
+	const providerResponses = nonNegative(input["providerResponses"], "provider response count", true);
+	const toolCalls = nonNegative(input["toolCalls"], "tool call count", true);
+	const toolFailures = nonNegative(input["toolFailures"], "tool failure count", true);
+	if (providerResponses < 1 || toolFailures > toolCalls) throw new Error("model run counters are inconsistent");
+	return {
+		runId: text(input["runId"], "run id"), provider: identity.provider, model: identity.model,
+		thinking: text(input["thinking"], "thinking level"), domain: input["domain"] as ModelTaskDomain, type: input["type"] as ModelTaskType,
+		startedAt, firstTokenAt, completedAt,
+		inputTokens: nonNegative(input["inputTokens"], "input tokens"),
+		outputTokens: nonNegative(input["outputTokens"], "output tokens"),
+		cacheReadTokens: nonNegative(input["cacheReadTokens"], "cache read tokens"),
+		cacheWriteTokens: nonNegative(input["cacheWriteTokens"], "cache write tokens"),
+		costUsd: nonNegative(input["costUsd"], "cost"), providerResponses, toolCalls, toolFailures,
+		stopReason: input["stopReason"] as ModelRunObservation["stopReason"], explicitOutcome: input["explicitOutcome"] as ExplicitOutcome,
+	};
+}
+
+export interface ModelTaskClassification {
+	domain: ModelTaskDomain;
+	type: ModelTaskType;
+}
+
+/** Domain and type are independent: a run can be domain=coding and type=research at once (e.g. reading a file, then searching the web in the same turn). */
+export function classifyTaskFromTools(toolNames: string[]): ModelTaskClassification {
+	const names = new Set(toolNames.slice(0, 100).map((name) => name.toLowerCase()));
+	const domain: ModelTaskDomain = ["edit", "write", "read", "bash", "grep", "find", "ls"].some((name) => names.has(name)) ? "coding" : "general";
+	const type: ModelTaskType = ["web_fetch", "web_search"].some((name) => names.has(name))
+		? "research"
+		: ["tasks", "papyrus_create", "papyrus_graph"].some((name) => names.has(name)) ? "planning" : "general";
+	return { domain, type };
+}
+
+export function modelRunMetrics(value: ModelRunObservation): MetricObservation[] {
+	const run = validateModelRunObservation(value);
+	const scope = `${run.provider}/${run.model}`;
+	const attributes = { provider: run.provider, model: run.model, thinking: run.thinking, domain: run.domain, type: run.type, runId: run.runId };
+	const metric = (name: string, amount: number, unit: MetricUnit): MetricObservation => ({ source: "local-model", scope, metric: name, value: amount, unit, observedAt: run.completedAt, attributes });
+	const wallMs = run.completedAt - run.startedAt;
+	const totalInput = run.inputTokens + run.cacheReadTokens;
+	const metrics: MetricObservation[] = [];
+	if (run.firstTokenAt !== null) metrics.push(metric("ttft", run.firstTokenAt - run.startedAt, "milliseconds"));
+	metrics.push(
+		metric("wall-latency", wallMs, "milliseconds"),
+		metric("output-throughput", wallMs === 0 ? 0 : run.outputTokens / (wallMs / 1_000), "tokens-per-second"),
+		metric("input-tokens", run.inputTokens, "tokens"),
+		metric("output-tokens", run.outputTokens, "tokens"),
+		metric("cache-read-tokens", run.cacheReadTokens, "tokens"),
+		metric("cache-write-tokens", run.cacheWriteTokens, "tokens"),
+		metric("cache-read-ratio", totalInput === 0 ? 0 : run.cacheReadTokens / totalInput, "ratio"),
+		metric("cost", run.costUsd, "usd"),
+		metric("provider-responses", run.providerResponses, "count"),
+		metric("retry-count", Math.max(0, run.providerResponses - 1), "count"),
+		metric("tool-calls", run.toolCalls, "count"),
+		metric("tool-failures", run.toolFailures, "count"),
+		metric("failure", run.stopReason === "error" ? 1 : 0, "ratio"),
+	);
+	if (run.explicitOutcome !== "unknown") metrics.push(metric("outcome-accepted", run.explicitOutcome === "accepted" ? 1 : 0, "ratio"));
+	return metrics;
+}
+
+function percentile(sorted: number[], fraction: number): number {
+	return sorted[Math.max(0, Math.ceil(sorted.length * fraction) - 1)]!;
+}
+
+function median(sorted: number[]): number {
+	const middle = Math.floor(sorted.length / 2);
+	return sorted.length % 2 === 0 ? (sorted[middle - 1]! + sorted[middle]!) / 2 : sorted[middle]!;
+}
+
+export function aggregateModelMetrics(input: StoredMetricObservation[], options: ModelAggregateOptions = {}): ModelMetricAggregate[] {
+	const now = options.now ?? Date.now();
+	const freshForMs = options.freshForMs ?? MODEL_OBSERVATION_FRESH_MS;
+	if (!Number.isSafeInteger(now) || now < 0 || !Number.isSafeInteger(freshForMs) || freshForMs <= 0) throw new Error("aggregate time bounds are invalid");
+	const groups = new Map<string, StoredMetricObservation[]>();
+	for (const row of input.slice(0, MODEL_AGGREGATE_MAX_ROWS)) {
+		if (row.source !== "local-model" || typeof row.value !== "number" || !Number.isFinite(row.value)) continue;
+		const provider = row.attributes["provider"];
+		const model = row.attributes["model"];
+		const thinking = row.attributes["thinking"];
+		const domain = row.attributes["domain"];
+		const type = row.attributes["type"];
+		if (typeof provider !== "string" || typeof model !== "string" || typeof thinking !== "string" || !TASK_DOMAINS.includes(domain as ModelTaskDomain) || !TASK_TYPES.includes(type as ModelTaskType)) continue;
+		const key = JSON.stringify([provider, model, thinking, domain, type, row.metric, row.unit]);
+		if (!groups.has(key) && groups.size >= MODEL_AGGREGATE_MAX_GROUPS) continue;
+		const rows = groups.get(key) ?? [];
+		rows.push(row);
+		groups.set(key, rows);
+	}
+	return [...groups.entries()].map(([key, rows]) => {
+		const [provider, model, thinking, domain, type, dimension, unit] = JSON.parse(key) as [string, string, string, ModelTaskDomain, ModelTaskType, string, MetricUnit];
+		const values = rows.map((row) => row.value as number).sort((left, right) => left - right);
+		const center = median(values);
+		const deviations = values.map((value) => Math.abs(value - center)).sort((left, right) => left - right);
+		const latestAt = Math.max(...rows.map((row) => row.observedAt));
+		const age = Math.max(0, now - latestAt);
+		const recency = Math.max(0, 1 - (age / freshForMs));
+		return {
+			provider, model, thinking, domain, type, dimension, unit,
+			sampleSize: values.length, median: center, p90: percentile(values, 0.9), medianAbsoluteDeviation: median(deviations), latestAt,
+			freshness: age <= freshForMs ? "fresh" as const : "stale" as const,
+			confidence: Math.min(1, Math.sqrt(values.length / 20)) * recency,
+		};
+	}).sort((left, right) => left.provider.localeCompare(right.provider) || left.model.localeCompare(right.model) || left.domain.localeCompare(right.domain) || left.type.localeCompare(right.type) || left.dimension.localeCompare(right.dimension));
+}

package/src/domain/model-ranking-service.ts

@@ -0,0 +1,41 @@
+import { MODEL_AGGREGATE_MAX_ROWS, MODEL_OBSERVATION_FRESH_MS, MODEL_RANKING_MAX_SOURCES } from "../constants.ts";
+import type { BenchmarkStore } from "../ports/benchmark-store.ts";
+import type { MetricStore } from "../ports/metric-store.ts";
+import { aggregateModelMetrics } from "./model-observation.ts";
+import { rankModelCandidates, type ModelCandidate, type ModelRankingResult, type ScopeAuthority, type UtilityWeights } from "./model-ranking.ts";
+import type { ModelTaskDomain, ModelTaskType } from "./model-observation.ts";
+
+export interface ModelRecommendationInput {
+	candidates: ModelCandidate[];
+	scopeAuthority: ScopeAuthority;
+	domain: ModelTaskDomain;
+	type: ModelTaskType;
+	budgetPressure: number;
+	weights: UtilityWeights;
+	sourceIds: string[];
+}
+
+export interface ModelRanker {
+	rank(input: ModelRecommendationInput): ModelRankingResult;
+}
+
+export class EvidenceModelRanker implements ModelRanker {
+	constructor(
+		private readonly benchmarks: BenchmarkStore,
+		private readonly metrics: MetricStore,
+		private readonly clock: () => number = Date.now,
+	) {}
+
+	rank(input: ModelRecommendationInput): ModelRankingResult {
+		if (!Array.isArray(input.sourceIds) || input.sourceIds.length > MODEL_RANKING_MAX_SOURCES || !input.sourceIds.every((sourceId) => typeof sourceId === "string" && sourceId.length > 0 && sourceId.length <= 160)) {
+			throw new Error("benchmark source selection is invalid");
+		}
+		const sourceIds = [...new Set(input.sourceIds)];
+		const { sourceIds: _sourceIds, ...rankingInput } = input;
+		const externalEvidence = sourceIds.flatMap((sourceId) => this.benchmarks.latest(sourceId)?.observations ?? []);
+		const localRows = this.metrics.query({ source: "local-model", order: "desc", limit: MODEL_AGGREGATE_MAX_ROWS });
+		const now = this.clock();
+		const localEvidence = aggregateModelMetrics(localRows, { now, freshForMs: MODEL_OBSERVATION_FRESH_MS });
+		return rankModelCandidates({ ...rankingInput, externalEvidence, localEvidence, now });
+	}
+}

package/src/domain/model-ranking.ts

@@ -0,0 +1,232 @@
+import { BENCHMARK_MAX_OBSERVATIONS_PER_SNAPSHOT, MAX_DYNAMIC_ROUTES, MODEL_AGGREGATE_MAX_ROWS } from "../constants.ts";
+import { normalizeModelIdentity, type BenchmarkObservation } from "./benchmark.ts";
+import { TASK_DOMAINS, TASK_TYPES, type ModelMetricAggregate, type ModelTaskDomain, type ModelTaskType } from "./model-observation.ts";
+
+export type ScopeAuthority = "exact-session" | "available-models";
+export type UtilityComponentName = "quality" | "cost" | "latency" | "context" | "reliability";
+
+export interface ModelCandidate {
+	provider: string;
+	model: string;
+	thinking: string;
+}
+
+export interface UtilityWeights {
+	quality: number;
+	cost: number;
+	latency: number;
+	context: number;
+	reliability: number;
+}
+
+export interface ModelRankingInput {
+	candidates: ModelCandidate[];
+	scopeAuthority: ScopeAuthority;
+	domain: ModelTaskDomain;
+	type: ModelTaskType;
+	budgetPressure: number;
+	weights: UtilityWeights;
+	externalEvidence: BenchmarkObservation[];
+	localEvidence: ModelMetricAggregate[];
+	now: number;
+}
+
+export interface UtilityComponent {
+	name: UtilityComponentName;
+	score: number | null;
+	confidence: number;
+	weight: number;
+	evidenceCount: number;
+	reason: string;
+}
+
+export interface RankingProvenance {
+	sourceId: string;
+	publisher: string;
+	url: string;
+	revision: string;
+	freshness: "fresh" | "stale";
+}
+
+export interface RankedModel {
+	candidate: ModelCandidate;
+	identity: string;
+	utility: number | null;
+	confidence: number;
+	components: UtilityComponent[];
+	provenance: RankingProvenance[];
+	trace: string[];
+}
+
+export interface ModelRankingResult {
+	scopeAuthority: ScopeAuthority;
+	scopeWarning: string | null;
+	domain: ModelTaskDomain;
+	type: ModelTaskType;
+	completeness: "complete" | "partial" | "insufficient-evidence";
+	ranked: RankedModel[];
+	automaticSelection: ModelCandidate | null;
+}
+
+interface RawComponent {
+	value: number | null;
+	confidence: number;
+	evidenceCount: number;
+	reason: string;
+	lowerIsBetter: boolean;
+}
+
+const COMPONENTS: UtilityComponentName[] = ["quality", "cost", "latency", "context", "reliability"];
+
+function finiteBound(value: number, name: string, minimum: number, maximum: number): number {
+	if (!Number.isFinite(value) || value < minimum || value > maximum) throw new Error(`${name} is outside its supported range`);
+	return value;
+}
+
+function candidateIdentity(candidate: ModelCandidate): string {
+	const identity = normalizeModelIdentity(candidate.provider, candidate.model);
+	if (typeof candidate.thinking !== "string" || candidate.thinking.length === 0 || candidate.thinking.length > 160) throw new Error("candidate thinking level is invalid");
+	return `${identity.canonical}:${candidate.thinking}`;
+}
+
+function average(values: number[]): number {
+	return values.reduce((sum, value) => sum + value, 0) / values.length;
+}
+
+function externalValues(candidate: ModelCandidate, evidence: BenchmarkObservation[], dimensions: string[], now: number): { values: number[]; confidences: number[]; provenance: RankingProvenance[] } {
+	const identity = normalizeModelIdentity(candidate.provider, candidate.model);
+	const matching = evidence.filter((item) => (item.model.canonical === identity.canonical || item.model.aliases.includes(identity.canonical)) && dimensions.includes(item.dimension));
+	return {
+		values: matching.map((item) => item.value),
+		confidences: matching.map((item) => item.provenance.confidence * (now <= item.provenance.freshUntil ? 1 : 0.25)),
+		provenance: matching.map((item) => ({ sourceId: item.provenance.sourceId, publisher: item.provenance.publisher, url: item.provenance.url, revision: item.provenance.revision, freshness: now <= item.provenance.freshUntil ? "fresh" : "stale" })),
+	};
+}
+
+function localValues(candidate: ModelCandidate, domain: ModelTaskDomain, type: ModelTaskType, evidence: ModelMetricAggregate[], dimension: string): ModelMetricAggregate[] {
+	const identity = normalizeModelIdentity(candidate.provider, candidate.model);
+	return evidence.filter((item) => item.provider === identity.provider && item.model === identity.model && item.thinking === candidate.thinking && item.domain === domain && item.type === type && item.dimension === dimension);
+}
+
+/**
+ * quality-{domain} is a subject-matter signal (e.g. quality-coding from a coding benchmark);
+ * quality-type-{type} is an activity signal (e.g. quality-type-planning from an agentic/tool-use
+ * benchmark). Both are optional and additive on top of the universal quality-general fallback --
+ * a candidate with no domain- or type-specific evidence still gets ranked on general quality
+ * rather than being treated as having zero evidence.
+ */
+function qualityDimensions(domain: ModelTaskDomain, type: ModelTaskType): string[] {
+	const dimensions: string[] = [];
+	if (domain !== "general") dimensions.push(`quality-${domain}`);
+	if (type !== "general") dimensions.push(`quality-type-${type}`);
+	dimensions.push("quality-general");
+	return dimensions;
+}
+
+function rawComponents(candidate: ModelCandidate, input: ModelRankingInput): { components: Record<UtilityComponentName, RawComponent>; provenance: RankingProvenance[] } {
+	const quality = externalValues(candidate, input.externalEvidence, qualityDimensions(input.domain, input.type), input.now);
+	const priceInput = externalValues(candidate, input.externalEvidence, ["price-input"], input.now);
+	const priceOutput = externalValues(candidate, input.externalEvidence, ["price-output"], input.now);
+	const measuredLatency = externalValues(candidate, input.externalEvidence, ["latency"], input.now);
+	const rankedLatency = externalValues(candidate, input.externalEvidence, ["latency-rank", "throughput-rank"], input.now);
+	const latency = measuredLatency.values.length > 0 ? measuredLatency : rankedLatency;
+	const context = externalValues(candidate, input.externalEvidence, ["context-window"], input.now);
+	const localLatency = localValues(candidate, input.domain, input.type, input.localEvidence, "wall-latency");
+	const failures = localValues(candidate, input.domain, input.type, input.localEvidence, "failure");
+	const outcomes = localValues(candidate, input.domain, input.type, input.localEvidence, "outcome-accepted");
+	const qualityValues = quality.values;
+	const prices = [...priceInput.values, ...priceOutput.values];
+	const latencyValues = localLatency.length > 0 ? localLatency.map((item) => item.median) : latency.values;
+	const latencyConfidences = localLatency.length > 0 ? localLatency.map((item) => item.confidence) : latency.confidences;
+	const reliabilityValues = [...failures.map((item) => 1 - item.median), ...outcomes.map((item) => item.median)];
+	const withEvidence = (values: number[], confidences: number[], lowerIsBetter: boolean, label: string): RawComponent => values.length === 0
+		? { value: null, confidence: 0, evidenceCount: 0, reason: `${label} evidence is missing`, lowerIsBetter }
+		: {
+			value: average(values),
+			confidence: average(confidences) / (1 + ((Math.max(...values) - Math.min(...values)) / Math.max(Math.abs(average(values)), Number.EPSILON))),
+			evidenceCount: values.length,
+			reason: `${values.length} ${label} observation${values.length === 1 ? "" : "s"}`,
+			lowerIsBetter,
+		};
+	const components: Record<UtilityComponentName, RawComponent> = {
+		quality: withEvidence(qualityValues, quality.confidences, false, "task quality"),
+		cost: withEvidence(prices, [...priceInput.confidences, ...priceOutput.confidences], true, "price"),
+		latency: withEvidence(latencyValues, latencyConfidences, true, "latency"),
+		context: withEvidence(context.values, context.confidences, false, "context window"),
+		reliability: withEvidence(reliabilityValues, [...failures, ...outcomes].map((item) => item.confidence), false, "local reliability"),
+	};
+	return { components, provenance: [...quality.provenance, ...priceInput.provenance, ...priceOutput.provenance, ...latency.provenance, ...context.provenance] };
+}
+
+function normalizedScore(value: number, values: number[], lowerIsBetter: boolean): number {
+	const minimum = Math.min(...values);
+	const maximum = Math.max(...values);
+	if (maximum === minimum) return 0.5;
+	const score = (value - minimum) / (maximum - minimum);
+	return lowerIsBetter ? 1 - score : score;
+}
+
+export function rankModelCandidates(value: ModelRankingInput): ModelRankingResult {
+	if (!Array.isArray(value.candidates) || value.candidates.length === 0 || value.candidates.length > MAX_DYNAMIC_ROUTES) throw new Error("candidate count is outside its supported range");
+	if (!Array.isArray(value.externalEvidence) || value.externalEvidence.length > BENCHMARK_MAX_OBSERVATIONS_PER_SNAPSHOT * 4) throw new Error("external evidence exceeds the supported bound");
+	if (!Array.isArray(value.localEvidence) || value.localEvidence.length > MODEL_AGGREGATE_MAX_ROWS) throw new Error("local evidence exceeds the supported bound");
+	if (value.scopeAuthority !== "exact-session" && value.scopeAuthority !== "available-models") throw new Error("scope authority is invalid");
+	if (!TASK_DOMAINS.includes(value.domain)) throw new Error("task domain is invalid");
+	if (!TASK_TYPES.includes(value.type)) throw new Error("task type is invalid");
+	if (!Number.isSafeInteger(value.now) || value.now <= 0) throw new Error("ranking time is invalid");
+	const budgetPressure = finiteBound(value.budgetPressure, "budget pressure", 0, 2);
+	const weights = Object.fromEntries(COMPONENTS.map((name) => [name, finiteBound(value.weights[name], `${name} weight`, 0, 10)])) as unknown as UtilityWeights;
+	const seen = new Set<string>();
+	const candidates = value.candidates.map((candidate) => ({ ...candidate })).filter((candidate) => {
+		const identity = candidateIdentity(candidate);
+		if (seen.has(identity)) return false;
+		seen.add(identity);
+		return true;
+	});
+	const raw = candidates.map((candidate) => rawComponents(candidate, value));
+	const effectiveWeights: UtilityWeights = { ...weights, cost: weights.cost * (1 + budgetPressure) };
+	const ranked = candidates.map((candidate, index): RankedModel => {
+		const source = raw[index]!;
+		const components = COMPONENTS.map((name): UtilityComponent => {
+			const component = source.components[name];
+			const comparable = raw.map((item) => item.components[name].value).filter((item): item is number => item !== null);
+			return {
+				name,
+				score: component.value === null ? null : normalizedScore(component.value, comparable, component.lowerIsBetter),
+				confidence: component.confidence,
+				weight: effectiveWeights[name],
+				evidenceCount: component.evidenceCount,
+				reason: component.reason,
+			};
+		});
+		const known = components.filter((component): component is UtilityComponent & { score: number } => component.score !== null && component.weight > 0);
+		const knownWeight = known.reduce((sum, component) => sum + component.weight, 0);
+		const totalWeight = components.reduce((sum, component) => sum + component.weight, 0);
+		const utility = knownWeight === 0 ? null : known.reduce((sum, component) => sum + (component.score * component.weight), 0) / knownWeight;
+		const confidence = totalWeight === 0 ? 0 : known.reduce((sum, component) => sum + (component.confidence * component.weight), 0) / totalWeight;
+		const provenance = [...new Map(source.provenance.map((item) => [`${item.sourceId}:${item.revision}:${item.url}`, item])).values()]
+			.sort((left, right) => left.sourceId.localeCompare(right.sourceId) || left.revision.localeCompare(right.revision));
+		return {
+			candidate,
+			identity: candidateIdentity(candidate),
+			utility,
+			confidence,
+			components,
+			provenance,
+			trace: [`domain ${value.domain}, type ${value.type}`, `budget pressure ${budgetPressure.toFixed(3)} makes cost weight ${effectiveWeights.cost.toFixed(3)}`, `${known.length}/${components.length} utility components have evidence`, `scope authority ${value.scopeAuthority}`],
+		};
+	}).sort((left, right) => (right.utility ?? -1) - (left.utility ?? -1) || right.confidence - left.confidence || left.identity.localeCompare(right.identity));
+	const knownComponents = ranked.reduce((sum, item) => sum + item.components.filter((component) => component.score !== null).length, 0);
+	const possibleComponents = ranked.length * COMPONENTS.length;
+	const completeness = knownComponents === 0 ? "insufficient-evidence" : knownComponents === possibleComponents ? "complete" : "partial";
+	const exact = value.scopeAuthority === "exact-session";
+	return {
+		scopeAuthority: value.scopeAuthority,
+		scopeWarning: exact ? null : "Pi available models are not the exact session scope; automatic selection is disabled",
+		domain: value.domain,
+		type: value.type,
+		completeness,
+		ranked,
+		automaticSelection: exact && ranked[0]?.utility !== null ? ranked[0]!.candidate : null,
+	};
+}