trekoon 0.3.5 → 0.3.7

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, withTransactionEventContext } from "../sync/event-writes";
 import { ENTITY_OPERATIONS } from "./mutation-operations";
 import { TrackerDomain, validateStatusTransition } from "./tracker-domain";
 import {
@@ -26,6 +26,29 @@ 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;
+
 function countMatches(value: string, searchText: string): number {
   if (searchText.length === 0) {
     return 0;
@@ -104,8 +127,12 @@ export class MutationService {
     this.#domain = new TrackerDomain(db);
   }
 
+  #writeTransaction<T>(fn: () => T): T {
+    return writeTransaction(this.#db, (): T => withTransactionEventContext(this.#db, this.#cwd, fn));
+  }
+
   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 +151,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,
@@ -180,7 +207,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 +223,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 +232,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 +252,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 +272,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, {
@@ -282,7 +309,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 +327,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 +335,36 @@ 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",
+          `${dependency.sourceId}->${dependency.dependsOnId}`,
+          ENTITY_OPERATIONS.dependency.removed,
+          {
+            source_id: dependency.sourceId,
+            depends_on_id: dependency.dependsOnId,
+            source_event_id: taskDeleteEventId,
+          },
+        );
+      }
+
+      return {
+        deletedSubtaskIds: [...plan.subtaskIds],
+        deletedDependencyIds: plan.touchingDependencies.map((dependency) => dependency.id),
+      };
     });
   }
 
@@ -321,7 +374,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 +386,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 +429,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,15 +446,75 @@ 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",
+          `${dependency.sourceId}->${dependency.dependsOnId}`,
+          ENTITY_OPERATIONS.dependency.removed,
+          {
+            source_id: dependency.sourceId,
+            depends_on_id: dependency.dependsOnId,
+            source_event_id: 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",
+          `${dependency.sourceId}->${dependency.dependsOnId}`,
+          ENTITY_OPERATIONS.dependency.removed,
+          {
+            source_id: dependency.sourceId,
+            depends_on_id: dependency.dependsOnId,
+            source_event_id: 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,
@@ -389,8 +526,30 @@ export class MutationService {
     });
   }
 
+  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", dependency.id, ENTITY_OPERATIONS.dependency.added, {
+        source_id: dependency.sourceId,
+        source_kind: dependency.sourceKind,
+        depends_on_id: dependency.dependsOnId,
+        depends_on_kind: 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, {
@@ -405,7 +564,7 @@ export class MutationService {
   }
 
   removeDependency(sourceId: string, dependsOnId: string): number {
-    return writeTransaction(this.#db, (): number => {
+    return this.#writeTransaction((): number => {
       const removed = this.#domain.removeDependency(sourceId, dependsOnId);
       if (removed > 0) {
         this.#appendEntityEvent("dependency", `${sourceId}->${dependsOnId}`, ENTITY_OPERATIONS.dependency.removed, {
@@ -417,6 +576,51 @@ export class MutationService {
     });
   }
 
+  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 existingDependencyIds = this.#domain.listDependencies(input.sourceId)
+        .filter((dependency) => dependency.dependsOnId === input.dependsOnId)
+        .map((dependency) => dependency.id);
+      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", `${input.sourceId}->${input.dependsOnId}`, ENTITY_OPERATIONS.dependency.removed, {
+        source_id: input.sourceId,
+        depends_on_id: input.dependsOnId,
+      });
+      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 +727,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 +736,86 @@ export class MutationService {
     });
   }
 
+  #completeAtomicIdempotentMutation(
+    claim: AtomicIdempotencyClaim,
+    mutate: () => AtomicIdempotencyCompletedResult,
+  ): AtomicIdempotentMutationResult {
+    return this.#writeTransaction((): AtomicIdempotentMutationResult => {
+      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;
+    });
+  }
+
   #previewScopeReplacement(
     nodes: readonly SearchNode[],
     searchText: string,
@@ -607,7 +891,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")