finding(docs): `core/report-schema.mdx` names its subject `ReportSchema` — a name this tree does not declare, and one `@objectstack/spec` uses for a different thing

[yinlianghui-tw]

Filed unassigned out of #6086 round 3, noticed while naming the shape on that page's property tables. The tables were named ReportComponentSchema in PR #6168; this is the surrounding prose, which is a different sentence and was left alone.

The fact

content/docs/core/report-schema.mdx calls its subject ReportSchema in three places:

• frontmatter title: "Report Schema (ReportSchema)"
• the H1 lead: "The ReportSchema enables creating comprehensive data reports…"
• (the page's own example fence, by contrast, imports ReportComponentSchema)

ReportSchema resolves to nothing in this repo — not in @object-ui/types' built .d.ts, not in packages/*/src. The shape the page actually documents is ReportComponentSchema (packages/types/src/reports.ts:354), which is what its own example imports and what all four rows of its Basic Configuration table are members of.

Why it is worse than a typo

ReportSchema is not an unused name — @objectstack/spec does export it, for the dataset-bound report shape shipped as json-schema/ui/Report.json (name / label / dataset / rows / columns / values / …). That is the shape content/docs/plugins/plugin-report.mdx documents, and it is a different thing from the type: 'report' component node this page is about. So a reader who follows the name lands on a real, wrong declaration rather than on nothing.

The two pages therefore use one name for two shapes, in the same docs tree.

Suggested resolution

Rename the subject on this page to ReportComponentSchema (title, H1 lead, and any other prose reference), which is what the page's own code already says. No source change.

Reproduce

head -12 content/docs/core/report-schema.mdx
grep -rn 'ReportComponentSchema' packages/types/src/reports.ts | head -3
ls node_modules/@objectstack/spec/json-schema/ui/Report.json

Refs: #6086 · PR #6168 (named the tables on this page) · #6155 (the same disease: one name, several shapes).

[yinlianghui-tw]

PM claim + dispatch order — R27

Claimed by the domain:devx @ objectui execution seat (#5748), PM session session_019b5UBNMtTzKbVtZZGvFuxe. Branch: claude/issue-6171-report-schema-name.

Ruling: take the card's own suggested resolution. Rename the subject to ReportComponentSchema. No source change.

This needs no contract decision, which is what separates it from its siblings (#6169, #6172's collision half, #6155 — all escalated or held). Three facts settle it without anyone choosing anything:

1. The page's own example fence already imports ReportComponentSchema. The prose disagrees with the code on the same page.
2. PR docs(core,guide,plugins): name the shape eight props tables describe #6168 already named this page's property tables ReportComponentSchema. The convention is set and landed; the title and H1 are simply the parts that sweep did not touch.
3. ReportComponentSchema is what actually exists (packages/types/src/reports.ts:354), and all four rows of the Basic Configuration table are members of it.

So the rename makes the page self-consistent and consistent with a landed precedent. ⛔ Do not propose renaming the type — the source is right and the prose is wrong.

⚠️ Why this is worse than a typo, and why the fix must not be a blind find-and-replace

ReportSchema is a real exported name — @objectstack/spec uses it for the dataset-bound report shape in json-schema/ui/Report.json (name / label / dataset / rows / columns / values). That is a different shape, and it is the one content/docs/plugins/plugin-report.mdx documents.

So a reader following the name today lands on a real, wrong declaration rather than on nothing — which is the harder failure to notice. And it means:

⛔ Do not rename occurrences of ReportSchema outside content/docs/core/report-schema.mdx. On plugin-report.mdx the name is correct and must stay. Scope the edit to the one page, and confirm by measurement that you have not touched the other.

What to change on that page

The card names three sites; verify the set rather than trusting the count:

• frontmatter title: "Report Schema (ReportSchema)"
• the H1 lead sentence
• any other prose reference on that page

Enumerate every occurrence on that page first and report the number, then confirm zero remain after the edit. If the page's own example fence or tables already say ReportComponentSchema, leave them exactly as they are — PR #6168 landed those and re-touching them would put this diff on top of a sweep for no reason.

Verification

• Re-measure before editing: confirm ReportSchema still resolves to nothing in this tree (not in @object-ui/types' built .d.ts, not in packages/*/src) and that ReportComponentSchema does resolve. ⭐ Both readings, not just the first — an empty grep with no positive control is not a reading, and this card's whole subject is a name that resolves somewhere unexpected.
• Confirm @objectstack/spec still exports ReportSchema for the other shape, so the "one name, two shapes" hazard is stated from a live reading rather than inherited from this card.
• Gate union with exit codes captured by redirect before any pipe, each quoting its own verdict line: check:doc-snippet-types, check:doc-types, docs:check-links, check:control-bytes.
• Derive each gate's scope from its own configuration rather than assuming which apply, and measure any exclusion instead of asserting it.
• Root vitest only, per objectui#3378 — never package-scoped.
• Changeset per the presence gate's own verdict. objectui has no skip-changeset mechanism, so that verdict is the declaration form.

Scope

content/docs/core/report-schema.mdx only. ⛔ Not plugin-report.mdx. ⛔ No source change. ⛔ Not #6121's subject — that card covers this same page's authoring examples contradicting their types (dataSource, exports) and is needs-user-decision; it is a different sentence set and is not yours. If you find the two overlapping in the same lines, stop and say so rather than deciding it.

⚠️ This page is also in #5867's core group (11 blocks / 1 file), currently blocked on #6121. Your diff is prose and frontmatter, not fences, so it should not collide — but note in your PR body that the page has in-flight interest, per the repo's shared-surface guidance.

---

Generated by Claude Code

[yinlianghui-tw]

{
 "issue": 6171,
 "status": "done",
 "branch": "claude/issue-6171-report-schema-name",
 "pr": "https://github.com/objectstack-ai/objectui/pull/6192",
 "premise_still_valid": true,
 "summary": "Renamed the subject of content/docs/core/report-schema.mdx from ReportSchema to ReportComponentSchema — prose and frontmatter only, no source change, no fence touched. The measured occurrence set is FOUR, not the three the card listed: frontmatter title (L2), H1 lead (L10), plus 'ReportSchema provides:' (L14) and 'ReportSchema is perfect for:' (L458), which the card's explicit list did not name. After the edit exact-word ReportSchema on the page = 0 (was 4) and ReportComponentSchema = 12 (was 8, all 8 pre-existing left byte-identical since PR #6168 landed them). PREMISE NUANCE worth recording: the card's literal wording 'ReportSchema resolves to nothing in this tree — not in @object-ui/types built .d.ts, NOT IN packages/*/src' is false on its second half. ReportSchema appears 15 times in packages/*/src — imported from @objectstack/spec/ui in app-shell metadata-admin and plugin-report, plus prose comments. The MATERIAL premise holds and is in fact stronger than the card stated: @object-ui/types does not export the bare name, because packages/types/src/spec-report.ts:103 deliberately re-exports the spec symbol prefixed as SpecReportSchema under the comment 'Spec* prefix to avoid collision with legacy reports.ts'. The repo had already renamed around this exact collision everywhere except this page's prose. Hazard confirmed live rather than inherited: spec 17.2.0 does export ReportSchema, and json-schema/ui/Report.json measures as name/label/description/type/dataset/rows/columns/values/... — the shape plugin-report.mdx documents, where the name is correct. No overlap with #6121: its subject lines are inside fences and the property table (L88, L231); this diff is L2/L10/L14/L458.",
 "tests": "All gates at final head 0f04ff605, tree clean, exit codes captured by redirect BEFORE any pipe, each quoted by its own verdict line. check:doc-snippets EXIT=0 'Semantic phase: 251 of 251 block(s) judged, 0 failed. / Every covered documentation snippet compiles against the built types.' | check:doc-types EXIT=0 'Every documented component type is registered.' (184 doc files, 1057 code blocks, 895 type literals) | docs:check-links EXIT=0 'Links are valid across 15 scan roots.' | check:control-bytes EXIT=0 'check-control-bytes: OK (scanned 5110 tracked text file(s); skipped 85 binary).' | check:doc-fences EXIT=0 'every TypeScript block in 223 document(s) is fenced ts/tsx/typescript, except 83 declared file(s) carrying 105 block(s) ... SHRINK-ONLY' — this fifth gate was NOT in the dispatch list; it was added by deriving scope from each gate's own config (DOCS_ROOT = content/docs covers this file), and its #5867 ratchet reading is unmoved since no fence changed. NOTE: the dispatch named check:doc-snippet-types; the real package script is check:doc-snippets (script file scripts/check-doc-snippet-types.mjs) — the real spelling is what ran. FIRST RUN of check:doc-snippets EXIT=1 and was NOT a failure of this diff: it printed 'The snippet program was NOT run: the packages it resolves against are not built'. After turbo run build (43/43 successful) it re-ran green — recorded because an unbuilt-tree exit is indistinguishable from a real failure at the exit-code level. EXCLUSION MEASURED not asserted: git status --porcelain = exactly 1 changed file, and content/docs/plugins/plugin-report.mdx re-measures to the identical sha256 6003c22e9765c58b90deb3c3db020c64ca2066bb2a01b3c454fd3ef1e34e1bf3 with its 1 correct ReportSchema occurrence intact. BOTH READINGS with positive control: bare ReportSchema in @object-ui/types built .d.ts = 0 files; positive control ReportComponentSchema = 5 files, declared at packages/types/dist/reports.d.ts:289 (source packages/types/src/reports.ts:359 — the card said :354). CHANGESET: none, per the presence gate's own verdict 'No source of a released package changed in this range, so no changeset is owed.' (EXIT=0) — objectui has no skip-changeset label mechanism so that verdict is the declaration form. ROOT VITEST (never package-scoped) run NARROWED, with the narrowing declared as a measurement: (1) population read from vitest's own config, vitest list --filesOnly = 1971 test files; (2) of that exact 1971-file population, 0 reference core/report-schema; (3) config invariance — vitest.config.mts include globs are packages/**, examples/**, eslint-rules/**, scripts/** and the string content/docs appears 0 times in the config, so no project can pick up an .mdx under it. The one test file that even mentions this page does so in a prose comment and never reads it from disk; run anyway: 1 passed (1), 5 tests passed. Control-byte self-scan of the edited file beyond the gate: no match (clean). All heavy commands ran through the shared lock (scripts/pm/os-verify-lock.sh), every VERDICT line command-exit 0.",
 "open_questions": [],
 "out_of_scope_findings": []
}

---

Generated by Claude Code

[yinlianghui-tw]

os-dev-report

This comment SUPERSEDES the earlier report. That copy was posted with the marker as an HTML comment and the sanitizer stripped the angle-bracket fragment on write — read back, its body begins with a bare fence and contains no os-dev-report marker in any form, so it is invisible to the PM's scan. The JSON below is byte-identical in content; only the marker spelling differs (literal text, not an HTML comment). Ignore the earlier copy.

{
 "issue": 6171,
 "status": "done",
 "branch": "claude/issue-6171-report-schema-name",
 "pr": "https://github.com/objectstack-ai/objectui/pull/6192",
 "premise_still_valid": true,
 "summary": "Renamed the subject of content/docs/core/report-schema.mdx from ReportSchema to ReportComponentSchema — prose and frontmatter only, no source change, no fence touched. The measured occurrence set is FOUR, not the three the card listed: frontmatter title (L2), H1 lead (L10), plus 'ReportSchema provides:' (L14) and 'ReportSchema is perfect for:' (L458), which the card's explicit list did not name. After the edit exact-word ReportSchema on the page = 0 (was 4) and ReportComponentSchema = 12 (was 8, all 8 pre-existing left byte-identical since PR #6168 landed them). PREMISE NUANCE worth recording: the card's literal wording 'ReportSchema resolves to nothing in this tree — not in @object-ui/types built .d.ts, NOT IN packages/*/src' is false on its second half. ReportSchema appears 15 times in packages/*/src — imported from @objectstack/spec/ui in app-shell metadata-admin and plugin-report, plus prose comments. The MATERIAL premise holds and is in fact stronger than the card stated: @object-ui/types does not export the bare name, because packages/types/src/spec-report.ts:103 deliberately re-exports the spec symbol prefixed as SpecReportSchema under the comment 'Spec* prefix to avoid collision with legacy reports.ts'. The repo had already renamed around this exact collision everywhere except this page's prose. Hazard confirmed live rather than inherited: spec 17.2.0 does export ReportSchema, and json-schema/ui/Report.json measures as name/label/description/type/dataset/rows/columns/values/... — the shape plugin-report.mdx documents, where the name is correct. No overlap with #6121: its subject lines are inside fences and the property table (L88, L231); this diff is L2/L10/L14/L458.",
 "tests": "All gates at final head 0f04ff605, tree clean, exit codes captured by redirect BEFORE any pipe, each quoted by its own verdict line. check:doc-snippets EXIT=0 'Semantic phase: 251 of 251 block(s) judged, 0 failed. / Every covered documentation snippet compiles against the built types.' | check:doc-types EXIT=0 'Every documented component type is registered.' (184 doc files, 1057 code blocks, 895 type literals) | docs:check-links EXIT=0 'Links are valid across 15 scan roots.' | check:control-bytes EXIT=0 'check-control-bytes: OK (scanned 5110 tracked text file(s); skipped 85 binary).' | check:doc-fences EXIT=0 'every TypeScript block in 223 document(s) is fenced ts/tsx/typescript, except 83 declared file(s) carrying 105 block(s) ... SHRINK-ONLY' — this fifth gate was NOT in the dispatch list; it was added by deriving scope from each gate's own config (DOCS_ROOT = content/docs covers this file), and its #5867 ratchet reading is unmoved since no fence changed. NOTE: the dispatch named check:doc-snippet-types; the real package script is check:doc-snippets (script file scripts/check-doc-snippet-types.mjs) — the real spelling is what ran. FIRST RUN of check:doc-snippets EXIT=1 and was NOT a failure of this diff: it printed 'The snippet program was NOT run: the packages it resolves against are not built'. After turbo run build (43/43 successful) it re-ran green — recorded because an unbuilt-tree exit is indistinguishable from a real failure at the exit-code level. EXCLUSION MEASURED not asserted: git status --porcelain = exactly 1 changed file, and content/docs/plugins/plugin-report.mdx re-measures to the identical sha256 6003c22e9765c58b90deb3c3db020c64ca2066bb2a01b3c454fd3ef1e34e1bf3 with its 1 correct ReportSchema occurrence intact. BOTH READINGS with positive control: bare ReportSchema in @object-ui/types built .d.ts = 0 files; positive control ReportComponentSchema = 5 files, declared at packages/types/dist/reports.d.ts:289 (source packages/types/src/reports.ts:359 — the card said :354). CHANGESET: none, per the presence gate's own verdict 'No source of a released package changed in this range, so no changeset is owed.' (EXIT=0) — objectui has no skip-changeset label mechanism so that verdict is the declaration form. ROOT VITEST (never package-scoped) run NARROWED, with the narrowing declared as a measurement: (1) population read from vitest's own config, vitest list --filesOnly = 1971 test files; (2) of that exact 1971-file population, 0 reference core/report-schema; (3) config invariance — vitest.config.mts include globs are packages/**, examples/**, eslint-rules/**, scripts/** and the string content/docs appears 0 times in the config, so no project can pick up an .mdx under it. The one test file that even mentions this page does so in a prose comment and never reads it from disk; run anyway: 1 passed (1), 5 tests passed. Control-byte self-scan of the edited file beyond the gate: no match (clean). All heavy commands ran through the shared lock (scripts/pm/os-verify-lock.sh), every VERDICT line command-exit 0.",
 "open_questions": [],
 "out_of_scope_findings": []
}

---

Generated by Claude Code

[yinlianghui-tw]

PM review — ACCEPTED. PR #6192 armed. ⭐ The card's premise was half false, and the correction makes the ruling stronger.

Reviewed against a pinned ref. All 21 checks green, 0 failures.

The measurement I asked for found more than the card listed

The card named three sites. There are four — the frontmatter title (L2), the H1 lead (L10), plus "ReportSchema provides:" (L14) and "ReportSchema is perfect for:" (L458), neither of which the card's explicit list named.

This is why the order said verify the set, do not trust the count. Re-derived myself against main:

reading	before	after
bare ReportSchema on the page	4	0
ReportComponentSchema on the page	8	12
diff	—	4 files… no: 1 file, +4 / −4

The 8 pre-existing ReportComponentSchema occurrences are byte-identical — PR #6168 landed those and they were not re-touched, as ordered.

⭐ And my explicit negative control holds: content/docs/plugins/plugin-report.mdx hashes identically before and after (6003c22e…), with its one correct ReportSchema occurrence intact. That was the thing a blind find-and-replace would have destroyed, and it is now proven untouched by sha rather than by assertion.

⭐ The premise correction is the best part of this round

The card said ReportSchema "resolves to nothing in this tree — not in @object-ui/types' built .d.ts, not in packages/*/src". The second half is false: it appears 15 times in packages/*/src, imported from @objectstack/spec/ui by app-shell metadata-admin and plugin-report.

The dev could have quietly relied on the card and shipped the same diff. Instead they measured, found the card wrong, and reported it — and what they found makes the ruling better founded than I knew when I made it:

packages/types/src/spec-report.ts:103 deliberately re-exports the spec symbol as SpecReportSchema, under the comment "Spec* prefix to avoid collision with legacy reports.ts".

⭐ The repo had already renamed around this exact collision — everywhere except this page's prose. So this is not a fresh naming judgement at all; it is the last unswept instance of a convention the codebase already adopted. That is a much stronger basis than "the page's own example fence disagrees with its title", which is what I ruled on.

Both readings were taken with a positive control, as ordered: bare ReportSchema in the built .d.ts = 0 files; ReportComponentSchema = 5 files, declared at packages/types/dist/reports.d.ts:289. (Source line is reports.ts:359, not the :354 the card gave — another inherited number that had moved.)

The @objectstack/spec hazard was confirmed live rather than inherited: 17.2.0 does export ReportSchema, and Report.json measures as the dataset-bound shape plugin-report.mdx documents.

No collision with #6121

Verified rather than assumed: #6121's subject lines are inside fences and the property table (L88, L231); this diff is L2 / L10 / L14 / L458. Disjoint, so the core group's eventual unblocking is unaffected.

Two process notes I am taking on the chin

1. My order named check:doc-snippet-types again — the script file, not the npm script (check:doc-snippets). Second card in a row where a dev had to correct that. It is now in objectstack#11901's territory as a recurring PM-side defect, not a one-off.
2. ⭐ The dev derived check:doc-fences from the gates' own config even though my list omitted it — and its finding(docs): TypeScript examples fenced as plaintext escape check-doc-snippet-types — 211 blocks in 122 files, and #5044 proved one of them taught a type error under a gate that reports the file as covered #5867 ratchet reading is unmoved, since no fence changed. That is the check that would have caught a rename accidentally touching a fenced block.

⭐ And one reading worth carrying to every doc card: check:doc-snippets first ran exit=1 with "The snippet program was NOT run: the packages it resolves against are not built". Correctly diagnosed as an unbuilt tree, rebuilt, re-run green — and recorded, because an unbuilt-tree exit is indistinguishable from a real failure at the exit-code level. A dev who trusted the first exit code would have reported a false red; one who trusted a cached green would have reported a false pass.

The vitest narrowing was declared as a measurement rather than a claim: population read from vitest list --filesOnly (1971 files), 0 of which reference this page, and content/docs appears 0 times in the config so no project can pick up an .mdx under it.

---

Generated by Claude Code