feat(spec): retire the themes carrier key and ThemeSchema — app.branding is the one colour surface (#10485, ADR-0049)

[os-elon]

Fixes#10485

What this is

ADR-0049 enforce-or-remove retirement of the defineStack({ themes }) carrier key and the ThemeSchema authoring surface, per the maintainer ruling recorded on the issue (2026-08-21, verbatim, untranslated):

B：退役授权面 — 收掉 themes 载体键与 schema，app.branding 留作唯一颜色面；objectui 引擎代码与单测保留。

The measured defect: authored themes were parsed strictly, ingested and stored — and then read by nothing. No framework package consumed .themes or stored theme items, theme was never a registered metadata type, no first-party app mounted the spec-aware provider, and nothing selected an active theme. Every gate was green and the console never changed. Clause-②: this PR removes previously-accepted themes declarations from the acceptance set (contract-review tier; not queued by the implementing seat).

Removal shape (per the spec-property-retirement playbook)

• Carrier: ObjectStackDefinitionSchema is a strictObject (An unknown top-level stack key is named but still not rejected — and the diagnostic is not a warning, so objectstack validate --strict cannot catch it either (17.0.0 GA) #8687) and the stack root is not a walked def (verified: no :themes row exists anywhere in the authorable-surface baseline), so the route is strict delete + guidance entry, not a retiredKey() tombstone. The unknown-key rejection carries the prescription: removal citation (defineStack({ themes }) is parsed, ingested and never applied — the last hop from a stored theme item to the theme engine does not exist #10485, ADR-0049), why it was inert, and the app.branding.primaryColor/accentColor replacement. No rename suggestion (finding-7 discipline).
• Schemas: ui/theme.zod.ts deleted whole — ThemeSchema, ColorPaletteSchema, TypographySchema, BorderRadiusSchema, ShadowSchema, ThemeModeSchema, defineTheme, and the inferred types. Orphaned value schemas leave with their one consumer (refactor(spec)!: remove the plugin sandboxing / integrity / approval config that never existed (#3896 follow-up) #3950).
• ADR-0087 registration: six retired-def entries (ui/Theme, ui/ThemeMode, ui/ColorPalette, ui/Typography, ui/BorderRadius, ui/Shadow) + the D3 semantic entry stack-themes-carrier-retired, registered under protocol 18 (launch-window convention — v17.0.0 was cut; the additionalTypes on MetadataPluginConfig is authorable, documented as THE way a plugin declares a metadata type, and has no reader — a plugin cannot declare a kind at all #8586/[finding] The ApiKey reference table documents better-auth's apiKey-plugin schema — a plugin this platform does not load and a shape sys_api_key does not have #8715 precedent). Semantic rather than a D2 conversion, on the D2 lossless-only scope guard: a stack may declare N themes and M apps, so which palette entry becomes which app's branding.primaryColor is a judgment a transform cannot make; auto-deleting the whole authored artifact would silently discard salvageable content. (Secondary, recorded in the entry file: a full-carrier stripKeys conversion also cannot coexist with the published theme-inert-token-scales-removed (主题引擎发出的 9 组 CSS 变量零消费方(--font-size-* / --z-* / --duration-* …):ADR-0049 该判去留 #5021) fixture under the fixture-disjointness replay contract — that fixture necessarily authors themes.)
• Meta door: the themes: 'theme' fold left PLURAL_TO_SINGULAR, so the regenerated URL-spelling contract drops theme and PUT /meta/theme/:name now earns the meta-unknown-type-namespace: a /meta type name that is not a plural of anything still mints a namespace — PUT /meta/fieldz/x answers 200 #8421 unrecognised-type refusal (ADR-0112 envelope, nothing stored) — not a regression to the pre-theme and analytics_cube have strict stack schemas but no UNREGISTERED_KIND_SCHEMAS binding — PUT /meta/theme/:name still accepts any JSON (the two doors #6245 left open) #10194 store-anything branch. The UNREGISTERED_KIND_SCHEMAS.theme binding is removed with it. Legacy stored theme rows: reads answer, DELETE works (stored-namespace exemption), applyConversionsToStoredItem passes them through unchanged.
• Ingest: ARTIFACT_FIELD_TO_TYPE.themes row removed (packages/metadata/src/plugin.ts).
• Retained, per the ruling: objectui's ThemeEngine/ThemeContext and their unit tests (objectui untouched); app.branding end to end.

Pin tests

• stack-top-level-strict.test.ts — a stack declaring themes (a body that parsed green on 17.0) is refused at the key with unrecognized_keys at the root path, message carrying #10485 + app.branding + primaryColor, and no "Did you mean" rename; positive control: the prescribed app.branding replacement parses green; no theme export survives on ./ui (with anti-vacuity probe).
• protocol.unrecognised-meta-type.test.ts — PUT /meta/theme refused with { code: 'INVALID_REQUEST', status: 400 } and zero rows stored; the ACCEPTED-side specimen for "URL-map-only plugin kind" moved theme → webhook (fixture triage: the class survives, the specimen retired).
• metadata-url-spelling.test.ts — theme/themes refused by name; the five surviving plugin kinds pinned by name.
• protocol.meta-types-mint-door-agreement.test.ts — theme reclassified from class 2 (url-map-only, creatable) to class 3 (withdrawn: advertised false, mint refused), with webhook taking the end-to-end write slot.

Docs

content/docs/ui/theming.mdx never shipped (withheld from PR #10483 per the correction on the issue) — nothing to delete or redirect. This PR makes app.branding the one documented colour surface: widget-contract.mdx's Theme section now teaches app.branding (and the still-true token facts — bare-HSL-triple values, base-stylesheet-owned shadcn token set — were salvaged into react-pages.mdx, the optional half of the correction). Getting-started/ui index prose scrubbed; references/ui/theme.mdx deleted by gen:docs.

skills/** touch — line readouts (clause-mandated)

file	before	after
skills/objectstack-platform/SKILL.md	1286	1286 (one inline key name removed; no line delta)
skills/objectstack-ui/references/_index.md (generated by gen:skill-refs)	57	56
whole package skills/objectstack-platform (all .md)	2634	2634
whole package skills/objectstack-ui (all .md)	2297	2296

Net shrink; no expansion. ⚠️skills/** is a governed surface (Prime Directive #14): human merge only — do not queue, arm, or flip out of draft.

File-surface note (declared expansion over the claim comment)

The claimed surface named stack.zod.ts, theme.zod.ts + ui barrel, the ingest row, ADR-0087 registry, changeset, pin tests and docs pointers. The retirement's measured consumer sweep additionally required: shared/metadata-collection.zod.ts (map rows), kernel/metadata-type-schemas.ts (door binding), meta-spelling/* (contract prose + regenerated data), cli stats/explain rows, examples/app-showcase (config + theme sources + coverage/tour prose), scripts/check-stack-collection-maps.mjs (waiver rows in both directions), four metadata-protocol/objectql/rest/runtime protocol-test retriages, qa/downstream-contract fixture row, type-alias-convention.pin.test.ts (Iso700–704 + count 839→834), PROTOCOL_MAP.md, the strictness-ledger row (converted to a retirement paragraph, the notification.zod.ts precedent), skills/objectstack-platform/SKILL.md, and the generated baselines (authorable-surface −57 rows / manifest −6 defs / api-surface / export-origins / spec-changes / upgrade-guide / strictness-ledger counts / meta-url-spelling / reference docs / skill refs). All are the same removal; no new verification surface. packages/spec/src/contracts/metadata-service.ts (H17 trigger of hold #8722) is not touched.

Out of scope, filed

• Plugin-manifest contributes.themes declares a theme-contribution channel nothing reads — same declared-but-unenforced shape as the retired stack themes carrier #10627 — plugin-manifest contributes.themes declares a theme-contribution channel nothing reads (separate declared surface, same ADR-0049 shape).
• objectui ThemeComponentSchema dead surface — separate card per the ruling (objectui repo).

Verification

Consumer-suite readouts below were measured at 2db934d61; origin/main was then merged (PRs #10643/#10644 — ui/i18n.zod.ts / data/object.zod.ts, verified disjoint from this diff: git diff origin/main...HEAD on those two paths is empty) via the scripts/pm/os-regen-merge.sh discipline (merge committed first, artifacts regenerated on the merged tree). Final union at head 846b572aa (worktree clean): check:generated → ✓ All 14 generated artifacts are up to date and the full spec suite → Test Files 415 passed (415) · Tests 11049 passed (11049), plus the light-gate set re-run green at the same head (stack-collection-maps, changeset trio + adr-0087-registration, skills-token-ratchet, nul-bytes, merge-driver, affected-docs, cross-package-test-inputs). Each verdict line quoted is the gate's own printed verdict; exit codes captured before any pipe.

Tests — every package whose tests/fixtures referenced themes/ThemeSchema/defineTheme, full suites, direction: downstream consumers of @objectstack/spec (built from the rebuilt dist):

package	readout
@objectstack/spec	Test Files 415 passed (415) · Tests 11049 passed (11049) (final head)
@objectstack/metadata	Test Files 31 passed (31) · Tests 609 passed (609)
@objectstack/metadata-protocol	Test Files 127 passed, 2 skipped (129) · Tests 1741 passed, 10 skipped (1751)
@objectstack/downstream-contract	Test Files 2 passed (2) · Tests 19 passed (19)
@objectstack/objectql	Test Files 225 passed (225) · Tests 3984 passed (3984)
@objectstack/cli	Test Files 139 passed (139) · Tests 1547 passed (1547)
@objectstack/rest	Test Files 132 passed (132)
@objectstack/runtime	Test Files 178 passed (178)

Reverse verification (measured direction, not assumed): the consumer suites were run against the rebuilt spec dist BEFORE retriage — theme saves that previously pinned success: true failed with the exact new verdict (Error: [invalid_request] 'theme' is not a metadata type … at refuseUnmintableMetaType), i.e. the retirement reached consumers through the built contract, not through test edits; the pins were then retriaged to record the new contract (specimen swaps theme → webhook, plus new #10485 refusal pins). Direction observed: new refusals appeared where acceptance was pinned — diagnostics increased, the expected direction for an accept-set narrowing.

Typecheck:@objectstack/spec (with check:test-typecheck ✓ after removing the Iso700–704 pins), cli, objectql, rest, runtime, downstream-contract, @objectstack/example-showcase — all tsc --noEmit clean after building each dependency closure.

Gates:check:generated green across all 14 artifacts (authorable-surface/manifest deletions self-proved: 6 schema(s) left the published set … each declared (#4725), 5 baseline deletion(s) … carry their own proof (#4650)) · check:stack-collection-maps ✓ (7 enumerations reconciled against 31 declared collections) · check:variant-docs ✓ (18 discriminated union(s) — 8 governed, 10 exempt) · check:liveness ✓ · check:empty-state ✓ · check:strictness-ledger ✓ (row → retirement paragraph; counts regenerated) · check:doc-formula-expressions ✓ · check:durability-log-level ✓ · check:slot-lookup ✓ · check:spec-parsed-alias ✓ · check:test-source-alias ✓ · check:type-source-resolution ✓ · check:merge-driver ✓ · check:cross-package-test-inputs ✓ · docs-audit/check-affected-docs ✓ · check:nul-bytes ✓ · changeset trio (no-major, empty, adr-0087-registration) ✓ · check:skills-token-ratchet ✓ · check:engine-double-contract ✓ · check:where-matcher ✓ · check:query-options-erasure ✓ · check:type-check-coverage ✓ · check:type-check-debt ✓ after full workspace build (lock VERDICT command-exit 0).

Gate list re-derived from the actual diff with node scripts/pm/dispatch-gates.mjs (no paths — merge-base derivation); it added the changeset trio, check:skills-token-ratchet, check-affected-docs, and the test-convention family (query-options-erasure, type-check-coverage, type-check-debt, engine-double-contract, where-matcher) beyond the dispatch list — all run, readouts above.

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 4 package(s): @objectstack/cli, @objectstack/metadata, @objectstack/downstream-contract, @objectstack/spec, touching 40 documentable anchor(s).

5 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/api/environment-routing.mdx(via ObjectStackDefinitionSchema (symbol))
• content/docs/automation/hook-bodies.mdx(via ObjectStackDefinitionSchema (symbol))
• content/docs/concepts/north-star.mdx(via ObjectStackDefinitionSchema (symbol))
• content/docs/deployment/cli.mdx(via ObjectStackDefinitionSchema (symbol))
• content/docs/ui/react-pages.mdx(via borderRadius (literal))

⛔ 3 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v12.mdx(via ObjectStackDefinitionSchema (symbol))
• content/docs/releases/v16.mdx(via os explain (command))
• content/docs/releases/v17.mdx(via ObjectStackDefinitionSchema (symbol))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 18 changed file(s) yielded no anchor (packages/spec/PROTOCOL_MAP.md, packages/spec/api-surface-signatures.json, packages/spec/api-surface/root.json, …) — pages documenting those are invisible to this run
• 23 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 45 of 221 client-bound route-ledger rows — the other 176 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run: node scripts/docs-audit/affected-docs.mjs --bridge-coverage

Coarse fallback — 135 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 5f2e54cc66330cbc53a17f6e3746acdfcdc14704 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from e8f5c35fb09c0fb479c101c9eef7ad74eb860128 — the merge of head 90dc771f2593e1d32d73397e587b95371230ba13 into base 5f2e54cc66330cbc53a17f6e3746acdfcdc14704, 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 e8f5c35fb09c0fb479c101c9eef7ad74eb860128 && git checkout e8f5c35fb09c0fb479c101c9eef7ad74eb860128
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 5f2e54cc66330cbc53a17f6e3746acdfcdc14704 90dc771f2593e1d32d73397e587b95371230ba13 && git checkout -B drift-repro 5f2e54cc66330cbc53a17f6e3746acdfcdc14704 && git merge --no-ff 90dc771f2593e1d32d73397e587b95371230ba13
node scripts/docs-audit/affected-docs.mjs --json 5f2e54cc66330cbc53a17f6e3746acdfcdc14704

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

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 5f2e54cc66330cbc53a17f6e3746acdfcdc14704 → pass the list as
args.docs, on the commit named under Which tree this was computed on.