@danypops/papyrus 0.44.9 → 0.44.11

package/src/handlers/discuss.ts

@@ -13,17 +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 { 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 { looseObjectSchema, numberProp, passthroughOutput, resolveArtifactIdWidened, stringProp, validationError } from "./shared.ts";
+import {
+	createOperationDefiner,
+	numberProp,
+	type OperationSchemaProperties,
+	resolveArtifactIdWidened,
+	stringProp,
+	validationError,
+} 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;
@@ -115,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/handlers/docs.ts

@@ -3,17 +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 { looseObjectSchema, numberProp, passthroughOutput, resolveArtifactIdWidened, stringProp, validationError } from "./shared.ts";
+import { booleanProp, 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,
@@ -47,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",
@@ -92,9 +66,9 @@ export function registerDocsVehicleOperations(
 
 	define(
 		"list",
-		"Lists Docs matching an optional status/text filter, scoped to project_root when given.",
+		"Lists Docs matching an optional status/text filter, scoped to project_root when given. Returns a lean summary (no body) by default -- pass full: true for the complete artifact.",
 		"read",
-		{ status: stringProp, text: stringProp, limit: numberProp, project_root: stringProp },
+		{ status: stringProp, text: stringProp, limit: numberProp, project_root: stringProp, full: booleanProp },
 		[],
 		(input) => input,
 	);

package/src/handlers/notes.ts

@@ -7,17 +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/note-service.ts";
-import { looseObjectSchema, numberProp, passthroughOutput, resolveArtifactIdWidened, stringProp, validationError } from "./shared.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;
@@ -43,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/handlers/playbooks.ts

@@ -18,7 +18,6 @@
  * 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";
@@ -30,21 +29,21 @@ 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 {
+	booleanProp,
 	buildWorkflowRunContent,
 	classifyPlaybookComposition,
 	classifySessionAuthorization,
 	classifyTaskExecutionBounds,
-	looseObjectSchema,
+	createOperationDefiner,
+	definePairedMutation,
 	normalizeJsonEncodedField,
 	numberProp,
-	passthroughOutput,
 	resolveArtifactIdWidened,
 	stringProp,
 	validationError,
 } 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;
@@ -80,36 +79,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",
@@ -138,9 +108,9 @@ export function registerPlaybooksVehicleOperations(registry: VehicleRegistry, de
 
 	define(
 		"list",
-		"Lists Playbooks matching an optional status/text filter, scoped to project_root when given.",
+		"Lists Playbooks matching an optional status/text filter, scoped to project_root when given. Returns a lean summary (no body/steps) by default -- pass full: true for the complete artifact.",
 		"read",
-		{ status: stringProp, text: stringProp, limit: numberProp, project_root: stringProp },
+		{ status: stringProp, text: stringProp, limit: numberProp, project_root: stringProp, full: booleanProp },
 		[],
 		(input) => input,
 	);
@@ -242,10 +212,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 +229,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 +252,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/handlers/rules.ts

@@ -4,16 +4,14 @@
  * composition-root-only concern, absent here too). 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 { listRules } from "../domain-services.ts";
 import { rulesOperations } from "../modules/rules.ts";
-import { looseObjectSchema, numberProp, passthroughOutput, resolveArtifactIdWidened, stringProp, validationError } from "./shared.ts";
+import { booleanProp, createOperationDefiner, numberProp, resolveArtifactIdWidened, stringProp, validationError } from "./shared.ts";
 
 const OWNER = "rules";
-const LIMITS = { defaultTimeoutMs: 5_000, maxTimeoutMs: 30_000, maxRequestBytes: 65_536, maxResponseBytes: 262_144 };
 
 /** Resolves a rule's id from either an explicit id or its title, widened past project_root when unscoped-vs-scoped search finds nothing. */
 function resolveRuleId(
@@ -47,31 +45,7 @@ function resolveTaskId(artifacts: ArtifactStore, _projectRoot: string | undefine
 export function registerRulesVehicleOperations(registry: VehicleRegistry, artifacts: ArtifactStore, scopes: ArtifactScopeStore): void {
 	const moduleOperations = new Map(rulesOperations(artifacts, scopes).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: `rules.${action}`,
-			version: 1,
-			description,
-			input: looseObjectSchema(properties, required),
-			output: passthroughOutput,
-			permissions: ["rules:read", "rules:write"],
-			effect,
-			idempotency: { mode: effect === "read" ? "safe" : "unsafe" },
-			limits: LIMITS,
-		});
-		registry.register(
-			OWNER,
-			bindVehicleOperation(operation, () => async (context) => call(`rules.${action}`, resolve(context.input))),
-		);
-	};
+	const define = createOperationDefiner(registry, OWNER, "rules", ["rules:read", "rules:write"], call);
 
 	define(
 		"create",
@@ -96,9 +70,9 @@ export function registerRulesVehicleOperations(registry: VehicleRegistry, artifa
 
 	define(
 		"list",
-		"Lists Rules matching an optional status/text filter, scoped to project_root when given.",
+		"Lists Rules matching an optional status/text filter, scoped to project_root when given. Returns a lean summary (no condition/action/body) by default -- pass full: true for the complete artifact.",
 		"read",
-		{ status: stringProp, text: stringProp, limit: numberProp, project_root: stringProp },
+		{ status: stringProp, text: stringProp, limit: numberProp, project_root: stringProp, full: booleanProp },
 		[],
 		(input) => input,
 	);

package/src/handlers/shared.ts

@@ -3,7 +3,16 @@
  * VehicleRegistry projection (notes-vehicle.ts, rules-vehicle.ts, docs-vehicle.ts,
  * artifact-trash-vehicle.ts).
  */
-import { defineVehicleSchema, type VehicleContentBlock, VehicleError, type VehicleSchemaCodec } from "@danypops/vehicle-core";
+import {
+	bindVehicleOperation,
+	defineVehicleOperation,
+	defineVehicleSchema,
+	type VehicleContentBlock,
+	VehicleError,
+	type VehicleOperationContext,
+	type VehicleSchemaCodec,
+} from "@danypops/vehicle-core";
+import type { VehicleRegistry } from "@danypops/vehicle-server";
 import type { Artifact } from "../artifact/artifact.ts";
 import type { ArtifactStore } from "../artifact/artifact-store.ts";
 import { PlaybookCompositionError } from "../playbook/playbook-definition.ts";
@@ -48,6 +57,7 @@ export const passthroughOutput: VehicleSchemaCodec<unknown> = defineVehicleSchem
 
 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
@@ -223,3 +233,84 @@ export function buildWorkflowRunContent(
 	].join("\n");
 	return { type: "text", text };
 }
+
+export type OperationSchemaProperties = Record<string, { type: string; enum?: readonly string[] }>;
+
+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,
+) => 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) => {
+		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: 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);
+}