@open-mercato/core 0.6.5-develop.4670.1.afe50dfd5c → 0.6.5-develop.4691.1.bb409545b3

package/src/helpers/integration/undoHarness.ts

@@ -1,5 +1,7 @@
-import { type APIRequestContext, type APIResponse, expect } from '@playwright/test'
+import { type APIRequestContext, type APIResponse, expect, test } from '@playwright/test'
+import { parseBooleanWithDefault } from '@open-mercato/shared/lib/boolean'
 import { apiRequest } from './api'
+import { expectId, readJsonSafe } from './generalFixtures'
 
 /**
  * Shared harness for verifying Undo/Redo correctness against the real command bus.
@@ -14,6 +16,7 @@ const HEADER_PREFIX = 'omop:'
 const UNDO_PATH = '/api/audit_logs/audit-logs/actions/undo'
 const REDO_PATH = '/api/audit_logs/audit-logs/actions/redo'
 const ACTIONS_PATH = '/api/audit_logs/audit-logs/actions'
+export const UNDO_TESTS_DISABLED_ENV = 'OM_INTEGRATION_UNDO_TESTS_DISABLED'
 
 export type Operation = {
   logId: string
@@ -23,6 +26,26 @@ export type Operation = {
   resourceId: string | null
 }
 
+export type CrudUndoEntityConfig = {
+  label: string
+  collectionPath: string
+  field: string
+  createPayload: (stamp: string) => Record<string, unknown>
+  updatePayload: (id: string, stamp: string) => Record<string, unknown>
+  readPath?: (id: string) => string
+  deletePath?: (id: string) => string
+  createStatus?: number
+  updateStatus?: number
+}
+
+export function undoTestsDisabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  return parseBooleanWithDefault(env[UNDO_TESTS_DISABLED_ENV], false)
+}
+
+export function skipIfUndoTestsDisabled(): void {
+  test.skip(undoTestsDisabled(), `${UNDO_TESTS_DISABLED_ENV} is set — undo/redo integration tests skipped`)
+}
+
 /** Parse the `x-om-operation` header into a structured operation, or null when absent/malformed. */
 export function extractOperation(response: APIResponse): Operation | null {
   const header = response.headers()['x-om-operation']
@@ -109,3 +132,111 @@ export function assertFieldsEqual(
     ).toBe(JSON.stringify((expected as Record<string, unknown>)[field]))
   }
 }
+
+function findRecord(body: unknown, id: string): Record<string, unknown> | null {
+  if (!body || typeof body !== 'object') return null
+  if (!Array.isArray(body) && (body as Record<string, unknown>).id === id) {
+    return body as Record<string, unknown>
+  }
+  for (const value of Array.isArray(body) ? body : Object.values(body)) {
+    const found = findRecord(value, id)
+    if (found) return found
+  }
+  return null
+}
+
+async function readRecord(
+  request: APIRequestContext,
+  token: string,
+  entity: CrudUndoEntityConfig,
+  id: string,
+): Promise<Record<string, unknown> | null> {
+  const path = entity.readPath?.(id) ?? `${entity.collectionPath}?id=${encodeURIComponent(id)}`
+  const response = await apiRequest(request, 'GET', path, { token })
+  const body = await readJsonSafe(response)
+  if (!response.ok()) return null
+  return findRecord(body, id)
+}
+
+function fieldValue(record: Record<string, unknown> | null, field: string): unknown {
+  return record?.[field]
+}
+
+async function deleteEntity(
+  request: APIRequestContext,
+  token: string,
+  entity: CrudUndoEntityConfig,
+  id: string,
+): Promise<APIResponse> {
+  const path = entity.deletePath?.(id) ?? `${entity.collectionPath}?id=${encodeURIComponent(id)}`
+  return apiRequest(request, 'DELETE', path, { token })
+}
+
+export async function runCrudUndoRoundTrip(
+  request: APIRequestContext,
+  token: string,
+  entity: CrudUndoEntityConfig,
+): Promise<void> {
+  const stamp = `${Date.now()}${Math.floor(Math.random() * 1000)}`
+  let createUndoId: string | null = null
+  let cycleId: string | null = null
+
+  try {
+    const createUndoRes = await apiRequest(request, 'POST', entity.collectionPath, {
+      token,
+      data: entity.createPayload(`${stamp}a`),
+    })
+    expect(createUndoRes.status(), `${entity.label} create-for-undo status`).toBe(entity.createStatus ?? 201)
+    const createUndoOp = expectOperation(createUndoRes, `${entity.label}.create`)
+    createUndoId = createUndoOp.resourceId || expectId((await readJsonSafe<Record<string, unknown>>(createUndoRes))?.id, `${entity.label} create id`)
+    expect(fieldValue(await readRecord(request, token, entity, createUndoId), entity.field), `${entity.label} field readable after create`).toBeDefined()
+
+    await undoOk(request, token, createUndoOp.undoToken, `${entity.label} undo create`)
+    expect(await readRecord(request, token, entity, createUndoId), `${entity.label} create→undo soft-deletes/removes the record (I3)`).toBeNull()
+    await expectTokenConsumed(request, token, createUndoOp.undoToken, `${entity.label} create token consumed (I5)`)
+
+    const createRes = await apiRequest(request, 'POST', entity.collectionPath, {
+      token,
+      data: entity.createPayload(`${stamp}b`),
+    })
+    expect(createRes.status(), `${entity.label} create status`).toBe(entity.createStatus ?? 201)
+    const createOp = expectOperation(createRes, `${entity.label}.create`)
+    cycleId = createOp.resourceId || expectId((await readJsonSafe<Record<string, unknown>>(createRes))?.id, `${entity.label} cycle id`)
+
+    const beforeUpdate = await readRecord(request, token, entity, cycleId)
+    const beforeValue = fieldValue(beforeUpdate, entity.field)
+    expect(beforeValue, `${entity.label} field readable before update`).toBeDefined()
+
+    const updateRes = await apiRequest(request, 'PUT', entity.collectionPath, {
+      token,
+      data: entity.updatePayload(cycleId, stamp),
+    })
+    expect(updateRes.status(), `${entity.label} update status`).toBe(entity.updateStatus ?? 200)
+    const updateOp = expectOperation(updateRes, `${entity.label}.update`)
+    const afterUpdate = await readRecord(request, token, entity, cycleId)
+    const afterUpdateValue = fieldValue(afterUpdate, entity.field)
+    expect(JSON.stringify(afterUpdateValue), `${entity.label} field changed by update`).not.toBe(JSON.stringify(beforeValue))
+
+    await new Promise((resolve) => setTimeout(resolve, 10))
+    await undoOk(request, token, updateOp.undoToken, `${entity.label} undo update`)
+    const afterUndo = await readRecord(request, token, entity, cycleId)
+    expect(JSON.stringify(fieldValue(afterUndo, entity.field)), `${entity.label} update→undo restores ${entity.field} (I1)`).toBe(JSON.stringify(beforeValue))
+    if (typeof beforeUpdate?.updatedAt === 'string' && typeof afterUndo?.updatedAt === 'string') {
+      expect(afterUndo.updatedAt, `${entity.label} undo bumps updatedAt`).not.toBe(beforeUpdate.updatedAt)
+    }
+
+    await redoOk(request, token, updateOp.logId, `${entity.label} redo update`)
+    expect(JSON.stringify(fieldValue(await readRecord(request, token, entity, cycleId), entity.field)), `${entity.label} redo re-applies update (I6)`).toBe(JSON.stringify(afterUpdateValue))
+
+    const deleteRes = await deleteEntity(request, token, entity, cycleId)
+    expect(deleteRes.ok(), `${entity.label} delete status ${deleteRes.status()}`).toBeTruthy()
+    const deleteOp = expectOperation(deleteRes, `${entity.label}.delete`)
+    expect(await readRecord(request, token, entity, cycleId), `${entity.label} deleted record should not read`).toBeNull()
+
+    await undoOk(request, token, deleteOp.undoToken, `${entity.label} undo delete`)
+    expect(fieldValue(await readRecord(request, token, entity, cycleId), entity.field), `${entity.label} delete→undo re-materializes (I2)`).toBeDefined()
+  } finally {
+    if (createUndoId) await deleteEntity(request, token, entity, createUndoId).catch(() => {})
+    if (cycleId) await deleteEntity(request, token, entity, cycleId).catch(() => {})
+  }
+}

package/src/modules/customers/AGENTS.md

@@ -87,6 +87,7 @@ Commands (`commands/people.ts`) demonstrate:
 3. Restore via `buildCustomFieldResetMap(before.custom, after.custom)` in undo
 4. Side effects with `emitCrudSideEffects` and `emitCrudUndoSideEffects`
 5. Include `indexer: { entityType, cacheAliases }` in both directions
+6. **Prefer `runCrudCommandWrite` for new commands** that combine entity writes + custom fields + side effects in one logical step. Reference: the migrated `updateDealCommand.execute` in `commands/deals.ts`. See `packages/core/AGENTS.md` → Entity Update Safety for the contract and `packages/shared/AGENTS.md` → `commands/runCrudCommandWrite` for the import.
 
 ## Transaction Safety
 

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

@@ -9,6 +9,7 @@ import {
   normalizeAuthorUserId,
 } from '@open-mercato/shared/lib/commands/helpers'
 import { withAtomicFlush } from '@open-mercato/shared/lib/commands/flush'
+import { runCrudCommandWrite } from '@open-mercato/shared/lib/commands/runCrudCommandWrite'
 import type { DataEngine } from '@open-mercato/shared/lib/data/engine'
 import type { EntityManager } from '@mikro-orm/postgresql'
 import {
@@ -569,120 +570,114 @@ const updateDealCommand: CommandHandler<DealUpdateInput, { dealId: string }> = {
     let nextPipelineStageLabel: string | null = null
     let resolvedCurrentPipelineStageLabel: string | null = null
 
-    await withAtomicFlush(em, [
-      async () => {
-        const pipelineAssignmentChanged =
-          parsed.pipelineId !== undefined || parsed.pipelineStageId !== undefined
-        const requestedPipelineStageId =
-          parsed.pipelineStageId !== undefined
-            ? parsed.pipelineStageId ?? null
-            : record.pipelineStageId ?? null
-        const requestedPipelineId =
-          parsed.pipelineId !== undefined ? parsed.pipelineId ?? null : record.pipelineId ?? null
-
-        nextStageSnapshot = requestedPipelineStageId && (pipelineAssignmentChanged || !record.pipelineStage)
-          ? await loadPipelineStageSnapshot(em, requestedPipelineStageId, record.tenantId, record.organizationId)
-          : null
-        if (pipelineAssignmentChanged) {
-          nextPipelineAssignment = resolvePipelineAssignment({
-            pipelineId: requestedPipelineId,
-            pipelineStageId: requestedPipelineStageId,
-            stageSnapshot: nextStageSnapshot,
-          })
-        }
-        nextPipelineStageLabel = nextStageSnapshot
-          ? (await ensureDictionaryEntry(em, {
-            tenantId: record.tenantId,
-            organizationId: record.organizationId,
-            kind: 'pipeline_stage',
-            value: nextStageSnapshot.label,
-          }))?.value ?? nextStageSnapshot.label
-          : null
-        resolvedCurrentPipelineStageLabel =
-          !nextStageSnapshot && record.pipelineStageId && (parsed.pipelineStageId !== undefined || !record.pipelineStage)
-            ? await resolvePipelineStageValue(em, record.pipelineStageId, record.tenantId, record.organizationId)
-            : null
-      },
-      () => {
-        if (parsed.title !== undefined) record.title = parsed.title
-        if (parsed.description !== undefined) record.description = parsed.description ?? null
-        if (parsed.status !== undefined) record.status = parsed.status ?? record.status
-        if (parsed.pipelineStage !== undefined) record.pipelineStage = parsed.pipelineStage ?? null
-        if (parsed.pipelineId !== undefined || (parsed.pipelineStageId !== undefined && nextStageSnapshot)) {
-          record.pipelineId = nextPipelineAssignment.pipelineId
-        }
-        if (parsed.pipelineStageId !== undefined) record.pipelineStageId = nextPipelineAssignment.pipelineStageId
-
-        if (nextPipelineStageLabel && (parsed.pipelineStageId !== undefined || !record.pipelineStage)) {
-          record.pipelineStage = nextPipelineStageLabel
-        } else if (resolvedCurrentPipelineStageLabel && (parsed.pipelineStageId !== undefined || !record.pipelineStage)) {
-          record.pipelineStage = resolvedCurrentPipelineStageLabel
-        }
-
-        if (parsed.valueAmount !== undefined) record.valueAmount = toNumericString(parsed.valueAmount)
-        if (parsed.valueCurrency !== undefined) record.valueCurrency = parsed.valueCurrency ?? null
-        if (parsed.probability !== undefined) record.probability = parsed.probability ?? null
-        if (parsed.expectedCloseAt !== undefined) record.expectedCloseAt = parsed.expectedCloseAt ?? null
-        if (parsed.ownerUserId !== undefined) record.ownerUserId = parsed.ownerUserId ?? null
-        if (parsed.source !== undefined) record.source = parsed.source ?? null
-        if (parsed.closureOutcome !== undefined) record.closureOutcome = parsed.closureOutcome ?? null
-        if (parsed.lossReasonId !== undefined) record.lossReasonId = parsed.lossReasonId ?? null
-        if (parsed.lossNotes !== undefined) record.lossNotes = parsed.lossNotes ?? null
-      },
-      async () => {
-        // CRITICAL: persist the scalar mutations above before any further `em.findOne` / sync
-        // helpers run inside this transaction. MikroORM v7's identity-map silently discards
-        // pending scalar changes on `record` if a query (such as the stage-transition lookup
-        // inside `upsertDealStageTransition`, or the linked-entity finds inside
-        // `syncDealPeople` / `syncDealCompanies`) executes on the same `EntityManager`
-        // before we explicitly flush. Without this flush, the entire kanban drag-and-drop
-        // returns 200 OK but never actually updates `customer_deals` rows — the card
-        // snaps back to its source lane on the next refetch (see SPEC-018).
-        await em.flush()
-      },
-      async () => {
-        const snapshot = nextStageSnapshot
-        if (!snapshot) return
-        const shouldRecord =
-          parsed.pipelineStageId !== undefined &&
-          parsed.pipelineStageId !== null &&
-          parsed.pipelineStageId !== previousPipelineStageId
-        if (!shouldRecord) return
-        await upsertDealStageTransition(em, {
-          deal: record,
-          pipelineId: snapshot.pipelineId,
-          stageId: snapshot.id,
-          stageLabel: nextPipelineStageLabel ?? snapshot.label,
-          stageOrder: snapshot.order,
-          transitionedByUserId: normalizedTransitionAuthorUserId,
-        })
-      },
-      () => syncDealPeople(em, record, parsed.personIds),
-      () => syncDealCompanies(em, record, parsed.companyIds),
-    ], { transaction: true })
-
-    const de = (ctx.container.resolve('dataEngine') as DataEngine)
-    await setCustomFieldsIfAny({
-      dataEngine: de,
+    await runCrudCommandWrite({
+      ctx,
+      em,
       entityId: DEAL_ENTITY_ID,
-      recordId: record.id,
-      organizationId: record.organizationId,
-      tenantId: record.tenantId,
-      values: custom,
-      notify: false,
-    })
-
-    await emitCrudSideEffects({
-      dataEngine: de,
       action: 'updated',
-      entity: record,
-      identifiers: {
-        id: record.id,
-        organizationId: record.organizationId,
-        tenantId: record.tenantId,
-      },
-      indexer: dealCrudIndexer,
+      scope: { tenantId: record.tenantId, organizationId: record.organizationId },
+      customFields: custom,
       events: dealCrudEvents,
+      indexer: dealCrudIndexer,
+      sideEffect: () => ({
+        entity: record,
+        identifiers: {
+          id: record.id,
+          organizationId: record.organizationId,
+          tenantId: record.tenantId,
+        },
+      }),
+      phases: [
+        async () => {
+          const pipelineAssignmentChanged =
+            parsed.pipelineId !== undefined || parsed.pipelineStageId !== undefined
+          const requestedPipelineStageId =
+            parsed.pipelineStageId !== undefined
+              ? parsed.pipelineStageId ?? null
+              : record.pipelineStageId ?? null
+          const requestedPipelineId =
+            parsed.pipelineId !== undefined ? parsed.pipelineId ?? null : record.pipelineId ?? null
+
+          nextStageSnapshot = requestedPipelineStageId && (pipelineAssignmentChanged || !record.pipelineStage)
+            ? await loadPipelineStageSnapshot(em, requestedPipelineStageId, record.tenantId, record.organizationId)
+            : null
+          if (pipelineAssignmentChanged) {
+            nextPipelineAssignment = resolvePipelineAssignment({
+              pipelineId: requestedPipelineId,
+              pipelineStageId: requestedPipelineStageId,
+              stageSnapshot: nextStageSnapshot,
+            })
+          }
+          nextPipelineStageLabel = nextStageSnapshot
+            ? (await ensureDictionaryEntry(em, {
+              tenantId: record.tenantId,
+              organizationId: record.organizationId,
+              kind: 'pipeline_stage',
+              value: nextStageSnapshot.label,
+            }))?.value ?? nextStageSnapshot.label
+            : null
+          resolvedCurrentPipelineStageLabel =
+            !nextStageSnapshot && record.pipelineStageId && (parsed.pipelineStageId !== undefined || !record.pipelineStage)
+              ? await resolvePipelineStageValue(em, record.pipelineStageId, record.tenantId, record.organizationId)
+              : null
+        },
+        () => {
+          if (parsed.title !== undefined) record.title = parsed.title
+          if (parsed.description !== undefined) record.description = parsed.description ?? null
+          if (parsed.status !== undefined) record.status = parsed.status ?? record.status
+          if (parsed.pipelineStage !== undefined) record.pipelineStage = parsed.pipelineStage ?? null
+          if (parsed.pipelineId !== undefined || (parsed.pipelineStageId !== undefined && nextStageSnapshot)) {
+            record.pipelineId = nextPipelineAssignment.pipelineId
+          }
+          if (parsed.pipelineStageId !== undefined) record.pipelineStageId = nextPipelineAssignment.pipelineStageId
+
+          if (nextPipelineStageLabel && (parsed.pipelineStageId !== undefined || !record.pipelineStage)) {
+            record.pipelineStage = nextPipelineStageLabel
+          } else if (resolvedCurrentPipelineStageLabel && (parsed.pipelineStageId !== undefined || !record.pipelineStage)) {
+            record.pipelineStage = resolvedCurrentPipelineStageLabel
+          }
+
+          if (parsed.valueAmount !== undefined) record.valueAmount = toNumericString(parsed.valueAmount)
+          if (parsed.valueCurrency !== undefined) record.valueCurrency = parsed.valueCurrency ?? null
+          if (parsed.probability !== undefined) record.probability = parsed.probability ?? null
+          if (parsed.expectedCloseAt !== undefined) record.expectedCloseAt = parsed.expectedCloseAt ?? null
+          if (parsed.ownerUserId !== undefined) record.ownerUserId = parsed.ownerUserId ?? null
+          if (parsed.source !== undefined) record.source = parsed.source ?? null
+          if (parsed.closureOutcome !== undefined) record.closureOutcome = parsed.closureOutcome ?? null
+          if (parsed.lossReasonId !== undefined) record.lossReasonId = parsed.lossReasonId ?? null
+          if (parsed.lossNotes !== undefined) record.lossNotes = parsed.lossNotes ?? null
+        },
+        async () => {
+          // CRITICAL: persist the scalar mutations above before any further `em.findOne` / sync
+          // helpers run inside this transaction. MikroORM v7's identity-map silently discards
+          // pending scalar changes on `record` if a query (such as the stage-transition lookup
+          // inside `upsertDealStageTransition`, or the linked-entity finds inside
+          // `syncDealPeople` / `syncDealCompanies`) executes on the same `EntityManager`
+          // before we explicitly flush. Without this flush, the entire kanban drag-and-drop
+          // returns 200 OK but never actually updates `customer_deals` rows — the card
+          // snaps back to its source lane on the next refetch (see SPEC-018).
+          await em.flush()
+        },
+        async () => {
+          const snapshot = nextStageSnapshot
+          if (!snapshot) return
+          const shouldRecord =
+            parsed.pipelineStageId !== undefined &&
+            parsed.pipelineStageId !== null &&
+            parsed.pipelineStageId !== previousPipelineStageId
+          if (!shouldRecord) return
+          await upsertDealStageTransition(em, {
+            deal: record,
+            pipelineId: snapshot.pipelineId,
+            stageId: snapshot.id,
+            stageLabel: nextPipelineStageLabel ?? snapshot.label,
+            stageOrder: snapshot.order,
+            transitionedByUserId: normalizedTransitionAuthorUserId,
+          })
+        },
+        () => syncDealPeople(em, record, parsed.personIds),
+        () => syncDealCompanies(em, record, parsed.companyIds),
+      ],
     })
 
     // Emit a lifecycle event for deal won/lost status changes; the notifications

package/src/modules/entities/lib/helpers.ts

@@ -118,6 +118,30 @@ export async function setRecordCustomFields(
     throw new Error(TOO_MANY_CUSTOM_FIELDS_ERROR)
   }
 
+  // Run the per-key delete+insert work inside ONE database transaction so a
+  // multi-value replacement is atomic and isolated. The array branch deletes the
+  // existing rows for a key and inserts the replacements; without an enclosing
+  // transaction those can land in separate commit boundaries under MikroORM's
+  // FlushMode.AUTO (a query elsewhere in the unit auto-flushes part of the work),
+  // which intermittently left the field with the delete applied but the inserts
+  // missing — the multi-select EDIT reverted to []. The single commit below makes
+  // it all-or-nothing. We only open our own transaction when the caller has not
+  // already started one (commands fork the request em and may run setCustomFields
+  // outside their own withAtomicFlush tx); join an ambient transaction otherwise.
+  const txEm = em as {
+    begin?: () => Promise<void>
+    commit?: () => Promise<void>
+    rollback?: () => Promise<void>
+    isInTransaction?: () => boolean
+  }
+  const txCapable =
+    typeof txEm.begin === 'function' &&
+    typeof txEm.commit === 'function' &&
+    typeof txEm.rollback === 'function' &&
+    typeof txEm.isInTransaction === 'function'
+  const ownCustomFieldTransaction = txCapable && !txEm.isInTransaction!()
+  if (ownCustomFieldTransaction) await txEm.begin!()
+  try {
   for (const fieldKey of keys) {
     const raw = values[fieldKey]
     if (raw === undefined) continue
@@ -125,10 +149,19 @@ export async function setRecordCustomFields(
     const def = defsByKey?.[fieldKey]
     const encrypted = Boolean(def?.configJson && (def as any).configJson?.encrypted)
     const isArray = Array.isArray(raw)
-    // When array: remove existing values for key and create multiple rows
+    // When array (multi-value): replace all existing rows for the key. The old
+    // rows are removed via em.remove (a DEFERRED delete keyed by primary id),
+    // not nativeDelete, so the DELETE and the replacement INSERTs are applied in
+    // the SAME em.flush() — MikroORM wraps a flush in one transaction, making the
+    // replacement atomic (the field can never be left empty by a partial
+    // failure between delete and insert). It also removes the FlushMode.AUTO
+    // footgun the old code had: a nativeDelete issued after em.create()
+    // auto-flushed the new rows and then deleted them by fieldKey, wiping the
+    // value on EDIT. Regression: TC-CAT-CF-MULTI-EDIT-001 / TC-CRM-CF-MULTI-EDIT-001.
     if (isArray) {
       const arr = raw as Primitive[]
-      const replacements: CustomFieldValue[] = []
+      const existing = await em.find(CustomFieldValue, { entityId, recordId, organizationId, tenantId, fieldKey })
+      for (const stale of existing) em.remove(stale)
       for (const val of arr) {
         const col: keyof CustomFieldValue = encrypted ? 'valueText' : def ? columnFromKind(def.kind) : columnFromJsValue(val)
         const cf = em.create(CustomFieldValue, { entityId, recordId, organizationId, tenantId, fieldKey, createdAt: new Date() })
@@ -144,10 +177,8 @@ export async function setRecordCustomFields(
           case 'valueBool': cf.valueBool = stored == null ? null : Boolean(stored); break
           default: cf.valueText = stored == null ? null : String(stored); break
         }
-        replacements.push(cf)
+        toPersist.push(cf)
       }
-      await em.nativeDelete(CustomFieldValue, { entityId, recordId, organizationId, tenantId, fieldKey })
-      toPersist.push(...replacements)
       continue
     }
 
@@ -186,24 +217,15 @@ export async function setRecordCustomFields(
 
   if (toPersist.length) em.persist(toPersist)
   await em.flush()
-  if (process.env.OM_CF_DEBUG) {
-    try {
-      const conn = em.getConnection()
-      for (const fieldKey of keys) {
-        if (values[fieldKey] === undefined) continue
-        const rows = await conn.execute(
-          'select value_text, value_multiline, value_int, value_float, value_bool from custom_field_values where entity_id = ? and record_id = ? and field_key = ? and ((organization_id is null and ? is null) or organization_id = ?) and ((tenant_id is null and ? is null) or tenant_id = ?)',
-          [entityId, recordId, fieldKey, organizationId, organizationId, tenantId, tenantId],
-          'all',
-        ) as Array<Record<string, unknown>>
-        const persisted = rows.map((row) => row.value_text ?? row.value_multiline ?? row.value_int ?? row.value_float ?? row.value_bool)
-        console.warn(`[CF_DEBUG] setRecordCustomFields entityId=${entityId} recordId=${recordId} fieldKey=${fieldKey} input=${JSON.stringify(values[fieldKey])} persistedRows=${rows.length} persisted=${JSON.stringify(persisted)}`)
-      }
-    } catch (err) {
-      console.warn(`[CF_DEBUG] re-query failed: ${(err as Error)?.message ?? String(err)}`)
+    if (ownCustomFieldTransaction) await txEm.commit!()
+  } catch (err) {
+    if (ownCustomFieldTransaction) {
+      try { await txEm.rollback!() } catch { /* surface the original error, not a rollback failure */ }
     }
+    throw err
   }
-  // Emit hook for indexing if requested (outside CRUD flows)
+  // Emit hook for indexing if requested (outside CRUD flows). Runs AFTER the
+  // transaction commits so consumers observe the persisted rows.
   try {
     if (typeof opts.onChanged === 'function') {
       await opts.onChanged({ entityId, recordId, organizationId, tenantId })

package/src/modules/query_index/lib/indexer.ts

@@ -158,7 +158,7 @@ function scopeEntityIndexes<QB extends { where: (...args: any[]) => QB }>(
 
 export async function upsertIndexRow(
   em: EntityManager,
-  args: { entityType: string; recordId: string; organizationId?: string | null; tenantId?: string | null; searchTokenDoc?: Record<string, unknown> | null }
+  args: { entityType: string; recordId: string; organizationId?: string | null; tenantId?: string | null; searchTokenDoc?: Record<string, unknown> | null; deferSearchTokens?: boolean }
 ): Promise<UpsertIndexResult> {
   const db = (em as any).getKysely()
 
@@ -172,14 +172,19 @@ export async function upsertIndexRow(
 
   const doc = await buildIndexDoc(em, args)
   if (!doc) {
-    try {
-      await deleteSearchTokensForRecord(db, {
-        entityType: args.entityType,
-        recordId: args.recordId,
-        organizationId: args.organizationId ?? null,
-        tenantId: args.tenantId ?? null,
-      })
-    } catch {}
+    // When the caller defers token work it owns the matching token cleanup; the
+    // projection-row removal below stays synchronous so list reads converge immediately.
+    if (!args.deferSearchTokens) {
+      try {
+        await reindexSearchTokensForRecord(em, {
+          entityType: args.entityType,
+          recordId: args.recordId,
+          organizationId: args.organizationId ?? null,
+          tenantId: args.tenantId ?? null,
+          doc: null,
+        })
+      } catch {}
+    }
     if (existed) {
       await scopeEntityIndexes(
         db.deleteFrom('entity_indexes' as any) as any,
@@ -233,27 +238,69 @@ export async function upsertIndexRow(
 
   const created = !existed
   const revived = existed && wasDeleted
-  try {
-    const tokenDoc = args.searchTokenDoc ?? (() => {
-      const encryption = resolveTenantEncryptionService(em as any)
-      const dekKeyCache = new Map<string | null, string | null>()
-      return decryptIndexDocForSearch(
-        args.entityType,
+  // The search-token rebuild (DELETE + chunked INSERT) is the heavy tail of indexing.
+  // Callers that defer it (the upsert subscriber) run `reindexSearchTokensForRecord`
+  // asynchronously after this projection update so write latency stays bounded.
+  if (!args.deferSearchTokens) {
+    try {
+      await reindexSearchTokensForRecord(em, {
+        entityType: args.entityType,
+        recordId: args.recordId,
+        organizationId: args.organizationId ?? null,
+        tenantId: args.tenantId ?? null,
         doc,
-        { tenantId: args.tenantId ?? null, organizationId: args.organizationId ?? null },
-        encryption,
-        dekKeyCache,
-      )
-    })()
-    await replaceSearchTokensForRecord(db, {
+        searchTokenDoc: args.searchTokenDoc ?? null,
+      })
+    } catch {}
+  }
+  return { doc, existed, wasDeleted, created, revived }
+}
+
+/**
+ * Rebuilds (or clears, when `doc` is null) the search-token rows for a single record.
+ * This is the asynchronous-friendly tail of `upsertIndexRow`: it does not touch the
+ * `entity_indexes` projection that list endpoints read, so it can run out-of-band
+ * without making query-index reads inconsistent.
+ */
+export async function reindexSearchTokensForRecord(
+  em: EntityManager,
+  args: {
+    entityType: string
+    recordId: string
+    organizationId?: string | null
+    tenantId?: string | null
+    doc: Record<string, any> | null
+    searchTokenDoc?: Record<string, unknown> | null
+  },
+): Promise<void> {
+  const db = (em as any).getKysely()
+  if (!args.doc) {
+    await deleteSearchTokensForRecord(db, {
       entityType: args.entityType,
       recordId: args.recordId,
       organizationId: args.organizationId ?? null,
       tenantId: args.tenantId ?? null,
-      doc: await tokenDoc,
     })
-  } catch {}
-  return { doc, existed, wasDeleted, created, revived }
+    return
+  }
+  const tokenDoc = args.searchTokenDoc ?? (() => {
+    const encryption = resolveTenantEncryptionService(em as any)
+    const dekKeyCache = new Map<string | null, string | null>()
+    return decryptIndexDocForSearch(
+      args.entityType,
+      args.doc,
+      { tenantId: args.tenantId ?? null, organizationId: args.organizationId ?? null },
+      encryption,
+      dekKeyCache,
+    )
+  })()
+  await replaceSearchTokensForRecord(db, {
+    entityType: args.entityType,
+    recordId: args.recordId,
+    organizationId: args.organizationId ?? null,
+    tenantId: args.tenantId ?? null,
+    doc: await tokenDoc,
+  })
 }
 
 export async function markDeleted(