@open-mercato/shared 0.7.1-develop.7154.1.981330c924 → 0.7.1-develop.7171.1.9b31dbba45

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

@@ -137,18 +137,21 @@ 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)}`
 }
 
+const UNKNOWN_RECORD_ID = 'unknown'
+
 function extractRecordId(record: Record<string, unknown>): string {
   const idValue = record.id
   if (typeof idValue === 'string' && idValue.trim().length > 0) return idValue.trim()
   if (typeof idValue === 'number') return String(idValue)
-  return 'unknown'
+  return UNKNOWN_RECORD_ID
 }
 
 function getEnricherCacheTtl(enricher: ResponseEnricher): number {
@@ -185,6 +188,18 @@ async function readEnricherCache<T>(
   }
 }
 
+/**
+ * The cache write was skipped because no safe envelope could be built. Logged
+ * rather than swallowed: from outside the runner a silently-skipped write is
+ * indistinguishable from a broken cache, and "this enricher is not purely
+ * additive" is the answer an author needs to see.
+ */
+function logSkippedCacheWrite(enricher: ResponseEnricher): void {
+  logger.debug('Skipped enricher cache write — enrichment is not purely additive or lacks usable record ids', {
+    enricherId: enricher.id,
+  })
+}
+
 async function writeEnricherCache(
   cache: CacheLike | null,
   key: string,
@@ -200,6 +215,103 @@ async function writeEnricherCache(
   }
 }
 
+/**
+ * Cached read-through payload: the fields each enricher ADDED, keyed by record id.
+ *
+ * Caching whole records would replace the freshly-read record with the snapshot
+ * taken at write time, so an edit to a base field (a product's name, an order's
+ * status) would not surface until the entry expired, and a cached array would
+ * also carry — and therefore overwrite — whatever the previous enricher in the
+ * chain contributed. The additive delta is a pure function of the enricher, the
+ * tenant/organization scope and the record ids, which is exactly what the cache
+ * key already encodes, so it is the only part of the result that is safe to reuse.
+ */
+type EnricherCacheEnvelope = {
+  version: 1
+  deltas: Record<string, Record<string, unknown>>
+}
+
+const ENRICHER_CACHE_VERSION = 1
+
+function isEnricherCacheEnvelope(value: unknown): value is EnricherCacheEnvelope {
+  if (typeof value !== 'object' || value === null) return false
+  const candidate = value as { version?: unknown; deltas?: unknown }
+  if (candidate.version !== ENRICHER_CACHE_VERSION) return false
+  return typeof candidate.deltas === 'object' && candidate.deltas !== null
+}
+
+/**
+ * The keys an enricher added to a record, or `null` when the enrichment was not
+ * purely additive — it changed or dropped a key that was already there. A
+ * non-additive enricher is never cached: replaying only its added keys onto a
+ * later record would silently lose the change it made to the existing ones.
+ *
+ * Comparison is by identity at the top level only, so an enricher that mutates a
+ * nested object in place is indistinguishable from one that left the record
+ * alone: its nested change is absent from the delta and therefore lost on a
+ * later hit. That fails safe — the served record is under-enriched, never
+ * stale-wrong — and a deep clone of every record on every enriched response is
+ * not worth paying for the case.
+ */
+function computeAdditiveDelta(
+  input: Record<string, unknown>,
+  output: Record<string, unknown>,
+): Record<string, unknown> | null {
+  const delta: Record<string, unknown> = {}
+  for (const key of Object.keys(input)) {
+    if (!Object.prototype.hasOwnProperty.call(output, key)) return null
+    if (output[key] !== input[key]) return null
+  }
+  for (const key of Object.keys(output)) {
+    if (Object.prototype.hasOwnProperty.call(input, key)) continue
+    delta[key] = output[key]
+  }
+  return delta
+}
+
+/**
+ * Build the cacheable envelope for a batch, or `null` when it cannot be built
+ * safely — an unusable record id, a duplicate id (the deltas would collide), or
+ * a non-additive enrichment. Every failure mode skips the cache write and leaves
+ * the enricher running on every request, which is the pre-cache behavior.
+ */
+function buildCacheEnvelope<T extends Record<string, unknown>>(
+  inputs: T[],
+  outputs: T[],
+): EnricherCacheEnvelope | null {
+  if (inputs.length !== outputs.length) return null
+  const deltas: Record<string, Record<string, unknown>> = {}
+  for (let index = 0; index < inputs.length; index += 1) {
+    const recordId = extractRecordId(inputs[index])
+    if (recordId === UNKNOWN_RECORD_ID) return null
+    if (Object.prototype.hasOwnProperty.call(deltas, recordId)) return null
+    const delta = computeAdditiveDelta(inputs[index], outputs[index])
+    if (!delta) return null
+    deltas[recordId] = delta
+  }
+  return { version: ENRICHER_CACHE_VERSION, deltas }
+}
+
+/**
+ * Merge a cached envelope onto freshly-read records. Returns `null` — a miss —
+ * when the envelope does not cover every record, so a partially-cached batch
+ * re-runs the enricher rather than returning some records unenriched.
+ */
+function applyCacheEnvelope<T extends Record<string, unknown>>(
+  envelope: EnricherCacheEnvelope,
+  records: T[],
+): T[] | null {
+  const merged: T[] = []
+  for (const record of records) {
+    const recordId = extractRecordId(record)
+    if (recordId === UNKNOWN_RECORD_ID) return null
+    const delta = envelope.deltas[recordId]
+    if (!delta || typeof delta !== 'object') return null
+    merged.push({ ...record, ...delta } as T)
+  }
+  return merged
+}
+
 /**
  * Apply response enrichers to a list of records.
  *
@@ -212,6 +324,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,19 +347,29 @@ 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
+      // Snapshot BEFORE enrichment: the contract does not forbid an enricher
+      // from mutating the records it was handed, and comparing a mutated record
+      // against itself would yield an empty delta — caching "this enricher adds
+      // nothing" and serving unenriched records for the rest of the TTL.
+      const inputItems = shouldUseCache ? currentItems.map((item) => ({ ...item })) : currentItems
       if (shouldUseCache && cacheKey) {
-        const cached = await readEnricherCache<T[]>(cache, cacheKey)
-        if (cached) {
-          currentItems = cached
-          enrichedBy.push(enricher.id)
-          continue
+        const cached = await readEnricherCache<unknown>(cache, cacheKey)
+        if (isEnricherCacheEnvelope(cached)) {
+          const merged = applyCacheEnvelope(cached, currentItems)
+          if (merged) {
+            currentItems = merged
+            enrichedBy.push(enricher.id)
+            continue
+          }
         }
       }
 
       if (enricher.enrichMany) {
         result = await Promise.race([
-          enricher.enrichMany(currentItems, context) as Promise<T[]>,
+          enricher.enrichMany(currentItems, enricherContext) as Promise<T[]>,
           timeoutPromise(timeout),
         ])
       } else {
@@ -265,13 +388,18 @@ export async function applyResponseEnrichers<T extends Record<string, unknown>>(
 
       currentItems = result
       if (shouldUseCache && cacheKey) {
-        await writeEnricherCache(
-          cache,
-          cacheKey,
-          result,
-          getEnricherCacheTtl(enricher),
-          getEnricherCacheTags(enricher, context),
-        )
+        const envelope = buildCacheEnvelope(inputItems, result)
+        if (envelope) {
+          await writeEnricherCache(
+            cache,
+            cacheKey,
+            envelope,
+            getEnricherCacheTtl(enricher),
+            getEnricherCacheTags(enricher, context),
+          )
+        } else {
+          logSkippedCacheWrite(enricher)
+        }
       }
       enrichedBy.push(enricher.id)
     } catch (err) {
@@ -311,6 +439,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,17 +461,24 @@ 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
+      // Snapshot before enrichment — see the list path for why.
+      const inputRecord = shouldUseCache ? ({ ...currentRecord } as T) : currentRecord
       if (shouldUseCache && cacheKey) {
-        const cached = await readEnricherCache<T>(cache, cacheKey)
-        if (cached) {
-          currentRecord = cached
-          enrichedBy.push(enricher.id)
-          continue
+        const cached = await readEnricherCache<unknown>(cache, cacheKey)
+        if (isEnricherCacheEnvelope(cached)) {
+          const merged = applyCacheEnvelope(cached, [currentRecord])
+          if (merged) {
+            currentRecord = merged[0]
+            enrichedBy.push(enricher.id)
+            continue
+          }
         }
       }
       const result = await Promise.race([
-        enricher.enrichOne(currentRecord, context) as Promise<T>,
+        enricher.enrichOne(currentRecord, enricherContext) as Promise<T>,
         timeoutPromise(timeout),
       ])
 
@@ -351,13 +487,18 @@ export async function applyResponseEnricherToRecord<T extends Record<string, unk
 
       currentRecord = result
       if (shouldUseCache && cacheKey) {
-        await writeEnricherCache(
-          cache,
-          cacheKey,
-          result,
-          getEnricherCacheTtl(enricher),
-          getEnricherCacheTags(enricher, context),
-        )
+        const envelope = buildCacheEnvelope([inputRecord], [result])
+        if (envelope) {
+          await writeEnricherCache(
+            cache,
+            cacheKey,
+            envelope,
+            getEnricherCacheTtl(enricher),
+            getEnricherCacheTags(enricher, context),
+          )
+        } else {
+          logSkippedCacheWrite(enricher)
+        }
       }
       enrichedBy.push(enricher.id)
     } catch (err) {

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 */
@@ -91,11 +93,33 @@ export interface ResponseEnricher<TRecord = any, TEnriched = any> {
   /** Tenant IDs where this enricher should be disabled. */
   disabledTenantIds?: string[]
 
-  /** Optional cache configuration for read-through enrichment results. */
+  /**
+   * Optional cache configuration for read-through enrichment results.
+   *
+   * The runner caches the **additive delta** — the keys this enricher adds to a
+   * record — not the record itself, so a cache hit still serves freshly-read
+   * base fields and cannot overwrite what an earlier enricher in the chain
+   * contributed. That makes the cache usable only by an enricher whose output is
+   * purely additive: one that changes or drops a key the record already carried
+   * is never cached and simply re-runs on every request. Declaring `cache` on
+   * such an enricher is silently a no-op rather than an error, so an enricher
+   * that appears never to cache is usually mutating an existing key.
+   */
   cache?: {
     strategy: 'read-through'
     ttl: number
     tags?: string[]
+    /**
+     * NOT IMPLEMENTED — nothing in the runner reads this field, so declaring it
+     * has no effect and an enricher relying on it will serve stale enrichment
+     * until the TTL expires. It is kept rather than removed so any existing
+     * declaration keeps compiling.
+     *
+     * Wire invalidation with an event subscriber that calls `deleteByTags` on
+     * the tags above; see
+     * `packages/core/src/modules/wms/subscribers/invalidate-enricher-cache-*.ts`
+     * for the reference implementation.
+     */
     invalidateOn?: string[]
   }
 

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,