feat(cli): dashboard widget reference integrity (dataset → dimensions/measures + chartConfig)

Closes #1721. The ADR-0021 single-form cutover makes every DashboardWidget
select its dataset's dimensions/measures BY NAME, but nothing validated
those references — a widget could name a dataset that doesn't exist, a
measure the dataset never declares, or point chartConfig.yAxis[].field at
a stale base column, and validate/lint/doctor/build all stayed green while
the page rendered an empty series. Downstream this broke 36 widgets across
11 template dashboards (templates#27, templates#30) with a green build.

`validateWidgetBindings()` (the #1719 semantic pass) now returns
severity-carrying findings:

errors — the binding cannot be satisfied; validate and build FAIL:
- widget-dataset-unknown    `dataset` resolves to no declared Dataset
- widget-dimension-unknown  a `dimensions[]` entry isn't a dataset dimension
- widget-measure-unknown    a `values[]` entry isn't a dataset measure
- chart-field-unknown       chartConfig xAxis.field doesn't resolve to a
  dataset dimension, or yAxis[].field / series[].name doesn't resolve to a
  measure selected in `values` (post-cutover rows are keyed by measure
  NAME, e.g. sum_amount — not the base column amount)

warnings — advisory, suppressible per widget via suppressWarnings:
- chart-config-missing      chart-type widget with no chartConfig (renders
  an empty series on chartConfig-driven renderers; templates#30 verified
  in-browser that adding the mapping fixes it)
- table-count-only          unchanged from #1719

Errors are not suppressible, and messages carry the declared-name list
plus a did-you-mean suggestion (containment-first, so amount → sum_amount).
Surfaces: validate + compile fail on errors (human + --json), lint passes
severity through, doctor gains a "Dashboard integrity" section mirroring
the orphan-view pass. A chartConfig field naming an already-invalid
selection entry is not double-reported — rules (b)/(c) own that error.

The example apps' chart widgets now carry explicit chartConfig (the
authoring shape templates#30 standardized on; objectui HEAD derives series
from `values` and ignores it, so this is compatible both ways). app-todo's
two count-only record-listing tables still warn — that re-modeling to
ListViews (ADR-0017) is #1719 territory, left as a follow-up.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: os-zhuang

examples/app-crm/src/dashboards/pipeline.dashboard.ts

@@ -90,6 +90,15 @@ export const PipelineDashboard: Dashboard = {
       dataset: 'opportunity_metrics',
       dimensions: ['close_date'],
       values: ['opp_count'],
+      // Axis fields name the dataset's dimension/measure (NOT base columns) —
+      // post-cutover query rows are keyed by measure name (issue #1721).
+      chartConfig: {
+        type: 'line',
+        xAxis: { field: 'close_date', showGridLines: true, logarithmic: false },
+        yAxis: [{ field: 'opp_count', showGridLines: true, logarithmic: false }],
+        showLegend: true,
+        showDataLabels: false,
+      },
       layout: { x: 0, y: 2, w: 8, h: 4 },
     },
     {
@@ -107,6 +116,13 @@ export const PipelineDashboard: Dashboard = {
       dataset: 'opportunity_metrics',
       dimensions: ['stage'],
       values: ['opp_count'],
+      chartConfig: {
+        type: 'bar',
+        xAxis: { field: 'stage', showGridLines: true, logarithmic: false },
+        yAxis: [{ field: 'opp_count', showGridLines: true, logarithmic: false }],
+        showLegend: true,
+        showDataLabels: false,
+      },
       layout: { x: 8, y: 2, w: 4, h: 4 },
     },
 
@@ -120,6 +136,13 @@ export const PipelineDashboard: Dashboard = {
       dataset: 'opportunity_metrics',
       dimensions: ['stage'],
       values: ['total_amount'],
+      chartConfig: {
+        type: 'pie',
+        xAxis: { field: 'stage', showGridLines: true, logarithmic: false },
+        yAxis: [{ field: 'total_amount', showGridLines: true, logarithmic: false }],
+        showLegend: true,
+        showDataLabels: false,
+      },
       layout: { x: 0, y: 6, w: 6, h: 4 },
     },
   ],

examples/app-showcase/src/dashboards/chart-gallery.dashboard.ts

@@ -1,10 +1,20 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
-import type { Dashboard } from '@objectstack/spec/ui';
+import type { ChartConfig, ChartType, Dashboard } from '@objectstack/spec/ui';
 
 const taskDs = 'showcase_task_metrics';
 const projectDs = 'showcase_project_metrics';
 
+/** Axis fields name the dataset's dimension/measure — query rows are keyed by
+ *  measure NAME post-cutover, never the base column (issue #1721). */
+const cfg = (type: ChartType, dimension: string, measure: string): ChartConfig => ({
+  type,
+  xAxis: { field: dimension, showGridLines: true, logarithmic: false },
+  yAxis: [{ field: measure, showGridLines: true, logarithmic: false }],
+  showLegend: true,
+  showDataLabels: false,
+});
+
 /**
  * Chart Gallery — one widget per chart family the dashboard renderer can draw
  * DISTINCTLY, so the showcase honestly reflects what the platform implements.
@@ -34,26 +44,26 @@ export const ChartGalleryDashboard: Dashboard = {
     { id: 'kpi_total_spent', type: 'metric', title: 'Total Spent', dataset: projectDs, values: ['spent_sum'], layout: { x: 8, y: 0, w: 4, h: 2 } },
 
     // ── Comparison ─────────────────────────────────────────────────────────
-    { id: 'bar_by_status', type: 'bar', title: 'Tasks by Status', dataset: taskDs, dimensions: ['status'], values: ['task_count'], layout: { x: 0, y: 2, w: 4, h: 4 } },
-    { id: 'column_by_priority', type: 'column', title: 'Tasks by Priority', dataset: taskDs, dimensions: ['priority'], values: ['task_count'], layout: { x: 4, y: 2, w: 4, h: 4 } },
-    { id: 'hbar_hours', type: 'horizontal-bar', title: 'Hours by Status', dataset: taskDs, dimensions: ['status'], values: ['est_hours'], layout: { x: 8, y: 2, w: 4, h: 4 } },
+    { id: 'bar_by_status', type: 'bar', title: 'Tasks by Status', dataset: taskDs, dimensions: ['status'], values: ['task_count'], chartConfig: cfg('bar', 'status', 'task_count'), layout: { x: 0, y: 2, w: 4, h: 4 } },
+    { id: 'column_by_priority', type: 'column', title: 'Tasks by Priority', dataset: taskDs, dimensions: ['priority'], values: ['task_count'], chartConfig: cfg('column', 'priority', 'task_count'), layout: { x: 4, y: 2, w: 4, h: 4 } },
+    { id: 'hbar_hours', type: 'horizontal-bar', title: 'Hours by Status', dataset: taskDs, dimensions: ['status'], values: ['est_hours'], chartConfig: cfg('horizontal-bar', 'status', 'est_hours'), layout: { x: 8, y: 2, w: 4, h: 4 } },
 
     // ── Trend (month-bucketed via the dataset's created_at granularity) ──────
-    { id: 'line_created', type: 'line', title: 'Tasks Created (monthly)', dataset: taskDs, dimensions: ['created_at'], values: ['task_count'], layout: { x: 0, y: 6, w: 6, h: 4 } },
-    { id: 'area_created', type: 'area', title: 'Tasks Created (area)', dataset: taskDs, dimensions: ['created_at'], values: ['task_count'], layout: { x: 6, y: 6, w: 6, h: 4 } },
+    { id: 'line_created', type: 'line', title: 'Tasks Created (monthly)', dataset: taskDs, dimensions: ['created_at'], values: ['task_count'], chartConfig: cfg('line', 'created_at', 'task_count'), layout: { x: 0, y: 6, w: 6, h: 4 } },
+    { id: 'area_created', type: 'area', title: 'Tasks Created (area)', dataset: taskDs, dimensions: ['created_at'], values: ['task_count'], chartConfig: cfg('area', 'created_at', 'task_count'), layout: { x: 6, y: 6, w: 6, h: 4 } },
 
     // ── Distribution ─────────────────────────────────────────────────────────
-    { id: 'pie_status', type: 'pie', title: 'Status Split', dataset: taskDs, dimensions: ['status'], values: ['task_count'], layout: { x: 0, y: 10, w: 4, h: 4 } },
-    { id: 'donut_priority', type: 'donut', title: 'Priority Split', dataset: taskDs, dimensions: ['priority'], values: ['task_count'], layout: { x: 4, y: 10, w: 4, h: 4 } },
-    { id: 'funnel_status', type: 'funnel', title: 'Status Funnel', dataset: taskDs, dimensions: ['status'], values: ['task_count'], layout: { x: 8, y: 10, w: 4, h: 4 } },
+    { id: 'pie_status', type: 'pie', title: 'Status Split', dataset: taskDs, dimensions: ['status'], values: ['task_count'], chartConfig: cfg('pie', 'status', 'task_count'), layout: { x: 0, y: 10, w: 4, h: 4 } },
+    { id: 'donut_priority', type: 'donut', title: 'Priority Split', dataset: taskDs, dimensions: ['priority'], values: ['task_count'], chartConfig: cfg('donut', 'priority', 'task_count'), layout: { x: 4, y: 10, w: 4, h: 4 } },
+    { id: 'funnel_status', type: 'funnel', title: 'Status Funnel', dataset: taskDs, dimensions: ['status'], values: ['task_count'], chartConfig: cfg('funnel', 'status', 'task_count'), layout: { x: 8, y: 10, w: 4, h: 4 } },
 
     // ── Relationship + Advanced ──────────────────────────────────────────────
-    { id: 'scatter_estimate', type: 'scatter', title: 'Estimate vs Progress', dataset: taskDs, dimensions: ['progress'], values: ['avg_estimate'], layout: { x: 0, y: 14, w: 6, h: 4 } },
-    { id: 'radar_priority', type: 'radar', title: 'Priority Radar', dataset: taskDs, dimensions: ['priority'], values: ['task_count'], layout: { x: 6, y: 14, w: 6, h: 4 } },
+    { id: 'scatter_estimate', type: 'scatter', title: 'Estimate vs Progress', dataset: taskDs, dimensions: ['progress'], values: ['avg_estimate'], chartConfig: cfg('scatter', 'progress', 'avg_estimate'), layout: { x: 0, y: 14, w: 6, h: 4 } },
+    { id: 'radar_priority', type: 'radar', title: 'Priority Radar', dataset: taskDs, dimensions: ['priority'], values: ['task_count'], chartConfig: cfg('radar', 'priority', 'task_count'), layout: { x: 6, y: 14, w: 6, h: 4 } },
 
     // ── Composition ──────────────────────────────────────────────────────────
-    { id: 'treemap_hours', type: 'treemap', title: 'Hours Treemap', dataset: taskDs, dimensions: ['status'], values: ['est_hours'], layout: { x: 0, y: 18, w: 6, h: 4 } },
-    { id: 'sankey_flow', type: 'sankey', title: 'Status Flow (Sankey)', dataset: taskDs, dimensions: ['status'], values: ['task_count'], layout: { x: 6, y: 18, w: 6, h: 4 } },
+    { id: 'treemap_hours', type: 'treemap', title: 'Hours Treemap', dataset: taskDs, dimensions: ['status'], values: ['est_hours'], chartConfig: cfg('treemap', 'status', 'est_hours'), layout: { x: 0, y: 18, w: 6, h: 4 } },
+    { id: 'sankey_flow', type: 'sankey', title: 'Status Flow (Sankey)', dataset: taskDs, dimensions: ['status'], values: ['task_count'], chartConfig: cfg('sankey', 'status', 'task_count'), layout: { x: 6, y: 18, w: 6, h: 4 } },
 
     // ── Tabular (real grouped tables, multiple measures) ─────────────────────
     { id: 'table_projects', type: 'table', title: 'Projects by Account', dataset: projectDs, dimensions: ['account'], values: ['project_count', 'budget_sum', 'spent_sum'], layout: { x: 0, y: 22, w: 6, h: 4 } },

examples/app-todo/src/dashboards/task.dashboard.ts

@@ -62,6 +62,8 @@ export const TaskDashboard: Dashboard = {
     },
 
     // Row 2: Task Distribution
+    // chartConfig axis fields name the dataset's dimension/measure — query
+    // rows are keyed by measure NAME post-cutover (issue #1721).
     {
       id: 'tasks_by_status',
       title: 'Tasks by Status',
@@ -70,6 +72,7 @@ export const TaskDashboard: Dashboard = {
       dataset: 'task_metrics',
       dimensions: ['status'],
       values: ['task_count'],
+      chartConfig: { type: 'pie', xAxis: { field: 'status', showGridLines: true, logarithmic: false }, yAxis: [{ field: 'task_count', showGridLines: true, logarithmic: false }], showLegend: true, showDataLabels: false },
       layout: { x: 0, y: 2, w: 6, h: 4 },
       options: { showLegend: true }
     },
@@ -81,6 +84,7 @@ export const TaskDashboard: Dashboard = {
       dataset: 'task_metrics',
       dimensions: ['priority'],
       values: ['task_count'],
+      chartConfig: { type: 'bar', xAxis: { field: 'priority', showGridLines: true, logarithmic: false }, yAxis: [{ field: 'task_count', showGridLines: true, logarithmic: false }], showLegend: true, showDataLabels: false },
       layout: { x: 6, y: 2, w: 6, h: 4 },
       options: { horizontal: true }
     },
@@ -94,6 +98,7 @@ export const TaskDashboard: Dashboard = {
       dataset: 'task_metrics',
       dimensions: ['completed_date'],
       values: ['task_count'],
+      chartConfig: { type: 'line', xAxis: { field: 'completed_date', showGridLines: true, logarithmic: false }, yAxis: [{ field: 'task_count', showGridLines: true, logarithmic: false }], showLegend: true, showDataLabels: false },
       layout: { x: 0, y: 6, w: 8, h: 4 },
       options: { showDataLabels: true }
     },
@@ -105,6 +110,7 @@ export const TaskDashboard: Dashboard = {
       dataset: 'task_metrics',
       dimensions: ['category'],
       values: ['task_count'],
+      chartConfig: { type: 'donut', xAxis: { field: 'category', showGridLines: true, logarithmic: false }, yAxis: [{ field: 'task_count', showGridLines: true, logarithmic: false }], showLegend: true, showDataLabels: false },
       layout: { x: 8, y: 6, w: 4, h: 4 },
       options: { showLegend: true }
     },

packages/cli/src/commands/compile.ts

@@ -147,13 +147,31 @@ export default class Compile extends Command {
         this.exit(1);
       }
 
-      // 3c. Widget-binding diagnostics (issue #1719) — semantic checks that
-      //     need the widget's `dataset` reference resolved to its dataset and
-      //     `values` resolved to measures with known aggregates. Advisory
-      //     only: warnings are printed (and included in --json output) but
-      //     never fail the build. Suppress per widget via
+      // 3c. Widget-binding diagnostics (issues #1719/#1721) — semantic checks
+      //     that need the widget's `dataset` reference resolved to its dataset
+      //     and `dimensions`/`values` resolved to declared names. Errors are
+      //     unresolvable bindings (dangling dataset/dimension/measure or a
+      //     chartConfig field the query result won't contain) and fail the
+      //     build; warnings are advisory and suppressible per widget via
       //     `suppressWarnings: ['<rule-id>']`.
-      const widgetWarnings = validateWidgetBindings(result.data as Record<string, unknown>);
+      if (!flags.json) printStep('Checking dashboard widget bindings (ADR-0021)...');
+      const widgetFindings = validateWidgetBindings(result.data as Record<string, unknown>);
+      const widgetErrors = widgetFindings.filter((f) => f.severity === 'error');
+      const widgetWarnings = widgetFindings.filter((f) => f.severity === 'warning');
+      if (widgetErrors.length > 0) {
+        if (flags.json) {
+          console.log(JSON.stringify({ success: false, error: 'widget binding validation failed', issues: widgetErrors }));
+          this.exit(1);
+        }
+        console.log('');
+        printError(`Dashboard widget integrity failed (${widgetErrors.length} issue${widgetErrors.length > 1 ? 's' : ''})`);
+        for (const f of widgetErrors.slice(0, 50)) {
+          console.log(`  • ${f.where}: ${f.message}`);
+          console.log(chalk.dim(`      ${f.hint}`));
+          console.log(chalk.dim(`      rule: ${f.rule}  at ${f.path}`));
+        }
+        this.exit(1);
+      }
       if (widgetWarnings.length > 0 && !flags.json) {
         console.log('');
         for (const w of widgetWarnings) {

packages/cli/src/commands/doctor.ts

@@ -8,6 +8,7 @@ import path from 'path';
 import { normalizeStackInput } from '@objectstack/spec';
 import { printHeader, printSuccess, printWarning, printError, printStep, printInfo } from '../utils/format.js';
 import { loadConfig, configExists } from '../utils/config.js';
+import { validateWidgetBindings } from '../utils/validate-widget-bindings.js';
 
 interface HealthCheckResult {
   name: string;
@@ -525,6 +526,31 @@ export default class Doctor extends Command {
             printSuccess('View integrity        All views reference valid objects');
           }
         }
+
+        // Dashboard widget integrity (issue #1721) — the widget-side analogue
+        // of the orphan-view pass: every widget's `dataset`, `dimensions`,
+        // `values`, and chartConfig axis/series fields must resolve against
+        // the declared datasets (ADR-0021).
+        if (Array.isArray(config.dashboards) && config.dashboards.length > 0) {
+          printStep('Checking dashboard widget integrity...');
+          const widgetFindings = validateWidgetBindings(config);
+          if (widgetFindings.length > 0) {
+            for (const f of widgetFindings) {
+              if (f.severity === 'error') {
+                hasErrors = true;
+                printError(`${f.where}: ${f.message}`);
+              } else {
+                hasWarnings = true;
+                printWarning(`${f.where}: ${f.message}`);
+              }
+              if (flags.verbose) {
+                console.log(chalk.dim(`      → ${f.hint}`));
+              }
+            }
+          } else {
+            printSuccess('Dashboard integrity   All widgets resolve datasets, dimensions, and measures');
+          }
+        }
       } catch {
         printWarning('Could not load config for analysis (config checks skipped)');
         hasWarnings = true;

packages/cli/src/commands/lint.ts

@@ -220,13 +220,16 @@ export function lintConfig(config: any): LintIssue[] {
   // objectstack-data/-ui skills. These double as the eval rubric (see score.ts).
   issues.push(...lintDataModel(objects));
 
-  // ── Dashboard widget bindings (ADR-0021, issue #1719) ──
-  // e.g. a table/pivot widget whose binding resolves to count-only measures
-  // with no dimensions — almost always a record listing that belongs in an
-  // object-bound ListView (ADR-0017), not an analytics dataset.
+  // ── Dashboard widget bindings (ADR-0021, issues #1719/#1721) ──
+  // Reference integrity (errors): widget `dataset`/`dimensions`/`values` and
+  // chartConfig axis/series fields must resolve against the declared
+  // datasets. Advisory shapes (warnings): e.g. a table/pivot widget whose
+  // binding resolves to count-only measures with no dimensions — almost
+  // always a record listing that belongs in an object-bound ListView
+  // (ADR-0017), not an analytics dataset.
   for (const w of validateWidgetBindings(config)) {
     issues.push({
-      severity: 'warning',
+      severity: w.severity,
       rule: w.rule,
       message: `${w.where}: ${w.message}`,
       path: w.path,

packages/cli/src/commands/validate.ts

@@ -5,6 +5,7 @@ import chalk from 'chalk';
 import { ZodError } from 'zod';
 import { ObjectStackDefinitionSchema, normalizeStackInput } from '@objectstack/spec';
 import { loadConfig } from '../utils/config.js';
+import { validateWidgetBindings } from '../utils/validate-widget-bindings.js';
 import {
   printHeader,
   printKV,
@@ -69,22 +70,56 @@ export default class Validate extends Command {
         this.exit(1);
       }
 
-      // 3. Collect and display stats
+      // 3. Dashboard widget reference integrity (issue #1721) — a semantic
+      //    cross-reference pass the protocol schema cannot express: every
+      //    widget's `dataset`/`dimensions`/`values` and chartConfig
+      //    axis/series fields must resolve against the declared datasets
+      //    (ADR-0021). Errors fail validation; warnings are advisory.
+      if (!flags.json) printStep('Checking dashboard widget bindings (ADR-0021)...');
+      const widgetFindings = validateWidgetBindings(result.data as Record<string, unknown>);
+      const widgetErrors = widgetFindings.filter((f) => f.severity === 'error');
+      const widgetWarnings = widgetFindings.filter((f) => f.severity === 'warning');
+
+      if (widgetErrors.length > 0) {
+        if (flags.json) {
+          console.log(JSON.stringify({
+            valid: false,
+            errors: widgetErrors,
+            warnings: widgetWarnings,
+            duration: timer.elapsed(),
+          }, null, 2));
+          this.exit(1);
+        }
+        console.log('');
+        printError(`Dashboard widget integrity failed (${widgetErrors.length} issue${widgetErrors.length > 1 ? 's' : ''})`);
+        for (const f of widgetErrors.slice(0, 50)) {
+          console.log(`  • ${f.where}: ${f.message}`);
+          console.log(chalk.dim(`      ${f.hint}`));
+          console.log(chalk.dim(`      rule: ${f.rule}  at ${f.path}`));
+        }
+        this.exit(1);
+      }
+
+      // 4. Collect and display stats
       const stats = collectMetadataStats(config);
 
       if (flags.json) {
         console.log(JSON.stringify({
           valid: true,
           manifest: config.manifest,
           stats,
+          warnings: widgetWarnings,
           duration: timer.elapsed(),
         }, null, 2));
         return;
       }
 
-      // 4. Warnings (non-blocking)
+      // 5. Warnings (non-blocking)
       const warnings: string[] = [];
-      
+
+      for (const f of widgetWarnings) {
+        warnings.push(`${f.where}: ${f.message}`);
+      }
       if (stats.objects === 0) {
         warnings.push('No objects defined — this stack has no data model');
       }
@@ -98,7 +133,7 @@ export default class Validate extends Command {
         warnings.push('Missing manifest.namespace — required for multi-app hosting');
       }
 
-      // 5. Display results
+      // 6. Display results
       console.log('');
       printSuccess(`Validation passed ${chalk.dim(`(${timer.display()})`)}`);
       console.log('');