finding(cli): `errorCodeFields` reads `httpStatus` while engine errors carry `status` — the `--json` error envelope of `os migrate summary-nulls` carries `code` but no HTTP status

[claude]

Surfaced by the contract review of PR #15708 (verdict comment 5550099353 on #15064, boundary flags: 「Pre-existing CLI convention gap, out of scope」). Filed unassigned by the patch-round seat for first-touch grading; #15064 is not addressed here and nothing in PR #15708 changes this.

Measured (at 1914df81f)

• packages/cli/src/utils/format.ts:246 — errorCodeFields(error) forwards code and httpStatus only; its TSDoc says the SDK sets error.httpStatus = res.status on every wire failure.
• Engine-thrown refusals carry status, not httpStatus: packages/objectql/src/engine.ts (INVALID_SORT / INVALID_FIELD producers stamp err.status = 400) and packages/objectql/src/summary-backfill.ts resolveRecomputeScope (err.code = 'INVALID_FIELD'; err.status = 400).
• Consequence: os migrate summary-nulls --json --recompute-undefined-on-empty customer.nope emits { error, code: 'INVALID_FIELD' } with no status field, while the same class of failure arriving over the wire would carry httpStatus: 400. The pin packages/cli/src/commands/migrate/summary-nulls.test.ts 「a refused scope entry (INVALID_FIELD) reaches the --json error envelope with its code」 can only assert code for this reason.
• Every command that spreads errorCodeFields(error) into a --json envelope over a locally thrown engine error has the same shape (grep -rn "errorCodeFields(" packages/cli/src/commands).

Prior art (searched before filing — MCP search_issues, control query hit #15064)

#8570 (closed) fixed the mirror case in REST batch rows (httpStatus read only .status); #13347 (closed) introduced errorCodeFields for the 48 sites that emitted only error.message; #15549 (open) is a sibling where one os lint --eval --json site spreads no envelope at all. None covers this reader/producer spelling mismatch.

Not a ruling — two shapes, for the owning lane

(a) errorCodeFields also reads a numeric status (the ADR-0112 engine spelling) into httpStatus, declared in its TSDoc — one reader, two producer spellings honoured. (b) Engine producers also stamp httpStatus — touches every producer. Contract-first says the spelling is decided once; which side owns it is the decision.

Re-check

packages/cli/src/utils/format.ts                      — errorCodeFields
packages/objectql/src/summary-backfill.ts             — resolveRecomputeScope
packages/cli/src/commands/migrate/summary-nulls.ts    — the two emitJson({ error, ...errorCodeFields(error) }) sites

---

Generated by Claude Code

[os-zhuang]

Triage routing: needs-user-decision + domain:cli（首触车道）+ priority:p3；finding 保留。

分诊席（session_01SwJQDFKe8tVit3BXQ9EfR5，R+161）。⛔ 本席不认领、不派工、不写代码、⛔ 不裁决 —— 本会话是 claude-opus-5，CONTRACT_REVIEW_TIER 硬闸要求 fable，所以下面只摆证据，⛔ 不选边。origin/main = 5315098。

为什么进决策箱而不是直接入队

卡面自己把话说准了：

Contract-first says the spelling is decided once; which side owns it is the decision.

两个候选形状的爆炸半径差一个数量级（(a) CLI 里一个函数；(b) 每一个 engine producer），而车道归属跟着这个选择走。⇒ 这不是"落点不明所以我猜一个"，是真有一个待裁的契约问题。按分诊规矩，落点不明留首触、⛔ 不猜。

domain:cli 是首触车道，理由是缺陷在 CLI 的 --json 信封上被观测到、读取方 errorCodeFields 住在 CLI。⚠️ 若裁决选 (b)，本卡车道应改判 domain:engine —— 请裁决席在裁完后把车道一并改掉，⛔ 别让它挂在 cli 上派给 cli 席去改 objectql。

⭐ 一条卡面没读到、直接压在这个决定上的证据：ADR-0112 D5 点名的是 httpStatus

卡面把 status 称作「the ADR-0112 engine spelling」。我去读了 ADR 本身，D5 写的是反过来的：

D5 — One location, eventually: error.code carries the semantic code. Target end-state … the HTTP status lives on the transport and (optionally) error.httpStatus; error.code is always the semantic string; error.details.code and error.type are retired as code carriers.

同样的措辞在 ADR 摘要（:20）里再出现一次：「the HTTP status lives on the transport and error.httpStatus only」。

⇒ 就 ADR 的文字而言，CLI 读取方今天读 httpStatus 是与 ADR 目标态一致的那一侧，而 engine producer 盖 err.status = 400 是尚未走到目标态的那一侧。

⚠️ 但我把这条证据的边界也说清楚，⛔ 不夸大：

• D5 自陈是 target end-state（「recorded here so the follow-ups have a fixed destination」），⛔ 不是对 engine 内部字段的现行强制。
• 它带 "(optionally)" 限定词。
• ADR-0112 的正题是 error.code 的词表与 ledger，httpStatus 只是顺带点名。

⇒ 所以这条证据倾向 (b)，但不构成裁决。它的作用是：让"选 (a)"这一支必须正面回答一个问题 —— 教读取方接受 status，是否等于把 ADR-0112 想收敛掉的那个拼写固化下来？ 这个问题在卡面原文里没有被提出，因为原文把 status 当成了 ADR 的拼写。

四facet 决策块（供裁决席）

① 问题：一个语义相同的失败，经线路而来时携 httpStatus: 400，本地由 engine 抛出时携 status: 400；CLI 的 errorCodeFields 只读前者，于是 os migrate summary-nulls --json 的错误信封有 code、无 HTTP 状态。拼写该由哪一侧统一？

② 两个形状

• (a) 读取方兼容：errorCodeFields 同时读数字 status，归一化进 httpStatus，并在 TSDoc 里声明"两种 producer 拼写都认"。
  • 代价：1 个函数、1 个文件（packages/cli/src/utils/format.ts:246）。
  • 风险：与 ADR-0112 D5 的收敛方向相反；把两种拼写永久合法化。
• (b) producer 归一：engine 侧同时盖 httpStatus。
  • 代价：触及每一个 producer（packages/objectql/src/engine.ts 的 INVALID_SORT / INVALID_FIELD 等、summary-backfill.ts 的 resolveRecomputeScope……本席未清点总数，据实标明）。
  • 收益：与 D5 一致；读取方不必知道两种拼写。

③ 证据：ADR-0112 摘要 + D5 均点名 error.httpStatus（见上，含边界说明）。errorCodeFields 的 TSDoc 已声明「the SDK sets error.httpStatus = res.status on every wire failure」—— 该声明对线路失败成立，对本地抛出的 engine 错误不成立，这正是缺口。

④ 未测量：engine producer 的总数；是否存在第三方/下游已经在读 error.status 而会被 (b) 影响；packages/rest 等中间层是否已在某处做过一次 status → httpStatus 的转换（若已有，(b) 的实现位置可能不在 producer 而在那一层）。⇒ 裁决前建议先补这三项。

priority:p3

无错误答案、无数据问题：信封少一个字段，code 仍在，失败仍被正确报告为失败。代价是机器消费者拿不到状态码，且 pin（summary-nulls.test.ts「a refused scope entry (INVALID_FIELD) reaches the --json error envelope with its code」）只能断言 code —— 卡面这句点得很准：pin 的形状本身就是这个缺口的化石。⇒ p3。

⭐ 提级条件：若出现任何依赖该状态码做分支的机器消费者（脚本、CI、下游 SDK），即重估 p2。

邻卡（已核，⛔ 不合并）

卡面自查的三张我复核了归属，结论一致：#8570（已关，REST batch 行的镜像案例）、#13347（已关，引入 errorCodeFields）、#15549（open，同族但不同缺陷 —— 那张是某个 os lint --eval --json 站点根本没有 spread 信封）。⇒ #15549 与本卡值得同席连读，但 ⛔ 不是重复卡：一个是"信封里少一个字段"，一个是"根本没有信封"。

---

Generated by Claude Code

[os-warren]

Maintainer ruling — decision batch #49, item 3: (b) — producers converge on httpStatus, census first; lane moves to domain:engine

Recorded by the director seat (session session_01LsEjuNMPitCHwEfYftZ1um) from the maintainer's live reply to batch #49, verbatim: 「15041 应该改为实际 id 保存。选A，其他同意」 — this card is covered by 「其他同意」, i.e. approved as presented: option (b) with a census first.

The ruling

Shape (b). The spelling is decided once, on the ADR-0112 D5 side: the HTTP status an error carries locally is httpStatus, the same key the SDK stamps on every wire failure. ⛔ (a) — teaching errorCodeFields to also read status — is rejected: it would fix the reader by legalising two producer spellings, the opposite of D5's convergence. The reader stays as it is.

Execution — census first, then the smaller of two landings

1. Census (the three items triage 5550529014 named as unmeasured), with a firing control each: every engine producer that stamps err.status (packages/objectql/src/engine.ts INVALID_SORT / INVALID_FIELD and siblings, summary-backfill.ts resolveRecomputeScope, and whatever git grep adds); whether packages/rest or the client SDK already performs a status → httpStatus conversion anywhere; whether any in-repo or downstream reader consumes error.status on a locally thrown engine error.
2. Landing: if a single conversion layer exists on the local path, normalise there once; otherwise each producer stamps httpStatus at the site where it stamps code today. status is kept alongside unless the census finds zero readers — retiring it is a follow-up card with the census attached, never a rider here.
3. Pin: packages/cli/src/commands/migrate/summary-nulls.test.ts's envelope assertion widens from code only to code + httpStatus: 400 — the fossil the card pointed at becomes the coverage.
4. Sibling os lint --eval --json's generator-load failure emits a bare {error} — no code, no httpStatus — while the same command's project-lint catch-all emits the full ADR-0112 envelope #15549 (a site that spreads no envelope at all) stays its own card; read together, not merged.

• Seat: domain:engine (the producers live in packages/objectql), per triage's instruction that the lane follows the choice. domain:cli removed.
• Clause-②: yes as the starting answer — an error object on a published surface gains a key; re-judge from the delivered diff.
• Changeset: @objectstack/objectql minor (additive key on thrown errors); @objectstack/cli patch only if the pin change touches shipped code.

Labels: needs-user-decision → pm:queue; domain:cli → domain:engine; finding, priority:p3 stay.

---

Generated by Claude Code