@open-mercato/shared 0.6.4-develop.4382.1.6b4f656b77 → 0.6.4

package/src/lib/commands/__tests__/redo.test.ts

@@ -0,0 +1,265 @@
+import { reviveSnapshotSeed, serializeRowSnapshot, makeCreateRedo } from '../redo'
+
+describe('reviveSnapshotSeed', () => {
+  it('revives the default date fields from ISO strings to Date', () => {
+    const seed = reviveSnapshotSeed({
+      id: 'row-1',
+      code: 'USD',
+      createdAt: '2026-01-02T03:04:05.000Z',
+      updatedAt: '2026-01-02T03:04:05.000Z',
+      deletedAt: null,
+    })
+    expect(seed.id).toBe('row-1')
+    expect(seed.code).toBe('USD')
+    expect(seed.createdAt).toBeInstanceOf(Date)
+    expect((seed.createdAt as Date).toISOString()).toBe('2026-01-02T03:04:05.000Z')
+    expect(seed.updatedAt).toBeInstanceOf(Date)
+    expect(seed.deletedAt).toBeNull()
+  })
+
+  it('revives explicitly declared extra date fields', () => {
+    const seed = reviveSnapshotSeed(
+      { id: 'row-1', effectiveAt: '2026-02-03T00:00:00.000Z', updatedAt: '2026-02-03T00:00:00.000Z' },
+      ['createdAt', 'updatedAt', 'deletedAt', 'effectiveAt'],
+    )
+    expect(seed.effectiveAt).toBeInstanceOf(Date)
+    expect(seed.updatedAt).toBeInstanceOf(Date)
+  })
+
+  it('leaves non-date values untouched and clones the input', () => {
+    const snapshot = { id: 'row-1', symbol: null, decimalPlaces: 2 }
+    const seed = reviveSnapshotSeed(snapshot)
+    expect(seed).not.toBe(snapshot)
+    expect(seed.symbol).toBeNull()
+    expect(seed.decimalPlaces).toBe(2)
+  })
+})
+
+describe('serializeRowSnapshot', () => {
+  it('picks the requested fields and converts dates to ISO strings', () => {
+    const entity = {
+      id: 'row-1',
+      code: 'USD',
+      symbol: undefined as unknown as string,
+      createdAt: new Date('2026-01-02T03:04:05.000Z'),
+      updatedAt: new Date('2026-01-02T03:04:05.000Z'),
+      ignored: 'nope',
+    }
+    const snapshot = serializeRowSnapshot(entity, ['id', 'code', 'symbol', 'createdAt', 'updatedAt'])
+    expect(snapshot).toEqual({
+      id: 'row-1',
+      code: 'USD',
+      symbol: null,
+      createdAt: '2026-01-02T03:04:05.000Z',
+      updatedAt: '2026-01-02T03:04:05.000Z',
+    })
+  })
+})
+
+describe('makeCreateRedo defaults', () => {
+  function buildContext(em: { fork: () => unknown }) {
+    const dataEngine = { markOrmEntityChange: () => undefined }
+    return {
+      container: {
+        resolve: (name: string) => (name === 'em' ? em : dataEngine),
+      },
+    } as never
+  }
+
+  it('uses the snapshot as the seed (with date revival) when no seedFromSnapshot is given', async () => {
+    const created: Array<Record<string, unknown>> = []
+    const forked = {
+      findOne: async () => null,
+      create: (_cls: unknown, data: Record<string, unknown>) => {
+        created.push(data)
+        return { ...data }
+      },
+      persist: () => undefined,
+      flush: async () => undefined,
+    }
+    const em = { fork: () => forked }
+    const redo = makeCreateRedo<{ id: string; organizationId?: string | null; tenantId?: string | null }, { id: string; code: string; createdAt: string; updatedAt: string }>({
+      entityClass: class {} as never,
+      buildResult: (entity) => ({ id: entity.id }),
+    })
+    const logEntry = {
+      snapshotAfter: { id: 'row-1', code: 'USD', createdAt: '2026-01-02T03:04:05.000Z', updatedAt: '2026-01-02T03:04:05.000Z' },
+    }
+    const result = await redo({ input: {}, ctx: buildContext(em), logEntry: logEntry as never })
+    expect(result).toEqual({ id: 'row-1' })
+    expect(created).toHaveLength(1)
+    expect(created[0].id).toBe('row-1')
+    expect(created[0].code).toBe('USD')
+    expect(created[0].createdAt).toBeInstanceOf(Date)
+  })
+
+  it('merges beforeRestore overrides into the create seed and runs before restore', async () => {
+    const created: Array<Record<string, unknown>> = []
+    const calls: string[] = []
+    const forked = {
+      findOne: async () => { calls.push('find'); return null },
+      create: (_cls: unknown, data: Record<string, unknown>) => { created.push(data); return { ...data } },
+      persist: () => undefined,
+      flush: async () => undefined,
+    }
+    const em = { fork: () => forked }
+    const resolvedRelation = { id: 'rel-1' }
+    const redo = makeCreateRedo<{ id: string }, { id: string; relationId: string }>({
+      entityClass: class {} as never,
+      buildResult: (entity) => ({ id: entity.id }),
+      beforeRestore: async ({ snapshot }) => { calls.push('before'); return { relation: resolvedRelation, relationId: undefined } },
+    })
+    const logEntry = { snapshotAfter: { id: 'row-1', relationId: 'rel-1' } }
+    await redo({ input: {}, ctx: buildContext(em), logEntry: logEntry as never })
+    expect(calls).toEqual(['before', 'find'])
+    expect(created[0].relation).toBe(resolvedRelation)
+    expect(created[0].relationId).toBeUndefined()
+  })
+
+  it('uses the findRow override instead of em.findOne', async () => {
+    const surviving: Record<string, unknown> = { id: 'row-1', deletedAt: new Date() }
+    let findRowCalled = false
+    const forked = {
+      findOne: async () => { throw new Error('default findOne must not run when findRow is set') },
+      create: () => { throw new Error('should not create when findRow returns a row') },
+      persist: () => undefined,
+      flush: async () => undefined,
+    }
+    const em = { fork: () => forked }
+    const redo = makeCreateRedo<{ id: string; deletedAt?: Date | null }, { id: string }>({
+      entityClass: class {} as never,
+      buildResult: (entity) => ({ id: entity.id }),
+      findRow: async ({ id }) => { findRowCalled = true; return id === 'row-1' ? (surviving as never) : null },
+    })
+    await redo({ input: {}, ctx: buildContext(em), logEntry: { snapshotAfter: { id: 'row-1' } } as never })
+    expect(findRowCalled).toBe(true)
+    expect(surviving.deletedAt).toBeNull()
+  })
+
+  it('passes logEntry to afterRestore', async () => {
+    let seenLogEntry: unknown = null
+    const forked = {
+      findOne: async () => null,
+      create: (_cls: unknown, data: Record<string, unknown>) => ({ ...data }),
+      persist: () => undefined,
+      flush: async () => undefined,
+    }
+    const em = { fork: () => forked }
+    const redo = makeCreateRedo<{ id: string }, { id: string }>({
+      entityClass: class {} as never,
+      buildResult: (entity) => ({ id: entity.id }),
+      afterRestore: async ({ logEntry }) => { seenLogEntry = logEntry },
+    })
+    const logEntry = { snapshotAfter: { id: 'row-1' }, resourceId: 'row-1' }
+    await redo({ input: {}, ctx: buildContext(em), logEntry: logEntry as never })
+    expect(seenLogEntry).toBe(logEntry)
+  })
+
+  it('wraps the restore in a transaction when transaction is true', async () => {
+    const order: string[] = []
+    const forked = {
+      isInTransaction: () => false,
+      begin: async () => { order.push('begin') },
+      commit: async () => { order.push('commit') },
+      rollback: async () => { order.push('rollback') },
+      getUnitOfWork: () => ({ getChangeSets: () => [] }),
+      findOne: async () => null,
+      create: (_cls: unknown, data: Record<string, unknown>) => { order.push('create'); return { ...data } },
+      persist: () => undefined,
+      flush: async () => { order.push('flush') },
+    }
+    const em = { fork: () => forked }
+    const redo = makeCreateRedo<{ id: string }, { id: string }>({
+      entityClass: class {} as never,
+      buildResult: (entity) => ({ id: entity.id }),
+      transaction: true,
+    })
+    await redo({ input: {}, ctx: buildContext(em), logEntry: { snapshotAfter: { id: 'row-1' } } as never })
+    expect(order[0]).toBe('begin')
+    expect(order).toContain('create')
+    expect(order[order.length - 1]).toBe('commit')
+    expect(order).not.toContain('rollback')
+  })
+
+  it('runs afterRestore inside the transaction before commit when transaction is true', async () => {
+    const order: string[] = []
+    const forked = {
+      isInTransaction: () => false,
+      begin: async () => { order.push('begin') },
+      commit: async () => { order.push('commit') },
+      rollback: async () => { order.push('rollback') },
+      getUnitOfWork: () => ({ getChangeSets: () => [] }),
+      findOne: async () => null,
+      create: (_cls: unknown, data: Record<string, unknown>) => { order.push('create'); return { ...data } },
+      persist: () => undefined,
+      flush: async () => { order.push('flush') },
+    }
+    const em = { fork: () => forked }
+    const redo = makeCreateRedo<{ id: string }, { id: string }>({
+      entityClass: class {} as never,
+      buildResult: (entity) => ({ id: entity.id }),
+      transaction: true,
+      afterRestore: async () => { order.push('afterRestore') },
+    })
+    await redo({ input: {}, ctx: buildContext(em), logEntry: { snapshotAfter: { id: 'row-1' } } as never })
+    expect(order).toEqual(['begin', 'create', 'flush', 'afterRestore', 'flush', 'commit'])
+  })
+
+  it('maps a Postgres unique-constraint violation thrown during flush to a 409 conflict', async () => {
+    const uniqueError = Object.assign(new Error('duplicate key value violates unique constraint'), { code: '23505' })
+    const forked = {
+      findOne: async () => null,
+      create: (_cls: unknown, data: Record<string, unknown>) => ({ ...data }),
+      persist: () => undefined,
+      flush: async () => { throw uniqueError },
+    }
+    const em = { fork: () => forked }
+    const redo = makeCreateRedo<{ id: string }, { id: string }>({
+      entityClass: class {} as never,
+      buildResult: (entity) => ({ id: entity.id }),
+    })
+    const logEntry = { snapshotAfter: { id: 'row-1' } }
+    await expect(redo({ input: {}, ctx: buildContext(em), logEntry: logEntry as never })).rejects.toMatchObject({
+      status: 409,
+    })
+  })
+
+  it('propagates a non-unique flush error unchanged', async () => {
+    const otherError = Object.assign(new Error('some other failure'), { code: '23503' })
+    const forked = {
+      findOne: async () => null,
+      create: (_cls: unknown, data: Record<string, unknown>) => ({ ...data }),
+      persist: () => undefined,
+      flush: async () => { throw otherError },
+    }
+    const em = { fork: () => forked }
+    const redo = makeCreateRedo<{ id: string }, { id: string }>({
+      entityClass: class {} as never,
+      buildResult: (entity) => ({ id: entity.id }),
+    })
+    const logEntry = { snapshotAfter: { id: 'row-1' } }
+    await expect(redo({ input: {}, ctx: buildContext(em), logEntry: logEntry as never })).rejects.toBe(otherError)
+  })
+
+  it('defaults getSnapshotId to snapshot.id and restores a surviving row in place', async () => {
+    const surviving: Record<string, unknown> = { id: 'row-1', deletedAt: new Date(), isActive: false }
+    const forked = {
+      findOne: async () => surviving,
+      create: () => {
+        throw new Error('should not create when row survives')
+      },
+      persist: () => undefined,
+      flush: async () => undefined,
+    }
+    const em = { fork: () => forked }
+    const redo = makeCreateRedo<{ id: string; deletedAt?: Date | null; isActive?: boolean }, { id: string; isActive: boolean }>({
+      entityClass: class {} as never,
+      buildResult: (entity) => ({ id: entity.id, isActive: entity.isActive }),
+    })
+    const logEntry = { snapshotAfter: { id: 'row-1', isActive: true } }
+    const result = await redo({ input: {}, ctx: buildContext(em), logEntry: logEntry as never })
+    expect(result).toEqual({ id: 'row-1', isActive: true })
+    expect(surviving.deletedAt).toBeNull()
+    expect(surviving.isActive).toBe(true)
+  })
+})

package/src/lib/commands/__tests__/runCrudCommandWrite.test.ts

@@ -0,0 +1,390 @@
+import { runCrudCommandWrite } from '../runCrudCommandWrite'
+
+type FakeEntityManager = {
+  flush: jest.Mock<Promise<void>, []>
+  begin: jest.Mock<Promise<void>, []>
+  commit: jest.Mock<Promise<void>, []>
+  rollback: jest.Mock<Promise<void>, []>
+  fork: jest.Mock<FakeEntityManager, []>
+}
+
+type FakeDataEngine = {
+  setCustomFields: jest.Mock<Promise<void>, [unknown]>
+  markOrmEntityChange: jest.Mock<void, [unknown]>
+}
+
+function createFakeEm(): FakeEntityManager {
+  const em: FakeEntityManager = {
+    flush: jest.fn().mockResolvedValue(undefined),
+    begin: jest.fn().mockResolvedValue(undefined),
+    commit: jest.fn().mockResolvedValue(undefined),
+    rollback: jest.fn().mockResolvedValue(undefined),
+    fork: jest.fn(),
+  }
+  em.fork.mockReturnValue(em)
+  return em
+}
+
+function createFakeDataEngine(): FakeDataEngine {
+  return {
+    setCustomFields: jest.fn().mockResolvedValue(undefined),
+    markOrmEntityChange: jest.fn(),
+  }
+}
+
+function createCtx(em: FakeEntityManager, de: FakeDataEngine) {
+  return {
+    container: {
+      resolve: jest.fn((token: string) => {
+        if (token === 'em') return em
+        if (token === 'dataEngine') return de
+        throw new Error(`unexpected resolve(${token})`)
+      }),
+    },
+    auth: null,
+    organizationScope: null,
+    selectedOrganizationId: null,
+    organizationIds: null,
+  } as any
+}
+
+const baseScope = { tenantId: 't1', organizationId: 'o1' } as const
+const entity = { id: 'rec-1', tenantId: 't1', organizationId: 'o1' }
+const identifiers = { id: 'rec-1', tenantId: 't1', organizationId: 'o1' }
+const events = { module: 'customers', entity: 'deal', persistent: true } as const
+const indexer = { entityType: 'customers:customer_deal' } as const
+
+describe('runCrudCommandWrite', () => {
+  it('runs phases on the helper-forked EM, then writes custom fields, then queues exactly one CRUD side-effect (AC1 + AC4)', async () => {
+    const rootEm = createFakeEm()
+    const forked = createFakeEm()
+    rootEm.fork.mockReturnValue(forked)
+    const de = createFakeDataEngine()
+    const ctx = createCtx(rootEm, de)
+    const events_called: string[] = []
+    let observedPhaseEm: FakeEntityManager | null = null
+
+    await runCrudCommandWrite({
+      ctx,
+      entityId: 'customers:customer_deal',
+      action: 'updated',
+      scope: baseScope,
+      customFields: { priority: 3 },
+      events,
+      indexer,
+      sideEffect: () => ({ entity, identifiers }),
+      phases: [
+        async ({ em }) => {
+          events_called.push('phase')
+          observedPhaseEm = em as unknown as FakeEntityManager
+        },
+      ],
+    })
+
+    expect(rootEm.fork).toHaveBeenCalledTimes(1)
+    expect(observedPhaseEm).toBe(forked)
+    expect(forked.begin).toHaveBeenCalledTimes(1)
+    expect(forked.flush).toHaveBeenCalledTimes(1)
+    expect(forked.commit).toHaveBeenCalledTimes(1)
+    expect(forked.rollback).not.toHaveBeenCalled()
+
+    expect(de.setCustomFields).toHaveBeenCalledTimes(1)
+    expect(de.setCustomFields).toHaveBeenCalledWith(
+      expect.objectContaining({
+        entityId: 'customers:customer_deal',
+        recordId: 'rec-1',
+        tenantId: 't1',
+        organizationId: 'o1',
+        values: { priority: 3 },
+        notify: false,
+      }),
+    )
+
+    expect(de.markOrmEntityChange).toHaveBeenCalledTimes(1)
+    expect(de.markOrmEntityChange).toHaveBeenCalledWith({
+      action: 'updated',
+      entity,
+      identifiers,
+      syncOrigin: null,
+      events,
+      indexer,
+    })
+
+    // Order: setCustomFields must complete before markOrmEntityChange is queued
+    const customFieldsOrder = de.setCustomFields.mock.invocationCallOrder[0]
+    const markOrder = de.markOrmEntityChange.mock.invocationCallOrder[0]
+    expect(customFieldsOrder).toBeLessThan(markOrder)
+  })
+
+  it('skips setCustomFields when customFields is undefined but still queues the side-effect', async () => {
+    const em = createFakeEm()
+    const de = createFakeDataEngine()
+    const ctx = createCtx(em, de)
+
+    await runCrudCommandWrite({
+      ctx,
+      entityId: 'customers:customer_deal',
+      action: 'created',
+      scope: baseScope,
+      sideEffect: () => ({ entity, identifiers }),
+      phases: [() => {}],
+    })
+
+    expect(de.setCustomFields).not.toHaveBeenCalled()
+    expect(de.markOrmEntityChange).toHaveBeenCalledTimes(1)
+  })
+
+  it('skips setCustomFields when customFields is an empty object', async () => {
+    const em = createFakeEm()
+    const de = createFakeDataEngine()
+    const ctx = createCtx(em, de)
+
+    await runCrudCommandWrite({
+      ctx,
+      entityId: 'customers:customer_deal',
+      action: 'updated',
+      scope: baseScope,
+      customFields: {},
+      sideEffect: () => ({ entity, identifiers }),
+      phases: [() => {}],
+    })
+
+    expect(de.setCustomFields).not.toHaveBeenCalled()
+    expect(de.markOrmEntityChange).toHaveBeenCalledTimes(1)
+  })
+
+  it('does NOT emit side-effects when a phase throws (AC2)', async () => {
+    const em = createFakeEm()
+    const de = createFakeDataEngine()
+    const ctx = createCtx(em, de)
+    const failure = new Error('phase-failure')
+
+    await expect(
+      runCrudCommandWrite({
+        ctx,
+        entityId: 'customers:customer_deal',
+        action: 'updated',
+        scope: baseScope,
+        customFields: { priority: 3 },
+        events,
+        indexer,
+        sideEffect: () => ({ entity, identifiers }),
+        phases: [
+          () => {
+            throw failure
+          },
+        ],
+      }),
+    ).rejects.toBe(failure)
+
+    expect(em.begin).toHaveBeenCalledTimes(1)
+    expect(em.rollback).toHaveBeenCalledTimes(1)
+    expect(em.flush).not.toHaveBeenCalled()
+    expect(em.commit).not.toHaveBeenCalled()
+    expect(de.setCustomFields).not.toHaveBeenCalled()
+    expect(de.markOrmEntityChange).not.toHaveBeenCalled()
+  })
+
+  it('does NOT emit side-effects when setCustomFields throws (AC3)', async () => {
+    const em = createFakeEm()
+    const de = createFakeDataEngine()
+    const ctx = createCtx(em, de)
+    const failure = new Error('custom-field-failure')
+    de.setCustomFields.mockRejectedValueOnce(failure)
+
+    await expect(
+      runCrudCommandWrite({
+        ctx,
+        entityId: 'customers:customer_deal',
+        action: 'updated',
+        scope: baseScope,
+        customFields: { priority: 3 },
+        events,
+        indexer,
+        sideEffect: () => ({ entity, identifiers }),
+        phases: [() => {}],
+      }),
+    ).rejects.toBe(failure)
+
+    expect(em.flush).toHaveBeenCalledTimes(1)
+    expect(em.commit).toHaveBeenCalledTimes(1)
+    expect(de.setCustomFields).toHaveBeenCalledTimes(1)
+    expect(de.markOrmEntityChange).not.toHaveBeenCalled()
+  })
+
+  it('uses a caller-supplied EM instead of forking a new one when opts.em is provided', async () => {
+    const rootEm = createFakeEm()
+    const callerEm = createFakeEm()
+    const de = createFakeDataEngine()
+    const ctx = createCtx(rootEm, de)
+    let observedPhaseEm: FakeEntityManager | null = null
+
+    await runCrudCommandWrite({
+      ctx,
+      entityId: 'customers:customer_deal',
+      action: 'updated',
+      scope: baseScope,
+      em: callerEm as any,
+      sideEffect: () => ({ entity, identifiers }),
+      phases: [
+        ({ em }) => {
+          observedPhaseEm = em as unknown as FakeEntityManager
+        },
+      ],
+    })
+
+    expect(rootEm.fork).not.toHaveBeenCalled()
+    expect(observedPhaseEm).toBe(callerEm)
+    expect(callerEm.begin).toHaveBeenCalledTimes(1)
+    expect(callerEm.flush).toHaveBeenCalledTimes(1)
+    expect(callerEm.commit).toHaveBeenCalledTimes(1)
+  })
+
+  it('uses a caller-supplied DataEngine instead of resolving from container', async () => {
+    const em = createFakeEm()
+    const containerDe = createFakeDataEngine()
+    const callerDe = createFakeDataEngine()
+    const ctx = createCtx(em, containerDe)
+
+    await runCrudCommandWrite({
+      ctx,
+      entityId: 'customers:customer_deal',
+      action: 'updated',
+      scope: baseScope,
+      customFields: { priority: 3 },
+      dataEngine: callerDe as any,
+      sideEffect: () => ({ entity, identifiers }),
+      phases: [() => {}],
+    })
+
+    expect(callerDe.setCustomFields).toHaveBeenCalledTimes(1)
+    expect(callerDe.markOrmEntityChange).toHaveBeenCalledTimes(1)
+    expect(containerDe.setCustomFields).not.toHaveBeenCalled()
+    expect(containerDe.markOrmEntityChange).not.toHaveBeenCalled()
+  })
+
+  it('evaluates sideEffect lazily after phases commit (supports closure-captured entities created inside a phase)', async () => {
+    const em = createFakeEm()
+    const de = createFakeDataEngine()
+    const ctx = createCtx(em, de)
+    let createdEntity: { id: string; tenantId: string; organizationId: string } | null = null
+    const sideEffectSpy = jest.fn(() => ({
+      entity: createdEntity!,
+      identifiers: { id: createdEntity!.id, tenantId: 't1', organizationId: 'o1' },
+    }))
+
+    await runCrudCommandWrite({
+      ctx,
+      entityId: 'customers:customer_deal',
+      action: 'created',
+      scope: baseScope,
+      sideEffect: sideEffectSpy,
+      phases: [
+        () => {
+          createdEntity = { id: 'fresh-id', tenantId: 't1', organizationId: 'o1' }
+        },
+      ],
+    })
+
+    expect(sideEffectSpy).toHaveBeenCalledTimes(1)
+    expect(de.markOrmEntityChange).toHaveBeenCalledWith(
+      expect.objectContaining({
+        entity: { id: 'fresh-id', tenantId: 't1', organizationId: 'o1' },
+        identifiers: { id: 'fresh-id', tenantId: 't1', organizationId: 'o1' },
+      }),
+    )
+  })
+
+  it('runs phases sequentially in a single transaction, flushing per phase (SPEC-018)', async () => {
+    const em = createFakeEm()
+    const de = createFakeDataEngine()
+    const ctx = createCtx(em, de)
+    const order: string[] = []
+
+    await runCrudCommandWrite({
+      ctx,
+      entityId: 'customers:customer_deal',
+      action: 'updated',
+      scope: baseScope,
+      sideEffect: () => ({ entity, identifiers }),
+      phases: [
+        async () => {
+          await Promise.resolve()
+          order.push('phase-1')
+        },
+        () => {
+          order.push('phase-2')
+        },
+      ],
+    })
+
+    expect(order).toEqual(['phase-1', 'phase-2'])
+    expect(em.begin).toHaveBeenCalledTimes(1)
+    // SPEC-018: withAtomicFlush flushes after each phase (one per phase) so a
+    // later phase's reads see the prior phase's mutations without UoW reset.
+    expect(em.flush).toHaveBeenCalledTimes(2)
+    expect(em.commit).toHaveBeenCalledTimes(1)
+  })
+
+  it('honours transaction:false (no begin/commit, single flush still happens)', async () => {
+    const em = createFakeEm()
+    const de = createFakeDataEngine()
+    const ctx = createCtx(em, de)
+
+    await runCrudCommandWrite({
+      ctx,
+      entityId: 'customers:customer_deal',
+      action: 'updated',
+      scope: baseScope,
+      transaction: false,
+      sideEffect: () => ({ entity, identifiers }),
+      phases: [() => {}],
+    })
+
+    expect(em.begin).not.toHaveBeenCalled()
+    expect(em.commit).not.toHaveBeenCalled()
+    expect(em.flush).toHaveBeenCalledTimes(1)
+    expect(de.markOrmEntityChange).toHaveBeenCalledTimes(1)
+  })
+
+  it('forwards syncOrigin to the side-effect emit', async () => {
+    const em = createFakeEm()
+    const de = createFakeDataEngine()
+    const ctx = createCtx(em, de)
+
+    await runCrudCommandWrite({
+      ctx,
+      entityId: 'customers:customer_deal',
+      action: 'updated',
+      scope: baseScope,
+      syncOrigin: 'sync_excel',
+      sideEffect: () => ({ entity, identifiers }),
+      phases: [() => {}],
+    })
+
+    expect(de.markOrmEntityChange).toHaveBeenCalledWith(
+      expect.objectContaining({ syncOrigin: 'sync_excel' }),
+    )
+  })
+
+  it('passes notifyCustomFields:true through to setCustomFields when requested', async () => {
+    const em = createFakeEm()
+    const de = createFakeDataEngine()
+    const ctx = createCtx(em, de)
+
+    await runCrudCommandWrite({
+      ctx,
+      entityId: 'customers:customer_deal',
+      action: 'updated',
+      scope: baseScope,
+      customFields: { priority: 3 },
+      notifyCustomFields: true,
+      sideEffect: () => ({ entity, identifiers }),
+      phases: [() => {}],
+    })
+
+    expect(de.setCustomFields).toHaveBeenCalledWith(
+      expect.objectContaining({ notify: true }),
+    )
+  })
+})