@open-mercato/shared 0.6.5-develop.4534.1.b459babe6d → 0.6.5-develop.4544.1.71c003c861

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

@@ -19,9 +19,12 @@ function createFakeEm(overrides?: { inTransaction?: boolean }): FakeEntityManage
 }
 
 describe('withAtomicFlush', () => {
-  it('runs phases in order and flushes once at the end', async () => {
+  it('runs phases in order and flushes after each phase (SPEC-018 boundaries)', async () => {
     const em = createFakeEm()
     const calls: string[] = []
+    em.flush.mockImplementation(async () => {
+      calls.push('flush')
+    })
 
     await withAtomicFlush(em as any, [
       async () => {
@@ -37,14 +40,23 @@ describe('withAtomicFlush', () => {
       },
     ])
 
-    expect(calls).toEqual(['phase1-start', 'phase1-end', 'phase2', 'phase3'])
-    expect(em.flush).toHaveBeenCalledTimes(1)
+    // Each phase is flushed before the next begins — the interleaved-read guard.
+    expect(calls).toEqual([
+      'phase1-start',
+      'phase1-end',
+      'flush',
+      'phase2',
+      'flush',
+      'phase3',
+      'flush',
+    ])
+    expect(em.flush).toHaveBeenCalledTimes(3)
     expect(em.begin).not.toHaveBeenCalled()
     expect(em.commit).not.toHaveBeenCalled()
     expect(em.rollback).not.toHaveBeenCalled()
   })
 
-  it('lets a later phase observe state a prior phase mutated', async () => {
+  it('flushes a phase before a later phase observes its mutation', async () => {
     const em = createFakeEm()
     const state: { value: number } = { value: 0 }
     let observed: number | null = null
@@ -59,7 +71,8 @@ describe('withAtomicFlush', () => {
     ])
 
     expect(observed).toBe(42)
-    expect(em.flush).toHaveBeenCalledTimes(1)
+    // Two phases → flushed at each boundary.
+    expect(em.flush).toHaveBeenCalledTimes(2)
   })
 
   it('wraps phases in begin/commit when transaction option is true', async () => {
@@ -93,25 +106,31 @@ describe('withAtomicFlush', () => {
     expect(em.rollback).toHaveBeenCalledTimes(1)
   })
 
-  it('propagates a thrown error and does NOT flush when a phase throws (non-transactional)', async () => {
+  it('propagates a thrown error and stops at the failing phase (non-transactional, per-phase flush)', async () => {
     const em = createFakeEm()
     const failure = new Error('phase-failure')
+    let thirdPhaseRan = false
 
     await expect(
       withAtomicFlush(em as any, [
         () => {
-          // ok
+          // ok — its changeset is flushed at the phase boundary before phase 2 runs
         },
         () => {
           throw failure
         },
         () => {
-          throw new Error('should-not-run')
+          thirdPhaseRan = true
         },
       ]),
     ).rejects.toBe(failure)
 
-    expect(em.flush).not.toHaveBeenCalled()
+    // Non-transactional: the first phase flushed independently before phase 2
+    // threw; the failing phase's own flush and every later phase are skipped.
+    // (This independent-commit risk is exactly why mutating commands pass
+    // `{ transaction: true }`, where the whole sequence rolls back instead.)
+    expect(em.flush).toHaveBeenCalledTimes(1)
+    expect(thirdPhaseRan).toBe(false)
   })
 
   it('is a true no-op when phases is empty — no flush, no transaction', async () => {
@@ -220,6 +239,88 @@ describe('withAtomicFlush', () => {
     expect(em.begin).toHaveBeenCalledWith(undefined)
   })
 
+  describe('commit-boundary pending-changes guard', () => {
+    type UowEm = FakeEntityManager & {
+      getUnitOfWork: jest.Mock<{ computeChangeSets: jest.Mock; getChangeSets: jest.Mock }, []>
+    }
+
+    function createUowEm(pendingChangeSets: unknown[], opts?: { inTransaction?: boolean }): UowEm {
+      const computeChangeSets = jest.fn()
+      const getChangeSets = jest.fn().mockReturnValue(pendingChangeSets)
+      return {
+        ...createFakeEm(opts),
+        getUnitOfWork: jest.fn().mockReturnValue({ computeChangeSets, getChangeSets }),
+      }
+    }
+
+    it('flushes once more when a change set lingers past the last phase flush', async () => {
+      // One managed entity is still dirty at the commit boundary (a phase mutated
+      // after its own flush). The guard must persist it instead of letting the
+      // transaction commit the work-in-progress silently.
+      const em = createUowEm([{ entity: 'lingering' }], { inTransaction: false })
+      const warn = jest.spyOn(console, 'warn').mockImplementation(() => {})
+      try {
+        await withAtomicFlush(em as any, [() => {}], { transaction: true, label: 'demo.command' })
+      } finally {
+        warn.mockRestore()
+      }
+
+      // 1 per-phase flush + 1 defensive guard flush, all inside the same transaction.
+      expect(em.flush).toHaveBeenCalledTimes(2)
+      expect(em.commit).toHaveBeenCalledTimes(1)
+      expect(em.rollback).not.toHaveBeenCalled()
+    })
+
+    it('warns (dev) and names the label when the guard has to act', async () => {
+      const em = createUowEm([{ a: 1 }, { b: 2 }])
+      const previousEnv = process.env.NODE_ENV
+      process.env.NODE_ENV = 'development'
+      const warn = jest.spyOn(console, 'warn').mockImplementation(() => {})
+      let warnCallCount = 0
+      let warnMessage = ''
+      try {
+        await withAtomicFlush(em as any, [() => {}], { label: 'sales.update_shipment' })
+        // Capture BEFORE mockRestore — restore() resets mock.calls.
+        warnCallCount = warn.mock.calls.length
+        warnMessage = String(warn.mock.calls[0]?.[0] ?? '')
+      } finally {
+        warn.mockRestore()
+        process.env.NODE_ENV = previousEnv
+      }
+
+      expect(warnCallCount).toBe(1)
+      expect(warnMessage).toContain('sales.update_shipment')
+      expect(warnMessage).toContain('2 pending change-set(s)')
+    })
+
+    it('does NOT flush again when the UnitOfWork is clean at the boundary', async () => {
+      const em = createUowEm([])
+      const warn = jest.spyOn(console, 'warn').mockImplementation(() => {})
+      try {
+        await withAtomicFlush(em as any, [() => {}, () => {}])
+      } finally {
+        warn.mockRestore()
+      }
+
+      // 2 phases → 2 per-phase flushes; the clean guard adds nothing.
+      expect(em.flush).toHaveBeenCalledTimes(2)
+      expect(warn).not.toHaveBeenCalled()
+    })
+
+    it('never throws when the UnitOfWork probe itself fails', async () => {
+      const em: any = {
+        ...createFakeEm(),
+        getUnitOfWork: jest.fn(() => {
+          throw new Error('uow unavailable')
+        }),
+      }
+
+      await expect(withAtomicFlush(em, [() => {}])).resolves.toBeUndefined()
+      // Probe failure → unknown → no defensive flush beyond the per-phase one.
+      expect(em.flush).toHaveBeenCalledTimes(1)
+    })
+  })
+
   it('opens its own transaction when the EM does not implement isInTransaction (partial/mock EM)', async () => {
     // Many command unit tests mock an EntityManager with begin/commit/rollback/flush
     // but no isInTransaction. The re-entrancy probe must not throw on such EMs — it

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/crud/__tests__/crud-factory.test.ts

@@ -4,6 +4,11 @@ jest.mock('@open-mercato/cache', () => ({
 
 import { makeCrudRoute } from '@open-mercato/shared/lib/crud/factory'
 import { registerApiInterceptors } from '@open-mercato/shared/lib/crud/interceptor-registry'
+import {
+  clearOptimisticLockReadersForTests,
+  getAllOptimisticLockReaders,
+  registerOptimisticLockReaders,
+} from '@open-mercato/shared/lib/crud/optimistic-lock-store'
 import { loadCustomFieldDefinitionIndex } from '@open-mercato/shared/lib/crud/custom-fields'
 import { z } from 'zod'
 
@@ -754,3 +759,104 @@ describe('CRUD Factory', () => {
     expect(body._interceptor).toEqual({ ok: true, count: 1 })
   })
 })
+
+describe('CRUD Factory — optimistic-lock auto-registration', () => {
+  beforeEach(() => {
+    clearOptimisticLockReadersForTests()
+  })
+
+  afterAll(() => {
+    clearOptimisticLockReadersForTests()
+  })
+
+  function makeMinimalRoute(opts: { eventsResource: string; entity: any }) {
+    return makeCrudRoute({
+      metadata: { GET: { requireAuth: true } },
+      orm: { entity: opts.entity, idField: 'id', orgField: 'organizationId', tenantField: 'tenantId' },
+      events: { module: opts.eventsResource.split('.')[0], entity: opts.eventsResource.split('.')[1], persistent: false } as any,
+      list: { schema: z.object({}).passthrough() as any },
+      create: {
+        commandId: `${opts.eventsResource}.create`,
+        schema: z.object({}).passthrough() as any,
+      },
+      update: {
+        commandId: `${opts.eventsResource}.update`,
+        schema: z.object({ id: z.string() }).passthrough() as any,
+      },
+      del: {
+        commandId: `${opts.eventsResource}.delete`,
+        schema: z.object({ id: z.string() }).passthrough() as any,
+      },
+    })
+  }
+
+  it('auto-registers a reader for the route resourceKind at factory call time', () => {
+    expect(getAllOptimisticLockReaders()).toEqual({})
+    makeMinimalRoute({ eventsResource: 'example.todo', entity: Todo })
+    const all = getAllOptimisticLockReaders()
+    expect(Object.keys(all)).toContain('example.todo')
+    expect(typeof all['example.todo']).toBe('function')
+  })
+
+  it('does NOT override an existing hand-wired reader (IfAbsent semantics)', () => {
+    const handWired = async () => 'hand-wired'
+    registerOptimisticLockReaders({ 'example.todo': handWired })
+    makeMinimalRoute({ eventsResource: 'example.todo', entity: Todo })
+    expect(getAllOptimisticLockReaders()['example.todo']).toBe(handWired)
+  })
+
+  it('skips registration when the entity has no resolvable resourceKind', () => {
+    expect(getAllOptimisticLockReaders()).toEqual({})
+    // Route with no events.module + no command IDs → resourceKind falls back to 'resource'
+    makeCrudRoute({
+      metadata: { GET: { requireAuth: true } },
+      orm: { entity: Todo },
+      list: { schema: z.object({}).passthrough() as any },
+    } as any)
+    // 'resource' is filtered out by the auto-registration guard
+    expect(getAllOptimisticLockReaders()['resource']).toBeUndefined()
+  })
+
+  it('the registered reader projects only updatedAt and fails open on schema mismatch', async () => {
+    makeMinimalRoute({ eventsResource: 'example.todo', entity: Todo })
+    const reader = getAllOptimisticLockReaders()['example.todo']
+    expect(reader).toBeDefined()
+    let captured: { entity: unknown; filter: Record<string, unknown>; options?: Record<string, unknown> } | null = null
+    const fakeEm = {
+      async findOne(entity: unknown, filter: Record<string, unknown>, options?: Record<string, unknown>) {
+        captured = { entity, filter, options }
+        return { updatedAt: new Date('2026-05-26T07:30:00.000Z') }
+      },
+    } as never
+    const out = await reader!(fakeEm, {
+      resourceKind: 'example.todo',
+      resourceId: 'todo-1',
+      tenantId: 'tenant-1',
+      organizationId: 'org-1',
+    })
+    expect(out).toBe('2026-05-26T07:30:00.000Z')
+    expect(captured).not.toBeNull()
+    expect(captured!.entity).toBe(Todo)
+    expect(captured!.filter).toEqual({
+      id: 'todo-1',
+      tenantId: 'tenant-1',
+      organizationId: 'org-1',
+      deletedAt: null,
+    })
+    expect(captured!.options).toEqual({ fields: ['updatedAt'] })
+
+    // Fail-open contract: throwing findOne yields null, not a re-thrown error.
+    const throwingEm = {
+      async findOne() {
+        throw new Error('schema mismatch')
+      },
+    } as never
+    const safe = await reader!(throwingEm, {
+      resourceKind: 'example.todo',
+      resourceId: 'todo-1',
+      tenantId: 'tenant-1',
+      organizationId: 'org-1',
+    })
+    expect(safe).toBeNull()
+  })
+})