@danypops/vehicle-core 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./atomic-json.js";
 export * from "./vehicle-contract.js";
 export * from "./vehicle-errors.js";
+export * from "./vehicle-jobs.js";

package/dist/index.js

@@ -1,3 +1,4 @@
 export * from "./atomic-json.js";
 export * from "./vehicle-contract.js";
 export * from "./vehicle-errors.js";
+export * from "./vehicle-jobs.js";

package/dist/vehicle-contract.d.ts

@@ -1,3 +1,4 @@
+import type { VehicleJobWakeBudget } from "./vehicle-jobs.js";
 export type JsonPrimitive = string | number | boolean | null;
 export type JsonValue = JsonPrimitive | readonly JsonValue[] | {
     readonly [key: string]: JsonValue;
@@ -85,6 +86,12 @@ 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;
+}
 export interface VehicleOperationDescriptor {
     readonly name: string;
     readonly version: number;
@@ -98,6 +105,7 @@ export interface VehicleOperationDescriptor {
     readonly longRunning: boolean;
     readonly limits: VehicleLimits;
     readonly errors: readonly VehicleFailureDescriptor[];
+    readonly background?: VehicleBackgroundCapability;
 }
 export interface VehicleOperation<Input, Output> {
     readonly descriptor: VehicleOperationDescriptor;
@@ -117,6 +125,7 @@ export interface DefineVehicleOperationOptions<Input, Output> {
     readonly longRunning?: boolean;
     readonly limits: VehicleLimits;
     readonly errors?: readonly VehicleFailureDescriptor[];
+    readonly background?: VehicleBackgroundCapability;
 }
 export interface VehiclePrincipal {
     readonly id: string;

package/dist/vehicle-contract.js

@@ -84,6 +84,15 @@ export function defineVehicleOperation(options) {
         longRunning: options.longRunning ?? false,
         limits: Object.freeze({ ...options.limits }),
         errors: Object.freeze((options.errors ?? []).map((failure) => Object.freeze({ ...failure }))),
+        ...(options.background
+            ? {
+                background: Object.freeze({
+                    supported: true,
+                    defaultWakeBudget: Object.freeze({ ...options.background.defaultWakeBudget }),
+                    maxWakeBudget: Object.freeze({ ...options.background.maxWakeBudget }),
+                }),
+            }
+            : {}),
     });
     return Object.freeze({ descriptor, input: options.input, output: options.output });
 }
@@ -114,6 +123,28 @@ function validateOperationMetadata(options) {
         (!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],
+        ]) {
+            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(value) {
     const serialized = JSON.stringify(value);

package/dist/vehicle-errors.d.ts

@@ -1,6 +1,6 @@
 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 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" | "background-not-supported" | "job-not-found";
 export interface VehicleRecovery {
     readonly operation?: string;
     readonly message: string;

package/dist/vehicle-jobs.d.ts

@@ -0,0 +1,45 @@
+/** Pure pieces of Vehicle Jobs: a termination-reason resolver and a bounded wake-log accumulator. Orchestration lives in vehicle-server's VehicleJobStore. */
+export type VehicleJobStatus = "running" | "succeeded" | "failed" | "canceled";
+/** Highest precedence first -- an explicit cancel always wins even if the handler also settled around the same time. */
+export declare const VEHICLE_JOB_TERMINATION_PRECEDENCE: readonly ["canceled", "timeout", "failed", "succeeded"];
+export type VehicleJobTerminationReason = (typeof VEHICLE_JOB_TERMINATION_PRECEDENCE)[number];
+export declare function resolveVehicleJobTerminationReason(candidates: readonly VehicleJobTerminationReason[]): VehicleJobTerminationReason;
+/** "always" keeps every notification; "transition" drops one identical to the last (hash dedup); "first-only" keeps just the first. */
+export type VehicleJobNotifyMode = "always" | "transition" | "first-only";
+export interface VehicleJobWakeBudget {
+    readonly maxCount: number;
+    readonly maxBytes: number;
+}
+export type VehicleJobWakeDropReason = "count-budget-exhausted" | "byte-budget-exhausted" | "deduplicated-transition" | "superseded-by-first-only";
+export interface VehicleJobWakeEntry {
+    readonly seq: number;
+    readonly at: number;
+    readonly progress: unknown;
+}
+export interface VehicleJobWakeAppendResult {
+    readonly accepted: boolean;
+    readonly entry?: VehicleJobWakeEntry;
+    readonly dropReason?: VehicleJobWakeDropReason;
+}
+export interface VehicleJobWakeLogOptions {
+    readonly notifyMode: VehicleJobNotifyMode;
+    readonly budget: VehicleJobWakeBudget;
+    /** Defaults to Date.now. */
+    readonly now?: () => number;
+}
+/** Bounds a job's accumulated progress notifications by count+bytes, same discipline as enforcePayloadSize but across a job's whole lifetime. */
+export declare class VehicleJobWakeLog {
+    private readonly options;
+    private readonly entries;
+    private usedBytes;
+    private nextSeq;
+    private lastHash;
+    private acceptedFirst;
+    private readonly now;
+    constructor(options: VehicleJobWakeLogOptions);
+    append(progress: unknown): VehicleJobWakeAppendResult;
+    /** Entries with seq strictly greater than `cursor`. */
+    since(cursor: number): readonly VehicleJobWakeEntry[];
+    /** Highest seq issued so far (0 if none accepted yet). */
+    get cursor(): number;
+}

package/dist/vehicle-jobs.js

@@ -0,0 +1,77 @@
+/** Pure pieces of Vehicle Jobs: a termination-reason resolver and a bounded wake-log accumulator. Orchestration lives in vehicle-server's VehicleJobStore. */
+/** Highest precedence first -- an explicit cancel always wins even if the handler also settled around the same time. */
+export const VEHICLE_JOB_TERMINATION_PRECEDENCE = ["canceled", "timeout", "failed", "succeeded"];
+export function resolveVehicleJobTerminationReason(candidates) {
+    if (candidates.length === 0)
+        throw new Error("resolveVehicleJobTerminationReason requires at least one candidate");
+    for (const reason of VEHICLE_JOB_TERMINATION_PRECEDENCE) {
+        if (candidates.includes(reason))
+            return reason;
+    }
+    throw new Error(`Unrecognized Vehicle job termination candidate(s): ${candidates.join(", ")}`);
+}
+/** Bounds a job's accumulated progress notifications by count+bytes, same discipline as enforcePayloadSize but across a job's whole lifetime. */
+export class VehicleJobWakeLog {
+    options;
+    entries = [];
+    usedBytes = 0;
+    nextSeq = 1;
+    lastHash;
+    acceptedFirst = false;
+    now;
+    constructor(options) {
+        this.options = options;
+        this.now = options.now ?? Date.now;
+    }
+    append(progress) {
+        if (this.options.notifyMode === "first-only" && this.acceptedFirst) {
+            return { accepted: false, dropReason: "superseded-by-first-only" };
+        }
+        const serialized = safeJsonStringify(progress);
+        if (this.options.notifyMode === "transition") {
+            const hash = fnv1aHash(serialized);
+            if (hash === this.lastHash)
+                return { accepted: false, dropReason: "deduplicated-transition" };
+            this.lastHash = hash;
+        }
+        const bytes = new TextEncoder().encode(serialized).byteLength;
+        if (this.entries.length >= this.options.budget.maxCount)
+            return { accepted: false, dropReason: "count-budget-exhausted" };
+        if (this.usedBytes + bytes > this.options.budget.maxBytes)
+            return { accepted: false, dropReason: "byte-budget-exhausted" };
+        const entry = { seq: this.nextSeq++, at: this.now(), progress };
+        this.entries.push(entry);
+        this.usedBytes += bytes;
+        this.acceptedFirst = true;
+        return { accepted: true, entry };
+    }
+    /** Entries with seq strictly greater than `cursor`. */
+    since(cursor) {
+        return this.entries.filter((entry) => entry.seq > cursor);
+    }
+    /** Highest seq issued so far (0 if none accepted yet). */
+    get cursor() {
+        return this.nextSeq - 1;
+    }
+}
+function safeJsonStringify(value) {
+    let serialized;
+    try {
+        serialized = JSON.stringify(value);
+    }
+    catch (error) {
+        throw new Error("Vehicle job progress value is not JSON-serializable", { cause: error });
+    }
+    if (serialized === undefined)
+        throw new Error("Vehicle job progress value is not JSON-serializable");
+    return serialized;
+}
+/** Non-cryptographic (FNV-1a) -- dedup only. */
+function fnv1aHash(value) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < value.length; i++) {
+        hash ^= value.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0).toString(16);
+}

package/package.json

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

package/src/index.ts

@@ -1,3 +1,4 @@
 export * from "./atomic-json.js";
 export * from "./vehicle-contract.js";
 export * from "./vehicle-errors.js";
+export * from "./vehicle-jobs.js";

package/src/vehicle-contract.ts

@@ -1,3 +1,5 @@
+import type { 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>>;
@@ -137,6 +139,13 @@ export interface VehicleFailureDescriptor {
 	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;
+}
+
 export interface VehicleOperationDescriptor {
 	readonly name: string;
 	readonly version: number;
@@ -150,6 +159,7 @@ export interface VehicleOperationDescriptor {
 	readonly longRunning: boolean;
 	readonly limits: VehicleLimits;
 	readonly errors: readonly VehicleFailureDescriptor[];
+	readonly background?: VehicleBackgroundCapability;
 }
 
 export interface VehicleOperation<Input, Output> {
@@ -171,6 +181,7 @@ export interface DefineVehicleOperationOptions<Input, Output> {
 	readonly longRunning?: boolean;
 	readonly limits: VehicleLimits;
 	readonly errors?: readonly VehicleFailureDescriptor[];
+	readonly background?: VehicleBackgroundCapability;
 }
 
 export interface VehiclePrincipal {
@@ -260,6 +271,15 @@ export function defineVehicleOperation<Input, Output>(
 		longRunning: options.longRunning ?? false,
 		limits: Object.freeze({ ...options.limits }),
 		errors: Object.freeze((options.errors ?? []).map((failure) => Object.freeze({ ...failure }))),
+		...(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 });
 }
@@ -293,6 +313,28 @@ function validateOperationMetadata<Input, Output>(options: DefineVehicleOperatio
 	) {
 		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 {

package/src/vehicle-errors.ts

@@ -25,7 +25,9 @@ export type VehicleCoreErrorCode =
 	| "policy-failed"
 	| "idempotency-key-required"
 	| "client-closed"
-	| "operation-unavailable";
+	| "operation-unavailable"
+	| "background-not-supported"
+	| "job-not-found";
 
 export interface VehicleRecovery {
 	readonly operation?: string;

package/src/vehicle-jobs.ts

@@ -0,0 +1,114 @@
+/** Pure pieces of Vehicle Jobs: a termination-reason resolver and a bounded wake-log accumulator. Orchestration lives in vehicle-server's VehicleJobStore. */
+
+export type VehicleJobStatus = "running" | "succeeded" | "failed" | "canceled";
+
+/** Highest precedence first -- an explicit cancel always wins even if the handler also settled around the same time. */
+export const VEHICLE_JOB_TERMINATION_PRECEDENCE = ["canceled", "timeout", "failed", "succeeded"] as const;
+export type VehicleJobTerminationReason = (typeof VEHICLE_JOB_TERMINATION_PRECEDENCE)[number];
+
+export function resolveVehicleJobTerminationReason(candidates: readonly VehicleJobTerminationReason[]): VehicleJobTerminationReason {
+	if (candidates.length === 0) throw new Error("resolveVehicleJobTerminationReason requires at least one candidate");
+	for (const reason of VEHICLE_JOB_TERMINATION_PRECEDENCE) {
+		if (candidates.includes(reason)) return reason;
+	}
+	throw new Error(`Unrecognized Vehicle job termination candidate(s): ${candidates.join(", ")}`);
+}
+
+/** "always" keeps every notification; "transition" drops one identical to the last (hash dedup); "first-only" keeps just the first. */
+export type VehicleJobNotifyMode = "always" | "transition" | "first-only";
+
+export interface VehicleJobWakeBudget {
+	readonly maxCount: number;
+	readonly maxBytes: number;
+}
+
+export type VehicleJobWakeDropReason =
+	| "count-budget-exhausted"
+	| "byte-budget-exhausted"
+	| "deduplicated-transition"
+	| "superseded-by-first-only";
+
+export interface VehicleJobWakeEntry {
+	readonly seq: number;
+	readonly at: number;
+	readonly progress: unknown;
+}
+
+export interface VehicleJobWakeAppendResult {
+	readonly accepted: boolean;
+	readonly entry?: VehicleJobWakeEntry;
+	readonly dropReason?: VehicleJobWakeDropReason;
+}
+
+export interface VehicleJobWakeLogOptions {
+	readonly notifyMode: VehicleJobNotifyMode;
+	readonly budget: VehicleJobWakeBudget;
+	/** Defaults to Date.now. */
+	readonly now?: () => number;
+}
+
+/** Bounds a job's accumulated progress notifications by count+bytes, same discipline as enforcePayloadSize but across a job's whole lifetime. */
+export class VehicleJobWakeLog {
+	private readonly entries: VehicleJobWakeEntry[] = [];
+	private usedBytes = 0;
+	private nextSeq = 1;
+	private lastHash: string | undefined;
+	private acceptedFirst = false;
+	private readonly now: () => number;
+
+	constructor(private readonly options: VehicleJobWakeLogOptions) {
+		this.now = options.now ?? Date.now;
+	}
+
+	append(progress: unknown): VehicleJobWakeAppendResult {
+		if (this.options.notifyMode === "first-only" && this.acceptedFirst) {
+			return { accepted: false, dropReason: "superseded-by-first-only" };
+		}
+		const serialized = safeJsonStringify(progress);
+		if (this.options.notifyMode === "transition") {
+			const hash = fnv1aHash(serialized);
+			if (hash === this.lastHash) return { accepted: false, dropReason: "deduplicated-transition" };
+			this.lastHash = hash;
+		}
+		const bytes = new TextEncoder().encode(serialized).byteLength;
+		if (this.entries.length >= this.options.budget.maxCount) return { accepted: false, dropReason: "count-budget-exhausted" };
+		if (this.usedBytes + bytes > this.options.budget.maxBytes) return { accepted: false, dropReason: "byte-budget-exhausted" };
+
+		const entry: VehicleJobWakeEntry = { seq: this.nextSeq++, at: this.now(), progress };
+		this.entries.push(entry);
+		this.usedBytes += bytes;
+		this.acceptedFirst = true;
+		return { accepted: true, entry };
+	}
+
+	/** Entries with seq strictly greater than `cursor`. */
+	since(cursor: number): readonly VehicleJobWakeEntry[] {
+		return this.entries.filter((entry) => entry.seq > cursor);
+	}
+
+	/** Highest seq issued so far (0 if none accepted yet). */
+	get cursor(): number {
+		return this.nextSeq - 1;
+	}
+}
+
+function safeJsonStringify(value: unknown): string {
+	let serialized: string | undefined;
+	try {
+		serialized = JSON.stringify(value);
+	} catch (error) {
+		throw new Error("Vehicle job progress value is not JSON-serializable", { cause: error });
+	}
+	if (serialized === undefined) throw new Error("Vehicle job progress value is not JSON-serializable");
+	return serialized;
+}
+
+/** Non-cryptographic (FNV-1a) -- dedup only. */
+function fnv1aHash(value: string): string {
+	let hash = 0x811c9dc5;
+	for (let i = 0; i < value.length; i++) {
+		hash ^= value.charCodeAt(i);
+		hash = Math.imul(hash, 0x01000193);
+	}
+	return (hash >>> 0).toString(16);
+}