fix(rest): answer the engine's DUPLICATE_RECORD insert-conflict envelope with the structured 409 UNIQUE_VIOLATION body

.changeset/rest-duplicate-record-arm-field-restored.md

@@ -0,0 +1,16 @@
+---
+'@objectstack/rest': patch
+---
+
+Restore the `field` key and the curated conflict sentence on the 409 body for an insert refused by a unique constraint
+
+Since the ObjectQL engine began answering a driver's unique violation with its own `DUPLICATE_RECORD` envelope (`status: 409`, `object`, `field`, the driver error on `cause`), `POST /api/v1/data/:object` let that envelope leave `classifyDataError` through the generic declared-status passthrough: still 409, but with `code: 'DUPLICATE_RECORD'`, no `field`, and the engine's own sentence in `error`. The `isUniqueViolationError` arm that names the conflicting column (`field: 'email'`, "A record with this email already exists") was no longer reached for an insert conflict. Measured with the real engine and real drivers: on `driver-sqlite-wasm` the `field` key disappeared from every conflict on a single-column index; on `driver-memory` the sentence changed.
+
+A dedicated arm for the engine's envelope now sits with the other structured 409s (`DELETE_RESTRICTED`, `CONCURRENT_UPDATE`), ahead of the passthrough:
+
+- `code` stays `UNIQUE_VIOLATION` — the code every client branching on this conflict already reads.
+- `field` is restored whenever the dialect determinably named the column (SQLite, Postgres); composite keys and index-naming dialects (MySQL) carry no `field` key, exactly as before.
+- `error` is the curated end-user sentence again; the engine's own sentence rides on `developerMessage`, the same split the `DELETE_RESTRICTED` body uses.
+- The body still quotes nothing the driver said — no offending value, no statement, no index name — including on `driver-memory`, whose raw refusal used to echo the offending values as JSON through the passthrough.
+
+`patch`: a restoration of the shipped body's keys and wording; the wire `code` and the status are unchanged. The arm fires for the engine's envelope only; a plugin or sandbox body that throws the registered `DUPLICATE_RECORD` itself keeps the answer it gets today.

packages/rest/src/error-response.ts

@@ -698,6 +698,84 @@ function classifyDataError(error: any, object?: string): { status: number; body:
             },
         };
     }
+    // [#14389] The engine's insert-conflict envelope → 409 `UNIQUE_VIOLATION`,
+    // with the structured `field` restored.
+    //
+    // Since #14095 `engine.insert` answers a driver's unique violation with the
+    // `DuplicateRecordError` envelope — `code: 'DUPLICATE_RECORD'`, `status:
+    // 409`, `object`, `field` when the dialect determinably named a column,
+    // the driver error whole on `cause`. It DECLARES a status, so it reached
+    // the declared-status passthrough below first and left through it: status
+    // right, `field` gone, and the platform's own sentence in `error`, while
+    // the `isUniqueViolationError` arm further down — holding the curated
+    // end-user wording and the `field` key since #7821 — was never reached
+    // for an insert conflict any more. Surfaced FIRST, beside the two
+    // structured 409s above, for the same reason they are: the structured
+    // field must survive the generic catch-alls.
+    //
+    // **The wire `code` stays `UNIQUE_VIOLATION`** (triage ruling on the card,
+    // 2026-09-02: the answer that changes nothing for clients — every consumer
+    // branching on this conflict today reads `UNIQUE_VIOLATION`, and renaming
+    // a wire code under existing consumers is a published-contract change,
+    // not a door's call). **No `declaredCode` beside it.** `DUPLICATE_RECORD`
+    // is a `StandardErrorCode` member, and `ApiErrorSchema.declaredCode`
+    // (`packages/spec/src/api/contract.zod.ts`, with its docblock) together
+    // with ADR-0112's "presence means demotion" amendment define the field as
+    // the demoted spelling of an UNREGISTERED code — absent when the
+    // producer's code IS a vocabulary member. So the field stays ABSENT here
+    // (contract review on the card, 2026-09-02), and the engine's spelling
+    // stays in-process exactly as every dialect code (`SQLITE_CONSTRAINT_UNIQUE`,
+    // `23505`, `ER_DUP_ENTRY`) always has at the `isUniqueViolationError` arm
+    // below. ADR-0112's 2026-08-29 scope correction declares the hand-written
+    // `declaredCode` emission population to be exactly one site; this arm is
+    // not a second. Pinned in `rest-duplicate-record-arm.test.ts`: §0 (both
+    // codes parse as `ErrorCode` — the reason) and §1 (`not.toHaveProperty`).
+    //
+    // **Two sentences — the `DELETE_RESTRICTED` split above.** `error` is the
+    // curated end-user sentence the #6250/#7821 arm has always produced: fixed
+    // text plus, at most, the bare column identifier the ENGINE resolved
+    // through `uniqueViolationColumn` (`field` is read off the envelope, not
+    // re-derived — the envelope is the contract). `developerMessage` is the
+    // engine's own sentence (`message`): it names the object and the column
+    // and carries no value. The envelope's own `developerMessage` is
+    // deliberately NOT relayed — it addresses the in-process caller of
+    // `engine.insert` ("attached as `cause`", "branch on `code ===
+    // 'DUPLICATE_RECORD'`"), and neither holds on this wire.
+    //
+    // **The body echoes nothing the driver said.** `cause` never reaches the
+    // wire and the sentence is fixed text. This matters most for
+    // `driver-memory`, whose raw refusal declares `status: 409` itself and so
+    // ALREADY took the passthrough before #14095 — with a message quoting the
+    // offending values as JSON. The envelope removed that; this arm keeps it
+    // removed.
+    //
+    // ⚠️ Gated on the ENVELOPE — name AND code — not on the code alone as the
+    // two siblings above are, and the difference is load-bearing: they relay
+    // `error.message`, this arm REPLACES it. A hook that deliberately throws
+    // the registered `DUPLICATE_RECORD` from a sandbox body is a different
+    // producer speaking a member of the vocabulary; it keeps the answer the
+    // sandbox unwrap door gives it today (its own sentence, its own code —
+    // `rest-thrown-code-vocabulary.test.ts` §2) rather than having its
+    // sentence swapped for this one and the QuickJS debug wrapper shipped as
+    // `developerMessage`.
+    if (error?.code === 'DUPLICATE_RECORD' && error?.name === 'DuplicateRecordError') {
+        const field = typeof error?.field === 'string' && error.field.length > 0 ? error.field : undefined;
+        const refused = typeof error?.object === 'string' && error.object.length > 0 ? error.object : object;
+        return {
+            status: 409,
+            body: {
+                error: field
+                    ? `A record with this ${field} already exists`
+                    : 'A record with this value already exists',
+                code: 'UNIQUE_VIOLATION',
+                ...(typeof error?.message === 'string' && error.message.length > 0
+                    ? { developerMessage: error.message }
+                    : {}),
+                ...(field ? { field } : {}),
+                ...(refused ? { object: refused } : {}),
+            },
+        };
+    }
     // A declared datasource that is refused by the host policy, or failed to
     // connect under OS_ALLOW_DRIVER_CONNECT_FAILURE → 503 (framework#3828).
     // Handled before the catch-alls because nothing about the REQUEST is wrong: