@fragno-dev/core 0.2.0 → 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,26 +28,42 @@ 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";
-import { recordTraceEvent } from "../internal/trace-context";
 
 // 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 "" | "/"
@@ -66,33 +98,27 @@ type PrefixInternalRoutes<TRoutes extends readonly AnyFragnoRouteConfig[]> =
     ? { [K in keyof TRoutesTuple]: PrefixInternalRoute<TRoutesTuple[K]> }
     : readonly AnyFragnoRouteConfig[];
 
-type ExtractRoutesFromFragment<T> =
-  T extends FragnoInstantiatedFragment<
-    infer TRoutes,
-    infer _TDeps,
-    infer _TServices,
-    infer _TServiceThisContext,
-    infer _THandlerThisContext,
-    infer _TRequestStorage,
-    infer _TOptions,
-    infer _TLinkedFragments
-  >
-    ? TRoutes
-    : never;
-
-type InternalLinkedRoutes<TLinkedFragments> =
-  TLinkedFragments extends Record<string, AnyFragnoInstantiatedFragment>
-    ? TLinkedFragments extends { _fragno_internal: infer TInternal }
-      ? ExtractRoutesFromFragment<TInternal> extends readonly AnyFragnoRouteConfig[]
-        ? PrefixInternalRoutes<ExtractRoutesFromFragment<TInternal>>
-        : readonly []
-      : readonly []
-    : readonly [];
+type InternalRoutesFromDefinition<TInternalRoutes extends readonly AnyRouteOrFactory[]> =
+  PrefixInternalRoutes<FlattenRouteFactories<TInternalRoutes>>;
 
 export type RoutesWithInternal<
   TRoutes extends readonly AnyFragnoRouteConfig[],
-  TLinkedFragments,
-> = readonly [...TRoutes, ...InternalLinkedRoutes<TLinkedFragments>];
+  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.
@@ -119,17 +145,16 @@ export type InstantiatedFragmentFromDefinition<
     infer TServiceThisContext,
     infer THandlerThisContext,
     infer TRequestStorage,
-    infer TLinkedFragments
+    infer TInternalRoutes
   >
     ? FragnoInstantiatedFragment<
-        RoutesWithInternal<readonly AnyFragnoRouteConfig[], TLinkedFragments>,
+        RoutesWithInternal<readonly AnyFragnoRouteConfig[], TInternalRoutes>,
         TDeps,
         BoundServices<TBaseServices & TServices>,
         TServiceThisContext,
         THandlerThisContext,
         TRequestStorage,
-        TOptions,
-        TLinkedFragments
+        TOptions
       >
     : never;
 
@@ -217,24 +242,11 @@ 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_LINKED_FRAGMENT_NAME = "_fragno_internal";
 const INTERNAL_ROUTE_PREFIX = "/_internal";
 
-type InternalLinkedRouteMeta = {
-  fragment: AnyFragnoInstantiatedFragment;
-  originalPath: string;
-  routes: readonly AnyFragnoRouteConfig[];
-};
-
-type InternalLinkedRouteConfig = AnyFragnoRouteConfig & {
-  __internal?: InternalLinkedRouteMeta;
-};
-
 function normalizeRoutePrefix(prefix: string): string {
   if (!prefix.startsWith("/")) {
     prefix = `/${prefix}`;
@@ -251,37 +263,6 @@ function joinRoutePath(prefix: string, path: string): string {
   return `${normalizedPrefix}${normalizedPath}`;
 }
 
-function collectLinkedFragmentRoutes(
-  linkedFragments: Record<string, AnyFragnoInstantiatedFragment>,
-): InternalLinkedRouteConfig[] {
-  const linkedRoutes: InternalLinkedRouteConfig[] = [];
-
-  for (const [name, fragment] of Object.entries(linkedFragments)) {
-    if (name !== INTERNAL_LINKED_FRAGMENT_NAME) {
-      continue;
-    }
-
-    const internalRoutes = (fragment.routes ?? []) as readonly AnyFragnoRouteConfig[];
-    if (internalRoutes.length === 0) {
-      continue;
-    }
-
-    for (const route of internalRoutes) {
-      linkedRoutes.push({
-        ...route,
-        path: joinRoutePath(INTERNAL_ROUTE_PREFIX, route.path),
-        __internal: {
-          fragment,
-          originalPath: route.path,
-          routes: internalRoutes,
-        },
-      });
-    }
-  }
-
-  return linkedRoutes;
-}
-
 export interface FragnoFragmentSharedConfig<
   TRoutes extends readonly FragnoRouteConfig<
     HTTPMethod,
@@ -308,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
@@ -326,7 +305,6 @@ export class FragnoInstantiatedFragment<
   #contextStorage: RequestContextStorage<TRequestStorage>;
   #createRequestStorage?: () => TRequestStorage;
   #options: TOptions;
-  #linkedFragments: TLinkedFragments;
   #internalData: Record<string, unknown>;
 
   constructor(params: {
@@ -340,7 +318,6 @@ export class FragnoInstantiatedFragment<
     storage: RequestContextStorage<TRequestStorage>;
     createRequestStorage?: () => TRequestStorage;
     options: TOptions;
-    linkedFragments?: TLinkedFragments;
     internalData?: Record<string, unknown>;
   }) {
     this.#name = params.name;
@@ -353,7 +330,6 @@ 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
@@ -402,7 +378,6 @@ export class FragnoInstantiatedFragment<
     return {
       deps: this.#deps,
       options: this.#options,
-      linkedFragments: this.#linkedFragments,
       ...this.#internalData,
     };
   }
@@ -424,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();
@@ -436,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);
   }
 
@@ -463,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>;
   }
 
   /**
@@ -534,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;
 
@@ -565,7 +611,7 @@ export class FragnoInstantiatedFragment<
     }
 
     // Get the expected content type from route config (default: application/json)
-    const routeConfig = route.data as InternalLinkedRouteConfig;
+    const routeConfig = route.data as AnyFragnoRouteConfig;
     const expectedContentType = routeConfig.contentType ?? "application/json";
 
     // Parse request body based on route's expected content type
@@ -653,6 +699,17 @@ export class FragnoInstantiatedFragment<
       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> => {
       // Parent middleware execution
@@ -661,46 +718,28 @@ export class FragnoInstantiatedFragment<
         return middlewareResult;
       }
 
-      // Internal fragment middleware execution (if linked)
-      const internalMeta = routeConfig.__internal;
-      if (internalMeta) {
-        const internalResult = await FragnoInstantiatedFragment.#runMiddlewareForFragment(
-          internalMeta.fragment as AnyFragnoInstantiatedFragment,
-          {
-            req,
-            method: routeConfig.method,
-            path: internalMeta.originalPath,
-            requestState,
-            routes: internalMeta.routes,
-          },
-        );
-        if (internalResult !== undefined) {
-          return internalResult;
-        }
-      }
-
       // Handler execution
       return this.#executeHandler(req, route, requestState, rawBody);
     };
 
     // 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);
@@ -711,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
@@ -732,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 =
@@ -770,6 +810,17 @@ export class FragnoInstantiatedFragment<
     // 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 {
@@ -791,7 +842,7 @@ export class FragnoInstantiatedFragment<
     };
 
     // Wrap with request storage context if provided
-    return this.#withRequestStorage(executeHandler);
+    return this.#withRequestStorage(executeHandler, "route", routeInfo);
   }
 
   /**
@@ -970,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,
@@ -983,7 +1034,7 @@ export function instantiateFragment<
     TServiceThisContext,
     THandlerThisContext,
     TRequestStorage,
-    TLinkedFragments
+    TInternalRoutes
   >,
   config: TConfig,
   routesOrFactories: TRoutesOrFactories,
@@ -991,14 +1042,13 @@ export function instantiateFragment<
   serviceImplementations?: TServiceDependencies,
   instantiationOptions?: InstantiationOptions,
 ): FragnoInstantiatedFragment<
-  RoutesWithInternal<FlattenRouteFactories<TRoutesOrFactories>, TLinkedFragments>,
+  RoutesWithInternal<FlattenRouteFactories<TRoutesOrFactories>, TInternalRoutes>,
   TDeps,
   BoundServices<TBaseServices & TServices>,
   TServiceThisContext,
   THandlerThisContext,
   TRequestStorage,
-  TOptions,
-  TLinkedFragments
+  TOptions
 > {
   const { dryRun = false } = instantiationOptions ?? {};
 
@@ -1033,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: {
@@ -1097,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 =
@@ -1121,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)) {
@@ -1157,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 })
@@ -1179,19 +1211,20 @@ export function instantiateFragment<
 
   const serviceContext = contexts?.serviceContext;
   const handlerContext = contexts?.handlerContext;
+
+  // 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;
   const internalData =
     definition.internalDataFactory?.({
       config,
       options,
       deps,
-      linkedFragments: linkedFragmentInstances,
+      services: boundServices as BoundServices<TBaseServices & TServices>,
+      serviceDeps: (serviceImplementations ?? {}) as TServiceDependencies,
     }) ?? {};
 
-  // 9. 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
+  // 11. Resolve routes with bound services
   const context = {
     config,
     deps,
@@ -1199,17 +1232,17 @@ export function instantiateFragment<
     serviceDeps: serviceImplementations ?? ({} as TServiceDependencies),
   };
   const routes = resolveRouteFactories(context, routesOrFactories) as AnyFragnoRouteConfig[];
-  const linkedRoutes = collectLinkedFragmentRoutes(
-    linkedFragmentInstances as Record<string, AnyFragnoInstantiatedFragment>,
-  );
+  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 =
-    linkedRoutes.length > 0 ? [...routes, ...linkedRoutes] : (routes as AnyFragnoRouteConfig[]);
-
-  // 11. Calculate mount route
-  const mountRoute = getMountRoute({
-    name: definition.name,
-    mountRoute: options.mountRoute,
-  });
+    prefixedInternalRoutes.length > 0
+      ? [...routes, ...prefixedInternalRoutes]
+      : (routes as AnyFragnoRouteConfig[]);
 
   // 12. Wrap createRequestStorage to capture context
   const createRequestStorageWithContext = definition.createRequestStorage
@@ -1223,7 +1256,7 @@ export function instantiateFragment<
     name: definition.name,
     routes: finalRoutes as unknown as RoutesWithInternal<
       FlattenRouteFactories<TRoutesOrFactories>,
-      TLinkedFragments
+      TInternalRoutes
     >,
     deps,
     services: boundServices as BoundServices<TBaseServices & TServices>,
@@ -1233,7 +1266,6 @@ export function instantiateFragment<
     storage,
     createRequestStorage: createRequestStorageWithContext,
     options,
-    linkedFragments: linkedFragmentInstances,
     internalData: internalData as Record<string, unknown>,
   });
 }
@@ -1310,7 +1342,6 @@ interface IFragnoInstantiatedFragment {
   get $internal(): {
     deps: unknown;
     options: unknown;
-    linkedFragments: unknown;
   } & Record<string, unknown>;
 
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -1321,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>;
@@ -1349,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,
@@ -1363,7 +1396,7 @@ export class FragmentInstantiationBuilder<
     TServiceThisContext,
     THandlerThisContext,
     TRequestStorage,
-    TLinkedFragments
+    TInternalRoutes
   >;
   #config?: TConfig;
   #routes?: TRoutesOrFactories;
@@ -1382,7 +1415,7 @@ export class FragmentInstantiationBuilder<
       TServiceThisContext,
       THandlerThisContext,
       TRequestStorage,
-      TLinkedFragments
+      TInternalRoutes
     >,
     routes?: TRoutesOrFactories,
   ) {
@@ -1404,7 +1437,7 @@ export class FragmentInstantiationBuilder<
     TServiceThisContext,
     THandlerThisContext,
     TRequestStorage,
-    TLinkedFragments
+    TInternalRoutes
   > {
     return this.#definition;
   }
@@ -1455,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
@@ -1485,14 +1518,13 @@ export class FragmentInstantiationBuilder<
    * Build and return the instantiated fragment
    */
   build(): FragnoInstantiatedFragment<
-    RoutesWithInternal<FlattenRouteFactories<TRoutesOrFactories>, TLinkedFragments>,
+    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";
@@ -1531,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,
@@ -1544,7 +1576,7 @@ export function instantiate<
     TServiceThisContext,
     THandlerThisContext,
     TRequestStorage,
-    TLinkedFragments
+    TInternalRoutes
   >,
 ): FragmentInstantiationBuilder<
   TConfig,
@@ -1558,7 +1590,7 @@ export function instantiate<
   THandlerThisContext,
   TRequestStorage,
   readonly [],
-  TLinkedFragments
+  TInternalRoutes
 > {
   return new FragmentInstantiationBuilder(definition);
 }