@danypops/vehicle-core 0.19.0 → 0.19.1

package/dist/client/client.d.ts

@@ -1,11 +1,14 @@
 import type { VehicleJobSnapshot, VehicleJobSubmitOptions, VehicleJobSubmitResult, VehicleJobTailResult } from "../jobs/wire.js";
 import type { VehicleManifest } from "../manifest/manifest.js";
 import type { VehicleInvocationOptions } from "../operations/context.js";
+import type { VehicleProtocolAgreement, VehicleProtocolOffer } from "../protocol/negotiation.js";
 export interface VehicleSubscription {
     close(): void;
 }
 export interface VehicleClient {
     manifest(): Promise<VehicleManifest>;
+    /** Optional for compatibility with clients authored before explicit wire negotiation. */
+    negotiate?(offer: VehicleProtocolOffer): Promise<VehicleProtocolAgreement>;
     invoke<Output = unknown>(name: string, version: number, input: unknown, options?: VehicleInvocationOptions): Promise<Output>;
     close(): Promise<void>;
     /**

package/dist/client/index.d.ts

@@ -1 +1,2 @@
 export * from "./client.js";
+export * from "./invocation-outcome.js";

package/dist/client/index.js

@@ -1 +1,2 @@
 export * from "./client.js";
+export * from "./invocation-outcome.js";

package/dist/client/invocation-outcome.d.ts

@@ -0,0 +1,29 @@
+import { type VehicleFailure } from "../errors/error.js";
+import type { VehicleInvocationOptions } from "../operations/context.js";
+import type { VehicleClient } from "./client.js";
+export type VehicleInvocationOutcome<Output> = {
+    readonly ok: true;
+    readonly value: Output;
+} | {
+    readonly ok: false;
+    readonly kind: "vehicle-failure";
+    readonly failure: VehicleFailure;
+} | {
+    readonly ok: false;
+    readonly kind: "cancelled";
+    readonly message: string;
+    readonly operationId?: string;
+} | {
+    readonly ok: false;
+    readonly kind: "transport-failure";
+    readonly message: string;
+    readonly retryable: true;
+    readonly operationId?: string;
+} | {
+    readonly ok: false;
+    readonly kind: "unexpected-failure";
+    readonly message: string;
+    readonly operationId?: string;
+};
+/** Invokes one Vehicle operation while representing expected and boundary failures as typed values. */
+export declare function invokeVehicleOutcome<Output = unknown>(client: VehicleClient, name: string, version: number, input: unknown, options?: VehicleInvocationOptions): Promise<VehicleInvocationOutcome<Output>>;

package/dist/client/invocation-outcome.js

@@ -0,0 +1,19 @@
+import { isVehicleError } from "../errors/error.js";
+/** Invokes one Vehicle operation while representing expected and boundary failures as typed values. */
+export async function invokeVehicleOutcome(client, name, version, input, options = {}) {
+    try {
+        return { ok: true, value: await client.invoke(name, version, input, options) };
+    }
+    catch (error) {
+        if (isVehicleError(error))
+            return { ok: false, kind: "vehicle-failure", failure: error.toFailure() };
+        const operation = options.operationId === undefined ? {} : { operationId: options.operationId };
+        if (error instanceof Error && error.name === "AbortError") {
+            return { ok: false, kind: "cancelled", message: "Vehicle invocation was cancelled", ...operation };
+        }
+        if (error instanceof TypeError) {
+            return { ok: false, kind: "transport-failure", message: "Vehicle transport failed", retryable: true, ...operation };
+        }
+        return { ok: false, kind: "unexpected-failure", message: "Vehicle invocation failed unexpectedly", ...operation };
+    }
+}

package/dist/index.d.ts

@@ -26,6 +26,7 @@ export * from "./jobs/index.js";
 export * from "./manifest/index.js";
 export * from "./operations/index.js";
 export * from "./persistence/index.js";
+export * from "./protocol/index.js";
 export * from "./resource-pool/index.js";
 export * from "./schedules/index.js";
 export * from "./schemas/index.js";

package/dist/index.js

@@ -26,6 +26,7 @@ export * from "./jobs/index.js";
 export * from "./manifest/index.js";
 export * from "./operations/index.js";
 export * from "./persistence/index.js";
+export * from "./protocol/index.js";
 export * from "./resource-pool/index.js";
 export * from "./schedules/index.js";
 export * from "./schemas/index.js";

package/dist/manifest/manifest.d.ts

@@ -1,10 +1,13 @@
 import type { VehicleManifestEvent } from "../events/event.js";
 import type { VehicleOperationDescriptor } from "../operations/operation.js";
+import type { VehicleProtocolSupport } from "../protocol/negotiation.js";
 export interface VehicleManifestIdentity {
     readonly name: string;
     readonly version: string;
     readonly description: string;
     readonly guidance?: readonly string[];
+    /** Wire compatibility served independently from this package's version and each operation's version. */
+    readonly protocol?: VehicleProtocolSupport;
 }
 /**
  * A manifest's own view of an operation: the static descriptor plus

package/dist/protocol/index.d.ts

@@ -0,0 +1 @@
+export * from "./negotiation.js";

package/dist/protocol/index.js

@@ -0,0 +1 @@
+export * from "./negotiation.js";

package/dist/protocol/negotiation.d.ts

@@ -0,0 +1,36 @@
+export declare const VEHICLE_PROTOCOL_VERSION = 1;
+export declare const MAX_VEHICLE_PROTOCOL_CAPABILITIES = 64;
+export declare const MAX_VEHICLE_PROTOCOL_CAPABILITY_LENGTH = 128;
+export declare const MAX_VEHICLE_PROTOCOL_OFFER_BYTES: number;
+/** Describes the wire versions and optional features one Vehicle server can serve. */
+export interface VehicleProtocolSupport {
+    readonly minimumVersion: number;
+    readonly maximumVersion: number;
+    readonly capabilities: readonly string[];
+}
+/** Describes the compatibility range and features one client requests before invoking operations. */
+export interface VehicleProtocolOffer {
+    readonly minimumVersion: number;
+    readonly maximumVersion: number;
+    readonly requiredCapabilities: readonly string[];
+    readonly optionalCapabilities: readonly string[];
+}
+/** Records the highest shared wire version and capabilities accepted by both peers. */
+export interface VehicleProtocolAgreement {
+    readonly version: number;
+    readonly capabilities: readonly string[];
+}
+export type VehicleProtocolNegotiationFailureCode = "protocol-offer-invalid" | "protocol-support-invalid" | "protocol-version-incompatible" | "protocol-capability-unsupported";
+export type VehicleProtocolNegotiationResult = {
+    readonly ok: true;
+    readonly value: VehicleProtocolAgreement;
+} | {
+    readonly ok: false;
+    readonly code: VehicleProtocolNegotiationFailureCode;
+    readonly message: string;
+};
+export declare const DEFAULT_VEHICLE_PROTOCOL_SUPPORT: VehicleProtocolSupport;
+/** Validates a protocol agreement received across an untrusted wire boundary. */
+export declare function isVehicleProtocolAgreement(value: unknown): value is VehicleProtocolAgreement;
+/** Negotiates one bounded protocol agreement without performing transport I/O. */
+export declare function negotiateVehicleProtocol(support: VehicleProtocolSupport, offer: VehicleProtocolOffer): VehicleProtocolNegotiationResult;

package/dist/protocol/negotiation.js

@@ -0,0 +1,71 @@
+export const VEHICLE_PROTOCOL_VERSION = 1;
+export const MAX_VEHICLE_PROTOCOL_CAPABILITIES = 64;
+export const MAX_VEHICLE_PROTOCOL_CAPABILITY_LENGTH = 128;
+export const MAX_VEHICLE_PROTOCOL_OFFER_BYTES = 16 * 1024;
+export const DEFAULT_VEHICLE_PROTOCOL_SUPPORT = Object.freeze({
+    minimumVersion: VEHICLE_PROTOCOL_VERSION,
+    maximumVersion: VEHICLE_PROTOCOL_VERSION,
+    capabilities: Object.freeze([]),
+});
+function validVersionRange(minimumVersion, maximumVersion) {
+    return (Number.isSafeInteger(minimumVersion) && minimumVersion > 0 && Number.isSafeInteger(maximumVersion) && maximumVersion >= minimumVersion);
+}
+function validCapabilities(capabilities) {
+    if (!Array.isArray(capabilities) || capabilities.length > MAX_VEHICLE_PROTOCOL_CAPABILITIES)
+        return false;
+    const unique = new Set();
+    for (const capability of capabilities) {
+        if (!capability.trim() || capability.length > MAX_VEHICLE_PROTOCOL_CAPABILITY_LENGTH || unique.has(capability))
+            return false;
+        unique.add(capability);
+    }
+    return true;
+}
+/** Validates a protocol agreement received across an untrusted wire boundary. */
+export function isVehicleProtocolAgreement(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const agreement = value;
+    return Number.isSafeInteger(agreement.version) && agreement.version > 0 && validCapabilities(agreement.capabilities);
+}
+/** Negotiates one bounded protocol agreement without performing transport I/O. */
+export function negotiateVehicleProtocol(support, offer) {
+    if (!validVersionRange(support.minimumVersion, support.maximumVersion) || !validCapabilities(support.capabilities)) {
+        return {
+            ok: false,
+            code: "protocol-support-invalid",
+            message: "Vehicle protocol support is malformed or exceeds its capability bound",
+        };
+    }
+    if (!validVersionRange(offer.minimumVersion, offer.maximumVersion) ||
+        !validCapabilities(offer.requiredCapabilities) ||
+        !validCapabilities(offer.optionalCapabilities) ||
+        offer.requiredCapabilities.length + offer.optionalCapabilities.length > MAX_VEHICLE_PROTOCOL_CAPABILITIES) {
+        return { ok: false, code: "protocol-offer-invalid", message: "Vehicle protocol offer is malformed or exceeds its capability bound" };
+    }
+    const minimumSharedVersion = Math.max(support.minimumVersion, offer.minimumVersion);
+    const maximumSharedVersion = Math.min(support.maximumVersion, offer.maximumVersion);
+    if (minimumSharedVersion > maximumSharedVersion) {
+        return {
+            ok: false,
+            code: "protocol-version-incompatible",
+            message: `Vehicle protocol versions do not overlap: server ${support.minimumVersion}-${support.maximumVersion}, client ${offer.minimumVersion}-${offer.maximumVersion}`,
+        };
+    }
+    const supported = new Set(support.capabilities);
+    for (const capability of offer.requiredCapabilities) {
+        if (!supported.has(capability)) {
+            return {
+                ok: false,
+                code: "protocol-capability-unsupported",
+                message: `Vehicle protocol requires unsupported capability "${capability}"`,
+            };
+        }
+    }
+    const capabilities = [...offer.requiredCapabilities];
+    for (const capability of offer.optionalCapabilities) {
+        if (supported.has(capability) && !capabilities.includes(capability))
+            capabilities.push(capability);
+    }
+    return { ok: true, value: Object.freeze({ version: maximumSharedVersion, capabilities: Object.freeze(capabilities) }) };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@danypops/vehicle-core",
-	"version": "0.19.0",
+	"version": "0.19.1",
 	"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",

package/src/client/client.ts

@@ -1,6 +1,7 @@
 import type { VehicleJobSnapshot, VehicleJobSubmitOptions, VehicleJobSubmitResult, VehicleJobTailResult } from "../jobs/wire.js";
 import type { VehicleManifest } from "../manifest/manifest.js";
 import type { VehicleInvocationOptions } from "../operations/context.js";
+import type { VehicleProtocolAgreement, VehicleProtocolOffer } from "../protocol/negotiation.js";
 
 export interface VehicleSubscription {
 	close(): void;
@@ -8,6 +9,8 @@ export interface VehicleSubscription {
 
 export interface VehicleClient {
 	manifest(): Promise<VehicleManifest>;
+	/** Optional for compatibility with clients authored before explicit wire negotiation. */
+	negotiate?(offer: VehicleProtocolOffer): Promise<VehicleProtocolAgreement>;
 	invoke<Output = unknown>(name: string, version: number, input: unknown, options?: VehicleInvocationOptions): Promise<Output>;
 	close(): Promise<void>;
 	/**

package/src/client/index.ts

@@ -1 +1,2 @@
 export * from "./client.js";
+export * from "./invocation-outcome.js";

package/src/client/invocation-outcome.ts

@@ -0,0 +1,39 @@
+import { isVehicleError, type VehicleFailure } from "../errors/error.js";
+import type { VehicleInvocationOptions } from "../operations/context.js";
+import type { VehicleClient } from "./client.js";
+
+export type VehicleInvocationOutcome<Output> =
+	| { readonly ok: true; readonly value: Output }
+	| { readonly ok: false; readonly kind: "vehicle-failure"; readonly failure: VehicleFailure }
+	| { readonly ok: false; readonly kind: "cancelled"; readonly message: string; readonly operationId?: string }
+	| {
+			readonly ok: false;
+			readonly kind: "transport-failure";
+			readonly message: string;
+			readonly retryable: true;
+			readonly operationId?: string;
+	  }
+	| { readonly ok: false; readonly kind: "unexpected-failure"; readonly message: string; readonly operationId?: string };
+
+/** Invokes one Vehicle operation while representing expected and boundary failures as typed values. */
+export async function invokeVehicleOutcome<Output = unknown>(
+	client: VehicleClient,
+	name: string,
+	version: number,
+	input: unknown,
+	options: VehicleInvocationOptions = {},
+): Promise<VehicleInvocationOutcome<Output>> {
+	try {
+		return { ok: true, value: await client.invoke<Output>(name, version, input, options) };
+	} catch (error) {
+		if (isVehicleError(error)) return { ok: false, kind: "vehicle-failure", failure: error.toFailure() };
+		const operation = options.operationId === undefined ? {} : { operationId: options.operationId };
+		if (error instanceof Error && error.name === "AbortError") {
+			return { ok: false, kind: "cancelled", message: "Vehicle invocation was cancelled", ...operation };
+		}
+		if (error instanceof TypeError) {
+			return { ok: false, kind: "transport-failure", message: "Vehicle transport failed", retryable: true, ...operation };
+		}
+		return { ok: false, kind: "unexpected-failure", message: "Vehicle invocation failed unexpectedly", ...operation };
+	}
+}

package/src/index.ts

@@ -26,6 +26,7 @@ export * from "./jobs/index.js";
 export * from "./manifest/index.js";
 export * from "./operations/index.js";
 export * from "./persistence/index.js";
+export * from "./protocol/index.js";
 export * from "./resource-pool/index.js";
 export * from "./schedules/index.js";
 export * from "./schemas/index.js";

package/src/manifest/manifest.ts

@@ -1,11 +1,14 @@
 import type { VehicleManifestEvent } from "../events/event.js";
 import type { VehicleOperationDescriptor } from "../operations/operation.js";
+import type { VehicleProtocolSupport } from "../protocol/negotiation.js";
 
 export interface VehicleManifestIdentity {
 	readonly name: string;
 	readonly version: string;
 	readonly description: string;
 	readonly guidance?: readonly string[];
+	/** Wire compatibility served independently from this package's version and each operation's version. */
+	readonly protocol?: VehicleProtocolSupport;
 }
 
 /**

package/src/protocol/index.ts

@@ -0,0 +1 @@
+export * from "./negotiation.js";

package/src/protocol/negotiation.ts

@@ -0,0 +1,110 @@
+export const VEHICLE_PROTOCOL_VERSION = 1;
+export const MAX_VEHICLE_PROTOCOL_CAPABILITIES = 64;
+export const MAX_VEHICLE_PROTOCOL_CAPABILITY_LENGTH = 128;
+export const MAX_VEHICLE_PROTOCOL_OFFER_BYTES = 16 * 1024;
+
+/** Describes the wire versions and optional features one Vehicle server can serve. */
+export interface VehicleProtocolSupport {
+	readonly minimumVersion: number;
+	readonly maximumVersion: number;
+	readonly capabilities: readonly string[];
+}
+
+/** Describes the compatibility range and features one client requests before invoking operations. */
+export interface VehicleProtocolOffer {
+	readonly minimumVersion: number;
+	readonly maximumVersion: number;
+	readonly requiredCapabilities: readonly string[];
+	readonly optionalCapabilities: readonly string[];
+}
+
+/** Records the highest shared wire version and capabilities accepted by both peers. */
+export interface VehicleProtocolAgreement {
+	readonly version: number;
+	readonly capabilities: readonly string[];
+}
+
+export type VehicleProtocolNegotiationFailureCode =
+	| "protocol-offer-invalid"
+	| "protocol-support-invalid"
+	| "protocol-version-incompatible"
+	| "protocol-capability-unsupported";
+
+export type VehicleProtocolNegotiationResult =
+	| { readonly ok: true; readonly value: VehicleProtocolAgreement }
+	| { readonly ok: false; readonly code: VehicleProtocolNegotiationFailureCode; readonly message: string };
+
+export const DEFAULT_VEHICLE_PROTOCOL_SUPPORT: VehicleProtocolSupport = Object.freeze({
+	minimumVersion: VEHICLE_PROTOCOL_VERSION,
+	maximumVersion: VEHICLE_PROTOCOL_VERSION,
+	capabilities: Object.freeze([]),
+});
+
+function validVersionRange(minimumVersion: number, maximumVersion: number): boolean {
+	return (
+		Number.isSafeInteger(minimumVersion) && minimumVersion > 0 && Number.isSafeInteger(maximumVersion) && maximumVersion >= minimumVersion
+	);
+}
+
+function validCapabilities(capabilities: unknown): capabilities is readonly string[] {
+	if (!Array.isArray(capabilities) || capabilities.length > MAX_VEHICLE_PROTOCOL_CAPABILITIES) return false;
+	const unique = new Set<string>();
+	for (const capability of capabilities) {
+		if (!capability.trim() || capability.length > MAX_VEHICLE_PROTOCOL_CAPABILITY_LENGTH || unique.has(capability)) return false;
+		unique.add(capability);
+	}
+	return true;
+}
+
+/** Validates a protocol agreement received across an untrusted wire boundary. */
+export function isVehicleProtocolAgreement(value: unknown): value is VehicleProtocolAgreement {
+	if (typeof value !== "object" || value === null) return false;
+	const agreement = value as { version?: unknown; capabilities?: unknown };
+	return Number.isSafeInteger(agreement.version) && (agreement.version as number) > 0 && validCapabilities(agreement.capabilities);
+}
+
+/** Negotiates one bounded protocol agreement without performing transport I/O. */
+export function negotiateVehicleProtocol(support: VehicleProtocolSupport, offer: VehicleProtocolOffer): VehicleProtocolNegotiationResult {
+	if (!validVersionRange(support.minimumVersion, support.maximumVersion) || !validCapabilities(support.capabilities)) {
+		return {
+			ok: false,
+			code: "protocol-support-invalid",
+			message: "Vehicle protocol support is malformed or exceeds its capability bound",
+		};
+	}
+	if (
+		!validVersionRange(offer.minimumVersion, offer.maximumVersion) ||
+		!validCapabilities(offer.requiredCapabilities) ||
+		!validCapabilities(offer.optionalCapabilities) ||
+		offer.requiredCapabilities.length + offer.optionalCapabilities.length > MAX_VEHICLE_PROTOCOL_CAPABILITIES
+	) {
+		return { ok: false, code: "protocol-offer-invalid", message: "Vehicle protocol offer is malformed or exceeds its capability bound" };
+	}
+
+	const minimumSharedVersion = Math.max(support.minimumVersion, offer.minimumVersion);
+	const maximumSharedVersion = Math.min(support.maximumVersion, offer.maximumVersion);
+	if (minimumSharedVersion > maximumSharedVersion) {
+		return {
+			ok: false,
+			code: "protocol-version-incompatible",
+			message: `Vehicle protocol versions do not overlap: server ${support.minimumVersion}-${support.maximumVersion}, client ${offer.minimumVersion}-${offer.maximumVersion}`,
+		};
+	}
+
+	const supported = new Set(support.capabilities);
+	for (const capability of offer.requiredCapabilities) {
+		if (!supported.has(capability)) {
+			return {
+				ok: false,
+				code: "protocol-capability-unsupported",
+				message: `Vehicle protocol requires unsupported capability "${capability}"`,
+			};
+		}
+	}
+
+	const capabilities = [...offer.requiredCapabilities];
+	for (const capability of offer.optionalCapabilities) {
+		if (supported.has(capability) && !capabilities.includes(capability)) capabilities.push(capability);
+	}
+	return { ok: true, value: Object.freeze({ version: maximumSharedVersion, capabilities: Object.freeze(capabilities) }) };
+}