@danypops/vehicle-core 0.17.0 → 0.17.1

package/dist/vehicle-contract.js

@@ -1,253 +0,0 @@
-/** Shared defense-in-depth vocabulary for credential-shaped fields at every Vehicle projection boundary. */
-export const VEHICLE_CREDENTIAL_FIELD_NAMES = Object.freeze([
-    "password",
-    "token",
-    "accessToken",
-    "refreshToken",
-    "apiKey",
-    "secret",
-    "authorization",
-    "credential",
-]);
-const NORMALIZED_VEHICLE_CREDENTIAL_FIELD_NAMES = new Set(VEHICLE_CREDENTIAL_FIELD_NAMES.map((name) => name.replace(/[^a-z0-9]/gi, "").toLowerCase()));
-/** Case/separator-insensitive credential-name check used as a fallback when a schema annotation is missing. */
-export function isVehicleCredentialFieldName(name) {
-    return NORMALIZED_VEHICLE_CREDENTIAL_FIELD_NAMES.has(name.replace(/[^a-z0-9]/gi, "").toLowerCase());
-}
-/**
- * JSON Schema property annotation consumed by human-facing Vehicle adapters.
- * `omit` hides the field; `summarize` may show shape/size but never its value.
- * Standard `writeOnly: true` and `format: "password"` always imply omission.
- */
-export const VEHICLE_SCHEMA_PRESENTATION_EXTENSION = "x-vehicle-presentation";
-export function defineVehicleSchema(codec) {
-    return Object.freeze({
-        jsonSchema: cloneJson(codec.jsonSchema),
-        safeParse: codec.safeParse,
-    });
-}
-/** JSON Schema's own `type` keyword vocabulary -- checked for real below so a declared `type: "number"` (say) can't silently accept a string forever. `"integer"` additionally requires no fractional part, matching JSON Schema's own distinction from plain `"number"`. An unrecognized type name is treated as "anything goes" (matches passthroughVehicleSchema's own precedent for a shape not worth strictly enforcing) rather than rejecting every input outright for what would otherwise be a schema-authoring typo. */
-function matchesLooseObjectPropertyType(type, value) {
-    switch (type) {
-        case "string":
-            return typeof value === "string";
-        case "number":
-            return typeof value === "number" && Number.isFinite(value);
-        case "integer":
-            return typeof value === "number" && Number.isInteger(value);
-        case "boolean":
-            return typeof value === "boolean";
-        case "object":
-            return typeof value === "object" && value !== null && !Array.isArray(value);
-        case "array":
-            return Array.isArray(value);
-        case "null":
-            return value === null;
-        default:
-            return true;
-    }
-}
-/**
- * A VehicleRegistry only ever calls a schema's own safeParse -- jsonSchema is
- * descriptive metadata surfaced to a client/Pi projection, never itself
- * enforced at runtime -- so a declared `type`/`enum`/`additionalProperties: false`
- * has to be checked here for real, or it's a documentation gesture, not an
- * honest contract (the exact drift this function's own jsonSchema metadata
- * had before: it always advertised `additionalProperties: false` and a
- * per-property `type`, while safeParse only ever checked `required` and
- * `enum`). Every consumer projecting a plain-object input onto a
- * VehicleOperation needs the same required/type/extra-key/enum checks; this
- * is that check written once.
- */
-export function defineLooseObjectSchema(properties, required = []) {
-    return defineVehicleSchema({
-        // LooseObjectProperty's named fields (type, enum) are all JSON-value-shaped
-        // at runtime, but TypeScript's structural check against the recursive
-        // JsonValue union doesn't see that through a plain interface -- the cast
-        // is a type-system limitation, not a runtime concern.
-        jsonSchema: { type: "object", properties: properties, required: [...required], additionalProperties: false },
-        safeParse(value) {
-            if (typeof value !== "object" || value === null || Array.isArray(value)) {
-                return { success: false, issues: [{ path: [], message: "input must be an object" }] };
-            }
-            const input = value;
-            for (const key of required) {
-                if (!(key in input))
-                    return { success: false, issues: [{ path: [key], message: `${key} is required` }] };
-            }
-            for (const key of Object.keys(input)) {
-                if (!(key in properties))
-                    return { success: false, issues: [{ path: [key], message: `${key} is not a recognized property` }] };
-            }
-            for (const [key, schema] of Object.entries(properties)) {
-                if (!(key in input))
-                    continue;
-                if (!matchesLooseObjectPropertyType(schema.type, input[key])) {
-                    return { success: false, issues: [{ path: [key], message: `${key} must be of type ${schema.type}` }] };
-                }
-                if (schema.enum && !schema.enum.includes(input[key])) {
-                    return { success: false, issues: [{ path: [key], message: `${key} must be one of ${schema.enum.join(", ")}` }] };
-                }
-            }
-            return { success: true, value: input };
-        },
-    });
-}
-/** Accepts any value unvalidated -- for an operation whose output shape isn't worth a dedicated schema (an internal/low-stakes result, or one already validated upstream by the domain logic it wraps). */
-export const passthroughVehicleSchema = defineVehicleSchema({
-    jsonSchema: { type: "object" },
-    safeParse: (value) => ({ success: true, value }),
-});
-/**
- * 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;
-}
-/** 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"];
-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}`;
-}
-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");
-        }
-    }
-}
-function cloneJson(value) {
-    const serialized = JSON.stringify(value);
-    if (serialized === undefined)
-        throw new Error("Vehicle JSON metadata must be serializable");
-    return freezeJson(JSON.parse(serialized));
-}
-function freezeJson(value) {
-    if (Array.isArray(value))
-        return Object.freeze(value.map(freezeJson));
-    if (value !== null && typeof value === "object") {
-        return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, child]) => [key, freezeJson(child)])));
-    }
-    return value;
-}

package/dist/vehicle-jobs.d.ts

@@ -1,159 +0,0 @@
-/** Pure pieces of Vehicle Jobs: a termination-reason resolver and a bounded wake-log accumulator. Orchestration lives in vehicle-server's VehicleJobStore. */
-import type { VehiclePrincipal } from "./vehicle-contract.js";
-import type { VehicleFailure } from "./vehicle-errors.js";
-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;
-/** "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;
-}
-/** 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;
-}
-/**
- * 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;
-}
-/**
- * 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,182 +0,0 @@
-/** 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. "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(", ")}`);
-}
-/** 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;
-    }
-}
-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);
-}
-/** 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];
-}