@fragno-dev/core 0.1.11 → 0.2.2

package/src/api/fragment-instantiator.ts

@@ -1,10 +1,26 @@
+import { addRoute, createRouter, findRoute } from "rou3";
+
 import type { StandardSchemaV1 } from "@standard-schema/spec";
+
+import type { ExtractRouteByPath, ExtractRoutePath } from "../client/client";
+import { instantiatedFragmentFakeSymbol } from "../internal/symbols";
+import { recordTraceEvent } from "../internal/trace-context";
+import type { InferOrUnknown } from "../util/types-util";
 import { type FragnoRouteConfig, type HTTPMethod, type RequestThisContext } from "./api";
+import { bindServicesToContext, type BoundServices } from "./bind-services";
 import { FragnoApiError } from "./error";
+import type { FragmentDefinition } from "./fragment-definition-builder";
+import { type FragnoResponse, parseFragnoResponse } from "./fragno-response";
+import type { ExtractPathParams } from "./internal/path";
 import { getMountRoute } from "./internal/route";
-import { addRoute, createRouter, findRoute } from "rou3";
+import { MutableRequestState } from "./mutable-request-state";
+import { RequestContextStorage } from "./request-context-storage";
 import { RequestInputContext, type RequestBodyType } from "./request-input-context";
-import type { ExtractPathParams } from "./internal/path";
+import {
+  RequestMiddlewareInputContext,
+  RequestMiddlewareOutputContext,
+  type FragnoMiddlewareCallback,
+} from "./request-middleware";
 import { RequestOutputContext } from "./request-output-context";
 import {
   type AnyFragnoRouteConfig,
@@ -12,25 +28,98 @@ import {
   type FlattenRouteFactories,
   resolveRouteFactories,
 } from "./route";
-import {
-  RequestMiddlewareInputContext,
-  RequestMiddlewareOutputContext,
-  type FragnoMiddlewareCallback,
-} from "./request-middleware";
-import { MutableRequestState } from "./mutable-request-state";
 import type { RouteHandlerInputOptions } from "./route-handler-input-options";
-import type { ExtractRouteByPath, ExtractRoutePath } from "../client/client";
-import { type FragnoResponse, parseFragnoResponse } from "./fragno-response";
-import type { InferOrUnknown } from "../util/types-util";
-import type { FragmentDefinition } from "./fragment-definition-builder";
 import type { FragnoPublicConfig } from "./shared-types";
-import { RequestContextStorage } from "./request-context-storage";
-import { bindServicesToContext, type BoundServices } from "./bind-services";
-import { instantiatedFragmentFakeSymbol } from "../internal/symbols";
 
 // Re-export types needed by consumers
 export type { BoundServices };
 
+type CallRoutePath<TRoutes extends readonly AnyFragnoRouteConfig[], TMethod extends HTTPMethod> = [
+  ExtractRoutePath<TRoutes, TMethod>,
+] extends [never]
+  ? string
+  : ExtractRoutePath<TRoutes, TMethod>;
+
+type CallRouteMatch<
+  TRoutes extends readonly AnyFragnoRouteConfig[],
+  TMethod extends HTTPMethod,
+  TPath extends string,
+> = [ExtractRouteByPath<TRoutes, TPath, TMethod>] extends [never]
+  ? AnyFragnoRouteConfig
+  : ExtractRouteByPath<TRoutes, TPath, TMethod>;
+
+const requestSourceSymbol = Symbol.for("fragno-request-source");
+const requestRouteSymbol = Symbol.for("fragno-request-route");
+const requestWaitUntilSymbol = Symbol.for("fragno-request-wait-until");
+
+type RequestRouteInfo = {
+  method: HTTPMethod;
+  path: string;
+  mountRoute?: string;
+  fullPath?: string;
+};
+type RequestSource = "route" | "context";
+
+export type FragnoRequestLifecycleContext = {
+  waitUntil?: (promise: Promise<unknown>) => void;
+};
+
+type InternalRoutePrefix = "/_internal";
+
+type JoinInternalRoutePath<TPath extends string> = TPath extends "" | "/"
+  ? InternalRoutePrefix
+  : TPath extends `/${string}`
+    ? `${InternalRoutePrefix}${TPath}`
+    : `${InternalRoutePrefix}/${TPath}`;
+
+type PrefixInternalRoute<TRoute> =
+  TRoute extends FragnoRouteConfig<
+    infer TMethod,
+    infer TPath,
+    infer TInputSchema,
+    infer TOutputSchema,
+    infer TErrorCode,
+    infer TQueryParameters,
+    infer TThisContext
+  >
+    ? FragnoRouteConfig<
+        TMethod,
+        JoinInternalRoutePath<TPath>,
+        TInputSchema,
+        TOutputSchema,
+        TErrorCode,
+        TQueryParameters,
+        TThisContext
+      >
+    : never;
+
+type PrefixInternalRoutes<TRoutes extends readonly AnyFragnoRouteConfig[]> =
+  TRoutes extends readonly [...infer TRoutesTuple]
+    ? { [K in keyof TRoutesTuple]: PrefixInternalRoute<TRoutesTuple[K]> }
+    : readonly AnyFragnoRouteConfig[];
+
+type InternalRoutesFromDefinition<TInternalRoutes extends readonly AnyRouteOrFactory[]> =
+  PrefixInternalRoutes<FlattenRouteFactories<TInternalRoutes>>;
+
+export type RoutesWithInternal<
+  TRoutes extends readonly AnyFragnoRouteConfig[],
+  TInternalRoutes extends readonly AnyRouteOrFactory[],
+> = readonly [...TRoutes, ...InternalRoutesFromDefinition<TInternalRoutes>];
+
+type ExtractServiceCallResult<T> = T extends undefined
+  ? undefined
+  : T extends { _internal: { finalResult?: infer R } }
+    ? R
+    : Awaited<T>;
+
+type ExtractServiceCallResults<T extends readonly unknown[]> = {
+  [K in keyof T]: ExtractServiceCallResult<T[K]>;
+};
+
+type ExtractServiceCallResultsOrSingle<T> = T extends readonly unknown[]
+  ? ExtractServiceCallResults<T>
+  : ExtractServiceCallResult<T>;
+
 /**
  * Helper type to extract the instantiated fragment type from a fragment definition.
  * This is useful for typing functions that accept instantiated fragments based on their definition.
@@ -56,17 +145,16 @@ export type InstantiatedFragmentFromDefinition<
     infer TServiceThisContext,
     infer THandlerThisContext,
     infer TRequestStorage,
-    infer TLinkedFragments
+    infer TInternalRoutes
   >
     ? FragnoInstantiatedFragment<
-        readonly AnyFragnoRouteConfig[], // Routes are dynamic, so we use a generic array
+        RoutesWithInternal<readonly AnyFragnoRouteConfig[], TInternalRoutes>,
         TDeps,
         BoundServices<TBaseServices & TServices>,
         TServiceThisContext,
         THandlerThisContext,
         TRequestStorage,
-        TOptions,
-        TLinkedFragments
+        TOptions
       >
     : never;
 
@@ -79,6 +167,34 @@ type ReactRouterHandlers = {
   action: (args: { request: Request }) => Promise<Response>;
 };
 
+const serializeHeadersForTrace = (headers: Headers): [string, string][] =>
+  Array.from(headers.entries()).sort(([a], [b]) => a.localeCompare(b));
+
+const serializeQueryForTrace = (query: URLSearchParams): [string, string][] =>
+  Array.from(query.entries()).sort(([a], [b]) => a.localeCompare(b));
+
+const serializeBodyForTrace = (body: RequestBodyType): unknown => {
+  if (body instanceof FormData) {
+    const entries = Array.from(body.entries()).map(([key, value]) => {
+      if (value instanceof Blob) {
+        return [key, { type: "blob", size: value.size, mime: value.type }] as const;
+      }
+      return [key, value] as const;
+    });
+    return { type: "form-data", entries };
+  }
+
+  if (body instanceof Blob) {
+    return { type: "blob", size: body.size, mime: body.type };
+  }
+
+  if (body instanceof ReadableStream) {
+    return { type: "stream" };
+  }
+
+  return body;
+};
+
 type SolidStartHandlers = {
   GET: (args: { request: Request }) => Promise<Response>;
   POST: (args: { request: Request }) => Promise<Response>;
@@ -126,11 +242,27 @@ export type AnyFragnoInstantiatedFragment = FragnoInstantiatedFragment<
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   any,
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  any,
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   any
 >;
 
+const INTERNAL_ROUTE_PREFIX = "/_internal";
+
+function normalizeRoutePrefix(prefix: string): string {
+  if (!prefix.startsWith("/")) {
+    prefix = `/${prefix}`;
+  }
+  return prefix.endsWith("/") && prefix.length > 1 ? prefix.slice(0, -1) : prefix;
+}
+
+function joinRoutePath(prefix: string, path: string): string {
+  const normalizedPrefix = normalizeRoutePrefix(prefix);
+  if (!path || path === "/") {
+    return normalizedPrefix;
+  }
+  const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+  return `${normalizedPrefix}${normalizedPath}`;
+}
+
 export interface FragnoFragmentSharedConfig<
   TRoutes extends readonly FragnoRouteConfig<
     HTTPMethod,
@@ -157,9 +289,7 @@ export class FragnoInstantiatedFragment<
   THandlerThisContext extends RequestThisContext,
   TRequestStorage = {},
   TOptions extends FragnoPublicConfig = FragnoPublicConfig,
-  TLinkedFragments extends Record<string, AnyFragnoInstantiatedFragment> = {},
-> implements IFragnoInstantiatedFragment
-{
+> implements IFragnoInstantiatedFragment {
   readonly [instantiatedFragmentFakeSymbol] = instantiatedFragmentFakeSymbol;
 
   // Private fields
@@ -175,7 +305,7 @@ export class FragnoInstantiatedFragment<
   #contextStorage: RequestContextStorage<TRequestStorage>;
   #createRequestStorage?: () => TRequestStorage;
   #options: TOptions;
-  #linkedFragments: TLinkedFragments;
+  #internalData: Record<string, unknown>;
 
   constructor(params: {
     name: string;
@@ -188,7 +318,7 @@ export class FragnoInstantiatedFragment<
     storage: RequestContextStorage<TRequestStorage>;
     createRequestStorage?: () => TRequestStorage;
     options: TOptions;
-    linkedFragments?: TLinkedFragments;
+    internalData?: Record<string, unknown>;
   }) {
     this.#name = params.name;
     this.#routes = params.routes;
@@ -200,7 +330,7 @@ export class FragnoInstantiatedFragment<
     this.#contextStorage = params.storage;
     this.#createRequestStorage = params.createRequestStorage;
     this.#options = params.options;
-    this.#linkedFragments = params.linkedFragments ?? ({} as TLinkedFragments);
+    this.#internalData = params.internalData ?? {};
 
     // Build router
     this.#router =
@@ -248,7 +378,7 @@ export class FragnoInstantiatedFragment<
     return {
       deps: this.#deps,
       options: this.#options,
-      linkedFragments: this.#linkedFragments,
+      ...this.#internalData,
     };
   }
 
@@ -269,9 +399,24 @@ export class FragnoInstantiatedFragment<
    * This is a shared helper used by inContext(), handler(), and callRouteRaw().
    * @private
    */
-  #withRequestStorage<T>(callback: () => T): T;
-  #withRequestStorage<T>(callback: () => Promise<T>): Promise<T>;
-  #withRequestStorage<T>(callback: () => T | Promise<T>): T | Promise<T> {
+  #withRequestStorage<T>(
+    callback: () => T,
+    source?: RequestSource,
+    routeInfo?: RequestRouteInfo,
+    lifecycleContext?: FragnoRequestLifecycleContext,
+  ): T;
+  #withRequestStorage<T>(
+    callback: () => Promise<T>,
+    source?: RequestSource,
+    routeInfo?: RequestRouteInfo,
+    lifecycleContext?: FragnoRequestLifecycleContext,
+  ): Promise<T>;
+  #withRequestStorage<T>(
+    callback: () => T | Promise<T>,
+    source: RequestSource = "context",
+    routeInfo?: RequestRouteInfo,
+    lifecycleContext?: FragnoRequestLifecycleContext,
+  ): T | Promise<T> {
     if (!this.#serviceThisContext && !this.#handlerThisContext) {
       // No request context configured - just run callback directly
       return callback();
@@ -281,6 +426,16 @@ export class FragnoInstantiatedFragment<
     const storageData = this.#createRequestStorage
       ? this.#createRequestStorage()
       : ({} as TRequestStorage);
+    if (storageData && typeof storageData === "object") {
+      const metadataTarget = storageData as Record<symbol, unknown>;
+      metadataTarget[requestSourceSymbol] = source;
+      if (routeInfo) {
+        metadataTarget[requestRouteSymbol] = routeInfo;
+      }
+      if (lifecycleContext?.waitUntil) {
+        metadataTarget[requestWaitUntilSymbol] = lifecycleContext.waitUntil;
+      }
+    }
     return this.#contextStorage.run(storageData, callback);
   }
 
@@ -308,9 +463,55 @@ export class FragnoInstantiatedFragment<
     // Always use handler context for inContext - it has full capabilities
     if (this.#handlerThisContext) {
       const boundCallback = callback.bind(this.#handlerThisContext);
-      return this.#withRequestStorage(boundCallback);
+      return this.#withRequestStorage(boundCallback, "context");
+    }
+    return this.#withRequestStorage(callback, "context");
+  }
+
+  /**
+   * Execute multiple service calls within a handler context.
+   * If called outside a request context, it will create one automatically.
+   * Pass a factory so service calls are created inside the active context.
+   * Primarily used by database fragments (handlerTx).
+   */
+  async callServices<TServiceCalls>(
+    serviceCalls: () => TServiceCalls,
+  ): Promise<ExtractServiceCallResultsOrSingle<TServiceCalls>> {
+    const handlerContext = this.#handlerThisContext as
+      | {
+          handlerTx?: () => {
+            withServiceCalls: (fn: () => readonly unknown[]) => { execute: () => Promise<unknown> };
+          };
+        }
+      | undefined;
+
+    if (!handlerContext?.handlerTx) {
+      throw new Error(
+        "callServices is only supported for fragments with handlerTx (database fragments).",
+      );
+    }
+
+    let callWasArray = false;
+    const execute = () => {
+      return handlerContext.handlerTx!()
+        .withServiceCalls(() => {
+          const calls = serviceCalls();
+          callWasArray = Array.isArray(calls);
+          return (callWasArray ? calls : [calls]) as readonly unknown[];
+        })
+        .execute();
+    };
+
+    const result = this.#contextStorage.hasStore()
+      ? await execute()
+      : await this.#withRequestStorage(execute, "context");
+
+    if (callWasArray) {
+      return result as ExtractServiceCallResultsOrSingle<TServiceCalls>;
     }
-    return this.#withRequestStorage(callback);
+
+    const [first] = result as unknown[];
+    return first as ExtractServiceCallResultsOrSingle<TServiceCalls>;
   }
 
   /**
@@ -379,7 +580,7 @@ export class FragnoInstantiatedFragment<
    * Main request handler for this fragment.
    * Handles routing, middleware, and error handling.
    */
-  async handler(req: Request): Promise<Response> {
+  async handler(req: Request, lifecycleContext?: FragnoRequestLifecycleContext): Promise<Response> {
     const url = new URL(req.url);
     const pathname = url.pathname;
 
@@ -409,44 +610,112 @@ export class FragnoInstantiatedFragment<
       );
     }
 
-    // Parse request body
+    // Get the expected content type from route config (default: application/json)
+    const routeConfig = route.data as AnyFragnoRouteConfig;
+    const expectedContentType = routeConfig.contentType ?? "application/json";
+
+    // Parse request body based on route's expected content type
     let requestBody: RequestBodyType = undefined;
     let rawBody: string | undefined = undefined;
 
     if (req.body instanceof ReadableStream) {
-      // Clone request to make sure we don't consume body stream
-      const clonedReq = req.clone();
-
-      // Get raw text
-      rawBody = await clonedReq.text();
+      const requestContentType = (req.headers.get("content-type") ?? "").toLowerCase();
+
+      if (expectedContentType === "multipart/form-data") {
+        // Route expects FormData (file uploads)
+        if (!requestContentType.includes("multipart/form-data")) {
+          return Response.json(
+            {
+              error: `This endpoint expects multipart/form-data, but received: ${requestContentType || "no content-type"}`,
+              code: "UNSUPPORTED_MEDIA_TYPE",
+            },
+            { status: 415 },
+          );
+        }
 
-      // Parse JSON if body is not empty
-      if (rawBody) {
         try {
-          requestBody = JSON.parse(rawBody);
+          requestBody = await req.formData();
         } catch {
-          // If JSON parsing fails, keep body as undefined
-          // This handles cases where body is not JSON
-          requestBody = undefined;
+          return Response.json(
+            { error: "Failed to parse multipart form data", code: "INVALID_REQUEST_BODY" },
+            { status: 400 },
+          );
+        }
+      } else if (expectedContentType === "application/octet-stream") {
+        if (!requestContentType.includes("application/octet-stream")) {
+          return Response.json(
+            {
+              error: `This endpoint expects application/octet-stream, but received: ${requestContentType || "no content-type"}`,
+              code: "UNSUPPORTED_MEDIA_TYPE",
+            },
+            { status: 415 },
+          );
+        }
+
+        requestBody = req.body ?? new ReadableStream<Uint8Array>();
+      } else {
+        // Route expects JSON (default)
+        // Note: We're lenient here - we accept requests without Content-Type header
+        // or with application/json. We reject multipart/form-data for JSON routes.
+        if (requestContentType.includes("multipart/form-data")) {
+          return Response.json(
+            {
+              error: `This endpoint expects JSON, but received multipart/form-data. Use a route with contentType: "multipart/form-data" for file uploads.`,
+              code: "UNSUPPORTED_MEDIA_TYPE",
+            },
+            { status: 415 },
+          );
+        }
+
+        // Clone request to make sure we don't consume body stream
+        const clonedReq = req.clone();
+
+        // Get raw text
+        rawBody = await clonedReq.text();
+
+        // Parse JSON if body is not empty
+        if (rawBody) {
+          try {
+            requestBody = JSON.parse(rawBody);
+          } catch {
+            // If JSON parsing fails, keep body as undefined
+            // This handles cases where body is not JSON
+            requestBody = undefined;
+          }
         }
       }
     }
 
+    // URL decode path params from rou3 (which returns encoded values)
+    const decodedRouteParams: Record<string, string> = {};
+    for (const [key, value] of Object.entries(route.params ?? {})) {
+      decodedRouteParams[key] = decodeURIComponent(value);
+    }
+
     const requestState = new MutableRequestState({
-      pathParams: route.params ?? {},
+      pathParams: decodedRouteParams,
       searchParams: url.searchParams,
       body: requestBody,
       headers: new Headers(req.headers),
     });
 
+    const fullRoutePath =
+      this.#mountRoute && this.#mountRoute !== "/"
+        ? `${this.#mountRoute}${routeConfig.path}`
+        : routeConfig.path;
+    const routeInfo: RequestRouteInfo = {
+      method: routeConfig.method,
+      path: routeConfig.path,
+      mountRoute: this.#mountRoute,
+      fullPath: fullRoutePath,
+    };
+
     // Execute middleware and handler
     const executeRequest = async (): Promise<Response> => {
-      // Middleware execution (if present)
-      if (this.#middlewareHandler) {
-        const middlewareResult = await this.#executeMiddleware(req, route, requestState);
-        if (middlewareResult !== undefined) {
-          return middlewareResult;
-        }
+      // Parent middleware execution
+      const middlewareResult = await this.#executeMiddleware(req, route, requestState);
+      if (middlewareResult !== undefined) {
+        return middlewareResult;
       }
 
       // Handler execution
@@ -454,23 +723,23 @@ export class FragnoInstantiatedFragment<
     };
 
     // Wrap with request storage context if provided
-    return this.#withRequestStorage(executeRequest);
+    return this.#withRequestStorage(executeRequest, "route", routeInfo, lifecycleContext);
   }
 
   /**
    * Call a route directly with typed inputs and outputs.
    * Useful for testing and server-side route calls.
    */
-  async callRoute<TMethod extends HTTPMethod, TPath extends ExtractRoutePath<TRoutes, TMethod>>(
+  async callRoute<TMethod extends HTTPMethod, TPath extends CallRoutePath<TRoutes, TMethod>>(
     method: TMethod,
     path: TPath,
     inputOptions?: RouteHandlerInputOptions<
       TPath,
-      ExtractRouteByPath<TRoutes, TPath, TMethod>["inputSchema"]
+      CallRouteMatch<TRoutes, TMethod, TPath>["inputSchema"]
     >,
   ): Promise<
     FragnoResponse<
-      InferOrUnknown<NonNullable<ExtractRouteByPath<TRoutes, TPath, TMethod>["outputSchema"]>>
+      InferOrUnknown<NonNullable<CallRouteMatch<TRoutes, TMethod, TPath>["outputSchema"]>>
     >
   > {
     const response = await this.callRouteRaw(method, path, inputOptions);
@@ -481,12 +750,12 @@ export class FragnoInstantiatedFragment<
    * Call a route directly and get the raw Response object.
    * Useful for testing and server-side route calls.
    */
-  async callRouteRaw<TMethod extends HTTPMethod, TPath extends ExtractRoutePath<TRoutes, TMethod>>(
+  async callRouteRaw<TMethod extends HTTPMethod, TPath extends CallRoutePath<TRoutes, TMethod>>(
     method: TMethod,
     path: TPath,
     inputOptions?: RouteHandlerInputOptions<
       TPath,
-      ExtractRouteByPath<TRoutes, TPath, TMethod>["inputSchema"]
+      CallRouteMatch<TRoutes, TMethod, TPath>["inputSchema"]
     >,
   ): Promise<Response> {
     // Find route in this.#routes
@@ -502,7 +771,8 @@ export class FragnoInstantiatedFragment<
       );
     }
 
-    const { pathParams = {}, body, query, headers } = inputOptions || {};
+    const { pathParams = {}, query, headers } = inputOptions || {};
+    const body = inputOptions && "body" in inputOptions ? inputOptions.body : undefined;
 
     // Convert query to URLSearchParams if needed
     const searchParams =
@@ -527,9 +797,30 @@ export class FragnoInstantiatedFragment<
       shouldValidateInput: true, // Enable validation for production use
     });
 
+    recordTraceEvent({
+      type: "route-input",
+      method: route.method,
+      path: route.path,
+      pathParams: (pathParams ?? {}) as Record<string, string>,
+      queryParams: serializeQueryForTrace(searchParams),
+      headers: serializeHeadersForTrace(requestHeaders),
+      body: serializeBodyForTrace(body),
+    });
+
     // Construct RequestOutputContext
     const outputContext = new RequestOutputContext(route.outputSchema);
 
+    const fullRoutePath =
+      this.#mountRoute && this.#mountRoute !== "/"
+        ? `${this.#mountRoute}${route.path}`
+        : route.path;
+    const routeInfo: RequestRouteInfo = {
+      method: route.method,
+      path: route.path,
+      mountRoute: this.#mountRoute,
+      fullPath: fullRoutePath,
+    };
+
     // Execute handler
     const executeHandler = async (): Promise<Response> => {
       try {
@@ -551,7 +842,7 @@ export class FragnoInstantiatedFragment<
     };
 
     // Wrap with request storage context if provided
-    return this.#withRequestStorage(executeHandler);
+    return this.#withRequestStorage(executeHandler, "route", routeInfo);
   }
 
   /**
@@ -563,32 +854,73 @@ export class FragnoInstantiatedFragment<
     route: ReturnType<typeof findRoute>,
     requestState: MutableRequestState,
   ): Promise<Response | undefined> {
-    if (!this.#middlewareHandler || !route) {
+    if (!route) {
       return undefined;
     }
 
     const { path } = route.data as AnyFragnoRouteConfig;
-
-    const middlewareInputContext = new RequestMiddlewareInputContext(this.#routes, {
+    return FragnoInstantiatedFragment.#runMiddlewareForFragment(this, {
+      req,
       method: req.method as HTTPMethod,
       path,
-      request: req,
-      state: requestState,
+      requestState,
     });
+  }
+
+  static async #runMiddlewareForFragment(
+    fragment: AnyFragnoInstantiatedFragment,
+    options: {
+      req: Request;
+      method: HTTPMethod;
+      path: string;
+      requestState: MutableRequestState;
+      routes?: readonly AnyFragnoRouteConfig[];
+    },
+  ): Promise<Response | undefined> {
+    if (!fragment.#middlewareHandler) {
+      return undefined;
+    }
 
-    const middlewareOutputContext = new RequestMiddlewareOutputContext(this.#deps, this.#services);
+    const middlewareInputContext = new RequestMiddlewareInputContext(
+      (options.routes ?? fragment.#routes) as readonly AnyFragnoRouteConfig[],
+      {
+        method: options.method,
+        path: options.path,
+        request: options.req,
+        state: options.requestState,
+      },
+    );
+
+    const middlewareOutputContext = new RequestMiddlewareOutputContext(
+      fragment.#deps,
+      fragment.#services,
+    );
 
     try {
-      const middlewareResult = await this.#middlewareHandler(
+      const middlewareResult = await fragment.#middlewareHandler(
         middlewareInputContext,
         middlewareOutputContext,
       );
+      recordTraceEvent({
+        type: "middleware-decision",
+        method: options.method,
+        path: options.path,
+        outcome: middlewareResult ? "deny" : "allow",
+        status: middlewareResult?.status,
+      });
       if (middlewareResult !== undefined) {
         return middlewareResult;
       }
     } catch (error) {
       console.error("Error in middleware", error);
 
+      recordTraceEvent({
+        type: "middleware-decision",
+        method: options.method,
+        path: options.path,
+        outcome: "deny",
+        status: error instanceof FragnoApiError ? error.status : 500,
+      });
       if (error instanceof FragnoApiError) {
         return error.toResponse();
       }
@@ -627,6 +959,16 @@ export class FragnoInstantiatedFragment<
       rawBody,
     });
 
+    recordTraceEvent({
+      type: "route-input",
+      method: req.method,
+      path,
+      pathParams: inputContext.pathParams as Record<string, string>,
+      queryParams: serializeQueryForTrace(requestState.searchParams),
+      headers: serializeHeadersForTrace(requestState.headers),
+      body: serializeBodyForTrace(requestState.body),
+    });
+
     const outputContext = new RequestOutputContext(outputSchema);
 
     try {
@@ -679,7 +1021,7 @@ export function instantiateFragment<
   const THandlerThisContext extends RequestThisContext,
   const TRequestStorage,
   const TRoutesOrFactories extends readonly AnyRouteOrFactory[],
-  const TLinkedFragments extends Record<string, AnyFragnoInstantiatedFragment>,
+  const TInternalRoutes extends readonly AnyRouteOrFactory[],
 >(
   definition: FragmentDefinition<
     TConfig,
@@ -692,7 +1034,7 @@ export function instantiateFragment<
     TServiceThisContext,
     THandlerThisContext,
     TRequestStorage,
-    TLinkedFragments
+    TInternalRoutes
   >,
   config: TConfig,
   routesOrFactories: TRoutesOrFactories,
@@ -700,14 +1042,13 @@ export function instantiateFragment<
   serviceImplementations?: TServiceDependencies,
   instantiationOptions?: InstantiationOptions,
 ): FragnoInstantiatedFragment<
-  FlattenRouteFactories<TRoutesOrFactories>,
+  RoutesWithInternal<FlattenRouteFactories<TRoutesOrFactories>, TInternalRoutes>,
   TDeps,
   BoundServices<TBaseServices & TServices>,
   TServiceThisContext,
   THandlerThisContext,
   TRequestStorage,
-  TOptions,
-  TLinkedFragments
+  TOptions
 > {
   const { dryRun = false } = instantiationOptions ?? {};
 
@@ -742,36 +1083,18 @@ export function instantiateFragment<
     }
   }
 
-  // 3. Instantiate linked fragments FIRST (before any services)
-  // Their services will be merged into private services
-  const linkedFragmentInstances = {} as TLinkedFragments;
-  const linkedFragmentServices: Record<string, unknown> = {};
-
-  if (definition.linkedFragments) {
-    for (const [name, callback] of Object.entries(definition.linkedFragments)) {
-      const linkedFragment = callback({
-        config,
-        options,
-        serviceDependencies: serviceImplementations,
-      });
-      (linkedFragmentInstances as Record<string, AnyFragnoInstantiatedFragment>)[name] =
-        linkedFragment;
-
-      // Merge all services from linked fragment into private services directly by their service name
-      const services = linkedFragment.services as Record<string, unknown>;
-      for (const [serviceName, service] of Object.entries(services)) {
-        linkedFragmentServices[serviceName] = service;
-      }
-    }
-  }
+  // 3. Calculate mount route early so internal routes can reference it
+  const mountRoute = getMountRoute({
+    name: definition.name,
+    mountRoute: options.mountRoute,
+  });
 
-  // Identity function for service definition (used to set 'this' context)
+  // 4. Identity function for service definition (used to set 'this' context)
   const defineService = <T>(services: T & ThisType<TServiceThisContext>): T => services;
 
-  // 4. Call privateServices factories
+  // 5. Call privateServices factories
   // Private services are instantiated in order, so earlier ones are available to later ones
-  // Start with linked fragment services, then add explicitly defined private services
-  const privateServices = { ...linkedFragmentServices } as TPrivateServices;
+  const privateServices = {} as TPrivateServices;
   if (definition.privateServices) {
     for (const [serviceName, factory] of Object.entries(definition.privateServices)) {
       const serviceFactory = factory as (context: {
@@ -806,7 +1129,7 @@ export function instantiateFragment<
     }
   }
 
-  // 5. Call baseServices callback (with access to private services including linked fragment services)
+  // 6. Call baseServices callback (with access to private services)
   let baseServices: TBaseServices;
   try {
     baseServices =
@@ -830,7 +1153,7 @@ export function instantiateFragment<
     }
   }
 
-  // 6. Call namedServices factories (with access to private services including linked fragment services)
+  // 7. Call namedServices factories (with access to private services)
   const namedServices = {} as TServices;
   if (definition.namedServices) {
     for (const [serviceName, factory] of Object.entries(definition.namedServices)) {
@@ -866,13 +1189,13 @@ export function instantiateFragment<
     }
   }
 
-  // 7. Merge public services (NOT including private services)
+  // 8. Merge public services (NOT including private services)
   const services = {
     ...baseServices,
     ...namedServices,
   };
 
-  // 8. Create request context storage and both service & handler contexts
+  // 9. Create request context storage and both service & handler contexts
   // Use external storage if provided, otherwise create new storage
   const storage = definition.getExternalStorage
     ? definition.getExternalStorage({ config, options, deps })
@@ -889,24 +1212,37 @@ export function instantiateFragment<
   const serviceContext = contexts?.serviceContext;
   const handlerContext = contexts?.handlerContext;
 
-  // 9. Bind services to serviceContext (restricted)
+  // 10. Bind services to serviceContext (restricted)
   // Services get the restricted context (for database fragments, this excludes execute methods)
   const boundServices = serviceContext ? bindServicesToContext(services, serviceContext) : services;
-
-  // 10. Resolve routes with bound services
+  const internalData =
+    definition.internalDataFactory?.({
+      config,
+      options,
+      deps,
+      services: boundServices as BoundServices<TBaseServices & TServices>,
+      serviceDeps: (serviceImplementations ?? {}) as TServiceDependencies,
+    }) ?? {};
+
+  // 11. Resolve routes with bound services
   const context = {
     config,
     deps,
     services: boundServices,
     serviceDeps: serviceImplementations ?? ({} as TServiceDependencies),
   };
-  const routes = resolveRouteFactories(context, routesOrFactories);
-
-  // 11. Calculate mount route
-  const mountRoute = getMountRoute({
-    name: definition.name,
-    mountRoute: options.mountRoute,
-  });
+  const routes = resolveRouteFactories(context, routesOrFactories) as AnyFragnoRouteConfig[];
+  const internalRoutes = definition.internalRoutes
+    ? (resolveRouteFactories(context, definition.internalRoutes) as readonly AnyFragnoRouteConfig[])
+    : [];
+  const prefixedInternalRoutes = internalRoutes.map((route) => ({
+    ...route,
+    path: joinRoutePath(INTERNAL_ROUTE_PREFIX, route.path),
+  }));
+  const finalRoutes =
+    prefixedInternalRoutes.length > 0
+      ? [...routes, ...prefixedInternalRoutes]
+      : (routes as AnyFragnoRouteConfig[]);
 
   // 12. Wrap createRequestStorage to capture context
   const createRequestStorageWithContext = definition.createRequestStorage
@@ -918,7 +1254,10 @@ export function instantiateFragment<
   // Handlers get handlerContext which may have more capabilities than serviceContext
   return new FragnoInstantiatedFragment({
     name: definition.name,
-    routes,
+    routes: finalRoutes as unknown as RoutesWithInternal<
+      FlattenRouteFactories<TRoutesOrFactories>,
+      TInternalRoutes
+    >,
     deps,
     services: boundServices as BoundServices<TBaseServices & TServices>,
     mountRoute,
@@ -927,7 +1266,7 @@ export function instantiateFragment<
     storage,
     createRequestStorage: createRequestStorageWithContext,
     options,
-    linkedFragments: linkedFragmentInstances,
+    internalData: internalData as Record<string, unknown>,
   });
 }
 
@@ -1003,8 +1342,7 @@ interface IFragnoInstantiatedFragment {
   get $internal(): {
     deps: unknown;
     options: unknown;
-    linkedFragments: unknown;
-  };
+  } & Record<string, unknown>;
 
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   withMiddleware(handler: any): this;
@@ -1014,10 +1352,13 @@ interface IFragnoInstantiatedFragment {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   inContext<T>(callback: any): Promise<T>;
 
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  callServices(serviceCalls: () => any): Promise<any>;
+
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   handlersFor(framework: FullstackFrameworks): any;
 
-  handler(req: Request): Promise<Response>;
+  handler(req: Request, lifecycleContext?: FragnoRequestLifecycleContext): Promise<Response>;
 
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   callRoute(method: HTTPMethod, path: string, inputOptions?: any): Promise<any>;
@@ -1042,9 +1383,8 @@ export class FragmentInstantiationBuilder<
   THandlerThisContext extends RequestThisContext,
   TRequestStorage,
   TRoutesOrFactories extends readonly AnyRouteOrFactory[],
-  TLinkedFragments extends Record<string, AnyFragnoInstantiatedFragment>,
-> implements IFragmentInstantiationBuilder
-{
+  TInternalRoutes extends readonly AnyRouteOrFactory[],
+> implements IFragmentInstantiationBuilder {
   #definition: FragmentDefinition<
     TConfig,
     TOptions,
@@ -1056,7 +1396,7 @@ export class FragmentInstantiationBuilder<
     TServiceThisContext,
     THandlerThisContext,
     TRequestStorage,
-    TLinkedFragments
+    TInternalRoutes
   >;
   #config?: TConfig;
   #routes?: TRoutesOrFactories;
@@ -1075,7 +1415,7 @@ export class FragmentInstantiationBuilder<
       TServiceThisContext,
       THandlerThisContext,
       TRequestStorage,
-      TLinkedFragments
+      TInternalRoutes
     >,
     routes?: TRoutesOrFactories,
   ) {
@@ -1097,7 +1437,7 @@ export class FragmentInstantiationBuilder<
     TServiceThisContext,
     THandlerThisContext,
     TRequestStorage,
-    TLinkedFragments
+    TInternalRoutes
   > {
     return this.#definition;
   }
@@ -1148,7 +1488,7 @@ export class FragmentInstantiationBuilder<
     THandlerThisContext,
     TRequestStorage,
     TNewRoutes,
-    TLinkedFragments
+    TInternalRoutes
   > {
     const newBuilder = new FragmentInstantiationBuilder(this.#definition, routes);
     // Preserve config, options, and services from the current instance
@@ -1178,14 +1518,13 @@ export class FragmentInstantiationBuilder<
    * Build and return the instantiated fragment
    */
   build(): FragnoInstantiatedFragment<
-    FlattenRouteFactories<TRoutesOrFactories>,
+    RoutesWithInternal<FlattenRouteFactories<TRoutesOrFactories>, TInternalRoutes>,
     TDeps,
     BoundServices<TBaseServices & TServices>,
     TServiceThisContext,
     THandlerThisContext,
     TRequestStorage,
-    TOptions,
-    TLinkedFragments
+    TOptions
   > {
     // This variable is set by the frango-cli when extracting database schemas
     const dryRun = process.env["FRAGNO_INIT_DRY_RUN"] === "true";
@@ -1224,7 +1563,7 @@ export function instantiate<
   TServiceThisContext extends RequestThisContext,
   THandlerThisContext extends RequestThisContext,
   TRequestStorage,
-  TLinkedFragments extends Record<string, AnyFragnoInstantiatedFragment>,
+  TInternalRoutes extends readonly AnyRouteOrFactory[],
 >(
   definition: FragmentDefinition<
     TConfig,
@@ -1237,7 +1576,7 @@ export function instantiate<
     TServiceThisContext,
     THandlerThisContext,
     TRequestStorage,
-    TLinkedFragments
+    TInternalRoutes
   >,
 ): FragmentInstantiationBuilder<
   TConfig,
@@ -1251,7 +1590,7 @@ export function instantiate<
   THandlerThisContext,
   TRequestStorage,
   readonly [],
-  TLinkedFragments
+  TInternalRoutes
 > {
   return new FragmentInstantiationBuilder(definition);
 }