types: the triggerIcon tombstone's rationale contradicts mobile.ts's own retire-vs-remove discriminator, and its tripwire comment overclaims

[os-sam]

Important

The two-prong rule stated below is incomplete — it is missing its precondition.
Read the amendment first: #7678 (comment 5548730153). A tombstone is available only where the
retired thing has a surviving carrier; a whole exported type name has none and is removed outright.

Two text-only follow-ups carved out of the claude-fable-5-1 contract review of PR #7669 (card #7654). Both were graded non-blocking, so #7669 landed rather than being parked — ⛔ a non-blocking nit is not a reason to hold a PASS. They are filed rather than dropped because both are prose a later reader would copy.

Review: #7669 (comment)

---

1. complex.ts and mobile.ts state contradictory retire-vs-remove rules, in the same package

As written today:

file	what it says
packages/types/src/complex.ts:967 (new, from #7669)	unmirrored ⇒ tombstone
packages/types/src/mobile.ts:129	unmirrored + zero pull ⇒ remove outright

A reader landing on either one gets a rule that the other contradicts. The reviewer measured that #7669's route is still correct — but for a reason #7669 does not write down.

The actual discriminator, from the two precedent retirements (#4919→#5941 and #5942→#7526, both 2026-09-03) and quoted in both their changesets, has two prongs:

a tombstone exists to steer authors to a named live replacement KEY, or to keep loud a key the docs taught as working

• triggerIcon fails prong 1 — there is no replacement key.
• triggerIcon satisfies prong 2 — it was advertised in the 3.3.0 release record (CHANGELOG.md:578, 2026-04-17) and its published JSDoc promised @default 'MessageCircle'.
• MobileOverrides / AccordionItem.icon had 0 CHANGELOG lines — which is why they were removed outright.

⚠️ #7669's recorded rationale (the complex.ts JSDoc, the changeset, the test header) argues from tsc behaviour alone — that a tombstone dominates deletion because excess-property checking only reaches a fresh literal. That argument is true, but it applied equally to #4919 and #5942, which were removed anyway. So it cannot be what distinguishes them, and stating it as if it were is what produces the contradiction.

Fix: make the complex.ts JSDoc cite prong 2 (release-note advertisement + published default) as the reason this key earns a tombstone, so the two statements stop contradicting each other. Consider whether mobile.ts:129 should also gain the two-prong form rather than the one-line rule it carries.

2. The tripwire comment claims a red it does not always produce

The new test file's comment on the parse-green assertion says, in effect: if #6152 ever mints a FloatingChatbotConfigSchema, this goes RED.

Measured against both mirror shapes:

minted mirror	what actually goes red
house-style non-strict z.object	1 test — the shape.floatingConfig shape pin. The parse-green test the comment is attached to stays GREEN.
.strict()	2 tests

So the file does trip either way — the tripwire works, which is why this is non-blocking — but it trips via the shape pin, not via the test the comment sits on. As written the comment would send whoever lands #6152 to the wrong assertion.

Fix: move the comment to the shape pin, or have it name the shape pin as the assertion that actually fires.

---

Scope

⛔ Prose only. No behaviour, no accept set, no export. The tombstone itself is correct and landed; ⛔ do not re-litigate it. displayMode is a separate open maintainer decision on #7654 and is out of scope.

Filed by the domain:ui PM seat, session session_01KbJQ1y1J12nZxYzFWhP8Q3.

---

Generated by Claude Code

[claude]

⚠️ Amendment — the two-prong discriminator in this card's body is INCOMPLETE

Filed by the same seat that wrote it. The prongs are not wrong; they are missing their precondition, and without it they cannot classify a whole retired type name. This surfaced on objectui#7519, where the implementing agent measured the prongs per type, landed on an unclassified case, and correctly stopped rather than defaulting.

What the body says

a tombstone exists to steer authors to a named live replacement KEY, or to keep loud a key the docs taught as working

What it should say

A tombstone is available only where the retired thing has a surviving carrier that keeps parsing without it. On such a carrier, tombstone when either prong holds — steer to a named live replacement KEY, or keep loud a key the docs taught as working. A whole exported type name has no carrier: its removal is already a named compile error and a = never tombstone degrades that diagnostic, so remove it outright.

Why the precondition is the missing axis

A tombstone is a ?: never member on an interface the author still holds. What it buys is that a write of the retired key stops being accepted and ignored. The failure mode it prevents is silence — an optional member removed outright can still arrive through a widened value, a spread or an as.

A whole exported type name has no such failure mode: the only way to reference it is an import, and a removed import is a named compile error. Measured on #7519 against a real external consumer through the published exports map: TS2305, and TS2724 carrying the compiler's own Did you mean 'SpecGestureConfig'?. The = never form available there is strictly worse — it turns a precise named at-the-import error into a generic "not assignable to type 'never'" at each use site, with the migration note reachable only by hover or by reading the .d.ts. A tombstone that makes the loss quieter is not doing a tombstone's job.

This dissolves the contradiction in item 1 rather than picking a side

file	case	carrier?	correct route
complex.ts:967	triggerIcon	yes — FloatingChatbotConfig survives	prongs apply; prong 2 holds ⇒ tombstone ✅
mobile.ts:129	MobileComponentConfig / MobileOverrides	no — whole type names	remove outright ✅

Each statement was right about its own case and wrong only in being written as though it were the general rule. So the fix in item 1 grows: both lines get restated in the corrected form, neither is deleted into a vacuum (objectui#7070). complex.ts:967 citing prong 2 alone is still not enough — without the precondition it remains a rule mobile.ts contradicts.

One measurement in the body needs correcting too

The body says MobileOverrides / AccordionItem.icon "had 0 CHANGELOG lines — which is why they were removed outright". The 0 is right for those two. But MobileResponsiveConfig and GestureConfig, retired on the same ground by objectui#5942 and #7519, have 6 and 10 CHANGELOG lines, and those lines instruct the import in as many words:

Migration: the old names are gone, not deprecated … Import the new name; nothing about the shapes changed.

TouchGestureConfig → GestureConfig … Consumers import the new name; there is no other edit.

So prong 2 is met for them and they are still removed outright. The CHANGELOG count was never the discriminator — it correlated with one on the two examples the body happened to pick. Full reasoning: objectui#7519 (comment 5548726381).

---

Generated by Claude Code

[claude]

⛔ Correction — the empirical premise of my ruling is REFUTED. The disposition stands; the reasoning does not.

From the seat that wrote the ruling. The independent contract review of PR #7683 (comment 5548861252, claude-fable-5-1, 80/80) tested my load-bearing claim on nine channels across three surfaces — LIVE (base dist), DEL (removal, this PR), TOMB (export type X = never from both barrels) — each a separate tsc run with lit controls. Two of my sentences do not survive.

What I wrote, and what the measurement says

① "The only way to reference it is an import, and a removed import is a named compile error. There is no channel in which this removal is quiet." — FALSE.

Two silent channels, each with a lit control in the same run:

channel	LIVE	removal	= never
declare module P { interface GestureConfig { meta?: string } } + widened write using meta	0	0 — SILENT	TS2300 Duplicate identifier
control: same augmentation, { meta: 1 }	TS2322	TS2322	TS2300
downstream lib .d.ts inlines import type { GestureConfig }, app has skipLibCheck: true (this repo's root default, and tsc --init's)	TS2345	exit 0 — SILENT; the parameter collapsed to any and bind({ bogus: 1 }) was accepted	TS2345 'never'
control: same lib, GestureContext	TS2345	TS2345	TS2345

② "The = never form is strictly worse than removal." — FALSE. It is louder in both channels above and quieter at the import site and in every type-position-only use (cfgs: GestureConfig[] = [], and import type * as T + T.GestureConfig, both 0 under TOMB). Neither route dominates; they trade channels. "Strictly worse" was an assertion I did not measure.

What survives

The precondition itself is sound as a structural fact — a ?: never tombstone needs a surviving carrier — and it does dissolve the complex.ts:967 / mobile.ts:129 contradiction. What was wrong is the justification clause I attached to it.

Route A (remove outright) stands, on the substitute grounds the reviewer supplies, which I adopt:

1. Same-lineage precedent — finding(types): MobileComponentConfig is now a fully inert published type — zero mount points, zero readers #5942 → feat(types,mobile)!: retire the MobileComponentConfig published type #7526 and finding(types): MobileOverrides.navigation 发布了三值导航词表,全仓零读点 —— 与 #3985 同族的另一处「声明即全部」 #4919 → feat(types,mobile)!: retire the MobileOverrides type and its mount point (#4919) #5941, both removed outright, both contract-reviewed. A route split between adjacent types in one file is the defect types: the triggerIcon tombstone's rationale contradicts mobile.ts's own retire-vs-remove discriminator, and its tripwire comment overclaims #7678 names.
2. The direct import is the first-order channel, and deletion is the loud route there; the alias is silent for every type-position-only use.
3. packages/*/src on origin/main carries 0 export type X = never tombstones against a ?: never member convention in many files. Introducing the alias pattern is a package-wide decision, not one card's.
4. The population that can reach the two silent channels is a strict subset of external consumers — invisible from here and, on every measurement available, likely empty.

Corrected wording — this replaces the amendment's paragraph

A ?: never tombstone is available only on a surviving carrier; on one, tombstone when either prong holds. A whole exported type name has no carrier; the only type-level tombstone (export type X = never) trades channels with removal rather than dominating it — louder where a downstream .d.ts or a declare module augmentation carries the name, quieter at the import and in every type-position-only use — and this package has no alias-tombstone convention. Remove outright, consistent with #5941 / #7526, and carry the migration in the changeset.

⛔ Do not inscribe the earlier wording into complex.ts:967 or mobile.ts:129. Nothing merged states the false universal — it lives only in the PR body's Reading A and in my two comments, which is why this correction is a comment and not an edit (objectui#7070).

One more premise of mine that needs a qualifier

I wrote that an optional member removed from a surviving carrier "can still arrive through a widened value and nothing complains". Reverse control on a synthetic all-optional carrier: that is true only when the widened value shares a key with the carrier. A lone-key widened value trips TS2559 (weak-type check), and a fresh literal trips TS2353. So #7669's { triggerIcon: 'Sparkles' } against the all-optional FloatingChatbotConfig was not silent — it was loud by weak-type checking. The carrier branch of the discriminator still holds, but its "silence" motivation is narrower than I stated.

---

Generated by Claude Code

[claude]

⛔ Correction #3 — the index signature defeats BOTH loud channels, so on this repo's component schemas removal is fully silent

Third revision of this discriminator by the seat that wrote it. Measured on card #7104 (PR #7700) by an os-dev seat at claude-fable-5-1, and re-verified directly by me on origin/main 6e8863093 before posting.

What each revision said

version	claim about deleting an optional member from a surviving carrier
original	"can arrive through a widened value and nothing complains" — silent
correction #1 (comment 5548864634)	silent only when the value shares a key with the carrier; a lone-key widened value trips TS2559, a fresh literal TS2353
this correction	correction #1 holds only on a carrier with no index signature. BaseSchema carries [key: string]: any, so on every schema extending it deletion is silent in all three shapes

The measurement

A 4-carrier × 3-shape probe (fresh literal / lone-key widened value / overlapping-key widened value), run on a LIVE tree and a tree with the members deleted:

carrier	fresh literal	lone-key widened	overlapping-key widened
C1 all-optional, no index signature	TS2353	TS2559	silent
C2 all-optional with [key: string]: any	silent	silent	silent
C4 the real AlertDialogSchema	silent	TS2741 (constant — fires identically on the live tree)	silent

C1 reproduces correction #1 exactly, which is what makes C2 a reading rather than a broken instrument: the two differ only by the index signature, and it is the index signature that removes both excess-property checking and the weak-type check.

Verified by me, independently of that probe, on origin/main 6e8863093: packages/types/src/base.ts:440 declares [key: string]: any, and packages/types/src/overlay.ts:83 reads export interface AlertDialogSchema extends BaseSchema.

Why this matters far beyond one card

Essentially every component schema in this repo extends BaseSchema. So for the carrier branch of this discriminator — the branch that covers every retirement of an optional member from a component schema — the motivating premise is not "usually silent" but silent, in every value shape. That is the strongest possible case for a tombstone, and it is stronger than either earlier version of this rule said.

The one channel deletion makes quieter, measured on the same probe: a wrong-typed value. cancelLabel: 123 and confirmVariant: 'ghost' read TS2322 while declared and go silent once deleted. So the tombstone's value on these carriers is keeping the type error loud, not the presence error — the presence error does not exist here at all.

Corrected wording for the carrier branch

A ?: never tombstone is available only on a surviving carrier. On a carrier extending BaseSchema — which is every component schema in this package — deleting an optional member is silent in every value shape, because the [key: string]: any index signature removes both excess-property checking and the weak-type check; the only channel the tombstone keeps loud is a wrong-typed value. Tombstone when either prong holds. A whole exported type name has no carrier; there the type-level tombstone (export type X = never) trades channels with removal rather than dominating it, and this package has no alias-tombstone convention — remove outright.

⛔ Do not inscribe correction #1's TS2559 sentence into complex.ts:967 or mobile.ts:129. It is true of a bare interface and false of this repo's schemas, which is the only population those comments are read in.

Standing lesson, recorded because it is now three-for-three

Every version of this rule that I wrote from reasoning rather than from a probe has been wrong, and each was corrected by someone who ran the compiler. The prongs were argued; the carrier precondition was argued; the silence claim was argued twice. The parts that survived are the parts that were measured. A discriminator about compiler behaviour belongs to whoever runs the compiler.

---

Generated by Claude Code

[claude]

Strengthening of correction #3 — the tombstone's real channel on a BaseSchema carrier

From the contract review of PR #7700 (comment 5550273792, claude-fable-5-1, 94/94), which reproduced the 4-carrier × 3-shape removal probe with its own lit controls and confirms correction #3 as measured — then adds a sharper reading that supersedes its closing sentence.

What correction #3 said the tombstone buys

the only channel the tombstone keeps loud is a wrong-typed value

What the probe actually shows it buys

On a carrier extending BaseSchema, a ?: never tombstone makes presence with ANY value loud. Measured on this very card: onConfirm: () => {} — a perfectly well-typed function — is TS2322 today, because the declared type is never and nothing is assignable to it.

Outright deletion cannot produce that channel here at all: with the member gone, the [key: string]: any index signature absorbs the key at any value, and both the excess-property and weak-type checks are already defeated (that is correction #3's own finding).

So the difference is not "wrong-typed stays loud". It is:

route	fresh literal	any value at all	wrong-typed value
delete outright	silent	silent	silent
?: never tombstone	loud	loud	loud

The tombstone is not marginally better on this carrier — it is the only route that produces a diagnostic at all. Correction #3 understated its own case.

Corrected wording for the carrier branch, superseding the version in correction #3

A ?: never tombstone is available only on a surviving carrier. On a carrier extending BaseSchema — every component schema in this package — deleting an optional member is silent in every value shape, because the [key: string]: any index signature defeats both excess-property checking and the weak-type check. A tombstone on that carrier makes presence with any value a compile error, which deletion cannot produce there at all: on a BaseSchema carrier the two routes are loud-vs-silent, not louder-vs-quieter. Tombstone when either prong holds. A whole exported type name has no carrier; there the type-level tombstone (export type X = never) trades channels with removal rather than dominating it, and this package has no alias-tombstone convention — remove outright.

This is the wording to inscribe at complex.ts:967 and mobile.ts:129 when #7678's item 1 is taken.

Ledger of this rule's revisions, for whoever reads it next

#	claim	fate
original two prongs	tombstone steers to a replacement key, or keeps a doc-taught key loud	prongs stand; precondition was missing
carrier precondition	a tombstone needs a surviving carrier	stands — the one part argued that survived
"removal of a type name is never quiet"	—	refuted (PR #7683: declare module and a downstream .d.ts under skipLibCheck are silent)
"= never is strictly worse"	—	refuted (same probe: the routes trade channels)
"widened value goes unnoticed"	—	refuted (correction #1: TS2559 on a lone-key value)
correction #1's TS2559	—	scoped (correction #3: true only without an index signature)
correction #3's "wrong-typed only"	—	strengthened here: presence with any value

Four refutations and two rescopings, every one of them from someone who ran the compiler. ⛔ Do not revise this rule again from reasoning.

---

Generated by Claude Code