@danypops/vehicle-core 0.8.0 → 0.10.0

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export * from "./atomic-json.js";
+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

@@ -1,5 +1,7 @@
 export * from "./atomic-json.js";
+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-approvals.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Wire-level shapes for the Approval Gate: a pending human/authority decision
+ * that stands between a gated-effect invoke() and its handler actually
+ * running. Kept in vehicle-core (runtime-neutral, zero dependencies) --
+ * the actual signing/verification authority (HmacApprovalAuthority) needs
+ * 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";
+/** Set once at registry-configuration time (VehicleRegistry.configureApprovals()); never on a per-invoke basis. */
+export declare const DEFAULT_APPROVAL_EFFECTS: readonly VehicleEffect[];
+/** How long a request stays resolvable before it lapses and must be re-requested. */
+export declare const DEFAULT_APPROVAL_TIMEOUT_MS: number;
+/** Emitted (as a Vehicle Event) the moment a gated-effect invoke() has no valid capability -- durable-first, before any interactive prompt is attempted. */
+export interface VehicleApprovalRequest {
+    readonly requestId: string;
+    readonly operationName: string;
+    readonly operationVersion: number;
+    readonly effect: VehicleEffect;
+    readonly principal?: VehiclePrincipal;
+    readonly requestedAt: number;
+    readonly expiresAt: number;
+    /** sha256 hex of the exact input the gated invoke() attempted -- a minted capability is scoped to this input, not just the operation. */
+    readonly inputHash: string;
+}
+export type VehicleApprovalDecision = "granted" | "denied";
+/** Emitted once vehicle.approval.resolve settles a request, whichever way. */
+export interface VehicleApprovalOutcome {
+    readonly requestId: string;
+    readonly decision: VehicleApprovalDecision;
+    readonly decidedAt: number;
+    readonly decidedBy?: string;
+}
+/**
+ * The real authority behind an approvalCapability -- replaces today's
+ * "any non-empty string satisfies it" rubber stamp. mint() is called only
+ * from inside vehicle.approval.resolve once a decision is actually made;
+ * verify() is called from invoke() itself against whatever capability the
+ * caller presents. A capability is scoped to the exact operation+input it
+ * was minted for and expires with its originating request -- presenting a
+ * capability minted for a different operation, a different input, or one
+ * already consumed (single-use) must fail verify().
+ */
+export interface VehicleApprovalAuthority {
+    mint(request: Pick<VehicleApprovalRequest, "requestId" | "operationName" | "operationVersion" | "expiresAt" | "inputHash">): string;
+    verify(capability: string, operationName: string, operationVersion: number, inputHash: string): boolean;
+}
+/** Built into every VehicleRegistry once configureApprovals() is called -- never registered unconditionally, so a Vehicle that never opts in has zero manifest/shape change. */
+export declare const vehicleApprovalRequestedEvent: import("./vehicle-contract.js").VehicleEvent<VehicleApprovalRequest>;
+export declare const vehicleApprovalResolvedEvent: import("./vehicle-contract.js").VehicleEvent<VehicleApprovalOutcome>;

package/dist/vehicle-approvals.js

@@ -0,0 +1,75 @@
+import { defineVehicleEvent, defineVehicleSchema } from "./vehicle-contract.js";
+/** Set once at registry-configuration time (VehicleRegistry.configureApprovals()); never on a per-invoke basis. */
+export const DEFAULT_APPROVAL_EFFECTS = ["destructive", "open-world"];
+/** How long a request stays resolvable before it lapses and must be re-requested. */
+export const DEFAULT_APPROVAL_TIMEOUT_MS = 5 * 60_000;
+const requestedPayloadSchema = defineVehicleSchema({
+    jsonSchema: {
+        type: "object",
+        properties: {
+            requestId: { type: "string" },
+            operationName: { type: "string" },
+            operationVersion: { type: "number" },
+            effect: { type: "string" },
+            requestedAt: { type: "number" },
+            expiresAt: { type: "number" },
+            inputHash: { type: "string" },
+        },
+        required: ["requestId", "operationName", "operationVersion", "effect", "requestedAt", "expiresAt", "inputHash"],
+        additionalProperties: true,
+    },
+    safeParse(value) {
+        if (typeof value !== "object" || value === null)
+            return { success: false, issues: [{ path: [], message: "input must be an object" }] };
+        const row = value;
+        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") {
+            return { success: false, issues: [{ path: [], message: "invalid approval request payload" }] };
+        }
+        return { success: true, value: row };
+    },
+});
+const resolvedPayloadSchema = defineVehicleSchema({
+    jsonSchema: {
+        type: "object",
+        properties: {
+            requestId: { type: "string" },
+            decision: { type: "string", enum: ["granted", "denied"] },
+            decidedAt: { type: "number" },
+            decidedBy: { type: "string" },
+        },
+        required: ["requestId", "decision", "decidedAt"],
+        additionalProperties: true,
+    },
+    safeParse(value) {
+        if (typeof value !== "object" || value === null)
+            return { success: false, issues: [{ path: [], message: "input must be an object" }] };
+        const row = value;
+        if (typeof row.requestId !== "string" ||
+            (row.decision !== "granted" && row.decision !== "denied") ||
+            typeof row.decidedAt !== "number") {
+            return { success: false, issues: [{ path: [], message: "invalid approval outcome payload" }] };
+        }
+        return { success: true, value: row };
+    },
+});
+/** Built into every VehicleRegistry once configureApprovals() is called -- never registered unconditionally, so a Vehicle that never opts in has zero manifest/shape change. */
+export const vehicleApprovalRequestedEvent = defineVehicleEvent({
+    name: "vehicle.approval.requested",
+    version: 1,
+    description: "A gated-effect operation was invoked without a valid approval capability.",
+    payload: requestedPayloadSchema,
+    maxPayloadBytes: 16_384,
+});
+export const vehicleApprovalResolvedEvent = defineVehicleEvent({
+    name: "vehicle.approval.resolved",
+    version: 1,
+    description: "A pending approval request was granted or denied.",
+    payload: resolvedPayloadSchema,
+    maxPayloadBytes: 4_096,
+});

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.8.0",
+	"version": "0.10.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

@@ -1,5 +1,7 @@
 export * from "./atomic-json.js";
+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-approvals.ts

@@ -0,0 +1,130 @@
+/**
+ * Wire-level shapes for the Approval Gate: a pending human/authority decision
+ * that stands between a gated-effect invoke() and its handler actually
+ * running. Kept in vehicle-core (runtime-neutral, zero dependencies) --
+ * the actual signing/verification authority (HmacApprovalAuthority) needs
+ * 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";
+
+/** Set once at registry-configuration time (VehicleRegistry.configureApprovals()); never on a per-invoke basis. */
+export const DEFAULT_APPROVAL_EFFECTS: readonly VehicleEffect[] = ["destructive", "open-world"];
+
+/** How long a request stays resolvable before it lapses and must be re-requested. */
+export const DEFAULT_APPROVAL_TIMEOUT_MS = 5 * 60_000;
+
+/** Emitted (as a Vehicle Event) the moment a gated-effect invoke() has no valid capability -- durable-first, before any interactive prompt is attempted. */
+export interface VehicleApprovalRequest {
+	readonly requestId: string;
+	readonly operationName: string;
+	readonly operationVersion: number;
+	readonly effect: VehicleEffect;
+	readonly principal?: VehiclePrincipal;
+	readonly requestedAt: number;
+	readonly expiresAt: number;
+	/** sha256 hex of the exact input the gated invoke() attempted -- a minted capability is scoped to this input, not just the operation. */
+	readonly inputHash: string;
+}
+
+export type VehicleApprovalDecision = "granted" | "denied";
+
+/** Emitted once vehicle.approval.resolve settles a request, whichever way. */
+export interface VehicleApprovalOutcome {
+	readonly requestId: string;
+	readonly decision: VehicleApprovalDecision;
+	readonly decidedAt: number;
+	readonly decidedBy?: string;
+}
+
+/**
+ * The real authority behind an approvalCapability -- replaces today's
+ * "any non-empty string satisfies it" rubber stamp. mint() is called only
+ * from inside vehicle.approval.resolve once a decision is actually made;
+ * verify() is called from invoke() itself against whatever capability the
+ * caller presents. A capability is scoped to the exact operation+input it
+ * was minted for and expires with its originating request -- presenting a
+ * capability minted for a different operation, a different input, or one
+ * already consumed (single-use) must fail verify().
+ */
+export interface VehicleApprovalAuthority {
+	mint(request: Pick<VehicleApprovalRequest, "requestId" | "operationName" | "operationVersion" | "expiresAt" | "inputHash">): string;
+	verify(capability: string, operationName: string, operationVersion: number, inputHash: string): boolean;
+}
+
+const requestedPayloadSchema = defineVehicleSchema<VehicleApprovalRequest>({
+	jsonSchema: {
+		type: "object",
+		properties: {
+			requestId: { type: "string" },
+			operationName: { type: "string" },
+			operationVersion: { type: "number" },
+			effect: { type: "string" },
+			requestedAt: { type: "number" },
+			expiresAt: { type: "number" },
+			inputHash: { type: "string" },
+		},
+		required: ["requestId", "operationName", "operationVersion", "effect", "requestedAt", "expiresAt", "inputHash"],
+		additionalProperties: true,
+	},
+	safeParse(value) {
+		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"
+		) {
+			return { success: false, issues: [{ path: [], message: "invalid approval request payload" }] };
+		}
+		return { success: true, value: row as unknown as VehicleApprovalRequest };
+	},
+});
+
+const resolvedPayloadSchema = defineVehicleSchema<VehicleApprovalOutcome>({
+	jsonSchema: {
+		type: "object",
+		properties: {
+			requestId: { type: "string" },
+			decision: { type: "string", enum: ["granted", "denied"] },
+			decidedAt: { type: "number" },
+			decidedBy: { type: "string" },
+		},
+		required: ["requestId", "decision", "decidedAt"],
+		additionalProperties: true,
+	},
+	safeParse(value) {
+		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"
+		) {
+			return { success: false, issues: [{ path: [], message: "invalid approval outcome payload" }] };
+		}
+		return { success: true, value: row as unknown as VehicleApprovalOutcome };
+	},
+});
+
+/** Built into every VehicleRegistry once configureApprovals() is called -- never registered unconditionally, so a Vehicle that never opts in has zero manifest/shape change. */
+export const vehicleApprovalRequestedEvent = defineVehicleEvent<VehicleApprovalRequest>({
+	name: "vehicle.approval.requested",
+	version: 1,
+	description: "A gated-effect operation was invoked without a valid approval capability.",
+	payload: requestedPayloadSchema,
+	maxPayloadBytes: 16_384,
+});
+
+export const vehicleApprovalResolvedEvent = defineVehicleEvent<VehicleApprovalOutcome>({
+	name: "vehicle.approval.resolved",
+	version: 1,
+	description: "A pending approval request was granted or denied.",
+	payload: resolvedPayloadSchema,
+	maxPayloadBytes: 4_096,
+});

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;
+}