fascicle 0.12.1 → 0.12.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. package/CHANGELOG.md +79 -33
  2. package/README.md +13 -13
  3. package/dist/{adapters-hmnJOOgf.js → adapters-CutexJd3.js} +12 -12
  4. package/dist/adapters-CutexJd3.js.map +1 -0
  5. package/dist/adapters.d.ts +10 -10
  6. package/dist/adapters.js +1 -1
  7. package/dist/agents.d.ts +13 -3
  8. package/dist/agents.js +12 -5
  9. package/dist/agents.js.map +1 -1
  10. package/dist/{core-DDRhHu5P.js → core-DdJEhyQc.js} +122 -488
  11. package/dist/core-DdJEhyQc.js.map +1 -0
  12. package/dist/{engine-b4ZH8esY.js → engine-J4lIxpw5.js} +40 -357
  13. package/dist/engine-J4lIxpw5.js.map +1 -0
  14. package/dist/index.d.ts +85 -25
  15. package/dist/index.js +402 -48
  16. package/dist/index.js.map +1 -1
  17. package/dist/{invoke-CyKNhvBw.js → invoke-CH_eJZeS.js} +8 -8
  18. package/dist/{invoke-CyKNhvBw.js.map → invoke-CH_eJZeS.js.map} +1 -1
  19. package/dist/leading_system-BUCT-PwD.js +330 -0
  20. package/dist/leading_system-BUCT-PwD.js.map +1 -0
  21. package/dist/mcp.d.ts +5 -5
  22. package/dist/mcp.js +10 -9
  23. package/dist/mcp.js.map +1 -1
  24. package/dist/otel.d.ts +1 -1
  25. package/dist/otel.js +4 -4
  26. package/dist/otel.js.map +1 -1
  27. package/dist/stdio.d.ts +2 -2
  28. package/dist/stdio.js +2 -2
  29. package/dist/testing.d.ts +1 -1
  30. package/dist/testing.js +3 -2
  31. package/dist/testing.js.map +1 -1
  32. package/dist/{trajectory-cSLNlHzh.d.ts → trajectory-ByoOQZ6T.d.ts} +10 -10
  33. package/dist/trajectory-D1eq9eue.js +81 -0
  34. package/dist/trajectory-D1eq9eue.js.map +1 -0
  35. package/dist/{types-BCtKsxrX.d.ts → types-BK0UW28o.d.ts} +3 -3
  36. package/dist/{types-BqUY6nRX.d.ts → types-DBpU27sQ.d.ts} +7 -2
  37. package/dist/{types-CXBB4aIM.d.ts → types-DU6cvoA4.d.ts} +3 -3
  38. package/dist/ui.d.ts +1 -1
  39. package/dist/ui.js +1 -1
  40. package/dist/ui.js.map +1 -1
  41. package/dist/viewer.d.ts +8 -8
  42. package/dist/viewer.js +16 -15
  43. package/dist/viewer.js.map +1 -1
  44. package/package.json +5 -4
  45. package/dist/adapters-hmnJOOgf.js.map +0 -1
  46. package/dist/core-DDRhHu5P.js.map +0 -1
  47. package/dist/engine-b4ZH8esY.js.map +0 -1
@@ -1,322 +1,4 @@
1
1
  import { randomUUID } from "node:crypto";
2
- //#region src/core/flow-schema.json
3
- var flow_schema_default = {
4
- $schema: "https://json-schema.org/draft/2020-12/schema",
5
- $id: "https://robmclarty.dev/schemas/flow-schema.json",
6
- title: "fascicle Flow DSL",
7
- description: "YAML/JSON representation of a composition tree. Documentation-only in v1. See spec.md §5.17.",
8
- type: "array",
9
- items: { "$ref": "#/$defs/compose_entry" },
10
- $defs: {
11
- "compose_entry": {
12
- "type": "object",
13
- "required": ["compose"],
14
- "properties": { "compose": { "type": "string" } },
15
- "allOf": [{ "$ref": "#/$defs/node" }]
16
- },
17
- "node": {
18
- "type": "object",
19
- "anyOf": [
20
- { "required": ["step"] },
21
- { "required": ["sequence"] },
22
- { "required": ["parallel"] },
23
- { "required": ["branch"] },
24
- { "required": ["map"] },
25
- { "required": ["pipe"] },
26
- { "required": ["retry"] },
27
- { "required": ["fallback"] },
28
- { "required": ["timeout"] },
29
- { "required": ["loop"] },
30
- { "required": ["compose_node"] },
31
- { "required": ["adversarial"] },
32
- { "required": ["ensemble"] },
33
- { "required": ["tournament"] },
34
- { "required": ["consensus"] },
35
- { "required": ["checkpoint"] },
36
- { "required": ["suspend"] },
37
- { "required": ["scope"] },
38
- { "required": ["chain"] },
39
- { "required": ["ref"] }
40
- ],
41
- "properties": {
42
- "step": { "$ref": "#/$defs/step_config" },
43
- "sequence": { "$ref": "#/$defs/sequence_config" },
44
- "parallel": { "$ref": "#/$defs/parallel_config" },
45
- "branch": { "$ref": "#/$defs/branch_config" },
46
- "map": { "$ref": "#/$defs/map_config" },
47
- "pipe": { "$ref": "#/$defs/pipe_config" },
48
- "retry": { "$ref": "#/$defs/retry_config" },
49
- "fallback": { "$ref": "#/$defs/fallback_config" },
50
- "timeout": { "$ref": "#/$defs/timeout_config" },
51
- "loop": { "$ref": "#/$defs/loop_config" },
52
- "compose_node": { "$ref": "#/$defs/compose_node_config" },
53
- "adversarial": { "$ref": "#/$defs/adversarial_config" },
54
- "ensemble": { "$ref": "#/$defs/ensemble_config" },
55
- "tournament": { "$ref": "#/$defs/tournament_config" },
56
- "consensus": { "$ref": "#/$defs/consensus_config" },
57
- "checkpoint": { "$ref": "#/$defs/checkpoint_config" },
58
- "suspend": { "$ref": "#/$defs/suspend_config" },
59
- "scope": { "$ref": "#/$defs/scope_config" },
60
- "chain": { "$ref": "#/$defs/chain_config" },
61
- "ref": { "type": "string" }
62
- }
63
- },
64
- "step_config": {
65
- "type": "object",
66
- "required": ["fn"],
67
- "properties": {
68
- "id": { "type": "string" },
69
- "fn": { "type": "string" }
70
- }
71
- },
72
- "sequence_config": {
73
- "type": "array",
74
- "items": { "$ref": "#/$defs/node" }
75
- },
76
- "parallel_config": {
77
- "type": "object",
78
- "additionalProperties": { "$ref": "#/$defs/node" }
79
- },
80
- "branch_config": {
81
- "type": "object",
82
- "required": [
83
- "when",
84
- "then",
85
- "otherwise"
86
- ],
87
- "properties": {
88
- "when": { "type": "string" },
89
- "then": { "$ref": "#/$defs/node" },
90
- "otherwise": { "$ref": "#/$defs/node" }
91
- }
92
- },
93
- "map_config": {
94
- "type": "object",
95
- "required": ["items", "do"],
96
- "properties": {
97
- "items": { "type": "string" },
98
- "do": { "$ref": "#/$defs/node" },
99
- "concurrency": {
100
- "type": "integer",
101
- "minimum": 1
102
- }
103
- }
104
- },
105
- "pipe_config": {
106
- "type": "object",
107
- "required": ["of", "fn"],
108
- "properties": {
109
- "of": { "$ref": "#/$defs/node" },
110
- "fn": { "type": "string" }
111
- }
112
- },
113
- "retry_config": {
114
- "type": "object",
115
- "required": ["do", "max_attempts"],
116
- "properties": {
117
- "do": { "$ref": "#/$defs/node" },
118
- "max_attempts": {
119
- "type": "integer",
120
- "minimum": 1
121
- },
122
- "backoff_ms": {
123
- "type": "integer",
124
- "minimum": 0
125
- }
126
- }
127
- },
128
- "fallback_config": {
129
- "type": "object",
130
- "required": ["primary", "backup"],
131
- "properties": {
132
- "primary": { "$ref": "#/$defs/node" },
133
- "backup": { "$ref": "#/$defs/node" }
134
- }
135
- },
136
- "timeout_config": {
137
- "type": "object",
138
- "required": ["do", "ms"],
139
- "properties": {
140
- "do": { "$ref": "#/$defs/node" },
141
- "ms": {
142
- "type": "integer",
143
- "minimum": 1
144
- }
145
- }
146
- },
147
- "compose_node_config": {
148
- "type": "object",
149
- "required": ["name", "do"],
150
- "properties": {
151
- "name": {
152
- "type": "string",
153
- "minLength": 1
154
- },
155
- "do": { "$ref": "#/$defs/node" }
156
- }
157
- },
158
- "loop_config": {
159
- "type": "object",
160
- "required": ["body", "max_rounds"],
161
- "properties": {
162
- "name": {
163
- "type": "string",
164
- "minLength": 1
165
- },
166
- "init": { "type": "string" },
167
- "body": { "$ref": "#/$defs/node" },
168
- "guard": { "$ref": "#/$defs/node" },
169
- "finish": { "type": "string" },
170
- "max_rounds": {
171
- "type": "integer",
172
- "minimum": 1
173
- }
174
- }
175
- },
176
- "adversarial_config": {
177
- "type": "object",
178
- "required": [
179
- "build",
180
- "critique",
181
- "accept",
182
- "max_rounds"
183
- ],
184
- "properties": {
185
- "build": { "$ref": "#/$defs/node" },
186
- "critique": { "$ref": "#/$defs/node" },
187
- "accept": { "type": "string" },
188
- "max_rounds": {
189
- "type": "integer",
190
- "minimum": 1
191
- }
192
- }
193
- },
194
- "ensemble_config": {
195
- "type": "object",
196
- "required": ["members", "score"],
197
- "properties": {
198
- "members": {
199
- "type": "object",
200
- "additionalProperties": { "$ref": "#/$defs/node" }
201
- },
202
- "score": { "type": "string" },
203
- "select": {
204
- "type": "string",
205
- "enum": ["max", "min"]
206
- }
207
- }
208
- },
209
- "tournament_config": {
210
- "type": "object",
211
- "required": ["members", "compare"],
212
- "properties": {
213
- "members": {
214
- "type": "object",
215
- "additionalProperties": { "$ref": "#/$defs/node" }
216
- },
217
- "compare": { "type": "string" }
218
- }
219
- },
220
- "consensus_config": {
221
- "type": "object",
222
- "required": [
223
- "members",
224
- "agree",
225
- "max_rounds"
226
- ],
227
- "properties": {
228
- "members": {
229
- "type": "object",
230
- "additionalProperties": { "$ref": "#/$defs/node" }
231
- },
232
- "agree": { "type": "string" },
233
- "max_rounds": {
234
- "type": "integer",
235
- "minimum": 1
236
- }
237
- }
238
- },
239
- "checkpoint_config": {
240
- "type": "object",
241
- "required": ["do", "key"],
242
- "properties": {
243
- "do": { "$ref": "#/$defs/node" },
244
- "key": { "type": "string" }
245
- }
246
- },
247
- "suspend_config": {
248
- "type": "object",
249
- "required": [
250
- "id",
251
- "on",
252
- "resume_schema",
253
- "combine"
254
- ],
255
- "properties": {
256
- "id": { "type": "string" },
257
- "on": { "type": "string" },
258
- "resume_schema": { "type": "string" },
259
- "combine": { "type": "string" }
260
- }
261
- },
262
- "scope_config": {
263
- "type": "array",
264
- "items": { "$ref": "#/$defs/scope_entry" }
265
- },
266
- "scope_entry": {
267
- "type": "object",
268
- "oneOf": [{
269
- "type": "object",
270
- "required": ["stash", "do"],
271
- "properties": {
272
- "stash": { "type": "string" },
273
- "do": { "$ref": "#/$defs/node" }
274
- }
275
- }, {
276
- "type": "object",
277
- "required": ["use", "do"],
278
- "properties": {
279
- "use": {
280
- "type": "array",
281
- "items": { "type": "string" }
282
- },
283
- "do": { "$ref": "#/$defs/node" }
284
- }
285
- }]
286
- },
287
- "chain_config": {
288
- "type": "object",
289
- "required": ["steps", "output"],
290
- "properties": {
291
- "input": { "type": "string" },
292
- "steps": {
293
- "type": "array",
294
- "items": { "$ref": "#/$defs/chain_entry" }
295
- },
296
- "output": { "type": "string" }
297
- }
298
- },
299
- "chain_entry": {
300
- "type": "object",
301
- "oneOf": [{
302
- "type": "object",
303
- "required": ["step", "fn"],
304
- "properties": {
305
- "step": { "type": "string" },
306
- "fn": { "type": "string" }
307
- }
308
- }, {
309
- "type": "object",
310
- "required": ["stage"],
311
- "properties": {
312
- "stage": { "type": "string" },
313
- "project": { "type": "string" }
314
- }
315
- }]
316
- }
317
- }
318
- };
319
- //#endregion
320
2
  //#region src/core/cleanup.ts
321
3
  const HANDLER_TIMEOUT_MS = 5e3;
322
4
  /**
@@ -388,6 +70,19 @@ async function run_one(fn, trajectory) {
388
70
  }
389
71
  }
390
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
+ */
78
+ function resolve_display_name(node, fallback) {
79
+ const display = node.config?.["display_name"];
80
+ if (typeof display === "string" && display.length > 0) return display;
81
+ const name = node.meta?.name;
82
+ if (typeof name === "string" && name.length > 0) return name;
83
+ return fallback;
84
+ }
85
+ //#endregion
391
86
  //#region src/core/errors.ts
392
87
  var timeout_error = class extends Error {
393
88
  kind = "timeout_error";
@@ -608,19 +303,6 @@ function register_kind(kind, fn) {
608
303
  dispatch.set(kind, fn);
609
304
  }
610
305
  /**
611
- * Resolve the trajectory span label for a step. Prefers a non-empty
612
- * `display_name` from `flow.config`; otherwise falls back to the supplied
613
- * default (typically the step's `kind`).
614
- *
615
- * Dispatch handlers use this so that any composer carrying a user-supplied
616
- * `name` surfaces under that label in the trajectory, while unconfigured
617
- * composers retain their kind-based label.
618
- */
619
- function resolve_span_label(flow, fallback) {
620
- const display = flow.config?.["display_name"];
621
- return typeof display === "string" && display.length > 0 ? display : fallback;
622
- }
623
- /**
624
306
  * Register the standard span-wrapping dispatch handler for a composer kind.
625
307
  *
626
308
  * Every composer wraps `flow.run` in a span identically; this centralizes that
@@ -632,7 +314,7 @@ function resolve_span_label(flow, fallback) {
632
314
  */
633
315
  function register_traced_kind(kind) {
634
316
  register_kind(kind, async (flow, input, ctx) => {
635
- const label = resolve_span_label(flow, kind);
317
+ const label = resolve_display_name(flow, kind);
636
318
  const span_meta = { id: flow.id };
637
319
  if (ctx.parent_span_id !== void 0) span_meta["parent_span_id"] = ctx.parent_span_id;
638
320
  const span_id = ctx.trajectory.start_span(label, span_meta);
@@ -800,7 +482,7 @@ function throw_if_aborted(ctx) {
800
482
  * Concurrent composers (`map`, `parallel`) use this to propagate a parent
801
483
  * abort into each in-flight child's composed signal. `controllers` is read by
802
484
  * reference, so a caller that appends to the array after installing (as
803
- * `map` does per newly-started item) is still covered by later aborts.
485
+ * `map` does per newly started item) is still covered by later aborts.
804
486
  * Returns the listener so the caller can remove it once its children settle.
805
487
  */
806
488
  function install_abort_fan_out(ctx, controllers) {
@@ -1025,19 +707,70 @@ const run = Object.assign(run_impl, {
1025
707
  until_suspended: run_until_suspended
1026
708
  });
1027
709
  //#endregion
710
+ //#region src/core/step_id.ts
711
+ /**
712
+ * Step id validation.
713
+ *
714
+ * Every id in the system is constrained to a valid JavaScript identifier
715
+ * rather than an arbitrary string, because ids are read back as property
716
+ * names: `chain` merges each binding into a typed record under its name, and
717
+ * a name you cannot destructure is a name the record cannot offer. Holding
718
+ * one rule across `step`, `chain`, and the agent surface means a user learns
719
+ * it once instead of discovering per-primitive exceptions.
720
+ *
721
+ * Prose is not constrained, because prose has its own channel: `meta.name`
722
+ * on a step, `name` on a chain binding or composer.
723
+ *
724
+ * Nothing normalizes an id on the caller's behalf. A silent transformation
725
+ * would map several distinct names onto one key ('my-id', 'my.id', and
726
+ * 'my_id' all reduce to 'my_id') and would have to stay bug-for-bug in sync
727
+ * with the equivalent type-level transformation. The suggestion in the
728
+ * failure message is a courtesy for the reader, never a contract.
729
+ */
730
+ const IDENTIFIER = /^[\p{ID_Start}$_][\p{ID_Continue}$]*$/u;
731
+ /**
732
+ * Report whether `id` can be read back as a property name.
733
+ */
734
+ function is_valid_step_id(id) {
735
+ return IDENTIFIER.test(id);
736
+ }
737
+ /**
738
+ * Render the closest identifier-shaped spelling of `raw`, for failure
739
+ * messages only. Prefixes an underscore when the swap alone still leaves an
740
+ * illegal leading character, so the suggestion is always usable as written.
741
+ */
742
+ function suggest_step_id(raw) {
743
+ const swapped = raw.replace(/[^\p{ID_Continue}$]/gu, "_");
744
+ return IDENTIFIER.test(swapped) ? swapped : `_${swapped}`;
745
+ }
746
+ /**
747
+ * Throw when `id` is not identifier-shaped. `subject` names the failing
748
+ * surface so the message points at the call the reader actually wrote, and
749
+ * `remedy` says where the prose spelling belongs instead.
750
+ */
751
+ function assert_valid_step_id(id, subject, remedy) {
752
+ if (is_valid_step_id(id)) return;
753
+ throw new TypeError(`${subject} ${JSON.stringify(id)} is not a valid identifier: ids are read back as property names, so use ${suggest_step_id(id)} and ${remedy}`);
754
+ }
755
+ //#endregion
1028
756
  //#region src/core/step.ts
1029
757
  /**
1030
758
  * step() factory.
1031
759
  *
1032
760
  * Three forms:
1033
761
  * step(id, fn): named step. id is rendered in trajectory spans and describe().
1034
- * step(id, fn, meta): named step with optional human-readable metadata for studio,
1035
- * codegen, and similar consumers. `meta` is purely descriptive
1036
- * and never affects runtime semantics.
762
+ * step(id, fn, meta): named step carrying descriptive metadata. `meta.name` is the
763
+ * display channel: it labels the step's trajectory span and its
764
+ * describe() line, leaving the id free to stay a stable
765
+ * identifier. Nothing keys off it, so it is safe to reword.
1037
766
  * step(fn): anonymous step. id is `step_<counter>`; cannot be checkpointed.
1038
767
  *
1039
768
  * Anonymous steps carry an internal `anonymous: true` flag so checkpoint can
1040
769
  * reject them synchronously at flow construction time.
770
+ *
771
+ * An explicit id must be identifier-shaped: ids are read back as property
772
+ * names wherever a step's output is bound (see step_id.ts). Free prose goes
773
+ * in `meta.name`.
1041
774
  */
1042
775
  let step_counter = 0;
1043
776
  /**
@@ -1055,6 +788,7 @@ function step(id_or_fn, maybe_fn, meta) {
1055
788
  anonymous: true
1056
789
  };
1057
790
  if (typeof maybe_fn !== "function") throw new TypeError("step(id, fn): fn must be a function");
791
+ assert_valid_step_id(id_or_fn, "step id", "put the label in meta.name");
1058
792
  if (meta) return {
1059
793
  id: id_or_fn,
1060
794
  kind: "step",
@@ -1138,9 +872,7 @@ function render_text(node, depth, lines, path, strict) {
1138
872
  }
1139
873
  path.add(node);
1140
874
  try {
1141
- const display = node.config?.["display_name"];
1142
- const label = typeof display === "string" && display.length > 0 ? display : node.kind;
1143
- lines.push(`${prefix}${label}(${node.id})`);
875
+ lines.push(`${prefix}${resolve_display_name(node, node.kind)}(${node.id})`);
1144
876
  if (node.config) for (const [key, value] of Object.entries(node.config)) {
1145
877
  if (key === "display_name") continue;
1146
878
  lines.push(`${prefix}${INDENT}${key}: ${render_value_text(value, path, strict)}`);
@@ -1350,7 +1082,7 @@ function next_id$10() {
1350
1082
  return `sequence_${sequence_counter}`;
1351
1083
  }
1352
1084
  function sequence(children, options) {
1353
- 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])`);
1085
+ 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])`);
1354
1086
  children.forEach((child, index) => {
1355
1087
  if (is_step(child)) return;
1356
1088
  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" : ""}`);
@@ -1994,11 +1726,15 @@ register_traced_kind("timeout");
1994
1726
  */
1995
1727
  let loop_counter = 0;
1996
1728
  /**
1997
- * Generate a unique step id, prefixed with the display name when one is set.
1729
+ * Generate a unique step id of the form `loop_<n>`.
1730
+ *
1731
+ * The display `name` deliberately stays out of the id. It is free prose, so
1732
+ * folding it in would both make a cosmetic rename move a trajectory id and
1733
+ * put an arbitrary string where an identifier is required.
1998
1734
  */
1999
- function next_id$2(name) {
1735
+ function next_id$2() {
2000
1736
  loop_counter += 1;
2001
- return `${name ?? "loop"}_${loop_counter}`;
1737
+ return `loop_${loop_counter}`;
2002
1738
  }
2003
1739
  /**
2004
1740
  * Normalize the guard config to its step form.
@@ -2028,7 +1764,7 @@ function wrap_guard(guard, loop_id) {
2028
1764
  function loop(config) {
2029
1765
  const { init, body, finish, name } = config;
2030
1766
  const rounds_limit = Math.max(1, Math.floor(config.max_rounds));
2031
- const id = next_id$2(name);
1767
+ const id = next_id$2();
2032
1768
  const guard = wrap_guard(config.guard, id);
2033
1769
  const run_fn = async (input, ctx) => {
2034
1770
  let state = init(input);
@@ -2069,37 +1805,40 @@ register_traced_kind("loop");
2069
1805
  /**
2070
1806
  * compose: name a composite step.
2071
1807
  *
2072
- * `compose(name, inner)` wraps any step and labels its trajectory span with
2073
- * `name`. The inner step's own span (e.g. a `sequence`) appears as a child of
2074
- * the compose span: the implementation tree is preserved while the user's
2075
- * intent ("this whole thing is an ensemble") is surfaced in observability.
1808
+ * `compose(inner, { name })` wraps any step and labels its trajectory span
1809
+ * with `name`. The inner step's own span (for example, a `sequence`) appears
1810
+ * as a child of the compose span: the implementation tree is preserved while
1811
+ * the user's intent ("this whole thing is an ensemble") is surfaced in
1812
+ * observability.
2076
1813
  *
2077
1814
  * Used by the composites package to make built-in patterns appear under
2078
1815
  * their familiar names, and available to library consumers who want their own
2079
1816
  * named composites to show up in logs as first-class components.
2080
1817
  *
2081
- * The primitive's `kind` is always `'compose'`; the user-supplied label lives
2082
- * in `config.display_name` and is the span name the dispatcher opens.
1818
+ * The primitive's `kind` is always `'compose'` and its id is `compose_<n>`.
1819
+ * The user-supplied label lives in `config.display_name`, is the span name
1820
+ * the dispatcher opens, and never reaches the id: it is free prose, so
1821
+ * folding it in would let a cosmetic rename move a trajectory id.
2083
1822
  */
2084
1823
  let compose_counter = 0;
2085
1824
  /**
2086
- * Generate a unique step id of the form `<name>_<n>`, using the user-supplied
2087
- * label so compose ids read naturally in traces.
1825
+ * Generate a unique step id of the form `compose_<n>`.
2088
1826
  */
2089
- function next_id$1(name) {
1827
+ function next_id$1() {
2090
1828
  compose_counter += 1;
2091
- return `${name}_${compose_counter}`;
1829
+ return `compose_${compose_counter}`;
2092
1830
  }
2093
1831
  /**
2094
1832
  * Wrap `inner` in a named composite step.
2095
1833
  *
2096
- * The step's `kind` is always `'compose'`; `name` becomes the
1834
+ * The step's `kind` is always `'compose'`; `config.name` becomes the
2097
1835
  * `display_name` used as the span label. Throws a `TypeError` when `name`
2098
1836
  * is not a non-empty string, catching the mistake at construction time.
2099
1837
  */
2100
- function compose(name, inner) {
2101
- if (typeof name !== "string" || name.length === 0) throw new TypeError("compose(name, inner): name must be a non-empty string");
2102
- const id = next_id$1(name);
1838
+ function compose(inner, config) {
1839
+ const name = config?.name;
1840
+ if (typeof name !== "string" || name.length === 0) throw new TypeError("compose(inner, { name }): name must be a non-empty string");
1841
+ const id = next_id$1();
2103
1842
  const run_fn = (input, ctx) => dispatch_step(inner, input, ctx);
2104
1843
  return {
2105
1844
  id,
@@ -2123,7 +1862,7 @@ register_traced_kind("compose");
2123
1862
  * `status: 'hit' | 'miss' | 'read_error'`.
2124
1863
  *
2125
1864
  * Wrapping an anonymous inner step throws synchronously at construction time
2126
- * with the message `checkpoint requires a named step; got anonymous`, because
1865
+ * with the message `checkpoint requires a named step, got anonymous`, because
2127
1866
  * a cached result must map back to a stable, identifiable step.
2128
1867
  */
2129
1868
  let checkpoint_counter = 0;
@@ -2144,7 +1883,7 @@ function next_id() {
2144
1883
  * is anonymous.
2145
1884
  */
2146
1885
  function checkpoint(inner, config) {
2147
- if (inner.anonymous === true) throw new Error("checkpoint requires a named step; got anonymous");
1886
+ if (inner.anonymous === true) throw new Error("checkpoint requires a named step, got anonymous — give the inner step an id with step('id', fn)");
2148
1887
  const id = next_id();
2149
1888
  const key_spec = config.key;
2150
1889
  const run_fn = async (input, ctx) => {
@@ -2199,7 +1938,7 @@ register_traced_kind("checkpoint");
2199
1938
  *
2200
1939
  * Always async, even for a validator that answers synchronously: the spec
2201
1940
  * permits `validate` to return either a result or a promise of one, and
2202
- * fascicle cannot know which a given vendor does. Awaiting a non-promise is
1941
+ * Fascicle cannot know which a given vendor does. Awaiting a non-promise is
2203
1942
  * cheap; guessing wrong is a silent bug.
2204
1943
  */
2205
1944
  async function validate_schema(schema, value) {
@@ -2214,7 +1953,7 @@ async function validate_schema(schema, value) {
2214
1953
  };
2215
1954
  }
2216
1955
  /**
2217
- * Flatten one vendor issue into fascicle's shape.
1956
+ * Flatten one vendor issue into Fascicle's shape.
2218
1957
  *
2219
1958
  * The spec allows a path segment to be a bare key or a `{ key }` wrapper, and
2220
1959
  * allows the path to be absent entirely. Normalizing here means no consumer has
@@ -2541,6 +2280,16 @@ function build_chain(input_name, entries, output_node) {
2541
2280
  };
2542
2281
  }
2543
2282
  /**
2283
+ * Project a binding's options onto `step`'s trailing metadata argument.
2284
+ *
2285
+ * Returned as a spreadable tuple so a binding with no label calls `step`
2286
+ * with two arguments, leaving `meta` genuinely absent rather than set to an
2287
+ * empty object that `describe` would then echo.
2288
+ */
2289
+ function binding_meta(options) {
2290
+ return options?.name === void 0 ? [] : [{ name: options.name }];
2291
+ }
2292
+ /**
2544
2293
  * Build the binding node for the arm-first `.step(name, arm, select)` form.
2545
2294
  *
2546
2295
  * The chain owns the dispatch: the synthesized body projects the record
@@ -2548,10 +2297,10 @@ function build_chain(input_name, entries, output_node) {
2548
2297
  * same arm is recorded as the binding's child, so the subtree `describe`
2549
2298
  * renders and the step that runs are one value by construction.
2550
2299
  */
2551
- function arm_node(name, arm, select) {
2300
+ function arm_node(name, arm, select, options) {
2552
2301
  if (typeof select !== "function") throw new TypeError("chain.step(name, arm, select): select must be a function");
2553
2302
  return {
2554
- ...step(name, (s, ctx) => ctx.call(arm, select(s))),
2303
+ ...step(name, (s, ctx) => ctx.call(arm, select(s)), ...binding_meta(options)),
2555
2304
  children: [arm]
2556
2305
  };
2557
2306
  }
@@ -2559,8 +2308,9 @@ function arm_node(name, arm, select) {
2559
2308
  * Build the binding node for the body form `.step(name, fn, { arm? })`.
2560
2309
  */
2561
2310
  function body_node(name, fn, options) {
2562
- const base = step(name, fn);
2563
- const arm = typeof options === "function" ? void 0 : options?.arm;
2311
+ const settings = typeof options === "function" ? void 0 : options;
2312
+ const base = step(name, fn, ...binding_meta(settings));
2313
+ const arm = settings?.arm;
2564
2314
  return arm === void 0 ? base : {
2565
2315
  ...base,
2566
2316
  children: [arm]
@@ -2576,9 +2326,10 @@ function body_node(name, fn, options) {
2576
2326
  */
2577
2327
  function make_chain(input_name, entries, bound) {
2578
2328
  return {
2579
- step: (name, fn_or_arm, options_or_select) => {
2329
+ step: (name, fn_or_arm, options_or_select, arm_options) => {
2330
+ assert_valid_step_id(name, "chain.step: binding name", "put the label in the options object as { name }");
2580
2331
  if (bound.has(name)) throw new TypeError(`chain.step: binding '${name}' is already defined in this stage; names are single-assignment`);
2581
- const node = is_step(fn_or_arm) ? arm_node(name, fn_or_arm, options_or_select) : body_node(name, fn_or_arm, options_or_select);
2332
+ const node = is_step(fn_or_arm) ? arm_node(name, fn_or_arm, options_or_select, arm_options) : body_node(name, fn_or_arm, options_or_select);
2582
2333
  return make_chain(input_name, [...entries, {
2583
2334
  kind: "step",
2584
2335
  name,
@@ -2610,6 +2361,7 @@ function make_chain(input_name, entries, bound) {
2610
2361
  */
2611
2362
  function chain(input_name) {
2612
2363
  const name = input_name ?? "input";
2364
+ assert_valid_step_id(name, "chain: input name", "rename the binding");
2613
2365
  const open = make_chain(name, [], /* @__PURE__ */ new Set([name]));
2614
2366
  return {
2615
2367
  ...open,
@@ -2618,124 +2370,6 @@ function chain(input_name) {
2618
2370
  }
2619
2371
  register_traced_kind("chain");
2620
2372
  //#endregion
2621
- //#region src/core/step_kinds.ts
2622
- /**
2623
- * Closed registry of every `Step.kind` produced by the composition layer.
2624
- *
2625
- * Studio (and any other consumer that needs to enumerate primitives: palette,
2626
- * docs, code generation) can rely on this being the exhaustive set. New
2627
- * primitives must add their kind here. The `step_kinds_cover_runner` contract
2628
- * test in `step_kinds.test.ts` asserts every dispatch handler corresponds to a
2629
- * kind listed here.
2630
- */
2631
- const STEP_KINDS = [
2632
- "step",
2633
- "sequence",
2634
- "parallel",
2635
- "branch",
2636
- "map",
2637
- "pipe",
2638
- "retry",
2639
- "fallback",
2640
- "timeout",
2641
- "loop",
2642
- "compose",
2643
- "adversarial",
2644
- "ensemble",
2645
- "tournament",
2646
- "consensus",
2647
- "checkpoint",
2648
- "suspend",
2649
- "scope",
2650
- "stash",
2651
- "use",
2652
- "chain"
2653
- ];
2654
- /**
2655
- * Check whether a value is one of the registered `Step.kind` strings.
2656
- */
2657
- function is_step_kind(value) {
2658
- return typeof value === "string" && STEP_KINDS.includes(value);
2659
- }
2660
- //#endregion
2661
- //#region src/core/trajectory.ts
2662
- /**
2663
- * The wire gate: a non-array object carrying a string `kind`.
2664
- *
2665
- * True for every well-known kind as well, since `custom` is the fallback shape
2666
- * rather than a disjoint case.
2667
- */
2668
- function is_custom_trajectory_event(value) {
2669
- if (typeof value !== "object" || value === null) return false;
2670
- if (Array.isArray(value)) return false;
2671
- return typeof value.kind === "string";
2672
- }
2673
- /** A composer span open: both `span_id` and `name` must be present as strings. */
2674
- function is_span_start_event(value) {
2675
- if (!is_custom_trajectory_event(value)) return false;
2676
- if (value.kind !== "span_start") return false;
2677
- return typeof value["span_id"] === "string" && typeof value["name"] === "string";
2678
- }
2679
- /** A composer span close: `span_id` must be present as a string, `name` need not be. */
2680
- function is_span_end_event(value) {
2681
- if (!is_custom_trajectory_event(value)) return false;
2682
- return value.kind === "span_end" && typeof value["span_id"] === "string";
2683
- }
2684
- /** A `ctx.emit` event: the kind alone identifies it, the payload is the caller's. */
2685
- function is_emit_event(value) {
2686
- return is_custom_trajectory_event(value) && value.kind === "emit";
2687
- }
2688
- const RUN_END_STATUSES = /* @__PURE__ */ new Set([
2689
- "done",
2690
- "failed",
2691
- "aborted",
2692
- "suspended"
2693
- ]);
2694
- /**
2695
- * A terminal run event: `status` must be one of the known run outcomes, so the
2696
- * narrowed type's `status` union is truthful. An unknown future status still
2697
- * passes the wire gate as a custom event.
2698
- */
2699
- function is_run_end_event(value) {
2700
- if (!is_custom_trajectory_event(value)) return false;
2701
- if (value.kind !== "run_end") return false;
2702
- const status = value["status"];
2703
- return typeof status === "string" && RUN_END_STATUSES.has(status);
2704
- }
2705
- const CHECKPOINT_STATUSES = /* @__PURE__ */ new Set([
2706
- "hit",
2707
- "miss",
2708
- "read_error"
2709
- ]);
2710
- /**
2711
- * A checkpoint lookup event: `status` must be a known lookup outcome and `key`
2712
- * the store key that was consulted, for the same truthful-narrowing reason as
2713
- * `is_run_end_event`.
2714
- */
2715
- function is_checkpoint_event(value) {
2716
- if (!is_custom_trajectory_event(value)) return false;
2717
- if (value.kind !== "checkpoint") return false;
2718
- const status = value["status"];
2719
- if (typeof status !== "string" || !CHECKPOINT_STATUSES.has(status)) return false;
2720
- return typeof value["key"] === "string";
2721
- }
2722
- /**
2723
- * Parse one wire value into a trajectory event, `safeParse`-shaped.
2724
- *
2725
- * On success `data` is the value itself, not a copy, so nothing on the line is
2726
- * dropped or reordered on the way through.
2727
- */
2728
- function parse_trajectory_event(value) {
2729
- if (!is_custom_trajectory_event(value)) return {
2730
- success: false,
2731
- error: /* @__PURE__ */ new Error("not a trajectory event: expected an object with a string 'kind'")
2732
- };
2733
- return {
2734
- success: true,
2735
- data: value
2736
- };
2737
- }
2738
- //#endregion
2739
2373
  //#region src/core/index.ts
2740
2374
  /**
2741
2375
  * Public surface for core.
@@ -2747,6 +2381,6 @@ function parse_trajectory_event(value) {
2747
2381
  * and surface through the umbrella package.
2748
2382
  */
2749
2383
  //#endregion
2750
- export { describe as A, flow_schema_default as B, compute_backoff as C, branch as D, map as E, describe_cycle_error as F, error_path as I, resume_validation_error as L, step as M, run as N, parallel as O, aborted_error as P, suspended_error as R, retry as S, pipe as T, checkpoint as _, is_span_end_event as a, timeout as b, STEP_KINDS as c, scope as d, stash as f, validate_schema as g, format_schema_issues as h, is_run_end_event as i, is_step as j, sequence as k, is_step_kind as l, suspend as m, is_custom_trajectory_event as n, is_span_start_event as o, use as p, is_emit_event as r, parse_trajectory_event as s, is_checkpoint_event as t, chain as u, compose as v, wait_with_abort as w, fallback as x, loop as y, timeout_error as z };
2384
+ export { error_path as A, step as C, run as D, suggest_step_id as E, suspended_error as M, timeout_error as N, aborted_error as O, resolve_display_name as P, is_step as S, is_valid_step_id 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, assert_valid_step_id as w, describe as x, parallel as y };
2751
2385
 
2752
- //# sourceMappingURL=core-DDRhHu5P.js.map
2386
+ //# sourceMappingURL=core-DdJEhyQc.js.map