@fluojs/runtime 1.0.0-beta.1

package/dist/http-adapter-shared.js

@@ -0,0 +1,199 @@
+import { createCorsMiddleware, createErrorResponse, createSecurityHeadersMiddleware, matchRoutePattern, normalizeRoutePattern, NotFoundException } from '@fluojs/http';
+import { bootstrapApplication } from './bootstrap.js';
+import { createConsoleApplicationLogger } from './logging/logger.js';
+
+/**
+ * Input type for configuring CORS in an HTTP adapter.
+ */
+
+/**
+ * Resolved target for an HTTP server listener.
+ */
+
+/**
+ * Common middleware options for HTTP adapters.
+ */
+
+/**
+ * Options for bootstrapping an HTTP adapter application.
+ */
+
+/**
+ * Options for running an HTTP adapter application with shutdown management.
+ */
+
+/**
+ * Function type for registering custom application shutdown logic.
+ */
+
+/**
+ * Bootstraps an HTTP application with the provided adapter and options.
+ *
+ * @param rootModule The root application module class.
+ * @param options Bootstrap configuration for middleware and logging.
+ * @param adapter The HTTP platform adapter to use.
+ * @returns A promise that resolves to the initialized application instance.
+ */
+export async function bootstrapHttpAdapterApplication(rootModule, options, adapter) {
+  return bootstrapApplication({
+    ...options,
+    adapter,
+    logger: options.logger ?? createConsoleApplicationLogger(),
+    middleware: createHttpAdapterMiddleware(options),
+    rootModule
+  });
+}
+
+/**
+ * Resolves the final middleware chain for an HTTP adapter based on options.
+ *
+ * @param options Middleware configuration including CORS and prefix settings.
+ * @returns An array of middleware instances to be registered in the adapter.
+ */
+export function createHttpAdapterMiddleware(options) {
+  const middleware = [...(options.middleware ?? [])];
+  if (options.securityHeaders !== false) {
+    middleware.unshift(createSecurityHeadersMiddleware(typeof options.securityHeaders === 'object' ? options.securityHeaders : undefined));
+  }
+  if (options.globalPrefix) {
+    middleware.unshift(createGlobalPrefixMiddleware(options.globalPrefix, options.globalPrefixExclude));
+  }
+  if (options.cors !== undefined && options.cors !== false) {
+    middleware.unshift(createCorsMiddleware(resolveCorsOptions(options.cors)));
+  }
+  return middleware;
+}
+
+/**
+ * Formats a log message indicating that the HTTP adapter is listening on a specific target.
+ *
+ * @param target - The listen target containing the URL and bind target.
+ * @returns A formatted string message.
+ */
+export function formatHttpAdapterListenMessage(target) {
+  return target.url.endsWith(target.bindTarget) ? `Listening on ${target.url}` : `Listening on ${target.url} (bound to ${target.bindTarget})`;
+}
+
+/**
+ * Boots and runs an HTTP application using the provided adapter and options,
+ * including setup for shutdown management and logging.
+ *
+ * @param rootModule - The root application module class.
+ * @param options - Run configuration including shutdown and logging settings.
+ * @param adapter - The managed HTTP platform adapter to use.
+ * @returns A promise that resolves to the running application instance.
+ */
+export async function runHttpAdapterApplication(rootModule, options, adapter) {
+  const logger = options.logger ?? createConsoleApplicationLogger();
+  const app = await bootstrapApplication({
+    ...options,
+    adapter,
+    logger,
+    middleware: createHttpAdapterMiddleware(options),
+    rootModule
+  });
+  try {
+    await app.listen();
+    logger.log(formatHttpAdapterListenMessage(adapter.getListenTarget()), 'FluoFactory');
+  } catch (error) {
+    logger.error('Failed to start application.', error, 'FluoFactory');
+    if (app.state !== 'closed') {
+      try {
+        await app.close('bootstrap-failed');
+      } catch (closeError) {
+        logger.error('Failed to close application after startup failure.', closeError, 'FluoFactory');
+      }
+    }
+    throw error;
+  }
+  const unregisterShutdownSignals = options.shutdownRegistration?.(app, logger, options.forceExitTimeoutMs) ?? (() => {});
+  const close = app.close.bind(app);
+  let shutdownSignalsUnregistered = false;
+  app.close = async signal => {
+    if (!shutdownSignalsUnregistered) {
+      unregisterShutdownSignals();
+      shutdownSignalsUnregistered = true;
+    }
+    await close(signal);
+  };
+  return app;
+}
+function createGlobalPrefixMiddleware(prefix, exclude) {
+  const normalizedPrefix = normalizeRoutePattern(prefix);
+  if (normalizedPrefix === '/') {
+    return {
+      async handle(_context, next) {
+        await next();
+      }
+    };
+  }
+  const exclusions = [...(exclude ?? [])].map(path => normalizeRoutePattern(path));
+  return {
+    async handle(context, next) {
+      const requestPath = normalizeRoutePattern(context.request.path);
+      if (matchesExcludedPath(requestPath, exclusions)) {
+        await next();
+        return;
+      }
+      if (shouldRejectGlobalPrefixRequest(requestPath, normalizedPrefix, exclusions)) {
+        await writeGlobalPrefixNotFound(context.requestContext.requestId, context.response);
+        return;
+      }
+      const strippedPath = stripGlobalPrefix(requestPath, normalizedPrefix);
+      context.request = rewriteGlobalPrefixRequest(context.request, requestPath, strippedPath);
+      await next();
+    }
+  };
+}
+function shouldRejectGlobalPrefixRequest(requestPath, normalizedPrefix, exclusions) {
+  if (!matchesPrefix(requestPath, normalizedPrefix)) {
+    return true;
+  }
+  return matchesExcludedPath(stripGlobalPrefix(requestPath, normalizedPrefix), exclusions);
+}
+function rewriteGlobalPrefixRequest(request, requestPath, strippedPath) {
+  return {
+    ...request,
+    path: strippedPath,
+    url: rewritePrefixedUrl(request.url, requestPath, strippedPath)
+  };
+}
+function writeGlobalPrefixNotFound(requestId, response) {
+  const error = new NotFoundException('Resource not found.');
+  response.setStatus(error.status);
+  return Promise.resolve(response.send(createErrorResponse(error, requestId)));
+}
+function matchesPrefix(path, prefix) {
+  return path === prefix || path.startsWith(`${prefix}/`);
+}
+function stripGlobalPrefix(path, prefix) {
+  if (path === prefix) {
+    return '/';
+  }
+  return normalizeRoutePattern(path.slice(prefix.length));
+}
+function matchesExcludedPath(path, exclusions) {
+  return exclusions.some(pattern => matchRoutePattern(pattern, path));
+}
+function rewritePrefixedUrl(url, originalPath, rewrittenPath) {
+  if (!url.startsWith(originalPath)) {
+    return rewrittenPath;
+  }
+  return rewrittenPath + url.slice(originalPath.length);
+}
+function resolveCorsOptions(cors) {
+  const defaults = {
+    allowHeaders: ['Authorization', 'Content-Type'],
+    exposeHeaders: ['X-Request-Id']
+  };
+  if (typeof cors === 'string' || Array.isArray(cors)) {
+    return {
+      ...defaults,
+      allowOrigin: cors
+    };
+  }
+  return {
+    ...defaults,
+    ...cors
+  };
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export * from './abort.js';
+export * from './bootstrap.js';
+export * from './health/diagnostics.js';
+export * from './errors.js';
+export * from './health/health.js';
+export type { MultipartOptions, MultipartRequestLike, MultipartResult, UploadedFile, } from './multipart.js';
+export type { PersistencePlatformStatusSnapshot, PlatformCheckResult, PlatformComponent, PlatformComponentInput, PlatformComponentRegistration, PlatformDiagnosticIssue, PlatformHealthReport, PlatformOptionsBase, PlatformReadinessReport, PlatformShell, PlatformShellSnapshot, PlatformSnapshot, PlatformState, PlatformValidationResult, } from './platform-contract.js';
+export * from './request-transaction.js';
+export { APPLICATION_LOGGER, PLATFORM_SHELL } from './tokens.js';
+export * from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,yBAAyB,CAAC;AACxC,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,YAAY,EACV,gBAAgB,EAChB,oBAAoB,EACpB,eAAe,EACf,YAAY,GACb,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACV,iCAAiC,EACjC,mBAAmB,EACnB,iBAAiB,EACjB,sBAAsB,EACtB,6BAA6B,EAC7B,uBAAuB,EACvB,oBAAoB,EACpB,mBAAmB,EACnB,uBAAuB,EACvB,aAAa,EACb,qBAAqB,EACrB,gBAAgB,EAChB,aAAa,EACb,wBAAwB,GACzB,MAAM,wBAAwB,CAAC;AAChC,cAAc,0BAA0B,CAAC;AACzC,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACjE,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+export * from './abort.js';
+export * from './bootstrap.js';
+export * from './health/diagnostics.js';
+export * from './errors.js';
+export * from './health/health.js';
+export * from './request-transaction.js';
+export { APPLICATION_LOGGER, PLATFORM_SHELL } from './tokens.js';
+export * from './types.js';

package/dist/internal-http-adapter.d.ts

@@ -0,0 +1,2 @@
+export * from './adapters/internal-http-adapter.js';
+//# sourceMappingURL=internal-http-adapter.d.ts.map

package/dist/internal-http-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal-http-adapter.d.ts","sourceRoot":"","sources":["../src/internal-http-adapter.ts"],"names":[],"mappings":"AAAA,cAAc,qCAAqC,CAAC"}

package/dist/internal-http-adapter.js

@@ -0,0 +1 @@
+export * from './adapters/internal-http-adapter.js';

package/dist/internal-node.d.ts

@@ -0,0 +1,2 @@
+export * from './node/internal-node.js';
+//# sourceMappingURL=internal-node.d.ts.map

package/dist/internal-node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal-node.d.ts","sourceRoot":"","sources":["../src/internal-node.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC"}

package/dist/internal-node.js

@@ -0,0 +1 @@
+export * from './node/internal-node.js';

package/dist/internal-request-response-factory.d.ts

@@ -0,0 +1,2 @@
+export * from './adapters/internal-request-response-factory.js';
+//# sourceMappingURL=internal-request-response-factory.d.ts.map

package/dist/internal-request-response-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal-request-response-factory.d.ts","sourceRoot":"","sources":["../src/internal-request-response-factory.ts"],"names":[],"mappings":"AAAA,cAAc,iDAAiD,CAAC"}

package/dist/internal-request-response-factory.js

@@ -0,0 +1 @@
+export * from './adapters/internal-request-response-factory.js';

package/dist/internal.d.ts

@@ -0,0 +1,2 @@
+export { APPLICATION_LOGGER, COMPILED_MODULES, HTTP_APPLICATION_ADAPTER, PLATFORM_SHELL, RUNTIME_CONTAINER, } from './tokens.js';
+//# sourceMappingURL=internal.d.ts.map

package/dist/internal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../src/internal.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,wBAAwB,EACxB,cAAc,EACd,iBAAiB,GAClB,MAAM,aAAa,CAAC"}

package/dist/internal.js

@@ -0,0 +1 @@
+export { APPLICATION_LOGGER, COMPILED_MODULES, HTTP_APPLICATION_ADAPTER, PLATFORM_SHELL, RUNTIME_CONTAINER } from './tokens.js';

package/dist/logging/json-logger.d.ts

@@ -0,0 +1,3 @@
+import type { ApplicationLogger } from '../types.js';
+export declare function createJsonApplicationLogger(): ApplicationLogger;
+//# sourceMappingURL=json-logger.d.ts.map

package/dist/logging/json-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-logger.d.ts","sourceRoot":"","sources":["../../src/logging/json-logger.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAqCrD,wBAAgB,2BAA2B,IAAI,iBAAiB,CAe/D"}

package/dist/logging/json-logger.js

@@ -0,0 +1,39 @@
+import { getCurrentRequestContext } from '@fluojs/http';
+function buildEntry(level, message, context, error) {
+  const entry = {
+    level,
+    message,
+    timestamp: new Date().toISOString()
+  };
+  const requestId = getCurrentRequestContext()?.requestId;
+  if (requestId) {
+    entry.requestId = requestId;
+  }
+  if (context) {
+    entry.context = context;
+  }
+  if (error instanceof Error) {
+    entry.error = {
+      message: error.message,
+      name: error.name,
+      stack: error.stack
+    };
+  }
+  return entry;
+}
+export function createJsonApplicationLogger() {
+  return {
+    debug(message, context) {
+      process.stdout.write(JSON.stringify(buildEntry('debug', message, context)) + '\n');
+    },
+    error(message, error, context) {
+      process.stderr.write(JSON.stringify(buildEntry('error', message, context, error)) + '\n');
+    },
+    log(message, context) {
+      process.stdout.write(JSON.stringify(buildEntry('log', message, context)) + '\n');
+    },
+    warn(message, context) {
+      process.stderr.write(JSON.stringify(buildEntry('warn', message, context)) + '\n');
+    }
+  };
+}

package/dist/logging/logger.d.ts

@@ -0,0 +1,3 @@
+import type { ApplicationLogger } from '../types.js';
+export declare function createConsoleApplicationLogger(): ApplicationLogger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logging/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/logging/logger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAuBrD,wBAAgB,8BAA8B,IAAI,iBAAiB,CAmBlE"}

package/dist/logging/logger.js

@@ -0,0 +1,36 @@
+const RESET = '\u001B[0m';
+const BRIGHT_GREEN = '\u001B[32m';
+const BRIGHT_RED = '\u001B[31m';
+const BRIGHT_YELLOW = '\u001B[33m';
+const DIM = '\u001B[2m';
+function colorize(value, color, enabled) {
+  return enabled ? `${color}${value}${RESET}` : value;
+}
+function formatLog(level, context, message, color) {
+  const prefix = colorize('[fluo]', BRIGHT_GREEN, color);
+  const pid = colorize(String(process.pid), BRIGHT_YELLOW, color);
+  const timestamp = colorize(new Date().toLocaleString('en-US'), DIM, color);
+  const levelColor = level === 'ERROR' || level === 'WARN' ? BRIGHT_RED : BRIGHT_GREEN;
+  const levelLabel = colorize(level, levelColor, color);
+  const contextLabel = colorize(`[${context}]`, BRIGHT_YELLOW, color);
+  return `${prefix} ${pid} - ${timestamp} ${levelLabel} ${contextLabel} ${message}`;
+}
+export function createConsoleApplicationLogger() {
+  return {
+    debug(message, context = 'fluo') {
+      console.debug(formatLog('DEBUG', context, message, Boolean(process.stdout.isTTY)));
+    },
+    error(message, error, context = 'fluo') {
+      console.error(formatLog('ERROR', context, message, Boolean(process.stderr.isTTY)));
+      if (error) {
+        console.error(error);
+      }
+    },
+    log(message, context = 'fluo') {
+      console.log(formatLog('LOG', context, message, Boolean(process.stdout.isTTY)));
+    },
+    warn(message, context = 'fluo') {
+      console.warn(formatLog('WARN', context, message, Boolean(process.stderr.isTTY)));
+    }
+  };
+}

package/dist/module-graph.d.ts

@@ -0,0 +1,26 @@
+import type { Provider } from '@fluojs/di';
+import type { Token } from '@fluojs/core';
+import type { BootstrapModuleOptions, CompiledModule, ModuleType } from './types.js';
+/**
+ * Returns the public token represented by a provider declaration.
+ *
+ * @param provider Provider declaration or class provider shortcut.
+ * @returns The token that should be registered and resolved for the provider.
+ */
+export declare function providerToken(provider: Provider): Token;
+/**
+ * Collects runtime provider tokens into a set for visibility and validation checks.
+ *
+ * @param providers Runtime providers supplied through bootstrap options.
+ * @returns A set containing each provider token exactly once.
+ */
+export declare function createRuntimeTokenSet(providers?: Provider[]): Set<Token>;
+/**
+ * Compiles and validates the reachable module graph for a bootstrap entry module.
+ *
+ * @param rootModule Root application module used as the graph entrypoint.
+ * @param options Bootstrap options that contribute runtime providers and validation tokens.
+ * @returns Compiled modules in dependency order after visibility and injection validation succeed.
+ */
+export declare function compileModuleGraph(rootModule: ModuleType, options?: BootstrapModuleOptions): CompiledModule[];
+//# sourceMappingURL=module-graph.d.ts.map

package/dist/module-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module-graph.d.ts","sourceRoot":"","sources":["../src/module-graph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAK1C,OAAO,KAAK,EAAE,sBAAsB,EAAE,cAAc,EAAoB,UAAU,EAAE,MAAM,YAAY,CAAC;AAEvG;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,QAAQ,GAAG,KAAK,CAMvD;AAyDD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,GAAE,QAAQ,EAAO,GAAG,GAAG,CAAC,KAAK,CAAC,CAE5E;AAyTD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,UAAU,EAAE,OAAO,GAAE,sBAA2B,GAAG,cAAc,EAAE,CASjH"}

package/dist/module-graph.js

@@ -0,0 +1,248 @@
+import { getClassDiMetadata, getModuleMetadata, getOwnClassDiMetadata } from '@fluojs/core/internal';
+import { ModuleGraphError, ModuleInjectionMetadataError, ModuleVisibilityError } from './errors.js';
+/**
+ * Returns the public token represented by a provider declaration.
+ *
+ * @param provider Provider declaration or class provider shortcut.
+ * @returns The token that should be registered and resolved for the provider.
+ */
+export function providerToken(provider) {
+  if (typeof provider === 'function') {
+    return provider;
+  }
+  return provider.provide;
+}
+function getEffectiveClassDiMetadata(target) {
+  const metadata = getClassDiMetadata(target);
+  if (!metadata) {
+    return undefined;
+  }
+  return {
+    inject: metadata.inject ? [...metadata.inject] : undefined
+  };
+}
+function isForwardRef(value) {
+  return typeof value === 'object' && value !== null && '__forwardRef__' in value && value.__forwardRef__ === true;
+}
+function isOptionalToken(value) {
+  return typeof value === 'object' && value !== null && '__optional__' in value && value.__optional__ === true;
+}
+function resolveInjectionToken(t) {
+  if (isForwardRef(t)) return t.forwardRef();
+  if (isOptionalToken(t)) return t.token;
+  return t;
+}
+function providerDependencies(provider) {
+  if (typeof provider === 'function') {
+    return [...(getEffectiveClassDiMetadata(provider)?.inject ?? [])];
+  }
+  if ('useFactory' in provider) {
+    return provider.inject ?? [];
+  }
+  if ('useClass' in provider) {
+    return provider.inject ?? [...(getEffectiveClassDiMetadata(provider.useClass)?.inject ?? [])];
+  }
+  return [];
+}
+function controllerDependencies(controller) {
+  return [...(getEffectiveClassDiMetadata(controller)?.inject ?? [])];
+}
+
+/**
+ * Collects runtime provider tokens into a set for visibility and validation checks.
+ *
+ * @param providers Runtime providers supplied through bootstrap options.
+ * @returns A set containing each provider token exactly once.
+ */
+export function createRuntimeTokenSet(providers = []) {
+  return new Set(providers.map(provider => providerToken(provider)));
+}
+function mergeRuntimeTokenSets(providers = [], validationTokens = []) {
+  return new Set([...createRuntimeTokenSet(providers), ...validationTokens]);
+}
+function requiredConstructorParameters(target) {
+  if (getOwnClassDiMetadata(target)?.inject !== undefined) {
+    return 0;
+  }
+  return target.length;
+}
+function validateClassInjectionMetadata(subject, implementation, inject, scope, remedy) {
+  const required = requiredConstructorParameters(implementation);
+  if (required === 0 || inject.length >= required) {
+    return;
+  }
+  const missingIndex = inject.length;
+  const configured = inject.length;
+  const parameterWord = required === 1 ? 'parameter' : 'parameters';
+  const tokenWord = configured === 1 ? 'token is' : 'tokens are';
+  throw new ModuleInjectionMetadataError(`${subject} in ${scope} declares ${required} constructor ${parameterWord} but only ${configured} injection ${tokenWord} configured. Add ${remedy} for constructor parameter #${missingIndex}.`, {
+    module: scope,
+    phase: 'injection metadata validation',
+    hint: `Ensure ${subject} has a matching @Inject(...) decorator or provider.inject array that covers all ${required} constructor parameters. Use @Inject() for an explicit empty override.`
+  });
+}
+function validateProviderInjectionMetadata(provider, scope) {
+  if (typeof provider === 'function') {
+    validateClassInjectionMetadata(`Provider ${provider.name || '<anonymous>'}`, provider, getEffectiveClassDiMetadata(provider)?.inject ?? [], scope, '@Inject(...) metadata');
+    return;
+  }
+  if ('useClass' in provider) {
+    const providedName = String(provider.provide);
+    const implementationName = provider.useClass.name || '<anonymous>';
+    const subject = provider.provide === provider.useClass ? `Provider ${implementationName}` : `Provider ${providedName} (${implementationName})`;
+    validateClassInjectionMetadata(subject, provider.useClass, provider.inject ?? getEffectiveClassDiMetadata(provider.useClass)?.inject ?? [], scope, provider.inject ? 'provider.inject entries' : '@Inject(...) metadata or provider.inject entries');
+  }
+}
+function validateControllerInjectionMetadata(controller, scope) {
+  validateClassInjectionMetadata(`Controller ${controller.name || '<anonymous>'}`, controller, getEffectiveClassDiMetadata(controller)?.inject ?? [], scope, '@Inject(...) metadata');
+}
+function normalizeModuleDefinition(rawDefinition) {
+  if (!rawDefinition) {
+    return {};
+  }
+  return {
+    global: rawDefinition.global ?? false,
+    imports: rawDefinition.imports ?? [],
+    providers: rawDefinition.providers ?? [],
+    controllers: rawDefinition.controllers ?? [],
+    exports: rawDefinition.exports ?? [],
+    middleware: rawDefinition.middleware ?? []
+  };
+}
+function compileModule(moduleType, runtimeProviderTokens, compiled = new Map(), visiting = new Set(), ordered = []) {
+  if (compiled.has(moduleType)) {
+    const existing = compiled.get(moduleType);
+    if (existing) {
+      return existing;
+    }
+  }
+  if (visiting.has(moduleType)) {
+    throw new ModuleGraphError(`Circular module import detected for ${moduleType.name}.`, {
+      module: moduleType.name,
+      phase: 'module graph compilation',
+      hint: 'Break the import cycle by extracting shared providers into a separate module that both sides can import independently.'
+    });
+  }
+  visiting.add(moduleType);
+  const definition = normalizeModuleDefinition(getModuleMetadata(moduleType));
+  for (const imported of definition.imports ?? []) {
+    compileModule(imported, runtimeProviderTokens, compiled, visiting, ordered);
+  }
+  const providerTokens = new Set((definition.providers ?? []).map(provider => providerToken(provider)));
+  const compiledModule = {
+    type: moduleType,
+    definition,
+    exportedTokens: new Set(),
+    providerTokens
+  };
+  compiled.set(moduleType, compiledModule);
+  visiting.delete(moduleType);
+  ordered.push(compiledModule);
+  return compiledModule;
+}
+function resolveImportedModules(compiledModule, compiledByType) {
+  return (compiledModule.definition.imports ?? []).map(imported => {
+    const importedModule = compiledByType.get(imported);
+    if (!importedModule) {
+      throw new ModuleGraphError(`Imported module ${imported.name} was not compiled.`, {
+        module: imported.name,
+        phase: 'module graph validation',
+        hint: `Ensure ${imported.name} is decorated with @Module() and included in the imports array of a compiled module.`
+      });
+    }
+    return importedModule;
+  });
+}
+function createImportedExportedTokenSet(importedModules) {
+  return new Set(importedModules.flatMap(imported => Array.from(imported.exportedTokens)));
+}
+function createAccessibleTokenSet(runtimeProviderTokens, moduleProviderTokens, importedExportedTokens, globalExportedTokens) {
+  return new Set([...runtimeProviderTokens, ...moduleProviderTokens, ...importedExportedTokens, ...globalExportedTokens]);
+}
+function validateProviderVisibility(compiledModule, scope, accessibleTokens) {
+  for (const provider of compiledModule.definition.providers ?? []) {
+    validateProviderInjectionMetadata(provider, scope);
+    for (const rawToken of providerDependencies(provider)) {
+      const token = resolveInjectionToken(rawToken);
+      if (!accessibleTokens.has(token)) {
+        throw new ModuleVisibilityError(`Provider ${String(providerToken(provider))} in module ${compiledModule.type.name} cannot access token ${String(token)} because it is not local, not exported by an imported module, and not visible through a global module.`, {
+          module: compiledModule.type.name,
+          token,
+          phase: 'provider visibility validation',
+          hint: `Add ${String(token)} to the exports array of the module that owns it, then import that module into ${compiledModule.type.name}. Alternatively, mark the owning module with @Global() to make its exports universally visible.`
+        });
+      }
+    }
+  }
+}
+function validateControllerVisibility(compiledModule, scope, accessibleTokens) {
+  for (const controller of compiledModule.definition.controllers ?? []) {
+    validateControllerInjectionMetadata(controller, scope);
+    for (const rawToken of controllerDependencies(controller)) {
+      const token = resolveInjectionToken(rawToken);
+      if (!accessibleTokens.has(token)) {
+        throw new ModuleVisibilityError(`Controller ${controller.name} in module ${compiledModule.type.name} cannot access token ${String(token)} because it is not local, not exported by an imported module, and not visible through a global module.`, {
+          module: compiledModule.type.name,
+          token,
+          phase: 'controller visibility validation',
+          hint: `Add ${String(token)} to the exports array of the module that owns it, then import that module into ${compiledModule.type.name}. Alternatively, mark the owning module with @Global().`
+        });
+      }
+    }
+  }
+}
+function createExportedTokenSet(compiledModule, importedExportedTokens) {
+  const exportedTokens = new Set();
+  for (const token of compiledModule.definition.exports ?? []) {
+    if (!compiledModule.providerTokens.has(token) && !importedExportedTokens.has(token)) {
+      throw new ModuleVisibilityError(`Module ${compiledModule.type.name} cannot export token ${String(token)} because it is neither local nor re-exported from an imported module.`, {
+        module: compiledModule.type.name,
+        token,
+        phase: 'export validation',
+        hint: `Either add a provider for ${String(token)} to ${compiledModule.type.name}'s providers array, or import a module that exports ${String(token)} so it can be re-exported.`
+      });
+    }
+    exportedTokens.add(token);
+  }
+  return exportedTokens;
+}
+function validateCompiledModules(modules, runtimeProviders, runtimeProviderTokens) {
+  const compiledByType = new Map(modules.map(compiledModule => [compiledModule.type, compiledModule]));
+  const globalExportedTokens = new Set();
+  for (const provider of runtimeProviders) {
+    validateProviderInjectionMetadata(provider, 'bootstrap runtime');
+  }
+  for (const compiledModule of modules) {
+    if (!compiledModule.definition.global) {
+      continue;
+    }
+    for (const token of compiledModule.definition.exports ?? []) {
+      globalExportedTokens.add(token);
+    }
+  }
+  for (const compiledModule of modules) {
+    const scope = `module ${compiledModule.type.name}`;
+    const importedModules = resolveImportedModules(compiledModule, compiledByType);
+    const importedExportedTokens = createImportedExportedTokenSet(importedModules);
+    const accessibleTokens = createAccessibleTokenSet(runtimeProviderTokens, compiledModule.providerTokens, importedExportedTokens, globalExportedTokens);
+    validateProviderVisibility(compiledModule, scope, accessibleTokens);
+    validateControllerVisibility(compiledModule, scope, accessibleTokens);
+    compiledModule.exportedTokens = createExportedTokenSet(compiledModule, importedExportedTokens);
+  }
+}
+
+/**
+ * Compiles and validates the reachable module graph for a bootstrap entry module.
+ *
+ * @param rootModule Root application module used as the graph entrypoint.
+ * @param options Bootstrap options that contribute runtime providers and validation tokens.
+ * @returns Compiled modules in dependency order after visibility and injection validation succeed.
+ */
+export function compileModuleGraph(rootModule, options = {}) {
+  const ordered = [];
+  const runtimeProviders = options.providers ?? [];
+  const runtimeProviderTokens = mergeRuntimeTokenSets(runtimeProviders, options.validationTokens ?? []);
+  compileModule(rootModule, runtimeProviderTokens, new Map(), new Set(), ordered);
+  validateCompiledModules(ordered, runtimeProviders, runtimeProviderTokens);
+  return ordered;
+}