@danypops/vehicle-core 0.17.0 → 0.17.1

package/README.md

@@ -22,3 +22,15 @@ tool-result type use, so no translation layer is needed at either boundary.
 `extractVehicleContent(output)` reads those blocks back out for a generic
 Vehicle client to prefer over raw JSON, returning undefined for absent or
 malformed content so the caller can fall back safely.
+
+## Layout
+
+`src/` is organized by capability, not by feature-flat filename prefix:
+`operations/`, `events/`, `manifest/`, `client/`, `schemas/`, `content/`,
+`approvals/`, `jobs/`, `schedules/`, `watches/`, and `errors/`/`idempotency/`
+each hold one cohesive concern; `persistence/` (atomic JSON writes) is kept
+separate as a technical utility, not a Vehicle protocol capability. Every
+public symbol is re-exported unchanged from the package root
+(`import { X } from "@danypops/vehicle-core"`); `./persistence` is also
+available as its own subpath export for a consumer that only needs the
+atomic-write primitive without the rest of the wire contract.

package/dist/{vehicle-approvals.d.ts → approvals/approval.d.ts}

@@ -1,12 +1,5 @@
-/**
- * Wire-level shapes for the Approval Gate: a pending human/authority decision
- * that stands between a gated-effect invoke() and its handler actually
- * running. Kept in vehicle-core (runtime-neutral, zero dependencies) --
- * the actual signing/verification authority (HmacApprovalAuthority) needs
- * node:crypto and lives in vehicle-server instead, the same split
- * atomic-json.ts already uses for fs access.
- */
-import type { VehicleEffect, VehiclePrincipal } from "./vehicle-contract.js";
+import type { VehiclePrincipal } from "../operations/context.js";
+import type { VehicleEffect } from "../operations/effect.js";
 /** Set once at registry-configuration time (VehicleRegistry.configureApprovals()); never on a per-invoke basis. */
 export declare const DEFAULT_APPROVAL_EFFECTS: readonly VehicleEffect[];
 /**
@@ -59,5 +52,5 @@ export interface VehicleApprovalAuthority {
     verify(capability: string, operationName: string, operationVersion: number, inputHash: string): boolean;
 }
 /** Built into every VehicleRegistry once configureApprovals() is called -- never registered unconditionally, so a Vehicle that never opts in has zero manifest/shape change. */
-export declare const vehicleApprovalRequestedEvent: import("./vehicle-contract.js").VehicleEvent<VehicleApprovalRequest>;
-export declare const vehicleApprovalResolvedEvent: import("./vehicle-contract.js").VehicleEvent<VehicleApprovalOutcome>;
+export declare const vehicleApprovalRequestedEvent: import("../events/event.js").VehicleEvent<VehicleApprovalRequest>;
+export declare const vehicleApprovalResolvedEvent: import("../events/event.js").VehicleEvent<VehicleApprovalOutcome>;

package/dist/{vehicle-approvals.js → approvals/approval.js}

@@ -1,4 +1,14 @@
-import { defineVehicleEvent, defineVehicleSchema, VEHICLE_EFFECTS } from "./vehicle-contract.js";
+/**
+ * Wire-level shapes for the Approval Gate: a pending human/authority decision
+ * that stands between a gated-effect invoke() and its handler actually
+ * running. Kept in vehicle-core (runtime-neutral, zero dependencies) --
+ * the actual signing/verification authority (HmacApprovalAuthority) needs
+ * node:crypto and lives in vehicle-server instead, the same split
+ * atomic-json.ts already uses for fs access.
+ */
+import { defineVehicleEvent } from "../events/event.js";
+import { VEHICLE_EFFECTS } from "../operations/effect.js";
+import { defineVehicleSchema } from "../schemas/codec.js";
 /** A sha256 hex digest: exactly 64 lowercase hex characters -- matches hashApprovalInput's own (vehicle-server) output shape. */
 const SHA256_HEX_PATTERN = /^[0-9a-f]{64}$/;
 function isVehicleEffect(value) {
@@ -8,11 +18,11 @@ function isVehiclePrincipal(value) {
     if (typeof value !== "object" || value === null)
         return false;
     const candidate = value;
-    if (typeof candidate.id !== "string")
+    if (typeof candidate["id"] !== "string")
         return false;
-    if (candidate.claims === undefined)
+    if (candidate["claims"] === undefined)
         return true;
-    return typeof candidate.claims === "object" && candidate.claims !== null && !Array.isArray(candidate.claims);
+    return typeof candidate["claims"] === "object" && candidate["claims"] !== null && !Array.isArray(candidate["claims"]);
 }
 /** Set once at registry-configuration time (VehicleRegistry.configureApprovals()); never on a per-invoke basis. */
 export const DEFAULT_APPROVAL_EFFECTS = ["destructive", "open-world"];
@@ -49,21 +59,21 @@ const requestedPayloadSchema = defineVehicleSchema({
         if (typeof value !== "object" || value === null)
             return { success: false, issues: [{ path: [], message: "input must be an object" }] };
         const row = value;
-        if (typeof row.requestId !== "string" ||
-            typeof row.operationName !== "string" ||
-            typeof row.operationVersion !== "number" ||
-            !Number.isInteger(row.operationVersion) ||
-            row.operationVersion < 1 ||
-            !isVehicleEffect(row.effect) ||
-            typeof row.requestedAt !== "number" ||
-            !Number.isFinite(row.requestedAt) ||
-            typeof row.expiresAt !== "number" ||
-            !Number.isFinite(row.expiresAt) ||
-            typeof row.inputHash !== "string" ||
-            !SHA256_HEX_PATTERN.test(row.inputHash)) {
+        if (typeof row["requestId"] !== "string" ||
+            typeof row["operationName"] !== "string" ||
+            typeof row["operationVersion"] !== "number" ||
+            !Number.isInteger(row["operationVersion"]) ||
+            row["operationVersion"] < 1 ||
+            !isVehicleEffect(row["effect"]) ||
+            typeof row["requestedAt"] !== "number" ||
+            !Number.isFinite(row["requestedAt"]) ||
+            typeof row["expiresAt"] !== "number" ||
+            !Number.isFinite(row["expiresAt"]) ||
+            typeof row["inputHash"] !== "string" ||
+            !SHA256_HEX_PATTERN.test(row["inputHash"])) {
             return { success: false, issues: [{ path: [], message: "invalid approval request payload" }] };
         }
-        if (row.principal !== undefined && !isVehiclePrincipal(row.principal)) {
+        if (row["principal"] !== undefined && !isVehiclePrincipal(row["principal"])) {
             return { success: false, issues: [{ path: ["principal"], message: "invalid approval request principal" }] };
         }
         return { success: true, value: row };
@@ -86,16 +96,16 @@ const resolvedPayloadSchema = defineVehicleSchema({
         if (typeof value !== "object" || value === null)
             return { success: false, issues: [{ path: [], message: "input must be an object" }] };
         const row = value;
-        if (typeof row.requestId !== "string" ||
-            (row.decision !== "granted" && row.decision !== "denied") ||
-            typeof row.decidedAt !== "number" ||
-            !Number.isFinite(row.decidedAt)) {
+        if (typeof row["requestId"] !== "string" ||
+            (row["decision"] !== "granted" && row["decision"] !== "denied") ||
+            typeof row["decidedAt"] !== "number" ||
+            !Number.isFinite(row["decidedAt"])) {
             return { success: false, issues: [{ path: [], message: "invalid approval outcome payload" }] };
         }
-        if (row.decidedBy !== undefined && typeof row.decidedBy !== "string") {
+        if (row["decidedBy"] !== undefined && typeof row["decidedBy"] !== "string") {
             return { success: false, issues: [{ path: ["decidedBy"], message: "decidedBy must be a string" }] };
         }
-        if (row.comment !== undefined && typeof row.comment !== "string") {
+        if (row["comment"] !== undefined && typeof row["comment"] !== "string") {
             return { success: false, issues: [{ path: ["comment"], message: "comment must be a string" }] };
         }
         return { success: true, value: row };

package/dist/approvals/index.d.ts

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

package/dist/approvals/index.js

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

package/dist/client/client.d.ts

@@ -0,0 +1,29 @@
+import type { VehicleJobSnapshot, VehicleJobSubmitOptions, VehicleJobSubmitResult, VehicleJobTailResult } from "../jobs/wire.js";
+import type { VehicleManifest } from "../manifest/manifest.js";
+import type { VehicleInvocationOptions } from "../operations/context.js";
+export interface VehicleSubscription {
+    close(): void;
+}
+export interface VehicleClient {
+    manifest(): Promise<VehicleManifest>;
+    invoke<Output = unknown>(name: string, version: number, input: unknown, options?: VehicleInvocationOptions): Promise<Output>;
+    close(): Promise<void>;
+    /**
+     * Vehicle Jobs -- submit a background-capable operation (one whose descriptor declares
+     * `background`, see {@link VehicleBackgroundCapability}) and get its jobId back immediately,
+     * without waiting for the operation itself to make any progress. Optional: a client that
+     * never talks to a job-capable Vehicle (or a hand-rolled test double) simply omits these five
+     * methods, exactly like this interface's own long-standing `subscribe()`-shaped extras --
+     * present on both LocalVehicleClient and RemoteVehicleClient, absent elsewhere. Feature-detect
+     * via the operation's own manifest `background` capability, not by probing for these methods.
+     */
+    submitJob?(name: string, version: number, input: unknown, options?: VehicleJobSubmitOptions): Promise<VehicleJobSubmitResult>;
+    /** Never blocks -- current status, plus output/error once terminal. */
+    pollJob?(jobId: string): Promise<VehicleJobSnapshot>;
+    /** Progress entries strictly after `cursor` (0 for everything so far), plus the next cursor. Never blocks. */
+    tailJob?(jobId: string, cursor?: number): Promise<VehicleJobTailResult>;
+    /** Pushes new input to an already-running job's handler, if it opted in via context.steerInputs. */
+    steerJob?(jobId: string, input: unknown): Promise<void>;
+    /** Best-effort cancellation of a still-running job -- a no-op against an already-terminal one. */
+    cancelJob?(jobId: string): Promise<void>;
+}

package/dist/client/client.js

@@ -0,0 +1 @@
+export {};

package/dist/client/index.d.ts

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

package/dist/client/index.js

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

package/dist/content/content.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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 declare function extractVehicleContent(output: unknown): readonly VehicleContentBlock[] | undefined;

package/dist/content/content.js

@@ -0,0 +1,25 @@
+/**
+ * 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) {
+    if (typeof output !== "object" || output === null || Array.isArray(output))
+        return undefined;
+    const content = output.content;
+    if (!Array.isArray(content) || content.length === 0)
+        return undefined;
+    const blocks = [];
+    for (const block of content) {
+        if (typeof block !== "object" || block === null)
+            return undefined;
+        const { type, text } = block;
+        if (type !== "text" || typeof text !== "string")
+            return undefined;
+        blocks.push({ type: "text", text });
+    }
+    return blocks;
+}

package/dist/content/index.d.ts

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

package/dist/content/index.js

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

package/dist/{vehicle-errors.d.ts → errors/error.d.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";
 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" | "idempotency-conflict" | "client-closed" | "operation-unavailable" | "background-not-supported" | "job-not-found" | "job-not-steerable" | "job-steer-queue-full";
 export interface VehicleRecovery {
@@ -20,10 +21,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;
@@ -51,10 +52,10 @@ 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;
+    readonly retryAfterMs?: number | undefined;
+    readonly recovery?: VehicleRecovery | undefined;
+    readonly details?: JsonValue | undefined;
+    readonly operationId?: string | undefined;
     private readonly exposeCause;
     constructor(code: string, message: string, options: VehicleErrorOptions);
     toFailure(): VehicleFailure;

package/dist/errors/index.d.ts

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

package/dist/errors/index.js

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

package/dist/events/event.d.ts

@@ -0,0 +1,42 @@
+import type { VehicleSchemaCodec } from "../schemas/codec.js";
+import { 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;
+}
+export declare function defineVehicleEvent<Payload>(options: DefineVehicleEventOptions<Payload>): VehicleEvent<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 declare function vehicleEventTopic(name: string, version: number): string;

package/dist/events/event.js

@@ -0,0 +1,35 @@
+import { cloneJson } from "../schemas/json.js";
+function validateEventMetadata(options) {
+    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(options) {
+    validateEventMetadata(options);
+    const descriptor = 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 });
+}
+/**
+ * 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, version) {
+    return `vehicle-event:${name}@${version}`;
+}

package/dist/events/index.d.ts

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

package/dist/events/index.js

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

package/dist/idempotency/index.d.ts

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

package/dist/idempotency/index.js

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

package/dist/{vehicle-idempotency.d.ts → idempotency/receipt.d.ts}

@@ -5,7 +5,7 @@
  * VehicleJobStore split (a pure, independently-testable bounded-retention rule here; the stateful
  * store that calls it lives in vehicle-server).
  */
-import type { VehicleFailure } from "./vehicle-errors.js";
+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;

package/dist/index.d.ts

@@ -1,8 +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-idempotency.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/dist/index.js

@@ -1,8 +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-idempotency.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/dist/jobs/identity.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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 declare function vehicleJobIdentityMatches(recordInstanceToken: string, currentInstanceToken: string): boolean;

package/dist/jobs/identity.js

@@ -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, currentInstanceToken) {
+    return recordInstanceToken === currentInstanceToken;
+}

package/dist/jobs/index.d.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/dist/jobs/index.js

@@ -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/dist/jobs/replay.d.ts

@@ -0,0 +1,8 @@
+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 declare function createStaticVehicleJobWakeLog(entries: readonly VehicleJobWakeEntry[]): VehicleJobWakeLogReader;

package/dist/jobs/replay.js

@@ -0,0 +1,9 @@
+/** 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) {
+    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/dist/jobs/retention.d.ts

@@ -0,0 +1,26 @@
+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 declare function selectVehicleJobsForEviction(candidates: readonly VehicleJobEvictionCandidate[], options: VehicleJobRetentionOptions): readonly string[];

package/dist/jobs/retention.js

@@ -0,0 +1,39 @@
+/**
+ * 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, options) {
+    const terminal = candidates.filter((candidate) => candidate.status !== "running");
+    const byAgeAscending = (a, b) => a.updatedAt - b.updatedAt;
+    const evicted = new Set();
+    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/dist/jobs/steer.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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 declare class VehicleJobSteerChannel implements AsyncIterable<unknown> {
+    private readonly maxQueueSize;
+    private readonly buffer;
+    private readonly waiters;
+    private closed;
+    constructor(maxQueueSize?: number);
+    push(value: unknown): VehicleJobSteerPushResult;
+    /** Ends every pending and future iteration with done:true; further push() calls report "channel-closed". Idempotent. */
+    close(): void;
+    [Symbol.asyncIterator](): AsyncIterator<unknown>;
+}