@open-mercato/shared 0.6.7-develop.6706.1.b3a4c759bb → 0.6.7-develop.6726.1.983ae8a07e

package/src/lib/bootstrap/__tests__/clientOnlyModules.test.ts

@@ -0,0 +1,189 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+import {
+  createClientOnlyStubPlugin,
+  encodeJsStringLiteral,
+  isClientOnlyModulePath,
+  renderClientOnlyModuleStub,
+} from '../clientOnlyModules'
+import { createCliBundlePlugins } from '../dynamicLoader'
+
+const CHART_IMPORT = '@open-mercato/ui/backend/charts'
+
+function createServerHelperFixture(tempDir: string): string {
+  const moduleDir = path.join(tempDir, 'src', 'modules', 'demo')
+  fs.mkdirSync(moduleDir, { recursive: true })
+
+  fs.writeFileSync(
+    path.join(moduleDir, 'http.client.ts'),
+    ['export const httpClient = { fetchOrders: async () => [] }', ''].join('\n'),
+  )
+
+  const entry = path.join(tempDir, 'modules.cli.generated.ts')
+  fs.writeFileSync(
+    entry,
+    [
+      "import { httpClient } from './src/modules/demo/http.client'",
+      'export const modules = [{',
+      "  id: 'demo',",
+      '  workers: [{ handler: () => httpClient.fetchOrders() }],',
+      '}]',
+      '',
+    ].join('\n'),
+  )
+
+  return entry
+}
+
+function createAppModuleFixture(tempDir: string): string {
+  const widgetDir = path.join(tempDir, 'src', 'modules', 'demo', 'widgets', 'dashboard', 'sales')
+  fs.mkdirSync(widgetDir, { recursive: true })
+
+  fs.writeFileSync(
+    path.join(widgetDir, 'widget.client.tsx'),
+    [
+      '"use client"',
+      `import { BarChart } from '${CHART_IMPORT}'`,
+      'export default function DemoWidget() { return BarChart }',
+      '',
+    ].join('\n'),
+  )
+
+  const entry = path.join(tempDir, 'modules.cli.generated.ts')
+  fs.writeFileSync(
+    entry,
+    [
+      'export const modules = [{',
+      "  id: 'demo',",
+      '  dashboardWidgets: [{',
+      "    moduleId: 'demo',",
+      "    key: 'demo:sales:widget',",
+      "    loader: () => import('./src/modules/demo/widgets/dashboard/sales/widget.client').then((mod) => mod.default ?? mod),",
+      '  }],',
+      '}]',
+      '',
+    ].join('\n'),
+  )
+
+  return entry
+}
+
+async function bundle(entry: string, outfile: string, withStubPlugin: boolean): Promise<string> {
+  const esbuild = await import('esbuild')
+  await esbuild.build({
+    entryPoints: [entry],
+    outfile,
+    bundle: true,
+    format: 'esm',
+    platform: 'node',
+    target: 'node18',
+    external: ['@open-mercato/*'],
+    plugins: withStubPlugin ? [createClientOnlyStubPlugin()] : [],
+  })
+  return fs.readFileSync(outfile, 'utf8')
+}
+
+describe('isClientOnlyModulePath', () => {
+  it('matches local client modules with and without an extension', () => {
+    expect(isClientOnlyModulePath('./widget.client')).toBe(true)
+    expect(isClientOnlyModulePath('./widget.client.tsx')).toBe(true)
+    expect(isClientOnlyModulePath('../dashboard/sales/widget.client.ts')).toBe(true)
+    expect(isClientOnlyModulePath('@/modules/demo/widgets/dashboard/sales/widget.client')).toBe(true)
+    expect(isClientOnlyModulePath('./notifications.client.ts')).toBe(true)
+  })
+
+  it('leaves bare package specifiers to the external-import plugin', () => {
+    expect(isClientOnlyModulePath('@open-mercato/ui/backend/charts')).toBe(false)
+    expect(isClientOnlyModulePath('@open-mercato/core/modules/demo/widget.client')).toBe(false)
+    expect(isClientOnlyModulePath('react')).toBe(false)
+  })
+
+  it('does not match server modules that merely mention client', () => {
+    expect(isClientOnlyModulePath('./widget.ts')).toBe(false)
+    expect(isClientOnlyModulePath('./clientFactory.ts')).toBe(false)
+    expect(isClientOnlyModulePath('./client/index.ts')).toBe(false)
+  })
+
+  it('does not match the generated notification-renderer registry', () => {
+    expect(isClientOnlyModulePath('@/.mercato/generated/notifications.client.generated')).toBe(false)
+    expect(isClientOnlyModulePath('@/.mercato/generated/notifications.client.generated.ts')).toBe(false)
+  })
+})
+
+describe('encodeJsStringLiteral', () => {
+  it('escapes quotes and backslashes so the literal cannot be terminated early', () => {
+    expect(encodeJsStringLiteral('say "hi"')).toBe('"say \\"hi\\""')
+    expect(encodeJsStringLiteral('a\\b')).toBe('"a\\\\b"')
+  })
+
+  it('escapes every character outside printable ASCII, including the separators JSON leaves raw', () => {
+    expect(encodeJsStringLiteral('a\u2028b')).toBe('"a\\u2028b"')
+    expect(encodeJsStringLiteral('a\u2029b')).toBe('"a\\u2029b"')
+    expect(encodeJsStringLiteral('a\nb')).toBe('"a\\u000ab"')
+  })
+
+  it('leaves no unescaped delimiter that could break out of the literal', () => {
+    const hostile = './widget.client"); globalThis.pwned = true; ("'
+    const encoded = encodeJsStringLiteral(hostile)
+
+    expect(encoded.startsWith('"')).toBe(true)
+    expect(encoded.endsWith('"')).toBe(true)
+    expect(encoded.slice(1, -1)).not.toMatch(/(^|[^\\])"/)
+    expect(JSON.parse(encoded)).toBe(hostile)
+  })
+})
+
+describe('renderClientOnlyModuleStub', () => {
+  it('exports a default that throws when the browser component is actually used', () => {
+    const stub = renderClientOnlyModuleStub('./widget.client')
+    expect(stub).toContain('export default clientOnlyModuleUnavailable')
+    expect(stub).toContain('./widget.client')
+  })
+})
+
+describe('createCliBundlePlugins', () => {
+  it('registers the client-only stub ahead of the alias and external plugins', () => {
+    expect(createCliBundlePlugins('/tmp/app-root').map((plugin) => plugin.name)).toEqual([
+      'client-only-stub',
+      'alias-resolver',
+      'external-non-json',
+    ])
+  })
+})
+
+describe('CLI bundle graph', () => {
+  let tempDir: string
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'open-mercato-client-only-'))
+  })
+
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true })
+  })
+
+  it('keeps browser-only widget imports out of the CLI bundle', async () => {
+    const entry = createAppModuleFixture(tempDir)
+    const output = await bundle(entry, path.join(tempDir, 'stubbed.mjs'), true)
+
+    expect(output).not.toContain(CHART_IMPORT)
+    expect(output).toContain('clientOnlyModuleUnavailable')
+  })
+
+  it('without the plugin the same fixture hoists the browser-only import (regression guard)', async () => {
+    const entry = createAppModuleFixture(tempDir)
+    const output = await bundle(entry, path.join(tempDir, 'plain.mjs'), false)
+
+    expect(output).toContain(CHART_IMPORT)
+  })
+
+  it('leaves statically imported server helpers alone even when they are named *.client', async () => {
+    const entry = createServerHelperFixture(tempDir)
+    const output = await bundle(entry, path.join(tempDir, 'server-helper.mjs'), true)
+
+    expect(output).toContain('fetchOrders')
+    expect(output).not.toContain('clientOnlyModuleUnavailable')
+  })
+})

package/src/lib/bootstrap/clientOnlyModules.ts

@@ -0,0 +1,85 @@
+/**
+ * Client-only modules (`*.client.tsx`) hold browser components and must never enter the
+ * CLI bundle graph. App modules are bundled from source by `compileAndImport`, and esbuild
+ * inlines dynamic imports into the single output file, hoisting the client file's static
+ * imports to the top of the bundle. A wrapper such as `@open-mercato/ui/backend/charts`
+ * would then execute on every CLI start and fail on bare Next.js specifiers that Node's
+ * ESM resolver cannot resolve.
+ *
+ * Resolving these files to an inert stub keeps the owning `widget.ts` importable (the CLI
+ * reads its metadata when seeding dashboards) while cutting the browser-only subgraph.
+ *
+ * Only `import()` expressions are stubbed. That is the documented way a server-side
+ * `widget.ts` reaches its browser component (`lazyDashboardWidget(() => import('./widget.client'))`),
+ * and its result is consumed as a namespace object, so a default-only stub is sufficient.
+ * Static imports are left to the bundler: they may request named bindings the stub cannot
+ * provide, which esbuild rejects with `No matching export`, failing the whole CLI bundle —
+ * the exact class of breakage this module exists to prevent. Restricting the rewrite to
+ * dynamic imports also keeps server-side helpers that merely follow a `*.client.ts` naming
+ * convention working untouched.
+ */
+
+export const CLIENT_ONLY_STUB_NAMESPACE = 'om-client-only-stub'
+
+const LOCAL_IMPORT_PATTERN = /^(\.{1,2}\/|@\/)/
+const CLIENT_ONLY_SUFFIX_PATTERN = /(^|[\\/])[^\\/]+\.client(\.[cm]?[jt]sx?)?$/
+
+/**
+ * Local (relative or `@/` aliased) imports of a `*.client` module. Bare package specifiers
+ * are left alone because the bundler already marks them external, so they never get inlined.
+ */
+export function isClientOnlyModulePath(importPath: string): boolean {
+  if (!LOCAL_IMPORT_PATTERN.test(importPath)) return false
+  return CLIENT_ONLY_SUFFIX_PATTERN.test(importPath)
+}
+
+/**
+ * Render a value as a JavaScript string literal safe to embed in generated source.
+ * Everything outside printable ASCII is escaped to a `\uXXXX` sequence, so no character
+ * of the input can terminate the literal or be re-interpreted as code — `JSON.stringify`
+ * alone is a JSON encoder, not a JavaScript-source escaper.
+ */
+export function encodeJsStringLiteral(value: string): string {
+  let encoded = ''
+  for (let index = 0; index < value.length; index += 1) {
+    const char = value[index]
+    if (char === '"' || char === '\\') {
+      encoded += `\\${char}`
+      continue
+    }
+    const code = value.charCodeAt(index)
+    if (code < 0x20 || code > 0x7e) {
+      encoded += `\\u${code.toString(16).padStart(4, '0')}`
+      continue
+    }
+    encoded += char
+  }
+  return `"${encoded}"`
+}
+
+export function renderClientOnlyModuleStub(importPath: string): string {
+  const message =
+    `[internal] Client-only module ${importPath} is not available in the CLI runtime. ` +
+    'It is excluded from the CLI bundle because it renders browser components.'
+  return [
+    `function clientOnlyModuleUnavailable() { throw new Error(${encodeJsStringLiteral(message)}) }`,
+    'export default clientOnlyModuleUnavailable',
+  ].join('\n')
+}
+
+export function createClientOnlyStubPlugin(): import('esbuild').Plugin {
+  return {
+    name: 'client-only-stub',
+    setup(build) {
+      build.onResolve({ filter: CLIENT_ONLY_SUFFIX_PATTERN }, (args) => {
+        if (args.kind !== 'dynamic-import') return null
+        if (!isClientOnlyModulePath(args.path)) return null
+        return { path: args.path, namespace: CLIENT_ONLY_STUB_NAMESPACE }
+      })
+      build.onLoad({ filter: /.*/, namespace: CLIENT_ONLY_STUB_NAMESPACE }, (args) => ({
+        contents: renderClientOnlyModuleStub(args.path),
+        loader: 'js',
+      }))
+    },
+  }
+}

package/src/lib/bootstrap/dynamicLoader.ts

@@ -6,6 +6,7 @@ import {
   ensureMikroOrmV7GeneratedCacheCompatibility,
   recoverMikroOrmV7GeneratedCacheFromImportError,
 } from './generatedCacheRecovery'
+import { createClientOnlyStubPlugin } from './clientOnlyModules'
 import path from 'node:path'
 import fs from 'node:fs'
 import { pathToFileURL } from 'node:url'
@@ -29,6 +30,59 @@ class GeneratedFileNotFoundError extends Error {
   }
 }
 
+/**
+ * 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 @/ 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 }
+      })
+    },
+  }
+
+  return [createClientOnlyStubPlugin(), aliasPlugin, externalNonJsonPlugin]
+}
+
 /**
  * Compile a TypeScript file to JavaScript using esbuild bundler.
  * This bundles the file and all its dependencies, handling JSON imports properly.
@@ -53,47 +107,6 @@ async function compileAndImport(tsPath: string, allowRecovery: boolean = true):
     // 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 }
-        })
-      },
-    }
-
     // Use esbuild.build with bundling to handle JSON imports
     await esbuild.build({
       entryPoints: [tsPath],
@@ -102,7 +115,7 @@ async function compileAndImport(tsPath: string, allowRecovery: boolean = true):
       format: 'esm',
       platform: 'node',
       target: 'node18',
-      plugins: [aliasPlugin, externalNonJsonPlugin],
+      plugins: createCliBundlePlugins(appRoot),
       // Allow JSON imports
       loader: { '.json': 'json' },
     })

package/src/lib/encryption/tenantDataEncryptionService.ts

@@ -336,12 +336,26 @@ export class TenantDataEncryptionService {
     this.kms.invalidateDek?.(tenantId)
   }
 
+  /**
+   * Lists the fields an encryption map marks as encrypted at rest.
+   *
+   * `isEnabled()` folds the environment toggle together with KMS health, so by default an
+   * unhealthy KMS reports "nothing is encrypted" — which is safe for write paths but wrong for
+   * readers that must decide whether a stored column holds ciphertext. `ignoreRuntimeHealth`
+   * answers the on-disk question instead: it consults the map even when the KMS cannot currently
+   * resolve a DEK, so callers can fail closed rather than treat ciphertext as plaintext (#4622).
+   */
   async getEncryptedFieldNames(
     entityId: string,
     tenantId: string | null | undefined,
-    organizationId?: string | null
+    organizationId?: string | null,
+    options?: { ignoreRuntimeHealth?: boolean }
   ): Promise<string[]> {
-    if (!this.isEnabled()) return []
+    if (options?.ignoreRuntimeHealth) {
+      if (!isTenantDataEncryptionEnabled()) return []
+    } else if (!this.isEnabled()) {
+      return []
+    }
     const map = await this.getMap({ entityId, tenantId: tenantId ?? null, organizationId: organizationId ?? null })
     const fields = new Set(normalizeEncryptedFieldNames(map?.fields))
     if (organizationId == null) {

package/src/lib/modules/__tests__/surfaceFingerprint.test.ts

@@ -0,0 +1,122 @@
+import type { Module, BackendRouteManifestEntry } from '../../../modules/registry'
+import { getBackendRouteManifests } from '../../../modules/registry'
+import { getModules } from '../registry'
+import { getModuleSurfaceFingerprint } from '../surfaceFingerprint'
+
+jest.mock('../registry', () => ({
+  getModules: jest.fn(),
+}))
+
+jest.mock('../../../modules/registry', () => ({
+  getBackendRouteManifests: jest.fn(),
+}))
+
+const mockGetModules = jest.mocked(getModules)
+const mockGetBackendRouteManifests = jest.mocked(getBackendRouteManifests)
+
+function route(pattern: string, overrides: Partial<BackendRouteManifestEntry> = {}): BackendRouteManifestEntry {
+  return {
+    moduleId: 'auth',
+    pattern,
+    title: 'Page',
+    load: async () => null,
+    ...overrides,
+  } as BackendRouteManifestEntry
+}
+
+type ModuleSurface = string | { id: string; features: Array<{ id: string; module?: string }> }
+
+function setSurface(modules: ModuleSurface[], routes: BackendRouteManifestEntry[]): void {
+  mockGetModules.mockReturnValue(modules.map((mod) => (typeof mod === 'string' ? { id: mod } : mod) as Module))
+  mockGetBackendRouteManifests.mockReturnValue(routes)
+}
+
+describe('getModuleSurfaceFingerprint', () => {
+  afterEach(() => {
+    jest.resetAllMocks()
+  })
+
+  it('is stable for the same enabled modules and route manifest', () => {
+    setSurface(['auth', 'search'], [route('/backend/dashboard')])
+    const first = getModuleSurfaceFingerprint()
+
+    setSurface(['auth', 'search'], [route('/backend/dashboard')])
+    expect(getModuleSurfaceFingerprint()).toBe(first)
+  })
+
+  it('changes when a module is enabled — the deploy that used to serve a stale nav', () => {
+    setSurface(['auth'], [route('/backend/dashboard')])
+    const before = getModuleSurfaceFingerprint()
+
+    setSurface(['auth', 'search'], [route('/backend/dashboard')])
+    expect(getModuleSurfaceFingerprint()).not.toBe(before)
+  })
+
+  it('changes when a backend route is added', () => {
+    setSurface(['auth'], [route('/backend/dashboard')])
+    const before = getModuleSurfaceFingerprint()
+
+    setSurface(['auth'], [route('/backend/dashboard'), route('/backend/search')])
+    expect(getModuleSurfaceFingerprint()).not.toBe(before)
+  })
+
+  it('changes when only a route metadata field changes', () => {
+    setSurface(['auth'], [route('/backend/dashboard', { title: 'Dashboard' })])
+    const before = getModuleSurfaceFingerprint()
+
+    setSurface(['auth'], [route('/backend/dashboard', { title: 'Overview' })])
+    expect(getModuleSurfaceFingerprint()).not.toBe(before)
+  })
+
+  it('changes when a module declares a new feature and no route moves', () => {
+    const routes = [route('/backend/dashboard')]
+    setSurface([{ id: 'auth', features: [{ id: 'auth.view' }] }], routes)
+    const before = getModuleSurfaceFingerprint()
+
+    setSurface([{ id: 'auth', features: [{ id: 'auth.view' }, { id: 'auth.manage' }] }], routes)
+    expect(getModuleSurfaceFingerprint()).not.toBe(before)
+  })
+
+  it('changes when a feature declares a different owning module', () => {
+    const routes = [route('/backend/dashboard')]
+    setSurface([{ id: 'auth', features: [{ id: 'analytics.view' }] }], routes)
+    const before = getModuleSurfaceFingerprint()
+
+    setSurface([{ id: 'auth', features: [{ id: 'analytics.view', module: 'reporting' }] }], routes)
+    expect(getModuleSurfaceFingerprint()).not.toBe(before)
+  })
+
+  it('ignores feature ordering within a module', () => {
+    const routes = [route('/backend/dashboard')]
+    setSurface([{ id: 'auth', features: [{ id: 'auth.view' }, { id: 'auth.manage' }] }], routes)
+    const forward = getModuleSurfaceFingerprint()
+
+    setSurface([{ id: 'auth', features: [{ id: 'auth.manage' }, { id: 'auth.view' }] }], routes)
+    expect(getModuleSurfaceFingerprint()).toBe(forward)
+  })
+
+  it('ignores route manifest ordering', () => {
+    setSurface(['auth'], [route('/backend/a'), route('/backend/b')])
+    const forward = getModuleSurfaceFingerprint()
+
+    setSurface(['auth'], [route('/backend/b'), route('/backend/a')])
+    expect(getModuleSurfaceFingerprint()).toBe(forward)
+  })
+
+  it('falls back to the route manifest alone when the module registry is not populated', () => {
+    mockGetModules.mockImplementation(() => {
+      throw new Error('[Bootstrap] Modules not registered.')
+    })
+    mockGetBackendRouteManifests.mockReturnValue([route('/backend/dashboard')])
+
+    expect(getModuleSurfaceFingerprint()).toMatch(/^[0-9a-f]{12}$/)
+  })
+
+  it('degrades to a constant rather than throwing when route metadata cannot be serialized', () => {
+    const circular = route('/backend/dashboard') as BackendRouteManifestEntry & { self?: unknown }
+    circular.self = circular
+    setSurface(['auth'], [circular])
+
+    expect(getModuleSurfaceFingerprint()).toBe('unknown')
+  })
+})

package/src/lib/modules/surfaceFingerprint.ts

@@ -0,0 +1,87 @@
+/**
+ * Deploy-time fingerprint of the registered module surface.
+ *
+ * Some cached payloads are derived from state that only changes when the app
+ * is redeployed — the enabled module set and the backend route manifest. That
+ * state has no database write to hang a tag invalidation off, so a cache key
+ * that omits it keeps serving the pre-deploy payload to anyone with a warm
+ * entry (see `/api/auth/admin/nav`, whose payload embeds
+ * `filterGrantsByEnabledModules(...)` computed at write time).
+ *
+ * Mixing this fingerprint into such keys makes new processes write to new
+ * keys, so old and new pods coexist during a rolling deploy without a purge
+ * step and without any ordering constraint between purge and rollout.
+ *
+ * Covered inputs: the enabled module ids, each module's declared `features`
+ * (which drive `filterGrantsByEnabledModules`, including the `*` superadmin
+ * expansion and off-convention prefixes), and every JSON-serializable field
+ * of the backend route manifest.
+ *
+ * NOT covered: a route's `icon`. It is a React element whose `type` is a
+ * function, which `JSON.stringify` drops — two different icon components
+ * serialize identically. Swapping an icon heals on the caller's TTL, not on
+ * the fingerprint. Callers MUST therefore still pass a `ttl`.
+ */
+import { createHash } from 'node:crypto'
+import type { Module } from '../../modules/registry'
+import { getBackendRouteManifests } from '../../modules/registry'
+import { getModules } from './registry'
+
+const UNKNOWN_FINGERPRINT = 'unknown'
+
+let cachedFingerprint: string | null = null
+let cachedManifestsRef: unknown = null
+let cachedModulesRef: unknown = null
+
+function readModulesRef(): readonly Module[] | null {
+  try {
+    return getModules()
+  } catch {
+    return null
+  }
+}
+
+function byCodeUnit(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0
+}
+
+function describeModules(modules: readonly Module[] | null): string[] {
+  if (!modules) return []
+  return modules
+    .map((mod) => {
+      const features = (Array.isArray(mod.features) ? mod.features : [])
+        .filter((feature) => feature && typeof feature.id === 'string' && feature.id.length > 0)
+        .map((feature) => `${feature.id}:${feature.module || mod.id}`)
+        .sort(byCodeUnit)
+      return JSON.stringify({ id: mod.id, features })
+    })
+    .sort(byCodeUnit)
+}
+
+export function getModuleSurfaceFingerprint(): string {
+  const manifests = getBackendRouteManifests()
+  const modulesRef = readModulesRef()
+  if (cachedFingerprint !== null && cachedManifestsRef === manifests && cachedModulesRef === modulesRef) {
+    return cachedFingerprint
+  }
+  // The manifest carries third-party route metadata and module-scope React
+  // elements, so serialization is not fully under this repo's control. Every
+  // other fallible step in the nav handler degrades rather than throws, and a
+  // throw here would blank the entire admin chrome — fall back to a constant,
+  // which is exactly the pre-fingerprint behavior.
+  let fingerprint: string
+  try {
+    const modules = describeModules(modulesRef)
+    const routes = manifests.map((route) => JSON.stringify(route)).sort(byCodeUnit)
+    fingerprint = createHash('sha1')
+      .update(JSON.stringify({ modules, routes }))
+      .digest('hex')
+      .slice(0, 12)
+  } catch {
+    fingerprint = UNKNOWN_FINGERPRINT
+  }
+  cachedManifestsRef = manifests
+  cachedModulesRef = modulesRef
+  cachedFingerprint = fingerprint
+  return fingerprint
+}