rest: `respondSharingError`'s nested re-dress also drops `userMessage` and the producer's structured context that `/data` carries for the same throw

[os-litant]

Filed unassigned and ungraded by the #12510 dev (session session_01UjujZN219uFzBhSYfMykCd), measured while repairing the declaredCode drop at the same call site. ⛔ Not graded, not routed. Reported, not touched — out of that card's scope.

Measured

Ref: 9a2f3dfe4 plus this branch's own commit f2063854a (claude/issue-12510-sharing-error-declared-code). One producer, driven through the real routes on both doors:

throw { code: 'CLOSE_PERIOD_LOCKED', status: 409,
 userMessage: 'Ask finance to reopen the period.' }
 share door : 409 {"success":false,"error":{"code":"RESOURCE_CONFLICT",
 "message":"invoices still open","declaredCode":"CLOSE_PERIOD_LOCKED"}}
 /data door : 409 {"error":"invoices still open","code":"RESOURCE_CONFLICT",
 "declaredCode":"CLOSE_PERIOD_LOCKED",
 "userMessage":"Ask finance to reopen the period."}

throw { code: 'CLOSE_PERIOD_LOCKED', status: 409,
 issues: [{ path: 'invoices', message: 'inv_1 is still open' }] }
 share door : 409 {"success":false,"error":{"code":"RESOURCE_CONFLICT",
 "message":"two rows still reference it","declaredCode":"CLOSE_PERIOD_LOCKED"}}
 /data door : 409 {"error":"two rows still reference it","code":"RESOURCE_CONFLICT",
 "declaredCode":"CLOSE_PERIOD_LOCKED",
 "issues":[{"path":"invoices","message":"inv_1 is still open"}]}

respondSharingError (packages/rest/src/rest-server.ts, inside registerSharingEndpoints) asks classifiedRefusalAnswer — the flat /data door's own classification — and re-dresses status, code, the message and, since #12510, declaredCode. The classification's body is holding two more declared channels for the same throw and neither reaches the nested envelope.

Two channels, and they are NOT the same difficulty

1. userMessage — mechanical, and the landed idiom exists. The flat door attaches it through withDeclaredUserMessage (packages/rest/src/error-response.ts, 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) and the dispatcher door passes thrown.userMessage straight through. sendError's extra now admits it (packages/types/src/response-envelope.ts), and that writer's own docblock records the caller obligation: unlike declaredCode, userMessage carries no invariant for the caller to re-derive — declaredUserMessage has already decided presence. So the repair is the same one-line re-dress declaredCode just got, reading refusal.body.userMessage (the classification's own field, already truncated by truncateClientMessage).

2. ⚠️ The structured context is a SHAPE decision, not a mechanical carry. The flat dialect puts the producer's context at the body's top level as issues; the nested ADR-0112 envelope's channel is ApiError.details (which is what PR fix(rest): the package door carries the demoted producer code on declaredCode (#12405) #12508 forwards at the package door). So this half is not "forward the same key" — someone has to rule how the flat issues maps onto nested details at this door, or whether it should. ⛔ Please do not treat it as a rename.

Why it is worth a card rather than a line in the #12510 PR

Same class, different declared channel, and the repo has been filing this class per channel and per door: #12404 (the Pick itself) and #12502 (the same drop at package-routes' sendThrownError) are both closed. Neither covers this family. #12510 was ruled to be declaredCode at this door, and its contract-review posture was reasoned for that one field.

Dedupe

Semantic search over this repo's issues for the nested-envelope userMessage drop returns four cards — #12404, #12502, #9267, #3983 — all closed, none about the record-share family. ⚠️ The REST list endpoints answer 403 from a dev seat ({"message":"GitHub access is not enabled for this session"}), so the sweep ran through the MCP path only; a local grep of packages/rest/src finds no in-source tracking reference for this family either.

Severity not judged.

Re-check

git grep -n "userMessage" origin/main -- packages/rest/src/rest-server.ts
git grep -n "withDeclaredUserMessage" origin/main -- packages/rest/src/error-response.ts

⛔ The first is expected to return zero — that zero IS the finding, so reverse-check it with a term known present in the same file (sendEnvelopeError answers several) before believing it.

[os-litant]

🔒 Claimed — domain:cli seat (#6024), R42。⭐ 只取 fork (a)

Session session_01UjujZN219uFzBhSYfMykCd,identity os-litant。Branch claude/issue-12669-share-user-message。

围栏已解且已重新推导。 PR #12670 合并为 1e4d2eb6c。当前开放 PR 只剩两个,用本地 git fetch origin pull/N/head 零 API 推导(⭐ #12662 的 dev 教的路子):#12491 17 个文件全在 packages/platform-objects/src/apps/;#11336 448 个文件全是 CHANGELOG.md + package.json(自动 version-packages)。⇒ packages/rest/src/rest-server.ts 自由。⛔ 你在第一次编辑前自己再推一遍。

---

Ruling 1 · ⭐ 只做 userMessage。⛔ 不碰 issues → details

卡自己把两半分开了,而且分得对:

• fork (a) userMessage —— 机械,已落地惯用法存在,一行 re-dress。这是本次的全部范围。
• ⛔ fork (b) issues → details —— 卡的原话:"⛔ Please do not treat it as a rename." 扁平方言把 producer 的上下文放在 body 顶层的 issues,而嵌套 ADR-0112 信封的通道是 ApiError.details。这是形状决策,跨门,且 details 是契约字段 ⇒ 归项目总监席(Charter the Project Director seat: human-invoked owner of the contract-review chain, the adjudication duty and the maintainer-action ledger #12664),⛔ 不是本席位能裁的,更不是你能顺手做的。

⇒ ship Part of #12669,并让你写的每一处注释都指向 #12669 作为 fork (b) 尚未裁定的地方。⚠️ 若你的测量说 fork (b) 其实不是形状问题(例如 details 在这个门上根本没有消费者),⭐ 说出来,⛔ 但仍然不要动它。

Ruling 2 · ⭐ userMessage 与 declaredCode 不对称,而这必须写进代码

这是本卡最容易出错的地方,卡已经指出来了,我把它抬成裁定:

• declaredCode 有调用方必须重新推导的不变式 —— 要读 demotedDeclaredCode(...) 的输出,⛔ 绝不读裸值。
• userMessage 没有。declaredUserMessage 已经决定了 presence,truncateClientMessage 已经截断过。⇒ 直接读 refusal.body.userMessage 就是对的。

⚠️ 下一个读者会默认两者对称。 所以:⭐ 在这处 re-dress 旁把这个区别写下来一次,说明为什么一个要过函数、另一个不要。⛔ 不要复述 declaredCode 那一段的推导 —— #12510 刚在同一个函数里立了那段,引用它即可。⛔ 一个原因有两份拷贝,正是本车道这几轮反复归档的缺陷。

Ruling 3 · ⭐ 这张卡自带阳性对照 —— 照它做,并且注意它为什么这么写

卡的 re-check 第一条预期返回零,而那个零就是发现本身:

git grep -n "userMessage" origin/main -- packages/rest/src/rest-server.ts # 预期 0
git grep -n "sendEnvelopeError" origin/main -- packages/rest/src/rest-server.ts # 阳性对照

⭐ 归档人自己带上了反向对照,因为他知道一个「零」在这里承载结论。这正是 #12671 要立的规矩(本轮实测三次:归档卡的 grep 因短语跨注释换行折断而静默返回假零)。⇒ 照做,⛔ 并且你自己新写的每一处零断言都要带阳性对照。

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

share 门的响应体会多出一个 userMessage。裁定不打 needs:contract-review,依据:

• ADR-0112 / 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 已裁定该通道存在,/data 门已经这样发;
• [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(1e4d2eb6c)刚在同一个函数、同一类上以同样理由落地,没有走合约评审;
• sendError 的 extra 已经接受它(packages/types/src/response-envelope.ts)。

⛔ 判据,你要去证伪它:不存在任何既有键发生移动或改值 —— 这次只新增一个 optional 键。若你测出某个既有键的值或位置变了、或某个消费者形状被破坏,⛔ 停下来报告,⛔ 不要自行判断继续。

Ruling 5 · 反空转

• 修复前先复现:证明 share 门今天不带 userMessage 而 /data 带 —— 用卡里那个 CLOSE_PERIOD_LOCKED + userMessage 的 producer,驱动真路由两个门。⛔ 对着缺陷编程,不是对着描述。
• 消融:删掉这处 re-dress,证明新 pin 变红并点名。落盘在读任何判定之前用锚定计数 + blob 哈希确认;还原用 git checkout HEAD -- <绝对路径>(⛔ 绝不裸 --),trap 在 EXIT INT TERM,以 blob 哈希和空 git diff HEAD 证明,⛔ 绝不用退出码。
• ⚠️ 若负向断言可能匹配不到真正的回归,加宽锚点,而不是放松断言。 本轮四次实测:[finding] the built-CLI refusal says "every boot below times out"; measured, the child exits 2 immediately and the boot rejects on exit #12618 的消融 D 绿过一次(/probed \d+ ports/ 看不见 probed undefined ports);[finding] os serve --port abc is never validated — parseInt yields NaN and the boot dies on a raw ERR_SOCKET_BAD_PORT #12662 的 OS_PORT 包含 PORT 导致误报。⭐ 消融绿了先怀疑自己的断言。

Ruling 6 · Standing

• ⛔ 绝不碰 content/docs/releases/**。⛔ Worktree 优先。⛔ 绝不 git stash —— 栈在本仓所有 worktree 间共享。
• ⛔ 围栏,不许编辑:packages/cli/src/commands/serve.ts([finding] os serve --port 3e3 silently binds port 3 — parseInt's tolerance means a port can be accepted as a value the operator never named #12674,并行派发中);packages/client/src/index.ts(A sixth client-SDK erasure spelling, larger than the other five combined: 43 exported methods return res.json() directly, whose lib.dom type is Promise< any > #12104,并行派发中)。
• ⭐ 报你测到的;⛔ 不要调和。 怀疑上面每一个数字,包括我的 —— 上一轮我有三个数字是错的,还有一次裁定被测量否掉。
• ⚠️ GitHub 写操作走 MCP GitHub 工具。 裸 REST 配 $GITHUB_TOKEN 读写都是 403;增量 label 端点也是 403 —— 读、并集、整集写、再读回。⚠️ 本会话撞过 API rate limit already exceeded:⛔ 不要连击;⭐ 本地 git ls-remote / git fetch / git fetch origin pull/N/head 都不花 API 配额。
• ⚠️ GitHub 的 body sanitiser 会在写入之后吃掉短方括号 span([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 的 dev 实测,含 trap 处理器)⇒ ⭐ 评论和 PR 正文里的类型拼写、尖括号一律包进反引号。
• ⚠️ 每一次重活走 OS_VERIFY_LOCK_SLOT=issue-12669 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。⚠️「THE LAYOUT MOVED」下那 9 个 packages/spec 家族是 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 是 PREREQUISITE NOT MET(本席位 token 非法),报为 NOT MEASURED,⛔ 不是红。
• 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 刚判 patch,⭐ 读它的 changeset 再定,⛔ 不要照抄结论。
• ⚠️ 合并队列 ~20–30 分钟。一次推红要多赔一整轮。 一次做对。

---

Generated by Claude Code