@open-mercato/shared 0.8.1-develop.7296.1.2111d779db → 0.9.0

package/src/lib/commands/flush.ts

@@ -1,6 +1,11 @@
 import type { EntityManager } from '@mikro-orm/postgresql'
 import type { IsolationLevel } from '@mikro-orm/core'
 import { createLogger } from '../logger'
+import { getTelemetryRuntime } from '../telemetry/runtime'
+import {
+  beginTransactionLifetime,
+  completeTransactionLifetime,
+} from './transaction-lifetime'
 
 const logger = createLogger('shared').child({ component: 'commands' })
 
@@ -171,6 +176,7 @@ export async function withAtomicFlush(
   }
 
   await em.begin(options.isolationLevel ? { isolationLevel: options.isolationLevel } : undefined)
+  const transactionLifetime = beginTransactionLifetime(em)
   try {
     await runPhasesAndFlush()
     await em.commit()
@@ -180,6 +186,16 @@ export async function withAtomicFlush(
     } catch {
       // rollback failure should not mask the original error; intentionally swallowed
     }
+    try {
+      await completeTransactionLifetime(em, transactionLifetime, 'rolled_back')
+    } catch (completionErr) {
+      logger.error('withAtomicFlush: rollback completion failed', { label: options.label ?? null, err: completionErr })
+      getTelemetryRuntime()?.reportError(completionErr, {
+        module: 'shared',
+        code: 'shared.transaction_rollback_completion_failed',
+      })
+    }
     throw err
   }
+  await completeTransactionLifetime(em, transactionLifetime, 'committed')
 }

package/src/lib/commands/index.ts

@@ -4,6 +4,13 @@ export { CommandBus } from './command-bus'
 export * from './customFieldSnapshots'
 export * from './undo'
 export * from './redo'
+export {
+  getTransactionLifetime,
+  onTransactionLifetimeComplete,
+  ownsTransactionLifetime,
+  type TransactionLifetime,
+  type TransactionOutcome,
+} from './transaction-lifetime'
 export {
   CommandInterceptorError,
   isCommandInterceptorError,

package/src/lib/commands/redo.ts

@@ -3,7 +3,7 @@ import type { CommandRuntimeContext, CommandUndoLogEntry } from './types'
 import type { DataEngine } from '@open-mercato/shared/lib/data/engine'
 import type { CrudEventsConfig, CrudIndexerConfig } from '@open-mercato/shared/lib/crud/types'
 import { CrudHttpError, conflict, isUniqueViolation } from '@open-mercato/shared/lib/crud/errors'
-import { extractUndoPayload, type UndoPayload } from './undo'
+import { extractUndoPayload, reviveSnapshotDates, type UndoPayload } from './undo'
 import { emitCrudSideEffects } from './helpers'
 import { withAtomicFlush } from './flush'
 
@@ -22,7 +22,8 @@ const DEFAULT_SNAPSHOT_DATE_FIELDS = ['createdAt', 'updatedAt', 'deletedAt'] as
 
 /**
  * Turn an after-snapshot into a create seed by shallow-cloning it and reviving the
- * declared date fields from ISO strings back to `Date`. Single-row snapshots are a
+ * declared date fields from ISO strings back to `Date` (via `reviveSnapshotDates`,
+ * which throws on an unparsable value). Single-row snapshots are a
  * faithful serialized row whose keys already equal entity property names, so the
  * snapshot doubles as the seed once dates are revived — no per-command mapping needed.
  */
@@ -30,12 +31,7 @@ export function reviveSnapshotSeed(
   snapshot: Record<string, unknown>,
   dateFields: readonly string[] = DEFAULT_SNAPSHOT_DATE_FIELDS,
 ): Record<string, unknown> {
-  const seed: Record<string, unknown> = { ...snapshot }
-  for (const field of dateFields) {
-    const value = seed[field]
-    if (typeof value === 'string') seed[field] = new Date(value)
-  }
-  return seed
+  return reviveSnapshotDates(snapshot, dateFields)
 }
 
 /**

package/src/lib/commands/transaction-lifetime.ts

@@ -0,0 +1,88 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createLogger } from '../logger'
+import { getTelemetryRuntime } from '../telemetry/runtime'
+
+const logger = createLogger('shared').child({ component: 'transaction-lifetime' })
+
+export type TransactionOutcome = 'committed' | 'rolled_back'
+
+const transactionLifetimeBrand: unique symbol = Symbol('open-mercato.transaction-lifetime')
+
+export type TransactionLifetime = {
+  readonly [transactionLifetimeBrand]: true
+}
+
+type ActiveTransactionLifetime = TransactionLifetime & {
+  completionCallbacks: Set<(outcome: TransactionOutcome) => void | Promise<void>>
+}
+
+const activeTransactionLifetimes = new AsyncLocalStorage<Map<object, ActiveTransactionLifetime>>()
+
+export function beginTransactionLifetime(em: EntityManager): TransactionLifetime {
+  const key = em as object
+  const currentLifetimes = activeTransactionLifetimes.getStore()
+  if (currentLifetimes?.has(key)) {
+    throw new Error('[internal] Transaction lifetime already active for EntityManager')
+  }
+  const lifetime: ActiveTransactionLifetime = {
+    [transactionLifetimeBrand]: true,
+    completionCallbacks: new Set(),
+  }
+  const scopedLifetimes = new Map(currentLifetimes)
+  scopedLifetimes.set(key, lifetime)
+  activeTransactionLifetimes.enterWith(scopedLifetimes)
+  return lifetime
+}
+
+export function getTransactionLifetime(em: EntityManager): TransactionLifetime | null {
+  return activeTransactionLifetimes.getStore()?.get(em as object) ?? null
+}
+
+export function ownsTransactionLifetime(
+  em: EntityManager,
+  lifetime: TransactionLifetime | null | undefined,
+): lifetime is TransactionLifetime {
+  return lifetime != null && activeTransactionLifetimes.getStore()?.get(em as object) === lifetime
+}
+
+export function onTransactionLifetimeComplete(
+  em: EntityManager,
+  callback: (outcome: TransactionOutcome) => void | Promise<void>,
+): void {
+  const lifetime = activeTransactionLifetimes.getStore()?.get(em as object)
+  if (!lifetime) {
+    throw new Error('[internal] Transaction-owned state requires an active transaction lifetime')
+  }
+  lifetime.completionCallbacks.add(callback)
+}
+
+export async function completeTransactionLifetime(
+  em: EntityManager,
+  lifetimeToken: TransactionLifetime,
+  outcome: TransactionOutcome,
+): Promise<void> {
+  const key = em as object
+  const currentLifetimes = activeTransactionLifetimes.getStore()
+  const lifetime = currentLifetimes?.get(key)
+  if (!currentLifetimes || !lifetime || lifetime !== lifetimeToken) {
+    throw new Error('[internal] Transaction lifetime mismatch for EntityManager')
+  }
+  currentLifetimes.delete(key)
+  const failures: unknown[] = []
+  for (const callback of lifetime.completionCallbacks) {
+    try {
+      await callback(outcome)
+    } catch (err) {
+      failures.push(err)
+    }
+  }
+  for (const err of failures) {
+    logger.error('Transaction completion callback failed', { outcome, failures: failures.length, err })
+    getTelemetryRuntime()?.reportError(err, {
+      module: 'shared',
+      code: 'shared.transaction_completion_callback_failed',
+      attributes: { outcome },
+    })
+  }
+}

package/src/lib/commands/types.ts

@@ -4,6 +4,7 @@ import type { ZodTypeAny } from 'zod'
 import { randomUUID } from 'crypto'
 import type { AuthContext } from '../auth/server'
 import type { OrganizationScope } from '@open-mercato/core/modules/directory/utils/organizationScope'
+import type { TransactionLifetime } from './transaction-lifetime'
 
 /**
  * Bulk-import / backfill deferral flags. When a command runs under a context that
@@ -26,6 +27,14 @@ export type BulkImportSuppression = {
   skipEvents?: boolean
   /** Advisory: handlers that fan out per-record notifications SHOULD honor this and skip them. */
   skipNotifications?: boolean
+  /**
+   * Skip a command's own full-collection derived-data rebuild (e.g. category tree
+   * `parentId`/`treePath`/`depth`/ancestor-descendant rewrite). The caller MUST run that rebuild
+   * itself exactly once after the batch, in a `finally` that covers the completed, cancelled and
+   * failed paths — otherwise every record written under this context is left with a stale
+   * derived shape.
+   */
+  skipDerivedRebuild?: boolean
 }
 
 export type CommandRuntimeContext = {
@@ -58,6 +67,27 @@ export type CommandRuntimeContext = {
    * surrounding work as a single atomic, single-locked operation.
    */
   transactionalEm?: EntityManager
+  /**
+   * Identifies the owner of an already-active {@link transactionalEm} lifetime.
+   * Atomic replay accepts an ambient EntityManager only when this is the exact
+   * token returned by `getTransactionLifetime(transactionalEm)` from the outer
+   * `withAtomicFlush` phase. The owner completes the token after its real commit
+   * or rollback, allowing replay leases and post-commit work to follow that
+   * boundary. Omit when the command bus opens and owns the transaction itself.
+   */
+  transactionLifetime?: TransactionLifetime
+  /**
+   * Optional request-level replay authorization that the command bus binds to
+   * its replay EntityManager. Atomic handlers run this guard in the same
+   * transaction as the source-log transition and domain mutation; legacy
+   * handlers run it in a dedicated read transaction before preserving their
+   * existing replay lifecycle.
+   */
+  replayTransactionGuard?: (args: {
+    operation: CommandReplayOperation
+    logEntry: CommandUndoLogEntry
+    transactionalEm: EntityManager
+  }) => Promise<void> | void
   /**
    * On-behalf-of attribution for non-human principals (Agent Identity &
    * On-Behalf-Of, Wave 4 P2). When an agent runs on behalf of a human, the
@@ -84,6 +114,22 @@ export type CommandRunAsContext = {
 
 export type CommandLogMetadata = {
   skipLog?: boolean
+  /**
+   * Per-execution replay policy. `false` records the audit entry without an undo
+   * token or command payload, so neither undo nor redo can replay sensitive input.
+   * Omitted preserves the command handler's existing replay behavior.
+   */
+  replayable?: boolean
+  /**
+   * Overrides the command input persisted in the audit entry's redo envelope.
+   * The default is the raw input, which for credential-bearing commands would put
+   * a plaintext secret at rest in `action_logs`. A handler that still wants its
+   * operation to be undoable supplies a redacted projection here instead of
+   * switching the whole entry to `replayable: false` — suppressing the undo token
+   * removes the operator's ability to revert a write that carries no secret of its
+   * own (undoing a user create only deletes a row).
+   */
+  redoInput?: unknown
   tenantId?: string | null
   organizationId?: string | null
   actorUserId?: string | null
@@ -106,6 +152,16 @@ export type CommandLogMetadata = {
 export type CommandExecuteResult<TResult> = {
   result: TResult
   logEntry: any | null
+  /**
+   * True when an atomic redo finalized its source action log in the same
+   * transaction as the domain mutation and the newly persisted log entry, and
+   * that transaction has committed. An ambient replay returns this as false
+   * while its caller-owned transaction is still active; the returned result
+   * object is updated to true by the owner's commit callback. It remains false
+   * on rollback. Callers that historically finalized redo themselves can use
+   * this additive signal to avoid a redundant post-commit write.
+   */
+  replaySourceFinalized?: boolean
 }
 
 /**
@@ -150,9 +206,35 @@ export type CommandLogBuilderArgs<TInput, TResult> = {
   }
 }
 
+export type CommandReplayOperation = 'undo' | 'redo'
+
+export type CommandReplayAuthorizationArgs<TInput> = {
+  operation: CommandReplayOperation
+  input: TInput
+  ctx: CommandRuntimeContext
+  logEntry: CommandUndoLogEntry
+}
+
 export interface CommandHandler<TInput = unknown, TResult = unknown> {
   readonly id: string
   readonly isUndoable?: boolean
+  /**
+   * Opts replay into the command bus's transaction-bound lifecycle. The source
+   * action-log transition, handler mutation, and any new replay log share one
+   * EntityManager and commit or roll back together. Handlers that enable this
+   * MUST reuse `ctx.transactionalEm` for every replay-time database operation.
+   * Omitted preserves the legacy non-atomic replay path.
+   */
+  readonly atomicReplay?: boolean
+  /**
+   * Acquires every authorization-state lock needed by an atomic replay before
+   * request-level replay authorization and feature-gated interceptors run.
+   * Implementations MUST discover their complete actor/target/destination set
+   * before taking the first lock and MUST reuse `ctx.transactionalEm`.
+   * Omitted preserves the existing lifecycle for handlers that do not need
+   * domain-specific authorization stabilization.
+   */
+  stabilizeReplay?(params: CommandReplayAuthorizationArgs<TInput>): Promise<void> | void
   /**
    * Optional Zod schema describing the command's return value. Feeds the
    * workflows context ledger so downstream activities can reason about the
@@ -164,6 +246,15 @@ export interface CommandHandler<TInput = unknown, TResult = unknown> {
   execute(input: TInput, ctx: CommandRuntimeContext): Promise<TResult> | TResult
   buildLog?(args: CommandLogBuilderArgs<TInput, TResult>): Promise<CommandLogMetadata | null | undefined> | CommandLogMetadata | null | undefined
   captureAfter?(input: TInput, result: TResult, ctx: CommandRuntimeContext): Promise<unknown> | unknown
+  /**
+   * Re-authorizes a stored command against the actor and resource state that
+   * exist at replay time. Legacy handlers are checked before claiming an undo
+   * log or beginning redo processing. Atomic handlers are checked inside their
+   * replay transaction before the guarded source transition; their mutation
+   * path can repeat the check after taking domain locks. Throwing aborts replay
+   * without committed domain side effects.
+   */
+  authorizeReplay?(params: CommandReplayAuthorizationArgs<TInput>): Promise<void> | void
   undo?(params: { input: TInput; ctx: CommandRuntimeContext; logEntry: CommandUndoLogEntry }): Promise<void> | void
   /**
    * Optional redo handler. When defined, the command bus calls this instead of

package/src/lib/commands/undo.ts

@@ -30,7 +30,85 @@ function snapshotFallback<T>(logEntry: UndoLogEntry): T | null {
   return { before: before ?? null, after: after ?? null } as T
 }
 
-export function extractUndoPayload<T>(logEntry: UndoLogEntry | null | undefined): T | null {
+export type UndoDateRevivalOptions = {
+  /** Keys revived from ISO strings to `Date` wherever they appear in the payload (any depth, arrays included). */
+  dateFields?: readonly string[]
+  /** Dot-separated paths from the payload root revived from ISO strings to `Date`; arrays on the way are walked element-wise. */
+  datePaths?: readonly string[]
+}
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value) && !(value instanceof Date)
+}
+
+function reviveDateValue(value: unknown, field: string): unknown {
+  if (typeof value !== 'string') return value
+  const date = new Date(value)
+  if (Number.isNaN(date.getTime())) {
+    throw new Error(`[internal] Invalid ${field} snapshot date: ${value}`)
+  }
+  return date
+}
+
+/**
+ * Shallow-clone a snapshot record and revive the named date fields from ISO strings
+ * back to `Date`. `null`, `undefined` and existing `Date` values are kept as-is; an
+ * unparsable string throws so a corrupt snapshot fails loudly instead of writing a bad row.
+ */
+export function reviveSnapshotDates<T extends Record<string, unknown>>(value: T, fields: readonly string[]): T {
+  const revived: Record<string, unknown> = { ...value }
+  for (const field of fields) {
+    if (field in revived) revived[field] = reviveDateValue(revived[field], field)
+  }
+  return revived as T
+}
+
+function reviveDateFieldsDeep(value: unknown, fields: ReadonlySet<string>): unknown {
+  if (Array.isArray(value)) return value.map((item) => reviveDateFieldsDeep(item, fields))
+  if (!isPlainRecord(value)) return value
+  return Object.fromEntries(
+    Object.entries(value).map(([key, entry]) => [
+      key,
+      fields.has(key) ? reviveDateValue(entry, key) : reviveDateFieldsDeep(entry, fields),
+    ]),
+  )
+}
+
+function reviveDatePath(value: unknown, segments: readonly string[]): unknown {
+  if (Array.isArray(value)) return value.map((item) => reviveDatePath(item, segments))
+  if (!isPlainRecord(value) || segments.length === 0) return value
+  const [head, ...rest] = segments
+  if (!(head in value)) return value
+  const entry = value[head]
+  return { ...value, [head]: rest.length === 0 ? reviveDateValue(entry, head) : reviveDatePath(entry, rest) }
+}
+
+function reviveUndoPayloadDates<T>(payload: T | null, options: UndoDateRevivalOptions | undefined): T | null {
+  if (payload === null || payload === undefined || !options) return payload
+  let revived: unknown = payload
+  if (options.dateFields && options.dateFields.length > 0) {
+    revived = reviveDateFieldsDeep(revived, new Set(options.dateFields))
+  }
+  for (const path of options.datePaths ?? []) {
+    const segments = path.split('.').filter((segment) => segment.length > 0)
+    if (segments.length > 0) revived = reviveDatePath(revived, segments)
+  }
+  return revived as T
+}
+
+/**
+ * Read the undo payload from a command log entry. Snapshots round-trip through `jsonb`,
+ * so `Date` values come back as ISO strings; pass `dateFields` / `datePaths` to revive
+ * them to `Date` (unparsable strings throw). Without options the raw payload is returned.
+ */
+export function extractUndoPayload<T>(
+  logEntry: UndoLogEntry | null | undefined,
+  options?: UndoDateRevivalOptions,
+): T | null {
+  return reviveUndoPayloadDates(extractRawUndoPayload<T>(logEntry), options)
+}
+
+function extractRawUndoPayload<T>(logEntry: UndoLogEntry | null | undefined): T | null {
   if (!logEntry) return null
   const rawPayload = logEntry.commandPayload ?? logEntry.payload
   if (!rawPayload || typeof rawPayload !== 'object' || Array.isArray(rawPayload)) {

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

@@ -0,0 +1,149 @@
+// Regression coverage for tenant-level (orgField: null) makeCrudRoute lists:
+// a create invalidates the tenant-level `org:null` collection tag (the record
+// carries no organization), so the cached list MUST be tagged with that same
+// tag — tagging it with the caller's organization scope left the entry
+// unflushable and served a stale list until TTL.
+
+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 { invalidateCrudCache } from '@open-mercato/shared/lib/crud/cache'
+import { registerApiInterceptors } from '@open-mercato/shared/lib/crud/interceptor-registry'
+import { z } from 'zod'
+
+const organizationId = 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa'
+const tenantId = '123e4567-e89b-12d3-a456-426614174000'
+
+let rows: Array<{ id: string; name: string }> = []
+
+const queryEngine = {
+  query: jest.fn(async () => ({ items: rows.map((row) => ({ ...row, tenant_id: tenantId })), total: rows.length })),
+}
+
+const store = new Map<string, { value: unknown; tags: string[] }>()
+const cache = {
+  get: jest.fn(async (key: string) => store.get(key)?.value ?? null),
+  set: jest.fn(async (key: string, value: unknown, options?: { tags?: string[] }) => {
+    store.set(key, { value, tags: options?.tags ?? [] })
+  }),
+  delete: jest.fn(async (key: string) => { store.delete(key) }),
+  deleteByTags: jest.fn(async (tags: string[]) => {
+    let removed = 0
+    for (const [key, entry] of Array.from(store.entries())) {
+      if (entry.tags.some((tag) => tags.includes(tag))) {
+        store.delete(key)
+        removed += 1
+      }
+    }
+    return removed
+  }),
+}
+
+const container = {
+  resolve: (name: string) => ({
+    em: {},
+    queryEngine,
+    cache,
+    accessLogService: { log: jest.fn(async () => {}) },
+  } as Record<string, unknown>)[name],
+}
+
+jest.mock('@open-mercato/shared/lib/di/container', () => ({
+  createRequestContainer: async () => container,
+}))
+
+jest.mock('@open-mercato/shared/lib/auth/server', () => {
+  const buildAuth = () => ({
+    sub: 'user-a',
+    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 TenantGroup {}
+
+const querySchema = z.object({
+  page: z.coerce.number().default(1),
+  pageSize: z.coerce.number().default(50),
+})
+
+const route = makeCrudRoute({
+  metadata: { GET: { requireAuth: true } },
+  orm: { entity: TenantGroup, idField: 'id', orgField: null, tenantField: 'tenantId', softDeleteField: 'deletedAt' },
+  events: { module: 'example', entity: 'tenant_group' },
+  indexer: { entityType: 'example:tenant_group' },
+  list: {
+    schema: querySchema,
+    entityId: 'example:tenant_group',
+    fields: ['id', 'name'],
+    transformItem: (item: { id: string; name: string }) => ({ id: item.id, name: item.name }),
+  },
+})
+
+const url = 'http://x/api/example/tenant-groups?page=1&pageSize=10'
+
+describe('CRUD Factory — tenant-level (orgField: null) list cache invalidation', () => {
+  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()
+    rows = []
+    registerApiInterceptors([])
+  })
+
+  it('tags the cached list with the tenant-level collection tag, not the caller org', async () => {
+    await route.GET(new Request(url))
+    const [entry] = Array.from(store.values())
+    expect(entry.tags).toContain(`crud:example.tenant.group:tenant:${tenantId}:org:null:collection`)
+    expect(entry.tags).not.toContain(`crud:example.tenant.group:tenant:${tenantId}:org:${organizationId}:collection`)
+  })
+
+  it('serves the new row after a create invalidates the tenant-level collection', async () => {
+    const before = await route.GET(new Request(url))
+    expect(before.headers.get('x-om-cache')).toBe('miss')
+    expect((await before.json()).items).toEqual([])
+
+    rows = [{ id: 'group-1', name: 'Wholesale' }]
+    await invalidateCrudCache(
+      container as never,
+      'example.tenant.group',
+      { id: 'group-1', organizationId: null, tenantId },
+      tenantId,
+      'created',
+    )
+
+    const after = await route.GET(new Request(url))
+    expect(after.headers.get('x-om-cache')).toBe('miss')
+    expect((await after.json()).items).toEqual([{ id: 'group-1', name: 'Wholesale' }])
+  })
+})

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

@@ -19,6 +19,12 @@ const defaultTenantId = '123e4567-e89b-12d3-a456-426614174000'
 
 let mockAuthSub = 'user-a'
 let mockAuthKeyId: string | null = null
+let mockOrganizationScope = {
+  selectedId: defaultOrganizationId,
+  filterIds: [defaultOrganizationId] as string[] | null,
+  allowedIds: [defaultOrganizationId] as string[] | null,
+  tenantId: defaultTenantId,
+}
 
 const em = {}
 
@@ -70,12 +76,7 @@ jest.mock('@open-mercato/shared/lib/auth/server', () => {
 })
 
 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',
-  })),
+  resolveOrganizationScopeForRequest: jest.fn(async () => mockOrganizationScope),
 }))
 
 jest.mock('@open-mercato/core/modules/entities/lib/helpers', () => ({
@@ -105,6 +106,20 @@ const route = makeCrudRoute({
   },
 })
 
+const scopeIdentityRoute = makeCrudRoute({
+  metadata: { GET: { requireAuth: true } },
+  orm: { entity: Todo, idField: 'id', orgField: null, tenantField: null, softDeleteField: null },
+  indexer: { entityType: 'example.cache_identity' },
+  list: {
+    schema: querySchema,
+    entityId: 'example.cache_identity',
+    fields: ['id', 'title'],
+    sortFieldMap: { id: 'id', title: 'title' },
+    buildFilters: () => ({} as any),
+    transformItem: (item: any) => ({ id: item.id, title: item.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', () => {
@@ -124,6 +139,12 @@ describe('CRUD Factory — list cache is partitioned per caller identity', () =>
     store.clear()
     mockAuthSub = 'user-a'
     mockAuthKeyId = null
+    mockOrganizationScope = {
+      selectedId: defaultOrganizationId,
+      filterIds: [defaultOrganizationId],
+      allowedIds: [defaultOrganizationId],
+      tenantId: defaultTenantId,
+    }
     registerApiInterceptors([])
   })
 
@@ -168,4 +189,25 @@ describe('CRUD Factory — list cache is partitioned per caller identity', () =>
     const apiKeyKey = Array.from(store.keys())[0] as string
     expect(apiKeyKey).toContain('user:api-key-9')
   })
+
+  it('encodes explicit empty and finite scopes as different cache keys', async () => {
+    await scopeIdentityRoute.GET(new Request(url))
+    const finiteKey = Array.from(store.keys())[0] as string
+
+    mockOrganizationScope = {
+      selectedId: defaultOrganizationId,
+      filterIds: [],
+      allowedIds: [defaultOrganizationId],
+      tenantId: defaultTenantId,
+    }
+    const emptyResponse = await scopeIdentityRoute.GET(new Request(url))
+    const keys = Array.from(store.keys())
+
+    expect(emptyResponse.headers.get('x-om-cache')).toBe('miss')
+    expect(keys).toHaveLength(2)
+    expect(finiteKey).toContain(`scope:${defaultOrganizationId}`)
+    expect(keys[1]).toContain('scope:empty')
+    expect(keys[1]).not.toBe(finiteKey)
+    expect(queryEngine.query).toHaveBeenCalledTimes(2)
+  })
 })