@boboddy/sdk 0.3.1 → 0.4.2

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;

package/dist/definitions/pipelines/fan-out-builder.d.ts

@@ -0,0 +1,66 @@
+import type { ZodType } from "zod";
+import { type AdvanceAllCtx, type AdvanceAllResult, type AdvanceEachCtx, type AdvanceEachResult } from "../advancement-policies/cohort-fluent-rules";
+import { type AnyTypedStep, type FanOutInputCtx, type IsAny, type LastSignalKeys, type PipelineMeta, type RequiredInputKeys } from "./builder-helpers";
+import type { AnyBinding, PipelineNodeConfig } from "./define-pipeline";
+import { PipelineStepBuilder } from "./builder";
+/**
+ * `.fanOutStep()` (issue #167) split out of `builder.ts` (which would
+ * otherwise exceed this repo's `max-lines` limit) — genuinely mutually
+ * referential with `PipelineStepBuilder` (`beginFanOut` both is called from
+ * `PipelineStepBuilder.fanOutStep()` and returns a new one), so the import
+ * cycle is structural, not accidental.
+ */
+export type FanOutInputMapping<S extends AnyTypedStep> = Partial<Record<string, AnyBinding>> & (IsAny<S["__inputType"]> extends true ? unknown : S["__inputType"] extends object ? {
+    [K in RequiredInputKeys<S["__inputType"]>]: AnyBinding;
+} : unknown);
+/**
+ * `.fanOutStep(step, config)`'s sole config argument — `step` itself is a
+ * separate positional argument (mirroring `.step(step, options)`), not a
+ * field on this object. `K` is inferred from the literal value of
+ * `config.over` in the same pass TypeScript type-checks `config.input`,
+ * the same mechanism `builder.ts`'s `StepOptions` already relies on for
+ * `.step()` — see that type's doc comment for why overloads are avoided
+ * here too.
+ */
+export type FanOutStepConfig<TInput extends ZodType, TSteps extends ReadonlyArray<AnyTypedStep>, TFanOuts extends ReadonlyArray<AnyTypedStep>, S extends AnyTypedStep, K extends LastSignalKeys<TSteps> = LastSignalKeys<TSteps>> = {
+    /**
+     * The signal to resolve each branch from — constrained to the most
+     * recent ordinary step's declared signal keys (`TSteps`'s last element).
+     * Note this is the last *step*, not necessarily the fan-out's immediate
+     * graph predecessor: chaining a second `.fanOutStep()` right after
+     * `.advanceAll()` (with no intervening `.step()`) still only offers this
+     * same step's signals, since a `cohortGate` node produces no signals of
+     * its own to resolve from.
+     *
+     * A number-typed signal resolves a fixed branch count with no `item` on
+     * the input ctx (count-only mode); an array-typed signal resolves branch
+     * count from the array's length and adds a typed `item` to the input
+     * ctx for each branch.
+     */
+    over: K;
+    input?: (ctx: FanOutInputCtx<TInput, TSteps, TFanOuts, K>) => FanOutInputMapping<S>;
+    /**
+     * Every branch's own continue/block decision (even the default "always
+     * continue" must be declared explicitly) — evaluated once per branch
+     * against that branch's own signals.
+     */
+    advance: (ctx: AdvanceEachCtx<S["__signalKeys"], S["__signalTypeMap"]>) => AdvanceEachResult;
+    /**
+     * The whole-cohort decision, evaluated once the fan-out's branches have
+     * settled — a pure gate, not a step: nothing besides the fan-out+gate
+     * pair itself is appended to the pipeline's node sequence.
+     */
+    advanceAll: (ctx: AdvanceAllCtx) => AdvanceAllResult;
+    timeout?: number | null;
+};
+/**
+ * Builds and pushes the `fanOut`+`cohortGate` node pair, resolves both the
+ * per-branch (`advance`) and whole-cohort (`advanceAll`) policies from
+ * `config`, and returns straight into a `PipelineStepBuilder` — mirroring
+ * how `pushStep` in `builder.ts` resolves a step's `advance` policy inline
+ * rather than through a chained `.advance()` call on an intermediate
+ * builder. Called from `PipelineStepBuilder.fanOutStep()` — factored out
+ * here (rather than inlined there) purely to keep the node-construction
+ * logic next to the types it feeds.
+ */
+export declare function beginFanOut<TInput extends ZodType, TSteps extends ReadonlyArray<AnyTypedStep>, TFanOuts extends ReadonlyArray<AnyTypedStep>, S extends AnyTypedStep, K extends LastSignalKeys<TSteps> = LastSignalKeys<TSteps>>(inputSchema: TInput, meta: Omit<PipelineMeta<TInput>, "additionalPipelineInput" | "additionalStepInput">, nodes: PipelineNodeConfig[], pipelineInputBindings: Record<string, AnyBinding>, pipelineStepInputBindings: Record<string, AnyBinding>, step: S, config: FanOutStepConfig<TInput, TSteps, TFanOuts, S, K>): PipelineStepBuilder<TInput, TSteps, [...TFanOuts, S]>;