feat(spec): retire record:highlights highlight-field icon — advertised on six surfaces, drawn by nothing (#10054, ADR-0049) (#10910)

* feat(spec): retire record:highlights highlight-field icon — advertised on six surfaces, drawn by nothing (#10054, ADR-0049)

Strict deletion + guidance prescription at the union's object arm (strictObject
route, the data/Metric:filters precedent — no retiredKey tombstone); the two
advertising describes corrected; ADR-0087 registration (retired-key entry
ui/RecordHighlightsField:icon, D2 conversion record-highlights-field-icon-removed,
step-18 chain); packages/lint entry-shape prose corrected; pin flips + refusal
pins through the zod-4 union collapse; regenerated reference docs; minor
changeset per the launch-window convention.

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

* chore: adr-0087 disposition marker on the changeset (#10054)

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

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: Elon Musk

.changeset/record-highlights-icon-retired.md

@@ -0,0 +1,79 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec): retire `record:highlights` highlight-field `icon` — advertised on six surfaces, drawn by nothing (#10054, ADR-0049)
+
+<!-- adr-0087: registered record-highlights-field-icon-removed -->
+
+**BREAKING** accept-set narrowing, landing after the v17.0.0 cut (the lockstep
+launch-window convention ships it as `minor`; the migration prescription is
+registered under protocol major 18, where `os migrate meta` users will look).
+
+`icon` on the object arm of `RecordHighlightsField` (`fields: [{ name, label?,
+icon?, … }]` on a `record:highlights` component) was a real authoring surface
+advertised on six author-facing surfaces — the union's own describe, the
+`fields` describe, the lint entry-shape prose, the reference docs, and
+objectui's input description — with ZERO read points, measured at the
+2026-08-20 census in every direction: objectui's renderer normalizes the
+authored object and carries `icon: f?.icon` into `HeaderHighlight`, whose chip
+has no icon slot (its only `icon` occurrence is a button `size="icon"`); the
+key is structurally unable to travel `useRegisterHighlightFields`, which
+registers `names: string[]`; the Studio block designer publishes the field
+list as a `string[]` input, so the key was never designer-publishable; and
+every in-tree `record:highlights` producer authors bare string arrays. So an
+authored `icon` parsed clean and was drawn by nothing — the #8691
+reference-rail-`icon` shape, on the highlight chip.
+
+**What is refused:** `icon` on an object-form highlight field. The arm is
+`strictObject`, so the key is deleted from the shape and the unknown-key
+rejection carries the retirement prescription via the arm's `guidance` entry
+(fully-qualified key, why it was inert, the no-replacement guidance, the
+`os migrate meta` pointer) — surfaced through the zod-4 union collapse by
+`packages/lint/src/zod-issue-format.ts`'s arm unpacking.
+
+**What stays accepted:** bare-string entries and `{name, label?, type?,
+readonly?}` objects parse byte-identically. `readonly` behaviour is untouched
+— it is the arm's one enforced key (#5176, HeaderHighlight's inline-edit
+gate). There is no replacement for `icon`: the highlight chip renders label
+and value only.
+
+The retirement kit:
+
+- strict deletion + `guidance` prescription at the schema
+  (`packages/spec/src/ui/component.zod.ts`); the two advertising describes
+  (the union's and `RecordHighlightsProps.fields`') no longer spell the key
+- ADR-0087 registration: retired-key entry `ui/RecordHighlightsField:icon` and
+  the D2 conversion `record-highlights-field-icon-removed` (protocol 18),
+  wired into the step-18 chain — `os migrate meta --from 17` strips the key
+  from the object entries of every `record:highlights` `fields[]` (pure
+  lossless delete; it never had an effect to lose)
+- pin tests (`component.test.ts` — the old parse-survival pin respells to the
+  surviving surface; a refusal pin asserts the named `unrecognized_keys`
+  rejection and its prescription through the union collapse)
+- generated baselines/docs follow the schema (spec-changes, upgrade guide,
+  reference docs); `packages/lint`'s entry-shape prose corrected
+- objectui's plugin-detail input-description advertisement is cross-repo and
+  follows on its own card
+
+## FROM → TO
+
+```ts
+// before — parsed green; the renderer normalized `icon` into a chip with no
+// icon slot, so the strip rendered identically with or without it
+{
+  type: 'record:highlights',
+  properties: {
+    fields: ['status', { name: 'budget', label: 'Budget', icon: 'dollar-sign' }],
+  },
+}
+
+// after — delete the key; nothing replaces it (the chip renders label and
+// value only)
+{
+  type: 'record:highlights',
+  properties: {
+    fields: ['status', { name: 'budget', label: 'Budget' }],
+  },
+}
+```

content/docs/references/ui/component.mdx

@@ -551,7 +551,7 @@ const result = AIChatWindowProps.parse(data);
 
 ## RecordHighlightsField
 
-Highlight field: bare name, or `{name,label?,icon?,type?,readonly?}`
+Highlight field: bare name, or `{name,label?,type?,readonly?}`
 
 ### Union Options
 
@@ -571,7 +571,6 @@ Type: `string`
 | :--- | :--- | :--- | :--- |
 | **name** | `string` | ✅ | Field name on the record |
 | **label** | `string` | optional | Display label (overrides schema label) |
-| **icon** | `string` | optional | Icon name (lucide icon key) |
 | **type** | `string` | optional | Override cell renderer type (rare) |
 | **readonly** | `boolean` | optional | Render this chip read-only — suppresses inline editing on the highlight card. Use for hook/automation-maintained columns that must not be hand-edited from the record header. |
 
@@ -586,7 +585,7 @@ Type: `string`
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **fields** | `(string \| { name: string; label?: string; icon?: string; type?: string; … })[]` | ✅ | Key fields to highlight (1-7 fields max, typically displayed as prominent cards). Each item may be a bare field name or `{name, label?, icon?, type?, readonly?}` for inline overrides. |
+| **fields** | `(string \| { name: string; label?: string; type?: string; readonly?: boolean })[]` | ✅ | Key fields to highlight (1-7 fields max, typically displayed as prominent cards). Each item may be a bare field name or `{name, label?, type?, readonly?}` for inline overrides. |
 | **layout** | `Enum<'horizontal' \| 'vertical'>` | optional (default: `"horizontal"`) | Layout orientation for highlight fields |
 | **aria** | `{ ariaLabel?: string \| Record<string, string>; ariaDescribedBy?: string; role?: string }` | optional | ARIA accessibility attributes |
 

packages/lint/src/zod-issue-format.ts

@@ -22,7 +22,7 @@
  *    exist to replace. `aggregate.groupBy` is a union (`ChartGroupBySchema` —
  *    bare field name or `{ field, dateGranularity?, alias? }`) and so is
  *    `RecordHighlightsProps.fields[]` (`RecordHighlightsField` — bare field
- *    name or `{ name, label?, icon?, type?, readonly? }`), so this is the
+ *    name or `{ name, label?, type?, readonly? }`), so this is the
  *    common path on both surfaces. **As of #5583 it is also the only thing
  *    carrying a STRICT rejection out of a union arm**: `ChartGroupBySchema`'s
  *    object arm is a `strictObject` now, and the `unrecognized_keys` it raises

packages/spec/src/conversions/registry.ts

@@ -7256,6 +7256,150 @@ const metricFiltersRemoved: MetadataConversion = {
   },
 };
 
+/**
+ * `record:highlights` highlight-field `icon` — a declared, advertised key with
+ * zero read points (#10054, ADR-0049 enforce-or-remove; maintainer ruling
+ * 2026-08-21, executing the 2026-08-20 census verdict).
+ *
+ * The dead-end is complete in every direction the census measured: objectui's
+ * renderer normalizes the authored object and carries `icon: f?.icon` into
+ * `HeaderHighlight`, whose chip has NO icon slot (its only `icon` occurrence
+ * is a button `size="icon"`); the key is structurally unable to travel
+ * `useRegisterHighlightFields`, which registers `names: string[]`; and the
+ * Studio block designer publishes the field list as a `string[]` input, so the
+ * key was never designer-publishable either. Meanwhile six author-facing
+ * surfaces advertised it — the union's own describe, the `fields` describe,
+ * the lint entry-shape prose, the reference docs, and objectui's input
+ * description. The exact #8691 reference-rail-`icon` shape, on the highlight
+ * chip.
+ *
+ * **A pure lossless delete.** The key never had an effect to lose: the chip
+ * renders label and value only, so there is no rewrite target — deleting the
+ * key preserves observed behaviour exactly.
+ *
+ * ⚠️ Scoped by component `type` AND by entry shape: `icon` is live on half a
+ * dozen other components (`element:button`, header actions, …), and the
+ * bare-string entries of the same `fields` array are not carriers — only the
+ * OBJECT entries of a `record:highlights` `fields[]` are touched. The
+ * neighbouring `readonly` key is LIVE (#5176 — HeaderHighlight's inline-edit
+ * gate reads it) and survives untouched.
+ */
+const recordHighlightsFieldIconRemoved: MetadataConversion = {
+  id: 'record-highlights-field-icon-removed',
+  toMajor: 18,
+  retiredFromLoadPath: true,
+  surface: 'page.component.record:highlights.fields[].icon',
+  summary:
+    "record:highlights highlight-field key 'icon' removed (#10054, ADR-0049 — no render path: "
+    + 'the highlight chip has no icon slot, the register hook carries field names only, and the '
+    + 'Studio designer publishes the field list as plain strings, so an authored icon was '
+    + 'accepted and drawn by nothing)',
+  apply(stack, emit) {
+    return mapPageComponents(stack, (component, path) => {
+      if (component.type !== 'record:highlights') return component;
+      const properties = component.properties;
+      if (!isDict(properties)) return component;
+      const fields = properties.fields;
+      if (!Array.isArray(fields)) return component;
+      let touched = false;
+      const nextFields = fields.map((entry, i) => {
+        // Bare-string entries are not carriers — untouched, same reference.
+        if (!isDict(entry)) return entry;
+        const stripped = stripKeys(entry, ['icon'], emit, `${path}.properties.fields[${i}]`);
+        if (stripped !== entry) touched = true;
+        return stripped;
+      });
+      if (!touched) return component;
+      return { ...component, properties: { ...properties, fields: nextFields } };
+    });
+  },
+  fixture: {
+    before: {
+      pages: [
+        {
+          name: 'project_detail',
+          regions: [
+            {
+              name: 'main',
+              components: [
+                {
+                  type: 'record:highlights',
+                  properties: {
+                    fields: [
+                      // Bare-string entry — the shape every in-tree producer
+                      // authors; not a carrier, rides through untouched.
+                      'status',
+                      // The retired shape: an object entry carrying `icon`.
+                      { name: 'budget', label: 'Budget', icon: 'dollar-sign' },
+                      // The LIVE neighbour keys survive — `readonly` is the
+                      // #5176 enforced key, `type` the renderer override.
+                      { name: 'health', type: 'number', readonly: true },
+                    ],
+                  },
+                },
+                // `icon` on a component that is not record:highlights — live
+                // there, and not this entry's key.
+                { type: 'element:button', properties: { label: 'Open', icon: 'external-link' } },
+              ],
+            },
+          ],
+        },
+        // The named-slot shape (#6776 reach): a highlights strip authored into
+        // a slotted record page's `highlights` slot.
+        {
+          name: 'task_detail',
+          kind: 'slotted',
+          regions: [],
+          slots: {
+            highlights: {
+              type: 'record:highlights',
+              properties: { fields: [{ name: 'priority', icon: 'flag' }] },
+            },
+          },
+        },
+      ],
+    },
+    after: {
+      pages: [
+        {
+          name: 'project_detail',
+          regions: [
+            {
+              name: 'main',
+              components: [
+                {
+                  type: 'record:highlights',
+                  properties: {
+                    fields: [
+                      'status',
+                      { name: 'budget', label: 'Budget' },
+                      { name: 'health', type: 'number', readonly: true },
+                    ],
+                  },
+                },
+                { type: 'element:button', properties: { label: 'Open', icon: 'external-link' } },
+              ],
+            },
+          ],
+        },
+        {
+          name: 'task_detail',
+          kind: 'slotted',
+          regions: [],
+          slots: {
+            highlights: {
+              type: 'record:highlights',
+              properties: { fields: [{ name: 'priority' }] },
+            },
+          },
+        },
+      ],
+    },
+    // Two notices: the region-level object entry and the slotted one.
+    expectedNotices: 2,
+  },
+};
+
 export const CONVERSIONS_BY_MAJOR: Readonly<Record<number, readonly MetadataConversion[]>> = {
   11: [flowNodeHttpRename, pageKindJsxToHtml, flowNodeFilterAlias, objectCompactLayoutRename],
   13: [stackRolesToPositions, owdLegacyReadAliases, sharingRecipientRoleToPosition],
@@ -7335,6 +7479,7 @@ export const CONVERSIONS_BY_MAJOR: Readonly<Record<number, readonly MetadataConv
     elementFilterRemoved,
     fieldColumnListsCanonicalized,
     metricFiltersRemoved,
+    recordHighlightsFieldIconRemoved,
   ],
 };
 

packages/spec/src/migrations/entries/retired-keys/18.ui__RecordHighlightsField__icon.ts

@@ -0,0 +1,33 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+// #10054 — ADR-0049 enforce-or-remove (maintainer ruling 2026-08-21, executing
+// the 2026-08-20 census verdict). `icon` on the object arm of
+// `RecordHighlightsField` was declared, described (`Icon name (lucide icon
+// key)`), and advertised on six author-facing surfaces — with ZERO read
+// points, measured in every direction: objectui's renderer normalizes the
+// authored object and carries `icon: f?.icon` into `HeaderHighlight`, whose
+// chip has NO icon slot (its only `icon` occurrence is a button
+// `size="icon"`); the key is structurally unable to travel
+// `useRegisterHighlightFields`, which registers `names: string[]`; the Studio
+// block designer publishes the field list as a `string[]` input, so the key
+// was never designer-publishable; and all in-tree `record:highlights`
+// producers author bare string arrays. The exact shape #8691 recorded for the
+// reference-rail `icon`: declared and normalized, drawn by nothing — an
+// authored value parsed clean and cost the author silently. The neighbouring
+// `readonly` key is LIVE (#5176, HeaderHighlight's inline-edit gate) and is
+// untouched.
+//
+// Registered under 18, not 17: v17.0.0 was cut before this landed, so the
+// removal ships on the 17.x line (launch-window convention: accept-set
+// narrowings ride minor releases) and the prescription lives at the major
+// boundary where `migrate meta` users look (the #8495 / PR #8666 precedent).
+// The object arm is `strictObject`, so the route is strict deletion + a
+// `guidance` entry carrying the prescription (no retiredKey tombstone — the
+// key is out of the walked shape entirely, and the refusal is the arm's own
+// named `unrecognized_keys`, unpacked through the zod-4 union collapse by
+// `packages/lint/src/zod-issue-format.ts`; the `data/Metric:filters` route).
+// Sources are rewritten by the D2 conversion
+// `record-highlights-field-icon-removed`, which strips the key from the object
+// entries of every `record:highlights` `fields[]` (pure lossless delete — the
+// chip renders label and value only, so the key never had an effect to lose).
+export const entry = 'ui/RecordHighlightsField:icon';

packages/spec/src/migrations/registry.ts

@@ -5111,14 +5111,26 @@ const step18: MigrationStep = {
     'objectui\'s ThemeEngine/ThemeContext and their unit tests are retained. Semantic ' +
     'rather than mechanical: an authored palette has no lossless target (N themes vs ' +
     'M apps is a judgment), so the entry prescribes the hand move instead of deleting ' +
-    'authored content silently.',
+    'authored content silently. ' +
+    'It also retires the `record:highlights` highlight-field `icon` (#10054, ADR-0049 ' +
+    'enforce-or-remove; maintainer ruling 2026-08-21, executing the 2026-08-20 census ' +
+    'verdict): a declared key with zero read points in any direction — objectui\'s renderer ' +
+    'normalized the authored object and carried `icon` into a highlight chip with no icon ' +
+    'slot, `useRegisterHighlightFields` registers field NAMES only (structurally unable to ' +
+    'carry it), and the Studio designer publishes the field list as plain strings — while ' +
+    'six author-facing surfaces advertised the key (the #8691 reference-rail-`icon` shape, ' +
+    'on the highlight chip). The mechanical conversion strips the key from the object ' +
+    'entries of every `record:highlights` `fields[]` (pure lossless delete — the chip ' +
+    'renders label and value only, so it never had an effect to lose); there is no ' +
+    'replacement, and the live neighbour `readonly` (#5176) is untouched.',
   conversionIds: [
     'field-malformed-scale-precision-removed',
     'record-chatter-position-vocabulary',
     'element-input-target-variable-removed',
     'element-filter-removed',
     'field-column-lists-canonicalized',
     'metric-filters-removed',
+    'record-highlights-field-icon-removed',
   ],
   semantic: [
     // One file per entry under `entries/semantic/`, concatenated here sorted by
@@ -6736,6 +6748,37 @@ export const RETIRED_KEYS_BY_MAJOR: Readonly<Record<number, readonly string[]>>
     // `element-input-target-variable-removed` (a page component IS a stack
     // collection member, unlike the `kernel/Manifest:loading` family).
     'ui/ElementTextInputProps:targetVariable',
+    // #10054 — ADR-0049 enforce-or-remove (maintainer ruling 2026-08-21, executing
+    // the 2026-08-20 census verdict). `icon` on the object arm of
+    // `RecordHighlightsField` was declared, described (`Icon name (lucide icon
+    // key)`), and advertised on six author-facing surfaces — with ZERO read
+    // points, measured in every direction: objectui's renderer normalizes the
+    // authored object and carries `icon: f?.icon` into `HeaderHighlight`, whose
+    // chip has NO icon slot (its only `icon` occurrence is a button
+    // `size="icon"`); the key is structurally unable to travel
+    // `useRegisterHighlightFields`, which registers `names: string[]`; the Studio
+    // block designer publishes the field list as a `string[]` input, so the key
+    // was never designer-publishable; and all in-tree `record:highlights`
+    // producers author bare string arrays. The exact shape #8691 recorded for the
+    // reference-rail `icon`: declared and normalized, drawn by nothing — an
+    // authored value parsed clean and cost the author silently. The neighbouring
+    // `readonly` key is LIVE (#5176, HeaderHighlight's inline-edit gate) and is
+    // untouched.
+    //
+    // Registered under 18, not 17: v17.0.0 was cut before this landed, so the
+    // removal ships on the 17.x line (launch-window convention: accept-set
+    // narrowings ride minor releases) and the prescription lives at the major
+    // boundary where `migrate meta` users look (the #8495 / PR #8666 precedent).
+    // The object arm is `strictObject`, so the route is strict deletion + a
+    // `guidance` entry carrying the prescription (no retiredKey tombstone — the
+    // key is out of the walked shape entirely, and the refusal is the arm's own
+    // named `unrecognized_keys`, unpacked through the zod-4 union collapse by
+    // `packages/lint/src/zod-issue-format.ts`; the `data/Metric:filters` route).
+    // Sources are rewritten by the D2 conversion
+    // `record-highlights-field-icon-removed`, which strips the key from the object
+    // entries of every `record:highlights` `fields[]` (pure lossless delete — the
+    // chip renders label and value only, so the key never had an effect to lose).
+    'ui/RecordHighlightsField:icon',
     // </os-generated retired-key:18>
   ],
 };