@danypops/jittor 0.5.1 → 0.7.0

package/src/client.ts

@@ -1,51 +1,19 @@
+import { AuthenticatedRpcClient, type FetchTransport } from "@danypops/daemon-kit/rpc-client";
 import type { OperationInputs, OperationName, OperationOutputs } from "./service.ts";
 import { ensureAuthToken, readDaemonHandle, resolveJittorPaths, type JittorPaths } from "./state.ts";
 
-export type FetchTransport = (request: Request) => Promise<Response>;
+export type { FetchTransport };
 
-export class JittorClient {
-	constructor(
-		private readonly baseUrl: string,
-		private readonly token: string,
-		private readonly transport: FetchTransport = fetch,
-	) {}
-
-	async call<Name extends OperationName>(operation: Name, input: OperationInputs[Name]): Promise<OperationOutputs[Name]> {
-		const response = await this.transport(new Request(`${this.baseUrl}/api/v1/ops`, {
-			method: "POST",
-			headers: { authorization: `Bearer ${this.token}`, "content-type": "application/json" },
-			body: JSON.stringify({ op: operation, input }),
-		}));
-		const body = await response.json() as { result?: OperationOutputs[Name]; error?: string };
-		if (!response.ok) throw new Error(body.error ?? `Jittor operation failed with HTTP ${response.status}`);
-		return body.result as OperationOutputs[Name];
-	}
-
-	async operations(): Promise<OperationName[]> {
-		const response = await this.transport(new Request(`${this.baseUrl}/api/v1/ops`, {
-			headers: { authorization: `Bearer ${this.token}` },
-		}));
-		const body = await response.json() as { operations?: OperationName[]; error?: string };
-		if (!response.ok) throw new Error(body.error ?? `Jittor discovery failed with HTTP ${response.status}`);
-		return body.operations ?? [];
-	}
-
-	async ready(): Promise<boolean> {
-		const response = await this.transport(new Request(`${this.baseUrl}/ready`, {
-			headers: { authorization: `Bearer ${this.token}` },
-		}));
-		if (response.status === 503) return false;
-		if (!response.ok) throw new Error(`Jittor readiness check failed with HTTP ${response.status}`);
-		return true;
-	}
-
-	async health(): Promise<{ ok: true; version: string }> {
-		const response = await this.transport(new Request(`${this.baseUrl}/health`, {
-			headers: { authorization: `Bearer ${this.token}` },
-		}));
-		const body = await response.json() as { ok?: boolean; version?: string; error?: string };
-		if (!response.ok || body.ok !== true || typeof body.version !== "string") throw new Error(body.error ?? "Jittor health check failed");
-		return { ok: true, version: body.version };
+/**
+ * Jittor's typed authenticated RPC client, now a thin named subclass of
+ * `@danypops/daemon-kit/rpc-client`'s `AuthenticatedRpcClient` -- the shared substrate factored
+ * out after jittor's own client.ts and web-spider-daemon's were found byte-identical (see
+ * daemon-kit's README). Keeps the old 3-positional-argument constructor so every existing call
+ * site is untouched by this migration.
+ */
+export class JittorClient extends AuthenticatedRpcClient<OperationName, OperationInputs, OperationOutputs> {
+	constructor(baseUrl: string, token: string, transport: FetchTransport = fetch) {
+		super(baseUrl, token, { label: "Jittor", transport });
 	}
 }
 

package/src/constants.ts

@@ -1,8 +1,33 @@
-export const SQLITE_SCHEMA_VERSION = 1;
 export const SQLITE_BUSY_TIMEOUT_MS = 5_000;
 export const DEFAULT_QUERY_LIMIT = 1_000;
 export const MAX_QUERY_LIMIT = 10_000;
 export const SERVICE_MAX_BODY_BYTES = 1_048_576;
+export const SERVICE_MAX_RESPONSE_BYTES = 4_194_304;
+export const METRIC_IDENTITY_MAX_CHARACTERS = 160;
+export const METRIC_ATTRIBUTES_MAX_SERIALIZED_CHARACTERS = 16_384;
+export const METRIC_ATTRIBUTES_MAX_DEPTH = 12;
+export const BENCHMARK_IDENTITY_MAX_CHARACTERS = 160;
+export const BENCHMARK_MAX_TEXT_CHARACTERS = 2_048;
+export const BENCHMARK_MAX_MODELS_PER_SOURCE = 250;
+export const BENCHMARK_MAX_OBSERVATIONS_PER_SNAPSHOT = 2_000;
+export const BENCHMARK_STORE_QUERY_LIMIT = (BENCHMARK_MAX_OBSERVATIONS_PER_SNAPSHOT * 2) + 1;
+export const BENCHMARK_DEFAULT_QUERY_LIMIT = 100;
+export const BENCHMARK_TUI_MAX_CANDIDATES = 20;
+export const BENCHMARK_TUI_MAX_PROVENANCE_PER_CANDIDATE = 2;
+export const BENCHMARK_MAX_QUERY_LIMIT = 500;
+export const BENCHMARK_SOURCE_MAX_RESPONSE_BYTES = 2_097_152;
+export const BENCHMARK_SOURCE_MAX_TOTAL_RESPONSE_BYTES = 6_291_456;
+export const BENCHMARK_REFRESH_INTERVAL_MS = 24 * 60 * 60 * 1_000;
+export const MODEL_OBSERVATION_IDENTITY_MAX_CHARACTERS = 160;
+export const MODEL_AGGREGATE_MAX_ROWS = 10_000;
+export const MODEL_AGGREGATE_MAX_GROUPS = 500;
+export const MODEL_RANKING_MAX_SOURCES = 4;
+export const MODEL_RANKING_DEFAULT_QUALITY_WEIGHT = 3;
+export const MODEL_RANKING_DEFAULT_COST_WEIGHT = 2;
+export const MODEL_RANKING_DEFAULT_LATENCY_WEIGHT = 1;
+export const MODEL_RANKING_DEFAULT_CONTEXT_WEIGHT = 1;
+export const MODEL_RANKING_DEFAULT_RELIABILITY_WEIGHT = 2;
+export const MODEL_OBSERVATION_FRESH_MS = 7 * 24 * 60 * 60 * 1_000;
 export const MAINTENANCE_INTERVAL_MS = 15 * 60 * 1_000;
 export const TELEMETRY_POLL_INTERVAL_MS = 60_000;
 export const TELEMETRY_STALE_AFTER_MS = 120_000;
@@ -12,20 +37,28 @@ export const FOOTER_CONTEXT_ERROR_FRACTION = 0.9;
 export const FOOTER_BAR_MIN_WIDTH = 4;
 export const FOOTER_BAR_MAX_WIDTH = 8;
 export const FOOTER_WIDE_TERMINAL_WIDTH = 100;
-export const FOOTER_COMPACTION_RENDER_INTERVAL_MS = 1_000;
-export const FOOTER_COMPACTION_DRAIN_STEP_MS = 3_000;
+export const FOOTER_COMPACTION_RENDER_INTERVAL_MS = 500;
+/** Half-period of the compacting liveness indicator; equal to the render tick so it visibly alternates every repaint. */
+export const FOOTER_COMPACTION_BLINK_HALF_PERIOD_MS = 500;
 export const MILLISECONDS_PER_SECOND = 1_000;
 export const MILLISECONDS_PER_MINUTE = 60 * MILLISECONDS_PER_SECOND;
 export const MILLISECONDS_PER_HOUR = 60 * MILLISECONDS_PER_MINUTE;
 export const PAPYRUS_CONTEXT_INJECTION_CHANNEL = "papyrus.context-injection.v1";
 export const PAPYRUS_CONTEXT_INJECTION_SCHEMA = "papyrus.context-injection/v1";
+/** Matches Papyrus's own constants by convention; Jittor does not depend on the Papyrus package. */
+export const PAPYRUS_TASK_FOCUS_CHANNEL = "papyrus.task-focus.v1";
+export const PAPYRUS_TASK_FOCUS_SCHEMA = "papyrus.task-focus/v1";
+export const TASK_FOCUS_EVENT_MAX_AGE_MS = 5 * MILLISECONDS_PER_MINUTE;
+export const TASK_FOCUS_ID_MAX_LENGTH = 200;
+export const TASK_COST_QUERY_LIMIT = 10_000;
+/** A `metrics prune --before` cutoff newer than this must pass `force: true`. Guards against accidentally wiping recent/live data with a too-recent cutoff (e.g. "now"), while still allowing routine cleanup of genuinely old rows without ceremony. */
+export const PRUNE_MIN_AGE_MS = 24 * MILLISECONDS_PER_HOUR;
 export const CONTEXT_OBSERVATION_MAX_CHARACTERS = 10_000_000;
 export const CONTEXT_OBSERVATION_MAX_AGE_MS = 5 * MILLISECONDS_PER_MINUTE;
 export const CONTEXT_ASSESSMENT_QUERY_LIMIT = 10_000;
 export const CONTEXT_EVENT_DEDUP_LIMIT = 1_000;
 export const CONTEXT_ASSESSMENT_DEFAULT_WINDOW_MS = 24 * MILLISECONDS_PER_HOUR;
 export const MILLISECONDS_PER_DAY = 24 * MILLISECONDS_PER_HOUR;
-export const LOOPBACK_HOST = "127.0.0.1";
 export const JITTOR_STATE_DIRECTORY = "jittor";
 export const JITTOR_EXTENSION_SETTINGS_FILENAME = "extension.json";
 export const DATABASE_FILENAME = "jittor.db";
@@ -34,8 +67,29 @@ export const HANDLE_FILENAME = "daemon.json";
 export const SYSTEMD_UNIT_NAME = "jittor.service";
 export const USAGE_CHART_HEIGHT = 8;
 export const USAGE_Y_AXIS_WIDTH = 7;
-export const USAGE_TOKEN_QUERY_LIMIT = 10_000;
+/**
+ * A single flat "most recent N rows" query lets one heavy provider/model monopolize the entire
+ * budget within the query window, silently starving every other series out of the chart no matter
+ * which time frame is selected (a real bug: a single long, heavy session can fill 10k rows within
+ * a few hours, hiding a whole other provider's usage from a day earlier even in the Monthly view).
+ * The usage/cost dashboard instead fetches per distinct scope (see distinctScopes), bounded by
+ * these two limits; the worst-case total row volume (40 * 250 = 10,000) matches the old flat cap,
+ * but is now fairly distributed across every active series instead of claimable by just one.
+ */
+export const USAGE_MAX_DISTINCT_SCOPES = 40;
+export const USAGE_PER_SCOPE_QUERY_LIMIT = 250;
+export const USAGE_RENDER_MAX_SERIES = 20;
+export const HUMAN_STATUS_MAX_SOURCES = 20;
+export const HUMAN_TEXT_FIELD_MAX_CHARACTERS = 160;
+export const CLI_METRICS_HUMAN_MAX_ROWS = 50;
+export const CLI_AVAILABLE_ROUTES_MAX = 200;
+/** Bounded rolling window for the compaction duration estimator; older samples are never fetched. */
+export const COMPACTION_DURATION_ESTIMATE_MAX_SAMPLES = 20;
+/** Below this many samples the estimate stays explicit cold-start uncertainty rather than a guess. */
+export const COMPACTION_DURATION_ESTIMATE_MIN_SAMPLES = 3;
 export const MAX_USAGE_BUCKETS = 120;
+/** Defense-in-depth cap on the SQL-side usage aggregation result: (scopes x metrics x buckets) is already small by construction, but this bounds it explicitly rather than trusting that alone. */
+export const USAGE_AGGREGATE_MAX_ROWS = 25_000;
 export const MAX_DYNAMIC_ROUTES = 100;
 export const CODEX_ERROR_MESSAGE_LIMIT = 160;
 export const CODEX_RETRY_AFTER_MAX_MS = 5 * MILLISECONDS_PER_MINUTE;
@@ -44,3 +98,13 @@ export const CODEX_RECOVERY_MAX_DELAY_MS = CODEX_RETRY_AFTER_MAX_MS;
 export const CODEX_RECOVERY_MAX_ATTEMPTS = 3;
 export const CODEX_RECOVERY_ATTEMPT_WINDOW_MS = 10 * MILLISECONDS_PER_MINUTE;
 export const CODEX_RECOVERY_JITTER_RATIO = 0.2;
+export const GOOGLE_VERTEX_BUDGET_DISPLAY_NAME_MAX_CHARACTERS = 160;
+/** Bounded per-poll pull size; a budget subscription realistically holds at most a few pending notifications. */
+export const GOOGLE_VERTEX_BUDGET_MAX_MESSAGES_PER_PULL = 20;
+/**
+ * Lower than Codex's header-derived 0.8: this is Google's own documented "estimated ... subject to
+ * change until your invoice is finalized" data, delivered at-least-once and possibly out of order,
+ * multiple times per day rather than on every response.
+ */
+export const GOOGLE_VERTEX_BUDGET_CONFIDENCE = 0.6;
+export const GOOGLE_ADC_TOKEN_REFRESH_SKEW_MS = 60_000;

package/src/daemon.ts

@@ -1,23 +1,35 @@
-import { LOOPBACK_HOST, MAINTENANCE_INTERVAL_MS, TELEMETRY_POLL_INTERVAL_MS } from "./constants.ts";
+import { startDaemon as startDaemonKit, type RunningDaemon } from "@danypops/daemon-kit/daemon";
+import { MAINTENANCE_INTERVAL_MS, TELEMETRY_POLL_INTERVAL_MS } from "./constants.ts";
 import { DEFAULT_POLICY, UNCONFIGURED_ROUTE } from "./config.ts";
 import { SQLiteMetricStore } from "./adapters/sqlite-metric-store.ts";
+import { MetricBenchmarkStore } from "./adapters/metric-benchmark-store.ts";
+import { OpenRouterBenchmarkIndexSource } from "./adapters/openrouter-benchmark-index-source.ts";
+import { OpenRouterBenchmarkSource } from "./adapters/openrouter-benchmark-source.ts";
 import { openJittorDb } from "./db.ts";
+import { BenchmarkCatalog } from "./domain/benchmark.ts";
+import { EvidenceModelRanker } from "./domain/model-ranking-service.ts";
 import { createApp, JittorService } from "./service.ts";
 import { JittorRouter } from "./router.ts";
+import type { BenchmarkSource } from "./ports/benchmark-source.ts";
 import type { TelemetrySource } from "./ports/telemetry-source.ts";
-import { CodexTelemetrySource, OpenRouterTelemetrySource } from "./providers/telemetry-sources.ts";
-import {
-	ensureAuthToken,
-	removeDaemonHandle,
-	resolveJittorPaths,
-	writeDaemonHandle,
-	type JittorPaths,
-} from "./state.ts";
+import { CodexTelemetrySource, GoogleVertexBudgetTelemetrySource, OpenRouterTelemetrySource } from "./providers/telemetry-sources.ts";
+import { createGoogleAdcTokenProvider } from "./providers/google-adc-auth.ts";
+import { GOOGLE_PUBSUB_READONLY_SCOPE } from "./providers/google-vertex-budget.ts";
+import type { GoogleVertexMetricSource } from "./providers/google-vertex-contracts.ts";
+import { ensureAuthToken, resolveJittorPaths, type JittorPaths } from "./state.ts";
+import { logEvent, logger } from "./log.ts";
 
-export interface RunningDaemon {
-	host: typeof LOOPBACK_HOST;
-	port: number;
-	stop(): Promise<void>;
+export type { RunningDaemon } from "@danypops/daemon-kit/daemon";
+
+export function reportMaintenanceFailure(event: string, error: unknown): void {
+	logEvent("error", event, { message: error instanceof Error ? error.message : String(error) });
+}
+
+export function benchmarkSourcesFromEnvironment(env: Record<string, string | undefined> = process.env): BenchmarkSource[] {
+	if (env["JITTOR_OPENROUTER_BENCHMARKS"] !== "1") return [];
+	const sources: BenchmarkSource[] = [new OpenRouterBenchmarkSource()];
+	if (env["OPENROUTER_API_KEY"]) sources.push(new OpenRouterBenchmarkIndexSource(env["OPENROUTER_API_KEY"]));
+	return sources;
 }
 
 export function telemetrySourcesFromEnvironment(env: Record<string, string | undefined> = process.env): TelemetrySource[] {
@@ -26,9 +38,27 @@ export function telemetrySourcesFromEnvironment(env: Record<string, string | und
 	if (codexAuthFile) sources.push(new CodexTelemetrySource(codexAuthFile));
 	const openRouterKey = env["OPENROUTER_API_KEY"];
 	if (openRouterKey) sources.push(new OpenRouterTelemetrySource(openRouterKey));
+	// Opt-in only: the Pub/Sub subscription is one-time GCP console/CLI setup outside Jittor (see
+	// docs/PROVIDER_RESEARCH.md), so its absence must never attempt ADC discovery or a network call.
+	const vertexBudgetSubscription = env["JITTOR_GOOGLE_VERTEX_BUDGET_SUBSCRIPTION"];
+	if (vertexBudgetSubscription) {
+		const source = (env["JITTOR_GOOGLE_VERTEX_BUDGET_SOURCE"] ?? "google-vertex") as GoogleVertexMetricSource;
+		const tokenProvider = createGoogleAdcTokenProvider([GOOGLE_PUBSUB_READONLY_SCOPE]);
+		sources.push(new GoogleVertexBudgetTelemetrySource(vertexBudgetSubscription, tokenProvider, Date.now, fetch, source));
+	}
 	return sources;
 }
 
+/**
+ * Composition root, now built on `@danypops/daemon-kit/daemon`'s `startDaemon` for binding,
+ * atomic handle write, maintenance-timer driving, and clean shutdown -- the skeleton that used to
+ * be hand-rolled here (and, byte-identically, in web-spider-daemon's and papyrus's daemon.ts; see
+ * daemon-kit's README). Each maintenance task still catches and classifies its own failure via
+ * `reportMaintenanceFailure` (preserving Jittor's specific `checkpoint_failed`/
+ * `benchmark_refresh_failed`/`telemetry_poll_failed` event taxonomy) rather than relying on
+ * daemon-kit's own generic "maintenance task failed: <name>" catch, which exists as a safety net
+ * for tasks that don't self-classify, not to replace a consumer's own richer classification.
+ */
 export function startDaemon(
 	paths: JittorPaths = resolveJittorPaths(),
 	env: Record<string, string | undefined> = process.env,
@@ -36,6 +66,10 @@ export function startDaemon(
 	const token = ensureAuthToken(paths);
 	const metrics = new SQLiteMetricStore(openJittorDb(paths.database));
 	const sources = telemetrySourcesFromEnvironment(env);
+	const benchmarkSources = benchmarkSourcesFromEnvironment(env);
+	const benchmarkStore = new MetricBenchmarkStore(metrics);
+	const benchmarks = new BenchmarkCatalog(benchmarkStore, benchmarkSources);
+	const modelRanker = new EvidenceModelRanker(benchmarkStore, metrics);
 	const router = new JittorRouter({
 		metrics,
 		sources,
@@ -43,37 +77,25 @@ export function startDaemon(
 		routes: [],
 		currentRoute: UNCONFIGURED_ROUTE,
 	});
-	const service = new JittorService(metrics, router);
-	const app = createApp({ service, token });
-	const server = Bun.serve({
-		hostname: LOOPBACK_HOST,
-		port: 0,
-		fetch: (request) => app.fetch(request),
+	const service = new JittorService(metrics, router, benchmarks, modelRanker);
+
+	const daemon = startDaemonKit({
+		daemonLabel: "Jittor",
+		handlePath: paths.handle,
+		logger,
+		buildApp: () => createApp({ service, token }),
+		maintenanceTasks: [
+			{ name: "checkpoint", intervalMs: MAINTENANCE_INTERVAL_MS, run: async () => { await service.execute("service.checkpoint", {}).catch((error) => reportMaintenanceFailure("checkpoint_failed", error)); } },
+			{ name: "benchmark-refresh", intervalMs: MAINTENANCE_INTERVAL_MS, run: async () => { await benchmarks.refresh().catch((error) => reportMaintenanceFailure("benchmark_refresh_failed", error)); } },
+			{ name: "telemetry-poll", intervalMs: TELEMETRY_POLL_INTERVAL_MS, run: async () => { await router.poll().catch((error) => reportMaintenanceFailure("telemetry_poll_failed", error)); } },
+		],
+		onShutdown: () => { service.close(); },
 	});
-	const port = server.port;
-	if (port === undefined) {
-		server.stop(true);
-		service.close();
-		throw new Error("Jittor daemon failed to bind a loopback port");
-	}
-	writeDaemonHandle(paths, { host: LOOPBACK_HOST, port, pid: process.pid });
-	const maintenance = setInterval(() => { void service.execute("service.checkpoint", {}); }, MAINTENANCE_INTERVAL_MS);
-	const poll = setInterval(() => { void router.poll(); }, TELEMETRY_POLL_INTERVAL_MS);
-	if (sources.length > 0) void router.poll();
-	let stopped = false;
-	return {
-		host: LOOPBACK_HOST,
-		port,
-		async stop(): Promise<void> {
-			if (stopped) return;
-			stopped = true;
-			clearInterval(maintenance);
-			clearInterval(poll);
-			await server.stop(true);
-			service.close();
-			removeDaemonHandle(paths);
-		},
-	};
+
+	if (sources.length > 0) router.poll().catch((error) => reportMaintenanceFailure("telemetry_poll_failed", error));
+	if (benchmarkSources.length > 0) benchmarks.refresh().catch((error) => reportMaintenanceFailure("benchmark_refresh_failed", error));
+
+	return daemon;
 }
 
 export function serveMain(): void {

package/src/db.ts

@@ -1,7 +1,6 @@
-import { Database } from "bun:sqlite";
-import { dirname } from "node:path";
-import { mkdirSync } from "node:fs";
-import { SQLITE_BUSY_TIMEOUT_MS, SQLITE_SCHEMA_VERSION } from "./constants.ts";
+import type { Database } from "bun:sqlite";
+import { openSqliteWithPragmas } from "@danypops/daemon-kit/storage";
+import { SQLITE_BUSY_TIMEOUT_MS } from "./constants.ts";
 
 const INITIAL_SCHEMA = `
 CREATE TABLE metric_observations (
@@ -20,31 +19,15 @@ CREATE INDEX metric_observations_time_idx
 	ON metric_observations(observed_at);
 `;
 
-function migrate(db: Database): void {
-	const row = db.query("PRAGMA user_version").get() as { user_version: number };
-	if (row.user_version > SQLITE_SCHEMA_VERSION) {
-		throw new Error(`database schema ${row.user_version} is newer than supported ${SQLITE_SCHEMA_VERSION}`);
-	}
-	if (row.user_version < 1) {
-		const migration = db.transaction(() => {
-			db.exec(INITIAL_SCHEMA);
-			db.exec("PRAGMA user_version = 1");
-		});
-		migration.immediate();
-	}
-	const migrated = db.query("PRAGMA user_version").get() as { user_version: number };
-	if (migrated.user_version !== SQLITE_SCHEMA_VERSION) {
-		throw new Error(`missing migration from schema ${migrated.user_version} to ${SQLITE_SCHEMA_VERSION}`);
-	}
-}
-
+/**
+ * Delegates bootstrap (pragmas, migration engine) to `@danypops/daemon-kit/storage`, which
+ * generalizes the byte-identical pragma/PRAGMA-user_version skeleton jittor's own db.ts used to
+ * hand-roll (see daemon-kit's README). Jittor's only remaining responsibility is its own schema.
+ */
 export function openJittorDb(path: string): Database {
-	if (path !== ":memory:") mkdirSync(dirname(path), { recursive: true });
-	const db = new Database(path, { create: true, strict: true });
-	db.exec("PRAGMA foreign_keys = ON");
-	db.exec(`PRAGMA busy_timeout = ${SQLITE_BUSY_TIMEOUT_MS}`);
-	if (path !== ":memory:") db.exec("PRAGMA journal_mode = WAL");
-	migrate(db);
-	db.exec("PRAGMA optimize=0x10002");
-	return db;
+	return openSqliteWithPragmas(path, {
+		databaseOptions: { create: true, strict: true },
+		busyTimeoutMs: SQLITE_BUSY_TIMEOUT_MS,
+		migrations: [{ version: 1, up: (db) => db.exec(INITIAL_SCHEMA) }],
+	});
 }

package/src/domain/benchmark.ts

@@ -0,0 +1,264 @@
+import {
+	BENCHMARK_DEFAULT_QUERY_LIMIT,
+	BENCHMARK_IDENTITY_MAX_CHARACTERS,
+	BENCHMARK_MAX_OBSERVATIONS_PER_SNAPSHOT,
+	BENCHMARK_MAX_QUERY_LIMIT,
+	BENCHMARK_MAX_TEXT_CHARACTERS,
+	BENCHMARK_REFRESH_INTERVAL_MS,
+} from "../constants.ts";
+import { METRIC_UNITS, type MetricUnit } from "./metric.ts";
+import type { BenchmarkController } from "../ports/benchmark-controller.ts";
+import type { BenchmarkSource as BenchmarkSourcePort } from "../ports/benchmark-source.ts";
+import type { BenchmarkStore } from "../ports/benchmark-store.ts";
+
+export type BenchmarkSourceType = "creator" | "marketplace" | "independent" | "operational" | "preference" | "local";
+
+export interface ModelIdentity {
+	provider: string;
+	model: string;
+	version: string | null;
+	canonical: string;
+	aliases: string[];
+}
+
+export interface BenchmarkProvenance {
+	sourceId: string;
+	sourceType: BenchmarkSourceType;
+	publisher: string;
+	url: string;
+	revision: string;
+	publishedAt: number | null;
+	retrievedAt: number;
+	freshUntil: number;
+	license: string;
+	confidence: number;
+}
+
+export interface BenchmarkObservation {
+	model: ModelIdentity;
+	dimension: string;
+	value: number;
+	unit: MetricUnit;
+	provenance: BenchmarkProvenance;
+	methodology: Record<string, string | number | boolean | null | string[]>;
+}
+
+export interface BenchmarkSourceSnapshot {
+	sourceId: string;
+	snapshotId: string;
+	retrievedAt: number;
+	observations: BenchmarkObservation[];
+}
+
+export interface BenchmarkSnapshot extends BenchmarkSourceSnapshot {
+	publishedAt: number;
+}
+
+export interface BenchmarkSourceStatus {
+	id: string;
+	ok: boolean | null;
+	hasEvidence: boolean;
+	lastAttemptAt: number | null;
+	lastSuccessAt: number | null;
+	observations: number;
+	error?: "source refresh failed";
+}
+
+export interface BenchmarkRefreshResult {
+	observedAt: number;
+	sources: BenchmarkSourceStatus[];
+}
+
+export interface BenchmarkQuery {
+	sourceId: string;
+	model?: string;
+	dimension?: string;
+	limit?: number;
+}
+
+export interface BenchmarkQueryResult extends BenchmarkSnapshot {
+	completeness: "complete" | "truncated";
+	freshness: "fresh" | "stale";
+	freshUntil: number;
+}
+
+export interface BenchmarkCatalogOptions {
+	clock?: () => number;
+	refreshIntervalMs?: number;
+}
+
+export type BenchmarkSource = BenchmarkSourcePort;
+
+const VERSION_SUFFIX = /-(\d{4}-\d{2}-\d{2})$/;
+const SOURCE_TYPES = new Set<BenchmarkSourceType>(["creator", "marketplace", "independent", "operational", "preference", "local"]);
+
+function boundedText(value: unknown, name: string, maximum = BENCHMARK_MAX_TEXT_CHARACTERS): string {
+	if (typeof value !== "string" || value.trim().length === 0) throw new Error(`${name} is required`);
+	const normalized = value.trim();
+	if (normalized.length > maximum) throw new Error(`${name} exceeds the length limit`);
+	if (/\p{Cc}/u.test(normalized)) throw new Error(`${name} contains control characters`);
+	return normalized;
+}
+
+function identityPart(value: string, name: string, allowPath = false): string {
+	const normalized = boundedText(value, name, BENCHMARK_IDENTITY_MAX_CHARACTERS).toLowerCase();
+	const pattern = allowPath ? /^[a-z0-9][a-z0-9._:+/-]*$/ : /^[a-z0-9][a-z0-9._:+-]*$/;
+	if (!pattern.test(normalized) || normalized.includes("//")) throw new Error(`${name} is invalid`);
+	return normalized;
+}
+
+export function normalizeModelIdentity(provider: string, model: string, aliases: string[] = []): ModelIdentity {
+	const normalizedProvider = identityPart(provider, "provider");
+	const normalizedModel = identityPart(model, "model", true);
+	const version = VERSION_SUFFIX.exec(normalizedModel)?.[1] ?? null;
+	const canonical = `${normalizedProvider}/${normalizedModel}`;
+	const normalizedAliases = [...new Set(aliases.map((alias) => boundedText(alias, "alias", BENCHMARK_IDENTITY_MAX_CHARACTERS).toLowerCase()))]
+		.filter((alias) => alias !== canonical)
+		.sort();
+	return { provider: normalizedProvider, model: normalizedModel, version, canonical, aliases: normalizedAliases };
+}
+
+function validateIdentity(value: unknown): ModelIdentity {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("model identity is required");
+	const input = value as Record<string, unknown>;
+	if (!Array.isArray(input["aliases"]) || !input["aliases"].every((alias) => typeof alias === "string")) throw new Error("model aliases are invalid");
+	const normalized = normalizeModelIdentity(String(input["provider"] ?? ""), String(input["model"] ?? ""), input["aliases"] as string[]);
+	if (input["canonical"] !== normalized.canonical || input["version"] !== normalized.version) throw new Error("model identity is not normalized");
+	return normalized;
+}
+
+function validateTimestamp(value: unknown, name: string, nullable = false): number | null {
+	if (nullable && value === null) return null;
+	if (!Number.isSafeInteger(value) || (value as number) <= 0) throw new Error(`${name} must be a positive integer timestamp`);
+	return value as number;
+}
+
+function validateProvenance(value: unknown): BenchmarkProvenance {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("provenance is required");
+	const input = value as Record<string, unknown>;
+	const sourceId = identityPart(String(input["sourceId"] ?? ""), "source id");
+	if (!SOURCE_TYPES.has(input["sourceType"] as BenchmarkSourceType)) throw new Error("source type is invalid");
+	let url: URL;
+	try { url = new URL(boundedText(input["url"], "source URL")); } catch { throw new Error("source URL is invalid"); }
+	if (url.protocol !== "https:") throw new Error("source URL must use HTTPS");
+	const confidence = input["confidence"];
+	if (typeof confidence !== "number" || !Number.isFinite(confidence) || confidence < 0 || confidence > 1) throw new Error("confidence must be between zero and one");
+	const retrievedAt = validateTimestamp(input["retrievedAt"], "retrieval time") as number;
+	const freshUntil = validateTimestamp(input["freshUntil"], "freshness deadline") as number;
+	if (freshUntil < retrievedAt) throw new Error("freshness deadline precedes retrieval");
+	return {
+		sourceId,
+		sourceType: input["sourceType"] as BenchmarkSourceType,
+		publisher: boundedText(input["publisher"], "publisher"),
+		url: url.toString(),
+		revision: boundedText(input["revision"], "revision"),
+		publishedAt: validateTimestamp(input["publishedAt"], "publication time", true),
+		retrievedAt,
+		freshUntil,
+		license: boundedText(input["license"], "license"),
+		confidence,
+	};
+}
+
+function validateMethodology(value: unknown): BenchmarkObservation["methodology"] {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("methodology is required");
+	const serialized = JSON.stringify(value);
+	if (serialized.length > BENCHMARK_MAX_TEXT_CHARACTERS) throw new Error("methodology exceeds the size limit");
+	return structuredClone(value as BenchmarkObservation["methodology"]);
+}
+
+export function validateBenchmarkObservation(value: unknown): BenchmarkObservation {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("benchmark observation must be an object");
+	const input = value as Record<string, unknown>;
+	const numericValue = input["value"];
+	if (typeof numericValue !== "number" || !Number.isFinite(numericValue)) throw new Error("benchmark value must be finite");
+	if (!METRIC_UNITS.includes(input["unit"] as MetricUnit)) throw new Error("benchmark unit is not supported");
+	return {
+		model: validateIdentity(input["model"]),
+		dimension: identityPart(String(input["dimension"] ?? ""), "dimension"),
+		value: numericValue,
+		unit: input["unit"] as MetricUnit,
+		provenance: validateProvenance(input["provenance"]),
+		methodology: validateMethodology(input["methodology"]),
+	};
+}
+
+function validateSourceSnapshot(value: BenchmarkSourceSnapshot, expectedSourceId: string): BenchmarkSourceSnapshot {
+	const sourceId = identityPart(value.sourceId, "source id");
+	if (sourceId !== expectedSourceId) throw new Error("source snapshot identity mismatch");
+	const snapshotId = boundedText(value.snapshotId, "snapshot id", BENCHMARK_IDENTITY_MAX_CHARACTERS);
+	const retrievedAt = validateTimestamp(value.retrievedAt, "retrieval time") as number;
+	if (!Array.isArray(value.observations) || value.observations.length > BENCHMARK_MAX_OBSERVATIONS_PER_SNAPSHOT) throw new Error("source snapshot exceeds the observation limit");
+	const observations = value.observations.map(validateBenchmarkObservation);
+	if (observations.some((observation) => observation.provenance.sourceId !== sourceId || observation.provenance.retrievedAt !== retrievedAt)) {
+		throw new Error("source snapshot provenance mismatch");
+	}
+	return { sourceId, snapshotId, retrievedAt, observations };
+}
+
+export class BenchmarkCatalog implements BenchmarkController {
+	private readonly clock: () => number;
+	private readonly refreshIntervalMs: number;
+	private readonly states = new Map<string, BenchmarkSourceStatus>();
+
+	constructor(
+		private readonly store: BenchmarkStore,
+		private readonly sources: BenchmarkSource[],
+		options: BenchmarkCatalogOptions = {},
+	) {
+		this.clock = options.clock ?? Date.now;
+		this.refreshIntervalMs = options.refreshIntervalMs ?? BENCHMARK_REFRESH_INTERVAL_MS;
+		for (const source of sources) {
+			const evidence = store.latest(source.id);
+			this.states.set(source.id, {
+				id: source.id,
+				ok: null,
+				hasEvidence: evidence !== null,
+				lastAttemptAt: null,
+				lastSuccessAt: evidence?.retrievedAt ?? null,
+				observations: evidence?.observations.length ?? 0,
+			});
+		}
+	}
+
+	async refresh(force = false): Promise<BenchmarkRefreshResult> {
+		const now = this.clock();
+		await Promise.all(this.sources.map(async (source) => {
+			const prior = this.states.get(source.id)!;
+			if (!force && prior.lastAttemptAt !== null && now - prior.lastAttemptAt < this.refreshIntervalMs) return;
+			this.states.set(source.id, { ...prior, lastAttemptAt: now });
+			try {
+				const snapshot = validateSourceSnapshot(await source.fetch(), source.id);
+				const published = this.store.publish(snapshot.sourceId, snapshot.snapshotId, snapshot.observations);
+				this.states.set(source.id, { id: source.id, ok: true, hasEvidence: true, lastAttemptAt: now, lastSuccessAt: published.retrievedAt, observations: published.observations.length });
+			} catch {
+				const evidence = this.store.latest(source.id);
+				this.states.set(source.id, { id: source.id, ok: false, hasEvidence: evidence !== null, lastAttemptAt: now, lastSuccessAt: evidence?.retrievedAt ?? prior.lastSuccessAt, observations: evidence?.observations.length ?? prior.observations, error: "source refresh failed" });
+			}
+		}));
+		return { observedAt: now, sources: this.status().sources };
+	}
+
+	status(): BenchmarkRefreshResult {
+		return { observedAt: this.clock(), sources: this.sources.map((source) => structuredClone(this.states.get(source.id)!)) };
+	}
+
+	query(input: BenchmarkQuery): BenchmarkQueryResult {
+		const sourceId = identityPart(input.sourceId, "source id");
+		const snapshot = this.store.latest(sourceId);
+		if (!snapshot) throw new Error("benchmark evidence is not available for the source");
+		const requestedLimit = Number.isFinite(input.limit) ? Math.floor(input.limit!) : BENCHMARK_DEFAULT_QUERY_LIMIT;
+		const limit = Math.max(1, Math.min(BENCHMARK_MAX_QUERY_LIMIT, requestedLimit));
+		const model = input.model?.trim().toLowerCase();
+		const dimension = input.dimension?.trim().toLowerCase();
+		const matched = snapshot.observations.filter((observation) => (!model || observation.model.canonical === model || observation.model.aliases.includes(model)) && (!dimension || observation.dimension === dimension));
+		const freshUntil = Math.min(...snapshot.observations.map((observation) => observation.provenance.freshUntil));
+		return {
+			...structuredClone(snapshot),
+			observations: structuredClone(matched.slice(0, limit)),
+			completeness: matched.length > limit ? "truncated" : "complete",
+			freshness: this.clock() <= freshUntil ? "fresh" : "stale",
+			freshUntil,
+		};
+	}
+}