@danypops/vehicle-core 0.4.0 → 0.5.0

package/dist/vehicle-contract.d.ts

@@ -154,6 +154,8 @@ export interface VehicleOperationContext<Input> {
     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/vehicle-errors.d.ts

@@ -1,6 +1,6 @@
 import type { JsonValue, VehicleSchemaIssue } from "./vehicle-contract.js";
 export type VehicleFailureCategory = "validation" | "not_found" | "conflict" | "authorization" | "capacity" | "timeout" | "cancelled" | "unavailable" | "internal";
-export type VehicleCoreErrorCode = "duplicate-owner" | "not-found" | "invalid-input" | "invalid-output" | "permission-denied" | "request-too-large" | "response-too-large" | "cancelled" | "deadline-exceeded" | "handler-failed" | "policy-failed" | "idempotency-key-required" | "client-closed" | "operation-unavailable" | "background-not-supported" | "job-not-found";
+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 interface VehicleRecovery {
     readonly operation?: string;
     readonly message: string;

package/dist/vehicle-jobs.d.ts

@@ -1,7 +1,7 @@
 /** Pure pieces of Vehicle Jobs: a termination-reason resolver and a bounded wake-log accumulator. Orchestration lives in vehicle-server's VehicleJobStore. */
 export type VehicleJobStatus = "running" | "succeeded" | "failed" | "canceled";
-/** Highest precedence first -- an explicit cancel always wins even if the handler also settled around the same time. */
-export declare const VEHICLE_JOB_TERMINATION_PRECEDENCE: readonly ["canceled", "timeout", "failed", "succeeded"];
+/** 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;
 /** "always" keeps every notification; "transition" drops one identical to the last (hash dedup); "first-only" keeps just the first. */
@@ -43,3 +43,72 @@ export declare class VehicleJobWakeLog {
     /** Highest seq issued so far (0 if none accepted yet). */
     get cursor(): number;
 }
+/** 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;
+/**
+ * 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>;
+}
+/**
+ * Vehicle Jobs run as in-process promises, not child processes -- there is
+ * no PID to reuse, but the same identity-confusion risk vstack's
+ * {pid, startToken, comm} design guards against still applies in a
+ * generalized form: a persisted job record written by one process
+ * instance must 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", the same conclusion vstack's identityMatches() reaches by
+ * comparing a live process's actual pid/start-time/command against a
+ * stored snapshot -- this is that same check with no process to inspect.
+ */
+export declare function vehicleJobIdentityMatches(recordInstanceToken: string, currentInstanceToken: string): boolean;
+/** 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/vehicle-jobs.js

@@ -1,6 +1,6 @@
 /** Pure pieces of Vehicle Jobs: a termination-reason resolver and a bounded wake-log accumulator. Orchestration lives in vehicle-server's VehicleJobStore. */
-/** Highest precedence first -- an explicit cancel always wins even if the handler also settled around the same time. */
-export const VEHICLE_JOB_TERMINATION_PRECEDENCE = ["canceled", "timeout", "failed", "succeeded"];
+/** 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");
@@ -75,3 +75,108 @@ function fnv1aHash(value) {
     }
     return (hash >>> 0).toString(16);
 }
+/** 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,
+    };
+}
+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));
+            },
+        };
+    }
+}
+/**
+ * Vehicle Jobs run as in-process promises, not child processes -- there is
+ * no PID to reuse, but the same identity-confusion risk vstack's
+ * {pid, startToken, comm} design guards against still applies in a
+ * generalized form: a persisted job record written by one process
+ * instance must 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", the same conclusion vstack's identityMatches() reaches by
+ * comparing a live process's actual pid/start-time/command against a
+ * stored snapshot -- this is that same check with no process to inspect.
+ */
+export function vehicleJobIdentityMatches(recordInstanceToken, currentInstanceToken) {
+    return recordInstanceToken === currentInstanceToken;
+}
+/**
+ * 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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@danypops/vehicle-core",
-	"version": "0.4.0",
+	"version": "0.5.0",
 	"description": "Vehicle's runtime-neutral wire contract: operation descriptors, schema codecs, failure shapes. Zero runtime dependencies, zero Bun-specific code -- the one thing every Vehicle client and server package depends on.",
 	"license": "MIT",
 	"type": "module",

package/src/vehicle-contract.ts

@@ -213,6 +213,8 @@ export interface VehicleOperationContext<Input> {
 	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;
 }
 

package/src/vehicle-errors.ts

@@ -27,7 +27,9 @@ export type VehicleCoreErrorCode =
 	| "client-closed"
 	| "operation-unavailable"
 	| "background-not-supported"
-	| "job-not-found";
+	| "job-not-found"
+	| "job-not-steerable"
+	| "job-steer-queue-full";
 
 export interface VehicleRecovery {
 	readonly operation?: string;

package/src/vehicle-jobs.ts

@@ -2,8 +2,8 @@
 
 export type VehicleJobStatus = "running" | "succeeded" | "failed" | "canceled";
 
-/** Highest precedence first -- an explicit cancel always wins even if the handler also settled around the same time. */
-export const VEHICLE_JOB_TERMINATION_PRECEDENCE = ["canceled", "timeout", "failed", "succeeded"] as const;
+/** Highest precedence first -- an explicit cancel always wins even if the handler also settled around the same time. "orphaned" is a restart-reconciliation outcome: a job that was still "running" when its process died, so nothing ever really failed or succeeded -- the record's own status just goes stale. */
+export const VEHICLE_JOB_TERMINATION_PRECEDENCE = ["canceled", "timeout", "orphaned", "failed", "succeeded"] as const;
 export type VehicleJobTerminationReason = (typeof VEHICLE_JOB_TERMINATION_PRECEDENCE)[number];
 
 export function resolveVehicleJobTerminationReason(candidates: readonly VehicleJobTerminationReason[]): VehicleJobTerminationReason {
@@ -112,3 +112,144 @@ function fnv1aHash(value: string): string {
 	}
 	return (hash >>> 0).toString(16);
 }
+
+/** Read-only replay side of a wake log -- both a live VehicleJobWakeLog and a restored (no-longer-appendable) job satisfy this with the same tail() semantics. */
+export interface VehicleJobWakeLogReader {
+	since(cursor: number): readonly VehicleJobWakeEntry[];
+	readonly cursor: number;
+}
+
+/** Wraps a fixed, already-finalized list of entries (e.g. restored from disk) in the same reader shape a live VehicleJobWakeLog exposes, so VehicleJobStore.tail() doesn't need to special-case a restored job. */
+export function createStaticVehicleJobWakeLog(entries: readonly VehicleJobWakeEntry[]): VehicleJobWakeLogReader {
+	const sorted = [...entries].sort((a, b) => a.seq - b.seq);
+	const cursor = sorted.length > 0 ? sorted[sorted.length - 1]!.seq : 0;
+	return {
+		since: (cursorArg) => sorted.filter((entry) => entry.seq > cursorArg),
+		cursor,
+	};
+}
+
+/**
+ * A job's mid-flight input channel -- the "steer" primitive. Bounded FIFO:
+ * push() while a handler isn't yet reading buffers up to maxQueueSize, then
+ * refuses further input rather than growing unboundedly or silently
+ * overwriting an unread entry. A handler consumes it via `for await (const
+ * input of context.steerInputs)`, which ends cleanly once close() is
+ * called (VehicleJobStore does this at job finalization).
+ */
+export interface VehicleJobSteerPushResult {
+	readonly accepted: boolean;
+	readonly dropReason?: "queue-full" | "channel-closed";
+}
+
+export class VehicleJobSteerChannel implements AsyncIterable<unknown> {
+	private readonly buffer: unknown[] = [];
+	private readonly waiters: ((result: IteratorResult<unknown>) => void)[] = [];
+	private closed = false;
+
+	constructor(private readonly maxQueueSize: number = 64) {}
+
+	push(value: unknown): VehicleJobSteerPushResult {
+		if (this.closed) return { accepted: false, dropReason: "channel-closed" };
+		const waiter = this.waiters.shift();
+		if (waiter) {
+			waiter({ value, done: false });
+			return { accepted: true };
+		}
+		if (this.buffer.length >= this.maxQueueSize) return { accepted: false, dropReason: "queue-full" };
+		this.buffer.push(value);
+		return { accepted: true };
+	}
+
+	/** Ends every pending and future iteration with done:true; further push() calls report "channel-closed". Idempotent. */
+	close(): void {
+		if (this.closed) return;
+		this.closed = true;
+		for (const waiter of this.waiters.splice(0)) waiter({ value: undefined, done: true });
+	}
+
+	[Symbol.asyncIterator](): AsyncIterator<unknown> {
+		return {
+			next: (): Promise<IteratorResult<unknown>> => {
+				if (this.buffer.length > 0) return Promise.resolve({ value: this.buffer.shift(), done: false });
+				if (this.closed) return Promise.resolve({ value: undefined, done: true });
+				return new Promise((resolve) => this.waiters.push(resolve));
+			},
+		};
+	}
+}
+
+/**
+ * Vehicle Jobs run as in-process promises, not child processes -- there is
+ * no PID to reuse, but the same identity-confusion risk vstack's
+ * {pid, startToken, comm} design guards against still applies in a
+ * generalized form: a persisted job record written by one process
+ * instance must 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", the same conclusion vstack's identityMatches() reaches by
+ * comparing a live process's actual pid/start-time/command against a
+ * stored snapshot -- this is that same check with no process to inspect.
+ */
+export function vehicleJobIdentityMatches(recordInstanceToken: string, currentInstanceToken: string): boolean {
+	return recordInstanceToken === currentInstanceToken;
+}
+
+/** Minimal shape selectVehicleJobsForEviction needs from a job record -- kept separate from VehicleJobSnapshot so vehicle-server doesn't have to construct a full snapshot just to ask "should this be swept". */
+export interface VehicleJobEvictionCandidate {
+	readonly jobId: string;
+	readonly status: VehicleJobStatus;
+	readonly delivered: boolean;
+	readonly updatedAt: number;
+}
+
+export interface VehicleJobRetentionOptions {
+	/** Hard cap on total retained job records (of any status). A running job is never evicted regardless of this cap. */
+	readonly maxRetainedJobs: number;
+	/** A delivered terminal job becomes eligible for eviction once this many ms have passed since it was delivered (== updatedAt at delivery time). */
+	readonly deliveredRetentionMs: number;
+	readonly now: number;
+}
+
+/**
+ * Pure eviction-selection policy, kept separate from VehicleJobStore's own
+ * bookkeeping so the bounded-retention rule is independently testable.
+ * Preference order: (1) delivered and past deliveredRetentionMs, oldest
+ * first; (2) once still over maxRetainedJobs, any delivered terminal job,
+ * oldest first; (3) only as a last resort, an undelivered terminal job,
+ * oldest first -- a real loss (a caller may still want that result), but
+ * an unbounded store is a worse failure mode. A running job is never a
+ * candidate.
+ */
+export function selectVehicleJobsForEviction(
+	candidates: readonly VehicleJobEvictionCandidate[],
+	options: VehicleJobRetentionOptions,
+): readonly string[] {
+	const terminal = candidates.filter((candidate) => candidate.status !== "running");
+	const byAgeAscending = (a: VehicleJobEvictionCandidate, b: VehicleJobEvictionCandidate) => a.updatedAt - b.updatedAt;
+
+	const evicted = new Set<string>();
+	for (const candidate of terminal) {
+		if (candidate.delivered && options.now - candidate.updatedAt >= options.deliveredRetentionMs) evicted.add(candidate.jobId);
+	}
+
+	const remainingCount = () => candidates.length - evicted.size;
+	if (remainingCount() > options.maxRetainedJobs) {
+		const deliveredOldestFirst = terminal.filter((candidate) => candidate.delivered && !evicted.has(candidate.jobId)).sort(byAgeAscending);
+		for (const candidate of deliveredOldestFirst) {
+			if (remainingCount() <= options.maxRetainedJobs) break;
+			evicted.add(candidate.jobId);
+		}
+	}
+	if (remainingCount() > options.maxRetainedJobs) {
+		const undeliveredOldestFirst = terminal
+			.filter((candidate) => !candidate.delivered && !evicted.has(candidate.jobId))
+			.sort(byAgeAscending);
+		for (const candidate of undeliveredOldestFirst) {
+			if (remainingCount() <= options.maxRetainedJobs) break;
+			evicted.add(candidate.jobId);
+		}
+	}
+	return [...evicted];
+}