raffel 0.1.2

package/dist/server/builder.js

@@ -0,0 +1,1682 @@
+/**
+ * Server Builder Implementation
+ *
+ * Unified server builder with fluent API for multi-protocol support.
+ */
+import { createRegistry } from '../core/registry.js';
+import { createRouter } from '../core/router.js';
+import { createHttpAdapter } from '../adapters/http.js';
+import { createWebSocketAdapter } from '../adapters/websocket.js';
+import { createTcpAdapter } from '../adapters/tcp.js';
+import { createJsonRpcAdapter, createJsonRpcMiddleware } from '../adapters/jsonrpc.js';
+import { createGrpcAdapter } from '../adapters/grpc.js';
+import { createGraphQLAdapter, createGraphQLMiddleware } from '../graphql/index.js';
+import { getRouterModuleDefinition } from './router-module.js';
+import { createSchemaRegistry, createValidationInterceptor } from '../validation/index.js';
+import { createMetricRegistry, createMetricsInterceptor, startProcessMetricsCollection, } from '../metrics/index.js';
+import { createTracer, createTracingInterceptor } from '../tracing/index.js';
+import { createUSDHandlers } from '../docs/index.js';
+import { createDiscoveryWatcher, createRouteInterceptors, isDevelopment, generateResourceRoutes, } from './fs-routes/index.js';
+import { createLogger } from '../utils/logger.js';
+import { createProcedureBuilder, createStreamBuilder, createEventBuilder, createGroupBuilder, joinHandlerName, } from './handler-builders.js';
+import { createResourceBuilder } from './resource-builder.js';
+import { registerDiscoveredHandlers, resolveHooksForProcedure } from './discovery-utils.js';
+import { buildChannelOptions, joinBasePath } from './channel-utils.js';
+import { createRestMiddleware, createHttpOverrideMiddleware, logRestMiddlewareRegistered, createDocsRouteMiddleware, } from './rest-middleware.js';
+import { buildProtocolConfig } from './protocol-config.js';
+const logger = createLogger('server');
+/**
+ * Check if a value is an async iterable
+ */
+function isAsyncIterable(value) {
+    return value !== null && typeof value === 'object' && Symbol.asyncIterator in value;
+}
+/**
+ * Create a unified Raffel server
+ */
+export function createServer(options) {
+    const { port, host = '0.0.0.0', basePath = '/', cors = true, eventDelivery, websocket, jsonrpc, tcp, graphql, middleware, http: httpOptions, discovery, hotReload = isDevelopment(), providers: initialProviders, } = options;
+    // Core components
+    const registry = createRegistry();
+    const router = createRouter(registry, { eventDelivery });
+    const schemaRegistry = createSchemaRegistry();
+    // Discovery watcher for file-system handlers
+    let discoveryWatcher = null;
+    // Create discovery watcher if configured
+    if (discovery) {
+        discoveryWatcher = createDiscoveryWatcher({
+            discovery: discovery === true
+                ? { http: true, channels: true, rpc: true, streams: true, rest: true, resources: true, tcp: true, udp: true }
+                : discovery,
+            hotReload,
+            onLoad: (stats) => {
+                logger.info({
+                    http: stats.http,
+                    rpc: stats.rpc,
+                    streams: stats.streams,
+                    channels: stats.channels,
+                    rest: stats.rest,
+                    resources: stats.resources,
+                    tcp: stats.tcp,
+                    udp: stats.udp,
+                    duration: stats.duration,
+                }, `Discovered ${stats.total} handlers`);
+            },
+            onReload: async (result) => {
+                applyDiscoveryResult(result);
+                logger.info({ total: result.stats.total }, 'Handlers hot-reloaded');
+            },
+            onError: (err) => {
+                logger.error({ err }, 'Discovery loading error');
+            },
+        });
+    }
+    // Protocol configuration (from options)
+    const protocols = buildProtocolConfig({ websocket, jsonrpc, tcp, graphql });
+    // Global interceptors (from options + added via .use())
+    const globalInterceptors = middleware ? [...middleware] : [];
+    // Namespace-level interceptors (for shared middleware per protocol)
+    // These are persistent across getter calls, enabling shared middleware chains
+    const httpInterceptors = [];
+    const wsInterceptors = [];
+    const streamInterceptors = [];
+    const rpcInterceptors = [];
+    const tcpInterceptors = [];
+    const udpInterceptors = [];
+    // Global hooks configuration (added via .hooks())
+    let globalHooks = {};
+    // Create hooks resolver that uses current globalHooks state
+    const createHooksResolver = () => (name) => resolveHooksForProcedure(name, globalHooks);
+    // Active adapters
+    let httpServer = null;
+    let wsAdapter = null;
+    let jsonRpcAdapter = null;
+    let tcpAdapter = null;
+    let grpcAdapter = null;
+    let graphqlAdapter = null;
+    let graphqlMiddleware = null;
+    let graphqlSubscriptionServer = null;
+    // Metrics
+    let metricsConfig = null;
+    let metricsRegistry = null;
+    let processMetricsCleanup = null;
+    // Tracing
+    let tracingConfig = null;
+    let tracerInstance = null;
+    // USD Documentation
+    let usdDocsConfig = null;
+    let usdDocsHandlers = null;
+    // State
+    let running = false;
+    let addresses = null;
+    // Provider definitions (added via .provide() or options.providers)
+    const providerDefinitions = new Map();
+    const resolvedProviders = {};
+    // Initialize provider definitions from options
+    if (initialProviders) {
+        for (const [name, config] of Object.entries(initialProviders)) {
+            if (typeof config === 'function') {
+                providerDefinitions.set(name, { factory: config });
+            }
+            else {
+                providerDefinitions.set(name, config);
+            }
+        }
+    }
+    // Custom protocol handlers (added via .addTcpHandler()/.addUdpHandler())
+    const tcpHandlers = [];
+    const udpHandlers = [];
+    const tcpServers = [];
+    const udpServers = [];
+    // Channel definitions discovered from filesystem or added manually
+    const channelRegistry = new Map();
+    // REST resources for HTTP routing
+    const restResourceRegistry = [];
+    function registerChannel(channel) {
+        channelRegistry.set(channel.name, channel);
+    }
+    function registerRestResource(resource) {
+        // Store in registry for HTTP middleware
+        restResourceRegistry.push(resource);
+        for (const route of resource.routes) {
+            // HEAD and OPTIONS have both collection and item routes - differentiate them
+            const suffix = (route.operation === 'head' || route.operation === 'options')
+                ? (route.isCollection ? ':collection' : ':item')
+                : '';
+            const name = `${resource.name}.${route.operation}${suffix}`;
+            if (route.inputSchema || route.outputSchema) {
+                const schema = {};
+                if (route.inputSchema)
+                    schema.input = route.inputSchema;
+                if (route.outputSchema)
+                    schema.output = route.outputSchema;
+                schemaRegistry.register(name, schema);
+            }
+            registry.procedure(name, route.handler, {
+                interceptors: globalInterceptors.length > 0 ? [...globalInterceptors] : undefined,
+            });
+        }
+        logger.debug({ name: resource.name, routes: resource.routes.length }, 'Added REST resource');
+    }
+    function registerResource(resource) {
+        const routes = generateResourceRoutes([resource]);
+        for (const route of routes) {
+            const name = `${resource.name}.${route.operation}`;
+            registry.procedure(name, route.handler, {
+                interceptors: globalInterceptors.length > 0 ? [...globalInterceptors] : undefined,
+            });
+        }
+        logger.debug({ name: resource.name, operations: routes.length }, 'Added resource');
+    }
+    function registerTcpHandler(handler) {
+        tcpHandlers.push(handler);
+        logger.debug({ name: handler.name, port: handler.config.port }, 'Added TCP handler');
+    }
+    function registerUdpHandler(handler) {
+        udpHandlers.push(handler);
+        logger.debug({ name: handler.name, port: handler.config.port }, 'Added UDP handler');
+    }
+    function applyDiscoveryResult(result) {
+        registerDiscoveredHandlers(result, registry, schemaRegistry, globalInterceptors);
+        for (const channel of result.channels) {
+            registerChannel(channel);
+        }
+        for (const resource of result.restResources) {
+            registerRestResource(resource);
+        }
+        for (const resource of result.resources) {
+            registerResource(resource);
+        }
+        for (const handler of result.tcpHandlers) {
+            registerTcpHandler(handler);
+        }
+        for (const handler of result.udpHandlers) {
+            registerUdpHandler(handler);
+        }
+    }
+    /**
+     * Register an HTTP route (Hono-style).
+     * Creates a procedure with the method and path as name (e.g., `get:/users/:id`).
+     *
+     * Interceptor chain order:
+     * 1. Global interceptors (server.use())
+     * 2. HTTP namespace interceptors (server.http.use())
+     * 3. Route-specific interceptors (options.use)
+     * 4. Validation interceptor (prepended if schema provided)
+     */
+    function registerHttpRoute(method, path, optionsOrHandler, maybeHandler) {
+        // Parse overloaded arguments
+        const isOptionsObject = typeof optionsOrHandler === 'object' && optionsOrHandler !== null;
+        const options = isOptionsObject ? optionsOrHandler : {};
+        const handler = isOptionsObject ? maybeHandler : optionsOrHandler;
+        // Generate procedure name from method and path (e.g., "get:/users/:id")
+        const name = `${method.toLowerCase()}:${path}`;
+        // Build interceptors: global → namespace → route-specific
+        const interceptors = [...globalInterceptors, ...httpInterceptors, ...(options.use ?? [])];
+        // Register schema if provided
+        if (options.input || options.output) {
+            const schema = {};
+            if (options.input)
+                schema.input = options.input;
+            if (options.output)
+                schema.output = options.output;
+            schemaRegistry.register(name, schema);
+            interceptors.unshift(createValidationInterceptor(schema));
+        }
+        // Register as a procedure with HTTP metadata
+        registry.procedure(name, handler, {
+            summary: options.summary,
+            description: options.description,
+            tags: options.tags,
+            httpPath: path,
+            httpMethod: method,
+            interceptors: interceptors.length > 0 ? interceptors : undefined,
+        });
+        logger.debug({ name, path, method }, 'Added HTTP route');
+        return server;
+    }
+    const server = {
+        // === Protocol Configuration ===
+        enableWebSocket(path = '/') {
+            protocols.websocket = {
+                enabled: true,
+                options: { path },
+                shared: true,
+            };
+            return server;
+        },
+        websocket(opts) {
+            protocols.websocket = {
+                enabled: true,
+                options: opts,
+                shared: opts.port === undefined,
+            };
+            return server;
+        },
+        enableJsonRpc(path = '/rpc') {
+            protocols.jsonrpc = {
+                enabled: true,
+                options: { path },
+                shared: true,
+            };
+            return server;
+        },
+        jsonrpc(opts) {
+            protocols.jsonrpc = {
+                enabled: true,
+                options: opts,
+                shared: opts.port === undefined,
+            };
+            return server;
+        },
+        tcp(opts) {
+            protocols.tcp = {
+                enabled: true,
+                options: opts,
+            };
+            return server;
+        },
+        grpc(opts) {
+            protocols.grpc = {
+                enabled: true,
+                options: opts,
+            };
+            return server;
+        },
+        protocols(config) {
+            // WebSocket
+            if (config.websocket !== undefined && config.websocket !== false) {
+                if (config.websocket === true) {
+                    server.enableWebSocket('/ws');
+                }
+                else if (typeof config.websocket === 'string') {
+                    server.enableWebSocket(config.websocket);
+                }
+                else {
+                    server.websocket(config.websocket);
+                }
+            }
+            // JSON-RPC
+            if (config.jsonrpc !== undefined && config.jsonrpc !== false) {
+                if (config.jsonrpc === true) {
+                    server.enableJsonRpc('/rpc');
+                }
+                else if (typeof config.jsonrpc === 'string') {
+                    server.enableJsonRpc(config.jsonrpc);
+                }
+                else {
+                    server.jsonrpc(config.jsonrpc);
+                }
+            }
+            // Streams (SSE)
+            if (config.streams !== undefined && config.streams !== false) {
+                // Streams are enabled automatically when stream handlers are registered
+                // This is a marker for documentation and configuration
+                logger.debug({ streams: config.streams }, 'Streams protocol enabled');
+            }
+            // GraphQL
+            if (config.graphql !== undefined && config.graphql !== false) {
+                if (config.graphql === true) {
+                    server.enableGraphQL('/graphql');
+                }
+                else if (typeof config.graphql === 'string') {
+                    server.enableGraphQL(config.graphql);
+                }
+                else {
+                    server.configureGraphQL(config.graphql);
+                }
+            }
+            // TCP (requires full options)
+            if (config.tcp) {
+                server.tcp(config.tcp);
+            }
+            // gRPC (requires full options)
+            if (config.grpc) {
+                server.grpc(config.grpc);
+            }
+            logger.info({ protocols: Object.keys(config).filter((k) => config[k]) }, 'Protocols configured');
+            return server;
+        },
+        enableGraphQL(path = '/graphql') {
+            protocols.graphql = {
+                enabled: true,
+                options: { path },
+                shared: true,
+            };
+            return server;
+        },
+        configureGraphQL(opts) {
+            protocols.graphql = {
+                enabled: true,
+                options: opts,
+                shared: opts.port === undefined,
+            };
+            return server;
+        },
+        // === Metrics ===
+        enableMetrics(config = {}) {
+            metricsConfig = {
+                enabled: config.enabled ?? true,
+                endpoint: config.endpoint ?? '/metrics',
+                defaultLabels: config.defaultLabels,
+                collectRequestMetrics: config.collectRequestMetrics ?? true,
+                collectProcessMetrics: config.collectProcessMetrics ?? false,
+            };
+            // Create registry immediately so it's available for custom metrics
+            metricsRegistry = createMetricRegistry();
+            if (metricsConfig.defaultLabels) {
+                metricsRegistry.setDefaultLabels(metricsConfig.defaultLabels);
+            }
+            return server;
+        },
+        // === Tracing ===
+        enableTracing(config = {}) {
+            tracingConfig = {
+                enabled: config.enabled ?? true,
+                serviceName: config.serviceName ?? 'raffel',
+                sampleRate: config.sampleRate ?? 1.0,
+                rateLimit: config.rateLimit ?? 0,
+                exporters: config.exporters ?? [],
+                batchSize: config.batchSize ?? 100,
+                batchTimeout: config.batchTimeout ?? 5000,
+                defaultAttributes: config.defaultAttributes ?? {},
+            };
+            // Create tracer immediately so it's available
+            tracerInstance = createTracer(tracingConfig);
+            return server;
+        },
+        // === USD Documentation ===
+        enableUSD(config = {}) {
+            usdDocsConfig = {
+                basePath: config.basePath ?? '/docs',
+                info: config.info,
+                servers: config.servers,
+                protocols: config.protocols,
+                securitySchemes: config.securitySchemes,
+                defaultSecurity: config.defaultSecurity,
+                tags: config.tags,
+                externalDocs: config.externalDocs,
+                ui: config.ui,
+                includeErrorSchemas: config.includeErrorSchemas,
+                includeStreamEventSchemas: config.includeStreamEventSchemas,
+                jsonrpc: config.jsonrpc,
+                grpc: config.grpc,
+            };
+            logger.info({ basePath: usdDocsConfig.basePath, protocols: usdDocsConfig.protocols ?? 'auto' }, 'USD Documentation enabled');
+            return server;
+        },
+        // === Providers ===
+        provide(name, factory, options) {
+            providerDefinitions.set(name, {
+                factory: factory,
+                onShutdown: options?.onShutdown,
+            });
+            return server;
+        },
+        // === Global Middleware ===
+        use(interceptor) {
+            globalInterceptors.push(interceptor);
+            return server;
+        },
+        // === Global Hooks ===
+        hooks(config) {
+            // Merge with existing hooks
+            if (config.before) {
+                globalHooks.before = { ...globalHooks.before, ...config.before };
+            }
+            if (config.after) {
+                globalHooks.after = { ...globalHooks.after, ...config.after };
+            }
+            if (config.error) {
+                globalHooks.error = { ...globalHooks.error, ...config.error };
+            }
+            return server;
+        },
+        // === Handler Registration ===
+        procedure(nameOrHandler, handler, opts) {
+            // Direct registration (backwards compatible)
+            if (typeof handler === 'function') {
+                // Include global interceptors for direct registration
+                const interceptors = [...globalInterceptors, ...(opts?.interceptors ?? [])];
+                registry.procedure(nameOrHandler, handler, {
+                    ...opts,
+                    interceptors: interceptors.length > 0 ? interceptors : undefined,
+                });
+                return;
+            }
+            // Fluent builder with hooks resolver
+            return createProcedureBuilder(registry, schemaRegistry, nameOrHandler, [...globalInterceptors], createHooksResolver());
+        },
+        stream(name) {
+            return createStreamBuilder(registry, schemaRegistry, name, [...globalInterceptors]);
+        },
+        event(name) {
+            return createEventBuilder(registry, schemaRegistry, name, [...globalInterceptors]);
+        },
+        resource(name, outputSchema, basePath) {
+            return createResourceBuilder({
+                registry,
+                schemaRegistry,
+                name,
+                basePath: basePath ?? `/${name}`,
+                outputSchema,
+                inheritedInterceptors: [...globalInterceptors],
+                tags: [name],
+            });
+        },
+        // === HTTP Routes (Hono-style) ===
+        get(path, optionsOrHandler, maybeHandler) {
+            return registerHttpRoute('GET', path, optionsOrHandler, maybeHandler);
+        },
+        post(path, optionsOrHandler, maybeHandler) {
+            return registerHttpRoute('POST', path, optionsOrHandler, maybeHandler);
+        },
+        put(path, optionsOrHandler, maybeHandler) {
+            return registerHttpRoute('PUT', path, optionsOrHandler, maybeHandler);
+        },
+        patch(path, optionsOrHandler, maybeHandler) {
+            return registerHttpRoute('PATCH', path, optionsOrHandler, maybeHandler);
+        },
+        delete(path, optionsOrHandler, maybeHandler) {
+            return registerHttpRoute('DELETE', path, optionsOrHandler, maybeHandler);
+        },
+        options(path, optionsOrHandler, maybeHandler) {
+            return registerHttpRoute('OPTIONS', path, optionsOrHandler, maybeHandler);
+        },
+        head(path, optionsOrHandler, maybeHandler) {
+            return registerHttpRoute('HEAD', path, optionsOrHandler, maybeHandler);
+        },
+        // === Declarative Registration ===
+        procedures(map) {
+            for (const [name, def] of Object.entries(map)) {
+                // Parse http config
+                let httpPath;
+                let httpMethod;
+                if (def.http) {
+                    if (typeof def.http === 'string') {
+                        httpPath = def.http;
+                        httpMethod = 'POST'; // default
+                    }
+                    else if (Array.isArray(def.http)) {
+                        ;
+                        [httpMethod, httpPath] = def.http;
+                    }
+                    else {
+                        httpPath = def.http.path;
+                        httpMethod = def.http.method ?? 'POST';
+                    }
+                }
+                // Build interceptors
+                const interceptors = [...globalInterceptors, ...(def.use ?? [])];
+                // Register schema
+                if (def.input || def.output) {
+                    const schema = {};
+                    if (def.input)
+                        schema.input = def.input;
+                    if (def.output)
+                        schema.output = def.output;
+                    schemaRegistry.register(name, schema);
+                    interceptors.unshift(createValidationInterceptor(schema));
+                }
+                registry.procedure(name, def.handler, {
+                    summary: def.summary,
+                    description: def.description,
+                    tags: def.tags,
+                    httpPath,
+                    httpMethod,
+                    interceptors: interceptors.length > 0 ? interceptors : undefined,
+                });
+                logger.debug({ name, httpPath, httpMethod }, 'Added procedure from map');
+            }
+            return server;
+        },
+        resources(map) {
+            for (const [name, def] of Object.entries(map)) {
+                const basePath = def.basePath ?? `/${name}`;
+                const tags = def.tags ?? [name];
+                const baseInterceptors = [...globalInterceptors, ...(def.use ?? [])];
+                // Helper to register an operation
+                const registerOp = (opName, handler, method, path, inputSchema) => {
+                    const procedureName = `${name}.${opName}`;
+                    const interceptors = [...baseInterceptors];
+                    if (inputSchema || def.schema) {
+                        const schema = {};
+                        if (inputSchema)
+                            schema.input = inputSchema;
+                        if (def.schema)
+                            schema.output = def.schema;
+                        schemaRegistry.register(procedureName, schema);
+                        if (inputSchema) {
+                            interceptors.unshift(createValidationInterceptor({ input: inputSchema }));
+                        }
+                    }
+                    registry.procedure(procedureName, handler, {
+                        tags,
+                        httpPath: path,
+                        httpMethod: method,
+                        summary: `${opName.charAt(0).toUpperCase() + opName.slice(1)} ${name}`,
+                        interceptors: interceptors.length > 0 ? interceptors : undefined,
+                    });
+                };
+                // Register standard operations
+                if (def.list) {
+                    const listDef = def.list;
+                    if (typeof listDef === 'function') {
+                        registerOp('list', listDef, 'GET', basePath, undefined);
+                    }
+                    else {
+                        registerOp('list', listDef.handler, 'GET', basePath, listDef.input);
+                    }
+                }
+                if (def.get) {
+                    registerOp('get', async (input, ctx) => def.get(input.id, ctx), 'GET', `${basePath}/:id`);
+                }
+                if (def.create) {
+                    const createDef = def.create;
+                    if (typeof createDef === 'function') {
+                        registerOp('create', createDef, 'POST', basePath, undefined);
+                    }
+                    else {
+                        registerOp('create', createDef.handler, 'POST', basePath, createDef.input);
+                    }
+                }
+                if (def.update) {
+                    const updateDef = def.update;
+                    if (typeof updateDef === 'function') {
+                        const handler = async (input, ctx) => updateDef(input.id, input, ctx);
+                        registerOp('update', handler, 'PUT', `${basePath}/:id`, undefined);
+                    }
+                    else {
+                        const handler = async (input, ctx) => updateDef.handler(input.id, input, ctx);
+                        registerOp('update', handler, 'PUT', `${basePath}/:id`, updateDef.input);
+                    }
+                }
+                if (def.patch) {
+                    const patchDef = def.patch;
+                    if (typeof patchDef === 'function') {
+                        const handler = async (input, ctx) => patchDef(input.id, input, ctx);
+                        registerOp('patch', handler, 'PATCH', `${basePath}/:id`, undefined);
+                    }
+                    else {
+                        const handler = async (input, ctx) => patchDef.handler(input.id, input, ctx);
+                        registerOp('patch', handler, 'PATCH', `${basePath}/:id`, patchDef.input);
+                    }
+                }
+                if (def.delete) {
+                    registerOp('delete', async (input, ctx) => def.delete(input.id, ctx), 'DELETE', `${basePath}/:id`);
+                }
+                // Register custom actions
+                if (def.actions) {
+                    for (const [actionName, action] of Object.entries(def.actions)) {
+                        registerOp(actionName, action.handler, 'POST', `${basePath}/${actionName}`, action.input);
+                    }
+                }
+                // Register item actions
+                if (def.itemActions) {
+                    for (const [actionName, action] of Object.entries(def.itemActions)) {
+                        const isObj = typeof action === 'object' && 'handler' in action;
+                        const handler = isObj
+                            ? async (input, ctx) => action.handler(input.id, input, ctx)
+                            : async (input, ctx) => action(input.id, ctx);
+                        const inputSchema = isObj ? action.input : undefined;
+                        registerOp(actionName, handler, 'POST', `${basePath}/:id/${actionName}`, inputSchema);
+                    }
+                }
+                logger.debug({ name, basePath, operations: Object.keys(def).length }, 'Added resource from map');
+            }
+            return server;
+        },
+        // === Grouping ===
+        group(prefix) {
+            return createGroupBuilder(registry, schemaRegistry, prefix, [...globalInterceptors], createHooksResolver());
+        },
+        mount(prefix, module, options = {}) {
+            const definition = getRouterModuleDefinition(module);
+            const mountInterceptors = options.interceptors ?? [];
+            for (const route of definition.routes) {
+                const fullName = joinHandlerName(prefix, route.name);
+                const interceptors = [
+                    ...(route.kind === 'procedure' && route.schema
+                        ? [createValidationInterceptor(route.schema)]
+                        : []),
+                    ...globalInterceptors,
+                    ...mountInterceptors,
+                    ...route.moduleInterceptors,
+                    ...route.interceptors,
+                ];
+                if (route.schema) {
+                    schemaRegistry.register(fullName, route.schema);
+                }
+                if (route.kind === 'procedure') {
+                    registry.procedure(fullName, route.handler, {
+                        summary: route.summary,
+                        description: route.description,
+                        tags: route.tags,
+                        graphql: route.graphql,
+                        httpPath: route.httpPath,
+                        httpMethod: route.httpMethod,
+                        jsonrpc: route.jsonrpc,
+                        grpc: route.grpc,
+                        interceptors: interceptors.length > 0 ? interceptors : undefined,
+                    });
+                }
+                else if (route.kind === 'stream') {
+                    registry.stream(fullName, route.handler, {
+                        description: route.description,
+                        direction: route.streamDirection,
+                        interceptors: interceptors.length > 0 ? interceptors : undefined,
+                    });
+                }
+                else {
+                    registry.event(fullName, route.handler, {
+                        description: route.description,
+                        delivery: route.delivery,
+                        retryPolicy: route.retryPolicy,
+                        deduplicationWindow: route.deduplicationWindow,
+                        interceptors: interceptors.length > 0 ? interceptors : undefined,
+                    });
+                }
+            }
+            return server;
+        },
+        // === Programmatic Registration ===
+        addProcedure(input) {
+            // Normalize input (LoadedRoute has 'handler' directly, AddProcedureInput also has 'handler')
+            const name = input.name;
+            const handler = input.handler;
+            const inputSchema = input.inputSchema;
+            const outputSchema = input.outputSchema;
+            const summary = 'meta' in input ? input.meta?.summary : input.summary;
+            const description = 'meta' in input ? input.meta?.description : input.description;
+            const tags = 'meta' in input ? input.meta?.tags : input.tags;
+            const graphql = 'meta' in input ? input.meta?.graphql : input.graphql;
+            const httpPath = 'meta' in input ? input.meta?.httpPath : input.httpPath;
+            const httpMethod = 'meta' in input ? input.meta?.httpMethod : input.httpMethod;
+            const jsonrpc = 'meta' in input ? input.meta?.jsonrpc : input.jsonrpc;
+            const grpc = 'meta' in input ? input.meta?.grpc : input.grpc;
+            const routeInterceptors = 'middlewares' in input ? createRouteInterceptors(input) : [];
+            const inputInterceptors = 'interceptors' in input ? input.interceptors ?? [] : [];
+            const interceptors = [...globalInterceptors, ...routeInterceptors, ...inputInterceptors];
+            // Register schema if defined
+            if (inputSchema || outputSchema) {
+                const schema = {};
+                if (inputSchema)
+                    schema.input = inputSchema;
+                if (outputSchema)
+                    schema.output = outputSchema;
+                schemaRegistry.register(name, schema);
+                interceptors.unshift(createValidationInterceptor(schema));
+            }
+            registry.procedure(name, handler, {
+                summary,
+                description,
+                tags,
+                graphql,
+                httpPath,
+                httpMethod,
+                jsonrpc,
+                grpc,
+                interceptors: interceptors.length > 0 ? interceptors : undefined,
+            });
+            logger.debug({ name }, 'Added procedure');
+            return server;
+        },
+        addStream(input) {
+            const name = input.name;
+            const handler = input.handler;
+            const inputSchema = input.inputSchema;
+            const outputSchema = input.outputSchema;
+            const description = 'meta' in input ? input.meta?.description : input.description;
+            const direction = 'meta' in input ? input.meta?.direction : input.direction;
+            const routeInterceptors = 'middlewares' in input ? createRouteInterceptors(input) : [];
+            const inputInterceptors = 'interceptors' in input ? input.interceptors ?? [] : [];
+            const interceptors = [...globalInterceptors, ...routeInterceptors, ...inputInterceptors];
+            if (inputSchema || outputSchema) {
+                const schema = {};
+                if (inputSchema)
+                    schema.input = inputSchema;
+                if (outputSchema)
+                    schema.output = outputSchema;
+                schemaRegistry.register(name, schema);
+            }
+            registry.stream(name, handler, {
+                description,
+                direction,
+                interceptors: interceptors.length > 0 ? interceptors : undefined,
+            });
+            logger.debug({ name }, 'Added stream');
+            return server;
+        },
+        addEvent(input) {
+            const name = input.name;
+            const handler = input.handler;
+            const inputSchema = input.inputSchema;
+            const description = 'meta' in input ? input.meta?.description : input.description;
+            const delivery = 'meta' in input ? input.meta?.delivery : input.delivery;
+            const retryPolicy = 'meta' in input ? input.meta?.retryPolicy : input.retryPolicy;
+            const deduplicationWindow = 'meta' in input ? input.meta?.deduplicationWindow : input.deduplicationWindow;
+            const routeInterceptors = 'middlewares' in input ? createRouteInterceptors(input) : [];
+            const inputInterceptors = 'interceptors' in input ? input.interceptors ?? [] : [];
+            const interceptors = [...globalInterceptors, ...routeInterceptors, ...inputInterceptors];
+            if (inputSchema) {
+                schemaRegistry.register(name, { input: inputSchema });
+            }
+            registry.event(name, handler, {
+                description,
+                delivery,
+                retryPolicy,
+                deduplicationWindow,
+                interceptors: interceptors.length > 0 ? interceptors : undefined,
+            });
+            logger.debug({ name }, 'Added event');
+            return server;
+        },
+        addChannel(channel) {
+            registerChannel(channel);
+            logger.debug({ name: channel.name }, 'Channel configuration registered');
+            return server;
+        },
+        addRest(resource) {
+            registerRestResource(resource);
+            return server;
+        },
+        addResource(resource) {
+            registerResource(resource);
+            return server;
+        },
+        addTcpHandler(handler) {
+            registerTcpHandler(handler);
+            return server;
+        },
+        addUdpHandler(handler) {
+            registerUdpHandler(handler);
+            return server;
+        },
+        addDiscovery(result) {
+            applyDiscoveryResult(result);
+            logger.debug({
+                routes: result.routes.length,
+                channels: result.channels.length,
+                rest: result.restResources.length,
+                resources: result.resources.length,
+                tcp: result.tcpHandlers.length,
+                udp: result.udpHandlers.length,
+            }, 'Added discovery result');
+            return server;
+        },
+        // === Lifecycle ===
+        async start() {
+            if (running) {
+                throw new Error('Server is already running');
+            }
+            // Initialize providers
+            if (providerDefinitions.size > 0) {
+                logger.debug({ count: providerDefinitions.size }, 'Initializing providers');
+                for (const [name, definition] of providerDefinitions) {
+                    try {
+                        const instance = await definition.factory();
+                        resolvedProviders[name] = instance;
+                        logger.debug({ name }, 'Provider initialized');
+                    }
+                    catch (err) {
+                        logger.error({ err, name }, 'Failed to initialize provider');
+                        throw err;
+                    }
+                }
+                // Add interceptor to inject providers into context
+                globalInterceptors.unshift(async (_env, ctx, next) => {
+                    // Inject all providers into context
+                    const ctxAny = ctx;
+                    for (const [name, instance] of Object.entries(resolvedProviders)) {
+                        ctxAny[name] = instance;
+                    }
+                    return next();
+                });
+            }
+            // Initialize metrics if enabled
+            if (metricsConfig?.enabled && metricsRegistry) {
+                logger.debug({ endpoint: metricsConfig.endpoint }, 'Initializing metrics');
+                // Add request metrics interceptor
+                if (metricsConfig.collectRequestMetrics) {
+                    globalInterceptors.unshift(createMetricsInterceptor(metricsRegistry));
+                }
+                // Start process metrics collection
+                if (metricsConfig.collectProcessMetrics) {
+                    processMetricsCleanup = startProcessMetricsCollection(metricsRegistry);
+                }
+                // Register /metrics endpoint as a procedure
+                const metricsEndpointName = `__metrics__`;
+                registry.procedure(metricsEndpointName, async () => {
+                    return metricsRegistry.export('prometheus');
+                });
+                logger.info({ endpoint: metricsConfig.endpoint }, 'Metrics enabled');
+            }
+            // Initialize tracing if enabled
+            if (tracingConfig?.enabled && tracerInstance) {
+                logger.debug({
+                    serviceName: tracingConfig.serviceName,
+                    sampleRate: tracingConfig.sampleRate,
+                }, 'Initializing tracing');
+                // Add tracing interceptor (should be first to capture full request duration)
+                globalInterceptors.unshift(createTracingInterceptor(tracerInstance));
+                logger.info({
+                    serviceName: tracingConfig.serviceName,
+                    sampleRate: tracingConfig.sampleRate,
+                    exporters: tracingConfig.exporters?.length ?? 0,
+                }, 'Tracing enabled');
+            }
+            // Load file-system handlers first (before starting adapters)
+            if (discoveryWatcher) {
+                const result = await discoveryWatcher.start();
+                applyDiscoveryResult(result);
+            }
+            addresses = {
+                http: { host, port },
+            };
+            // Build HTTP middleware list
+            const httpMiddleware = [];
+            if (httpOptions?.middleware?.length) {
+                httpMiddleware.push(...httpOptions.middleware);
+            }
+            // Add USD Documentation handlers if enabled
+            if (usdDocsConfig) {
+                usdDocsHandlers = createUSDHandlers({
+                    registry,
+                    schemaRegistry,
+                    channels: channelRegistry,
+                    restResources: restResourceRegistry,
+                    tcpHandlers,
+                    udpHandlers,
+                    protocolConfig: protocols,
+                }, {
+                    basePath: usdDocsConfig.basePath ?? '/docs',
+                    info: usdDocsConfig.info,
+                    servers: usdDocsConfig.servers,
+                    protocols: usdDocsConfig.protocols,
+                    securitySchemes: usdDocsConfig.securitySchemes,
+                    defaultSecurity: usdDocsConfig.defaultSecurity,
+                    tags: usdDocsConfig.tags,
+                    externalDocs: usdDocsConfig.externalDocs,
+                    ui: usdDocsConfig.ui,
+                    includeErrorSchemas: usdDocsConfig.includeErrorSchemas,
+                    includeStreamEventSchemas: usdDocsConfig.includeStreamEventSchemas,
+                    jsonrpc: usdDocsConfig.jsonrpc,
+                    grpc: usdDocsConfig.grpc,
+                });
+                // Create Hono middleware for USD routes
+                const usdBasePath = usdDocsConfig.basePath ?? '/docs';
+                httpMiddleware.push(createDocsRouteMiddleware([
+                    { method: 'GET', path: usdBasePath, handler: usdDocsHandlers.serveUI },
+                    { method: 'GET', path: `${usdBasePath}/usd.json`, handler: usdDocsHandlers.serveUSD },
+                    { method: 'GET', path: `${usdBasePath}/usd.yaml`, handler: usdDocsHandlers.serveUSDYaml },
+                    { method: 'GET', path: `${usdBasePath}/openapi.json`, handler: usdDocsHandlers.serveOpenAPI },
+                ]));
+                logger.info({ basePath: usdBasePath }, 'USD Documentation middleware registered');
+            }
+            httpMiddleware.push(createHttpOverrideMiddleware({
+                router,
+                registry,
+                basePath,
+                maxBodySize: httpOptions?.maxBodySize ?? 1024 * 1024,
+                contextFactory: httpOptions?.contextFactory,
+                codecs: httpOptions?.codecs,
+            }));
+            // Add REST middleware for proper HTTP verb routing
+            if (restResourceRegistry.length > 0) {
+                httpMiddleware.push(createRestMiddleware({
+                    restResources: restResourceRegistry,
+                    router,
+                    basePath,
+                    maxBodySize: httpOptions?.maxBodySize ?? 1024 * 1024,
+                    contextFactory: httpOptions?.contextFactory,
+                    codecs: httpOptions?.codecs,
+                }));
+                logRestMiddlewareRegistered(restResourceRegistry.length);
+            }
+            // Add JSON-RPC middleware when sharing the HTTP port
+            if (protocols.jsonrpc?.enabled && protocols.jsonrpc.shared) {
+                const rpcOpts = protocols.jsonrpc.options;
+                const rpcPath = rpcOpts.path || '/rpc';
+                const sharedRpcPath = joinBasePath(basePath, rpcPath);
+                httpMiddleware.push(createJsonRpcMiddleware(router, {
+                    path: sharedRpcPath,
+                    timeout: rpcOpts.timeout,
+                    maxBodySize: rpcOpts.maxBodySize,
+                    cors: false,
+                    codecs: rpcOpts.codecs,
+                }));
+            }
+            // Add GraphQL middleware when sharing the HTTP port
+            if (protocols.graphql?.enabled && protocols.graphql.shared) {
+                const gqlOpts = protocols.graphql.options;
+                const gqlPath = gqlOpts.path || '/graphql';
+                const sharedGqlPath = joinBasePath(basePath, gqlPath);
+                const isDev = isDevelopment();
+                graphqlMiddleware = createGraphQLMiddleware({
+                    router,
+                    registry,
+                    schemaRegistry,
+                    config: {
+                        ...gqlOpts,
+                        path: sharedGqlPath,
+                        playground: gqlOpts.playground ?? isDev,
+                        introspection: gqlOpts.introspection ?? isDev,
+                        timeout: gqlOpts.timeout ?? 30000,
+                        maxBodySize: gqlOpts.maxBodySize ?? 1024 * 1024,
+                    },
+                });
+                httpMiddleware.push(graphqlMiddleware.middleware);
+                graphqlAdapter = {
+                    async start() {
+                        if (!httpServer?.server)
+                            return;
+                        graphqlSubscriptionServer = graphqlMiddleware?.createSubscriptionServer(httpServer.server) ?? null;
+                    },
+                    async stop() {
+                        if (graphqlSubscriptionServer) {
+                            graphqlSubscriptionServer.close();
+                            graphqlSubscriptionServer = null;
+                        }
+                    },
+                    get schema() {
+                        return graphqlMiddleware.schema;
+                    },
+                    get schemaInfo() {
+                        return graphqlMiddleware.schemaInfo;
+                    },
+                    get address() {
+                        return { host, port, path: sharedGqlPath };
+                    },
+                };
+            }
+            // Start HTTP adapter (always)
+            httpServer = createHttpAdapter(router, {
+                port,
+                host,
+                basePath,
+                maxBodySize: httpOptions?.maxBodySize,
+                contextFactory: httpOptions?.contextFactory,
+                codecs: httpOptions?.codecs,
+                cors: cors === true
+                    ? {
+                        origin: '*',
+                        methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
+                        headers: ['Content-Type', 'Authorization', 'Accept', 'X-Request-Id', 'Traceparent', 'Tracestate'],
+                    }
+                    : cors,
+                middleware: httpMiddleware.length > 0 ? httpMiddleware : undefined,
+            });
+            await httpServer.start();
+            // Start WebSocket adapter
+            if (protocols.websocket?.enabled) {
+                const wsOpts = protocols.websocket.options;
+                const channels = buildChannelOptions(channelRegistry, wsOpts.channels);
+                if (protocols.websocket.shared) {
+                    // Share HTTP port - attach to HTTP server
+                    wsAdapter = createWebSocketAdapter(router, {
+                        host,
+                        port,
+                        server: httpServer.server ?? undefined,
+                        path: wsOpts.path || '/',
+                        maxPayloadSize: wsOpts.maxPayloadSize,
+                        heartbeatInterval: wsOpts.heartbeatInterval,
+                        channels,
+                        contextFactory: wsOpts.contextFactory,
+                    });
+                    addresses.websocket = { host, port, path: wsOpts.path || '/', shared: true };
+                }
+                else {
+                    wsAdapter = createWebSocketAdapter(router, {
+                        port: wsOpts.port,
+                        host,
+                        path: wsOpts.path || '/',
+                        maxPayloadSize: wsOpts.maxPayloadSize,
+                        heartbeatInterval: wsOpts.heartbeatInterval,
+                        channels,
+                        contextFactory: wsOpts.contextFactory,
+                    });
+                    addresses.websocket = { host, port: wsOpts.port, path: wsOpts.path || '/', shared: false };
+                }
+                await wsAdapter.start();
+            }
+            // Start JSON-RPC adapter
+            if (protocols.jsonrpc?.enabled) {
+                const rpcOpts = protocols.jsonrpc.options;
+                if (protocols.jsonrpc.shared) {
+                    const rpcPath = rpcOpts.path || '/rpc';
+                    addresses.jsonrpc = { host, port, path: joinBasePath(basePath, rpcPath), shared: true };
+                }
+                else {
+                    jsonRpcAdapter = createJsonRpcAdapter(router, {
+                        port: rpcOpts.port,
+                        host,
+                        path: rpcOpts.path || '/rpc',
+                        timeout: rpcOpts.timeout,
+                        maxBodySize: rpcOpts.maxBodySize,
+                    });
+                    addresses.jsonrpc = { host, port: rpcOpts.port, path: rpcOpts.path || '/rpc', shared: false };
+                    await jsonRpcAdapter.start();
+                }
+            }
+            // Start TCP adapter
+            if (protocols.tcp?.enabled) {
+                const tcpOpts = protocols.tcp.options;
+                tcpAdapter = createTcpAdapter(router, {
+                    port: tcpOpts.port,
+                    host: tcpOpts.host || host,
+                    maxMessageSize: tcpOpts.maxMessageSize,
+                    keepAliveInterval: tcpOpts.keepAliveInterval,
+                });
+                await tcpAdapter.start();
+                addresses.tcp = { host: tcpOpts.host || host, port: tcpOpts.port };
+            }
+            // Start gRPC adapter
+            if (protocols.grpc?.enabled) {
+                const grpcOpts = protocols.grpc.options;
+                grpcAdapter = createGrpcAdapter(router, {
+                    host: grpcOpts.host || host,
+                    port: grpcOpts.port,
+                    protoPath: grpcOpts.protoPath,
+                    packageName: grpcOpts.packageName,
+                    serviceNames: grpcOpts.serviceNames,
+                    loaderOptions: grpcOpts.loaderOptions,
+                    tls: grpcOpts.tls,
+                    maxReceiveMessageLength: grpcOpts.maxReceiveMessageLength,
+                    maxSendMessageLength: grpcOpts.maxSendMessageLength,
+                });
+                await grpcAdapter.start();
+                if (grpcAdapter.address) {
+                    addresses.grpc = grpcAdapter.address;
+                }
+                else {
+                    addresses.grpc = { host: grpcOpts.host || host, port: grpcOpts.port };
+                }
+            }
+            // Start GraphQL adapter
+            if (protocols.graphql?.enabled) {
+                const gqlOpts = protocols.graphql.options;
+                const gqlPath = gqlOpts.path || '/graphql';
+                if (protocols.graphql.shared) {
+                    if (graphqlAdapter) {
+                        await graphqlAdapter.start();
+                    }
+                    addresses.graphql = { host, port, path: joinBasePath(basePath, gqlPath), shared: true };
+                }
+                else {
+                    const isDev = isDevelopment();
+                    graphqlAdapter = createGraphQLAdapter({
+                        router,
+                        registry,
+                        schemaRegistry,
+                        host,
+                        port: gqlOpts.port,
+                        config: {
+                            ...gqlOpts,
+                            path: gqlPath,
+                            playground: gqlOpts.playground ?? isDev,
+                            introspection: gqlOpts.introspection ?? isDev,
+                            timeout: gqlOpts.timeout ?? 30000,
+                            maxBodySize: gqlOpts.maxBodySize ?? 1024 * 1024,
+                        },
+                    });
+                    await graphqlAdapter.start();
+                    addresses.graphql = { host, port: gqlOpts.port, path: gqlPath, shared: false };
+                }
+            }
+            // Start custom TCP handlers (added via .addTcpHandler())
+            for (const handler of tcpHandlers) {
+                const { createTcpServer } = await import('./fs-routes/tcp/index.js');
+                const tcpServer = createTcpServer(handler);
+                await tcpServer.start();
+                tcpServers.push(tcpServer);
+                logger.info({ name: handler.name, port: handler.config.port }, 'TCP handler started');
+            }
+            // Start custom UDP handlers (added via .addUdpHandler())
+            for (const handler of udpHandlers) {
+                const { createUdpServer } = await import('./fs-routes/udp/index.js');
+                const udpServer = createUdpServer(handler);
+                await udpServer.start();
+                udpServers.push(udpServer);
+                logger.info({ name: handler.name, port: handler.config.port }, 'UDP handler started');
+            }
+            running = true;
+        },
+        async stop() {
+            if (!running)
+                return;
+            const stops = [];
+            if (tcpAdapter) {
+                stops.push(tcpAdapter.stop());
+                tcpAdapter = null;
+            }
+            if (jsonRpcAdapter) {
+                stops.push(jsonRpcAdapter.stop());
+                jsonRpcAdapter = null;
+            }
+            if (wsAdapter) {
+                stops.push(wsAdapter.stop());
+                wsAdapter = null;
+            }
+            if (httpServer) {
+                stops.push(httpServer.stop());
+                httpServer = null;
+            }
+            if (grpcAdapter) {
+                stops.push(grpcAdapter.stop());
+                grpcAdapter = null;
+            }
+            if (graphqlAdapter) {
+                stops.push(graphqlAdapter.stop());
+                graphqlAdapter = null;
+            }
+            await Promise.all(stops);
+            // Stop custom TCP servers
+            for (const tcpServer of tcpServers) {
+                await tcpServer.stop();
+            }
+            tcpServers.length = 0;
+            // Stop custom UDP servers
+            for (const udpServer of udpServers) {
+                await udpServer.stop();
+            }
+            udpServers.length = 0;
+            // Stop discovery watcher
+            if (discoveryWatcher) {
+                discoveryWatcher.stop();
+            }
+            // Stop process metrics collection
+            if (processMetricsCleanup) {
+                processMetricsCleanup();
+                processMetricsCleanup = null;
+            }
+            // Shutdown tracer (flush pending spans)
+            if (tracerInstance) {
+                await tracerInstance.shutdown();
+                tracerInstance = null;
+            }
+            // Shutdown providers
+            for (const [name, definition] of providerDefinitions) {
+                if (definition.onShutdown && resolvedProviders[name]) {
+                    try {
+                        await definition.onShutdown(resolvedProviders[name]);
+                        logger.debug({ name }, 'Provider shut down');
+                    }
+                    catch (err) {
+                        logger.error({ err, name }, 'Error shutting down provider');
+                    }
+                }
+            }
+            router.stop();
+            running = false;
+            addresses = null;
+        },
+        async restart() {
+            await server.stop();
+            await server.start();
+        },
+        // === Protocol Namespaces ===
+        get http() {
+            // Uses persistent httpInterceptors from outer scope for shared middleware chain
+            const httpNamespace = {
+                get(path, optionsOrHandler, maybeHandler) {
+                    registerHttpRoute('GET', path, optionsOrHandler, maybeHandler);
+                    return httpNamespace;
+                },
+                post(path, optionsOrHandler, maybeHandler) {
+                    registerHttpRoute('POST', path, optionsOrHandler, maybeHandler);
+                    return httpNamespace;
+                },
+                put(path, optionsOrHandler, maybeHandler) {
+                    registerHttpRoute('PUT', path, optionsOrHandler, maybeHandler);
+                    return httpNamespace;
+                },
+                patch(path, optionsOrHandler, maybeHandler) {
+                    registerHttpRoute('PATCH', path, optionsOrHandler, maybeHandler);
+                    return httpNamespace;
+                },
+                delete(path, optionsOrHandler, maybeHandler) {
+                    registerHttpRoute('DELETE', path, optionsOrHandler, maybeHandler);
+                    return httpNamespace;
+                },
+                options(path, optionsOrHandler, maybeHandler) {
+                    registerHttpRoute('OPTIONS', path, optionsOrHandler, maybeHandler);
+                    return httpNamespace;
+                },
+                head(path, optionsOrHandler, maybeHandler) {
+                    registerHttpRoute('HEAD', path, optionsOrHandler, maybeHandler);
+                    return httpNamespace;
+                },
+                use(interceptor) {
+                    httpInterceptors.push(interceptor);
+                    return httpNamespace;
+                },
+            };
+            return httpNamespace;
+        },
+        get ws() {
+            // Handler state for chained API - these are local since channel() consumes them
+            let subscribeHandler = null;
+            let messageHandler = null;
+            let unsubscribeHandler = null;
+            // Uses persistent wsInterceptors from outer scope for shared middleware chain
+            const wsNamespace = {
+                channel(channelName, options) {
+                    // Determine auth requirement based on type
+                    const authRequirement = options?.type === 'public' ? 'none' : 'required';
+                    // Wrap handlers to match ChannelExports signature
+                    const wrappedOnJoin = subscribeHandler
+                        ? (member, ctx) => subscribeHandler(channelName, ctx)
+                        : undefined;
+                    const wrappedOnLeave = unsubscribeHandler
+                        ? (member, ctx) => unsubscribeHandler(channelName, ctx)
+                        : undefined;
+                    // Register channel with the channel registry using correct LoadedChannel structure
+                    const channelDef = {
+                        name: channelName,
+                        filePath: '<programmatic>',
+                        config: {
+                            auth: authRequirement,
+                            onJoin: wrappedOnJoin,
+                            onLeave: wrappedOnLeave,
+                        },
+                    };
+                    channelRegistry.set(channelName, channelDef);
+                    logger.debug({ name: channelName, type: options?.type ?? 'public', auth: authRequirement }, 'Added WebSocket channel');
+                    return wsNamespace;
+                },
+                onSubscribe(handler) {
+                    subscribeHandler = handler;
+                    return wsNamespace;
+                },
+                onMessage(handler) {
+                    messageHandler = handler;
+                    return wsNamespace;
+                },
+                onUnsubscribe(handler) {
+                    unsubscribeHandler = handler;
+                    return wsNamespace;
+                },
+                use(interceptor) {
+                    wsInterceptors.push(interceptor);
+                    return wsNamespace;
+                },
+            };
+            return wsNamespace;
+        },
+        get streams() {
+            // Uses persistent streamInterceptors from outer scope for shared middleware chain
+            const streamsNamespace = {
+                source(name, optionsOrHandler, maybeHandler) {
+                    const isOptionsObject = typeof optionsOrHandler === 'object' && optionsOrHandler !== null && !isAsyncIterable(optionsOrHandler);
+                    const options = isOptionsObject ? optionsOrHandler : {};
+                    const handler = isOptionsObject ? maybeHandler : optionsOrHandler;
+                    // Register as a stream handler using the registry
+                    const streamName = `stream:${name}`;
+                    const interceptors = [...globalInterceptors, ...streamInterceptors];
+                    if (options.input) {
+                        const schema = { input: options.input };
+                        schemaRegistry.register(streamName, schema);
+                        interceptors.unshift(createValidationInterceptor(schema));
+                    }
+                    registry.stream(streamName, handler, {
+                        description: options.description,
+                        direction: 'server',
+                        interceptors: interceptors.length > 0 ? interceptors : undefined,
+                    });
+                    logger.debug({ name: streamName, path: options.path ?? `/${name}` }, 'Added stream source');
+                    return streamsNamespace;
+                },
+                sink(name, optionsOrHandler, maybeHandler) {
+                    const isOptionsObject = typeof optionsOrHandler === 'object' && optionsOrHandler !== null;
+                    const options = isOptionsObject ? optionsOrHandler : {};
+                    const handler = isOptionsObject ? maybeHandler : optionsOrHandler;
+                    const streamName = `stream:${name}`;
+                    const interceptors = [...globalInterceptors, ...streamInterceptors];
+                    if (options.input) {
+                        const schema = { input: options.input };
+                        schemaRegistry.register(streamName, schema);
+                        interceptors.unshift(createValidationInterceptor(schema));
+                    }
+                    registry.stream(streamName, handler, {
+                        description: options.description,
+                        direction: 'client',
+                        interceptors: interceptors.length > 0 ? interceptors : undefined,
+                    });
+                    logger.debug({ name: streamName, path: options.path ?? `/${name}` }, 'Added stream sink');
+                    return streamsNamespace;
+                },
+                duplex(name, optionsOrHandler, maybeHandler) {
+                    const isOptionsObject = typeof optionsOrHandler === 'object' && optionsOrHandler !== null;
+                    const options = isOptionsObject ? optionsOrHandler : {};
+                    const handler = isOptionsObject ? maybeHandler : optionsOrHandler;
+                    const streamName = `stream:${name}`;
+                    const interceptors = [...globalInterceptors, ...streamInterceptors];
+                    if (options.input) {
+                        const schema = { input: options.input };
+                        schemaRegistry.register(streamName, schema);
+                        interceptors.unshift(createValidationInterceptor(schema));
+                    }
+                    registry.stream(streamName, handler, {
+                        description: options.description,
+                        direction: 'bidi',
+                        interceptors: interceptors.length > 0 ? interceptors : undefined,
+                    });
+                    logger.debug({ name: streamName, path: options.path ?? `/${name}` }, 'Added stream duplex');
+                    return streamsNamespace;
+                },
+                use(interceptor) {
+                    streamInterceptors.push(interceptor);
+                    return streamsNamespace;
+                },
+            };
+            return streamsNamespace;
+        },
+        get rpc() {
+            // Uses persistent rpcInterceptors from outer scope for shared middleware chain
+            const registerRpcMethod = (name, optionsOrHandler, maybeHandler, isNotification = false) => {
+                const isOptionsObject = typeof optionsOrHandler === 'object' && optionsOrHandler !== null && typeof maybeHandler === 'function';
+                const options = isOptionsObject ? optionsOrHandler : {};
+                const handler = isOptionsObject ? maybeHandler : optionsOrHandler;
+                const interceptors = [...globalInterceptors, ...rpcInterceptors];
+                if (options.input) {
+                    const schema = { input: options.input, output: options.output };
+                    schemaRegistry.register(name, schema);
+                    interceptors.unshift(createValidationInterceptor(schema));
+                }
+                registry.procedure(name, handler, {
+                    description: options.description,
+                    tags: options.tags,
+                    jsonrpc: { notification: isNotification },
+                    interceptors: interceptors.length > 0 ? interceptors : undefined,
+                });
+                logger.debug({ name, notification: isNotification }, 'Added RPC method');
+            };
+            const rpcNamespace = {
+                method(name, optionsOrHandler, maybeHandler) {
+                    registerRpcMethod(name, optionsOrHandler, maybeHandler, false);
+                    return rpcNamespace;
+                },
+                notification(name, optionsOrHandler, maybeHandler) {
+                    registerRpcMethod(name, optionsOrHandler, maybeHandler, true);
+                    return rpcNamespace;
+                },
+                use(interceptor) {
+                    rpcInterceptors.push(interceptor);
+                    return rpcNamespace;
+                },
+            };
+            return rpcNamespace;
+        },
+        get tcpNs() {
+            // Uses persistent tcpInterceptors from outer scope for shared middleware chain
+            const tcpNamespace = {
+                handler(name, options) {
+                    let connectHandler;
+                    let dataHandler;
+                    let closeHandler;
+                    let errorHandler;
+                    const handlerBuilder = {
+                        onConnect(handler) {
+                            connectHandler = handler;
+                            return handlerBuilder;
+                        },
+                        onData(handler) {
+                            dataHandler = handler;
+                            return handlerBuilder;
+                        },
+                        onClose(handler) {
+                            closeHandler = handler;
+                            return handlerBuilder;
+                        },
+                        onError(handler) {
+                            errorHandler = handler;
+                            return handlerBuilder;
+                        },
+                        end() {
+                            // Build framing config if specified
+                            const framingConfig = options?.framing ? {
+                                type: options.framing,
+                                lengthBytes: 4,
+                                lengthEncoding: 'BE',
+                                maxMessageSize: 16 * 1024 * 1024,
+                                delimiter: options.delimiter ? Buffer.from(options.delimiter) : undefined,
+                            } : null;
+                            // Store TCP handler configuration for later startup
+                            const tcpHandler = {
+                                name,
+                                filePath: '<programmatic>',
+                                config: {
+                                    port: options?.port ?? 0,
+                                    host: options?.host ?? '0.0.0.0',
+                                    keepAlive: true,
+                                    keepAliveInitialDelay: 30000,
+                                    timeout: 0,
+                                    maxConnections: 0,
+                                    noDelay: true,
+                                    framing: framingConfig,
+                                },
+                                handlers: {
+                                    onConnect: connectHandler,
+                                    onData: dataHandler,
+                                    onClose: closeHandler,
+                                    onError: errorHandler,
+                                },
+                            };
+                            tcpHandlers.push(tcpHandler);
+                            logger.debug({ name, port: options?.port }, 'Added TCP handler');
+                            return tcpNamespace;
+                        },
+                    };
+                    return handlerBuilder;
+                },
+                use(interceptor) {
+                    tcpInterceptors.push(interceptor);
+                    return tcpNamespace;
+                },
+            };
+            return tcpNamespace;
+        },
+        get udp() {
+            // Uses persistent udpInterceptors from outer scope for shared middleware chain
+            const udpNamespace = {
+                handler(name, options) {
+                    let messageHandler;
+                    let errorHandler;
+                    const handlerBuilder = {
+                        onMessage(handler) {
+                            messageHandler = handler;
+                            return handlerBuilder;
+                        },
+                        onError(handler) {
+                            errorHandler = handler;
+                            return handlerBuilder;
+                        },
+                        end() {
+                            // Build multicast config if specified
+                            const multicastConfig = options?.multicast ? {
+                                group: options.multicast,
+                                ttl: 1,
+                                loopback: false,
+                            } : null;
+                            // Store UDP handler configuration for later startup
+                            const udpHandler = {
+                                name,
+                                filePath: '<programmatic>',
+                                config: {
+                                    port: options?.port ?? 0,
+                                    host: options?.host ?? '0.0.0.0',
+                                    type: options?.type ?? 'udp4',
+                                    reuseAddr: true,
+                                    reusePort: false,
+                                    recvBufferSize: 65536,
+                                    sendBufferSize: 65536,
+                                    ipv6Only: false,
+                                    multicast: multicastConfig,
+                                },
+                                handlers: {
+                                    onMessage: messageHandler,
+                                    onError: errorHandler,
+                                },
+                            };
+                            udpHandlers.push(udpHandler);
+                            logger.debug({ name, port: options?.port }, 'Added UDP handler');
+                            return udpNamespace;
+                        },
+                    };
+                    return handlerBuilder;
+                },
+                use(interceptor) {
+                    udpInterceptors.push(interceptor);
+                    return udpNamespace;
+                },
+            };
+            return udpNamespace;
+        },
+        get grpcNs() {
+            // Interceptors for gRPC namespace
+            const grpcInterceptors = [];
+            const grpcNamespace = {
+                service(serviceName, serviceOptions) {
+                    const packageName = serviceOptions?.packageName ?? '';
+                    const serviceBuilder = {
+                        method(name, optionsOrHandler, maybeHandler) {
+                            const isOptionsObject = typeof optionsOrHandler === 'object' && optionsOrHandler !== null && typeof maybeHandler === 'function';
+                            const options = isOptionsObject ? optionsOrHandler : {};
+                            const handler = isOptionsObject ? maybeHandler : optionsOrHandler;
+                            const procedureName = packageName ? `${packageName}.${serviceName}.${name}` : `${serviceName}.${name}`;
+                            const interceptors = [...globalInterceptors, ...grpcInterceptors];
+                            if (options.input || options.output) {
+                                const schema = {};
+                                if (options.input)
+                                    schema.input = options.input;
+                                if (options.output)
+                                    schema.output = options.output;
+                                schemaRegistry.register(procedureName, schema);
+                                interceptors.unshift(createValidationInterceptor(schema));
+                            }
+                            registry.procedure(procedureName, handler, {
+                                description: options.description,
+                                grpc: { service: serviceName, method: name, type: 'unary' },
+                                interceptors: interceptors.length > 0 ? interceptors : undefined,
+                            });
+                            logger.debug({ name: procedureName, type: 'unary' }, 'Added gRPC method');
+                            return serviceBuilder;
+                        },
+                        serverStream(name, optionsOrHandler, maybeHandler) {
+                            const isOptionsObject = typeof optionsOrHandler === 'object' && optionsOrHandler !== null && typeof maybeHandler === 'function';
+                            const options = isOptionsObject ? optionsOrHandler : {};
+                            const handler = isOptionsObject ? maybeHandler : optionsOrHandler;
+                            const procedureName = packageName ? `${packageName}.${serviceName}.${name}` : `${serviceName}.${name}`;
+                            const interceptors = [...globalInterceptors, ...grpcInterceptors];
+                            if (options.input || options.output) {
+                                const schema = {};
+                                if (options.input)
+                                    schema.input = options.input;
+                                if (options.output)
+                                    schema.output = options.output;
+                                schemaRegistry.register(procedureName, schema);
+                            }
+                            registry.stream(procedureName, handler, {
+                                description: options.description,
+                                direction: 'server',
+                                interceptors: interceptors.length > 0 ? interceptors : undefined,
+                            });
+                            logger.debug({ name: procedureName, type: 'server-stream' }, 'Added gRPC server stream');
+                            return serviceBuilder;
+                        },
+                        clientStream(name, optionsOrHandler, maybeHandler) {
+                            const isOptionsObject = typeof optionsOrHandler === 'object' && optionsOrHandler !== null && typeof maybeHandler === 'function';
+                            const options = isOptionsObject ? optionsOrHandler : {};
+                            const handler = isOptionsObject ? maybeHandler : optionsOrHandler;
+                            const procedureName = packageName ? `${packageName}.${serviceName}.${name}` : `${serviceName}.${name}`;
+                            const interceptors = [...globalInterceptors, ...grpcInterceptors];
+                            if (options.input || options.output) {
+                                const schema = {};
+                                if (options.input)
+                                    schema.input = options.input;
+                                if (options.output)
+                                    schema.output = options.output;
+                                schemaRegistry.register(procedureName, schema);
+                            }
+                            registry.stream(procedureName, handler, {
+                                description: options.description,
+                                direction: 'client',
+                                interceptors: interceptors.length > 0 ? interceptors : undefined,
+                            });
+                            logger.debug({ name: procedureName, type: 'client-stream' }, 'Added gRPC client stream');
+                            return serviceBuilder;
+                        },
+                        bidiStream(name, optionsOrHandler, maybeHandler) {
+                            const isOptionsObject = typeof optionsOrHandler === 'object' && optionsOrHandler !== null && typeof maybeHandler === 'function';
+                            const options = isOptionsObject ? optionsOrHandler : {};
+                            const handler = isOptionsObject ? maybeHandler : optionsOrHandler;
+                            const procedureName = packageName ? `${packageName}.${serviceName}.${name}` : `${serviceName}.${name}`;
+                            const interceptors = [...globalInterceptors, ...grpcInterceptors];
+                            if (options.input || options.output) {
+                                const schema = {};
+                                if (options.input)
+                                    schema.input = options.input;
+                                if (options.output)
+                                    schema.output = options.output;
+                                schemaRegistry.register(procedureName, schema);
+                            }
+                            registry.stream(procedureName, handler, {
+                                description: options.description,
+                                direction: 'bidi',
+                                interceptors: interceptors.length > 0 ? interceptors : undefined,
+                            });
+                            logger.debug({ name: procedureName, type: 'bidi-stream' }, 'Added gRPC bidi stream');
+                            return serviceBuilder;
+                        },
+                        end() {
+                            return grpcNamespace;
+                        },
+                    };
+                    return serviceBuilder;
+                },
+                use(interceptor) {
+                    grpcInterceptors.push(interceptor);
+                    return grpcNamespace;
+                },
+            };
+            return grpcNamespace;
+        },
+        // === Accessors ===
+        get registry() {
+            return registry;
+        },
+        get router() {
+            return router;
+        },
+        get isRunning() {
+            return running;
+        },
+        get addresses() {
+            return addresses;
+        },
+        get channels() {
+            return wsAdapter?.channels ?? null;
+        },
+        get discoveryWatcher() { return discoveryWatcher; },
+        get providers() { return resolvedProviders; },
+        get graphql() { return graphqlAdapter; },
+        get metrics() { return metricsRegistry; },
+        get tracer() { return tracerInstance; },
+        get usd() { return usdDocsHandlers; },
+        // === USD Document Access ===
+        getUSDDocument() {
+            if (!usdDocsHandlers) {
+                return null;
+            }
+            return usdDocsHandlers.getUSDDocument();
+        },
+        getOpenAPIDocument() {
+            if (!usdDocsHandlers) {
+                return null;
+            }
+            return usdDocsHandlers.getOpenAPIDocument();
+        },
+    };
+    return server;
+}
+//# sourceMappingURL=builder.js.map