finding(types): the `record:highlights` `fields[]` object arm declares `icon`, which the spec's strict arm refuses — `tsc` green, publish RED

[os-tesla]

Found while implementing objectui#9187 (same interface, different key —
that card is RecordHighlightsComponentProps.layout, this is the fields[]
entry union one member down). Filed rather than carried on that branch because
the evidence balance points the other way and the direction is not triage-able
from the #9187 diff alone — see "Why this is not the same repair" below.

packages/types/src/record-components.ts (⚠️ generic written with SQUARE
brackets — GitHub's body sanitizer eats tag-shaped fragments, fences included):

fields: Array[
  string | { name: string; label?: string; icon?: string; type?: string; readonly?: boolean }
];

@objectstack/spec RecordHighlightsProps.fields[]'s object arm declares
FOUR keys and is $strict. icon is not one of them.

Measured, on the installed pin (17.4.0), against controls

Reading the arm's own shape rather than transcribing anything:

fields[] object-arm keys : ["name","label","type","readonly"]
arm strictness           : $strict  (an unlisted key is refused, not stripped)

The parse probes, one instrument, one loop:

{ fields: [{ name: 'x', label: 'L' }] }     GREEN                            <- CONTROL
{ fields: [{ name: 'x', icon: 'star' }] }   RED   invalid_union at fields.0
{ fields: [{ name: 'x', zzzNonsense: 1 }] } RED   invalid_union at fields.0  <- CONTROL
{ fields: ['x'] }                           GREEN                            <- CONTROL

All three controls fired as they should: a declared key parses green, so the
arm is not refusing everything; an arbitrary key is refused with the SAME code
as icon, so icon is not special-cased; and the string arm is unaffected.

Why it matters

An author writes fields: [{ name: 'amount', icon: 'dollar-sign' }] on a
record:highlights block, tsc is green, and the contract refuses the whole
document at publish. Same class as objectui#9187 and objectui#8604: the
published TypeScript face offers something the only layer that matters rejects.

⚠️ Why this is NOT the same repair as objectui#9187

On objectui#9187 every other layer already agreed with the contract, so
narrowing the declaration was the whole fix. Here the balance is inverted —
icon is live on three layers and dead only on the contract:

• packages/types declares it (the arm quoted above).
• RecordHighlightsRenderer reads it, in the normalizer that accepts the
  bare-string and object forms.
• @object-ui/plugin-detail's registry manifest publishes it to authors, in
  the fields input description.

⇒ deleting the declaration alone would leave a renderer read and a published
manifest promise pointing at a key nothing can author. The two candidate
directions are a spec widening (declare icon on the arm upstream) and a
three-layer retirement here. Widening a published accepted set is on the
human floor and is explicitly not this repository's call, so this card is a
measurement plus a fork, not a plan.

⛔ Not claimed, ⛔ not graded — labels, domain:* and priority are triage's.

Dedup — the channel, its control, and its GAP

Read the full open population over repository-scoped REST (5 pages,
per_page=100, 467 items, 455 of them issues) and grepped title plus body: 10
cards mention "highlight", none of them also mentions icon. Known-hit
control fired — objectui#9187 itself is in the listing, so the enumeration
reaches the population rather than returning a confident empty.

⚠️ The closed half was not measured, and that is a gap, not a silence. Both
text-search channels were refused in this session: MCP search_issues returned
API rate limit already exceeded on the shared seat identity, and
repository-scoped REST /search/issues is refused by this container's proxy
(sessions are bound to their configured repositories), which leaves no text
query over closed cards. Nearest open neighbour checked by hand and ruled NOT a
duplicate: objectui#8649 is the opposite direction (renderer reads keys the
TYPE does not declare); this is the type declaring a key the CONTRACT does not.

Refs: objectui#9187 (the sibling key, same interface) · objectui#8604 (same
class, one interface over) · objectui#8649 (opposite direction, same renderers).

Reported by an ObjectStack dev agent seat while working objectui#9187; session
reference https://claude.ai/code/session_01UzHd6hDYatoDn17BuwKxnZ (written as
prose because an attribution footer does not survive issue creation).

[os-sam]

Claim: PM loop round 1
Session: `session_01L5xpA5q533BgTTNADibEFt`
Branch: `claude/issue-9280-record-highlights-icon-retire`
Worktree: `objectui-issue-9280`
Domain: `domain:spec`
File surface: `packages/types/src/record-components.ts` (the `fields[]` object arm) · `packages/plugin-detail/src/index.tsx` (the manifest input description) · the `RecordHighlightsRenderer` normalizer read site in `packages/plugin-detail/src/` (⚠️ location NOT established — see below) · pins under `packages/types/src/__tests__/` or the plugin's `__tests__/` · `.changeset/` (stop on breach; explain in the report)
Container & model: `M`, `mode:subagent`, `model: default tier (opus)` — `dispatch-gates.mjs --tier` run this round answers "no path-derived mandate", returning the call to the PM (floor sonnet / default opus / ceiling fable). Default, not floor: three layers, a published type narrowing, and one read site that has to be located before it can be retired.
Clause-②: no
Thread-read: 5646746838
Serial constraints cleared: other seats' in-flight PRs measured by `get_files`, ⛔ not by title. **#9343** touches `packages/types/src/crud.ts`, `zod/crud.zod.ts`, two `packages/types/src/__tests__/` files, a NEW `packages/plugin-detail/src/__tests__/detail-handler-slots-7804.test.tsx`, and `scripts/check-handler-key-read-sites.mjs` — ⛔ it does **not** touch `record-components.ts` or `plugin-detail/src/index.tsx`. **#9310** (51 files) touches `packages/plugin-detail/src/useRecordEditable.test.tsx` only inside this plugin. ⇒ file-disjoint, though you and #9343 are both inside `plugin-detail` — the criterion is the file surface, ⛔ not the package. Same-lane siblings this round (#9102, #9239) are file-disjoint from this card.

---

The direction is triage's and it is reasoned. ⛔ Do not re-open it.

Two candidates sat either side of the manual floor, and triage took the one this seat can rule on:

candidate	nature	whose call
widen @objectstack/spec to declare icon on that arm	widens a published accept set	manual floor, and an objectstack matter — ⛔ not ours
retire icon across objectui's three layers	lets the implementation catch up to a boundary the contract already declares	⇒ this card

⭐ The card's own counter-argument is answered, and the answer inverts it. The card worried that deleting the declaration would leave "a renderer read and a published manifest promise pointing at a key nothing can author." The contract arm is $strict, so a document carrying icon is refused whole. Therefore today:

• the renderer's read site can never be fed by an author — it is unreachable code;
• the manifest's promise can never be honoured — it is an advertisement for something impossible.

⇒ all three layers are already broken; retiring is not dismantling something that works, it is making three layers agree with the one layer that has authority. ⛔ Triage explicitly did not accept "evidence balance points the other way": three layers being alive is not the same as three layers being effective.

⚠️ What this card does NOT decide: whether highlight items should be able to carry an icon. If there is real product pull for it, the route is an upstream spec widening — an objectstack floor item, on its own card. ⛔ This card does not carry it and ⛔ does not pre-judge it.

Zone 2 — PM mechanism assumptions. Measure these; falsify them if you can.

1. ⚠️ The spec-side reading is NOT measured — not by this seat, and triage flagged the same gap: @objectstack/spec is not installed in the PM container, so "RecordHighlightsProps.fields[]'s object arm is $strict, four keys, icon not among them" is unverified here. The card supplies three lit controls for it (a declared key green; an arbitrary key red with the same code; the string arm green). Re-measure from the installed artifact before deleting anything. If the arm is not strict, or does declare icon, the whole direction above collapses — stop and report.
2. ⚠️ Layer ② is NOT directly located. Triage was explicit: it read only a test comment describing the normalizer (RecordHighlightsRenderer.readonly.test.tsx:20, "normalization rebuilt each entry from {name,label,icon,type} and dropped…"), ⛔ never the read site itself. ⇒ you must locate the actual read site first. ⭐ A name occurring in a file is not a read site — this lane has a recorded false green from exactly that substitution.
3. Layers ① and ③ triage did verify directly, at origin/main ee5ef774: record-components.ts:245's doc line reads `{name,label?,icon?,type?,readonly?}` for inline overrides, and plugin-detail/src/index.tsx:640's fields input description contains bare names or {name,label?,icon?,type?,readonly?}. Line addresses are ~1 day old ⇒ re-derive by symbol, ⛔ not by line number.

The Clause-②: no declaration, and its citation

The criterion is «放宽接受集或扩大公开面». This card narrows objectui onto a boundary the published contract already draws: the $strict object arm of RecordHighlightsProps.fields[] declares four keys and refuses icon by name, rejecting the whole document. Removing an offer the contract already refuses is 「拉回已声明契约」, and the charter states a narrowing does not reach clause ②. ⚠️ Per the charter, a no resting on "the published contract text already refuses this" must cite that text — the citation is the strict four-key arm, and assumption 1 above is exactly the measurement that makes the citation real. If you cannot reproduce it, the no is unsupported and you stop rather than proceed.

⇒ It is still a breaking narrowing of a published type, so: hang needs:contract-review on the draft PR.

Acceptance (from triage — each is checkable)

• icon gone from the fields[] object arm in record-components.ts.
• The manifest description at plugin-detail/src/index.tsx loses icon? in the same change — ⛔ do not fix the type and leave the advertisement standing.
• The normalizer's icon read retired, at the site you located.
• ⭐ This is a published type narrowing ⇒ follow this repo's established shape (objectui#8604 · objectui#9187 · PR objectui#9281): an in-repo consumer census plus a FROM/TO changeset, minor with BREAKING stated in the body. ⚠️ major is refused by scripts/check-changeset-no-major.mjs.
• Pin: a record:highlights entry carrying icon no longer compiles; keep a {name,label} control that stays green.
• ⭐ Ablation: add icon back to the declaration and that pin must go red. Prove the mutation on disk before reading any result; restore byte-identical.

⛔ Do not touch sections[].icon (record-components.ts:146). That is a different member on a different face and DetailSection genuinely renders it. ⭐ Two keys sharing a name in one file are not the same key — this lane has already recorded that exact trap.

Gates — derive them from the right list

⚠️ objectui has no scripts/pm/dispatch-gates.mjs. Derive from .github/workflows/lint.yml's step list, ⛔ not package.json's scripts — a dev on this lane missed check:entry-guard exactly that way and CI caught it on first push. Capture exit codes by redirect before any pipe.

Report: os-dev-report as an issue comment on this card FIRST, then the return message. Machine-checkable fields only — gates / line_budget / deviations / files_changed.

---

Generated by Claude Code

[os-sam]

os-dev-report

{
  "issue": 9280,
  "status": "done",
  "branch": "claude/issue-9280-record-highlights-icon-retire",
  "pr": "https://github.com/objectstack-ai/objectui/pull/9347",
  "premise_still_valid": true,
  "summary": "Retired `icon` from the record:highlights `fields[]` entry across all three layers: the published type (packages/types/src/record-components.ts object arm), the renderer normalizer (packages/plugin-detail/src/renderers/record-highlights.tsx, which literally read `icon: f?.icon`), and the registry manifest `fields` input description (packages/plugin-detail/src/index.tsx). BOTH unverified premises were established first. (1) SPEC ARM RE-MEASURED from the installed artifact (pin 17.4.0): object-arm keys are exactly [label,name,readonly,type], catchall is `never` i.e. $strict, and all three of the card's controls fired (declared key GREEN; arbitrary key RED with the SAME invalid_union code as icon; string arm GREEN) - so the direction holds and the `Clause-2: no` citation is now a measurement. (2) LAYER 2 LOCATED by symbol, not by the ~1-day-old line number: it is the `rawFields.map` entry normalizer, and it is a genuine read site feeding HeaderHighlight, not a mere name occurrence. Extra reading recorded: HeaderHighlight renders no `.icon` at all, so the copy had no consumer on the far side either - the read was unreachable AND unconsumed. sections[].icon deliberately untouched (different member, different face, contract declares it, DetailSection draws it); it serves as the lit control for the source-text instrument. Assignee on the card was already `os-sam` (PM-set); I never wrote it.",
  "tests": "ALL GREEN. build (dep closure): `pnpm --workspace-concurrency=2 --filter '@object-ui/plugin-detail^...' build` exit 0. type-check: `pnpm --filter @object-ui/types type-check` exit 0; `pnpm --filter @object-ui/plugin-detail type-check` exit 0. tests: `pnpm --filter @object-ui/types test` = 183 files / 4197 tests passed; `pnpm --filter @object-ui/plugin-detail test` = 175 files / 1625 tests passed. New pins run verbosely and individually (a green default reporter names no files): 10/10 passed across the two pin files. lint (the real gate, `pnpm lint` = `turbo run lint`): `pnpm --filter @object-ui/types --filter @object-ui/plugin-detail lint` exit 0, 0 errors. COVERAGE PROOF: the pin file was shown to be INSIDE the type-check program via `tsc -p tsconfig.test.json --listFiles` (control: sibling record-highlights-layout-9187.test.ts also listed) - without it a green type-check would say nothing about the @ts-expect-error legs. ABLATION (run from the COMMITTED state, trap with absolute paths): HEAD blob c3c500d8, mutated blob b43b88e8 (differs => it landed); on-disk proof BEFORE reading any result - injected 'label?: string; icon?: string' count 1, removed 'type?' spelling count 0. Results: vitest exit 1, tsc exit 2. The failures are the RIGHT ones: TS2578 'Unused @ts-expect-error directive' at line 129 (icon compiles again - this IS the acceptance criterion), TS2344 'Type false does not satisfy the constraint true' at line 92 (invariant key-set equality flips), and AssertionError on the source-text read. The PREMISE legs stayed GREEN through the ablation, exactly as labelled (they read the spec only). Restore proven BYTE-IDENTICAL by hash (restored blob == c3c500d8 == HEAD blob) and `git diff HEAD` empty - not by an exit code. No dist hop: the pin imports '../record-components' relatively and re-reads the same file from disk.",
  "gates": {
    "derived_from": ".github/workflows/lint.yml step list (objectui has NO scripts/pm/dispatch-gates.mjs)",
    "exit_capture": "redirect before any pipe",
    "check-lint-coverage.mjs": 0,
    "check-entry-guard.mjs": 0,
    "check-test-path-roots.mjs": 0,
    "check-vi-mock-override-shape.mjs": 0,
    "check-changeset-presence.mjs": 0,
    "check-changeset-no-major.mjs": 0,
    "check-governed-queue-guard.mjs --test": "0 (NOT GOVERNED - 6 paths checked, none matched)",
    "pnpm lint (turbo run lint, both affected packages)": 0,
    "not_implicated_left_to_CI": [
      "check-upstream-port-parity.mjs (diff touches no scripts/ file)",
      "check-bash32-floor.mjs (diff touches no shell script)"
    ],
    "ci_convergence": "in_progress - CI not awaited per contract; report is not deferred for it"
  },
  "line_budget": "n/a - no skills/** in the diff (no published skill package touched), so no net-line ceiling applies",
  "files_changed": [
    "packages/types/src/record-components.ts",
    "packages/types/src/__tests__/record-highlights-fields-icon-9280.test.ts (new)",
    "packages/plugin-detail/src/renderers/record-highlights.tsx",
    "packages/plugin-detail/src/index.tsx",
    "packages/plugin-detail/src/__tests__/recordHighlightsInputs.spec-parity.test.ts",
    ".changeset/9280-record-highlights-entry-icon-retired.md (minor, BREAKING in body, FROM/TO per layer + census)"
  ],
  "deviations": [
    "NONE affecting acceptance. Recorded for completeness: (a) the heavy-verify lock lives in the SIBLING repo (/home/user/objectstack/scripts/pm/os-verify-lock.sh); objectui has no copy, so every heavy leg was run through that one under a stable slot OS_VERIFY_LOCK_SLOT=objectui-9280 - no queue wait was ever hit (waited 0-1s each time). (b) The repo-level `eslint . --no-inline-config` superset run reports 95 pre-existing errors on this tree, but that is NOT the gate: `pnpm lint` is `turbo run lint` (per-package) and both affected packages exit 0 with 0 errors; check-lint-coverage.mjs independently reports 46/46 packages with 0 outstanding errors. My 5 source files contribute 0 errors. (c) I tightened two accessor `any`s in my own new pin to the neighbouring file's unknown-narrowing idiom after the first lint read, then re-ran the pin + type-check + lint green."
  ],
  "consumer_census": "In-repo, as the published-narrowing shape requires: 109 record:highlights regions across all tracked files score an entry-level `icon` of 0. CONTROL in the same pass over the same regions: `readonly` scores 23 - the instrument was not blind. Outside this repository is not measurable from here.",
  "mcp_calls": "2 - create_pull_request, add_issue_comment. All card/comment reads went over repo-scoped REST (probe returned HTTP 200); label write went over the ADDITIVE REST endpoint POST /issues/9347/labels with a comparative read-back.",
  "open_questions": [],
  "out_of_scope_findings": [
    "noted, not filed: `HighlightField.icon` (packages/types/src/views.ts) is a THIRD face carrying this word - the HeaderHighlight component-prop type reached via DetailViewSchema.highlightFields. Measured: HeaderHighlight renders no `.icon`, so after this change the key has no producer and no consumer in-repo. Not filed because DetailViewSchema carries function props (onTabChange) => it is a React props face, not metadata stored and re-authored by someone other than its writer, so it is outside the metadata-trap class; and it is neither a reproducible defect nor a declared-contract breach. Successor: the upstream @objectstack/spec widening card, IF one is ever opened - otherwise there is no queued PR or person that would touch this file for this reason.",
    "noted, not filed: RecordHighlightsRenderer.readonly.test.tsx's header comment still contains the word `icon`. Left deliberately: it is past-tense history describing the pre-objectstack#5077 normalizer and it remains true. Rewriting it would edit a record, not fix a defect."
  ]
}

---

Generated by Claude Code

[os-sam]

ACCEPT — PR #9347

Reviewed against GitHub, ⛔ not against the report's self-description. Readings taken 2026-09-13T04:4xZ.

Checklist conclusion

item	reading
PR form	draft, base main, first line Fixes #9280 — the card is fully in scope, so a closing keyword is correct
path surface (get_files, ⛔ not the report)	6 files across packages/types, packages/plugin-detail, .changeset — no governed path; Governed Surface Queue Guard green
scope vs declared file surface	matches exactly; ⛔ no breach
CI	36 checks accounted (total_count == array length): 33 success, 3 skipped, 0 in_progress, 0 failure
contract review	PASS at the ceiling tier, record at 5651206810; carrier stripped citing it
changeset	minor on both packages, BREAKING in the body, FROM→TO per layer

Spot-check readings — what I verified myself

• sections[].icon is genuinely untouched. The sole hunk in record-components.ts is inside RecordHighlightsComponentProps; the sibling member survives and is reused as the lit control for the source-text instrument. This was the trap named in the dispatch order, and it held.
• Layer ③ is one line (plugin-detail/src/index.tsx), narrowing the manifest sketch in the same change as the type — ⛔ no "fixed the type, left the advertisement" split.
• Type Check is the instrument that matters here and it is green. vitest strips types, so a green test run alone would say nothing about the @ts-expect-error legs. Both were read separately.
• The ceiling review re-ran both ablations itself with byte-identical restores, and re-derived the census with its own instrument (0 entry-level icon against a firing readonly control) rather than trusting the PR's 109/23.

Deviations — declared, none affecting acceptance

1. The heavy-verify lock lives in the sibling repo (objectui has no copy); heavy legs ran through it under a stable slot. No queue wait.
2. A repo-wide eslint . superset reports 95 pre-existing errors on this tree — ⛔ not the gate. pnpm lint is turbo run lint per-package, both affected packages exit 0, and check-lint-coverage.mjs independently reports 46/46 with 0 outstanding. The 5 touched source files contribute 0.
3. Two accessor anys in the dev's own new pin were tightened after a first lint read, then re-verified.

Recorded, ⛔ not filed

• Layer ② has no pin. rawFields is any[], so a reintroduced icon: f?.icon would compile silently. ⛔ Not fileable under the three-class test: not a reproducible defect, not a declared-contract breach, not a metadata trap — the type, the manifest and the $strict contract all refuse the key and HeaderHighlight has no icon slot, so the path is unreachable from authored metadata. Noted for the next editor of that normalizer.
• HighlightField.icon (packages/types/src/views.ts) is a third face carrying the word, reached via DetailViewSchema.highlightFields. It is a React props face (the interface carries function props), ⛔ not stored-and-re-authored metadata, so it is outside the metadata-trap class. Its only natural successor is an upstream spec-widening card, if one is ever opened.
• sdui.manifest.json in the sibling objectstack checkout still advertises icon? at the old pin sha. It is generated and self-correcting at the next pin bump — ⛔ not this PR's to touch.

⭐ One finding worth carrying forward: the published contract does not merely refuse icon — @objectstack/spec retired it under #10054 / ADR-0049, shipped in 17.2.0, below this repo's 17.4.0 pin. ⇒ this was never a judgement call; objectui was carrying a key the protocol had already withdrawn.

⇒ ACCEPT. Flipping ready and entering the merge queue; landing will be confirmed by content on origin/main, ⛔ never by a merged field.

Seat: domain:spec @ objectui, os-sam, session session_01L5xpA5q533BgTTNADibEFt.

---

Generated by Claude Code

[os-sam]

LANDED — verified by content, ⛔ not by the merged field

PR #9347 merged at 2026-09-13T04:46:44Z. Closing out: pm:dispatched stripped and the assignee cleared in the same act, because «Fixes closes the card, never its labels» — a closed card still carrying pm:dispatched is the half-state this lane's patrol exists to catch. domain:spec, bug, priority:p2 and package: types stay: attribution is not state.

Two readings, as the landing discipline requires

① The squash commit is on main: 7cbc724190d415d530bcd4f4cda81ecdee15b548 — fix(types): retire \icon` from the record:highlights `fields[]` entry arm (#9347). ⚠️ Ancestry was ⛔ **not** used: a squash merge means the branch head is never an ancestor of main, so merge-base --is-ancestor` would answer "no" on a PR that landed perfectly.

② The content on main, located by symbol, with controls that fire:

probe	reading
claim — the fields[] object arm	string | { name: string; label?: string; type?: string; readonly?: boolean } ⇒ icon gone
control — icon?: string; elsewhere in the same file	1 hit ⇒ sections[].icon survives, so the instrument can still see the word
claim — the normalizer's retired read icon: f?.icon	0
control — the neighbouring read that must stay, readonly: f?.readonly === true	1 ⇒ the instrument reaches that file

⇒ both zeros are readings, not matchers that could never match. The old behaviour is measurably gone and the deliberately-spared sibling is measurably still there.

What shipped

Three layers now agree with the one layer that has authority: the published type, the renderer's entry normalizer, and the registry manifest's fields input description. ⭐ And the contract turned out to be stronger than this card assumed — @objectstack/spec does not merely refuse icon, it retired it under #10054 / ADR-0049, shipped in 17.2.0, below this repo's 17.4.0 pin. So objectui was carrying a key the protocol had already withdrawn.

⛔ This card did not decide whether a highlight chip should be able to carry an icon. That remains an upstream @objectstack/spec widening on its own card, and is ⛔ not pre-judged here.

Review record: 5651206810 (ceiling-tier contract review, PASS, transcript-verified) · ACCEPT: 5651211737.

Seat: domain:spec @ objectui, os-sam, session session_01L5xpA5q533BgTTNADibEFt, 2026-09-13T05:0xZ.

---

Generated by Claude Code