From c953465c9cdde6326f0da1bb0966c2c6ae5b4789 Mon Sep 17 00:00:00 2001
From: sebastianbarrozo <sebastian.barrozo@etendo.software>
Date: Thu, 23 Jul 2026 09:11:04 -0300
Subject: [PATCH 01/10] Feature ETP-4559: Neutralize CSV formula injection in
 client CSV builders

---
 packages/app-shell-core/package.json          |   2 +-
 .../components/import/ImportReviewQueue.jsx   |  10 +-
 .../lib/csv/__tests__/csvSerializer.test.js   | 101 ++++++++++++++++++
 .../src/lib/csv/csvSerializer.js              |  26 +++++
 .../src/lib/import/buildTemplateCsv.js        |   7 +-
 5 files changed, 133 insertions(+), 13 deletions(-)
 create mode 100644 packages/app-shell-core/src/lib/csv/__tests__/csvSerializer.test.js
 create mode 100644 packages/app-shell-core/src/lib/csv/csvSerializer.js

diff --git a/packages/app-shell-core/package.json b/packages/app-shell-core/package.json
index b8d9eb808..2d327918d 100644
--- a/packages/app-shell-core/package.json
+++ b/packages/app-shell-core/package.json
@@ -39,7 +39,7 @@
     "!src/**/__tests__/**"
   ],
   "scripts": {
-    "test": "node --test test/*.test.js src/auth/__tests__/*.test.js src/i18n/__tests__/*.test.js src/runtime/__tests__/*.test.js src/theme/__tests__/*.test.js src/components/ui/__tests__/*.test.js src/lib/__tests__/*.test.js src/lib/validation/__tests__/*.test.js src/lib/import/__tests__/*.test.js",
+    "test": "node --test test/*.test.js src/auth/__tests__/*.test.js src/i18n/__tests__/*.test.js src/runtime/__tests__/*.test.js src/theme/__tests__/*.test.js src/components/ui/__tests__/*.test.js src/lib/__tests__/*.test.js src/lib/validation/__tests__/*.test.js src/lib/import/__tests__/*.test.js src/lib/csv/__tests__/*.test.js",
     "test:vitest": "vitest run",
     "test:consumer": "node scripts/package-consumer-smoke.mjs"
   },
diff --git a/packages/app-shell-core/src/components/import/ImportReviewQueue.jsx b/packages/app-shell-core/src/components/import/ImportReviewQueue.jsx
index 5111ac67a..c09c0f4a8 100644
--- a/packages/app-shell-core/src/components/import/ImportReviewQueue.jsx
+++ b/packages/app-shell-core/src/components/import/ImportReviewQueue.jsx
@@ -7,6 +7,7 @@ import { Popover, PopoverTrigger, PopoverContent } from '../ui/popover.jsx';
 import { Command, CommandInput, CommandList, CommandEmpty, CommandGroup, CommandItem } from '../ui/command.jsx';
 import { Dialog, DialogContent, DialogHeader, DialogFooter, DialogTitle, DialogDescription } from '../ui/dialog.jsx';
 import { ScrollPane } from '../ui/scroll-pane.jsx';
+import { csvField } from '../../lib/csv/csvSerializer.js';
 
 const DEFAULT_LABELS = {
   filterAll: 'All',
@@ -79,11 +80,6 @@ const STATUS_TAG_COLORS = {
   neutral: 'bg-[#F5F7F9] text-[#3F3F50]',
 };
 
-function csvEscape(value) {
-  const s = String(value ?? '');
-  return /[",\n]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s;
-}
-
 /** Line number + status pill, shared by every row in the frozen leading column. */
 function StatusLineTag({ index, tag, children }) {
   return (
@@ -266,12 +262,12 @@ function FkMismatchCell({ index, field, value, error, onSelect, simSearchFn, tok
  */
 export function buildErrorsCsv(entries, headers, mapping) {
   const mappedHeaders = headers.filter((h) => mapping[h]);
-  const lines = [[...mappedHeaders, 'Error'].map(csvEscape).join(',')];
+  const lines = [[...mappedHeaders, 'Error'].map(csvField).join(',')];
   for (const entry of entries) {
     if (entry.errors.length === 0) continue;
     const values = mappedHeaders.map((h) => entry.row[mapping[h]]);
     const errorText = entry.errors.map((e) => (e.target ? `${e.target}: ${e.message}` : e.message)).join(' | ');
-    lines.push([...values, errorText].map(csvEscape).join(','));
+    lines.push([...values, errorText].map(csvField).join(','));
   }
   return lines.join('\n');
 }
diff --git a/packages/app-shell-core/src/lib/csv/__tests__/csvSerializer.test.js b/packages/app-shell-core/src/lib/csv/__tests__/csvSerializer.test.js
new file mode 100644
index 000000000..c2d0d266f
--- /dev/null
+++ b/packages/app-shell-core/src/lib/csv/__tests__/csvSerializer.test.js
@@ -0,0 +1,101 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { csvField } from '../csvSerializer.js';
+
+describe('csvField', () => {
+  describe('neutralizes spreadsheet formula injection', () => {
+    it('prepends an apostrophe to a value starting with =', () => {
+      assert.equal(csvField('=1+1'), "'=1+1");
+    });
+
+    it('prepends an apostrophe to a value starting with +', () => {
+      assert.equal(csvField('+SUM(A1:A2)'), "'+SUM(A1:A2)");
+    });
+
+    it('prepends an apostrophe to a value starting with -', () => {
+      assert.equal(csvField('-CMD'), "'-CMD");
+    });
+
+    it('prepends an apostrophe to a value starting with @', () => {
+      assert.equal(csvField('@SUM(A1:A2)'), "'@SUM(A1:A2)");
+    });
+
+    it('catches a marker hiding behind a leading tab', () => {
+      assert.equal(csvField('\t=1+1'), "'\t=1+1");
+    });
+
+    it('catches a marker hiding behind a leading carriage return', () => {
+      assert.equal(csvField('\r=1+1'), "'\r=1+1");
+    });
+
+    it('catches a marker hiding behind leading spaces', () => {
+      assert.equal(csvField('   =1+1'), "'   =1+1");
+    });
+
+    it('catches a marker hiding behind a leading line feed (and quotes it, since it now contains a raw newline)', () => {
+      assert.equal(csvField('\n=1+1'), '"\'\n=1+1"');
+    });
+
+    it('neutralizes AND quotes when the value also needs RFC 4180 quoting', () => {
+      assert.equal(csvField('=1+1,extra'), '"\'=1+1,extra"');
+    });
+  });
+
+  describe('does not double-prefix or break legitimate values', () => {
+    it('does not add a second apostrophe to an already-neutralized value', () => {
+      assert.equal(csvField("'=1+1"), "'=1+1");
+    });
+
+    it('neutralizes a legitimate negative number (documented trade-off, same as the server policy)', () => {
+      assert.equal(csvField('-500.00'), "'-500.00");
+    });
+
+    it('leaves ordinary text untouched', () => {
+      assert.equal(csvField('Normal Value'), 'Normal Value');
+    });
+
+    it('leaves zero untouched', () => {
+      assert.equal(csvField(0), '0');
+    });
+
+    it('returns an empty string for null', () => {
+      assert.equal(csvField(null), '');
+    });
+
+    it('returns an empty string for undefined', () => {
+      assert.equal(csvField(undefined), '');
+    });
+
+    it('returns an empty string for an empty string', () => {
+      assert.equal(csvField(''), '');
+    });
+
+    it('quotes a value containing a comma', () => {
+      assert.equal(csvField('texto, con coma'), '"texto, con coma"');
+    });
+
+    it('escapes embedded double quotes and quotes the field', () => {
+      assert.equal(csvField('con "comillas" internas'), '"con ""comillas"" internas"');
+    });
+
+    it('preserves an embedded (non-leading) line feed and quotes the field', () => {
+      assert.equal(csvField('line one\nline two'), '"line one\nline two"');
+    });
+
+    it('preserves an embedded (non-leading) CRLF and quotes the field', () => {
+      assert.equal(csvField('line one\r\nline two'), '"line one\r\nline two"');
+    });
+
+    it('preserves Unicode characters', () => {
+      assert.equal(csvField('José Ñáñez'), 'José Ñáñez');
+    });
+
+    it('leaves a safe header untouched', () => {
+      assert.equal(csvField('Commercial Name'), 'Commercial Name');
+    });
+
+    it('is deterministic across repeated calls', () => {
+      assert.equal(csvField('=1+1'), csvField('=1+1'));
+    });
+  });
+});
diff --git a/packages/app-shell-core/src/lib/csv/csvSerializer.js b/packages/app-shell-core/src/lib/csv/csvSerializer.js
new file mode 100644
index 000000000..ca7f98bc2
--- /dev/null
+++ b/packages/app-shell-core/src/lib/csv/csvSerializer.js
@@ -0,0 +1,26 @@
+const FORMULA_TRIGGER_CHARS = '=+-@';
+
+/**
+ * A value is formula-sensitive when its first non-whitespace character is a spreadsheet
+ * formula trigger. Leading whitespace/control characters (space, tab, CR, LF) are skipped
+ * first so a marker cannot hide behind them. Mirrors the server-side policy in
+ * NeoCsvExportService.java (com.etendoerp.go) so both sides neutralize the same inputs.
+ */
+function isFormulaInjection(value) {
+  let i = 0;
+  while (i < value.length && /\s/.test(value[i])) i++;
+  return i < value.length && FORMULA_TRIGGER_CHARS.includes(value[i]);
+}
+
+/**
+ * Serializes a single CSV field: neutralizes spreadsheet formula injection (CWE-1236) by
+ * prepending an apostrophe when the value is formula-sensitive, then applies RFC 4180
+ * quoting (only when the value contains a comma, quote, or newline).
+ */
+export function csvField(value) {
+  let s = String(value ?? '');
+  if (isFormulaInjection(s)) {
+    s = `'${s}`;
+  }
+  return /[",\n]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s;
+}
diff --git a/packages/app-shell-core/src/lib/import/buildTemplateCsv.js b/packages/app-shell-core/src/lib/import/buildTemplateCsv.js
index 994cd0393..102742cd5 100644
--- a/packages/app-shell-core/src/lib/import/buildTemplateCsv.js
+++ b/packages/app-shell-core/src/lib/import/buildTemplateCsv.js
@@ -1,7 +1,4 @@
-function csvEscape(value) {
-  const s = String(value ?? '');
-  return /[",\n]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s;
-}
+import { csvField } from '../csv/csvSerializer.js';
 
 /**
  * Builds a blank (header-row-only) CSV template for a window's import
@@ -13,6 +10,6 @@ function csvEscape(value) {
  */
 export function buildTemplateCsv(fields) {
   return fields
-    .map((field) => csvEscape(field.aliases?.[0] ?? field.label ?? field.target))
+    .map((field) => csvField(field.aliases?.[0] ?? field.label ?? field.target))
     .join(',');
 }

From fe3d7b6a6202e23b58b5246e6c3e6180fa9839cc Mon Sep 17 00:00:00 2001
From: sebastianbarrozo <sebastian.barrozo@etendo.software>
Date: Thu, 23 Jul 2026 19:41:54 -0300
Subject: [PATCH 02/10] Feature ETP-4657: Fix semantic color token drift from
 ETP-4554

- Restore --foreground/--muted-foreground/--border-subtle to match
  the original design (verified against staging) after they drifted
  to unaudited generic shadcn defaults during the ETP-4554 migration.
- Revert --border-control/--input to the original light color: it
  drove both real form-control borders AND shared outline buttons,
  so its WCAG 1.4.11 fix visually broke buttons too. Documented as
  an accepted, known a11y gap (WARN comments) instead of silently
  dropped.
- Add ALIAS_TOKEN_PAIRS consistency check (theme/index.js +
  accessibility.test.js) so generic tokens can't silently drift
  from the audited accessibility contract again.
- Fix shared TableRow/TableHeader/TableFooter: used border-structural
  (WCAG 3:1-gated, meant for real structural boundaries) for plain
  decorative row/section dividers; switched to border-subtle.
---
 .../src/components/ui/table.jsx               | 15 +++-
 packages/app-shell-core/src/styles.css        | 20 +++--
 .../src/theme/__tests__/accessibility.test.js | 73 +++++++++++++++++--
 packages/app-shell-core/src/theme/index.js    | 50 ++++++++++++-
 4 files changed, 143 insertions(+), 15 deletions(-)

diff --git a/packages/app-shell-core/src/components/ui/table.jsx b/packages/app-shell-core/src/components/ui/table.jsx
index 7c3659402..afd765d7d 100644
--- a/packages/app-shell-core/src/components/ui/table.jsx
+++ b/packages/app-shell-core/src/components/ui/table.jsx
@@ -13,7 +13,8 @@ const Table = React.forwardRef(({ className, ...props }, ref) => (
 Table.displayName = "Table"
 
 const TableHeader = React.forwardRef(({ className, ...props }, ref) => (
-  <thead ref={ref} className={cn("[&_tr]:border-b [&_tr]:border-border-structural", className)} {...props} />
+  // WARN(a11y): border-border-subtle, not border-border-structural — see TableRow below.
+  <thead ref={ref} className={cn("[&_tr]:border-b [&_tr]:border-border-subtle", className)} {...props} />
 ))
 TableHeader.displayName = "TableHeader"
 
@@ -26,9 +27,10 @@ const TableBody = React.forwardRef(({ className, ...props }, ref) => (
 TableBody.displayName = "TableBody"
 
 const TableFooter = React.forwardRef(({ className, ...props }, ref) => (
+  // WARN(a11y): border-border-subtle, not border-border-structural — see TableRow below.
   <tfoot
     ref={ref}
-    className={cn("border-t border-border-structural font-medium [&>tr]:last:border-b-0", className)}
+    className={cn("border-t border-border-subtle font-medium [&>tr]:last:border-b-0", className)}
     {...props} />
 ))
 TableFooter.displayName = "TableFooter"
@@ -36,8 +38,15 @@ TableFooter.displayName = "TableFooter"
 const TableRow = React.forwardRef(({ className, ...props }, ref) => (
   <tr
     ref={ref}
+    // WARN(a11y): intentionally border-border-subtle, NOT border-border-structural,
+    // for the whole Table (header, body rows, footer). A table hairline isn't a UI
+    // component boundary under WCAG 1.4.11 (cell content + hover/selected bg already
+    // convey the boundary), so it doesn't need the enforced 3:1 contrast — confirmed
+    // against staging (go.staging.etendo.cloud), which never had this distinction.
+    // border-border-structural stays reserved for genuinely structural separators
+    // elsewhere (e.g. BalanceFooterPanel, DocumentTotalsPanel).
     className={cn(
-      "border-b border-border-structural transition-colors hover:bg-muted/50 data-[state=selected]:bg-muted",
+      "border-b border-border-subtle transition-colors hover:bg-muted/50 data-[state=selected]:bg-muted",
       className
     )}
     {...props} />
diff --git a/packages/app-shell-core/src/styles.css b/packages/app-shell-core/src/styles.css
index 6e699755c..10a10b4ac 100644
--- a/packages/app-shell-core/src/styles.css
+++ b/packages/app-shell-core/src/styles.css
@@ -286,7 +286,7 @@
 
   :root {
     --background: 220 14% 96%;
-    --foreground: 222 47% 11%;
+    --foreground: 222 47% 11%;             /* #0F1729 — matches staging (go.staging.etendo.cloud), the original design spec's color */
     --card: 0 0% 100%;
     --card-foreground: 222 47% 11%;
     --popover: 0 0% 100%;
@@ -296,7 +296,7 @@
     --secondary: 210 40% 96%;
     --secondary-foreground: 222 47% 11%;
     --muted: 210 40% 96%;
-    --muted-foreground: 215 16% 47%;
+    --muted-foreground: 240 12% 48%;       /* #6C6C89 — NOT staging's #65758B: that fails WCAG AA (4.3:1) against --background (only passes 4.7:1 against white --card); this is the a11y-review fix, matches --text-secondary */
     --accent: 210 40% 96%;
     --accent-foreground: 222 47% 11%;
     --destructive: 0 84% 60%;
@@ -306,10 +306,20 @@
     --inverse-muted: 215 16% 72%;
     --inverse-border: 215 20% 30%;
     /* Semantic accessibility contract v1 (ETP-4554). */
-    --border-control: 215 16% 47%;
+    /* WARN(a11y): --border-control (and --input, which aliases it) is back to
+       staging's original light color. It drives BOTH real form-control borders
+       AND the shared outline-button border (shadcn's `border-input` convention),
+       so darkening it for WCAG 1.4.11 compliance visually affected buttons too,
+       which the design didn't want. Known gap: at this value, --border-control
+       only reaches ~1.5:1 contrast against --background/--card, short of the
+       3:1 WCAG 1.4.11 non-text contrast minimum for control boundaries. Revisit
+       by splitting a dedicated (darker) token for real <input>/<select> borders
+       if/when accessibility compliance is prioritized over matching staging.
+       See theme/index.js: removed from the enforced `requirements` contrast list. */
+    --border-control: 214 32% 91%;
     --border-structural: 215 16% 47%;
-    --border-subtle: 214 32% 85%;
-    --text-primary: 240 12% 8%;
+    --border-subtle: 214 32% 91%;          /* #E1E7EF — matches staging exactly (decorative divider, not a11y-gated) */
+    --text-primary: 222 47% 11%;
     --text-secondary: 240 12% 48%;
     --text-disabled: 225 12% 38%;
     --icon-secondary: 215 16% 47%;
diff --git a/packages/app-shell-core/src/theme/__tests__/accessibility.test.js b/packages/app-shell-core/src/theme/__tests__/accessibility.test.js
index 3abfe7d31..6d10d9965 100644
--- a/packages/app-shell-core/src/theme/__tests__/accessibility.test.js
+++ b/packages/app-shell-core/src/theme/__tests__/accessibility.test.js
@@ -3,6 +3,7 @@ import assert from 'node:assert/strict';
 import { readFile } from 'node:fs/promises';
 
 import {
+  ALIAS_TOKEN_PAIRS,
   SEMANTIC_THEME_TOKENS,
   contrastRatio,
   extractThemeTokens,
@@ -11,6 +12,21 @@ import {
 
 const stylesUrl = new URL('../../styles.css', import.meta.url);
 
+const VALID_THEME = {
+  '--background': '0 0% 100%',
+  '--card': '0 0% 100%',
+  '--border-control': '0 0% 40%',
+  '--border-structural': '0 0% 40%',
+  '--border-subtle': '0 0% 90%',
+  '--text-primary': '0 0% 10%',
+  '--text-secondary': '0 0% 40%',
+  '--text-disabled': '0 0% 40%',
+  '--icon-secondary': '0 0% 40%',
+  '--focus-ring': '0 0% 0%',
+  '--foreground': '0 0% 10%',
+  '--muted-foreground': '0 0% 40%',
+};
+
 describe('semantic accessibility theme contract (ETP-4554)', () => {
   it('calculates WCAG contrast for known pairs and accepts uppercase hex', () => {
     assert.equal(contrastRatio('#000000', '#FFFFFF'), 21);
@@ -57,24 +73,71 @@ describe('semantic accessibility theme contract (ETP-4554)', () => {
       '--focus-ring': '0 0% 10%',
     });
 
-    assert.ok(errors.some((error) => error.includes('--border-control') && error.includes('--card')));
+    assert.ok(errors.some((error) => error.includes('--border-structural') && error.includes('--card')));
   });
 
-  it('validates every semantic value and the focus ring against its control boundary', () => {
+  it('does not gate --border-control — it is a documented, accepted a11y gap', () => {
+    // WARN(a11y) in styles.css: --border-control matches staging's light color,
+    // ~1.5:1 against background/card, well short of 3:1. This must NOT fail.
     const errors = validateThemeContract({
       '--background': '0 0% 100%',
       '--card': '0 0% 100%',
-      '--border-control': '0 0% 40%',
+      '--border-control': '0 0% 95%',
+      '--border-structural': '0 0% 40%',
+      '--border-subtle': '0 0% 90%',
+      '--text-primary': '0 0% 10%',
+      '--text-secondary': '0 0% 40%',
+      '--text-disabled': '0 0% 40%',
+      '--icon-secondary': '0 0% 40%',
+      '--focus-ring': '0 0% 10%',
+    });
+
+    assert.deepEqual(errors, []);
+  });
+
+  it('validates every semantic value including the focus ring against page surfaces', () => {
+    const errors = validateThemeContract({
+      '--background': '0 0% 100%',
+      '--card': '0 0% 100%',
+      '--border-control': '0 0% 95%',
       '--border-structural': '0 0% 40%',
       '--border-subtle': 'not-a-colour',
       '--text-primary': '0 0% 10%',
       '--text-secondary': '0 0% 40%',
       '--text-disabled': '0 0% 40%',
       '--icon-secondary': '0 0% 40%',
-      '--focus-ring': '0 0% 40%',
+      '--focus-ring': '0 0% 96%',
     });
 
     assert.ok(errors.some((error) => error.includes('--border-subtle') && error.includes('invalid')));
-    assert.ok(errors.some((error) => error.includes('--focus-ring') && error.includes('--border-control')));
+    assert.ok(errors.some((error) => error.includes('--focus-ring') && error.includes('--card')));
+  });
+
+  it('passes when generic role tokens stay equal to their audited counterparts', () => {
+    assert.deepEqual(validateThemeContract(VALID_THEME), []);
+  });
+
+  it('flags a generic token that drifts from its accessibility-audited counterpart', () => {
+    // Reproduces the ETP-4659 regression: --foreground kept its unaudited shadcn
+    // default while --text-primary was corrected, so the app rendered a
+    // different ink color than the one the contrast contract had verified.
+    const drifted = { ...VALID_THEME, '--foreground': '222 47% 11%' };
+
+    const errors = validateThemeContract(drifted);
+
+    assert.ok(errors.some((error) => error.includes('--foreground') && error.includes('--text-primary')));
+  });
+
+  it('does not require every alias pair to be present to validate the rest', () => {
+    const partial = { ...VALID_THEME };
+    delete partial['--foreground'];
+
+    assert.deepEqual(validateThemeContract(partial), []);
+  });
+
+  it('keeps ALIAS_TOKEN_PAIRS pointing only at real semantic tokens', () => {
+    for (const [, canonical] of ALIAS_TOKEN_PAIRS) {
+      assert.ok(SEMANTIC_THEME_TOKENS.includes(canonical), `${canonical} must be a SEMANTIC_THEME_TOKENS entry`);
+    }
   });
 });
diff --git a/packages/app-shell-core/src/theme/index.js b/packages/app-shell-core/src/theme/index.js
index 6cdb69b36..88ce764b2 100644
--- a/packages/app-shell-core/src/theme/index.js
+++ b/packages/app-shell-core/src/theme/index.js
@@ -15,6 +15,30 @@ export const SEMANTIC_THEME_TOKENS = Object.freeze([
   '--focus-ring',
 ]);
 
+/**
+ * shadcn/Tailwind's generic role tokens (--foreground, --card-foreground, ...)
+ * are what application code actually consumes via Tailwind utilities
+ * (text-foreground, ...) — SEMANTIC_THEME_TOKENS above is rarely used
+ * directly. Each generic token here must resolve to the exact same color as
+ * its audited counterpart in BOTH themes, so a future edit to one side can't
+ * silently drift the app's rendered colors away from the ETP-4554 contrast
+ * contract while this test keeps passing.
+ *
+ * Deliberately excludes --primary, --inverse, --sidebar-foreground and
+ * --sidebar-accent-foreground: those legitimately diverge from --text-primary
+ * in the dark theme (a distinct brand-blue primary, an inverted-background
+ * role, and a separately-tuned near-white sidebar text), so they are not safe
+ * to pin to a single canonical token across both themes.
+ */
+export const ALIAS_TOKEN_PAIRS = Object.freeze([
+  ['--foreground', '--text-primary'],
+  ['--card-foreground', '--text-primary'],
+  ['--popover-foreground', '--text-primary'],
+  ['--secondary-foreground', '--text-primary'],
+  ['--accent-foreground', '--text-primary'],
+  ['--muted-foreground', '--text-secondary'],
+]);
+
 function parseHex(value) {
   const match = value.trim().match(/^#([\da-f]{3}|[\da-f]{6})$/i);
   if (!match) return null;
@@ -92,14 +116,17 @@ export function validateThemeContract(theme) {
     }
   }
 
+  // WARN(a11y): --border-control is deliberately NOT gated here (see styles.css).
+  // It's back to staging's light color, which is ~1.5:1 against --background/--card —
+  // short of the WCAG 1.4.11 3:1 minimum. Known, accepted gap; do not re-add without
+  // also resolving the button-vs-input token conflict documented at its definition.
   const requirements = [
-    ['--border-control', ['--background', '--card'], 3],
     ['--border-structural', ['--background', '--card'], 3],
     ['--text-primary', ['--background', '--card'], 4.5],
     ['--text-secondary', ['--background', '--card'], 4.5],
     ['--text-disabled', ['--background', '--card'], 4.5],
     ['--icon-secondary', ['--background', '--card'], 3],
-    ['--focus-ring', ['--background', '--card', '--border-control'], 3],
+    ['--focus-ring', ['--background', '--card'], 3],
   ];
 
   for (const [token, surfaces, minimum] of requirements) {
@@ -112,5 +139,24 @@ export function validateThemeContract(theme) {
       }
     }
   }
+
+  for (const [alias, canonical] of ALIAS_TOKEN_PAIRS) {
+    if (!theme[alias] || !theme[canonical]) continue;
+    try {
+      const [ar, ag, ab] = parseColor(theme[alias]);
+      const [cr, cg, cb] = parseColor(theme[canonical]);
+      const driftedChannel = [ar - cr, ag - cg, ab - cb].some((delta) => Math.abs(delta) > 1 / 255);
+      if (driftedChannel) {
+        errors.push(
+          `${alias} (${theme[alias]}) has drifted from its accessibility-audited counterpart `
+          + `${canonical} (${theme[canonical]}); keep them equal or move ${alias} into SEMANTIC_THEME_TOKENS `
+          + 'with its own contrast requirement',
+        );
+      }
+    } catch (error) {
+      errors.push(`${alias} or ${canonical} is invalid: ${error.message}`);
+    }
+  }
+
   return errors;
 }

From 6b22c93ee57043e3cbded7cbd32f1e33667a2ff6 Mon Sep 17 00:00:00 2001
From: sebastianbarrozo <sebastian.barrozo@etendo.software>
Date: Fri, 24 Jul 2026 07:47:20 -0300
Subject: [PATCH 03/10] Feature ETP-4657: Fix data-testid codemod formatting in
 Table

---
 packages/app-shell-core/src/components/ui/table.jsx | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/packages/app-shell-core/src/components/ui/table.jsx b/packages/app-shell-core/src/components/ui/table.jsx
index afd765d7d..37d9b08d0 100644
--- a/packages/app-shell-core/src/components/ui/table.jsx
+++ b/packages/app-shell-core/src/components/ui/table.jsx
@@ -14,7 +14,7 @@ Table.displayName = "Table"
 
 const TableHeader = React.forwardRef(({ className, ...props }, ref) => (
   // WARN(a11y): border-border-subtle, not border-border-structural — see TableRow below.
-  <thead ref={ref} className={cn("[&_tr]:border-b [&_tr]:border-border-subtle", className)} {...props} />
+  (<thead ref={ref} className={cn("[&_tr]:border-b [&_tr]:border-border-subtle", className)} {...props} />)
 ))
 TableHeader.displayName = "TableHeader"
 
@@ -28,10 +28,10 @@ TableBody.displayName = "TableBody"
 
 const TableFooter = React.forwardRef(({ className, ...props }, ref) => (
   // WARN(a11y): border-border-subtle, not border-border-structural — see TableRow below.
-  <tfoot
+  (<tfoot
     ref={ref}
     className={cn("border-t border-border-subtle font-medium [&>tr]:last:border-b-0", className)}
-    {...props} />
+    {...props} />)
 ))
 TableFooter.displayName = "TableFooter"
 

From d7429d44f01aae943b4c461d22c891d4b9ae3d75 Mon Sep 17 00:00:00 2001
From: sebastianbarrozo <sebastian.barrozo@etendo.software>
Date: Fri, 24 Jul 2026 09:34:30 -0300
Subject: [PATCH 04/10] Feature ETP-4669: i18n import flow labels + friendly
 backend errors

---
 .../src/components/import/ImportDialog.jsx    |  66 +++++++--
 .../import/__tests__/ImportDialog.test.jsx    |  10 +-
 .../lib/import/__tests__/importEngine.test.js |  79 ++++++-----
 .../src/lib/import/importEngine.js            | 125 ++++++++++++++----
 4 files changed, 209 insertions(+), 71 deletions(-)

diff --git a/packages/app-shell-core/src/components/import/ImportDialog.jsx b/packages/app-shell-core/src/components/import/ImportDialog.jsx
index d6bd60ec9..353b5c268 100644
--- a/packages/app-shell-core/src/components/import/ImportDialog.jsx
+++ b/packages/app-shell-core/src/components/import/ImportDialog.jsx
@@ -18,7 +18,38 @@ import { buildOperations } from '../../lib/import/buildOperations.js';
 import { runImport, sendRow, SEND_STATUS } from '../../lib/import/importEngine.js';
 import { buildTemplateCsv } from '../../lib/import/buildTemplateCsv.js';
 
-const DEFAULT_LABELS = { title: 'Import', revalidating: 'Revalidating rows…', downloadTemplate: 'Download CSV template' };
+// Root-level labels for ImportDialog's own chrome. `importButton` is a function of the
+// valid-row count, mirroring the (n) => string labels the confirm step already uses, so the
+// whole flow's button text is translatable rather than the hardcoded `Import ${n}` it was.
+const DEFAULT_LABELS = { title: 'Import', revalidating: 'Revalidating rows…', downloadTemplate: 'Download CSV template', importButton: (n) => `Import ${n}` };
+
+/**
+ * Shape of the optional `labels` prop — a NESTED object: root-level keys for this dialog's
+ * own chrome, plus one sub-slice per child component, each matching that child's own
+ * DEFAULT_LABELS. Every level is optional; any omitted key/slice falls back to the child's
+ * hardcoded English DEFAULT_LABELS. The functional app (etendo_schema_forge's ListView)
+ * builds this object from its useUI() dictionary and MUST match this shape exactly.
+ *
+ *   {
+ *     title, revalidating, downloadTemplate, importButton: (n) => string,   // this dialog
+ *     dropzone:     { dropHere, dropHint },                                  // ImportDropzone
+ *     progress:     { title, subtitle },                                     // ImportProgressStep
+ *     mapping:      { notImported, mappedSummary, editMatch, editTitle, save, cancel }, // ImportColumnMapping
+ *     confirm:      { title, willImport: (n) => string, willSkip: (n) => string, cancel, confirm }, // ImportConfirmStep
+ *     fileError:    { title, cancel, retry },                                // ImportFileErrorDialog
+ *     reviewQueue:  { filterAll, filterOk, filterError, skip, skipped, unskip, downloadErrors,
+ *                     status, statusOk, statusError, fieldErrorsTooltip, bulkApplyTitle,
+ *                     bulkApplyDescription, bulkApplyOnlyThis, bulkApplyAll, retry },  // ImportReviewQueue
+ *                     // NB: `retry` feeds ImportReviewQueue's separate `retryLabel` prop, not its DEFAULT_LABELS
+ *     systemError:  { title, subtitle, copy, copied, copyFailed, close, showReport, hideReport,
+ *                     rowData, requestSent, serverResponse },                 // ImportSystemErrorDialog
+ *   }
+ *
+ * Templated strings (mappedSummary's {mapped}/{total}, fieldErrorsTooltip's {fields},
+ * bulkApplyDescription's {count}/{raw}/{value}) keep their {placeholders} — each child fills
+ * them at render time. `translate` is a separate, plain (key, params) => string function
+ * (e.g. useUI's `ui`) injected into the send pipeline so backend errors get localized too.
+ */
 
 const STEP = { DROPZONE: 'dropzone', MAPPING: 'mapping', CONFIRM: 'confirm', SENDING: 'sending', FILE_ERROR: 'fileError', RESULT: 'result' };
 
@@ -40,7 +71,7 @@ function renameRowKeys(row, mapping) {
   return renamed;
 }
 
-export function ImportDialog({ open, onOpenChange, config, token, postBatch, simSearchFn, onImported, labels }) {
+export function ImportDialog({ open, onOpenChange, config, token, postBatch, simSearchFn, onImported, labels, translate }) {
   const text = { ...DEFAULT_LABELS, ...labels };
   const [step, setStep] = useState(STEP.DROPZONE);
   const [fileErrorMessage, setFileErrorMessage] = useState(null);
@@ -98,13 +129,17 @@ export function ImportDialog({ open, onOpenChange, config, token, postBatch, sim
   // which made `simSearch`'s own guard clause short-circuit to "no match" for every row
   // instead of actually querying — the descriptor then threw "country could not be
   // resolved" for every address-bearing row (confirmed via a real browser run).
+  // `translate` is threaded into the descriptor config too — a composite descriptor (e.g.
+  // Contacts) throws its own row-level errors (an unresolved country FK) and needs the app's
+  // translate fn to localize them, exactly like the send pipeline does for backend errors.
   const operationsConfig = useMemo(() => ({
     spec: config.spec,
     entity: config.entity,
     descriptorName: config.descriptor,
     targets: config.fields.map((f) => f.target),
     token,
-  }), [config.spec, config.entity, config.descriptor, config.fields, token]);
+    translate,
+  }), [config.spec, config.entity, config.descriptor, config.fields, token, translate]);
 
   // The real config shape (decisions.json → window.import, verified against
   // artifacts/contacts/decisions.json) is `dedupe: { scope, key: string[] }`, not a flat
@@ -240,6 +275,7 @@ export function ImportDialog({ open, onOpenChange, config, token, postBatch, sim
       ({ results } = await runImport(toSend.map((e) => e.row), {
         buildRowOperations: (row) => buildOperations(row, operationsConfig),
         postBatch,
+        translate,
         concurrency: config.concurrency,
         maxRows: config.maxRows,
         onProgress: (completed, total) => setProgress(Math.round((completed / total) * 100)),
@@ -251,7 +287,7 @@ export function ImportDialog({ open, onOpenChange, config, token, postBatch, sim
     }
     const okCount = results.filter((r) => r.status === 'ok').length;
     // A DUPLICATE result (the row's record already exists server-side, a unique-constraint
-    // rejection — see importEngine.js's isDuplicateKeyError) is not an actionable failure:
+    // rejection — see importEngine.js's classifyImportError) is not an actionable failure:
     // retrying would only repeat the identical rejection, and there's nothing for the user
     // to fix. Reported as a skipped entry (same treatment the pre-send in-file dedupe
     // already uses — greyed out, no retry/skip buttons, per ImportReviewQueue) rather than
@@ -289,12 +325,12 @@ export function ImportDialog({ open, onOpenChange, config, token, postBatch, sim
     onImported({ okCount, failedCount: trueFailures.length });
     if (okCount > 0) toast.success(`${okCount} records imported successfully`);
     if (duplicateResults.length > 0) toast.info(`${duplicateResults.length} row(s) skipped — already exist`);
-  }, [entries, operationsConfig, config.concurrency, config.maxRows, postBatch, onImported]);
+  }, [entries, operationsConfig, config.concurrency, config.maxRows, postBatch, onImported, translate]);
 
   const handleRetryEntryPostSend = useCallback(async (index) => {
     const entry = entries[index];
     const operations = await buildOperations(entry.row, operationsConfig);
-    const result = await sendRow(operations, { postBatch });
+    const result = await sendRow(operations, { postBatch, translate });
     setEntries((prev) => {
       const next = [...prev];
       if (result.status === 'ok') {
@@ -311,7 +347,7 @@ export function ImportDialog({ open, onOpenChange, config, token, postBatch, sim
     if (result.status !== 'ok' && result.status !== SEND_STATUS.DUPLICATE) {
       setSystemError({ message: result.error?.message || 'Unknown error', raw: result.error?.raw, row: entry.row, operations });
     }
-  }, [entries, operationsConfig, postBatch]);
+  }, [entries, operationsConfig, postBatch, translate]);
 
   const handleRetryFile = useCallback(() => {
     setFileErrorMessage(null);
@@ -328,7 +364,7 @@ export function ImportDialog({ open, onOpenChange, config, token, postBatch, sim
 
           {step === STEP.DROPZONE && (
             <div className="flex flex-col gap-2">
-              <ImportDropzone onFileSelected={handleFileSelected} data-testid="ImportDropzone__38a6c3" />
+              <ImportDropzone onFileSelected={handleFileSelected} labels={labels?.dropzone} data-testid="ImportDropzone__38a6c3" />
               <button
                 type="button"
                 className="self-center text-xs text-muted-foreground underline underline-offset-2 hover:text-foreground"
@@ -345,6 +381,7 @@ export function ImportDialog({ open, onOpenChange, config, token, postBatch, sim
               message={fileErrorMessage}
               onCancel={() => onOpenChange(false)}
               onRetry={handleRetryFile}
+              labels={labels?.fileError}
               data-testid="ImportFileErrorDialog__38a6c3" />
           )}
 
@@ -355,6 +392,7 @@ export function ImportDialog({ open, onOpenChange, config, token, postBatch, sim
                 importFields={config.fields}
                 mapping={mapping}
                 onApplyMapping={handleApplyMapping}
+                labels={labels?.mapping}
                 data-testid="ImportColumnMapping__38a6c3" />
               <div className="relative flex min-h-0 flex-1 flex-col">
                 {isRevalidating && (
@@ -376,6 +414,7 @@ export function ImportDialog({ open, onOpenChange, config, token, postBatch, sim
                   onUnskipEntry={handleUnskipEntry}
                   onApplyFkValue={handleApplyFkValue}
                   onDownloadErrors={() => downloadCsv(buildErrorsCsv(entries, headers, mapping), 'import-errors.csv')}
+                  labels={labels?.reviewQueue}
                   simSearchFn={simSearchFn}
                   token={token}
                   data-testid="ImportReviewQueue__38a6c3" />
@@ -387,7 +426,7 @@ export function ImportDialog({ open, onOpenChange, config, token, postBatch, sim
                   disabled={validCount === 0}
                   data-testid="ImportDialog__importButton"
                 >
-                  {`Import ${validCount}`}
+                  {text.importButton(validCount)}
                 </Button>
               </div>
             </div>
@@ -399,10 +438,11 @@ export function ImportDialog({ open, onOpenChange, config, token, postBatch, sim
               skipCount={skipCount}
               onCancel={() => setStep(STEP.MAPPING)}
               onConfirm={handleSend}
+              labels={labels?.confirm}
               data-testid="ImportConfirmStep__38a6c3" />
           )}
 
-          {step === STEP.SENDING && <ImportProgressStep percent={progress} data-testid="ImportProgressStep__38a6c3" />}
+          {step === STEP.SENDING && <ImportProgressStep percent={progress} labels={labels?.progress} data-testid="ImportProgressStep__38a6c3" />}
 
           {step === STEP.RESULT && (
             <div className="flex min-h-0 max-h-[70vh] min-w-0 flex-col gap-4">
@@ -418,7 +458,8 @@ export function ImportDialog({ open, onOpenChange, config, token, postBatch, sim
                   onUnskipEntry={handleUnskipEntry}
                   onApplyFkValue={handleApplyFkValue}
                   onDownloadErrors={() => downloadCsv(buildErrorsCsv(entries, headers, mapping), 'import-errors.csv')}
-                  retryLabel="Retry"
+                  retryLabel={labels?.reviewQueue?.retry ?? 'Retry'}
+                  labels={labels?.reviewQueue}
                   simSearchFn={simSearchFn}
                   token={token}
                   data-testid="ImportReviewQueue__38a6c3" />
@@ -430,7 +471,7 @@ export function ImportDialog({ open, onOpenChange, config, token, postBatch, sim
                   disabled={validCount === 0}
                   data-testid="ImportDialog__importButton"
                 >
-                  {`Import ${validCount}`}
+                  {text.importButton(validCount)}
                 </Button>
               </div>
             </div>
@@ -444,6 +485,7 @@ export function ImportDialog({ open, onOpenChange, config, token, postBatch, sim
         operations={systemError?.operations}
         raw={systemError?.raw}
         onClose={() => setSystemError(null)}
+        labels={labels?.systemError}
         data-testid="ImportSystemErrorDialog__38a6c3" />
     </>
   );
diff --git a/packages/app-shell-core/src/components/import/__tests__/ImportDialog.test.jsx b/packages/app-shell-core/src/components/import/__tests__/ImportDialog.test.jsx
index 8b492d919..3e559c051 100644
--- a/packages/app-shell-core/src/components/import/__tests__/ImportDialog.test.jsx
+++ b/packages/app-shell-core/src/components/import/__tests__/ImportDialog.test.jsx
@@ -136,7 +136,10 @@ describe('ImportDialog', () => {
     await waitFor(() => expect(onImported).toHaveBeenCalledWith({ okCount: 0, failedCount: 1 }));
     // The dialog itself must still be showing the review queue at this point, not
     // already torn down — this is what a caller closing on every onImported call hides.
-    expect(screen.getByTestId('ImportReviewQueue__rowError-0').textContent).toContain('Invalid value for OBTIKTaxIDKey');
+    // ETP-4669: the row now shows a friendly, classified message — the raw backend text
+    // ("Invalid value for OBTIKTaxIDKey", an uncontrolled leak) is no longer rendered here;
+    // it is preserved on error.raw for the system-error dialog's report.
+    expect(screen.getByTestId('ImportReviewQueue__rowError-0').textContent).toMatch(/could not be imported/i);
   });
 
   it('regression: shows the ImportSystemErrorDialog with the last failure\'s message, row data, request sent, and raw trace after a failed send', async () => {
@@ -156,7 +159,10 @@ describe('ImportDialog', () => {
     fireEvent.click(screen.getByTestId('ImportDialog__importButton'));
     fireEvent.click(screen.getByTestId('ImportConfirmStep__confirm'));
     await waitFor(() => screen.getByTestId('ImportSystemErrorDialog__title'));
-    expect(screen.getByTestId('ImportSystemErrorDialog__message').textContent).toBe("Operation 'bp' rejected by server");
+    // ETP-4669: the prominent message is the friendly, classified text — never the raw
+    // wrapper ("Operation 'bp' rejected by server"). The raw trace still carries the real
+    // backend text and is shown (collapsed) under "View full report".
+    expect(screen.getByTestId('ImportSystemErrorDialog__message').textContent).toMatch(/could not be imported/i);
     expect(screen.queryByTestId('ImportSystemErrorDialog__trace')).toBeNull();
     fireEvent.click(screen.getByTestId('ImportSystemErrorDialog__toggleReport'));
     expect(screen.getByTestId('ImportSystemErrorDialog__row').textContent).toContain('Lucia');
diff --git a/packages/app-shell-core/src/lib/import/__tests__/importEngine.test.js b/packages/app-shell-core/src/lib/import/__tests__/importEngine.test.js
index bd27f1d4c..2b907843c 100644
--- a/packages/app-shell-core/src/lib/import/__tests__/importEngine.test.js
+++ b/packages/app-shell-core/src/lib/import/__tests__/importEngine.test.js
@@ -10,11 +10,16 @@ describe('sendRow', () => {
     assert.equal(result.recordId, 'REC-1');
   });
 
-  it('returns FAILED with the server error on a committed:false response', async () => {
+  it('returns FAILED on a committed:false response, surfacing a friendly message with the raw text preserved on error.raw', async () => {
+    // ETP-4669: an unrecognized backend message is no longer shown to the user verbatim —
+    // it is classified to a friendly generic fallback, while the raw text stays on error.raw
+    // for the console/telemetry and the system-error dialog's report.
     const postBatch = async () => ({ committed: false, failedAt: { index: 0 }, error: { message: 'Rejected' } });
     const result = await sendRow([{ id: 'row' }], { postBatch });
     assert.equal(result.status, SEND_STATUS.FAILED);
-    assert.equal(result.error.message, 'Rejected');
+    assert.notEqual(result.error.message, 'Rejected');
+    assert.match(result.error.message, /could not be imported/i);
+    assert.ok(result.error.raw.includes('Rejected'), `expected raw to preserve the backend text, got: ${result.error.raw}`);
   });
 
   it('regression: classifies a unique-constraint rejection as DUPLICATE, not FAILED — nothing for the user to fix or retry', async () => {
@@ -53,13 +58,14 @@ describe('sendRow', () => {
     });
     const result = await sendRow([{ id: 'bp' }], { postBatch });
     assert.equal(result.status, SEND_STATUS.DUPLICATE);
-    assert.equal(
-      result.error.message,
-      'There is already a Business Partner with the same (Client, Organization, Search Key). (Client, Organization, Search Key) must be unique. You must change the values entered.',
-    );
+    // ETP-4669: the user sees a friendly duplicate message, not the raw AD text (which
+    // names technical field groups). The raw text is preserved on error.raw.
+    assert.match(result.error.message, /already exists/i);
+    assert.ok(!result.error.message.includes('Business Partner'), `expected no raw AD text leak, got: ${result.error.message}`);
+    assert.ok(result.error.raw.includes('must be unique'), `expected raw to preserve the backend text, got: ${result.error.raw}`);
   });
 
-  it('regression: a real /batch failure with a non-duplicate nested message surfaces that message and stays FAILED', async () => {
+  it('regression: a real /batch failure with a non-duplicate nested message stays FAILED and preserves the raw text on error.raw', async () => {
     const postBatch = async () => ({
       committed: false,
       failedAt: { index: 0, id: 'bp' },
@@ -71,7 +77,10 @@ describe('sendRow', () => {
     });
     const result = await sendRow([{ id: 'bp' }], { postBatch });
     assert.equal(result.status, SEND_STATUS.FAILED);
-    assert.equal(result.error.message, 'Could not find Sequence for: EM_Etgo_Identifier');
+    // ETP-4669: unrecognized backend text is not shown verbatim — a friendly generic
+    // message is shown, with the real text kept on error.raw for the report.
+    assert.match(result.error.message, /could not be imported/i);
+    assert.ok(result.error.raw.includes('Could not find Sequence for: EM_Etgo_Identifier'), `expected raw to preserve the backend text, got: ${result.error.raw}`);
   });
 
   it('regression: a genuinely different failure message is still classified as FAILED, not DUPLICATE', async () => {
@@ -92,26 +101,27 @@ describe('sendRow', () => {
     assert.equal(result.status, SEND_STATUS.UNKNOWN);
   });
 
-  it('regression: surfaces the real message from a raw exception response ({ message } shape, not the documented { error } wrapper)', async () => {
-    // Confirmed via a live capture: an unhandled server-side exception (a genuine 500,
-    // not a graceful BatchService.java transactional rollback) never goes through the
-    // documented `{ committed: false, error: { message, ... } }` shape at all — it comes
-    // back as Etendo's generic error envelope, `{ message: "..." }`, with no `.error` key
-    // (useBatch's runBatch returns this unmodified whenever the non-ok body happens to
-    // parse as JSON). Reading only `response.error` for that shape silently produced
-    // `error: undefined`, so the actual backend exception text never reached the UI —
-    // the user saw nothing more useful than a generic "Unknown error" bubble.
+  it('regression (ETP-4669): an uncontrolled backend leak ({ message } shape) never reaches the user as-is — friendly message, raw kept on error.raw', async () => {
+    // Confirmed via a live capture: an unhandled server-side exception (a genuine 500, not
+    // a graceful BatchService.java transactional rollback) comes back as Etendo's generic
+    // envelope, `{ message: "..." }`, with no `.error` key. The exception text here is an
+    // unserialized Redis CachedSet reference (the sibling ETP-4668 backend bug) — exactly
+    // the kind of raw, meaningless-to-the-user leak that must NOT be shown in the bubble.
+    // It is classified to a friendly generic message; the raw text stays on error.raw for
+    // the system-error dialog's report and the console.
     const postBatch = async () => ({ message: 'Invalid value for OBTIKTaxIDKey: some.CachedSet@1a2b3c' });
     const result = await sendRow([{ id: 'row' }], { postBatch });
     assert.equal(result.status, SEND_STATUS.FAILED);
-    assert.equal(result.error.message, 'Invalid value for OBTIKTaxIDKey: some.CachedSet@1a2b3c');
+    assert.ok(!result.error.message.includes('CachedSet'), `expected the raw leak to be hidden from the user, got: ${result.error.message}`);
+    assert.match(result.error.message, /could not be imported/i);
+    assert.ok(result.error.raw.includes('CachedSet'), `expected raw to preserve the backend text, got: ${result.error.raw}`);
   });
 
-  it('regression: falls back to a generic message only when the response has neither shape', async () => {
+  it('regression: falls back to a friendly generic message when the response has neither shape', async () => {
     const postBatch = async () => ({});
     const result = await sendRow([{ id: 'row' }], { postBatch });
     assert.equal(result.status, SEND_STATUS.FAILED);
-    assert.equal(result.error.message, 'Unknown error');
+    assert.match(result.error.message, /could not be imported/i);
   });
 
   it('regression: carries error.detail through as a readable raw trace (the underlying NEO error, not just the generic wrapper message)', async () => {
@@ -163,12 +173,15 @@ describe('sendRow', () => {
     });
     const result = await sendRow([{ id: 'bp' }], { postBatch });
     assert.equal(result.status, SEND_STATUS.FAILED);
-    assert.ok(result.error.message.includes('searchKey'), `expected message to include the field name, got: ${result.error.message}`);
-    assert.ok(result.error.message.includes('Value too long'), `expected message to include the validation text, got: ${result.error.message}`);
+    // ETP-4669: a "value too long" validation is classified to a friendly message; the raw
+    // field-level text (which leaks the technical field name searchKey) is kept on error.raw.
+    assert.match(result.error.message, /too long/i);
+    assert.ok(!result.error.message.includes('searchKey'), `expected no technical field-name leak, got: ${result.error.message}`);
     assert.ok(!result.error.message.includes("rejected by server"), `expected the generic wrapper text to be replaced, got: ${result.error.message}`);
+    assert.ok(result.error.raw.includes('Value too long'), `expected raw to preserve the validation text, got: ${result.error.raw}`);
   });
 
-  it('regression: joins multiple field validation messages from error.detail.response.errors into one readable string', async () => {
+  it('regression: joins multiple field validation messages from error.detail.response.errors into the raw trace', async () => {
     const postBatch = async () => ({
       committed: false,
       failedAt: { index: 0, id: 'bp' },
@@ -188,13 +201,15 @@ describe('sendRow', () => {
     });
     const result = await sendRow([{ id: 'bp' }], { postBatch });
     assert.equal(result.status, SEND_STATUS.FAILED);
-    assert.ok(result.error.message.includes('searchKey'), `expected message to include searchKey, got: ${result.error.message}`);
-    assert.ok(result.error.message.includes('Value too long'), `expected message to include the searchKey text, got: ${result.error.message}`);
-    assert.ok(result.error.message.includes('email'), `expected message to include email, got: ${result.error.message}`);
-    assert.ok(result.error.message.includes('Invalid email format'), `expected message to include the email text, got: ${result.error.message}`);
+    // ETP-4669: the user sees one friendly message; the joined field-level detail (both the
+    // searchKey and email messages) is preserved on error.raw for the report.
+    assert.match(result.error.message, /too long|could not be imported/i);
+    assert.ok(!result.error.message.includes('searchKey'), `expected no technical field-name leak, got: ${result.error.message}`);
+    assert.ok(result.error.raw.includes('searchKey') && result.error.raw.includes('Value too long'), `expected raw to include the searchKey detail, got: ${result.error.raw}`);
+    assert.ok(result.error.raw.includes('email') && result.error.raw.includes('Invalid email format'), `expected raw to include the email detail, got: ${result.error.raw}`);
   });
 
-  it('regression: prefers error.detail.error.message over error.detail.response.errors when both happen to be present (documented priority order)', async () => {
+  it('regression: prefers error.detail.error.message over error.detail.response.errors when both are present (classification priority)', async () => {
     const postBatch = async () => ({
       committed: false,
       failedAt: { index: 0, id: 'bp' },
@@ -208,11 +223,11 @@ describe('sendRow', () => {
       },
     });
     const result = await sendRow([{ id: 'bp' }], { postBatch });
+    // The nested duplicate message (detail.error.message) wins over the value-too-long
+    // validation shape, so the outcome is DUPLICATE and the raw duplicate text is preserved.
     assert.equal(result.status, SEND_STATUS.DUPLICATE);
-    assert.equal(
-      result.error.message,
-      'There is already a Business Partner with the same (Client, Organization, Search Key). (Client, Organization, Search Key) must be unique.',
-    );
+    assert.match(result.error.message, /already exists/i);
+    assert.ok(result.error.raw.includes('must be unique'), `expected raw to preserve the duplicate text, got: ${result.error.raw}`);
   });
 });
 
diff --git a/packages/app-shell-core/src/lib/import/importEngine.js b/packages/app-shell-core/src/lib/import/importEngine.js
index 5b05eca4c..2dd1eb6d6 100644
--- a/packages/app-shell-core/src/lib/import/importEngine.js
+++ b/packages/app-shell-core/src/lib/import/importEngine.js
@@ -8,16 +8,85 @@ export class BatchTimeoutError extends Error {
 export const SEND_STATUS = { OK: 'ok', FAILED: 'failed', UNKNOWN: 'unknown', DUPLICATE: 'duplicate' };
 
 /**
- * Etendo's generic AD-level uniqueness-constraint message ("X must be unique") — the same
- * wording for any entity's unique index, not something specific to BusinessPartner
- * (confirmed via a real capture: "There is already a Business Partner with the same
- * (Client, Organization, Search Key). (Client, Organization, Search Key) must be unique.").
- * A row that already exists server-side isn't a failure the user needs to act on or
- * retry — retrying would only repeat the same rejection — so it's classified and reported
- * separately from a genuine FAILED/UNKNOWN outcome.
+ * English fallbacks for each classified error KIND — used verbatim only when the caller
+ * injects no `translate` function. This mirrors the DEFAULT_LABELS fallback the import UI
+ * components already use: a controlled, friendly default, NEVER the raw backend text. The
+ * raw text is always preserved separately on `error.raw` for the console/telemetry and the
+ * system-error dialog's collapsible report — it is just never the user-facing `message`.
+ * Keys match the genericLabels keys the functional app defines, so an injected `translate`
+ * (e.g. useUI's `ui`) resolves the same key to a localized string.
  */
-function isDuplicateKeyError(message) {
-  return typeof message === 'string' && /must be unique/i.test(message);
+const IMPORT_ERROR_FALLBACKS = {
+  importErrorRequiredField: (p) => `The field "${p.field}" is required.`,
+  importErrorRequiredGeneric: () => 'A required field is missing.',
+  importErrorDuplicate: () => 'A record with the same value already exists.',
+  importErrorDuplicateIdentifier: () => 'A record with this identifier already exists.',
+  importErrorValueTooLong: () => 'A value is too long for one of its fields.',
+  importErrorGeneric: () => 'This row could not be imported. Open the details for the technical report or contact support.',
+};
+
+/** snake_case / camelCase DB column → a human-readable "Title Case" label, self-contained. */
+function toReadableFieldLabel(column) {
+  const normalized = String(column || '').trim();
+  if (!normalized) return 'Field';
+  return normalized
+    .replace(/_/g, ' ')
+    .replace(/([a-z])([A-Z])/g, '$1 $2')
+    .toLowerCase()
+    .replace(/\b\w/g, (ch) => ch.toUpperCase());
+}
+
+/**
+ * Maps a raw backend diagnostic string to a stable, translatable error KIND — an i18n key,
+ * its interpolation params, and whether the outcome is a benign duplicate (a row that
+ * already exists server-side: nothing for the user to fix or retry, so it is reported
+ * separately from a genuine FAILED outcome — the same wording matches ANY entity's unique
+ * index, e.g. "There is already a Business Partner with the same (...). (...) must be
+ * unique.").
+ *
+ * `importEngine.js` is a plain app-shell-core lib and cannot import the functional app's
+ * error code (useEntity.normalizeServerError / backendErrors.js), so the KINDS worth
+ * recognizing are reimplemented here, self-contained. Anything unrecognized falls through
+ * to `importErrorGeneric` — a friendly generic, never the raw dump. Regex gaps are bounded
+ * ({1,200}) rather than unbounded to avoid super-linear backtracking (SonarQube S5852).
+ */
+export function classifyImportError(rawMessage) {
+  const msg = typeof rawMessage === 'string' ? rawMessage : '';
+  const requiredMatch = msg.match(/null value in column\s+"([^"]+)"\s+of relation/i);
+  if (requiredMatch) {
+    return { key: 'importErrorRequiredField', params: { field: toReadableFieldLabel(requiredMatch[1]) }, duplicate: false };
+  }
+  if (/violates\s+not-null\s+constraint/i.test(msg)) {
+    return { key: 'importErrorRequiredGeneric', params: {}, duplicate: false };
+  }
+  if (/duplicate key value violates unique constraint/i.test(msg)) {
+    return { key: 'importErrorDuplicate', params: {}, duplicate: true };
+  }
+  if (
+    /ya existe.{1,200}\(.{1,200}\).{1,200}debe ser único/i.test(msg)
+    || /there is already.{1,200}\(.{1,200}\).{1,200}must be unique/i.test(msg)
+    || /must be unique/i.test(msg)
+  ) {
+    return { key: 'importErrorDuplicateIdentifier', params: {}, duplicate: true };
+  }
+  if (/value too long/i.test(msg)) {
+    return { key: 'importErrorValueTooLong', params: {}, duplicate: false };
+  }
+  return { key: 'importErrorGeneric', params: {}, duplicate: false };
+}
+
+/**
+ * Turns a classification into the user-facing message. With an injected `translate` it
+ * returns the localized string (falling back to the English default if the key is missing —
+ * `translate` returning the key unchanged is the "missing" signal, same guard the app's own
+ * translate helpers use). With no `translate`, the English default. Never the raw backend text.
+ */
+function friendlyImportMessage(classification, translate) {
+  const { key, params } = classification;
+  const fallback = IMPORT_ERROR_FALLBACKS[key](params);
+  if (typeof translate !== 'function') return fallback;
+  const translated = translate(key, params);
+  return translated && translated !== key ? translated : fallback;
 }
 
 /**
@@ -46,7 +115,7 @@ function firstValidationMessage(errors) {
  * may have already committed server-side, and blindly treating it as a safe
  * retry target risks a duplicate create.
  */
-export async function sendRow(operations, { postBatch }) {
+export async function sendRow(operations, { postBatch, translate } = {}) {
   let response;
   try {
     response = await postBatch(operations);
@@ -83,22 +152,28 @@ export async function sendRow(operations, { postBatch }) {
   // full trace, one at a time, until the pipeline stabilizes).
   const raw = error.raw ?? (error.detail ? JSON.stringify(error.detail, null, 2) : JSON.stringify(response, null, 2));
   // error.message is BatchService.java's own generic wrapper ("Operation 'bp' rejected by
-  // server") — always the same text regardless of cause, so isDuplicateKeyError's
-  // /must be unique/i check against it can never match. The real diagnostic text (e.g.
-  // Etendo's own "... must be unique." message) lives one level deeper, at
-  // error.detail.error.message, whenever NeoCrudHandler attached the underlying NEO
-  // response as `detail` (verified against a real capture of a duplicate-key /batch
-  // failure). Prefer that nested message everywhere this result's error surfaces —
-  // both for classification and for what the review queue actually shows the user —
-  // falling back to the wrapper text only when there's no nested detail to read. A
-  // validation-error op (NEO status -4) uses a third shape instead — detail.response.errors
-  // — checked second since a plain-failure op never has both.
-  const diagnosticMessage =
+  // server") — always the same text regardless of cause, so classification against it can
+  // never match. The real diagnostic text (e.g. Etendo's own "... must be unique." message)
+  // lives one level deeper, at error.detail.error.message, whenever NeoCrudHandler attached
+  // the underlying NEO response as `detail` (verified against a real capture of a
+  // duplicate-key /batch failure). Read that nested message first, falling back to the
+  // wrapper only when there's no nested detail. A validation-error op (NEO status -4) uses
+  // a third shape instead — detail.response.errors — checked second since a plain-failure
+  // op never has both. This is the RAW text used only to CLASSIFY the outcome; it is never
+  // shown to the user directly.
+  const rawDiagnostic =
     error.detail?.error?.message
     || firstValidationMessage(error.detail?.response?.errors)
     || error.message;
-  const status = isDuplicateKeyError(diagnosticMessage) ? SEND_STATUS.DUPLICATE : SEND_STATUS.FAILED;
-  return { status, error: { ...error, message: diagnosticMessage, raw } };
+  const classification = classifyImportError(rawDiagnostic);
+  const status = classification.duplicate ? SEND_STATUS.DUPLICATE : SEND_STATUS.FAILED;
+  // The user-facing message is the classified, friendly (and, when `translate` is injected,
+  // localized) text — NEVER `rawDiagnostic`, which can be an uncontrolled backend leak
+  // (e.g. an unserialized `com.etendoerp.redis.interfaces.CachedSet@55b0cf12`, ETP-4668).
+  // The raw text stays on `error.raw` for the console/telemetry and the system-error
+  // dialog's collapsible report, so nothing diagnostic is lost — it just isn't the bubble.
+  const message = friendlyImportMessage(classification, translate);
+  return { status, error: { ...error, message, raw } };
 }
 
 /**
@@ -126,7 +201,7 @@ async function runBoundedPool(items, concurrency, worker, onSettle) {
  * `results` — the caller reports `truncatedCount` explicitly rather than
  * silently dropping them.
  */
-export async function runImport(rows, { buildRowOperations, postBatch, concurrency = 4, maxRows = 5000, onProgress }) {
+export async function runImport(rows, { buildRowOperations, postBatch, translate, concurrency = 4, maxRows = 5000, onProgress }) {
   const attempted = rows.slice(0, maxRows);
   const truncatedCount = rows.length - attempted.length;
   const results = new Array(attempted.length);
@@ -155,7 +230,7 @@ export async function runImport(rows, { buildRowOperations, postBatch, concurren
       } catch (error) {
         return { status: SEND_STATUS.FAILED, error, operations: null };
       }
-      const result = await sendRow(operations, { postBatch });
+      const result = await sendRow(operations, { postBatch, translate });
       return { ...result, operations };
     },
     (result, row, index) => {

From 818c98d3ab5211e99eb553e8f598c0526c1ed174 Mon Sep 17 00:00:00 2001
From: sebastianbarrozo <sebastian.barrozo@etendo.software>
Date: Fri, 24 Jul 2026 09:49:09 -0300
Subject: [PATCH 05/10] Feature ETP-4669: Add import label-forwarding + error
 i18n unit tests

---
 .../__tests__/ImportDialog.labels.test.jsx    | 209 ++++++++++++++++++
 .../__tests__/importEngine.i18n.test.js       | 120 ++++++++++
 2 files changed, 329 insertions(+)
 create mode 100644 packages/app-shell-core/src/components/import/__tests__/ImportDialog.labels.test.jsx
 create mode 100644 packages/app-shell-core/src/lib/import/__tests__/importEngine.i18n.test.js

diff --git a/packages/app-shell-core/src/components/import/__tests__/ImportDialog.labels.test.jsx b/packages/app-shell-core/src/components/import/__tests__/ImportDialog.labels.test.jsx
new file mode 100644
index 000000000..8ecda1a28
--- /dev/null
+++ b/packages/app-shell-core/src/components/import/__tests__/ImportDialog.labels.test.jsx
@@ -0,0 +1,209 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { render, screen, fireEvent, waitFor, cleanup } from '@testing-library/react';
+
+// ETP-4669: ImportDialog is the single point that fans the nested `labels` prop out to every
+// child of the import flow. These tests mock each child so we can assert the EXACT sub-slice
+// each one receives (by object identity), not merely that something rendered — a mis-wiring
+// (e.g. forwarding `labels.confirm` where `labels.mapping` belongs) would slip past a
+// render-only assertion but is caught here. The root-level chrome (title, downloadTemplate,
+// importButton) is asserted through the real DOM, since ImportDialog renders it itself.
+
+const captured = vi.hoisted(() => ({}));
+
+vi.mock('../ImportDropzone.jsx', () => ({
+  ImportDropzone: (props) => {
+    captured.dropzone = props;
+    return (
+      <div data-testid="mock-dropzone">
+        <button
+          type="button"
+          data-testid="mock-dropzone-select"
+          onClick={() => props.onFileSelected(new File(['Name,Email\nLucia,lucia@x.com'], 'c.csv', { type: 'text/csv' }))}
+        />
+        <button
+          type="button"
+          data-testid="mock-dropzone-bad"
+          onClick={() => props.onFileSelected(new File([''], 'empty.csv', { type: 'text/csv' }))}
+        />
+      </div>
+    );
+  },
+}));
+
+vi.mock('../ImportColumnMapping.jsx', () => ({
+  ImportColumnMapping: (props) => {
+    captured.mapping = props;
+    return <div data-testid="mock-mapping" />;
+  },
+}));
+
+// ImportDialog imports both ImportReviewQueue and buildErrorsCsv from this module — the mock
+// must preserve both named exports or the import itself breaks.
+vi.mock('../ImportReviewQueue.jsx', () => ({
+  buildErrorsCsv: () => '',
+  ImportReviewQueue: (props) => {
+    captured.reviewQueue = props;
+    return <div data-testid="mock-reviewQueue" />;
+  },
+}));
+
+vi.mock('../ImportConfirmStep.jsx', () => ({
+  ImportConfirmStep: (props) => {
+    captured.confirm = props;
+    return <button type="button" data-testid="mock-confirm" onClick={() => props.onConfirm()} />;
+  },
+}));
+
+vi.mock('../ImportProgressStep.jsx', () => ({
+  ImportProgressStep: (props) => {
+    captured.progress = props;
+    return <div data-testid="mock-progress" />;
+  },
+}));
+
+vi.mock('../ImportFileErrorDialog.jsx', () => ({
+  ImportFileErrorDialog: (props) => {
+    captured.fileError = props;
+    return <div data-testid="mock-fileError" />;
+  },
+}));
+
+vi.mock('../ImportSystemErrorDialog.jsx', () => ({
+  ImportSystemErrorDialog: (props) => {
+    captured.systemError = props;
+    return props.open ? <div data-testid="mock-systemError" /> : null;
+  },
+}));
+
+import { ImportDialog } from '../ImportDialog.jsx';
+
+// The real Radix Dialog stays mounted (only the step children are mocked); jsdom needs the
+// same observer/pointer polyfills the sibling ImportDialog.test.jsx already installs.
+if (!global.ResizeObserver) {
+  global.ResizeObserver = class {
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+  };
+}
+if (!Element.prototype.hasPointerCapture) Element.prototype.hasPointerCapture = () => false;
+if (!Element.prototype.releasePointerCapture) Element.prototype.releasePointerCapture = () => {};
+if (!Element.prototype.scrollIntoView) Element.prototype.scrollIntoView = () => {};
+
+const config = {
+  spec: 'contacts',
+  entity: 'businessPartner',
+  fields: [
+    { target: 'name', label: 'Name', required: true },
+    { target: 'email', label: 'Email', isEmail: true },
+  ],
+  dedupe: { scope: 'file', key: ['email'] },
+};
+
+// Distinct sentinel per slice — every child's sub-slice is a unique object, so an identity
+// (toBe) assertion proves the RIGHT slice reached the RIGHT child, not just any label.
+const labels = {
+  title: 'L_title',
+  revalidating: 'L_revalidating',
+  downloadTemplate: 'L_downloadTemplate',
+  importButton: (n) => `L_import_${n}`,
+  dropzone: { dropHere: 'L_dropHere', dropHint: 'L_dropHint' },
+  progress: { title: 'L_progressTitle', subtitle: 'L_progressSubtitle' },
+  mapping: { notImported: 'L_notImported', mappedSummary: 'L_mappedSummary', editMatch: 'L_editMatch', editTitle: 'L_editTitle', save: 'L_save', cancel: 'L_cancel' },
+  confirm: { title: 'L_confirmTitle', willImport: (n) => `L_willImport_${n}`, willSkip: (n) => `L_willSkip_${n}`, cancel: 'L_cancel', confirm: 'L_confirm' },
+  fileError: { title: 'L_fileErrorTitle', cancel: 'L_cancel', retry: 'L_retry' },
+  reviewQueue: { filterAll: 'L_filterAll', filterError: 'L_filterError', skip: 'L_skip', retry: 'L_rqRetry' },
+  systemError: { title: 'L_sysTitle', subtitle: 'L_sysSubtitle', close: 'L_sysClose' },
+};
+
+function renderDialog(props = {}) {
+  return render(
+    <ImportDialog
+      open
+      config={config}
+      token="t"
+      postBatch={vi.fn()}
+      simSearchFn={vi.fn()}
+      onImported={() => {}}
+      labels={labels}
+      {...props}
+    />,
+  );
+}
+
+async function driveToMapping() {
+  fireEvent.click(screen.getByTestId('mock-dropzone-select'));
+  await waitFor(() => screen.getByTestId('mock-mapping'));
+}
+
+beforeEach(() => {
+  for (const k of Object.keys(captured)) delete captured[k];
+});
+afterEach(() => cleanup());
+
+describe('ImportDialog — label forwarding to every child', () => {
+  it('forwards labels.dropzone to ImportDropzone and renders the root chrome (title, downloadTemplate) from the merged labels', () => {
+    renderDialog();
+    expect(captured.dropzone.labels).toBe(labels.dropzone);
+    expect(screen.getByTestId('DialogTitle__38a6c3').textContent).toBe('L_title');
+    expect(screen.getByTestId('ImportDialog__downloadTemplate').textContent).toBe('L_downloadTemplate');
+  });
+
+  it('always mounts ImportSystemErrorDialog with labels.systemError (closed until a failure occurs)', () => {
+    renderDialog();
+    expect(captured.systemError.labels).toBe(labels.systemError);
+    expect(captured.systemError.open).toBe(false);
+  });
+
+  it('forwards labels.mapping to ImportColumnMapping, labels.reviewQueue to ImportReviewQueue, and interpolates the import button with the valid-row count', async () => {
+    renderDialog();
+    await driveToMapping();
+    expect(captured.mapping.labels).toBe(labels.mapping);
+    expect(captured.reviewQueue.labels).toBe(labels.reviewQueue);
+    // Pre-send queue has no retry affordance — the (n) => string chrome label is what renders
+    // on the real Import button, proving importButton() is called with the count, not a constant.
+    expect(captured.reviewQueue.retryLabel).toBeUndefined();
+    expect(screen.getByTestId('ImportDialog__importButton').textContent).toBe('L_import_1');
+  });
+
+  it('forwards labels.confirm to ImportConfirmStep', async () => {
+    renderDialog();
+    await driveToMapping();
+    fireEvent.click(screen.getByTestId('ImportDialog__importButton'));
+    await waitFor(() => screen.getByTestId('mock-confirm'));
+    expect(captured.confirm.labels).toBe(labels.confirm);
+  });
+
+  it('forwards labels.progress to ImportProgressStep while a send is in flight', async () => {
+    // A postBatch that never resolves pins the dialog on the SENDING step so the progress
+    // child is deterministically observable (not a transient flash between confirm and result).
+    const postBatch = vi.fn(() => new Promise(() => {}));
+    renderDialog({ postBatch });
+    await driveToMapping();
+    fireEvent.click(screen.getByTestId('ImportDialog__importButton'));
+    fireEvent.click(await screen.findByTestId('mock-confirm'));
+    await waitFor(() => expect(captured.progress).toBeTruthy());
+    expect(captured.progress.labels).toBe(labels.progress);
+  });
+
+  it('forwards labels.reviewQueue + retryLabel to the result-step queue and labels.systemError (now open) after a failed send', async () => {
+    // Classified FAILED (unrecognized backend message) → the result step renders the review
+    // queue with a retry affordance AND opens the system-error dialog.
+    const postBatch = vi.fn().mockResolvedValue({ message: 'boom-unrecognized' });
+    renderDialog({ postBatch });
+    await driveToMapping();
+    fireEvent.click(screen.getByTestId('ImportDialog__importButton'));
+    fireEvent.click(await screen.findByTestId('mock-confirm'));
+    await waitFor(() => expect(captured.systemError.open).toBe(true));
+    expect(captured.reviewQueue.labels).toBe(labels.reviewQueue);
+    expect(captured.reviewQueue.retryLabel).toBe(labels.reviewQueue.retry);
+    expect(captured.systemError.labels).toBe(labels.systemError);
+  });
+
+  it('forwards labels.fileError to ImportFileErrorDialog when a file fails to parse', async () => {
+    renderDialog();
+    fireEvent.click(screen.getByTestId('mock-dropzone-bad'));
+    await waitFor(() => screen.getByTestId('mock-fileError'));
+    expect(captured.fileError.labels).toBe(labels.fileError);
+  });
+});
diff --git a/packages/app-shell-core/src/lib/import/__tests__/importEngine.i18n.test.js b/packages/app-shell-core/src/lib/import/__tests__/importEngine.i18n.test.js
new file mode 100644
index 000000000..73fa25a97
--- /dev/null
+++ b/packages/app-shell-core/src/lib/import/__tests__/importEngine.i18n.test.js
@@ -0,0 +1,120 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { classifyImportError, sendRow, SEND_STATUS } from '../importEngine.js';
+
+// ETP-4669: importEngine now classifies raw backend diagnostics into stable, translatable
+// error KINDS and never surfaces the raw text as the user-facing message (it moves to
+// error.raw). The existing importEngine.test.js covers the English-fallback path (no
+// translator); these cover the classifier directly and the translator-injected path — the
+// two behaviors the two-repo wiring depends on but that were previously untested here.
+
+describe('classifyImportError', () => {
+  it('maps a Postgres not-null column violation to a required-field kind with a readable field name', () => {
+    const c = classifyImportError('null value in column "commercial_name" of relation "c_bpartner" violates not-null constraint');
+    assert.equal(c.key, 'importErrorRequiredField');
+    assert.equal(c.params.field, 'Commercial Name');
+    assert.equal(c.duplicate, false);
+  });
+
+  it('maps a bare not-null constraint (no column captured) to the generic required kind', () => {
+    const c = classifyImportError('ERROR: violates not-null constraint');
+    assert.equal(c.key, 'importErrorRequiredGeneric');
+    assert.equal(c.duplicate, false);
+  });
+
+  it('maps a Postgres unique-index violation to the duplicate kind (benign, retry-proof)', () => {
+    const c = classifyImportError('duplicate key value violates unique constraint "c_bpartner_value_uk"');
+    assert.equal(c.key, 'importErrorDuplicate');
+    assert.equal(c.duplicate, true);
+  });
+
+  it('maps Etendo\'s AD-level uniqueness message (English and Spanish) to the duplicate-identifier kind', () => {
+    const en = classifyImportError('There is already a Business Partner with the same (Client, Organization, Search Key). (Client, Organization, Search Key) must be unique.');
+    const es = classifyImportError('Ya existe un Tercero con la misma (Cliente, Organización, Clave de búsqueda). (Cliente, Organización, Clave de búsqueda) debe ser único.');
+    assert.equal(en.key, 'importErrorDuplicateIdentifier');
+    assert.equal(en.duplicate, true);
+    assert.equal(es.key, 'importErrorDuplicateIdentifier');
+    assert.equal(es.duplicate, true);
+  });
+
+  it('maps a value-too-long validation to its own kind', () => {
+    const c = classifyImportError('Value too long. Length 48, maximum allowed 40');
+    assert.equal(c.key, 'importErrorValueTooLong');
+    assert.equal(c.duplicate, false);
+  });
+
+  it('falls through to the generic kind for an uncontrolled backend leak (never a partial match on internal noise)', () => {
+    const c = classifyImportError('Invalid value for OBTIKTaxIDKey: com.etendoerp.redis.interfaces.CachedSet@55b0cf12');
+    assert.equal(c.key, 'importErrorGeneric');
+    assert.equal(c.duplicate, false);
+  });
+
+  it('is total over non-string input — a null/undefined/number diagnostic classifies as generic, never throws', () => {
+    for (const bad of [null, undefined, 42, {}, []]) {
+      const c = classifyImportError(bad);
+      assert.equal(c.key, 'importErrorGeneric');
+      assert.equal(c.duplicate, false);
+    }
+  });
+});
+
+// A translator echoing a small Spanish table; returning the key unchanged is the "missing
+// key" signal the engine's fallback guard checks for.
+const es = {
+  importErrorRequiredField: (p) => `El campo "${p.field}" es obligatorio.`,
+  importErrorDuplicateIdentifier: () => 'Ya existe un registro con este identificador.',
+  importErrorValueTooLong: () => 'Un valor es demasiado largo.',
+  importErrorGeneric: () => 'No se pudo importar esta fila. Abra el detalle para ver el reporte técnico.',
+};
+const translate = (key, params) => (es[key] ? es[key](params ?? {}) : key);
+
+describe('sendRow — translator-injected friendly messages', () => {
+  it('localizes a classified required-field error and interpolates the field name, keeping the raw text on error.raw', async () => {
+    const rawText = 'null value in column "value" of relation "c_bpartner" violates not-null constraint';
+    const postBatch = async () => ({ committed: false, error: { message: rawText } });
+    const result = await sendRow([{ id: 'row' }], { postBatch, translate });
+    assert.equal(result.status, SEND_STATUS.FAILED);
+    assert.equal(result.error.message, 'El campo "Value" es obligatorio.');
+    assert.ok(result.error.raw.includes('null value in column'), `expected raw to keep the backend text, got: ${result.error.raw}`);
+  });
+
+  it('localizes an uncontrolled leak to the generic message — the raw CachedSet text never reaches the user but stays on error.raw', async () => {
+    const postBatch = async () => ({ message: 'Invalid value for OBTIKTaxIDKey: com.etendoerp.redis.interfaces.CachedSet@1a2b3c' });
+    const result = await sendRow([{ id: 'row' }], { postBatch, translate });
+    assert.equal(result.status, SEND_STATUS.FAILED);
+    assert.equal(result.error.message, es.importErrorGeneric());
+    assert.ok(!result.error.message.includes('CachedSet'), `expected no raw leak in the message, got: ${result.error.message}`);
+    assert.ok(result.error.raw.includes('CachedSet'), `expected raw to keep the backend text, got: ${result.error.raw}`);
+  });
+
+  it('localizes a unique-constraint rejection as a DUPLICATE with a friendly identifier message', async () => {
+    const postBatch = async () => ({
+      committed: false,
+      error: { message: "Operation 'bp' rejected by server", detail: { error: { message: 'There is already a Business Partner with the same (Client, Organization, Search Key). (Client, Organization, Search Key) must be unique.' } } },
+    });
+    const result = await sendRow([{ id: 'bp' }], { postBatch, translate });
+    assert.equal(result.status, SEND_STATUS.DUPLICATE);
+    assert.equal(result.error.message, 'Ya existe un registro con este identificador.');
+    assert.ok(!result.error.message.includes('Business Partner'), `expected no raw AD text leak, got: ${result.error.message}`);
+    assert.ok(result.error.raw.includes('must be unique'), `expected raw to keep the backend text, got: ${result.error.raw}`);
+  });
+
+  it('falls back to the English default when the injected translator has no entry for the classified key (returns the key unchanged)', async () => {
+    // A translator that resolves NOTHING (echoes every key) must not leak the bare key as the
+    // user-facing message — the engine detects `translated === key` and uses its English default.
+    const echoKey = (key) => key;
+    const postBatch = async () => ({ message: 'some unrecognized backend failure' });
+    const result = await sendRow([{ id: 'row' }], { postBatch, translate: echoKey });
+    assert.equal(result.status, SEND_STATUS.FAILED);
+    assert.notEqual(result.error.message, 'importErrorGeneric');
+    assert.match(result.error.message, /could not be imported/i);
+  });
+
+  it('with no translator injected, uses the English fallback table and still interpolates params', async () => {
+    const postBatch = async () => ({ committed: false, error: { message: 'null value in column "search_key" of relation "c_bpartner" violates not-null constraint' } });
+    const result = await sendRow([{ id: 'row' }], { postBatch });
+    assert.equal(result.status, SEND_STATUS.FAILED);
+    assert.equal(result.error.message, 'The field "Search Key" is required.');
+    assert.ok(result.error.raw.includes('null value in column'), `expected raw to keep the backend text, got: ${result.error.raw}`);
+  });
+});

From 90adb2745563d02b3869c66a20c6a3780c0f4980 Mon Sep 17 00:00:00 2001
From: sebastianbarrozo <sebastian.barrozo@etendo.software>
Date: Fri, 24 Jul 2026 10:29:04 -0300
Subject: [PATCH 06/10] Feature ETP-4669: Apply data-testid codemod to
 table.jsx (pre-push gate)

---
 packages/app-shell-core/src/components/ui/table.jsx | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/packages/app-shell-core/src/components/ui/table.jsx b/packages/app-shell-core/src/components/ui/table.jsx
index afd765d7d..37d9b08d0 100644
--- a/packages/app-shell-core/src/components/ui/table.jsx
+++ b/packages/app-shell-core/src/components/ui/table.jsx
@@ -14,7 +14,7 @@ Table.displayName = "Table"
 
 const TableHeader = React.forwardRef(({ className, ...props }, ref) => (
   // WARN(a11y): border-border-subtle, not border-border-structural — see TableRow below.
-  <thead ref={ref} className={cn("[&_tr]:border-b [&_tr]:border-border-subtle", className)} {...props} />
+  (<thead ref={ref} className={cn("[&_tr]:border-b [&_tr]:border-border-subtle", className)} {...props} />)
 ))
 TableHeader.displayName = "TableHeader"
 
@@ -28,10 +28,10 @@ TableBody.displayName = "TableBody"
 
 const TableFooter = React.forwardRef(({ className, ...props }, ref) => (
   // WARN(a11y): border-border-subtle, not border-border-structural — see TableRow below.
-  <tfoot
+  (<tfoot
     ref={ref}
     className={cn("border-t border-border-subtle font-medium [&>tr]:last:border-b-0", className)}
-    {...props} />
+    {...props} />)
 ))
 TableFooter.displayName = "TableFooter"
 

From 083ad97f1c089bebb25713f8a1e860891003c8f1 Mon Sep 17 00:00:00 2001
From: sebastianbarrozo <sebastian.barrozo@etendo.software>
Date: Fri, 24 Jul 2026 12:20:24 -0300
Subject: [PATCH 07/10] Feature ETP-4669: Classify duplicate-user error with
 friendly message

---
 packages/app-shell-core/src/lib/import/importEngine.js | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/packages/app-shell-core/src/lib/import/importEngine.js b/packages/app-shell-core/src/lib/import/importEngine.js
index 2dd1eb6d6..e3da13631 100644
--- a/packages/app-shell-core/src/lib/import/importEngine.js
+++ b/packages/app-shell-core/src/lib/import/importEngine.js
@@ -21,6 +21,7 @@ const IMPORT_ERROR_FALLBACKS = {
   importErrorRequiredGeneric: () => 'A required field is missing.',
   importErrorDuplicate: () => 'A record with the same value already exists.',
   importErrorDuplicateIdentifier: () => 'A record with this identifier already exists.',
+  importErrorDuplicateUser: () => 'A user with this name already exists for the contact. Try a different name.',
   importErrorValueTooLong: () => 'A value is too long for one of its fields.',
   importErrorGeneric: () => 'This row could not be imported. Open the details for the technical report or contact support.',
 };
@@ -69,6 +70,12 @@ export function classifyImportError(rawMessage) {
   ) {
     return { key: 'importErrorDuplicateIdentifier', params: {}, duplicate: true };
   }
+  // Etendo auto-creates a portal AD_User for a contact; the derived username can collide
+  // with an existing user. Its own top-level `{error:{message}}` shape carries no "must be
+  // unique" wording, so it needs its own branch rather than falling into the generic bucket.
+  if (/user with the same name already exists/i.test(msg)) {
+    return { key: 'importErrorDuplicateUser', params: {}, duplicate: true };
+  }
   if (/value too long/i.test(msg)) {
     return { key: 'importErrorValueTooLong', params: {}, duplicate: false };
   }

From 712cc40aee6dbd431beb5ec36ccea933ba1e77c9 Mon Sep 17 00:00:00 2001
From: sebastianbarrozo <sebastian.barrozo@etendo.software>
Date: Fri, 24 Jul 2026 12:22:06 -0300
Subject: [PATCH 08/10] Feature ETP-4669: Treat duplicate-user error as
 actionable, not skipped

---
 packages/app-shell-core/src/lib/import/importEngine.js | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/packages/app-shell-core/src/lib/import/importEngine.js b/packages/app-shell-core/src/lib/import/importEngine.js
index e3da13631..407e554d2 100644
--- a/packages/app-shell-core/src/lib/import/importEngine.js
+++ b/packages/app-shell-core/src/lib/import/importEngine.js
@@ -73,8 +73,12 @@ export function classifyImportError(rawMessage) {
   // Etendo auto-creates a portal AD_User for a contact; the derived username can collide
   // with an existing user. Its own top-level `{error:{message}}` shape carries no "must be
   // unique" wording, so it needs its own branch rather than falling into the generic bucket.
+  // `duplicate: false` (unlike the genuine already-exists cases above): the CONTACT is not a
+  // duplicate — only the derived username collides — so the user can fix it (change the
+  // commercial name) and retry. It gets the normal actionable-error treatment (stays in the
+  // queue, counts toward failedCount, retriable inline) rather than being silently skipped.
   if (/user with the same name already exists/i.test(msg)) {
-    return { key: 'importErrorDuplicateUser', params: {}, duplicate: true };
+    return { key: 'importErrorDuplicateUser', params: {}, duplicate: false };
   }
   if (/value too long/i.test(msg)) {
     return { key: 'importErrorValueTooLong', params: {}, duplicate: false };

From 3674d68188bd77e1a205632b90e2b1aa7c79dd01 Mon Sep 17 00:00:00 2001
From: sebastianbarrozo <sebastian.barrozo@etendo.software>
Date: Fri, 24 Jul 2026 12:24:31 -0300
Subject: [PATCH 09/10] Feature ETP-4669: Add duplicate-user classifier
 regression test

---
 .../__tests__/importEngine.i18n.test.js       | 31 +++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/packages/app-shell-core/src/lib/import/__tests__/importEngine.i18n.test.js b/packages/app-shell-core/src/lib/import/__tests__/importEngine.i18n.test.js
index 73fa25a97..809e5002c 100644
--- a/packages/app-shell-core/src/lib/import/__tests__/importEngine.i18n.test.js
+++ b/packages/app-shell-core/src/lib/import/__tests__/importEngine.i18n.test.js
@@ -37,6 +37,15 @@ describe('classifyImportError', () => {
     assert.equal(es.duplicate, true);
   });
 
+  it('maps a duplicate-username collision to its own kind, flagged actionable (duplicate:false) — the contact is not a duplicate, only the derived AD_User name is', () => {
+    // No "must be unique" wording, so it must NOT fall into the earlier duplicate-identifier
+    // branch (which is duplicate:true / benign-skip). Its own branch keeps it actionable.
+    const c = classifyImportError('A user with the same name already exists. Enter a different name for this user');
+    assert.equal(c.key, 'importErrorDuplicateUser');
+    assert.equal(c.duplicate, false);
+    assert.deepEqual(c.params, {});
+  });
+
   it('maps a value-too-long validation to its own kind', () => {
     const c = classifyImportError('Value too long. Length 48, maximum allowed 40');
     assert.equal(c.key, 'importErrorValueTooLong');
@@ -63,6 +72,7 @@ describe('classifyImportError', () => {
 const es = {
   importErrorRequiredField: (p) => `El campo "${p.field}" es obligatorio.`,
   importErrorDuplicateIdentifier: () => 'Ya existe un registro con este identificador.',
+  importErrorDuplicateUser: () => 'Ya existe un usuario con este nombre para el contacto. Use un nombre diferente.',
   importErrorValueTooLong: () => 'Un valor es demasiado largo.',
   importErrorGeneric: () => 'No se pudo importar esta fila. Abra el detalle para ver el reporte técnico.',
 };
@@ -99,6 +109,27 @@ describe('sendRow — translator-injected friendly messages', () => {
     assert.ok(result.error.raw.includes('must be unique'), `expected raw to keep the backend text, got: ${result.error.raw}`);
   });
 
+  it('classifies a duplicate-username collision as an actionable FAILED (not DUPLICATE), with a friendly message and the raw text on error.raw — translator injected and not', async () => {
+    // Etendo's derived-username collision arrives as a top-level error.message, status 500, no
+    // .detail. duplicate:false means SEND_STATUS.FAILED (stays in the queue, counts toward
+    // failedCount) — never silently skipped like a benign already-exists row.
+    const rawText = 'A user with the same name already exists. Enter a different name for this user';
+    const postBatch = async () => ({ committed: false, error: { message: rawText, status: 500 } });
+
+    const withT = await sendRow([{ id: 'bp' }], { postBatch, translate });
+    assert.equal(withT.status, SEND_STATUS.FAILED);
+    assert.equal(withT.status !== SEND_STATUS.DUPLICATE, true);
+    assert.equal(withT.error.message, es.importErrorDuplicateUser());
+    assert.notEqual(withT.error.message, rawText);
+    assert.ok(withT.error.raw.includes('user with the same name already exists'), `expected raw to keep the backend text, got: ${withT.error.raw}`);
+
+    const noT = await sendRow([{ id: 'bp' }], { postBatch });
+    assert.equal(noT.status, SEND_STATUS.FAILED);
+    assert.equal(noT.error.message, 'A user with this name already exists for the contact. Try a different name.');
+    assert.notEqual(noT.error.message, rawText);
+    assert.ok(noT.error.raw.includes('user with the same name already exists'), `expected raw to keep the backend text, got: ${noT.error.raw}`);
+  });
+
   it('falls back to the English default when the injected translator has no entry for the classified key (returns the key unchanged)', async () => {
     // A translator that resolves NOTHING (echoes every key) must not leak the bare key as the
     // user-facing message — the engine detects `translated === key` and uses its English default.

From 5fc52cf5dec699d0b8e12e981d4202ef28f37b3a Mon Sep 17 00:00:00 2001
From: sebastianbarrozo <sebastian.barrozo@etendo.software>
Date: Mon, 27 Jul 2026 10:12:28 -0300
Subject: [PATCH 10/10] Feature ETP-4657: Exclude locale JSON dictionaries from
 duplicated-block detection

---
 cli/src/pr-review.js       | 11 ++++++++-
 cli/test/pr-review.test.js | 47 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 57 insertions(+), 1 deletion(-)

diff --git a/cli/src/pr-review.js b/cli/src/pr-review.js
index 9bf4ce787..78a80ee09 100755
--- a/cli/src/pr-review.js
+++ b/cli/src/pr-review.js
@@ -39,6 +39,14 @@ function isGeneratedDependencyManifest(path) {
   return /(^|\/)(package-lock|npm-shrinkwrap)\.json$/.test(path);
 }
 
+function isLocaleJsonFile(path) {
+  // Locale JSON dictionaries are DATA (parallel key -> translation maps), not
+  // application logic: translated strings legitimately repeat across locale
+  // dictionaries (e.g. es_AR and es_ES sharing the same neutral phrasing) —
+  // DRY/extract-shared-logic rules apply to logic, not to data.
+  return /\/locales\/[^/]+\.json$/.test(path);
+}
+
 function normalizeDuplicateLine(line) {
   const trimmed = line.trim();
   if (!trimmed) return '';
@@ -171,6 +179,7 @@ export function detectDuplicatedBlocks(diffText, { minLines = DUPLICATE_MIN_LINE
     // rules do not apply, same as the artifacts/ skip above.
     if (run.path.startsWith('cli/cache/')) continue;
     if (isGeneratedDependencyManifest(run.path)) continue;
+    if (isLocaleJsonFile(run.path)) continue;
     const normalizedLines = run.lines
       .map((entry) => ({ ...entry, normalized: normalizeDuplicateLine(entry.text) }))
       .filter((entry) => entry.normalized);
@@ -313,7 +322,7 @@ function isExemptFromSizeGate(path) {
     return true;
   }
   // Locale JSON files grow predictably as the app is translated — skip them.
-  if (/\/locales\/[^/]+\.json$/.test(path)) {
+  if (isLocaleJsonFile(path)) {
     return true;
   }
   // Generated contract snapshots are intentionally verbose and are checked
diff --git a/cli/test/pr-review.test.js b/cli/test/pr-review.test.js
index f39be5bf8..85f7ccbec 100644
--- a/cli/test/pr-review.test.js
+++ b/cli/test/pr-review.test.js
@@ -140,6 +140,53 @@ describe('detectDuplicatedBlocks', () => {
       ['tools/app-shell/src/foo.js', 'tools/app-shell/src/bar.js'],
     );
   });
+
+  it('ignores duplicated blocks in locale JSON dictionaries', () => {
+    const block = [
+      '+  "csvImport": "Importar",',
+      '+  "csvImportEditCorrespondence": "Editar correspondencia",',
+      '+  "csvImportReviewQueue": "Cola de revisión",',
+      '+  "csvImportApplyToAll": "Aplicar a todos",',
+      '+  "csvImportRevalidate": "Revalidar",',
+      '+  "csvImportDiscardRow": "Descartar fila"',
+    ].join('\n');
+
+    const diff = [
+      makeDiff('tools/app-shell/src/locales/es_AR.json', block),
+      makeDiff('tools/app-shell/src/locales/es_ES.json', block),
+    ].join('\n');
+
+    assert.deepEqual(detectDuplicatedBlocks(diff), []);
+  });
+
+  it('still flags the same duplicated block when it lands in real source (locale skip is path-scoped, not a blanket disable)', () => {
+    const block = [
+      '+  "csvImport": "Importar",',
+      '+  "csvImportEditCorrespondence": "Editar correspondencia",',
+      '+  "csvImportReviewQueue": "Cola de revisión",',
+      '+  "csvImportApplyToAll": "Aplicar a todos",',
+      '+  "csvImportRevalidate": "Revalidar",',
+      '+  "csvImportDiscardRow": "Descartar fila"',
+    ].join('\n');
+
+    // The locale JSON copy is silently dropped; the two real source copies must still
+    // collide. This proves the skip only removes locales/ runs from the comparison,
+    // rather than disabling duplication detection for the whole diff.
+    const diff = [
+      makeDiff('tools/app-shell/src/locales/es_AR.json', block),
+      makeDiff('tools/app-shell/src/foo.js', block),
+      makeDiff('tools/app-shell/src/bar.js', block),
+    ].join('\n');
+
+    const findings = detectDuplicatedBlocks(diff);
+    assert.equal(findings.length, 1);
+    assert.equal(findings[0].code, 'DUPLICATED_BLOCK');
+    assert.equal(findings[0].severity, 'blocker');
+    assert.deepEqual(
+      findings[0].locations.map((location) => location.path),
+      ['tools/app-shell/src/foo.js', 'tools/app-shell/src/bar.js'],
+    );
+  });
 });
 
 describe('analyzeChangedFiles', () => {