@open-mercato/core 0.7.1-develop.7153.1.7145d295e6 → 0.7.1-develop.7170.1.d95074d7ba

package/src/modules/customer_accounts/widgets/injection/account-status/widget.client.tsx

@@ -48,9 +48,26 @@ interface PersonData {
   } | null
 }
 
-function InviteForm({ personEntityId, onSuccess }: { personEntityId: string; onSuccess: () => void }) {
+async function fetchPendingInvitation(filter: string): Promise<PendingInvitationData | null> {
+  const result = await apiCall(`/api/customer_accounts/admin/users-invite?${filter}&pageSize=1`)
+  if (!result.ok) return null
+  const json = result.result as Record<string, unknown> | null
+  const items = json?.items as PendingInvitationData[] | undefined
+  return items?.[0] || null
+}
+
+function InviteForm({
+  personEntityId,
+  personData,
+  isLoadingPerson,
+  onSuccess,
+}: {
+  personEntityId: string
+  personData: PersonData | null
+  isLoadingPerson: boolean
+  onSuccess: () => void
+}) {
   const t = useT()
-  const [isLoadingPerson, setIsLoadingPerson] = React.useState(true)
   const [email, setEmail] = React.useState('')
   const [displayName, setDisplayName] = React.useState('')
   const [selectedRoleIds, setSelectedRoleIds] = React.useState<string[]>([])
@@ -63,35 +80,19 @@ function InviteForm({ personEntityId, onSuccess }: { personEntityId: string; onS
   })
 
   React.useEffect(() => {
-    let cancelled = false
-    async function loadPerson() {
-      try {
-        const call = await apiCall<PersonData>(
-          `/api/customers/people/${encodeURIComponent(personEntityId)}`,
-        )
-        if (cancelled) return
-        if (call.ok && call.result) {
-          const person = call.result.person
-          const profile = call.result.profile
-          if (person?.primaryEmail) {
-            setEmail(person.primaryEmail)
-          }
-          const nameParts = [profile?.firstName, profile?.lastName].filter(Boolean)
-          if (nameParts.length > 0) {
-            setDisplayName(nameParts.join(' '))
-          } else if (person?.displayName) {
-            setDisplayName(person.displayName)
-          }
-        }
-      } catch {
-        /* ignore - fields will remain empty for manual entry */
-      } finally {
-        if (!cancelled) setIsLoadingPerson(false)
-      }
+    if (!personData) return
+    const person = personData.person
+    const profile = personData.profile
+    if (person?.primaryEmail) {
+      setEmail(person.primaryEmail)
     }
-    loadPerson()
-    return () => { cancelled = true }
-  }, [personEntityId])
+    const nameParts = [profile?.firstName, profile?.lastName].filter(Boolean)
+    if (nameParts.length > 0) {
+      setDisplayName(nameParts.join(' '))
+    } else if (person?.displayName) {
+      setDisplayName(person.displayName)
+    }
+  }, [personData])
 
   React.useEffect(() => {
     let cancelled = false
@@ -272,25 +273,52 @@ export default function AccountStatusWidget({ context }: AccountStatusProps) {
     enabled: !!personEntityId,
   })
 
+  // The person record backs both the pending-invitation email fallback below and
+  // the invite form defaults, so it is fetched once here and shared.
+  const { data: personData, isLoading: isLoadingPerson } = useQuery({
+    queryKey: ['customer-account-person', personEntityId],
+    queryFn: async (): Promise<PersonData | null> => {
+      if (!personEntityId) return null
+      const result = await apiCall<PersonData>(
+        `/api/customers/people/${encodeURIComponent(personEntityId)}`,
+      )
+      if (!result.ok) return null
+      return (result.result as PersonData | null) || null
+    },
+    enabled: !!personEntityId && !isLoading && !data,
+  })
+
+  const personEmail = personData?.person?.primaryEmail?.trim() || null
+
   // A portal account only exists once the invitation is accepted, so the users
   // query above stays empty right after a successful invite. Without this the
   // widget renders the identical "no account" state and the invite looks like a
   // no-op (#4950).
   const { data: pendingInvitation, isLoading: isLoadingInvitation } = useQuery({
-    queryKey: ['customer-account-pending-invitation', personEntityId],
+    queryKey: ['customer-account-pending-invitation', personEntityId, personEmail],
     queryFn: async (): Promise<PendingInvitationData | null> => {
       if (!personEntityId) return null
-      const result = await apiCall(
-        `/api/customer_accounts/admin/users-invite?personEntityId=${encodeURIComponent(personEntityId)}&pageSize=1`,
+      const byPerson = await fetchPendingInvitation(
+        `personEntityId=${encodeURIComponent(personEntityId)}`,
       )
-      if (!result.ok) return null
-      const json = result.result as Record<string, unknown> | null
-      const items = json?.items as PendingInvitationData[] | undefined
-      return items?.[0] || null
+      if (byPerson) return byPerson
+      // person_entity_id is optional on an invitation: the portal invite route
+      // only ever knows the company, and rows written before the entity-ownership
+      // guard landed the person id in customer_entity_id instead. The recipient
+      // address is the one identity every invitation carries, so match on it
+      // before reporting "no account" for someone who was already invited (#5499).
+      if (!personEmail) return null
+      return fetchPendingInvitation(`email=${encodeURIComponent(personEmail)}`)
     },
-    enabled: !!personEntityId && !isLoading && !data,
+    enabled: !!personEntityId && !isLoading && !data && !isLoadingPerson,
   })
 
+  // A disabled React Query reports isLoading === false, so isLoadingInvitation is
+  // false for the whole person fetch the email fallback waits on. Rendering off
+  // that alone would show "no portal account linked" with a live invite button
+  // during that window — the double-invite #5499 exists to prevent.
+  const isResolvingInvitation = isLoadingPerson || isLoadingInvitation
+
   function handleInviteSuccess() {
     setShowInviteForm(false)
     queryClient.invalidateQueries({ queryKey: ['customer-account-status', personEntityId] })
@@ -305,7 +333,7 @@ export default function AccountStatusWidget({ context }: AccountStatusProps) {
     return (
       <div className="rounded-md border p-3">
         <div className="text-sm font-medium mb-1">{t('customer_accounts.widgets.accountStatus', 'Portal Account')}</div>
-        {isLoadingInvitation ? (
+        {isResolvingInvitation ? (
           <div className="text-sm text-muted-foreground">{t('common.loading', 'Loading...')}</div>
         ) : pendingInvitation ? (
           <div className="space-y-1 text-sm">
@@ -327,7 +355,7 @@ export default function AccountStatusWidget({ context }: AccountStatusProps) {
         ) : (
           <div className="text-sm text-muted-foreground">{t('customer_accounts.widgets.noAccount', 'No portal account linked')}</div>
         )}
-        {!showInviteForm && personEntityId && !isLoadingInvitation && (
+        {!showInviteForm && personEntityId && !isResolvingInvitation && (
           <div className="mt-2">
             <Button
               type="button"
@@ -342,7 +370,12 @@ export default function AccountStatusWidget({ context }: AccountStatusProps) {
           </div>
         )}
         {showInviteForm && personEntityId && (
-          <InviteForm personEntityId={personEntityId} onSuccess={handleInviteSuccess} />
+          <InviteForm
+            personEntityId={personEntityId}
+            personData={personData ?? null}
+            isLoadingPerson={isLoadingPerson}
+            onSuccess={handleInviteSuccess}
+          />
         )}
       </div>
     )

package/src/modules/customers/commands/people.ts

@@ -207,6 +207,7 @@ const personCrudEvents: CrudEventsConfig<CustomerEntity> = {
     entityId: ctx.entity?.id ?? ctx.identifiers.id,
     organizationId: ctx.identifiers.organizationId,
     tenantId: ctx.identifiers.tenantId,
+    ...(ctx.syncOrigin ? { syncOrigin: ctx.syncOrigin } : {}),
   }),
 }
 
@@ -723,6 +724,8 @@ const createPersonCommand: CommandHandler<PersonCreateInput, { entityId: string;
         tenantId,
         organizationId,
       },
+      syncOrigin: ctx.syncOrigin,
+      actorUserId: ctx.auth?.sub ?? null,
       indexer: personCrudIndexer,
       events: personCrudEvents,
     })
@@ -784,6 +787,8 @@ const createPersonCommand: CommandHandler<PersonCreateInput, { entityId: string;
       action: 'deleted',
       entity,
       identifiers,
+      syncOrigin: ctx.syncOrigin,
+      actorUserId: ctx.auth?.sub ?? null,
       indexer: personCrudIndexer,
       events: personCrudEvents,
     })
@@ -904,6 +909,8 @@ const createPersonCommand: CommandHandler<PersonCreateInput, { entityId: string;
         tenantId: restoredEntity.tenantId,
         organizationId: restoredEntity.organizationId,
       },
+      syncOrigin: ctx.syncOrigin,
+      actorUserId: ctx.auth?.sub ?? null,
       indexer: personCrudIndexer,
       events: personCrudEvents,
     })
@@ -1057,6 +1064,8 @@ const updatePersonCommand: CommandHandler<PersonUpdateInput, { entityId: string
         tenantId: record.tenantId,
         organizationId: record.organizationId,
       },
+      syncOrigin: ctx.syncOrigin,
+      actorUserId: ctx.auth?.sub ?? null,
       indexer: personCrudIndexer,
       events: personCrudEvents,
     })
@@ -1199,6 +1208,8 @@ const updatePersonCommand: CommandHandler<PersonUpdateInput, { entityId: string
         organizationId: before.entity.organizationId,
         tenantId: before.entity.tenantId,
       },
+      syncOrigin: ctx.syncOrigin,
+      actorUserId: ctx.auth?.sub ?? null,
       indexer: personCrudIndexer,
       events: personCrudEvents,
     })
@@ -1322,6 +1333,8 @@ const deletePersonCommand: CommandHandler<{ body?: Record<string, unknown>; quer
           organizationId: record.organizationId,
           tenantId: record.tenantId,
         },
+        syncOrigin: ctx.syncOrigin,
+        actorUserId: ctx.auth?.sub ?? null,
         indexer: personCrudIndexer,
         events: personCrudEvents,
       })
@@ -1677,6 +1690,8 @@ const deletePersonCommand: CommandHandler<{ body?: Record<string, unknown>; quer
           organizationId: entity.organizationId,
           tenantId: entity.tenantId,
         },
+        syncOrigin: ctx.syncOrigin,
+        actorUserId: ctx.auth?.sub ?? null,
         indexer: personCrudIndexer,
         events: personCrudEvents,
       })

package/src/modules/data_sync/backend/data-sync/runs/[id]/page.tsx

@@ -1,6 +1,6 @@
 "use client"
 import * as React from 'react'
-import { usePathname, useRouter } from 'next/navigation'
+import { useRouter } from 'next/navigation'
 import { Page, PageBody } from '@open-mercato/ui/backend/Page'
 import { FormHeader } from '@open-mercato/ui/backend/forms'
 import { Card, CardHeader, CardTitle, CardContent } from '@open-mercato/ui/primitives/card'
@@ -87,28 +87,15 @@ function formatEtaSeconds(seconds: number): string {
 
 type SyncRunDetailPageProps = {
   params?: {
-    id?: string | string[]
+    id?: string
   }
 }
 
-function resolveRouteId(value: string | string[] | undefined): string | undefined {
-  if (Array.isArray(value)) return value[0]
-  return value
-}
-
-function resolvePathnameId(pathname: string): string | undefined {
-  const parts = pathname.split('/').filter(Boolean)
-  const runId = parts.at(-1)
-  if (!runId || runId === 'runs' || runId === 'data-sync') return undefined
-  return decodeURIComponent(runId)
-}
-
 const LOG_PAGE_SIZE = 50
 
 export default function SyncRunDetailPage({ params }: SyncRunDetailPageProps) {
-  const pathname = usePathname()
   const router = useRouter()
-  const runId = resolveRouteId(params?.id) ?? resolvePathnameId(pathname)
+  const runId = params?.id
   const t = useT()
   const { runMutation } = useGuardedMutation<Record<string, unknown>>({
     contextId: 'data_sync.runDetail',
@@ -129,14 +116,6 @@ export default function SyncRunDetailPage({ params }: SyncRunDetailPageProps) {
   // event that re-reads the run.
   const parameterLabelsIntegrationRef = React.useRef<string | null>(null)
 
-  const resolveCurrentRunId = React.useCallback(() => {
-    return runId ?? (
-      typeof window !== 'undefined'
-        ? resolvePathnameId(window.location.pathname)
-        : undefined
-    )
-  }, [runId])
-
   // The run row stores machine keys. Resolve the adapter's declared labels so a
   // past run reads as "Start id" rather than "startId"; keys the adapter no
   // longer declares keep their raw form, which keeps historical runs readable.
@@ -158,15 +137,14 @@ export default function SyncRunDetailPage({ params }: SyncRunDetailPageProps) {
   }, [t])
 
   const loadRun = React.useCallback(async () => {
-    const currentRunId = resolveCurrentRunId()
-    if (!currentRunId) {
+    if (!runId) {
       setError(t('data_sync.runs.detail.loadError'))
       setIsLoading(false)
       return
     }
     setIsNotFound(false)
     const call = await apiCall<SyncRunDetail>(
-      `/api/data_sync/runs/${encodeURIComponent(currentRunId)}`,
+      `/api/data_sync/runs/${encodeURIComponent(runId)}`,
       undefined,
       { fallback: null },
     )
@@ -184,14 +162,13 @@ export default function SyncRunDetailPage({ params }: SyncRunDetailPageProps) {
     if (call.result.parameters && Object.keys(call.result.parameters).length > 0) {
       void loadParameterLabels(call.result.integrationId)
     }
-  }, [loadParameterLabels, resolveCurrentRunId, t])
+  }, [loadParameterLabels, runId, t])
 
   const loadLogs = React.useCallback(async (page?: number) => {
-    const currentRunId = resolveCurrentRunId()
-    if (!currentRunId) return
+    if (!runId) return
     const targetPage = page ?? logsPageRef.current
     setIsLoadingLogs(true)
-    const params = new URLSearchParams({ runId: currentRunId, pageSize: String(LOG_PAGE_SIZE), page: String(targetPage) })
+    const params = new URLSearchParams({ runId, pageSize: String(LOG_PAGE_SIZE), page: String(targetPage) })
     const call = await apiCall<{ items: LogEntry[]; total?: number }>(
       `/api/integrations/logs?${params.toString()}`,
       undefined,
@@ -204,7 +181,7 @@ export default function SyncRunDetailPage({ params }: SyncRunDetailPageProps) {
       setLogsPage(targetPage)
     }
     setIsLoadingLogs(false)
-  }, [resolveCurrentRunId])
+  }, [runId])
 
   React.useEffect(() => {
     void loadRun()
@@ -265,18 +242,17 @@ export default function SyncRunDetailPage({ params }: SyncRunDetailPageProps) {
   }, [loadLogs, loadRun])
 
   const handleCancel = React.useCallback(async () => {
-    const currentRunId = resolveCurrentRunId()
-    if (!currentRunId) return
+    if (!runId) return
     const call = await runMutation({
       // optimistic-lock-exempt: run lifecycle action endpoint (cancel), not a concurrent record edit
-      operation: () => apiCall(`/api/data_sync/runs/${encodeURIComponent(currentRunId)}/cancel`, {
+      operation: () => apiCall(`/api/data_sync/runs/${encodeURIComponent(runId)}/cancel`, {
         method: 'POST',
       }, { fallback: null }),
-      mutationPayload: { runId: currentRunId },
+      mutationPayload: { runId },
       context: {
         operation: 'update',
         actionId: 'cancel-sync-run',
-        runId: currentRunId,
+        runId,
       },
     })
     if (call.ok) {
@@ -285,23 +261,22 @@ export default function SyncRunDetailPage({ params }: SyncRunDetailPageProps) {
     } else {
       flash(t('data_sync.runs.detail.cancelError'), 'error')
     }
-  }, [resolveCurrentRunId, runMutation, t, loadRun])
+  }, [runId, runMutation, t, loadRun])
 
   const handleRetry = React.useCallback(async () => {
-    const currentRunId = resolveCurrentRunId()
-    if (!currentRunId) return
+    if (!runId) return
     const call = await runMutation({
       // optimistic-lock-exempt: starts a new retry run (create), not a concurrent record edit
-      operation: () => apiCall<{ id: string }>(`/api/data_sync/runs/${encodeURIComponent(currentRunId)}/retry`, {
+      operation: () => apiCall<{ id: string }>(`/api/data_sync/runs/${encodeURIComponent(runId)}/retry`, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({ fromBeginning: false }),
       }, { fallback: null }),
-      mutationPayload: { runId: currentRunId, fromBeginning: false },
+      mutationPayload: { runId, fromBeginning: false },
       context: {
         operation: 'create',
         actionId: 'retry-sync-run',
-        runId: currentRunId,
+        runId,
       },
     })
     if (call.ok && call.result) {
@@ -310,7 +285,7 @@ export default function SyncRunDetailPage({ params }: SyncRunDetailPageProps) {
     } else {
       flash(buildRetryFailureMessage(call.result as RetryFailureBody | null, t), 'error')
     }
-  }, [resolveCurrentRunId, router, runMutation, t])
+  }, [runId, router, runMutation, t])
 
   if (isLoading) return <Page><PageBody><LoadingMessage label={t('data_sync.runs.detail.title')} /></PageBody></Page>
   if (isNotFound) {

package/src/modules/data_sync/lib/sync-schedule-service.ts

@@ -40,11 +40,11 @@ export function createSyncScheduleService(em: EntityManager, schedulerService?:
     return schedulerService
   }
 
-  function buildScheduleName(row: SyncSchedule): string {
+  function buildScheduleName(row: { integrationId: string; entityType: string; direction: 'import' | 'export' }): string {
     return `Data sync: ${row.integrationId} ${row.entityType} ${row.direction}`
   }
 
-  function buildScheduleDescription(row: SyncSchedule): string {
+  function buildScheduleDescription(row: { integrationId: string; entityType: string; direction: 'import' | 'export' }): string {
     return `Scheduled ${row.direction} for ${row.integrationId} (${row.entityType})`
   }
 
@@ -156,8 +156,36 @@ export function createSyncScheduleService(em: EntityManager, schedulerService?:
         })
       }
 
+      const id = existing?.id ?? randomUUID()
+      const scheduledJobId = existing?.scheduledJobId ?? id
+
+      // Validate the schedule (and register it with the scheduler) before writing
+      // the SyncSchedule row — an unparseable scheduleValue must not leave a
+      // persisted row with no working schedule behind it.
+      await requireScheduler().register({
+        id: scheduledJobId,
+        name: buildScheduleName(input),
+        description: buildScheduleDescription(input),
+        scopeType: 'organization',
+        organizationId: scope.organizationId,
+        tenantId: scope.tenantId,
+        scheduleType: input.scheduleType,
+        scheduleValue: input.scheduleValue,
+        timezone: input.timezone,
+        targetType: 'queue',
+        targetQueue: 'data-sync-scheduled',
+        targetPayload: {
+          scheduleId: id,
+          scope,
+        },
+        requireFeature: 'data_sync.run',
+        sourceType: 'module',
+        sourceModule: 'data_sync',
+        isEnabled: input.isEnabled,
+      })
+
       const row = existing ?? em.create(SyncSchedule, {
-        id: randomUUID(),
+        id,
         integrationId: input.integrationId,
         entityType: input.entityType,
         direction: input.direction,
@@ -178,7 +206,7 @@ export function createSyncScheduleService(em: EntityManager, schedulerService?:
       row.timezone = input.timezone
       row.fullSync = input.fullSync
       row.isEnabled = input.isEnabled
-      row.scheduledJobId = row.scheduledJobId ?? row.id
+      row.scheduledJobId = scheduledJobId
 
       if (!existing) {
         em.persist(row)
@@ -186,28 +214,6 @@ export function createSyncScheduleService(em: EntityManager, schedulerService?:
 
       await em.flush()
 
-      await requireScheduler().register({
-        id: row.scheduledJobId,
-        name: buildScheduleName(row),
-        description: buildScheduleDescription(row),
-        scopeType: 'organization',
-        organizationId: scope.organizationId,
-        tenantId: scope.tenantId,
-        scheduleType: row.scheduleType,
-        scheduleValue: row.scheduleValue,
-        timezone: row.timezone,
-        targetType: 'queue',
-        targetQueue: 'data-sync-scheduled',
-        targetPayload: {
-          scheduleId: row.id,
-          scope,
-        },
-        requireFeature: 'data_sync.run',
-        sourceType: 'module',
-        sourceModule: 'data_sync',
-        isEnabled: row.isEnabled,
-      })
-
       return row
     },
 

package/src/modules/entities/api/records.ts

@@ -15,6 +15,7 @@ import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
 import { enforceCommandOptimisticLockWithGuards } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
 import { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
 import { assertEntityAclForRequest, getDeclaredCustomEntityRestriction } from '../lib/entityAcl'
+import { loadCustomFieldKinds } from '../lib/scoped-field-defs'
 import { createLogger } from '@open-mercato/shared/lib/logger'
 
 const logger = createLogger('entities').child({ component: 'records' })
@@ -197,24 +198,34 @@ export async function GET(req: Request) {
     if (organizationIds && organizationIds.length === 0) {
       return NextResponse.json({ items: [], total: 0, page, pageSize, totalPages: 0 })
     }
-    const normalizeCustomEntityValue = (value: unknown) => {
-      if (Array.isArray(value)) {
-        return value.map((entry) => {
-          if (typeof entry !== 'string') return entry
-          const parsed = parseBooleanToken(entry)
-          return parsed === null ? entry : parsed
-        })
-      }
-      if (typeof value !== 'string') return value
+    // Doc storage keeps custom-field values as JSON, so a checkbox can arrive as the
+    // string "true"/"1" and must be handed back to the form as a real boolean. That
+    // parse is only ever correct for fields DECLARED boolean: applied blind it also
+    // rewrites legitimate string values whose text happens to be a boolean token —
+    // a `select` option `no` came back as `false`, and the edit form then wrote that
+    // boolean back over the stored option (#5791). Consult the declared kind instead.
+    const needsFieldKinds = isCustomEntity || qpEntries.some(([key]) => key.startsWith('cf_'))
+    const fieldKinds = needsFieldKinds
+      ? await loadCustomFieldKinds(em, { entityId, organizationId: scope.selectedId ?? auth.orgId ?? null, tenantId: auth.tenantId ?? null })
+      : new Map<string, string>()
+    const isBooleanField = (key: string) => fieldKinds.get(key) === 'boolean'
+    const parseBooleanField = (key: string, value: unknown) => {
+      if (typeof value !== 'string' || !isBooleanField(key)) return value
       const parsed = parseBooleanToken(value)
       return parsed === null ? value : parsed
     }
+    const normalizeCustomEntityValue = (key: string, value: unknown) => {
+      if (Array.isArray(value)) return value.map((entry) => parseBooleanField(key, entry))
+      return parseBooleanField(key, value)
+    }
     const mapRow = (row: any) => {
       if (!isCustomEntity || !row || typeof row !== 'object') return row
       const out: Record<string, unknown> = {}
       for (const [k, v] of Object.entries(row)) {
-        if (k.startsWith('cf_')) out[k.replace(/^cf_/, '')] = normalizeCustomEntityValue(v)
-        else out[k] = v
+        if (k.startsWith('cf_')) {
+          const bare = k.replace(/^cf_/, '')
+          out[bare] = normalizeCustomEntityValue(bare, v)
+        } else out[k] = v
       }
       return out
     }
@@ -235,8 +246,7 @@ export async function GET(req: Request) {
             const values = parseCommaSeparatedList(val)
             ;(filtersObj as any)[key] = { $in: values }
           } else {
-            const parsed = parseBooleanToken(val)
-            ;(filtersObj as any)[key] = parsed === null ? val : parsed
+            ;(filtersObj as any)[key] = parseBooleanField(key.replace(/^cf_/, ''), val)
           }
         }
       } else if (allowAnyKey) {
@@ -244,8 +254,7 @@ export async function GET(req: Request) {
           const values = parseCommaSeparatedList(val)
           ;(filtersObj as any)[key] = { $in: values }
         } else {
-          const parsed = parseBooleanToken(val)
-          ;(filtersObj as any)[key] = parsed === null ? val : parsed
+          ;(filtersObj as any)[key] = parseBooleanField(key, val)
         }
       } else {
         if (['id', 'created_at', 'updated_at', 'deleted_at', 'name', 'title', 'email'].includes(key)) {

package/src/modules/entities/lib/scoped-field-defs.ts

@@ -0,0 +1,76 @@
+import type { EntityManager } from '@mikro-orm/core'
+import { CustomFieldDef } from '../data/entities'
+
+export type ScopedCustomFieldDefsOptions = {
+  entityId: string
+  organizationId?: string | null
+  tenantId?: string | null
+}
+
+// Definitions overlay by scope: an org+tenant row shadows a tenant-global row,
+// which shadows an instance-global one. Duplicate keys within the same scope are
+// resolved by recency so the newest definition wins.
+const scopeScore = (def: CustomFieldDef) => (def.tenantId ? 2 : 0) + (def.organizationId ? 1 : 0)
+
+const definitionTime = (def: CustomFieldDef) =>
+  def.updatedAt instanceof Date ? def.updatedAt.getTime() : new Date(def.updatedAt).getTime()
+
+export async function loadScopedCustomFieldDefs(
+  em: EntityManager,
+  opts: ScopedCustomFieldDefsOptions,
+): Promise<Map<string, CustomFieldDef>> {
+  const organizationId = opts.organizationId ?? null
+  const tenantId = opts.tenantId ?? null
+  const defs = await em.find(CustomFieldDef, {
+    entityId: opts.entityId,
+    isActive: true,
+    deletedAt: null,
+    $and: [
+      {
+        $or: organizationId === null
+          ? [{ organizationId: null }]
+          : [{ organizationId }, { organizationId: null }],
+      },
+      {
+        $or: tenantId === null
+          ? [{ tenantId: null }]
+          : [{ tenantId }, { tenantId: null }],
+      },
+    ],
+  } as any)
+
+  const byKey = new Map<string, CustomFieldDef>()
+  for (const def of defs) {
+    const existing = byKey.get(def.key)
+    if (!existing) {
+      byKey.set(def.key, def)
+      continue
+    }
+    const nextScore = scopeScore(def)
+    const existingScore = scopeScore(existing)
+    if (nextScore > existingScore) {
+      byKey.set(def.key, def)
+      continue
+    }
+    if (nextScore < existingScore) continue
+    if (definitionTime(def) >= definitionTime(existing)) byKey.set(def.key, def)
+  }
+  return byKey
+}
+
+// Kind lookup used by read paths that must not reinterpret a stored value against
+// the wrong type. Failures degrade to an empty map: callers then leave values as
+// stored, which is always safer than coercing them blind.
+export async function loadCustomFieldKinds(
+  em: EntityManager,
+  opts: ScopedCustomFieldDefsOptions,
+): Promise<Map<string, string>> {
+  try {
+    const defs = await loadScopedCustomFieldDefs(em, opts)
+    const kinds = new Map<string, string>()
+    for (const [key, def] of defs) kinds.set(key, String(def.kind || ''))
+    return kinds
+  } catch {
+    return new Map<string, string>()
+  }
+}