fascicle 0.12.1 → 0.12.5
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 +113 -38
- package/README.md +16 -15
- package/dist/{adapters-hmnJOOgf.js → adapters-CutexJd3.js} +12 -12
- package/dist/adapters-CutexJd3.js.map +1 -0
- package/dist/adapters.d.ts +10 -10
- package/dist/adapters.js +1 -1
- package/dist/agents.d.ts +13 -3
- package/dist/agents.js +12 -5
- package/dist/agents.js.map +1 -1
- package/dist/{core-DDRhHu5P.js → core-DdJEhyQc.js} +122 -488
- package/dist/core-DdJEhyQc.js.map +1 -0
- package/dist/{engine-b4ZH8esY.js → engine-CdXegeqC.js} +201 -380
- package/dist/engine-CdXegeqC.js.map +1 -0
- package/dist/index.d.ts +111 -25
- package/dist/index.js +446 -48
- package/dist/index.js.map +1 -1
- package/dist/{invoke-CyKNhvBw.js → invoke-CH_eJZeS.js} +8 -8
- package/dist/{invoke-CyKNhvBw.js.map → invoke-CH_eJZeS.js.map} +1 -1
- package/dist/leading_system-BUCT-PwD.js +330 -0
- package/dist/leading_system-BUCT-PwD.js.map +1 -0
- package/dist/mcp.d.ts +5 -5
- package/dist/mcp.js +10 -9
- package/dist/mcp.js.map +1 -1
- package/dist/otel.d.ts +21 -3
- package/dist/otel.js +232 -12
- package/dist/otel.js.map +1 -1
- package/dist/stdio.d.ts +2 -2
- package/dist/stdio.js +2 -2
- package/dist/testing.d.ts +1 -1
- package/dist/testing.js +3 -2
- package/dist/testing.js.map +1 -1
- package/dist/{trajectory-cSLNlHzh.d.ts → trajectory-ByoOQZ6T.d.ts} +10 -10
- package/dist/trajectory-D1eq9eue.js +81 -0
- package/dist/trajectory-D1eq9eue.js.map +1 -0
- package/dist/{types-BCtKsxrX.d.ts → types-BK0UW28o.d.ts} +3 -3
- package/dist/{types-CXBB4aIM.d.ts → types-CLigYA62.d.ts} +30 -4
- package/dist/{types-BqUY6nRX.d.ts → types-DBpU27sQ.d.ts} +7 -2
- package/dist/ui.d.ts +1 -1
- package/dist/ui.js +1 -1
- package/dist/ui.js.map +1 -1
- package/dist/viewer.d.ts +8 -8
- package/dist/viewer.js +16 -15
- package/dist/viewer.js.map +1 -1
- package/package.json +10 -5
- package/dist/adapters-hmnJOOgf.js.map +0 -1
- package/dist/core-DDRhHu5P.js.map +0 -1
- 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 =
|
|
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
|
|
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
|
|
1035
|
-
*
|
|
1036
|
-
*
|
|
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
|
-
|
|
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
|
|
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
|
|
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(
|
|
1735
|
+
function next_id$2() {
|
|
2000
1736
|
loop_counter += 1;
|
|
2001
|
-
return
|
|
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(
|
|
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(
|
|
2073
|
-
* `name`. The inner step's own span (
|
|
2074
|
-
* the compose span: the implementation tree is preserved while
|
|
2075
|
-
* intent ("this whole thing is an ensemble") is surfaced in
|
|
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'
|
|
2082
|
-
* in `config.display_name
|
|
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
|
|
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(
|
|
1827
|
+
function next_id$1() {
|
|
2090
1828
|
compose_counter += 1;
|
|
2091
|
-
return
|
|
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(
|
|
2101
|
-
|
|
2102
|
-
|
|
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
|
|
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
|
|
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
|
-
*
|
|
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
|
|
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
|
|
2563
|
-
const
|
|
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 {
|
|
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-
|
|
2386
|
+
//# sourceMappingURL=core-DdJEhyQc.js.map
|