@danypops/jittor 0.13.0 → 0.15.0

package/src/router.ts

@@ -1,14 +1,14 @@
 import { ROUTER_MAX_SESSION_SCOPES, ROUTER_SESSION_ID_MAX_CHARACTERS } from "./constants.ts";
+import { type BudgetWindow, evaluateRoutingPolicy, type PolicyConfig, type PolicyDecision, type Route } from "./policy.ts";
 import type { MetricStore } from "./ports/metric-store.ts";
-import type { RouteOverride, RouterController, RouterStatus, TelemetryPollResult, TelemetrySourceStatus } from "./ports/router-controller.ts";
+import type {
+	RouteOverride,
+	RouterController,
+	RouterStatus,
+	TelemetryPollResult,
+	TelemetrySourceStatus,
+} from "./ports/router-controller.ts";
 import type { TelemetrySource } from "./ports/telemetry-source.ts";
-import {
-	evaluateRoutingPolicy,
-	type BudgetWindow,
-	type PolicyConfig,
-	type PolicyDecision,
-	type Route,
-} from "./policy.ts";
 
 export interface JittorRouterOptions {
 	metrics: MetricStore;
@@ -57,7 +57,9 @@ export class JittorRouter implements RouterController {
 	}
 
 	poll(): Promise<TelemetryPollResult> {
-		this.inFlightPoll ??= this.runPoll().finally(() => { this.inFlightPoll = null; });
+		this.inFlightPoll ??= this.runPoll().finally(() => {
+			this.inFlightPoll = null;
+		});
 		return this.inFlightPoll;
 	}
 
@@ -79,33 +81,66 @@ export class JittorRouter implements RouterController {
 		const now = this.clock();
 		const state = this.sessionState(sessionId);
 		this.expireOverride(state);
-		if (state.paused) return this.remember(state, { action: "halt", pressure: Number.POSITIVE_INFINITY, reason: "Jittor is paused", decidedAt: now, trace: ["manual pause"] });
+		if (state.paused)
+			return this.remember(state, {
+				action: "halt",
+				pressure: Number.POSITIVE_INFINITY,
+				reason: "Jittor is paused",
+				decidedAt: now,
+				trace: ["manual pause"],
+			});
 		if (state.override) {
 			const route = state.override.route;
-			const action = route.provider !== state.currentRoute.provider
-				? "switch-provider"
-				: route.model !== state.currentRoute.model
-					? "switch-model"
-					: route.thinking !== state.currentRoute.thinking ? "lower-thinking" : "continue";
-			return this.remember(state, { action, route, pressure: 0, reason: "manual route override", decidedAt: now, trace: ["manual override"] });
+			const action =
+				route.provider !== state.currentRoute.provider
+					? "switch-provider"
+					: route.model !== state.currentRoute.model
+						? "switch-model"
+						: route.thinking !== state.currentRoute.thinking
+							? "lower-thinking"
+							: "continue";
+			return this.remember(state, {
+				action,
+				route,
+				pressure: 0,
+				reason: "manual route override",
+				decidedAt: now,
+				trace: ["manual override"],
+			});
 		}
-		if (!this.isReady(state)) return this.remember(state, { action: "halt", pressure: Number.POSITIVE_INFINITY, reason: "required telemetry is not ready", decidedAt: now, trace: ["fail closed"] });
+		if (!this.isReady(state))
+			return this.remember(state, {
+				action: "halt",
+				pressure: Number.POSITIVE_INFINITY,
+				reason: "required telemetry is not ready",
+				decidedAt: now,
+				trace: ["fail closed"],
+			});
 		const activeSources = this.options.sources.filter((source) => source.provider === state.currentRoute.provider);
 		const activeSourceIds = new Set(activeSources.map((source) => source.id));
 		const requiredSourceIds = new Set(activeSources.filter((source) => source.required).map((source) => source.id));
 		const activeWindows = [...this.windows.entries()].filter(([sourceId]) => activeSourceIds.has(sourceId));
 		const requiredWindows = activeWindows.filter(([sourceId]) => requiredSourceIds.has(sourceId)).flatMap(([, windows]) => windows);
 		if (requiredSourceIds.size === 0 && activeWindows.every(([, windows]) => windows.length === 0)) {
-			return this.rememberPolicy(state, { action: "continue", pressure: 0, reason: "provider has no enforceable budget window; monitor-only", decidedAt: now, trace: ["monitor-only"] });
+			return this.rememberPolicy(state, {
+				action: "continue",
+				pressure: 0,
+				reason: "provider has no enforceable budget window; monitor-only",
+				decidedAt: now,
+				trace: ["monitor-only"],
+			});
 		}
-		return this.rememberPolicy(state, evaluateRoutingPolicy({
-			now,
-			windows: requiredSourceIds.size > 0 && requiredWindows.length === 0 ? [] : activeWindows.flatMap(([, windows]) => windows),
-			currentRoute: state.currentRoute,
-			routes: state.availableRoutes,
-			config: this.options.policy,
-			previousDecision: state.previousPolicyDecision ?? undefined,
-		}));
+		return this.rememberPolicy(
+			state,
+			evaluateRoutingPolicy({
+				now,
+				windows: requiredSourceIds.size > 0 && requiredWindows.length === 0 ? [] : activeWindows.flatMap(([, windows]) => windows),
+				currentRoute: state.currentRoute,
+				routes: state.availableRoutes,
+				config: this.options.policy,
+				previousDecision: state.previousPolicyDecision ?? undefined,
+			}),
+		);
 	}
 
 	pause(sessionId?: string): RouterStatus {
@@ -120,7 +155,8 @@ export class JittorRouter implements RouterController {
 
 	setOverride(override: RouteOverride | undefined, sessionId?: string): RouterStatus {
 		const state = this.sessionState(sessionId);
-		if (!override || !state.availableRoutes.some((route) => sameRoute(route, override.route))) throw new Error("override route is not available in Pi");
+		if (!override || !state.availableRoutes.some((route) => sameRoute(route, override.route)))
+			throw new Error("override route is not available in Pi");
 		if (override.expiresAt !== null && override.expiresAt <= this.clock()) throw new Error("override expiry must be in the future");
 		state.override = structuredClone(override);
 		return this.status(sessionId);
@@ -139,10 +175,18 @@ export class JittorRouter implements RouterController {
 
 	setAvailableRoutes(routes: Route[], sessionId?: string): RouterStatus {
 		if (!Array.isArray(routes)) throw new Error("available routes must be an array");
-		const valid = routes.filter((route) => typeof route?.provider === "string" && route.provider.length > 0
-			&& typeof route.model === "string" && route.model.length > 0
-			&& typeof route.thinking === "string" && route.thinking.length > 0);
-		this.sessionState(sessionId).availableRoutes = valid.filter((route, index) => valid.findIndex((candidate) => sameRoute(candidate, route)) === index).map((route) => structuredClone(route));
+		const valid = routes.filter(
+			(route) =>
+				typeof route?.provider === "string" &&
+				route.provider.length > 0 &&
+				typeof route.model === "string" &&
+				route.model.length > 0 &&
+				typeof route.thinking === "string" &&
+				route.thinking.length > 0,
+		);
+		this.sessionState(sessionId).availableRoutes = valid
+			.filter((route, index) => valid.findIndex((candidate) => sameRoute(candidate, route)) === index)
+			.map((route) => structuredClone(route));
 		return this.status(sessionId);
 	}
 
@@ -155,22 +199,27 @@ export class JittorRouter implements RouterController {
 			.filter((route): route is Route => route !== undefined);
 		const current = ranked.find((route) => sameRoute(route, state.currentRoute));
 		if (!current) throw new Error("model ranking does not contain the current available route");
-		state.availableRoutes = [structuredClone(current), ...ranked.filter((route) => !sameRoute(route, current)).map((route) => structuredClone(route))];
+		state.availableRoutes = [
+			structuredClone(current),
+			...ranked.filter((route) => !sameRoute(route, current)).map((route) => structuredClone(route)),
+		];
 		return this.status(sessionId);
 	}
 
 	private async runPoll(): Promise<TelemetryPollResult> {
-		const statuses = await Promise.all(this.options.sources.map(async (source): Promise<TelemetrySourceStatus> => {
-			try {
-				const batch = await source.poll();
-				for (const observation of batch.metrics) this.options.metrics.record(observation);
-				this.windows.set(source.id, batch.windows);
-				return { id: source.id, provider: source.provider, ok: true, metrics: batch.metrics.length, observedAt: batch.observedAt };
-			} catch {
-				this.windows.delete(source.id);
-				return { id: source.id, provider: source.provider, ok: false, metrics: 0, observedAt: this.clock(), error: "poll failed" };
-			}
-		}));
+		const statuses = await Promise.all(
+			this.options.sources.map(async (source): Promise<TelemetrySourceStatus> => {
+				try {
+					const batch = await source.poll();
+					for (const observation of batch.metrics) this.options.metrics.record(observation);
+					this.windows.set(source.id, batch.windows);
+					return { id: source.id, provider: source.provider, ok: true, metrics: batch.metrics.length, observedAt: batch.observedAt };
+				} catch {
+					this.windows.delete(source.id);
+					return { id: source.id, provider: source.provider, ok: false, metrics: 0, observedAt: this.clock(), error: "poll failed" };
+				}
+			}),
+		);
 		this.sourceStatuses = statuses;
 		return { sources: structuredClone(statuses), observedAt: this.clock() };
 	}

package/src/service.ts

@@ -1,26 +1,29 @@
+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 { InvalidSessionSecretError, SessionIdentity, type RegisterSessionIdentityResult } from "./session-identity-service.ts";
-import { VERSION } from "./version.ts";
-import type { MetricObservation, MetricQuery, StoredMetricObservation } from "./domain/metric.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 type { BenchmarkQuery, BenchmarkQueryResult, BenchmarkRefreshResult } from "./domain/benchmark.ts";
-import type { ModelRanker, ModelRecommendationInput } from "./domain/model-ranking-service.ts";
-import type { ModelRankingResult } from "./domain/model-ranking.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 type { PolicyDecision, Route } from "./policy.ts";
-import { metricsOperations } from "./operations/metrics-operations.ts";
 import { benchmarkOperations } from "./operations/benchmark-operations.ts";
 import { contextOperations } from "./operations/context-operations.ts";
-import { routerOperations } from "./operations/router-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";
 
 export const EXPECTED_OPERATION_NAMES = [
 	"metrics.record",
@@ -50,8 +53,11 @@ export const EXPECTED_OPERATION_NAMES = [
 	"router.available_routes",
 ] as const;
 
-export type OperationName = typeof EXPECTED_OPERATION_NAMES[number];
-interface RouterScopeInput { session_id?: string; session_secret?: string }
+export type OperationName = (typeof EXPECTED_OPERATION_NAMES)[number];
+interface RouterScopeInput {
+	session_id?: string;
+	session_secret?: string;
+}
 export interface OperationInputs {
 	"session.register": { session_id: string };
 	"session.release": { session_id: string; session_secret?: string };
@@ -111,31 +117,73 @@ export class UnknownOperationError extends Error {}
 export { InvalidSessionSecretError };
 
 class UnavailableModelRanker implements ModelRanker {
-	rank(): ModelRankingResult { throw new Error("model ranking is not configured"); }
+	rank(): ModelRankingResult {
+		throw new Error("model ranking is not configured");
+	}
 }
 
 class UnavailableBenchmarkController implements BenchmarkController {
-	async refresh(): Promise<BenchmarkRefreshResult> { return this.status(); }
-	status(): BenchmarkRefreshResult { return { observedAt: Date.now(), sources: [] }; }
-	query(): BenchmarkQueryResult { throw new Error("benchmark evidence is not configured"); }
+	async refresh(): Promise<BenchmarkRefreshResult> {
+		return this.status();
+	}
+	status(): BenchmarkRefreshResult {
+		return { observedAt: Date.now(), sources: [] };
+	}
+	query(): BenchmarkQueryResult {
+		throw new Error("benchmark evidence is not configured");
+	}
 }
 
 class UnavailableRouter implements RouterController {
-	private readonly unavailable: RouterStatus = { ready: false, paused: false, sources: [], lastDecision: null, override: null, currentRoute: null, availableRoutes: [] };
-	async poll(): Promise<TelemetryPollResult> { return { sources: [], observedAt: Date.now() }; }
-	status(): RouterStatus { return structuredClone(this.unavailable); }
-	decide(): PolicyDecision { return { action: "halt", pressure: Number.POSITIVE_INFINITY, reason: "router is not configured", decidedAt: Date.now(), trace: ["fail closed"] }; }
-	pause(): RouterStatus { return this.status(); }
-	resume(): RouterStatus { return this.status(); }
-	setOverride(): RouterStatus { return this.status(); }
-	clearOverride(): RouterStatus { return this.status(); }
-	setCurrentRoute(): RouterStatus { return this.status(); }
-	setAvailableRoutes(): RouterStatus { return this.status(); }
+	private readonly unavailable: RouterStatus = {
+		ready: false,
+		paused: false,
+		sources: [],
+		lastDecision: null,
+		override: null,
+		currentRoute: null,
+		availableRoutes: [],
+	};
+	async poll(): Promise<TelemetryPollResult> {
+		return { sources: [], observedAt: Date.now() };
+	}
+	status(): RouterStatus {
+		return structuredClone(this.unavailable);
+	}
+	decide(): PolicyDecision {
+		return {
+			action: "halt",
+			pressure: Number.POSITIVE_INFINITY,
+			reason: "router is not configured",
+			decidedAt: Date.now(),
+			trace: ["fail closed"],
+		};
+	}
+	pause(): RouterStatus {
+		return this.status();
+	}
+	resume(): RouterStatus {
+		return this.status();
+	}
+	setOverride(): RouterStatus {
+		return this.status();
+	}
+	clearOverride(): RouterStatus {
+		return this.status();
+	}
+	setCurrentRoute(): RouterStatus {
+		return this.status();
+	}
+	setAvailableRoutes(): RouterStatus {
+		return this.status();
+	}
 }
 
 export class JittorService {
 	private readonly router: RouterController;
 	private readonly operations: OperationHandlerMap;
+	/** Every jittor operation, also projected onto the real Vehicle protocol -- see vehicle-registration.ts. Served alongside (not replacing) the /api/v1/ops route below. */
+	readonly vehicleRegistry: VehicleRegistry;
 
 	constructor(
 		private readonly metrics: MetricStore,
@@ -157,6 +205,12 @@ export class JittorService {
 			...modelRankingOperations(modelRanker, router, authorize),
 			...sessionIdentityOperations(sessionIdentity),
 		};
+		this.vehicleRegistry = new VehicleRegistry({
+			name: "jittor",
+			version: "1.0.0",
+			description: "Just-in-Time Token Optimizing Router for Pi -- metrics, benchmark evidence, model ranking, and router policy.",
+		});
+		registerJittorVehicleOperations(this.vehicleRegistry, this.operations);
 	}
 
 	operationNames(): OperationName[] {
@@ -204,10 +258,16 @@ function json(value: unknown, status = 200): Response {
 
 export function createApp(options: JittorAppOptions): { fetch(request: Request): Promise<Response> } {
 	const maxBodyBytes = options.maxBodyBytes ?? SERVICE_MAX_BODY_BYTES;
+	// A real second transport for every jittor operation (see vehicle-registration.ts) --
+	// composed here rather than replacing /api/v1/ops, matching every other Vehicle-migrated
+	// daemon in this ecosystem ("served alongside", not "instead of"). Routed before the
+	// top-level bearer check below since createVehicleHttpApp performs its own.
+	const vehicleApp = createVehicleHttpApp({ registry: options.service.vehicleRegistry, token: options.token });
 	return {
 		async fetch(request: Request): Promise<Response> {
-			if (!requireBearerToken(request, options.token)) return errorResponse("unauthorized", 401);
 			const url = new URL(request.url);
+			if (url.pathname.startsWith("/vehicle/")) return vehicleApp.fetch(request);
+			if (!requireBearerToken(request, options.token)) return errorResponse("unauthorized", 401);
 			if (request.method === "GET" && url.pathname === "/health") return healthResponse(VERSION);
 			if (request.method === "GET" && url.pathname === "/ready") return readyResponse(options.service.ready());
 			if (request.method === "GET" && url.pathname === "/api/v1/ops") return json({ operations: options.service.operationNames() });
@@ -219,9 +279,10 @@ export function createApp(options: JittorAppOptions): { fetch(request: Request):
 			try {
 				const body = JSON.parse(text) as { op?: unknown; input?: unknown };
 				if (typeof body.op !== "string") throw new Error("op is required");
-				const input = typeof body.input === "object" && body.input !== null && !Array.isArray(body.input)
-					? body.input as Record<string, unknown>
-					: {};
+				const input =
+					typeof body.input === "object" && body.input !== null && !Array.isArray(body.input)
+						? (body.input as Record<string, unknown>)
+						: {};
 				return json({ result: await options.service.execute(body.op, input) });
 			} catch (error) {
 				if (error instanceof UnknownOperationError) return json({ error: error.message }, 404);

package/src/session-identity-service.ts

@@ -1,4 +1,9 @@
-import { isSessionRegistered, registerSessionIdentity, releaseSessionIdentity, verifySessionSecret } from "@danypops/vehicle-server/session-identity";
+import {
+	isSessionRegistered,
+	registerSessionIdentity,
+	releaseSessionIdentity,
+	verifySessionSecret,
+} from "@danypops/vehicle-server/session-identity";
 import type { SessionIdentityStore } from "./ports/session-identity-store.ts";
 
 export interface RegisterSessionIdentityResult {
@@ -50,6 +55,9 @@ export class SessionIdentity {
 	assertAuthorized(sessionId: string | undefined, secret: string | undefined): void {
 		if (sessionId === undefined) return;
 		if (!this.isRegistered(sessionId)) return;
-		if (!this.verify(sessionId, secret)) throw new InvalidSessionSecretError(`session "${sessionId}" is registered; a valid session_secret is required to mutate its router state`);
+		if (!this.verify(sessionId, secret))
+			throw new InvalidSessionSecretError(
+				`session "${sessionId}" is registered; a valid session_secret is required to mutate its router state`,
+			);
 	}
 }

package/src/state.ts

@@ -6,22 +6,16 @@
  * client.ts, cli.ts, and their tests) is untouched by this migration.
  */
 import {
+	type DaemonHandle,
+	type DaemonPaths,
 	ensureAuthToken as ensureVehicleAuthToken,
+	type PathEnvironment,
 	readDaemonHandle as readVehicleHandle,
 	removeDaemonHandle as removeVehicleHandle,
 	resolveDaemonPaths,
 	writeDaemonHandle as writeVehicleHandle,
-	type DaemonHandle,
-	type DaemonPaths,
-	type PathEnvironment,
 } from "@danypops/vehicle-server/paths";
-import {
-	DATABASE_FILENAME,
-	HANDLE_FILENAME,
-	JITTOR_STATE_DIRECTORY,
-	SYSTEMD_UNIT_NAME,
-	TOKEN_FILENAME,
-} from "./constants.ts";
+import { DATABASE_FILENAME, HANDLE_FILENAME, JITTOR_STATE_DIRECTORY, SYSTEMD_UNIT_NAME, TOKEN_FILENAME } from "./constants.ts";
 
 export type JittorPaths = DaemonPaths;
 export type { DaemonHandle, PathEnvironment };

package/src/vehicle-registration.ts

@@ -0,0 +1,154 @@
+/**
+ * jittor's 25-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
+ * uses) -- no behavior change, only a second real transport served
+ * 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
+ * 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
+ * truth for what's accepted.
+ *
+ * jittor's operations are never exposed as Pi tools (confirmed: pi-jittor
+ * has zero pi.registerTool() call sites -- its whole surface is consumed
+ * internally by the extension's own footer/context-hub/router capabilities),
+ * so effect/permission classification here is about standardized taxonomy
+ * and future eligibility (Vehicle Jobs, Approval Gate, Safety), not gating
+ * an agent-facing tool call the way it does for a Vehicle whose operations
+ * ARE projected as tools.
+ */
+
+import type { VehicleEffect, VehicleIdempotency } from "@danypops/vehicle-core";
+import { bindVehicleOperation, defineVehicleOperation, passthroughVehicleSchema, VehicleError } from "@danypops/vehicle-core";
+import type { VehicleRegistry } from "@danypops/vehicle-server";
+import type { OperationHandlerMap } from "./operations/types.ts";
+import type { OperationName } from "./service.ts";
+import { InvalidSessionSecretError } from "./session-identity-service.ts";
+
+/**
+ * Preserves /api/v1/ops's own error-to-status behavior (see createApp() in
+ * service.ts): InvalidSessionSecretError -> 403, everything else a handler
+ * throws -> 400. Without this, VehicleRegistry's own invoke() wraps any
+ * handler-thrown error that isn't already a VehicleError into
+ * category:"internal" (HTTP 500), losing both the specific status and the
+ * error's own message (a VehicleFailure never serializes an error's cause
+ * over the wire) -- the same regression class found and fixed in
+ * web-spider's own migration (see its vehicle-error-parity.ts).
+ */
+async function withJittorErrorParity<T>(run: () => T | Promise<T>): Promise<T> {
+	try {
+		return await run();
+	} catch (error) {
+		if (error instanceof VehicleError) throw error;
+		if (error instanceof InvalidSessionSecretError) {
+			throw new VehicleError("invalid-session-secret", error.message, { category: "authorization", cause: error });
+		}
+		const message = error instanceof Error ? error.message : String(error);
+		throw new VehicleError("operation-rejected", message, { category: "validation", cause: error });
+	}
+}
+
+const OWNER = "jittor";
+const LIMITS = { defaultTimeoutMs: 10_000, maxTimeoutMs: 30_000, maxRequestBytes: 65_536, maxResponseBytes: 1_048_576 };
+
+interface OperationMeta {
+	readonly description: string;
+	readonly effect: VehicleEffect;
+}
+
+const READ: VehicleIdempotency = { mode: "safe" };
+const WRITE: VehicleIdempotency = { mode: "unsafe" };
+
+/**
+ * One entry per EXPECTED_OPERATION_NAMES member -- effect classification
+ * rationale:
+ * - metrics.record/record_batch: local-write (jittor's own metric store).
+ * - metrics.query/distinct_scopes/usage_series/cost_by_task: read (pure
+ *   projections of already-recorded local data).
+ * - metrics.prune: destructive (irreversible deletion; the handler itself
+ *   already refuses a too-recent cutoff without force:true).
+ * - benchmark.refresh: external-write (refreshes from external model
+ *   benchmark/leaderboard sources) -- a genuine future Vehicle Jobs
+ *   candidate given its existing status/query split, deferred here (see
+ *   this task's closing note) same as web-spider's fetch/crawl.
+ * - benchmark.status/query: read (local cache of the last refresh).
+ * - session.register/release: local-write (jittor's own session-identity
+ *   registry).
+ * - models.rank: local-write -- primarily a read/scoring operation, but an
+ *   automatic selection applies it as a real router mutation as a side
+ *   effect (see model-ranking-operations.ts), so classified by its most
+ *   consequential possible outcome, not its common case.
+ * - context.assess/compaction.estimate: read.
+ * - service.checkpoint: local-write (flushes the metric store's WAL).
+ * - telemetry.poll: read (reads external telemetry provider status; does
+ *   not itself expose a way to write anything back to those providers).
+ * - router.status/decide: read (a decision query, not a mutation).
+ * - router.pause/resume/override/clear_override/current_route/
+ *   available_routes: local-write (every one is a real router.set (or
+ *   pause/resume) call, despite router.current_route's read-sounding name
+ *   -- confirmed directly against router-operations.ts).
+ */
+const OPERATION_META: Record<OperationName, OperationMeta> = {
+	"metrics.record": { description: "Records one metric observation.", effect: "local-write" },
+	"metrics.record_batch": { description: "Records a bounded batch of metric observations as one atomic unit.", effect: "local-write" },
+	"metrics.query": { description: "Queries recorded metric observations.", effect: "read" },
+	"metrics.distinct_scopes": { description: "Lists distinct scopes recorded for a source within a bounded time window.", effect: "read" },
+	"metrics.usage_series": { description: "Server-side bucketed usage aggregation for a source's distinct scopes.", effect: "read" },
+	"metrics.cost_by_task": { description: "Sums cost/token metrics by focused task within a bounded time window.", effect: "read" },
+	"metrics.prune": { description: "Deletes metric observations older than a cutoff. Irreversible.", effect: "destructive" },
+	"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" },
+	"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": {
+		description: "Scores model candidates; an automatic selection also applies it as a router mutation.",
+		effect: "local-write",
+	},
+	"context.assess": { description: "Assesses context-injection/compaction health within a bounded time window.", effect: "read" },
+	"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" },
+	"router.status": { description: "Reports the router's current status.", effect: "read" },
+	"router.decide": { description: "Computes the router's current policy decision without applying it.", effect: "read" },
+	"router.pause": { description: "Pauses automatic routing.", effect: "local-write" },
+	"router.resume": { description: "Resumes automatic routing.", effect: "local-write" },
+	"router.override": { description: "Sets a time-bounded manual route override.", effect: "local-write" },
+	"router.clear_override": { description: "Clears a manual route override.", effect: "local-write" },
+	"router.current_route": { description: "Sets the router's currently-active route.", effect: "local-write" },
+	"router.available_routes": { description: "Sets the router's currently-available routes.", effect: "local-write" },
+};
+
+/** Read effects need only jittor:read; every other effect needs both (writes commonly also read first). */
+function permissionsFor(effect: VehicleEffect): readonly string[] {
+	return effect === "read" ? ["jittor:read"] : ["jittor:read", "jittor:write"];
+}
+
+export function registerJittorVehicleOperations(registry: VehicleRegistry, operations: OperationHandlerMap): void {
+	for (const [name, meta] of Object.entries(OPERATION_META) as Array<[OperationName, OperationMeta]>) {
+		const handler = operations[name];
+		if (!handler) throw new Error(`jittor Vehicle registration: no handler configured for operation "${name}"`);
+		const operation = defineVehicleOperation({
+			name,
+			version: 1,
+			description: meta.description,
+			input: passthroughVehicleSchema,
+			output: passthroughVehicleSchema,
+			permissions: permissionsFor(meta.effect),
+			effect: meta.effect,
+			idempotency: meta.effect === "read" ? READ : WRITE,
+			limits: LIMITS,
+		});
+		registry.register(
+			OWNER,
+			bindVehicleOperation(
+				operation,
+				() => async (context) => withJittorErrorParity(() => handler(context.input as Record<string, unknown>)),
+			),
+		);
+	}
+}