feat(spec): retire the metric sub-caption — the widget translation subCaption key and translateDashboard's options.description overlay (#21342)

Fixes #21257
Clause-②: no (narrowing)

Retires the metric sub-caption at both ends, objectstack first. This
executes ruling **C** on objectstack-ai/objectui#11389 (batch #264 item
5, maintainer 「同意264」), which reverses #5428 item 4. A dashboard widget
keeps one authored description, `widget.description`. It renders as the
card-header subtitle and is translated by the widget node's
`description` key. No `options.description` comeback, and no new
widget-level key.

## What changes

1. **The translation member is retired.** In
`packages/spec/src/system/translation.zod.ts`, `subCaption` on the
widget translation node is now a `retiredKey()` tombstone. Its
prescription is: delete the entry; translate the card subtitle through
the widget's `description` entry; run `os migrate meta --from 17`. The
node is spread into the per-app bundle entry, the platform bundle entry
and the `translation` item, and all three refuse the key.
2. **The overlay is removed.** `translateDashboard` no longer writes
`options.description`, and it carries `options` through by reference.
The `attr` union of `lookupWidgetAttr` drops `'subCaption'`, and the
`WidgetLike.options` and `translateDashboard` docblocks say so.
3. **The census asserts nothing writes the key.**
`scripts/check-widget-option-census.mjs`: `NON_DECLARED_MEMBERS` is
empty. The `description` row left together with its witness and its
self-test cases. The row checks (stale row, witness gone, witness only
in prose) still run against a fixture ledger, through a new `ledger`
parameter on `judge`. A new battery pins `description` coming back into
the census as `UNDECLARED-AND-UNLEDGERED`, and the self-test floor goes
from 16 to 17. The gate's own `WITNESS GONE` text prescribes taking the
key out of the census, so `@objectstack/sdui-parser`'s
`CONSUMED_WIDGET_OPTION_KEYS` drops `description` in the same change. An
authored `options.description` now draws the `unconsumed-widget-option`
warning, which is a warning and fails nothing.
4. **Docblocks** in `ui/dashboard.zod.ts`,
`sdui-parser/src/dashboard-widget-options.ts` and
`platform-objects/.../source-hash.ts` now state the retired state and
point at `widget.description`.

Retirement kit, per `.claude/skills/spec-property-retirement`:
- **D2 conversion.** `translation-widget-sub-caption-removed` (protocol
18, `MAJOR_18_CONVERSIONS` order 55, `retiredAfter: '17.6.0'`). It
strips the key from bundle entries and bare items, and is retired from
the load path. Stored `translation` rows replay it through
`applyConversionsToStoredItem`.
- **D3 entry.** The semantic entry
`translation-widget-sub-caption-retired` and its `STEP18_RATIONALE`
fragment (order 60). The registry region was regenerated with
`gen:migration-registry`.
- **Liveness.** The `translation.json` `dashboards` row has new evidence
and a new note, and `verifiedAt` is 2026-10-02. The member sits below
the ledger's walk boundary, inside the `widgets` record, so it has no
row of its own.
- **Generated.** `content/docs/references/system/translation.mdx` was
regenerated by `check:generated --fix`, which judged only `check:docs`
stale. Nothing was hand-edited.
- **Docs.** `content/docs/ui/translations.mdx` is corrected at the table
row, the callout and the packaged-strings table.
- **Changeset.** `.changeset/21257-widget-sub-caption-retired.md` bumps
`@objectstack/spec`, `@objectstack/sdui-parser` and `@objectstack/lint`
by `minor`. It has a `**BREAKING**` banner, a FROM-to-TO table and the
ADR-0087 marker `registered translation-widget-sub-caption-removed,
translation-widget-sub-caption-retired`.
- **No `RETIRED_KEYS_BY_MAJOR` row.** The key sits under two records,
and the nested-key resolver deliberately does not traverse
`additionalProperties`. The component-copy `submitLabel` retirement
(commit d173125) made the same choice.

## The `subtitle` alias: refused, not repointed

The old table carried `subtitle: 'subCaption'`. With `subCaption`
tombstoned, that row is the shape the alias-integrity audit refuses by
name. Measured by putting the row back in: `alias-integrity.test.ts`
went red with "`subtitle` -> `subCaption` — `subCaption` is a tombstone;
it accepts nothing".

Every precedent in the tree for an alias whose target was retired moves
the alias into `guidance` with a refusal: chart `accessibility` /
`ariaProps`, postgres `passwd` / `pwd`, permission `restore` / `purge`,
app `home` / `homepage` / `landingpage`, and component-copy `submit`.
None of them repoints the alias.

Repointing it at `description` would also silently change what the word
is taken to mean. The alias existed because a `subtitle` on a metric
widget meant the caption under the number. So `subtitle` is now a
`guidance` entry that names both readings: card-header copy belongs
under `description`; a caption under the value has nowhere to render, so
delete it. This keeps the four-axis 「过渡也从紧」 rule: no rename window and
no silent repoint. The change is a refusal message, not an accept-set
change: `subtitle` was never accepted.

## Measurements

- **Producers (objectstack `main` `393ae878d3`, re-read at
`1371dc980c`).**
- `git grep subCaption` over `examples/`, `packages/platform-objects`
and `apps/` returns 0 hits. Control: widget translation entries exist in
the showcase and platform bundles (`widgets:` appears 4 times in
`examples/app-showcase/src/system/translations/index.ts` and once in
each `platform-objects` locale file).
- Authored widget `options` blocks in the 6 `*.dashboard.ts` sources
under `examples/` and `packages/platform-objects`: 0. The two `options:`
hits are global-filter option arrays. Control: `widget.description` is
authored, for example on `pipeline.dashboard.ts`.
  - `app-multi-package` has no dashboards.
  - So: 0 producers. This is not a stop.
- **objectui pin check (`.objectui-sha` `31971ff1e28f`).** The pinned
objectui still reads `subCaption` and `options.description`:
`useObjectLabel.widgetSubCaption`, `widgetSubCaption.ts`,
`DatasetWidget`, `DashboardRenderer`, and its own `sdui-parser` census.
That is objectui#11389's reader half. It imports no symbol this PR
removes: `git grep` at the pin finds no import of `WidgetLike`,
`translateDashboard` or `lookupWidgetAttr`. Control: the pin does import
from `@objectstack/spec` elsewhere, for example
`spec-symbol-parity.test.ts`. No exported symbol is removed here, and
the bundle-shaped `subCaption` fixtures at the pin are untyped. So there
is no build break, and no sibling fix rides this landing.
- **Lockstep window.** objectui's `CONSUMED_WIDGET_OPTION_KEYS` at the
pin still lists `description`, and objectui#11389 drops it with the
reader. Until then this copy is one member short. That errs in the safe
direction: this copy warns on a key that objectui's strict authoring
face already refuses. `check:sdui-lockstep` compares grammar, codes and
the containment predicate, not this array, and it is green. The window
is documented at the array.

## Verification (final head `8438e24995`, which is `3f1c6d9c4d` with
`origin/main` `1371dc980c` merged)

- `pnpm --filter @objectstack/spec build`, then `check:generated`. 1 of
15 artifacts was stale (`check:docs`), and `--fix` regenerated only that
one.
- Spec tests:
- `vitest run --project local` (at `3f1c6d9c4d`): 597 files, 17487
passed, 1 todo.
  - `vitest run --project repo`: 48 files, 849 passed.
  - `pnpm --filter @objectstack/spec typecheck`: exit 0.
- Other package tests:
  - `@objectstack/sdui-parser`: test 218 passed; typecheck exit 0.
- `@objectstack/lint`: test 5575 passed after the merge; typecheck exit
0.
- `@objectstack/platform-objects` (comment-only change): test 948
passed; typecheck exit 0.
- `node scripts/check-widget-option-census.mjs --self-test`: 17 cases
pass. The real run is green with 5 declared keys in 5 members and 0
non-declared.
- Derived gates. `node scripts/pm/dispatch-gates.mjs --repo
objectstack-ai/objectstack --commands` derived 137 commands at
`8438e24995`. All 137 ran with recorded exit codes, and `--ran`
reconciles: 136 run, 1 NOT-MEASURED, 0 UNRUN.
- The NOT-MEASURED one is `check:pm-dispatch-gates`. Two foreground runs
were killed at the container cap (580s and 560s) before reaching a
verdict; CI runs it.
- Five gates first exited 3 (PREREQUISITE NOT MET) and passed after the
CLI and client-react closures were built: `check:i18n`,
`check:i18n-walk-parity`, `check:skill-examples`,
`check:lean-entry-closure`, `check:dual-build-cjs-loads`.
- **Reverse verification (cross-package type).** I planted `subCaption`
on `widget_total_users` in
`packages/platform-objects/src/apps/translations/en.ts`, which is typed
`TranslationData` through spec's rebuilt `dist`. `tsc --noEmit` went
red: `en.ts(210,69)`, error TS2322, a `string` not assignable to the
`'[REMOVED] Key retired: …': never` mark. The file was restored, the
blob equals HEAD, and `git diff HEAD` is empty. My first attempt was a
no-op: `ablation-replace` refused because the replacement contained the
anchor. It wrote nothing.
- **Ablations, one-shot, each restored to the HEAD blob.**
- Re-adding an `options.description` write in `translateDashboard`
turned the 3 new resolver pins red.
- Swapping the tombstone for `z.string().optional()` turned 3
translation pins red. The `subtitle` pin stays green because it is
independent of the tombstone.
- Restoring the `subtitle -> subCaption` alias turned alias-integrity
red, as quoted above.
- **eslint, a declared narrowing.** I ran `eslint --no-inline-config
--format json` on the 13 changed `.ts` / `.mjs` files: 13 files linted,
0 errors, 0 warnings, and none ignored, because an ignored file would
have shown as a warning. `eslint.config.mjs` states that type-aware
linting is never enabled (no `parserOptions.project`), so this diff
cannot move a verdict on an untouched file. The repo-wide `pnpm lint`
belongs to CI.

## Acceptance notes

- Two example comments still describe the dataset-bound read set as
"plus the `description` sub-caption":
`examples/app-crm/src/dashboards/pipeline.dashboard.ts:41` and
`examples/app-todo/src/dashboards/task.dashboard.ts:22`. That is true of
objectui's renderer at the pin, and false once objectui#11389 lands.
These are comments only and outside the claimed file surface, so they
are not edited here. No carrier is named.
- `DashboardWidgetOptionsSchema` stays `passthrough`, as ruled when the
bag was opened, so the spec still parses an authored
`options.description`. What now names it is the
`unconsumed-widget-option` warning at `os validate`, `os build` and `os
lint`. This is an observation, not a finding: 0 producers were measured.
- The card body asked for `Clause-②: yes (narrowing)`. The measured arm
is `no (narrowing)`, which matches the claim: no surface widens. The
`subtitle` change alters a refusal message only, and the new conversion
and semantic entries are registry rows, not an accept-set or export
widening.
- `#20274` regenerates `liveness/state-counts*` and
`content/docs/references/**`. This PR changes no state count; the
`dashboards` row stays `live`. It does change
`references/system/translation.mdx`. If the two collide, the second to
land regenerates through `scripts/pm/os-regen-merge.sh`.

---
_Generated by [Claude
Code](https://claude.ai/code/session_01UtnxvdiN376GF3sgXwAw4d)_

---------

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

Author: objectstack-fleet[bot]

.changeset/21257-widget-sub-caption-retired.md

@@ -0,0 +1,35 @@
+---
+'@objectstack/spec': minor
+'@objectstack/sdui-parser': minor
+'@objectstack/lint': minor
+---
+
+The metric sub-caption is retired at both ends. A dashboard widget keeps one authored description, `widget.description`, which renders as the card-header subtitle and is translated by the widget's `description` translation key. The widget translation key `subCaption` is refused, and the server no longer writes a widget's `options.description`.
+
+Clause-②: no (narrowing)
+
+<!-- adr-0087: registered translation-widget-sub-caption-removed, translation-widget-sub-caption-retired -->
+
+**What is retired.** `dashboards.DASHBOARD.widgets.WIDGET.subCaption` in a translation bundle (`defineTranslationBundle`, `stack.translations`, the platform bundle) and in a registered `translation` item. It overlaid a caption under a metric's value onto the widget's `options.description`. The dashboard schema never declared `options.description`, and no authored widget wrote it, so `translateDashboard`'s overlay was the key's only writer. That overlay is removed: `translateDashboard` now translates a widget's `title` and `description` and carries `options` through untouched.
+
+**BREAKING** — an accept-set narrowing, shipped as `minor` under the launch-window convention.
+
+### FROM → TO
+
+| wrote | write instead |
+| --- | --- |
+| `dashboards.DASHBOARD.widgets.WIDGET.subCaption: 'TEXT'` | delete the entry. If the copy belongs on the card, put it in the widget's `description` and translate it under `dashboards.DASHBOARD.widgets.WIDGET.description`. |
+| `dashboards.DASHBOARD.widgets.WIDGET.subtitle: 'TEXT'` | `subtitle` was only ever a rename suggestion for `subCaption`. Card-header copy goes under `description`; a caption under the value has nowhere to render, so delete it. |
+
+**The one-line fix: delete every `subCaption:` entry under `dashboards.*.widgets.*` in your translation bundles.** `os migrate meta --from 17` lists the mechanical edits for existing sources; stored `translation` items are converted when they are read.
+
+**What an author now sees.** Writing `subCaption` fails `tsc` (its input type is the retired-key mark) and fails the parse with a prescription naming the widget's `description`. Writing `subtitle` on a widget translation fails the parse with both readings named, instead of a rename suggestion onto a key that is refused next. `os validate`, `os build` and `os lint` now raise the `unconsumed-widget-option` warning on an authored widget `options.description`, like any other options key the dataset-bound render path does not read. It is a warning, so none of the three fails on it.
+
+**Measured producers: none.** Zero `subCaption` entries and zero authored widget `options.description` in the four example apps (`app-crm`, `app-todo`, `app-showcase`, `app-multi-package`) and in the bundles `@objectstack/platform-objects` ships, so no shipped exit code changes.
+
+### The retirement kit
+
+- **Tombstone.** `subCaption` is a `retiredKey()` tombstone on the widget translation node, so the refusal carries the prescription on all three faces the node is spread into (per-app bundle entry, platform bundle entry, `translation` item). The node sits under two records (`dashboards`, `widgets`), below the authorable-surface walk, so it has no `RETIRED_KEYS_BY_MAJOR` row, the same as the `submitLabel` component-copy key before it.
+- **The former alias.** The `subtitle` → `subCaption` rename suggestion moves to the node's `guidance` table. An alias whose target is a tombstone is the shape the alias-integrity audit refuses, and repointing it at `description` would silently change what the word is taken to mean.
+- **Conversion.** `translation-widget-sub-caption-removed` (protocol 18) strips the key from bundle entries and bare translation items as a lossless delete. It is retired from the load path, so authors are refused at parse while stored rows and `os migrate meta` replay it. Its D3 record is the semantic entry `translation-widget-sub-caption-retired`.
+- **`@objectstack/sdui-parser`.** `CONSUMED_WIDGET_OPTION_KEYS` drops `description`, its one undeclared member, which existed only because the overlay wrote it. `check:widget-option-census`'s `NON_DECLARED_MEMBERS` ledger is now empty, so the census asserts that nothing writes an undeclared key into `options`.

content/docs/references/system/translation.mdx

@@ -231,7 +231,7 @@ Translation data for a single object
 | **label** | `string` | optional | Translated dashboard title |
 | **description** | `string` | optional | Translated dashboard description |
 | **actions** | `Record<string, { label?: string }>` | optional | Header action label translations keyed by action url/key |
-| **widgets** | `Record<string, { title?: string; description?: string; subCaption?: string }>` | optional | Widget translations keyed by widget id |
+| **widgets** | `Record<string, { title?: string; description?: string }>` | optional | Widget translations keyed by widget id |
 | **globalFilters** | `Record<string, { label?: string; options?: Record<string, string> }>` | optional | Global-filter translations keyed by the filter `name` (a filter that authors no `name` is keyed by its `field`) |
 
 ### Nested Shape: `PlatformTranslationData.datasets[string]`
@@ -429,7 +429,7 @@ Translation data for a single object
 | **label** | `string` | optional | Translated dashboard title |
 | **description** | `string` | optional | Translated dashboard description |
 | **actions** | `Record<string, { label?: string }>` | optional | Header action label translations keyed by action url/key |
-| **widgets** | `Record<string, { title?: string; description?: string; subCaption?: string }>` | optional | Widget translations keyed by widget id |
+| **widgets** | `Record<string, { title?: string; description?: string }>` | optional | Widget translations keyed by widget id |
 | **globalFilters** | `Record<string, { label?: string; options?: Record<string, string> }>` | optional | Global-filter translations keyed by the filter `name` (a filter that authors no `name` is keyed by its `field`) |
 
 ### Nested Shape: `TranslationData.datasets[string]`
@@ -588,7 +588,7 @@ Translation data for a single object
 | **label** | `string` | optional | Translated dashboard title |
 | **description** | `string` | optional | Translated dashboard description |
 | **actions** | `Record<string, { label?: string }>` | optional | Header action label translations keyed by action url/key |
-| **widgets** | `Record<string, { title?: string; description?: string; subCaption?: string }>` | optional | Widget translations keyed by widget id |
+| **widgets** | `Record<string, { title?: string; description?: string }>` | optional | Widget translations keyed by widget id |
 | **globalFilters** | `Record<string, { label?: string; options?: Record<string, string> }>` | optional | Global-filter translations keyed by the filter `name` (a filter that authors no `name` is keyed by its `field`) |
 
 ### Nested Shape: `TranslationItem.datasets[string]`

content/docs/ui/translations.mdx

@@ -74,7 +74,7 @@ export default defineStack({
 | Custom validation-rule messages | `objects.<name>._validations.<rule>.message` |
 | App navigation | `apps.<app>.navigation.<id>.label` |
 | Dashboard label / description | `dashboards.<name>.label` / `description` |
-| Dashboard widget title / description / sub-caption | `dashboards.<name>.widgets.<widgetId>.title` / `description` / `subCaption` |
+| Dashboard widget title / description (the card-header subtitle) | `dashboards.<name>.widgets.<widgetId>.title` / `description` |
 | Dashboard global-filter label and static option labels | `dashboards.<name>.globalFilters.<filterName>.label` / `.options.<value>` — the key is the filter's `name`, or its `field` when it authors no `name`; an option is keyed by its `value` spelled as a string |
 | Analytics dataset label / description | `datasets.<name>.label` / `description` |
 | Dataset dimension and measure labels | `datasets.<name>.dimensions.<dimension>.label` / `datasets.<name>.measures.<measure>.label` |
@@ -95,13 +95,16 @@ in a zh-CN workspace for every consumer except the Console, which happened to
 re-resolve them client-side against its own copy of the bundle.
 
 <Callout type="info">
-**A widget's `subtitle` alias resolves to `subCaption`, not `description`
-(#5428 item 4, #7862).** The metric widget's sub-caption — the string under
-the number — is the authored `widget.options.description`, a *different*
-authored field from `widget.description` (the copy under the card header).
-Two authored fields get two keys (「两个作者字段两个 key」): `description`
-translates `widget.description`, `subCaption` translates
-`widget.options.description`, and neither reaches the other's field.
+**A widget has one translatable description; the metric sub-caption is
+retired (#21257).** `widget.description` renders as the card-header subtitle
+and is translated by `dashboards.<name>.widgets.<widgetId>.description`.
+The `subCaption` key, which used to overlay a caption under a metric's value
+onto `widget.options.description`, is refused at parse with its prescription,
+and the server no longer writes `options.description`. A `subtitle` entry is
+refused too, naming both readings: card-header copy belongs under
+`description`; a caption under the value has nowhere to render, so delete
+it. `os migrate meta --from 17` lists the `subCaption` entries to delete from
+existing bundles.
 </Callout>
 
 <Callout type="info">
@@ -185,7 +188,7 @@ with the same string in the item as the package shipped it:
 
 | Packaged type | Strings compared, and how each is matched |
 |:---|:---|
-| Dashboard | its `label` and `description`; each widget's `title`, `description` and sub-caption (`subCaption`), matched by widget `id`; each global filter's `label` and static option labels, matched by the filter key and the option `value` |
+| Dashboard | its `label` and `description`; each widget's `title` and `description`, matched by widget `id`; each global filter's `label` and static option labels, matched by the filter key and the option `value` |
 | View | its `label` and `description`; each bulk action's `label`, `confirmText` and `confirmLabel`, and each of its params' `label`, `help` and `placeholder`, matched by `name` |
 
 - **Only the edited strings move.** A widget the org left alone on an edited

packages/lint/src/validate-dashboard-widget-options.test.ts

@@ -53,7 +53,6 @@ describe('validateDashboardWidgetOptions — the SDUI widget-option check at the
     // schema refuses it on any other type, so the control widget is a funnel.
     const values: AnyRec = {
       dateGranularity: 'month',
-      description: 'sub-caption',
       limit: 10,
       sortBy: 'total_amount',
       sortOrder: 'desc',

packages/platform-objects/src/apps/translations/source-hash.ts

@@ -277,9 +277,11 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
  * (`apps.setup.navigation.group_overview.label`).
  *
  * A generic deep walk rather than an enumeration of the known shapes: the
- * sections grow keys (`subCaption`, `pages.<n>.components.<id>.<copyKey>`) and
- * an enumeration would silently stop covering the new ones — the same
- * declared-but-unwalked failure this module exists to close.
+ * sections grow keys (`dashboards.<n>.globalFilters.<key>.options.<value>`,
+ * `pages.<n>.components.<id>.<copyKey>`) and an enumeration would silently stop
+ * covering the new ones — the same declared-but-unwalked failure this module
+ * exists to close. (They shrink too: the widget `subCaption` key this sentence
+ * once cited was retired, and a deep walk needs no edit for that either.)
  */
 export function collectSourceLeaves(data: TranslationData | undefined): Map<string, string> {
   return collectLeavesOf(data, HAND_AUTHORED_SECTIONS);

packages/sdui-parser/src/__tests__/dashboard-widget-options.test.ts

@@ -122,23 +122,22 @@ describe('the census the expectations derive from is not vacuous', () => {
     expect([...CONSUMED_WIDGET_OPTION_KEYS].sort()).toEqual([...CONSUMED_WIDGET_OPTION_KEYS]);
   });
 
-  it('the accepted set is exactly objectui\'s — the lockstep pin this copy cannot re-derive', () => {
+  it('the accepted set is the five declared query keys — the lockstep pin this copy cannot re-derive', () => {
     // This repo has no dashboard renderer, so the read-site half of the census
     // is not measurable here (objectui owns it). What IS measurable here is the
     // DECLARED half: the five query keys below are exactly the five properties
     // `DashboardWidgetOptionsSchema` declares in
     // `packages/spec/src/ui/dashboard.zod.ts` — the spec ships from THIS repo,
     // so a declared key landing there without landing here would turn this
-    // module into a false positive on legal metadata. `description` is the
-    // sixth, undeclared, member: the metric sub-caption channel that
-    // `translateDashboard` writes into `options` (see `WidgetLike.options` in
-    // `packages/spec/src/system/i18n-resolver.ts`), also a read site in this
-    // repo. Re-read both files when this pin fails.
+    // module into a false positive on legal metadata. There is no undeclared
+    // member: `description`, the metric sub-caption `translateDashboard` used
+    // to write into `options`, was retired at both ends (objectstack#21257,
+    // ruling C on objectui#11389), and objectui's copy drops it with the
+    // reader in objectui#11389. Re-read both files when this pin fails.
     // The declared half of that sentence is re-derived by
     // `scripts/check-widget-option-census.mjs`; this pin is the array's shape.
     expect([...CONSUMED_WIDGET_OPTION_KEYS]).toEqual([
       'dateGranularity',
-      'description',
       'limit',
       'sortBy',
       'sortOrder',
@@ -192,18 +191,33 @@ describe('the ruled first case: gauge options.invert (objectui#5709)', () => {
   it('the emitted diagnostic is byte-equal to objectui\'s, field for field', () => {
     // The lockstep claim is about the WHOLE envelope, not just the code: a
     // message that drifted by one word is a different author-visible dialect.
+    // The printed set omits `description` (objectstack#21257); objectui's
+    // copy prints it until objectui#11389 drops the retired sub-caption read.
     const found = unconsumed(dash({ ...slaGauge, options: { invert: true } }));
     expect(found).toEqual([
       {
         severity: 'warning',
         code: 'unconsumed-widget-option',
         message:
           '<dashboard> widget "sla_compliance_gauge" (gauge): options.invert reaches no renderer — ' +
-          'dashboard widget renderers read only: dateGranularity, description, limit, sortBy, sortOrder, stageOrder',
+          'dashboard widget renderers read only: dateGranularity, limit, sortBy, sortOrder, stageOrder',
         tag: 'dashboard',
       },
     ]);
   });
+
+  it('`options.description` draws the warning — the retired metric sub-caption is no consumed key (objectstack#21257)', () => {
+    // Flipped, not deleted: until objectstack#21257 `description` was the
+    // census's one undeclared member, because `translateDashboard` wrote the
+    // metric sub-caption into it. Ruling C on objectui#11389 retired that
+    // channel at both ends, so the key is now judged like any other.
+    const found = unconsumed(
+      dash({ id: 'won', type: 'metric', dataset: 'sales', values: ['won_amount'], options: { description: 'vs last quarter' } }),
+    );
+    expect(found).toHaveLength(1);
+    expect(found[0]!.severity).toBe('warning');
+    expect(found[0]!.message).toContain('options.description reaches no renderer');
+  });
 });
 
 describe('the port is ADDITIVE — it must not move this copy\'s accept/reject set', () => {

packages/sdui-parser/src/dashboard-widget-options.ts

@@ -24,7 +24,9 @@
  * objectui's `src/dashboard-widget-options.ts` SAVE FOR ONE TOKEN, called out
  * at the site itself: the emitted `code` is spelled as an inline literal here
  * and as the constant there, because this repo runs a vocabulary gate objectui
- * does not. The emitted `code`, `severity`, `message` and the whole census
+ * does not. One census MEMBER differs too, for a bounded window: objectui's
+ * copy at the pin still lists `description`, which this one dropped with the
+ * retired metric sub-caption (see `CONSUMED_WIDGET_OPTION_KEYS`). The emitted `code`, `severity`, `message` and the whole census
  * scope are identical, and `__tests__/dashboard-widget-options.test.ts`
  * re-derives that rather than trusting it — including an explicit pin that the
  * literal equals `UNCONSUMED_WIDGET_OPTION`. Change these functions only
@@ -50,17 +52,16 @@
  *   dateGranularity, sortBy, sortOrder, limit   (query-affecting, framework#3588)
  *   stageOrder                                  (funnel stage order — the only type that reads it)
  *
- * plus ONE undeclared key with a real read site:
- *
- *   description — the metric-card sub-caption channel. `translateDashboard`
- *   OVERLAYS the `widgets.{id}.subCaption` translation onto this key, and that
- *   pipeline lives IN THIS REPO: `packages/spec/src/system/i18n-resolver.ts`
- *   documents `WidgetLike.options` as "the renderer-extras bag …
- *   `translateDashboard` writes exactly one key into it — `description`"
- *   (objectstack#5428 item 4, objectstack#7862). Warning on a key the
- *   platform's own translation pipeline writes would be a false positive on
- *   legal metadata, so it is in the accepted set even though the dataset-bound
- *   render path does not currently display it.
+ * and nothing undeclared. `description` used to be the one undeclared member:
+ * the metric-card sub-caption channel, which `translateDashboard` overlaid from
+ * a `widgets.{id}.subCaption` translation (objectstack#5428 item 4,
+ * objectstack#7862), so warning on it would have flagged the platform's own
+ * output. Ruling C on objectui#11389 retired that channel at both ends,
+ * objectstack first (objectstack#21257): the overlay is gone, the bundle key is
+ * a tombstone, and a widget keeps ONE authored description, `widget.description`
+ * — never `options.description`. With no writer left, `description` left this
+ * census, so an `options.description` now draws the warning like any other key
+ * the dataset-bound path is not meant to read.
  *
  * Notably NOT consumed on the path a widget really renders through:
  * `thresholds` and `format`. Both were widely believed to work; both draw this
@@ -114,12 +115,18 @@ export const DASHBOARD_WIDGET_HOST_TYPES: ReadonlySet<string> = new Set([
 
 /**
  * The accepted set: every `options` key with a renderer read site on the
- * dataset-bound path, plus the sub-caption convention key. Alphabetical; the
- * warning message prints it verbatim. Derivation and evidence: file header.
+ * dataset-bound path. Alphabetical; the warning message prints it verbatim.
+ * Derivation and evidence: file header.
+ *
+ * ⚠️ One member short of objectui's copy until objectui#11389 lands: objectui's
+ * renderer at the pin still reads `options.description` for the retired metric
+ * sub-caption, and its census lists it; that card drops the read and the member
+ * together. The window errs in the safe direction — this copy warns on a key
+ * objectui's strict authoring face already refuses — and no served document
+ * carries the key, because its only writer was the retired overlay.
  */
 export const CONSUMED_WIDGET_OPTION_KEYS: readonly string[] = [
   'dateGranularity',
-  'description',
   'limit',
   'sortBy',
   'sortOrder',