@open-mercato/shared 0.7.1-develop.7154.1.981330c924 → 0.7.1-develop.7171.1.9b31dbba45

package/src/lib/bootstrap/dynamicLoader.ts

@@ -3,6 +3,10 @@ import type { AppDiRegistrar } from '../di/container'
 import { findAppRoot, type AppRoot } from './appResolver'
 import { registerEntityIds } from '../encryption/entityIds'
 import { createLogger } from '../logger'
+import {
+  applyModuleOverridesFromEnabledModules,
+  type ModuleEntryWithOverrides,
+} from '../../modules/overrides'
 import {
   ensureMikroOrmV7GeneratedCacheCompatibility,
   recoverMikroOrmV7GeneratedCacheFromImportError,
@@ -589,6 +593,95 @@ async function loadAppDiRegistrar(appDir: string): Promise<AppDiRegistrar | null
   }
 }
 
+/**
+ * Override domains whose applier is not registered by `registerBuiltInModuleOverrideAppliers()`
+ * but by importing a domain package for its side effect. `bootstrap-common.ts` does this with a
+ * static import right before it dispatches; the dynamic bootstrap path has no bundler to lean on,
+ * so it resolves the same modules here — lazily, and only when an app actually declares the
+ * domain, so `@open-mercato/shared` keeps its rule of never taking a runtime dependency on a
+ * domain package (soft-optional coupling, `packages/core/AGENTS.md` → Cross-Module Coupling).
+ */
+const OPTIONAL_OVERRIDE_APPLIER_MODULES: Record<string, string> = {
+  ai: '@open-mercato/ai-assistant/modules/ai_assistant/lib/ai-overrides',
+}
+
+/**
+ * Import the side-effect module that registers the applier for every declared override domain
+ * that has no built-in one. A domain package the app does not install is not an error — there
+ * is nothing for that domain to apply to — so a failed resolution is logged and skipped, and the
+ * dispatcher's own "domain not yet wired" warning still fires behind it.
+ */
+async function ensureOptionalOverrideAppliers(enabledModules: ModuleEntryWithOverrides[]): Promise<void> {
+  for (const [domain, specifier] of Object.entries(OPTIONAL_OVERRIDE_APPLIER_MODULES)) {
+    const declared = enabledModules.some((entry) => {
+      const overrides = entry?.overrides as Record<string, unknown> | undefined
+      return Boolean(overrides && overrides[domain])
+    })
+    if (!declared) continue
+    try {
+      await import(/* webpackIgnore: true */ /* turbopackIgnore: true */ specifier)
+    } catch (error) {
+      logger.debug('Optional override applier module is not installed; the domain has nothing to apply to', {
+        domain,
+        specifier,
+        err: error,
+      })
+    }
+  }
+}
+
+/**
+ * Dispatch `entry.overrides` declared in the app's `src/modules.ts` for the dynamic
+ * bootstrap path.
+ *
+ * The Next.js runtime imports `enabledModules` statically from its own `src/modules.ts` and
+ * calls `applyModuleOverridesFromEnabledModules` from `bootstrap-common.ts` before any registry
+ * first-loads. Worker, scheduler and CLI processes bootstrap through `bootstrapFromAppRoot`
+ * instead, which only ever compiled the generated `modules.cli.generated.ts` — so an app's
+ * `entry.overrides` (encryption maps, ACL features, CLI commands, workers, event subscribers,
+ * setup, …) silently never applied there. `seed-encryption` seeding the base encryption maps
+ * instead of the app's `overrides.encryption.maps` was the concrete symptom (#5582).
+ *
+ * An app layout with no `src/modules.ts` at all is logged and skipped — that is a real
+ * compatibility case, handled the same way an absent `src/di.ts` is. A file that is *present*
+ * but fails to compile or import is not: it throws, matching how this same function treats
+ * every other mandatory input and how the Next.js runtime treats this same file (a static
+ * import in `bootstrap-common.ts`). Degrading there would put `seed-encryption` back on the
+ * base encryption maps while still printing success — #5582's outcome, only quieter.
+ */
+async function loadAppModuleOverrides(appDir: string): Promise<void> {
+  const tsPath = path.join(appDir, 'src', 'modules.ts')
+  if (!fs.existsSync(tsPath)) {
+    logger.debug('App-level modules file not present, skipping entry.overrides dispatch', { filePath: tsPath })
+    return
+  }
+
+  let enabledModules: unknown
+  try {
+    const appModulesModule = await compileAndImport(tsPath, {
+      appRoot: appDir,
+      outFile: path.join(appDir, '.mercato', 'generated', 'app-modules-overrides.compiled.mjs'),
+    })
+    enabledModules = appModulesModule.enabledModules
+  } catch (error) {
+    throw new Error(
+      `[internal] Failed to load the app-level modules file (${tsPath}); entry.overrides cannot be applied. ` +
+        'Refusing to bootstrap with a partial override set.',
+      { cause: error },
+    )
+  }
+
+  if (!Array.isArray(enabledModules)) {
+    throw new Error(
+      `[internal] The app-level modules file (${tsPath}) exports no enabledModules array; ` +
+        'entry.overrides cannot be applied. Refusing to bootstrap with a partial override set.',
+    )
+  }
+
+  await ensureOptionalOverrideAppliers(enabledModules as ModuleEntryWithOverrides[])
+  applyModuleOverridesFromEnabledModules(enabledModules as ModuleEntryWithOverrides[])
+}
+
 /**
  * Dynamically load bootstrap data from a resolved app directory.
  *
@@ -681,13 +774,20 @@ export async function loadBootstrapData(appRoot?: string): Promise<BootstrapData
 export async function bootstrapFromAppRoot(appRoot?: string): Promise<BootstrapData> {
   const { createBootstrap, waitForAsyncRegistration } = await import('./factory.js')
   const resolved = resolveAppRootOrThrow(appRoot)
-  // Both loads compile through esbuild, so they share one lifecycle scope: without it
+  // All three loads compile through esbuild, so they share one lifecycle scope: without it
   // `loadBootstrapData` releases the esbuild helper process and `loadAppDiRegistrar`
   // silently starts a second one that nothing ever stops.
-  const { data, appDiRegistrar } = await withEsbuildLifecycle(async () => ({
-    data: await loadBootstrapData(resolved.appDir),
-    appDiRegistrar: await loadAppDiRegistrar(resolved.appDir),
-  }))
+  const { data, appDiRegistrar } = await withEsbuildLifecycle(async () => {
+    // Dispatch the app's `entry.overrides` (src/modules.ts) BEFORE any registry
+    // first-loads — the `bootstrap()` call below runs `registerModules(data.modules)`,
+    // and `registerCliModules` in the mercato bin right after this function returns;
+    // both read the override side-registry this populates.
+    await loadAppModuleOverrides(resolved.appDir)
+    return {
+      data: await loadBootstrapData(resolved.appDir),
+      appDiRegistrar: await loadAppDiRegistrar(resolved.appDir),
+    }
+  })
   const bootstrap = createBootstrap(data, appDiRegistrar ? { appDiRegistrar } : {})
   bootstrap()
   // In CLI context, wait for async registrations (UI widgets, search configs, etc.)

package/src/lib/crud/__tests__/crud-factory.test.ts

@@ -922,6 +922,29 @@ describe('CRUD Factory', () => {
     expect(mockDataEngine.emitOrmEntityEvent).not.toHaveBeenCalled()
   })
 
+  it('returns a correlated 409 without leaking the constraint name when a handler hits a foreign key violation', async () => {
+    setRecordCustomFields.mockImplementationOnce(async () => {
+      // Mirror MikroORM's wrapping: the pg error sits behind `previous`, and the
+      // wrapper only carries the message.
+      throw Object.assign(
+        new Error('update or delete on table "users" violates foreign key constraint "sidebar_variants_user_id_foreign" on table "sidebar_variants"'),
+        { previous: { code: '23503', constraint: 'sidebar_variants_user_id_foreign' } },
+      )
+    })
+    const res = await route.POST(new Request('http://x/api/example/todos', { method: 'POST', body: JSON.stringify({ title: 'Referenced', is_done: true, cf_priority: 3 }), headers: { 'content-type': 'application/json' } }))
+    expect(res.status).toBe(409)
+    const body = await res.json()
+    expect(body.code).toBe('FOREIGN_KEY_VIOLATION')
+    // Internal schema names stay in the server log, never in the client body.
+    expect(body.constraint).toBeUndefined()
+    expect(JSON.stringify(body)).not.toContain('sidebar_variants_user_id_foreign')
+    // Same correlation contract as the generic 500 path.
+    expect(typeof body.requestId).toBe('string')
+    expect(res.headers.get('x-request-id')).toBe(body.requestId)
+    expect(Object.values(db)).toHaveLength(0)
+    expect(mockDataEngine.emitOrmEntityEvent).not.toHaveBeenCalled()
+  })
+
   it('POST surfaces CRUD side-effect failures after custom field writes', async () => {
     mockDataEngine.emitOrmEntityEvent.mockImplementationOnce(async () => {
       throw new Error('index write failed')

package/src/lib/crud/__tests__/enricher-registry.test.ts

@@ -37,6 +37,22 @@ describe('enricher-registry', () => {
       expect(result[0].enricher.id).toBe('a.tier')
     })
 
+    it('includes wildcard enrichers in priority order for a concrete entity', () => {
+      registerResponseEnrichers([
+        {
+          moduleId: 'mod-a',
+          enrichers: [
+            makeEnricher({ id: 'a.exact', targetEntity: 'customers.person', priority: 10 }),
+            makeEnricher({ id: 'a.wildcard', targetEntity: '*', priority: 50 }),
+            makeEnricher({ id: 'a.other', targetEntity: 'sales.order', priority: 100 }),
+          ],
+        },
+      ])
+
+      const result = getEnrichersForEntity('customers.person')
+      expect(result.map((entry) => entry.enricher.id)).toEqual(['a.wildcard', 'a.exact'])
+    })
+
     it('returns enrichers regardless of queryEngine config', () => {
       registerResponseEnrichers([
         {

package/src/lib/crud/__tests__/enricher-runner.read-through-cache.test.ts

@@ -0,0 +1,291 @@
+import { applyResponseEnrichers, applyResponseEnricherToRecord } from '../enricher-runner'
+import { registerResponseEnrichers } from '../enricher-registry'
+import type { EnricherContext, ResponseEnricher } from '../response-enricher'
+
+type Record_ = Record<string, unknown>
+
+function createCache() {
+  const store = new Map<string, unknown>()
+  const set = jest.fn(async (key: string, value: unknown) => {
+    store.set(key, value)
+  })
+  const get = jest.fn(async (key: string) => (store.has(key) ? store.get(key) : null))
+  return { store, cache: { get, set } }
+}
+
+function createContext(cache: { get: jest.Mock; set: jest.Mock } | null): EnricherContext {
+  return {
+    tenantId: 'tenant-1',
+    organizationId: 'org-1',
+    userFeatures: ['demo.view'],
+    container: cache ? { resolve: (name: string) => (name === 'cache' ? cache : null) } : undefined,
+  } as unknown as EnricherContext
+}
+
+const TARGET = 'demo:widget'
+
+function defineEnricher(
+  enrichMany: (records: Record_[]) => Record_[],
+  overrides: Partial<ResponseEnricher> = {},
+): ResponseEnricher {
+  return {
+    id: 'demo.enricher',
+    targetEntity: TARGET,
+    priority: 10,
+    cache: { strategy: 'read-through', ttl: 30_000, tags: ['demo:widgets'] },
+    async enrichOne(record: Record_) {
+      return enrichMany([record])[0]
+    },
+    async enrichMany(records: Record_[]) {
+      return enrichMany(records)
+    },
+    ...overrides,
+  } as ResponseEnricher
+}
+
+function register(enricher: ResponseEnricher) {
+  registerResponseEnrichers([{ moduleId: 'demo', enrichers: [enricher] }])
+}
+
+describe('enricher runner read-through cache', () => {
+  beforeEach(() => {
+    registerResponseEnrichers([])
+  })
+
+  it('serves the enrichment from cache on the second call without re-running the enricher', async () => {
+    const { cache } = createCache()
+    const enrichMany = jest.fn((records: Record_[]) =>
+      records.map((record) => ({ ...record, _demo: { stock: 7 } })),
+    )
+    register(defineEnricher(enrichMany))
+
+    const items = [{ id: 'a', name: 'first' }]
+    const first = await applyResponseEnrichers(items, TARGET, createContext(cache))
+    expect(first.items[0]._demo).toEqual({ stock: 7 })
+    expect(enrichMany).toHaveBeenCalledTimes(1)
+
+    const second = await applyResponseEnrichers(items, TARGET, createContext(cache))
+    expect(second.items[0]._demo).toEqual({ stock: 7 })
+    expect(second._meta.enrichedBy).toEqual(['demo.enricher'])
+    expect(enrichMany).toHaveBeenCalledTimes(1)
+  })
+
+  it('keeps base record fields fresh on a cache hit instead of replaying the cached snapshot', async () => {
+    const { cache } = createCache()
+    const enrichMany = jest.fn((records: Record_[]) =>
+      records.map((record) => ({ ...record, _demo: { stock: 7 } })),
+    )
+    register(defineEnricher(enrichMany))
+
+    await applyResponseEnrichers([{ id: 'a', name: 'old name' }], TARGET, createContext(cache))
+
+    const second = await applyResponseEnrichers(
+      [{ id: 'a', name: 'new name' }],
+      TARGET,
+      createContext(cache),
+    )
+
+    expect(enrichMany).toHaveBeenCalledTimes(1)
+    expect(second.items[0].name).toBe('new name')
+    expect(second.items[0]._demo).toEqual({ stock: 7 })
+  })
+
+  it('does not cache an enricher that mutates a pre-existing field', async () => {
+    const { cache } = createCache()
+    const enrichMany = jest.fn((records: Record_[]) =>
+      records.map((record) => ({ ...record, name: 'rewritten', _demo: { stock: 1 } })),
+    )
+    register(defineEnricher(enrichMany))
+
+    const items = [{ id: 'a', name: 'original' }]
+    await applyResponseEnrichers(items, TARGET, createContext(cache))
+    expect(cache.set).not.toHaveBeenCalled()
+
+    const second = await applyResponseEnrichers(items, TARGET, createContext(cache))
+    expect(enrichMany).toHaveBeenCalledTimes(2)
+    expect(second.items[0].name).toBe('rewritten')
+  })
+
+  it('does not cache a batch containing a record without a usable id', async () => {
+    const { cache } = createCache()
+    const enrichMany = jest.fn((records: Record_[]) =>
+      records.map((record) => ({ ...record, _demo: { stock: 3 } })),
+    )
+    register(defineEnricher(enrichMany))
+
+    await applyResponseEnrichers([{ name: 'no id' }], TARGET, createContext(cache))
+
+    expect(cache.set).not.toHaveBeenCalled()
+  })
+
+  it('re-runs the enricher when the cached envelope does not cover every record', async () => {
+    const { store, cache } = createCache()
+    const enrichMany = jest.fn((records: Record_[]) =>
+      records.map((record) => ({ ...record, _demo: { stock: 5 } })),
+    )
+    register(defineEnricher(enrichMany))
+
+    const items = [{ id: 'a' }, { id: 'b' }]
+    await applyResponseEnrichers(items, TARGET, createContext(cache))
+    expect(enrichMany).toHaveBeenCalledTimes(1)
+
+    const [cacheKey] = Array.from(store.keys())
+    store.set(cacheKey, { version: 1, deltas: { a: { _demo: { stock: 5 } } } })
+
+    const second = await applyResponseEnrichers(items, TARGET, createContext(cache))
+    expect(enrichMany).toHaveBeenCalledTimes(2)
+    expect(second.items.map((item) => item._demo)).toEqual([{ stock: 5 }, { stock: 5 }])
+  })
+
+  it('ignores a cached payload written under a different envelope version', async () => {
+    const { store, cache } = createCache()
+    const enrichMany = jest.fn((records: Record_[]) =>
+      records.map((record) => ({ ...record, _demo: { stock: 9 } })),
+    )
+    register(defineEnricher(enrichMany))
+
+    const items = [{ id: 'a' }]
+    await applyResponseEnrichers(items, TARGET, createContext(cache))
+
+    const [cacheKey] = Array.from(store.keys())
+    store.set(cacheKey, { version: 99, deltas: { a: { _demo: { stock: 0 } } } })
+
+    const second = await applyResponseEnrichers(items, TARGET, createContext(cache))
+    expect(enrichMany).toHaveBeenCalledTimes(2)
+    expect(second.items[0]._demo).toEqual({ stock: 9 })
+  })
+
+  it('caches the delta of an enricher that mutates the records in place', async () => {
+    // The contract does not forbid in-place mutation. Comparing a mutated
+    // record against itself would produce an empty delta, so the cache would
+    // then serve unenriched records for the rest of the TTL.
+    const { cache } = createCache()
+    const enrichMany = jest.fn((records: Record_[]) => {
+      for (const record of records) {
+        record._demo = { stock: 11 }
+      }
+      return records
+    })
+    register(defineEnricher(enrichMany))
+
+    const first = await applyResponseEnrichers(
+      [{ id: 'a', name: 'first' }],
+      TARGET,
+      createContext(cache),
+    )
+    expect(first.items[0]._demo).toEqual({ stock: 11 })
+    expect(cache.set).toHaveBeenCalledTimes(1)
+
+    const second = await applyResponseEnrichers(
+      [{ id: 'a', name: 'first' }],
+      TARGET,
+      createContext(cache),
+    )
+
+    expect(enrichMany).toHaveBeenCalledTimes(1)
+    expect(second.items[0]._demo).toEqual({ stock: 11 })
+  })
+
+  it('caches an empty delta when the enricher genuinely adds nothing', async () => {
+    const { cache } = createCache()
+    const enrichMany = jest.fn((records: Record_[]) => records)
+    register(defineEnricher(enrichMany))
+
+    const items = [{ id: 'a', name: 'unchanged' }]
+    await applyResponseEnrichers(items, TARGET, createContext(cache))
+    expect(cache.set).toHaveBeenCalledTimes(1)
+
+    const second = await applyResponseEnrichers(items, TARGET, createContext(cache))
+    expect(enrichMany).toHaveBeenCalledTimes(1)
+    expect(second.items[0]).toEqual({ id: 'a', name: 'unchanged' })
+  })
+
+  it('does not let a cache hit mutate the caller\'s input records', async () => {
+    const { cache } = createCache()
+    register(
+      defineEnricher((records) => records.map((record) => ({ ...record, _demo: { stock: 8 } }))),
+    )
+
+    await applyResponseEnrichers([{ id: 'a' }], TARGET, createContext(cache))
+
+    const input = [{ id: 'a' }]
+    const second = await applyResponseEnrichers(input, TARGET, createContext(cache))
+
+    expect(second.items[0]._demo).toEqual({ stock: 8 })
+    expect(input[0]).toEqual({ id: 'a' })
+  })
+
+  it('never touches the cache for an enricher that did not opt in', async () => {
+    const { cache } = createCache()
+    const enrichMany = jest.fn((records: Record_[]) =>
+      records.map((record) => ({ ...record, _demo: { stock: 2 } })),
+    )
+    register(defineEnricher(enrichMany, { cache: undefined }))
+
+    const items = [{ id: 'a' }]
+    await applyResponseEnrichers(items, TARGET, createContext(cache))
+    await applyResponseEnrichers(items, TARGET, createContext(cache))
+
+    expect(cache.get).not.toHaveBeenCalled()
+    expect(cache.set).not.toHaveBeenCalled()
+    expect(enrichMany).toHaveBeenCalledTimes(2)
+  })
+
+  it('writes the enrichment tags alongside the automatic tenant, organization and enricher tags', async () => {
+    const { cache } = createCache()
+    register(
+      defineEnricher((records) => records.map((record) => ({ ...record, _demo: { stock: 1 } }))),
+    )
+
+    await applyResponseEnrichers([{ id: 'a' }], TARGET, createContext(cache))
+
+    expect(cache.set).toHaveBeenCalledTimes(1)
+    const [, , options] = cache.set.mock.calls[0]
+    expect(options.ttl).toBe(30_000)
+    expect(options.tags).toEqual(
+      expect.arrayContaining([
+        'tenant:tenant-1',
+        'organization:org-1',
+        'enricher:demo.enricher',
+        'demo:widgets',
+      ]),
+    )
+  })
+
+  it('caches the single-record path and keeps its base fields fresh', async () => {
+    const { cache } = createCache()
+    const enrichMany = jest.fn((records: Record_[]) =>
+      records.map((record) => ({ ...record, _demo: { stock: 4 } })),
+    )
+    register(defineEnricher(enrichMany))
+
+    const first = await applyResponseEnricherToRecord(
+      { id: 'a', name: 'old' },
+      TARGET,
+      createContext(cache),
+    )
+    expect(first.record._demo).toEqual({ stock: 4 })
+
+    const second = await applyResponseEnricherToRecord(
+      { id: 'a', name: 'new' },
+      TARGET,
+      createContext(cache),
+    )
+
+    expect(enrichMany).toHaveBeenCalledTimes(1)
+    expect(second.record.name).toBe('new')
+    expect(second.record._demo).toEqual({ stock: 4 })
+  })
+
+  it('runs normally when no cache service is available in the container', async () => {
+    const enrichMany = jest.fn((records: Record_[]) =>
+      records.map((record) => ({ ...record, _demo: { stock: 6 } })),
+    )
+    register(defineEnricher(enrichMany))
+
+    const result = await applyResponseEnrichers([{ id: 'a' }], TARGET, createContext(null))
+
+    expect(result.items[0]._demo).toEqual({ stock: 6 })
+    expect(enrichMany).toHaveBeenCalledTimes(1)
+  })
+})

package/src/lib/crud/__tests__/enricher-runner.test.ts

@@ -0,0 +1,59 @@
+import type { EnricherContext, ResponseEnricher } from '../response-enricher'
+import { registerResponseEnrichers } from '../enricher-registry'
+import { applyResponseEnricherToRecord } from '../enricher-runner'
+
+describe('enricher runner', () => {
+  it('partitions wildcard read-through cache entries by concrete entity', async () => {
+    const cacheEntries = new Map<string, unknown>()
+    const cache = {
+      get: jest.fn(async (key: string) => cacheEntries.get(key)),
+      set: jest.fn(async (key: string, value: unknown) => {
+        cacheEntries.set(key, value)
+      }),
+    }
+    const enrichOne = jest.fn(
+      async (record: Record<string, unknown>, context: EnricherContext) => ({
+        ...record,
+        enrichedFrom: context.targetEntity,
+      }),
+    )
+    const enricher: ResponseEnricher<
+      Record<string, unknown>,
+      { enrichedFrom: string | undefined }
+    > = {
+      id: 'test.wildcard-cache',
+      targetEntity: '*',
+      timeout: 10,
+      cache: { strategy: 'read-through', ttl: 60_000 },
+      enrichOne,
+    }
+    registerResponseEnrichers([{ moduleId: 'test', enrichers: [enricher] }])
+
+    const context: EnricherContext = {
+      organizationId: 'org-1',
+      tenantId: 'tenant-1',
+      userId: 'user-1',
+      em: {},
+      container: { resolve: () => cache },
+    }
+
+    const personResult = await applyResponseEnricherToRecord(
+      { id: 'shared-id' },
+      'customers.person',
+      context,
+    )
+    const orderResult = await applyResponseEnricherToRecord(
+      { id: 'shared-id' },
+      'sales.order',
+      context,
+    )
+
+    expect(personResult.record).toMatchObject({ enrichedFrom: 'customers.person' })
+    expect(orderResult.record).toMatchObject({ enrichedFrom: 'sales.order' })
+    expect(enrichOne).toHaveBeenCalledTimes(2)
+    expect(Array.from(cacheEntries.keys())).toEqual([
+      expect.stringContaining('entity:customers.person'),
+      expect.stringContaining('entity:sales.order'),
+    ])
+  })
+})

package/src/lib/crud/enricher-registry.ts

@@ -87,7 +87,8 @@ export function getEnrichersForEntity(
   selector?: EnricherSurfaceSelector,
 ): EnricherRegistryEntry[] {
   const entityEntries = getResponseEnrichers().filter(
-    (entry) => entry.enricher.targetEntity === targetEntity,
+    (entry) =>
+      entry.enricher.targetEntity === targetEntity || entry.enricher.targetEntity === '*',
   )
 
   if (!selector || selector.surface === 'api-response') {