@barnum/barnum 0.2.2 → 0.3.0

package/dist/handler.js

@@ -0,0 +1,146 @@
+import { fileURLToPath } from "node:url";
+import { typedAction } from "./ast.js";
+import { zodToCheckedJsonSchema } from "./schema.js";
+// ---------------------------------------------------------------------------
+// Handler — opaque typed handler reference
+// ---------------------------------------------------------------------------
+const HANDLER_BRAND = Symbol.for("barnum:handler");
+// ---------------------------------------------------------------------------
+// getCallerFilePath
+// ---------------------------------------------------------------------------
+/**
+ * Deduces the caller's file path from the V8 stack trace API.
+ * Frame 0 = getCallerFilePath, Frame 1 = createHandler, Frame 2 = the caller.
+ */
+function getCallerFilePath() {
+    const original = Error.prepareStackTrace;
+    let callerFile;
+    Error.prepareStackTrace = (_err, stack) => {
+        const frame = stack[2];
+        callerFile = frame?.getFileName() ?? undefined;
+        return "";
+    };
+    const err = new Error("stack trace capture");
+    void err.stack;
+    Error.prepareStackTrace = original;
+    if (!callerFile) {
+        throw new Error("createHandler: could not determine caller file path from stack trace.");
+    }
+    if (callerFile.startsWith("file://")) {
+        return fileURLToPath(callerFile);
+    }
+    return callerFile;
+}
+// Implementation
+export function createHandler(definition, exportName) {
+    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,
+            ...(inputSchema && { input_schema: inputSchema }),
+            ...(outputSchema && { output_schema: outputSchema }),
+        },
+    });
+    // Non-enumerable: invisible to JSON.stringify, visible to the worker
+    Object.defineProperty(action, HANDLER_BRAND, {
+        value: true,
+        enumerable: false,
+    });
+    Object.defineProperty(action, "__definition", {
+        value: definition,
+        enumerable: false,
+    });
+    return action;
+}
+// Implementation
+export function createHandlerWithConfig(definition, exportName) {
+    const filePath = getCallerFilePath();
+    const funcName = exportName ?? "default";
+    // 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`)
+        : {};
+    const configSchema = definition.stepConfigValidator
+        ? zodToCheckedJsonSchema(definition.stepConfigValidator, `${filePath}:${funcName} stepConfig`)
+        : {};
+    const inputSchema = {
+        type: "array",
+        prefixItems: [valueSchema, configSchema],
+        items: false,
+        minItems: 2,
+        maxItems: 2,
+    };
+    const outputSchema = definition.outputValidator
+        ? zodToCheckedJsonSchema(definition.outputValidator, `${filePath}:${funcName} output`)
+        : undefined;
+    // Internal handle that unpacks the [value, config] tuple from All
+    const internalDefinition = {
+        handle: ({ value }) => {
+            const [pipelineValue, config] = value;
+            return definition.handle({ value: pipelineValue, stepConfig: config });
+        },
+    };
+    const invokeAction = typedAction({
+        kind: "Invoke",
+        handler: {
+            kind: "TypeScript",
+            module: filePath,
+            func: funcName,
+            input_schema: inputSchema,
+            ...(outputSchema && { output_schema: outputSchema }),
+        },
+    });
+    // Non-enumerable: invisible to JSON.stringify, visible to the worker
+    Object.defineProperty(invokeAction, HANDLER_BRAND, {
+        value: true,
+        enumerable: false,
+    });
+    Object.defineProperty(invokeAction, "__definition", {
+        value: internalDefinition,
+        enumerable: false,
+    });
+    // The factory function is the module export, so it must also carry
+    // __definition for the worker to find (the worker imports the module
+    // and accesses the named export, which is this function).
+    const factory = (config) => typedAction({
+        kind: "Chain",
+        first: {
+            kind: "All",
+            actions: [
+                {
+                    kind: "Invoke",
+                    handler: { kind: "Builtin", builtin: { kind: "Identity" } },
+                },
+                {
+                    kind: "Invoke",
+                    handler: {
+                        kind: "Builtin",
+                        builtin: { kind: "Constant", value: config },
+                    },
+                },
+            ],
+        },
+        rest: invokeAction,
+    });
+    Object.defineProperty(factory, HANDLER_BRAND, {
+        value: true,
+        enumerable: false,
+    });
+    Object.defineProperty(factory, "__definition", {
+        value: internalDefinition,
+        enumerable: false,
+    });
+    return factory;
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+import type { TaggedUnion, OptionDef, ResultDef } from "./ast.js";
+export * from "./ast.js";
+export { constant, identity, drop, tag, merge, flatten, extractField, extractIndex, pick, dropResult, withResource, augment, tap, range, Option, Result, } from "./builtins.js";
+export * from "./handler.js";
+export { runPipeline } from "./run.js";
+export { zodToCheckedJsonSchema } from "./schema.js";
+export type Option<T> = TaggedUnion<OptionDef<T>>;
+export type Result<TValue, TError> = TaggedUnion<ResultDef<TValue, TError>>;

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from "./ast.js";
+export { constant, identity, drop, tag, merge, flatten, extractField, extractIndex, pick, dropResult, withResource, augment, tap, range, Option, Result, } from "./builtins.js";
+export * from "./handler.js";
+export { runPipeline } from "./run.js";
+export { zodToCheckedJsonSchema } from "./schema.js";

package/dist/pipe.d.ts

@@ -0,0 +1,11 @@
+import { type PipeIn, type Pipeable, type TypedAction } from "./ast.js";
+export declare function pipe<T1, T2>(a1: Pipeable<T1, T2>): TypedAction<PipeIn<T1>, T2>;
+export declare function pipe<T1, T2, T3>(a1: Pipeable<T1, T2>, a2: Pipeable<T2, T3>): TypedAction<PipeIn<T1>, T3>;
+export declare function pipe<T1, T2, T3, T4>(a1: Pipeable<T1, T2>, a2: Pipeable<T2, T3>, a3: Pipeable<T3, T4>): TypedAction<PipeIn<T1>, T4>;
+export declare function pipe<T1, T2, T3, T4, T5>(a1: Pipeable<T1, T2>, a2: Pipeable<T2, T3>, a3: Pipeable<T3, T4>, a4: Pipeable<T4, T5>): TypedAction<PipeIn<T1>, T5>;
+export declare function pipe<T1, T2, T3, T4, T5, T6>(a1: Pipeable<T1, T2>, a2: Pipeable<T2, T3>, a3: Pipeable<T3, T4>, a4: Pipeable<T4, T5>, a5: Pipeable<T5, T6>): TypedAction<PipeIn<T1>, T6>;
+export declare function pipe<T1, T2, T3, T4, T5, T6, T7>(a1: Pipeable<T1, T2>, a2: Pipeable<T2, T3>, a3: Pipeable<T3, T4>, a4: Pipeable<T4, T5>, a5: Pipeable<T5, T6>, a6: Pipeable<T6, T7>): TypedAction<PipeIn<T1>, T7>;
+export declare function pipe<T1, T2, T3, T4, T5, T6, T7, T8>(a1: Pipeable<T1, T2>, a2: Pipeable<T2, T3>, a3: Pipeable<T3, T4>, a4: Pipeable<T4, T5>, a5: Pipeable<T5, T6>, a6: Pipeable<T6, T7>, a7: Pipeable<T7, T8>): TypedAction<PipeIn<T1>, T8>;
+export declare function pipe<T1, T2, T3, T4, T5, T6, T7, T8, T9>(a1: Pipeable<T1, T2>, a2: Pipeable<T2, T3>, a3: Pipeable<T3, T4>, a4: Pipeable<T4, T5>, a5: Pipeable<T5, T6>, a6: Pipeable<T6, T7>, a7: Pipeable<T7, T8>, a8: Pipeable<T8, T9>): TypedAction<PipeIn<T1>, T9>;
+export declare function pipe<T1, T2, T3, T4, T5, T6, T7, T8, T9, T10>(a1: Pipeable<T1, T2>, a2: Pipeable<T2, T3>, a3: Pipeable<T3, T4>, a4: Pipeable<T4, T5>, a5: Pipeable<T5, T6>, a6: Pipeable<T6, T7>, a7: Pipeable<T7, T8>, a8: Pipeable<T8, T9>, a9: Pipeable<T9, T10>): TypedAction<PipeIn<T1>, T10>;
+export declare function pipe<T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11>(a1: Pipeable<T1, T2>, a2: Pipeable<T2, T3>, a3: Pipeable<T3, T4>, a4: Pipeable<T4, T5>, a5: Pipeable<T5, T6>, a6: Pipeable<T6, T7>, a7: Pipeable<T7, T8>, a8: Pipeable<T8, T9>, a9: Pipeable<T9, T10>, a10: Pipeable<T10, T11>): TypedAction<PipeIn<T1>, T11>;

package/dist/pipe.js

@@ -0,0 +1,11 @@
+import { typedAction, } from "./ast.js";
+import { identity } from "./builtins.js";
+export function pipe(...actions) {
+    if (actions.length === 0) {
+        return identity;
+    }
+    if (actions.length === 1) {
+        return actions[0];
+    }
+    return actions.reduceRight((rest, first) => typedAction({ kind: "Chain", first, rest }));
+}

package/dist/race.d.ts

@@ -0,0 +1,53 @@
+import { type Pipeable, type Result, type TypedAction } from "./ast.js";
+/**
+ * Run multiple actions concurrently. The first to complete wins; losers
+ * are cancelled during `RestartHandle` frame teardown.
+ *
+ * All branches must have the same input and output type (since either
+ * could win).
+ *
+ * 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 declare function race<TIn, TOut>(...actions: Pipeable<TIn, TOut>[]): TypedAction<TIn, TOut>;
+/**
+ * Sleep for a fixed duration, ignoring input and returning void.
+ *
+ * `ms` is baked into the AST at construction time. Executed by the Rust
+ * scheduler via `tokio::time::sleep` — no subprocess spawned.
+ *
+ * To preserve data across a sleep, use `bindInput`.
+ */
+export declare function sleep(ms: number): TypedAction<any, never>;
+/**
+ * @internal TypeScript handler that takes ms as pipeline input and returns
+ * void after the timer fires. Used by `withTimeout` where the duration
+ * comes from a runtime pipeline, not a build-time constant.
+ */
+export declare function dynamicSleep(): void;
+/**
+ * Race the body against a sleep timer. Returns `Result<TOut, void>`:
+ * - Ok(value) if the body completed first
+ * - Err(void) if the timeout fired first
+ *
+ * The `ms` parameter is an AST node that evaluates to the timeout duration
+ * in milliseconds. Use `constant(5000)` for a fixed timeout, or any action
+ * 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 the Break+Perform. `race()`
+ * requires homogeneous output types, but withTimeout needs heterogeneous
+ * tagging.
+ *
+ * Same restart+Branch substrate as race: each branch tags Break after
+ * wrapping its result as Ok or Err.
+ */
+export declare function withTimeout<TIn, TOut>(ms: Pipeable<TIn, number>, body: Pipeable<TIn, TOut>): TypedAction<TIn, Result<TOut, void>>;

package/dist/race.js

@@ -0,0 +1,141 @@
+import { typedAction, buildRestartBranchAction, TAG_BREAK, IDENTITY, } from "./ast.js";
+import { allocateRestartHandlerId, } from "./effect-id.js";
+// ---------------------------------------------------------------------------
+// Shared AST fragments
+// ---------------------------------------------------------------------------
+const TAG_OK = {
+    kind: "Invoke",
+    handler: { kind: "Builtin", builtin: { kind: "Tag", value: "Ok" } },
+};
+const TAG_ERR = {
+    kind: "Invoke",
+    handler: { kind: "Builtin", builtin: { kind: "Tag", value: "Err" } },
+};
+/**
+ * `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) {
+    return {
+        kind: "Chain",
+        first: TAG_BREAK,
+        rest: { kind: "RestartPerform", restart_handler_id: restartHandlerId },
+    };
+}
+// ---------------------------------------------------------------------------
+// race — first branch to complete wins, losers cancelled
+// ---------------------------------------------------------------------------
+/**
+ * Run multiple actions concurrently. The first to complete wins; losers
+ * are cancelled during `RestartHandle` frame teardown.
+ *
+ * All branches must have the same input and output type (since either
+ * could win).
+ *
+ * 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(...actions) {
+    const restartHandlerId = allocateRestartHandlerId();
+    const perform = breakPerform(restartHandlerId);
+    const branches = actions.map((action) => ({
+        kind: "Chain",
+        first: action,
+        rest: perform,
+    }));
+    const allAction = { kind: "All", actions: branches };
+    return typedAction(buildRestartBranchAction(restartHandlerId, allAction, IDENTITY));
+}
+// ---------------------------------------------------------------------------
+// sleep — Rust builtin that delays for a fixed duration (passthrough)
+// ---------------------------------------------------------------------------
+/**
+ * Sleep for a fixed duration, ignoring input and returning void.
+ *
+ * `ms` is baked into the AST at construction time. Executed by the Rust
+ * scheduler via `tokio::time::sleep` — no subprocess spawned.
+ *
+ * To preserve data across a sleep, use `bindInput`.
+ */
+export function sleep(ms) {
+    return typedAction({
+        kind: "Invoke",
+        handler: { kind: "Builtin", builtin: { kind: "Sleep", value: ms } },
+    });
+}
+// ---------------------------------------------------------------------------
+// dynamicSleep — TypeScript handler for withTimeout (takes ms as input)
+// ---------------------------------------------------------------------------
+/** The raw Invoke node for the dynamic sleep handler. */
+const DYNAMIC_SLEEP_INVOKE = {
+    kind: "Invoke",
+    handler: {
+        kind: "TypeScript",
+        module: import.meta.url,
+        func: "dynamicSleep",
+    },
+};
+/**
+ * @internal TypeScript handler that takes ms as pipeline input and returns
+ * void after the timer fires. Used by `withTimeout` where the duration
+ * comes from a runtime pipeline, not a build-time constant.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-function
+export function dynamicSleep() { }
+Object.defineProperty(dynamicSleep, "__definition", {
+    value: {
+        handle: ({ value }) => new Promise((resolve) => setTimeout(resolve, value)),
+    },
+    enumerable: false,
+});
+// ---------------------------------------------------------------------------
+// withTimeout — race body against sleep, return Result
+// ---------------------------------------------------------------------------
+/**
+ * Race the body against a sleep timer. Returns `Result<TOut, void>`:
+ * - Ok(value) if the body completed first
+ * - Err(void) if the timeout fired first
+ *
+ * The `ms` parameter is an AST node that evaluates to the timeout duration
+ * in milliseconds. Use `constant(5000)` for a fixed timeout, or any action
+ * 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 the Break+Perform. `race()`
+ * requires homogeneous output types, but withTimeout needs heterogeneous
+ * tagging.
+ *
+ * Same restart+Branch substrate as race: each branch tags Break after
+ * wrapping its result as Ok or Err.
+ */
+export function withTimeout(ms, body) {
+    const restartHandlerId = allocateRestartHandlerId();
+    const perform = breakPerform(restartHandlerId);
+    // Branch 1: body → Tag("Ok") → Tag("Break") → RestartPerform
+    const bodyBranch = {
+        kind: "Chain",
+        first: { kind: "Chain", first: body, rest: TAG_OK },
+        rest: perform,
+    };
+    // Branch 2: ms → sleep() → Tag("Err") → Tag("Break") → RestartPerform
+    const sleepBranch = {
+        kind: "Chain",
+        first: {
+            kind: "Chain",
+            first: { kind: "Chain", first: ms, rest: DYNAMIC_SLEEP_INVOKE },
+            rest: TAG_ERR,
+        },
+        rest: perform,
+    };
+    const allAction = { kind: "All", actions: [bodyBranch, sleepBranch] };
+    return typedAction(buildRestartBranchAction(restartHandlerId, allAction, IDENTITY));
+}

package/dist/recursive.d.ts

@@ -0,0 +1,34 @@
+import { type Action, type Pipeable, type TypedAction } from "./ast.js";
+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;
+};
+/**
+ * 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 declare 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>;
+export {};

package/dist/recursive.js

@@ -0,0 +1,53 @@
+import { 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";
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const UNUSED_STATE = 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(bodiesFn) {
+    const resumeHandlerId = allocateResumeHandlerId();
+    const resumePerform = {
+        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)));
+    // Get function body ASTs
+    const bodyActions = bodiesFn(...callTokens);
+    // Branch cases: CallN → ExtractField("value") → bodyN
+    const cases = {};
+    for (let i = 0; i < bodyActions.length; i++) {
+        cases[`Call${i}`] = chain(extractField("value"), bodyActions[i]);
+    }
+    // Return curried entry-point combinator
+    return (entryFn) => {
+        const userBody = entryFn(...callTokens);
+        return typedAction(chain(all(identity, constant(UNUSED_STATE)), {
+            kind: "ResumeHandle",
+            resume_handler_id: resumeHandlerId,
+            body: chain(extractIndex(0), userBody),
+            handler: all(chain(extractIndex(0), branch(cases)), constant(UNUSED_STATE)),
+        }));
+    };
+}

package/dist/run.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Workflow execution: resolves the barnum binary, tsx executor, and worker
+ * script, then spawns the workflow as a subprocess.
+ */
+import type { Action, ExtractOutput } from "./ast.js";
+/** Run a pipeline to completion. Returns the workflow's final output value. */
+export declare function runPipeline<TPipeline extends Action>(pipeline: TPipeline, input?: unknown): Promise<ExtractOutput<TPipeline>>;

package/dist/run.js

@@ -0,0 +1,143 @@
+/**
+ * Workflow execution: resolves the barnum binary, tsx executor, and worker
+ * script, then spawns the workflow as a subprocess.
+ */
+import { execFileSync, spawn as nodeSpawn } from "node:child_process";
+import { createRequire } from "node:module";
+import { existsSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { chain } from "./chain.js";
+import { constant } from "./builtins.js";
+const __dirname = import.meta.dirname;
+/** Resolve the TypeScript executor. Uses bun if the workflow was launched with bun, otherwise tsx. */
+function resolveExecutor() {
+    if (process.versions.bun) {
+        return "bun";
+    }
+    const callerRequire = createRequire(process.argv[1] || import.meta.url);
+    const tsxPath = callerRequire.resolve("tsx/cli");
+    return `node ${tsxPath}`;
+}
+/** Resolve the platform-specific binary from the @barnum/barnum package artifacts. */
+function resolveInstalledBinary() {
+    const platform = os.platform();
+    const arch = os.arch();
+    let artifactDir;
+    let binaryName = "barnum";
+    if (platform === "darwin" && arch === "arm64") {
+        artifactDir = "macos-arm64";
+    }
+    else if (platform === "darwin") {
+        artifactDir = "macos-x64";
+    }
+    else if (platform === "linux" && arch === "arm64") {
+        artifactDir = "linux-arm64";
+    }
+    else if (platform === "linux") {
+        artifactDir = "linux-x64";
+    }
+    else if (platform === "win32") {
+        artifactDir = "win-x64";
+        binaryName = "barnum.exe";
+    }
+    else {
+        return undefined;
+    }
+    const callerRequire = createRequire(process.argv[1] || import.meta.url);
+    try {
+        const packageDir = path.dirname(callerRequire.resolve("@barnum/barnum/package.json"));
+        const binaryPath = path.join(packageDir, "artifacts", artifactDir, binaryName);
+        if (existsSync(binaryPath)) {
+            return binaryPath;
+        }
+    }
+    catch {
+        // Package not installed
+    }
+    return undefined;
+}
+/** Resolve the barnum binary. Checks: BARNUM env var, local repo, node_modules. */
+function resolveBinary() {
+    if (process.env.BARNUM) {
+        return { kind: "Env", path: process.env.BARNUM };
+    }
+    const repoRoot = path.resolve(__dirname, "../../..");
+    if (existsSync(path.join(repoRoot, "Cargo.toml"))) {
+        return {
+            kind: "Local",
+            path: path.join(repoRoot, "target/debug/barnum"),
+        };
+    }
+    const installedBinaryPath = resolveInstalledBinary();
+    if (installedBinaryPath) {
+        return { kind: "NodeModules", path: installedBinaryPath };
+    }
+    throw new Error("Could not find barnum binary. Set BARNUM env var or install @barnum/barnum.");
+}
+/** Resolve worker.ts relative to this package. */
+function resolveWorker() {
+    return path.resolve(__dirname, "../src/worker.ts");
+}
+/** Build the barnum binary if using the local dev path. */
+function buildBinary() {
+    const repoRoot = path.resolve(__dirname, "../../..");
+    execFileSync("cargo", ["build", "-p", "barnum_cli"], {
+        cwd: repoRoot,
+        stdio: "ignore",
+    });
+}
+/** Run a pipeline to completion. Returns the workflow's final output value. */
+export function runPipeline(pipeline, input) {
+    const workflow = input === undefined
+        ? pipeline
+        : chain(constant(input), pipeline);
+    return spawnBarnum({ workflow });
+}
+/** Spawn the barnum CLI with the given config. Returns the parsed final value from stdout. */
+function spawnBarnum(config) {
+    const binaryResolution = resolveBinary();
+    if (binaryResolution.kind === "Local") {
+        buildBinary();
+    }
+    const executor = resolveExecutor();
+    const worker = resolveWorker();
+    const configJson = JSON.stringify(config);
+    return new Promise((resolve, reject) => {
+        const child = nodeSpawn(binaryResolution.path, [
+            "run",
+            "--config",
+            configJson,
+            "--executor",
+            executor,
+            "--worker",
+            worker,
+        ], {
+            stdio: ["inherit", "pipe", "inherit"],
+        });
+        const stdoutChunks = [];
+        child.stdout?.on("data", (chunk) => {
+            stdoutChunks.push(chunk);
+        });
+        child.on("error", (error) => {
+            reject(new Error(`Failed to spawn barnum: ${error.message}`));
+        });
+        child.on("close", (code) => {
+            if (code !== 0) {
+                reject(new Error(`barnum exited with code ${code}`));
+                return;
+            }
+            const stdout = Buffer.concat(stdoutChunks).toString("utf8").trim();
+            if (!stdout) {
+                resolve(undefined);
+                return;
+            }
+            try {
+                resolve(JSON.parse(stdout));
+            }
+            catch {
+                reject(new Error(`barnum produced non-JSON output on stdout: ${stdout}`));
+            }
+        });
+    });
+}

package/dist/schema.d.ts

@@ -0,0 +1,8 @@
+import type { JSONSchema7 } from "json-schema";
+import { type z } from "zod";
+/**
+ * Convert a Zod schema to a JSON Schema document suitable for embedding
+ * in the serialized AST. Throws if the schema contains types that can't
+ * survive the TS → JSON → Rust boundary.
+ */
+export declare function zodToCheckedJsonSchema(schema: z.ZodType, label: string): JSONSchema7;