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 +20 -0
- package/dist/adapters.d.ts +1 -1
- package/dist/agents.d.ts +2 -2
- package/dist/agents.js +1 -1
- package/dist/bin/fascicle-diagram.js +9 -0
- package/dist/{core-BClsJ3h0.js → core-BVCVUMmH.js} +332 -65
- package/dist/core-BVCVUMmH.js.map +1 -0
- package/dist/diagram_bin.d.ts +25 -0
- package/dist/diagram_bin.js +239 -0
- package/dist/diagram_bin.js.map +1 -0
- package/dist/{engine-Djq7EH9x.js → engine-Ct4LBzb9.js} +4 -4
- package/dist/{engine-Djq7EH9x.js.map → engine-Ct4LBzb9.js.map} +1 -1
- package/dist/index.d.ts +56 -32
- package/dist/index.js +48 -53
- package/dist/index.js.map +1 -1
- package/dist/{invoke-dc5DdrrJ.js → invoke-BcPDqE5C.js} +3 -3
- package/dist/{invoke-dc5DdrrJ.js.map → invoke-BcPDqE5C.js.map} +1 -1
- package/dist/{leading_system-B6hsYN90.js → leading_system-CfOIc5fi.js} +2 -2
- package/dist/{leading_system-B6hsYN90.js.map → leading_system-CfOIc5fi.js.map} +1 -1
- package/dist/mcp.d.ts +2 -2
- package/dist/mcp.js +1 -1
- package/dist/otel.d.ts +1 -1
- package/dist/stdio.d.ts +1 -1
- package/dist/stdio.js +1 -1
- package/dist/testing.d.ts +1 -1
- package/dist/testing.js +3 -3
- package/dist/{types-DBpU27sQ.d.ts → types-BasW4Wwb.d.ts} +43 -2
- package/dist/{types-DcNpT0Hl.d.ts → types-bEpfDrys.d.ts} +2 -2
- package/dist/ui.d.ts +1 -1
- package/dist/viewer.js +1 -1
- package/package.json +4 -2
- package/dist/core-BClsJ3h0.js.map +0 -1
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
|
package/dist/adapters.d.ts
CHANGED
package/dist/agents.d.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
import {
|
|
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-
|
|
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 {
|
|
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)
|
|
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, {
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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):
|
|
1017
|
-
* step(id, fn,
|
|
1018
|
-
*
|
|
1019
|
-
*
|
|
1020
|
-
*
|
|
1021
|
-
*
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
1813
|
-
|
|
1814
|
-
|
|
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
|
|
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
|
-
...
|
|
2372
|
-
|
|
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
|
-
|
|
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 {
|
|
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-
|
|
2721
|
+
//# sourceMappingURL=core-BVCVUMmH.js.map
|