@open-mercato/shared 0.6.8-develop.6899.1.433952fd93 → 0.6.8-develop.6907.1.2968c89bdf

package/dist/lib/version.js

@@ -1,4 +1,4 @@
-const APP_VERSION = "0.6.8-develop.6899.1.433952fd93";
+const APP_VERSION = "0.6.8-develop.6907.1.2968c89bdf";
 const appVersion = APP_VERSION;
 export {
   APP_VERSION,

package/dist/lib/version.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/lib/version.ts"],
-  "sourcesContent": ["// Build-time generated version\nexport const APP_VERSION = '0.6.8-develop.6899.1.433952fd93';\nexport const appVersion = APP_VERSION;\n"],
+  "sourcesContent": ["// Build-time generated version\nexport const APP_VERSION = '0.6.8-develop.6907.1.2968c89bdf';\nexport const appVersion = APP_VERSION;\n"],
   "mappings": "AACO,MAAM,cAAc;AACpB,MAAM,aAAa;",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/shared",
-  "version": "0.6.8-develop.6899.1.433952fd93",
+  "version": "0.6.8-develop.6907.1.2968c89bdf",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -105,7 +105,7 @@
     "@mikro-orm/core": "^7.1.8",
     "@mikro-orm/decorators": "^7.1.8",
     "@mikro-orm/postgresql": "^7.1.8",
-    "@open-mercato/cache": "0.6.8-develop.6899.1.433952fd93",
+    "@open-mercato/cache": "0.6.8-develop.6907.1.2968c89bdf",
     "@types/sanitize-html": "^2.16.1",
     "dotenv": "^17.4.2",
     "pino": "^10.3.1",

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

@@ -4,11 +4,15 @@ import {
   registerCommand,
   registerCommandLoaders,
   CommandBus,
+  isCommandInterceptorError,
 } from '@open-mercato/shared/lib/commands'
+import { registerCommandInterceptors } from '@open-mercato/shared/lib/commands/command-interceptor-store'
+import type { CommandInterceptor } from '@open-mercato/shared/lib/commands/command-interceptor'
 
 describe('CommandBus', () => {
   afterEach(() => {
     commandRegistry.clear()
+    registerCommandInterceptors([])
   })
 
   it('executes registered command and logs action metadata', async () => {
@@ -119,4 +123,63 @@ describe('CommandBus', () => {
     expect(result).toEqual({ ok: true })
     expect(execute).toHaveBeenCalledTimes(1)
   })
+
+  describe('interceptor rejections', () => {
+    const blockingInterceptor = (result: Record<string, unknown>): CommandInterceptor => ({
+      id: 'test.block',
+      targetCommand: 'test.*',
+      beforeExecute: async () => result,
+    })
+
+    const runBlockedCommand = async (interceptor: CommandInterceptor) => {
+      const execute = jest.fn(async () => ({ ok: true }))
+      registerCommand({ id: 'test.command.blocked', execute })
+      registerCommandInterceptors([{ moduleId: 'test', interceptors: [interceptor] }])
+
+      const container = createContainer({ injectionMode: InjectionMode.CLASSIC })
+      const bus = new CommandBus()
+      const ctx = {
+        container,
+        auth: { sub: 'user-4', tenantId: 'tenant-4', orgId: null },
+        organizationScope: null,
+        selectedOrganizationId: null,
+        organizationIds: null,
+      }
+
+      const error = await bus.execute('test.command.blocked', { input: {}, ctx }).catch((e: unknown) => e)
+      return { error, execute }
+    }
+
+    it('forwards the interceptor status and derived body onto the thrown error', async () => {
+      const { error, execute } = await runBlockedCommand(
+        blockingInterceptor({ ok: false, message: 'Missing required fields: VAT id', status: 422 }),
+      )
+
+      expect(isCommandInterceptorError(error)).toBe(true)
+      expect((error as { status?: number }).status).toBe(422)
+      expect((error as { body?: Record<string, unknown> }).body).toEqual({
+        error: 'Missing required fields: VAT id',
+      })
+      expect(execute).not.toHaveBeenCalled()
+    })
+
+    it('forwards an explicit interceptor body verbatim', async () => {
+      const body = { error: 'Blocked', missingFields: ['vatId'] }
+      const { error } = await runBlockedCommand(
+        blockingInterceptor({ ok: false, message: 'Blocked', status: 409, body }),
+      )
+
+      expect((error as { status?: number }).status).toBe(409)
+      expect((error as { body?: Record<string, unknown> }).body).toEqual(body)
+    })
+
+    it('leaves status and body undefined when the interceptor supplies no status', async () => {
+      const { error } = await runBlockedCommand(blockingInterceptor({ ok: false, message: 'Blocked' }))
+
+      expect(isCommandInterceptorError(error)).toBe(true)
+      expect((error as Error).message).toBe('Blocked')
+      expect((error as { status?: number }).status).toBeUndefined()
+      expect((error as { body?: unknown }).body).toBeUndefined()
+    })
+  })
 })

package/src/lib/commands/__tests__/command-interceptor-error.test.ts

@@ -1,4 +1,8 @@
-import { CommandInterceptorError } from '../errors'
+import {
+  CommandInterceptorError,
+  getCommandInterceptorHttpRejection,
+  isCommandInterceptorError,
+} from '../errors'
 
 describe('CommandInterceptorError', () => {
   it('has the correct name', () => {
@@ -15,4 +19,90 @@ describe('CommandInterceptorError', () => {
     const error = new CommandInterceptorError('test')
     expect(error).toBeInstanceOf(Error)
   })
+
+  it('carries no transport information when constructed with a message alone', () => {
+    const error = new CommandInterceptorError('test')
+    expect(error.status).toBeUndefined()
+    expect(error.body).toBeUndefined()
+  })
+
+  it('carries the status and derives the body from the message', () => {
+    const error = new CommandInterceptorError('Missing required fields: VAT id', { status: 422 })
+    expect(error.status).toBe(422)
+    expect(error.body).toEqual({ error: 'Missing required fields: VAT id' })
+  })
+
+  it('keeps an explicit body verbatim', () => {
+    const body = { error: 'Blocked', missingFields: ['vatId'] }
+    const error = new CommandInterceptorError('Blocked', { status: 422, body })
+    expect(error.body).toEqual(body)
+  })
+
+  it('ignores a body supplied without a status, so status and body move together', () => {
+    const error = new CommandInterceptorError('Blocked', { body: { error: 'Blocked' } })
+    expect(error.status).toBeUndefined()
+    expect(error.body).toBeUndefined()
+  })
+
+  it('preserves the cause when one is supplied', () => {
+    const cause = new Error('underlying')
+    const error = new CommandInterceptorError('Blocked', { cause })
+    expect(error.cause).toBe(cause)
+  })
+
+  it('is detected by isCommandInterceptorError across module boundaries', () => {
+    expect(isCommandInterceptorError(new CommandInterceptorError('test'))).toBe(true)
+    // A structurally identical error from a duplicated bundle carries the same registered symbol.
+    const duplicated = Object.assign(new Error('test'), {
+      [Symbol.for('@open-mercato/CommandInterceptorError')]: true,
+    })
+    expect(isCommandInterceptorError(duplicated)).toBe(true)
+  })
+
+  it('does not treat unrelated values as interceptor errors', () => {
+    expect(isCommandInterceptorError(new Error('plain'))).toBe(false)
+    expect(isCommandInterceptorError(null)).toBe(false)
+    expect(isCommandInterceptorError('CommandInterceptorError')).toBe(false)
+  })
+})
+
+describe('getCommandInterceptorHttpRejection', () => {
+  it('returns the status and body of a status-carrying rejection', () => {
+    const error = new CommandInterceptorError('Missing required fields: VAT id', { status: 422 })
+    expect(getCommandInterceptorHttpRejection(error)).toEqual({
+      status: 422,
+      body: { error: 'Missing required fields: VAT id' },
+    })
+  })
+
+  it('returns the explicit body when the interceptor supplied one', () => {
+    const body = { error: 'Blocked', missingFields: ['vatId'] }
+    const error = new CommandInterceptorError('Blocked', { status: 409, body })
+    expect(getCommandInterceptorHttpRejection(error)).toEqual({ status: 409, body })
+  })
+
+  it('returns null for a rejection that carries no status', () => {
+    expect(getCommandInterceptorHttpRejection(new CommandInterceptorError('Blocked'))).toBeNull()
+  })
+
+  it('returns null for errors that are not interceptor rejections', () => {
+    expect(getCommandInterceptorHttpRejection(new Error('plain'))).toBeNull()
+    expect(getCommandInterceptorHttpRejection(null)).toBeNull()
+  })
+
+  it('rejects a status outside 4xx/5xx so the transport layer keeps its generic handling', () => {
+    // Statuses arrive as third-party interceptor data: outside 200-599 the Response constructor
+    // throws RangeError, and a 2xx would report a deliberate block as a success.
+    for (const status of [200, 302, 399, 600, 999, 0, -1]) {
+      const error = Object.assign(new CommandInterceptorError('Blocked'), { status })
+      expect(getCommandInterceptorHttpRejection(error)).toBeNull()
+    }
+  })
+
+  it('rejects a non-integer status', () => {
+    for (const status of [Number.NaN, 422.5, Number.POSITIVE_INFINITY]) {
+      const error = Object.assign(new CommandInterceptorError('Blocked'), { status })
+      expect(getCommandInterceptorHttpRejection(error)).toBeNull()
+    }
+  })
 })

package/src/lib/commands/__tests__/command-interceptor-runner.test.ts

@@ -112,6 +112,56 @@ describe('runCommandInterceptorsBefore', () => {
     expect(i2.beforeExecute).not.toHaveBeenCalled()
   })
 
+  // Issue #5045 — a rejection only carries transport information when the interceptor asks for it.
+  it('omits status and body when the rejection carries no status', async () => {
+    const interceptor = makeInterceptor({
+      id: 'i1',
+      beforeExecute: jest.fn().mockResolvedValue({ ok: false, message: 'Blocked' }),
+    })
+    const result = await runCommandInterceptorsBefore([interceptor], 'customers.create-person', {}, baseContext, [])
+    expect(result.error).toEqual({ message: 'Blocked' })
+  })
+
+  it('propagates the status and derives a body from the message', async () => {
+    const interceptor = makeInterceptor({
+      id: 'i1',
+      beforeExecute: jest.fn().mockResolvedValue({ ok: false, message: 'Missing required fields', status: 422 }),
+    })
+    const result = await runCommandInterceptorsBefore([interceptor], 'customers.create-person', {}, baseContext, [])
+    expect(result.error).toEqual({
+      message: 'Missing required fields',
+      status: 422,
+      body: { error: 'Missing required fields' },
+    })
+  })
+
+  it('propagates an explicit body alongside the status', async () => {
+    const interceptor = makeInterceptor({
+      id: 'i1',
+      beforeExecute: jest.fn().mockResolvedValue({
+        ok: false,
+        message: 'Blocked',
+        status: 422,
+        body: { error: 'Blocked', missingFields: ['vatId'] },
+      }),
+    })
+    const result = await runCommandInterceptorsBefore([interceptor], 'customers.create-person', {}, baseContext, [])
+    expect(result.error?.body).toEqual({ error: 'Blocked', missingFields: ['vatId'] })
+  })
+
+  it('falls back to the generated message when a status-carrying rejection has none', async () => {
+    const interceptor = makeInterceptor({
+      id: 'i1',
+      beforeExecute: jest.fn().mockResolvedValue({ ok: false, status: 422 }),
+    })
+    const result = await runCommandInterceptorsBefore([interceptor], 'customers.create-person', {}, baseContext, [])
+    expect(result.error).toEqual({
+      message: 'Blocked by command interceptor: i1',
+      status: 422,
+      body: { error: 'Blocked by command interceptor: i1' },
+    })
+  })
+
   it('accumulates modified input', async () => {
     const i1 = makeInterceptor({
       id: 'i1',
@@ -236,6 +286,29 @@ describe('runCommandInterceptorsBeforeUndo', () => {
     expect(result.ok).toBe(false)
     expect(result.error?.message).toBe('Cannot undo')
   })
+
+  // Issue #5045 — the undo path shares the before-result contract, so it carries a status too.
+  it('omits status and body when the undo rejection carries no status', async () => {
+    const interceptor = makeInterceptor({
+      id: 'i1',
+      beforeUndo: jest.fn().mockResolvedValue({ ok: false, message: 'Cannot undo' }),
+    })
+    const result = await runCommandInterceptorsBeforeUndo([interceptor], 'customers.create-person', undoContext, baseContext, [])
+    expect(result.error).toEqual({ message: 'Cannot undo' })
+  })
+
+  it('propagates the status and body of an undo rejection', async () => {
+    const interceptor = makeInterceptor({
+      id: 'i1',
+      beforeUndo: jest.fn().mockResolvedValue({ ok: false, message: 'Cannot undo a settled invoice', status: 409 }),
+    })
+    const result = await runCommandInterceptorsBeforeUndo([interceptor], 'customers.create-person', undoContext, baseContext, [])
+    expect(result.error).toEqual({
+      message: 'Cannot undo a settled invoice',
+      status: 409,
+      body: { error: 'Cannot undo a settled invoice' },
+    })
+  })
 })
 
 describe('runCommandInterceptorsAfterUndo', () => {

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

@@ -245,7 +245,8 @@ export class CommandBus {
         allInterceptors, commandId, options.input, interceptorCtx, userFeatures,
       )
       if (!beforeResult.ok) {
-        throw new CommandInterceptorError(beforeResult.error!.message)
+        const blocked = beforeResult.error!
+        throw new CommandInterceptorError(blocked.message, { status: blocked.status, body: blocked.body })
       }
       interceptorMetadata = beforeResult.metadataByInterceptor
       if (beforeResult.modifiedInput) {
@@ -363,7 +364,8 @@ export class CommandBus {
           allInterceptors, log.commandId, undoCtx, interceptorCtx, userFeatures,
         )
         if (!beforeResult.ok) {
-          throw new CommandInterceptorError(beforeResult.error!.message)
+          const blocked = beforeResult.error!
+          throw new CommandInterceptorError(blocked.message, { status: blocked.status, body: blocked.body })
         }
         undoInterceptorMetadata = beforeResult.metadataByInterceptor
       }

package/src/lib/commands/command-interceptor-runner.ts

@@ -1,5 +1,6 @@
 import type {
   CommandInterceptor,
+  CommandInterceptorBeforeResult,
   CommandInterceptorContext,
   CommandInterceptorUndoContext,
 } from './command-interceptor'
@@ -8,6 +9,26 @@ import { createLogger } from '../logger'
 
 const logger = createLogger('shared').child({ component: 'commands' })
 
+/**
+ * A blocking verdict from a before-hook, normalized for the command bus. `status`/`body` are
+ * present only when the interceptor supplied a status, so a rejection without one keeps the
+ * historical generic-500 handling downstream.
+ */
+export type CommandInterceptorBlockedError = {
+  message: string
+  status?: number
+  body?: Record<string, unknown>
+}
+
+function buildBlockedError(
+  result: CommandInterceptorBeforeResult,
+  fallbackMessage: string,
+): CommandInterceptorBlockedError {
+  const message = result.message ?? fallbackMessage
+  if (typeof result.status !== 'number') return { message }
+  return { message, status: result.status, body: result.body ?? { error: message } }
+}
+
 // ---------------------------------------------------------------------------
 // Command pattern matching
 // ---------------------------------------------------------------------------
@@ -49,7 +70,7 @@ export async function runCommandInterceptorsBefore(
   userFeatures: string[],
 ): Promise<{
   ok: boolean
-  error?: { message: string }
+  error?: CommandInterceptorBlockedError
   modifiedInput?: Record<string, unknown>
   metadataByInterceptor: Map<string, Record<string, unknown>>
 }> {
@@ -65,7 +86,7 @@ export async function runCommandInterceptorsBefore(
     if (result?.ok === false) {
       return {
         ok: false,
-        error: { message: result.message ?? `Blocked by command interceptor: ${interceptor.id}` },
+        error: buildBlockedError(result, `Blocked by command interceptor: ${interceptor.id}`),
         metadataByInterceptor,
       }
     }
@@ -139,7 +160,7 @@ export async function runCommandInterceptorsBeforeUndo(
   userFeatures: string[],
 ): Promise<{
   ok: boolean
-  error?: { message: string }
+  error?: CommandInterceptorBlockedError
   metadataByInterceptor: Map<string, Record<string, unknown>>
 }> {
   const matching = collectMatching(interceptors, commandId, userFeatures)
@@ -153,7 +174,7 @@ export async function runCommandInterceptorsBeforeUndo(
     if (result?.ok === false) {
       return {
         ok: false,
-        error: { message: result.message ?? `Undo blocked by command interceptor: ${interceptor.id}` },
+        error: buildBlockedError(result, `Undo blocked by command interceptor: ${interceptor.id}`),
         metadataByInterceptor,
       }
     }

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

@@ -67,6 +67,14 @@ export interface CommandInterceptorBeforeResult {
   ok?: boolean
   /** Error message when blocking */
   message?: string
+  /**
+   * HTTP status code when blocking. Omit to keep the historical behaviour, where a rejection
+   * without a status surfaces as a generic 500 — set it (e.g. 422) to have the CRUD transport
+   * layer answer with a deliberate business-rejection status instead.
+   */
+  status?: number
+  /** Error body when blocking (overrides message). Only used together with `status`. */
+  body?: Record<string, unknown>
   /** Modified input — shallow-merged into command input if ok:true */
   modifiedInput?: Record<string, unknown>
   /** Metadata passed to the corresponding after hook */

package/src/lib/commands/errors.ts

@@ -1,6 +1,71 @@
+// Use Symbol.for so the marker survives module duplication across bundle boundaries
+// (same behaviour as CrudHttpError and the globalThis-based DI registries)
+const COMMAND_INTERCEPTOR_ERROR_MARKER = Symbol.for('@open-mercato/CommandInterceptorError')
+
+export type CommandInterceptorErrorOptions = {
+  /** HTTP status the transport layer should answer with. Omit to keep the generic 500. */
+  status?: number
+  /**
+   * Response body the transport layer should answer with, defaulting to `{ error: message }`.
+   * Only meaningful together with `status` — a body on its own is ignored, mirroring the same
+   * rule on `CommandInterceptorBeforeResult`.
+   */
+  body?: Record<string, unknown>
+  cause?: unknown
+}
+
 export class CommandInterceptorError extends Error {
-  constructor(message: string) {
-    super(message)
+  readonly [COMMAND_INTERCEPTOR_ERROR_MARKER] = true
+  /**
+   * HTTP status a deliberate interceptor rejection wants to surface. `undefined` when the
+   * interceptor supplied none, in which case the transport layer keeps its generic 500.
+   */
+  readonly status?: number
+  /**
+   * Response body for the rejection — `options.body`, else `{ error: message }`. Set only
+   * alongside `status`, so the two are always populated together or not at all.
+   */
+  readonly body?: Record<string, unknown>
+
+  constructor(message: string, options?: CommandInterceptorErrorOptions) {
+    super(message, options?.cause !== undefined ? { cause: options.cause } : undefined)
     this.name = 'CommandInterceptorError'
+    if (typeof options?.status === 'number') {
+      this.status = options.status
+      this.body = options.body ?? { error: message }
+    }
   }
 }
+
+/**
+ * Type-safe check for CommandInterceptorError that works across module/bundle boundaries.
+ * Prefer this over `instanceof CommandInterceptorError` whenever the error may originate
+ * from a different module bundle (e.g. enterprise packages, dynamic imports).
+ */
+export function isCommandInterceptorError(err: unknown): err is CommandInterceptorError {
+  return !!err && typeof err === 'object'
+    && (err as Record<symbol, unknown>)[COMMAND_INTERCEPTOR_ERROR_MARKER] === true
+}
+
+export type CommandInterceptorHttpRejection = {
+  status: number
+  body: Record<string, unknown>
+}
+
+const MIN_REJECTION_STATUS = 400
+const MAX_REJECTION_STATUS = 599
+
+/**
+ * Transport data for a deliberate interceptor rejection, or `null` when the error is not one or
+ * carries no usable status. The status is restricted to 4xx/5xx on purpose: interceptor data is
+ * third-party input travelling through the runner and the bus, `new Response(body, { status })`
+ * throws `RangeError` outside 200-599, and a rejection answered with a 2xx would report a block as
+ * a success. Anything else falls through to the caller's generic handling.
+ */
+export function getCommandInterceptorHttpRejection(err: unknown): CommandInterceptorHttpRejection | null {
+  if (!isCommandInterceptorError(err)) return null
+  const status = err.status
+  if (typeof status !== 'number' || !Number.isInteger(status)) return null
+  if (status < MIN_REJECTION_STATUS || status > MAX_REJECTION_STATUS) return null
+  return { status, body: err.body ?? { error: err.message } }
+}

package/src/lib/commands/index.ts

@@ -4,7 +4,13 @@ export { CommandBus } from './command-bus'
 export * from './customFieldSnapshots'
 export * from './undo'
 export * from './redo'
-export { CommandInterceptorError } from './errors'
+export {
+  CommandInterceptorError,
+  isCommandInterceptorError,
+  getCommandInterceptorHttpRejection,
+  type CommandInterceptorErrorOptions,
+  type CommandInterceptorHttpRejection,
+} from './errors'
 export {
   runCrudCommandWrite,
   type RunCrudCommandWriteOptions,

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

@@ -11,6 +11,7 @@ import {
 } 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 { CommandInterceptorError } from '@open-mercato/shared/lib/commands/errors'
 import { z } from 'zod'
 
 // Keep the real custom-field helpers but spy on the definition loader so we can
@@ -983,6 +984,78 @@ describe('CRUD Factory', () => {
     }))
   })
 
+  // Issue #5045 — a deliberate interceptor rejection must not be laundered into a generic 500.
+  const interceptorErrorRoute = () => 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 postInterceptorErrorRequest = (route: ReturnType<typeof interceptorErrorRoute>) => route.POST(
+    new Request('http://x/api/example/todos/command', {
+      method: 'POST',
+      body: JSON.stringify({ title: 'A' }),
+      headers: { 'content-type': 'application/json' },
+    }),
+  )
+
+  it('POST command route keeps the generic 500 when an interceptor blocks without a status', async () => {
+    commandBus.execute.mockRejectedValue(new CommandInterceptorError('Missing required fields: VAT id'))
+
+    const res = await postInterceptorErrorRequest(interceptorErrorRoute())
+
+    expect(res.status).toBe(500)
+    await expect(res.json()).resolves.toEqual({
+      error: 'Internal server error',
+      message: 'Something went wrong. Please try again later.',
+    })
+  })
+
+  it('POST command route surfaces the interceptor status and message when the block carries a status', async () => {
+    commandBus.execute.mockRejectedValue(
+      new CommandInterceptorError('Missing required fields: VAT id', { status: 422 }),
+    )
+
+    const res = await postInterceptorErrorRequest(interceptorErrorRoute())
+
+    expect(res.status).toBe(422)
+    await expect(res.json()).resolves.toEqual({ error: 'Missing required fields: VAT id' })
+  })
+
+  it('POST command route surfaces the interceptor body verbatim when one is supplied', async () => {
+    commandBus.execute.mockRejectedValue(
+      new CommandInterceptorError('Blocked', { status: 422, body: { error: 'Blocked', missingFields: ['vatId'] } }),
+    )
+
+    const res = await postInterceptorErrorRequest(interceptorErrorRoute())
+
+    expect(res.status).toBe(422)
+    await expect(res.json()).resolves.toEqual({ error: 'Blocked', missingFields: ['vatId'] })
+  })
+
+  it('POST command route keeps the generic 500 when the interceptor status is outside 4xx/5xx', async () => {
+    // A status the Response constructor would reject (or that would report a block as success)
+    // must not escape handleError as a RangeError — it falls back to the generic 500 instead.
+    commandBus.execute.mockRejectedValue(
+      Object.assign(new CommandInterceptorError('Blocked'), { status: 600, body: { error: 'Blocked' } }),
+    )
+
+    const res = await postInterceptorErrorRequest(interceptorErrorRoute())
+
+    expect(res.status).toBe(500)
+    await expect(res.json()).resolves.toEqual({
+      error: 'Internal server error',
+      message: 'Something went wrong. Please try again later.',
+    })
+  })
+
   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 () => {})

package/src/lib/crud/factory.ts

@@ -8,6 +8,7 @@ import { SortDir } from '@open-mercato/shared/lib/query/types'
 import type { DataEngine } from '@open-mercato/shared/lib/data/engine'
 import { resolveOrganizationScopeForRequest, type OrganizationScope } from '@open-mercato/core/modules/directory/utils/organizationScope'
 import { serializeOperationMetadata } from '@open-mercato/shared/lib/commands/operationMetadata'
+import { getCommandInterceptorHttpRejection } from '@open-mercato/shared/lib/commands/errors'
 import { parseBooleanToken } from '@open-mercato/shared/lib/boolean'
 import {
   runMutationGuards,
@@ -586,6 +587,13 @@ function attachOperationHeader(res: Response, logEntry: any) {
 function handleError(err: unknown): Response {
   if (err instanceof Response) return err
   if (isCrudHttpError(err)) return json(err.body, { status: err.status })
+  // A command interceptor that blocked with an explicit status is a deliberate business
+  // rejection, not a server fault — surface its status and message instead of a generic 500.
+  // Without a usable status the error falls through to the historical handling below (issue #5045).
+  const interceptorRejection = getCommandInterceptorHttpRejection(err)
+  if (interceptorRejection) {
+    return json(interceptorRejection.body, { status: interceptorRejection.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