@danypops/vehicle-core 0.13.1 → 0.15.0

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,14 +171,31 @@ 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;
     readonly claims?: Readonly<Record<string, JsonValue>>;
 }
+/**
+ * callerSessionId/callerProjectRoot identify the real host session (e.g. one Pi TUI process) that
+ * originated this call, and its working directory at call time -- a generic ownership/attribution
+ * hook any operation handler can read (e.g. scoping a background subscription to the session or
+ * project that created it), distinct from both:
+ *  - correlationId: a caller-CHOSEN id deliberately meant to span several separate invoke() calls
+ *    (a batch/business-transaction id), not an automatically-derived caller identity.
+ *  - principal: broader identity/claims used for permission and approval decisions, usually a
+ *    fixed per-extension value (e.g. {id: "pi-pipes"}), not a distinguishing per-session id.
+ * A Pi projection layer (see vehicle-client-pi's invokeVehicleOperation) auto-derives both from
+ * context.sessionManager.getSessionId()/context.cwd on every call, the same way it already
+ * auto-derives correlationId -- a handler that never reads them pays nothing extra.
+ */
 export interface VehicleInvocationOptions {
     readonly operationId?: string;
     readonly correlationId?: string;
+    readonly callerSessionId?: string;
+    readonly callerProjectRoot?: string;
     readonly signal?: AbortSignal;
     readonly deadline?: number;
     readonly permissions?: readonly string[];
@@ -158,6 +209,10 @@ export interface VehicleOperationContext<Input> {
     readonly input: Input;
     readonly operationId: string;
     readonly correlationId?: string;
+    /** See VehicleInvocationOptions's own doc comment. */
+    readonly callerSessionId?: string;
+    /** See VehicleInvocationOptions's own doc comment. */
+    readonly callerProjectRoot?: string;
     readonly signal: AbortSignal;
     readonly deadline: number;
     readonly permissions: readonly string[];
@@ -192,6 +247,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.1",
+	"version": "0.15.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-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 {
@@ -218,9 +254,24 @@ export interface VehiclePrincipal {
 	readonly claims?: Readonly<Record<string, JsonValue>>;
 }
 
+/**
+ * callerSessionId/callerProjectRoot identify the real host session (e.g. one Pi TUI process) that
+ * originated this call, and its working directory at call time -- a generic ownership/attribution
+ * hook any operation handler can read (e.g. scoping a background subscription to the session or
+ * project that created it), distinct from both:
+ *  - correlationId: a caller-CHOSEN id deliberately meant to span several separate invoke() calls
+ *    (a batch/business-transaction id), not an automatically-derived caller identity.
+ *  - principal: broader identity/claims used for permission and approval decisions, usually a
+ *    fixed per-extension value (e.g. {id: "pi-pipes"}), not a distinguishing per-session id.
+ * A Pi projection layer (see vehicle-client-pi's invokeVehicleOperation) auto-derives both from
+ * context.sessionManager.getSessionId()/context.cwd on every call, the same way it already
+ * auto-derives correlationId -- a handler that never reads them pays nothing extra.
+ */
 export interface VehicleInvocationOptions {
 	readonly operationId?: string;
 	readonly correlationId?: string;
+	readonly callerSessionId?: string;
+	readonly callerProjectRoot?: string;
 	readonly signal?: AbortSignal;
 	readonly deadline?: number;
 	readonly permissions?: readonly string[];
@@ -235,6 +286,10 @@ export interface VehicleOperationContext<Input> {
 	readonly input: Input;
 	readonly operationId: string;
 	readonly correlationId?: string;
+	/** See VehicleInvocationOptions's own doc comment. */
+	readonly callerSessionId?: string;
+	/** See VehicleInvocationOptions's own doc comment. */
+	readonly callerProjectRoot?: string;
 	readonly signal: AbortSignal;
 	readonly deadline: number;
 	readonly permissions: readonly string[];
@@ -273,6 +328,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 +457,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({