@danypops/papyrus 0.46.1 → 0.47.0

package/README.md

@@ -46,6 +46,8 @@ Task project names are explicit registrations, never ambient-directory guesses.
 
 `tasks.create` accepts an optional `idempotency_key`. Replays with the same caller, canonical project root, key, and payload return the original response without another mutation; conflicting payload reuse is rejected. Keys are retained for seven days, isolated across callers and projects, and then expire. Retry only when reusing the exact key and payload; an unkeyed create remains unsafe to replay after an ambiguous transport failure.
 
+Task lifecycle mutations (`start`, `submit`, `reject`, `retry`, `cancel`, `reopen`, `complete`, `pause`, and `unpause`) are destination-state idempotent: repeating an already-achieved transition is a successful `changed: false` no-op and creates no duplicate history. Supply an `idempotency_key` for every mutation whose response could be lost. After an unknown outcome, call `tasks.show` and `tasks.mutation_status` with the original key, then replay only that exact operation/key if needed—never invent a new key from stale state. Completed receipts are retained for seven days; concurrent duplicate completion calls share one gate run. A genuinely incompatible transition returns typed `invalid-transition` details with current/intended status, allowed actions, and recovery guidance.
+
 Task lease responses are name-first: `tasks.claim`, `tasks.heartbeat_lease`, and `tasks.lease` return the reusable artifact alias as `taskName` plus `taskTitle`, not the backend UUID. Use `taskName` for later Task operations; retain the lease token for heartbeat or release.
 
 ### Context Mesh persistence model

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.46.1",
+  "version": "0.47.0",
   "description": "Daemon-backed graph artifacts, evidence-bearing tasks, rules, skills, and native TUI workflows for Pi",
   "type": "module",
   "keywords": ["pi-package"],

package/src/cli/task-command.ts

@@ -102,10 +102,16 @@ const focusedCommand = buildCommand({
 
 function buildPauseUnpauseCommand(action: "pause" | "unpause") {
 	return buildCommand({
-		func: async function (this: TaskContext, flags: { sessionId?: string; sessionSecret?: string }) {
+		func: async function (this: TaskContext, flags: { sessionId?: string; sessionSecret?: string; idempotencyKey?: string }) {
 			const focus = await this.client.call<Record<string, unknown>, { artifact: CliArtifact; status: string }>(
 				`tasks.${action}` as OperationName,
-				{ actor: "user", source: "cli", session_id: flags.sessionId, session_secret: flags.sessionSecret },
+				{
+					actor: "user",
+					source: "cli",
+					session_id: flags.sessionId,
+					session_secret: flags.sessionSecret,
+					...(flags.idempotencyKey ? { idempotency_key: flags.idempotencyKey } : {}),
+				},
 			);
 			render.call(this, focus, `Focused (${focus.status}): ${artifactLabel(focus.artifact)}`);
 		},
@@ -119,6 +125,13 @@ function buildPauseUnpauseCommand(action: "pause" | "unpause") {
 					placeholder: "secret",
 					optional: true,
 				},
+				idempotencyKey: {
+					brief: "Retry key for this exact mutation",
+					kind: "parsed",
+					parse: String,
+					placeholder: "key",
+					optional: true,
+				},
 			},
 		},
 		docs: { brief: `${action === "pause" ? "Pause" : "Resume"} the active Task Focus` },
@@ -307,6 +320,21 @@ const eventFeedCommand = buildCommand({
 	docs: { brief: "Feed of raw Task lifecycle events across every task" },
 });
 
+const mutationStatusCommand = buildCommand({
+	func: async function (this: TaskContext, _flags: Record<string, never>, idempotencyKey: string) {
+		const receipt = await this.client.call<Record<string, unknown>, { receiptId: string; operation: string; state: string }>(
+			"tasks.mutation_status",
+			{ idempotency_key: idempotencyKey },
+		);
+		render.call(this, receipt, `${receipt.operation}: ${receipt.state} (${receipt.receiptId})`);
+	},
+	parameters: {
+		flags: {},
+		positional: { kind: "tuple", parameters: [{ brief: "Original idempotency key", parse: String, placeholder: "key" }] },
+	},
+	docs: { brief: "Resolve an unknown Task lifecycle mutation outcome" },
+});
+
 // -- CRUD -----------------------------------------------------------------------------------
 
 const createCommand = buildCommand({
@@ -788,12 +816,13 @@ const planCommand = buildCommand({
 });
 
 const completeCommand = buildCommand({
-	func: async function (this: TaskContext, flags: { sessionId?: string }, id: string) {
+	func: async function (this: TaskContext, flags: { sessionId?: string; idempotencyKey?: string }, id: string) {
 		const completion = await this.client.call<Record<string, unknown>, CliCompletion>("tasks.complete", {
 			id,
 			actor: "user",
 			source: "cli",
 			session_id: flags.sessionId,
+			...(flags.idempotencyKey ? { idempotency_key: flags.idempotencyKey } : {}),
 		});
 		const lines = [`${completion.completed ? "Completed" : "Rejected"}: ${artifactLabel(completion.artifact)}`];
 		if (completion.focused) lines.push(`Active: ${artifactLabel(completion.focused)}`);
@@ -806,24 +835,31 @@ const completeCommand = buildCommand({
 		render.call(this, completion, lines.join("\n"));
 	},
 	parameters: {
-		flags: { sessionId: { brief: "Scope to one agent session", kind: "parsed", parse: String, placeholder: "id", optional: true } },
+		flags: {
+			sessionId: { brief: "Scope to one agent session", kind: "parsed", parse: String, placeholder: "id", optional: true },
+			idempotencyKey: { brief: "Retry key for this exact mutation", kind: "parsed", parse: String, placeholder: "key", optional: true },
+		},
 		positional: { kind: "tuple", parameters: [{ brief: "Task id", parse: String, placeholder: "id" }] },
 	},
 	docs: { brief: "Run gates and checklist review, then complete" },
 });
 
 const startCommand = buildCommand({
-	func: async function (this: TaskContext, flags: { sessionId?: string }, id: string) {
+	func: async function (this: TaskContext, flags: { sessionId?: string; idempotencyKey?: string }, id: string) {
 		const artifact = await this.client.call<Record<string, unknown>, CliArtifact>("tasks.start", {
 			id,
 			actor: "user",
 			source: "cli",
 			session_id: flags.sessionId,
+			...(flags.idempotencyKey ? { idempotency_key: flags.idempotencyKey } : {}),
 		});
 		render.call(this, artifact, `Started: ${artifactLabel(artifact)}`);
 	},
 	parameters: {
-		flags: { sessionId: { brief: "Scope to one agent session", kind: "parsed", parse: String, placeholder: "id", optional: true } },
+		flags: {
+			sessionId: { brief: "Scope to one agent session", kind: "parsed", parse: String, placeholder: "id", optional: true },
+			idempotencyKey: { brief: "Retry key for this exact mutation", kind: "parsed", parse: String, placeholder: "key", optional: true },
+		},
 		positional: { kind: "tuple", parameters: [{ brief: "Task id", parse: String, placeholder: "id" }] },
 	},
 	docs: { brief: "Lifecycle transition: todo -> in-progress" },
@@ -831,17 +867,21 @@ const startCommand = buildCommand({
 
 function buildSimpleTransitionCommand(action: "submit" | "reject" | "retry" | "cancel" | "reopen", brief: string) {
 	return buildCommand({
-		func: async function (this: TaskContext, flags: { sessionId?: string }, id: string) {
+		func: async function (this: TaskContext, flags: { sessionId?: string; idempotencyKey?: string }, id: string) {
 			const artifact = await this.client.call<Record<string, unknown>, CliArtifact>(`tasks.${action}` as OperationName, {
 				id,
 				actor: "user",
 				source: "cli",
 				session_id: flags.sessionId,
+				...(flags.idempotencyKey ? { idempotency_key: flags.idempotencyKey } : {}),
 			});
 			render.call(this, artifact, `${action[0]!.toUpperCase()}${action.slice(1)}: ${artifactLabel(artifact)}`);
 		},
 		parameters: {
-			flags: { sessionId: { brief: "Scope to one agent session", kind: "parsed", parse: String, placeholder: "id", optional: true } },
+			flags: {
+				sessionId: { brief: "Scope to one agent session", kind: "parsed", parse: String, placeholder: "id", optional: true },
+				idempotencyKey: { brief: "Retry key for this exact mutation", kind: "parsed", parse: String, placeholder: "key", optional: true },
+			},
 			positional: { kind: "tuple", parameters: [{ brief: "Task id", parse: String, placeholder: "id" }] },
 		},
 		docs: { brief },
@@ -920,6 +960,7 @@ const app = buildApplication(
 			lease: leaseCommand,
 			"reap-stale-leases": reapStaleLeasesCommand,
 			"event-feed": eventFeedCommand,
+			"mutation-status": mutationStatusCommand,
 			create: createCommand,
 			list: listCommand,
 			show: showCommand,

package/src/cli.ts

@@ -162,8 +162,8 @@ const USAGE = `Usage:
   papyrus tasks graph [--session-id <id>] [--json]
   papyrus tasks active [--session-id <id>] [--json]
   papyrus tasks focused [--session-id <id>] [--json]
-  papyrus tasks pause [--session-id <id>] [--session-secret <secret>] [--json]
-  papyrus tasks unpause [--session-id <id>] [--session-secret <secret>] [--json]
+  papyrus tasks pause [--session-id <id>] [--session-secret <secret>] [--idempotency-key <key>] [--json]
+  papyrus tasks unpause [--session-id <id>] [--session-secret <secret>] [--idempotency-key <key>] [--json]
   papyrus tasks clear-focus [--session-id <id>] [--session-secret <secret>] [--json]
   papyrus tasks reap-stale-focus [--json]
   papyrus tasks claim <id> --owner <owner> [--ttl-ms <ms>] [--note <text>] [--json]
@@ -172,17 +172,19 @@ const USAGE = `Usage:
   papyrus tasks lease <id> [--json]
   papyrus tasks reap-stale-leases [--json]
   papyrus tasks event-feed [--cursor <n>] [--limit <n>] [--event-types-json <json>] [--json]
+  papyrus tasks mutation-status <idempotency-key> [--json]
   papyrus tasks history <id> [--json]
   papyrus tasks scope [project|all|graph <root-id>] [--json]
   papyrus tasks assign-project <id> [project-root] [--json]
   papyrus tasks focus <id> [--session-id <id>] [--session-secret <secret>] [--json]
   papyrus tasks update <id> [--title <title>] [--body <body>] [--labels-json <json>] [--status todo --reason <reason>] [--json]
-  papyrus tasks complete <id> [--session-id <id>] [--json]
-  papyrus tasks start <id> [--session-id <id>] [--json]
-  papyrus tasks submit <id> [--session-id <id>] [--json]
-  papyrus tasks reject <id> [--session-id <id>] [--json]
-  papyrus tasks retry <id> [--session-id <id>] [--json]
-  papyrus tasks cancel <id> [--session-id <id>] [--json]
+  papyrus tasks complete <id> [--session-id <id>] [--idempotency-key <key>] [--json]
+  papyrus tasks start <id> [--session-id <id>] [--idempotency-key <key>] [--json]
+  papyrus tasks submit <id> [--session-id <id>] [--idempotency-key <key>] [--json]
+  papyrus tasks reject <id> [--session-id <id>] [--idempotency-key <key>] [--json]
+  papyrus tasks retry <id> [--session-id <id>] [--idempotency-key <key>] [--json]
+  papyrus tasks cancel <id> [--session-id <id>] [--idempotency-key <key>] [--json]
+  papyrus tasks reopen <id> [--session-id <id>] [--idempotency-key <key>] [--json]
   papyrus tasks cancel-subtree <id> [--session-id <id>] [--json]
   papyrus tasks depend <id> <prerequisite-id> [--reason <reason>] [--session-id <id>] [--json]
   papyrus tasks undepend <id> <prerequisite-id> [--reason <reason>] [--session-id <id>] [--json]

package/src/constants.ts

@@ -9,7 +9,7 @@ export const DAEMON_PROBE_TIMEOUT_MS = 800;
 export const DAEMON_UNIT_NAME = "papyrus.service";
 export const DAEMON_DIR_ENV = "PAPYRUS_DAEMON_DIR";
 export const SQLITE_BUSY_TIMEOUT_MS = 5_000;
-export const SQLITE_SCHEMA_VERSION = 26;
+export const SQLITE_SCHEMA_VERSION = 27;
 export const SERVICE_MAX_BODY_BYTES = 1_048_576;
 
 export const WAL_CHECKPOINT_INTERVAL_MS = 60_000;
@@ -267,6 +267,8 @@ export const TASK_PROJECT_ALIAS_MAX_COUNT = 20;
 export const TASK_PROJECT_LIST_MAX_RESULTS = 100;
 export const TASK_CREATE_IDEMPOTENCY_KEY_MAX_LENGTH = 200;
 export const TASK_CREATE_IDEMPOTENCY_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+export const TASK_MUTATION_IDEMPOTENCY_KEY_MAX_LENGTH = 200;
+export const TASK_MUTATION_IDEMPOTENCY_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
 export const GRAPH_RENDER_PADDING_X = 2;
 export const GRAPH_RENDER_PADDING_Y = 1;
 export const GRAPH_RENDER_BOX_PADDING = 0;

package/src/db.ts

@@ -176,6 +176,24 @@ CREATE TABLE IF NOT EXISTS task_create_requests (
 	PRIMARY KEY (request_scope, idempotency_key)
 );
 CREATE INDEX IF NOT EXISTS task_create_requests_expiry_idx ON task_create_requests(expires_at);
+CREATE TABLE IF NOT EXISTS task_mutation_requests (
+	request_scope   TEXT NOT NULL,
+	idempotency_key TEXT NOT NULL,
+	receipt_id      TEXT NOT NULL UNIQUE,
+	task_id         TEXT REFERENCES artifacts(id) ON DELETE CASCADE,
+	operation       TEXT NOT NULL,
+	request_hash    TEXT NOT NULL,
+	state           TEXT NOT NULL CHECK (state IN ('pending', 'completed')),
+	response_json   TEXT,
+	created_at      TEXT NOT NULL,
+	updated_at      TEXT NOT NULL,
+	expires_at      TEXT NOT NULL,
+	PRIMARY KEY (request_scope, idempotency_key),
+	CHECK ((state = 'pending' AND response_json IS NULL) OR (state = 'completed' AND response_json IS NOT NULL))
+);
+CREATE INDEX IF NOT EXISTS task_mutation_requests_expiry_idx ON task_mutation_requests(expires_at);
+CREATE UNIQUE INDEX IF NOT EXISTS task_mutation_requests_pending_task_operation_idx
+	ON task_mutation_requests(task_id, operation) WHERE state = 'pending' AND task_id IS NOT NULL;
 CREATE TABLE IF NOT EXISTS artifact_events (
 	id                   INTEGER PRIMARY KEY AUTOINCREMENT,
 	artifact_id          TEXT NOT NULL REFERENCES artifacts(id),
@@ -799,6 +817,32 @@ const FUTURE_MIGRATIONS: ReadonlyArray<PapyrusMigration> = [
 			}
 		},
 	},
+	{
+		version: 27,
+		name: "task-lifecycle-mutation-receipts",
+		up: (db) => {
+			db.exec(`
+				CREATE TABLE IF NOT EXISTS task_mutation_requests (
+					request_scope   TEXT NOT NULL,
+					idempotency_key TEXT NOT NULL,
+					receipt_id      TEXT NOT NULL UNIQUE,
+					task_id         TEXT REFERENCES artifacts(id) ON DELETE CASCADE,
+					operation       TEXT NOT NULL,
+					request_hash    TEXT NOT NULL,
+					state           TEXT NOT NULL CHECK (state IN ('pending', 'completed')),
+					response_json   TEXT,
+					created_at      TEXT NOT NULL,
+					updated_at      TEXT NOT NULL,
+					expires_at      TEXT NOT NULL,
+					PRIMARY KEY (request_scope, idempotency_key),
+					CHECK ((state = 'pending' AND response_json IS NULL) OR (state = 'completed' AND response_json IS NOT NULL))
+				);
+				CREATE INDEX IF NOT EXISTS task_mutation_requests_expiry_idx ON task_mutation_requests(expires_at);
+				CREATE UNIQUE INDEX IF NOT EXISTS task_mutation_requests_pending_task_operation_idx
+					ON task_mutation_requests(task_id, operation) WHERE state = 'pending' AND task_id IS NOT NULL;
+			`);
+		},
+	},
 ];
 
 /**

package/src/domain-service-shared.ts

@@ -107,9 +107,8 @@ export type TransitionTable<Action extends string, Status extends string> = Reco
 /**
  * The from/to-table lookup+validation half of a transition, split out from runTransition
  * (below) so a caller with its own side effects gated on "is this action even valid from the
- * current status" (e.g. Tasks.transition's dependency-blocking check and focus-store
- * bookkeeping, which must run -- or not -- before the status write itself) can call this
- * directly instead of duplicating the same lookup+throw three times. Every other caller
+ * current status" can call this directly instead of duplicating the same lookup+throw.
+ * Task lifecycle now uses its richer retry-safe transition primitive instead. Every other caller
  * (Document/Rule/Playbook, none of which have that ordering constraint) uses runTransition
  * instead, which does this same check plus the write in one call.
  */

package/src/handlers/playbooks.ts

@@ -44,6 +44,10 @@ import {
 } from "./shared.ts";
 
 const OWNER = "playbooks";
+const jsonObjectProp = {
+	type: ["object", "string"],
+	description: "A JSON object; a JSON-encoded object string is also accepted for tool-calling compatibility.",
+} as const;
 
 export interface PlaybooksVehicleDeps {
 	artifacts: ArtifactStore;
@@ -126,7 +130,7 @@ export function registerPlaybooksVehicleOperations(registry: VehicleRegistry, de
 		"preview",
 		"Renders a Playbook's whole composition tree as text, with no side effects.",
 		"read",
-		{ id: stringProp, name: stringProp, arguments: { type: "object" } },
+		{ id: stringProp, name: stringProp, arguments: jsonObjectProp },
 		[],
 		(input) => {
 			normalizeJsonEncodedField(input, "arguments");
@@ -138,7 +142,7 @@ export function registerPlaybooksVehicleOperations(registry: VehicleRegistry, de
 		"invoke",
 		"Compiles the Playbook's steps and composition tree into real Tasks wired with dependsOn, and focuses the first one -- one step surfaces at a time as it becomes focused, exactly like any other Task. `arguments` supplies known values as {name: value}; if a declared REQUIRED argument is still missing, nothing is created and missingArguments is returned instead -- ask the human for these (discuss tool, live:true) and invoke again, never guess. Drive the returned entryTaskId forward with the tasks tool (start/submit/complete).",
 		"local-write",
-		{ id: stringProp, name: stringProp, run_id: stringProp, arguments: { type: "object" }, project_root: stringProp },
+		{ id: stringProp, name: stringProp, run_id: stringProp, arguments: jsonObjectProp, project_root: stringProp },
 		[],
 		(input) => {
 			normalizeJsonEncodedField(input, "arguments");

package/src/handlers/shared.ts

@@ -7,11 +7,13 @@ import {
 	bindVehicleOperation,
 	defineVehicleOperation,
 	defineVehicleSchema,
+	type JsonSchema,
 	type VehicleContentBlock,
 	VehicleError,
 	type VehicleLimits,
 	type VehicleOperationContext,
 	type VehicleSchemaCodec,
+	type VehicleSchemaIssue,
 } from "@danypops/vehicle-core";
 import type { VehicleRegistry } from "@danypops/vehicle-server";
 import type { Artifact } from "../artifact/artifact.ts";
@@ -21,33 +23,118 @@ import { InvalidSessionSecretError } from "../session-identity/session-identity-
 import { TaskCreateIdempotencyConflictError } from "../stores/task-create-request-store.ts";
 import { TaskDependencyCycleError, TaskExecutionBoundExceededError, type TaskExecutionPlan } from "../task/task-execution.ts";
 
-/**
- * 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 `enum` has to be checked here for
- * real, or it's a documentation gesture, not an honest contract.
- */
+interface OperationSchemaNode {
+	readonly type?: string | readonly string[];
+	readonly enum?: readonly unknown[];
+	readonly properties?: Readonly<Record<string, OperationSchemaNode>>;
+	readonly required?: readonly string[];
+	readonly additionalProperties?: boolean | OperationSchemaNode;
+	readonly items?: OperationSchemaNode;
+	readonly minLength?: number;
+	readonly maxLength?: number;
+	readonly minimum?: number;
+	readonly maximum?: number;
+	readonly minItems?: number;
+	readonly maxItems?: number;
+	readonly description?: string;
+	readonly [key: string]: unknown;
+}
+
+function schemaIssue(path: readonly (string | number)[], message: string): VehicleSchemaIssue[] {
+	return [{ path, message }];
+}
+
+function matchesSchemaType(value: unknown, type: string): boolean {
+	if (type === "object") return typeof value === "object" && value !== null && !Array.isArray(value);
+	if (type === "array") return Array.isArray(value);
+	if (type === "string") return typeof value === "string";
+	if (type === "number") return typeof value === "number" && Number.isFinite(value);
+	if (type === "integer") return typeof value === "number" && Number.isInteger(value);
+	if (type === "boolean") return typeof value === "boolean";
+	return true;
+}
+
+function validateSchemaValue(value: unknown, schema: OperationSchemaNode, path: readonly (string | number)[]): VehicleSchemaIssue[] {
+	const label = path.length === 0 ? "input" : String(path.at(-1));
+	const declaredTypes = typeof schema.type === "string" ? [schema.type] : (schema.type ?? []);
+	const type = declaredTypes.find((candidate) => matchesSchemaType(value, candidate));
+	if (declaredTypes.length > 0 && type === undefined) {
+		const accepted = declaredTypes.map((candidate) =>
+			candidate === "integer" ? "an integer" : `${candidate === "object" ? "an" : "a"} ${candidate}`,
+		);
+		return schemaIssue(path, `${label} must be ${accepted.join(" or ")}`);
+	}
+	if (type === "object") {
+		if (typeof value !== "object" || value === null || Array.isArray(value)) return schemaIssue(path, `${label} must be an object`);
+		const record = value as Record<string, unknown>;
+		for (const key of schema.required ?? []) {
+			if (!(key in record)) {
+				const acceptedShape = schema.description ? `; ${schema.description}` : "";
+				return schemaIssue([...path, key], `${key} is required${acceptedShape}`);
+			}
+		}
+		for (const [key, child] of Object.entries(schema.properties ?? {})) {
+			if (!(key in record)) continue;
+			const issues = validateSchemaValue(record[key], child, [...path, key]);
+			if (issues.length > 0) return issues;
+		}
+		for (const key of Object.keys(record)) {
+			if (key in (schema.properties ?? {})) continue;
+			if (schema.additionalProperties === false) return schemaIssue([...path, key], `${key} is not allowed`);
+			if (typeof schema.additionalProperties === "object") {
+				const issues = validateSchemaValue(record[key], schema.additionalProperties, [...path, key]);
+				if (issues.length > 0) return issues;
+			}
+		}
+	} else if (type === "array") {
+		const entries = value as unknown[];
+		if (schema.minItems !== undefined && entries.length < schema.minItems) {
+			return schemaIssue(path, `${label} must contain at least ${schema.minItems} item(s)`);
+		}
+		if (schema.maxItems !== undefined && entries.length > schema.maxItems) {
+			return schemaIssue(path, `${label} cannot contain more than ${schema.maxItems} item(s)`);
+		}
+		if (schema.items) {
+			for (const [index, entry] of entries.entries()) {
+				const issues = validateSchemaValue(entry, schema.items, [...path, index]);
+				if (issues.length > 0) return issues;
+			}
+		}
+	} else if (type === "string") {
+		const text = value as string;
+		if (schema.minLength !== undefined && text.length < schema.minLength) {
+			return schemaIssue(path, `${label} must contain at least ${schema.minLength} character(s)`);
+		}
+		if (schema.maxLength !== undefined && text.length > schema.maxLength) {
+			return schemaIssue(path, `${label} cannot exceed ${schema.maxLength} character(s)`);
+		}
+	} else if (type === "number" || type === "integer") {
+		const number = value as number;
+		if (schema.minimum !== undefined && number < schema.minimum) {
+			return schemaIssue(path, `${label} must be at least ${schema.minimum}`);
+		}
+		if (schema.maximum !== undefined && number > schema.maximum) {
+			return schemaIssue(path, `${label} cannot exceed ${schema.maximum}`);
+		}
+	}
+	if (schema.enum && !schema.enum.includes(value)) {
+		return schemaIssue(path, `${label} must be one of ${schema.enum.join(", ")}`);
+	}
+	return [];
+}
+
+/** VehicleRegistry executes this codec before resolving or dispatching an operation. Keep the
+ * recursive runtime checks aligned with the same JSON Schema clients and tools_man receive. */
 export function looseObjectSchema(
-	properties: Record<string, { type: string; enum?: readonly string[] }>,
+	properties: Readonly<Record<string, OperationSchemaNode>>,
 	required: readonly string[] = [],
 ): VehicleSchemaCodec<Record<string, unknown>> {
+	const schema = { type: "object", properties, required: [...required], additionalProperties: false } as const;
 	return defineVehicleSchema<Record<string, unknown>>({
-		jsonSchema: { type: "object", properties, required: [...required], additionalProperties: false },
+		jsonSchema: schema as unknown as JsonSchema,
 		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, schema] of Object.entries(properties)) {
-				if (!schema.enum || !(key in input)) continue;
-				if (!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 };
+			const issues = validateSchemaValue(value, schema, []);
+			return issues.length > 0 ? { success: false, issues } : { success: true, value: value as Record<string, unknown> };
 		},
 	});
 }
@@ -249,7 +336,7 @@ export function buildWorkflowRunContent(
 
 export type OperationSchemaProperties = Record<
 	string,
-	{ type: string; enum?: readonly string[]; description?: string; [key: string]: unknown }
+	{ type: string | readonly string[]; enum?: readonly string[]; description?: string; [key: string]: unknown }
 >;
 
 export type DefineOperation = (