fascicle 0.12.11 → 0.12.12

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.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,25 @@
1
1
  # Changelog
2
2
 
3
+ ## v0.12.12 — 2026-09-25
4
+
5
+ ### Added
6
+
7
+ - **`describe.diagram(step)` draws a flow as an annotated tree.** It renders the `describe.json` tree with box-drawing glyphs, one row per node, and puts each node's description in a column beside it. A row is labelled with the node's display name, then an id its author chose, then its kind, so a counter-generated id never appears and the same flow always renders to the same bytes. That lets an app hold the diagram in its `flow.ts` header to the code with one equality test. A branch labels its arms `then` and `else`, a loop labels its guard, parallel members carry their keys, and a chain's stages nest the entries they span. `width` wraps the descriptions, and `prefix` starts every line so the output pastes straight into a doc comment.
8
+ - **Composers take a `description`.** Every core composer, every composite, chain bindings, and `model_call` accept a `description` beside `name`. It's stored as `meta.description`, so it reaches `describe.json` and the trajectory's `flow_structure`, and the diagram prints it.
9
+ - **`step(id, fn, { arm })` declares the steps its body calls.** A step whose body `ctx.call`s an arm can now name it (one step or a list) the way a chain binding already could. The arm shows up as a child in `describe`, the diagram, and `flow_structure`, and the step never runs it itself. The trailing argument's type is the new `StepOptions`.
10
+ - **The `fascicle-diagram` command prints a flow's diagram.** It ships in the package beside `fascicle-viewer`. Point it at a module whose `flow` export is the Step, or a function that builds it from stubs with no arguments, and add `"diagram": "fascicle-diagram src/diagram.ts"` to your scripts to check a header against the code whenever you want. It loads TypeScript through the project's own `tsx` and takes `--export`, `--width`, and `--prefix`. It exits 0 when it prints, 1 when the module won't load or holds no Step, and 2 on a usage error.
11
+ - **`FlowNode` marks a generated id.** `describe.json` sets `anonymous: true` on a node whose id was generated rather than chosen, which is what the diagram reads to keep counters out.
12
+
13
+ ### Changed
14
+
15
+ - **A `model_call` without an `id` is anonymous, like `step(fn)`.** Its generated id carries a process-wide counter, so the diagram labels it by kind rather than printing a number that depends on build order. As a result, `checkpoint` and `gate` now reject an id-less `model_call` the way they reject an anonymous step, so give the call an `id` to wrap it.
16
+ - **`describe()` prints a branch's arms once.** Its text tree listed `then` and `otherwise` as config lines and again as children. Each arm now renders once, under its key.
17
+
18
+ ### Internal
19
+
20
+ - Release workflows survive a tag push that GitHub delivers twice. Both take a per-ref concurrency group, `release.yaml` exits cleanly when the release already exists, and `publish.yaml` skips the publish job before the approval gate when npm already has the version.
21
+ - Blueprint rule 3 now has the flow draw its own header diagram, with a test holding the header to `describe.diagram` and a `diagram` script for looking at it. Rule 6 covers declaring the arms that a direct-style step calls.
22
+
3
23
  ## v0.12.11 — 2026-09-25
4
24
 
5
25
  ### Added
@@ -1,4 +1,4 @@
1
- import { d as TrajectoryLogger, n as CheckpointStore } from "./types-DBpU27sQ.js";
1
+ import { m as TrajectoryLogger, n as CheckpointStore } from "./types-BasW4Wwb.js";
2
2
 
3
3
  //#region src/adapters/filesystem_logger.d.ts
4
4
  type FilesystemLoggerConfig = {
package/dist/agents.d.ts CHANGED
@@ -1,6 +1,6 @@
1
- import { a as Step } from "./types-DBpU27sQ.js";
1
+ import { s as Step } from "./types-BasW4Wwb.js";
2
2
  import { r as ToolSchema } from "./types-BK0UW28o.js";
3
- import { a as Engine, i as EffortLevel } from "./types-DcNpT0Hl.js";
3
+ import { a as Engine, i as EffortLevel } from "./types-bEpfDrys.js";
4
4
 
5
5
  //#region src/agents/define_agent.d.ts
6
6
  type AgentBuiltPrompt = string | {
package/dist/agents.js CHANGED
@@ -1,4 +1,4 @@
1
- import { S as assert_valid_step_id, k as aborted_error, x as step } from "./core-BClsJ3h0.js";
1
+ import { O as aborted_error, S as assert_valid_step_id, x as step } from "./core-BVCVUMmH.js";
2
2
  import { readFileSync } from "node:fs";
3
3
  import { fileURLToPath } from "node:url";
4
4
  //#region src/agents/define_agent.ts
@@ -0,0 +1,9 @@
1
+ #!/usr/bin/env node
2
+ import { pathToFileURL } from 'node:url';
3
+ import { dirname, resolve } from 'node:path';
4
+ import { fileURLToPath } from 'node:url';
5
+
6
+ const here = dirname(fileURLToPath(import.meta.url));
7
+ const dist_bin = resolve(here, '..', 'diagram_bin.js');
8
+ const mod = await import(pathToFileURL(dist_bin).href);
9
+ await mod.run_diagram_bin(process.argv.slice(2));
@@ -70,6 +70,248 @@ async function run_one(fn, trajectory) {
70
70
  }
71
71
  }
72
72
  //#endregion
73
+ //#region src/core/display_name.ts
74
+ /**
75
+ * Resolve the human-readable label for `node`, falling back to `fallback`
76
+ * (typically the step's kind) when neither display channel is populated.
77
+ * It reads only `config` and `meta`, so a `describe.json` node resolves the
78
+ * same way as the step it was drawn from.
79
+ */
80
+ function resolve_display_name(node, fallback) {
81
+ const display = node.config?.["display_name"];
82
+ if (typeof display === "string" && display.length > 0) return display;
83
+ const name = node.meta?.name;
84
+ if (typeof name === "string" && name.length > 0) return name;
85
+ return fallback;
86
+ }
87
+ /**
88
+ * The `meta` a composer spreads into the step it returns for its
89
+ * `description` option: `meta.description` when one is given, and nothing
90
+ * otherwise, so a composer without a description carries no empty `meta`
91
+ * for `describe` to echo.
92
+ */
93
+ function description_meta(description) {
94
+ return description === void 0 ? {} : { meta: { description } };
95
+ }
96
+ //#endregion
97
+ //#region src/core/step_kinds.ts
98
+ /**
99
+ * Closed registry of every `Step.kind` produced by the composition layer.
100
+ *
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
103
+ * 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.
107
+ */
108
+ const STEP_KINDS = [
109
+ "step",
110
+ "sequence",
111
+ "parallel",
112
+ "branch",
113
+ "map",
114
+ "pipe",
115
+ "retry",
116
+ "fallback",
117
+ "timeout",
118
+ "loop",
119
+ "compose",
120
+ "adversarial",
121
+ "ensemble",
122
+ "tournament",
123
+ "consensus",
124
+ "checkpoint",
125
+ "suspend",
126
+ "scope",
127
+ "stash",
128
+ "use",
129
+ "chain"
130
+ ];
131
+ /**
132
+ * Check whether a value is one of the registered `Step.kind` strings.
133
+ */
134
+ function is_step_kind(value) {
135
+ return typeof value === "string" && STEP_KINDS.includes(value);
136
+ }
137
+ //#endregion
138
+ //#region src/core/diagram.ts
139
+ /**
140
+ * The renderer behind `describe.diagram(step)`: a flow drawn as an annotated
141
+ * box-drawing tree.
142
+ *
143
+ * It reads only the `FlowNode` tree that `describe.json` produces, so the same
144
+ * flow renders to the same bytes wherever it is built, and an app can hold the
145
+ * diagram in its `flow.ts` header to the code with one equality test.
146
+ *
147
+ * Each node gets one row. A row is labelled with the node's display name, then
148
+ * an id the author chose, then its kind. A counter-generated id never appears,
149
+ * because its number depends on what else the process built first. Roles come
150
+ * from the parent's kind (a branch's `then` and `else`, a loop's `guard`, a
151
+ * parallel member's key, a chain's stages), never from a config dump.
152
+ * Descriptions share one column after the widest row. A composer's description
153
+ * follows its kind (`branch: ...`), and a node without one shows its kind.
154
+ */
155
+ const CHOSEN_ID_KINDS = /* @__PURE__ */ new Set(["step", "suspend"]);
156
+ const BRANCH_ROLES = ["then", "else"];
157
+ const STAGE_PREFIX = "stage:";
158
+ const COLUMN_GAP = 2;
159
+ /**
160
+ * Draw a `FlowNode` tree as rows of box-drawing glyphs, labels, and aligned
161
+ * descriptions, joined with newlines and free of trailing whitespace.
162
+ */
163
+ function render_diagram(root, options) {
164
+ const rows = [];
165
+ flatten(to_item(root, void 0), "", "", rows);
166
+ const column = Math.max(...rows.map((row) => row.lead.length + row.head.length)) + COLUMN_GAP;
167
+ const prefix = options?.prefix ?? "";
168
+ const limit = options?.width === void 0 ? Number.POSITIVE_INFINITY : options.width - prefix.length - column;
169
+ return rows.flatMap((row) => {
170
+ const [first, ...rest] = wrap(row.note, limit);
171
+ const head = `${row.lead}${row.head}`;
172
+ return [first === void 0 ? head : `${head.padEnd(column)}${first}`, ...rest.map((line) => `${row.wrap_lead.padEnd(column)}${line}`)];
173
+ }).map((line) => `${prefix}${line}`).join("\n");
174
+ }
175
+ /**
176
+ * Append `item` and its subtree to `rows` in reading order.
177
+ *
178
+ * `indent` is the glyph run this item's children are drawn after. A wrapped
179
+ * description line reuses it, plus a bar when children follow, so the
180
+ * vertical lines stay unbroken through the wrap.
181
+ */
182
+ function flatten(item, lead, indent, rows) {
183
+ const has_children = item.children.length > 0;
184
+ rows.push({
185
+ lead,
186
+ head: item.head,
187
+ note: item.note,
188
+ wrap_lead: has_children ? `${indent}│` : indent
189
+ });
190
+ item.children.forEach((child, index) => {
191
+ const last = index === item.children.length - 1;
192
+ flatten(child, `${indent}${last ? "└─ " : "├─ "}`, `${indent}${last ? " " : "│ "}`, rows);
193
+ });
194
+ }
195
+ /**
196
+ * Break a description's words into lines no longer than `limit`. A word
197
+ * longer than `limit` gets a line to itself rather than being split.
198
+ */
199
+ function wrap(words, limit) {
200
+ const lines = [];
201
+ let current = "";
202
+ for (const word of words) if (current === "") current = word;
203
+ else if (current.length + 1 + word.length <= limit) current = `${current} ${word}`;
204
+ else {
205
+ lines.push(current);
206
+ current = word;
207
+ }
208
+ if (current !== "") lines.push(current);
209
+ return lines;
210
+ }
211
+ /**
212
+ * Convert one node into the item the layout draws. `role` is the name the
213
+ * parent gives this child, and it is dropped when it only repeats the label.
214
+ */
215
+ function to_item(node, role) {
216
+ const { label, by_kind } = label_of(node);
217
+ return {
218
+ head: role === void 0 || role === label ? label : `${role} ${label}`,
219
+ note: note_of(node, by_kind),
220
+ children: child_items(node)
221
+ };
222
+ }
223
+ /**
224
+ * Pick a node's label: its display name, else an id its author chose, else
225
+ * its kind. `by_kind` reports the last case, where the kind already shows.
226
+ */
227
+ function label_of(node) {
228
+ const display = resolve_display_name(node, "");
229
+ if (display !== "") return {
230
+ label: display,
231
+ by_kind: false
232
+ };
233
+ if (has_chosen_id(node)) return {
234
+ label: node.id,
235
+ by_kind: false
236
+ };
237
+ return {
238
+ label: node.kind,
239
+ by_kind: true
240
+ };
241
+ }
242
+ /**
243
+ * True when a node's id was chosen by its author. Anonymous steps, cycle
244
+ * markers, and every built-in composer carry generated ids. A kind outside
245
+ * the built-in set belongs to a hand-built step, whose id is its author's.
246
+ */
247
+ function has_chosen_id(node) {
248
+ if (node.anonymous === true || node.kind === "<cycle>") return false;
249
+ return !is_step_kind(node.kind) || CHOSEN_ID_KINDS.has(node.kind);
250
+ }
251
+ /**
252
+ * The words of a row's description column.
253
+ *
254
+ * A row labelled by its kind shows only the description. A plain step shows
255
+ * its description, or `step` without one. Any other node shows its kind, then
256
+ * the description after a colon. Whitespace in a description collapses, so a
257
+ * multi-line string still draws as one wrapped column.
258
+ */
259
+ function note_of(node, by_kind) {
260
+ const words = (node.meta?.description ?? "").split(/\s+/).filter((word) => word !== "");
261
+ if (by_kind) return words;
262
+ if (node.kind === "step") return words.length > 0 ? words : ["step"];
263
+ return words.length > 0 ? [`${node.kind}:`, ...words] : [node.kind];
264
+ }
265
+ /**
266
+ * Convert a node's children, naming each by the role its parent's kind gives
267
+ * it.
268
+ */
269
+ function child_items(node) {
270
+ const children = node.children ?? [];
271
+ if (node.kind === "branch") return children.map((child, i) => to_item(child, BRANCH_ROLES[i]));
272
+ if (node.kind === "loop") return children.map((child, i) => to_item(child, i === 1 ? "guard" : void 0));
273
+ if (node.kind === "parallel") {
274
+ const keys = string_list(node.config?.["keys"]);
275
+ return children.map((child, i) => to_item(child, keys[i]));
276
+ }
277
+ if (node.kind === "chain") return staged_items(children, string_list(node.config?.["plan"]));
278
+ return children.map((child) => to_item(child, void 0));
279
+ }
280
+ /**
281
+ * Convert a chain's children in plan order, nesting the entries after each
282
+ * `.stage(name)` under a row for that stage, which is how the stage's span
283
+ * encloses them in the trajectory. Children the plan does not account for
284
+ * follow in order, so a node without a plan still draws every child.
285
+ */
286
+ function staged_items(children, plan) {
287
+ const top = [];
288
+ let target = top;
289
+ let next = 0;
290
+ for (const entry of plan) if (entry.startsWith(STAGE_PREFIX)) {
291
+ const members = [];
292
+ top.push({
293
+ head: `stage ${entry.slice(6)}`,
294
+ note: [],
295
+ children: members
296
+ });
297
+ target = members;
298
+ } else {
299
+ const child = children[next];
300
+ next += 1;
301
+ if (child !== void 0) target.push(to_item(child, void 0));
302
+ }
303
+ for (const child of children.slice(next)) target.push(to_item(child, void 0));
304
+ return top;
305
+ }
306
+ /**
307
+ * Read a config value as a list of strings, as `parallel` records its keys
308
+ * and `chain` its plan. Anything else reads as an empty list.
309
+ */
310
+ function string_list(value) {
311
+ if (!Array.isArray(value)) return [];
312
+ return value.filter((entry) => typeof entry === "string");
313
+ }
314
+ //#endregion
73
315
  //#region src/core/errors.ts
74
316
  var timeout_error = class extends Error {
75
317
  kind = "timeout_error";
@@ -166,32 +408,25 @@ function is_step(value) {
166
408
  return typeof id === "string" && typeof kind === "string" && typeof run === "function";
167
409
  }
168
410
  //#endregion
169
- //#region src/core/display_name.ts
170
- /**
171
- * Resolve the human-readable label for `node`, falling back to `fallback`
172
- * (typically the step's kind) when neither display channel is populated.
173
- */
174
- function resolve_display_name(node, fallback) {
175
- const display = node.config?.["display_name"];
176
- if (typeof display === "string" && display.length > 0) return display;
177
- const name = node.meta?.name;
178
- if (typeof name === "string" && name.length > 0) return name;
179
- return fallback;
180
- }
181
- //#endregion
182
411
  //#region src/core/describe.ts
183
412
  /**
184
- * describe(step) and describe.json(step): composition introspection.
413
+ * describe(step), describe.json(step), and describe.diagram(step):
414
+ * composition introspection.
185
415
  *
186
416
  * `describe(step)` is the text-tree renderer. Multi-line string with
187
417
  * hierarchical indentation. Function values render as `<fn>` (or
188
418
  * `<fn:name>` when the function has a non-empty `name`); zod schemas
189
- * render as `<schema>`.
419
+ * render as `<schema>`. A config entry that holds one of the node's own
420
+ * children (a branch's `then` and `otherwise`) renders that child once, in
421
+ * place of the config line, rather than again among the children.
190
422
  *
191
423
  * `describe.json(step)` returns a `FlowNode` tree (kind, id, config, children)
192
424
  * for tooling (Studio UI, Mermaid renderers, diff tools). Function values
193
425
  * serialize as `{ kind: '<fn>', name? }` and schemas as `{ kind: '<schema>' }`.
194
426
  *
427
+ * `describe.diagram(step)` draws the `describe.json` tree as an annotated
428
+ * box-drawing diagram (see diagram.ts).
429
+ *
195
430
  * Both forms detect cycles. Under the default (loose) mode, back-references
196
431
  * render as `<cycle>(id)` in text and `{ kind: '<cycle>', id }` in JSON. Under
197
432
  * `{ strict: true }`, cycles throw `describe_cycle_error`.
@@ -214,32 +449,52 @@ function describe_json(root, options) {
214
449
  return render_json(root, /* @__PURE__ */ new Set(), strict);
215
450
  }
216
451
  /**
452
+ * Render a step tree as an annotated box-drawing diagram. It is drawn from
453
+ * the `describe.json` tree, so the output depends on the flow's shape alone.
454
+ */
455
+ function describe_diagram(root, options) {
456
+ return render_diagram(describe_json(root, options), options);
457
+ }
458
+ /**
217
459
  * Public entry point: `describe(step)` for text, `describe.json(step)` for
218
- * the `FlowNode` tree.
460
+ * the `FlowNode` tree, `describe.diagram(step)` for the annotated diagram.
219
461
  */
220
- const describe = Object.assign(describe_text, { json: describe_json });
462
+ const describe = Object.assign(describe_text, {
463
+ json: describe_json,
464
+ diagram: describe_diagram
465
+ });
221
466
  /**
222
467
  * Append one node (label line, config lines, then children) to `lines`.
223
468
  *
469
+ * `role` prefixes the label line when a parent's config entry names this
470
+ * node. A config entry whose value is one of the node's own children renders
471
+ * that child's whole subtree in its place, under the entry's key, and the
472
+ * child is then skipped among the children so it appears once.
473
+ *
224
474
  * `path` holds the steps on the current root-to-node path for cycle
225
475
  * detection; membership is added before recursing and removed in a `finally`
226
476
  * so shared (diamond) references are not misreported as cycles.
227
477
  */
228
- function render_text(node, depth, lines, path, strict) {
478
+ function render_text(node, depth, lines, path, strict, role = "") {
229
479
  const prefix = INDENT.repeat(depth);
230
480
  if (path.has(node)) {
231
481
  if (strict) throw new describe_cycle_error(node.id);
232
- lines.push(`${prefix}<cycle>(${node.id})`);
482
+ lines.push(`${prefix}${role}<cycle>(${node.id})`);
233
483
  return;
234
484
  }
235
485
  path.add(node);
236
486
  try {
237
- lines.push(`${prefix}${resolve_display_name(node, node.kind)}(${node.id})`);
238
- if (node.config) for (const [key, value] of Object.entries(node.config)) {
487
+ lines.push(`${prefix}${role}${resolve_display_name(node, node.kind)}(${node.id})`);
488
+ const children = node.children ?? [];
489
+ const placed = /* @__PURE__ */ new Set();
490
+ for (const [key, value] of Object.entries(node.config ?? {})) {
239
491
  if (key === "display_name") continue;
240
- lines.push(`${prefix}${INDENT}${key}: ${render_value_text(value, path, strict)}`);
492
+ if (is_step(value) && children.includes(value)) {
493
+ placed.add(value);
494
+ render_text(value, depth + 1, lines, path, strict, `${key}: `);
495
+ } else lines.push(`${prefix}${INDENT}${key}: ${render_value_text(value, path, strict)}`);
241
496
  }
242
- if (node.children && node.children.length > 0) for (const child of node.children) render_text(child, depth + 1, lines, path, strict);
497
+ for (const child of children) if (!placed.has(child)) render_text(child, depth + 1, lines, path, strict);
243
498
  } finally {
244
499
  path.delete(node);
245
500
  }
@@ -327,6 +582,7 @@ function render_json(node, path, strict) {
327
582
  }
328
583
  if (node.children && node.children.length > 0) result.children = node.children.map((child) => render_json(child, path, strict));
329
584
  if (node.meta) result.meta = node.meta;
585
+ if (node.anonymous === true) result.anonymous = true;
330
586
  return result;
331
587
  } finally {
332
588
  path.delete(node);
@@ -1013,12 +1269,13 @@ function assert_valid_step_id(id, subject, remedy) {
1013
1269
  * step() factory.
1014
1270
  *
1015
1271
  * Three forms:
1016
- * step(id, fn): named step. id is rendered in trajectory spans and describe().
1017
- * step(id, fn, meta): named step carrying descriptive metadata. `meta.name` is the
1018
- * display channel: it labels the step's trajectory span and its
1019
- * describe() line, leaving the id free to stay a stable
1020
- * identifier. Nothing keys off it, so it is safe to reword.
1021
- * step(fn): anonymous step. id is `step_<counter>`; cannot be checkpointed.
1272
+ * step(id, fn): named step. id is rendered in trajectory spans and describe().
1273
+ * step(id, fn, options): named step carrying descriptive metadata. `name` is the
1274
+ * display channel: it labels the step's trajectory span and
1275
+ * its describe() line, leaving the id free to stay a stable
1276
+ * identifier. Nothing keys off it, so it is safe to reword.
1277
+ * `arm` declares the steps the body invokes via `ctx.call`.
1278
+ * step(fn): anonymous step. id is `step_<counter>`; cannot be checkpointed.
1022
1279
  *
1023
1280
  * Anonymous steps carry an internal `anonymous: true` flag so checkpoint can
1024
1281
  * reject them synchronously at flow construction time.
@@ -1035,7 +1292,13 @@ function next_step_id() {
1035
1292
  step_counter += 1;
1036
1293
  return `step_${step_counter}`;
1037
1294
  }
1038
- function step(id_or_fn, maybe_fn, meta) {
1295
+ /**
1296
+ * Normalize a declared arm (one step or several) to the children list.
1297
+ */
1298
+ function arm_children(arm) {
1299
+ return is_step(arm) ? [arm] : arm;
1300
+ }
1301
+ function step(id_or_fn, maybe_fn, options) {
1039
1302
  if (typeof id_or_fn === "function") return {
1040
1303
  id: next_step_id(),
1041
1304
  kind: "step",
@@ -1044,16 +1307,13 @@ function step(id_or_fn, maybe_fn, meta) {
1044
1307
  };
1045
1308
  if (typeof maybe_fn !== "function") throw new TypeError("step(id, fn): fn must be a function");
1046
1309
  assert_valid_step_id(id_or_fn, "step id", "put the label in meta.name");
1047
- if (meta) return {
1048
- id: id_or_fn,
1049
- kind: "step",
1050
- run: maybe_fn,
1051
- meta
1052
- };
1310
+ const { arm, ...meta } = options ?? {};
1053
1311
  return {
1054
1312
  id: id_or_fn,
1055
1313
  kind: "step",
1056
- run: maybe_fn
1314
+ run: maybe_fn,
1315
+ ...Object.keys(meta).length > 0 ? { meta } : {},
1316
+ ...arm === void 0 ? {} : { children: arm_children(arm) }
1057
1317
  };
1058
1318
  }
1059
1319
  register_traced_kind("step");
@@ -1107,6 +1367,7 @@ function sequence(children, options) {
1107
1367
  kind: "sequence",
1108
1368
  children: children_ref,
1109
1369
  ...config_meta ? { config: config_meta } : {},
1370
+ ...description_meta(options?.description),
1110
1371
  run: run_fn
1111
1372
  };
1112
1373
  }
@@ -1236,6 +1497,7 @@ function parallel(members, options) {
1236
1497
  kind: "parallel",
1237
1498
  children: child_list,
1238
1499
  config: config_meta,
1500
+ ...description_meta(options?.description),
1239
1501
  run: run_fn
1240
1502
  };
1241
1503
  }
@@ -1281,6 +1543,7 @@ function branch(config) {
1281
1543
  kind: "branch",
1282
1544
  children: [then_step, otherwise_step],
1283
1545
  config: config_meta,
1546
+ ...description_meta(config.description),
1284
1547
  run: run_fn
1285
1548
  };
1286
1549
  }
@@ -1373,6 +1636,7 @@ function map(config) {
1373
1636
  kind: "map",
1374
1637
  children: [per_item],
1375
1638
  config: config_meta,
1639
+ ...description_meta(config.description),
1376
1640
  run: run_fn
1377
1641
  };
1378
1642
  }
@@ -1418,6 +1682,7 @@ function pipe(inner, fn, options) {
1418
1682
  kind: "pipe",
1419
1683
  children: [inner],
1420
1684
  config: config_meta,
1685
+ ...description_meta(options?.description),
1421
1686
  run: run_fn
1422
1687
  };
1423
1688
  }
@@ -1594,6 +1859,7 @@ function retry(inner, config) {
1594
1859
  kind: "retry",
1595
1860
  children: [inner],
1596
1861
  config: config_meta,
1862
+ ...description_meta(config.description),
1597
1863
  run: run_fn
1598
1864
  };
1599
1865
  }
@@ -1679,6 +1945,7 @@ function fallback(primary, backup, options) {
1679
1945
  kind: "fallback",
1680
1946
  children: [primary, backup],
1681
1947
  ...Object.keys(config_meta).length > 0 ? { config: config_meta } : {},
1948
+ ...description_meta(options?.description),
1682
1949
  run: run_fn
1683
1950
  };
1684
1951
  }
@@ -1756,6 +2023,7 @@ function timeout(inner, ms, options) {
1756
2023
  kind: "timeout",
1757
2024
  children: [inner],
1758
2025
  config: config_meta,
2026
+ ...description_meta(options?.description),
1759
2027
  run: run_fn
1760
2028
  };
1761
2029
  }
@@ -1805,14 +2073,19 @@ function next_id$2() {
1805
2073
  * (with an id derived from the loop's, so trees with several loops stay
1806
2074
  * unambiguous) rather than special-cased in the run loop: the predicate form
1807
2075
  * then dispatches, traces, and terminates identically to a hand-written guard.
2076
+ * The wrapper is marked anonymous because its id carries the loop's counter,
2077
+ * which `describe.diagram` must never print.
1808
2078
  */
1809
2079
  function wrap_guard(guard, loop_id) {
1810
2080
  if (guard === void 0) return void 0;
1811
2081
  if (typeof guard !== "function") return guard;
1812
- return step(`${loop_id}_guard`, async (state) => ({
1813
- stop: await guard(state),
1814
- state
1815
- }));
2082
+ return {
2083
+ ...step(`${loop_id}_guard`, async (state) => ({
2084
+ stop: await guard(state),
2085
+ state
2086
+ })),
2087
+ anonymous: true
2088
+ };
1816
2089
  }
1817
2090
  /**
1818
2091
  * Build a bounded iteration step with carry-state.
@@ -1858,6 +2131,7 @@ function loop(config) {
1858
2131
  kind: "loop",
1859
2132
  children: guard ? [body, guard] : [body],
1860
2133
  config: config_meta,
2134
+ ...description_meta(config.description),
1861
2135
  run: run_fn
1862
2136
  };
1863
2137
  }
@@ -1907,6 +2181,7 @@ function compose(inner, config) {
1907
2181
  kind: "compose",
1908
2182
  children: [inner],
1909
2183
  config: { display_name: name },
2184
+ ...description_meta(config.description),
1910
2185
  run: run_fn
1911
2186
  };
1912
2187
  }
@@ -1989,6 +2264,7 @@ function checkpoint(inner, config) {
1989
2264
  kind: "checkpoint",
1990
2265
  children: [inner],
1991
2266
  config: config_meta,
2267
+ ...description_meta(config.description),
1992
2268
  run: run_fn
1993
2269
  };
1994
2270
  }
@@ -2101,6 +2377,7 @@ function suspend(config) {
2101
2377
  id: suspend_id,
2102
2378
  kind: "suspend",
2103
2379
  config: config_meta,
2380
+ ...description_meta(config.description),
2104
2381
  run: run_fn
2105
2382
  };
2106
2383
  }
@@ -2184,6 +2461,7 @@ function scope(children, options) {
2184
2461
  kind: "scope",
2185
2462
  children,
2186
2463
  ...config_meta ? { config: config_meta } : {},
2464
+ ...description_meta(options?.description),
2187
2465
  run: run_fn
2188
2466
  };
2189
2467
  }
@@ -2208,6 +2486,7 @@ function stash(key, source, options) {
2208
2486
  kind: "stash",
2209
2487
  children: [source],
2210
2488
  config: config_meta,
2489
+ ...description_meta(options?.description),
2211
2490
  run: run_fn
2212
2491
  };
2213
2492
  }
@@ -2231,6 +2510,7 @@ function use(keys, fn, options) {
2231
2510
  id,
2232
2511
  kind: "use",
2233
2512
  config: config_meta,
2513
+ ...description_meta(options?.description),
2234
2514
  run: run_fn
2235
2515
  };
2236
2516
  }
@@ -2348,41 +2628,28 @@ function build_chain(input_name, entries, output_node) {
2348
2628
  };
2349
2629
  }
2350
2630
  /**
2351
- * Project a binding's options onto `step`'s trailing metadata argument.
2352
- *
2353
- * Returned as a spreadable tuple so a binding with no label calls `step`
2354
- * with two arguments, leaving `meta` genuinely absent rather than set to an
2355
- * empty object that `describe` would then echo.
2356
- */
2357
- function binding_meta(options) {
2358
- return options?.name === void 0 ? [] : [{ name: options.name }];
2359
- }
2360
- /**
2361
2631
  * Build the binding node for the arm-first `.step(name, arm, select)` form.
2362
2632
  *
2363
2633
  * The chain owns the dispatch: the synthesized body projects the record
2364
2634
  * through `select` and hands the result to the arm via `ctx.call`, and the
2365
- * same arm is recorded as the binding's child, so the subtree `describe`
2635
+ * same arm is declared as the binding's arm, so the subtree `describe`
2366
2636
  * renders and the step that runs are one value by construction.
2367
2637
  */
2368
2638
  function arm_node(name, arm, select, options) {
2369
2639
  if (typeof select !== "function") throw new TypeError("chain.step(name, arm, select): select must be a function");
2370
- return {
2371
- ...step(name, (s, ctx) => ctx.call(arm, select(s)), ...binding_meta(options)),
2372
- children: [arm]
2373
- };
2640
+ return step(name, (s, ctx) => ctx.call(arm, select(s)), {
2641
+ ...options,
2642
+ arm
2643
+ });
2374
2644
  }
2375
2645
  /**
2376
2646
  * Build the binding node for the body form `.step(name, fn, { arm? })`.
2647
+ *
2648
+ * A declared arm is describe metadata only: `step` records it as the
2649
+ * binding's child, and the body's own `ctx.call` is what runs it.
2377
2650
  */
2378
2651
  function body_node(name, fn, options) {
2379
- const settings = typeof options === "function" ? void 0 : options;
2380
- const base = step(name, fn, ...binding_meta(settings));
2381
- const arm = settings?.arm;
2382
- return arm === void 0 ? base : {
2383
- ...base,
2384
- children: [arm]
2385
- };
2652
+ return step(name, fn, typeof options === "function" ? void 0 : options);
2386
2653
  }
2387
2654
  /**
2388
2655
  * Internal untyped builder behind `chain`.
@@ -2449,6 +2716,6 @@ register_traced_kind("chain");
2449
2716
  * and surface through the umbrella package.
2450
2717
  */
2451
2718
  //#endregion
2452
- export { describe_cycle_error as A, is_valid_step_id as C, resolve_display_name as D, describe as E, resume_validation_error as M, suspended_error as N, is_step as O, timeout_error 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, 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 };
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 };
2453
2720
 
2454
- //# sourceMappingURL=core-BClsJ3h0.js.map
2721
+ //# sourceMappingURL=core-BVCVUMmH.js.map