fascicle 0.12.13 → 0.13.1

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 (49) hide show
  1. package/CHANGELOG.md +34 -1
  2. package/dist/adapters-DNnzeLxr.js +447 -0
  3. package/dist/adapters-DNnzeLxr.js.map +1 -0
  4. package/dist/adapters.d.ts +54 -9
  5. package/dist/adapters.js +1 -1
  6. package/dist/agents.d.ts +12 -9
  7. package/dist/agents.js +1 -1
  8. package/dist/{core-BVCVUMmH.js → core-DK7g1Z40.js} +887 -74
  9. package/dist/core-DK7g1Z40.js.map +1 -0
  10. package/dist/diagram_bin.d.ts +1 -2
  11. package/dist/diagram_bin.js +5 -2
  12. package/dist/diagram_bin.js.map +1 -1
  13. package/dist/{engine-Ct4LBzb9.js → engine-BOGuc0X2.js} +366 -36
  14. package/dist/engine-BOGuc0X2.js.map +1 -0
  15. package/dist/index.d.ts +342 -180
  16. package/dist/index.js +149 -123
  17. package/dist/index.js.map +1 -1
  18. package/dist/{invoke-BcPDqE5C.js → invoke-Beef3R3X.js} +3 -3
  19. package/dist/{invoke-BcPDqE5C.js.map → invoke-Beef3R3X.js.map} +1 -1
  20. package/dist/mcp.d.ts +8 -9
  21. package/dist/mcp.js +1 -1
  22. package/dist/otel.d.ts +3 -4
  23. package/dist/stdio.d.ts +4 -5
  24. package/dist/stdio.js +2 -2
  25. package/dist/testing.d.ts +46 -10
  26. package/dist/testing.js +540 -4
  27. package/dist/testing.js.map +1 -1
  28. package/dist/{trajectory-D1eq9eue.js → trajectory-BI-mrVFT.js} +25 -2
  29. package/dist/trajectory-BI-mrVFT.js.map +1 -0
  30. package/dist/{trajectory-ByoOQZ6T.d.ts → trajectory-Bm-mOtqw.d.ts} +34 -3
  31. package/dist/{types-BasW4Wwb.d.ts → types-CPqLZOEr.d.ts} +40 -2
  32. package/dist/{types-bEpfDrys.d.ts → types-CZ83Q5nm.d.ts} +12 -7
  33. package/dist/ui.d.ts +11 -10
  34. package/dist/ui.js +3 -2
  35. package/dist/ui.js.map +1 -1
  36. package/dist/viewer-app/assets/index-DXsB0byD.js +2 -0
  37. package/dist/viewer-app/index.html +1 -1
  38. package/dist/viewer.d.ts +7 -8
  39. package/dist/viewer.js +2 -2
  40. package/dist/viewer.js.map +1 -1
  41. package/package.json +28 -28
  42. package/dist/adapters-CutexJd3.js +0 -270
  43. package/dist/adapters-CutexJd3.js.map +0 -1
  44. package/dist/core-BVCVUMmH.js.map +0 -1
  45. package/dist/engine-Ct4LBzb9.js.map +0 -1
  46. package/dist/leading_system-CfOIc5fi.js +0 -330
  47. package/dist/leading_system-CfOIc5fi.js.map +0 -1
  48. package/dist/trajectory-D1eq9eue.js.map +0 -1
  49. package/dist/viewer-app/assets/index-BBEYkjnQ.js +0 -2
@@ -1,4 +1,4 @@
1
- import { randomUUID } from "node:crypto";
1
+ import { createHash, randomUUID } from "node:crypto";
2
2
  //#region src/core/cleanup.ts
3
3
  const HANDLER_TIMEOUT_MS = 5e3;
4
4
  /**
@@ -135,6 +135,154 @@ function is_step_kind(value) {
135
135
  return typeof value === "string" && STEP_KINDS.includes(value);
136
136
  }
137
137
  //#endregion
138
+ //#region src/core/node_label.ts
139
+ /**
140
+ * What a flow node is called: its display name, an id its author chose, or
141
+ * its kind, in that order. `describe.diagram` labels its rows this way, and
142
+ * `describe.replays` names the steps it finds the same way.
143
+ *
144
+ * A counter-generated id never serves as a label, because its number depends
145
+ * on what else the process built first.
146
+ */
147
+ const CHOSEN_ID_KINDS = /* @__PURE__ */ new Set(["step", "suspend"]);
148
+ /**
149
+ * Pick a node's label: its display name, else an id its author chose, else
150
+ * its kind. `by_kind` reports the last case, where the kind already shows.
151
+ */
152
+ function label_of(node) {
153
+ const display = resolve_display_name(node, "");
154
+ if (display !== "") return {
155
+ label: display,
156
+ by_kind: false
157
+ };
158
+ if (has_chosen_id(node)) return {
159
+ label: node.id,
160
+ by_kind: false
161
+ };
162
+ return {
163
+ label: node.kind,
164
+ by_kind: true
165
+ };
166
+ }
167
+ /**
168
+ * True when a node's id was chosen by its author. Anonymous steps, cycle
169
+ * markers, and every built-in composer carry generated ids. A kind outside
170
+ * the built-in set belongs to a hand-built step, whose id is its author's.
171
+ */
172
+ function has_chosen_id(node) {
173
+ if (node.anonymous === true || node.kind === "<cycle>") return false;
174
+ return !is_step_kind(node.kind) || CHOSEN_ID_KINDS.has(node.kind);
175
+ }
176
+ //#endregion
177
+ //#region src/core/replays.ts
178
+ /**
179
+ * The analysis behind `describe.replays(step)`: which steps marked
180
+ * `side_effect` a resumed run can run again before it reaches a gate.
181
+ *
182
+ * A run that resumes at a `suspend` replays the flow from its input, so a step
183
+ * that ran before the gate runs again, unless a `checkpoint` stored its
184
+ * result. The runtime reports each one as a `step_replayed` event once it has
185
+ * happened. This finds them from the flow's shape alone, before anything runs,
186
+ * so an app can hold its flow to having none in a test.
187
+ *
188
+ * It reads only the `FlowNode` tree that `describe.json` produces. A marked
189
+ * step can replay at a gate when it can start before the gate in one pass and
190
+ * no checkpoint stores its result first. Where the two paths split decides
191
+ * which comes first:
192
+ *
193
+ * - `parallel` members start together, and a step's arms run in whatever
194
+ * order its body calls them, so either one can.
195
+ * - The arms of a `branch` exclude each other within a pass, so neither does.
196
+ * - Anything else runs its children in order: a `sequence`, a `chain`'s plan,
197
+ * a `fallback`'s primary before its backup, a `loop`'s body before its guard
198
+ * within a round, and a kind this module doesn't know.
199
+ * - A step that holds the gate starts before it.
200
+ *
201
+ * A checkpoint protects a step from a gate when it holds the step and not the
202
+ * gate. One around both stores its result only after the gate resumes.
203
+ *
204
+ * What the tree can't show, this can't see: a model call that a step's body
205
+ * makes without declaring it as an arm, a step that a `suspend`'s `combine`
206
+ * hands back, and a gate that a loop reaches only in a later round.
207
+ */
208
+ /**
209
+ * Append `node` and every node under it to `out`, in reading order.
210
+ */
211
+ function walk(node, trail, out) {
212
+ out.push({
213
+ node,
214
+ trail
215
+ });
216
+ for (const [index, child] of (node.children ?? []).entries()) walk(child, [...trail, {
217
+ node,
218
+ index
219
+ }], out);
220
+ }
221
+ /**
222
+ * True when, under a node of `kind`, the child at `first` can start before
223
+ * the child at `second` within one pass.
224
+ */
225
+ function comes_first(kind, first, second) {
226
+ if (kind === "branch") return false;
227
+ if (kind === "parallel" || kind === "step") return true;
228
+ return first < second;
229
+ }
230
+ /**
231
+ * How many turns two trails share before they part, which is the depth of
232
+ * the node where their paths split. A trail that runs out first is shared
233
+ * whole.
234
+ */
235
+ function shared_depth(a, b) {
236
+ const parted = a.findIndex((turn, i) => turn.index !== b[i]?.index);
237
+ return parted === -1 ? a.length : parted;
238
+ }
239
+ /**
240
+ * True when the marked step at `s` can run before the gate at `g` with no
241
+ * checkpoint between them that holds the step and not the gate.
242
+ */
243
+ function runs_before(s, g) {
244
+ const depth = shared_depth(s.trail, g.trail);
245
+ const split_s = s.trail[depth];
246
+ const split_g = g.trail[depth];
247
+ if (split_g === void 0) return false;
248
+ if (split_s === void 0) return true;
249
+ if (!comes_first(split_s.node.kind, split_s.index, split_g.index)) return false;
250
+ return !s.trail.slice(depth + 1).some(({ node }) => node.kind === "checkpoint");
251
+ }
252
+ /**
253
+ * The gates each marked node can run before, by node, for every marked node
254
+ * that has any. A gate that appears twice in the tree is listed once.
255
+ */
256
+ function replay_gates(root) {
257
+ const visits = [];
258
+ walk(root, [], visits);
259
+ const gates = visits.filter(({ node }) => node.kind === "suspend");
260
+ const found = /* @__PURE__ */ new Map();
261
+ for (const visit of visits) {
262
+ if (visit.node.meta?.side_effect !== true) continue;
263
+ const ids = [...new Set(gates.filter((gate) => runs_before(visit, gate)).map(({ node }) => node.id))];
264
+ if (ids.length > 0) found.set(visit.node, ids);
265
+ }
266
+ return found;
267
+ }
268
+ /**
269
+ * Every step marked `side_effect` that a resumed run can run again before one
270
+ * of the flow's gates, in flow order. A step that appears twice in the tree
271
+ * gets one hint, with the gates of both places.
272
+ */
273
+ function find_replays(root) {
274
+ const by_id = /* @__PURE__ */ new Map();
275
+ for (const [node, gates] of replay_gates(root)) {
276
+ const seen = by_id.get(node.id);
277
+ by_id.set(node.id, {
278
+ id: node.id,
279
+ label: label_of(node).label,
280
+ gates: seen === void 0 ? gates : [.../* @__PURE__ */ new Set([...seen.gates, ...gates])]
281
+ });
282
+ }
283
+ return [...by_id.values()];
284
+ }
285
+ //#endregion
138
286
  //#region src/core/diagram.ts
139
287
  /**
140
288
  * The renderer behind `describe.diagram(step)`: a flow drawn as an annotated
@@ -151,8 +299,9 @@ function is_step_kind(value) {
151
299
  * parallel member's key, a chain's stages), never from a config dump.
152
300
  * Descriptions share one column after the widest row. A composer's description
153
301
  * follows its kind (`branch: ...`), and a node without one shows its kind.
302
+ * With `replays` set, a step that a resumed run can run again before a gate
303
+ * ends its description with the gates it runs before.
154
304
  */
155
- const CHOSEN_ID_KINDS = /* @__PURE__ */ new Set(["step", "suspend"]);
156
305
  const BRANCH_ROLES = ["then", "else"];
157
306
  const STAGE_PREFIX = "stage:";
158
307
  const COLUMN_GAP = 2;
@@ -162,7 +311,7 @@ const COLUMN_GAP = 2;
162
311
  */
163
312
  function render_diagram(root, options) {
164
313
  const rows = [];
165
- flatten(to_item(root, void 0), "", "", rows);
314
+ flatten(to_item(root, void 0, options?.replays === true ? replay_gates(root) : /* @__PURE__ */ new Map()), "", "", rows);
166
315
  const column = Math.max(...rows.map((row) => row.lead.length + row.head.length)) + COLUMN_GAP;
167
316
  const prefix = options?.prefix ?? "";
168
317
  const limit = options?.width === void 0 ? Number.POSITIVE_INFINITY : options.width - prefix.length - column;
@@ -212,41 +361,20 @@ function wrap(words, limit) {
212
361
  * Convert one node into the item the layout draws. `role` is the name the
213
362
  * parent gives this child, and it is dropped when it only repeats the label.
214
363
  */
215
- function to_item(node, role) {
364
+ function to_item(node, role, marks) {
216
365
  const { label, by_kind } = label_of(node);
217
366
  return {
218
367
  head: role === void 0 || role === label ? label : `${role} ${label}`,
219
- note: note_of(node, by_kind),
220
- children: child_items(node)
221
- };
222
- }
223
- /**
224
- * Pick a node's label: its display name, else an id its author chose, else
225
- * its kind. `by_kind` reports the last case, where the kind already shows.
226
- */
227
- function label_of(node) {
228
- const display = resolve_display_name(node, "");
229
- if (display !== "") return {
230
- label: display,
231
- by_kind: false
232
- };
233
- if (has_chosen_id(node)) return {
234
- label: node.id,
235
- by_kind: false
236
- };
237
- return {
238
- label: node.kind,
239
- by_kind: true
368
+ note: [...note_of(node, by_kind), ...replay_note(marks.get(node))],
369
+ children: child_items(node, marks)
240
370
  };
241
371
  }
242
372
  /**
243
- * True when a node's id was chosen by its author. Anonymous steps, cycle
244
- * markers, and every built-in composer carry generated ids. A kind outside
245
- * the built-in set belongs to a hand-built step, whose id is its author's.
373
+ * The words that mark a step a resumed run can run again, naming the gates
374
+ * it runs before, or none for a step it can't.
246
375
  */
247
- function has_chosen_id(node) {
248
- if (node.anonymous === true || node.kind === "<cycle>") return false;
249
- return !is_step_kind(node.kind) || CHOSEN_ID_KINDS.has(node.kind);
376
+ function replay_note(gates) {
377
+ return gates === void 0 ? [] : `(replays before ${gates.join(", ")})`.split(" ");
250
378
  }
251
379
  /**
252
380
  * The words of a row's description column.
@@ -266,16 +394,16 @@ function note_of(node, by_kind) {
266
394
  * Convert a node's children, naming each by the role its parent's kind gives
267
395
  * it.
268
396
  */
269
- function child_items(node) {
397
+ function child_items(node, marks) {
270
398
  const children = node.children ?? [];
271
- if (node.kind === "branch") return children.map((child, i) => to_item(child, BRANCH_ROLES[i]));
272
- if (node.kind === "loop") return children.map((child, i) => to_item(child, i === 1 ? "guard" : void 0));
399
+ if (node.kind === "branch") return children.map((child, i) => to_item(child, BRANCH_ROLES[i], marks));
400
+ if (node.kind === "loop") return children.map((child, i) => to_item(child, i === 1 ? "guard" : void 0, marks));
273
401
  if (node.kind === "parallel") {
274
402
  const keys = string_list(node.config?.["keys"]);
275
- return children.map((child, i) => to_item(child, keys[i]));
403
+ return children.map((child, i) => to_item(child, keys[i], marks));
276
404
  }
277
- if (node.kind === "chain") return staged_items(children, string_list(node.config?.["plan"]));
278
- return children.map((child) => to_item(child, void 0));
405
+ if (node.kind === "chain") return staged_items(children, string_list(node.config?.["plan"]), marks);
406
+ return children.map((child) => to_item(child, void 0, marks));
279
407
  }
280
408
  /**
281
409
  * Convert a chain's children in plan order, nesting the entries after each
@@ -283,7 +411,7 @@ function child_items(node) {
283
411
  * encloses them in the trajectory. Children the plan does not account for
284
412
  * follow in order, so a node without a plan still draws every child.
285
413
  */
286
- function staged_items(children, plan) {
414
+ function staged_items(children, plan, marks) {
287
415
  const top = [];
288
416
  let target = top;
289
417
  let next = 0;
@@ -298,9 +426,9 @@ function staged_items(children, plan) {
298
426
  } else {
299
427
  const child = children[next];
300
428
  next += 1;
301
- if (child !== void 0) target.push(to_item(child, void 0));
429
+ if (child !== void 0) target.push(to_item(child, void 0, marks));
302
430
  }
303
- for (const child of children.slice(next)) target.push(to_item(child, void 0));
431
+ for (const child of children.slice(next)) target.push(to_item(child, void 0, marks));
304
432
  return top;
305
433
  }
306
434
  /**
@@ -326,20 +454,46 @@ var suspended_error = class extends Error {
326
454
  kind = "suspended_error";
327
455
  suspend_id;
328
456
  payload;
329
- constructor(suspend_id, payload, message) {
457
+ deadline_ms;
458
+ constructor(suspend_id, payload, message, deadline_ms) {
330
459
  super(message ?? `suspended at ${suspend_id}`);
331
460
  this.name = "suspended_error";
332
461
  this.suspend_id = suspend_id;
333
462
  this.payload = payload;
463
+ this.deadline_ms = deadline_ms;
334
464
  }
335
465
  };
336
466
  var resume_validation_error = class extends Error {
337
467
  kind = "resume_validation_error";
338
468
  issues;
339
- constructor(message, issues) {
469
+ suspend_id;
470
+ constructor(message, issues, suspend_id) {
340
471
  super(message);
341
472
  this.name = "resume_validation_error";
342
473
  this.issues = issues;
474
+ this.suspend_id = suspend_id;
475
+ }
476
+ };
477
+ var flow_changed_error = class extends Error {
478
+ kind = "flow_changed_error";
479
+ run_id;
480
+ started_on;
481
+ continued_on;
482
+ constructor(run_id, started_on, continued_on) {
483
+ super(`durable run ${run_id} started on a flow of another shape (${started_on}, now ${continued_on}): finish it on the flow it started with, delete it, or drive it with on_flow_change: 'replay'`);
484
+ this.name = "flow_changed_error";
485
+ this.run_id = run_id;
486
+ this.started_on = started_on;
487
+ this.continued_on = continued_on;
488
+ }
489
+ };
490
+ var run_not_found_error = class extends Error {
491
+ kind = "run_not_found_error";
492
+ run_id;
493
+ constructor(run_id) {
494
+ super(`no durable run ${run_id}: start it before resuming it`);
495
+ this.name = "run_not_found_error";
496
+ this.run_id = run_id;
343
497
  }
344
498
  };
345
499
  var describe_cycle_error = class extends Error {
@@ -427,6 +581,10 @@ function is_step(value) {
427
581
  * `describe.diagram(step)` draws the `describe.json` tree as an annotated
428
582
  * box-drawing diagram (see diagram.ts).
429
583
  *
584
+ * `describe.replays(step)` reads the same tree for the steps marked
585
+ * `side_effect` that a resumed run can run again before it reaches a gate
586
+ * (see replays.ts).
587
+ *
430
588
  * Both forms detect cycles. Under the default (loose) mode, back-references
431
589
  * render as `<cycle>(id)` in text and `{ kind: '<cycle>', id }` in JSON. Under
432
590
  * `{ strict: true }`, cycles throw `describe_cycle_error`.
@@ -456,12 +614,22 @@ function describe_diagram(root, options) {
456
614
  return render_diagram(describe_json(root, options), options);
457
615
  }
458
616
  /**
617
+ * Find the steps marked `side_effect` that a resumed run can run again before
618
+ * it reaches a gate. Like the diagram, it reads the `describe.json` tree, so
619
+ * it judges the flow's shape and runs nothing.
620
+ */
621
+ function describe_replays(root, options) {
622
+ return find_replays(describe_json(root, options));
623
+ }
624
+ /**
459
625
  * Public entry point: `describe(step)` for text, `describe.json(step)` for
460
- * the `FlowNode` tree, `describe.diagram(step)` for the annotated diagram.
626
+ * the `FlowNode` tree, `describe.diagram(step)` for the annotated diagram,
627
+ * and `describe.replays(step)` for the steps a resume would pay for twice.
461
628
  */
462
629
  const describe = Object.assign(describe_text, {
463
630
  json: describe_json,
464
- diagram: describe_diagram
631
+ diagram: describe_diagram,
632
+ replays: describe_replays
465
633
  });
466
634
  /**
467
635
  * Append one node (label line, config lines, then children) to `lines`.
@@ -799,6 +967,7 @@ function create_streaming_channel(base, high_water_mark = STREAMING_HIGH_WATER_M
799
967
  * identical to `run(...)`.
800
968
  */
801
969
  const dispatch = /* @__PURE__ */ new Map();
970
+ const unreached_gates = /* @__PURE__ */ new Map();
802
971
  /**
803
972
  * Register the dispatch handler for a step kind.
804
973
  *
@@ -824,6 +993,7 @@ function register_traced_kind(kind) {
824
993
  const span_meta = { id: flow.id };
825
994
  if (ctx.parent_span_id !== void 0) span_meta["parent_span_id"] = ctx.parent_span_id;
826
995
  const span_id = ctx.trajectory.start_span(label, span_meta);
996
+ if (flow.meta?.side_effect === true) record_replay(flow, ctx, span_id);
827
997
  const child_ctx = {
828
998
  ...ctx,
829
999
  parent_span_id: span_id
@@ -842,6 +1012,40 @@ function register_traced_kind(kind) {
842
1012
  });
843
1013
  }
844
1014
  /**
1015
+ * Record a `step_replayed` event for `flow`, a step marked `side_effect`, when
1016
+ * it starts before its run has reached every gate the run was resumed with.
1017
+ * The event names the gates still ahead, and it carries the step's own span.
1018
+ */
1019
+ function record_replay(flow, ctx, span_id) {
1020
+ const unreached = unreached_gates.get(ctx.run_id);
1021
+ if (unreached === void 0) return;
1022
+ ctx.trajectory.record({
1023
+ kind: "step_replayed",
1024
+ step_id: flow.id,
1025
+ span_id,
1026
+ suspend_ids: [...unreached]
1027
+ });
1028
+ }
1029
+ /**
1030
+ * Note that a run has reached `suspend_ids`: a `suspend` consumed its resume
1031
+ * data, or a checkpoint hit stood in for the gates inside it. Once a run has
1032
+ * reached all of them, nothing it runs afterwards is a replay.
1033
+ */
1034
+ function mark_gates_reached(ctx, suspend_ids) {
1035
+ const unreached = unreached_gates.get(ctx.run_id);
1036
+ if (unreached === void 0) return;
1037
+ for (const id of suspend_ids) unreached.delete(id);
1038
+ if (unreached.size === 0) unreached_gates.delete(ctx.run_id);
1039
+ }
1040
+ /**
1041
+ * Start tracking the gates a run was resumed with, the ones `resume_data`
1042
+ * holds a value for. A run started without any is never replaying.
1043
+ */
1044
+ function track_resumed_gates(run_id, resume_data) {
1045
+ const resumed = Object.entries(resume_data ?? {}).filter(([, value]) => value !== void 0).map(([id]) => id);
1046
+ if (resumed.length > 0) unreached_gates.set(run_id, new Set(resumed));
1047
+ }
1048
+ /**
845
1049
  * Project an escaping error onto trajectory meta fields.
846
1050
  *
847
1051
  * `error` is always present (the message); `error_name` and `error_kind`
@@ -866,6 +1070,15 @@ let signal_handler_installed = false;
866
1070
  let sigint_handler = null;
867
1071
  let sigterm_handler = null;
868
1072
  /**
1073
+ * Build the handler for one process signal: it aborts every active run with
1074
+ * an `aborted_error` that names the signal.
1075
+ */
1076
+ function abort_all_on(signal_name) {
1077
+ return () => {
1078
+ for (const controller of active_runs) controller.abort(new aborted_error(`received ${signal_name}`, { reason: { signal: signal_name } }));
1079
+ };
1080
+ }
1081
+ /**
869
1082
  * Install process-wide SIGINT/SIGTERM handlers once.
870
1083
  *
871
1084
  * The handlers abort every active run with an `aborted_error` naming the
@@ -875,11 +1088,8 @@ let sigterm_handler = null;
875
1088
  function ensure_signal_handlers() {
876
1089
  if (signal_handler_installed) return;
877
1090
  signal_handler_installed = true;
878
- const abort_all = (signal_name) => () => {
879
- for (const controller of active_runs) controller.abort(new aborted_error(`received ${signal_name}`, { reason: { signal: signal_name } }));
880
- };
881
- sigint_handler = abort_all("SIGINT");
882
- sigterm_handler = abort_all("SIGTERM");
1091
+ sigint_handler = abort_all_on("SIGINT");
1092
+ sigterm_handler = abort_all_on("SIGTERM");
883
1093
  process.on("SIGINT", sigint_handler);
884
1094
  process.on("SIGTERM", sigterm_handler);
885
1095
  }
@@ -1031,7 +1241,7 @@ function link_external_abort(controller, external) {
1031
1241
  * settle-time teardown ordering (cleanup handlers first, then unlinking and
1032
1242
  * stream close).
1033
1243
  */
1034
- function start_run(flow, input, options, high_water_mark) {
1244
+ function start_run$1(flow, input, options, high_water_mark) {
1035
1245
  const install_signal_handlers = options.install_signal_handlers !== false;
1036
1246
  const base_logger = options.trajectory ?? noop_logger;
1037
1247
  const streaming = high_water_mark !== null;
@@ -1075,6 +1285,7 @@ function start_run(flow, input, options, high_water_mark) {
1075
1285
  resume_data: options.resume_data,
1076
1286
  streaming
1077
1287
  };
1288
+ track_resumed_gates(run_id, options.resume_data);
1078
1289
  active_runs.add(controller);
1079
1290
  if (install_signal_handlers) ensure_signal_handlers();
1080
1291
  const result = (async () => {
@@ -1099,6 +1310,7 @@ function start_run(flow, input, options, high_water_mark) {
1099
1310
  await cleanup.run_all();
1100
1311
  } finally {
1101
1312
  logger.record(terminal);
1313
+ unreached_gates.delete(run_id);
1102
1314
  unlink_abort();
1103
1315
  active_runs.delete(controller);
1104
1316
  release_signal_handlers();
@@ -1153,14 +1365,14 @@ function empty_async_iterable() {
1153
1365
  * Execute a flow and resolve with its final output.
1154
1366
  */
1155
1367
  async function run_impl(flow, input, options = {}) {
1156
- const { result } = start_run(flow, input, options, null);
1368
+ const { result } = start_run$1(flow, input, options, null);
1157
1369
  return result;
1158
1370
  }
1159
1371
  /**
1160
1372
  * Execute a flow while exposing its trajectory events as an async iterable.
1161
1373
  */
1162
1374
  function run_stream(flow, input, options = {}) {
1163
- const { events, result } = start_run(flow, input, options, STREAMING_HIGH_WATER_MARK);
1375
+ const { events, result } = start_run$1(flow, input, options, STREAMING_HIGH_WATER_MARK);
1164
1376
  return {
1165
1377
  events,
1166
1378
  result
@@ -1173,7 +1385,8 @@ function run_stream(flow, input, options = {}) {
1173
1385
  * Resolves `{ kind: 'done', output }` on completion. When a `suspend` gate
1174
1386
  * fires, resolves `{ kind: 'suspended', id, payload, resume }` where `id` is
1175
1387
  * the gate's suspend id, `payload` is what the gate raised on its
1176
- * `suspended_error`, and `resume(data)` re-runs the flow from the original
1388
+ * `suspended_error` (plus `deadline_ms`, when the gate set one), and
1389
+ * `resume(data)` re-runs the flow from the original
1177
1390
  * input with `resume_data[id] = data` merged over the caller's options: the
1178
1391
  * same full re-run semantics as calling `run` again yourself, so pure
1179
1392
  * prefixes replay and `checkpoint`ed steps are served from the store. The
@@ -1194,6 +1407,7 @@ async function run_until_suspended(flow, input, options = {}) {
1194
1407
  kind: "suspended",
1195
1408
  id,
1196
1409
  payload: err.payload,
1410
+ ...err.deadline_ms === void 0 ? {} : { deadline_ms: err.deadline_ms },
1197
1411
  resume: (data) => run_until_suspended(flow, input, {
1198
1412
  ...options,
1199
1413
  resume_data: {
@@ -1218,6 +1432,517 @@ const run = Object.assign(run_impl, {
1218
1432
  until_suspended: run_until_suspended
1219
1433
  });
1220
1434
  //#endregion
1435
+ //#region src/core/durable.ts
1436
+ /**
1437
+ * durable: drive a flow that suspends across processes, one event at a time.
1438
+ *
1439
+ * `run.until_suspended` hands back a `resume` closure, and a closure dies
1440
+ * with its process. An app that resumes runs from events (a webhook, a
1441
+ * finished job, a deadline timer) needs the run to live in a store instead:
1442
+ * its input, the resume data its gates consumed, and where it stopped.
1443
+ * `durable({ store })` keeps exactly that under one scope per run id, and it
1444
+ * drives the flow again from the input whenever an event lands, so replay and
1445
+ * checkpoints behave the way they always do.
1446
+ *
1447
+ * Three things every event-driven app would otherwise write for itself, and
1448
+ * usually get wrong, are built in. A lease (a claim on the run's scope that
1449
+ * the driver renews while it drives) keeps two invocations from driving one
1450
+ * run at once, so a CI webhook and a deadline timer that land together can't
1451
+ * both run the same step, and the record's revision fences every write, so a
1452
+ * drive that stalled past its lease can't write over the drive that took the
1453
+ * run from it. An event that finds the lease taken waits in the run's inbox
1454
+ * under its gate's id, and whoever holds the lease takes it up once the run
1455
+ * reaches that gate, so the event is queued rather than dropped. And the run
1456
+ * records a fingerprint of the flow's shape, so a deploy that changes the
1457
+ * flow while a run waits fails loudly instead of replaying different steps
1458
+ * against old checkpoints.
1459
+ *
1460
+ * Everything the driver keeps (the input, resume data, gate payloads, and the
1461
+ * output) goes through the store, so it has to survive JSON, the same as any
1462
+ * checkpointed value.
1463
+ *
1464
+ * A run's scope holds its record under `record`, the events waiting on gates
1465
+ * in the `inbox` scope, the flow's checkpoints in the `flow` scope, and the
1466
+ * lease as the claim on `lease`. Deleting a run clears the whole scope.
1467
+ */
1468
+ const RECORD = "record";
1469
+ const LEASE = "lease";
1470
+ const INBOX = "inbox";
1471
+ const FLOW = "flow";
1472
+ const DEFAULT_LEASE_MS = 6e4;
1473
+ const STATUSES = /* @__PURE__ */ new Set([
1474
+ "running",
1475
+ "suspended",
1476
+ "done",
1477
+ "failed"
1478
+ ]);
1479
+ /**
1480
+ * A short digest of the flow's shape: each node's kind, the id its author
1481
+ * chose, and how the nodes nest. Generated ids stay out, since they shift with
1482
+ * build order, and so do names, descriptions, and config. Rewording a step or
1483
+ * editing a prompt leaves the digest alone, while adding, removing, moving,
1484
+ * or renaming a step changes it.
1485
+ */
1486
+ function fingerprint(flow) {
1487
+ const shape = JSON.stringify(shape_of(describe.json(flow)));
1488
+ return createHash("sha256").update(shape).digest("hex").slice(0, 16);
1489
+ }
1490
+ /**
1491
+ * One node of the shape that `fingerprint` digests.
1492
+ */
1493
+ function shape_of(node) {
1494
+ return [
1495
+ node.kind,
1496
+ has_chosen_id(node) ? node.id : null,
1497
+ (node.children ?? []).map(shape_of)
1498
+ ];
1499
+ }
1500
+ /**
1501
+ * True for a plain object, the only shape a stored record or entry takes.
1502
+ */
1503
+ function is_object(value) {
1504
+ return typeof value === "object" && value !== null && !Array.isArray(value);
1505
+ }
1506
+ /**
1507
+ * Read a stored suspension back, or `null` when the value isn't one.
1508
+ */
1509
+ function as_suspension(value) {
1510
+ if (!is_object(value)) return null;
1511
+ const { id, payload, deadline_at } = value;
1512
+ if (typeof id !== "string") return null;
1513
+ return {
1514
+ id,
1515
+ payload,
1516
+ deadline_at: typeof deadline_at === "number" ? deadline_at : null
1517
+ };
1518
+ }
1519
+ /**
1520
+ * Read a stored run record back, or `undefined` when the value isn't one this
1521
+ * driver wrote. `start` treats an unreadable record as no record and begins
1522
+ * the run again from its input, where its checkpoints still serve.
1523
+ */
1524
+ function as_record(value) {
1525
+ if (!is_object(value) || value["format"] !== 1) return void 0;
1526
+ const { revision, input, flow, resume_data, output, error, status } = value;
1527
+ if (typeof revision !== "number" || typeof flow !== "string") return void 0;
1528
+ if (!is_object(resume_data) || !STATUSES.has(status)) return void 0;
1529
+ const base = {
1530
+ format: 1,
1531
+ revision,
1532
+ input,
1533
+ flow,
1534
+ resume_data,
1535
+ output,
1536
+ error: typeof error === "string" ? error : ""
1537
+ };
1538
+ const suspended = as_suspension(value["suspended"]);
1539
+ if (status !== "suspended") return {
1540
+ ...base,
1541
+ status,
1542
+ suspended
1543
+ };
1544
+ return suspended === null ? void 0 : {
1545
+ ...base,
1546
+ status,
1547
+ suspended
1548
+ };
1549
+ }
1550
+ /**
1551
+ * The outcome a finished run reports to the call that drove it.
1552
+ */
1553
+ function done_view(drive, record) {
1554
+ return {
1555
+ kind: "done",
1556
+ run_id: drive.run_id,
1557
+ output: record.output
1558
+ };
1559
+ }
1560
+ /**
1561
+ * The outcome a run waiting at `gate` reports.
1562
+ */
1563
+ function suspended_view(run_id, gate) {
1564
+ return {
1565
+ kind: "suspended",
1566
+ run_id,
1567
+ id: gate.id,
1568
+ payload: gate.payload,
1569
+ ...gate.deadline_at === null ? {} : { deadline_at: gate.deadline_at }
1570
+ };
1571
+ }
1572
+ /**
1573
+ * What `get` reports for a stored run.
1574
+ */
1575
+ function state_of(run_id, record) {
1576
+ if (record.status === "suspended") return suspended_view(run_id, record.suspended);
1577
+ if (record.status === "done") return {
1578
+ kind: "done",
1579
+ run_id,
1580
+ output: record.output
1581
+ };
1582
+ if (record.status === "failed") return {
1583
+ kind: "failed",
1584
+ run_id,
1585
+ error: record.error
1586
+ };
1587
+ return {
1588
+ kind: "running",
1589
+ run_id
1590
+ };
1591
+ }
1592
+ /**
1593
+ * Take the run's lease for a fresh owner and renew it every third of
1594
+ * `lease_ms` until `end`.
1595
+ *
1596
+ * A renewal that finds another owner holding the lease marks it lost, stops
1597
+ * renewing, and aborts the drive through `signal`, so a drive that outlived
1598
+ * its lease stops instead of running a step twice. Loss is final: a lost
1599
+ * lease never renews again, even once the key is free. A renewal that throws
1600
+ * is retried on the next tick. `end` waits out the renewals still in flight
1601
+ * before it releases, so a late one can't take the lease back afterwards.
1602
+ */
1603
+ async function take_lease(scope, lease_ms) {
1604
+ const owner = randomUUID();
1605
+ if (!await scope.claim(LEASE, owner, lease_ms)) return void 0;
1606
+ const controller = new AbortController();
1607
+ let lost = false;
1608
+ let renewals = Promise.resolve();
1609
+ let timer;
1610
+ const lose = () => {
1611
+ lost = true;
1612
+ clearInterval(timer);
1613
+ const err = new aborted_error("another drive took over this run");
1614
+ controller.abort(err);
1615
+ return err;
1616
+ };
1617
+ const renew = async () => !lost && await scope.claim(LEASE, owner, lease_ms);
1618
+ timer = setInterval(() => {
1619
+ renewals = renewals.then(renew).then((held) => {
1620
+ if (!held) lose();
1621
+ }, () => {});
1622
+ }, lease_ms / 3);
1623
+ timer.unref();
1624
+ return {
1625
+ signal: controller.signal,
1626
+ lost: () => lost,
1627
+ lose,
1628
+ confirm: async () => {
1629
+ if (!await renew()) throw lose();
1630
+ },
1631
+ end: async () => {
1632
+ clearInterval(timer);
1633
+ await renewals;
1634
+ await scope.release(LEASE, owner);
1635
+ }
1636
+ };
1637
+ }
1638
+ /**
1639
+ * Write the run's record and resolve the record as written.
1640
+ *
1641
+ * The write goes through only while this drive holds the lease and the
1642
+ * stored record is still the revision that `next` was built from. A drive
1643
+ * that lost the lease, or that stalled while another drive moved the run on,
1644
+ * finds the revision moved, loses the lease, and leaves the record alone.
1645
+ */
1646
+ async function save(scope, lease, next) {
1647
+ await lease.confirm();
1648
+ const stored = as_record(await scope.get(RECORD));
1649
+ if (stored === void 0 || stored.revision !== next.revision) throw lease.lose();
1650
+ const saved = {
1651
+ ...next,
1652
+ revision: next.revision + 1
1653
+ };
1654
+ await scope.set(RECORD, saved);
1655
+ return saved;
1656
+ }
1657
+ /**
1658
+ * Hold a run to the flow shape it started on. A run on the same shape passes
1659
+ * through. A changed shape throws `flow_changed_error`, unless the driver
1660
+ * replays, in which case the run records a `flow_changed` event and adopts
1661
+ * the new shape.
1662
+ */
1663
+ async function check_shape(drive, lease, record) {
1664
+ if (record.flow === drive.shape) return record;
1665
+ if (drive.on_flow_change === "fail") throw new flow_changed_error(drive.run_id, record.flow, drive.shape);
1666
+ drive.options.trajectory?.record({
1667
+ kind: "flow_changed",
1668
+ run_id: drive.run_id,
1669
+ started_on: record.flow,
1670
+ continued_on: drive.shape,
1671
+ ts: Date.now()
1672
+ });
1673
+ return save(drive.scope, lease, {
1674
+ ...record,
1675
+ flow: drive.shape
1676
+ });
1677
+ }
1678
+ /**
1679
+ * The resume data waiting in the run's inbox for `gate_id`, if any arrived.
1680
+ */
1681
+ async function read_inbox(scope, gate_id) {
1682
+ const entry = await scope.scope(INBOX).get(gate_id);
1683
+ return is_object(entry) && "data" in entry ? { data: entry["data"] } : void 0;
1684
+ }
1685
+ /**
1686
+ * Move the resume data waiting at the run's gate into the run, or resolve
1687
+ * `undefined` when none has arrived.
1688
+ *
1689
+ * The record is saved before the inbox entry is deleted, so a crash between
1690
+ * the two leaves the data in one place or the other and never in neither.
1691
+ */
1692
+ async function take_up(drive, lease, record) {
1693
+ const gate = record.suspended.id;
1694
+ const entry = await read_inbox(drive.scope, gate);
1695
+ if (entry === void 0) return void 0;
1696
+ const current = await check_shape(drive, lease, record);
1697
+ const saved = await save(drive.scope, lease, {
1698
+ ...current,
1699
+ status: "running",
1700
+ resume_data: {
1701
+ ...current.resume_data,
1702
+ [gate]: entry.data
1703
+ }
1704
+ });
1705
+ await drive.scope.scope(INBOX).delete(gate);
1706
+ return saved;
1707
+ }
1708
+ /**
1709
+ * The record after a drive came to rest: done with its output, or waiting at
1710
+ * a gate with that gate's deadline, if it has one, counted from now.
1711
+ */
1712
+ function after_outcome(record, outcome) {
1713
+ if (outcome.kind === "done") return {
1714
+ ...record,
1715
+ status: "done",
1716
+ output: outcome.output,
1717
+ suspended: null
1718
+ };
1719
+ const deadline_at = outcome.deadline_ms === void 0 ? null : Date.now() + outcome.deadline_ms;
1720
+ const gate = {
1721
+ id: outcome.id,
1722
+ payload: outcome.payload,
1723
+ deadline_at
1724
+ };
1725
+ return {
1726
+ ...record,
1727
+ status: "suspended",
1728
+ suspended: gate
1729
+ };
1730
+ }
1731
+ /**
1732
+ * The record after a drive threw. A resume the gate refused is dropped, and
1733
+ * the run goes back to waiting at that gate, so one bad event can't wedge the
1734
+ * run. Anything else marks the run failed until the next event drives it
1735
+ * again.
1736
+ */
1737
+ function after_failure(record, err) {
1738
+ const gate = record.suspended;
1739
+ if (err instanceof resume_validation_error && gate !== null && err.suspend_id === gate.id) {
1740
+ const resume_data = Object.fromEntries(Object.entries(record.resume_data).filter(([id]) => id !== gate.id));
1741
+ return {
1742
+ ...record,
1743
+ status: "suspended",
1744
+ suspended: gate,
1745
+ resume_data
1746
+ };
1747
+ }
1748
+ return {
1749
+ ...record,
1750
+ status: "failed",
1751
+ error: err instanceof Error ? err.message : String(err)
1752
+ };
1753
+ }
1754
+ /**
1755
+ * Run the flow from its input with every resume datum taken up so far, then
1756
+ * save where it came to rest. The run's abort signal fires when the lease is
1757
+ * lost, as well as when the caller's own signal does.
1758
+ *
1759
+ * A drive that throws surfaces its own error even when the store then fails
1760
+ * to save the failure. The record stays as it was in that case, and the next
1761
+ * event drives the run again, the way it would after a crash.
1762
+ */
1763
+ async function drive_once(drive, lease, stored) {
1764
+ const record = await check_shape(drive, lease, stored);
1765
+ const caller_abort = drive.options.abort;
1766
+ let outcome;
1767
+ try {
1768
+ outcome = await run.until_suspended(drive.flow, record.input, {
1769
+ ...drive.options,
1770
+ abort: caller_abort === void 0 ? lease.signal : AbortSignal.any([caller_abort, lease.signal]),
1771
+ checkpoint_store: drive.scope.scope(FLOW),
1772
+ resume_data: record.resume_data
1773
+ });
1774
+ } catch (err) {
1775
+ await save(drive.scope, lease, after_failure(record, err)).catch(() => {});
1776
+ throw err;
1777
+ }
1778
+ return save(drive.scope, lease, after_outcome(record, outcome));
1779
+ }
1780
+ /**
1781
+ * Drive the run until it's done or waiting at a gate with nothing in its
1782
+ * inbox for that gate.
1783
+ */
1784
+ async function settle$1(drive, lease, loaded) {
1785
+ let record = loaded;
1786
+ for (;;) {
1787
+ if (record.status === "done") return done_view(drive, record);
1788
+ if (record.status === "suspended") {
1789
+ const resumed = await take_up(drive, lease, record);
1790
+ if (resumed === void 0) return suspended_view(drive.run_id, record.suspended);
1791
+ record = resumed;
1792
+ }
1793
+ record = await drive_once(drive, lease, record);
1794
+ }
1795
+ }
1796
+ /**
1797
+ * Take the lease, bring the run to rest, and let the lease go.
1798
+ *
1799
+ * An event that landed for the run's gate while this call held the lease
1800
+ * found it taken and left its data in the inbox. So once the lease is gone,
1801
+ * the call looks again and drives once more when something waits at the gate.
1802
+ * Another call that took the lease in between gets it first, and this one
1803
+ * reports the run busy.
1804
+ */
1805
+ async function bring_to_rest(drive, load) {
1806
+ for (;;) {
1807
+ const lease = await take_lease(drive.scope, drive.lease_ms);
1808
+ if (lease === void 0) return {
1809
+ kind: "busy",
1810
+ run_id: drive.run_id
1811
+ };
1812
+ let outcome;
1813
+ try {
1814
+ outcome = await settle$1(drive, lease, await load());
1815
+ } catch (err) {
1816
+ if (lease.lost()) return {
1817
+ kind: "busy",
1818
+ run_id: drive.run_id
1819
+ };
1820
+ throw err;
1821
+ } finally {
1822
+ await lease.end();
1823
+ }
1824
+ if (outcome.kind !== "suspended") return outcome;
1825
+ if (await read_inbox(drive.scope, outcome.id) === void 0) return outcome;
1826
+ }
1827
+ }
1828
+ /**
1829
+ * The scope that holds `run_id`, which has to be a non-empty string.
1830
+ */
1831
+ function scope_for(driver, run_id) {
1832
+ if (run_id.length === 0) throw new TypeError("durable: a run id must be a non-empty string");
1833
+ return driver.store.scope(run_id);
1834
+ }
1835
+ /**
1836
+ * The record of a run that has to exist, or `run_not_found_error`.
1837
+ */
1838
+ async function existing_record(run_id, scope) {
1839
+ const record = as_record(await scope.get(RECORD));
1840
+ if (record === void 0) throw new run_not_found_error(run_id);
1841
+ return record;
1842
+ }
1843
+ /**
1844
+ * Collect what one call drives with.
1845
+ */
1846
+ function drive_for(driver, run_id, flow, options) {
1847
+ return {
1848
+ run_id,
1849
+ scope: scope_for(driver, run_id),
1850
+ flow,
1851
+ shape: fingerprint(flow),
1852
+ options,
1853
+ lease_ms: driver.lease_ms,
1854
+ on_flow_change: driver.on_flow_change
1855
+ };
1856
+ }
1857
+ /**
1858
+ * Start a run, or pick it up where it is when it already exists. A repeated
1859
+ * start (a webhook delivered twice) neither restarts the run nor changes its
1860
+ * input, though it does drive a run that failed, or whose drive died, once
1861
+ * more. The new record is read back before the first drive, so that drive
1862
+ * sees the input the way every later one will, after a trip through the
1863
+ * store.
1864
+ */
1865
+ async function start_run(driver, run_id, flow, input, options) {
1866
+ const drive = drive_for(driver, run_id, flow, options);
1867
+ return bring_to_rest(drive, async () => {
1868
+ const existing = as_record(await drive.scope.get(RECORD));
1869
+ if (existing !== void 0) return existing;
1870
+ const record = {
1871
+ format: 1,
1872
+ revision: 0,
1873
+ input,
1874
+ flow: drive.shape,
1875
+ resume_data: {},
1876
+ output: null,
1877
+ error: "",
1878
+ status: "running",
1879
+ suspended: null
1880
+ };
1881
+ await drive.scope.set(RECORD, record);
1882
+ return existing_record(run_id, drive.scope);
1883
+ });
1884
+ }
1885
+ /**
1886
+ * Hand resume data to a run and drive it as far as it goes.
1887
+ *
1888
+ * Each datum is written to the run's inbox before the lease is taken, so a
1889
+ * call that finds the run busy still leaves its data where the holder takes
1890
+ * it up. Data for a gate the run already passed is dropped, because changing
1891
+ * it would change the replay, and so is data for a gate whose inbox already
1892
+ * holds some: the first datum to reach a gate is the one it gets. `undefined`
1893
+ * resumes nothing. A call with no new data still drives a run that failed,
1894
+ * or whose drive died, once more.
1895
+ */
1896
+ async function resume_run(driver, run_id, flow, resume_data, options) {
1897
+ const drive = drive_for(driver, run_id, flow, options);
1898
+ const record = await existing_record(run_id, drive.scope);
1899
+ if (record.status === "done") return done_view(drive, record);
1900
+ const fresh = Object.entries(resume_data).filter(([id, data]) => data !== void 0 && !Object.hasOwn(record.resume_data, id));
1901
+ const inbox = drive.scope.scope(INBOX);
1902
+ await Promise.all(fresh.map(async ([id, data]) => {
1903
+ if (await read_inbox(drive.scope, id) === void 0) await inbox.set(id, { data });
1904
+ }));
1905
+ return bring_to_rest(drive, () => existing_record(run_id, drive.scope));
1906
+ }
1907
+ /**
1908
+ * Delete everything a run keeps, unless a drive holds it right now.
1909
+ */
1910
+ async function delete_run(driver, run_id) {
1911
+ const scope = scope_for(driver, run_id);
1912
+ if (!await scope.claim(LEASE, randomUUID(), driver.lease_ms)) return false;
1913
+ await scope.clear();
1914
+ return true;
1915
+ }
1916
+ /**
1917
+ * Keep the runs of flows that suspend in `config.store`, and drive them one
1918
+ * event at a time.
1919
+ *
1920
+ * `start(run_id, flow, input)` begins a run and drives it until it's done or
1921
+ * waiting at a gate. `resume(run_id, flow, { [gate]: data })` hands a run
1922
+ * the data its gate waits for and drives it on. Both report `busy` instead
1923
+ * when another invocation is driving the run, and both are safe to repeat.
1924
+ * `get(run_id)` reads where a run stands without driving it, and
1925
+ * `delete(run_id)` removes it, resolving false while a drive holds it.
1926
+ */
1927
+ function durable(config) {
1928
+ const lease_ms = config.lease_ms ?? DEFAULT_LEASE_MS;
1929
+ if (!Number.isFinite(lease_ms) || lease_ms <= 0) throw new RangeError(`durable: lease_ms must be a positive number of milliseconds, got ${lease_ms}`);
1930
+ const driver = {
1931
+ store: config.store,
1932
+ lease_ms,
1933
+ on_flow_change: config.on_flow_change ?? "fail"
1934
+ };
1935
+ return {
1936
+ start: (run_id, flow, input, options = {}) => start_run(driver, run_id, flow, input, options),
1937
+ resume: (run_id, flow, resume_data, options = {}) => resume_run(driver, run_id, flow, resume_data, options),
1938
+ get: async (run_id) => {
1939
+ const record = as_record(await scope_for(driver, run_id).get(RECORD));
1940
+ return record === void 0 ? void 0 : state_of(run_id, record);
1941
+ },
1942
+ delete: (run_id) => delete_run(driver, run_id)
1943
+ };
1944
+ }
1945
+ //#endregion
1221
1946
  //#region src/core/step_id.ts
1222
1947
  /**
1223
1948
  * Step id validation.
@@ -1558,6 +2283,17 @@ register_traced_kind("branch");
1558
2283
  * `concurrency` caps simultaneous in-flight items; omitted means full
1559
2284
  * parallelism.
1560
2285
  *
2286
+ * The first item that throws stops new items from starting, and its error
2287
+ * propagates once the in-flight items settle, so every result the other items
2288
+ * computed is lost. `settle: true` keeps them, the way a batch needs: every
2289
+ * item runs, and its slot in the output holds `{ ok: true, value }` or
2290
+ * `{ ok: false, error }`. The error is reduced to the fields that survive JSON
2291
+ * (`message`, `name`, `kind`, `path`), so a settled array can be checkpointed
2292
+ * and reads the same when a resumed run takes it from the store. Each failed
2293
+ * item also records a `map_item_failed` event. `suspended_error` and
2294
+ * `aborted_error` are control flow rather than failures, so they propagate in
2295
+ * both modes, and so does an error that `items` itself throws.
2296
+ *
1561
2297
  * Cancellation: each in-flight item runs with a composed abort signal via
1562
2298
  * `AbortSignal.any([ctx.abort, child_local])`.
1563
2299
  * On abort no new items start. The composer awaits all in-flight items before
@@ -1572,13 +2308,45 @@ function next_id$7() {
1572
2308
  return `map_${map_counter}`;
1573
2309
  }
1574
2310
  /**
1575
- * Build a per-item execution step.
1576
- *
1577
- * Extracts an array via `items(input)`, runs `do` once per element through a
1578
- * bounded worker pool, and returns results in input order. The first item
1579
- * failure stops new work and propagates after in-flight items settle.
2311
+ * Reduce a thrown value to the fields of it that survive JSON. A value that
2312
+ * isn't an `Error` keeps only its string form, as the message.
1580
2313
  */
1581
- function map(config) {
2314
+ function settled_error(err) {
2315
+ if (!(err instanceof Error)) return { message: String(err) };
2316
+ const kind = Reflect.get(err, "kind");
2317
+ const path = error_path(err);
2318
+ return {
2319
+ message: err.message,
2320
+ ...err.name.length > 0 ? { name: err.name } : {},
2321
+ ...typeof kind === "string" ? { kind } : {},
2322
+ ...path === void 0 ? {} : { path }
2323
+ };
2324
+ }
2325
+ /**
2326
+ * Turn an item's error into its slot in a settled map's output, and record
2327
+ * the failure as a `map_item_failed` event, with the error's `kind` as
2328
+ * `error_kind` when it has one.
2329
+ */
2330
+ function settle_failure(err, index, step_id, ctx) {
2331
+ const error = settled_error(err);
2332
+ ctx.trajectory.record({
2333
+ kind: "map_item_failed",
2334
+ step_id,
2335
+ index,
2336
+ error: error.message,
2337
+ ...error.kind === void 0 ? {} : { error_kind: error.kind }
2338
+ });
2339
+ return {
2340
+ ok: false,
2341
+ error
2342
+ };
2343
+ }
2344
+ /**
2345
+ * Build a map step that fills each item's slot with `fulfilled(value)`.
2346
+ * Given `rejected`, an item's application error fills its slot as well, and
2347
+ * without it the first error fails the map.
2348
+ */
2349
+ function build_map(config, fulfilled, rejected) {
1582
2350
  const id = next_id$7();
1583
2351
  const { items, do: per_item, concurrency, name } = config;
1584
2352
  const run_fn = async (input, ctx) => {
@@ -1599,8 +2367,13 @@ function map(config) {
1599
2367
  abort: composed
1600
2368
  };
1601
2369
  const item_value = list[idx];
1602
- const value = await dispatch_step(per_item, item_value, child_ctx);
1603
- results[idx] = value;
2370
+ try {
2371
+ const value = await dispatch_step(per_item, item_value, child_ctx);
2372
+ results[idx] = fulfilled(value);
2373
+ } catch (err) {
2374
+ if (rejected !== void 0 && !is_control_flow_error(err) && !ctx.abort.aborted) results[idx] = rejected(err, idx, id, ctx);
2375
+ else if (worker_error === void 0) worker_error = err;
2376
+ }
1604
2377
  };
1605
2378
  const worker = async () => {
1606
2379
  while (true) {
@@ -1608,12 +2381,7 @@ function map(config) {
1608
2381
  const idx = cursor;
1609
2382
  cursor += 1;
1610
2383
  if (idx >= list.length) return;
1611
- try {
1612
- await run_one(idx);
1613
- } catch (err) {
1614
- if (worker_error === void 0) worker_error = err;
1615
- return;
1616
- }
2384
+ await run_one(idx);
1617
2385
  }
1618
2386
  };
1619
2387
  try {
@@ -1630,6 +2398,7 @@ function map(config) {
1630
2398
  };
1631
2399
  const config_meta = { items };
1632
2400
  if (concurrency !== void 0) config_meta["concurrency"] = concurrency;
2401
+ if (rejected !== void 0) config_meta["settle"] = true;
1633
2402
  if (name !== void 0) config_meta["display_name"] = name;
1634
2403
  return {
1635
2404
  id,
@@ -1640,6 +2409,13 @@ function map(config) {
1640
2409
  run: run_fn
1641
2410
  };
1642
2411
  }
2412
+ function map(config) {
2413
+ if (config.settle === true) return build_map(config, (value) => ({
2414
+ ok: true,
2415
+ value
2416
+ }), settle_failure);
2417
+ return build_map(config, (value) => value);
2418
+ }
1643
2419
  register_traced_kind("map");
1644
2420
  //#endregion
1645
2421
  //#region src/core/pipe.ts
@@ -2201,6 +2977,10 @@ register_traced_kind("compose");
2201
2977
  * Wrapping an anonymous inner step throws synchronously at construction time
2202
2978
  * with the message `checkpoint requires a named step, got anonymous`, because
2203
2979
  * a cached result must map back to a stable, identifiable step.
2980
+ *
2981
+ * A hit stands in for every `suspend` gate inside `inner` as well. Those gates
2982
+ * ran when the result was stored, so a resumed run that skips them has still
2983
+ * reached them, and the steps after the checkpoint aren't replays.
2204
2984
  */
2205
2985
  let checkpoint_counter = 0;
2206
2986
  /**
@@ -2211,6 +2991,16 @@ function next_id() {
2211
2991
  return `checkpoint_${checkpoint_counter}`;
2212
2992
  }
2213
2993
  /**
2994
+ * The ids of every `suspend` gate in a step tree, the root included. `seen`
2995
+ * guards against a tree that reaches the same step twice.
2996
+ */
2997
+ function gates_within(root, seen = /* @__PURE__ */ new Set()) {
2998
+ if (seen.has(root)) return [];
2999
+ seen.add(root);
3000
+ const inner = (root.children ?? []).flatMap((child) => gates_within(child, seen));
3001
+ return root.kind === "suspend" ? [root.id, ...inner] : inner;
3002
+ }
3003
+ /**
2214
3004
  * Wrap `inner` with persist-and-resume behavior keyed by `config.key`.
2215
3005
  *
2216
3006
  * `key` is a fixed string or a function of the input. Without a
@@ -2223,6 +3013,7 @@ function checkpoint(inner, config) {
2223
3013
  if (inner.anonymous === true) throw new Error("checkpoint requires a named step, got anonymous — give the inner step an id with step('id', fn)");
2224
3014
  const id = next_id();
2225
3015
  const key_spec = config.key;
3016
+ const gates = gates_within(inner);
2226
3017
  const run_fn = async (input, ctx) => {
2227
3018
  const key = typeof key_spec === "function" ? key_spec(input) : key_spec;
2228
3019
  const store = ctx.checkpoint_store;
@@ -2251,7 +3042,10 @@ function checkpoint(inner, config) {
2251
3042
  ...lookup_meta
2252
3043
  });
2253
3044
  }
2254
- if (hit) return cached;
3045
+ if (hit) {
3046
+ mark_gates_reached(ctx, gates);
3047
+ return cached;
3048
+ }
2255
3049
  }
2256
3050
  const result = await dispatch_step(inner, input, ctx);
2257
3051
  if (store) await store.set(key, result);
@@ -2340,7 +3134,22 @@ function format_issue(issue) {
2340
3134
  * validated against `resume_schema` and passed to `combine(input, resume,
2341
3135
  * ctx)`; the result is returned. Invalid resume data throws
2342
3136
  * `resume_validation_error` carrying the vendor-neutral issue list.
3137
+ *
3138
+ * `deadline_ms` says how long the gate waits for its resume. The run can't
3139
+ * keep a clock of its own, since it unwinds as soon as it suspends, so the
3140
+ * value rides out on the `suspended_error` (and the outcome
3141
+ * `run.until_suspended` reports) for whoever drives the run to schedule a
3142
+ * timer that resumes the gate with whatever a timed-out resume means to it.
3143
+ */
3144
+ /**
3145
+ * The resume value addressed to `suspend_id`, read from the run's own resume
3146
+ * data only, so a gate named like an `Object.prototype` member (`toString`,
3147
+ * `constructor`) never mistakes the inherited member for a decision.
2343
3148
  */
3149
+ function resume_value_for(ctx, suspend_id) {
3150
+ const resume_data = ctx.resume_data;
3151
+ return resume_data !== void 0 && Object.hasOwn(resume_data, suspend_id) ? resume_data[suspend_id] : void 0;
3152
+ }
2344
3153
  /**
2345
3154
  * Build a human-in-the-loop pause step.
2346
3155
  *
@@ -2351,27 +3160,31 @@ function format_issue(issue) {
2351
3160
  */
2352
3161
  function suspend(config) {
2353
3162
  const suspend_id = config.id;
3163
+ const deadline_ms = config.deadline_ms;
2354
3164
  const on_fn = config.on;
2355
3165
  const resume_schema = config.resume_schema;
2356
3166
  const combine_fn = config.combine;
2357
3167
  const run_fn = async (input, ctx) => {
2358
- const resume_value = ctx.resume_data?.[suspend_id];
3168
+ const resume_value = resume_value_for(ctx, suspend_id);
2359
3169
  if (resume_value === void 0) {
2360
3170
  await on_fn(input, ctx);
2361
3171
  ctx.trajectory.record({
2362
3172
  kind: "suspended",
2363
3173
  suspend_id,
2364
- step_id: suspend_id
3174
+ step_id: suspend_id,
3175
+ ...deadline_ms === void 0 ? {} : { deadline_ms }
2365
3176
  });
2366
- throw new suspended_error(suspend_id, { input });
3177
+ throw new suspended_error(suspend_id, { input }, void 0, deadline_ms);
2367
3178
  }
3179
+ mark_gates_reached(ctx, [suspend_id]);
2368
3180
  const parsed = await validate_schema(resume_schema, resume_value);
2369
- if (!parsed.ok) throw new resume_validation_error(`resume data for ${suspend_id} failed validation`, parsed.issues);
3181
+ if (!parsed.ok) throw new resume_validation_error(`resume data for ${suspend_id} failed validation`, parsed.issues, suspend_id);
2370
3182
  const result = await combine_fn(input, parsed.value, ctx);
2371
3183
  if (is_step(result)) return dispatch_step(result, input, ctx);
2372
3184
  return result;
2373
3185
  };
2374
3186
  const config_meta = { id: suspend_id };
3187
+ if (deadline_ms !== void 0) config_meta["deadline_ms"] = deadline_ms;
2375
3188
  if (config.name !== void 0) config_meta["display_name"] = config.name;
2376
3189
  return {
2377
3190
  id: suspend_id,
@@ -2716,6 +3529,6 @@ register_traced_kind("chain");
2716
3529
  * and surface through the umbrella package.
2717
3530
  */
2718
3531
  //#endregion
2719
- export { error_path as A, is_valid_step_id as C, is_step as D, describe as E, is_step_kind as F, resolve_display_name as I, suspended_error as M, timeout_error as N, aborted_error as O, STEP_KINDS as P, assert_valid_step_id as S, run as T, map as _, suspend as a, sequence as b, checkpoint as c, timeout as d, fallback as f, pipe as g, wait_with_abort as h, use as i, resume_validation_error as j, describe_cycle_error as k, compose as l, compute_backoff as m, scope as n, format_schema_issues as o, retry as p, stash as r, validate_schema as s, chain as t, loop as u, branch as v, suggest_step_id as w, step as x, parallel as y };
3532
+ export { describe_cycle_error as A, is_valid_step_id as C, describe as D, run as E, suspended_error as F, timeout_error as I, STEP_KINDS as L, flow_changed_error as M, resume_validation_error as N, is_step as O, run_not_found_error as P, is_step_kind as R, assert_valid_step_id as S, durable as T, map as _, suspend as a, sequence as b, checkpoint as c, timeout as d, fallback as f, pipe as g, wait_with_abort as h, use as i, error_path as j, aborted_error as k, compose as l, compute_backoff as m, scope as n, format_schema_issues as o, retry as p, stash as r, validate_schema as s, chain as t, loop as u, branch as v, suggest_step_id as w, step as x, parallel as y, resolve_display_name as z };
2720
3533
 
2721
- //# sourceMappingURL=core-BVCVUMmH.js.map
3534
+ //# sourceMappingURL=core-DK7g1Z40.js.map