fascicle 0.11.0 → 0.11.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.
@@ -552,8 +552,8 @@ const dispatch = /* @__PURE__ */ new Map();
552
552
  /**
553
553
  * Register the dispatch handler for a step kind.
554
554
  *
555
- * Composer files call this (directly or via `register_traced_kind`) at module
556
- * load, which is how the runner stays free of composer-specific logic.
555
+ * Composer files call this via `register_traced_kind` at module load, which is
556
+ * how the runner stays free of composer-specific logic.
557
557
  */
558
558
  function register_kind(kind, fn) {
559
559
  dispatch.set(kind, fn);
@@ -723,6 +723,26 @@ function throw_if_aborted(ctx) {
723
723
  throw reason instanceof Error ? reason : new aborted_error("aborted", { reason });
724
724
  }
725
725
  /**
726
+ * Install a fan-out abort listener over a set of child controllers: when
727
+ * `ctx.abort` fires, every controller currently in `controllers` is aborted
728
+ * with the same reason. An already-aborted parent fires immediately instead
729
+ * of registering a listener.
730
+ *
731
+ * Concurrent composers (`map`, `parallel`) use this to propagate a parent
732
+ * abort into each in-flight child's composed signal. `controllers` is read by
733
+ * reference, so a caller that appends to the array after installing (as
734
+ * `map` does per newly-started item) is still covered by later aborts.
735
+ * Returns the listener so the caller can remove it once its children settle.
736
+ */
737
+ function install_abort_fan_out(ctx, controllers) {
738
+ const on_parent_abort = () => {
739
+ for (const c of controllers) c.abort(ctx.abort.reason);
740
+ };
741
+ if (ctx.abort.aborted) on_parent_abort();
742
+ else ctx.abort.addEventListener("abort", on_parent_abort, { once: true });
743
+ return on_parent_abort;
744
+ }
745
+ /**
726
746
  * Forward a caller-owned AbortSignal into the run's internal controller and
727
747
  * return an unlink function. The reason is preserved so the original
728
748
  * cancellation cause propagates out of `run`. The listener is `once` and the
@@ -909,7 +929,7 @@ register_traced_kind("step");
909
929
  * True when the value has a string `id`, a string `kind`, and a callable
910
930
  * `run`.
911
931
  */
912
- function is_step$1(value) {
932
+ function is_step(value) {
913
933
  if (typeof value !== "object" || value === null) return false;
914
934
  if (!("id" in value) || !("kind" in value) || !("run" in value)) return false;
915
935
  const { id, kind, run } = value;
@@ -989,8 +1009,35 @@ function render_text(node, depth, lines, path, strict) {
989
1009
  * Functions become `<fn>` or `<fn:name>`, zod schemas `<schema>`, and Step
990
1010
  * references `kind(id)`; arrays and plain objects recurse. Strings are
991
1011
  * JSON-quoted so empty and whitespace values stay visible.
1012
+ *
1013
+ * Steps, arrays, and renderable objects each own a branch; everything else
1014
+ * (functions, the empty markers, schemas, primitives) resolves through
1015
+ * `render_scalar_text`. The three object-shaped cases are mutually exclusive at
1016
+ * runtime, so their order relative to the scalar cases is immaterial.
992
1017
  */
993
1018
  function render_value_text(value, path, strict) {
1019
+ if (is_step(value)) return render_step_text(value, path, strict);
1020
+ if (Array.isArray(value)) return `[${value.map((item) => render_value_text(item, path, strict)).join(", ")}]`;
1021
+ if (is_renderable_object(value)) return `{ ${Object.entries({ ...value }).map(([k, v]) => `${k}: ${render_value_text(v, path, strict)}`).join(", ")} }`;
1022
+ return render_scalar_text(value);
1023
+ }
1024
+ /**
1025
+ * Render a Step reference for the text tree: a back-reference on the current
1026
+ * path becomes `<cycle>(id)` (or throws under strict mode); otherwise `kind(id)`.
1027
+ */
1028
+ function render_step_text(value, path, strict) {
1029
+ if (path.has(value)) {
1030
+ if (strict) throw new describe_cycle_error(value.id);
1031
+ return `<cycle>(${value.id})`;
1032
+ }
1033
+ return `${value.kind}(${value.id})`;
1034
+ }
1035
+ /**
1036
+ * Render the non-recursive value cases for the text tree: functions (`<fn>` or
1037
+ * `<fn:name>`), the empty markers, zod schemas, and (via `render_primitive_text`)
1038
+ * raw primitives.
1039
+ */
1040
+ function render_scalar_text(value) {
994
1041
  if (typeof value === "function") {
995
1042
  const name = typeof value.name === "string" && value.name.length > 0 ? value.name : "";
996
1043
  return name ? `<fn:${name}>` : "<fn>";
@@ -998,15 +1045,14 @@ function render_value_text(value, path, strict) {
998
1045
  if (value === null) return "null";
999
1046
  if (value === void 0) return "undefined";
1000
1047
  if (is_zod_schema(value)) return "<schema>";
1001
- if (is_step$1(value)) {
1002
- if (path.has(value)) {
1003
- if (strict) throw new describe_cycle_error(value.id);
1004
- return `<cycle>(${value.id})`;
1005
- }
1006
- return `${value.kind}(${value.id})`;
1007
- }
1008
- if (Array.isArray(value)) return `[${value.map((item) => render_value_text(item, path, strict)).join(", ")}]`;
1009
- if (typeof value === "object") return `{ ${Object.entries({ ...value }).map(([k, v]) => `${k}: ${render_value_text(v, path, strict)}`).join(", ")} }`;
1048
+ return render_primitive_text(value);
1049
+ }
1050
+ /**
1051
+ * Render a primitive (or unrecognized) value for the text tree. Strings are
1052
+ * JSON-quoted so empty and whitespace values stay visible; bigints keep an `n`
1053
+ * suffix; anything unexpected falls back to JSON.
1054
+ */
1055
+ function render_primitive_text(value) {
1010
1056
  if (typeof value === "string") return JSON.stringify(value);
1011
1057
  if (typeof value === "bigint") return `${value.toString()}n`;
1012
1058
  if (typeof value === "symbol") return value.toString();
@@ -1052,8 +1098,42 @@ function render_json(node, path, strict) {
1052
1098
  * `{ kind: '<schema>' }`, Step references as `{ kind, id }`. `undefined`
1053
1099
  * maps to `null` and bigints/symbols to strings so the result survives
1054
1100
  * `JSON.stringify` without loss.
1101
+ *
1102
+ * Mirrors `render_value_text`: steps, arrays, and renderable objects each own a
1103
+ * branch, and everything else resolves through `render_scalar_json`.
1055
1104
  */
1056
1105
  function render_value_json(value, path, strict) {
1106
+ if (is_step(value)) return render_step_json(value, path, strict);
1107
+ if (Array.isArray(value)) return value.map((item) => render_value_json(item, path, strict));
1108
+ if (is_renderable_object(value)) {
1109
+ const out = {};
1110
+ for (const [k, v] of Object.entries({ ...value })) out[k] = render_value_json(v, path, strict);
1111
+ return out;
1112
+ }
1113
+ return render_scalar_json(value);
1114
+ }
1115
+ /**
1116
+ * Serialize a Step reference: a back-reference on the current path becomes
1117
+ * `{ kind: '<cycle>', id }` (or throws under strict mode); otherwise `{ kind, id }`.
1118
+ */
1119
+ function render_step_json(value, path, strict) {
1120
+ if (path.has(value)) {
1121
+ if (strict) throw new describe_cycle_error(value.id);
1122
+ return {
1123
+ kind: "<cycle>",
1124
+ id: value.id
1125
+ };
1126
+ }
1127
+ return {
1128
+ kind: value.kind,
1129
+ id: value.id
1130
+ };
1131
+ }
1132
+ /**
1133
+ * Serialize the non-recursive value cases: functions, the empty markers, zod
1134
+ * schemas, and (via `render_primitive_json`) raw primitives.
1135
+ */
1136
+ function render_scalar_json(value) {
1057
1137
  if (typeof value === "function") {
1058
1138
  const name = typeof value.name === "string" && value.name.length > 0 ? value.name : "";
1059
1139
  return name ? {
@@ -1064,25 +1144,14 @@ function render_value_json(value, path, strict) {
1064
1144
  if (value === null) return null;
1065
1145
  if (value === void 0) return null;
1066
1146
  if (is_zod_schema(value)) return { kind: "<schema>" };
1067
- if (is_step$1(value)) {
1068
- if (path.has(value)) {
1069
- if (strict) throw new describe_cycle_error(value.id);
1070
- return {
1071
- kind: "<cycle>",
1072
- id: value.id
1073
- };
1074
- }
1075
- return {
1076
- kind: value.kind,
1077
- id: value.id
1078
- };
1079
- }
1080
- if (Array.isArray(value)) return value.map((item) => render_value_json(item, path, strict));
1081
- if (typeof value === "object") {
1082
- const out = {};
1083
- for (const [k, v] of Object.entries({ ...value })) out[k] = render_value_json(v, path, strict);
1084
- return out;
1085
- }
1147
+ return render_primitive_json(value);
1148
+ }
1149
+ /**
1150
+ * Serialize a primitive (or unrecognized) value. `undefined` already resolves
1151
+ * to `null` in `render_scalar_json`; bigints and symbols become strings so the
1152
+ * result survives `JSON.stringify` without loss.
1153
+ */
1154
+ function render_primitive_json(value) {
1086
1155
  if (typeof value === "string") return value;
1087
1156
  if (typeof value === "number" || typeof value === "boolean") return value;
1088
1157
  if (typeof value === "bigint") return `${value.toString()}n`;
@@ -1097,6 +1166,14 @@ function is_zod_schema(value) {
1097
1166
  if (typeof value !== "object" || value === null) return false;
1098
1167
  return "_zod" in value || "_def" in value;
1099
1168
  }
1169
+ /**
1170
+ * True for a plain object rendered by recursing into its own entries: an object
1171
+ * that is neither null nor a zod schema. The Step and array cases are checked
1172
+ * before this at every call site, so they never reach it.
1173
+ */
1174
+ function is_renderable_object(value) {
1175
+ return typeof value === "object" && value !== null && !is_zod_schema(value);
1176
+ }
1100
1177
  //#endregion
1101
1178
  //#region src/core/sequence.ts
1102
1179
  /**
@@ -1124,7 +1201,7 @@ function next_id$10() {
1124
1201
  function sequence(children, options) {
1125
1202
  if (!Array.isArray(children)) throw new TypeError(`sequence(children): children must be an array of Steps, got ${typeof children} — sequence takes a single array, e.g. sequence([a, b, c])`);
1126
1203
  children.forEach((child, index) => {
1127
- if (is_step$1(child)) return;
1204
+ if (is_step(child)) return;
1128
1205
  throw new TypeError(`sequence(children): children[${index}] is not a Step, got ${typeof child}${typeof child === "function" ? " — wrap plain functions with step(fn), or use pipe(inner, fn) to transform output" : ""}`);
1129
1206
  });
1130
1207
  const id = next_id$10();
@@ -1175,6 +1252,68 @@ function next_id$9() {
1175
1252
  return `parallel_${parallel_counter}`;
1176
1253
  }
1177
1254
  /**
1255
+ * Run one child under its own composed abort signal and settle it: an
1256
+ * `'ok'`/`'err'` record rather than a thrown error, so a sibling's failure
1257
+ * never short-circuits `Promise.all` before every child has finished.
1258
+ */
1259
+ async function run_child(entry, local, input, ctx) {
1260
+ const [key, child] = entry;
1261
+ if (!local) throw new Error("parallel: missing controller");
1262
+ const composed = AbortSignal.any([ctx.abort, local.signal]);
1263
+ const child_ctx = {
1264
+ ...ctx,
1265
+ abort: composed
1266
+ };
1267
+ try {
1268
+ return {
1269
+ status: "ok",
1270
+ key,
1271
+ value: await dispatch_step(child, input, child_ctx)
1272
+ };
1273
+ } catch (err) {
1274
+ return {
1275
+ status: "err",
1276
+ key,
1277
+ err
1278
+ };
1279
+ }
1280
+ }
1281
+ /**
1282
+ * Choose which settled error (if any) `run_fn` should rethrow: a
1283
+ * `suspended_error` wins over any application error so a human-approval gate
1284
+ * inside a branch stays resumable rather than masked by a sibling's failure;
1285
+ * otherwise the first error in declared order propagates.
1286
+ */
1287
+ function pick_error(settled) {
1288
+ let first_err;
1289
+ let has_err = false;
1290
+ let suspended;
1291
+ let has_suspended = false;
1292
+ for (const s of settled) {
1293
+ if (s.status !== "err") continue;
1294
+ if (!has_err) {
1295
+ first_err = s.err;
1296
+ has_err = true;
1297
+ }
1298
+ if (!has_suspended && s.err instanceof suspended_error) {
1299
+ suspended = s.err;
1300
+ has_suspended = true;
1301
+ }
1302
+ }
1303
+ if (has_suspended) return {
1304
+ thrown: true,
1305
+ err: suspended
1306
+ };
1307
+ if (has_err) return {
1308
+ thrown: true,
1309
+ err: first_err
1310
+ };
1311
+ return {
1312
+ thrown: false,
1313
+ err: void 0
1314
+ };
1315
+ }
1316
+ /**
1178
1317
  * Build a step that runs named children concurrently on the same input.
1179
1318
  *
1180
1319
  * Returns an object keyed by child name. All children settle before any
@@ -1189,55 +1328,12 @@ function parallel(members, options) {
1189
1328
  const keys = entries.map(([k]) => k);
1190
1329
  const run_fn = async (input, ctx) => {
1191
1330
  const controllers = entries.map(() => new AbortController());
1192
- const on_parent_abort = () => {
1193
- for (const c of controllers) c.abort(ctx.abort.reason);
1194
- };
1195
- if (ctx.abort.aborted) on_parent_abort();
1196
- else ctx.abort.addEventListener("abort", on_parent_abort, { once: true });
1331
+ const on_parent_abort = install_abort_fan_out(ctx, controllers);
1197
1332
  try {
1198
- const settled = await Promise.all(entries.map(async ([key, child], idx) => {
1199
- const local = controllers[idx];
1200
- if (!local) throw new Error("parallel: missing controller");
1201
- const composed = AbortSignal.any([ctx.abort, local.signal]);
1202
- const child_ctx = {
1203
- ...ctx,
1204
- abort: composed
1205
- };
1206
- try {
1207
- return {
1208
- status: "ok",
1209
- key,
1210
- value: await dispatch_step(child, input, child_ctx)
1211
- };
1212
- } catch (err) {
1213
- return {
1214
- status: "err",
1215
- key,
1216
- err
1217
- };
1218
- }
1219
- }));
1220
- if (ctx.abort.aborted) {
1221
- const reason = ctx.abort.reason;
1222
- throw reason instanceof Error ? reason : new aborted_error("aborted", { reason });
1223
- }
1224
- let first_err;
1225
- let has_err = false;
1226
- let suspended;
1227
- let has_suspended = false;
1228
- for (const s of settled) {
1229
- if (s.status !== "err") continue;
1230
- if (!has_err) {
1231
- first_err = s.err;
1232
- has_err = true;
1233
- }
1234
- if (!has_suspended && s.err instanceof suspended_error) {
1235
- suspended = s.err;
1236
- has_suspended = true;
1237
- }
1238
- }
1239
- if (has_suspended) throw suspended;
1240
- if (has_err) throw first_err;
1333
+ const settled = await Promise.all(entries.map((entry, idx) => run_child(entry, controllers[idx], input, ctx)));
1334
+ throw_if_aborted(ctx);
1335
+ const choice = pick_error(settled);
1336
+ if (choice.thrown) throw choice.err;
1241
1337
  const out = {};
1242
1338
  for (const s of settled) if (s.status === "ok") out[s.key] = s.value;
1243
1339
  return out;
@@ -1340,11 +1436,7 @@ function map(config) {
1340
1436
  const results = Array.from({ length: list.length });
1341
1437
  const limit = concurrency === void 0 ? list.length : Math.max(1, concurrency);
1342
1438
  const controllers = [];
1343
- const on_parent_abort = () => {
1344
- for (const c of controllers) c.abort(ctx.abort.reason);
1345
- };
1346
- if (ctx.abort.aborted) on_parent_abort();
1347
- else ctx.abort.addEventListener("abort", on_parent_abort, { once: true });
1439
+ const on_parent_abort = install_abort_fan_out(ctx, controllers);
1348
1440
  let cursor = 0;
1349
1441
  let worker_error = void 0;
1350
1442
  const run_one = async (idx) => {
@@ -1378,10 +1470,7 @@ function map(config) {
1378
1470
  const workers = [];
1379
1471
  for (let w = 0; w < worker_count; w += 1) workers.push(worker());
1380
1472
  await Promise.all(workers);
1381
- if (ctx.abort.aborted) {
1382
- const reason = ctx.abort.reason;
1383
- throw reason instanceof Error ? reason : new aborted_error("aborted", { reason });
1384
- }
1473
+ throw_if_aborted(ctx);
1385
1474
  if (worker_error !== void 0) throw worker_error;
1386
1475
  return results;
1387
1476
  } finally {
@@ -1424,12 +1513,12 @@ function next_id$6() {
1424
1513
  * `sequence([...])` instead of failing obscurely at run time.
1425
1514
  */
1426
1515
  function pipe(inner, fn, options) {
1427
- if (!is_step$1(inner)) throw new TypeError(`pipe(inner, fn): inner must be a Step, got ${typeof inner}${typeof inner === "function" ? " — wrap plain functions with step(fn)" : ""}`);
1516
+ if (!is_step(inner)) throw new TypeError(`pipe(inner, fn): inner must be a Step, got ${typeof inner}${typeof inner === "function" ? " — wrap plain functions with step(fn)" : ""}`);
1428
1517
  if (typeof fn !== "function") {
1429
- if (is_step$1(fn)) throw new TypeError("pipe(inner, fn): fn must be a function, got a Step — pipe is not variadic; to chain Steps use sequence([...])");
1518
+ if (is_step(fn)) throw new TypeError("pipe(inner, fn): fn must be a function, got a Step — pipe is not variadic; to chain Steps use sequence([...])");
1430
1519
  throw new TypeError(`pipe(inner, fn): fn must be a function, got ${typeof fn}`);
1431
1520
  }
1432
- if (is_step$1(options)) throw new TypeError("pipe(inner, fn, options): got a Step as the third argument — pipe is not variadic; to chain Steps use sequence([...])");
1521
+ if (is_step(options)) throw new TypeError("pipe(inner, fn, options): got a Step as the third argument — pipe is not variadic; to chain Steps use sequence([...])");
1433
1522
  const id = next_id$6();
1434
1523
  const run_fn = async (input, ctx) => {
1435
1524
  return fn(await dispatch_step(inner, input, ctx));
@@ -1977,18 +2066,6 @@ function format_issue(issue) {
1977
2066
  * `resume_validation_error` carrying the vendor-neutral issue list.
1978
2067
  */
1979
2068
  /**
1980
- * Structurally detect a `Step` returned from `combine`.
1981
- *
1982
- * `combine` may return either a plain value or a Step to dispatch; this local
1983
- * check distinguishes the two without importing the shared helper.
1984
- */
1985
- function is_step(value) {
1986
- if (typeof value !== "object" || value === null) return false;
1987
- if (!("id" in value) || !("kind" in value) || !("run" in value)) return false;
1988
- const { id, kind, run } = value;
1989
- return typeof id === "string" && typeof kind === "string" && typeof run === "function";
1990
- }
1991
- /**
1992
2069
  * Build a human-in-the-loop pause step.
1993
2070
  *
1994
2071
  * First run fires the `on` side effect and throws `suspended_error`; a resume
@@ -2252,4 +2329,4 @@ function parse_trajectory_event(value) {
2252
2329
  //#endregion
2253
2330
  export { aborted_error as A, map as C, describe as D, sequence as E, flow_schema_default as F, resume_validation_error as M, suspended_error as N, step as O, timeout_error as P, pipe as S, parallel as T, timeout as _, parse_trajectory_event as a, compute_backoff as b, scope as c, suspend as d, format_schema_issues as f, loop as g, compose as h, is_span_start_event as i, describe_cycle_error as j, run as k, stash as l, checkpoint as m, is_emit_event as n, STEP_KINDS as o, validate_schema as p, is_span_end_event as r, is_step_kind as s, is_custom_trajectory_event as t, use as u, fallback as v, branch as w, wait_with_abort as x, retry as y };
2254
2331
 
2255
- //# sourceMappingURL=core-Ww6An4CS.js.map
2332
+ //# sourceMappingURL=core-DgH4mDbK.js.map