@open-mercato/shared 0.6.7 → 0.6.8-develop.6874.1.982d6097d8

package/src/lib/bootstrap/dynamicLoader.ts

@@ -1,16 +1,98 @@
 import type { BootstrapData } from './types'
+import type { AppDiRegistrar } from '../di/container'
 import { findAppRoot, type AppRoot } from './appResolver'
 import { registerEntityIds } from '../encryption/entityIds'
+import { createLogger } from '../logger'
 import {
   ensureMikroOrmV7GeneratedCacheCompatibility,
   recoverMikroOrmV7GeneratedCacheFromImportError,
 } from './generatedCacheRecovery'
+import { CLIENT_ONLY_STUB_NAMESPACE, createClientOnlyStubPlugin } from './clientOnlyModules'
 import path from 'node:path'
 import fs from 'node:fs'
 import crypto from 'node:crypto'
 import { createRequire } from 'node:module'
 import { pathToFileURL } from 'node:url'
 
+const logger = createLogger('shared').child({ component: 'bootstrap' })
+
+/**
+ * Thrown when an expected generated source file is absent.
+ *
+ * Optional registries treat this as the supported compatibility case (an app
+ * that never generated the file), which is what makes it distinguishable from
+ * a file that exists but fails to compile or import.
+ */
+class GeneratedFileNotFoundError extends Error {
+  readonly filePath: string
+
+  constructor(filePath: string) {
+    super(`Generated file not found: ${filePath}`)
+    this.name = 'GeneratedFileNotFoundError'
+    this.filePath = filePath
+  }
+}
+
+/**
+ * esbuild plugins for the CLI bundle, in resolution order. The client-only stub must come
+ * first so it wins over the alias and external plugins for `*.client` dynamic imports.
+ *
+ * Exported so the wiring itself is testable: a test that only exercises
+ * `createClientOnlyStubPlugin` in isolation stays green if the plugin is dropped from this
+ * list, which would silently reintroduce #4623.
+ */
+export function createCliBundlePlugins(appRoot: string): import('esbuild').Plugin[] {
+  // Plugin to resolve the @/ alias the way the app tsconfig maps it:
+  // `@/.mercato/*` to the app root, every other `@/*` to the app's src/ directory.
+  const aliasPlugin: import('esbuild').Plugin = {
+    name: 'alias-resolver',
+    setup(build) {
+      build.onResolve({ filter: /^@\// }, (args) => {
+        const rest = args.path.slice('@/'.length)
+        const bases = rest.startsWith('.mercato/')
+          ? [path.join(appRoot, rest)]
+          : [path.join(appRoot, 'src', rest), path.join(appRoot, rest)]
+        for (const base of bases) {
+          if (fs.existsSync(base) && fs.statSync(base).isFile()) {
+            return { path: base }
+          }
+          for (const suffix of ['.ts', '.tsx', '/index.ts', '/index.tsx']) {
+            if (fs.existsSync(base + suffix)) {
+              return { path: base + suffix }
+            }
+          }
+        }
+        // Nothing matched — hand esbuild the literal mapping so it reports the
+        // missing file against the path the app author actually wrote.
+        return { path: path.join(appRoot, rest) }
+      })
+    },
+  }
+
+  // Plugin to mark non-JSON package imports as external
+  const externalNonJsonPlugin: import('esbuild').Plugin = {
+    name: 'external-non-json',
+    setup(build) {
+      // Mark all package imports as external EXCEPT JSON files
+      // Filter matches paths that don't start with . or / (package imports like @open-mercato/shared)
+      build.onResolve({ filter: /^[^./]/ }, (args) => {
+        // Skip Windows absolute paths (e.g., C:\...) - they're local files, not packages
+        if (/^[a-zA-Z]:/.test(args.path)) {
+          return null // Let esbuild handle it
+        }
+        // If it's a JSON file, let esbuild bundle it
+        if (args.path.endsWith('.json')) {
+          return null // Let esbuild handle it
+        }
+        // Otherwise mark as external
+        return { path: args.path, external: true }
+      })
+    },
+  }
+
+  return [createClientOnlyStubPlugin(), aliasPlugin, externalNonJsonPlugin]
+}
+
 const DYNAMIC_LOADER_CACHE_VERSION = 4
 
 type DynamicLoaderCacheMetadata = {
@@ -167,6 +249,7 @@ function collectDependencyHashes(
 ): Record<string, string> {
   return Object.fromEntries(
     Object.keys(inputs)
+      .filter((inputPath) => !inputPath.startsWith(`${CLIENT_ONLY_STUB_NAMESPACE}:`))
       .map((inputPath) => {
         const absolutePath = path.isAbsolute(inputPath)
           ? inputPath
@@ -221,14 +304,33 @@ function cacheIsValid(
     && dependenciesAreValid(appRoot, metadata.dependencies)
 }
 
+/**
+ * Options for `compileAndImport`.
+ *
+ * Both paths default to the generated-registry layout (`<appRoot>/.mercato/generated/<file>.ts`
+ * compiled to a `.mjs` sibling). Sources that live elsewhere in the app — `src/di.ts` — MUST pass
+ * both explicitly: the default app root is derived by walking three directories up from the source,
+ * which only holds inside `.mercato/generated`.
+ */
+type CompileAndImportOptions = {
+  appRoot?: string
+  outFile?: string
+  allowRecovery?: boolean
+}
+
 /**
  * Compile a TypeScript file to JavaScript using esbuild bundler.
  * This bundles the file and all its dependencies, handling JSON imports properly.
- * The compiled file is written next to the source file with a .mjs extension.
+ * The compiled file is written next to the source file with a .mjs extension unless
+ * `outFile` says otherwise.
  */
-async function compileAndImport(tsPath: string, allowRecovery: boolean = true): Promise<Record<string, unknown>> {
-  const jsPath = tsPath.replace(/\.ts$/, '.mjs')
-  const appRoot = path.dirname(path.dirname(path.dirname(tsPath)))
+async function compileAndImport(
+  tsPath: string,
+  options: CompileAndImportOptions = {},
+): Promise<Record<string, unknown>> {
+  const allowRecovery = options.allowRecovery ?? true
+  const jsPath = options.outFile ?? tsPath.replace(/\.ts$/, '.mjs')
+  const appRoot = options.appRoot ?? path.dirname(path.dirname(path.dirname(tsPath)))
   const appTsconfig = path.join(appRoot, 'tsconfig.json')
   const metadataPath = cacheMetadataPath(jsPath)
 
@@ -236,7 +338,7 @@ async function compileAndImport(tsPath: string, allowRecovery: boolean = true):
   const tsconfigExists = fs.existsSync(appTsconfig)
 
   if (!tsExists) {
-    throw new Error(`Generated file not found: ${tsPath}`)
+    throw new GeneratedFileNotFoundError(tsPath)
   }
   if (!tsconfigExists) {
     throw new Error(`App TypeScript config not found: ${appTsconfig}`)
@@ -247,50 +349,10 @@ async function compileAndImport(tsPath: string, allowRecovery: boolean = true):
   const needsCompile = !cacheIsValid(appRoot, jsPath, metadataPath, expectedInputHash)
 
   if (needsCompile) {
+    fs.mkdirSync(path.dirname(jsPath), { recursive: true })
     // Dynamically import esbuild only when needed
     const esbuild = await import('esbuild')
 
-    // Plugin to resolve @/ alias to app root (works for @app modules)
-    const aliasPlugin: import('esbuild').Plugin = {
-      name: 'alias-resolver',
-      setup(build) {
-        // Resolve @/ alias to app root
-        build.onResolve({ filter: /^@\// }, (args) => {
-          const resolved = path.join(appRoot, args.path.slice(2))
-          // Try with .ts extension if base path doesn't exist
-          if (!fs.existsSync(resolved) && fs.existsSync(resolved + '.ts')) {
-            return { path: resolved + '.ts' }
-          }
-          // Also check for /index.ts if it's a directory
-          if (fs.existsSync(resolved) && fs.statSync(resolved).isDirectory() && fs.existsSync(path.join(resolved, 'index.ts'))) {
-            return { path: path.join(resolved, 'index.ts') }
-          }
-          return { path: resolved }
-        })
-      },
-    }
-
-    // Plugin to mark non-JSON package imports as external
-    const externalNonJsonPlugin: import('esbuild').Plugin = {
-      name: 'external-non-json',
-      setup(build) {
-        // Mark all package imports as external EXCEPT JSON files
-        // Filter matches paths that don't start with . or / (package imports like @open-mercato/shared)
-        build.onResolve({ filter: /^[^./]/ }, (args) => {
-          // Skip Windows absolute paths (e.g., C:\...) - they're local files, not packages
-          if (/^[a-zA-Z]:/.test(args.path)) {
-            return null // Let esbuild handle it
-          }
-          // If it's a JSON file, let esbuild bundle it
-          if (args.path.endsWith('.json')) {
-            return null // Let esbuild handle it
-          }
-          // Otherwise mark as external
-          return { path: args.path, external: true }
-        })
-      },
-    }
-
     // Use esbuild.build with bundling to handle JSON imports
     const result = await esbuild.build({
       entryPoints: [tsPath],
@@ -302,7 +364,7 @@ async function compileAndImport(tsPath: string, allowRecovery: boolean = true):
       platform: 'node',
       target: 'node18',
       tsconfig: appTsconfig,
-      plugins: [aliasPlugin, externalNonJsonPlugin],
+      plugins: createCliBundlePlugins(appRoot),
       // Allow JSON imports
       loader: { '.json': 'json' },
     })
@@ -333,25 +395,45 @@ async function compileAndImport(tsPath: string, allowRecovery: boolean = true):
       throw error
     }
 
-    return compileAndImport(tsPath, false)
+    return compileAndImport(tsPath, { ...options, allowRecovery: false })
   }
 }
 
 
 /**
- * Dynamically load bootstrap data from a resolved app directory.
- *
- * IMPORTANT: This only works in unbundled contexts (CLI, tsx).
- * Do NOT use this in Next.js bundled code - use static imports instead.
+ * Load a generated registry that older apps may not have generated yet.
  *
- * For CLI context, we skip loading modules.generated.ts which has Next.js dependencies.
- * CLI commands are discovered separately via the CLI module system.
- *
- * @param appRoot - Optional explicit app root path. If not provided, will search from cwd.
- * @returns The loaded bootstrap data
- * @throws Error if app root cannot be found or generated files are missing
+ * An absent source file is the supported compatibility case and resolves to
+ * `fallback` quietly. Any other failure — a compile error, a broken import, a
+ * runtime throw at module scope — still resolves to `fallback` so bootstrap
+ * keeps working, but is reported at error level: a registry that silently
+ * degrades to nothing is exactly how command interceptors stopped applying in
+ * worker/CLI processes (#4327, #4491).
  */
-export async function loadBootstrapData(appRoot?: string): Promise<BootstrapData> {
+async function loadOptionalGeneratedModule(
+  tsPath: string,
+  fallback: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+  try {
+    return await compileAndImport(tsPath)
+  } catch (error) {
+    if (error instanceof GeneratedFileNotFoundError) {
+      logger.debug('Optional generated registry not present, using empty fallback', {
+        file: path.basename(tsPath),
+      })
+      return fallback
+    }
+
+    logger.error('Failed to load generated registry, continuing without its entries', {
+      file: path.basename(tsPath),
+      filePath: tsPath,
+      err: error,
+    })
+    return fallback
+  }
+}
+
+function resolveAppRootOrThrow(appRoot?: string): AppRoot {
   const resolved: AppRoot | null = appRoot
     ? {
         generatedDir: path.join(appRoot, '.mercato', 'generated'),
@@ -368,6 +450,68 @@ export async function loadBootstrapData(appRoot?: string): Promise<BootstrapData
     )
   }
 
+  return resolved
+}
+
+/**
+ * Load the app-level DI registrar (`src/di.ts`) for the dynamic bootstrap path.
+ *
+ * The Next.js runtime imports `@/di` statically from its own `src/bootstrap.ts` and hands the
+ * registrar to `createBootstrap`. Worker, scheduler and CLI processes bootstrap through
+ * `bootstrapFromAppRoot` instead, where the `@/` alias does not exist — so without this the app's
+ * DI registrations silently never ran there, and every request container paid a failed
+ * `import('@/di')` resolution (the compatibility fallback in `lib/di/container.ts`).
+ *
+ * An absent `src/di.ts` is the supported case and resolves to `null` quietly. A file that exists
+ * but cannot be compiled, imported, or does not export `register` is reported at error level and
+ * still resolves to `null`, so a broken app DI module degrades the same way a broken generated
+ * registry does (#4327, #4491) instead of taking the whole process down.
+ */
+async function loadAppDiRegistrar(appDir: string): Promise<AppDiRegistrar | null> {
+  const tsPath = path.join(appDir, 'src', 'di.ts')
+  if (!fs.existsSync(tsPath)) {
+    logger.debug('App-level DI module not present, skipping its registrations', { filePath: tsPath })
+    return null
+  }
+
+  try {
+    const appDiModule = await compileAndImport(tsPath, {
+      appRoot: appDir,
+      outFile: path.join(appDir, '.mercato', 'generated', 'app-di.compiled.mjs'),
+    })
+    const register = appDiModule.register
+    if (typeof register !== 'function') {
+      logger.error('App-level DI module exports no register(); its registrations are skipped', {
+        filePath: tsPath,
+      })
+      return null
+    }
+    return register as AppDiRegistrar
+  } catch (error) {
+    logger.error('Failed to load the app-level DI module; its registrations are skipped', {
+      filePath: tsPath,
+      err: error,
+    })
+    return null
+  }
+}
+
+/**
+ * Dynamically load bootstrap data from a resolved app directory.
+ *
+ * IMPORTANT: This only works in unbundled contexts (CLI, tsx).
+ * Do NOT use this in Next.js bundled code - use static imports instead.
+ *
+ * For CLI context, we skip loading modules.generated.ts which has Next.js dependencies.
+ * CLI commands are discovered separately via the CLI module system.
+ *
+ * @param appRoot - Optional explicit app root path. If not provided, will search from cwd.
+ * @returns The loaded bootstrap data
+ * @throws Error if app root cannot be found or generated files are missing
+ */
+export async function loadBootstrapData(appRoot?: string): Promise<BootstrapData> {
+  const resolved = resolveAppRootOrThrow(appRoot)
+
   const { generatedDir } = resolved
 
   ensureMikroOrmV7GeneratedCacheCompatibility(resolved.appDir)
@@ -392,10 +536,12 @@ export async function loadBootstrapData(appRoot?: string): Promise<BootstrapData
     compileAndImport(path.join(generatedDir, 'modules.cli.generated.ts')),
     compileAndImport(path.join(generatedDir, 'entities.generated.ts')),
     compileAndImport(path.join(generatedDir, 'di.generated.ts')),
-    compileAndImport(path.join(generatedDir, 'search.generated.ts')).catch(() => ({ searchModuleConfigs: [] })),
-    compileAndImport(path.join(generatedDir, 'command-loaders.generated.ts')).catch(() => ({ commandLoaderEntries: [] })),
-    compileAndImport(path.join(generatedDir, 'command-interceptors.generated.ts')).catch(() => ({ commandInterceptorEntries: [] })),
-    compileAndImport(path.join(generatedDir, 'workflows.generated.ts')).catch(() => ({ allCodeWorkflows: [] })),
+    loadOptionalGeneratedModule(path.join(generatedDir, 'search.generated.ts'), { searchModuleConfigs: [] }),
+    loadOptionalGeneratedModule(path.join(generatedDir, 'command-loaders.generated.ts'), { commandLoaderEntries: [] }),
+    loadOptionalGeneratedModule(path.join(generatedDir, 'command-interceptors.generated.ts'), {
+      commandInterceptorEntries: [],
+    }),
+    loadOptionalGeneratedModule(path.join(generatedDir, 'workflows.generated.ts'), { allCodeWorkflows: [] }),
   ])
 
   return {
@@ -437,8 +583,10 @@ export async function loadBootstrapData(appRoot?: string): Promise<BootstrapData
  */
 export async function bootstrapFromAppRoot(appRoot?: string): Promise<BootstrapData> {
   const { createBootstrap, waitForAsyncRegistration } = await import('./factory.js')
-  const data = await loadBootstrapData(appRoot)
-  const bootstrap = createBootstrap(data)
+  const resolved = resolveAppRootOrThrow(appRoot)
+  const data = await loadBootstrapData(resolved.appDir)
+  const appDiRegistrar = await loadAppDiRegistrar(resolved.appDir)
+  const bootstrap = createBootstrap(data, appDiRegistrar ? { appDiRegistrar } : {})
   bootstrap()
   // In CLI context, wait for async registrations (UI widgets, search configs, etc.)
   await waitForAsyncRegistration()

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

@@ -7,6 +7,10 @@ import {
 } from '../command-interceptor-runner'
 import type { CommandInterceptor, CommandInterceptorContext, CommandInterceptorUndoContext } from '../command-interceptor'
 import { createLogger } from '@open-mercato/shared/lib/logger'
+import {
+  applyAclFeatureOverrides,
+  resetModuleContractOverridesForTests,
+} from '@open-mercato/shared/modules/overrides'
 
 jest.mock('@open-mercato/shared/lib/logger', () => {
   const mocked = {
@@ -59,6 +63,10 @@ describe('matchesCommandPattern', () => {
 })
 
 describe('runCommandInterceptorsBefore', () => {
+  afterEach(() => {
+    resetModuleContractOverridesForTests()
+  })
+
   it('returns ok when no interceptors match', async () => {
     const interceptor = makeInterceptor({
       id: 'i1',
@@ -158,6 +166,26 @@ describe('runCommandInterceptorsBefore', () => {
     expect(withWildcard.ok).toBe(false)
     expect(withWildcard.error?.message).toBe('Blocked by wildcard')
   })
+
+  it('does not run an interceptor gated by a nulled ACL feature', async () => {
+    applyAclFeatureOverrides({ 'premium.audit': null })
+    const interceptor = makeInterceptor({
+      id: 'i1',
+      features: ['premium.audit'],
+      beforeExecute: jest.fn().mockResolvedValue({ ok: false }),
+    })
+
+    const result = await runCommandInterceptorsBefore(
+      [interceptor],
+      'customers.create-person',
+      {},
+      baseContext,
+      ['*', 'premium.audit'],
+    )
+
+    expect(result.ok).toBe(true)
+    expect(interceptor.beforeExecute).not.toHaveBeenCalled()
+  })
 })
 
 describe('runCommandInterceptorsAfter', () => {

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

@@ -31,6 +31,7 @@ import {
 } from './command-interceptor-runner'
 import type { CommandInterceptorContext } from './command-interceptor'
 import { CommandInterceptorError } from './errors'
+import { isReadProjectionAlwaysConsistent } from '@open-mercato/shared/lib/data/consistency'
 import { createLogger } from '../logger'
 
 const logger = createLogger('shared').child({ component: 'commands' })
@@ -697,7 +698,10 @@ export class CommandBus {
     try {
       const dataEngine = (container.resolve('dataEngine') as DataEngine)
       await dataEngine.flushOrmEntityChanges(suppress)
-    } catch {
+    } catch (error) {
+      if (isReadProjectionAlwaysConsistent()) {
+        throw error
+      }
       // best-effort: failures should not block command execution
     }
   }

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

@@ -3,7 +3,7 @@ import type {
   CommandInterceptorContext,
   CommandInterceptorUndoContext,
 } from './command-interceptor'
-import { hasAllFeatures } from '../../security/features'
+import { authorizeFeatures } from '../../security/featurePolicy'
 import { createLogger } from '../logger'
 
 const logger = createLogger('shared').child({ component: 'commands' })
@@ -33,7 +33,7 @@ function collectMatching(
 ): CommandInterceptor[] {
   return interceptors
     .filter((i) => matchesCommandPattern(i.targetCommand, commandId))
-    .filter((i) => hasAllFeatures(userFeatures, i.features))
+    .filter((i) => authorizeFeatures(i.features ?? [], { grantedFeatures: userFeatures }))
     .sort((a, b) => (a.priority ?? 50) - (b.priority ?? 50))
 }
 

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

@@ -0,0 +1,171 @@
+// Regression coverage for the CRUD list cache key missing a caller-identity
+// segment: two callers in the same tenant/org scope requesting the identical
+// URL must NOT share cache entries, because list payloads can vary per caller —
+// buildFilters may narrow by ctx.auth (e.g. ?mine=true on staff time-projects,
+// the isSuperAdmin branch on scheduler jobs), before-interceptor query rewrites
+// are feature-gated per user, and afterList/after-interceptor output is
+// embedded in the stored payload.
+
+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 { z } from 'zod'
+
+const defaultOrganizationId = 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa'
+const defaultTenantId = '123e4567-e89b-12d3-a456-426614174000'
+
+let mockAuthSub = 'user-a'
+let mockAuthKeyId: string | null = null
+
+const em = {}
+
+// Returns rows derived from the per-caller filter buildFilters produced, so a
+// cross-user cache hit is observable as one user's rows in another's response.
+const queryEngine = {
+  query: jest.fn(async (_entity: string, opts: Record<string, any>) => {
+    const owner = opts?.filters?.owner_user_id?.$eq ?? 'unfiltered'
+    return {
+      items: [{ id: `todo-of-${owner}`, title: `Owned by ${owner}`, organization_id: defaultOrganizationId, tenant_id: defaultTenantId }],
+      total: 1,
+    }
+  }),
+}
+
+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 () => {}) }
+
+jest.mock('@open-mercato/shared/lib/di/container', () => ({
+  createRequestContainer: async () => ({
+    resolve: (name: string) => ({
+      em,
+      queryEngine,
+      cache,
+      accessLogService,
+    } as any)[name],
+  }),
+}))
+
+jest.mock('@open-mercato/shared/lib/auth/server', () => {
+  const buildAuth = () => ({
+    sub: mockAuthSub,
+    keyId: mockAuthKeyId ?? undefined,
+    orgId: 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa',
+    tenantId: '123e4567-e89b-12d3-a456-426614174000',
+    roles: ['admin'],
+  })
+  return {
+    getAuthFromCookies: async () => buildAuth(),
+    getAuthFromRequest: async () => buildAuth(),
+  }
+})
+
+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 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: (_query: any, ctx: any) => ({ owner_user_id: { $eq: ctx.auth?.sub ?? null } } as any),
+    transformItem: (i: any) => ({ id: i.id, title: i.title }),
+  },
+})
+
+const url = 'http://x/api/example/todos?page=1&pageSize=10&sortField=id&sortDir=asc'
+
+describe('CRUD Factory — list cache is partitioned per caller identity', () => {
+  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()
+    mockAuthSub = 'user-a'
+    mockAuthKeyId = null
+    registerApiInterceptors([])
+  })
+
+  it('caches per user and still serves same-user repeat requests from cache', async () => {
+    const first = await route.GET(new Request(url))
+    expect(first.status).toBe(200)
+    expect(first.headers.get('x-om-cache')).toBe('miss')
+    expect((await first.json()).items[0].id).toBe('todo-of-user-a')
+
+    const second = await route.GET(new Request(url))
+    expect(second.headers.get('x-om-cache')).toBe('hit')
+    expect((await second.json()).items[0].id).toBe('todo-of-user-a')
+    expect(queryEngine.query).toHaveBeenCalledTimes(1)
+  })
+
+  it('does not serve one user\'s cached rows to another user on the identical URL', async () => {
+    mockAuthSub = 'user-a'
+    const aRes = await route.GET(new Request(url))
+    expect((await aRes.json()).items[0].id).toBe('todo-of-user-a')
+    expect(store.size).toBe(1)
+
+    mockAuthSub = 'user-b'
+    const bRes = await route.GET(new Request(url))
+    expect(bRes.headers.get('x-om-cache')).toBe('miss')
+    expect((await bRes.json()).items[0].id).toBe('todo-of-user-b')
+    expect(store.size).toBe(2)
+
+    mockAuthSub = 'user-a'
+    const aAgain = await route.GET(new Request(url))
+    expect(aAgain.headers.get('x-om-cache')).toBe('hit')
+    expect((await aAgain.json()).items[0].id).toBe('todo-of-user-a')
+  })
+
+  it('keys every entry with an identity segment, preferring the API key id over the user id', async () => {
+    await route.GET(new Request(url))
+    const userKey = Array.from(store.keys())[0] as string
+    expect(userKey).toContain('user:user-a')
+
+    store.clear()
+    mockAuthKeyId = 'api-key-9'
+    await route.GET(new Request(url))
+    const apiKeyKey = Array.from(store.keys())[0] as string
+    expect(apiKeyKey).toContain('user:api-key-9')
+  })
+})