@procedures/client 0.0.0-stage → 0.2.0

package/dist/client/client.js

@@ -0,0 +1,1011 @@
+/**
+ * Universal Client
+ *
+ * Protocol-agnostic RPC client with middleware composition.
+ * Works with any transport: HTTP, gRPC, WebSocket, or local.
+ *
+ * The Client class is generic over its accumulated context type, enabling
+ * compile-time validation of middleware chains. Each call to `use()` returns
+ * a new type that includes the middleware's provided context.
+ *
+ * @example
+ * ```typescript
+ * // Type accumulates as middleware is added
+ * const client = new Client(transport)
+ *   .use(createRetryMiddleware())     // Client<BaseContext & RetryContext>
+ *   .use(createCacheMiddleware({ methods: ["users.get"] }))     // Client<... & CacheContext>
+ *   .use(createAuthMiddleware(...))   // Client<... & AuthContext>
+ *
+ * // Middleware requiring context validates at compile time
+ * client.use(middlewareThatRequiresAuth); // OK if AuthContext is in chain
+ *
+ * // Context passing via withContext() and per-call options
+ * const authedClient = client.withContext({ auth: { token: "user-token" } });
+ * await authedClient.call(method, payload, { context: { retry: { maxAttempts: 5 } } });
+ * ```
+ */
+import { ClientError } from "./types.js";
+import { compose } from "../middleware/compose.js";
+import { pathToMethod } from "../server/method.js";
+import { mergeContext, normalizeCallOptions } from "./context.js";
+import { methodToKey } from "./validation/types.js";
+import { SCHEMA_REGISTRY } from "./validation/middleware.js";
+import { buildResponse, toMiddlewareContext } from "./call-types.js";
+import { RouteResolver } from "./route-resolver.js";
+import { BatchExecutor } from "./batch-executor.js";
+import { TIMEOUT_METADATA_KEY, narrowCapability } from "../procedures/capability.js";
+import { PROCEDURE_REGISTRY } from "../procedures/registry.js";
+import { validateSchema } from "../procedures/schema.js";
+import { InvocationError, invokeProcedure, outputItems, outputValue, } from "../procedures/invoke.js";
+import { isHandlerConfig, isStreamConfig } from "./consumption.js";
+import { isAnyProcedureRef, isPlainObject, normalizeRef, prepareRootCall, rawInputRule, } from "../procedures/ref.js";
+/** Each element of each array item: the stream form of an `outputMode: "batch"` procedure. */
+async function* batchElements(items) {
+    for await (const item of items) {
+        if (Array.isArray(item)) {
+            yield* item;
+        }
+        else {
+            yield item;
+        }
+    }
+}
+/**
+ * The items of a source, with up to `size` items read ahead of the reader. With size 0, the
+ * source runs only when the reader reads (the source itself is returned).
+ */
+function readAhead(source, size) {
+    if (size <= 0)
+        return source;
+    return (async function* () {
+        const iterator = source[Symbol.asyncIterator]();
+        const buffer = [];
+        let ended = false;
+        const pull = () => {
+            while (!ended && buffer.length < size + 1) {
+                const next = iterator.next();
+                buffer.push(next);
+                // The handler marks the end, and keeps a failure from being unhandled until it is read
+                next.then((result) => {
+                    if (result.done)
+                        ended = true;
+                }, () => {
+                    ended = true;
+                });
+            }
+        };
+        let finished = false;
+        try {
+            // Before each read: the item for the reader, and `size` items ahead
+            for (pull(); buffer.length > 0; pull()) {
+                const result = await buffer.shift();
+                if (result.done)
+                    break;
+                yield result.value;
+            }
+            finished = true;
+        }
+        finally {
+            if (!finished)
+                await iterator.return?.();
+        }
+    })();
+}
+/**
+ * Generate a unique message ID.
+ */
+function generateId() {
+    return `${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+}
+/**
+ * Universal Client for protocol-agnostic RPC.
+ *
+ * Features:
+ * - Works with any transport (HTTP, gRPC, WebSocket, local)
+ * - Middleware composition (retry, cache, timeout, custom)
+ * - Stream-first API (single response = stream with 1 item)
+ * - Type-safe request/response handling
+ * - **Type-accumulating middleware**: Context types build through `use()` calls
+ *
+ * @typeParam TContext - Accumulated context type from applied middleware.
+ *   Starts as `{}` and grows as middleware is added via `use()`.
+ *
+ * @example
+ * ```typescript
+ * // HTTP client with type-accumulating middleware
+ * const client = new Client({ transport: new HttpTransport({ baseUrl: "/api" }) })
+ *   .use(createRetryMiddleware())    // Client<{} & RetryContext>
+ *   .use(createCacheMiddleware({ methods: ["users.get"] }))    // Client<{} & RetryContext & CacheContext>
+ *   .use(createAuthMiddleware({      // Client<... & AuthContext>
+ *     token: "abc123"
+ *   }));
+ *
+ * // The client type now carries all middleware context
+ * const user = await client.call(
+ *   { service: "users", operation: "get" },
+ *   { id: 123 }
+ * );
+ *
+ * // Streaming
+ * for await (const event of client.stream(
+ *   { service: "events", operation: "watch" },
+ *   { topic: "orders" }
+ * )) {
+ *   console.log(event);
+ * }
+ * ```
+ */
+export class Client {
+    transport;
+    middleware = [];
+    defaultMetadata;
+    throwOnError;
+    /** The bus of the local procedures. Undefined: the global bus. */
+    bus;
+    /** The interceptors of the local invocations (roadmap 1.2) */
+    interceptors = [];
+    /** The capability of the local invocations (CAPABILITIES-2026-10). Undefined: no limits. */
+    capability;
+    /** The order of the clearance values. */
+    clearanceOrder;
+    /**
+     * Context values set via withContext().
+     * Merged with parent context when creating child clients.
+     */
+    clientContext;
+    /**
+     * Parent client reference (for context inheritance).
+     * When set, middleware and transport are shared, only context differs.
+     */
+    parent;
+    constructor(options) {
+        // Support both new Client(transport) and new Client({ transport, ... })
+        if ("send" in options && typeof options.send === "function") {
+            // Direct transport passed - narrow to Transport type
+            const transport = options;
+            this.transport = transport;
+            this.defaultMetadata = {};
+            this.throwOnError = true;
+        }
+        else {
+            // Options object - narrow to ClientOptions type
+            const opts = options;
+            this.transport = opts.transport;
+            this.defaultMetadata = opts.defaultMetadata || {};
+            this.throwOnError = opts.throwOnError !== false;
+            this.bus = opts.bus;
+            this.interceptors = opts.interceptors ?? [];
+            this.capability = opts.capability;
+            this.clearanceOrder = opts.clearanceOrder;
+        }
+        // Initialize empty context (child clients override this)
+        this.clientContext = {};
+    }
+    /**
+     * Create a child client from this client (private, for withContext).
+     */
+    static createChild(parent, additionalContext) {
+        // Create a child with shared middleware chain
+        const child = Object.create(Client.prototype);
+        // Share immutable references (no copying)
+        child.transport = parent.transport;
+        child.middleware = parent.middleware;
+        child.defaultMetadata = parent.defaultMetadata;
+        child.throwOnError = parent.throwOnError;
+        child.bus = parent.bus;
+        child.interceptors = parent.interceptors;
+        child.capability = parent.capability;
+        child.clearanceOrder = parent.clearanceOrder;
+        // Object.create() bypasses class-field initializers, so procedureRegistry (which normally
+        // defaults to PROCEDURE_REGISTRY via a field initializer) would be undefined on the child
+        // and exec()/route() would throw "Cannot read properties of undefined (reading 'get')".
+        // Inherit the parent's registry; leave the lazy resolver/executor undefined so the child
+        // builds its own (batchExecutor binds this.executeProcedure, which must be the child's).
+        // See documentation/BUGS-2026-07.md (H1).
+        child.procedureRegistry = parent.procedureRegistry;
+        child.routeResolver = undefined;
+        child.batchExecutor = undefined;
+        // Set parent and additional context
+        child.parent = parent;
+        child.clientContext = additionalContext;
+        return child;
+    }
+    /**
+     * Create a child client with additional context.
+     *
+     * Child clients:
+     * - Share the middleware chain (cheap to create)
+     * - Inherit parent context (merged recursively)
+     * - Can override specific context fields
+     *
+     * Context priority (lowest to highest):
+     * 1. Middleware defaults (e.g., maxRetries: 3 from createRetryMiddleware)
+     * 2. Parent client context (full inheritance chain)
+     * 3. This client's context
+     * 4. Per-call context override
+     *
+     * @param context - Context to set/override on the child client
+     * @returns New client with accumulated context
+     *
+     * @example
+     * ```typescript
+     * // Create authenticated child client
+     * const authedClient = client.withContext({
+     *   auth: { token: "user-token" },
+     *   timeout: { overall: 5000 }
+     * });
+     *
+     * // Nested children inherit and can override
+     * const adminClient = authedClient.withContext({
+     *   auth: { token: "admin-token" },  // Overrides parent token
+     *   // timeout inherited from parent
+     * });
+     * ```
+     */
+    withContext(context) {
+        return Client.createChild(this, context);
+    }
+    /**
+     * Get effective context by merging entire parent chain.
+     *
+     * @returns Merged context from all ancestors plus this client
+     */
+    getEffectiveContext() {
+        if (this.parent) {
+            return mergeContext(this.parent.getEffectiveContext(), this.clientContext);
+        }
+        return this.clientContext;
+    }
+    /**
+     * Add middleware to the client.
+     *
+     * Middleware is composed in the order added (onion model):
+     * - First added = outermost layer
+     * - Last added = innermost layer (closest to transport)
+     *
+     * **Type Accumulation**: When using `TypedClientMiddleware`, the return type
+     * accumulates the middleware's provided context. This enables compile-time
+     * validation of middleware chains.
+     *
+     * @typeParam TProvides - Context type this middleware provides
+     * @typeParam TRequires - Context type this middleware requires (must be subset of TContext)
+     * @param middleware - Middleware function (typed or untyped)
+     * @returns Client with accumulated context type
+     *
+     * @example
+     * ```typescript
+     * // Type accumulation example
+     * const client = new Client(transport)
+     *   .use(createTimeoutMiddleware({ overall: 5000 }))  // Client<TimeoutContext>
+     *   .use(createRetryMiddleware())                     // Client<TimeoutContext & RetryContext>
+     *   .use(createCacheMiddleware({ methods: ["users.get"] }));                    // Client<... & CacheContext>
+     *
+     * // Middleware ordering (onion model)
+     * client
+     *   .use(timeoutMiddleware())   // Outer: handles timeouts
+     *   .use(retryMiddleware())     // Middle: handles retries
+     *   .use(cacheMiddleware());    // Inner: handles caching
+     * ```
+     */
+    use(middleware) {
+        this.middleware.push(middleware);
+        // Cast is safe because we're just adding type information
+        // Runtime behavior is unchanged
+        return this;
+    }
+    /**
+     * Make a single RPC call (request/response).
+     *
+     * The result is the last item of the response stream: the one item of a request/response
+     * call, or the final item of a streaming procedure. To read each item, use `stream()`.
+     *
+     * @param method - Method to invoke
+     * @param payload - Request payload
+     * @param options - Call options (context override, metadata, signal, schema)
+     *                  OR legacy Metadata object for backward compatibility
+     * @returns Response payload
+     * @throws {ClientError} if response has error status (when throwOnError=true)
+     *
+     * @example
+     * ```typescript
+     * // Simple call
+     * const user = await client.call(
+     *   { service: "users", operation: "get" },
+     *   { id: 123 }
+     * );
+     *
+     * // With context override
+     * const user = await client.call(
+     *   { service: "users", operation: "get" },
+     *   { id: 123 },
+     *   { context: { timeout: { overall: 10000 } } }
+     * );
+     * ```
+     */
+    async call(method, payload, options) {
+        // The result of a stream is its last item (the "sponge" mode of procedures/types.ts). Every
+        // request/response transport yields one item, so its result does not change. (Before, the
+        // result was the first item, and a falsy first item - 0, false, "" - threw "No response".)
+        let last;
+        for await (const item of this.stream(method, payload, options)) {
+            last = { value: item };
+        }
+        if (!last) {
+            throw new Error("No response received from stream");
+        }
+        return last.value;
+    }
+    // ===========================================================================
+    // Procedure Reference Execution (Procedure-as-Data)
+    // ===========================================================================
+    /**
+     * Execute a procedure reference with automatic input hydration.
+     *
+     * This method supports procedure-as-data: procedures can be passed as inputs
+     * to other procedures, composed declaratively via JSON, or imperatively via TypeScript.
+     *
+     * **Input Hydration**: Any ProcedureRef or `$proc` objects in the input tree
+     * are automatically executed and replaced with their results before the
+     * main procedure runs.
+     *
+     * @param refOrPath - Procedure reference, JSON procedure ref, or procedure path
+     * @param input - Input for the procedure. With a reference, its fields go over the fields of the reference's input.
+     * @returns Output of the procedure
+     *
+     * @example
+     * ```typescript
+     * import { proc } from "@procedures/client";
+     *
+     * // Using proc() builder
+     * const result = await client.exec(
+     *   proc(["git", "add"]).input({ all: true }).build()
+     * );
+     *
+     * // Using JSON format
+     * const result = await client.exec({
+     *   $proc: ["git", "add"],
+     *   input: { all: true },
+     * });
+     *
+     * // Using path + input (simple form)
+     * const result = await client.exec(["git", "add"], { all: true });
+     *
+     * // Nested procedure refs (hydrated automatically)
+     * const result = await client.exec(
+     *   proc(["dag", "traverse"]).input({
+     *     visit: proc(["client", "chain"]).input({
+     *       steps: [
+     *         proc(["git", "add"]).input({ all: true }).ref,
+     *         proc(["git", "commit"]).input({ message: "auto" }).ref,
+     *       ],
+     *     }).ref,
+     *   }).build()
+     * );
+     * ```
+     */
+    async exec(refOrPath, input, options = {}) {
+        const caller = options.onRef ? { onRef: options.onRef } : {};
+        const { path, input: hydratedInput } = await this.prepareRef(refOrPath, input, caller);
+        return this.execInternal(path, hydratedInput, caller);
+    }
+    /**
+     * Execute a procedure reference and read each output: each item of a streaming procedure, or
+     * the one value of another procedure. The input refs run as in `exec()`. Nothing runs until
+     * the caller reads the first item.
+     *
+     * @example
+     * ```typescript
+     * for await (const line of client.execStream(["logs", "tail"], { file: "app.log" })) {
+     *   console.log(line);
+     * }
+     * ```
+     */
+    execStream(refOrPath, input, options = {}) {
+        const self = this;
+        const caller = options.onRef ? { onRef: options.onRef } : {};
+        return (async function* () {
+            const { path, input: hydratedInput } = await self.prepareRef(refOrPath, input, caller);
+            yield* self.execStreamInternal(path, hydratedInput, caller);
+        })();
+    }
+    /**
+     * The path and the input of a reference, with the refs of the input run (hydrated).
+     */
+    async prepareRef(refOrPath, input, caller = {}) {
+        // Normalize to ProcedureRef
+        let ref;
+        if (isAnyProcedureRef(refOrPath)) {
+            ref = normalizeRef(refOrPath);
+            // The fields of `input` go over the fields of the ref's input (before, `input` was ignored)
+            if (input !== undefined) {
+                ref = {
+                    ...ref,
+                    input: isPlainObject(ref.input) && isPlainObject(input) ? { ...ref.input, ...input } : input,
+                };
+            }
+        }
+        else if (Array.isArray(refOrPath) && refOrPath.every((s) => typeof s === "string")) {
+            // Path array provided, use second argument as input
+            ref = {
+                [Symbol.for("@mark/procedure")]: true,
+                path: refOrPath,
+                input: input ?? {},
+            };
+        }
+        else {
+            throw new Error("exec() requires a ProcedureRef, $proc JSON, or procedure path array");
+        }
+        // Create executor function for hydration
+        const executor = async (path, inp) => {
+            return this.execInternal(path, inp, caller);
+        };
+        // A procedure that takes its input raw (control flow, the `runs-refs` and `raw-input` tags,
+        // `procedure.define`) gets its operand refs RAW: it runs them itself, with correct
+        // ordering/laziness/error-scoping. Eagerly hydrating here would run the operands up-front
+        // and can hijack an all-refs array into an implicit chain that clobbers `steps`. See
+        // documentation/BUGS-2026-07.md (C2, H2, H3, M35). The procedure in the registry decides,
+        // also for the refs nested in the input (deep dive CORE-5: before, the last path segment did).
+        // The body of a defined procedure starts its root call the same way (prepareRootCall, DOC-3)
+        return prepareRootCall(ref, executor, { rawInput: rawInputRule(this.procedureRegistry), onRef: caller.onRef });
+    }
+    /**
+     * The options of a local invocation. The nested calls of the procedure go through this
+     * client, so a path without a local handler goes to the transport. The nested calls get the
+     * metadata and the signal of the caller: when the caller aborts, its nested work stops. (Before,
+     * each nested call started again with no metadata and no signal: deep dive CORE-10.)
+     */
+    invokeOptions(caller = {}) {
+        const self = this;
+        // The nested calls get the metadata and the signal of the invocation (an interceptor can
+        // change them), and name it as their parent
+        const client = (invocation) => {
+            // The nested calls get the capability of the invocation, or a narrower one on request
+            const nested = (options) => ({
+                metadata: invocation.metadata,
+                signal: invocation.signal,
+                parent: invocation,
+                onRef: caller.onRef,
+                capability: options?.narrow
+                    ? narrowCapability(invocation.capability, options.narrow, self.clearanceOrder)
+                    : invocation.capability,
+            });
+            return {
+                call: (path, input, options) => self.execInternal(path, input, nested(options)),
+                stream: (path, input, options) => self.execStreamInternal(path, input, nested(options)),
+            };
+        };
+        return {
+            registry: this.procedureRegistry,
+            metadata: caller.metadata ?? {},
+            signal: caller.signal,
+            client,
+            bus: this.bus,
+            interceptors: this.interceptors,
+            parent: caller.parent,
+            onRef: caller.onRef,
+            capability: caller.capability ?? this.capability,
+            clearanceOrder: this.clearanceOrder,
+        };
+    }
+    /**
+     * The call options of a remote call for a caller: its metadata as context, and its signal. A
+     * deadline goes as the remaining time (`procedure-timeout`, in milliseconds): the server
+     * calculates its own deadline, so a difference between two clocks has no effect.
+     */
+    remoteCallOptions(caller) {
+        const deadline = (caller.capability ?? this.capability)?.deadline;
+        const metadata = deadline === undefined ? caller.metadata ?? {} : { ...caller.metadata, [TIMEOUT_METADATA_KEY]: Math.max(0, deadline - Date.now()) };
+        const options = { context: metadata };
+        if (caller.signal) {
+            options.signal = caller.signal;
+        }
+        return options;
+    }
+    /**
+     * The input for a procedure without a local handler: validated with the local schema when
+     * the registry has the procedure, then sent to the transport.
+     */
+    async remoteInput(procedure, path, input) {
+        if (!procedure)
+            return input;
+        const result = await validateSchema(procedure.input, input);
+        if (!result.ok) {
+            throw new InvocationError("VALIDATION_ERROR", `Input validation failed for ${path.join(".")}: ${result.message}`, path);
+        }
+        return result.value;
+    }
+    /**
+     * Internal procedure execution (no hydration of the top-level input).
+     */
+    async execInternal(path, input, caller = {}) {
+        const procedure = this.procedureRegistry.get(path);
+        if (procedure?.handler) {
+            const options = this.invokeOptions(caller);
+            return outputValue(await invokeProcedure(procedure, input, options), path);
+        }
+        // No local handler: the transport runs it (a remote procedure)
+        return this.call(this.pathToMethod(path), await this.remoteInput(procedure, path, input), this.remoteCallOptions(caller));
+    }
+    /**
+     * Internal streaming execution (no hydration of the top-level input).
+     */
+    execStreamInternal(path, input, caller = {}) {
+        const self = this;
+        return (async function* () {
+            const procedure = self.procedureRegistry.get(path);
+            if (procedure?.handler) {
+                const options = self.invokeOptions(caller);
+                yield* outputItems(await invokeProcedure(procedure, input, options));
+                return;
+            }
+            yield* self.stream(self.pathToMethod(path), await self.remoteInput(procedure, path, input), self.remoteCallOptions(caller));
+        })();
+    }
+    /**
+     * Make a streaming RPC call.
+     *
+     * Returns an async iterable that yields response payloads.
+     * For single request/response, yields exactly one item.
+     *
+     * @param method - Method to invoke
+     * @param payload - Request payload
+     * @param options - Call options (context override, metadata, signal, schema)
+     *                  OR legacy Metadata object for backward compatibility
+     * @returns Async iterable of response payloads
+     * @throws {ClientError} if any response item has error status (when throwOnError=true)
+     *
+     * @example
+     * ```typescript
+     * // Streaming response
+     * for await (const event of client.stream(
+     *   { service: "events", operation: "watch" },
+     *   { topic: "orders" }
+     * )) {
+     *   console.log(event);
+     * }
+     *
+     * // With context and signal
+     * const controller = new AbortController();
+     * for await (const event of client.stream(
+     *   { service: "events", operation: "watch" },
+     *   { topic: "orders" },
+     *   { context: { timeout: { overall: 30000 } }, signal: controller.signal }
+     * )) {
+     *   console.log(event);
+     * }
+     * ```
+     */
+    async *stream(method, payload, options) {
+        // Normalize options (backward compatible with legacy Metadata parameter)
+        const opts = normalizeCallOptions(options);
+        // Merge context: parent chain -> client context -> per-call context
+        const effectiveContext = mergeContext(this.getEffectiveContext(), (opts.context ?? {}));
+        // Create message with merged context in metadata
+        const message = {
+            id: generateId(),
+            method,
+            payload,
+            metadata: {
+                ...this.defaultMetadata,
+                ...effectiveContext, // Context flows into metadata
+                ...opts.metadata, // Raw metadata last (highest priority)
+            },
+        };
+        // Set signal if provided
+        if (opts.signal) {
+            message.signal = opts.signal;
+        }
+        // Store schema override in metadata for Zod middleware
+        if (opts.schema) {
+            message.metadata.__schema = opts.schema;
+        }
+        // Compose middleware chain
+        const runner = this.composeMiddleware();
+        // Execute through middleware chain
+        const context = { message };
+        const responseStream = runner(context);
+        // Yield payloads, handling errors
+        for await (const item of responseStream) {
+            if (item.status.type === "error" && this.throwOnError) {
+                throw new ClientError(item.status, item.id);
+            }
+            yield item.payload;
+        }
+    }
+    /**
+     * Compose middleware chain using universal middleware composition.
+     *
+     * @returns Composed runner function
+     * @private
+     */
+    composeMiddleware() {
+        // Innermost function: call transport
+        const self = this;
+        const transportRunner = async function* (context) {
+            yield* self.transport.send(context.message);
+        };
+        // Use universal middleware composition
+        // compose(...middleware, finalRunner) applies middleware in order (onion model)
+        return compose(...this.middleware, transportRunner);
+    }
+    /**
+     * Get transport name.
+     */
+    get transportName() {
+        return this.transport.name;
+    }
+    /**
+     * Close client and cleanup transport resources.
+     */
+    async close() {
+        await this.transport.close();
+    }
+    // ===========================================================================
+    // Schema Registration (Zod Validation)
+    // ===========================================================================
+    /**
+     * Cached reference to Zod middleware for schema registration.
+     */
+    zodMiddleware;
+    /**
+     * Register a validation schema for a specific method.
+     *
+     * Requires `createZodMiddleware()` to be added via `.use()` first.
+     * Schemas are used to validate request payloads before sending and
+     * response payloads after receiving.
+     *
+     * @param method - Method to register schema for
+     * @param schemas - Input and/or output Zod schemas
+     * @returns this (for chaining)
+     *
+     * @example
+     * ```typescript
+     * import { z } from "zod";
+     *
+     * const client = new Client({ transport })
+     *   .use(createZodMiddleware())
+     *   .schema({ service: "users", operation: "get" }, {
+     *     input: z.object({ id: z.string() }),
+     *     output: z.object({ id: z.string(), name: z.string() }),
+     *   })
+     *   .schema({ service: "users", operation: "create" }, {
+     *     input: UserCreateSchema,
+     *     output: UserSchema,
+     *   });
+     *
+     * // Validation happens automatically on call
+     * const user = await client.call(
+     *   { service: "users", operation: "get" },
+     *   { id: "123" }  // Validated against input schema
+     * );
+     * // Response validated against output schema
+     * ```
+     */
+    schema(method, schemas) {
+        // Find Zod middleware (lazy lookup, cached)
+        if (!this.zodMiddleware) {
+            this.zodMiddleware = this.findZodMiddleware();
+        }
+        if (!this.zodMiddleware) {
+            throw new Error("Cannot register schema: createZodMiddleware() must be added via .use() first");
+        }
+        const key = methodToKey(method);
+        this.zodMiddleware[SCHEMA_REGISTRY].set(key, schemas);
+        return this;
+    }
+    /**
+     * Find Zod middleware in the middleware chain.
+     */
+    findZodMiddleware() {
+        // Check parent chain first (child clients share middleware)
+        if (this.parent) {
+            return this.parent.findZodMiddleware();
+        }
+        return this.middleware.find((m) => SCHEMA_REGISTRY in m);
+    }
+    // ===========================================================================
+    // Nested Route API
+    // ===========================================================================
+    /**
+     * Procedure registry for route resolution.
+     * Uses global registry by default.
+     */
+    procedureRegistry = PROCEDURE_REGISTRY;
+    /**
+     * Route resolver instance (lazy initialized).
+     */
+    routeResolver;
+    /**
+     * Batch executor instance (lazy initialized).
+     */
+    batchExecutor;
+    /**
+     * Set a custom procedure registry for this client.
+     *
+     * @param registry - Procedure registry to use
+     * @returns this (for chaining)
+     */
+    useRegistry(registry) {
+        this.procedureRegistry = registry;
+        this.routeResolver = undefined; // Reset resolver
+        return this;
+    }
+    /**
+     * Set the event bus of the local procedures of this client (`ctx.bus`).
+     *
+     * @param bus - Event bus for the procedures
+     * @returns this (for chaining)
+     */
+    useBus(bus) {
+        this.bus = bus;
+        return this;
+    }
+    /**
+     * Make a call using the nested route API.
+     *
+     * This method supports:
+     * - Per-call middleware overrides
+     * - Batch execution with configurable strategies
+     * - Type-safe nested route structures
+     *
+     * @param request - Call request with route and options
+     * @returns Response mirroring the route structure
+     *
+     * @example
+     * ```typescript
+     * // Single route call
+     * const result = await client.route({
+     *   route: {
+     *     collections: {
+     *       users: {
+     *         get: { id: "123" }
+     *       }
+     *     }
+     *   }
+     * });
+     * // result.collections.users.get.data = { id: "123", name: "John" }
+     *
+     * // Batched call with middleware overrides
+     * const results = await client.route({
+     *   middlewares: {
+     *     retry: { attempts: 3 },
+     *     timeout: { ms: 5000 }
+     *   },
+     *   batch: { strategy: 'all' },
+     *   route: {
+     *     collections: {
+     *       users: { get: { id: "123" } },
+     *       orders: { list: { userId: "123" } }
+     *     },
+     *     weather: {
+     *       forecast: { city: "NYC", days: 5 }
+     *     }
+     *   }
+     * });
+     * ```
+     */
+    async route(request) {
+        const resolver = this.getRouteResolver();
+        const executor = this.getBatchExecutor();
+        // Resolve routes to procedures
+        const resolution = resolver.resolve(request.route);
+        if (!resolution.success) {
+            return buildResponse(this.resolutionFailure(resolution));
+        }
+        // Create execution context
+        const context = this.createExecutionContext(request);
+        // Execute routes
+        const batchConfig = request.batch ?? { strategy: "all" };
+        const result = await executor.executeBatch(resolution.resolved, context, batchConfig);
+        return result.response;
+    }
+    /**
+     * Make a streaming call using the nested route API.
+     *
+     * Returns an async iterator that yields results as they complete,
+     * plus a promise for the final complete response.
+     *
+     * @param request - Call request (batch.strategy should be 'stream')
+     * @returns Streaming response with iterator and completion promise
+     */
+    routeStream(request) {
+        const resolver = this.getRouteResolver();
+        const executor = this.getBatchExecutor();
+        const resolution = resolver.resolve(request.route);
+        if (!resolution.success) {
+            // Return error response immediately
+            const errorResults = this.resolutionFailure(resolution);
+            return {
+                results: (async function* () {
+                    for (const [path, result] of errorResults) {
+                        yield { path, result };
+                    }
+                })(),
+                complete: Promise.resolve(buildResponse(errorResults)),
+            };
+        }
+        const context = this.createExecutionContext(request);
+        const streamConfig = request.batch ?? { strategy: "stream" };
+        return executor.getStreamingResponse(resolution.resolved, context, streamConfig);
+    }
+    /**
+     * The results of a route that did not resolve: an error for each leaf that failed, and
+     * `SKIPPED` for every other leaf, also the leaves after a validation error. (Before, the leaves
+     * after a validation error were missing: deep dive CORE-14.)
+     */
+    resolutionFailure(resolution) {
+        const skipped = (path) => ({
+            success: false,
+            error: { code: "SKIPPED", message: "Skipped due to other route errors", retryable: false, path },
+        });
+        const results = resolution.errors.map((error) => [
+            error.path,
+            {
+                success: false,
+                error: {
+                    code: error.type === "not_found" ? "NOT_FOUND" : "VALIDATION_ERROR",
+                    message: error.message,
+                    retryable: false,
+                    path: error.path,
+                },
+            },
+        ]);
+        for (const resolved of resolution.resolved)
+            results.push([resolved.path, skipped(resolved.path)]);
+        for (const path of resolution.skipped)
+            results.push([path, skipped(path)]);
+        return results;
+    }
+    /**
+     * Get the route resolver (lazy initialization).
+     */
+    getRouteResolver() {
+        if (!this.routeResolver) {
+            this.routeResolver = new RouteResolver(this.procedureRegistry);
+        }
+        return this.routeResolver;
+    }
+    /**
+     * Get the batch executor (lazy initialization).
+     */
+    getBatchExecutor() {
+        if (!this.batchExecutor) {
+            this.batchExecutor = new BatchExecutor(this.executeProcedure.bind(this));
+        }
+        return this.batchExecutor;
+    }
+    /**
+     * Create execution context from call request.
+     */
+    createExecutionContext(request) {
+        // Merge context: parent chain -> client context -> middleware overrides. The override keys
+        // become the keys that the middleware reads (deep dive CORE-14). No internal key goes into
+        // the metadata: a handler sees it as ctx.metadata (deep dive CORE-10).
+        const effectiveContext = mergeContext(this.getEffectiveContext(), toMiddlewareContext(request.middlewares));
+        const context = {
+            metadata: {
+                ...this.defaultMetadata,
+                ...effectiveContext,
+            },
+        };
+        // Only set signal if provided (exactOptionalPropertyTypes)
+        if (request.signal) {
+            context.signal = request.signal;
+        }
+        return context;
+    }
+    /**
+     * Execute a single procedure call.
+     * Used by BatchExecutor.
+     *
+     * The `out` config of the route leaf chooses the result (BUGS-2026-07 H8):
+     * - sponge (the default): the value, or the last item of a stream (or `accumulate` of all items);
+     * - stream: `data` is an AsyncIterable of the items. The procedure starts when the reader reads.
+     *   With `bufferSize`, that many items are read ahead of the reader;
+     * - handlers: `progress` gets each item but the last, `complete` gets the last, `error` gets the error.
+     *
+     * A procedure with `outputMode: "batch"` returns an array: sponge gives the array, and stream
+     * gives each element.
+     */
+    async executeProcedure(resolved, context) {
+        const { path, outputConfig } = resolved;
+        try {
+            const items = this.routeItems(resolved, context);
+            if (isStreamConfig(outputConfig)) {
+                const elements = resolved.procedure.outputMode === "batch" ? batchElements(items) : items;
+                return { success: true, data: readAhead(elements, outputConfig.bufferSize ?? 0) };
+            }
+            if (isHandlerConfig(outputConfig)) {
+                return { success: true, data: await this.consumeWithHandlers(items, outputConfig, path) };
+            }
+            return { success: true, data: await this.sponge(items, outputConfig, path) };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: {
+                    code: error instanceof ClientError || error instanceof InvocationError ? error.code : "EXECUTION_ERROR",
+                    message: error instanceof Error ? error.message : String(error),
+                    retryable: error instanceof ClientError ? error.retryable : false,
+                    path,
+                },
+            };
+        }
+    }
+    /**
+     * The output items of a resolved route: from the local handler, or from the transport.
+     */
+    routeItems(resolved, context) {
+        const self = this;
+        const { path, procedure, input } = resolved;
+        return (async function* () {
+            if (procedure.handler) {
+                // The resolver validated the input already (not an asynchronous schema: see ResolvedRoute)
+                const options = {
+                    ...self.invokeOptions({ metadata: context.metadata, signal: context.signal }),
+                    inputValidated: resolved.inputValidated !== false,
+                };
+                yield* outputItems(await invokeProcedure(procedure, input, options));
+                return;
+            }
+            const callOptions = { context: context.metadata };
+            if (context.signal) {
+                callOptions.signal = context.signal;
+            }
+            yield* self.stream(self.pathToMethod(path), input, callOptions);
+        })();
+    }
+    /** The sponge mode: the last item, or `accumulate` of all items. */
+    async sponge(items, config, path) {
+        const accumulate = "type" in config && config.type === "sponge" ? config.accumulate : undefined;
+        const all = [];
+        let last;
+        for await (const item of items) {
+            last = { value: item };
+            if (accumulate)
+                all.push(item);
+        }
+        if (!last) {
+            throw new InvocationError("NO_OUTPUT", `Procedure gave no output: ${path.join(".")}`, path);
+        }
+        return accumulate ? accumulate(all.slice(0, -1), last.value) : last.value;
+    }
+    /** The handlers mode: `progress` for each item but the last, then `complete`, or `error`. */
+    async consumeWithHandlers(items, config, path) {
+        let previous;
+        try {
+            for await (const item of items) {
+                if (previous)
+                    await this.deliver(config.progress, previous.value);
+                previous = { value: item };
+            }
+        }
+        catch (error) {
+            await this.deliver(config.error, error instanceof Error ? error : new Error(String(error)));
+            throw error;
+        }
+        if (!previous) {
+            throw new InvocationError("NO_OUTPUT", `Procedure gave no output: ${path.join(".")}`, path);
+        }
+        await this.deliver(config.complete, previous.value);
+        return previous.value;
+    }
+    /** A handler callback gets the data: a function, or a procedure path (the data is its input). */
+    async deliver(callback, data) {
+        if (callback === undefined)
+            return;
+        if (Array.isArray(callback)) {
+            await this.execInternal(callback, data);
+            return;
+        }
+        await callback(data);
+    }
+    /**
+     * Convert procedure path to Method object.
+     */
+    pathToMethod(path) {
+        // The one mapping of every host (deep dive architecture review 3.3)
+        return pathToMethod(path);
+    }
+}
+//# sourceMappingURL=client.js.map