schema-catalog: all 9 `plugin-dashboard` examples are refused by the spec's `DashboardSchema` — the AI few-shot corpus teaches the pre-ADR-0021 widget shape

[yinlianghui]

Found while implementing #4356 (Phases 0+1), measuring whether the guardrail that card asked for could be built as suggested. Not fixed there — that card's scope is the globalFilters[].options shorthand, and this is strictly larger.

What was measured

Parsing every examples/schema-catalog/src/schemas/plugin-dashboard/*.json entry with the real @objectstack/spec DashboardSchema, on origin/main at 92250d648:

REJECT  basic-dashboard.json                        (17 issues)
REJECT  e-commerce-dashboard.json                   (22 issues)
REJECT  filtered-dashboard.json
REJECT  filtered-dashboard-dataset-widgets.json
REJECT  filtered-dashboard-date-presets.json
REJECT  filtered-dashboard-dynamic-options.json
REJECT  filtered-dashboard-filter-types.json
REJECT  filtered-dashboard-target-widgets.json
REJECT  support-dashboard.json

9 of 9. Fixing #4356's bare-string options shorthand does not change this — those three entries stay refused for the reasons below, which is why #4356 pinned its guardrail at GlobalFilterSchema (the sub-schema that owns the property that regressed) rather than at DashboardSchema as the objectstack#7917 survey had suggested. That narrowing is deliberate and recorded in that PR; this issue is the remainder.

Two distinct causes, and they are not the same kind of problem:

1. Metadata identity keys — arguably by design. Every entry reports [name] Invalid input: expected string, received undefined and [label] Invalid input. These are objectui SDUI component schemas ({ "type": "dashboard", "title": …, "columns": … }), not stored platform metadata documents, so they legitimately carry no name / label identity. If that is the intended reading, then DashboardSchema is simply the wrong schema for an SDUI node and the interesting question is which schema is right.

2. The widget shape — this is the real finding. Most entries' widgets use the pre-ADR-0021 inline analytics form:

[widgets.0] Unrecognized key(s) on this dashboard widget: `object`, `categoryField`, `aggregate`.
  • The pre-ADR-0021 inline analytics shape (`object` + `categoryField` + `valueField` + `aggregate`,
    pivot `rowField`/`columnField`) was removed — bind a `dataset` and select `dimensions` + `values`
    by name. Renderer-only settings belong under `options`. Undeclared top-level keys were dropped
    silently before strict validation, shipping inert metadata; a stale or mis-layered key is now a
    loud parse error.

@objectstack/spec 17 removed that shape. And objectui's own DashboardWidgetSchema (packages/types/src/complex.ts) does not declare object / categoryField / aggregate either — it takes its keys from the spec through extends and adds only component, layout, type, options, chartConfig, filter, responsive. So these examples author keys that neither contract declares. Nothing catches it because the entries are imported as JSON and the catalog's only assertions are structural (smoke.test.tsx) and render-without-throw.

Why it matters

This is the same defect class as #4356, in the same corpus, with the same blast radius — and #4356's was judged worth a card. examples/schema-catalog/package.json describes itself as the "single source of truth for example schemas consumed by the docs site, smoke tests, and AI few-shot retrieval", and test/fields-form-hosted.test.tsx records the #3910 lesson verbatim: "these examples are the docs site's field demos and a few-shot retrieval source for AI authors, so what they show is what gets copied."

So an AI author retrieving filtered-dashboard.json today is taught a widget shape the platform refuses at publish, exactly as it was being taught the bare-string options shorthand until #4356. The objectstack#7917 survey's core point applies unchanged: the stored population of these documents is still growing, because the corpus is still producing them.

Uncertainty, stated plainly

Not measured here: whether objectui's renderer still supports the inline analytics form at runtime. It evidently renders (the catalog's render-without-throw tests pass), so this may be a live compat arm rather than dead metadata — in which case the finding is a documented-tolerance divergence of the #4356 shape (renderer accepts, spec refuses) and wants the same enforce-or-retire treatment, not a silent rewrite of the examples. Whoever picks this up should establish that before choosing between "migrate the 9 examples to dataset + dimensions + values" and "retire the renderer arm too".

Related, both closed and from an earlier era: #824 (examples' dashboard/widget metadata vs spec) and #3965 (48 catalog examples using the deprecated div component type) — same corpus, same failure mode, which suggests the catalog needs a standing spec-validation gate rather than another one-off sweep. #4356 added one for globalFilters only.

---

Generated by Claude Code

[yinlianghui]

CLAIM (measure-only) — session session_017Qqyix2QcnpUC9XeYVDzx3. This seat EDITS NOTHING: its deliverable is the measurement this card's own body says its ruling needs ("whether the renderer still supports the inline analytics form was NOT measured, and that determines whether the fix is 'migrate the 9 examples' or 'retire the renderer arm too'"), reported here for PM ruling. No branch, no PR, no changeset.

Measurement scope:

1. Renderer support: does plugin-dashboard's widget path still READ the pre-ADR-0021 inline analytics keys (object + categoryField + aggregate)? Trace the code (file:line), and answer working-render vs dead-code vs partial with a scratch render probe if needed.
2. Type layer: what does objectui's own DashboardWidgetSchema (packages/types) declare today — inline shape, dataset shape, both?
3. Docs layer: what do content/docs and the plugin README teach — inline, dataset, both? (The normalizeFilterOptions accepts a bare-string globalFilters[].options shorthand that @objectstack/spec rejects at publish #4356 survey found the docs still teach inline "elsewhere" — enumerate where.)
4. Catalog: per-entry failure classes of all 9 plugin-dashboard entries vs the spec's DashboardSchema on current main (re-verify the normalizeFilterOptions accepts a bare-string globalFilters[].options shorthand that @objectstack/spec rejects at publish #4356-era measurement: metadata-identity keys + inline widget shape), plus each entry's other divergences if any.
5. Migration shape: for one representative entry, the concrete diff migrating inline → the spec-17 dataset+dimensions+values form — enough to size "migrate the 9" honestly.
6. In-repo reliance: tests/consumers that depend on the inline form rendering (count + cite).

Output: a findings comment on this issue with the six answers (verbatim probe outputs, file:line citations) and the option space with measured costs — no recommendation required beyond stating which facts bear on which option. Read-only everywhere; scratch probes in the session scratchpad only. ⛔ Zero repo file edits; ⛔ no interference with the in-flight #4580-round2 seat's packages (reads are fine).

---

Generated by Claude Code

---

Generated by Claude Code

[yinlianghui]

Measurement report (measure-only seat — nothing was edited, no branch, no PR)

Measured on origin/main at f69127fcc, against installed @objectstack/spec@17.0.0-rc.6. The card's own stated uncertainty — "Not measured here: whether objectui's renderer still supports the inline analytics form at runtime" — is the first thing below, and it resolves the other way from the card's guess, which collapses most of the option space.

Headline: the renderer arm is already retired (framework#3320). The inline shape does not render a chart — it renders a red dashed error placeholder reading "This widget uses a retired data format. Edit it to bind a dataset." So these 9 entries are not merely "refused at publish while rendering fine". 15 of their 28 widgets are visibly broken in objectui's own docs-site gallery today, and 3 docs files still teach the shape that produces them.

---

1. Renderer support for the inline analytics shape

Verdict: retired, with a diagnostic — not a live compat arm, and not silently dead.

Method: static trace of every read, plus running the pinned test on this commit (real output below).

Per-key verdicts, at widget top level:

key	verdict	citation
object	live as a sentinel only — read at exactly ONE site repo-wide, to select the error placeholder	packages/plugin-dashboard/src/DashboardRenderer.tsx:549
categoryField	dead — read nowhere	—
categoryGranularity	dead — read nowhere	—
valueField	dead — read nowhere	—
aggregate	dead — read nowhere	—
rowField / columnField	dead — the pivot family returns the same placeholder	DashboardRenderer.tsx:703-709

The decisive lines, verbatim (DashboardRenderer.tsx:537-551):

            // Renderer-internal data sources only (ADR-0021): the inline
            // `options.data` / `widget.data` array, or the `provider: 'object'`
            // async config (which carries its OWN nested `object`/`aggregate`).
            // The pre-ADR-0021 top-level analytics keys (`object`, `categoryField`,
            // `valueField`, `aggregate`, …) are no longer read — their renderer
            // branches were retired in framework#3320.
            const widgetData = (widget as any).data || options.data;

            // Retired legacy inline-analytics widget (framework#3320): still carries
            // the pre-ADR-0021 top-level `object` binding with no `dataset` and no
            // inline `options.data`. No authoring surface emits this anymore, so it
            // is stale stored metadata — render a visible error placeholder (not a
            // blank) prompting a rebind to a dataset.
            if (!widgetData && (widget as any).object) {
                return LEGACY_RETIRED_WIDGET_SCHEMA;
            }

and the placeholder it selects (DashboardRenderer.tsx:149-155):

const LEGACY_RETIRED_WIDGET_SCHEMA = {
  type: 'text',
  value: 'This widget uses a retired data format. Edit it to bind a dataset.',
  variant: 'caption',
  align: 'center',
  className: '… border-dashed border-destructive/40 bg-destructive/5 … text-destructive',
} as const;

Do not confuse this with the live nested surface. The object / aggregate reads at DashboardRenderer.tsx:567-694 and DashboardGridLayout.tsx:190-295 are all on widgetData — the nested options.data = { provider: 'object', … } async data-provider config, which is a different and still-live authoring surface. Repo-wide, a top-level widget.object is read in exactly one place:

$ grep -rn "widget as any).object\|widget\.object" packages/plugin-dashboard/src/*.tsx
src/DashboardRenderer.tsx:549:            if (!widgetData && (widget as any).object) {

Live confirmation — the pinned test on this commit:

$ pnpm exec vitest run packages/plugin-dashboard/src/__tests__/DashboardRenderer.legacyRetired.test.tsx
 RUN  v4.1.10 /home/user/objectui-4600-measure
 Test Files  1 passed (1)
      Tests  6 passed (6)
   Duration  8.06s

Its 4 positive cases render bar / metric / pivot / table widgets carrying the inline shape and assert the placeholder is visible; its 2 negative controls assert a dataset-bound and an options.data widget do not get it. Two of those cases are byte-for-byte the shapes in filtered-dashboard.json ({ type: 'metric', object: 'invoices', aggregate: 'count' } is widgets.2 exactly).

Secondary finding — the sibling surface has no such fallback. DashboardGridLayout (separately exported, used by DashboardWithConfig / editable dashboards) carries no legacy sentinel. A legacy widget there takes the series branch with widgetData undefined, so isObjectProvider(undefined) is false and it falls through to the static-data branch with data: [] (DashboardGridLayout.tsx:215-225) — i.e. a blank chart with no diagnostic, precisely the outcome the retirement's own test header says must not happen ("must render a VISIBLE error placeholder prompting a rebind, not a blank widget"). The graceful fallback was applied to one of the two surfaces. Flagging, not fixing — see the option space.

---

2. Type layer

Spec (@objectstack/spec@17.0.0-rc.6, DashboardWidgetSchema from /ui), probed directly:

keys (22): id, title, description, type, chartConfig, colorVariant, requiresObject,
  requiresService, actionUrl, actionType, actionIcon, filter, compareTo, dataset,
  dimensions, values, layout, options, filterBindings, suppressWarnings, responsive, aria

required (no .optional()):
  - id
  - dataset
  - values

No inline key is present at all. dataset and values are required, which is why every widget in every entry also reports two invalid_type issues on top of the unrecognized-key issue.

objectui, TS — packages/types/src/complex.ts:676-677: DashboardWidgetSchema extends Omit< Partial< SpecDashboardWidget >, 'type' | 'options' | 'chartConfig' | 'filter' | 'responsive' > and adds only component, layout, type, options, chartConfig, filter, responsive, searchable, pagination. Its own comment says the spec keys "flow in from the spec through the extends above — do not restate them here". No inline keys.

objectui, Zod twin — packages/types/src/zod/complex.zod.ts:303-310: derived from SpecDashboardWidgetSchema.shape. No inline keys. TS and Zod agree.

The one surface that still declares them is the config panel pair, and it is not an authoring path to the dead shape:

• packages/types/src/designer.ts:538-552 — interface DashboardWidgetConfig (object?, categoryField?, …)
• packages/types/src/zod/complex.zod.ts:452-459 — DashboardWidgetConfigSchema, commented "for DashboardConfigPanel"
• but packages/plugin-dashboard/src/WidgetConfigPanel.tsx:459-482 actively scrubs them on save, via LEGACY_ANALYTICS_KEYS = ['object', 'categoryField', 'categoryGranularity', 'valueField', 'aggregate', 'aggregation', 'rowField', 'columnField', …], so that "switching type (or saving a legacy widget) never re-emits the dead shape".
• and packages/app-shell/…/inspectors/DashboardWidgetInspector.tsx records that the inline object query "was removed (framework#3251), so no Studio surface can author the dead shape".

So: no authoring surface emits this shape. The catalog corpus is the last producer in the repo.

---

3. Docs layer

Three files teach the retired inline form for a dashboard widget; zero files teach the dataset form for a widget.

file	lines	what it shows
content/docs/guide/dashboard-filters.md	41-50 (Step 1), 183-196 (Step 4)	full JSON widgets with object + categoryField + categoryGranularity + aggregate
content/docs/plugins/plugin-dashboard.mdx	175-181	{ "id": "w1", "type": "bar", "object": "invoices", "aggregate": "count" } and two more
packages/plugin-dashboard/README.md	235-243	the same three widgets

Plus prose in dashboard-filters.md that asserts the shape is live:

• :19-22 — "Working examples: the schema catalog ships a plugin-dashboard/filtered-dashboard example plus variants…" (all 3 of that entry's widgets render the retired placeholder)
• :266-269 — "Inline (object-based) and dataset-bound widgets can mix freely on one filtered dashboard."
• :285-291 — "Bind the widget to an object (or a dataset) if it should respond to filters" and "Default bindings are metadata-checked for object widgets only"

Deliberately excluded from this census (checked, different live surfaces — do not batch-rewrite them):

• content/docs/plugins/plugin-report.mdx:250 — report.columns[].aggregate, the spec-report surface, unrelated and live.
• packages/plugin-dashboard/README.md:230 — optionsFrom.valueField, the global-filter dynamic-options surface, live.

---

4. Catalog per-entry failure classes (all 9, verbatim)

DashboardSchema.safeParse on each entry. 9 of 9 REJECT, confirming the card. Three distinct classes, not the two the card names:

• Class A — metadata identity: [name] + [label]. Every entry, 2 issues each.
• Class B — SDUI envelope keys at dashboard level: type (all 9) and title (the 6 filtered-*). 1 issue each. This class is not named in the card body.
• Class C — widget shape, which splits in two:
  • C1 retired inline analytics — object / categoryField / categoryGranularity / aggregate. 6 entries, 15 widgets.
  • C2 metric-card — value / icon / trend / trendValue, and type: "metric-card" is not in the spec's 20-value widget enum at all. 3 entries, 11 widgets. This is not an ADR-0021 problem; it is a widget family objectui has and the spec does not model.
  • every widget additionally reports missing dataset and values (both required), and C2's widgets also miss id.

Representative verbatim output:

REJECT  filtered-dashboard.json  (12 issues)
  [name] invalid_type: Invalid input: expected string, received undefined
  [label] invalid_union: Invalid input
  [widgets.0.dataset] invalid_type: Invalid input: expected string, received undefined
  [widgets.0.values] invalid_type: Invalid input: expected array, received undefined
  [widgets.0] unrecognized_keys: Unrecognized key(s) on this dashboard widget: `object`, `categoryField`, `aggregate`.
  • The pre-ADR-0021 inline analytics shape (`object` + `categoryField` + `valueField` + `aggregate`, pivot `rowField`/`columnField`) was removed — bind a `dataset` and select `dimensions` + `values` by name. …
  [widgets.1] unrecognized_keys: … `object`, `categoryField`, `categoryGranularity`, `aggregate`.
  [widgets.2] unrecognized_keys: … `object`, `aggregate`.
  [] unrecognized_keys: Unrecognized key(s) on this dashboard: `type`, `title`. Did you mean `title` → `label`? …

REJECT  basic-dashboard.json  (18 issues)
  [name] / [label] …
  [widgets.0.type] invalid_value: Invalid option: expected one of "bar"|"horizontal-bar"|"column"|"line"|"area"|"pie"|"donut"|"funnel"|"scatter"|"treemap"|"sankey"|"combo"|"gauge"|"solid-gauge"|"metric"|"kpi"|"bullet"|"radar"|"table"|"pivot"
  [widgets.0] unrecognized_keys: Unrecognized key(s) on this dashboard widget: `value`, `icon`, `trend`, `trendValue`. Did you mean `value` → `values`? …
  [] unrecognized_keys: Unrecognized key(s) on this dashboard: `type`. …

Full per-entry issue counts on f69127fcc: basic-dashboard 18, e-commerce-dashboard 23, support-dashboard 23, filtered-dashboard 12, -date-presets 12, -filter-types 12, -target-widgets 12, -dynamic-options 9, -dataset-widgets 6.

Two counts differ from the card's snapshot at 92250d648 (18 vs 17, 23 vs 22). The one intervening commit touching this corpus is f279debf5 (#4356 / PR #4601); I did not chase the attribution, and the class breakdown is unchanged — the delta does not bear on any option below.

What these entries render today (the part the card assumed was fine)

Replaying the renderer's own fork (DashboardRenderer.tsx:528 datasetBound, :542 widgetData, :549 sentinel, :703 pivot; the :549 behaviour independently pinned green by the 6/6 test above) over the real entries:

filtered-dashboard.json                  [3/3 widgets show the retired placeholder]
filtered-dashboard-date-presets.json     [3/3]
filtered-dashboard-filter-types.json     [3/3]
filtered-dashboard-target-widgets.json   [3/3]
filtered-dashboard-dynamic-options.json  [2/2]
filtered-dashboard-dataset-widgets.json  [1/3]   (widgets.0/1 are dataset-bound)
basic-dashboard.json                     [0/3]   (metric-card, renders)
e-commerce-dashboard.json                [0/4]   (metric-card, renders)
support-dashboard.json                   [0/4]   (metric-card, renders)

=== TOTALS across all 9 entries ===
  RETIRED_PLACEHOLDER: 15
  DatasetWidget: 2
  renders (static/passthrough): 11

apps/site/app/components/SchemaCatalogIndex.tsx:105-111 renders every catalog example through a real SchemaRenderer. So /docs/guide/schema-catalog currently shows 15 red dashed "retired data format" tiles, and 5 of the 6 filtered-* entries are 100% placeholder — including the one dashboard-filters.md:19 calls a "Working example".

---

5. Migration shape — filtered-dashboard.json, worked

The minimal spec-valid widget parses clean (probed):

minimal migrated widget parse: ACCEPT
  { id: 'invoices_by_status', title: 'Invoices by Status', type: 'bar',
    dataset: 'invoices', dimensions: ['status'], values: ['count'] }

Migrating the whole entry means changing the document's kind, not just its widgets — classes A and B are envelope changes:

{
  // Class B: the SDUI envelope keys must GO. `type: "dashboard"` is rejected,
  // `title` must become `label`.
  "name": "sales_overview",          // Class A: invented — no source in the file
  "label": "Sales Overview",         // from the old `title`
  "columns": 2,
  "gap": 4,
  "dateRange": { … },                // unchanged, accepted
  "globalFilters": [ … ],            // unchanged, accepted (already fixed by #4356)
  "widgets": [
    { "id": "invoices_by_status", "title": "Invoices by Status", "type": "bar",
      "dataset": "invoices",         // invented — no such dataset metadata exists
      "dimensions": ["status"],      // from `categoryField`
      "values": ["count"] },         // from `aggregate: "count"`
    { "id": "accounts_signed", "title": "Accounts Signed", "type": "line",
      "dataset": "accounts",         // invented
      "dimensions": ["signed_at"],   // `categoryGranularity: "month"` has NO
                                     //   top-level equivalent — a granularity
                                     //   belongs to the dataset's dimension
                                     //   definition, not the widget
      "values": ["count"],
      "filterBindings": { "dateRange": "signed_at", "region": "sales_region" } },
    { "id": "total_invoices", "title": "Total Invoices (all regions)", "type": "metric",
      "dataset": "invoices",         // invented
      "values": ["count"],
      "filterBindings": { "region": false } }
  ]
}

Information that is missing and must be invented — this is the honest sizing input:

1. name — no source anywhere in the file. One identifier per entry, invented.
2. The datasets themselves. dataset is a reference by name to a separate semantic-layer metadata document (the spec exports DatasetSchema / defineDataset). The catalog has no place to put one — it is a directory of standalone SDUI component JSON. So the 9 entries would reference invoices / accounts / sales datasets that exist nowhere, and dimensions / values would name dimensions and measures nobody has declared.
3. categoryGranularity has no widget-level home in the new model; the monthly bucketing demonstrated by accounts_signed is simply lost unless a dataset declares that dimension.
4. The 3 metric-card entries (class C2) cannot be migrated at all without ceasing to be what they demonstrate — a static presentational metric card with value: "1,234", icon, trend. There is no metric-card in the spec's widget enum and no dataset behind a hard-coded string.

And the measured sting — migration does not fix the rendering. The docs gallery passes dataSource: {} (apps/site/app/components/SchemaThumbnail.tsx:25). DatasetWidget.tsx:767-769 reads:

    const src = dataSource as DatasetCapableSource | undefined;
    if (!src || typeof src.queryDataset !== 'function') {
      setState({ status: 'error', rows: [], error: tt('dashboard.datasetUnsupported', 'This data source does not support dataset queries.') });

which renders an error alert (:929-932). This is not a prediction — it is already happening: the 2 dataset-bound widgets in filtered-dashboard-dataset-widgets.json show that error in the gallery today. So migrating the 15 inline widgets converts 15 "retired data format" placeholders into 17 "does not support dataset queries" errors. Different message, same broken gallery.

---

6. In-repo reliance on the inline form rendering

Measured by grepping every renderer read plus every test that constructs such a widget. The reliance is on the placeholder, not on any chart.

#	site	what it depends on
1	packages/plugin-dashboard/src/__tests__/DashboardRenderer.legacyRetired.test.tsx	the only renderer-level reliance: 4 cases assert the placeholder appears, 2 controls assert it does not for dataset / options.data. Goes red if the :549 sentinel is removed.
2	the 6 filtered-* catalog JSON entries	data, not tests — they produce 15 placeholders in the docs gallery
3	examples/schema-catalog/test/plugin-dashboard-global-filters-spec.test.ts	iterates the same entries but validates globalFilters only — independent of widget shape, unaffected by any option below

Zero tests or consumers depend on the inline form producing a chart, a metric, a table or a pivot. Checked and excluded as different surfaces: packages/app-shell/src/__tests__/widget-dom-leak-sweep.test.tsx:277-282 (objectName + categoryField — the object-chart SDUI block's props, live); packages/types/src/__tests__/dashboard-config.test.ts (the config-panel type, not the renderer); DashboardWidgetInspector.test.tsx (asserts the Studio surface is gone); plugin-view / plugin-list / app-shell ObjectView (chartConfig.xAxisField, live).

Also worth recording: examples/schema-catalog/test/smoke.test.tsx contains no render( call at all — its assertions are purely structural (schema is an object, node.type is a non-empty string). The catalog has no render-without-throw test for this category, so nothing in CI would have noticed the 15 placeholders.

Note for the record: examples/crm and examples/todo are clean — the inline widgets #824 added there in Feb 2026 are gone. The corpus in schema-catalog is the only survivor.

---

Option space, with measured costs

(b) "Retire the renderer arm too" — already done; there is nothing to buy. framework#3320 retired it before this card was filed. The card's premise that this might be "a live compat arm" is disproven. Residue: the :549 sentinel (worth keeping — it is the graceful fallback for stored legacy metadata) and the DashboardGridLayout asymmetry in §1.

(a) "Migrate the 9 examples to dataset + dimensions + values" — larger than it looks, and does not fix what is actually broken.

• Bears on it: §5 — it is not a widget rewrite but a document-kind conversion (invent name, drop the SDUI type, rename title→label), it invents 3 datasets that exist nowhere, it silently drops categoryGranularity, and 3 of the 9 entries (class C2, 11 widgets) cannot be migrated at all.
• Bears on it: §5's last paragraph — with dataSource: {} in the gallery, migration turns 15 placeholders into 17 dataset errors. Measured, not predicted.
• Also: converting SDUI component examples into platform metadata documents arguably breaks the catalog's own contract (a directory of renderable SDUI nodes), which is the card's own class-A observation pointing at "which schema is the right one".

(c) "Keep both, gate on a narrower sub-schema" (status quo after #4356).

• Bears on it: §1 + §4 — "keep both" is not available as stated, because the renderer does not keep the inline arm. The status quo leaves 15 broken tiles in the published gallery and 3 docs files teaching a shape that renders an error. That is the real cost of doing nothing, and it is user-visible, not observation-class.

(d) What the measurements themselves suggest — split into three, because they are three different decisions:

1. Corpus + docs truth (the live defect). The 6 filtered-* entries and the 3 docs locations teach a shape objectui itself refuses to render. Fixing the corpus honestly requires both rewriting them and giving SchemaThumbnail a dataset-capable stub dataSource — otherwise (a) just changes the error text. Sizing: 6 JSON files + 3 docs files + 1 stub in apps/site.
2. Which schema an SDUI dashboard node should be validated against (classes A + B, all 9 entries). This is the card's own "the interesting question is which schema is right", and it is a spec/contract decision, not a rewrite. Until it is answered, a DashboardSchema gate over this corpus is permanently red for reasons that have nothing to do with ADR-0021 — which is exactly why normalizeFilterOptions accepts a bare-string globalFilters[].options shorthand that @objectstack/spec rejects at publish #4356 pinned its guardrail at GlobalFilterSchema. A standing catalog gate (the card's closing suggestion) needs this answered first, or it needs to be a widget-level gate rather than a document-level one.
3. DashboardGridLayout's missing fallback (§1) — an independent defect: the same stored metadata that gets a helpful placeholder in DashboardRenderer gets a silent blank chart in the editable surface. Small, self-contained, and unrelated to the corpus.

Recommendation (offered, not required). Do (d1) and (d3); do not do (a) as stated, and do not open (d2) as part of this card. The business pull is real but narrow and it is entirely on (d1): the corpus is a few-shot retrieval source and the gallery is published, so today it both teaches and demonstrates a dead shape — that is a live authoring-quality defect, and it is the half that is cheap and unambiguous. (d2) changes a contract and should be a maintainer ruling with its own card; guessing it wrong would be far more expensive than leaving classes A and B red for now, since nothing enforces them today anyway. The AI-authoring axis also argues for (d1) over (c): what makes this shape hard to get wrong is not another consumer-side tolerance but removing the last producer of it, which the config panel already did in code (LEGACY_ANALYTICS_KEYS) and the corpus has not yet done in data.

---

Generated by Claude Code

---

Generated by Claude Code

[yinlianghui]

PM ruling on the measurement above (delegated, veto window open). The measurement inverts this card's premise — the renderer's inline arm is ALREADY retired (framework#3320) and renders a diagnostic placeholder, so the real, user-visible defect is that the published docs gallery shows 15 "retired data format" tiles today, including an entry the docs call a "Working example", and nothing in CI can see it (the smoke test contains no render call). Disposition in four parts:

1. (a) migrate-the-9 as originally stated: REJECTED. Measured: it is a document-kind conversion that invents three nonexistent datasets, drops categoryGranularity, cannot migrate the 3 metric-card entries at all — and with the gallery's dataSource: {} it converts 15 placeholders into 17 dataset errors. Different message, same broken gallery.
2. (b) retire the renderer arm: MOOT — already done; the :549 sentinel stays as the graceful fallback for stored legacy metadata.
3. (d1) corpus + docs truth: ACCEPTED as this card's implementation scope. One seat: rewrite the 6 filtered-* entries onto STILL-LIVE surfaces that actually render in the gallery (the entries exist to demonstrate FILTERS — the seat measures whether options.data provider config, static data, or dataset-bound-plus-stub yields working charts and uses what works); fix the 3 docs teaching locations plus the false "Working examples" / "mix freely" prose; give SchemaThumbnail a dataset-capable stub dataSource so the 2 dataset-bound widgets render; and add the missing render-based gallery pin for this category (no retired-placeholder tile, no error tile) so this cannot silently regress again. The 3 metric-card entries render fine and stay as-is — their spec-validity is (d2)'s question, not a rendering defect.
4. (d2) which schema an SDUI dashboard node validates against (classes A + B + C2, including whether metric-card joins the spec's widget enum): ROUTED UPSTREAM as a domain:spec decision card in objectstack, with this measurement as evidence — the same contract-first routing as objectstack#7496/#7917. A DashboardSchema catalog gate stays impossible until it is answered, which is exactly why normalizeFilterOptions accepts a bare-string globalFilters[].options shorthand that @objectstack/spec rejects at publish #4356 pinned at GlobalFilterSchema. OQ2 ruled A (C2 folds into that one ruling).

OQ1 ruled A: the DashboardGridLayout missing-fallback defect (silent blank chart where DashboardRenderer shows the rebind prompt) is filed standalone (searched: no open issue mentions it) and dispatched as its own small seat — a renderer fix does not belong inside a docs/examples card.

---

Generated by Claude Code

---

Generated by Claude Code

[yinlianghui]

CLAIM (implementation, d1) — session session_017Qqyix2QcnpUC9XeYVDzx3, branch claude/issue-4600-gallery-truth. Scope per the ruling above: 6 filtered-* entries rewritten onto still-live, gallery-renderable surfaces (seat measures which of options.data provider config / static data / dataset+stub actually renders and uses what works); the 3 docs teaching locations + false prose corrected; SchemaThumbnail gains a dataset-capable stub dataSource; a render-based gallery pin (no retired-placeholder tile, no error tile) closes the CI blind spot. ⛔ NOT here: metric-card entries (render fine; spec-validity is objectstack#8593's ruling), packages/plugin-dashboard/src/** (#4612's seat), re-teaching the bare-string filter shorthand (the #4356 guardrail is live). Phase (d2) waits upstream on objectstack#8593.

---

Generated by Claude Code

---

Generated by Claude Code

[yinlianghui]

(d1) implemented — PR #4615 (draft). Two notes the PM needs before 复核:

1. The gallery was broken one layer deeper than the measurement could see. The measurement seat replayed DashboardRenderer's fork over the entries, which is accurate for what those entries produce once the plugin is loaded. Rendering them through the gallery's actual registration set says something else: SchemaThumbnail loads @object-ui/react, @object-ui/components and registerLayoutBlocks and no plugin at all, so all 9 dashboard tiles were the registry's red Unknown component type: dashboard (OBJUI-001) panel — the 15 placeholders and 2 dataset errors were never reachable on that page. Rewriting the entries alone would therefore have changed nothing visible. The PR adds the registration (gallery-only, apps/site) alongside the stub and the rewrite; a census of the rest of that gap (≈32 more entries across calendar / chatbot / editor / gantt / map / markdown / timeline / kanban) is filed as #4616.

2. ⚠️ main is red and the PR inherits it. ci.yml's Build Docs job runs next build, which type-checks apps/site, and it has failed since c1d939f7f — the merge of PR #4608 (#4580, "the union wins"). Five TS2322s, all SchemaNode not assignable to SchemaRenderer's schema prop; four of the five are in files PR #4615 does not touch (InteractiveDemo ×2, LiveSplitDemo, playground/page.tsx). Evidence and the two contract options are on #4617. It is deliberately not fixed in PR #4615: the honest fix is a published prop-type decision in @object-ui/react, and casting at the call sites is the consumer-side tolerance contract-first forbids. Every other gate on the PR is green.

---

Generated by Claude Code

---

Generated by Claude Code