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

package/src/handler.ts

@@ -1,6 +1,7 @@
 import { fileURLToPath } from "node:url";
 import type { z } from "zod";
 import { type TypedAction, typedAction } from "./ast.js";
+import { zodToCheckedJsonSchema } from "./schema.js";
 
 // ---------------------------------------------------------------------------
 // HandlerDefinition — the user's handle function + optional validators
@@ -12,6 +13,7 @@ export interface HandlerDefinition<
   TStepConfig = unknown,
 > {
   inputValidator?: z.ZodType<TValue>;
+  outputValidator?: z.ZodType<TOutput>;
   stepConfigValidator?: z.ZodType<TStepConfig>;
   handle: (context: {
     value: TValue;
@@ -22,6 +24,7 @@ export interface HandlerDefinition<
 /** Runtime-only handler definition shape — erases generic type info. */
 interface UntypedHandlerDefinition {
   inputValidator?: z.ZodType;
+  outputValidator?: z.ZodType;
   stepConfigValidator?: z.ZodType;
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   handle: (...args: any[]) => Promise<unknown>;
@@ -37,7 +40,10 @@ const HANDLER_BRAND = Symbol.for("barnum:handler");
  * Opaque handler reference with typed metadata. The `__definition` property
  * is non-enumerable — invisible to `JSON.stringify`, visible to the worker.
  */
-export type Handler<TValue = unknown, TOutput = unknown> = TypedAction<TValue, TOutput> & {
+export type Handler<TValue = unknown, TOutput = unknown> = TypedAction<
+  TValue,
+  TOutput
+> & {
   readonly [HANDLER_BRAND]: true;
   readonly __definition: UntypedHandlerDefinition;
 };
@@ -88,26 +94,18 @@ function getCallerFilePath(): string {
 type HandlerOutput<TOutput> = [TOutput] extends [void] ? never : TOutput;
 
 // ---------------------------------------------------------------------------
-// createHandler — handlers with no config, returns TypedAction directly
+// createHandler — single overload, validators optional
 // ---------------------------------------------------------------------------
 
-// With inputValidator: handler accepts typed pipeline input.
-export function createHandler<TValue, TOutput>(
+export function createHandler<TValue = never, TOutput = unknown>(
   definition: {
-    inputValidator: z.ZodType<TValue>;
+    inputValidator?: z.ZodType<TValue>;
+    outputValidator?: z.ZodType<NoInfer<TOutput>>;
     handle: (context: { value: TValue }) => Promise<TOutput>;
   },
   exportName?: string,
 ): Handler<TValue, HandlerOutput<TOutput>>;
 
-// Without inputValidator: handler takes no pipeline input.
-export function createHandler<TOutput>(
-  definition: {
-    handle: () => Promise<TOutput>;
-  },
-  exportName?: string,
-): Handler<never, HandlerOutput<TOutput>>;
-
 // Implementation
 export function createHandler(
   definition: UntypedHandlerDefinition,
@@ -117,9 +115,28 @@ export function createHandler(
   const filePath = getCallerFilePath();
   const funcName = exportName ?? "default";
 
+  const inputSchema = definition.inputValidator
+    ? zodToCheckedJsonSchema(
+        definition.inputValidator,
+        `${filePath}:${funcName} input`,
+      )
+    : undefined;
+  const outputSchema = definition.outputValidator
+    ? zodToCheckedJsonSchema(
+        definition.outputValidator,
+        `${filePath}:${funcName} output`,
+      )
+    : undefined;
+
   const action = typedAction({
     kind: "Invoke",
-    handler: { kind: "TypeScript", module: filePath, func: funcName },
+    handler: {
+      kind: "TypeScript",
+      module: filePath,
+      func: funcName,
+      ...(inputSchema && { input_schema: inputSchema }),
+      ...(outputSchema && { output_schema: outputSchema }),
+    },
   });
 
   // Non-enumerable: invisible to JSON.stringify, visible to the worker
@@ -136,28 +153,26 @@ export function createHandler(
 }
 
 // ---------------------------------------------------------------------------
-// createHandlerWithConfig — handlers that need static config
+// createHandlerWithConfig — single overload, validators optional
 // ---------------------------------------------------------------------------
 
-// With inputValidator: handler accepts typed pipeline input + config.
-export function createHandlerWithConfig<TValue, TOutput, TStepConfig>(
+export function createHandlerWithConfig<
+  TValue = never,
+  TOutput = unknown,
+  TStepConfig = unknown,
+>(
   definition: {
-    inputValidator: z.ZodType<TValue>;
-    stepConfigValidator: z.ZodType<TStepConfig>;
-    handle: (context: { value: TValue; stepConfig: TStepConfig }) => Promise<TOutput>;
+    inputValidator?: z.ZodType<TValue>;
+    outputValidator?: z.ZodType<NoInfer<TOutput>>;
+    stepConfigValidator?: z.ZodType<TStepConfig>;
+    handle: (context: {
+      value: TValue;
+      stepConfig: TStepConfig;
+    }) => Promise<TOutput>;
   },
   exportName?: string,
 ): (config: TStepConfig) => TypedAction<TValue, HandlerOutput<TOutput>>;
 
-// Without inputValidator: handler takes no pipeline input, has config.
-export function createHandlerWithConfig<TOutput, TStepConfig>(
-  definition: {
-    stepConfigValidator: z.ZodType<TStepConfig>;
-    handle: (context: { stepConfig: TStepConfig }) => Promise<TOutput>;
-  },
-  exportName?: string,
-): (config: TStepConfig) => TypedAction<never, HandlerOutput<TOutput>>;
-
 // Implementation
 export function createHandlerWithConfig(
   definition: UntypedHandlerDefinition,
@@ -167,6 +182,19 @@ export function createHandlerWithConfig(
   const filePath = getCallerFilePath();
   const funcName = exportName ?? "default";
 
+  const inputSchema = definition.inputValidator
+    ? zodToCheckedJsonSchema(
+        definition.inputValidator,
+        `${filePath}:${funcName} input`,
+      )
+    : undefined;
+  const outputSchema = definition.outputValidator
+    ? zodToCheckedJsonSchema(
+        definition.outputValidator,
+        `${filePath}:${funcName} output`,
+      )
+    : undefined;
+
   // Internal handle that unpacks the [value, config] tuple from All
   const internalDefinition: UntypedHandlerDefinition = {
     handle: ({ value }: { value: unknown }) => {
@@ -177,7 +205,13 @@ export function createHandlerWithConfig(
 
   const invokeAction = typedAction({
     kind: "Invoke",
-    handler: { kind: "TypeScript", module: filePath, func: funcName },
+    handler: {
+      kind: "TypeScript",
+      module: filePath,
+      func: funcName,
+      ...(inputSchema && { input_schema: inputSchema }),
+      ...(outputSchema && { output_schema: outputSchema }),
+    },
   });
 
   // Non-enumerable: invisible to JSON.stringify, visible to the worker
@@ -199,8 +233,17 @@ export function createHandlerWithConfig(
       first: {
         kind: "All",
         actions: [
-          { kind: "Invoke", handler: { kind: "Builtin", builtin: { kind: "Identity" } } },
-          { kind: "Invoke", handler: { kind: "Builtin", builtin: { kind: "Constant", value: config } } },
+          {
+            kind: "Invoke",
+            handler: { kind: "Builtin", builtin: { kind: "Identity" } },
+          },
+          {
+            kind: "Invoke",
+            handler: {
+              kind: "Builtin",
+              builtin: { kind: "Constant", value: config },
+            },
+          },
         ],
       },
       rest: invokeAction,

package/src/index.ts

@@ -1,3 +1,5 @@
+import type { TaggedUnion, OptionDef, ResultDef } from "./ast.js";
+
 export * from "./ast.js";
 export {
   constant,
@@ -17,6 +19,12 @@ export {
   Option,
   Result,
 } from "./builtins.js";
-export { createHandler, createHandlerWithConfig } from "./handler.js";
-export type { HandlerDefinition, Handler } from "./handler.js";
-export { run } from "./run.js";
+export * from "./handler.js";
+export { runPipeline } from "./run.js";
+export { zodToCheckedJsonSchema } from "./schema.js";
+
+// Declaration merge: the explicit value exports of Option/Result from builtins
+// shadow the type-only exports from ast's `export *`. Re-declare the generic
+// type aliases here so consumers get both the type and value under one name.
+export type Option<T> = TaggedUnion<OptionDef<T>>;
+export type Result<TValue, TError> = TaggedUnion<ResultDef<TValue, TError>>;

package/src/pipe.ts

@@ -1,4 +1,10 @@
-import { type Action, type PipeIn, type Pipeable, type TypedAction, typedAction } from "./ast.js";
+import {
+  type Action,
+  type PipeIn,
+  type Pipeable,
+  type TypedAction,
+  typedAction,
+} from "./ast.js";
 import { identity } from "./builtins.js";
 
 export function pipe<T1, T2, R1 extends string>(
@@ -9,16 +15,28 @@ export function pipe<T1, T2, T3, R1 extends string, R2 extends string>(
   a2: Pipeable<T2, T3, R2>,
 ): TypedAction<PipeIn<T1>, T3, R1 | R2>;
 export function pipe<
-  T1, T2, T3, T4,
-  R1 extends string, R2 extends string, R3 extends string,
+  T1,
+  T2,
+  T3,
+  T4,
+  R1 extends string,
+  R2 extends string,
+  R3 extends string,
 >(
   a1: Pipeable<T1, T2, R1>,
   a2: Pipeable<T2, T3, R2>,
   a3: Pipeable<T3, T4, R3>,
 ): TypedAction<PipeIn<T1>, T4, R1 | R2 | R3>;
 export function pipe<
-  T1, T2, T3, T4, T5,
-  R1 extends string, R2 extends string, R3 extends string, R4 extends string,
+  T1,
+  T2,
+  T3,
+  T4,
+  T5,
+  R1 extends string,
+  R2 extends string,
+  R3 extends string,
+  R4 extends string,
 >(
   a1: Pipeable<T1, T2, R1>,
   a2: Pipeable<T2, T3, R2>,
@@ -26,9 +44,17 @@ export function pipe<
   a4: Pipeable<T4, T5, R4>,
 ): TypedAction<PipeIn<T1>, T5, R1 | R2 | R3 | R4>;
 export function pipe<
-  T1, T2, T3, T4, T5, T6,
-  R1 extends string, R2 extends string, R3 extends string,
-  R4 extends string, R5 extends string,
+  T1,
+  T2,
+  T3,
+  T4,
+  T5,
+  T6,
+  R1 extends string,
+  R2 extends string,
+  R3 extends string,
+  R4 extends string,
+  R5 extends string,
 >(
   a1: Pipeable<T1, T2, R1>,
   a2: Pipeable<T2, T3, R2>,
@@ -37,9 +63,19 @@ export function pipe<
   a5: Pipeable<T5, T6, R5>,
 ): TypedAction<PipeIn<T1>, T6, R1 | R2 | R3 | R4 | R5>;
 export function pipe<
-  T1, T2, T3, T4, T5, T6, T7,
-  R1 extends string, R2 extends string, R3 extends string,
-  R4 extends string, R5 extends string, R6 extends string,
+  T1,
+  T2,
+  T3,
+  T4,
+  T5,
+  T6,
+  T7,
+  R1 extends string,
+  R2 extends string,
+  R3 extends string,
+  R4 extends string,
+  R5 extends string,
+  R6 extends string,
 >(
   a1: Pipeable<T1, T2, R1>,
   a2: Pipeable<T2, T3, R2>,
@@ -49,9 +85,20 @@ export function pipe<
   a6: Pipeable<T6, T7, R6>,
 ): TypedAction<PipeIn<T1>, T7, R1 | R2 | R3 | R4 | R5 | R6>;
 export function pipe<
-  T1, T2, T3, T4, T5, T6, T7, T8,
-  R1 extends string, R2 extends string, R3 extends string,
-  R4 extends string, R5 extends string, R6 extends string,
+  T1,
+  T2,
+  T3,
+  T4,
+  T5,
+  T6,
+  T7,
+  T8,
+  R1 extends string,
+  R2 extends string,
+  R3 extends string,
+  R4 extends string,
+  R5 extends string,
+  R6 extends string,
   R7 extends string,
 >(
   a1: Pipeable<T1, T2, R1>,
@@ -63,10 +110,23 @@ export function pipe<
   a7: Pipeable<T7, T8, R7>,
 ): TypedAction<PipeIn<T1>, T8, R1 | R2 | R3 | R4 | R5 | R6 | R7>;
 export function pipe<
-  T1, T2, T3, T4, T5, T6, T7, T8, T9,
-  R1 extends string, R2 extends string, R3 extends string,
-  R4 extends string, R5 extends string, R6 extends string,
-  R7 extends string, R8 extends string,
+  T1,
+  T2,
+  T3,
+  T4,
+  T5,
+  T6,
+  T7,
+  T8,
+  T9,
+  R1 extends string,
+  R2 extends string,
+  R3 extends string,
+  R4 extends string,
+  R5 extends string,
+  R6 extends string,
+  R7 extends string,
+  R8 extends string,
 >(
   a1: Pipeable<T1, T2, R1>,
   a2: Pipeable<T2, T3, R2>,
@@ -78,10 +138,25 @@ export function pipe<
   a8: Pipeable<T8, T9, R8>,
 ): TypedAction<PipeIn<T1>, T9, R1 | R2 | R3 | R4 | R5 | R6 | R7 | R8>;
 export function pipe<
-  T1, T2, T3, T4, T5, T6, T7, T8, T9, T10,
-  R1 extends string, R2 extends string, R3 extends string,
-  R4 extends string, R5 extends string, R6 extends string,
-  R7 extends string, R8 extends string, R9 extends string,
+  T1,
+  T2,
+  T3,
+  T4,
+  T5,
+  T6,
+  T7,
+  T8,
+  T9,
+  T10,
+  R1 extends string,
+  R2 extends string,
+  R3 extends string,
+  R4 extends string,
+  R5 extends string,
+  R6 extends string,
+  R7 extends string,
+  R8 extends string,
+  R9 extends string,
 >(
   a1: Pipeable<T1, T2, R1>,
   a2: Pipeable<T2, T3, R2>,
@@ -94,10 +169,26 @@ export function pipe<
   a9: Pipeable<T9, T10, R9>,
 ): TypedAction<PipeIn<T1>, T10, R1 | R2 | R3 | R4 | R5 | R6 | R7 | R8 | R9>;
 export function pipe<
-  T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11,
-  R1 extends string, R2 extends string, R3 extends string,
-  R4 extends string, R5 extends string, R6 extends string,
-  R7 extends string, R8 extends string, R9 extends string,
+  T1,
+  T2,
+  T3,
+  T4,
+  T5,
+  T6,
+  T7,
+  T8,
+  T9,
+  T10,
+  T11,
+  R1 extends string,
+  R2 extends string,
+  R3 extends string,
+  R4 extends string,
+  R5 extends string,
+  R6 extends string,
+  R7 extends string,
+  R8 extends string,
+  R9 extends string,
   R10 extends string,
 >(
   a1: Pipeable<T1, T2, R1>,
@@ -110,7 +201,11 @@ export function pipe<
   a8: Pipeable<T8, T9, R8>,
   a9: Pipeable<T9, T10, R9>,
   a10: Pipeable<T10, T11, R10>,
-): TypedAction<PipeIn<T1>, T11, R1 | R2 | R3 | R4 | R5 | R6 | R7 | R8 | R9 | R10>;
+): TypedAction<
+  PipeIn<T1>,
+  T11,
+  R1 | R2 | R3 | R4 | R5 | R6 | R7 | R8 | R9 | R10
+>;
 export function pipe(...actions: Action[]): Action {
   if (actions.length === 0) {
     return identity;
@@ -118,7 +213,7 @@ export function pipe(...actions: Action[]): Action {
   if (actions.length === 1) {
     return actions[0];
   }
-  return actions.reduceRight((rest, first) =>
-    typedAction({ kind: "Chain", first, rest }) as Action,
+  return actions.reduceRight(
+    (rest, first) => typedAction({ kind: "Chain", first, rest }) as Action,
   );
 }

package/src/race.ts

@@ -1,20 +1,22 @@
-import { type Action, type Pipeable, type Result, type TypedAction, typedAction } from "./ast.js";
-import { allocateEffectId } from "./effect-id.js";
+import {
+  type Action,
+  type Pipeable,
+  type Result,
+  type TypedAction,
+  typedAction,
+  buildRestartBranchAction,
+  TAG_BREAK,
+  IDENTITY,
+} from "./ast.js";
+import {
+  allocateRestartHandlerId,
+  type RestartHandlerId,
+} from "./effect-id.js";
 
 // ---------------------------------------------------------------------------
 // Shared AST fragments
 // ---------------------------------------------------------------------------
 
-const EXTRACT_PAYLOAD: Action = {
-  kind: "Invoke",
-  handler: { kind: "Builtin", builtin: { kind: "ExtractField", value: "payload" } },
-};
-
-const TAG_DISCARD: Action = {
-  kind: "Invoke",
-  handler: { kind: "Builtin", builtin: { kind: "Tag", value: "Discard" } },
-};
-
 const TAG_OK: Action = {
   kind: "Invoke",
   handler: { kind: "Builtin", builtin: { kind: "Tag", value: "Ok" } },
@@ -25,12 +27,18 @@ const TAG_ERR: Action = {
   handler: { kind: "Builtin", builtin: { kind: "Tag", value: "Err" } },
 };
 
-/** Handler DAG shared by race and withTimeout: extract payload, tag Discard. */
-const RACE_HANDLER: Action = {
-  kind: "Chain",
-  first: EXTRACT_PAYLOAD,
-  rest: TAG_DISCARD,
-};
+/**
+ * `Chain(Tag("Break"), RestartPerform(id))` — shared by race branches.
+ * The winning branch tags its result as Break, then performs. The handler
+ * restarts the body; Branch takes the Break arm (identity), `RestartHandle` exits.
+ */
+function breakPerform(restartHandlerId: RestartHandlerId): Action {
+  return {
+    kind: "Chain",
+    first: TAG_BREAK,
+    rest: { kind: "RestartPerform", restart_handler_id: restartHandlerId },
+  };
+}
 
 // ---------------------------------------------------------------------------
 // race — first branch to complete wins, losers cancelled
@@ -38,26 +46,27 @@ const RACE_HANDLER: Action = {
 
 /**
  * Run multiple actions concurrently. The first to complete wins; losers
- * are cancelled during Handle frame teardown.
+ * are cancelled during `RestartHandle` frame teardown.
  *
  * All branches must have the same input and output type (since either
  * could win).
  *
- * Compiles to:
- *   Handle(effectId, Chain(ExtractField("payload"), Tag("Discard")),
- *     All(
- *       Chain(action1, Perform(effectId)),
- *       Chain(action2, Perform(effectId)),
- *       ...
- *     ),
- *   )
+ * Compiled form (restart+Branch, same substrate as loop/earlyReturn):
+ *   `Chain(Tag("Continue"),`
+ *     `RestartHandle(id, ExtractIndex(0),`
+ *       `Branch({`
+ *         `Continue: All(Chain(a, breakPerform), Chain(b, breakPerform), ...),`
+ *         `Break: identity,`
+ *       `})))`
+ *
+ * First branch to complete tags Break → `RestartPerform` → handler restarts →
+ * Branch takes Break arm → identity → `RestartHandle` exits with winner's value.
  */
 export function race<TIn, TOut>(
   ...actions: Pipeable<TIn, TOut>[]
 ): TypedAction<TIn, TOut> {
-  const effectId = allocateEffectId();
-
-  const perform: Action = { kind: "Perform", effect_id: effectId };
+  const restartHandlerId = allocateRestartHandlerId();
+  const perform = breakPerform(restartHandlerId);
 
   const branches = actions.map((action) => ({
     kind: "Chain" as const,
@@ -65,12 +74,11 @@ export function race<TIn, TOut>(
     rest: perform,
   }));
 
-  return typedAction({
-    kind: "Handle",
-    effect_id: effectId,
-    handler: RACE_HANDLER,
-    body: { kind: "All", actions: branches },
-  });
+  const allAction: Action = { kind: "All", actions: branches };
+
+  return typedAction(
+    buildRestartBranchAction(restartHandlerId, allAction, IDENTITY),
+  );
 }
 
 // ---------------------------------------------------------------------------
@@ -129,28 +137,28 @@ Object.defineProperty(sleep, "__definition", {
  * that computes a duration from the pipeline input.
  *
  * Built as raw AST rather than through `race()` because each branch wraps
- * its result differently (Ok vs Err) before Perform. `race()` requires
- * homogeneous output types, but withTimeout needs heterogeneous tagging.
+ * its result differently (Ok vs Err) before the Break+Perform. `race()`
+ * requires homogeneous output types, but withTimeout needs heterogeneous
+ * tagging.
  *
- * Compiles to the same Handle/All/Perform structure as race, with each
- * branch wrapping its result as Ok or Err before Perform.
+ * Same restart+Branch substrate as race: each branch tags Break after
+ * wrapping its result as Ok or Err.
  */
 export function withTimeout<TIn, TOut>(
   ms: Pipeable<TIn, number>,
   body: Pipeable<TIn, TOut>,
 ): TypedAction<TIn, Result<TOut, void>> {
-  const effectId = allocateEffectId();
-
-  const perform: Action = { kind: "Perform", effect_id: effectId };
+  const restartHandlerId = allocateRestartHandlerId();
+  const perform = breakPerform(restartHandlerId);
 
-  // Branch 1: body → Tag("Ok") → Perform
+  // Branch 1: body → Tag("Ok") → Tag("Break") → RestartPerform
   const bodyBranch: Action = {
     kind: "Chain",
     first: { kind: "Chain", first: body as Action, rest: TAG_OK },
     rest: perform,
   };
 
-  // Branch 2: ms → sleep() → Tag("Err") → Perform
+  // Branch 2: ms → sleep() → Tag("Err") → Tag("Break") → RestartPerform
   const sleepBranch: Action = {
     kind: "Chain",
     first: {
@@ -161,11 +169,9 @@ export function withTimeout<TIn, TOut>(
     rest: perform,
   };
 
-  return typedAction({
-    kind: "Handle",
-    effect_id: effectId,
-    handler: RACE_HANDLER,
-    body: { kind: "All", actions: [bodyBranch, sleepBranch] },
-  });
-}
+  const allAction: Action = { kind: "All", actions: [bodyBranch, sleepBranch] };
 
+  return typedAction(
+    buildRestartBranchAction(restartHandlerId, allAction, IDENTITY),
+  );
+}