@fragno-dev/core 0.1.10 → 0.2.0

package/src/api/fragment-instantiator.ts

@@ -27,10 +27,112 @@ 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 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 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 [];
+
+export type RoutesWithInternal<
+  TRoutes extends readonly AnyFragnoRouteConfig[],
+  TLinkedFragments,
+> = readonly [...TRoutes, ...InternalLinkedRoutes<TLinkedFragments>];
+
+/**
+ * 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.
+ *
+ * @example
+ * ```typescript
+ * const myFragmentDef = defineFragment("my-fragment").build();
+ * type MyInstantiatedFragment = InstantiatedFragmentFromDefinition<typeof myFragmentDef>;
+ * ```
+ */
+export type InstantiatedFragmentFromDefinition<
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  TDef extends FragmentDefinition<any, any, any, any, any, any, any, any, any, any, any>,
+> =
+  TDef extends FragmentDefinition<
+    infer _TConfig,
+    infer TOptions,
+    infer TDeps,
+    infer TBaseServices,
+    infer TServices,
+    infer _TServiceDependencies,
+    infer _TPrivateServices,
+    infer TServiceThisContext,
+    infer THandlerThisContext,
+    infer TRequestStorage,
+    infer TLinkedFragments
+  >
+    ? FragnoInstantiatedFragment<
+        RoutesWithInternal<readonly AnyFragnoRouteConfig[], TLinkedFragments>,
+        TDeps,
+        BoundServices<TBaseServices & TServices>,
+        TServiceThisContext,
+        THandlerThisContext,
+        TRequestStorage,
+        TOptions,
+        TLinkedFragments
+      >
+    : never;
+
 type AstroHandlers = {
   ALL: (req: Request) => Promise<Response>;
 };
@@ -40,6 +142,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>;
@@ -73,8 +203,7 @@ type HandlersByFramework = {
 
 type FullstackFrameworks = keyof HandlersByFramework;
 
-// Safe: This is a catch-all type for any instantiated fragment
-type AnyFragnoInstantiatedFragment = FragnoInstantiatedFragment<
+export type AnyFragnoInstantiatedFragment = FragnoInstantiatedFragment<
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   any,
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -93,7 +222,65 @@ type AnyFragnoInstantiatedFragment = FragnoInstantiatedFragment<
   any
 >;
 
-export type { AnyFragnoInstantiatedFragment };
+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}`;
+  }
+  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}`;
+}
+
+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<
@@ -122,7 +309,8 @@ export class FragnoInstantiatedFragment<
   TRequestStorage = {},
   TOptions extends FragnoPublicConfig = FragnoPublicConfig,
   TLinkedFragments extends Record<string, AnyFragnoInstantiatedFragment> = {},
-> {
+> implements IFragnoInstantiatedFragment
+{
   readonly [instantiatedFragmentFakeSymbol] = instantiatedFragmentFakeSymbol;
 
   // Private fields
@@ -139,6 +327,7 @@ export class FragnoInstantiatedFragment<
   #createRequestStorage?: () => TRequestStorage;
   #options: TOptions;
   #linkedFragments: TLinkedFragments;
+  #internalData: Record<string, unknown>;
 
   constructor(params: {
     name: string;
@@ -152,6 +341,7 @@ export class FragnoInstantiatedFragment<
     createRequestStorage?: () => TRequestStorage;
     options: TOptions;
     linkedFragments?: TLinkedFragments;
+    internalData?: Record<string, unknown>;
   }) {
     this.#name = params.name;
     this.#routes = params.routes;
@@ -164,6 +354,7 @@ export class FragnoInstantiatedFragment<
     this.#createRequestStorage = params.createRequestStorage;
     this.#options = params.options;
     this.#linkedFragments = params.linkedFragments ?? ({} as TLinkedFragments);
+    this.#internalData = params.internalData ?? {};
 
     // Build router
     this.#router =
@@ -212,6 +403,7 @@ export class FragnoInstantiatedFragment<
       deps: this.#deps,
       options: this.#options,
       linkedFragments: this.#linkedFragments,
+      ...this.#internalData,
     };
   }
 
@@ -372,31 +564,90 @@ export class FragnoInstantiatedFragment<
       );
     }
 
-    // Parse request body
+    // Get the expected content type from route config (default: application/json)
+    const routeConfig = route.data as InternalLinkedRouteConfig;
+    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),
@@ -404,11 +655,27 @@ export class FragnoInstantiatedFragment<
 
     // 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;
+      }
+
+      // 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;
         }
       }
 
@@ -475,7 +742,6 @@ export class FragnoInstantiatedFragment<
           ? new URLSearchParams(query)
           : new URLSearchParams();
 
-    // Convert headers to Headers if needed
     const requestHeaders =
       headers instanceof Headers ? headers : headers ? new Headers(headers) : new Headers();
 
@@ -491,6 +757,16 @@ 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);
 
@@ -527,32 +803,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();
       }
@@ -591,6 +908,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 {
@@ -615,6 +942,18 @@ export class FragnoInstantiatedFragment<
   }
 }
 
+/**
+ * Options for fragment instantiation.
+ */
+export interface InstantiationOptions {
+  /**
+   * If true, catches errors during initialization and returns stub implementations.
+   * This is useful for CLI tools that need to extract metadata (like database schemas)
+   * without requiring all dependencies to be fully initialized.
+   */
+  dryRun?: boolean;
+}
+
 /**
  * Core instantiation function that creates a fragment instance from a definition.
  * This function validates dependencies, calls all callbacks, and wires everything together.
@@ -650,8 +989,9 @@ export function instantiateFragment<
   routesOrFactories: TRoutesOrFactories,
   options: TOptions,
   serviceImplementations?: TServiceDependencies,
+  instantiationOptions?: InstantiationOptions,
 ): FragnoInstantiatedFragment<
-  FlattenRouteFactories<TRoutesOrFactories>,
+  RoutesWithInternal<FlattenRouteFactories<TRoutesOrFactories>, TLinkedFragments>,
   TDeps,
   BoundServices<TBaseServices & TServices>,
   TServiceThisContext,
@@ -660,6 +1000,8 @@ export function instantiateFragment<
   TOptions,
   TLinkedFragments
 > {
+  const { dryRun = false } = instantiationOptions ?? {};
+
   // 1. Validate service dependencies
   const serviceDependencies = definition.serviceDependencies;
   if (serviceDependencies) {
@@ -675,7 +1017,21 @@ export function instantiateFragment<
   }
 
   // 2. Call dependencies callback
-  const deps = definition.dependencies?.({ config, options }) ?? ({} as TDeps);
+  let deps: TDeps;
+  try {
+    deps = definition.dependencies?.({ config, options }) ?? ({} as TDeps);
+  } catch (error) {
+    if (dryRun) {
+      console.warn(
+        "Warning: Failed to initialize dependencies in dry run mode:",
+        error instanceof Error ? error.message : String(error),
+      );
+      // Return empty deps - database fragments will add implicit deps later
+      deps = {} as TDeps;
+    } else {
+      throw error;
+    }
+  }
 
   // 3. Instantiate linked fragments FIRST (before any services)
   // Their services will be merged into private services
@@ -717,28 +1073,54 @@ export function instantiateFragment<
         privateServices: TPrivateServices;
         defineService: <T>(svc: T & ThisType<TServiceThisContext>) => T;
       }) => unknown;
-      (privateServices as Record<string, unknown>)[serviceName] = serviceFactory({
+
+      try {
+        (privateServices as Record<string, unknown>)[serviceName] = serviceFactory({
+          config,
+          options,
+          deps,
+          serviceDeps: (serviceImplementations ?? {}) as TServiceDependencies,
+          privateServices, // Pass the current state of private services (earlier ones are available)
+          defineService,
+        });
+      } catch (error) {
+        if (dryRun) {
+          console.warn(
+            `Warning: Failed to initialize private service '${serviceName}' in dry run mode:`,
+            error instanceof Error ? error.message : String(error),
+          );
+          (privateServices as Record<string, unknown>)[serviceName] = {};
+        } else {
+          throw error;
+        }
+      }
+    }
+  }
+
+  // 5. Call baseServices callback (with access to private services including linked fragment services)
+  let baseServices: TBaseServices;
+  try {
+    baseServices =
+      definition.baseServices?.({
         config,
         options,
         deps,
         serviceDeps: (serviceImplementations ?? {}) as TServiceDependencies,
-        privateServices, // Pass the current state of private services (earlier ones are available)
+        privateServices,
         defineService,
-      });
+      }) ?? ({} as TBaseServices);
+  } catch (error) {
+    if (dryRun) {
+      console.warn(
+        "Warning: Failed to initialize base services in dry run mode:",
+        error instanceof Error ? error.message : String(error),
+      );
+      baseServices = {} as TBaseServices;
+    } else {
+      throw error;
     }
   }
 
-  // 5. Call baseServices callback (with access to private services including linked fragment services)
-  const baseServices =
-    definition.baseServices?.({
-      config,
-      options,
-      deps,
-      serviceDeps: (serviceImplementations ?? {}) as TServiceDependencies,
-      privateServices,
-      defineService,
-    }) ?? ({} as TBaseServices);
-
   // 6. Call namedServices factories (with access to private services including linked fragment services)
   const namedServices = {} as TServices;
   if (definition.namedServices) {
@@ -751,14 +1133,27 @@ export function instantiateFragment<
         privateServices: TPrivateServices;
         defineService: <T>(svc: T & ThisType<TServiceThisContext>) => T;
       }) => unknown;
-      (namedServices as Record<string, unknown>)[serviceName] = serviceFactory({
-        config,
-        options,
-        deps,
-        serviceDeps: (serviceImplementations ?? {}) as TServiceDependencies,
-        privateServices,
-        defineService,
-      });
+
+      try {
+        (namedServices as Record<string, unknown>)[serviceName] = serviceFactory({
+          config,
+          options,
+          deps,
+          serviceDeps: (serviceImplementations ?? {}) as TServiceDependencies,
+          privateServices,
+          defineService,
+        });
+      } catch (error) {
+        if (dryRun) {
+          console.warn(
+            `Warning: Failed to initialize service '${serviceName}' in dry run mode:`,
+            error instanceof Error ? error.message : String(error),
+          );
+          (namedServices as Record<string, unknown>)[serviceName] = {};
+        } else {
+          throw error;
+        }
+      }
     }
   }
 
@@ -784,6 +1179,13 @@ export function instantiateFragment<
 
   const serviceContext = contexts?.serviceContext;
   const handlerContext = contexts?.handlerContext;
+  const internalData =
+    definition.internalDataFactory?.({
+      config,
+      options,
+      deps,
+      linkedFragments: linkedFragmentInstances,
+    }) ?? {};
 
   // 9. Bind services to serviceContext (restricted)
   // Services get the restricted context (for database fragments, this excludes execute methods)
@@ -796,7 +1198,12 @@ export function instantiateFragment<
     services: boundServices,
     serviceDeps: serviceImplementations ?? ({} as TServiceDependencies),
   };
-  const routes = resolveRouteFactories(context, routesOrFactories);
+  const routes = resolveRouteFactories(context, routesOrFactories) as AnyFragnoRouteConfig[];
+  const linkedRoutes = collectLinkedFragmentRoutes(
+    linkedFragmentInstances as Record<string, AnyFragnoInstantiatedFragment>,
+  );
+  const finalRoutes =
+    linkedRoutes.length > 0 ? [...routes, ...linkedRoutes] : (routes as AnyFragnoRouteConfig[]);
 
   // 11. Calculate mount route
   const mountRoute = getMountRoute({
@@ -814,7 +1221,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>,
+      TLinkedFragments
+    >,
     deps,
     services: boundServices as BoundServices<TBaseServices & TServices>,
     mountRoute,
@@ -824,9 +1234,105 @@ export function instantiateFragment<
     createRequestStorage: createRequestStorageWithContext,
     options,
     linkedFragments: linkedFragmentInstances,
+    internalData: internalData as Record<string, unknown>,
   });
 }
 
+/**
+ * Interface that defines the public API for a fragment instantiation builder.
+ * Used to ensure consistency between real implementations and stubs.
+ */
+interface IFragmentInstantiationBuilder {
+  /**
+   * Get the fragment definition
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  get definition(): any;
+
+  /**
+   * Get the configured routes
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  get routes(): any;
+
+  /**
+   * Get the configuration
+   */
+  get config(): unknown;
+
+  /**
+   * Get the options
+   */
+  get options(): unknown;
+
+  /**
+   * Set the configuration for the fragment
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  withConfig(config: any): unknown;
+
+  /**
+   * Set the routes for the fragment
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  withRoutes(routes: any): unknown;
+
+  /**
+   * Set the options for the fragment (e.g., mountRoute, databaseAdapter)
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  withOptions(options: any): unknown;
+
+  /**
+   * Provide implementations for services that this fragment uses
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  withServices(services: any): unknown;
+
+  /**
+   * Build and return the instantiated fragment
+   */
+  build(): IFragnoInstantiatedFragment;
+}
+
+/**
+ * Interface that defines the public API for an instantiated fragment.
+ * Used to ensure consistency between real implementations and stubs.
+ */
+interface IFragnoInstantiatedFragment {
+  readonly [instantiatedFragmentFakeSymbol]: typeof instantiatedFragmentFakeSymbol;
+
+  get name(): string;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  get routes(): any;
+  get services(): Record<string, unknown>;
+  get mountRoute(): string;
+  get $internal(): {
+    deps: unknown;
+    options: unknown;
+    linkedFragments: unknown;
+  } & Record<string, unknown>;
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  withMiddleware(handler: any): this;
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  inContext<T>(callback: any): T;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  inContext<T>(callback: any): Promise<T>;
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  handlersFor(framework: FullstackFrameworks): any;
+
+  handler(req: Request): Promise<Response>;
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  callRoute(method: HTTPMethod, path: string, inputOptions?: any): Promise<any>;
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  callRouteRaw(method: HTTPMethod, path: string, inputOptions?: any): Promise<Response>;
+}
+
 /**
  * Fluent builder for instantiating fragments.
  * Provides a type-safe API for configuring and building fragment instances.
@@ -844,7 +1350,8 @@ export class FragmentInstantiationBuilder<
   TRequestStorage,
   TRoutesOrFactories extends readonly AnyRouteOrFactory[],
   TLinkedFragments extends Record<string, AnyFragnoInstantiatedFragment>,
-> {
+> implements IFragmentInstantiationBuilder
+{
   #definition: FragmentDefinition<
     TConfig,
     TOptions,
@@ -978,7 +1485,7 @@ export class FragmentInstantiationBuilder<
    * Build and return the instantiated fragment
    */
   build(): FragnoInstantiatedFragment<
-    FlattenRouteFactories<TRoutesOrFactories>,
+    RoutesWithInternal<FlattenRouteFactories<TRoutesOrFactories>, TLinkedFragments>,
     TDeps,
     BoundServices<TBaseServices & TServices>,
     TServiceThisContext,
@@ -987,12 +1494,16 @@ export class FragmentInstantiationBuilder<
     TOptions,
     TLinkedFragments
   > {
+    // This variable is set by the frango-cli when extracting database schemas
+    const dryRun = process.env["FRAGNO_INIT_DRY_RUN"] === "true";
+
     return instantiateFragment(
       this.#definition,
       this.#config ?? ({} as TConfig),
       this.#routes ?? ([] as const as unknown as TRoutesOrFactories),
       this.#options ?? ({} as TOptions),
       this.#services,
+      { dryRun },
     );
   }
 }
@@ -1051,3 +1562,6 @@ export function instantiate<
 > {
   return new FragmentInstantiationBuilder(definition);
 }
+
+// Export interfaces for stub implementations
+export type { IFragmentInstantiationBuilder, IFragnoInstantiatedFragment };