@open-mercato/shared 0.7.1-develop.7153.1.7145d295e6 → 0.7.1-develop.7170.1.d95074d7ba

package/src/lib/bootstrap/dynamicLoader.ts

@@ -3,6 +3,10 @@ import type { AppDiRegistrar } from '../di/container'
 import { findAppRoot, type AppRoot } from './appResolver'
 import { registerEntityIds } from '../encryption/entityIds'
 import { createLogger } from '../logger'
+import {
+  applyModuleOverridesFromEnabledModules,
+  type ModuleEntryWithOverrides,
+} from '../../modules/overrides'
 import {
   ensureMikroOrmV7GeneratedCacheCompatibility,
   recoverMikroOrmV7GeneratedCacheFromImportError,
@@ -589,6 +593,95 @@ async function loadAppDiRegistrar(appDir: string): Promise<AppDiRegistrar | null
   }
 }
 
+/**
+ * Override domains whose applier is not registered by `registerBuiltInModuleOverrideAppliers()`
+ * but by importing a domain package for its side effect. `bootstrap-common.ts` does this with a
+ * static import right before it dispatches; the dynamic bootstrap path has no bundler to lean on,
+ * so it resolves the same modules here — lazily, and only when an app actually declares the
+ * domain, so `@open-mercato/shared` keeps its rule of never taking a runtime dependency on a
+ * domain package (soft-optional coupling, `packages/core/AGENTS.md` → Cross-Module Coupling).
+ */
+const OPTIONAL_OVERRIDE_APPLIER_MODULES: Record<string, string> = {
+  ai: '@open-mercato/ai-assistant/modules/ai_assistant/lib/ai-overrides',
+}
+
+/**
+ * Import the side-effect module that registers the applier for every declared override domain
+ * that has no built-in one. A domain package the app does not install is not an error — there
+ * is nothing for that domain to apply to — so a failed resolution is logged and skipped, and the
+ * dispatcher's own "domain not yet wired" warning still fires behind it.
+ */
+async function ensureOptionalOverrideAppliers(enabledModules: ModuleEntryWithOverrides[]): Promise<void> {
+  for (const [domain, specifier] of Object.entries(OPTIONAL_OVERRIDE_APPLIER_MODULES)) {
+    const declared = enabledModules.some((entry) => {
+      const overrides = entry?.overrides as Record<string, unknown> | undefined
+      return Boolean(overrides && overrides[domain])
+    })
+    if (!declared) continue
+    try {
+      await import(/* webpackIgnore: true */ /* turbopackIgnore: true */ specifier)
+    } catch (error) {
+      logger.debug('Optional override applier module is not installed; the domain has nothing to apply to', {
+        domain,
+        specifier,
+        err: error,
+      })
+    }
+  }
+}
+
+/**
+ * Dispatch `entry.overrides` declared in the app's `src/modules.ts` for the dynamic
+ * bootstrap path.
+ *
+ * The Next.js runtime imports `enabledModules` statically from its own `src/modules.ts` and
+ * calls `applyModuleOverridesFromEnabledModules` from `bootstrap-common.ts` before any registry
+ * first-loads. Worker, scheduler and CLI processes bootstrap through `bootstrapFromAppRoot`
+ * instead, which only ever compiled the generated `modules.cli.generated.ts` — so an app's
+ * `entry.overrides` (encryption maps, ACL features, CLI commands, workers, event subscribers,
+ * setup, …) silently never applied there. `seed-encryption` seeding the base encryption maps
+ * instead of the app's `overrides.encryption.maps` was the concrete symptom (#5582).
+ *
+ * An app layout with no `src/modules.ts` at all is logged and skipped — that is a real
+ * compatibility case, handled the same way an absent `src/di.ts` is. A file that is *present*
+ * but fails to compile or import is not: it throws, matching how this same function treats
+ * every other mandatory input and how the Next.js runtime treats this same file (a static
+ * import in `bootstrap-common.ts`). Degrading there would put `seed-encryption` back on the
+ * base encryption maps while still printing success — #5582's outcome, only quieter.
+ */
+async function loadAppModuleOverrides(appDir: string): Promise<void> {
+  const tsPath = path.join(appDir, 'src', 'modules.ts')
+  if (!fs.existsSync(tsPath)) {
+    logger.debug('App-level modules file not present, skipping entry.overrides dispatch', { filePath: tsPath })
+    return
+  }
+
+  let enabledModules: unknown
+  try {
+    const appModulesModule = await compileAndImport(tsPath, {
+      appRoot: appDir,
+      outFile: path.join(appDir, '.mercato', 'generated', 'app-modules-overrides.compiled.mjs'),
+    })
+    enabledModules = appModulesModule.enabledModules
+  } catch (error) {
+    throw new Error(
+      `[internal] Failed to load the app-level modules file (${tsPath}); entry.overrides cannot be applied. ` +
+        'Refusing to bootstrap with a partial override set.',
+      { cause: error },
+    )
+  }
+
+  if (!Array.isArray(enabledModules)) {
+    throw new Error(
+      `[internal] The app-level modules file (${tsPath}) exports no enabledModules array; ` +
+        'entry.overrides cannot be applied. Refusing to bootstrap with a partial override set.',
+    )
+  }
+
+  await ensureOptionalOverrideAppliers(enabledModules as ModuleEntryWithOverrides[])
+  applyModuleOverridesFromEnabledModules(enabledModules as ModuleEntryWithOverrides[])
+}
+
 /**
  * Dynamically load bootstrap data from a resolved app directory.
  *
@@ -681,13 +774,20 @@ export async function loadBootstrapData(appRoot?: string): Promise<BootstrapData
 export async function bootstrapFromAppRoot(appRoot?: string): Promise<BootstrapData> {
   const { createBootstrap, waitForAsyncRegistration } = await import('./factory.js')
   const resolved = resolveAppRootOrThrow(appRoot)
-  // Both loads compile through esbuild, so they share one lifecycle scope: without it
+  // All three loads compile through esbuild, so they share one lifecycle scope: without it
   // `loadBootstrapData` releases the esbuild helper process and `loadAppDiRegistrar`
   // silently starts a second one that nothing ever stops.
-  const { data, appDiRegistrar } = await withEsbuildLifecycle(async () => ({
-    data: await loadBootstrapData(resolved.appDir),
-    appDiRegistrar: await loadAppDiRegistrar(resolved.appDir),
-  }))
+  const { data, appDiRegistrar } = await withEsbuildLifecycle(async () => {
+    // Dispatch the app's `entry.overrides` (src/modules.ts) BEFORE any registry
+    // first-loads — the `bootstrap()` call below runs `registerModules(data.modules)`,
+    // and `registerCliModules` in the mercato bin right after this function returns;
+    // both read the override side-registry this populates.
+    await loadAppModuleOverrides(resolved.appDir)
+    return {
+      data: await loadBootstrapData(resolved.appDir),
+      appDiRegistrar: await loadAppDiRegistrar(resolved.appDir),
+    }
+  })
   const bootstrap = createBootstrap(data, appDiRegistrar ? { appDiRegistrar } : {})
   bootstrap()
   // In CLI context, wait for async registrations (UI widgets, search configs, etc.)

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

@@ -922,6 +922,29 @@ describe('CRUD Factory', () => {
     expect(mockDataEngine.emitOrmEntityEvent).not.toHaveBeenCalled()
   })
 
+  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
+      // wrapper only carries the message.
+      throw Object.assign(
+        new Error('update or delete on table "users" violates foreign key constraint "sidebar_variants_user_id_foreign" on table "sidebar_variants"'),
+        { previous: { code: '23503', constraint: 'sidebar_variants_user_id_foreign' } },
+      )
+    })
+    const res = await route.POST(new Request('http://x/api/example/todos', { method: 'POST', body: JSON.stringify({ title: 'Referenced', is_done: true, cf_priority: 3 }), headers: { 'content-type': 'application/json' } }))
+    expect(res.status).toBe(409)
+    const body = await res.json()
+    expect(body.code).toBe('FOREIGN_KEY_VIOLATION')
+    // Internal schema names stay in the server log, never in the client body.
+    expect(body.constraint).toBeUndefined()
+    expect(JSON.stringify(body)).not.toContain('sidebar_variants_user_id_foreign')
+    // Same correlation contract as the generic 500 path.
+    expect(typeof body.requestId).toBe('string')
+    expect(res.headers.get('x-request-id')).toBe(body.requestId)
+    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')

package/src/lib/crud/__tests__/enricher-registry.test.ts

@@ -37,6 +37,22 @@ describe('enricher-registry', () => {
       expect(result[0].enricher.id).toBe('a.tier')
     })
 
+    it('includes wildcard enrichers in priority order for a concrete entity', () => {
+      registerResponseEnrichers([
+        {
+          moduleId: 'mod-a',
+          enrichers: [
+            makeEnricher({ id: 'a.exact', targetEntity: 'customers.person', priority: 10 }),
+            makeEnricher({ id: 'a.wildcard', targetEntity: '*', priority: 50 }),
+            makeEnricher({ id: 'a.other', targetEntity: 'sales.order', priority: 100 }),
+          ],
+        },
+      ])
+
+      const result = getEnrichersForEntity('customers.person')
+      expect(result.map((entry) => entry.enricher.id)).toEqual(['a.wildcard', 'a.exact'])
+    })
+
     it('returns enrichers regardless of queryEngine config', () => {
       registerResponseEnrichers([
         {

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

@@ -0,0 +1,59 @@
+import type { EnricherContext, ResponseEnricher } from '../response-enricher'
+import { registerResponseEnrichers } from '../enricher-registry'
+import { applyResponseEnricherToRecord } from '../enricher-runner'
+
+describe('enricher runner', () => {
+  it('partitions wildcard read-through cache entries by concrete entity', async () => {
+    const cacheEntries = new Map<string, unknown>()
+    const cache = {
+      get: jest.fn(async (key: string) => cacheEntries.get(key)),
+      set: jest.fn(async (key: string, value: unknown) => {
+        cacheEntries.set(key, value)
+      }),
+    }
+    const enrichOne = jest.fn(
+      async (record: Record<string, unknown>, context: EnricherContext) => ({
+        ...record,
+        enrichedFrom: context.targetEntity,
+      }),
+    )
+    const enricher: ResponseEnricher<
+      Record<string, unknown>,
+      { enrichedFrom: string | undefined }
+    > = {
+      id: 'test.wildcard-cache',
+      targetEntity: '*',
+      timeout: 10,
+      cache: { strategy: 'read-through', ttl: 60_000 },
+      enrichOne,
+    }
+    registerResponseEnrichers([{ moduleId: 'test', enrichers: [enricher] }])
+
+    const context: EnricherContext = {
+      organizationId: 'org-1',
+      tenantId: 'tenant-1',
+      userId: 'user-1',
+      em: {},
+      container: { resolve: () => cache },
+    }
+
+    const personResult = await applyResponseEnricherToRecord(
+      { id: 'shared-id' },
+      'customers.person',
+      context,
+    )
+    const orderResult = await applyResponseEnricherToRecord(
+      { id: 'shared-id' },
+      'sales.order',
+      context,
+    )
+
+    expect(personResult.record).toMatchObject({ enrichedFrom: 'customers.person' })
+    expect(orderResult.record).toMatchObject({ enrichedFrom: 'sales.order' })
+    expect(enrichOne).toHaveBeenCalledTimes(2)
+    expect(Array.from(cacheEntries.keys())).toEqual([
+      expect.stringContaining('entity:customers.person'),
+      expect.stringContaining('entity:sales.order'),
+    ])
+  })
+})

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

@@ -87,7 +87,8 @@ export function getEnrichersForEntity(
   selector?: EnricherSurfaceSelector,
 ): EnricherRegistryEntry[] {
   const entityEntries = getResponseEnrichers().filter(
-    (entry) => entry.enricher.targetEntity === targetEntity,
+    (entry) =>
+      entry.enricher.targetEntity === targetEntity || entry.enricher.targetEntity === '*',
   )
 
   if (!selector || selector.surface === 'api-response') {

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

@@ -137,11 +137,12 @@ function resolveCache(context: EnricherContext): CacheLike | null {
 function buildCacheKey(
   enricher: ResponseEnricher,
   context: EnricherContext,
+  targetEntity: string,
   mode: 'one' | 'many',
   recordIds: string[],
 ): string {
   const sortedIds = [...recordIds].sort((a, b) => a.localeCompare(b))
-  return `umes:enricher:${enricher.id}:tenant:${context.tenantId}:org:${context.organizationId}:mode:${mode}:ids:${JSON.stringify(sortedIds)}`
+  return `umes:enricher:${enricher.id}:entity:${targetEntity}:tenant:${context.tenantId}:org:${context.organizationId}:mode:${mode}:ids:${JSON.stringify(sortedIds)}`
 }
 
 function extractRecordId(record: Record<string, unknown>): string {
@@ -212,6 +213,7 @@ export async function applyResponseEnrichers<T extends Record<string, unknown>>(
   context: EnricherContext,
   preFilteredEntries?: EnricherRegistryEntry[],
 ): Promise<EnrichmentResult<T>> {
+  const enricherContext: EnricherContext = { ...context, targetEntity }
   const activeEntries = preFilteredEntries
     ? filterByACLAndTenant(preFilteredEntries, context)
     : getActiveEnrichers(targetEntity, context)
@@ -234,7 +236,9 @@ export async function applyResponseEnrichers<T extends Record<string, unknown>>(
       let result: T[]
       const recordIds = currentItems.map((item) => extractRecordId(item))
       const shouldUseCache = enricher.cache?.strategy === 'read-through'
-      const cacheKey = shouldUseCache ? buildCacheKey(enricher, context, 'many', recordIds) : null
+      const cacheKey = shouldUseCache
+        ? buildCacheKey(enricher, context, targetEntity, 'many', recordIds)
+        : null
       if (shouldUseCache && cacheKey) {
         const cached = await readEnricherCache<T[]>(cache, cacheKey)
         if (cached) {
@@ -246,7 +250,7 @@ export async function applyResponseEnrichers<T extends Record<string, unknown>>(
 
       if (enricher.enrichMany) {
         result = await Promise.race([
-          enricher.enrichMany(currentItems, context) as Promise<T[]>,
+          enricher.enrichMany(currentItems, enricherContext) as Promise<T[]>,
           timeoutPromise(timeout),
         ])
       } else {
@@ -311,6 +315,7 @@ export async function applyResponseEnricherToRecord<T extends Record<string, unk
   context: EnricherContext,
   preFilteredEntries?: EnricherRegistryEntry[],
 ): Promise<SingleEnrichmentResult<T>> {
+  const enricherContext: EnricherContext = { ...context, targetEntity }
   const activeEntries = preFilteredEntries
     ? filterByACLAndTenant(preFilteredEntries, context)
     : getActiveEnrichers(targetEntity, context)
@@ -332,7 +337,9 @@ export async function applyResponseEnricherToRecord<T extends Record<string, unk
     try {
       const recordId = extractRecordId(currentRecord)
       const shouldUseCache = enricher.cache?.strategy === 'read-through'
-      const cacheKey = shouldUseCache ? buildCacheKey(enricher, context, 'one', [recordId]) : null
+      const cacheKey = shouldUseCache
+        ? buildCacheKey(enricher, context, targetEntity, 'one', [recordId])
+        : null
       if (shouldUseCache && cacheKey) {
         const cached = await readEnricherCache<T>(cache, cacheKey)
         if (cached) {
@@ -342,7 +349,7 @@ export async function applyResponseEnricherToRecord<T extends Record<string, unk
         }
       }
       const result = await Promise.race([
-        enricher.enrichOne(currentRecord, context) as Promise<T>,
+        enricher.enrichOne(currentRecord, enricherContext) as Promise<T>,
         timeoutPromise(timeout),
       ])
 

package/src/lib/crud/factory.ts

@@ -75,7 +75,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'
+import { getForeignKeyViolationConstraint, isForeignKeyViolation, isTransientDbError } from '../db/pg-errors'
 import { getTelemetryRuntime } from '../telemetry/runtime'
 import { randomUUID } from 'node:crypto'
 
@@ -633,6 +633,35 @@ function handleError(err: unknown, request?: Request): Response {
     )
   }
 
+  if (isForeignKeyViolation(err)) {
+    // SQLSTATE 23503 covers both directions: a DELETE blocked by a dependent row
+    // and an INSERT/UPDATE pointing at a missing parent. Either way it is a
+    // data-state conflict the caller can act on, so answer 409 instead of 500.
+    // The constraint name stays in the log only: it maps internal table/column
+    // names and has no business in a client-facing body. The missing-parent
+    // direction is often a server-side defect, so the error is still reported to
+    // telemetry and carries a requestId exactly like the generic 500 below.
+    const requestId = resolveRequestId(request)
+    const constraint = getForeignKeyViolationConstraint(err)
+    logger.warn('Foreign key violation during CRUD handler', {
+      message: err instanceof Error ? err.message : undefined,
+      constraint,
+      requestId,
+    })
+    getTelemetryRuntime()?.reportError(err, {
+      module: 'crud',
+      attributes: { requestId, errorName: 'ForeignKeyViolation', constraint: constraint ?? undefined },
+    })
+    return json(
+      {
+        error: 'The record is still referenced by other data, or references a record that does not exist',
+        code: 'FOREIGN_KEY_VIOLATION',
+        requestId,
+      },
+      { status: 409, headers: { 'x-request-id': requestId } },
+    )
+  }
+
   // Unexpected exceptions still collapse into a generic 500 for the client (no internal
   // detail leaked), but a requestId ties that response to this log line and to whatever
   // reaches APM, so a client/support ticket citing it can be correlated with server-side

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

@@ -17,6 +17,8 @@ export interface EnricherContext {
   organizationId: string
   tenantId: string
   userId: string
+  /** Concrete entity currently being enriched, including for wildcard enrichers. */
+  targetEntity?: string
   em: unknown
   container: unknown
   requestedFields?: string[]
@@ -53,7 +55,7 @@ export interface ResponseEnricher<TRecord = any, TEnriched = any> {
   /** Unique identifier: `<module>.<enricher-name>` */
   id: string
 
-  /** Target entity to enrich: `<module>.<entity>` (e.g., 'customers.person') */
+  /** Target entity to enrich: `<module>.<entity>` (e.g., 'customers.person') or `*` for all entities. */
   targetEntity: string
 
   /** ACL features required for this enricher to run */

package/src/lib/db/__tests__/pg-errors.test.ts

@@ -1,4 +1,4 @@
-import { isTransientDbError, isUniqueViolation } from '../pg-errors'
+import { getForeignKeyViolationConstraint, isForeignKeyViolation, isTransientDbError, isUniqueViolation } from '../pg-errors'
 
 describe('isTransientDbError', () => {
   it('is true for the max_connections SQLSTATE', () => {
@@ -46,3 +46,61 @@ describe('isTransientDbError', () => {
     expect(isTransientDbError(uniqueErr)).toBe(false)
   })
 })
+
+describe('isForeignKeyViolation', () => {
+  it('is true for the foreign_key_violation SQLSTATE', () => {
+    expect(isForeignKeyViolation({ code: '23503' })).toBe(true)
+  })
+
+  it('is true for ORM-wrapped messages that drop the SQLSTATE', () => {
+    expect(
+      isForeignKeyViolation(
+        new Error('update or delete on table "users" violates foreign key constraint "sidebar_variants_user_id_foreign" on table "sidebar_variants"'),
+      ),
+    ).toBe(true)
+  })
+
+  it('looks through MikroORM wrapper chains (cause / previous), including re-wrapped errors', () => {
+    expect(isForeignKeyViolation({ message: 'wrapped', cause: { code: '23503' } })).toBe(true)
+    expect(isForeignKeyViolation({ message: 'wrapped', previous: { code: '23503' } })).toBe(true)
+    expect(isForeignKeyViolation({ message: 'outer', cause: { message: 'inner', previous: { code: '23503' } } })).toBe(true)
+  })
+
+  it('stops on cyclic or very deep wrapper chains', () => {
+    const cyclic: Record<string, unknown> = { message: 'loop' }
+    cyclic.cause = cyclic
+    expect(isForeignKeyViolation(cyclic)).toBe(false)
+    const deep = { cause: { cause: { cause: { cause: { cause: { code: '23503' } } } } } }
+    expect(isForeignKeyViolation(deep)).toBe(false)
+  })
+
+  it('is false for unique violations, transient errors and non-DB errors', () => {
+    expect(isForeignKeyViolation({ code: '23505' })).toBe(false)
+    expect(isForeignKeyViolation({ code: '53300' })).toBe(false)
+    expect(isForeignKeyViolation(new Error('something unrelated broke'))).toBe(false)
+    expect(isForeignKeyViolation(null)).toBe(false)
+  })
+})
+
+describe('getForeignKeyViolationConstraint', () => {
+  const driverMessage = 'update or delete on table "users" violates foreign key constraint "sidebar_variants_user_id_foreign" on table "sidebar_variants"'
+
+  it('reads the pg constraint field from the top-level error', () => {
+    expect(getForeignKeyViolationConstraint({ code: '23503', constraint: 'user_roles_user_id_foreign' })).toBe('user_roles_user_id_foreign')
+  })
+
+  it('reads the constraint from a wrapped driver error', () => {
+    expect(getForeignKeyViolationConstraint({ message: 'wrapped', previous: { code: '23503', constraint: 'sessions_user_id_foreign' } })).toBe('sessions_user_id_foreign')
+    expect(getForeignKeyViolationConstraint({ message: 'wrapped', cause: { code: '23503', constraint: 'user_acls_user_id_foreign' } })).toBe('user_acls_user_id_foreign')
+  })
+
+  it('falls back to the quoted constraint in the driver message', () => {
+    expect(getForeignKeyViolationConstraint(new Error(driverMessage))).toBe('sidebar_variants_user_id_foreign')
+  })
+
+  it('is null when nothing identifies the constraint', () => {
+    expect(getForeignKeyViolationConstraint({ code: '23503' })).toBeNull()
+    expect(getForeignKeyViolationConstraint(new Error('something unrelated broke'))).toBeNull()
+    expect(getForeignKeyViolationConstraint(null)).toBeNull()
+  })
+})

package/src/lib/db/pg-errors.ts

@@ -11,6 +11,63 @@ export function isUniqueViolation(err: unknown): boolean {
   return typeof message === 'string' && /duplicate key value|unique constraint/i.test(message)
 }
 
+const FOREIGN_KEY_VIOLATION_MESSAGE = /violates foreign key constraint(?: "([^"]+)")?/i
+
+const MAX_ERROR_CHAIN_DEPTH = 4
+
+/**
+ * MikroORM wraps driver errors and copies the pg fields onto the wrapper, but
+ * the original error may also sit behind `cause` (Node) or `previous`
+ * (MikroORM), possibly re-wrapped by a transaction helper. Walk that chain,
+ * breadth-first with a small depth cap, so a check works on any layer.
+ */
+function pgErrorCandidates(err: unknown): Array<Record<string, unknown>> {
+  const found: Array<Record<string, unknown>> = []
+  const seen = new Set<unknown>()
+  let layer: unknown[] = [err]
+  for (let depth = 0; depth < MAX_ERROR_CHAIN_DEPTH && layer.length > 0; depth += 1) {
+    const next: unknown[] = []
+    for (const candidate of layer) {
+      if (!candidate || typeof candidate !== 'object' || seen.has(candidate)) continue
+      seen.add(candidate)
+      const record = candidate as Record<string, unknown>
+      found.push(record)
+      next.push(record.cause, record.previous)
+    }
+    layer = next
+  }
+  return found
+}
+
+/**
+ * Detect a Postgres foreign-key violation (SQLSTATE 23503): the row is still
+ * referenced by a dependent table, or the payload references a parent that
+ * does not exist. Looks through MikroORM's driver-error wrapping.
+ */
+export function isForeignKeyViolation(err: unknown): boolean {
+  return pgErrorCandidates(err).some((candidate) => {
+    if (candidate.code === '23503') return true // Postgres foreign_key_violation
+    return typeof candidate.message === 'string' && FOREIGN_KEY_VIOLATION_MESSAGE.test(candidate.message)
+  })
+}
+
+/**
+ * Name of the constraint behind a foreign-key violation, read from the pg
+ * `constraint` field on any layer of the wrapper chain, or parsed out of the
+ * quoted constraint in the driver message when the field is missing.
+ */
+export function getForeignKeyViolationConstraint(err: unknown): string | null {
+  for (const candidate of pgErrorCandidates(err)) {
+    if (typeof candidate.constraint === 'string' && candidate.constraint.length > 0) return candidate.constraint
+  }
+  for (const candidate of pgErrorCandidates(err)) {
+    if (typeof candidate.message !== 'string') continue
+    const match = FOREIGN_KEY_VIOLATION_MESSAGE.exec(candidate.message)
+    if (match?.[1]) return match[1]
+  }
+  return null
+}
+
 /**
  * Postgres SQLSTATEs for transient connection / availability failures — the
  * database (or its connection pool) is temporarily unreachable and the request

package/src/lib/number.ts

@@ -1,3 +1,106 @@
+type LocaleNumberSeparators = { group: string; decimal: string }
+
+const DEFAULT_SEPARATORS: LocaleNumberSeparators = { group: ',', decimal: '.' }
+const separatorCache = new Map<string, LocaleNumberSeparators>()
+
+const UNICODE_MINUS_SIGNS = /[−‒–—]/g
+const GROUP_LIKE_CHARACTER = /[\s'’ʼ]/
+const GROUP_LIKE_SEPARATOR_IN_POSITION = /(\d)[\s'’ʼ](?=\d{3}(?!\d))/g
+const NORMALIZED_NUMBER = /^[+-]?(\d+(\.\d*)?|\.\d+)(e[+-]?\d+)?$/i
+
+/**
+ * Group and decimal separators the given locale uses, derived from `Intl` rather than
+ * assumed, so grouping characters such as the narrow no-break space (`fr-FR`) are covered.
+ */
+export function resolveLocaleNumberSeparators(locale?: string): LocaleNumberSeparators {
+  const cacheKey = locale ?? ''
+  const cached = separatorCache.get(cacheKey)
+  if (cached) return cached
+  let resolved = DEFAULT_SEPARATORS
+  try {
+    const parts = new Intl.NumberFormat(locale, {
+      useGrouping: true,
+      minimumFractionDigits: 1,
+    }).formatToParts(12345.6)
+    const group = parts.find((part) => part.type === 'group')?.value ?? DEFAULT_SEPARATORS.group
+    const decimal = parts.find((part) => part.type === 'decimal')?.value ?? DEFAULT_SEPARATORS.decimal
+    resolved = { group, decimal }
+  } catch {
+    resolved = DEFAULT_SEPARATORS
+  }
+  separatorCache.set(cacheKey, resolved)
+  return resolved
+}
+
+function isValidGrouping(integerPart: string, separator: string): boolean {
+  const digits = integerPart.replace(/^[+-]/, '')
+  const segments = digits.split(separator)
+  if (segments.length < 2) return true
+  const [first, ...rest] = segments
+  if (!/^\d{1,3}$/.test(first)) return false
+  return rest.every((segment) => /^\d{3}$/.test(segment))
+}
+
+/**
+ * Parses a user-typed number written in the conventions of `locale` — `110,70` under `pl-PL`,
+ * `1 234,56` under `fr-FR`, `1,234.56` under `en-US`. Returns `null` when the input is not a
+ * number, never a silent `0`, so callers can tell "unparseable" apart from "zero".
+ *
+ * Both `,` and `.` are accepted as the decimal separator whichever way the locale runs, because
+ * users type the shape their keyboard offers. A SINGLE `,` or `.` is therefore always the decimal
+ * point, in every locale: `1.500` is 1.5 under `de-DE` just as it is under `en-US`. Reading a lone
+ * separator as grouping instead would turn `1.500` into 1500 with no visible cue — a silent 1000×
+ * on a money field, and three- and four-decimal unit prices are ordinary here. Grouping is
+ * recognized only where it is unambiguous: at least two separators (`1.234.567`), or a whitespace
+ * or apostrophe separator standing in a valid group-of-three position (`1 234,56`, `1’234.5`).
+ * Whitespace and apostrophes anywhere else are not absorbed — `1 2` is rejected rather than read
+ * as 12 — so a mistyped or pasted value surfaces as an error instead of a different number.
+ *
+ * Use it only on strings a user typed. Values arriving from an API or the database are already
+ * numbers and MUST NOT go through it.
+ */
+export function parseLocaleNumber(input: string | null | undefined, locale?: string): number | null {
+  if (input == null) return null
+  const trimmed = input.trim()
+  if (!trimmed) return null
+
+  const { group } = resolveLocaleNumberSeparators(locale)
+  let candidate = trimmed.replace(UNICODE_MINUS_SIGNS, '-')
+  if (group && group !== ',' && group !== '.' && !GROUP_LIKE_CHARACTER.test(group)) {
+    candidate = candidate.split(group).join(' ')
+  }
+  candidate = candidate.replace(GROUP_LIKE_SEPARATOR_IN_POSITION, '$1')
+  if (!candidate) return null
+
+  const hasComma = candidate.includes(',')
+  const hasDot = candidate.includes('.')
+  let decimalSeparator: string | null = null
+  if (hasComma && hasDot) {
+    decimalSeparator = candidate.lastIndexOf(',') > candidate.lastIndexOf('.') ? ',' : '.'
+  } else if (hasComma || hasDot) {
+    const separator = hasComma ? ',' : '.'
+    const segments = candidate.split(separator)
+    decimalSeparator = segments.length > 2 ? null : separator
+  }
+
+  const groupSeparator = decimalSeparator
+    ? decimalSeparator === ','
+      ? '.'
+      : ','
+    : hasComma
+      ? ','
+      : '.'
+  const [integerPart, ...fractionParts] = decimalSeparator ? candidate.split(decimalSeparator) : [candidate]
+  if (fractionParts.length > 1) return null
+  if (!isValidGrouping(integerPart, groupSeparator)) return null
+  if (fractionParts.length && fractionParts[0].includes(groupSeparator)) return null
+
+  const normalized = `${integerPart.split(groupSeparator).join('')}${fractionParts.length ? `.${fractionParts[0]}` : ''}`
+  if (!NORMALIZED_NUMBER.test(normalized)) return null
+  const parsed = Number(normalized)
+  return Number.isFinite(parsed) ? parsed : null
+}
+
 export function parseNumberWithDefault(
   raw: string | null | undefined,
   fallback: number,