fascicle 0.16.3 → 0.16.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -163,6 +163,8 @@ type DiagramOptions = {
163
163
  readonly prefix?: string;
164
164
  /** Mark each step that `describe.replays` finds with the gates it can run again before. */
165
165
  readonly replays?: boolean;
166
+ /** Draw a named composite's internal steps instead of only the parts it was built from. */
167
+ readonly internals?: boolean;
166
168
  };
167
169
  //#endregion
168
170
  //#region src/core/replays.d.ts
@@ -283,13 +285,20 @@ type SequenceOptions = {
283
285
  * every element up front so a non-Step (usually a bare function) fails at
284
286
  * construction with a pointed message rather than at run time. Checks
285
287
  * `ctx.abort` before each child so aborts land on step boundaries.
288
+ *
289
+ * The checked signature comes again after the array one. A call that matches
290
+ * no overload is reported against the last one, so repeating the checked
291
+ * signature there puts its `SequenceJointMismatch`, which names the joint, in
292
+ * the error, where the array overload would only say that every step must be
293
+ * a `Step<T, T>`. A call that does match still resolves in the order above.
286
294
  */
287
295
  export declare function sequence<const children extends readonly unknown[]>(children: children & CheckedChildren<children>, options?: SequenceOptions): Step<FirstInput<children>, LastOutput$1<children>>;
288
296
  export declare function sequence<t>(children: ReadonlyArray<Step<t, t>>, options?: SequenceOptions): Step<t, t>;
297
+ export declare function sequence<const children extends readonly unknown[]>(children: children & CheckedChildren<children>, options?: SequenceOptions): Step<FirstInput<children>, LastOutput$1<children>>;
289
298
  //#endregion
290
299
  //#region src/core/parallel.d.ts
291
- type UnionToIntersection<u> = (u extends unknown ? (x: u) => void : never) extends ((x: infer i) => void) ? i : never;
292
- type ParallelInput<children extends Record<string, AnyStep>> = UnionToIntersection<StepInput<children[keyof children]>>;
300
+ type ParallelInput<children extends Record<string, AnyStep>> = { [k in keyof children]: (input: Accepted<StepInput<children[k]>>) => void; }[keyof children] extends ((input: infer i) => void) ? i : never;
301
+ type Accepted<i> = [i] extends [never] ? unknown : i;
293
302
  type ParallelOutputs<children extends Record<string, AnyStep>> = { [k in keyof children]: StepOutput<children[k]>; };
294
303
  type ParallelOptions = {
295
304
  readonly name?: string;
@@ -307,12 +316,12 @@ type ParallelOptions = {
307
316
  export declare function parallel<children extends Record<string, AnyStep>>(members: children, options?: ParallelOptions): Step<ParallelInput<children>, ParallelOutputs<children>>;
308
317
  //#endregion
309
318
  //#region src/core/branch.d.ts
310
- type BranchConfig<i, o> = {
319
+ type BranchConfig<i, o, otherwise_o = o> = {
311
320
  readonly name?: string;
312
321
  readonly description?: string;
313
322
  readonly when: (input: i) => boolean | Promise<boolean>;
314
323
  readonly then: Step<i, o>;
315
- readonly otherwise: Step<i, o>;
324
+ readonly otherwise: Step<i, otherwise_o>;
316
325
  };
317
326
  /**
318
327
  * Build a conditional-routing step.
@@ -321,7 +330,7 @@ type BranchConfig<i, o> = {
321
330
  * Both branches appear as children so `describe()` renders the full tree even
322
331
  * though only one branch runs.
323
332
  */
324
- export declare function branch<i, o>(config: BranchConfig<i, o>): Step<i, o>;
333
+ export declare function branch<i, o, otherwise_o = o>(config: BranchConfig<i, o, otherwise_o>): Step<i, o | otherwise_o>;
325
334
  //#endregion
326
335
  //#region src/core/map.d.ts
327
336
  type MapConfig<input, item, result> = {
@@ -537,6 +546,7 @@ export declare function loop<i, state, o>(config: LoopConfig<i, state, o>): Step
537
546
  type ComposeConfig = {
538
547
  readonly name: string;
539
548
  readonly description?: string | undefined;
549
+ readonly parts?: Readonly<Record<string, AnyStep>> | undefined;
540
550
  };
541
551
  /**
542
552
  * Wrap `inner` in a named composite step.
@@ -544,6 +554,11 @@ type ComposeConfig = {
544
554
  * The step's `kind` is always `'compose'`; `config.name` becomes the
545
555
  * `display_name` used as the span label. Throws a `TypeError` when `name`
546
556
  * is not a non-empty string, catching the mistake at construction time.
557
+ *
558
+ * Each of `config.parts` is recorded as the path of child indices that leads
559
+ * to it from the composite, so `describe.json` keeps the whole tree that the
560
+ * viewer maps spans onto while `describe.diagram` can draw just the parts. A
561
+ * part that isn't inside `inner` throws, since there would be no path to draw.
547
562
  */
548
563
  export declare function compose<i, o>(inner: Step<i, o>, config: ComposeConfig): Step<i, o>;
549
564
  //#endregion
@@ -643,6 +658,9 @@ type ChainStepOptions = {
643
658
  /** What the binding is for, carried to `describe` as `meta.description`. */
644
659
  readonly description?: string;
645
660
  };
661
+ interface ChainInputUndeclared<fix extends string> {
662
+ readonly chain_input_undeclared: fix;
663
+ }
646
664
  type Chain<i, acc> = {
647
665
  readonly step: {
648
666
  <k extends string, o>(name: k, fn: (s: acc, ctx: RunContext) => Promise<o> | o, options?: ChainStepOptions): Chain<i, merge<acc, { readonly [p in k]: o; }>>;
@@ -667,16 +685,16 @@ type ChainOpen<i, k extends string, acc> = Chain<i, acc> & {
667
685
  /**
668
686
  * Open a chain builder whose record starts as `{ [input_name]: input }`.
669
687
  *
670
- * `input_name` defaults to `'input'`. The input type defaults to `never`, so
671
- * a chain that never states it produces a `Step<never, o>` that no real
672
- * input satisfies at `run`; state it as the type argument or, when the
688
+ * `input_name` defaults to `'input'`. The input type defaults to a branded
689
+ * `ChainInputUndeclared` that no real input satisfies at `run`, and whose
690
+ * name in an error says what to do; state it as the type argument or, when the
673
691
  * binding is renamed, once via `.input<t>()` on the fresh builder. Each
674
692
  * `.step` narrows subsequent callbacks to the record accumulated so far, and
675
693
  * `.stage` with a projection re-types the record to the projection's
676
694
  * return, so binding names and views are checked at compile time with no
677
695
  * declared state shape.
678
696
  */
679
- export declare function chain<i = never, k extends string = 'input'>(input_name?: k): ChainOpen<i, k, { readonly [p in k]: i; }>;
697
+ export declare function chain<i = ChainInputUndeclared<'call .input<T>() on the chain to say what it takes'>, k extends string = 'input'>(input_name?: k): ChainOpen<i, k, { readonly [p in k]: i; }>;
680
698
  //#endregion
681
699
  //#region src/core/errors.d.ts
682
700
  export declare class timeout_error extends Error {
@@ -1106,6 +1124,12 @@ export declare const flow_schema: {
1106
1124
  description: {
1107
1125
  type: string;
1108
1126
  };
1127
+ parts: {
1128
+ type: string;
1129
+ additionalProperties: {
1130
+ $ref: string;
1131
+ };
1132
+ };
1109
1133
  do: {
1110
1134
  $ref: string;
1111
1135
  };
package/dist/index.js CHANGED
@@ -1,8 +1,8 @@
1
- import { A as describe_cycle_error, C as durable, D as describe, E as run, F as suspended_error, I as timeout_error, L as STEP_KINDS, M as flow_changed_error, N as resume_validation_error, O as is_step, P as run_not_found_error, R as is_step_kind, S as suggest_step_id, _ as parallel, a as suspend, b as assert_valid_step_id, c as loop, d as retry, g as branch, h as map, i as use, j as error_path, k as aborted_error, l as timeout, m as pipe, n as scope, o as checkpoint, r as stash, s as compose, t as chain, u as fallback, v as sequence, x as is_valid_step_id, y as step, z as resolve_display_name } from "./core-CErsxGF6.js";
2
- import { t as create_engine } from "./engine-CR8q2IqV.js";
1
+ import { A as describe_cycle_error, C as durable, D as describe, E as run, F as suspended_error, I as timeout_error, L as STEP_KINDS, M as flow_changed_error, N as resume_validation_error, O as is_step, P as run_not_found_error, R as is_step_kind, S as suggest_step_id, _ as parallel, a as suspend, b as assert_valid_step_id, c as loop, d as retry, g as branch, h as map, i as use, j as error_path, k as aborted_error, l as timeout, m as pipe, n as scope, o as checkpoint, r as stash, s as compose, t as chain, u as fallback, v as sequence, x as is_valid_step_id, y as step, z as resolve_display_name } from "./core-BOFcG3tp.js";
2
+ import { t as create_engine } from "./engine-B6rIIM4J.js";
3
3
  import { a as is_run_end_event, c as is_step_replayed_event, i as is_map_item_failed_event, l as parse_trajectory_event, n as is_custom_trajectory_event, o as is_span_end_event, r as is_emit_event, s as is_span_start_event, t as is_checkpoint_event } from "./trajectory-DeURWIhj.js";
4
4
  import { a as http_logger, n as tee_logger, o as filesystem_logger } from "./adapters-CDUzZlby.js";
5
- import { A as tool_error, C as provider_capability_error, D as rate_limit_error, E as provider_required_error, O as schema_validation_error, S as provider_auth_error, T as provider_not_configured_error, _ as engine_config_error, b as model_required_error, g as claude_cli_error, j as turn_timeout_error, k as tool_approval_denied_error, u as default_normalize_usage, v as engine_disposed_error, w as provider_error, x as on_chunk_error, y as incomplete_generation_error } from "./leading_system-PoHzNHuV.js";
5
+ import { A as tool_error, C as provider_capability_error, D as rate_limit_error, E as provider_required_error, O as schema_validation_error, S as provider_auth_error, T as provider_not_configured_error, _ as engine_config_error, b as model_required_error, g as claude_cli_error, j as turn_timeout_error, k as tool_approval_denied_error, u as default_normalize_usage, v as engine_disposed_error, w as provider_error, x as on_chunk_error, y as incomplete_generation_error } from "./leading_system-WhW76tRn.js";
6
6
  import { createHash } from "node:crypto";
7
7
  import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
8
8
  import { dirname, join } from "node:path";
@@ -214,6 +214,10 @@ const flow_schema = {
214
214
  "minLength": 1
215
215
  },
216
216
  "description": { "type": "string" },
217
+ "parts": {
218
+ "type": "object",
219
+ "additionalProperties": { "$ref": "#/$defs/node" }
220
+ },
217
221
  "do": { "$ref": "#/$defs/node" }
218
222
  }
219
223
  },
@@ -682,7 +686,11 @@ function adversarial(config) {
682
686
  });
683
687
  return compose(inner, {
684
688
  name: config.name ?? "adversarial",
685
- description: config.description
689
+ description: config.description,
690
+ parts: {
691
+ build,
692
+ critique
693
+ }
686
694
  });
687
695
  }
688
696
  //#endregion
@@ -738,7 +746,8 @@ function consensus(config) {
738
746
  });
739
747
  return compose(inner, {
740
748
  name: config.name ?? "consensus",
741
- description: config.description
749
+ description: config.description,
750
+ parts: members
742
751
  });
743
752
  }
744
753
  //#endregion
@@ -806,6 +815,21 @@ function best_of(ranked, select) {
806
815
  return best?.[0];
807
816
  }
808
817
  //#endregion
818
+ //#region src/composites/parts.ts
819
+ /**
820
+ * Collect parts by role, giving a role that's already taken a numbered
821
+ * suffix, so every part is still drawn.
822
+ */
823
+ function name_parts(entries) {
824
+ const parts = {};
825
+ for (const [role, part] of entries) {
826
+ let name = role;
827
+ for (let n = 2; Object.hasOwn(parts, name); n += 1) name = `${role}_${n}`;
828
+ parts[name] = part;
829
+ }
830
+ return parts;
831
+ }
832
+ //#endregion
809
833
  //#region src/composites/ensemble_step.ts
810
834
  /**
811
835
  * ensemble_step: N-of-M pick-best with a Step-based scorer.
@@ -896,7 +920,8 @@ function ensemble_step(config) {
896
920
  ]);
897
921
  return compose(inner, {
898
922
  name: config.name ?? "ensemble_step",
899
- description: config.description
923
+ description: config.description,
924
+ parts: name_parts([...Object.entries(members), ["score", score]])
900
925
  });
901
926
  }
902
927
  //#endregion
@@ -1011,7 +1036,8 @@ function gate(inner, config) {
1011
1036
  ]);
1012
1037
  return compose(body, {
1013
1038
  name: config.name ?? "gate",
1014
- description: config.description
1039
+ description: config.description,
1040
+ parts: name_parts([[inner.id, inner], [id, approval]])
1015
1041
  });
1016
1042
  }
1017
1043
  //#endregion
@@ -1200,7 +1226,12 @@ function improve(config) {
1200
1226
  ]);
1201
1227
  return compose(inner, {
1202
1228
  name: config.name ?? "improve",
1203
- description: config.description
1229
+ description: config.description,
1230
+ parts: {
1231
+ seed,
1232
+ propose,
1233
+ score
1234
+ }
1204
1235
  });
1205
1236
  }
1206
1237
  //#endregion