@open-mercato/shared 0.6.7-develop.6828.1.ab1620a63e → 0.6.7-develop.6834.1.e76f4b8cbc

package/src/lib/bootstrap/dynamicLoader.ts

@@ -1,4 +1,5 @@
 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'
@@ -41,22 +42,29 @@ class GeneratedFileNotFoundError extends Error {
  * list, which would silently reintroduce #4623.
  */
 export function createCliBundlePlugins(appRoot: string): import('esbuild').Plugin[] {
-  // Plugin to resolve @/ alias to app root (works for @app modules)
+  // 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) {
-      // 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' }
+        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 }
+            }
+          }
         }
-        // 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 }
+        // 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) }
       })
     },
   }
@@ -296,14 +304,33 @@ function cacheIsValid(
     && dependenciesAreValid(appRoot, metadata.dependencies)
 }
 
+/**
+ * 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
+}
+
 /**
  * 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.
+ * The compiled file is written next to the source file with a .mjs extension unless
+ * `outFile` says otherwise.
  */
-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)))
+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)))
   const appTsconfig = path.join(appRoot, 'tsconfig.json')
   const metadataPath = cacheMetadataPath(jsPath)
 
@@ -322,6 +349,7 @@ async function compileAndImport(tsPath: string, allowRecovery: boolean = true):
   const needsCompile = !cacheIsValid(appRoot, jsPath, metadataPath, expectedInputHash)
 
   if (needsCompile) {
+    fs.mkdirSync(path.dirname(jsPath), { recursive: true })
     // Dynamically import esbuild only when needed
     const esbuild = await import('esbuild')
 
@@ -367,7 +395,7 @@ async function compileAndImport(tsPath: string, allowRecovery: boolean = true):
       throw error
     }
 
-    return compileAndImport(tsPath, false)
+    return compileAndImport(tsPath, { ...options, allowRecovery: false })
   }
 }
 
@@ -405,20 +433,7 @@ async function loadOptionalGeneratedModule(
   }
 }
 
-/**
- * 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
- */
-export async function loadBootstrapData(appRoot?: string): Promise<BootstrapData> {
+function resolveAppRootOrThrow(appRoot?: string): AppRoot {
   const resolved: AppRoot | null = appRoot
     ? {
         generatedDir: path.join(appRoot, '.mercato', 'generated'),
@@ -435,6 +450,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
+ */
+export async function loadBootstrapData(appRoot?: string): Promise<BootstrapData> {
+  const resolved = resolveAppRootOrThrow(appRoot)
+
   const { generatedDir } = resolved
 
   ensureMikroOrmV7GeneratedCacheCompatibility(resolved.appDir)
@@ -506,8 +583,10 @@ 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)
+  const data = await loadBootstrapData(resolved.appDir)
+  const 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/di/__tests__/container-app-di-absent.test.ts

@@ -84,9 +84,10 @@ jest.mock(
 )
 
 const mockWarn = jest.fn()
+const mockDebug = jest.fn()
 jest.mock('../../logger', () => ({
   createLogger: () => ({
-    debug: jest.fn(),
+    debug: (...args: unknown[]) => mockDebug(...args),
     info: jest.fn(),
     warn: (...args: unknown[]) => mockWarn(...args),
     error: jest.fn(),
@@ -107,6 +108,7 @@ describe('app-level DI override hook when @/di is absent', () => {
     registerAppDiRegistrar(null)
     registerDiRegistrars([])
     mockWarn.mockClear()
+    mockDebug.mockClear()
   })
 
   it('creates the container without warning', async () => {
@@ -117,6 +119,20 @@ describe('app-level DI override hook when @/di is absent', () => {
     expect(mockWarn).not.toHaveBeenCalled()
   })
 
+  // Worker and CLI processes create one request container per job against built package
+  // output, where the app's `@/` alias does not exist. Retrying the doomed import per
+  // container repeats a failed module resolution — and its log line — once per job.
+  it('stops retrying the unresolvable @/di import after the first container', async () => {
+    await createRequestContainer()
+    await createRequestContainer()
+    await createRequestContainer()
+
+    const unresolvableLogs = mockDebug.mock.calls.filter(
+      ([message]) => message === 'App-level DI override module (@/di) not resolvable; skipping',
+    )
+    expect(unresolvableLogs).toHaveLength(1)
+  })
+
   it('warns once when @/di fails because a nested app alias is missing', async () => {
     const nestedAliasError = Object.assign(new Error("Cannot find module '@/di/helpers'"), {
       code: 'MODULE_NOT_FOUND',

package/src/lib/di/container.ts

@@ -26,6 +26,11 @@ const GLOBAL_KEY = '__openMercatoDiRegistrars__'
 const APP_DI_REGISTRAR_KEY = '__openMercatoAppDiRegistrar__'
 const APP_DI_LOAD_WARNING_KEY = '__openMercatoAppDiLoadWarningEmitted__'
 const APP_DI_REGISTER_WARNING_KEY = '__openMercatoAppDiRegisterWarningEmitted__'
+// Set once the legacy `@/di` fallback proves the specifier is unresolvable in this process.
+// Worker/CLI processes run against built package output where the app's `@/` alias does not
+// exist, so retrying the import per request container only repeats a failed module resolution
+// (and its log line) once per job.
+const APP_DI_MODULE_UNRESOLVABLE_KEY = '__openMercatoAppDiModuleUnresolvable__'
 // Phase 5 — process-scoped bootstrap cache. The cache/event-bus/encryption
 // services bootstrap() creates are inherently process-scoped (they hold
 // state across requests). Caching them on globalThis after the first
@@ -120,6 +125,9 @@ export function registerDiRegistrars(registrars: DiRegistrar[]) {
   // Force re-bootstrap on HMR — module subscribers may have changed.
   ;(globalThis as any)[BOOTSTRAP_CACHE_KEY] = null
   ;(globalThis as any)[ENCRYPTION_ENABLED_KEY] = undefined
+  // An app that gains a src/di.ts mid-session reloads through here, so the negative
+  // resolution result must not outlive the reload.
+  ;(globalThis as Record<string, unknown>)[APP_DI_MODULE_UNRESOLVABLE_KEY] = undefined
 }
 
 export function getDiRegistrars(): DiRegistrar[] {
@@ -145,6 +153,15 @@ export function resetBootstrapCache(): void {
   ;(globalThis as any)[ENCRYPTION_ENABLED_KEY] = undefined
   ;(globalThis as Record<string, unknown>)[APP_DI_LOAD_WARNING_KEY] = undefined
   ;(globalThis as Record<string, unknown>)[APP_DI_REGISTER_WARNING_KEY] = undefined
+  ;(globalThis as Record<string, unknown>)[APP_DI_MODULE_UNRESOLVABLE_KEY] = undefined
+}
+
+function isAppDiModuleUnresolvable(): boolean {
+  return (globalThis as Record<string, unknown>)[APP_DI_MODULE_UNRESOLVABLE_KEY] === true
+}
+
+function markAppDiModuleUnresolvable(): void {
+  ;(globalThis as Record<string, unknown>)[APP_DI_MODULE_UNRESOLVABLE_KEY] = true
 }
 
 function isAppDiModuleNotFound(error: unknown): boolean {
@@ -267,7 +284,7 @@ export async function createRequestContainer(): Promise<AppContainer> {
     } catch (error) {
       logger.error('App-level DI registrar failed', { err: error })
     }
-  } else {
+  } else if (!isAppDiModuleUnresolvable()) {
     // Backward-compatible fallback for apps that have not adopted explicit wiring.
     try {
       // @ts-ignore - @/di only exists in app context, not in packages
@@ -286,6 +303,7 @@ export async function createRequestContainer(): Promise<AppContainer> {
       }
     } catch (err) {
       if (isAppDiModuleNotFound(err)) {
+        markAppDiModuleUnresolvable()
         logger.debug('App-level DI override module (@/di) not resolvable; skipping', { err })
       } else {
         warnAppDiFailureOnce(

package/src/lib/i18n/__tests__/server-unbootstrapped.test.ts

@@ -0,0 +1,29 @@
+import { invalidateDictionaryCache, loadDictionary, registerModules, resolveTranslations } from '../server'
+import type { Module } from '../../../modules/registry'
+
+const REGISTRY_GLOBAL_KEY = '__openMercatoModulesRegistry__'
+
+describe('loadDictionary without a bootstrapped module registry', () => {
+  beforeEach(() => {
+    delete (globalThis as Record<string, unknown>)[REGISTRY_GLOBAL_KEY]
+    invalidateDictionaryCache()
+  })
+
+  it('resolves the app dictionary instead of throwing a bootstrap error', async () => {
+    await expect(loadDictionary('en')).resolves.toEqual(expect.any(Object))
+  })
+
+  it('lets a route handler translate its response before bootstrap runs', async () => {
+    const { translate } = await resolveTranslations()
+
+    expect(translate('storage_s3.upload.errors.unsupported', 'Unsupported file type')).toBe('Unsupported file type')
+  })
+
+  it('picks up module translations once bootstrap registers them', async () => {
+    await loadDictionary('en')
+
+    registerModules([{ id: 'demo', translations: { en: { 'demo.hello': 'Hello' } } }] satisfies Module[])
+
+    await expect(loadDictionary('en')).resolves.toMatchObject({ 'demo.hello': 'Hello' })
+  })
+})

package/src/lib/i18n/server.ts

@@ -2,7 +2,7 @@ import { defaultLocale, locales, type Locale } from './config'
 import type { Dict } from './context'
 import { resolveForcedLocale, resolveLocaleFromAcceptLanguage } from './locale'
 import { createFallbackTranslator, createTranslator } from './translate'
-import { getModules } from '../modules/registry'
+import { tryGetModules } from '../modules/registry'
 import { loadAppDictionary } from './app-dictionaries'
 import { getCachedDictionary, setCachedDictionary } from './dictionary-cache'
 
@@ -61,7 +61,11 @@ export async function loadDictionary(locale: Locale): Promise<Dict> {
   // Load from registry instead of @/ import (works in standalone packages)
   const baseRaw = await loadAppDictionary(locale)
   const merged: Dict = { ...flattenDictionary(baseRaw) }
-  const modules = getModules()
+  // Route handlers translate their responses, so they resolve a dictionary even
+  // when they are exercised in isolation without a bootstrapped registry. The
+  // app dictionary alone is the right degraded answer there — `registerModules`
+  // invalidates this cache, so a later bootstrap still gets the merged result.
+  const modules = tryGetModules() ?? []
   for (const m of modules) {
     const dict = m.translations?.[locale]
     if (dict) Object.assign(merged, flattenDictionary(dict))

package/src/lib/logger/__tests__/logger.test.ts

@@ -3,7 +3,9 @@ import {
   createLogger,
   getLogLevel,
   isLevelEnabled,
+  registerLoggerExtension,
   resetLogLevelCache,
+  resetLoggerExtension,
   resetLoggerRegistry,
 } from '../index'
 import { resolveLevel, type LogLevel } from '../level'
@@ -65,6 +67,7 @@ function resetLoggerState(): void {
   resetLoggerRegistry()
   resetServerLoggerCache()
   resetLogPrettyCache()
+  resetLoggerExtension()
 }
 
 function forcePinoTransport(): void {
@@ -241,6 +244,80 @@ describe('structured logging facade', () => {
     })
   })
 
+  describe('process-wide logger extension', () => {
+    beforeEach(() => {
+      forcePinoTransport()
+    })
+
+    it('keeps one local line and observes one correlated record with child bindings', () => {
+      const fake = createFakePinoHarness()
+      mockPinoLoader(fake.factory)
+      const records: unknown[] = []
+      registerLoggerExtension({
+        enrich: () => ({ trace_id: 'trace-1', span_id: 'span-1' }),
+        emit: (record) => records.push(record),
+      })
+
+      createLogger('orders')
+        .child({ module: 'sales' })
+        .info('Order placed', { orderId: 'o-1' })
+
+      expect(fake.calls).toEqual([{
+        level: 'info',
+        args: [{
+          orderId: 'o-1',
+          trace_id: 'trace-1',
+          span_id: 'span-1',
+        }, 'Order placed'],
+      }])
+      expect(records).toHaveLength(1)
+      expect(records[0]).toMatchObject({
+        level: 'info',
+        namespace: 'orders',
+        message: 'Order placed',
+        fields: {
+          module: 'sales',
+          orderId: 'o-1',
+          trace_id: 'trace-1',
+          span_id: 'span-1',
+        },
+      })
+    })
+
+    it('applies the shared level gate to local and remote output', () => {
+      process.env.OM_LOG_LEVEL = 'warn'
+      resetLogLevelCache()
+      const fake = createFakePinoHarness()
+      mockPinoLoader(fake.factory)
+      const emit = jest.fn()
+      registerLoggerExtension({ emit })
+      const logger = createLogger('gated-extension')
+
+      logger.info('quiet')
+      logger.warn('visible')
+
+      expect(fake.calls.map((call) => call.level)).toEqual(['warn'])
+      expect(emit).toHaveBeenCalledTimes(1)
+      expect(emit.mock.calls[0][0]).toMatchObject({ level: 'warn', message: 'visible' })
+    })
+
+    it('isolates extension failures from application logging', () => {
+      const fake = createFakePinoHarness()
+      mockPinoLoader(fake.factory)
+      registerLoggerExtension({
+        enrich: () => {
+          throw new Error('context failed')
+        },
+        emit: () => {
+          throw new Error('sink failed')
+        },
+      })
+
+      expect(() => createLogger('resilient-extension').error('Still local')).not.toThrow()
+      expect(fake.calls).toEqual([{ level: 'error', args: [{}, 'Still local'] }])
+    })
+  })
+
   describe('isomorphism', () => {
     beforeEach(() => {
       forcePinoTransport()

package/src/lib/logger/extension.ts

@@ -0,0 +1,59 @@
+import type { LogLevel } from './level'
+
+export type LoggerExtensionRecord = {
+  level: LogLevel
+  namespace: string
+  message: string
+  fields: Record<string, unknown>
+  time: number
+}
+
+export type LoggerExtension = {
+  /**
+   * Add process-local context (for example trace/span ids) to both the local
+   * line and the optional remote sink.
+   */
+  enrich?(): Record<string, unknown> | undefined
+  /**
+   * Observe a record after the local transport writes it. Implementations must
+   * never throw into application code.
+   */
+  emit?(record: LoggerExtensionRecord): void
+}
+
+const GLOBAL_KEY = Symbol.for('@open-mercato/shared.loggerExtension')
+
+type LoggerExtensionStore = {
+  active?: LoggerExtension
+}
+
+function store(): LoggerExtensionStore {
+  const globalStore = globalThis as unknown as Record<symbol, LoggerExtensionStore | undefined>
+  let current = globalStore[GLOBAL_KEY]
+  if (!current) {
+    current = {}
+    globalStore[GLOBAL_KEY] = current
+  }
+  return current
+}
+
+/**
+ * Register the single process-wide logger extension. The returned disposer only
+ * clears the extension when it is still the active registration.
+ */
+export function registerLoggerExtension(extension: LoggerExtension): () => void {
+  store().active = extension
+  return () => {
+    const current = store()
+    if (current.active === extension) current.active = undefined
+  }
+}
+
+export function getLoggerExtension(): LoggerExtension | undefined {
+  return store().active
+}
+
+/** Test-only: clear the process-wide extension. */
+export function resetLoggerExtension(): void {
+  store().active = undefined
+}

package/src/lib/logger/index.ts

@@ -1,9 +1,17 @@
 import { selectTransport } from './transport'
+import { getLoggerExtension } from './extension'
+import { isLevelEnabled, type LogLevel } from './level'
 
 export type { LogLevel } from './level'
 export { getLogLevel, isLevelEnabled, resetLogLevelCache, OM_LOG_LEVEL_ENV } from './level'
 export { resetServerLoggerCache, OM_LOG_DESTINATION_ENV } from './transport.server'
 export { resetLogPrettyCache, OM_LOG_PRETTY_ENV } from './transport.pretty'
+export {
+  getLoggerExtension,
+  registerLoggerExtension,
+  resetLoggerExtension,
+} from './extension'
+export type { LoggerExtension, LoggerExtensionRecord } from './extension'
 
 export type LogBindings = Record<string, unknown>
 
@@ -18,11 +26,61 @@ export interface Logger {
 
 const loggerRegistry = new Map<string, Logger>()
 
+function createExtendedLogger(
+  namespace: string,
+  transport: Logger,
+  bindings: LogBindings = {},
+): Logger {
+  const emit = (
+    level: LogLevel,
+    msg: string,
+    fields?: LogBindings,
+  ): void => {
+    if (!isLevelEnabled(level)) return
+
+    const extension = getLoggerExtension()
+    let context: LogBindings = {}
+    try {
+      context = extension?.enrich?.() ?? {}
+    } catch {
+      // Observability must never alter application behavior.
+    }
+
+    const mergedFields = { ...fields, ...context }
+    transport[level](msg, mergedFields)
+
+    try {
+      extension?.emit?.({
+        level,
+        namespace,
+        message: msg,
+        fields: { ...bindings, ...mergedFields },
+        time: Date.now(),
+      })
+    } catch {
+      // Remote logging is best-effort; the local line has already been written.
+    }
+  }
+
+  return {
+    debug: (msg, fields) => emit('debug', msg, fields),
+    info: (msg, fields) => emit('info', msg, fields),
+    warn: (msg, fields) => emit('warn', msg, fields),
+    error: (msg, fields) => emit('error', msg, fields),
+    child: (childBindings) =>
+      createExtendedLogger(
+        namespace,
+        transport.child(childBindings),
+        { ...bindings, ...childBindings },
+      ),
+  }
+}
+
 /** Create (or reuse) a namespaced logger. `namespace` is attached as `name`. */
 export function createLogger(namespace: string): Logger {
   const existing = loggerRegistry.get(namespace)
   if (existing) return existing
-  const created = selectTransport(namespace)
+  const created = createExtendedLogger(namespace, selectTransport(namespace))
   loggerRegistry.set(namespace, created)
   return created
 }

package/src/lib/modules/registry.ts

@@ -69,3 +69,13 @@ export function getModules(): Module[] {
   }
   return modules
 }
+
+/**
+ * Non-throwing counterpart of `getModules()` for call sites that have a
+ * meaningful degraded behavior when bootstrap has not run — route unit tests
+ * exercise a single handler without `registerModules()`, and a hard throw there
+ * turns an unrelated assertion into a bootstrap error.
+ */
+export function tryGetModules(): Module[] | null {
+  return getGlobalModules()
+}

package/src/lib/telemetry/runtime.ts

@@ -0,0 +1,72 @@
+export type TelemetryTraceCarrier = Record<string, string>
+
+export type TelemetryRuntime = {
+  /**
+   * True only when the active SDK may safely use the process-global W3C
+   * propagator for cross-boundary extraction.
+   */
+  canUseGlobalTracePropagation(): boolean
+  captureTraceContext(): TelemetryTraceCarrier
+  continueTrace<T>(
+    carrier: TelemetryTraceCarrier | undefined,
+    name: string,
+    fn: () => T,
+    options?: { kind?: 'internal' | 'server' | 'client' | 'producer' | 'consumer' },
+  ): T
+  recordHttpDuration(method: string, route: string, status: number, startedAt: number): void
+  reportError(
+    error: unknown,
+    context?: {
+      module?: string
+      attributes?: Record<string, string | number | boolean | undefined>
+    },
+  ): void
+  shutdown(): Promise<void>
+}
+
+const GLOBAL_KEY = Symbol.for('@open-mercato/shared.telemetryRuntime')
+const ENABLED_BACKENDS = new Set(['console', 'signoz', 'newrelic', 'otlp'])
+
+type TelemetryRuntimeStore = {
+  active?: TelemetryRuntime
+}
+
+function store(): TelemetryRuntimeStore {
+  const globalStore = globalThis as unknown as Record<symbol, TelemetryRuntimeStore | undefined>
+  let current = globalStore[GLOBAL_KEY]
+  if (!current) {
+    current = {}
+    globalStore[GLOBAL_KEY] = current
+  }
+  return current
+}
+
+/**
+ * This check is intentionally owned by shared code so hosts can decide whether
+ * to dynamically import the telemetry package without evaluating that package.
+ */
+export function isTelemetryBackendEnabled(raw?: string): boolean {
+  const value = raw ?? (
+    typeof process === 'undefined'
+      ? undefined
+      : process.env.TELEMETRY_BACKEND
+  )
+  return ENABLED_BACKENDS.has((value ?? '').trim().toLowerCase())
+}
+
+export function registerTelemetryRuntime(runtime: TelemetryRuntime): () => void {
+  store().active = runtime
+  return () => {
+    const current = store()
+    if (current.active === runtime) current.active = undefined
+  }
+}
+
+export function getTelemetryRuntime(): TelemetryRuntime | undefined {
+  return store().active
+}
+
+/** Test-only: clear the process-wide telemetry bridge. */
+export function resetTelemetryRuntime(): void {
+  store().active = undefined
+}