@open-mercato/shared 0.8.1-develop.7275.1.f772b944d4 → 0.8.1-develop.7294.1.0ef99fc518

package/dist/lib/navigation/pageReload.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/lib/navigation/pageReload.ts"],
+  "sourcesContent": ["/**\n * Boundary-crossing navigation helpers: they reload the document instead of handing the route to\n * the client router.\n *\n * The portal's `(frontend)` layout \u2014 the server component that decides the portal chrome and\n * resolves the customer session \u2014 sits *above* the `[...slug]` segment so portal navigation does\n * not remount the client subtree. A client-side `router.push`/`router.replace` therefore never\n * re-runs that layout, and any navigation that crosses the public/authenticated boundary would\n * keep rendering chrome computed for the page it came from: authenticated chrome over the login\n * page after a logout, or logged-out chrome over the dashboard after a login.\n *\n * Use these helpers for every boundary-crossing navigation (login, logout, signup completion,\n * invite acceptance, auth guards redirecting to login) so the layout re-runs and recomputes both\n * the chrome and the session. Same-side navigation should keep using the client router.\n *\n * Pick the one that matches the client-router call it stands in for, so session history behaves\n * the same way: `navigateWithPageReload` for `router.push`, `replaceWithPageReload` for\n * `router.replace`.\n */\n\n/** Full page load that adds a session-history entry \u2014 the document-loading counterpart of `router.push`. */\nexport function navigateWithPageReload(path: string): void {\n  window.location.assign(path)\n}\n\n/**\n * Full page load that replaces the current session-history entry \u2014 the document-loading\n * counterpart of `router.replace`.\n *\n * Use this where the client-router call being replaced was a `router.replace`: an auth guard\n * sending an unauthenticated visitor to the login page, or the portal landing page forwarding a\n * signed-in customer to the dashboard.\n *\n * Note that for those call sites specifically, `navigateWithPageReload` was measured to behave\n * identically: they redirect from an effect during page load, and a browser treats a navigation\n * started then as a client redirect, replacing the entry rather than pushing it whichever method\n * is used. This helper exists so the call site states which semantics it means instead of relying\n * on that heuristic \u2014 and so a redirect that later moves behind a user gesture, where the\n * distinction does bite, keeps the behaviour it was written with.\n */\nexport function replaceWithPageReload(path: string): void {\n  window.location.replace(path)\n}\n"],
+  "mappings": "AAqBO,SAAS,uBAAuB,MAAoB;AACzD,SAAO,SAAS,OAAO,IAAI;AAC7B;AAiBO,SAAS,sBAAsB,MAAoB;AACxD,SAAO,SAAS,QAAQ,IAAI;AAC9B;",
+  "names": []
+}

package/dist/lib/schedule/interval.js

@@ -0,0 +1,33 @@
+const MIN_SCHEDULE_INTERVAL_MS = 60 * 1e3;
+const SCHEDULE_INTERVAL_PATTERN = /^(\d+)(s|m|h|d)$/;
+const UNIT_MULTIPLIERS = {
+  s: 1e3,
+  m: 60 * 1e3,
+  h: 60 * 60 * 1e3,
+  d: 24 * 60 * 60 * 1e3
+};
+function matchScheduleInterval(interval) {
+  const match = SCHEDULE_INTERVAL_PATTERN.exec(interval);
+  if (!match) return null;
+  return { amount: Number.parseInt(match[1], 10), unit: match[2] };
+}
+function parseScheduleInterval(interval) {
+  const parts = matchScheduleInterval(interval);
+  if (!parts) {
+    throw new Error(`Invalid interval format: ${interval}. Expected format: <number><unit> (e.g., 15m, 2h, 1d)`);
+  }
+  return parts.amount * UNIT_MULTIPLIERS[parts.unit];
+}
+function isValidScheduleInterval(interval) {
+  const parts = matchScheduleInterval(interval);
+  if (!parts) return false;
+  return parts.amount * UNIT_MULTIPLIERS[parts.unit] >= MIN_SCHEDULE_INTERVAL_MS;
+}
+export {
+  MIN_SCHEDULE_INTERVAL_MS,
+  SCHEDULE_INTERVAL_PATTERN,
+  isValidScheduleInterval,
+  matchScheduleInterval,
+  parseScheduleInterval
+};
+//# sourceMappingURL=interval.js.map

package/dist/lib/schedule/interval.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/lib/schedule/interval.ts"],
+  "sourcesContent": ["/**\n * Canonical interval-format rules for recurring schedules.\n *\n * Both the scheduler runtime and the API validators that reject a schedule\n * before it is persisted read the format from here, so the documented format\n * (`<number><unit>`, e.g. `15m`, `1h`, `24h`) cannot drift between the layer\n * that accepts a value and the layer that has to run it.\n */\nexport const MIN_SCHEDULE_INTERVAL_MS = 60 * 1000\n\nexport const SCHEDULE_INTERVAL_PATTERN = /^(\\d+)(s|m|h|d)$/\n\nconst UNIT_MULTIPLIERS: Record<string, number> = {\n  s: 1000,\n  m: 60 * 1000,\n  h: 60 * 60 * 1000,\n  d: 24 * 60 * 60 * 1000,\n}\n\nexport type ScheduleIntervalUnit = 's' | 'm' | 'h' | 'd'\n\nexport type ScheduleIntervalParts = {\n  amount: number\n  unit: ScheduleIntervalUnit\n}\n\nexport function matchScheduleInterval(interval: string): ScheduleIntervalParts | null {\n  const match = SCHEDULE_INTERVAL_PATTERN.exec(interval)\n  if (!match) return null\n  return { amount: Number.parseInt(match[1], 10), unit: match[2] as ScheduleIntervalUnit }\n}\n\nexport function parseScheduleInterval(interval: string): number {\n  const parts = matchScheduleInterval(interval)\n  if (!parts) {\n    throw new Error(`Invalid interval format: ${interval}. Expected format: <number><unit> (e.g., 15m, 2h, 1d)`)\n  }\n  return parts.amount * UNIT_MULTIPLIERS[parts.unit]\n}\n\nexport function isValidScheduleInterval(interval: string): boolean {\n  const parts = matchScheduleInterval(interval)\n  if (!parts) return false\n  return parts.amount * UNIT_MULTIPLIERS[parts.unit] >= MIN_SCHEDULE_INTERVAL_MS\n}\n"],
+  "mappings": "AAQO,MAAM,2BAA2B,KAAK;AAEtC,MAAM,4BAA4B;AAEzC,MAAM,mBAA2C;AAAA,EAC/C,GAAG;AAAA,EACH,GAAG,KAAK;AAAA,EACR,GAAG,KAAK,KAAK;AAAA,EACb,GAAG,KAAK,KAAK,KAAK;AACpB;AASO,SAAS,sBAAsB,UAAgD;AACpF,QAAM,QAAQ,0BAA0B,KAAK,QAAQ;AACrD,MAAI,CAAC,MAAO,QAAO;AACnB,SAAO,EAAE,QAAQ,OAAO,SAAS,MAAM,CAAC,GAAG,EAAE,GAAG,MAAM,MAAM,CAAC,EAA0B;AACzF;AAEO,SAAS,sBAAsB,UAA0B;AAC9D,QAAM,QAAQ,sBAAsB,QAAQ;AAC5C,MAAI,CAAC,OAAO;AACV,UAAM,IAAI,MAAM,4BAA4B,QAAQ,uDAAuD;AAAA,EAC7G;AACA,SAAO,MAAM,SAAS,iBAAiB,MAAM,IAAI;AACnD;AAEO,SAAS,wBAAwB,UAA2B;AACjE,QAAM,QAAQ,sBAAsB,QAAQ;AAC5C,MAAI,CAAC,MAAO,QAAO;AACnB,SAAO,MAAM,SAAS,iBAAiB,MAAM,IAAI,KAAK;AACxD;",
+  "names": []
+}

package/dist/lib/schedule/invalidScheduleValue.js

@@ -0,0 +1,19 @@
+const INVALID_SCHEDULE_VALUE_CODE = "INVALID_SCHEDULE_VALUE";
+function createInvalidScheduleValueError(scheduleType, scheduleValue, message) {
+  return Object.assign(new Error(message), {
+    code: INVALID_SCHEDULE_VALUE_CODE,
+    scheduleType,
+    scheduleValue
+  });
+}
+function isInvalidScheduleValueError(error) {
+  if (typeof error !== "object" || error === null) return false;
+  const candidate = error;
+  return candidate.code === INVALID_SCHEDULE_VALUE_CODE && (candidate.scheduleType === "cron" || candidate.scheduleType === "interval");
+}
+export {
+  INVALID_SCHEDULE_VALUE_CODE,
+  createInvalidScheduleValueError,
+  isInvalidScheduleValueError
+};
+//# sourceMappingURL=invalidScheduleValue.js.map

package/dist/lib/schedule/invalidScheduleValue.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/lib/schedule/invalidScheduleValue.ts"],
+  "sourcesContent": ["export const INVALID_SCHEDULE_VALUE_CODE = 'INVALID_SCHEDULE_VALUE'\n\nexport type ScheduleValueKind = 'cron' | 'interval'\n\nexport type InvalidScheduleValueError = Error & {\n  code: typeof INVALID_SCHEDULE_VALUE_CODE\n  scheduleType: ScheduleValueKind\n  scheduleValue: string\n}\n\nexport function createInvalidScheduleValueError(\n  scheduleType: ScheduleValueKind,\n  scheduleValue: string,\n  message: string,\n): InvalidScheduleValueError {\n  return Object.assign(new Error(message), {\n    code: INVALID_SCHEDULE_VALUE_CODE,\n    scheduleType,\n    scheduleValue,\n  } as const)\n}\n\n/**\n * Structural check rather than `instanceof`: the error crosses a package\n * boundary (and a production bundle), where a duplicated class identity would\n * make `instanceof` silently false.\n */\nexport function isInvalidScheduleValueError(error: unknown): error is InvalidScheduleValueError {\n  if (typeof error !== 'object' || error === null) return false\n  const candidate = error as { code?: unknown; scheduleType?: unknown }\n  return candidate.code === INVALID_SCHEDULE_VALUE_CODE\n    && (candidate.scheduleType === 'cron' || candidate.scheduleType === 'interval')\n}\n"],
+  "mappings": "AAAO,MAAM,8BAA8B;AAUpC,SAAS,gCACd,cACA,eACA,SAC2B;AAC3B,SAAO,OAAO,OAAO,IAAI,MAAM,OAAO,GAAG;AAAA,IACvC,MAAM;AAAA,IACN;AAAA,IACA;AAAA,EACF,CAAU;AACZ;AAOO,SAAS,4BAA4B,OAAoD;AAC9F,MAAI,OAAO,UAAU,YAAY,UAAU,KAAM,QAAO;AACxD,QAAM,YAAY;AAClB,SAAO,UAAU,SAAS,gCACpB,UAAU,iBAAiB,UAAU,UAAU,iBAAiB;AACxE;",
+  "names": []
+}

package/dist/lib/version.js

@@ -1,4 +1,4 @@
-const APP_VERSION = "0.8.1-develop.7275.1.f772b944d4";
+const APP_VERSION = "0.8.1-develop.7294.1.0ef99fc518";
 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.8.1-develop.7275.1.f772b944d4';\nexport const appVersion = APP_VERSION;\n"],
+  "sourcesContent": ["// Build-time generated version\nexport const APP_VERSION = '0.8.1-develop.7294.1.0ef99fc518';\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.8.1-develop.7275.1.f772b944d4",
+  "version": "0.8.1-develop.7294.1.0ef99fc518",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -113,7 +113,7 @@
     "@mikro-orm/core": "^7.1.14",
     "@mikro-orm/decorators": "^7.1.14",
     "@mikro-orm/postgresql": "^7.1.14",
-    "@open-mercato/cache": "0.8.1-develop.7275.1.f772b944d4",
+    "@open-mercato/cache": "0.8.1-develop.7294.1.0ef99fc518",
     "@types/html-to-text": "^9.0.4",
     "@types/sanitize-html": "^2.16.1",
     "dotenv": "^17.4.2",
@@ -129,6 +129,7 @@
   "devDependencies": {
     "@types/jest": "^30.0.0",
     "jest": "^30.4.2",
+    "language-subtag-registry": "^0.3.20",
     "ts-jest": "^29.4.12",
     "ts-morph": "^28.0.0",
     "typescript": "7.0.2"

package/scripts/generate-countries.mjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+/**
+ * Build-time generator: extracts ISO alpha-2 region subtags from
+ * language-subtag-registry into a small TypeScript module so the published
+ * package never imports the registry JSON at runtime (Node ESM requires
+ * `with { type: 'json' }`, which esbuild strips when bundle:false).
+ *
+ * Usage:
+ *   node packages/shared/scripts/generate-countries.mjs         # write when drifted
+ *   node packages/shared/scripts/generate-countries.mjs --check # exit 1 on drift
+ */
+import { createRequire } from 'node:module'
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import process from 'node:process'
+
+const checkMode = process.argv.includes('--check')
+
+const packageDir = fileURLToPath(new URL('..', import.meta.url))
+const require = createRequire(join(packageDir, 'package.json'))
+const registry = require('language-subtag-registry/data/json/registry.json')
+
+/**
+ * @typedef {{ Type: string, Subtag?: string, Description?: string[], Deprecated?: string }} RegistryEntry
+ */
+
+/** @param {RegistryEntry} entry */
+function isIsoAlpha2(entry) {
+  if (entry.Type !== 'region') return false
+  if (!entry.Subtag || !/^[A-Z]{2}$/.test(entry.Subtag)) return false
+  if (entry.Deprecated) return false
+  if (!entry.Description || !entry.Description.length) return false
+  if (entry.Description[0] === 'Private use') return false
+  return true
+}
+
+const countries = /** @type {RegistryEntry[]} */ (registry)
+  .filter(isIsoAlpha2)
+  .map((entry) => ({
+    code: /** @type {string} */ (entry.Subtag),
+    name: /** @type {string[]} */ (entry.Description).join(', '),
+  }))
+  .sort((a, b) => a.code.localeCompare(b.code))
+
+const lines = [
+  '// AUTO-GENERATED by scripts/generate-countries.mjs — do not edit by hand.',
+  '// Regenerate via `node packages/shared/scripts/generate-countries.mjs` or the shared package build.',
+  '',
+  'export const REGISTRY_COUNTRIES: Array<{ code: string; name: string }> = [',
+  ...countries.map((c) => `  { code: ${JSON.stringify(c.code)}, name: ${JSON.stringify(c.name)} },`),
+  ']',
+  '',
+]
+
+const outPath = join(packageDir, 'src/lib/location/countries.generated.ts')
+const content = lines.join('\n')
+
+if (checkMode) {
+  if (!existsSync(outPath)) {
+    console.error(`[generate-countries] missing ${outPath}`)
+    process.exit(1)
+  }
+  const existing = readFileSync(outPath, 'utf8')
+  if (existing !== content) {
+    console.error(`[generate-countries] drift detected in ${outPath}`)
+    process.exit(1)
+  }
+  console.log(`[generate-countries] check passed (${countries.length} countries)`)
+} else if (existsSync(outPath) && readFileSync(outPath, 'utf8') === content) {
+  console.log(`[generate-countries] up to date (${countries.length} countries)`)
+} else {
+  writeFileSync(outPath, content, 'utf8')
+  console.log(`[generate-countries] wrote ${countries.length} countries → ${outPath}`)
+}

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

@@ -2,7 +2,18 @@ jest.mock('@open-mercato/cache', () => ({
   runWithCacheTenant: async (_tenantId: string | null, fn: () => Promise<unknown>) => fn(),
 }), { virtual: true })
 
+// Default behavior matches production's fallback-translator shape for a key with no
+// dictionary entry (`dict[key] ?? fallback ?? key`) — shared has no domain dictionary to
+// consult, so every existing test observes the same pass-through it always has. Individual
+// tests override `mockTranslate` to prove `handleError` actually routes a CrudHttpError body
+// through the resolved `translate()` instead of forwarding it verbatim (#5727).
+const mockTranslate = jest.fn((key: string, fallback?: string) => fallback ?? key)
+jest.mock('@open-mercato/shared/lib/i18n/server', () => ({
+  resolveTranslations: async () => ({ t: mockTranslate, translate: mockTranslate }),
+}))
+
 import { makeCrudRoute } from '@open-mercato/shared/lib/crud/factory'
+import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
 import { registerApiInterceptors } from '@open-mercato/shared/lib/crud/interceptor-registry'
 import {
   clearOptimisticLockReadersForTests,
@@ -803,6 +814,139 @@ describe('CRUD Factory', () => {
     })
   })
 
+  describe('afterList hook ordering on the export paths', () => {
+    // Issue #5969: both export branches used to call serializeExport() before awaiting
+    // hooks.afterList, so a hook that patches values the base query cannot compute reached
+    // the JSON list response but never the exported file.
+    const patchTitles = (res: any) => {
+      for (const item of res.items) item.title = `patched:${item.title}`
+    }
+
+    it('GET applies afterList mutations to the query-engine export, matching the JSON list', async () => {
+      const hookedRoute = makeCrudRoute({
+        metadata: { GET: { requireAuth: true } },
+        orm: { entity: Todo, idField: 'id', orgField: 'organizationId', tenantField: 'tenantId', softDeleteField: 'deletedAt' },
+        indexer: { entityType: 'example.todo' },
+        list: {
+          schema: querySchema,
+          entityId: 'example.todo',
+          fields: ['id', 'title', 'is_done'],
+          sortFieldMap: { id: 'id' },
+          buildFilters: () => ({} as any),
+          transformItem: (i: any) => ({ id: i.id, title: i.title }),
+          allowCsv: true,
+          csv: { headers: ['id', 'title'], row: (t: any) => [t.id, t.title], filename: 'todos.csv' },
+        },
+        hooks: { afterList: patchTitles },
+      })
+
+      const jsonRes = await hookedRoute.GET(new Request('http://x/api/example/todos'))
+      expect((await jsonRes.json()).items[0].title).toBe('patched:A')
+
+      const csvRes = await hookedRoute.GET(new Request('http://x/api/example/todos?format=csv'))
+      expect((await csvRes.text()).split('\n')[1]).toBe('id-1,patched:A')
+    })
+
+    it('GET honors an afterList hook that replaces the export payload items', async () => {
+      const replacingRoute = makeCrudRoute({
+        metadata: { GET: { requireAuth: true } },
+        orm: { entity: Todo, idField: 'id', orgField: 'organizationId', tenantField: 'tenantId', softDeleteField: 'deletedAt' },
+        indexer: { entityType: 'example.todo' },
+        list: {
+          schema: querySchema,
+          entityId: 'example.todo',
+          fields: ['id', 'title', 'is_done'],
+          sortFieldMap: { id: 'id' },
+          buildFilters: () => ({} as any),
+          transformItem: (i: any) => ({ id: i.id, title: i.title }),
+          allowCsv: true,
+          csv: { headers: ['id', 'title'], row: (t: any) => [t.id, t.title], filename: 'todos.csv' },
+        },
+        hooks: { afterList: (res: any) => { res.items = [{ id: 'replaced', title: 'Z' }] } },
+      })
+
+      const csvRes = await replacingRoute.GET(new Request('http://x/api/example/todos?format=csv'))
+      expect((await csvRes.text()).split('\n').slice(1)).toEqual(['replaced,Z'])
+    })
+
+    it('GET applies afterList mutations to the ORM-fallback export', async () => {
+      db['id-1'] = { id: 'id-1', title: 'A', organizationId: defaultOrganizationId, tenantId: defaultTenantId }
+      const fallbackRoute = makeCrudRoute({
+        metadata: { GET: { requireAuth: true } },
+        orm: { entity: Todo, idField: 'id', orgField: 'organizationId', tenantField: 'tenantId', softDeleteField: 'deletedAt' },
+        list: {
+          schema: querySchema,
+          buildFilters: () => ({} as any),
+          allowCsv: true,
+          csv: { headers: ['id', 'title'], row: (t: any) => [t.id, t.title], filename: 'todos.csv' },
+        },
+        hooks: { afterList: patchTitles },
+      })
+
+      const jsonRes = await fallbackRoute.GET(new Request('http://x/api/example/todos'))
+      expect((await jsonRes.json()).items[0].title).toBe('patched:A')
+
+      db['id-1'] = { id: 'id-1', title: 'A', organizationId: defaultOrganizationId, tenantId: defaultTenantId }
+      const csvRes = await fallbackRoute.GET(new Request('http://x/api/example/todos?format=csv'))
+      expect((await csvRes.text()).split('\n')[1]).toBe('id-1,patched:A')
+    })
+
+    // #6019 review: on exportScope=full, items are normalized via normalizeFullRecordForExport
+    // before the hook runs but the hook's own additions used to skip that normalization,
+    // leaking `_`-prefixed metadata and un-flattened `cf_*` keys into the exported file.
+    const addAssociationsMetadata = (res: any) => {
+      for (const item of res.items) {
+        item.title = `patched:${item.title}`
+        item._associations = { ok: false, reason: 'lookup failed' }
+        item.cf_color = 're-added'
+      }
+    }
+
+    it('GET re-normalizes afterList output on the full-export query-engine path (#6019)', async () => {
+      const fullExportRoute = makeCrudRoute({
+        metadata: { GET: { requireAuth: true } },
+        orm: { entity: Todo, idField: 'id', orgField: 'organizationId', tenantField: 'tenantId', softDeleteField: 'deletedAt' },
+        indexer: { entityType: 'example.todo' },
+        list: {
+          schema: querySchema,
+          entityId: 'example.todo',
+          fields: ['id', 'title', 'is_done'],
+          sortFieldMap: { id: 'id' },
+          buildFilters: () => ({} as any),
+          transformItem: (i: any) => ({ id: i.id, title: i.title }),
+        },
+        hooks: { afterList: addAssociationsMetadata },
+      })
+
+      const res = await fullExportRoute.GET(new Request('http://x/api/example/todos?format=json&exportScope=full'))
+      const parsed = JSON.parse(await res.text())
+      expect(parsed[0].Title).toBe('patched:A')
+      expect(parsed[0].Color).toBe('re-added')
+      expect(Object.keys(parsed[0])).not.toContain('_associations')
+      expect(JSON.stringify(parsed)).not.toContain('lookup failed')
+    })
+
+    it('GET re-normalizes afterList output on the full-export ORM-fallback path (#6019)', async () => {
+      db['id-1'] = { id: 'id-1', title: 'A', organizationId: defaultOrganizationId, tenantId: defaultTenantId }
+      const fullFallbackRoute = makeCrudRoute({
+        metadata: { GET: { requireAuth: true } },
+        orm: { entity: Todo, idField: 'id', orgField: 'organizationId', tenantField: 'tenantId', softDeleteField: 'deletedAt' },
+        list: {
+          schema: querySchema,
+          buildFilters: () => ({} as any),
+        },
+        hooks: { afterList: addAssociationsMetadata },
+      })
+
+      const res = await fullFallbackRoute.GET(new Request('http://x/api/example/todos?format=json&exportScope=full'))
+      const parsed = JSON.parse(await res.text())
+      expect(parsed[0].Title).toBe('patched:A')
+      expect(parsed[0].Color).toBe('re-added')
+      expect(Object.keys(parsed[0])).not.toContain('_associations')
+      expect(JSON.stringify(parsed)).not.toContain('lookup failed')
+    })
+  })
+
   describe('export loop termination', () => {
     const EXPORT_PAGE_SIZE = 1000
 
@@ -1477,6 +1621,39 @@ describe('CRUD Factory', () => {
     })
   })
 
+  // Issue #5727 — a command that raises CrudHttpError with a raw i18n key (rather than an
+  // already-translated message) must not leak that key verbatim; handleError() routes it
+  // through the resolved translate() before responding.
+  it('POST command route translates a raw i18n key on a CrudHttpError body instead of forwarding it verbatim', async () => {
+    mockTranslate.mockImplementationOnce((key: string, fallback?: string) =>
+      key === 'some_module.errors.lineLocked' ? 'This line is locked.' : (fallback ?? key),
+    )
+    commandBus.execute.mockRejectedValue(new CrudHttpError(400, { error: 'some_module.errors.lineLocked' }))
+
+    const res = await postInterceptorErrorRequest(interceptorErrorRoute())
+
+    expect(res.status).toBe(400)
+    await expect(res.json()).resolves.toEqual({ error: 'This line is locked.' })
+    expect(mockTranslate).toHaveBeenCalledWith('some_module.errors.lineLocked', 'some_module.errors.lineLocked')
+  })
+
+  it('POST command route preserves other CrudHttpError body fields alongside the translated error', async () => {
+    mockTranslate.mockImplementationOnce((key: string, fallback?: string) =>
+      key === 'some_module.errors.conflict' ? 'A conflicting record already exists.' : (fallback ?? key),
+    )
+    commandBus.execute.mockRejectedValue(
+      new CrudHttpError(409, { error: 'some_module.errors.conflict', conflictingId: 'todo-9' }),
+    )
+
+    const res = await postInterceptorErrorRequest(interceptorErrorRoute())
+
+    expect(res.status).toBe(409)
+    await expect(res.json()).resolves.toEqual({
+      error: 'A conflicting record already exists.',
+      conflictingId: 'todo-9',
+    })
+  })
+
   // Issue #5608 — a generic 500 must carry a requestId the client/support can cite, and
   // that same id must appear on the server log line so the two can be correlated.
   describe('generic 500 requestId correlation', () => {

package/src/lib/crud/__tests__/errors.test.ts

@@ -1,4 +1,4 @@
-import { CrudHttpError, isCrudHttpError, assertFound, notFound } from '../errors'
+import { CrudHttpError, isCrudHttpError, assertFound, notFound, translateCrudErrorBody } from '../errors'
 
 describe('CrudHttpError', () => {
   it('builds from string body', () => {
@@ -80,3 +80,33 @@ describe('assertFound', () => {
     }
   })
 })
+
+describe('translateCrudErrorBody', () => {
+  it('translates a raw i18n key found in the dictionary', () => {
+    const dict: Record<string, string> = {
+      'warranty_claims.errors.lineLocked': 'This line is locked in the current claim status.',
+    }
+    const translate = (key: string, fallback?: string) => dict[key] ?? fallback ?? key
+    const body = translateCrudErrorBody({ error: 'warranty_claims.errors.lineLocked' }, translate)
+    expect(body).toEqual({ error: 'This line is locked in the current claim status.' })
+  })
+
+  it('falls back to the raw key when the dictionary has no entry, instead of throwing', () => {
+    const translate = (key: string, fallback?: string) => fallback ?? key
+    const body = translateCrudErrorBody({ error: 'warranty_claims.errors.unknownKey' }, translate)
+    expect(body).toEqual({ error: 'warranty_claims.errors.unknownKey' })
+  })
+
+  it('preserves other body fields untouched', () => {
+    const translate = (key: string) => `translated:${key}`
+    const body = translateCrudErrorBody({ error: 'some.key', field: 'x', code: 42 }, translate)
+    expect(body).toEqual({ error: 'translated:some.key', field: 'x', code: 42 })
+  })
+
+  it('returns the body unchanged when error is not a string', () => {
+    const translate = jest.fn((key: string) => key)
+    const body = translateCrudErrorBody({ field: 'x' }, translate)
+    expect(body).toEqual({ field: 'x' })
+    expect(translate).not.toHaveBeenCalled()
+  })
+})

package/src/lib/crud/errors.ts

@@ -96,3 +96,19 @@ export function assertFound<T>(value: T | null | undefined, message: string): T
   if (!value) throw notFound(message)
   return value
 }
+
+/**
+ * Translates a `CrudHttpError` body's `error` field before it reaches the client.
+ * Some callers (command handlers, lib helpers reused by subscribers/CLI/workers) raise
+ * `CrudHttpError` with a raw i18n key because they run without a request locale — a route
+ * handler forwarding `err.body` verbatim would leak that key to the user. Call this at the
+ * route boundary, passing the `translate` the route already resolved, instead of forwarding
+ * `err.body` directly.
+ */
+export function translateCrudErrorBody<T extends Record<string, unknown>>(
+  body: T,
+  translate: (key: string, fallback?: string) => string,
+): T {
+  if (typeof body?.error !== 'string') return body
+  return { ...body, error: translate(body.error, body.error) }
+}

package/src/lib/crud/factory.ts

@@ -10,6 +10,7 @@ import { resolveOrganizationScopeForRequest, type OrganizationScope } from '@ope
 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 { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
 import {
   runMutationGuards,
   bridgeLegacyGuard,
@@ -41,7 +42,7 @@ import {
   type ResolvedCustomFieldDefinitions,
 } from './custom-field-definition-index'
 import { serializeExport, normalizeExportFormat, defaultExportFilename, ensureColumns, type CrudExportFormat, type PreparedExport } from './exporters'
-import { CrudHttpError, isCrudHttpError } from './errors'
+import { CrudHttpError, isCrudHttpError, translateCrudErrorBody } from './errors'
 import type { CommandBus, CommandLogMetadata } from '@open-mercato/shared/lib/commands'
 import type { EntityId } from '@open-mercato/shared/modules/entities'
 import type { EntityManager } from '@mikro-orm/postgresql'
@@ -634,9 +635,12 @@ function classifyCrudError(err: unknown): { code: CrudErrorCode; pgSqlState: str
   return { code: 'INTERNAL_ERROR', pgSqlState: null }
 }
 
-function handleError(err: unknown, request?: Request): Response {
+async function handleError(err: unknown, request?: Request): Promise<Response> {
   if (err instanceof Response) return err
-  if (isCrudHttpError(err)) return json(err.body, { status: err.status })
+  if (isCrudHttpError(err)) {
+    const { translate } = await resolveTranslations()
+    return json(translateCrudErrorBody(err.body, translate), { 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).
@@ -2027,15 +2031,25 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
               nextPage += 1
             }
           }
+          const exportPayload = { items: exportItems, total, page: 1, pageSize: exportItems.length, totalPages: 1, ...(res.meta ? { meta: res.meta } : {}) }
+          // Serialize only after `afterList` has run: the hook is the documented place to
+          // patch values the base query cannot compute, and an export built before it runs
+          // ships a different shape than the JSON list response for the same request (#5969).
+          await opts.hooks?.afterList?.(exportPayload, { ...ctx, query: validated as any })
+          profiler.mark('after_list_hook')
+          const hookExportItems = Array.isArray(exportPayload.items) ? exportPayload.items : exportItems
+          // Re-normalize after the hook: `afterList` can add keys the full-export contract
+          // strips (`_`-prefixed metadata, `cf_*`) or fail to flatten (#6019 review).
+          // Idempotent on records already shaped by normalizeFullRecordForExport above.
+          const finalExportItems = exportFullRequested
+            ? hookExportItems.map(normalizeFullRecordForExport)
+            : hookExportItems
           const prepared = exportFullRequested
-            ? { columns: ensureColumns(exportItems), rows: exportItems }
-            : prepareExportData(exportItems, opts.list, validated as any, ctx)
+            ? { columns: ensureColumns(finalExportItems), rows: finalExportItems }
+            : prepareExportData(finalExportItems, opts.list, validated as any, ctx)
           const fallbackBase = `${opts.events?.entity || resourceKind || 'list'}${exportFullRequested ? '_full' : ''}`
           const filename = finalizeExportFilename(opts.list, requestedExport, fallbackBase)
           const serialized = serializeExport(prepared, requestedExport)
-          const exportPayload = { items: exportItems, total, page: 1, pageSize: exportItems.length, totalPages: 1, ...(res.meta ? { meta: res.meta } : {}) }
-          await opts.hooks?.afterList?.(exportPayload, { ...ctx, query: validated as any })
-          profiler.mark('after_list_hook')
           const response = new Response(serialized.body, {
             headers: {
               'content-type': serialized.contentType,
@@ -2058,7 +2072,7 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
           finishProfile({
             result: 'export',
             cacheStatus,
-            itemCount: exportItems.length,
+            itemCount: finalExportItems.length,
             total,
           })
           return response
@@ -2230,14 +2244,22 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
       profiler.mark('access_logged', accessLogResult)
       if (exportRequested && requestedExport) {
         const exportItems = exportFullRequested ? list.map(normalizeFullRecordForExport) : list
+        const exportPayload = { items: exportItems, total: exportItems.length, page: 1, pageSize: exportItems.length, totalPages: 1 }
+        // Same ordering contract as the query-engine export path above (#5969).
+        await opts.hooks?.afterList?.(exportPayload, { ...ctx, query: validated as any })
+        profiler.mark('after_list_hook')
+        const hookExportItems = Array.isArray(exportPayload.items) ? exportPayload.items : exportItems
+        // Re-normalize after the hook: same full-export contract as the query-engine path
+        // above (#6019 review).
+        const finalExportItems = exportFullRequested
+          ? hookExportItems.map(normalizeFullRecordForExport)
+          : hookExportItems
         const prepared = exportFullRequested
-          ? { columns: ensureColumns(exportItems), rows: exportItems }
-          : prepareExportData(exportItems, opts.list, validated as any, ctx)
+          ? { columns: ensureColumns(finalExportItems), rows: finalExportItems }
+          : prepareExportData(finalExportItems, opts.list, validated as any, ctx)
         const fallbackBase = `${opts.events?.entity || resourceKind || 'list'}${exportFullRequested ? '_full' : ''}`
         const filename = finalizeExportFilename(opts.list, requestedExport, fallbackBase)
         const serialized = serializeExport(prepared, requestedExport)
-        await opts.hooks?.afterList?.({ items: exportItems, total: exportItems.length, page: 1, pageSize: exportItems.length, totalPages: 1 }, { ...ctx, query: validated as any })
-        profiler.mark('after_list_hook')
         const response = new Response(serialized.body, {
           headers: {
             'content-type': serialized.contentType,
@@ -2247,8 +2269,8 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
         finishProfile({
           result: 'export',
           cacheStatus,
-          itemCount: exportItems.length,
-          total: exportItems.length,
+          itemCount: finalExportItems.length,
+          total: finalExportItems.length,
           branch: 'fallback',
         })
         return response