fascicle 0.13.0 → 0.13.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,12 @@
1
1
  # Changelog
2
2
 
3
+ ## v0.13.1 — 2026-10-09
4
+
5
+ ### Added
6
+
7
+ - **`describe.replays(step)` names the steps a resume would pay for twice, before anything runs.** A run that resumes at a `suspend` replays the flow from its input, so a step marked `side_effect` (every `model_call` is) that can run before the gate runs again, unless a `checkpoint` that holds the step and not the gate stored its result. It reads the `describe.json` tree and returns a `ReplayHint` (`{ id, label, gates }`) for each such step, so a test can hold a flow to an empty list, and on `examples/durable-runs` it names the same step that the run's `step_replayed` event reports. Inside a `sequence`, a `chain`, a `fallback`, or one round of a `loop` the children run in order, `parallel` members and a step's arms can start in either order, and the arms of a `branch` never run against each other. A model call that a step's body makes without declaring it as an `arm` is out of its sight.
8
+ - **`describe.diagram` and `fascicle-diagram` can mark those steps.** Pass `replays: true` to `describe.diagram`, or `--replays` to the bin, and each of those rows ends with the gates it runs before, as in `(replays before approve)`. Without the option the diagram is unchanged byte for byte.
9
+
3
10
  ## v0.13.0 — 2026-10-09
4
11
 
5
12
  ### Added
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-B-M7nAkg.js";
1
+ import { S as assert_valid_step_id, k as aborted_error, x as step } from "./core-DK7g1Z40.js";
2
2
  import { readFileSync } from "node:fs";
3
3
  import { fileURLToPath } from "node:url";
4
4
  //#region src/agents/define_agent.ts
@@ -135,6 +135,154 @@ function is_step_kind(value) {
135
135
  return typeof value === "string" && STEP_KINDS.includes(value);
136
136
  }
137
137
  //#endregion
138
+ //#region src/core/node_label.ts
139
+ /**
140
+ * What a flow node is called: its display name, an id its author chose, or
141
+ * its kind, in that order. `describe.diagram` labels its rows this way, and
142
+ * `describe.replays` names the steps it finds the same way.
143
+ *
144
+ * A counter-generated id never serves as a label, because its number depends
145
+ * on what else the process built first.
146
+ */
147
+ const CHOSEN_ID_KINDS = /* @__PURE__ */ new Set(["step", "suspend"]);
148
+ /**
149
+ * Pick a node's label: its display name, else an id its author chose, else
150
+ * its kind. `by_kind` reports the last case, where the kind already shows.
151
+ */
152
+ function label_of(node) {
153
+ const display = resolve_display_name(node, "");
154
+ if (display !== "") return {
155
+ label: display,
156
+ by_kind: false
157
+ };
158
+ if (has_chosen_id(node)) return {
159
+ label: node.id,
160
+ by_kind: false
161
+ };
162
+ return {
163
+ label: node.kind,
164
+ by_kind: true
165
+ };
166
+ }
167
+ /**
168
+ * True when a node's id was chosen by its author. Anonymous steps, cycle
169
+ * markers, and every built-in composer carry generated ids. A kind outside
170
+ * the built-in set belongs to a hand-built step, whose id is its author's.
171
+ */
172
+ function has_chosen_id(node) {
173
+ if (node.anonymous === true || node.kind === "<cycle>") return false;
174
+ return !is_step_kind(node.kind) || CHOSEN_ID_KINDS.has(node.kind);
175
+ }
176
+ //#endregion
177
+ //#region src/core/replays.ts
178
+ /**
179
+ * The analysis behind `describe.replays(step)`: which steps marked
180
+ * `side_effect` a resumed run can run again before it reaches a gate.
181
+ *
182
+ * A run that resumes at a `suspend` replays the flow from its input, so a step
183
+ * that ran before the gate runs again, unless a `checkpoint` stored its
184
+ * result. The runtime reports each one as a `step_replayed` event once it has
185
+ * happened. This finds them from the flow's shape alone, before anything runs,
186
+ * so an app can hold its flow to having none in a test.
187
+ *
188
+ * It reads only the `FlowNode` tree that `describe.json` produces. A marked
189
+ * step can replay at a gate when it can start before the gate in one pass and
190
+ * no checkpoint stores its result first. Where the two paths split decides
191
+ * which comes first:
192
+ *
193
+ * - `parallel` members start together, and a step's arms run in whatever
194
+ * order its body calls them, so either one can.
195
+ * - The arms of a `branch` exclude each other within a pass, so neither does.
196
+ * - Anything else runs its children in order: a `sequence`, a `chain`'s plan,
197
+ * a `fallback`'s primary before its backup, a `loop`'s body before its guard
198
+ * within a round, and a kind this module doesn't know.
199
+ * - A step that holds the gate starts before it.
200
+ *
201
+ * A checkpoint protects a step from a gate when it holds the step and not the
202
+ * gate. One around both stores its result only after the gate resumes.
203
+ *
204
+ * What the tree can't show, this can't see: a model call that a step's body
205
+ * makes without declaring it as an arm, a step that a `suspend`'s `combine`
206
+ * hands back, and a gate that a loop reaches only in a later round.
207
+ */
208
+ /**
209
+ * Append `node` and every node under it to `out`, in reading order.
210
+ */
211
+ function walk(node, trail, out) {
212
+ out.push({
213
+ node,
214
+ trail
215
+ });
216
+ for (const [index, child] of (node.children ?? []).entries()) walk(child, [...trail, {
217
+ node,
218
+ index
219
+ }], out);
220
+ }
221
+ /**
222
+ * True when, under a node of `kind`, the child at `first` can start before
223
+ * the child at `second` within one pass.
224
+ */
225
+ function comes_first(kind, first, second) {
226
+ if (kind === "branch") return false;
227
+ if (kind === "parallel" || kind === "step") return true;
228
+ return first < second;
229
+ }
230
+ /**
231
+ * How many turns two trails share before they part, which is the depth of
232
+ * the node where their paths split. A trail that runs out first is shared
233
+ * whole.
234
+ */
235
+ function shared_depth(a, b) {
236
+ const parted = a.findIndex((turn, i) => turn.index !== b[i]?.index);
237
+ return parted === -1 ? a.length : parted;
238
+ }
239
+ /**
240
+ * True when the marked step at `s` can run before the gate at `g` with no
241
+ * checkpoint between them that holds the step and not the gate.
242
+ */
243
+ function runs_before(s, g) {
244
+ const depth = shared_depth(s.trail, g.trail);
245
+ const split_s = s.trail[depth];
246
+ const split_g = g.trail[depth];
247
+ if (split_g === void 0) return false;
248
+ if (split_s === void 0) return true;
249
+ if (!comes_first(split_s.node.kind, split_s.index, split_g.index)) return false;
250
+ return !s.trail.slice(depth + 1).some(({ node }) => node.kind === "checkpoint");
251
+ }
252
+ /**
253
+ * The gates each marked node can run before, by node, for every marked node
254
+ * that has any. A gate that appears twice in the tree is listed once.
255
+ */
256
+ function replay_gates(root) {
257
+ const visits = [];
258
+ walk(root, [], visits);
259
+ const gates = visits.filter(({ node }) => node.kind === "suspend");
260
+ const found = /* @__PURE__ */ new Map();
261
+ for (const visit of visits) {
262
+ if (visit.node.meta?.side_effect !== true) continue;
263
+ const ids = [...new Set(gates.filter((gate) => runs_before(visit, gate)).map(({ node }) => node.id))];
264
+ if (ids.length > 0) found.set(visit.node, ids);
265
+ }
266
+ return found;
267
+ }
268
+ /**
269
+ * Every step marked `side_effect` that a resumed run can run again before one
270
+ * of the flow's gates, in flow order. A step that appears twice in the tree
271
+ * gets one hint, with the gates of both places.
272
+ */
273
+ function find_replays(root) {
274
+ const by_id = /* @__PURE__ */ new Map();
275
+ for (const [node, gates] of replay_gates(root)) {
276
+ const seen = by_id.get(node.id);
277
+ by_id.set(node.id, {
278
+ id: node.id,
279
+ label: label_of(node).label,
280
+ gates: seen === void 0 ? gates : [.../* @__PURE__ */ new Set([...seen.gates, ...gates])]
281
+ });
282
+ }
283
+ return [...by_id.values()];
284
+ }
285
+ //#endregion
138
286
  //#region src/core/diagram.ts
139
287
  /**
140
288
  * The renderer behind `describe.diagram(step)`: a flow drawn as an annotated
@@ -151,8 +299,9 @@ function is_step_kind(value) {
151
299
  * parallel member's key, a chain's stages), never from a config dump.
152
300
  * Descriptions share one column after the widest row. A composer's description
153
301
  * follows its kind (`branch: ...`), and a node without one shows its kind.
302
+ * With `replays` set, a step that a resumed run can run again before a gate
303
+ * ends its description with the gates it runs before.
154
304
  */
155
- const CHOSEN_ID_KINDS = /* @__PURE__ */ new Set(["step", "suspend"]);
156
305
  const BRANCH_ROLES = ["then", "else"];
157
306
  const STAGE_PREFIX = "stage:";
158
307
  const COLUMN_GAP = 2;
@@ -162,7 +311,7 @@ const COLUMN_GAP = 2;
162
311
  */
163
312
  function render_diagram(root, options) {
164
313
  const rows = [];
165
- flatten(to_item(root, void 0), "", "", rows);
314
+ flatten(to_item(root, void 0, options?.replays === true ? replay_gates(root) : /* @__PURE__ */ new Map()), "", "", rows);
166
315
  const column = Math.max(...rows.map((row) => row.lead.length + row.head.length)) + COLUMN_GAP;
167
316
  const prefix = options?.prefix ?? "";
168
317
  const limit = options?.width === void 0 ? Number.POSITIVE_INFINITY : options.width - prefix.length - column;
@@ -212,41 +361,20 @@ function wrap(words, limit) {
212
361
  * Convert one node into the item the layout draws. `role` is the name the
213
362
  * parent gives this child, and it is dropped when it only repeats the label.
214
363
  */
215
- function to_item(node, role) {
364
+ function to_item(node, role, marks) {
216
365
  const { label, by_kind } = label_of(node);
217
366
  return {
218
367
  head: role === void 0 || role === label ? label : `${role} ${label}`,
219
- note: note_of(node, by_kind),
220
- children: child_items(node)
221
- };
222
- }
223
- /**
224
- * Pick a node's label: its display name, else an id its author chose, else
225
- * its kind. `by_kind` reports the last case, where the kind already shows.
226
- */
227
- function label_of(node) {
228
- const display = resolve_display_name(node, "");
229
- if (display !== "") return {
230
- label: display,
231
- by_kind: false
232
- };
233
- if (has_chosen_id(node)) return {
234
- label: node.id,
235
- by_kind: false
236
- };
237
- return {
238
- label: node.kind,
239
- by_kind: true
368
+ note: [...note_of(node, by_kind), ...replay_note(marks.get(node))],
369
+ children: child_items(node, marks)
240
370
  };
241
371
  }
242
372
  /**
243
- * True when a node's id was chosen by its author. Anonymous steps, cycle
244
- * markers, and every built-in composer carry generated ids. A kind outside
245
- * the built-in set belongs to a hand-built step, whose id is its author's.
373
+ * The words that mark a step a resumed run can run again, naming the gates
374
+ * it runs before, or none for a step it can't.
246
375
  */
247
- function has_chosen_id(node) {
248
- if (node.anonymous === true || node.kind === "<cycle>") return false;
249
- return !is_step_kind(node.kind) || CHOSEN_ID_KINDS.has(node.kind);
376
+ function replay_note(gates) {
377
+ return gates === void 0 ? [] : `(replays before ${gates.join(", ")})`.split(" ");
250
378
  }
251
379
  /**
252
380
  * The words of a row's description column.
@@ -266,16 +394,16 @@ function note_of(node, by_kind) {
266
394
  * Convert a node's children, naming each by the role its parent's kind gives
267
395
  * it.
268
396
  */
269
- function child_items(node) {
397
+ function child_items(node, marks) {
270
398
  const children = node.children ?? [];
271
- if (node.kind === "branch") return children.map((child, i) => to_item(child, BRANCH_ROLES[i]));
272
- if (node.kind === "loop") return children.map((child, i) => to_item(child, i === 1 ? "guard" : void 0));
399
+ if (node.kind === "branch") return children.map((child, i) => to_item(child, BRANCH_ROLES[i], marks));
400
+ if (node.kind === "loop") return children.map((child, i) => to_item(child, i === 1 ? "guard" : void 0, marks));
273
401
  if (node.kind === "parallel") {
274
402
  const keys = string_list(node.config?.["keys"]);
275
- return children.map((child, i) => to_item(child, keys[i]));
403
+ return children.map((child, i) => to_item(child, keys[i], marks));
276
404
  }
277
- if (node.kind === "chain") return staged_items(children, string_list(node.config?.["plan"]));
278
- return children.map((child) => to_item(child, void 0));
405
+ if (node.kind === "chain") return staged_items(children, string_list(node.config?.["plan"]), marks);
406
+ return children.map((child) => to_item(child, void 0, marks));
279
407
  }
280
408
  /**
281
409
  * Convert a chain's children in plan order, nesting the entries after each
@@ -283,7 +411,7 @@ function child_items(node) {
283
411
  * encloses them in the trajectory. Children the plan does not account for
284
412
  * follow in order, so a node without a plan still draws every child.
285
413
  */
286
- function staged_items(children, plan) {
414
+ function staged_items(children, plan, marks) {
287
415
  const top = [];
288
416
  let target = top;
289
417
  let next = 0;
@@ -298,9 +426,9 @@ function staged_items(children, plan) {
298
426
  } else {
299
427
  const child = children[next];
300
428
  next += 1;
301
- if (child !== void 0) target.push(to_item(child, void 0));
429
+ if (child !== void 0) target.push(to_item(child, void 0, marks));
302
430
  }
303
- for (const child of children.slice(next)) target.push(to_item(child, void 0));
431
+ for (const child of children.slice(next)) target.push(to_item(child, void 0, marks));
304
432
  return top;
305
433
  }
306
434
  /**
@@ -453,6 +581,10 @@ function is_step(value) {
453
581
  * `describe.diagram(step)` draws the `describe.json` tree as an annotated
454
582
  * box-drawing diagram (see diagram.ts).
455
583
  *
584
+ * `describe.replays(step)` reads the same tree for the steps marked
585
+ * `side_effect` that a resumed run can run again before it reaches a gate
586
+ * (see replays.ts).
587
+ *
456
588
  * Both forms detect cycles. Under the default (loose) mode, back-references
457
589
  * render as `<cycle>(id)` in text and `{ kind: '<cycle>', id }` in JSON. Under
458
590
  * `{ strict: true }`, cycles throw `describe_cycle_error`.
@@ -482,12 +614,22 @@ function describe_diagram(root, options) {
482
614
  return render_diagram(describe_json(root, options), options);
483
615
  }
484
616
  /**
617
+ * Find the steps marked `side_effect` that a resumed run can run again before
618
+ * it reaches a gate. Like the diagram, it reads the `describe.json` tree, so
619
+ * it judges the flow's shape and runs nothing.
620
+ */
621
+ function describe_replays(root, options) {
622
+ return find_replays(describe_json(root, options));
623
+ }
624
+ /**
485
625
  * Public entry point: `describe(step)` for text, `describe.json(step)` for
486
- * the `FlowNode` tree, `describe.diagram(step)` for the annotated diagram.
626
+ * the `FlowNode` tree, `describe.diagram(step)` for the annotated diagram,
627
+ * and `describe.replays(step)` for the steps a resume would pay for twice.
487
628
  */
488
629
  const describe = Object.assign(describe_text, {
489
630
  json: describe_json,
490
- diagram: describe_diagram
631
+ diagram: describe_diagram,
632
+ replays: describe_replays
491
633
  });
492
634
  /**
493
635
  * Append one node (label line, config lines, then children) to `lines`.
@@ -3389,4 +3531,4 @@ register_traced_kind("chain");
3389
3531
  //#endregion
3390
3532
  export { describe_cycle_error as A, is_valid_step_id as C, describe as D, run as E, suspended_error as F, timeout_error as I, STEP_KINDS as L, flow_changed_error as M, resume_validation_error as N, is_step as O, run_not_found_error as P, is_step_kind as R, assert_valid_step_id as S, durable as T, map as _, suspend as a, sequence as b, checkpoint as c, timeout as d, fallback as f, pipe as g, wait_with_abort as h, use as i, error_path as j, aborted_error as k, compose as l, compute_backoff as m, scope as n, format_schema_issues as o, retry as p, stash as r, validate_schema as s, chain as t, loop as u, branch as v, suggest_step_id as w, step as x, parallel as y, resolve_display_name as z };
3391
3533
 
3392
- //# sourceMappingURL=core-B-M7nAkg.js.map
3534
+ //# sourceMappingURL=core-DK7g1Z40.js.map