@@ -0,0 +1,16 @@
+---
+'@objectstack/spec': minor
+'@objectstack/lint': minor
+---
+
+feat(spec): a report chart can split its bars by a second dataset dimension with `chart.seriesBy`
+
+Clause-②: yes (widening)
+Metadata-protocol: added
+
+`ReportChartSchema` declares one optional key, `seriesBy`: the name of a second dimension of the report's bound dataset. It splits the chart's one `yAxis` measure into a series per value of that dimension, so a report can draw a bar per owner split by stage. It is the report's spelling of a dashboard widget's two-entry `dimensions` selection. With `seriesBy` set, a `chart.series[]` entry's `name` names a value of that dimension, because each derived series is one value.
+
+- **Lint.** `os validate`, `os build` and the report publish door resolve `chart.seriesBy` against the dataset's declared dimensions exactly as they resolve `chart.xAxis`: an undeclared name is a `chart-dimension-unknown` error with the nearest declared dimension suggested. When `seriesBy` is set, `chart.series[].name` is no longer judged against the chart's measure, since it names a dimension value.
+- **Liveness.** The key is graded `planned` with an author warning: this is the contract half, and the report chart still draws one series until the renderer reads `seriesBy` in a later change.
+
+Nothing to do for existing reports. A chart without `seriesBy` parses and draws exactly as before.
@@ -104,6 +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 |
 
 ### Nested Shape: `Report.dateRange`
 
@@ -167,6 +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 |
 
 ### Allowed Values: `ReportChart.type`
 
 
@@ -3306,7 +3306,9 @@ const CHART_AXIS_NOT_SELECTED_EXPLANATION: RuleExplanation = {
       'exactly one dimension × one measure and derives ONE series, while `report.values` is the ' +
       'selection of the table beneath it. So a report\'s `chart.yAxis` is never reported — a chart ' +
       'cannot fail to select what it queries — and a `chart.series[].name` override lands only when ' +
-      'it names `chart.yAxis`. The verdict quotes at most three names of the selection.',
+      'it names `chart.yAxis`. With `chart.seriesBy` set the chart derives one series per value of ' +
+      'that dimension, so an override names a value, which no static check can see, and is not ' +
+      'judged. The verdict quotes at most three names of the selection.',
     CHART_BINDING_SURFACES,
   ],
 };
 
@@ -128,6 +128,49 @@ describe('validateChartBindings — report charts', () => {
     expect(findings[0].path).toBe('reports[0].chart.xAxis');
   });
 
+  // #27974 — the split dimension is resolved exactly like `xAxis`, so a
+  // misspelled one is refused at publish rather than silently plotting one series.
+  it('errors on a seriesBy naming an undeclared dimension, and passes a declared one', () => {
+    const report = (seriesBy: string) => ({
+      ...baseStack(),
+      reports: [
+        {
+          name: 'r',
+          dataset: 'task_metrics',
+          values: ['task_count'],
+          chart: { type: 'bar', xAxis: 'status', yAxis: 'task_count', seriesBy },
+        },
+      ],
+    });
+    expect(validateChartBindings(report('priority')), 'control: a declared dimension').toEqual([]);
+    const findings = validateChartBindings(report('priorty'));
+    expect(findings).toHaveLength(1);
+    expect(findings[0].severity).toBe('error');
+    expect(findings[0].rule).toBe(CHART_DIMENSION_UNKNOWN);
+    expect(findings[0].path).toBe('reports[0].chart.seriesBy');
+    expect(findings[0].hint).toContain('Did you mean "priority"?');
+  });
+
+  // With `seriesBy` set the derived series are the split dimension's VALUES,
+  // so an override's `name` names a value — not a measure, and not judged.
+  it('does not judge `series[].name` against the measures when `seriesBy` splits the chart', () => {
+    const chart = (extra: Record<string, unknown>) => ({
+      ...baseStack(),
+      reports: [
+        {
+          name: 'r',
+          dataset: 'task_metrics',
+          values: ['task_count'],
+          chart: { type: 'bar', xAxis: 'status', yAxis: 'task_count', series: [{ name: 'high', label: 'High' }], ...extra },
+        },
+      ],
+    });
+    // Control: without the split, `high` is no declared measure and warns.
+    const unsplit = validateChartBindings(chart({}));
+    expect(unsplit.map((f) => [f.rule, f.path])).toEqual([[CHART_MEASURE_UNKNOWN, 'reports[0].chart.series[0].name']]);
+    expect(validateChartBindings(chart({ seriesBy: 'priority' }))).toEqual([]);
+  });
+
   // #15734 — this fixture WARNED until the set moved, and this pin held the
   // warning in place. At the pinned `@object-ui` revision the embedded chart
   // runs its OWN query out of the axis pair — `useDatasetRows(dataset,
 
@@ -19,6 +19,8 @@
  *      object/array shapes to bare STRINGS, which is why simply pointing the
  *      dashboard rule at reports would find nothing: its `Array.isArray(yAxis)`
  *      guard skips a string silently. `series[].name` keeps the array shape.
+ *      `seriesBy`, the optional split dimension, is a string dimension ref
+ *      like `xAxis` and is resolved the same way.
  *      A `joined` report draws no chart (#20161): its container `chart` is
  *      refused by `ReportSchema` and a block has no `chart` key, so neither is
  *      a binding this rule checks. Checking one would tell the author their
@@ -269,6 +271,8 @@ interface ChartBinding {
   values?: { names: string[]; path: string };
   /** Single dimension ref (report `xAxis`). */
   xAxis?: { name: string; path: string };
+  /** Single dimension ref (report `seriesBy`, the split dimension). */
+  seriesBy?: { name: string; path: string };
   /** Single measure ref (report `yAxis`). */
   yAxis?: { name: string; path: string };
   /**
@@ -501,6 +505,7 @@ export function validateChartBindings(stack: AnyRec): ChartBindingFinding[] {
       }
     }
     if (binding.xAxis) dimensionRef(binding.xAxis.name, binding.xAxis.path);
+    if (binding.seriesBy) dimensionRef(binding.seriesBy.name, binding.seriesBy.path);
     // No selection is passed at this position: the report `yAxis` IS the query
     // the chart issues, so it cannot name a measure that query does not ask
     // for (#15734). The `chart-measure-unknown` half still runs — an undeclared
@@ -576,15 +581,22 @@ export function validateChartBindings(stack: AnyRec): ChartBindingFinding[] {
       if (!isRec(chart)) return;
       const xAxisName = strName(chart.xAxis);
       const yAxisName = strName(chart.yAxis);
+      const seriesByName = strName(chart.seriesBy);
       checkAgainst(ds, dsName, {
         xAxis: xAxisName ? { name: xAxisName, path: `${path}.chart.xAxis` } : undefined,
         yAxis: yAxisName ? { name: yAxisName, path: `${path}.chart.yAxis` } : undefined,
+        // The split dimension is a dimension ref exactly like `xAxis`: the
+        // chart's query groups by it, so an undeclared name is no column.
+        seriesBy: seriesByName ? { name: seriesByName, path: `${path}.chart.seriesBy` } : undefined,
         // The chart's own selection: the ONE measure it queries and derives a
         // series from. Empty when no `yAxis` is authored — the chart plots
         // nothing at all then, which the shape rules own, so no override can
         // be reported as landing on nothing.
         ownSelection: yAxisName ? [yAxisName] : [],
-        series: recordsOf(chart.series)
+        // With `seriesBy` set the chart derives one series per VALUE of that
+        // dimension, so a `series[].name` override names a value — data no
+        // static check can see — and is not judged against any measure set.
+        series: seriesByName ? [] : recordsOf(chart.series)
           .map((s, si) => ({
             name: strName(s.name),
             path: `${path}.chart.series[${si}].name`,
 
@@ -1260,6 +1260,7 @@
     "ui/ReportChart:height",
     "ui/ReportChart:interaction",
     "ui/ReportChart:series",
+    "ui/ReportChart:seriesBy",
     "ui/ReportChart:showDataLabels",
     "ui/ReportChart:showLegend",
     "ui/ReportChart:subtitle",
 
@@ -51,7 +51,24 @@
     "chart": {
       "status": "live",
       "verifiedAt": "2026-09-27",
-      "note": "objectui: DatasetReportChart plots `chart.xAxis` (dataset dimension) × `chart.yAxis` (measure) via useDatasetRows, honoring `type`/`title` (framework#1890/#3441). Supersedes the 2026-06 audit's DEAD finding. Sub-key `groupBy` stays experimental (its own describe marker) — the dataset renderer plots a single series and never reads it. Live on NON-joined reports only (#20161, re-read at the `.objectui-sha` pin f8a9d0fb): the one `report.chart` read (DatasetReportRenderer.tsx:1557) sits after the joined branch's return (:1462-1524), so on a `type: 'joined'` report the schema's refinement REFUSES `chart` rather than accepting a key nothing reads. A `joined` report draws no chart (packages/spec/src/ui/report.zod.ts, the joined-chart prescription, #20161; read point moved out of spec source, #23434): at objectui @f8a9d0fb0596 packages/plugin-report/src/DatasetReportRenderer.tsx#DatasetReportRenderer the joined branch draws each block as a `DatasetMatrixTable` / `DatasetReportTable` and returns before the one `report.chart` read, and no renderer reads a block's `chart`."
+      "note": "objectui: DatasetReportChart plots `chart.xAxis` (dataset dimension) × `chart.yAxis` (measure) via useDatasetRows, honoring `type`/`title` (framework#1890/#3441). Supersedes the 2026-06 audit's DEAD finding. Sub-key `groupBy` stays experimental (its own describe marker) — the dataset renderer plots a single series and never reads it. Live on NON-joined reports only (#20161, re-read at the `.objectui-sha` pin f8a9d0fb): the one `report.chart` read (DatasetReportRenderer.tsx:1557) sits after the joined branch's return (:1462-1524), so on a `type: 'joined'` report the schema's refinement REFUSES `chart` rather than accepting a key nothing reads. A `joined` report draws no chart (packages/spec/src/ui/report.zod.ts, the joined-chart prescription, #20161; read point moved out of spec source, #23434): at objectui @f8a9d0fb0596 packages/plugin-report/src/DatasetReportRenderer.tsx#DatasetReportRenderer the joined branch draws each block as a `DatasetMatrixTable` / `DatasetReportTable` and returns before the one `report.chart` read, and no renderer reads a block's `chart`.",
+      "childrenDefault": "live",
+      "children": {
+        "aria": {
+          "status": "dead",
+          "verifiedAt": "2026-10-30",
+          "note": "REMOVED in @objectstack/spec 17 (ADR-0049 D2; the `chart-config-aria-removed` conversion): `ChartConfigSchema` tombstones it with retiredKey, so authoring `report.chart.aria` is a tsc error and a parse error carrying the prescription (use `description` on this same chart config). The row exists because the tombstone keeps the key in the walked shape now that `chart` drills; the retirement record is `dashboard.json`'s `widgets.chartConfig.aria` row."
+        },
+        "seriesBy": {
+          "status": "planned",
+          "verifiedAt": "2026-10-30",
+          "evidenceScope": "in-repo",
+          "evidence": "packages/spec/src/ui/report.zod.ts#ReportChartSchema (declares `seriesBy`, an optional dataset dimension name); packages/lint/src/validate-chart-bindings.ts#validateChartBindings (resolves it against the report's bound dataset dimensions exactly as `xAxis`, `chart-dimension-unknown` at error, at os validate / os build and the report publish door)",
+          "authorWarn": true,
+          "authorHint": "Keep it, but nothing draws it yet: the report chart still draws a single series, and the split by this dimension appears once the report renderer reads `seriesBy`.",
+          "note": "Spec half of the report chart series split (#27974): a second dataset dimension that splits the one `yAxis` measure into a series per value, the report's spelling of a dashboard widget's two-entry `dimensions` selection. Planned because the renderer half is a follow-up: at this tree ui/packages/plugin-report/src/DatasetReportRenderer.tsx#DatasetReportChart still queries `[xAxis]` × `[yAxis]` and hands `buildChartSeries` one dimension, so the split is not drawn. The other children of `chart` inherit the row's `live` verdict through `childrenDefault`; this row exists to keep that blanket from vouching for the one key nothing reads yet. Flip to `live` with the renderer card."
+        }
+      }
     },
     "dateRange": {
       "status": "live",
 
@@ -12,4 +12,4 @@ committed anywhere: `check:liveness` sums the shards when it reads them.
 
 | Type | live | exp | elsewhere | dead | planned | classified |
 |---|---|---|---|---|---|---|
-| `report` | 27 | 0 | 0 | 0 | 0 | 27 |
+| `report` | 39 | 0 | 0 | 1 | 1 | 41 |
@@ -119,7 +119,9 @@
     "query/groupBy",
     "query/orderBy",
     "report/blocks",
-    "report/chart",
+    "report/chart.annotations",
+    "report/chart.interaction",
+    "report/chart.series",
     "report/order",
     "skill/triggerConditions",
     "translation/apps",
 
@@ -370,10 +370,12 @@ describe('批 15 — the five closed chart sites', () => {
 
   it('strictness RIDES `.extend()` onto ReportChartSchema — the webhook/view trap, here on purpose', () => {
     // `.extend()` inherits `.strict()` AND the error map. `ReportChartSchema`
-    // narrows xAxis/yAxis to dataset names and adds no key of its own, so the
-    // inherited key set is exactly right — but that has to be asserted, not
-    // assumed, because the same mechanic is what made finding 16 a finding.
+    // narrows xAxis/yAxis to dataset names and adds one key of its own
+    // (`seriesBy`), so the key set is the inherited one plus that — but that
+    // has to be asserted, not assumed, because the same mechanic is what made
+    // finding 16 a finding.
     expect(ReportChartSchema.safeParse({ type: 'bar', xAxis: 'dim', yAxis: 'measure' }).success, 'control').toBe(true);
+    expect(ReportChartSchema.safeParse({ type: 'bar', xAxis: 'dim', yAxis: 'measure', seriesBy: 'dim2' }).success, 'own key').toBe(true);
     const msg = reject(ReportChartSchema as never, { type: 'bar', xAxis: 'd', yAxis: 'm', chartType: 'bar' });
     expect(msg).toContain('chartType');
     expect(msg, 'the base error map rides too, so the report surface gets the rename').toContain('`chartType` → `type`');