@danypops/vehicle-core 0.1.0

package/README.md

@@ -0,0 +1,15 @@
+# @danypops/vehicle-core
+
+Vehicle's runtime-neutral wire contract: operation descriptors, schema
+codecs, and failure shapes. Zero runtime dependencies, zero Bun-specific
+code -- the one thing every Vehicle client and server package depends on.
+
+```bash
+bun add @danypops/vehicle-core
+```
+
+`defineVehicleOperation()`/`bindVehicleOperation()` build a serializable
+descriptor kept separate from its executable handler. See the
+[workspace README](https://github.com/DanyPops/daemon-kit#readme) for how it
+fits with `@danypops/vehicle-server`, `@danypops/vehicle-client`, and
+`@danypops/vehicle-client-pi`.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./vehicle-contract.js";
+export * from "./vehicle-errors.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from "./vehicle-contract.js";
+export * from "./vehicle-errors.js";

package/dist/vehicle-contract.d.ts

@@ -0,0 +1,136 @@
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+export type JsonSchema = Readonly<Record<string, JsonValue>>;
+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[];
+};
+export interface VehicleSchemaCodec<T> {
+    readonly jsonSchema: JsonSchema;
+    safeParse(value: unknown): VehicleSchemaResult<T>;
+}
+export declare function defineVehicleSchema<T>(codec: VehicleSchemaCodec<T>): VehicleSchemaCodec<T>;
+export type VehicleEffect = "read" | "local-write" | "external-write" | "destructive" | "open-world";
+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;
+}
+export interface VehicleFailureDescriptor {
+    readonly code: string;
+    readonly description: string;
+}
+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[];
+}
+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[];
+}
+export interface VehiclePrincipal {
+    readonly id: string;
+    readonly claims?: Readonly<Record<string, JsonValue>>;
+}
+export interface VehicleInvocationOptions {
+    readonly operationId?: string;
+    readonly correlationId?: 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;
+    readonly signal: AbortSignal;
+    readonly deadline: number;
+    readonly permissions: readonly string[];
+    readonly principal?: VehiclePrincipal;
+    readonly idempotencyKey?: string;
+    readonly expectedRevision?: string | number;
+    readonly approvalCapability?: string;
+    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;
+}
+export interface VehicleManifest extends VehicleManifestIdentity {
+    readonly operations: readonly VehicleManifestOperation[];
+}
+export interface VehicleClient {
+    manifest(): Promise<VehicleManifest>;
+    invoke<Output = unknown>(name: string, version: number, input: unknown, options?: VehicleInvocationOptions): Promise<Output>;
+    close(): Promise<void>;
+}
+export declare function defineVehicleOperation<Input, Output>(options: DefineVehicleOperationOptions<Input, Output>): VehicleOperation<Input, Output>;
+export declare function bindVehicleOperation<Input, Output>(operation: VehicleOperation<Input, Output>, bind: () => VehicleOperationHandler<Input, Output>): VehicleOperationBinding<Input, Output>;

package/dist/vehicle-contract.js

@@ -0,0 +1,65 @@
+export function defineVehicleSchema(codec) {
+    return Object.freeze({
+        jsonSchema: cloneJson(codec.jsonSchema),
+        safeParse: codec.safeParse,
+    });
+}
+export function defineVehicleOperation(options) {
+    validateOperationMetadata(options);
+    const descriptor = 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 }))),
+    });
+    return Object.freeze({ descriptor, input: options.input, output: options.output });
+}
+export function bindVehicleOperation(operation, bind) {
+    return Object.freeze({ operation, bind });
+}
+function validateOperationMetadata(options) {
+    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");
+    }
+}
+function cloneJson(value) {
+    const serialized = JSON.stringify(value);
+    if (serialized === undefined)
+        throw new Error("Vehicle JSON metadata must be serializable");
+    return freezeJson(JSON.parse(serialized));
+}
+function freezeJson(value) {
+    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;
+}

package/dist/vehicle-errors.d.ts

@@ -0,0 +1,38 @@
+import type { JsonValue, VehicleSchemaIssue } from "./vehicle-contract.js";
+export type VehicleFailureCategory = "validation" | "not_found" | "conflict" | "authorization" | "capacity" | "timeout" | "cancelled" | "unavailable" | "internal";
+export type VehicleCoreErrorCode = "duplicate-owner" | "not-found" | "invalid-input" | "invalid-output" | "permission-denied" | "request-too-large" | "response-too-large" | "cancelled" | "deadline-exceeded" | "handler-failed" | "policy-failed" | "idempotency-key-required" | "client-closed" | "operation-unavailable";
+export interface VehicleRecovery {
+    readonly operation?: string;
+    readonly message: string;
+}
+export interface VehicleFailure {
+    readonly code: string;
+    readonly category: VehicleFailureCategory;
+    readonly message: string;
+    readonly retryable: boolean;
+    readonly retryAfterMs?: number;
+    readonly recovery?: VehicleRecovery;
+    readonly details?: JsonValue;
+    readonly operationId?: string;
+}
+export interface VehicleErrorOptions {
+    readonly category: VehicleFailureCategory;
+    readonly retryable?: boolean;
+    readonly retryAfterMs?: number;
+    readonly recovery?: VehicleRecovery;
+    readonly details?: JsonValue;
+    readonly operationId?: string;
+    readonly cause?: unknown;
+}
+export declare class VehicleError extends Error {
+    readonly code: string;
+    readonly category: VehicleFailureCategory;
+    readonly retryable: boolean;
+    readonly retryAfterMs?: number;
+    readonly recovery?: VehicleRecovery;
+    readonly details?: JsonValue;
+    readonly operationId?: string;
+    constructor(code: string, message: string, options: VehicleErrorOptions);
+    toFailure(): VehicleFailure;
+}
+export declare function boundedValidationDetails(issues: readonly VehicleSchemaIssue[] | undefined): JsonValue | undefined;

package/dist/vehicle-errors.js

@@ -0,0 +1,46 @@
+export class VehicleError extends Error {
+    code;
+    category;
+    retryable;
+    retryAfterMs;
+    recovery;
+    details;
+    operationId;
+    constructor(code, message, options) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.code = code;
+        this.name = "VehicleError";
+        this.category = options.category;
+        this.retryable = options.retryable ?? false;
+        this.retryAfterMs = options.retryAfterMs;
+        this.recovery = options.recovery;
+        this.details = options.details;
+        this.operationId = options.operationId;
+    }
+    toFailure() {
+        return {
+            code: this.code,
+            category: this.category,
+            message: this.message,
+            retryable: this.retryable,
+            ...(this.retryAfterMs === undefined ? {} : { retryAfterMs: this.retryAfterMs }),
+            ...(this.recovery === undefined ? {} : { recovery: this.recovery }),
+            ...(this.details === undefined ? {} : { details: this.details }),
+            ...(this.operationId === undefined ? {} : { operationId: this.operationId }),
+        };
+    }
+}
+const MAX_VALIDATION_ISSUES = 10;
+const MAX_ISSUE_MESSAGE_LENGTH = 500;
+const MAX_ISSUE_PATH_LENGTH = 20;
+export function boundedValidationDetails(issues) {
+    if (!issues?.length)
+        return undefined;
+    return {
+        issues: issues.slice(0, MAX_VALIDATION_ISSUES).map((issue) => ({
+            path: issue.path.slice(0, MAX_ISSUE_PATH_LENGTH),
+            message: issue.message.slice(0, MAX_ISSUE_MESSAGE_LENGTH),
+        })),
+        ...(issues.length > MAX_VALIDATION_ISSUES ? { truncated: true } : {}),
+    };
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+	"name": "@danypops/vehicle-core",
+	"version": "0.1.0",
+	"description": "Vehicle's runtime-neutral wire contract: operation descriptors, schema codecs, failure shapes. Zero runtime dependencies, zero Bun-specific code -- the one thing every Vehicle client and server package depends on.",
+	"license": "MIT",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		}
+	},
+	"scripts": {
+		"build": "rm -rf dist && tsc -p tsconfig.build.json",
+		"test": "bun test test",
+		"typecheck": "tsc --noEmit"
+	},
+	"devDependencies": {
+		"@types/node": "^22.0.0",
+		"typescript": "latest"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/DanyPops/daemon-kit.git",
+		"directory": "packages/vehicle-core"
+	},
+	"keywords": ["vehicle", "agent-tools"],
+	"files": ["src", "dist", "README.md"]
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from "./vehicle-contract.js";
+export * from "./vehicle-errors.js";

package/src/vehicle-contract.ts

@@ -0,0 +1,217 @@
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | readonly JsonValue[] | { readonly [key: string]: JsonValue };
+export type JsonSchema = Readonly<Record<string, JsonValue>>;
+
+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[] };
+
+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 type VehicleEffect = "read" | "local-write" | "external-write" | "destructive" | "open-world";
+
+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;
+}
+
+export interface VehicleFailureDescriptor {
+	readonly code: string;
+	readonly description: string;
+}
+
+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[];
+}
+
+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[];
+}
+
+export interface VehiclePrincipal {
+	readonly id: string;
+	readonly claims?: Readonly<Record<string, JsonValue>>;
+}
+
+export interface VehicleInvocationOptions {
+	readonly operationId?: string;
+	readonly correlationId?: 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;
+	readonly signal: AbortSignal;
+	readonly deadline: number;
+	readonly permissions: readonly string[];
+	readonly principal?: VehiclePrincipal;
+	readonly idempotencyKey?: string;
+	readonly expectedRevision?: string | number;
+	readonly approvalCapability?: string;
+	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;
+}
+
+export interface VehicleManifest extends VehicleManifestIdentity {
+	readonly operations: readonly VehicleManifestOperation[];
+}
+
+export interface VehicleClient {
+	manifest(): Promise<VehicleManifest>;
+	invoke<Output = unknown>(
+		name: string,
+		version: number,
+		input: unknown,
+		options?: VehicleInvocationOptions,
+	): Promise<Output>;
+	close(): 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 }))),
+	});
+	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");
+	}
+}
+
+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;
+}

package/src/vehicle-errors.ts

@@ -0,0 +1,106 @@
+import type { JsonValue, VehicleSchemaIssue } from "./vehicle-contract.js";
+
+export type VehicleFailureCategory =
+	| "validation"
+	| "not_found"
+	| "conflict"
+	| "authorization"
+	| "capacity"
+	| "timeout"
+	| "cancelled"
+	| "unavailable"
+	| "internal";
+
+export type VehicleCoreErrorCode =
+	| "duplicate-owner"
+	| "not-found"
+	| "invalid-input"
+	| "invalid-output"
+	| "permission-denied"
+	| "request-too-large"
+	| "response-too-large"
+	| "cancelled"
+	| "deadline-exceeded"
+	| "handler-failed"
+	| "policy-failed"
+	| "idempotency-key-required"
+	| "client-closed"
+	| "operation-unavailable";
+
+export interface VehicleRecovery {
+	readonly operation?: string;
+	readonly message: string;
+}
+
+export interface VehicleFailure {
+	readonly code: string;
+	readonly category: VehicleFailureCategory;
+	readonly message: string;
+	readonly retryable: boolean;
+	readonly retryAfterMs?: number;
+	readonly recovery?: VehicleRecovery;
+	readonly details?: JsonValue;
+	readonly operationId?: string;
+}
+
+export interface VehicleErrorOptions {
+	readonly category: VehicleFailureCategory;
+	readonly retryable?: boolean;
+	readonly retryAfterMs?: number;
+	readonly recovery?: VehicleRecovery;
+	readonly details?: JsonValue;
+	readonly operationId?: string;
+	readonly cause?: unknown;
+}
+
+export class VehicleError extends Error {
+	readonly category: VehicleFailureCategory;
+	readonly retryable: boolean;
+	readonly retryAfterMs?: number;
+	readonly recovery?: VehicleRecovery;
+	readonly details?: JsonValue;
+	readonly operationId?: string;
+
+	constructor(
+		readonly code: string,
+		message: string,
+		options: VehicleErrorOptions,
+	) {
+		super(message, options.cause === undefined ? undefined : { cause: options.cause });
+		this.name = "VehicleError";
+		this.category = options.category;
+		this.retryable = options.retryable ?? false;
+		this.retryAfterMs = options.retryAfterMs;
+		this.recovery = options.recovery;
+		this.details = options.details;
+		this.operationId = options.operationId;
+	}
+
+	toFailure(): VehicleFailure {
+		return {
+			code: this.code,
+			category: this.category,
+			message: this.message,
+			retryable: this.retryable,
+			...(this.retryAfterMs === undefined ? {} : { retryAfterMs: this.retryAfterMs }),
+			...(this.recovery === undefined ? {} : { recovery: this.recovery }),
+			...(this.details === undefined ? {} : { details: this.details }),
+			...(this.operationId === undefined ? {} : { operationId: this.operationId }),
+		};
+	}
+}
+
+const MAX_VALIDATION_ISSUES = 10;
+const MAX_ISSUE_MESSAGE_LENGTH = 500;
+const MAX_ISSUE_PATH_LENGTH = 20;
+
+export function boundedValidationDetails(issues: readonly VehicleSchemaIssue[] | undefined): JsonValue | undefined {
+	if (!issues?.length) return undefined;
+	return {
+		issues: issues.slice(0, MAX_VALIDATION_ISSUES).map((issue) => ({
+			path: issue.path.slice(0, MAX_ISSUE_PATH_LENGTH),
+			message: issue.message.slice(0, MAX_ISSUE_MESSAGE_LENGTH),
+		})),
+		...(issues.length > MAX_VALIDATION_ISSUES ? { truncated: true } : {}),
+	};
+}