@open-mercato/shared 0.6.7 → 0.6.8-develop.6874.1.982d6097d8

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

@@ -10,6 +10,7 @@ import {
   registerOptimisticLockReaders,
 } from '@open-mercato/shared/lib/crud/optimistic-lock-store'
 import { loadCustomFieldDefinitionIndex } from '@open-mercato/shared/lib/crud/custom-fields'
+import { registerMutationGuards } from '@open-mercato/shared/lib/crud/mutation-guard-store'
 import { z } from 'zod'
 
 // Keep the real custom-field helpers but spy on the definition loader so we can
@@ -201,6 +202,7 @@ describe('CRUD Factory', () => {
     }
     crudMutationGuardService = null
     registerApiInterceptors([])
+    registerMutationGuards([])
   })
 
   const querySchema = z.object({
@@ -537,12 +539,66 @@ describe('CRUD Factory', () => {
     })
   })
 
+  describe('export loop termination', () => {
+    const EXPORT_PAGE_SIZE = 1000
+
+    afterEach(() => {
+      queryEngine.query.mockImplementation(async (_entityId: any, _q: any) => ({ items: [{ id: 'id-1', title: 'A', is_done: false, organization_id: defaultOrganizationId, tenant_id: defaultTenantId }], total: 1 }))
+    })
+
+    const makeItems = (count: number, offset = 0) =>
+      Array.from({ length: count }, (_, index) => ({
+        id: `id-${offset + index}`,
+        title: `Todo ${offset + index}`,
+        is_done: false,
+        organization_id: defaultOrganizationId,
+        tenant_id: defaultTenantId,
+      }))
+
+    const queuePages = (pages: Array<Array<Record<string, unknown>>>, total: number) => {
+      queryEngine.query.mockImplementation(async (_entityId: any, q: any) => {
+        const page = q?.page?.page ?? 1
+        return { items: pages[page - 1] ?? [], total }
+      })
+    }
+
+    it('GET export enumerates every page even when total under-reports the result set', async () => {
+      queuePages(
+        [makeItems(EXPORT_PAGE_SIZE), makeItems(EXPORT_PAGE_SIZE, EXPORT_PAGE_SIZE), makeItems(5, EXPORT_PAGE_SIZE * 2)],
+        3,
+      )
+      const res = await route.GET(new Request('http://x/api/example/todos?format=json'))
+      expect(res.status).toBe(200)
+      const parsed = JSON.parse(await res.text())
+      expect(parsed).toHaveLength(EXPORT_PAGE_SIZE * 2 + 5)
+      expect(queryEngine.query).toHaveBeenCalledTimes(3)
+    })
+
+    it('GET export terminates on a short final page instead of trusting an inflated total', async () => {
+      queuePages([makeItems(4)], 10_000)
+      const res = await route.GET(new Request('http://x/api/example/todos?format=json'))
+      expect(res.status).toBe(200)
+      const parsed = JSON.parse(await res.text())
+      expect(parsed).toHaveLength(4)
+      expect(queryEngine.query).toHaveBeenCalledTimes(1)
+    })
+
+    it('GET export fails closed at the page ceiling rather than serializing a partial export', async () => {
+      const fullPage = makeItems(EXPORT_PAGE_SIZE)
+      queryEngine.query.mockImplementation(async () => ({ items: fullPage, total: EXPORT_PAGE_SIZE }))
+      const res = await route.GET(new Request('http://x/api/example/todos?format=json'))
+      expect(res.status).toBe(500)
+      expect(queryEngine.query).toHaveBeenCalledTimes(1000)
+    })
+  })
+
   it('POST creates entity, saves custom fields, emits created event', async () => {
     const res = await route.POST(new Request('http://x/api/example/todos', { method: 'POST', body: JSON.stringify({ title: 'B', is_done: true, cf_priority: 3 }), headers: { 'content-type': 'application/json' } }))
     expect(res.status).toBe(201)
     const data = await res.json()
     expect(data.id).toBeDefined()
     // CF saved
+    expect(mockDataEngine.setCustomFields).toHaveBeenCalledWith(expect.objectContaining({ notify: false }))
     expect(setRecordCustomFields).toHaveBeenCalledWith(expect.anything(), expect.objectContaining({ entityId: 'example.todo', values: { priority: 3 } }))
     // Event + indexer delegated to data engine
     expect(mockDataEngine.emitOrmEntityEvent).toHaveBeenCalledTimes(1)
@@ -569,6 +625,7 @@ describe('CRUD Factory', () => {
     await em.persist(created).flush()
     const res = await route.PUT(new Request('http://x/api/example/todos', { method: 'PUT', body: JSON.stringify({ id: created.id, title: 'X2', cf_priority: 5 }), headers: { 'content-type': 'application/json' } }))
     expect(res.status).toBe(200)
+    expect(mockDataEngine.setCustomFields).toHaveBeenCalledWith(expect.objectContaining({ notify: false }))
     expect(setRecordCustomFields).toHaveBeenCalledWith(expect.anything(), expect.objectContaining({ values: { priority: 5 } }))
     expect(mockDataEngine.emitOrmEntityEvent).toHaveBeenCalledTimes(1)
     const updatedCall = mockDataEngine.emitOrmEntityEvent.mock.calls.at(0)
@@ -590,6 +647,34 @@ describe('CRUD Factory', () => {
     expect(mockDataEngine.emitOrmEntityEvent).not.toHaveBeenCalled()
   })
 
+  it('returns a retryable 503 when a handler hits a transient DB connection failure', async () => {
+    setRecordCustomFields.mockImplementationOnce(async () => {
+      throw Object.assign(new Error('sorry, too many clients already'), { code: '53300' })
+    })
+    const res = await route.POST(new Request('http://x/api/example/todos', { method: 'POST', body: JSON.stringify({ title: 'Exhausted', is_done: true, cf_priority: 3 }), headers: { 'content-type': 'application/json' } }))
+    expect(res.status).toBe(503)
+    expect(res.headers.get('Retry-After')).toBe('2')
+    // The failed write is still rolled back — no created event/index leaks out.
+    expect(Object.values(db)).toHaveLength(0)
+    expect(mockDataEngine.emitOrmEntityEvent).not.toHaveBeenCalled()
+  })
+
+  it('POST surfaces CRUD side-effect failures after custom field writes', async () => {
+    mockDataEngine.emitOrmEntityEvent.mockImplementationOnce(async () => {
+      throw new Error('index write failed')
+    })
+
+    const res = await route.POST(new Request('http://x/api/example/todos', {
+      method: 'POST',
+      body: JSON.stringify({ title: 'Indexed', is_done: true, cf_priority: 3 }),
+      headers: { 'content-type': 'application/json' },
+    }))
+
+    expect(res.status).toBe(500)
+    expect(mockDataEngine.setCustomFields).toHaveBeenCalledWith(expect.objectContaining({ notify: false }))
+    expect(mockDataEngine.emitOrmEntityEvent).toHaveBeenCalledTimes(1)
+  })
+
   it('PUT rolls back the entity update when the custom field write fails', async () => {
     const created = em.create(Todo, { title: 'Before', organizationId: defaultOrganizationId, tenantId: defaultTenantId }) as Rec
     created.id = '123e4567-e89b-12d3-a456-426614174003'
@@ -721,6 +806,193 @@ describe('CRUD Factory', () => {
     expect(mockDataEngine.emitOrmEntityEvent).not.toHaveBeenCalled()
   })
 
+  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: [{
+      id: 'example.block-command-create',
+      targetEntity: 'example.todo',
+      operations: ['create'],
+      validate: guardValidate,
+    }] }])
+    const commandRoute = makeCrudRoute({
+      metadata: { POST: { requireAuth: true } },
+      orm: { entity: Todo, idField: 'id', orgField: 'organizationId', tenantField: 'tenantId', softDeleteField: 'deletedAt' },
+      indexer: { entityType: 'example.todo' },
+      actions: {
+        create: {
+          commandId: 'example.todo.create',
+          schema: createSchema,
+          response: () => ({ ok: true }),
+        },
+      },
+    })
+
+    const res = await commandRoute.POST(new Request('http://x/api/example/todos/command', {
+      method: 'POST',
+      body: JSON.stringify({ title: 'A' }),
+      headers: { 'content-type': 'application/json' },
+    }))
+
+    expect(res.status).toBe(403)
+    expect(guardValidate).toHaveBeenCalledWith(expect.objectContaining({
+      resourceKind: 'example.todo',
+      resourceId: null,
+      operation: 'create',
+      mutationPayload: expect.objectContaining({ title: 'A' }),
+    }))
+    expect(commandBus.execute).not.toHaveBeenCalled()
+  })
+
+  it('POST command route merges guard modifiedPayload and runs afterSuccess with the command result id', async () => {
+    commandBus.execute.mockResolvedValue({ result: { id: 'cmd-created-1' }, logEntry: { id: 'log-1' } })
+    const guardAfterSuccess = jest.fn(async () => {})
+    registerMutationGuards([{ moduleId: 'example', guards: [{
+      id: 'example.rewrite-command-create',
+      targetEntity: 'example.todo',
+      operations: ['create'],
+      validate: async (_input: any) => ({ ok: true, modifiedPayload: { title: 'FROM-GUARD' }, shouldRunAfterSuccess: true }),
+      afterSuccess: guardAfterSuccess,
+    }] }])
+    const commandRoute = makeCrudRoute({
+      metadata: { POST: { requireAuth: true } },
+      orm: { entity: Todo, idField: 'id', orgField: 'organizationId', tenantField: 'tenantId', softDeleteField: 'deletedAt' },
+      indexer: { entityType: 'example.todo' },
+      actions: {
+        create: {
+          commandId: 'example.todo.create',
+          schema: createSchema,
+          response: () => ({ ok: true }),
+        },
+      },
+    })
+
+    const res = await commandRoute.POST(new Request('http://x/api/example/todos/command', {
+      method: 'POST',
+      body: JSON.stringify({ title: 'A' }),
+      headers: { 'content-type': 'application/json' },
+    }))
+
+    expect(res.status).toBe(201)
+    expect(commandBus.execute).toHaveBeenCalledWith('example.todo.create', expect.objectContaining({
+      input: expect.objectContaining({ title: 'FROM-GUARD' }),
+    }))
+    expect(guardAfterSuccess).toHaveBeenCalledWith(expect.objectContaining({
+      resourceId: 'cmd-created-1',
+      operation: 'create',
+    }))
+  })
+
+  it('POST command route falls back to the response payload id for guard afterSuccess', async () => {
+    commandBus.execute.mockResolvedValue({ result: { lineId: 'line-42' }, logEntry: { id: 'log-1' } })
+    const guardAfterSuccess = jest.fn(async () => {})
+    registerMutationGuards([{ moduleId: 'example', guards: [{
+      id: 'example.after-command-create',
+      targetEntity: 'example.todo',
+      operations: ['create'],
+      validate: async (_input: any) => ({ ok: true, shouldRunAfterSuccess: true }),
+      afterSuccess: guardAfterSuccess,
+    }] }])
+    const commandRoute = makeCrudRoute({
+      metadata: { POST: { requireAuth: true } },
+      orm: { entity: Todo, idField: 'id', orgField: 'organizationId', tenantField: 'tenantId', softDeleteField: 'deletedAt' },
+      indexer: { entityType: 'example.todo' },
+      actions: {
+        create: {
+          commandId: 'example.todo.create',
+          schema: createSchema,
+          response: ({ result }: any) => ({ id: result.lineId }),
+        },
+      },
+    })
+
+    const res = await commandRoute.POST(new Request('http://x/api/example/todos/command', {
+      method: 'POST',
+      body: JSON.stringify({ title: 'A' }),
+      headers: { 'content-type': 'application/json' },
+    }))
+
+    expect(res.status).toBe(201)
+    expect(guardAfterSuccess).toHaveBeenCalledWith(expect.objectContaining({
+      resourceId: 'line-42',
+      operation: 'create',
+    }))
+  })
+
+  // Commands whose mapInput wraps the payload (e.g. `{ body }`) null the factory
+  // candidateId and thereby OPT OUT of row-level mutation guards, leaving the
+  // command-level optimistic-lock check as the sole guard — a documented contract
+  // (apps/docs/docs/framework/data-integrity/concurrency-locking.mdx) that sales
+  // line/adjustment routes rely on.
+  it('PUT command route without a top-level id keeps the documented row-level guard opt-out', async () => {
+    crudMutationGuardService = {
+      validateMutation: jest.fn().mockResolvedValue({ ok: true, shouldRunAfterSuccess: false }),
+      afterMutationSuccess: jest.fn().mockResolvedValue(undefined),
+    }
+    const guardValidate = jest.fn(async (_input: any) => ({ ok: false, status: 409, message: 'must not run' }))
+    registerMutationGuards([{ moduleId: 'example', guards: [{
+      id: 'example.idless-update-opt-out',
+      targetEntity: 'example.todo',
+      operations: ['update'],
+      validate: guardValidate,
+    }] }])
+    const commandRoute = makeCrudRoute({
+      metadata: { PUT: { requireAuth: true } },
+      orm: { entity: Todo, idField: 'id', orgField: 'organizationId', tenantField: 'tenantId', softDeleteField: 'deletedAt' },
+      indexer: { entityType: 'example.todo' },
+      actions: {
+        update: {
+          commandId: 'example.todo.update',
+          schema: z.object({ title: z.string() }),
+          mapInput: ({ parsed }: any) => ({ body: parsed }),
+          response: () => ({ ok: true }),
+        },
+      },
+    })
+
+    const res = await commandRoute.PUT(new Request('http://x/api/example/todos/command', {
+      method: 'PUT',
+      body: JSON.stringify({ title: 'nested id shape' }),
+      headers: { 'content-type': 'application/json' },
+    }))
+
+    expect(res.status).toBe(200)
+    expect(guardValidate).not.toHaveBeenCalled()
+    expect(crudMutationGuardService.validateMutation).not.toHaveBeenCalled()
+    expect(commandBus.execute).toHaveBeenCalledWith('example.todo.update', expect.anything())
+  })
+
+  it('DELETE command route without any id keeps the documented row-level guard opt-out', async () => {
+    const guardValidate = jest.fn(async (_input: any) => ({ ok: false, status: 403, message: 'must not run' }))
+    registerMutationGuards([{ moduleId: 'example', guards: [{
+      id: 'example.idless-delete-opt-out',
+      targetEntity: 'example.todo',
+      operations: ['delete'],
+      validate: guardValidate,
+    }] }])
+    const commandRoute = makeCrudRoute({
+      metadata: { DELETE: { requireAuth: true } },
+      orm: { entity: Todo, idField: 'id', orgField: 'organizationId', tenantField: 'tenantId', softDeleteField: 'deletedAt' },
+      indexer: { entityType: 'example.todo' },
+      actions: {
+        delete: {
+          commandId: 'example.todo.delete',
+          schema: z.any(),
+          response: () => ({ ok: true }),
+        },
+      },
+    })
+
+    const res = await commandRoute.DELETE(new Request('http://x/api/example/todos/command', {
+      method: 'DELETE',
+      body: JSON.stringify({}),
+      headers: { 'content-type': 'application/json' },
+    }))
+
+    expect(res.status).toBe(200)
+    expect(guardValidate).not.toHaveBeenCalled()
+    expect(commandBus.execute).toHaveBeenCalledWith('example.todo.delete', expect.anything())
+  })
+
   it('POST is blocked by interceptor before hook', async () => {
     registerApiInterceptors([
       {
@@ -784,6 +1056,85 @@ describe('CRUD Factory', () => {
     const body = await res.json()
     expect(body._interceptor).toEqual({ ok: true, count: 1 })
   })
+
+  // The command DELETE path used to hand before-interceptors the body only, so a
+  // guard reading `?id=` saw nothing to object to and the delete went through
+  // with a 200 (issue #4842).
+  it('DELETE command route passes the query id to interceptor before hooks', async () => {
+    const lockedId = '123e4567-e89b-12d3-a456-426614174010'
+    const seenQueries: Array<Record<string, unknown> | undefined> = []
+    registerApiInterceptors([
+      {
+        moduleId: 'example',
+        interceptors: [
+          {
+            id: 'example.block-locked-delete',
+            targetRoute: 'example/todos/command',
+            methods: ['DELETE'],
+            async before(request) {
+              seenQueries.push(request.query)
+              const queryId = request.query?.id
+              if (typeof queryId === 'string' && queryId === lockedId) {
+                return { ok: false, statusCode: 409, message: 'Record is locked' }
+              }
+              return { ok: true }
+            },
+          },
+        ],
+      },
+    ])
+    const commandRoute = makeCrudRoute({
+      metadata: { DELETE: { requireAuth: true } },
+      orm: { entity: Todo, idField: 'id', orgField: 'organizationId', tenantField: 'tenantId', softDeleteField: 'deletedAt' },
+      indexer: { entityType: 'example.todo' },
+      actions: {
+        delete: {
+          commandId: 'example.todo.delete',
+          schema: z.any(),
+          response: () => ({ ok: true }),
+        },
+      },
+    })
+
+    const res = await commandRoute.DELETE(new Request(`http://x/api/example/todos/command?id=${lockedId}`, {
+      method: 'DELETE',
+      body: JSON.stringify({}),
+      headers: { 'content-type': 'application/json' },
+    }))
+
+    expect(res.status).toBe(409)
+    expect(await res.json()).toMatchObject({ error: 'Record is locked' })
+    expect(seenQueries).toEqual([{ id: lockedId }])
+    expect(commandBus.execute).not.toHaveBeenCalled()
+  })
+
+  it('DELETE route passes the whole query string to interceptor before hooks', async () => {
+    const created = em.create(Todo, { title: 'Z', organizationId: defaultOrganizationId, tenantId: defaultTenantId }) as Rec
+    created.id = '123e4567-e89b-12d3-a456-426614174011'
+    await em.persist(created).flush()
+    let seenQuery: Record<string, unknown> | undefined
+    registerApiInterceptors([
+      {
+        moduleId: 'example',
+        interceptors: [
+          {
+            id: 'example.capture-delete-query',
+            targetRoute: 'example/todos',
+            methods: ['DELETE'],
+            async before(request) {
+              seenQuery = request.query
+              return { ok: true }
+            },
+          },
+        ],
+      },
+    ])
+
+    const res = await route.DELETE(new Request(`http://x/api/example/todos?id=${created.id}&reason=cleanup`, { method: 'DELETE' }))
+
+    expect(res.status).toBe(200)
+    expect(seenQuery).toEqual({ id: created.id, reason: 'cleanup' })
+  })
 })
 
 describe('CRUD Factory — optimistic-lock auto-registration', () => {

package/src/lib/crud/__tests__/mutation-guard-registry.test.ts

@@ -1,5 +1,9 @@
 import { matchesEntity, runMutationGuards } from '../mutation-guard-registry'
 import type { MutationGuard, MutationGuardInput } from '../mutation-guard-registry'
+import {
+  applyAclFeatureOverrides,
+  resetModuleContractOverridesForTests,
+} from '../../../modules/overrides'
 
 describe('matchesEntity', () => {
   it('matches wildcard "*" against any entity', () => {
@@ -24,6 +28,10 @@ describe('matchesEntity', () => {
 })
 
 describe('runMutationGuards', () => {
+  afterEach(() => {
+    resetModuleContractOverridesForTests()
+  })
+
   const baseInput: MutationGuardInput = {
     tenantId: 'tenant-1',
     organizationId: 'org-1',
@@ -159,6 +167,24 @@ describe('runMutationGuards', () => {
     expect(resultWithWildcard.errorBody).toEqual({ error: 'Blocked by wildcard', guardId: 'g1' })
   })
 
+  it('does not run a guard gated by a nulled ACL feature', async () => {
+    applyAclFeatureOverrides({ 'premium.locks': null })
+    const guard = makeGuard({
+      id: 'g1',
+      features: ['premium.locks'],
+      validate: jest.fn().mockResolvedValue({ ok: false }),
+    })
+
+    const result = await runMutationGuards(
+      [guard],
+      baseInput,
+      { userFeatures: ['*', 'premium.locks'] },
+    )
+
+    expect(result.ok).toBe(true)
+    expect(guard.validate).not.toHaveBeenCalled()
+  })
+
   it('uses custom error body when provided', async () => {
     const guard = makeGuard({
       id: 'g1',

package/src/lib/crud/enricher-runner.ts

@@ -15,6 +15,7 @@ import type {
 import { getEnrichersForEntity } from './enricher-registry'
 import { logEnricherTiming } from '../umes/enricher-timing'
 import { createLogger } from '../logger'
+import { authorizeFeatures } from '../../security/featurePolicy'
 
 const logger = createLogger('shared').child({ component: 'umes' })
 
@@ -35,17 +36,7 @@ function hasRequiredFeatures(
 ): boolean {
   if (!enricher.features || enricher.features.length === 0) return true
   if (!userFeatures) return false
-  const hasFeature = (required: string): boolean => {
-    for (const granted of userFeatures) {
-      if (granted === '*' || granted === required) return true
-      if (granted.endsWith('.*')) {
-        const prefix = granted.slice(0, -1)
-        if (required.startsWith(prefix)) return true
-      }
-    }
-    return false
-  }
-  return enricher.features.every((feature) => hasFeature(feature))
+  return authorizeFeatures(enricher.features, { grantedFeatures: userFeatures })
 }
 
 function filterByACLAndTenant(

package/src/lib/crud/factory.ts

@@ -57,6 +57,7 @@ import {
   isCrudCacheEnabled,
   normalizeIdentifierValue,
   normalizeTagSegment,
+  pickFirstIdentifier,
   resolveCrudCache,
 } from './cache'
 import { deriveCrudSegmentTag } from './cache-stats'
@@ -72,6 +73,7 @@ import { parseExtensionHeaders } from '../umes/extension-headers'
 import { createGenericOptimisticLockReader } from './optimistic-lock'
 import { registerOptimisticLockReaderIfAbsent } from './optimistic-lock-store'
 import { createLogger } from '../logger'
+import { isTransientDbError } from '../db/pg-errors'
 
 type RbacServiceLike = {
   getGrantedFeatures: (userId: string, opts: { tenantId: string | null; organizationId: string | null }) => Promise<string[]>
@@ -250,6 +252,7 @@ const DEFAULT_EXPORT_FORMATS: CrudExportFormat[] = ['csv', 'json', 'xml', 'markd
 const DEFAULT_EXPORT_BATCH_SIZE = 1000
 const MIN_EXPORT_BATCH_SIZE = 100
 const MAX_EXPORT_BATCH_SIZE = 10000
+const EXPORT_MAX_PAGES = 1000
 
 type ColumnResolver = {
   field: string
@@ -554,6 +557,18 @@ function handleError(err: unknown): Response {
   if (err instanceof Response) return err
   if (isCrudHttpError(err)) return json(err.body, { status: err.status })
   if (err instanceof z.ZodError) return json({ error: 'Invalid input', details: err.issues }, { status: 400 })
+  if (isTransientDbError(err)) {
+    // Transient DB unavailability (pool exhausted, `max_connections` reached, DB
+    // restarting) is retryable — surface a 503 with a Retry-After hint instead of
+    // a generic 500 so clients back off and retry once the DB recovers.
+    logger.warn('Transient DB failure during CRUD handler', {
+      message: err instanceof Error ? err.message : undefined,
+    })
+    return json(
+      { error: 'Service temporarily unavailable' },
+      { status: 503, headers: { 'Retry-After': '2' } },
+    )
+  }
 
   const message = err instanceof Error ? err.message : undefined
   const stack = err instanceof Error ? err.stack : undefined
@@ -915,6 +930,12 @@ function buildCrudCacheKey(
     `tenant:${normalizeTagSegment(ctx.auth?.tenantId ?? null)}`,
     `selectedOrg:${normalizeTagSegment(ctx.selectedOrganizationId ?? null)}`,
     `scope:${scopeSegment}`,
+    // List payloads can vary per caller identity beyond tenant/org scope:
+    // buildFilters may narrow by ctx.auth (e.g. ?mine=true), before-interceptor
+    // query rewrites are feature-gated per user, and afterList/after-interceptor
+    // output is embedded in the stored payload — so entries MUST be partitioned
+    // per actor (API key or user), never shared across identities.
+    `user:${normalizeTagSegment((ctx.auth?.keyId ?? ctx.auth?.sub) ?? null)}`,
     `query:${serializeSearchParams(url.searchParams)}`,
   ]
   // The cached list payload already embeds enricher output (enrichment runs before
@@ -1786,13 +1807,17 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
           const initialExportItems = exportFullRequested
             ? rawItems.map(normalizeFullRecordForExport)
             : transformedItems
-          let exportItems = [...initialExportItems]
-          if (total > exportItems.length) {
-            const exportPageSizeNumber = typeof page.pageSize === 'number' ? page.pageSize : exportPageSize
+          const exportItems = [...initialExportItems]
+          const exportPageSizeNumber = typeof page.pageSize === 'number' ? page.pageSize : exportPageSize
+          // Short-page termination: `total` is a display value, not a loop bound — it can
+          // under-report (capped counts) or drift while rows are inserted/deleted mid-export.
+          // Keep fetching while pages come back full; fail closed at the page ceiling rather
+          // than serializing a partial export.
+          if (rawItems.length >= exportPageSizeNumber) {
             const queryBase: any = { ...queryOpts }
             delete queryBase.page
             let nextPage = 2
-            while (exportItems.length < total) {
+            for (;;) {
               profiler.mark('export_next_page_request', { page: nextPage })
               const nextRes = await qe.query(opts.list.entityId as any, {
                 ...queryBase,
@@ -1807,7 +1832,10 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
                 ? nextItemsRaw.map(normalizeFullRecordForExport)
                 : nextTransformed
               exportItems.push(...nextExportItems)
-              if (nextExportItems.length < exportPageSizeNumber) break
+              if (nextItemsRaw.length < exportPageSizeNumber) break
+              if (nextPage >= EXPORT_MAX_PAGES) {
+                throw new Error(`[internal] export exceeded ${EXPORT_MAX_PAGES} pages; refusing to return a partial export`)
+              }
               nextPage += 1
             }
           }
@@ -2140,6 +2168,31 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
           }
         }
 
+        // Mutation guard registry — command path (mirrors the direct create branch)
+        const createCmdUserFeatures = await resolveUserFeatures(ctx)
+        const { allGuards: createCmdAllGuards } = collectAndRunGuards(ctx.container)
+        let createCmdGuardAfterCallbacks: Array<{ guard: MutationGuard; metadata: Record<string, unknown> | null }> = []
+        if (createCmdAllGuards.length && ctx.auth.tenantId) {
+          const guardResult = await runMutationGuards(createCmdAllGuards, {
+            tenantId: ctx.auth.tenantId,
+            organizationId: ctx.selectedOrganizationId ?? ctx.auth.orgId ?? null,
+            userId: ctx.auth.sub,
+            resourceKind,
+            resourceId: null,
+            operation: 'create',
+            requestMethod: request.method,
+            requestHeaders: request.headers,
+            mutationPayload: input && typeof input === 'object' ? (input as Record<string, unknown>) : null,
+          }, { userFeatures: createCmdUserFeatures ?? [] })
+          if (!guardResult.ok) {
+            return json(guardResult.errorBody ?? { error: 'Operation blocked by guard' }, { status: guardResult.errorStatus ?? 422 })
+          }
+          if (guardResult.modifiedPayload && typeof input === 'object' && input) {
+            input = { ...input as Record<string, unknown>, ...guardResult.modifiedPayload }
+          }
+          createCmdGuardAfterCallbacks = guardResult.afterSuccessCallbacks
+        }
+
         const baseMetadata: CommandLogMetadata = {
           tenantId: ctx.auth?.tenantId ?? null,
           organizationId: ctx.selectedOrganizationId ?? ctx.auth.orgId ?? null,
@@ -2182,6 +2235,22 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
         const status = action.status ?? 201
         const response = json(resolvedPayload, { status })
         attachOperationHeader(response, logEntry)
+        const commandResultId = pickFirstIdentifier(
+          (result as Record<string, unknown> | null | undefined)?.id,
+          (resolvedPayload as Record<string, unknown> | null | undefined)?.id,
+        )
+        if (createCmdGuardAfterCallbacks.length && ctx.auth.tenantId && commandResultId) {
+          await runGuardAfterSuccessCallbacks(createCmdGuardAfterCallbacks, {
+            tenantId: ctx.auth.tenantId,
+            organizationId: ctx.selectedOrganizationId ?? ctx.auth.orgId ?? null,
+            userId: ctx.auth.sub,
+            resourceKind,
+            resourceId: commandResultId,
+            operation: 'create',
+            requestMethod: request.method,
+            requestHeaders: request.headers,
+          })
+        }
         // Note: side effects (events + indexing) are already flushed by CommandBus.execute()
         // via flushCrudSideEffects(). Calling markCommandResultForIndexing here would cause
         // duplicate event emissions.
@@ -2285,6 +2354,7 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
               organizationId: targetOrgId,
               tenantId: writeTenantId,
               values,
+              notify: false,
             })
           }
         }
@@ -2422,6 +2492,10 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
         const updateUserFeatures = await resolveUserFeatures(ctx)
         const { allGuards: updateAllGuards } = collectAndRunGuards(ctx.container)
         let cmdUpdateGuardAfterCallbacks: Array<{ guard: MutationGuard; metadata: Record<string, unknown> | null }> = []
+        // Commands whose mapInput wraps the payload (e.g. `{ body }`) intentionally
+        // null candidateId and OPT OUT of row-level guards, leaving the command-level
+        // optimistic-lock check as the sole guard — a documented contract, see
+        // apps/docs/docs/framework/data-integrity/concurrency-locking.mdx.
         if (updateAllGuards.length && ctx.auth.tenantId && candidateId) {
           const guardResult = await runMutationGuards(updateAllGuards, {
             tenantId: ctx.auth.tenantId,
@@ -2618,6 +2692,7 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
               organizationId: targetOrgId,
               tenantId: writeTenantId,
               values,
+              notify: false,
             })
           }
         }
@@ -2721,6 +2796,7 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
           request,
           method: 'DELETE',
           body: interceptorInput,
+          query: raw.query,
         })
         if (beforeInterceptors.errorResponse) return beforeInterceptors.errorResponse
         interceptorRequestPayload = beforeInterceptors.requestPayload
@@ -2845,7 +2921,7 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
         request,
         method: 'DELETE',
         body: idFrom === 'query' ? undefined : ({ id } as Record<string, unknown>),
-        query: idFrom === 'query' ? ({ id } as Record<string, unknown>) : undefined,
+        query: idFrom === 'query' ? Object.fromEntries(url.searchParams.entries()) : undefined,
       })
       if (beforeInterceptors.errorResponse) return beforeInterceptors.errorResponse
       interceptorRequestPayload = beforeInterceptors.requestPayload