@open-mercato/shared 0.6.4-develop.4282.1.4d95e85930 → 0.6.4-develop.4305.1.efaf0ebab1

package/dist/lib/version.js

@@ -1,4 +1,4 @@
-const APP_VERSION = "0.6.4-develop.4282.1.4d95e85930";
+const APP_VERSION = "0.6.4-develop.4305.1.efaf0ebab1";
 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.6.4-develop.4282.1.4d95e85930'\nexport const appVersion = APP_VERSION\n"],
+  "sourcesContent": ["// Build-time generated version\nexport const APP_VERSION = '0.6.4-develop.4305.1.efaf0ebab1'\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.6.4-develop.4282.1.4d95e85930",
+  "version": "0.6.4-develop.4305.1.efaf0ebab1",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
@@ -89,10 +89,10 @@
     }
   },
   "dependencies": {
-    "@mikro-orm/core": "^7.1.1",
-    "@mikro-orm/decorators": "^7.1.1",
-    "@mikro-orm/postgresql": "^7.1.1",
-    "@open-mercato/cache": "0.6.4-develop.4282.1.4d95e85930",
+    "@mikro-orm/core": "^7.1.3",
+    "@mikro-orm/decorators": "^7.1.3",
+    "@mikro-orm/postgresql": "^7.1.3",
+    "@open-mercato/cache": "0.6.4-develop.4305.1.efaf0ebab1",
     "dotenv": "^17.4.2",
     "rate-limiter-flexible": "^11.1.0",
     "re2js": "2.8.3",

package/src/lib/commands/types.ts

@@ -12,6 +12,14 @@ export type CommandRuntimeContext = {
   organizationIds: string[] | null
   request?: Request
   syncOrigin?: string | null
+  /**
+   * Marks a trusted server-side invocation (CLI seeding, tenant setup) that runs
+   * without an authenticated end-user actor. Commands that gate writes behind a
+   * privileged actor (e.g. super-admin-only platform tables) may treat this as
+   * an explicit system grant. HTTP request paths MUST NOT set this — they always
+   * carry a real `auth` actor, so a present-but-unprivileged actor stays denied.
+   */
+  systemActor?: boolean
   /**
    * When set, command handlers that support it MUST run their writes within this
    * existing transactional EntityManager (reusing its row locks) instead of

package/src/lib/crud/__tests__/crud-factory.enricher-cache.test.ts

@@ -0,0 +1,284 @@
+// Regression coverage for #2222: a CRUD list cache hit may skip re-running
+// response enrichers ONLY when every active enricher opts into
+// `cacheableOnListHit` (its output is a pure function of the cached record). For
+// such enrichers the stored payload embeds enricher output and the cache key is
+// partitioned by the active-enricher signature, so a hit serves the cached
+// enrichment directly — eliminating the ~15ms per-hit cost — while staying
+// ACL-gated. Enrichers that read live cross-module / time-dependent data (the
+// default, fail-closed) MUST re-run on every hit, and the cache stores their
+// pre-enrichment base payload — see the fail-closed test at the bottom.
+
+jest.mock('@open-mercato/cache', () => ({
+  runWithCacheTenant: async (_tenantId: string | null, fn: () => Promise<unknown>) => fn(),
+}), { virtual: true })
+
+import { makeCrudRoute } from '@open-mercato/shared/lib/crud/factory'
+import { registerApiInterceptors } from '@open-mercato/shared/lib/crud/interceptor-registry'
+import { registerResponseEnrichers } from '@open-mercato/shared/lib/crud/enricher-registry'
+import type { ResponseEnricher } from '@open-mercato/shared/lib/crud/response-enricher'
+import { z } from 'zod'
+
+const defaultOrganizationId = 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa'
+const defaultTenantId = '123e4567-e89b-12d3-a456-426614174000'
+
+let mockUserFeatures: string[] | undefined
+
+const em = {}
+
+const queryEngine = {
+  query: jest.fn(async () => ({
+    items: [{ id: 'id-1', title: 'A', organization_id: defaultOrganizationId, tenant_id: defaultTenantId }],
+    total: 1,
+  })),
+}
+
+// Simple Map-backed CRUD cache supporting the surface the factory touches.
+const store = new Map<string, unknown>()
+const cache = {
+  get: jest.fn(async (key: string) => (store.has(key) ? store.get(key) : null)),
+  set: jest.fn(async (key: string, value: unknown) => { store.set(key, value) }),
+  delete: jest.fn(async (key: string) => { store.delete(key) }),
+  deleteByTags: jest.fn(async () => 0),
+}
+
+const accessLogService = { log: jest.fn(async () => {}) }
+
+const rbacService = {
+  getGrantedFeatures: jest.fn(async () => mockUserFeatures),
+}
+
+jest.mock('@open-mercato/shared/lib/di/container', () => ({
+  createRequestContainer: async () => ({
+    resolve: (name: string) => ({
+      em,
+      queryEngine,
+      cache,
+      accessLogService,
+      rbacService,
+    } as any)[name],
+  }),
+}))
+
+jest.mock('@open-mercato/shared/lib/auth/server', () => {
+  const auth = {
+    sub: 'u1',
+    orgId: 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa',
+    tenantId: '123e4567-e89b-12d3-a456-426614174000',
+    roles: ['admin'],
+  }
+  return {
+    getAuthFromCookies: async () => auth,
+    getAuthFromRequest: async () => auth,
+  }
+})
+
+jest.mock('@open-mercato/core/modules/directory/utils/organizationScope', () => ({
+  resolveOrganizationScopeForRequest: jest.fn(async () => ({
+    selectedId: 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa',
+    filterIds: ['aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa'],
+    allowedIds: ['aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa'],
+    tenantId: '123e4567-e89b-12d3-a456-426614174000',
+  })),
+}))
+
+jest.mock('@open-mercato/core/modules/entities/lib/helpers', () => ({
+  setRecordCustomFields: jest.fn(async () => {}),
+}))
+
+class Todo {}
+
+const enrichManyCalls = jest.fn()
+
+// Record-pure enricher: its output depends only on the cached record, so it
+// opts into `cacheableOnListHit` and is safe to embed in the list cache.
+const gatedEnricher: ResponseEnricher<any> = {
+  id: 'example.todo-flag',
+  targetEntity: 'example.todo',
+  features: ['example.view'],
+  priority: 10,
+  timeout: 2000,
+  critical: false,
+  cacheableOnListHit: true,
+  fallback: { _example: { flagged: false } },
+  async enrichOne(record, context) {
+    return (await this.enrichMany!([record], context))[0]
+  },
+  async enrichMany(records) {
+    enrichManyCalls()
+    return records.map((record) => ({ ...record, _example: { flagged: true } }))
+  },
+}
+
+// Live enricher: its output mirrors mutable external state (a stand-in for a
+// cross-module read like the catalog product image in TC-SALES-023). It does NOT
+// set `cacheableOnListHit`, so it must re-run on every cache hit.
+const liveEnricherCalls = jest.fn()
+let liveExternalValue = 'v1'
+
+const liveEnricher: ResponseEnricher<any> = {
+  id: 'example.todo-live',
+  targetEntity: 'example.todo',
+  features: [],
+  priority: 5,
+  timeout: 2000,
+  critical: false,
+  async enrichOne(record, context) {
+    return (await this.enrichMany!([record], context))[0]
+  },
+  async enrichMany(records) {
+    liveEnricherCalls()
+    return records.map((record) => ({ ...record, _live: { value: liveExternalValue } }))
+  },
+}
+
+const querySchema = z.object({
+  page: z.coerce.number().default(1),
+  pageSize: z.coerce.number().default(50),
+  sortField: z.string().default('id'),
+  sortDir: z.enum(['asc', 'desc']).default('asc'),
+})
+
+const route = makeCrudRoute({
+  metadata: { GET: { requireAuth: true } },
+  orm: { entity: Todo, idField: 'id', orgField: 'organizationId', tenantField: 'tenantId', softDeleteField: 'deletedAt' },
+  indexer: { entityType: 'example.todo' },
+  list: {
+    schema: querySchema,
+    entityId: 'example.todo',
+    fields: ['id', 'title'],
+    sortFieldMap: { id: 'id', title: 'title' },
+    buildFilters: () => ({} as any),
+    transformItem: (i: any) => ({ id: i.id, title: i.title }),
+  },
+  enrichers: { entityId: 'example.todo' },
+})
+
+const url = 'http://x/api/example/todos?page=1&pageSize=10&sortField=id&sortDir=asc'
+
+describe('CRUD Factory — response enrichers + list cache (#2222)', () => {
+  const previousCacheFlag = process.env.ENABLE_CRUD_API_CACHE
+
+  beforeAll(() => {
+    process.env.ENABLE_CRUD_API_CACHE = 'true'
+  })
+
+  afterAll(() => {
+    if (previousCacheFlag === undefined) delete process.env.ENABLE_CRUD_API_CACHE
+    else process.env.ENABLE_CRUD_API_CACHE = previousCacheFlag
+  })
+
+  beforeEach(() => {
+    jest.clearAllMocks()
+    store.clear()
+    mockUserFeatures = ['example.view']
+    registerApiInterceptors([])
+    registerResponseEnrichers([{ moduleId: 'example', enrichers: [gatedEnricher] }])
+  })
+
+  it('runs enrichers on the cache miss and caches the enriched payload', async () => {
+    const res = await route.GET(new Request(url))
+    expect(res.status).toBe(200)
+    const body = await res.json()
+    expect(body.items[0]._example).toEqual({ flagged: true })
+    expect(enrichManyCalls).toHaveBeenCalledTimes(1)
+    expect(res.headers.get('x-om-cache')).toBe('miss')
+
+    // The stored payload embeds the enrichment.
+    const stored = Array.from(store.values())[0] as any
+    expect(stored.payload.items[0]._example).toEqual({ flagged: true })
+  })
+
+  it('serves enriched fields from cache WITHOUT re-running enrichers on a hit', async () => {
+    const first = await route.GET(new Request(url))
+    expect(first.headers.get('x-om-cache')).toBe('miss')
+    expect(enrichManyCalls).toHaveBeenCalledTimes(1)
+
+    const second = await route.GET(new Request(url))
+    const body = await second.json()
+    expect(second.headers.get('x-om-cache')).toBe('hit')
+    // Enriched output still present...
+    expect(body.items[0]._example).toEqual({ flagged: true })
+    // ...but the enricher did NOT run a second time.
+    expect(enrichManyCalls).toHaveBeenCalledTimes(1)
+  })
+
+  it('partitions the cache by active-enricher signature so feature cohorts cannot leak ACL-gated fields', async () => {
+    // Cohort A holds the gating feature → enricher active, enriched payload cached.
+    mockUserFeatures = ['example.view']
+    const aRes = await route.GET(new Request(url))
+    const aBody = await aRes.json()
+    expect(aBody.items[0]._example).toEqual({ flagged: true })
+    const keysAfterA = new Set(store.keys())
+    expect(keysAfterA.size).toBe(1)
+
+    // Cohort B lacks the gating feature → enricher inactive (different signature →
+    // different cache key) → must NOT receive cohort A's enriched fields.
+    mockUserFeatures = []
+    const bRes = await route.GET(new Request(url))
+    const bBody = await bRes.json()
+    expect(bBody.items[0]._example).toBeUndefined()
+    expect(bRes.headers.get('x-om-cache')).toBe('miss')
+    // A distinct entry was written for cohort B rather than reusing cohort A's.
+    expect(store.size).toBe(2)
+
+    // Cohort A still gets a fast, correct hit from its own entry.
+    mockUserFeatures = ['example.view']
+    const aAgain = await route.GET(new Request(url))
+    const aAgainBody = await aAgain.json()
+    expect(aAgain.headers.get('x-om-cache')).toBe('hit')
+    expect(aAgainBody.items[0]._example).toEqual({ flagged: true })
+  })
+})
+
+describe('CRUD Factory — fail-closed enrichers re-run on cache hits (#2222)', () => {
+  const previousCacheFlag = process.env.ENABLE_CRUD_API_CACHE
+
+  beforeAll(() => {
+    process.env.ENABLE_CRUD_API_CACHE = 'true'
+  })
+
+  afterAll(() => {
+    if (previousCacheFlag === undefined) delete process.env.ENABLE_CRUD_API_CACHE
+    else process.env.ENABLE_CRUD_API_CACHE = previousCacheFlag
+  })
+
+  beforeEach(() => {
+    jest.clearAllMocks()
+    store.clear()
+    liveExternalValue = 'v1'
+    mockUserFeatures = ['example.view']
+    registerApiInterceptors([])
+    registerResponseEnrichers([{ moduleId: 'example', enrichers: [liveEnricher] }])
+  })
+
+  it('re-runs a non-cacheable enricher on a cache hit and reflects updated external data', async () => {
+    const first = await route.GET(new Request(url))
+    const firstBody = await first.json()
+    expect(first.headers.get('x-om-cache')).toBe('miss')
+    expect(firstBody.items[0]._live).toEqual({ value: 'v1' })
+    expect(liveEnricherCalls).toHaveBeenCalledTimes(1)
+
+    // External data the list cache does not invalidate on changes (e.g. a
+    // catalog product image update for a sales line, as in TC-SALES-023).
+    liveExternalValue = 'v2'
+
+    const second = await route.GET(new Request(url))
+    const secondBody = await second.json()
+    expect(second.headers.get('x-om-cache')).toBe('hit')
+    // The enricher re-ran on the hit, so the response reflects the new value...
+    expect(secondBody.items[0]._live).toEqual({ value: 'v2' })
+    expect(liveEnricherCalls).toHaveBeenCalledTimes(2)
+  })
+
+  it('caches the pre-enrichment base payload (no live enrichment embedded, no signature partition)', async () => {
+    await route.GET(new Request(url))
+
+    // Exactly one entry was written...
+    expect(store.size).toBe(1)
+    const [key, stored] = Array.from(store.entries())[0] as [string, any]
+    // ...holding the base record without the live enrichment...
+    expect(stored.payload.items[0]._live).toBeUndefined()
+    // ...under a key that is NOT partitioned by an enricher signature.
+    expect(key).not.toContain('enrichers:')
+  })
+})

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

@@ -65,6 +65,54 @@ function getActiveEnrichers(
   return filterByACLAndTenant(entries, context)
 }
 
+/**
+ * Plan describing whether (and how) a CRUD list cache may embed enricher output.
+ */
+export type ListCacheEnricherPlan = {
+  /**
+   * Stable signature of the active, cache-embeddable enrichers in registry
+   * (priority) order. Included in the CRUD list cache key so a cached enriched
+   * payload is only ever served back to a request whose entitlements select the
+   * exact same enricher set. Empty string when nothing is embeddable — keeping
+   * the cache key identical to the pre-enricher shape for unaffected routes.
+   */
+  signature: string
+  /**
+   * True only when there is at least one active enricher for the context AND
+   * every active enricher opted into `cacheableOnListHit`. When true, the
+   * enriched list payload may be stored in the cache and served on a hit without
+   * re-running enrichers. When false, enrichers MUST re-run on every request so
+   * the response reflects live data (cross-module reads, wall-clock values, etc.)
+   * and no live enrichment is embedded in the shared cache entry.
+   */
+  skipEnrichersOnCacheHit: boolean
+}
+
+/**
+ * Resolve, for the given context, whether the CRUD list cache may embed enricher
+ * output and the cache-key signature to partition by when it can.
+ *
+ * The enriched payload is only embeddable (and the cache hit allowed to skip
+ * enrichment) when every active enricher is `cacheableOnListHit` — i.e. its
+ * output is a pure function of the cached record and invalidated together with
+ * it. If any active enricher reads data the list cache does not invalidate on,
+ * the route falls back to caching the pre-enrichment payload and re-running
+ * enrichers on every request.
+ */
+export function resolveListCacheEnricherPlan(
+  targetEntity: string,
+  context: EnricherContext,
+): ListCacheEnricherPlan {
+  const active = getActiveEnrichers(targetEntity, context)
+  if (active.length === 0) return { signature: '', skipEnrichersOnCacheHit: false }
+  const allCacheable = active.every((entry) => entry.enricher.cacheableOnListHit === true)
+  if (!allCacheable) return { signature: '', skipEnrichersOnCacheHit: false }
+  return {
+    signature: active.map((entry) => entry.enricher.id).join(','),
+    skipEnrichersOnCacheHit: true,
+  }
+}
+
 type CacheLike = {
   get: (key: string) => Promise<unknown>
   set: (key: string, value: unknown, options?: { ttl?: number; tags?: string[] }) => Promise<unknown>

package/src/lib/crud/factory.ts

@@ -62,7 +62,7 @@ import {
 import { deriveCrudSegmentTag } from './cache-stats'
 import { createProfiler, shouldEnableProfiler, type Profiler } from '@open-mercato/shared/lib/profiler'
 import { getTranslationOverlayPlugin } from '@open-mercato/shared/lib/localization/overlay-plugin'
-import { applyResponseEnrichers, applyResponseEnricherToRecord } from './enricher-runner'
+import { applyResponseEnrichers, applyResponseEnricherToRecord, resolveListCacheEnricherPlan, type ListCacheEnricherPlan } from './enricher-runner'
 import type { EnricherContext } from './response-enricher'
 import type { ApiInterceptorMethod, InterceptorRequest, InterceptorResponse } from './api-interceptor'
 import { runApiInterceptorsAfter, runApiInterceptorsBefore } from './interceptor-runner'
@@ -879,13 +879,18 @@ function serializeSearchParams(params: URLSearchParams): string {
   return JSON.stringify(normalized)
 }
 
-function buildCrudCacheKey(resource: string, request: Request, ctx: CrudCtx): string {
+function buildCrudCacheKey(
+  resource: string,
+  request: Request,
+  ctx: CrudCtx,
+  enricherSignature = '',
+): string {
   const url = new URL(request.url)
   const scopeIds = collectScopeOrganizationIds(ctx)
   const scopeSegment = scopeIds.length
     ? scopeIds.map((id) => normalizeTagSegment(id)).sort((a, b) => a.localeCompare(b)).join(',')
     : 'none'
-  return [
+  const segments = [
     'crud',
     normalizeTagSegment(resource),
     'GET',
@@ -894,7 +899,18 @@ function buildCrudCacheKey(resource: string, request: Request, ctx: CrudCtx): st
     `selectedOrg:${normalizeTagSegment(ctx.selectedOrganizationId ?? null)}`,
     `scope:${scopeSegment}`,
     `query:${serializeSearchParams(url.searchParams)}`,
-  ].join('|')
+  ]
+  // The cached list payload already embeds enricher output (enrichment runs before
+  // the cache store), so the cache key MUST partition by the set of enrichers a
+  // request's entitlements actually select. Two callers in the same tenant/org
+  // scope but with different active enrichers (e.g. one holding the enricher's
+  // gating feature and one not) get distinct entries, which lets the cache-hit
+  // path skip re-running enrichers without leaking ACL-gated fields across
+  // feature cohorts. Routes without enrichers pass '' and keep their key shape.
+  if (enricherSignature) {
+    segments.push(`enrichers:${normalizeTagSegment(enricherSignature)}`)
+  }
+  return segments.join('|')
 }
 
 function extractRecordIds(items: any[], idField: string): string[] {
@@ -1106,6 +1122,21 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
     return resolveUserFeaturesOnce(ctx)
   }
 
+  const NO_ENRICHER_CACHE_PLAN: ListCacheEnricherPlan = { signature: '', skipEnrichersOnCacheHit: false }
+
+  /**
+   * Resolve whether this request's CRUD list cache may embed enricher output and
+   * the cache-key signature to partition by. Returns the no-op plan when no
+   * enrichers are configured or active — keeping the cache key identical to the
+   * pre-enricher shape and forcing enrichers (if any) to run on every request.
+   */
+  async function resolveListCachePlan(ctx: CrudCtx): Promise<ListCacheEnricherPlan> {
+    if (!opts.enrichers?.entityId) return NO_ENRICHER_CACHE_PLAN
+    const enricherCtx = await buildEnricherContext(ctx)
+    if (!enricherCtx) return NO_ENRICHER_CACHE_PLAN
+    return resolveListCacheEnricherPlan(opts.enrichers.entityId, enricherCtx)
+  }
+
   const interceptorContextCache = new WeakMap<object, ReturnType<typeof buildInterceptorContextInner>>()
 
   async function buildInterceptorContextInner(ctx: CrudCtx) {
@@ -1357,7 +1388,8 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
         ? process.hrtime.bigint()
         : null
       const cache = cacheEnabled ? resolveCrudCache(ctx.container) : null
-      const cacheKey = cacheEnabled ? buildCrudCacheKey(resourceKind, request, ctx) : null
+      const enricherCachePlan = cacheEnabled ? await resolveListCachePlan(ctx) : NO_ENRICHER_CACHE_PLAN
+      const cacheKey = cacheEnabled ? buildCrudCacheKey(resourceKind, request, ctx, enricherCachePlan.signature) : null
       let cacheStatus: 'hit' | 'miss' = 'miss'
       let cachedValue: CrudCacheStoredValue | null = null
 
@@ -1414,6 +1446,25 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
         }
       }
 
+      // Enrich the (miss-path) payload and store it in the CRUD cache, honoring
+      // the request's enricher cache plan:
+      // - skipEnrichersOnCacheHit: every active enricher is record-pure and safe
+      //   to embed, so enrich first and cache the enriched payload (a later hit
+      //   serves it without re-running enrichers — the #2222 optimization).
+      // - otherwise: cache the PRE-enrichment payload, then enrich only the
+      //   response. A later hit re-runs enrichers against fresh data, and no live
+      //   enrichment is ever embedded in the shared cache entry (avoids stale
+      //   cross-module output and cross-cohort ACL leaks).
+      const enrichAndStorePayload = async (payload: any) => {
+        if (enricherCachePlan.skipEnrichersOnCacheHit) {
+          await enrichListPayload(payload, ctx, profiler)
+          await maybeStoreCrudCache(payload)
+          return
+        }
+        await maybeStoreCrudCache(payload)
+        await enrichListPayload(payload, ctx, profiler)
+      }
+
       const logCacheOutcome = (event: 'hit' | 'miss', itemCount: number) => {
         if (!cacheTimerStart) return
         const elapsedMs = Number(process.hrtime.bigint() - cacheTimerStart) / 1_000_000
@@ -1498,7 +1549,20 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
           return json(cacheAfterInterceptors.body, { status: cacheAfterInterceptors.statusCode, headers: cacheAfterInterceptors.headers })
         }
         Object.assign(payload, cacheAfterInterceptors.body)
-        await enrichListPayload(payload, ctx, profiler)
+        if (enricherCachePlan.skipEnrichersOnCacheHit) {
+          // Every active enricher is record-pure: the cached payload already
+          // embeds their output and the cache key is partitioned by the active
+          // enricher signature, so the cached enrichment matches this caller's
+          // entitlements exactly. Skipping it removes the per-hit enricher cost
+          // (the ~15ms regression reported in #2222) while staying ACL-gated.
+          profiler.mark('enrichers_skipped_cache_hit', { enricherSignature: enricherCachePlan.signature || null })
+        } else {
+          // Live-mode enrichers (or none): the cached payload is the
+          // pre-enrichment base, so re-run enrichers against current data. This
+          // keeps cross-module / time-dependent enrichment (catalog images,
+          // pipeline state) fresh on cache hits.
+          await enrichListPayload(payload, ctx, profiler)
+        }
         logCacheOutcome('hit', items.length)
         const response = respondWithPayload(payload)
         finishProfile({ result: 'cache_hit', cacheStatus })
@@ -1728,8 +1792,7 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
           return json(afterInterceptors.body, { status: afterInterceptors.statusCode, headers: afterInterceptors.headers })
         }
         Object.assign(payload, afterInterceptors.body)
-        await enrichListPayload(payload, ctx, profiler)
-        await maybeStoreCrudCache(payload)
+        await enrichAndStorePayload(payload)
         profiler.mark('cache_store_attempt', { cacheEnabled })
         logCacheOutcome(cacheStatus, payload.items.length)
         const response = respondWithPayload(payload)
@@ -1914,8 +1977,7 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
         return json(fallbackAfterInterceptors.body, { status: fallbackAfterInterceptors.statusCode, headers: fallbackAfterInterceptors.headers })
       }
       Object.assign(payload, fallbackAfterInterceptors.body)
-      await enrichListPayload(payload, ctx, profiler)
-      await maybeStoreCrudCache(payload)
+      await enrichAndStorePayload(payload)
       profiler.mark('cache_store_attempt', { cacheEnabled })
       logCacheOutcome(cacheStatus, payload.items.length)
       const response = respondWithPayload(payload)

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

@@ -71,6 +71,23 @@ export interface ResponseEnricher<TRecord = any, TEnriched = any> {
   /** If true, enricher errors propagate as HTTP errors. Default: false */
   critical?: boolean
 
+  /**
+   * When true, this enricher's output for a record is a pure function of that
+   * record's own cached state and is invalidated together with it, so the
+   * enriched value is safe to embed in the CRUD list cache and serve back on a
+   * cache hit WITHOUT re-running the enricher (the #2222 cache-hit optimization).
+   *
+   * Leave this false (the default) for any enricher whose output depends on data
+   * the list cache does not invalidate on: cross-module / cross-entity reads
+   * (e.g. a product image fetched for a sales line), wall-clock-relative values
+   * (e.g. "days in stage"), or aggregates over other tables. Such enrichers MUST
+   * re-run on every request so the response reflects current data — embedding
+   * their output in the shared cache entry would serve stale values.
+   *
+   * Default: false (fail-closed — always re-run on a list cache hit).
+   */
+  cacheableOnListHit?: boolean
+
   /** Tenant IDs where this enricher should be disabled. */
   disabledTenantIds?: string[]