@danypops/vehicle-core 0.16.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,29 @@
-import { defineVehicleEvent, defineVehicleSchema } 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) {
+    return typeof value === "string" && VEHICLE_EFFECTS.includes(value);
+}
+function isVehiclePrincipal(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const candidate = value;
+    if (typeof candidate["id"] !== "string")
+        return false;
+    if (candidate["claims"] === undefined)
+        return true;
+    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"];
 /**
@@ -21,7 +46,8 @@ const requestedPayloadSchema = defineVehicleSchema({
             requestId: { type: "string" },
             operationName: { type: "string" },
             operationVersion: { type: "number" },
-            effect: { type: "string" },
+            effect: { type: "string", enum: [...VEHICLE_EFFECTS] },
+            principal: { type: "object" },
             requestedAt: { type: "number" },
             expiresAt: { type: "number" },
             inputHash: { type: "string" },
@@ -33,15 +59,23 @@ 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" ||
-            typeof row.effect !== "string" ||
-            typeof row.requestedAt !== "number" ||
-            typeof row.expiresAt !== "number" ||
-            typeof row.inputHash !== "string") {
+        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"])) {
+            return { success: false, issues: [{ path: ["principal"], message: "invalid approval request principal" }] };
+        }
         return { success: true, value: row };
     },
 });
@@ -62,11 +96,18 @@ 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") {
+        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") {
+            return { success: false, issues: [{ path: ["decidedBy"], message: "decidedBy must be a 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,6 +1,7 @@
-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" | "client-closed" | "operation-unavailable" | "background-not-supported" | "job-not-found" | "job-not-steerable" | "job-steer-queue-full";
+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 {
     readonly operation?: string;
     readonly message: string;
@@ -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,16 +52,27 @@ 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;
 }
 /** Recognizes VehicleError instances across duplicated package installations in one process. */
 export declare function isVehicleError(value: unknown): value is VehicleError;
+/**
+ * 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 declare function vehicleErrorFromFailure(failure: VehicleFailure): VehicleError;
 /** Extracts a bounded, wire-safe message from an unknown cause -- never the full stack trace, never an unbounded payload. */
 export declare function boundedCauseMessage(cause: unknown): string | undefined;
 export declare function boundedValidationDetails(issues: readonly VehicleSchemaIssue[] | undefined): JsonValue | undefined;

package/dist/{vehicle-errors.js → errors/error.js}

@@ -60,6 +60,26 @@ export class VehicleError extends Error {
 export function isVehicleError(value) {
     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) {
+    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. */
 export function boundedCauseMessage(cause) {

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/idempotency/receipt.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 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 declare function selectVehicleIdempotencyReceiptsForEviction(candidates: readonly VehicleIdempotencyEvictionCandidate[], options: VehicleIdempotencyRetentionOptions): readonly string[];

package/dist/idempotency/receipt.js

@@ -0,0 +1,42 @@
+/**
+ * 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, options) {
+    const byAgeAscending = (a, b) => a.settledAt - b.settledAt;
+    const evicted = new Set();
+    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/dist/index.d.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/dist/index.js

@@ -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/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;