@boboddy/sdk 0.2.15-alpha → 0.4.0

package/dist/definitions/advancement-policies/index.js

@@ -242,10 +242,252 @@ function makeAdvanceCtx() {
     route: (pipelineKey, inputJson) => inputJson !== undefined ? { outcome: "route", pipelineKey, inputJson } : { outcome: "route", pipelineKey }
   };
 }
+// src/definitions/advancement-policies/cohort-advancement-policy.ts
+var cohortAdvancementEventTypeValues = ["continue", "block"];
+function serializeCohortCondition(condition) {
+  if (condition._tag === "signal") {
+    return {
+      fact: typeof condition.signal === "string" ? condition.signal : condition.signal.key,
+      operator: condition.operator,
+      value: condition.value
+    };
+  }
+  if (condition._tag === "all") {
+    return { all: condition.conditions.map(serializeCohortCondition) };
+  }
+  return { any: condition.conditions.map(serializeCohortCondition) };
+}
+function serializeCohortRule(rule) {
+  return {
+    conditions: { [rule.mode]: rule.conditions.map(serializeCohortCondition) },
+    event: {
+      type: rule.outcome,
+      ...rule.outcomeJson ? { params: rule.outcomeJson } : {}
+    }
+  };
+}
+function serializeCohortAdvancementPolicy(policy) {
+  if (!policy) {
+    return { rules: [], defaultEventType: "continue", defaultEventParamsJson: null };
+  }
+  return {
+    rules: (policy.rules ?? []).map(serializeCohortRule),
+    defaultEventType: policy.default,
+    defaultEventParamsJson: policy.defaultParamsJson ?? null
+  };
+}
+function visitCohortSignalConditions(conditions, visit) {
+  for (const c of conditions) {
+    if (c._tag === "signal") {
+      visit(c);
+    } else {
+      visitCohortSignalConditions(c.conditions, visit);
+    }
+  }
+}
+function isSameStepSignalsListDefinition(a, b) {
+  return JSON.stringify(a.ops) === JSON.stringify(b.ops) && JSON.stringify(a.reducer) === JSON.stringify(b.reducer);
+}
+function extractInlineStepSignalsListDefinitions(policy) {
+  if (!policy?.rules)
+    return [];
+  const byKey = new Map;
+  for (const rule of policy.rules) {
+    visitCohortSignalConditions(rule.conditions, (cond) => {
+      if (typeof cond.signal === "string")
+        return;
+      const inline = cond.signal;
+      const def = {
+        key: inline.key,
+        ops: inline.ops,
+        reducer: inline.reducer
+      };
+      const existing = byKey.get(def.key);
+      if (existing) {
+        if (!isSameStepSignalsListDefinition(existing, def)) {
+          throw new Error(`Conflicting inline stepSignalsList definitions for key "${def.key}"`);
+        }
+        return;
+      }
+      byKey.set(def.key, def);
+    });
+  }
+  return [...byKey.values()];
+}
+// src/definitions/advancement-policies/cohort-fluent-rules.ts
+var LEAF_BRAND2 = Symbol("boboddy.cohortRule.leaf");
+var GROUP_BRAND2 = Symbol("boboddy.cohortRule.group");
+function createCohortSignalRef(signal2) {
+  const leaf = (operator, value) => {
+    const condition = {
+      _tag: "signal",
+      signal: signal2,
+      operator,
+      value
+    };
+    return {
+      [LEAF_BRAND2]: condition,
+      then(outcome, paramsJson) {
+        return {
+          _tag: "rule",
+          mode: "all",
+          conditions: [condition],
+          outcome,
+          ...paramsJson ? { outcomeJson: paramsJson } : {}
+        };
+      }
+    };
+  };
+  return {
+    eq: (v) => leaf("equal", v),
+    ne: (v) => leaf("notEqual", v),
+    gt: (v) => leaf("greaterThan", v),
+    gte: (v) => leaf("greaterThanInclusive", v),
+    lt: (v) => leaf("lessThan", v),
+    lte: (v) => leaf("lessThanInclusive", v),
+    in: (vs) => leaf("in", vs),
+    notIn: (vs) => leaf("notIn", vs),
+    contains: (v) => leaf("contains", v),
+    doesNotContain: (v) => leaf("doesNotContain", v)
+  };
+}
+function createCohortLeafFromCondition(condition) {
+  return {
+    [LEAF_BRAND2]: condition,
+    then(outcome, paramsJson) {
+      return {
+        _tag: "rule",
+        mode: "all",
+        conditions: [condition],
+        outcome,
+        ...paramsJson ? { outcomeJson: paramsJson } : {}
+      };
+    }
+  };
+}
+function extractCohortCondition(ref) {
+  if (LEAF_BRAND2 in ref)
+    return ref[LEAF_BRAND2];
+  const group = ref[GROUP_BRAND2];
+  return group.mode === "all" ? { _tag: "all", conditions: group.conditions } : { _tag: "any", conditions: group.conditions };
+}
+function createCohortGroup(mode, refs) {
+  const conditions = refs.map(extractCohortCondition);
+  return {
+    [GROUP_BRAND2]: { mode, conditions },
+    then(outcome, paramsJson) {
+      return {
+        _tag: "rule",
+        mode,
+        conditions,
+        outcome,
+        ...paramsJson ? { outcomeJson: paramsJson } : {}
+      };
+    }
+  };
+}
+function makeKeyedCohortSignalRef(key) {
+  return createCohortSignalRef(key);
+}
+function makeAdvanceEachCtx() {
+  return {
+    signal: (key) => makeKeyedCohortSignalRef(key),
+    stepSignals: new Proxy({}, {
+      get(_, key) {
+        if (typeof key === "string")
+          return makeKeyedCohortSignalRef(key);
+        return;
+      }
+    }),
+    all: (...refs) => createCohortGroup("all", refs),
+    any: (...refs) => createCohortGroup("any", refs)
+  };
+}
+var branchOutcomeValues = [
+  "continue",
+  "block",
+  "error",
+  "abandoned"
+];
+function summarizeTransformOp(op) {
+  if (op.op === "filter") {
+    return `filter_${op.operator}_${JSON.stringify(op.value)}`;
+  }
+  if (op.op === "sortBy") {
+    return `sortBy_${op.direction}`;
+  }
+  return "unique";
+}
+function deriveStepSignalsListKey(ops, reducer) {
+  const pluck = ops.find((op) => op.op === "pluck");
+  const base = `${reducer.op}_${pluck?.signalKey ?? "value"}`;
+  const extras = ops.filter((op) => op.op !== "pluck").map(summarizeTransformOp);
+  const reducerExtra = reducer.op === "join" ? `sep_${reducer.separator}` : null;
+  const suffixParts = [...extras, ...reducerExtra ? [reducerExtra] : []];
+  return suffixParts.length > 0 ? `${base}_${suffixParts.join("_")}` : base;
+}
+function createStepSignalsListBuilder(ops) {
+  const withOp = (op) => createStepSignalsListBuilder([...ops, op]);
+  const reduce = (reducer) => {
+    const token = {
+      _tag: "step_signals_list",
+      key: deriveStepSignalsListKey(ops, reducer),
+      ops: [...ops],
+      reducer
+    };
+    return createCohortSignalRef(token);
+  };
+  return {
+    filter: (operator, value) => withOp({ op: "filter", operator, value }),
+    sortBy: (direction = "asc") => withOp({ op: "sortBy", direction }),
+    unique: () => withOp({ op: "unique" }),
+    count: () => reduce({ op: "count" }),
+    sum: () => reduce({ op: "sum" }),
+    avg: () => reduce({ op: "avg" }),
+    min: () => reduce({ op: "min" }),
+    max: () => reduce({ op: "max" }),
+    booleanAll: () => reduce({ op: "booleanAll" }),
+    booleanAny: () => reduce({ op: "booleanAny" }),
+    join: (separator = ",") => reduce({ op: "join", separator }),
+    first: () => reduce({ op: "first" }),
+    last: () => reduce({ op: "last" })
+  };
+}
+function makeAdvanceAllCtx() {
+  return {
+    branchOutcomes: {
+      total: () => createCohortSignalRef("branchCount"),
+      count: (outcome) => createCohortSignalRef(`${outcome}Count`),
+      every: (outcome) => createCohortLeafFromCondition({
+        _tag: "signal",
+        signal: `${outcome}Count`,
+        operator: "equal",
+        value: { fact: "branchCount" }
+      }),
+      some: (outcome) => createCohortLeafFromCondition({
+        _tag: "signal",
+        signal: `${outcome}Count`,
+        operator: "greaterThan",
+        value: 0
+      })
+    },
+    stepSignalsList: {
+      pluck: (signalKey) => createStepSignalsListBuilder([{ op: "pluck", signalKey }])
+    },
+    all: (...refs) => createCohortGroup("all", refs),
+    any: (...refs) => createCohortGroup("any", refs)
+  };
+}
 export {
+  serializeCohortAdvancementPolicy,
   serializeAdvancementPolicy,
+  makeAdvanceEachCtx,
   makeAdvanceCtx,
+  makeAdvanceAllCtx,
+  extractInlineStepSignalsListDefinitions,
   extractInlineComputedSignals,
+  cohortAdvancementEventTypeValues,
+  branchOutcomeValues,
   Rule,
   Computed
 };

package/dist/definitions/pipelines/builder-helpers.d.ts

@@ -1,12 +1,35 @@
 import { z, type ZodType } from "zod";
 import { type AdditionalStepInputBinding, type TypedStepDefinitionSpec } from "../steps/define-step";
-import { type AnyBinding, type LiteralBinding, type StepOutputBinding, type StepSignalBinding, type WorkItemBinding } from "./define-pipeline";
+import { type AnyBinding, type FanOutItemBinding, type LiteralBinding, type SignalsListBinding, type StepOutputBinding, type StepSignalBinding, type WorkItemBinding } from "./define-pipeline";
 import { type InputAccessor } from "./input-accessor";
 export type AnyTypedStep = TypedStepDefinitionSpec<any, any, any, any>;
-export type StepConfig = {
-    timeout?: number | null;
-};
 type ElementOf<T extends ReadonlyArray<unknown>> = T extends ReadonlyArray<infer U> ? U : never;
+export type LastStep<T extends ReadonlyArray<AnyTypedStep>> = T extends readonly [...AnyTypedStep[], infer L] ? L extends AnyTypedStep ? L : never : never;
+export type LastSignalKeys<T extends ReadonlyArray<AnyTypedStep>> = LastStep<T> extends AnyTypedStep ? LastStep<T>["__signalKeys"] : never;
+/**
+ * The per-branch `item` type a fan-out's `over` key resolves to (issue
+ * #167): `never` unless `K` names a signal on the most recent ordinary step
+ * (`LastStep<TSteps>`) whose resolved TS type is itself an array — in which
+ * case this is that array's element type. A number-typed signal (count-only
+ * mode) resolves to `never`, which is how `FanOutInputCtx` below decides
+ * whether `item` exists on the ctx type at all.
+ */
+export type FanOutItemType<TSteps extends ReadonlyArray<AnyTypedStep>, K extends string> = K extends keyof LastStep<TSteps>["__signalTypeMap"] ? LastStep<TSteps>["__signalTypeMap"][K] extends ReadonlyArray<infer Item> ? Item : never : never;
+/**
+ * A fan-out's own `input` mapper ctx: everything `StepInputCtx` already
+ * offers, plus `item` when `FanOutItemType` resolves to something other
+ * than `never`. `item`'s exposed type is intersected with `FanOutItemBinding`
+ * (the same "phantom binding" trick `WithWorkItemFields`/`InputAccessor`
+ * use elsewhere in this file) so it reads as the real per-item TS type
+ * (e.g. `string`) to callers while still structurally satisfying `AnyBinding`
+ * when assigned straight into a `FanOutInputMapping` field — at runtime it
+ * is always the single `{ source: "fan_out_item" }` binding object,
+ * regardless of `Item`'s shape.
+ */
+export type FanOutInputCtx<TInput extends ZodType, TSteps extends ReadonlyArray<AnyTypedStep>, TFanOuts extends ReadonlyArray<AnyTypedStep>, K extends string> = StepInputCtx<TInput, TSteps, TFanOuts> & (FanOutItemType<TSteps, K> extends never ? unknown : {
+    item: FanOutItemBinding & FanOutItemType<TSteps, K>;
+});
+export type IsAny<T> = 0 extends 1 & T ? true : false;
 export type WorkItemAccessor = {
     readonly title: WorkItemBinding;
     readonly description: WorkItemBinding;
@@ -21,20 +44,28 @@ export type WithWorkItemFields<T> = {
     workItemDescription: string | null;
     workItemComments: PinnedWorkItemComment[];
 } & T;
-type RequiredInputKeys<T extends object> = {
+export type RequiredInputKeys<T extends object> = {
     [K in keyof T & string]-?: undefined extends T[K] ? never : K;
 }[keyof T & string];
-type OptionalInputKeys<T extends object> = {
+export type OptionalInputKeys<T extends object> = {
     [K in keyof T & string]-?: undefined extends T[K] ? K : never;
 }[keyof T & string];
 type Prettify<T> = {
     [K in keyof T]: T[K];
 } & {};
-export type StepInputCtx<TInput extends ZodType, TSteps extends ReadonlyArray<AnyTypedStep>> = {
+export type StepInputCtx<TInput extends ZodType, TSteps extends ReadonlyArray<AnyTypedStep>, TFanOuts extends ReadonlyArray<AnyTypedStep> = []> = {
     input: InputAccessor<Prettify<WithWorkItemFields<TInput["_output"]>>>;
     signal: <S extends ElementOf<TSteps>>(step: S, key: S["__signalKeys"]) => StepSignalBinding;
     output: (step: ElementOf<TSteps>) => StepOutputBinding;
     literal: (value: unknown) => LiteralBinding;
+    /**
+     * Reaches a fan-out's whole cohort — every terminal branch's own signals
+     * + output, resolved server-side — from a later, non-adjacent step's
+     * input mapper (issue #167). `fanOutStep` is constrained to a fan-out
+     * step already seen earlier in this pipeline (`.fanOutStep(fanOutStep, ...)`),
+     * the same way `signal`/`output` are constrained to `TSteps`.
+     */
+    signalsList: (fanOutStep: ElementOf<TFanOuts>) => SignalsListBinding;
 };
 type ReservedPipelineInputKeys = "workItemTitle" | "workItemDescription" | "workItemComments";
 export type NoReservedKeys<T extends ZodType> = T extends {
@@ -66,7 +97,7 @@ export type PipelineMeta<TInput extends ZodType = z.ZodUnknown> = {
     };
 };
 export declare const WORK_ITEM_ACCESSOR: WorkItemAccessor;
-export declare function makeStepInputCtx<TInput extends ZodType>(inputSchema: TInput): StepInputCtx<TInput, ReadonlyArray<AnyTypedStep>>;
+export declare function makeStepInputCtx<TInput extends ZodType>(inputSchema: TInput): StepInputCtx<TInput, ReadonlyArray<AnyTypedStep>, ReadonlyArray<AnyTypedStep>>;
 export declare function literal(value: unknown): LiteralBinding;
 export declare function normalizeInputMapping(mapping: Record<string, AnyBinding | undefined> | undefined): Record<string, AnyBinding> | undefined;
 export declare function resolveAdditionalStepInputBindings(label: "additionalStepInput", definition: PipelineMeta["additionalStepInput"] | undefined): Record<string, AnyBinding>;

package/dist/definitions/pipelines/builder.d.ts

@@ -1,74 +1,80 @@
 import { z, type ZodType } from "zod";
 import { type AdvanceCtx, type AdvanceResult } from "../advancement-policies/fluent-rules";
-import { type AnyBinding, type PipelineDefinitionSpec, type PipelineStepConfig } from "./define-pipeline";
-import { type AnyTypedStep, type PipelineMeta, type StepConfig, type StepInputCtx } from "./builder-helpers";
-export type { AnyTypedStep, PipelineMeta, StepConfig, StepInputCtx, WorkItemAccessor, } from "./builder-helpers";
-type LastStep<T extends ReadonlyArray<AnyTypedStep>> = T extends readonly [
-    ...AnyTypedStep[],
-    infer L
-] ? L extends AnyTypedStep ? L : never : never;
-type LastSignalKeys<T extends ReadonlyArray<AnyTypedStep>> = LastStep<T> extends AnyTypedStep ? LastStep<T>["__signalKeys"] : never;
-type LastSignalTypeMap<T extends ReadonlyArray<AnyTypedStep>> = LastStep<T> extends AnyTypedStep ? LastStep<T>["__signalTypeMap"] : Record<string, unknown>;
-type IsAny<T> = 0 extends 1 & T ? true : false;
-type RequiredInputKeys<T extends object> = {
-    [K in keyof T & string]-?: undefined extends T[K] ? never : K;
-}[keyof T & string];
-type OptionalInputKeys<T extends object> = {
-    [K in keyof T & string]-?: undefined extends T[K] ? K : never;
-}[keyof T & string];
+import { type AnyBinding, type PipelineDefinitionSpec, type PipelineNodeConfig } from "./define-pipeline";
+import { type AnyTypedStep, type IsAny, type LastSignalKeys, type OptionalInputKeys, type PipelineMeta, type RequiredInputKeys, type StepInputCtx } from "./builder-helpers";
+import { type FanOutStepConfig } from "./fan-out-builder";
+export type { AnyTypedStep, PipelineMeta, StepInputCtx, WorkItemAccessor, } from "./builder-helpers";
+export { type FanOutStepConfig, type FanOutInputMapping, } from "./fan-out-builder";
 type StepInputMapping<S extends AnyTypedStep> = IsAny<S["__inputType"]> extends true ? Partial<Record<string, AnyBinding>> : S["__inputType"] extends object ? {
     [K in RequiredInputKeys<S["__inputType"]>]: AnyBinding;
 } & {
     [K in OptionalInputKeys<S["__inputType"]>]?: AnyBinding;
 } : Partial<Record<string, AnyBinding>>;
 /**
- * Returned by `.step()`. Requires `.advance()` before the pipeline can
- * continue. Also accepts `.timeout()` before `.advance()`.
+ * `.step()`'s single options argument. Deliberately a single generic type
+ * (not a set of overload signatures split on `S["__hasAdditionalInput"]`):
+ * with overloads, a mistake inside `options.input`'s return value fails
+ * every overload, and TS reports "no overload matches" against the whole
+ * call rather than pointing at the specific missing/wrong property inside
+ * `input`'s return type. A single signature lets TS check `options`
+ * structurally in one pass and localize the error correctly.
  */
-export declare class PipelineStepAdvancementBuilder<TInput extends ZodType, TSteps extends ReadonlyArray<AnyTypedStep>> {
-    protected readonly inputSchema: TInput;
-    protected readonly meta: Omit<PipelineMeta<TInput>, "additionalPipelineInput" | "additionalStepInput">;
-    protected readonly steps: PipelineStepConfig[];
-    protected readonly pipelineInputBindings: Record<string, AnyBinding>;
-    protected readonly pipelineStepInputBindings: Record<string, AnyBinding>;
-    readonly __steps: TSteps;
-    constructor(inputSchema: TInput, meta: Omit<PipelineMeta<TInput>, "additionalPipelineInput" | "additionalStepInput">, steps: PipelineStepConfig[], pipelineInputBindings?: Record<string, AnyBinding>, pipelineStepInputBindings?: Record<string, AnyBinding>);
-    advance(callback: (ctx: AdvanceCtx<LastSignalKeys<TSteps>, LastSignalTypeMap<TSteps>>) => AdvanceResult<LastSignalKeys<TSteps>>): PipelineStepBuilder<TInput, TSteps>;
-}
+type StepOptions<TInput extends ZodType, TSteps extends ReadonlyArray<AnyTypedStep>, TFanOuts extends ReadonlyArray<AnyTypedStep>, S extends AnyTypedStep> = (S extends {
+    __hasAdditionalInput: false;
+} ? {
+    input?: (ctx: StepInputCtx<TInput, TSteps, TFanOuts>) => Partial<Record<string, AnyBinding>>;
+} : {
+    input: (ctx: StepInputCtx<TInput, TSteps, TFanOuts>) => StepInputMapping<S>;
+}) & {
+    advance: (ctx: AdvanceCtx<S["__signalKeys"], S["__signalTypeMap"]>) => AdvanceResult<S["__signalKeys"]>;
+    timeout?: number | null;
+};
 /**
- * Returned by `.advance()`. Provides `.step()` to chain additional steps,
- * `.timeout()` to set timeout after advancing, and `.build()` to finalize.
+ * Returned by `.step()`/`pipeline()`. Provides `.step()` to chain the next
+ * step, `.fanOutStep()` to begin a fan-out+cohort-gate pair (issue #167),
+ * and `.build()` to finalize. `.step()` requires an `advance` callback in
+ * its options — deciding how the pipeline continues past this step — as
+ * part of the same call that declares the step's input, rather than as a
+ * separate chained method on an intermediate builder class.
  */
-export declare class PipelineStepBuilder<TInput extends ZodType, TSteps extends ReadonlyArray<AnyTypedStep>> {
+export declare class PipelineStepBuilder<TInput extends ZodType, TSteps extends ReadonlyArray<AnyTypedStep>, TFanOuts extends ReadonlyArray<AnyTypedStep> = []> {
     protected readonly inputSchema: TInput;
     protected readonly meta: Omit<PipelineMeta<TInput>, "additionalPipelineInput" | "additionalStepInput">;
-    protected readonly steps: PipelineStepConfig[];
+    protected readonly nodes: PipelineNodeConfig[];
     protected readonly pipelineInputBindings: Record<string, AnyBinding>;
     protected readonly pipelineStepInputBindings: Record<string, AnyBinding>;
     readonly __steps: TSteps;
-    constructor(inputSchema: TInput, meta: Omit<PipelineMeta<TInput>, "additionalPipelineInput" | "additionalStepInput">, steps: PipelineStepConfig[], pipelineInputBindings?: Record<string, AnyBinding>, pipelineStepInputBindings?: Record<string, AnyBinding>);
-    step<S extends AnyTypedStep & {
-        __hasAdditionalInput: false;
-    }>(step: S, mapper?: (ctx: StepInputCtx<TInput, TSteps>) => Partial<Record<string, AnyBinding>>, configFn?: (config: StepConfig) => void): PipelineStepAdvancementBuilder<TInput, [...TSteps, S]>;
-    step<S extends AnyTypedStep>(step: S, mapper: (ctx: StepInputCtx<TInput, TSteps>) => StepInputMapping<S>, configFn?: (config: StepConfig) => void): PipelineStepAdvancementBuilder<TInput, [...TSteps, S]>;
+    readonly __fanOuts: TFanOuts;
+    constructor(inputSchema: TInput, meta: Omit<PipelineMeta<TInput>, "additionalPipelineInput" | "additionalStepInput">, nodes: PipelineNodeConfig[], pipelineInputBindings?: Record<string, AnyBinding>, pipelineStepInputBindings?: Record<string, AnyBinding>);
+    step<S extends AnyTypedStep>(step: S, options: StepOptions<TInput, TSteps, TFanOuts, S>): PipelineStepBuilder<TInput, [...TSteps, S], TFanOuts>;
+    /**
+     * Begins a fan-out+cohort-gate pair (issue #167): `step` is the template
+     * every branch executes, with its branch count (and, when `over` names
+     * an array-typed signal, each branch's own typed `item`) resolved at
+     * runtime from `config.over` (a signal on the step immediately
+     * preceding this fan-out). `config` requires both `advance` (each
+     * branch's own continue/block decision) and `advanceAll` (the
+     * whole-cohort decision — a pure gate, not a step; nothing besides the
+     * fan-out+gate pair itself is appended to the pipeline's node sequence)
+     * up front, mirroring how `.step()` requires `advance` in its own
+     * options rather than as a separate chained call.
+     */
+    fanOutStep<S extends AnyTypedStep, K extends LastSignalKeys<TSteps>>(step: S, config: FanOutStepConfig<TInput, TSteps, TFanOuts, S, K>): PipelineStepBuilder<TInput, TSteps, [...TFanOuts, S]>;
     build(): PipelineDefinitionSpec;
 }
 /**
  * Entry-point builder returned by `pipeline()`. Only exposes `.step()` —
- * call that to receive a `PipelineStepAdvancementBuilder` which requires
- * `.advance()` before the pipeline can proceed.
+ * call that to receive a `PipelineStepBuilder`, which chains further
+ * `.step()`/`.fanOutStep()` calls or finalizes with `.build()`.
  */
 export declare class PipelineBuilder<TInput extends ZodType> {
     private readonly inputSchema;
     private readonly meta;
-    private readonly steps;
+    private readonly nodes;
     private readonly pipelineInputBindings;
     private readonly pipelineStepInputBindings;
     constructor(meta: PipelineMeta<TInput>);
-    step<S extends AnyTypedStep & {
-        __hasAdditionalInput: false;
-    }>(step: S, mapper?: (ctx: StepInputCtx<TInput, []>) => Partial<Record<string, AnyBinding>>, configFn?: (config: StepConfig) => void): PipelineStepAdvancementBuilder<TInput, [S]>;
-    step<S extends AnyTypedStep>(step: S, mapper: (ctx: StepInputCtx<TInput, []>) => StepInputMapping<S>, configFn?: (config: StepConfig) => void): PipelineStepAdvancementBuilder<TInput, [S]>;
+    step<S extends AnyTypedStep>(step: S, options: StepOptions<TInput, [], [], S>): PipelineStepBuilder<TInput, [S]>;
 }
 export { literal } from "./builder-helpers";
 export declare function pipeline<TInput extends ZodType = z.ZodUnknown>(meta: PipelineMeta<TInput>): PipelineBuilder<TInput>;

package/dist/definitions/pipelines/chain-graph.d.ts

@@ -0,0 +1,19 @@
+import type { DependencyEdgeSpec, NodeDefinitionSpec } from "./define-pipeline";
+/**
+ * Orders `nodeDefinitions` by walking `dependencyEdges` from the single root
+ * to the single leaf. Returns `null` (does not throw) on any structural
+ * problem: multiple roots, a node with more than one outgoing edge, a node
+ * with more than one incoming edge, a cycle, or a disconnected node.
+ */
+export declare function tryOrderChainNodeDefinitions(nodeDefinitions: readonly NodeDefinitionSpec[], dependencyEdges: readonly DependencyEdgeSpec[]): NodeDefinitionSpec[] | null;
+/**
+ * Builds one dependency edge between each consecutive pair of `orderedNodes`,
+ * in the order given. Used to synthesize a chain's edges from an already-known
+ * author order (e.g. declaration order in `.step()` calls).
+ */
+export declare function buildChainDependencyEdges(orderedNodes: readonly Pick<NodeDefinitionSpec, "nodeKey">[]): DependencyEdgeSpec[];
+/**
+ * `tryOrderChainNodeDefinitions`, but throws a descriptive error instead of
+ * returning `null` when the graph isn't a single valid chain.
+ */
+export declare function orderChainNodeDefinitions(nodeDefinitions: readonly NodeDefinitionSpec[], dependencyEdges: readonly DependencyEdgeSpec[]): NodeDefinitionSpec[];

package/dist/definitions/pipelines/define-default-pipeline-assignment.d.ts

@@ -185,10 +185,10 @@ type SerializedAssignmentRule = {
 export type SerializedDefaultPipelineAssignment = {
     /**
      * Pipeline key for the primary assign pipeline; resolved to a
-     * `linearPipelineDefinitionId` by the push layer. Null when `default`
+     * `pipelineDefinitionId` by the push layer. Null when `default`
      * is `skip()` and no rule assigns a pipeline (push will reject this).
      */
-    linearPipelineDefinitionKey: string;
+    pipelineDefinitionKey: string;
     rulesJson: {
         rules: SerializedAssignmentRule[];
     };
@@ -199,7 +199,7 @@ export type SerializedDefaultPipelineAssignment = {
 /**
  * Serialize a `DefaultPipelineAssignmentSpec` to the wire format.
  *
- * `linearPipelineDefinitionKey` is the key of the primary assign pipeline —
+ * `pipelineDefinitionKey` is the key of the primary assign pipeline —
  * taken from `default` if it's `assign(...)`, otherwise from the first rule
  * that assigns a pipeline. The push layer rejects specs with no assign outcome.
  */

package/dist/definitions/pipelines/define-pipeline.d.ts

@@ -1,6 +1,7 @@
 import { type ZodType } from "zod";
 import type { StepDefinitionSpec, TypedStepDefinitionSpec } from "../steps/define-step";
 import { type AdvancementPolicy, type SerializedAdvancementPolicy, type SerializedComputedSignalDefinition } from "../advancement-policies/define-advancement-policy";
+import { type CohortAdvancementPolicy, type SerializedCohortAdvancementPolicy, type SerializedStepSignalsListDefinition } from "../advancement-policies/cohort-advancement-policy";
 export type { AdvancementPolicy, PipelineStepComputedSignalType, } from "../advancement-policies/define-advancement-policy";
 export { Computed, Rule, } from "../advancement-policies/define-advancement-policy";
 type AnyTypedStep = TypedStepDefinitionSpec<any, any, any, any>;
@@ -25,7 +26,31 @@ export type LiteralBinding = {
     source: "literal";
     value: unknown;
 };
-export type AnyBinding = PipelineInputBinding | WorkItemBinding | StepSignalBinding | StepOutputBinding | LiteralBinding;
+/**
+ * `ctx.signalsList(fanOutStep)`'s binding (issue #167): reaches a fan-out's
+ * whole cohort — every terminal branch's own signals + output — from a
+ * later, non-adjacent step's input mapper. Resolved server-side against
+ * `ResolvedNodeInputContext.cohorts[stepKey]` (an array of
+ * `{ branchIndex, signals, outputJson }`, sorted by `branchIndex`).
+ */
+export type SignalsListBinding = {
+    source: "signals_list";
+    fanOutStep: AnyTypedStep;
+};
+/**
+ * `.fanOutStep(step, config)`'s own `input` ctx's `item` binding (issue
+ * #167): resolves server-side, per branch, to that branch's own item value
+ * — the element of the array `config.over` names, when `over` resolves to
+ * an array (count-only mode has no `item` to bind, both at the type level
+ * — see `FanOutItemType` — and at the wire level, since no `fanOut` node
+ * config would carry an `item` binding for it). Carries no extra fields:
+ * the branch index alone (implicit in which branch is executing) is enough
+ * to resolve the right element server-side.
+ */
+export type FanOutItemBinding = {
+    source: "fan_out_item";
+};
+export type AnyBinding = PipelineInputBinding | WorkItemBinding | StepSignalBinding | StepOutputBinding | LiteralBinding | SignalsListBinding | FanOutItemBinding;
 export type PipelineStepConfig<TStep extends AnyTypedStep = AnyTypedStep> = {
     step: TStep;
     /** Maps each step input field to an input source. Extra keys are ignored at runtime. */
@@ -43,7 +68,50 @@ export type PipelineStepConfig<TStep extends AnyTypedStep = AnyTypedStep> = {
      */
     advancement?: AdvancementPolicy<TStep["__signalKeys"]>;
 };
-type SerializedBinding = {
+/**
+ * `.fanOutStep(step, config)`'s node config (issue #167): a `fanOut` node
+ * whose `stepDefinitionId`/`stepDefinitionVersion` template is `fanOutStep`
+ * — the template every branch executes — and whose `advanceEach` policy
+ * each branch's own result is evaluated against. Pushes exactly one
+ * `fanOut` node onto the pipeline's node sequence (paired with exactly one
+ * `PipelineCohortGateNodeConfig` immediately after it — see `.advanceAll()`
+ * — never more than the fan-out+gate pair itself).
+ *
+ * Named `*StepConfig` (rather than a bare `PipelineFanOutConfig`) to reserve
+ * room for a future sibling `PipelineFanOutSubPipelineConfig` — a fan-out
+ * whose template is a whole sub-pipeline rather than a single step. That
+ * sibling is out of scope for issue #167 and is not implemented here.
+ */
+export type PipelineFanOutStepConfig<TStep extends AnyTypedStep = AnyTypedStep> = {
+    nodeType: "fanOut";
+    fanOutStep: TStep;
+    overSignalKey: string;
+    input?: Partial<{
+        [K in keyof NonNullable<TStep["__inputType"]> & string]: AnyBinding;
+    }>;
+    timeout?: number | null;
+    advanceEach?: CohortAdvancementPolicy;
+};
+/**
+ * `.advanceAll(callback)`'s node config (issue #167): the pure decision
+ * gate that aggregates a fan-out's cohort back together — no work of its
+ * own, so no `step`/`input`/`timeout`. `nodeKey` is derived by the builder
+ * (`${fanOutStep.key}__cohortGate`), not user-supplied.
+ */
+export type PipelineCohortGateNodeConfig = {
+    nodeType: "cohortGate";
+    nodeKey: string;
+    advanceAll?: CohortAdvancementPolicy;
+    stepSignalsListDefinitions?: SerializedStepSignalsListDefinition[];
+};
+/**
+ * A single entry in a pipeline's declaration-order node sequence: an
+ * ordinary step, or one half of a fan-out+cohort-gate pair. Discriminated
+ * by the presence/value of `nodeType` (absent means a plain step) rather
+ * than a `kind` field, so `PipelineStepConfig` itself needs no change.
+ */
+export type PipelineNodeConfig = PipelineStepConfig | PipelineFanOutStepConfig | PipelineCohortGateNodeConfig;
+export type SerializedBinding = {
     source: "pipeline_input";
     path: string;
 } | {
@@ -59,6 +127,39 @@ type SerializedBinding = {
 } | {
     source: "literal";
     value: unknown;
+} | {
+    source: "signals_list";
+    stepKey: string;
+} | {
+    source: "fan_out_item";
+};
+export type NodeDefinitionKind = "step" | "fanOut" | "cohortGate";
+export type NodeDefinitionSpec = {
+    /** Unique within the pipeline; equals `stepKey` for a step/fanOut node, or the builder-derived gate key for a cohortGate node. */
+    nodeKey: string;
+    kind: NodeDefinitionKind;
+    /** `step`/`fanOut` only — the step template's key/version. Absent on a `cohortGate` node (it produces no work of its own). */
+    stepKey?: string;
+    stepName?: string;
+    stepDescription?: string | null;
+    inputBindingsJson?: Record<string, SerializedBinding>;
+    timeoutSeconds?: number | null;
+    /** `step` only. */
+    advancementPolicyDefinition?: SerializedAdvancementPolicy;
+    /** `step` only. */
+    computedSignalDefinitions?: SerializedComputedSignalDefinition[];
+    /** `fanOut` only — the signal its branch cardinality is resolved from. */
+    overSignalKey?: string;
+    /** `fanOut` only — each branch's own continue/block decision. */
+    advanceEachPolicyDefinition?: SerializedCohortAdvancementPolicy;
+    /** `cohortGate` only — the whole cohort's continue/block decision. */
+    advanceAllPolicyDefinition?: SerializedCohortAdvancementPolicy;
+    /** `cohortGate` only — every `ctx.stepSignalsList`-derived value `advanceAll`'s rules may reference. */
+    stepSignalsListDefinitions?: SerializedStepSignalsListDefinition[];
+};
+export type DependencyEdgeSpec = {
+    fromNodeKey: string;
+    toNodeKey: string;
 };
 export type PipelineDefinitionSpec = {
     key: string;
@@ -67,16 +168,8 @@ export type PipelineDefinitionSpec = {
     version: number;
     status: "draft" | "active" | "archived";
     inputSchemaJson?: Record<string, unknown> | null;
-    steps: Array<{
-        stepKey: string;
-        stepName: string;
-        stepDescription: string | null;
-        position: number;
-        inputBindingsJson: Record<string, SerializedBinding>;
-        timeoutSeconds: number | null;
-        advancementPolicyDefinition: SerializedAdvancementPolicy;
-        computedSignalDefinitions: SerializedComputedSignalDefinition[];
-    }>;
+    nodeDefinitions: NodeDefinitionSpec[];
+    dependencyEdges: DependencyEdgeSpec[];
     /** Step specs referenced by this pipeline. Used by the push command to auto-push steps that aren't explicitly exported. */
     _stepDefinitions?: StepDefinitionSpec[];
 };
@@ -87,7 +180,7 @@ export type DefinePipelineInput = {
     version?: number;
     status?: "draft" | "active";
     input?: ZodType | null;
-    steps: ReadonlyArray<PipelineStepConfig>;
+    nodes: ReadonlyArray<PipelineNodeConfig>;
     pipelineInputBindings?: Record<string, AnyBinding>;
 };
 export declare function buildPipelineSpec(config: DefinePipelineInput): PipelineDefinitionSpec;