feat(spec)!: a pie / donut / funnel / treemap / sankey widget takes one measure with a dimension too — refuse two or more at values, and rename the check to checkDashboardWidgetChartMeasureArity (#21293) (#21425)

Fixes #21293
Clause-②: yes (narrowing)

Extends #20958's per-type measure-arity rule to the dimensioned arm, as
triage ruled on objectstack-ai/objectui#11417 (comment `5943580519`,
carried onto this card as `5944795015`): for `pie`, `donut`, `funnel`,
`treemap` and `sankey`, two or more measures are refused **whatever the
dimension**. It uses #20958's mechanism and message shape: the same
check, one more arm, and one ADR-0087 semantic entry in #20958's shape.
No second rule is added. `scatter` and `radar` with a dimension are
outside the ruling and parse as before.

## What changed

- **`packages/spec/src/ui/dashboard.zod.ts`**
- New module-private `SINGLE_SERIES_CHART_TYPES` (`:784`): `pie` /
`donut` / `funnel` / `treemap` / `sankey`, typed `as const satisfies
readonly ChartType[]`. It is private, like the metric family's list. The
check, its refusal text and the `values` doc string read it.
- The check gains a second arm, the **single-series arm**. When
`dimensions` is declared and non-empty, `values` has two or more
members, and `type` is one of the five, it emits ONE `custom` issue at
`values`. The issue names the widget `id`, the count and the type, and
says the type "draws ONE series whatever its `dimensions`". It steers to
`type: 'table'` (a column per measure), a bar-family type (one bar per
measure in each category), or one widget per measure.
- The dimensionless arm is unchanged, byte for byte, in both verdict and
message. The arms are exclusive on `dimensions`, so a dimensionless
`pie` still gets the dimensionless message, and only one issue.
- The metric family still returns early (its sibling check owns it), and
so do types outside `ChartTypeSchema`.
- **Renamed export:** `checkDashboardWidgetDimensionlessMeasureArity` is
now `checkDashboardWidgetChartMeasureArity` (`:878`, chained at
`:1461`). The reason is in "The rename" below.
- The `values` doc string now states the single-series rule. It reads
the private constant.
- **ADR-0087 entry**
`packages/spec/src/migrations/entries/semantic/18.dashboard-widget-single-series-multi-measure-refused.ts`,
plus the `gen:migration-registry` lap. Nothing between the markers was
hand-edited. Its acceptance criteria name the doors as measured (below),
state that the TODO cannot name per-document measures, and list what is
and is not refused. It also records the export rename (FROM → TO).
- **The #20958 entry, amended in two sentences**
(`18.dashboard-widget-dimensionless-multi-measure-refused.ts`). It named
the old export, and it said "the same seven types WITH a dimension keep
accepting several measures exactly as before". This change makes both
false, and `os migrate meta` prints both entries in the same hop. They
now name the new export (noting the old name) and point the five at this
entry. This file is outside the claim's listed file surface; see
Deviations.
- **Tests**
- `dashboard.test.ts`: a new `[#21293]` block, plus the fixture triage
below.
- `object-refinement-check-exports.test.ts`: the parity catalogue row is
renamed, and its fixtures are triaged.
- **Changeset**
`.changeset/21293-single-series-multi-measure-refused.md`: `minor`, a
**BREAKING** banner, the `(narrowing)` arm, and exactly one ADR-0087
marker (`registered
dashboard-widget-single-series-multi-measure-refused`). It carries a
FROM → TO table that includes the export rename.
- **Regenerated:**
- `api-surface/ui.json` and `export-origins/ui.json`: one row renamed in
each, `-1 / +1`.
  - The `values` row of `content/docs/references/ui/dashboard.mdx`.
  - `src/migrations/registry.ts`.

## The rename, and what objectui's mirror chains today

The check now judges widgets WITH a dimension, so
`...DimensionlessMeasureArity` names a boundary that no longer exists. A
mirror deciding which export to chain reasons from that name first. This
is the cheapest moment there will ever be to change it, because nothing
chains it yet:

- At the `.objectui-sha` pin `89cad75d55702cc4f267bead5bf267de575d5842`,
`git grep "DimensionlessMeasureArity\|MULTI_MEASURE_TYPES"` returns **0
hits**. The control, `checkDashboardWidgetMetricMeasureArity` in
`packages/types/src/zod/complex.zod.ts`, returns 2. objectui's
`DashboardWidgetSchema` mirror chains `checkDashboardWidgetStageOrder`
and `checkDashboardWidgetMetricMeasureArity` only
(`complex.zod.ts:1304`, and the `attached` row in
`spec-object-refinements-7715.test.ts:135`).
- On objectui `origin/main` `5988b6b53` the readings are the same: 0
hits, control 2.
- In this repository the old name had no consumer outside
`packages/spec`'s own tests (`git grep`).
- The spec object's check COUNT is unchanged at three, so objectui's
census test sees no count change at the bump.

A rename is a removal plus an addition, so the changeset carries the
import FROM → TO, and `Clause-②` is `yes`.

## Measured before building (the dispatch's four hypotheses)

The branch base is `4b20c84748`. It is newer than the dispatch's
`1d0600bf66`, and `dashboard.zod.ts` did not change between the two.

- **H1, holds.** The check returned early on any non-empty `dimensions`
(old `:834`), and `DASHBOARD_WIDGET_MULTI_MEASURE_TYPES` listed the
eight multi-measure types. At the base I built `dist` and ran
`DashboardWidgetSchema.safeParse` on `{ id, type, dataset, dimensions:
['stage'], values: ['revenue', 'cost'] }`. It returned **ACCEPT** for
`pie`, `donut`, `funnel`, `treemap`, `sankey`, `scatter`, `radar`, `bar`
and `table`. One measure returned ACCEPT on all of them. The lit
control, the same body plus `bogusProp`, returned REFUSE
`unrecognized_keys` on every type.
- **H2, holds.** objectui's renderer at the pin
(`packages/plugin-charts/src/AdvancedChartImpl.tsx`) binds the first
series on exactly these arms:
- `pie` / `donut` at `:2095` (`const pieDataKey = series[0]?.dataKey ||
'value'`);
- `funnel` at `:2161`, `treemap` at `:2243` and `sankey` at `:2278`
(`const dataKey = series[0]?.dataKey || 'value'`).
  - `radar` maps every series (`:2406` onward, `series.map(...)`).
- objectui's `DatasetWidget.tsx` at the pin already names the same five
as `SINGLE_SERIES_CHART_FAMILIES` (`:387`–`:413`), which is the #11417
diagnostic. It says `scatter` "refuses a second series out loud".
- **H3, partly falsified.** There is no declared "order":
`build-migration-registry.ts` derives the order by sorting entry ids
("Order is DERIVED, never declared"). The serial constraint did hold. PR
#21399 (`analytics-query-window-non-negative-integer`) landed on `main`
first, so this branch merged `origin/main` `db3fee3dc9` through
`scripts/pm/os-regen-merge.sh` (merge commit `b3b3c516f9`).
  - The registry text-merged clean.
- `gen:migration-registry` on the merged tree rewrote it byte-identical:
346 semantic entries, `git status` empty.
- All three sibling entries are present at HEAD. Quoted-exact-name `git
grep`, HEAD vs `origin/main`:
`analytics-query-window-non-negative-integer` 1/1,
`dashboard-widget-dimensionless-multi-measure-refused` 1/1, and
`dashboard-widget-single-series-multi-measure-refused` 1 at HEAD, 0 on
main.
- **H4, census: no authored hit.** I scanned brace-local literals
carrying `values: [...]` over every tracked
`.ts/.tsx/.js/.mjs/.cjs/.json/.md/.mdx/.yml` file.
- objectstack at `4b20c84748`: 496 literals, 33 on the seven types, 1
dimensioned multi-measure on the five. That one is
`packages/spec/src/ui/object-refinement-check-exports.test.ts:365`, the
fixture that pinned the old acceptance, triaged below.
- Lit control: 9 dimensioned multi-measure literals on other types
(`table` / `combo` widgets in `examples/app-showcase`, and others).
- objectui at the pin: 480 literals, 13 on the seven, and 1 hit on the
five. That hit is the prose example in
`.changeset/11417-dashboard-single-series-dropped-measure.md:10`, not
metadata.
- `examples/**`, the showcase and CRM apps, and
`packages/platform-objects` dashboards carry zero instances.
- Dynamically built fixtures do not show up in a static scan. I
inspected each downstream test that loops over chart types or builds
widgets (`lint` `validate-widget-bindings`, `runtime-gate`,
`validate-dashboard-widget-options`, and `metadata-protocol`'s two donut
fixtures). All carry one measure.

## Doors after the change (built `dist`, one-shot probe, deleted
afterwards, `git status` clean)

| body (`dimensions: ['stage']`) | `DashboardSchema` |
`getMetadataTypeSchema('dashboard')` | `ObjectStackDefinitionSchema` |
`defineStack` |
|---|---|---|---|---|
| `pie`, 2 measures | REFUSE `widgets.0.values:custom` | REFUSE
`widgets.0.values:custom` | REFUSE
`dashboards.0.widgets.0.values:custom` | throws `defineStack validation
failed (1 issue)`, naming the widget |
| `sankey`, 2 measures | REFUSE | REFUSE | REFUSE | throws |
| `pie`, 1 measure (control) | ACCEPT | ACCEPT | ACCEPT | returns |
| `radar`, 2 measures (control) | ACCEPT | ACCEPT | ACCEPT | returns |
| `bar`, 2 measures (control) | ACCEPT | ACCEPT | ACCEPT | returns |

I did not re-measure `os validate` or the metadata save path. The entry
does not claim them. They parse through the same schema at the same
attachment point as #20958, which measured both.

## Fixture triage (pins whose premise this change makes false)

- **`object-refinement-check-exports.test.ts`.** The row "two measures
on a `pie` WITH a dimension — out of this rule" (`refusesAt: []`) is
this arm's subject now. It becomes five refusing rows, one per
single-series type. Accepting rows are added for `scatter` / `radar`
with a dimension and for a one-measure dimensioned `pie`.
- **`dashboard.test.ts`, the #20958 block.** "accepts `%s` with ONE
dimension and two measures" iterated all seven types. It keeps `scatter`
and `radar`, and the five move to the new block as refusals.
- **`dashboard.test.ts`, the #17779 block.** "leaves `%s` — every
NON-metric type — accepting three measures" ran on `WIDGET_BASE`, which
carries a dimension. Its own claim is that the METRIC check leaves
non-metric types alone, so that claim is now read off the metric export
directly for all 15 types. The parse leg keeps the 10 types no check
refuses.
- **#20958's dimensionless pins are unchanged.** That covers the
refusals, the explicit `dimensions: []` refusals, the message pin and
the metric-family one-issue pin.

## New pins (`[#21293]` block in `dashboard.test.ts`)

- Each of the five, with a dimension and two measures: REFUSE, `custom`
at `values`, message naming the type.
- The control: one measure on each of the five with a dimension: ACCEPT.
- Each of the five with TWO dimensions: REFUSE.
- `scatter` / `radar` with a dimension and two measures: ACCEPT.
- Every multi-measure type with a dimension and three measures: ACCEPT.
- **Taxonomy read off the door:** with a dimension, the set of
`ChartTypeSchema` types refused at two measures is exactly the metric
family plus the five.
- A dimensionless widget of each of the five keeps the dimensionless
message, word for word and as ONE issue. The parse leg equals the direct
call.
- The metric family with a dimension keeps its own refusal, and the
chart export stays silent on it.
- Direct-call legs: a dimensioned `pie` is refused; a wider-enum type
(`custom`) and a dimensioned `scatter` are not.
- `DashboardSchema.widgets[]` travel, and the `values` doc string.
- The old export name is absent from `@objectstack/spec/ui`. The new
export is the lit control.

## Verification

Every reading below is at HEAD `b3b3c516f9` unless it names another
commit.

**Reverse verification**, at committed `221df98d72`, through
`scripts/ablation-replace.mjs`:

- The mutation turned the single-series arm's type guard into an
unconditional `return`. The subject is imported from `src` by relative
path, so no `dist` is involved.
- The prediction was "turns red", and that is the direction observed.

```
anchor x1 -> x0 · marker x0 -> x1 · blob 9a8c228 -> cfdc26ae3cbf (mutation landed)
RED   vitest exit=1   19 failed | 342 passed (361)   (dashboard.test.ts + object-refinement-check-exports.test.ts)
restored blob 9a8c228 == HEAD blob, git diff HEAD empty; marker count after restore 0
```

The 19 red tests:

- 14 in the new block: 5 refusals, 5 two-dimension refusals, the
taxonomy pin, the message pin, the direct-call pin and the travel pin;
- 5 parity rows in the exports catalogue, one per dimensioned
single-series fixture.

**Tests.** Each is the package's own vitest run. Downstream packages
were chosen by direction: the dependents of `@objectstack/spec` that
import or parse the dashboard schemas (`git grep`). This is not the full
`...@objectstack/spec` sweep.

| package | result |
|---|---|
| `@objectstack/spec` (`--project local`) | 600 files, 17666 passed, 1
todo, exit 0 |
| `@objectstack/spec` typecheck (tsc + scripts + test layer) | exit 0
(and at `221df98d72` before the merge). The test-layer ledger held at 52
files / 246 errors / 135 signatures; `tsc -p tsconfig.test.json
--listFiles` lists both touched test files and the new entry. |
| `@objectstack/lint` | 119 files, 5575 tests, exit 0 |
| `@objectstack/sdui-parser` | 13 files, 218 tests, exit 0 |
| `@objectstack/platform-objects` | 59 files, 949 tests, exit 0 |
| `@objectstack/metadata-protocol` | 201 passed, 3 skipped (204 files);
2983 passed, 19 skipped; exit 0 |
| `@objectstack/metadata` | 56 files, 836 tests, exit 0 |
| `@objectstack/service-analytics` | 168 files; 3794 passed, 89 skipped;
exit 0 |
| `@objectstack/cli` (`--project unit`) | 247 files, 3538 tests, exit 0.
The integration tier is declared to CI: no spawn entry or integration
file is touched. |
| `@objectstack/objectql` (`--project local`) | 364 files, 7360 tests,
exit 0 |

**Generated artefacts.** `pnpm --filter @objectstack/spec
check:generated` reports "All 15 generated artifacts are up to date" on
the merged tree, after a rebuild. `check:migration-registry` reports
`registry.ts is current (346 semantic, 243 retired-key, 212
retired-def)`.

**Gates.**

- `node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack
--commands` at `b3b3c516f9` derives 115 commands. The 10 changed paths
are measured against merge base `db3fee3dc`; 671 changed lines.
- All 115 ran. `--ran` reconciliation: "115 derived, 115 run, 0
NOT-MEASURED, 0 UNRUN (a DERIVED zero)".
- Six first answered `PREREQUISITE NOT MET` (exit 3) and were re-run to
a real exit 0 after a workspace build:
- `check:doc-formula-expressions` and `check:doc-security-posture`
(`lint` / `formula` not built);
  - `check:skill-examples` (`client-react` not built);
  - `check:docs-transcript-drift` (`lint` not built);
  - `check:dual-build-cjs-loads` (86 packages had no `dist`);
  - `check:lean-entry-closure` (`objectql` not built).
- Compared with the seat's dispatch-time list (109), the re-derivation
adds six: the changeset-driven `check-empty-changeset` pair,
`release-rehearsal-clone --self-test`, `release-pending-publish
--self-test`, `check:objectui-changeset` and
`check:pm-changeset-deadline-census`. All six ran.
- Verdict lines:
- `check-adr-0087-registration --base origin/main`:
`[BREAKING+bang+clause-②-narrowing] registered
dashboard-widget-single-series-multi-measure-refused (new here:
dashboard-widget-single-series-multi-measure-refused)`.
- `check:api-surface`: "public API surface + factory signatures
unchanged ✓", against the regenerated snapshot.
- `check:doc-authoring`: no internal issue-id in the 17250
customer-facing strings. The refusal text carries none.
  - `check:nul-bytes`: OK.

**`Clause-②`, measured.** `node scripts/pm/check-widening-tells.mjs
--declaration no --diff` on `git diff origin/main...HEAD` exits 4:

- It reports five T2 tells, `dashboard.zod.ts:785`–`:789`. These are the
members of the module-private `SINGLE_SERIES_CHART_TYPES` `as const`
array. The array narrows the accept set, so these tells are false as
widenings.
- T3 does not fire, because the `api-surface/ui.json` hunk removes the
old row beside the new one.
- The export listing does gain a row:
`checkDashboardWidgetChartMeasureArity (function)`, the renamed export.
- `--declaration yes` exits 0.

So the measured arm is `Clause-②: yes (narrowing)`. The `yes` holds
because a renamed check function is exported for objectui's `.shape`
mirror to chain, which is the dispatch's own example. The `(narrowing)`
holds because the accept set shrinks.

**Lint**, a measured narrowing rather than the repo-wide run (that run
belongs to CI):

- I ran `eslint --no-inline-config --format json` over the 6 touched
`.ts` files. The JSON reports 6 files, 0 errors and 0 warnings.
- Population: `eslint --print-config` returns a rule set for each file,
so none is ignored.
- Invariance: `parserOptions.project` and `projectService` are null for
every file, and `eslint.config.mjs:327` states that it never enables
type-aware linting. This diff therefore cannot move a verdict on any
untouched file.

## Deviations

- **One file outside the claim's listed surface:** the #20958 entry. Two
of its sentences, one naming the export and one saying the dimensioned
arm keeps accepting, became false in this change. `os migrate meta`
prints both entries in one hop, so leaving them would print a
contradiction. The standing dev definition requires fixing released text
that a change makes false. The claim's "stop on breach" reads the other
way, so the conflict is named here rather than settled silently. The
edit is two sentences, and the registry region is regenerated, not
hand-edited.

## Acceptance notes

None of these is filed. None is a reproducible defect, a contract
violation or an authoring trap.

- **`check-widening-tells` T2 fires on a module-private `as const` set
whose members narrow.** The declaration is `yes` for the export row
anyway, so the tells decide nothing here. The matcher was not touched.
The precedent (`SINGLE_MEASURE_WIDGET_TYPES`) predates the gate.
Carrier: none.
- **The single-series set is not exported.** objectui's dataset widget
keeps its own renderer-derived copy (`SINGLE_SERIES_CHART_FAMILIES`,
"Kept here, once, because the renderer has no declaration of it to
read"). No import of a spec list is measured anywhere. If objectui's
mirror or diagnostic later wants it, exporting it is a free widening.
Carrier: none.
- **No `STEP18_RATIONALE` fragment**, following #20958's precedent.

## Downstream: objectui's mirror (not in this PR;
objectstack-ai/objectui#11417 carries it)

`@object-ui/types` builds `DashboardWidgetSchema` from a `.shape`
spread, so it runs only the checks it chains, and today it chains
neither arm. At the pin bump that carries this change:

- Import `checkDashboardWidgetChartMeasureArity` from
`@objectstack/spec/ui`.
- Chain it in `packages/types/src/zod/complex.zod.ts` after
`.superRefine(checkDashboardWidgetMetricMeasureArity)`.
- Add it to the `attached` list of the `DashboardWidgetSchema
(complex.zod.ts)` row in `spec-object-refinements-7715.test.ts`.
- Refusal shape: ONE `custom` issue at `path: ['values']`. With a
dimension, the message starts "Widget `ID` declares N measures on `type:
'T'`, a single-series type (...) that draws ONE series whatever its
`dimensions`". Without one, it keeps #20958's "declares N measures with
no `dimensions`" text.

objectstack-ai/objectui#11417 remains open: this PR carries only the
spec half.

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

---------

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

Author: objectstack-fleet[bot]

.changeset/21293-single-series-multi-measure-refused.md

@@ -0,0 +1,66 @@
+---
+'@objectstack/spec': minor
+---
+
+feat(spec)!: a `pie` / `donut` / `funnel` / `treemap` / `sankey` dashboard widget takes ONE measure with a dimension too — two or more are refused at `values`, and the check export is renamed `checkDashboardWidgetChartMeasureArity` (#21293; extends #20958)
+
+Clause-②: yes (narrowing) — the accept set NARROWS (that is the change), and the published surface swaps one export for another: `checkDashboardWidgetDimensionlessMeasureArity` is removed and `checkDashboardWidgetChartMeasureArity` is added in its place, the same check with a second arm.
+
+<!-- adr-0087: registered dashboard-widget-single-series-multi-measure-refused -->
+
+**BREAKING** accept-set narrowing at `dashboard.widgets[].values`, plus one renamed
+export, shipped as `minor` under this repo's launch-window convention for breaking
+changes (`check-changeset-no-major` refuses `major` while the window is open, so
+breaking-ness is carried by this banner and by the ADR-0087 disposition above,
+never by the bump level). The prescription is registered under protocol major 18
+as `dashboard-widget-single-series-multi-measure-refused`.
+
+**What was wrong.** The previous release refused two or more measures on a
+dimensionless `pie` / `donut` / `funnel` / `scatter` / `radar` / `treemap` /
+`sankey`, and stepped aside for any widget that declared a dimension. Five of those
+types draw ONE series whatever the dimension: objectui's chart renderer binds the
+first series on its `pie` / `donut`, `funnel`, `treemap` and `sankey` arms and reads
+no other, so `{ type: 'pie', dimensions: ['stage'], values: ['revenue', 'cost'] }`
+drew one slice per stage for `revenue` and no trace of `cost`. Measured on this tree
+before the change: that body parsed through `DashboardWidgetSchema` on all five
+types (and on `scatter` / `radar` / `bar` / `table`), while `bogusProp` on the same
+widget was refused by name, the lit control. After it, the five are refused at
+`widgets[N].values`; `scatter` and `radar` with a dimension are outside the ruling
+and parse as before.
+
+### Write instead
+
+| wrote | write instead |
+|---|---|
+| `{ id: 'mix', type: 'pie', dataset: 'sales', dimensions: ['stage'], values: ['revenue', 'cost'] }` | `{ id: 'mix', type: 'table', dataset: 'sales', dimensions: ['stage'], values: ['revenue', 'cost'] }` — a column per measure |
+| the same, wanting a chart | `type: 'bar'` (or `column` / `horizontal-bar`) — one bar per measure in each stage |
+| the same, wanting the pie | `{ id: 'mix', type: 'pie', …, values: ['revenue'] }` **and** `{ id: 'mix_cost', type: 'pie', …, values: ['cost'] }` — one widget per measure, each with its own `id` (and `layout`, if you pin positions) |
+| `import { checkDashboardWidgetDimensionlessMeasureArity } from '@objectstack/spec/ui'` | `import { checkDashboardWidgetChartMeasureArity } from '@objectstack/spec/ui'` — same `(widget, ctx)` signature; chain it where the old name was chained |
+
+No conversion does this for you: whether a two-measure pie by stage meant a table, a
+grouped bar chart or two pies is an authoring choice. The refusal is ONE `custom`
+issue at `widgets[N].values` naming the widget's `id`, the number of measures and
+the authored `type`, and saying that type draws one series whatever its
+`dimensions`.
+
+**Why the export is renamed.** The dimensionless rule's check now has a second arm
+that judges widgets WITH a dimension, so its old name described a boundary that no
+longer exists. It refuses everything the old name refused, word for word on a
+dimensionless widget. No first-party consumer chained the old name: objectui's
+`DashboardWidgetSchema` mirror chains `checkDashboardWidgetStageOrder` and
+`checkDashboardWidgetMetricMeasureArity` only, measured at the pinned objectui
+commit and on objectui's `main`.
+
+**Nothing else moves.** One measure parses on every type; `scatter` and `radar`
+keep accepting several measures with a dimension; every type in
+`DASHBOARD_WIDGET_MULTI_MEASURE_TYPES` keeps accepting any number of measures with
+or without a dimension; a dimensionless widget of the five keeps the dimensionless
+refusal, word for word and still ONE issue; the metric family's refusal is
+unchanged; an empty `values` keeps its `too_small`; a `type` outside
+`ChartTypeSchema` reports the type refusal alone. Census at the branch point
+(`4b20c8474`), every tracked `.ts` / `.tsx` / `.js` / `.mjs` / `.cjs` / `.json` /
+`.md` / `.mdx` / `.yml`: 496 literals carry `values: [...]`, 33 of them on one of
+the seven types, and the only dimensioned multi-measure one on the five is a spec
+test fixture that pinned the old acceptance (moved to the refusal in this change).
+The same scan over objectui at its pinned commit (`89cad75d5`) finds no authored
+widget of that shape — its one hit is the prose example in a changeset.

content/docs/references/ui/dashboard.mdx

@@ -77,7 +77,7 @@ const result = DashboardSchema.parse(data);
 | **compareTo** | `{ kind: Enum<'previousPeriod' \| 'previousYear'>; dimension?: string }` | optional | Period-over-period comparison window (`{ kind, dimension? }`) |
 | **dataset** | `string` | ✅ | Dataset name to bind (ADR-0021) |
 | **dimensions** | `string[]` | optional | Dimension names — X/group/split |
-| **values** | `string[]` | ✅ | Measure names — Y (at least one; exactly one on the metric/kpi/gauge/solid-gauge/bullet family; with no dimensions, two or more only on table/pivot/bar/column/horizontal-bar/line/area/combo) |
+| **values** | `string[]` | ✅ | Measure names — Y (at least one; exactly one on the metric/kpi/gauge/solid-gauge/bullet family and on the single-series pie/donut/funnel/treemap/sankey; with no dimensions, two or more only on table/pivot/bar/column/horizontal-bar/line/area/combo) |
 | **layout** | `{ x: number; y: number; w: number; h: number }` | optional | Grid layout position (auto-flowed when omitted) |
 | **options** | `{ dateGranularity?: Enum<'day' \| 'week' \| 'month' \| 'quarter' \| 'year'>; sortBy?: string; sortOrder?: Enum<'asc' \| 'desc'>; limit?: integer; … } & Record<string, any>` | optional | Widget specific configuration |
 | **filterBindings** | `Record<string, string \| false>` | optional | Per-widget dashboard-filter bindings: filter name → this widget's field, or false to opt out |
@@ -182,7 +182,7 @@ Dashboard header action
 | **compareTo** | `{ kind: Enum<'previousPeriod' \| 'previousYear'>; dimension?: string }` | optional | Period-over-period comparison window (`{ kind, dimension? }`) |
 | **dataset** | `string` | ✅ | Dataset name to bind (ADR-0021) |
 | **dimensions** | `string[]` | optional | Dimension names — X/group/split |
-| **values** | `string[]` | ✅ | Measure names — Y (at least one; exactly one on the metric/kpi/gauge/solid-gauge/bullet family; with no dimensions, two or more only on table/pivot/bar/column/horizontal-bar/line/area/combo) |
+| **values** | `string[]` | ✅ | Measure names — Y (at least one; exactly one on the metric/kpi/gauge/solid-gauge/bullet family and on the single-series pie/donut/funnel/treemap/sankey; with no dimensions, two or more only on table/pivot/bar/column/horizontal-bar/line/area/combo) |
 | **layout** | `{ x: number; y: number; w: number; h: number }` | optional | Grid layout position (auto-flowed when omitted) |
 | **options** | `{ dateGranularity?: Enum<'day' \| 'week' \| 'month' \| 'quarter' \| 'year'>; sortBy?: string; sortOrder?: Enum<'asc' \| 'desc'>; limit?: integer; … } & Record<string, any>` | optional | Widget specific configuration |
 | **filterBindings** | `Record<string, string \| false>` | optional | Per-widget dashboard-filter bindings: filter name → this widget's field, or false to opt out |

packages/spec/api-surface/ui.json

@@ -478,7 +478,7 @@
     "chartAggregateCategoryKey (function)",
     "chartAggregateResultKeys (function)",
     "chartAggregateValueKey (function)",
-    "checkDashboardWidgetDimensionlessMeasureArity (function)",
+    "checkDashboardWidgetChartMeasureArity (function)",
     "checkDashboardWidgetMetricMeasureArity (function)",
     "checkDashboardWidgetStageOrder (function)",
     "checkGlobalFilterDateDefaultValue (function)",

packages/spec/export-origins/ui.json

@@ -463,7 +463,7 @@
     "chartAggregateCategoryKey": "src/ui/chart-aggregate.ts#chartAggregateCategoryKey (function)",
     "chartAggregateResultKeys": "src/ui/chart-aggregate.ts#chartAggregateResultKeys (function)",
     "chartAggregateValueKey": "src/ui/chart-aggregate.ts#chartAggregateValueKey (function)",
-    "checkDashboardWidgetDimensionlessMeasureArity": "src/ui/dashboard.zod.ts#checkDashboardWidgetDimensionlessMeasureArity (function)",
+    "checkDashboardWidgetChartMeasureArity": "src/ui/dashboard.zod.ts#checkDashboardWidgetChartMeasureArity (function)",
     "checkDashboardWidgetMetricMeasureArity": "src/ui/dashboard.zod.ts#checkDashboardWidgetMetricMeasureArity (function)",
     "checkDashboardWidgetStageOrder": "src/ui/dashboard.zod.ts#checkDashboardWidgetStageOrder (function)",
     "checkGlobalFilterDateDefaultValue": "src/ui/dashboard.zod.ts#checkGlobalFilterDateDefaultValue (function)",

packages/spec/src/migrations/entries/semantic/18.dashboard-widget-dimensionless-multi-measure-refused.ts

@@ -60,12 +60,16 @@ export const entry: SemanticMigration = {
     + '`id`, the number of measures and the authored `type`, when `dimensions` is absent or an empty '
     + 'array, `values` carries two or more measures, and `type` is `pie`, `donut`, `funnel`, '
     + '`scatter`, `radar`, `treemap` or `sankey`. The check is the exported '
-    + '`checkDashboardWidgetDimensionlessMeasureArity`, and the set it reads is the exported '
+    + '`checkDashboardWidgetChartMeasureArity` (exported as '
+    + '`checkDashboardWidgetDimensionlessMeasureArity` until '
+    + '`dashboard-widget-single-series-multi-measure-refused` gave it a second arm and renamed it), and '
+    + 'the set it reads is the exported '
     + '`DASHBOARD_WIDGET_MULTI_MEASURE_TYPES` — one list, which the check, the refusal text and the '
     + '`values` doc string all read. '
-    + 'WHAT IS NOT, so this is not read as complete: the same seven types WITH a dimension keep '
-    + 'accepting several measures exactly as before (whether that shape renders them all is a '
-    + 'separate question this entry does not answer); one measure parses on every type; every type in '
+    + 'WHAT IS NOT, so this is not read as complete: the same seven types WITH a dimension are '
+    + 'outside THIS entry — `scatter` and `radar` keep accepting several measures with a dimension, and '
+    + '`pie` / `donut` / `funnel` / `treemap` / `sankey` are refused with a dimension too, by '
+    + '`dashboard-widget-single-series-multi-measure-refused`; one measure parses on every type; every type in '
     + '`DASHBOARD_WIDGET_MULTI_MEASURE_TYPES` keeps accepting any number of measures with no '
     + 'dimension; the metric family (`metric` / `kpi` / `gauge` / `solid-gauge` / `bullet`, and a '
     + 'widget that declares no `type`, which resolves to `metric`) keeps its OWN refusal, unchanged '

packages/spec/src/migrations/entries/semantic/18.dashboard-widget-single-series-multi-measure-refused.ts

@@ -0,0 +1,80 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { SemanticMigration } from '../../types.js';
+
+export const entry: SemanticMigration = {
+  id: 'dashboard-widget-single-series-multi-measure-refused',
+  surface: 'dashboard widget measure arity WITH a dimension on a single-series chart type — '
+    + '`dashboard.widgets[].values` (`DashboardWidgetSchema.values`) on a widget whose `dimensions` '
+    + 'declares one or more dimensions and whose `type` is `pie`, `donut`, `funnel`, `treemap` or '
+    + '`sankey`; and the check export `checkDashboardWidgetDimensionlessMeasureArity` (from '
+    + '`@objectstack/spec/ui`), renamed `checkDashboardWidgetChartMeasureArity`',
+  replacement: 'Keep ONE measure on the widget, or pick a visual that renders several. With a '
+    + 'dimension, `type: \'table\'` renders a column per measure and a bar-family type (`bar` / '
+    + '`column` / `horizontal-bar`) renders one bar per measure in each category; both keep the '
+    + 'unbounded `values` they have always had. Or keep the type and give each measure its OWN '
+    + 'widget: a new `id`, the same `dataset` and `dimensions`, that one measure in `values`, and its '
+    + 'own `layout` if the dashboard pins grid positions. ⛔ The migration does not do this for you '
+    + 'and no conversion could: whether a two-measure pie by stage meant a table, a grouped bar chart '
+    + 'or two pies is an authoring choice, and N widgets need N ids and N boxes on a 12-column grid, '
+    + 'which is a LAYOUT decision about a dashboard the registry has never seen. A mirror that '
+    + 'chained the old check export by name imports `checkDashboardWidgetChartMeasureArity` instead: '
+    + 'same signature, same attachment point, and it refuses everything the old name refused.',
+  reason:
+    'Triage\'s ruling on objectui\'s finding that a dimensioned pie draws only its first measure: '
+    + 'the spec refuses, the renderer does not invent. It extends '
+    + '`dashboard-widget-dimensionless-multi-measure-refused`, which applied maintainer ruling D '
+    + '(「协议不正确的应该先修改协议」) to a widget with NO dimension, to the dimensioned arm for '
+    + 'the five types that draw one series whatever the dimension. Measured in objectui\'s shared '
+    + 'chart renderer: the `pie` / `donut`, `funnel`, `treemap` and `sankey` arms each bind the '
+    + 'first series and read no other, so `{ type: \'pie\', dimensions: [\'stage\'], values: '
+    + '[\'revenue\', \'cost\'] }` drew one slice per stage for `revenue` and no trace of `cost` — the '
+    + 'dataset query selects and computes every measure, and all but the first are thrown away. '
+    + 'Every door accepted the document, because the dimensionless rule stepped aside for any '
+    + 'widget that declared a dimension. That is the declared≠delivered shape ADR-0049 exists to '
+    + 'end. A pie of several measures has zero measured pull, so no rendering is invented for it. '
+    + 'The census before the change found zero authored dimensioned multi-measure widgets of the five '
+    + 'types in the platform\'s examples, its first-party dashboards or objectui\'s example apps, so '
+    + 'this ships at once with no deprecation window. Relaxing later is free and needs no second '
+    + 'migration — a type whose renderer gains a declared rendering for several measures with a '
+    + 'dimension leaves the single-series set — while leaving the shape accepted costs an author a '
+    + 'widget that silently drops what they declared. The check export is renamed in the same change '
+    + 'because its old name said a widget with a dimension was outside it, which stopped being true; '
+    + 'no first-party consumer chained it under that name.',
+  acceptanceCriteria:
+    '⚠️ WHICH DOOR: the refusal is the spec\'s, attached at the same point as the dimensionless rule, '
+    + 'so it reaches every door that parses the spec schema — measured on `defineStack`, which throws '
+    + 'naming the widget, and on the stack schema, the dashboard schema and the `dashboard` '
+    + 'metadata-type schema, each refusing at `widgets[N].values`. It is NOT refused by objectui\'s '
+    + 'client-side authoring door until that door chains the export: `@object-ui/types` builds its '
+    + '`DashboardWidgetSchema` from a `.shape` spread of the spec\'s, which carries the FIELDS and '
+    + 'drops every object-level check, so its editor keeps accepting a dimensioned two-measure `pie` '
+    + 'and the author meets the refusal at publish. ⇒ Do not read a green editor as a clean '
+    + 'dashboard; re-parse through the spec. '
+    + '⚠️ AND THE TODO CANNOT NAME YOUR MEASURES: a `SemanticMigration` is static prose emitted once '
+    + 'per hop, with no per-document interpolation and no filtering by whether the stack carries the '
+    + 'shape, so `os migrate meta` prints THIS paragraph, not a list of your widgets. The refusal is '
+    + 'what names them, per widget, on the re-parse — drive the fix off `os validate`, not off the '
+    + 'migrate output. '
+    + 'WHAT IS REFUSED, exactly: ONE `custom` issue at `widgets[N].values`, naming the widget\'s '
+    + '`id`, the number of measures and the authored `type`, and saying the type draws one series '
+    + 'whatever its `dimensions`, when `dimensions` declares at least one dimension, `values` carries '
+    + 'two or more measures, and `type` is `pie`, `donut`, `funnel`, `treemap` or `sankey`. The check '
+    + 'is the exported `checkDashboardWidgetChartMeasureArity` — the dimensionless rule\'s own check, '
+    + 'with a second arm; the single-series set it reads is not exported, and the refusal prints it. '
+    + 'WHAT IS NOT, so this is not read as complete: `scatter` and `radar` WITH a dimension keep '
+    + 'accepting several measures exactly as before (the ruling named the five: `radar` draws every '
+    + 'series, and `scatter` says on the chart that it draws one); every type in '
+    + '`DASHBOARD_WIDGET_MULTI_MEASURE_TYPES` keeps accepting any number of measures with a dimension; '
+    + 'one measure parses on every type; a DIMENSIONLESS widget of the five keeps the dimensionless '
+    + 'refusal, word for word and still ONE issue; the metric family (`metric` / `kpi` / `gauge` / '
+    + '`solid-gauge` / `bullet`, and a widget that declares no `type`, which resolves to `metric`) '
+    + 'keeps its OWN refusal, unchanged; an EMPTY `values` keeps the field\'s own `too_small`; a '
+    + '`type` outside `ChartTypeSchema` reports the TYPE refusal alone, and called directly on a '
+    + 'wider type enum the export judges only the types the spec declares; and whether each measure '
+    + 'EXISTS in the bound dataset is still unreachable from this schema. '
+    + 'VERIFY by re-parsing each dashboard: a dashboard that had one two-measure `pie` by stage should '
+    + 'end with a `table` or bar-family widget carrying both measures, or with two widgets of one '
+    + 'measure each — check the rendered grid afterwards, because the second measure is a number the '
+    + 'dashboard was ALREADY paying to compute and had never shown.',
+};