@danypops/vehicle-core 0.16.0 → 0.17.1

package/src/content/content.ts

@@ -0,0 +1,46 @@
+/**
+ * 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;
+}

package/src/content/index.ts

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

package/src/{vehicle-errors.ts → errors/error.ts}

@@ -1,4 +1,5 @@
-import type { JsonValue, VehicleSchemaIssue } from "./vehicle-contract.js";
+import type { VehicleSchemaIssue } from "../schemas/codec.js";
+import type { JsonValue } from "../schemas/json.js";
 
 const VEHICLE_ERROR_BRAND = Symbol.for("@danypops/vehicle-core/VehicleError");
 
@@ -26,6 +27,7 @@ export type VehicleCoreErrorCode =
 	| "handler-failed"
 	| "policy-failed"
 	| "idempotency-key-required"
+	| "idempotency-conflict"
 	| "client-closed"
 	| "operation-unavailable"
 	| "background-not-supported"
@@ -54,10 +56,10 @@ export interface VehicleFailure {
 export interface VehicleErrorOptions {
 	readonly category: VehicleFailureCategory;
 	readonly retryable?: boolean;
-	readonly retryAfterMs?: number;
-	readonly recovery?: VehicleRecovery;
-	readonly details?: JsonValue;
-	readonly operationId?: string;
+	readonly retryAfterMs?: number | undefined;
+	readonly recovery?: VehicleRecovery | undefined;
+	readonly details?: JsonValue | undefined;
+	readonly operationId?: string | undefined;
 	readonly cause?: unknown;
 	/** Includes cause's message in toFailure().causeMessage. Default false -- an arbitrary cause could carry a credential or internal detail. */
 	readonly exposeCause?: boolean;
@@ -112,10 +114,10 @@ export function defineErrorMapping(
 export class VehicleError extends Error {
 	readonly category: VehicleFailureCategory;
 	readonly retryable: boolean;
-	readonly retryAfterMs?: number;
-	readonly recovery?: VehicleRecovery;
-	readonly details?: JsonValue;
-	readonly operationId?: string;
+	readonly retryAfterMs?: number | undefined;
+	readonly recovery?: VehicleRecovery | undefined;
+	readonly details?: JsonValue | undefined;
+	readonly operationId?: string | undefined;
 	private readonly exposeCause: boolean;
 
 	constructor(
@@ -156,6 +158,27 @@ export function isVehicleError(value: unknown): value is VehicleError {
 	return value instanceof Error && Reflect.get(value, VEHICLE_ERROR_BRAND) === true;
 }
 
+/**
+ * Reconstructs a throwable VehicleError from a previously-serialized VehicleFailure -- the inverse
+ * of VehicleError.prototype.toFailure(), needed anywhere a wire-safe failure gets replayed as a
+ * real rejection later (e.g. VehicleIdempotencyPolicy replaying a settled failed receipt to a
+ * second caller reusing the same idempotency key). Lossy on purpose: a VehicleFailure never
+ * carries the original `cause` (toFailure() already reduced it to an optional bounded
+ * causeMessage per the throw site's own exposeCause choice), so the reconstructed error has no
+ * cause at all rather than fabricating one -- a replayed failure only needs to match the original
+ * code/category/message/details a caller would react to, not its internal cause chain.
+ */
+export function vehicleErrorFromFailure(failure: VehicleFailure): VehicleError {
+	return new VehicleError(failure.code, failure.message, {
+		category: failure.category,
+		retryable: failure.retryable,
+		retryAfterMs: failure.retryAfterMs,
+		recovery: failure.recovery,
+		details: failure.details,
+		operationId: failure.operationId,
+	});
+}
+
 const MAX_CAUSE_MESSAGE_LENGTH = 500;
 
 /** Extracts a bounded, wire-safe message from an unknown cause -- never the full stack trace, never an unbounded payload. */

package/src/errors/index.ts

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

package/src/events/event.ts

@@ -0,0 +1,72 @@
+import type { VehicleSchemaCodec } from "../schemas/codec.js";
+import { cloneJson, type JsonSchema } from "../schemas/json.js";
+
+/**
+ * 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. 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;
+
+/**
+ * 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}`;
+}

package/src/events/index.ts

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

package/src/idempotency/index.ts

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

package/src/idempotency/receipt.ts

@@ -0,0 +1,97 @@
+/**
+ * Pure pieces of Vehicle's bounded keyed-idempotency replay policy: the settled-receipt shape and
+ * its eviction-selection rule. Orchestration (in-flight dedup, persistence, fail-closed conflict
+ * detection) lives in vehicle-server's VehicleIdempotencyPolicy -- mirrors the vehicle-jobs.js /
+ * VehicleJobStore split (a pure, independently-testable bounded-retention rule here; the stateful
+ * store that calls it lives in vehicle-server).
+ */
+import type { VehicleFailure } from "../errors/error.js";
+
+/** A settled keyed-idempotency outcome -- exactly what gets replayed to a caller reusing the same key. Never carries the original request's raw input (only its hash is ever retained, see VehicleIdempotencyReceipt) and never a credential: `output`/`failure` are already what the operation would hand back to any caller, the same wire-safe boundary VehicleJobPersistedRecord's own `output`/`error` fields already cross. */
+export type VehicleIdempotencyResult =
+	| { readonly ok: true; readonly output: unknown }
+	| { readonly ok: false; readonly failure: VehicleFailure };
+
+/**
+ * One settled keyed-idempotency receipt. Deliberately excludes the original request's raw input --
+ * `inputHash` is the only trace of it retained, so a persisted receipt can never leak whatever the
+ * caller originally sent (which may carry sensitive arguments the operation's own output does not).
+ * A still-in-flight (pending) request has no receipt yet -- that bookkeeping is transient,
+ * in-memory-only state in VehicleIdempotencyPolicy, deliberately never a candidate for persistence
+ * or eviction (mirrors "a running job is never a candidate" in vehicle-jobs.js's own job eviction).
+ */
+export interface VehicleIdempotencyReceipt {
+	readonly key: string;
+	readonly operationName: string;
+	readonly operationVersion: number;
+	readonly inputHash: string;
+	readonly settledAt: number;
+	/** settledAt + the descriptor's own keyed retentionMs at the time this receipt settled. A receipt past this is no longer a valid replay -- see selectVehicleIdempotencyReceiptsForEviction. */
+	readonly expiresAt: number;
+	readonly result: VehicleIdempotencyResult;
+	/** Approximate serialized size of `result`, used only to enforce maxTotalBytes -- never exact byte-for-byte, matching every other Vehicle capacity bound's own "good enough to stay bounded" precedent (e.g. enforcePayloadSize). */
+	readonly sizeBytes: number;
+}
+
+/** Minimal shape selectVehicleIdempotencyReceiptsForEviction needs -- kept separate from VehicleIdempotencyReceipt's own `result` so a sweep never has to touch (or risk logging) the actual settled output/failure it's merely deciding whether to keep. */
+export interface VehicleIdempotencyEvictionCandidate {
+	readonly key: string;
+	readonly settledAt: number;
+	readonly expiresAt: number;
+	readonly sizeBytes: number;
+}
+
+export interface VehicleIdempotencyRetentionOptions {
+	/** Hard cap on total retained settled receipts. */
+	readonly maxEntries: number;
+	/** Hard cap on the sum of every retained receipt's own sizeBytes. */
+	readonly maxTotalBytes: number;
+	readonly now: number;
+}
+
+/**
+ * Pure eviction-selection policy for settled keyed-idempotency receipts, independently testable
+ * from VehicleIdempotencyPolicy's own bookkeeping -- mirrors selectVehicleJobsForEviction's own
+ * three-phase shape:
+ *
+ *  1. Any receipt already past its own `expiresAt` (a real per-operation retentionMs elapsed --
+ *     replaying it would no longer be correct, keeping it around would only be wasted memory).
+ *  2. If still over maxEntries once (1) is applied, the oldest remaining receipts by settledAt,
+ *     until back within budget.
+ *  3. If still over maxTotalBytes once (1)+(2) are applied, the oldest remaining receipts by
+ *     settledAt, until back within budget.
+ *
+ * A pending (still in-flight) request is never a candidate -- it has no receipt yet, so it can
+ * never appear in `candidates` at all; this function only ever sees settled ones.
+ */
+export function selectVehicleIdempotencyReceiptsForEviction(
+	candidates: readonly VehicleIdempotencyEvictionCandidate[],
+	options: VehicleIdempotencyRetentionOptions,
+): readonly string[] {
+	const byAgeAscending = (a: VehicleIdempotencyEvictionCandidate, b: VehicleIdempotencyEvictionCandidate) => a.settledAt - b.settledAt;
+
+	const evicted = new Set<string>();
+	for (const candidate of candidates) {
+		if (options.now >= candidate.expiresAt) evicted.add(candidate.key);
+	}
+
+	const remaining = () => candidates.filter((candidate) => !evicted.has(candidate.key));
+	if (remaining().length > options.maxEntries) {
+		const oldestFirst = remaining().sort(byAgeAscending);
+		for (const candidate of oldestFirst) {
+			if (remaining().length <= options.maxEntries) break;
+			evicted.add(candidate.key);
+		}
+	}
+
+	const totalBytes = () => remaining().reduce((sum, candidate) => sum + candidate.sizeBytes, 0);
+	if (totalBytes() > options.maxTotalBytes) {
+		const oldestFirst = remaining().sort(byAgeAscending);
+		for (const candidate of oldestFirst) {
+			if (totalBytes() <= options.maxTotalBytes) break;
+			evicted.add(candidate.key);
+		}
+	}
+
+	return [...evicted];
+}

package/src/index.ts

@@ -1,7 +1,26 @@
-export * from "./atomic-json.js";
-export * from "./vehicle-approvals.js";
-export * from "./vehicle-contract.js";
-export * from "./vehicle-errors.js";
-export * from "./vehicle-jobs.js";
-export * from "./vehicle-scheduler.js";
-export * from "./vehicle-watchers.js";
+/**
+ * Vehicle's runtime-neutral wire contract, organized by capability (see each
+ * subfolder's own index.ts) rather than one flat forest of vehicle-*.ts files:
+ * schemas (codecs, loose-object validation, credential presentation), content
+ * (model-facing narrative blocks), operations (descriptors, effect
+ * classification, invocation context), events, manifest, client (the port a
+ * caller programs against), approvals (the Approval Gate's wire shapes), jobs
+ * (Vehicle Jobs' pure pieces), schedules, watches, and persistence (atomic
+ * JSON -- a technical utility, not a Vehicle protocol capability, kept
+ * distinct for that reason). Every symbol below is re-exported unchanged
+ * from its historical flat-file home, so root-level `import { X } from
+ * "@danypops/vehicle-core"` usage is completely unaffected by this layout.
+ */
+export * from "./approvals/index.js";
+export * from "./client/index.js";
+export * from "./content/index.js";
+export * from "./errors/index.js";
+export * from "./events/index.js";
+export * from "./idempotency/index.js";
+export * from "./jobs/index.js";
+export * from "./manifest/index.js";
+export * from "./operations/index.js";
+export * from "./persistence/index.js";
+export * from "./schedules/index.js";
+export * from "./schemas/index.js";
+export * from "./watches/index.js";

package/src/jobs/identity.ts

@@ -0,0 +1,13 @@
+/**
+ * Vehicle Jobs run as in-process promises, not child processes -- there is
+ * no PID to reuse, but a persisted job record written by one process
+ * instance must still never be mistaken for one this (possibly restarted)
+ * instance can still resolve. Each VehicleJobStore construction gets a
+ * fresh random instanceToken; a persisted record's own stamped token only
+ * ever matches the instance that wrote it. A mismatch means "the original
+ * run is gone" -- this instance should treat the record as orphaned rather
+ * than resolve it.
+ */
+export function vehicleJobIdentityMatches(recordInstanceToken: string, currentInstanceToken: string): boolean {
+	return recordInstanceToken === currentInstanceToken;
+}

package/src/jobs/index.ts

@@ -0,0 +1,7 @@
+export * from "./identity.js";
+export * from "./replay.js";
+export * from "./retention.js";
+export * from "./steer.js";
+export * from "./termination.js";
+export * from "./wake-log.js";
+export * from "./wire.js";

package/src/jobs/replay.ts

@@ -0,0 +1,17 @@
+import type { VehicleJobWakeEntry } from "./wake-log.js";
+
+/** Read-only replay side of a wake log -- both a live VehicleJobWakeLog and a restored (no-longer-appendable) job satisfy this with the same tail() semantics. */
+export interface VehicleJobWakeLogReader {
+	since(cursor: number): readonly VehicleJobWakeEntry[];
+	readonly cursor: number;
+}
+
+/** Wraps a fixed, already-finalized list of entries (e.g. restored from disk) in the same reader shape a live VehicleJobWakeLog exposes, so VehicleJobStore.tail() doesn't need to special-case a restored job. */
+export function createStaticVehicleJobWakeLog(entries: readonly VehicleJobWakeEntry[]): VehicleJobWakeLogReader {
+	const sorted = [...entries].sort((a, b) => a.seq - b.seq);
+	const cursor = sorted.length > 0 ? sorted[sorted.length - 1]!.seq : 0;
+	return {
+		since: (cursorArg) => sorted.filter((entry) => entry.seq > cursorArg),
+		cursor,
+	};
+}

package/src/jobs/retention.ts

@@ -0,0 +1,59 @@
+import type { VehicleJobStatus } from "./termination.js";
+
+/** Minimal shape selectVehicleJobsForEviction needs from a job record -- kept separate from VehicleJobSnapshot so vehicle-server doesn't have to construct a full snapshot just to ask "should this be swept". */
+export interface VehicleJobEvictionCandidate {
+	readonly jobId: string;
+	readonly status: VehicleJobStatus;
+	readonly delivered: boolean;
+	readonly updatedAt: number;
+}
+
+export interface VehicleJobRetentionOptions {
+	/** Hard cap on total retained job records (of any status). A running job is never evicted regardless of this cap. */
+	readonly maxRetainedJobs: number;
+	/** A delivered terminal job becomes eligible for eviction once this many ms have passed since it was delivered (== updatedAt at delivery time). */
+	readonly deliveredRetentionMs: number;
+	readonly now: number;
+}
+
+/**
+ * Pure eviction-selection policy, kept separate from VehicleJobStore's own
+ * bookkeeping so the bounded-retention rule is independently testable.
+ * Preference order: (1) delivered and past deliveredRetentionMs, oldest
+ * first; (2) once still over maxRetainedJobs, any delivered terminal job,
+ * oldest first; (3) only as a last resort, an undelivered terminal job,
+ * oldest first -- a real loss (a caller may still want that result), but
+ * an unbounded store is a worse failure mode. A running job is never a
+ * candidate.
+ */
+export function selectVehicleJobsForEviction(
+	candidates: readonly VehicleJobEvictionCandidate[],
+	options: VehicleJobRetentionOptions,
+): readonly string[] {
+	const terminal = candidates.filter((candidate) => candidate.status !== "running");
+	const byAgeAscending = (a: VehicleJobEvictionCandidate, b: VehicleJobEvictionCandidate) => a.updatedAt - b.updatedAt;
+
+	const evicted = new Set<string>();
+	for (const candidate of terminal) {
+		if (candidate.delivered && options.now - candidate.updatedAt >= options.deliveredRetentionMs) evicted.add(candidate.jobId);
+	}
+
+	const remainingCount = () => candidates.length - evicted.size;
+	if (remainingCount() > options.maxRetainedJobs) {
+		const deliveredOldestFirst = terminal.filter((candidate) => candidate.delivered && !evicted.has(candidate.jobId)).sort(byAgeAscending);
+		for (const candidate of deliveredOldestFirst) {
+			if (remainingCount() <= options.maxRetainedJobs) break;
+			evicted.add(candidate.jobId);
+		}
+	}
+	if (remainingCount() > options.maxRetainedJobs) {
+		const undeliveredOldestFirst = terminal
+			.filter((candidate) => !candidate.delivered && !evicted.has(candidate.jobId))
+			.sort(byAgeAscending);
+		for (const candidate of undeliveredOldestFirst) {
+			if (remainingCount() <= options.maxRetainedJobs) break;
+			evicted.add(candidate.jobId);
+		}
+	}
+	return [...evicted];
+}

package/src/jobs/steer.ts

@@ -0,0 +1,49 @@
+/**
+ * A job's mid-flight input channel -- the "steer" primitive. Bounded FIFO:
+ * push() while a handler isn't yet reading buffers up to maxQueueSize, then
+ * refuses further input rather than growing unboundedly or silently
+ * overwriting an unread entry. A handler consumes it via `for await (const
+ * input of context.steerInputs)`, which ends cleanly once close() is
+ * called (VehicleJobStore does this at job finalization).
+ */
+export interface VehicleJobSteerPushResult {
+	readonly accepted: boolean;
+	readonly dropReason?: "queue-full" | "channel-closed";
+}
+
+export class VehicleJobSteerChannel implements AsyncIterable<unknown> {
+	private readonly buffer: unknown[] = [];
+	private readonly waiters: ((result: IteratorResult<unknown>) => void)[] = [];
+	private closed = false;
+
+	constructor(private readonly maxQueueSize: number = 64) {}
+
+	push(value: unknown): VehicleJobSteerPushResult {
+		if (this.closed) return { accepted: false, dropReason: "channel-closed" };
+		const waiter = this.waiters.shift();
+		if (waiter) {
+			waiter({ value, done: false });
+			return { accepted: true };
+		}
+		if (this.buffer.length >= this.maxQueueSize) return { accepted: false, dropReason: "queue-full" };
+		this.buffer.push(value);
+		return { accepted: true };
+	}
+
+	/** Ends every pending and future iteration with done:true; further push() calls report "channel-closed". Idempotent. */
+	close(): void {
+		if (this.closed) return;
+		this.closed = true;
+		for (const waiter of this.waiters.splice(0)) waiter({ value: undefined, done: true });
+	}
+
+	[Symbol.asyncIterator](): AsyncIterator<unknown> {
+		return {
+			next: (): Promise<IteratorResult<unknown>> => {
+				if (this.buffer.length > 0) return Promise.resolve({ value: this.buffer.shift(), done: false });
+				if (this.closed) return Promise.resolve({ value: undefined, done: true });
+				return new Promise((resolve) => this.waiters.push(resolve));
+			},
+		};
+	}
+}

package/src/jobs/termination.ts

@@ -0,0 +1,13 @@
+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. "orphaned" is a restart-reconciliation outcome: a job that was still "running" when its process died, so nothing ever really failed or succeeded -- the record's own status just goes stale. */
+export const VEHICLE_JOB_TERMINATION_PRECEDENCE = ["canceled", "timeout", "orphaned", "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(", ")}`);
+}

package/src/jobs/wake-log.ts

@@ -0,0 +1,98 @@
+/** "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;
+}
+
+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);
+}
+
+/** 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;
+	}
+}

package/src/jobs/wire.ts

@@ -0,0 +1,51 @@
+import type { VehicleFailure } from "../errors/error.js";
+import type { VehiclePrincipal } from "../operations/context.js";
+import type { VehicleJobStatus, VehicleJobTerminationReason } from "./termination.js";
+import type { VehicleJobNotifyMode, VehicleJobWakeBudget, VehicleJobWakeEntry } from "./wake-log.js";
+
+/**
+ * The client-facing wire shapes for Vehicle Jobs -- submit/poll/tail options and results, shared by
+ * vehicle-server's VehicleJobStore (the orchestration side) and vehicle-client's job-capable clients
+ * (the calling side), so both halves of the wire agree on one definition instead of two structurally
+ * -identical copies drifting apart. Every field type referenced here already lives in vehicle-core
+ * (VehiclePrincipal, VehicleFailure, VehicleJobStatus, ...), which is what makes it safe for these
+ * shapes to live here too, alongside the rest of Vehicle Jobs' pure pieces.
+ */
+export interface VehicleJobSubmitOptions {
+	readonly permissions?: readonly string[];
+	readonly principal?: VehiclePrincipal;
+	readonly idempotencyKey?: string;
+	readonly expectedRevision?: string | number;
+	readonly approvalCapability?: string;
+	readonly correlationId?: string;
+	readonly callerSessionId?: string;
+	readonly callerProjectRoot?: string;
+	/** Defaults to "transition". */
+	readonly notifyMode?: VehicleJobNotifyMode;
+	/** Defaults to background.defaultWakeBudget; clamped to background.maxWakeBudget either way. */
+	readonly wakeBudget?: VehicleJobWakeBudget;
+	/** No default -- unset means the job runs until it settles or is canceled. */
+	readonly maxLifetimeMs?: number;
+}
+
+export interface VehicleJobSubmitResult {
+	readonly jobId: string;
+}
+
+export interface VehicleJobSnapshot {
+	readonly jobId: string;
+	readonly operationName: string;
+	readonly operationVersion: number;
+	readonly status: VehicleJobStatus;
+	readonly createdAt: number;
+	readonly updatedAt: number;
+	readonly delivered: boolean;
+	readonly terminationReason?: VehicleJobTerminationReason;
+	readonly output?: unknown;
+	readonly error?: VehicleFailure;
+}
+
+export interface VehicleJobTailResult {
+	readonly entries: readonly VehicleJobWakeEntry[];
+	readonly cursor: number;
+}

package/src/manifest/index.ts

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