fascicle 0.15.0 → 0.16.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 (65) hide show
  1. package/CHANGELOG.md +121 -0
  2. package/README.md +8 -8
  3. package/dist/acp.d.ts +9 -2
  4. package/dist/acp.js +1538 -1472
  5. package/dist/acp.js.map +1 -1
  6. package/dist/{adapters-DNnzeLxr.js → adapters-CDUzZlby.js} +35 -13
  7. package/dist/adapters-CDUzZlby.js.map +1 -0
  8. package/dist/adapters.d.ts +8 -1
  9. package/dist/adapters.js +1 -1
  10. package/dist/agents.d.ts +1 -1
  11. package/dist/agents.js +15 -8
  12. package/dist/agents.js.map +1 -1
  13. package/dist/bin/fascicle-viewer.js +4 -1
  14. package/dist/console-CdB4pcFO.js +37 -0
  15. package/dist/console-CdB4pcFO.js.map +1 -0
  16. package/dist/{core-CDrz0NM1.js → core-CErsxGF6.js} +246 -147
  17. package/dist/core-CErsxGF6.js.map +1 -0
  18. package/dist/diagram_bin.js +2 -2
  19. package/dist/diagram_bin.js.map +1 -1
  20. package/dist/{engine-ha9xmgwE.js → engine-CR8q2IqV.js} +173 -67
  21. package/dist/engine-CR8q2IqV.js.map +1 -0
  22. package/dist/index.d.ts +529 -73
  23. package/dist/index.js +440 -137
  24. package/dist/index.js.map +1 -1
  25. package/dist/{invoke-px31fffH.js → invoke-COaeZ-vy.js} +6 -5
  26. package/dist/invoke-COaeZ-vy.js.map +1 -0
  27. package/dist/{json_schema_to_standard-BTWD0J6p.js → json_schema_to_standard-C4F4lXHE.js} +9 -12
  28. package/dist/json_schema_to_standard-C4F4lXHE.js.map +1 -0
  29. package/dist/{leading_system-DfJLqpGi.js → leading_system-PoHzNHuV.js} +28 -8
  30. package/dist/leading_system-PoHzNHuV.js.map +1 -0
  31. package/dist/mcp.d.ts +3 -2
  32. package/dist/mcp.js +8 -4
  33. package/dist/mcp.js.map +1 -1
  34. package/dist/otel.js +10 -10
  35. package/dist/otel.js.map +1 -1
  36. package/dist/{search-CA_OqFeW.js → search-CpCJYMUm.js} +53 -6
  37. package/dist/search-CpCJYMUm.js.map +1 -0
  38. package/dist/search_worker.js +1 -1
  39. package/dist/stdio.js +7 -3
  40. package/dist/stdio.js.map +1 -1
  41. package/dist/testing.d.ts +1 -1
  42. package/dist/testing.js +3 -3
  43. package/dist/testing.js.map +1 -1
  44. package/dist/{trajectory-Bm-mOtqw.d.ts → trajectory-BKGNxi7u.d.ts} +10 -9
  45. package/dist/{trajectory-BI-mrVFT.js → trajectory-DeURWIhj.js} +6 -5
  46. package/dist/trajectory-DeURWIhj.js.map +1 -0
  47. package/dist/{types-De-TVQxS.d.ts → types-Sw0oHW-_.d.ts} +6 -7
  48. package/dist/ui.d.ts +2 -1
  49. package/dist/ui.js +8 -1
  50. package/dist/ui.js.map +1 -1
  51. package/dist/viewer-app/assets/index-BYF5Dp7d.js +2 -0
  52. package/dist/viewer-app/index.html +2 -1
  53. package/dist/viewer.d.ts +26 -12
  54. package/dist/viewer.js +282 -63
  55. package/dist/viewer.js.map +1 -1
  56. package/package.json +5 -5
  57. package/dist/adapters-DNnzeLxr.js.map +0 -1
  58. package/dist/core-CDrz0NM1.js.map +0 -1
  59. package/dist/engine-ha9xmgwE.js.map +0 -1
  60. package/dist/invoke-px31fffH.js.map +0 -1
  61. package/dist/json_schema_to_standard-BTWD0J6p.js.map +0 -1
  62. package/dist/leading_system-DfJLqpGi.js.map +0 -1
  63. package/dist/search-CA_OqFeW.js.map +0 -1
  64. package/dist/trajectory-BI-mrVFT.js.map +0 -1
  65. package/dist/viewer-app/assets/index-Fnh5HKSU.js +0 -2
@@ -1,3 +1,4 @@
1
+ import { n as is_record } from "./records-1HU7mWXf.js";
1
2
  import { createHash, randomUUID } from "node:crypto";
2
3
  //#region src/core/cleanup.ts
3
4
  const HANDLER_TIMEOUT_MS = 5e3;
@@ -98,12 +99,12 @@ function description_meta(description) {
98
99
  /**
99
100
  * Closed registry of every `Step.kind` produced by the composition layer.
100
101
  *
101
- * Studio (and any other consumer that needs to enumerate primitives: palette,
102
- * docs, code generation) can rely on this being the exhaustive set. New
102
+ * The viewer (and any other consumer that needs to enumerate primitives:
103
+ * palette, docs, code generation) can rely on this being the exhaustive set. New
103
104
  * primitives must add their kind here. `step_kinds.test.ts` pins the list
104
- * against the kinds core actually constructs, and
105
- * `composites/__tests__/coverage.test.ts` covers the four composite kinds
106
- * whose factories live outside core.
105
+ * against the kinds core actually constructs, in both directions. The
106
+ * composites (`ensemble`, `tournament`, and the rest) add no kinds of their
107
+ * own: each builds a `compose` step that carries its name as the display name.
107
108
  */
108
109
  const STEP_KINDS = [
109
110
  "step",
@@ -117,10 +118,6 @@ const STEP_KINDS = [
117
118
  "timeout",
118
119
  "loop",
119
120
  "compose",
120
- "adversarial",
121
- "ensemble",
122
- "tournament",
123
- "consensus",
124
121
  "checkpoint",
125
122
  "suspend",
126
123
  "scope",
@@ -575,7 +572,7 @@ function is_step(value) {
575
572
  * place of the config line, rather than again among the children.
576
573
  *
577
574
  * `describe.json(step)` returns a `FlowNode` tree (kind, id, config, children)
578
- * for tooling (Studio UI, Mermaid renderers, diff tools). Function values
575
+ * for tooling (the viewer, Mermaid renderers, diff tools). Function values
579
576
  * serialize as `{ kind: '<fn>', name? }` and schemas as `{ kind: '<schema>' }`.
580
577
  *
581
578
  * `describe.diagram(step)` draws the `describe.json` tree as an annotated
@@ -585,8 +582,9 @@ function is_step(value) {
585
582
  * `side_effect` that a resumed run can run again before it reaches a gate
586
583
  * (see replays.ts).
587
584
  *
588
- * Both forms detect cycles. Under the default (loose) mode, back-references
589
- * render as `<cycle>(id)` in text and `{ kind: '<cycle>', id }` in JSON. Under
585
+ * Every form detects cycles, since the diagram and the replay hints read the
586
+ * `describe.json` tree. Under the default (loose) mode, back-references render
587
+ * as `<cycle>(id)` in text and `{ kind: '<cycle>', id }` in JSON. Under
590
588
  * `{ strict: true }`, cycles throw `describe_cycle_error`.
591
589
  */
592
590
  const INDENT = " ";
@@ -955,13 +953,18 @@ function create_streaming_channel(base, high_water_mark = STREAMING_HIGH_WATER_M
955
953
  *
956
954
  * Dispatches a step to its kind-specific handler. `runner.ts` contains no
957
955
  * composer-specific logic beyond a Map lookup on `step.kind`; each composer
958
- * file registers its handler at module load via `register_kind(...)`.
956
+ * file registers its handler at module load via `register_traced_kind(...)`.
959
957
  *
960
958
  * `run(flow, input, options?)` constructs a fresh `RunContext` per top-level
961
959
  * call, installs process signal handlers (opt-out via options), forwards an
962
960
  * optional caller-supplied `AbortSignal` into the run, and guarantees cleanup
963
961
  * handlers execute in LIFO order on success, failure, or abort.
964
962
  *
963
+ * A SIGINT or SIGTERM aborts only the runs that installed the handlers. A run
964
+ * started with `install_signal_handlers: false` keeps going through a signal,
965
+ * even while another run's handlers are installed, because opting out says
966
+ * the host forwards cancellation itself, through `abort`.
967
+ *
965
968
  * `run.stream(flow, input, options?)` is a secondary entry point returning
966
969
  * `{ events, result }`. Streaming is purely observational; the step graph is
967
970
  * identical to `run(...)`.
@@ -1065,24 +1068,24 @@ function error_meta(err) {
1065
1068
  }
1066
1069
  return meta;
1067
1070
  }
1068
- const active_runs = /* @__PURE__ */ new Set();
1071
+ const signal_runs = /* @__PURE__ */ new Set();
1069
1072
  let signal_handler_installed = false;
1070
1073
  let sigint_handler = null;
1071
1074
  let sigterm_handler = null;
1072
1075
  /**
1073
- * Build the handler for one process signal: it aborts every active run with
1074
- * an `aborted_error` that names the signal.
1076
+ * Build the handler for one process signal: it aborts every run that installed
1077
+ * the handlers with an `aborted_error` that names the signal.
1075
1078
  */
1076
1079
  function abort_all_on(signal_name) {
1077
1080
  return () => {
1078
- for (const controller of active_runs) controller.abort(new aborted_error(`received ${signal_name}`, { reason: { signal: signal_name } }));
1081
+ for (const controller of signal_runs) controller.abort(new aborted_error(`received ${signal_name}`, { reason: { signal: signal_name } }));
1079
1082
  };
1080
1083
  }
1081
1084
  /**
1082
1085
  * Install process-wide SIGINT/SIGTERM handlers once.
1083
1086
  *
1084
- * The handlers abort every active run with an `aborted_error` naming the
1085
- * signal, so a Ctrl-C tears down all in-flight flows through the normal
1087
+ * The handlers abort every run that installed them with an `aborted_error`
1088
+ * naming the signal, so a Ctrl-C tears down those flows through the normal
1086
1089
  * abort/cleanup path instead of killing the process mid-step.
1087
1090
  */
1088
1091
  function ensure_signal_handlers() {
@@ -1094,14 +1097,15 @@ function ensure_signal_handlers() {
1094
1097
  process.on("SIGTERM", sigterm_handler);
1095
1098
  }
1096
1099
  /**
1097
- * Remove the process signal handlers once the last active run settles.
1100
+ * Remove the process signal handlers once the last run that installed them
1101
+ * settles.
1098
1102
  *
1099
1103
  * Keeps a library embed from leaving stray `process.on` listeners behind
1100
1104
  * after all runs complete.
1101
1105
  */
1102
1106
  function release_signal_handlers() {
1103
1107
  if (!signal_handler_installed) return;
1104
- if (active_runs.size > 0) return;
1108
+ if (signal_runs.size > 0) return;
1105
1109
  signal_handler_installed = false;
1106
1110
  if (sigint_handler) process.off("SIGINT", sigint_handler);
1107
1111
  if (sigterm_handler) process.off("SIGTERM", sigterm_handler);
@@ -1117,7 +1121,7 @@ const noop_logger = {
1117
1121
  * Wrap a logger so every emitted event automatically carries `run_id` and a
1118
1122
  * `ts` (epoch milliseconds) stamped at emission.
1119
1123
  *
1120
- * Studios and other downstream consumers multiplex events across runs by
1124
+ * The viewer and other downstream consumers multiplex events across runs by
1121
1125
  * `run_id` and reconstruct real timing from `ts` instead of fabricating it at
1122
1126
  * ingest. Either field already present on an event or its meta is preserved;
1123
1127
  * we never overwrite a caller-supplied value.
@@ -1286,8 +1290,10 @@ function start_run$1(flow, input, options, high_water_mark) {
1286
1290
  streaming
1287
1291
  };
1288
1292
  track_resumed_gates(run_id, options.resume_data);
1289
- active_runs.add(controller);
1290
- if (install_signal_handlers) ensure_signal_handlers();
1293
+ if (install_signal_handlers) {
1294
+ signal_runs.add(controller);
1295
+ ensure_signal_handlers();
1296
+ }
1291
1297
  const result = (async () => {
1292
1298
  let terminal = {
1293
1299
  kind: "run_end",
@@ -1312,7 +1318,7 @@ function start_run$1(flow, input, options, high_water_mark) {
1312
1318
  logger.record(terminal);
1313
1319
  unreached_gates.delete(run_id);
1314
1320
  unlink_abort();
1315
- active_runs.delete(controller);
1321
+ signal_runs.delete(controller);
1316
1322
  release_signal_handlers();
1317
1323
  if (close_stream) close_stream();
1318
1324
  }
@@ -1432,6 +1438,63 @@ const run = Object.assign(run_impl, {
1432
1438
  until_suspended: run_until_suspended
1433
1439
  });
1434
1440
  //#endregion
1441
+ //#region src/schema/validate.ts
1442
+ /**
1443
+ * Validate `value` against `schema`, returning the typed value or the issues.
1444
+ *
1445
+ * Always async, even for a validator that answers synchronously: the spec
1446
+ * permits `validate` to return either a result or a promise of one, and
1447
+ * Fascicle cannot know which a given vendor does. Awaiting a non-promise is
1448
+ * cheap; guessing wrong is a silent bug.
1449
+ */
1450
+ async function validate_schema(schema, value) {
1451
+ const result = await schema["~standard"].validate(value);
1452
+ if (result.issues) return {
1453
+ ok: false,
1454
+ issues: result.issues.map(normalize_issue)
1455
+ };
1456
+ return {
1457
+ ok: true,
1458
+ value: result.value
1459
+ };
1460
+ }
1461
+ /**
1462
+ * Flatten one vendor issue into Fascicle's shape.
1463
+ *
1464
+ * The spec allows a path segment to be a bare key or a `{ key }` wrapper, and
1465
+ * allows the path to be absent entirely. Normalizing here means no consumer has
1466
+ * to know which vendor produced the issue.
1467
+ */
1468
+ function normalize_issue(issue) {
1469
+ if (issue.path === void 0) return { message: issue.message };
1470
+ const path = issue.path.map((segment) => typeof segment === "object" ? segment.key : segment);
1471
+ return {
1472
+ message: issue.message,
1473
+ path
1474
+ };
1475
+ }
1476
+ /**
1477
+ * Render issues as the single line that goes into an error message or a repair
1478
+ * prompt fed back to the model.
1479
+ *
1480
+ * Paths are dotted (`address.city`, `items.0.name`) rather than bracketed for
1481
+ * indices: the model reads it as a hint about which field to fix, and one
1482
+ * consistent separator is easier to follow than two.
1483
+ */
1484
+ function format_schema_issues(issues) {
1485
+ if (issues.length === 0) return "unknown schema issue";
1486
+ return issues.map(format_issue).join("; ");
1487
+ }
1488
+ /**
1489
+ * Render one issue as `path: message`, or just the message when the vendor
1490
+ * reported no path (a failure about the value as a whole).
1491
+ */
1492
+ function format_issue(issue) {
1493
+ const path = issue.path;
1494
+ if (path === void 0 || path.length === 0) return issue.message;
1495
+ return `${path.map((segment) => String(segment)).join(".")}: ${issue.message}`;
1496
+ }
1497
+ //#endregion
1435
1498
  //#region src/core/durable.ts
1436
1499
  /**
1437
1500
  * durable: drive a flow that suspends across processes, one event at a time.
@@ -1498,16 +1561,10 @@ function shape_of(node) {
1498
1561
  ];
1499
1562
  }
1500
1563
  /**
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
1564
  * Read a stored suspension back, or `null` when the value isn't one.
1508
1565
  */
1509
1566
  function as_suspension(value) {
1510
- if (!is_object(value)) return null;
1567
+ if (!is_record(value)) return null;
1511
1568
  const { id, payload, deadline_at } = value;
1512
1569
  if (typeof id !== "string") return null;
1513
1570
  return {
@@ -1522,10 +1579,10 @@ function as_suspension(value) {
1522
1579
  * the run again from its input, where its checkpoints still serve.
1523
1580
  */
1524
1581
  function as_record(value) {
1525
- if (!is_object(value) || value["format"] !== 1) return void 0;
1582
+ if (!is_record(value) || value["format"] !== 1) return void 0;
1526
1583
  const { revision, input, flow, resume_data, output, error, status } = value;
1527
1584
  if (typeof revision !== "number" || typeof flow !== "string") return void 0;
1528
- if (!is_object(resume_data) || !STATUSES.has(status)) return void 0;
1585
+ if (!is_record(resume_data) || !STATUSES.has(status)) return void 0;
1529
1586
  const base = {
1530
1587
  format: 1,
1531
1588
  revision,
@@ -1680,7 +1737,40 @@ async function check_shape(drive, lease, record) {
1680
1737
  */
1681
1738
  async function read_inbox(scope, gate_id) {
1682
1739
  const entry = await scope.scope(INBOX).get(gate_id);
1683
- return is_object(entry) && "data" in entry ? { data: entry["data"] } : void 0;
1740
+ return is_record(entry) && "data" in entry ? { data: entry["data"] } : void 0;
1741
+ }
1742
+ /**
1743
+ * Leave `data` in the run's inbox for `gate_id`, unless a datum already waits
1744
+ * there, another resume is leaving one, the run has already passed the gate,
1745
+ * or the run is gone.
1746
+ *
1747
+ * The reads and the write happen under a claim on the gate's inbox key, so of
1748
+ * two resumes that race for one gate, only the first to claim it writes, and
1749
+ * the other drops its datum as it would on finding one there. The inbox is
1750
+ * read before the record because `take_up` saves a gate's datum into the
1751
+ * record before it deletes the inbox entry, so a datum that's taken up between
1752
+ * the two reads still shows in the record. The claim lasts `lease_ms` and
1753
+ * comes off right after the write.
1754
+ *
1755
+ * Two windows stay open, because the store contract has no compare-and-set to
1756
+ * close them with. A resume that stalls past its claim, after its reads and
1757
+ * before its write, can still write once another resume has moved the run
1758
+ * past the gate. And a `delete` that lands between the record read and the
1759
+ * write leaves the datum in the cleared scope, where a new run under the same
1760
+ * id takes it up.
1761
+ */
1762
+ async function deliver(drive, gate_id, data) {
1763
+ const key = `${INBOX}/${gate_id}`;
1764
+ const owner = randomUUID();
1765
+ if (!await drive.scope.claim(key, owner, drive.lease_ms)) return;
1766
+ try {
1767
+ if (await read_inbox(drive.scope, gate_id) !== void 0) return;
1768
+ const record = as_record(await drive.scope.get(RECORD));
1769
+ if (record === void 0 || Object.hasOwn(record.resume_data, gate_id)) return;
1770
+ await drive.scope.scope(INBOX).set(gate_id, { data });
1771
+ } finally {
1772
+ await drive.scope.release(key, owner);
1773
+ }
1684
1774
  }
1685
1775
  /**
1686
1776
  * Move the resume data waiting at the run's gate into the run, or resolve
@@ -1887,21 +1977,28 @@ async function start_run(driver, run_id, flow, input, options) {
1887
1977
  *
1888
1978
  * Each datum is written to the run's inbox before the lease is taken, so a
1889
1979
  * 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.
1980
+ * it up. Data for a gate the run has already passed is dropped, because
1981
+ * changing it would change the replay, and so is data for a run that's gone,
1982
+ * and data for a gate whose inbox already holds some: the first datum to
1983
+ * reach a gate is the one it gets. Each of those checks happens under a claim
1984
+ * on the gate's inbox key, so it holds when two calls race for one gate, and
1985
+ * when another call moves the run past the gate or deletes the run before
1986
+ * this one claims. The claim lasts the driver's `lease_ms` and comes off
1987
+ * right after the write, so a call that dies between the two holds that
1988
+ * gate's data back until the claim lapses, and data sent for the gate in that
1989
+ * window is dropped. Without a compare-and-set in the store contract, two
1990
+ * windows stay open: a call that stalls past its claim can still write data
1991
+ * for a gate the run has passed since, and a `delete` that lands between the
1992
+ * call's record read and its write leaves the data for a new run under the
1993
+ * same id. `undefined` resumes nothing. A call with no new data still drives
1994
+ * a run that failed, or whose drive died, once more.
1895
1995
  */
1896
1996
  async function resume_run(driver, run_id, flow, resume_data, options) {
1897
1997
  const drive = drive_for(driver, run_id, flow, options);
1898
1998
  const record = await existing_record(run_id, drive.scope);
1899
1999
  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
- }));
2000
+ const fresh = Object.entries(resume_data).filter(([, data]) => data !== void 0);
2001
+ await Promise.all(fresh.map(([id, data]) => deliver(drive, id, data)));
1905
2002
  return bring_to_rest(drive, () => existing_record(run_id, drive.scope));
1906
2003
  }
1907
2004
  /**
@@ -2280,8 +2377,8 @@ register_traced_kind("branch");
2280
2377
  *
2281
2378
  * `map({ items, do, concurrency? })` extracts an array via `items(input)`,
2282
2379
  * runs `do` once per element, returns an array in the same order as inputs.
2283
- * `concurrency` caps simultaneous in-flight items; omitted means full
2284
- * parallelism.
2380
+ * `concurrency` caps simultaneous in-flight items (rounded down, and never
2381
+ * below 1); omitted means full parallelism, and NaN throws at construction.
2285
2382
  *
2286
2383
  * The first item that throws stops new items from starting, and its error
2287
2384
  * propagates once the in-flight items settle, so every result the other items
@@ -2347,16 +2444,19 @@ function settle_failure(err, index, step_id, ctx) {
2347
2444
  * without it the first error fails the map.
2348
2445
  */
2349
2446
  function build_map(config, fulfilled, rejected) {
2350
- const id = next_id$7();
2351
2447
  const { items, do: per_item, concurrency, name } = config;
2448
+ if (Number.isNaN(concurrency)) throw new TypeError(`map: concurrency must be a number, got ${concurrency}`);
2449
+ const id = next_id$7();
2450
+ const concurrency_cap = concurrency === void 0 ? void 0 : Math.max(1, Math.floor(concurrency));
2352
2451
  const run_fn = async (input, ctx) => {
2353
2452
  const list = await items(input);
2354
2453
  if (list.length === 0) return [];
2355
2454
  const results = Array.from({ length: list.length });
2356
- const limit = concurrency === void 0 ? list.length : Math.max(1, concurrency);
2455
+ const limit = concurrency_cap ?? list.length;
2357
2456
  const controllers = [];
2358
2457
  const on_parent_abort = install_abort_fan_out(ctx, controllers);
2359
2458
  let cursor = 0;
2459
+ let has_worker_error = false;
2360
2460
  let worker_error = void 0;
2361
2461
  const run_one = async (idx) => {
2362
2462
  const local = new AbortController();
@@ -2372,12 +2472,15 @@ function build_map(config, fulfilled, rejected) {
2372
2472
  results[idx] = fulfilled(value);
2373
2473
  } catch (err) {
2374
2474
  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;
2475
+ else if (!has_worker_error) {
2476
+ has_worker_error = true;
2477
+ worker_error = err;
2478
+ }
2376
2479
  }
2377
2480
  };
2378
2481
  const worker = async () => {
2379
2482
  while (true) {
2380
- if (ctx.abort.aborted || worker_error !== void 0) return;
2483
+ if (ctx.abort.aborted || has_worker_error) return;
2381
2484
  const idx = cursor;
2382
2485
  cursor += 1;
2383
2486
  if (idx >= list.length) return;
@@ -2390,7 +2493,7 @@ function build_map(config, fulfilled, rejected) {
2390
2493
  for (let w = 0; w < worker_count; w += 1) workers.push(worker());
2391
2494
  await Promise.all(workers);
2392
2495
  throw_if_aborted(ctx);
2393
- if (worker_error !== void 0) throw worker_error;
2496
+ if (has_worker_error) throw worker_error;
2394
2497
  return results;
2395
2498
  } finally {
2396
2499
  ctx.abort.removeEventListener("abort", on_parent_abort);
@@ -2482,9 +2585,8 @@ function compute_backoff(policy, attempt) {
2482
2585
  * Sleep `ms`, rejecting the moment `signal` fires instead of serving out the
2483
2586
  * delay, so a pending abort never waits out a backoff.
2484
2587
  *
2485
- * A non-positive `ms` resolves without arming a timer or consulting `signal`,
2486
- * matching what both retry layers did before. The rejection value is
2487
- * `to_error` applied to `signal.reason`.
2588
+ * A non-positive `ms` resolves without arming a timer or consulting `signal`.
2589
+ * The rejection value is `to_error` applied to `signal.reason`.
2488
2590
  */
2489
2591
  function wait_with_abort(ms, signal, to_error) {
2490
2592
  if (ms <= 0) return Promise.resolve();
@@ -2714,6 +2816,7 @@ function fallback(primary, backup, options) {
2714
2816
  };
2715
2817
  const config_meta = {};
2716
2818
  if (when) config_meta["when"] = when;
2819
+ if (handoff) config_meta["handoff"] = handoff;
2717
2820
  if (options?.project) config_meta["project"] = options.project;
2718
2821
  if (options?.name !== void 0) config_meta["display_name"] = options.name;
2719
2822
  return {
@@ -2874,6 +2977,7 @@ function wrap_guard(guard, loop_id) {
2874
2977
  */
2875
2978
  function loop(config) {
2876
2979
  const { init, body, finish, name } = config;
2980
+ if (Number.isNaN(config.max_rounds)) throw new TypeError(`loop: max_rounds must be a number, got ${config.max_rounds}`);
2877
2981
  const rounds_limit = Math.max(1, Math.floor(config.max_rounds));
2878
2982
  const id = next_id$2();
2879
2983
  const guard = wrap_guard(config.guard, id);
@@ -2974,6 +3078,14 @@ register_traced_kind("compose");
2974
3078
  * lookup records a `checkpoint` trajectory event with
2975
3079
  * `status: 'hit' | 'miss' | 'read_error'`.
2976
3080
  *
3081
+ * A failed write (store throws on `set`) doesn't fail the run either. It
3082
+ * records a `checkpoint` event with `status: 'write_error'` and returns the
3083
+ * inner result, because `inner` has already run and been paid for, and a
3084
+ * checkpoint is a cache, not the result. The next run with the same key
3085
+ * misses and runs `inner` again. `on_write_error: 'fail'` records the same
3086
+ * event and then throws the store's error, for a result that a `suspend`
3087
+ * hands to an approver, which has to be the one the store kept.
3088
+ *
2977
3089
  * Wrapping an anonymous inner step throws synchronously at construction time
2978
3090
  * with the message `checkpoint requires a named step, got anonymous`, because
2979
3091
  * a cached result must map back to a stable, identifiable step.
@@ -3001,6 +3113,67 @@ function gates_within(root, seen = /* @__PURE__ */ new Set()) {
3001
3113
  return root.kind === "suspend" ? [root.id, ...inner] : inner;
3002
3114
  }
3003
3115
  /**
3116
+ * The fields every `checkpoint` event of one lookup carries: the step `id`,
3117
+ * the store `key`, and the `span_id` of the checkpoint's span when there is
3118
+ * one, so a viewer can nest the event.
3119
+ */
3120
+ function event_meta(id, key, ctx) {
3121
+ const meta = {
3122
+ id,
3123
+ key
3124
+ };
3125
+ if (ctx.parent_span_id !== void 0) meta["span_id"] = ctx.parent_span_id;
3126
+ return meta;
3127
+ }
3128
+ /**
3129
+ * The `checkpoint` event for a store call that threw, carrying its message.
3130
+ */
3131
+ function store_failure(status, err, meta) {
3132
+ return {
3133
+ kind: "checkpoint",
3134
+ status,
3135
+ error: err instanceof Error ? err.message : String(err),
3136
+ ...meta
3137
+ };
3138
+ }
3139
+ /**
3140
+ * The value stored at `key` in `store`, or `undefined` on a miss, recording
3141
+ * exactly one `checkpoint` event so hits, misses, and swallowed read errors
3142
+ * are all visible in the trajectory. A stored `null` or `undefined` is a
3143
+ * miss, which is what lets `undefined` stand for one, and a throwing
3144
+ * `store.get` still behaves as a miss (a broken store must not fail the run),
3145
+ * but under `status: 'read_error'` instead of silently.
3146
+ */
3147
+ async function look_up(store, key, meta, ctx) {
3148
+ try {
3149
+ const value = await store.get(key);
3150
+ const hit = value !== null && value !== void 0;
3151
+ ctx.trajectory.record({
3152
+ kind: "checkpoint",
3153
+ status: hit ? "hit" : "miss",
3154
+ ...meta
3155
+ });
3156
+ return hit ? value : void 0;
3157
+ } catch (err) {
3158
+ ctx.trajectory.record(store_failure("read_error", err, meta));
3159
+ return;
3160
+ }
3161
+ }
3162
+ /**
3163
+ * Write `result` to `store` at `key`. A throwing `store.set` records
3164
+ * `status: 'write_error'` and leaves the result to the caller, since the
3165
+ * inner step that produced it has already run, unless `fail_on_write` says
3166
+ * to throw the store's error once the event is recorded.
3167
+ */
3168
+ async function keep(store, key, result, meta, ctx, fail_on_write) {
3169
+ try {
3170
+ await store.set(key, result);
3171
+ } catch (err) {
3172
+ ctx.trajectory.record(store_failure("write_error", err, meta));
3173
+ if (fail_on_write) throw err;
3174
+ }
3175
+ }
3176
+ /**
3004
3177
  * Wrap `inner` with persist-and-resume behavior keyed by `config.key`.
3005
3178
  *
3006
3179
  * `key` is a fixed string or a function of the input. Without a
@@ -3013,42 +3186,20 @@ function checkpoint(inner, config) {
3013
3186
  if (inner.anonymous === true) throw new Error("checkpoint requires a named step, got anonymous — give the inner step an id with step('id', fn)");
3014
3187
  const id = next_id();
3015
3188
  const key_spec = config.key;
3189
+ const fail_on_write = config.on_write_error === "fail";
3016
3190
  const gates = gates_within(inner);
3017
3191
  const run_fn = async (input, ctx) => {
3018
3192
  const key = typeof key_spec === "function" ? key_spec(input) : key_spec;
3019
3193
  const store = ctx.checkpoint_store;
3020
- if (store) {
3021
- let cached = void 0;
3022
- let hit = false;
3023
- const lookup_meta = {
3024
- id,
3025
- key
3026
- };
3027
- if (ctx.parent_span_id !== void 0) lookup_meta["span_id"] = ctx.parent_span_id;
3028
- try {
3029
- cached = await store.get(key);
3030
- hit = cached !== null && cached !== void 0;
3031
- ctx.trajectory.record({
3032
- kind: "checkpoint",
3033
- status: hit ? "hit" : "miss",
3034
- ...lookup_meta
3035
- });
3036
- } catch (err) {
3037
- hit = false;
3038
- ctx.trajectory.record({
3039
- kind: "checkpoint",
3040
- status: "read_error",
3041
- error: err instanceof Error ? err.message : String(err),
3042
- ...lookup_meta
3043
- });
3044
- }
3045
- if (hit) {
3046
- mark_gates_reached(ctx, gates);
3047
- return cached;
3048
- }
3194
+ if (!store) return dispatch_step(inner, input, ctx);
3195
+ const meta = event_meta(id, key, ctx);
3196
+ const cached = await look_up(store, key, meta, ctx);
3197
+ if (cached !== void 0) {
3198
+ mark_gates_reached(ctx, gates);
3199
+ return cached;
3049
3200
  }
3050
3201
  const result = await dispatch_step(inner, input, ctx);
3051
- if (store) await store.set(key, result);
3202
+ await keep(store, key, result, meta, ctx, fail_on_write);
3052
3203
  return result;
3053
3204
  };
3054
3205
  const config_meta = { key: key_spec };
@@ -3064,63 +3215,6 @@ function checkpoint(inner, config) {
3064
3215
  }
3065
3216
  register_traced_kind("checkpoint");
3066
3217
  //#endregion
3067
- //#region src/schema/validate.ts
3068
- /**
3069
- * Validate `value` against `schema`, returning the typed value or the issues.
3070
- *
3071
- * Always async, even for a validator that answers synchronously: the spec
3072
- * permits `validate` to return either a result or a promise of one, and
3073
- * Fascicle cannot know which a given vendor does. Awaiting a non-promise is
3074
- * cheap; guessing wrong is a silent bug.
3075
- */
3076
- async function validate_schema(schema, value) {
3077
- const result = await schema["~standard"].validate(value);
3078
- if (result.issues) return {
3079
- ok: false,
3080
- issues: result.issues.map(normalize_issue)
3081
- };
3082
- return {
3083
- ok: true,
3084
- value: result.value
3085
- };
3086
- }
3087
- /**
3088
- * Flatten one vendor issue into Fascicle's shape.
3089
- *
3090
- * The spec allows a path segment to be a bare key or a `{ key }` wrapper, and
3091
- * allows the path to be absent entirely. Normalizing here means no consumer has
3092
- * to know which vendor produced the issue.
3093
- */
3094
- function normalize_issue(issue) {
3095
- if (issue.path === void 0) return { message: issue.message };
3096
- const path = issue.path.map((segment) => typeof segment === "object" ? segment.key : segment);
3097
- return {
3098
- message: issue.message,
3099
- path
3100
- };
3101
- }
3102
- /**
3103
- * Render issues as the single line that goes into an error message or a repair
3104
- * prompt fed back to the model.
3105
- *
3106
- * Paths are dotted (`address.city`, `items.0.name`) rather than bracketed for
3107
- * indices: the model reads it as a hint about which field to fix, and one
3108
- * consistent separator is easier to follow than two.
3109
- */
3110
- function format_schema_issues(issues) {
3111
- if (issues.length === 0) return "unknown schema issue";
3112
- return issues.map(format_issue).join("; ");
3113
- }
3114
- /**
3115
- * Render one issue as `path: message`, or just the message when the vendor
3116
- * reported no path (a failure about the value as a whole).
3117
- */
3118
- function format_issue(issue) {
3119
- const path = issue.path;
3120
- if (path === void 0 || path.length === 0) return issue.message;
3121
- return `${path.map((segment) => String(segment)).join(".")}: ${issue.message}`;
3122
- }
3123
- //#endregion
3124
3218
  //#region src/core/suspend.ts
3125
3219
  /**
3126
3220
  * suspend: human-in-the-loop pause.
@@ -3156,9 +3250,11 @@ function resume_value_for(ctx, suspend_id) {
3156
3250
  * First run fires the `on` side effect and throws `suspended_error`; a resume
3157
3251
  * run validates `resume_data[id]` against `resume_schema` and feeds it to
3158
3252
  * `combine`. The step's id is the user-supplied suspend id so resume data can
3159
- * be addressed to it.
3253
+ * be addressed to it, which is why it's held to the step id rule and throws
3254
+ * a `TypeError` when it's built if it isn't an identifier.
3160
3255
  */
3161
3256
  function suspend(config) {
3257
+ assert_valid_step_id(config.id, "suspend id", "put the label in name");
3162
3258
  const suspend_id = config.id;
3163
3259
  const deadline_ms = config.deadline_ms;
3164
3260
  const on_fn = config.on;
@@ -3287,7 +3383,7 @@ function scope(children, options) {
3287
3383
  function stash(key, source, options) {
3288
3384
  const id = next_stash_id();
3289
3385
  const run_fn = async (input, ctx) => {
3290
- if (!is_scope_state(ctx.state)) throw new Error("stash() may only appear inside scope(); got: top-level");
3386
+ if (!is_scope_state(ctx.state)) throw new Error(`stash('${key}') ran outside any scope(): wrap it and the steps that use() its key in scope([...])`);
3291
3387
  const value = await dispatch_step(source, input, ctx);
3292
3388
  ctx.state.set(key, value);
3293
3389
  return value;
@@ -3312,7 +3408,10 @@ function stash(key, source, options) {
3312
3408
  function use(keys, fn, options) {
3313
3409
  const id = next_use_id();
3314
3410
  const run_fn = async (input, ctx) => {
3315
- if (!is_scope_state(ctx.state)) throw new Error("use() may only appear inside scope(); got: top-level");
3411
+ if (!is_scope_state(ctx.state)) {
3412
+ const listed = keys.map((k) => `'${k}'`).join(", ");
3413
+ throw new Error(`use([${listed}]) ran outside any scope(): wrap it and the stash() steps that set its keys in scope([...])`);
3414
+ }
3316
3415
  const projection = {};
3317
3416
  for (const k of keys) projection[k] = ctx.state.get(k);
3318
3417
  return fn(projection, input, ctx);
@@ -3518,6 +3617,6 @@ function chain(input_name) {
3518
3617
  }
3519
3618
  register_traced_kind("chain");
3520
3619
  //#endregion
3521
- 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 };
3620
+ export { describe_cycle_error as A, durable 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, suggest_step_id as S, validate_schema as T, parallel as _, suspend as a, assert_valid_step_id as b, loop as c, retry as d, compute_backoff as f, branch as g, map as h, use as i, error_path as j, aborted_error as k, timeout as l, pipe as m, scope as n, checkpoint as o, wait_with_abort as p, stash as r, compose as s, chain as t, fallback as u, sequence as v, format_schema_issues as w, is_valid_step_id as x, step as y, resolve_display_name as z };
3522
3621
 
3523
- //# sourceMappingURL=core-CDrz0NM1.js.map
3622
+ //# sourceMappingURL=core-CErsxGF6.js.map