@danypops/vehicle-core 0.17.0 → 0.18.0

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

@@ -1,18 +1,16 @@
 /**
  * "Trigger something at a future time or on a recurring interval,"
  * independent of any specific job's own lifecycle -- a distinct shape from
- * Vehicle Jobs (submit-then-track a unit of work already running). Modeled
- * on ~/Workspace/alef's packages/core/foundry/src/scheduler.ts
- * (defer/repeat/cancel/list), generalized so the fired action is a
- * declarative Vehicle operation invocation or event emission -- never a
- * bespoke callback closure, so it can be persisted and re-armed after a
- * restart the way a closure never could.
+ * Vehicle Jobs (submit-then-track a unit of work already running). The
+ * fired action is a declarative Vehicle operation invocation or event
+ * emission -- never a bespoke callback closure, so it can be persisted and
+ * re-armed after a restart the way a closure never could.
  *
  * Pure pieces only: trigger/action shapes and the fire-time arithmetic.
  * Real timers, persistence, and registry wiring live in vehicle-server's
- * VehicleScheduler, the same core/server split vehicle-jobs.ts uses.
+ * VehicleScheduler, the same core/server split Vehicle Jobs uses.
  */
-import type { JsonValue } from "./vehicle-contract.js";
+import type { JsonValue } from "../schemas/json.js";
 export type VehicleScheduleTrigger = {
     readonly kind: "at";
     readonly at: number;

package/dist/schemas/codec.d.ts

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

package/dist/schemas/codec.js

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

package/dist/schemas/index.d.ts

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

package/dist/schemas/index.js

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

package/dist/schemas/json.d.ts

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

package/dist/schemas/json.js

@@ -0,0 +1,14 @@
+export function cloneJson(value) {
+    const serialized = JSON.stringify(value);
+    if (serialized === undefined)
+        throw new Error("Vehicle JSON metadata must be serializable");
+    return freezeJson(JSON.parse(serialized));
+}
+export function freezeJson(value) {
+    if (Array.isArray(value))
+        return Object.freeze(value.map(freezeJson));
+    if (value !== null && typeof value === "object") {
+        return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, child]) => [key, freezeJson(child)])));
+    }
+    return value;
+}

package/dist/schemas/loose-object.d.ts

@@ -0,0 +1,20 @@
+import { type VehicleSchemaCodec } from "./codec.js";
+export interface LooseObjectProperty {
+    readonly type: string;
+    readonly enum?: readonly string[];
+}
+/**
+ * A VehicleRegistry only ever calls a schema's own safeParse -- jsonSchema is
+ * descriptive metadata surfaced to a client/Pi projection, never itself
+ * enforced at runtime -- so a declared `type`/`enum`/`additionalProperties: false`
+ * has to be checked here for real, or it's a documentation gesture, not an
+ * honest contract (the exact drift this function's own jsonSchema metadata
+ * had before: it always advertised `additionalProperties: false` and a
+ * per-property `type`, while safeParse only ever checked `required` and
+ * `enum`). Every consumer projecting a plain-object input onto a
+ * VehicleOperation needs the same required/type/extra-key/enum checks; this
+ * is that check written once.
+ */
+export declare function defineLooseObjectSchema(properties: Record<string, LooseObjectProperty>, required?: readonly string[]): VehicleSchemaCodec<Record<string, unknown>>;
+/** Accepts any value unvalidated -- for an operation whose output shape isn't worth a dedicated schema (an internal/low-stakes result, or one already validated upstream by the domain logic it wraps). */
+export declare const passthroughVehicleSchema: VehicleSchemaCodec<unknown>;

package/dist/schemas/loose-object.js

@@ -0,0 +1,73 @@
+import { defineVehicleSchema } from "./codec.js";
+/** JSON Schema's own `type` keyword vocabulary -- checked for real below so a declared `type: "number"` (say) can't silently accept a string forever. `"integer"` additionally requires no fractional part, matching JSON Schema's own distinction from plain `"number"`. An unrecognized type name is treated as "anything goes" (matches passthroughVehicleSchema's own precedent for a shape not worth strictly enforcing) rather than rejecting every input outright for what would otherwise be a schema-authoring typo. */
+function matchesLooseObjectPropertyType(type, value) {
+    switch (type) {
+        case "string":
+            return typeof value === "string";
+        case "number":
+            return typeof value === "number" && Number.isFinite(value);
+        case "integer":
+            return typeof value === "number" && Number.isInteger(value);
+        case "boolean":
+            return typeof value === "boolean";
+        case "object":
+            return typeof value === "object" && value !== null && !Array.isArray(value);
+        case "array":
+            return Array.isArray(value);
+        case "null":
+            return value === null;
+        default:
+            return true;
+    }
+}
+/**
+ * A VehicleRegistry only ever calls a schema's own safeParse -- jsonSchema is
+ * descriptive metadata surfaced to a client/Pi projection, never itself
+ * enforced at runtime -- so a declared `type`/`enum`/`additionalProperties: false`
+ * has to be checked here for real, or it's a documentation gesture, not an
+ * honest contract (the exact drift this function's own jsonSchema metadata
+ * had before: it always advertised `additionalProperties: false` and a
+ * per-property `type`, while safeParse only ever checked `required` and
+ * `enum`). Every consumer projecting a plain-object input onto a
+ * VehicleOperation needs the same required/type/extra-key/enum checks; this
+ * is that check written once.
+ */
+export function defineLooseObjectSchema(properties, required = []) {
+    return defineVehicleSchema({
+        // LooseObjectProperty's named fields (type, enum) are all JSON-value-shaped
+        // at runtime, but TypeScript's structural check against the recursive
+        // JsonValue union doesn't see that through a plain interface -- the cast
+        // is a type-system limitation, not a runtime concern.
+        jsonSchema: { type: "object", properties: properties, required: [...required], additionalProperties: false },
+        safeParse(value) {
+            if (typeof value !== "object" || value === null || Array.isArray(value)) {
+                return { success: false, issues: [{ path: [], message: "input must be an object" }] };
+            }
+            const input = value;
+            for (const key of required) {
+                if (!(key in input))
+                    return { success: false, issues: [{ path: [key], message: `${key} is required` }] };
+            }
+            for (const key of Object.keys(input)) {
+                if (!(key in properties))
+                    return { success: false, issues: [{ path: [key], message: `${key} is not a recognized property` }] };
+            }
+            for (const [key, schema] of Object.entries(properties)) {
+                if (!(key in input))
+                    continue;
+                if (!matchesLooseObjectPropertyType(schema.type, input[key])) {
+                    return { success: false, issues: [{ path: [key], message: `${key} must be of type ${schema.type}` }] };
+                }
+                if (schema.enum && !schema.enum.includes(input[key])) {
+                    return { success: false, issues: [{ path: [key], message: `${key} must be one of ${schema.enum.join(", ")}` }] };
+                }
+            }
+            return { success: true, value: input };
+        },
+    });
+}
+/** Accepts any value unvalidated -- for an operation whose output shape isn't worth a dedicated schema (an internal/low-stakes result, or one already validated upstream by the domain logic it wraps). */
+export const passthroughVehicleSchema = defineVehicleSchema({
+    jsonSchema: { type: "object" },
+    safeParse: (value) => ({ success: true, value }),
+});

package/dist/schemas/presentation.d.ts

@@ -0,0 +1,11 @@
+/** Shared defense-in-depth vocabulary for credential-shaped fields at every Vehicle projection boundary. */
+export declare const VEHICLE_CREDENTIAL_FIELD_NAMES: readonly ["password", "token", "accessToken", "refreshToken", "apiKey", "secret", "authorization", "credential"];
+/** Case/separator-insensitive credential-name check used as a fallback when a schema annotation is missing. */
+export declare function isVehicleCredentialFieldName(name: string): boolean;
+/**
+ * JSON Schema property annotation consumed by human-facing Vehicle adapters.
+ * `omit` hides the field; `summarize` may show shape/size but never its value.
+ * Standard `writeOnly: true` and `format: "password"` always imply omission.
+ */
+export declare const VEHICLE_SCHEMA_PRESENTATION_EXTENSION: "x-vehicle-presentation";
+export type VehicleSchemaPresentation = "omit" | "summarize";

package/dist/schemas/presentation.js

@@ -0,0 +1,22 @@
+/** Shared defense-in-depth vocabulary for credential-shaped fields at every Vehicle projection boundary. */
+export const VEHICLE_CREDENTIAL_FIELD_NAMES = Object.freeze([
+    "password",
+    "token",
+    "accessToken",
+    "refreshToken",
+    "apiKey",
+    "secret",
+    "authorization",
+    "credential",
+]);
+const NORMALIZED_VEHICLE_CREDENTIAL_FIELD_NAMES = new Set(VEHICLE_CREDENTIAL_FIELD_NAMES.map((name) => name.replace(/[^a-z0-9]/gi, "").toLowerCase()));
+/** Case/separator-insensitive credential-name check used as a fallback when a schema annotation is missing. */
+export function isVehicleCredentialFieldName(name) {
+    return NORMALIZED_VEHICLE_CREDENTIAL_FIELD_NAMES.has(name.replace(/[^a-z0-9]/gi, "").toLowerCase());
+}
+/**
+ * JSON Schema property annotation consumed by human-facing Vehicle adapters.
+ * `omit` hides the field; `summarize` may show shape/size but never its value.
+ * Standard `writeOnly: true` and `format: "password"` always imply omission.
+ */
+export const VEHICLE_SCHEMA_PRESENTATION_EXTENSION = "x-vehicle-presentation";

package/dist/watches/index.d.ts

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

package/dist/watches/index.js

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

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

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

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

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

package/package.json

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

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

@@ -6,8 +6,11 @@
  * 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, VEHICLE_EFFECTS } from "./vehicle-contract.js";
+import { defineVehicleEvent } from "../events/event.js";
+import type { VehiclePrincipal } from "../operations/context.js";
+import type { VehicleEffect } from "../operations/effect.js";
+import { VEHICLE_EFFECTS } from "../operations/effect.js";
+import { defineVehicleSchema } from "../schemas/codec.js";
 
 /** A sha256 hex digest: exactly 64 lowercase hex characters -- matches hashApprovalInput's own (vehicle-server) output shape. */
 const SHA256_HEX_PATTERN = /^[0-9a-f]{64}$/;
@@ -19,9 +22,9 @@ function isVehicleEffect(value: unknown): value is VehicleEffect {
 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);
+	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. */
@@ -102,22 +105,22 @@ const requestedPayloadSchema = defineVehicleSchema<VehicleApprovalRequest>({
 		if (typeof value !== "object" || value === null) return { success: false, issues: [{ path: [], message: "input must be an object" }] };
 		const row = value as Record<string, unknown>;
 		if (
-			typeof row.requestId !== "string" ||
-			typeof row.operationName !== "string" ||
-			typeof row.operationVersion !== "number" ||
-			!Number.isInteger(row.operationVersion) ||
-			row.operationVersion < 1 ||
-			!isVehicleEffect(row.effect) ||
-			typeof row.requestedAt !== "number" ||
-			!Number.isFinite(row.requestedAt) ||
-			typeof row.expiresAt !== "number" ||
-			!Number.isFinite(row.expiresAt) ||
-			typeof row.inputHash !== "string" ||
-			!SHA256_HEX_PATTERN.test(row.inputHash)
+			typeof row["requestId"] !== "string" ||
+			typeof row["operationName"] !== "string" ||
+			typeof row["operationVersion"] !== "number" ||
+			!Number.isInteger(row["operationVersion"]) ||
+			row["operationVersion"] < 1 ||
+			!isVehicleEffect(row["effect"]) ||
+			typeof row["requestedAt"] !== "number" ||
+			!Number.isFinite(row["requestedAt"]) ||
+			typeof row["expiresAt"] !== "number" ||
+			!Number.isFinite(row["expiresAt"]) ||
+			typeof row["inputHash"] !== "string" ||
+			!SHA256_HEX_PATTERN.test(row["inputHash"])
 		) {
 			return { success: false, issues: [{ path: [], message: "invalid approval request payload" }] };
 		}
-		if (row.principal !== undefined && !isVehiclePrincipal(row.principal)) {
+		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 };
@@ -141,17 +144,17 @@ const resolvedPayloadSchema = defineVehicleSchema<VehicleApprovalOutcome>({
 		if (typeof value !== "object" || value === null) return { success: false, issues: [{ path: [], message: "input must be an object" }] };
 		const row = value as Record<string, unknown>;
 		if (
-			typeof row.requestId !== "string" ||
-			(row.decision !== "granted" && row.decision !== "denied") ||
-			typeof row.decidedAt !== "number" ||
-			!Number.isFinite(row.decidedAt)
+			typeof row["requestId"] !== "string" ||
+			(row["decision"] !== "granted" && row["decision"] !== "denied") ||
+			typeof row["decidedAt"] !== "number" ||
+			!Number.isFinite(row["decidedAt"])
 		) {
 			return { success: false, issues: [{ path: [], message: "invalid approval outcome payload" }] };
 		}
-		if (row.decidedBy !== undefined && typeof row.decidedBy !== "string") {
+		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") {
+		if (row["comment"] !== undefined && typeof row["comment"] !== "string") {
 			return { success: false, issues: [{ path: ["comment"], message: "comment must be a string" }] };
 		}
 		return { success: true, value: row as unknown as VehicleApprovalOutcome };

package/src/approvals/index.ts

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

package/src/client/client.ts

@@ -0,0 +1,31 @@
+import type { VehicleJobSnapshot, VehicleJobSubmitOptions, VehicleJobSubmitResult, VehicleJobTailResult } from "../jobs/wire.js";
+import type { VehicleManifest } from "../manifest/manifest.js";
+import type { VehicleInvocationOptions } from "../operations/context.js";
+
+export interface VehicleSubscription {
+	close(): void;
+}
+
+export interface VehicleClient {
+	manifest(): Promise<VehicleManifest>;
+	invoke<Output = unknown>(name: string, version: number, input: unknown, options?: VehicleInvocationOptions): Promise<Output>;
+	close(): Promise<void>;
+	/**
+	 * Vehicle Jobs -- submit a background-capable operation (one whose descriptor declares
+	 * `background`, see {@link VehicleBackgroundCapability}) and get its jobId back immediately,
+	 * without waiting for the operation itself to make any progress. Optional: a client that
+	 * never talks to a job-capable Vehicle (or a hand-rolled test double) simply omits these five
+	 * methods, exactly like this interface's own long-standing `subscribe()`-shaped extras --
+	 * present on both LocalVehicleClient and RemoteVehicleClient, absent elsewhere. Feature-detect
+	 * via the operation's own manifest `background` capability, not by probing for these methods.
+	 */
+	submitJob?(name: string, version: number, input: unknown, options?: VehicleJobSubmitOptions): Promise<VehicleJobSubmitResult>;
+	/** Never blocks -- current status, plus output/error once terminal. */
+	pollJob?(jobId: string): Promise<VehicleJobSnapshot>;
+	/** Progress entries strictly after `cursor` (0 for everything so far), plus the next cursor. Never blocks. */
+	tailJob?(jobId: string, cursor?: number): Promise<VehicleJobTailResult>;
+	/** Pushes new input to an already-running job's handler, if it opted in via context.steerInputs. */
+	steerJob?(jobId: string, input: unknown): Promise<void>;
+	/** Best-effort cancellation of a still-running job -- a no-op against an already-terminal one. */
+	cancelJob?(jobId: string): Promise<void>;
+}

package/src/client/index.ts

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

package/src/content/content.ts

@@ -0,0 +1,46 @@
+/**
+ * A block of narrative text meant to be read by the model, not parsed as
+ * data -- same field name and shape MCP's own CallToolResult.content and
+ * Pi's own ToolDefinition.execute() return already use, so a Vehicle
+ * operation adopting this needs no translation layer at either boundary.
+ * Only the "text" variant exists here; there's no Vehicle use case yet for
+ * MCP's image/audio/resource-link block kinds.
+ */
+export interface VehicleContentBlock {
+	readonly type: "text";
+	readonly text: string;
+}
+
+/**
+ * An operation's Output type can intersect this to carry its own
+ * model-facing narrative alongside its structured data, e.g.
+ * `type RunOutput = { runId: string; created: Task[] } & WithVehicleContent`.
+ * The operation itself builds `content` since it's the only code that
+ * actually knows how to describe what it computed -- never a per-consumer
+ * override bolted on wherever the operation happens to get registered.
+ */
+export interface WithVehicleContent {
+	readonly content?: readonly VehicleContentBlock[];
+}
+
+/**
+ * Reads an operation's own `content` blocks off its output when present and
+ * well-formed, so a generic Vehicle client can prefer them over dumping raw
+ * JSON at the model -- without knowing anything about the operation's own
+ * domain shape. Returns undefined for a malformed or absent `content` field;
+ * the caller falls back to its own default (formatted JSON) rather than
+ * risk forwarding partial/garbled blocks.
+ */
+export function extractVehicleContent(output: unknown): readonly VehicleContentBlock[] | undefined {
+	if (typeof output !== "object" || output === null || Array.isArray(output)) return undefined;
+	const content = (output as { readonly content?: unknown }).content;
+	if (!Array.isArray(content) || content.length === 0) return undefined;
+	const blocks: VehicleContentBlock[] = [];
+	for (const block of content) {
+		if (typeof block !== "object" || block === null) return undefined;
+		const { type, text } = block as { readonly type?: unknown; readonly text?: unknown };
+		if (type !== "text" || typeof text !== "string") return undefined;
+		blocks.push({ type: "text", text });
+	}
+	return blocks;
+}

package/src/content/index.ts

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

package/src/{vehicle-errors.ts → errors/error.ts}

@@ -1,4 +1,5 @@
-import type { JsonValue, VehicleSchemaIssue } from "./vehicle-contract.js";
+import type { VehicleSchemaIssue } from "../schemas/codec.js";
+import type { JsonValue } from "../schemas/json.js";
 
 const VEHICLE_ERROR_BRAND = Symbol.for("@danypops/vehicle-core/VehicleError");
 
@@ -55,10 +56,10 @@ export interface VehicleFailure {
 export interface VehicleErrorOptions {
 	readonly category: VehicleFailureCategory;
 	readonly retryable?: boolean;
-	readonly retryAfterMs?: number;
-	readonly recovery?: VehicleRecovery;
-	readonly details?: JsonValue;
-	readonly operationId?: string;
+	readonly retryAfterMs?: number | undefined;
+	readonly recovery?: VehicleRecovery | undefined;
+	readonly details?: JsonValue | undefined;
+	readonly operationId?: string | undefined;
 	readonly cause?: unknown;
 	/** Includes cause's message in toFailure().causeMessage. Default false -- an arbitrary cause could carry a credential or internal detail. */
 	readonly exposeCause?: boolean;
@@ -113,10 +114,10 @@ export function defineErrorMapping(
 export class VehicleError extends Error {
 	readonly category: VehicleFailureCategory;
 	readonly retryable: boolean;
-	readonly retryAfterMs?: number;
-	readonly recovery?: VehicleRecovery;
-	readonly details?: JsonValue;
-	readonly operationId?: string;
+	readonly retryAfterMs?: number | undefined;
+	readonly recovery?: VehicleRecovery | undefined;
+	readonly details?: JsonValue | undefined;
+	readonly operationId?: string | undefined;
 	private readonly exposeCause: boolean;
 
 	constructor(

package/src/errors/index.ts

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

package/src/events/event.ts

@@ -0,0 +1,72 @@
+import type { VehicleSchemaCodec } from "../schemas/codec.js";
+import { cloneJson, type JsonSchema } from "../schemas/json.js";
+
+/**
+ * A named, schema'd event type a provider declares as part of its
+ * manifest -- the typed alternative to a raw PushChannel.publish(topic,
+ * payload) call with a hand-invented topic string. No `available` flag the
+ * way an operation has one: an event type, once declared, is always
+ * emittable -- there's no credential-gated "this event is currently
+ * unavailable" concept the way a live external-service-backed operation
+ * can have.
+ */
+export interface VehicleEventDescriptor {
+	readonly name: string;
+	readonly version: number;
+	readonly description: string;
+	readonly payloadSchema: JsonSchema;
+	/** Same bounded-resource discipline as an operation's own maxRequestBytes/maxResponseBytes -- required, never silently defaulted. */
+	readonly maxPayloadBytes: number;
+}
+
+export interface VehicleEvent<Payload> {
+	readonly descriptor: VehicleEventDescriptor;
+	readonly payload: VehicleSchemaCodec<Payload>;
+}
+
+export interface DefineVehicleEventOptions<Payload> {
+	readonly name: string;
+	readonly version: number;
+	readonly description: string;
+	readonly payload: VehicleSchemaCodec<Payload>;
+	readonly maxPayloadBytes: number;
+}
+
+function validateEventMetadata<Payload>(options: DefineVehicleEventOptions<Payload>): void {
+	if (!options.name.trim()) throw new Error("Vehicle event name must not be empty");
+	if (!Number.isInteger(options.version) || options.version < 1) {
+		throw new Error("Vehicle event version must be a positive integer");
+	}
+	if (!options.description.trim()) throw new Error("Vehicle event description must not be empty");
+	if (!Number.isSafeInteger(options.maxPayloadBytes) || options.maxPayloadBytes < 1) {
+		throw new Error("Vehicle event maxPayloadBytes must be a positive integer");
+	}
+}
+
+export function defineVehicleEvent<Payload>(options: DefineVehicleEventOptions<Payload>): VehicleEvent<Payload> {
+	validateEventMetadata(options);
+	const descriptor: VehicleEventDescriptor = Object.freeze({
+		name: options.name,
+		version: options.version,
+		description: options.description,
+		payloadSchema: cloneJson(options.payload.jsonSchema),
+		maxPayloadBytes: options.maxPayloadBytes,
+	});
+	return Object.freeze({ descriptor, payload: options.payload });
+}
+
+export type VehicleManifestEvent = VehicleEventDescriptor;
+
+export type VehicleEventHandler<Payload> = (payload: Payload) => void;
+
+/**
+ * The wire topic name a bridge (bridgeVehicleEventsToPushChannel, in
+ * vehicle-server) publishes an event under, and a subscriber
+ * (RemoteVehicleClient.subscribe()) subscribes to -- one shared naming
+ * function in vehicle-core so both sides can never drift apart on the
+ * convention, the same failure mode this primitive exists to prevent
+ * providers from reinventing per-project.
+ */
+export function vehicleEventTopic(name: string, version: number): string {
+	return `vehicle-event:${name}@${version}`;
+}

package/src/events/index.ts

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

package/src/idempotency/index.ts

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

package/src/{vehicle-idempotency.ts → idempotency/receipt.ts}

@@ -5,7 +5,7 @@
  * 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";
+import type { VehicleFailure } from "../errors/error.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 =

package/src/index.ts

@@ -1,8 +1,26 @@
-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";
+/**
+ * Vehicle's runtime-neutral wire contract, organized by capability (see each
+ * subfolder's own index.ts) rather than one flat forest of vehicle-*.ts files:
+ * schemas (codecs, loose-object validation, credential presentation), content
+ * (model-facing narrative blocks), operations (descriptors, effect
+ * classification, invocation context), events, manifest, client (the port a
+ * caller programs against), approvals (the Approval Gate's wire shapes), jobs
+ * (Vehicle Jobs' pure pieces), schedules, watches, and persistence (atomic
+ * JSON -- a technical utility, not a Vehicle protocol capability, kept
+ * distinct for that reason). Every symbol below is re-exported unchanged
+ * from its historical flat-file home, so root-level `import { X } from
+ * "@danypops/vehicle-core"` usage is completely unaffected by this layout.
+ */
+export * from "./approvals/index.js";
+export * from "./client/index.js";
+export * from "./content/index.js";
+export * from "./errors/index.js";
+export * from "./events/index.js";
+export * from "./idempotency/index.js";
+export * from "./jobs/index.js";
+export * from "./manifest/index.js";
+export * from "./operations/index.js";
+export * from "./persistence/index.js";
+export * from "./schedules/index.js";
+export * from "./schemas/index.js";
+export * from "./watches/index.js";