@danypops/papyrus 0.44.8 → 0.44.10

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

@@ -4,23 +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 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 = "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(
@@ -54,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",

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

@@ -3,12 +3,21 @@
  * 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 type { Artifact } from "../domain/artifact.ts";
-import { PlaybookCompositionError } from "../playbook-definition.ts";
-import type { ArtifactStore } from "../ports/artifact-store.ts";
-import { InvalidSessionSecretError } from "../session-identity-service.ts";
-import { TaskDependencyCycleError, TaskExecutionBoundExceededError, type TaskExecutionPlan } from "../task-execution.ts";
+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";
+import { InvalidSessionSecretError } from "../session-identity/session-identity-service.ts";
+import { TaskDependencyCycleError, TaskExecutionBoundExceededError, type TaskExecutionPlan } from "../task/task-execution.ts";
 
 /**
  * VehicleRegistry only ever calls a schema's own safeParse -- jsonSchema is
@@ -223,3 +232,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);
+}

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

@@ -10,7 +10,7 @@
  *  - session_secret authorizes which session's Task Focus row gets mutated
  *    (modules/tasks.ts's own guardFocusMutation). It must never be a model-visible
  *    input field -- it travels through VehicleInvocationOptions.principal.claims,
- *    the same mechanism playbooks.invoke uses (see vehicle-notes-client.ts).
+ *    the same mechanism playbooks.invoke uses (see pi-papyrus's tools/vehicle-notes-client.ts).
  *  - papyrus.task-focus.v1 is a same-process Pi extension event bus broadcast (a
  *    token-cost router or similar can correlate its own telemetry with the
  *    currently focused task) with no Vehicle-transport equivalent -- fired from
@@ -19,26 +19,25 @@
  *
  * remove/remove_subtree/restore are not duplicated here -- see ./artifact-trash-vehicle.ts.
  */
-import { bindVehicleOperation, defineVehicleOperation, type VehicleOperationContext } from "@danypops/vehicle-core";
 import type { VehicleRegistry } from "@danypops/vehicle-server";
+import type { ArtifactStore } from "../artifact/artifact-store.ts";
 import type { TaskViewMode } from "../domain/task-scope.ts";
 import { tasksOperations } from "../modules/tasks.ts";
-import type { ArtifactStore } from "../ports/artifact-store.ts";
-import type { SessionIdentity } from "../session-identity-service.ts";
-import type { TaskExecutionPlan } from "../task-execution.ts";
-import type { TaskCompletion, Tasks } from "../task-service.ts";
+import type { SessionIdentity } from "../session-identity/session-identity-service.ts";
+import type { TaskExecutionPlan } from "../task/task-execution.ts";
+import type { TaskCompletion, Tasks } from "../task/task-service.ts";
 import {
 	classifySessionAuthorization,
 	classifyTaskDependencyCycles,
 	classifyTaskExecutionBounds,
+	createOperationDefiner,
+	definePairedMutation,
 	labelsById,
-	looseObjectSchema,
 	numberProp,
-	passthroughOutput,
 	resolveArtifactIdWidened,
 	stringProp,
 	validationError,
-} from "./artifact-vehicle-shared.ts";
+} from "./shared.ts";
 
 const OWNER = "tasks";
 const LIMITS = { defaultTimeoutMs: 5_000, maxTimeoutMs: 30_000, maxRequestBytes: 65_536, maxResponseBytes: 262_144 };
@@ -167,36 +166,7 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 		classifySessionAuthorization(() =>
 			classifyTaskExecutionBounds(() => classifyTaskDependencyCycles(() => 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: `tasks.${action}`,
-			version: 1,
-			description,
-			input: looseObjectSchema(properties, required),
-			output: passthroughOutput,
-			permissions: ["tasks:read", "tasks:write"],
-			effect,
-			idempotency: { mode: effect === "read" ? "safe" : "unsafe" },
-			limits: LIMITS,
-		});
-		registry.register(
-			OWNER,
-			bindVehicleOperation(
-				operation,
-				() => async (context) =>
-					(execute ?? ((input: Record<string, unknown>) => call(`tasks.${action}`, input)))(resolve(context.input), context),
-			),
-		);
-	};
+	const define = createOperationDefiner(registry, OWNER, "tasks", ["tasks:read", "tasks:write"], call);
 
 	/** Shared by every action taking a single id/name: resolves root_task_name first, then name -> id against the final scope. */
 	const resolveIdAndScope = (input: Record<string, unknown>): Record<string, unknown> => {
@@ -395,6 +365,7 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 		(input) => input,
 	);
 
+	/** Injects the caller's own session claims (never a model-visible input field) onto every focus/pause/unpause/clear_focus call -- see this file's own doc comment. */
 	const focusOperation = (
 		action: "focus" | "pause" | "unpause" | "clear_focus",
 		description: string,
@@ -402,24 +373,10 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 		required: readonly string[],
 		resolve: (input: Record<string, unknown>) => Record<string, unknown>,
 	): void => {
-		const operation = defineVehicleOperation({
-			name: `tasks.${action}`,
-			version: 1,
-			description,
-			input: looseObjectSchema(properties, required),
-			output: passthroughOutput,
-			permissions: ["tasks:read", "tasks:write"],
-			effect: "local-write",
-			idempotency: { mode: "unsafe" },
-			limits: LIMITS,
+		define(action, description, "local-write", properties, required, resolve, (resolvedInput, context) => {
+			const claims = context.principal?.claims as { sessionId?: string; sessionSecret?: string } | undefined;
+			return call(`tasks.${action}`, { ...resolvedInput, session_id: claims?.sessionId, session_secret: claims?.sessionSecret });
 		});
-		registry.register(
-			OWNER,
-			bindVehicleOperation(operation, () => async (context) => {
-				const claims = context.principal?.claims as { sessionId?: string; sessionSecret?: string } | undefined;
-				return call(`tasks.${action}`, { ...resolve(context.input), session_id: claims?.sessionId, session_secret: claims?.sessionSecret });
-			}),
-		);
 	};
 
 	focusOperation(
@@ -585,34 +542,16 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 
 	const scopeProp = { type: "string", enum: ["project", "graph", "all"] } as const;
 
-	define(
-		"depend",
-		"Adds a dependency edge (this task waits for dependency_id/dependency_name). Dependency edges form an executable DAG -- self-dependencies and cycles are rejected. A name resolved outside project_root's own scope is retried once against every project before failing, unless scope is pinned explicitly.",
-		"local-write",
-		{
-			id: stringProp,
-			name: stringProp,
-			dependency_id: stringProp,
-			dependency_name: stringProp,
-			project_root: stringProp,
-			scope: scopeProp,
-			session_id: stringProp,
-		},
-		[],
-		(input) => {
-			const filter = { projectRoot: input.project_root as string | undefined, scope: input.scope as TaskViewMode | undefined };
-			return {
-				...input,
-				id: resolveTaskId(artifacts, tasks, filter, input.id, input.name),
-				dependency_id: resolveTaskId(artifacts, tasks, filter, input.dependency_id, input.dependency_name),
-			};
-		},
-	);
+	/** Resolves a task id/name pair against the filter derived from this same input's own project_root/scope -- shared by depend/undepend and contain/uncontain below. */
+	const resolveScopedTaskId = (input: Record<string, unknown>, idProp: string, nameProp: string): string => {
+		const filter = { projectRoot: input.project_root as string | undefined, scope: input.scope as TaskViewMode | undefined };
+		return resolveTaskId(artifacts, tasks, filter, input[idProp], input[nameProp]);
+	};
 
-	define(
-		"undepend",
-		"Removes a dependency edge. Idempotent -- a no-op if the edge is already absent.",
-		"local-write",
+	definePairedMutation(
+		define,
+		{ idProp: "id", nameProp: "name" },
+		{ idProp: "dependency_id", nameProp: "dependency_name" },
 		{
 			id: stringProp,
 			name: stringProp,
@@ -623,44 +562,19 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 			session_id: stringProp,
 		},
 		[],
-		(input) => {
-			const filter = { projectRoot: input.project_root as string | undefined, scope: input.scope as TaskViewMode | undefined };
-			return {
-				...input,
-				id: resolveTaskId(artifacts, tasks, filter, input.id, input.name),
-				dependency_id: resolveTaskId(artifacts, tasks, filter, input.dependency_id, input.dependency_name),
-			};
-		},
-	);
-
-	define(
-		"contain",
-		"Nests a child Task inside a parent (parent_id/parent_name contains child_id/child_name) -- explicit hierarchy, distinct from depends_on execution ordering. A name resolved outside project_root's own scope is retried once against every project before failing, unless scope is pinned explicitly.",
-		"local-write",
+		resolveScopedTaskId,
 		{
-			parent_id: stringProp,
-			parent_name: stringProp,
-			child_id: stringProp,
-			child_name: stringProp,
-			project_root: stringProp,
-			scope: scopeProp,
-			session_id: stringProp,
-		},
-		[],
-		(input) => {
-			const filter = { projectRoot: input.project_root as string | undefined, scope: input.scope as TaskViewMode | undefined };
-			return {
-				...input,
-				parent_id: resolveTaskId(artifacts, tasks, filter, input.parent_id, input.parent_name),
-				child_id: resolveTaskId(artifacts, tasks, filter, input.child_id, input.child_name),
-			};
+			action: "depend",
+			description:
+				"Adds a dependency edge (this task waits for dependency_id/dependency_name). Dependency edges form an executable DAG -- self-dependencies and cycles are rejected. A name resolved outside project_root's own scope is retried once against every project before failing, unless scope is pinned explicitly.",
 		},
+		{ action: "undepend", description: "Removes a dependency edge. Idempotent -- a no-op if the edge is already absent." },
 	);
 
-	define(
-		"uncontain",
-		"Removes a parent/child nesting. Idempotent -- a no-op if the edge is already absent.",
-		"local-write",
+	definePairedMutation(
+		define,
+		{ idProp: "parent_id", nameProp: "parent_name" },
+		{ idProp: "child_id", nameProp: "child_name" },
 		{
 			parent_id: stringProp,
 			parent_name: stringProp,
@@ -671,14 +585,13 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 			session_id: stringProp,
 		},
 		[],
-		(input) => {
-			const filter = { projectRoot: input.project_root as string | undefined, scope: input.scope as TaskViewMode | undefined };
-			return {
-				...input,
-				parent_id: resolveTaskId(artifacts, tasks, filter, input.parent_id, input.parent_name),
-				child_id: resolveTaskId(artifacts, tasks, filter, input.child_id, input.child_name),
-			};
+		resolveScopedTaskId,
+		{
+			action: "contain",
+			description:
+				"Nests a child Task inside a parent (parent_id/parent_name contains child_id/child_name) -- explicit hierarchy, distinct from depends_on execution ordering. A name resolved outside project_root's own scope is retried once against every project before failing, unless scope is pinned explicitly.",
 		},
+		{ action: "uncontain", description: "Removes a parent/child nesting. Idempotent -- a no-op if the edge is already absent." },
 	);
 
 	define(

package/src/index.ts

@@ -5,7 +5,9 @@
  * purposeful API, not "everything happens to be reachable."
  */
 
-export { projectArtifactRelationships } from "./artifact-relationship-view.ts";
+export type { Artifact, ArtifactEdge } from "./artifact/artifact.ts";
+export { projectArtifactRelationships } from "./artifact/artifact-relationship-view.ts";
+export type { ArtifactStore } from "./artifact/artifact-store.ts";
 export {
 	connectPapyrusClient,
 	type PapyrusClient,
@@ -15,8 +17,7 @@ export {
 	type VehicleClientTarget,
 } from "./client.ts";
 export * from "./constants.ts";
-export type { DiscussionAndRounds } from "./discussion-service.ts";
-export type { Artifact, ArtifactEdge } from "./domain/artifact.ts";
+export type { DiscussionAndRounds } from "./discussion/discussion-service.ts";
 export { checklistEntries, PROOF_TYPES, type ProofReference } from "./domain/checklist.ts";
 export { DISCUSSION_SUBTYPE, type DiscussionRound, readDiscussionExtra } from "./domain/discussion.ts";
 export type { DisplayGraph, DisplayGraphEdge, DisplayGraphNode, RenderedGraph } from "./domain/display-graph.ts";
@@ -25,14 +26,13 @@ export type { NoteHistoryPage } from "./domain/note-event.ts";
 export type { TaskEvent, TaskHistoryPage } from "./domain/task-event.ts";
 export type { TaskLease } from "./domain/task-lease.ts";
 export type { TaskViewSelection } from "./domain/task-scope.ts";
-export { NOTE_DISPOSITIONS } from "./note-service.ts";
-export type { PlaybookInvocationResult, PlaybookMissingArguments } from "./playbook-execution.ts";
-export type { ArtifactStore } from "./ports/artifact-store.ts";
-export type { GraphRenderer } from "./ports/graph-renderer.ts";
+export { NOTE_DISPOSITIONS } from "./note/note-service.ts";
+export type { PlaybookInvocationResult, PlaybookMissingArguments } from "./playbook/playbook-execution.ts";
+export type { WorkflowRunResult } from "./playbook/workflow-execution.ts";
 export type { OperationName, SchemaState } from "./service.ts";
-export { taskContext } from "./task-context.ts";
-export { projectTaskExecution, type TaskExecutionPlan, type TaskExecutionState } from "./task-execution.ts";
-export { projectTaskGraph, type TaskGraphView } from "./task-graph-view.ts";
-export { fallbackLabel, projectTaskRelationships } from "./task-relationship-view.ts";
-export type { TaskCompletion, TaskGraph, TaskNode, TaskStatus } from "./task-service.ts";
-export type { WorkflowRunResult } from "./workflow-execution.ts";
+export type { GraphRenderer } from "./stores/graph-renderer.ts";
+export { taskContext } from "./task/task-context.ts";
+export { projectTaskExecution, type TaskExecutionPlan, type TaskExecutionState } from "./task/task-execution.ts";
+export { projectTaskGraph, type TaskGraphView } from "./task/task-graph-view.ts";
+export { fallbackLabel, projectTaskRelationships } from "./task/task-relationship-view.ts";
+export type { TaskCompletion, TaskGraph, TaskNode, TaskStatus } from "./task/task-service.ts";

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

@@ -9,8 +9,8 @@ import {
 	type LogQuery,
 	meetsLevel,
 	validateAppendLogEntryCommand,
-} from "./domain/log-entry.ts";
-import type { LogStore } from "./ports/log-store.ts";
+} from "../domain/log-entry.ts";
+import type { LogStore } from "../stores/log-store.ts";
 
 export class Logs {
 	constructor(private readonly store: LogStore) {}

package/src/modules/discuss.ts

@@ -3,44 +3,23 @@
  * domain/discussion.ts and discussion-service.ts for the full design.
  */
 
-import type { Discussions } from "../discussion-service.ts";
-import type { ArtifactEventContext } from "../domain/artifact-event.ts";
+import type { ArtifactEventContext } from "../artifact/artifact-event.ts";
+import type { Discussions } from "../discussion/discussion-service.ts";
 import type { OperationDefinition } from "../module-registry.ts";
+import { type OperationInput, optionalNumber, optionalString, optionalStringArray } from "./operation-input.ts";
 
 const MODULE_ID = "discuss";
 
-type OperationInput = Record<string, unknown>;
-
-function string(input: OperationInput, key: string): string {
-	const value = input[key];
-	if (typeof value !== "string" || value.length === 0)
-		throw new Error(`${key} is required${REQUIRED_FIELD_HINTS[key] ? ` (${REQUIRED_FIELD_HINTS[key]})` : ""}`);
-	return value;
-}
-
 /** Fields whose name alone doesn't say what a valid value looks like -- everything else (title, content, id, settlement) is self-explanatory. */
 const REQUIRED_FIELD_HINTS: Record<string, string> = {
 	actor: 'a display name for who is posting, e.g. "alice" or "agent"',
 };
 
-function optionalString(input: OperationInput, key: string): string | undefined {
-	const value = input[key];
-	if (value === undefined) return undefined;
-	if (typeof value !== "string") throw new Error(`${key} must be a string`);
-	return value;
-}
-
-function optionalStringArray(input: OperationInput, key: string): string[] | undefined {
-	const value = input[key];
-	if (value === undefined) return undefined;
-	if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) throw new Error(`${key} must be an array of strings`);
-	return value as string[];
-}
-
-function optionalNumber(input: OperationInput, key: string): number | undefined {
+/** Same contract as the shared string() in ./operation-input.ts, plus a field-specific hint on failure -- discuss's own operations are the one surface where a bare "actor is required" isn't self-explanatory. */
+function string(input: OperationInput, key: string): string {
 	const value = input[key];
-	if (value === undefined) return undefined;
-	if (typeof value !== "number" || !Number.isFinite(value)) throw new Error(`${key} must be a number`);
+	if (typeof value !== "string" || value.length === 0)
+		throw new Error(`${key} is required${REQUIRED_FIELD_HINTS[key] ? ` (${REQUIRED_FIELD_HINTS[key]})` : ""}`);
 	return value;
 }
 

package/src/modules/docs.ts

@@ -6,6 +6,9 @@
  * Imports only src/domain-services.ts's Doc functions, which are already generic
  * ArtifactStore-based with no other module's concrete class dependency.
  */
+
+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 {
 	assignDocumentProject,
@@ -18,33 +21,10 @@ import {
 	updateDocument,
 } from "../domain-services.ts";
 import type { OperationDefinition } from "../module-registry.ts";
-import type { ArtifactScopeStore } from "../ports/artifact-scope-store.ts";
-import type { ArtifactStore } from "../ports/artifact-store.ts";
+import { type OperationInput, optionalNumber, optionalString, string } from "./operation-input.ts";
 
 const MODULE_ID = "docs";
 
-type OperationInput = Record<string, unknown>;
-
-function string(input: OperationInput, key: string): string {
-	const value = input[key];
-	if (typeof value !== "string" || value.length === 0) throw new Error(`${key} is required`);
-	return value;
-}
-
-function optionalString(input: OperationInput, key: string): string | undefined {
-	const value = input[key];
-	if (value === undefined) return undefined;
-	if (typeof value !== "string") throw new Error(`${key} must be a string`);
-	return value;
-}
-
-function optionalNumber(input: OperationInput, key: string): number | undefined {
-	const value = input[key];
-	if (value === undefined) return undefined;
-	if (typeof value !== "number" || !Number.isFinite(value)) throw new Error(`${key} must be a number`);
-	return value;
-}
-
 const eventContext = (input: OperationInput) => ({
 	actor: optionalString(input, "actor"),
 	source: optionalString(input, "source"),

package/src/modules/graph-projection.ts

@@ -5,6 +5,8 @@
  * src/domain/graph-projection.ts and src/graph-projection-service.ts for the protocol
  * itself; this file only parses/validates raw operation input into that typed shape.
  */
+
+import type { ArtifactStore } from "../artifact/artifact-store.ts";
 import type { AuthorityRegistry } from "../authority-registry.ts";
 import type {
 	GRAPH_PROJECTION_SCHEMA_VERSION,
@@ -12,21 +14,13 @@ import type {
 	ProjectedArtifact,
 	ProjectedEdge,
 } from "../domain/graph-projection.ts";
-import { GraphProjection } from "../graph-projection-service.ts";
+import { GraphProjection } from "../graph-projection/graph-projection-service.ts";
 import type { OperationDefinition } from "../module-registry.ts";
-import type { ArtifactStore } from "../ports/artifact-store.ts";
-import type { GraphProjectionStore } from "../ports/graph-projection-store.ts";
+import type { GraphProjectionStore } from "../stores/graph-projection-store.ts";
+import { type OperationInput, string } from "./operation-input.ts";
 
 const MODULE_ID = "graph_projection";
 
-type OperationInput = Record<string, unknown>;
-
-function string(input: OperationInput, key: string): string {
-	const value = input[key];
-	if (typeof value !== "string" || value.length === 0) throw new Error(`${key} is required`);
-	return value;
-}
-
 function number(input: OperationInput, key: string): number {
 	const value = input[key];
 	if (typeof value !== "number" || !Number.isFinite(value)) throw new Error(`${key} is required and must be a number`);

package/src/modules/logs.ts

@@ -6,33 +6,12 @@
  * comment on why `log` is not an Artifact kind).
  */
 import type { JsonValue, LogLevel } from "../domain/log-entry.ts";
-import type { Logs } from "../log-service.ts";
+import type { Logs } from "../log/log-service.ts";
 import type { OperationDefinition } from "../module-registry.ts";
+import { type OperationInput, optionalNumber, optionalString, string } from "./operation-input.ts";
 
 const MODULE_ID = "logs";
 
-type OperationInput = Record<string, unknown>;
-
-function string(input: OperationInput, key: string): string {
-	const value = input[key];
-	if (typeof value !== "string" || value.length === 0) throw new Error(`${key} is required`);
-	return value;
-}
-
-function optionalString(input: OperationInput, key: string): string | undefined {
-	const value = input[key];
-	if (value === undefined) return undefined;
-	if (typeof value !== "string") throw new Error(`${key} must be a string`);
-	return value;
-}
-
-function optionalNumber(input: OperationInput, key: string): number | undefined {
-	const value = input[key];
-	if (value === undefined) return undefined;
-	if (typeof value !== "number" || !Number.isFinite(value)) throw new Error(`${key} must be a number`);
-	return value;
-}
-
 function isJsonValue(value: unknown): value is JsonValue {
 	return (
 		value === null ||