@danypops/jittor 0.16.2 → 0.17.0

package/src/sqlite/usage-import-store.ts

@@ -0,0 +1,133 @@
+import type { Database } from "bun:sqlite";
+import type { MetricObservation } from "../observability/metric.ts";
+import { validateMetricObservation } from "../observability/metric.ts";
+import type { HistoricalUsageRecord, UsageImportResult, UsageImportStatus, UsageImportStore } from "../observability/usage-import.ts";
+
+function validateRecord(record: HistoricalUsageRecord): HistoricalUsageRecord {
+	if (!/^[a-f0-9]{64}$/.test(record.identity)) throw new Error("usage import identity is invalid");
+	if (!Number.isSafeInteger(record.observedAt) || record.observedAt < 0) throw new Error("usage import timestamp is invalid");
+	return record;
+}
+
+function observations(record: HistoricalUsageRecord): MetricObservation[] {
+	const attributes = {
+		provider: record.provider,
+		model: record.model,
+		...(record.thinking ? { thinking: record.thinking } : {}),
+		imported: true,
+		importIdentity: record.identity,
+	};
+	const token = (metric: string, value: number, scope: "request-input" | "response-output" | "cache-read" | "cache-write") => ({
+		source: "pi",
+		scope: `${record.provider}:${record.model}`,
+		metric,
+		value,
+		unit: "tokens" as const,
+		observedAt: record.observedAt,
+		attributes: {
+			...attributes,
+			tokenMeasurement: {
+				tokens: value,
+				scope,
+				provenance: "provider-reported",
+				method: "pi-assistant-usage",
+				provider: record.provider,
+				model: record.model,
+			},
+		},
+	});
+	return [
+		token("input-tokens", record.inputTokens, "request-input"),
+		token("output-tokens", record.outputTokens, "response-output"),
+		token("cache-read-tokens", record.cacheReadTokens, "cache-read"),
+		token("cache-write-tokens", record.cacheWriteTokens, "cache-write"),
+		{
+			source: "pi",
+			scope: `${record.provider}:${record.model}`,
+			metric: "cost",
+			value: record.costUsd,
+			unit: "usd",
+			observedAt: record.observedAt,
+			attributes,
+		},
+	].map(validateMetricObservation);
+}
+
+export class SQLiteUsageImportStore implements UsageImportStore {
+	constructor(private readonly db: Database) {}
+
+	import(input: HistoricalUsageRecord[]): { imported: number; duplicates: number } {
+		const records = input.map(validateRecord);
+		const claim = this.db.prepare("INSERT OR IGNORE INTO usage_import_identities(identity, imported_at) VALUES (?, ?)");
+		const matchingLive = this.db.prepare(
+			"SELECT COUNT(DISTINCT metric) AS matched FROM metric_observations WHERE source = 'pi' AND scope = ? AND observed_at = ? AND ((metric = 'input-tokens' AND value = ?) OR (metric = 'output-tokens' AND value = ?) OR (metric = 'cache-read-tokens' AND value = ?) OR (metric = 'cache-write-tokens' AND value = ?) OR (metric = 'cost' AND value = ?))",
+		);
+		const insert = this.db.prepare(
+			"INSERT INTO metric_observations(source, scope, metric, value, unit, observed_at, attributes) VALUES (?, ?, ?, ?, ?, ?, ?)",
+		);
+		let imported = 0;
+		let duplicates = 0;
+		this.db.transaction(() => {
+			for (const record of records) {
+				const scope = `${record.provider}:${record.model}`;
+				const live = matchingLive.get(
+					scope,
+					record.observedAt,
+					record.inputTokens,
+					record.outputTokens,
+					record.cacheReadTokens,
+					record.cacheWriteTokens,
+					record.costUsd,
+				) as { matched: number };
+				const result = claim.run(record.identity, Date.now());
+				if (result.changes === 0 || live.matched === 5) {
+					duplicates += 1;
+					continue;
+				}
+				for (const observation of observations(record)) {
+					insert.run(
+						observation.source,
+						observation.scope,
+						observation.metric,
+						observation.value,
+						observation.unit,
+						observation.observedAt,
+						JSON.stringify(observation.attributes ?? {}),
+					);
+				}
+				imported += 1;
+			}
+		})();
+		return { imported, duplicates };
+	}
+
+	preview(records: HistoricalUsageRecord[]): { duplicates: number } {
+		const exists = this.db.prepare("SELECT 1 AS found FROM usage_import_identities WHERE identity = ? LIMIT 1");
+		return { duplicates: records.map(validateRecord).filter((record) => exists.get(record.identity) !== null).length };
+	}
+
+	status(): UsageImportStatus {
+		const row = this.db.query<{ status: string }, []>("SELECT status FROM usage_import_state WHERE id = 1").get();
+		if (!row) return { running: false, cancelRequested: false, lastResult: null };
+		try {
+			const parsed = JSON.parse(row.status) as { lastResult?: unknown };
+			const lastResult = parsed.lastResult;
+			return {
+				running: false,
+				cancelRequested: false,
+				lastResult:
+					typeof lastResult === "object" && lastResult !== null && !Array.isArray(lastResult) ? (lastResult as UsageImportResult) : null,
+			};
+		} catch {
+			return { running: false, cancelRequested: false, lastResult: null };
+		}
+	}
+
+	saveStatus(status: UsageImportStatus): void {
+		this.db
+			.prepare(
+				"INSERT INTO usage_import_state(id, status, updated_at) VALUES (1, ?, ?) ON CONFLICT(id) DO UPDATE SET status = excluded.status, updated_at = excluded.updated_at",
+			)
+			.run(JSON.stringify(status), Date.now());
+	}
+}

package/src/telemetry-export/exporter.ts

@@ -0,0 +1,84 @@
+import type { MetricObservation, MetricQuery, StoredMetricObservation } from "../observability/metric.ts";
+import type { DistinctScopesFilter, MetricStore, UsageAggregateFilter } from "../observability/store.ts";
+import type { UsageAggregateRow } from "../observability/usage.ts";
+
+export interface ObservationExportStatus {
+	enabled: boolean;
+	semanticConventions: string;
+	queued: number;
+	dropped: number;
+	exported: number;
+	failures: number;
+	lastSuccessAt: number | null;
+	lastFailureAt: number | null;
+}
+
+export interface ObservationExporter {
+	enqueue(observation: MetricObservation): void;
+	flush(): Promise<void>;
+	shutdown(): Promise<void>;
+	status(): ObservationExportStatus;
+}
+
+export class DisabledObservationExporter implements ObservationExporter {
+	enqueue(): void {}
+	async flush(): Promise<void> {}
+	async shutdown(): Promise<void> {}
+	status(): ObservationExportStatus {
+		return {
+			enabled: false,
+			semanticConventions: "none",
+			queued: 0,
+			dropped: 0,
+			exported: 0,
+			failures: 0,
+			lastSuccessAt: null,
+			lastFailureAt: null,
+		};
+	}
+}
+
+/** Local persistence completes first; exporter enqueue is best-effort and can never alter that result. */
+export class ExportingMetricStore implements MetricStore {
+	constructor(
+		private readonly local: MetricStore,
+		private readonly exporter: ObservationExporter,
+	) {}
+
+	record(observation: MetricObservation): StoredMetricObservation {
+		const stored = this.local.record(observation);
+		try {
+			this.exporter.enqueue(observation);
+		} catch {}
+		return stored;
+	}
+
+	recordBatch(observations: MetricObservation[]): StoredMetricObservation[] {
+		const stored = this.local.recordBatch(observations);
+		for (const observation of observations) {
+			try {
+				this.exporter.enqueue(observation);
+			} catch {}
+		}
+		return stored;
+	}
+
+	query(filter?: MetricQuery): StoredMetricObservation[] {
+		return this.local.query(filter);
+	}
+	distinctScopes(filter: DistinctScopesFilter): string[] {
+		return this.local.distinctScopes(filter);
+	}
+	aggregateUsage(filter: UsageAggregateFilter): UsageAggregateRow[] {
+		return this.local.aggregateUsage(filter);
+	}
+	pruneBefore(cutoff: number): number {
+		return this.local.pruneBefore(cutoff);
+	}
+	checkpoint(): void {
+		this.local.checkpoint();
+	}
+	close(): void {
+		this.local.close();
+	}
+}

package/src/{operations → vehicle}/benchmark-operations.ts

@@ -1,6 +1,6 @@
-import type { BenchmarkQuery } from "../domain/benchmark.ts";
-import type { BenchmarkController } from "../ports/benchmark-controller.ts";
-import type { OperationHandlerMap } from "./types.ts";
+import type { BenchmarkQuery } from "../optimization/model-selection/benchmark.ts";
+import type { BenchmarkController } from "../optimization/model-selection/controller.ts";
+import type { OperationHandlerMap } from "./operation-types.ts";
 
 /** benchmark.* -- every operation whose only collaborator is the benchmark-controller port. */
 export function benchmarkOperations(benchmarks: BenchmarkController): OperationHandlerMap {

package/src/vehicle/catalog-operations.ts

@@ -0,0 +1,10 @@
+import type { ModelCatalogController, ModelCatalogQuery } from "../optimization/model-selection/catalog.ts";
+import type { OperationHandlerMap } from "./operation-types.ts";
+
+export function catalogOperations(catalog: ModelCatalogController): OperationHandlerMap {
+	return {
+		"catalog.refresh": (input) => catalog.refresh(input.force === true),
+		"catalog.status": () => catalog.status(),
+		"catalog.query": (input) => catalog.query(input as unknown as ModelCatalogQuery),
+	};
+}

package/src/{client.ts → vehicle/client.ts}

@@ -1,6 +1,6 @@
 import { AuthenticatedRpcClient, type FetchTransport } from "@danypops/vehicle-client/rpc-client";
+import { ensureAuthToken, type JittorPaths, readDaemonHandle, resolveJittorPaths } from "../state.ts";
 import type { OperationInputs, OperationName, OperationOutputs } from "./service.ts";
-import { ensureAuthToken, type JittorPaths, readDaemonHandle, resolveJittorPaths } from "./state.ts";
 
 export type { FetchTransport };
 

package/src/{operations → vehicle}/context-operations.ts

@@ -3,12 +3,14 @@ import {
 	CONTEXT_ASSESSMENT_DEFAULT_WINDOW_MS,
 	CONTEXT_ASSESSMENT_QUERY_LIMIT,
 } from "../constants.ts";
-import { assessContextTelemetry, estimateCompactionDuration } from "../domain/context-telemetry.ts";
-import type { MetricStore } from "../ports/metric-store.ts";
-import type { OperationHandlerMap } from "./types.ts";
+import type { ContextSnapshot } from "../observability/context-delta.ts";
+import type { ContextSnapshotHistory } from "../observability/context-snapshot-history.ts";
+import { assessContextTelemetry, estimateCompactionDuration } from "../observability/context-telemetry.ts";
+import type { MetricStore } from "../observability/store.ts";
+import type { OperationHandlerMap } from "../vehicle/operation-types.ts";
 
-/** context.assess and compaction.estimate -- both read-only projections of recorded metrics, no router/session involvement. */
-export function contextOperations(metrics: MetricStore): OperationHandlerMap {
+/** Context assessment, content-free snapshots/deltas, and compaction estimates. */
+export function contextOperations(metrics: MetricStore, snapshots: ContextSnapshotHistory): OperationHandlerMap {
 	return {
 		"context.assess": (input) => {
 			const until = input.until === undefined ? Date.now() : input.until;
@@ -25,6 +27,12 @@ export function contextOperations(metrics: MetricStore): OperationHandlerMap {
 				truncated: injections.length >= CONTEXT_ASSESSMENT_QUERY_LIMIT || compactions.length >= CONTEXT_ASSESSMENT_QUERY_LIMIT,
 			});
 		},
+		"context.snapshot": (input) => snapshots.record(input as unknown as ContextSnapshot),
+		"context.delta": (input) => {
+			if (typeof input.session_id !== "string" || !/^[A-Za-z0-9_-]{32,64}$/.test(input.session_id))
+				throw new Error("context delta requires an opaque session_id fingerprint");
+			return snapshots.latestDelta(input.session_id);
+		},
 		"compaction.estimate": () => {
 			const rows = metrics.query({
 				source: "pi-context",

package/src/vehicle/export-operations.ts

@@ -0,0 +1,12 @@
+import type { ObservationExporter } from "../telemetry-export/exporter.ts";
+import type { OperationHandlerMap } from "./operation-types.ts";
+
+export function exportOperations(exporter: ObservationExporter): OperationHandlerMap {
+	return {
+		"export.status": () => exporter.status(),
+		"export.flush": async () => {
+			await exporter.flush();
+			return exporter.status();
+		},
+	};
+}

package/src/{operations/metrics-operations.ts → vehicle/metric-operations.ts}

@@ -5,10 +5,10 @@ import {
 	TASK_COST_QUERY_LIMIT,
 	USAGE_MAX_DISTINCT_SCOPES,
 } from "../constants.ts";
-import { type MetricQuery, validateMetricObservation } from "../domain/metric.ts";
-import { buildTaskCostSummary } from "../domain/task-cost.ts";
-import type { MetricStore } from "../ports/metric-store.ts";
-import type { OperationHandlerMap } from "./types.ts";
+import { type MetricQuery, validateMetricObservation } from "../observability/metric.ts";
+import type { MetricStore } from "../observability/store.ts";
+import { buildTaskCostSummary } from "../observability/task-cost.ts";
+import type { OperationHandlerMap } from "../vehicle/operation-types.ts";
 
 /** metrics.* and service.checkpoint -- every operation whose only collaborator is the metric-store port. */
 export function metricsOperations(metrics: MetricStore): OperationHandlerMap {

package/src/{operations → vehicle}/model-ranking-operations.ts

@@ -1,6 +1,6 @@
-import type { ModelRanker, ModelRecommendationInput } from "../domain/model-ranking-service.ts";
-import type { RouterController } from "../ports/router-controller.ts";
-import type { OperationHandlerMap } from "./types.ts";
+import type { ModelRanker, ModelRecommendationInput } from "../optimization/model-selection/ranker.ts";
+import type { RouterController } from "../optimization/routing/controller.ts";
+import type { OperationHandlerMap } from "./operation-types.ts";
 
 /** models.rank -- scores candidates via the model ranker, then, only for an automatic selection, applies it as a router mutation (so it shares the same session-identity authorization as every other router mutation). */
 export function modelRankingOperations(

package/src/{vehicle-registration.ts → vehicle/registration.ts}

@@ -1,5 +1,5 @@
 /**
- * jittor's 25-operation surface projected onto the real Vehicle protocol.
+ * jittor's operation surface projected onto the real Vehicle protocol.
  * Every operation delegates to the exact same handler function service.ts's
  * hand-rolled dispatch already calls (one implementation, two projections --
  * the same shape every other Vehicle-migrated daemon in this ecosystem
@@ -7,7 +7,7 @@
  * alongside (not replacing) the existing /api/v1/ops route.
  *
  * Every jittor operation already validates its own loosely-typed
- * Record<string, unknown> input internally (see operations/*.ts) -- there
+ * Record<string, unknown> input internally (see each feature's operation module) -- there
  * is no separate Vehicle-side schema to duplicate that logic, so both input
  * and output use passthroughVehicleSchema and let the real handler's own
  * validation (already covered by service.test.ts) be the single source of
@@ -25,9 +25,9 @@
 import type { VehicleEffect, VehicleIdempotency } from "@danypops/vehicle-core";
 import { bindVehicleOperation, defineErrorMapping, defineVehicleOperation, passthroughVehicleSchema } from "@danypops/vehicle-core";
 import type { VehicleRegistry } from "@danypops/vehicle-server";
-import type { OperationHandlerMap } from "./operations/types.ts";
+import { InvalidSessionSecretError } from "../sessions/identity.ts";
+import type { OperationHandlerMap } from "./operation-types.ts";
 import type { OperationName } from "./service.ts";
-import { InvalidSessionSecretError } from "./session-identity-service.ts";
 
 /** Preserves the legacy route's 403 for invalid session credentials; every other rejection remains validation. */
 const withJittorErrorParity = defineErrorMapping([
@@ -85,6 +85,14 @@ const OPERATION_META: Record<OperationName, OperationMeta> = {
 	"benchmark.refresh": { description: "Refreshes model benchmark evidence from external sources.", effect: "external-write" },
 	"benchmark.status": { description: "Reports the last benchmark refresh's own status.", effect: "read" },
 	"benchmark.query": { description: "Queries cached benchmark evidence.", effect: "read" },
+	"catalog.refresh": { description: "Refreshes the opt-in models.dev metadata snapshot.", effect: "external-write" },
+	"catalog.status": { description: "Reports model-catalog configuration and last-good snapshot status.", effect: "read" },
+	"catalog.query": { description: "Queries bounded provenance-bearing model metadata.", effect: "read" },
+	"usage.import": { description: "Imports bounded content-free usage from persisted Pi sessions.", effect: "local-write" },
+	"usage.import_status": { description: "Reports durable historical usage import progress.", effect: "read" },
+	"usage.import_cancel": { description: "Requests cancellation of active historical usage imports.", effect: "local-write" },
+	"export.status": { description: "Reports credential-safe OTLP exporter health and queue status.", effect: "read" },
+	"export.flush": { description: "Flushes the bounded OTLP export queue.", effect: "external-write" },
 	"session.register": { description: "Registers a Pi session identity, issuing a session secret.", effect: "local-write" },
 	"session.release": { description: "Releases a registered Pi session identity.", effect: "local-write" },
 	"models.rank": {
@@ -92,6 +100,8 @@ const OPERATION_META: Record<OperationName, OperationMeta> = {
 		effect: "local-write",
 	},
 	"context.assess": { description: "Assesses context-injection/compaction health within a bounded time window.", effect: "read" },
+	"context.delta": { description: "Returns the latest bounded content-free context delta for one opaque session.", effect: "read" },
+	"context.snapshot": { description: "Records one bounded content-free context snapshot and computes its delta.", effect: "local-write" },
 	"compaction.estimate": { description: "Estimates compaction duration from recorded samples.", effect: "read" },
 	"service.checkpoint": { description: "Flushes the metric store's write-ahead log.", effect: "local-write" },
 	"telemetry.poll": { description: "Polls external telemetry provider status.", effect: "read" },

package/src/{operations/router-operations.ts → vehicle/routing-operations.ts}

@@ -1,7 +1,7 @@
-import type { Route } from "../policy.ts";
-import type { RouteOverride, RouterController } from "../ports/router-controller.ts";
-import { routerSessionId } from "./session-scope.ts";
-import type { OperationHandlerMap } from "./types.ts";
+import type { RouteOverride, RouterController } from "../optimization/routing/controller.ts";
+import type { Route } from "../optimization/routing/policy.ts";
+import { routerSessionId } from "../sessions/router-authorization.ts";
+import type { OperationHandlerMap } from "./operation-types.ts";
 
 /** telemetry.poll and every router.* operation -- reads pass a bare session_id through; mutations run authorize first, matching the opt-in session-identity armor. */
 export function routerOperations(

package/src/{service.ts → vehicle/service.ts}

@@ -1,29 +1,42 @@
 import { VehicleRegistry } from "@danypops/vehicle-server";
 import { createVehicleHttpApp } from "@danypops/vehicle-server/http";
 import { errorResponse, healthResponse, readyResponse, requireBearerToken } from "@danypops/vehicle-server/rpc-http";
-import { SERVICE_MAX_BODY_BYTES, SERVICE_MAX_RESPONSE_BYTES } from "./constants.ts";
-import type { BenchmarkQuery, BenchmarkQueryResult, BenchmarkRefreshResult } from "./domain/benchmark.ts";
-import type { CompactionDurationEstimate, ContextAssessment } from "./domain/context-telemetry.ts";
-import type { MetricObservation, MetricQuery, StoredMetricObservation } from "./domain/metric.ts";
-import type { ModelRankingResult } from "./domain/model-ranking.ts";
-import type { ModelRanker, ModelRecommendationInput } from "./domain/model-ranking-service.ts";
-import type { TaskCostSummary } from "./domain/task-cost.ts";
-import type { UsageAggregateRow } from "./domain/usage.ts";
-import { benchmarkOperations } from "./operations/benchmark-operations.ts";
-import { contextOperations } from "./operations/context-operations.ts";
-import { metricsOperations } from "./operations/metrics-operations.ts";
-import { modelRankingOperations } from "./operations/model-ranking-operations.ts";
-import { routerOperations } from "./operations/router-operations.ts";
-import { sessionIdentityOperations } from "./operations/session-identity-operations.ts";
-import { routerMutationAuthorizer } from "./operations/session-scope.ts";
-import type { OperationHandlerMap } from "./operations/types.ts";
-import type { PolicyDecision, Route } from "./policy.ts";
-import type { BenchmarkController } from "./ports/benchmark-controller.ts";
-import type { MetricStore } from "./ports/metric-store.ts";
-import type { RouteOverride, RouterController, RouterStatus, TelemetryPollResult } from "./ports/router-controller.ts";
-import { InvalidSessionSecretError, type RegisterSessionIdentityResult, type SessionIdentity } from "./session-identity-service.ts";
-import { registerJittorVehicleOperations } from "./vehicle-registration.ts";
-import { VERSION } from "./version.ts";
+import { SERVICE_MAX_BODY_BYTES, SERVICE_MAX_RESPONSE_BYTES } from "../constants.ts";
+import type { ContextDelta, ContextSnapshot } from "../observability/context-delta.ts";
+import { type ContextSnapshotHistory, MetricContextSnapshotHistory } from "../observability/context-snapshot-history.ts";
+import type { CompactionDurationEstimate, ContextAssessment } from "../observability/context-telemetry.ts";
+import type { MetricObservation, MetricQuery, StoredMetricObservation } from "../observability/metric.ts";
+import type { MetricStore } from "../observability/store.ts";
+import type { TaskCostSummary } from "../observability/task-cost.ts";
+import type { UsageAggregateRow } from "../observability/usage.ts";
+import type { UsageImportController, UsageImportResult, UsageImportStatus } from "../observability/usage-import.ts";
+import type { BenchmarkQuery, BenchmarkQueryResult, BenchmarkRefreshResult } from "../optimization/model-selection/benchmark.ts";
+import type {
+	ModelCatalogController,
+	ModelCatalogQuery,
+	ModelCatalogQueryResult,
+	ModelCatalogStatus,
+} from "../optimization/model-selection/catalog.ts";
+import type { BenchmarkController } from "../optimization/model-selection/controller.ts";
+import type { ModelRanker, ModelRecommendationInput } from "../optimization/model-selection/ranker.ts";
+import type { ModelRankingResult } from "../optimization/model-selection/ranking.ts";
+import type { RouteOverride, RouterController, RouterStatus, TelemetryPollResult } from "../optimization/routing/controller.ts";
+import type { PolicyDecision, Route } from "../optimization/routing/policy.ts";
+import { InvalidSessionSecretError, type RegisterSessionIdentityResult, type SessionIdentity } from "../sessions/identity.ts";
+import { routerMutationAuthorizer } from "../sessions/router-authorization.ts";
+import { DisabledObservationExporter, type ObservationExporter, type ObservationExportStatus } from "../telemetry-export/exporter.ts";
+import { VERSION } from "../version.ts";
+import { benchmarkOperations } from "./benchmark-operations.ts";
+import { catalogOperations } from "./catalog-operations.ts";
+import { contextOperations } from "./context-operations.ts";
+import { exportOperations } from "./export-operations.ts";
+import { metricsOperations } from "./metric-operations.ts";
+import { modelRankingOperations } from "./model-ranking-operations.ts";
+import type { OperationHandlerMap } from "./operation-types.ts";
+import { registerJittorVehicleOperations } from "./registration.ts";
+import { routerOperations } from "./routing-operations.ts";
+import { sessionIdentityOperations } from "./session-operations.ts";
+import { usageImportOperations } from "./usage-import-operations.ts";
 
 export const EXPECTED_OPERATION_NAMES = [
 	"metrics.record",
@@ -36,10 +49,20 @@ export const EXPECTED_OPERATION_NAMES = [
 	"benchmark.refresh",
 	"benchmark.status",
 	"benchmark.query",
+	"catalog.refresh",
+	"catalog.status",
+	"catalog.query",
+	"usage.import",
+	"usage.import_status",
+	"usage.import_cancel",
+	"export.status",
+	"export.flush",
 	"session.register",
 	"session.release",
 	"models.rank",
 	"context.assess",
+	"context.delta",
+	"context.snapshot",
 	"compaction.estimate",
 	"service.checkpoint",
 	"telemetry.poll",
@@ -71,8 +94,18 @@ export interface OperationInputs {
 	"benchmark.refresh": { force?: boolean };
 	"benchmark.status": Record<string, never>;
 	"benchmark.query": BenchmarkQuery;
+	"catalog.refresh": { force?: boolean };
+	"catalog.status": Record<string, never>;
+	"catalog.query": ModelCatalogQuery;
+	"usage.import": { dryRun?: boolean };
+	"usage.import_status": Record<string, never>;
+	"usage.import_cancel": Record<string, never>;
+	"export.status": Record<string, never>;
+	"export.flush": Record<string, never>;
 	"models.rank": ModelRecommendationInput & RouterScopeInput;
 	"context.assess": { since?: number; until?: number };
+	"context.delta": { session_id: string };
+	"context.snapshot": ContextSnapshot;
 	"compaction.estimate": Record<string, never>;
 	"service.checkpoint": Record<string, never>;
 	"telemetry.poll": Record<string, never>;
@@ -98,8 +131,18 @@ export interface OperationOutputs {
 	"benchmark.refresh": BenchmarkRefreshResult;
 	"benchmark.status": BenchmarkRefreshResult;
 	"benchmark.query": BenchmarkQueryResult;
+	"catalog.refresh": ModelCatalogStatus;
+	"catalog.status": ModelCatalogStatus;
+	"catalog.query": ModelCatalogQueryResult;
+	"usage.import": UsageImportResult;
+	"usage.import_status": UsageImportStatus;
+	"usage.import_cancel": UsageImportStatus;
+	"export.status": ObservationExportStatus;
+	"export.flush": ObservationExportStatus;
 	"models.rank": ModelRankingResult;
 	"context.assess": ContextAssessment;
+	"context.delta": ContextDelta | null;
+	"context.snapshot": ContextDelta;
 	"compaction.estimate": CompactionDurationEstimate;
 	"service.checkpoint": { ok: true };
 	"telemetry.poll": TelemetryPollResult;
@@ -116,6 +159,38 @@ export interface OperationOutputs {
 export class UnknownOperationError extends Error {}
 export { InvalidSessionSecretError };
 
+class UnavailableUsageImporter implements UsageImportController {
+	async run(): Promise<UsageImportResult> {
+		throw new Error("historical usage import is not configured");
+	}
+	status(): UsageImportStatus {
+		return { running: false, cancelRequested: false, lastResult: null };
+	}
+	cancel(): UsageImportStatus {
+		return this.status();
+	}
+}
+
+class UnavailableModelCatalog implements ModelCatalogController {
+	async refresh(): Promise<ModelCatalogStatus> {
+		return this.status();
+	}
+	status(): ModelCatalogStatus {
+		return {
+			configured: false,
+			ok: null,
+			hasSnapshot: false,
+			lastAttemptAt: null,
+			lastSuccessAt: null,
+			entries: 0,
+			revision: null,
+		};
+	}
+	query(): ModelCatalogQueryResult {
+		throw new Error("model catalog is not configured");
+	}
+}
+
 class UnavailableModelRanker implements ModelRanker {
 	rank(): ModelRankingResult {
 		throw new Error("model ranking is not configured");
@@ -191,6 +266,10 @@ export class JittorService {
 		benchmarks: BenchmarkController = new UnavailableBenchmarkController(),
 		modelRanker: ModelRanker = new UnavailableModelRanker(),
 		sessionIdentity?: SessionIdentity,
+		contextSnapshots: ContextSnapshotHistory = new MetricContextSnapshotHistory(metrics),
+		catalog: ModelCatalogController = new UnavailableModelCatalog(),
+		usageImporter: UsageImportController = new UnavailableUsageImporter(),
+		exporter: ObservationExporter = new DisabledObservationExporter(),
 	) {
 		this.router = router;
 		const authorize = routerMutationAuthorizer(sessionIdentity);
@@ -200,15 +279,18 @@ export class JittorService {
 		this.operations = {
 			...metricsOperations(metrics),
 			...benchmarkOperations(benchmarks),
-			...contextOperations(metrics),
+			...catalogOperations(catalog),
+			...usageImportOperations(usageImporter),
+			...exportOperations(exporter),
+			...contextOperations(metrics, contextSnapshots),
 			...routerOperations(router, authorize),
 			...modelRankingOperations(modelRanker, router, authorize),
 			...sessionIdentityOperations(sessionIdentity),
 		};
 		this.vehicleRegistry = new VehicleRegistry({
 			name: "jittor",
-			packageJsonUrl: new URL("../package.json", import.meta.url),
-			description: "Just-in-Time Token Optimizing Router for Pi -- metrics, benchmark evidence, model ranking, and router policy.",
+			packageJsonUrl: new URL("../../package.json", import.meta.url),
+			description: "Just-in-Time Token Optimization Router for Pi -- token and context observability with optimization policies.",
 		});
 		// withJittorErrorParity() already converts every real handler error into a well-formed
 		// VehicleError, so this only affects a genuine registration/binding bug.

package/src/{operations/session-identity-operations.ts → vehicle/session-operations.ts}

@@ -1,6 +1,6 @@
-import type { SessionIdentity } from "../session-identity-service.ts";
-import { requiredString, routerSessionSecret } from "./session-scope.ts";
-import type { OperationHandlerMap } from "./types.ts";
+import type { SessionIdentity } from "../sessions/identity.ts";
+import { requiredString, routerSessionSecret } from "../sessions/router-authorization.ts";
+import type { OperationHandlerMap } from "../vehicle/operation-types.ts";
 
 /** session.register and session.release -- the only two operations that mutate SessionIdentity itself, distinct from the router mutations it later authorizes. */
 export function sessionIdentityOperations(sessionIdentity: SessionIdentity | undefined): OperationHandlerMap {

package/src/vehicle/usage-import-operations.ts

@@ -0,0 +1,10 @@
+import type { UsageImportController } from "../observability/usage-import.ts";
+import type { OperationHandlerMap } from "./operation-types.ts";
+
+export function usageImportOperations(importer: UsageImportController): OperationHandlerMap {
+	return {
+		"usage.import": (input) => importer.run({ dryRun: input.dryRun === true }),
+		"usage.import_status": () => importer.status(),
+		"usage.import_cancel": () => importer.cancel(),
+	};
+}