@danypops/papyrus 0.46.1 → 0.47.0

package/src/handlers/tasks.ts

@@ -19,17 +19,25 @@
  *
  * remove/remove_subtree/restore are not duplicated here -- see ./artifact-trash-vehicle.ts.
  */
-import { VehicleError, type VehicleLimits } from "@danypops/vehicle-core";
+import { VehicleError, type VehicleLimits, type VehicleOperationContext } from "@danypops/vehicle-core";
 import type { VehicleRegistry } from "@danypops/vehicle-server";
 import type { ArtifactStore } from "../artifact/artifact-store.ts";
-import { GATE_TIMEOUT_MAX_MS, TASK_CREATE_IDEMPOTENCY_KEY_MAX_LENGTH } from "../constants.ts";
+import { GATE_TIMEOUT_MAX_MS, TASK_CREATE_IDEMPOTENCY_KEY_MAX_LENGTH, TASK_MUTATION_IDEMPOTENCY_KEY_MAX_LENGTH } from "../constants.ts";
 import { PROOF_TYPES } from "../domain/checklist.ts";
 import { GATE_TYPES } from "../domain/gate.ts";
 import type { TaskViewMode } from "../domain/task-scope.ts";
 import { tasksOperations } from "../modules/tasks.ts";
 import type { SessionIdentity } from "../session-identity/session-identity-service.ts";
+import { TaskMutationIdempotencyConflictError, TaskMutationPendingError } from "../stores/task-mutation-request-store.ts";
 import type { TaskExecutionPlan } from "../task/task-execution.ts";
-import { type TaskCompletion, TaskProjectAmbiguousError, TaskProjectNotFoundError, type Tasks } from "../task/task-service.ts";
+import {
+	type TaskCompletion,
+	TaskInvalidTransitionError,
+	TaskMutationReceiptNotFoundError,
+	TaskProjectAmbiguousError,
+	TaskProjectNotFoundError,
+	type Tasks,
+} from "../task/task-service.ts";
 import {
 	booleanProp,
 	classifySessionAuthorization,
@@ -75,12 +83,20 @@ const GATE_OPERATION_LIMITS: VehicleLimits = {
 const objectProp = { type: "object" } as const;
 const arrayProp = { type: "array" } as const;
 const _boolProp = { type: "boolean" } as const;
+const mutationIdempotencyProp = {
+	type: "string",
+	minLength: 1,
+	maxLength: TASK_MUTATION_IDEMPOTENCY_KEY_MAX_LENGTH,
+	description:
+		"Retry key for this exact mutation. Reuse the same key after an unknown outcome; inspect mutation_status before choosing a new action.",
+} as const;
 
 const gateProp = {
 	type: "array",
 	description: "Validation gates run by tasks.run_gates and tasks.complete.",
 	items: {
 		type: "object",
+		description: "Accepted gate shape: {type, target, expect?, timeoutMs?}.",
 		properties: {
 			type: { type: "string", enum: GATE_TYPES, description: "Gate evaluator." },
 			target: { type: "string", minLength: 1, description: "Path, command, text target, or test command." },
@@ -109,6 +125,7 @@ const checklistProp = {
 				minItems: 1,
 				items: {
 					type: "object",
+					description: "Accepted proof shape: {type, target, expect?}.",
 					properties: {
 						type: { type: "string", enum: PROOF_TYPES },
 						target: { type: "string", minLength: 1 },
@@ -249,13 +266,58 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 	 * vehicle-registry's own secure-by-default handler-failed opacity still applies to a genuine
 	 * unexpected crash (see artifact-vehicle-shared.ts's classify* helpers).
 	 */
+	const throwLifecycleError = (error: unknown): never => {
+		if (error instanceof TaskInvalidTransitionError) {
+			throw new VehicleError("invalid-transition", error.message, {
+				category: "conflict",
+				details: {
+					operation: error.operation,
+					currentStatus: error.currentStatus,
+					intendedStatus: error.intendedStatus,
+					allowedActions: [...error.allowedActions],
+					recovery: error.recovery,
+				},
+			});
+		}
+		if (error instanceof TaskMutationIdempotencyConflictError) {
+			throw new VehicleError("idempotency-key-conflict", error.message, { category: "conflict" });
+		}
+		if (error instanceof TaskMutationPendingError) {
+			throw new VehicleError("mutation-pending", error.message, {
+				category: "conflict",
+				details: { receiptId: error.receiptId, operation: error.operation },
+			});
+		}
+		if (error instanceof TaskMutationReceiptNotFoundError) {
+			throw new VehicleError("mutation-receipt-not-found", error.message, { category: "not_found" });
+		}
+		throw error;
+	};
+	const classifyLifecycle = <T>(run: () => T): T => {
+		try {
+			const result = run();
+			return result instanceof Promise ? (result.catch(throwLifecycleError) as T) : result;
+		} catch (error) {
+			return throwLifecycleError(error);
+		}
+	};
 	const call = (name: string, input: Record<string, unknown>): unknown =>
 		classifySessionAuthorization(() =>
 			classifyTaskCreateIdempotency(() =>
-				classifyTaskExecutionBounds(() => classifyTaskDependencyCycles(() => moduleOperations.get(name)!.execute(input))),
+				classifyTaskExecutionBounds(() =>
+					classifyTaskDependencyCycles(() => classifyLifecycle(() => moduleOperations.get(name)!.execute(input))),
+				),
 			),
 		);
 	const define = createOperationDefiner(registry, OWNER, "tasks", ["tasks:read", "tasks:write"], call);
+	const mutationInput = (
+		input: Record<string, unknown>,
+		context: VehicleOperationContext<Record<string, unknown>>,
+	): Record<string, unknown> => ({
+		...input,
+		idempotency_key: input.idempotency_key ?? context.idempotencyKey,
+		idempotency_caller: context.principal?.id ?? "anonymous",
+	});
 
 	const resolveProject = (reference: string) => {
 		try {
@@ -286,7 +348,7 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 
 	define(
 		"create",
-		"Creates a Task -- work: desired outcomes, gates, checklists, and dependencies. project_root is required (no ambient cwd server-side). Prefer parent_name/depends_on_names over parent_id/depends_on -- resolved server-side.",
+		'Creates a Task -- work: desired outcomes, gates, checklists, and dependencies. Gates are {type, target, expect?, timeoutMs?}; for example [{type: "command", target: "bun run typecheck", timeoutMs: 60000}]. Checklist criteria are {proof: [{type, target, expect?}]}. project_root is required (no ambient cwd server-side). Prefer parent_name/depends_on_names over parent_id/depends_on -- resolved server-side.',
 		"local-write",
 		{
 			title: stringProp,
@@ -520,7 +582,8 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 	): void => {
 		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 });
+			const operationInput = action === "pause" || action === "unpause" ? mutationInput(resolvedInput, context) : resolvedInput;
+			return call(`tasks.${action}`, { ...operationInput, session_id: claims?.sessionId, session_secret: claims?.sessionSecret });
 		});
 	};
 
@@ -534,63 +597,67 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 			id: resolveTaskId(artifacts, tasks, { projectRoot: input.project_root as string | undefined }, input.id, input.name),
 		}),
 	);
-	focusOperation("pause", "Pauses the active Task Focus without clearing it.", { reason: stringProp }, [], (input) => input);
-	focusOperation("unpause", "Resumes a paused Task Focus.", {}, [], (input) => input);
-	focusOperation("clear_focus", "Clears the active Task Focus.", {}, [], (input) => input);
-
-	define(
-		"start",
-		"Lifecycle transition: todo -> in-progress.",
-		"local-write",
-		{ id: stringProp, name: stringProp, reason: stringProp, session_id: stringProp, project_root: stringProp },
-		[],
-		resolveIdAndScope,
-	);
-	define(
-		"submit",
-		"Lifecycle transition: in-progress -> review.",
-		"local-write",
-		{ id: stringProp, name: stringProp, reason: stringProp, session_id: stringProp, project_root: stringProp },
-		[],
-		resolveIdAndScope,
-	);
-	define(
-		"reject",
-		"Lifecycle transition: review -> rejected.",
-		"local-write",
-		{ id: stringProp, name: stringProp, reason: stringProp, session_id: stringProp, project_root: stringProp },
-		[],
-		resolveIdAndScope,
-	);
-	define(
-		"retry",
-		"Lifecycle transition: rejected -> in-progress.",
-		"local-write",
-		{ id: stringProp, name: stringProp, reason: stringProp, session_id: stringProp, project_root: stringProp },
+	focusOperation(
+		"pause",
+		"Pauses Task Focus. Destination-state idempotent: replaying after success returns changed=false. Reuse idempotency_key after an unknown outcome.",
+		{ reason: stringProp, idempotency_key: mutationIdempotencyProp },
 		[],
-		resolveIdAndScope,
+		(input) => input,
 	);
-	define(
-		"cancel",
-		"Lifecycle transition to canceled (terminal) from todo/in-progress/review/rejected. Reversible via tasks.reopen if this turns out to be premature.",
-		"local-write",
-		{ id: stringProp, name: stringProp, reason: stringProp, session_id: stringProp, project_root: stringProp },
+	focusOperation(
+		"unpause",
+		"Resumes paused Task Focus. Destination-state idempotent: replaying after success returns changed=false. Reuse idempotency_key after an unknown outcome.",
+		{ idempotency_key: mutationIdempotencyProp },
 		[],
-		resolveIdAndScope,
+		(input) => input,
 	);
+	focusOperation("clear_focus", "Clears the active Task Focus.", {}, [], (input) => input);
 
-	define(
-		"reopen",
-		"Lifecycle transition: canceled -> todo. For a task legitimately canceled through a normal transition (e.g. a deliberate pause/park) that should resume -- distinct from tasks.update's status:todo path, which only recovers a task that was terminal at its own creation (a caller mistake), never one canceled/rejected later.",
-		"local-write",
-		{ id: stringProp, name: stringProp, reason: stringProp, session_id: stringProp, project_root: stringProp },
-		[],
-		resolveIdAndScope,
+	const transitionOperation = (action: "start" | "submit" | "reject" | "retry" | "cancel" | "reopen", description: string): void =>
+		define(
+			action,
+			`${description} Destination-state idempotent: a replay after success returns changed=false. After an unknown outcome, call tasks.show and mutation_status, then reuse the SAME idempotency_key; never retry with a new key from stale state.`,
+			"local-write",
+			{
+				id: stringProp,
+				name: stringProp,
+				reason: stringProp,
+				session_id: stringProp,
+				project_root: stringProp,
+				idempotency_key: mutationIdempotencyProp,
+			},
+			[],
+			resolveIdAndScope,
+			(input, context) => {
+				const result = call(`tasks.${action}`, mutationInput(input, context)) as {
+					title: string;
+					status: string;
+					changed: boolean;
+					receiptId?: string;
+					replayed?: boolean;
+				};
+				const text = result.changed
+					? `${result.title} transitioned to ${result.status}.`
+					: result.replayed
+						? `Recovered the prior ${action} receipt for ${result.title}; call tasks.show to confirm its current status before the next action.`
+						: `${result.title} was already ${result.status}; replay was a safe no-op.`;
+				return { ...result, content: [{ type: "text" as const, text }] };
+			},
+		);
+
+	transitionOperation("start", "Lifecycle transition: todo -> in-progress.");
+	transitionOperation("submit", "Lifecycle transition: in-progress -> review.");
+	transitionOperation("reject", "Lifecycle transition: review -> rejected.");
+	transitionOperation("retry", "Lifecycle transition: rejected -> in-progress.");
+	transitionOperation(
+		"cancel",
+		"Lifecycle transition to canceled (terminal) from todo/in-progress/review/rejected. Reversible via tasks.reopen if premature.",
 	);
+	transitionOperation("reopen", "Lifecycle transition: canceled -> todo for work that should resume.");
 
 	define(
 		"complete",
-		"Runs gates + checklist-proof review, then focuses one deterministic ready successor without claiming effort. Rejects (not completes) on gate/checklist failure.",
+		"Runs gates + checklist-proof review, then focuses one deterministic ready successor without claiming effort. Rejects on gate/checklist failure. Reuse the same idempotency_key after an unknown outcome so gates and history are not run twice; inspect mutation_status before choosing a new action. A replay after done is a changed=false no-op.",
 		"local-write",
 		{
 			id: stringProp,
@@ -601,11 +668,12 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 			scope: { type: "string", enum: ["project", "graph", "all"] },
 			root_task_id: stringProp,
 			root_task_name: stringProp,
+			idempotency_key: mutationIdempotencyProp,
 		},
 		[],
 		resolveIdAndScope,
-		async (input) => {
-			const result = (await call("tasks.complete", input)) as TaskCompletion;
+		async (input, context) => {
+			const result = (await call("tasks.complete", mutationInput(input, context))) as TaskCompletion;
 			const dependencyIds = result.blocked.flatMap((entry) => entry.dependencyIds);
 			const labels = labelsById(artifacts, dependencyIds);
 			return { ...result, content: [{ type: "text" as const, text: completionContentText(labels, result) }] };
@@ -613,6 +681,16 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 		GATE_OPERATION_LIMITS,
 	);
 
+	define(
+		"mutation_status",
+		"Resolves an unknown lifecycle mutation outcome by the original idempotency_key. Read this receipt before selecting another transition; never invent a replacement key for the same attempt.",
+		"read",
+		{ idempotency_key: mutationIdempotencyProp },
+		["idempotency_key"],
+		(input) => input,
+		(input, context) => call("tasks.mutation_status", mutationInput(input, context)),
+	);
+
 	define(
 		"run_gates",
 		"Runs a Task's configured gates without transitioning its status -- for checking readiness before submit/complete.",

package/src/id-migration.ts

@@ -54,6 +54,7 @@ const FK_COLUMNS: ReadonlyArray<{ table: string; column: string }> = [
 	{ table: "task_events", column: "task_id" },
 	{ table: "task_scopes", column: "task_id" },
 	{ table: "task_views", column: "root_task_id" },
+	{ table: "task_mutation_requests", column: "task_id" },
 	{ table: "artifact_events", column: "artifact_id" },
 	{ table: "artifact_events", column: "related_id" },
 ];
@@ -68,6 +69,7 @@ const TEXT_SCAN_COLUMNS: ReadonlyArray<{ table: string; column: string }> = [
 	{ table: "artifacts", column: "extra" },
 	{ table: "task_events", column: "reason" },
 	{ table: "task_events", column: "evidence_json" },
+	{ table: "task_mutation_requests", column: "response_json" },
 ];
 
 /** Audit tables whose append-only guard must be suspended for exactly this migration's duration. */

package/src/index.ts

@@ -35,4 +35,12 @@ 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";
+export type {
+	TaskCompletion,
+	TaskGraph,
+	TaskLifecycleMutationResult,
+	TaskMutationReceiptView,
+	TaskNode,
+	TaskStatus,
+} from "./task/task-service.ts";
+export { TaskInvalidTransitionError, TaskMutationReceiptNotFoundError } from "./task/task-service.ts";

package/src/modules/tasks.ts

@@ -28,7 +28,7 @@ import type { OperationDefinition } from "../module-registry.ts";
 import type { SessionIdentity } from "../session-identity/session-identity-service.ts";
 import { taskContext } from "../task/task-context.ts";
 import { projectTaskExecution } from "../task/task-execution.ts";
-import type { TaskStatus, Tasks } from "../task/task-service.ts";
+import type { TaskMutationRequestContext, TaskStatus, Tasks } from "../task/task-service.ts";
 import { type OperationInput, optionalBoolean, optionalNumber, optionalString, optionalStringArray, string } from "./operation-input.ts";
 
 const MODULE_ID = "tasks";
@@ -40,6 +40,11 @@ const eventContext = (input: OperationInput): TaskEventContext => ({
 	reason: optionalString(input, "reason"),
 });
 
+const mutationRequest = (input: OperationInput): TaskMutationRequestContext => ({
+	key: optionalString(input, "idempotency_key"),
+	caller: optionalString(input, "idempotency_caller"),
+});
+
 const taskFilter = (input: OperationInput) => ({
 	status: optionalString(input, "status"),
 	text: optionalString(input, "text"),
@@ -83,6 +88,7 @@ export const TASKS_OPERATION_NAMES = [
 	"tasks.start",
 	"tasks.submit",
 	"tasks.complete",
+	"tasks.mutation_status",
 	"tasks.run_gates",
 	"tasks.set_checklist",
 	"tasks.set_gates",
@@ -195,20 +201,29 @@ export function tasksOperations(tasks: Tasks, artifacts: ArtifactStore, sessionI
 		}),
 		define("tasks.pause", (input: OperationInput) => {
 			guardFocusMutation(input);
-			return tasks.pauseFocus(eventContext(input));
+			return tasks.pauseFocus(eventContext(input), mutationRequest(input));
 		}),
 		define("tasks.unpause", (input: OperationInput) => {
 			guardFocusMutation(input);
-			return tasks.unpauseFocus(eventContext(input));
+			return tasks.unpauseFocus(eventContext(input), mutationRequest(input));
 		}),
 		define("tasks.clear_focus", (input: OperationInput) => {
 			guardFocusMutation(input);
 			return tasks.clearFocus(eventContext(input));
 		}),
 		define("tasks.reap_stale_focus", () => ({ removed: tasks.reapStaleFocus() })),
-		define("tasks.start", (input: OperationInput) => tasks.transition(string(input, "id"), "start", eventContext(input))),
-		define("tasks.submit", (input: OperationInput) => tasks.transition(string(input, "id"), "submit", eventContext(input))),
-		define("tasks.complete", (input: OperationInput) => tasks.completeAsync(string(input, "id"), eventContext(input))),
+		define("tasks.start", (input: OperationInput) =>
+			tasks.transition(string(input, "id"), "start", eventContext(input), mutationRequest(input)),
+		),
+		define("tasks.submit", (input: OperationInput) =>
+			tasks.transition(string(input, "id"), "submit", eventContext(input), mutationRequest(input)),
+		),
+		define("tasks.complete", (input: OperationInput) =>
+			tasks.completeAsync(string(input, "id"), eventContext(input), {}, mutationRequest(input)),
+		),
+		define("tasks.mutation_status", (input: OperationInput) =>
+			tasks.mutationStatus(string(input, "idempotency_key"), optionalString(input, "idempotency_caller")),
+		),
 		define("tasks.run_gates", (input: OperationInput) => tasks.runGates(string(input, "id"), eventContext(input))),
 		define("tasks.set_checklist", (input: OperationInput) => tasks.setChecklist(string(input, "id"), input.checklist as Checklist)),
 		define("tasks.set_gates", (input: OperationInput) =>
@@ -222,10 +237,18 @@ export function tasksOperations(tasks: Tasks, artifacts: ArtifactStore, sessionI
 				optionalString(input, "verbosity") === "summary" ? "summary" : "full",
 			),
 		),
-		define("tasks.reject", (input: OperationInput) => tasks.transition(string(input, "id"), "reject", eventContext(input))),
-		define("tasks.retry", (input: OperationInput) => tasks.transition(string(input, "id"), "retry", eventContext(input))),
-		define("tasks.cancel", (input: OperationInput) => tasks.transition(string(input, "id"), "cancel", eventContext(input))),
-		define("tasks.reopen", (input: OperationInput) => tasks.transition(string(input, "id"), "reopen", eventContext(input))),
+		define("tasks.reject", (input: OperationInput) =>
+			tasks.transition(string(input, "id"), "reject", eventContext(input), mutationRequest(input)),
+		),
+		define("tasks.retry", (input: OperationInput) =>
+			tasks.transition(string(input, "id"), "retry", eventContext(input), mutationRequest(input)),
+		),
+		define("tasks.cancel", (input: OperationInput) =>
+			tasks.transition(string(input, "id"), "cancel", eventContext(input), mutationRequest(input)),
+		),
+		define("tasks.reopen", (input: OperationInput) =>
+			tasks.transition(string(input, "id"), "reopen", eventContext(input), mutationRequest(input)),
+		),
 		define("tasks.cancel_subtree", (input: OperationInput) => tasks.cancelSubtree(string(input, "id"), eventContext(input))),
 		define("tasks.depend", (input: OperationInput) =>
 			tasks.depend(string(input, "id"), string(input, "dependency_id"), eventContext(input)),

package/src/service.ts

@@ -43,6 +43,7 @@ import { SQLiteTaskCreateRequestStore } from "./stores/sqlite-task-create-reques
 import { SQLiteTaskEventStore } from "./stores/sqlite-task-event-store.ts";
 import { SQLiteTaskFocusStore } from "./stores/sqlite-task-focus-store.ts";
 import { SQLiteTaskLeaseStore } from "./stores/sqlite-task-lease-store.ts";
+import { SQLiteTaskMutationRequestStore } from "./stores/sqlite-task-mutation-request-store.ts";
 import { SQLiteTaskScopeStore } from "./stores/sqlite-task-scope-store.ts";
 import type { TaskEventStore } from "./stores/task-event-store.ts";
 import type { TaskScopeStore } from "./stores/task-scope-store.ts";
@@ -368,6 +369,7 @@ function handlers(
 		"tasks.start": forwardToModule("tasks.start"),
 		"tasks.submit": forwardToModule("tasks.submit"),
 		"tasks.complete": forwardToModule("tasks.complete"),
+		"tasks.mutation_status": forwardToModule("tasks.mutation_status"),
 		"tasks.run_gates": forwardToModule("tasks.run_gates"),
 		"tasks.set_checklist": forwardToModule("tasks.set_checklist"),
 		"tasks.set_gates": forwardToModule("tasks.set_gates"),
@@ -454,7 +456,8 @@ export function createPapyrusService(path: string): PapyrusService {
 	const scopes = new SQLiteTaskScopeStore(db);
 	const leases = new SQLiteTaskLeaseStore(db);
 	const createRequests = new SQLiteTaskCreateRequestStore(db);
-	const tasks = new Tasks(artifacts, gates, focus, events, scopes, leases, createRequests);
+	const mutationRequests = new SQLiteTaskMutationRequestStore(db);
+	const tasks = new Tasks(artifacts, gates, focus, events, scopes, leases, createRequests, mutationRequests);
 	const noteEvents = new SQLiteNoteEventStore(db);
 	const notes = new Notes(artifacts, noteEvents);
 	const projections = new SQLiteGraphProjectionStore(db);

package/src/stores/sqlite-task-mutation-request-store.ts

@@ -0,0 +1,98 @@
+import type { Db } from "../db.ts";
+import { TaskMutationPendingError, type TaskMutationRequestRecord, type TaskMutationRequestStore } from "./task-mutation-request-store.ts";
+
+interface TaskMutationRequestRow {
+	request_scope: string;
+	idempotency_key: string;
+	receipt_id: string;
+	task_id: string | null;
+	operation: string;
+	request_hash: string;
+	state: "pending" | "completed";
+	response_json: string | null;
+	created_at: string;
+	updated_at: string;
+	expires_at: string;
+}
+
+function mapRow(row: TaskMutationRequestRow): TaskMutationRequestRecord {
+	return {
+		scope: row.request_scope,
+		key: row.idempotency_key,
+		receiptId: row.receipt_id,
+		...(row.task_id === null ? {} : { taskId: row.task_id }),
+		operation: row.operation,
+		requestHash: row.request_hash,
+		state: row.state,
+		...(row.response_json === null ? {} : { responseJson: row.response_json }),
+		createdAt: row.created_at,
+		updatedAt: row.updated_at,
+		expiresAt: row.expires_at,
+	};
+}
+
+export class SQLiteTaskMutationRequestStore implements TaskMutationRequestStore {
+	constructor(private readonly db: Db) {}
+
+	get(scope: string, key: string, now: string): TaskMutationRequestRecord | undefined {
+		const row = this.db
+			.prepare("SELECT * FROM task_mutation_requests WHERE request_scope = ? AND idempotency_key = ? AND expires_at > ?")
+			.get(scope, key, now) as TaskMutationRequestRow | null;
+		return row ? mapRow(row) : undefined;
+	}
+
+	findPending(taskId: string, operation: string, now: string): TaskMutationRequestRecord | undefined {
+		const row = this.db
+			.prepare(
+				"SELECT * FROM task_mutation_requests WHERE task_id = ? AND operation = ? AND state = 'pending' AND expires_at > ? ORDER BY created_at LIMIT 1",
+			)
+			.get(taskId, operation, now) as TaskMutationRequestRow | null;
+		return row ? mapRow(row) : undefined;
+	}
+
+	put(record: TaskMutationRequestRecord): void {
+		try {
+			this.db
+				.prepare(`
+					INSERT INTO task_mutation_requests (
+						request_scope, idempotency_key, receipt_id, task_id, operation, request_hash,
+						state, response_json, created_at, updated_at, expires_at
+					) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+				`)
+				.run(
+					record.scope,
+					record.key,
+					record.receiptId,
+					record.taskId ?? null,
+					record.operation,
+					record.requestHash,
+					record.state,
+					record.responseJson ?? null,
+					record.createdAt,
+					record.updatedAt,
+					record.expiresAt,
+				);
+		} catch (error) {
+			const pending = record.taskId ? this.findPending(record.taskId, record.operation, record.createdAt) : undefined;
+			if (pending) {
+				throw new TaskMutationPendingError(`an earlier ${record.operation} outcome is still pending`, pending.receiptId, pending.operation);
+			}
+			throw error;
+		}
+	}
+
+	complete(scope: string, key: string, responseJson: string, updatedAt: string): void {
+		const result = this.db
+			.prepare(`
+				UPDATE task_mutation_requests
+				SET state = 'completed', response_json = ?, updated_at = ?
+				WHERE request_scope = ? AND idempotency_key = ?
+			`)
+			.run(responseJson, updatedAt, scope, key);
+		if (result.changes !== 1) throw new Error("task mutation receipt not found");
+	}
+
+	prune(now: string): number {
+		return this.db.prepare("DELETE FROM task_mutation_requests WHERE expires_at <= ?").run(now).changes;
+	}
+}

package/src/stores/task-mutation-request-store.ts

@@ -0,0 +1,89 @@
+export type TaskMutationRequestState = "pending" | "completed";
+
+export interface TaskMutationRequestRecord {
+	scope: string;
+	key: string;
+	receiptId: string;
+	taskId?: string;
+	operation: string;
+	requestHash: string;
+	state: TaskMutationRequestState;
+	responseJson?: string;
+	createdAt: string;
+	updatedAt: string;
+	expiresAt: string;
+}
+
+export interface TaskMutationRequestStore {
+	get(scope: string, key: string, now: string): TaskMutationRequestRecord | undefined;
+	findPending(taskId: string, operation: string, now: string): TaskMutationRequestRecord | undefined;
+	put(record: TaskMutationRequestRecord): void;
+	complete(scope: string, key: string, responseJson: string, updatedAt: string): void;
+	prune(now: string): number;
+}
+
+export class TaskMutationIdempotencyConflictError extends Error {}
+
+export class TaskMutationPendingError extends Error {
+	constructor(
+		message: string,
+		readonly receiptId: string,
+		readonly operation: string,
+	) {
+		super(message);
+	}
+}
+
+export class InMemoryTaskMutationRequestStore implements TaskMutationRequestStore {
+	private readonly records = new Map<string, TaskMutationRequestRecord>();
+
+	private recordKey(scope: string, key: string): string {
+		return `${scope}\u0000${key}`;
+	}
+
+	get(scope: string, key: string, now: string): TaskMutationRequestRecord | undefined {
+		const record = this.records.get(this.recordKey(scope, key));
+		return !record || record.expiresAt <= now ? undefined : { ...record };
+	}
+
+	findPending(taskId: string, operation: string, now: string): TaskMutationRequestRecord | undefined {
+		for (const record of this.records.values()) {
+			if (record.taskId === taskId && record.operation === operation && record.state === "pending" && record.expiresAt > now) {
+				return { ...record };
+			}
+		}
+		return undefined;
+	}
+
+	put(record: TaskMutationRequestRecord): void {
+		if (record.state === "pending" && record.taskId) {
+			const existing = this.findPending(record.taskId, record.operation, record.createdAt);
+			if (existing) {
+				throw new TaskMutationPendingError(
+					`an earlier ${record.operation} outcome is still pending`,
+					existing.receiptId,
+					existing.operation,
+				);
+			}
+		}
+		this.records.set(this.recordKey(record.scope, record.key), { ...record });
+	}
+
+	complete(scope: string, key: string, responseJson: string, updatedAt: string): void {
+		const recordKey = this.recordKey(scope, key);
+		const record = this.records.get(recordKey);
+		if (!record) throw new Error("task mutation receipt not found");
+		this.records.set(recordKey, { ...record, state: "completed", responseJson, updatedAt });
+	}
+
+	prune(now: string): number {
+		let removed = 0;
+		for (const [key, record] of this.records) {
+			if (record.expiresAt <= now) {
+				this.records.delete(key);
+				removed += 1;
+			}
+		}
+		return removed;
+	}
+}