@agentick/core 0.0.1

package/dist/core/procedure.js

@@ -0,0 +1,899 @@
+/**
+ * New Procedure Implementation - Variable Arity, Decorators, Pipelines
+ *
+ * Design Principles:
+ * - Everything is a Procedure
+ * - Variable arity support (0, 1, N args)
+ * - Decorator = Function (same type)
+ * - Hooks are Procedures (@hook decorator)
+ * - Pipelines for middleware bundles
+ * - Direct calls (no registration)
+ * - Automatic tracking (execution graph, telemetry)
+ */
+import { z } from "zod";
+import { EventEmitter } from "node:events";
+import { Context, isKernelContext } from "./context";
+import { ExecutionTracker } from "./execution-tracker";
+import { randomUUID } from "node:crypto";
+import { ProcedureNode } from "./procedure-graph";
+import { AbortError, ValidationError } from "@tentickle/shared";
+import { EventBuffer } from "./event-buffer";
+/**
+ * Create a ProcedurePromise from a regular Promise.
+ *
+ * Adds a `.result` property that chains through to the inner handle's result.
+ * If the resolved value has a `.result` property, `.result` resolves to that.
+ * Otherwise, `.result` resolves to the value itself.
+ *
+ * @param promise - The base promise to enhance
+ * @returns Enhanced ProcedurePromise with .result chaining
+ */
+export function createProcedurePromise(promise) {
+    const enhanced = promise;
+    Object.defineProperty(enhanced, "result", {
+        get() {
+            return promise.then((value) => {
+                // If the resolved value has a .result property, chain to it
+                if (value && typeof value === "object" && "result" in value) {
+                    return value.result;
+                }
+                // Otherwise, return the value itself
+                return value;
+            });
+        },
+        enumerable: true,
+        configurable: false,
+    });
+    return enhanced;
+}
+// ============================================================================
+// Symbol Branding
+// ============================================================================
+/**
+ * Symbol used to brand Procedure objects for deterministic type checking.
+ * Using Symbol.for() ensures the same symbol across module instances.
+ */
+export const PROCEDURE_SYMBOL = Symbol.for("@tentickle/kernel.procedure");
+/**
+ * Check if a value is a Procedure using Symbol branding.
+ *
+ * This is more reliable than duck typing because it uses a unique Symbol
+ * that can only be present on objects created by the procedure system.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a branded Procedure
+ *
+ * @example
+ * ```typescript
+ * const proc = createProcedure(async (x: number) => x * 2);
+ * isProcedure(proc); // true
+ * isProcedure(() => {}); // false
+ * isProcedure({ use: () => {} }); // false (duck typing would say true)
+ * ```
+ */
+export function isProcedure(value) {
+    return value != null && typeof value === "function" && PROCEDURE_SYMBOL in value;
+}
+/**
+ * Default implementation of ExecutionHandle.
+ *
+ * Creates a handle that wraps a result promise and event stream.
+ * Uses EventBuffer for dual consumption - multiple iterators can independently
+ * consume all events, and late subscribers receive replayed events.
+ *
+ * @typeParam TResult - The return type of the procedure
+ * @typeParam TEvent - The event type for streaming
+ */
+export class ExecutionHandleImpl {
+    result;
+    traceId;
+    _status = "running";
+    _abortController;
+    events;
+    constructor(result, events, traceId, abortController) {
+        this.result = result;
+        this.traceId = traceId;
+        this._abortController = abortController ?? new AbortController();
+        this.events = events;
+        // Update status when result settles
+        result.then(() => {
+            if (this._status === "running") {
+                this._status = "completed";
+                this.events.close();
+            }
+        }, (err) => {
+            if (this._status === "running") {
+                this._status = "error";
+                this.events.error(err instanceof Error ? err : new Error(String(err)));
+            }
+        });
+    }
+    /**
+     * @deprecated Use `events` instead. This getter exists for backwards compatibility.
+     */
+    get eventBuffer() {
+        return this.events;
+    }
+    get status() {
+        return this._status;
+    }
+    abort(reason) {
+        if (this._status === "running") {
+            this._status = "aborted";
+            this._abortController.abort(reason);
+            this.events.close();
+        }
+    }
+    /**
+     * Push an event to the buffer.
+     * This is the primary way to emit events from procedure handlers.
+     */
+    pushEvent(event) {
+        this.events.push(event);
+    }
+    // AsyncIterable implementation - delegates to EventBuffer for dual consumption
+    [Symbol.asyncIterator]() {
+        return this.events[Symbol.asyncIterator]();
+    }
+}
+/**
+ * Create a reusable middleware pipeline.
+ *
+ * Pipelines bundle multiple middleware together for reuse across procedures.
+ * They can be passed to `procedure.use()` just like individual middleware.
+ *
+ * @param middleware - Initial middleware to include in the pipeline
+ * @returns A new MiddlewarePipeline
+ *
+ * @example
+ * ```typescript
+ * // Create a pipeline with initial middleware
+ * const authPipeline = createPipeline([authMiddleware, rateLimitMiddleware]);
+ *
+ * // Or build it up with .use()
+ * const logPipeline = createPipeline()
+ *   .use(requestLogging)
+ *   .use(responseLogging);
+ *
+ * // Apply to procedures
+ * const proc = createProcedure(handler)
+ *   .use(authPipeline)
+ *   .use(logPipeline);
+ * ```
+ *
+ * @see {@link MiddlewarePipeline} - The pipeline interface
+ */
+export function createPipeline(middleware = []) {
+    const middlewares = [...middleware];
+    return {
+        use(...mw) {
+            middlewares.push(...mw);
+            return this;
+        },
+        getMiddleware() {
+            return middlewares;
+        },
+    };
+}
+// ============================================================================
+// Helper Functions
+// ============================================================================
+export function isAsyncIterable(obj) {
+    return obj && typeof obj[Symbol.asyncIterator] === "function";
+}
+function flattenMiddleware(middleware) {
+    const flattened = [];
+    for (const mw of middleware) {
+        if ("getMiddleware" in mw && typeof mw.getMiddleware === "function") {
+            flattened.push(...mw.getMiddleware());
+        }
+        else {
+            flattened.push(mw);
+        }
+    }
+    return flattened;
+}
+class ProcedureImpl {
+    internalMiddlewares = [];
+    middlewares = [];
+    schema;
+    procedureName;
+    sourceType = "procedure";
+    sourceId;
+    handleFactory;
+    metadata; // For telemetry span attributes
+    handler;
+    timeout; // Timeout in milliseconds
+    skipTracking; // Skip ExecutionTracker for transparent wrappers
+    executionBoundary; // Execution boundary config (Phase 3)
+    executionType; // Explicit execution type (Phase 3)
+    constructor(options = {}, handler) {
+        this.procedureName = options.name;
+        this.schema = options.schema;
+        this.sourceType = options.sourceType || "procedure";
+        this.sourceId = options.sourceId;
+        this.handleFactory = options.handleFactory;
+        this.metadata = options.metadata; // Store metadata for telemetry
+        this.timeout = options.timeout; // Store timeout
+        this.skipTracking = options.skipTracking; // Store skipTracking flag
+        this.executionBoundary = options.executionBoundary; // Execution boundary config (Phase 3)
+        this.executionType = options.executionType; // Explicit execution type (Phase 3)
+        if (options.middleware) {
+            this.middlewares = flattenMiddleware(options.middleware);
+        }
+        // Adapt Procedure middleware to internal middleware format
+        for (const mw of this.middlewares) {
+            const adaptedMw = async (args, ctx, nextFn) => {
+                const envelope = {
+                    sourceType: this.sourceType,
+                    sourceId: this.sourceId,
+                    operationName: this.procedureName || "anonymous",
+                    args,
+                    context: ctx,
+                };
+                return mw(args, envelope, async (transformedArgs) => {
+                    return nextFn(transformedArgs);
+                });
+            };
+            this.internalMiddlewares.push(adaptedMw);
+        }
+        // Set handler if provided
+        if (handler) {
+            this.handler = handler;
+        }
+    }
+    /**
+     * Set the handler function. Returns a new Procedure with the handler set.
+     */
+    setHandler(fn) {
+        return createProcedureFromImpl({
+            name: this.procedureName,
+            schema: this.schema,
+            middleware: this.middlewares,
+            handleFactory: this.handleFactory,
+            sourceType: this.sourceType,
+            sourceId: this.sourceId,
+            metadata: this.metadata, // Preserve metadata when setting new handler
+            // Preserve execution tracking options (Phase 3)
+            executionBoundary: this.executionBoundary,
+            executionType: this.executionType,
+            skipTracking: this.skipTracking,
+            timeout: this.timeout,
+        }, fn);
+    }
+    /**
+     * Internal execution method - runs middleware pipeline and handler.
+     */
+    async runMiddlewarePipeline(args, context) {
+        if (!this.handler) {
+            throw new Error("Procedure handler not set. Call constructor with handler or use .setHandler() method.");
+        }
+        // Get context middleware at execution time (from Tentickle instance)
+        // This enables runtime middleware configuration that can differ per-app or per-request
+        const procedureName = this.procedureName || "anonymous";
+        const contextMiddleware = [];
+        if (context.middleware?.getMiddlewareFor) {
+            const externalMiddleware = context.middleware.getMiddlewareFor(procedureName);
+            for (const mw of externalMiddleware) {
+                // Adapt external middleware to internal format
+                const adaptedMw = async (mwArgs, ctx, nextFn) => {
+                    const envelope = {
+                        sourceType: this.sourceType,
+                        sourceId: this.sourceId,
+                        operationName: procedureName,
+                        args: mwArgs,
+                        context: ctx,
+                    };
+                    // Cast envelope to any[] version since external middleware uses Middleware<any[]>
+                    return mw(mwArgs, envelope, async (transformedArgs) => {
+                        return nextFn(transformedArgs);
+                    });
+                };
+                contextMiddleware.push(adaptedMw);
+            }
+        }
+        // Combine: context middleware runs first, then instance middleware
+        const allMiddleware = [...contextMiddleware, ...this.internalMiddlewares];
+        // Helper function to run the middleware pipeline
+        const executeMiddlewarePipeline = async () => {
+            // Check Abort Signal before starting
+            if (context?.signal?.aborted) {
+                throw new AbortError();
+            }
+            // Run Middleware Pipeline
+            let index = 0;
+            let currentInput = args;
+            const runMiddleware = async (transformedInput) => {
+                // Check Abort Signal before each middleware/handler
+                if (context?.signal?.aborted) {
+                    throw new AbortError();
+                }
+                // Update current input if middleware provided transformed input
+                if (transformedInput !== undefined) {
+                    currentInput = transformedInput;
+                }
+                if (index < allMiddleware.length) {
+                    const middleware = allMiddleware[index++];
+                    const result = await middleware(currentInput, context, runMiddleware);
+                    // Check Abort Signal after middleware execution (middleware might have aborted)
+                    if (context?.signal?.aborted) {
+                        throw new AbortError();
+                    }
+                    return result;
+                }
+                else {
+                    // Check Abort Signal before handler
+                    if (context?.signal?.aborted) {
+                        throw new AbortError();
+                    }
+                    // Call handler with current input (which may have been transformed)
+                    const result = this.handler(...currentInput);
+                    // Handler can return anything - Promise.resolve handles Promise, value, or AsyncIterable
+                    return result;
+                }
+            };
+            return runMiddleware();
+        };
+        // Skip ExecutionTracker for transparent wrappers (e.g., withContext)
+        // This prevents duplicate procedure tracking when a wrapper delegates to another procedure
+        if (this.skipTracking) {
+            return executeMiddlewarePipeline();
+        }
+        // Wrap execution with ExecutionTracker
+        return ExecutionTracker.track(context, {
+            name: this.procedureName || `procedure:${this.handler.name || "anonymous"}`,
+            parentPid: context.procedurePid,
+            metadata: this.metadata, // Pass metadata to ExecutionTracker for span attributes
+            // Execution boundary configuration (Phase 3)
+            executionBoundary: this.executionBoundary,
+            executionType: this.executionType,
+        }, async (_node) => {
+            return executeMiddlewarePipeline();
+        });
+    }
+    /**
+     * Internal execution method.
+     */
+    async execute(args, options, opEvents) {
+        if (!this.handler) {
+            throw ValidationError.required("handler", "Procedure handler not set. Call constructor with handler or use .setHandler() method.");
+        }
+        // Validate input if schema provided
+        let validatedArgs = args;
+        if (this.schema && args.length > 0) {
+            const validated = await this.schema.parseAsync(args[0]);
+            validatedArgs = [validated, ...args.slice(1)];
+        }
+        // Resolve context: either create new root or derive child from current
+        let context;
+        const currentContext = Context.tryGet();
+        // Detect if we have "real" context overrides (not just signal/traceId from createHandle)
+        const hasRealOverrides = options &&
+            Object.keys(options).some((k) => k !== "signal" && k !== "traceId" && k !== "events");
+        if (!currentContext) {
+            // No existing context - create a new root context
+            context = Context.create(options);
+            // If opEvents was provided, use it instead of the auto-created events emitter
+            // (Context.create always creates a new EventEmitter, we need to override it)
+            if (opEvents) {
+                context.events = opEvents;
+            }
+        }
+        else if (hasRealOverrides) {
+            // Existing context with meaningful overrides - create a child context
+            // This ensures we don't mutate the parent's context object
+            context = Context.child({
+                ...options,
+                events: opEvents ?? options?.events ?? currentContext.events,
+                channels: options?.channels ?? currentContext.channels,
+            });
+        }
+        else {
+            // Existing context, no meaningful overrides - reuse as-is
+            // This preserves procedureGraph sharing with parent context
+            context = currentContext;
+        }
+        // Create handle if handleFactory is provided and handle doesn't exist
+        if (this.handleFactory && !context.executionHandle) {
+            const events = new EventBuffer();
+            const traceId = context.traceId || randomUUID();
+            const resultPromise = Promise.resolve();
+            // Only call handleFactory if it's a function, otherwise use default implementation
+            const handle = typeof this.handleFactory === "function"
+                ? this.handleFactory(events, traceId, resultPromise, context)
+                : new ExecutionHandleImpl(resultPromise, events, traceId);
+            context.executionHandle = handle;
+        }
+        const currentStore = Context.tryGet();
+        const isRoot = context !== currentStore;
+        const executeInternal = async () => {
+            let result;
+            if (isRoot) {
+                result = await Context.run(context, async () => this.runMiddlewarePipeline(validatedArgs, context));
+            }
+            else {
+                result = await this.runMiddlewarePipeline(validatedArgs, context);
+            }
+            // AsyncIterables are now fully handled by ExecutionTracker (context, procedure:end/error)
+            // No additional wrapping needed here - just return the result
+            // ExecutionTracker wraps AsyncIterables to:
+            // 1. Maintain the forked context with procedurePid during iteration
+            // 2. Emit procedure:end when iteration completes
+            // 3. Emit procedure:error on errors
+            return result;
+        };
+        // Apply timeout if configured
+        if (this.timeout && this.timeout > 0) {
+            return this.withTimeoutRace(executeInternal(), this.timeout);
+        }
+        return executeInternal();
+    }
+    /**
+     * Race execution against a timeout.
+     */
+    async withTimeoutRace(promise, timeoutMs) {
+        let timeoutId;
+        const timeoutPromise = new Promise((_, reject) => {
+            timeoutId = setTimeout(() => {
+                reject(AbortError.timeout(timeoutMs));
+            }, timeoutMs);
+        });
+        try {
+            return await Promise.race([promise, timeoutPromise]);
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    /**
+     * Execute the procedure and return a ProcedurePromise.
+     *
+     * All procedures return ProcedurePromise<T> consistently:
+     * - `await proc()` → T (the value or handle)
+     * - `await proc().result` → final result (chains to T.result if exists)
+     *
+     * By default, procedures are PASS-THROUGH:
+     * - T is whatever the handler returns
+     * - If handler returns something with .result, proc().result chains to it
+     *
+     * To wrap in ExecutionHandle, provide a handleFactory:
+     * - T is ExecutionHandle<HandlerReturn>
+     * - handle.result is the handler's return value
+     */
+    exec(...args) {
+        // If handleFactory is a function or true, use handle wrapping
+        if (typeof this.handleFactory === "function" || this.handleFactory === true) {
+            return this.executeWithHandle(args);
+        }
+        // Default: pass-through mode (handleFactory: false or undefined)
+        return this.executePassThrough(args);
+    }
+    /**
+     * Execute in pass-through mode - returns ProcedurePromise<T>.
+     * Used when handleFactory: false.
+     *
+     * Always returns ProcedurePromise for consistency, even when there's no middleware.
+     * This ensures `await proc()` and `await proc().result` always work predictably.
+     */
+    executePassThrough(args) {
+        const promise = (async () => {
+            // Validate if schema provided
+            let validatedArgs = args;
+            if (this.schema && args.length > 0) {
+                const validated = await this.schema.parseAsync(args[0]);
+                validatedArgs = [validated, ...args.slice(1)];
+            }
+            // If no middleware and no timeout, call handler directly
+            // But still check abort signal first
+            if (this.middlewares.length === 0 && !this.timeout) {
+                const ctx = Context.tryGet();
+                if (ctx?.signal?.aborted) {
+                    throw new AbortError();
+                }
+                return this.handler(...validatedArgs);
+            }
+            // Otherwise go through the middleware chain
+            return this.execute(validatedArgs);
+        })();
+        return createProcedurePromise(promise);
+    }
+    /**
+     * Execute with handle wrapping - returns ProcedurePromise<ExecutionHandle<T>>.
+     * Used when handleFactory is provided (not false).
+     */
+    executeWithHandle(args) {
+        const handle = this.createHandle(args);
+        // Wrap the synchronously-created handle in a ProcedurePromise
+        return createProcedurePromise(Promise.resolve(handle));
+    }
+    /**
+     * Create an ExecutionHandle for the given args.
+     * This is the core method that creates the handle and starts execution.
+     */
+    createHandle(args) {
+        const events = new EventBuffer();
+        const traceId = Context.tryGet()?.traceId || randomUUID();
+        const abortController = new AbortController();
+        // Create the result promise that will resolve when execution completes
+        const resultPromise = (async () => {
+            // Validate input if schema provided
+            let validatedArgs = args;
+            if (this.schema && args.length > 0) {
+                const validated = await this.schema.parseAsync(args[0]);
+                validatedArgs = [validated, ...args.slice(1)];
+            }
+            // Execute with the events buffer - it has EventEmitter-compatible API
+            return this.execute(validatedArgs, { signal: abortController.signal, traceId }, events);
+        })();
+        // Create handle using factory or default implementation
+        if (this.handleFactory && typeof this.handleFactory === "function") {
+            const context = Context.tryGet() || Context.create({ traceId });
+            return this.handleFactory(events, traceId, resultPromise, context, abortController);
+        }
+        return new ExecutionHandleImpl(resultPromise, events, traceId, abortController);
+    }
+    /**
+     * Add middleware to the procedure. Returns a new Procedure.
+     */
+    use(...middleware) {
+        const flattened = flattenMiddleware(middleware);
+        return createProcedureFromImpl({
+            name: this.procedureName,
+            schema: this.schema,
+            middleware: [...this.middlewares, ...flattened],
+            handleFactory: this.handleFactory,
+            sourceType: this.sourceType,
+            sourceId: this.sourceId,
+            metadata: this.metadata, // Preserve metadata when adding middleware
+            // Preserve execution tracking options (Phase 3)
+            executionBoundary: this.executionBoundary,
+            executionType: this.executionType,
+            skipTracking: this.skipTracking,
+            timeout: this.timeout,
+        }, this.handler);
+    }
+    /**
+     * Create a procedure variant with merged context. Returns a new Procedure.
+     *
+     * IMPORTANT: This does NOT copy middleware to the new procedure. The middleware
+     * runs when proc.execute() is called in the wrapped handler. Copying middleware
+     * would cause double execution since execute() runs its own middleware chain.
+     */
+    withContext(ctx) {
+        const proc = this;
+        // Create a wrapper that merges context BEFORE execution
+        const wrappedHandler = (async (...args) => {
+            // Get current context and merge
+            // Note: Signal should come from ExecutionHandle, not Context inheritance
+            // Context signal is only for external aborts (e.g., user-provided), not execution lifecycle
+            const currentCtx = Context.tryGet() || Context.create();
+            const mergedCtx = { ...currentCtx, ...ctx };
+            // Run with merged context - this ensures middleware sees the merged context
+            return Context.run(mergedCtx, async () => {
+                // Call the original procedure's execute method with merged context as options
+                // This ensures the merged context is used throughout execution
+                return proc.execute(args, ctx);
+            });
+        });
+        // Don't copy middleware here! The original proc.execute() will run its middleware.
+        // Copying middleware would cause double execution.
+        // Skip tracking for this wrapper - the inner proc.execute() will handle tracking.
+        return createProcedureFromImpl({
+            name: this.procedureName,
+            schema: this.schema,
+            middleware: [], // Empty - middleware runs in proc.execute()
+            handleFactory: this.handleFactory,
+            sourceType: this.sourceType,
+            sourceId: this.sourceId,
+            metadata: this.metadata, // Preserve metadata for telemetry
+            skipTracking: true, // Wrapper delegates to original - don't double-track
+        }, wrappedHandler);
+    }
+    /**
+     * Add a single middleware. Returns a new Procedure.
+     */
+    withMiddleware(mw) {
+        return this.use(mw);
+    }
+    /**
+     * Create a procedure variant with a timeout. Returns a new Procedure.
+     * Throws AbortError.timeout() if the timeout is exceeded.
+     *
+     * @param ms - Timeout in milliseconds
+     */
+    withTimeout(ms) {
+        return createProcedureFromImpl({
+            name: this.procedureName,
+            schema: this.schema,
+            middleware: this.middlewares,
+            handleFactory: this.handleFactory,
+            sourceType: this.sourceType,
+            sourceId: this.sourceId,
+            metadata: this.metadata,
+            timeout: ms,
+            // Preserve execution tracking options (Phase 3)
+            executionBoundary: this.executionBoundary,
+            executionType: this.executionType,
+            skipTracking: this.skipTracking,
+        }, this.handler);
+    }
+    /**
+     * Create a procedure variant with merged metadata. Returns a new Procedure.
+     * Metadata flows to ExecutionTracker and is included in procedure events and telemetry spans.
+     *
+     * @param metadata - Metadata to merge with existing procedure metadata
+     */
+    withMetadata(metadata) {
+        return createProcedureFromImpl({
+            name: this.procedureName,
+            schema: this.schema,
+            middleware: this.middlewares,
+            handleFactory: this.handleFactory,
+            sourceType: this.sourceType,
+            sourceId: this.sourceId,
+            // Merge metadata - new values override existing
+            metadata: { ...this.metadata, ...metadata },
+            timeout: this.timeout,
+            // Preserve execution tracking options (Phase 3)
+            executionBoundary: this.executionBoundary,
+            executionType: this.executionType,
+            skipTracking: this.skipTracking,
+        }, this.handler);
+    }
+    /**
+     * Pipe the output of this procedure to another procedure.
+     * Creates a new procedure that runs this procedure, then passes its result to the next.
+     */
+    pipe(next) {
+        const self = this;
+        const pipedHandler = async (...args) => {
+            const firstResult = await self.execute(args);
+            const secondResult = await next(firstResult);
+            return secondResult;
+        };
+        return createProcedureFromImpl({
+            name: this.procedureName ? `${this.procedureName}.pipe` : "piped-procedure",
+            sourceType: this.sourceType,
+            sourceId: this.sourceId,
+            metadata: this.metadata,
+            timeout: this.timeout,
+        }, pipedHandler);
+    }
+}
+function createProcedureFromImpl(options, handler) {
+    const impl = new ProcedureImpl(options, handler);
+    // Create a callable function
+    const proc = (...args) => {
+        // Support context as last arg (backward compat)
+        let actualArgs;
+        if (args.length > 0) {
+            const lastArg = args[args.length - 1];
+            // Check if last arg is a KernelContext
+            if (isKernelContext(lastArg)) {
+                actualArgs = args.slice(0, -1);
+            }
+            else {
+                actualArgs = args;
+            }
+        }
+        else {
+            actualArgs = args;
+        }
+        // Return result directly (pass-through) or ExecutionHandle
+        return impl.exec(...actualArgs);
+    };
+    // Attach methods - same for both Procedure with handle return and Pass-through return Procedure
+    proc.use = impl.use.bind(impl);
+    proc.withContext = impl.withContext.bind(impl);
+    proc.withMiddleware = impl.withMiddleware.bind(impl);
+    proc.withTimeout = impl.withTimeout.bind(impl);
+    proc.withMetadata = impl.withMetadata.bind(impl);
+    proc.exec = impl.exec.bind(impl);
+    proc.pipe = impl.pipe.bind(impl);
+    // Brand with symbol for deterministic type checking
+    proc[PROCEDURE_SYMBOL] = true;
+    return proc;
+}
+export function generatorProcedure(optionsOrFn, fn) {
+    if (typeof optionsOrFn === "function") {
+        fn = optionsOrFn;
+    }
+    return createProcedure(function (...args) {
+        if (!fn) {
+            throw ValidationError.required("handler", "Handler function required when options are provided");
+        }
+        return fn.apply(this, args);
+    });
+}
+// Implementation
+export function createProcedure(optionsOrFn, fn) {
+    let options = {};
+    let handler;
+    if (typeof optionsOrFn === "function") {
+        handler = optionsOrFn;
+        options = { sourceType: "procedure" };
+    }
+    else if (optionsOrFn) {
+        options = { ...optionsOrFn, sourceType: "procedure" };
+        if (!fn) {
+            throw ValidationError.required("handler", "Handler function required when options are provided");
+        }
+        handler = fn;
+    }
+    else if (fn) {
+        handler = fn;
+        options = { sourceType: "procedure" };
+    }
+    if (!handler) {
+        throw ValidationError.required("handler");
+    }
+    return createProcedureFromImpl(options, handler);
+}
+export function pipe(...procedures) {
+    if (procedures.length === 0) {
+        throw new ValidationError("pipe requires at least one procedure", "procedures");
+    }
+    if (procedures.length === 1) {
+        return procedures[0];
+    }
+    // Chain all procedures together using the instance pipe method
+    let result = procedures[0];
+    for (let i = 1; i < procedures.length; i++) {
+        result = result.pipe(procedures[i]);
+    }
+    return result;
+}
+export function compose(...procedures) {
+    if (procedures.length === 0) {
+        throw new ValidationError("compose requires at least one procedure", "procedures");
+    }
+    if (procedures.length === 1) {
+        return procedures[0];
+    }
+    // Chain in reverse order: compose(a, b, c) = a(b(c(x)))
+    // Start from the end and work backwards
+    let result = procedures[procedures.length - 1];
+    for (let i = procedures.length - 2; i >= 0; i--) {
+        result = result.pipe(procedures[i]);
+    }
+    return result;
+}
+export function createHook(optionsOrFn, fn) {
+    let options = {};
+    let handler;
+    if (typeof optionsOrFn === "function") {
+        handler = optionsOrFn;
+        options = { sourceType: "hook" };
+    }
+    else if (optionsOrFn) {
+        options = { ...optionsOrFn, sourceType: "hook" };
+        if (!fn) {
+            throw ValidationError.required("handler", "Handler function required when options are provided");
+        }
+        handler = fn;
+    }
+    else if (fn) {
+        handler = fn;
+        options = { sourceType: "hook" };
+    }
+    if (!handler) {
+        throw ValidationError.required("handler");
+    }
+    return createProcedure(options, handler);
+}
+// ============================================================================
+// ProcedureBase - Base class for auto-wrapping methods as Procedures
+// ============================================================================
+// ============================================================================
+// Helper Functions
+// ============================================================================
+/**
+ * Type-safe helper to apply middleware to a Procedure while preserving types.
+ *
+ * This helper ensures that middleware types are correctly matched to the Procedure's
+ * argument types, avoiding the need for type assertions.
+ *
+ * @example
+ * ```typescript
+ * const proc = createProcedure({ name: 'test' }, async (input: string) => input);
+ * const middleware: Middleware<[string]>[] = [...];
+ * const procWithMw = applyMiddleware(proc, middleware);
+ * // procWithMw is still Procedure<[string], string> - types preserved!
+ * ```
+ */
+export function applyMiddleware(procedure, ...middleware) {
+    return procedure.use(...middleware);
+}
+/**
+ * Type-safe helper to apply middleware from a registry/hook system.
+ *
+ * This is useful when middleware comes from hook registries where types might
+ * be unions or `Middleware<any[]>`. The helper ensures type safety by requiring
+ * the middleware to match the Procedure's argument types.
+ *
+ * @example
+ * ```typescript
+ * const proc = createProcedure({ name: 'test' }, async (input: string) => input);
+ * const registryMiddleware = registry.getMiddleware('test'); // Middleware<any[]>[]
+ * const procWithMw = applyRegistryMiddleware(proc, registryMiddleware);
+ * // Types are preserved and validated
+ * ```
+ */
+export function applyRegistryMiddleware(procedure, ...middleware) {
+    // Type assertion is safe here because we're applying middleware that should
+    // be compatible with the Procedure's args. The runtime will validate.
+    // We accept Procedure<any, any> to handle cases where createEngineProcedure
+    // returns a generic Procedure type that needs to be narrowed.
+    return procedure.use(...middleware);
+}
+export function wrapProcedure(middleware) {
+    function wrapProcedureImpl(optionsOrFn, fn) {
+        let config;
+        let handler;
+        if (typeof optionsOrFn === "function") {
+            // Handler-only overload: createEngineProcedure(handler)
+            handler = optionsOrFn;
+            config = {
+                name: handler.name || "anonymous",
+            };
+        }
+        else if (optionsOrFn) {
+            // Config + handler overload: createEngineProcedure(config, handler)
+            config = { ...optionsOrFn };
+            if (!fn) {
+                throw ValidationError.required("handler", "Handler function required when options are provided");
+            }
+            handler = fn;
+        }
+        else if (fn) {
+            // Edge case: just handler as second param
+            handler = fn;
+            config = {
+                name: handler.name || "anonymous",
+            };
+        }
+        else {
+            throw ValidationError.required("handler");
+        }
+        // Merge middleware: engine defaults + global + config middleware
+        config.middleware = [...middleware, ...(config.middleware || [])];
+        return createProcedure(config, handler);
+    }
+    return wrapProcedureImpl;
+}
+export function wrapHook(middleware) {
+    function wrapHookImpl(optionsOrFn, fn) {
+        let config;
+        let handler;
+        if (typeof optionsOrFn === "function") {
+            // Handler-only overload: createEngineHook(handler)
+            handler = optionsOrFn;
+            config = {
+                name: handler.name || "anonymous",
+            };
+        }
+        else if (optionsOrFn) {
+            // Config + handler overload: createEngineHook(config, handler)
+            config = { ...optionsOrFn };
+            if (!fn) {
+                throw ValidationError.required("handler", "Handler function required when options are provided");
+            }
+            handler = fn;
+        }
+        else if (fn) {
+            // Edge case: just handler as second param
+            handler = fn;
+            config = {
+                name: handler.name || "anonymous",
+            };
+        }
+        else {
+            throw ValidationError.required("handler");
+        }
+        // Merge middleware: engine defaults + global + config middleware
+        config.middleware = [...middleware, ...(config.middleware || [])];
+        return createHook(config, handler);
+    }
+    return wrapHookImpl;
+}
+//# sourceMappingURL=procedure.js.map