fascicle 0.15.0 → 0.16.0
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 +114 -0
- package/README.md +8 -8
- package/dist/acp.d.ts +9 -2
- package/dist/acp.js +1538 -1472
- package/dist/acp.js.map +1 -1
- package/dist/{adapters-DNnzeLxr.js → adapters-CDUzZlby.js} +35 -13
- package/dist/adapters-CDUzZlby.js.map +1 -0
- package/dist/adapters.d.ts +8 -1
- package/dist/adapters.js +1 -1
- package/dist/agents.d.ts +1 -1
- package/dist/agents.js +15 -8
- package/dist/agents.js.map +1 -1
- package/dist/bin/fascicle-viewer.js +4 -1
- package/dist/console-CdB4pcFO.js +37 -0
- package/dist/console-CdB4pcFO.js.map +1 -0
- package/dist/{core-CDrz0NM1.js → core-CErsxGF6.js} +246 -147
- package/dist/core-CErsxGF6.js.map +1 -0
- package/dist/diagram_bin.js +2 -2
- package/dist/diagram_bin.js.map +1 -1
- package/dist/{engine-ha9xmgwE.js → engine-CR8q2IqV.js} +173 -67
- package/dist/engine-CR8q2IqV.js.map +1 -0
- package/dist/index.d.ts +529 -73
- package/dist/index.js +440 -137
- package/dist/index.js.map +1 -1
- package/dist/{invoke-px31fffH.js → invoke-COaeZ-vy.js} +6 -5
- package/dist/invoke-COaeZ-vy.js.map +1 -0
- package/dist/{json_schema_to_standard-BTWD0J6p.js → json_schema_to_standard-C4F4lXHE.js} +9 -12
- package/dist/json_schema_to_standard-C4F4lXHE.js.map +1 -0
- package/dist/{leading_system-DfJLqpGi.js → leading_system-PoHzNHuV.js} +28 -8
- package/dist/leading_system-PoHzNHuV.js.map +1 -0
- package/dist/mcp.d.ts +3 -2
- package/dist/mcp.js +8 -4
- package/dist/mcp.js.map +1 -1
- package/dist/otel.js +10 -10
- package/dist/otel.js.map +1 -1
- package/dist/{search-CA_OqFeW.js → search-CpCJYMUm.js} +53 -6
- package/dist/search-CpCJYMUm.js.map +1 -0
- package/dist/search_worker.js +1 -1
- package/dist/stdio.js +7 -3
- package/dist/stdio.js.map +1 -1
- package/dist/testing.d.ts +1 -1
- package/dist/testing.js +3 -3
- package/dist/testing.js.map +1 -1
- package/dist/{trajectory-Bm-mOtqw.d.ts → trajectory-BKGNxi7u.d.ts} +10 -9
- package/dist/{trajectory-BI-mrVFT.js → trajectory-DeURWIhj.js} +6 -5
- package/dist/trajectory-DeURWIhj.js.map +1 -0
- package/dist/{types-De-TVQxS.d.ts → types-Sw0oHW-_.d.ts} +6 -7
- package/dist/ui.d.ts +2 -1
- package/dist/ui.js +8 -1
- package/dist/ui.js.map +1 -1
- package/dist/viewer-app/assets/index-BYF5Dp7d.js +2 -0
- package/dist/viewer-app/index.html +2 -1
- package/dist/viewer.d.ts +26 -12
- package/dist/viewer.js +282 -63
- package/dist/viewer.js.map +1 -1
- package/package.json +4 -4
- package/dist/adapters-DNnzeLxr.js.map +0 -1
- package/dist/core-CDrz0NM1.js.map +0 -1
- package/dist/engine-ha9xmgwE.js.map +0 -1
- package/dist/invoke-px31fffH.js.map +0 -1
- package/dist/json_schema_to_standard-BTWD0J6p.js.map +0 -1
- package/dist/leading_system-DfJLqpGi.js.map +0 -1
- package/dist/search-CA_OqFeW.js.map +0 -1
- package/dist/trajectory-BI-mrVFT.js.map +0 -1
- package/dist/viewer-app/assets/index-Fnh5HKSU.js +0 -2
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { n as is_record } from "./records-1HU7mWXf.js";
|
|
1
2
|
import { createHash, randomUUID } from "node:crypto";
|
|
2
3
|
//#region src/core/cleanup.ts
|
|
3
4
|
const HANDLER_TIMEOUT_MS = 5e3;
|
|
@@ -98,12 +99,12 @@ function description_meta(description) {
|
|
|
98
99
|
/**
|
|
99
100
|
* Closed registry of every `Step.kind` produced by the composition layer.
|
|
100
101
|
*
|
|
101
|
-
*
|
|
102
|
-
* docs, code generation) can rely on this being the exhaustive set. New
|
|
102
|
+
* The viewer (and any other consumer that needs to enumerate primitives:
|
|
103
|
+
* palette, docs, code generation) can rely on this being the exhaustive set. New
|
|
103
104
|
* primitives must add their kind here. `step_kinds.test.ts` pins the list
|
|
104
|
-
* against the kinds core actually constructs,
|
|
105
|
-
*
|
|
106
|
-
*
|
|
105
|
+
* against the kinds core actually constructs, in both directions. The
|
|
106
|
+
* composites (`ensemble`, `tournament`, and the rest) add no kinds of their
|
|
107
|
+
* own: each builds a `compose` step that carries its name as the display name.
|
|
107
108
|
*/
|
|
108
109
|
const STEP_KINDS = [
|
|
109
110
|
"step",
|
|
@@ -117,10 +118,6 @@ const STEP_KINDS = [
|
|
|
117
118
|
"timeout",
|
|
118
119
|
"loop",
|
|
119
120
|
"compose",
|
|
120
|
-
"adversarial",
|
|
121
|
-
"ensemble",
|
|
122
|
-
"tournament",
|
|
123
|
-
"consensus",
|
|
124
121
|
"checkpoint",
|
|
125
122
|
"suspend",
|
|
126
123
|
"scope",
|
|
@@ -575,7 +572,7 @@ function is_step(value) {
|
|
|
575
572
|
* place of the config line, rather than again among the children.
|
|
576
573
|
*
|
|
577
574
|
* `describe.json(step)` returns a `FlowNode` tree (kind, id, config, children)
|
|
578
|
-
* for tooling (
|
|
575
|
+
* for tooling (the viewer, Mermaid renderers, diff tools). Function values
|
|
579
576
|
* serialize as `{ kind: '<fn>', name? }` and schemas as `{ kind: '<schema>' }`.
|
|
580
577
|
*
|
|
581
578
|
* `describe.diagram(step)` draws the `describe.json` tree as an annotated
|
|
@@ -585,8 +582,9 @@ function is_step(value) {
|
|
|
585
582
|
* `side_effect` that a resumed run can run again before it reaches a gate
|
|
586
583
|
* (see replays.ts).
|
|
587
584
|
*
|
|
588
|
-
*
|
|
589
|
-
*
|
|
585
|
+
* Every form detects cycles, since the diagram and the replay hints read the
|
|
586
|
+
* `describe.json` tree. Under the default (loose) mode, back-references render
|
|
587
|
+
* as `<cycle>(id)` in text and `{ kind: '<cycle>', id }` in JSON. Under
|
|
590
588
|
* `{ strict: true }`, cycles throw `describe_cycle_error`.
|
|
591
589
|
*/
|
|
592
590
|
const INDENT = " ";
|
|
@@ -955,13 +953,18 @@ function create_streaming_channel(base, high_water_mark = STREAMING_HIGH_WATER_M
|
|
|
955
953
|
*
|
|
956
954
|
* Dispatches a step to its kind-specific handler. `runner.ts` contains no
|
|
957
955
|
* composer-specific logic beyond a Map lookup on `step.kind`; each composer
|
|
958
|
-
* file registers its handler at module load via `
|
|
956
|
+
* file registers its handler at module load via `register_traced_kind(...)`.
|
|
959
957
|
*
|
|
960
958
|
* `run(flow, input, options?)` constructs a fresh `RunContext` per top-level
|
|
961
959
|
* call, installs process signal handlers (opt-out via options), forwards an
|
|
962
960
|
* optional caller-supplied `AbortSignal` into the run, and guarantees cleanup
|
|
963
961
|
* handlers execute in LIFO order on success, failure, or abort.
|
|
964
962
|
*
|
|
963
|
+
* A SIGINT or SIGTERM aborts only the runs that installed the handlers. A run
|
|
964
|
+
* started with `install_signal_handlers: false` keeps going through a signal,
|
|
965
|
+
* even while another run's handlers are installed, because opting out says
|
|
966
|
+
* the host forwards cancellation itself, through `abort`.
|
|
967
|
+
*
|
|
965
968
|
* `run.stream(flow, input, options?)` is a secondary entry point returning
|
|
966
969
|
* `{ events, result }`. Streaming is purely observational; the step graph is
|
|
967
970
|
* identical to `run(...)`.
|
|
@@ -1065,24 +1068,24 @@ function error_meta(err) {
|
|
|
1065
1068
|
}
|
|
1066
1069
|
return meta;
|
|
1067
1070
|
}
|
|
1068
|
-
const
|
|
1071
|
+
const signal_runs = /* @__PURE__ */ new Set();
|
|
1069
1072
|
let signal_handler_installed = false;
|
|
1070
1073
|
let sigint_handler = null;
|
|
1071
1074
|
let sigterm_handler = null;
|
|
1072
1075
|
/**
|
|
1073
|
-
* Build the handler for one process signal: it aborts every
|
|
1074
|
-
* an `aborted_error` that names the signal.
|
|
1076
|
+
* Build the handler for one process signal: it aborts every run that installed
|
|
1077
|
+
* the handlers with an `aborted_error` that names the signal.
|
|
1075
1078
|
*/
|
|
1076
1079
|
function abort_all_on(signal_name) {
|
|
1077
1080
|
return () => {
|
|
1078
|
-
for (const controller of
|
|
1081
|
+
for (const controller of signal_runs) controller.abort(new aborted_error(`received ${signal_name}`, { reason: { signal: signal_name } }));
|
|
1079
1082
|
};
|
|
1080
1083
|
}
|
|
1081
1084
|
/**
|
|
1082
1085
|
* Install process-wide SIGINT/SIGTERM handlers once.
|
|
1083
1086
|
*
|
|
1084
|
-
* The handlers abort every
|
|
1085
|
-
* signal, so a Ctrl-C tears down
|
|
1087
|
+
* The handlers abort every run that installed them with an `aborted_error`
|
|
1088
|
+
* naming the signal, so a Ctrl-C tears down those flows through the normal
|
|
1086
1089
|
* abort/cleanup path instead of killing the process mid-step.
|
|
1087
1090
|
*/
|
|
1088
1091
|
function ensure_signal_handlers() {
|
|
@@ -1094,14 +1097,15 @@ function ensure_signal_handlers() {
|
|
|
1094
1097
|
process.on("SIGTERM", sigterm_handler);
|
|
1095
1098
|
}
|
|
1096
1099
|
/**
|
|
1097
|
-
* Remove the process signal handlers once the last
|
|
1100
|
+
* Remove the process signal handlers once the last run that installed them
|
|
1101
|
+
* settles.
|
|
1098
1102
|
*
|
|
1099
1103
|
* Keeps a library embed from leaving stray `process.on` listeners behind
|
|
1100
1104
|
* after all runs complete.
|
|
1101
1105
|
*/
|
|
1102
1106
|
function release_signal_handlers() {
|
|
1103
1107
|
if (!signal_handler_installed) return;
|
|
1104
|
-
if (
|
|
1108
|
+
if (signal_runs.size > 0) return;
|
|
1105
1109
|
signal_handler_installed = false;
|
|
1106
1110
|
if (sigint_handler) process.off("SIGINT", sigint_handler);
|
|
1107
1111
|
if (sigterm_handler) process.off("SIGTERM", sigterm_handler);
|
|
@@ -1117,7 +1121,7 @@ const noop_logger = {
|
|
|
1117
1121
|
* Wrap a logger so every emitted event automatically carries `run_id` and a
|
|
1118
1122
|
* `ts` (epoch milliseconds) stamped at emission.
|
|
1119
1123
|
*
|
|
1120
|
-
*
|
|
1124
|
+
* The viewer and other downstream consumers multiplex events across runs by
|
|
1121
1125
|
* `run_id` and reconstruct real timing from `ts` instead of fabricating it at
|
|
1122
1126
|
* ingest. Either field already present on an event or its meta is preserved;
|
|
1123
1127
|
* we never overwrite a caller-supplied value.
|
|
@@ -1286,8 +1290,10 @@ function start_run$1(flow, input, options, high_water_mark) {
|
|
|
1286
1290
|
streaming
|
|
1287
1291
|
};
|
|
1288
1292
|
track_resumed_gates(run_id, options.resume_data);
|
|
1289
|
-
|
|
1290
|
-
|
|
1293
|
+
if (install_signal_handlers) {
|
|
1294
|
+
signal_runs.add(controller);
|
|
1295
|
+
ensure_signal_handlers();
|
|
1296
|
+
}
|
|
1291
1297
|
const result = (async () => {
|
|
1292
1298
|
let terminal = {
|
|
1293
1299
|
kind: "run_end",
|
|
@@ -1312,7 +1318,7 @@ function start_run$1(flow, input, options, high_water_mark) {
|
|
|
1312
1318
|
logger.record(terminal);
|
|
1313
1319
|
unreached_gates.delete(run_id);
|
|
1314
1320
|
unlink_abort();
|
|
1315
|
-
|
|
1321
|
+
signal_runs.delete(controller);
|
|
1316
1322
|
release_signal_handlers();
|
|
1317
1323
|
if (close_stream) close_stream();
|
|
1318
1324
|
}
|
|
@@ -1432,6 +1438,63 @@ const run = Object.assign(run_impl, {
|
|
|
1432
1438
|
until_suspended: run_until_suspended
|
|
1433
1439
|
});
|
|
1434
1440
|
//#endregion
|
|
1441
|
+
//#region src/schema/validate.ts
|
|
1442
|
+
/**
|
|
1443
|
+
* Validate `value` against `schema`, returning the typed value or the issues.
|
|
1444
|
+
*
|
|
1445
|
+
* Always async, even for a validator that answers synchronously: the spec
|
|
1446
|
+
* permits `validate` to return either a result or a promise of one, and
|
|
1447
|
+
* Fascicle cannot know which a given vendor does. Awaiting a non-promise is
|
|
1448
|
+
* cheap; guessing wrong is a silent bug.
|
|
1449
|
+
*/
|
|
1450
|
+
async function validate_schema(schema, value) {
|
|
1451
|
+
const result = await schema["~standard"].validate(value);
|
|
1452
|
+
if (result.issues) return {
|
|
1453
|
+
ok: false,
|
|
1454
|
+
issues: result.issues.map(normalize_issue)
|
|
1455
|
+
};
|
|
1456
|
+
return {
|
|
1457
|
+
ok: true,
|
|
1458
|
+
value: result.value
|
|
1459
|
+
};
|
|
1460
|
+
}
|
|
1461
|
+
/**
|
|
1462
|
+
* Flatten one vendor issue into Fascicle's shape.
|
|
1463
|
+
*
|
|
1464
|
+
* The spec allows a path segment to be a bare key or a `{ key }` wrapper, and
|
|
1465
|
+
* allows the path to be absent entirely. Normalizing here means no consumer has
|
|
1466
|
+
* to know which vendor produced the issue.
|
|
1467
|
+
*/
|
|
1468
|
+
function normalize_issue(issue) {
|
|
1469
|
+
if (issue.path === void 0) return { message: issue.message };
|
|
1470
|
+
const path = issue.path.map((segment) => typeof segment === "object" ? segment.key : segment);
|
|
1471
|
+
return {
|
|
1472
|
+
message: issue.message,
|
|
1473
|
+
path
|
|
1474
|
+
};
|
|
1475
|
+
}
|
|
1476
|
+
/**
|
|
1477
|
+
* Render issues as the single line that goes into an error message or a repair
|
|
1478
|
+
* prompt fed back to the model.
|
|
1479
|
+
*
|
|
1480
|
+
* Paths are dotted (`address.city`, `items.0.name`) rather than bracketed for
|
|
1481
|
+
* indices: the model reads it as a hint about which field to fix, and one
|
|
1482
|
+
* consistent separator is easier to follow than two.
|
|
1483
|
+
*/
|
|
1484
|
+
function format_schema_issues(issues) {
|
|
1485
|
+
if (issues.length === 0) return "unknown schema issue";
|
|
1486
|
+
return issues.map(format_issue).join("; ");
|
|
1487
|
+
}
|
|
1488
|
+
/**
|
|
1489
|
+
* Render one issue as `path: message`, or just the message when the vendor
|
|
1490
|
+
* reported no path (a failure about the value as a whole).
|
|
1491
|
+
*/
|
|
1492
|
+
function format_issue(issue) {
|
|
1493
|
+
const path = issue.path;
|
|
1494
|
+
if (path === void 0 || path.length === 0) return issue.message;
|
|
1495
|
+
return `${path.map((segment) => String(segment)).join(".")}: ${issue.message}`;
|
|
1496
|
+
}
|
|
1497
|
+
//#endregion
|
|
1435
1498
|
//#region src/core/durable.ts
|
|
1436
1499
|
/**
|
|
1437
1500
|
* durable: drive a flow that suspends across processes, one event at a time.
|
|
@@ -1498,16 +1561,10 @@ function shape_of(node) {
|
|
|
1498
1561
|
];
|
|
1499
1562
|
}
|
|
1500
1563
|
/**
|
|
1501
|
-
* True for a plain object, the only shape a stored record or entry takes.
|
|
1502
|
-
*/
|
|
1503
|
-
function is_object(value) {
|
|
1504
|
-
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
1505
|
-
}
|
|
1506
|
-
/**
|
|
1507
1564
|
* Read a stored suspension back, or `null` when the value isn't one.
|
|
1508
1565
|
*/
|
|
1509
1566
|
function as_suspension(value) {
|
|
1510
|
-
if (!
|
|
1567
|
+
if (!is_record(value)) return null;
|
|
1511
1568
|
const { id, payload, deadline_at } = value;
|
|
1512
1569
|
if (typeof id !== "string") return null;
|
|
1513
1570
|
return {
|
|
@@ -1522,10 +1579,10 @@ function as_suspension(value) {
|
|
|
1522
1579
|
* the run again from its input, where its checkpoints still serve.
|
|
1523
1580
|
*/
|
|
1524
1581
|
function as_record(value) {
|
|
1525
|
-
if (!
|
|
1582
|
+
if (!is_record(value) || value["format"] !== 1) return void 0;
|
|
1526
1583
|
const { revision, input, flow, resume_data, output, error, status } = value;
|
|
1527
1584
|
if (typeof revision !== "number" || typeof flow !== "string") return void 0;
|
|
1528
|
-
if (!
|
|
1585
|
+
if (!is_record(resume_data) || !STATUSES.has(status)) return void 0;
|
|
1529
1586
|
const base = {
|
|
1530
1587
|
format: 1,
|
|
1531
1588
|
revision,
|
|
@@ -1680,7 +1737,40 @@ async function check_shape(drive, lease, record) {
|
|
|
1680
1737
|
*/
|
|
1681
1738
|
async function read_inbox(scope, gate_id) {
|
|
1682
1739
|
const entry = await scope.scope(INBOX).get(gate_id);
|
|
1683
|
-
return
|
|
1740
|
+
return is_record(entry) && "data" in entry ? { data: entry["data"] } : void 0;
|
|
1741
|
+
}
|
|
1742
|
+
/**
|
|
1743
|
+
* Leave `data` in the run's inbox for `gate_id`, unless a datum already waits
|
|
1744
|
+
* there, another resume is leaving one, the run has already passed the gate,
|
|
1745
|
+
* or the run is gone.
|
|
1746
|
+
*
|
|
1747
|
+
* The reads and the write happen under a claim on the gate's inbox key, so of
|
|
1748
|
+
* two resumes that race for one gate, only the first to claim it writes, and
|
|
1749
|
+
* the other drops its datum as it would on finding one there. The inbox is
|
|
1750
|
+
* read before the record because `take_up` saves a gate's datum into the
|
|
1751
|
+
* record before it deletes the inbox entry, so a datum that's taken up between
|
|
1752
|
+
* the two reads still shows in the record. The claim lasts `lease_ms` and
|
|
1753
|
+
* comes off right after the write.
|
|
1754
|
+
*
|
|
1755
|
+
* Two windows stay open, because the store contract has no compare-and-set to
|
|
1756
|
+
* close them with. A resume that stalls past its claim, after its reads and
|
|
1757
|
+
* before its write, can still write once another resume has moved the run
|
|
1758
|
+
* past the gate. And a `delete` that lands between the record read and the
|
|
1759
|
+
* write leaves the datum in the cleared scope, where a new run under the same
|
|
1760
|
+
* id takes it up.
|
|
1761
|
+
*/
|
|
1762
|
+
async function deliver(drive, gate_id, data) {
|
|
1763
|
+
const key = `${INBOX}/${gate_id}`;
|
|
1764
|
+
const owner = randomUUID();
|
|
1765
|
+
if (!await drive.scope.claim(key, owner, drive.lease_ms)) return;
|
|
1766
|
+
try {
|
|
1767
|
+
if (await read_inbox(drive.scope, gate_id) !== void 0) return;
|
|
1768
|
+
const record = as_record(await drive.scope.get(RECORD));
|
|
1769
|
+
if (record === void 0 || Object.hasOwn(record.resume_data, gate_id)) return;
|
|
1770
|
+
await drive.scope.scope(INBOX).set(gate_id, { data });
|
|
1771
|
+
} finally {
|
|
1772
|
+
await drive.scope.release(key, owner);
|
|
1773
|
+
}
|
|
1684
1774
|
}
|
|
1685
1775
|
/**
|
|
1686
1776
|
* Move the resume data waiting at the run's gate into the run, or resolve
|
|
@@ -1887,21 +1977,28 @@ async function start_run(driver, run_id, flow, input, options) {
|
|
|
1887
1977
|
*
|
|
1888
1978
|
* Each datum is written to the run's inbox before the lease is taken, so a
|
|
1889
1979
|
* call that finds the run busy still leaves its data where the holder takes
|
|
1890
|
-
* it up. Data for a gate the run already passed is dropped, because
|
|
1891
|
-
* it would change the replay, and so is data for a
|
|
1892
|
-
*
|
|
1893
|
-
*
|
|
1894
|
-
*
|
|
1980
|
+
* it up. Data for a gate the run has already passed is dropped, because
|
|
1981
|
+
* changing it would change the replay, and so is data for a run that's gone,
|
|
1982
|
+
* and data for a gate whose inbox already holds some: the first datum to
|
|
1983
|
+
* reach a gate is the one it gets. Each of those checks happens under a claim
|
|
1984
|
+
* on the gate's inbox key, so it holds when two calls race for one gate, and
|
|
1985
|
+
* when another call moves the run past the gate or deletes the run before
|
|
1986
|
+
* this one claims. The claim lasts the driver's `lease_ms` and comes off
|
|
1987
|
+
* right after the write, so a call that dies between the two holds that
|
|
1988
|
+
* gate's data back until the claim lapses, and data sent for the gate in that
|
|
1989
|
+
* window is dropped. Without a compare-and-set in the store contract, two
|
|
1990
|
+
* windows stay open: a call that stalls past its claim can still write data
|
|
1991
|
+
* for a gate the run has passed since, and a `delete` that lands between the
|
|
1992
|
+
* call's record read and its write leaves the data for a new run under the
|
|
1993
|
+
* same id. `undefined` resumes nothing. A call with no new data still drives
|
|
1994
|
+
* a run that failed, or whose drive died, once more.
|
|
1895
1995
|
*/
|
|
1896
1996
|
async function resume_run(driver, run_id, flow, resume_data, options) {
|
|
1897
1997
|
const drive = drive_for(driver, run_id, flow, options);
|
|
1898
1998
|
const record = await existing_record(run_id, drive.scope);
|
|
1899
1999
|
if (record.status === "done") return done_view(drive, record);
|
|
1900
|
-
const fresh = Object.entries(resume_data).filter(([
|
|
1901
|
-
|
|
1902
|
-
await Promise.all(fresh.map(async ([id, data]) => {
|
|
1903
|
-
if (await read_inbox(drive.scope, id) === void 0) await inbox.set(id, { data });
|
|
1904
|
-
}));
|
|
2000
|
+
const fresh = Object.entries(resume_data).filter(([, data]) => data !== void 0);
|
|
2001
|
+
await Promise.all(fresh.map(([id, data]) => deliver(drive, id, data)));
|
|
1905
2002
|
return bring_to_rest(drive, () => existing_record(run_id, drive.scope));
|
|
1906
2003
|
}
|
|
1907
2004
|
/**
|
|
@@ -2280,8 +2377,8 @@ register_traced_kind("branch");
|
|
|
2280
2377
|
*
|
|
2281
2378
|
* `map({ items, do, concurrency? })` extracts an array via `items(input)`,
|
|
2282
2379
|
* runs `do` once per element, returns an array in the same order as inputs.
|
|
2283
|
-
* `concurrency` caps simultaneous in-flight items
|
|
2284
|
-
* parallelism.
|
|
2380
|
+
* `concurrency` caps simultaneous in-flight items (rounded down, and never
|
|
2381
|
+
* below 1); omitted means full parallelism, and NaN throws at construction.
|
|
2285
2382
|
*
|
|
2286
2383
|
* The first item that throws stops new items from starting, and its error
|
|
2287
2384
|
* propagates once the in-flight items settle, so every result the other items
|
|
@@ -2347,16 +2444,19 @@ function settle_failure(err, index, step_id, ctx) {
|
|
|
2347
2444
|
* without it the first error fails the map.
|
|
2348
2445
|
*/
|
|
2349
2446
|
function build_map(config, fulfilled, rejected) {
|
|
2350
|
-
const id = next_id$7();
|
|
2351
2447
|
const { items, do: per_item, concurrency, name } = config;
|
|
2448
|
+
if (Number.isNaN(concurrency)) throw new TypeError(`map: concurrency must be a number, got ${concurrency}`);
|
|
2449
|
+
const id = next_id$7();
|
|
2450
|
+
const concurrency_cap = concurrency === void 0 ? void 0 : Math.max(1, Math.floor(concurrency));
|
|
2352
2451
|
const run_fn = async (input, ctx) => {
|
|
2353
2452
|
const list = await items(input);
|
|
2354
2453
|
if (list.length === 0) return [];
|
|
2355
2454
|
const results = Array.from({ length: list.length });
|
|
2356
|
-
const limit =
|
|
2455
|
+
const limit = concurrency_cap ?? list.length;
|
|
2357
2456
|
const controllers = [];
|
|
2358
2457
|
const on_parent_abort = install_abort_fan_out(ctx, controllers);
|
|
2359
2458
|
let cursor = 0;
|
|
2459
|
+
let has_worker_error = false;
|
|
2360
2460
|
let worker_error = void 0;
|
|
2361
2461
|
const run_one = async (idx) => {
|
|
2362
2462
|
const local = new AbortController();
|
|
@@ -2372,12 +2472,15 @@ function build_map(config, fulfilled, rejected) {
|
|
|
2372
2472
|
results[idx] = fulfilled(value);
|
|
2373
2473
|
} catch (err) {
|
|
2374
2474
|
if (rejected !== void 0 && !is_control_flow_error(err) && !ctx.abort.aborted) results[idx] = rejected(err, idx, id, ctx);
|
|
2375
|
-
else if (
|
|
2475
|
+
else if (!has_worker_error) {
|
|
2476
|
+
has_worker_error = true;
|
|
2477
|
+
worker_error = err;
|
|
2478
|
+
}
|
|
2376
2479
|
}
|
|
2377
2480
|
};
|
|
2378
2481
|
const worker = async () => {
|
|
2379
2482
|
while (true) {
|
|
2380
|
-
if (ctx.abort.aborted ||
|
|
2483
|
+
if (ctx.abort.aborted || has_worker_error) return;
|
|
2381
2484
|
const idx = cursor;
|
|
2382
2485
|
cursor += 1;
|
|
2383
2486
|
if (idx >= list.length) return;
|
|
@@ -2390,7 +2493,7 @@ function build_map(config, fulfilled, rejected) {
|
|
|
2390
2493
|
for (let w = 0; w < worker_count; w += 1) workers.push(worker());
|
|
2391
2494
|
await Promise.all(workers);
|
|
2392
2495
|
throw_if_aborted(ctx);
|
|
2393
|
-
if (
|
|
2496
|
+
if (has_worker_error) throw worker_error;
|
|
2394
2497
|
return results;
|
|
2395
2498
|
} finally {
|
|
2396
2499
|
ctx.abort.removeEventListener("abort", on_parent_abort);
|
|
@@ -2482,9 +2585,8 @@ function compute_backoff(policy, attempt) {
|
|
|
2482
2585
|
* Sleep `ms`, rejecting the moment `signal` fires instead of serving out the
|
|
2483
2586
|
* delay, so a pending abort never waits out a backoff.
|
|
2484
2587
|
*
|
|
2485
|
-
* A non-positive `ms` resolves without arming a timer or consulting `signal
|
|
2486
|
-
*
|
|
2487
|
-
* `to_error` applied to `signal.reason`.
|
|
2588
|
+
* A non-positive `ms` resolves without arming a timer or consulting `signal`.
|
|
2589
|
+
* The rejection value is `to_error` applied to `signal.reason`.
|
|
2488
2590
|
*/
|
|
2489
2591
|
function wait_with_abort(ms, signal, to_error) {
|
|
2490
2592
|
if (ms <= 0) return Promise.resolve();
|
|
@@ -2714,6 +2816,7 @@ function fallback(primary, backup, options) {
|
|
|
2714
2816
|
};
|
|
2715
2817
|
const config_meta = {};
|
|
2716
2818
|
if (when) config_meta["when"] = when;
|
|
2819
|
+
if (handoff) config_meta["handoff"] = handoff;
|
|
2717
2820
|
if (options?.project) config_meta["project"] = options.project;
|
|
2718
2821
|
if (options?.name !== void 0) config_meta["display_name"] = options.name;
|
|
2719
2822
|
return {
|
|
@@ -2874,6 +2977,7 @@ function wrap_guard(guard, loop_id) {
|
|
|
2874
2977
|
*/
|
|
2875
2978
|
function loop(config) {
|
|
2876
2979
|
const { init, body, finish, name } = config;
|
|
2980
|
+
if (Number.isNaN(config.max_rounds)) throw new TypeError(`loop: max_rounds must be a number, got ${config.max_rounds}`);
|
|
2877
2981
|
const rounds_limit = Math.max(1, Math.floor(config.max_rounds));
|
|
2878
2982
|
const id = next_id$2();
|
|
2879
2983
|
const guard = wrap_guard(config.guard, id);
|
|
@@ -2974,6 +3078,14 @@ register_traced_kind("compose");
|
|
|
2974
3078
|
* lookup records a `checkpoint` trajectory event with
|
|
2975
3079
|
* `status: 'hit' | 'miss' | 'read_error'`.
|
|
2976
3080
|
*
|
|
3081
|
+
* A failed write (store throws on `set`) doesn't fail the run either. It
|
|
3082
|
+
* records a `checkpoint` event with `status: 'write_error'` and returns the
|
|
3083
|
+
* inner result, because `inner` has already run and been paid for, and a
|
|
3084
|
+
* checkpoint is a cache, not the result. The next run with the same key
|
|
3085
|
+
* misses and runs `inner` again. `on_write_error: 'fail'` records the same
|
|
3086
|
+
* event and then throws the store's error, for a result that a `suspend`
|
|
3087
|
+
* hands to an approver, which has to be the one the store kept.
|
|
3088
|
+
*
|
|
2977
3089
|
* Wrapping an anonymous inner step throws synchronously at construction time
|
|
2978
3090
|
* with the message `checkpoint requires a named step, got anonymous`, because
|
|
2979
3091
|
* a cached result must map back to a stable, identifiable step.
|
|
@@ -3001,6 +3113,67 @@ function gates_within(root, seen = /* @__PURE__ */ new Set()) {
|
|
|
3001
3113
|
return root.kind === "suspend" ? [root.id, ...inner] : inner;
|
|
3002
3114
|
}
|
|
3003
3115
|
/**
|
|
3116
|
+
* The fields every `checkpoint` event of one lookup carries: the step `id`,
|
|
3117
|
+
* the store `key`, and the `span_id` of the checkpoint's span when there is
|
|
3118
|
+
* one, so a viewer can nest the event.
|
|
3119
|
+
*/
|
|
3120
|
+
function event_meta(id, key, ctx) {
|
|
3121
|
+
const meta = {
|
|
3122
|
+
id,
|
|
3123
|
+
key
|
|
3124
|
+
};
|
|
3125
|
+
if (ctx.parent_span_id !== void 0) meta["span_id"] = ctx.parent_span_id;
|
|
3126
|
+
return meta;
|
|
3127
|
+
}
|
|
3128
|
+
/**
|
|
3129
|
+
* The `checkpoint` event for a store call that threw, carrying its message.
|
|
3130
|
+
*/
|
|
3131
|
+
function store_failure(status, err, meta) {
|
|
3132
|
+
return {
|
|
3133
|
+
kind: "checkpoint",
|
|
3134
|
+
status,
|
|
3135
|
+
error: err instanceof Error ? err.message : String(err),
|
|
3136
|
+
...meta
|
|
3137
|
+
};
|
|
3138
|
+
}
|
|
3139
|
+
/**
|
|
3140
|
+
* The value stored at `key` in `store`, or `undefined` on a miss, recording
|
|
3141
|
+
* exactly one `checkpoint` event so hits, misses, and swallowed read errors
|
|
3142
|
+
* are all visible in the trajectory. A stored `null` or `undefined` is a
|
|
3143
|
+
* miss, which is what lets `undefined` stand for one, and a throwing
|
|
3144
|
+
* `store.get` still behaves as a miss (a broken store must not fail the run),
|
|
3145
|
+
* but under `status: 'read_error'` instead of silently.
|
|
3146
|
+
*/
|
|
3147
|
+
async function look_up(store, key, meta, ctx) {
|
|
3148
|
+
try {
|
|
3149
|
+
const value = await store.get(key);
|
|
3150
|
+
const hit = value !== null && value !== void 0;
|
|
3151
|
+
ctx.trajectory.record({
|
|
3152
|
+
kind: "checkpoint",
|
|
3153
|
+
status: hit ? "hit" : "miss",
|
|
3154
|
+
...meta
|
|
3155
|
+
});
|
|
3156
|
+
return hit ? value : void 0;
|
|
3157
|
+
} catch (err) {
|
|
3158
|
+
ctx.trajectory.record(store_failure("read_error", err, meta));
|
|
3159
|
+
return;
|
|
3160
|
+
}
|
|
3161
|
+
}
|
|
3162
|
+
/**
|
|
3163
|
+
* Write `result` to `store` at `key`. A throwing `store.set` records
|
|
3164
|
+
* `status: 'write_error'` and leaves the result to the caller, since the
|
|
3165
|
+
* inner step that produced it has already run, unless `fail_on_write` says
|
|
3166
|
+
* to throw the store's error once the event is recorded.
|
|
3167
|
+
*/
|
|
3168
|
+
async function keep(store, key, result, meta, ctx, fail_on_write) {
|
|
3169
|
+
try {
|
|
3170
|
+
await store.set(key, result);
|
|
3171
|
+
} catch (err) {
|
|
3172
|
+
ctx.trajectory.record(store_failure("write_error", err, meta));
|
|
3173
|
+
if (fail_on_write) throw err;
|
|
3174
|
+
}
|
|
3175
|
+
}
|
|
3176
|
+
/**
|
|
3004
3177
|
* Wrap `inner` with persist-and-resume behavior keyed by `config.key`.
|
|
3005
3178
|
*
|
|
3006
3179
|
* `key` is a fixed string or a function of the input. Without a
|
|
@@ -3013,42 +3186,20 @@ function checkpoint(inner, config) {
|
|
|
3013
3186
|
if (inner.anonymous === true) throw new Error("checkpoint requires a named step, got anonymous — give the inner step an id with step('id', fn)");
|
|
3014
3187
|
const id = next_id();
|
|
3015
3188
|
const key_spec = config.key;
|
|
3189
|
+
const fail_on_write = config.on_write_error === "fail";
|
|
3016
3190
|
const gates = gates_within(inner);
|
|
3017
3191
|
const run_fn = async (input, ctx) => {
|
|
3018
3192
|
const key = typeof key_spec === "function" ? key_spec(input) : key_spec;
|
|
3019
3193
|
const store = ctx.checkpoint_store;
|
|
3020
|
-
if (store)
|
|
3021
|
-
|
|
3022
|
-
|
|
3023
|
-
|
|
3024
|
-
|
|
3025
|
-
|
|
3026
|
-
};
|
|
3027
|
-
if (ctx.parent_span_id !== void 0) lookup_meta["span_id"] = ctx.parent_span_id;
|
|
3028
|
-
try {
|
|
3029
|
-
cached = await store.get(key);
|
|
3030
|
-
hit = cached !== null && cached !== void 0;
|
|
3031
|
-
ctx.trajectory.record({
|
|
3032
|
-
kind: "checkpoint",
|
|
3033
|
-
status: hit ? "hit" : "miss",
|
|
3034
|
-
...lookup_meta
|
|
3035
|
-
});
|
|
3036
|
-
} catch (err) {
|
|
3037
|
-
hit = false;
|
|
3038
|
-
ctx.trajectory.record({
|
|
3039
|
-
kind: "checkpoint",
|
|
3040
|
-
status: "read_error",
|
|
3041
|
-
error: err instanceof Error ? err.message : String(err),
|
|
3042
|
-
...lookup_meta
|
|
3043
|
-
});
|
|
3044
|
-
}
|
|
3045
|
-
if (hit) {
|
|
3046
|
-
mark_gates_reached(ctx, gates);
|
|
3047
|
-
return cached;
|
|
3048
|
-
}
|
|
3194
|
+
if (!store) return dispatch_step(inner, input, ctx);
|
|
3195
|
+
const meta = event_meta(id, key, ctx);
|
|
3196
|
+
const cached = await look_up(store, key, meta, ctx);
|
|
3197
|
+
if (cached !== void 0) {
|
|
3198
|
+
mark_gates_reached(ctx, gates);
|
|
3199
|
+
return cached;
|
|
3049
3200
|
}
|
|
3050
3201
|
const result = await dispatch_step(inner, input, ctx);
|
|
3051
|
-
|
|
3202
|
+
await keep(store, key, result, meta, ctx, fail_on_write);
|
|
3052
3203
|
return result;
|
|
3053
3204
|
};
|
|
3054
3205
|
const config_meta = { key: key_spec };
|
|
@@ -3064,63 +3215,6 @@ function checkpoint(inner, config) {
|
|
|
3064
3215
|
}
|
|
3065
3216
|
register_traced_kind("checkpoint");
|
|
3066
3217
|
//#endregion
|
|
3067
|
-
//#region src/schema/validate.ts
|
|
3068
|
-
/**
|
|
3069
|
-
* Validate `value` against `schema`, returning the typed value or the issues.
|
|
3070
|
-
*
|
|
3071
|
-
* Always async, even for a validator that answers synchronously: the spec
|
|
3072
|
-
* permits `validate` to return either a result or a promise of one, and
|
|
3073
|
-
* Fascicle cannot know which a given vendor does. Awaiting a non-promise is
|
|
3074
|
-
* cheap; guessing wrong is a silent bug.
|
|
3075
|
-
*/
|
|
3076
|
-
async function validate_schema(schema, value) {
|
|
3077
|
-
const result = await schema["~standard"].validate(value);
|
|
3078
|
-
if (result.issues) return {
|
|
3079
|
-
ok: false,
|
|
3080
|
-
issues: result.issues.map(normalize_issue)
|
|
3081
|
-
};
|
|
3082
|
-
return {
|
|
3083
|
-
ok: true,
|
|
3084
|
-
value: result.value
|
|
3085
|
-
};
|
|
3086
|
-
}
|
|
3087
|
-
/**
|
|
3088
|
-
* Flatten one vendor issue into Fascicle's shape.
|
|
3089
|
-
*
|
|
3090
|
-
* The spec allows a path segment to be a bare key or a `{ key }` wrapper, and
|
|
3091
|
-
* allows the path to be absent entirely. Normalizing here means no consumer has
|
|
3092
|
-
* to know which vendor produced the issue.
|
|
3093
|
-
*/
|
|
3094
|
-
function normalize_issue(issue) {
|
|
3095
|
-
if (issue.path === void 0) return { message: issue.message };
|
|
3096
|
-
const path = issue.path.map((segment) => typeof segment === "object" ? segment.key : segment);
|
|
3097
|
-
return {
|
|
3098
|
-
message: issue.message,
|
|
3099
|
-
path
|
|
3100
|
-
};
|
|
3101
|
-
}
|
|
3102
|
-
/**
|
|
3103
|
-
* Render issues as the single line that goes into an error message or a repair
|
|
3104
|
-
* prompt fed back to the model.
|
|
3105
|
-
*
|
|
3106
|
-
* Paths are dotted (`address.city`, `items.0.name`) rather than bracketed for
|
|
3107
|
-
* indices: the model reads it as a hint about which field to fix, and one
|
|
3108
|
-
* consistent separator is easier to follow than two.
|
|
3109
|
-
*/
|
|
3110
|
-
function format_schema_issues(issues) {
|
|
3111
|
-
if (issues.length === 0) return "unknown schema issue";
|
|
3112
|
-
return issues.map(format_issue).join("; ");
|
|
3113
|
-
}
|
|
3114
|
-
/**
|
|
3115
|
-
* Render one issue as `path: message`, or just the message when the vendor
|
|
3116
|
-
* reported no path (a failure about the value as a whole).
|
|
3117
|
-
*/
|
|
3118
|
-
function format_issue(issue) {
|
|
3119
|
-
const path = issue.path;
|
|
3120
|
-
if (path === void 0 || path.length === 0) return issue.message;
|
|
3121
|
-
return `${path.map((segment) => String(segment)).join(".")}: ${issue.message}`;
|
|
3122
|
-
}
|
|
3123
|
-
//#endregion
|
|
3124
3218
|
//#region src/core/suspend.ts
|
|
3125
3219
|
/**
|
|
3126
3220
|
* suspend: human-in-the-loop pause.
|
|
@@ -3156,9 +3250,11 @@ function resume_value_for(ctx, suspend_id) {
|
|
|
3156
3250
|
* First run fires the `on` side effect and throws `suspended_error`; a resume
|
|
3157
3251
|
* run validates `resume_data[id]` against `resume_schema` and feeds it to
|
|
3158
3252
|
* `combine`. The step's id is the user-supplied suspend id so resume data can
|
|
3159
|
-
* be addressed to it
|
|
3253
|
+
* be addressed to it, which is why it's held to the step id rule and throws
|
|
3254
|
+
* a `TypeError` when it's built if it isn't an identifier.
|
|
3160
3255
|
*/
|
|
3161
3256
|
function suspend(config) {
|
|
3257
|
+
assert_valid_step_id(config.id, "suspend id", "put the label in name");
|
|
3162
3258
|
const suspend_id = config.id;
|
|
3163
3259
|
const deadline_ms = config.deadline_ms;
|
|
3164
3260
|
const on_fn = config.on;
|
|
@@ -3287,7 +3383,7 @@ function scope(children, options) {
|
|
|
3287
3383
|
function stash(key, source, options) {
|
|
3288
3384
|
const id = next_stash_id();
|
|
3289
3385
|
const run_fn = async (input, ctx) => {
|
|
3290
|
-
if (!is_scope_state(ctx.state)) throw new Error(
|
|
3386
|
+
if (!is_scope_state(ctx.state)) throw new Error(`stash('${key}') ran outside any scope(): wrap it and the steps that use() its key in scope([...])`);
|
|
3291
3387
|
const value = await dispatch_step(source, input, ctx);
|
|
3292
3388
|
ctx.state.set(key, value);
|
|
3293
3389
|
return value;
|
|
@@ -3312,7 +3408,10 @@ function stash(key, source, options) {
|
|
|
3312
3408
|
function use(keys, fn, options) {
|
|
3313
3409
|
const id = next_use_id();
|
|
3314
3410
|
const run_fn = async (input, ctx) => {
|
|
3315
|
-
if (!is_scope_state(ctx.state))
|
|
3411
|
+
if (!is_scope_state(ctx.state)) {
|
|
3412
|
+
const listed = keys.map((k) => `'${k}'`).join(", ");
|
|
3413
|
+
throw new Error(`use([${listed}]) ran outside any scope(): wrap it and the stash() steps that set its keys in scope([...])`);
|
|
3414
|
+
}
|
|
3316
3415
|
const projection = {};
|
|
3317
3416
|
for (const k of keys) projection[k] = ctx.state.get(k);
|
|
3318
3417
|
return fn(projection, input, ctx);
|
|
@@ -3518,6 +3617,6 @@ function chain(input_name) {
|
|
|
3518
3617
|
}
|
|
3519
3618
|
register_traced_kind("chain");
|
|
3520
3619
|
//#endregion
|
|
3521
|
-
export { describe_cycle_error as A,
|
|
3620
|
+
export { describe_cycle_error as A, durable as C, describe as D, run as E, suspended_error as F, timeout_error as I, STEP_KINDS as L, flow_changed_error as M, resume_validation_error as N, is_step as O, run_not_found_error as P, is_step_kind as R, suggest_step_id as S, validate_schema as T, parallel as _, suspend as a, assert_valid_step_id as b, loop as c, retry as d, compute_backoff as f, branch as g, map as h, use as i, error_path as j, aborted_error as k, timeout as l, pipe as m, scope as n, checkpoint as o, wait_with_abort as p, stash as r, compose as s, chain as t, fallback as u, sequence as v, format_schema_issues as w, is_valid_step_id as x, step as y, resolve_display_name as z };
|
|
3522
3621
|
|
|
3523
|
-
//# sourceMappingURL=core-
|
|
3622
|
+
//# sourceMappingURL=core-CErsxGF6.js.map
|