trekoon 0.3.6 → 0.3.8

package/src/domain/mutation-service.ts

@@ -1,7 +1,7 @@
 import { type Database } from "bun:sqlite";
 
 import { writeTransaction } from "../storage/database";
-import { appendEventWithGitContext } from "../sync/event-writes";
+import { appendEventWithGitContext, prepareEventWriteContext, withTransactionEventContext } from "../sync/event-writes";
 import { ENTITY_OPERATIONS } from "./mutation-operations";
 import { TrackerDomain, validateStatusTransition } from "./tracker-domain";
 import {
@@ -26,6 +26,31 @@ import {
   DomainError,
 } from "./types";
 
+interface AtomicIdempotencyClaim {
+  readonly scope: "subtask" | "dependency" | "deleted_subtask" | "deleted_dependency";
+  readonly idempotencyKey: string;
+  readonly requestFingerprint: string;
+  readonly conflictMessage: string;
+}
+
+interface AtomicIdempotencyReplayResult {
+  readonly state: "replay";
+  readonly status: number;
+  readonly responseData: Record<string, unknown>;
+}
+
+interface AtomicIdempotencyCompletedResult {
+  readonly state: "completed";
+  readonly status: number;
+  readonly responseData: Record<string, unknown>;
+}
+
+type AtomicIdempotentMutationResult =
+  | AtomicIdempotencyReplayResult
+  | AtomicIdempotencyCompletedResult;
+
+const BOARD_IDEMPOTENCY_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+
 function countMatches(value: string, searchText: string): number {
   if (searchText.length === 0) {
     return 0;
@@ -104,8 +129,54 @@ export class MutationService {
     this.#domain = new TrackerDomain(db);
   }
 
+  #writeTransaction<T>(fn: () => T): T {
+    const eventContext = prepareEventWriteContext(this.#db, this.#cwd);
+    return writeTransaction(this.#db, (): T => withTransactionEventContext(this.#db, eventContext, fn));
+  }
+
+  #dependencyEventEntityId(input: {
+    sourceId: string;
+    sourceKind: string;
+    dependsOnId: string;
+    dependsOnKind: string;
+  }): string {
+    return `${input.sourceKind}:${input.sourceId}->${input.dependsOnKind}:${input.dependsOnId}`;
+  }
+
+  #dependencyEventFields(input: {
+    dependencyId?: string | undefined;
+    sourceId: string;
+    sourceKind?: string | undefined;
+    dependsOnId: string;
+    dependsOnKind?: string | undefined;
+    sourceEventId?: string | undefined;
+  }): Record<string, string> {
+    const fields: Record<string, string> = {
+      source_id: input.sourceId,
+      depends_on_id: input.dependsOnId,
+    };
+
+    if (input.dependencyId) {
+      fields.dependency_id = input.dependencyId;
+    }
+
+    if (input.sourceKind) {
+      fields.source_kind = input.sourceKind;
+    }
+
+    if (input.dependsOnKind) {
+      fields.depends_on_kind = input.dependsOnKind;
+    }
+
+    if (input.sourceEventId) {
+      fields.source_event_id = input.sourceEventId;
+    }
+
+    return fields;
+  }
+
   createEpic(input: { title: string; description: string; status?: string | undefined }): EpicRecord {
-    return writeTransaction(this.#db, (): EpicRecord => {
+    return this.#writeTransaction((): EpicRecord => {
       const epic = this.#domain.createEpic(input);
       this.#appendEntityEvent("epic", epic.id, ENTITY_OPERATIONS.epic.created, {
         title: epic.title,
@@ -124,7 +195,7 @@ export class MutationService {
     subtaskSpecs: readonly CompactSubtaskSpec[];
     dependencySpecs: readonly CompactDependencySpec[];
   }): CompactEpicCreateResult {
-    return writeTransaction(this.#db, (): CompactEpicCreateResult => {
+    return this.#writeTransaction((): CompactEpicCreateResult => {
       const epic = this.#domain.createEpic(input);
       const created = this.#domain.expandEpic({
         epicId: epic.id,
@@ -158,12 +229,18 @@ export class MutationService {
       }
 
       for (const dependency of created.dependencies) {
-        this.#appendEntityEvent("dependency", dependency.id, ENTITY_OPERATIONS.dependency.added, {
-          source_id: dependency.sourceId,
-          source_kind: dependency.sourceKind,
-          depends_on_id: dependency.dependsOnId,
-          depends_on_kind: dependency.dependsOnKind,
-        });
+        this.#appendEntityEvent(
+          "dependency",
+          this.#dependencyEventEntityId(dependency),
+          ENTITY_OPERATIONS.dependency.added,
+          this.#dependencyEventFields({
+            dependencyId: dependency.id,
+            sourceId: dependency.sourceId,
+            sourceKind: dependency.sourceKind,
+            dependsOnId: dependency.dependsOnId,
+            dependsOnKind: dependency.dependsOnKind,
+          }),
+        );
       }
 
       return {
@@ -180,7 +257,7 @@ export class MutationService {
     id: string,
     input: { title?: string | undefined; description?: string | undefined; status?: string | undefined },
   ): EpicRecord {
-    return writeTransaction(this.#db, (): EpicRecord => {
+    return this.#writeTransaction((): EpicRecord => {
       if (input.status !== undefined) {
         const existing = this.#domain.getEpicOrThrow(id);
         validateStatusTransition(existing.status, input.status, "epic", id);
@@ -196,7 +273,7 @@ export class MutationService {
   }
 
   updateEpicStatusCascade(id: string, status: string): StatusCascadePlan {
-    return writeTransaction(this.#db, (): StatusCascadePlan => {
+    return this.#writeTransaction((): StatusCascadePlan => {
       const plan = this.#domain.planStatusCascade("epic", id, status);
       this.#assertCascadeNotBlocked(plan);
       this.#applyStatusCascadePlan(plan);
@@ -205,14 +282,14 @@ export class MutationService {
   }
 
   deleteEpic(id: string): void {
-    writeTransaction(this.#db, (): void => {
+    this.#writeTransaction((): void => {
       this.#domain.deleteEpic(id);
       this.#appendEntityEvent("epic", id, ENTITY_OPERATIONS.epic.deleted, {});
     });
   }
 
   createTask(input: { epicId: string; title: string; description: string; status?: string | undefined }): TaskRecord {
-    return writeTransaction(this.#db, (): TaskRecord => {
+    return this.#writeTransaction((): TaskRecord => {
       const task = this.#domain.createTask(input);
       this.#appendEntityEvent("task", task.id, ENTITY_OPERATIONS.task.created, {
         epic_id: task.epicId,
@@ -225,7 +302,7 @@ export class MutationService {
   }
 
   createTaskBatch(input: { epicId: string; specs: readonly CompactTaskSpec[] }): CompactTaskBatchCreateResult {
-    return writeTransaction(this.#db, (): CompactTaskBatchCreateResult => {
+    return this.#writeTransaction((): CompactTaskBatchCreateResult => {
       const created = this.#domain.createTaskBatch(input);
       for (const task of created.tasks) {
         this.#appendEntityEvent("task", task.id, ENTITY_OPERATIONS.task.created, {
@@ -245,7 +322,7 @@ export class MutationService {
     subtaskSpecs: readonly CompactSubtaskSpec[];
     dependencySpecs: readonly CompactDependencySpec[];
   }): CompactEpicExpandResult {
-    return writeTransaction(this.#db, (): CompactEpicExpandResult => {
+    return this.#writeTransaction((): CompactEpicExpandResult => {
       const created = this.#domain.expandEpic(input);
       for (const task of created.tasks) {
         this.#appendEntityEvent("task", task.id, ENTITY_OPERATIONS.task.created, {
@@ -266,12 +343,18 @@ export class MutationService {
       }
 
       for (const dependency of created.dependencies) {
-        this.#appendEntityEvent("dependency", dependency.id, ENTITY_OPERATIONS.dependency.added, {
-          source_id: dependency.sourceId,
-          source_kind: dependency.sourceKind,
-          depends_on_id: dependency.dependsOnId,
-          depends_on_kind: dependency.dependsOnKind,
-        });
+        this.#appendEntityEvent(
+          "dependency",
+          this.#dependencyEventEntityId(dependency),
+          ENTITY_OPERATIONS.dependency.added,
+          this.#dependencyEventFields({
+            dependencyId: dependency.id,
+            sourceId: dependency.sourceId,
+            sourceKind: dependency.sourceKind,
+            dependsOnId: dependency.dependsOnId,
+            dependsOnKind: dependency.dependsOnKind,
+          }),
+        );
       }
 
       return created;
@@ -282,7 +365,7 @@ export class MutationService {
     id: string,
     input: { title?: string | undefined; description?: string | undefined; status?: string | undefined; owner?: string | null | undefined },
   ): TaskRecord {
-    return writeTransaction(this.#db, (): TaskRecord => {
+    return this.#writeTransaction((): TaskRecord => {
       if (input.status !== undefined) {
         const existing = this.#domain.getTaskOrThrow(id);
         validateStatusTransition(existing.status, input.status, "task", id);
@@ -300,7 +383,7 @@ export class MutationService {
   }
 
   updateTaskStatusCascade(id: string, status: string): StatusCascadePlan {
-    return writeTransaction(this.#db, (): StatusCascadePlan => {
+    return this.#writeTransaction((): StatusCascadePlan => {
       const plan = this.#domain.planStatusCascade("task", id, status);
       this.#assertCascadeNotBlocked(plan);
       this.#applyStatusCascadePlan(plan);
@@ -308,10 +391,39 @@ export class MutationService {
     });
   }
 
-  deleteTask(id: string): void {
-    writeTransaction(this.#db, (): void => {
+  deleteTask(id: string): { deletedSubtaskIds: string[]; deletedDependencyIds: string[] } {
+    return this.#writeTransaction((): { deletedSubtaskIds: string[]; deletedDependencyIds: string[] } => {
+      const plan = this.#domain.planTaskDeletion(id);
       this.#domain.deleteTask(id);
-      this.#appendEntityEvent("task", id, ENTITY_OPERATIONS.task.deleted, {});
+      const taskDeleteEventId = this.#appendEntityEvent("task", id, ENTITY_OPERATIONS.task.deleted, {});
+
+      for (const subtaskId of plan.subtaskIds) {
+        this.#appendEntityEvent("subtask", subtaskId, ENTITY_OPERATIONS.subtask.deleted, {
+          task_id: id,
+          source_event_id: taskDeleteEventId,
+        });
+      }
+
+      for (const dependency of plan.touchingDependencies) {
+          this.#appendEntityEvent(
+            "dependency",
+            this.#dependencyEventEntityId(dependency),
+            ENTITY_OPERATIONS.dependency.removed,
+            this.#dependencyEventFields({
+              dependencyId: dependency.id,
+              sourceId: dependency.sourceId,
+              sourceKind: dependency.sourceKind,
+              dependsOnId: dependency.dependsOnId,
+              dependsOnKind: dependency.dependsOnKind,
+              sourceEventId: taskDeleteEventId,
+            }),
+          );
+      }
+
+      return {
+        deletedSubtaskIds: [...plan.subtaskIds],
+        deletedDependencyIds: plan.touchingDependencies.map((dependency) => dependency.id),
+      };
     });
   }
 
@@ -321,7 +433,7 @@ export class MutationService {
     description?: string | undefined;
     status?: string | undefined;
   }): SubtaskRecord {
-    return writeTransaction(this.#db, (): SubtaskRecord => {
+    return this.#writeTransaction((): SubtaskRecord => {
       const subtask = this.#domain.createSubtask(input);
       this.#appendEntityEvent("subtask", subtask.id, ENTITY_OPERATIONS.subtask.created, {
         task_id: subtask.taskId,
@@ -333,8 +445,32 @@ export class MutationService {
     });
   }
 
+  createSubtaskAtomicallyWithIdempotency(input: {
+    taskId: string;
+    title: string;
+    description?: string | undefined;
+    status?: string | undefined;
+    claim: AtomicIdempotencyClaim;
+    buildResponseData: (result: { subtask: SubtaskRecord; domain: TrackerDomain }) => Record<string, unknown>;
+  }): AtomicIdempotentMutationResult {
+    return this.#completeAtomicIdempotentMutation(input.claim, (): AtomicIdempotencyCompletedResult => {
+      const subtask = this.#domain.createSubtask(input);
+      this.#appendEntityEvent("subtask", subtask.id, ENTITY_OPERATIONS.subtask.created, {
+        task_id: subtask.taskId,
+        title: subtask.title,
+        description: subtask.description,
+        status: subtask.status,
+      });
+      return {
+        state: "completed",
+        status: 201,
+        responseData: input.buildResponseData({ subtask, domain: this.#domain }),
+      };
+    });
+  }
+
   createSubtaskBatch(input: { taskId: string; specs: readonly CompactSubtaskSpec[] }): CompactSubtaskBatchCreateResult {
-    return writeTransaction(this.#db, (): CompactSubtaskBatchCreateResult => {
+    return this.#writeTransaction((): CompactSubtaskBatchCreateResult => {
       const created = this.#domain.createSubtaskBatch(input);
       for (const subtask of created.subtasks) {
         this.#appendEntityEvent("subtask", subtask.id, ENTITY_OPERATIONS.subtask.created, {
@@ -352,7 +488,7 @@ export class MutationService {
     id: string,
     input: { title?: string | undefined; description?: string | undefined; status?: string | undefined; owner?: string | null | undefined },
   ): SubtaskRecord {
-    return writeTransaction(this.#db, (): SubtaskRecord => {
+    return this.#writeTransaction((): SubtaskRecord => {
       if (input.status !== undefined) {
         const existing = this.#domain.getSubtaskOrThrow(id);
         validateStatusTransition(existing.status, input.status, "subtask", id);
@@ -369,54 +505,224 @@ export class MutationService {
     });
   }
 
-  deleteSubtask(id: string): void {
-    writeTransaction(this.#db, (): void => {
+  deleteSubtask(id: string): { deletedDependencyIds: string[] } {
+    return this.#writeTransaction((): { deletedDependencyIds: string[] } => {
+      const touchingDependencies = this.#domain.listDependenciesTouchingNode(id);
       this.#domain.deleteSubtask(id);
-      this.#appendEntityEvent("subtask", id, ENTITY_OPERATIONS.subtask.deleted, {});
+      const subtaskDeleteEventId = this.#appendEntityEvent("subtask", id, ENTITY_OPERATIONS.subtask.deleted, {});
+      for (const dependency of touchingDependencies) {
+        this.#appendEntityEvent(
+          "dependency",
+          this.#dependencyEventEntityId(dependency),
+          ENTITY_OPERATIONS.dependency.removed,
+          this.#dependencyEventFields({
+            dependencyId: dependency.id,
+            sourceId: dependency.sourceId,
+            sourceKind: dependency.sourceKind,
+            dependsOnId: dependency.dependsOnId,
+            dependsOnKind: dependency.dependsOnKind,
+            sourceEventId: subtaskDeleteEventId,
+          }),
+        );
+      }
+      return {
+        deletedDependencyIds: touchingDependencies.map((dependency) => dependency.id),
+      };
+    });
+  }
+
+  deleteSubtaskAtomicallyWithIdempotency(input: {
+    id: string;
+    claim: AtomicIdempotencyClaim;
+    buildResponseData: (result: {
+      subtaskId: string;
+      deletedDependencyIds: string[];
+      domain: TrackerDomain;
+      taskId: string;
+      epicId: string;
+    }) => Record<string, unknown>;
+  }): AtomicIdempotentMutationResult {
+    return this.#completeAtomicIdempotentMutation(input.claim, (): AtomicIdempotencyCompletedResult => {
+      const existingSubtask = this.#domain.getSubtaskOrThrow(input.id);
+      const task = this.#domain.getTaskOrThrow(existingSubtask.taskId);
+      const touchingDependencies = this.#domain.listDependenciesTouchingNode(input.id);
+      this.#domain.deleteSubtask(input.id);
+      const subtaskDeleteEventId = this.#appendEntityEvent("subtask", input.id, ENTITY_OPERATIONS.subtask.deleted, {});
+      for (const dependency of touchingDependencies) {
+        this.#appendEntityEvent(
+          "dependency",
+          this.#dependencyEventEntityId(dependency),
+          ENTITY_OPERATIONS.dependency.removed,
+          this.#dependencyEventFields({
+            dependencyId: dependency.id,
+            sourceId: dependency.sourceId,
+            sourceKind: dependency.sourceKind,
+            dependsOnId: dependency.dependsOnId,
+            dependsOnKind: dependency.dependsOnKind,
+            sourceEventId: subtaskDeleteEventId,
+          }),
+        );
+      }
+
+      return {
+        state: "completed",
+        status: 200,
+        responseData: input.buildResponseData({
+          subtaskId: input.id,
+          deletedDependencyIds: touchingDependencies.map((dependency) => dependency.id),
+          domain: this.#domain,
+          taskId: task.id,
+          epicId: task.epicId,
+        }),
+      };
     });
   }
 
   addDependency(sourceId: string, dependsOnId: string): DependencyRecord {
-    return writeTransaction(this.#db, (): DependencyRecord => {
+    return this.#writeTransaction((): DependencyRecord => {
       const dependency = this.#domain.addDependency(sourceId, dependsOnId);
-      this.#appendEntityEvent("dependency", dependency.id, ENTITY_OPERATIONS.dependency.added, {
-        source_id: dependency.sourceId,
-        source_kind: dependency.sourceKind,
-        depends_on_id: dependency.dependsOnId,
-        depends_on_kind: dependency.dependsOnKind,
-      });
+      this.#appendEntityEvent(
+        "dependency",
+        this.#dependencyEventEntityId(dependency),
+        ENTITY_OPERATIONS.dependency.added,
+        this.#dependencyEventFields({
+          dependencyId: dependency.id,
+          sourceId: dependency.sourceId,
+          sourceKind: dependency.sourceKind,
+          dependsOnId: dependency.dependsOnId,
+          dependsOnKind: dependency.dependsOnKind,
+        }),
+      );
       return dependency;
     });
   }
 
+  addDependencyAtomicallyWithIdempotency(input: {
+    sourceId: string;
+    dependsOnId: string;
+    claim: AtomicIdempotencyClaim;
+    buildResponseData: (result: { dependency: DependencyRecord; domain: TrackerDomain }) => Record<string, unknown>;
+  }): AtomicIdempotentMutationResult {
+    return this.#completeAtomicIdempotentMutation(input.claim, (): AtomicIdempotencyCompletedResult => {
+      const dependency = this.#domain.addDependency(input.sourceId, input.dependsOnId);
+      this.#appendEntityEvent(
+        "dependency",
+        this.#dependencyEventEntityId(dependency),
+        ENTITY_OPERATIONS.dependency.added,
+        this.#dependencyEventFields({
+          dependencyId: dependency.id,
+          sourceId: dependency.sourceId,
+          sourceKind: dependency.sourceKind,
+          dependsOnId: dependency.dependsOnId,
+          dependsOnKind: dependency.dependsOnKind,
+        }),
+      );
+      return {
+        state: "completed",
+        status: 201,
+        responseData: input.buildResponseData({ dependency, domain: this.#domain }),
+      };
+    });
+  }
+
   addDependencyBatch(input: { specs: readonly CompactDependencySpec[] }): CompactDependencyBatchAddResult {
-    return writeTransaction(this.#db, (): CompactDependencyBatchAddResult => {
+    return this.#writeTransaction((): CompactDependencyBatchAddResult => {
       const created = this.#domain.addDependencyBatch(input);
       for (const dependency of created.dependencies) {
-        this.#appendEntityEvent("dependency", dependency.id, ENTITY_OPERATIONS.dependency.added, {
-          source_id: dependency.sourceId,
-          source_kind: dependency.sourceKind,
-          depends_on_id: dependency.dependsOnId,
-          depends_on_kind: dependency.dependsOnKind,
-        });
+        this.#appendEntityEvent(
+          "dependency",
+          this.#dependencyEventEntityId(dependency),
+          ENTITY_OPERATIONS.dependency.added,
+          this.#dependencyEventFields({
+            dependencyId: dependency.id,
+            sourceId: dependency.sourceId,
+            sourceKind: dependency.sourceKind,
+            dependsOnId: dependency.dependsOnId,
+            dependsOnKind: dependency.dependsOnKind,
+          }),
+        );
       }
       return created;
     });
   }
 
   removeDependency(sourceId: string, dependsOnId: string): number {
-    return writeTransaction(this.#db, (): number => {
+    return this.#writeTransaction((): number => {
+      const existingDependency = this.#domain.listDependencies(sourceId)
+        .find((dependency) => dependency.dependsOnId === dependsOnId);
       const removed = this.#domain.removeDependency(sourceId, dependsOnId);
       if (removed > 0) {
-        this.#appendEntityEvent("dependency", `${sourceId}->${dependsOnId}`, ENTITY_OPERATIONS.dependency.removed, {
-          source_id: sourceId,
-          depends_on_id: dependsOnId,
-        });
+        this.#appendEntityEvent("dependency", this.#dependencyEventEntityId({
+          sourceId,
+          sourceKind: existingDependency?.sourceKind ?? "task",
+          dependsOnId,
+          dependsOnKind: existingDependency?.dependsOnKind ?? "task",
+        }), ENTITY_OPERATIONS.dependency.removed, this.#dependencyEventFields({
+          dependencyId: existingDependency?.id,
+          sourceId,
+          sourceKind: existingDependency?.sourceKind,
+          dependsOnId,
+          dependsOnKind: existingDependency?.dependsOnKind,
+        }));
       }
       return removed;
     });
   }
 
+  removeDependencyAtomicallyWithIdempotency(input: {
+    sourceId: string;
+    dependsOnId: string;
+    claim: AtomicIdempotencyClaim;
+    buildResponseData: (result: {
+      sourceId: string;
+      dependsOnId: string;
+      removed: number;
+      existingDependencyIds: string[];
+      domain: TrackerDomain;
+    }) => Record<string, unknown>;
+  }): AtomicIdempotentMutationResult {
+    return this.#completeAtomicIdempotentMutation(input.claim, (): AtomicIdempotencyCompletedResult => {
+      const existingDependencies = this.#domain.listDependencies(input.sourceId)
+        .filter((dependency) => dependency.dependsOnId === input.dependsOnId);
+      const existingDependencyIds = existingDependencies.map((dependency) => dependency.id);
+      const existingDependency = existingDependencies[0];
+      const removed = this.#domain.removeDependency(input.sourceId, input.dependsOnId);
+      if (removed === 0) {
+        throw new DomainError({
+          code: "not_found",
+          message: "Dependency edge not found",
+          details: {
+            sourceId: input.sourceId,
+            dependsOnId: input.dependsOnId,
+          },
+        });
+      }
+      this.#appendEntityEvent("dependency", this.#dependencyEventEntityId({
+        sourceId: input.sourceId,
+        sourceKind: existingDependency?.sourceKind ?? "task",
+        dependsOnId: input.dependsOnId,
+        dependsOnKind: existingDependency?.dependsOnKind ?? "task",
+      }), ENTITY_OPERATIONS.dependency.removed, this.#dependencyEventFields({
+        dependencyId: existingDependency?.id,
+        sourceId: input.sourceId,
+        sourceKind: existingDependency?.sourceKind,
+        dependsOnId: input.dependsOnId,
+        dependsOnKind: existingDependency?.dependsOnKind,
+      }));
+      return {
+        state: "completed",
+        status: 200,
+        responseData: input.buildResponseData({
+          sourceId: input.sourceId,
+          dependsOnId: input.dependsOnId,
+          removed,
+          existingDependencyIds,
+          domain: this.#domain,
+        }),
+      };
+    });
+  }
+
   describeError(error: unknown): string | undefined {
     if (!(error instanceof DomainError)) {
       return undefined;
@@ -523,8 +829,8 @@ export class MutationService {
     entityId: string,
     operation: string,
     fields: Record<string, unknown>,
-  ): void {
-    appendEventWithGitContext(this.#db, this.#cwd, {
+  ): string {
+    return appendEventWithGitContext(this.#db, this.#cwd, {
       entityKind,
       entityId,
       operation,
@@ -532,6 +838,98 @@ export class MutationService {
     });
   }
 
+  #completeAtomicIdempotentMutation(
+    claim: AtomicIdempotencyClaim,
+    mutate: () => AtomicIdempotencyCompletedResult,
+  ): AtomicIdempotentMutationResult {
+    return this.#writeTransaction((): AtomicIdempotentMutationResult => {
+      this.#pruneExpiredIdempotencyKeys();
+      const inserted = this.#db.query(
+        `
+        INSERT INTO board_idempotency_keys (
+          scope,
+          idempotency_key,
+          request_fingerprint,
+          state,
+          response_status,
+          response_body,
+          created_at
+        ) VALUES (?, ?, ?, 'pending', 0, '{}', ?)
+        ON CONFLICT(scope, idempotency_key) DO NOTHING
+        `,
+      ).run(claim.scope, claim.idempotencyKey, claim.requestFingerprint, Date.now());
+
+      if (inserted.changes === 0) {
+        const row = this.#db.query(
+          `
+          SELECT request_fingerprint, response_status, response_body
+          FROM board_idempotency_keys
+          WHERE scope = ? AND idempotency_key = ?
+          `,
+        ).get(claim.scope, claim.idempotencyKey) as {
+          request_fingerprint: string;
+          response_status: number;
+          response_body: string;
+        } | null;
+
+        if (!row) {
+          throw new DomainError({
+            code: "invalid_input",
+            message: "Idempotency claim changed while processing request; retry the request",
+          });
+        }
+
+        if (row.request_fingerprint !== claim.requestFingerprint) {
+          throw new DomainError({
+            code: "invalid_input",
+            message: claim.conflictMessage,
+            details: { field: "clientRequestId" },
+          });
+        }
+
+        if (row.response_status === 0) {
+          throw new DomainError({
+            code: "invalid_input",
+            message: "Idempotency record is incomplete; retry the request with a new idempotency key",
+            details: { field: "clientRequestId" },
+          });
+        }
+
+        return {
+          state: "replay",
+          status: row.response_status,
+          responseData: JSON.parse(row.response_body) as Record<string, unknown>,
+        };
+      }
+
+      const result = mutate();
+      this.#db.query(
+        `
+        UPDATE board_idempotency_keys
+        SET state = 'completed',
+            response_status = ?,
+            response_body = ?,
+            created_at = ?
+        WHERE scope = ?
+          AND idempotency_key = ?
+          AND request_fingerprint = ?
+        `,
+      ).run(result.status, JSON.stringify(result.responseData), Date.now(), claim.scope, claim.idempotencyKey, claim.requestFingerprint);
+      return result;
+    });
+  }
+
+  #pruneExpiredIdempotencyKeys(now: number = Date.now()): void {
+    const cutoff: number = now - BOARD_IDEMPOTENCY_RETENTION_MS;
+    this.#db.query(
+      `
+      DELETE FROM board_idempotency_keys
+      WHERE state = 'completed'
+        AND created_at < ?;
+      `,
+    ).run(cutoff);
+  }
+
   #previewScopeReplacement(
     nodes: readonly SearchNode[],
     searchText: string,
@@ -607,7 +1005,7 @@ export class MutationService {
   ): ScopeReplacementResult {
     const result = this.#buildScopeReplacementResult(nodes, searchText, replacementText, fields, "apply");
 
-    writeTransaction(this.#db, (): void => {
+    this.#writeTransaction((): void => {
       for (const node of nodes) {
         const nextTitle = fields.includes("title") ? replaceMatches(node.title, searchText, replacementText) : node.title;
         const nextDescription = fields.includes("description")