@open-mercato/shared 0.6.7 → 0.6.8-canary.320.1.bf889f49e4

package/src/lib/bootstrap/dynamicLoader.ts

@@ -1,16 +1,137 @@
 import type { BootstrapData } from './types'
+import type { AppDiRegistrar } from '../di/container'
 import { findAppRoot, type AppRoot } from './appResolver'
 import { registerEntityIds } from '../encryption/entityIds'
+import { createLogger } from '../logger'
 import {
   ensureMikroOrmV7GeneratedCacheCompatibility,
   recoverMikroOrmV7GeneratedCacheFromImportError,
 } from './generatedCacheRecovery'
+import { CLIENT_ONLY_STUB_NAMESPACE, createClientOnlyStubPlugin } from './clientOnlyModules'
 import path from 'node:path'
 import fs from 'node:fs'
 import crypto from 'node:crypto'
 import { createRequire } from 'node:module'
 import { pathToFileURL } from 'node:url'
 
+let activeBootstrapLoads = 0
+let esbuildRuntime: typeof import('esbuild') | null = null
+let esbuildStopPromise: Promise<void> | null = null
+
+const logger = createLogger('shared').child({ component: 'bootstrap' })
+
+async function getEsbuildRuntime(): Promise<typeof import('esbuild')> {
+  if (esbuildStopPromise) await esbuildStopPromise
+  if (esbuildRuntime) return esbuildRuntime
+
+  const loadedRuntime = await import('esbuild')
+  esbuildRuntime ??= loadedRuntime
+  return esbuildRuntime
+}
+
+async function withEsbuildLifecycle<T>(load: () => Promise<T>): Promise<T> {
+  activeBootstrapLoads += 1
+
+  try {
+    return await load()
+  } finally {
+    activeBootstrapLoads -= 1
+    if (activeBootstrapLoads === 0 && esbuildRuntime) {
+      // esbuild keeps a helper process alive after build(). Bootstrap compilation
+      // is a bounded phase, so release it once every concurrent loader is done.
+      // A later build() call transparently starts a fresh helper process.
+      const runtimeToStop = esbuildRuntime
+      esbuildRuntime = null
+      const stopPromise = runtimeToStop.stop().catch((err) => {
+        logger.warn('Failed to stop the bootstrap compiler service', { err })
+      })
+      esbuildStopPromise = stopPromise
+      try {
+        await stopPromise
+      } finally {
+        if (esbuildStopPromise === stopPromise) esbuildStopPromise = null
+      }
+    }
+  }
+}
+
+/**
+ * Thrown when an expected generated source file is absent.
+ *
+ * Optional registries treat this as the supported compatibility case (an app
+ * that never generated the file), which is what makes it distinguishable from
+ * a file that exists but fails to compile or import.
+ */
+class GeneratedFileNotFoundError extends Error {
+  readonly filePath: string
+
+  constructor(filePath: string) {
+    super(`Generated file not found: ${filePath}`)
+    this.name = 'GeneratedFileNotFoundError'
+    this.filePath = filePath
+  }
+}
+
+/**
+ * esbuild plugins for the CLI bundle, in resolution order. The client-only stub must come
+ * first so it wins over the alias and external plugins for `*.client` dynamic imports.
+ *
+ * Exported so the wiring itself is testable: a test that only exercises
+ * `createClientOnlyStubPlugin` in isolation stays green if the plugin is dropped from this
+ * list, which would silently reintroduce #4623.
+ */
+export function createCliBundlePlugins(appRoot: string): import('esbuild').Plugin[] {
+  // Plugin to resolve the @/ alias the way the app tsconfig maps it:
+  // `@/.mercato/*` to the app root, every other `@/*` to the app's src/ directory.
+  const aliasPlugin: import('esbuild').Plugin = {
+    name: 'alias-resolver',
+    setup(build) {
+      build.onResolve({ filter: /^@\// }, (args) => {
+        const rest = args.path.slice('@/'.length)
+        const bases = rest.startsWith('.mercato/')
+          ? [path.join(appRoot, rest)]
+          : [path.join(appRoot, 'src', rest), path.join(appRoot, rest)]
+        for (const base of bases) {
+          if (fs.existsSync(base) && fs.statSync(base).isFile()) {
+            return { path: base }
+          }
+          for (const suffix of ['.ts', '.tsx', '/index.ts', '/index.tsx']) {
+            if (fs.existsSync(base + suffix)) {
+              return { path: base + suffix }
+            }
+          }
+        }
+        // Nothing matched — hand esbuild the literal mapping so it reports the
+        // missing file against the path the app author actually wrote.
+        return { path: path.join(appRoot, rest) }
+      })
+    },
+  }
+
+  // Plugin to mark non-JSON package imports as external
+  const externalNonJsonPlugin: import('esbuild').Plugin = {
+    name: 'external-non-json',
+    setup(build) {
+      // Mark all package imports as external EXCEPT JSON files
+      // Filter matches paths that don't start with . or / (package imports like @open-mercato/shared)
+      build.onResolve({ filter: /^[^./]/ }, (args) => {
+        // Skip Windows absolute paths (e.g., C:\...) - they're local files, not packages
+        if (/^[a-zA-Z]:/.test(args.path)) {
+          return null // Let esbuild handle it
+        }
+        // If it's a JSON file, let esbuild bundle it
+        if (args.path.endsWith('.json')) {
+          return null // Let esbuild handle it
+        }
+        // Otherwise mark as external
+        return { path: args.path, external: true }
+      })
+    },
+  }
+
+  return [createClientOnlyStubPlugin(), aliasPlugin, externalNonJsonPlugin]
+}
+
 const DYNAMIC_LOADER_CACHE_VERSION = 4
 
 type DynamicLoaderCacheMetadata = {
@@ -167,6 +288,7 @@ function collectDependencyHashes(
 ): Record<string, string> {
   return Object.fromEntries(
     Object.keys(inputs)
+      .filter((inputPath) => !inputPath.startsWith(`${CLIENT_ONLY_STUB_NAMESPACE}:`))
       .map((inputPath) => {
         const absolutePath = path.isAbsolute(inputPath)
           ? inputPath
@@ -222,21 +344,74 @@ function cacheIsValid(
 }
 
 /**
- * Compile a TypeScript file to JavaScript using esbuild bundler.
- * This bundles the file and all its dependencies, handling JSON imports properly.
- * The compiled file is written next to the source file with a .mjs extension.
+ * Options for `compileAndImport`.
+ *
+ * Both paths default to the generated-registry layout (`<appRoot>/.mercato/generated/<file>.ts`
+ * compiled to a `.mjs` sibling). Sources that live elsewhere in the app — `src/di.ts` — MUST pass
+ * both explicitly: the default app root is derived by walking three directories up from the source,
+ * which only holds inside `.mercato/generated`.
+ */
+type CompileAndImportOptions = {
+  appRoot?: string
+  outFile?: string
+  allowRecovery?: boolean
+}
+
+/**
+ * Options for `compileAppSourceFile`.
+ *
+ * `appRoot` anchors the tsconfig, the `@/` alias resolution and the dependency
+ * cache; `outFile` is the absolute path of the artifact to write. `format`
+ * selects the module system of that artifact — `'cjs'` exists for the Jest
+ * runtime, which cannot `import()` an ESM sibling.
+ */
+export type CompileAppSourceOptions = {
+  appRoot: string
+  outFile: string
+  format?: 'esm' | 'cjs'
+}
+
+/**
+ * Compile one app-owned TypeScript source and its relative import graph into a
+ * single JavaScript artifact, leaving every package import external.
+ *
+ * This is the only supported way to load app source (`apps/<app>/src/**`,
+ * `.mercato/generated/**`) from a plain Node process. Those files are never
+ * compiled to `dist`, and Node's own type stripping cannot load them: it
+ * requires explicit file extensions on relative specifiers and rejects the
+ * decorator and enum syntax the entities and DI files use.
+ *
+ * The artifact is cached against the content of the entry, its whole bundled
+ * dependency graph, and the tsconfig chain, so an edit anywhere in the graph
+ * invalidates it.
+ *
+ * The build runs inside the shared esbuild lifecycle. Callers outside a
+ * bootstrap load — the generated-registry loader compiling an `@app` module —
+ * would otherwise hold a build on a service another scope is entitled to
+ * `stop()`, and would leave the helper process running afterwards. Nesting is
+ * safe: the scope only releases the service when the last participant exits.
  */
-async function compileAndImport(tsPath: string, allowRecovery: boolean = true): Promise<Record<string, unknown>> {
-  const jsPath = tsPath.replace(/\.ts$/, '.mjs')
-  const appRoot = path.dirname(path.dirname(path.dirname(tsPath)))
+export async function compileAppSourceFile(
+  tsPath: string,
+  options: CompileAppSourceOptions,
+): Promise<string> {
+  return withEsbuildLifecycle(() => compileAppSourceFileWithActiveEsbuild(tsPath, options))
+}
+
+async function compileAppSourceFileWithActiveEsbuild(
+  tsPath: string,
+  options: CompileAppSourceOptions,
+): Promise<string> {
+  const { appRoot, outFile } = options
+  const format = options.format ?? 'esm'
   const appTsconfig = path.join(appRoot, 'tsconfig.json')
-  const metadataPath = cacheMetadataPath(jsPath)
+  const metadataPath = cacheMetadataPath(outFile)
 
   const tsExists = fs.existsSync(tsPath)
   const tsconfigExists = fs.existsSync(appTsconfig)
 
   if (!tsExists) {
-    throw new Error(`Generated file not found: ${tsPath}`)
+    throw new GeneratedFileNotFoundError(tsPath)
   }
   if (!tsconfigExists) {
     throw new Error(`App TypeScript config not found: ${appTsconfig}`)
@@ -244,79 +419,59 @@ async function compileAndImport(tsPath: string, allowRecovery: boolean = true):
 
   const tsconfigPaths = collectTsconfigPaths(appTsconfig)
   const expectedInputHash = cacheInputHash(tsPath, appRoot, tsconfigPaths)
-  const needsCompile = !cacheIsValid(appRoot, jsPath, metadataPath, expectedInputHash)
-
-  if (needsCompile) {
-    // Dynamically import esbuild only when needed
-    const esbuild = await import('esbuild')
-
-    // Plugin to resolve @/ alias to app root (works for @app modules)
-    const aliasPlugin: import('esbuild').Plugin = {
-      name: 'alias-resolver',
-      setup(build) {
-        // Resolve @/ alias to app root
-        build.onResolve({ filter: /^@\// }, (args) => {
-          const resolved = path.join(appRoot, args.path.slice(2))
-          // Try with .ts extension if base path doesn't exist
-          if (!fs.existsSync(resolved) && fs.existsSync(resolved + '.ts')) {
-            return { path: resolved + '.ts' }
-          }
-          // Also check for /index.ts if it's a directory
-          if (fs.existsSync(resolved) && fs.statSync(resolved).isDirectory() && fs.existsSync(path.join(resolved, 'index.ts'))) {
-            return { path: path.join(resolved, 'index.ts') }
-          }
-          return { path: resolved }
-        })
-      },
-    }
 
-    // Plugin to mark non-JSON package imports as external
-    const externalNonJsonPlugin: import('esbuild').Plugin = {
-      name: 'external-non-json',
-      setup(build) {
-        // Mark all package imports as external EXCEPT JSON files
-        // Filter matches paths that don't start with . or / (package imports like @open-mercato/shared)
-        build.onResolve({ filter: /^[^./]/ }, (args) => {
-          // Skip Windows absolute paths (e.g., C:\...) - they're local files, not packages
-          if (/^[a-zA-Z]:/.test(args.path)) {
-            return null // Let esbuild handle it
-          }
-          // If it's a JSON file, let esbuild bundle it
-          if (args.path.endsWith('.json')) {
-            return null // Let esbuild handle it
-          }
-          // Otherwise mark as external
-          return { path: args.path, external: true }
-        })
-      },
-    }
+  if (cacheIsValid(appRoot, outFile, metadataPath, expectedInputHash)) {
+    return outFile
+  }
 
-    // Use esbuild.build with bundling to handle JSON imports
-    const result = await esbuild.build({
-      entryPoints: [tsPath],
-      outfile: jsPath,
-      absWorkingDir: appRoot,
-      bundle: true,
-      metafile: true,
-      format: 'esm',
-      platform: 'node',
-      target: 'node18',
-      tsconfig: appTsconfig,
-      plugins: [aliasPlugin, externalNonJsonPlugin],
-      // Allow JSON imports
-      loader: { '.json': 'json' },
-    })
-    const metadata: DynamicLoaderCacheMetadata = {
-      version: DYNAMIC_LOADER_CACHE_VERSION,
-      inputHash: expectedInputHash,
-      outputHash: contentHash(fs.readFileSync(jsPath)),
-      dependencies: {
-        ...collectDependencyHashes(appRoot, result.metafile.inputs),
-        ...hashFilesRelativeTo(appRoot, tsconfigPaths),
-      },
-    }
-    fs.writeFileSync(metadataPath, JSON.stringify(metadata))
+  fs.mkdirSync(path.dirname(outFile), { recursive: true })
+  // Dynamically import esbuild only when needed
+  const esbuild = await getEsbuildRuntime()
+
+  // Use esbuild.build with bundling to handle JSON imports
+  const result = await esbuild.build({
+    entryPoints: [tsPath],
+    outfile: outFile,
+    absWorkingDir: appRoot,
+    bundle: true,
+    metafile: true,
+    format,
+    platform: 'node',
+    target: 'node18',
+    tsconfig: appTsconfig,
+    plugins: createCliBundlePlugins(appRoot),
+    // Allow JSON imports
+    loader: { '.json': 'json' },
+  })
+  const metadata: DynamicLoaderCacheMetadata = {
+    version: DYNAMIC_LOADER_CACHE_VERSION,
+    inputHash: expectedInputHash,
+    outputHash: contentHash(fs.readFileSync(outFile)),
+    dependencies: {
+      ...collectDependencyHashes(appRoot, result.metafile.inputs),
+      ...hashFilesRelativeTo(appRoot, tsconfigPaths),
+    },
   }
+  fs.writeFileSync(metadataPath, JSON.stringify(metadata))
+
+  return outFile
+}
+
+/**
+ * Compile a TypeScript file to JavaScript using esbuild bundler.
+ * This bundles the file and all its dependencies, handling JSON imports properly.
+ * The compiled file is written next to the source file with a .mjs extension unless
+ * `outFile` says otherwise.
+ */
+async function compileAndImport(
+  tsPath: string,
+  options: CompileAndImportOptions = {},
+): Promise<Record<string, unknown>> {
+  const allowRecovery = options.allowRecovery ?? true
+  const jsPath = options.outFile ?? tsPath.replace(/\.ts$/, '.mjs')
+  const appRoot = options.appRoot ?? path.dirname(path.dirname(path.dirname(tsPath)))
+
+  await compileAppSourceFile(tsPath, { appRoot, outFile: jsPath })
 
   // Import the compiled JavaScript
   try {
@@ -333,25 +488,45 @@ async function compileAndImport(tsPath: string, allowRecovery: boolean = true):
       throw error
     }
 
-    return compileAndImport(tsPath, false)
+    return compileAndImport(tsPath, { ...options, allowRecovery: false })
   }
 }
 
 
 /**
- * Dynamically load bootstrap data from a resolved app directory.
- *
- * IMPORTANT: This only works in unbundled contexts (CLI, tsx).
- * Do NOT use this in Next.js bundled code - use static imports instead.
- *
- * For CLI context, we skip loading modules.generated.ts which has Next.js dependencies.
- * CLI commands are discovered separately via the CLI module system.
+ * Load a generated registry that older apps may not have generated yet.
  *
- * @param appRoot - Optional explicit app root path. If not provided, will search from cwd.
- * @returns The loaded bootstrap data
- * @throws Error if app root cannot be found or generated files are missing
+ * An absent source file is the supported compatibility case and resolves to
+ * `fallback` quietly. Any other failure — a compile error, a broken import, a
+ * runtime throw at module scope — still resolves to `fallback` so bootstrap
+ * keeps working, but is reported at error level: a registry that silently
+ * degrades to nothing is exactly how command interceptors stopped applying in
+ * worker/CLI processes (#4327, #4491).
  */
-export async function loadBootstrapData(appRoot?: string): Promise<BootstrapData> {
+async function loadOptionalGeneratedModule(
+  tsPath: string,
+  fallback: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+  try {
+    return await compileAndImport(tsPath)
+  } catch (error) {
+    if (error instanceof GeneratedFileNotFoundError) {
+      logger.debug('Optional generated registry not present, using empty fallback', {
+        file: path.basename(tsPath),
+      })
+      return fallback
+    }
+
+    logger.error('Failed to load generated registry, continuing without its entries', {
+      file: path.basename(tsPath),
+      filePath: tsPath,
+      err: error,
+    })
+    return fallback
+  }
+}
+
+function resolveAppRootOrThrow(appRoot?: string): AppRoot {
   const resolved: AppRoot | null = appRoot
     ? {
         generatedDir: path.join(appRoot, '.mercato', 'generated'),
@@ -368,6 +543,68 @@ export async function loadBootstrapData(appRoot?: string): Promise<BootstrapData
     )
   }
 
+  return resolved
+}
+
+/**
+ * Load the app-level DI registrar (`src/di.ts`) for the dynamic bootstrap path.
+ *
+ * The Next.js runtime imports `@/di` statically from its own `src/bootstrap.ts` and hands the
+ * registrar to `createBootstrap`. Worker, scheduler and CLI processes bootstrap through
+ * `bootstrapFromAppRoot` instead, where the `@/` alias does not exist — so without this the app's
+ * DI registrations silently never ran there, and every request container paid a failed
+ * `import('@/di')` resolution (the compatibility fallback in `lib/di/container.ts`).
+ *
+ * An absent `src/di.ts` is the supported case and resolves to `null` quietly. A file that exists
+ * but cannot be compiled, imported, or does not export `register` is reported at error level and
+ * still resolves to `null`, so a broken app DI module degrades the same way a broken generated
+ * registry does (#4327, #4491) instead of taking the whole process down.
+ */
+async function loadAppDiRegistrar(appDir: string): Promise<AppDiRegistrar | null> {
+  const tsPath = path.join(appDir, 'src', 'di.ts')
+  if (!fs.existsSync(tsPath)) {
+    logger.debug('App-level DI module not present, skipping its registrations', { filePath: tsPath })
+    return null
+  }
+
+  try {
+    const appDiModule = await compileAndImport(tsPath, {
+      appRoot: appDir,
+      outFile: path.join(appDir, '.mercato', 'generated', 'app-di.compiled.mjs'),
+    })
+    const register = appDiModule.register
+    if (typeof register !== 'function') {
+      logger.error('App-level DI module exports no register(); its registrations are skipped', {
+        filePath: tsPath,
+      })
+      return null
+    }
+    return register as AppDiRegistrar
+  } catch (error) {
+    logger.error('Failed to load the app-level DI module; its registrations are skipped', {
+      filePath: tsPath,
+      err: error,
+    })
+    return null
+  }
+}
+
+/**
+ * Dynamically load bootstrap data from a resolved app directory.
+ *
+ * IMPORTANT: This only works in unbundled contexts (CLI, tsx).
+ * Do NOT use this in Next.js bundled code - use static imports instead.
+ *
+ * For CLI context, we skip loading modules.generated.ts which has Next.js dependencies.
+ * CLI commands are discovered separately via the CLI module system.
+ *
+ * @param appRoot - Optional explicit app root path. If not provided, will search from cwd.
+ * @returns The loaded bootstrap data
+ * @throws Error if app root cannot be found or generated files are missing
+ */
+async function loadBootstrapDataWithActiveEsbuild(appRoot?: string): Promise<BootstrapData> {
+  const resolved = resolveAppRootOrThrow(appRoot)
+
   const { generatedDir } = resolved
 
   ensureMikroOrmV7GeneratedCacheCompatibility(resolved.appDir)
@@ -392,10 +629,12 @@ export async function loadBootstrapData(appRoot?: string): Promise<BootstrapData
     compileAndImport(path.join(generatedDir, 'modules.cli.generated.ts')),
     compileAndImport(path.join(generatedDir, 'entities.generated.ts')),
     compileAndImport(path.join(generatedDir, 'di.generated.ts')),
-    compileAndImport(path.join(generatedDir, 'search.generated.ts')).catch(() => ({ searchModuleConfigs: [] })),
-    compileAndImport(path.join(generatedDir, 'command-loaders.generated.ts')).catch(() => ({ commandLoaderEntries: [] })),
-    compileAndImport(path.join(generatedDir, 'command-interceptors.generated.ts')).catch(() => ({ commandInterceptorEntries: [] })),
-    compileAndImport(path.join(generatedDir, 'workflows.generated.ts')).catch(() => ({ allCodeWorkflows: [] })),
+    loadOptionalGeneratedModule(path.join(generatedDir, 'search.generated.ts'), { searchModuleConfigs: [] }),
+    loadOptionalGeneratedModule(path.join(generatedDir, 'command-loaders.generated.ts'), { commandLoaderEntries: [] }),
+    loadOptionalGeneratedModule(path.join(generatedDir, 'command-interceptors.generated.ts'), {
+      commandInterceptorEntries: [],
+    }),
+    loadOptionalGeneratedModule(path.join(generatedDir, 'workflows.generated.ts'), { allCodeWorkflows: [] }),
   ])
 
   return {
@@ -423,6 +662,10 @@ export async function loadBootstrapData(appRoot?: string): Promise<BootstrapData
   }
 }
 
+export async function loadBootstrapData(appRoot?: string): Promise<BootstrapData> {
+  return withEsbuildLifecycle(() => loadBootstrapDataWithActiveEsbuild(appRoot))
+}
+
 /**
  * Create and execute bootstrap in CLI context.
  *
@@ -437,8 +680,15 @@ export async function loadBootstrapData(appRoot?: string): Promise<BootstrapData
  */
 export async function bootstrapFromAppRoot(appRoot?: string): Promise<BootstrapData> {
   const { createBootstrap, waitForAsyncRegistration } = await import('./factory.js')
-  const data = await loadBootstrapData(appRoot)
-  const bootstrap = createBootstrap(data)
+  const resolved = resolveAppRootOrThrow(appRoot)
+  // Both loads compile through esbuild, so they share one lifecycle scope: without it
+  // `loadBootstrapData` releases the esbuild helper process and `loadAppDiRegistrar`
+  // silently starts a second one that nothing ever stops.
+  const { data, appDiRegistrar } = await withEsbuildLifecycle(async () => ({
+    data: await loadBootstrapData(resolved.appDir),
+    appDiRegistrar: await loadAppDiRegistrar(resolved.appDir),
+  }))
+  const bootstrap = createBootstrap(data, appDiRegistrar ? { appDiRegistrar } : {})
   bootstrap()
   // In CLI context, wait for async registrations (UI widgets, search configs, etc.)
   await waitForAsyncRegistration()

package/src/lib/bootstrap/factory.ts

@@ -17,7 +17,7 @@ import { registerNotificationHandlers } from '../notifications/handler-registry'
 import { clearRegisteredIntegrations, registerBundles, registerIntegrations } from '../../modules/integrations/types'
 import { applyComponentOverridesToEntries } from '../../modules/overrides'
 
-let _bootstrapped = false
+const _bootstrappedKeys = new Set<string>()
 
 // Store the async registration promise so callers can await it if needed
 let _asyncRegistrationPromise: Promise<void> | null = null
@@ -34,13 +34,14 @@ let _asyncRegistrationPromise: Promise<void> | null = null
  */
 export function createBootstrap(data: BootstrapData, options: BootstrapOptions = {}) {
   return function bootstrap(): void {
+    const registrationKey = options.registrationKey ?? 'default'
     if (options.appDiRegistrar) {
       registerAppDiRegistrar(options.appDiRegistrar)
     }
     // In development, always re-run registrations to handle HMR
     // (Module state may be reset when Turbopack reloads packages)
-    if (_bootstrapped && process.env.NODE_ENV !== 'development') return
-    _bootstrapped = true
+    if (_bootstrappedKeys.has(registrationKey) && process.env.NODE_ENV !== 'development') return
+    _bootstrappedKeys.add(registrationKey)
 
     // === 1. Foundation: ORM entities and DI registrars ===
     registerOrmEntities(data.entities)
@@ -138,21 +139,26 @@ export async function waitForAsyncRegistration(): Promise<void> {
 }
 
 async function registerWidgetsAndOptionalPackages(data: BootstrapData, options: BootstrapOptions): Promise<void> {
-  // Register UI widgets (dynamic imports to avoid circular deps with ui/core packages)
+  // Register widget data required by server-side injection independently from
+  // browser-facing UI registries. API-only bootstraps avoid loading @open-mercato/ui.
   try {
-    const [dashboardRegistry, injectionRegistry, coreInjection] = await Promise.all([
-      import('@open-mercato/ui/backend/dashboard/widgetRegistry'),
-      import('@open-mercato/ui/backend/injection/widgetRegistry'),
-      import('@open-mercato/core/modules/widgets/lib/injection'),
-    ])
-
-    dashboardRegistry.registerDashboardWidgets(data.dashboardWidgetEntries)
-    injectionRegistry.registerInjectionWidgets(data.injectionWidgetEntries)
-    coreInjection.registerCoreInjectionWidgets(data.injectionWidgetEntries)
+    const coreInjection = await import('@open-mercato/core/modules/widgets/lib/injection')
+    if (!options.skipCoreInjectionWidgets) {
+      coreInjection.registerCoreInjectionWidgets(data.injectionWidgetEntries)
+    }
     coreInjection.registerCoreInjectionTables(data.injectionTables)
     coreInjection.registerEnabledModuleIds(
       data.modules.map((module) => module.id).filter((id): id is string => typeof id === 'string' && id.length > 0),
     )
+
+    if (!options.skipUiRegistries) {
+      const [dashboardRegistry, injectionRegistry] = await Promise.all([
+        import('@open-mercato/ui/backend/dashboard/widgetRegistry'),
+        import('@open-mercato/ui/backend/injection/widgetRegistry'),
+      ])
+      dashboardRegistry.registerDashboardWidgets(data.dashboardWidgetEntries)
+      injectionRegistry.registerInjectionWidgets(data.injectionWidgetEntries)
+    }
   } catch {
     // UI packages may not be available in all contexts
   }
@@ -170,12 +176,12 @@ async function registerWidgetsAndOptionalPackages(data: BootstrapData, options:
  * Check if bootstrap has been called.
  */
 export function isBootstrapped(): boolean {
-  return _bootstrapped
+  return _bootstrappedKeys.size > 0
 }
 
 /**
  * Reset bootstrap state. Useful for testing.
  */
 export function resetBootstrapState(): void {
-  _bootstrapped = false
+  _bootstrappedKeys.clear()
 }

package/src/lib/bootstrap/types.ts

@@ -69,6 +69,12 @@ export interface BootstrapData {
 
 export interface BootstrapOptions {
   skipSearchConfigs?: boolean
+  /** Independent registration scope for partitioned runtime bootstraps. */
+  registrationKey?: string
+  /** Skip browser-facing dashboard/injection registries in API-only runtimes. */
+  skipUiRegistries?: boolean
+  /** Keep an existing core injection-widget registry intact in partitioned runtimes. */
+  skipCoreInjectionWidgets?: boolean
   onRegistrationComplete?: () => void
   appDiRegistrar?: AppDiRegistrar
 }