`engine.update` still leaks the raw driver unique-violation error — the same defect one verb over from the insert door, with the whole UPDATE statement as its message

[os-musk]

Found while implementing #14095, whose scope was explicitly the INSERT door. Filed rather than widened into that PR.

Measured

Real ObjectQL engine on a real driver-sqlite-wasm store, an object carrying a declared unique index on email. Two rows exist; the second is driven onto the first's value, so the UPDATE violates the index:

{
  "threw": true,
  "name": "Error",
  "code": undefined,
  "status": undefined,
  "hasCause": false,
  "message": "update `duly_note` set `id` = 'JrzMrU3fJnc5__tV', `email` = 'a@b.example', `updated_at` = '2026-09-02T03:54:04.936Z' where `id` = 'JrzMrU3fJnc5__tV' -"
}

No code, no status, no cause — and the message is the compiled UPDATE statement with its bound values, exactly the shape #14095 measured on the insert side.

Why it matters, and why it is not merely cosmetic

The platform now has ONE contract for this condition on insert and none on update, which is worse than having neither: an application that correctly branches on code === 'DUPLICATE_RECORD' for its create path silently falls through to the generic error branch on its edit path, on every driver. "Renaming a record onto a name someone else already took" is the ordinary form-submission case, and it is the one that stays dialect-coupled.

An application cannot close it locally for the same three reasons the insert card enumerated: branching on SQLITE_CONSTRAINT_UNIQUE couples it to one dialect, the message is a compiled statement, and isUniqueViolationError lives in @objectstack/types, which an application cannot resolve.

The shape of the work

The insert side landed as envelopeUniqueViolation(error, object) from packages/objectql/src/duplicate-record-error.ts, applied at each point a driver error leaves the insert door. The update door needs the same treatment at its own driver-error exits, with the same negative contract (only a recognised unique violation is enveloped; a NOT NULL, a deadlock, a missing table and an unreachable store leave untouched) and the same operator-log rule (the log takes cause, so the driver's diagnosis stays in the line).

Two things the insert card settled that this one has to decide for itself:

• update can refuse a MULTI-row write. Which row conflicted is a question the insert envelope never had to answer, and the driver's error may not answer it either. The envelope's field half is unaffected (uniqueViolationColumn reads the same channels), but a caller may reasonably want to know it was one of N.
• upsert is the same door's neighbour and is deliberately excluded here: on some dialects an upsert converts a conflict into a merge, so "a unique violation escaped" means something different there. It deserves its own measurement before any envelope is put on it.

Unassigned and untriaged.

---

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 reference pattern this card is asked to mirror (envelopeUniqueViolation) is on main now, so the line was inert and misrepresented the card as gated. This card is already pm:dispatched, so nothing else changes.

Generated by Claude Code

[huangyiirene]

Triage: bug · priority:p1 · pm:blocked on #14095 · domain:engine (packages/objectql) · needs:contract-review · type Bug. Blocked-by: #14095 backfilled into the body — the fix reuses envelopeUniqueViolation from packages/objectql/src/duplicate-record-error.ts, which is #14095's artifact and does not exist on main yet (git grep DUPLICATE_RECORD -- packages/objectql/src → 0 at 5c9e40a). pm:blocking derived onto #14095.

A sharper statement of the severity than the card gives itself, checked at the REST boundary. The compiled UPDATE statement does not reach the client — packages/rest/src/error-response.ts:955 onward sanitises unclassified faults, and an error with no code and no status lands as 500 INTERNAL_ERROR with INTERNAL_ERROR_MESSAGE. So there is no value leak to callers, and the bound email in that message stays in operator logs.

⇒ What the caller actually gets is the real defect, and it is worse than "an unhelpful message": the same user action answers 409 DUPLICATE_RECORD on create and 500 INTERNAL_ERROR on edit. A 500 tells a client the server fell over, tells a form to show a generic failure, and pages whoever watches 5xx rates — for what is a conflict the user can fix by typing a different value. That asymmetry, not the wording, is why this is p1 rather than a DX nit, and it is the sentence to put in the changeset.

Both open questions have answers that do not need escalating, and one that does:

• Multi-row update. Answer the question the envelope can actually answer and no more. field comes from uniqueViolationColumn and is unaffected; ⛔ do not invent a "one of N" count the driver error does not carry — a fabricated row attribution is worse than an absent one. If the driver names nothing, the envelope names nothing, exactly as the composite-index case already does on insert.
• upsert stays out. ⛔ Not in this card, not "while we're here". The card is right that a conflict a dialect converts into a merge means something different, and that needs its own measurement first. If the implementer finds the update door and the upsert door share a code path, that is a finding to file, not a licence to widen.
• The wire code. Same fork as the sibling 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 #14389 and the same fence: this card puts a producer-side envelope on update, which is restoration. ⛔ It does not decide what code the REST layer speaks — that is 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 #14389's, and switching the wire from UNIQUE_VIOLATION to DUPLICATE_RECORD is a published-contract change on the human floor. Land the envelope; leave the wire question alone.

Serialisation. #14389 (REST arm) and this card (engine door) are blocked on the same upstream and touch different packages, so they can land in either order — but ⛔ they are not one PR. #14389's premise is that the envelope reaches classifyDataError; this card's is that update produces one. Folding them hides which half a regression came from.

Keep the negative contract verbatim. The insert side's discipline — only a recognised unique violation is enveloped; NOT NULL, deadlock, missing table and unreachable store pass through untouched; the log takes cause so the driver's diagnosis survives — is the part that makes this safe to land. A pin per non-enveloped class, not just the positive case.

Size/model suggestion: M at CONTRACT_REVIEW_TIER.

---

Generated by Claude Code