@fluojs/http 1.0.0-beta.1 → 1.0.0-beta.11

package/dist/dispatch/dispatcher.js

@@ -1,21 +1,23 @@
-import { invokeControllerHandler } from './dispatch-handler-policy.js';
-import { resolveContentNegotiation, writeErrorResponse, writeSuccessResponse } from './dispatch-response-policy.js';
-import { matchHandlerOrThrow, updateRequestParams } from './dispatch-routing-policy.js';
+import { getCompiledDtoBindingPlan } from '../adapters/dto-binding-plan.js';
+import { createRequestContext, runWithRequestContext } from '../context/request-context.js';
+import { SseResponse } from '../context/sse.js';
 import { RequestAbortedError } from '../errors.js';
 import { runGuardChain } from '../guards.js';
 import { runInterceptorChain } from '../interceptors.js';
-import { runMiddlewareChain } from '../middleware/middleware.js';
-import { createRequestContext, runWithRequestContext } from '../context/request-context.js';
-import { SseResponse } from '../context/sse.js';
+import { isMiddlewareRouteConfig, matchRoutePattern, runMiddlewareChain } from '../middleware/middleware.js';
+import { invokeControllerHandler } from './dispatch-handler-policy.js';
+import { resolveContentNegotiation, writeErrorResponse, writeSuccessResponse } from './dispatch-response-policy.js';
+import { matchHandlerOrThrow, updateRequestParams } from './dispatch-routing-policy.js';
+import { attachFrameworkRequestNativeRouteHandoff, readFrameworkRequestNativeRouteHandoff } from './native-route-handoff.js';
+import { compileFastPathEligibility, getHandlerFastPathEligibility, setHandlerFastPathEligibility, FAST_PATH_STATS_SYMBOL, addPathDebugHeader, createFastPathStats, createPathDebugInfo, executeFastPath, shouldUseFastPathForRequest } from './fast-path/index.js';
+export { FAST_PATH_ELIGIBILITY_SYMBOL, FAST_PATH_STATS_SYMBOL } from './fast-path/index.js';
 
-/**
- * Type definition for a global HTTP error handler function.
- */
+/** Type definition for a global HTTP error handler function. */
 
-/**
- * Options for creating an HTTP {@link Dispatcher}.
- */
+/** Options for creating an HTTP {@link Dispatcher}. */
 
+const EMPTY_NATIVE_FAST_PATH_HANDLER_EXECUTION_PLANS = new WeakMap();
+const EMPTY_NATIVE_FAST_PATH_OBSERVERS = [];
 function logDispatchFailure(logger, message, error) {
   if (logger) {
     logger.error(message, error, 'HttpDispatcher');
@@ -24,33 +26,260 @@ function logDispatchFailure(logger, message, error) {
   console.error(`[fluo][HttpDispatcher] ${message}`, error);
 }
 function createDispatchRequest(request) {
-  return {
-    ...request,
+  const dispatchRequest = {
+    get cookies() {
+      return request.cookies;
+    },
+    get headers() {
+      return request.headers;
+    },
+    get query() {
+      return request.query;
+    },
+    body: request.body,
+    method: request.method,
     params: {
       ...request.params
+    },
+    path: request.path,
+    raw: request.raw,
+    rawBody: request.rawBody,
+    requestId: request.requestId,
+    signal: request.signal,
+    url: request.url
+  };
+  const nativeRouteHandoff = readFrameworkRequestNativeRouteHandoff(request);
+  const files = request.files;
+  const principal = request.principal;
+  if (files !== undefined) {
+    dispatchRequest.files = files;
+  }
+  if (principal !== undefined) {
+    dispatchRequest.principal = principal;
+  }
+  return nativeRouteHandoff ? attachFrameworkRequestNativeRouteHandoff(dispatchRequest, nativeRouteHandoff) : dispatchRequest;
+}
+function cloneHandlerDescriptor(descriptor) {
+  const cloned = {
+    ...descriptor,
+    metadata: {
+      ...descriptor.metadata,
+      moduleMiddleware: [...descriptor.metadata.moduleMiddleware],
+      pathParams: [...descriptor.metadata.pathParams]
+    },
+    route: {
+      ...descriptor.route,
+      guards: descriptor.route.guards ? [...descriptor.route.guards] : undefined,
+      headers: descriptor.route.headers?.map(header => ({
+        ...header
+      })),
+      interceptors: descriptor.route.interceptors ? [...descriptor.route.interceptors] : undefined,
+      produces: descriptor.route.produces ? [...descriptor.route.produces] : undefined,
+      redirect: descriptor.route.redirect ? {
+        ...descriptor.route.redirect
+      } : undefined
     }
   };
+  const eligibility = getHandlerFastPathEligibility(descriptor);
+  if (eligibility) {
+    setHandlerFastPathEligibility(cloned, eligibility);
+  }
+  return cloned;
 }
 function readRequestId(request) {
+  if (request.requestId) {
+    return request.requestId;
+  }
   const raw = request.headers['x-request-id'] ?? request.headers['X-Request-Id'];
   const value = Array.isArray(raw) ? raw[0] : raw;
   const normalized = value?.trim();
   return normalized ? normalized : undefined;
 }
-function createDispatchContext(request, response, rootContainer) {
-  return createRequestContext({
-    container: rootContainer.createRequestScope(),
+function createDispatchContext(request, response, container, promoteOnContainerAccess) {
+  const context = createRequestContext({
+    container,
     metadata: {},
     request,
     requestId: readRequestId(request),
     response
   });
+  if (!promoteOnContainerAccess) {
+    return context;
+  }
+
+  // Wrap the container to only promote to request scope when resolve() is actually called.
+  // This allows fast-path handlers to check ctx.container without triggering scope creation.
+  let activeContainer = container;
+  let wrappedContainer;
+  let promoted = false;
+  const ensurePromoted = () => {
+    if (!promoted) {
+      activeContainer = promoteOnContainerAccess();
+      promoted = true;
+    }
+    return activeContainer;
+  };
+  const getWrappedContainer = () => {
+    if (!wrappedContainer) {
+      wrappedContainer = {
+        async resolve(token) {
+          const targetContainer = ensurePromoted();
+          return targetContainer.resolve(token);
+        },
+        async dispose() {
+          // If promotion never happened, this is a no-op.
+          // This prevents accidentally disposing the root container when a
+          // captured container reference is used after a singleton-only request.
+          if (!promoted) {
+            return;
+          }
+          return activeContainer.dispose();
+        }
+      };
+    }
+    return wrappedContainer;
+  };
+  Object.defineProperty(context, 'container', {
+    configurable: true,
+    enumerable: true,
+    get() {
+      // If promotion has already occurred, return the actual container.
+      if (promoted) {
+        return activeContainer;
+      }
+      // Return the wrapped container that will promote on resolve().
+      return getWrappedContainer();
+    },
+    set(value) {
+      activeContainer = value;
+      promoted = true;
+    }
+  });
+  return context;
+}
+function createRootDispatchScope(rootContainer) {
+  return {
+    container: rootContainer,
+    requestScoped: false
+  };
+}
+function createRequestDispatchScope(rootContainer) {
+  return {
+    container: rootContainer.createRequestScope(),
+    requestScoped: true
+  };
+}
+function activeMiddlewareMayRequireRequestScope(definitions, request) {
+  return definitions.some(definition => {
+    if (!isMiddlewareRouteConfig(definition)) {
+      return true;
+    }
+    return definition.routes.length === 0 || definition.routes.some(route => matchRoutePattern(route, request.path));
+  });
+}
+function compileMiddlewareScopePlan(definitions) {
+  const conditionalDefinitions = [];
+  for (const definition of definitions) {
+    if (!isMiddlewareRouteConfig(definition) || definition.routes.length === 0) {
+      return {
+        alwaysRequiresRequestScope: true,
+        conditionalDefinitions: []
+      };
+    }
+    conditionalDefinitions.push(definition);
+  }
+  return {
+    alwaysRequiresRequestScope: false,
+    conditionalDefinitions
+  };
+}
+function compiledMiddlewareMayRequireRequestScope(plan, request) {
+  return plan.alwaysRequiresRequestScope || activeMiddlewareMayRequireRequestScope(plan.conditionalDefinitions, request);
+}
+function requestDtoMayRequireRequestScope(handler, options) {
+  if (!handler.route.request) {
+    return false;
+  }
+  if ((options.requestScope?.converterDefinitions ?? []).length > 0) {
+    return true;
+  }
+  if (options.binder) {
+    return true;
+  }
+  const plan = getCompiledDtoBindingPlan(handler.route.request);
+  return plan.entries.some(entry => entry.converter !== undefined);
+}
+function handlerMethodMayUseRequestContext(handler) {
+  const method = handler.controllerToken.prototype[handler.methodName];
+  return typeof method === 'function' && method.length >= 2;
+}
+function hasRequestScopeInspector(container) {
+  return typeof container === 'object' && container !== null && 'hasRequestScopedDependency' in container && typeof container.hasRequestScopedDependency === 'function';
+}
+function compileHandlerExecutionPlan(handler, options) {
+  const routeGuards = handler.route.guards ?? [];
+  const requestScope = compileMiddlewareScopePlan(handler.metadata.moduleMiddleware);
+  const mergedInterceptors = mergeInterceptors(options.interceptors ?? [], handler.route.interceptors ?? []);
+  return {
+    mergedInterceptors,
+    requestScope,
+    requiresRequestScope: routeGuards.length > 0 || mergedInterceptors.length > 0 || requestScope.alwaysRequiresRequestScope || requestDtoMayRequireRequestScope(handler, options) || handlerMethodMayUseRequestContext(handler) || (hasRequestScopeInspector(options.rootContainer) ? options.rootContainer.hasRequestScopedDependency(handler.controllerToken) : true),
+    routeGuards
+  };
+}
+function handlerMayRequireRequestScope(plan, request) {
+  return plan.requiresRequestScope || compiledMiddlewareMayRequireRequestScope(plan.requestScope, request);
+}
+function compileDispatchStartPlan(observers, appMiddleware) {
+  const requestScope = compileMiddlewareScopePlan(appMiddleware);
+  return {
+    requestScope,
+    requiresRequestScope: observers.length > 0 || requestScope.alwaysRequiresRequestScope
+  };
+}
+function dispatchStartMayRequireRequestScope(plan, request) {
+  return plan.requiresRequestScope || compiledMiddlewareMayRequireRequestScope(plan.requestScope, request);
+}
+function ensureRequestScope(context) {
+  if (context.dispatchScope.requestScoped) {
+    return;
+  }
+  context.dispatchScope = createRequestDispatchScope(context.options.rootContainer);
+  context.requestContext.container = context.dispatchScope.container;
 }
 function ensureRequestNotAborted(request) {
-  if (request.signal?.aborted) {
+  if (isRequestAborted(request)) {
     throw new RequestAbortedError();
   }
 }
+function isRequestAborted(request) {
+  return request.isAborted?.() ?? request.signal?.aborted === true;
+}
+function resolveFastPathHandlerRuntimeCache(handler, cache) {
+  const cached = cache.get(handler);
+  if (cached) {
+    return cached;
+  }
+  const method = handler.controllerToken.prototype[handler.methodName];
+  const compiled = {
+    method: typeof method === 'function' ? method : undefined
+  };
+  cache.set(handler, compiled);
+  return compiled;
+}
+function resolveFastPathController(handler, controllerContainer, runtimeCache) {
+  if (runtimeCache.controller) {
+    return runtimeCache.controller;
+  }
+  runtimeCache.controllerPromise ??= controllerContainer.resolve(handler.controllerToken).then(controller => {
+    runtimeCache.controller = controller;
+    return controller;
+  });
+  return runtimeCache.controllerPromise;
+}
+function isPromiseLike(value) {
+  return typeof value === 'object' && value !== null && 'then' in value && typeof value.then === 'function';
+}
 function isRequestObserver(value) {
   return typeof value === 'object' && value !== null;
 }
@@ -71,29 +300,40 @@ async function notifyObservers(observers, requestContext, callback, handler) {
   }
 }
 async function notifyObserversSafely(observers, requestContext, callback, logger, handler) {
+  if (observers.length === 0) {
+    return;
+  }
   try {
     await notifyObservers(observers, requestContext, callback, handler);
   } catch (error) {
     logDispatchFailure(logger, 'Request observer threw an unhandled error.', error);
   }
 }
-async function dispatchMatchedHandler(handler, requestContext, observers, contentNegotiation, binder, globalInterceptors, logger) {
-  const guardContext = {
-    handler,
-    requestContext
-  };
-  const interceptorContext = {
-    handler,
-    requestContext
-  };
-  await runGuardChain(handler.route.guards ?? [], guardContext);
+function mergeInterceptors(globalInterceptors, routeInterceptors) {
+  if (globalInterceptors.length === 0) {
+    return routeInterceptors;
+  }
+  if (routeInterceptors.length === 0) {
+    return globalInterceptors;
+  }
+  return [...globalInterceptors, ...routeInterceptors];
+}
+async function dispatchMatchedHandler(handler, executionPlan, requestContext, controllerContainer, observers, contentNegotiation, binder, logger) {
+  const routeGuards = executionPlan.routeGuards;
+  if (routeGuards.length > 0) {
+    const guardContext = {
+      handler,
+      requestContext
+    };
+    await runGuardChain(routeGuards, guardContext);
+  }
   if (requestContext.response.committed) {
     return;
   }
-  const interceptors = [...(globalInterceptors ?? []), ...(handler.route.interceptors ?? [])];
-  const result = await runInterceptorChain(interceptors, interceptorContext, async () => {
-    return invokeControllerHandler(handler, requestContext, binder);
-  });
+  const result = executionPlan.mergedInterceptors.length === 0 ? await invokeControllerHandler(handler, requestContext, binder, controllerContainer) : await runInterceptorChain(executionPlan.mergedInterceptors, {
+    handler,
+    requestContext
+  }, async () => invokeControllerHandler(handler, requestContext, binder, controllerContainer));
   ensureRequestNotAborted(requestContext.request);
   if (!(result instanceof SseResponse) && !requestContext.response.committed) {
     await writeSuccessResponse(handler, requestContext.request, requestContext.response, result, contentNegotiation);
@@ -102,6 +342,72 @@ async function dispatchMatchedHandler(handler, requestContext, observers, conten
     await observer.onRequestSuccess?.(context, result);
   }, logger, handler);
 }
+function resolveHandlerExecutionPlan(handler, executionPlans, options) {
+  const cached = executionPlans.get(handler);
+  if (cached) {
+    return cached;
+  }
+  const compiled = compileHandlerExecutionPlan(handler, options);
+  executionPlans.set(handler, compiled);
+  return compiled;
+}
+async function dispatchNativeFastRoute(match, request, response, options, contentNegotiation, fastPathRuntimeCache) {
+  const eligibility = getHandlerFastPathEligibility(match.descriptor);
+  if (!shouldUseFastPathForRequest(eligibility, request)) {
+    return false;
+  }
+  if (options.fastPathDebugHeaders === true && eligibility && !response.committed) {
+    const debugInfo = createPathDebugInfo(eligibility);
+    addPathDebugHeader(response.setHeader.bind(response), debugInfo);
+  }
+  const dispatchRequest = request;
+  const dispatchScope = createRootDispatchScope(options.rootContainer);
+  let phaseContext;
+  let containerPromotionOpen = true;
+  const requestContext = createDispatchContext(dispatchRequest, response, dispatchScope.container, () => {
+    if (!containerPromotionOpen) {
+      return phaseContext.dispatchScope.container;
+    }
+    ensureRequestScope(phaseContext);
+    return phaseContext.dispatchScope.container;
+  });
+  phaseContext = {
+    contentNegotiation,
+    dispatchScope,
+    fastPathRuntimeCache,
+    handlerExecutionPlans: EMPTY_NATIVE_FAST_PATH_HANDLER_EXECUTION_PLANS,
+    observers: EMPTY_NATIVE_FAST_PATH_OBSERVERS,
+    options,
+    requestContext,
+    response
+  };
+  phaseContext.matchedHandler = match.descriptor;
+  updateRequestParams(phaseContext.requestContext, match.params);
+  await runWithRequestContext(phaseContext.requestContext, async () => {
+    try {
+      ensureRequestNotAborted(phaseContext.requestContext.request);
+      const fastPathSuccess = await tryFastPathExecution(match.descriptor, phaseContext);
+      if (!fastPathSuccess) {
+        throw new Error(`Native route ${match.descriptor.route.method}:${match.descriptor.route.path} was not fast-path executable.`);
+      }
+    } catch (error) {
+      await handleDispatchError(phaseContext, error);
+    } finally {
+      if (!phaseContext.dispatchScope.requestScoped) {
+        phaseContext.requestContext.container = phaseContext.dispatchScope.container;
+      }
+      containerPromotionOpen = false;
+      if (phaseContext.dispatchScope.requestScoped) {
+        try {
+          await phaseContext.dispatchScope.container.dispose();
+        } catch (error) {
+          logDispatchFailure(options.logger, 'Request-scoped container dispose threw an error.', error);
+        }
+      }
+    }
+  });
+  return true;
+}
 async function notifyRequestStart(context) {
   await notifyObserversSafely(context.observers, context.requestContext, async (observer, observationContext) => {
     await observer.onRequestStart?.(observationContext);
@@ -122,6 +428,36 @@ async function notifyRequestFinish(context) {
     await observer.onRequestFinish?.(observationContext);
   }, context.options.logger, context.matchedHandler);
 }
+async function tryFastPathExecution(handler, context) {
+  const eligibility = getHandlerFastPathEligibility(handler);
+  if (!eligibility || eligibility.executionPath !== 'fast') {
+    return false;
+  }
+  if (typeof context.dispatchScope.container.resolve !== 'function') {
+    ensureRequestScope(context);
+  }
+  const runtimeCache = resolveFastPathHandlerRuntimeCache(handler, context.fastPathRuntimeCache);
+  const controllerOrPromise = resolveFastPathController(handler, context.dispatchScope.container, runtimeCache);
+  const controller = isPromiseLike(controllerOrPromise) ? await controllerOrPromise : controllerOrPromise;
+  const fastPathResult = await executeFastPath({
+    binder: context.options.binder,
+    contentNegotiation: context.contentNegotiation,
+    controller,
+    controllerContainer: context.dispatchScope.container,
+    handler,
+    method: runtimeCache.method,
+    request: context.requestContext.request,
+    requestContext: context.requestContext,
+    response: context.response
+  });
+  if (fastPathResult.executed) {
+    return true;
+  }
+  if (fastPathResult.error) {
+    throw fastPathResult.error;
+  }
+  return false;
+}
 async function runDispatchPipeline(context) {
   ensureRequestNotAborted(context.requestContext.request);
   const appMiddlewareContext = {
@@ -129,13 +465,28 @@ async function runDispatchPipeline(context) {
     requestContext: context.requestContext,
     response: context.response
   };
-  await runMiddlewareChain(context.options.appMiddleware ?? [], appMiddlewareContext, async () => {
+  const dispatchMatchedRoute = async () => {
     if (context.response.committed) {
       return;
     }
-    const match = matchHandlerOrThrow(context.options.handlerMapping, appMiddlewareContext.request);
+    const match = readFrameworkRequestNativeRouteHandoff(appMiddlewareContext.request) ?? matchHandlerOrThrow(context.options.handlerMapping, appMiddlewareContext.request);
     context.matchedHandler = match.descriptor;
     updateRequestParams(context.requestContext, match.params);
+    const eligibility = getHandlerFastPathEligibility(match.descriptor);
+    if (context.options.fastPathDebugHeaders === true && eligibility && !context.response.committed) {
+      const debugInfo = createPathDebugInfo(eligibility);
+      addPathDebugHeader(context.response.setHeader.bind(context.response), debugInfo);
+    }
+    if (shouldUseFastPathForRequest(eligibility, appMiddlewareContext.request)) {
+      const fastPathSuccess = await tryFastPathExecution(match.descriptor, context);
+      if (fastPathSuccess) {
+        return;
+      }
+    }
+    const executionPlan = resolveHandlerExecutionPlan(match.descriptor, context.handlerExecutionPlans, context.options);
+    if (handlerMayRequireRequestScope(executionPlan, appMiddlewareContext.request)) {
+      ensureRequestScope(context);
+    }
     await notifyHandlerMatched(context, match.descriptor);
     const moduleMiddlewareContext = {
       request: context.requestContext.request,
@@ -143,12 +494,18 @@ async function runDispatchPipeline(context) {
       response: context.response
     };
     await runMiddlewareChain(match.descriptor.metadata.moduleMiddleware ?? [], moduleMiddlewareContext, async () => {
-      await dispatchMatchedHandler(match.descriptor, context.requestContext, context.observers, context.contentNegotiation, context.options.binder, context.options.interceptors, context.options.logger);
+      await dispatchMatchedHandler(match.descriptor, executionPlan, context.requestContext, context.dispatchScope.container, context.observers, context.contentNegotiation, context.options.binder, context.options.logger);
     });
-  });
+  };
+  const appMiddleware = context.options.appMiddleware ?? [];
+  if (appMiddleware.length === 0) {
+    await dispatchMatchedRoute();
+    return;
+  }
+  await runMiddlewareChain(appMiddleware, appMiddlewareContext, dispatchMatchedRoute);
 }
 async function handleDispatchError(context, error) {
-  if (error instanceof RequestAbortedError || context.requestContext.request.signal?.aborted) {
+  if (error instanceof RequestAbortedError || isRequestAborted(context.requestContext.request)) {
     return;
   }
   await notifyRequestError(context, error);
@@ -167,30 +524,89 @@ async function handleDispatchError(context, error) {
  */
 export function createDispatcher(options) {
   const contentNegotiation = resolveContentNegotiation(options.contentNegotiation);
-  return {
+  const observers = options.observers ?? [];
+  const appMiddleware = options.appMiddleware ?? [];
+  const dispatchStartPlan = compileDispatchStartPlan(observers, appMiddleware);
+  const fastPathRuntimeCache = new WeakMap();
+  const handlerExecutionPlans = new WeakMap();
+  const adapter = options.adapter ?? 'default';
+  const fastPathEligibilities = [];
+  for (const descriptor of options.handlerMapping.descriptors) {
+    handlerExecutionPlans.set(descriptor, compileHandlerExecutionPlan(descriptor, options));
+    const {
+      eligibility
+    } = compileFastPathEligibility(descriptor, options, adapter);
+    setHandlerFastPathEligibility(descriptor, eligibility);
+    fastPathEligibilities.push(eligibility);
+  }
+  const fastPathStats = createFastPathStats(fastPathEligibilities);
+  const dispatcher = {
+    describeRoutes() {
+      return options.handlerMapping.descriptors.map(descriptor => cloneHandlerDescriptor(descriptor));
+    },
+    async dispatchNativeRoute(match, request, response) {
+      return dispatchNativeFastRoute(match, request, response, options, contentNegotiation, fastPathRuntimeCache);
+    },
     async dispatch(request, response) {
-      const phaseContext = {
+      const dispatchRequest = createDispatchRequest(request);
+      const dispatchScope = dispatchStartMayRequireRequestScope(dispatchStartPlan, dispatchRequest) ? createRequestDispatchScope(options.rootContainer) : createRootDispatchScope(options.rootContainer);
+      let phaseContext;
+      let containerPromotionOpen = true;
+      const requestContext = createDispatchContext(dispatchRequest, response, dispatchScope.container, () => {
+        if (!containerPromotionOpen) {
+          return phaseContext.dispatchScope.container;
+        }
+        ensureRequestScope(phaseContext);
+        return phaseContext.dispatchScope.container;
+      });
+      phaseContext = {
         contentNegotiation,
-        observers: options.observers ?? [],
+        dispatchScope,
+        fastPathRuntimeCache,
+        handlerExecutionPlans,
+        observers,
         options,
-        requestContext: createDispatchContext(createDispatchRequest(request), response, options.rootContainer),
+        requestContext,
         response
       };
       await runWithRequestContext(phaseContext.requestContext, async () => {
         try {
-          await notifyRequestStart(phaseContext);
+          if (observers.length > 0) {
+            await notifyRequestStart(phaseContext);
+          }
           await runDispatchPipeline(phaseContext);
         } catch (error) {
           await handleDispatchError(phaseContext, error);
         } finally {
-          await notifyRequestFinish(phaseContext);
-          try {
-            await phaseContext.requestContext.container.dispose();
-          } catch (error) {
-            logDispatchFailure(options.logger, 'Request-scoped container dispose threw an error.', error);
+          if (observers.length > 0) {
+            await notifyRequestFinish(phaseContext);
+          }
+          if (!phaseContext.dispatchScope.requestScoped) {
+            phaseContext.requestContext.container = phaseContext.dispatchScope.container;
+          }
+          containerPromotionOpen = false;
+          if (phaseContext.dispatchScope.requestScoped) {
+            try {
+              await phaseContext.dispatchScope.container.dispose();
+            } catch (error) {
+              logDispatchFailure(options.logger, 'Request-scoped container dispose threw an error.', error);
+            }
           }
         }
       });
     }
   };
-}
+  dispatcher[FAST_PATH_STATS_SYMBOL] = fastPathStats;
+  return dispatcher;
+}
+
+/**
+ * Reads automatic fast-path eligibility statistics attached to a dispatcher.
+ *
+ * @param dispatcher Dispatcher returned by {@link createDispatcher}.
+ * @returns Fast-path statistics when available.
+ */
+export function getDispatcherFastPathStats(dispatcher) {
+  return dispatcher[FAST_PATH_STATS_SYMBOL];
+}
+export { formatFastPathStats } from './fast-path/index.js';

package/dist/dispatch/fast-path/debug-visibility.d.ts

@@ -0,0 +1,18 @@
+import type { FastPathEligibility, FastPathStats } from './eligibility.js';
+interface PathDebugInfo {
+    executionPath: 'fast' | 'full';
+    fallbackReason?: string;
+    routeId: string;
+}
+export declare function createPathDebugInfo(eligibility: FastPathEligibility): PathDebugInfo;
+export declare function addPathDebugHeader(setHeader: (name: string, value: string) => void, info: PathDebugInfo): void;
+export declare function createFastPathStats(eligibilities: readonly FastPathEligibility[]): FastPathStats;
+/**
+ * Formats dispatcher fast-path statistics for debug logs and benchmark output.
+ *
+ * @param stats Fast-path statistics returned by {@link getDispatcherFastPathStats}.
+ * @returns A human-readable route breakdown.
+ */
+export declare function formatFastPathStats(stats: FastPathStats): string;
+export {};
+//# sourceMappingURL=debug-visibility.d.ts.map

package/dist/dispatch/fast-path/debug-visibility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug-visibility.d.ts","sourceRoot":"","sources":["../../../src/dispatch/fast-path/debug-visibility.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAI3E,UAAU,aAAa;IACrB,aAAa,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,mBAAmB,GAAG,aAAa,CAMnF;AAED,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,EAChD,IAAI,EAAE,aAAa,GAClB,IAAI,CAMN;AAED,wBAAgB,mBAAmB,CAAC,aAAa,EAAE,SAAS,mBAAmB,EAAE,GAAG,aAAa,CAShG;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAuBhE"}

package/dist/dispatch/fast-path/debug-visibility.js

@@ -0,0 +1,39 @@
+const DEBUG_HEADER_NAME = 'X-Fluo-Path';
+export function createPathDebugInfo(eligibility) {
+  return {
+    executionPath: eligibility.executionPath,
+    fallbackReason: eligibility.fallbackReason,
+    routeId: eligibility.routeId
+  };
+}
+export function addPathDebugHeader(setHeader, info) {
+  const value = info.executionPath === 'fast' ? `fast; route=${info.routeId}` : `full; route=${info.routeId}; reason=${info.fallbackReason ?? 'none'}`;
+  setHeader(DEBUG_HEADER_NAME, value);
+}
+export function createFastPathStats(eligibilities) {
+  const fastPathRoutes = eligibilities.filter(e => e.executionPath === 'fast').length;
+  return {
+    fastPathRoutes,
+    fullPathRoutes: eligibilities.length - fastPathRoutes,
+    routes: eligibilities,
+    totalRoutes: eligibilities.length
+  };
+}
+
+/**
+ * Formats dispatcher fast-path statistics for debug logs and benchmark output.
+ *
+ * @param stats Fast-path statistics returned by {@link getDispatcherFastPathStats}.
+ * @returns A human-readable route breakdown.
+ */
+export function formatFastPathStats(stats) {
+  const fastPathPercent = stats.totalRoutes === 0 ? '0.0' : (stats.fastPathRoutes / stats.totalRoutes * 100).toFixed(1);
+  const fullPathPercent = stats.totalRoutes === 0 ? '0.0' : (stats.fullPathRoutes / stats.totalRoutes * 100).toFixed(1);
+  const lines = ['=== Fast Path Statistics ===', `Total routes: ${String(stats.totalRoutes)}`, `Fast path: ${String(stats.fastPathRoutes)} (${fastPathPercent}%)`, `Full path: ${String(stats.fullPathRoutes)} (${fullPathPercent}%)`, '', 'Route breakdown:'];
+  for (const route of stats.routes) {
+    const status = route.executionPath === 'fast' ? 'FAST' : 'FULL';
+    const reason = route.fallbackReason ? ` (${route.fallbackReason})` : '';
+    lines.push(`  [${status}] ${route.routeId}${reason}`);
+  }
+  return lines.join('\n');
+}