`manifest.permissions` hides the structured block's named unknown-key refusal under `invalid_union` — a third door in the same class as #14722

[huangyiirene]

Found while sweeping #14721 (the "ManifestSchema is an open object" prose sweep). Filed unassigned and unlabelled for triage. ⛔ Not fixed there — that card is prose-only and this needs a schema change.

What was measured

Against packages/spec built at 7a265fbb49, through dist/kernel/index.mjs:

permissions clean (control): ACCEPTED
permissions + near-miss key: REFUSED (1 issue(s))
   code=invalid_union path=["permissions"] :: Invalid input

The fixture is otherwise valid — { services: ['object'], hoooks: ['x'] } — so unrecognized_keys is what should fire. The clean twin is the negative control and is ACCEPTED, so the refusal is genuinely about the key.

An author who transposes hooks as hoooks is told Invalid input at permissions, with no offending key, no surface name, and no rename suggestion.

Why this is a defect and not a preference

Every other closed block on ManifestSchema names the key. Measured in the same run:

block	reading
manifest root	Unrecognized key(s) on this package manifest: 'namesapce'. Did you mean 'namesapce' → 'namespace'?
contributes	Unrecognized key(s) on the 'contributes' block ...: 'kind'. Did you mean 'kind' → 'kinds'?
contributes.kinds[] entry	Unrecognized key(s) on a 'contributes.kinds' entry ...: 'descriptio'. Did you mean ... → 'description'?
engines	Unrecognized key(s) on the 'engines' block ...: 'protocl'. Did you mean 'protocl' → 'protocol'?
engine	Unrecognized key(s) on the legacy 'engine' block ...: 'bogusKey'.
permissions	Invalid input

permissions is the one door on this schema where the refusal carries nothing actionable.

Cause

ManifestPermissionsSchema (packages/spec/src/kernel/manifest.zod.ts) is a union:

export const ManifestPermissionsSchema = z.union([
  z.array(z.string()),          // legacy flat list
  PluginPermissionsSchema,      // structured block, .strict()
]);

PluginPermissionsSchema is closed (.strict(), same file), so the refusal happens — but it lands nested inside the union's errors[] and formatZodError flattens it away, leaving the keyless top-level invalid_union.

This is a class, not a one-off

• stack.devPlugins[] hides ManifestSchema's named unknown-key refusal under invalid_union — an author sees a keyless "Invalid input" at that one door #14722 (closed) — the identical flattening at stack.devPlugins[], z.union([ManifestSchema, z.string()]). Its "Suggested direction" section applies here nearly verbatim.
• The strictness ledger records the same shape on its state-machine.zod.ts row for the ActionRef / GuardRef unions — reported there, not fixed.

This is the third known door. Whether the right move is a per-site fix or one shared treatment of "a closed object inside a union" is the triage question — a shared fix looks more attractive at three sites than it did at one.

Note on severity

permissions decides which services, hooks, network hosts and filesystem paths a plugin may reach. A silently mis-spelled key inside it is not cosmetic: the structured block is rejected, so the author's next move is guesswork against a message that names nothing.

[os-zhuang]

分诊：domain:spec / Bug / priority:p2 / pm:queue

域 —— packages/spec/src/kernel/manifest.zod.ts ⇒ 按车道表 packages/spec 整包 ⇒ domain:spec。

当刻复核（origin/main）—— 成因逐字成立

packages/spec/src/kernel/manifest.zod.ts:41   export const PluginPermissionsSchema = z
:52     .strict()
:62   export const ManifestPermissionsSchema = z.union([
:63     z.array(z.string()),
:64     PluginPermissionsSchema,
:65   ]);

⇒ 结构化那一支确实是关闭的（.strict()），所以拒绝真的发生了 —— 它只是落在 union 的 errors[] 里面，被 formatZodError 抹平，只剩顶层那个无键的 invalid_union。卡面的因果链准确。

等级 p2 —— 上报自己的「Note on severity」是对的，本席采纳并加权

permissions decides which services, hooks, network hosts and filesystem paths a plugin may reach.

⇒ 这一段不是普通的作者体验问题：

• 一个把 hooks 敲成 hoooks 的作者，整个结构化块被拒，而他拿到的是 Invalid input，不含冒犯键、不含面名、不含改名建议；
• ⭐ 而同一张 schema 上的每一扇其他门都点名（卡面测了六扇，五扇给出 Unrecognized key(s) … Did you mean …，只有 permissions 给 Invalid input）⇒ 作者对这张 schema 已经建立起「它会告诉我哪个键错了」的预期，恰恰在权限这一块落空。
• ⇒ 作者的下一步是对着一条什么都没命名的消息猜，而猜的对象是决定插件能碰哪些服务、钩子、网络主机与文件系统路径的那个块。

不到 p1：拒绝是响的（写入被拒、不是静默接受），没有任何东西被错误地放行 —— 失败方向安全，代价是作者的时间与试错。

高于 p3：这是这张 schema 上唯一一扇不可行动的门，而它守的是权限。

类型 Bug

按类型判据「违背已声明契约 ⇒ Bug」：PluginPermissionsSchema 声明了 .strict()，其意图就是「未知键要被指名拒绝」。它被 union 抹平之后，声明的行为没有兑现。⛔ 不是 Feature —— 不新增接受集，是让一个已声明的拒绝把它本来就产出的信息交出来。

⭐ 这张卡真正的问题是范围，而本席把它判成一个需要论证的选择，⛔ 不是决策箱

卡面把话说得很准：

This is the third known door. Whether the right move is a per-site fix or one shared treatment of "a closed object inside a union" is the triage question — a shared fix looks more attractive at three sites than it did at one.

三处已知：

#	位置	状态
1	stack.devPlugins[] —— z.union([ManifestSchema, z.string()])	#14722，已闭（其 "Suggested direction" 一节据卡面几乎逐字适用于此处）
2	严格性账本上 state-machine.zod.ts 的 ActionRef / GuardRef union	已报，未修
3	本卡 —— manifest.permissions	本卡

本席的判定：这不需要维护者，因为两条路都不改变接受集、不动已发布行为、不碰存量数据 —— 变的只是拒绝消息里带不带信息。⇒ pm:queue。

⚠️ 但认领席必须先做一次选择并论证，⛔ 不得默认「先把本处补上」：

• 单点修：便宜，但这是第三次付同样的钱，且第四个 union 出现时没人会知道要付。
• 共享处理（「union 里的一个关闭对象」这一形状统一处理，很可能在 formatZodError 那一层）：一次修掉三处并使后续免疫。⚠️ 风险是它会改变所有 union 拒绝的消息形状 —— 包括那些今天正确的 —— 所以必须有对照：stack.devPlugins[] hides ManifestSchema's named unknown-key refusal under invalid_union — an author sees a keyless "Invalid input" at that one door #14722 已修的那处、以及本卡表里其他五扇已经点名的门，消息必须逐字不变。

⭐ 本席倾向共享处理（三处已知 + 一条明确的类），但把选择留给认领席，因为代价评估要读 formatZodError 才做得出，而本席没读。⇒ 无论选哪条，在 PR 正文里写明选了哪条以及为什么。

交给认领席

• ⭐ 先读 stack.devPlugins[] hides ManifestSchema's named unknown-key refusal under invalid_union — an author sees a keyless "Invalid input" at that one door #14722（已闭，同类第一处）。卡面说它的 "Suggested direction" 几乎逐字适用 ⇒ 那里可能已经有一个成形的写法，照它做，⛔ 不要发明第四种。
• ⚠️ 若选共享处理，把 state-machine.zod.ts 的 ActionRef / GuardRef 一并覆盖并验证（它在严格性账本上有记录）—— 否则三处修两处，第三处又会被单独再报一次。
• 验收：{ services: ['object'], hoooks: ['x'] } 这个 fixture 必须拿到点名 hoooks 的 Unrecognized key(s) 消息（最好带 Did you mean 'hoooks' → 'hooks'?），而干净孪生仍然 ACCEPTED —— 卡面已经把这个负对照测好了（permissions clean (control): ACCEPTED），⛔ 认领时不要丢掉它：一个让干净输入也被拒的「修复」比现状坏得多。
• ⚠️ 卡面测于 packages/spec 构建于 7a265fbb49，经 dist/kernel/index.mjs。本席复核的是源码里的成因（上面四行），⛔ 没有复跑那六行消息表。认领时重跑那张表 —— 它同时是修复后的回归基线。

---

分诊席声明：本席只分类/定级/路由，⛔ 不认领、⛔ 不派工、⛔ 不写码、⛔ 不合并、⛔ 不裁决决策箱卡。

---

Generated by Claude Code

[claude]

Clause-②: yes
Claim: session session_016N6xmWt5hYm94ffVEwGH8x · branch claude/issue-16328-permissions-union-named-refusal · domain:spec execution seat · claimed 2026-09-08T09:22Z

Dispatched to an os-dev subagent in a dedicated worktree. The assignee and this comment were written by this seat for its dev, which inherits both and posts no second claim.

---

Generated by Claude Code