@danypops/vehicle-core 0.16.0 → 0.17.1

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";

package/dist/{vehicle-scheduler.d.ts → schedules/schedule.d.ts}

@@ -1,18 +1,16 @@
 /**
  * "Trigger something at a future time or on a recurring interval,"
  * independent of any specific job's own lifecycle -- a distinct shape from
- * Vehicle Jobs (submit-then-track a unit of work already running). Modeled
- * on ~/Workspace/alef's packages/core/foundry/src/scheduler.ts
- * (defer/repeat/cancel/list), generalized so the fired action is a
- * declarative Vehicle operation invocation or event emission -- never a
- * bespoke callback closure, so it can be persisted and re-armed after a
- * restart the way a closure never could.
+ * Vehicle Jobs (submit-then-track a unit of work already running). The
+ * fired action is a declarative Vehicle operation invocation or event
+ * emission -- never a bespoke callback closure, so it can be persisted and
+ * re-armed after a restart the way a closure never could.
  *
  * Pure pieces only: trigger/action shapes and the fire-time arithmetic.
  * Real timers, persistence, and registry wiring live in vehicle-server's
- * VehicleScheduler, the same core/server split vehicle-jobs.ts uses.
+ * VehicleScheduler, the same core/server split Vehicle Jobs uses.
  */
-import type { JsonValue } from "./vehicle-contract.js";
+import type { JsonValue } from "../schemas/json.js";
 export type VehicleScheduleTrigger = {
     readonly kind: "at";
     readonly at: number;
@@ -49,7 +47,23 @@ export declare class VehicleScheduleLimitExceeded extends Error {
     readonly max: number;
     constructor(owner: string, max: number);
 }
-/** The first fire time for a freshly created schedule. */
+/** Raised for a trigger whose own numeric field is non-finite, zero, or negative -- see isValidVehicleScheduleTrigger. A typed failure a caller can recognize by class, the same discoverability VehicleScheduleLimitExceeded already gives the capacity case. */
+export declare class VehicleScheduleInvalidTriggerError extends Error {
+    readonly trigger: VehicleScheduleTrigger;
+    constructor(trigger: VehicleScheduleTrigger);
+}
+/**
+ * Real validation for a VehicleScheduleTrigger's own numeric field -- `kind`/`at`/`intervalMs` are
+ * plain TypeScript types, never runtime-checked before this, so a wire or persisted trigger with a
+ * non-finite or non-positive value silently corrupted every arithmetic function below it:
+ * `now + NaN` poisons nextFireAt forever, `now + 0` or a negative intervalMs fires an "every"
+ * schedule again immediately on every tick (a respawn-storm-shaped bug), and a non-finite `at`
+ * breaks every `> now` comparison nextFireAtAfterRestore relies on. Both `at` and `intervalMs` are
+ * required to be a real, positive, finite number -- a wall-clock fire time or interval of zero,
+ * negative, NaN, or Infinity is never a legitimate schedule, only ever a wire/persistence defect.
+ */
+export declare function isValidVehicleScheduleTrigger(trigger: VehicleScheduleTrigger): boolean;
+/** The first fire time for a freshly created schedule. Throws VehicleScheduleInvalidTriggerError if `trigger` isn't valid -- see isValidVehicleScheduleTrigger; callers at a real wire/persistence boundary should validate (and reject/discard) before ever reaching here, this is a last-resort guard against a caller that skipped that. */
 export declare function initialFireAt(trigger: VehicleScheduleTrigger, now: number): number;
 /** The next fire time after a successful fire, or undefined if the entry (a one-shot "at") should be removed instead of re-armed. */
 export declare function nextFireAtAfterFire(trigger: VehicleScheduleTrigger, now: number): number | undefined;

package/dist/schedules/schedule.js

@@ -0,0 +1,61 @@
+/** Matches WatchRegistry's own historical default (Lector's MAX_WATCHES_PER_WORKSPACE). */
+export const DEFAULT_MAX_SCHEDULES_PER_OWNER = 32;
+/** Raised when an owner already has its configured maximum of schedules -- fails closed, the same bounded-resource discipline WatchLimitExceeded already applies to Vehicle Watchers. */
+export class VehicleScheduleLimitExceeded extends Error {
+    owner;
+    max;
+    constructor(owner, max) {
+        super(`owner "${owner}" already has ${max} active schedules -- cancel one before adding another`);
+        this.owner = owner;
+        this.max = max;
+        this.name = "VehicleScheduleLimitExceeded";
+    }
+}
+/** Raised for a trigger whose own numeric field is non-finite, zero, or negative -- see isValidVehicleScheduleTrigger. A typed failure a caller can recognize by class, the same discoverability VehicleScheduleLimitExceeded already gives the capacity case. */
+export class VehicleScheduleInvalidTriggerError extends Error {
+    trigger;
+    constructor(trigger) {
+        super(`Invalid Vehicle schedule trigger: ${JSON.stringify(trigger)}`);
+        this.trigger = trigger;
+        this.name = "VehicleScheduleInvalidTriggerError";
+    }
+}
+/**
+ * Real validation for a VehicleScheduleTrigger's own numeric field -- `kind`/`at`/`intervalMs` are
+ * plain TypeScript types, never runtime-checked before this, so a wire or persisted trigger with a
+ * non-finite or non-positive value silently corrupted every arithmetic function below it:
+ * `now + NaN` poisons nextFireAt forever, `now + 0` or a negative intervalMs fires an "every"
+ * schedule again immediately on every tick (a respawn-storm-shaped bug), and a non-finite `at`
+ * breaks every `> now` comparison nextFireAtAfterRestore relies on. Both `at` and `intervalMs` are
+ * required to be a real, positive, finite number -- a wall-clock fire time or interval of zero,
+ * negative, NaN, or Infinity is never a legitimate schedule, only ever a wire/persistence defect.
+ */
+export function isValidVehicleScheduleTrigger(trigger) {
+    if (trigger.kind === "at")
+        return Number.isFinite(trigger.at) && trigger.at > 0;
+    if (trigger.kind === "every")
+        return Number.isFinite(trigger.intervalMs) && trigger.intervalMs > 0;
+    return false;
+}
+/** The first fire time for a freshly created schedule. Throws VehicleScheduleInvalidTriggerError if `trigger` isn't valid -- see isValidVehicleScheduleTrigger; callers at a real wire/persistence boundary should validate (and reject/discard) before ever reaching here, this is a last-resort guard against a caller that skipped that. */
+export function initialFireAt(trigger, now) {
+    if (!isValidVehicleScheduleTrigger(trigger))
+        throw new VehicleScheduleInvalidTriggerError(trigger);
+    return trigger.kind === "at" ? trigger.at : now + trigger.intervalMs;
+}
+/** The next fire time after a successful fire, or undefined if the entry (a one-shot "at") should be removed instead of re-armed. */
+export function nextFireAtAfterFire(trigger, now) {
+    return trigger.kind === "every" ? now + trigger.intervalMs : undefined;
+}
+/**
+ * Where a restored entry should be re-armed to. A one-shot "at" entry keeps
+ * its original persisted time (fires as soon as possible if overdue -- the
+ * one thing it was supposed to do must not be silently lost). A recurring
+ * "every" entry resumes its normal cadence from now if it fell behind while
+ * the daemon was down, rather than firing once per missed tick.
+ */
+export function nextFireAtAfterRestore(trigger, persistedNextFireAt, now) {
+    if (trigger.kind === "at")
+        return persistedNextFireAt;
+    return persistedNextFireAt > now ? persistedNextFireAt : now + trigger.intervalMs;
+}

package/dist/schemas/codec.d.ts

@@ -0,0 +1,25 @@
+import { type JsonSchema } from "./json.js";
+export interface VehicleSchemaIssue {
+    readonly path: readonly (string | number)[];
+    readonly message: string;
+}
+export type VehicleSchemaResult<T> = {
+    readonly success: true;
+    readonly value: T;
+} | {
+    readonly success: false;
+    readonly issues?: readonly VehicleSchemaIssue[];
+};
+/**
+ * A serializable, descriptive `jsonSchema` (surfaced to a client or Pi tool
+ * projection) paired with a real `safeParse` that actually enforces it at
+ * runtime -- a Vehicle registry's own `invoke()` only ever calls
+ * `safeParse`; `jsonSchema` alone is never itself enforced, so a codec that
+ * only sets `jsonSchema` without a matching `safeParse` is a documentation
+ * gesture, not an honest contract.
+ */
+export interface VehicleSchemaCodec<T> {
+    readonly jsonSchema: JsonSchema;
+    safeParse(value: unknown): VehicleSchemaResult<T>;
+}
+export declare function defineVehicleSchema<T>(codec: VehicleSchemaCodec<T>): VehicleSchemaCodec<T>;

package/dist/schemas/codec.js

@@ -0,0 +1,7 @@
+import { cloneJson } from "./json.js";
+export function defineVehicleSchema(codec) {
+    return Object.freeze({
+        jsonSchema: cloneJson(codec.jsonSchema),
+        safeParse: codec.safeParse,
+    });
+}

package/dist/schemas/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./codec.js";
+export * from "./json.js";
+export * from "./loose-object.js";
+export * from "./presentation.js";

package/dist/schemas/index.js

@@ -0,0 +1,4 @@
+export * from "./codec.js";
+export * from "./json.js";
+export * from "./loose-object.js";
+export * from "./presentation.js";

package/dist/schemas/json.d.ts

@@ -0,0 +1,7 @@
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+export type JsonSchema = Readonly<Record<string, JsonValue>>;
+export declare function cloneJson<T extends JsonValue>(value: T): T;
+export declare function freezeJson(value: JsonValue): JsonValue;

package/dist/schemas/json.js

@@ -0,0 +1,14 @@
+export 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));
+}
+export 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/schemas/loose-object.d.ts

@@ -0,0 +1,20 @@
+import { type VehicleSchemaCodec } from "./codec.js";
+export interface LooseObjectProperty {
+    readonly type: string;
+    readonly enum?: readonly string[];
+}
+/**
+ * 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 declare function defineLooseObjectSchema(properties: Record<string, LooseObjectProperty>, required?: readonly string[]): VehicleSchemaCodec<Record<string, unknown>>;
+/** 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 declare const passthroughVehicleSchema: VehicleSchemaCodec<unknown>;

package/dist/schemas/loose-object.js

@@ -0,0 +1,73 @@
+import { defineVehicleSchema } from "./codec.js";
+/** 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 }),
+});

package/dist/schemas/presentation.d.ts

@@ -0,0 +1,11 @@
+/** Shared defense-in-depth vocabulary for credential-shaped fields at every Vehicle projection boundary. */
+export declare const VEHICLE_CREDENTIAL_FIELD_NAMES: readonly ["password", "token", "accessToken", "refreshToken", "apiKey", "secret", "authorization", "credential"];
+/** Case/separator-insensitive credential-name check used as a fallback when a schema annotation is missing. */
+export declare function isVehicleCredentialFieldName(name: string): boolean;
+/**
+ * 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 declare const VEHICLE_SCHEMA_PRESENTATION_EXTENSION: "x-vehicle-presentation";
+export type VehicleSchemaPresentation = "omit" | "summarize";

package/dist/schemas/presentation.js

@@ -0,0 +1,22 @@
+/** 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";

package/dist/watches/index.d.ts

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

package/dist/watches/index.js

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

package/dist/{vehicle-watchers.d.ts → watches/registry.d.ts}

@@ -1,13 +1,6 @@
 /**
- * "Watch a changing resource, get notified" -- lifted near-verbatim from
- * Lector's own `WatchRegistry` (packages/lector/src/domain/watch-registry.ts),
- * generalized past Lector's own workspace/pattern vocabulary (`workspaceId`
- * -> `scope`, `pattern` -> `resource`) into a shared Vehicle primitive.
- * Confirmed independently reinvented three-plus times across this house's
- * own ecosystem before this existed: Lector's own registry, Lector's CLI
- * (a second, non-resilient reimplementation of the same watch/subscribe
- * shape), and Papyrus's TaskOverlay/NoteOverlay (each hand-rolling the same
- * ensurePushChannel()+poll dance independently).
+ * "Watch a changing resource, get notified" -- a shared Vehicle primitive
+ * generalizing a (scope, resource) watch registration into a wire topic.
  *
  * Pure, in-memory bookkeeping only -- no filesystem, network, or PushChannel
  * I/O here. Matching pattern/resource against a real changed resource is a

package/dist/{vehicle-watchers.js → watches/registry.js}

@@ -1,13 +1,6 @@
 /**
- * "Watch a changing resource, get notified" -- lifted near-verbatim from
- * Lector's own `WatchRegistry` (packages/lector/src/domain/watch-registry.ts),
- * generalized past Lector's own workspace/pattern vocabulary (`workspaceId`
- * -> `scope`, `pattern` -> `resource`) into a shared Vehicle primitive.
- * Confirmed independently reinvented three-plus times across this house's
- * own ecosystem before this existed: Lector's own registry, Lector's CLI
- * (a second, non-resilient reimplementation of the same watch/subscribe
- * shape), and Papyrus's TaskOverlay/NoteOverlay (each hand-rolling the same
- * ensurePushChannel()+poll dance independently).
+ * "Watch a changing resource, get notified" -- a shared Vehicle primitive
+ * generalizing a (scope, resource) watch registration into a wire topic.
  *
  * Pure, in-memory bookkeeping only -- no filesystem, network, or PushChannel
  * I/O here. Matching pattern/resource against a real changed resource is a

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@danypops/vehicle-core",
-	"version": "0.16.0",
+	"version": "0.17.1",
 	"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",
@@ -10,6 +10,10 @@
 		".": {
 			"types": "./dist/index.d.ts",
 			"default": "./dist/index.js"
+		},
+		"./persistence": {
+			"types": "./dist/persistence/index.d.ts",
+			"default": "./dist/persistence/index.js"
 		}
 	},
 	"scripts": {

package/src/{vehicle-approvals.ts → approvals/approval.ts}

@@ -6,8 +6,26 @@
  * 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 { defineVehicleEvent, defineVehicleSchema } from "./vehicle-contract.js";
+import { defineVehicleEvent } from "../events/event.js";
+import type { VehiclePrincipal } from "../operations/context.js";
+import type { VehicleEffect } from "../operations/effect.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: unknown): value is VehicleEffect {
+	return typeof value === "string" && (VEHICLE_EFFECTS as readonly string[]).includes(value);
+}
+
+function isVehiclePrincipal(value: unknown): value is VehiclePrincipal {
+	if (typeof value !== "object" || value === null) return false;
+	const candidate = value as Record<string, unknown>;
+	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: readonly VehicleEffect[] = ["destructive", "open-world"];
@@ -74,7 +92,8 @@ const requestedPayloadSchema = defineVehicleSchema<VehicleApprovalRequest>({
 			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" },
@@ -86,16 +105,24 @@ const requestedPayloadSchema = defineVehicleSchema<VehicleApprovalRequest>({
 		if (typeof value !== "object" || value === null) return { success: false, issues: [{ path: [], message: "input must be an object" }] };
 		const row = value as Record<string, unknown>;
 		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"
+			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 as unknown as VehicleApprovalRequest };
 	},
 });
@@ -117,12 +144,19 @@ const resolvedPayloadSchema = defineVehicleSchema<VehicleApprovalOutcome>({
 		if (typeof value !== "object" || value === null) return { success: false, issues: [{ path: [], message: "input must be an object" }] };
 		const row = value as Record<string, unknown>;
 		if (
-			typeof row.requestId !== "string" ||
-			(row.decision !== "granted" && row.decision !== "denied") ||
-			typeof row.decidedAt !== "number"
+			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 as unknown as VehicleApprovalOutcome };
 	},
 });

package/src/approvals/index.ts

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

package/src/client/client.ts

@@ -0,0 +1,31 @@
+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/src/client/index.ts

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