@danypops/vehicle-core 0.17.0 → 0.18.0

package/src/vehicle-contract.ts

@@ -1,597 +0,0 @@
-import type {
-	VehicleJobSnapshot,
-	VehicleJobSubmitOptions,
-	VehicleJobSubmitResult,
-	VehicleJobTailResult,
-	VehicleJobWakeBudget,
-} from "./vehicle-jobs.js";
-
-export type JsonPrimitive = string | number | boolean | null;
-export type JsonValue = JsonPrimitive | readonly JsonValue[] | { readonly [key: string]: JsonValue };
-export type JsonSchema = Readonly<Record<string, JsonValue>>;
-
-/** Shared defense-in-depth vocabulary for credential-shaped fields at every Vehicle projection boundary. */
-export const VEHICLE_CREDENTIAL_FIELD_NAMES = Object.freeze([
-	"password",
-	"token",
-	"accessToken",
-	"refreshToken",
-	"apiKey",
-	"secret",
-	"authorization",
-	"credential",
-] as const);
-
-const NORMALIZED_VEHICLE_CREDENTIAL_FIELD_NAMES = new Set(
-	VEHICLE_CREDENTIAL_FIELD_NAMES.map((name) => name.replace(/[^a-z0-9]/gi, "").toLowerCase()),
-);
-
-/** Case/separator-insensitive credential-name check used as a fallback when a schema annotation is missing. */
-export function isVehicleCredentialFieldName(name: string): boolean {
-	return NORMALIZED_VEHICLE_CREDENTIAL_FIELD_NAMES.has(name.replace(/[^a-z0-9]/gi, "").toLowerCase());
-}
-
-/**
- * JSON Schema property annotation consumed by human-facing Vehicle adapters.
- * `omit` hides the field; `summarize` may show shape/size but never its value.
- * Standard `writeOnly: true` and `format: "password"` always imply omission.
- */
-export const VEHICLE_SCHEMA_PRESENTATION_EXTENSION = "x-vehicle-presentation" as const;
-export type VehicleSchemaPresentation = "omit" | "summarize";
-
-export interface VehicleSchemaIssue {
-	readonly path: readonly (string | number)[];
-	readonly message: string;
-}
-
-export type VehicleSchemaResult<T> =
-	| { readonly success: true; readonly value: T }
-	| { readonly success: false; readonly issues?: readonly VehicleSchemaIssue[] };
-
-/**
- * A serializable, descriptive `jsonSchema` (surfaced to a client or Pi tool
- * projection) paired with a real `safeParse` that actually enforces it at
- * runtime -- a Vehicle registry's own `invoke()` only ever calls
- * `safeParse`; `jsonSchema` alone is never itself enforced, so a codec that
- * only sets `jsonSchema` without a matching `safeParse` is a documentation
- * gesture, not an honest contract.
- */
-export interface VehicleSchemaCodec<T> {
-	readonly jsonSchema: JsonSchema;
-	safeParse(value: unknown): VehicleSchemaResult<T>;
-}
-
-export function defineVehicleSchema<T>(codec: VehicleSchemaCodec<T>): VehicleSchemaCodec<T> {
-	return Object.freeze({
-		jsonSchema: cloneJson(codec.jsonSchema),
-		safeParse: codec.safeParse,
-	});
-}
-
-export interface LooseObjectProperty {
-	readonly type: string;
-	readonly enum?: readonly string[];
-}
-
-/** JSON Schema's own `type` keyword vocabulary -- checked for real below so a declared `type: "number"` (say) can't silently accept a string forever. `"integer"` additionally requires no fractional part, matching JSON Schema's own distinction from plain `"number"`. An unrecognized type name is treated as "anything goes" (matches passthroughVehicleSchema's own precedent for a shape not worth strictly enforcing) rather than rejecting every input outright for what would otherwise be a schema-authoring typo. */
-function matchesLooseObjectPropertyType(type: string, value: unknown): boolean {
-	switch (type) {
-		case "string":
-			return typeof value === "string";
-		case "number":
-			return typeof value === "number" && Number.isFinite(value);
-		case "integer":
-			return typeof value === "number" && Number.isInteger(value);
-		case "boolean":
-			return typeof value === "boolean";
-		case "object":
-			return typeof value === "object" && value !== null && !Array.isArray(value);
-		case "array":
-			return Array.isArray(value);
-		case "null":
-			return value === null;
-		default:
-			return true;
-	}
-}
-
-/**
- * A VehicleRegistry only ever calls a schema's own safeParse -- jsonSchema is
- * descriptive metadata surfaced to a client/Pi projection, never itself
- * enforced at runtime -- so a declared `type`/`enum`/`additionalProperties: false`
- * has to be checked here for real, or it's a documentation gesture, not an
- * honest contract (the exact drift this function's own jsonSchema metadata
- * had before: it always advertised `additionalProperties: false` and a
- * per-property `type`, while safeParse only ever checked `required` and
- * `enum`). Every consumer projecting a plain-object input onto a
- * VehicleOperation needs the same required/type/extra-key/enum checks; this
- * is that check written once.
- */
-export function defineLooseObjectSchema(
-	properties: Record<string, LooseObjectProperty>,
-	required: readonly string[] = [],
-): VehicleSchemaCodec<Record<string, unknown>> {
-	return defineVehicleSchema<Record<string, unknown>>({
-		// LooseObjectProperty's named fields (type, enum) are all JSON-value-shaped
-		// at runtime, but TypeScript's structural check against the recursive
-		// JsonValue union doesn't see that through a plain interface -- the cast
-		// is a type-system limitation, not a runtime concern.
-		jsonSchema: { type: "object", properties: properties as unknown as JsonValue, required: [...required], additionalProperties: false },
-		safeParse(value) {
-			if (typeof value !== "object" || value === null || Array.isArray(value)) {
-				return { success: false, issues: [{ path: [], message: "input must be an object" }] };
-			}
-			const input = value as Record<string, unknown>;
-			for (const key of required) {
-				if (!(key in input)) return { success: false, issues: [{ path: [key], message: `${key} is required` }] };
-			}
-			for (const key of Object.keys(input)) {
-				if (!(key in properties)) return { success: false, issues: [{ path: [key], message: `${key} is not a recognized property` }] };
-			}
-			for (const [key, schema] of Object.entries(properties)) {
-				if (!(key in input)) continue;
-				if (!matchesLooseObjectPropertyType(schema.type, input[key])) {
-					return { success: false, issues: [{ path: [key], message: `${key} must be of type ${schema.type}` }] };
-				}
-				if (schema.enum && !schema.enum.includes(input[key] as string)) {
-					return { success: false, issues: [{ path: [key], message: `${key} must be one of ${schema.enum.join(", ")}` }] };
-				}
-			}
-			return { success: true, value: input };
-		},
-	});
-}
-
-/** Accepts any value unvalidated -- for an operation whose output shape isn't worth a dedicated schema (an internal/low-stakes result, or one already validated upstream by the domain logic it wraps). */
-export const passthroughVehicleSchema: VehicleSchemaCodec<unknown> = defineVehicleSchema<unknown>({
-	jsonSchema: { type: "object" },
-	safeParse: (value) => ({ success: true, value }),
-});
-
-/**
- * A block of narrative text meant to be read by the model, not parsed as
- * data -- same field name and shape MCP's own CallToolResult.content and
- * Pi's own ToolDefinition.execute() return already use, so a Vehicle
- * operation adopting this needs no translation layer at either boundary.
- * Only the "text" variant exists here; there's no Vehicle use case yet for
- * MCP's image/audio/resource-link block kinds.
- */
-export interface VehicleContentBlock {
-	readonly type: "text";
-	readonly text: string;
-}
-
-/**
- * An operation's Output type can intersect this to carry its own
- * model-facing narrative alongside its structured data, e.g.
- * `type RunOutput = { runId: string; created: Task[] } & WithVehicleContent`.
- * The operation itself builds `content` since it's the only code that
- * actually knows how to describe what it computed -- never a per-consumer
- * override bolted on wherever the operation happens to get registered.
- */
-export interface WithVehicleContent {
-	readonly content?: readonly VehicleContentBlock[];
-}
-
-/**
- * Reads an operation's own `content` blocks off its output when present and
- * well-formed, so a generic Vehicle client can prefer them over dumping raw
- * JSON at the model -- without knowing anything about the operation's own
- * domain shape. Returns undefined for a malformed or absent `content` field;
- * the caller falls back to its own default (formatted JSON) rather than
- * risk forwarding partial/garbled blocks.
- */
-export function extractVehicleContent(output: unknown): readonly VehicleContentBlock[] | undefined {
-	if (typeof output !== "object" || output === null || Array.isArray(output)) return undefined;
-	const content = (output as { readonly content?: unknown }).content;
-	if (!Array.isArray(content) || content.length === 0) return undefined;
-	const blocks: VehicleContentBlock[] = [];
-	for (const block of content) {
-		if (typeof block !== "object" || block === null) return undefined;
-		const { type, text } = block as { readonly type?: unknown; readonly text?: unknown };
-		if (type !== "text" || typeof text !== "string") return undefined;
-		blocks.push({ type: "text", text });
-	}
-	return blocks;
-}
-
-/** Canonical list VehicleEffect is itself derived from, so a runtime discriminator check (e.g. a persisted/wire VehicleApprovalRequest's own `effect` field) has one real source to check against instead of a second, driftable hardcoded list. */
-export const VEHICLE_EFFECTS = ["read", "local-write", "external-write", "destructive", "open-world"] as const;
-export type VehicleEffect = (typeof VEHICLE_EFFECTS)[number];
-
-export type VehicleIdempotency =
-	| { readonly mode: "safe" }
-	| { readonly mode: "keyed"; readonly retentionMs: number }
-	| { readonly mode: "unsafe" };
-
-export interface VehicleLimits {
-	readonly defaultTimeoutMs: number;
-	readonly maxTimeoutMs: number;
-	readonly maxRequestBytes: number;
-	readonly maxResponseBytes: number;
-}
-
-/** One structured, documented failure mode a {@link VehicleOperationDescriptor} declares up front -- part of the operation's own serializable contract, not an ad hoc thrown Error a caller has to reverse-engineer from a message string. */
-export interface VehicleFailureDescriptor {
-	readonly code: string;
-	readonly description: string;
-}
-
-/** Declares an operation safe to run as a Vehicle Job (detached, polled/tailed/canceled by id). Absent means live-invoke only. */
-export interface VehicleBackgroundCapability {
-	readonly supported: true;
-	readonly defaultWakeBudget: VehicleJobWakeBudget;
-	readonly maxWakeBudget: VehicleJobWakeBudget;
-}
-
-/**
- * The serializable half of a Vehicle operation -- name, version, schemas,
- * ownership-implying permissions, effect classification, idempotency,
- * streaming/long-running capability, request/response limits, and declared
- * {@link VehicleFailureDescriptor} failure modes. Kept separate from the
- * executable {@link VehicleOperationHandler} on purpose: a manifest, a Pi
- * tool projection, or a client's own capability check can all inspect this
- * shape without ever touching (or needing to trust) the implementation
- * behind it.
- */
-export interface VehicleOperationDescriptor {
-	readonly name: string;
-	readonly version: number;
-	readonly description: string;
-	readonly inputSchema: JsonSchema;
-	readonly outputSchema: JsonSchema;
-	readonly permissions: readonly string[];
-	readonly effect: VehicleEffect;
-	readonly idempotency: VehicleIdempotency;
-	readonly streaming: boolean;
-	readonly longRunning: boolean;
-	readonly limits: VehicleLimits;
-	readonly errors: readonly VehicleFailureDescriptor[];
-	readonly background?: VehicleBackgroundCapability;
-	/**
-	 * Owner-declared override for whether this specific operation is ever a candidate for
-	 * approval gating, independent of its `effect`. Undefined (the default) means "derive it
-	 * from `effect` against the registry's own requireApprovalForEffects set instead" --
-	 * VehicleRegistry.manifest()'s own resolution rule, unchanged for every existing
-	 * operation that never sets this.
-	 *
-	 * Exists because VehicleEffect's five values are coarse enough that two operations a
-	 * real owner classifies very differently (e.g. "restart an already-installed,
-	 * already-vetted service" vs. "sync a read-only catalog mirror") can land in the same
-	 * effect bucket (both external-write) -- no single requireApprovalForEffects set can
-	 * gate one without also gating the other. The owner who registers the operation knows
-	 * its real risk far better than a 5-value enum can; this lets them say so directly.
-	 */
-	readonly requiresApproval?: boolean;
-}
-
-export interface VehicleOperation<Input, Output> {
-	readonly descriptor: VehicleOperationDescriptor;
-	readonly input: VehicleSchemaCodec<Input>;
-	readonly output: VehicleSchemaCodec<Output>;
-}
-
-export interface DefineVehicleOperationOptions<Input, Output> {
-	readonly name: string;
-	readonly version: number;
-	readonly description: string;
-	readonly input: VehicleSchemaCodec<Input>;
-	readonly output: VehicleSchemaCodec<Output>;
-	readonly permissions?: readonly string[];
-	readonly effect: VehicleEffect;
-	readonly idempotency: VehicleIdempotency;
-	readonly streaming?: boolean;
-	readonly longRunning?: boolean;
-	readonly limits: VehicleLimits;
-	readonly errors?: readonly VehicleFailureDescriptor[];
-	readonly background?: VehicleBackgroundCapability;
-	/** See {@link VehicleOperationDescriptor.requiresApproval}. */
-	readonly requiresApproval?: boolean;
-}
-
-export interface VehiclePrincipal {
-	readonly id: string;
-	readonly claims?: Readonly<Record<string, JsonValue>>;
-}
-
-/**
- * callerSessionId/callerProjectRoot identify the real host session (e.g. one Pi TUI process) that
- * originated this call, and its working directory at call time -- a generic ownership/attribution
- * hook any operation handler can read (e.g. scoping a background subscription to the session or
- * project that created it), distinct from both:
- *  - correlationId: a caller-CHOSEN id deliberately meant to span several separate invoke() calls
- *    (a batch/business-transaction id), not an automatically-derived caller identity.
- *  - principal: broader identity/claims used for permission and approval decisions, usually a
- *    fixed per-extension value (e.g. {id: "pi-pipes"}), not a distinguishing per-session id.
- * A Pi projection layer (see vehicle-client-pi's invokeVehicleOperation) auto-derives both from
- * context.sessionManager.getSessionId()/context.cwd on every call, the same way it already
- * auto-derives correlationId -- a handler that never reads them pays nothing extra.
- */
-export interface VehicleInvocationOptions {
-	readonly operationId?: string;
-	readonly correlationId?: string;
-	readonly callerSessionId?: string;
-	readonly callerProjectRoot?: string;
-	readonly signal?: AbortSignal;
-	readonly deadline?: number;
-	readonly permissions?: readonly string[];
-	readonly principal?: VehiclePrincipal;
-	readonly idempotencyKey?: string;
-	readonly expectedRevision?: string | number;
-	readonly approvalCapability?: string;
-	readonly onProgress?: (progress: unknown) => void;
-}
-
-export interface VehicleOperationContext<Input> {
-	readonly input: Input;
-	readonly operationId: string;
-	readonly correlationId?: string;
-	/** See VehicleInvocationOptions's own doc comment. */
-	readonly callerSessionId?: string;
-	/** See VehicleInvocationOptions's own doc comment. */
-	readonly callerProjectRoot?: string;
-	readonly signal: AbortSignal;
-	readonly deadline: number;
-	readonly permissions: readonly string[];
-	readonly principal?: VehiclePrincipal;
-	readonly idempotencyKey?: string;
-	readonly expectedRevision?: string | number;
-	readonly approvalCapability?: string;
-	/** Set only for a job execution (VehicleJobStore.submit()); undefined for a plain invoke(). A handler that wants mid-flight input opts in with `for await (const input of context.steerInputs ?? [])`. */
-	readonly steerInputs?: AsyncIterable<unknown>;
-	reportProgress(progress: unknown): void;
-}
-
-export type VehicleOperationHandler<Input, Output> = (context: VehicleOperationContext<Input>) => Promise<Output>;
-
-export interface VehicleOperationBinding<Input, Output> {
-	readonly operation: VehicleOperation<Input, Output>;
-	bind(): VehicleOperationHandler<Input, Output>;
-}
-
-export interface VehicleManifestIdentity {
-	readonly name: string;
-	readonly version: string;
-	readonly description: string;
-	readonly guidance?: readonly string[];
-}
-
-/**
- * A manifest's own view of an operation: the static descriptor plus
- * whether it's currently usable on this particular server instance right
- * now. Availability is a runtime property of a live registry (a
- * credential got configured or removed), never baked into the static
- * descriptor defineVehicleOperation() produces -- two manifest() calls
- * against the same registry can report different availability for the
- * exact same descriptor.
- */
-export interface VehicleManifestOperation extends VehicleOperationDescriptor {
-	readonly available: boolean;
-	readonly unavailableReason?: string;
-	/**
-	 * The registry's own, live, fully-resolved answer to "does invoking this operation right
-	 * now require approval" -- accounts for the registry's current approval policy being
-	 * enabled/disabled, this operation's own `requiresApproval` override when set, and the
-	 * effect-derived default otherwise. A real VehicleRegistry.manifest() always sets this
-	 * (false when the registry never called configureApprovals() at all) -- unlike
-	 * `requiresApproval` (the static, author-declared override on the descriptor itself),
-	 * this always reflects the current instant, so a client re-fetching the manifest after a
-	 * live policy change (VehicleRegistry.updateApprovalPolicy) sees the new answer with no
-	 * separate sync mechanism needed.
-	 *
-	 * Optional purely for backward compatibility with every hand-authored VehicleManifest
-	 * test fixture across the ecosystem that predates this field (the same reason
-	 * VehicleManifest.events is optional) -- a consumer reading it should treat undefined the
-	 * same as a caller of classifyVehicleOperationSafety does: fall back to the effect-level
-	 * default, never assume false.
-	 */
-	readonly approvalRequired?: boolean;
-}
-
-/**
- * A named, schema'd event type a provider declares as part of its
- * manifest -- the typed alternative to a raw PushChannel.publish(topic,
- * payload) call with a hand-invented topic string. Confirmed independently
- * reinvented three-plus times across Papyrus and Lector before this
- * existed (see this task's own body). No `available` flag the way an
- * operation has one: an event type, once declared, is always emittable --
- * there's no credential-gated "this event is currently unavailable"
- * concept the way a live external-service-backed operation can have.
- */
-export interface VehicleEventDescriptor {
-	readonly name: string;
-	readonly version: number;
-	readonly description: string;
-	readonly payloadSchema: JsonSchema;
-	/** Same bounded-resource discipline as an operation's own maxRequestBytes/maxResponseBytes -- required, never silently defaulted. */
-	readonly maxPayloadBytes: number;
-}
-
-export interface VehicleEvent<Payload> {
-	readonly descriptor: VehicleEventDescriptor;
-	readonly payload: VehicleSchemaCodec<Payload>;
-}
-
-export interface DefineVehicleEventOptions<Payload> {
-	readonly name: string;
-	readonly version: number;
-	readonly description: string;
-	readonly payload: VehicleSchemaCodec<Payload>;
-	readonly maxPayloadBytes: number;
-}
-
-function validateEventMetadata<Payload>(options: DefineVehicleEventOptions<Payload>): void {
-	if (!options.name.trim()) throw new Error("Vehicle event name must not be empty");
-	if (!Number.isInteger(options.version) || options.version < 1) {
-		throw new Error("Vehicle event version must be a positive integer");
-	}
-	if (!options.description.trim()) throw new Error("Vehicle event description must not be empty");
-	if (!Number.isSafeInteger(options.maxPayloadBytes) || options.maxPayloadBytes < 1) {
-		throw new Error("Vehicle event maxPayloadBytes must be a positive integer");
-	}
-}
-
-export function defineVehicleEvent<Payload>(options: DefineVehicleEventOptions<Payload>): VehicleEvent<Payload> {
-	validateEventMetadata(options);
-	const descriptor: VehicleEventDescriptor = Object.freeze({
-		name: options.name,
-		version: options.version,
-		description: options.description,
-		payloadSchema: cloneJson(options.payload.jsonSchema),
-		maxPayloadBytes: options.maxPayloadBytes,
-	});
-	return Object.freeze({ descriptor, payload: options.payload });
-}
-
-export type VehicleManifestEvent = VehicleEventDescriptor;
-
-export type VehicleEventHandler<Payload> = (payload: Payload) => void;
-
-export interface VehicleSubscription {
-	close(): void;
-}
-
-/**
- * The wire topic name a bridge (bridgeVehicleEventsToPushChannel, in
- * vehicle-server) publishes an event under, and a subscriber
- * (RemoteVehicleClient.subscribe()) subscribes to -- one shared naming
- * function in vehicle-core so both sides can never drift apart on the
- * convention, the same failure mode this primitive exists to prevent
- * providers from reinventing per-project.
- */
-export function vehicleEventTopic(name: string, version: number): string {
-	return `vehicle-event:${name}@${version}`;
-}
-
-/**
- * `events` is optional purely for backward compatibility with every
- * hand-authored VehicleManifest test fixture across the ecosystem that
- * predates this field -- a real VehicleRegistry.manifest() always
- * populates it (as [] when no events are declared), never omits it.
- */
-export interface VehicleManifest extends VehicleManifestIdentity {
-	readonly operations: readonly VehicleManifestOperation[];
-	readonly events?: readonly VehicleManifestEvent[];
-}
-
-export interface VehicleClient {
-	manifest(): Promise<VehicleManifest>;
-	invoke<Output = unknown>(name: string, version: number, input: unknown, options?: VehicleInvocationOptions): Promise<Output>;
-	close(): Promise<void>;
-	/**
-	 * Vehicle Jobs -- submit a background-capable operation (one whose descriptor declares
-	 * `background`, see {@link VehicleBackgroundCapability}) and get its jobId back immediately,
-	 * without waiting for the operation itself to make any progress. Optional: a client that
-	 * never talks to a job-capable Vehicle (or a hand-rolled test double) simply omits these five
-	 * methods, exactly like this interface's own long-standing `subscribe()`-shaped extras --
-	 * present on both LocalVehicleClient and RemoteVehicleClient, absent elsewhere. Feature-detect
-	 * via the operation's own manifest `background` capability, not by probing for these methods.
-	 */
-	submitJob?(name: string, version: number, input: unknown, options?: VehicleJobSubmitOptions): Promise<VehicleJobSubmitResult>;
-	/** Never blocks -- current status, plus output/error once terminal. */
-	pollJob?(jobId: string): Promise<VehicleJobSnapshot>;
-	/** Progress entries strictly after `cursor` (0 for everything so far), plus the next cursor. Never blocks. */
-	tailJob?(jobId: string, cursor?: number): Promise<VehicleJobTailResult>;
-	/** Pushes new input to an already-running job's handler, if it opted in via context.steerInputs. */
-	steerJob?(jobId: string, input: unknown): Promise<void>;
-	/** Best-effort cancellation of a still-running job -- a no-op against an already-terminal one. */
-	cancelJob?(jobId: string): Promise<void>;
-}
-
-export function defineVehicleOperation<Input, Output>(
-	options: DefineVehicleOperationOptions<Input, Output>,
-): VehicleOperation<Input, Output> {
-	validateOperationMetadata(options);
-	const descriptor: VehicleOperationDescriptor = Object.freeze({
-		name: options.name,
-		version: options.version,
-		description: options.description,
-		inputSchema: cloneJson(options.input.jsonSchema),
-		outputSchema: cloneJson(options.output.jsonSchema),
-		permissions: Object.freeze([...(options.permissions ?? [])]),
-		effect: options.effect,
-		idempotency: Object.freeze({ ...options.idempotency }),
-		streaming: options.streaming ?? false,
-		longRunning: options.longRunning ?? false,
-		limits: Object.freeze({ ...options.limits }),
-		errors: Object.freeze((options.errors ?? []).map((failure) => Object.freeze({ ...failure }))),
-		...(options.requiresApproval !== undefined ? { requiresApproval: options.requiresApproval } : {}),
-		...(options.background
-			? {
-					background: Object.freeze({
-						supported: true as const,
-						defaultWakeBudget: Object.freeze({ ...options.background.defaultWakeBudget }),
-						maxWakeBudget: Object.freeze({ ...options.background.maxWakeBudget }),
-					}),
-				}
-			: {}),
-	});
-	return Object.freeze({ descriptor, input: options.input, output: options.output });
-}
-
-export function bindVehicleOperation<Input, Output>(
-	operation: VehicleOperation<Input, Output>,
-	bind: () => VehicleOperationHandler<Input, Output>,
-): VehicleOperationBinding<Input, Output> {
-	return Object.freeze({ operation, bind });
-}
-
-function validateOperationMetadata<Input, Output>(options: DefineVehicleOperationOptions<Input, Output>): void {
-	if (!options.name.trim()) throw new Error("Vehicle operation name must not be empty");
-	if (!Number.isInteger(options.version) || options.version < 1) {
-		throw new Error("Vehicle operation version must be a positive integer");
-	}
-	if (!options.description.trim()) throw new Error("Vehicle operation description must not be empty");
-	for (const permission of options.permissions ?? []) {
-		if (!permission.trim()) throw new Error("Vehicle operation permissions must not contain an empty value");
-	}
-	const limits = options.limits;
-	for (const [name, value] of Object.entries(limits)) {
-		if (!Number.isSafeInteger(value) || value < 1) throw new Error(`Vehicle operation ${name} must be a positive integer`);
-	}
-	if (limits.defaultTimeoutMs > limits.maxTimeoutMs) {
-		throw new Error("Vehicle operation defaultTimeoutMs must not exceed maxTimeoutMs");
-	}
-	if (
-		options.idempotency.mode === "keyed" &&
-		(!Number.isSafeInteger(options.idempotency.retentionMs) || options.idempotency.retentionMs < 1)
-	) {
-		throw new Error("Vehicle keyed idempotency retentionMs must be a positive integer");
-	}
-	if (options.background) {
-		if (!options.longRunning) {
-			throw new Error("Vehicle operation with a background capability must also set longRunning: true");
-		}
-		for (const [budgetName, budget] of [
-			["defaultWakeBudget", options.background.defaultWakeBudget],
-			["maxWakeBudget", options.background.maxWakeBudget],
-		] as const) {
-			if (!Number.isSafeInteger(budget.maxCount) || budget.maxCount < 1) {
-				throw new Error(`Vehicle operation background.${budgetName}.maxCount must be a positive integer`);
-			}
-			if (!Number.isSafeInteger(budget.maxBytes) || budget.maxBytes < 1) {
-				throw new Error(`Vehicle operation background.${budgetName}.maxBytes must be a positive integer`);
-			}
-		}
-		if (options.background.defaultWakeBudget.maxCount > options.background.maxWakeBudget.maxCount) {
-			throw new Error("Vehicle operation background.defaultWakeBudget.maxCount must not exceed maxWakeBudget.maxCount");
-		}
-		if (options.background.defaultWakeBudget.maxBytes > options.background.maxWakeBudget.maxBytes) {
-			throw new Error("Vehicle operation background.defaultWakeBudget.maxBytes must not exceed maxWakeBudget.maxBytes");
-		}
-	}
-}
-
-function cloneJson<T extends JsonValue>(value: T): T {
-	const serialized = JSON.stringify(value);
-	if (serialized === undefined) throw new Error("Vehicle JSON metadata must be serializable");
-	return freezeJson(JSON.parse(serialized) as JsonValue) as T;
-}
-
-function freezeJson(value: JsonValue): JsonValue {
-	if (Array.isArray(value)) return Object.freeze(value.map(freezeJson));
-	if (value !== null && typeof value === "object") {
-		return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, child]) => [key, freezeJson(child)])));
-	}
-	return value;
-}