# plugin-ui 0.3.1 → 0.4.0 migration note

From-predecessor note for the 0.4.0 MINOR bump (the L5 §E.1 input trio -- text-input, select, boolean-input -- gateway issue \#463; design record `.claude/deep-review/2026-10-16-classref-l5-plugin-ui-0-4-0-design.md`, whose §5 carries the owner-worded sanction for the standards motion this bump is).


# What changed

Three things moved in the train, none of them in this schema set:

1.  **The renderer** (`packages/ui-html` 0.3.0, landed ahead of this corpus in the train's PR-1): three §E.1 partials -- `render_text_input`, `render_select`, `render_boolean` -- plus their data classes, harness rows, canonical fixtures and a pattern-library page. The §E.1 table grows 11→14 rows; the manifest vocabulary never changes (a control is schema-derived from the settings schema at render time; the corpus validator consumes its own version re-stamp, nothing more).
2.  **The corpus re-stamp** (this directory): the four schemas are 0.3.1 byte-copies re-stamped 0.4.0 -- `$id`, `contract_version` consts and titles; the cross-schema `$ref` URLs re-stamp with them (the 0.3.0→0.3.1 shape, verified by sorted-key diff to be version strings only). The substance lives in the renderer, the gateway's layout-consumption arms, the SDK expander/ladder widening and this re-stamp.
3.  **The class-reference family 0.2.0** (the same train): the layout vocabulary's `control.kind` enum widens `["button","numeric","rotary"]` → `["button","numeric","rotary","text","select","boolean"]`; everything else is the re-stamp.


# The wall payment (single-serving)

The served range slides narrow: `>=0.3.1,<0.4.0` → `>=0.4.0,<0.5.0`. A pin to 0.3.1 is OUT of the carried set after this bump -- the same one-live-object rule as every plugin-ui bump (the normative bundle row lists the live code object in every carried version's row, so single-serving is the only honest posture; the manifest's policy note names the sanctioned narrow-range crossing). Re-stamp 0.3.1 pins to 0.4.0: the documents are 0.4.0-valid except `contract_version`, which the re-stamp updates; no previously-valid 0.3.1 document becomes invalid under its own frozen schema.


# Effect on consumers

- SDK `check-ui`/`check-preset`/`derive-ui`: unchanged mechanically -- the SDK ingests this corpus by sync at its next release; a 0.3.1-stamped document refuses `unsupported_version` against this validator until re-stamped.
- The gateway's layout consumption (read-only, CON-5): a layout node of kind `text`/`select`/`boolean` renders the read-only disabled span (kind's class hook + the §C.2 `no-authority` label) -- zero enabled controls, the L4 posture byte-for-byte.
- Class references: a reference whose `targets.plugin_ui` is `">=0.3.1"` stays satisfied by the active 0.4.0 (the comparator is per-parsed- operator, `>=` admits both).
- Layout blocks authored at 0.1.0: the 0.2.0 family schema pins `contract_version` 0.2.0, so an in-flight 0.1.0 block refuses `classref_layout_invalid`. Accepted deliberately (the design's §4 consequence block): the only 0.1.0-block authors are the SDK expander (re-derives at 0.2.0), the SDK test fixtures and the class-capture page data, all re-derived in this train; no external block author exists.