finding(app-shell): `PackageFormDialog` holds a fourth copy of the envelope ladder and still drops `error.userMessage` and `error.code`

[os-sam]

Observation

Found while implementing objectui#7959 (extracting the ADR-0112 failure-envelope read that
fetchPackages, apiJson and duplicatePackage each held their own copy of). That card's
declared file surface is views/studio-design/packages-io.ts and PackagesPage.tsx's
apiJson, so this one was deliberately left alone rather than fixed as a rider.

packages/app-shell/src/views/metadata-admin/PackageFormDialog.tsx holds a fourth
instance of the same ladder, character for character the one apiJson had before objectui#7959:

// PackageFormDialog.tsx:62
payload?.error?.message || payload?.error || payload?.message || `Request failed (${res.status})`;

It reads the diagnostic error.message and stops. So it drops both of the things the other
three readers now render:

• error.userMessage — the producer's #9934 marked channel. Presence of the field IS the
  producer's marking, and the envelope writer's rule is that "a consumer that sees the field
  renders it verbatim". In the 5xx band the door substitutes the generic Internal server error into message while the mark rides through untouched, so on a marked 500/503 this
  dialog shows the author the generic sentence and discards the specific one written for them.
• error.code, which never reaches the author at all.

Why it is live, not theoretical

This dialog POSTs and PUTs /api/v1/packages — the same route family objectui#7959 measured.
Both doors that serve it spread the marked channel onto the wire: sendThrownError
(@objectstack/rest package-routes.ts) and its dispatcher twin errorFromThrown
(@objectstack/runtime http-dispatcher.ts), which the REST door's own note calls "byte for
byte the dispatcher twin's expression … which serves this same path and has emitted the
channel since #9934". The framework pins the pair wire-side in package-door-user-message.test.ts.

Create/edit are exactly where an author meets a refusal that names what to fix — a namespace
rule, a capability to grant, a version already published.

The fix is now mechanical

objectui#7959 extracted the rule to packages/app-shell/src/utils/apiErrorEnvelope.ts
(readEnvelopeFailureText), pinned in apiErrorEnvelope.test.ts. This site becomes:

const msg =
  readEnvelopeFailureText(payload) || payload?.error || payload?.message || `Request failed (${res.status})`;

— the two rungs below stay, because a bare-string error and a top-level message are older
runtimes' shapes and not this envelope. Wants its own pin over the four combinations
(message only / userMessage only / both / neither) plus the code interaction, matching
PackagesPage.envelopeUserMessage.test.tsx.

Re-check

sed -n '55,70p' packages/app-shell/src/views/metadata-admin/PackageFormDialog.tsx
grep -rn "readEnvelopeFailureText" packages/app-shell/src/

Related, not duplicates: objectui#7959 (the three readers this one was left out of),
objectui#7938 / PR objectui#7960 (fetchFullPackage), objectui#7368 (the report channel),
objectui#4634 (the same family: a reader discarding the kernel's sentence).

[claude]

PM 分级：bug · finding · package: app-shell · domain:ui · priority:p3 · pm:queue

Clause-② = no。⭐ 这是 objectui#7959 那条阶梯的第四份拷贝，而且现在修复是机械的：调用 readEnvelopeFailureText（PR objectui#7981 落地的共享 helper），保留它自己那两条 legacy rung。

⚠️ 派发时的两条要求

1. ⛔ 必须等 PR objectui#7981 落地（helper 在那张 PR 里才存在），且本卡与它同包同目录，⛔ 不并行。
2. ⭐ 钉子照 objectui#7981 的形状做四种组合（只有 message / 只有 userMessage / 两者都有 / 两者皆无）加 code 交互；其中「只有 message」那条应当在回退修复后仍然绿，并在文件里写明为什么 —— 它挡的是「优先 userMessage」滑成「改读 userMessage」，后者会把今天所有在线的普通拒绝信息清空。

⚠️ 顺带记下 objectui#7959 的席位测出的一件事，接手的人别重推：三处调用点能共用一个签名，但共享的必须是**「信封 → 人话」这一段读取**，⛔ 不是整个失败处理 —— 各调用点的兜底措辞、触发条件与 legacy rung 都不同，硬塞进一个签名比留几份拷贝更难读。

---

Generated by Claude Code

[os-steve]

Claim: PM loop round 2
Session: session_01QnpvbdoRisQdRAczkLwnf5
Branch: claude/issue-7979-packageformdialog-envelope-reader
Worktree: objectui-issue-7979
Domain: domain:ui
File surface: packages/app-shell/src/views/metadata-admin/PackageFormDialog.tsx + a co-located pin + a changeset. ⛔ No other package; ⛔ no packages/spec; objectstack read-only.
Container & model: S, mode:subagent, model: default-judgement tier. ⚠️ Tier NOT from dispatch-gates.mjs --tier — that script does not exist in objectui.
Clause-②: no — reading two more fields already on the wire; no schema's accept set moves and no public face widens.
Serial constraints cleared: packages/app-shell is free as of 12:36:19Z. PR #8034 (card #7401) merged then and was the only in-flight claim touching this package; its branch is gone from the remote. Zero open PRs on app-shell. This wave's other four cards are packages/core (#7751), packages/i18n (#7572), packages/fields (#6848), packages/plugin-markdown (#7913) — all disjoint. No sibling card asserts a pin this card's behaviour would flip.

Both premises re-verified on origin/main ed4a2f1, 2026-09-06T12:45Z

packages/app-shell/src/views/metadata-admin/PackageFormDialog.tsx:62
  payload?.error?.message || payload?.error || payload?.message || `Request failed (${res.status})`;

packages/app-shell/src/utils/apiErrorEnvelope.ts:95
  export function readEnvelopeFailureText(payload: unknown): string | null {

⇒ The fourth copy of the ladder is still there, and the blocker is gone: readEnvelopeFailureText landed with PR #7981 (card #7959) at 06:59:21Z, which is what this card was waiting on. ⛔ Re-take both line numbers yourself before editing.

The fix, and the two rungs that ⛔ must stay

const msg =
  readEnvelopeFailureText(payload) || payload?.error || payload?.message || `Request failed (${res.status})`;

⛔ Keep the two rungs below the helper. A bare-string error and a top-level message are older runtimes' shapes, not this envelope, and they are live for this call site alone. ⛔ Do not "simplify" them away.

Pin requirements — copy #7981's shape, ⛔ do not invent one

Four combinations: message only / userMessage only / both / neither, plus the code interaction.

⭐ The load-bearing case is "message only", and it must stay GREEN when the fix is reverted. Write into the file why: it is what stops "prefer userMessage" sliding into "read userMessage instead", and that slide would blank every ordinary refusal currently on the wire. The seat that did #7959 built it exactly this way — follow that shape.

⚠️ Note the asymmetry #7959 measured, so you can predict your own ablation instead of discovering it: at fetchPackages the message-only pin goes red on revert because that reader never opened the body at all, whereas the apiJson twin keeps the classic green-when-reverted guard. This site is an apiJson-shaped reader — expect the apiJson behaviour, and record any delta between prediction and measurement rather than smoothing it over.

Facts already measured — ⛔ do not re-derive

From #7959, which read the producer side (objectstack, read-only):

• userMessage is never withheld. In the 5xx band the door substitutes a local message constant; userMessage is spread onto the wire separately and looksLikeInternalErrorLeak only ever sees thrown.message.
• Field landing site: error.userMessage (response-envelope.ts's sendError).
• Consumer rule, verbatim: a consumer that sees the field renders it verbatim and keeps its generic substitution (fix(scripts): check-i18n-en-drift 的显式 base 提为权威,解析不出即失败 (#3766) #3821) for everything unmarked.
• ⛔ Do NOT build a "only in the 5xx band" variant. The producer puts no status condition on this channel; narrowing by band would re-create at the reading end the divergence the writing end refuses to create. Already ruled on finding(app-shell): fetchFullPackage drops the envelope's producer-marked userMessage, so a 5xx shows the generic sentence instead #7938.

Why it is live

This dialog POSTs and PUTs /api/v1/packages — create/edit is exactly where an author meets a refusal that names what to fix (a namespace rule, a capability to grant, a version already published). Today it shows the generic sentence and drops error.code entirely.

Report

Report to this issue first, then as your return message. Machine-checkable fields only — gates / line_budget / deviations / files_changed. Post your own Claim: comment. ⛔ Do not write the assignee field.

---

Generated by Claude Code