@open-mercato/shared 0.6.3-develop.3876.1.d40fe4ec2d → 0.6.3-develop.3894.1.352abf4240

package/src/lib/crud/custom-fields.ts

@@ -337,24 +337,113 @@ function selectDefinitionForRecord(
   return sortDefinitionSummaries(defs)[0] ?? null
 }
 
-export async function loadCustomFieldDefinitionIndex(opts: {
+type LoadCustomFieldDefinitionIndexOptions = {
   em: EntityManager
   entityIds: string | string[]
   tenantId?: string | null | undefined
   organizationIds?: Array<string | null | undefined> | null
   fieldset?: string | string[] | null
-}): Promise<CustomFieldDefinitionIndex> {
-  const list = Array.isArray(opts.entityIds) ? opts.entityIds : [opts.entityIds]
-  const entityIds = list
-    .map((id) => (typeof id === 'string' ? id.trim() : String(id ?? '')))
-    .filter((id) => id.length > 0)
-  if (!entityIds.length) return new Map()
+}
+
+type CustomFieldDefIndexCache = {
+  get(key: string): Promise<unknown> | unknown
+  set(key: string, value: unknown, opts?: { ttl?: number; tags?: string[] }): Promise<unknown> | unknown
+  deleteByTags?(tags: string[]): Promise<number> | number
+}
+
+const CF_DEF_INDEX_CACHE_KEY_PREFIX = 'crud:cf-def-index'
+// Phase 2 default-off: integration runs observed `/api/customers/people`
+// returning 500 with this cache path active, and the readiness-probe
+// timeout blocked artifact upload so the direct stack trace was lost.
+// Until cross-request safety of the SQLite-cache JSON round-trip is
+// re-verified, ship with the layer disabled. Set
+// `OM_CF_DEF_CACHE_TTL_MS=300000` (or any positive integer) to opt in.
+const CF_DEF_INDEX_DEFAULT_TTL_MS = 0
+
+function resolveCfDefIndexCacheTtlMs(): number {
+  const raw = process.env.OM_CF_DEF_CACHE_TTL_MS
+  if (raw === undefined) return CF_DEF_INDEX_DEFAULT_TTL_MS
+  const parsed = Number(raw)
+  if (!Number.isFinite(parsed) || parsed < 0) return CF_DEF_INDEX_DEFAULT_TTL_MS
+  return parsed
+}
+
+function buildCfDefIndexCacheKey(opts: {
+  tenantId: string | null
+  entityIds: string[]
+  organizationIds: string[]
+  fieldsetKey: string | null
+}): string {
+  const tenant = opts.tenantId ?? 'global'
+  const entities = opts.entityIds.slice().sort().join('|')
+  const orgs = opts.organizationIds.length ? opts.organizationIds.slice().sort().join('|') : 'none'
+  const fieldset = opts.fieldsetKey ?? 'all'
+  return `${CF_DEF_INDEX_CACHE_KEY_PREFIX}:${tenant}:${entities}:${orgs}:${fieldset}`
+}
+
+function buildCfDefIndexCacheTags(opts: {
+  tenantId: string | null
+  entityIds: string[]
+}): string[] {
+  const tenant = opts.tenantId ?? 'global'
+  const tagBase = `entities:definitions:${tenant}`
+  const tags = new Set<string>([tagBase])
+  for (const entityId of opts.entityIds) {
+    tags.add(`${tagBase}:entity:${entityId}`)
+  }
+  return Array.from(tags)
+}
+
+function normalizeFieldsetKey(value: string | string[] | null | undefined): string | null {
+  if (!value) return null
+  if (Array.isArray(value)) {
+    const cleaned = value
+      .map((entry) => (typeof entry === 'string' ? entry.trim() : ''))
+      .filter((entry) => entry.length > 0)
+    if (!cleaned.length) return null
+    return cleaned.sort().join(',')
+  }
+  if (typeof value !== 'string') return null
+  const trimmed = value.trim()
+  return trimmed.length > 0 ? trimmed : null
+}
+
+function serializableIndexFromMap(index: CustomFieldDefinitionIndex): Array<[string, CustomFieldDefinitionSummary[]]> {
+  return Array.from(index.entries())
+}
+
+function indexMapFromSerializable(value: unknown): CustomFieldDefinitionIndex | null {
+  if (!Array.isArray(value)) return null
+  const map: CustomFieldDefinitionIndex = new Map()
+  for (const entry of value) {
+    if (!Array.isArray(entry) || entry.length !== 2) return null
+    const [key, summaries] = entry as [unknown, unknown]
+    if (typeof key !== 'string' || !Array.isArray(summaries)) return null
+    map.set(key, summaries as CustomFieldDefinitionSummary[])
+  }
+  return map
+}
+
+// Per-request micro-cache. Two CRUD calls within one HTTP request (rare but
+// possible via interceptors) share the same Map keyed by ctx-like objects.
+const requestScopedCfDefIndexCache = new WeakMap<object, Map<string, CustomFieldDefinitionIndex>>()
+
+export type CustomFieldDefinitionIndexCacheKey = string
+
+export function getRequestScopedCfDefIndexCache(scope: object): Map<string, CustomFieldDefinitionIndex> {
+  let bucket = requestScopedCfDefIndexCache.get(scope)
+  if (!bucket) {
+    bucket = new Map()
+    requestScopedCfDefIndexCache.set(scope, bucket)
+  }
+  return bucket
+}
+
+async function loadCustomFieldDefinitionIndexFresh(
+  opts: LoadCustomFieldDefinitionIndexOptions & { entityIds: string[]; orgCandidates: string[] }
+): Promise<CustomFieldDefinitionIndex> {
+  const { em, entityIds, orgCandidates } = opts
   const tenantId = opts.tenantId ?? null
-  const orgCandidates = Array.isArray(opts.organizationIds)
-    ? opts.organizationIds
-        .map((id) => (typeof id === 'string' ? id.trim() : id))
-        .filter((id): id is string => typeof id === 'string' && id.length > 0)
-    : []
   const scopeClauses: Record<string, unknown>[] = [
     tenantId
       ? { $or: [{ tenantId: tenantId as any }, { tenantId: null }] }
@@ -373,7 +462,7 @@ export async function loadCustomFieldDefinitionIndex(opts: {
     isActive: true,
     $and: scopeClauses,
   }
-  const defs = await opts.em.find(CustomFieldDef, where as any)
+  const defs = await em.find(CustomFieldDef, where as any)
   const fieldsetFilter = normalizeFieldsetFilter(opts.fieldset)
   const index: CustomFieldDefinitionIndex = new Map()
   defs.forEach((def) => {
@@ -406,6 +495,73 @@ export async function loadCustomFieldDefinitionIndex(opts: {
   return index
 }
 
+export async function loadCustomFieldDefinitionIndex(opts: LoadCustomFieldDefinitionIndexOptions & {
+  cache?: CustomFieldDefIndexCache | null
+  requestScope?: object | null
+}): Promise<CustomFieldDefinitionIndex> {
+  const list = Array.isArray(opts.entityIds) ? opts.entityIds : [opts.entityIds]
+  const entityIds = list
+    .map((id) => (typeof id === 'string' ? id.trim() : String(id ?? '')))
+    .filter((id) => id.length > 0)
+  if (!entityIds.length) return new Map()
+  const tenantId = opts.tenantId ?? null
+  const orgCandidates = Array.isArray(opts.organizationIds)
+    ? opts.organizationIds
+        .map((id) => (typeof id === 'string' ? id.trim() : id))
+        .filter((id): id is string => typeof id === 'string' && id.length > 0)
+    : []
+
+  const fieldsetKey = normalizeFieldsetKey(opts.fieldset)
+  const ttlMs = resolveCfDefIndexCacheTtlMs()
+  const cacheKey = buildCfDefIndexCacheKey({
+    tenantId,
+    entityIds,
+    organizationIds: orgCandidates,
+    fieldsetKey,
+  })
+
+  const requestBucket = opts.requestScope
+    ? getRequestScopedCfDefIndexCache(opts.requestScope)
+    : null
+  if (requestBucket) {
+    const cached = requestBucket.get(cacheKey)
+    if (cached) return cached
+  }
+
+  const sharedCache = ttlMs > 0 ? opts.cache ?? null : null
+  if (sharedCache && typeof sharedCache.get === 'function') {
+    try {
+      const cached = await sharedCache.get(cacheKey)
+      const restored = indexMapFromSerializable(cached)
+      if (restored) {
+        if (requestBucket) requestBucket.set(cacheKey, restored)
+        return restored
+      }
+    } catch (err) {
+      console.warn('[crud:cf-def-cache] read failed', err)
+    }
+  }
+
+  const index = await loadCustomFieldDefinitionIndexFresh({
+    ...opts,
+    entityIds,
+    orgCandidates,
+  })
+
+  if (sharedCache && typeof sharedCache.set === 'function') {
+    try {
+      await sharedCache.set(cacheKey, serializableIndexFromMap(index), {
+        ttl: ttlMs,
+        tags: buildCfDefIndexCacheTags({ tenantId, entityIds }),
+      })
+    } catch (err) {
+      console.warn('[crud:cf-def-cache] write failed', err)
+    }
+  }
+  if (requestBucket) requestBucket.set(cacheKey, index)
+  return index
+}
+
 export type ApplyCustomFieldsNormalizationOptions = {
   /**
    * When true, removes raw `cf_*` and `cf:*` keys from the record once they

package/src/lib/crud/factory.ts

@@ -38,6 +38,7 @@ import { CrudHttpError, isCrudHttpError } from './errors'
 import type { CommandBus, CommandLogMetadata } from '@open-mercato/shared/lib/commands'
 import type { EntityId } from '@open-mercato/shared/modules/entities'
 import type { EntityManager } from '@mikro-orm/postgresql'
+import type { CacheStrategy } from '@open-mercato/cache'
 import {
   buildCollectionTags,
   buildRecordTag,
@@ -637,7 +638,11 @@ function isUuid(v: any): v is string {
   return typeof v === 'string' && /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(v)
 }
 
-type AccessLogServiceLike = { log: (input: any) => Promise<unknown> | unknown }
+type AccessLogServiceLike = {
+  log: (input: any) => Promise<unknown> | unknown
+  logMany?: (inputs: any[]) => Promise<unknown> | unknown
+  flush?: () => Promise<void> | void
+}
 
 function resolveAccessLogService(container: AwilixContainer): AccessLogServiceLike | null {
   const registrations = (container as { registrations?: Record<string, unknown> }).registrations
@@ -654,6 +659,33 @@ function resolveAccessLogService(container: AwilixContainer): AccessLogServiceLi
   return null
 }
 
+function shouldBlockAccessLogWrites(): boolean {
+  return process.env.OM_CRUD_ACCESS_LOG_BLOCKING === '1'
+}
+
+// Module-level set of in-flight access-log writes started by the CRUD factory.
+// Sits alongside the same registry inside AccessLogService so callers without
+// the concrete service (or in tests with mocks) can still drain pending work
+// via `flushPendingCrudAccessLogs()`.
+const pendingCrudAccessLogPromises = new Set<Promise<unknown>>()
+
+function trackPendingCrudAccessLogPromise<T>(promise: Promise<T>): Promise<T> {
+  pendingCrudAccessLogPromises.add(promise as unknown as Promise<unknown>)
+  promise
+    .catch(() => undefined)
+    .finally(() => {
+      pendingCrudAccessLogPromises.delete(promise as unknown as Promise<unknown>)
+    })
+  return promise
+}
+
+export async function flushPendingCrudAccessLogs(): Promise<void> {
+  while (pendingCrudAccessLogPromises.size > 0) {
+    const snapshot = Array.from(pendingCrudAccessLogPromises)
+    await Promise.allSettled(snapshot)
+  }
+}
+
 function logForbidden(details: Record<string, unknown>) {
   try {
     // eslint-disable-next-line no-console
@@ -705,12 +737,18 @@ export type LogCrudAccessOptions = {
   fields?: string[]
 }
 
-export async function logCrudAccess(options: LogCrudAccessOptions) {
+export type LogCrudAccessResult = {
+  mode: 'batch' | 'fanout' | 'blocking' | 'skipped'
+  count: number
+  pending: number
+}
+
+export async function logCrudAccess(options: LogCrudAccessOptions): Promise<LogCrudAccessResult> {
   const { container, auth, request, items, resourceKind } = options
-  if (!auth) return
-  if (!Array.isArray(items) || items.length === 0) return
+  if (!auth) return { mode: 'skipped', count: 0, pending: pendingCrudAccessLogPromises.size }
+  if (!Array.isArray(items) || items.length === 0) return { mode: 'skipped', count: 0, pending: pendingCrudAccessLogPromises.size }
   const service = resolveAccessLogService(container)
-  if (!service) return
+  if (!service) return { mode: 'skipped', count: 0, pending: pendingCrudAccessLogPromises.size }
 
   const idField = options.idField || 'id'
   const tenantId = options.tenantId ?? auth.tenantId ?? null
@@ -736,7 +774,7 @@ export async function logCrudAccess(options: LogCrudAccessOptions) {
   }
 
   const uniqueIds = new Set<string>()
-  const tasks: Promise<unknown>[] = []
+  const payloads: Record<string, unknown>[] = []
   for (const item of items) {
     if (!item || typeof item !== 'object') continue
     const rawId = (item as any)[idField]
@@ -753,16 +791,41 @@ export async function logCrudAccess(options: LogCrudAccessOptions) {
     }
     if (fields.length > 0) payload.fields = fields
     if (Object.keys(context).length > 0) payload.context = context
-      tasks.push(
-        Promise.resolve(service.log(payload)).catch((err) => {
-          try {
-            console.error('[crud] failed to record access log', { err, payload })
-          } catch {}
-          return undefined
-        })
-      )
+    payloads.push(payload)
+  }
+  if (!payloads.length) return { mode: 'skipped', count: 0, pending: pendingCrudAccessLogPromises.size }
+
+  const blocking = shouldBlockAccessLogWrites()
+  const dispatchMode: 'batch' | 'fanout' = typeof service.logMany === 'function' ? 'batch' : 'fanout'
+  const writePromise = (async () => {
+    try {
+      if (typeof service.logMany === 'function') {
+        await service.logMany(payloads)
+      } else {
+        // Legacy fallback for service mocks/implementations without logMany.
+        await Promise.all(
+          payloads.map((payload) =>
+            Promise.resolve(service.log(payload)).catch((err) => {
+              try {
+                console.error('[crud] failed to record access log', { err, payload })
+              } catch {}
+              return undefined
+            }),
+          ),
+        )
+      }
+    } catch (err) {
+      try {
+        console.error('[crud] failed to record access logs (batch)', { err, count: payloads.length })
+      } catch {}
+    }
+  })()
+  trackPendingCrudAccessLogPromise(writePromise)
+  if (blocking) {
+    await writePromise
+    return { mode: 'blocking', count: payloads.length, pending: pendingCrudAccessLogPromises.size }
   }
-  if (tasks.length > 0) await Promise.all(tasks)
+  return { mode: dispatchMode, count: payloads.length, pending: pendingCrudAccessLogPromises.size }
 }
 
 type CrudCacheStoredValue = {
@@ -908,11 +971,17 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
         Array.isArray(ctx.organizationIds) && ctx.organizationIds.length
           ? ctx.organizationIds
           : [ctx.selectedOrganizationId ?? null]
+      let cfDefCache: CacheStrategy | null = null
+      try {
+        cfDefCache = ctx.container.resolve('cache') as CacheStrategy
+      } catch {}
       const definitionIndex = await loadCustomFieldDefinitionIndex({
         em,
         entityIds,
         tenantId: ctx.auth?.tenantId ?? null,
         organizationIds,
+        cache: cfDefCache ?? null,
+        requestScope: ctx,
       })
       cfProfiler.mark('definitions_loaded', { definitionCount: definitionIndex.size })
       const decoratedItems = items.map((raw) => {
@@ -954,6 +1023,36 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
     }
   }
 
+  // Phase 3 — per-request userFeatures memo. CrudCtx is a plain object that
+  // lives only for the duration of one HTTP request, so a WeakMap keyed on
+  // ctx is the right scope: interceptor + enricher + any future call site
+  // share one Promise<string[] | undefined> per request. The cache lifetime
+  // is bounded by the request and cannot desync from mid-request grant
+  // changes because RBAC grants never change mid-request.
+  const userFeaturesPromiseCache = new WeakMap<object, Promise<string[] | undefined>>()
+
+  function resolveUserFeaturesOnce(ctx: CrudCtx): Promise<string[] | undefined> {
+    if (!ctx.auth) return Promise.resolve(undefined)
+    const cached = userFeaturesPromiseCache.get(ctx)
+    if (cached) return cached
+    const promise = (async () => {
+      try {
+        const rbac = ctx.container.resolve('rbacService') as RbacServiceLike | undefined
+        if (rbac?.getGrantedFeatures) {
+          return await rbac.getGrantedFeatures(ctx.auth!.sub, {
+            tenantId: ctx.auth!.tenantId,
+            organizationId: ctx.selectedOrganizationId ?? ctx.auth!.orgId,
+          })
+        }
+      } catch {
+        // rbacService not available — enrichers without feature requirements still run
+      }
+      return undefined
+    })()
+    userFeaturesPromiseCache.set(ctx, promise)
+    return promise
+  }
+
   /**
    * Build enricher context from CRUD context and resolve user features for ACL gating.
    * Returns null if enrichers are not configured or auth is missing.
@@ -962,18 +1061,7 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
     if (!opts.enrichers?.entityId) return null
     if (!ctx.auth) return null
 
-    let userFeatures: string[] | undefined
-    try {
-      const rbac = ctx.container.resolve('rbacService') as RbacServiceLike | undefined
-      if (rbac?.getGrantedFeatures) {
-        userFeatures = await rbac.getGrantedFeatures(ctx.auth.sub, {
-          tenantId: ctx.auth.tenantId,
-          organizationId: ctx.selectedOrganizationId ?? ctx.auth.orgId,
-        })
-      }
-    } catch {
-      // rbacService not available — enrichers without feature requirements still run
-    }
+    const userFeatures = await resolveUserFeaturesOnce(ctx)
 
     return {
       organizationId: ctx.selectedOrganizationId ?? ctx.auth.orgId ?? '',
@@ -986,19 +1074,7 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
   }
 
   async function resolveUserFeatures(ctx: CrudCtx): Promise<string[] | undefined> {
-    if (!ctx.auth) return undefined
-    try {
-      const rbac = ctx.container.resolve('rbacService') as RbacServiceLike | undefined
-      if (rbac?.getGrantedFeatures) {
-        return await rbac.getGrantedFeatures(ctx.auth.sub, {
-          tenantId: ctx.auth.tenantId,
-          organizationId: ctx.selectedOrganizationId ?? ctx.auth.orgId,
-        })
-      }
-    } catch {
-      // rbacService is optional in some contexts
-    }
-    return undefined
+    return resolveUserFeaturesOnce(ctx)
   }
 
   const interceptorContextCache = new WeakMap<object, ReturnType<typeof buildInterceptorContextInner>>()
@@ -1514,7 +1590,7 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
           profiler.mark('translation_overlays_complete', { itemCount: transformedItems.length })
         }
 
-        await logCrudAccess({
+        const accessLogResult = await logCrudAccess({
           container: ctx.container,
           auth: ctx.auth,
           request,
@@ -1525,7 +1601,7 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
           tenantId: ctx.auth.tenantId ?? null,
           query: validated,
         })
-        profiler.mark('access_logged')
+        profiler.mark('access_logged', accessLogResult)
 
         if (exportRequested && requestedExport) {
           const total = typeof res.total === 'number' ? res.total : rawItems.length
@@ -1746,7 +1822,7 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
         profiler.mark('fallback_translation_overlays_complete', { itemCount: Array.isArray(list) ? list.length : 0 })
       }
 
-      await logCrudAccess({
+      const accessLogResult = await logCrudAccess({
         container: ctx.container,
         auth: ctx.auth,
         request,
@@ -1757,7 +1833,7 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
         tenantId: ctx.auth.tenantId ?? null,
         query: validated,
       })
-      profiler.mark('access_logged')
+      profiler.mark('access_logged', accessLogResult)
       if (exportRequested && requestedExport) {
         const exportItems = exportFullRequested ? list.map(normalizeFullRecordForExport) : list
         const prepared = exportFullRequested

package/src/lib/di/__tests__/bootstrap-cache.test.ts

@@ -0,0 +1,182 @@
+// Unit tests for the Phase 5 process-scoped bootstrap once-guard.
+//
+// The once-guard caches `cache`, `eventBus`, `kmsService`, etc. on
+// `globalThis` after the first `createRequestContainer()` call so that
+// subsequent calls in the same process re-register those services
+// directly without re-importing `@open-mercato/core/bootstrap`.
+// `registerDiRegistrars` clears the cache so HMR sees fresh subscribers.
+// `OM_BOOTSTRAP_CACHE` gates the whole behavior; default OFF.
+
+import { asValue } from 'awilix'
+
+// Mock the deep ORM/engine imports BEFORE importing container.ts so we can
+// exercise the bootstrap once-guard without pulling in MikroORM decorators.
+jest.mock(
+  '@open-mercato/shared/lib/db/mikro',
+  () => {
+    const baseEm: any = {
+      fork: () => baseEm,
+      getRepository: () => ({ find: async () => [], findOne: async () => null }),
+    }
+    return {
+      __esModule: true,
+      getOrm: async () => ({ em: baseEm }),
+      getOrmEntities: () => [],
+      registerOrmEntities: () => {},
+    }
+  },
+  { virtual: false },
+)
+
+jest.mock(
+  '@mikro-orm/core',
+  () => ({
+    __esModule: true,
+    RequestContext: { getEntityManager: () => null },
+  }),
+  { virtual: true },
+)
+
+jest.mock(
+  '@open-mercato/shared/lib/query/engine',
+  () => ({ __esModule: true, BasicQueryEngine: class {} }),
+  { virtual: false },
+)
+
+jest.mock(
+  '@open-mercato/shared/lib/data/engine',
+  () => ({ __esModule: true, DefaultDataEngine: class {} }),
+  { virtual: false },
+)
+
+jest.mock(
+  '@open-mercato/shared/lib/commands',
+  () => ({
+    __esModule: true,
+    commandRegistry: {},
+    CommandBus: class { constructor() {} },
+  }),
+  { virtual: false },
+)
+
+jest.mock(
+  '@open-mercato/shared/modules/overrides',
+  () => ({
+    __esModule: true,
+    applyDiOverridesToContainer: () => {},
+  }),
+  { virtual: false },
+)
+
+const {
+  registerDiRegistrars,
+  resetBootstrapCache,
+} = require('@open-mercato/shared/lib/di/container')
+
+const bootstrapMock = jest.fn(async (container: any) => {
+  container.register({
+    cache: asValue({ __value: 'cache-value' }),
+    eventBus: asValue({ __value: 'event-bus-value' }),
+    tenantEncryptionService: asValue({ isEnabled: () => true, __value: 'enc' }),
+  })
+})
+
+jest.mock(
+  '@open-mercato/core/bootstrap',
+  () => ({
+    __esModule: true,
+    bootstrap: (...args: unknown[]) => bootstrapMock(...args as [any]),
+  }),
+  { virtual: true },
+)
+
+const subscriberRegistered = jest.fn()
+jest.mock(
+  '@open-mercato/shared/lib/encryption/subscriber',
+  () => ({
+    __esModule: true,
+    registerTenantEncryptionSubscriber: (...args: unknown[]) => subscriberRegistered(...args),
+  }),
+  { virtual: true },
+)
+
+const ORIGINAL_FLAG = process.env.OM_BOOTSTRAP_CACHE
+
+describe('bootstrap once-guard cache', () => {
+  beforeEach(() => {
+    resetBootstrapCache()
+    bootstrapMock.mockClear()
+    subscriberRegistered.mockClear()
+    registerDiRegistrars([])
+  })
+
+  afterAll(() => {
+    if (ORIGINAL_FLAG === undefined) delete process.env.OM_BOOTSTRAP_CACHE
+    else process.env.OM_BOOTSTRAP_CACHE = ORIGINAL_FLAG
+  })
+
+  it('resetBootstrapCache clears the process-scoped bootstrap cache and encryption flag', () => {
+    const g = globalThis as Record<string, unknown>
+    g.__openMercatoBootstrapCache__ = { cache: { tag: 'memo' } }
+    g.__openMercatoEncryptionEnabledCache__ = true
+    resetBootstrapCache()
+    expect(g.__openMercatoBootstrapCache__).toBeNull()
+    expect(g.__openMercatoEncryptionEnabledCache__).toBeUndefined()
+  })
+
+  it('runs bootstrap() on the first createRequestContainer() and replays cached services on the second when OM_BOOTSTRAP_CACHE=1', async () => {
+    process.env.OM_BOOTSTRAP_CACHE = '1'
+    const { createRequestContainer } = await import('@open-mercato/shared/lib/di/container')
+    const first = await createRequestContainer()
+    expect(bootstrapMock).toHaveBeenCalledTimes(1)
+    expect(first.resolve('cache')).toMatchObject({ __value: 'cache-value' })
+
+    const second = await createRequestContainer()
+    // Bootstrap MUST NOT run again — the cached entries are replayed.
+    expect(bootstrapMock).toHaveBeenCalledTimes(1)
+    expect(second.resolve('cache')).toMatchObject({ __value: 'cache-value' })
+    expect(second.resolve('eventBus')).toMatchObject({ __value: 'event-bus-value' })
+  })
+
+  it('runs bootstrap() on every createRequestContainer() when OM_BOOTSTRAP_CACHE is unset (default)', async () => {
+    delete process.env.OM_BOOTSTRAP_CACHE
+    const { createRequestContainer } = await import('@open-mercato/shared/lib/di/container')
+    await createRequestContainer()
+    await createRequestContainer()
+    expect(bootstrapMock).toHaveBeenCalledTimes(2)
+  })
+
+  it('registerDiRegistrars clears the cache so HMR re-runs bootstrap on the next request', async () => {
+    process.env.OM_BOOTSTRAP_CACHE = '1'
+    const { createRequestContainer } = await import('@open-mercato/shared/lib/di/container')
+    await createRequestContainer()
+    expect(bootstrapMock).toHaveBeenCalledTimes(1)
+    registerDiRegistrars([])
+    await createRequestContainer()
+    expect(bootstrapMock).toHaveBeenCalledTimes(2)
+  })
+
+  it('memoizes tenantEncryptionService.isEnabled() across requests', async () => {
+    process.env.OM_BOOTSTRAP_CACHE = '1'
+    let isEnabledCalls = 0
+    bootstrapMock.mockImplementationOnce(async (container: any) => {
+      container.register({
+        cache: asValue({ __value: 'cache-value' }),
+        eventBus: asValue({ __value: 'event-bus-value' }),
+        tenantEncryptionService: asValue({
+          isEnabled: () => {
+            isEnabledCalls += 1
+            return true
+          },
+        }),
+      })
+    })
+    const { createRequestContainer } = await import('@open-mercato/shared/lib/di/container')
+    await createRequestContainer()
+    await createRequestContainer()
+    await createRequestContainer()
+    // Called once during the first bootstrap, then cached on globalThis.
+    expect(isEnabledCalls).toBe(1)
+    expect(subscriberRegistered).toHaveBeenCalledTimes(3)
+  })
+})