rest: an UNDECLARED hook refusal answers 500 on `/analytics/dataset/query` where the same refusal answers 400 on `/data` — the route's fallback arm treats a business refusal as a server fault

[os-zhuang]

Filed unassigned while implementing #11588. That card fixed the message on this route (the QuickJS debug wrapper no longer reaches the client); this is the status, which #11588 deliberately did not move.

Measured

On claude/issue-11588-sandbox-wrapper-bulk-routes at f93aa39e, driving the real POST /api/v1/analytics/dataset/query handler in process, with a hook throwing new Error('month-end close is in progress') and declaring no status and no code:

face	answer
POST /api/v1/data/:object (and every other /data write)	400 — month-end close is in progress
POST /api/v1/analytics/dataset/query	500 ANALYTICS_QUERY_FAILED — month-end close is in progress

Pinned as measured (green on both sides of #11588) in packages/rest/src/rest-hook-refusal-message-parity.test.ts §8b, which asserts the 500 explicitly and says in its comment that the status is a separate defect left standing.

Why

The analytics catch has three arms. ① serves a declared 4xx plus a code; a declared 5xx and everything else fall to ③, the hand-built 500 ANALYTICS_QUERY_FAILED. Both halves of ①'s gate are deliberate and documented (#5352: a 4xx with no code "would force this route to invent one"). But that leaves the undeclared refusal — a hook that simply throws a sentence, which is the most common shape an app author writes — classified as a server fault.

classifyDataError's sandbox unwrap door answers exactly this case with 400 and the verbatim message, which is what hook-error-format.dogfood.test.ts pins end to end. So one hook body, one throw, two statuses depending on whether the caller hit a dashboard tile or a list view.

Why #11588 did not fix it

Its dispatch carried a hard stop on contract-shaped moves, and changing which arm an undeclared refusal lands in is a classification change on a shipped route, not a message repair. It is also genuinely arguable: ADR-0112's "the producer names the condition" reading says an undeclared throw is unclassified and 500 is honest, while the /data door's reading says a hook's throw is a business rule and 400 is honest. The two doors currently disagree, and that disagreement is the defect regardless of which way it is settled.

Not established here

• Which answer is right. The two candidate rulings are named above; picking between them is a contract call.
• Whether the sibling /analytics/query face (through dispatcher-plugin.errorResponseBase) has the same split. Not exercised.
• Severity not judged.

Region: packages/rest/src/rest-server.ts, the /analytics/dataset/query catch only.

[os-zhuang]

Triage: lands in packages/rest (the analytics route's fallback arm) → domain:cli, type Bug, pm:queue. Rationale: a declared hook refusal answering 500 where the same refusal answers 400 on /data violates the route family's own error-mapping contract — declared≠enforced on the status axis, no design question inside.

⚠️ Family / serial constraint for the dispatching seat: #11588 is in flight on the same seam (the mapDataError unwrap and the sandbox-wrapper leak, dispatched domain:cli), and #11683 is the record-share sibling queued this same round. Fold-or-serial is a must-answer at claim time per the five gates — at minimum hard-serialize behind #11588 and re-measure this route's arm on its merged ref; #11588's fix may move or close this card's gap.

---

Generated by Claude Code

[os-zhuang]

Claim — domain:cli lane execution seat, session 019siH5jDmk5hrayvfyojUqR, round R34.

Branch: claude/issue-11683-route-refusal-classification — this card is folded with #11683 and is implemented on that card's branch, in one PR, with per-card acceptance criteria.

Declared file surface (shared with #11683): packages/rest/src/rest-server.ts (the /analytics/dataset/query catch and the three record-share catches), packages/rest/src/rest-hook-refusal-message-parity.test.ts §8b, + a changeset.

Serial constraint discharged. #11588 landed as #11687 (merged), so the "hard-serialize behind #11588 and re-measure on its merged ref" constraint is released by that merge. Re-measurement on the current origin/main is part of the dispatch: #11687 fixed the message on this route and may have shifted this card's arm.

Fold rationale and the fork clause are stated in full on #11683 (comment 5395514237) — including the ⛔ binding stop: if both candidate readings of "what status does an undeclared hook refusal deserve" turn out to have live in-repo pins, the dev reports the fork and lands nothing on this arm; this card then returns to pm:queue while the share half may land alone.

Acceptance criterion for this card specifically: an undeclared hook throw on POST /api/v1/analytics/dataset/query answers the same status as the same throw on POST /api/v1/data/:object. §8b's pin on the 500 is inverted, not deleted — it currently records the defect as measured, so it becomes the pin that the two doors now agree, with its comment rewritten to say which reading won and why.

---

Generated by Claude Code