@danypops/vehicle-core 0.17.0 → 0.18.0

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>;
+}

package/dist/jobs/steer.js

@@ -0,0 +1,41 @@
+export class VehicleJobSteerChannel {
+    maxQueueSize;
+    buffer = [];
+    waiters = [];
+    closed = false;
+    constructor(maxQueueSize = 64) {
+        this.maxQueueSize = maxQueueSize;
+    }
+    push(value) {
+        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() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        for (const waiter of this.waiters.splice(0))
+            waiter({ value: undefined, done: true });
+    }
+    [Symbol.asyncIterator]() {
+        return {
+            next: () => {
+                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/dist/jobs/termination.d.ts

@@ -0,0 +1,5 @@
+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 declare const VEHICLE_JOB_TERMINATION_PRECEDENCE: readonly ["canceled", "timeout", "orphaned", "failed", "succeeded"];
+export type VehicleJobTerminationReason = (typeof VEHICLE_JOB_TERMINATION_PRECEDENCE)[number];
+export declare function resolveVehicleJobTerminationReason(candidates: readonly VehicleJobTerminationReason[]): VehicleJobTerminationReason;

package/dist/jobs/termination.js

@@ -0,0 +1,11 @@
+/** 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"];
+export function resolveVehicleJobTerminationReason(candidates) {
+    if (candidates.length === 0)
+        throw new Error("resolveVehicleJobTerminationReason requires at least one candidate");
+    for (const reason of VEHICLE_JOB_TERMINATION_PRECEDENCE) {
+        if (candidates.includes(reason))
+            return reason;
+    }
+    throw new Error(`Unrecognized Vehicle job termination candidate(s): ${candidates.join(", ")}`);
+}

package/dist/jobs/wake-log.d.ts

@@ -0,0 +1,39 @@
+/** "always" keeps every notification; "transition" drops one identical to the last (hash dedup); "first-only" keeps just the first. */
+export type VehicleJobNotifyMode = "always" | "transition" | "first-only";
+export interface VehicleJobWakeBudget {
+    readonly maxCount: number;
+    readonly maxBytes: number;
+}
+export type VehicleJobWakeDropReason = "count-budget-exhausted" | "byte-budget-exhausted" | "deduplicated-transition" | "superseded-by-first-only";
+export interface VehicleJobWakeEntry {
+    readonly seq: number;
+    readonly at: number;
+    readonly progress: unknown;
+}
+export interface VehicleJobWakeAppendResult {
+    readonly accepted: boolean;
+    readonly entry?: VehicleJobWakeEntry;
+    readonly dropReason?: VehicleJobWakeDropReason;
+}
+export interface VehicleJobWakeLogOptions {
+    readonly notifyMode: VehicleJobNotifyMode;
+    readonly budget: VehicleJobWakeBudget;
+    /** Defaults to Date.now. */
+    readonly now?: () => number;
+}
+/** Bounds a job's accumulated progress notifications by count+bytes, same discipline as enforcePayloadSize but across a job's whole lifetime. */
+export declare class VehicleJobWakeLog {
+    private readonly options;
+    private readonly entries;
+    private usedBytes;
+    private nextSeq;
+    private lastHash;
+    private acceptedFirst;
+    private readonly now;
+    constructor(options: VehicleJobWakeLogOptions);
+    append(progress: unknown): VehicleJobWakeAppendResult;
+    /** Entries with seq strictly greater than `cursor`. */
+    since(cursor: number): readonly VehicleJobWakeEntry[];
+    /** Highest seq issued so far (0 if none accepted yet). */
+    get cursor(): number;
+}

package/dist/jobs/wake-log.js

@@ -0,0 +1,65 @@
+function safeJsonStringify(value) {
+    let serialized;
+    try {
+        serialized = JSON.stringify(value);
+    }
+    catch (error) {
+        throw new Error("Vehicle job progress value is not JSON-serializable", { cause: error });
+    }
+    if (serialized === undefined)
+        throw new Error("Vehicle job progress value is not JSON-serializable");
+    return serialized;
+}
+/** Non-cryptographic (FNV-1a) -- dedup only. */
+function fnv1aHash(value) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < value.length; i++) {
+        hash ^= value.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0).toString(16);
+}
+/** Bounds a job's accumulated progress notifications by count+bytes, same discipline as enforcePayloadSize but across a job's whole lifetime. */
+export class VehicleJobWakeLog {
+    options;
+    entries = [];
+    usedBytes = 0;
+    nextSeq = 1;
+    lastHash;
+    acceptedFirst = false;
+    now;
+    constructor(options) {
+        this.options = options;
+        this.now = options.now ?? Date.now;
+    }
+    append(progress) {
+        if (this.options.notifyMode === "first-only" && this.acceptedFirst) {
+            return { accepted: false, dropReason: "superseded-by-first-only" };
+        }
+        const serialized = safeJsonStringify(progress);
+        if (this.options.notifyMode === "transition") {
+            const hash = fnv1aHash(serialized);
+            if (hash === this.lastHash)
+                return { accepted: false, dropReason: "deduplicated-transition" };
+            this.lastHash = hash;
+        }
+        const bytes = new TextEncoder().encode(serialized).byteLength;
+        if (this.entries.length >= this.options.budget.maxCount)
+            return { accepted: false, dropReason: "count-budget-exhausted" };
+        if (this.usedBytes + bytes > this.options.budget.maxBytes)
+            return { accepted: false, dropReason: "byte-budget-exhausted" };
+        const entry = { seq: this.nextSeq++, at: this.now(), progress };
+        this.entries.push(entry);
+        this.usedBytes += bytes;
+        this.acceptedFirst = true;
+        return { accepted: true, entry };
+    }
+    /** Entries with seq strictly greater than `cursor`. */
+    since(cursor) {
+        return this.entries.filter((entry) => entry.seq > cursor);
+    }
+    /** Highest seq issued so far (0 if none accepted yet). */
+    get cursor() {
+        return this.nextSeq - 1;
+    }
+}

package/dist/jobs/wire.d.ts

@@ -0,0 +1,47 @@
+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/dist/jobs/wire.js

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

package/dist/manifest/index.d.ts

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

package/dist/manifest/index.js

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

package/dist/manifest/manifest.d.ts

@@ -0,0 +1,49 @@
+import type { VehicleManifestEvent } from "../events/event.js";
+import type { VehicleOperationDescriptor } from "../operations/operation.js";
+export interface VehicleManifestIdentity {
+    readonly name: string;
+    readonly version: string;
+    readonly description: string;
+    readonly guidance?: readonly string[];
+}
+/**
+ * A manifest's own view of an operation: the static descriptor plus
+ * whether it's currently usable on this particular server instance right
+ * now. Availability is a runtime property of a live registry (a
+ * credential got configured or removed), never baked into the static
+ * descriptor defineVehicleOperation() produces -- two manifest() calls
+ * against the same registry can report different availability for the
+ * exact same descriptor.
+ */
+export interface VehicleManifestOperation extends VehicleOperationDescriptor {
+    readonly available: boolean;
+    readonly unavailableReason?: string;
+    /**
+     * The registry's own, live, fully-resolved answer to "does invoking this operation right
+     * now require approval" -- accounts for the registry's current approval policy being
+     * enabled/disabled, this operation's own `requiresApproval` override when set, and the
+     * effect-derived default otherwise. A real VehicleRegistry.manifest() always sets this
+     * (false when the registry never called configureApprovals() at all) -- unlike
+     * `requiresApproval` (the static, author-declared override on the descriptor itself),
+     * this always reflects the current instant, so a client re-fetching the manifest after a
+     * live policy change (VehicleRegistry.updateApprovalPolicy) sees the new answer with no
+     * separate sync mechanism needed.
+     *
+     * Optional purely for backward compatibility with every hand-authored VehicleManifest
+     * test fixture across the ecosystem that predates this field (the same reason
+     * VehicleManifest.events is optional) -- a consumer reading it should treat undefined the
+     * same as a caller of classifyVehicleOperationSafety does: fall back to the effect-level
+     * default, never assume false.
+     */
+    readonly approvalRequired?: boolean;
+}
+/**
+ * `events` is optional purely for backward compatibility with every
+ * hand-authored VehicleManifest test fixture across the ecosystem that
+ * predates this field -- a real VehicleRegistry.manifest() always
+ * populates it (as [] when no events are declared), never omits it.
+ */
+export interface VehicleManifest extends VehicleManifestIdentity {
+    readonly operations: readonly VehicleManifestOperation[];
+    readonly events?: readonly VehicleManifestEvent[];
+}

package/dist/manifest/manifest.js

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

package/dist/operations/context.d.ts

@@ -0,0 +1,52 @@
+import type { JsonValue } from "../schemas/json.js";
+export interface VehiclePrincipal {
+    readonly id: string;
+    readonly claims?: Readonly<Record<string, JsonValue>>;
+}
+/**
+ * callerSessionId/callerProjectRoot identify the real host session (e.g. one Pi TUI process) that
+ * originated this call, and its working directory at call time -- a generic ownership/attribution
+ * hook any operation handler can read (e.g. scoping a background subscription to the session or
+ * project that created it), distinct from both:
+ *  - correlationId: a caller-CHOSEN id deliberately meant to span several separate invoke() calls
+ *    (a batch/business-transaction id), not an automatically-derived caller identity.
+ *  - principal: broader identity/claims used for permission and approval decisions, usually a
+ *    fixed per-extension value (e.g. {id: "pi-pipes"}), not a distinguishing per-session id.
+ * A Pi projection layer (see vehicle-client-pi's invokeVehicleOperation) auto-derives both from
+ * context.sessionManager.getSessionId()/context.cwd on every call, the same way it already
+ * auto-derives correlationId -- a handler that never reads them pays nothing extra.
+ */
+export interface VehicleInvocationOptions {
+    readonly operationId?: string;
+    readonly correlationId?: string;
+    readonly callerSessionId?: string;
+    readonly callerProjectRoot?: string;
+    readonly signal?: AbortSignal;
+    readonly deadline?: number;
+    readonly permissions?: readonly string[];
+    readonly principal?: VehiclePrincipal;
+    readonly idempotencyKey?: string;
+    readonly expectedRevision?: string | number;
+    readonly approvalCapability?: string;
+    readonly onProgress?: (progress: unknown) => void;
+}
+export interface VehicleOperationContext<Input> {
+    readonly input: Input;
+    readonly operationId: string;
+    readonly correlationId?: string;
+    /** See VehicleInvocationOptions's own doc comment. */
+    readonly callerSessionId?: string;
+    /** See VehicleInvocationOptions's own doc comment. */
+    readonly callerProjectRoot?: string;
+    readonly signal: AbortSignal;
+    readonly deadline: number;
+    readonly permissions: readonly string[];
+    readonly principal?: VehiclePrincipal;
+    readonly idempotencyKey?: string;
+    readonly expectedRevision?: string | number;
+    readonly approvalCapability?: string;
+    /** Set only for a job execution (VehicleJobStore.submit()); undefined for a plain invoke(). A handler that wants mid-flight input opts in with `for await (const input of context.steerInputs ?? [])`. */
+    readonly steerInputs?: AsyncIterable<unknown>;
+    reportProgress(progress: unknown): void;
+}
+export type VehicleOperationHandler<Input, Output> = (context: VehicleOperationContext<Input>) => Promise<Output>;

package/dist/operations/context.js

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

package/dist/operations/effect.d.ts

@@ -0,0 +1,3 @@
+/** Canonical list VehicleEffect is itself derived from, so a runtime discriminator check (e.g. a persisted/wire VehicleApprovalRequest's own `effect` field) has one real source to check against instead of a second, driftable hardcoded list. */
+export declare const VEHICLE_EFFECTS: readonly ["read", "local-write", "external-write", "destructive", "open-world"];
+export type VehicleEffect = (typeof VEHICLE_EFFECTS)[number];

package/dist/operations/effect.js

@@ -0,0 +1,2 @@
+/** Canonical list VehicleEffect is itself derived from, so a runtime discriminator check (e.g. a persisted/wire VehicleApprovalRequest's own `effect` field) has one real source to check against instead of a second, driftable hardcoded list. */
+export const VEHICLE_EFFECTS = ["read", "local-write", "external-write", "destructive", "open-world"];

package/dist/operations/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./context.js";
+export * from "./effect.js";
+export * from "./operation.js";

package/dist/operations/index.js

@@ -0,0 +1,3 @@
+export * from "./context.js";
+export * from "./effect.js";
+export * from "./operation.js";

package/dist/operations/operation.d.ts

@@ -0,0 +1,98 @@
+import type { VehicleJobWakeBudget } from "../jobs/wake-log.js";
+import type { VehicleSchemaCodec } from "../schemas/codec.js";
+import { type JsonSchema } from "../schemas/json.js";
+import type { VehicleOperationHandler } from "./context.js";
+import type { VehicleEffect } from "./effect.js";
+export type VehicleIdempotency = {
+    readonly mode: "safe";
+} | {
+    readonly mode: "keyed";
+    readonly retentionMs: number;
+} | {
+    readonly mode: "unsafe";
+};
+export interface VehicleLimits {
+    readonly defaultTimeoutMs: number;
+    readonly maxTimeoutMs: number;
+    readonly maxRequestBytes: number;
+    readonly maxResponseBytes: number;
+}
+/** One structured, documented failure mode a {@link VehicleOperationDescriptor} declares up front -- part of the operation's own serializable contract, not an ad hoc thrown Error a caller has to reverse-engineer from a message string. */
+export interface VehicleFailureDescriptor {
+    readonly code: string;
+    readonly description: string;
+}
+/** Declares an operation safe to run as a Vehicle Job (detached, polled/tailed/canceled by id). Absent means live-invoke only. */
+export interface VehicleBackgroundCapability {
+    readonly supported: true;
+    readonly defaultWakeBudget: VehicleJobWakeBudget;
+    readonly maxWakeBudget: VehicleJobWakeBudget;
+}
+/**
+ * The serializable half of a Vehicle operation -- name, version, schemas,
+ * ownership-implying permissions, effect classification, idempotency,
+ * streaming/long-running capability, request/response limits, and declared
+ * {@link VehicleFailureDescriptor} failure modes. Kept separate from the
+ * executable {@link VehicleOperationHandler} on purpose: a manifest, a Pi
+ * tool projection, or a client's own capability check can all inspect this
+ * shape without ever touching (or needing to trust) the implementation
+ * behind it.
+ */
+export interface VehicleOperationDescriptor {
+    readonly name: string;
+    readonly version: number;
+    readonly description: string;
+    readonly inputSchema: JsonSchema;
+    readonly outputSchema: JsonSchema;
+    readonly permissions: readonly string[];
+    readonly effect: VehicleEffect;
+    readonly idempotency: VehicleIdempotency;
+    readonly streaming: boolean;
+    readonly longRunning: boolean;
+    readonly limits: VehicleLimits;
+    readonly errors: readonly VehicleFailureDescriptor[];
+    readonly background?: VehicleBackgroundCapability;
+    /**
+     * Owner-declared override for whether this specific operation is ever a candidate for
+     * approval gating, independent of its `effect`. Undefined (the default) means "derive it
+     * from `effect` against the registry's own requireApprovalForEffects set instead" --
+     * VehicleRegistry.manifest()'s own resolution rule, unchanged for every existing
+     * operation that never sets this.
+     *
+     * Exists because VehicleEffect's five values are coarse enough that two operations a
+     * real owner classifies very differently (e.g. "restart an already-installed,
+     * already-vetted service" vs. "sync a read-only catalog mirror") can land in the same
+     * effect bucket (both external-write) -- no single requireApprovalForEffects set can
+     * gate one without also gating the other. The owner who registers the operation knows
+     * its real risk far better than a 5-value enum can; this lets them say so directly.
+     */
+    readonly requiresApproval?: boolean;
+}
+export interface VehicleOperation<Input, Output> {
+    readonly descriptor: VehicleOperationDescriptor;
+    readonly input: VehicleSchemaCodec<Input>;
+    readonly output: VehicleSchemaCodec<Output>;
+}
+export interface DefineVehicleOperationOptions<Input, Output> {
+    readonly name: string;
+    readonly version: number;
+    readonly description: string;
+    readonly input: VehicleSchemaCodec<Input>;
+    readonly output: VehicleSchemaCodec<Output>;
+    readonly permissions?: readonly string[];
+    readonly effect: VehicleEffect;
+    readonly idempotency: VehicleIdempotency;
+    readonly streaming?: boolean;
+    readonly longRunning?: boolean;
+    readonly limits: VehicleLimits;
+    readonly errors?: readonly VehicleFailureDescriptor[];
+    readonly background?: VehicleBackgroundCapability;
+    /** See {@link VehicleOperationDescriptor.requiresApproval}. */
+    readonly requiresApproval?: boolean;
+}
+export interface VehicleOperationBinding<Input, Output> {
+    readonly operation: VehicleOperation<Input, Output>;
+    bind(): VehicleOperationHandler<Input, Output>;
+}
+export declare function defineVehicleOperation<Input, Output>(options: DefineVehicleOperationOptions<Input, Output>): VehicleOperation<Input, Output>;
+export declare function bindVehicleOperation<Input, Output>(operation: VehicleOperation<Input, Output>, bind: () => VehicleOperationHandler<Input, Output>): VehicleOperationBinding<Input, Output>;

package/dist/operations/operation.js

@@ -0,0 +1,79 @@
+import { cloneJson } from "../schemas/json.js";
+export function defineVehicleOperation(options) {
+    validateOperationMetadata(options);
+    const descriptor = Object.freeze({
+        name: options.name,
+        version: options.version,
+        description: options.description,
+        inputSchema: cloneJson(options.input.jsonSchema),
+        outputSchema: cloneJson(options.output.jsonSchema),
+        permissions: Object.freeze([...(options.permissions ?? [])]),
+        effect: options.effect,
+        idempotency: Object.freeze({ ...options.idempotency }),
+        streaming: options.streaming ?? false,
+        longRunning: options.longRunning ?? false,
+        limits: Object.freeze({ ...options.limits }),
+        errors: Object.freeze((options.errors ?? []).map((failure) => Object.freeze({ ...failure }))),
+        ...(options.requiresApproval !== undefined ? { requiresApproval: options.requiresApproval } : {}),
+        ...(options.background
+            ? {
+                background: Object.freeze({
+                    supported: true,
+                    defaultWakeBudget: Object.freeze({ ...options.background.defaultWakeBudget }),
+                    maxWakeBudget: Object.freeze({ ...options.background.maxWakeBudget }),
+                }),
+            }
+            : {}),
+    });
+    return Object.freeze({ descriptor, input: options.input, output: options.output });
+}
+export function bindVehicleOperation(operation, bind) {
+    return Object.freeze({ operation, bind });
+}
+function validateOperationMetadata(options) {
+    if (!options.name.trim())
+        throw new Error("Vehicle operation name must not be empty");
+    if (!Number.isInteger(options.version) || options.version < 1) {
+        throw new Error("Vehicle operation version must be a positive integer");
+    }
+    if (!options.description.trim())
+        throw new Error("Vehicle operation description must not be empty");
+    for (const permission of options.permissions ?? []) {
+        if (!permission.trim())
+            throw new Error("Vehicle operation permissions must not contain an empty value");
+    }
+    const limits = options.limits;
+    for (const [name, value] of Object.entries(limits)) {
+        if (!Number.isSafeInteger(value) || value < 1)
+            throw new Error(`Vehicle operation ${name} must be a positive integer`);
+    }
+    if (limits.defaultTimeoutMs > limits.maxTimeoutMs) {
+        throw new Error("Vehicle operation defaultTimeoutMs must not exceed maxTimeoutMs");
+    }
+    if (options.idempotency.mode === "keyed" &&
+        (!Number.isSafeInteger(options.idempotency.retentionMs) || options.idempotency.retentionMs < 1)) {
+        throw new Error("Vehicle keyed idempotency retentionMs must be a positive integer");
+    }
+    if (options.background) {
+        if (!options.longRunning) {
+            throw new Error("Vehicle operation with a background capability must also set longRunning: true");
+        }
+        for (const [budgetName, budget] of [
+            ["defaultWakeBudget", options.background.defaultWakeBudget],
+            ["maxWakeBudget", options.background.maxWakeBudget],
+        ]) {
+            if (!Number.isSafeInteger(budget.maxCount) || budget.maxCount < 1) {
+                throw new Error(`Vehicle operation background.${budgetName}.maxCount must be a positive integer`);
+            }
+            if (!Number.isSafeInteger(budget.maxBytes) || budget.maxBytes < 1) {
+                throw new Error(`Vehicle operation background.${budgetName}.maxBytes must be a positive integer`);
+            }
+        }
+        if (options.background.defaultWakeBudget.maxCount > options.background.maxWakeBudget.maxCount) {
+            throw new Error("Vehicle operation background.defaultWakeBudget.maxCount must not exceed maxWakeBudget.maxCount");
+        }
+        if (options.background.defaultWakeBudget.maxBytes > options.background.maxWakeBudget.maxBytes) {
+            throw new Error("Vehicle operation background.defaultWakeBudget.maxBytes must not exceed maxWakeBudget.maxBytes");
+        }
+    }
+}

package/dist/{atomic-json.d.ts → persistence/atomic-json.d.ts}

@@ -8,8 +8,7 @@
  * the caller (vehicle-server, vehicle-client-pi) supplies real node:fs
  * functions, this module only sequences them.
  *
- * Modeled on github.com/nicobailon/pi-subagents' `createAtomicJsonWriter`:
- * a collision-safe temp filename, injectable fs/now/pid/random for
+ * A collision-safe temp filename, injectable fs/now/pid/random for
  * deterministic tests, and explicit Windows-aware rename retry (a plain
  * `fs.rename` onto an existing path can transiently fail on Windows if
  * another process -- antivirus, search indexing -- has the destination

package/dist/{atomic-json.js → persistence/atomic-json.js}

@@ -8,8 +8,7 @@
  * the caller (vehicle-server, vehicle-client-pi) supplies real node:fs
  * functions, this module only sequences them.
  *
- * Modeled on github.com/nicobailon/pi-subagents' `createAtomicJsonWriter`:
- * a collision-safe temp filename, injectable fs/now/pid/random for
+ * A collision-safe temp filename, injectable fs/now/pid/random for
  * deterministic tests, and explicit Windows-aware rename retry (a plain
  * `fs.rename` onto an existing path can transiently fail on Windows if
  * another process -- antivirus, search indexing -- has the destination

package/dist/persistence/index.d.ts

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

package/dist/persistence/index.js

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

package/dist/schedules/index.d.ts

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

package/dist/schedules/index.js

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