@barnum/barnum 0.0.0-main-e8b82cff → 0.0.0-main-00082d0f

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barnum/barnum",
-  "version": "0.0.0-main-e8b82cff",
+  "version": "0.0.0-main-00082d0f",
   "description": "Barnum workflow engine",
   "type": "module",
   "main": "dist/index.js",

package/src/ast.ts

@@ -134,29 +134,23 @@ export type MergeTuple<TTuple> = TTuple extends unknown[]
  * An action with tracked input/output types. Phantom fields enforce invariance
  * and are never set at runtime — they exist only for the TypeScript compiler.
  *
- * Invariance is enforced through paired covariant/contravariant phantom fields:
- *
- *   In:  __phantom_in (contravariant) + __in (covariant) → invariant
- *   Out: __phantom_out (covariant) + __phantom_out_check (contravariant) → invariant
+ * Each type variable gets a contravariant + covariant field pair:
+ *   In:  __in (contravariant) + __in_co (covariant) → invariant
+ *   Out: __out (covariant) + __out_contra (contravariant) → invariant
  *
  * This ensures exact type matching at every pipeline connection point.
  * Data crosses serialization boundaries to handlers in arbitrary languages
  * (Rust, Python, etc.), so extra/missing fields are runtime errors.
- *
- * __in also enables config() to reject workflows that expect input
- * (the contravariant __phantom_in makes never the most permissive input,
- * so the covariant __in is needed for the entry point check).
- *
  */
 export type TypedAction<
   In = unknown,
   Out = unknown,
   Refs extends string = never,
 > = Action & {
-  __phantom_in?: (input: In) => void;
-  __phantom_out?: () => Out;
-  __phantom_out_check?: (output: Out) => void;
-  __in?: In;
+  __in?: (input: In) => void;
+  __in_co?: In;
+  __out?: () => Out;
+  __out_contra?: (output: Out) => void;
   __refs?: { _brand: Refs };
   /** Chain this action with another. `a.then(b)` ≡ `chain(a, b)`. */
   then<TNext, TRefs2 extends string = never>(
@@ -260,8 +254,8 @@ export type TypedAction<
  * as TypedAction but without methods.
  *
  * Invariance: Both In and Out are invariant, matching TypedAction:
- *   In:  __phantom_in (contravariant) + __in (covariant) → invariant
- *   Out: __phantom_out (covariant) + __phantom_out_check (contravariant) → invariant
+ *   In:  __in (contravariant) + __in_co (covariant) → invariant
+ *   Out: __out (covariant) + __out_contra (contravariant) → invariant
  *
  * Why no methods: TypedAction's methods (then, branch, etc.) participate in
  * TS assignability checks in complex, recursive ways that interfere with
@@ -278,20 +272,20 @@ export type Pipeable<
   Out = unknown,
   Refs extends string = never,
 > = Action & {
-  __phantom_in?: (input: In) => void;
-  __phantom_out?: () => Out;
-  __phantom_out_check?: (output: Out) => void;
-  __in?: In;
+  __in?: (input: In) => void;
+  __in_co?: In;
+  __out?: () => Out;
+  __out_contra?: (output: Out) => void;
   __refs?: { _brand: Refs };
 };
 
 /**
  * Contravariant-only input checking for branch case handler positions.
  *
- * Omits __in (covariant input) and __phantom_out_check (contravariant output)
+ * Omits __in_co (covariant input) and __out_contra (contravariant output)
  * compared to TypedAction/Pipeable. This gives:
- *   In:  contravariant only (via __phantom_in)
- *   Out: covariant only (via __phantom_out)
+ *   In:  contravariant only (via __in)
+ *   Out: covariant only (via __out)
  *
  * Why contravariant input: a handler that accepts `unknown` (like drop)
  * can handle any variant. (input: unknown) => void is assignable to
@@ -299,7 +293,7 @@ export type Pipeable<
  *
  * Why covariant output: the constraint doesn't restrict output types —
  * they're inferred from the actual case handlers via ExtractOutput.
- * TypedAction's invariant __phantom_out_check with Out=unknown would
+ * TypedAction's invariant __out_contra with Out=unknown would
  * reject any handler with a specific output type, so we omit it.
  *
  * TypedAction is assignable to CaseHandler because CaseHandler only
@@ -310,8 +304,8 @@ type CaseHandler<
   TOut = unknown,
   TRefs extends string = never,
 > = Action & {
-  __phantom_in?: (input: TIn) => void;
-  __phantom_out?: () => TOut;
+  __in?: (input: TIn) => void;
+  __out?: () => TOut;
   __refs?: { _brand: TRefs };
 };
 
@@ -629,10 +623,10 @@ export function typedAction<
  *
  * Uses direct phantom field extraction (not full TypedAction matching) to
  * avoid the `TypedAction<any, any, any>` constraint which fails for In=never
- * due to __phantom_in contravariance.
+ * due to __in contravariance.
  */
 export type ExtractInput<T> = T extends {
-  __phantom_in?: (input: infer In) => void;
+  __in?: (input: infer In) => void;
 }
   ? In
   : never;
@@ -642,7 +636,7 @@ export type ExtractInput<T> = T extends {
  *
  * Uses direct phantom field extraction to avoid constraint issues.
  */
-export type ExtractOutput<T> = T extends { __phantom_out?: () => infer Out }
+export type ExtractOutput<T> = T extends { __out?: () => infer Out }
   ? Out
   : never;
 
@@ -654,6 +648,7 @@ export { pipe } from "./pipe.js";
 export { chain } from "./chain.js";
 export { all } from "./all.js";
 export { bind, bindInput, type VarRef, type InferVarRefs } from "./bind.js";
+export { defineRecursiveFunctions } from "./recursive.js";
 export { resetEffectIdCounter } from "./effect-id.js";
 import {
   allocateRestartHandlerId,

package/src/bind.ts

@@ -41,7 +41,7 @@ function createVarRef<TValue>(
  *
  * Constraint is `Action[]` (not `Pipeable<any, any>[]`) because
  * `TypedAction<never, X>` (e.g. from `constant()`) fails the invariant
- * `__phantom_in` check against `Pipeable<any, any>` on the 9-variant
+ * `__in` check against `Pipeable<any, any>` on the 9-variant
  * Action union. Using raw `Action[]` avoids the phantom field
  * assignability issue while `ExtractOutput` still extracts the correct
  * output type from the phantom fields on the concrete types.
@@ -118,17 +118,12 @@ function readVar(n: number): Action {
  */
 /**
  * Constraint for the body callback return type. Only requires the output
- * phantom fields — omits `__phantom_in` and `__in` so that body actions
- * with `In = never` (e.g. pipelines starting from a VarRef) are assignable.
- *
- * This is necessary because `TypedAction<never, X>` is not assignable to
- * `Pipeable<any, X>`: the contravariant `__phantom_in` field check fails
- * since `(input: never) => void` is not assignable to `(input: any) => void`
- * when distributed across the 9-variant Action union.
+ * phantom fields — omits `__in` and `__in_co` so that body actions with
+ * `In = never` (e.g. pipelines starting from a VarRef) are assignable.
  */
 type BodyResult<TOut> = Action & {
-  __phantom_out?: () => TOut;
-  __phantom_out_check?: (output: TOut) => void;
+  __out?: () => TOut;
+  __out_contra?: (output: TOut) => void;
 };
 
 export function bind<TBindings extends Action[], TOut>(

package/src/builtins.ts

@@ -686,8 +686,8 @@ export const Result = {
    */
   unwrapOr<TValue, TError>(
     defaultAction: Action & {
-      __phantom_in?: (input: TError) => void;
-      __phantom_out?: () => TValue;
+      __in?: (input: TError) => void;
+      __out?: () => TValue;
     },
   ): TypedAction<ResultT<TValue, TError>, TValue> {
     return typedAction(resultBranch(IDENTITY, defaultAction as Action));

package/src/handler.ts

@@ -1,4 +1,5 @@
 import { fileURLToPath } from "node:url";
+import type { JSONSchema7 } from "json-schema";
 import type { z } from "zod";
 import { type TypedAction, typedAction } from "./ast.js";
 import { zodToCheckedJsonSchema } from "./schema.js";
@@ -182,12 +183,28 @@ export function createHandlerWithConfig(
   const filePath = getCallerFilePath();
   const funcName = exportName ?? "default";
 
-  const inputSchema = definition.inputValidator
+  // The invoke receives [value, config] from All(Identity, Constant(config)).
+  // Build a tuple schema manually — the Rust engine doesn't support draft-07
+  // array-form `items` for tuples, so use `prefixItems` (2020-12 style).
+  const valueSchema = definition.inputValidator
     ? zodToCheckedJsonSchema(
         definition.inputValidator,
         `${filePath}:${funcName} input`,
       )
-    : undefined;
+    : {};
+  const configSchema = definition.stepConfigValidator
+    ? zodToCheckedJsonSchema(
+        definition.stepConfigValidator,
+        `${filePath}:${funcName} stepConfig`,
+      )
+    : {};
+  const inputSchema: JSONSchema7 = {
+    type: "array",
+    prefixItems: [valueSchema, configSchema],
+    items: false,
+    minItems: 2,
+    maxItems: 2,
+  } as JSONSchema7;
   const outputSchema = definition.outputValidator
     ? zodToCheckedJsonSchema(
         definition.outputValidator,
@@ -209,7 +226,7 @@ export function createHandlerWithConfig(
       kind: "TypeScript",
       module: filePath,
       func: funcName,
-      ...(inputSchema && { input_schema: inputSchema }),
+      input_schema: inputSchema,
       ...(outputSchema && { output_schema: outputSchema }),
     },
   });

package/src/recursive.ts

@@ -0,0 +1,112 @@
+import {
+  type Action,
+  type Pipeable,
+  type TypedAction,
+  typedAction,
+  branch,
+} from "./ast.js";
+import { all } from "./all.js";
+import { chain } from "./chain.js";
+import {
+  constant,
+  identity,
+  extractField,
+  extractIndex,
+  tag,
+} from "./builtins.js";
+import { allocateResumeHandlerId } from "./effect-id.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+type FunctionDef = [input: unknown, output: unknown];
+
+type FunctionRefs<TDefs extends FunctionDef[]> = {
+  [K in keyof TDefs]: TypedAction<TDefs[K][0], TDefs[K][1]>;
+};
+
+/**
+ * Constraint for the entry-point callback return type. Only requires the
+ * output phantom fields — omits __in and __in_co so that actions with
+ * In = never (e.g. pipelines starting from a call token) are assignable.
+ */
+type BodyResult<TOut> = Action & {
+  __out?: () => TOut;
+  __out_contra?: (output: TOut) => void;
+};
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const UNUSED_STATE: any = undefined;
+
+// ---------------------------------------------------------------------------
+// defineRecursiveFunctions
+// ---------------------------------------------------------------------------
+
+/**
+ * Define mutually recursive functions that can call each other.
+ *
+ * The type parameter is an array of [In, Out] tuples — one per function.
+ * TypeScript can't infer these from circular definitions, so they must be
+ * explicit.
+ *
+ * Returns a curried combinator: the first callback defines function bodies,
+ * the second receives the same call tokens and returns the workflow entry
+ * point.
+ *
+ * Desugars to a ResumeHandle with a Branch-based handler. Each call token
+ * is Chain(Tag("CallN"), ResumePerform(id)). The handler dispatches to the
+ * correct function body by tag. The caller's pipeline is preserved as a
+ * ResumePerformFrame across each call.
+ */
+export function defineRecursiveFunctions<TDefs extends FunctionDef[]>(
+  bodiesFn: (...fns: FunctionRefs<TDefs>) => {
+    [K in keyof TDefs]: Pipeable<TDefs[K][0], TDefs[K][1]>;
+  },
+): <TOut>(
+  entryFn: (...fns: FunctionRefs<TDefs>) => BodyResult<TOut>,
+) => TypedAction<any, TOut> {
+  const resumeHandlerId = allocateResumeHandlerId();
+
+  const resumePerform: Action = {
+    kind: "ResumePerform",
+    resume_handler_id: resumeHandlerId,
+  };
+
+  // Call tokens: Chain(Tag("CallN"), ResumePerform(resumeHandlerId))
+  const fnCount = bodiesFn.length;
+  const callTokens = Array.from({ length: fnCount }, (_, i) =>
+    typedAction(chain(tag(`Call${i}`), resumePerform as any) as Action),
+  );
+
+  // Get function body ASTs
+  const bodyActions = bodiesFn(
+    ...(callTokens as FunctionRefs<TDefs>),
+  ) as Action[];
+
+  // Branch cases: CallN → ExtractField("value") → bodyN
+  const cases: Record<string, Action> = {};
+  for (let i = 0; i < bodyActions.length; i++) {
+    cases[`Call${i}`] = chain(
+      extractField("value"),
+      bodyActions[i] as any,
+    ) as Action;
+  }
+
+  // Return curried entry-point combinator
+  return <TOut>(entryFn: (...fns: FunctionRefs<TDefs>) => BodyResult<TOut>) => {
+    const userBody = entryFn(...(callTokens as FunctionRefs<TDefs>)) as Action;
+
+    return typedAction<any, TOut>(
+      chain(all(identity, constant(UNUSED_STATE)), {
+        kind: "ResumeHandle",
+        resume_handler_id: resumeHandlerId,
+        body: chain(extractIndex(0), userBody as any) as Action,
+        handler: all(
+          chain(extractIndex(0), branch(cases) as any),
+          constant(UNUSED_STATE),
+        ) as Action,
+      } as Action) as Action,
+    );
+  };
+}