fascicle 0.12.12 → 0.13.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 (49) hide show
  1. package/CHANGELOG.md +38 -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-B-M7nAkg.js} +704 -33
  9. package/dist/core-B-M7nAkg.js.map +1 -0
  10. package/dist/diagram_bin.d.ts +1 -2
  11. package/dist/diagram_bin.js +1 -1
  12. package/dist/diagram_bin.js.map +1 -1
  13. package/dist/{engine-Ct4LBzb9.js → engine-BRzVcTBB.js} +366 -36
  14. package/dist/engine-BRzVcTBB.js.map +1 -0
  15. package/dist/index.d.ts +325 -179
  16. package/dist/index.js +149 -123
  17. package/dist/index.js.map +1 -1
  18. package/dist/{invoke-BcPDqE5C.js → invoke-CIdhjChw.js} +3 -3
  19. package/dist/{invoke-BcPDqE5C.js.map → invoke-CIdhjChw.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
  /**
@@ -326,20 +326,46 @@ var suspended_error = class extends Error {
326
326
  kind = "suspended_error";
327
327
  suspend_id;
328
328
  payload;
329
- constructor(suspend_id, payload, message) {
329
+ deadline_ms;
330
+ constructor(suspend_id, payload, message, deadline_ms) {
330
331
  super(message ?? `suspended at ${suspend_id}`);
331
332
  this.name = "suspended_error";
332
333
  this.suspend_id = suspend_id;
333
334
  this.payload = payload;
335
+ this.deadline_ms = deadline_ms;
334
336
  }
335
337
  };
336
338
  var resume_validation_error = class extends Error {
337
339
  kind = "resume_validation_error";
338
340
  issues;
339
- constructor(message, issues) {
341
+ suspend_id;
342
+ constructor(message, issues, suspend_id) {
340
343
  super(message);
341
344
  this.name = "resume_validation_error";
342
345
  this.issues = issues;
346
+ this.suspend_id = suspend_id;
347
+ }
348
+ };
349
+ var flow_changed_error = class extends Error {
350
+ kind = "flow_changed_error";
351
+ run_id;
352
+ started_on;
353
+ continued_on;
354
+ constructor(run_id, started_on, continued_on) {
355
+ 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'`);
356
+ this.name = "flow_changed_error";
357
+ this.run_id = run_id;
358
+ this.started_on = started_on;
359
+ this.continued_on = continued_on;
360
+ }
361
+ };
362
+ var run_not_found_error = class extends Error {
363
+ kind = "run_not_found_error";
364
+ run_id;
365
+ constructor(run_id) {
366
+ super(`no durable run ${run_id}: start it before resuming it`);
367
+ this.name = "run_not_found_error";
368
+ this.run_id = run_id;
343
369
  }
344
370
  };
345
371
  var describe_cycle_error = class extends Error {
@@ -799,6 +825,7 @@ function create_streaming_channel(base, high_water_mark = STREAMING_HIGH_WATER_M
799
825
  * identical to `run(...)`.
800
826
  */
801
827
  const dispatch = /* @__PURE__ */ new Map();
828
+ const unreached_gates = /* @__PURE__ */ new Map();
802
829
  /**
803
830
  * Register the dispatch handler for a step kind.
804
831
  *
@@ -824,6 +851,7 @@ function register_traced_kind(kind) {
824
851
  const span_meta = { id: flow.id };
825
852
  if (ctx.parent_span_id !== void 0) span_meta["parent_span_id"] = ctx.parent_span_id;
826
853
  const span_id = ctx.trajectory.start_span(label, span_meta);
854
+ if (flow.meta?.side_effect === true) record_replay(flow, ctx, span_id);
827
855
  const child_ctx = {
828
856
  ...ctx,
829
857
  parent_span_id: span_id
@@ -842,6 +870,40 @@ function register_traced_kind(kind) {
842
870
  });
843
871
  }
844
872
  /**
873
+ * Record a `step_replayed` event for `flow`, a step marked `side_effect`, when
874
+ * it starts before its run has reached every gate the run was resumed with.
875
+ * The event names the gates still ahead, and it carries the step's own span.
876
+ */
877
+ function record_replay(flow, ctx, span_id) {
878
+ const unreached = unreached_gates.get(ctx.run_id);
879
+ if (unreached === void 0) return;
880
+ ctx.trajectory.record({
881
+ kind: "step_replayed",
882
+ step_id: flow.id,
883
+ span_id,
884
+ suspend_ids: [...unreached]
885
+ });
886
+ }
887
+ /**
888
+ * Note that a run has reached `suspend_ids`: a `suspend` consumed its resume
889
+ * data, or a checkpoint hit stood in for the gates inside it. Once a run has
890
+ * reached all of them, nothing it runs afterwards is a replay.
891
+ */
892
+ function mark_gates_reached(ctx, suspend_ids) {
893
+ const unreached = unreached_gates.get(ctx.run_id);
894
+ if (unreached === void 0) return;
895
+ for (const id of suspend_ids) unreached.delete(id);
896
+ if (unreached.size === 0) unreached_gates.delete(ctx.run_id);
897
+ }
898
+ /**
899
+ * Start tracking the gates a run was resumed with, the ones `resume_data`
900
+ * holds a value for. A run started without any is never replaying.
901
+ */
902
+ function track_resumed_gates(run_id, resume_data) {
903
+ const resumed = Object.entries(resume_data ?? {}).filter(([, value]) => value !== void 0).map(([id]) => id);
904
+ if (resumed.length > 0) unreached_gates.set(run_id, new Set(resumed));
905
+ }
906
+ /**
845
907
  * Project an escaping error onto trajectory meta fields.
846
908
  *
847
909
  * `error` is always present (the message); `error_name` and `error_kind`
@@ -866,6 +928,15 @@ let signal_handler_installed = false;
866
928
  let sigint_handler = null;
867
929
  let sigterm_handler = null;
868
930
  /**
931
+ * Build the handler for one process signal: it aborts every active run with
932
+ * an `aborted_error` that names the signal.
933
+ */
934
+ function abort_all_on(signal_name) {
935
+ return () => {
936
+ for (const controller of active_runs) controller.abort(new aborted_error(`received ${signal_name}`, { reason: { signal: signal_name } }));
937
+ };
938
+ }
939
+ /**
869
940
  * Install process-wide SIGINT/SIGTERM handlers once.
870
941
  *
871
942
  * The handlers abort every active run with an `aborted_error` naming the
@@ -875,11 +946,8 @@ let sigterm_handler = null;
875
946
  function ensure_signal_handlers() {
876
947
  if (signal_handler_installed) return;
877
948
  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");
949
+ sigint_handler = abort_all_on("SIGINT");
950
+ sigterm_handler = abort_all_on("SIGTERM");
883
951
  process.on("SIGINT", sigint_handler);
884
952
  process.on("SIGTERM", sigterm_handler);
885
953
  }
@@ -1031,7 +1099,7 @@ function link_external_abort(controller, external) {
1031
1099
  * settle-time teardown ordering (cleanup handlers first, then unlinking and
1032
1100
  * stream close).
1033
1101
  */
1034
- function start_run(flow, input, options, high_water_mark) {
1102
+ function start_run$1(flow, input, options, high_water_mark) {
1035
1103
  const install_signal_handlers = options.install_signal_handlers !== false;
1036
1104
  const base_logger = options.trajectory ?? noop_logger;
1037
1105
  const streaming = high_water_mark !== null;
@@ -1075,6 +1143,7 @@ function start_run(flow, input, options, high_water_mark) {
1075
1143
  resume_data: options.resume_data,
1076
1144
  streaming
1077
1145
  };
1146
+ track_resumed_gates(run_id, options.resume_data);
1078
1147
  active_runs.add(controller);
1079
1148
  if (install_signal_handlers) ensure_signal_handlers();
1080
1149
  const result = (async () => {
@@ -1099,6 +1168,7 @@ function start_run(flow, input, options, high_water_mark) {
1099
1168
  await cleanup.run_all();
1100
1169
  } finally {
1101
1170
  logger.record(terminal);
1171
+ unreached_gates.delete(run_id);
1102
1172
  unlink_abort();
1103
1173
  active_runs.delete(controller);
1104
1174
  release_signal_handlers();
@@ -1153,14 +1223,14 @@ function empty_async_iterable() {
1153
1223
  * Execute a flow and resolve with its final output.
1154
1224
  */
1155
1225
  async function run_impl(flow, input, options = {}) {
1156
- const { result } = start_run(flow, input, options, null);
1226
+ const { result } = start_run$1(flow, input, options, null);
1157
1227
  return result;
1158
1228
  }
1159
1229
  /**
1160
1230
  * Execute a flow while exposing its trajectory events as an async iterable.
1161
1231
  */
1162
1232
  function run_stream(flow, input, options = {}) {
1163
- const { events, result } = start_run(flow, input, options, STREAMING_HIGH_WATER_MARK);
1233
+ const { events, result } = start_run$1(flow, input, options, STREAMING_HIGH_WATER_MARK);
1164
1234
  return {
1165
1235
  events,
1166
1236
  result
@@ -1173,7 +1243,8 @@ function run_stream(flow, input, options = {}) {
1173
1243
  * Resolves `{ kind: 'done', output }` on completion. When a `suspend` gate
1174
1244
  * fires, resolves `{ kind: 'suspended', id, payload, resume }` where `id` is
1175
1245
  * 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
1246
+ * `suspended_error` (plus `deadline_ms`, when the gate set one), and
1247
+ * `resume(data)` re-runs the flow from the original
1177
1248
  * input with `resume_data[id] = data` merged over the caller's options: the
1178
1249
  * same full re-run semantics as calling `run` again yourself, so pure
1179
1250
  * prefixes replay and `checkpoint`ed steps are served from the store. The
@@ -1194,6 +1265,7 @@ async function run_until_suspended(flow, input, options = {}) {
1194
1265
  kind: "suspended",
1195
1266
  id,
1196
1267
  payload: err.payload,
1268
+ ...err.deadline_ms === void 0 ? {} : { deadline_ms: err.deadline_ms },
1197
1269
  resume: (data) => run_until_suspended(flow, input, {
1198
1270
  ...options,
1199
1271
  resume_data: {
@@ -1218,6 +1290,517 @@ const run = Object.assign(run_impl, {
1218
1290
  until_suspended: run_until_suspended
1219
1291
  });
1220
1292
  //#endregion
1293
+ //#region src/core/durable.ts
1294
+ /**
1295
+ * durable: drive a flow that suspends across processes, one event at a time.
1296
+ *
1297
+ * `run.until_suspended` hands back a `resume` closure, and a closure dies
1298
+ * with its process. An app that resumes runs from events (a webhook, a
1299
+ * finished job, a deadline timer) needs the run to live in a store instead:
1300
+ * its input, the resume data its gates consumed, and where it stopped.
1301
+ * `durable({ store })` keeps exactly that under one scope per run id, and it
1302
+ * drives the flow again from the input whenever an event lands, so replay and
1303
+ * checkpoints behave the way they always do.
1304
+ *
1305
+ * Three things every event-driven app would otherwise write for itself, and
1306
+ * usually get wrong, are built in. A lease (a claim on the run's scope that
1307
+ * the driver renews while it drives) keeps two invocations from driving one
1308
+ * run at once, so a CI webhook and a deadline timer that land together can't
1309
+ * both run the same step, and the record's revision fences every write, so a
1310
+ * drive that stalled past its lease can't write over the drive that took the
1311
+ * run from it. An event that finds the lease taken waits in the run's inbox
1312
+ * under its gate's id, and whoever holds the lease takes it up once the run
1313
+ * reaches that gate, so the event is queued rather than dropped. And the run
1314
+ * records a fingerprint of the flow's shape, so a deploy that changes the
1315
+ * flow while a run waits fails loudly instead of replaying different steps
1316
+ * against old checkpoints.
1317
+ *
1318
+ * Everything the driver keeps (the input, resume data, gate payloads, and the
1319
+ * output) goes through the store, so it has to survive JSON, the same as any
1320
+ * checkpointed value.
1321
+ *
1322
+ * A run's scope holds its record under `record`, the events waiting on gates
1323
+ * in the `inbox` scope, the flow's checkpoints in the `flow` scope, and the
1324
+ * lease as the claim on `lease`. Deleting a run clears the whole scope.
1325
+ */
1326
+ const RECORD = "record";
1327
+ const LEASE = "lease";
1328
+ const INBOX = "inbox";
1329
+ const FLOW = "flow";
1330
+ const DEFAULT_LEASE_MS = 6e4;
1331
+ const STATUSES = /* @__PURE__ */ new Set([
1332
+ "running",
1333
+ "suspended",
1334
+ "done",
1335
+ "failed"
1336
+ ]);
1337
+ /**
1338
+ * A short digest of the flow's shape: each node's kind, the id its author
1339
+ * chose, and how the nodes nest. Generated ids stay out, since they shift with
1340
+ * build order, and so do names, descriptions, and config. Rewording a step or
1341
+ * editing a prompt leaves the digest alone, while adding, removing, moving,
1342
+ * or renaming a step changes it.
1343
+ */
1344
+ function fingerprint(flow) {
1345
+ const shape = JSON.stringify(shape_of(describe.json(flow)));
1346
+ return createHash("sha256").update(shape).digest("hex").slice(0, 16);
1347
+ }
1348
+ /**
1349
+ * One node of the shape that `fingerprint` digests.
1350
+ */
1351
+ function shape_of(node) {
1352
+ return [
1353
+ node.kind,
1354
+ has_chosen_id(node) ? node.id : null,
1355
+ (node.children ?? []).map(shape_of)
1356
+ ];
1357
+ }
1358
+ /**
1359
+ * True for a plain object, the only shape a stored record or entry takes.
1360
+ */
1361
+ function is_object(value) {
1362
+ return typeof value === "object" && value !== null && !Array.isArray(value);
1363
+ }
1364
+ /**
1365
+ * Read a stored suspension back, or `null` when the value isn't one.
1366
+ */
1367
+ function as_suspension(value) {
1368
+ if (!is_object(value)) return null;
1369
+ const { id, payload, deadline_at } = value;
1370
+ if (typeof id !== "string") return null;
1371
+ return {
1372
+ id,
1373
+ payload,
1374
+ deadline_at: typeof deadline_at === "number" ? deadline_at : null
1375
+ };
1376
+ }
1377
+ /**
1378
+ * Read a stored run record back, or `undefined` when the value isn't one this
1379
+ * driver wrote. `start` treats an unreadable record as no record and begins
1380
+ * the run again from its input, where its checkpoints still serve.
1381
+ */
1382
+ function as_record(value) {
1383
+ if (!is_object(value) || value["format"] !== 1) return void 0;
1384
+ const { revision, input, flow, resume_data, output, error, status } = value;
1385
+ if (typeof revision !== "number" || typeof flow !== "string") return void 0;
1386
+ if (!is_object(resume_data) || !STATUSES.has(status)) return void 0;
1387
+ const base = {
1388
+ format: 1,
1389
+ revision,
1390
+ input,
1391
+ flow,
1392
+ resume_data,
1393
+ output,
1394
+ error: typeof error === "string" ? error : ""
1395
+ };
1396
+ const suspended = as_suspension(value["suspended"]);
1397
+ if (status !== "suspended") return {
1398
+ ...base,
1399
+ status,
1400
+ suspended
1401
+ };
1402
+ return suspended === null ? void 0 : {
1403
+ ...base,
1404
+ status,
1405
+ suspended
1406
+ };
1407
+ }
1408
+ /**
1409
+ * The outcome a finished run reports to the call that drove it.
1410
+ */
1411
+ function done_view(drive, record) {
1412
+ return {
1413
+ kind: "done",
1414
+ run_id: drive.run_id,
1415
+ output: record.output
1416
+ };
1417
+ }
1418
+ /**
1419
+ * The outcome a run waiting at `gate` reports.
1420
+ */
1421
+ function suspended_view(run_id, gate) {
1422
+ return {
1423
+ kind: "suspended",
1424
+ run_id,
1425
+ id: gate.id,
1426
+ payload: gate.payload,
1427
+ ...gate.deadline_at === null ? {} : { deadline_at: gate.deadline_at }
1428
+ };
1429
+ }
1430
+ /**
1431
+ * What `get` reports for a stored run.
1432
+ */
1433
+ function state_of(run_id, record) {
1434
+ if (record.status === "suspended") return suspended_view(run_id, record.suspended);
1435
+ if (record.status === "done") return {
1436
+ kind: "done",
1437
+ run_id,
1438
+ output: record.output
1439
+ };
1440
+ if (record.status === "failed") return {
1441
+ kind: "failed",
1442
+ run_id,
1443
+ error: record.error
1444
+ };
1445
+ return {
1446
+ kind: "running",
1447
+ run_id
1448
+ };
1449
+ }
1450
+ /**
1451
+ * Take the run's lease for a fresh owner and renew it every third of
1452
+ * `lease_ms` until `end`.
1453
+ *
1454
+ * A renewal that finds another owner holding the lease marks it lost, stops
1455
+ * renewing, and aborts the drive through `signal`, so a drive that outlived
1456
+ * its lease stops instead of running a step twice. Loss is final: a lost
1457
+ * lease never renews again, even once the key is free. A renewal that throws
1458
+ * is retried on the next tick. `end` waits out the renewals still in flight
1459
+ * before it releases, so a late one can't take the lease back afterwards.
1460
+ */
1461
+ async function take_lease(scope, lease_ms) {
1462
+ const owner = randomUUID();
1463
+ if (!await scope.claim(LEASE, owner, lease_ms)) return void 0;
1464
+ const controller = new AbortController();
1465
+ let lost = false;
1466
+ let renewals = Promise.resolve();
1467
+ let timer;
1468
+ const lose = () => {
1469
+ lost = true;
1470
+ clearInterval(timer);
1471
+ const err = new aborted_error("another drive took over this run");
1472
+ controller.abort(err);
1473
+ return err;
1474
+ };
1475
+ const renew = async () => !lost && await scope.claim(LEASE, owner, lease_ms);
1476
+ timer = setInterval(() => {
1477
+ renewals = renewals.then(renew).then((held) => {
1478
+ if (!held) lose();
1479
+ }, () => {});
1480
+ }, lease_ms / 3);
1481
+ timer.unref();
1482
+ return {
1483
+ signal: controller.signal,
1484
+ lost: () => lost,
1485
+ lose,
1486
+ confirm: async () => {
1487
+ if (!await renew()) throw lose();
1488
+ },
1489
+ end: async () => {
1490
+ clearInterval(timer);
1491
+ await renewals;
1492
+ await scope.release(LEASE, owner);
1493
+ }
1494
+ };
1495
+ }
1496
+ /**
1497
+ * Write the run's record and resolve the record as written.
1498
+ *
1499
+ * The write goes through only while this drive holds the lease and the
1500
+ * stored record is still the revision that `next` was built from. A drive
1501
+ * that lost the lease, or that stalled while another drive moved the run on,
1502
+ * finds the revision moved, loses the lease, and leaves the record alone.
1503
+ */
1504
+ async function save(scope, lease, next) {
1505
+ await lease.confirm();
1506
+ const stored = as_record(await scope.get(RECORD));
1507
+ if (stored === void 0 || stored.revision !== next.revision) throw lease.lose();
1508
+ const saved = {
1509
+ ...next,
1510
+ revision: next.revision + 1
1511
+ };
1512
+ await scope.set(RECORD, saved);
1513
+ return saved;
1514
+ }
1515
+ /**
1516
+ * Hold a run to the flow shape it started on. A run on the same shape passes
1517
+ * through. A changed shape throws `flow_changed_error`, unless the driver
1518
+ * replays, in which case the run records a `flow_changed` event and adopts
1519
+ * the new shape.
1520
+ */
1521
+ async function check_shape(drive, lease, record) {
1522
+ if (record.flow === drive.shape) return record;
1523
+ if (drive.on_flow_change === "fail") throw new flow_changed_error(drive.run_id, record.flow, drive.shape);
1524
+ drive.options.trajectory?.record({
1525
+ kind: "flow_changed",
1526
+ run_id: drive.run_id,
1527
+ started_on: record.flow,
1528
+ continued_on: drive.shape,
1529
+ ts: Date.now()
1530
+ });
1531
+ return save(drive.scope, lease, {
1532
+ ...record,
1533
+ flow: drive.shape
1534
+ });
1535
+ }
1536
+ /**
1537
+ * The resume data waiting in the run's inbox for `gate_id`, if any arrived.
1538
+ */
1539
+ async function read_inbox(scope, gate_id) {
1540
+ const entry = await scope.scope(INBOX).get(gate_id);
1541
+ return is_object(entry) && "data" in entry ? { data: entry["data"] } : void 0;
1542
+ }
1543
+ /**
1544
+ * Move the resume data waiting at the run's gate into the run, or resolve
1545
+ * `undefined` when none has arrived.
1546
+ *
1547
+ * The record is saved before the inbox entry is deleted, so a crash between
1548
+ * the two leaves the data in one place or the other and never in neither.
1549
+ */
1550
+ async function take_up(drive, lease, record) {
1551
+ const gate = record.suspended.id;
1552
+ const entry = await read_inbox(drive.scope, gate);
1553
+ if (entry === void 0) return void 0;
1554
+ const current = await check_shape(drive, lease, record);
1555
+ const saved = await save(drive.scope, lease, {
1556
+ ...current,
1557
+ status: "running",
1558
+ resume_data: {
1559
+ ...current.resume_data,
1560
+ [gate]: entry.data
1561
+ }
1562
+ });
1563
+ await drive.scope.scope(INBOX).delete(gate);
1564
+ return saved;
1565
+ }
1566
+ /**
1567
+ * The record after a drive came to rest: done with its output, or waiting at
1568
+ * a gate with that gate's deadline, if it has one, counted from now.
1569
+ */
1570
+ function after_outcome(record, outcome) {
1571
+ if (outcome.kind === "done") return {
1572
+ ...record,
1573
+ status: "done",
1574
+ output: outcome.output,
1575
+ suspended: null
1576
+ };
1577
+ const deadline_at = outcome.deadline_ms === void 0 ? null : Date.now() + outcome.deadline_ms;
1578
+ const gate = {
1579
+ id: outcome.id,
1580
+ payload: outcome.payload,
1581
+ deadline_at
1582
+ };
1583
+ return {
1584
+ ...record,
1585
+ status: "suspended",
1586
+ suspended: gate
1587
+ };
1588
+ }
1589
+ /**
1590
+ * The record after a drive threw. A resume the gate refused is dropped, and
1591
+ * the run goes back to waiting at that gate, so one bad event can't wedge the
1592
+ * run. Anything else marks the run failed until the next event drives it
1593
+ * again.
1594
+ */
1595
+ function after_failure(record, err) {
1596
+ const gate = record.suspended;
1597
+ if (err instanceof resume_validation_error && gate !== null && err.suspend_id === gate.id) {
1598
+ const resume_data = Object.fromEntries(Object.entries(record.resume_data).filter(([id]) => id !== gate.id));
1599
+ return {
1600
+ ...record,
1601
+ status: "suspended",
1602
+ suspended: gate,
1603
+ resume_data
1604
+ };
1605
+ }
1606
+ return {
1607
+ ...record,
1608
+ status: "failed",
1609
+ error: err instanceof Error ? err.message : String(err)
1610
+ };
1611
+ }
1612
+ /**
1613
+ * Run the flow from its input with every resume datum taken up so far, then
1614
+ * save where it came to rest. The run's abort signal fires when the lease is
1615
+ * lost, as well as when the caller's own signal does.
1616
+ *
1617
+ * A drive that throws surfaces its own error even when the store then fails
1618
+ * to save the failure. The record stays as it was in that case, and the next
1619
+ * event drives the run again, the way it would after a crash.
1620
+ */
1621
+ async function drive_once(drive, lease, stored) {
1622
+ const record = await check_shape(drive, lease, stored);
1623
+ const caller_abort = drive.options.abort;
1624
+ let outcome;
1625
+ try {
1626
+ outcome = await run.until_suspended(drive.flow, record.input, {
1627
+ ...drive.options,
1628
+ abort: caller_abort === void 0 ? lease.signal : AbortSignal.any([caller_abort, lease.signal]),
1629
+ checkpoint_store: drive.scope.scope(FLOW),
1630
+ resume_data: record.resume_data
1631
+ });
1632
+ } catch (err) {
1633
+ await save(drive.scope, lease, after_failure(record, err)).catch(() => {});
1634
+ throw err;
1635
+ }
1636
+ return save(drive.scope, lease, after_outcome(record, outcome));
1637
+ }
1638
+ /**
1639
+ * Drive the run until it's done or waiting at a gate with nothing in its
1640
+ * inbox for that gate.
1641
+ */
1642
+ async function settle$1(drive, lease, loaded) {
1643
+ let record = loaded;
1644
+ for (;;) {
1645
+ if (record.status === "done") return done_view(drive, record);
1646
+ if (record.status === "suspended") {
1647
+ const resumed = await take_up(drive, lease, record);
1648
+ if (resumed === void 0) return suspended_view(drive.run_id, record.suspended);
1649
+ record = resumed;
1650
+ }
1651
+ record = await drive_once(drive, lease, record);
1652
+ }
1653
+ }
1654
+ /**
1655
+ * Take the lease, bring the run to rest, and let the lease go.
1656
+ *
1657
+ * An event that landed for the run's gate while this call held the lease
1658
+ * found it taken and left its data in the inbox. So once the lease is gone,
1659
+ * the call looks again and drives once more when something waits at the gate.
1660
+ * Another call that took the lease in between gets it first, and this one
1661
+ * reports the run busy.
1662
+ */
1663
+ async function bring_to_rest(drive, load) {
1664
+ for (;;) {
1665
+ const lease = await take_lease(drive.scope, drive.lease_ms);
1666
+ if (lease === void 0) return {
1667
+ kind: "busy",
1668
+ run_id: drive.run_id
1669
+ };
1670
+ let outcome;
1671
+ try {
1672
+ outcome = await settle$1(drive, lease, await load());
1673
+ } catch (err) {
1674
+ if (lease.lost()) return {
1675
+ kind: "busy",
1676
+ run_id: drive.run_id
1677
+ };
1678
+ throw err;
1679
+ } finally {
1680
+ await lease.end();
1681
+ }
1682
+ if (outcome.kind !== "suspended") return outcome;
1683
+ if (await read_inbox(drive.scope, outcome.id) === void 0) return outcome;
1684
+ }
1685
+ }
1686
+ /**
1687
+ * The scope that holds `run_id`, which has to be a non-empty string.
1688
+ */
1689
+ function scope_for(driver, run_id) {
1690
+ if (run_id.length === 0) throw new TypeError("durable: a run id must be a non-empty string");
1691
+ return driver.store.scope(run_id);
1692
+ }
1693
+ /**
1694
+ * The record of a run that has to exist, or `run_not_found_error`.
1695
+ */
1696
+ async function existing_record(run_id, scope) {
1697
+ const record = as_record(await scope.get(RECORD));
1698
+ if (record === void 0) throw new run_not_found_error(run_id);
1699
+ return record;
1700
+ }
1701
+ /**
1702
+ * Collect what one call drives with.
1703
+ */
1704
+ function drive_for(driver, run_id, flow, options) {
1705
+ return {
1706
+ run_id,
1707
+ scope: scope_for(driver, run_id),
1708
+ flow,
1709
+ shape: fingerprint(flow),
1710
+ options,
1711
+ lease_ms: driver.lease_ms,
1712
+ on_flow_change: driver.on_flow_change
1713
+ };
1714
+ }
1715
+ /**
1716
+ * Start a run, or pick it up where it is when it already exists. A repeated
1717
+ * start (a webhook delivered twice) neither restarts the run nor changes its
1718
+ * input, though it does drive a run that failed, or whose drive died, once
1719
+ * more. The new record is read back before the first drive, so that drive
1720
+ * sees the input the way every later one will, after a trip through the
1721
+ * store.
1722
+ */
1723
+ async function start_run(driver, run_id, flow, input, options) {
1724
+ const drive = drive_for(driver, run_id, flow, options);
1725
+ return bring_to_rest(drive, async () => {
1726
+ const existing = as_record(await drive.scope.get(RECORD));
1727
+ if (existing !== void 0) return existing;
1728
+ const record = {
1729
+ format: 1,
1730
+ revision: 0,
1731
+ input,
1732
+ flow: drive.shape,
1733
+ resume_data: {},
1734
+ output: null,
1735
+ error: "",
1736
+ status: "running",
1737
+ suspended: null
1738
+ };
1739
+ await drive.scope.set(RECORD, record);
1740
+ return existing_record(run_id, drive.scope);
1741
+ });
1742
+ }
1743
+ /**
1744
+ * Hand resume data to a run and drive it as far as it goes.
1745
+ *
1746
+ * Each datum is written to the run's inbox before the lease is taken, so a
1747
+ * call that finds the run busy still leaves its data where the holder takes
1748
+ * it up. Data for a gate the run already passed is dropped, because changing
1749
+ * it would change the replay, and so is data for a gate whose inbox already
1750
+ * holds some: the first datum to reach a gate is the one it gets. `undefined`
1751
+ * resumes nothing. A call with no new data still drives a run that failed,
1752
+ * or whose drive died, once more.
1753
+ */
1754
+ async function resume_run(driver, run_id, flow, resume_data, options) {
1755
+ const drive = drive_for(driver, run_id, flow, options);
1756
+ const record = await existing_record(run_id, drive.scope);
1757
+ if (record.status === "done") return done_view(drive, record);
1758
+ const fresh = Object.entries(resume_data).filter(([id, data]) => data !== void 0 && !Object.hasOwn(record.resume_data, id));
1759
+ const inbox = drive.scope.scope(INBOX);
1760
+ await Promise.all(fresh.map(async ([id, data]) => {
1761
+ if (await read_inbox(drive.scope, id) === void 0) await inbox.set(id, { data });
1762
+ }));
1763
+ return bring_to_rest(drive, () => existing_record(run_id, drive.scope));
1764
+ }
1765
+ /**
1766
+ * Delete everything a run keeps, unless a drive holds it right now.
1767
+ */
1768
+ async function delete_run(driver, run_id) {
1769
+ const scope = scope_for(driver, run_id);
1770
+ if (!await scope.claim(LEASE, randomUUID(), driver.lease_ms)) return false;
1771
+ await scope.clear();
1772
+ return true;
1773
+ }
1774
+ /**
1775
+ * Keep the runs of flows that suspend in `config.store`, and drive them one
1776
+ * event at a time.
1777
+ *
1778
+ * `start(run_id, flow, input)` begins a run and drives it until it's done or
1779
+ * waiting at a gate. `resume(run_id, flow, { [gate]: data })` hands a run
1780
+ * the data its gate waits for and drives it on. Both report `busy` instead
1781
+ * when another invocation is driving the run, and both are safe to repeat.
1782
+ * `get(run_id)` reads where a run stands without driving it, and
1783
+ * `delete(run_id)` removes it, resolving false while a drive holds it.
1784
+ */
1785
+ function durable(config) {
1786
+ const lease_ms = config.lease_ms ?? DEFAULT_LEASE_MS;
1787
+ if (!Number.isFinite(lease_ms) || lease_ms <= 0) throw new RangeError(`durable: lease_ms must be a positive number of milliseconds, got ${lease_ms}`);
1788
+ const driver = {
1789
+ store: config.store,
1790
+ lease_ms,
1791
+ on_flow_change: config.on_flow_change ?? "fail"
1792
+ };
1793
+ return {
1794
+ start: (run_id, flow, input, options = {}) => start_run(driver, run_id, flow, input, options),
1795
+ resume: (run_id, flow, resume_data, options = {}) => resume_run(driver, run_id, flow, resume_data, options),
1796
+ get: async (run_id) => {
1797
+ const record = as_record(await scope_for(driver, run_id).get(RECORD));
1798
+ return record === void 0 ? void 0 : state_of(run_id, record);
1799
+ },
1800
+ delete: (run_id) => delete_run(driver, run_id)
1801
+ };
1802
+ }
1803
+ //#endregion
1221
1804
  //#region src/core/step_id.ts
1222
1805
  /**
1223
1806
  * Step id validation.
@@ -1558,6 +2141,17 @@ register_traced_kind("branch");
1558
2141
  * `concurrency` caps simultaneous in-flight items; omitted means full
1559
2142
  * parallelism.
1560
2143
  *
2144
+ * The first item that throws stops new items from starting, and its error
2145
+ * propagates once the in-flight items settle, so every result the other items
2146
+ * computed is lost. `settle: true` keeps them, the way a batch needs: every
2147
+ * item runs, and its slot in the output holds `{ ok: true, value }` or
2148
+ * `{ ok: false, error }`. The error is reduced to the fields that survive JSON
2149
+ * (`message`, `name`, `kind`, `path`), so a settled array can be checkpointed
2150
+ * and reads the same when a resumed run takes it from the store. Each failed
2151
+ * item also records a `map_item_failed` event. `suspended_error` and
2152
+ * `aborted_error` are control flow rather than failures, so they propagate in
2153
+ * both modes, and so does an error that `items` itself throws.
2154
+ *
1561
2155
  * Cancellation: each in-flight item runs with a composed abort signal via
1562
2156
  * `AbortSignal.any([ctx.abort, child_local])`.
1563
2157
  * On abort no new items start. The composer awaits all in-flight items before
@@ -1572,13 +2166,45 @@ function next_id$7() {
1572
2166
  return `map_${map_counter}`;
1573
2167
  }
1574
2168
  /**
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.
2169
+ * Reduce a thrown value to the fields of it that survive JSON. A value that
2170
+ * isn't an `Error` keeps only its string form, as the message.
1580
2171
  */
1581
- function map(config) {
2172
+ function settled_error(err) {
2173
+ if (!(err instanceof Error)) return { message: String(err) };
2174
+ const kind = Reflect.get(err, "kind");
2175
+ const path = error_path(err);
2176
+ return {
2177
+ message: err.message,
2178
+ ...err.name.length > 0 ? { name: err.name } : {},
2179
+ ...typeof kind === "string" ? { kind } : {},
2180
+ ...path === void 0 ? {} : { path }
2181
+ };
2182
+ }
2183
+ /**
2184
+ * Turn an item's error into its slot in a settled map's output, and record
2185
+ * the failure as a `map_item_failed` event, with the error's `kind` as
2186
+ * `error_kind` when it has one.
2187
+ */
2188
+ function settle_failure(err, index, step_id, ctx) {
2189
+ const error = settled_error(err);
2190
+ ctx.trajectory.record({
2191
+ kind: "map_item_failed",
2192
+ step_id,
2193
+ index,
2194
+ error: error.message,
2195
+ ...error.kind === void 0 ? {} : { error_kind: error.kind }
2196
+ });
2197
+ return {
2198
+ ok: false,
2199
+ error
2200
+ };
2201
+ }
2202
+ /**
2203
+ * Build a map step that fills each item's slot with `fulfilled(value)`.
2204
+ * Given `rejected`, an item's application error fills its slot as well, and
2205
+ * without it the first error fails the map.
2206
+ */
2207
+ function build_map(config, fulfilled, rejected) {
1582
2208
  const id = next_id$7();
1583
2209
  const { items, do: per_item, concurrency, name } = config;
1584
2210
  const run_fn = async (input, ctx) => {
@@ -1599,8 +2225,13 @@ function map(config) {
1599
2225
  abort: composed
1600
2226
  };
1601
2227
  const item_value = list[idx];
1602
- const value = await dispatch_step(per_item, item_value, child_ctx);
1603
- results[idx] = value;
2228
+ try {
2229
+ const value = await dispatch_step(per_item, item_value, child_ctx);
2230
+ results[idx] = fulfilled(value);
2231
+ } catch (err) {
2232
+ if (rejected !== void 0 && !is_control_flow_error(err) && !ctx.abort.aborted) results[idx] = rejected(err, idx, id, ctx);
2233
+ else if (worker_error === void 0) worker_error = err;
2234
+ }
1604
2235
  };
1605
2236
  const worker = async () => {
1606
2237
  while (true) {
@@ -1608,12 +2239,7 @@ function map(config) {
1608
2239
  const idx = cursor;
1609
2240
  cursor += 1;
1610
2241
  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
- }
2242
+ await run_one(idx);
1617
2243
  }
1618
2244
  };
1619
2245
  try {
@@ -1630,6 +2256,7 @@ function map(config) {
1630
2256
  };
1631
2257
  const config_meta = { items };
1632
2258
  if (concurrency !== void 0) config_meta["concurrency"] = concurrency;
2259
+ if (rejected !== void 0) config_meta["settle"] = true;
1633
2260
  if (name !== void 0) config_meta["display_name"] = name;
1634
2261
  return {
1635
2262
  id,
@@ -1640,6 +2267,13 @@ function map(config) {
1640
2267
  run: run_fn
1641
2268
  };
1642
2269
  }
2270
+ function map(config) {
2271
+ if (config.settle === true) return build_map(config, (value) => ({
2272
+ ok: true,
2273
+ value
2274
+ }), settle_failure);
2275
+ return build_map(config, (value) => value);
2276
+ }
1643
2277
  register_traced_kind("map");
1644
2278
  //#endregion
1645
2279
  //#region src/core/pipe.ts
@@ -2201,6 +2835,10 @@ register_traced_kind("compose");
2201
2835
  * Wrapping an anonymous inner step throws synchronously at construction time
2202
2836
  * with the message `checkpoint requires a named step, got anonymous`, because
2203
2837
  * a cached result must map back to a stable, identifiable step.
2838
+ *
2839
+ * A hit stands in for every `suspend` gate inside `inner` as well. Those gates
2840
+ * ran when the result was stored, so a resumed run that skips them has still
2841
+ * reached them, and the steps after the checkpoint aren't replays.
2204
2842
  */
2205
2843
  let checkpoint_counter = 0;
2206
2844
  /**
@@ -2211,6 +2849,16 @@ function next_id() {
2211
2849
  return `checkpoint_${checkpoint_counter}`;
2212
2850
  }
2213
2851
  /**
2852
+ * The ids of every `suspend` gate in a step tree, the root included. `seen`
2853
+ * guards against a tree that reaches the same step twice.
2854
+ */
2855
+ function gates_within(root, seen = /* @__PURE__ */ new Set()) {
2856
+ if (seen.has(root)) return [];
2857
+ seen.add(root);
2858
+ const inner = (root.children ?? []).flatMap((child) => gates_within(child, seen));
2859
+ return root.kind === "suspend" ? [root.id, ...inner] : inner;
2860
+ }
2861
+ /**
2214
2862
  * Wrap `inner` with persist-and-resume behavior keyed by `config.key`.
2215
2863
  *
2216
2864
  * `key` is a fixed string or a function of the input. Without a
@@ -2223,6 +2871,7 @@ function checkpoint(inner, config) {
2223
2871
  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
2872
  const id = next_id();
2225
2873
  const key_spec = config.key;
2874
+ const gates = gates_within(inner);
2226
2875
  const run_fn = async (input, ctx) => {
2227
2876
  const key = typeof key_spec === "function" ? key_spec(input) : key_spec;
2228
2877
  const store = ctx.checkpoint_store;
@@ -2251,7 +2900,10 @@ function checkpoint(inner, config) {
2251
2900
  ...lookup_meta
2252
2901
  });
2253
2902
  }
2254
- if (hit) return cached;
2903
+ if (hit) {
2904
+ mark_gates_reached(ctx, gates);
2905
+ return cached;
2906
+ }
2255
2907
  }
2256
2908
  const result = await dispatch_step(inner, input, ctx);
2257
2909
  if (store) await store.set(key, result);
@@ -2340,8 +2992,23 @@ function format_issue(issue) {
2340
2992
  * validated against `resume_schema` and passed to `combine(input, resume,
2341
2993
  * ctx)`; the result is returned. Invalid resume data throws
2342
2994
  * `resume_validation_error` carrying the vendor-neutral issue list.
2995
+ *
2996
+ * `deadline_ms` says how long the gate waits for its resume. The run can't
2997
+ * keep a clock of its own, since it unwinds as soon as it suspends, so the
2998
+ * value rides out on the `suspended_error` (and the outcome
2999
+ * `run.until_suspended` reports) for whoever drives the run to schedule a
3000
+ * timer that resumes the gate with whatever a timed-out resume means to it.
2343
3001
  */
2344
3002
  /**
3003
+ * The resume value addressed to `suspend_id`, read from the run's own resume
3004
+ * data only, so a gate named like an `Object.prototype` member (`toString`,
3005
+ * `constructor`) never mistakes the inherited member for a decision.
3006
+ */
3007
+ function resume_value_for(ctx, suspend_id) {
3008
+ const resume_data = ctx.resume_data;
3009
+ return resume_data !== void 0 && Object.hasOwn(resume_data, suspend_id) ? resume_data[suspend_id] : void 0;
3010
+ }
3011
+ /**
2345
3012
  * Build a human-in-the-loop pause step.
2346
3013
  *
2347
3014
  * First run fires the `on` side effect and throws `suspended_error`; a resume
@@ -2351,27 +3018,31 @@ function format_issue(issue) {
2351
3018
  */
2352
3019
  function suspend(config) {
2353
3020
  const suspend_id = config.id;
3021
+ const deadline_ms = config.deadline_ms;
2354
3022
  const on_fn = config.on;
2355
3023
  const resume_schema = config.resume_schema;
2356
3024
  const combine_fn = config.combine;
2357
3025
  const run_fn = async (input, ctx) => {
2358
- const resume_value = ctx.resume_data?.[suspend_id];
3026
+ const resume_value = resume_value_for(ctx, suspend_id);
2359
3027
  if (resume_value === void 0) {
2360
3028
  await on_fn(input, ctx);
2361
3029
  ctx.trajectory.record({
2362
3030
  kind: "suspended",
2363
3031
  suspend_id,
2364
- step_id: suspend_id
3032
+ step_id: suspend_id,
3033
+ ...deadline_ms === void 0 ? {} : { deadline_ms }
2365
3034
  });
2366
- throw new suspended_error(suspend_id, { input });
3035
+ throw new suspended_error(suspend_id, { input }, void 0, deadline_ms);
2367
3036
  }
3037
+ mark_gates_reached(ctx, [suspend_id]);
2368
3038
  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);
3039
+ if (!parsed.ok) throw new resume_validation_error(`resume data for ${suspend_id} failed validation`, parsed.issues, suspend_id);
2370
3040
  const result = await combine_fn(input, parsed.value, ctx);
2371
3041
  if (is_step(result)) return dispatch_step(result, input, ctx);
2372
3042
  return result;
2373
3043
  };
2374
3044
  const config_meta = { id: suspend_id };
3045
+ if (deadline_ms !== void 0) config_meta["deadline_ms"] = deadline_ms;
2375
3046
  if (config.name !== void 0) config_meta["display_name"] = config.name;
2376
3047
  return {
2377
3048
  id: suspend_id,
@@ -2716,6 +3387,6 @@ register_traced_kind("chain");
2716
3387
  * and surface through the umbrella package.
2717
3388
  */
2718
3389
  //#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 };
3390
+ 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
3391
 
2721
- //# sourceMappingURL=core-BVCVUMmH.js.map
3392
+ //# sourceMappingURL=core-B-M7nAkg.js.map