@@ -0,0 +1,17 @@
+---
+'@objectstack/spec': minor
+---
+
+feat(spec)!: a report chart's `seriesBy` that cannot split is refused at authoring time — on a single-series chart type, or naming the same dimension as `xAxis`
+
+Clause-②: yes (narrowing)
+Metadata-protocol: narrowed
+
+<!-- adr-0087: not-required (no-migration-prescription) No key of any schema is added, removed, renamed or re-shaped: two combinations of existing values that no renderer could draw are now refused. A conversion cannot know whether the author meant a bar chart or one series, so there is nothing for a migration to rewrite; the refusal text names both fixes. -->
+
+**BREAKING** for two report chart shapes, both of which parsed before and then failed on the page. `ReportSchema` (non-`joined` reports; a joined report's `chart` is refused whole, as before) now refuses, at `chart.seriesBy`:
+
+- **`seriesBy` on a single-series type** — `pie`, `donut`, `funnel`, `treemap` or `sankey`. The split derives one series per value of the `seriesBy` dimension and these types draw one series, so the page showed a refusal panel instead of the chart. The refusal names the report, the type and the split. Fix: a bar-family type (`bar` / `column` / `horizontal-bar`) for one bar per split value in each `xAxis` category, or drop `seriesBy` to keep the single-series chart. This is the report spelling of the rule dashboards already apply to a dimensioned widget with several measures on the same types.
+- **`seriesBy` naming the same dimension as `xAxis`** — every series held exactly one point. Fix: name a different dimension than `xAxis`, or drop `seriesBy`.
+
+`SINGLE_SERIES_CHART_TYPES` is now exported from `@objectstack/spec/ui` (the list `checkDashboardWidgetChartMeasureArity` reads); the report refusal reads the same constant, so the two doors cannot drift apart.
@@ -104,7 +104,7 @@ const result = JoinedReportBlockSchema.parse(data);
 | **annotations** | `{ type?: Enum<'line' \| 'region'>; axis?: Enum<'x' \| 'y'>; value: number \| string; endValue?: number \| string; … }[]` | optional | Reference lines/bands drawn over the plot: `{ type: "line" \| "region", axis: "x" \| "y", value, endValue?, color?, label?, style? }` |
 | **interaction** | `{ tooltips?: boolean; brush?: boolean }` | optional | Interaction toggles: `{ tooltips?, brush? }` |
 | **aria** | `never` | optional | [REMOVED] `ChartConfig.aria` — authored as `dashboard.widgets[].chartConfig.aria`, `report.chart.aria` and `report.blocks[].chart.aria` — was removed in @objectstack/spec 17 (ADR-0049 D2). No chart renderer ever applied it: the chart implementation declares no `aria` prop, the presentation lowering names it nowhere, and the react `<ObjectChart>` block never published it, so ARIA attributes declared here parsed and then silently did not reach the DOM. Delete the key. The accessible name that IS applied on this same chart config is its sibling `description`, which the chart renderer lowers onto the chart graphic as `role="img"` plus `aria-label`. The shared `AriaProps` shape is NOT gone — `ariaLabel` / `ariaDescribedBy` / `role` stay live in the `aria` block on `page.aria`, `page.components[].aria` and the list view `aria`. Run `os migrate meta --from 17` to list the mechanical edits for existing sources; `--write` applies the ones it can prove, and you apply the rest by hand. |
-| **seriesBy** | `string` | optional | Dataset dimension name that splits the yAxis measure into one series per value of it (bound-dataset dimension, not a raw field); with it set, `series[].name` names a value of this dimension |
+| **seriesBy** | `string` | optional | Dataset dimension name that splits the yAxis measure into one series per value of it (bound-dataset dimension, not a raw field); with it set, `series[].name` names a value of this dimension. Refused on a single-series type (pie/donut/funnel/treemap/sankey) and when it names the xAxis dimension |
 
 ### Nested Shape: `Report.dateRange`
 
@@ -168,7 +168,7 @@ const result = JoinedReportBlockSchema.parse(data);
 | **annotations** | `{ type?: Enum<'line' \| 'region'>; axis?: Enum<'x' \| 'y'>; value: number \| string; endValue?: number \| string; … }[]` | optional | Reference lines/bands drawn over the plot: `{ type: "line" \| "region", axis: "x" \| "y", value, endValue?, color?, label?, style? }` |
 | **interaction** | `{ tooltips?: boolean; brush?: boolean }` | optional | Interaction toggles: `{ tooltips?, brush? }` |
 | **aria** | `never` | optional | [REMOVED] `ChartConfig.aria` — authored as `dashboard.widgets[].chartConfig.aria`, `report.chart.aria` and `report.blocks[].chart.aria` — was removed in @objectstack/spec 17 (ADR-0049 D2). No chart renderer ever applied it: the chart implementation declares no `aria` prop, the presentation lowering names it nowhere, and the react `<ObjectChart>` block never published it, so ARIA attributes declared here parsed and then silently did not reach the DOM. Delete the key. The accessible name that IS applied on this same chart config is its sibling `description`, which the chart renderer lowers onto the chart graphic as `role="img"` plus `aria-label`. The shared `AriaProps` shape is NOT gone — `ariaLabel` / `ariaDescribedBy` / `role` stay live in the `aria` block on `page.aria`, `page.components[].aria` and the list view `aria`. Run `os migrate meta --from 17` to list the mechanical edits for existing sources; `--write` applies the ones it can prove, and you apply the rest by hand. |
-| **seriesBy** | `string` | optional | Dataset dimension name that splits the yAxis measure into one series per value of it (bound-dataset dimension, not a raw field); with it set, `series[].name` names a value of this dimension |
+| **seriesBy** | `string` | optional | Dataset dimension name that splits the yAxis measure into one series per value of it (bound-dataset dimension, not a raw field); with it set, `series[].name` names a value of this dimension. Refused on a single-series type (pie/donut/funnel/treemap/sankey) and when it names the xAxis dimension |
 
 ### Allowed Values: `ReportChart.type`
 
 
@@ -429,6 +429,7 @@
     "RowHeight (type)",
     "RowHeightSchema (const)",
     "SECTION_HEADING_COUNT_HOLE (const)",
+    "SINGLE_SERIES_CHART_TYPES (const)",
     "STRING_ARM_REGISTERED_TYPES (const)",
     "SelectionConfig (type)",
     "SelectionConfigParsed (type)",
 
@@ -412,6 +412,7 @@
     "RowHeight": "src/ui/view.zod.ts#RowHeight (type)",
     "RowHeightSchema": "src/ui/view.zod.ts#RowHeightSchema (const)",
     "SECTION_HEADING_COUNT_HOLE": "src/ui/component.zod.ts#SECTION_HEADING_COUNT_HOLE (const)",
+    "SINGLE_SERIES_CHART_TYPES": "src/ui/dashboard.zod.ts#SINGLE_SERIES_CHART_TYPES (const)",
     "STRING_ARM_REGISTERED_TYPES": "src/ui/component-type-vocabulary.ts#STRING_ARM_REGISTERED_TYPES (const)",
     "SelectionConfig": "src/ui/view.zod.ts#SelectionConfig (type)",
     "SelectionConfigParsed": "src/ui/view.zod.ts#SelectionConfigParsed (type)",
 
@@ -780,10 +780,12 @@ export const DASHBOARD_WIDGET_MULTI_MEASURE_TYPES = [
 
 /**
  * The chart `type`s that draw ONE series whatever the widget's `dimensions` —
- * the single-series set. Module-private, like the metric family's list above,
- * and the only list of it in this package:
- * {@link checkDashboardWidgetChartMeasureArity} reads it, that check's refusal
- * text reads it, and the `values` doc string reads it.
+ * the single-series set. One exported constant, and the only list of it in
+ * this package: {@link checkDashboardWidgetChartMeasureArity} reads it, that
+ * check's refusal text reads it, the `values` doc string reads it, and the
+ * report's chart reads it too — `ReportSchema` refuses a `chart.seriesBy`
+ * split on any of these types, since the split derives one series per value
+ * and these types draw one. Import it; ⛔ never restate it.
  *
  * Measured in objectui's shared chart renderer (`AdvancedChartImpl` in
  * `@object-ui/plugin-charts`; recorded in `packages/spec/liveness/dashboard.json`,
@@ -805,7 +807,7 @@ export const DASHBOARD_WIDGET_MULTI_MEASURE_TYPES = [
  * remove a member to make a document parse — only when a renderer draws every
  * measure.
  */
-const SINGLE_SERIES_CHART_TYPES = [
+export const SINGLE_SERIES_CHART_TYPES = [
   'pie',
   'donut',
   'funnel',
 
@@ -12,6 +12,8 @@ import {
   defineReport,
 } from './report.zod';
 import { strictObjectDeclarations } from '../shared/strict-object';
+import { SINGLE_SERIES_CHART_TYPES } from './dashboard.zod';
+import { ChartTypeSchema } from './chart.zod';
 import { getMetadataTypeSchema } from '../kernel/metadata-type-schemas';
 
 /**
@@ -580,3 +582,66 @@ describe('ReportChartSchema', () => {
     expect(r.error?.issues.map((i) => i.path.join('.'))).toContain('seriesBy');
   });
 });
+
+/**
+ * A `chart.seriesBy` split that cannot split is refused at authoring time, on
+ * the report, at `chart.seriesBy` — not drawn as a refusal panel on the page.
+ * Two arms: a single-series `type` (the dashboard's `SINGLE_SERIES_CHART_TYPES`,
+ * one source), and `seriesBy` naming the `xAxis` dimension. Non-joined only.
+ */
+describe('ReportSchema refuses a chart `seriesBy` that cannot split', () => {
+  const report = (chart: Record<string, unknown>, extra: Record<string, unknown> = {}) => ({
+    name: 'pipeline_by_owner', label: 'Pipeline', type: 'summary',
+    dataset: 'opportunities', rows: ['owner'], values: ['amount'],
+    chart: { xAxis: 'owner', yAxis: 'amount', ...chart },
+    ...extra,
+  });
+  const splitIssues = (doc: unknown) => {
+    const r = ReportSchema.safeParse(doc);
+    return r.success ? [] : r.error.issues.filter((i) => i.path.join('.') === 'chart.seriesBy');
+  };
+
+  it.each(['pie', 'donut', 'funnel'])('refuses `seriesBy` on a `%s` chart, naming the report, the type and the split', (type) => {
+    const issues = splitIssues(report({ type, seriesBy: 'stage' }));
+    expect(issues).toHaveLength(1);
+    expect(issues[0].code).toBe('custom');
+    expect(issues[0].message).toContain('`pipeline_by_owner`');
+    expect(issues[0].message).toContain(`\`type: '${type}'\``);
+    expect(issues[0].message).toContain("`seriesBy: 'stage'`");
+    expect(issues[0].message).toContain('`bar` / `column` / `horizontal-bar`');
+  });
+
+  it('refuses `seriesBy` naming the same dimension as `xAxis`', () => {
+    const issues = splitIssues(report({ type: 'bar', seriesBy: 'owner' }));
+    expect(issues).toHaveLength(1);
+    expect(issues[0].code).toBe('custom');
+    expect(issues[0].message).toContain("`seriesBy: 'owner'`");
+    expect(issues[0].message).toContain('`seriesBy` must name a different dimension than `xAxis`');
+  });
+
+  it('controls: `bar` / `line` with a distinct `seriesBy` parse, and a `pie` without one parses', () => {
+    for (const type of ['bar', 'line']) {
+      const r = ReportSchema.safeParse(report({ type, seriesBy: 'stage' }));
+      expect(r.success, `${type} split by stage`).toBe(true);
+      expect(r.data?.chart?.seriesBy).toBe('stage');
+    }
+    expect(ReportSchema.safeParse(report({ type: 'pie' })).success, 'pie, one series').toBe(true);
+  });
+
+  it('a joined report is untouched — its `chart` refusal stands alone, at `chart`', () => {
+    const joined = {
+      name: 'joined_pipeline', label: 'Joined', type: 'joined',
+      blocks: [{ name: 'open_block', type: 'summary', dataset: 'opportunities', rows: ['owner'], values: ['amount'] }],
+      chart: { type: 'pie', xAxis: 'owner', yAxis: 'amount', seriesBy: 'owner' },
+    };
+    const r = ReportSchema.safeParse(joined);
+    expect(r.success).toBe(false);
+    expect(r.error?.issues.map((i) => i.path.join('.'))).toEqual(['chart']);
+  });
+
+  it('one source: the refused type set is exactly the dashboard\'s SINGLE_SERIES_CHART_TYPES', () => {
+    const refused = ChartTypeSchema.options.filter((type) => splitIssues(report({ type, seriesBy: 'stage' })).length > 0);
+    expect([...refused].sort()).toEqual([...SINGLE_SERIES_CHART_TYPES].sort());
+    expect(refused.length).toBeGreaterThan(0);
+  });
+});
@@ -5,7 +5,7 @@ import { ProtectionSchema } from '../shared/protection.zod';
 import { MetadataProtectionFields } from '../kernel/metadata-protection.zod';
 import { analyticsCarrierFilter } from './analytics-carrier-filter';
 import { ChartConfigSchema } from './chart.zod';
-import { DATE_RANGE_DEFAULT_RANGES } from './dashboard.zod';
+import { DATE_RANGE_DEFAULT_RANGES, SINGLE_SERIES_CHART_TYPES } from './dashboard.zod';
 import { ReportExportOptionsSchema } from './list-view-export-options';
 import { SnakeCaseIdentifierSchema } from '../shared/identifiers.zod';
 import { I18nLabelSchema } from './i18n.zod';
@@ -47,10 +47,13 @@ export const ReportChartSchema = lazySchema(() => ChartConfigSchema.extend({
   /**
    * Dataset **dimension** name whose values split the `yAxis` measure into one
    * series each (from the report's bound dataset). Omitted = one series.
+   * `ReportSchema` refuses it on a single-series `type` and when it names the
+   * `xAxis` dimension (`checkReportChartSeriesSplit`).
    */
   seriesBy: z.string().optional().describe(
     'Dataset dimension name that splits the yAxis measure into one series per value of it '
-    + '(bound-dataset dimension, not a raw field); with it set, `series[].name` names a value of this dimension',
+    + '(bound-dataset dimension, not a raw field); with it set, `series[].name` names a value of this dimension. '
+    + 'Refused on a single-series type (' + SINGLE_SERIES_CHART_TYPES.join('/') + ') and when it names the xAxis dimension',
   ),
 }));
 
@@ -140,6 +143,65 @@ function checkReportOrder(
   }
 }
 
+/**
+ * Refuse a `chart.seriesBy` split that cannot split — on a non-`joined`
+ * report (a joined report's `chart` is refused whole, so this never reaches
+ * one). Two arms, both refusals with no valid reading, at `chart.seriesBy`:
+ *
+ *  1. **Single-series arm** — `chart.type` is in `SINGLE_SERIES_CHART_TYPES`
+ *     (imported from `dashboard.zod.ts`, never restated). The split derives one
+ *     series per value of the `seriesBy` dimension and these types draw one
+ *     series, so the renderer draws its one-series refusal panel where the
+ *     chart should be. The dashboard's spelling of the same split (a widget
+ *     with a dimension and several measures on these types) is refused by
+ *     `checkDashboardWidgetChartMeasureArity` — objectui#8894 ruling D; this
+ *     is the report's spelling of it.
+ *  2. **Same-dimension arm** — `seriesBy` names the `xAxis` dimension. The
+ *     selection `[xAxis, seriesBy]` then groups by one dimension twice, so
+ *     every derived series holds exactly one point, and the chart reads as
+ *     broken with nothing saying why.
+ *
+ * The arms are exclusive: on a single-series type the first one answers,
+ * since dropping `seriesBy` is the fix for both. Whether `seriesBy` names a
+ * dimension the bound dataset DECLARES is not reachable from this schema; that
+ * is `@objectstack/lint`'s `validateChartBindings`.
+ */
+function checkReportChartSeriesSplit(
+  r: { name?: unknown; chart?: { type?: unknown; xAxis?: unknown; seriesBy?: unknown } },
+  ctx: z.RefinementCtx,
+): void {
+  const chart = r.chart;
+  if (!chart || typeof chart.seriesBy !== 'string') return;
+  const { type, xAxis, seriesBy } = chart;
+  const report = typeof r.name === 'string' && r.name.length > 0 ? `Report \`${r.name}\`` : 'This report';
+
+  if (typeof type === 'string' && (SINGLE_SERIES_CHART_TYPES as readonly string[]).includes(type)) {
+    const singleSeriesTypes = SINGLE_SERIES_CHART_TYPES.map((t) => '`' + t + '`').join(' / ');
+    ctx.addIssue({
+      code: 'custom',
+      path: ['chart', 'seriesBy'],
+      message:
+        `${report} splits its \`type: '${type}'\` chart by \`seriesBy: '${seriesBy}'\`, but \`${type}\` is a `
+        + `single-series type (${singleSeriesTypes}) that draws ONE series, so the split into one series `
+        + `per \`${seriesBy}\` value has nowhere to go and the page shows a refusal instead of the chart. `
+        + `Write a bar-family type (\`bar\` / \`column\` / \`horizontal-bar\`) for one bar per \`${seriesBy}\` `
+        + `value in each \`xAxis\` category, or drop \`seriesBy\` to keep the \`${type}\`.`,
+    });
+    return;
+  }
+
+  if (seriesBy === xAxis) {
+    ctx.addIssue({
+      code: 'custom',
+      path: ['chart', 'seriesBy'],
+      message:
+        `${report} splits its chart by \`seriesBy: '${seriesBy}'\`, the same dimension as its \`xAxis\`, so `
+        + 'every series holds exactly one point. `seriesBy` must name a different dimension than `xAxis` '
+        + '— the one each `xAxis` category is split by — or be dropped for one series.',
+    });
+  }
+}
+
 /**
  * Lower a report's authored `order` into the `DatasetSelection.order` a
  * preview/query request posts (framework#3916).
@@ -765,6 +827,7 @@ export const ReportSchema = lazySchema(() => strictObject({
     }
   } else {
     checkReportOrder(r, ctx);
+    checkReportChartSeriesSplit(r, ctx);
   }
 }));