docs(core): enumerate all eight enforced plugin keys, and declare the break

The contract review returned NOT PASSED on two text findings. Neither moves a
line of enforcement: `plugin-loader.ts`'s filter and `PluginSchema` are
byte-identical to the reviewed head.

1. The narrowing was understated by five of eight keys. `PluginSchema` declares
   nine optional keys and `validatePluginContract` excludes `version`, so the
   refusal reaches `id`, `type`, `staticPath`, `slug`, `default`, `description`,
   `author` and `homepage` — plus an explicit `null` on any of them, all eight
   being `.optional()`. The changeset, the loader's JSDoc and the
   `PLUGIN_CONTRACT_VIOLATION` vocabulary row each named only three of them, so
   an author refused `at 'author'` who greps the shipped CHANGELOG read an
   enumeration affirmatively saying their key is not enforced. All three
   carriers now enumerate the eight and the `null` behaviour, and all three
   state what is STILL accepted, which is what bounds the blast radius: unknown
   keys pass (a plain `z.object`, no `.strict()`), a version-less plugin loads,
   and `version` is excluded outright so `1.0.0-alpha.1` and `1.0.0+20230101`
   still load.

2. No `**BREAKING**` banner and no ADR-0087 disposition.
   `check-changeset-no-major.mjs` names an accept-set narrowing as the breaking
   shape and those two as the mandatory carriers during the launch window; the
   precedent on this same key (`d8024f0`) carries both. The changeset now opens
   with the banner in that shape and closes with exactly one
   `not-required (no-migration-prescription)` disposition: `PluginSchema` is
   read, not changed, no stored representation moves, and the channel that
   reaches an affected author is the refusal naming the key. The level stays
   `minor`.

No `#NNNNN` id enters the vocabulary `why` string, so the cross-package prose-id
leg of `check:doc-authoring` stays at its baseline.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ARYe3yQTQCUFm5qPYNgKaJ

Author: claude

.changeset/enforce-plugin-schema-at-kernel-use.md

@@ -2,9 +2,22 @@
 "@objectstack/core": minor
 ---
 
-`kernel.use()` now enforces the declared plugin contract. A plugin object with an **unknown `type`**, an **invalid `slug`** or an **invalid `homepage`** is refused at load instead of being stored and mounted.
+`kernel.use()` now enforces the declared plugin contract. A plugin object that `PluginSchema` (`@objectstack/spec`, `kernel/plugin.zod.ts`) refuses is refused at load instead of being stored and mounted.
 
-**This refuses input the runtime accepted before**, which is why it is not a `patch`: `PluginSchema` (`@objectstack/spec`, `kernel/plugin.zod.ts`) had zero runtime callers, so every constraint it declared beyond `name`, `init` and semver was a declaration with nothing behind it. The sharpest reading of that gap, one input and two answers: `defineStack` accepted `type: 'ui-plugin'` while `PluginSchema.safeParse` refused it — and only one of those answers was on the path a real plugin takes. Maintainer ruling of 2026-09-06 (ADR-0049 enforce-or-remove): the protocol is the baseline, the runtime aligns to it.
+**BREAKING** accept-set narrowing on a published runtime entry point, shipped as `minor` under the repo's launch-window convention for breaking changes (`scripts/check-changeset-no-major.mjs`). **This refuses input the runtime accepted before**, which is also why it is not a `patch`: `PluginSchema` had zero runtime callers, so every constraint it declared beyond `name`, `init` and semver was a declaration with nothing behind it. The sharpest reading of that gap, one input and two answers: `defineStack` accepted `type: 'ui-plugin'` while `PluginSchema.safeParse` refused it — and only one of those answers was on the path a real plugin takes. Maintainer ruling of 2026-09-06 (ADR-0049 enforce-or-remove): the protocol is the baseline, the runtime aligns to it.
+
+**Exactly what is newly refused: all EIGHT declared keys, not three.** The schema declares nine optional keys; the loader excludes `version` (below), so enforcement reaches these eight, each refused with the offending key named in the message:
+
+- **`id`** — a non-string, or the empty string (`z.string().min(1)`).
+- **`type`** — any value outside the closed set `standard`, `ui`, `driver`, `server`, `app`, `theme`, `agent`, `objectql`.
+- **`staticPath`** — a non-string.
+- **`slug`** — a non-string, or a string that does not match `/^[a-z0-9-_]+$/`.
+- **`default`** — a non-boolean.
+- **`description`** — a non-string.
+- **`author`** — a non-string. An object such as `{ name: 'x' }` is refused; the declared type is a plain string.
+- **`homepage`** — a non-string, or a string that is not a URL.
+
+**`null` is refused on every one of the eight.** These keys are `.optional()`, which admits absence and `undefined` — never an explicit `null`. A plugin object that spells "no value" as `null` on any of the eight loaded before and is refused now.
 
 **What a refusal looks like.** It travels the loader's existing plugin-load error path — no new error channel — carrying the stable code `PLUGIN_CONTRACT_VIOLATION` at the head of the message and on the error's `code` property, and naming the plugin plus the first violated key:
 
@@ -15,10 +28,14 @@ plugin contract at 'type': Invalid option: expected one of "standard"|"ui"|…
 
 A wrong `type` is therefore diagnosable at boot rather than at route mount. The code is a **boot refusal**, not wire vocabulary: it is raised before any HTTP boundary exists, and no door answers with it.
 
-**What does NOT change.**
+**What is STILL ACCEPTED — the door is not narrowed past those eight keys.** Measured on this tree, not assumed:
 
-- The plugin object is validated, never replaced. `safeParse` is read for `success` and its output discarded, because a copy destroys the prototype chain of class-based plugins — the reason `PluginLoader.toPluginMetadata` is a cast. A class-based plugin's identity, prototype and prototype methods surviving `use()` is pinned by test, not asserted in prose.
-- `PluginSchema`'s `.default('standard')` is **not** written back: a plugin declaring no `type` still loads and still stores no `type`.
-- **`version` is deliberately excluded from this enforcement.** The schema spells it `/^\d+\.\d+\.\d+$/`, which refuses the prerelease and build-metadata forms SemVer 2.0.0 defines, while the loader's own `isValidSemanticVersion` implements the full grammar and accepts them — and does so deliberately, pinned by `plugin-loader.test.ts`. Enforcing the narrower spelling would retire that capability silently, so the loader's check remains authoritative for `version` and `1.0.0-alpha.1` / `1.0.0+20230101` still load. Reconciling the two spellings is spec work, tracked separately.
+- **Unknown keys still pass.** `PluginSchema` is a plain `z.object` with **no `.strict()`** — the strip posture — and the parse output is discarded, so a valid plugin carrying four keys the schema never declares loads, and is stored as the very object that was passed in with all of its keys intact. A plugin is refused for what it says about a **declared** key, never for saying something extra.
+- **A version-less plugin still loads**, exactly as before.
+- **A plugin declaring no `type` still loads and still stores no `type`**: `PluginSchema`'s `.default('standard')` is **not** written back.
+- **A class-based plugin keeps its identity, its prototype and its prototype methods.** The plugin object is validated, never replaced: `safeParse` is read for `success` and its output discarded, because a copy destroys the prototype chain of class-based plugins — the reason `PluginLoader.toPluginMetadata` is a cast. That survival is pinned by test, not asserted in prose.
+- **`version` is excluded from this enforcement entirely**, so `1.0.0-alpha.1` and `1.0.0+20230101` still load. The schema spells `version` as `/^\d+\.\d+\.\d+$/`, which refuses the prerelease and build-metadata forms SemVer 2.0.0 defines, while the loader's own `isValidSemanticVersion` implements the full grammar and accepts them — deliberately, pinned by `plugin-loader.test.ts`. Enforcing the narrower spelling would retire that capability silently, so the loader's check remains authoritative for `version`. Reconciling the two spellings is spec work, tracked separately.
 
 **Blast radius, measured rather than assumed.** Every in-repo plugin object declares a `type` inside the closed set (`standard` ×62, `server` ×2, `driver` ×2, `objectql`, `app`), and the repo contains no producer of `slug` or `homepage` on a plugin object at all — so no in-repo plugin changes behaviour. Externally authored plugins are the population this reaches, and they are exactly the population that never met the compile-time `Plugin.type` union either.
+
+<!-- adr-0087: not-required (no-migration-prescription) An accept-set narrowing performed entirely at the runtime boot path: `PluginSchema` is READ by `kernel.use()`, not changed. No metadata key, spec symbol, Zod schema, object definition or stored representation is added, removed or given a different name, so `objectstack migrate meta` has nothing to visit and there is no tombstone to mint. Stored metadata is untouched; what moves is which plugin OBJECTS a boot accepts. The channel that reaches an affected plugin author is the refusal itself, which names the offending key at `kernel.use()` and is more precise than a ledger line — and which value a formerly-refused key should carry is authoring intent no ledger entry can decide. -->

packages/core/src/plugin-loader.ts

@@ -425,6 +425,36 @@ export class PluginLoader {
      * mounted routes. A wrong `type` surfaced (if at all) at route mount; it
      * now surfaces here, named, at `kernel.use()`.
      *
+     * ## What this refuses: the EIGHT declared keys, and `null` on any of them
+     *
+     * `PluginSchema` declares nine optional keys; the filter below drops
+     * `version` (see below), so the accept-set narrowing this method
+     * performs covers exactly these eight, each reported as `at '<key>'`:
+     *
+     * - `id` — a non-string, or the empty string (`z.string().min(1)`).
+     * - `type` — outside the closed set `'standard'` + `CORE_PLUGIN_TYPES`.
+     * - `staticPath` — a non-string.
+     * - `slug` — a non-string, or not matching `/^[a-z0-9-_]+$/`.
+     * - `default` — a non-boolean.
+     * - `description` — a non-string.
+     * - `author` — a non-string; an object such as `{ name }` is refused.
+     * - `homepage` — a non-string, or a string that is not a URL.
+     *
+     * All eight are `.optional()`, which admits absence and `undefined` but
+     * never an explicit `null` — so `null` on any of the eight is refused too.
+     *
+     * ⛔ ENUMERATE ALL EIGHT wherever this is restated. The changeset ships to
+     * consumers as `CHANGELOG.md` and is what an upgrading author greps after
+     * the refusal, so a shorter enumeration there does not merely omit keys —
+     * it tells an author refused `at 'author'` that their key is not enforced.
+     * This comment, the changeset and the `PLUGIN_CONTRACT_VIOLATION` row in
+     * `dispatcher-error-vocabulary.ts` are the three places that restate it.
+     *
+     * What this does NOT refuse, which is what bounds the narrowing: UNKNOWN
+     * keys. `PluginSchema` is a plain `z.object` with no `.strict()` — the
+     * strip posture — and the parse output is discarded here, so a plugin
+     * carrying keys the schema never declares still loads, stored verbatim.
+     *
      * ## ⛔ safeParse for VALIDATION ONLY — the parse output is discarded
      *
      * The returned object is a COPY, and {@link toPluginMetadata} exists
@@ -451,10 +481,10 @@ export class PluginLoader {
      *
      * So enforcing the schema's `version` here would not enforce the protocol —
      * it would RETIRE a pinned capability, silently, under a card that ruled on
-     * `type`. The ruling's own changeset note enumerates what this refuses:
-     * an unknown `type`, an invalid `slug`, an invalid `homepage`. Version is
-     * not in it, and the version check that already runs is the wider, correct
-     * one. Reconciling the two spellings belongs in `packages/spec` beside
+     * `type`. Version is not among the eight keys enumerated above, and the
+     * version check that already runs is the wider, correct one: a version-less
+     * plugin loads, and so do `1.0.0-alpha.1` and `1.0.0+20230101`.
+     * Reconciling the two spellings belongs in `packages/spec` beside
      * #16334; until then this exclusion is declared here rather than performed
      * by leaving the disagreement unmeasured.
      */

packages/runtime/src/dispatcher-error-vocabulary.ts

@@ -763,7 +763,11 @@ export const UNREGISTERED_CODE_SITES: readonly UnregisteredCodeSite[] = [
         verdict: 'boot-refusal',
         why:
             'Raised by `PluginLoader.validatePluginContract` when a plugin object does not satisfy the '
-            + 'declared `PluginSchema` — an unknown `type`, an invalid `slug`, an invalid `homepage`. It is '
+            + 'declared `PluginSchema` on any of the EIGHT keys that enforcement covers — `id`, `type`, '
+            + '`staticPath`, `slug`, `default`, `description`, `author`, `homepage` — including an explicit '
+            + '`null` on any of them, since all eight are `.optional()` and admit absence but not `null`. '
+            + '`version` is excluded from the enforcement, and unknown keys are not refused at all (the '
+            + 'schema carries no `.strict()`), so the narrowing stops at those eight. It is '
             + 'raised while the kernel is still registering plugins, before bootstrap and therefore before '
             + 'any HTTP boundary exists: `ObjectKernel.use()` re-wraps it into a fresh `Error` that the host '
             + 'rethrows and the process aborts on, so no door can answer with it and no door can demote it. '