@danypops/papyrus 0.46.2 → 0.47.1

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;
+	}
+}