@danypops/papyrus 0.44.8 → 0.44.10

package/src/client.ts

@@ -3,7 +3,7 @@ import { fileURLToPath } from "node:url";
 import { connectWithVersionCheck, type ExpectedVersion, spawnDetachedDaemon } from "@danypops/vehicle-client/daemon-client";
 import { createLiveVersionExpectation } from "@danypops/vehicle-client/version";
 import { DAEMON_CLIENT_TIMEOUT_MS, DAEMON_DIR_ENV, DAEMON_PROBE_TIMEOUT_MS } from "./constants.ts";
-import { type DaemonHandle, daemonStateDir, readDaemonHandle } from "./daemon-state.ts";
+import { type DaemonHandle, daemonStateDir, readDaemonHandle } from "./daemon/daemon-state.ts";
 import type { OperationName, SchemaState } from "./service.ts";
 
 /**
@@ -161,7 +161,7 @@ export function resolvePushChannelTarget(dir: string = daemonStateDir()): PushCh
 }
 
 export interface VehicleClientTarget {
-	/** Base URL for a domain migrated onto VehicleRegistry (see src/vehicle/*.ts) -- @danypops/vehicle-client's RemoteVehicleClient mounts its own /vehicle/manifest, /vehicle/invoke, /vehicle/cancel routes under this. */
+	/** Base URL for a domain migrated onto VehicleRegistry (see src/handlers/*.ts) -- @danypops/vehicle-client's RemoteVehicleClient mounts its own /vehicle/manifest, /vehicle/invoke, /vehicle/cancel routes under this. */
 	baseUrl: string;
 	token: string;
 }

package/src/{daemon-state.ts → daemon/daemon-state.ts}

@@ -3,7 +3,7 @@ import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { LOOPBACK_HOST, removeDaemonHandle, writeDaemonHandle } from "@danypops/vehicle-server/paths";
-import { DAEMON_DIR_ENV, DAEMON_HANDLE_FILE, DAEMON_HOST, DAEMON_PORT_FILE, DAEMON_TOKEN_FILE } from "./constants.ts";
+import { DAEMON_DIR_ENV, DAEMON_HANDLE_FILE, DAEMON_HOST, DAEMON_PORT_FILE, DAEMON_TOKEN_FILE } from "../constants.ts";
 
 export interface DaemonHandle {
 	baseUrl: string;

package/src/{daemon.ts → daemon/daemon.ts}

@@ -1,7 +1,9 @@
 import { join } from "node:path";
 import { acquireDaemonLock, releaseDaemonLock } from "@danypops/vehicle-server/paths";
 import { PushChannel } from "@danypops/vehicle-server/push-channel";
-import { DAEMON_HOST, DB_OPTIMIZE_INTERVAL_MS, dbPath, WAL_CHECKPOINT_INTERVAL_MS } from "./constants.ts";
+import { DAEMON_HOST, DB_OPTIMIZE_INTERVAL_MS, dbPath, WAL_CHECKPOINT_INTERVAL_MS } from "../constants.ts";
+import { logEvent, vehicleLogger } from "../log/log.ts";
+import { createApp, createPapyrusService } from "../service.ts";
 import {
 	clearDaemonPort,
 	clearVehicleHandle,
@@ -10,8 +12,6 @@ import {
 	writeDaemonPort,
 	writeVehicleHandle,
 } from "./daemon-state.ts";
-import { logEvent, vehicleLogger } from "./log.ts";
-import { createApp, createPapyrusService } from "./service.ts";
 
 /**
  * Operations that never change what a Task-graph reader (the pi-papyrus widget's

package/src/db.ts

@@ -2,8 +2,8 @@ import { mkdirSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname } from "node:path";
 import { runMigrations, type SqliteMigrationRunner } from "@danypops/vehicle-server/storage";
+import { generateUniqueAlias, slugify } from "./artifact/artifact-alias.ts";
 import { SQLITE_BUSY_TIMEOUT_MS, SQLITE_SCHEMA_VERSION } from "./constants.ts";
-import { generateUniqueAlias, slugify } from "./domain/artifact-alias.ts";
 
 const require_ = createRequire(import.meta.url);
 const IS_BUN = typeof (globalThis as { Bun?: unknown }).Bun !== "undefined";

package/src/{discussion-service.ts → discussion/discussion-service.ts}

@@ -3,9 +3,11 @@
  * append-only rounds (via DiscussionRoundStore). See domain/discussion.ts for the full
  * design rationale.
  */
-import { DISCUSSION_LIST_DEFAULT_LIMIT, DISCUSSION_LIST_MAX_LIMIT, DISCUSSION_MAX_ROUNDS } from "./constants.ts";
-import type { Artifact } from "./domain/artifact.ts";
-import type { ArtifactEventContext } from "./domain/artifact-event.ts";
+
+import type { Artifact } from "../artifact/artifact.ts";
+import type { ArtifactEventContext } from "../artifact/artifact-event.ts";
+import type { AtomicArtifactStore } from "../artifact/atomic-artifact-store.ts";
+import { DISCUSSION_LIST_DEFAULT_LIMIT, DISCUSSION_LIST_MAX_LIMIT, DISCUSSION_MAX_ROUNDS } from "../constants.ts";
 import {
 	DISCUSSION_SUBTYPE,
 	type DiscussionExtra,
@@ -19,9 +21,8 @@ import {
 	validateDiscussionOptions,
 	validateSelectedOptions,
 	validateSettlement,
-} from "./domain/discussion.ts";
-import type { AtomicArtifactStore } from "./ports/atomic-artifact-store.ts";
-import type { DiscussionRoundStore } from "./ports/discussion-round-store.ts";
+} from "../domain/discussion.ts";
+import type { DiscussionRoundStore } from "../stores/discussion-round-store.ts";
 
 export class DiscussionError extends Error {}
 

package/src/domain-services.ts

@@ -1,3 +1,7 @@
+import { type Artifact, requireLocallyOwnedContent } from "./artifact/artifact.ts";
+import type { ArtifactEventContext } from "./artifact/artifact-event.ts";
+import type { ArtifactScopeStore } from "./artifact/artifact-scope-store.ts";
+import type { ArtifactStore } from "./artifact/artifact-store.ts";
 import type { ArtifactAction, AuthorityRegistry } from "./authority-registry.ts";
 import {
 	ARTIFACT_BODY_MAX_LENGTH,
@@ -14,8 +18,6 @@ import {
 	RULE_TEXT_HARD_LIMIT_CHARACTERS,
 	SKILL_MAX_ENUM_VALUES,
 } from "./constants.ts";
-import { type Artifact, requireLocallyOwnedContent } from "./domain/artifact.ts";
-import type { ArtifactEventContext } from "./domain/artifact-event.ts";
 import {
 	BLUEPRINT_INPUT_TYPES,
 	type BlueprintArgumentValue,
@@ -23,9 +25,7 @@ import {
 	validateArgumentValue,
 } from "./domain/blueprint-definition.ts";
 import { normalizeProjectRoot } from "./domain/task-scope.ts";
-import { NOTE_SUBTYPE } from "./note-service.ts";
-import type { ArtifactScopeStore } from "./ports/artifact-scope-store.ts";
-import type { ArtifactStore } from "./ports/artifact-store.ts";
+import { NOTE_SUBTYPE } from "./note/note-service.ts";
 
 export interface UpdateContentInput {
 	title?: string;

package/src/{graph-projection-service.ts → graph-projection/graph-projection-service.ts}

@@ -4,16 +4,16 @@
  * documented, deliberate scope limits of this first walking-skeleton slice.
  */
 
-import type { AuthorityRegistry } from "./authority-registry.ts";
+import type { ArtifactStore } from "../artifact/artifact-store.ts";
+import { requireAtomicArtifactStore } from "../artifact/atomic-artifact-store.ts";
+import type { AuthorityRegistry } from "../authority-registry.ts";
 import {
 	GRAPH_PROJECTION_ID_MAX_LENGTH,
 	GRAPH_PROJECTION_MAX_ARTIFACTS_PER_BATCH,
 	GRAPH_PROJECTION_MAX_EDGES_PER_BATCH,
-} from "./constants.ts";
-import { GRAPH_PROJECTION_SCHEMA_VERSION, type GraphProjectionBatch, type GraphProjectionResult } from "./domain/graph-projection.ts";
-import type { ArtifactStore } from "./ports/artifact-store.ts";
-import { requireAtomicArtifactStore } from "./ports/atomic-artifact-store.ts";
-import type { GraphProjectionStore } from "./ports/graph-projection-store.ts";
+} from "../constants.ts";
+import { GRAPH_PROJECTION_SCHEMA_VERSION, type GraphProjectionBatch, type GraphProjectionResult } from "../domain/graph-projection.ts";
+import type { GraphProjectionStore } from "../stores/graph-projection-store.ts";
 
 function boundedId(value: string, label: string): string {
 	if (!value || value.length === 0) throw new Error(`${label} is required`);

package/src/{vehicle/artifact-trash-vehicle.ts → handlers/artifact-trash.ts}

@@ -5,10 +5,10 @@
  */
 import { bindVehicleOperation, defineVehicleOperation } from "@danypops/vehicle-core";
 import type { VehicleRegistry } from "@danypops/vehicle-server";
-import { removeArtifactSubtree } from "../artifact-subtree.ts";
-import type { ArtifactStore } from "../ports/artifact-store.ts";
-import type { ArtifactTrashStore } from "../ports/artifact-trash-store.ts";
-import { looseObjectSchema, numberProp, passthroughOutput, stringProp, validationError } from "./artifact-vehicle-shared.ts";
+import type { ArtifactStore } from "../artifact/artifact-store.ts";
+import { removeArtifactSubtree } from "../artifact/artifact-subtree.ts";
+import type { ArtifactTrashStore } from "../artifact/artifact-trash-store.ts";
+import { looseObjectSchema, numberProp, passthroughOutput, stringProp, validationError } from "./shared.ts";
 
 const OWNER = "artifact";
 const LIMITS = { defaultTimeoutMs: 5_000, maxTimeoutMs: 30_000, maxRequestBytes: 65_536, maxResponseBytes: 262_144 };

package/src/{vehicle/discuss-vehicle.ts → handlers/discuss.ts}

@@ -13,24 +13,23 @@
  * (service.ts's moduleRegistry) stays registered unchanged for pi-papyrus's
  * own /discuss TUI, which never went through the retired mega-tool.
  */
-import { bindVehicleOperation, defineVehicleOperation, type VehicleContentBlock } from "@danypops/vehicle-core";
+import type { VehicleContentBlock } from "@danypops/vehicle-core";
 import type { VehicleRegistry } from "@danypops/vehicle-server";
-import type { DiscussionAndRounds, Discussions } from "../discussion-service.ts";
-import type { Artifact } from "../domain/artifact.ts";
+import type { Artifact } from "../artifact/artifact.ts";
+import type { ArtifactStore } from "../artifact/artifact-store.ts";
+import type { DiscussionAndRounds, Discussions } from "../discussion/discussion-service.ts";
 import { DISCUSSION_SUBTYPE, type DiscussionRound } from "../domain/discussion.ts";
 import { discussOperations } from "../modules/discuss.ts";
-import type { ArtifactStore } from "../ports/artifact-store.ts";
 import {
-	looseObjectSchema,
+	createOperationDefiner,
 	numberProp,
-	passthroughOutput,
+	type OperationSchemaProperties,
 	resolveArtifactIdWidened,
 	stringProp,
 	validationError,
-} from "./artifact-vehicle-shared.ts";
+} from "./shared.ts";
 
 const OWNER = "discuss";
-const LIMITS = { defaultTimeoutMs: 5_000, maxTimeoutMs: 30_000, maxRequestBytes: 65_536, maxResponseBytes: 262_144 };
 const arrayProp = { type: "array" } as const;
 /** Purely a client-side hint (see vehicle-client-pi's interactiveFollowUps) -- never read server-side, but must still be declared or the schema's additionalProperties:false rejects it outright. */
 const boolProp = { type: "boolean" } as const;
@@ -122,34 +121,30 @@ const optionsUnionSchema = { type: "array" } as const;
 export function registerDiscussVehicleOperations(registry: VehicleRegistry, discussions: Discussions, artifacts: ArtifactStore): void {
 	const moduleOperations = new Map(discussOperations(discussions).map((op) => [op.name, op]));
 	const call = <Output>(name: string, input: Record<string, unknown>): Output => moduleOperations.get(name)!.execute(input) as Output;
+	const baseDefine = createOperationDefiner(registry, OWNER, "discuss", ["discuss:read", "discuss:write"], call);
 
+	/**
+	 * Defensively shallow-copies context.input before handing it to resolve() -- unlike every
+	 * other domain's resolve, discuss's own (normalizeOptions, defaultActorToAgent) mutate their
+	 * argument in place, and context.input must never be the object that mutation lands on.
+	 */
 	const define = (
 		action: string,
 		description: string,
 		effect: "read" | "local-write",
-		properties: Record<string, { type: string; enum?: readonly string[] }>,
+		properties: OperationSchemaProperties,
 		required: readonly string[],
 		resolve: (input: Record<string, unknown>) => Record<string, unknown>,
 		wrap: (raw: unknown, resolvedInput: Record<string, unknown>) => unknown = (raw) => raw,
 	): void => {
-		const operation = defineVehicleOperation({
-			name: `discuss.${action}`,
-			version: 1,
+		baseDefine(
+			action,
 			description,
-			input: looseObjectSchema(properties, required),
-			output: passthroughOutput,
-			permissions: ["discuss:read", "discuss:write"],
 			effect,
-			idempotency: { mode: effect === "read" ? "safe" : "unsafe" },
-			limits: LIMITS,
-		});
-		registry.register(
-			OWNER,
-			bindVehicleOperation(operation, () => async (context) => {
-				const resolvedInput = resolve({ ...(context.input as Record<string, unknown>) });
-				const raw = call(`discuss.${action}`, resolvedInput);
-				return wrap(raw, resolvedInput);
-			}),
+			properties,
+			required,
+			(input) => resolve({ ...input }),
+			(resolvedInput) => wrap(call(`discuss.${action}`, resolvedInput), resolvedInput),
 		);
 	};
 

package/src/{vehicle/docs-vehicle.ts → handlers/docs.ts}

@@ -3,24 +3,15 @@
  * Wraps modules/docs.ts's operation definitions. remove/restore/remove_subtree
  * are not duplicated here -- see ./artifact-trash-vehicle.ts.
  */
-import { bindVehicleOperation, defineVehicleOperation } from "@danypops/vehicle-core";
 import type { VehicleRegistry } from "@danypops/vehicle-server";
+import type { ArtifactScopeStore } from "../artifact/artifact-scope-store.ts";
+import type { ArtifactStore } from "../artifact/artifact-store.ts";
 import type { AuthorityRegistry } from "../authority-registry.ts";
 import { listDocuments } from "../domain-services.ts";
 import { docsOperations } from "../modules/docs.ts";
-import type { ArtifactScopeStore } from "../ports/artifact-scope-store.ts";
-import type { ArtifactStore } from "../ports/artifact-store.ts";
-import {
-	looseObjectSchema,
-	numberProp,
-	passthroughOutput,
-	resolveArtifactIdWidened,
-	stringProp,
-	validationError,
-} from "./artifact-vehicle-shared.ts";
+import { createOperationDefiner, numberProp, resolveArtifactIdWidened, stringProp, validationError } from "./shared.ts";
 
 const OWNER = "docs";
-const LIMITS = { defaultTimeoutMs: 5_000, maxTimeoutMs: 30_000, maxRequestBytes: 65_536, maxResponseBytes: 262_144 };
 
 function resolveDocId(
 	artifacts: ArtifactStore,
@@ -54,31 +45,7 @@ export function registerDocsVehicleOperations(
 ): void {
 	const moduleOperations = new Map(docsOperations(artifacts, scopes, authority).map((op) => [op.name, op]));
 	const call = (name: string, input: Record<string, unknown>): unknown => moduleOperations.get(name)!.execute(input);
-
-	const define = (
-		action: string,
-		description: string,
-		effect: "read" | "local-write",
-		properties: Record<string, { type: string; enum?: readonly string[] }>,
-		required: readonly string[],
-		resolve: (input: Record<string, unknown>) => Record<string, unknown>,
-	): void => {
-		const operation = defineVehicleOperation({
-			name: `docs.${action}`,
-			version: 1,
-			description,
-			input: looseObjectSchema(properties, required),
-			output: passthroughOutput,
-			permissions: ["docs:read", "docs:write"],
-			effect,
-			idempotency: { mode: effect === "read" ? "safe" : "unsafe" },
-			limits: LIMITS,
-		});
-		registry.register(
-			OWNER,
-			bindVehicleOperation(operation, () => async (context) => call(`docs.${action}`, resolve(context.input))),
-		);
-	};
+	const define = createOperationDefiner(registry, OWNER, "docs", ["docs:read", "docs:write"], call);
 
 	define(
 		"create",

package/src/{vehicle/notes-vehicle.ts → handlers/notes.ts}

@@ -7,24 +7,14 @@
  * input parsing. Resolves `name`/`target_name` to `id`/`target_id` server-side, in
  * the same call -- avoids a separate round trip per name before the real call.
  */
-import { bindVehicleOperation, defineVehicleOperation } from "@danypops/vehicle-core";
 import type { VehicleRegistry } from "@danypops/vehicle-server";
+import type { ArtifactStore } from "../artifact/artifact-store.ts";
 import { notesOperations } from "../modules/notes.ts";
-import { NOTE_DISPOSITIONS, type Notes } from "../note-service.ts";
-import type { ArtifactStore } from "../ports/artifact-store.ts";
-import {
-	looseObjectSchema,
-	numberProp,
-	passthroughOutput,
-	resolveArtifactIdWidened,
-	stringProp,
-	validationError,
-} from "./artifact-vehicle-shared.ts";
+import { NOTE_DISPOSITIONS, type Notes } from "../note/note-service.ts";
+import { createOperationDefiner, numberProp, resolveArtifactIdWidened, stringProp, validationError } from "./shared.ts";
 
 const OWNER = "notes";
 
-const LIMITS = { defaultTimeoutMs: 5_000, maxTimeoutMs: 30_000, maxRequestBytes: 65_536, maxResponseBytes: 262_144 };
-
 /** Resolves a note's id from either an explicit id or its title within projectRoot. */
 function resolveNoteId(artifacts: ArtifactStore, notes: Notes, projectRoot: string, id: unknown, name: unknown): string {
 	if (typeof id === "string" && id.length > 0) return id;
@@ -50,31 +40,7 @@ function resolveArtifactId(artifacts: ArtifactStore, id: unknown, name: unknown)
 export function registerNotesVehicleOperations(registry: VehicleRegistry, notes: Notes, artifacts: ArtifactStore): void {
 	const moduleOperations = new Map(notesOperations(notes).map((op) => [op.name, op]));
 	const call = (name: string, input: Record<string, unknown>): unknown => moduleOperations.get(name)!.execute(input);
-
-	const define = (
-		action: string,
-		description: string,
-		effect: "read" | "local-write",
-		properties: Record<string, { type: string; enum?: readonly string[] }>,
-		required: readonly string[],
-		resolve: (input: Record<string, unknown>) => Record<string, unknown>,
-	): void => {
-		const operation = defineVehicleOperation({
-			name: `notes.${action}`,
-			version: 1,
-			description,
-			input: looseObjectSchema(properties, required),
-			output: passthroughOutput,
-			permissions: ["notes:read", "notes:write"],
-			effect,
-			idempotency: { mode: effect === "read" ? "safe" : "unsafe" },
-			limits: LIMITS,
-		});
-		registry.register(
-			OWNER,
-			bindVehicleOperation(operation, () => async (context) => call(`notes.${action}`, resolve(context.input))),
-		);
-	};
+	const define = createOperationDefiner(registry, OWNER, "notes", ["notes:read", "notes:write"], call);
 
 	define(
 		"capture",

package/src/{vehicle/playbooks-vehicle.ts → handlers/playbooks.ts}

@@ -9,7 +9,7 @@
  * Those two fields never belong in this operation's model-visible inputSchema -- a model
  * has no business knowing or supplying a session secret. Instead they travel through
  * VehicleInvocationOptions.principal.claims, populated by pi-papyrus's own
- * resolveInvocation hook (see vehicle-notes-client.ts) from its own already-cached
+ * resolveInvocation hook (see pi-papyrus's tools/vehicle-notes-client.ts) from its own already-cached
  * session_secret, the same value the hand-rolled tool used to thread through as a raw
  * input field. A caller with no cached secret for this session (unregistered, or a non-Pi
  * Vehicle client) simply gets the guard's own no-op-when-unset default, unchanged.
@@ -18,33 +18,31 @@
  * WithVehicleContent) built from the same execution-DAG summary pi-papyrus's hand-rolled
  * tool used to build client-side.
  */
-import { bindVehicleOperation, defineVehicleOperation, type VehicleOperationContext } from "@danypops/vehicle-core";
 import type { VehicleRegistry } from "@danypops/vehicle-server";
+import type { ArtifactScopeStore } from "../artifact/artifact-scope-store.ts";
+import type { ArtifactStore } from "../artifact/artifact-store.ts";
 import { listPlaybooks } from "../domain-services.ts";
 import { playbooksOperations } from "../modules/playbooks.ts";
-import type { PlaybookInvocationResult, PlaybookMissingArguments } from "../playbook-execution.ts";
-import type { ArtifactScopeStore } from "../ports/artifact-scope-store.ts";
-import type { ArtifactStore } from "../ports/artifact-store.ts";
-import type { TaskEventStore } from "../ports/task-event-store.ts";
-import type { TaskScopeStore } from "../ports/task-scope-store.ts";
-import type { SessionIdentity } from "../session-identity-service.ts";
-import type { Tasks } from "../task-service.ts";
+import type { PlaybookInvocationResult, PlaybookMissingArguments } from "../playbook/playbook-execution.ts";
+import type { SessionIdentity } from "../session-identity/session-identity-service.ts";
+import type { TaskEventStore } from "../stores/task-event-store.ts";
+import type { TaskScopeStore } from "../stores/task-scope-store.ts";
+import type { Tasks } from "../task/task-service.ts";
 import {
 	buildWorkflowRunContent,
 	classifyPlaybookComposition,
 	classifySessionAuthorization,
 	classifyTaskExecutionBounds,
-	looseObjectSchema,
+	createOperationDefiner,
+	definePairedMutation,
 	normalizeJsonEncodedField,
 	numberProp,
-	passthroughOutput,
 	resolveArtifactIdWidened,
 	stringProp,
 	validationError,
-} from "./artifact-vehicle-shared.ts";
+} from "./shared.ts";
 
 const OWNER = "playbooks";
-const LIMITS = { defaultTimeoutMs: 5_000, maxTimeoutMs: 30_000, maxRequestBytes: 65_536, maxResponseBytes: 262_144 };
 
 export interface PlaybooksVehicleDeps {
 	artifacts: ArtifactStore;
@@ -70,7 +68,7 @@ export function registerPlaybooksVehicleOperations(registry: VehicleRegistry, de
 	/**
 	 * Every playbooks.* action funnels through here. invoke's own module handler re-runs
 	 * sessionIdentity.assertAuthorized directly (see this file's own doc comment) and its
-	 * blueprint-materialization engine (workflow-execution.ts) can hit the same execution-graph
+	 * blueprint-materialization engine (playbook/workflow-execution.ts) can hit the same execution-graph
 	 * bounds tasks-vehicle.ts's own operations do -- classifying both reviewed domain error classes
 	 * at this one choke point covers every action that can throw them. Anything else propagates
 	 * unchanged -- vehicle-registry's own secure-by-default handler-failed opacity still applies to a
@@ -80,36 +78,7 @@ export function registerPlaybooksVehicleOperations(registry: VehicleRegistry, de
 		classifySessionAuthorization(() =>
 			classifyTaskExecutionBounds(() => classifyPlaybookComposition(() => moduleOperations.get(name)!.execute(input))),
 		);
-
-	const define = (
-		action: string,
-		description: string,
-		effect: "read" | "local-write",
-		properties: Record<string, { type: string; enum?: readonly string[] }>,
-		required: readonly string[],
-		resolve: (input: Record<string, unknown>) => Record<string, unknown>,
-		execute?: (input: Record<string, unknown>, context: VehicleOperationContext<Record<string, unknown>>) => unknown,
-	): void => {
-		const operation = defineVehicleOperation({
-			name: `playbooks.${action}`,
-			version: 1,
-			description,
-			input: looseObjectSchema(properties, required),
-			output: passthroughOutput,
-			permissions: ["playbooks:read", "playbooks:write"],
-			effect,
-			idempotency: { mode: effect === "read" ? "safe" : "unsafe" },
-			limits: LIMITS,
-		});
-		registry.register(
-			OWNER,
-			bindVehicleOperation(
-				operation,
-				() => async (context) =>
-					(execute ?? ((input: Record<string, unknown>) => call(`playbooks.${action}`, input)))(resolve(context.input), context),
-			),
-		);
-	};
+	const define = createOperationDefiner(registry, OWNER, "playbooks", ["playbooks:read", "playbooks:write"], call);
 
 	define(
 		"create",
@@ -242,10 +211,13 @@ export function registerPlaybooksVehicleOperations(registry: VehicleRegistry, de
 		(input) => ({ ...input, id: resolvePlaybookId(artifacts, artifactScopes, input.id, input.name) }),
 	);
 
-	define(
-		"contain",
-		"Nests a child Playbook inside a parent -- the child's steps run AFTER the parent's own. Prefer parent_name/child_name over parent_id/child_id -- resolved server-side.",
-		"local-write",
+	const resolvePlaybookIdField = (input: Record<string, unknown>, idProp: string, nameProp: string): string =>
+		resolvePlaybookId(artifacts, artifactScopes, input[idProp], input[nameProp]);
+
+	definePairedMutation(
+		define,
+		{ idProp: "parent_id", nameProp: "parent_name" },
+		{ idProp: "child_id", nameProp: "child_name" },
 		{
 			parent_id: stringProp,
 			parent_name: stringProp,
@@ -256,38 +228,19 @@ export function registerPlaybooksVehicleOperations(registry: VehicleRegistry, de
 			session_id: stringProp,
 		},
 		[],
-		(input) => ({
-			...input,
-			parent_id: resolvePlaybookId(artifacts, artifactScopes, input.parent_id, input.parent_name),
-			child_id: resolvePlaybookId(artifacts, artifactScopes, input.child_id, input.child_name),
-		}),
-	);
-
-	define(
-		"uncontain",
-		"Removes a parent/child Playbook nesting. Idempotent -- a no-op if the edge is already absent.",
-		"local-write",
+		resolvePlaybookIdField,
 		{
-			parent_id: stringProp,
-			parent_name: stringProp,
-			child_id: stringProp,
-			child_name: stringProp,
-			actor: stringProp,
-			source: stringProp,
-			session_id: stringProp,
+			action: "contain",
+			description:
+				"Nests a child Playbook inside a parent -- the child's steps run AFTER the parent's own. Prefer parent_name/child_name over parent_id/child_id -- resolved server-side.",
 		},
-		[],
-		(input) => ({
-			...input,
-			parent_id: resolvePlaybookId(artifacts, artifactScopes, input.parent_id, input.parent_name),
-			child_id: resolvePlaybookId(artifacts, artifactScopes, input.child_id, input.child_name),
-		}),
+		{ action: "uncontain", description: "Removes a parent/child Playbook nesting. Idempotent -- a no-op if the edge is already absent." },
 	);
 
-	define(
-		"depend",
-		"Chains a prerequisite Playbook before another -- it must fully complete FIRST. Prefer dependency_name over dependency_id.",
-		"local-write",
+	definePairedMutation(
+		define,
+		{ idProp: "id", nameProp: "name" },
+		{ idProp: "dependency_id", nameProp: "dependency_name" },
 		{
 			id: stringProp,
 			name: stringProp,
@@ -298,31 +251,12 @@ export function registerPlaybooksVehicleOperations(registry: VehicleRegistry, de
 			session_id: stringProp,
 		},
 		[],
-		(input) => ({
-			...input,
-			id: resolvePlaybookId(artifacts, artifactScopes, input.id, input.name),
-			dependency_id: resolvePlaybookId(artifacts, artifactScopes, input.dependency_id, input.dependency_name),
-		}),
-	);
-
-	define(
-		"undepend",
-		"Removes a Playbook dependency. Idempotent -- a no-op if the edge is already absent.",
-		"local-write",
+		resolvePlaybookIdField,
 		{
-			id: stringProp,
-			name: stringProp,
-			dependency_id: stringProp,
-			dependency_name: stringProp,
-			actor: stringProp,
-			source: stringProp,
-			session_id: stringProp,
+			action: "depend",
+			description:
+				"Chains a prerequisite Playbook before another -- it must fully complete FIRST. Prefer dependency_name over dependency_id.",
 		},
-		[],
-		(input) => ({
-			...input,
-			id: resolvePlaybookId(artifacts, artifactScopes, input.id, input.name),
-			dependency_id: resolvePlaybookId(artifacts, artifactScopes, input.dependency_id, input.dependency_name),
-		}),
+		{ action: "undepend", description: "Removes a Playbook dependency. Idempotent -- a no-op if the edge is already absent." },
 	);
 }

package/src/{vehicle/papyrus-vehicle.ts → handlers/registry.ts}

@@ -6,23 +6,23 @@
  * per domain.
  */
 import { VehicleRegistry } from "@danypops/vehicle-server";
+import type { ArtifactScopeStore } from "../artifact/artifact-scope-store.ts";
+import type { ArtifactStore } from "../artifact/artifact-store.ts";
+import type { ArtifactTrashStore } from "../artifact/artifact-trash-store.ts";
 import type { AuthorityRegistry } from "../authority-registry.ts";
-import type { Discussions } from "../discussion-service.ts";
-import type { Notes } from "../note-service.ts";
-import type { ArtifactScopeStore } from "../ports/artifact-scope-store.ts";
-import type { ArtifactStore } from "../ports/artifact-store.ts";
-import type { ArtifactTrashStore } from "../ports/artifact-trash-store.ts";
-import type { TaskEventStore } from "../ports/task-event-store.ts";
-import type { TaskScopeStore } from "../ports/task-scope-store.ts";
-import type { SessionIdentity } from "../session-identity-service.ts";
-import type { Tasks } from "../task-service.ts";
-import { registerArtifactTrashOperations } from "./artifact-trash-vehicle.ts";
-import { registerDiscussVehicleOperations } from "./discuss-vehicle.ts";
-import { registerDocsVehicleOperations } from "./docs-vehicle.ts";
-import { registerNotesVehicleOperations } from "./notes-vehicle.ts";
-import { registerPlaybooksVehicleOperations } from "./playbooks-vehicle.ts";
-import { registerRulesVehicleOperations } from "./rules-vehicle.ts";
-import { registerTasksVehicleOperations } from "./tasks-vehicle.ts";
+import type { Discussions } from "../discussion/discussion-service.ts";
+import type { Notes } from "../note/note-service.ts";
+import type { SessionIdentity } from "../session-identity/session-identity-service.ts";
+import type { TaskEventStore } from "../stores/task-event-store.ts";
+import type { TaskScopeStore } from "../stores/task-scope-store.ts";
+import type { Tasks } from "../task/task-service.ts";
+import { registerArtifactTrashOperations } from "./artifact-trash.ts";
+import { registerDiscussVehicleOperations } from "./discuss.ts";
+import { registerDocsVehicleOperations } from "./docs.ts";
+import { registerNotesVehicleOperations } from "./notes.ts";
+import { registerPlaybooksVehicleOperations } from "./playbooks.ts";
+import { registerRulesVehicleOperations } from "./rules.ts";
+import { registerTasksVehicleOperations } from "./tasks.ts";
 
 export interface PapyrusVehicleDeps {
 	artifacts: ArtifactStore & ArtifactTrashStore;