The `protection` block's unknown-key refusal carries zod's bare message — no surface, no declared keys, no rename, on four authorable types

[claude]

Found while fixing #16328 (the manifest permissions block's unknown-key refusal). Filed unassigned and unlabelled for triage. Not fixed there — that card owns kernel/manifest.zod.ts only, and this is a different file reached from four other metadata types.

What was measured

Against packages/spec built from origin/main at f89812e4d, through dist/ai/index.mjs and dist/shared/index.mjs:

AgentSchema.safeParse({ name: 'a', protection: { lockk: 'system' } })

  RAW  code=unrecognized_keys path=["protection"] :: Unrecognized key: "lockk"

  FORMATTED (formatZodError):
    ✗ protection: Unrecognized key: "lockk"

lockk is one keystroke from the declared lock. The author is told the key is wrong and nothing else: no surface name, no declared-key list, and no rename suggestion.

Why this is a defect and not a preference

ProtectionSchema (packages/spec/src/shared/protection.zod.ts:63) is a bare z.object({ ... }).strict() with no error map. It is closed — the refusal is loud, nothing is silently stripped — but it never adopted the strictObject helper that the #4001 unknown-key campaign made the standard for authorable shapes, so it emits zod's own default text instead of the campaign's named message.

Every neighbouring authorable block reached from the same schemas names all three parts. Compare, measured in the same run against the manifest:

Unrecognized key(s) on the `engines` block of this package manifest: `protocl`.
Did you mean `protocl` -> `protocol`? ...

Reach

protection is declared on four schemas, three of which are registered metadata types an author writes by hand:

• ai/agent.zod.ts:374 (agent)
• ai/tool.zod.ts:204 (tool)
• ai/skill.zod.ts (skill)
• identity/position.zod.ts:127

So defineStack({ agents }), the metadata REST doors and the Studio forms all reach this refusal.

Note on the strictness ledger

docs/audits/2026-07-unknown-key-strictness-ledger.md has no row for shared/protection.zod.ts. Its one near-mention (line 501) is about a counting bug and names kernel/metadata-protection.zod.ts — a different file. So this site appears not to have been enumerated by the campaign rather than deliberately accepted; that is worth confirming at triage before treating it as a plain fix.

Suggested direction

Convert ProtectionSchema to strictObject({ surface, history }, { ... }), exactly as #16328 did for PluginPermissionsSchema. That change cannot move the accept set: strictObject is z.object(shape, { error }).strict(), and an error map is consulted only once an issue is already being raised.

⚠️ The population is not established here. This is one site found while working a neighbouring card, not a sweep. Whether other closed authorable shapes still carry zod's bare message needs its own measured count — #14722's triage already ruled that a sweep needs its own card with a measured population, so this card deliberately does not perform one.

---

Generated by Claude Code

[claude]

Evidence for triage: this card undercounts its own reach by a factor of three — 16 mount sites across 14 files, not four

domain:spec execution seat, session session_016N6xmWt5hYm94ffVEwGH8x, measured on origin/main at 2026-09-08T10:42:49Z. ⛔ Evidence only — no grade, no domain:*, no pm:* touched; this card stays bare for the triage seat.

The card lists four consumers (ai/agent.zod.ts:374, ai/tool.zod.ts:204, ai/skill.zod.ts, identity/position.zod.ts:127). PR #16846's at-tier contract review noticed a fifth (ui/app.zod.ts:1556) and said the card undercounts. ⚠️ Both are low. Enumerated:

git grep -n "protection: ProtectionSchema" origin/main -- packages/spec/src | grep -v shared/protection.zod.ts

file	line
ai/agent.zod.ts	374
ai/skill.zod.ts	418
ai/tool.zod.ts	204
automation/flow.zod.ts	917
automation/webhook.zod.ts	220
data/object.zod.ts	2374
identity/position.zod.ts	127
security/permission.zod.ts	632
system/email-template.zod.ts	136
ui/app.zod.ts	1556
ui/dashboard.zod.ts	982
ui/dataset.zod.ts	338
ui/report.zod.ts	371
ui/view.zod.ts	3810, 3961, 4356

16 mount sites in 14 files. Control: the declaring file shared/protection.zod.ts itself returns 3 hits under the neighbouring query, so the instrument fires.

Why this changes the card rather than just annotating it

As filed, this reads as "a fourth door in the same class as #16328" — a small follow-up. It is not. ProtectionSchema is mounted on object definitions, views, dashboards, datasets, reports, apps, flows, webhooks, permissions, positions, email templates, agents, tools and skills — i.e. very nearly every authorable top-level entity in the platform. Every one of them today answers an unknown key inside protection with zod's bare Unrecognized key: "lockk": no surface name, no declared-key list, no rename suggestion.

⚠️ ⛔ This is not a request to fold it into PR #16846. That review judged the separation correct, and the #14722 rule that a population sweep needs its own card is why. The point is only that the population is three times what the card states, and a grade taken off "four consumers" would be taken off a wrong number.

One measured note for whoever picks it up

⚠️ ui/view.zod.ts carries three mounts (:3810, :3961, :4356), and the third (:4356) has no .describe() while the other two do. ⛔ Locate all of them by text — this file has moved repeatedly this week.

---

Generated by Claude Code