@codemation/core 0.0.1

package/src/scheduler/HintOnlyOffloadPolicy.ts

@@ -0,0 +1,9 @@
+import type { NodeConfigBase, NodeId, NodeOffloadPolicy, NodeSchedulerDecision, WorkflowId } from "../types";
+
+export class HintOnlyOffloadPolicy implements NodeOffloadPolicy {
+  decide(args: { workflowId: WorkflowId; nodeId: NodeId; config: NodeConfigBase }): NodeSchedulerDecision {
+    const hint = args.config.execution?.hint;
+    if (hint === "worker") return { mode: "worker", queue: args.config.execution?.queue };
+    return { mode: "local" };
+  }
+}

package/src/scheduler/InlineDrivingScheduler.ts

@@ -0,0 +1,145 @@
+import type {
+  NodeActivationContinuation,
+  NodeActivationReceipt,
+  NodeActivationRequest,
+  NodeActivationScheduler,
+  RunId,
+} from "../types";
+import { NodeExecutor } from "../execution/NodeExecutor";
+
+export class InlineDrivingScheduler implements NodeActivationScheduler {
+  private continuation: NodeActivationContinuation | undefined;
+  private readonly drainingRuns = new Set<RunId>();
+  private readonly queuesByRunId = new Map<
+    RunId,
+    Array<Readonly<{ request: NodeActivationRequest; receipt: NodeActivationReceipt }>>
+  >();
+  private readonly scheduledRuns = new Set<RunId>();
+  private seq = 0;
+
+  constructor(private readonly nodeExecutor: NodeExecutor) {}
+
+  setContinuation(continuation: NodeActivationContinuation): void {
+    this.continuation = continuation;
+  }
+
+  async enqueue(request: NodeActivationRequest): Promise<NodeActivationReceipt> {
+    const receipt: NodeActivationReceipt = { receiptId: `inline_${++this.seq}`, mode: "local" };
+    const q = this.queuesByRunId.get(request.runId) ?? [];
+    q.push({ request, receipt });
+    this.queuesByRunId.set(request.runId, q);
+
+    return receipt;
+  }
+
+  notifyPendingStatePersisted(runId: RunId): void {
+    if ((this.queuesByRunId.get(runId)?.length ?? 0) === 0) {
+      return;
+    }
+    this.scheduleDrain(runId);
+  }
+
+  private async drainRun(runId: RunId): Promise<void> {
+    if (this.drainingRuns.has(runId)) return;
+    this.drainingRuns.add(runId);
+    this.scheduledRuns.delete(runId);
+    try {
+      const q = this.queuesByRunId.get(runId) ?? [];
+      while (q.length > 0) {
+        const next = q.shift()!;
+        const { request } = next;
+
+        const cont = this.continuation;
+        if (!cont) throw new Error("InlineDrivingScheduler is missing a continuation (setContinuation was not called)");
+
+        await cont.markNodeRunning({
+          runId: request.runId,
+          activationId: request.activationId,
+          nodeId: request.nodeId,
+          inputsByPort: request.kind === "multi" ? request.inputsByPort : { in: request.input },
+        });
+
+        let outputs;
+        try {
+          outputs = await this.nodeExecutor.execute(request);
+        } catch (e) {
+          await this.resumeAfterExecutionError(cont, request, this.asError(e));
+          continue;
+        }
+
+        await this.resumeAfterExecutionResult(cont, request, outputs ?? {});
+      }
+    } finally {
+      if ((this.queuesByRunId.get(runId)?.length ?? 0) === 0) this.queuesByRunId.delete(runId);
+      this.drainingRuns.delete(runId);
+      if ((this.queuesByRunId.get(runId)?.length ?? 0) > 0) {
+        this.scheduleDrain(runId);
+      }
+    }
+  }
+
+  private scheduleDrain(runId: RunId): void {
+    if (this.drainingRuns.has(runId) || this.scheduledRuns.has(runId)) {
+      return;
+    }
+    this.scheduledRuns.add(runId);
+    setTimeout(() => {
+      this.scheduledRuns.delete(runId);
+      void this.drainRun(runId);
+    }, 0);
+  }
+
+  private async resumeAfterExecutionResult(
+    continuation: NodeActivationContinuation,
+    request: NodeActivationRequest,
+    outputs: unknown,
+  ): Promise<void> {
+    try {
+      await continuation.resumeFromNodeResult({
+        runId: request.runId,
+        activationId: request.activationId,
+        nodeId: request.nodeId,
+        outputs: outputs as any,
+      });
+    } catch (e) {
+      this.rethrowUnlessIgnorableContinuationError(e);
+    }
+  }
+
+  private async resumeAfterExecutionError(
+    continuation: NodeActivationContinuation,
+    request: NodeActivationRequest,
+    error: Error,
+  ): Promise<void> {
+    try {
+      await continuation.resumeFromNodeError({
+        runId: request.runId,
+        activationId: request.activationId,
+        nodeId: request.nodeId,
+        error,
+      });
+    } catch (e) {
+      this.rethrowUnlessIgnorableContinuationError(e);
+    }
+  }
+
+  private asError(e: unknown): Error {
+    return e instanceof Error ? e : new Error(String(e));
+  }
+
+  private rethrowUnlessIgnorableContinuationError(e: unknown): void {
+    if (this.isIgnorableContinuationError(e)) {
+      return;
+    }
+    throw this.asError(e);
+  }
+
+  private isIgnorableContinuationError(e: unknown): boolean {
+    const message = this.asError(e).message;
+    return (
+      message.includes(" is not pending") ||
+      message.includes("activationId mismatch") ||
+      message.includes("nodeId mismatch")
+    );
+  }
+}

package/src/scheduler/InlineDrivingSchedulerFactory.ts

@@ -0,0 +1,9 @@
+import { NodeExecutor } from "../execution/NodeExecutor";
+
+import { InlineDrivingScheduler } from "./InlineDrivingScheduler";
+
+export class InlineDrivingSchedulerFactory {
+  create(nodeExecutor: NodeExecutor): InlineDrivingScheduler {
+    return new InlineDrivingScheduler(nodeExecutor);
+  }
+}

package/src/scheduler/LocalOnlyScheduler.ts

@@ -0,0 +1,7 @@
+import type { NodeExecutionRequest, NodeExecutionScheduler } from "../types";
+
+export class LocalOnlyScheduler implements NodeExecutionScheduler {
+  async enqueue(_request: NodeExecutionRequest): Promise<{ receiptId: string }> {
+    throw new Error("No worker scheduler configured");
+  }
+}

package/src/serialization/ItemsInputNormalizer.ts

@@ -0,0 +1,36 @@
+import type { Item, Items } from "../contracts/workflowTypes";
+import { injectable } from "../di";
+
+/**
+ * Normalizes external inputs into the engine's canonical `Items` shape.
+ * Used at host and builder boundaries where callers may provide either a raw value,
+ * a single item-like object, or an array of item-like values.
+ */
+@injectable()
+export class ItemsInputNormalizer {
+  normalize(raw: unknown): Items {
+    if (raw === undefined || raw === null) {
+      return [];
+    }
+    if (Array.isArray(raw)) {
+      return raw.map((value) => this.normalizeItem(value));
+    }
+    return [this.normalizeItem(raw)];
+  }
+
+  private normalizeItem(raw: unknown): Item {
+    if (!this.isItem(raw)) {
+      return { json: raw };
+    }
+    return {
+      json: raw.json,
+      ...(raw.binary === undefined ? {} : { binary: raw.binary }),
+      ...(raw.meta === undefined ? {} : { meta: raw.meta }),
+      ...(raw.paired === undefined ? {} : { paired: raw.paired }),
+    };
+  }
+
+  private isItem(raw: unknown): raw is Item {
+    return typeof raw === "object" && raw !== null && Object.prototype.hasOwnProperty.call(raw, "json");
+  }
+}

package/src/testing/RejectingCredentialSessionService.ts

@@ -0,0 +1,15 @@
+import type { CredentialSessionService } from "../contracts/credentialTypes";
+
+/**
+ * Test harness default: rejects any credential lookup so missing bindings fail loudly.
+ * Prefer registering a real {@link CredentialSessionService} in integration scenarios.
+ */
+export class RejectingCredentialSessionService implements CredentialSessionService {
+  async getSession<TSession = unknown>(
+    args: Readonly<{ workflowId: string; nodeId: string; slotKey: string }>,
+  ): Promise<TSession> {
+    throw new Error(
+      `Credential sessions are unavailable for workflow ${args.workflowId} node ${args.nodeId} slot "${args.slotKey}". Register a real CredentialSessionService implementation before executing workflows.`,
+    );
+  }
+}

package/src/testing.ts

@@ -0,0 +1,6 @@
+/**
+ * Test-only adapters and helpers. Not part of the supported production public API.
+ */
+export { InMemoryLiveWorkflowRepository } from "./runtime/InMemoryLiveWorkflowRepository";
+export { WorkflowSnapshotCodec as PersistedWorkflowSnapshotFactory } from "./workflowSnapshots/WorkflowSnapshotCodec";
+export { RejectingCredentialSessionService } from "./testing/RejectingCredentialSessionService";

package/src/types/index.ts

@@ -0,0 +1,12 @@
+export * from "../contracts/retryPolicySpec.types";
+export * from "../contracts/NoRetryPolicy";
+export * from "../contracts/RetryPolicy";
+export * from "../contracts/ExpRetryPolicy";
+export * from "../contracts/credentialTypes";
+export * from "../contracts/runtimeTypes";
+export * from "../contracts/runFinishedAtFactory";
+export * from "../contracts/runTypes";
+export * from "../contracts/webhookTypes";
+export * from "../contracts/workflowTypes";
+export * from "../contracts/workflowActivationPolicy";
+export * from "../workflow";

package/src/workflow/definition/ConnectionInvocationIdFactory.ts

@@ -0,0 +1,17 @@
+import { randomUUID } from "node:crypto";
+
+import type { NodeId } from "../../types";
+
+/**
+ * Unique ids for persisted connection invocation history rows (LLM/tool calls under an owning node).
+ */
+export class ConnectionInvocationIdFactory {
+  static create(): string {
+    return `cinv_${randomUUID()}`;
+  }
+
+  /** Deterministic id for tests when a stable sequence is needed. */
+  static createForTest(runId: string, connectionNodeId: NodeId, sequence: number): string {
+    return `cinv_${runId}_${connectionNodeId}_${sequence}`;
+  }
+}

package/src/workflow/definition/ConnectionNodeIdFactory.ts

@@ -0,0 +1,42 @@
+import type { NodeId } from "../../types";
+
+/**
+ * Deterministic ids for workflow connection-owned child nodes (LLM slot, tools, etc.).
+ * These are stable across loads.
+ */
+export class ConnectionNodeIdFactory {
+  static readonly connectionSegment = "__conn__" as const;
+
+  static languageModelConnectionNodeId(parentNodeId: NodeId): NodeId {
+    return `${parentNodeId}${this.connectionSegment}llm`;
+  }
+
+  static toolConnectionNodeId(parentNodeId: NodeId, toolName: string): NodeId {
+    const normalized = this.normalizeToolName(toolName);
+    return `${parentNodeId}${this.connectionSegment}tool${this.connectionSegment}${normalized}`;
+  }
+
+  static isLanguageModelConnectionNodeId(nodeId: NodeId): boolean {
+    return nodeId.endsWith(`${this.connectionSegment}llm`);
+  }
+
+  static isToolConnectionNodeId(nodeId: NodeId): boolean {
+    return nodeId.includes(`${this.connectionSegment}tool${this.connectionSegment}`);
+  }
+
+  /** True when `nodeId` is a connection-owned child of `parentNodeId` (LLM or tool slot). */
+  static isConnectionOwnedDescendantOf(parentNodeId: NodeId, nodeId: NodeId): boolean {
+    return nodeId.startsWith(`${parentNodeId}${this.connectionSegment}`);
+  }
+
+  /** Normalizes a tool display name to a stable id segment. */
+  static normalizeToolName(toolName: string): string {
+    return (
+      toolName
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "") || "tool"
+    );
+  }
+}

package/src/workflow/definition/WorkflowExecutableNodeClassifier.ts

@@ -0,0 +1,71 @@
+import type { NodeDefinition, NodeId, WorkflowDefinition } from "../../types";
+
+/**
+ * Derives which workflow nodes participate in the main execution graph vs connection-only children.
+ */
+export class WorkflowExecutableNodeClassifier {
+  private readonly connectionOwnedIds: ReadonlySet<NodeId>;
+
+  constructor(workflow: WorkflowDefinition) {
+    this.connectionOwnedIds = this.collectConnectionOwnedIds(workflow);
+  }
+
+  isConnectionOwnedNodeId(nodeId: NodeId): boolean {
+    return this.connectionOwnedIds.has(nodeId);
+  }
+
+  isExecutableNodeId(nodeId: NodeId): boolean {
+    return !this.connectionOwnedIds.has(nodeId);
+  }
+
+  filterExecutableNodeDefinitions(nodes: ReadonlyArray<NodeDefinition>): ReadonlyArray<NodeDefinition> {
+    return nodes.filter((n) => this.isExecutableNodeId(n.id));
+  }
+
+  private collectConnectionOwnedIds(workflow: WorkflowDefinition): ReadonlySet<NodeId> {
+    const ids = new Set<NodeId>();
+    for (const connection of workflow.connections ?? []) {
+      for (const childId of connection.childNodeIds) {
+        ids.add(childId);
+      }
+    }
+    return ids;
+  }
+
+  /**
+   * Resolves the default start node: first trigger, else first executable node with no incoming edges from executable nodes.
+   */
+  findDefaultExecutableStartNodeId(workflow: WorkflowDefinition): NodeId {
+    const firstTrigger = workflow.nodes.find((n) => n.kind === "trigger" && this.isExecutableNodeId(n.id))?.id;
+    if (firstTrigger) return firstTrigger;
+
+    const incoming = new Map<NodeId, number>();
+    for (const n of workflow.nodes) {
+      if (this.isExecutableNodeId(n.id)) incoming.set(n.id, 0);
+    }
+    for (const e of workflow.edges) {
+      if (!this.isExecutableNodeId(e.from.nodeId) || !this.isExecutableNodeId(e.to.nodeId)) continue;
+      incoming.set(e.to.nodeId, (incoming.get(e.to.nodeId) ?? 0) + 1);
+    }
+    const start = workflow.nodes.find((n) => this.isExecutableNodeId(n.id) && (incoming.get(n.id) ?? 0) === 0)?.id;
+    return (
+      start ??
+      workflow.nodes.find((n) => this.isExecutableNodeId(n.id))?.id ??
+      (() => {
+        throw new Error(`Workflow ${workflow.id} has no executable nodes`);
+      })()
+    );
+  }
+
+  firstExecutableNodeIdInDefinitionOrder(workflow: WorkflowDefinition): NodeId | undefined {
+    return workflow.nodes.find((n) => this.isExecutableNodeId(n.id))?.id;
+  }
+
+  lastExecutableNodeIdInDefinitionOrder(workflow: WorkflowDefinition): NodeId {
+    for (let i = workflow.nodes.length - 1; i >= 0; i--) {
+      const n = workflow.nodes[i]!;
+      if (this.isExecutableNodeId(n.id)) return n.id;
+    }
+    throw new Error(`Workflow ${workflow.id} has no executable nodes`);
+  }
+}

package/src/workflow/definition/WorkflowExecutableNodeClassifierFactory.ts

@@ -0,0 +1,9 @@
+import type { WorkflowDefinition } from "../../types";
+
+import { WorkflowExecutableNodeClassifier } from "./WorkflowExecutableNodeClassifier";
+
+export class WorkflowExecutableNodeClassifierFactory {
+  static create(workflow: WorkflowDefinition): WorkflowExecutableNodeClassifier {
+    return new WorkflowExecutableNodeClassifier(workflow);
+  }
+}

package/src/workflow/dsl/ChainCursorResolver.ts

@@ -0,0 +1,103 @@
+import type {
+  NodeRef,
+  OutputPortKey,
+  RunnableNodeConfig,
+  RunnableNodeOutputJson,
+  WorkflowDefinition,
+} from "../../types";
+
+import { WorkflowBuilder } from "./WorkflowBuilder";
+import { WhenBuilder } from "./WhenBuilder";
+import type {
+  AnyRunnableNodeConfig,
+  BooleanWhenOverloads,
+  BranchOutputGuard,
+  BranchStepsArg,
+  StepSequenceOutput,
+} from "./workflowBuilderTypes";
+
+type ChainCursorWhenOverloads<TCurrentJson> = BooleanWhenOverloads<TCurrentJson, WhenBuilder<TCurrentJson>> & {
+  <
+    TTrueSteps extends ReadonlyArray<AnyRunnableNodeConfig> | undefined,
+    TFalseSteps extends ReadonlyArray<AnyRunnableNodeConfig> | undefined,
+  >(
+    branches: Readonly<{
+      true?: TTrueSteps extends ReadonlyArray<AnyRunnableNodeConfig> ? BranchStepsArg<TCurrentJson, TTrueSteps> : never;
+      false?: TFalseSteps extends ReadonlyArray<AnyRunnableNodeConfig>
+        ? BranchStepsArg<TCurrentJson, TFalseSteps>
+        : never;
+    }> &
+      BranchOutputGuard<TCurrentJson, TTrueSteps, TFalseSteps>,
+  ): ChainCursor<StepSequenceOutput<TCurrentJson, TTrueSteps>>;
+};
+
+export class ChainCursor<TCurrentJson> {
+  constructor(
+    private readonly wf: WorkflowBuilder,
+    private readonly cursor: NodeRef,
+    private readonly cursorOutput: OutputPortKey,
+  ) {}
+
+  then<TConfig extends RunnableNodeConfig<TCurrentJson, any>>(
+    config: TConfig,
+  ): ChainCursor<RunnableNodeOutputJson<TConfig>> {
+    const next = (this.wf as any).add(config) as NodeRef;
+    (this.wf as any).connect(this.cursor, next, this.cursorOutput);
+    return new ChainCursor<RunnableNodeOutputJson<TConfig>>(this.wf, next, "main");
+  }
+
+  readonly when: ChainCursorWhenOverloads<TCurrentJson> = ((
+    arg1:
+      | boolean
+      | Readonly<{ true?: ReadonlyArray<AnyRunnableNodeConfig>; false?: ReadonlyArray<AnyRunnableNodeConfig> }>,
+    steps?: ReadonlyArray<AnyRunnableNodeConfig> | AnyRunnableNodeConfig,
+    ...more: AnyRunnableNodeConfig[]
+  ): WhenBuilder<TCurrentJson> | ChainCursor<TCurrentJson> => {
+    if (typeof arg1 === "boolean") {
+      const list = Array.isArray(steps) ? steps : steps ? [steps, ...more] : more;
+      const port: OutputPortKey = arg1 ? "true" : "false";
+      const b = new WhenBuilder<TCurrentJson>(this.wf, this.cursor, port);
+      b.addBranch(list);
+      return b;
+    }
+
+    const branches = arg1;
+    const makeMerge = (this.wf as any).options?.makeMergeNode as ((name: string) => AnyRunnableNodeConfig) | undefined;
+    if (!makeMerge) {
+      throw new Error(
+        'WorkflowBuilder is missing options.makeMergeNode (required for when({true,false}). Use createWorkflowBuilder from "@codemation/core-nodes".',
+      );
+    }
+
+    const wfAny = this.wf as any;
+
+    const buildBranch = (
+      port: OutputPortKey,
+      branchSteps: ReadonlyArray<AnyRunnableNodeConfig> | undefined,
+    ): Readonly<{ end: NodeRef; endOutput: OutputPortKey }> => {
+      const list = branchSteps ?? [];
+      let prev: NodeRef | null = null;
+      for (const cfg of list) {
+        const ref = wfAny.add(cfg) as NodeRef;
+        if (!prev) wfAny.connect(this.cursor, ref, port, "in");
+        else wfAny.connect(prev, ref, "main", "in");
+        prev = ref;
+      }
+      if (!prev) return { end: this.cursor, endOutput: port };
+      return { end: prev, endOutput: "main" };
+    };
+
+    const t = buildBranch("true", branches.true);
+    const f = buildBranch("false", branches.false);
+
+    const merge = wfAny.add(makeMerge("Merge (auto)")) as NodeRef;
+    wfAny.connect(t.end, merge, t.endOutput, "true");
+    wfAny.connect(f.end, merge, f.endOutput, "false");
+
+    return new ChainCursor<TCurrentJson>(this.wf, merge, "main");
+  }) as ChainCursorWhenOverloads<TCurrentJson>;
+
+  build(): WorkflowDefinition {
+    return this.wf.build();
+  }
+}

package/src/workflow/dsl/WhenBuilder.ts

@@ -0,0 +1,57 @@
+import type { NodeId, NodeRef, OutputPortKey, UpstreamRefPlaceholder, WorkflowDefinition } from "../../types";
+
+import { WorkflowBuilder } from "./WorkflowBuilder";
+import type { AnyRunnableNodeConfig, BooleanWhenOverloads, ValidStepSequence } from "./workflowBuilderTypes";
+
+export class WhenBuilder<TCurrentJson> {
+  constructor(
+    private readonly wf: WorkflowBuilder,
+    private readonly from: NodeRef,
+    private readonly branchPort: OutputPortKey,
+  ) {}
+
+  addBranch<TSteps extends ReadonlyArray<AnyRunnableNodeConfig>>(
+    steps: TSteps & ValidStepSequence<TCurrentJson, TSteps>,
+  ): this {
+    const created: NodeRef[] = [];
+
+    let prev: NodeRef | null = null;
+    for (const cfg of steps) {
+      const ref = (this.wf as any).add(cfg) as NodeRef;
+      created.push(ref);
+      if (!prev) (this.wf as any).connect(this.from, ref, this.branchPort, "in");
+      else (this.wf as any).connect(prev, ref, "main", "in");
+      prev = ref;
+    }
+
+    for (const cfg of steps) {
+      const maybe = cfg as unknown as { upstreamRefs?: Array<{ nodeId: NodeId } | UpstreamRefPlaceholder> };
+      if (!Array.isArray(maybe.upstreamRefs) || maybe.upstreamRefs.length === 0) continue;
+
+      maybe.upstreamRefs = maybe.upstreamRefs.map((r) => {
+        if (typeof r !== "string") return r;
+        const idx = parseInt(r.slice(1), 10);
+        const nodeId = created[idx]?.id;
+        return nodeId ? { nodeId } : { nodeId: r };
+      });
+    }
+
+    return this;
+  }
+
+  readonly when: BooleanWhenOverloads<TCurrentJson, WhenBuilder<TCurrentJson>> = (
+    branch: boolean,
+    steps: ReadonlyArray<AnyRunnableNodeConfig> | AnyRunnableNodeConfig,
+    ...more: AnyRunnableNodeConfig[]
+  ): WhenBuilder<TCurrentJson> => {
+    const list = Array.isArray(steps) ? steps : [steps, ...more];
+    const port: OutputPortKey = branch ? "true" : "false";
+    const b = new WhenBuilder<TCurrentJson>(this.wf, this.from, port);
+    b.addBranch(list);
+    return b;
+  };
+
+  build(): WorkflowDefinition {
+    return this.wf.build();
+  }
+}

package/src/workflow/dsl/WorkflowBuilder.ts

@@ -0,0 +1,55 @@
+import type {
+  InputPortKey,
+  NodeConfigBase,
+  NodeDefinition,
+  NodeRef,
+  OutputPortKey,
+  RunnableNodeOutputJson,
+  TriggerNodeOutputJson,
+  WorkflowDefinition,
+  WorkflowId,
+} from "../../types";
+
+import { ChainCursor } from "./ChainCursorResolver";
+import type { AnyRunnableNodeConfig, AnyTriggerNodeConfig } from "./workflowBuilderTypes";
+
+export class WorkflowBuilder {
+  private readonly nodes: NodeDefinition[] = [];
+  private readonly edges: WorkflowDefinition["edges"] = [];
+  private seq = 0;
+
+  constructor(
+    private readonly meta: { id: WorkflowId; name: string },
+    private readonly options?: Readonly<{
+      makeMergeNode?: (name: string) => AnyRunnableNodeConfig;
+    }>,
+  ) {}
+
+  private add(config: NodeConfigBase): NodeRef {
+    const tokenName = typeof config.type === "function" ? config.type.name : String(config.type);
+    const id = config.id ?? `${tokenName}:${++this.seq}`;
+    this.nodes.push({ id, kind: config.kind, type: config.type, name: config.name, config });
+    return { id, kind: config.kind, name: config.name };
+  }
+
+  private connect(from: NodeRef, to: NodeRef, fromOutput: OutputPortKey = "main", toInput: InputPortKey = "in"): void {
+    this.edges.push({ from: { nodeId: from.id, output: fromOutput }, to: { nodeId: to.id, input: toInput } });
+  }
+
+  trigger<TConfig extends AnyTriggerNodeConfig>(config: TConfig): ChainCursor<TriggerNodeOutputJson<TConfig>> {
+    const ref = this.add(config);
+    return new ChainCursor<TriggerNodeOutputJson<TConfig>>(this, ref, "main");
+  }
+
+  start<TConfig extends AnyRunnableNodeConfig>(config: TConfig): ChainCursor<RunnableNodeOutputJson<TConfig>> {
+    const ref = this.add(config);
+    return new ChainCursor<RunnableNodeOutputJson<TConfig>>(this, ref, "main");
+  }
+
+  build(): WorkflowDefinition {
+    return { ...this.meta, nodes: this.nodes, edges: this.edges };
+  }
+}
+
+export { ChainCursor } from "./ChainCursorResolver";
+export { WhenBuilder } from "./WhenBuilder";

package/src/workflow/dsl/workflowBuilderTypes.ts

@@ -0,0 +1,63 @@
+import type { RunnableNodeConfig, RunnableNodeOutputJson, TriggerNodeConfig } from "../../types";
+
+export type AnyRunnableNodeConfig = RunnableNodeConfig<any, any>;
+
+export type AnyTriggerNodeConfig = TriggerNodeConfig<any>;
+
+export type ValidStepSequence<
+  TCurrentJson,
+  TSteps extends ReadonlyArray<AnyRunnableNodeConfig>,
+> = TSteps extends readonly []
+  ? readonly []
+  : TSteps extends readonly [infer TFirst, ...infer TRest]
+    ? TFirst extends RunnableNodeConfig<TCurrentJson, infer TNextJson>
+      ? TRest extends ReadonlyArray<AnyRunnableNodeConfig>
+        ? readonly [TFirst, ...ValidStepSequence<TNextJson, TRest>]
+        : never
+      : never
+    : TSteps;
+
+export type StepSequenceOutput<TCurrentJson, TSteps extends ReadonlyArray<AnyRunnableNodeConfig> | undefined> =
+  TSteps extends ReadonlyArray<AnyRunnableNodeConfig>
+    ? TSteps extends readonly []
+      ? TCurrentJson
+      : TSteps extends readonly [infer TFirst, ...infer TRest]
+        ? TFirst extends RunnableNodeConfig<TCurrentJson, infer TNextJson>
+          ? TRest extends ReadonlyArray<AnyRunnableNodeConfig>
+            ? StepSequenceOutput<TNextJson, TRest>
+            : never
+          : never
+        : TCurrentJson
+    : TCurrentJson;
+
+type TypesMatch<TLeft, TRight> = [TLeft] extends [TRight] ? ([TRight] extends [TLeft] ? true : false) : false;
+
+export type BranchOutputGuard<
+  TCurrentJson,
+  TTrueSteps extends ReadonlyArray<AnyRunnableNodeConfig> | undefined,
+  TFalseSteps extends ReadonlyArray<AnyRunnableNodeConfig> | undefined,
+> =
+  TypesMatch<StepSequenceOutput<TCurrentJson, TTrueSteps>, StepSequenceOutput<TCurrentJson, TFalseSteps>> extends true
+    ? unknown
+    : never;
+
+export type BranchStepsArg<TCurrentJson, TSteps extends ReadonlyArray<AnyRunnableNodeConfig>> = TSteps &
+  ValidStepSequence<TCurrentJson, TSteps>;
+
+export type BranchMoreArgs<
+  TCurrentJson,
+  TFirstStep extends RunnableNodeConfig<TCurrentJson, any>,
+  TRestSteps extends ReadonlyArray<AnyRunnableNodeConfig>,
+> = TRestSteps & ValidStepSequence<RunnableNodeOutputJson<TFirstStep>, TRestSteps>;
+
+export type BooleanWhenOverloads<TCurrentJson, TReturn> = {
+  <TSteps extends ReadonlyArray<AnyRunnableNodeConfig>>(
+    branch: boolean,
+    steps: BranchStepsArg<TCurrentJson, TSteps>,
+  ): TReturn;
+  <TFirstStep extends RunnableNodeConfig<TCurrentJson, any>, TRestSteps extends ReadonlyArray<AnyRunnableNodeConfig>>(
+    branch: boolean,
+    step: TFirstStep,
+    ...more: BranchMoreArgs<TCurrentJson, TFirstStep, TRestSteps>
+  ): TReturn;
+};