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

package/dist/lib/crud/enricher-runner.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/lib/crud/enricher-runner.ts"],
-  "sourcesContent": ["/**\n * Response Enricher Runner\n *\n * Executes response enrichers against API response payloads.\n * Handles timeout, fallback, ACL feature gating, and error isolation.\n */\n\nimport type {\n  EnricherContext,\n  EnricherRegistryEntry,\n  EnrichmentResult,\n  ResponseEnricher,\n  SingleEnrichmentResult,\n} from './response-enricher'\nimport { getEnrichersForEntity } from './enricher-registry'\nimport { logEnricherTiming } from '../umes/enricher-timing'\nimport { createLogger } from '../logger'\nimport { authorizeFeatures } from '../../security/featurePolicy'\n\nconst logger = createLogger('shared').child({ component: 'umes' })\n\nconst DEFAULT_TIMEOUT = 2000\nconst SLOW_WARN_MS = 100\nconst SLOW_ERROR_MS = 500\nconst DEFAULT_CACHE_TTL_MS = 60_000\n\nfunction timeoutPromise(ms: number): Promise<never> {\n  return new Promise((_, reject) =>\n    setTimeout(() => reject(new Error(`Enricher timed out after ${ms}ms`)), ms),\n  )\n}\n\nfunction hasRequiredFeatures(\n  enricher: ResponseEnricher,\n  userFeatures: string[] | undefined,\n): boolean {\n  if (!enricher.features || enricher.features.length === 0) return true\n  if (!userFeatures) return false\n  return authorizeFeatures(enricher.features, { grantedFeatures: userFeatures })\n}\n\nfunction filterByACLAndTenant(\n  entries: EnricherRegistryEntry[],\n  context: EnricherContext,\n): EnricherRegistryEntry[] {\n  return entries.filter((entry) => {\n    const enricher = entry.enricher\n    if (!hasRequiredFeatures(enricher, context.userFeatures)) return false\n    if (enricher.disabledTenantIds?.includes(context.tenantId)) return false\n    return true\n  })\n}\n\nfunction getActiveEnrichers(\n  targetEntity: string,\n  context: EnricherContext,\n): EnricherRegistryEntry[] {\n  const entries = getEnrichersForEntity(targetEntity)\n  return filterByACLAndTenant(entries, context)\n}\n\n/**\n * Plan describing whether (and how) a CRUD list cache may embed enricher output.\n */\nexport type ListCacheEnricherPlan = {\n  /**\n   * Stable signature of the active, cache-embeddable enrichers in registry\n   * (priority) order. Included in the CRUD list cache key so a cached enriched\n   * payload is only ever served back to a request whose entitlements select the\n   * exact same enricher set. Empty string when nothing is embeddable \u2014 keeping\n   * the cache key identical to the pre-enricher shape for unaffected routes.\n   */\n  signature: string\n  /**\n   * True only when there is at least one active enricher for the context AND\n   * every active enricher opted into `cacheableOnListHit`. When true, the\n   * enriched list payload may be stored in the cache and served on a hit without\n   * re-running enrichers. When false, enrichers MUST re-run on every request so\n   * the response reflects live data (cross-module reads, wall-clock values, etc.)\n   * and no live enrichment is embedded in the shared cache entry.\n   */\n  skipEnrichersOnCacheHit: boolean\n}\n\n/**\n * Resolve, for the given context, whether the CRUD list cache may embed enricher\n * output and the cache-key signature to partition by when it can.\n *\n * The enriched payload is only embeddable (and the cache hit allowed to skip\n * enrichment) when every active enricher is `cacheableOnListHit` \u2014 i.e. its\n * output is a pure function of the cached record and invalidated together with\n * it. If any active enricher reads data the list cache does not invalidate on,\n * the route falls back to caching the pre-enrichment payload and re-running\n * enrichers on every request.\n */\nexport function resolveListCacheEnricherPlan(\n  targetEntity: string,\n  context: EnricherContext,\n): ListCacheEnricherPlan {\n  const active = getActiveEnrichers(targetEntity, context)\n  if (active.length === 0) return { signature: '', skipEnrichersOnCacheHit: false }\n  const allCacheable = active.every((entry) => entry.enricher.cacheableOnListHit === true)\n  if (!allCacheable) return { signature: '', skipEnrichersOnCacheHit: false }\n  return {\n    signature: active.map((entry) => entry.enricher.id).join(','),\n    skipEnrichersOnCacheHit: true,\n  }\n}\n\ntype CacheLike = {\n  get: (key: string) => Promise<unknown>\n  set: (key: string, value: unknown, options?: { ttl?: number; tags?: string[] }) => Promise<unknown>\n}\n\nfunction resolveCache(context: EnricherContext): CacheLike | null {\n  const container = context.container as { resolve?: (name: string) => unknown } | undefined\n  if (!container?.resolve) return null\n  try {\n    const cache = container.resolve('cache') as CacheLike\n    if (cache && typeof cache.get === 'function' && typeof cache.set === 'function') {\n      return cache\n    }\n  } catch {\n    // ignore cache resolution failures\n  }\n  try {\n    const cacheService = container.resolve('cacheService') as CacheLike\n    if (cacheService && typeof cacheService.get === 'function' && typeof cacheService.set === 'function') {\n      return cacheService\n    }\n  } catch {\n    // ignore cache service resolution failures\n  }\n  return null\n}\n\nfunction buildCacheKey(\n  enricher: ResponseEnricher,\n  context: EnricherContext,\n  mode: 'one' | 'many',\n  recordIds: string[],\n): string {\n  const sortedIds = [...recordIds].sort((a, b) => a.localeCompare(b))\n  return `umes:enricher:${enricher.id}:tenant:${context.tenantId}:org:${context.organizationId}:mode:${mode}:ids:${JSON.stringify(sortedIds)}`\n}\n\nfunction extractRecordId(record: Record<string, unknown>): string {\n  const idValue = record.id\n  if (typeof idValue === 'string' && idValue.trim().length > 0) return idValue.trim()\n  if (typeof idValue === 'number') return String(idValue)\n  return 'unknown'\n}\n\nfunction getEnricherCacheTtl(enricher: ResponseEnricher): number {\n  const ttl = enricher.cache?.ttl\n  if (typeof ttl === 'number' && Number.isFinite(ttl) && ttl > 0) {\n    return ttl\n  }\n  return DEFAULT_CACHE_TTL_MS\n}\n\nfunction getEnricherCacheTags(enricher: ResponseEnricher, context: EnricherContext): string[] {\n  const tags = new Set<string>([\n    `tenant:${context.tenantId}`,\n    `organization:${context.organizationId}`,\n    `enricher:${enricher.id}`,\n  ])\n  for (const tag of enricher.cache?.tags ?? []) {\n    if (!tag || tag.trim().length === 0) continue\n    tags.add(tag)\n  }\n  return Array.from(tags)\n}\n\nasync function readEnricherCache<T>(\n  cache: CacheLike | null,\n  key: string,\n): Promise<T | null> {\n  if (!cache) return null\n  try {\n    const value = await cache.get(key)\n    return value == null ? null : (value as T)\n  } catch {\n    return null\n  }\n}\n\nasync function writeEnricherCache(\n  cache: CacheLike | null,\n  key: string,\n  value: unknown,\n  ttl: number,\n  tags: string[],\n): Promise<void> {\n  if (!cache) return\n  try {\n    await cache.set(key, value, { ttl, tags })\n  } catch {\n    // ignore cache write failures\n  }\n}\n\n/**\n * Apply response enrichers to a list of records.\n *\n * Runs AFTER CrudHooks.afterList, BEFORE HTTP response serialization.\n * Each enricher runs independently \u2014 a failed non-critical enricher is skipped.\n */\nexport async function applyResponseEnrichers<T extends Record<string, unknown>>(\n  items: T[],\n  targetEntity: string,\n  context: EnricherContext,\n  preFilteredEntries?: EnricherRegistryEntry[],\n): Promise<EnrichmentResult<T>> {\n  const activeEntries = preFilteredEntries\n    ? filterByACLAndTenant(preFilteredEntries, context)\n    : getActiveEnrichers(targetEntity, context)\n\n  if (activeEntries.length === 0) {\n    return { items, _meta: { enrichedBy: [] } }\n  }\n\n  const enrichedBy: string[] = []\n  const enricherErrors: string[] = []\n  let currentItems = items\n  const cache = resolveCache(context)\n\n  for (const entry of activeEntries) {\n    const enricher = entry.enricher\n    const timeout = enricher.timeout ?? DEFAULT_TIMEOUT\n    const startTime = Date.now()\n\n    try {\n      let result: T[]\n      const recordIds = currentItems.map((item) => extractRecordId(item))\n      const shouldUseCache = enricher.cache?.strategy === 'read-through'\n      const cacheKey = shouldUseCache ? buildCacheKey(enricher, context, 'many', recordIds) : null\n      if (shouldUseCache && cacheKey) {\n        const cached = await readEnricherCache<T[]>(cache, cacheKey)\n        if (cached) {\n          currentItems = cached\n          enrichedBy.push(enricher.id)\n          continue\n        }\n      }\n\n      if (enricher.enrichMany) {\n        result = await Promise.race([\n          enricher.enrichMany(currentItems, context) as Promise<T[]>,\n          timeoutPromise(timeout),\n        ])\n      } else {\n        throw new Error(\n          `Enricher ${enricher.id} must implement enrichMany() for list endpoints`,\n        )\n      }\n\n      const elapsedMs = Date.now() - startTime\n      if (elapsedMs > SLOW_ERROR_MS) {\n        logger.error('Enricher exceeded slow threshold', { enricherId: enricher.id, elapsedMs, thresholdMs: SLOW_ERROR_MS })\n      } else if (elapsedMs > SLOW_WARN_MS) {\n        logger.warn('Enricher exceeded slow threshold', { enricherId: enricher.id, elapsedMs, thresholdMs: SLOW_WARN_MS })\n      }\n      logEnricherTiming(enricher.id, entry.moduleId, targetEntity, elapsedMs)\n\n      currentItems = result\n      if (shouldUseCache && cacheKey) {\n        await writeEnricherCache(\n          cache,\n          cacheKey,\n          result,\n          getEnricherCacheTtl(enricher),\n          getEnricherCacheTags(enricher, context),\n        )\n      }\n      enrichedBy.push(enricher.id)\n    } catch (err) {\n      if (enricher.critical) {\n        throw err\n      }\n\n      logger.warn('Enricher failed', { enricherId: enricher.id, err })\n      enricherErrors.push(enricher.id)\n\n      if (enricher.fallback) {\n        currentItems = currentItems.map((item) => ({\n          ...item,\n          ...enricher.fallback,\n        })) as T[]\n      }\n    }\n  }\n\n  return {\n    items: currentItems,\n    _meta: {\n      enrichedBy,\n      ...(enricherErrors.length > 0 ? { enricherErrors } : {}),\n    },\n  }\n}\n\n/**\n * Apply response enrichers to a single record.\n *\n * Used for detail endpoints (GET /:id), POST, and PUT responses.\n */\nexport async function applyResponseEnricherToRecord<T extends Record<string, unknown>>(\n  record: T,\n  targetEntity: string,\n  context: EnricherContext,\n  preFilteredEntries?: EnricherRegistryEntry[],\n): Promise<SingleEnrichmentResult<T>> {\n  const activeEntries = preFilteredEntries\n    ? filterByACLAndTenant(preFilteredEntries, context)\n    : getActiveEnrichers(targetEntity, context)\n\n  if (activeEntries.length === 0) {\n    return { record, _meta: { enrichedBy: [] } }\n  }\n\n  const enrichedBy: string[] = []\n  const enricherErrors: string[] = []\n  let currentRecord = record\n  const cache = resolveCache(context)\n\n  for (const entry of activeEntries) {\n    const enricher = entry.enricher\n    const timeout = enricher.timeout ?? DEFAULT_TIMEOUT\n    const startTime = Date.now()\n\n    try {\n      const recordId = extractRecordId(currentRecord)\n      const shouldUseCache = enricher.cache?.strategy === 'read-through'\n      const cacheKey = shouldUseCache ? buildCacheKey(enricher, context, 'one', [recordId]) : null\n      if (shouldUseCache && cacheKey) {\n        const cached = await readEnricherCache<T>(cache, cacheKey)\n        if (cached) {\n          currentRecord = cached\n          enrichedBy.push(enricher.id)\n          continue\n        }\n      }\n      const result = await Promise.race([\n        enricher.enrichOne(currentRecord, context) as Promise<T>,\n        timeoutPromise(timeout),\n      ])\n\n      const elapsedMs = Date.now() - startTime\n      logEnricherTiming(enricher.id, entry.moduleId, targetEntity, elapsedMs)\n\n      currentRecord = result\n      if (shouldUseCache && cacheKey) {\n        await writeEnricherCache(\n          cache,\n          cacheKey,\n          result,\n          getEnricherCacheTtl(enricher),\n          getEnricherCacheTags(enricher, context),\n        )\n      }\n      enrichedBy.push(enricher.id)\n    } catch (err) {\n      if (enricher.critical) {\n        throw err\n      }\n\n      logger.warn('Enricher failed', { enricherId: enricher.id, err })\n      enricherErrors.push(enricher.id)\n\n      if (enricher.fallback) {\n        currentRecord = { ...currentRecord, ...enricher.fallback } as T\n      }\n    }\n  }\n\n  return {\n    record: currentRecord,\n    _meta: {\n      enrichedBy,\n      ...(enricherErrors.length > 0 ? { enricherErrors } : {}),\n    },\n  }\n}\n"],
-  "mappings": "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",
+  "sourcesContent": ["/**\n * Response Enricher Runner\n *\n * Executes response enrichers against API response payloads.\n * Handles timeout, fallback, ACL feature gating, and error isolation.\n */\n\nimport type {\n  EnricherContext,\n  EnricherRegistryEntry,\n  EnrichmentResult,\n  ResponseEnricher,\n  SingleEnrichmentResult,\n} from './response-enricher'\nimport { getEnrichersForEntity } from './enricher-registry'\nimport { logEnricherTiming } from '../umes/enricher-timing'\nimport { createLogger } from '../logger'\nimport { authorizeFeatures } from '../../security/featurePolicy'\n\nconst logger = createLogger('shared').child({ component: 'umes' })\n\nconst DEFAULT_TIMEOUT = 2000\nconst SLOW_WARN_MS = 100\nconst SLOW_ERROR_MS = 500\nconst DEFAULT_CACHE_TTL_MS = 60_000\n\nfunction timeoutPromise(ms: number): Promise<never> {\n  return new Promise((_, reject) =>\n    setTimeout(() => reject(new Error(`Enricher timed out after ${ms}ms`)), ms),\n  )\n}\n\nfunction hasRequiredFeatures(\n  enricher: ResponseEnricher,\n  userFeatures: string[] | undefined,\n): boolean {\n  if (!enricher.features || enricher.features.length === 0) return true\n  if (!userFeatures) return false\n  return authorizeFeatures(enricher.features, { grantedFeatures: userFeatures })\n}\n\nfunction filterByACLAndTenant(\n  entries: EnricherRegistryEntry[],\n  context: EnricherContext,\n): EnricherRegistryEntry[] {\n  return entries.filter((entry) => {\n    const enricher = entry.enricher\n    if (!hasRequiredFeatures(enricher, context.userFeatures)) return false\n    if (enricher.disabledTenantIds?.includes(context.tenantId)) return false\n    return true\n  })\n}\n\nfunction getActiveEnrichers(\n  targetEntity: string,\n  context: EnricherContext,\n): EnricherRegistryEntry[] {\n  const entries = getEnrichersForEntity(targetEntity)\n  return filterByACLAndTenant(entries, context)\n}\n\n/**\n * Plan describing whether (and how) a CRUD list cache may embed enricher output.\n */\nexport type ListCacheEnricherPlan = {\n  /**\n   * Stable signature of the active, cache-embeddable enrichers in registry\n   * (priority) order. Included in the CRUD list cache key so a cached enriched\n   * payload is only ever served back to a request whose entitlements select the\n   * exact same enricher set. Empty string when nothing is embeddable \u2014 keeping\n   * the cache key identical to the pre-enricher shape for unaffected routes.\n   */\n  signature: string\n  /**\n   * True only when there is at least one active enricher for the context AND\n   * every active enricher opted into `cacheableOnListHit`. When true, the\n   * enriched list payload may be stored in the cache and served on a hit without\n   * re-running enrichers. When false, enrichers MUST re-run on every request so\n   * the response reflects live data (cross-module reads, wall-clock values, etc.)\n   * and no live enrichment is embedded in the shared cache entry.\n   */\n  skipEnrichersOnCacheHit: boolean\n}\n\n/**\n * Resolve, for the given context, whether the CRUD list cache may embed enricher\n * output and the cache-key signature to partition by when it can.\n *\n * The enriched payload is only embeddable (and the cache hit allowed to skip\n * enrichment) when every active enricher is `cacheableOnListHit` \u2014 i.e. its\n * output is a pure function of the cached record and invalidated together with\n * it. If any active enricher reads data the list cache does not invalidate on,\n * the route falls back to caching the pre-enrichment payload and re-running\n * enrichers on every request.\n */\nexport function resolveListCacheEnricherPlan(\n  targetEntity: string,\n  context: EnricherContext,\n): ListCacheEnricherPlan {\n  const active = getActiveEnrichers(targetEntity, context)\n  if (active.length === 0) return { signature: '', skipEnrichersOnCacheHit: false }\n  const allCacheable = active.every((entry) => entry.enricher.cacheableOnListHit === true)\n  if (!allCacheable) return { signature: '', skipEnrichersOnCacheHit: false }\n  return {\n    signature: active.map((entry) => entry.enricher.id).join(','),\n    skipEnrichersOnCacheHit: true,\n  }\n}\n\ntype CacheLike = {\n  get: (key: string) => Promise<unknown>\n  set: (key: string, value: unknown, options?: { ttl?: number; tags?: string[] }) => Promise<unknown>\n}\n\nfunction resolveCache(context: EnricherContext): CacheLike | null {\n  const container = context.container as { resolve?: (name: string) => unknown } | undefined\n  if (!container?.resolve) return null\n  try {\n    const cache = container.resolve('cache') as CacheLike\n    if (cache && typeof cache.get === 'function' && typeof cache.set === 'function') {\n      return cache\n    }\n  } catch {\n    // ignore cache resolution failures\n  }\n  try {\n    const cacheService = container.resolve('cacheService') as CacheLike\n    if (cacheService && typeof cacheService.get === 'function' && typeof cacheService.set === 'function') {\n      return cacheService\n    }\n  } catch {\n    // ignore cache service resolution failures\n  }\n  return null\n}\n\nfunction buildCacheKey(\n  enricher: ResponseEnricher,\n  context: EnricherContext,\n  targetEntity: string,\n  mode: 'one' | 'many',\n  recordIds: string[],\n): string {\n  const sortedIds = [...recordIds].sort((a, b) => a.localeCompare(b))\n  return `umes:enricher:${enricher.id}:entity:${targetEntity}:tenant:${context.tenantId}:org:${context.organizationId}:mode:${mode}:ids:${JSON.stringify(sortedIds)}`\n}\n\nconst UNKNOWN_RECORD_ID = 'unknown'\n\nfunction extractRecordId(record: Record<string, unknown>): string {\n  const idValue = record.id\n  if (typeof idValue === 'string' && idValue.trim().length > 0) return idValue.trim()\n  if (typeof idValue === 'number') return String(idValue)\n  return UNKNOWN_RECORD_ID\n}\n\nfunction getEnricherCacheTtl(enricher: ResponseEnricher): number {\n  const ttl = enricher.cache?.ttl\n  if (typeof ttl === 'number' && Number.isFinite(ttl) && ttl > 0) {\n    return ttl\n  }\n  return DEFAULT_CACHE_TTL_MS\n}\n\nfunction getEnricherCacheTags(enricher: ResponseEnricher, context: EnricherContext): string[] {\n  const tags = new Set<string>([\n    `tenant:${context.tenantId}`,\n    `organization:${context.organizationId}`,\n    `enricher:${enricher.id}`,\n  ])\n  for (const tag of enricher.cache?.tags ?? []) {\n    if (!tag || tag.trim().length === 0) continue\n    tags.add(tag)\n  }\n  return Array.from(tags)\n}\n\nasync function readEnricherCache<T>(\n  cache: CacheLike | null,\n  key: string,\n): Promise<T | null> {\n  if (!cache) return null\n  try {\n    const value = await cache.get(key)\n    return value == null ? null : (value as T)\n  } catch {\n    return null\n  }\n}\n\n/**\n * The cache write was skipped because no safe envelope could be built. Logged\n * rather than swallowed: from outside the runner a silently-skipped write is\n * indistinguishable from a broken cache, and \"this enricher is not purely\n * additive\" is the answer an author needs to see.\n */\nfunction logSkippedCacheWrite(enricher: ResponseEnricher): void {\n  logger.debug('Skipped enricher cache write \u2014 enrichment is not purely additive or lacks usable record ids', {\n    enricherId: enricher.id,\n  })\n}\n\nasync function writeEnricherCache(\n  cache: CacheLike | null,\n  key: string,\n  value: unknown,\n  ttl: number,\n  tags: string[],\n): Promise<void> {\n  if (!cache) return\n  try {\n    await cache.set(key, value, { ttl, tags })\n  } catch {\n    // ignore cache write failures\n  }\n}\n\n/**\n * Cached read-through payload: the fields each enricher ADDED, keyed by record id.\n *\n * Caching whole records would replace the freshly-read record with the snapshot\n * taken at write time, so an edit to a base field (a product's name, an order's\n * status) would not surface until the entry expired, and a cached array would\n * also carry \u2014 and therefore overwrite \u2014 whatever the previous enricher in the\n * chain contributed. The additive delta is a pure function of the enricher, the\n * tenant/organization scope and the record ids, which is exactly what the cache\n * key already encodes, so it is the only part of the result that is safe to reuse.\n */\ntype EnricherCacheEnvelope = {\n  version: 1\n  deltas: Record<string, Record<string, unknown>>\n}\n\nconst ENRICHER_CACHE_VERSION = 1\n\nfunction isEnricherCacheEnvelope(value: unknown): value is EnricherCacheEnvelope {\n  if (typeof value !== 'object' || value === null) return false\n  const candidate = value as { version?: unknown; deltas?: unknown }\n  if (candidate.version !== ENRICHER_CACHE_VERSION) return false\n  return typeof candidate.deltas === 'object' && candidate.deltas !== null\n}\n\n/**\n * The keys an enricher added to a record, or `null` when the enrichment was not\n * purely additive \u2014 it changed or dropped a key that was already there. A\n * non-additive enricher is never cached: replaying only its added keys onto a\n * later record would silently lose the change it made to the existing ones.\n *\n * Comparison is by identity at the top level only, so an enricher that mutates a\n * nested object in place is indistinguishable from one that left the record\n * alone: its nested change is absent from the delta and therefore lost on a\n * later hit. That fails safe \u2014 the served record is under-enriched, never\n * stale-wrong \u2014 and a deep clone of every record on every enriched response is\n * not worth paying for the case.\n */\nfunction computeAdditiveDelta(\n  input: Record<string, unknown>,\n  output: Record<string, unknown>,\n): Record<string, unknown> | null {\n  const delta: Record<string, unknown> = {}\n  for (const key of Object.keys(input)) {\n    if (!Object.prototype.hasOwnProperty.call(output, key)) return null\n    if (output[key] !== input[key]) return null\n  }\n  for (const key of Object.keys(output)) {\n    if (Object.prototype.hasOwnProperty.call(input, key)) continue\n    delta[key] = output[key]\n  }\n  return delta\n}\n\n/**\n * Build the cacheable envelope for a batch, or `null` when it cannot be built\n * safely \u2014 an unusable record id, a duplicate id (the deltas would collide), or\n * a non-additive enrichment. Every failure mode skips the cache write and leaves\n * the enricher running on every request, which is the pre-cache behavior.\n */\nfunction buildCacheEnvelope<T extends Record<string, unknown>>(\n  inputs: T[],\n  outputs: T[],\n): EnricherCacheEnvelope | null {\n  if (inputs.length !== outputs.length) return null\n  const deltas: Record<string, Record<string, unknown>> = {}\n  for (let index = 0; index < inputs.length; index += 1) {\n    const recordId = extractRecordId(inputs[index])\n    if (recordId === UNKNOWN_RECORD_ID) return null\n    if (Object.prototype.hasOwnProperty.call(deltas, recordId)) return null\n    const delta = computeAdditiveDelta(inputs[index], outputs[index])\n    if (!delta) return null\n    deltas[recordId] = delta\n  }\n  return { version: ENRICHER_CACHE_VERSION, deltas }\n}\n\n/**\n * Merge a cached envelope onto freshly-read records. Returns `null` \u2014 a miss \u2014\n * when the envelope does not cover every record, so a partially-cached batch\n * re-runs the enricher rather than returning some records unenriched.\n */\nfunction applyCacheEnvelope<T extends Record<string, unknown>>(\n  envelope: EnricherCacheEnvelope,\n  records: T[],\n): T[] | null {\n  const merged: T[] = []\n  for (const record of records) {\n    const recordId = extractRecordId(record)\n    if (recordId === UNKNOWN_RECORD_ID) return null\n    const delta = envelope.deltas[recordId]\n    if (!delta || typeof delta !== 'object') return null\n    merged.push({ ...record, ...delta } as T)\n  }\n  return merged\n}\n\n/**\n * Apply response enrichers to a list of records.\n *\n * Runs AFTER CrudHooks.afterList, BEFORE HTTP response serialization.\n * Each enricher runs independently \u2014 a failed non-critical enricher is skipped.\n */\nexport async function applyResponseEnrichers<T extends Record<string, unknown>>(\n  items: T[],\n  targetEntity: string,\n  context: EnricherContext,\n  preFilteredEntries?: EnricherRegistryEntry[],\n): Promise<EnrichmentResult<T>> {\n  const enricherContext: EnricherContext = { ...context, targetEntity }\n  const activeEntries = preFilteredEntries\n    ? filterByACLAndTenant(preFilteredEntries, context)\n    : getActiveEnrichers(targetEntity, context)\n\n  if (activeEntries.length === 0) {\n    return { items, _meta: { enrichedBy: [] } }\n  }\n\n  const enrichedBy: string[] = []\n  const enricherErrors: string[] = []\n  let currentItems = items\n  const cache = resolveCache(context)\n\n  for (const entry of activeEntries) {\n    const enricher = entry.enricher\n    const timeout = enricher.timeout ?? DEFAULT_TIMEOUT\n    const startTime = Date.now()\n\n    try {\n      let result: T[]\n      const recordIds = currentItems.map((item) => extractRecordId(item))\n      const shouldUseCache = enricher.cache?.strategy === 'read-through'\n      const cacheKey = shouldUseCache\n        ? buildCacheKey(enricher, context, targetEntity, 'many', recordIds)\n        : null\n      // Snapshot BEFORE enrichment: the contract does not forbid an enricher\n      // from mutating the records it was handed, and comparing a mutated record\n      // against itself would yield an empty delta \u2014 caching \"this enricher adds\n      // nothing\" and serving unenriched records for the rest of the TTL.\n      const inputItems = shouldUseCache ? currentItems.map((item) => ({ ...item })) : currentItems\n      if (shouldUseCache && cacheKey) {\n        const cached = await readEnricherCache<unknown>(cache, cacheKey)\n        if (isEnricherCacheEnvelope(cached)) {\n          const merged = applyCacheEnvelope(cached, currentItems)\n          if (merged) {\n            currentItems = merged\n            enrichedBy.push(enricher.id)\n            continue\n          }\n        }\n      }\n\n      if (enricher.enrichMany) {\n        result = await Promise.race([\n          enricher.enrichMany(currentItems, enricherContext) as Promise<T[]>,\n          timeoutPromise(timeout),\n        ])\n      } else {\n        throw new Error(\n          `Enricher ${enricher.id} must implement enrichMany() for list endpoints`,\n        )\n      }\n\n      const elapsedMs = Date.now() - startTime\n      if (elapsedMs > SLOW_ERROR_MS) {\n        logger.error('Enricher exceeded slow threshold', { enricherId: enricher.id, elapsedMs, thresholdMs: SLOW_ERROR_MS })\n      } else if (elapsedMs > SLOW_WARN_MS) {\n        logger.warn('Enricher exceeded slow threshold', { enricherId: enricher.id, elapsedMs, thresholdMs: SLOW_WARN_MS })\n      }\n      logEnricherTiming(enricher.id, entry.moduleId, targetEntity, elapsedMs)\n\n      currentItems = result\n      if (shouldUseCache && cacheKey) {\n        const envelope = buildCacheEnvelope(inputItems, result)\n        if (envelope) {\n          await writeEnricherCache(\n            cache,\n            cacheKey,\n            envelope,\n            getEnricherCacheTtl(enricher),\n            getEnricherCacheTags(enricher, context),\n          )\n        } else {\n          logSkippedCacheWrite(enricher)\n        }\n      }\n      enrichedBy.push(enricher.id)\n    } catch (err) {\n      if (enricher.critical) {\n        throw err\n      }\n\n      logger.warn('Enricher failed', { enricherId: enricher.id, err })\n      enricherErrors.push(enricher.id)\n\n      if (enricher.fallback) {\n        currentItems = currentItems.map((item) => ({\n          ...item,\n          ...enricher.fallback,\n        })) as T[]\n      }\n    }\n  }\n\n  return {\n    items: currentItems,\n    _meta: {\n      enrichedBy,\n      ...(enricherErrors.length > 0 ? { enricherErrors } : {}),\n    },\n  }\n}\n\n/**\n * Apply response enrichers to a single record.\n *\n * Used for detail endpoints (GET /:id), POST, and PUT responses.\n */\nexport async function applyResponseEnricherToRecord<T extends Record<string, unknown>>(\n  record: T,\n  targetEntity: string,\n  context: EnricherContext,\n  preFilteredEntries?: EnricherRegistryEntry[],\n): Promise<SingleEnrichmentResult<T>> {\n  const enricherContext: EnricherContext = { ...context, targetEntity }\n  const activeEntries = preFilteredEntries\n    ? filterByACLAndTenant(preFilteredEntries, context)\n    : getActiveEnrichers(targetEntity, context)\n\n  if (activeEntries.length === 0) {\n    return { record, _meta: { enrichedBy: [] } }\n  }\n\n  const enrichedBy: string[] = []\n  const enricherErrors: string[] = []\n  let currentRecord = record\n  const cache = resolveCache(context)\n\n  for (const entry of activeEntries) {\n    const enricher = entry.enricher\n    const timeout = enricher.timeout ?? DEFAULT_TIMEOUT\n    const startTime = Date.now()\n\n    try {\n      const recordId = extractRecordId(currentRecord)\n      const shouldUseCache = enricher.cache?.strategy === 'read-through'\n      const cacheKey = shouldUseCache\n        ? buildCacheKey(enricher, context, targetEntity, 'one', [recordId])\n        : null\n      // Snapshot before enrichment \u2014 see the list path for why.\n      const inputRecord = shouldUseCache ? ({ ...currentRecord } as T) : currentRecord\n      if (shouldUseCache && cacheKey) {\n        const cached = await readEnricherCache<unknown>(cache, cacheKey)\n        if (isEnricherCacheEnvelope(cached)) {\n          const merged = applyCacheEnvelope(cached, [currentRecord])\n          if (merged) {\n            currentRecord = merged[0]\n            enrichedBy.push(enricher.id)\n            continue\n          }\n        }\n      }\n      const result = await Promise.race([\n        enricher.enrichOne(currentRecord, enricherContext) as Promise<T>,\n        timeoutPromise(timeout),\n      ])\n\n      const elapsedMs = Date.now() - startTime\n      logEnricherTiming(enricher.id, entry.moduleId, targetEntity, elapsedMs)\n\n      currentRecord = result\n      if (shouldUseCache && cacheKey) {\n        const envelope = buildCacheEnvelope([inputRecord], [result])\n        if (envelope) {\n          await writeEnricherCache(\n            cache,\n            cacheKey,\n            envelope,\n            getEnricherCacheTtl(enricher),\n            getEnricherCacheTags(enricher, context),\n          )\n        } else {\n          logSkippedCacheWrite(enricher)\n        }\n      }\n      enrichedBy.push(enricher.id)\n    } catch (err) {\n      if (enricher.critical) {\n        throw err\n      }\n\n      logger.warn('Enricher failed', { enricherId: enricher.id, err })\n      enricherErrors.push(enricher.id)\n\n      if (enricher.fallback) {\n        currentRecord = { ...currentRecord, ...enricher.fallback } as T\n      }\n    }\n  }\n\n  return {\n    record: currentRecord,\n    _meta: {\n      enrichedBy,\n      ...(enricherErrors.length > 0 ? { enricherErrors } : {}),\n    },\n  }\n}\n"],
+  "mappings": "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",
   "names": []
 }

package/dist/lib/crud/factory.js

@@ -54,7 +54,7 @@ import { parseExtensionHeaders } from "../umes/extension-headers.js";
 import { createGenericOptimisticLockReader } from "./optimistic-lock.js";
 import { registerOptimisticLockReaderIfAbsent } from "./optimistic-lock-store.js";
 import { createLogger } from "../logger/index.js";
-import { isTransientDbError } from "../db/pg-errors.js";
+import { getForeignKeyViolationConstraint, isForeignKeyViolation, isTransientDbError } from "../db/pg-errors.js";
 import { getTelemetryRuntime } from "../telemetry/runtime.js";
 import { randomUUID } from "node:crypto";
 const logger = createLogger("shared").child({ component: "crud" });
@@ -324,6 +324,27 @@ function handleError(err, request) {
       { status: 503, headers: { "Retry-After": "2" } }
     );
   }
+  if (isForeignKeyViolation(err)) {
+    const requestId2 = resolveRequestId(request);
+    const constraint = getForeignKeyViolationConstraint(err);
+    logger.warn("Foreign key violation during CRUD handler", {
+      message: err instanceof Error ? err.message : void 0,
+      constraint,
+      requestId: requestId2
+    });
+    getTelemetryRuntime()?.reportError(err, {
+      module: "crud",
+      attributes: { requestId: requestId2, errorName: "ForeignKeyViolation", constraint: constraint ?? void 0 }
+    });
+    return json(
+      {
+        error: "The record is still referenced by other data, or references a record that does not exist",
+        code: "FOREIGN_KEY_VIOLATION",
+        requestId: requestId2
+      },
+      { status: 409, headers: { "x-request-id": requestId2 } }
+    );
+  }
   const message = err instanceof Error ? err.message : void 0;
   const stack = err instanceof Error ? err.stack : void 0;
   const errorName = err instanceof Error ? err.name : void 0;