@open-mercato/shared 0.7.1-develop.7149.1.7efa6e1612 → 0.7.1-develop.7151.1.00d0391847

package/src/lib/crud/__tests__/crud-factory.test.ts

@@ -116,6 +116,8 @@ const queryEngine = {
 
 const mockDataEngine = {
   __pendingSideEffects: [] as any[],
+  __defaultIndexer: null as any,
+  __indexedDefaultEntityClass: false,
   createOrmEntity: jest.fn(async ({ entity, data }: any) => {
     const created = em.create(entity, data)
     await em.persist(created as any).flush()
@@ -142,14 +144,29 @@ const mockDataEngine = {
   emitOrmEntityEvent: jest.fn(async (_entry: any) => {}),
   markOrmEntityChange: jest.fn(function (this: any, entry: any) {
     if (!entry || !entry.entity) return
-    this.__pendingSideEffects.push(entry)
+    const defaultIndexer = this.__defaultIndexer
+    const indexer = entry.indexer
+      ?? (defaultIndexer && entry.entity instanceof defaultIndexer.entityClass ? defaultIndexer.indexer : undefined)
+    this.__pendingSideEffects.push(indexer ? { ...entry, indexer } : entry)
   }),
   flushOrmEntityChanges: jest.fn(async function (this: any) {
     while (this.__pendingSideEffects.length > 0) {
       const next = this.__pendingSideEffects.shift()
+      if (next.indexer && this.__defaultIndexer && next.entity instanceof this.__defaultIndexer.entityClass) {
+        this.__indexedDefaultEntityClass = true
+      }
       await this.emitOrmEntityEvent(next)
     }
   }),
+  // Mirrors DefaultDataEngine's route-declared indexer default (#5741) so the factory's
+  // command path exercises the same contract it does against the real engine.
+  setDefaultIndexerConfig: jest.fn(function (this: any, config: any) {
+    this.__defaultIndexer = config
+    this.__indexedDefaultEntityClass = false
+  }),
+  hasIndexedDefaultEntityClass: jest.fn(function (this: any) {
+    return this.__indexedDefaultEntityClass === true
+  }),
 }
 
 const accessLogService = {
@@ -207,6 +224,8 @@ describe('CRUD Factory', () => {
     jest.clearAllMocks()
     accessLogService.log.mockClear()
     mockDataEngine.__pendingSideEffects = []
+    mockDataEngine.__defaultIndexer = null
+    mockDataEngine.__indexedDefaultEntityClass = false
     mockOrganizationScopeOverride = null
     commandBus = {
       execute: jest.fn(async () => ({ result: {}, logEntry: { id: 'log-1' } })),
@@ -1050,6 +1069,159 @@ describe('CRUD Factory', () => {
     expect(mockDataEngine.emitOrmEntityEvent).not.toHaveBeenCalled()
   })
 
+  // #5741 — a route whose verbs are all command-backed used to declare `indexer:` that no
+  // code ever read, so `entity_indexes` was never maintained for it and nothing said so.
+  describe('command routes honour the route-declared indexer', () => {
+    const routeIndexer = { entityType: 'example.todo' }
+
+    const buildCommandRoute = () => makeCrudRoute({
+      metadata: { POST: { requireAuth: true }, PUT: { requireAuth: true }, DELETE: { requireAuth: true } },
+      orm: { entity: Todo, idField: 'id', orgField: 'organizationId', tenantField: 'tenantId', softDeleteField: 'deletedAt' },
+      indexer: routeIndexer,
+      actions: {
+        create: { commandId: 'example.todo.create', schema: z.any(), response: () => ({ ok: true }) },
+        update: { commandId: 'example.todo.update', schema: z.any(), response: () => ({ ok: true }) },
+        delete: { commandId: 'example.todo.delete', schema: z.any(), response: () => ({ ok: true }) },
+      },
+    })
+
+    // Stands in for every core command handler that ends in `emitCrudSideEffects({ events })`
+    // with no `indexer` of its own — customers/commands/tags.ts, catalog/commands/prices.ts.
+    const markEventsOnly = (action: 'created' | 'updated' | 'deleted', entity: object) => async () => {
+      mockDataEngine.markOrmEntityChange({
+        action,
+        entity,
+        events: { module: 'example', entity: 'todo' },
+        identifiers: { id: 'todo-1', organizationId: defaultOrganizationId, tenantId: defaultTenantId },
+      } as any)
+      await mockDataEngine.flushOrmEntityChanges()
+      return { result: { id: 'todo-1' }, logEntry: { id: 'log-1' } }
+    }
+
+    const flushedEntries = () => mockDataEngine.emitOrmEntityEvent.mock.calls.map(([entry]) => entry as any)
+
+    it.each([
+      ['POST', 'created' as const],
+      ['PUT', 'updated' as const],
+      ['DELETE', 'deleted' as const],
+    ])('%s applies the declaration to the handler\'s events-only mark', async (method, action) => {
+      commandBus.execute.mockImplementation(markEventsOnly(action, new Todo()))
+      const route = buildCommandRoute()
+      const res = await (route as any)[method](new Request('http://x/api/example/todos/command?id=todo-1', {
+        method,
+        body: JSON.stringify({ id: 'todo-1' }),
+        headers: { 'content-type': 'application/json' },
+      }))
+
+      expect(res.status).toBeLessThan(400)
+      expect(flushedEntries()).toEqual([expect.objectContaining({ action, indexer: routeIndexer })])
+      // The declaration is scoped to the command; it must not linger for later writes.
+      expect(mockDataEngine.setDefaultIndexerConfig).toHaveBeenLastCalledWith(null)
+    })
+
+    it('leaves a handler-supplied indexer in place', async () => {
+      const handlerIndexer = { entityType: 'example.todo_handler_owned' }
+      commandBus.execute.mockImplementation(async () => {
+        mockDataEngine.markOrmEntityChange({
+          action: 'created',
+          entity: new Todo(),
+          events: { module: 'example', entity: 'todo' },
+          indexer: handlerIndexer,
+          identifiers: { id: 'todo-1', organizationId: defaultOrganizationId, tenantId: defaultTenantId },
+        } as any)
+        await mockDataEngine.flushOrmEntityChanges()
+        return { result: { id: 'todo-1' }, logEntry: { id: 'log-1' } }
+      })
+      const route = buildCommandRoute()
+      const res = await route.POST(new Request('http://x/api/example/todos/command', {
+        method: 'POST',
+        body: JSON.stringify({}),
+        headers: { 'content-type': 'application/json' },
+      }))
+
+      expect(res.status).toBeLessThan(400)
+      expect(flushedEntries()).toEqual([expect.objectContaining({ indexer: handlerIndexer })])
+    })
+
+    it('never declares an indexer the route did not configure', async () => {
+      commandBus.execute.mockImplementation(markEventsOnly('created', new Todo()))
+      const route = makeCrudRoute({
+        metadata: { POST: { requireAuth: true } },
+        orm: { entity: Todo, idField: 'id', orgField: 'organizationId', tenantField: 'tenantId', softDeleteField: 'deletedAt' },
+        actions: {
+          create: { commandId: 'example.todo.create', schema: z.any(), response: () => ({ ok: true }) },
+        },
+      })
+      const res = await route.POST(new Request('http://x/api/example/todos/command', {
+        method: 'POST',
+        body: JSON.stringify({}),
+        headers: { 'content-type': 'application/json' },
+      }))
+
+      expect(res.status).toBeLessThan(400)
+      expect(mockDataEngine.setDefaultIndexerConfig).not.toHaveBeenCalled()
+      expect(flushedEntries()).toEqual([expect.not.objectContaining({ indexer: expect.anything() })])
+    })
+
+    it('clears the declaration when the command throws', async () => {
+      commandBus.execute.mockRejectedValue(new Error('boom'))
+      const route = buildCommandRoute()
+      await route.POST(new Request('http://x/api/example/todos/command', {
+        method: 'POST',
+        body: JSON.stringify({}),
+        headers: { 'content-type': 'application/json' },
+      }))
+
+      expect(mockDataEngine.setDefaultIndexerConfig).toHaveBeenLastCalledWith(null)
+    })
+
+    describe('the undischarged-declaration warning', () => {
+      // The warning is the only part of this change a module author ever sees, so it is pinned
+      // in both directions: present when a handler drops the write, absent on the happy path.
+      const logRecords: LoggerExtensionRecord[] = []
+      const undischargedWarnings = () => logRecords.filter((record) =>
+        record.level === 'warn' && String(record.message).includes('did not discharge'))
+
+      beforeEach(() => {
+        logRecords.length = 0
+        registerLoggerExtension({ emit: (record) => logRecords.push(record) })
+      })
+      afterEach(() => { resetLoggerExtension() })
+
+      it('warns once, naming the command, when the handler marks nothing at all', async () => {
+        commandBus.execute.mockImplementation(async () => ({ result: { id: 'todo-1' }, logEntry: { id: 'log-1' } }))
+        const route = buildCommandRoute()
+        const res = await route.POST(new Request('http://x/api/example/todos/command', {
+          method: 'POST',
+          body: JSON.stringify({}),
+          headers: { 'content-type': 'application/json' },
+        }))
+
+        expect(res.status).toBeLessThan(400)
+        const warnings = undischargedWarnings()
+        expect(warnings).toHaveLength(1)
+        expect(warnings[0].fields).toMatchObject({
+          operation: 'created',
+          commandId: 'example.todo.create',
+          entityType: routeIndexer.entityType,
+        })
+      })
+
+      it('stays silent when the handler discharges the declaration', async () => {
+        commandBus.execute.mockImplementation(markEventsOnly('created', new Todo()))
+        const route = buildCommandRoute()
+        const res = await route.POST(new Request('http://x/api/example/todos/command', {
+          method: 'POST',
+          body: JSON.stringify({}),
+          headers: { 'content-type': 'application/json' },
+        }))
+
+        expect(res.status).toBeLessThan(400)
+        expect(undischargedWarnings()).toHaveLength(0)
+      })
+    })
+  })
+
   it('POST command route runs mutation guards before executing the command', async () => {
     const guardValidate = jest.fn(async (_input: any) => ({ ok: false, status: 403, message: 'Blocked by test guard' }))
     registerMutationGuards([{ moduleId: 'example', guards: [{

package/src/lib/crud/factory.ts

@@ -1100,6 +1100,49 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
   const indexerConfig = opts.indexer as CrudIndexerConfig | undefined
   const eventsConfig = opts.events as CrudEventsConfig | undefined
 
+  // Command-backed verbs (`actions.*`) never reach the built-in `markOrmEntityChange` calls
+  // below — the handler owns the mark and the command bus owns the flush. Hand the route's
+  // declared `indexer:` to the data engine for the duration of the command so a handler that
+  // marks `events:` only still writes the projection the route promised, using the handler's
+  // own entity and identifiers. Without this the declaration reaches no code at all (#5741).
+  const withRouteIndexerDeclaration = async <TResult>(
+    ctx: CrudCtx,
+    operation: CrudEventAction,
+    commandId: string,
+    run: () => Promise<TResult>,
+  ): Promise<TResult> => {
+    if (!indexerConfig || !ormCfg.entity) return run()
+    let de: DataEngine | null = null
+    try {
+      de = ctx.container.resolve('dataEngine') as DataEngine
+    } catch {
+      de = null
+    }
+    if (!de || typeof de.setDefaultIndexerConfig !== 'function') return run()
+    de.setDefaultIndexerConfig({ indexer: indexerConfig, entityClass: ormCfg.entity })
+    try {
+      const result = await run()
+      if (de.hasIndexedDefaultEntityClass?.() === false) {
+        // The one genuinely undiagnosable case: a handler that marks no side effect at all,
+        // so neither the route nor the command maintains the projection. One line per dropped
+        // write — far narrower than warning at construction time, though not literally false-
+        // positive-free: the flag tracks the route's own entity class, so a handler that
+        // discharges the projection through a different class (marking a parent aggregate with
+        // its own explicit `indexer:`) would also be warned about. No route in this repository
+        // does that today; widen the flag to "any indexer discharged" if one ever needs to.
+        logger.warn('CRUD route declares an indexer that its command handler did not discharge; the query index was not updated for this write', {
+          resourceKind,
+          operation,
+          commandId,
+          entityType: indexerConfig.entityType,
+        })
+      }
+      return result
+    } finally {
+      de.setDefaultIndexerConfig(null)
+    }
+  }
+
   const inferFieldValue = (item: Record<string, unknown>, keys: string[]): string | null => {
     for (const key of keys) {
       const value = item[key]
@@ -2286,7 +2329,9 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
           context: { cacheAliases: resourceTargets },
         }
         const metadataToSend = mergeCommandMetadata(baseMetadata, userMetadata)
-        const { result, logEntry } = await commandBus.execute(action.commandId, { input, ctx, metadata: metadataToSend })
+        const { result, logEntry } = await withRouteIndexerDeclaration(ctx, 'created', action.commandId, () =>
+          commandBus.execute(action.commandId, { input, ctx, metadata: metadataToSend }),
+        )
 
         // Sync after-event (*.created) — command path
         if (createLifecycleCmd.afterEventId && ctx.auth.tenantId) {
@@ -2337,9 +2382,11 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
             requestHeaders: request.headers,
           })
         }
-        // Note: side effects (events + indexing) are already flushed by CommandBus.execute()
-        // via flushCrudSideEffects(). Calling markCommandResultForIndexing here would cause
-        // duplicate event emissions.
+        // Note: side effects are already flushed by CommandBus.execute() via
+        // flushCrudSideEffects(). Re-marking the result here would emit a duplicate domain
+        // event, so the route does not. The route's `indexer:` declaration still reaches
+        // that flush: withRouteIndexerDeclaration() hands it to the data engine as the
+        // default for marks the handler makes without one (#5741).
         return response
       }
 
@@ -2612,7 +2659,9 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
         }
         if (candidateId) baseMetadata.resourceId = candidateId
         const metadataToSend = mergeCommandMetadata(baseMetadata, userMetadata)
-        const { result, logEntry } = await commandBus.execute(action.commandId, { input, ctx, metadata: metadataToSend })
+        const { result, logEntry } = await withRouteIndexerDeclaration(ctx, 'updated', action.commandId, () =>
+          commandBus.execute(action.commandId, { input, ctx, metadata: metadataToSend }),
+        )
         const payload = action.response ? action.response({ result, logEntry, ctx }) : result
         let resolvedPayload = await Promise.resolve(payload)
         if (interceptorRequestPayload && resolvedPayload && typeof resolvedPayload === 'object' && !Array.isArray(resolvedPayload)) {
@@ -2659,9 +2708,11 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
           }
         }
 
-        // Note: side effects (events + indexing) are already flushed by CommandBus.execute()
-        // via flushCrudSideEffects(). Calling markCommandResultForIndexing here would cause
-        // duplicate event emissions.
+        // Note: side effects are already flushed by CommandBus.execute() via
+        // flushCrudSideEffects(). Re-marking the result here would emit a duplicate domain
+        // event, so the route does not. The route's `indexer:` declaration still reaches
+        // that flush: withRouteIndexerDeclaration() hands it to the data engine as the
+        // default for marks the handler makes without one (#5741).
         return response
       }
 
@@ -2945,7 +2996,9 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
         }
         if (candidateId) baseMetadata.resourceId = candidateId
         const metadataToSend = mergeCommandMetadata(baseMetadata, userMetadata)
-        const { result, logEntry } = await commandBus.execute(action.commandId, { input, ctx, metadata: metadataToSend })
+        const { result, logEntry } = await withRouteIndexerDeclaration(ctx, 'deleted', action.commandId, () =>
+          commandBus.execute(action.commandId, { input, ctx, metadata: metadataToSend }),
+        )
         const payload = action.response ? action.response({ result, logEntry, ctx }) : result
         let resolvedPayload = await Promise.resolve(payload)
         if (interceptorRequestPayload && resolvedPayload && typeof resolvedPayload === 'object' && !Array.isArray(resolvedPayload)) {
@@ -2991,9 +3044,11 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
           }
         }
 
-        // Note: side effects (events + indexing) are already flushed by CommandBus.execute()
-        // via flushCrudSideEffects(). Calling markCommandResultForIndexing here would cause
-        // duplicate event emissions.
+        // Note: side effects are already flushed by CommandBus.execute() via
+        // flushCrudSideEffects(). Re-marking the result here would emit a duplicate domain
+        // event, so the route does not. The route's `indexer:` declaration still reaches
+        // that flush: withRouteIndexerDeclaration() hands it to the data engine as the
+        // default for marks the handler makes without one (#5741).
         return response
       }
 

package/src/lib/crud/types.ts

@@ -24,6 +24,29 @@ export type CrudEventsConfig<TEntity = unknown> = {
   buildPayload?(ctx: CrudEmitContext<TEntity>): unknown
 }
 
+/**
+ * Declares that a CRUD write maintains the `query_index` projection for `entityType`.
+ *
+ * On `makeCrudRoute`'s built-in write path (`create` / `update` / `del`) the route emits the
+ * projection event itself. On the command path (`actions.*`) the command handler owns the
+ * side-effect mark and the command bus owns the flush, so the route's declaration is applied
+ * to the handler's mark: a handler that calls `emitCrudSideEffects({ events })` without an
+ * `indexer` still indexes the record under this `entityType`, and one that passes its own
+ * `indexer` keeps it. A handler that marks no side effect at all indexes nothing — the route
+ * logs a warning naming the command when that happens.
+ *
+ * Two limits of that hand-down are worth knowing before you rely on it:
+ *
+ * - It is scoped to one `CommandBus.execute()`, and the declaration lives on the request's
+ *   `DataEngine` instance. That is sound because `createRequestContainer()` registers
+ *   `dataEngine` per request; re-registering it as a transient would leave the command marking
+ *   on a different instance than the route declared on, so nothing is indexed and every write
+ *   logs the warning.
+ * - `CommandBus.undo()` runs outside any route, so no declaration is active there. An undo
+ *   handler that must maintain the projection MUST pass its own `indexer` to
+ *   `emitCrudUndoSideEffects` — otherwise undoing a delete restores the row in the database and
+ *   leaves it missing from `query_index` until the next full rebuild.
+ */
 export type CrudIndexerConfig<TEntity = unknown> = {
   entityType: string
   buildUpsertPayload?(ctx: CrudEmitContext<TEntity>): unknown

package/src/lib/data/__tests__/engine.default-indexer.test.ts

@@ -0,0 +1,188 @@
+import type { AwilixContainer } from 'awilix'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { DefaultDataEngine } from '../engine'
+import type { CrudEventsConfig, CrudIndexerConfig } from '../../crud/types'
+
+// A command-backed CRUD route (`makeCrudRoute` + `actions.*`) cannot mark its own side effect:
+// the handler owns the mark and the command bus owns the flush. The route therefore hands its
+// declared `indexer:` to the engine for the duration of the command, and the engine applies it
+// to marks the handler makes without one — otherwise the declaration reaches no code at all and
+// the projection is never written (#5741). The entity-class gate is what keeps a handler's
+// sibling-entity marks from being indexed under the route's entityType.
+
+class RouteEntity {
+  constructor(public id: string) {}
+}
+
+class SiblingEntity {
+  constructor(public id: string) {}
+}
+
+const EVENTS: CrudEventsConfig<unknown> = { module: 'customers', entity: 'tag', persistent: false }
+const ROUTE_INDEXER: CrudIndexerConfig<unknown> = { entityType: 'customers:customer_tag' }
+const HANDLER_INDEXER: CrudIndexerConfig<unknown> = { entityType: 'customers:handler_owned' }
+const IDENTIFIERS = { id: 'rec-1', organizationId: 'org-1', tenantId: 'tenant-1' }
+
+function buildEngine() {
+  const emitEvent = jest.fn().mockResolvedValue(undefined)
+  const container = {
+    resolve: (token: string) => {
+      if (token === 'eventBus') return { emitEvent }
+      throw new Error(`unexpected resolve(${token})`)
+    },
+  } as unknown as AwilixContainer
+  const engine = new DefaultDataEngine({} as EntityManager, container)
+  const indexPayloads = (eventName: string) =>
+    emitEvent.mock.calls.filter(([name]) => name === eventName).map(([, payload]) => payload as Record<string, unknown>)
+  return { engine, emitEvent, indexPayloads }
+}
+
+describe('DefaultDataEngine route-declared indexer default', () => {
+  let warnSpy: jest.SpyInstance
+  beforeAll(() => { warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => undefined) })
+  afterAll(() => { warnSpy.mockRestore() })
+
+  it('indexes an events-only mark under the route-declared entityType', async () => {
+    const { engine, indexPayloads } = buildEngine()
+    engine.setDefaultIndexerConfig({ indexer: ROUTE_INDEXER, entityClass: RouteEntity })
+
+    // What every command handler on the two affected core routes does: mark `events:` only.
+    engine.markOrmEntityChange({ action: 'created', entity: new RouteEntity('rec-1'), events: EVENTS, identifiers: IDENTIFIERS })
+    await engine.flushOrmEntityChanges()
+
+    const upserts = indexPayloads('query_index.upsert_one')
+    expect(upserts).toHaveLength(1)
+    expect(upserts[0]).toMatchObject({ entityType: 'customers:customer_tag', recordId: 'rec-1', crudAction: 'created' })
+    expect(engine.hasIndexedDefaultEntityClass()).toBe(true)
+  })
+
+  it('emits the delete projection for an events-only delete mark', async () => {
+    const { engine, indexPayloads } = buildEngine()
+    engine.setDefaultIndexerConfig({ indexer: ROUTE_INDEXER, entityClass: RouteEntity })
+
+    engine.markOrmEntityChange({ action: 'deleted', entity: new RouteEntity('rec-1'), events: EVENTS, identifiers: IDENTIFIERS })
+    await engine.flushOrmEntityChanges()
+
+    expect(indexPayloads('query_index.delete_one')).toHaveLength(1)
+    expect(indexPayloads('query_index.upsert_one')).toHaveLength(0)
+  })
+
+  it('leaves a handler-supplied indexer untouched — explicit wins over the default', async () => {
+    const { engine, indexPayloads } = buildEngine()
+    engine.setDefaultIndexerConfig({ indexer: ROUTE_INDEXER, entityClass: RouteEntity })
+
+    engine.markOrmEntityChange({
+      action: 'updated',
+      entity: new RouteEntity('rec-1'),
+      events: EVENTS,
+      indexer: HANDLER_INDEXER,
+      identifiers: IDENTIFIERS,
+    })
+    await engine.flushOrmEntityChanges()
+
+    const upserts = indexPayloads('query_index.upsert_one')
+    expect(upserts).toHaveLength(1)
+    expect(upserts[0]).toMatchObject({ entityType: 'customers:handler_owned' })
+  })
+
+  it('does not apply the default to a mark for a different entity class', async () => {
+    const { engine, emitEvent } = buildEngine()
+    engine.setDefaultIndexerConfig({ indexer: ROUTE_INDEXER, entityClass: RouteEntity })
+
+    // A tag command also marks its tag *assignments*; indexing those as `customer_tag` would
+    // write a projection row for the wrong record.
+    engine.markOrmEntityChange({ action: 'updated', entity: new SiblingEntity('assignment-1'), identifiers: { ...IDENTIFIERS, id: 'assignment-1' } })
+    await engine.flushOrmEntityChanges()
+
+    expect(emitEvent.mock.calls.map(([name]) => name)).not.toContain('query_index.upsert_one')
+    expect(engine.hasIndexedDefaultEntityClass()).toBe(false)
+  })
+
+  it('reports an undischarged declaration when the handler marks nothing at all', async () => {
+    const { engine, emitEvent } = buildEngine()
+    engine.setDefaultIndexerConfig({ indexer: ROUTE_INDEXER, entityClass: RouteEntity })
+
+    await engine.flushOrmEntityChanges()
+
+    expect(emitEvent).not.toHaveBeenCalled()
+    expect(engine.hasIndexedDefaultEntityClass()).toBe(false)
+  })
+
+  it('stops applying the declaration once it is cleared', async () => {
+    const { engine, emitEvent } = buildEngine()
+    engine.setDefaultIndexerConfig({ indexer: ROUTE_INDEXER, entityClass: RouteEntity })
+    engine.setDefaultIndexerConfig(null)
+
+    engine.markOrmEntityChange({ action: 'created', entity: new RouteEntity('rec-1'), events: EVENTS, identifiers: IDENTIFIERS })
+    await engine.flushOrmEntityChanges()
+
+    expect(emitEvent.mock.calls.map(([name]) => name)).not.toContain('query_index.upsert_one')
+    expect(engine.hasIndexedDefaultEntityClass()).toBe(false)
+  })
+
+  it('keeps a handler indexer when a later events-only mark hits the same key', async () => {
+    const { engine, indexPayloads } = buildEngine()
+    engine.setDefaultIndexerConfig({ indexer: ROUTE_INDEXER, entityClass: RouteEntity })
+
+    // Same (action, id, organizationId, tenantId) key twice. The merge branch must not let the
+    // route default overwrite the config the first mark installed — that would silently drop the
+    // handler's own `buildUpsertPayload` and invert the "explicit always wins" rule.
+    engine.markOrmEntityChange({
+      action: 'updated',
+      entity: new RouteEntity('rec-1'),
+      events: EVENTS,
+      indexer: HANDLER_INDEXER,
+      identifiers: IDENTIFIERS,
+    })
+    engine.markOrmEntityChange({ action: 'updated', entity: new RouteEntity('rec-1'), events: EVENTS, identifiers: IDENTIFIERS })
+    await engine.flushOrmEntityChanges()
+
+    const upserts = indexPayloads('query_index.upsert_one')
+    expect(upserts).toHaveLength(1)
+    expect(upserts[0]).toMatchObject({ entityType: 'customers:handler_owned' })
+  })
+
+  it('still applies the default when the first mark on a key carried no indexer', async () => {
+    const { engine, indexPayloads } = buildEngine()
+    engine.setDefaultIndexerConfig({ indexer: ROUTE_INDEXER, entityClass: RouteEntity })
+
+    engine.markOrmEntityChange({ action: 'updated', entity: new RouteEntity('rec-1'), events: EVENTS, identifiers: IDENTIFIERS })
+    engine.markOrmEntityChange({ action: 'updated', entity: new RouteEntity('rec-1'), events: EVENTS, identifiers: IDENTIFIERS })
+    await engine.flushOrmEntityChanges()
+
+    const upserts = indexPayloads('query_index.upsert_one')
+    expect(upserts).toHaveLength(1)
+    expect(upserts[0]).toMatchObject({ entityType: 'customers:customer_tag' })
+  })
+
+  it('ignores a non-constructor entityClass instead of throwing on the write path', async () => {
+    const { engine, emitEvent } = buildEngine()
+    // `OrmEntityConfig.entity` is `any` and this repo treats `EntitySchema` instances — plain
+    // objects, not constructors — as a first-class entity shape. `instanceof` against one throws,
+    // and it would throw inside `markOrmEntityChange`, outside the flush's best-effort catch.
+    const entitySchemaLike = { name: 'RouteEntity', meta: {} } as unknown as new (...args: never[]) => unknown
+    engine.setDefaultIndexerConfig({ indexer: ROUTE_INDEXER, entityClass: entitySchemaLike })
+
+    expect(() => engine.markOrmEntityChange({
+      action: 'created',
+      entity: new RouteEntity('rec-1'),
+      events: EVENTS,
+      identifiers: IDENTIFIERS,
+    })).not.toThrow()
+    await engine.flushOrmEntityChanges()
+
+    expect(emitEvent.mock.calls.map(([name]) => name)).not.toContain('query_index.upsert_one')
+    expect(engine.hasIndexedDefaultEntityClass()).toBe(false)
+  })
+
+  it('honours a bulk-import skipReindex suppression over the declaration', async () => {
+    const { engine, emitEvent } = buildEngine()
+    engine.setDefaultIndexerConfig({ indexer: ROUTE_INDEXER, entityClass: RouteEntity })
+
+    engine.markOrmEntityChange({ action: 'created', entity: new RouteEntity('rec-1'), events: EVENTS, identifiers: IDENTIFIERS })
+    await engine.flushOrmEntityChanges({ skipReindex: true })
+
+    expect(emitEvent.mock.calls.map(([name]) => name)).not.toContain('query_index.upsert_one')
+    expect(engine.hasIndexedDefaultEntityClass()).toBe(false)
+  })
+})