@open-mercato/shared 0.4.2-canary-c02407ff85

package/src/lib/db/mikro.ts

@@ -0,0 +1,100 @@
+import 'dotenv/config'
+import 'reflect-metadata'
+import { MikroORM } from '@mikro-orm/core'
+import { PostgreSqlDriver } from '@mikro-orm/postgresql'
+
+let ormInstance: MikroORM<PostgreSqlDriver> | null = null
+
+// Registration pattern for publishable packages
+let _entities: any[] | null = null
+
+export function registerOrmEntities(entities: any[]) {
+  if (_entities !== null && process.env.NODE_ENV === 'development') {
+    console.debug('[Bootstrap] ORM entities re-registered (this may occur during HMR)')
+  }
+  _entities = entities
+}
+
+export function getOrmEntities(): any[] {
+  if (!_entities) {
+    throw new Error('[Bootstrap] ORM entities not registered. Call registerOrmEntities() at bootstrap.')
+  }
+  return _entities
+}
+
+export async function getOrm() {
+  if (ormInstance) {
+    return ormInstance
+  }
+  const entities = getOrmEntities()
+  const clientUrl = process.env.DATABASE_URL
+  if (!clientUrl) throw new Error('DATABASE_URL is not set')
+  
+  // Parse connection pool settings from environment
+  const poolMin = parseInt(process.env.DB_POOL_MIN || '2')
+  const poolMax = parseInt(process.env.DB_POOL_MAX || '50')
+  const poolIdleTimeout = parseInt(process.env.DB_POOL_IDLE_TIMEOUT || '3000')
+  const poolAcquireTimeout = parseInt(process.env.DB_POOL_ACQUIRE_TIMEOUT || '6000')
+  const idleSessionTimeoutEnv = parseInt(process.env.DB_IDLE_SESSION_TIMEOUT_MS || '')
+  const idleInTxTimeoutEnv = parseInt(process.env.DB_IDLE_IN_TRANSACTION_TIMEOUT_MS || '')
+  const idleSessionTimeoutMs = Number.isFinite(idleSessionTimeoutEnv)
+    ? idleSessionTimeoutEnv
+    : process.env.NODE_ENV === 'production'
+      ? undefined
+      : 600_000
+  const idleInTransactionTimeoutMs = Number.isFinite(idleInTxTimeoutEnv)
+    ? idleInTxTimeoutEnv
+    : process.env.NODE_ENV === 'production'
+      ? undefined
+      : 120_000
+  const connectionOptions =
+    idleSessionTimeoutMs && idleSessionTimeoutMs > 0
+      ? `-c idle_session_timeout=${idleSessionTimeoutMs}`
+      : undefined
+  
+  ormInstance = await MikroORM.init<PostgreSqlDriver>({
+    driver: PostgreSqlDriver,
+    clientUrl,
+    entities,
+    debug: false,
+    // Connection pooling configuration
+    pool: {
+      min: poolMin,
+      max: poolMax,
+      idleTimeoutMillis: poolIdleTimeout,
+      acquireTimeoutMillis: poolAcquireTimeout,
+      // Close idle connections after 30 seconds
+      destroyTimeoutMillis: process.env.NODE_ENV === 'production' ? 30000 : 3000,
+    },
+    // Connection options
+    driverOptions: {
+      // Enable connection pooling
+      connection: {
+        // Maximum number of connections in the pool
+        max: poolMax,
+        // Minimum number of connections in the pool
+        min: poolMin,
+        // Close connections after this many milliseconds of inactivity
+        idleTimeoutMillis: poolIdleTimeout,
+        // Maximum time to wait for a connection from the pool
+        acquireTimeoutMillis: poolAcquireTimeout,
+        idle_in_transaction_session_timeout: idleInTransactionTimeoutMs,
+        options: connectionOptions,
+      },
+    },
+  })
+  return ormInstance
+}
+
+
+async function closeOrmIfLoaded(): Promise<void> {
+  if (ormInstance) {
+    await ormInstance.close(true)
+    ormInstance = null
+  }
+}
+
+// In dev mode, handle reloads cleanly without leaving dangling connections.
+if (process.env.NODE_ENV !== 'production') {
+  void closeOrmIfLoaded()
+}

package/src/lib/di/container.ts

@@ -0,0 +1,105 @@
+import { createContainer, asValue, AwilixContainer, InjectionMode } from 'awilix'
+import { RequestContext } from '@mikro-orm/core'
+import { getOrm } from '@open-mercato/shared/lib/db/mikro'
+import { EntityManager } from '@mikro-orm/postgresql'
+import { BasicQueryEngine } from '@open-mercato/shared/lib/query/engine'
+import { DefaultDataEngine } from '@open-mercato/shared/lib/data/engine'
+import { commandRegistry, CommandBus } from '@open-mercato/shared/lib/commands'
+
+export type AppContainer = AwilixContainer
+export type DiRegistrar = (container: AwilixContainer) => void
+
+// Registration pattern for publishable packages
+// Use globalThis to survive tsx/esbuild module duplication issue where the same
+// file can be loaded as multiple module instances when mixing dynamic and static imports
+const GLOBAL_KEY = '__openMercatoDiRegistrars__'
+
+function getGlobalRegistrars(): DiRegistrar[] | null {
+  return (globalThis as any)[GLOBAL_KEY] ?? null
+}
+
+function setGlobalRegistrars(registrars: DiRegistrar[]): void {
+  (globalThis as any)[GLOBAL_KEY] = registrars
+}
+
+export function registerDiRegistrars(registrars: DiRegistrar[]) {
+  const existing = getGlobalRegistrars()
+  if (existing !== null && process.env.NODE_ENV === 'development') {
+    console.debug('[Bootstrap] DI registrars re-registered (this may occur during HMR)')
+  }
+  setGlobalRegistrars(registrars)
+}
+
+export function getDiRegistrars(): DiRegistrar[] {
+  const registrars = getGlobalRegistrars()
+  if (!registrars) {
+    throw new Error('[Bootstrap] DI registrars not registered. Call registerDiRegistrars() at bootstrap.')
+  }
+  return registrars
+}
+
+export async function createRequestContainer(): Promise<AppContainer> {
+  const diRegistrars = getDiRegistrars()
+  const orm = await getOrm()
+  // Use a fresh event manager so request-level subscribers (e.g., encryption) don't pile up globally
+  const baseEm = (RequestContext.getEntityManager() as any) ?? orm.em
+  const em = baseEm.fork({ clear: true, freshEventManager: true, useContext: true }) as unknown as EntityManager
+  const container = createContainer({ injectionMode: InjectionMode.CLASSIC })
+  // Core registrations
+  container.register({
+    em: asValue(em),
+    queryEngine: asValue(new BasicQueryEngine(em, undefined, () => {
+      try { return container.resolve('tenantEncryptionService') as any } catch { return null }
+    })),
+    dataEngine: asValue(new DefaultDataEngine(em, container as any)),
+    commandRegistry: asValue(commandRegistry),
+    commandBus: asValue(new CommandBus()),
+  })
+  // Allow modules to override/extend
+  for (const reg of diRegistrars) {
+    try { reg?.(container) } catch {}
+  }
+  // Core bootstrap (cache, event bus, encryption subscriber/KMS, module subscribers)
+  try {
+    const { bootstrap } = await import('@open-mercato/core/bootstrap') as any
+    if (bootstrap && typeof bootstrap === 'function') {
+      // Avoid double bootstrap if caller already wired it
+      const alreadyBootstrapped = !!container.registrations?.eventBus
+      if (!alreadyBootstrapped) {
+        await bootstrap(container)
+      }
+    }
+  } catch { /* optional */ }
+  // App-level DI override (last chance)
+  // This import path resolves only in the app context, not in packages
+  try {
+    // @ts-ignore - @/di only exists in app context, not in packages
+    const appDi = await import('@/di') as any
+    if (appDi?.register) {
+      try {
+        const maybe = appDi.register(container)
+        if (maybe && typeof maybe.then === 'function') await maybe
+      } catch {}
+    }
+  } catch {}
+  // Ensure tenant encryption subscriber is always registered on the fresh request-scoped EM
+  try {
+    const emForEnc = container.resolve('em') as any
+    const tenantEncryptionService = container.hasRegistration('tenantEncryptionService')
+      ? (container.resolve('tenantEncryptionService') as any)
+      : null
+    if (emForEnc && tenantEncryptionService?.isEnabled?.()) {
+      const { registerTenantEncryptionSubscriber } = await import('@open-mercato/shared/lib/encryption/subscriber')
+      registerTenantEncryptionSubscriber(emForEnc, tenantEncryptionService)
+    }
+  } catch {
+    // best-effort; do not block container creation
+  }
+  return container
+}
+try {
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  require('server-only')
+} catch {
+  // allow CLI/generator usage where Next server-only is not present
+}

package/src/lib/email/send.ts

@@ -0,0 +1,18 @@
+import { Resend } from 'resend'
+import React from 'react'
+
+export type SendEmailOptions = {
+  to: string
+  subject: string
+  react: React.ReactElement
+  from?: string
+}
+
+export async function sendEmail({ to, subject, react, from }: SendEmailOptions) {
+  const apiKey = process.env.RESEND_API_KEY
+  if (!apiKey) throw new Error('RESEND_API_KEY is not set')
+  const resend = new Resend(apiKey)
+  const fromAddr = from || process.env.EMAIL_FROM || 'no-reply@localhost'
+  await resend.emails.send({ to, subject, from: fromAddr, react })
+}
+

package/src/lib/encryption/__tests__/customFieldValues.test.ts

@@ -0,0 +1,63 @@
+import type { EntityManager } from '@mikro-orm/core'
+import { decryptCustomFieldValue, encryptCustomFieldValue, resolveTenantEncryptionService } from '../customFieldValues'
+
+const fixedKey = Buffer.alloc(32, 1).toString('base64')
+
+describe('customFieldValues encryption helpers', () => {
+  it('caches tenant encryption service per entity manager', () => {
+    const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {})
+    const em = {} as EntityManager
+    const first = resolveTenantEncryptionService(em)
+    const second = resolveTenantEncryptionService(em)
+    expect(first).toBe(second)
+    warnSpy.mockRestore()
+  })
+
+  it('encrypts and decrypts primitives when enabled', async () => {
+    const service = {
+      isEnabled: () => true,
+      getDek: async () => ({ key: fixedKey }),
+    } as any
+    const cache = new Map<string | null, string | null>()
+
+    const encrypted = await encryptCustomFieldValue('secret', 'tenant-1', service, cache)
+    expect(typeof encrypted).toBe('string')
+    const decrypted = await decryptCustomFieldValue(encrypted, 'tenant-1', service, cache)
+    expect(decrypted).toBe('secret')
+
+    const encryptedNumber = await encryptCustomFieldValue(42, 'tenant-1', service, cache)
+    const decryptedNumber = await decryptCustomFieldValue(encryptedNumber, 'tenant-1', service, cache)
+    expect(decryptedNumber).toBe(42)
+  })
+
+  it('creates a tenant DEK on first encrypt when none exists', async () => {
+    let created = false
+    const service = {
+      isEnabled: () => true,
+      getDek: jest.fn(async () => (created ? { key: fixedKey } : null)),
+      createDek: jest.fn(async () => {
+        created = true
+        return { key: fixedKey }
+      }),
+    } as any
+    const cache = new Map<string | null, string | null>()
+
+    const encrypted = await encryptCustomFieldValue('secret', 'tenant-1', service, cache)
+    expect(typeof encrypted).toBe('string')
+    expect(encrypted).not.toBe('secret')
+    expect(service.createDek).toHaveBeenCalledTimes(1)
+
+    const decrypted = await decryptCustomFieldValue(encrypted, 'tenant-1', service, cache)
+    expect(decrypted).toBe('secret')
+  })
+
+  it('returns original value when encryption is disabled or tenant is missing', async () => {
+    const disabledService = {
+      isEnabled: () => false,
+      getDek: async () => ({ key: fixedKey }),
+    } as any
+    expect(await encryptCustomFieldValue('plain', 'tenant-1', disabledService)).toBe('plain')
+    expect(await decryptCustomFieldValue('plain', 'tenant-1', disabledService)).toBe('plain')
+    expect(await encryptCustomFieldValue('plain', null, disabledService)).toBe('plain')
+  })
+})

package/src/lib/encryption/__tests__/indexDoc.test.ts

@@ -0,0 +1,115 @@
+import { decryptIndexDocCustomFields, decryptIndexDocForSearch, encryptIndexDocForStorage } from '../indexDoc'
+import { decryptCustomFieldValue } from '../customFieldValues'
+
+jest.mock('../customFieldValues', () => ({
+  decryptCustomFieldValue: jest.fn(async (value: unknown) => value),
+}))
+
+const decryptCustomFieldValueMock = decryptCustomFieldValue as jest.Mock
+
+describe('encryption/indexDoc', () => {
+  beforeEach(() => {
+    decryptCustomFieldValueMock.mockReset()
+    decryptCustomFieldValueMock.mockImplementation(async (value: unknown) => value)
+  })
+
+  test('decryptIndexDocCustomFields decrypts cf keys (including arrays)', async () => {
+    decryptCustomFieldValueMock.mockImplementation(async (value: unknown) => {
+      if (value === 'enc') return 'dec'
+      if (value === 'enc2') return 'dec2'
+      return value
+    })
+
+    const doc = {
+      id: '1',
+      title: 'Encrypted',
+      'cf:secret': 'enc',
+      'cf:tags': ['enc2', 'plain'],
+      cf_secret: 'enc',
+    }
+
+    const out = await decryptIndexDocCustomFields(doc, { tenantId: 't1', organizationId: 'org1' }, {} as any)
+    expect(out).toEqual({
+      id: '1',
+      title: 'Encrypted',
+      'cf:secret': 'dec',
+      'cf:tags': ['dec2', 'plain'],
+      cf_secret: 'dec',
+    })
+    expect(decryptCustomFieldValueMock).toHaveBeenCalled()
+  })
+
+  test('decryptIndexDocForSearch merges decrypted entity payload and decrypts cf keys', async () => {
+    decryptCustomFieldValueMock.mockImplementation(async (value: unknown) => (value === 'enc' ? 'dec' : value))
+
+    const service = {
+      isEnabled: () => true,
+      decryptEntityPayload: jest.fn(async (_entityId: string, _payload: Record<string, unknown>) => ({
+        title: 'Plain',
+      })),
+    }
+
+    const out = await decryptIndexDocForSearch(
+      'example:todo',
+      { id: '1', title: 'Encrypted', 'cf:secret': 'enc' },
+      { tenantId: 't1', organizationId: 'org1' },
+      service as any,
+    )
+
+    expect(out.title).toBe('Plain')
+    expect(out['cf:secret']).toBe('dec')
+    expect(service.decryptEntityPayload).toHaveBeenCalledWith(
+      'example:todo',
+      expect.any(Object),
+      't1',
+      'org1',
+    )
+  })
+
+  test('decryptIndexDocForSearch decrypts customer entity when indexing customer profiles', async () => {
+    const service = {
+      isEnabled: () => true,
+      decryptEntityPayload: jest.fn(async (entityId: string) => (entityId === 'customers:customer_entity' ? { display_name: 'Plain' } : {})),
+    }
+
+    const out = await decryptIndexDocForSearch(
+      'customers:customer_person_profile',
+      { id: '1', display_name: 'Encrypted' },
+      { tenantId: 't1', organizationId: 'org1' },
+      service as any,
+    )
+
+    expect(out.display_name).toBe('Plain')
+    expect(service.decryptEntityPayload).toHaveBeenCalledWith(
+      'customers:customer_entity',
+      expect.any(Object),
+      't1',
+      'org1',
+    )
+  })
+
+  test('encryptIndexDocForStorage encrypts entity fields using the configured map', async () => {
+    const service = {
+      isEnabled: () => true,
+      encryptEntityPayload: jest.fn(async (_entityId: string, payload: Record<string, unknown>) => ({
+        ...payload,
+        resultTitle: 'enc',
+      })),
+    }
+
+    const out = await encryptIndexDocForStorage(
+      'vector:vector_search',
+      { resultTitle: 'plain' },
+      { tenantId: 't1', organizationId: 'org1' },
+      service as any,
+    )
+
+    expect(out.resultTitle).toBe('enc')
+    expect(service.encryptEntityPayload).toHaveBeenCalledWith(
+      'vector:vector_search',
+      expect.any(Object),
+      't1',
+      'org1',
+    )
+  })
+})

package/src/lib/encryption/aes.ts

@@ -0,0 +1,64 @@
+import crypto from 'node:crypto'
+import { isEncryptionDebugEnabled } from './toggles'
+
+export type EncryptionPayload = {
+  value: string | null
+  raw: string
+  version: string
+}
+
+export function generateDek(): string {
+  return crypto.randomBytes(32).toString('base64')
+}
+
+function logDebug(event: string, payload: Record<string, unknown>) {
+  if (!isEncryptionDebugEnabled()) return
+  try {
+    // eslint-disable-next-line no-console
+    console.debug('[encryption]', event, payload)
+  } catch {
+    // ignore
+  }
+}
+
+export function encryptWithAesGcm(value: string, dekBase64: string): EncryptionPayload {
+  const dek = Buffer.from(dekBase64, 'base64')
+  const iv = crypto.randomBytes(12)
+  const cipher = crypto.createCipheriv('aes-256-gcm', dek, iv)
+  const ciphertext = Buffer.concat([cipher.update(value, 'utf8'), cipher.final()])
+  const tag = cipher.getAuthTag()
+  const payload = [
+    iv.toString('base64'),
+    ciphertext.toString('base64'),
+    tag.toString('base64'),
+    'v1',
+  ].join(':')
+  logDebug('encrypt', { length: ciphertext.length })
+  return { value: payload, raw: payload, version: 'v1' }
+}
+
+export function decryptWithAesGcm(payload: string, dekBase64: string): string | null {
+  if (!payload) return null
+  const parts = payload.split(':')
+  if (parts.length !== 4) return null
+  const [ivB64, ciphertextB64, tagB64, version] = parts
+  if (version !== 'v1') return null
+  const dek = Buffer.from(dekBase64, 'base64')
+  const iv = Buffer.from(ivB64, 'base64')
+  const ciphertext = Buffer.from(ciphertextB64, 'base64')
+  const tag = Buffer.from(tagB64, 'base64')
+  try {
+    const decipher = crypto.createDecipheriv('aes-256-gcm', dek, iv)
+    decipher.setAuthTag(tag)
+    const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString('utf8')
+    logDebug('decrypt', { iv: ivB64, tag: tagB64 })
+    return decrypted
+  } catch (err) {
+    logDebug('decrypt_error', { message: (err as Error)?.message || String(err) })
+    return null
+  }
+}
+
+export function hashForLookup(value: string): string {
+  return crypto.createHash('sha256').update(value.toLowerCase().trim()).digest('hex')
+}

package/src/lib/encryption/customFieldValues.ts

@@ -0,0 +1,67 @@
+import type { EntityManager } from '@mikro-orm/core'
+import { encryptWithAesGcm, decryptWithAesGcm } from './aes'
+import { TenantDataEncryptionService } from './tenantDataEncryptionService'
+
+const serviceCache = new WeakMap<EntityManager, TenantDataEncryptionService>()
+
+export function resolveTenantEncryptionService(
+  em: EntityManager,
+  provided?: TenantDataEncryptionService | null,
+): TenantDataEncryptionService | null {
+  if (provided) return provided
+  const cached = serviceCache.get(em)
+  if (cached) return cached
+  const service = new TenantDataEncryptionService(em as any)
+  serviceCache.set(em, service)
+  return service
+}
+
+async function resolveDekKey(
+  service: TenantDataEncryptionService | null,
+  tenantId: string | null | undefined,
+  cache?: Map<string | null, string | null>,
+  opts?: { createIfMissing?: boolean },
+): Promise<string | null> {
+  const scopedTenantId = tenantId ?? null
+  if (!service || !service.isEnabled() || !scopedTenantId) return null
+  if (cache?.has(scopedTenantId)) return cache.get(scopedTenantId) ?? null
+  const dek = await service.getDek(scopedTenantId)
+  let key = dek?.key ?? null
+  if (!key && opts?.createIfMissing && typeof service.createDek === 'function') {
+    const created = await service.createDek(scopedTenantId)
+    key = created?.key ?? null
+  }
+  cache?.set(scopedTenantId, key)
+  return key
+}
+
+export async function encryptCustomFieldValue(
+  value: unknown,
+  tenantId: string | null | undefined,
+  service: TenantDataEncryptionService | null,
+  cache?: Map<string | null, string | null>,
+): Promise<unknown> {
+  if (value === undefined || value === null) return value
+  const key = await resolveDekKey(service, tenantId, cache, { createIfMissing: true })
+  if (!key) return value
+  const serialized = typeof value === 'string' ? value : JSON.stringify(value)
+  return encryptWithAesGcm(serialized, key).value
+}
+
+export async function decryptCustomFieldValue(
+  value: unknown,
+  tenantId: string | null | undefined,
+  service: TenantDataEncryptionService | null,
+  cache?: Map<string | null, string | null>,
+): Promise<unknown> {
+  if (value === undefined || value === null || typeof value !== 'string') return value
+  const key = await resolveDekKey(service, tenantId, cache)
+  if (!key) return value
+  const decrypted = decryptWithAesGcm(value, key)
+  if (decrypted === null) return value
+  try {
+    return JSON.parse(decrypted)
+  } catch {
+    return decrypted
+  }
+}

package/src/lib/encryption/entityFields.ts

@@ -0,0 +1,39 @@
+// Registration pattern for entity fields (for Turbopack compatibility)
+export type EntityFieldsRegistry = Record<string, Record<string, string>>
+
+let _entityFieldsRegistry: EntityFieldsRegistry | null = null
+
+export function registerEntityFields(registry: EntityFieldsRegistry) {
+  if (_entityFieldsRegistry !== null && process.env.NODE_ENV === 'development') {
+    console.debug('[Bootstrap] Entity fields re-registered (this may occur during HMR)')
+  }
+  _entityFieldsRegistry = registry
+}
+
+/**
+ * Get registered entity fields.
+ *
+ * @param throwIfNotRegistered - If true, throws error when entity fields are not registered.
+ *                               If false, returns empty object (useful during module load).
+ *                               Default: true
+ */
+export function getEntityFieldsRegistry(throwIfNotRegistered = true): EntityFieldsRegistry {
+  if (!_entityFieldsRegistry) {
+    if (throwIfNotRegistered) {
+      throw new Error('[Bootstrap] Entity fields not registered. Call registerEntityFields() at bootstrap.')
+    }
+    return {} as EntityFieldsRegistry
+  }
+  return _entityFieldsRegistry
+}
+
+/**
+ * Get fields for a specific entity by slug.
+ *
+ * @param slug - The entity slug (e.g., 'user', 'sales_order')
+ * @returns The entity's fields or undefined if not found
+ */
+export function getEntityFields(slug: string): Record<string, string> | undefined {
+  const registry = getEntityFieldsRegistry(false)
+  return registry[slug]
+}

package/src/lib/encryption/entityIds.ts

@@ -0,0 +1,107 @@
+import type { EntityMetadata } from '@mikro-orm/core'
+
+// Registration pattern for publishable packages
+export type EntityIds = Record<string, Record<string, string>>
+
+let _entityIds: EntityIds | null = null
+let _entityIdLookup: Map<string, string> | null = null
+
+export function registerEntityIds(E: EntityIds) {
+  if (_entityIds !== null && process.env.NODE_ENV === 'development') {
+    console.debug('[Bootstrap] Entity IDs re-registered (this may occur during HMR)')
+  }
+  _entityIds = E
+  _entityIdLookup = null // Reset cache on re-registration
+}
+
+/**
+ * Get registered entity IDs.
+ *
+ * @param throwIfNotRegistered - If true, throws error when entity IDs are not registered.
+ *                               If false, returns empty object (useful during module load).
+ *                               Default: true
+ */
+export function getEntityIds(throwIfNotRegistered = true): EntityIds {
+  if (!_entityIds) {
+    if (throwIfNotRegistered) {
+      throw new Error('[Bootstrap] Entity IDs not registered. Call registerEntityIds() at bootstrap.')
+    }
+    return {} as EntityIds
+  }
+  return _entityIds
+}
+
+const toSnake = (value: string): string =>
+  value
+    .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+    .replace(/[\s-]+/g, '_')
+    .replace(/__+/g, '_')
+    .toLowerCase()
+
+function getEntityIdLookup(): Map<string, string> {
+  if (_entityIdLookup) return _entityIdLookup
+  const E = getEntityIds()
+  const map = new Map<string, string>()
+  for (const mod of Object.values(E || {})) {
+    for (const [key, entityId] of Object.entries(mod || {})) {
+      const snake = toSnake(key)
+      map.set(snake, entityId)
+      // Also allow the original key and PascalCase class names to resolve
+      map.set(key.toLowerCase(), entityId)
+      map.set(
+        key
+          .split('_')
+          .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+          .join(''),
+        entityId,
+      )
+    }
+  }
+  _entityIdLookup = map
+  return map
+}
+
+const normalizeKey = (value: string): string =>
+  value
+    .replace(/["'`]/g, '')
+    .replace(/[\W]+/g, '_')
+    .replace(/__+/g, '_')
+    .toLowerCase()
+
+const maybeSingularize = (value: string): string => {
+  if (value.endsWith('ies')) return `${value.slice(0, -3)}y`
+  if (value.endsWith('s')) return value.slice(0, -1)
+  return value
+}
+
+export function resolveEntityIdFromMetadata(meta: EntityMetadata<any> | undefined): string | null {
+  if (!meta) return null
+  const candidates = [
+    (meta as any).className,
+    meta.name,
+    (meta as any).collection,
+    (meta as any).tableName,
+  ].filter(Boolean) as string[]
+
+  for (const raw of candidates) {
+    const normalized = normalizeKey(raw)
+    const singular = maybeSingularize(normalized)
+    const snake = toSnake(raw)
+    const snakeSingular = maybeSingularize(snake)
+    const variants = [
+      normalized,
+      singular,
+      normalized.replace(/_/g, ''), // Pascal-ish fallback
+      singular.replace(/_/g, ''),
+      snake,
+      snakeSingular,
+    ]
+    const lookup = getEntityIdLookup()
+    for (const candidate of variants) {
+      if (!candidate) continue
+      const id = lookup.get(candidate)
+      if (id) return id
+    }
+  }
+  return null
+}