@hexabot-ai/agentic 3.4.0 → 3.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (134) hide show
  1. package/README.md +67 -15
  2. package/dist/cjs/action/abstract-action.js +13 -1
  3. package/dist/cjs/checkpoint.js +301 -0
  4. package/dist/cjs/context.js +11 -27
  5. package/dist/cjs/dsl.types.js +3 -0
  6. package/dist/cjs/errors.js +116 -9
  7. package/dist/cjs/index.js +15 -6
  8. package/dist/cjs/resume-payload.js +257 -0
  9. package/dist/cjs/runner-runtime-control.js +181 -306
  10. package/dist/cjs/step-executors/conditional-executor.js +27 -29
  11. package/dist/cjs/step-executors/loop-executor.js +53 -62
  12. package/dist/cjs/step-executors/parallel-executor.js +169 -102
  13. package/dist/cjs/step-executors/task-executor.js +180 -96
  14. package/dist/cjs/utils/clone.js +73 -0
  15. package/dist/cjs/workflow-fingerprint.js +138 -0
  16. package/dist/cjs/workflow-runner.js +220 -155
  17. package/dist/cjs/workflow.js +24 -12
  18. package/dist/esm/action/abstract-action.js +14 -2
  19. package/dist/esm/checkpoint.js +293 -0
  20. package/dist/esm/context.js +11 -27
  21. package/dist/esm/dsl.types.js +3 -0
  22. package/dist/esm/errors.js +105 -6
  23. package/dist/esm/index.js +3 -3
  24. package/dist/esm/resume-payload.js +250 -0
  25. package/dist/esm/runner-runtime-control.js +179 -303
  26. package/dist/esm/step-executors/conditional-executor.js +27 -29
  27. package/dist/esm/step-executors/loop-executor.js +53 -62
  28. package/dist/esm/step-executors/parallel-executor.js +165 -98
  29. package/dist/esm/step-executors/task-executor.js +181 -97
  30. package/dist/esm/utils/clone.js +67 -0
  31. package/dist/esm/workflow-fingerprint.js +134 -0
  32. package/dist/esm/workflow-runner.js +220 -155
  33. package/dist/esm/workflow.js +24 -12
  34. package/dist/types/action/abstract-action.d.ts.map +1 -1
  35. package/dist/types/action/action.types.d.ts +0 -14
  36. package/dist/types/action/action.types.d.ts.map +1 -1
  37. package/dist/types/checkpoint.d.ts +188 -0
  38. package/dist/types/checkpoint.d.ts.map +1 -0
  39. package/dist/types/context.d.ts +45 -11
  40. package/dist/types/context.d.ts.map +1 -1
  41. package/dist/types/dsl.types.d.ts.map +1 -1
  42. package/dist/types/errors.d.ts +77 -3
  43. package/dist/types/errors.d.ts.map +1 -1
  44. package/dist/types/index.d.ts +6 -7
  45. package/dist/types/index.d.ts.map +1 -1
  46. package/dist/types/resume-payload.d.ts +69 -0
  47. package/dist/types/resume-payload.d.ts.map +1 -0
  48. package/dist/types/runner-runtime-control.d.ts +63 -51
  49. package/dist/types/runner-runtime-control.d.ts.map +1 -1
  50. package/dist/types/step-executors/conditional-executor.d.ts +6 -3
  51. package/dist/types/step-executors/conditional-executor.d.ts.map +1 -1
  52. package/dist/types/step-executors/loop-executor.d.ts +6 -4
  53. package/dist/types/step-executors/loop-executor.d.ts.map +1 -1
  54. package/dist/types/step-executors/parallel-executor.d.ts +11 -3
  55. package/dist/types/step-executors/parallel-executor.d.ts.map +1 -1
  56. package/dist/types/step-executors/task-executor.d.ts +11 -4
  57. package/dist/types/step-executors/task-executor.d.ts.map +1 -1
  58. package/dist/types/step-executors/types.d.ts +21 -13
  59. package/dist/types/step-executors/types.d.ts.map +1 -1
  60. package/dist/types/utils/clone.d.ts +33 -0
  61. package/dist/types/utils/clone.d.ts.map +1 -0
  62. package/dist/types/workflow-event-emitter.d.ts +29 -5
  63. package/dist/types/workflow-event-emitter.d.ts.map +1 -1
  64. package/dist/types/workflow-fingerprint.d.ts +14 -0
  65. package/dist/types/workflow-fingerprint.d.ts.map +1 -0
  66. package/dist/types/workflow-runner.d.ts +83 -41
  67. package/dist/types/workflow-runner.d.ts.map +1 -1
  68. package/dist/types/workflow-types.d.ts +25 -54
  69. package/dist/types/workflow-types.d.ts.map +1 -1
  70. package/dist/types/workflow.d.ts +24 -9
  71. package/dist/types/workflow.d.ts.map +1 -1
  72. package/examples/defs-bindings-agent/bindings.ts +1 -1
  73. package/examples/defs-bindings-agent/workflow.ts +3 -2
  74. package/examples/full/actions/await-user-input.ts +3 -2
  75. package/examples/full/actions/call-llm.ts +18 -18
  76. package/examples/full/actions/create-ticket.ts +1 -2
  77. package/examples/full/actions/decision-router.ts +6 -2
  78. package/examples/full/actions/get-calendar-events.ts +1 -2
  79. package/examples/full/actions/get-user-profile.ts +1 -2
  80. package/examples/full/actions/query-memory.ts +1 -2
  81. package/examples/full/actions/search-web.ts +1 -2
  82. package/examples/full/actions/send-email.ts +3 -2
  83. package/examples/full/workflow.ts +3 -2
  84. package/examples/loop/actions/await-reply.ts +2 -7
  85. package/examples/loop/workflow.ts +4 -2
  86. package/examples/suspend-resume/actions/wait-for-user.ts +11 -9
  87. package/examples/suspend-resume/workflow.ts +51 -11
  88. package/package.json +3 -3
  89. package/src/__tests__/checkpoint.test.ts +2568 -0
  90. package/src/__tests__/resume-payload.test.ts +245 -0
  91. package/src/__tests__/runner-runtime-control.test.ts +265 -0
  92. package/src/__tests__/workflow-fingerprint.test.ts +165 -0
  93. package/src/__tests__/workflow-runner.test.ts +167 -144
  94. package/src/__tests__/workflow.test.ts +97 -6
  95. package/src/action/abstract-action.ts +21 -2
  96. package/src/action/action.types.ts +0 -12
  97. package/src/checkpoint.ts +561 -0
  98. package/src/context.ts +51 -41
  99. package/src/dsl.types.ts +3 -0
  100. package/src/errors.ts +161 -8
  101. package/src/index.ts +33 -14
  102. package/src/resume-payload.ts +326 -0
  103. package/src/runner-runtime-control.ts +222 -456
  104. package/src/step-executors/conditional-executor.test.ts +77 -46
  105. package/src/step-executors/conditional-executor.ts +47 -40
  106. package/src/step-executors/loop-executor.test.ts +106 -92
  107. package/src/step-executors/loop-executor.ts +84 -101
  108. package/src/step-executors/parallel-executor.test.ts +300 -89
  109. package/src/step-executors/parallel-executor.ts +243 -125
  110. package/src/step-executors/task-executor.test.ts +321 -51
  111. package/src/step-executors/task-executor.ts +232 -145
  112. package/src/step-executors/types.ts +23 -22
  113. package/src/utils/clone.ts +75 -0
  114. package/src/workflow-event-emitter.ts +32 -6
  115. package/src/workflow-fingerprint.ts +159 -0
  116. package/src/workflow-runner.ts +325 -209
  117. package/src/workflow-types.ts +25 -56
  118. package/src/workflow.ts +41 -34
  119. package/dist/cjs/step-executors/suspension-continuation.js +0 -27
  120. package/dist/cjs/suspension-rebuilder.js +0 -265
  121. package/dist/cjs/utils/deferred.js +0 -17
  122. package/dist/esm/step-executors/suspension-continuation.js +0 -24
  123. package/dist/esm/suspension-rebuilder.js +0 -260
  124. package/dist/esm/utils/deferred.js +0 -14
  125. package/dist/types/step-executors/suspension-continuation.d.ts +0 -10
  126. package/dist/types/step-executors/suspension-continuation.d.ts.map +0 -1
  127. package/dist/types/suspension-rebuilder.d.ts +0 -67
  128. package/dist/types/suspension-rebuilder.d.ts.map +0 -1
  129. package/dist/types/utils/deferred.d.ts +0 -7
  130. package/dist/types/utils/deferred.d.ts.map +0 -1
  131. package/src/__tests__/suspension-rebuilder.test.ts +0 -404
  132. package/src/step-executors/suspension-continuation.ts +0 -31
  133. package/src/suspension-rebuilder.ts +0 -446
  134. package/src/utils/deferred.ts +0 -23
@@ -8,7 +8,11 @@ import { z, ZodType } from 'zod';
8
8
 
9
9
  import { BaseWorkflowContext } from '../context';
10
10
  import { BaseSettingsSchema } from '../dsl.types';
11
- import { throwIfAborted } from '../errors';
11
+ import {
12
+ isNonDeterministicWorkflowError,
13
+ isWorkflowResumeRejectedError,
14
+ throwIfAborted,
15
+ } from '../errors';
12
16
  import { assertSnakeCaseName } from '../utils/naming';
13
17
  import { sleep, withTimeout } from '../utils/timeout';
14
18
 
@@ -136,12 +140,21 @@ export abstract class AbstractAction<
136
140
  const maxDelayMs = retrySettings.max_delay_ms;
137
141
  const jitter = retrySettings.jitter;
138
142
  const multiplier = retrySettings.multiplier;
143
+ // Suspend keys are positional within the body, so every attempt has to
144
+ // start from where this run did: otherwise a retry asks for `index:2`
145
+ // where the first attempt resolved `index:1`, and the step suspends on a
146
+ // wait whose payload was already delivered.
147
+ const rewindSuspendCursor = context
148
+ ?.getWorkflowRuntime?.()
149
+ ?.markSuspendCursor?.();
139
150
 
140
151
  while (attempt < maxAttempts) {
141
152
  if (signal) {
142
153
  throwIfAborted(signal);
143
154
  }
144
155
 
156
+ rewindSuspendCursor?.();
157
+
145
158
  try {
146
159
  const result = await withTimeout(
147
160
  this.execute({
@@ -159,7 +172,13 @@ export abstract class AbstractAction<
159
172
  } catch (error) {
160
173
  attempt += 1;
161
174
 
162
- if (attempt >= maxAttempts) {
175
+ // A retry would read the same refused resume payload again, or replay
176
+ // the same body into the same mismatch with what it recorded.
177
+ if (
178
+ attempt >= maxAttempts ||
179
+ isWorkflowResumeRejectedError(error) ||
180
+ isNonDeterministicWorkflowError(error)
181
+ ) {
163
182
  throw error;
164
183
  }
165
184
 
@@ -9,7 +9,6 @@ import { ZodType } from 'zod';
9
9
  import type { InferWorkflowBindings } from '../bindings/base-binding';
10
10
  import { BaseWorkflowContext } from '../context';
11
11
  import { Settings } from '../dsl.types';
12
- import { Deferred } from '../utils/deferred';
13
12
 
14
13
  export type RuntimeSettings<S = unknown> = Settings & S;
15
14
 
@@ -82,14 +81,3 @@ export type InferActionSettings<S extends Action> =
82
81
 
83
82
  export type InferActionBindings<S extends Action> =
84
83
  InferActionArgs<S>['bindings'];
85
-
86
- export interface SuspensionNotice {
87
- stepId: string;
88
- reason?: string;
89
- data?: unknown;
90
- resume: Deferred<unknown>;
91
- }
92
-
93
- export type ActionExecutionOutcome<T> =
94
- | { type: 'completed'; value: T }
95
- | { type: 'suspended'; notice: SuspensionNotice };
@@ -0,0 +1,561 @@
1
+ /*
2
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
3
+ * Copyright (c) 2025 Hexastack.
4
+ * Full terms: see LICENSE.md.
5
+ */
6
+
7
+ import { z } from 'zod';
8
+
9
+ import {
10
+ WorkflowCheckpointInvalidError,
11
+ WorkflowDefinitionDriftError,
12
+ WorkflowResumeError,
13
+ WorkflowWaitAmbiguousError,
14
+ WorkflowWaitNotFoundError,
15
+ } from './errors';
16
+ import { checkResumePayload } from './resume-payload';
17
+ import { isRecord } from './utils/clone';
18
+ import { StepType, type StepInfo } from './workflow-event-emitter';
19
+ import { fingerprintWorkflow } from './workflow-fingerprint';
20
+ import type {
21
+ CompiledStep,
22
+ CompiledWorkflow,
23
+ ConditionalStep,
24
+ LoopStep,
25
+ ParallelStep,
26
+ } from './workflow-types';
27
+
28
+ /** Current format version of {@link WorkflowCheckpoint}. */
29
+ export const CHECKPOINT_VERSION = 1;
30
+
31
+ /** One open suspension a run is waiting on. */
32
+ export type WaitInfo = {
33
+ /**
34
+ * Handle a host passes to `resume()` to satisfy this wait. Opaque: unique
35
+ * within a run and stable for as long as the wait is open, but never meant
36
+ * to be parsed.
37
+ */
38
+ waitId: string;
39
+ /** Instance step (loop iterations included) that suspended. */
40
+ step: StepInfo;
41
+ /** Normalized suspend point inside the step body (`index:<n>` or `key:<k>`). */
42
+ suspendKey: string;
43
+ reason?: string;
44
+ data?: unknown;
45
+ /**
46
+ * JSON Schema of the payload the wait accepts, in its JSON form, when
47
+ * `suspend()` was given an `accepts` schema. It is relaxed so that it never
48
+ * refuses a JSON payload the action would accept; the action's schema still
49
+ * has the final say.
50
+ */
51
+ accepts?: Record<string, unknown>;
52
+ /**
53
+ * Set when the `accepts` schema also accepts a resume without payload,
54
+ * which JSON Schema cannot express: `accepts` describes a payload that is
55
+ * given.
56
+ */
57
+ payloadOptional?: boolean;
58
+ };
59
+
60
+ /**
61
+ * Answer recorded for one `suspend()` call. The value is wrapped so that a
62
+ * resume without payload, whose value is `undefined`, is still recorded as
63
+ * answered once JSON drops the value.
64
+ */
65
+ export type RecordedResult = { value?: unknown };
66
+
67
+ /**
68
+ * Suspended task: the only frame that runs code on resume. Its body re-runs
69
+ * with `inputs`, and every `suspend()` call already answered in
70
+ * `awaitResults` resolves immediately.
71
+ */
72
+ export type TaskFrame = {
73
+ kind: 'task';
74
+ stepId: string;
75
+ inputs: Record<string, unknown>;
76
+ /** Answers of the body's earlier `suspend()` calls, by suspend key. */
77
+ awaitResults: Record<string, RecordedResult>;
78
+ wait: WaitInfo;
79
+ };
80
+
81
+ /** Conditional whose chosen branch suspended; conditions are not re-evaluated. */
82
+ export type ConditionalFrame = {
83
+ kind: 'conditional';
84
+ stepId: string;
85
+ branchIndex: number;
86
+ child: SequenceFrame;
87
+ };
88
+
89
+ /** Loop suspended inside iteration `index`. */
90
+ export type LoopFrame = {
91
+ kind: 'loop';
92
+ stepId: string;
93
+ index: number;
94
+ /** Items resolved when a `for_each` loop started; absent for `while`. */
95
+ items?: unknown[];
96
+ /** Accumulator value at the start of iteration `index`. */
97
+ accumulator?: unknown;
98
+ child: SequenceFrame;
99
+ };
100
+
101
+ /** Settled state of one parallel branch when the block suspended. */
102
+ export type ParallelBranchFrame =
103
+ | { status: 'fulfilled'; outputDelta: Record<string, unknown> }
104
+ | {
105
+ status: 'suspended';
106
+ outputDelta: Record<string, unknown>;
107
+ child: StepFrame;
108
+ };
109
+
110
+ /** Parallel block with at least one suspended branch. */
111
+ export type ParallelFrame = {
112
+ kind: 'parallel';
113
+ stepId: string;
114
+ branches: ParallelBranchFrame[];
115
+ };
116
+
117
+ /** Frame of a single compiled step. `stepId` is the compiled (not instance) id. */
118
+ export type StepFrame =
119
+ | TaskFrame
120
+ | ConditionalFrame
121
+ | LoopFrame
122
+ | ParallelFrame;
123
+
124
+ /** Position inside a list of sequential steps. */
125
+ export type SequenceFrame = {
126
+ kind: 'sequence';
127
+ index: number;
128
+ /**
129
+ * `$accumulator` of the sequence's scope when it suspended. A loop that
130
+ * finished earlier in the sequence may have replaced the one the scope
131
+ * started with.
132
+ */
133
+ accumulator?: unknown;
134
+ child: StepFrame;
135
+ };
136
+
137
+ /**
138
+ * Everything needed to resume a suspended run, in any process.
139
+ *
140
+ * The frame tree mirrors the compiled flow: each composite step records only
141
+ * the local state it needs to continue (sequence position, chosen branch,
142
+ * loop position, parallel branch outcomes), so resuming never replays work
143
+ * that already completed.
144
+ */
145
+ export type WorkflowCheckpoint = {
146
+ version: typeof CHECKPOINT_VERSION;
147
+ /** Definition fingerprint the frames were taken against. */
148
+ fingerprint: string;
149
+ input: Record<string, unknown>;
150
+ output: Record<string, unknown>;
151
+ root: SequenceFrame;
152
+ /** Every open wait in the frame tree, in flow order. */
153
+ waits: WaitInfo[];
154
+ };
155
+
156
+ export type CheckpointValidationResult =
157
+ | { ok: true; checkpoint: WorkflowCheckpoint }
158
+ | { ok: false; error: WorkflowResumeError };
159
+
160
+ const recordSchema = z.record(z.string(), z.unknown());
161
+ const stepIdSchema = z.string().min(1);
162
+ const stepInfoSchema = z.object({
163
+ id: stepIdSchema,
164
+ name: z.string(),
165
+ type: z.enum(StepType),
166
+ });
167
+ const waitInfoSchema: z.ZodType<WaitInfo> = z.object({
168
+ waitId: z.string().min(1),
169
+ step: stepInfoSchema,
170
+ suspendKey: z.string().min(1),
171
+ reason: z.string().optional(),
172
+ data: z.unknown().optional(),
173
+ accepts: recordSchema.optional(),
174
+ payloadOptional: z.boolean().optional(),
175
+ });
176
+ const taskFrameSchema: z.ZodType<TaskFrame> = z.object({
177
+ kind: z.literal('task'),
178
+ stepId: stepIdSchema,
179
+ inputs: recordSchema,
180
+ awaitResults: z.record(
181
+ z.string(),
182
+ z.object({ value: z.unknown().optional() }),
183
+ ),
184
+ wait: waitInfoSchema,
185
+ });
186
+ const conditionalFrameSchema: z.ZodType<ConditionalFrame> = z.lazy(() =>
187
+ z.object({
188
+ kind: z.literal('conditional'),
189
+ stepId: stepIdSchema,
190
+ branchIndex: z.int().nonnegative(),
191
+ child: sequenceFrameSchema,
192
+ }),
193
+ );
194
+ const loopFrameSchema: z.ZodType<LoopFrame> = z.lazy(() =>
195
+ z.object({
196
+ kind: z.literal('loop'),
197
+ stepId: stepIdSchema,
198
+ index: z.int().nonnegative(),
199
+ items: z.array(z.unknown()).optional(),
200
+ accumulator: z.unknown().optional(),
201
+ child: sequenceFrameSchema,
202
+ }),
203
+ );
204
+ const parallelFrameSchema: z.ZodType<ParallelFrame> = z.lazy(() =>
205
+ z.object({
206
+ kind: z.literal('parallel'),
207
+ stepId: stepIdSchema,
208
+ branches: z.array(
209
+ z.union([
210
+ z.object({ status: z.literal('fulfilled'), outputDelta: recordSchema }),
211
+ z.object({
212
+ status: z.literal('suspended'),
213
+ outputDelta: recordSchema,
214
+ child: stepFrameSchema,
215
+ }),
216
+ ]),
217
+ ),
218
+ }),
219
+ );
220
+ const stepFrameSchema: z.ZodType<StepFrame> = z.lazy(() =>
221
+ z.union([
222
+ taskFrameSchema,
223
+ conditionalFrameSchema,
224
+ loopFrameSchema,
225
+ parallelFrameSchema,
226
+ ]),
227
+ );
228
+ const sequenceFrameSchema: z.ZodType<SequenceFrame> = z.lazy(() =>
229
+ z.object({
230
+ kind: z.literal('sequence'),
231
+ index: z.int().nonnegative(),
232
+ accumulator: z.unknown().optional(),
233
+ child: stepFrameSchema,
234
+ }),
235
+ );
236
+
237
+ /** Schema of a persisted {@link WorkflowCheckpoint}, for hosts to type storage. */
238
+ export const workflowCheckpointSchema: z.ZodType<WorkflowCheckpoint> = z.object(
239
+ {
240
+ version: z.literal(CHECKPOINT_VERSION),
241
+ fingerprint: z.string().min(1),
242
+ input: recordSchema,
243
+ output: recordSchema,
244
+ root: sequenceFrameSchema,
245
+ waits: z.array(waitInfoSchema).min(1),
246
+ },
247
+ );
248
+
249
+ /**
250
+ * Build the handle of a wait from the instance step that suspended and its
251
+ * suspend key.
252
+ *
253
+ * @param stepInstanceId Instance step id, including any loop iteration suffix.
254
+ * @param suspendKey Normalized suspend key within the step body.
255
+ * @returns The wait id.
256
+ */
257
+ export const buildWaitId = (
258
+ stepInstanceId: string,
259
+ suspendKey: string,
260
+ ): string => `${stepInstanceId}@${suspendKey}`;
261
+
262
+ /**
263
+ * List the open waits held by a frame tree, in flow order.
264
+ *
265
+ * @param frame Root or subtree of a checkpoint.
266
+ * @returns The waits of every suspended task under the frame.
267
+ */
268
+ export function collectWaits(frame: SequenceFrame | StepFrame): WaitInfo[] {
269
+ switch (frame.kind) {
270
+ case 'task':
271
+ return [frame.wait];
272
+ case 'sequence':
273
+ case 'conditional':
274
+ case 'loop':
275
+ return collectWaits(frame.child);
276
+ case 'parallel':
277
+ return frame.branches.flatMap((branch) =>
278
+ branch.status === 'suspended' ? collectWaits(branch.child) : [],
279
+ );
280
+ }
281
+ }
282
+
283
+ /**
284
+ * Pick the wait a resume targets. `resume()` and `validateCheckpoint` both
285
+ * use it, so a payload is always checked against the wait it would resolve.
286
+ *
287
+ * @param waits Open waits of the suspended run.
288
+ * @param waitId Requested wait, optional when exactly one wait is open.
289
+ * @returns The targeted wait.
290
+ * @throws {WorkflowWaitNotFoundError} When `waitId` is not an open wait.
291
+ * @throws {WorkflowWaitAmbiguousError} When several waits are open and no
292
+ * `waitId` is given.
293
+ */
294
+ export function selectWait(waits: WaitInfo[], waitId?: string): WaitInfo {
295
+ const openWaitIds = waits.map((candidate) => candidate.waitId);
296
+ if (waitId === undefined) {
297
+ if (waits.length === 1) {
298
+ return waits[0];
299
+ }
300
+
301
+ throw new WorkflowWaitAmbiguousError(openWaitIds);
302
+ }
303
+
304
+ const wait = waits.find((candidate) => candidate.waitId === waitId);
305
+ if (!wait) {
306
+ throw new WorkflowWaitNotFoundError(waitId, openWaitIds);
307
+ }
308
+
309
+ return wait;
310
+ }
311
+
312
+ /**
313
+ * Check that a frame was taken for the given compiled step.
314
+ *
315
+ * @param frame The frame about to be resumed, if any.
316
+ * @param step The compiled step it is being handed to.
317
+ * @param path Location used in the error message.
318
+ * @throws {WorkflowCheckpointInvalidError} When the frame belongs elsewhere.
319
+ */
320
+ export function assertFrameMatchesStep(
321
+ frame: StepFrame | undefined,
322
+ step: CompiledStep,
323
+ path: Array<string | number> = [],
324
+ ): void {
325
+ if (!frame) {
326
+ return;
327
+ }
328
+
329
+ if ((frame.kind as string) !== step.type || frame.stepId !== step.id) {
330
+ throw new WorkflowCheckpointInvalidError(
331
+ 'structure',
332
+ `Checkpoint expects ${frame.kind} step "${frame.stepId}" but the flow ` +
333
+ `has ${step.type} step "${step.id}".`,
334
+ { path },
335
+ );
336
+ }
337
+ }
338
+
339
+ /**
340
+ * Decide whether a checkpoint can resume against a compiled workflow, without
341
+ * running anything.
342
+ *
343
+ * Checks, in order: presence and shape, format version, definition
344
+ * fingerprint, that every frame lines up with the compiled step it names, that
345
+ * the `waits` index matches the frame tree, and (optionally) that a given wait
346
+ * is open and accepts a given payload.
347
+ *
348
+ * @param compiled The compiled workflow the run will resume against.
349
+ * @param checkpoint The persisted checkpoint, as stored.
350
+ * @param options.waitId Wait the caller is about to resume.
351
+ * @param options.resumeData Payload the caller is about to resume with. When
352
+ * the key is present, it is checked against the wait `resume()` would pick:
353
+ * the one named by `waitId`, or the only open wait.
354
+ * @returns The parsed checkpoint, or the typed reason it cannot resume.
355
+ */
356
+ export function validateCheckpoint(
357
+ compiled: CompiledWorkflow,
358
+ checkpoint: unknown,
359
+ options: { waitId?: string; resumeData?: unknown } = {},
360
+ ): CheckpointValidationResult {
361
+ try {
362
+ const parsed = parseCheckpoint(checkpoint);
363
+ const actual = fingerprintWorkflow(compiled);
364
+ if (parsed.fingerprint !== actual) {
365
+ throw new WorkflowDefinitionDriftError(parsed.fingerprint, actual);
366
+ }
367
+
368
+ assertSequenceMatches(compiled.flow, parsed.root, ['root']);
369
+ assertWaitIndex(parsed);
370
+
371
+ if (options.waitId !== undefined || 'resumeData' in options) {
372
+ const wait = selectWait(parsed.waits, options.waitId);
373
+ if ('resumeData' in options) {
374
+ const payload = checkResumePayload(wait, options.resumeData);
375
+ if (!payload.ok) {
376
+ throw payload.error;
377
+ }
378
+ }
379
+ }
380
+
381
+ return { ok: true, checkpoint: parsed };
382
+ } catch (error) {
383
+ if (error instanceof WorkflowResumeError) {
384
+ return { ok: false, error };
385
+ }
386
+
387
+ throw error;
388
+ }
389
+ }
390
+
391
+ const parseCheckpoint = (checkpoint: unknown): WorkflowCheckpoint => {
392
+ if (checkpoint === null || checkpoint === undefined) {
393
+ throw new WorkflowCheckpointInvalidError(
394
+ 'missing',
395
+ 'No checkpoint was persisted for this run.',
396
+ );
397
+ }
398
+
399
+ if (
400
+ isRecord(checkpoint) &&
401
+ checkpoint.version !== undefined &&
402
+ checkpoint.version !== CHECKPOINT_VERSION
403
+ ) {
404
+ throw new WorkflowCheckpointInvalidError(
405
+ 'unsupported_version',
406
+ `Unsupported checkpoint version ${String(checkpoint.version)}; ` +
407
+ `expected ${CHECKPOINT_VERSION}.`,
408
+ );
409
+ }
410
+
411
+ const result = workflowCheckpointSchema.safeParse(checkpoint);
412
+ if (!result.success) {
413
+ const issues = result.error.issues.map(
414
+ (issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`,
415
+ );
416
+
417
+ throw new WorkflowCheckpointInvalidError(
418
+ 'malformed',
419
+ `Checkpoint does not match the expected shape: ${issues.join('; ')}`,
420
+ { issues },
421
+ );
422
+ }
423
+
424
+ return result.data;
425
+ };
426
+ const structureError = (message: string, path: Array<string | number>) =>
427
+ new WorkflowCheckpointInvalidError('structure', message, { path });
428
+ const assertSequenceMatches = (
429
+ steps: CompiledStep[],
430
+ frame: SequenceFrame,
431
+ path: Array<string | number>,
432
+ ): void => {
433
+ const step = steps[frame.index];
434
+ if (!step) {
435
+ throw structureError(
436
+ `Sequence position ${frame.index} is out of range (${steps.length} steps).`,
437
+ path,
438
+ );
439
+ }
440
+
441
+ assertStepMatches(step, frame.child, [...path, frame.index]);
442
+ };
443
+ const assertStepMatches = (
444
+ step: CompiledStep,
445
+ frame: StepFrame,
446
+ path: Array<string | number>,
447
+ ): void => {
448
+ assertFrameMatchesStep(frame, step, path);
449
+
450
+ switch (step.type) {
451
+ case StepType.Task:
452
+ return;
453
+ case StepType.Conditional:
454
+ return assertConditionalMatches(step, frame as ConditionalFrame, path);
455
+ case StepType.Loop:
456
+ return assertLoopMatches(step, frame as LoopFrame, path);
457
+ case StepType.Parallel:
458
+ return assertParallelMatches(step, frame as ParallelFrame, path);
459
+ }
460
+ };
461
+ const assertConditionalMatches = (
462
+ step: ConditionalStep,
463
+ frame: ConditionalFrame,
464
+ path: Array<string | number>,
465
+ ): void => {
466
+ const branch = step.branches[frame.branchIndex];
467
+ if (!branch) {
468
+ throw structureError(
469
+ `Branch ${frame.branchIndex} does not exist on conditional "${step.id}".`,
470
+ path,
471
+ );
472
+ }
473
+
474
+ assertSequenceMatches(branch.steps, frame.child, [
475
+ ...path,
476
+ 'branch',
477
+ frame.branchIndex,
478
+ ]);
479
+ };
480
+ const assertLoopMatches = (
481
+ step: LoopStep,
482
+ frame: LoopFrame,
483
+ path: Array<string | number>,
484
+ ): void => {
485
+ if (step.loopType === 'for_each') {
486
+ if (!frame.items || frame.index >= frame.items.length) {
487
+ throw structureError(
488
+ `for_each loop "${step.id}" is suspended at iteration ${frame.index} ` +
489
+ `of ${frame.items?.length ?? 0} recorded items.`,
490
+ path,
491
+ );
492
+ }
493
+ } else if (frame.items !== undefined) {
494
+ throw structureError(
495
+ `while loop "${step.id}" cannot carry for_each items.`,
496
+ path,
497
+ );
498
+ }
499
+
500
+ assertSequenceMatches(step.steps, frame.child, [...path, frame.index]);
501
+ };
502
+ const assertParallelMatches = (
503
+ step: ParallelStep,
504
+ frame: ParallelFrame,
505
+ path: Array<string | number>,
506
+ ): void => {
507
+ if (frame.branches.length !== step.steps.length) {
508
+ throw structureError(
509
+ `Parallel "${step.id}" has ${step.steps.length} branches but the ` +
510
+ `checkpoint records ${frame.branches.length}.`,
511
+ path,
512
+ );
513
+ }
514
+
515
+ let suspended = 0;
516
+ frame.branches.forEach((branch, index) => {
517
+ if (branch.status === 'suspended') {
518
+ suspended += 1;
519
+ assertStepMatches(step.steps[index], branch.child, [
520
+ ...path,
521
+ 'parallel',
522
+ index,
523
+ ]);
524
+ } else if (step.strategy === 'wait_any') {
525
+ // A fulfilled branch wins a wait_any race, so it can never be parked.
526
+ throw structureError(
527
+ `wait_any parallel "${step.id}" cannot record a fulfilled branch.`,
528
+ path,
529
+ );
530
+ }
531
+ });
532
+
533
+ if (suspended === 0) {
534
+ throw structureError(
535
+ `Parallel "${step.id}" is recorded as suspended without a suspended branch.`,
536
+ path,
537
+ );
538
+ }
539
+ };
540
+ const assertWaitIndex = (checkpoint: WorkflowCheckpoint): void => {
541
+ const expected = collectWaits(checkpoint.root).map((wait) => wait.waitId);
542
+ const actual = checkpoint.waits.map((wait) => wait.waitId);
543
+
544
+ if (
545
+ expected.length !== actual.length ||
546
+ expected.some((waitId, index) => waitId !== actual[index])
547
+ ) {
548
+ throw structureError(
549
+ `Checkpoint waits [${actual.join(', ')}] do not match the suspended ` +
550
+ `steps [${expected.join(', ')}].`,
551
+ ['waits'],
552
+ );
553
+ }
554
+
555
+ if (new Set(expected).size !== expected.length) {
556
+ throw structureError(
557
+ `Checkpoint holds duplicate waits [${expected.join(', ')}].`,
558
+ ['waits'],
559
+ );
560
+ }
561
+ };