@open-mercato/cli 0.8.1-develop.7296.1.2111d779db → 0.9.0

package/src/lib/generate-watch-structure.ts

@@ -4,6 +4,7 @@ import path from 'node:path'
 import {
   MODULE_CODE_EXTENSIONS,
   SCAN_CONFIGS,
+  resolveStandaloneSourceMirrorBase,
   scanModuleDir,
   stripModuleCodeExtension,
   type ModuleRoots,
@@ -66,6 +67,13 @@ function checksum(value: string): string {
   return crypto.createHash('md5').update(value).digest('hex')
 }
 
+function moduleRootIdentity(roots: ModuleRoots): string {
+  return JSON.stringify([
+    roots.pkgBase.replace(/\\/g, '/'),
+    roots.appBase.replace(/\\/g, '/'),
+  ])
+}
+
 function fileRecord(filePath: string, base: string, mode: 'content' | 'shape'): string | null {
   if (!fs.existsSync(filePath)) return null
   let stat: fs.Stats
@@ -86,6 +94,17 @@ function fileRecord(filePath: string, base: string, mode: 'content' | 'shape'):
   }
 }
 
+function addFileRecord(
+  records: string[],
+  prefix: string,
+  filePath: string,
+  base: string,
+  mode: 'content' | 'shape',
+): void {
+  const record = fileRecord(filePath, base, mode)
+  if (record) records.push(`${prefix}:${record}`)
+}
+
 function resolveCodeFile(base: string, relativePath: string): string | null {
   const stripped = stripModuleCodeExtension(relativePath)
   const candidates = MODULE_CODE_EXTENSIONS.map((extension) => `${stripped}${extension}`)
@@ -96,6 +115,16 @@ function resolveCodeFile(base: string, relativePath: string): string | null {
   return null
 }
 
+function resolveRuntimeCounterpart(
+  pkgBase: string,
+  sourceBase: string,
+  sourceFile: string,
+): string | null {
+  if (sourceBase === pkgBase) return null
+  const relativePath = path.relative(sourceBase, sourceFile).replace(/\\/g, '/')
+  return resolveCodeFile(pkgBase, relativePath)
+}
+
 function hasInlinePageMetadata(filePath: string): boolean {
   try {
     const source = fs.readFileSync(filePath, 'utf8')
@@ -107,48 +136,131 @@ function hasInlinePageMetadata(filePath: string): boolean {
 }
 
 function addConventionRecords(records: string[], roots: ModuleRoots): void {
+  const packageSourceBase = resolveStandaloneSourceMirrorBase(roots.pkgBase) ?? roots.pkgBase
   for (const base of [roots.pkgBase, roots.appBase]) {
     records.push(`module-root:${base}:${fs.existsSync(base) ? 'present' : 'missing'}`)
-    for (const relativePath of STRUCTURAL_CONVENTION_FILES) {
-      const filePath = resolveCodeFile(base, relativePath)
-      if (!filePath) {
-        records.push(`missing:${base}:${relativePath}`)
-        continue
+  }
+  if (packageSourceBase !== roots.pkgBase) {
+    records.push(
+      `module-root:${packageSourceBase}:${fs.existsSync(packageSourceBase) ? 'present' : 'missing'}`,
+    )
+  }
+
+  for (const relativePath of STRUCTURAL_CONVENTION_FILES) {
+    const appFile = resolveCodeFile(roots.appBase, relativePath)
+    if (appFile) {
+      addFileRecord(records, 'convention:app', appFile, roots.appBase, 'content')
+      continue
+    }
+
+    const sourceFile = resolveCodeFile(packageSourceBase, relativePath)
+    if (!sourceFile) {
+      const runtimeFile = packageSourceBase === roots.pkgBase
+        ? null
+        : resolveCodeFile(roots.pkgBase, relativePath)
+      if (runtimeFile) {
+        addFileRecord(records, 'convention:package-runtime', runtimeFile, roots.pkgBase, 'content')
+      } else {
+        records.push(`convention:missing:${relativePath}`)
       }
-      const record = fileRecord(filePath, base, 'content')
-      if (record) records.push(record)
+      continue
+    }
+
+    const packagePrefix = packageSourceBase === roots.pkgBase ? 'package' : 'package-source'
+    addFileRecord(records, `convention:${packagePrefix}`, sourceFile, packageSourceBase, 'content')
+    const runtimeFile = resolveRuntimeCounterpart(roots.pkgBase, packageSourceBase, sourceFile)
+    if (runtimeFile) {
+      addFileRecord(records, 'convention:package-runtime', runtimeFile, roots.pkgBase, 'content')
+    } else if (packageSourceBase !== roots.pkgBase) {
+      records.push(`convention:package-runtime:missing:${relativePath}`)
     }
   }
 }
 
 function addScannedRecords(records: string[], roots: ModuleRoots): void {
+  const packageSourceBase = resolveStandaloneSourceMirrorBase(roots.pkgBase) ?? roots.pkgBase
   for (const config of CONTENT_SENSITIVE_SCAN_CONFIGS) {
     for (const scanned of scanModuleDir(roots, config)) {
-      const base = scanned.fromApp ? roots.appBase : roots.pkgBase
+      const base = scanned.fromApp ? roots.appBase : packageSourceBase
       const filePath = path.join(base, ...config.folder.split('/'), ...scanned.relPath.split('/'))
-      const record = fileRecord(filePath, base, 'content')
-      if (record) records.push(`${config.folder}:${record}`)
+      let sourceOrigin = 'app'
+      if (!scanned.fromApp) {
+        sourceOrigin = packageSourceBase === roots.pkgBase ? 'package' : 'package-source'
+      }
+      addFileRecord(records, `${config.folder}:${sourceOrigin}`, filePath, base, 'content')
+
+      if (!scanned.fromApp && packageSourceBase !== roots.pkgBase) {
+        const runtimeFile = resolveRuntimeCounterpart(roots.pkgBase, packageSourceBase, filePath)
+        if (runtimeFile) {
+          addFileRecord(
+            records,
+            `${config.folder}:package-runtime`,
+            runtimeFile,
+            roots.pkgBase,
+            'content',
+          )
+        } else {
+          records.push(`${config.folder}:package-runtime:missing:${scanned.relPath}`)
+        }
+      }
     }
   }
 
   for (const config of ROUTE_SHAPE_SCAN_CONFIGS) {
     for (const scanned of scanModuleDir(roots, config)) {
-      const base = scanned.fromApp ? roots.appBase : roots.pkgBase
+      const base = scanned.fromApp ? roots.appBase : packageSourceBase
       const folderPath = path.join(base, ...config.folder.split('/'))
       const filePath = path.join(folderPath, ...scanned.relPath.split('/'))
-      const pageRecord = fileRecord(filePath, base, hasInlinePageMetadata(filePath) ? 'content' : 'shape')
-      if (pageRecord) records.push(`${config.folder}:${pageRecord}`)
+      let sourceOrigin = 'app'
+      if (!scanned.fromApp) {
+        sourceOrigin = packageSourceBase === roots.pkgBase ? 'package' : 'package-source'
+      }
+      addFileRecord(
+        records,
+        `${config.folder}:${sourceOrigin}`,
+        filePath,
+        base,
+        hasInlinePageMetadata(filePath) ? 'content' : 'shape',
+      )
+
+      let runtimeFile: string | null = null
+      if (!scanned.fromApp && packageSourceBase !== roots.pkgBase) {
+        runtimeFile = resolveRuntimeCounterpart(roots.pkgBase, packageSourceBase, filePath)
+        if (runtimeFile) {
+          addFileRecord(
+            records,
+            `${config.folder}:package-runtime`,
+            runtimeFile,
+            roots.pkgBase,
+            hasInlinePageMetadata(runtimeFile) ? 'content' : 'shape',
+          )
+        } else {
+          records.push(`${config.folder}:package-runtime:missing:${scanned.relPath}`)
+        }
+      }
 
-      const dir = path.dirname(filePath)
       const stem = stripModuleCodeExtension(path.basename(filePath))
       const metaCandidates = stem === 'page'
         ? ['page.meta', 'meta']
         : [`${stem}.meta`, 'meta']
       for (const candidate of metaCandidates) {
-        const metaPath = resolveCodeFile(dir, candidate)
+        const metaPath = resolveCodeFile(path.dirname(filePath), candidate)
         if (!metaPath) continue
-        const record = fileRecord(metaPath, base, 'content')
-        if (record) records.push(`${config.folder}:meta:${record}`)
+        addFileRecord(records, `${config.folder}:meta:${sourceOrigin}`, metaPath, base, 'content')
+      }
+
+      if (runtimeFile) {
+        for (const candidate of metaCandidates) {
+          const runtimeMetaPath = resolveCodeFile(path.dirname(runtimeFile), candidate)
+          if (!runtimeMetaPath) continue
+          addFileRecord(
+            records,
+            `${config.folder}:meta:package-runtime`,
+            runtimeMetaPath,
+            roots.pkgBase,
+            'content',
+          )
+        }
       }
     }
   }
@@ -163,8 +275,11 @@ export function calculateGenerateWatchStructureChecksum(options: {
   records.push(modulesRecord ?? `missing:${options.modulesFile}`)
 
   for (const roots of options.moduleRoots) {
-    addConventionRecords(records, roots)
-    addScannedRecords(records, roots)
+    const moduleRecords: string[] = []
+    addConventionRecords(moduleRecords, roots)
+    addScannedRecords(moduleRecords, roots)
+    const rootIdentity = moduleRootIdentity(roots)
+    records.push(...moduleRecords.map((record) => `${rootIdentity}:${record}`))
   }
 
   return checksum(records.sort((a, b) => a.localeCompare(b)).join('\n'))

package/src/lib/generators/__tests__/module-facts.customers.fixture.test.ts

@@ -18,7 +18,11 @@ describe('module-facts customers fixture (T1 anti-drift guard)', () => {
 
   it('locks the source-derived customers entity surface in colon-form ids', () => {
     expect(facts.module).toBe('customers')
-    expect(facts.entities).toHaveLength(25)
+    // 26 since the email conversation-share feature added
+    // `CustomerEmailConversationShare` (the read grant backing owner-controlled
+    // conversation sharing). Bump deliberately: this guard exists to make an
+    // entity-surface change visible, not to be silenced.
+    expect(facts.entities).toHaveLength(26)
     expect(facts.entities.every((entity) => entity.id.startsWith('customers:'))).toBe(true)
     expect(facts.entities[0]).toMatchObject({ id: 'customers:customer_entity' })
     for (const entity of facts.entities) {
@@ -31,8 +35,15 @@ describe('module-facts customers fixture (T1 anti-drift guard)', () => {
     // 50 since #5114 added `customers.person.company_assignment.detached` — the profile-only
     // sibling of the person_company_link CRUD events. Bump deliberately: this guard exists to
     // make an event-surface change visible, not to be silenced.
-    expect(facts.events).toHaveLength(50)
-    expect(facts.aclFeatures).toHaveLength(21)
+    //
+    // 51 since the email conversation-share feature added
+    // `customers.email.conversation_visibility_changed` (audit trail for the
+    // owner-controlled share/un-share act), and 22 ACL features since it added
+    // `customers.email.share_conversation` (owner-scoped: it only ever lets you
+    // share your OWN conversation, so the existing `customers.*` admin wildcard
+    // grants no escalation).
+    expect(facts.events).toHaveLength(51)
+    expect(facts.aclFeatures).toHaveLength(22)
     expect(facts.searchEntities).toEqual([
       'customers:customer_person_profile',
       'customers:customer_company_profile',

package/src/lib/generators/__tests__/module-package-sources.test.ts

@@ -86,7 +86,7 @@ describe('generateModulePackageSources', () => {
     await generateModulePackageSources({ resolver, quiet: true })
     const outputBefore = fs.readFileSync(outFile, 'utf8')
     const checksumBefore = readChecksumRecord(checksumFile)
-    const pinnedTime = new Date(Date.now() - 60_000)
+    const pinnedTime = new Date('2020-01-01T00:00:00.000Z')
     fs.utimesSync(outFile, pinnedTime, pinnedTime)
     fs.utimesSync(checksumFile, pinnedTime, pinnedTime)
 
@@ -121,7 +121,7 @@ describe('generateModulePackageSources', () => {
     await generateModulePackageSources({ resolver: initialResolver, quiet: true })
     const outputBefore = fs.readFileSync(outFile, 'utf8')
     const initialStructure = readChecksumRecord(checksumFile)?.structure
-    const pinnedTime = new Date(Date.now() - 60_000)
+    const pinnedTime = new Date('2020-01-01T00:00:00.000Z')
     fs.utimesSync(outFile, pinnedTime, pinnedTime)
 
     await generateModulePackageSources({ resolver: alternateResolver, quiet: true })

package/src/lib/generators/__tests__/registry-variant-parity.test.ts

@@ -263,6 +263,22 @@ describe('module registry variant parity', () => {
     expect(carriesRuntime).toEqual(registryFiles.map((fileName) => [fileName, true, false]))
   })
 
+  // The IIFE `namespaceFallback` emits narrows `unknown` to `{}`. That satisfies `setup`, whose
+  // every member is optional, but `ModuleRuntime.start` is required — so without a cast the three
+  // namespace-lookup registries fail `tsc` the moment any module ships a runtime.ts. `generate`
+  // stays green either way, which is what let this ship.
+  it('casts the emitted runtime, so its required `start` does not break typecheck', () => {
+    const namespaceLookupRegistries = [
+      'modules.app.generated.ts',
+      'modules.bootstrap.generated.ts',
+      'modules.cli.generated.ts',
+    ]
+
+    for (const fileName of namespaceLookupRegistries) {
+      expect(readGenerated(fileName)).toContain("as Module['runtime']")
+    }
+  })
+
   describe('known, intentional divergences', () => {
     it('only the main variant carries eager api handlers and the cli entry point', () => {
       expect(mainVariant.get('orders')!.has('apis')).toBe(true)

package/src/lib/generators/__tests__/web-research-adapters.test.ts

@@ -0,0 +1,141 @@
+import { spawnSync } from 'node:child_process'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import ts from 'typescript-js'
+import type { PackageResolver } from '../../resolver'
+import { generateWebResearchAdapters } from '../web-research-adapters'
+
+let tmpRoot: string
+let appDir: string
+let outputDir: string
+
+function createMockResolver(): PackageResolver {
+  return {
+    getAppDir: () => appDir,
+    getOutputDir: () => outputDir,
+  } as unknown as PackageResolver
+}
+
+function writeAdapterPackage(
+  packageDir: string,
+  packageName: string,
+  adapterId: string,
+  source = `export const id = '${adapterId}'\n`,
+): void {
+  fs.mkdirSync(packageDir, { recursive: true })
+  fs.writeFileSync(
+    path.join(packageDir, 'package.json'),
+    JSON.stringify({
+      name: packageName,
+      type: 'module',
+      exports: './index.js',
+      openMercato: { webResearchAdapter: { id: adapterId } },
+    }),
+  )
+  fs.writeFileSync(path.join(packageDir, 'index.js'), source)
+}
+
+function writeWorkspaceOnlyAdapter(directoryName: string, packageName: string, adapterId: string): void {
+  writeAdapterPackage(path.join(tmpRoot, 'packages', directoryName), packageName, adapterId)
+}
+
+function writeInstalledAdapter(packageName: string, adapterId: string, source?: string): void {
+  writeAdapterPackage(path.join(tmpRoot, 'node_modules', ...packageName.split('/')), packageName, adapterId, source)
+}
+
+async function generate(): Promise<string> {
+  await generateWebResearchAdapters({ resolver: createMockResolver(), quiet: true })
+  return fs.readFileSync(path.join(outputDir, 'web-research-adapters.generated.ts'), 'utf8')
+}
+
+function runGeneratedRegistry(content: string): { status: number | null; stdout: string; stderr: string } {
+  const compiled = ts.transpileModule(content, {
+    compilerOptions: { module: ts.ModuleKind.ESNext, target: ts.ScriptTarget.ES2022 },
+  }).outputText
+  const registryFile = path.join(outputDir, 'web-research-adapters.generated.mjs')
+  fs.writeFileSync(registryFile, compiled)
+  const script = [
+    `const { webResearchAdapterEntries } = await import(${JSON.stringify(registryFile)})`,
+    'console.log(JSON.stringify(webResearchAdapterEntries.map((entry) => [entry.packageName, entry.module.id])))',
+  ].join('\n')
+  const result = spawnSync(process.execPath, ['--input-type=module', '-e', script], {
+    cwd: appDir,
+    encoding: 'utf8',
+  })
+  return { status: result.status, stdout: result.stdout.trim(), stderr: result.stderr }
+}
+
+beforeEach(() => {
+  tmpRoot = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'web-research-adapters-test-')))
+  appDir = path.join(tmpRoot, 'apps', 'mercato')
+  outputDir = path.join(appDir, '.mercato', 'generated')
+  fs.mkdirSync(outputDir, { recursive: true })
+})
+
+afterEach(() => {
+  fs.rmSync(tmpRoot, { recursive: true, force: true })
+})
+
+describe('generateWebResearchAdapters', () => {
+  it('emits an empty registry when no adapter package is discovered', async () => {
+    const content = await generate()
+
+    expect(content).toContain('export const webResearchAdapterEntries: AdapterRegistryEntry[] = []')
+    expect(content).not.toMatch(/import\(/)
+  })
+
+  it('imports every discovered adapter with a literal specifier and no static import', async () => {
+    writeInstalledAdapter('@acme/web-research-installed', 'installed')
+    writeWorkspaceOnlyAdapter('web-research-workspace-only', '@acme/web-research-workspace-only', 'workspace-only')
+
+    const content = await generate()
+
+    expect(content).toContain("import('@acme/web-research-installed')")
+    expect(content).toContain("import('@acme/web-research-workspace-only')")
+    expect(content).not.toMatch(/^import \* as /m)
+  })
+
+  it('loads installed adapters and skips workspace packages the app cannot resolve', async () => {
+    writeInstalledAdapter('@acme/web-research-installed', 'installed')
+    writeWorkspaceOnlyAdapter('web-research-workspace-only', '@acme/web-research-workspace-only', 'workspace-only')
+
+    const result = runGeneratedRegistry(await generate())
+
+    expect(result.stderr).toBe('')
+    expect(result.status).toBe(0)
+    expect(JSON.parse(result.stdout)).toEqual([['@acme/web-research-installed', 'installed']])
+  })
+
+  it('still surfaces an installed adapter that fails while loading', async () => {
+    writeInstalledAdapter('@acme/web-research-broken', 'broken', "throw new Error('adapter exploded')\n")
+
+    const result = runGeneratedRegistry(await generate())
+
+    expect(result.status).not.toBe(0)
+    expect(result.stderr).toContain('adapter exploded')
+  })
+
+  it('still surfaces an installed adapter whose own dependency is missing', async () => {
+    writeInstalledAdapter(
+      '@acme/web-research-needs-dep',
+      'needs-dep',
+      "import '@acme/missing-adapter-dependency'\nexport const id = 'needs-dep'\n",
+    )
+
+    const result = runGeneratedRegistry(await generate())
+
+    expect(result.status).not.toBe(0)
+    expect(result.stderr).toContain('@acme/missing-adapter-dependency')
+  })
+
+  it('still surfaces an installed adapter whose entry file is missing', async () => {
+    writeInstalledAdapter('@acme/web-research-unbuilt', 'unbuilt')
+    fs.rmSync(path.join(tmpRoot, 'node_modules', '@acme', 'web-research-unbuilt', 'index.js'))
+
+    const result = runGeneratedRegistry(await generate())
+
+    expect(result.status).not.toBe(0)
+    expect(result.stderr).toMatch(/Cannot find module/)
+  })
+})

package/src/lib/generators/module-registry.ts

@@ -4624,6 +4624,7 @@ async function generateModuleRegistryAppFromDiscovery(options: ModuleRegistryRen
           importName: moduleRuntimeImportName,
           members: ['default', 'runtime'],
           fallback: identifier('undefined'),
+          castType: "Module['runtime']",
         }),
       })
     }
@@ -5035,6 +5036,7 @@ async function generateModuleRegistryCliFromDiscovery(options: ModuleRegistryRen
           importName: moduleRuntimeImportName,
           members: ['default', 'runtime'],
           fallback: identifier('undefined'),
+          castType: "Module['runtime']",
         }),
       })
     }

package/src/lib/generators/web-research-adapters.ts

@@ -67,14 +67,48 @@ function scanDirectory(root: string, results: Map<string, DiscoveredAdapter>): v
   }
 }
 
-function identifierFor(index: number): string {
-  return `adapter${index}`
+function renderEntries(adapters: readonly DiscoveredAdapter[]): string {
+  if (adapters.length === 0) return 'export const webResearchAdapterEntries: AdapterRegistryEntry[] = []\n'
+  const loaders = adapters
+    .map(
+      (adapter) =>
+        `  loadAdapterEntry('${adapter.packageName}', () => import('${adapter.packageName}')),`,
+    )
+    .join('\n')
+  return `const MISSING_MODULE_CODES = new Set(['ERR_MODULE_NOT_FOUND', 'MODULE_NOT_FOUND'])
+
+async function loadAdapterEntry(
+  packageName: string,
+  load: () => Promise<unknown>,
+): Promise<AdapterRegistryEntry | null> {
+  try {
+    return { packageName, module: await load() }
+  } catch (error) {
+    const { code, message } = (error ?? {}) as { code?: unknown; message?: unknown }
+    const isMissingCode = typeof code === 'string' && MISSING_MODULE_CODES.has(code)
+    const namesThisPackage = typeof message === 'string' && message.includes(\`'\${packageName}'\`)
+    if (isMissingCode && namesThisPackage) return null
+    throw error
+  }
+}
+
+const loadedEntries = await Promise.all([
+${loaders}
+])
+
+export const webResearchAdapterEntries: AdapterRegistryEntry[] = loadedEntries.filter(
+  (entry): entry is AdapterRegistryEntry => entry !== null,
+)
+`
 }
 
 /**
- * Emits the statically imported adapter registry. Discovery happens here, at
- * build time, because a bundler cannot follow `import()` with a runtime-computed
- * specifier — a dynamic registry would resolve to nothing under Turbopack.
+ * Emits the adapter registry. Discovery happens here, at build time, because a
+ * bundler cannot follow `import()` with a runtime-computed specifier — a dynamic
+ * registry would resolve to nothing under Turbopack. Each adapter is imported
+ * with a literal specifier and a package that is not installed where the
+ * registry runs is skipped: discovery scans the whole workspace, but a process
+ * such as a worker in a production image only has the app's own dependencies.
  */
 export async function generateWebResearchAdapters(
   options: WebResearchAdaptersOptions,
@@ -99,26 +133,13 @@ export async function generateWebResearchAdapters(
     left.packageName.localeCompare(right.packageName),
   )
 
-  const imports = adapters
-    .map((adapter, index) => `import * as ${identifierFor(index)} from '${adapter.packageName}'`)
-    .join('\n')
-  const entries = adapters
-    .map(
-      (adapter, index) =>
-        `  { packageName: '${adapter.packageName}', module: ${identifierFor(index)} },`,
-    )
-    .join('\n')
-
   const content = `// AUTO-GENERATED — do not edit by hand.
 // Source: packages declaring \`${MANIFEST_NAMESPACE}.${ADAPTER_MANIFEST_KEY}\` in package.json.
 // Regenerate with: yarn generate
+// Adapter packages that are not installed where this registry runs are skipped.
 import type { AdapterRegistryEntry } from '@open-mercato/web-research'
-${imports}
 
-export const webResearchAdapterEntries: AdapterRegistryEntry[] = [
-${entries}
-]
-`
+${renderEntries(adapters)}`
 
   writeGeneratedFile({
     outFile,

package/src/lib/telemetry-init.ts

@@ -102,17 +102,40 @@ export async function register(): Promise<void> {
   // Initialize telemetry (no-op unless TELEMETRY_BACKEND is set). OTEL's NodeSDK
   // is Node-only and incompatible with the edge runtime, so the telemetry
   // bootstrap — which can pull in the SDK — is imported only on the Node.js
-  // runtime. The helper owns init + graceful degrade + shutdown flush.
+  // runtime. The helper owns init + graceful degrade + shutdown flush; a
+  // deliberate configuration failure bubbles here so the host exits loudly.
   if (
     process.env.NEXT_RUNTIME === 'nodejs'
     && isTelemetryBackendEnabled()
   ) {
     const { registerTelemetryForNextjs } = await import('@open-mercato/telemetry/nextjs')
-    await registerTelemetryForNextjs()
+    try {
+      await registerTelemetryForNextjs()
+    } catch (err) {
+      const nodeProcess = process
+      nodeProcess.stderr.write(\`\${err instanceof Error ? err.message : String(err)}\\n\`)
+      nodeProcess.exit(1)
+    }
   }
 }
 `
 
+const MULTILINE_TELEMETRY_GUARD = `  if (
+    process.env.NEXT_RUNTIME === 'nodejs'
+    && isTelemetryBackendEnabled()
+  ) {`
+const INLINE_TELEMETRY_GUARD = `  if (process.env.NEXT_RUNTIME === 'nodejs' && isTelemetryBackendEnabled()) {`
+const LEGACY_NODE_TELEMETRY_GUARD = `  if (process.env.NEXT_RUNTIME === 'nodejs') {`
+const TELEMETRY_DYNAMIC_IMPORT = `    const { registerTelemetryForNextjs } = await import('@open-mercato/telemetry/nextjs')`
+const BARE_TELEMETRY_REGISTRATION = `    await registerTelemetryForNextjs()`
+const GUARDED_TELEMETRY_REGISTRATION = `    try {
+      await registerTelemetryForNextjs()
+    } catch (err) {
+      const nodeProcess = process
+      nodeProcess.stderr.write(\`\${err instanceof Error ? err.message : String(err)}\\n\`)
+      nodeProcess.exit(1)
+    }`
+
 const DISPATCHER_SNIPPET = `  // add near the other imports:
   import { getTelemetryRuntime } from '@open-mercato/shared/lib/telemetry/runtime'
 
@@ -331,17 +354,45 @@ function patchInstrumentation(appDir: string, options: TelemetryInitOptions): St
   }
   const content = readFileSync(path, 'utf8')
   if (content.includes('registerTelemetryForNextjs')) {
-    if (content.includes('isTelemetryBackendEnabled')) {
+    const guardedBootstraps = [MULTILINE_TELEMETRY_GUARD, INLINE_TELEMETRY_GUARD]
+    const safeBootstrap = guardedBootstraps
+      .map((guard) => `${guard}\n${TELEMETRY_DYNAMIC_IMPORT}\n${GUARDED_TELEMETRY_REGISTRATION}`)
+      .find((bootstrap) => content.includes(bootstrap))
+    if (safeBootstrap) {
       return { file, status: 'skipped', detail: 'telemetry already wired' }
     }
-    const migrated =
-      `import { isTelemetryBackendEnabled } from '@open-mercato/shared/lib/telemetry/runtime'\n` +
-      content.replace(
-        `if (process.env.NEXT_RUNTIME === 'nodejs') {`,
-        `if (process.env.NEXT_RUNTIME === 'nodejs' && isTelemetryBackendEnabled()) {`,
+    const guardedLegacyBootstrap = guardedBootstraps
+      .map((guard) => `${guard}\n${TELEMETRY_DYNAMIC_IMPORT}\n${BARE_TELEMETRY_REGISTRATION}`)
+      .find((bootstrap) => content.includes(bootstrap))
+    if (guardedLegacyBootstrap) {
+      const migrated = content.replace(
+        guardedLegacyBootstrap,
+        guardedLegacyBootstrap.replace(BARE_TELEMETRY_REGISTRATION, GUARDED_TELEMETRY_REGISTRATION),
       )
-    if (!options.dryRun) writeFileSync(path, migrated)
-    return { file, status: 'patched', detail: 'added the explicit backend import guard' }
+      if (!options.dryRun) writeFileSync(path, migrated)
+      return { file, status: 'patched', detail: 'wrapped OTLP dependency failures with host termination' }
+    }
+    const nodeOnlyLegacyBootstrap = `${LEGACY_NODE_TELEMETRY_GUARD}\n${TELEMETRY_DYNAMIC_IMPORT}\n${BARE_TELEMETRY_REGISTRATION}`
+    if (content.includes(nodeOnlyLegacyBootstrap)) {
+      const guardedBootstrap = nodeOnlyLegacyBootstrap
+        .replace(LEGACY_NODE_TELEMETRY_GUARD, INLINE_TELEMETRY_GUARD)
+        .replace(BARE_TELEMETRY_REGISTRATION, GUARDED_TELEMETRY_REGISTRATION)
+      const importLine = `import { isTelemetryBackendEnabled } from '@open-mercato/shared/lib/telemetry/runtime'\n`
+      const withBootstrap = content.replace(nodeOnlyLegacyBootstrap, guardedBootstrap)
+      const migrated = withBootstrap.includes(importLine) ? withBootstrap : importLine + withBootstrap
+      if (!options.dryRun) writeFileSync(path, migrated)
+      return {
+        file,
+        status: 'patched',
+        detail: 'added the explicit backend guard and wrapped OTLP dependency failures with host termination',
+      }
+    }
+    return {
+      file,
+      status: 'manual',
+      detail: 'existing telemetry bootstrap needs the canonical Node guard and fail-closed host wrapper',
+      manualSnippet: INSTRUMENTATION_TS,
+    }
   }
   const anchor = content.match(/export\s+async\s+function\s+register\s*\([^)]*\)\s*:\s*Promise<void>\s*\{/)
   if (!anchor || anchor.index === undefined) {
@@ -357,7 +408,13 @@ function patchInstrumentation(appDir: string, options: TelemetryInitOptions): St
     `\n  // Initialize telemetry (no-op unless TELEMETRY_BACKEND is set); Node-only.` +
     `\n  if (process.env.NEXT_RUNTIME === 'nodejs' && isTelemetryBackendEnabled()) {` +
     `\n    const { registerTelemetryForNextjs } = await import('@open-mercato/telemetry/nextjs')` +
-    `\n    await registerTelemetryForNextjs()` +
+    `\n    try {` +
+    `\n      await registerTelemetryForNextjs()` +
+    `\n    } catch (err) {` +
+    `\n      const nodeProcess = process` +
+    `\n      nodeProcess.stderr.write(\`\${err instanceof Error ? err.message : String(err)}\\n\`)` +
+    `\n      nodeProcess.exit(1)` +
+    `\n    }` +
     `\n  }`
   const importLine = `import { isTelemetryBackendEnabled } from '@open-mercato/shared/lib/telemetry/runtime'\n`
   const withImport = content.includes('isTelemetryBackendEnabled')