fascicle 0.12.0 → 0.12.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +70 -0
- package/README.md +15 -5
- package/dist/adapters.d.ts +1 -1
- package/dist/agents.d.ts +11 -2
- package/dist/agents.js +63 -20
- package/dist/agents.js.map +1 -1
- package/dist/bin/fascicle-viewer.js +2 -2
- package/dist/{core-BkB2l1-e.js → core-DDRhHu5P.js} +235 -56
- package/dist/core-DDRhHu5P.js.map +1 -0
- package/dist/engine-b4ZH8esY.js +7317 -0
- package/dist/engine-b4ZH8esY.js.map +1 -0
- package/dist/index.d.ts +158 -159
- package/dist/index.js +289 -7797
- package/dist/index.js.map +1 -1
- package/dist/{invoke-JkzNf7-Y.js → invoke-CyKNhvBw.js} +3 -3
- package/dist/{invoke-JkzNf7-Y.js.map → invoke-CyKNhvBw.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/static/viewer.html +2 -1
- package/dist/stdio.d.ts +1 -1
- package/dist/stdio.js +1 -1
- package/dist/testing.d.ts +66 -15
- package/dist/testing.js +199 -34
- package/dist/testing.js.map +1 -1
- package/dist/trajectory-cSLNlHzh.d.ts +114 -0
- package/dist/{types-CVdTBXE_.d.ts → types-BqUY6nRX.d.ts} +14 -2
- package/dist/{types-4l54cexm.d.ts → types-CXBB4aIM.d.ts} +8 -4
- package/dist/ui.d.ts +2 -2
- package/dist/viewer.d.ts +117 -0
- package/dist/viewer.js +658 -0
- package/dist/viewer.js.map +1 -0
- package/package.json +22 -9
- package/dist/core-BkB2l1-e.js.map +0 -1
- package/dist/leading_system-BVtGMweY.js +0 -307
- package/dist/leading_system-BVtGMweY.js.map +0 -1
|
@@ -436,7 +436,7 @@ var aborted_error = class extends Error {
|
|
|
436
436
|
super(message);
|
|
437
437
|
this.name = "aborted_error";
|
|
438
438
|
if (metadata.reason !== void 0) this.reason = metadata.reason;
|
|
439
|
-
this.step_index = metadata.step_index
|
|
439
|
+
if (metadata.step_index !== void 0) this.step_index = metadata.step_index;
|
|
440
440
|
if (metadata.tool_call_in_flight !== void 0) this.tool_call_in_flight = metadata.tool_call_in_flight;
|
|
441
441
|
}
|
|
442
442
|
};
|
|
@@ -452,6 +452,23 @@ var aborted_error = class extends Error {
|
|
|
452
452
|
function is_control_flow_error(err) {
|
|
453
453
|
return err instanceof suspended_error || err instanceof aborted_error;
|
|
454
454
|
}
|
|
455
|
+
/**
|
|
456
|
+
* Read the step-id path off any error that crossed the runner's dispatch.
|
|
457
|
+
*
|
|
458
|
+
* The runner attaches `path` to whatever escapes a step, including
|
|
459
|
+
* user-thrown errors the declared class fields cannot type, so a catch block
|
|
460
|
+
* needs a narrowing read rather than a cast. Returns the ids only when the
|
|
461
|
+
* property is present and well-formed (an all-string array); anything else,
|
|
462
|
+
* including non-object inputs, is `undefined`.
|
|
463
|
+
*/
|
|
464
|
+
function error_path(err) {
|
|
465
|
+
if (err === null || typeof err !== "object") return void 0;
|
|
466
|
+
const path = Reflect.get(err, "path");
|
|
467
|
+
if (!Array.isArray(path)) return void 0;
|
|
468
|
+
const entries = path;
|
|
469
|
+
const ids = entries.filter((v) => typeof v === "string");
|
|
470
|
+
return ids.length === entries.length ? ids : void 0;
|
|
471
|
+
}
|
|
455
472
|
//#endregion
|
|
456
473
|
//#region src/core/streaming.ts
|
|
457
474
|
const STREAMING_HIGH_WATER_MARK = 1e4;
|
|
@@ -630,12 +647,32 @@ function register_traced_kind(kind) {
|
|
|
630
647
|
} catch (err) {
|
|
631
648
|
ctx.trajectory.end_span(span_id, {
|
|
632
649
|
id: flow.id,
|
|
633
|
-
|
|
650
|
+
...error_meta(err)
|
|
634
651
|
});
|
|
635
652
|
throw err;
|
|
636
653
|
}
|
|
637
654
|
});
|
|
638
655
|
}
|
|
656
|
+
/**
|
|
657
|
+
* Project an escaping error onto trajectory meta fields.
|
|
658
|
+
*
|
|
659
|
+
* `error` is always present (the message); `error_name` and `error_kind`
|
|
660
|
+
* surface the class name and the `kind` discriminant the typed error classes
|
|
661
|
+
* carry, so a consumer can classify a failure without regex-matching the
|
|
662
|
+
* message. `error_path` is the chain of step ids the error crossed below this
|
|
663
|
+
* point, already accumulated on the error by `prepend_path` as it bubbled up.
|
|
664
|
+
*/
|
|
665
|
+
function error_meta(err) {
|
|
666
|
+
const meta = { error: err instanceof Error ? err.message : String(err) };
|
|
667
|
+
if (err instanceof Error && err.name.length > 0) meta["error_name"] = err.name;
|
|
668
|
+
if (err !== null && typeof err === "object") {
|
|
669
|
+
const kind = Reflect.get(err, "kind");
|
|
670
|
+
if (typeof kind === "string") meta["error_kind"] = kind;
|
|
671
|
+
const path = Reflect.get(err, "path");
|
|
672
|
+
if (Array.isArray(path)) meta["error_path"] = path.filter((v) => typeof v === "string");
|
|
673
|
+
}
|
|
674
|
+
return meta;
|
|
675
|
+
}
|
|
639
676
|
const active_runs = /* @__PURE__ */ new Set();
|
|
640
677
|
let signal_handler_installed = false;
|
|
641
678
|
let sigint_handler = null;
|
|
@@ -848,19 +885,27 @@ function start_run(flow, input, options, high_water_mark) {
|
|
|
848
885
|
active_runs.add(controller);
|
|
849
886
|
if (install_signal_handlers) ensure_signal_handlers();
|
|
850
887
|
const result = (async () => {
|
|
888
|
+
let terminal = {
|
|
889
|
+
kind: "run_end",
|
|
890
|
+
status: "done"
|
|
891
|
+
};
|
|
851
892
|
try {
|
|
852
893
|
throw_if_aborted(ctx);
|
|
853
894
|
return await dispatch_step(flow, input, ctx);
|
|
854
895
|
} catch (err) {
|
|
896
|
+
let thrown = err;
|
|
855
897
|
if (controller.signal.aborted && !(err instanceof aborted_error)) {
|
|
856
898
|
const reason = controller.signal.reason;
|
|
857
|
-
if (reason instanceof aborted_error)
|
|
899
|
+
if (reason instanceof aborted_error) thrown = reason;
|
|
858
900
|
}
|
|
859
|
-
|
|
901
|
+
const was_aborted = thrown instanceof aborted_error || controller.signal.aborted && thrown === controller.signal.reason;
|
|
902
|
+
terminal = run_end_event(thrown, was_aborted);
|
|
903
|
+
throw thrown;
|
|
860
904
|
} finally {
|
|
861
905
|
try {
|
|
862
906
|
await cleanup.run_all();
|
|
863
907
|
} finally {
|
|
908
|
+
logger.record(terminal);
|
|
864
909
|
unlink_abort();
|
|
865
910
|
active_runs.delete(controller);
|
|
866
911
|
release_signal_handlers();
|
|
@@ -874,6 +919,30 @@ function start_run(flow, input, options, high_water_mark) {
|
|
|
874
919
|
};
|
|
875
920
|
}
|
|
876
921
|
/**
|
|
922
|
+
* Build the terminal `run_end` event for a run that did not complete.
|
|
923
|
+
*
|
|
924
|
+
* Control-flow endings get their own statuses (`aborted`, `suspended`) so a
|
|
925
|
+
* consumer never has to sniff error text to tell a cancellation or a pending
|
|
926
|
+
* approval from a real failure; only `failed` carries the full error meta.
|
|
927
|
+
*/
|
|
928
|
+
function run_end_event(err, was_aborted) {
|
|
929
|
+
if (err instanceof suspended_error) return {
|
|
930
|
+
kind: "run_end",
|
|
931
|
+
status: "suspended",
|
|
932
|
+
suspend_id: err.suspend_id
|
|
933
|
+
};
|
|
934
|
+
if (was_aborted) return {
|
|
935
|
+
kind: "run_end",
|
|
936
|
+
status: "aborted",
|
|
937
|
+
error: err instanceof Error ? err.message : String(err)
|
|
938
|
+
};
|
|
939
|
+
return {
|
|
940
|
+
kind: "run_end",
|
|
941
|
+
status: "failed",
|
|
942
|
+
...error_meta(err)
|
|
943
|
+
};
|
|
944
|
+
}
|
|
945
|
+
/**
|
|
877
946
|
* Build an async iterable that is immediately done.
|
|
878
947
|
*
|
|
879
948
|
* Non-streaming runs hand this to callers so the `events` field always has
|
|
@@ -909,8 +978,9 @@ function run_stream(flow, input, options = {}) {
|
|
|
909
978
|
* thrown `suspended_error`.
|
|
910
979
|
*
|
|
911
980
|
* Resolves `{ kind: 'done', output }` on completion. When a `suspend` gate
|
|
912
|
-
* fires, resolves `{ kind: 'suspended', id, resume }` where `id` is
|
|
913
|
-
* gate's suspend id
|
|
981
|
+
* fires, resolves `{ kind: 'suspended', id, payload, resume }` where `id` is
|
|
982
|
+
* the gate's suspend id, `payload` is what the gate raised on its
|
|
983
|
+
* `suspended_error`, and `resume(data)` re-runs the flow from the original
|
|
914
984
|
* input with `resume_data[id] = data` merged over the caller's options: the
|
|
915
985
|
* same full re-run semantics as calling `run` again yourself, so pure
|
|
916
986
|
* prefixes replay and `checkpoint`ed steps are served from the store. The
|
|
@@ -930,6 +1000,7 @@ async function run_until_suspended(flow, input, options = {}) {
|
|
|
930
1000
|
return {
|
|
931
1001
|
kind: "suspended",
|
|
932
1002
|
id,
|
|
1003
|
+
payload: err.payload,
|
|
933
1004
|
resume: (data) => run_until_suspended(flow, input, {
|
|
934
1005
|
...options,
|
|
935
1006
|
resume_data: {
|
|
@@ -963,22 +1034,22 @@ const run = Object.assign(run_impl, {
|
|
|
963
1034
|
* step(id, fn, meta): named step with optional human-readable metadata for studio,
|
|
964
1035
|
* codegen, and similar consumers. `meta` is purely descriptive
|
|
965
1036
|
* and never affects runtime semantics.
|
|
966
|
-
* step(fn): anonymous step. id is `
|
|
1037
|
+
* step(fn): anonymous step. id is `step_<counter>`; cannot be checkpointed.
|
|
967
1038
|
*
|
|
968
1039
|
* Anonymous steps carry an internal `anonymous: true` flag so checkpoint can
|
|
969
1040
|
* reject them synchronously at flow construction time.
|
|
970
1041
|
*/
|
|
971
|
-
let
|
|
1042
|
+
let step_counter = 0;
|
|
972
1043
|
/**
|
|
973
|
-
* Generate a unique id of the form `
|
|
1044
|
+
* Generate a unique id of the form `step_<n>` for anonymous steps.
|
|
974
1045
|
*/
|
|
975
|
-
function
|
|
976
|
-
|
|
977
|
-
return `
|
|
1046
|
+
function next_step_id() {
|
|
1047
|
+
step_counter += 1;
|
|
1048
|
+
return `step_${step_counter}`;
|
|
978
1049
|
}
|
|
979
1050
|
function step(id_or_fn, maybe_fn, meta) {
|
|
980
1051
|
if (typeof id_or_fn === "function") return {
|
|
981
|
-
id:
|
|
1052
|
+
id: next_step_id(),
|
|
982
1053
|
kind: "step",
|
|
983
1054
|
run: id_or_fn,
|
|
984
1055
|
anonymous: true
|
|
@@ -1261,9 +1332,14 @@ function is_renderable_object(value) {
|
|
|
1261
1332
|
*
|
|
1262
1333
|
* For a literal tuple of children, every joint is checked at compile time:
|
|
1263
1334
|
* each child after the first must accept its predecessor's output, and a
|
|
1264
|
-
* mismatch
|
|
1265
|
-
*
|
|
1266
|
-
*
|
|
1335
|
+
* mismatch resolves the offending element to a branded SequenceJointMismatch
|
|
1336
|
+
* so the error names the joint and both types. A spread segment inside a
|
|
1337
|
+
* tuple (`sequence([first, ...mids, last])`) is checked as a homogeneous
|
|
1338
|
+
* self-composing segment rather than index-zipped, since its positions are
|
|
1339
|
+
* not statically known. Arrays built at runtime carry no positional types,
|
|
1340
|
+
* so they must be homogeneous `ReadonlyArray<Step<T, T>>` and produce a
|
|
1341
|
+
* `Step<T, T>`; heterogeneous runtime arrays are rejected rather than
|
|
1342
|
+
* silently degrading to `Step<unknown, unknown>`.
|
|
1267
1343
|
*/
|
|
1268
1344
|
let sequence_counter = 0;
|
|
1269
1345
|
/**
|
|
@@ -1273,17 +1349,6 @@ function next_id$10() {
|
|
|
1273
1349
|
sequence_counter += 1;
|
|
1274
1350
|
return `sequence_${sequence_counter}`;
|
|
1275
1351
|
}
|
|
1276
|
-
/**
|
|
1277
|
-
* Build a step that chains children, each feeding the next.
|
|
1278
|
-
*
|
|
1279
|
-
* The children parameter is checked joint by joint for literal tuples via
|
|
1280
|
-
* `CheckedChildren`; the intersection with the bare `children` parameter is
|
|
1281
|
-
* what lets inference read the precise tuple while the checked shape
|
|
1282
|
-
* constrains it. Validates every element up front so a non-Step (usually a
|
|
1283
|
-
* bare function) fails at construction with a pointed message rather than at
|
|
1284
|
-
* run time. Checks `ctx.abort` before each child so aborts land on step
|
|
1285
|
-
* boundaries.
|
|
1286
|
-
*/
|
|
1287
1352
|
function sequence(children, options) {
|
|
1288
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])`);
|
|
1289
1354
|
children.forEach((child, index) => {
|
|
@@ -1721,6 +1786,7 @@ function to_abort_error(reason) {
|
|
|
1721
1786
|
* control-flow signals propagate untouched.
|
|
1722
1787
|
*/
|
|
1723
1788
|
function retry(inner, config) {
|
|
1789
|
+
if (!Number.isFinite(config.max_attempts)) throw new TypeError(`retry: max_attempts must be a finite number, got ${config.max_attempts}`);
|
|
1724
1790
|
const id = next_id$5();
|
|
1725
1791
|
const max_attempts = Math.max(1, Math.floor(config.max_attempts));
|
|
1726
1792
|
const backoff_ms = config.backoff_ms ?? DEFAULT_BACKOFF_MS;
|
|
@@ -1746,7 +1812,7 @@ function retry(inner, config) {
|
|
|
1746
1812
|
await wait_with_abort(compute_backoff(backoff_policy, attempt - 1), ctx.abort, to_abort_error);
|
|
1747
1813
|
}
|
|
1748
1814
|
}
|
|
1749
|
-
throw last_err;
|
|
1815
|
+
throw last_err ?? /* @__PURE__ */ new Error("retry: no attempts executed");
|
|
1750
1816
|
};
|
|
1751
1817
|
const config_meta = {
|
|
1752
1818
|
max_attempts,
|
|
@@ -1773,7 +1839,9 @@ register_traced_kind("retry");
|
|
|
1773
1839
|
* `fallback(primary, backup)` runs `primary`. If it throws an application
|
|
1774
1840
|
* error, runs `backup` with the same input, or with `handoff(input, err)`
|
|
1775
1841
|
* when the `handoff` option is set, so the backup can be told why it is
|
|
1776
|
-
* running. If `backup` also throws, the `backup` error propagates
|
|
1842
|
+
* running. If `backup` also throws, the `backup` error propagates with the
|
|
1843
|
+
* primary's error attached as its `cause` (unless it already carries one),
|
|
1844
|
+
* so the original failure stays diagnosable from the escaping error.
|
|
1777
1845
|
* Control-flow signals (`suspended_error`, `aborted_error`) are not
|
|
1778
1846
|
* failures: they propagate instead of triggering the backup, so a
|
|
1779
1847
|
* human-approval gate is never silently bypassed and the backup never runs
|
|
@@ -1802,7 +1870,13 @@ function fallback(primary, backup, options) {
|
|
|
1802
1870
|
return await dispatch_step(primary, input, ctx);
|
|
1803
1871
|
} catch (err) {
|
|
1804
1872
|
if (is_control_flow_error(err)) throw err;
|
|
1805
|
-
|
|
1873
|
+
const backup_input = handoff === void 0 ? input : handoff(input, err);
|
|
1874
|
+
try {
|
|
1875
|
+
return await dispatch_step(backup, backup_input, ctx);
|
|
1876
|
+
} catch (backup_err) {
|
|
1877
|
+
if (!is_control_flow_error(backup_err) && backup_err instanceof Error && !("cause" in backup_err)) backup_err.cause = err;
|
|
1878
|
+
throw backup_err;
|
|
1879
|
+
}
|
|
1806
1880
|
}
|
|
1807
1881
|
};
|
|
1808
1882
|
const config_meta = options?.name === void 0 ? void 0 : { display_name: options.name };
|
|
@@ -1900,7 +1974,9 @@ register_traced_kind("timeout");
|
|
|
1900
1974
|
* `loop({ init, body, guard?, finish, max_rounds, name? })` runs `body` up to
|
|
1901
1975
|
* `max_rounds` times, threading `state` through each iteration. After every
|
|
1902
1976
|
* `body` call, an optional `guard` step inspects (and may transform) the state
|
|
1903
|
-
* and decides whether to stop
|
|
1977
|
+
* and decides whether to stop; a bare `(state) => boolean` predicate is
|
|
1978
|
+
* accepted as shorthand for a guard that stops without transforming.
|
|
1979
|
+
* When `guard.stop` is true, the loop exits
|
|
1904
1980
|
* "converged"; otherwise it continues until `max_rounds`. `finish` projects
|
|
1905
1981
|
* the final state to the loop's output value, and is the loop's only output
|
|
1906
1982
|
* channel: `loop` returns `Step<i, o>`, not an envelope around `o`.
|
|
@@ -1925,6 +2001,22 @@ function next_id$2(name) {
|
|
|
1925
2001
|
return `${name ?? "loop"}_${loop_counter}`;
|
|
1926
2002
|
}
|
|
1927
2003
|
/**
|
|
2004
|
+
* Normalize the guard config to its step form.
|
|
2005
|
+
*
|
|
2006
|
+
* A bare predicate is sugar for the state-preserving guard step, wrapped here
|
|
2007
|
+
* (with an id derived from the loop's, so trees with several loops stay
|
|
2008
|
+
* unambiguous) rather than special-cased in the run loop: the predicate form
|
|
2009
|
+
* then dispatches, traces, and terminates identically to a hand-written guard.
|
|
2010
|
+
*/
|
|
2011
|
+
function wrap_guard(guard, loop_id) {
|
|
2012
|
+
if (guard === void 0) return void 0;
|
|
2013
|
+
if (typeof guard !== "function") return guard;
|
|
2014
|
+
return step(`${loop_id}_guard`, async (state) => ({
|
|
2015
|
+
stop: await guard(state),
|
|
2016
|
+
state
|
|
2017
|
+
}));
|
|
2018
|
+
}
|
|
2019
|
+
/**
|
|
1928
2020
|
* Build a bounded iteration step with carry-state.
|
|
1929
2021
|
*
|
|
1930
2022
|
* Threads `state` through up to `max_rounds` runs of `body`, lets the
|
|
@@ -1934,9 +2026,10 @@ function next_id$2(name) {
|
|
|
1934
2026
|
* its output.
|
|
1935
2027
|
*/
|
|
1936
2028
|
function loop(config) {
|
|
1937
|
-
const { init, body,
|
|
2029
|
+
const { init, body, finish, name } = config;
|
|
1938
2030
|
const rounds_limit = Math.max(1, Math.floor(config.max_rounds));
|
|
1939
2031
|
const id = next_id$2(name);
|
|
2032
|
+
const guard = wrap_guard(config.guard, id);
|
|
1940
2033
|
const run_fn = async (input, ctx) => {
|
|
1941
2034
|
let state = init(input);
|
|
1942
2035
|
let round = 0;
|
|
@@ -2025,7 +2118,9 @@ register_traced_kind("compose");
|
|
|
2025
2118
|
* `checkpoint(inner, { key })` checks a persistent store for a completed
|
|
2026
2119
|
* result at `key` before running `inner`. On a hit, returns the stored
|
|
2027
2120
|
* value. On a miss, runs `inner`, persists its result at `key`, and returns
|
|
2028
|
-
* it. Corrupted reads (store throws on `get`) are treated as a miss.
|
|
2121
|
+
* it. Corrupted reads (store throws on `get`) are treated as a miss. Every
|
|
2122
|
+
* lookup records a `checkpoint` trajectory event with
|
|
2123
|
+
* `status: 'hit' | 'miss' | 'read_error'`.
|
|
2029
2124
|
*
|
|
2030
2125
|
* Wrapping an anonymous inner step throws synchronously at construction time
|
|
2031
2126
|
* with the message `checkpoint requires a named step; got anonymous`, because
|
|
@@ -2058,11 +2153,27 @@ function checkpoint(inner, config) {
|
|
|
2058
2153
|
if (store) {
|
|
2059
2154
|
let cached = void 0;
|
|
2060
2155
|
let hit = false;
|
|
2156
|
+
const lookup_meta = {
|
|
2157
|
+
id,
|
|
2158
|
+
key
|
|
2159
|
+
};
|
|
2160
|
+
if (ctx.parent_span_id !== void 0) lookup_meta["span_id"] = ctx.parent_span_id;
|
|
2061
2161
|
try {
|
|
2062
2162
|
cached = await store.get(key);
|
|
2063
2163
|
hit = cached !== null && cached !== void 0;
|
|
2064
|
-
|
|
2164
|
+
ctx.trajectory.record({
|
|
2165
|
+
kind: "checkpoint",
|
|
2166
|
+
status: hit ? "hit" : "miss",
|
|
2167
|
+
...lookup_meta
|
|
2168
|
+
});
|
|
2169
|
+
} catch (err) {
|
|
2065
2170
|
hit = false;
|
|
2171
|
+
ctx.trajectory.record({
|
|
2172
|
+
kind: "checkpoint",
|
|
2173
|
+
status: "read_error",
|
|
2174
|
+
error: err instanceof Error ? err.message : String(err),
|
|
2175
|
+
...lookup_meta
|
|
2176
|
+
});
|
|
2066
2177
|
}
|
|
2067
2178
|
if (hit) return cached;
|
|
2068
2179
|
}
|
|
@@ -2325,21 +2436,26 @@ register_traced_kind("use");
|
|
|
2325
2436
|
* chain: named steps over a growing record.
|
|
2326
2437
|
*
|
|
2327
2438
|
* `chain<i>(input_name?)` opens a builder whose threaded value is a record of
|
|
2328
|
-
* named outputs rather than a single value.
|
|
2329
|
-
* the
|
|
2330
|
-
*
|
|
2331
|
-
*
|
|
2332
|
-
*
|
|
2333
|
-
*
|
|
2439
|
+
* named outputs rather than a single value. The input type must be stated,
|
|
2440
|
+
* either as the type argument or via `.input<t>()` on the freshly opened
|
|
2441
|
+
* chain; an unannotated `chain()` defaults to `never` so the omission fails
|
|
2442
|
+
* at the `run` call site instead of accepting anything. `.step(name, fn)`
|
|
2443
|
+
* runs `fn` over the record and merges its output back in under `name`;
|
|
2444
|
+
* `.stage(name, project?)` concludes a phase: it opens a grouping span in
|
|
2445
|
+
* the trajectory and, when `project` is given, replaces the record with the
|
|
2446
|
+
* projection so earlier bindings go out of scope; `.output(fn)` closes the
|
|
2447
|
+
* builder and returns an ordinary `Step<i, o>`.
|
|
2334
2448
|
*
|
|
2335
2449
|
* Each `.step` entry is a regular `step(name, fn)` whose input happens to be
|
|
2336
2450
|
* the record, so anything true of steps (spans, error paths, abort checks
|
|
2337
2451
|
* between entries) is true of chain entries, and the binding name doubles as
|
|
2338
|
-
* the entry's id in trajectories.
|
|
2339
|
-
*
|
|
2340
|
-
*
|
|
2341
|
-
* binding's child so `describe` renders
|
|
2342
|
-
*
|
|
2452
|
+
* the entry's id in trajectories. A binding whose whole job is to invoke an
|
|
2453
|
+
* arm is `.step(name, arm, select)`: the chain projects the record through
|
|
2454
|
+
* `select`, dispatches the arm via `ctx.call`, and records it as the
|
|
2455
|
+
* binding's child, so what `describe` renders and what runs cannot diverge.
|
|
2456
|
+
* The escape hatch for bodies that need code around the call is
|
|
2457
|
+
* `.step(name, fn, { arm })`: the body does its own `ctx.call` and the arm
|
|
2458
|
+
* is metadata only, recorded for `describe` but never dispatched.
|
|
2343
2459
|
*
|
|
2344
2460
|
* Builder values are immutable: every method returns a new chain, so a
|
|
2345
2461
|
* prefix can be shared and extended in different directions safely.
|
|
@@ -2425,6 +2541,32 @@ function build_chain(input_name, entries, output_node) {
|
|
|
2425
2541
|
};
|
|
2426
2542
|
}
|
|
2427
2543
|
/**
|
|
2544
|
+
* Build the binding node for the arm-first `.step(name, arm, select)` form.
|
|
2545
|
+
*
|
|
2546
|
+
* The chain owns the dispatch: the synthesized body projects the record
|
|
2547
|
+
* through `select` and hands the result to the arm via `ctx.call`, and the
|
|
2548
|
+
* same arm is recorded as the binding's child, so the subtree `describe`
|
|
2549
|
+
* renders and the step that runs are one value by construction.
|
|
2550
|
+
*/
|
|
2551
|
+
function arm_node(name, arm, select) {
|
|
2552
|
+
if (typeof select !== "function") throw new TypeError("chain.step(name, arm, select): select must be a function");
|
|
2553
|
+
return {
|
|
2554
|
+
...step(name, (s, ctx) => ctx.call(arm, select(s))),
|
|
2555
|
+
children: [arm]
|
|
2556
|
+
};
|
|
2557
|
+
}
|
|
2558
|
+
/**
|
|
2559
|
+
* Build the binding node for the body form `.step(name, fn, { arm? })`.
|
|
2560
|
+
*/
|
|
2561
|
+
function body_node(name, fn, options) {
|
|
2562
|
+
const base = step(name, fn);
|
|
2563
|
+
const arm = typeof options === "function" ? void 0 : options?.arm;
|
|
2564
|
+
return arm === void 0 ? base : {
|
|
2565
|
+
...base,
|
|
2566
|
+
children: [arm]
|
|
2567
|
+
};
|
|
2568
|
+
}
|
|
2569
|
+
/**
|
|
2428
2570
|
* Internal untyped builder behind `chain`.
|
|
2429
2571
|
*
|
|
2430
2572
|
* `bound` holds the binding names of the current stage segment so duplicate
|
|
@@ -2434,13 +2576,9 @@ function build_chain(input_name, entries, output_node) {
|
|
|
2434
2576
|
*/
|
|
2435
2577
|
function make_chain(input_name, entries, bound) {
|
|
2436
2578
|
return {
|
|
2437
|
-
step: (name,
|
|
2579
|
+
step: (name, fn_or_arm, options_or_select) => {
|
|
2438
2580
|
if (bound.has(name)) throw new TypeError(`chain.step: binding '${name}' is already defined in this stage; names are single-assignment`);
|
|
2439
|
-
const
|
|
2440
|
-
const node = options?.arm === void 0 ? base : {
|
|
2441
|
-
...base,
|
|
2442
|
-
children: [options.arm]
|
|
2443
|
-
};
|
|
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);
|
|
2444
2582
|
return make_chain(input_name, [...entries, {
|
|
2445
2583
|
kind: "step",
|
|
2446
2584
|
name,
|
|
@@ -2461,15 +2599,22 @@ function make_chain(input_name, entries, bound) {
|
|
|
2461
2599
|
/**
|
|
2462
2600
|
* Open a chain builder whose record starts as `{ [input_name]: input }`.
|
|
2463
2601
|
*
|
|
2464
|
-
* `input_name` defaults to `'input'`. The
|
|
2465
|
-
*
|
|
2602
|
+
* `input_name` defaults to `'input'`. The input type defaults to `never`, so
|
|
2603
|
+
* a chain that never states it produces a `Step<never, o>` that no real
|
|
2604
|
+
* input satisfies at `run`; state it as the type argument or, when the
|
|
2605
|
+
* binding is renamed, once via `.input<t>()` on the fresh builder. Each
|
|
2606
|
+
* `.step` narrows subsequent callbacks to the record accumulated so far, and
|
|
2466
2607
|
* `.stage` with a projection re-types the record to the projection's
|
|
2467
2608
|
* return, so binding names and views are checked at compile time with no
|
|
2468
2609
|
* declared state shape.
|
|
2469
2610
|
*/
|
|
2470
2611
|
function chain(input_name) {
|
|
2471
2612
|
const name = input_name ?? "input";
|
|
2472
|
-
|
|
2613
|
+
const open = make_chain(name, [], /* @__PURE__ */ new Set([name]));
|
|
2614
|
+
return {
|
|
2615
|
+
...open,
|
|
2616
|
+
input: () => open
|
|
2617
|
+
};
|
|
2473
2618
|
}
|
|
2474
2619
|
register_traced_kind("chain");
|
|
2475
2620
|
//#endregion
|
|
@@ -2540,6 +2685,40 @@ function is_span_end_event(value) {
|
|
|
2540
2685
|
function is_emit_event(value) {
|
|
2541
2686
|
return is_custom_trajectory_event(value) && value.kind === "emit";
|
|
2542
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
|
+
}
|
|
2543
2722
|
/**
|
|
2544
2723
|
* Parse one wire value into a trajectory event, `safeParse`-shaped.
|
|
2545
2724
|
*
|
|
@@ -2568,6 +2747,6 @@ function parse_trajectory_event(value) {
|
|
|
2568
2747
|
* and surface through the umbrella package.
|
|
2569
2748
|
*/
|
|
2570
2749
|
//#endregion
|
|
2571
|
-
export {
|
|
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 };
|
|
2572
2751
|
|
|
2573
|
-
//# sourceMappingURL=core-
|
|
2752
|
+
//# sourceMappingURL=core-DDRhHu5P.js.map
|