@barnum/barnum 0.0.0-main-ef6df91f → 0.0.0-main-e8b82cff

package/src/ast.ts

@@ -1,3 +1,5 @@
+import type { JSONSchema7 } from "json-schema";
+
 // ---------------------------------------------------------------------------
 // Serializable Types — mirror the Rust AST in barnum_ast
 // ---------------------------------------------------------------------------
@@ -8,9 +10,10 @@ export type Action =
   | ForEachAction
   | AllAction
   | BranchAction
-  | StepAction
-  | HandleAction
-  | PerformAction;
+  | ResumeHandleAction
+  | ResumePerformAction
+  | RestartHandleAction
+  | RestartPerformAction;
 
 export interface InvokeAction {
   kind: "Invoke";
@@ -38,25 +41,30 @@ export interface BranchAction {
   cases: Record<string, Action>;
 }
 
-export interface StepAction {
-  kind: "Step";
-  step: StepRef;
+export interface ResumeHandleAction {
+  kind: "ResumeHandle";
+  resume_handler_id: ResumeHandlerId;
+  body: Action;
+  handler: Action;
+}
+
+export interface ResumePerformAction {
+  kind: "ResumePerform";
+  resume_handler_id: ResumeHandlerId;
 }
 
-export interface HandleAction {
-  kind: "Handle";
-  effect_id: number;
+export interface RestartHandleAction {
+  kind: "RestartHandle";
+  restart_handler_id: RestartHandlerId;
   body: Action;
   handler: Action;
 }
 
-export interface PerformAction {
-  kind: "Perform";
-  effect_id: number;
+export interface RestartPerformAction {
+  kind: "RestartPerform";
+  restart_handler_id: RestartHandlerId;
 }
 
-export type StepRef = { kind: "Named"; name: string } | { kind: "Root" };
-
 // ---------------------------------------------------------------------------
 // HandlerKind
 // ---------------------------------------------------------------------------
@@ -67,6 +75,8 @@ export interface TypeScriptHandler {
   kind: "TypeScript";
   module: string;
   func: string;
+  input_schema?: JSONSchema7;
+  output_schema?: JSONSchema7;
 }
 
 export interface BuiltinHandler {
@@ -86,32 +96,6 @@ export type BuiltinKind =
   | { kind: "Pick"; value: string[] }
   | { kind: "CollectSome" };
 
-// ---------------------------------------------------------------------------
-// WorkflowAction — loosened input constraint for workflow entry points
-// ---------------------------------------------------------------------------
-
-/**
- * A TypedAction suitable as a workflow entry point. Workflows start with
- * no input data, so the action must not require specific input.
- *
- * Uses `__in?: void` to accept both:
- *   - `TypedAction<any, Out>` — combinators that ignore input (constant, sleep)
- *   - `TypedAction<never, Out>` — handlers that genuinely take no params
- *
- * Rejects `TypedAction<{ artifact: string }, Out>` etc. because
- * `{ artifact: string }` is not assignable to `void`.
- *
- * Only `__in` is checked (no `__phantom_in`) — the contravariant phantom
- * field would accept anything due to `void`'s permissiveness, so omitting
- * it is harmless and avoids deep method signature comparison.
- */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type WorkflowAction<Out = any> = Action & {
-  __in?: void;
-  __phantom_out?: () => Out;
-  __phantom_out_check?: (output: Out) => void;
-};
-
 /**
  * When TIn is `never` (handler ignores input), produce `any` so the
  * combinator/pipe can sit in any pipeline position.
@@ -122,10 +106,8 @@ export type PipeIn<T> = [T] extends [never] ? any : T;
 // Config
 // ---------------------------------------------------------------------------
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export interface Config<Out = any> {
-  workflow: WorkflowAction<Out>;
-  steps?: Record<string, Action>;
+export interface Config {
+  workflow: Action;
 }
 
 // ---------------------------------------------------------------------------
@@ -133,14 +115,16 @@ export interface Config<Out = any> {
 // ---------------------------------------------------------------------------
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-type UnionToIntersection<TUnion> = (TUnion extends any ? (x: TUnion) => void : never) extends (
-  x: infer TIntersection,
-) => void
+type UnionToIntersection<TUnion> = (
+  TUnion extends any ? (x: TUnion) => void : never
+) extends (x: infer TIntersection) => void
   ? TIntersection
   : never;
 
 /** Merge a tuple of objects into a single intersection type. */
-export type MergeTuple<TTuple> = TTuple extends unknown[] ? UnionToIntersection<TTuple[number]> : never;
+export type MergeTuple<TTuple> = TTuple extends unknown[]
+  ? UnionToIntersection<TTuple[number]>
+  : never;
 
 // ---------------------------------------------------------------------------
 // Phantom Types — type-safe input/output tracking
@@ -163,8 +147,6 @@ export type MergeTuple<TTuple> = TTuple extends unknown[] ? UnionToIntersection<
  * (the contravariant __phantom_in makes never the most permissive input,
  * so the covariant __in is needed for the entry point check).
  *
- * Refs: tracks step reference names through combinators for compile-time
- *   validation in registerSteps (see ValidateStepRefs)
  */
 export type TypedAction<
   In = unknown,
@@ -181,16 +163,34 @@ export type TypedAction<
     next: Pipeable<Out, TNext, TRefs2>,
   ): TypedAction<In, TNext, Refs | TRefs2>;
   /** Apply an action to each element of an array output. `a.forEach(b)` ≡ `a.then(forEach(b))`. */
-  forEach<TIn, TElement, TNext, TRefs extends string, TRefs2 extends string = never>(
+  forEach<
+    TIn,
+    TElement,
+    TNext,
+    TRefs extends string,
+    TRefs2 extends string = never,
+  >(
     this: TypedAction<TIn, TElement[], TRefs>,
     action: Pipeable<TElement, TNext, TRefs2>,
   ): TypedAction<TIn, TNext[], TRefs | TRefs2>;
   /** Dispatch on a tagged union output. Auto-unwraps `value` before each case handler. */
-  branch<TCases extends { [K in BranchKeys<Out>]: CaseHandler<BranchPayload<Out, K>, unknown, string> }>(
+  branch<
+    TCases extends {
+      [K in BranchKeys<Out>]: CaseHandler<
+        BranchPayload<Out, K>,
+        unknown,
+        string
+      >;
+    },
+  >(
     cases: [BranchKeys<Out>] extends [never] ? never : TCases,
-  ): TypedAction<In, ExtractOutput<TCases[keyof TCases & string]>, Refs | ExtractRefs<TCases[keyof TCases & string]>>;
+  ): TypedAction<In, ExtractOutput<TCases[keyof TCases & string]>, Refs>;
   /** Flatten a nested array output. `a.flatten()` ≡ `pipe(a, flatten())`. */
-  flatten(): TypedAction<In, Out extends (infer TElement)[][] ? TElement[] : Out, Refs>;
+  flatten(): TypedAction<
+    In,
+    Out extends (infer TElement)[][] ? TElement[] : Out,
+    Refs
+  >;
   /** Discard output. `a.drop()` ≡ `pipe(a, drop)`. */
   drop(): TypedAction<In, never, Refs>;
   /** Wrap output as a tagged union member. Requires full variant map TDef so __def is carried. */
@@ -198,7 +198,9 @@ export type TypedAction<
     kind: TKind,
   ): TypedAction<In, TaggedUnion<TDef>, Refs>;
   /** Extract a field from the output object. `a.get("name")` ≡ `pipe(a, extractField("name"))`. */
-  get<TField extends keyof Out & string>(field: TField): TypedAction<In, Out[TField], Refs>;
+  get<TField extends keyof Out & string>(
+    field: TField,
+  ): TypedAction<In, Out[TField], Refs>;
   /**
    * Run this sub-pipeline, then merge its output back into the original input.
    * `pipe(extractField("x"), transform).augment()` takes `In`, runs the
@@ -303,7 +305,11 @@ export type Pipeable<
  * TypedAction is assignable to CaseHandler because CaseHandler only
  * requires a subset of TypedAction's phantom fields.
  */
-type CaseHandler<TIn = unknown, TOut = unknown, TRefs extends string = never> = Action & {
+type CaseHandler<
+  TIn = unknown,
+  TOut = unknown,
+  TRefs extends string = never,
+> = Action & {
   __phantom_in?: (input: TIn) => void;
   __phantom_out?: () => TOut;
   __refs?: { _brand: TRefs };
@@ -320,8 +326,21 @@ type CaseHandler<TIn = unknown, TOut = unknown, TRefs extends string = never> =
  * (`keyof ExtractDef<Out>` and `ExtractDef<Out>[K]`) instead of
  * conditional types (`KindOf<Out>` and `Extract<Out, { kind: K }>`).
  */
+// 0 extends 1 & T detects `any` — preserve as-is to avoid collapsing.
+type VoidToNull<T> = 0 extends 1 & T
+  ? T
+  : [T] extends [never]
+    ? never
+    : [T] extends [void]
+      ? null
+      : T;
+
 export type TaggedUnion<TDef extends Record<string, unknown>> = {
-  [K in keyof TDef & string]: { kind: K; value: TDef[K]; __def?: TDef };
+  [K in keyof TDef & string]: {
+    kind: K;
+    value: VoidToNull<TDef[K]>;
+    __def?: TDef;
+  };
 }[keyof TDef & string];
 
 /** Extract the variant map definition from a tagged union's phantom __def. */
@@ -352,50 +371,65 @@ type UnwrapVariant<T> = T extends { value: infer V } ? V : T;
  * output carries __def. Falls back to KindOf (conditional type) for
  * outputs without __def.
  */
-type BranchKeys<Out> =
-  [ExtractDef<Out>] extends [never] ? KindOf<Out> : keyof ExtractDef<Out> & string;
+type BranchKeys<Out> = [ExtractDef<Out>] extends [never]
+  ? KindOf<Out>
+  : keyof ExtractDef<Out> & string;
 
 /**
  * Branch case payload: prefer ExtractDef[K] (simple indexing) when available.
  * Falls back to UnwrapVariant<Extract<Out, { kind: K }>> for outputs without __def.
  */
-type BranchPayload<Out, K extends string> =
-  [ExtractDef<Out>] extends [never]
-    ? UnwrapVariant<Extract<Out, { kind: K }>>
-    : K extends keyof ExtractDef<Out> ? ExtractDef<Out>[K] : never;
-
+type BranchPayload<Out, K extends string> = [ExtractDef<Out>] extends [never]
+  ? UnwrapVariant<Extract<Out, { kind: K }>>
+  : K extends keyof ExtractDef<Out>
+    ? VoidToNull<ExtractDef<Out>[K]>
+    : never;
 
 // ---------------------------------------------------------------------------
 // typedAction — attach .then() and .forEach() as non-enumerable methods
 // ---------------------------------------------------------------------------
 
 // Shared implementations (one closure, not per-instance)
-function thenMethod<TIn, TOut, TRefs extends string, TNext, TRefs2 extends string>(
+function thenMethod<
+  TIn,
+  TOut,
+  TRefs extends string,
+  TNext,
+  TRefs2 extends string,
+>(
   this: TypedAction<TIn, TOut, TRefs>,
   next: Pipeable<TOut, TNext, TRefs2>,
 ): TypedAction<TIn, TNext, TRefs | TRefs2> {
   return typedAction({ kind: "Chain", first: this, rest: next as Action });
 }
 
-function forEachMethod(
-  this: TypedAction,
-  action: Action,
-): TypedAction {
-  return typedAction({ kind: "Chain", first: this, rest: { kind: "ForEach", action } });
+function forEachMethod(this: TypedAction, action: Action): TypedAction {
+  return typedAction({
+    kind: "Chain",
+    first: this,
+    rest: { kind: "ForEach", action },
+  });
 }
 
 function branchMethod(
   this: TypedAction,
   cases: Record<string, Action>,
 ): TypedAction {
-  return typedAction({ kind: "Chain", first: this, rest: { kind: "Branch", cases: unwrapBranchCases(cases) } });
+  return typedAction({
+    kind: "Chain",
+    first: this,
+    rest: { kind: "Branch", cases: unwrapBranchCases(cases) },
+  });
 }
 
 function flattenMethod(this: TypedAction): TypedAction {
   return typedAction({
     kind: "Chain",
     first: this,
-    rest: { kind: "Invoke", handler: { kind: "Builtin", builtin: { kind: "Flatten" } } },
+    rest: {
+      kind: "Invoke",
+      handler: { kind: "Builtin", builtin: { kind: "Flatten" } },
+    },
   });
 }
 
@@ -403,7 +437,10 @@ function dropMethod(this: TypedAction): TypedAction {
   return typedAction({
     kind: "Chain",
     first: this,
-    rest: { kind: "Invoke", handler: { kind: "Builtin", builtin: { kind: "Drop" } } },
+    rest: {
+      kind: "Invoke",
+      handler: { kind: "Builtin", builtin: { kind: "Drop" } },
+    },
   });
 }
 
@@ -411,7 +448,10 @@ function tagMethod(this: TypedAction, kind: string): TypedAction {
   return typedAction({
     kind: "Chain",
     first: this,
-    rest: { kind: "Invoke", handler: { kind: "Builtin", builtin: { kind: "Tag", value: kind } } },
+    rest: {
+      kind: "Invoke",
+      handler: { kind: "Builtin", builtin: { kind: "Tag", value: kind } },
+    },
   });
 }
 
@@ -419,7 +459,13 @@ function getMethod(this: TypedAction, field: string): TypedAction {
   return typedAction({
     kind: "Chain",
     first: this,
-    rest: { kind: "Invoke", handler: { kind: "Builtin", builtin: { kind: "ExtractField", value: field } } },
+    rest: {
+      kind: "Invoke",
+      handler: {
+        kind: "Builtin",
+        builtin: { kind: "ExtractField", value: field },
+      },
+    },
   });
 }
 
@@ -433,10 +479,16 @@ function augmentMethod(this: TypedAction): TypedAction {
       kind: "All",
       actions: [
         this as Action,
-        { kind: "Invoke", handler: { kind: "Builtin", builtin: { kind: "Identity" } } },
+        {
+          kind: "Invoke",
+          handler: { kind: "Builtin", builtin: { kind: "Identity" } },
+        },
       ],
     },
-    rest: { kind: "Invoke", handler: { kind: "Builtin", builtin: { kind: "Merge" } } },
+    rest: {
+      kind: "Invoke",
+      handler: { kind: "Builtin", builtin: { kind: "Merge" } },
+    },
   });
 }
 
@@ -444,7 +496,10 @@ function mergeMethod(this: TypedAction): TypedAction {
   return typedAction({
     kind: "Chain",
     first: this,
-    rest: { kind: "Invoke", handler: { kind: "Builtin", builtin: { kind: "Merge" } } },
+    rest: {
+      kind: "Invoke",
+      handler: { kind: "Builtin", builtin: { kind: "Merge" } },
+    },
   });
 }
 
@@ -452,7 +507,10 @@ function pickMethod(this: TypedAction, ...keys: string[]): TypedAction {
   return typedAction({
     kind: "Chain",
     first: this,
-    rest: { kind: "Invoke", handler: { kind: "Builtin", builtin: { kind: "Pick", value: keys } } },
+    rest: {
+      kind: "Invoke",
+      handler: { kind: "Builtin", builtin: { kind: "Pick", value: keys } },
+    },
   });
 }
 
@@ -466,9 +524,22 @@ function mapOptionMethod(this: TypedAction, action: Action): TypedAction {
     first: this,
     rest: {
       kind: "Branch",
-          cases: unwrapBranchCases({
-        Some: { kind: "Chain", first: action, rest: { kind: "Invoke", handler: { kind: "Builtin", builtin: { kind: "Tag", value: "Some" } } } },
-        None: { kind: "Invoke", handler: { kind: "Builtin", builtin: { kind: "Tag", value: "None" } } },
+      cases: unwrapBranchCases({
+        Some: {
+          kind: "Chain",
+          first: action,
+          rest: {
+            kind: "Invoke",
+            handler: {
+              kind: "Builtin",
+              builtin: { kind: "Tag", value: "Some" },
+            },
+          },
+        },
+        None: {
+          kind: "Invoke",
+          handler: { kind: "Builtin", builtin: { kind: "Tag", value: "None" } },
+        },
       }),
     },
   });
@@ -481,9 +552,22 @@ function mapErrMethod(this: TypedAction, action: Action): TypedAction {
     first: this,
     rest: {
       kind: "Branch",
-          cases: unwrapBranchCases({
-        Ok: { kind: "Invoke", handler: { kind: "Builtin", builtin: { kind: "Tag", value: "Ok" } } },
-        Err: { kind: "Chain", first: action, rest: { kind: "Invoke", handler: { kind: "Builtin", builtin: { kind: "Tag", value: "Err" } } } },
+      cases: unwrapBranchCases({
+        Ok: {
+          kind: "Invoke",
+          handler: { kind: "Builtin", builtin: { kind: "Tag", value: "Ok" } },
+        },
+        Err: {
+          kind: "Chain",
+          first: action,
+          rest: {
+            kind: "Invoke",
+            handler: {
+              kind: "Builtin",
+              builtin: { kind: "Tag", value: "Err" },
+            },
+          },
+        },
       }),
     },
   });
@@ -496,8 +580,11 @@ function unwrapOrMethod(this: TypedAction, defaultAction: Action): TypedAction {
     first: this,
     rest: {
       kind: "Branch",
-          cases: unwrapBranchCases({
-        Ok: { kind: "Invoke", handler: { kind: "Builtin", builtin: { kind: "Identity" } } },
+      cases: unwrapBranchCases({
+        Ok: {
+          kind: "Invoke",
+          handler: { kind: "Builtin", builtin: { kind: "Identity" } },
+        },
         Err: defaultAction,
       }),
     },
@@ -508,9 +595,11 @@ function unwrapOrMethod(this: TypedAction, defaultAction: Action): TypedAction {
  * Attach `.then()` and `.forEach()` methods to a plain Action object.
  * Methods are non-enumerable: invisible to JSON.stringify and toEqual.
  */
-export function typedAction<In = unknown, Out = unknown, Refs extends string = never>(
-  action: Action,
-): TypedAction<In, Out, Refs> {
+export function typedAction<
+  In = unknown,
+  Out = unknown,
+  Refs extends string = never,
+>(action: Action): TypedAction<In, Out, Refs> {
   if (!("then" in action)) {
     Object.defineProperties(action, {
       then: { value: thenMethod, configurable: true },
@@ -542,140 +631,20 @@ export function typedAction<In = unknown, Out = unknown, Refs extends string = n
  * avoid the `TypedAction<any, any, any>` constraint which fails for In=never
  * due to __phantom_in contravariance.
  */
-export type ExtractInput<T> =
-  T extends { __phantom_in?: (input: infer In) => void } ? In : never;
+export type ExtractInput<T> = T extends {
+  __phantom_in?: (input: infer In) => void;
+}
+  ? In
+  : never;
 
 /**
  * Extract the output type from a TypedAction.
  *
  * Uses direct phantom field extraction to avoid constraint issues.
  */
-export type ExtractOutput<T> =
-  T extends { __phantom_out?: () => infer Out } ? Out : never;
-
-/**
- * Extract step reference names tracked in a TypedAction's Refs parameter.
- *
- * Uses direct __refs extraction (not full TypedAction matching) to avoid
- * variance issues with contravariant __phantom_in when In = never.
- */
-export type ExtractRefs<T> =
-  T extends { __refs?: { _brand: infer R } }
-    ? R extends string
-      ? R
-      : never
-    : never;
-
-/**
- * Validates that all step references in R resolve to known step names
- * within the current batch only (keyof R). Previously registered steps
- * should be accessed via the callback's `steps` parameter, not stepRef.
- *
- * When valid: resolves to {} (transparent intersection).
- * When invalid: resolves to a type with __error that causes a compile error.
- */
-export type ValidateStepRefs<
-  R extends Record<string, Action>,
-> = [ExtractRefs<R[keyof R]>] extends [keyof R]
-  ? // eslint-disable-next-line @typescript-eslint/no-empty-object-type
-    {}
-  : {
-      __error: `Step reference to undefined step: ${Exclude<ExtractRefs<R[keyof R]>, keyof R> & string}`;
-    };
-
-// ---------------------------------------------------------------------------
-// Step Reference Tracking (Refs type parameter)
-// ---------------------------------------------------------------------------
-//
-// ## Overview
-//
-// Named steps can reference each other via `stepRef("B")`. These references
-// are validated at compile time: if you write `stepRef("Bt")` when only "A"
-// and "B" exist, TypeScript rejects it. This works through a third type
-// parameter on TypedAction called `Refs`.
-//
-// ## How it works
-//
-// 1. `stepRef<N extends string>(name: N)` returns `TypedAction<any, any, N>`.
-//    The literal string "B" is captured in the Refs position.
-//
-// 2. Every combinator propagates Refs via union. For example, pipe's 2-arg
-//    overload is:
-//
-//      pipe<T1, T2, T3, R1 extends string, R2 extends string>(
-//        a1: TypedAction<T1, T2, R1>,
-//        a2: TypedAction<T2, T3, R2>,
-//      ): TypedAction<T1, T3, R1 | R2>
-//
-//    So `pipe(check(), stepRef("B"))` has Refs = never | "B" = "B".
-//    And `pipe(stepRef("A"), stepRef("B"))` has Refs = "A" | "B".
-//
-// 3. `registerSteps` uses `ValidateStepRefs` to extract all Refs from the
-//    registered step values and check they're a subset of the current batch
-//    keys only (keyof R). Previously registered steps are accessed via the
-//    typed `steps` parameter in the callback form, not via stepRef:
-//
-//      registerSteps<R extends Record<string, Action>>(
-//        stepsOrBuild:
-//          | (R & ValidateStepRefs<R>)
-//          | ((ctx: { steps: StripRefs<TSteps>; stepRef: ... })
-//              => R & ValidateStepRefs<R>),
-//      )
-//
-//    When valid, ValidateStepRefs resolves to {} (transparent intersection).
-//    When invalid, it resolves to { __error: "Step reference to undefined
-//    step: Bt" }, which makes the argument incompatible and produces a
-//    readable compile error.
-//
-//    stepRef is not exported — it's only available as a parameter in the
-//    registerSteps callback. This ensures step references are always
-//    validated within a batch context.
-//
-// 4. `StripRefs` removes Refs from step types before they're passed to the
-//    workflow callback, since refs have already been validated by
-//    registerSteps and shouldn't propagate into the workflow's return type.
-//
-// ## Why Refs is boxed: `__refs?: { _brand: Refs }`
-//
-// The Refs phantom field uses a boxing wrapper `{ _brand: Refs }` instead of
-// a bare `__refs?: Refs`. This is necessary because of how TypeScript infers
-// generic type parameters from optional properties on discriminated unions.
-//
-// When Refs = never (the common case — most actions don't use stepRef), the
-// field `__refs?: never` collapses to `undefined` at the type level. When
-// pipe's overload tries to infer `R1 extends string` from this field, TS
-// sees `undefined`, can't find a valid inference for `R1`, and falls back to
-// the constraint bound `string`.
-//
-// This means `pipe(check(), recur())` — two actions with no step refs —
-// would infer Refs = string | string = string. Then ValidateStepRefs sees
-// Refs = string and rejects it because `string` doesn't extend the step
-// name literals.
-//
-// **Important**: this only happens with the real Action type (a discriminated
-// union of 8 variants). With a simple `{ kind: string }` Action type, TS
-// infers correctly. The union distribution changes how TS resolves optional
-// fields during inference.
-//
-// The fix: `__refs?: { _brand: Refs }`. When Refs = never, the field is
-// `__refs?: { _brand: never }`. The wrapper `{ _brand: never }` is a
-// distinct structural type (not just `undefined`), so TS can match
-// `{ _brand: R1 }` against `{ _brand: never }` and correctly infer
-// R1 = never.
-//
-// ## Why ExtractInput/ExtractOutput/ExtractRefs use structural extraction
-//
-// All three Extract* utilities match on individual phantom fields rather than
-// on the full TypedAction type. The constraint `TypedAction<any, any, any>`
-// fails for actions with In = never because `(input: never) => void` is not
-// assignable to `(input: any) => void` (function params are contravariant).
-// Structural extraction avoids this entirely.
-//
-// ExtractRefs uses a two-step conditional (`infer R` then `R extends string`)
-// rather than `infer R extends string` because the latter falls back to the
-// constraint bound `string` when R = never.
-//
-// ---------------------------------------------------------------------------
+export type ExtractOutput<T> = T extends { __phantom_out?: () => infer Out }
+  ? Out
+  : never;
 
 // ---------------------------------------------------------------------------
 // Combinators
@@ -686,7 +655,11 @@ export { chain } from "./chain.js";
 export { all } from "./all.js";
 export { bind, bindInput, type VarRef, type InferVarRefs } from "./bind.js";
 export { resetEffectIdCounter } from "./effect-id.js";
-import { allocateEffectId } from "./effect-id.js";
+import {
+  allocateRestartHandlerId,
+  type RestartHandlerId,
+  type ResumeHandlerId,
+} from "./effect-id.js";
 export { tryCatch } from "./try-catch.js";
 export { race, sleep, withTimeout } from "./race.js";
 
@@ -702,12 +675,20 @@ export function forEach<In, Out, R extends string = never>(
  * extracts `value` before passing to the handler. Case handlers receive
  * the payload directly, not the full `{ kind, value }` variant.
  */
-function unwrapBranchCases(cases: Record<string, Action>): Record<string, Action> {
+function unwrapBranchCases(
+  cases: Record<string, Action>,
+): Record<string, Action> {
   const unwrapped: Record<string, Action> = {};
   for (const key of Object.keys(cases)) {
     unwrapped[key] = {
       kind: "Chain",
-      first: { kind: "Invoke", handler: { kind: "Builtin", builtin: { kind: "ExtractField", value: "value" } } },
+      first: {
+        kind: "Invoke",
+        handler: {
+          kind: "Builtin",
+          builtin: { kind: "ExtractField", value: "value" },
+        },
+      },
       rest: cases[key],
     };
   }
@@ -723,8 +704,8 @@ function unwrapBranchCases(cases: Record<string, Action>): Record<string, Action
  * Example: `BranchInput<{ Yes: TypedAction<number, ...>, No: TypedAction<string, ...> }>`
  *        = `{ kind: "Yes"; value: number } | { kind: "No"; value: string }`
  *
- * When a case handler uses `any` as input (e.g. stepRef), the wrapping
- * produces `{ kind: K; value: any }`, which is the correct escape hatch.
+ * When a case handler uses `any` as input, the wrapping produces
+ * `{ kind: K; value: any }`, which is the correct escape hatch.
  */
 export type BranchInput<TCases> = {
   [K in keyof TCases & string]: { kind: K; value: ExtractInput<TCases[K]> };
@@ -735,8 +716,7 @@ export function branch<TCases extends Record<string, Action>>(
   cases: TCases,
 ): TypedAction<
   BranchInput<TCases>,
-  ExtractOutput<TCases[keyof TCases & string]>,
-  ExtractRefs<TCases[keyof TCases & string]>
+  ExtractOutput<TCases[keyof TCases & string]>
 > {
   return typedAction({ kind: "Branch", cases: unwrapBranchCases(cases) });
 }
@@ -746,7 +726,9 @@ type LoopResultDef<TContinue, TBreak> = {
   Break: TBreak;
 };
 
-export type LoopResult<TContinue, TBreak> = TaggedUnion<LoopResultDef<TContinue, TBreak>>;
+export type LoopResult<TContinue, TBreak> = TaggedUnion<
+  LoopResultDef<TContinue, TBreak>
+>;
 
 // ---------------------------------------------------------------------------
 // Shared AST constants for control flow compilation
@@ -754,12 +736,7 @@ export type LoopResult<TContinue, TBreak> = TaggedUnion<LoopResultDef<TContinue,
 
 const EXTRACT_PAYLOAD: Action = {
   kind: "Invoke",
-  handler: { kind: "Builtin", builtin: { kind: "ExtractField", value: "payload" } },
-};
-
-const TAG_RESTART_BODY: Action = {
-  kind: "Invoke",
-  handler: { kind: "Builtin", builtin: { kind: "Tag", value: "RestartBody" } },
+  handler: { kind: "Builtin", builtin: { kind: "ExtractIndex", value: 0 } },
 };
 
 const TAG_CONTINUE: Action = {
@@ -767,23 +744,16 @@ const TAG_CONTINUE: Action = {
   handler: { kind: "Builtin", builtin: { kind: "Tag", value: "Continue" } },
 };
 
-const TAG_BREAK: Action = {
+export const TAG_BREAK: Action = {
   kind: "Invoke",
   handler: { kind: "Builtin", builtin: { kind: "Tag", value: "Break" } },
 };
 
-const IDENTITY: Action = {
+export const IDENTITY: Action = {
   kind: "Invoke",
   handler: { kind: "Builtin", builtin: { kind: "Identity" } },
 };
 
-/** Handler: extract payload, tag as RestartBody. */
-const RESTART_BODY_HANDLER: Action = {
-  kind: "Chain",
-  first: EXTRACT_PAYLOAD,
-  rest: TAG_RESTART_BODY,
-};
-
 // ---------------------------------------------------------------------------
 // recur — restart body primitive
 // ---------------------------------------------------------------------------
@@ -795,25 +765,25 @@ const RESTART_BODY_HANDLER: Action = {
  * If the body completes normally → output is TOut.
  * If restart fires → body re-executes with the restarted value.
  *
- * Compiled form: Handle(effectId, body, RestartBodyHandler)
+ * Compiled form: `RestartHandle(id, ExtractIndex(0), body)`
  */
 export function recur<TIn = never, TOut = any, TRefs extends string = never>(
   bodyFn: (restart: TypedAction<TIn, never>) => Pipeable<TIn, TOut, TRefs>,
 ): TypedAction<PipeIn<TIn>, TOut, TRefs> {
-  const effectId = allocateEffectId();
+  const restartHandlerId = allocateRestartHandlerId();
 
   const restartAction = typedAction<TIn, never>({
-    kind: "Perform",
-    effect_id: effectId,
+    kind: "RestartPerform",
+    restart_handler_id: restartHandlerId,
   });
 
   const body = bodyFn(restartAction) as Action;
 
   return typedAction({
-    kind: "Handle",
-    effect_id: effectId,
+    kind: "RestartHandle",
+    restart_handler_id: restartHandlerId,
     body,
-    handler: RESTART_BODY_HANDLER,
+    handler: EXTRACT_PAYLOAD,
   });
 }
 
@@ -833,20 +803,29 @@ export function recur<TIn = never, TOut = any, TRefs extends string = never>(
  * a Branch. earlyReturn tags with Break and performs — the handler restarts
  * the body, Branch takes the Break path, and the value exits.
  */
-export function earlyReturn<TEarlyReturn = never, TIn = any, TOut = any, TRefs extends string = never>(
-  bodyFn: (earlyReturn: TypedAction<TEarlyReturn, never>) => Pipeable<TIn, TOut, TRefs>,
+export function earlyReturn<
+  TEarlyReturn = never,
+  TIn = any,
+  TOut = any,
+  TRefs extends string = never,
+>(
+  bodyFn: (
+    earlyReturn: TypedAction<TEarlyReturn, never>,
+  ) => Pipeable<TIn, TOut, TRefs>,
 ): TypedAction<TIn, TEarlyReturn | TOut, TRefs> {
-  const effectId = allocateEffectId();
+  const restartHandlerId = allocateRestartHandlerId();
 
   const earlyReturnAction = typedAction<TEarlyReturn, never>({
     kind: "Chain",
     first: TAG_BREAK,
-    rest: { kind: "Perform", effect_id: effectId },
+    rest: { kind: "RestartPerform", restart_handler_id: restartHandlerId },
   });
 
   const body = bodyFn(earlyReturnAction) as Action;
 
-  return typedAction(buildLoopAction(effectId, body));
+  return typedAction(
+    buildRestartBranchAction(restartHandlerId, body, IDENTITY),
+  );
 }
 
 // ---------------------------------------------------------------------------
@@ -854,27 +833,33 @@ export function earlyReturn<TEarlyReturn = never, TIn = any, TOut = any, TRefs e
 // ---------------------------------------------------------------------------
 
 /**
- * Build the restart+branch compiled form used by earlyReturn and loop:
- * Chain(Tag("Continue"), Handle(effectId, Branch({ Continue: body, Break: identity() }), RestartBodyHandler))
+ * Build the restart+branch compiled form:
+ * `Chain(Tag("Continue"), RestartHandle(id, ExtractIndex(0), Branch({ Continue: continueArm, Break: breakArm })))`
  *
- * Input is tagged Continue so the Branch enters the body on first execution.
- * Continue tag → restart → re-enters body. Break tag → restart → exits via Branch.
+ * Input is tagged Continue so the Branch enters the continueArm on first execution.
+ * Continue tag → restart → re-enters continueArm. Break tag → restart → runs breakArm, exits `RestartHandle`.
+ *
+ * Used by earlyReturn, loop, tryCatch, and race.
  */
-function buildLoopAction(effectId: number, body: Action): Action {
+export function buildRestartBranchAction(
+  restartHandlerId: RestartHandlerId,
+  continueArm: Action,
+  breakArm: Action,
+): Action {
   return {
     kind: "Chain",
     first: TAG_CONTINUE,
     rest: {
-      kind: "Handle",
-      effect_id: effectId,
+      kind: "RestartHandle",
+      restart_handler_id: restartHandlerId,
       body: {
         kind: "Branch",
         cases: unwrapBranchCases({
-          Continue: body,
-          Break: IDENTITY,
+          Continue: continueArm,
+          Break: breakArm,
         }),
       },
-      handler: RESTART_BODY_HANDLER,
+      handler: EXTRACT_PAYLOAD,
     },
   };
 }
@@ -886,17 +871,20 @@ function buildLoopAction(effectId: number, body: Action): Action {
  *
  * Both are TypedAction values (not functions), consistent with throwError in tryCatch.
  *
- * Compiles to Handle/Perform/Branch — same effect substrate as tryCatch and earlyReturn.
+ * Compiles to `RestartHandle`/`RestartPerform`/Branch — same effect substrate as tryCatch and earlyReturn.
  */
 export function loop<TBreak = never, TIn = never, TRefs extends string = never>(
   bodyFn: (
     recur: TypedAction<TIn, never>,
-    done: TypedAction<TBreak, never>,
+    done: TypedAction<VoidToNull<TBreak>, never>,
   ) => Pipeable<TIn, never, TRefs>,
-): TypedAction<PipeIn<TIn>, TBreak, TRefs> {
-  const effectId = allocateEffectId();
+): TypedAction<PipeIn<TIn>, VoidToNull<TBreak>, TRefs> {
+  const restartHandlerId = allocateRestartHandlerId();
 
-  const perform: Action = { kind: "Perform", effect_id: effectId };
+  const perform: Action = {
+    kind: "RestartPerform",
+    restart_handler_id: restartHandlerId,
+  };
 
   const recurAction = typedAction<TIn, never>({
     kind: "Chain",
@@ -904,7 +892,7 @@ export function loop<TBreak = never, TIn = never, TRefs extends string = never>(
     rest: perform,
   });
 
-  const doneAction = typedAction<TBreak, never>({
+  const doneAction = typedAction<VoidToNull<TBreak>, never>({
     kind: "Chain",
     first: TAG_BREAK,
     rest: perform,
@@ -912,196 +900,16 @@ export function loop<TBreak = never, TIn = never, TRefs extends string = never>(
 
   const body = bodyFn(recurAction, doneAction) as Action;
 
-  return typedAction(buildLoopAction(effectId, body));
-}
-
-/**
- * Create a typed step reference. The name is tracked at the type level
- * via the Refs parameter so registerSteps can validate all references resolve.
- *
- * Not exported — only available as a parameter in registerSteps callbacks.
- * This ensures step references are always validated within a batch context.
- *
- * **Warning: no input/output type safety.** stepRef returns
- * `TypedAction<any, any, N>` — it validates the reference *name* at compile
- * time, but provides no type checking on input or output. The referenced
- * step's types are unknown at the call site (mutual recursion means the
- * step may not be fully defined yet). Prefer `steps.X` from the callback
- * parameter when referencing previously registered steps, as that preserves
- * full input/output types.
- */
-function stepRef<N extends string>(name: N): TypedAction<any, any, N> {
-  return typedAction({
-    kind: "Step",
-    step: { kind: "Named", name },
-  });
+  return typedAction(
+    buildRestartBranchAction(restartHandlerId, body, IDENTITY),
+  );
 }
 
 // ---------------------------------------------------------------------------
 // Config builders
 // ---------------------------------------------------------------------------
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-type AnyAction = TypedAction<any, any, any>;
-
-/**
- * Strip the Refs parameter from registered step types. Refs are a compile-time
- * mechanism for validating step references in registerSteps — once validated,
- * they shouldn't propagate into the workflow callback's return type.
- */
-type StripRefs<TSteps> = {
-  [K in keyof TSteps]: TypedAction<ExtractInput<TSteps[K]>, ExtractOutput<TSteps[K]>>;
-};
-
-/** Simple config with no named steps. */
-export function config<Out>(workflow: WorkflowAction<Out>): Config<Out> {
+/** Simple config factory. */
+export function config(workflow: Action): Config {
   return { workflow };
 }
-
-/** Builder for configs with type-safe named steps. */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export class ConfigBuilder<TSteps extends Record<string, AnyAction> = {}> {
-  private readonly _steps: Record<string, Action>;
-
-  constructor(steps: Record<string, Action> = {}) {
-    this._steps = steps;
-  }
-
-  /**
-   * Register named steps. Two forms:
-   *
-   * **Object form** — for steps with no cross-references:
-   *
-   * ```ts
-   * .registerSteps({
-   *   Setup: setup(),
-   *   Migrate: pipe(listFiles(), forEach(migrate())),
-   * })
-   * ```
-   *
-   * **Callback form** — for mutual recursion (via `stepRef`) and/or
-   * referencing previously registered steps (via `steps`):
-   *
-   * ```ts
-   * .registerSteps({ Setup: setup() })
-   * .registerSteps(({ steps, stepRef }) => ({
-   *   Pipeline: pipe(steps.Setup, process(), stepRef("FixCycle")),
-   *   FixCycle: loop(pipe(check(), stepRef("Pipeline"))),
-   * }))
-   * ```
-   *
-   * `stepRef` only validates against current-batch keys. Previously
-   * registered steps must be accessed via `steps`.
-   */
-  registerSteps<R extends Record<string, Action>>(
-    steps: R & ValidateStepRefs<R>,
-  ): ConfigBuilder<TSteps & R>;
-  registerSteps<R extends Record<string, Action>>(
-    build: (ctx: {
-      steps: StripRefs<TSteps>;
-      stepRef: <N extends string>(name: N) => TypedAction<any, any, N>;
-    }) => R,
-  ): [ExtractRefs<R[keyof R]>] extends [keyof R]
-    ? ConfigBuilder<TSteps & R>
-    : ValidateStepRefs<R>;
-  registerSteps<R extends Record<string, Action>>(
-    stepsOrBuild:
-      | (R & ValidateStepRefs<R>)
-      | ((ctx: {
-          steps: StripRefs<TSteps>;
-          stepRef: <N extends string>(name: N) => TypedAction<any, any, N>;
-        }) => R),
-  ): ConfigBuilder<TSteps & R> {
-    const resolved =
-      typeof stepsOrBuild === "function"
-        ? stepsOrBuild({ steps: this._buildStepRefs() as StripRefs<TSteps>, stepRef })
-        : stepsOrBuild;
-    return new ConfigBuilder({
-      ...this._steps,
-      ...resolved,
-    }) as ConfigBuilder<TSteps & R>;
-  }
-
-  /** Build typed step reference objects for previously registered steps. */
-  private _buildStepRefs(): Record<string, Action> {
-    const refs: Record<string, Action> = {};
-    for (const name of Object.keys(this._steps)) {
-      refs[name] = typedAction({ kind: "Step", step: { kind: "Named", name } });
-    }
-    return refs;
-  }
-
-  /**
-   * Define the workflow entry point.
-   *
-   * @param build - receives `{ steps, self }`.
-   *   `self` is `TypedAction<never, never>` — a jump to the workflow
-   *   root. Input `never` because it doesn't consume pipeline data.
-   *   Output `never` because the execution path restarts (and `never`
-   *   is eliminated from unions, so branches with `self` don't pollute
-   *   the output type).
-   *
-   *   Use `pipe(drop, self)` to place `self` in a branch case.
-   *
-   *   Note: ideally `self` would be `TypedAction<never, Out>` so it
-   *   carries the workflow's output type, but TypeScript can't infer
-   *   a generic from a callback's return and use it in the same
-   *   callback's parameter — Out falls back to `unknown`.
-   */
-  workflow<Out>(
-    build: (ctx: {
-      steps: StripRefs<TSteps>;
-      self: TypedAction<never, never>;
-    }) => WorkflowAction<Out>,
-  ): RunnableConfig<Out> {
-    const stepRefs: Record<string, Action> = {};
-    for (const name of Object.keys(this._steps)) {
-      stepRefs[name] = typedAction({ kind: "Step", step: { kind: "Named", name } });
-    }
-    const self = typedAction<never, never>({
-      kind: "Step",
-      step: { kind: "Root" },
-    });
-    const workflowAction = build({ steps: stepRefs as StripRefs<TSteps>, self });
-    const steps = Object.keys(this._steps).length > 0 ? this._steps : undefined;
-    return new RunnableConfig(workflowAction, steps);
-  }
-}
-
-/**
- * A workflow config with a `.run()` method for execution.
- *
- * Serializes to the same JSON shape as `Config` via `toJSON()`, so it
- * works with `JSON.stringify` and round-trip tests.
- */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export class RunnableConfig<Out = any> {
-  readonly workflow: WorkflowAction<Out>;
-  readonly steps?: Record<string, Action>;
-
-  constructor(workflow: WorkflowAction<Out>, steps?: Record<string, Action>) {
-    this.workflow = workflow;
-    this.steps = steps;
-  }
-
-  /** Run this workflow to completion. Prints result to stdout. */
-  async run(): Promise<void> {
-    // Dynamic import to avoid pulling in Node.js APIs at module load time
-    // (keeps ast.ts importable in non-Node environments for type checking).
-    const { run } = await import("./run.js");
-    await run(this.toJSON());
-  }
-
-  /** Serialize to the same shape as Config. */
-  toJSON(): Config<Out> {
-    const result: Config<Out> = { workflow: this.workflow };
-    if (this.steps) {
-      result.steps = this.steps;
-    }
-    return result;
-  }
-}
-
-export function workflowBuilder(): ConfigBuilder {
-  return new ConfigBuilder();
-}