@open-mercato/shared 0.6.4-develop.4217.1.c9aa050183 → 0.6.4-develop.4236.1.9fa6806b34

package/src/lib/crud/custom-fields.ts

@@ -6,6 +6,17 @@ import type { TenantDataEncryptionService } from '../encryption/tenantDataEncryp
 import { decryptCustomFieldValue, resolveTenantEncryptionService } from '../encryption/customFieldValues'
 import { parseBooleanToken } from '../boolean'
 import { extractCustomFieldEntries } from './custom-fields-client'
+import {
+  buildCustomFieldDefinitionIndexFromRows,
+  normalizeDefinitionKey,
+  normalizeFieldsetFilter,
+  selectDefinitionForRecord,
+  type CustomFieldDefinitionIndex,
+  type CustomFieldDefinitionRow,
+  type CustomFieldDefinitionSummary,
+} from './custom-field-definition-index'
+
+export type { CustomFieldDefinitionSummary, CustomFieldDefinitionIndex } from './custom-field-definition-index'
 
 export type CustomFieldSelectors = {
   keys: string[]
@@ -18,20 +29,6 @@ export type SplitCustomFieldPayload = {
   custom: Record<string, unknown>
 }
 
-export type CustomFieldDefinitionSummary = {
-  key: string
-  label: string | null
-  kind: string | null
-  multi: boolean
-  dictionaryId?: string | null
-  organizationId?: string | null
-  tenantId?: string | null
-  priority: number
-  updatedAt: number
-}
-
-export type CustomFieldDefinitionIndex = Map<string, CustomFieldDefinitionSummary[]>
-
 export type CustomFieldDisplayEntry = {
   key: string
   label: string | null
@@ -93,22 +90,6 @@ export function extractAllCustomFieldEntries(item: Record<string, unknown>): Rec
   return extractCustomFieldEntries(item)
 }
 
-function normalizeFieldsetFilter(input?: string | string[] | null): Set<string | null> | null {
-  if (input == null) return null
-  const values = Array.isArray(input) ? input : [input]
-  const normalized = new Set<string | null>()
-  for (const raw of values) {
-    if (raw == null) continue
-    const trimmed = String(raw).trim()
-    if (!trimmed) {
-      normalized.add(null)
-    } else {
-      normalized.add(trimmed)
-    }
-  }
-  return normalized.size ? normalized : null
-}
-
 export async function buildCustomFieldFiltersFromQuery(opts: {
   entityId?: EntityId
   entityIds?: EntityId[]
@@ -250,93 +231,6 @@ export function extractCustomFieldValuesFromPayload(raw: Record<string, unknown>
   return splitCustomFieldPayload(raw).custom
 }
 
-function normalizeDefinitionKey(key: unknown): string {
-  if (typeof key !== 'string') return ''
-  const trimmed = key.trim()
-  return trimmed.length ? trimmed.toLowerCase() : ''
-}
-
-function normalizeDefinitionConfig(raw: unknown): Record<string, any> {
-  if (!raw) return {}
-  if (typeof raw === 'string') {
-    try {
-      const parsed = JSON.parse(raw)
-      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
-        return { ...(parsed as Record<string, any>) }
-      }
-      return {}
-    } catch {
-      return {}
-    }
-  }
-  if (typeof raw === 'object' && !Array.isArray(raw)) {
-    return { ...(raw as Record<string, any>) }
-  }
-  return {}
-}
-
-function summarizeDefinition(def: CustomFieldDef): CustomFieldDefinitionSummary | null {
-  const normalizedKey = normalizeDefinitionKey(def.key)
-  if (!normalizedKey) return null
-  const cfg = normalizeDefinitionConfig((def as any).configJson)
-  const label =
-    typeof cfg.label === 'string' && cfg.label.trim().length
-      ? cfg.label.trim()
-      : def.key
-  const dictionaryId =
-    typeof cfg.dictionaryId === 'string' && cfg.dictionaryId.trim().length
-      ? cfg.dictionaryId.trim()
-      : null
-  const multi =
-    cfg.multi !== undefined ? Boolean(cfg.multi) : false
-  const priority =
-    typeof cfg.priority === 'number' ? cfg.priority : 0
-  const updatedAt =
-    def.updatedAt instanceof Date
-      ? def.updatedAt.getTime()
-      : new Date(def.updatedAt as any).getTime()
-  return {
-    key: def.key,
-    label,
-    kind: typeof def.kind === 'string' ? def.kind : null,
-    multi,
-    dictionaryId,
-    organizationId: def.organizationId ?? null,
-    tenantId: def.tenantId ?? null,
-    priority,
-    updatedAt: Number.isNaN(updatedAt) ? 0 : updatedAt,
-  }
-}
-
-function sortDefinitionSummaries(defs: CustomFieldDefinitionSummary[]): CustomFieldDefinitionSummary[] {
-  return [...defs].sort((a, b) => {
-    const priorityDiff = (a.priority ?? 0) - (b.priority ?? 0)
-    if (priorityDiff !== 0) return priorityDiff
-    const updatedDiff = (b.updatedAt ?? 0) - (a.updatedAt ?? 0)
-    if (updatedDiff !== 0) return updatedDiff
-    return a.key.localeCompare(b.key)
-  })
-}
-
-function selectDefinitionForRecord(
-  defs: CustomFieldDefinitionSummary[],
-  organizationId: string | null,
-  tenantId: string | null,
-): CustomFieldDefinitionSummary | null {
-  if (!defs.length) return null
-  const prioritizedForOrg = defs.filter(
-    (def) => def.organizationId && organizationId && def.organizationId === organizationId,
-  )
-  if (prioritizedForOrg.length) return sortDefinitionSummaries(prioritizedForOrg)[0]
-  const prioritizedForTenant = defs.filter(
-    (def) => def.tenantId && tenantId && def.tenantId === tenantId && !def.organizationId,
-  )
-  if (prioritizedForTenant.length) return sortDefinitionSummaries(prioritizedForTenant)[0]
-  const global = defs.filter((def) => !def.organizationId)
-  if (global.length) return sortDefinitionSummaries(global)[0]
-  return sortDefinitionSummaries(defs)[0] ?? null
-}
-
 type LoadCustomFieldDefinitionIndexOptions = {
   em: EntityManager
   entityIds: string | string[]
@@ -463,36 +357,20 @@ async function loadCustomFieldDefinitionIndexFresh(
     $and: scopeClauses,
   }
   const defs = await em.find(CustomFieldDef, where as any)
-  const fieldsetFilter = normalizeFieldsetFilter(opts.fieldset)
-  const index: CustomFieldDefinitionIndex = new Map()
-  defs.forEach((def) => {
-    if (fieldsetFilter) {
-      const config = normalizeDefinitionConfig((def as any).configJson)
-      const fieldsets = Array.isArray(config.fieldsets)
-        ? config.fieldsets
-            .filter((entry: unknown): entry is string => typeof entry === 'string')
-            .map((entry: string) => entry.trim())
-            .filter((entry: string) => entry.length > 0)
-        : []
-      const fieldset = typeof config.fieldset === 'string' && config.fieldset.trim().length > 0
-        ? config.fieldset.trim()
-        : null
-      const matches = fieldsets.length > 0
-        ? fieldsets.some((entry: string) => fieldsetFilter.has(entry))
-        : fieldsetFilter.has(fieldset)
-      if (!matches) return
-    }
-    const summary = summarizeDefinition(def)
-    if (!summary) return
-    const normalizedKey = normalizeDefinitionKey(summary.key)
-    if (!normalizedKey) return
-    if (!index.has(normalizedKey)) index.set(normalizedKey, [])
-    index.get(normalizedKey)!.push(summary)
-  })
-  index.forEach((entries, key) => {
-    index.set(key, sortDefinitionSummaries(entries))
+  const rows: CustomFieldDefinitionRow[] = defs.map((def) => ({
+    key: def.key,
+    entityId: String((def as any).entityId),
+    kind: typeof def.kind === 'string' ? def.kind : null,
+    configJson: (def as any).configJson,
+    organizationId: def.organizationId ?? null,
+    tenantId: def.tenantId ?? null,
+    deletedAt: (def as any).deletedAt ?? null,
+    updatedAt: (def as any).updatedAt ?? null,
+  }))
+  return buildCustomFieldDefinitionIndexFromRows(rows, {
+    organizationIds: orgCandidates,
+    fieldset: opts.fieldset,
   })
-  return index
 }
 
 export async function loadCustomFieldDefinitionIndex(opts: LoadCustomFieldDefinitionIndexOptions & {

package/src/lib/crud/factory.ts

@@ -33,6 +33,12 @@ import {
   applyCustomFieldsNormalization,
   loadCustomFieldDefinitionIndex,
 } from './custom-fields'
+import {
+  canReuseCustomFieldDefinitions,
+  resolveCfDefIndexOrgCandidates,
+  type CustomFieldDefinitionIndex,
+  type ResolvedCustomFieldDefinitions,
+} from './custom-field-definition-index'
 import { serializeExport, normalizeExportFormat, defaultExportFilename, ensureColumns, type CrudExportFormat, type PreparedExport } from './exporters'
 import { CrudHttpError, isCrudHttpError } from './errors'
 import type { CommandBus, CommandLogMetadata } from '@open-mercato/shared/lib/commands'
@@ -956,7 +962,11 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
     return null
   }
 
-  const decorateItemsWithCustomFields = async (items: any[], ctx: CrudCtx): Promise<any[]> => {
+  const decorateItemsWithCustomFields = async (
+    items: any[],
+    ctx: CrudCtx,
+    precomputedDefinitions?: ResolvedCustomFieldDefinitions,
+  ): Promise<any[]> => {
     if (!listCustomFieldDecorator || !Array.isArray(items) || items.length === 0) return items
     const entityIds = Array.isArray(listCustomFieldDecorator.entityIds)
       ? listCustomFieldDecorator.entityIds
@@ -976,19 +986,33 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
         Array.isArray(ctx.organizationIds) && ctx.organizationIds.length
           ? ctx.organizationIds
           : [ctx.selectedOrganizationId ?? null]
-      let cfDefCache: CacheStrategy | null = null
-      try {
-        cfDefCache = ctx.container.resolve('cache') as CacheStrategy
-      } catch {}
-      const definitionIndex = await loadCustomFieldDefinitionIndex({
-        em,
-        entityIds,
-        tenantId: ctx.auth?.tenantId ?? null,
-        organizationIds,
-        cache: cfDefCache ?? null,
-        requestScope: ctx,
+      const tenantId = ctx.auth?.tenantId ?? null
+      // Reuse the index the query engine already resolved for this same scope
+      // (#2133) instead of issuing a second `custom_field_defs` round-trip.
+      const reusable = canReuseCustomFieldDefinitions(precomputedDefinitions, {
+        entityIds: entityIds.map(String),
+        tenantId,
+        organizationIds: resolveCfDefIndexOrgCandidates(ctx.organizationIds, ctx.selectedOrganizationId ?? null),
       })
-      cfProfiler.mark('definitions_loaded', { definitionCount: definitionIndex.size })
+      let definitionIndex: CustomFieldDefinitionIndex
+      if (reusable && precomputedDefinitions) {
+        definitionIndex = precomputedDefinitions.index
+        cfProfiler.mark('definitions_reused', { definitionCount: definitionIndex.size })
+      } else {
+        let cfDefCache: CacheStrategy | null = null
+        try {
+          cfDefCache = ctx.container.resolve('cache') as CacheStrategy
+        } catch {}
+        definitionIndex = await loadCustomFieldDefinitionIndex({
+          em,
+          entityIds,
+          tenantId,
+          organizationIds,
+          cache: cfDefCache ?? null,
+          requestScope: ctx,
+        })
+        cfProfiler.mark('definitions_loaded', { definitionCount: definitionIndex.size })
+      }
       const decoratedItems = items.map((raw) => {
         if (!raw || typeof raw !== 'object') return raw
         const item = raw as Record<string, unknown>
@@ -1572,7 +1596,7 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
         const rawItems = res.items || []
         let transformedItems = rawItems.map(i => (opts.list!.transformItem ? opts.list!.transformItem(i) : i))
         profiler.mark('transform_complete', { itemCount: transformedItems.length })
-        transformedItems = await decorateItemsWithCustomFields(transformedItems, ctx)
+        transformedItems = await decorateItemsWithCustomFields(transformedItems, ctx, res.customFieldDefinitions)
         profiler.mark('custom_fields_complete', { itemCount: transformedItems.length })
 
         if (opts.list?.entityId && request) {
@@ -1630,7 +1654,7 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
               const nextItemsRaw = nextRes.items || []
               if (!nextItemsRaw.length) break
               let nextTransformed = nextItemsRaw.map(i => (opts.list!.transformItem ? opts.list!.transformItem(i) : i))
-              nextTransformed = await decorateItemsWithCustomFields(nextTransformed, ctx)
+              nextTransformed = await decorateItemsWithCustomFields(nextTransformed, ctx, nextRes.customFieldDefinitions)
               const nextExportItems = exportFullRequested
                 ? nextItemsRaw.map(normalizeFullRecordForExport)
                 : nextTransformed
@@ -2094,25 +2118,31 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
         if (!ctx.auth.tenantId) return json({ error: 'Tenant context is required' }, { status: 400 })
         entityData[ormCfg.tenantField] = ctx.auth.tenantId
       }
-      const entity = await de.createOrmEntity({ entity: ormCfg.entity, data: entityData })
-
-      // Custom fields
-      if (createConfig.customFields && (createConfig.customFields as any).enabled) {
-        const cfc = createConfig.customFields as Exclude<CustomFieldsConfig, false>
-        const values = cfc.map
-          ? cfc.map(body)
-          : (cfc.pickPrefixed ? extractCustomFieldValuesFromPayload(body as Record<string, unknown>) : {})
-        if (values && Object.keys(values).length > 0) {
-          const de = (ctx.container.resolve('dataEngine') as DataEngine)
-          await de.setCustomFields({
-            entityId: cfc.entityId as any,
-            recordId: String((entity as any)[ormCfg.idField!]),
-            organizationId: targetOrgId,
-            tenantId: ctx.auth.tenantId!,
-            values,
-          })
+      const em = (ctx.container.resolve('em') as EntityManager)
+      const writeTenantId = ctx.auth.tenantId!
+      const entity = await em.transactional(async () => {
+        const created = await de.createOrmEntity({ entity: ormCfg.entity, data: entityData })
+
+        // Custom fields
+        if (createConfig.customFields && (createConfig.customFields as any).enabled) {
+          const cfc = createConfig.customFields as Exclude<CustomFieldsConfig, false>
+          const values = cfc.map
+            ? cfc.map(body)
+            : (cfc.pickPrefixed ? extractCustomFieldValuesFromPayload(body as Record<string, unknown>) : {})
+          if (values && Object.keys(values).length > 0) {
+            const de = (ctx.container.resolve('dataEngine') as DataEngine)
+            await de.setCustomFields({
+              entityId: cfc.entityId as any,
+              recordId: String((created as any)[ormCfg.idField!]),
+              organizationId: targetOrgId,
+              tenantId: writeTenantId,
+              values,
+            })
+          }
         }
-      }
+
+        return created
+      })
 
       await opts.hooks?.afterCreate?.(entity, { ...ctx, input: input as any })
 
@@ -2414,31 +2444,38 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
           softDeleteField: ormCfg.softDeleteField,
         }
       )
-      const entity = await de.updateOrmEntity({
-        entity: ormCfg.entity,
-        where,
-        apply: (e: any) => updateConfig.applyToEntity(e, input as any, ctx),
+      const em = (ctx.container.resolve('em') as EntityManager)
+      const writeTenantId = ctx.auth.tenantId!
+      const entity = await em.transactional(async () => {
+        const updated = await de.updateOrmEntity({
+          entity: ormCfg.entity,
+          where,
+          apply: (e: any) => updateConfig.applyToEntity(e, input as any, ctx),
+        })
+        if (!updated) return null
+
+        // Custom fields
+        if (updateConfig.customFields && (updateConfig.customFields as any).enabled) {
+          const cfc = updateConfig.customFields as Exclude<CustomFieldsConfig, false>
+          const values = cfc.map
+            ? cfc.map(body)
+            : (cfc.pickPrefixed ? extractCustomFieldValuesFromPayload(body as Record<string, unknown>) : {})
+          if (values && Object.keys(values).length > 0) {
+            const de = (ctx.container.resolve('dataEngine') as DataEngine)
+            await de.setCustomFields({
+              entityId: cfc.entityId as any,
+              recordId: String((updated as any)[ormCfg.idField!]),
+              organizationId: targetOrgId,
+              tenantId: writeTenantId,
+              values,
+            })
+          }
+        }
+
+        return updated
       })
       if (!entity) return json({ error: 'Not found' }, { status: 404 })
 
-      // Custom fields
-      if (updateConfig.customFields && (updateConfig.customFields as any).enabled) {
-        const cfc = updateConfig.customFields as Exclude<CustomFieldsConfig, false>
-        const values = cfc.map
-          ? cfc.map(body)
-          : (cfc.pickPrefixed ? extractCustomFieldValuesFromPayload(body as Record<string, unknown>) : {})
-        if (values && Object.keys(values).length > 0) {
-          const de = (ctx.container.resolve('dataEngine') as DataEngine)
-          await de.setCustomFields({
-            entityId: cfc.entityId as any,
-            recordId: String((entity as any)[ormCfg.idField!]),
-            organizationId: targetOrgId,
-            tenantId: ctx.auth.tenantId!,
-            values,
-          })
-        }
-      }
-
       await opts.hooks?.afterUpdate?.(entity, { ...ctx, input: input as any })
 
       // Guard afterSuccess callbacks (multi)

package/src/lib/query/__tests__/engine.test.ts

@@ -517,6 +517,86 @@ describe('BasicQueryEngine (Kysely)', () => {
     expect(hasInFilter).toBe(true)
   })
 
+  test('exposes resolved customFieldDefinitions when includeCustomFields is true (issue #2133)', async () => {
+    const fakeDb = createFakeKysely()
+    const engine = new BasicQueryEngine({} as any, () => fakeDb as any)
+    const res = await engine.query('auth:user', {
+      includeCustomFields: true,
+      fields: ['id'],
+      organizationId: '1',
+      tenantId: 't1',
+      page: { page: 1, pageSize: 10 },
+    })
+    expect(res.customFieldDefinitions).toBeDefined()
+    expect(res.customFieldDefinitions!.entityIds).toEqual(['auth:user'])
+    expect(res.customFieldDefinitions!.tenantId).toBe('t1')
+    expect(res.customFieldDefinitions!.organizationIds).toEqual(['1'])
+    expect(Array.from(res.customFieldDefinitions!.index.keys()).sort()).toEqual(['industry', 'vip'])
+  })
+
+  test('exposed customFieldDefinitions index drops soft-deleted and foreign-org defs', async () => {
+    const fakeDb = createFakeKysely({
+      custom_field_defs: [
+        { key: 'kept', entity_id: 'auth:user', is_active: true, config_json: '{}', kind: 'text', organization_id: null, tenant_id: 't1', updated_at: null, deleted_at: null },
+        { key: 'foreign', entity_id: 'auth:user', is_active: true, config_json: '{}', kind: 'text', organization_id: 'other-org', tenant_id: 't1', updated_at: null, deleted_at: null },
+        { key: 'gone', entity_id: 'auth:user', is_active: true, config_json: '{}', kind: 'text', organization_id: null, tenant_id: 't1', updated_at: null, deleted_at: '2026-01-01T00:00:00.000Z' },
+      ],
+      custom_field_values: [],
+    })
+    const engine = new BasicQueryEngine({} as any, () => fakeDb as any)
+    const res = await engine.query('auth:user', {
+      includeCustomFields: true,
+      fields: ['id'],
+      organizationId: 'allowed-org',
+      tenantId: 't1',
+      page: { page: 1, pageSize: 10 },
+    })
+    expect(Array.from(res.customFieldDefinitions!.index.keys())).toEqual(['kept'])
+  })
+
+  test('customFieldDefinitions entityIds include base entity plus custom field sources', async () => {
+    const fakeDb = createFakeKysely({
+      custom_field_defs: [
+        { key: 'birthday', entity_id: 'customers:customer_person_profile', is_active: true, config_json: '{}', kind: 'text', organization_id: null, tenant_id: 't1', updated_at: null, deleted_at: null },
+      ],
+      custom_field_values: [],
+      customer_entities: [],
+      customer_people: [],
+    })
+    const engine = new BasicQueryEngine({} as any, () => fakeDb as any)
+    const res = await engine.query('customers:customer_entity', {
+      tenantId: 't1',
+      includeCustomFields: true,
+      fields: ['id'],
+      customFieldSources: [
+        {
+          entityId: 'customers:customer_person_profile',
+          table: 'customer_people',
+          alias: 'person_profile',
+          recordIdColumn: 'id',
+          join: { fromField: 'id', toField: 'entity_id' },
+        },
+      ],
+      page: { page: 1, pageSize: 10 },
+    })
+    expect(res.customFieldDefinitions!.entityIds.sort()).toEqual([
+      'customers:customer_entity',
+      'customers:customer_person_profile',
+    ])
+  })
+
+  test('does not expose customFieldDefinitions when includeCustomFields is a key list', async () => {
+    const fakeDb = createFakeKysely()
+    const engine = new BasicQueryEngine({} as any, () => fakeDb as any)
+    const res = await engine.query('auth:user', {
+      includeCustomFields: ['vip'],
+      fields: ['id', 'cf:vip'],
+      tenantId: 't1',
+      page: { page: 1, pageSize: 10 },
+    })
+    expect(res.customFieldDefinitions).toBeUndefined()
+  })
+
   test('sorts encrypted base fields after decryption before pagination', async () => {
     const fakeDb = createFakeKysely({
       customer_entities: [

package/src/lib/query/engine.ts

@@ -14,6 +14,12 @@ import {
 import { resolveSearchConfig } from '../search/config'
 import { tokenizeText } from '../search/tokenize'
 import { runBeforeQueryPipeline, runAfterQueryPipeline, type QueryExtensionContext } from './query-extension-runner'
+import {
+  buildCustomFieldDefinitionIndexFromRows,
+  resolveCfDefIndexOrgCandidates,
+  type CustomFieldDefinitionRow,
+  type ResolvedCustomFieldDefinitions,
+} from '../crud/custom-field-definition-index'
 import { resolveEncryptedSortFields, sortRowsInMemory } from './encrypted-sort'
 
 type AnyDb = Kysely<any>
@@ -530,6 +536,9 @@ export class BasicQueryEngine implements QueryEngine {
       : []
     const cfKeys = new Set<string>()
     const keySource = new Map<string, ResolvedCustomFieldSource>()
+    // Custom-field definition index threaded onto the result so the CRUD factory
+    // can decorate list rows without reloading definitions from the DB (#2133).
+    let resolvedCustomFieldDefinitions: ResolvedCustomFieldDefinitions | undefined
     // Explicit in fields/filters
     for (const f of (opts.fields || [])) {
       if (typeof f === 'string' && f.startsWith('cf:')) cfKeys.add(f.slice(3))
@@ -544,21 +553,59 @@ export class BasicQueryEngine implements QueryEngine {
         entityIdList.forEach((id, idx) => entityOrder.set(id, idx))
         const rows = await db
           .selectFrom('custom_field_defs' as any)
-          .select(['key' as any, 'entity_id' as any, 'config_json' as any, 'kind' as any])
+          .select([
+            'key' as any,
+            'entity_id' as any,
+            'config_json' as any,
+            'kind' as any,
+            'organization_id' as any,
+            'tenant_id' as any,
+            'updated_at' as any,
+            'deleted_at' as any,
+          ])
           .where('entity_id' as any, 'in', entityIdList)
           .where('is_active' as any, '=', true)
           .where((eb: any) => eb.or([
             eb('tenant_id' as any, '=', tenantId),
             eb('tenant_id' as any, 'is', null),
           ]))
-          .execute() as Array<{ key: string; entity_id: string; config_json: unknown; kind: string }>
-        type CustomFieldDefinitionRow = {
+          .execute() as Array<{
+            key: string
+            entity_id: string
+            config_json: unknown
+            kind: string
+            organization_id: string | null
+            tenant_id: string | null
+            updated_at: Date | string | number | null
+            deleted_at: Date | string | number | null
+          }>
+        // Build the decoration index from the same rows, scoped exactly like the
+        // factory's loadCustomFieldDefinitionIndex (tenant + is_active already
+        // applied in SQL; org + soft-delete applied in the shared builder).
+        const orgCandidates = resolveCfDefIndexOrgCandidates(opts.organizationIds, opts.organizationId ?? null)
+        const definitionRows: CustomFieldDefinitionRow[] = rows.map((row) => ({
+          key: String(row.key),
+          entityId: String(row.entity_id),
+          kind: row.kind == null ? null : String(row.kind),
+          configJson: row.config_json,
+          organizationId: row.organization_id == null ? null : String(row.organization_id),
+          tenantId: row.tenant_id == null ? null : String(row.tenant_id),
+          deletedAt: row.deleted_at ?? null,
+          updatedAt: row.updated_at ?? null,
+        }))
+        resolvedCustomFieldDefinitions = {
+          index: buildCustomFieldDefinitionIndexFromRows(definitionRows, { organizationIds: orgCandidates }),
+          entityIds: entityIdList,
+          tenantId: tenantId ?? null,
+          organizationIds: orgCandidates,
+        }
+        type ScoredCustomFieldRow = {
           key: string
           entityId: string
           kind: string
           config: Record<string, unknown>
         }
-        const sorted: CustomFieldDefinitionRow[] = rows.map((row) => {
+        const sorted: ScoredCustomFieldRow[] = rows.map((row) => {
           const raw = row.config_json
           let cfg: Record<string, any> = {}
           if (raw && typeof raw === 'string') {
@@ -848,6 +895,12 @@ export class BasicQueryEngine implements QueryEngine {
       ) as QueryResult<T>
     }
 
+    // Attach after the extension pipeline so the field always survives even if a
+    // subscriber replaces the whole result object.
+    if (resolvedCustomFieldDefinitions) {
+      queryResult.customFieldDefinitions = resolvedCustomFieldDefinitions
+    }
+
     return queryResult
   }
 

package/src/lib/query/types.ts

@@ -1,5 +1,6 @@
 import type { EntityId } from '@open-mercato/shared/modules/entities'
 import type { Profiler } from '../profiler'
+import type { ResolvedCustomFieldDefinitions } from '../crud/custom-field-definition-index'
 
 export type FilterOp = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin' | 'like' | 'ilike' | 'exists'
 
@@ -147,6 +148,14 @@ export type QueryResult<T = any> = {
   pageSize: number
   total: number
   meta?: QueryResultMeta
+  /**
+   * Custom-field definitions the engine resolved while building this result
+   * (only present when `includeCustomFields: true`). Lets the CRUD factory
+   * decorate list rows without reloading definitions from the DB (issue #2133).
+   * Internal contract — additive and optional; callers must treat absence as a
+   * cue to load definitions themselves.
+   */
+  customFieldDefinitions?: ResolvedCustomFieldDefinitions
 }
 
 export interface QueryEngine {