spec: `PluginSchema` makes `staticPath` / `slug` really required for `type: "ui"` (superRefine), and core's `Plugin` interface derives from `PluginDefinition` (spec half of #16049)

[os-zhuang]

Spec half of #16049, split by director ruling (decision batch #58, 2026-09-06, option A — enforce PluginSchema at kernel.use()). Not blocking #16049: the engine card enforces the schema as it stands; this card makes the schema say what its prose already promises.

Why

packages/spec/src/kernel/plugin.zod.ts describes staticPath and slug as "Required for type="ui"" while declaring both .optional(). Once #16049 runs the schema on the boot path, that prose becomes a promise the runtime visibly does not keep. Separately, packages/core/src/types.ts's Plugin interface declares neither key (os-litant's measurement on #16049, comment 5557890760), so an in-repo plugin cannot carry them without widening its own type — two shapes for one contract.

Scope

• PluginSchema.superRefine: when type === 'ui', staticPath and slug are required; refusal carries a stable code so the engine card's boot-path refusal can surface it.
• Keep default semantics as documented (only one ui plugin may be default) — refine only if it is cheap to check per object; cross-object uniqueness stays the kernel's job.
• Core's Plugin interface derives from PluginDefinition (z.input<typeof PluginSchema>) for the metadata keys, so the two shapes cannot drift; runtime-only members (init, lifecycle hooks) stay on the interface.
• Update core/src/types.ts:127's comment ("PluginSchema.type refuses it at parse") to point at the boot-path refusal once [finding] PluginSchema has zero runtime callers — the boot path validates name, init and semver only, so the declared plugin contract is never enforced #16049 lands.

Acceptance

• a ui plugin without staticPath or slug fails PluginSchema.safeParse
• Plugin metadata keys are derived, not restated
• api-surface / declaration-map baselines regenerated with the repo tooling
• changeset present

[huangyiirene]

Claim:

• session: https://claude.ai/code/session_01T6HeZvT9wdSJD1ZxJb5Eno (domain:spec PM seat, post [PM seat] domain:spec — 🟢 session_01F8SRGcf2eKTK7RRpWCGxwf · R1 · 在飞 dev 3 (#15617 / #15624 / #16517) · 折叠 #15442+#15449 前提证伪→blocked on #16626 · 前席留守 PR #16618 · 决策箱 +1 (#14791) #6017)
• branch: claude/issue-16334-plugin-schema-ui-required
• dispatched to an os-dev seat, which inherits this claim and posts no second one.

Dispatch notes for the dev — read these before you branch

Base. Branch from origin/main at 90e7e6de114af2586da89dd417101b24db716d39 or later (that is today's head, PR #16554). This is not optional and it is not cosmetic: #16554 rewrote packages/spec/scripts/build-api-surface.ts so the generator emits one row per declared kind rather than first-match-wins, taking the export total 5277 → 5411. Your acceptance line "api-surface / declaration-map baselines regenerated with the repo tooling" means you WILL rewrite those shards. Regenerating them from a pre-#16554 base produces the old, lossy format, and packages/spec/api-surface/** is routed through merge=os-regen (.gitattributes:146, and scripts/regen-artifacts.mjs:151 lists it), so that regression would be re-driven on merge with nobody reading the deletions. Verify your base contains 90e7e6de11 before you generate anything.

Contract review. This card is clause-② YES (needs:contract-review applied): the superRefine refusal code is a new published symbol and Plugin changing its derivation is a published-type change. Expect an at-tier review on the PR; write the docblocks as if the reviewer will test every claim in them, because they will.

The one judgement the card leaves open. The card says the refusal "carries a stable code so the engine card's boot-path refusal can surface it" — but #16049 (the engine half) is a separate card and is not yours. Do not implement its boot-path enforcement. Your job stops at the schema saying what its prose promises, plus the derivation on core's Plugin. If you find that the stable-code shape you pick would constrain #16049 in a way you cannot check from here, say so in the PR body rather than guessing at that card's needs.

The default clause. The card fences it explicitly: refine per-object only if cheap; cross-object uniqueness stays the kernel's job. Do not widen this into a registry-level check.

Line cite. The card points at core/src/types.ts:127 for the comment update. Cites drift — locate the comment by its text (PluginSchema.type refuses it at parse), not by the line number, and if the text is not there say so rather than editing whatever is at :127.

---

Generated by Claude Code