@open-mercato/shared 0.8.1-develop.7228.1.b7ea09d2d3 → 0.8.1-develop.7238.1.3abe669ea5

package/src/lib/availability/__tests__/registry.test.ts

@@ -0,0 +1,115 @@
+import { availabilityProviderRegistry, resolveAvailability, AVAILABILITY_CATALOG_ONLY_PROVIDER_ID } from '../registry'
+import type { AvailabilityModuleConfigReader } from '../registry'
+import type { AvailabilityProvider, AvailabilityQuery, AvailabilityResult } from '../types'
+
+function makeProvider(id: string, result: Partial<AvailabilityResult['byItem'][string]> = {}): AvailabilityProvider {
+  return {
+    id,
+    async getAvailability(query: AvailabilityQuery): Promise<AvailabilityResult> {
+      const byItem: AvailabilityResult['byItem'] = {}
+      for (const item of query.items) {
+        const key = `${item.catalogProductId}:${item.catalogVariantId ?? ''}`
+        byItem[key] = {
+          state: 'in_stock',
+          availableQuantity: 100,
+          canFulfil: true,
+          leadTimeDays: null,
+          releaseAt: null,
+          isAuthoritative: true,
+          policySourceId: null,
+          ...result,
+        }
+      }
+      return { byItem }
+    },
+  }
+}
+
+function makeQuery(overrides: Partial<AvailabilityQuery> = {}): AvailabilityQuery {
+  return {
+    tenantId: 'tenant-1',
+    organizationId: 'org-1',
+    items: [{ catalogProductId: 'product-1', catalogVariantId: 'variant-1', quantity: 1 }],
+    ...overrides,
+  }
+}
+
+describe('availabilityProviderRegistry', () => {
+  beforeEach(() => {
+    availabilityProviderRegistry.reset()
+  })
+
+  it('registers and retrieves providers by id', () => {
+    const provider = makeProvider('alpha')
+    availabilityProviderRegistry.register(provider)
+    expect(availabilityProviderRegistry.get('alpha')).toBe(provider)
+    expect(availabilityProviderRegistry.get('missing')).toBeNull()
+  })
+
+  it('is idempotent — replaces by id rather than duplicating', () => {
+    const first = makeProvider('alpha')
+    const second = makeProvider('alpha')
+    availabilityProviderRegistry.register(first)
+    availabilityProviderRegistry.register(second)
+    expect(availabilityProviderRegistry.list()).toHaveLength(1)
+    expect(availabilityProviderRegistry.get('alpha')).toBe(second)
+  })
+
+  it('lists providers in registration order', () => {
+    availabilityProviderRegistry.register(makeProvider('first'))
+    availabilityProviderRegistry.register(makeProvider('second'))
+    expect(availabilityProviderRegistry.list().map((p) => p.id)).toEqual(['first', 'second'])
+  })
+
+  it('rejects a provider with an empty id', () => {
+    expect(() => availabilityProviderRegistry.register({ id: '', getAvailability: async () => ({ byItem: {} }) })).toThrow()
+  })
+})
+
+describe('resolveAvailability', () => {
+  beforeEach(() => {
+    availabilityProviderRegistry.reset()
+  })
+
+  it('falls back to catalog-only when nothing else is registered and selection is auto', async () => {
+    availabilityProviderRegistry.register(makeProvider(AVAILABILITY_CATALOG_ONLY_PROVIDER_ID, { state: 'not_tracked', availableQuantity: null }))
+    const result = await resolveAvailability(makeQuery())
+    expect(result.byItem['product-1:variant-1'].state).toBe('not_tracked')
+  })
+
+  it("'auto' picks the highest-precedence non-catalog-only registrant", async () => {
+    availabilityProviderRegistry.register(makeProvider(AVAILABILITY_CATALOG_ONLY_PROVIDER_ID, { state: 'not_tracked' }))
+    availabilityProviderRegistry.register(makeProvider('wms', { state: 'in_stock' }))
+    const result = await resolveAvailability(makeQuery())
+    expect(result.byItem['product-1:variant-1'].state).toBe('in_stock')
+  })
+
+  it('honors an explicit selection via the injected module-config reader', async () => {
+    availabilityProviderRegistry.register(makeProvider(AVAILABILITY_CATALOG_ONLY_PROVIDER_ID, { state: 'not_tracked' }))
+    availabilityProviderRegistry.register(makeProvider('wms', { state: 'in_stock' }))
+    const moduleConfig: AvailabilityModuleConfigReader = {
+      getValue: async () => 'catalog-only',
+    }
+    const result = await resolveAvailability(makeQuery(), { moduleConfig })
+    expect(result.byItem['product-1:variant-1'].state).toBe('not_tracked')
+  })
+
+  it('falls back to catalog-only when the selected id is not currently registered', async () => {
+    availabilityProviderRegistry.register(makeProvider(AVAILABILITY_CATALOG_ONLY_PROVIDER_ID, { state: 'not_tracked' }))
+    const moduleConfig: AvailabilityModuleConfigReader = {
+      getValue: async () => 'some-unregistered-provider',
+    }
+    const result = await resolveAvailability(makeQuery(), { moduleConfig })
+    expect(result.byItem['product-1:variant-1'].state).toBe('not_tracked')
+  })
+
+  it('defaults to auto when the module-config reader is omitted', async () => {
+    availabilityProviderRegistry.register(makeProvider('wms', { state: 'in_stock' }))
+    const result = await resolveAvailability(makeQuery())
+    expect(result.byItem['product-1:variant-1'].state).toBe('in_stock')
+  })
+
+  it('throws when no provider is registered at all', async () => {
+    await expect(resolveAvailability(makeQuery())).rejects.toThrow()
+  })
+})

package/src/lib/availability/catalogOnlyProvider.ts

@@ -0,0 +1,119 @@
+/**
+ * The built-in `catalog-only` fallback provider. Always registered so a
+ * `wms`-less *and* `availability`-less storefront stays fully functional.
+ *
+ * @see .ai/specs/2026-08-14-availability-contract.md §4.3
+ */
+
+import { availabilityItemKey } from './types'
+import type { AvailabilityItemResult, AvailabilityQuery, AvailabilityResult } from './types'
+import { availabilityProviderRegistry, AVAILABILITY_CATALOG_ONLY_PROVIDER_ID } from './registry'
+
+/** Per-item policy signal the optional lookup hook may report. */
+export type CatalogOnlyPolicyOverride = {
+  /** `true` → the item is explicitly opted into stock tracking with no data source behind it (§4.3, out_of_stock). */
+  isStockManaged?: boolean
+  /** `false` → the policy row is inactive; treated as out_of_stock. */
+  isActive?: boolean
+  /** ISO-8601. In the future → `preorder`. */
+  preorderReleaseAt?: string | null
+  /** The `AvailabilityPolicy` row id that produced this override. */
+  policySourceId?: string | null
+}
+
+/**
+ * Optional soft lookup into `AvailabilityPolicy` when the `availability`
+ * module is installed. Keyed by `availabilityItemKey()`. Returning `null` or
+ * omitting an item from the map means "no policy row — module default".
+ */
+export type CatalogOnlyPolicyLookup = (
+  query: AvailabilityQuery,
+) => Promise<Record<string, CatalogOnlyPolicyOverride | null | undefined>>
+
+let policyLookup: CatalogOnlyPolicyLookup | null = null
+
+/**
+ * Wired by the `availability` module's `di.ts` at container-build time
+ * (closure captures the container, mirroring `wms/di.ts`'s own provider
+ * registration) — never a static import from `packages/shared`. Pass `null`
+ * to clear (test isolation).
+ */
+export function setCatalogOnlyPolicyLookup(lookup: CatalogOnlyPolicyLookup | null): void {
+  policyLookup = lookup
+}
+
+function pureFallbackItem(): AvailabilityItemResult {
+  return {
+    state: 'not_tracked',
+    availableQuantity: null,
+    canFulfil: true,
+    leadTimeDays: null,
+    releaseAt: null,
+    isAuthoritative: true,
+    policySourceId: null,
+  }
+}
+
+/**
+ * Applies decision 7's matrix (see PLAN.md § Key design decisions) for a
+ * resolved policy override on top of the pure fallback.
+ */
+function applyOverride(override: CatalogOnlyPolicyOverride | null | undefined): AvailabilityItemResult {
+  const base = pureFallbackItem()
+  if (!override) return base
+
+  const policySourceId = override.policySourceId ?? null
+
+  if (override.preorderReleaseAt) {
+    const releaseAt = new Date(override.preorderReleaseAt)
+    if (!Number.isNaN(releaseAt.getTime()) && releaseAt.getTime() > Date.now()) {
+      return {
+        ...base,
+        state: 'preorder',
+        canFulfil: true,
+        releaseAt: override.preorderReleaseAt,
+        policySourceId,
+      }
+    }
+  }
+
+  if (override.isActive === false) {
+    return { ...base, state: 'out_of_stock', canFulfil: false, policySourceId }
+  }
+
+  if (override.isStockManaged === true) {
+    // Opted into stock tracking with no data source to verify against — see
+    // decision 7: this is the "policy explicitly marks the item unavailable"
+    // case rather than a silent "in stock" claim (R5).
+    return { ...base, state: 'out_of_stock', canFulfil: false, policySourceId }
+  }
+
+  return { ...base, policySourceId }
+}
+
+async function getAvailability(query: AvailabilityQuery): Promise<AvailabilityResult> {
+  const byItem: AvailabilityResult['byItem'] = {}
+
+  let overrides: Record<string, CatalogOnlyPolicyOverride | null | undefined> = {}
+  if (policyLookup) {
+    try {
+      overrides = await policyLookup(query)
+    } catch {
+      // Degrade gracefully to the pure fallback — never let an optional
+      // policy lookup failure break the always-available fallback provider.
+      overrides = {}
+    }
+  }
+
+  for (const item of query.items) {
+    const key = availabilityItemKey(item)
+    byItem[key] = applyOverride(overrides[key])
+  }
+
+  return { byItem }
+}
+
+availabilityProviderRegistry.register({
+  id: AVAILABILITY_CATALOG_ONLY_PROVIDER_ID,
+  getAvailability,
+})

package/src/lib/availability/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Public entrypoint for the Availability Contract's shared, dependency-free
+ * base — types, the provider registry, `resolveAvailability()`, and the
+ * built-in `catalog-only` fallback.
+ *
+ * Importing from this barrel (rather than `./registry` directly) guarantees
+ * the `catalog-only` provider is registered — it self-registers as an import
+ * side effect in `./catalogOnlyProvider`, which this file always pulls in.
+ *
+ * @see .ai/specs/2026-08-14-availability-contract.md §4.1a
+ */
+
+export * from './types'
+export * from './registry'
+export { setCatalogOnlyPolicyLookup } from './catalogOnlyProvider'
+export type { CatalogOnlyPolicyLookup, CatalogOnlyPolicyOverride } from './catalogOnlyProvider'
+
+import './catalogOnlyProvider'

package/src/lib/availability/registry.ts

@@ -0,0 +1,120 @@
+/**
+ * Availability provider registry — module-level singleton that collects
+ * registered providers and dispatches `resolveAvailability()` to the
+ * per-tenant selected one, falling back safely to the built-in
+ * `catalog-only` provider.
+ *
+ * Mirrors `packages/shared/src/lib/ai/llm-provider-registry.ts`.
+ *
+ * @see ./types
+ * @see .ai/specs/2026-08-14-availability-contract.md §4.1a
+ */
+
+import type { AvailabilityProvider, AvailabilityQuery, AvailabilityResult } from './types'
+
+export const AVAILABILITY_CATALOG_ONLY_PROVIDER_ID = 'catalog-only'
+
+/** Public interface of the registry. Exposed as a singleton via {@link availabilityProviderRegistry}. */
+export interface AvailabilityProviderRegistry {
+  /**
+   * Registers or replaces a provider. Registration is idempotent — calling
+   * with the same id replaces the existing entry. Never order-dependent.
+   */
+  register(provider: AvailabilityProvider): void
+
+  /** Returns the provider with the given id, or null when not registered. */
+  get(id: string): AvailabilityProvider | null
+
+  /** Returns all registered providers in registration order. */
+  list(): readonly AvailabilityProvider[]
+
+  /** Removes all registered providers. Intended for test isolation. */
+  reset(): void
+}
+
+class AvailabilityProviderRegistryImpl implements AvailabilityProviderRegistry {
+  // Preserves registration order via Map iteration semantics.
+  private readonly providers = new Map<string, AvailabilityProvider>()
+
+  register(provider: AvailabilityProvider): void {
+    if (!provider || typeof provider.id !== 'string' || provider.id.length === 0) {
+      throw new Error('[internal] AvailabilityProviderRegistry: provider must have a non-empty id')
+    }
+    // Idempotent: replace existing by id.
+    this.providers.set(provider.id, provider)
+  }
+
+  get(id: string): AvailabilityProvider | null {
+    return this.providers.get(id) ?? null
+  }
+
+  list(): readonly AvailabilityProvider[] {
+    return Array.from(this.providers.values())
+  }
+
+  reset(): void {
+    this.providers.clear()
+  }
+}
+
+/** Process-level singleton instance of the registry. */
+export const availabilityProviderRegistry: AvailabilityProviderRegistry = new AvailabilityProviderRegistryImpl()
+
+export type AvailabilityProviderSelection = 'auto' | 'catalog-only' | (string & {})
+
+/**
+ * Narrow port for per-tenant provider selection — declared locally so this
+ * package stays dependency-free. A caller with DI access (an `availability`
+ * module route, a future `ecommerce`/`cart`/`checkout` consumer) passes in
+ * its resolved `ModuleConfigService` instance; omitting it always resolves
+ * `'auto'`.
+ */
+export interface AvailabilityModuleConfigReader {
+  getValue<T = unknown>(
+    moduleId: string,
+    name: string,
+    options?: { defaultValue?: T | null; scope?: { tenantId?: string | null; organizationId?: string | null } },
+  ): Promise<T | null>
+}
+
+export interface ResolveAvailabilityOptions {
+  /** `ModuleConfigService('availability', 'selectedProvider')` reader. See {@link AvailabilityModuleConfigReader}. */
+  moduleConfig?: AvailabilityModuleConfigReader
+}
+
+function resolveAutoProvider(): AvailabilityProvider | null {
+  // 'auto' = "the highest-precedence registered provider" — the first
+  // non-catalog-only registrant, in registration order.
+  for (const provider of availabilityProviderRegistry.list()) {
+    if (provider.id !== AVAILABILITY_CATALOG_ONLY_PROVIDER_ID) return provider
+  }
+  return availabilityProviderRegistry.get(AVAILABILITY_CATALOG_ONLY_PROVIDER_ID)
+}
+
+/**
+ * The entry point every read-side consumer calls. Advisory only — see §4.1:
+ * `resolveAvailability()` is never a stock guarantee, `reserveAvailability()`
+ * (the `availability` module, not shipped by this contract) is.
+ */
+export async function resolveAvailability(
+  query: AvailabilityQuery,
+  options?: ResolveAvailabilityOptions,
+): Promise<AvailabilityResult> {
+  const selection = options?.moduleConfig
+    ? await options.moduleConfig.getValue<AvailabilityProviderSelection>('availability', 'selectedProvider', {
+        defaultValue: 'auto',
+        scope: { tenantId: query.tenantId },
+      })
+    : 'auto'
+
+  const provider =
+    !selection || selection === 'auto'
+      ? resolveAutoProvider()
+      : availabilityProviderRegistry.get(selection) ?? availabilityProviderRegistry.get(AVAILABILITY_CATALOG_ONLY_PROVIDER_ID)
+
+  const resolved = provider ?? availabilityProviderRegistry.get(AVAILABILITY_CATALOG_ONLY_PROVIDER_ID)
+  if (!resolved) {
+    throw new Error('[internal] No availability provider registered, including the built-in catalog-only fallback')
+  }
+  return resolved.getAvailability(query)
+}

package/src/lib/availability/types.ts

@@ -0,0 +1,71 @@
+/**
+ * Availability Contract — base types.
+ *
+ * Zero module dependencies, so `ecommerce`, `cart`, `checkout` and `catalog`
+ * can consume this without a `requires` edge on either `availability` or `wms`.
+ *
+ * @see .ai/specs/2026-08-14-availability-contract.md §4.1a
+ */
+
+export type AvailabilityState =
+  | 'in_stock'
+  | 'low_stock'
+  | 'out_of_stock'
+  | 'backorder'
+  | 'preorder'
+  | 'not_tracked'
+
+export type AvailabilityItemQuery = {
+  catalogProductId: string
+  /** `null` or omitted → product-level rollup over active variants. */
+  catalogVariantId?: string | null
+  /** The quantity being asked about; state is relative to it. */
+  quantity: number
+}
+
+export type AvailabilityQuery = {
+  tenantId: string
+  organizationId: string
+  items: AvailabilityItemQuery[]
+  /** Selects the policy chain. */
+  storeId?: string | null
+  channelId?: string | null
+  /** `null`/omitted → every in-scope location. */
+  locationIds?: string[] | null
+  /**
+   * Additive, optional. When true, a provider MUST skip any internal read
+   * cache and compute a live result — the §6 "cart re-validation" row.
+   */
+  bypassCache?: boolean
+}
+
+export type AvailabilityItemResult = {
+  state: AvailabilityState
+  /** Sellable quantity; `null` when not tracked. */
+  availableQuantity: number | null
+  /** Whether the requested quantity can be met, including a backorder/preorder path. */
+  canFulfil: boolean
+  /** Set for `'backorder'`. */
+  leadTimeDays: number | null
+  /** ISO-8601; set for `'preorder'`. */
+  releaseAt: string | null
+  /** `false` for a cached browse-time read — never a guarantee. */
+  isAuthoritative: boolean
+  /** The `AvailabilityPolicy` row that decided, or `null` for a module default. */
+  policySourceId: string | null
+}
+
+export type AvailabilityResult = {
+  /** Key: `${catalogProductId}:${catalogVariantId ?? ''}` — stable and caller-derivable. */
+  byItem: Record<string, AvailabilityItemResult>
+}
+
+export interface AvailabilityProvider {
+  id: string
+  getAvailability(query: AvailabilityQuery): Promise<AvailabilityResult>
+}
+
+/** Builds the stable `AvailabilityResult.byItem` key for an item. */
+export function availabilityItemKey(item: { catalogProductId: string; catalogVariantId?: string | null }): string {
+  return `${item.catalogProductId}:${item.catalogVariantId ?? ''}`
+}

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

@@ -23,6 +23,7 @@ import {
   type TelemetryRuntime,
 } from '@open-mercato/shared/lib/telemetry/runtime'
 import { z } from 'zod'
+import { NotFoundError as MikroOrmNotFoundError, ValidationError as MikroOrmValidationError } from '@mikro-orm/core'
 
 // Keep the real custom-field helpers but spy on the definition loader so we can
 // assert the factory skips the second DB round-trip when the query engine has
@@ -917,11 +918,90 @@ describe('CRUD Factory', () => {
     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')
+    const body = await res.json()
+    expect(body.code).toBe('DATABASE_UNAVAILABLE')
+    expect(typeof body.requestId).toBe('string')
+    expect(res.headers.get('x-request-id')).toBe(body.requestId)
     // 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('echoes an inbound x-request-id on the 503 transient-DB response', 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', 'x-request-id': 'req-fixed-503' },
+    }))
+    expect(res.status).toBe(503)
+    const body = await res.json()
+    expect(body.requestId).toBe('req-fixed-503')
+    expect(res.headers.get('x-request-id')).toBe('req-fixed-503')
+  })
+
+  it('returns DATABASE_ERROR for an unmapped Postgres SQLSTATE without leaking driver detail', async () => {
+    setRecordCustomFields.mockImplementationOnce(async () => {
+      throw Object.assign(new Error('relation "missing_table" does not exist'), { code: '42P01' })
+    })
+    const res = await route.POST(new Request('http://x/api/example/todos', {
+      method: 'POST',
+      body: JSON.stringify({ title: 'Undefined table', is_done: true, cf_priority: 3 }),
+      headers: { 'content-type': 'application/json' },
+    }))
+    expect(res.status).toBe(500)
+    const body = await res.json()
+    expect(body.code).toBe('DATABASE_ERROR')
+    expect(typeof body.requestId).toBe('string')
+    expect(JSON.stringify(body)).not.toContain('42P01')
+    expect(JSON.stringify(body)).not.toContain('missing_table')
+  })
+
+  it('returns PERSISTENCE_ERROR for a MikroORM ValidationError with no Postgres SQLSTATE', async () => {
+    setRecordCustomFields.mockImplementationOnce(async () => {
+      throw new MikroOrmValidationError('entity failed validation')
+    })
+    const res = await route.POST(new Request('http://x/api/example/todos', {
+      method: 'POST',
+      body: JSON.stringify({ title: 'Invalid entity', is_done: true, cf_priority: 3 }),
+      headers: { 'content-type': 'application/json' },
+    }))
+    expect(res.status).toBe(500)
+    const body = await res.json()
+    expect(body.code).toBe('PERSISTENCE_ERROR')
+    expect(typeof body.requestId).toBe('string')
+  })
+
+  it('returns PERSISTENCE_ERROR for a MikroORM NotFoundError with no Postgres SQLSTATE', async () => {
+    setRecordCustomFields.mockImplementationOnce(async () => {
+      throw new MikroOrmNotFoundError('entity not found')
+    })
+    const res = await route.POST(new Request('http://x/api/example/todos', {
+      method: 'POST',
+      body: JSON.stringify({ title: 'Missing entity', is_done: true, cf_priority: 3 }),
+      headers: { 'content-type': 'application/json' },
+    }))
+    expect(res.status).toBe(500)
+    const body = await res.json()
+    expect(body.code).toBe('PERSISTENCE_ERROR')
+  })
+
+  it('does not misclassify a Node system error code as a database error', async () => {
+    setRecordCustomFields.mockImplementationOnce(async () => {
+      throw Object.assign(new Error('connect ECONNREFUSED 127.0.0.1:80'), { code: 'ECONNREFUSED' })
+    })
+    const res = await route.POST(new Request('http://x/api/example/todos', {
+      method: 'POST',
+      body: JSON.stringify({ title: 'Unrelated socket failure', is_done: true, cf_priority: 3 }),
+      headers: { 'content-type': 'application/json' },
+    }))
+    expect(res.status).toBe(500)
+    const body = await res.json()
+    expect(body.code).toBe('INTERNAL_ERROR')
+  })
+
   it('returns a correlated 409 without leaking the constraint name when a handler hits a foreign key violation', async () => {
     setRecordCustomFields.mockImplementationOnce(async () => {
       // Mirror MikroORM's wrapping: the pg error sits behind `previous`, and the
@@ -1353,6 +1433,7 @@ describe('CRUD Factory', () => {
       error: 'Internal server error',
       message: 'Something went wrong. Please try again later.',
       requestId: expect.any(String),
+      code: 'INTERNAL_ERROR',
     })
   })
 
@@ -1392,6 +1473,7 @@ describe('CRUD Factory', () => {
       error: 'Internal server error',
       message: 'Something went wrong. Please try again later.',
       requestId: expect.any(String),
+      code: 'INTERNAL_ERROR',
     })
   })
 
@@ -1497,7 +1579,7 @@ describe('CRUD Factory', () => {
       expect(body.requestId).toMatch(/^[A-Za-z0-9-]{36}$/)
     })
 
-    it('reports the error to telemetry with the same requestId', async () => {
+    it('reports the error to telemetry with the same requestId and a groupable code', async () => {
       commandBus.execute.mockRejectedValue(new Error('boom'))
 
       const res = await postWithRequestId('req-fixed-123')
@@ -1507,12 +1589,17 @@ describe('CRUD Factory', () => {
       expect(reportError).toHaveBeenCalledTimes(1)
       expect(reportError).toHaveBeenCalledWith(
         expect.any(Error),
-        { module: 'crud', attributes: { requestId: 'req-fixed-123', errorName: 'Error' } },
+        {
+          module: 'crud',
+          code: 'crud.internal_error',
+          attributes: { requestId: 'req-fixed-123', errorName: 'Error', code: 'INTERNAL_ERROR', pgCode: undefined },
+        },
       )
     })
 
-    // The 503/422 branches deliberately stay outside this change (issue #5608) — lock that
-    // in so a later refactor cannot quietly widen the correlation id across every branch.
+    // The 422 interceptor-rejection branch deliberately stays outside this change (issue
+    // #5608) — lock that in so a later refactor cannot quietly widen the correlation id
+    // across every branch. The 503 transient-DB branch gained requestId/code separately.
     it('leaves the interceptor-rejection branch without a requestId', async () => {
       commandBus.execute.mockRejectedValue(
         new CommandInterceptorError('Missing required fields: VAT id', { status: 422 }),

package/src/lib/crud/factory.ts

@@ -75,9 +75,10 @@ import { parseExtensionHeaders } from '../umes/extension-headers'
 import { createGenericOptimisticLockReader } from './optimistic-lock'
 import { registerOptimisticLockReaderIfAbsent } from './optimistic-lock-store'
 import { createLogger } from '../logger'
-import { getForeignKeyViolationConstraint, isForeignKeyViolation, isTransientDbError } from '../db/pg-errors'
+import { getForeignKeyViolationConstraint, isForeignKeyViolation, isTransientDbError, readPgSqlState } from '../db/pg-errors'
 import { getTelemetryRuntime } from '../telemetry/runtime'
 import { randomUUID } from 'node:crypto'
+import { NotFoundError as MikroOrmNotFoundError, ValidationError as MikroOrmValidationError } from '@mikro-orm/core'
 
 type RbacServiceLike = {
   getGrantedFeatures: (userId: string, opts: { tenantId: string | null; organizationId: string | null }) => Promise<string[]>
@@ -609,6 +610,30 @@ function resolveRequestId(request?: Request): string {
   return randomUUID()
 }
 
+/**
+ * Stable, UPPER_SNAKE classification codes for the generic 500/503 fallback
+ * bodies below. See `apps/docs/docs/framework/runtime/request-lifecycle.mdx`
+ * for the full contract.
+ *
+ * - `DATABASE_UNAVAILABLE` — `isTransientDbError` matched (503 branch).
+ * - `DATABASE_ERROR` — a Postgres SQLSTATE is present (via `readPgSqlState`)
+ *   but was not already classified as transient (503) or a foreign-key
+ *   violation (409).
+ * - `PERSISTENCE_ERROR` — a MikroORM `ValidationError`/`NotFoundError` that
+ *   was not already handled by a more specific branch.
+ * - `INTERNAL_ERROR` — default fallback for anything else.
+ */
+type CrudErrorCode = 'INTERNAL_ERROR' | 'DATABASE_ERROR' | 'PERSISTENCE_ERROR' | 'DATABASE_UNAVAILABLE'
+
+function classifyCrudError(err: unknown): { code: CrudErrorCode; pgSqlState: string | null } {
+  const pgSqlState = readPgSqlState(err)
+  if (pgSqlState) return { code: 'DATABASE_ERROR', pgSqlState }
+  if (err instanceof MikroOrmValidationError || err instanceof MikroOrmNotFoundError) {
+    return { code: 'PERSISTENCE_ERROR', pgSqlState: null }
+  }
+  return { code: 'INTERNAL_ERROR', pgSqlState: null }
+}
+
 function handleError(err: unknown, request?: Request): Response {
   if (err instanceof Response) return err
   if (isCrudHttpError(err)) return json(err.body, { status: err.status })
@@ -623,13 +648,16 @@ function handleError(err: unknown, request?: Request): Response {
   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.
+    // a generic 500 so clients back off and retry once the DB recovers. Carries
+    // the same requestId correlation contract as the other branches below.
+    const requestId = resolveRequestId(request)
     logger.warn('Transient DB failure during CRUD handler', {
       message: err instanceof Error ? err.message : undefined,
+      requestId,
     })
     return json(
-      { error: 'Service temporarily unavailable' },
-      { status: 503, headers: { 'Retry-After': '2' } },
+      { error: 'Service temporarily unavailable', code: 'DATABASE_UNAVAILABLE', requestId },
+      { status: 503, headers: { 'Retry-After': '2', 'x-request-id': requestId } },
     )
   }
 
@@ -670,15 +698,18 @@ function handleError(err: unknown, request?: Request): Response {
   const stack = err instanceof Error ? err.stack : undefined
   const errorName = err instanceof Error ? err.name : undefined
   const requestId = resolveRequestId(request)
-  logger.error('Unexpected CRUD error', { message, stack, err, requestId })
+  const { code, pgSqlState } = classifyCrudError(err)
+  logger.error('Unexpected CRUD error', { message, stack, err, requestId, code })
   getTelemetryRuntime()?.reportError(err, {
     module: 'crud',
-    attributes: { requestId, errorName },
+    code: `crud.${code.toLowerCase()}`,
+    attributes: { requestId, errorName, code, pgCode: pgSqlState ?? undefined },
   })
   const body: Record<string, unknown> = {
     error: 'Internal server error',
     message: 'Something went wrong. Please try again later.',
     requestId,
+    code,
   }
   return json(body, { status: 500, headers: { 'x-request-id': requestId } })
 }