@danypops/vehicle-core 0.13.0 → 0.14.0

package/dist/vehicle-approvals.d.ts

@@ -41,6 +41,8 @@ export interface VehicleApprovalOutcome {
     readonly decision: VehicleApprovalDecision;
     readonly decidedAt: number;
     readonly decidedBy?: string;
+    /** Optional human rationale captured by a rich HITL presenter. */
+    readonly comment?: string;
 }
 /**
  * The real authority behind an approvalCapability -- replaces today's

package/dist/vehicle-approvals.js

@@ -53,6 +53,7 @@ const resolvedPayloadSchema = defineVehicleSchema({
             decision: { type: "string", enum: ["granted", "denied"] },
             decidedAt: { type: "number" },
             decidedBy: { type: "string" },
+            comment: { type: "string" },
         },
         required: ["requestId", "decision", "decidedAt"],
         additionalProperties: true,

package/dist/vehicle-contract.d.ts

@@ -26,6 +26,14 @@ export type VehicleSchemaResult<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>;
@@ -93,6 +101,7 @@ export interface VehicleLimits {
     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;
@@ -103,6 +112,16 @@ export interface VehicleBackgroundCapability {
     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;
@@ -117,6 +136,21 @@ export interface VehicleOperationDescriptor {
     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;
@@ -137,6 +171,8 @@ export interface DefineVehicleOperationOptions<Input, Output> {
     readonly limits: VehicleLimits;
     readonly errors?: readonly VehicleFailureDescriptor[];
     readonly background?: VehicleBackgroundCapability;
+    /** See {@link VehicleOperationDescriptor.requiresApproval}. */
+    readonly requiresApproval?: boolean;
 }
 export interface VehiclePrincipal {
     readonly id: string;
@@ -192,6 +228,24 @@ export interface VehicleManifestIdentity {
 export interface VehicleManifestOperation extends VehicleOperationDescriptor {
     readonly available: boolean;
     readonly unavailableReason?: string;
+    /**
+     * The registry's own, live, fully-resolved answer to "does invoking this operation right
+     * now require approval" -- accounts for the registry's current approval policy being
+     * enabled/disabled, this operation's own `requiresApproval` override when set, and the
+     * effect-derived default otherwise. A real VehicleRegistry.manifest() always sets this
+     * (false when the registry never called configureApprovals() at all) -- unlike
+     * `requiresApproval` (the static, author-declared override on the descriptor itself),
+     * this always reflects the current instant, so a client re-fetching the manifest after a
+     * live policy change (VehicleRegistry.updateApprovalPolicy) sees the new answer with no
+     * separate sync mechanism needed.
+     *
+     * Optional purely for backward compatibility with every hand-authored VehicleManifest
+     * test fixture across the ecosystem that predates this field (the same reason
+     * VehicleManifest.events is optional) -- a consumer reading it should treat undefined the
+     * same as a caller of classifyVehicleOperationSafety does: fall back to the effect-level
+     * default, never assume false.
+     */
+    readonly approvalRequired?: boolean;
 }
 /**
  * A named, schema'd event type a provider declares as part of its

package/dist/vehicle-contract.js

@@ -140,6 +140,7 @@ export function defineVehicleOperation(options) {
         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({

package/package.json

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

@@ -48,6 +48,8 @@ export interface VehicleApprovalOutcome {
 	readonly decision: VehicleApprovalDecision;
 	readonly decidedAt: number;
 	readonly decidedBy?: string;
+	/** Optional human rationale captured by a rich HITL presenter. */
+	readonly comment?: string;
 }
 
 /**
@@ -106,6 +108,7 @@ const resolvedPayloadSchema = defineVehicleSchema<VehicleApprovalOutcome>({
 			decision: { type: "string", enum: ["granted", "denied"] },
 			decidedAt: { type: "number" },
 			decidedBy: { type: "string" },
+			comment: { type: "string" },
 		},
 		required: ["requestId", "decision", "decidedAt"],
 		additionalProperties: true,

package/src/vehicle-contract.ts

@@ -42,6 +42,14 @@ 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>;
@@ -163,6 +171,7 @@ export interface VehicleLimits {
 	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;
@@ -175,6 +184,16 @@ export interface VehicleBackgroundCapability {
 	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;
@@ -189,6 +208,21 @@ export interface VehicleOperationDescriptor {
 	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> {
@@ -211,6 +245,8 @@ export interface DefineVehicleOperationOptions<Input, Output> {
 	readonly limits: VehicleLimits;
 	readonly errors?: readonly VehicleFailureDescriptor[];
 	readonly background?: VehicleBackgroundCapability;
+	/** See {@link VehicleOperationDescriptor.requiresApproval}. */
+	readonly requiresApproval?: boolean;
 }
 
 export interface VehiclePrincipal {
@@ -273,6 +309,24 @@ export interface VehicleManifestIdentity {
 export interface VehicleManifestOperation extends VehicleOperationDescriptor {
 	readonly available: boolean;
 	readonly unavailableReason?: string;
+	/**
+	 * The registry's own, live, fully-resolved answer to "does invoking this operation right
+	 * now require approval" -- accounts for the registry's current approval policy being
+	 * enabled/disabled, this operation's own `requiresApproval` override when set, and the
+	 * effect-derived default otherwise. A real VehicleRegistry.manifest() always sets this
+	 * (false when the registry never called configureApprovals() at all) -- unlike
+	 * `requiresApproval` (the static, author-declared override on the descriptor itself),
+	 * this always reflects the current instant, so a client re-fetching the manifest after a
+	 * live policy change (VehicleRegistry.updateApprovalPolicy) sees the new answer with no
+	 * separate sync mechanism needed.
+	 *
+	 * Optional purely for backward compatibility with every hand-authored VehicleManifest
+	 * test fixture across the ecosystem that predates this field (the same reason
+	 * VehicleManifest.events is optional) -- a consumer reading it should treat undefined the
+	 * same as a caller of classifyVehicleOperationSafety does: fall back to the effect-level
+	 * default, never assume false.
+	 */
+	readonly approvalRequired?: boolean;
 }
 
 /**
@@ -384,6 +438,7 @@ export function defineVehicleOperation<Input, Output>(
 		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({