`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

[zhuangjianguo]

Claim: PM loop, domain:spec seat (seat post #6017), R1 of this shift
Session: session_0174WZTU6XcFcS7g2kykC53i (GitHub zhuangjianguo)
Branch: claude/issue-14722-dev-plugins-union-refusal
Worktree: objectstack-issue-14722
Domain: domain:spec
File surface: packages/spec/src/stack.zod.ts — the devPlugins declaration only (:780 on origin/main 9786d39: z.array(z.union([ManifestSchema, z.string()])).optional()); ⛔ ManifestSchema and formatZodError untouched · packages/spec/src/kernel/manifest-unknown-keys.test.ts:144 — the ['devPlugins', 0] pin FLIPPED from "nested inside invalid_union" to "the named unrecognized_keys issue at ['devPlugins', 0, …]" (⛔ never deleted) · the strictness ledger prose only if it records this door (dev reads the state-machine.zod.ts row that already names the class; a new row is not owed unless the ledger's own convention says so) · generated references only if a describe text moves · .changeset/*.md (@objectstack/spec patch — an error-shape fix; the accept set does not move). Stop on breach; explain in the report.
Container & model: S in lines, M in judgment (the discriminator is typeof object vs string, not a literal field — whether the submitBehavior precedent's exact move is available is the first thing to establish), mode:subagent, model: opus. node scripts/pm/dispatch-gates.mjs --tier packages/spec/src/stack.zod.ts at 9786d39 (15:40Z): "no path-derived mandate" + "Clause ② SUSPECT surface — a hint, not a verdict" (packages/spec/src/**).
Clause-②: no — the same inputs are accepted and refused before and after; only the issue shape changes (the object branch's own unrecognized_keys issue surfaces instead of a keyless invalid_union). The path limb hits at enqueue regardless: the dev hangs needs:contract-review on the draft PR with the delivered diff, this seat mirrors it onto the card and reviews in-seat at tier (fuse read 15:29Z: claude-fable-5-1) before any ready flip.
Serial constraints cleared: open-PR file scan at 15:38Z (22 open PRs, file lists read via REST) — none touches stack.zod.ts or manifest-unknown-keys.test.ts; stack.zod.ts last changed by 35dffeac (#14854, merged 2026-09-03T09:27Z) ⇒ same-day churn line carried in the dispatch; fold-or-serial answered for the two queued siblings on the same file: #14847 (composeStacks re-merges bound actions — a different defect shape, ⛔ not foldable) and #14873 (two stale comments naming the deleted actionObjectKey — docs, different region) both wait SERIAL behind this card; H17 index: no row names stack.zod.ts.

Decision re-read (all comments read, one — triage 5517394178): the direction is the landed submitBehavior precedent (discriminated shape) unless the typeof discriminator makes it unavailable — establish first, not assume; the pin flips, never deleted; ⛔ no sweep of the other union sites here (say in the PR whether one is warranted). Premise re-read on origin/main 9786d39 (15:40Z): the union at stack.zod.ts:780 and the pin at manifest-unknown-keys.test.ts:144 both present verbatim; #14124's blocker discharged (PR #14686 landed 279431e7). Premise holds.

---

Generated by Claude Code

[zhuangjianguo]

Dispatch (R1 of this shift, 2026-09-03T16:05Z) — domain:spec seat, session_0174WZTU6XcFcS7g2kykC53i, seat post #6017. mode:subagent, model: opus, size S/M, Clause ② no (path limb hits at enqueue ⇒ in-seat review at tier before ready). The dev leaves its own Claim: comment below (session + branch + Clause-②: no + its complete file surface); the assignee stays the PM's.

Dispatch text handed to the dev, in brief (triage 5517394178's scope, fences and direction are quoted verbatim and marked non-renegotiable):

• Fix the devPlugins union shape in stack.zod.ts so the object branch's own unrecognized_keys issue (key name, surface, rename) surfaces at ['devPlugins', N, …]; flip the manifest-unknown-keys.test.ts:144 pin (⛔ never delete it); ⛔ ManifestSchema and formatZodError untouched; accept set unchanged and pinned with positive controls; the discriminated-shape precedent (submitBehavior) preferred only if a typeof discriminator is available — establish first.
• Hypotheses to measure: H1 the zod-4 mechanism (arm order / re-raise / typeof routing — measured against the flipped pin, losers reported); H2 whether the strictness ledger owes a stack.zod.ts sentence (counts file regenerated, never hand-edited); H3 no reference page moves unless a describe changes; H4 changeset patch.
• Same-day churn line carried (35dffeac, feat(spec): composeStacks refuses two stacks whose actions resolve to one scope-qualified runtime key #14854, 09:27Z); siblings composeStacks re-merges bound standalone actions that defineStack already copied into their objects — every bound action appears twice in the composed object's actions #14847 / [finding] Two packages/spec/src/stack.zod.ts comments name the deleted actionObjectKey as the LIVE registration-key reader — the two sites #14669's face did not reach #14873 wait serial behind this card; the sweep question is answered in the PR body, not performed.
• Landing: draft PR with Fixes #14722 + needs:contract-review on the PR in the same stroke (the seat mirrors it onto the card); ⛔ no ready flip.

---

Generated by Claude Code