raffel 0.2.3 → 1.0.0-next.f81d4db

package/dist/server/builder.js

@@ -5,25 +5,22 @@
  */
 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 { createSchemaRegistry } from '../validation/index.js';
+import { createEnvelopeInterceptor, createStandardEnvelopeInterceptor } from '../middleware/interceptors/envelope.js';
+import { 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';
+import { buildProtocolConfig, resolveSinglePortConfig } from './protocol-config.js';
+import { normalizeInterceptors as normalizeInterceptorsShared } from './interceptor-utils.js';
+import { buildServerConfigPreview, emitConfigWarnings, logSinglePortConfig, } from './builder/config-preview.js';
+import { createFrontDoorBootstrap, normalizeFrontDoorProtocol } from './front-door.js';
+import { createDiscoveryBootstrap } from './discovery-bootstrap.js';
+import { createServerLifecycle } from './builder/lifecycle.js';
+import { configureMetrics, configureTracing, createTelemetryState, } from './telemetry-bootstrap.js';
+import { isSinglePortTcpRouteEnabled as detectSinglePortTcpRouteEnabled, isSinglePortUdpRouteEnabled as detectSinglePortUdpRouteEnabled, } from './builder/single-port-utils.js';
 const logger = createLogger('server');
 /**
  * Check if a value is an async iterable
@@ -35,46 +32,150 @@ function isAsyncIterable(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, protocolExtensions: initialProtocolExtensions, } = options;
+    const { port, host = '0.0.0.0', basePath = '/', cors = true, eventDelivery, websocket, jsonrpc, tcp, grpc, graphql, middleware, http: httpOptions, frontDoor, singlePort, envelope, discovery, hotReload = isDevelopment(), providers: initialProviders, protocolExtensions: initialProtocolExtensions, protocolAliasMode: serverProtocolAliasMode = 'standard', } = 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');
-            },
-        });
-    }
+    const telemetryState = createTelemetryState();
+    const discoveryBootstrap = createDiscoveryBootstrap({
+        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 });
+    const frontDoorEnabled = frontDoor?.enabled === true;
+    const frontDoorHost = frontDoor?.host ?? host;
+    const frontDoorPort = frontDoor?.port ?? port;
+    let singlePortConfigInput = singlePort;
+    let singlePortConfig = resolveSinglePortConfig(singlePortConfigInput);
+    const frontDoorAliasMode = frontDoor?.protocolAliasMode ?? serverProtocolAliasMode;
+    const effectiveHost = frontDoorEnabled ? frontDoorHost : host;
+    const effectivePort = frontDoorEnabled ? frontDoorPort : port;
+    const frontDoorProtocols = frontDoor?.protocols && frontDoor.protocols.length > 0
+        ? Array.from(new Set(frontDoor.protocols.map((protocol) => normalizeFrontDoorProtocol(protocol, frontDoorAliasMode)).filter(Boolean)))
+        : null;
+    const getSinglePortAliasMode = () => {
+        return singlePortConfigInput?.protocolAliasMode ?? serverProtocolAliasMode;
+    };
+    const getSinglePortSource = () => {
+        return singlePortConfig.enabled ? 'singlePort' : 'native';
+    };
+    const updateSinglePortConfig = (next) => {
+        if (next === undefined)
+            return;
+        if (typeof next === 'boolean') {
+            singlePortConfigInput = {
+                ...(singlePortConfigInput ?? {}),
+                enabled: next,
+                protocolFusion: next ? (singlePortConfigInput?.protocolFusion ?? true) : false,
+            };
+        }
+        else {
+            singlePortConfigInput = { ...(singlePortConfigInput ?? {}), ...next };
+        }
+        singlePortConfig = resolveSinglePortConfig(singlePortConfigInput);
+    };
+    const shouldUseFrontDoor = (name) => {
+        if (!frontDoorEnabled)
+            return false;
+        if (!frontDoorProtocols) {
+            return ['websocket', 'jsonrpc', 'graphql'].includes(name);
+        }
+        return frontDoorProtocols.includes(name);
+    };
+    const strategyFor = (name, fallback) => {
+        const strategy = frontDoor?.strategy?.[name];
+        return strategy ?? fallback;
+    };
+    const protocols = buildProtocolConfig({
+        websocket,
+        jsonrpc,
+        tcp,
+        graphql,
+        grpc,
+        frontDoor,
+        singlePort,
+        protocolAliasMode: frontDoorAliasMode,
+    });
+    const frontDoorBootstrap = createFrontDoorBootstrap({
+        frontDoorEnabled,
+        frontDoorProtocols,
+        protocols,
+        basePath,
+        effectiveHost,
+        effectivePort,
+    });
     // Global interceptors (from options + added via .use())
     const globalInterceptors = middleware ? [...middleware] : [];
+    const envelopeInterceptor = createEnvelopeInterceptorFromOptions(envelope);
+    if (envelopeInterceptor) {
+        globalInterceptors.push(envelopeInterceptor);
+    }
+    function createEnvelopeInterceptorFromOptions(config) {
+        if (config === undefined || config === false) {
+            return undefined;
+        }
+        if (config === true) {
+            return createStandardEnvelopeInterceptor();
+        }
+        return createEnvelopeInterceptor(config);
+    }
+    function normalizeInterceptors(interceptors, schema) {
+        return normalizeInterceptorsShared(interceptors, {
+            envelopeInterceptor,
+            schema,
+        });
+    }
+    const serverConfigPreviewContext = {
+        effectiveHost,
+        effectivePort,
+        frontDoorEnabled,
+        frontDoorHost,
+        frontDoorPort,
+        frontDoorProtocols,
+        protocolAliasMode: frontDoorAliasMode,
+        getSinglePortConfig: () => ({
+            enabled: singlePortConfig.enabled,
+            protocolFusion: singlePortConfig.protocolFusion,
+            sniffTimeoutMs: singlePortConfig.sniffTimeoutMs,
+            sniffMaxBytes: singlePortConfig.sniffMaxBytes,
+            maxConcurrentDetections: singlePortConfig.maxConcurrentDetections,
+            protocols: singlePortConfig.protocols,
+            alpn: singlePortConfig.alpn,
+        }),
+        getSinglePortAliasMode,
+        getSinglePortSource,
+        protocols,
+    };
+    function emitConfiguredWarnings() {
+        emitConfigWarnings(serverConfigPreviewContext, logger);
+    }
+    function getPreviewConfig() {
+        return buildServerConfigPreview(serverConfigPreviewContext);
+    }
+    function logSinglePortConfiguration() {
+        logSinglePortConfig(serverConfigPreviewContext, logger);
+    }
     // Namespace-level interceptors (for shared middleware per protocol)
     // These are persistent across getter calls, enabling shared middleware chains
     const httpInterceptors = [];
@@ -88,32 +189,29 @@ export function createServer(options) {
     let wsUnsubscribeHandler = null;
     // 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;
+    // Hooks resolver that closes over globalHooks (mutable by .hooks())
+    const hooksResolver = (name) => resolveHooksForProcedure(name, globalHooks);
+    // Runtime state shared with lifecycle module
+    const serverState = {
+        running: { value: false },
+        addresses: { value: null },
+        providerMiddlewareInstalled: { value: false },
+        portBinding: { value: null },
+        singlePortTcpConnectionHandler: { value: null },
+        httpServer: { value: null },
+        wsAdapter: { value: null },
+        jsonRpcAdapter: { value: null },
+        tcpAdapter: { value: null },
+        grpcAdapter: { value: null },
+        graphqlAdapter: { value: null },
+        graphqlMiddleware: { value: null },
+        graphqlSubscriptionServer: { value: null },
+        usdDocsHandlers: { value: null },
+    };
     const protocolExtensionConfigs = [];
     const protocolAdapters = new Map();
-    // 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 = {};
@@ -210,6 +308,52 @@ export function createServer(options) {
             registerUdpHandler(handler);
         }
     }
+    const createFrontDoorDecisionMiddleware = () => frontDoorBootstrap.createDecisionMiddleware({
+        info: logger.info.bind(logger),
+        debug: logger.debug.bind(logger),
+        warn: logger.warn.bind(logger),
+    });
+    const isSinglePortTcpRouteEnabled = () => detectSinglePortTcpRouteEnabled(singlePortConfig.enabled, protocols.tcp?.enabled ?? false, protocols.tcp?.options.port, protocols.tcp?.options.host, effectiveHost, effectivePort);
+    const isSinglePortUdpRouteEnabled = (handler) => detectSinglePortUdpRouteEnabled(singlePortConfig.enabled, handler.config.port, handler.config.host, effectiveHost, effectivePort);
+    const serverLifecycle = createServerLifecycle({
+        logger,
+        state: serverState,
+        discoveryBootstrap,
+        telemetryState,
+        protocolExtensionConfigs,
+        protocolAdapters,
+        providerDefinitions,
+        resolvedProviders,
+        frontDoorEnabled,
+        frontDoorProtocols,
+        protocols,
+        registry,
+        schemaRegistry,
+        router,
+        globalInterceptors,
+        channelRegistry,
+        restResourceRegistry,
+        tcpHandlers,
+        udpHandlers,
+        tcpServers,
+        udpServers,
+        singlePortConfig,
+        isSinglePortTcpRouteEnabled,
+        isSinglePortUdpRouteEnabled,
+        getSinglePortSource,
+        getSinglePortAliasMode,
+        createFrontDoorDecisionMiddleware,
+        applyDiscoveryResult,
+        logSinglePortConfig: logSinglePortConfiguration,
+        host,
+        effectiveHost,
+        effectivePort,
+        basePath,
+        cors,
+        httpOptions,
+        wsMessageHandler,
+        usdDocsConfig,
+    });
     /**
      * Register an HTTP route (Hono-style).
      * Creates a procedure with the method and path as name (e.g., `get:/users/:id`).
@@ -228,7 +372,7 @@ export function createServer(options) {
         // 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 ?? [])];
+        const interceptors = normalizeInterceptors([...globalInterceptors, ...httpInterceptors, ...(options.use ?? [])]);
         // Register schema if provided
         if (options.input || options.output) {
             const schema = {};
@@ -237,7 +381,9 @@ export function createServer(options) {
             if (options.output)
                 schema.output = options.output;
             schemaRegistry.register(name, schema);
-            interceptors.unshift(createValidationInterceptor(schema));
+            const normalizedWithSchema = normalizeInterceptors([...interceptors], schema);
+            interceptors.length = 0;
+            interceptors.push(...normalizedWithSchema);
         }
         // Register as a procedure with HTTP metadata
         registry.procedure(name, handler, {
@@ -254,107 +400,244 @@ export function createServer(options) {
     const server = {
         // === Protocol Configuration ===
         enableWebSocket(path = '/') {
+            const useFrontDoor = shouldUseFrontDoor('websocket');
             protocols.websocket = {
                 enabled: true,
                 options: { path },
                 shared: true,
+                frontDoor: useFrontDoor,
+                strategy: useFrontDoor ? strategyFor('websocket', 'shared') : strategyFor('websocket', 'native'),
             };
             return server;
         },
         websocket(opts) {
+            const useFrontDoor = shouldUseFrontDoor('websocket');
+            const requestedShared = opts.port === undefined;
+            const shared = useFrontDoor || requestedShared;
             protocols.websocket = {
                 enabled: true,
                 options: opts,
-                shared: opts.port === undefined,
+                shared,
+                frontDoor: useFrontDoor,
+                strategy: useFrontDoor ? strategyFor('websocket', 'shared') : strategyFor('websocket', 'native'),
             };
             return server;
         },
         enableJsonRpc(path = '/rpc') {
+            const useFrontDoor = shouldUseFrontDoor('jsonrpc');
             protocols.jsonrpc = {
                 enabled: true,
                 options: { path },
                 shared: true,
+                frontDoor: useFrontDoor,
+                strategy: useFrontDoor ? strategyFor('jsonrpc', 'shared') : strategyFor('jsonrpc', 'native'),
             };
             return server;
         },
         jsonrpc(opts) {
+            const useFrontDoor = shouldUseFrontDoor('jsonrpc');
+            const requestedShared = opts.port === undefined;
+            const shared = useFrontDoor || requestedShared;
             protocols.jsonrpc = {
                 enabled: true,
                 options: opts,
-                shared: opts.port === undefined,
+                shared,
+                frontDoor: useFrontDoor,
+                strategy: useFrontDoor ? strategyFor('jsonrpc', 'shared') : strategyFor('jsonrpc', 'native'),
             };
             return server;
         },
         tcp(opts) {
+            const useFrontDoor = shouldUseFrontDoor('tcp');
             protocols.tcp = {
                 enabled: true,
                 options: opts,
+                frontDoor: useFrontDoor,
+                strategy: useFrontDoor ? strategyFor('tcp', 'offload') : strategyFor('tcp', 'native'),
             };
             return server;
         },
         grpc(opts) {
+            const useFrontDoor = shouldUseFrontDoor('grpc');
             protocols.grpc = {
                 enabled: true,
                 options: opts,
+                frontDoor: useFrontDoor,
+                strategy: useFrontDoor ? strategyFor('grpc', 'offload') : strategyFor('grpc', 'native'),
             };
             return server;
         },
         protocols(config) {
+            server.withProtocols({
+                websocket: config.websocket,
+                jsonrpc: config.jsonrpc,
+                streams: config.streams,
+                graphql: config.graphql,
+                tcp: config.tcp,
+                grpc: config.grpc,
+            });
+            return server;
+        },
+        withProtocols(config) {
+            const hasOwnFields = (value) => {
+                for (const key in value) {
+                    if (Object.prototype.hasOwnProperty.call(value, key)) {
+                        return true;
+                    }
+                }
+                return false;
+            };
+            // Helper to check if a slot has enabled: false
+            function isDisabled(value) {
+                if (value === false)
+                    return true;
+                if (typeof value === 'object' && value !== null && 'enabled' in value) {
+                    return value.enabled === false;
+                }
+                return false;
+            }
             // WebSocket
-            if (config.websocket !== undefined && config.websocket !== false) {
-                if (config.websocket === true) {
+            if (config.websocket !== undefined && !isDisabled(config.websocket)) {
+                const ws = config.websocket;
+                if (ws === true) {
                     server.enableWebSocket('/ws');
                 }
-                else if (typeof config.websocket === 'string') {
-                    server.enableWebSocket(config.websocket);
+                else if (typeof ws === 'string') {
+                    server.enableWebSocket(ws);
+                }
+                else if (typeof ws === 'object' && 'enabled' in ws) {
+                    const { enabled: _enabled, ...rest } = ws;
+                    if (hasOwnFields(rest)) {
+                        server.websocket(rest);
+                    }
+                    else {
+                        server.enableWebSocket('/ws');
+                    }
                 }
                 else {
-                    server.websocket(config.websocket);
+                    server.websocket(ws);
                 }
             }
             // JSON-RPC
-            if (config.jsonrpc !== undefined && config.jsonrpc !== false) {
-                if (config.jsonrpc === true) {
+            if (config.jsonrpc !== undefined && !isDisabled(config.jsonrpc)) {
+                const jrpc = config.jsonrpc;
+                if (jrpc === true) {
                     server.enableJsonRpc('/rpc');
                 }
-                else if (typeof config.jsonrpc === 'string') {
-                    server.enableJsonRpc(config.jsonrpc);
+                else if (typeof jrpc === 'string') {
+                    server.enableJsonRpc(jrpc);
+                }
+                else if (typeof jrpc === 'object' && 'enabled' in jrpc) {
+                    const { enabled: _enabled, ...rest } = jrpc;
+                    server.enableJsonRpc(rest.path ?? '/rpc');
                 }
                 else {
-                    server.jsonrpc(config.jsonrpc);
+                    server.jsonrpc(jrpc);
                 }
             }
-            // Streams (SSE)
+            // Streams
             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) {
+            if (config.graphql !== undefined && !isDisabled(config.graphql)) {
+                const gql = config.graphql;
+                if (gql === true) {
                     server.enableGraphQL('/graphql');
                 }
-                else if (typeof config.graphql === 'string') {
-                    server.enableGraphQL(config.graphql);
+                else if (typeof gql === 'string') {
+                    server.enableGraphQL(gql);
+                }
+                else if (typeof gql === 'object' && 'enabled' in gql) {
+                    const { enabled: _enabled, ...rest } = gql;
+                    if (hasOwnFields(rest)) {
+                        server.configureGraphQL(rest);
+                    }
+                    else {
+                        server.enableGraphQL('/graphql');
+                    }
+                }
+                else {
+                    server.configureGraphQL(gql);
+                }
+            }
+            // TCP
+            if (config.tcp !== undefined && !isDisabled(config.tcp)) {
+                const tcpCfg = config.tcp;
+                if (typeof tcpCfg === 'object' && 'enabled' in tcpCfg) {
+                    const { enabled: _enabled, ...rest } = tcpCfg;
+                    if (rest.port !== undefined) {
+                        server.tcp(rest);
+                    }
                 }
                 else {
-                    server.configureGraphQL(config.graphql);
+                    server.tcp(tcpCfg);
                 }
             }
-            // TCP (requires full options)
-            if (config.tcp) {
-                server.tcp(config.tcp);
+            // UDP (test-scope marker only — no production adapter)
+            if (config.udp !== undefined && !isDisabled(config.udp)) {
+                logger.debug('UDP protocol noted (test-scope only; no production adapter registered)');
             }
-            // gRPC (requires full options)
-            if (config.grpc) {
-                server.grpc(config.grpc);
+            // gRPC
+            if (config.grpc !== undefined && !isDisabled(config.grpc)) {
+                const grpcCfg = config.grpc;
+                if (typeof grpcCfg === 'object' && 'enabled' in grpcCfg) {
+                    const { enabled: _enabled, ...rest } = grpcCfg;
+                    if (rest.port !== undefined && rest.protoPath !== undefined) {
+                        server.grpc(rest);
+                    }
+                }
+                else {
+                    server.grpc(grpcCfg);
+                }
             }
-            logger.info({ protocols: Object.keys(config).filter((k) => config[k]) }, 'Protocols configured');
+            emitConfiguredWarnings();
+            return server;
+        },
+        withProfile(profile, overrides) {
+            if (profile === 'local') {
+                updateSinglePortConfig({ protocolAliasMode: 'extended' });
+            }
+            else if (profile === 'staging') {
+                updateSinglePortConfig({ protocolAliasMode: 'standard' });
+            }
+            else if (profile === 'production') {
+                updateSinglePortConfig({ protocolAliasMode: 'standard' });
+                if (hotReload) {
+                    logger.warn('hotReload is enabled but profile is "production". Pass hotReload: false to createServer() for production.');
+                }
+                if (serverProtocolAliasMode === 'extended') {
+                    logger.warn('protocolAliasMode "extended" was passed to createServer() but profile is "production". Use "standard" in production.');
+                }
+            }
+            if (overrides?.protocols) {
+                server.withProtocols(overrides.protocols);
+            }
+            return server;
+        },
+        withPreset(preset, options = {}) {
+            const websocketPath = options.websocketPath ?? '/ws';
+            const jsonrpcPath = options.jsonrpcPath ?? '/rpc';
+            const graphqlPath = options.graphqlPath ?? '/graphql';
+            if (preset === 'realtime') {
+                server.enableWebSocket(websocketPath);
+            }
+            else if (preset === 'rpc') {
+                server.enableJsonRpc(jsonrpcPath);
+            }
+            else if (preset === 'api' || preset === 'dev' || preset === 'full') {
+                server.enableWebSocket(websocketPath);
+                server.enableJsonRpc(jsonrpcPath);
+                server.enableGraphQL(graphqlPath);
+            }
+            return server;
+        },
+        enableSinglePort(config = true) {
+            updateSinglePortConfig(config);
             return server;
         },
         registerProtocol(name, factory, options) {
-            if (running) {
+            if (serverState.running.value) {
                 throw new Error('Cannot register protocol adapter after the server has started');
             }
             registerProtocolExtension({
@@ -365,51 +648,37 @@ export function createServer(options) {
             return server;
         },
         enableGraphQL(path = '/graphql') {
+            const useFrontDoor = shouldUseFrontDoor('graphql');
             protocols.graphql = {
                 enabled: true,
                 options: { path },
                 shared: true,
+                frontDoor: useFrontDoor,
+                strategy: useFrontDoor ? strategyFor('graphql', 'shared') : strategyFor('graphql', 'native'),
             };
             return server;
         },
         configureGraphQL(opts) {
+            const useFrontDoor = shouldUseFrontDoor('graphql');
+            const requestedShared = opts.port === undefined;
+            const shared = useFrontDoor || requestedShared;
             protocols.graphql = {
                 enabled: true,
                 options: opts,
-                shared: opts.port === undefined,
+                shared,
+                frontDoor: useFrontDoor,
+                strategy: useFrontDoor ? strategyFor('graphql', 'shared') : strategyFor('graphql', 'native'),
             };
             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);
-            }
+            configureMetrics(telemetryState, config);
             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);
+            configureTracing(telemetryState, config);
             return server;
         },
         // === USD Documentation ===
@@ -422,8 +691,11 @@ export function createServer(options) {
                 securitySchemes: config.securitySchemes,
                 defaultSecurity: config.defaultSecurity,
                 tags: config.tags,
+                contentTypes: config.contentTypes,
+                tagGroups: config.tagGroups,
                 externalDocs: config.externalDocs,
                 ui: config.ui,
+                documentation: config.documentation,
                 includeErrorSchemas: config.includeErrorSchemas,
                 includeStreamEventSchemas: config.includeStreamEventSchemas,
                 jsonrpc: config.jsonrpc,
@@ -472,7 +744,7 @@ export function createServer(options) {
                 return;
             }
             // Fluent builder with hooks resolver
-            return createProcedureBuilder(registry, schemaRegistry, nameOrHandler, [...globalInterceptors], createHooksResolver());
+            return createProcedureBuilder(registry, schemaRegistry, nameOrHandler, [...globalInterceptors], hooksResolver, envelopeInterceptor);
         },
         stream(name) {
             return createStreamBuilder(registry, schemaRegistry, name, [...globalInterceptors]);
@@ -534,7 +806,7 @@ export function createServer(options) {
                     }
                 }
                 // Build interceptors
-                const interceptors = [...globalInterceptors, ...(def.use ?? [])];
+                let interceptors = normalizeInterceptors([...globalInterceptors, ...(def.use ?? [])]);
                 // Register schema
                 if (def.input || def.output) {
                     const schema = {};
@@ -543,7 +815,7 @@ export function createServer(options) {
                     if (def.output)
                         schema.output = def.output;
                     schemaRegistry.register(name, schema);
-                    interceptors.unshift(createValidationInterceptor(schema));
+                    interceptors = normalizeInterceptors(interceptors, schema);
                 }
                 registry.procedure(name, def.handler, {
                     summary: def.summary,
@@ -565,7 +837,7 @@ export function createServer(options) {
                 // Helper to register an operation
                 const registerOp = (opName, handler, method, path, inputSchema) => {
                     const procedureName = `${name}.${opName}`;
-                    const interceptors = [...baseInterceptors];
+                    let interceptors = [...baseInterceptors];
                     if (inputSchema || def.schema) {
                         const schema = {};
                         if (inputSchema)
@@ -574,9 +846,12 @@ export function createServer(options) {
                             schema.output = def.schema;
                         schemaRegistry.register(procedureName, schema);
                         if (inputSchema) {
-                            interceptors.unshift(createValidationInterceptor({ input: inputSchema }));
+                            interceptors = normalizeInterceptors(interceptors, { input: inputSchema });
                         }
                     }
+                    else {
+                        interceptors = normalizeInterceptors(interceptors);
+                    }
                     registry.procedure(procedureName, handler, {
                         tags,
                         httpPath: path,
@@ -655,22 +930,15 @@ export function createServer(options) {
         },
         // === Grouping ===
         group(prefix) {
-            return createGroupBuilder(registry, schemaRegistry, prefix, [...globalInterceptors], createHooksResolver());
+            return createGroupBuilder(registry, schemaRegistry, prefix, [...globalInterceptors], hooksResolver, envelopeInterceptor);
         },
         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,
-                ];
+                const routeSchema = route.kind === 'procedure' ? route.schema : undefined;
+                const interceptors = normalizeInterceptors([...globalInterceptors, ...mountInterceptors, ...route.moduleInterceptors, ...route.interceptors], routeSchema);
                 if (route.schema) {
                     schemaRegistry.register(fullName, route.schema);
                 }
@@ -723,7 +991,7 @@ export function createServer(options) {
             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];
+            let interceptors = normalizeInterceptors([...globalInterceptors, ...routeInterceptors, ...inputInterceptors]);
             // Register schema if defined
             if (inputSchema || outputSchema) {
                 const schema = {};
@@ -732,7 +1000,7 @@ export function createServer(options) {
                 if (outputSchema)
                     schema.output = outputSchema;
                 schemaRegistry.register(name, schema);
-                interceptors.unshift(createValidationInterceptor(schema));
+                interceptors = normalizeInterceptors(interceptors, schema);
             }
             registry.procedure(name, handler, {
                 summary,
@@ -833,443 +1101,10 @@ export function createServer(options) {
         },
         // === 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, wsMessageHandler ?? undefined);
-                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 };
-                }
-            }
-            if (protocolExtensionConfigs.length > 0) {
-                const protocolContext = {
-                    router,
-                    registry,
-                    schemaRegistry,
-                    httpServer,
-                    basePath,
-                    host,
-                    port,
-                    providers: resolvedProviders,
-                };
-                for (const extension of protocolExtensionConfigs) {
-                    const adapter = await extension.factory(protocolContext, extension.options);
-                    protocolAdapters.set(extension.name, adapter);
-                    await adapter.start();
-                    if (adapter.address) {
-                        if (!addresses.protocols) {
-                            addresses.protocols = {};
-                        }
-                        addresses.protocols[extension.name] = adapter.address;
-                    }
-                    logger.info({ name: extension.name }, 'Protocol adapter started');
-                }
-            }
-            // 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);
-                if (!addresses.udp) {
-                    addresses.udp = { host: udpServer.host, port: udpServer.port };
-                }
-                logger.info({ name: handler.name, port: handler.config.port }, 'UDP handler started');
-            }
-            running = true;
+            await serverLifecycle.start();
         },
         async stop() {
-            if (!running)
-                return;
-            const stops = [];
-            if (protocolAdapters.size > 0) {
-                for (const [name, adapter] of protocolAdapters) {
-                    logger.info({ name }, 'Protocol adapter stopping');
-                    stops.push(adapter.stop());
-                }
-                protocolAdapters.clear();
-            }
-            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;
+            await serverLifecycle.stop();
         },
         async restart() {
             await server.stop();
@@ -1336,6 +1171,10 @@ export function createServer(options) {
                             onJoin: wrappedOnJoin,
                             onLeave: wrappedOnLeave,
                         },
+                        // Include documentation metadata
+                        type: options?.type ?? 'public',
+                        description: options?.description,
+                        tags: options?.tags,
                     };
                     channelRegistry.set(channelName, channelDef);
                     logger.debug({ name: channelName, type: options?.type ?? 'public', auth: authRequirement }, 'Added WebSocket channel');
@@ -1362,18 +1201,21 @@ export function createServer(options) {
         },
         get streams() {
             // Uses persistent streamInterceptors from outer scope for shared middleware chain
+            const isStreamOptions = (optionsOrHandler) => typeof optionsOrHandler === 'object'
+                && optionsOrHandler !== null
+                && !isAsyncIterable(optionsOrHandler);
             const streamsNamespace = {
                 source(name, optionsOrHandler, maybeHandler) {
-                    const isOptionsObject = typeof optionsOrHandler === 'object' && optionsOrHandler !== null && !isAsyncIterable(optionsOrHandler);
+                    const isOptionsObject = isStreamOptions(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];
+                    let interceptors = normalizeInterceptors([...globalInterceptors, ...streamInterceptors]);
                     if (options.input) {
                         const schema = { input: options.input };
                         schemaRegistry.register(streamName, schema);
-                        interceptors.unshift(createValidationInterceptor(schema));
+                        interceptors = normalizeInterceptors(interceptors, schema);
                     }
                     registry.stream(streamName, handler, {
                         description: options.description,
@@ -1384,15 +1226,15 @@ export function createServer(options) {
                     return streamsNamespace;
                 },
                 sink(name, optionsOrHandler, maybeHandler) {
-                    const isOptionsObject = typeof optionsOrHandler === 'object' && optionsOrHandler !== null;
+                    const isOptionsObject = isStreamOptions(optionsOrHandler);
                     const options = isOptionsObject ? optionsOrHandler : {};
                     const handler = isOptionsObject ? maybeHandler : optionsOrHandler;
                     const streamName = `stream:${name}`;
-                    const interceptors = [...globalInterceptors, ...streamInterceptors];
+                    let interceptors = normalizeInterceptors([...globalInterceptors, ...streamInterceptors]);
                     if (options.input) {
                         const schema = { input: options.input };
                         schemaRegistry.register(streamName, schema);
-                        interceptors.unshift(createValidationInterceptor(schema));
+                        interceptors = normalizeInterceptors(interceptors, schema);
                     }
                     registry.stream(streamName, handler, {
                         description: options.description,
@@ -1403,15 +1245,15 @@ export function createServer(options) {
                     return streamsNamespace;
                 },
                 duplex(name, optionsOrHandler, maybeHandler) {
-                    const isOptionsObject = typeof optionsOrHandler === 'object' && optionsOrHandler !== null;
+                    const isOptionsObject = isStreamOptions(optionsOrHandler);
                     const options = isOptionsObject ? optionsOrHandler : {};
                     const handler = isOptionsObject ? maybeHandler : optionsOrHandler;
                     const streamName = `stream:${name}`;
-                    const interceptors = [...globalInterceptors, ...streamInterceptors];
+                    let interceptors = normalizeInterceptors([...globalInterceptors, ...streamInterceptors]);
                     if (options.input) {
                         const schema = { input: options.input };
                         schemaRegistry.register(streamName, schema);
-                        interceptors.unshift(createValidationInterceptor(schema));
+                        interceptors = normalizeInterceptors(interceptors, schema);
                     }
                     registry.stream(streamName, handler, {
                         description: options.description,
@@ -1434,11 +1276,11 @@ export function createServer(options) {
                 const isOptionsObject = typeof optionsOrHandler === 'object' && optionsOrHandler !== null && typeof maybeHandler === 'function';
                 const options = isOptionsObject ? optionsOrHandler : {};
                 const handler = isOptionsObject ? maybeHandler : optionsOrHandler;
-                const interceptors = [...globalInterceptors, ...rpcInterceptors];
+                let interceptors = normalizeInterceptors([...globalInterceptors, ...rpcInterceptors]);
                 if (options.input) {
                     const schema = { input: options.input, output: options.output };
                     schemaRegistry.register(name, schema);
-                    interceptors.unshift(createValidationInterceptor(schema));
+                    interceptors = normalizeInterceptors(interceptors, schema);
                 }
                 registry.procedure(name, handler, {
                     description: options.description,
@@ -1601,7 +1443,7 @@ export function createServer(options) {
                             const options = isOptionsObject ? optionsOrHandler : {};
                             const handler = isOptionsObject ? maybeHandler : optionsOrHandler;
                             const procedureName = packageName ? `${packageName}.${serviceName}.${name}` : `${serviceName}.${name}`;
-                            const interceptors = [...globalInterceptors, ...grpcInterceptors];
+                            let interceptors = normalizeInterceptors([...globalInterceptors, ...grpcInterceptors]);
                             if (options.input || options.output) {
                                 const schema = {};
                                 if (options.input)
@@ -1609,7 +1451,7 @@ export function createServer(options) {
                                 if (options.output)
                                     schema.output = options.output;
                                 schemaRegistry.register(procedureName, schema);
-                                interceptors.unshift(createValidationInterceptor(schema));
+                                interceptors = normalizeInterceptors(interceptors, schema);
                             }
                             registry.procedure(procedureName, handler, {
                                 description: options.description,
@@ -1706,32 +1548,35 @@ export function createServer(options) {
             return router;
         },
         get isRunning() {
-            return running;
+            return serverState.running.value;
         },
         get addresses() {
-            return addresses;
+            return serverState.addresses.value;
         },
         get channels() {
-            return wsAdapter?.channels ?? null;
+            return serverState.wsAdapter.value?.channels ?? null;
         },
-        get discoveryWatcher() { return discoveryWatcher; },
+        get discoveryWatcher() { return discoveryBootstrap.watcher; },
         get providers() { return resolvedProviders; },
-        get graphql() { return graphqlAdapter; },
-        get metrics() { return metricsRegistry; },
-        get tracer() { return tracerInstance; },
-        get usd() { return usdDocsHandlers; },
+        get graphql() { return serverState.graphqlAdapter.value; },
+        get metrics() { return telemetryState.metricsRegistry; },
+        get tracer() { return telemetryState.tracerInstance; },
+        previewConfig() {
+            return getPreviewConfig();
+        },
+        get usd() { return serverState.usdDocsHandlers.value; },
         // === USD Document Access ===
         getUSDDocument() {
-            if (!usdDocsHandlers) {
+            if (!serverState.usdDocsHandlers.value) {
                 return null;
             }
-            return usdDocsHandlers.getUSDDocument();
+            return serverState.usdDocsHandlers.value.getUSDDocument();
         },
         getOpenAPIDocument() {
-            if (!usdDocsHandlers) {
+            if (!serverState.usdDocsHandlers.value) {
                 return null;
             }
-            return usdDocsHandlers.getOpenAPIDocument();
+            return serverState.usdDocsHandlers.value.getOpenAPIDocument();
         },
     };
     return server;