@boboddy/sdk 0.4.3 → 0.5.0

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

@@ -1,165 +1,114 @@
-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";
+import { z, type ZodType } from "zod";
+import type { StepDefinitionSpec } from "../steps/define-step";
+import type { SerializedAdvancementPolicy, SerializedComputedSignalDefinition, SerializedCondition } from "../advancement-policies/define-advancement-policy";
+import type { SerializedCohortAdvancementPolicy, SerializedStepSignalsListDefinition } from "../advancement-policies/cohort-advancement-policy";
+import type { SerializedBinding } from "./bindings";
+import type { DefinePipelineInput } from "./pipeline-states";
 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>;
-export type PipelineInputBinding = {
-    source: "pipeline_input";
-    path: string;
+export * from "./pipeline-states";
+export * from "./node-input-ctx";
+export * from "./bindings";
+export type NodeDefinitionKind = "step" | "fanOut" | "cohortGate" | "choice" | "parallel" | "loop" | "succeed" | "fail";
+export type ChoiceCaseSpec = {
+    conditionJson: SerializedCondition;
+    targetNodeKey: string;
 };
-export type WorkItemBinding = {
-    source: "work_item";
-    field: string;
-};
-export type StepSignalBinding = {
-    source: "step_signal";
-    step: AnyTypedStep;
-    signalKey: string;
-};
-export type StepOutputBinding = {
-    source: "step_output";
-    step: AnyTypedStep;
-};
-export type LiteralBinding = {
-    source: "literal";
-    value: unknown;
-};
-/**
- * `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;
+export type ParallelBranchSpec = {
+    stepKey: string;
+    stepName: string;
+    stepDescription: string | null;
+    inputBindingsJson: Record<string, SerializedBinding>;
 };
 /**
- * `.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.
+ * Fields shared by every node kind that does its own work by running a step
+ * template (`step`/`fanOut`/`loop`) — the step's own key/name/description,
+ * its resolved input bindings, and its timeout. Intersected into each of
+ * those three kinds' own type below rather than duplicated field-for-field.
  */
-export type FanOutItemBinding = {
-    source: "fan_out_item";
+type StepTemplateFields = {
+    stepKey: string;
+    stepName: string;
+    stepDescription: string | null;
+    inputBindingsJson: Record<string, SerializedBinding>;
+    timeoutSeconds: number | null;
 };
-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. */
-    input?: Partial<{
-        [K in keyof NonNullable<TStep["__inputType"]> & string]: AnyBinding;
-    }>;
-    timeout?: number | null;
-    /**
-     * Controls when and how this step advances in the pipeline.
-     * Signal keys in `Rule.signal()` / `Rule.when()` calls are type-checked
-     * against the step's declared signals. Inline `Computed.X(...)` tokens can
-     * also appear in the signal position; they're hoisted into the step's
-     * `computedSignalDefinitions` at serialization time.
-     * Defaults to `{ defaultOutcome: "continue" }` when omitted.
-     */
-    advancement?: AdvancementPolicy<TStep["__signalKeys"]>;
+export type StepNodeDefinitionSpec = StepTemplateFields & {
+    nodeKey: string;
+    kind: "step";
+    advancementPolicyDefinition: SerializedAdvancementPolicy;
+    computedSignalDefinitions: SerializedComputedSignalDefinition[];
 };
-/**
- * `.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;
+export type FanOutNodeDefinitionSpec = StepTemplateFields & {
+    nodeKey: string;
+    kind: "fanOut";
+    /** The signal its branch cardinality is resolved from. */
     overSignalKey: string;
-    input?: Partial<{
-        [K in keyof NonNullable<TStep["__inputType"]> & string]: AnyBinding;
-    }>;
-    timeout?: number | null;
-    advanceEach?: CohortAdvancementPolicy;
+    /** Each branch's own continue/block decision. */
+    advanceEachPolicyDefinition: SerializedCohortAdvancementPolicy;
+    /** Caps how many branches release to the claim pool up front. */
+    maxConcurrency: number | null;
 };
-/**
- * `.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";
+export type CohortGateNodeDefinitionSpec = {
     nodeKey: string;
-    advanceAll?: CohortAdvancementPolicy;
-    stepSignalsListDefinitions?: SerializedStepSignalsListDefinition[];
+    kind: "cohortGate";
+    /** The whole cohort's continue/block decision. */
+    advanceAllPolicyDefinition: SerializedCohortAdvancementPolicy;
+    /** Every `ctx.stepSignalsList`-derived value `advanceAll`'s rules may reference. */
+    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;
-} | {
-    source: "work_item";
-    field: string;
-} | {
-    source: "step_signal";
-    stepKey: string;
-    signalKey: string;
-} | {
-    source: "step_output";
-    stepKey: string;
-} | {
-    source: "literal";
-    value: unknown;
-} | {
-    source: "signals_list";
-    stepKey: string;
-} | {
-    source: "fan_out_item";
+export type ChoiceNodeDefinitionSpec = {
+    nodeKey: string;
+    kind: "choice";
+    /** The routing table — may be empty when `default` alone covers every case. */
+    choices: ChoiceCaseSpec[];
+    /** The fallback target when no `choices[]` entry matches. */
+    default: string | null;
 };
-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. */
+export type ParallelNodeDefinitionSpec = {
     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. */
+    kind: "parallel";
+    /** Its named, single-step branches. */
+    branches: Record<string, ParallelBranchSpec>;
+    /** The whole cohort's continue/block decision — absent means "continue iff every branch continued." */
     advanceAllPolicyDefinition?: SerializedCohortAdvancementPolicy;
-    /** `cohortGate` only — every `ctx.stepSignalsList`-derived value `advanceAll`'s rules may reference. */
-    stepSignalsListDefinitions?: SerializedStepSignalsListDefinition[];
 };
+export type LoopNodeDefinitionSpec = StepTemplateFields & {
+    nodeKey: string;
+    kind: "loop";
+    maxIterations: number;
+    /** The condition tested after each iteration. */
+    untilConditionJson: SerializedCondition;
+};
+/** `succeed`/`fail` carry no fields of their own besides `nodeKey`/`kind`. */
+export type TerminalNodeDefinitionSpec = {
+    nodeKey: string;
+    kind: "succeed" | "fail";
+};
+/**
+ * One compiled node in the pipeline's graph, discriminated by `kind` — each
+ * kind's own fields (see its type above) are the only ones legal on it; a
+ * `choice` node has no `stepKey`, a `step` node has no `choices`, etc. The
+ * ones that need real ids (a `step`/`fanOut`/`loop`'s `stepKey`, a
+ * `parallel` branch's own `stepKey`) are resolved to `stepDefinitionId`s by
+ * `pipeline-definitions-client.ts` at push time, not here — this spec only
+ * ever carries author-declared keys.
+ */
+export type NodeDefinitionSpec = StepNodeDefinitionSpec | FanOutNodeDefinitionSpec | CohortGateNodeDefinitionSpec | ChoiceNodeDefinitionSpec | ParallelNodeDefinitionSpec | LoopNodeDefinitionSpec | TerminalNodeDefinitionSpec;
+/** The kinds that run a step template and therefore carry `StepTemplateFields`. */
+export type WorkingNodeDefinitionSpec = StepNodeDefinitionSpec | FanOutNodeDefinitionSpec | LoopNodeDefinitionSpec;
+/** Narrows a `NodeDefinitionSpec` to the kinds that run a step template. */
+export declare function isWorkingNodeDefinition(node: NodeDefinitionSpec): node is WorkingNodeDefinitionSpec;
 export type DependencyEdgeSpec = {
     fromNodeKey: string;
     toNodeKey: string;
+    /**
+     * A `loop` node's `next`/`onExhausted` disambiguation
+     * (`{loopExit: "next" | "onExhausted"}` — the routing source of truth
+     * for `loop`) or a `choice` edge's designer-only display summary (never
+     * the routing source of truth for `choice` — see §4).
+     */
+    discriminantJson?: Record<string, unknown> | null;
 };
 export type PipelineDefinitionSpec = {
     key: string;
@@ -173,14 +122,12 @@ export type PipelineDefinitionSpec = {
     /** Step specs referenced by this pipeline. Used by the push command to auto-push steps that aren't explicitly exported. */
     _stepDefinitions?: StepDefinitionSpec[];
 };
-export type DefinePipelineInput = {
-    key: string;
-    name: string;
-    description?: string | null;
-    version?: number;
-    status?: "draft" | "active";
-    input?: ZodType | null;
-    nodes: ReadonlyArray<PipelineNodeConfig>;
-    pipelineInputBindings?: Record<string, AnyBinding>;
-};
-export declare function buildPipelineSpec(config: DefinePipelineInput): PipelineDefinitionSpec;
+/**
+ * Compiles a flat, ASL-flavored pipeline definition (see
+ * docs/research/flat-pipeline-sdk-and-visual-designer.md §4) into the wire
+ * `PipelineDefinitionSpec` shape. `states` is a map keyed by node key —
+ * there is no `dependsOn`; every node's incoming edge(s) are derived here
+ * by walking each state's own forward pointer(s) (`next`/`choices[].next`/
+ * `default`/`onExhausted`/branch-completion target).
+ */
+export declare function definePipeline<TInput extends ZodType = z.ZodUnknown>(config: DefinePipelineInput<TInput>): PipelineDefinitionSpec;

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

@@ -1,6 +1,4 @@
 export * from "./define-pipeline";
-export * from "./builder";
-export * from "./input-accessor";
 export * from "./pipeline-definitions-client";
 export * from "./define-default-pipeline-assignment";
 export * from "./work-item-fields";