Skip to content
This repository was archived by the owner on Nov 4, 2026. It is now read-only.

Commit 841dd2b

Browse files
claude[bot]claude
andauthored
feat(types)!: redirect the node recursion point at AnyComponentSchema (#8344) (#8501)
* feat(types)!: redirect the node recursion point at AnyComponentSchema (#8344) Every child slot is `z.union([SchemaNodeSchema, z.array(SchemaNodeSchema)])`, and `SchemaNodeSchema`'s component arm was `BaseSchemaCore` — the ~21 base keys and nothing type-specific — so per-type enforcement was ROOT-ONLY at every depth, for every component type. That is objectui#7869, measured there: an off-spec `size` on a nested `icon` node was accepted while the same node alone was refused. The arm is now `AnyComponentSchema`. ⛔ Nothing here is `.strict()`; no declaration is repaired. Measured over the catalog + docs corpora on c90395b (554 node documents): 45 refused before, 54 after — the nine documents the card enumerates, each pre-existing debt this surfaces rather than creates. Two mechanical constraints, both measured rather than assumed: - `AnyComponentSchema` is built in `index.zod.ts` from all 13 category modules while 14 modules import `base.zod.ts`, so the arm cannot be an import: `z.lazy` defers evaluation, not the module graph, and the import deadlocks on `BaseSchema`'s TDZ when the graph is entered at `base.zod.js`. - It is a written `z.union` OPTION SLOT and not a `z.lazy` holder, because `z.lazy` memoises: a holder lets whichever module graph parses first decide the accept set for the whole process. `z.union` re-reads its options every parse, so the fill is live and no first parse can freeze the pre-fill answer in. `complex.zod.ts#DashboardWidgetSchema.component` names `BaseSchema` explicitly now. It is the one slot where the redirect would reverse a standing ruling: `metric-card` is objectui's CLOSED widget-slot component extension (objectstack#8593), admitted there and deliberately not an arm of `AnyComponentSchema`. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CZY49skxUBYyJcdnTcYPrE * fix(types): record the DashboardWidgetSchema.component drift the #8344 carve-out creates The parity ledger is a TYPE MAP over the mirrors, so the `complex.zod.ts` change in ae99480 moved a drift row INSIDE zod-mirror-parity.test.ts without editing it: `DashboardWidgetSchema.component` names `BaseSchema` where TS declares `SchemaNode`, so the five primitive arms are newly narrower-than-declared. Re-derived from the tree with the compiler API, not copied: `DriftOf` for the pair resolves to 'component' | 'options'. The header figure moves with it, 64 -> 65 keys across an unchanged 42 entries, derived by an AST count of the interface. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CZY49skxUBYyJcdnTcYPrE * docs(types): declare the chatbot widening, the bundle caveat and the memoisation Three accept/reject facts and one caveat the changeset owed a reader: - `DashboardWidgetSchema.component` narrows (a primitive in that slot was accepted and is refused now); - `SchemaNodeSchema` moves TDZ_BOUND -> MEMOISED; - `ChatbotSchema.body` is a record and therefore WIDER than the base arm, so a nested chatbot node carrying one is refused before and accepted now. Measured with a corpus-valid seed at two child slots, against both the narrowing and a legal-node control; - the `sideEffects: false` bundle caveat: a bundler that drops the barrel body leaves the redirect inert, measured on this repo's own Vite/rollup lib build. The pin's header claimed `getter() === getter()` is FALSE for the exported wrapper. Measured on the built face, that holds on `main` and NOT at this head: the redirect made this const MEMOISED, and the `fill is LIVE` leg works because of it. The header now states both readings and why the wrapper is still the handle the pin uses. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CZY49skxUBYyJcdnTcYPrE * docs(changeset): point the chatbot widening at its follow-up, and state the bundle caveat as measured The widening declaration now names objectui#8572, the card filed for the narrowing decision, so the declaration reads as "declared, follow-up filed" rather than as an accepted permanent state. The bundle caveat is restated from what was actually measured this round. Three candidate fixes were tried on disk and none of them is a manifest edit this change may make on its own: - narrowing `sideEffects` to an array is not a legal declaration for this package. `scripts/check-side-effects-array.mjs` requires an array to name every ENTRY FORM (12 missing on a one-element array); `scripts/__tests__/side-effects-declaration-consistency.test.ts` refuses a named entry that has no load-time effect. This package's entry forms are pure, so the two rules have no common solution here. Both readings taken from the gates themselves. - a bare top-level call in the barrel is dropped too: `"sideEffects": false` is a package-level promise that no in-module spelling overrides. Measured with the statement on disk and in `dist`: the probe entry still ACCEPTED the nested off-spec node. - removing the field closes the leak at +16,078 gzipped bytes on the console `framework` chunk — which now FITS, since the ceiling raise landed — but it drops the workspace census from 5 packages to 4 and fails that same pin's population floor. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CZY49skxUBYyJcdnTcYPrE * docs(changeset): name the two follow-up cards the bundle caveat leaves open The caveat now points at objectui#8577 (the leak and the manifest decision, carrying every measured figure and the maintainer-floor census edit the closing route needs) and objectui#8578 (the classifier that scores this package zero load-time registrations because it counts top-level call statements and cannot see an effect inside a `const` initializer). Changeset text only. No source, no manifest, no test moved. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CZY49skxUBYyJcdnTcYPrE * feat(types)!: bind the component union in the getter, and narrow the chatbot arm Implements decision batch #93 (objectui#8344 comment 5585333656), items F2, F3, F5 and the stale-text half of items 8/9. Changeset text is NOT yet updated in this commit; its three false "by ruling" attributions are the next push. F3 — the tree-shake leak. `base.zod.ts` now imports `AnyComponentSchema` and reads that binding INSIDE `SchemaNodeSchema`'s `z.lazy` getter. The option-array write, `defineNodeComponentUnion` and its identity assertion are gone with it. `"sideEffects": false` stays true and untouched: this module performs no load-time write at all now. Measured, not assumed — this repo's own Vite/rollup lib build, an entry importing ONLY `CardSchema`: before this commit 370,652 raw / 113,887 gzip, no fill, nested off-spec node ACCEPTED — the redirect silently inert after 1,147,266 raw / 342,193 gzip, nested off-spec node REFUSED — the union is retained because the binding is read A graph that never evaluates the barrel now throws `ReferenceError: Cannot access 'BaseSchema' before initialization` at import instead of quietly answering as `main`. That is the ruled behaviour, and its cost is paid here: 102 `packages/types` test files entered at a category module and now carry a barrel-first import. Whole unit project after the fix: 989 files, 16,837 tests, 0 failures. F2 — the chatbot widening, eliminated rather than declared. The arm the getter installs is `AnyComponentSchema.superRefine(...)`, which checks a nested `chatbot` node's `body` against `BaseSchemaCore.shape.body`. The root mirror is untouched, so a root `chatbot` with a record `body` still parses and the same node one slot down does not. Both directions pinned, plus a non-vacuity leg and a leg asserting the refusal names `body`. The discrimination objectui#8498 added survives the wrapper (`propValues` intact), so a nested refusal still costs one arm. F5 — depth on the redirected path: 276 / 3,626 / 8,404 / 14,610 / 22,244 chars at depths 0-4, all refused, none throwing. New pins cover depths 0-4 through `safeValidateSchema`, a linear-growth ceiling at depth 4, and a legal-leaf control. Items 8/9 — `any-component-union-fanout.test.ts`'s rationale said a nested document is "simply ACCEPTED"; corrected in place. The pin's identity-leg comment and header now describe THIS head. The objectui#7918 row returns to `TDZ_BOUND`: the getter builds the node union per call again, so `getter() === getter()` is FALSE, and `unstableLazyExports` reads 8 again. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CZY49skxUBYyJcdnTcYPrE * docs(changeset): state what ships, and drop three attributions that were never ruled Batch #93 refused the routes the previous revision described, so the changeset described a PR that does not exist. Corrected, not softened: - the widening fact said "Declared here rather than eliminated, by ruling". No ruling said that; #93 ordered it eliminated. It now records the nested refusal and the untouched root, and points the root question at objectui#8572. - the `TDZ_BOUND -> MEMOISED` fact is gone: that byproduct belonged to the option-array spelling and the row is `TDZ_BOUND` again. - the bundle caveat said the fix was "a maintainer-floor authorisation, deliberately not taken here" and "Until objectui#8577 is ruled". Both false against #93: the ruled route needs no manifest change and no census-floor edit, and it ships in this PR. The section now states the wiring, the measured before/after, and both byte costs. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CZY49skxUBYyJcdnTcYPrE * fix(types): revert the F3 import binding — CI proved it breaks a real consumer ⛔ The `Build Docs` failure on 2ac5381 is THIS BRANCH'S CODE, not the changeset text: `ReferenceError: Cannot access 'BaseSchema' before initialization` out of `packages/types/dist/zod/app.zod.js`, prerendering `/docs/guide/schema-catalog` through `plugin-view`. Reproduced locally in one line — with the binding in place, importing `dist/zod/app.zod.js` throws; without it, it loads clean. Mechanism, measured rather than reasoned: making `base.zod.ts` import the barrel gives the cycle an edge that is only safe when the barrel is evaluated FIRST. Node honours that if the entry is `./zod`; a bundler is free to order the cycle category-module-first, and the site's build does. ⇒ the ruled F3 spelling is sound for a module graph and unsound for a bundle, which is the opposite of the property it was chosen for. My own docblock claim that "consumers cannot hit that" was falsified by CI, and the 102-file barrel-first hygiene could not have helped: the failing consumer already imports the barrel. This commit therefore restores the wiring CI was last green on (`d375037a8`) and KEEPS batch #93's F2 in the spelling the reviewer originally wrote it in: the slot-0 write installs `union.superRefine(...)`, so a nested `chatbot` node with a record `body` is refused while the published root mirror is untouched. The identity assertion now checks the WRAPPER it installed, and the pin says why a `toBe(AnyComponentSchema)` assertion would go green if the narrowing were dropped. The 102 barrel-first imports are reverted with the binding that needed them; the objectui#7918 row is `MEMOISED` again, matching this wiring. ⇒ F2 and F5 ship; F3 does NOT, and the changeset now states the gap, the CI evidence and all four measured candidates instead of claiming a fix. Green on this tree: build 0, type-check 0 (all three projects), packages/types 148 files / 2,824 tests / 0 failed, the four changeset gates 0, and the category-first import that CI choked on now loads clean. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CZY49skxUBYyJcdnTcYPrE * docs(types): declare the tree-shake gap as shipped, cite one measurement, point at objectui#8598 Implements decision batch #98 on objectui#8344 (comment 5587037055), Finding 3 of the contract review of `ca2037680` (PR #8501 comment 5587000173). The byte pair `base.zod.ts` quoted (369,733 / 1,144,999) and the pair the changeset quoted (370,652 / 1,149,749) were the same measurement taken on two heads. Both texts now cite ONE measurement, taken on this head with a named instrument: a Vite 8.2.1 lib build of the published `dist/zod` face, `es`, esbuild-minified, `zod` 4.4.3 and `@objectstack/spec` external, each entry built alone and read in a fresh Node process — barrel, CardSchema + AnyComponentSchema 750,542 / 206,815 REFUSED fill present barrel, CardSchema only 212,567 / 61,025 ACCEPTED fill absent deep-link entry at layout.zod.js 212,563 / 61,030 ACCEPTED fill absent Minified so that editing this very docblock cannot move the figure it carries. The stale "its disposition is a ruling in flight" sentence is gone: the ruling is in. The gap ships DECLARED, the declaration names who is exposed (an external consumer whose bundler honours `sideEffects: false` and never reads `AnyComponentSchema` keeps the pre-redirect accept set for NESTED nodes; root-level enforcement and every union-reading graph get the new set), and the changeset's leak paragraph points at objectui#8598 — the `./zod` face built as one module — as the card that closes it. No source outside comments moved. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TezFG8ZMrNH6n5VTNpPpdH --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 86ef0c7 commit 841dd2b

11 files changed

Lines changed: 690 additions & 37 deletions
Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
---
2+
'@object-ui/types': minor
3+
---
4+
5+
Redirect the node recursion point from `BaseSchemaCore` to `AnyComponentSchema`
6+
(objectui#8344) — a nested node is now judged by its OWN component schema.
7+
8+
**Behaviour change, deliberately, at every depth below the root.** Every child slot
9+
(`body`, `children`, and every per-component redeclaration of them) is
10+
`z.union([SchemaNodeSchema, z.array(SchemaNodeSchema)])`, and `SchemaNodeSchema`'s
11+
component arm was `BaseSchemaCore` — the ~21 base keys and nothing type-specific. So
12+
per-type enforcement was ROOT-ONLY, for every component type: objectui#7869 measured
13+
an off-spec `size` on a nested `icon` node being ACCEPTED while the same node standing
14+
alone was refused. The arm is now the union of the registered component mirrors, so
15+
the same node gets the same verdict at every depth.
16+
17+
⛔ **Nothing here is `.strict()`.** `BaseSchemaCore` keeps its passthrough, no schema
18+
gained a `catchall`, and no declaration was repaired. Measured over the catalog +
19+
docs corpora on `c90395b2` (431 catalog files + the `json` fences under
20+
`content/docs`, 554 node documents): **45 refused before, 54 after** — re-derived
21+
unchanged after merging `main` `3f775eeb8`, same pair, same instrument — nine documents,
22+
each one pre-existing debt this SURFACES rather than creates. Four have a child whose
23+
`type` resolves in no arm; five carry a child already red under its own schema and
24+
shielded until now by the recursion point.
25+
26+
**What an author sees.** A document whose nested node is off-spec — a bad enum value,
27+
a wrong-typed key, a `type` no component mirror declares — is refused now, where it
28+
parsed green before. That is the point of the change, and it is why this ships behind
29+
a contract review rather than as a patch.
30+
31+
**Two mechanical notes for anyone editing the wiring.** `AnyComponentSchema` is built
32+
in `zod/index.zod.ts` from all 13 category modules and 14 modules import
33+
`zod/base.zod.ts`, so the arm cannot be an import — `z.lazy` defers evaluation, not
34+
the module graph. It is a written option slot that `index.zod.ts` fills inside
35+
`AnyComponentSchema`'s own initializer, and it is a `z.union` option rather than a
36+
`z.lazy` holder because `z.lazy` memoises its getter: a holder would let whichever
37+
module graph parsed first decide the accept set for the whole process. Both
38+
constraints are measured, and the reasoning lives on `defineNodeComponentUnion` in
39+
`zod/base.zod.ts`.
40+
41+
42+
## Three more public-surface facts this ships
43+
44+
**1. `DashboardWidgetSchema.component` narrows.** That legacy `{ id, component, layout }`
45+
envelope names `BaseSchema` explicitly instead of following the redirect, so the widget
46+
slot keeps admitting `metric-card`, objectui's closed widget-slot extension. One measured
47+
delta on that slot and only one: a PRIMITIVE in it (`component: 'text'`) was accepted
48+
through `SchemaNodeSchema` and is refused now. No corpus document, fixture or pin writes
49+
one.
50+
51+
**2. The `chatbot` record `body` is refused NESTED, and still accepted at the ROOT.**
52+
`ChatbotSchema.body` mirrors the chat API's body params as
53+
`z.record(z.string(), z.unknown())`, which is WIDER than `BaseSchemaCore.body` — the only
54+
wider redeclaration among the 109 base-key redeclarations across the union's arms. Judging
55+
a child by its own schema would therefore have ADMITTED, at every child slot, a document
56+
the base arm refused. ⛔ That widening is eliminated rather than declared: the arm the
57+
recursion point installs carries a check that a nested `chatbot` node's `body` still fits
58+
the node slot. Measured, corpus-valid chatbot seed plus `body: { model, temperature }`:
59+
accepted at the root before and after; inside `card.body[]` and `div.children[]` refused
60+
before and refused now. ⇒ the redirect narrows at all 109 redeclarations and widens at
61+
none. The published `ChatbotSchema` is untouched — whether its own `body` should carry the
62+
chat API's params is a separate question, recorded on objectui#8572 and deliberately not
63+
decided here.
64+
65+
**3. ⚠️ KNOWN GAP, declared rather than papered over: a bundled consumer that never reads
66+
`AnyComponentSchema` can tree-shake the redirect away.** This package declares
67+
`"sideEffects": false` and the arm is filled by a statement in the `./zod` barrel's body, so a
68+
bundler that honours the flag and sees no reference to `AnyComponentSchema` may drop the fill —
69+
and then every child slot validates with the PRE-redirect arm, with no error and no warning.
70+
Who is exposed, stated plainly: an external consumer whose bundler honours `sideEffects: false`
71+
and never reads `AnyComponentSchema` keeps `main`'s accept set for NESTED nodes. Root-level
72+
enforcement is unchanged by the gap, and every consumer whose import graph reads the union —
73+
the `./zod` barrel under Node or vitest, `@object-ui/cli`'s `check` / `validate` (they call
74+
`safeValidateSchema`, which references the union), any bundle that imports `AnyComponentSchema`
75+
— gets the new set at every depth.
76+
77+
Measured on the published `dist/zod` face of this head (Vite 8.2.1 lib build, `es`,
78+
esbuild-minified, `zod` 4.4.3 and `@objectstack/spec` external, so the figures are this
79+
package's own bytes; nested off-spec node = `{ type: 'icon', icon: 'check', size: 'huge' }`
80+
inside `card.body[]`, parsed through `CardSchema`):
81+
82+
| entry | nested off-spec node | bundle (raw / gzip) | fill in output |
83+
| --- | --- | --: | --- |
84+
| barrel, `CardSchema` and `AnyComponentSchema` imported | REFUSED | 750,542 / 206,815 B | present |
85+
| barrel, `CardSchema` only | **ACCEPTED (inert)** | 212,567 / 61,025 B | absent |
86+
| deep-link entry at `layout.zod.js` | **ACCEPTED (inert)** | 212,563 / 61,030 B | absent |
87+
88+
⛔ It is NOT closed here, and the reason is measured rather than argued. The route that closes
89+
it by binding the union inside `SchemaNodeSchema`'s `z.lazy` getter was implemented and pushed,
90+
and CI refused it: `Build Docs` failed with `ReferenceError: Cannot access 'BaseSchema' before
91+
initialization` out of `packages/types/dist/zod/app.zod.js`, because that import makes
92+
`base.zod.ts` depend on the barrel and a bundler is free to evaluate the resulting cycle
93+
category-module-first. Reproduced locally in one line — importing `dist/zod/app.zod.js` throws
94+
with the binding in place and loads clean without it. The other three candidates were measured
95+
too: a narrowed `sideEffects` array is not a legal declaration for this package (one gate
96+
requires every entry form to be named, another refuses a named entry with no load-time effect,
97+
and this package's entry forms are pure), a bare top-level call is dropped by the same flag,
98+
and dropping the flag costs 16,078 gzipped bytes on the console `framework` chunk and moves a
99+
workspace census a guard pins.
100+
101+
⇒ **The card that closes this gap is objectui#8598**: build the `./zod` subpath as ONE bundled
102+
module, so a consumer bundler has no internal graph to link past and every entry — one schema,
103+
the barrel, or a deep link — gets the same accept set. Until it lands, a consumer that bundles
104+
`@object-ui/types/zod` should keep `AnyComponentSchema` in its import graph, which is enough to
105+
make the redirect apply.

‎content/docs/api/schema-reference.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -178,7 +178,7 @@ A styled container with optional header, body, and footer regions.
178178
"variant": "outline",
179179
"hoverable": true,
180180
"header": [
181-
{ "type": "badge", "label": "Live", "variant": "success" }
181+
{ "type": "badge", "label": "Live", "variant": "secondary" }
182182
],
183183
"body": [
184184
{ "type": "statistic", "label": "Total Revenue", "value": "$12,400" }
@@ -1281,8 +1281,8 @@ Schemas are designed to compose. Nest any `SchemaNode` inside another to build c
12811281
"type": "dashboard",
12821282
"columns": 2,
12831283
"widgets": [
1284-
{ "id": "w1", "title": "Leads", "body": { "type": "statistic", "value": "142" } },
1285-
{ "id": "w2", "title": "Revenue", "body": { "type": "statistic", "value": "$24k" } }
1284+
{ "type": "metric-card", "title": "Leads", "value": "142" },
1285+
{ "type": "metric-card", "title": "Revenue", "value": "$24k" }
12861286
]
12871287
}
12881288
},

‎content/docs/guide/schema-playground.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -103,9 +103,9 @@ A content card with a header, description, and body:
103103
"icon": "dollar-sign",
104104
"body": {
105105
"type": "stack",
106-
"direction": "vertical",
107-
"gap": "md",
108-
"items": [
106+
"direction": "col",
107+
"gap": 4,
108+
"children": [
109109
{
110110
"type": "text",
111111
"content": "$48,250",

‎packages/types/src/__tests__/any-component-union-fanout.test.ts‎

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -28,11 +28,18 @@
2828
* refused node 4 deep 19,311 -> 4,330 chars
2929
*
3030
* A bound that also passed on the flat union would assert nothing, which is the
31-
* failure mode this card is most exposed to: `AnyComponentSchema` does not yet
32-
* recurse into child slots (objectui#7869 / objectui#8344), so a nested document
33-
* is simply ACCEPTED and a naive "does not throw at depth 4" test is green for
34-
* the wrong reason. The depth case below is therefore built on `MenuItemSchema`,
35-
* which ALREADY refuses at depth on this tree.
31+
* failure mode this card was most exposed to. ⚠️ The reason it was exposed has
32+
* since changed and this paragraph is corrected in place rather than deleted:
33+
* when this file was written `AnyComponentSchema` did not recurse into child
34+
* slots, so a nested document was simply ACCEPTED and a naive "does not throw at
35+
* depth 4" test was green for the wrong reason — which is why the depth case
36+
* below is built on `MenuItemSchema`, one of the few schemas that ALREADY refused
37+
* at depth on that tree. objectui#8344 has since redirected the node recursion
38+
* point, so a nested off-spec node IS refused now and the `MenuItemSchema` choice
39+
* is no longer load-bearing. ⛔ It stays anyway: it is the case this card measured
40+
* and re-pointing it would retire the measurement without replacing it. The
41+
* redirected path gets its own depth pin in
42+
* `node-recursion-point-8344.test.ts`, where the linear-growth reading lives.
3643
*/
3744

3845
import { describe, it, expect } from 'vitest';

0 commit comments

Comments
 (0)