@open-mercato/shared 0.6.7 → 0.6.8-develop.6874.1.982d6097d8

package/src/lib/crud/interceptor-runner.ts

@@ -6,7 +6,7 @@ import type {
   InterceptorBeforeResult,
 } from './api-interceptor'
 import { getApiInterceptorsForRoute } from './interceptor-registry'
-import { hasAllFeatures } from '../../security/features'
+import { authorizeFeatures } from '../../security/featurePolicy'
 import { logInterceptorActivity } from '../umes/interceptor-activity'
 
 const DEFAULT_TIMEOUT_MS = 5000
@@ -39,7 +39,7 @@ function sanitizeObject(input?: Record<string, unknown>): Record<string, unknown
 }
 
 function hasRequiredFeatures(features: string[] | undefined, userFeatures: string[] | undefined): boolean {
-  return hasAllFeatures(userFeatures, features)
+  return authorizeFeatures(features ?? [], { grantedFeatures: userFeatures ?? [] })
 }
 
 function timeoutPromise(ms: number, interceptorId: string): Promise<never> {

package/src/lib/crud/mutation-guard-registry.ts

@@ -1,5 +1,5 @@
 import type { AwilixContainer } from 'awilix'
-import { hasAllFeatures } from '../../security/features'
+import { authorizeFeatures } from '../../security/featurePolicy'
 import { resolveCrudMutationGuardService } from './mutation-guard-service'
 
 // ---------------------------------------------------------------------------
@@ -101,7 +101,7 @@ export async function runMutationGuards(
   const matching = guards
     .filter((g) => matchesEntity(g.targetEntity, input.resourceKind))
     .filter((g) => g.operations.includes(input.operation))
-    .filter((g) => hasAllFeatures(context.userFeatures, g.features))
+    .filter((g) => authorizeFeatures(g.features ?? [], { grantedFeatures: context.userFeatures }))
     .sort((a, b) => (a.priority ?? 50) - (b.priority ?? 50))
 
   let payload = input.mutationPayload

package/src/lib/crud/types.ts

@@ -1,5 +1,8 @@
 export type CrudEventAction = 'created' | 'updated' | 'deleted'
 
+/** Internal payload marker: the data engine owns this CRUD event's query-index decision. */
+export const CRUD_QUERY_INDEX_MANAGED_PAYLOAD_KEY = '__omQueryIndexManaged' as const
+
 export type CrudEntityIdentifiers = {
   id: string
   organizationId: string | null

package/src/lib/data/__tests__/consistency.test.ts

@@ -0,0 +1,38 @@
+import {
+  __resetAlwaysConsistentCacheForTests,
+  isReadProjectionAlwaysConsistent,
+  parseAlwaysConsistentEnv,
+} from '../consistency'
+
+describe('read projection consistency flag', () => {
+  const originalEnv = process.env.OM_CACHE_SAFETY_ALWAYS_CONSISTENT
+
+  afterEach(() => {
+    if (originalEnv === undefined) {
+      delete process.env.OM_CACHE_SAFETY_ALWAYS_CONSISTENT
+    } else {
+      process.env.OM_CACHE_SAFETY_ALWAYS_CONSISTENT = originalEnv
+    }
+    __resetAlwaysConsistentCacheForTests()
+  })
+
+  it.each([undefined, null, '', ' ', 'off', 'false', '0', 'no', 'disabled', 'none', 'unexpected'])(
+    'parses %p as OFF',
+    (raw) => {
+      expect(parseAlwaysConsistentEnv(raw)).toBe(false)
+    },
+  )
+
+  it.each(['on', 'true', '1', 'yes', 'enabled'])('parses %p as ON', (raw) => {
+    expect(parseAlwaysConsistentEnv(raw)).toBe(true)
+  })
+
+  it('memoizes the env value until reset for tests', () => {
+    process.env.OM_CACHE_SAFETY_ALWAYS_CONSISTENT = 'on'
+    expect(isReadProjectionAlwaysConsistent()).toBe(true)
+    process.env.OM_CACHE_SAFETY_ALWAYS_CONSISTENT = 'off'
+    expect(isReadProjectionAlwaysConsistent()).toBe(true)
+    __resetAlwaysConsistentCacheForTests()
+    expect(isReadProjectionAlwaysConsistent()).toBe(false)
+  })
+})

package/src/lib/data/__tests__/engine.bulk-suppress.test.ts

@@ -1,7 +1,11 @@
 import type { AwilixContainer } from 'awilix'
 import type { EntityManager } from '@mikro-orm/postgresql'
 import { DefaultDataEngine } from '../engine'
-import type { CrudEventsConfig, CrudIndexerConfig } from '../../crud/types'
+import {
+  CRUD_QUERY_INDEX_MANAGED_PAYLOAD_KEY,
+  type CrudEventsConfig,
+  type CrudIndexerConfig,
+} from '../../crud/types'
 
 // The bulk-import deferral (`suppress`) must gate the two per-record side effects `emitOrmEntityEvent`
 // fans out — the `<module>.<entity>.<action>` domain event and the inline `query_index.upsert_one`
@@ -25,6 +29,15 @@ function buildEngine() {
   return { engine, emitEvent, emittedNames }
 }
 
+function expectManagedDomainPayload(emitEvent: jest.Mock, eventName: string): void {
+  const call = emitEvent.mock.calls.find(([name]) => name === eventName)
+  expect(call).toBeDefined()
+  const payload = call?.[1] as Record<string, unknown>
+  expect(payload[CRUD_QUERY_INDEX_MANAGED_PAYLOAD_KEY]).toBe(true)
+  expect(Object.keys(payload)).not.toContain(CRUD_QUERY_INDEX_MANAGED_PAYLOAD_KEY)
+  expect(JSON.stringify(payload)).not.toContain(CRUD_QUERY_INDEX_MANAGED_PAYLOAD_KEY)
+}
+
 describe('DefaultDataEngine bulk-import suppression', () => {
   // The test events are intentionally not registered in the event registry; silence the
   // one-time "undeclared event" warning so it doesn't clutter the suite output.
@@ -33,9 +46,10 @@ describe('DefaultDataEngine bulk-import suppression', () => {
   afterAll(() => { warnSpy.mockRestore() })
 
   it('emits both the domain event and the reindex when unsuppressed', async () => {
-    const { engine, emittedNames } = buildEngine()
+    const { engine, emitEvent, emittedNames } = buildEngine()
     await engine.emitOrmEntityEvent({ action: 'created', entity: {}, events: EVENTS, indexer: INDEXER, identifiers: IDENTIFIERS })
     expect(emittedNames()).toEqual(expect.arrayContaining(['sales.order.created', 'query_index.upsert_one']))
+    expectManagedDomainPayload(emitEvent, 'sales.order.created')
   })
 
   it('skips the domain event but keeps the reindex with skipEvents', async () => {
@@ -47,11 +61,12 @@ describe('DefaultDataEngine bulk-import suppression', () => {
   })
 
   it('skips the reindex but keeps the domain event with skipReindex', async () => {
-    const { engine, emittedNames } = buildEngine()
+    const { engine, emitEvent, emittedNames } = buildEngine()
     await engine.emitOrmEntityEvent({ action: 'created', entity: {}, events: EVENTS, indexer: INDEXER, identifiers: IDENTIFIERS, suppress: { skipReindex: true } })
     const names = emittedNames()
     expect(names).toContain('sales.order.created')
     expect(names).not.toContain('query_index.upsert_one')
+    expectManagedDomainPayload(emitEvent, 'sales.order.created')
   })
 
   it('emits nothing when both are suppressed', async () => {

package/src/lib/data/consistency.ts

@@ -0,0 +1,17 @@
+import { parseBooleanWithDefault } from '../boolean'
+
+let alwaysConsistentFlag: boolean | null = null
+
+export function parseAlwaysConsistentEnv(raw: string | undefined | null): boolean {
+  return parseBooleanWithDefault(raw, false)
+}
+
+export function isReadProjectionAlwaysConsistent(): boolean {
+  if (alwaysConsistentFlag !== null) return alwaysConsistentFlag
+  alwaysConsistentFlag = parseAlwaysConsistentEnv(process.env.OM_CACHE_SAFETY_ALWAYS_CONSISTENT)
+  return alwaysConsistentFlag
+}
+
+export function __resetAlwaysConsistentCacheForTests(): void {
+  alwaysConsistentFlag = null
+}

package/src/lib/data/engine.ts

@@ -6,11 +6,12 @@ import { setRecordCustomFields } from '@open-mercato/core/modules/entities/lib/h
 import { validateCustomFieldValuesServer } from '@open-mercato/core/modules/entities/lib/validation'
 import { sanitizeCustomFieldHtmlRichTextValuesServer } from '@open-mercato/core/modules/entities/lib/htmlRichTextSanitizer'
 import type { EventBus } from '@open-mercato/events/types'
-import type {
-  CrudEventAction,
-  CrudEventsConfig,
-  CrudIndexerConfig,
-  CrudEntityIdentifiers,
+import {
+  CRUD_QUERY_INDEX_MANAGED_PAYLOAD_KEY,
+  type CrudEventAction,
+  type CrudEventsConfig,
+  type CrudIndexerConfig,
+  type CrudEntityIdentifiers,
 } from '../crud/types'
 import type { BulkImportSuppression } from '../commands/types'
 import { CrudHttpError } from '../crud/errors'
@@ -18,6 +19,7 @@ import { resolveRegisteredEntityTableName } from '../query/engine'
 import { getEntityIds } from '../encryption/entityIds'
 import { normalizeCustomFieldValues } from '../custom-fields/normalize'
 import { parseBooleanToken } from '../boolean'
+import { isReadProjectionAlwaysConsistent } from './consistency'
 import { isEventDeclared } from '../../modules/events'
 import { createLogger } from '../logger'
 
@@ -598,7 +600,7 @@ export class DefaultDataEngine implements DataEngine {
     if (events && !suppress?.skipEvents) {
       const eventName = `${events.module}.${events.entity}.${action}`
       warnIfUndeclaredEvent(eventName, 'emitOrmEntityEvent')
-      const payload = events.buildPayload
+      const builtPayload = events.buildPayload
         ? events.buildPayload(ctx)
         : {
             id: ctx.identifiers.id,
@@ -606,6 +608,20 @@ export class DefaultDataEngine implements DataEngine {
             tenantId: ctx.identifiers.tenantId,
             ...(ctx.syncOrigin ? { syncOrigin: ctx.syncOrigin } : {}),
           }
+      // A configured indexer means this data-engine call owns the query-index
+      // decision, including an explicit skipReindex suppression. Mark object
+      // payloads so the legacy domain-event bridge does not enqueue the same
+      // record a second time. Keep the marker non-enumerable so client broadcasts
+      // and persisted domain payloads retain their existing public shape.
+      // Primitive custom payloads cannot be bridged in any case because they do
+      // not expose the record id.
+      const payload = indexer && builtPayload && typeof builtPayload === 'object' && !Array.isArray(builtPayload)
+        ? Object.defineProperty(
+            { ...(builtPayload as Record<string, unknown>) },
+            CRUD_QUERY_INDEX_MANAGED_PAYLOAD_KEY,
+            { value: true, enumerable: false },
+          )
+        : builtPayload
       try {
         await bus.emitEvent(eventName, payload, {
           persistent: !!events.persistent,
@@ -618,6 +634,7 @@ export class DefaultDataEngine implements DataEngine {
     }
 
     if (indexer && !suppress?.skipReindex) {
+      const alwaysConsistent = isReadProjectionAlwaysConsistent()
       const resolveCoverageBaseDelta = (): number | undefined => {
         if (action === 'created') return 1
         if (action === 'deleted') return -1
@@ -643,9 +660,14 @@ export class DefaultDataEngine implements DataEngine {
         // returns. The subscriber removes the projection row + tokens synchronously and
         // defers the coverage recompute + fulltext delete, so this stays bounded.
         // Errors are logged, not thrown — index drift never fails the originating write.
-        await bus.emitEvent('query_index.delete_one', enrichedPayload).catch((err: unknown) => {
-          logger.error('query_index.delete_one emit failed', { err })
-        })
+        // Always-consistent mode rethrows so drift is loud and retryable.
+        if (alwaysConsistent) {
+          await bus.emitEvent('query_index.delete_one', enrichedPayload, { rethrowHandlerErrors: true })
+        } else {
+          await bus.emitEvent('query_index.delete_one', enrichedPayload).catch((err: unknown) => {
+            logger.error('query_index.delete_one emit failed', { err })
+          })
+        }
       } else {
         const payload = indexer.buildUpsertPayload
           ? indexer.buildUpsertPayload(ctx)
@@ -663,18 +685,27 @@ export class DefaultDataEngine implements DataEngine {
         // (see delete_one above). The subscriber updates `entity_indexes` synchronously
         // and defers the heavy token-reindex pipeline (build doc + encrypt + decrypt +
         // tokenize + DELETE + chunked INSERT) so write latency stays bounded.
-        await bus.emitEvent('query_index.upsert_one', enrichedPayload).catch((err: unknown) => {
-          logger.error('query_index.upsert_one emit failed', { err })
-        })
+        if (alwaysConsistent) {
+          await bus.emitEvent('query_index.upsert_one', enrichedPayload, { rethrowHandlerErrors: true })
+        } else {
+          await bus.emitEvent('query_index.upsert_one', enrichedPayload).catch((err: unknown) => {
+            logger.error('query_index.upsert_one emit failed', { err })
+          })
+        }
       }
 
-      if (shouldTriggerCoverageRefresh(indexer.entityType, ctx.identifiers.tenantId ?? null)) {
-        void bus.emitEvent('query_index.coverage.refresh', {
+      if (alwaysConsistent || shouldTriggerCoverageRefresh(indexer.entityType, ctx.identifiers.tenantId ?? null)) {
+        const coveragePayload = {
           entityType: indexer.entityType,
           tenantId: ctx.identifiers.tenantId ?? null,
           organizationId: null,
           delayMs: 0,
-        }).catch(() => undefined)
+        }
+        if (alwaysConsistent) {
+          await bus.emitEvent('query_index.coverage.refresh', coveragePayload, { rethrowHandlerErrors: true })
+        } else {
+          void bus.emitEvent('query_index.coverage.refresh', coveragePayload).catch(() => undefined)
+        }
       }
     }
   }
@@ -739,7 +770,10 @@ export class DefaultDataEngine implements DataEngine {
           indexer: entry.indexer as CrudIndexerConfig<unknown>,
           suppress,
         })
-      } catch {
+      } catch (error) {
+        if (isReadProjectionAlwaysConsistent()) {
+          throw error
+        }
         // best-effort; continue with remaining side effects
       }
     }

package/src/lib/db/__tests__/entityMetadata.test.ts

@@ -0,0 +1,38 @@
+import { listEntityMetadata, listEntityMetadataFromRegistry } from '../entityMetadata'
+
+const personMeta = { className: 'Person', tableName: 'people' }
+const orderMeta = { className: 'Order', tableName: 'orders' }
+
+describe('listEntityMetadataFromRegistry', () => {
+  it('reads the MikroORM v7 Map returned by getAll()', () => {
+    const registry = { getAll: () => new Map([[Object, personMeta], [Array, orderMeta]]) }
+    expect(listEntityMetadataFromRegistry(registry)).toEqual([personMeta, orderMeta])
+  })
+
+  it('reads the MikroORM v6 dictionary returned by getAll()', () => {
+    const registry = { getAll: () => ({ Person: personMeta, Order: orderMeta }) }
+    expect(listEntityMetadataFromRegistry(registry)).toEqual([personMeta, orderMeta])
+  })
+
+  it('falls back to the metadata property when getAll() yields nothing', () => {
+    const registry = { getAll: () => new Map(), metadata: { Person: personMeta } }
+    expect(listEntityMetadataFromRegistry(registry)).toEqual([personMeta])
+  })
+
+  it('returns an empty array for a missing registry', () => {
+    expect(listEntityMetadataFromRegistry(null)).toEqual([])
+    expect(listEntityMetadataFromRegistry({})).toEqual([])
+  })
+})
+
+describe('listEntityMetadata', () => {
+  it('resolves the registry through getMetadata()', () => {
+    const em = { getMetadata: () => ({ getAll: () => new Map([[Object, personMeta]]) }) }
+    expect(listEntityMetadata(em)).toEqual([personMeta])
+  })
+
+  it('returns an empty array when the source exposes no registry', () => {
+    expect(listEntityMetadata({})).toEqual([])
+    expect(listEntityMetadata(undefined)).toEqual([])
+  })
+})

package/src/lib/db/__tests__/pg-errors.test.ts

@@ -0,0 +1,48 @@
+import { isTransientDbError, isUniqueViolation } from '../pg-errors'
+
+describe('isTransientDbError', () => {
+  it('is true for the max_connections SQLSTATE', () => {
+    expect(isTransientDbError({ code: '53300' })).toBe(true)
+  })
+
+  it('is true for connection-family SQLSTATEs', () => {
+    for (const code of ['53400', '57P01', '57P02', '57P03', '08000', '08001', '08003', '08006']) {
+      expect(isTransientDbError({ code })).toBe(true)
+    }
+  })
+
+  it('is true for driver/ORM-wrapped connection messages that drop the SQLSTATE', () => {
+    expect(isTransientDbError(new Error('sorry, too many clients already'))).toBe(true)
+    expect(isTransientDbError(new Error('Knex: Timeout acquiring a connection. The pool is probably full.'))).toBe(true)
+    expect(isTransientDbError(new Error('Unable to acquire a connection'))).toBe(true)
+    expect(isTransientDbError(new Error('Connection terminated unexpectedly'))).toBe(true)
+    expect(isTransientDbError(new Error('the database system is starting up'))).toBe(true)
+  })
+
+  it('is false for bare socket errors with no Postgres signal (avoids false positives)', () => {
+    // Generic socket failures can come from any outbound connection (HTTP, cache,
+    // queue), so they must NOT be attributed to the database.
+    expect(isTransientDbError({ code: 'ECONNREFUSED' })).toBe(false)
+    expect(isTransientDbError({ code: 'ETIMEDOUT' })).toBe(false)
+    expect(isTransientDbError(Object.assign(new Error('read ECONNRESET'), { code: 'ECONNRESET' }))).toBe(false)
+  })
+
+  it('is false for a unique violation and other query-level errors', () => {
+    expect(isTransientDbError({ code: '23505' })).toBe(false)
+    expect(isTransientDbError({ code: '40P01' })).toBe(false) // deadlock — not a connection failure
+    expect(isTransientDbError({ code: '40001' })).toBe(false) // serialization — not a connection failure
+  })
+
+  it('is false for non-DB and empty errors', () => {
+    expect(isTransientDbError(new Error('something unrelated broke'))).toBe(false)
+    expect(isTransientDbError(null)).toBe(false)
+    expect(isTransientDbError(undefined)).toBe(false)
+    expect(isTransientDbError('a string')).toBe(false)
+  })
+
+  it('does not overlap with isUniqueViolation', () => {
+    const uniqueErr = { code: '23505', message: 'duplicate key value violates unique constraint' }
+    expect(isUniqueViolation(uniqueErr)).toBe(true)
+    expect(isTransientDbError(uniqueErr)).toBe(false)
+  })
+})

package/src/lib/db/entityMetadata.ts

@@ -0,0 +1,43 @@
+import type { EntityMetadata } from '@mikro-orm/core'
+
+type MetadataRegistryLike = {
+  getAll?: () => unknown
+  metadata?: unknown
+}
+
+type MetadataHolder = {
+  getMetadata?: () => unknown
+}
+
+/**
+ * MikroORM v7 returns a `Map` from `MetadataStorage.getAll()`; v6 returned a plain
+ * dictionary. `Object.values(someMap)` evaluates to `[]`, so a v6-era read of the
+ * registry silently reports zero entities instead of failing loudly.
+ */
+function toMetadataList(value: unknown): EntityMetadata[] {
+  if (!value) return []
+  if (value instanceof Map) return Array.from(value.values()) as EntityMetadata[]
+  if (Array.isArray(value)) return value as EntityMetadata[]
+  if (typeof value === 'object') return Object.values(value as Record<string, EntityMetadata>)
+  return []
+}
+
+export function listEntityMetadataFromRegistry(registry: unknown): EntityMetadata[] {
+  const source = registry as MetadataRegistryLike | null | undefined
+  if (!source) return []
+  if (typeof source.getAll === 'function') {
+    const entries = toMetadataList(source.getAll())
+    if (entries.length) return entries
+  }
+  return toMetadataList(source.metadata)
+}
+
+/**
+ * List every discovered entity metadata from an `EntityManager` or `MikroORM` instance.
+ * Returns an empty array when the source exposes no metadata registry.
+ */
+export function listEntityMetadata(source: unknown): EntityMetadata[] {
+  const holder = source as MetadataHolder | null | undefined
+  if (!holder || typeof holder.getMetadata !== 'function') return []
+  return listEntityMetadataFromRegistry(holder.getMetadata())
+}

package/src/lib/db/pg-errors.ts

@@ -10,3 +10,61 @@ export function isUniqueViolation(err: unknown): boolean {
   const message = (err as { message?: string }).message
   return typeof message === 'string' && /duplicate key value|unique constraint/i.test(message)
 }
+
+/**
+ * Postgres SQLSTATEs for transient connection / availability failures — the
+ * database (or its connection pool) is temporarily unreachable and the request
+ * can succeed on retry. Deliberately scoped to connection/availability codes;
+ * query-level conflicts (deadlock 40P01, serialization 40001, lock_not_available
+ * 55P03) are NOT included because they do not mean "service unavailable".
+ */
+const TRANSIENT_CONNECTION_SQLSTATES = new Set([
+  '53300', // too_many_connections
+  '53400', // configuration_limit_exceeded
+  '57P01', // admin_shutdown
+  '57P02', // crash_shutdown
+  '57P03', // cannot_connect_now (db starting up)
+  '08000', // connection_exception
+  '08001', // sqlclient_unable_to_establish_sqlconnection
+  '08003', // connection_does_not_exist
+  '08006', // connection_failure
+])
+
+/**
+ * Postgres-driver / connection-pool messages that describe a transient DB
+ * connection failure when the SQLSTATE is dropped by the ORM wrapper. These are
+ * intentionally DB-specific phrases only. Bare socket codes (ECONNREFUSED,
+ * ETIMEDOUT, …) are deliberately NOT matched: they can originate from any
+ * outbound socket (HTTP, cache, queue), so keying off them would falsely
+ * attribute unrelated failures to the database.
+ */
+const TRANSIENT_DB_MESSAGE_PATTERNS = [
+  /too many clients already/i,
+  /unable to acquire a connection/i,
+  /timeout acquiring a connection/i,
+  /connection terminated/i,
+  /the database system is (starting up|shutting down|in recovery)/i,
+]
+
+/**
+ * Detect a transient Postgres connection / availability failure (pool exhaustion,
+ * `max_connections` reached, DB restarting) via its SQLSTATE or a DB-specific
+ * driver message. Gates retryable 503 responses so callers do not report a
+ * temporary infrastructure blip as an auth failure (401) or an unexpected server
+ * error (500). Scoped to unambiguous DB signals so generic socket errors from
+ * non-DB calls are never misclassified.
+ */
+export function isTransientDbError(err: unknown): boolean {
+  if (!err || typeof err !== 'object') {
+    return false
+  }
+  const code = (err as { code?: string }).code
+  if (typeof code === 'string' && TRANSIENT_CONNECTION_SQLSTATES.has(code)) {
+    return true
+  }
+  const message = (err as { message?: string }).message
+  if (typeof message === 'string' && TRANSIENT_DB_MESSAGE_PATTERNS.some((pattern) => pattern.test(message))) {
+    return true
+  }
+  return false
+}

package/src/lib/di/__tests__/container-app-di-absent.test.ts

@@ -0,0 +1,155 @@
+// The app-level DI override module (`@/di`) is OPTIONAL: most apps ship no
+// src/di.ts, and packages contexts cannot resolve the alias at all. Its
+// absence must not produce warnings — only real load/register failures do
+// (covered in container-app-di.test.ts). This file deliberately does NOT
+// mock '@/di', so the import fails with module-not-found, exercising the
+// quiet branch.
+
+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 },
+)
+
+// Keep this suite hermetic: without this mock the REAL core bootstrap module
+// loads (and runs its module-level side effects) whenever generated files
+// exist on disk, polluting globalThis state shared with sibling test files.
+jest.mock(
+  '@open-mercato/core/bootstrap',
+  () => ({
+    __esModule: true,
+    bootstrap: async () => {},
+  }),
+  { virtual: true },
+)
+
+jest.mock(
+  '@open-mercato/shared/lib/encryption/subscriber',
+  () => ({
+    __esModule: true,
+    registerTenantEncryptionSubscriber: () => {},
+  }),
+  { virtual: true },
+)
+
+const mockWarn = jest.fn()
+const mockDebug = jest.fn()
+jest.mock('../../logger', () => ({
+  createLogger: () => ({
+    debug: (...args: unknown[]) => mockDebug(...args),
+    info: jest.fn(),
+    warn: (...args: unknown[]) => mockWarn(...args),
+    error: jest.fn(),
+    child() { return this },
+  }),
+}))
+
+const {
+  createRequestContainer,
+  registerAppDiRegistrar,
+  registerDiRegistrars,
+  resetBootstrapCache,
+} = require('@open-mercato/shared/lib/di/container')
+
+describe('app-level DI override hook when @/di is absent', () => {
+  beforeEach(() => {
+    resetBootstrapCache()
+    registerAppDiRegistrar(null)
+    registerDiRegistrars([])
+    mockWarn.mockClear()
+    mockDebug.mockClear()
+  })
+
+  it('creates the container without warning', async () => {
+    const firstContainer = await createRequestContainer()
+    const secondContainer = await createRequestContainer()
+    expect(firstContainer).toBeDefined()
+    expect(secondContainer).toBeDefined()
+    expect(mockWarn).not.toHaveBeenCalled()
+  })
+
+  // Worker and CLI processes create one request container per job against built package
+  // output, where the app's `@/` alias does not exist. Retrying the doomed import per
+  // container repeats a failed module resolution — and its log line — once per job.
+  it('stops retrying the unresolvable @/di import after the first container', async () => {
+    await createRequestContainer()
+    await createRequestContainer()
+    await createRequestContainer()
+
+    const unresolvableLogs = mockDebug.mock.calls.filter(
+      ([message]) => message === 'App-level DI override module (@/di) not resolvable; skipping',
+    )
+    expect(unresolvableLogs).toHaveLength(1)
+  })
+
+  it('warns once when @/di fails because a nested app alias is missing', async () => {
+    const nestedAliasError = Object.assign(new Error("Cannot find module '@/di/helpers'"), {
+      code: 'MODULE_NOT_FOUND',
+    })
+    jest.doMock('@/di', () => {
+      throw nestedAliasError
+    }, { virtual: true })
+
+    const firstContainer = await createRequestContainer()
+    const secondContainer = await createRequestContainer()
+
+    expect(firstContainer).toBeDefined()
+    expect(secondContainer).toBeDefined()
+    expect(mockWarn).toHaveBeenCalledTimes(1)
+    expect(mockWarn).toHaveBeenCalledWith(
+      'App-level DI override module (@/di) failed to load; its registrations are skipped',
+      { err: nestedAliasError },
+    )
+  })
+})