docs(spec): state what fieldGroups[].collapsed maps to on its own

[os-support-ai]

Part of #19311

Clause-②: no

Why that reading: one .describe() string on an already-deprecated alias. No key is added, removed or re-typed, no accept set moves, the normalizer is untouched, and the public export set is byte-identical. The grade stays patch exactly as measured below.

What the card asked, and what re-measuring found

#19311 is a verification request: its own body says the reading is INHERITED, was not seat-verified, and asks whether it still holds on today's origin/main with a lit control. Both halves were re-measured here rather than inherited.

Half 1 — the spec side

Instrument: git grep -nE over packages/spec/src/**/*.zod.ts, plus ObjectSchema.safeParse run against the package built from this branch. Radius: this repository at eea7ccc3ec (the branch point) for the greps; the built packages/spec/dist for the parse. Dark control: a nonsense token of the same shape (collapsibul) over the same glob returns 0 hits, so the instrument discriminates.

The describes do already name collapsible, and both keys are deprecated in favour of the ADR-0085 collapse enum — so the card's literal claim ("the describe does not mention collapsible") is stale. What is not stale is the gap underneath it: nothing in the published text says what collapsed maps to on its own. Measured, nine inputs on one field group:

authored on the group	collapse after parse
collapsed: true	'collapsed'
collapsed: false	'none'
collapsible: true	'expanded'
collapsible: false	'none'
collapsed: true + collapsible: false	'collapsed' — collapsed outranks
collapsed: true + collapsible: true	'collapsed'
defaultExpanded: false	'collapsed'
neither key (lit control)	'none'
an explicit collapse (lit control)	wins; the aliases are not read

The last two rows are the run's own controls: the default arm fires when nothing is authored, and the alias arm is skipped when collapse is present — so the other seven rows are the normalizer's doing and not an artefact.

collapse: 'collapsed' is described one screen above as collapsible, starts closed. So on this surface collapsed: true alone already implies collapsible — the behaviour was never the gap; the text was. The mapping lives only in the docblock of a non-exported helper, which nothing publishes, while the sibling alias defaultExpanded spelled its own mapping out in its describe and these two did not.

Half 2 — the consumer side

Two radii, measured separately.

This repository. git grep -nE "\.collapsed\b|\.collapsible\b" over packages/*/src/**, excluding packages/spec/src, tests and generated files → 0 hits. Lit control on the same instrument and the same glob: \.visibleWhen\b returns hits in five or more files. Nothing here reads the raw pair; rendering is the sibling repo's.

The pinned sibling. Read at .objectui-sha = 87af769e9a3ee28ace099fdd653d3ebd79fe82e2, which git merge-base --is-ancestor confirms (exit 0, self-proving) is an ancestor of the objectui checkout on this box. Dark control on a nonsense token of the same shape over the same blob: 0 hits.

• packages/plugin-form/src/ObjectForm.tsx:1560 — const isCollapsible = Boolean(section.collapsible) || Boolean(section.collapsed); — the maintainer ruling of 2026-09-18 (letter A: collapsed implies collapsible, read from the declaration) is applied, and the pin carries it.
• packages/plugin-form/src/DrawerForm.tsx:609 and :677 — both arms pass collapsible: section.collapsible alone. The file names objectui#9780 in a comment and declares the residual deliberately fenced.

So the downstream half is partly repaired and partly still open, and the open part is another repo's and another seat's. Nothing about it is touched here.

The change

One describe, on the declared file surface and nothing else:

before:  [DEPRECATED → collapse] Boolean pair with `collapsible`; use the `collapse` enum.
after:   [DEPRECATED → collapse] true → 'collapsed' (collapsible, starts closed) on its own — it
         needs no `collapsible` and outranks `collapsible: false`; false → 'none', or 'expanded'
         beside `collapsible: true`. Use the `collapse` enum.

content/docs/references/data/object.mdx is regenerated from it by the repo's own generator, never by hand.

Reverse verification — the gate can see this text

Run in order on this branch, exit codes captured before any pipe:

1. after the edit and a spec rebuild, pnpm --filter @objectstack/spec check:docs → exit 1, naming content/docs/references/data/object.mdx as out of date. That is the lit control: the gate reads this describe.
2. gen:schema && gen:docs → the two published rows change and nothing else does (the shape is nested under two parents, hence two identical row edits).
3. pnpm --filter @objectstack/spec check:generated → exit 0, all 15 generated artifacts up to date.

Step 1 is what makes step 3 a measurement rather than a silence.

Verification

Measured at 1fae1ecc40, the last commit on this branch.

run	exit
the 101 commands from node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands	0 — each captured before any pipe; six first returned 3 (PREREQUISITE NOT MET, never read as a pass), were cleared by building @objectstack/lint..., @objectstack/client-react, @objectstack/objectql and then the whole workspace, and re-ran at 0
dispatch-gates.mjs --ran reconciliation	0 — 101 derived families accounted for, 101 run, 0 not-measured
the six roster families whose roster sits under a directory this diff touches	0 each — run explicitly rather than read as silent
pnpm --filter @objectstack/spec test	0 — 514 files, 14991 passed, 1 todo
pnpm --filter @objectstack/spec typecheck	0 — includes check:test-typecheck; tsc --listFiles shows the main program carries 0 *.test.ts, which is why that second gate is the one covering them
pnpm --filter @objectstack/spec check:generated	0
pnpm lint (eslint . --no-inline-config, whole repo, not narrowed)	0 — 1m46s

Changeset — measured, not pattern-matched

patch on @objectstack/spec. Decided by grepping the new describe text through each entry of this package's own files[] after a real build:

• positive — the new text is present in 20 files under dist, 11 under json-schema, and in src/data/object.zod.ts, which files[] ships verbatim as src/**/*.zod.ts. It publishes three ways over.
• negative, with a lit leg — the same grep finds are GENERATED — do not hand-edit them in packages/spec/scripts/lib/generated-output.ts and in 0 files across every files[] path. So the instrument separates shipped from unshipped, and the positive above is not an artefact of grepping everything.

skip-changeset would therefore be wrong here.

Hand-written docs corpus — key-name probe

The Docs Drift Check bot listed nothing on this head and says in its own words that an empty list is not a clean bill of health: an emitter-only diff shares no identifier with a page that states the rule by its inputs. So the probe was dropped from the sentence to the narrowest token any page restating this rule must still carry.

Radius: the whole hand-written content/docs corpus — 216 tracked files, generated content/docs/references/** excluded by pathspec. Instrument: git grep -nw per token.

token	hit lines
collapsed	17
collapsible	16
collapse	24
fieldGroups	21
unique lines, deduplicated	72, across 31 pages
dark control collapsable (near-miss spelling)	0 — exit 1
lit control defaultExpanded	1 — exit 0

Not a double zero, so the instrument discriminates.

Reading: nothing is falsified. No hand-written page states the fieldGroups[].collapsible / collapsed mapping at all, so none of them can contradict a describe that now states it. The one page that documents the enum — content/docs/data-modeling/schema-design.mdx:316 — already spells 'collapsed' as collapsible and starts closed, which is exactly what the corrected describe now says. It names only defaultExpanded as the deprecated alias and omits this pair: an omission, not a contradiction, and not edited here. Every single-hit page (18 of them) uses "collapse" in the ordinary English sense of folding two things into one, not as a metadata key.

content/docs/releases/** contributed 14 of the 72 lines across five pages. Release-owned and read-only: none of them states the mapping rule, all are feature-note prose, and none was touched.

Three hits are about the OTHER surface — the form-view sections[] pair (FormSectionSchema, packages/spec/src/ui/view.zod.ts), which this PR does not touch and which has no alias mapping behind it. They are reported, not edited, and routing them is the dispatching seat's:

• content/docs/protocol/objectui/concept.mdx:588-596 — a YAML example captioned "Advanced section (collapsed by default)" that authors collapsed: true on a form section with no collapsible beside it. At the pinned .objectui-sha, the two DrawerForm arms honour that literally.
• content/docs/ui/views.mdx:416-417 — the section key table reads collapsible = "Can section be collapsed", collapsed = "Initially collapsed", silent about the dependency the 2026-09-18 ruling settled.
• content/docs/protocol/objectui/layout-dsl.mdx:354-355, :422, :529, :835-836 — the same pair documented four more times without the dependency. The authored example at :354-355 writes both keys together, so it is safe as written.

Limit of this radius, stated: the probe sees a page that NAMES one of the four tokens. It does not see a page that describes collapse behaviour in prose with no key name at all. Nothing here claims more than the token can carry.

Acceptance notes

Noted, deliberately not ridden along:

• collapsible's describe carries the mirror-image silence. collapsible: true alone parses to collapse: 'expanded' and its describe says only Boolean pair with `collapsed`. Same family, same correction shape; left out because the card names collapsed and the dispatch said the describe and nothing else.
• The @deprecated TSDoc lines above both keys still read "pair with X", the framing that produced the card. They are IDE text, not published-page text, so they are a separate, smaller surface.

A measured finding on a file outside this PR's declared surface is reported to the dispatching seat rather than filed from here.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

1 anchor(s) derived from 1 changed package(s); no hand-written page names any of them, so this run has nothing to list — not a clean bill of health. This check sees only pages that NAME a derived anchor: one that documents this change in prose, or enumerates it in an authoring dialect, names none and stays invisible to it on every run.

What this run could not see

• the SDK route bridge reached 60 of 215 client-bound route-ledger rows — the other 155 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 155: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 100 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• 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 — 136 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 7e1b048a1dbd7142bd6aa2cd9cbcccf7e1c69345 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from cdf09f9d865c0ec496d93bbfd1ec8849aff9065a — the merge of head 1fae1ecc405616715050383da71dc690dd3a707f into base 7e1b048a1dbd7142bd6aa2cd9cbcccf7e1c69345, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin cdf09f9d865c0ec496d93bbfd1ec8849aff9065a && git checkout cdf09f9d865c0ec496d93bbfd1ec8849aff9065a
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 7e1b048a1dbd7142bd6aa2cd9cbcccf7e1c69345 1fae1ecc405616715050383da71dc690dd3a707f && git checkout -B drift-repro 7e1b048a1dbd7142bd6aa2cd9cbcccf7e1c69345 && git merge --no-ff 1fae1ecc405616715050383da71dc690dd3a707f

node scripts/docs-audit/affected-docs.mjs --json 7e1b048a1dbd7142bd6aa2cd9cbcccf7e1c69345

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

[os-support-ai]

Contract review

Served-tier: 79/79 CONTRACT_REVIEW_TIER (seat-measured, 2026-09-22T12:53Z)
Head-sha: 1fae1ecc405616715050383da71dc690dd3a707f

Rendered by an isolated at-tier review subagent on the head above.

① Derived judgments

1. Declaration Clause-②: no — judged CORRECT. The diff's only source change is one string literal inside .describe() at packages/spec/src/data/object.zod.ts:1220. normalizeSemanticRoleAliases (:2818–2843) and the ObjectSchema parse wrappers (:2861, :2864) are untouched; no key is added, removed or re-typed; no export changes (check:api-surface on a full DTS build: unchanged). Neither limb of the clause fires — the accept set is not widened and the public surface is not enlarged. A Contract-text: citation is NOT owed: the rule attaches it to a no that deletes a false rejection, and this diff deletes no rejection. The declaration carries no (widening)/(narrowing) arm, which AGENTS.md permits. Both carriers read no — check-clause2-carriers.mjs --pair 19699 exit 0, governing claim comment and PR body line agreeing.
2. Every claim in the new contract text verified against the built package at head — a 12-input probe through ObjectSchema.safeParse against dist/data/index.js: collapsed:true alone → 'collapsed'; it needs no collapsible (same row); collapsed:true + collapsible:false → 'collapsed' (the ternary at :2831 tests collapsed === true first, so "outranks" is literally the code order); collapsed:false alone, +collapsible:false, +defaultExpanded:false all → 'none'; collapsed:false + collapsible:true → 'expanded'; the parenthetical "(collapsible, starts closed)" is the enum's own describe at :1209 verbatim. Lit controls in the same run: neither key → 'none' (default arm), explicit collapse:'expanded' beside collapsed:true → 'expanded' (aliases unread). No published statement is false. The pinned objectui (.objectui-sha 87af769e) derives the same precedence at ObjectGroupInspector.tsx:74, so the text contradicts no downstream reader either.
3. Reach of the claim — a precision limit that predates the PR, recorded not failed. The mapping runs only inside ObjectSchema.parse/safeParse (the sync wrappers). Measured on the same build: standalone ObjectFieldGroupSchema.safeParse({key, label, collapsed:true}) → collapse:'none' with collapsed:true preserved; parseAsync/safeParseAsync are not wrapped. The describe names no entry point — but neither does the sibling defaultExpanded describe it mirrors (:1216), which carries the identical conditionality. No standalone or async consumer exists: in-repo the group schema is reached only via ObjectSchema.fieldGroups (:2022); at the objectui pin it is imported as a type only (object-fields-io.ts:334). Judged consistent with the established describe precision on this schema.
4. collapsible's describe left uncorrected (:1218) — defensible, and a finding. Not a contradiction: the corrected collapsed row now says "needs no collapsible" and covers collapsible:true beside collapsed:false. What stays unstated is collapsible:true alone → 'expanded' and collapsible:false alone → 'none' — a silence that predates the PR, reported by the dev in the acceptance notes and within the dispatch's "add that clause" for collapsed. Shipping the pair half-described is a sibling-card follow-up, ⛔ not grounds to hold correct text back.
5. Public face: the describe is published contract text — shipped verbatim in src/data/object.zod.ts (files[] entry src/**/*.zod.ts), in 20 dist files and 11 json-schema files including json-schema/data/ObjectFieldGroup.json and json-schema/data/Object.json, and in the regenerated content/docs/references/data/object.mdx. That is why this review is owed; it enlarges nothing.

② Semver level

Declared patch on @objectstack/spec (.changeset/19311-collapsed-alias-alone-mapping.md). Measured, not pattern-matched: a real build in an isolated worktree at head (gen:schema 1546 schemas, gen:openapi, tsup JS, tsup DTS — each exit 0), then pnpm pack → objectstack-spec-17.4.0.tgz, 1902 entries.

• Positive controls: package/src/data/object.zod.ts present, package/dist/index.js present, 1538 package/json-schema/ entries; the new text found in 1 src + 20 dist + 11 json-schema files INSIDE the tarball; the old text 0.
• Negative controls: package/scripts/build-docs.ts absent, zero *.test.ts, src/data/field-group-layout.ts (a non-.zod.ts src file) absent; the generator banner "are GENERATED — do not hand-edit them" 0 in the tarball against 1 in the unshipped scripts/lib/generated-output.ts. The instrument separates shipped from unshipped.

It publishes, so a changeset is owed and skip-changeset would be a false declaration. Description-only, check:api-surface unchanged, and a no declaration ⇒ patch is the correct level; the at-least-minor rule binds only a yes. Agreed.

Check conclusions are read from the head's check-runs, not locally: Check Changeset newest run by that name (106687408973, 09:20:30Z) is success; the earlier failure (106686491479, 09:17:30Z) ran against the pre-edit body and is superseded by name.

③ Boundary flags

• Manual floor: none crossed — no ADR, no docs/adr/**, no content/docs/releases/**, no CHANGELOG edit; no security or permission surface, no runtime behaviour.
• Regeneration verified from the tree: pnpm --filter @objectstack/spec check:docs on the head worktree after a real build → exit 0, 225 generated files in sync, worktree clean afterwards. The two changed rows in object.mdx (:314 and :670 — the shape nests under two parents) are generator output, not hand edits. Regen-provenance: not owed: one commit, no regen-only head move.
• Dev flags and open_questions: (1) card/PR surface mismatch — settled by the seat as Part of, outside this question; the delivered change is sound on its own terms. (2) REST-proxy channel deviation — process, not contract; escalated to the seat as the report records. (3) the collapsible mirror silence and the @deprecated TSDoc "pair with X" framing — answered in ① item 4: leave, file a sibling card. (4) not raised by the dev, raised by the review: the mapping is conditional on the ObjectSchema sync parse entry (① item 3) — recorded, no change requested.
• Construction tier — recorded, ⛔ not a FAIL. The claim's container line reads model: claude-opus-5 while asserting construction "runs at CONTRACT_REVIEW_TIER"; on origin/main that constant has read claude-fable-5-1 since 372931e512 (pm(tooling): the contract-review tier is fable — revert the opus constant and the retired-word list #19684, 2026-09-22T08:04Z), which is before the claim was written (2026-09-22T08:22Z). Construction was therefore at TIER_DEFAULT, and this at-tier review is the designed compensation for exactly that — so not a FAIL. The claim's self-description was simply stale when written; the seat acknowledged it in an earlier comment on this PR.
• CI on head, newest run per check name: all success or skipped by design (Auto Label, Check PR Size, Console Pin Gate, Packed-tarball smoke); Type Check · source gates (check:generated reconcile) and Type Check · consumer gates (check:api-surface) both success.

Implemented-by: claude/issue-19311-collapsed-implies-collapsible
Reviewed-by: session_013RDBh5DqXd2xnLwvHLgLFr

VERDICT: PASS

---

Tier control — measured by the seat, not reported by the reviewer

The reviewer self-reported 16/16 by counting its own turns, and said plainly that a self-count is not a reading. It is right: the governing control is the transcript's per-request harness model stamp, and get_session is ⛔ not admissible as corroboration. So the seat counted the transcript itself:

• 79 assistant requests, 79 stamped claude-fable-5-1 — every per-request "message":{"model":…}, no exceptions.
• 93/93 counting every model field in the transcript, per-request stamps and advisorModel alike.
• Dark control: 0. Filtering every "model"/"advisorModel" occurrence for anything other than claude-fable-5-1 returns empty — no other model name appears anywhere in the transcript.
• The four keyword hits for fallback/overload were read in context: three are tool-schema prose, one is the reviewer's own sentence about not being able to observe a fallback from inside. ⛔ None is a fallback notice.
• CONTRACT_REVIEW_TIER re-read at source (origin/main:scripts/pm/dispatch-gates.mjs) = claude-fable-5-1, matching the stamps.

The reviewer was served at tier for every request it made.

Two carried readings the seat is recording rather than burying

• Carried, not re-measured (by the rule that derived gate families are read from CI, never re-run by the reviewer): the dev's pnpm --filter @objectstack/spec test (14991 passed) and whole-repo pnpm lint. Test Core 1–6 and Lint & Repo Gates are green on this head.
• The reviewer's first local check:generated flagged api-surface/ — because that build had no .d.ts yet, which the tool itself says. After the DTS pass check:api-surface reads clean, exit 0, worktree clean. The stale flag was the missing-DTS artefact, ⛔ not the PR.
• ⛔ Could not measure: the merge-base "before" behaviour by execution — a structural argument stands in its place (the diff touches only a string literal inside .describe(), which cannot alter parsing); and the objectui renderer beyond git grep at the pin (no build or run of it).

Seat follow-ups this record does not discharge

1. collapsible's describe silence (① item 4) — a sibling card, ⛔ not owed on this PR.
2. The ObjectSchema-sync-entry precision limit (① item 3) applies to all three aliases alike, not just collapsed — pre-existing, recorded.
3. #19311 is NOT satisfied by this PR. Its card names packages/spec/src/ui/view.zod.ts:3315–3316, where collapsible and collapsed both sit with no .describe() at all — a different schema from the packages/spec/src/data/object.zod.ts row this PR corrects. The seat re-dispatches finding(spec): the sections[].collapsed describe owes an 「implies collapsible」 clause #19311 at its own file; this PR closes as Part of, not Fixes.
4. One shared side effect to clean up: the reviewer's git worktree add registered a worktree in the shared repo's list. Removable with git worktree remove; left in place as evidence for now.

---

Generated by Claude Code