@open-mercato/shared 0.7.1-develop.7170.1.d95074d7ba → 0.7.1-develop.7171.1.9b31dbba45

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

@@ -62,11 +62,12 @@ function buildCacheKey(enricher, context, targetEntity, mode, recordIds) {
   const sortedIds = [...recordIds].sort((a, b) => a.localeCompare(b));
   return `umes:enricher:${enricher.id}:entity:${targetEntity}:tenant:${context.tenantId}:org:${context.organizationId}:mode:${mode}:ids:${JSON.stringify(sortedIds)}`;
 }
+const UNKNOWN_RECORD_ID = "unknown";
 function extractRecordId(record) {
   const idValue = record.id;
   if (typeof idValue === "string" && idValue.trim().length > 0) return idValue.trim();
   if (typeof idValue === "number") return String(idValue);
-  return "unknown";
+  return UNKNOWN_RECORD_ID;
 }
 function getEnricherCacheTtl(enricher) {
   const ttl = enricher.cache?.ttl;
@@ -96,6 +97,11 @@ async function readEnricherCache(cache, key) {
     return null;
   }
 }
+function logSkippedCacheWrite(enricher) {
+  logger.debug("Skipped enricher cache write \u2014 enrichment is not purely additive or lacks usable record ids", {
+    enricherId: enricher.id
+  });
+}
 async function writeEnricherCache(cache, key, value, ttl, tags) {
   if (!cache) return;
   try {
@@ -103,6 +109,49 @@ async function writeEnricherCache(cache, key, value, ttl, tags) {
   } catch {
   }
 }
+const ENRICHER_CACHE_VERSION = 1;
+function isEnricherCacheEnvelope(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value;
+  if (candidate.version !== ENRICHER_CACHE_VERSION) return false;
+  return typeof candidate.deltas === "object" && candidate.deltas !== null;
+}
+function computeAdditiveDelta(input, output) {
+  const delta = {};
+  for (const key of Object.keys(input)) {
+    if (!Object.prototype.hasOwnProperty.call(output, key)) return null;
+    if (output[key] !== input[key]) return null;
+  }
+  for (const key of Object.keys(output)) {
+    if (Object.prototype.hasOwnProperty.call(input, key)) continue;
+    delta[key] = output[key];
+  }
+  return delta;
+}
+function buildCacheEnvelope(inputs, outputs) {
+  if (inputs.length !== outputs.length) return null;
+  const deltas = {};
+  for (let index = 0; index < inputs.length; index += 1) {
+    const recordId = extractRecordId(inputs[index]);
+    if (recordId === UNKNOWN_RECORD_ID) return null;
+    if (Object.prototype.hasOwnProperty.call(deltas, recordId)) return null;
+    const delta = computeAdditiveDelta(inputs[index], outputs[index]);
+    if (!delta) return null;
+    deltas[recordId] = delta;
+  }
+  return { version: ENRICHER_CACHE_VERSION, deltas };
+}
+function applyCacheEnvelope(envelope, records) {
+  const merged = [];
+  for (const record of records) {
+    const recordId = extractRecordId(record);
+    if (recordId === UNKNOWN_RECORD_ID) return null;
+    const delta = envelope.deltas[recordId];
+    if (!delta || typeof delta !== "object") return null;
+    merged.push({ ...record, ...delta });
+  }
+  return merged;
+}
 async function applyResponseEnrichers(items, targetEntity, context, preFilteredEntries) {
   const enricherContext = { ...context, targetEntity };
   const activeEntries = preFilteredEntries ? filterByACLAndTenant(preFilteredEntries, context) : getActiveEnrichers(targetEntity, context);
@@ -122,12 +171,16 @@ async function applyResponseEnrichers(items, targetEntity, context, preFilteredE
       const recordIds = currentItems.map((item) => extractRecordId(item));
       const shouldUseCache = enricher.cache?.strategy === "read-through";
       const cacheKey = shouldUseCache ? buildCacheKey(enricher, context, targetEntity, "many", recordIds) : null;
+      const inputItems = shouldUseCache ? currentItems.map((item) => ({ ...item })) : currentItems;
       if (shouldUseCache && cacheKey) {
         const cached = await readEnricherCache(cache, cacheKey);
-        if (cached) {
-          currentItems = cached;
-          enrichedBy.push(enricher.id);
-          continue;
+        if (isEnricherCacheEnvelope(cached)) {
+          const merged = applyCacheEnvelope(cached, currentItems);
+          if (merged) {
+            currentItems = merged;
+            enrichedBy.push(enricher.id);
+            continue;
+          }
         }
       }
       if (enricher.enrichMany) {
@@ -149,13 +202,18 @@ async function applyResponseEnrichers(items, targetEntity, context, preFilteredE
       logEnricherTiming(enricher.id, entry.moduleId, targetEntity, elapsedMs);
       currentItems = result;
       if (shouldUseCache && cacheKey) {
-        await writeEnricherCache(
-          cache,
-          cacheKey,
-          result,
-          getEnricherCacheTtl(enricher),
-          getEnricherCacheTags(enricher, context)
-        );
+        const envelope = buildCacheEnvelope(inputItems, result);
+        if (envelope) {
+          await writeEnricherCache(
+            cache,
+            cacheKey,
+            envelope,
+            getEnricherCacheTtl(enricher),
+            getEnricherCacheTags(enricher, context)
+          );
+        } else {
+          logSkippedCacheWrite(enricher);
+        }
       }
       enrichedBy.push(enricher.id);
     } catch (err) {
@@ -198,12 +256,16 @@ async function applyResponseEnricherToRecord(record, targetEntity, context, preF
       const recordId = extractRecordId(currentRecord);
       const shouldUseCache = enricher.cache?.strategy === "read-through";
       const cacheKey = shouldUseCache ? buildCacheKey(enricher, context, targetEntity, "one", [recordId]) : null;
+      const inputRecord = shouldUseCache ? { ...currentRecord } : currentRecord;
       if (shouldUseCache && cacheKey) {
         const cached = await readEnricherCache(cache, cacheKey);
-        if (cached) {
-          currentRecord = cached;
-          enrichedBy.push(enricher.id);
-          continue;
+        if (isEnricherCacheEnvelope(cached)) {
+          const merged = applyCacheEnvelope(cached, [currentRecord]);
+          if (merged) {
+            currentRecord = merged[0];
+            enrichedBy.push(enricher.id);
+            continue;
+          }
         }
       }
       const result = await Promise.race([
@@ -214,13 +276,18 @@ async function applyResponseEnricherToRecord(record, targetEntity, context, preF
       logEnricherTiming(enricher.id, entry.moduleId, targetEntity, elapsedMs);
       currentRecord = result;
       if (shouldUseCache && cacheKey) {
-        await writeEnricherCache(
-          cache,
-          cacheKey,
-          result,
-          getEnricherCacheTtl(enricher),
-          getEnricherCacheTags(enricher, context)
-        );
+        const envelope = buildCacheEnvelope([inputRecord], [result]);
+        if (envelope) {
+          await writeEnricherCache(
+            cache,
+            cacheKey,
+            envelope,
+            getEnricherCacheTtl(enricher),
+            getEnricherCacheTags(enricher, context)
+          );
+        } else {
+          logSkippedCacheWrite(enricher);
+        }
       }
       enrichedBy.push(enricher.id);
     } catch (err) {

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  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\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 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      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, 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        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 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      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, 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        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/version.js

@@ -1,4 +1,4 @@
-const APP_VERSION = "0.7.1-develop.7170.1.d95074d7ba";
+const APP_VERSION = "0.7.1-develop.7171.1.9b31dbba45";
 const appVersion = APP_VERSION;
 export {
   APP_VERSION,

package/dist/lib/version.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/lib/version.ts"],
-  "sourcesContent": ["// Build-time generated version\nexport const APP_VERSION = '0.7.1-develop.7170.1.d95074d7ba';\nexport const appVersion = APP_VERSION;\n"],
+  "sourcesContent": ["// Build-time generated version\nexport const APP_VERSION = '0.7.1-develop.7171.1.9b31dbba45';\nexport const appVersion = APP_VERSION;\n"],
   "mappings": "AACO,MAAM,cAAc;AACpB,MAAM,aAAa;",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/shared",
-  "version": "0.7.1-develop.7170.1.d95074d7ba",
+  "version": "0.7.1-develop.7171.1.9b31dbba45",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -113,7 +113,7 @@
     "@mikro-orm/core": "^7.1.8",
     "@mikro-orm/decorators": "^7.1.8",
     "@mikro-orm/postgresql": "^7.1.8",
-    "@open-mercato/cache": "0.7.1-develop.7170.1.d95074d7ba",
+    "@open-mercato/cache": "0.7.1-develop.7171.1.9b31dbba45",
     "@types/html-to-text": "^9.0.4",
     "@types/sanitize-html": "^2.16.1",
     "dotenv": "^17.4.2",

package/src/lib/crud/__tests__/enricher-runner.read-through-cache.test.ts

@@ -0,0 +1,291 @@
+import { applyResponseEnrichers, applyResponseEnricherToRecord } from '../enricher-runner'
+import { registerResponseEnrichers } from '../enricher-registry'
+import type { EnricherContext, ResponseEnricher } from '../response-enricher'
+
+type Record_ = Record<string, unknown>
+
+function createCache() {
+  const store = new Map<string, unknown>()
+  const set = jest.fn(async (key: string, value: unknown) => {
+    store.set(key, value)
+  })
+  const get = jest.fn(async (key: string) => (store.has(key) ? store.get(key) : null))
+  return { store, cache: { get, set } }
+}
+
+function createContext(cache: { get: jest.Mock; set: jest.Mock } | null): EnricherContext {
+  return {
+    tenantId: 'tenant-1',
+    organizationId: 'org-1',
+    userFeatures: ['demo.view'],
+    container: cache ? { resolve: (name: string) => (name === 'cache' ? cache : null) } : undefined,
+  } as unknown as EnricherContext
+}
+
+const TARGET = 'demo:widget'
+
+function defineEnricher(
+  enrichMany: (records: Record_[]) => Record_[],
+  overrides: Partial<ResponseEnricher> = {},
+): ResponseEnricher {
+  return {
+    id: 'demo.enricher',
+    targetEntity: TARGET,
+    priority: 10,
+    cache: { strategy: 'read-through', ttl: 30_000, tags: ['demo:widgets'] },
+    async enrichOne(record: Record_) {
+      return enrichMany([record])[0]
+    },
+    async enrichMany(records: Record_[]) {
+      return enrichMany(records)
+    },
+    ...overrides,
+  } as ResponseEnricher
+}
+
+function register(enricher: ResponseEnricher) {
+  registerResponseEnrichers([{ moduleId: 'demo', enrichers: [enricher] }])
+}
+
+describe('enricher runner read-through cache', () => {
+  beforeEach(() => {
+    registerResponseEnrichers([])
+  })
+
+  it('serves the enrichment from cache on the second call without re-running the enricher', async () => {
+    const { cache } = createCache()
+    const enrichMany = jest.fn((records: Record_[]) =>
+      records.map((record) => ({ ...record, _demo: { stock: 7 } })),
+    )
+    register(defineEnricher(enrichMany))
+
+    const items = [{ id: 'a', name: 'first' }]
+    const first = await applyResponseEnrichers(items, TARGET, createContext(cache))
+    expect(first.items[0]._demo).toEqual({ stock: 7 })
+    expect(enrichMany).toHaveBeenCalledTimes(1)
+
+    const second = await applyResponseEnrichers(items, TARGET, createContext(cache))
+    expect(second.items[0]._demo).toEqual({ stock: 7 })
+    expect(second._meta.enrichedBy).toEqual(['demo.enricher'])
+    expect(enrichMany).toHaveBeenCalledTimes(1)
+  })
+
+  it('keeps base record fields fresh on a cache hit instead of replaying the cached snapshot', async () => {
+    const { cache } = createCache()
+    const enrichMany = jest.fn((records: Record_[]) =>
+      records.map((record) => ({ ...record, _demo: { stock: 7 } })),
+    )
+    register(defineEnricher(enrichMany))
+
+    await applyResponseEnrichers([{ id: 'a', name: 'old name' }], TARGET, createContext(cache))
+
+    const second = await applyResponseEnrichers(
+      [{ id: 'a', name: 'new name' }],
+      TARGET,
+      createContext(cache),
+    )
+
+    expect(enrichMany).toHaveBeenCalledTimes(1)
+    expect(second.items[0].name).toBe('new name')
+    expect(second.items[0]._demo).toEqual({ stock: 7 })
+  })
+
+  it('does not cache an enricher that mutates a pre-existing field', async () => {
+    const { cache } = createCache()
+    const enrichMany = jest.fn((records: Record_[]) =>
+      records.map((record) => ({ ...record, name: 'rewritten', _demo: { stock: 1 } })),
+    )
+    register(defineEnricher(enrichMany))
+
+    const items = [{ id: 'a', name: 'original' }]
+    await applyResponseEnrichers(items, TARGET, createContext(cache))
+    expect(cache.set).not.toHaveBeenCalled()
+
+    const second = await applyResponseEnrichers(items, TARGET, createContext(cache))
+    expect(enrichMany).toHaveBeenCalledTimes(2)
+    expect(second.items[0].name).toBe('rewritten')
+  })
+
+  it('does not cache a batch containing a record without a usable id', async () => {
+    const { cache } = createCache()
+    const enrichMany = jest.fn((records: Record_[]) =>
+      records.map((record) => ({ ...record, _demo: { stock: 3 } })),
+    )
+    register(defineEnricher(enrichMany))
+
+    await applyResponseEnrichers([{ name: 'no id' }], TARGET, createContext(cache))
+
+    expect(cache.set).not.toHaveBeenCalled()
+  })
+
+  it('re-runs the enricher when the cached envelope does not cover every record', async () => {
+    const { store, cache } = createCache()
+    const enrichMany = jest.fn((records: Record_[]) =>
+      records.map((record) => ({ ...record, _demo: { stock: 5 } })),
+    )
+    register(defineEnricher(enrichMany))
+
+    const items = [{ id: 'a' }, { id: 'b' }]
+    await applyResponseEnrichers(items, TARGET, createContext(cache))
+    expect(enrichMany).toHaveBeenCalledTimes(1)
+
+    const [cacheKey] = Array.from(store.keys())
+    store.set(cacheKey, { version: 1, deltas: { a: { _demo: { stock: 5 } } } })
+
+    const second = await applyResponseEnrichers(items, TARGET, createContext(cache))
+    expect(enrichMany).toHaveBeenCalledTimes(2)
+    expect(second.items.map((item) => item._demo)).toEqual([{ stock: 5 }, { stock: 5 }])
+  })
+
+  it('ignores a cached payload written under a different envelope version', async () => {
+    const { store, cache } = createCache()
+    const enrichMany = jest.fn((records: Record_[]) =>
+      records.map((record) => ({ ...record, _demo: { stock: 9 } })),
+    )
+    register(defineEnricher(enrichMany))
+
+    const items = [{ id: 'a' }]
+    await applyResponseEnrichers(items, TARGET, createContext(cache))
+
+    const [cacheKey] = Array.from(store.keys())
+    store.set(cacheKey, { version: 99, deltas: { a: { _demo: { stock: 0 } } } })
+
+    const second = await applyResponseEnrichers(items, TARGET, createContext(cache))
+    expect(enrichMany).toHaveBeenCalledTimes(2)
+    expect(second.items[0]._demo).toEqual({ stock: 9 })
+  })
+
+  it('caches the delta of an enricher that mutates the records in place', async () => {
+    // The contract does not forbid in-place mutation. Comparing a mutated
+    // record against itself would produce an empty delta, so the cache would
+    // then serve unenriched records for the rest of the TTL.
+    const { cache } = createCache()
+    const enrichMany = jest.fn((records: Record_[]) => {
+      for (const record of records) {
+        record._demo = { stock: 11 }
+      }
+      return records
+    })
+    register(defineEnricher(enrichMany))
+
+    const first = await applyResponseEnrichers(
+      [{ id: 'a', name: 'first' }],
+      TARGET,
+      createContext(cache),
+    )
+    expect(first.items[0]._demo).toEqual({ stock: 11 })
+    expect(cache.set).toHaveBeenCalledTimes(1)
+
+    const second = await applyResponseEnrichers(
+      [{ id: 'a', name: 'first' }],
+      TARGET,
+      createContext(cache),
+    )
+
+    expect(enrichMany).toHaveBeenCalledTimes(1)
+    expect(second.items[0]._demo).toEqual({ stock: 11 })
+  })
+
+  it('caches an empty delta when the enricher genuinely adds nothing', async () => {
+    const { cache } = createCache()
+    const enrichMany = jest.fn((records: Record_[]) => records)
+    register(defineEnricher(enrichMany))
+
+    const items = [{ id: 'a', name: 'unchanged' }]
+    await applyResponseEnrichers(items, TARGET, createContext(cache))
+    expect(cache.set).toHaveBeenCalledTimes(1)
+
+    const second = await applyResponseEnrichers(items, TARGET, createContext(cache))
+    expect(enrichMany).toHaveBeenCalledTimes(1)
+    expect(second.items[0]).toEqual({ id: 'a', name: 'unchanged' })
+  })
+
+  it('does not let a cache hit mutate the caller\'s input records', async () => {
+    const { cache } = createCache()
+    register(
+      defineEnricher((records) => records.map((record) => ({ ...record, _demo: { stock: 8 } }))),
+    )
+
+    await applyResponseEnrichers([{ id: 'a' }], TARGET, createContext(cache))
+
+    const input = [{ id: 'a' }]
+    const second = await applyResponseEnrichers(input, TARGET, createContext(cache))
+
+    expect(second.items[0]._demo).toEqual({ stock: 8 })
+    expect(input[0]).toEqual({ id: 'a' })
+  })
+
+  it('never touches the cache for an enricher that did not opt in', async () => {
+    const { cache } = createCache()
+    const enrichMany = jest.fn((records: Record_[]) =>
+      records.map((record) => ({ ...record, _demo: { stock: 2 } })),
+    )
+    register(defineEnricher(enrichMany, { cache: undefined }))
+
+    const items = [{ id: 'a' }]
+    await applyResponseEnrichers(items, TARGET, createContext(cache))
+    await applyResponseEnrichers(items, TARGET, createContext(cache))
+
+    expect(cache.get).not.toHaveBeenCalled()
+    expect(cache.set).not.toHaveBeenCalled()
+    expect(enrichMany).toHaveBeenCalledTimes(2)
+  })
+
+  it('writes the enrichment tags alongside the automatic tenant, organization and enricher tags', async () => {
+    const { cache } = createCache()
+    register(
+      defineEnricher((records) => records.map((record) => ({ ...record, _demo: { stock: 1 } }))),
+    )
+
+    await applyResponseEnrichers([{ id: 'a' }], TARGET, createContext(cache))
+
+    expect(cache.set).toHaveBeenCalledTimes(1)
+    const [, , options] = cache.set.mock.calls[0]
+    expect(options.ttl).toBe(30_000)
+    expect(options.tags).toEqual(
+      expect.arrayContaining([
+        'tenant:tenant-1',
+        'organization:org-1',
+        'enricher:demo.enricher',
+        'demo:widgets',
+      ]),
+    )
+  })
+
+  it('caches the single-record path and keeps its base fields fresh', async () => {
+    const { cache } = createCache()
+    const enrichMany = jest.fn((records: Record_[]) =>
+      records.map((record) => ({ ...record, _demo: { stock: 4 } })),
+    )
+    register(defineEnricher(enrichMany))
+
+    const first = await applyResponseEnricherToRecord(
+      { id: 'a', name: 'old' },
+      TARGET,
+      createContext(cache),
+    )
+    expect(first.record._demo).toEqual({ stock: 4 })
+
+    const second = await applyResponseEnricherToRecord(
+      { id: 'a', name: 'new' },
+      TARGET,
+      createContext(cache),
+    )
+
+    expect(enrichMany).toHaveBeenCalledTimes(1)
+    expect(second.record.name).toBe('new')
+    expect(second.record._demo).toEqual({ stock: 4 })
+  })
+
+  it('runs normally when no cache service is available in the container', async () => {
+    const enrichMany = jest.fn((records: Record_[]) =>
+      records.map((record) => ({ ...record, _demo: { stock: 6 } })),
+    )
+    register(defineEnricher(enrichMany))
+
+    const result = await applyResponseEnrichers([{ id: 'a' }], TARGET, createContext(null))
+
+    expect(result.items[0]._demo).toEqual({ stock: 6 })
+    expect(enrichMany).toHaveBeenCalledTimes(1)
+  })
+})

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

@@ -145,11 +145,13 @@ function buildCacheKey(
   return `umes:enricher:${enricher.id}:entity:${targetEntity}:tenant:${context.tenantId}:org:${context.organizationId}:mode:${mode}:ids:${JSON.stringify(sortedIds)}`
 }
 
+const UNKNOWN_RECORD_ID = 'unknown'
+
 function extractRecordId(record: Record<string, unknown>): string {
   const idValue = record.id
   if (typeof idValue === 'string' && idValue.trim().length > 0) return idValue.trim()
   if (typeof idValue === 'number') return String(idValue)
-  return 'unknown'
+  return UNKNOWN_RECORD_ID
 }
 
 function getEnricherCacheTtl(enricher: ResponseEnricher): number {
@@ -186,6 +188,18 @@ async function readEnricherCache<T>(
   }
 }
 
+/**
+ * The cache write was skipped because no safe envelope could be built. Logged
+ * rather than swallowed: from outside the runner a silently-skipped write is
+ * indistinguishable from a broken cache, and "this enricher is not purely
+ * additive" is the answer an author needs to see.
+ */
+function logSkippedCacheWrite(enricher: ResponseEnricher): void {
+  logger.debug('Skipped enricher cache write — enrichment is not purely additive or lacks usable record ids', {
+    enricherId: enricher.id,
+  })
+}
+
 async function writeEnricherCache(
   cache: CacheLike | null,
   key: string,
@@ -201,6 +215,103 @@ async function writeEnricherCache(
   }
 }
 
+/**
+ * Cached read-through payload: the fields each enricher ADDED, keyed by record id.
+ *
+ * Caching whole records would replace the freshly-read record with the snapshot
+ * taken at write time, so an edit to a base field (a product's name, an order's
+ * status) would not surface until the entry expired, and a cached array would
+ * also carry — and therefore overwrite — whatever the previous enricher in the
+ * chain contributed. The additive delta is a pure function of the enricher, the
+ * tenant/organization scope and the record ids, which is exactly what the cache
+ * key already encodes, so it is the only part of the result that is safe to reuse.
+ */
+type EnricherCacheEnvelope = {
+  version: 1
+  deltas: Record<string, Record<string, unknown>>
+}
+
+const ENRICHER_CACHE_VERSION = 1
+
+function isEnricherCacheEnvelope(value: unknown): value is EnricherCacheEnvelope {
+  if (typeof value !== 'object' || value === null) return false
+  const candidate = value as { version?: unknown; deltas?: unknown }
+  if (candidate.version !== ENRICHER_CACHE_VERSION) return false
+  return typeof candidate.deltas === 'object' && candidate.deltas !== null
+}
+
+/**
+ * The keys an enricher added to a record, or `null` when the enrichment was not
+ * purely additive — it changed or dropped a key that was already there. A
+ * non-additive enricher is never cached: replaying only its added keys onto a
+ * later record would silently lose the change it made to the existing ones.
+ *
+ * Comparison is by identity at the top level only, so an enricher that mutates a
+ * nested object in place is indistinguishable from one that left the record
+ * alone: its nested change is absent from the delta and therefore lost on a
+ * later hit. That fails safe — the served record is under-enriched, never
+ * stale-wrong — and a deep clone of every record on every enriched response is
+ * not worth paying for the case.
+ */
+function computeAdditiveDelta(
+  input: Record<string, unknown>,
+  output: Record<string, unknown>,
+): Record<string, unknown> | null {
+  const delta: Record<string, unknown> = {}
+  for (const key of Object.keys(input)) {
+    if (!Object.prototype.hasOwnProperty.call(output, key)) return null
+    if (output[key] !== input[key]) return null
+  }
+  for (const key of Object.keys(output)) {
+    if (Object.prototype.hasOwnProperty.call(input, key)) continue
+    delta[key] = output[key]
+  }
+  return delta
+}
+
+/**
+ * Build the cacheable envelope for a batch, or `null` when it cannot be built
+ * safely — an unusable record id, a duplicate id (the deltas would collide), or
+ * a non-additive enrichment. Every failure mode skips the cache write and leaves
+ * the enricher running on every request, which is the pre-cache behavior.
+ */
+function buildCacheEnvelope<T extends Record<string, unknown>>(
+  inputs: T[],
+  outputs: T[],
+): EnricherCacheEnvelope | null {
+  if (inputs.length !== outputs.length) return null
+  const deltas: Record<string, Record<string, unknown>> = {}
+  for (let index = 0; index < inputs.length; index += 1) {
+    const recordId = extractRecordId(inputs[index])
+    if (recordId === UNKNOWN_RECORD_ID) return null
+    if (Object.prototype.hasOwnProperty.call(deltas, recordId)) return null
+    const delta = computeAdditiveDelta(inputs[index], outputs[index])
+    if (!delta) return null
+    deltas[recordId] = delta
+  }
+  return { version: ENRICHER_CACHE_VERSION, deltas }
+}
+
+/**
+ * Merge a cached envelope onto freshly-read records. Returns `null` — a miss —
+ * when the envelope does not cover every record, so a partially-cached batch
+ * re-runs the enricher rather than returning some records unenriched.
+ */
+function applyCacheEnvelope<T extends Record<string, unknown>>(
+  envelope: EnricherCacheEnvelope,
+  records: T[],
+): T[] | null {
+  const merged: T[] = []
+  for (const record of records) {
+    const recordId = extractRecordId(record)
+    if (recordId === UNKNOWN_RECORD_ID) return null
+    const delta = envelope.deltas[recordId]
+    if (!delta || typeof delta !== 'object') return null
+    merged.push({ ...record, ...delta } as T)
+  }
+  return merged
+}
+
 /**
  * Apply response enrichers to a list of records.
  *
@@ -239,12 +350,20 @@ export async function applyResponseEnrichers<T extends Record<string, unknown>>(
       const cacheKey = shouldUseCache
         ? buildCacheKey(enricher, context, targetEntity, 'many', recordIds)
         : null
+      // Snapshot BEFORE enrichment: the contract does not forbid an enricher
+      // from mutating the records it was handed, and comparing a mutated record
+      // against itself would yield an empty delta — caching "this enricher adds
+      // nothing" and serving unenriched records for the rest of the TTL.
+      const inputItems = shouldUseCache ? currentItems.map((item) => ({ ...item })) : currentItems
       if (shouldUseCache && cacheKey) {
-        const cached = await readEnricherCache<T[]>(cache, cacheKey)
-        if (cached) {
-          currentItems = cached
-          enrichedBy.push(enricher.id)
-          continue
+        const cached = await readEnricherCache<unknown>(cache, cacheKey)
+        if (isEnricherCacheEnvelope(cached)) {
+          const merged = applyCacheEnvelope(cached, currentItems)
+          if (merged) {
+            currentItems = merged
+            enrichedBy.push(enricher.id)
+            continue
+          }
         }
       }
 
@@ -269,13 +388,18 @@ export async function applyResponseEnrichers<T extends Record<string, unknown>>(
 
       currentItems = result
       if (shouldUseCache && cacheKey) {
-        await writeEnricherCache(
-          cache,
-          cacheKey,
-          result,
-          getEnricherCacheTtl(enricher),
-          getEnricherCacheTags(enricher, context),
-        )
+        const envelope = buildCacheEnvelope(inputItems, result)
+        if (envelope) {
+          await writeEnricherCache(
+            cache,
+            cacheKey,
+            envelope,
+            getEnricherCacheTtl(enricher),
+            getEnricherCacheTags(enricher, context),
+          )
+        } else {
+          logSkippedCacheWrite(enricher)
+        }
       }
       enrichedBy.push(enricher.id)
     } catch (err) {
@@ -340,12 +464,17 @@ export async function applyResponseEnricherToRecord<T extends Record<string, unk
       const cacheKey = shouldUseCache
         ? buildCacheKey(enricher, context, targetEntity, 'one', [recordId])
         : null
+      // Snapshot before enrichment — see the list path for why.
+      const inputRecord = shouldUseCache ? ({ ...currentRecord } as T) : currentRecord
       if (shouldUseCache && cacheKey) {
-        const cached = await readEnricherCache<T>(cache, cacheKey)
-        if (cached) {
-          currentRecord = cached
-          enrichedBy.push(enricher.id)
-          continue
+        const cached = await readEnricherCache<unknown>(cache, cacheKey)
+        if (isEnricherCacheEnvelope(cached)) {
+          const merged = applyCacheEnvelope(cached, [currentRecord])
+          if (merged) {
+            currentRecord = merged[0]
+            enrichedBy.push(enricher.id)
+            continue
+          }
         }
       }
       const result = await Promise.race([
@@ -358,13 +487,18 @@ export async function applyResponseEnricherToRecord<T extends Record<string, unk
 
       currentRecord = result
       if (shouldUseCache && cacheKey) {
-        await writeEnricherCache(
-          cache,
-          cacheKey,
-          result,
-          getEnricherCacheTtl(enricher),
-          getEnricherCacheTags(enricher, context),
-        )
+        const envelope = buildCacheEnvelope([inputRecord], [result])
+        if (envelope) {
+          await writeEnricherCache(
+            cache,
+            cacheKey,
+            envelope,
+            getEnricherCacheTtl(enricher),
+            getEnricherCacheTags(enricher, context),
+          )
+        } else {
+          logSkippedCacheWrite(enricher)
+        }
       }
       enrichedBy.push(enricher.id)
     } catch (err) {

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

@@ -93,11 +93,33 @@ export interface ResponseEnricher<TRecord = any, TEnriched = any> {
   /** Tenant IDs where this enricher should be disabled. */
   disabledTenantIds?: string[]
 
-  /** Optional cache configuration for read-through enrichment results. */
+  /**
+   * Optional cache configuration for read-through enrichment results.
+   *
+   * The runner caches the **additive delta** — the keys this enricher adds to a
+   * record — not the record itself, so a cache hit still serves freshly-read
+   * base fields and cannot overwrite what an earlier enricher in the chain
+   * contributed. That makes the cache usable only by an enricher whose output is
+   * purely additive: one that changes or drops a key the record already carried
+   * is never cached and simply re-runs on every request. Declaring `cache` on
+   * such an enricher is silently a no-op rather than an error, so an enricher
+   * that appears never to cache is usually mutating an existing key.
+   */
   cache?: {
     strategy: 'read-through'
     ttl: number
     tags?: string[]
+    /**
+     * NOT IMPLEMENTED — nothing in the runner reads this field, so declaring it
+     * has no effect and an enricher relying on it will serve stale enrichment
+     * until the TTL expires. It is kept rather than removed so any existing
+     * declaration keeps compiling.
+     *
+     * Wire invalidation with an event subscriber that calls `deleteByTags` on
+     * the tags above; see
+     * `packages/core/src/modules/wms/subscribers/invalidate-enricher-cache-*.ts`
+     * for the reference implementation.
+     */
     invalidateOn?: string[]
   }