@danypops/vehicle-core 0.16.0 → 0.17.0

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export * from "./atomic-json.js";
 export * from "./vehicle-approvals.js";
 export * from "./vehicle-contract.js";
 export * from "./vehicle-errors.js";
+export * from "./vehicle-idempotency.js";
 export * from "./vehicle-jobs.js";
 export * from "./vehicle-scheduler.js";
 export * from "./vehicle-watchers.js";

package/dist/index.js

@@ -2,6 +2,7 @@ export * from "./atomic-json.js";
 export * from "./vehicle-approvals.js";
 export * from "./vehicle-contract.js";
 export * from "./vehicle-errors.js";
+export * from "./vehicle-idempotency.js";
 export * from "./vehicle-jobs.js";
 export * from "./vehicle-scheduler.js";
 export * from "./vehicle-watchers.js";

package/dist/vehicle-approvals.js

@@ -1,4 +1,19 @@
-import { defineVehicleEvent, defineVehicleSchema } from "./vehicle-contract.js";
+import { defineVehicleEvent, defineVehicleSchema, VEHICLE_EFFECTS } from "./vehicle-contract.js";
+/** A sha256 hex digest: exactly 64 lowercase hex characters -- matches hashApprovalInput's own (vehicle-server) output shape. */
+const SHA256_HEX_PATTERN = /^[0-9a-f]{64}$/;
+function isVehicleEffect(value) {
+    return typeof value === "string" && VEHICLE_EFFECTS.includes(value);
+}
+function isVehiclePrincipal(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const candidate = value;
+    if (typeof candidate.id !== "string")
+        return false;
+    if (candidate.claims === undefined)
+        return true;
+    return typeof candidate.claims === "object" && candidate.claims !== null && !Array.isArray(candidate.claims);
+}
 /** Set once at registry-configuration time (VehicleRegistry.configureApprovals()); never on a per-invoke basis. */
 export const DEFAULT_APPROVAL_EFFECTS = ["destructive", "open-world"];
 /**
@@ -21,7 +36,8 @@ const requestedPayloadSchema = defineVehicleSchema({
             requestId: { type: "string" },
             operationName: { type: "string" },
             operationVersion: { type: "number" },
-            effect: { type: "string" },
+            effect: { type: "string", enum: [...VEHICLE_EFFECTS] },
+            principal: { type: "object" },
             requestedAt: { type: "number" },
             expiresAt: { type: "number" },
             inputHash: { type: "string" },
@@ -36,12 +52,20 @@ const requestedPayloadSchema = defineVehicleSchema({
         if (typeof row.requestId !== "string" ||
             typeof row.operationName !== "string" ||
             typeof row.operationVersion !== "number" ||
-            typeof row.effect !== "string" ||
+            !Number.isInteger(row.operationVersion) ||
+            row.operationVersion < 1 ||
+            !isVehicleEffect(row.effect) ||
             typeof row.requestedAt !== "number" ||
+            !Number.isFinite(row.requestedAt) ||
             typeof row.expiresAt !== "number" ||
-            typeof row.inputHash !== "string") {
+            !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 };
     },
 });
@@ -64,9 +88,16 @@ const resolvedPayloadSchema = defineVehicleSchema({
         const row = value;
         if (typeof row.requestId !== "string" ||
             (row.decision !== "granted" && row.decision !== "denied") ||
-            typeof row.decidedAt !== "number") {
+            typeof row.decidedAt !== "number" ||
+            !Number.isFinite(row.decidedAt)) {
             return { success: false, issues: [{ path: [], message: "invalid approval outcome payload" }] };
         }
+        if (row.decidedBy !== undefined && typeof row.decidedBy !== "string") {
+            return { success: false, issues: [{ path: ["decidedBy"], message: "decidedBy must be a string" }] };
+        }
+        if (row.comment !== undefined && typeof row.comment !== "string") {
+            return { success: false, issues: [{ path: ["comment"], message: "comment must be a string" }] };
+        }
         return { success: true, value: row };
     },
 });

package/dist/vehicle-contract.d.ts

@@ -46,10 +46,14 @@ export interface LooseObjectProperty {
 /**
  * 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 `enum` has to be checked here for
- * real, or it's a documentation gesture, not an honest contract. Every
- * consumer projecting a plain-object input onto a VehicleOperation needs the
- * same required/enum checks; this is that check written once.
+ * 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). */
@@ -86,7 +90,9 @@ export interface WithVehicleContent {
  * risk forwarding partial/garbled blocks.
  */
 export declare function extractVehicleContent(output: unknown): readonly VehicleContentBlock[] | undefined;
-export type VehicleEffect = "read" | "local-write" | "external-write" | "destructive" | "open-world";
+/** 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];
 export type VehicleIdempotency = {
     readonly mode: "safe";
 } | {

package/dist/vehicle-contract.js

@@ -26,13 +26,38 @@ export function defineVehicleSchema(codec) {
         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 `enum` has to be checked here for
- * real, or it's a documentation gesture, not an honest contract. Every
- * consumer projecting a plain-object input onto a VehicleOperation needs the
- * same required/enum checks; this is that check written once.
+ * 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({
@@ -50,10 +75,17 @@ export function defineLooseObjectSchema(properties, 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 (!schema.enum || !(key in input))
+                if (!(key in input))
                     continue;
-                if (!schema.enum.includes(input[key])) {
+                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(", ")}` }] };
                 }
             }
@@ -91,6 +123,8 @@ export function extractVehicleContent(output) {
     }
     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");

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" | "job-not-steerable" | "job-steer-queue-full";
+export type VehicleCoreErrorCode = "duplicate-owner" | "not-found" | "invalid-input" | "invalid-output" | "permission-denied" | "request-too-large" | "response-too-large" | "cancelled" | "deadline-exceeded" | "handler-failed" | "policy-failed" | "idempotency-key-required" | "idempotency-conflict" | "client-closed" | "operation-unavailable" | "background-not-supported" | "job-not-found" | "job-not-steerable" | "job-steer-queue-full";
 export interface VehicleRecovery {
     readonly operation?: string;
     readonly message: string;
@@ -61,6 +61,17 @@ export declare class VehicleError extends Error {
 }
 /** Recognizes VehicleError instances across duplicated package installations in one process. */
 export declare function isVehicleError(value: unknown): value is VehicleError;
+/**
+ * Reconstructs a throwable VehicleError from a previously-serialized VehicleFailure -- the inverse
+ * of VehicleError.prototype.toFailure(), needed anywhere a wire-safe failure gets replayed as a
+ * real rejection later (e.g. VehicleIdempotencyPolicy replaying a settled failed receipt to a
+ * second caller reusing the same idempotency key). Lossy on purpose: a VehicleFailure never
+ * carries the original `cause` (toFailure() already reduced it to an optional bounded
+ * causeMessage per the throw site's own exposeCause choice), so the reconstructed error has no
+ * cause at all rather than fabricating one -- a replayed failure only needs to match the original
+ * code/category/message/details a caller would react to, not its internal cause chain.
+ */
+export declare function vehicleErrorFromFailure(failure: VehicleFailure): VehicleError;
 /** Extracts a bounded, wire-safe message from an unknown cause -- never the full stack trace, never an unbounded payload. */
 export declare function boundedCauseMessage(cause: unknown): string | undefined;
 export declare function boundedValidationDetails(issues: readonly VehicleSchemaIssue[] | undefined): JsonValue | undefined;

package/dist/vehicle-errors.js

@@ -60,6 +60,26 @@ export class VehicleError extends Error {
 export function isVehicleError(value) {
     return value instanceof Error && Reflect.get(value, VEHICLE_ERROR_BRAND) === true;
 }
+/**
+ * Reconstructs a throwable VehicleError from a previously-serialized VehicleFailure -- the inverse
+ * of VehicleError.prototype.toFailure(), needed anywhere a wire-safe failure gets replayed as a
+ * real rejection later (e.g. VehicleIdempotencyPolicy replaying a settled failed receipt to a
+ * second caller reusing the same idempotency key). Lossy on purpose: a VehicleFailure never
+ * carries the original `cause` (toFailure() already reduced it to an optional bounded
+ * causeMessage per the throw site's own exposeCause choice), so the reconstructed error has no
+ * cause at all rather than fabricating one -- a replayed failure only needs to match the original
+ * code/category/message/details a caller would react to, not its internal cause chain.
+ */
+export function vehicleErrorFromFailure(failure) {
+    return new VehicleError(failure.code, failure.message, {
+        category: failure.category,
+        retryable: failure.retryable,
+        retryAfterMs: failure.retryAfterMs,
+        recovery: failure.recovery,
+        details: failure.details,
+        operationId: failure.operationId,
+    });
+}
 const MAX_CAUSE_MESSAGE_LENGTH = 500;
 /** Extracts a bounded, wire-safe message from an unknown cause -- never the full stack trace, never an unbounded payload. */
 export function boundedCauseMessage(cause) {

package/dist/vehicle-idempotency.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Pure pieces of Vehicle's bounded keyed-idempotency replay policy: the settled-receipt shape and
+ * its eviction-selection rule. Orchestration (in-flight dedup, persistence, fail-closed conflict
+ * detection) lives in vehicle-server's VehicleIdempotencyPolicy -- mirrors the vehicle-jobs.js /
+ * VehicleJobStore split (a pure, independently-testable bounded-retention rule here; the stateful
+ * store that calls it lives in vehicle-server).
+ */
+import type { VehicleFailure } from "./vehicle-errors.js";
+/** A settled keyed-idempotency outcome -- exactly what gets replayed to a caller reusing the same key. Never carries the original request's raw input (only its hash is ever retained, see VehicleIdempotencyReceipt) and never a credential: `output`/`failure` are already what the operation would hand back to any caller, the same wire-safe boundary VehicleJobPersistedRecord's own `output`/`error` fields already cross. */
+export type VehicleIdempotencyResult = {
+    readonly ok: true;
+    readonly output: unknown;
+} | {
+    readonly ok: false;
+    readonly failure: VehicleFailure;
+};
+/**
+ * One settled keyed-idempotency receipt. Deliberately excludes the original request's raw input --
+ * `inputHash` is the only trace of it retained, so a persisted receipt can never leak whatever the
+ * caller originally sent (which may carry sensitive arguments the operation's own output does not).
+ * A still-in-flight (pending) request has no receipt yet -- that bookkeeping is transient,
+ * in-memory-only state in VehicleIdempotencyPolicy, deliberately never a candidate for persistence
+ * or eviction (mirrors "a running job is never a candidate" in vehicle-jobs.js's own job eviction).
+ */
+export interface VehicleIdempotencyReceipt {
+    readonly key: string;
+    readonly operationName: string;
+    readonly operationVersion: number;
+    readonly inputHash: string;
+    readonly settledAt: number;
+    /** settledAt + the descriptor's own keyed retentionMs at the time this receipt settled. A receipt past this is no longer a valid replay -- see selectVehicleIdempotencyReceiptsForEviction. */
+    readonly expiresAt: number;
+    readonly result: VehicleIdempotencyResult;
+    /** Approximate serialized size of `result`, used only to enforce maxTotalBytes -- never exact byte-for-byte, matching every other Vehicle capacity bound's own "good enough to stay bounded" precedent (e.g. enforcePayloadSize). */
+    readonly sizeBytes: number;
+}
+/** Minimal shape selectVehicleIdempotencyReceiptsForEviction needs -- kept separate from VehicleIdempotencyReceipt's own `result` so a sweep never has to touch (or risk logging) the actual settled output/failure it's merely deciding whether to keep. */
+export interface VehicleIdempotencyEvictionCandidate {
+    readonly key: string;
+    readonly settledAt: number;
+    readonly expiresAt: number;
+    readonly sizeBytes: number;
+}
+export interface VehicleIdempotencyRetentionOptions {
+    /** Hard cap on total retained settled receipts. */
+    readonly maxEntries: number;
+    /** Hard cap on the sum of every retained receipt's own sizeBytes. */
+    readonly maxTotalBytes: number;
+    readonly now: number;
+}
+/**
+ * Pure eviction-selection policy for settled keyed-idempotency receipts, independently testable
+ * from VehicleIdempotencyPolicy's own bookkeeping -- mirrors selectVehicleJobsForEviction's own
+ * three-phase shape:
+ *
+ *  1. Any receipt already past its own `expiresAt` (a real per-operation retentionMs elapsed --
+ *     replaying it would no longer be correct, keeping it around would only be wasted memory).
+ *  2. If still over maxEntries once (1) is applied, the oldest remaining receipts by settledAt,
+ *     until back within budget.
+ *  3. If still over maxTotalBytes once (1)+(2) are applied, the oldest remaining receipts by
+ *     settledAt, until back within budget.
+ *
+ * A pending (still in-flight) request is never a candidate -- it has no receipt yet, so it can
+ * never appear in `candidates` at all; this function only ever sees settled ones.
+ */
+export declare function selectVehicleIdempotencyReceiptsForEviction(candidates: readonly VehicleIdempotencyEvictionCandidate[], options: VehicleIdempotencyRetentionOptions): readonly string[];

package/dist/vehicle-idempotency.js

@@ -0,0 +1,42 @@
+/**
+ * Pure eviction-selection policy for settled keyed-idempotency receipts, independently testable
+ * from VehicleIdempotencyPolicy's own bookkeeping -- mirrors selectVehicleJobsForEviction's own
+ * three-phase shape:
+ *
+ *  1. Any receipt already past its own `expiresAt` (a real per-operation retentionMs elapsed --
+ *     replaying it would no longer be correct, keeping it around would only be wasted memory).
+ *  2. If still over maxEntries once (1) is applied, the oldest remaining receipts by settledAt,
+ *     until back within budget.
+ *  3. If still over maxTotalBytes once (1)+(2) are applied, the oldest remaining receipts by
+ *     settledAt, until back within budget.
+ *
+ * A pending (still in-flight) request is never a candidate -- it has no receipt yet, so it can
+ * never appear in `candidates` at all; this function only ever sees settled ones.
+ */
+export function selectVehicleIdempotencyReceiptsForEviction(candidates, options) {
+    const byAgeAscending = (a, b) => a.settledAt - b.settledAt;
+    const evicted = new Set();
+    for (const candidate of candidates) {
+        if (options.now >= candidate.expiresAt)
+            evicted.add(candidate.key);
+    }
+    const remaining = () => candidates.filter((candidate) => !evicted.has(candidate.key));
+    if (remaining().length > options.maxEntries) {
+        const oldestFirst = remaining().sort(byAgeAscending);
+        for (const candidate of oldestFirst) {
+            if (remaining().length <= options.maxEntries)
+                break;
+            evicted.add(candidate.key);
+        }
+    }
+    const totalBytes = () => remaining().reduce((sum, candidate) => sum + candidate.sizeBytes, 0);
+    if (totalBytes() > options.maxTotalBytes) {
+        const oldestFirst = remaining().sort(byAgeAscending);
+        for (const candidate of oldestFirst) {
+            if (totalBytes() <= options.maxTotalBytes)
+                break;
+            evicted.add(candidate.key);
+        }
+    }
+    return [...evicted];
+}

package/dist/vehicle-scheduler.d.ts

@@ -49,7 +49,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/vehicle-scheduler.js

@@ -11,8 +11,36 @@ export class VehicleScheduleLimitExceeded extends Error {
         this.name = "VehicleScheduleLimitExceeded";
     }
 }
-/** 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 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. */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@danypops/vehicle-core",
-	"version": "0.16.0",
+	"version": "0.17.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/index.ts

@@ -2,6 +2,7 @@ export * from "./atomic-json.js";
 export * from "./vehicle-approvals.js";
 export * from "./vehicle-contract.js";
 export * from "./vehicle-errors.js";
+export * from "./vehicle-idempotency.js";
 export * from "./vehicle-jobs.js";
 export * from "./vehicle-scheduler.js";
 export * from "./vehicle-watchers.js";

package/src/vehicle-approvals.ts

@@ -7,7 +7,22 @@
  * 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, defineVehicleSchema, VEHICLE_EFFECTS } from "./vehicle-contract.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 +89,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" },
@@ -89,13 +105,21 @@ const requestedPayloadSchema = defineVehicleSchema<VehicleApprovalRequest>({
 			typeof row.requestId !== "string" ||
 			typeof row.operationName !== "string" ||
 			typeof row.operationVersion !== "number" ||
-			typeof row.effect !== "string" ||
+			!Number.isInteger(row.operationVersion) ||
+			row.operationVersion < 1 ||
+			!isVehicleEffect(row.effect) ||
 			typeof row.requestedAt !== "number" ||
+			!Number.isFinite(row.requestedAt) ||
 			typeof row.expiresAt !== "number" ||
-			typeof row.inputHash !== "string"
+			!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 };
 	},
 });
@@ -119,10 +143,17 @@ const resolvedPayloadSchema = defineVehicleSchema<VehicleApprovalOutcome>({
 		if (
 			typeof row.requestId !== "string" ||
 			(row.decision !== "granted" && row.decision !== "denied") ||
-			typeof row.decidedAt !== "number"
+			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/vehicle-contract.ts

@@ -73,13 +73,39 @@ export interface LooseObjectProperty {
 	readonly enum?: readonly string[];
 }
 
+/** 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: string, value: unknown): boolean {
+	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 `enum` has to be checked here for
- * real, or it's a documentation gesture, not an honest contract. Every
- * consumer projecting a plain-object input onto a VehicleOperation needs the
- * same required/enum checks; this is that check written once.
+ * 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: Record<string, LooseObjectProperty>,
@@ -99,9 +125,15 @@ export function defineLooseObjectSchema(
 			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 (!schema.enum || !(key in input)) continue;
-				if (!schema.enum.includes(input[key] as string)) {
+				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] as string)) {
 					return { success: false, issues: [{ path: [key], message: `${key} must be one of ${schema.enum.join(", ")}` }] };
 				}
 			}
@@ -163,7 +195,9 @@ export function extractVehicleContent(output: unknown): readonly VehicleContentB
 	return blocks;
 }
 
-export type VehicleEffect = "read" | "local-write" | "external-write" | "destructive" | "open-world";
+/** 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"] as const;
+export type VehicleEffect = (typeof VEHICLE_EFFECTS)[number];
 
 export type VehicleIdempotency =
 	| { readonly mode: "safe" }

package/src/vehicle-errors.ts

@@ -26,6 +26,7 @@ export type VehicleCoreErrorCode =
 	| "handler-failed"
 	| "policy-failed"
 	| "idempotency-key-required"
+	| "idempotency-conflict"
 	| "client-closed"
 	| "operation-unavailable"
 	| "background-not-supported"
@@ -156,6 +157,27 @@ export function isVehicleError(value: unknown): value is VehicleError {
 	return value instanceof Error && Reflect.get(value, VEHICLE_ERROR_BRAND) === true;
 }
 
+/**
+ * Reconstructs a throwable VehicleError from a previously-serialized VehicleFailure -- the inverse
+ * of VehicleError.prototype.toFailure(), needed anywhere a wire-safe failure gets replayed as a
+ * real rejection later (e.g. VehicleIdempotencyPolicy replaying a settled failed receipt to a
+ * second caller reusing the same idempotency key). Lossy on purpose: a VehicleFailure never
+ * carries the original `cause` (toFailure() already reduced it to an optional bounded
+ * causeMessage per the throw site's own exposeCause choice), so the reconstructed error has no
+ * cause at all rather than fabricating one -- a replayed failure only needs to match the original
+ * code/category/message/details a caller would react to, not its internal cause chain.
+ */
+export function vehicleErrorFromFailure(failure: VehicleFailure): VehicleError {
+	return new VehicleError(failure.code, failure.message, {
+		category: failure.category,
+		retryable: failure.retryable,
+		retryAfterMs: failure.retryAfterMs,
+		recovery: failure.recovery,
+		details: failure.details,
+		operationId: failure.operationId,
+	});
+}
+
 const MAX_CAUSE_MESSAGE_LENGTH = 500;
 
 /** Extracts a bounded, wire-safe message from an unknown cause -- never the full stack trace, never an unbounded payload. */

package/src/vehicle-idempotency.ts

@@ -0,0 +1,97 @@
+/**
+ * Pure pieces of Vehicle's bounded keyed-idempotency replay policy: the settled-receipt shape and
+ * its eviction-selection rule. Orchestration (in-flight dedup, persistence, fail-closed conflict
+ * detection) lives in vehicle-server's VehicleIdempotencyPolicy -- mirrors the vehicle-jobs.js /
+ * VehicleJobStore split (a pure, independently-testable bounded-retention rule here; the stateful
+ * store that calls it lives in vehicle-server).
+ */
+import type { VehicleFailure } from "./vehicle-errors.js";
+
+/** A settled keyed-idempotency outcome -- exactly what gets replayed to a caller reusing the same key. Never carries the original request's raw input (only its hash is ever retained, see VehicleIdempotencyReceipt) and never a credential: `output`/`failure` are already what the operation would hand back to any caller, the same wire-safe boundary VehicleJobPersistedRecord's own `output`/`error` fields already cross. */
+export type VehicleIdempotencyResult =
+	| { readonly ok: true; readonly output: unknown }
+	| { readonly ok: false; readonly failure: VehicleFailure };
+
+/**
+ * One settled keyed-idempotency receipt. Deliberately excludes the original request's raw input --
+ * `inputHash` is the only trace of it retained, so a persisted receipt can never leak whatever the
+ * caller originally sent (which may carry sensitive arguments the operation's own output does not).
+ * A still-in-flight (pending) request has no receipt yet -- that bookkeeping is transient,
+ * in-memory-only state in VehicleIdempotencyPolicy, deliberately never a candidate for persistence
+ * or eviction (mirrors "a running job is never a candidate" in vehicle-jobs.js's own job eviction).
+ */
+export interface VehicleIdempotencyReceipt {
+	readonly key: string;
+	readonly operationName: string;
+	readonly operationVersion: number;
+	readonly inputHash: string;
+	readonly settledAt: number;
+	/** settledAt + the descriptor's own keyed retentionMs at the time this receipt settled. A receipt past this is no longer a valid replay -- see selectVehicleIdempotencyReceiptsForEviction. */
+	readonly expiresAt: number;
+	readonly result: VehicleIdempotencyResult;
+	/** Approximate serialized size of `result`, used only to enforce maxTotalBytes -- never exact byte-for-byte, matching every other Vehicle capacity bound's own "good enough to stay bounded" precedent (e.g. enforcePayloadSize). */
+	readonly sizeBytes: number;
+}
+
+/** Minimal shape selectVehicleIdempotencyReceiptsForEviction needs -- kept separate from VehicleIdempotencyReceipt's own `result` so a sweep never has to touch (or risk logging) the actual settled output/failure it's merely deciding whether to keep. */
+export interface VehicleIdempotencyEvictionCandidate {
+	readonly key: string;
+	readonly settledAt: number;
+	readonly expiresAt: number;
+	readonly sizeBytes: number;
+}
+
+export interface VehicleIdempotencyRetentionOptions {
+	/** Hard cap on total retained settled receipts. */
+	readonly maxEntries: number;
+	/** Hard cap on the sum of every retained receipt's own sizeBytes. */
+	readonly maxTotalBytes: number;
+	readonly now: number;
+}
+
+/**
+ * Pure eviction-selection policy for settled keyed-idempotency receipts, independently testable
+ * from VehicleIdempotencyPolicy's own bookkeeping -- mirrors selectVehicleJobsForEviction's own
+ * three-phase shape:
+ *
+ *  1. Any receipt already past its own `expiresAt` (a real per-operation retentionMs elapsed --
+ *     replaying it would no longer be correct, keeping it around would only be wasted memory).
+ *  2. If still over maxEntries once (1) is applied, the oldest remaining receipts by settledAt,
+ *     until back within budget.
+ *  3. If still over maxTotalBytes once (1)+(2) are applied, the oldest remaining receipts by
+ *     settledAt, until back within budget.
+ *
+ * A pending (still in-flight) request is never a candidate -- it has no receipt yet, so it can
+ * never appear in `candidates` at all; this function only ever sees settled ones.
+ */
+export function selectVehicleIdempotencyReceiptsForEviction(
+	candidates: readonly VehicleIdempotencyEvictionCandidate[],
+	options: VehicleIdempotencyRetentionOptions,
+): readonly string[] {
+	const byAgeAscending = (a: VehicleIdempotencyEvictionCandidate, b: VehicleIdempotencyEvictionCandidate) => a.settledAt - b.settledAt;
+
+	const evicted = new Set<string>();
+	for (const candidate of candidates) {
+		if (options.now >= candidate.expiresAt) evicted.add(candidate.key);
+	}
+
+	const remaining = () => candidates.filter((candidate) => !evicted.has(candidate.key));
+	if (remaining().length > options.maxEntries) {
+		const oldestFirst = remaining().sort(byAgeAscending);
+		for (const candidate of oldestFirst) {
+			if (remaining().length <= options.maxEntries) break;
+			evicted.add(candidate.key);
+		}
+	}
+
+	const totalBytes = () => remaining().reduce((sum, candidate) => sum + candidate.sizeBytes, 0);
+	if (totalBytes() > options.maxTotalBytes) {
+		const oldestFirst = remaining().sort(byAgeAscending);
+		for (const candidate of oldestFirst) {
+			if (totalBytes() <= options.maxTotalBytes) break;
+			evicted.add(candidate.key);
+		}
+	}
+
+	return [...evicted];
+}

package/src/vehicle-scheduler.ts

@@ -50,8 +50,33 @@ export class VehicleScheduleLimitExceeded extends Error {
 	}
 }
 
-/** 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 class VehicleScheduleInvalidTriggerError extends Error {
+	constructor(readonly trigger: VehicleScheduleTrigger) {
+		super(`Invalid Vehicle schedule trigger: ${JSON.stringify(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: VehicleScheduleTrigger): boolean {
+	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: VehicleScheduleTrigger, now: number): number {
+	if (!isValidVehicleScheduleTrigger(trigger)) throw new VehicleScheduleInvalidTriggerError(trigger);
 	return trigger.kind === "at" ? trigger.at : now + trigger.intervalMs;
 }