@open-mercato/shared 0.6.6-develop.6460.1.f94c74174c → 0.6.6-develop.6471.1.9ab5bdd79a

package/src/lib/commands/__tests__/flush.test.ts

@@ -1,4 +1,19 @@
 import { withAtomicFlush } from '../flush'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+
+jest.mock('@open-mercato/shared/lib/logger', () => {
+  const mocked = {
+    debug: jest.fn(),
+    info: jest.fn(),
+    warn: jest.fn(),
+    error: jest.fn(),
+    child: jest.fn(),
+  }
+  mocked.child.mockImplementation(() => mocked)
+  return { createLogger: jest.fn(() => mocked) }
+})
+const loggerWarn = createLogger('shared').warn as jest.Mock
+
 
 type FakeEntityManager = {
   flush: jest.Mock<Promise<void>, []>
@@ -258,11 +273,10 @@ describe('withAtomicFlush', () => {
       // after its own flush). The guard must persist it instead of letting the
       // transaction commit the work-in-progress silently.
       const em = createUowEm([{ entity: 'lingering' }], { inTransaction: false })
-      const warn = jest.spyOn(console, 'warn').mockImplementation(() => {})
+      loggerWarn.mockClear()
       try {
         await withAtomicFlush(em as any, [() => {}], { transaction: true, label: 'demo.command' })
       } finally {
-        warn.mockRestore()
       }
 
       // 1 per-phase flush + 1 defensive guard flush, all inside the same transaction.
@@ -275,36 +289,31 @@ describe('withAtomicFlush', () => {
       const em = createUowEm([{ a: 1 }, { b: 2 }])
       const previousEnv = process.env.NODE_ENV
       process.env.NODE_ENV = 'development'
-      const warn = jest.spyOn(console, 'warn').mockImplementation(() => {})
-      let warnCallCount = 0
-      let warnMessage = ''
+      loggerWarn.mockClear()
       try {
         await withAtomicFlush(em as any, [() => {}], { label: 'sales.update_shipment' })
-        // Capture BEFORE mockRestore — restore() resets mock.calls.
-        warnCallCount = warn.mock.calls.length
-        warnMessage = String(warn.mock.calls[0]?.[0] ?? '')
       } finally {
-        warn.mockRestore()
         process.env.NODE_ENV = previousEnv
       }
 
-      expect(warnCallCount).toBe(1)
-      expect(warnMessage).toContain('sales.update_shipment')
-      expect(warnMessage).toContain('2 pending change-set(s)')
+      expect(loggerWarn).toHaveBeenCalledTimes(1)
+      expect(loggerWarn).toHaveBeenCalledWith(
+        expect.stringContaining('flushed defensively'),
+        expect.objectContaining({ label: 'sales.update_shipment', pendingCount: 2 }),
+      )
     })
 
     it('does NOT flush again when the UnitOfWork is clean at the boundary', async () => {
       const em = createUowEm([])
-      const warn = jest.spyOn(console, 'warn').mockImplementation(() => {})
+      loggerWarn.mockClear()
       try {
         await withAtomicFlush(em as any, [() => {}, () => {}])
       } finally {
-        warn.mockRestore()
       }
 
       // 2 phases → 2 per-phase flushes; the clean guard adds nothing.
       expect(em.flush).toHaveBeenCalledTimes(2)
-      expect(warn).not.toHaveBeenCalled()
+      expect(loggerWarn).not.toHaveBeenCalled()
     })
 
     it('never throws when the UnitOfWork probe itself fails', async () => {

package/src/lib/commands/__tests__/normalizeAuthorUserId.test.ts

@@ -3,8 +3,20 @@ import { normalizeAuthorUserId } from '@open-mercato/shared/lib/commands/helpers
 describe('normalizeAuthorUserId', () => {
   const validUuid = 'a1b2c3d4-e5f6-1a2b-9c3d-4e5f6a7b8c9d'
 
-  it('returns explicit authorUserId when provided', () => {
-    expect(normalizeAuthorUserId('explicit-id', { sub: validUuid })).toBe('explicit-id')
+  it('ignores explicit authorUserId for normal authenticated callers', () => {
+    const spoofedUuid = 'b1b2c3d4-e5f6-1a2b-9c3d-4e5f6a7b8c9d'
+
+    expect(normalizeAuthorUserId(spoofedUuid, { sub: validUuid })).toBe(validUuid)
+  })
+
+  it('honors explicit authorUserId for super admins', () => {
+    const delegatedUuid = 'b1b2c3d4-e5f6-1a2b-9c3d-4e5f6a7b8c9d'
+
+    expect(normalizeAuthorUserId(delegatedUuid, { sub: validUuid, isSuperAdmin: true })).toBe(delegatedUuid)
+  })
+
+  it('rejects non-UUID explicit authorUserId values for super admins', () => {
+    expect(normalizeAuthorUserId('not-a-uuid', { sub: validUuid, isSuperAdmin: true })).toBe(validUuid)
   })
 
   it('returns null when no explicit ID and auth is null', () => {

package/src/lib/commands/__tests__/registry.test.ts

@@ -1,4 +1,19 @@
 import { commandRegistry, registerCommand, registerCommandLoaders } from '@open-mercato/shared/lib/commands'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+
+jest.mock('@open-mercato/shared/lib/logger', () => {
+  const mocked = {
+    debug: jest.fn(),
+    info: jest.fn(),
+    warn: jest.fn(),
+    error: jest.fn(),
+    child: jest.fn(),
+  }
+  mocked.child.mockImplementation(() => mocked)
+  return { createLogger: jest.fn(() => mocked) }
+})
+const loggerDebug = createLogger('shared').debug as jest.Mock
+
 
 describe('command registry registration', () => {
   const originalNodeEnv = process.env.NODE_ENV
@@ -27,7 +42,7 @@ describe('command registry registration', () => {
 
   it('overwrites duplicate command ids in development to tolerate HMR re-evaluation', () => {
     process.env.NODE_ENV = 'development'
-    const debugSpy = jest.spyOn(console, 'debug').mockImplementation(() => {})
+    loggerDebug.mockClear()
     const firstExecute = jest.fn(async () => 'first')
     const secondExecute = jest.fn(async () => 'second')
 
@@ -42,7 +57,7 @@ describe('command registry registration', () => {
     })
 
     expect(commandRegistry.get('test.command.hmr')?.execute).toBe(secondExecute)
-    expect(debugSpy).toHaveBeenCalledWith('[Bootstrap] Commands re-registered (this may occur during HMR)')
+    expect(loggerDebug).toHaveBeenCalledWith('Commands re-registered (this may occur during HMR)')
   })
 
   it('loads a command handler on demand from a registered loader', async () => {

package/src/lib/commands/__tests__/scope.test.ts

@@ -1,6 +1,21 @@
 import { ensureOrganizationScope, ensureTenantScope } from '@open-mercato/shared/lib/commands/scope'
 import type { CommandRuntimeContext } from '@open-mercato/shared/lib/commands'
 import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+
+jest.mock('@open-mercato/shared/lib/logger', () => {
+  const mocked = {
+    debug: jest.fn(),
+    info: jest.fn(),
+    warn: jest.fn(),
+    error: jest.fn(),
+    child: jest.fn(),
+  }
+  mocked.child.mockImplementation(() => mocked)
+  return { createLogger: jest.fn(() => mocked) }
+})
+const loggerWarn = createLogger('shared').warn as jest.Mock
+
 
 type ScopeShape = NonNullable<CommandRuntimeContext['organizationScope']>
 
@@ -154,17 +169,14 @@ describe('ensureOrganizationScope', () => {
   describe('fail-open-by-omission hardening (#2441)', () => {
     const originalNodeEnv = process.env.NODE_ENV
     const originalStrict = process.env.OM_ENFORCE_ORG_SCOPE_STRICT
-    let warnSpy: jest.SpyInstance
-
     beforeEach(() => {
       // The scope loggers suppress output under NODE_ENV==='test'; flip it so the
       // observability signal becomes assertable, then restore in afterEach.
       process.env.NODE_ENV = 'development'
-      warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {})
+      loggerWarn.mockClear()
     })
 
     afterEach(() => {
-      warnSpy.mockRestore()
       if (originalNodeEnv === undefined) delete process.env.NODE_ENV
       else process.env.NODE_ENV = originalNodeEnv
       if (originalStrict === undefined) delete process.env.OM_ENFORCE_ORG_SCOPE_STRICT
@@ -175,8 +187,8 @@ describe('ensureOrganizationScope', () => {
       delete process.env.OM_ENFORCE_ORG_SCOPE_STRICT
       const ctx = buildCtx({ orgId: null, selectedOrganizationId: null, organizationScope: null })
       expect(() => ensureOrganizationScope(ctx, 'org-b')).not.toThrow()
-      expect(warnSpy).toHaveBeenCalledWith(
-        '[scope] Unscoped organization command executed without organization context',
+      expect(loggerWarn).toHaveBeenCalledWith(
+        'Unscoped organization command executed without organization context',
         expect.objectContaining({ targetOrganizationId: 'org-b', strictEnforcement: false })
       )
     })
@@ -185,8 +197,8 @@ describe('ensureOrganizationScope', () => {
       process.env.OM_ENFORCE_ORG_SCOPE_STRICT = 'true'
       const ctx = buildCtx({ orgId: null, selectedOrganizationId: null, organizationScope: null })
       expect(() => ensureOrganizationScope(ctx, 'org-b')).toThrow(CrudHttpError)
-      expect(warnSpy).toHaveBeenCalledWith(
-        '[scope] Unscoped organization command executed without organization context',
+      expect(loggerWarn).toHaveBeenCalledWith(
+        'Unscoped organization command executed without organization context',
         expect.objectContaining({ targetOrganizationId: 'org-b', strictEnforcement: true })
       )
     })
@@ -195,7 +207,7 @@ describe('ensureOrganizationScope', () => {
       delete process.env.OM_ENFORCE_ORG_SCOPE_STRICT
       const ctx = buildCtx({ orgId: null, selectedOrganizationId: null, organizationScope: null })
       expect(() => ensureOrganizationScope(ctx, '')).not.toThrow()
-      expect(warnSpy).not.toHaveBeenCalled()
+      expect(loggerWarn).not.toHaveBeenCalled()
     })
   })
 })

package/src/lib/commands/command-bus.ts

@@ -30,6 +30,9 @@ import {
 } from './command-interceptor-runner'
 import type { CommandInterceptorContext } from './command-interceptor'
 import { CommandInterceptorError } from './errors'
+import { createLogger } from '../logger'
+
+const logger = createLogger('shared').child({ component: 'commands' })
 
 const SKIPPED_ACTION_LOG_RESOURCE_KINDS = new Set<string>([
   'audit_logs.access',
@@ -624,7 +627,7 @@ export class CommandBus {
     } catch (err) {
       if (isCrudCacheDebugEnabled()) {
         try {
-          console.debug('[crud][cache] execute-invalidation failed', { commandId, err })
+          logger.debug('Cache execute-invalidation failed', { commandId, err })
         } catch {}
       }
     }
@@ -656,7 +659,7 @@ export class CommandBus {
     } catch (err) {
       if (isCrudCacheDebugEnabled()) {
         try {
-          console.debug('[crud][cache] undo-invalidation failed', { commandId: log.commandId, err })
+          logger.debug('Cache undo-invalidation failed', { commandId: log.commandId, err })
         } catch {}
       }
     }

package/src/lib/commands/command-interceptor-runner.ts

@@ -4,6 +4,9 @@ import type {
   CommandInterceptorUndoContext,
 } from './command-interceptor'
 import { hasAllFeatures } from '../../security/features'
+import { createLogger } from '../logger'
+
+const logger = createLogger('shared').child({ component: 'commands' })
 
 // ---------------------------------------------------------------------------
 // Command pattern matching
@@ -116,7 +119,7 @@ export async function runCommandInterceptorsAfter(
         currentResult = { ...(currentResult as Record<string, unknown>), ...afterResult.modifiedResult }
       }
     } catch (error) {
-      console.error(`[command-interceptor] afterExecute failed: ${interceptor.id}`, error)
+      logger.error('Command interceptor afterExecute failed', { interceptorId: interceptor.id, err: error })
     }
   }
 
@@ -185,7 +188,7 @@ export async function runCommandInterceptorsAfterUndo(
         { ...context, commandId, metadata: metadataByInterceptor.get(interceptor.id) },
       )
     } catch (error) {
-      console.error(`[command-interceptor] afterUndo failed: ${interceptor.id}`, error)
+      logger.error('Command interceptor afterUndo failed', { interceptorId: interceptor.id, err: error })
     }
   }
 }

package/src/lib/commands/flush.ts

@@ -1,5 +1,8 @@
 import type { EntityManager } from '@mikro-orm/postgresql'
 import type { IsolationLevel } from '@mikro-orm/core'
+import { createLogger } from '../logger'
+
+const logger = createLogger('shared').child({ component: 'commands' })
 
 /**
  * Options controlling how {@link withAtomicFlush} executes its phases.
@@ -72,11 +75,7 @@ async function flushPendingChangesGuard(
   if (pendingCount > 0) {
     await em.flush()
     if (process.env.NODE_ENV !== 'production') {
-      const where = label ? ` (${label})` : ''
-      console.warn(
-        `[withAtomicFlush]${where}: ${pendingCount} pending change-set(s) remained at the commit boundary and were flushed defensively. ` +
-          'A phase mutated a managed entity after its flush boundary — split the mutation and any dependent read/sync into separate phases so the change is never at risk of being dropped.',
-      )
+      logger.warn('withAtomicFlush: pending change-sets remained at the commit boundary and were flushed defensively — a phase mutated a managed entity after its flush boundary; split the mutation and any dependent read/sync into separate phases', { label: label ?? null, pendingCount })
     }
   }
 }

package/src/lib/commands/helpers.ts

@@ -170,9 +170,16 @@ const AUTHOR_UUID_REGEX = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[8
 
 export function normalizeAuthorUserId(
   explicitAuthorUserId: string | undefined | null,
-  auth: { isApiKey?: boolean; sub?: string | null } | undefined | null
+  auth: { isApiKey?: boolean; isSuperAdmin?: boolean; sub?: string | null } | undefined | null
 ): string | null {
-  if (explicitAuthorUserId) return explicitAuthorUserId
+  if (
+    explicitAuthorUserId &&
+    auth?.isSuperAdmin === true &&
+    auth.isApiKey !== true &&
+    AUTHOR_UUID_REGEX.test(explicitAuthorUserId)
+  ) {
+    return explicitAuthorUserId
+  }
   const authSub = auth?.isApiKey ? null : auth?.sub ?? null
   if (!authSub) return null
   return AUTHOR_UUID_REGEX.test(authSub) ? authSub : null

package/src/lib/commands/registry.ts

@@ -1,4 +1,7 @@
 import type { CommandHandler } from './types'
+import { createLogger } from '../logger'
+
+const logger = createLogger('shared').child({ component: 'commands' })
 
 export type CommandLoader = {
   id?: string | null
@@ -21,7 +24,7 @@ class CommandRegistry {
     if (this.handlers.has(handler.id)) {
       if (process.env.NODE_ENV === 'development') {
         if (!this.didWarnAboutDevelopmentReregistration) {
-          console.debug('[Bootstrap] Commands re-registered (this may occur during HMR)')
+          logger.debug('Commands re-registered (this may occur during HMR)')
           this.didWarnAboutDevelopmentReregistration = true
         }
         this.handlers.set(handler.id, handler)
@@ -42,7 +45,7 @@ class CommandRegistry {
           throw new Error(`Duplicate command loader registration for id ${loader.id}`)
         }
         if (this.loadersById.has(loader.id) && process.env.NODE_ENV === 'development' && !this.didWarnAboutDevelopmentLoaderReregistration) {
-          console.debug('[Bootstrap] Command loaders re-registered (this may occur during HMR)')
+          logger.debug('Command loaders re-registered (this may occur during HMR)')
           this.didWarnAboutDevelopmentLoaderReregistration = true
         }
         this.loadersById.set(loader.id, loader)
@@ -55,7 +58,7 @@ class CommandRegistry {
         throw new Error(`Duplicate command loader registration for key ${key}`)
       }
       if (existing.has(key) && process.env.NODE_ENV === 'development' && !this.didWarnAboutDevelopmentLoaderReregistration) {
-        console.debug('[Bootstrap] Command loaders re-registered (this may occur during HMR)')
+        logger.debug('Command loaders re-registered (this may occur during HMR)')
         this.didWarnAboutDevelopmentLoaderReregistration = true
       }
       existing.set(key, loader)

package/src/lib/commands/scope.ts

@@ -3,6 +3,9 @@ import type { CommandRuntimeContext } from '@open-mercato/shared/lib/commands'
 import { isOrganizationAccessAllowed } from '@open-mercato/shared/lib/auth/organizationAccess'
 import { parseBooleanWithDefault } from '@open-mercato/shared/lib/boolean'
 import { env } from 'process'
+import { createLogger } from '../logger'
+
+const logger = createLogger('shared').child({ component: 'scope' })
 
 function buildScopeLogContext(ctx: CommandRuntimeContext) {
   const requestInfo =
@@ -46,7 +49,7 @@ function logScopeViolation(
 ): void {
   try {
     if (env.NODE_ENV !== 'test') {
-      console.warn('[scope] Forbidden organization scope mismatch detected', {
+      logger.warn('Forbidden organization scope mismatch detected', {
         expectedId: expected,
         actualId: actual,
         ...buildScopeLogContext(ctx),
@@ -60,7 +63,7 @@ function logScopeViolation(
 function logUnscopedOrganizationAccess(ctx: CommandRuntimeContext, organizationId: string): void {
   try {
     if (env.NODE_ENV !== 'test') {
-      console.warn('[scope] Unscoped organization command executed without organization context', {
+      logger.warn('Unscoped organization command executed without organization context', {
         targetOrganizationId: organizationId,
         strictEnforcement: isStrictOrganizationScopeEnforced(),
         ...buildScopeLogContext(ctx),
@@ -78,7 +81,7 @@ function logTenantScopeViolation(
 ): void {
   try {
     if (env.NODE_ENV !== 'test') {
-      console.warn('[scope] Forbidden tenant scope mismatch detected', {
+      logger.warn('Forbidden tenant scope mismatch detected', {
         expectedTenantId,
         actualTenantId,
         ...buildScopeLogContext(ctx),

package/src/lib/crud/__tests__/optimistic-lock.test.ts

@@ -10,6 +10,21 @@ import {
   OPTIMISTIC_LOCK_HEADER_NAME,
 } from '../optimistic-lock-headers'
 import type { CrudMutationGuardValidateInput } from '../mutation-guard'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+
+jest.mock('@open-mercato/shared/lib/logger', () => {
+  const mocked = {
+    debug: jest.fn(),
+    info: jest.fn(),
+    warn: jest.fn(),
+    error: jest.fn(),
+    child: jest.fn(),
+  }
+  mocked.child.mockImplementation(() => mocked)
+  return { createLogger: jest.fn(() => mocked) }
+})
+const loggerError = createLogger('shared').error as jest.Mock
+
 
 describe('parseOptimisticLockEnv', () => {
   it('returns mode=all when unset (default ON)', () => {
@@ -476,7 +491,7 @@ describe('createGenericOptimisticLockReader', () => {
         throw new Error('column "deleted_at" does not exist')
       },
     } as never
-    const errorSpy = jest.spyOn(console, 'error').mockImplementation(() => {})
+    loggerError.mockClear()
     try {
       const result = await reader(em, {
         resourceKind: 'customers.tag',
@@ -487,12 +502,12 @@ describe('createGenericOptimisticLockReader', () => {
       // Fail-open control flow preserved: a query error must never 500 the mutation.
       expect(result).toBeNull()
       // ...but a misconfig must be visible, naming the affected resourceKind.
-      expect(errorSpy).toHaveBeenCalledTimes(1)
-      const [message] = errorSpy.mock.calls[0]
-      expect(String(message)).toContain('customers.tag')
-      expect(String(message)).toContain('[optimistic-lock]')
+      expect(loggerError).toHaveBeenCalledTimes(1)
+      const [message, fields] = loggerError.mock.calls[0]
+      expect(String(message)).toContain('optimistic locking is DISABLED')
+      expect(fields).toEqual(expect.objectContaining({ resourceKind: 'customers.tag' }))
     } finally {
-      errorSpy.mockRestore()
+      loggerError.mockClear()
     }
   })
 

package/src/lib/crud/__tests__/route-mutation-guard.test.ts

@@ -2,6 +2,21 @@ import type { AwilixContainer } from 'awilix'
 import { registerMutationGuards } from '../mutation-guard-store'
 import type { MutationGuard } from '../mutation-guard-registry'
 import { runRouteMutationGuards, toRegistryMutationOperation } from '../route-mutation-guard'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+
+jest.mock('@open-mercato/shared/lib/logger', () => {
+  const mocked = {
+    debug: jest.fn(),
+    info: jest.fn(),
+    warn: jest.fn(),
+    error: jest.fn(),
+    child: jest.fn(),
+  }
+  mocked.child.mockImplementation(() => mocked)
+  return { createLogger: jest.fn(() => mocked) }
+})
+const loggerError = createLogger('shared').error as jest.Mock
+
 
 type Registrations = Record<string, unknown>
 
@@ -146,7 +161,7 @@ describe('runRouteMutationGuards', () => {
   })
 
   it('swallows afterSuccess callback errors so a committed write still succeeds', async () => {
-    const consoleError = jest.spyOn(console, 'error').mockImplementation(() => {})
+    loggerError.mockClear()
     const guard = makeGuard({
       id: 'throwing-after-guard',
       validate: jest.fn().mockResolvedValue({ ok: true, shouldRunAfterSuccess: true }),
@@ -164,7 +179,7 @@ describe('runRouteMutationGuards', () => {
     expect(result.ok).toBe(true)
     if (!result.ok) throw new Error('expected passed result')
     await expect(result.runAfterSuccess()).resolves.toBeUndefined()
-    expect(consoleError).toHaveBeenCalled()
+    expect(loggerError).toHaveBeenCalledWith('Mutation guard afterSuccess failed', expect.objectContaining({ guardId: 'throwing-after-guard' }))
   })
 
   it('skips feature-gated guards when the caller lacks the feature', async () => {

package/src/lib/crud/__tests__/sync-event-runner.test.ts

@@ -1,6 +1,21 @@
 import { matchesEventPattern, collectSyncSubscribers, runSyncBeforeEvent, runSyncAfterEvent } from '../sync-event-runner'
 import type { SyncSubscriberEntry } from '../sync-subscriber-store'
 import type { SyncCrudEventPayload } from '../sync-event-types'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+
+jest.mock('@open-mercato/shared/lib/logger', () => {
+  const mocked = {
+    debug: jest.fn(),
+    info: jest.fn(),
+    warn: jest.fn(),
+    error: jest.fn(),
+    child: jest.fn(),
+  }
+  mocked.child.mockImplementation(() => mocked)
+  return { createLogger: jest.fn(() => mocked) }
+})
+const loggerError = createLogger('shared').error as jest.Mock
+
 
 describe('matchesEventPattern', () => {
   it('matches exact event ID', () => {
@@ -158,10 +173,9 @@ describe('runSyncAfterEvent', () => {
       handler: jest.fn().mockResolvedValue(undefined),
     }
 
-    const consoleSpy = jest.spyOn(console, 'error').mockImplementation()
+    loggerError.mockClear()
     await runSyncAfterEvent([s1, s2], basePayload, ctx)
     expect(s2.handler).toHaveBeenCalled()
-    expect(consoleSpy).toHaveBeenCalled()
-    consoleSpy.mockRestore()
+    expect(loggerError).toHaveBeenCalled()
   })
 })

package/src/lib/crud/advanced-filter-integration.ts

@@ -5,6 +5,9 @@ import {
   convertAdvancedFilterToWhere,
 } from '../query/advanced-filter'
 import { compileTreeToWhere, type AdvancedFilterTree } from '../query/advanced-filter-tree'
+import { createLogger } from '../logger'
+
+const logger = createLogger('shared').child({ component: 'crud' })
 
 function splitOrClauses(filters: Record<string, unknown>): {
   directFilters: Record<string, unknown>
@@ -142,7 +145,7 @@ export function consumeAdvancedFilterState(query: Record<string, unknown>): Adva
         if (!g[sentinel]) {
           g[sentinel] = true
           // eslint-disable-next-line no-console
-          console.warn('[advanced-filter] legacy v1 URL detected; auto-upgraded to v2 tree')
+          logger.warn('Legacy v1 advanced-filter URL detected; auto-upgraded to v2 tree')
         }
       }
     }

package/src/lib/crud/cache.ts

@@ -1,6 +1,9 @@
 import type { AwilixContainer } from 'awilix'
 import { runWithCacheTenant, type CacheStrategy } from '@open-mercato/cache'
 import { parseBooleanToken } from '../boolean'
+import { createLogger } from '../logger'
+
+const logger = createLogger('shared').child({ component: 'crud-cache' })
 
 export type CrudCacheIdentifiers = {
   id?: string | null
@@ -25,7 +28,7 @@ export function isCrudCacheDebugEnabled(): boolean {
 export function debugCrudCache(event: string, context: Record<string, unknown>) {
   if (!isCrudCacheDebugEnabled()) return
   try {
-    console.debug('[crud][cache]', event, context)
+    logger.debug(event, context)
   } catch {}
 }
 

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

@@ -6,6 +6,7 @@ import type { TenantDataEncryptionService } from '../encryption/tenantDataEncryp
 import { decryptCustomFieldValue, resolveTenantEncryptionService } from '../encryption/customFieldValues'
 import { parseBooleanToken } from '../boolean'
 import { extractCustomFieldEntries } from './custom-fields-client'
+import { createLogger } from '../logger'
 import {
   buildCustomFieldDefinitionIndexFromRows,
   normalizeDefinitionKey,
@@ -16,6 +17,8 @@ import {
   type CustomFieldDefinitionSummary,
 } from './custom-field-definition-index'
 
+const logger = createLogger('shared').child({ component: 'crud' })
+
 export type { CustomFieldDefinitionSummary, CustomFieldDefinitionIndex } from './custom-field-definition-index'
 
 export type CustomFieldSelectors = {
@@ -416,7 +419,7 @@ export async function loadCustomFieldDefinitionIndex(opts: LoadCustomFieldDefini
         return restored
       }
     } catch (err) {
-      console.warn('[crud:cf-def-cache] read failed', err)
+      logger.warn('Custom-field definition cache read failed', { err })
     }
   }
 
@@ -433,7 +436,7 @@ export async function loadCustomFieldDefinitionIndex(opts: LoadCustomFieldDefini
         tags: buildCfDefIndexCacheTags({ tenantId, entityIds }),
       })
     } catch (err) {
-      console.warn('[crud:cf-def-cache] write failed', err)
+      logger.warn('Custom-field definition cache write failed', { err })
     }
   }
   if (requestBucket) requestBucket.set(cacheKey, index)

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

@@ -14,6 +14,9 @@ import type {
 } from './response-enricher'
 import { getEnrichersForEntity } from './enricher-registry'
 import { logEnricherTiming } from '../umes/enricher-timing'
+import { createLogger } from '../logger'
+
+const logger = createLogger('shared').child({ component: 'umes' })
 
 const DEFAULT_TIMEOUT = 2000
 const SLOW_WARN_MS = 100
@@ -263,13 +266,9 @@ export async function applyResponseEnrichers<T extends Record<string, unknown>>(
 
       const elapsedMs = Date.now() - startTime
       if (elapsedMs > SLOW_ERROR_MS) {
-        console.error(
-          `[UMES] Enricher ${enricher.id} took ${elapsedMs}ms (threshold: ${SLOW_ERROR_MS}ms)`,
-        )
+        logger.error('Enricher exceeded slow threshold', { enricherId: enricher.id, elapsedMs, thresholdMs: SLOW_ERROR_MS })
       } else if (elapsedMs > SLOW_WARN_MS) {
-        console.warn(
-          `[UMES] Enricher ${enricher.id} took ${elapsedMs}ms (threshold: ${SLOW_WARN_MS}ms)`,
-        )
+        logger.warn('Enricher exceeded slow threshold', { enricherId: enricher.id, elapsedMs, thresholdMs: SLOW_WARN_MS })
       }
       logEnricherTiming(enricher.id, entry.moduleId, targetEntity, elapsedMs)
 
@@ -289,8 +288,7 @@ export async function applyResponseEnrichers<T extends Record<string, unknown>>(
         throw err
       }
 
-      const message = err instanceof Error ? err.message : String(err)
-      console.warn(`[UMES] Enricher ${enricher.id} failed: ${message}`)
+      logger.warn('Enricher failed', { enricherId: enricher.id, err })
       enricherErrors.push(enricher.id)
 
       if (enricher.fallback) {
@@ -376,8 +374,7 @@ export async function applyResponseEnricherToRecord<T extends Record<string, unk
         throw err
       }
 
-      const message = err instanceof Error ? err.message : String(err)
-      console.warn(`[UMES] Enricher ${enricher.id} failed: ${message}`)
+      logger.warn('Enricher failed', { enricherId: enricher.id, err })
       enricherErrors.push(enricher.id)
 
       if (enricher.fallback) {