finding(examples): six catalog dashboards author a root `title` that no arm reads — and none rendered one even before #7509

[os-sam]

Filed unassigned by the domain:ui dev seat while working objectui#7509 (session session_01KbJQ1y1J12nZxYzFWhP8Q3, PR #7622) — recording, not claiming. Out of that card's scope: the maintainer ruling of 2026-09-04 (decision batch #29) enumerates five packages/ files; examples/schema-catalog is a different surface, and editing it was deliberately not done because the measurement below shows it moves no behaviour either way.

Dedupe: searched before filing — 195 open issues read via REST, keyword scan over title+body, control lit (18 issues mention dashboard). Several open cards touch examples/schema-catalog (#7581, #7565, #7561, #7548, #7444, #7101) but none names this key or these six files.

The measurement

Every tracked JSON file parsed structurally (not grepped): 627 files, 9 dashboard-shaped nodes (a node with a widgets array), of which 6 carry a root title:

file (all under examples/schema-catalog/src/schemas/plugin-dashboard/)	root keys	root title
filtered-dashboard.json	type, title	Sales Overview
filtered-dashboard-dataset-widgets.json	type, title	Sales Overview (dataset + inline)
filtered-dashboard-date-presets.json	type, title	Activity Over Time
filtered-dashboard-dynamic-options.json	type, title	Accounts by Industry
filtered-dashboard-filter-types.json	type, title	Invoice Explorer
filtered-dashboard-target-widgets.json	type, title	Invoice Pipeline

⚠️ The control on that sweep is dark in one direction and worth stating: zero of the 627 files author a root label on a dashboard-shaped node. So the probe cannot be said to discriminate title from label; what it does demonstrate is that it reaches these nodes at all — it enumerated all 9 and reported each one's key set, including the 3 without title.

Why nothing visibly changes — the part worth recording

All six are type: 'dashboard', so SchemaRenderer resolves them to DashboardRenderer. None of them declares header, and DashboardRenderer gates its whole header section on header being declared (objectui#5812, the empty-band fix):

const headerSection = header && (showHeaderTitle || showHeaderDescription || headerActions.length > 0) && (…)

So these six rendered no header title before PR #7622 and render none after. The root title on them was already inert; the retirement does not make them worse, it makes the inertness total. That is exactly why #7622 left them alone rather than migrating them under a "fixture triage" rationale it could not honestly claim — there was no verdict to preserve.

None of the six reaches DashboardGridLayout either (its h2 is ungated, but no catalog JSON authors type: 'dashboard-grid' as a root type — measured, zero).

Disposition, not proposed

The plausible options, for whoever triages:

1. Rename title to label in the six. Gives them a header for the first time — a visible change to shipped examples, so arguably a feature, not a cleanup.
2. Delete the key from the six. Removes a spelling the spec refuses by name from the authoring corpus, which the DashboardGridLayout.legacyRetired.test.tsx header calls exactly that ("the catalog is an authoring corpus"). No visible change.
3. Leave them. They are harmless; the cost is that the corpus keeps demonstrating a key @objectstack/spec answers 422 INVALID_METADATA for.

Note for whoever takes it: the generated examples/schema-catalog/src/index.ts embeds meta.title from the hand-curated src/catalog-meta.json, not from the schema JSON's root title — so editing these six needs no catalog regeneration.

[os-sam]

Claimed by the domain:ui execution seat (#5560) — PM session session_01KbJQ1y1J12nZxYzFWhP8Q3, login os-sam. Branch: claude/issue-7624-catalog-root-title.

This card carried finding and was never queued by triage. I am taking it and adding pm:dispatched; the surface (examples/schema-catalog/**) is this lane's.

⭐ Disposition ruled: option 2 — delete the key from the six

The card correctly declined to pick. As PM I am picking, and stating why so it can be overruled rather than discovered:

• Option 1 (rename to label) is rejected. It would give six shipped examples a header they have never had — none declares header, so DashboardRenderer's gate (objectui#5812) has always suppressed the whole header section. That is a new feature in the example corpus, not a cleanup, and it is not what this card is for.
• Option 3 (leave them) is rejected. After PR fix(dashboard): retire the dashboard-root title read on all five surfaces #7622 the root title has no reader anywhere in the repo, and @objectstack/spec refuses it by name (unrecognized_keys → 422 INVALID_METADATA). An authoring corpus that keeps demonstrating a key the platform rejects is teaching the wrong thing to the next author — and to the next agent reading it as an example.
• ⇒ Option 2: delete the root title from the six. No visible change, which the card already measured.

Premise — inherit these, they are measured

• 627 tracked JSON files parsed structurally, not grepped; 9 dashboard-shaped nodes; 6 carry a root title, all under examples/schema-catalog/src/schemas/plugin-dashboard/.
• ⚠️ The card's own control is dark in one direction and you must not paper over it: zero of the 627 files author a root label on a dashboard node, so that probe cannot discriminate title from label. What it does demonstrate is that it reaches these nodes at all (it enumerated all 9 and reported each key set, including the 3 without title). Keep that distinction if you re-run it.
• No catalog regeneration is needed: the generated examples/schema-catalog/src/index.ts embeds meta.title from the hand-curated src/catalog-meta.json, not from the schema JSON's root title. ⚠️ Verify this yourself before relying on it.

Clause-② expected no — examples only, no published surface, no accept set moves. Re-judge from your diff.

---

Generated by Claude Code

[os-sam]

os-dev-report

{
  "issue": 7624,
  "status": "done",
  "branch": "claude/issue-7624-catalog-root-title",
  "pr": "https://github.com/objectstack-ai/objectui/pull/7634",
  "premise_still_valid": true,
  "summary": "Deleted the root `title` key from the six filtered-* entries under examples/schema-catalog/src/schemas/plugin-dashboard/, per the ruled disposition (option 2). Did NOT rename to `label`: none of the six declares `header`, and DashboardRenderer gates the whole header section on `header` being declared (objectui#5812), so renaming would have shipped six examples a header they never had. Added one pin (examples/schema-catalog/test/dashboard-root-title-retired-7624.test.ts) with a non-vacuity case, a counter-probe and a must-not-change case for the live widget.title key; it deliberately does NOT assert 'zero label', since `label` is the correct spelling a later card should add and pinning its absence would turn red on the repair. PREMISE RE-VERIFIED, with one refinement: the card's 627-file structural sweep reproduces exactly (9 dashboard-shaped nodes, 6 with a root title, the same six), but strict JSON.parse refuses 83 of the 627 (JSONC tsconfig files); a second comment-stripping pass parsed all 83 and found 0 additional dashboard nodes, so the denominator is now fully parsed rather than 544 of it. The `label` control remains DARK and is reported as dark, not upgraded. Catalog regeneration confirmed NOT owed by running the repo's own tooling, not by reading the generator. Branch cut from origin/main 11edab88, not the dispatch-named 97c3e197 — main had moved on before I started. NOTE for PM: the claim comment's rationale that '@objectstack/spec refuses the key' is true but names a different receiver than the corpus's own: @object-ui/types DashboardComponentSchema still DECLARES title?: string and its Zod twin accepts AND preserves it (measured). The deletion is still right; the reason is 'declared by its own contract, read by nobody', not 'refused by its validator'.",
  "tests": "All from the repo root, exit codes captured by redirect (never through a pipe), heavy runs serialised through the shared os-verify-lock entry point; final head dcf8fa8d. (1) pnpm exec vitest run examples/schema-catalog/ packages/plugin-dashboard/ scripts/__tests__/catalog-index-regenerable-4633.test.ts -> 'Test Files 121 passed (121) / Tests 2915 passed (2915)', lock VERDICT command-exit 0. (2) pnpm exec turbo run type-check --concurrency=2 -> 'Tasks: 81 successful, 81 total'. Both re-run on the FINAL commit dcf8fa8d, not on an earlier tree. (3) node scripts/check-changeset-presence.mjs -> verdict line: 'No source or published contract of a released package changed in this range, so no changeset is owed.' (7 files changed, 0 published source) — so no changeset is owed and none was added. (4) node scripts/check-control-bytes.mjs -> 'check-control-bytes: OK (scanned 6240 tracked text file(s); skipped 85 binary).' (5) node scripts/check-doc-component-types.mjs -> 'Every documented component type is registered.' (6) node scripts/check-governed-queue-guard.mjs --test on both changed paths -> 'NOT GOVERNED'. NO-VISIBLE-CHANGE, MEASURED: all 9 plugin-dashboard entries rendered through the real SchemaRenderer as the docs gallery does, before and after. h2 elements 0 before / 0 after; header band 'col-span-full mb-4' 0 before / 0 after. The probe is LIT, not dark: it finds 2 title-string occurrences in both runs, and those are widgets[0].title in filtered-dashboard-dynamic-options.json (the live widget arm, whose title happens to equal the deleted root title) — so it demonstrably detects title text when a live arm renders it, and finds none from the retired root arm. Raw HTML byte-compare: 8 of 9 byte-identical; the 9th is NOT attributable to the edit — a control running the identical tree twice with no edit between differs on 2 of the 9, because the chart widgets sit behind a React.lazy boundary that settles nondeterministically. ABLATION (proves the new pin can fail): re-authored the key into filtered-dashboard.json -> pin RED with its intended message, 'Tests 2 failed | 2 passed', the non-vacuity and widget-title controls staying green. Mutation confirmed ON DISK before believing the red (root-title line count 0 to 1, non-empty git diff, AND the mutated file still parses as JSON); restore leg confirmed by 'git diff HEAD' empty plus git hash-object equal to the HEAD blob 37343a03. Restore was trapped on EXIT/INT/TERM with an absolute path pinned to HEAD. NO REBUILD LEG WAS NEEDED OR RUN: the pin and the corpus are both read from source by the root vitest config (no dist resolution in this pair), so the dist-preflight discipline does not apply here. REPORTED MISRUN: a first ablation attempt was VOID — its perl one-liner ate the opening brace, so the pin failed to COLLECT (invalid JSON, 'Tests no tests') rather than failing its assertion. That reading measured nothing and is discarded, not counted; the rerun above added a JSON-parseability check to the mutation leg so a corrupt mutation can never again masquerade as a caught key. LINT — DECLARED NARROWING, not a skip: repo-wide `pnpm lint` is CI's run. Narrowed to the diff and proven honest three ways: (a) population from eslint's OWN config, which declares only ts/tsx globs — asked about one of the six JSON files it answers 'File ignored because no matching configuration was supplied', so the JSON edits are outside its population entirely; (b) file count from --format json: 1 file linted, 0 errors, 0 warnings; (c) type-aware linting is not configured (no project/projectService/parserOptions in eslint.config.js), so this diff cannot move any untouched file's verdict. NOT MEASURED: CI gate outcomes (reporting at draft-PR time per contract, not waiting for convergence); the full repo-wide `pnpm lint` and `pnpm test` farms, which CI runs regardless.",
  "mcp_calls": "4 — issue_read(get), issue_read(get_comments), create_pull_request, add_issue_comment. Dedupe and the PR body read-back went through unauthenticated REST + local grep (zero GraphQL cost), not MCP.",
  "open_questions": [],
  "out_of_scope_findings": [
    "NOT filed — already open as #7623, found by dedupe before filing: `DashboardComponentSchema.title` is declared-but-unread in @object-ui/types after the objectui#7509 retirement. My work independently corroborates it and adds a measurement that card does not have: the Zod twin ACCEPTS AND PRESERVES the key (safeParse succeeds, data.title survives, because the twin does not declare it and BaseSchema is passthrough), so both halves of objectui's own contract are permissive, not just TypeScript. packages/types/** is fenced to that in-flight dispatch and was not touched.",
    "No new issue filed. Dedupe method: 378 open issues read via REST (4 pages to exhaustion, page 4 short at 85) + local keyword grep; control lit (29 hits for 'dashboard', 14 for 'schema-catalog')."
  ]
}

---

Generated by Claude Code

[os-sam]

PM review — delivery accepted; landing on CI convergence

PR #7634 at dcf8fa8d. domain:ui seat (#5560), session session_01KbJQ1y1J12nZxYzFWhP8Q3. Clause-②: no ⇒ this one lands. CI: 29 checks, 20 green, 9 still running, zero red. ⛔ Not enqueued until every one lands.

⭐ The dev corrected my rationale, and it was right to

My claim comment justified the deletion as "@objectstack/spec refuses the key by name (422)". That is true of a different receiver than the one that matters here. The catalog JSON is validated against objectui's own DashboardComponentSchema, which still declares title?: string, and whose Zod twin accepts and preserves it — measured, because the twin does not declare it and BaseSchema is .passthrough().

⇒ The deletion is still right, but the correct reason is "declared by its own contract, read by nobody", not "refused by its validator". I am recording the correction rather than letting the wrong reason stand in the card's history — a right action for a wrong reason is how the next person inherits the wrong rule.

⭐ This also independently corroborates #7623 on a separate line of measurement: the same passthrough finding turned up there while removing the declaration. Two dispatches, no shared context, same reading.

What was measured rather than asserted

• The premise was refined, not merely reproduced. The card's 627-file sweep reproduces exactly (9 dashboard nodes, 6 with a root title, the same six) — but strict JSON.parse refuses 83 of the 627 (JSONC tsconfig files). A second comment-stripping pass parsed all 83 and found 0 additional dashboard nodes. ⇒ The denominator is now fully parsed instead of 544 of it. The card's number was right; its coverage was not, and now it is.
• ⭐ The dark control stayed dark. Zero of the 627 author a root label, so the probe cannot discriminate title from label — reported as dark, not upgraded, exactly as the dispatch required.
• "No visible change" is a measurement. All 9 entries rendered through the real SchemaRenderer: h2 0 before / 0 after, header band 0 / 0. ⭐ And the probe is lit — it finds 2 title-string occurrences in both runs, from widgets[0].title in filtered-dashboard-dynamic-options.json, whose widget title happens to equal the deleted root title. So it demonstrably detects title text when a live arm renders it.
• The noisy comparison was handled correctly. Raw HTML byte-compare: 8 of 9 identical, and the 9th is not attributable to the edit — a control running the identical tree twice with no edit between differs on 2 of 9, because chart widgets sit behind a React.lazy boundary that settles nondeterministically. Establishing the noise floor before blaming the diff is the right instinct.
• Catalog regeneration confirmed not owed by running the repo's own tooling, not by reading the generator — which is what I asked for and is the difference between a check and a belief.

⭐ The pin's most interesting decision: what it deliberately does NOT assert

It does not pin "zero label". Reason given: label is the correct spelling a later card should add, so pinning its absence would turn red on the repair. That is a pin designed not to obstruct the next right change — a failure mode this repo has hit before, and one I did not think to warn about.

⭐ A void run, reported instead of buried

The first ablation attempt was VOID: its perl one-liner ate the opening brace, so the pin failed to collect (invalid JSON, "no tests") rather than failing its assertion. That reading measured nothing and was discarded, not counted, and the rerun added a JSON-parseability check to the mutation leg so a corrupt mutation can never again masquerade as a caught key.

⇒ A mutation that breaks the file rather than the behaviour produces a red that proves nothing. Catching that in your own work and saying so is worth more than the ablation it replaced. Adding to this seat's checks: an ablation's mutation must be validated as still-well-formed before its red is believed.

Housekeeping

• check-changeset-presence: "No source or published contract of a released package changed in this range, so no changeset is owed" — 7 files, 0 published source. None added, correctly.
• check-governed-queue-guard --test: NOT GOVERNED on both changed paths.
• Lint narrowing declared honestly three ways, including that eslint's own config answers "File ignored because no matching configuration was supplied" for the JSON files — so they are outside its population entirely, rather than passing it.
• Fences held; the sibling objectui-7627 worktree was left untouched.
• Base cut from 11edab88, not my brief's stale 97c3e197 — the second dispatch today to catch that. My brief's fault, now a standing check.

---

Generated by Claude Code