@blokjs/helper 0.2.1 → 0.6.0

package/dist/types/StepOpts.d.ts

@@ -2,34 +2,53 @@ 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"]>>;
+    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;
+    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;
+    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 +60,27 @@ 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"]>>;
+        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;
+        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;
+        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 +90,9 @@ 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;
+        active?: boolean | undefined;
+        stop?: boolean | undefined;
+        stream_logs?: boolean | undefined;
     };
     conditions?: ((...args: unknown[]) => unknown) | undefined;
 }, {
@@ -71,6 +102,9 @@ 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;
+        active?: boolean | undefined;
+        stop?: boolean | undefined;
+        stream_logs?: boolean | undefined;
     };
     conditions?: ((...args: unknown[]) => unknown) | undefined;
 }>;
@@ -78,3 +112,689 @@ 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]>>;
+}, "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;
+    active?: boolean | undefined;
+    stop?: boolean | undefined;
+    stream_logs?: boolean | undefined;
+    idempotencyKey?: string | undefined;
+    as?: string | undefined;
+    spread?: boolean | undefined;
+    ephemeral?: boolean | 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;
+    active?: boolean | undefined;
+    stop?: boolean | undefined;
+    stream_logs?: boolean | undefined;
+    idempotencyKey?: string | undefined;
+    as?: string | undefined;
+    spread?: boolean | undefined;
+    ephemeral?: boolean | 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;
+    active?: boolean | undefined;
+    stop?: boolean | undefined;
+    stream_logs?: boolean | undefined;
+    idempotencyKey?: string | undefined;
+    as?: string | undefined;
+    spread?: boolean | undefined;
+    ephemeral?: boolean | 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;
+    active?: boolean | undefined;
+    stop?: boolean | undefined;
+    stream_logs?: boolean | undefined;
+    idempotencyKey?: string | undefined;
+    as?: string | undefined;
+    spread?: boolean | undefined;
+    ephemeral?: boolean | 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;
+    allowList?: readonly string[];
+    /**
+     * G2 (v0.6) — dispatch strategy. `in-process` (default) runs the
+     * child workflow in the same Node process; `http-self` makes an
+     * HTTP self-call to the deployment so multi-process deployments
+     * can isolate child execution. Requires the child to have an HTTP
+     * trigger (`trigger.http.path` set).
+     */
+    dispatch?: "in-process" | "http-self";
+}>;
+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;
+    idempotencyKey?: undefined;
+    as?: string | undefined;
+    spread?: undefined;
+    ephemeral?: boolean | undefined;
+    retry?: undefined;
+    maxDuration?: undefined;
+}, {
+    id: string;
+    wait: {
+        for?: string | number | undefined;
+        until?: string | number | undefined;
+    };
+    active?: boolean | undefined;
+    stop?: boolean | undefined;
+    concurrencyKey?: undefined;
+    idempotencyKey?: undefined;
+    as?: string | undefined;
+    spread?: undefined;
+    ephemeral?: boolean | undefined;
+    retry?: undefined;
+    maxDuration?: undefined;
+}>, {
+    id: string;
+    wait: {
+        for?: string | number | undefined;
+        until?: string | number | undefined;
+    };
+    active?: boolean | undefined;
+    stop?: boolean | undefined;
+    concurrencyKey?: undefined;
+    idempotencyKey?: undefined;
+    as?: string | undefined;
+    spread?: undefined;
+    ephemeral?: boolean | undefined;
+    retry?: undefined;
+    maxDuration?: undefined;
+}, {
+    id: string;
+    wait: {
+        for?: string | number | undefined;
+        until?: string | number | undefined;
+    };
+    active?: boolean | undefined;
+    stop?: boolean | undefined;
+    concurrencyKey?: undefined;
+    idempotencyKey?: undefined;
+    as?: string | undefined;
+    spread?: undefined;
+    ephemeral?: boolean | undefined;
+    retry?: undefined;
+    maxDuration?: undefined;
+}>;
+export type V2WaitStep = z.infer<typeof V2WaitStepSchema>;
+/**
+ * V2 forEach step — iterate over a collection running a sub-pipeline
+ * per item. Sequential (default) or parallel with bounded concurrency.
+ *
+ * @example
+ *   forEach({
+ *     id: "process-orders",
+ *     in: $.state.orders,
+ *     as: "order",
+ *     mode: "parallel",
+ *     concurrency: 5,
+ *     do: [
+ *       { id: "charge", use: "stripe-charge", inputs: { amount: $.state.order.total } },
+ *     ],
+ *   })
+ */
+export declare const V2ForEachStepSchema: z.ZodLazy<z.ZodObject<{
+    id: z.ZodString;
+    forEach: z.ZodObject<{
+        in: z.ZodUnknown;
+        as: z.ZodString;
+        mode: z.ZodOptional<z.ZodEnum<["sequential", "parallel"]>>;
+        concurrency: z.ZodOptional<z.ZodNumber>;
+        do: z.ZodArray<z.ZodUnknown, "many">;
+    }, "strip", z.ZodTypeAny, {
+        as: string;
+        do: unknown[];
+        mode?: "sequential" | "parallel" | undefined;
+        concurrency?: number | undefined;
+        in?: unknown;
+    }, {
+        as: string;
+        do: unknown[];
+        mode?: "sequential" | "parallel" | undefined;
+        concurrency?: number | undefined;
+        in?: unknown;
+    }>;
+    active: z.ZodOptional<z.ZodBoolean>;
+    stop: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    forEach: {
+        as: string;
+        do: unknown[];
+        mode?: "sequential" | "parallel" | undefined;
+        concurrency?: number | undefined;
+        in?: unknown;
+    };
+    id: string;
+    active?: boolean | undefined;
+    stop?: boolean | undefined;
+}, {
+    forEach: {
+        as: string;
+        do: unknown[];
+        mode?: "sequential" | "parallel" | undefined;
+        concurrency?: number | undefined;
+        in?: unknown;
+    };
+    id: string;
+    active?: boolean | undefined;
+    stop?: boolean | undefined;
+}>>;
+export type V2ForEachStep = z.infer<typeof V2ForEachStepSchema>;
+/**
+ * V2 loop step — while-loop with hard maxIterations safety cap.
+ *
+ * @example
+ *   loop({
+ *     id: "poll",
+ *     while: '$.state["check-status"].status !== "done"',
+ *     maxIterations: 60,
+ *     do: [
+ *       { id: "wait-tick", wait: { for: "2s" } },
+ *       { id: "check-status", use: "@blokjs/api-call", inputs: { url: $.state.url } },
+ *     ],
+ *   })
+ */
+export declare const V2LoopStepSchema: z.ZodLazy<z.ZodObject<{
+    id: z.ZodString;
+    loop: z.ZodObject<{
+        while: z.ZodString;
+        maxIterations: z.ZodOptional<z.ZodNumber>;
+        do: z.ZodArray<z.ZodUnknown, "many">;
+    }, "strip", z.ZodTypeAny, {
+        do: unknown[];
+        while: string;
+        maxIterations?: number | undefined;
+    }, {
+        do: unknown[];
+        while: string;
+        maxIterations?: number | undefined;
+    }>;
+    active: z.ZodOptional<z.ZodBoolean>;
+    stop: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    loop: {
+        do: unknown[];
+        while: string;
+        maxIterations?: number | undefined;
+    };
+    active?: boolean | undefined;
+    stop?: boolean | undefined;
+}, {
+    id: string;
+    loop: {
+        do: unknown[];
+        while: string;
+        maxIterations?: number | undefined;
+    };
+    active?: boolean | undefined;
+    stop?: boolean | undefined;
+}>>;
+export type V2LoopStep = z.infer<typeof V2LoopStepSchema>;
+/**
+ * V2 switch step — N-way branch keyed on a value. First matching case wins.
+ *
+ * `on` resolves to a value at run time (literal, `$` proxy expression, or
+ * `js/...` string). Each case carries a `when` and a `do` sub-pipeline:
+ * - `when` is a literal → match if `on === when`.
+ * - `when` is an array  → match if `array.includes(on)` (group related cases).
+ * - `default` runs when no case matches. Optional.
+ *
+ * @example
+ *   switchOn({
+ *     id: "route-by-tenant",
+ *     on: $.req.headers["x-tenant-id"],
+ *     cases: [
+ *       { when: "acme",   do: [{ id: "x", subworkflow: "acme-process" }] },
+ *       { when: ["a","b"], do: [{ id: "y", subworkflow: "shared" }] },
+ *     ],
+ *     default: [{ id: "respond-403", use: "@blokjs/respond", stop: true,
+ *                 inputs: { status: 403, body: { error: "Unknown tenant" } } }],
+ *   })
+ */
+export declare const V2SwitchStepSchema: z.ZodLazy<z.ZodObject<{
+    id: z.ZodString;
+    switch: z.ZodObject<{
+        on: z.ZodUnknown;
+        cases: z.ZodArray<z.ZodObject<{
+            when: z.ZodUnknown;
+            do: z.ZodArray<z.ZodUnknown, "many">;
+        }, "strip", z.ZodTypeAny, {
+            do: unknown[];
+            when?: unknown;
+        }, {
+            do: unknown[];
+            when?: unknown;
+        }>, "many">;
+        default: z.ZodOptional<z.ZodArray<z.ZodUnknown, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        cases: {
+            do: unknown[];
+            when?: unknown;
+        }[];
+        on?: unknown;
+        default?: unknown[] | undefined;
+    }, {
+        cases: {
+            do: unknown[];
+            when?: unknown;
+        }[];
+        on?: unknown;
+        default?: unknown[] | undefined;
+    }>;
+    active: z.ZodOptional<z.ZodBoolean>;
+    stop: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    switch: {
+        cases: {
+            do: unknown[];
+            when?: unknown;
+        }[];
+        on?: unknown;
+        default?: unknown[] | undefined;
+    };
+    active?: boolean | undefined;
+    stop?: boolean | undefined;
+}, {
+    id: string;
+    switch: {
+        cases: {
+            do: unknown[];
+            when?: unknown;
+        }[];
+        on?: unknown;
+        default?: unknown[] | undefined;
+    };
+    active?: boolean | undefined;
+    stop?: boolean | undefined;
+}>>;
+export type V2SwitchStep = z.infer<typeof V2SwitchStepSchema>;
+/**
+ * V2 tryCatch step — JS-like exception handling for sub-pipelines.
+ *
+ * - `try` block runs first.
+ * - On error, the `catch` block runs with `ctx.error` populated
+ *   (`$.error.message`, `$.error.name`, `$.error.stack`). Errors thrown
+ *   inside `catch` propagate to the next outer handler — they DO NOT
+ *   re-trigger `catch`.
+ * - `finally` (if provided) runs unconditionally after try/catch — on
+ *   normal completion, after a caught error, AND after an uncaught
+ *   error from inside `catch`. Errors from `finally` propagate.
+ *
+ * State mutations from any block are visible to subsequent top-level
+ * steps (passthrough flow, like switch).
+ *
+ * @example
+ *   tryCatch({
+ *     id: "saga",
+ *     try: [
+ *       { id: "create", use: "user-create", inputs: { email: $.req.body.email } },
+ *       { id: "notify", use: "email-send", inputs: { to: $.state.create.email } },
+ *     ],
+ *     catch: [
+ *       { id: "rollback", use: "user-delete",
+ *         inputs: { userId: $.state.create.id, reason: $.error.message } },
+ *     ],
+ *     finally: [
+ *       { id: "metric", use: "@blokjs/metrics-emit", inputs: { event: "saga-attempt" } },
+ *     ],
+ *   })
+ */
+export declare const V2TryCatchStepSchema: z.ZodLazy<z.ZodObject<{
+    id: z.ZodString;
+    tryCatch: z.ZodObject<{
+        try: z.ZodArray<z.ZodUnknown, "many">;
+        catch: z.ZodArray<z.ZodUnknown, "many">;
+        finally: z.ZodOptional<z.ZodArray<z.ZodUnknown, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        try: unknown[];
+        catch: unknown[];
+        finally?: unknown[] | undefined;
+    }, {
+        try: unknown[];
+        catch: unknown[];
+        finally?: unknown[] | undefined;
+    }>;
+    active: z.ZodOptional<z.ZodBoolean>;
+    stop: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    tryCatch: {
+        try: unknown[];
+        catch: unknown[];
+        finally?: unknown[] | undefined;
+    };
+    active?: boolean | undefined;
+    stop?: boolean | undefined;
+}, {
+    id: string;
+    tryCatch: {
+        try: unknown[];
+        catch: unknown[];
+        finally?: unknown[] | undefined;
+    };
+    active?: boolean | undefined;
+    stop?: boolean | undefined;
+}>>;
+export type V2TryCatchStep = z.infer<typeof V2TryCatchStepSchema>;
+/**
+ * Discriminated v2 step — regular, branch, sub-workflow, wait, forEach, loop, switch, or tryCatch.
+ *
+ * Discriminators (no `kind` field needed):
+ * - presence of `branch` → branch step
+ * - presence of `subworkflow` → sub-workflow step
+ * - presence of `wait` (object) → wait step
+ * - presence of `forEach` → forEach step (v0.5)
+ * - presence of `loop` → loop step (v0.5)
+ * - presence of `switch` → switch step (v0.5)
+ * - presence of `tryCatch` → tryCatch step (v0.5)
+ * - otherwise → regular step
+ */
+export declare const V2StepSchema: z.ZodType<V2RegularStep | V2BranchStep | V2SubworkflowStep | V2WaitStep | V2ForEachStep | V2LoopStep | V2SwitchStep | V2TryCatchStep>;
+export type V2Step = V2RegularStep | V2BranchStep | V2SubworkflowStep | V2WaitStep | V2ForEachStep | V2LoopStep | V2SwitchStep | V2TryCatchStep;
+/**
+ * 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;
+/**
+ * Type guard — true when the step is a forEach iteration (v0.5).
+ */
+export declare function isForEachStep(step: V2Step): step is V2ForEachStep;
+/**
+ * Type guard — true when the step is a while-loop (v0.5).
+ */
+export declare function isLoopStep(step: V2Step): step is V2LoopStep;
+/**
+ * Type guard — true when the step is an N-way switch (v0.5).
+ */
+export declare function isSwitchStep(step: V2Step): step is V2SwitchStep;
+/**
+ * Type guard — true when the step is a tryCatch (v0.5).
+ */
+export declare function isTryCatchStep(step: V2Step): step is V2TryCatchStep;