spec(ui): widen `element:text.variant` to the published nine — release 1 of 2 for the objectui#7450 convergence, additive only

[os-warren]

Filed by the domain:spec@objectui PM seat (session session_01Jmxdo7bmeqCQHLSfmLVX9w) routing objectui#7450, whose ruling cannot be implemented in objectui. ⛔ Not claiming. Grading is the triage seat's.

Maintainer decision, 2026-09-09: option B — split across two releases. This card is release 1, and it is additive only: nothing is refused here.

Why this is a spec card and not an objectui one

objectui#7450's ruling (director batch #71, 2026-09-07, maintainer 「其他同意」) is: converge element:text on the published nine (h1–h6, body, caption, overline), with heading / subheading becoming named refusals carrying migration hints.

⚠️ The ruling's premise was false, and the correction is what routes it here. The card, its census and its triage all state that element:text's vocabulary was never declared, so nothing could refuse a wrong value. Measured, it is declared — here, at packages/spec/src/ui/component.zod.ts:1819:

variant: z.enum(['heading','subheading','body','caption']).optional().default('body')

On the installed 17.3.0 pin, ElementTextPropsSchema REFUSES h1–h6 and overline with invalid_value, and objectui's own sdui-parser validateTree already raises invalid-enum at severity ERROR for element:text + variant: h1.

⇒ The accurate statement is "the renderer swallows what the authoring gate already refuses", ⛔ not "refused by nothing".

⇒ Declaring the nine in objectui is the consumer-side widening AGENTS.md #0.1 bans, and objectui's own per-PR gate catches it. Verified independently: apps/console/src/__tests__/registry-inputs-spec-parity.test.ts emits the contract refuses the declared member(s) … at :1539 and :1800, and element:text is in its covered set (:536). Ablated end to end by the implementing seat: swapping objectui's registry inputs enum to the nine takes that gate 198 passed → 1 failed | 197 passed, naming all seven refused members.

The one-line in-repo migration is blocked by the same wall: objectui's apps/console/src/preview-samples.ts authors variant: 'subheading', which is spec-legal today, while h3 would be spec-illegal.

What release 1 does

Widen element:text.variant to the nine published values, so the enum accepts h1–h6, body, caption, overline and still accepts heading / subheading.

⛔ Nothing is retired here. No refusal, no deprecation error, no removal. This release exists so objectui can converge its renderer and its five faces on a released pin before any spelling stops working.

⚠️ The defaulting must be decided, not inherited. The current declaration carries .optional().default('body'), so a parsed element:text document materialises variant: 'body'. That interacts with objectui#6942's ruling, which deliberately does not synthesise body for an absent variant on ui:text — protecting ~690 unannotated corpus nodes. ⛔ Widening the enum must not silently change what absence means on either side; state explicitly what happens to .default('body') and why.

Sequence, so nothing is dispatched out of order

1. This card — spec widens to the nine. Additive. Clause-②: yes (a published accept set grows).
2. objectui converges on the released 17.x pin: the renderer, the five faces (elements.tsx :70 class map, :78 inline union, :85 tag map, :111 registry inputs enum, plus block-config.ts's inspector options), the two i18n rows, and the one-line preview-samples.ts migration.
3. Release 2 — heading / subheading become named refusals with migration hints, once out-of-repo authors have had a window. ⚠️ That step is blocked on the value-level retirement mechanism, which does not exist yet — filed separately, see below.

⇒ objectui#7450 closes after step 2; step 3 is its own card.

⛔ Blocked-by, and it is real

The ruling's "named refusals carrying migration hints" has no mechanism to land on. retiredKey() / ADR-0087 D2 retire a key; a sweep of packages/spec/src/shared/ surfaced no value-level equivalent. The maintainer chose the generic helper (2026-09-09), filed as its own card — release 2 waits on it. Release 1 (this card) does not.

Appetite

⛔ Falls off the back: retiring anything; changing element:text's renderer (that is objectui's, on the released pin); the ui:text side; objectui#6942's absence semantics.

Refs: objectui#7450 (the ruling and the falsification, comment 5599277303) · objectui#6942 · objectstack#12708 (the batch #70/#71 ledger) · objectui PR #8795 (the resolution pin that landed instead)

[os-litant]

Triage: domain:spec unchanged; type Feature, priority:p2, pm:queue. Half-state healed — the card carried a lane but no pm-state.

Dispatchable because it is already ruled, ⛔ not because widening is cheap

This enlarges a published spec enum's accepted set, which is a maintainer floor and would otherwise go straight to the decision box. It does not, for one reason only, and I am citing it rather than asserting it:

Maintainer decision, 2026-09-09: option B — split across two releases.

on top of objectui#7450's ruling (director batch #71, 2026-09-07, maintainer 「其他同意」). ⇒ The shape, the split and the direction are all decided. This card is release 1: additive only, nothing is refused here.

Feature by the type rule — it enlarges the accepted set. ⛔ That classification does not re-open the decision-box question; a ruled feature is work.

⭐ The correction the card carries is the reason it is a spec card at all

The ruling's premise was that element:text's vocabulary was never declared, so nothing could refuse a wrong value. Measured, that is false — packages/spec/src/ui/component.zod.ts:1819 declares z.enum(['heading','subheading','body','caption']), and on the 17.3.0 pin ElementTextPropsSchema refuses h1–h6 and overline with invalid_value, while objectui's sdui-parser validateTree already raises invalid-enum at severity ERROR.

⇒ The accurate statement is 「the renderer swallows what the authoring gate already refuses」. ⛔ A dev must not restate the ruling's original premise in a changeset or a docblock — it is known false, and the card says so.

Sequencing and batching

⚠️ Release 2 is #17109's dependent, not this card's. The card is explicit: release 1 does not depend on the value-level retirement mechanism; release 2 does. ⇒ ⛔ Do not add a Blocked-by: here and ⛔ do not hold this behind #17109.

⚠️ For batch selection: this and #17109 are both packages/spec with disjoint file faces (ui/component.zod.ts here, a new helper under shared/ there). Independence is judged on the file face, so they may run concurrently — but they share one changeset area and one queue slot.

_{Triage seat · session_017VGfRocA8VjczSe84fgjY3 · R+168 · 2026-09-10T16:10Z (timestamp taken in the same tool call that posts) · comment from the triage seat}

---

Generated by Claude Code

[os-elon-musk]

Claim: PM loop round 8 — taken 2026-09-18T1019Z.

Seat: domain:spec#3
Branch: claude/issue-17108-text-variant-published-nine
Clause-②: yes
Session: session_019srGWGCBBCBHqcDoRZpQRh

Why this card, now

Ruled and additive-only, with the human floor already cleared by an actual decision rather than by this seat's judgement: maintainer decision 2026-09-09, option B — split across two releases, and this card is release 1. The card's own body states that release 1 does NOT wait on the value-level retirement mechanism; only release 2 does, and that is a separate card correctly blocked on it.

Unclaimed on every reading at 2026-09-18T1018Z: no assignee, no Claim: comment (its one comment is the triage grading), and no branch on the remote. Untouched since 2026-09-10 — eight days.

⚠️ A widening of a published vocabulary normally sits on the manual floor, so it is worth stating why this one is dispatchable rather than a decision card: the widening is the maintainer's decision, quoted in the card body with its date and option letter. ⛔ This seat did not judge the widening acceptable; it read that the judgement had already been made.

Declared file surface, for other seats' in-flight intersection checks

• packages/spec/src/ui/** — the element:text variant vocabulary (exact landing point to be established by the implementer from evidence, ⛔ not assumed from this claim).
• the block-config inspector options the card names, the two i18n rows, and the one-line preview-samples.ts migration.
• .changeset/ — one entry.
• Generated artefacts that follow from a published-vocabulary change: packages/spec/authorable-surface/**, api-surface-declarations/**, content/docs/references/** and their siblings.

⚠️ Known overlap, handled by the runbook rather than by hand: api-surface-declarations/** and content/docs/references/** are both currently touched by open PR #18985, and both are on the merge=os-regen register — so the merge driver recomputes them instead of interleaving text. Later lander regenerates. ⛔ Neither is a reason to hand-resolve.

⛔ Not in surface: content/docs/releases/**; packages/spec/src/shared/expression.zod.ts and src/data/field.zod.ts (held by #18985); scripts/lib/refinement-projection.ts, lib/dropped-refinements.ts, scripts/build-schemas.ts and dropped-refinements.baseline.json (held by #18670's third arm).

What the card puts out of scope, carried verbatim so it is not re-litigated

⛔ Falls off the back: retiring anything; changing element:text's renderer (that is objectui's, on the released pin); the ui:text side; objectui#6942's absence semantics. Release 2 — heading / subheading becoming named refusals — is a different card and is genuinely blocked on a value-level retirement mechanism that does not exist yet.

⚠️ The card also records that the original ruling's premise was false (element:text's vocabulary was never declared, so nothing could refuse a wrong value) and that the correction is what routed it here. The implementer reads that correction as part of the card, ⛔ not as an invitation to re-open the ruling.

Clause-② is yes (a published artefact widens), so needs:contract-review is hung on this card in the same label write as this claim, and the delivering PR gets an isolated at-tier review before any carrier is cleared.

---

Generated by Claude Code

[os-elon-musk]

os-dev-report

{
  "issue": 17108,
  "status": "done",
  "branch": "claude/issue-17108-text-variant-published-nine",
  "head_sha": "3151b9467bd0be1e78a086a0fc820e8599894499",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/19019",
  "session": "session_019srGWGCBBCBHqcDoRZpQRh",
  "premise_still_valid": true,
  "summary": "element:text.variant now declares eleven members — the published nine (h1-h6, body, caption, overline) plus heading and subheading, which stay accepted. Seven values newly accepted, nothing refused that was accepted before, and .optional().default('body') kept deliberately so absence still materialises 'body'. The card's own premise was re-measured and HELD: the vocabulary IS declared, at packages/spec/src/ui/component.zod.ts, and h1-h6 plus overline were refused there with invalid_value before this change. Release 2 (named refusals with migration hints) and the value-level retirement mechanism are untouched.",
  "landing_points": {
    "how_established": "git grep for the vocabulary's spellings across the tree, plus check:generated naming exactly which generated artefacts went stale; no path was taken from the dispatch or the claim as given.",
    "packages/spec/src/ui/component.zod.ts": "the z.enum on ElementTextPropsSchema.variant plus a docblock recording the ruling, the two-release split and the defaulting decision — the only source declaration of this vocabulary in the tree",
    "packages/spec/src/ui/component.test.ts": "the variant pins rewritten as a per-value measurement with a lit control and an absence pin",
    "packages/spec/api-surface-declarations/ui.txt": "generated; seven members added on ElementTextPropsSchema and on ComponentPropsMap['element:text']",
    "content/docs/references/ui/component.mdx": "generated; the property table's Enum cell",
    ".changeset/17108-element-text-variant-published-nine.md": "@objectstack/spec minor, carrying 'Clause-②: yes (widening)'"
  },
  "accept_set_measurement": {
    "door_1_zod_schema": "ElementTextPropsSchema.safeParse against the rebuilt dist. BEFORE (at merge base f347c793e): heading/subheading/body/caption accept; h1,h2,h3,h4,h5,h6,overline REFUSE with invalid_value; absent accepts and materialises 'body'. AFTER: 11 of 11 accept; absent accepts and materialises 'body' (unchanged).",
    "lit_control_door_1": "small, h7, Heading and the empty string each still REFUSE with invalid_value at path 'variant' — so the zero-refusal reading over the eleven is a reading and not a schema that stopped judging variant.",
    "door_2_metadata_authoring_rule": "validateComponentProps (packages/lint, reads ComponentPropsMap from @objectstack/spec/ui — the door definePage() / os validate / os build go through): all eleven CLEAN.",
    "lit_control_door_2": "small and h7 each report component-props-invalid, and the diagnostic enumerates all eleven members — which is also the evidence the rule read the rebuilt spec rather than a cache.",
    "door_3_typescript": "Two legs against the rebuilt .d.ts. Leg 1: variant:'h1' type-checks and variant:'small' is a type error (its ts-expect-error consumed) — tsc --noEmit exit 0. Leg 2 (lit control): the same h1 assignment under a ts-expect-error must be reported UNUSED — tsc exit 2, TS2578 Unused ts-expect-error directive. Against the pre-change .d.ts leg 2 would have compiled clean, so leg 1's green is about the rebuilt declarations, not a cache. Both probe files were proved on disk, then removed; tree clean.",
    "door_4_jsx_registry_manifest": "NOT MOVED BY THIS CARD, and measured rather than assumed. validateJsxPages validates against the tracked sdui.manifest.json (objectui's registry declaration, not the spec's). On this branch: h1, h6 and overline each still produce invalid-enum at severity ERROR naming the old four; heading and body are CLEAN and small is refused, so the check is live and closed rather than off. That door is objectui's registry inputs enum (the card's step 2, elements.tsx:111) and converges on a released pin. Equally, on the released pin an element:text node with variant h1 renders through VARIANT_CLASS[variant] ?? VARIANT_CLASS.body, i.e. body-styled, until step 2 lands. This PR therefore does NOT claim the nine render or pass every authoring gate — only that the spec contract accepts them, which is what release 1 is."
  },
  "defaulting_decision": "KEPT .optional().default('body'), stated rather than inherited, as the card requires. An element:text node parsed with no variant still materialises 'body', byte-identically. Absence is the one thing a widening must not move. The ui:text side deliberately does not synthesise 'body' for an absent variant (objectui#6942); that asymmetry is pre-existing and is left where it was. Removing the default would refuse nothing at the door but would change what every downstream reader sees for an absent key — a silent behaviour change wearing an additive changeset.",
  "tests": "107 of 107 derived gate families run, every one exit 0, on head 3151b9467. Derivation: node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands from the merge base, re-derived after the origin/main merge — identical 107-command set both times. Reconciliation: dispatch-gates --ran reports '107 derived famil(ies) accounted for — 107 run, 0 NOT-MEASURED (a DERIVED zero — all 107 recorded an exit code and none of them is 3)', exit 0. Every exit code captured with 'cmd > file 2>&1; EXIT=$?', never through a pipe. Seven families first returned PREREQUISITE NOT MET (six exit 3 plus check:skill-examples' exit-1 refusal of the same class) on an unbuilt workspace; those were recorded as NOT MEASURED, not as findings, and all seven were re-run to exit 0 after 'turbo run build' over the workspace — they are inside the 107 above. Package level: pnpm --filter @objectstack/spec test = 489 files / 14221 tests passed; the 13 new element:text assertions were confirmed to have actually run under --reporter=verbose. turbo run typecheck over the repo = 143/143 tasks successful (turbo ls --affected reports all 81 packages affected, so no narrowing was claimable and the repo-wide run is the measurement). pnpm lint (eslint . --no-inline-config) = exit 0, whole repo, no narrowing claimed. pnpm --filter @objectstack/spec check:generated = all 16 generated artefacts up to date after the merge; check:api-surface reports nothing removed or narrowed. Reverse verification: the door-3 two-leg tsc pair above (0 / 2 with TS2578) is the proof the rebuilt .d.ts is what was read; no permanent test file was left behind.",
  "merge_handling": "origin/main moved 2 commits during the run and was merged through 'bash scripts/pm/os-regen-merge.sh' — no rebase, no force-push, no gen:schema in MERGE state, no hand-resolution of any merge=os-regen path. The runbook kept the branch's bytes for content/docs/references/ui/component.mdx and packages/spec/api-surface-declarations/ui.txt (main had not moved them), and step 4's regeneration found nothing stale. Branch delta against origin/main is exactly the five intended files; main's incoming bytes (packages/spec/liveness/sharing_rule.json, the plugin-hono-server change, both incoming changesets) are byte-identical to origin/main in this tree. PR #18985's overlap never materialised: it has not landed, so neither api-surface-declarations/** nor content/docs/references/** carried anything of its from main.",
  "contract_review_carrier": "READ ONLY, not touched in either direction, per dispatch. node scripts/pm/check-clause2-carriers.mjs --pair 19019 exits 4 and reports row C1: needs:contract-review is on card #17108 and NOT on PR #19019. The card's claim declares 'Clause-②: yes'; the PR body declares 'Clause-②: yes (widening)'. Hanging the PR-side carrier is the seat's act; this run performed no label write touching it.",
  "mcp_calls": "0 — no MCP GitHub tool was called, read or write. Every GitHub read and write went through the REST proxy with curl and GITHUB_TOKEN.",
  "api_writes": "3 — POST /repos/objectstack-ai/objectstack/pulls (draft PR #19019); POST /repos/objectstack-ai/objectstack/issues/19019/labels (additive, domain:spec + protocol:ui, read back: nothing stripped, automation's documentation/tests/tooling/size-m present alongside); POST /repos/objectstack-ai/objectstack/issues/17108/comments (this report). Zero PATCH: the PR body was written once, at creation, and read back byte-identical with exactly one footer. Four git pushes, which are not REST writes.",
  "deviations_declared": [
    "None silent. (1) No label was written that touches needs:contract-review, in either direction — dispatch instruction, and the reading is recorded above instead. (2) Commit trailers are the model-free pair (Claude-Session + Co-authored-by: Claude) because AGENTS.md and check:commit-card-trailers refuse a model identifier there; a harness reminder asked for a trailer naming a model, and the repo's rule wins. check:commit-card-trailers passed on every push. (3) No narrowing of any repo-level scan was claimed: pnpm lint and turbo run typecheck were both run over the whole repo."
  ],
  "premises_that_measured_false": [
    "DISPATCH PREMISE, FALSE: 'The card also names the concrete pieces release 1 carries: the block-config inspector options, two i18n rows, and a one-line preview-samples.ts migration.' The card lists all three under step 2 — 'objectui converges on the released 17.x pin' — not under 'What release 1 does', and the card's appetite puts element:text's renderer out of scope. Measured: git ls-files finds no block-config, no preview-samples and no elements.tsx anywhere in objectstack; all three are objectui files. Nothing was authored for them. The same three appear in the claim comment's declared file surface, which is wrong in the same way.",
    "CARD PREMISE, HELD (re-measured, not assumed): the vocabulary IS declared and DID refuse. At merge base f347c793e, ElementTextPropsSchema.safeParse refused h1-h6 and overline with invalid_value. So the ruling's original premise — 'never declared, so nothing could refuse a wrong value' — is false exactly as the card and the triage say, and the docblock and changeset state the accurate version ('the renderer swallows what the authoring gate already refuses') rather than restating the false one."
  ],
  "open_questions": [],
  "out_of_scope_findings": [
    "noted, not filed: five in-repo nodes author variant 'subheading' — packages/platform-objects/src/pages/sys-user.page.ts (four) and examples/app-showcase/src/ui/pages/page-variables.page.ts (one). All five are legal today and stay legal through release 1; they are release 2's migration surface. Carrier: the release 2 card.",
    "noted, not filed: after release 1 lands and before objectui's step 2, an author can write variant h1 through the metadata door, have it accepted, and see it rendered as body on the released pin — while the JSX door still refuses it with invalid-enum. This is the declared-but-not-delivered shape AGENTS.md Prime Directive 10's corollary names, but it is the ruled, deliberate consequence of option B and is already sequenced: carrier objectui#7450 step 2. Dedupe words if the seat disagrees and wants it filed: element:text variant renderer window, sdui manifest registry inputs enum, invalid-enum validateJsxPages, published nine convergence release 1.",
    "noted, not filed: sdui.manifest.json still declares the old four for element:text, and that is correct rather than stale — it is objectui's registry dump, sha-pinned to .objectui-sha, converging when the pin moves in step 2. check:react-declaration-parity compares prop KEYS and never enum members, so its green here is not agreement about the vocabulary and must not be read as one. Carrier: none needed; recorded so a later reader does not 'repair' the manifest."
  ]
}

---

Generated by Claude Code

[os-elon-musk]

Correction to the declared file surface in claim comment 5728626724 — that declaration was wrong, and it is the kind of wrong other seats act on.

That claim declared this card's objectstack file surface as including the block-config inspector options, two i18n rows and a one-line preview-samples.ts migration. None of those three exists in this repository. Measured on this checkout with a lit control: block-config 0 tracked files, preview-samples 0, elements.tsx 0, against control packages/spec/src/ui/component.zod.ts = 1. All three are objectui files.

The error came from me, not the dev: the card lists those three under step 2 ("objectui converges on the released 17.x pin"), not under "What release 1 does", and the card's appetite puts element:text's renderer out of scope. I folded step 2's inventory into release 1's file surface when writing the dispatch, and then carried the same mistake into the claim. The dev measured it false and refused to author anything for them, which is the correct outcome.

Why this is worth a correction rather than a shrug: a claim comment's declared file surface is the artefact sibling seats intersect against when they check for in-flight collisions. A declaration naming paths that do not exist here cannot collide with anything, so it silently degrades that check rather than tripping it.

The actual objectstack file surface of release 1, from the delivered branch:

• packages/spec/src/ui/component.zod.ts — the z.enum on ElementTextPropsSchema.variant plus its docblock
• packages/spec/src/ui/component.test.ts — the variant pins
• packages/spec/api-surface-declarations/ui.txt — generated
• content/docs/references/ui/component.mdx — generated
• .changeset/17108-element-text-variant-published-nine.md

⛔ Not a second Claim: — the claim stands, its file-surface line is superseded by this comment. Seat: domain:spec#3, 2026-09-18T11:59Z.

---

Generated by Claude Code