@open-mercato/shared 0.6.7 → 0.6.8-canary.320.1.bf889f49e4

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

@@ -15,6 +15,7 @@ import type {
 import { getEnrichersForEntity } from './enricher-registry'
 import { logEnricherTiming } from '../umes/enricher-timing'
 import { createLogger } from '../logger'
+import { authorizeFeatures } from '../../security/featurePolicy'
 
 const logger = createLogger('shared').child({ component: 'umes' })
 
@@ -35,17 +36,7 @@ function hasRequiredFeatures(
 ): boolean {
   if (!enricher.features || enricher.features.length === 0) return true
   if (!userFeatures) return false
-  const hasFeature = (required: string): boolean => {
-    for (const granted of userFeatures) {
-      if (granted === '*' || granted === required) return true
-      if (granted.endsWith('.*')) {
-        const prefix = granted.slice(0, -1)
-        if (required.startsWith(prefix)) return true
-      }
-    }
-    return false
-  }
-  return enricher.features.every((feature) => hasFeature(feature))
+  return authorizeFeatures(enricher.features, { grantedFeatures: userFeatures })
 }
 
 function filterByACLAndTenant(

package/src/lib/crud/factory.ts

@@ -8,6 +8,7 @@ import { SortDir } from '@open-mercato/shared/lib/query/types'
 import type { DataEngine } from '@open-mercato/shared/lib/data/engine'
 import { resolveOrganizationScopeForRequest, type OrganizationScope } from '@open-mercato/core/modules/directory/utils/organizationScope'
 import { serializeOperationMetadata } from '@open-mercato/shared/lib/commands/operationMetadata'
+import { getCommandInterceptorHttpRejection } from '@open-mercato/shared/lib/commands/errors'
 import { parseBooleanToken } from '@open-mercato/shared/lib/boolean'
 import {
   runMutationGuards,
@@ -57,6 +58,7 @@ import {
   isCrudCacheEnabled,
   normalizeIdentifierValue,
   normalizeTagSegment,
+  pickFirstIdentifier,
   resolveCrudCache,
 } from './cache'
 import { deriveCrudSegmentTag } from './cache-stats'
@@ -72,6 +74,7 @@ import { parseExtensionHeaders } from '../umes/extension-headers'
 import { createGenericOptimisticLockReader } from './optimistic-lock'
 import { registerOptimisticLockReaderIfAbsent } from './optimistic-lock-store'
 import { createLogger } from '../logger'
+import { isTransientDbError } from '../db/pg-errors'
 
 type RbacServiceLike = {
   getGrantedFeatures: (userId: string, opts: { tenantId: string | null; organizationId: string | null }) => Promise<string[]>
@@ -79,10 +82,13 @@ type RbacServiceLike = {
 
 const logger = createLogger('shared').child({ component: 'crud' })
 
-function resolveSortParams(queryParams: Record<string, unknown>) {
-  const rawSortField = queryParams.sortField ?? queryParams.sort ?? 'id'
-  const rawSortDir = queryParams.sortDir ?? queryParams.order ?? 'asc'
-  const sortField = typeof rawSortField === 'string' && rawSortField.trim().length > 0 ? rawSortField.trim() : 'id'
+function resolveSortParams(queryParams: Record<string, unknown>, defaultSort?: CrudDefaultSort) {
+  const rawSortField = queryParams.sortField ?? queryParams.sort
+  const requestedSortField =
+    typeof rawSortField === 'string' && rawSortField.trim().length > 0 ? rawSortField.trim() : null
+  const sortField = requestedSortField ?? defaultSort?.field ?? 'id'
+  const rawSortDir =
+    queryParams.sortDir ?? queryParams.order ?? (requestedSortField ? 'asc' : defaultSort?.dir ?? 'asc')
   const normalizedDir = typeof rawSortDir === 'string' ? rawSortDir.trim().toLowerCase() : 'asc'
   const sortDir = normalizedDir === 'desc' ? SortDir.Desc : SortDir.Asc
   return { sortField, sortDir }
@@ -190,6 +196,8 @@ export type CrudListCustomFieldDecorator = {
   stripPrefixedKeys?: boolean
 }
 
+export type CrudDefaultSort = { field: string; dir?: 'asc' | 'desc' }
+
 export type ListConfig<TList> = {
   schema: z.ZodType<TList>
   // Optional: use the QueryEngine when entityId + fields are provided.
@@ -200,12 +208,41 @@ export type ListConfig<TList> = {
   entityId?: any
   fields?: any[] | ((query: TList, ctx: CrudCtx) => any[])
   sortFieldMap?: Record<string, any>
+  /**
+   * Sort used when the request carries no `sortField` / `sort` param. The field is
+   * resolved through `sortFieldMap`, so a name the map defines is translated to its
+   * column and an unmapped name is used as the column directly. `dir` only applies
+   * together with the default field — an explicit `sortField` without `sortDir`
+   * still defaults to ascending. Defaults to `{ field: 'id', dir: 'asc' }`, which is
+   * only a meaningful order for sequential ids, never for random UUIDs.
+   *
+   * Applies to the Query Engine list path only (the route must set both `entityId`
+   * and `fields`). The plain-ORM fallback list issues an unordered `find` and
+   * already ignores `sortField` today, so it ignores this too.
+   *
+   * The list schema must keep `sortField` optional for this to take effect — a zod
+   * `.default()` on `sortField` reaches the sort resolver as an explicit request and
+   * pins the order itself.
+   */
+  defaultSort?: CrudDefaultSort
+  /**
+   * Appended as a secondary ascending sort whenever it differs from the resolved
+   * primary sort, so rows sharing a primary value keep a stable order across pages
+   * and re-fetches instead of falling back to the database's arbitrary row order.
+   * Applies to explicit sorts too, and is resolved through `sortFieldMap` and gated
+   * on the Query Engine path exactly like `defaultSort`.
+   */
+  tiebreakSortField?: string
   buildFilters?: (query: TList, ctx: CrudCtx) => Where<any> | Promise<Where<any>>
   transformItem?: (item: any) => any
   allowCsv?: boolean
+  // The function forms mirror `fields` above: a route whose export columns depend
+  // on per-request state (for example custom-field definitions discovered in
+  // `beforeList`) MUST resolve them from `ctx` rather than from module-level
+  // mutable state, which would bleed one tenant's columns into another's export.
   csv?: {
-    headers: string[]
-    row: (item: any) => (string | number | boolean | null | undefined)[]
+    headers: string[] | ((query: TList, ctx: CrudCtx) => string[])
+    row: (item: any, ctx: CrudCtx) => (string | number | boolean | null | undefined)[]
     filename?: string
   }
   export?: CrudExportOptions
@@ -250,6 +287,7 @@ const DEFAULT_EXPORT_FORMATS: CrudExportFormat[] = ['csv', 'json', 'xml', 'markd
 const DEFAULT_EXPORT_BATCH_SIZE = 1000
 const MIN_EXPORT_BATCH_SIZE = 100
 const MAX_EXPORT_BATCH_SIZE = 10000
+const EXPORT_MAX_PAGES = 1000
 
 type ColumnResolver = {
   field: string
@@ -313,14 +351,20 @@ function buildExportFromColumns(items: any[], columnsConfig: CrudExportColumnCon
   }
 }
 
-function buildExportFromCsv(items: any[], csv: NonNullable<ListConfig<any>['csv']>): PreparedExport {
+function buildExportFromCsv(
+  items: any[],
+  csv: NonNullable<ListConfig<any>['csv']>,
+  query: unknown,
+  ctx: CrudCtx,
+): PreparedExport {
   const used = new Set<string>()
-  const columns = csv.headers.map((header, idx) => ({
+  const resolvedHeaders = typeof csv.headers === 'function' ? csv.headers(query as any, ctx) : csv.headers
+  const columns = resolvedHeaders.map((header, idx) => ({
     field: sanitizeFieldName(header || `column_${idx + 1}`, used, idx),
     header: header || `Column ${idx + 1}`,
   }))
   const rows = items.map((item) => {
-    const values = csv.row(item) || []
+    const values = csv.row(item, ctx) || []
     const row: Record<string, unknown> = {}
     columns.forEach((column, idx) => {
       row[column.field] = values[idx]
@@ -343,12 +387,12 @@ function buildDefaultExport(items: any[]): PreparedExport {
   }
 }
 
-function prepareExportData(items: any[], list: ListConfig<any>): PreparedExport {
+function prepareExportData(items: any[], list: ListConfig<any>, query: unknown, ctx: CrudCtx): PreparedExport {
   if (list.export?.columns && list.export.columns.length > 0) {
     return buildExportFromColumns(items, list.export.columns)
   }
   if (list.csv) {
-    return buildExportFromCsv(items, list.csv)
+    return buildExportFromCsv(items, list.csv, query, ctx)
   }
   const prepared = buildDefaultExport(items)
   return {
@@ -553,7 +597,26 @@ function attachOperationHeader(res: Response, logEntry: any) {
 function handleError(err: unknown): Response {
   if (err instanceof Response) return err
   if (isCrudHttpError(err)) return json(err.body, { status: err.status })
+  // A command interceptor that blocked with an explicit status is a deliberate business
+  // rejection, not a server fault — surface its status and message instead of a generic 500.
+  // Without a usable status the error falls through to the historical handling below (issue #5045).
+  const interceptorRejection = getCommandInterceptorHttpRejection(err)
+  if (interceptorRejection) {
+    return json(interceptorRejection.body, { status: interceptorRejection.status })
+  }
   if (err instanceof z.ZodError) return json({ error: 'Invalid input', details: err.issues }, { status: 400 })
+  if (isTransientDbError(err)) {
+    // Transient DB unavailability (pool exhausted, `max_connections` reached, DB
+    // restarting) is retryable — surface a 503 with a Retry-After hint instead of
+    // a generic 500 so clients back off and retry once the DB recovers.
+    logger.warn('Transient DB failure during CRUD handler', {
+      message: err instanceof Error ? err.message : undefined,
+    })
+    return json(
+      { error: 'Service temporarily unavailable' },
+      { status: 503, headers: { 'Retry-After': '2' } },
+    )
+  }
 
   const message = err instanceof Error ? err.message : undefined
   const stack = err instanceof Error ? err.stack : undefined
@@ -915,6 +978,12 @@ function buildCrudCacheKey(
     `tenant:${normalizeTagSegment(ctx.auth?.tenantId ?? null)}`,
     `selectedOrg:${normalizeTagSegment(ctx.selectedOrganizationId ?? null)}`,
     `scope:${scopeSegment}`,
+    // List payloads can vary per caller identity beyond tenant/org scope:
+    // buildFilters may narrow by ctx.auth (e.g. ?mine=true), before-interceptor
+    // query rewrites are feature-gated per user, and afterList/after-interceptor
+    // output is embedded in the stored payload — so entries MUST be partitioned
+    // per actor (API key or user), never shared across identities.
+    `user:${normalizeTagSegment((ctx.auth?.keyId ?? ctx.auth?.sub) ?? null)}`,
     `query:${serializeSearchParams(url.searchParams)}`,
   ]
   // The cached list payload already embeds enricher output (enrichment runs before
@@ -1655,10 +1724,21 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
         profiler.mark('query_engine_prepare')
         const qe = (ctx.container.resolve('queryEngine') as QueryEngine)
         profiler.mark('query_engine_resolved')
-        const { sortField: sortFieldRaw, sortDir: sortDirRaw } = resolveSortParams(queryParams as Record<string, unknown>)
-        const mappedSortField = (opts.list.sortFieldMap && opts.list.sortFieldMap[sortFieldRaw]) || sortFieldRaw
-        const sortField = typeof mappedSortField === 'string' ? normalizeSortFieldSelector(mappedSortField) : mappedSortField
+        const sortFieldMap = opts.list.sortFieldMap
+        const resolveSortSelector = (field: string) => {
+          const mapped = (sortFieldMap && sortFieldMap[field]) || field
+          return typeof mapped === 'string' ? normalizeSortFieldSelector(mapped) : mapped
+        }
+        const { sortField: sortFieldRaw, sortDir: sortDirRaw } = resolveSortParams(
+          queryParams as Record<string, unknown>,
+          opts.list.defaultSort,
+        )
+        const sortField = resolveSortSelector(sortFieldRaw)
         const sort: Sort[] = [{ field: sortField as any, dir: sortDirRaw } as any]
+        if (opts.list.tiebreakSortField) {
+          const tiebreakField = resolveSortSelector(opts.list.tiebreakSortField)
+          if (tiebreakField !== sortField) sort.push({ field: tiebreakField as any, dir: SortDir.Asc } as any)
+        }
         const page: Page = exportRequested
           ? { page: 1, pageSize: exportPageSize }
           : { page: requestedPage, pageSize: requestedPageSize }
@@ -1786,13 +1866,17 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
           const initialExportItems = exportFullRequested
             ? rawItems.map(normalizeFullRecordForExport)
             : transformedItems
-          let exportItems = [...initialExportItems]
-          if (total > exportItems.length) {
-            const exportPageSizeNumber = typeof page.pageSize === 'number' ? page.pageSize : exportPageSize
+          const exportItems = [...initialExportItems]
+          const exportPageSizeNumber = typeof page.pageSize === 'number' ? page.pageSize : exportPageSize
+          // Short-page termination: `total` is a display value, not a loop bound — it can
+          // under-report (capped counts) or drift while rows are inserted/deleted mid-export.
+          // Keep fetching while pages come back full; fail closed at the page ceiling rather
+          // than serializing a partial export.
+          if (rawItems.length >= exportPageSizeNumber) {
             const queryBase: any = { ...queryOpts }
             delete queryBase.page
             let nextPage = 2
-            while (exportItems.length < total) {
+            for (;;) {
               profiler.mark('export_next_page_request', { page: nextPage })
               const nextRes = await qe.query(opts.list.entityId as any, {
                 ...queryBase,
@@ -1807,13 +1891,16 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
                 ? nextItemsRaw.map(normalizeFullRecordForExport)
                 : nextTransformed
               exportItems.push(...nextExportItems)
-              if (nextExportItems.length < exportPageSizeNumber) break
+              if (nextItemsRaw.length < exportPageSizeNumber) break
+              if (nextPage >= EXPORT_MAX_PAGES) {
+                throw new Error(`[internal] export exceeded ${EXPORT_MAX_PAGES} pages; refusing to return a partial export`)
+              }
               nextPage += 1
             }
           }
           const prepared = exportFullRequested
             ? { columns: ensureColumns(exportItems), rows: exportItems }
-            : prepareExportData(exportItems, opts.list)
+            : prepareExportData(exportItems, opts.list, validated as any, ctx)
           const fallbackBase = `${opts.events?.entity || resourceKind || 'list'}${exportFullRequested ? '_full' : ''}`
           const filename = finalizeExportFilename(opts.list, requestedExport, fallbackBase)
           const serialized = serializeExport(prepared, requestedExport)
@@ -2015,7 +2102,7 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
         const exportItems = exportFullRequested ? list.map(normalizeFullRecordForExport) : list
         const prepared = exportFullRequested
           ? { columns: ensureColumns(exportItems), rows: exportItems }
-          : prepareExportData(exportItems, opts.list)
+          : prepareExportData(exportItems, opts.list, validated as any, ctx)
         const fallbackBase = `${opts.events?.entity || resourceKind || 'list'}${exportFullRequested ? '_full' : ''}`
         const filename = finalizeExportFilename(opts.list, requestedExport, fallbackBase)
         const serialized = serializeExport(prepared, requestedExport)
@@ -2140,6 +2227,31 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
           }
         }
 
+        // Mutation guard registry — command path (mirrors the direct create branch)
+        const createCmdUserFeatures = await resolveUserFeatures(ctx)
+        const { allGuards: createCmdAllGuards } = collectAndRunGuards(ctx.container)
+        let createCmdGuardAfterCallbacks: Array<{ guard: MutationGuard; metadata: Record<string, unknown> | null }> = []
+        if (createCmdAllGuards.length && ctx.auth.tenantId) {
+          const guardResult = await runMutationGuards(createCmdAllGuards, {
+            tenantId: ctx.auth.tenantId,
+            organizationId: ctx.selectedOrganizationId ?? ctx.auth.orgId ?? null,
+            userId: ctx.auth.sub,
+            resourceKind,
+            resourceId: null,
+            operation: 'create',
+            requestMethod: request.method,
+            requestHeaders: request.headers,
+            mutationPayload: input && typeof input === 'object' ? (input as Record<string, unknown>) : null,
+          }, { userFeatures: createCmdUserFeatures ?? [] })
+          if (!guardResult.ok) {
+            return json(guardResult.errorBody ?? { error: 'Operation blocked by guard' }, { status: guardResult.errorStatus ?? 422 })
+          }
+          if (guardResult.modifiedPayload && typeof input === 'object' && input) {
+            input = { ...input as Record<string, unknown>, ...guardResult.modifiedPayload }
+          }
+          createCmdGuardAfterCallbacks = guardResult.afterSuccessCallbacks
+        }
+
         const baseMetadata: CommandLogMetadata = {
           tenantId: ctx.auth?.tenantId ?? null,
           organizationId: ctx.selectedOrganizationId ?? ctx.auth.orgId ?? null,
@@ -2182,6 +2294,22 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
         const status = action.status ?? 201
         const response = json(resolvedPayload, { status })
         attachOperationHeader(response, logEntry)
+        const commandResultId = pickFirstIdentifier(
+          (result as Record<string, unknown> | null | undefined)?.id,
+          (resolvedPayload as Record<string, unknown> | null | undefined)?.id,
+        )
+        if (createCmdGuardAfterCallbacks.length && ctx.auth.tenantId && commandResultId) {
+          await runGuardAfterSuccessCallbacks(createCmdGuardAfterCallbacks, {
+            tenantId: ctx.auth.tenantId,
+            organizationId: ctx.selectedOrganizationId ?? ctx.auth.orgId ?? null,
+            userId: ctx.auth.sub,
+            resourceKind,
+            resourceId: commandResultId,
+            operation: 'create',
+            requestMethod: request.method,
+            requestHeaders: request.headers,
+          })
+        }
         // Note: side effects (events + indexing) are already flushed by CommandBus.execute()
         // via flushCrudSideEffects(). Calling markCommandResultForIndexing here would cause
         // duplicate event emissions.
@@ -2285,6 +2413,7 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
               organizationId: targetOrgId,
               tenantId: writeTenantId,
               values,
+              notify: false,
             })
           }
         }
@@ -2422,6 +2551,10 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
         const updateUserFeatures = await resolveUserFeatures(ctx)
         const { allGuards: updateAllGuards } = collectAndRunGuards(ctx.container)
         let cmdUpdateGuardAfterCallbacks: Array<{ guard: MutationGuard; metadata: Record<string, unknown> | null }> = []
+        // Commands whose mapInput wraps the payload (e.g. `{ body }`) intentionally
+        // null candidateId and OPT OUT of row-level guards, leaving the command-level
+        // optimistic-lock check as the sole guard — a documented contract, see
+        // apps/docs/docs/framework/data-integrity/concurrency-locking.mdx.
         if (updateAllGuards.length && ctx.auth.tenantId && candidateId) {
           const guardResult = await runMutationGuards(updateAllGuards, {
             tenantId: ctx.auth.tenantId,
@@ -2618,6 +2751,7 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
               organizationId: targetOrgId,
               tenantId: writeTenantId,
               values,
+              notify: false,
             })
           }
         }
@@ -2721,6 +2855,7 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
           request,
           method: 'DELETE',
           body: interceptorInput,
+          query: raw.query,
         })
         if (beforeInterceptors.errorResponse) return beforeInterceptors.errorResponse
         interceptorRequestPayload = beforeInterceptors.requestPayload
@@ -2845,7 +2980,7 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
         request,
         method: 'DELETE',
         body: idFrom === 'query' ? undefined : ({ id } as Record<string, unknown>),
-        query: idFrom === 'query' ? ({ id } as Record<string, unknown>) : undefined,
+        query: idFrom === 'query' ? Object.fromEntries(url.searchParams.entries()) : undefined,
       })
       if (beforeInterceptors.errorResponse) return beforeInterceptors.errorResponse
       interceptorRequestPayload = beforeInterceptors.requestPayload

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

@@ -6,7 +6,7 @@ import type {
   InterceptorBeforeResult,
 } from './api-interceptor'
 import { getApiInterceptorsForRoute } from './interceptor-registry'
-import { hasAllFeatures } from '../../security/features'
+import { authorizeFeatures } from '../../security/featurePolicy'
 import { logInterceptorActivity } from '../umes/interceptor-activity'
 
 const DEFAULT_TIMEOUT_MS = 5000
@@ -39,7 +39,7 @@ function sanitizeObject(input?: Record<string, unknown>): Record<string, unknown
 }
 
 function hasRequiredFeatures(features: string[] | undefined, userFeatures: string[] | undefined): boolean {
-  return hasAllFeatures(userFeatures, features)
+  return authorizeFeatures(features ?? [], { grantedFeatures: userFeatures ?? [] })
 }
 
 function timeoutPromise(ms: number, interceptorId: string): Promise<never> {

package/src/lib/crud/mutation-guard-registry.ts

@@ -1,5 +1,5 @@
 import type { AwilixContainer } from 'awilix'
-import { hasAllFeatures } from '../../security/features'
+import { authorizeFeatures } from '../../security/featurePolicy'
 import { resolveCrudMutationGuardService } from './mutation-guard-service'
 
 // ---------------------------------------------------------------------------
@@ -101,7 +101,7 @@ export async function runMutationGuards(
   const matching = guards
     .filter((g) => matchesEntity(g.targetEntity, input.resourceKind))
     .filter((g) => g.operations.includes(input.operation))
-    .filter((g) => hasAllFeatures(context.userFeatures, g.features))
+    .filter((g) => authorizeFeatures(g.features ?? [], { grantedFeatures: context.userFeatures }))
     .sort((a, b) => (a.priority ?? 50) - (b.priority ?? 50))
 
   let payload = input.mutationPayload

package/src/lib/crud/types.ts

@@ -1,5 +1,8 @@
 export type CrudEventAction = 'created' | 'updated' | 'deleted'
 
+/** Internal payload marker: the data engine owns this CRUD event's query-index decision. */
+export const CRUD_QUERY_INDEX_MANAGED_PAYLOAD_KEY = '__omQueryIndexManaged' as const
+
 export type CrudEntityIdentifiers = {
   id: string
   organizationId: string | null

package/src/lib/data/__tests__/consistency.test.ts

@@ -0,0 +1,38 @@
+import {
+  __resetAlwaysConsistentCacheForTests,
+  isReadProjectionAlwaysConsistent,
+  parseAlwaysConsistentEnv,
+} from '../consistency'
+
+describe('read projection consistency flag', () => {
+  const originalEnv = process.env.OM_CACHE_SAFETY_ALWAYS_CONSISTENT
+
+  afterEach(() => {
+    if (originalEnv === undefined) {
+      delete process.env.OM_CACHE_SAFETY_ALWAYS_CONSISTENT
+    } else {
+      process.env.OM_CACHE_SAFETY_ALWAYS_CONSISTENT = originalEnv
+    }
+    __resetAlwaysConsistentCacheForTests()
+  })
+
+  it.each([undefined, null, '', ' ', 'off', 'false', '0', 'no', 'disabled', 'none', 'unexpected'])(
+    'parses %p as OFF',
+    (raw) => {
+      expect(parseAlwaysConsistentEnv(raw)).toBe(false)
+    },
+  )
+
+  it.each(['on', 'true', '1', 'yes', 'enabled'])('parses %p as ON', (raw) => {
+    expect(parseAlwaysConsistentEnv(raw)).toBe(true)
+  })
+
+  it('memoizes the env value until reset for tests', () => {
+    process.env.OM_CACHE_SAFETY_ALWAYS_CONSISTENT = 'on'
+    expect(isReadProjectionAlwaysConsistent()).toBe(true)
+    process.env.OM_CACHE_SAFETY_ALWAYS_CONSISTENT = 'off'
+    expect(isReadProjectionAlwaysConsistent()).toBe(true)
+    __resetAlwaysConsistentCacheForTests()
+    expect(isReadProjectionAlwaysConsistent()).toBe(false)
+  })
+})

package/src/lib/data/__tests__/engine.bulk-suppress.test.ts

@@ -1,7 +1,11 @@
 import type { AwilixContainer } from 'awilix'
 import type { EntityManager } from '@mikro-orm/postgresql'
 import { DefaultDataEngine } from '../engine'
-import type { CrudEventsConfig, CrudIndexerConfig } from '../../crud/types'
+import {
+  CRUD_QUERY_INDEX_MANAGED_PAYLOAD_KEY,
+  type CrudEventsConfig,
+  type CrudIndexerConfig,
+} from '../../crud/types'
 
 // The bulk-import deferral (`suppress`) must gate the two per-record side effects `emitOrmEntityEvent`
 // fans out — the `<module>.<entity>.<action>` domain event and the inline `query_index.upsert_one`
@@ -25,6 +29,15 @@ function buildEngine() {
   return { engine, emitEvent, emittedNames }
 }
 
+function expectManagedDomainPayload(emitEvent: jest.Mock, eventName: string): void {
+  const call = emitEvent.mock.calls.find(([name]) => name === eventName)
+  expect(call).toBeDefined()
+  const payload = call?.[1] as Record<string, unknown>
+  expect(payload[CRUD_QUERY_INDEX_MANAGED_PAYLOAD_KEY]).toBe(true)
+  expect(Object.keys(payload)).not.toContain(CRUD_QUERY_INDEX_MANAGED_PAYLOAD_KEY)
+  expect(JSON.stringify(payload)).not.toContain(CRUD_QUERY_INDEX_MANAGED_PAYLOAD_KEY)
+}
+
 describe('DefaultDataEngine bulk-import suppression', () => {
   // The test events are intentionally not registered in the event registry; silence the
   // one-time "undeclared event" warning so it doesn't clutter the suite output.
@@ -33,9 +46,10 @@ describe('DefaultDataEngine bulk-import suppression', () => {
   afterAll(() => { warnSpy.mockRestore() })
 
   it('emits both the domain event and the reindex when unsuppressed', async () => {
-    const { engine, emittedNames } = buildEngine()
+    const { engine, emitEvent, emittedNames } = buildEngine()
     await engine.emitOrmEntityEvent({ action: 'created', entity: {}, events: EVENTS, indexer: INDEXER, identifiers: IDENTIFIERS })
     expect(emittedNames()).toEqual(expect.arrayContaining(['sales.order.created', 'query_index.upsert_one']))
+    expectManagedDomainPayload(emitEvent, 'sales.order.created')
   })
 
   it('skips the domain event but keeps the reindex with skipEvents', async () => {
@@ -47,11 +61,12 @@ describe('DefaultDataEngine bulk-import suppression', () => {
   })
 
   it('skips the reindex but keeps the domain event with skipReindex', async () => {
-    const { engine, emittedNames } = buildEngine()
+    const { engine, emitEvent, emittedNames } = buildEngine()
     await engine.emitOrmEntityEvent({ action: 'created', entity: {}, events: EVENTS, indexer: INDEXER, identifiers: IDENTIFIERS, suppress: { skipReindex: true } })
     const names = emittedNames()
     expect(names).toContain('sales.order.created')
     expect(names).not.toContain('query_index.upsert_one')
+    expectManagedDomainPayload(emitEvent, 'sales.order.created')
   })
 
   it('emits nothing when both are suppressed', async () => {

package/src/lib/data/consistency.ts

@@ -0,0 +1,17 @@
+import { parseBooleanWithDefault } from '../boolean'
+
+let alwaysConsistentFlag: boolean | null = null
+
+export function parseAlwaysConsistentEnv(raw: string | undefined | null): boolean {
+  return parseBooleanWithDefault(raw, false)
+}
+
+export function isReadProjectionAlwaysConsistent(): boolean {
+  if (alwaysConsistentFlag !== null) return alwaysConsistentFlag
+  alwaysConsistentFlag = parseAlwaysConsistentEnv(process.env.OM_CACHE_SAFETY_ALWAYS_CONSISTENT)
+  return alwaysConsistentFlag
+}
+
+export function __resetAlwaysConsistentCacheForTests(): void {
+  alwaysConsistentFlag = null
+}