@danypops/vehicle-core 0.9.0 → 0.11.0

package/dist/index.d.ts

@@ -3,4 +3,5 @@ export * from "./vehicle-approvals.js";
 export * from "./vehicle-contract.js";
 export * from "./vehicle-errors.js";
 export * from "./vehicle-jobs.js";
+export * from "./vehicle-scheduler.js";
 export * from "./vehicle-watchers.js";

package/dist/index.js

@@ -3,4 +3,5 @@ export * from "./vehicle-approvals.js";
 export * from "./vehicle-contract.js";
 export * from "./vehicle-errors.js";
 export * from "./vehicle-jobs.js";
+export * from "./vehicle-scheduler.js";
 export * from "./vehicle-watchers.js";

package/dist/vehicle-errors.d.ts

@@ -14,6 +14,14 @@ export interface VehicleFailure {
     readonly recovery?: VehicleRecovery;
     readonly details?: JsonValue;
     readonly operationId?: string;
+    /**
+     * The underlying cause's own message, when this failure wraps an unexpected error (e.g. a
+     * handler throwing something other than a VehicleError) -- bounded, never a full stack trace.
+     * Without this, a caller sees only a generic template like "x handler failed" and has no way
+     * to tell what actually went wrong or whether the underlying operation may have partially
+     * applied.
+     */
+    readonly causeMessage?: string;
 }
 export interface VehicleErrorOptions {
     readonly category: VehicleFailureCategory;
@@ -23,6 +31,15 @@ export interface VehicleErrorOptions {
     readonly details?: JsonValue;
     readonly operationId?: string;
     readonly cause?: unknown;
+    /**
+     * Secure by default (false): `cause` is always attached to the real in-process Error chain
+     * (for server-side logging/observability), but its message crosses the wire via
+     * toFailure().causeMessage only when the throw site explicitly opts in here -- an arbitrary
+     * cause's message could contain a credential, an internal path, or other detail the thrower
+     * never reviewed for wire-safety. Set true only when the cause is known-safe to show (e.g. a
+     * validation library's own message intended for the caller).
+     */
+    readonly exposeCause?: boolean;
 }
 export declare class VehicleError extends Error {
     readonly code: string;
@@ -32,7 +49,10 @@ export declare class VehicleError extends Error {
     readonly recovery?: VehicleRecovery;
     readonly details?: JsonValue;
     readonly operationId?: string;
+    private readonly exposeCause;
     constructor(code: string, message: string, options: VehicleErrorOptions);
     toFailure(): VehicleFailure;
 }
+/** 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

@@ -6,6 +6,7 @@ export class VehicleError extends Error {
     recovery;
     details;
     operationId;
+    exposeCause;
     constructor(code, message, options) {
         super(message, options.cause === undefined ? undefined : { cause: options.cause });
         this.code = code;
@@ -16,8 +17,10 @@ export class VehicleError extends Error {
         this.recovery = options.recovery;
         this.details = options.details;
         this.operationId = options.operationId;
+        this.exposeCause = options.exposeCause ?? false;
     }
     toFailure() {
+        const causeMessage = this.exposeCause ? boundedCauseMessage(this.cause) : undefined;
         return {
             code: this.code,
             category: this.category,
@@ -27,9 +30,19 @@ export class VehicleError extends Error {
             ...(this.recovery === undefined ? {} : { recovery: this.recovery }),
             ...(this.details === undefined ? {} : { details: this.details }),
             ...(this.operationId === undefined ? {} : { operationId: this.operationId }),
+            ...(causeMessage === undefined ? {} : { causeMessage }),
         };
     }
 }
+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) {
+    if (cause instanceof Error && cause.message.length > 0)
+        return cause.message.slice(0, MAX_CAUSE_MESSAGE_LENGTH);
+    if (typeof cause === "string" && cause.length > 0)
+        return cause.slice(0, MAX_CAUSE_MESSAGE_LENGTH);
+    return undefined;
+}
 const MAX_VALIDATION_ISSUES = 10;
 const MAX_ISSUE_MESSAGE_LENGTH = 500;
 const MAX_ISSUE_PATH_LENGTH = 20;

package/dist/vehicle-scheduler.d.ts

@@ -0,0 +1,63 @@
+/**
+ * "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.
+ *
+ * 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.
+ */
+import type { JsonValue } from "./vehicle-contract.js";
+export type VehicleScheduleTrigger = {
+    readonly kind: "at";
+    readonly at: number;
+} | {
+    readonly kind: "every";
+    readonly intervalMs: number;
+};
+export type VehicleScheduleAction = {
+    readonly kind: "operation";
+    readonly name: string;
+    readonly version: number;
+    readonly input: JsonValue;
+    readonly permissions?: readonly string[];
+} | {
+    readonly kind: "event";
+    readonly name: string;
+    readonly version: number;
+    readonly payload: JsonValue;
+};
+export interface VehicleScheduledEntry {
+    readonly scheduleId: string;
+    readonly owner: string;
+    readonly trigger: VehicleScheduleTrigger;
+    readonly action: VehicleScheduleAction;
+    readonly createdAt: number;
+    /** For "at": consumed once it fires. For "every": advanced to the next tick after each fire. */
+    readonly nextFireAt: number;
+}
+/** Matches WatchRegistry's own historical default (Lector's MAX_WATCHES_PER_WORKSPACE). */
+export declare 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 declare class VehicleScheduleLimitExceeded extends Error {
+    readonly owner: string;
+    readonly max: number;
+    constructor(owner: string, max: number);
+}
+/** The first fire time for a freshly created schedule. */
+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;
+/**
+ * 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 declare function nextFireAtAfterRestore(trigger: VehicleScheduleTrigger, persistedNextFireAt: number, now: number): number;

package/dist/vehicle-scheduler.js

@@ -0,0 +1,33 @@
+/** 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";
+    }
+}
+/** The first fire time for a freshly created schedule. */
+export function initialFireAt(trigger, now) {
+    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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@danypops/vehicle-core",
-	"version": "0.9.0",
+	"version": "0.11.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

@@ -3,4 +3,5 @@ export * from "./vehicle-approvals.js";
 export * from "./vehicle-contract.js";
 export * from "./vehicle-errors.js";
 export * from "./vehicle-jobs.js";
+export * from "./vehicle-scheduler.js";
 export * from "./vehicle-watchers.js";

package/src/vehicle-errors.ts

@@ -45,6 +45,14 @@ export interface VehicleFailure {
 	readonly recovery?: VehicleRecovery;
 	readonly details?: JsonValue;
 	readonly operationId?: string;
+	/**
+	 * The underlying cause's own message, when this failure wraps an unexpected error (e.g. a
+	 * handler throwing something other than a VehicleError) -- bounded, never a full stack trace.
+	 * Without this, a caller sees only a generic template like "x handler failed" and has no way
+	 * to tell what actually went wrong or whether the underlying operation may have partially
+	 * applied.
+	 */
+	readonly causeMessage?: string;
 }
 
 export interface VehicleErrorOptions {
@@ -55,6 +63,15 @@ export interface VehicleErrorOptions {
 	readonly details?: JsonValue;
 	readonly operationId?: string;
 	readonly cause?: unknown;
+	/**
+	 * Secure by default (false): `cause` is always attached to the real in-process Error chain
+	 * (for server-side logging/observability), but its message crosses the wire via
+	 * toFailure().causeMessage only when the throw site explicitly opts in here -- an arbitrary
+	 * cause's message could contain a credential, an internal path, or other detail the thrower
+	 * never reviewed for wire-safety. Set true only when the cause is known-safe to show (e.g. a
+	 * validation library's own message intended for the caller).
+	 */
+	readonly exposeCause?: boolean;
 }
 
 export class VehicleError extends Error {
@@ -64,6 +81,7 @@ export class VehicleError extends Error {
 	readonly recovery?: VehicleRecovery;
 	readonly details?: JsonValue;
 	readonly operationId?: string;
+	private readonly exposeCause: boolean;
 
 	constructor(
 		readonly code: string,
@@ -78,9 +96,11 @@ export class VehicleError extends Error {
 		this.recovery = options.recovery;
 		this.details = options.details;
 		this.operationId = options.operationId;
+		this.exposeCause = options.exposeCause ?? false;
 	}
 
 	toFailure(): VehicleFailure {
+		const causeMessage = this.exposeCause ? boundedCauseMessage(this.cause) : undefined;
 		return {
 			code: this.code,
 			category: this.category,
@@ -90,10 +110,20 @@ export class VehicleError extends Error {
 			...(this.recovery === undefined ? {} : { recovery: this.recovery }),
 			...(this.details === undefined ? {} : { details: this.details }),
 			...(this.operationId === undefined ? {} : { operationId: this.operationId }),
+			...(causeMessage === undefined ? {} : { causeMessage }),
 		};
 	}
 }
 
+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: unknown): string | undefined {
+	if (cause instanceof Error && cause.message.length > 0) return cause.message.slice(0, MAX_CAUSE_MESSAGE_LENGTH);
+	if (typeof cause === "string" && cause.length > 0) return cause.slice(0, MAX_CAUSE_MESSAGE_LENGTH);
+	return undefined;
+}
+
 const MAX_VALIDATION_ISSUES = 10;
 const MAX_ISSUE_MESSAGE_LENGTH = 500;
 const MAX_ISSUE_PATH_LENGTH = 20;

package/src/vehicle-scheduler.ts

@@ -0,0 +1,73 @@
+/**
+ * "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.
+ *
+ * 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.
+ */
+import type { JsonValue } from "./vehicle-contract.js";
+
+export type VehicleScheduleTrigger = { readonly kind: "at"; readonly at: number } | { readonly kind: "every"; readonly intervalMs: number };
+
+export type VehicleScheduleAction =
+	| {
+			readonly kind: "operation";
+			readonly name: string;
+			readonly version: number;
+			readonly input: JsonValue;
+			readonly permissions?: readonly string[];
+	  }
+	| { readonly kind: "event"; readonly name: string; readonly version: number; readonly payload: JsonValue };
+
+export interface VehicleScheduledEntry {
+	readonly scheduleId: string;
+	readonly owner: string;
+	readonly trigger: VehicleScheduleTrigger;
+	readonly action: VehicleScheduleAction;
+	readonly createdAt: number;
+	/** For "at": consumed once it fires. For "every": advanced to the next tick after each fire. */
+	readonly nextFireAt: number;
+}
+
+/** 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 {
+	constructor(
+		readonly owner: string,
+		readonly max: number,
+	) {
+		super(`owner "${owner}" already has ${max} active schedules -- cancel one before adding another`);
+		this.name = "VehicleScheduleLimitExceeded";
+	}
+}
+
+/** The first fire time for a freshly created schedule. */
+export function initialFireAt(trigger: VehicleScheduleTrigger, now: number): number {
+	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: VehicleScheduleTrigger, now: number): number | undefined {
+	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: VehicleScheduleTrigger, persistedNextFireAt: number, now: number): number {
+	if (trigger.kind === "at") return persistedNextFireAt;
+	return persistedNextFireAt > now ? persistedNextFireAt : now + trigger.intervalMs;
+}