`mapDataError` has no `DUPLICATE_RECORD` arm: the engine's insert conflict envelope reaches the wire through the generic passthrough, dropping the `field` key and the user-facing conflict sentence

[os-musk]

Found while implementing #14095 (the ObjectQL half of the 2026-09-01 unique-violation ruling). The engine change is correct and lands on its own; this is the REST-side half of the same condition, in domain:cli territory, filed rather than ridden on that PR.

What changes, and where

Since #14095 engine.insert answers a driver unique violation with an ADR-0112 envelope: code: 'DUPLICATE_RECORD', status: 409, the driver error whole on cause, and field when uniqueViolationColumn determinably named the conflicting column.

classifyDataError (packages/rest/src/error-response.ts) reaches the declared-status passthrough arm first, because the envelope declares a status. That arm returns { status, body: { error, ...thrownCodeFields(error, status), object } } — it ships no structured fields of its own. The dedicated isUniqueViolationError arm further down, which builds 409 UNIQUE_VIOLATION with a field key, is never reached for an insert conflict any more.

Measured, end to end

Real engine, real drivers, the real mapDataError. AFTER is the envelope; BEFORE is the same conflict's raw driver error handed to the same boundary:

driver	index	status	code	field on the body
driver-sqlite-wasm	single column	409 → 409	UNIQUE_VIOLATION → DUPLICATE_RECORD	email → absent
driver-sqlite-wasm	composite	409 → 409	UNIQUE_VIOLATION → DUPLICATE_RECORD	absent → absent (composite names none, by contract)
driver-memory	single column	409 → 409	UNIQUE_VIOLATION → DUPLICATE_RECORD	absent → absent
driver-memory	composite	409 → 409	UNIQUE_VIOLATION → DUPLICATE_RECORD	absent → absent

So: the status is unaffected — the passthrough honours the declared 409 on every driver, which is the good half. Two things do move:

1. The field key is gone on the dialects that name a column. That key is what an import UI or a Console form highlights ("A record with this email already exists"), and it is the whole point of import-runner's sanitizeRowError keeps its own three-dialect unique regexes — deferred from #6250 to avoid a merge race with #4633 #6544 / REST: the UNIQUE_VIOLATION 409 message is hard-coded English and carries no field — and it is less informative than the bulk path's own message for the same constraint #7821.
2. The sentence changes from A record with this email already exists to the engine's own Duplicate record refused on 'duly_note': a unique constraint on 'email' already holds this value. No record was written. Accurate, but it is the platform's sentence, not the one the 409 arm curated for an end user.

For driver-memory the change is an improvement in one respect: that driver's own refusal already declared status: 409, so it ALREADY took the passthrough, and its raw message — which echoes the offending values as JSON (a record with the values {"email":"a@b.example"} already exists) — was reaching the client. The envelope replaces it with a sentence carrying no values.

The shape of the fix

A dedicated DUPLICATE_RECORD arm in classifyDataError, placed with the other structured 409s (DELETE_RESTRICTED, CONCURRENT_UPDATE) ahead of the declared-status passthrough — that placement already exists in the file for exactly this reason ("Surfaced FIRST so the structured fields survive the generic catch-alls"). The envelope carries everything such an arm needs: object, field, developerMessage, and cause.

Open questions for whoever takes it, both wire-contract decisions rather than mechanics:

• Which code should the wire speak — DUPLICATE_RECORD (what the producer now declares) or UNIQUE_VIOLATION (what clients see today)? Both are registered. The ADR-0112 rule is that the producer names the condition, which argues for the former; back-compatibility argues for the latter, and there is a third option where the arm keeps UNIQUE_VIOLATION on the wire and puts the producer's spelling in declaredCode.
• Which sentence — the engine's, or the arm's curated end-user wording plus developerMessage beside it (the DELETE_RESTRICTED split).

Not a regression in the importer

Measured separately: the import row report READS err.message and err.code (toFailedResult → sanitizeRowError). Its code improves from a dialect token (SQLITE_CONSTRAINT_UNIQUE, 11000) to DUPLICATE_RECORD, and the message is the engine's sentence, which the SQL backstop passes through unchanged (it names no statement). No fix owed there.

---

Triage housekeeping (R+98): the Blocked-by: #14095 line has been removed from this body. #14095 closed as completed on 2026-09-02T06:52Z via PR #14405 — the envelope this card reacts to is on main now, so the line was inert and misrepresented the card as gated. This card is pm:dispatched with PR #14544 open against it, which is the live state; nothing else changes.

Generated by Claude Code

[huangyiirene]

Triage: bug · priority:p1 · pm:blocked on #14095 · domain:cli (packages/rest) · needs:contract-review · type Bug. The Blocked-by: #14095 line was already in the body at line start — correct channel, nothing to backfill. pm:blocking derived onto #14095.

Verified on origin/main @ 5c9e40a: #14095 has not landed (git grep DUPLICATE_RECORD -- packages/objectql/src → 0), so today's wire is unchanged and this is a regression-in-waiting rather than a live one. The file convention the card leans on is real and already there: the structured DELETE_RESTRICTED arm sits at error-response.ts:660, the isUniqueViolationError arm at :1190, and :841 carries the comment naming exactly this ordering rule. So the fix has a shape the file already endorses.

Why p1 for a card that changes nothing today. The field key is not decoration — #6544 / #7821 exist to put it on the wire, and an import UI or a Console form is what reads it to highlight the offending input. The day #14095 lands, that key silently disappears for every dialect that names a column, and nothing fails: status stays 409, the body is still well-formed, and the only symptom is a form that stops highlighting a field. That is the shape that survives a release. It should land in the same window as #14095, not a fortnight later.

The one fork, and it is not the implementer's to take

The card asks which code the wire should speak. ⛔ Default to the answer that changes nothing for clients: keep UNIQUE_VIOLATION on the wire and carry the producer's spelling alongside (the card's third option, declaredCode). Restoring field while preserving the wire code is a restoration — declared = enforced — and that is the bug lane, dispatchable now.

Switching the wire to DUPLICATE_RECORD is a published-contract change: every client branching on code today sees UNIQUE_VIOLATION, and ADR-0112's "the producer names the condition" is an argument about internals, not a licence to rename a wire code under existing consumers. That is the human floor. ⛔ If whoever implements this concludes the wire code should change, they stop and file a needs-user-decision card with the four facets — they do not decide it inside the arm, and they do not "compromise" by emitting both.

The sentence question follows the same rule and has an easier answer: take the DELETE_RESTRICTED split the file already uses — curated end-user sentence on error, the engine's diagnostic on developerMessage. That keeps the user-facing wording stable and keeps the platform's precise sentence available, with no contract question to settle.

One improvement the card found and should not lose in the fix. For driver-memory the envelope is strictly better than today: that driver's raw refusal already declared status: 409, so it already took the passthrough, and its message echoes the offending values as JSON ({"email":"a@b.example"}) to the client. Whatever arm lands must not reintroduce that — the curated sentence carries no values, and that property is worth a pin of its own.

Scope fence. ⛔ One arm, in classifyDataError, ahead of the declared-status passthrough. Do not refactor the passthrough, do not touch isUniqueViolationError, and do not extend to update — that door is #14390, blocked on the same upstream and landing in a different package.

No fix owed in the importer, and the card measured why (it reads err.message / err.code, both of which improve). ⛔ Do not "fix" it.

Size/model suggestion: S at CONTRACT_REVIEW_TIER — small diff, but it is a wire-contract surface and the fork above must be respected rather than resolved.

---

Generated by Claude Code