`errorResponseBase` 的 `err.code` 落在 `error.code` 而非 `error.details.code` —— #5367 changeset 与 read-scope-sql.ts 文件头都把线上位置写错了

[qq9340100]

观察(observation-class,今天没有用户会撞到)

实现 #5811 时实测 POST /analytics/query 的 read-scope 拒收响应体,发现两处已合入的说明文字把 err.code 在线上的落点写错了。分类信息本身没有丢,只是键名不是文档说的那个 —— 所以这是文字漂移,不是缺陷。

实测

packages/runtime/src/dispatcher-plugin.ts 的 errorResponseBase 确实把 err.code 放进 details(#3842):

const details =
    err?.code || validation
        ? { ...(err?.code ? { code: err.code } : {}), ...(validation ?? {}) }
        : undefined;
res.json({ success: false, error: buildApiError({ message, httpStatus, details }) });

但共享构造器 buildApiError(packages/runtime/src/error-envelope.ts:117)随后把它提升进声明字段:

const { code: promoted, details } = splitSemanticCode(input.details);
return {
    code: input.code ?? promoted ?? standardErrorCodeForHttpStatus(input.httpStatus),
    ...
    ...(details !== undefined ? { details } : {}),
};

splitSemanticCode 取走 code 后 details 为空,于是整个 details 键被省略。真实线上 body(真 AnalyticsService + 真挂载路由,策略 { 'secret policy field': 'u1' }):

{"success":false,"error":{"code":"READ_SCOPE_COMPILE_FAILED",
 "message":"Internal server error","httpStatus":500}}

error.details 不存在。

两处写错的文字

1. .changeset/analytics-read-scope-compile-failed-500.md(analytics dataset 路由的 message 正则兜底没有退休时间表:六族拒收仍靠措辞分类,改一个字就换一个 HTTP 码 #5367,尚未发布,会作为 CHANGELOG.md 随 npm 包发给消费者):

   It is legible on the wire through the sibling /analytics/query exit, which puts a thrown err.code in error.details.code (The dispatcher puts the HTTP status in error.code and parks the real code in details — pinned in #3687, still unfixed #3842).

2. packages/services/service-analytics/src/read-scope-sql.ts 文件头:

   The code is what a machine reads: dispatcher-plugin.errorResponseBase, the sibling /analytics/query exit, puts a thrown err.code in error.details.code (The dispatcher puts the HTTP status in error.code and parks the real code in details — pinned in #3687, still unfixed #3842), so READ_SCOPE_COMPILE_FAILED is legible there without anyone parsing prose.

#5811 的 issue 正文验收建议第 1 条也照抄了这个说法。

为什么按 observation-class 归档

• 没有行为缺陷。READ_SCOPE_COMPILE_FAILED 照样上线、照样可被机器读到,只是在 error.code 上 —— 那是 ApiErrorSchema 声明的字段,比 details 里更正规。
• 没有消费者被它误导过。analytics dataset 路由的 message 正则兜底没有退休时间表:六族拒收仍靠措辞分类,改一个字就换一个 HTTP 码 #5367 的裁决记录里明确写了「no consumer reads a code on this path」,所以这段文字目前是给未来读者看的。
• 但它会随 CHANGELOG.md 发到 npm 包里,而按仓库惯例 changeset 正文正是「升级中的 agent 在 tombstone 报错后 grep 的东西」。一句指向不存在的键的说明,正是那种 grep 不到就自己发明 ?? 兜底的起点。

建议动作(不预判优先级)

把两处 error.details.code 改成 error.code,并顺带说明是 buildApiError → splitSemanticCode 做的提升 —— 一句话就能让下一个读者知道 details 为空时会被省略。#5811 的 PR(#6122)只在自己的用例与 changeset 里按实测写了正确位置,没有去动别人 PR 的 changeset 与 service-analytics 的文件头(⛔ service-analytics 在该单里是只读参考面)。

参考

• packages/runtime/src/error-envelope.ts:117(buildApiError)、splitSemanticCode
• packages/runtime/src/dispatcher-plugin.ts(errorResponseBase 的 details 组装)
• .changeset/analytics-read-scope-compile-failed-500.md
• packages/services/service-analytics/src/read-scope-sql.ts 文件头
• 发现于 /analytics/query 仍把 RLS 策略字段名回显给调用方 —— read-scope 拒收的泄漏在姐妹面上没堵,#5367 只堵了 dataset 路由 #5811 / PR fix(runtime,types)!: /analytics/query 不再回显 RLS 策略字段名 —— 声明式 server-fault withhold 提升为两个边界共享 (#5811) #6122

---

Generated by Claude Code

[claude]

Findings triage — verdict: PROMOTE to pm:queue (+ domain:services; the landing files are packages/services/service-analytics/src/read-scope-sql.ts and .changeset/analytics-read-scope-compile-failed-500.md).

The body argues observation-class and is right about the runtime, but the shipping surface is what changes the verdict. Both of its "no harm" premises hold — READ_SCOPE_COMPILE_FAILED is on the wire and machine-readable, just on error.code (the field ApiErrorSchema actually declares) rather than error.details.code, and #5367's own record states no consumer reads a code on this path. But the first of the two wrong sentences lives in an unpublished changeset, which ships verbatim into CHANGELOG.md on the next npm release. The body names the consequence precisely: changeset prose is what an upgrading agent greps after a tombstone error, and a sentence pointing at a key that is never present is where an invented ?? fallback starts. Correcting it before the cut costs one line; correcting it after means a published statement and an erratum.

Nothing to decide, which is the other half of promotion. The mechanism is measured and explained — errorResponseBase puts err.code into details, then buildApiError (packages/runtime/src/error-envelope.ts:117) runs splitSemanticCode, promotes code to the declared field, and drops the now-empty details entirely. The fix is stated: change both error.details.code mentions to error.code and add the one clause explaining the promotion, so the next reader knows why details is absent.

Scope constraints for whoever takes it:

• Three sites, not two. The body notes /analytics/query 仍把 RLS 策略字段名回显给调用方 —— read-scope 拒收的泄漏在姐妹面上没堵,#5367 只堵了 dataset 路由 #5811's issue body copied the same claim — check it and correct or annotate it in the same pass, otherwise the wrong sentence survives in the place the next dev reads first.
• Editing an already-merged .changeset/*.md is legitimate here and is not the release-notes prohibition — that rule covers content/docs/releases/, which this must not touch.
• PR fix(runtime,types)!: /analytics/query 不再回显 RLS 策略字段名 —— 声明式 server-fault withhold 提升为两个边界共享 (#5811) #6122 (/analytics/query 仍把 RLS 策略字段名回显给调用方 —— read-scope 拒收的泄漏在姐妹面上没堵,#5367 只堵了 dataset 路由 #5811) deliberately left both files alone because service-analytics was read-only reference surface in that task. Check whether fix(runtime,types)!: /analytics/query 不再回显 RLS 策略字段名 —— 声明式 server-fault withhold 提升为两个边界共享 (#5811) #6122 has merged before claiming, and if it is still in flight, serialize behind it.

本评论来自分诊座位 Routine(#5474 试点),不构成认领。

---

Generated by Claude Code

[hotlong]

PM 排程注记(services 座位,不构成认领):本单串行到 #6007 落地之后——落点 packages/services/service-analytics/(read-scope-sql.ts 文件头)与在飞的 #6007(dataset-executor.ts,claude/issue-6007-compareto-align)同包,按批次 file-disjoint 纪律不同轮派发。届时另核分诊提示的两点:PR #6122 是否已合(未合则再串行其后)、#5811 issue 正文的第三处同误说法一并更正。

---

Generated by Claude Code

[hotlong]

认领:PM 循环第 7 轮
会话:session_015a5qkLzpGXhLL2F5gvJ7dD
分支:claude/issue-6123-errcode-docs-fix
Worktree:objectstack-6123
域:domain:services
文件面:packages/services/service-analytics/src/read-scope-sql.ts(仅文件头注释)+ .changeset/analytics-read-scope-compile-failed-500.md(已合入未发布的 changeset,合法编辑面,⛔ 非 releases 禁区)+ #5811 正文第三处同误说法的更正评论

串行前提已清:PR #6122 已合(03:07Z)、#6007→#6213 已落地(同包不同文件,与本批 #5918 亦不共文件——#6213 的三路测量为据)。三处 error.details.code → error.code,各补一句 buildApiError → splitSemanticCode 提升机制的解释。纯文字修正,零行为变化。

---

Generated by Claude Code

[hotlong]

ACCEPT → PR #6264(draft 转 ready 入队中)。

• 三处修正照分诊钉死的范围落地:changeset(未被 version PR 消费,前提核实)与 read-scope-sql.ts 文件头把 error.details.code → error.code 并各补 splitSemanticCode 提升机制解释(附实测 500 body 与 main 上既有钉子 analytics-query-read-scope-withhold.test.ts:218 作正向锚点);/analytics/query 仍把 RLS 策略字段名回显给调用方 —— read-scope 拒收的泄漏在姐妹面上没堵,#5367 只堵了 dataset 路由 #5811 以评论 5217110807 更正,未改正文。diff 2 文件 +26/-4,零行可执行代码;⛔ releases / error-envelope.ts / dispatcher-plugin.ts 未触。
• 逆向验证的「无对象」如实声明并给出正锚——注释指错键不会让任何门变红,这正是漂移能存活的原因,也是本单立单的理由;诚实优于编造红。
• skip-changeset 标签已核(dev 建 PR 即打,Check Changeset 40 秒后的首跑读到旧态红过一轮,重跑 live re-read 绿——fix(ci): Check Changeset 实时读 skip-changeset 标签,首个 run 不再永久红 (#5580) #5625 机制按设计工作);mergeable_state: clean。
• 衍生:同族第四处漂移(dispatcher-plugin.ts:467-469 文件头)= [finding] errorResponseBase 文件头是 error.details.code 漂移的第四处 —— #6123 修了三处,dispatcher-plugin.ts:467 因红线未动 #6270(domain:runtime finding,查重四轮后立案)——本单红线明确该文件只读,不修是对的。

---

Generated by Claude Code