@danypops/vehicle-core 0.17.0 → 0.18.0

package/src/operations/operation.ts

@@ -0,0 +1,184 @@
+import type { VehicleJobWakeBudget } from "../jobs/wake-log.js";
+import type { VehicleSchemaCodec } from "../schemas/codec.js";
+import { cloneJson, type JsonSchema } from "../schemas/json.js";
+import type { VehicleOperationHandler } from "./context.js";
+import type { VehicleEffect } from "./effect.js";
+
+export type VehicleIdempotency =
+	| { readonly mode: "safe" }
+	| { readonly mode: "keyed"; readonly retentionMs: number }
+	| { readonly mode: "unsafe" };
+
+export interface VehicleLimits {
+	readonly defaultTimeoutMs: number;
+	readonly maxTimeoutMs: number;
+	readonly maxRequestBytes: number;
+	readonly maxResponseBytes: number;
+}
+
+/** One structured, documented failure mode a {@link VehicleOperationDescriptor} declares up front -- part of the operation's own serializable contract, not an ad hoc thrown Error a caller has to reverse-engineer from a message string. */
+export interface VehicleFailureDescriptor {
+	readonly code: string;
+	readonly description: string;
+}
+
+/** Declares an operation safe to run as a Vehicle Job (detached, polled/tailed/canceled by id). Absent means live-invoke only. */
+export interface VehicleBackgroundCapability {
+	readonly supported: true;
+	readonly defaultWakeBudget: VehicleJobWakeBudget;
+	readonly maxWakeBudget: VehicleJobWakeBudget;
+}
+
+/**
+ * The serializable half of a Vehicle operation -- name, version, schemas,
+ * ownership-implying permissions, effect classification, idempotency,
+ * streaming/long-running capability, request/response limits, and declared
+ * {@link VehicleFailureDescriptor} failure modes. Kept separate from the
+ * executable {@link VehicleOperationHandler} on purpose: a manifest, a Pi
+ * tool projection, or a client's own capability check can all inspect this
+ * shape without ever touching (or needing to trust) the implementation
+ * behind it.
+ */
+export interface VehicleOperationDescriptor {
+	readonly name: string;
+	readonly version: number;
+	readonly description: string;
+	readonly inputSchema: JsonSchema;
+	readonly outputSchema: JsonSchema;
+	readonly permissions: readonly string[];
+	readonly effect: VehicleEffect;
+	readonly idempotency: VehicleIdempotency;
+	readonly streaming: boolean;
+	readonly longRunning: boolean;
+	readonly limits: VehicleLimits;
+	readonly errors: readonly VehicleFailureDescriptor[];
+	readonly background?: VehicleBackgroundCapability;
+	/**
+	 * Owner-declared override for whether this specific operation is ever a candidate for
+	 * approval gating, independent of its `effect`. Undefined (the default) means "derive it
+	 * from `effect` against the registry's own requireApprovalForEffects set instead" --
+	 * VehicleRegistry.manifest()'s own resolution rule, unchanged for every existing
+	 * operation that never sets this.
+	 *
+	 * Exists because VehicleEffect's five values are coarse enough that two operations a
+	 * real owner classifies very differently (e.g. "restart an already-installed,
+	 * already-vetted service" vs. "sync a read-only catalog mirror") can land in the same
+	 * effect bucket (both external-write) -- no single requireApprovalForEffects set can
+	 * gate one without also gating the other. The owner who registers the operation knows
+	 * its real risk far better than a 5-value enum can; this lets them say so directly.
+	 */
+	readonly requiresApproval?: boolean;
+}
+
+export interface VehicleOperation<Input, Output> {
+	readonly descriptor: VehicleOperationDescriptor;
+	readonly input: VehicleSchemaCodec<Input>;
+	readonly output: VehicleSchemaCodec<Output>;
+}
+
+export interface DefineVehicleOperationOptions<Input, Output> {
+	readonly name: string;
+	readonly version: number;
+	readonly description: string;
+	readonly input: VehicleSchemaCodec<Input>;
+	readonly output: VehicleSchemaCodec<Output>;
+	readonly permissions?: readonly string[];
+	readonly effect: VehicleEffect;
+	readonly idempotency: VehicleIdempotency;
+	readonly streaming?: boolean;
+	readonly longRunning?: boolean;
+	readonly limits: VehicleLimits;
+	readonly errors?: readonly VehicleFailureDescriptor[];
+	readonly background?: VehicleBackgroundCapability;
+	/** See {@link VehicleOperationDescriptor.requiresApproval}. */
+	readonly requiresApproval?: boolean;
+}
+
+export interface VehicleOperationBinding<Input, Output> {
+	readonly operation: VehicleOperation<Input, Output>;
+	bind(): VehicleOperationHandler<Input, Output>;
+}
+
+export function defineVehicleOperation<Input, Output>(
+	options: DefineVehicleOperationOptions<Input, Output>,
+): VehicleOperation<Input, Output> {
+	validateOperationMetadata(options);
+	const descriptor: VehicleOperationDescriptor = 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 as const,
+						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<Input, Output>(
+	operation: VehicleOperation<Input, Output>,
+	bind: () => VehicleOperationHandler<Input, Output>,
+): VehicleOperationBinding<Input, Output> {
+	return Object.freeze({ operation, bind });
+}
+
+function validateOperationMetadata<Input, Output>(options: DefineVehicleOperationOptions<Input, Output>): void {
+	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],
+		] as const) {
+			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/src/{atomic-json.ts → persistence/atomic-json.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/src/persistence/index.ts

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

package/src/schedules/index.ts

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

package/src/{vehicle-scheduler.ts → schedules/schedule.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 } | { readonly kind: "every"; readonly intervalMs: number };
 

package/src/schemas/codec.ts

@@ -0,0 +1,30 @@
+import { cloneJson, 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 function defineVehicleSchema<T>(codec: VehicleSchemaCodec<T>): VehicleSchemaCodec<T> {
+	return Object.freeze({
+		jsonSchema: cloneJson(codec.jsonSchema),
+		safeParse: codec.safeParse,
+	});
+}

package/src/schemas/index.ts

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

package/src/schemas/json.ts

@@ -0,0 +1,17 @@
+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 function cloneJson<T extends JsonValue>(value: T): T {
+	const serialized = JSON.stringify(value);
+	if (serialized === undefined) throw new Error("Vehicle JSON metadata must be serializable");
+	return freezeJson(JSON.parse(serialized) as JsonValue) as T;
+}
+
+export function freezeJson(value: JsonValue): JsonValue {
+	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/src/schemas/loose-object.ts

@@ -0,0 +1,82 @@
+import { defineVehicleSchema, type VehicleSchemaCodec } from "./codec.js";
+import type { JsonValue } from "./json.js";
+
+export interface LooseObjectProperty {
+	readonly type: string;
+	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 `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>,
+	required: readonly string[] = [],
+): VehicleSchemaCodec<Record<string, unknown>> {
+	return defineVehicleSchema<Record<string, unknown>>({
+		// 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 as unknown as JsonValue, 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 as Record<string, unknown>;
+			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] as string)) {
+					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: VehicleSchemaCodec<unknown> = defineVehicleSchema<unknown>({
+	jsonSchema: { type: "object" },
+	safeParse: (value) => ({ success: true, value }),
+});

package/src/schemas/presentation.ts

@@ -0,0 +1,28 @@
+/** 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",
+] as const);
+
+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: string): boolean {
+	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" as const;
+export type VehicleSchemaPresentation = "omit" | "summarize";

package/src/watches/index.ts

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

package/src/{vehicle-watchers.ts → watches/registry.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