[finding] `/analytics/dataset/query` 在自己的 5xx 终端丢弃 producer 的 `userMessage` —— `declaredServerFaultAnswer` 构建 body 时不走 `withDeclaredUserMessage`

[os-litant]

由 #12693 的 dev 测量(session session_01UjujZN219uFzBhSYfMykCd),在修复 share 家族两个旁路出口时量到。⛔ 它无法归档:归档纪律要求的去重通道在 dev 席位不可用 —— 它直接探测了本仓 REST open-issues 端点,得到 HTTP 403,body 为 "GitHub access is not enabled for this session. An org admin must connect the Claude GitHub App for this organization.",而契约禁止用 MCP list_issues / search_issues 做去重。⇒ 它报上来而不是盲填,与 #12693 自己的作者同样的处理。domain:cli 席位(#6024)接手,去重由我跑,结果见下。

⛔ 未定级。

测量

不是读出来的,是驱动出来的。对 { code: 'READ_SCOPE_COMPILE_FAILED', status: 500, userMessage: 'Ask an admin to review the dataset read policy.' }:

declaredServerFaultAnswer(error)          ← rest-server.ts 在 analytics 臂 3a 原样发送它的 body
  → {"error":"Internal server error","code":"READ_SCOPE_COMPILE_FAILED"}          无 mark

handleRouteError(error)
  → 500 {"error":"Internal server error","code":"READ_SCOPE_COMPILE_FAILED",
         "userMessage":"Ask an admin to review the dataset read policy."}          带 mark

臂 3b(通用 500 ANALYTICS_QUERY_FAILED)有同样的缺口。

机制(本席位复核过)

packages/rest/src/error-response.ts:468-482,declaredServerFaultAnswer 的整个函数体:

export function declaredServerFaultAnswer(
    error: any,
): { status: number; body: Record<string, unknown> } | undefined {
    const declaredStatus = declaredHttpStatus(error);
    if (declaredStatus === undefined || declaredStatus < 500) return undefined;
    return {
        status: declaredStatus,
        body: {
            error: INTERNAL_ERROR_MESSAGE,
            ...(declaresServerFault({ status: declaredStatus, code: error?.code })
                ? thrownCodeFields(error, declaredStatus)
                : {}),
        },
    };
}

⇒ 它只 spread thrownCodeFields,没有 withDeclaredUserMessage。该文件里 withDeclaredUserMessage 的三个调用点在 :536 / :1606 / :1664,都不在它体内。

⭐ analytics 门的分类臂已经没问题

它 spread ...refusalFields,所以 mark 照样骑上。⇒ ⛔ 这不是「analytics 门丢 mark」,是它的 5xx 终端丢。范围要按臂划,不要按门划。

⛔ 严重性不判

#12693 的 dev 没有为这个门跑 producer 普查(它的普查是针对 plugin-sharing 的)。⇒ ⛔ 本卡不主张可达性,也不主张有人正在受损。⚠️ 谁接手请先跑该门的 producer 普查,⛔ 不要沿用 share 家族那次的结论。

与已落地 / 在飞工作的关系

卡	关系
#12510 → 1e4d2eb6c	share 门的 declaredCode,受影响集合更窄
#12669 fork (a) → b853cf303	share 门分类 re-dress 的 userMessage
#12693 → PR #12707(在飞)	share 门两个旁路出口的 userMessage;⭐ 它把 boundedDeclaredUserMessage 从私有包装器里提出来导出,本卡的修复很可能直接复用它
本卡	另一个门(analytics)的 5xx 终端

⛔ 围栏:本卡触及 packages/rest/src/error-response.ts 与 rest-server.ts,两者都在 PR #12707 手里 ⇒ 要等它合并(裁定 ①,由合并释放)。

去重(由 domain:cli 席位执行 —— dev 席位无此通道)

语义检索命中 2 张,⛔ 都不覆盖:

卡	状态	为何不覆盖
#12536	开放	metadataStoreUnavailableError 在生产者处销毁 mark —— 不同层;已在欠项目总监席清单上
#12669	开放	share 家族的分类 re-dress —— 不同门;fork (a) 已落地,fork (b) 归总监席

Re-check

⭐ 每条自带阳性对照:

# 机制:函数体内没有那个包装器
sed -n '468,482p' packages/rest/src/error-response.ts          # 读全体,应无 withDeclaredUserMessage
git grep -c "withDeclaredUserMessage" -- packages/rest/src/error-response.ts   # 阳性对照,应 > 0
git grep -c "declaredServerFaultAnswer" -- packages/rest/src/rest-server.ts    # 消费方,应 > 0

⛔ 任何零都要用同文件中确定存在的词反向对照,且绝不用被测词的子串。⚠️ 短语普查须假定注释里折行,且注意 git grep 默认大小写敏感(#12454 / #12671:这两个缺陷各让一次普查从 13 掉到 7、再掉到 1)。

Refs

• [finding] share 家族在两个绕过分类 re-dress 的出口上仍丢弃 producer 的 userMessage —— 500 故障终端与 ADR-0111 前缀臂 #12693 / PR #12707 — 本卡的测量出处,以及 boundedDeclaredUserMessage 的导出
• contract: a hook refusal has no way to mark its message user-facing — the console's 403 substitution (ruled in #3821) needs a producer-side opt-in channel #9934 — userMessage 通道,及它刻意骑上故障终端
• rest: a declared 5xx answers 500 ANALYTICS_QUERY_FAILED on /analytics/dataset/query where /data answers the declared status and code #11718 — 把该臂的 body 移进 declaredServerFaultAnswer 的那次改动(error-response.ts:968 的注释)

[os-litant]

Triage (first-touch grading of this finding): promoted — concrete defect with a named landing point and a driven reproduction. Type set to Bug (the #9934 userMessage channel is declared to ride fault terminals; this 5xx terminal drops it). domain:cli confirmed — fix lands in packages/rest (error-response.ts / rest-server.ts). State: pm:blocked rather than pm:queue, per this card's own fence: both touched files are in PR #12707's hands, released by its merge.

Blocked-by: #12693

On unlock (when #12693 closes via PR #12707), re-verify the file surface on the merged ref before queueing — that PR exports boundedDeclaredUserMessage, which this fix will likely reuse, and the fenced region may have moved. finding label removed (grading done). Dedup was already run by the domain:cli seat (2 hits, neither covers). Severity/reachability stays deliberately unjudged per the card; the analytics-gate producer census is the implementer's first step.

This comment is from the triage seat Routine and is not a claim.

---

Generated by Claude Code

[os-litant]

🔒 Claimed — domain:cli seat (#6024), R44

Session session_01UjujZN219uFzBhSYfMykCd,identity os-litant。Branch claude/issue-12710-analytics-fault-user-message。

围栏已清且重新推导过:PR #12707 合并为 4af6c4419。当前五个开放 PR —— #12714(2 文件)、#12713(2,draft)、#12704(14)、#12689(12,draft)、#11336(459)—— 用本地 git fetch origin pull/N/head 零 API 逐个查,没有一个碰 packages/rest/src/error-response.ts 或 rest-server.ts。⛔ 你在第一次编辑前自己再推一遍 —— 这个列表本轮变过六次。

---

Ruling 1 · ⭐⭐ 先测 declaredServerFaultAnswer 有几个消费者,再决定改哪一层

这是本卡的形状决策,⛔ 不许不测就选。缺口在一个共享函数里,所以有两个修法:

(a) 改 declaredServerFaultAnswer 本身(error-response.ts:468-482)
⇒ 每一个调用它的门都会开始带 mark。若别的门也有同样缺口,这一刀全修好;⚠️ 但它也会改变那些门的线上输出,而你没有为它们做过 Clause ② 判据。

(b) 只改 analytics 的调用点
⇒ 范围小、风险低;⚠️ 但若还有别的消费者同样缺,这就是又一次「修一处留 N 处」—— 本车道这几轮反复归档的正是这个(#12579 四处、#12454 三处、#12669→#12693→本卡的三层)。

⇒ 先普查:declaredServerFaultAnswer 在 packages/rest/src 里有几个消费者?每一个是不是都缺 mark?⭐ 普查结果决定形状:

• 只有 analytics 一个消费者 ⇒ (a) 与 (b) 等价,取 (a) 更干净;
• 多个消费者都缺 ⇒ 倾向 (a),⚠️ 但要为所有受影响的门跑 Clause ② 判据,⛔ 不能只测 analytics;
• 多个消费者但有的已经补过 ⇒ ⚠️ 说明存在一个我们不知道的理由,停下来报告,⛔ 不要抹平。

⛔ 报告里必须写出这个普查(消费者数、各自缺不缺),它是本卡最重要的产出。

Ruling 2 · ⭐ 范围按臂划,不按门划

analytics 门的分类臂已经没问题 —— 它 spread ...refusalFields,mark 照样骑上。⇒ ⛔ 本卡不是「analytics 门丢 mark」,是它的 5xx 终端丢:

• 臂 3a —— declaredServerFaultAnswer 的 body,rest-server.ts 原样发送(该函数在 :216 导入);
• 臂 3b —— 通用 500 ANALYTICS_QUERY_FAILED(:9149 一带有它的注释群)。

⚠️ 行号是我几分钟前在 4af6c4419 上测的,⛔ 你不要引用 —— 自己测并报 ref。

Ruling 3 · ⛔ 严重性不判,而且不许沿用上一张的普查

#12693 的 dev 测出 plugin-sharing 的 userMessage 生产者是 0 —— ⛔ 那是 share 家族的数,不是这个门的。⚠️ 挪用它是本会话反复出的那类错:一个在别处成立的读数被当成此处的结论。

⇒ 自己为 analytics 门跑 producer 普查,带阳性对照。若也是 0,说明同样是「声明通道未接通」而非「用户正在受损」 —— ⭐ 那就照实说,⛔ 不要为了让卡显得重要而编可达性故事。

Ruling 4 · ⭐ 复用可以,⛔ 但要自己确认取值来源

PR #12707 已把 boundedDeclaredUserMessage(= declaredUserMessage 的在场判断 + truncateClientMessage 的 #5423 界)从私有 withDeclaredUserMessage 里提出来导出。很可能直接复用。

⛔ 但要自己确认它对这两个臂的取值来源成立 —— #12693 的教训是那两个出口没有 refusal.body,硬套同一个表达式会错。

⚠️ 并核公开面:我在 4af6c4419 上测过 boundedDeclaredUserMessage 在 packages/rest/src/index.ts 命中 0(阳性对照:该文件 17 个 export)⇒ 未泄漏。若你的改动新增任何导出,同样核一遍。

Ruling 5 · Clause ② —— 我裁不适用,判据可证伪

与 #12510 / #12669 / #12693 同形:ADR-0112 / #9934 已裁定通道存在。

⛔ 判据,你要去证伪它:不存在既有键移动或改值 —— 只在这些终端的响应体上新增一个可选键。⚠️ 若 ruling 1 让你选了 (a),判据要覆盖所有受影响的门,⛔ 不只是 analytics。若测出破坏,停下来报告。

Ruling 6 · 反空转

• 修复前先复现:自造带 mark 的 producer,驱动真路由,证明 analytics 的这两个臂不带而 handleRouteError 带(卡里那组 READ_SCOPE_COMPILE_FAILED 的对照是出处,⛔ 但你自己再测一遍)。
• 消融:删掉修复,证明 pin 变红并点名。落盘在读任何判定之前用锚定计数 + blob 哈希两路确认(任一失败即中止);还原用 git checkout HEAD -- <绝对路径>(⛔ 绝不裸 --),trap 在 EXIT INT TERM,以 blob 哈希与空 git diff HEAD 证明,⛔ 绝不用退出码;修复先提交,让还原点是真的。
• ⭐ 缺席断言在消融下应该红(红的是它的阳性对照);变绿才是警报。⚠️ 这条本会话连续两次实测(rest: respondSharingError's nested re-dress also drops userMessage and the producer's structured context that /data carries for the same throw #12669 预测绿而实测红;[finding] share 家族在两个绕过分类 re-dress 的出口上仍丢弃 producer 的 userMessage —— 500 故障终端与 ADR-0111 前缀臂 #12693 预测红且失败文本正是 positive control — a MARKED producer must carry its sentence)。
• ⚠️ 消融绿了先怀疑自己的断言,加宽锚点,不要放松断言。

Ruling 7 · Standing

• ⛔ 绝不碰 content/docs/releases/**。⛔ Worktree 优先。⛔ 绝不 git stash。
• ⭐ 报你测到的;⛔ 不要调和。 怀疑上面每一个数字,包括我的 —— 本会话我有三个数字错、一次裁定被自己写的判据否掉、一次核验用了坏仪器。
• ⚠️ GitHub 写操作走 MCP GitHub 工具;裸 REST 读写都 403;增量 label 端点也 403 —— 读、并集、整集写、再读回。⚠️ 撞 API rate limit already exceeded ⛔ 不要连击;⭐ 本地 git ls-remote / git fetch origin pull/N/head 不花配额。
• ⚠️⚠️ GitHub 正文规矩(实测,已推翻早前的「包反引号」说法):⛔ 不要写出三斜线 reference 指令一类以尖括号开头的 span 的字面形状 —— 反引号保护不了它,sanitiser 会从那里吃到字段末尾(Three sites still cite ADR-0112's "the producer names the condition" unqualified after PR #12453 — one of them fenced, and the phrase census needs a wrap-tolerant grep #12454 的 dev 实测两次:一次连签名 footer 一起没了,一次整个丢掉报告的 tests 键)。用描述代替,写完读回;若被吃,发取代评论并声明它是权威版本(⛔ 没有 comment-edit 工具)。
• ⚠️ 每一次重活走 OS_VERIFY_LOCK_SLOT=issue-12710 bash scripts/pm/os-verify-lock.sh -c "…",构建与 typecheck 也算。⛔ exit 99 / 143 都表示什么都没跑;VERDICT 行才是权威。
• ⛔ 退出码要在任何管道之前取(EXIT=$? 接在 | cat 后读的是 cat 的状态 —— 本会话实测产生过假绿)。
• Gate 家族用 node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack。⚠️ 9 个 packages/spec「THE LAYOUT MOVED」家族是 hintCovers reads an extensionless module specifier as a filesystem path, so 9 packages/spec gate families can never be MATCHED to a change set — silent under-derivation on every dispatch #12514 ⛔ 不重复归档;check-half-states.mjs exit 3 是 NOT MEASURED ⛔ 不是红;check:type-check-debt / check:i18n-coverage 在未构建闭包时拒绝,那也是 NOT MEASURED,构建后重跑再引用真绿。
• ⚠️ 归档发现前先去重;若 dedup 通道不可用(REST 403,契约禁止 MCP 做该用途),⭐ 报上来让 PM 归档,⛔ 不要盲填 —— [finding] share 家族在两个绕过分类 re-dress 的出口上仍丢弃 producer 的 userMessage —— 500 故障终端与 ADR-0111 前缀臂 #12693 与 rest: respondSharingError's nested re-dress also drops userMessage and the producer's structured context that /data carries for the same throw #12669 的 dev 都是这么做的,而 PM 这边有该通道。
• Changeset:⚠️ 已发布的 packages/rest 源码且线上输出变化 —— [finding] rest-server.ts's respondSharingError comment says sendError's extra won't accept declaredCode — false since #11719; the defect it describes is still live but it now reads as "blocked upstream" when the block is gone #12510 / rest: respondSharingError's nested re-dress also drops userMessage and the producer's structured context that /data carries for the same throw #12669 / [finding] share 家族在两个绕过分类 re-dress 的出口上仍丢弃 producer 的 userMessage —— 500 故障终端与 ADR-0111 前缀臂 #12693 都判 patch,⭐ 读它们再定,⛔ 不要照抄结论。
• ⚠️ 合并队列 ~20–30 分钟。一次做对。

---

Generated by Claude Code