fix(spec-docs): one shared def renders one optionality face on every reference page

[objectstack-fleet]

Fixes #21466

Clause-②: no

What was wrong

A generated reference page gave two optionality answers for one shared def. The card measured it on PR #21463's regeneration of content/docs/references/ui/component.mdx: ObjectGridProps.grouping.fields[] rendered order? / collapsed?, and data[provider='api'].read / .write rendered method?, while the same defs on the ObjectKanbanProps, ObjectGanttProps, ObjectMapProps and ObjectTreeProps rows rendered them required.

Mechanism: measured, and it is not evaluation order

The card's working hypothesis was an evaluation-order dependence: a memoised conversion, a .shape getter or a def cache decided by whichever caller came first. Measured, there is none:

• Two-order harness. The five props schemas go through the generator's own projectPublishedJsonSchema and its output-to-input fallback, under 2 import orders (ui/view.zod first or ui/component.zod first) times 2 emission orders (grid first or grid last), with OS_EAGER_SCHEMAS=1 as gen:schema runs. All four orders print byte-identical output, with 1 distinct output per tree. That holds on main at 6210f8870a, on feat(spec)!: an object-grid page block types the seven members the grid reads, and resizableColumns retires for resizable (#21445) #21463's head 38159d1362, and on this branch's final head.
• What actually flips is the document's io mode. On feat(spec)!: an object-grid page block types the seven members the grid reads, and resizableColumns retires for resizable (#21445) #21463's head, ui/ObjectGridProps.json is the one props schema emitted "(input shape)". Its output projection throws "Transforms cannot be represented in JSON Schema", because one newly typed member carries a transform. So build-schemas.ts falls back to io: 'input' for the whole document. Input mode leaves .default() members out of required, output mode lists them, and both keep default.
• The renderer leaked that mode. The Type column's { … } shape summary marked a key optional from required alone (scripts/lib/format-type.ts). The Required column already read default (renderRequiredCell, [finding] reference-doc tables render .default()-bearing fields as required (✅) for every output-shape def — authors read "must write" where the schema means "may omit" #8703's rule). Before this change, [finding] reference-doc tables render .default()-bearing fields as required (✅) for every output-shape def — authors read "must write" where the schema means "may omit" #8703's rule covered only one of the two places a page states optionality.

Corpus reading on main 6210f8870a, with the old renderer: 1398 exports project in both io modes. When each section is rendered from both projections, 215 of them differ, over 483 lines. Each of the 483 lines differs only by this marker.

Fix

There is one predicate now, isAuthorOmittable(prop, required) in format-type.ts: default decides, and required breaks the tie. Both optionality positions read it: the shape summary's key?: marker and renderRequiredCell, whose output is unchanged byte for byte.

What does not change:

• No emitted JSON Schema. Under [finding] reference-doc tables render .default()-bearing fields as required (✅) for every output-shape def — authors read "must write" where the schema means "may omit" #8703's design, the published files keep describing the post-parse shape.
• No packages/spec/src/** change.
• No per-row patch, and no hand edit of a generated page.

Afterwards the same corpus measurement reads 0 of 1398 differing (0 lines) on 6210f8870a, and 0 of 1392 on the final head d5d88f55a5. The population is smaller on the final head because ObjectGridProps is input-only there and main's agent.lifecycle retirement removed some exports.

Regenerated pages (the second pin)

check:generated --fix on the base changed 459 rows on 86 pages. Each changed row only adds ? to defaulted members (932 markers in total). No row removes one, and no other byte moved.

main was merged in twice, and each time the colliding generated page was regenerated on the merged tree rather than text-merged:

• The first merge brought feat(spec)!: an object-grid page block types the seven members the grid reads, and resizableColumns retires for resizable (#21445) #21463 and regenerated component.mdx.
• The second brought main at 0b8239111f (the agent.lifecycle retirement plus one non-docs commit) and regenerated agent.mdx. automation/state-machine.mdx stays deleted, as main has it.

Against main at 0b8239111f (and identically against 6e33b67912), the references delta is 453 rows on 85 pages, 925 markers added. With every ?: normalised to :, each of the 85 pages is byte-identical to main's copy. No row removes a marker.

On the final component.mdx:

• method?: appears 8 times and method: 0 times; collapsed?: 3 times and collapsed: 0 times.
• The grid's and the kanban's grouping.fields rows are byte-identical.
• The four data[provider='api'] read rows are byte-identical, and so are the four write rows.

The same JSON from #21463's head, rendered with the old renderer, gives the card's exact rows (order? on the grid and order on the kanban). Rendered with this branch's renderer, every shared-def row is identical.

Pin

packages/spec/scripts/schema-section.test.ts has a new block, "one shared def renders one face, whichever io mode its document took". Two parent rows share a grouping def and a { url, method } def through the generator's own projection. One parent projects in output mode; the other projects only in input mode, because it has a transform member.

• Two precondition cases prove the fixture really is one output-mode and one input-mode document, and that their required arrays disagree. So the identical rendering comes from the renderer, not the fixture.
• The render case requires the shared defs' rows to be byte-identical and on the input face.
• A fourth case pins the marker on hand-written nodes.

Reverse verification used the committed fix at 3a62f4a391. The mutation went through scripts/ablation-replace.mjs: anchor count 1 to 0, blob changed. The restore was proven: blob equals HEAD and git diff HEAD is empty. Putting back the old required-only marker turns 2 of 137 cases red: the render case and the hand-written summary case. The two precondition cases stay green, as designed. The subject resolves to source through a relative import, so no dist/ leg applies.

Gates

At the final head d5d88f55a5, after the second merge:

• pnpm --filter @objectstack/spec exec vitest run --project local --maxWorkers=2: 602 files, 17769 passed, 1 todo.
• check:generated ("All 15 generated artifacts are up to date"), check:docs and check:nul-bytes: exit 0.

At ce1d8ceaf8, before the second merge, which brought only main's commits and one regenerated page:

• pnpm --filter @objectstack/spec typecheck (the build program, tsconfig.scripts.json and the test program): exit 0. The three touched TS files are in the tsconfig.scripts.json program (checked with --listFilesOnly).
• node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --ran: 88 derived, 88 run, 0 NOT-MEASURED, 0 UNRUN, every one exit 0. That includes check:generated, check:docs and check:nul-bytes. This full union was not re-run at d5d88f55a5.
• Lint was narrowed to the 3 touched TS files: eslint --no-inline-config --format json reads 3 files, 0 errors, 0 warnings. The .mdx pages match no lint files glob in eslint.config.mjs. That config enables no type-aware linting (no parserOptions.project), so this diff cannot move a verdict on an untouched file. The repo-wide pnpm lint is left to CI.

Changeset

skip-changeset, measured:

• @objectstack/spec's files[] is dist, json-schema, liveness, prompts, llms.txt, README.md, src/**/*.zod.ts, CHANGELOG.md, api-surface and spec-changes.json.
• This diff touches only packages/spec/scripts/** and content/docs/references/**. The docs site, apps/docs, is private.
• After a build, isAuthorOmittable and carriesDefault match 0 files under those paths. The positive control, lazySchema, matches 240.
• check:generated moved no published artifact.

Acceptance notes

• The two-order harness and the corpus io-face measurement were one-time readings from scratch scripts and are not committed. The committed pin is the two-parent-row block above.
• Open edge, with no instances today: the predicate reads a member's own default. A member spelled as a bare $ref to a defaulted def would carry default only on the def, not on the property node. The corpus reads 0 such members (0 differing lines in either column after the change). Carrier: none.
• The io fallback is per document by design: one transform anywhere moves the whole document to the input projection. After this change that no longer shows on the page. It does still decide which JSON Schema face json-schema/ publishes for that document, and that is out of this card's scope.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

Nothing in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 0 changed package(s)), so this run has no opinion about the docs.

What this run could not see

• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 0 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 0b8239111fe2195a8d6d120568367ee547d96003 → packageMentionDocs.