From 18cfc3165968abeafc786b885ec1de676737c1d2 Mon Sep 17 00:00:00 2001 From: Waleed Latif Date: Thu, 12 Nov 2026 14:44:51 -0800 Subject: [PATCH] chore(api): describe the settled-pause rule in the run status overlay TSDoc --- apps/sim/lib/api/contracts/v2/logs.ts | 10 +++++----- apps/sim/lib/api/contracts/v2/workflows.ts | 11 ++++++----- 2 files changed, 11 insertions(+), 10 deletions(-) diff --git a/apps/sim/lib/api/contracts/v2/logs.ts b/apps/sim/lib/api/contracts/v2/logs.ts index f5847eac519..e657a31519f 100644 --- a/apps/sim/lib/api/contracts/v2/logs.ts +++ b/apps/sim/lib/api/contracts/v2/logs.ts @@ -86,15 +86,15 @@ const v2LogDetailCostSchema = z * * That pass-through is also why this field disagrees with the run resources for the * same run, and the disagreement is documented rather than reconciled. The run list - * projects `paused` over the persisted value whenever the run holds a `paused` or - * `partially_resumed` row in `paused_executions` (`executionStatus` in - * `lib/workflows/executor/execution-queries.ts`), so an ordinary human-in-the-loop + * projects `paused` over the persisted value while the run holds a `paused` or + * `partially_resumed` row in `paused_executions` with a point still to resume + * (`executionStatus` in `lib/workflows/executor/execution-queries.ts`), so an ordinary human-in-the-loop * pause reads `paused` there and `pending` here. Adopting the overlay would need this * read to join `paused_executions`, and would silently move live runs between the * `pending` and `paused` buckets of a shipped field that internal log consumers read * from the same query — a breaking change, not a correction. Callers that need the - * pause distinction read the run resources, which also carry the `paused` object that - * separates "waiting on a human" from "a resume attempt failed". + * pause distinction read the run resources, which also carry the `paused` object with the + * pause kind, resume time, and any automatic-resume waiting reason. */ export const v2LogStatusSchema = z .enum(PERSISTED_WORKFLOW_EXECUTION_STATUSES) diff --git a/apps/sim/lib/api/contracts/v2/workflows.ts b/apps/sim/lib/api/contracts/v2/workflows.ts index 816a0fd78b7..ce9558a9b7e 100644 --- a/apps/sim/lib/api/contracts/v2/workflows.ts +++ b/apps/sim/lib/api/contracts/v2/workflows.ts @@ -1988,11 +1988,12 @@ const RUN_STATUS_DESCRIPTION = /** * The list projection passes `workflow_execution_logs.status` through except where it * overlays `paused` for a run holding a `paused` or `partially_resumed` row in - * `paused_executions` — so a reported `paused` is either that overlay or the persisted - * value a failed resume attempt left behind. Both branches land in the persisted set, so the reported enum is - * derived from it — a value missing here fails the response parse, and because list - * validation is whole-page one such row turns an entire page into a 500. `queued` is not - * reportable: a run still only in the job queue has no log row to list. + * `paused_executions` that still has a point to resume (a finished run whose every point + * resumed or failed reads its log status). A reported `paused` is either that overlay or the + * persisted value a failed resume attempt left behind. Both branches land in the persisted + * set, so the reported enum is derived from it — a value missing here fails the response + * parse, and because list validation is whole-page one such row turns an entire page into a + * 500. `queued` is not reportable: a run still only in the job queue has no log row to list. */ export const v2WorkflowRunListStatusValueSchema = z .enum(PERSISTED_WORKFLOW_EXECUTION_STATUSES)