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.
@@ -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 ?? 0;
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
- error: err instanceof Error ? err.message : String(err)
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) throw reason;
899
+ if (reason instanceof aborted_error) thrown = reason;
858
900
  }
859
- throw err;
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 the
913
- * gate's suspend id and `resume(data)` re-runs the flow from the original
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 `anon_<counter>`; cannot be checkpointed.
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 anon_counter = 0;
1042
+ let step_counter = 0;
972
1043
  /**
973
- * Generate a unique id of the form `anon_<n>` for anonymous steps.
1044
+ * Generate a unique id of the form `step_<n>` for anonymous steps.
974
1045
  */
975
- function next_anon_id() {
976
- anon_counter += 1;
977
- return `anon_${anon_counter}`;
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: next_anon_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 errors on the offending element. Arrays built at runtime carry no
1265
- * positional types, so they degrade to the outer boundary (`unknown` in and
1266
- * out) while each element is still checked to be a Step.
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
- return dispatch_step(backup, handoff === void 0 ? input : handoff(input, err), ctx);
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. When `guard.stop` is true, the loop exits
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, guard, finish, name } = config;
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
- } catch {
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. `.step(name, fn)` runs `fn` over
2329
- * the record and merges its output back in under `name`; `.stage(name,
2330
- * project?)` concludes a phase: it opens a grouping span in the trajectory
2331
- * and, when `project` is given, replaces the record with the projection so
2332
- * earlier bindings go out of scope; `.output(fn)` closes the builder and
2333
- * returns an ordinary `Step<i, o>`.
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. Invoking another Step from inside a
2339
- * binding is `ctx.call`, exactly as in a hand-written step body; passing
2340
- * that Step as `.step(name, fn, { arm })` additionally records it as the
2341
- * binding's child so `describe` renders the arm's subtree. The arm is
2342
- * metadata only: dispatch runs `fn` and ignores it.
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, fn, options) => {
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 base = step(name, fn);
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 builder is typed: each `.step`
2465
- * narrows subsequent callbacks to the record accumulated so far, and
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
- return make_chain(name, [], /* @__PURE__ */ new Set([name]));
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 { run as A, pipe as C, sequence as D, parallel as E, timeout_error as F, flow_schema_default as I, describe_cycle_error as M, resume_validation_error as N, describe as O, suspended_error as P, wait_with_abort as S, branch as T, loop as _, parse_trajectory_event as a, retry as b, chain as c, use as d, suspend as f, compose as g, checkpoint as h, is_span_start_event as i, aborted_error as j, step as k, scope as l, validate_schema as m, is_emit_event as n, STEP_KINDS as o, format_schema_issues as p, is_span_end_event as r, is_step_kind as s, is_custom_trajectory_event as t, stash as u, timeout as v, map as w, compute_backoff as x, fallback as y };
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-BkB2l1-e.js.map
2752
+ //# sourceMappingURL=core-DDRhHu5P.js.map