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

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

@@ -83,4 +83,52 @@ describe('ensureOrganizationScope', () => {
       expect(() => ensureOrganizationScope(ctx, 'org-b')).toThrow(CrudHttpError)
     })
   })
+
+  describe('fail-open-by-omission hardening (#2441)', () => {
+    const originalNodeEnv = process.env.NODE_ENV
+    const originalStrict = process.env.OM_ENFORCE_ORG_SCOPE_STRICT
+    let warnSpy: jest.SpyInstance
+
+    beforeEach(() => {
+      // The scope loggers suppress output under NODE_ENV==='test'; flip it so the
+      // observability signal becomes assertable, then restore in afterEach.
+      process.env.NODE_ENV = 'development'
+      warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {})
+    })
+
+    afterEach(() => {
+      warnSpy.mockRestore()
+      if (originalNodeEnv === undefined) delete process.env.NODE_ENV
+      else process.env.NODE_ENV = originalNodeEnv
+      if (originalStrict === undefined) delete process.env.OM_ENFORCE_ORG_SCOPE_STRICT
+      else process.env.OM_ENFORCE_ORG_SCOPE_STRICT = originalStrict
+    })
+
+    it('emits an observability warning when scope and currentOrg are both null', () => {
+      delete process.env.OM_ENFORCE_ORG_SCOPE_STRICT
+      const ctx = buildCtx({ orgId: null, selectedOrganizationId: null, organizationScope: null })
+      expect(() => ensureOrganizationScope(ctx, 'org-b')).not.toThrow()
+      expect(warnSpy).toHaveBeenCalledWith(
+        '[scope] Unscoped organization command executed without organization context',
+        expect.objectContaining({ targetOrganizationId: 'org-b', strictEnforcement: false })
+      )
+    })
+
+    it('throws when OM_ENFORCE_ORG_SCOPE_STRICT is enabled', () => {
+      process.env.OM_ENFORCE_ORG_SCOPE_STRICT = 'true'
+      const ctx = buildCtx({ orgId: null, selectedOrganizationId: null, organizationScope: null })
+      expect(() => ensureOrganizationScope(ctx, 'org-b')).toThrow(CrudHttpError)
+      expect(warnSpy).toHaveBeenCalledWith(
+        '[scope] Unscoped organization command executed without organization context',
+        expect.objectContaining({ targetOrganizationId: 'org-b', strictEnforcement: true })
+      )
+    })
+
+    it('does not warn or throw when there is no target organization to validate', () => {
+      delete process.env.OM_ENFORCE_ORG_SCOPE_STRICT
+      const ctx = buildCtx({ orgId: null, selectedOrganizationId: null, organizationScope: null })
+      expect(() => ensureOrganizationScope(ctx, '')).not.toThrow()
+      expect(warnSpy).not.toHaveBeenCalled()
+    })
+  })
 })

package/src/lib/commands/command-bus.ts

@@ -230,7 +230,11 @@ export class CommandBus {
     }
 
     const snapshots = await this.prepareSnapshots(handler, effectiveOptions)
-    const result = await handler.execute(effectiveOptions.input, effectiveOptions.ctx)
+    const redoLogEntry = effectiveOptions.redoLogEntry ?? null
+    const result =
+      redoLogEntry && typeof handler.redo === 'function'
+        ? await handler.redo({ input: effectiveOptions.input, ctx: effectiveOptions.ctx, logEntry: redoLogEntry })
+        : await handler.execute(effectiveOptions.input, effectiveOptions.ctx)
     const afterSnapshot = await this.captureAfter(handler, effectiveOptions, result)
     const snapshotsWithAfter = { ...snapshots, after: afterSnapshot }
     const logMeta = await this.buildLog(handler, effectiveOptions, result, snapshotsWithAfter)
@@ -302,53 +306,67 @@ export class CommandBus {
       throw new Error(`Command ${log.commandId} is not undoable`)
     }
 
-    // Run beforeUndo command interceptors
-    const allInterceptors = getAllCommandInterceptorInstances()
-    let undoInterceptorMetadata = new Map<string, Record<string, unknown>>()
-    const userFeatures = allInterceptors.length
-      ? await this.resolveUserFeaturesForInterceptors(ctx)
-      : []
-    if (allInterceptors.length) {
-      const undoCtx = { input: log.commandPayload, logEntry: log, undoToken }
-      const interceptorCtx: CommandInterceptorContext = {
-        commandId: log.commandId,
-        auth: ctx.auth ?? null,
-        selectedOrganizationId: ctx.selectedOrganizationId ?? ctx.auth?.orgId ?? null,
-        container: ctx.container,
-      }
-      const beforeResult = await runCommandInterceptorsBeforeUndo(
-        allInterceptors, log.commandId, undoCtx, interceptorCtx, userFeatures,
-      )
-      if (!beforeResult.ok) {
-        throw new CommandInterceptorError(beforeResult.error!.message)
-      }
-      undoInterceptorMetadata = beforeResult.metadataByInterceptor
-    }
+    // Atomically claim the action-log row before running any undo side effects.
+    // Two concurrent requests holding the same undo token can both pass
+    // findByUndoToken/executionState checks; the compare-and-set below ensures
+    // only one transitions `done` -> `undoing` and proceeds, the other bails out.
+    const claimed = await service.claimForUndo(log.id)
+    if (!claimed) throw new Error('Undo token already consumed')
 
-    await handler.undo({
-      input: log.commandPayload as Parameters<NonNullable<typeof handler.undo>>[0]['input'],
-      ctx,
-      logEntry: log,
-    })
-    await service.markUndone(log.id, this.buildUndoTraceLog(log, ctx))
+    try {
+      // Run beforeUndo command interceptors
+      const allInterceptors = getAllCommandInterceptorInstances()
+      let undoInterceptorMetadata = new Map<string, Record<string, unknown>>()
+      const userFeatures = allInterceptors.length
+        ? await this.resolveUserFeaturesForInterceptors(ctx)
+        : []
+      if (allInterceptors.length) {
+        const undoCtx = { input: log.commandPayload, logEntry: log, undoToken }
+        const interceptorCtx: CommandInterceptorContext = {
+          commandId: log.commandId,
+          auth: ctx.auth ?? null,
+          selectedOrganizationId: ctx.selectedOrganizationId ?? ctx.auth?.orgId ?? null,
+          container: ctx.container,
+        }
+        const beforeResult = await runCommandInterceptorsBeforeUndo(
+          allInterceptors, log.commandId, undoCtx, interceptorCtx, userFeatures,
+        )
+        if (!beforeResult.ok) {
+          throw new CommandInterceptorError(beforeResult.error!.message)
+        }
+        undoInterceptorMetadata = beforeResult.metadataByInterceptor
+      }
 
-    // Run afterUndo command interceptors
-    if (allInterceptors.length) {
-      const undoCtx = { input: log.commandPayload, logEntry: log, undoToken }
-      const interceptorCtx: CommandInterceptorContext = {
-        commandId: log.commandId,
-        auth: ctx.auth ?? null,
-        selectedOrganizationId: ctx.selectedOrganizationId ?? ctx.auth?.orgId ?? null,
-        container: ctx.container,
+      await handler.undo({
+        input: log.commandPayload as Parameters<NonNullable<typeof handler.undo>>[0]['input'],
+        ctx,
+        logEntry: log,
+      })
+      await service.markUndone(log.id, this.buildUndoTraceLog(log, ctx))
+
+      // Run afterUndo command interceptors
+      if (allInterceptors.length) {
+        const undoCtx = { input: log.commandPayload, logEntry: log, undoToken }
+        const interceptorCtx: CommandInterceptorContext = {
+          commandId: log.commandId,
+          auth: ctx.auth ?? null,
+          selectedOrganizationId: ctx.selectedOrganizationId ?? ctx.auth?.orgId ?? null,
+          container: ctx.container,
+        }
+        await runCommandInterceptorsAfterUndo(
+          allInterceptors, log.commandId, undoCtx, interceptorCtx,
+          userFeatures, undoInterceptorMetadata,
+        )
       }
-      await runCommandInterceptorsAfterUndo(
-        allInterceptors, log.commandId, undoCtx, interceptorCtx,
-        userFeatures, undoInterceptorMetadata,
-      )
-    }
 
-    await this.invalidateCacheAfterUndo(log, ctx)
-    await this.flushCrudSideEffects(ctx.container)
+      await this.invalidateCacheAfterUndo(log, ctx)
+      await this.flushCrudSideEffects(ctx.container)
+    } catch (err) {
+      // Undo failed after claiming the row — release the claim so the action
+      // remains retryable instead of being stranded in the `undoing` state.
+      await service.releaseUndoClaim(log.id).catch(() => {})
+      throw err
+    }
   }
 
   private buildUndoTraceLog(log: ActionLog, ctx: CommandRuntimeContext): ActionLogCreateInput | undefined {

package/src/lib/commands/flush.ts

@@ -19,11 +19,68 @@ export type AtomicFlushOptions = {
    */
   isolationLevel?: IsolationLevel
   /**
-   * Optional label for diagnostics. Currently informational only.
+   * Optional label for diagnostics. Surfaced in the commit-boundary guard's
+   * dev warning when a pending change set had to be flushed defensively, so the
+   * offending command is identifiable.
    */
   label?: string
 }
 
+type UnitOfWorkProbe = {
+  computeChangeSets?: () => void
+  getChangeSets?: () => ReadonlyArray<unknown>
+}
+
+type FlushGuardEntityManager = {
+  flush: () => Promise<void>
+  getUnitOfWork?: () => UnitOfWorkProbe | undefined
+}
+
+/**
+ * Commit-boundary safety net.
+ *
+ * After every phase has run and flushed, this asserts the UnitOfWork holds NO
+ * pending change sets before the transaction commits. If it still does — a phase
+ * mutated a managed entity AFTER its own per-phase flush boundary (the exact
+ * shape that silently drops a scalar UPDATE under MikroORM v7) — the guard
+ * flushes those changes defensively so the write can never be lost, and warns in
+ * non-production so the latent ordering bug gets fixed at the source.
+ *
+ * Detection is best-effort and fail-safe: it only issues the extra flush when it
+ * can PROVE the UnitOfWork is dirty (`computeChangeSets()` → `getChangeSets()`
+ * non-empty). On EntityManagers that don't expose a UnitOfWork (partial/mock EMs
+ * in unit tests) it does nothing — the per-phase flushes already ran — so it
+ * never double-flushes a clean unit of work and never changes flush counts for
+ * callers that were already correct.
+ */
+async function flushPendingChangesGuard(
+  em: FlushGuardEntityManager,
+  label?: string,
+): Promise<void> {
+  let pendingCount = -1
+  try {
+    const uow = typeof em.getUnitOfWork === 'function' ? em.getUnitOfWork() : undefined
+    if (uow && typeof uow.computeChangeSets === 'function' && typeof uow.getChangeSets === 'function') {
+      uow.computeChangeSets()
+      pendingCount = uow.getChangeSets().length
+    }
+  } catch {
+    // Probing the UnitOfWork must never break a command; fall back to "unknown".
+    pendingCount = -1
+  }
+
+  if (pendingCount > 0) {
+    await em.flush()
+    if (process.env.NODE_ENV !== 'production') {
+      const where = label ? ` (${label})` : ''
+      console.warn(
+        `[withAtomicFlush]${where}: ${pendingCount} pending change-set(s) remained at the commit boundary and were flushed defensively. ` +
+          'A phase mutated a managed entity after its flush boundary — split the mutation and any dependent read/sync into separate phases so the change is never at risk of being dropped.',
+      )
+    }
+  }
+}
+
 /**
  * Wraps multiple mutation phases in a single atomic flush.
  *
@@ -67,11 +124,31 @@ export async function withAtomicFlush(
 ): Promise<void> {
   if (phases.length === 0) return
 
+  // SPEC-018: the phases ARE flush boundaries — flush AFTER EACH phase, not once
+  // at the end. A phase's scalar mutations must be persisted before the NEXT
+  // phase runs any query (em.find / findOne / nativeUpdate / a sync helper);
+  // otherwise the interleaved read resets MikroORM v7's identity-map changeset
+  // and the pending scalar UPDATE is silently dropped (the #2453 family). This
+  // is the framework-level guarantee that lets commands keep mutations and the
+  // reads that depend on them in separate phases without hand-rolled flushes.
+  //
+  // Atomicity is preserved: when `transaction: true` (or an ambient transaction
+  // is joined), each `em.flush()` only emits SQL inside the open transaction —
+  // the single commit/rollback below still spans every phase, so a later-phase
+  // failure rolls back all earlier phases. Without a transaction the helper
+  // keeps its documented "each phase flushes independently" behavior.
+  //
+  // Commit-boundary guarantee: after the last phase flush, `flushPendingChangesGuard`
+  // re-checks the UnitOfWork and flushes once more if ANY pending change set remains
+  // (a phase mutated state after its boundary). The transaction therefore can never
+  // commit with unflushed work — if a per-phase flush was missed "for some reason",
+  // the guard catches it inside the same transaction and warns in dev.
   const runPhasesAndFlush = async () => {
     for (const phase of phases) {
       await phase()
+      await em.flush()
     }
-    await em.flush()
+    await flushPendingChangesGuard(em as unknown as FlushGuardEntityManager, options?.label)
   }
 
   if (!options?.transaction) {

package/src/lib/commands/index.ts

@@ -3,4 +3,13 @@ export * from './registry'
 export { CommandBus } from './command-bus'
 export * from './customFieldSnapshots'
 export * from './undo'
+export * from './redo'
 export { CommandInterceptorError } from './errors'
+export {
+  runCrudCommandWrite,
+  type RunCrudCommandWriteOptions,
+  type RunCrudCommandWriteResult,
+  type CrudCommandWritePhase,
+  type CrudCommandWriteScope,
+  type CrudCommandWriteSideEffectTarget,
+} from './runCrudCommandWrite'

package/src/lib/commands/redo.ts

@@ -0,0 +1,235 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { CommandRuntimeContext, CommandUndoLogEntry } from './types'
+import type { DataEngine } from '@open-mercato/shared/lib/data/engine'
+import type { CrudEventsConfig, CrudIndexerConfig } from '@open-mercato/shared/lib/crud/types'
+import { CrudHttpError, conflict, isUniqueViolation } from '@open-mercato/shared/lib/crud/errors'
+import { extractUndoPayload, type UndoPayload } from './undo'
+import { emitCrudSideEffects } from './helpers'
+import { withAtomicFlush } from './flush'
+
+type EntityClass<T> = abstract new (...args: never[]) => T
+
+type ScopedSoftDeletable = {
+  id: string
+  organizationId?: string | null
+  tenantId?: string | null
+  deletedAt?: Date | null
+  isActive?: boolean
+}
+
+/** Snapshot keys revived from ISO strings to `Date` when no explicit `dateFields` is given. */
+const DEFAULT_SNAPSHOT_DATE_FIELDS = ['createdAt', 'updatedAt', 'deletedAt'] as const
+
+/**
+ * Turn an after-snapshot into a create seed by shallow-cloning it and reviving the
+ * declared date fields from ISO strings back to `Date`. Single-row snapshots are a
+ * faithful serialized row whose keys already equal entity property names, so the
+ * snapshot doubles as the seed once dates are revived — no per-command mapping needed.
+ */
+export function reviveSnapshotSeed(
+  snapshot: Record<string, unknown>,
+  dateFields: readonly string[] = DEFAULT_SNAPSHOT_DATE_FIELDS,
+): Record<string, unknown> {
+  const seed: Record<string, unknown> = { ...snapshot }
+  for (const field of dateFields) {
+    const value = seed[field]
+    if (typeof value === 'string') seed[field] = new Date(value)
+  }
+  return seed
+}
+
+/**
+ * Serialize a persisted row into a plain after-snapshot object: pick `fields` from
+ * the entity and convert the declared `dateFields` from `Date` to ISO strings. Use
+ * for single-row snapshot loaders that are a clean 1:1 column copy; loaders that
+ * shape nested/related data keep their bespoke mapping.
+ */
+export function serializeRowSnapshot<TEntity extends Record<string, unknown>>(
+  entity: TEntity,
+  fields: readonly string[],
+  dateFields: readonly string[] = DEFAULT_SNAPSHOT_DATE_FIELDS,
+): Record<string, unknown> {
+  const snapshot: Record<string, unknown> = {}
+  const dateFieldSet = new Set(dateFields)
+  for (const field of fields) {
+    const value = entity[field]
+    if (dateFieldSet.has(field)) {
+      snapshot[field] = value instanceof Date ? value.toISOString() : (value ?? null)
+    } else {
+      snapshot[field] = value ?? null
+    }
+  }
+  return snapshot
+}
+
+/**
+ * Resolve the after-snapshot a create command persisted for its action log, so a
+ * `redo` handler can re-materialize the original record. Reads the `undo.after`
+ * snapshot via {@link extractUndoPayload} and falls back to `snapshotAfter`.
+ */
+export function resolveRedoSnapshot<T>(logEntry: CommandUndoLogEntry | null | undefined): T | null {
+  if (!logEntry) return null
+  const undo = extractUndoPayload<UndoPayload<T>>(logEntry)
+  if (undo && undo.after != null) return undo.after as T
+  if (logEntry.snapshotAfter != null) return logEntry.snapshotAfter as T
+  return null
+}
+
+/**
+ * Re-materialize a single row that a create command produced, reusing its original
+ * id. If the row still exists (it was soft-deleted by undo), clears `deletedAt` and
+ * restores `isActive` from the seed. If it was hard-deleted, re-creates it from the
+ * seed (which MUST include the original `id`). This keeps redo idempotent on id so
+ * undo/redo snapshots and cross-references stay stable (issue #2506, invariant I6).
+ */
+export async function restoreCreatedRow<TEntity extends ScopedSoftDeletable>(
+  em: EntityManager,
+  entityClass: EntityClass<TEntity>,
+  id: string,
+  seedFromSnapshot: () => Record<string, unknown>,
+  findRow?: (em: EntityManager, id: string) => Promise<TEntity | null>,
+): Promise<TEntity> {
+  const existing = findRow
+    ? await findRow(em, id)
+    : ((await em.findOne(entityClass as never, { id } as never)) as TEntity | null)
+  if (existing) {
+    existing.deletedAt = null
+    const seed = seedFromSnapshot()
+    if (typeof seed.isActive === 'boolean') existing.isActive = seed.isActive
+    return existing
+  }
+  const record = em.create(entityClass as never, { ...seedFromSnapshot(), deletedAt: null } as never) as TEntity
+  em.persist(record as never)
+  return record
+}
+
+export type CreateRedoConfig<TEntity extends ScopedSoftDeletable, TSnapshot, TResult> = {
+  entityClass: EntityClass<TEntity>
+  /**
+   * Pulls the original primary id out of the after-snapshot. Defaults to
+   * `(snapshot) => snapshot.id`, which fits single-row snapshots whose top-level
+   * `id` is the row's primary key. Override only when the id lives elsewhere.
+   */
+  getSnapshotId?: (snapshot: TSnapshot) => string | null | undefined
+  /**
+   * Maps the after-snapshot back to a create seed; MUST include the original id.
+   * Defaults to {@link reviveSnapshotSeed} — the snapshot itself with `dateFields`
+   * revived to `Date`. Override only when the snapshot keys diverge from entity
+   * columns (e.g. nested shapes or derived columns).
+   */
+  seedFromSnapshot?: (snapshot: TSnapshot) => Record<string, unknown>
+  /**
+   * Snapshot keys to revive from ISO string to `Date` for the default seed.
+   * Defaults to `['createdAt', 'updatedAt', 'deletedAt']`; list additional date
+   * columns (e.g. `effectiveAt`, `returnedAt`) when the entity has them.
+   */
+  dateFields?: readonly string[]
+  /** Builds the command result (mirrors `execute`'s return), e.g. `(e) => ({ currencyId: e.id })`. */
+  buildResult: (entity: TEntity, snapshot: TSnapshot) => TResult
+  events?: CrudEventsConfig<any>
+  indexer?: CrudIndexerConfig<any>
+  /**
+   * Override how the existing row is looked up before restore. Defaults to
+   * `em.findOne(entityClass, { id })`. Pass a decryption-aware finder
+   * (`findOneWithDecryption`) for encrypted entities so the revive-in-place path
+   * sees the same row the rest of the module does.
+   */
+  findRow?: (args: { em: EntityManager; ctx: CommandRuntimeContext; id: string; snapshot: TSnapshot }) => Promise<TEntity | null>
+  /**
+   * Runs after the em fork, before the row is restored. Use to validate
+   * referenced relations (throw `CrudHttpError` to fail the redo) or resolve
+   * relation entities. Anything it returns is shallow-merged into the create
+   * seed (e.g. `{ entity: resolvedEntity }`), letting the seed reference a live
+   * relation instead of a raw id.
+   */
+  beforeRestore?: (args: {
+    em: EntityManager
+    ctx: CommandRuntimeContext
+    snapshot: TSnapshot
+  }) => Promise<Record<string, unknown> | void> | Record<string, unknown> | void
+  /** Optional extra side effects after the row is restored (e.g. query-index upserts, custom-field restore). */
+  afterRestore?: (args: {
+    em: EntityManager
+    ctx: CommandRuntimeContext
+    entity: TEntity
+    snapshot: TSnapshot
+    logEntry: CommandUndoLogEntry
+  }) => Promise<void> | void
+  /**
+   * Wrap the restore (create/revive + flush) in a single transaction via
+   * {@link withAtomicFlush}. Use when the create participated in a multi-phase
+   * atomic flush in `execute` and partial commits must be impossible.
+   */
+  transaction?: boolean
+}
+
+/**
+ * Build a create command's `redo` handler that restores the original row in place
+ * (reusing its id) instead of replaying `execute` and minting a new id. Wires the
+ * `created` side effects (events + query index) exactly like `execute`. Use this for
+ * single-row create commands; multi-entity creates implement `redo` by hand.
+ */
+export function makeCreateRedo<
+  TEntity extends ScopedSoftDeletable,
+  TSnapshot,
+  TInput = unknown,
+  TResult = unknown,
+>(config: CreateRedoConfig<TEntity, TSnapshot, TResult>) {
+  const getSnapshotId = config.getSnapshotId ?? ((snapshot: TSnapshot) => (snapshot as { id?: string | null }).id ?? null)
+  const seedFromSnapshot =
+    config.seedFromSnapshot ?? ((snapshot: TSnapshot) => reviveSnapshotSeed(snapshot as Record<string, unknown>, config.dateFields))
+  return async ({ ctx, logEntry }: { input: TInput; ctx: CommandRuntimeContext; logEntry: CommandUndoLogEntry }): Promise<TResult> => {
+    const snapshot = resolveRedoSnapshot<TSnapshot>(logEntry)
+    const id = snapshot ? getSnapshotId(snapshot) : (logEntry.resourceId ?? null)
+    if (!snapshot || !id) {
+      throw new CrudHttpError(400, { error: '[internal] redo snapshot unavailable for create command' })
+    }
+    const em = (ctx.container.resolve('em') as EntityManager).fork()
+    const overrides = config.beforeRestore ? await config.beforeRestore({ em, ctx, snapshot }) : undefined
+    const buildSeed = () => (overrides ? { ...seedFromSnapshot(snapshot), ...overrides } : seedFromSnapshot(snapshot))
+    const findRow = config.findRow
+      ? (forkedEm: EntityManager, rowId: string) => config.findRow!({ em: forkedEm, ctx, id: rowId, snapshot })
+      : undefined
+    let entity!: TEntity
+    const restorePhase = async () => {
+      entity = await restoreCreatedRow(em, config.entityClass, id, buildSeed, findRow)
+    }
+    const afterRestorePhase = async () => {
+      if (config.afterRestore) {
+        await config.afterRestore({ em, ctx, entity, snapshot, logEntry })
+      }
+    }
+    try {
+      if (config.transaction) {
+        const phases = config.afterRestore ? [restorePhase, afterRestorePhase] : [restorePhase]
+        await withAtomicFlush(em, phases, { transaction: true })
+      } else {
+        await restorePhase()
+        await em.flush()
+        await afterRestorePhase()
+      }
+    } catch (err) {
+      if (isUniqueViolation(err)) {
+        // [internal] prefix: this shared-lib helper has no `t(...)` context; the
+        // redo unique-collision is a rare developer-facing edge (the after-snapshot's
+        // unique key was re-taken since undo), surfaced via normal error handling.
+        throw conflict('[internal] Cannot redo: a record with the same unique key already exists.')
+      }
+      throw err
+    }
+    const dataEngine = ctx.container.resolve('dataEngine') as DataEngine
+    await emitCrudSideEffects({
+      dataEngine,
+      action: 'created',
+      entity,
+      identifiers: {
+        id,
+        organizationId: entity.organizationId ?? null,
+        tenantId: entity.tenantId ?? null,
+      },
+      events: config.events,
+      indexer: config.indexer,
+    })
+    return config.buildResult(entity, snapshot)
+  }
+}

package/src/lib/commands/runCrudCommandWrite.ts

@@ -0,0 +1,82 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { CommandRuntimeContext } from './types'
+import type { DataEngine } from '../data/engine'
+import type {
+  CrudEventAction,
+  CrudEventsConfig,
+  CrudIndexerConfig,
+  CrudEntityIdentifiers,
+} from '../crud/types'
+import { withAtomicFlush } from './flush'
+import { setCustomFieldsIfAny, emitCrudSideEffects } from './helpers'
+
+export type CrudCommandWritePhase = (args: { em: EntityManager }) => void | Promise<void>
+
+export type CrudCommandWriteSideEffectTarget<TEntity> = {
+  entity: TEntity
+  identifiers: CrudEntityIdentifiers
+}
+
+export type CrudCommandWriteScope = {
+  tenantId: string | null
+  organizationId: string | null
+}
+
+export type RunCrudCommandWriteOptions<TEntity> = {
+  ctx: CommandRuntimeContext
+  entityId: string
+  action: CrudEventAction
+  scope: CrudCommandWriteScope
+  phases: CrudCommandWritePhase[]
+  customFields?: Record<string, unknown>
+  notifyCustomFields?: boolean
+  events?: CrudEventsConfig<TEntity>
+  indexer?: CrudIndexerConfig<TEntity>
+  syncOrigin?: string | null
+  sideEffect: () => CrudCommandWriteSideEffectTarget<TEntity>
+  em?: EntityManager
+  transaction?: boolean
+  dataEngine?: DataEngine
+}
+
+export type RunCrudCommandWriteResult = { em: EntityManager }
+
+export async function runCrudCommandWrite<TEntity>(
+  opts: RunCrudCommandWriteOptions<TEntity>,
+): Promise<RunCrudCommandWriteResult> {
+  const em = opts.em ?? (opts.ctx.container.resolve('em') as EntityManager).fork()
+  const transaction = opts.transaction ?? true
+
+  await withAtomicFlush(
+    em,
+    opts.phases.map((phase) => () => phase({ em })),
+    { transaction },
+  )
+
+  const dataEngine = opts.dataEngine ?? (opts.ctx.container.resolve('dataEngine') as DataEngine)
+  const target = opts.sideEffect()
+
+  if (opts.customFields && Object.keys(opts.customFields).length > 0) {
+    await setCustomFieldsIfAny({
+      dataEngine,
+      entityId: opts.entityId,
+      recordId: target.identifiers.id,
+      tenantId: opts.scope.tenantId,
+      organizationId: opts.scope.organizationId,
+      values: opts.customFields,
+      notify: opts.notifyCustomFields ?? false,
+    })
+  }
+
+  await emitCrudSideEffects({
+    dataEngine,
+    action: opts.action,
+    entity: target.entity,
+    identifiers: target.identifiers,
+    syncOrigin: opts.syncOrigin ?? null,
+    events: opts.events,
+    indexer: opts.indexer,
+  })
+
+  return { em }
+}