@open-mercato/shared 0.10.1-develop.7576.1.21d5b50435 → 0.10.1-develop.7577.1.477f2486e5

package/src/lib/bootstrap/__tests__/dynamicLoader.tsconfig.test.ts

@@ -133,7 +133,7 @@ describe('dynamic loader app tsconfig and content-addressed cache', () => {
     loadBootstrapDataInNode(appRoot)
     const after = readCacheMetadata(appRoot, 'entities')
 
-    expect(after.version).toBe(4)
+    expect(after.version).toBe(5)
     expect(after.inputHash).not.toBe(before.inputHash)
   })
 
@@ -287,6 +287,6 @@ describe('dynamic loader app tsconfig and content-addressed cache', () => {
 
     loadBootstrapDataInNode(appRoot)
 
-    expect(readCacheMetadata(appRoot, 'entities').version).toBe(4)
+    expect(readCacheMetadata(appRoot, 'entities').version).toBe(5)
   })
 })

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

@@ -62,7 +62,8 @@ describe('partitioned bootstrap registration', () => {
   })
 
   it('keeps API-only bootstrap from replacing core injection widgets', async () => {
-    const apiBootstrap = createBootstrap(emptyBootstrapData, {
+    const entry = { moduleId: 'example', key: 'example:widget', source: 'app' as const, loader: async () => ({}) as never }
+    const apiBootstrap = createBootstrap({ ...emptyBootstrapData, injectionWidgetEntries: [entry] }, {
       registrationKey: 'api-only',
       skipUiRegistries: true,
       skipCoreInjectionWidgets: true,
@@ -71,11 +72,22 @@ describe('partitioned bootstrap registration', () => {
     apiBootstrap()
     await waitForAsyncRegistration()
 
-    expect(registerCoreInjectionWidgetsMock).not.toHaveBeenCalled()
-    // The raw widget entries still travel with the tables so a `key`-spelled injection
-    // override resolves to the `widgetId` the slots reference (#5152), even though this
-    // bootstrap deliberately skips registering the widgets themselves.
-    expect(registerCoreInjectionTablesMock).toHaveBeenCalledWith([], [])
+    // The API partition still contributes its entries — module API routes resolve widget
+    // contributions on the request path — but in `merge` mode, so it can never shrink a
+    // registry the full page bootstrap already published in the same process.
+    expect(registerCoreInjectionWidgetsMock).toHaveBeenCalledWith([entry], { mode: 'merge' })
+    // The raw widget entries also travel with the tables so a `key`-spelled injection
+    // override resolves to the `widgetId` the slots reference (#5152).
+    expect(registerCoreInjectionTablesMock).toHaveBeenCalledWith([], [entry])
     expect(registerEnabledModuleIdsMock).toHaveBeenCalledTimes(1)
   })
+
+  it('lets the full bootstrap replace the registry outright', async () => {
+    const fullBootstrap = createBootstrap(emptyBootstrapData, { registrationKey: 'full-only' })
+
+    fullBootstrap()
+    await waitForAsyncRegistration()
+
+    expect(registerCoreInjectionWidgetsMock).toHaveBeenCalledWith([], undefined)
+  })
 })

package/src/lib/bootstrap/__tests__/next-subpath-resolve-hook.test.ts

@@ -0,0 +1,174 @@
+import {
+  installNextSubpathResolveHook,
+  resetNextSubpathResolveHookForTests,
+  resolveNextSubpath,
+  resolveNextSubpathAsync,
+} from '../next-subpath-resolve-hook'
+
+function notFound(specifier: string): Error & { code: string } {
+  return Object.assign(new Error(`Cannot find module '${specifier}'`), { code: 'ERR_MODULE_NOT_FOUND' })
+}
+
+describe('resolveNextSubpath (#6118)', () => {
+  const context = { parentURL: 'file:///app/route.js' }
+
+  it('leaves specifiers other than next/<subpath> to the default resolver', () => {
+    const nextResolve = jest.fn(() => ({ url: 'file:///app/node_modules/zod/index.js' }))
+
+    const result = resolveNextSubpath('zod', context, nextResolve)
+
+    expect(result.url).toBe('file:///app/node_modules/zod/index.js')
+    expect(nextResolve).toHaveBeenCalledTimes(1)
+    expect(nextResolve).toHaveBeenCalledWith('zod', context)
+  })
+
+  it('does not touch a next/<subpath> that resolves on its own', () => {
+    // The day `next` ships an exports map the hook must step aside.
+    const nextResolve = jest.fn(() => ({ url: 'file:///app/node_modules/next/server.js' }))
+
+    resolveNextSubpath('next/server', context, nextResolve)
+
+    expect(nextResolve).toHaveBeenCalledTimes(1)
+  })
+
+  it('retries a bare next/<subpath> with the .js suffix when Node cannot resolve it', () => {
+    // `next` has no exports map and Node ESM does no extension guessing, so
+    // `next/server` fails while `next/server.js` is a real file.
+    const nextResolve = jest
+      .fn()
+      .mockImplementationOnce(() => { throw notFound('/app/node_modules/next/server') })
+      .mockImplementationOnce(() => ({ url: 'file:///app/node_modules/next/server.js' }))
+
+    const result = resolveNextSubpath('next/server', context, nextResolve)
+
+    expect(result.url).toBe('file:///app/node_modules/next/server.js')
+    expect(nextResolve).toHaveBeenNthCalledWith(1, 'next/server', context)
+    expect(nextResolve).toHaveBeenNthCalledWith(2, 'next/server.js', context)
+  })
+
+  it('covers the other subpaths route modules import', () => {
+    for (const subpath of ['next/headers', 'next/navigation', 'next/cache']) {
+      const nextResolve = jest
+        .fn()
+        .mockImplementationOnce(() => { throw notFound(subpath) })
+        .mockImplementationOnce((resolvedSpecifier: string) => ({
+          url: `file:///app/node_modules/${resolvedSpecifier}`,
+        }))
+      expect(resolveNextSubpath(subpath, context, nextResolve).url).toBe(`file:///app/node_modules/${subpath}.js`)
+    }
+  })
+
+  it('does not retry deeper or already-suffixed specifiers', () => {
+    for (const specifier of ['next/server.js', 'next/dist/server/web/spec-extension/response', 'next']) {
+      const nextResolve = jest.fn(() => { throw notFound(specifier) })
+      expect(() => resolveNextSubpath(specifier, context, nextResolve)).toThrow(/Cannot find module/)
+      expect(nextResolve).toHaveBeenCalledTimes(1)
+    }
+  })
+
+  it('rethrows the original error when the .js form is missing too', () => {
+    const original = notFound('/app/node_modules/next/server')
+    const nextResolve = jest
+      .fn()
+      .mockImplementationOnce(() => { throw original })
+      .mockImplementationOnce(() => { throw notFound('/app/node_modules/next/server.js') })
+
+    expect(() => resolveNextSubpath('next/server', context, nextResolve)).toThrow(original)
+  })
+
+  it('rethrows errors that are not ERR_MODULE_NOT_FOUND without retrying', () => {
+    const syntaxError = Object.assign(new Error('bad package.json'), { code: 'ERR_INVALID_PACKAGE_CONFIG' })
+    const nextResolve = jest.fn(() => { throw syntaxError })
+
+    expect(() => resolveNextSubpath('next/server', context, nextResolve)).toThrow(syntaxError)
+    expect(nextResolve).toHaveBeenCalledTimes(1)
+  })
+})
+
+describe('installNextSubpathResolveHook', () => {
+  beforeEach(() => {
+    resetNextSubpathResolveHookForTests()
+  })
+
+  it('registers the resolve hook once per process', () => {
+    const register = jest.fn()
+
+    expect(installNextSubpathResolveHook(register, null)).toBe(true)
+    expect(installNextSubpathResolveHook(register, null)).toBe(false)
+
+    expect(register).toHaveBeenCalledTimes(1)
+    expect(register).toHaveBeenCalledWith({ resolve: resolveNextSubpath })
+  })
+
+  it('registers an asynchronous hook on Node 22.0-22.14', () => {
+    const registerHookModule = jest.fn()
+
+    expect(installNextSubpathResolveHook(null, registerHookModule)).toBe(true)
+    expect(registerHookModule).toHaveBeenCalledWith(
+      expect.objectContaining({ href: expect.stringMatching(/next-subpath-resolve-hook-worker\.js$/) }),
+      expect.stringMatching(/^file:/),
+    )
+  })
+
+  it('is a no-op on a runtime without either registration API', () => {
+    expect(installNextSubpathResolveHook(null, null)).toBe(false)
+  })
+})
+
+describe('resolveNextSubpathAsync', () => {
+  const context = { parentURL: 'file:///app/route.js' }
+
+  it('retries a bare next/<subpath> with the .js suffix', async () => {
+    const nextResolve = jest
+      .fn()
+      .mockRejectedValueOnce(notFound('/app/node_modules/next/server'))
+      .mockResolvedValueOnce({ url: 'file:///app/node_modules/next/server.js' })
+
+    const result = await resolveNextSubpathAsync('next/server', context, nextResolve)
+
+    expect(result.url).toBe('file:///app/node_modules/next/server.js')
+    expect(nextResolve).toHaveBeenNthCalledWith(1, 'next/server', context)
+    expect(nextResolve).toHaveBeenNthCalledWith(2, 'next/server.js', context)
+  })
+})
+
+describe('installNextSubpathResolveHook against the runtime node:module', () => {
+  afterEach(() => {
+    jest.dontMock('node:module')
+    jest.resetModules()
+  })
+
+  it('installs through node:module.register on Node 22.0-22.14', () => {
+    // A named import of `registerHooks` would throw while the module loads on
+    // such a runtime; the helper must load and use the older registration API.
+    jest.resetModules()
+    const register = jest.fn()
+    jest.doMock('node:module', () => ({ register }))
+    let installed: boolean | undefined
+    jest.isolateModules(() => {
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      const hookModule = require('../next-subpath-resolve-hook') as typeof import('../next-subpath-resolve-hook')
+      installed = hookModule.installNextSubpathResolveHook()
+    })
+    expect(installed).toBe(true)
+    expect(register).toHaveBeenCalledTimes(1)
+    expect(register.mock.calls[0][0]).toEqual(
+      expect.objectContaining({ href: expect.stringMatching(/next-subpath-resolve-hook-worker\.js$/) }),
+    )
+  })
+
+  it('installs through node:module.registerHooks when the runtime has it', () => {
+    jest.resetModules()
+    const register = jest.fn()
+    jest.doMock('node:module', () => ({ registerHooks: register }))
+    let installed: boolean | undefined
+    jest.isolateModules(() => {
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      const hookModule = require('../next-subpath-resolve-hook') as typeof import('../next-subpath-resolve-hook')
+      installed = hookModule.installNextSubpathResolveHook()
+    })
+    expect(installed).toBe(true)
+    expect(register).toHaveBeenCalledTimes(1)
+    expect(register.mock.calls[0][0]).toEqual({ resolve: expect.any(Function) })
+  })
+})

package/src/lib/bootstrap/dynamicLoader.ts

@@ -16,7 +16,7 @@ import { CLIENT_ONLY_STUB_NAMESPACE, createClientOnlyStubPlugin } from './client
 import path from 'node:path'
 import fs from 'node:fs'
 import crypto from 'node:crypto'
-import { createRequire } from 'node:module'
+import { createRequire, isBuiltin } from 'node:module'
 import { pathToFileURL } from 'node:url'
 
 let activeBootstrapLoads = 0
@@ -77,6 +77,44 @@ class GeneratedFileNotFoundError extends Error {
   }
 }
 
+function splitBareSpecifier(specifier: string): { packageName: string; subpath: string } | null {
+  const segments = specifier.split('/')
+  const nameLength = specifier.startsWith('@') ? 2 : 1
+  if (segments.length <= nameLength || segments.slice(0, nameLength).some((segment) => !segment)) return null
+  return {
+    packageName: segments.slice(0, nameLength).join('/'),
+    subpath: segments.slice(nameLength).join('/'),
+  }
+}
+
+/**
+ * Rewrites an externalized `pkg/subpath` specifier to the file Node's ESM resolver can load
+ * when `pkg` publishes no `exports` map (#6993). Builtins, packages with `exports`, subpaths
+ * that already carry an extension and anything that fails to resolve keep the original
+ * specifier, so the bundle never gets worse than before.
+ */
+function rewriteLegacySubpathSpecifier(
+  specifier: string,
+  appRequire: NodeRequire,
+  onRewrite: (manifestPath: string) => void,
+): string {
+  if (isBuiltin(specifier)) return specifier
+  const parts = splitBareSpecifier(specifier)
+  if (!parts || path.posix.extname(parts.subpath)) return specifier
+  try {
+    const manifestPath = appRequire.resolve(`${parts.packageName}/package.json`)
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8')) as { exports?: unknown }
+    if (manifest.exports != null) return specifier
+    const resolvedFile = appRequire.resolve(specifier)
+    const relativeFile = path.relative(path.dirname(manifestPath), resolvedFile)
+    if (!relativeFile || relativeFile.startsWith('..') || path.isAbsolute(relativeFile)) return specifier
+    onRewrite(manifestPath)
+    return `${parts.packageName}/${relativeFile.split(path.sep).join('/')}`
+  } catch {
+    return specifier
+  }
+}
+
 /**
  * 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.
@@ -85,7 +123,10 @@ class GeneratedFileNotFoundError extends Error {
  * `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[] {
+export function createCliBundlePlugins(
+  appRoot: string,
+  options: { onLegacySubpathRewrite?: (manifestPath: string) => void } = {},
+): 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 = {
@@ -113,6 +154,19 @@ export function createCliBundlePlugins(appRoot: string): import('esbuild').Plugi
     },
   }
 
+  // Node's ESM resolver only maps an extensionless package subpath (`next/link`) when the
+  // package publishes an `exports` map; legacy packages need the real file path instead.
+  const appRequire = createRequire(path.join(appRoot, 'package.json'))
+  const externalSpecifierCache = new Map<string, string>()
+  const onLegacySubpathRewrite = options.onLegacySubpathRewrite ?? (() => undefined)
+  const resolveExternalSpecifier = (specifier: string): string => {
+    const cached = externalSpecifierCache.get(specifier)
+    if (cached !== undefined) return cached
+    const resolved = rewriteLegacySubpathSpecifier(specifier, appRequire, onLegacySubpathRewrite)
+    externalSpecifierCache.set(specifier, resolved)
+    return resolved
+  }
+
   // Plugin to mark non-JSON package imports as external
   const externalNonJsonPlugin: import('esbuild').Plugin = {
     name: 'external-non-json',
@@ -129,7 +183,7 @@ export function createCliBundlePlugins(appRoot: string): import('esbuild').Plugi
           return null // Let esbuild handle it
         }
         // Otherwise mark as external
-        return { path: args.path, external: true }
+        return { path: resolveExternalSpecifier(args.path), external: true }
       })
     },
   }
@@ -137,7 +191,7 @@ export function createCliBundlePlugins(appRoot: string): import('esbuild').Plugi
   return [createClientOnlyStubPlugin(), aliasPlugin, externalNonJsonPlugin]
 }
 
-const DYNAMIC_LOADER_CACHE_VERSION = 4
+const DYNAMIC_LOADER_CACHE_VERSION = 5
 
 type DynamicLoaderCacheMetadata = {
   version: number
@@ -433,6 +487,7 @@ async function compileAppSourceFileWithActiveEsbuild(
   // Dynamically import esbuild only when needed
   const esbuild = await getEsbuildRuntime()
 
+  const rewrittenPackageManifests = new Set<string>()
   // Use esbuild.build with bundling to handle JSON imports
   const result = await esbuild.build({
     entryPoints: [tsPath],
@@ -444,7 +499,9 @@ async function compileAppSourceFileWithActiveEsbuild(
     platform: 'node',
     target: 'node18',
     tsconfig: appTsconfig,
-    plugins: createCliBundlePlugins(appRoot),
+    plugins: createCliBundlePlugins(appRoot, {
+      onLegacySubpathRewrite: (manifestPath) => rewrittenPackageManifests.add(manifestPath),
+    }),
     // Allow JSON imports
     loader: { '.json': 'json' },
   })
@@ -455,6 +512,7 @@ async function compileAppSourceFileWithActiveEsbuild(
     dependencies: {
       ...collectDependencyHashes(appRoot, result.metafile.inputs),
       ...hashFilesRelativeTo(appRoot, tsconfigPaths),
+      ...hashFilesRelativeTo(appRoot, [...rewrittenPackageManifests]),
     },
   }
   fs.writeFileSync(metadataPath, JSON.stringify(metadata))

package/src/lib/bootstrap/factory.ts

@@ -143,9 +143,14 @@ async function registerWidgetsAndOptionalPackages(data: BootstrapData, options:
   // browser-facing UI registries. API-only bootstraps avoid loading @open-mercato/ui.
   try {
     const coreInjection = await import('@open-mercato/core/modules/widgets/lib/injection')
-    if (!options.skipCoreInjectionWidgets) {
-      coreInjection.registerCoreInjectionWidgets(data.injectionWidgetEntries)
-    }
+    // A partitioned runtime still needs its own entries — server-side resolvers read this
+    // registry on request paths — it just must not shrink what a fuller partition already
+    // published in the same process. Merge does both; skipping registration altogether left
+    // API-only processes with an unregistered registry that throws on first read.
+    coreInjection.registerCoreInjectionWidgets(
+      data.injectionWidgetEntries,
+      options.skipCoreInjectionWidgets ? { mode: 'merge' } : undefined,
+    )
     coreInjection.registerCoreInjectionTables(data.injectionTables, data.injectionWidgetEntries)
     coreInjection.registerEnabledModuleIds(
       data.modules.map((module) => module.id).filter((id): id is string => typeof id === 'string' && id.length > 0),

package/src/lib/bootstrap/next-subpath-resolve-hook-worker.ts

@@ -0,0 +1,3 @@
+import { resolveNextSubpathAsync } from './next-subpath-resolve-hook'
+
+export const resolve = resolveNextSubpathAsync

package/src/lib/bootstrap/next-subpath-resolve-hook.ts

@@ -0,0 +1,130 @@
+/**
+ * Node ESM resolution for `next/<subpath>` outside the Next bundler (#6118, #7102).
+ *
+ * Installed by the `mercato` CLI entry, so every CLI command and worker it
+ * runs can load package dists that import `next/dynamic`, `next/link`,
+ * `next/server` … The `next/dynamic` imports in particular MUST keep the bare
+ * specifier: Next's `next_dynamic` compiler transform only matches it exactly.
+ *
+ * `mercato ai_assistant mcp:serve-http` (and `mcp:serve`, `mcp:dev`,
+ * `mcp:list-tools`) run in plain Node, and the AI API operation runner loads
+ * API route modules with a runtime `import()`. Those modules import
+ * `NextResponse` from `'next/server'`: a bare package subpath that only a
+ * bundler resolves, because `next` ships no `exports` map and Node's ESM
+ * resolver does no extension guessing. Every route with that import (287 of
+ * them on the 0.7.0 packages) therefore fails to load with
+ * `ERR_MODULE_NOT_FOUND … node_modules/next/server`, and every tool backed by
+ * such a route returns "Failed to load route module".
+ *
+ * `next/server.js`, `next/headers.js`, `next/navigation.js` … do exist as files,
+ * which is why `@open-mercato/shared` imports `'next/headers.js'`. Rather than
+ * rewriting several hundred imports across every package (and every
+ * third-party module), this hook retries a failed bare `next/<subpath>` with
+ * the `.js` suffix. It only runs in the processes that install it, only for
+ * `next/*` specifiers, and only after the normal resolution failed, so it
+ * becomes a no-op the day `next` publishes an `exports` map.
+ */
+import * as nodeModule from 'node:module'
+
+type ResolveContext = Record<string, unknown>
+type ResolveResult = { url: string; format?: string | null | undefined; shortCircuit?: boolean }
+type NextResolve = (specifier: string, context?: ResolveContext) => ResolveResult
+type AsyncNextResolve = (specifier: string, context?: ResolveContext) => ResolveResult | Promise<ResolveResult>
+
+/** Bare `next/<one segment>` specifiers, e.g. `next/server`, `next/headers`. */
+const NEXT_BARE_SUBPATH = /^next\/[A-Za-z0-9_-]+$/
+
+let installed = false
+
+function isModuleNotFound(error: unknown): boolean {
+  return Boolean(error) && typeof error === 'object' && (error as { code?: unknown }).code === 'ERR_MODULE_NOT_FOUND'
+}
+
+/**
+ * The resolve hook itself. Exported so it can be tested without touching the
+ * process-global hook chain.
+ */
+export function resolveNextSubpath(
+  specifier: string,
+  context: ResolveContext,
+  nextResolve: NextResolve,
+): ResolveResult {
+  if (!NEXT_BARE_SUBPATH.test(specifier)) return nextResolve(specifier, context)
+  try {
+    return nextResolve(specifier, context)
+  } catch (error) {
+    if (!isModuleNotFound(error)) throw error
+    try {
+      return nextResolve(`${specifier}.js`, context)
+    } catch {
+      // Neither form resolves (Next is not installed at all): surface the
+      // original error, which names the specifier the caller wrote.
+      throw error
+    }
+  }
+}
+
+export async function resolveNextSubpathAsync(
+  specifier: string,
+  context: ResolveContext,
+  nextResolve: AsyncNextResolve,
+): Promise<ResolveResult> {
+  if (!NEXT_BARE_SUBPATH.test(specifier)) return nextResolve(specifier, context)
+  try {
+    return await nextResolve(specifier, context)
+  } catch (error) {
+    if (!isModuleNotFound(error)) throw error
+    try {
+      return await nextResolve(`${specifier}.js`, context)
+    } catch {
+      throw error
+    }
+  }
+}
+
+type RegisterHooks = (hooks: { resolve: typeof resolveNextSubpath }) => unknown
+type RegisterHookModule = (specifier: string | URL, parentURL?: string | URL) => unknown
+
+/**
+ * `module.registerHooks` exists from Node 22.15. It is read off the namespace
+ * rather than imported by name: in the published ESM build a named import of an
+ * export the running Node lacks fails while the module links, before the check
+ * in `installNextSubpathResolveHook` can run, and the package still declares
+ * `node >= 22.0.0`.
+ */
+function runtimeRegisterHooks(): RegisterHooks | undefined {
+  const candidate = (nodeModule as unknown as { registerHooks?: unknown }).registerHooks
+  return typeof candidate === 'function' ? (candidate as RegisterHooks) : undefined
+}
+
+function runtimeRegisterHookModule(): RegisterHookModule | undefined {
+  const candidate = (nodeModule as unknown as { register?: unknown }).register
+  return typeof candidate === 'function' ? (candidate as RegisterHookModule) : undefined
+}
+
+/**
+ * Install the hook once per process. Returns `true` when it was installed by
+ * this call, `false` when it already was or when the runtime has neither
+ * registration API. Node 22.15+ uses the synchronous hook API; earlier
+ * supported Node 22 releases use the asynchronous hook API.
+ */
+export function installNextSubpathResolveHook(
+  registerHooks: RegisterHooks | null | undefined = runtimeRegisterHooks(),
+  registerHookModule: RegisterHookModule | null | undefined = runtimeRegisterHookModule(),
+): boolean {
+  if (installed) return false
+  if (typeof registerHooks === 'function') {
+    registerHooks({ resolve: resolveNextSubpath })
+  } else if (typeof registerHookModule === 'function') {
+    registerHookModule(new URL('./next-subpath-resolve-hook-worker.js', import.meta.url), import.meta.url)
+  } else {
+    return false
+  }
+  installed = true
+  return true
+}
+
+/** Test seam: forget that the hook was installed. */
+export function resetNextSubpathResolveHookForTests(): void {
+  installed = false
+}

package/src/lib/bootstrap/types.ts

@@ -73,7 +73,11 @@ export interface BootstrapOptions {
   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. */
+  /**
+   * Keep an existing core injection-widget registry intact in partitioned runtimes: this
+   * bootstrap's entries are merged in rather than published as the whole registry, so a
+   * partition that registers second never shrinks what the first one already exposed.
+   */
   skipCoreInjectionWidgets?: boolean
   onRegistrationComplete?: () => void
   appDiRegistrar?: AppDiRegistrar

package/src/lib/catalog-visibility/__tests__/hashEffectiveScope.test.ts

@@ -0,0 +1,121 @@
+import { canonicalizeEffectiveScope } from '../canonicalizeEffectiveScope'
+import { hashEffectiveScope } from '../hashEffectiveScope'
+import type { AssortmentScope, EffectiveAssortmentScope } from '../types'
+import { mulberry32, randomAssortmentScope } from './testFixtures'
+
+function shuffle<T>(rng: () => number, items: T[]): T[] {
+  const copy = [...items]
+  for (let index = copy.length - 1; index > 0; index -= 1) {
+    const swap = Math.floor(rng() * (index + 1))
+    const held = copy[index]
+    copy[index] = copy[swap]
+    copy[swap] = held
+  }
+  return copy
+}
+
+function shuffleScope(rng: () => number, scope: AssortmentScope): AssortmentScope {
+  const entries = shuffle(rng, Object.entries(scope)).map(([key, value]) => {
+    if (key === 'allOf') {
+      return [key, shuffle(rng, (value as AssortmentScope[]).map((nested) => shuffleScope(rng, nested)))]
+    }
+    return [key, shuffle(rng, value as string[])]
+  })
+  return Object.fromEntries(entries) as AssortmentScope
+}
+
+function randomEffective(rng: () => number): EffectiveAssortmentScope {
+  if (rng() < 0.1) return null
+  const branches: AssortmentScope[] = []
+  const count = Math.floor(rng() * 4)
+  for (let index = 0; index < count; index += 1) {
+    const branch = randomAssortmentScope(rng)
+    if (rng() < 0.3) {
+      branch.allOf = [randomAssortmentScope(rng), randomAssortmentScope(rng)]
+    }
+    branches.push(branch)
+  }
+  return branches
+}
+
+describe('canonicalizeEffectiveScope', () => {
+  it('distinguishes unrestricted (null) from deny-all ([])', () => {
+    expect(canonicalizeEffectiveScope(null)).toBe('null')
+    expect(canonicalizeEffectiveScope([])).toBe('[]')
+    expect(hashEffectiveScope(null)).not.toBe(hashEffectiveScope([]))
+  })
+
+  it('treats empty arrays as absent keys', () => {
+    expect(canonicalizeEffectiveScope([{ categoryIds: [], tagIds: ['t1'], excludeTagIds: [] }])).toBe(
+      canonicalizeEffectiveScope([{ tagIds: ['t1'] }]),
+    )
+    expect(canonicalizeEffectiveScope([{ categoryIds: [], allOf: [] }])).toBe(canonicalizeEffectiveScope([{}]))
+  })
+
+  it('keeps an empty branch (matches everything) distinct from no branches', () => {
+    expect(canonicalizeEffectiveScope([{}])).toBe('[{}]')
+    expect(canonicalizeEffectiveScope([{}])).not.toBe(canonicalizeEffectiveScope([]))
+  })
+
+  it('is invariant to key order, id order and duplicate ids', () => {
+    const left: EffectiveAssortmentScope = [{ tagIds: ['b', 'a', 'a'], categoryIds: ['y', 'x'] }]
+    const right: EffectiveAssortmentScope = [{ categoryIds: ['x', 'y'], tagIds: ['a', 'b'] }]
+    expect(canonicalizeEffectiveScope(left)).toBe(canonicalizeEffectiveScope(right))
+    expect(hashEffectiveScope(left)).toBe(hashEffectiveScope(right))
+  })
+
+  it('is invariant to branch order and collapses identical branches', () => {
+    const forward: EffectiveAssortmentScope = [{ categoryIds: ['a'] }, { tagIds: ['b'] }]
+    const reversed: EffectiveAssortmentScope = [{ tagIds: ['b'] }, { categoryIds: ['a'] }, { categoryIds: ['a'] }]
+    expect(canonicalizeEffectiveScope(forward)).toBe(canonicalizeEffectiveScope(reversed))
+  })
+
+  it('canonicalizes nested allOf entries and their order', () => {
+    const left: EffectiveAssortmentScope = [
+      { categoryIds: ['a'], allOf: [{ tagIds: ['t2', 't1'] }, { excludeProductIds: ['p1'], allOf: [{ categoryIds: ['c2', 'c1'] }] }] },
+    ]
+    const right: EffectiveAssortmentScope = [
+      { allOf: [{ allOf: [{ categoryIds: ['c1', 'c2'] }], excludeProductIds: ['p1'] }, { tagIds: ['t1', 't2'] }], categoryIds: ['a'] },
+    ]
+    expect(canonicalizeEffectiveScope(left)).toBe(canonicalizeEffectiveScope(right))
+  })
+
+  it('distinguishes scopes that match differently', () => {
+    expect(canonicalizeEffectiveScope([{ categoryIds: ['a'] }])).not.toBe(canonicalizeEffectiveScope([{ tagIds: ['a'] }]))
+    expect(canonicalizeEffectiveScope([{ categoryIds: ['a'], tagIds: ['b'] }])).not.toBe(
+      canonicalizeEffectiveScope([{ categoryIds: ['a'] }, { tagIds: ['b'] }]),
+    )
+    expect(canonicalizeEffectiveScope([{ categoryIds: ['a'] }])).not.toBe(
+      canonicalizeEffectiveScope([{ excludeCategoryIds: ['a'] }]),
+    )
+  })
+})
+
+describe('hashEffectiveScope', () => {
+  it('returns 16 lowercase hex characters', () => {
+    expect(hashEffectiveScope([{ categoryIds: ['a'] }])).toMatch(/^[0-9a-f]{16}$/)
+    expect(hashEffectiveScope(null)).toMatch(/^[0-9a-f]{16}$/)
+  })
+
+  it('property: shuffling branch, key and id order preserves the hash', () => {
+    for (let seed = 1; seed <= 200; seed += 1) {
+      const rng = mulberry32(seed)
+      const scope = randomEffective(rng)
+      const shuffled = scope === null ? null : shuffle(rng, scope.map((branch) => shuffleScope(rng, branch)))
+      expect(hashEffectiveScope(shuffled)).toBe(hashEffectiveScope(scope))
+    }
+  })
+
+  it('property: equal canonical form if and only if equal hash across random pairs', () => {
+    const rng = mulberry32(4242)
+    const scopes: EffectiveAssortmentScope[] = []
+    for (let index = 0; index < 60; index += 1) scopes.push(randomEffective(rng))
+    for (const left of scopes) {
+      for (const right of scopes) {
+        const sameCanonical = canonicalizeEffectiveScope(left) === canonicalizeEffectiveScope(right)
+        const sameHash = hashEffectiveScope(left) === hashEffectiveScope(right)
+        expect(sameHash).toBe(sameCanonical)
+      }
+    }
+  })
+})