@blokjs/helper 0.2.0 → 0.4.0

package/dist/types/StepOpts.d.ts

@@ -2,34 +2,61 @@ import { z } from "zod";
 import type { ConditionElseOpts } from "../components/AddElse";
 import type { ConditionOpts } from "../components/AddIf";
 /**
- * RuntimeKind represents all supported runtime environments
- * Synced with @blokjs/runner RuntimeKind type
+ * RuntimeKind represents all supported runtime environments.
+ *
+ * Synced with `@blokjs/runner` `RuntimeKind` type.
  */
 export declare const RuntimeKindSchema: z.ZodEnum<["nodejs", "bun", "python3", "go", "java", "rust", "php", "csharp", "ruby", "docker", "wasm"]>;
 export type RuntimeKind = z.infer<typeof RuntimeKindSchema>;
 /**
- * Node type enum - includes both legacy types and new runtime types
+ * Node type enum — includes both legacy types and new runtime types.
  */
 export declare const NodeTypeSchema: z.ZodEnum<["local", "module", "runtime.python3", "runtime.nodejs", "runtime.bun", "runtime.go", "runtime.java", "runtime.rust", "runtime.php", "runtime.csharp", "runtime.ruby", "runtime.docker", "runtime.wasm"]>;
 export type NodeType = z.infer<typeof NodeTypeSchema>;
+/**
+ * Validation schema for a single workflow step (v1 — legacy).
+ *
+ * Mirrors the JSON workflow step shape so the TypeScript DSL produces
+ * structurally-identical output to JSON workflows.
+ *
+ * @deprecated Prefer {@link StepV2Schema}. v1 shapes are still accepted and
+ * normalized at workflow load time.
+ */
 export declare const StepOptsSchema: z.ZodObject<{
     name: z.ZodString;
     node: z.ZodString;
     type: z.ZodEnum<["local", "module", "runtime.python3", "runtime.nodejs", "runtime.bun", "runtime.go", "runtime.java", "runtime.rust", "runtime.php", "runtime.csharp", "runtime.ruby", "runtime.docker", "runtime.wasm"]>;
     inputs: z.ZodOptional<z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>>;
     runtime: z.ZodOptional<z.ZodEnum<["nodejs", "bun", "python3", "go", "java", "rust", "php", "csharp", "ruby", "docker", "wasm"]>>;
+    /**
+     * @deprecated v2 default-stores every step's output. Set `ephemeral: true`
+     * to opt out. `set_var: true` is now a no-op (default behaviour);
+     * `set_var: false` is normalized to `ephemeral: true` at load time.
+     */
+    set_var: z.ZodOptional<z.ZodBoolean>;
+    active: z.ZodOptional<z.ZodBoolean>;
+    stop: z.ZodOptional<z.ZodBoolean>;
+    stream_logs: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     name: string;
     node: string;
     type: "local" | "module" | "runtime.python3" | "runtime.nodejs" | "runtime.bun" | "runtime.go" | "runtime.java" | "runtime.rust" | "runtime.php" | "runtime.csharp" | "runtime.ruby" | "runtime.docker" | "runtime.wasm";
     inputs?: {} | undefined;
     runtime?: "nodejs" | "bun" | "python3" | "go" | "java" | "rust" | "php" | "csharp" | "ruby" | "docker" | "wasm" | undefined;
+    set_var?: boolean | undefined;
+    active?: boolean | undefined;
+    stop?: boolean | undefined;
+    stream_logs?: boolean | undefined;
 }, {
     name: string;
     node: string;
     type: "local" | "module" | "runtime.python3" | "runtime.nodejs" | "runtime.bun" | "runtime.go" | "runtime.java" | "runtime.rust" | "runtime.php" | "runtime.csharp" | "runtime.ruby" | "runtime.docker" | "runtime.wasm";
     inputs?: {} | undefined;
     runtime?: "nodejs" | "bun" | "python3" | "go" | "java" | "rust" | "php" | "csharp" | "ruby" | "docker" | "wasm" | undefined;
+    set_var?: boolean | undefined;
+    active?: boolean | undefined;
+    stop?: boolean | undefined;
+    stream_logs?: boolean | undefined;
 }>;
 export type StepOpts = z.infer<typeof StepOptsSchema>;
 export declare const StepInputsSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
@@ -41,18 +68,35 @@ export declare const StepConditionSchema: z.ZodObject<{
         type: z.ZodEnum<["local", "module", "runtime.python3", "runtime.nodejs", "runtime.bun", "runtime.go", "runtime.java", "runtime.rust", "runtime.php", "runtime.csharp", "runtime.ruby", "runtime.docker", "runtime.wasm"]>;
         inputs: z.ZodOptional<z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>>;
         runtime: z.ZodOptional<z.ZodEnum<["nodejs", "bun", "python3", "go", "java", "rust", "php", "csharp", "ruby", "docker", "wasm"]>>;
+        /**
+         * @deprecated v2 default-stores every step's output. Set `ephemeral: true`
+         * to opt out. `set_var: true` is now a no-op (default behaviour);
+         * `set_var: false` is normalized to `ephemeral: true` at load time.
+         */
+        set_var: z.ZodOptional<z.ZodBoolean>;
+        active: z.ZodOptional<z.ZodBoolean>;
+        stop: z.ZodOptional<z.ZodBoolean>;
+        stream_logs: z.ZodOptional<z.ZodBoolean>;
     }, "strip", z.ZodTypeAny, {
         name: string;
         node: string;
         type: "local" | "module" | "runtime.python3" | "runtime.nodejs" | "runtime.bun" | "runtime.go" | "runtime.java" | "runtime.rust" | "runtime.php" | "runtime.csharp" | "runtime.ruby" | "runtime.docker" | "runtime.wasm";
         inputs?: {} | undefined;
         runtime?: "nodejs" | "bun" | "python3" | "go" | "java" | "rust" | "php" | "csharp" | "ruby" | "docker" | "wasm" | undefined;
+        set_var?: boolean | undefined;
+        active?: boolean | undefined;
+        stop?: boolean | undefined;
+        stream_logs?: boolean | undefined;
     }, {
         name: string;
         node: string;
         type: "local" | "module" | "runtime.python3" | "runtime.nodejs" | "runtime.bun" | "runtime.go" | "runtime.java" | "runtime.rust" | "runtime.php" | "runtime.csharp" | "runtime.ruby" | "runtime.docker" | "runtime.wasm";
         inputs?: {} | undefined;
         runtime?: "nodejs" | "bun" | "python3" | "go" | "java" | "rust" | "php" | "csharp" | "ruby" | "docker" | "wasm" | undefined;
+        set_var?: boolean | undefined;
+        active?: boolean | undefined;
+        stop?: boolean | undefined;
+        stream_logs?: boolean | undefined;
     }>;
     conditions: z.ZodOptional<z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodUnknown>>;
 }, "strip", z.ZodTypeAny, {
@@ -62,6 +106,10 @@ export declare const StepConditionSchema: z.ZodObject<{
         type: "local" | "module" | "runtime.python3" | "runtime.nodejs" | "runtime.bun" | "runtime.go" | "runtime.java" | "runtime.rust" | "runtime.php" | "runtime.csharp" | "runtime.ruby" | "runtime.docker" | "runtime.wasm";
         inputs?: {} | undefined;
         runtime?: "nodejs" | "bun" | "python3" | "go" | "java" | "rust" | "php" | "csharp" | "ruby" | "docker" | "wasm" | undefined;
+        set_var?: boolean | undefined;
+        active?: boolean | undefined;
+        stop?: boolean | undefined;
+        stream_logs?: boolean | undefined;
     };
     conditions?: ((...args: unknown[]) => unknown) | undefined;
 }, {
@@ -71,6 +119,10 @@ export declare const StepConditionSchema: z.ZodObject<{
         type: "local" | "module" | "runtime.python3" | "runtime.nodejs" | "runtime.bun" | "runtime.go" | "runtime.java" | "runtime.rust" | "runtime.php" | "runtime.csharp" | "runtime.ruby" | "runtime.docker" | "runtime.wasm";
         inputs?: {} | undefined;
         runtime?: "nodejs" | "bun" | "python3" | "go" | "java" | "rust" | "php" | "csharp" | "ruby" | "docker" | "wasm" | undefined;
+        set_var?: boolean | undefined;
+        active?: boolean | undefined;
+        stop?: boolean | undefined;
+        stream_logs?: boolean | undefined;
     };
     conditions?: ((...args: unknown[]) => unknown) | undefined;
 }>;
@@ -78,3 +130,404 @@ export interface IConditions {
     conditions: () => ConditionOpts[] | ConditionElseOpts[];
 }
 export type StepConditionOpts = z.infer<typeof StepConditionSchema>;
+/**
+ * Retry configuration for a v2 step.
+ *
+ * Wraps `step.process(ctx, step)` in a retry loop with capped exponential
+ * backoff. Per-attempt failures emit `NODE_ATTEMPT_FAILED` trace events.
+ *
+ * Defaults applied by the runner when fields are omitted:
+ * - `minTimeoutInMs`: 1000
+ * - `maxTimeoutInMs`: 30000
+ * - `factor`: 2
+ *
+ * Shape mirrors Trigger.dev's `retry` config so authors moving between
+ * platforms read familiar semantics. No jitter is added — matches
+ * Trigger.dev's default.
+ */
+export declare const RetryConfigSchema: z.ZodEffects<z.ZodObject<{
+    maxAttempts: z.ZodNumber;
+    minTimeoutInMs: z.ZodOptional<z.ZodNumber>;
+    maxTimeoutInMs: z.ZodOptional<z.ZodNumber>;
+    factor: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    maxAttempts: number;
+    factor?: number | undefined;
+    minTimeoutInMs?: number | undefined;
+    maxTimeoutInMs?: number | undefined;
+}, {
+    maxAttempts: number;
+    factor?: number | undefined;
+    minTimeoutInMs?: number | undefined;
+    maxTimeoutInMs?: number | undefined;
+}>, {
+    maxAttempts: number;
+    factor?: number | undefined;
+    minTimeoutInMs?: number | undefined;
+    maxTimeoutInMs?: number | undefined;
+}, {
+    maxAttempts: number;
+    factor?: number | undefined;
+    minTimeoutInMs?: number | undefined;
+    maxTimeoutInMs?: number | undefined;
+}>;
+export type RetryConfig = z.infer<typeof RetryConfigSchema>;
+/**
+ * V2 regular step — invokes a node with inputs.
+ *
+ * **Identity**
+ * - `id` is the step's stable identifier. Other steps reference this step's
+ *   output as `$.state[id]`.
+ * - `use` is the node reference (e.g. `@blokjs/api-call`).
+ *
+ * **Persistence (default-store rule)**
+ * Every step's `result.data` is automatically stored in `ctx.state[id]`
+ * after execution. This is the 95% case. The four declarative knobs:
+ * - `as: "<name>"` — store at `state[name]` instead of `state[id]`.
+ * - `spread: true` — shallow-merge keys of `result.data` into `state`
+ *   (data-pipeline pattern). Mutually exclusive with `as`.
+ * - `ephemeral: true` — skip storage; only `ctx.prev` carries the result
+ *   to the next step.
+ *
+ * @example
+ *   { id: "fetch-users", use: "postgres-query", inputs: { sql: "..." } }
+ *   // state["fetch-users"] = result.data
+ *
+ * @example
+ *   { id: "step-1", use: "...", as: "users" }
+ *   // state.users = result.data
+ *
+ * @example
+ *   { id: "load", use: "fetch-user-and-profile", spread: true }
+ *   // result.data = { user, profile } -> state.user + state.profile
+ */
+export declare const V2RegularStepSchema: z.ZodEffects<z.ZodObject<{
+    id: z.ZodString;
+    use: z.ZodString;
+    type: z.ZodOptional<z.ZodEnum<["local", "module", "runtime.python3", "runtime.nodejs", "runtime.bun", "runtime.go", "runtime.java", "runtime.rust", "runtime.php", "runtime.csharp", "runtime.ruby", "runtime.docker", "runtime.wasm"]>>;
+    inputs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    as: z.ZodOptional<z.ZodString>;
+    spread: z.ZodOptional<z.ZodBoolean>;
+    ephemeral: z.ZodOptional<z.ZodBoolean>;
+    runtime: z.ZodOptional<z.ZodEnum<["nodejs", "bun", "python3", "go", "java", "rust", "php", "csharp", "ruby", "docker", "wasm"]>>;
+    active: z.ZodOptional<z.ZodBoolean>;
+    stop: z.ZodOptional<z.ZodBoolean>;
+    stream_logs: z.ZodOptional<z.ZodBoolean>;
+    idempotencyKey: z.ZodOptional<z.ZodString>;
+    idempotencyKeyTTL: z.ZodOptional<z.ZodNumber>;
+    retry: z.ZodOptional<z.ZodEffects<z.ZodObject<{
+        maxAttempts: z.ZodNumber;
+        minTimeoutInMs: z.ZodOptional<z.ZodNumber>;
+        maxTimeoutInMs: z.ZodOptional<z.ZodNumber>;
+        factor: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        maxAttempts: number;
+        factor?: number | undefined;
+        minTimeoutInMs?: number | undefined;
+        maxTimeoutInMs?: number | undefined;
+    }, {
+        maxAttempts: number;
+        factor?: number | undefined;
+        minTimeoutInMs?: number | undefined;
+        maxTimeoutInMs?: number | undefined;
+    }>, {
+        maxAttempts: number;
+        factor?: number | undefined;
+        minTimeoutInMs?: number | undefined;
+        maxTimeoutInMs?: number | undefined;
+    }, {
+        maxAttempts: number;
+        factor?: number | undefined;
+        minTimeoutInMs?: number | undefined;
+        maxTimeoutInMs?: number | undefined;
+    }>>;
+    maxDuration: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodString]>>;
+    set_var: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    use: string;
+    type?: "local" | "module" | "runtime.python3" | "runtime.nodejs" | "runtime.bun" | "runtime.go" | "runtime.java" | "runtime.rust" | "runtime.php" | "runtime.csharp" | "runtime.ruby" | "runtime.docker" | "runtime.wasm" | undefined;
+    inputs?: Record<string, unknown> | undefined;
+    runtime?: "nodejs" | "bun" | "python3" | "go" | "java" | "rust" | "php" | "csharp" | "ruby" | "docker" | "wasm" | undefined;
+    set_var?: boolean | undefined;
+    active?: boolean | undefined;
+    stop?: boolean | undefined;
+    stream_logs?: boolean | undefined;
+    as?: string | undefined;
+    spread?: boolean | undefined;
+    ephemeral?: boolean | undefined;
+    idempotencyKey?: string | undefined;
+    idempotencyKeyTTL?: number | undefined;
+    retry?: {
+        maxAttempts: number;
+        factor?: number | undefined;
+        minTimeoutInMs?: number | undefined;
+        maxTimeoutInMs?: number | undefined;
+    } | undefined;
+    maxDuration?: string | number | undefined;
+}, {
+    id: string;
+    use: string;
+    type?: "local" | "module" | "runtime.python3" | "runtime.nodejs" | "runtime.bun" | "runtime.go" | "runtime.java" | "runtime.rust" | "runtime.php" | "runtime.csharp" | "runtime.ruby" | "runtime.docker" | "runtime.wasm" | undefined;
+    inputs?: Record<string, unknown> | undefined;
+    runtime?: "nodejs" | "bun" | "python3" | "go" | "java" | "rust" | "php" | "csharp" | "ruby" | "docker" | "wasm" | undefined;
+    set_var?: boolean | undefined;
+    active?: boolean | undefined;
+    stop?: boolean | undefined;
+    stream_logs?: boolean | undefined;
+    as?: string | undefined;
+    spread?: boolean | undefined;
+    ephemeral?: boolean | undefined;
+    idempotencyKey?: string | undefined;
+    idempotencyKeyTTL?: number | undefined;
+    retry?: {
+        maxAttempts: number;
+        factor?: number | undefined;
+        minTimeoutInMs?: number | undefined;
+        maxTimeoutInMs?: number | undefined;
+    } | undefined;
+    maxDuration?: string | number | undefined;
+}>, {
+    id: string;
+    use: string;
+    type?: "local" | "module" | "runtime.python3" | "runtime.nodejs" | "runtime.bun" | "runtime.go" | "runtime.java" | "runtime.rust" | "runtime.php" | "runtime.csharp" | "runtime.ruby" | "runtime.docker" | "runtime.wasm" | undefined;
+    inputs?: Record<string, unknown> | undefined;
+    runtime?: "nodejs" | "bun" | "python3" | "go" | "java" | "rust" | "php" | "csharp" | "ruby" | "docker" | "wasm" | undefined;
+    set_var?: boolean | undefined;
+    active?: boolean | undefined;
+    stop?: boolean | undefined;
+    stream_logs?: boolean | undefined;
+    as?: string | undefined;
+    spread?: boolean | undefined;
+    ephemeral?: boolean | undefined;
+    idempotencyKey?: string | undefined;
+    idempotencyKeyTTL?: number | undefined;
+    retry?: {
+        maxAttempts: number;
+        factor?: number | undefined;
+        minTimeoutInMs?: number | undefined;
+        maxTimeoutInMs?: number | undefined;
+    } | undefined;
+    maxDuration?: string | number | undefined;
+}, {
+    id: string;
+    use: string;
+    type?: "local" | "module" | "runtime.python3" | "runtime.nodejs" | "runtime.bun" | "runtime.go" | "runtime.java" | "runtime.rust" | "runtime.php" | "runtime.csharp" | "runtime.ruby" | "runtime.docker" | "runtime.wasm" | undefined;
+    inputs?: Record<string, unknown> | undefined;
+    runtime?: "nodejs" | "bun" | "python3" | "go" | "java" | "rust" | "php" | "csharp" | "ruby" | "docker" | "wasm" | undefined;
+    set_var?: boolean | undefined;
+    active?: boolean | undefined;
+    stop?: boolean | undefined;
+    stream_logs?: boolean | undefined;
+    as?: string | undefined;
+    spread?: boolean | undefined;
+    ephemeral?: boolean | undefined;
+    idempotencyKey?: string | undefined;
+    idempotencyKeyTTL?: number | undefined;
+    retry?: {
+        maxAttempts: number;
+        factor?: number | undefined;
+        minTimeoutInMs?: number | undefined;
+        maxTimeoutInMs?: number | undefined;
+    } | undefined;
+    maxDuration?: string | number | undefined;
+}>;
+export type V2RegularStep = z.infer<typeof V2RegularStepSchema>;
+/**
+ * V2 branch step — `branch({when, then, else})`.
+ *
+ * Replaces the legacy `addCondition + new AddIf().addStep().build()` pattern.
+ * Compiles down to the existing `@blokjs/if-else` flow node at workflow
+ * load time, so the runner core needs no change.
+ *
+ * @example
+ *   {
+ *     id: "route-by-method",
+ *     branch: {
+ *       when: '$.req.method === "POST"',
+ *       then: [{ id: "create", use: "...", inputs: {...} }],
+ *       else: [{ id: "read",   use: "...", inputs: {...} }]
+ *     }
+ *   }
+ */
+export declare const V2BranchStepSchema: z.ZodType<{
+    id: string;
+    branch: {
+        when: string;
+        then: unknown[];
+        else?: unknown[];
+    };
+    active?: boolean;
+    stop?: boolean;
+}>;
+export type V2BranchStep = z.infer<typeof V2BranchStepSchema>;
+/**
+ * V2 sub-workflow step — invoke another named workflow inline.
+ *
+ * The parent step blocks until the child workflow completes (`wait: true`,
+ * the default). The child gets its own `ctx`, its own trace run record,
+ * and runs through the same `RunnerSteps` machinery as a top-level run.
+ * The child's `ctx.response` becomes the parent step's output, so it
+ * lands on `state[<id>]` like any other step (mirrors HTTP semantics:
+ * sub-workflow looks like a function call).
+ *
+ * Inputs flow from parent → child as `ctx.request.body` — the child
+ * reads them via `$.req.body.<key>` exactly as if it had been
+ * HTTP-triggered.
+ *
+ * **Composition with Tier 1**:
+ * - `idempotencyKey` on this step caches the entire sub-workflow's
+ *   result. Cache hit = child workflow is NEVER invoked (no side
+ *   effects fire on rerun). Documented footgun + headline pattern.
+ * - `retry` retries the whole sub-workflow on failure.
+ * - Replay re-creates fresh sub-run lineage automatically.
+ *
+ * @example
+ *   {
+ *     id: "send-receipt",
+ *     subworkflow: "send-receipt-email",
+ *     inputs: { user: $.state.user, order: $.state.order },
+ *     wait: true,           // default; `wait: false` deferred to a follow-up
+ *     idempotencyKey: $.req.body.requestId,
+ *   }
+ */
+export declare const V2SubworkflowStepSchema: z.ZodType<{
+    id: string;
+    subworkflow: string;
+    inputs?: Record<string, unknown>;
+    wait?: boolean;
+    as?: string;
+    spread?: boolean;
+    ephemeral?: boolean;
+    active?: boolean;
+    stop?: boolean;
+    idempotencyKey?: string;
+    idempotencyKeyTTL?: number;
+    retry?: RetryConfig;
+}>;
+export type V2SubworkflowStep = z.infer<typeof V2SubworkflowStepSchema>;
+/**
+ * V2 wait step (PR 4 · `wait.for(duration)` / `wait.until(date)`).
+ *
+ * Pauses workflow execution mid-run for the specified duration (or until
+ * the absolute deadline). Composes with the durable scheduler — long
+ * waits survive process restart via the existing
+ * `scheduled_dispatches` infrastructure (PR 4 P3 adds
+ * `last_completed_step_index` so the runner skips past completed
+ * pre-wait steps on resume).
+ *
+ * Author surface:
+ * ```ts
+ * { id: "wait-3d", wait: { for: "3d" } }
+ * { id: "wait-deadline", wait: { until: $.req.body.scheduledAt } }
+ * ```
+ *
+ * Cannot combine with `idempotencyKey` (the wait IS the checkpoint) or
+ * `retry` (waits don't fail in a retryable way).
+ */
+export declare const V2WaitStepSchema: z.ZodEffects<z.ZodObject<{
+    id: z.ZodString;
+    wait: z.ZodObject<{
+        for: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodString]>>;
+        until: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodString]>>;
+    }, "strict", z.ZodTypeAny, {
+        for?: string | number | undefined;
+        until?: string | number | undefined;
+    }, {
+        for?: string | number | undefined;
+        until?: string | number | undefined;
+    }>;
+    as: z.ZodOptional<z.ZodString>;
+    ephemeral: z.ZodOptional<z.ZodBoolean>;
+    active: z.ZodOptional<z.ZodBoolean>;
+    stop: z.ZodOptional<z.ZodBoolean>;
+    idempotencyKey: z.ZodOptional<z.ZodNever>;
+    retry: z.ZodOptional<z.ZodNever>;
+    maxDuration: z.ZodOptional<z.ZodNever>;
+    concurrencyKey: z.ZodOptional<z.ZodNever>;
+    spread: z.ZodOptional<z.ZodNever>;
+}, "strict", z.ZodTypeAny, {
+    id: string;
+    wait: {
+        for?: string | number | undefined;
+        until?: string | number | undefined;
+    };
+    active?: boolean | undefined;
+    stop?: boolean | undefined;
+    concurrencyKey?: undefined;
+    as?: string | undefined;
+    spread?: undefined;
+    ephemeral?: boolean | undefined;
+    idempotencyKey?: undefined;
+    retry?: undefined;
+    maxDuration?: undefined;
+}, {
+    id: string;
+    wait: {
+        for?: string | number | undefined;
+        until?: string | number | undefined;
+    };
+    active?: boolean | undefined;
+    stop?: boolean | undefined;
+    concurrencyKey?: undefined;
+    as?: string | undefined;
+    spread?: undefined;
+    ephemeral?: boolean | undefined;
+    idempotencyKey?: undefined;
+    retry?: undefined;
+    maxDuration?: undefined;
+}>, {
+    id: string;
+    wait: {
+        for?: string | number | undefined;
+        until?: string | number | undefined;
+    };
+    active?: boolean | undefined;
+    stop?: boolean | undefined;
+    concurrencyKey?: undefined;
+    as?: string | undefined;
+    spread?: undefined;
+    ephemeral?: boolean | undefined;
+    idempotencyKey?: undefined;
+    retry?: undefined;
+    maxDuration?: undefined;
+}, {
+    id: string;
+    wait: {
+        for?: string | number | undefined;
+        until?: string | number | undefined;
+    };
+    active?: boolean | undefined;
+    stop?: boolean | undefined;
+    concurrencyKey?: undefined;
+    as?: string | undefined;
+    spread?: undefined;
+    ephemeral?: boolean | undefined;
+    idempotencyKey?: undefined;
+    retry?: undefined;
+    maxDuration?: undefined;
+}>;
+export type V2WaitStep = z.infer<typeof V2WaitStepSchema>;
+/**
+ * Discriminated v2 step — regular, branch, sub-workflow, or wait.
+ *
+ * Discriminators (no `kind` field needed):
+ * - presence of `branch` → branch step
+ * - presence of `subworkflow` → sub-workflow step
+ * - presence of `wait` (object) → wait step
+ * - otherwise → regular step
+ */
+export declare const V2StepSchema: z.ZodType<V2RegularStep | V2BranchStep | V2SubworkflowStep | V2WaitStep>;
+export type V2Step = V2RegularStep | V2BranchStep | V2SubworkflowStep | V2WaitStep;
+/**
+ * Type guard — true when the step is a branch.
+ */
+export declare function isBranchStep(step: V2Step): step is V2BranchStep;
+/**
+ * Type guard — true when the step is a wait (PR 4 `wait.for` / `wait.until`).
+ */
+export declare function isWaitStep(step: V2Step): step is V2WaitStep;
+/**
+ * Type guard — true when the step is a sub-workflow invocation.
+ */
+export declare function isSubworkflowStep(step: V2Step): step is V2SubworkflowStep;