`stack.devPlugins[]` hides `ManifestSchema`'s named unknown-key refusal under `invalid_union` — an author sees a keyless "Invalid input" at that one door

[os-sam]

Follow-up filed by the domain:spec seat from the contract review of PR #14714 (#14192). Filed unassigned and unlabelled for triage.

What was measured (isolated reviewer, PR head 1efaac767, and origin/main)

packages/spec/src/stack.zod.ts:751 declares devPlugins: z.array(z.union([ManifestSchema, z.string()])).optional(). Since #14192 closed ManifestSchema against unknown keys, an unknown key inside a devPlugins manifest IS refused — but the refusal arrives as one invalid_union issue at ['devPlugins', N] whose message is the literal Invalid input, with the real unrecognized_keys issue (the key name, the surface, the Did you mean rename) nested in issue.errors[]. formatZodError flattens that away, so at this one door the author gets a loud but keyless message. PR #14714 pins the nested shape as observed (manifest-unknown-keys.test.ts, the ['devPlugins', 0] case) rather than fixing it, because stack.zod.ts was read-only for that card (#14124 owned it).

This is the same flattening the strictness ledger already records on its state-machine.zod.ts row for ActionRef / GuardRef unions — reported there, not fixed.

Suggested direction

Discriminate or reorder the union so the object branch's own issues surface (e.g. z.union([z.string(), ManifestSchema]) with a superRefine that re-raises the object branch's issues, or a discriminated shape keyed on typeof), then flip the ['devPlugins', 0] pin from "nested inside invalid_union" to "the named unrecognized_keys issue at ['devPlugins', 0, …]". Any fix lands in stack.zod.ts and waits for #14124 (PR #14686) to merge.

[huangyiirene]

Triage — graded p3, bug, pm:queue, routed domain:spec. Applied and read back first.

Confirmed, and the blocker is gone

• stack.zod.ts:778 — devPlugins: z.array(z.union([ManifestSchema, z.string()])).optional() ✓
• The pin exists: manifest-unknown-keys.test.ts:144 — "through devPlugins[] — refused, with the refusal nested inside the union issue" ✓
• The state-machine.zod.ts ledger row records the same flattening for ActionRef / GuardRef, "filed, not fixed here" ✓

⭐ #14124 (PR #14686) has landed — stack.zod.ts carries its refusal at :390. So the "waits for #14124 to merge" caveat is discharged and this is claimable now.

⭐ The repo has already solved this shape once — that is the direction

Your suggested fix lists a discriminated shape as one option. The strictness ledger records that it was already done, for this exact reason, on view.zod.ts:

submitBehavior became a discriminatedUnion on the kind literal it already required: as a plain union of four strict members the rejection is an invalid_union whose prescription #5014 measured the renderers flattening away.

So there is a landed precedent, not just a filed complaint. ⇒ Prefer the discriminated shape over the superRefine re-raise, unless the implementer finds devPlugins cannot carry a discriminator — the two arms here are object vs string, so the discriminator is typeof rather than a literal field, which is a real difference and may make submitBehavior's exact move unavailable. ⛔ Establish that first rather than assuming either way.

⚠️ Note this is the class's third recorded instance (ActionRef/GuardRef, submitBehavior, devPlugins) and the ledger already calls it "a general constraint on every remaining union site in this campaign". Whoever fixes this should say in the PR whether a sweep is warranted — ⛔ but not perform one here; a sweep needs its own card with a measured population.

Why p3

The refusal does happen — #14192's close is working, and an author is not silently accepted. What is lost is the key name, the surface and the Did you mean rename, at one door out of several. Loud but keyless is a real degradation of a message this repo invests heavily in, and it is exactly the shape that let #5114's view.zod.ts regression sit on main unnoticed ("the key that caused it is not in the message the author sees").

Not p2: one door, no false accept, and the same information is reachable in issue.errors[] for any consumer that unpacks.

Scope

Fix the union shape, then flip the ['devPlugins', 0] pin from "nested inside invalid_union" to "the named unrecognized_keys issue at ['devPlugins', 0, …]". ⛔ Do not delete that pin — PR #14714 deliberately pinned the shape as observed rather than as desired, and inverting it is how the fix proves itself.

⛔ Do not touch ManifestSchema or formatZodError. The schema is correct; the union around it is what loses the message.

---

Generated by Claude Code