@sonamu-kit/tasks 0.2.0 → 0.3.0

package/src/database/backend.testsuite.ts

@@ -1,9 +1,11 @@
 import { randomUUID } from "node:crypto";
+
 import { afterAll, beforeAll, describe, expect, test } from "vitest";
-import type { Backend } from "..//backend";
-import type { SerializableRetryPolicy } from "../core/retry";
-import type { StepAttempt } from "../core/step";
-import type { WorkflowRun } from "../core/workflow";
+
+import { type Backend } from "..//backend";
+import { type SerializableRetryPolicy } from "../core/retry";
+import { type StepAttempt } from "../core/step";
+import { type WorkflowRun } from "../core/workflow";
 
 /**
  * Options for the Backend test suite.
@@ -138,7 +140,7 @@ export function testBackend(options: TestBackendOptions): void {
         // p2
         const page2 = await backend.listWorkflowRuns({
           limit: 2,
-          // biome-ignore lint/style/noNonNullAssertion: for test
+          // oxlint-disable-next-line @typescript-eslint/no-non-null-assertion -- for test
           after: page1.pagination.next!,
         });
         expect(page2.data).toHaveLength(2);
@@ -150,7 +152,7 @@ export function testBackend(options: TestBackendOptions): void {
         // p3
         const page3 = await backend.listWorkflowRuns({
           limit: 2,
-          // biome-ignore lint/style/noNonNullAssertion: for test
+          // oxlint-disable-next-line @typescript-eslint/no-non-null-assertion -- for test
           after: page2.pagination.next!,
         });
         expect(page3.data).toHaveLength(1);
@@ -161,7 +163,7 @@ export function testBackend(options: TestBackendOptions): void {
         // p2 again
         const page2Back = await backend.listWorkflowRuns({
           limit: 2,
-          // biome-ignore lint/style/noNonNullAssertion: for test
+          // oxlint-disable-next-line @typescript-eslint/no-non-null-assertion -- for test
           before: page3.pagination.prev!,
         });
         expect(page2Back.data).toHaveLength(2);
@@ -203,7 +205,7 @@ export function testBackend(options: TestBackendOptions): void {
 
         const page2 = await backend.listWorkflowRuns({
           limit: 2,
-          // biome-ignore lint/style/noNonNullAssertion: for test
+          // oxlint-disable-next-line @typescript-eslint/no-non-null-assertion -- for test
           after: page1.pagination.next!,
         });
         expect(page2.data).toHaveLength(2);
@@ -213,7 +215,7 @@ export function testBackend(options: TestBackendOptions): void {
 
         const page3 = await backend.listWorkflowRuns({
           limit: 2,
-          // biome-ignore lint/style/noNonNullAssertion: for test
+          // oxlint-disable-next-line @typescript-eslint/no-non-null-assertion -- for test
           after: page2.pagination.next!,
         });
         expect(page3.data).toHaveLength(1);
@@ -222,7 +224,7 @@ export function testBackend(options: TestBackendOptions): void {
 
         const page2Back = await backend.listWorkflowRuns({
           limit: 2,
-          // biome-ignore lint/style/noNonNullAssertion: for test
+          // oxlint-disable-next-line @typescript-eslint/no-non-null-assertion -- for test
           before: page3.pagination.prev!,
         });
         expect(page2Back.data).toHaveLength(2);
@@ -678,7 +680,7 @@ export function testBackend(options: TestBackendOptions): void {
 
         const created = await backend.createStepAttempt({
           workflowRunId: expected.workflowRunId,
-          // biome-ignore lint/style/noNonNullAssertion: for test
+          // oxlint-disable-next-line @typescript-eslint/no-non-null-assertion -- for test
           workerId: workflowRun.workerId!,
           stepName: expected.stepName,
           kind: expected.kind,
@@ -704,7 +706,7 @@ export function testBackend(options: TestBackendOptions): void {
 
         const created = await backend.createStepAttempt({
           workflowRunId: claimed.id,
-          // biome-ignore lint/style/noNonNullAssertion: for test
+          // oxlint-disable-next-line @typescript-eslint/no-non-null-assertion -- for test
           workerId: claimed.workerId!,
           stepName: randomUUID(),
           kind: "function",
@@ -733,7 +735,7 @@ export function testBackend(options: TestBackendOptions): void {
 
         const first = await backend.createStepAttempt({
           workflowRunId: claimed.id,
-          // biome-ignore lint/style/noNonNullAssertion: for test
+          // oxlint-disable-next-line @typescript-eslint/no-non-null-assertion -- for test
           workerId: claimed.workerId!,
           stepName: randomUUID(),
           kind: "function",
@@ -743,7 +745,7 @@ export function testBackend(options: TestBackendOptions): void {
         await backend.completeStepAttempt({
           workflowRunId: claimed.id,
           stepAttemptId: first.id,
-          // biome-ignore lint/style/noNonNullAssertion: for test
+          // oxlint-disable-next-line @typescript-eslint/no-non-null-assertion -- for test
           workerId: claimed.workerId!,
           output: { ok: true },
         });
@@ -752,7 +754,7 @@ export function testBackend(options: TestBackendOptions): void {
 
         const second = await backend.createStepAttempt({
           workflowRunId: claimed.id,
-          // biome-ignore lint/style/noNonNullAssertion: for test
+          // oxlint-disable-next-line @typescript-eslint/no-non-null-assertion -- for test
           workerId: claimed.workerId!,
           stepName: randomUUID(),
           kind: "function",
@@ -773,7 +775,7 @@ export function testBackend(options: TestBackendOptions): void {
         for (let i = 0; i < 5; i++) {
           await backend.createStepAttempt({
             workflowRunId: claimed.id,
-            // biome-ignore lint/style/noNonNullAssertion: for test
+            // oxlint-disable-next-line @typescript-eslint/no-non-null-assertion -- for test
             workerId: claimed.workerId!,
             stepName: `step-${String(i)}`,
             kind: "function",
@@ -799,7 +801,7 @@ export function testBackend(options: TestBackendOptions): void {
         const page2 = await backend.listStepAttempts({
           workflowRunId: claimed.id,
           limit: 2,
-          // biome-ignore lint/style/noNonNullAssertion: for test
+          // oxlint-disable-next-line @typescript-eslint/no-non-null-assertion -- for test
           after: page1.pagination.next!,
         });
         expect(page2.data).toHaveLength(2);
@@ -812,7 +814,7 @@ export function testBackend(options: TestBackendOptions): void {
         const page3 = await backend.listStepAttempts({
           workflowRunId: claimed.id,
           limit: 2,
-          // biome-ignore lint/style/noNonNullAssertion: for test
+          // oxlint-disable-next-line @typescript-eslint/no-non-null-assertion -- for test
           after: page2.pagination.next!,
         });
         expect(page3.data).toHaveLength(1);
@@ -824,7 +826,7 @@ export function testBackend(options: TestBackendOptions): void {
         const page2Back = await backend.listStepAttempts({
           workflowRunId: claimed.id,
           limit: 2,
-          // biome-ignore lint/style/noNonNullAssertion: for test
+          // oxlint-disable-next-line @typescript-eslint/no-non-null-assertion -- for test
           before: page3.pagination.prev!,
         });
         expect(page2Back.data).toHaveLength(2);
@@ -848,7 +850,7 @@ export function testBackend(options: TestBackendOptions): void {
         const claimed = await createClaimedWorkflowRun(backend);
         await backend.createStepAttempt({
           workflowRunId: claimed.id,
-          // biome-ignore lint/style/noNonNullAssertion: for test
+          // oxlint-disable-next-line @typescript-eslint/no-non-null-assertion -- for test
           workerId: claimed.workerId!,
           stepName: "step-1",
           kind: "function",
@@ -880,7 +882,7 @@ export function testBackend(options: TestBackendOptions): void {
 
         const created = await backend.createStepAttempt({
           workflowRunId: claimed.id,
-          // biome-ignore lint/style/noNonNullAssertion: for test
+          // oxlint-disable-next-line @typescript-eslint/no-non-null-assertion -- for test
           workerId: claimed.workerId!,
           stepName: randomUUID(),
           kind: "function",
@@ -892,15 +894,16 @@ export function testBackend(options: TestBackendOptions): void {
         const completed = await backend.completeStepAttempt({
           workflowRunId: claimed.id,
           stepAttemptId: created.id,
-          // biome-ignore lint/style/noNonNullAssertion: for test
+          // oxlint-disable-next-line @typescript-eslint/no-non-null-assertion -- for test
           workerId: claimed.workerId!,
           output,
         });
 
-        expect(completed.status).toBe("completed");
-        expect(completed.output).toEqual(output);
-        expect(completed.error).toBeNull();
-        expect(completed.finishedAt).not.toBeNull();
+        expect(completed).not.toBeNull();
+        expect(completed?.status).toBe("completed");
+        expect(completed?.output).toEqual(output);
+        expect(completed?.error).toBeNull();
+        expect(completed?.finishedAt).not.toBeNull();
 
         const fetched = await backend.getStepAttempt({
           stepAttemptId: created.id,
@@ -924,7 +927,7 @@ export function testBackend(options: TestBackendOptions): void {
 
         const stepAttempt = await backend.createStepAttempt({
           workflowRunId: claimed.id,
-          // biome-ignore lint/style/noNonNullAssertion: for test
+          // oxlint-disable-next-line @typescript-eslint/no-non-null-assertion -- for test
           workerId: claimed.workerId!,
           stepName: randomUUID(),
           kind: "function",
@@ -935,7 +938,7 @@ export function testBackend(options: TestBackendOptions): void {
         // complete the workflow so it's no longer running
         await backend.completeWorkflowRun({
           workflowRunId: claimed.id,
-          // biome-ignore lint/style/noNonNullAssertion: for test
+          // oxlint-disable-next-line @typescript-eslint/no-non-null-assertion -- for test
           workerId: claimed.workerId!,
           output: null,
         });
@@ -945,7 +948,7 @@ export function testBackend(options: TestBackendOptions): void {
           backend.completeStepAttempt({
             workflowRunId: claimed.id,
             stepAttemptId: stepAttempt.id,
-            // biome-ignore lint/style/noNonNullAssertion: for test
+            // oxlint-disable-next-line @typescript-eslint/no-non-null-assertion -- for test
             workerId: claimed.workerId!,
             output: { foo: "bar" },
           }),
@@ -962,7 +965,7 @@ export function testBackend(options: TestBackendOptions): void {
           backend.completeStepAttempt({
             workflowRunId: claimed.id,
             stepAttemptId: randomUUID(),
-            // biome-ignore lint/style/noNonNullAssertion: for test
+            // oxlint-disable-next-line @typescript-eslint/no-non-null-assertion -- for test
             workerId: claimed.workerId!,
             output: { foo: "bar" },
           }),
@@ -986,7 +989,7 @@ export function testBackend(options: TestBackendOptions): void {
 
         const created = await backend.createStepAttempt({
           workflowRunId: claimed.id,
-          // biome-ignore lint/style/noNonNullAssertion: for test
+          // oxlint-disable-next-line @typescript-eslint/no-non-null-assertion -- for test
           workerId: claimed.workerId!,
           stepName: randomUUID(),
           kind: "function",
@@ -998,15 +1001,16 @@ export function testBackend(options: TestBackendOptions): void {
         const failed = await backend.failStepAttempt({
           workflowRunId: claimed.id,
           stepAttemptId: created.id,
-          // biome-ignore lint/style/noNonNullAssertion: for test
+          // oxlint-disable-next-line @typescript-eslint/no-non-null-assertion -- for test
           workerId: claimed.workerId!,
           error,
         });
 
-        expect(failed.status).toBe("failed");
-        expect(failed.error).toEqual(error);
-        expect(failed.output).toBeNull();
-        expect(failed.finishedAt).not.toBeNull();
+        expect(failed).not.toBeNull();
+        expect(failed?.status).toBe("failed");
+        expect(failed?.error).toEqual(error);
+        expect(failed?.output).toBeNull();
+        expect(failed?.finishedAt).not.toBeNull();
 
         const fetched = await backend.getStepAttempt({
           stepAttemptId: created.id,
@@ -1030,7 +1034,7 @@ export function testBackend(options: TestBackendOptions): void {
 
         const stepAttempt = await backend.createStepAttempt({
           workflowRunId: claimed.id,
-          // biome-ignore lint/style/noNonNullAssertion: for test
+          // oxlint-disable-next-line @typescript-eslint/no-non-null-assertion -- for test
           workerId: claimed.workerId!,
           stepName: randomUUID(),
           kind: "function",
@@ -1041,7 +1045,7 @@ export function testBackend(options: TestBackendOptions): void {
         // complete the workflow so it's no longer running
         await backend.completeWorkflowRun({
           workflowRunId: claimed.id,
-          // biome-ignore lint/style/noNonNullAssertion: for test
+          // oxlint-disable-next-line @typescript-eslint/no-non-null-assertion -- for test
           workerId: claimed.workerId!,
           output: null,
         });
@@ -1051,7 +1055,7 @@ export function testBackend(options: TestBackendOptions): void {
           backend.failStepAttempt({
             workflowRunId: claimed.id,
             stepAttemptId: stepAttempt.id,
-            // biome-ignore lint/style/noNonNullAssertion: for test
+            // oxlint-disable-next-line @typescript-eslint/no-non-null-assertion -- for test
             workerId: claimed.workerId!,
             error: { message: "nope" },
           }),
@@ -1068,7 +1072,7 @@ export function testBackend(options: TestBackendOptions): void {
           backend.failStepAttempt({
             workflowRunId: claimed.id,
             stepAttemptId: randomUUID(),
-            // biome-ignore lint/style/noNonNullAssertion: for test
+            // oxlint-disable-next-line @typescript-eslint/no-non-null-assertion -- for test
             workerId: claimed.workerId!,
             error: { message: "nope" },
           }),

package/src/database/backend.ts

@@ -1,6 +1,9 @@
 import { getLogger } from "@logtape/logtape";
 import { camelize } from "inflection";
-import knex, { type Knex } from "knex";
+import knex from "knex";
+import { type Knex } from "knex";
+
+import { DEFAULT_NAMESPACE_ID } from "../backend";
 import {
   type Backend,
   type CancelWorkflowRunParams,
@@ -9,7 +12,6 @@ import {
   type CompleteWorkflowRunParams,
   type CreateStepAttemptParams,
   type CreateWorkflowRunParams,
-  DEFAULT_NAMESPACE_ID,
   type ExtendWorkflowRunLeaseParams,
   type FailStepAttemptParams,
   type FailWorkflowRunParams,
@@ -18,13 +20,17 @@ import {
   type ListStepAttemptsParams,
   type ListWorkflowRunsParams,
   type PaginatedResponse,
+  type PauseWorkflowRunParams,
+  type ResumeWorkflowRunParams,
   type SleepWorkflowRunParams,
 } from "../backend";
-import { mergeRetryPolicy, type SerializableRetryPolicy } from "../core/retry";
-import type { StepAttempt } from "../core/step";
-import type { WorkflowRun } from "../core/workflow";
+import { mergeRetryPolicy } from "../core/retry";
+import { type SerializableRetryPolicy } from "../core/retry";
+import { type StepAttempt } from "../core/step";
+import { type WorkflowRun } from "../core/workflow";
 import { DEFAULT_SCHEMA, migrate } from "./base";
-import { type OnSubscribed, PostgresPubSub } from "./pubsub";
+import { PostgresPubSub } from "./pubsub";
+import { type OnSubscribed } from "./pubsub";
 
 export const DEFAULT_LISTEN_CHANNEL = "new_tasks" as const;
 const DEFAULT_PAGINATION_PAGE_SIZE = 100 as const;
@@ -155,6 +161,8 @@ export class BackendPostgres implements Backend {
     await this.pubsub?.destroy();
     this.pubsub = null;
     await this.knex.destroy();
+    this._knex = null;
+    this.initialized = false;
   }
 
   async createWorkflowRun(params: CreateWorkflowRunParams): Promise<WorkflowRun> {
@@ -253,6 +261,8 @@ export class BackendPostgres implements Backend {
     });
     const limit = params.limit ?? DEFAULT_PAGINATION_PAGE_SIZE;
     const { after, before } = params;
+    const order = params.order ?? "asc";
+    const reverseOrder = order === "asc" ? "desc" : "asc";
 
     let cursor: Cursor | null = null;
     if (after) {
@@ -261,10 +271,10 @@ export class BackendPostgres implements Backend {
       cursor = decodeCursor(before);
     }
 
-    const qb = this.buildListWorkflowRunsWhere(params, cursor);
+    const qb = this.buildListWorkflowRunsWhere(params, cursor, order);
     const rows = await qb
-      .orderBy("created_at", before ? "desc" : "asc")
-      .orderBy("id", before ? "desc" : "asc")
+      .orderBy("created_at", before ? reverseOrder : order)
+      .orderBy("id", before ? reverseOrder : order)
       .limit(limit + 1);
 
     return this.processPaginationResults(
@@ -275,7 +285,11 @@ export class BackendPostgres implements Backend {
     );
   }
 
-  private buildListWorkflowRunsWhere(params: ListWorkflowRunsParams, cursor: Cursor | null) {
+  private buildListWorkflowRunsWhere(
+    params: ListWorkflowRunsParams,
+    cursor: Cursor | null,
+    order: "asc" | "desc",
+  ) {
     const { after } = params;
     const qb = this.knex
       .withSchema(DEFAULT_SCHEMA)
@@ -283,13 +297,28 @@ export class BackendPostgres implements Backend {
       .where("namespace_id", this.namespaceId);
 
     if (cursor) {
-      const operator = after ? ">" : "<";
-      return qb.whereRaw(`("created_at", "id") ${operator} (?, ?)`, [
+      // asc: after → ">", before → "<"
+      // desc: after → "<", before → ">"
+      const operator = (order === "asc") === !!after ? ">" : "<";
+      qb.whereRaw(`("created_at", "id") ${operator} (?, ?)`, [
         cursor.createdAt.toISOString(),
         cursor.id,
       ]);
     }
 
+    if (params.status && params.status.length > 0) {
+      qb.whereIn("status", params.status);
+    }
+    if (params.workflowName) {
+      qb.where("workflow_name", params.workflowName);
+    }
+    if (params.createdAfter) {
+      qb.where("created_at", ">=", params.createdAfter);
+    }
+    if (params.createdBefore) {
+      qb.where("created_at", "<=", params.createdBefore);
+    }
+
     return qb;
   }
 
@@ -381,6 +410,11 @@ export class BackendPostgres implements Backend {
       .returning("*");
 
     if (!updated) {
+      const wr = await this.getWorkflowRun({ workflowRunId: params.workflowRunId });
+      if (wr && (wr.status === "paused" || wr.status === "canceled")) {
+        throw new Error("Workflow run is paused or canceled");
+      }
+
       logger.error("Failed to extend lease for workflow run: {params}", { params });
       throw new Error("Failed to extend lease for workflow run");
     }
@@ -575,7 +609,7 @@ export class BackendPostgres implements Backend {
       .table("workflow_runs")
       .where("namespace_id", this.namespaceId)
       .where("id", params.workflowRunId)
-      .whereIn("status", ["pending", "running", "sleeping"])
+      .whereIn("status", ["pending", "running", "sleeping", "paused"])
       .update({
         status: "canceled",
         worker_id: null,
@@ -618,6 +652,111 @@ export class BackendPostgres implements Backend {
     return updated;
   }
 
+  async pauseWorkflowRun(params: PauseWorkflowRunParams): Promise<WorkflowRun> {
+    if (!this.initialized) {
+      throw new Error("Backend not initialized");
+    }
+
+    logger.info("Pausing workflow run: {workflowRunId}", { workflowRunId: params.workflowRunId });
+
+    const [updated] = await this.knex
+      .withSchema(DEFAULT_SCHEMA)
+      .table("workflow_runs")
+      .where("namespace_id", this.namespaceId)
+      .where("id", params.workflowRunId)
+      .whereIn("status", ["pending", "running", "sleeping"])
+      .update({
+        status: "paused",
+        worker_id: null,
+        available_at: null,
+        updated_at: this.knex.fn.now(),
+      })
+      .returning("*");
+
+    if (!updated) {
+      const existing = await this.getWorkflowRun({
+        workflowRunId: params.workflowRunId,
+      });
+      if (!existing) {
+        throw new Error(`Workflow run ${params.workflowRunId} does not exist`);
+      }
+
+      // 이미 paused이면 멱등하게 반환합니다.
+      if (existing.status === "paused") {
+        return existing;
+      }
+
+      // 터미널 상태에서는 pause할 수 없습니다.
+      // 'succeeded' status is deprecated
+      if (["succeeded", "completed", "failed", "canceled"].includes(existing.status)) {
+        logger.error("Cannot pause workflow run: {params} with status {status}", {
+          params,
+          status: existing.status,
+        });
+        throw new Error(
+          `Cannot pause workflow run ${params.workflowRunId} with status ${existing.status}`,
+        );
+      }
+
+      logger.error("Failed to pause workflow run: {params}", { params });
+      throw new Error("Failed to pause workflow run");
+    }
+
+    return updated;
+  }
+
+  async resumeWorkflowRun(params: ResumeWorkflowRunParams): Promise<WorkflowRun> {
+    if (!this.initialized) {
+      throw new Error("Backend not initialized");
+    }
+
+    logger.info("Resuming workflow run: {workflowRunId}", { workflowRunId: params.workflowRunId });
+
+    const [updated] = await this.knex
+      .withSchema(DEFAULT_SCHEMA)
+      .table("workflow_runs")
+      .where("namespace_id", this.namespaceId)
+      .where("id", params.workflowRunId)
+      .where("status", "paused")
+      .update({
+        status: "pending",
+        available_at: this.knex.fn.now(),
+        updated_at: this.knex.fn.now(),
+      })
+      .returning("*");
+
+    if (!updated) {
+      const existing = await this.getWorkflowRun({
+        workflowRunId: params.workflowRunId,
+      });
+      if (!existing) {
+        throw new Error(`Workflow run ${params.workflowRunId} does not exist`);
+      }
+
+      // 이미 pending/running이면 멱등하게 반환합니다.
+      if (existing.status === "pending" || existing.status === "running") {
+        return existing;
+      }
+
+      // 터미널 상태에서는 resume할 수 없습니다.
+      // 'succeeded' status is deprecated
+      if (["succeeded", "completed", "failed", "canceled"].includes(existing.status)) {
+        logger.error("Cannot resume workflow run: {params} with status {status}", {
+          params,
+          status: existing.status,
+        });
+        throw new Error(
+          `Cannot resume workflow run ${params.workflowRunId} with status ${existing.status}`,
+        );
+      }
+
+      logger.error("Failed to resume workflow run: {params}", { params });
+      throw new Error("Failed to resume workflow run");
+    }
+
+    return updated;
+  }
+
   async createStepAttempt(params: CreateStepAttemptParams): Promise<StepAttempt> {
     if (!this.initialized) {
       throw new Error("Backend not initialized");
@@ -685,6 +824,8 @@ export class BackendPostgres implements Backend {
 
     const limit = params.limit ?? DEFAULT_PAGINATION_PAGE_SIZE;
     const { after, before } = params;
+    const order = params.order ?? "asc";
+    const reverseOrder = order === "asc" ? "desc" : "asc";
 
     let cursor: Cursor | null = null;
     if (after) {
@@ -693,10 +834,10 @@ export class BackendPostgres implements Backend {
       cursor = decodeCursor(before);
     }
 
-    const qb = this.buildListStepAttemptsWhere(params, cursor);
+    const qb = this.buildListStepAttemptsWhere(params, cursor, order);
     const rows = await qb
-      .orderBy("created_at", before ? "desc" : "asc")
-      .orderBy("id", before ? "desc" : "asc")
+      .orderBy("created_at", before ? reverseOrder : order)
+      .orderBy("id", before ? reverseOrder : order)
       .limit(limit + 1);
 
     return this.processPaginationResults(
@@ -707,7 +848,11 @@ export class BackendPostgres implements Backend {
     );
   }
 
-  private buildListStepAttemptsWhere(params: ListStepAttemptsParams, cursor: Cursor | null) {
+  private buildListStepAttemptsWhere(
+    params: ListStepAttemptsParams,
+    cursor: Cursor | null,
+    order: "asc" | "desc",
+  ) {
     const { after } = params;
     const qb = this.knex
       .withSchema(DEFAULT_SCHEMA)
@@ -716,7 +861,9 @@ export class BackendPostgres implements Backend {
       .where("workflow_run_id", params.workflowRunId);
 
     if (cursor) {
-      const operator = after ? ">" : "<";
+      // asc: after → ">", before → "<"
+      // desc: after → "<", before → ">"
+      const operator = (order === "asc") === !!after ? ">" : "<";
       return qb.whereRaw(`("created_at", "id") ${operator} (?, ?)`, [
         cursor.createdAt.toISOString(),
         cursor.id,
@@ -767,8 +914,10 @@ export class BackendPostgres implements Backend {
     };
   }
 
-  // NOTE: 실제 서비스에서 이게 안 되는 것 같은데, 쿼리 등을 체크할 필요가 있음.
-  async completeStepAttempt(params: CompleteStepAttemptParams): Promise<StepAttempt> {
+  // WHERE 조건에 wr.status='running', sa.status='running'이 포함되어 있어,
+  // 외부에서 워크플로우 상태가 변경된 경우(pause/cancel) null을 반환합니다.
+  // 예상하지 못한 이유로 실패한 경우에는 에러를 로깅합니다.
+  async completeStepAttempt(params: CompleteStepAttemptParams): Promise<StepAttempt | null> {
     if (!this.initialized) {
       throw new Error("Backend not initialized");
     }
@@ -801,14 +950,13 @@ export class BackendPostgres implements Backend {
       .returning("sa.*");
 
     if (!updated) {
-      logger.error("Failed to mark step attempt completed: {params}", { params });
-      throw new Error("Failed to mark step attempt completed");
+      return this.handleStepAttemptUpdateMiss("completed", params);
     }
 
     return updated;
   }
 
-  async failStepAttempt(params: FailStepAttemptParams): Promise<StepAttempt> {
+  async failStepAttempt(params: FailStepAttemptParams): Promise<StepAttempt | null> {
     if (!this.initialized) {
       throw new Error("Backend not initialized");
     }
@@ -842,12 +990,46 @@ export class BackendPostgres implements Backend {
       .returning("sa.*");
 
     if (!updated) {
-      logger.error("Failed to mark step attempt failed: {params}", { params });
-      throw new Error("Failed to mark step attempt failed");
+      return this.handleStepAttemptUpdateMiss("failed", params);
     }
 
     return updated;
   }
+
+  /**
+   * completeStepAttempt/failStepAttempt에서 UPDATE가 0건일 때,
+   * 외부 상태 변경(pause/cancel)에 의한 것인지 판단합니다.
+   * - 외부 상태 변경이면 해당 step의 상태도 워크플로우와 동일하게 맞추고 null을 반환합니다.
+   * - 그 외에는 예상하지 못한 상황이므로 에러를 throw합니다.
+   */
+  private async handleStepAttemptUpdateMiss(
+    method: string,
+    params: { workflowRunId: string; stepAttemptId: string; workerId: string },
+  ): Promise<null> {
+    const wr = await this.getWorkflowRun({ workflowRunId: params.workflowRunId });
+
+    // 워크플로우가 외부에서 paused/canceled된 경우 → step 상태도 동일하게 갱신하고 null 반환
+    if (wr && (wr.status === "paused" || wr.status === "canceled")) {
+      await this.knex
+        .withSchema(DEFAULT_SCHEMA)
+        .table("step_attempts")
+        .where("namespace_id", this.namespaceId)
+        .where("id", params.stepAttemptId)
+        .whereIn("status", ["running", "paused"])
+        .update({
+          status: wr.status,
+          updated_at: this.knex.fn.now(),
+        });
+      return null;
+    }
+
+    // 그 외(워크플로우가 여전히 running인데 UPDATE가 안 된 경우 등) → 예상 못한 상황
+    logger.error("Failed to mark step attempt {method}: {params}", {
+      method,
+      params,
+    });
+    throw new Error(`Failed to mark step attempt ${method}`);
+  }
 }
 
 /**