rest: `classifyDataError`'s structured-code arms ship the QuickJS debug wrapper as `error` for a sandboxed producer — the mirror of #11588, on the door #11588 did not touch

[os-trump]

Found while implementing #14541 (ordering between resolveErrorResponse's declared-status passthrough and the bespoke structured arms). That card's fix is fenced to the ORDERING, and closing this one means deciding which sentence the arms read — a separate contract question — so it is filed rather than ridden on its PR.

Measured

packages/rest/src/error-response.ts at d2afe5b91d (the #14541 branch; the same measurement holds on origin/main c616c2cc20, where the arms are inline in classifyDataError rather than lifted). One SandboxError-shaped error — message carrying the QuickJS debug wrapper, innerMessage carrying the business sentence, exactly what runtime/src/sandbox/quickjs-runner.ts produces — handed to both REST exits:

error = { message: "hook 'guard' threw: Error: Opportunity is closed.",
 innerMessage: 'Opportunity is closed.',
 code: 'DELETE_RESTRICTED', status: 409,
 object: 'account', dependentObject: 'contact' }

sendThrownError / handleRouteError (the bulk / metadata / UI door)
 409 {"error":"Opportunity is closed.","code":"DELETE_RESTRICTED"}

mapDataError (the single-record /data door)
 409 {"error":"hook 'guard' threw: Error: Opportunity is closed.","code":"DELETE_RESTRICTED",
 "dependentObject":"contact","object":"account"}

The bulk door is correct — that is #11588's sandboxBusinessMessage read on the declared-status passthrough. The single-record door ships the wrapper.

Mechanism

classifyDataError's structured-code arms are surfaced ahead of the sandbox unwrap door, deliberately, "so the structured fields survive the generic catch-alls" — and every one of them builds its sentence from error?.message. For a sandboxed producer error.message IS the debug wrapper, and the unwrap door that would have read innerMessage sits below them and is never reached.

#11588 repaired the same class one door over: it named sandboxBusinessMessage and taught the declared-status passthrough in resolveErrorResponse to read it, because that arm "shipped the QuickJS DEBUG WRAPPER to the end user … One hook, one refusal, two different sentences depending on which route the caller happened to use." The arms in classifyDataError were not in that card's scope. So the wrapper still reaches a client — now on the by-id door rather than the bulk one, i.e. the direction reversed rather than closed.

#14389 already recognised the shape from the other side and worked around it locally: its DUPLICATE_RECORD arm is gated on name === 'DuplicateRecordError' rather than on the code alone, precisely so "a hook that deliberately throws the registered DUPLICATE_RECORD from a sandbox body … keeps the answer the sandbox unwrap door gives it today … rather than having its sentence swapped for this one and the QuickJS debug wrapper shipped as developerMessage." That reasoning applies to every sibling arm; only that one arm carries the guard.

Which arms

Every arm whose gate is a bare code (or a name a sandbox error can carry) and whose body reads error?.message:

DELETE_RESTRICTED · CONCURRENT_UPDATE · ERR_DATASOURCE_UNAVAILABLE · VALIDATION_FAILED · FEEDS_DISABLED / FILES_DISABLED · ATTACHMENT_PARENT_ACCESS / ATTACHMENT_DELETE_DENIED · RECORD_NOT_ACCESSIBLE · PERMISSION_DENIED.

DUPLICATE_RECORD is exempt (the name gate above). OBJECT_NOT_FOUND and INVALID_FIELD are not affected on main — they sit BELOW the unwrap door, so a sandboxed producer reaches the unwrap door first; on the #14541 branch they carry an explicit !isSandboxOrigin clause that preserves exactly that.

VALIDATION_FAILED is the most plausible producer of the three: a metadata-app hook writing throw Object.assign(new Error('Amount must be positive'), { code: 'VALIDATION_FAILED', fields: […] }) is the documented way for an app author to refuse a write with per-field detail, and on the by-id /data door it currently answers 400 {"error":"hook 'guard' threw: Error: Amount must be positive", …}.

What is NOT claimed

• The STATUS is right on both doors, and the structured fields are right on the single-record door. Only the human sentence is wrong there.
• Routes exiting through handleRouteError answer the engine's DUPLICATE_RECORD envelope from resolveErrorResponse's .status passthrough — field and object dropped, mapDataError's structured 409 arms never consulted #14541's fix does not move this in either direction: its consult declines a sandbox-origin error precisely so the bulk door keeps the sentence it has today, and it changes nothing inside mapDataError.
• I did not measure an in-repo producer that throws one of these codes from a sandbox body; the producer this addresses is an app-authored hook, which is the same population rest: the sandbox debug wrapper hook '<name>' threw: Error: … reaches the client on every write route that exits above mapDataError's unwrap (batch, createMany, updateMany, deleteMany, clone, analytics) #11588's own repair was written for.

Shape of a fix (for triage, not decided here)

The arms need the same two-read rule the unwrap door and the passthrough already share — sandboxBusinessMessage(error) ?? error.message — rather than a third local opinion. The contract question triage would need to settle is what a sandboxed CRASH (isScriptFaultMessage, #7543) should get from an arm gated on a declared code: today the arms answer it with the TypeError prose, where the unwrap door's terminal is the sanitised 500. That is a fault-classification decision, not a message-source one, which is why it is not folded into #14541.

[huangyiirene]

Triage — graded p2, bug, pm:queue, routed domain:cli (packages/rest). Applied and read back first.

Why pm:queue and not a decision card

You separate two questions cleanly, and only one of them is open:

• Message source — settled. sandboxBusinessMessage(error) ?? error.message is the rule the unwrap door and the declared-status passthrough already share; rest: the sandbox debug wrapper hook '<name>' threw: Error: … reaches the client on every write route that exits above mapDataError's unwrap (batch, createMany, updateMany, deleteMany, clone, analytics) #11588 established it for exactly this defect one door over. Applying an established rule to sibling arms is repair, not adjudication. ⭐ And 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 already reached the same conclusion locally — its DUPLICATE_RECORD arm is gated on name === 'DuplicateRecordError' specifically so a sandbox-thrown registered code keeps the unwrap door's sentence. Its reasoning applies to every sibling; only that one arm carries the guard.
• Crash classification — genuinely open, and ⛔ not this card's to settle.

Scope, in the two-branch form

Do: give the code-gated arms the two-read rule, so the by-id /data door stops shipping the QuickJS wrapper. The arms you list — DELETE_RESTRICTED, CONCURRENT_UPDATE, ERR_DATASOURCE_UNAVAILABLE, VALIDATION_FAILED, FEEDS_DISABLED/FILES_DISABLED, ATTACHMENT_PARENT_ACCESS/ATTACHMENT_DELETE_DENIED, RECORD_NOT_ACCESSIBLE, PERMISSION_DENIED — plus DUPLICATE_RECORD converging on the shared rule rather than keeping its local guard.

⛔ Do not decide the crash question. If a sandboxed crash (isScriptFaultMessage, #7543) reaches a code-gated arm, leave today's behaviour exactly as it is, implement the business-message read only, and name the site and the divergence in the report — the arms answer with TypeError prose where the unwrap door's terminal is a sanitised 500, and choosing between those is fault classification. That becomes a follow-up decision card; ⛔ do not ask mid-run and ⛔ do not pick one.

⛔ Do not touch #14541's ordering fix. You are right that it moves this in neither direction — its consult declines a sandbox-origin error precisely so the bulk door keeps today's sentence, and it changes nothing inside mapDataError.

⛔ Do not move OBJECT_NOT_FOUND or INVALID_FIELD. They sit below the unwrap door on main and carry an explicit !isSandboxOrigin clause on the #14541 branch; both spellings already produce the right answer.

Why p2

The status is right and the structured fields are right — only the human sentence is wrong, and only on one door. That caps it below p1.

What holds it at p2 is the population: VALIDATION_FAILED is the documented way for an app author to refuse a write with per-field detail, so the wrong sentence lands on the most ordinary authored refusal there is, and it reads hook 'guard' threw: Error: Amount must be positive to an end user. ⭐ And the shape is worse than a plain bug because #11588 already fixed it once: the same hook, the same refusal, still two different sentences depending on the route — with the direction now reversed rather than closed.

On the filing

⭐ The "What is NOT claimed" section is the part I would keep verbatim, especially "I did not measure an in-repo producer that throws one of these codes from a sandbox body; the producer this addresses is an app-authored hook". Naming the population you could not observe, and pointing at the precedent written for that same population, is what lets this be graded without a re-measurement.

---

Generated by Claude Code