@danypops/papyrus 0.54.3 → 0.54.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.54.3",
+  "version": "0.54.5",
   "description": "Daemon-backed graph artifacts, evidence-bearing tasks, rules, skills, and native TUI workflows for Pi",
   "type": "module",
   "main": "./src/index.ts",
@@ -15,6 +15,17 @@
     "serve": "bun src/cli.ts serve",
     "service:install": "bun src/cli.ts service install"
   },
+  "packed": {
+    "daemonService": {
+      "name": "papyrus",
+      "displayName": "Papyrus graph artifact service",
+      "binPath": "src/cli.ts",
+      "args": ["serve"],
+      "handleFilename": "vehicle-handle.json",
+      "restartOnFailure": true,
+      "restartSec": 2
+    }
+  },
   "devDependencies": {
     "bun-types": "latest",
     "typescript": "^5.7.3"

package/src/client.ts

@@ -126,18 +126,31 @@ export interface ConnectPapyrusClientOptions {
 	env?: Record<string, string | undefined>;
 	/** Overrides the version connectWithVersionCheck compares against. Defaults to PAPYRUS_VERSION; test-only -- lets a test force a mismatch against a real daemon without a second build. */
 	expectedVersion?: ExpectedVersion;
+	/**
+	 * Overrides the default fail-closed behavior (see connectPapyrusClient's own doc comment for
+	 * why that default changed). Test-only -- covers the auto-spawn mechanism itself
+	 * (connect-client-auto-spawn.test.ts) and lets other real-daemon integration tests keep using
+	 * it as convenient bootstrap. A real, non-Armada-supervised standalone deployment could also
+	 * set this explicitly, but that is not this option's primary purpose.
+	 */
+	autoStart?: boolean;
 }
 
 /**
- * Transparently starts the daemon first if it is not already running -- matches
- * every other daemon-backed ecosystem package that opted into auto-start (see
- * @danypops/vehicle-client's connectWithPolicy doc comment: web-spider opts in,
- * lector/pi-packed fail closed by design). Papyrus previously failed closed with
- * "install/start papyrus.service", requiring a human to separately discover and
- * run `papyrus service install` before the very first tool call could succeed.
- * A handle file that exists but points at a dead/unreachable daemon is a distinct
- * failure (stale, not "never started") and is NOT auto-recovered here -- it still
- * throws its own actionable "restart manually" error, unchanged from before.
+ * Fails closed if nothing is reachable at all -- matches lector/pi-packed (see
+ * @danypops/vehicle-client's connectWithPolicy doc comment). Papyrus used to auto-start here
+ * (autoStart: true) because it predated being a properly Armada-supervised Vehicle; that flag
+ * is now a genuine liability, not a convenience: a real, live race was traced to it directly --
+ * Armada's own systemd unit and THIS client's auto-spawn each independently tried to be "the one
+ * that starts Papyrus" whenever no daemon was momentarily reachable (e.g. mid-restart), and
+ * whichever one's child won the OS-level single-instance-lock race became an orphan invisible to
+ * systemd's own tracking, permanently confusing `armada status`. Now that Armada's systemd unit
+ * (Restart=on-failure) is the one and only thing responsible for keeping Papyrus running, a
+ * client that finds nothing reachable should say so plainly, not compete to fix it.
+ *
+ * Stale-VERSION self-healing (an already-running daemon reporting an older version than this
+ * client expects) is unrelated to autoStart and still works: connectWithVersionCheck's own kill-
+ * and-replace path only requires `spawn` to be defined, independent of the autoStart flag above.
  */
 export async function connectPapyrusClient(
 	dir: string = daemonStateDir(),
@@ -147,7 +160,7 @@ export async function connectPapyrusClient(
 		{
 			readHandle: () => readDaemonHandle(dir) ?? null,
 			buildClient: probedPapyrusClient,
-			autoStart: true,
+			autoStart: options.autoStart ?? false,
 			spawn: () => {
 				spawnDetachedDaemon({
 					binPath: papyrusCliPath(),
@@ -156,7 +169,8 @@ export async function connectPapyrusClient(
 					spawn: spawnPapyrusDaemonProcess,
 				});
 			},
-			fallbackMessage: "Papyrus daemon failed to start automatically; run `papyrus service install` or `papyrus serve` manually.",
+			fallbackMessage:
+				"Papyrus daemon is not running; Armada should be supervising it -- run `armada status`/`armada reconcile`, or `papyrus serve` directly if this is a standalone (non-Armada) setup.",
 		},
 		{
 			expectedVersion: options.expectedVersion ?? papyrusExpectedVersion,

package/src/domain/gate-execution.ts

@@ -0,0 +1,205 @@
+/**
+ * Gate-execution engine, split out of ops.ts (the artifact-CRUD file) as part of a SOLID-audit-
+ * driven decomposition (see Doc "Modularity playbook: building-block-shaped TypeScript modules
+ * for papyrus/pi-papyrus" and the "gate-execution engine" child of "Epic: Modularize papyrus/
+ * pi-papyrus god-files into building-block modules"). This logic was already unified in a prior
+ * refactor (sync/async outcome evaluation shared via evaluateProcessGateResult/spawnErrorGateResult)
+ * but still lived inside the artifact-CRUD file until now.
+ *
+ * Only `runGates`/`runGatesAsync` are real public API -- verified via find_references before this
+ * move, not assumed from a grep hit count: the only two real importers were
+ * stores/sqlite-gate-runner.ts and test/ops.test.ts (every other `runGates`-named hit in the
+ * codebase is Tasks.runGates, a same-named but distinct method that calls into this module only
+ * indirectly, through the GateRunner port). Both were updated to import from this file directly;
+ * no barrel re-export needed.
+ *
+ * Depends on ops.ts's own `getArtifact` (still the right owner of that read -- it's real
+ * artifact-CRUD, not gate-execution's own concern) -- a one-directional dependency, since ops.ts
+ * no longer needs to import anything back from here.
+ */
+import { createRequire } from "node:module";
+import {
+	GATE_COMMAND_TIMEOUT_MS,
+	GATE_FILE_MAX_BYTES,
+	GATE_MAX_BUFFER_BYTES,
+	GATE_OUTPUT_LIMIT,
+	GATE_TEST_TIMEOUT_MS,
+} from "../constants.ts";
+import type { Db } from "../db.ts";
+import { getArtifact } from "../ops.ts";
+import type { Gate, GateResult, GateRunOptions } from "./gate.ts";
+
+const require_ = createRequire(import.meta.url);
+
+function readBoundedGateFile(path: string): string {
+	const { readFileSync, statSync } = require_("node:fs");
+	if (statSync(path).size > GATE_FILE_MAX_BYTES) throw new Error(`file exceeds ${GATE_FILE_MAX_BYTES} bytes`);
+	return readFileSync(path, "utf-8") as string;
+}
+
+/**
+ * Shared by the sync and async process-gate runners so "test" is never a second, independently
+ * maintained copy of "command"'s own command-template selection.
+ *
+ * "test" runs `gate.target` verbatim, exactly like "command" -- the only real difference is a
+ * more generous default timeout (GATE_TEST_TIMEOUT_MS vs GATE_COMMAND_TIMEOUT_MS), since a test
+ * suite routinely runs longer than an arbitrary command. It previously wrapped target in
+ * `npx vitest run ${target} --reporter=dot`, silently wrong for every real consumer in this
+ * ecosystem (all Bun-native, none use vitest): a target that was itself a full command (e.g.
+ * `bun test path/to.test.ts`, exactly what every existing gate/checklist example here has always
+ * shown) got parsed by vitest as three separate positional args, triggering vitest's own broad
+ * discovery across the whole repo instead of running the intended command at all -- a real
+ * incident (task ab1463e2) that produced an unrelated multi-suite vitest failure cascade instead
+ * of the actual target ever running.
+ */
+function processGateCommand(gate: Gate): { command: string; timeout: number } {
+	if (gate.type === "test") return { command: gate.target, timeout: gate.timeoutMs ?? GATE_TEST_TIMEOUT_MS };
+	return { command: gate.target, timeout: gate.timeoutMs ?? GATE_COMMAND_TIMEOUT_MS };
+}
+
+/**
+ * Keeps the LAST GATE_OUTPUT_LIMIT characters, not the first -- a real command's own meaningful
+ * pass/fail summary is its last lines, not its first (setup/banner noise). See GATE_OUTPUT_LIMIT's
+ * own doc comment (constants.ts) for the real incident this fixes.
+ */
+function gateOutputTail(text: string): string {
+	return text.length > GATE_OUTPUT_LIMIT ? text.slice(-GATE_OUTPUT_LIMIT) : text;
+}
+
+/**
+ * The one place "did this process gate pass, and what should its display output say" is decided,
+ * shared by the sync (runProcessGateSync) and async (executeGateCommand's caller) process-gate
+ * runners -- previously two hand-copied inline checks that already had to be fixed twice, by
+ * hand, more than once (gate.expect seeing stderr too; GATE_OUTPUT_LIMIT's truncation direction).
+ * `matchable` must be the FULL captured output (bounded only by GATE_MAX_BUFFER_BYTES / Node's own
+ * spawnSync maxBuffer, never GATE_OUTPUT_LIMIT), so gate.expect always sees the whole run, never
+ * the truncated display copy `output` becomes.
+ */
+function evaluateProcessGateResult(gate: Gate, code: number | null, matchable: string): { passed: boolean; output: string } {
+	const exitedZero = code === 0;
+	return {
+		passed: exitedZero && (gate.expect ? matchable.includes(gate.expect) : true),
+		output: gateOutputTail(matchable) || (exitedZero ? "ok" : `command exited with code ${code}`),
+	};
+}
+
+/** The other shared branch: a literal spawn-level failure (command not found, spawnSync's own maxBuffer exceeded, etc.) -- distinct from a process that ran and exited non-zero, which evaluateProcessGateResult above handles. Identical treatment on both the sync and async paths: the raw error message, tail-truncated like any other gate output. */
+function spawnErrorGateResult(gate: Gate, error: Error): GateResult {
+	return { gate, passed: false, output: gateOutputTail(error.message) };
+}
+
+function runProcessGateSync(gate: Gate, cwd?: string): GateResult {
+	const { spawnSync } = require_("node:child_process");
+	const { command, timeout } = processGateCommand(gate);
+	const result = spawnSync(command, { shell: true, encoding: "utf-8", timeout, ...(cwd ? { cwd } : {}) });
+	if (result.error) return spawnErrorGateResult(gate, result.error);
+	const combined = `${result.stdout ?? ""}${result.stderr ?? ""}`.trim();
+	return { gate, ...evaluateProcessGateResult(gate, result.status, combined) };
+}
+
+/**
+ * Runs one gate command with two invariants a prior implementation lacked (a real incident; see
+ * GateRunOptions.cwd's doc comment):
+ *   1. `cwd` is always explicit, never inherited from the daemon's own process cwd.
+ *   2. The whole process group is killed on timeout, not just the immediate shell. `exec()`'s own
+ *      `timeout` option only signals the process it directly spawned (the shell running
+ *      `command`); a shell's own child (e.g. `bun` under `sh -c "bun test"`) is not in general
+ *      killed by that signal and can be reparented and keep running -- and consuming memory --
+ *      indefinitely after Papyrus considers the gate "timed out". Spawning detached (its own
+ *      process group) and killing the negated pid on our own timer reaches the whole tree.
+ */
+function executeGateCommand(gate: Gate, command: string, timeout: number, cwd?: string): Promise<GateResult> {
+	// `spawn(..., { shell: true, detached: true })` instead of the `exec()` convenience wrapper:
+	// `detached` (needed to make the shell the leader of its own process group, so the negated pid
+	// below reaches every descendant, not just the shell) is not part of Node's `exec()`/
+	// `ExecOptions` type at all -- `spawn`'s options support it directly and correctly.
+	const { spawn } = require_("node:child_process") as typeof import("node:child_process");
+	return new Promise((resolve) => {
+		let settled = false;
+		let buffered = "";
+		let truncated = false;
+		const child = spawn(command, { shell: true, detached: true, ...(cwd ? { cwd } : {}) });
+
+		const append = (chunk: Buffer): void => {
+			if (truncated) return;
+			buffered += chunk.toString("utf8");
+			if (buffered.length > GATE_MAX_BUFFER_BYTES) {
+				buffered = buffered.slice(0, GATE_MAX_BUFFER_BYTES);
+				truncated = true;
+			}
+		};
+		child.stdout?.on("data", append);
+		child.stderr?.on("data", append);
+
+		const finish = (result: GateResult): void => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			resolve(result);
+		};
+
+		child.on("error", (error) => finish(spawnErrorGateResult(gate, error)));
+		child.on("close", (code) => finish({ gate, ...evaluateProcessGateResult(gate, code, buffered.trim()) }));
+
+		const timer = setTimeout(() => {
+			if (settled) return;
+			if (child.pid !== undefined) {
+				try {
+					process.kill(-child.pid, "SIGKILL");
+				} catch {
+					child.kill("SIGKILL");
+				}
+			}
+			finish({ gate, passed: false, output: `gate command timed out after ${timeout}ms` });
+		}, timeout);
+	});
+}
+
+function runNonProcessGate(gate: Gate): GateResult {
+	if (gate.type === "file-exists") {
+		const { existsSync } = require_("node:fs");
+		const exists = existsSync(gate.target);
+		return { gate, passed: exists, output: exists ? "exists" : "not found" };
+	}
+	if (gate.type === "contains") {
+		try {
+			const content = readBoundedGateFile(gate.target);
+			const found = gate.expect ? content.includes(gate.expect) : content.length > 0;
+			return { gate, passed: found, output: found ? "found" : `"${gate.expect ?? ""}" not found` };
+		} catch {
+			return { gate, passed: false, output: "file not readable" };
+		}
+	}
+	return { gate, passed: false, output: `unknown gate type: ${String(gate.type)}` };
+}
+
+export function runGates(db: Db, artifactId: string, options: GateRunOptions = {}): GateResult[] {
+	const art = getArtifact(db, artifactId);
+	if (!art) throw new Error("artifact not found");
+	const gates = (art.extra.gates as Gate[]) ?? [];
+	const cwd = options.cwd;
+	return gates.map((gate) => (gate.type === "command" || gate.type === "test" ? runProcessGateSync(gate, cwd) : runNonProcessGate(gate)));
+}
+
+/** Gate runner for daemon request paths; subprocess gates never block the event loop. */
+export async function runGatesAsync(db: Db, artifactId: string, options: GateRunOptions = {}): Promise<GateResult[]> {
+	const art = getArtifact(db, artifactId);
+	if (!art) throw new Error("artifact not found");
+	const gates = (art.extra.gates as Gate[]) ?? [];
+	const results: GateResult[] = [];
+	for (const gate of gates) {
+		const remainingMs = options.deadlineMs === undefined ? undefined : options.deadlineMs - Date.now();
+		if (remainingMs !== undefined && remainingMs <= 0) {
+			results.push({ gate, passed: false, output: "gate runtime deadline exceeded" });
+			continue;
+		}
+		if (gate.type === "command" || gate.type === "test") {
+			const { command, timeout: configuredTimeout } = processGateCommand(gate);
+			const timeout = remainingMs === undefined ? configuredTimeout : Math.max(1, Math.min(configuredTimeout, remainingMs));
+			results.push(await executeGateCommand(gate, command, timeout, options.cwd));
+		} else {
+			results.push(runNonProcessGate(gate));
+		}
+	}
+	return results;
+}

package/src/handlers/artifact-helpers.ts

@@ -0,0 +1,110 @@
+/**
+ * Cross-domain artifact name/id resolution and workflow-run narrative building, split out of
+ * handlers/shared.ts as part of a SOLID-audit-driven decomposition (see Doc "Modularity playbook:
+ * building-block-shaped TypeScript modules for papyrus/pi-papyrus" and the "handlers/shared.ts
+ * split" child of "Epic: Modularize papyrus/pi-papyrus god-files into building-block modules").
+ */
+import { type VehicleContentBlock, VehicleError } from "@danypops/vehicle-core";
+import type { Artifact } from "../artifact/artifact.ts";
+import type { ArtifactStore } from "../artifact/artifact-store.ts";
+import type { TaskExecutionPlan } from "../task/task-execution.ts";
+import { validationError } from "./operation-schema.ts";
+
+/** A known LLM tool-calling quirk: a nested-object field arrives JSON-stringified rather than as a real object. Mutates input[key] in place when it's a string, leaves it untouched otherwise. */
+export function normalizeJsonEncodedField(input: Record<string, unknown>, key: string): void {
+	const value = input[key];
+	if (typeof value !== "string") return;
+	try {
+		input[key] = JSON.parse(value);
+	} catch {
+		throw validationError(`${key} must be valid JSON`);
+	}
+}
+
+/** Exact match semantics as the Pi-extension helper this replaces (domain-tools.ts's matchArtifactByName) -- case-insensitive exact title match, refuses to guess between ambiguous matches. */
+export function matchArtifactByName(candidates: readonly Artifact[], name: string): string {
+	const needle = name.trim().toLowerCase();
+	const matches = candidates.filter((artifact) => artifact.title.trim().toLowerCase() === needle);
+	if (matches.length === 0) {
+		throw new VehicleError("artifact-not-found", `no artifact named "${name}" found in this scope`, { category: "not_found" });
+	}
+	if (matches.length > 1) {
+		throw new VehicleError(
+			"artifact-name-ambiguous",
+			`${matches.length} artifacts are named "${name}": ${matches.map((a) => `${a.title} (${a.alias})`).join(", ")} -- use id or alias to disambiguate`,
+			{ category: "conflict" },
+		);
+	}
+	return matches[0]!.id;
+}
+
+/**
+ * Resolves a name to an id. Checks `artifacts.getByAlias` first -- a real, indexed,
+ * globally-unique match, unlike title -- before falling back to today's scoped
+ * title-based matching, retrying against `fetchWidened` (an unscoped/cross-project
+ * search) only when `fetchCandidates` finds nothing. Owns the match-or-widen control
+ * flow only -- the caller supplies its own scoped/widened list calls, since scoping
+ * differs per domain. Omit `fetchWidened` when there is no wider scope to retry.
+ */
+export function resolveArtifactIdWidened(
+	artifacts: ArtifactStore,
+	name: string,
+	fetchCandidates: () => readonly Artifact[],
+	fetchWidened?: () => readonly Artifact[],
+): string {
+	const byAlias = artifacts.getByAlias(name.trim());
+	if (byAlias) return byAlias.id;
+	try {
+		return matchArtifactByName(fetchCandidates(), name);
+	} catch (error) {
+		if (!(error instanceof VehicleError) || error.code !== "artifact-not-found" || !fetchWidened) throw error;
+		return matchArtifactByName(fetchWidened(), name);
+	}
+}
+
+/** Synchronous equivalent of pi-papyrus's own artifactLabelsById -- server-side, a direct ArtifactStore.get() replaces the extra RPC round-trip that helper needed client-side. Always suffixes the alias -- a short, meaningful, globally-unique reference, unlike the raw UUID it replaces. */
+export function labelsById(artifacts: ArtifactStore, ids: readonly string[]): Map<string, string> {
+	const uniqueIds = [...new Set(ids)];
+	const resolved = uniqueIds.map((id) => artifacts.get(id)).filter((artifact): artifact is Artifact => artifact !== null);
+	return new Map(resolved.map((artifact) => [artifact.id, `${artifact.title} (${artifact.alias})`]));
+}
+
+export interface WorkflowRunNarrativeInput {
+	runId: string;
+	created: { docs: readonly string[]; rules: readonly string[]; tasks: readonly string[] };
+	rootTaskIds: readonly string[];
+	execution: TaskExecutionPlan;
+}
+
+/**
+ * Builds the model-facing `content` text for a workflow run result (ready roots, context docs,
+ * scoped rules, an execution tree) directly, so the model reads a summary instead of the raw
+ * execution DAG -- the same shape pi-papyrus's own hand-rolled playbooks tool built
+ * client-side, now built once here where the run result is actually produced.
+ */
+export function buildWorkflowRunContent(
+	artifacts: ArtifactStore,
+	headline: string,
+	input: WorkflowRunNarrativeInput,
+	extraLines: readonly string[] = [],
+): VehicleContentBlock {
+	const nodeById = new Map(input.execution.nodes.map((node) => [node.id, node]));
+	const rootLabels = input.rootTaskIds.map((id) => nodeById.get(id)?.title ?? "unknown task");
+	const createdLabels = labelsById(artifacts, [...input.created.docs, ...input.created.rules]);
+	const titleCounts = new Map<string, number>();
+	for (const node of input.execution.nodes) titleCounts.set(node.title, (titleCounts.get(node.title) ?? 0) + 1);
+	const executionLines = input.execution.nodes
+		.map((node) =>
+			(titleCounts.get(node.title) ?? 0) > 1 ? `  [${node.state}] ${node.title} (${node.id})` : `  [${node.state}] ${node.title}`,
+		)
+		.join("\n");
+	const text = [
+		headline,
+		...extraLines,
+		`Ready roots: ${rootLabels.join(", ") || "none"}.`,
+		`Context docs: ${input.created.docs.map((id) => createdLabels.get(id) ?? "unknown document").join(", ") || "none"}.`,
+		`Scoped rules: ${input.created.rules.map((id) => createdLabels.get(id) ?? "unknown rule").join(", ") || "none"}.`,
+		...(executionLines ? ["Execution:", executionLines] : []),
+	].join("\n");
+	return { type: "text", text };
+}

package/src/handlers/operation-schema.ts

@@ -0,0 +1,161 @@
+/**
+ * Generic, domain-agnostic operation-input schema DSL, split out of handlers/shared.ts as part of
+ * a SOLID-audit-driven decomposition (see Doc "Modularity playbook: building-block-shaped
+ * TypeScript modules for papyrus/pi-papyrus" and the "handlers/shared.ts split" child of "Epic:
+ * Modularize papyrus/pi-papyrus god-files into building-block modules"). Nothing here references
+ * a specific Papyrus domain (tasks/docs/rules/...) -- a real candidate to eventually become its
+ * own building block other Vehicle-backed daemons could reuse directly.
+ */
+import {
+	defineVehicleSchema,
+	type JsonSchema,
+	VehicleError,
+	type VehicleSchemaCodec,
+	type VehicleSchemaIssue,
+} from "@danypops/vehicle-core";
+
+export 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;
+	/** A key not in `properties` is validated against the first pattern here whose RegExp matches it, instead of falling through to `additionalProperties` -- e.g. a free-form string-keyed map (tasks.create's checklist) uses `{"^.*$": entrySchema}` so a client-side JSON-Schema validator that reports `additionalProperties`-as-schema violations only as a generic top-level "must not have additional properties" (TypeBox's own real, confirmed behavior -- see vehicle-shell.ts's formatSchemaChildren for the matching tools_man rendering) instead descends into the real nested violation, matching an array's `items` precision. */
+	readonly patternProperties?: Readonly<Record<string, 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;
+			const patternMatch = Object.entries(schema.patternProperties ?? {}).find(([pattern]) => new RegExp(pattern).test(key));
+			if (patternMatch) {
+				const issues = validateSchemaValue(record[key], patternMatch[1], [...path, key]);
+				if (issues.length > 0) return issues;
+				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: 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: schema as unknown as JsonSchema,
+		safeParse(value) {
+			const issues = validateSchemaValue(value, schema, []);
+			return issues.length > 0 ? { success: false, issues } : { success: true, value: value as Record<string, unknown> };
+		},
+	});
+}
+
+export const passthroughOutput: VehicleSchemaCodec<unknown> = defineVehicleSchema<unknown>({
+	jsonSchema: { type: "object" },
+	safeParse: (value) => ({ success: true, value }),
+});
+
+export const stringProp = { type: "string" } as const;
+export const numberProp = { type: "number" } as const;
+export const booleanProp = { type: "boolean" } as const;
+
+/**
+ * A plain `throw new Error(...)` inside any resolve()/execute() step here is caught by
+ * vehicle-registry.ts's generic dispatch and re-wrapped as VehicleError("handler-failed",
+ * `${key} handler failed`, {category: "internal"}) -- built to catch a genuine crash, but
+ * it can't distinguish that from an ordinary, expected validation/lookup failure, so it
+ * discards the original message and category either way. Every guard clause and name
+ * resolution below must throw a VehicleError directly so it passes through that dispatch
+ * unchanged (vehicle-registry.ts only rewraps errors that are NOT already a VehicleError).
+ */
+export function validationError(message: string): VehicleError {
+	return new VehicleError("validation-failed", message, { category: "validation" });
+}

package/src/handlers/paired-mutation.ts

@@ -0,0 +1,102 @@
+/**
+ * Vehicle-operation-definer DSL (createOperationDefiner) and the paired add/remove mutation shape
+ * built on top of it (definePairedMutation), split out of handlers/shared.ts as part of a
+ * SOLID-audit-driven decomposition (see Doc "Modularity playbook: building-block-shaped
+ * TypeScript modules for papyrus/pi-papyrus" and the "handlers/shared.ts split" child of "Epic:
+ * Modularize papyrus/pi-papyrus god-files into building-block modules").
+ */
+import { bindVehicleOperation, defineVehicleOperation, type VehicleLimits, type VehicleOperationContext } from "@danypops/vehicle-core";
+import type { VehicleRegistry } from "@danypops/vehicle-server";
+import { looseObjectSchema, passthroughOutput } from "./operation-schema.ts";
+
+export type OperationSchemaProperties = Record<
+	string,
+	{ type: string | readonly string[]; enum?: readonly string[]; description?: string; [key: string]: unknown }
+>;
+
+export type DefineOperation = (
+	action: string,
+	description: string,
+	effect: "read" | "local-write",
+	properties: OperationSchemaProperties,
+	required: readonly string[],
+	resolve: (input: Record<string, unknown>) => Record<string, unknown>,
+	execute?: (input: Record<string, unknown>, context: VehicleOperationContext<Record<string, unknown>>) => unknown,
+	/**
+	 * Overrides this one operation's own Vehicle transport limits, distinct from every other
+	 * operation this same createOperationDefiner call produces. For an operation that shells out
+	 * to and waits on a real external command (e.g. tasks.run_gates/tasks.complete) rather than an
+	 * instant CRUD read/write -- see handlers/tasks.ts's GATE_OPERATION_LIMITS for the motivating
+	 * case. Omit to keep the definer's own default limits, unchanged for every other action.
+	 */
+	limits?: VehicleLimits,
+) => void;
+
+const STANDARD_OPERATION_LIMITS = { defaultTimeoutMs: 5_000, maxTimeoutMs: 30_000, maxRequestBytes: 65_536, maxResponseBytes: 262_144 };
+
+/**
+ * Every *-vehicle.ts handler wires up the identical defineVehicleOperation +
+ * bindVehicleOperation + registry.register triple per action, differing only in
+ * owner/domain-prefix/permissions and (for tasks/playbooks) a real execute() override
+ * in place of the default "call the wrapped module operation" behavior. One factory,
+ * called once per domain, replaces that repetition.
+ */
+export function createOperationDefiner(
+	registry: VehicleRegistry,
+	owner: string,
+	domain: string,
+	permissions: readonly [string, string],
+	defaultCall: (name: string, input: Record<string, unknown>) => unknown,
+): DefineOperation {
+	return (action, description, effect, properties, required, resolve, execute, limits) => {
+		const operation = defineVehicleOperation({
+			name: `${domain}.${action}`,
+			version: 1,
+			description,
+			input: looseObjectSchema(properties, required),
+			output: passthroughOutput,
+			permissions: [...permissions],
+			effect,
+			idempotency: { mode: effect === "read" ? "safe" : "unsafe" },
+			limits: limits ?? STANDARD_OPERATION_LIMITS,
+		});
+		registry.register(
+			owner,
+			bindVehicleOperation(
+				operation,
+				() => async (context) =>
+					(execute ?? ((input: Record<string, unknown>) => defaultCall(`${domain}.${action}`, input)))(resolve(context.input), context),
+			),
+		);
+	};
+}
+
+export interface PairedMutationFieldSpec {
+	idProp: string;
+	nameProp: string;
+}
+
+/**
+ * depend/undepend and contain/uncontain (tasks-vehicle.ts, playbooks-vehicle.ts) share
+ * one shape: two id-or-name fields resolved the same way for both the add and the
+ * remove action, differing only in action name/description. One call replaces two
+ * near-identical define() invocations.
+ */
+export function definePairedMutation(
+	define: DefineOperation,
+	first: PairedMutationFieldSpec,
+	second: PairedMutationFieldSpec,
+	properties: OperationSchemaProperties,
+	required: readonly string[],
+	resolveId: (input: Record<string, unknown>, idProp: string, nameProp: string) => string,
+	add: { action: string; description: string },
+	remove: { action: string; description: string },
+): void {
+	const resolve = (input: Record<string, unknown>): Record<string, unknown> => ({
+		...input,
+		[first.idProp]: resolveId(input, first.idProp, first.nameProp),
+		[second.idProp]: resolveId(input, second.idProp, second.nameProp),
+	});
+	define(add.action, add.description, "local-write", properties, required, resolve);
+	define(remove.action, remove.description, "local-write", properties, required, resolve);
+}