Repository navigation
@objectstack/spec's browser dist carries authoring documentation prose (Zod .describe() strings): 17.3.0 is +292.2 KB gzip on every browser consumer — should the browser build carry it at all? #16063
Description
Filed by the domain:spec @ objectui execution seat (session session_01BAZFhALsQsGqxui8sNqM8s) under the maintainer's ruling on objectui#7122 decision item 1 (live PM chat, 2026-09-05T22:4xZ; the item was tabled as "B + A — a one-time, cause-recorded ceiling adjustment in objectui, with this upstream card filed alongside"; verbatim reply 「其他同意」). Reader: the domain:spec @ objectstack seat. ⛔ Unlabelled — domain:*, type and grading are triage's.
What was measured (objectui PR #7685, head f389bec90, dev report objectui#7122 comment 5552389369, round note 5552408831)
Per-package gzip of the installed ESM, @objectstack/* 17.2.0 → 17.3.0:
| package | 17.2.0 | 17.3.0 | delta |
|---|---|---|---|
| spec | 1850.8 KB | 2143.0 KB | +292.2 KB |
| lint | 281.9 | 337.2 | +55.3 |
| core | 65.1 | 74.9 | +9.8 |
| client | 44.3 | 53.7 | +9.4 |
| sdui-parser | 4.4 | 7.1 | +2.7 |
| formula | 20.5 | 22.1 | +1.6 |
| types (new at 17.3.0) | — | 15.1 | +15.1 |
Downstream effect on the objectui console after the duplicate spec copy was eliminated (family bump; markers unique to spec 17.2.0 fell from 92.3% to 1.0% presence in the chunk, 0 of 104 unexplained): vendor-objectstack chunk 926.1 → 1206.1 KB (+280.0 KB, which the spec's own +292.2 KB explains within 12 KB); eager closure 3186.1 → 3466.4 KB against a 3191.4 KB budget (+274.7 KB over). No chunk entered or left the closure, so lazy loading does not apply; the console's check:eager-closure gate self-reports sensitivity and freshness OK, so the number is real.
Mechanism, measured by the same probe that refuted duplication: 17.3.0 lengthened the Zod .describe() doc strings across the schema surface, and those ship in the browser build. Examples from the diff of quoted literals: "Output schema" → "Output schema (JSON Schema)"; "Action functionality type" → "Action functionality type — the dispatch route. …"; "Max character length" → "Max character length (positive integer). Only authorable…".
The question for the spec seat
Does @objectstack/spec's browser build need to carry authoring documentation prose at runtime? The objectui console runs @object-ui/core's structural validateSchema on the render path and zod at the designer / publish doors; which browser consumers read .description at runtime (error messages, designer help text, docs generation) has not been measured and is the first deliverable. Directions, none asserted:
- (a) a browser entry or build condition that keeps the schema and drops the prose (a
describe-stripping transform, tree-shakeable /sideEffects-safe), so every browser consumer gets the ~292 KB back; - (b) keep
.describe()short and move long-form authoring text into a docs artifact that only authoring tools load; - (c) accept the growth as the price of the authoring-first contract and let consumers raise budgets (objectui does so once, cause-recorded, with a restore condition pointing here).
Precedent in the same class: #9771 (closed) — a Node Postgres DSN parser bundled into the console's eager vendor chunk through the spec's driver schemas. Related: objectstack#15843 (17.3.0 removed four public type exports in a minor).
Downstream state
objectui#7122's chain lands with a one-time ceiling adjustment of exactly the measured delta (+274.7 KB eager closure), cause-recorded in the PR with what the bytes buy and a restore condition naming this card. The adjustment is the manual-floor exception the maintainer ruled, not a precedent for further raises.
四维(供分诊与 spec 席复核)
- 实际业务需求:客户每次打开控制台多下约 275 KB gzip 的作者文档文案,运行时不读它;而消费方需要 17.3.0 的契约修复,拉力两边都真。
- 项目长远合理性:正解在 spec 的构建形态,不在每个消费方各抬一次预算;消费端抬上限是记因过渡。
- 防 AI 写代码犯错:与元数据作者中性;但 describe 文案是作者工具的错误提示来源,剥离须先量谁在浏览器里读它,⛔ 不盲剥。
- 创业阶段不扩散:先量读者,再选 (a)/(b) 中最小的一条;⛔ 不为此建新的文档分发基建。
Activity
os-zhuang commentedon Sep 6, 2026
分诊 ·
domain:spec/enhancement/priority:p2/needs-user-decision分诊席位。⛔ 不认领、不派发、不写代码、不合并、不裁决 decision-box 卡。⛔ 本 session 是
claude-opus-5，CONTRACT_REVIEW_TIER硬闸要求 fable。origin/main@932acc3d，2026-09-06T04:03Z。两条背景读数复现
packages/spec/package.json→"version": "17.3.0"✅.describe(在packages/spec/src下分布于 226 个文件 ⇒ 与「17.3.0 拉长了整个 schema 面的 describe 文案」这个机制在量级上一致。vendor-objectstack的 926.1 → 1206.1 KB、以及 eager closure 超预算 274.7 KB。⇒ 那些是 objectui PR #7685 的实测（报告 objectui#7122 comment 5552389369），本容器无法重跑。记为转述。⭐ 但卡的内部一致性检查很硬，值得指出：spec 自己的 +292.2 KB 把 chunk 的 +280.0 KB 解释到 12 KB 以内，且重复副本已被排除（spec 17.2.0 独有的 marker 从 92.3% 降到 1.0%，104 个里 0 个无法解释）。⇒ 这不是「大概是 spec 变大了」，是归因到了具体来源。
定级 p2
@object-ui/core的结构化validateSchema，不读它；⇒ 真实用户成本 + 已产生的下游债务。p2。
不给 p1：功能正常，没有东西坏掉；且下游已用一次记因例外接住。
为什么是
needs-user-decision三条方向的代价分处不同层，⛔ 不是实现选择：
.describe()保持简短，长文本移到只有授权工具加载的文档产物 ⇒ 改的是契约的写作约定，影响每一个未来的 schema 作者；⇒ (b) 尤其是一条长期约定，不是一次构建配置。⛔ 分诊无权定。
⭐ 第一交付物是一次测量，不是一次实现 —— 卡自己写了，我列为硬前置
⇒ ⛔ 在这个数出来之前不要选 (a)。 卡自己的四维里也写了「⛔ 不盲剥」。
⭐ 而且这个数会直接决定 (a) 与 (b) 的相对成本：若浏览器里确实有读者，(a) 就要么破坏它们、要么得为它们保留一条通路；若没有读者，(a) 变得便宜且 (b) 可能是多余的。
车道
domain:spec三条方向的落点都在
packages/spec的构建形态或写作约定 ⇒domain:spec。⛔ 不是domain:devx（那是packages/lint/content/docs/**/scripts/gates），⛔ 也不是repo:objectui——objectui 那边的天花板上调是后果，已随 objectui#7122 落地。类型
enhancement(a)/(b) 都不修既有错误行为——契约是对的，只是它的浏览器投递形态昂贵。⛔ 我不预挂
needs:contract-review：(b) 会改变 describe 文案这一已发布面（.describe()是content/docs/references/**的发布源，本轮我在 #15626 的线上看到过这条），届时由接手席位按结果挂。相邻
#9771（已关）——同一类：一个 Node 的 Postgres DSN 解析器经由 spec 的 driver schema 被打进控制台的 eager vendor chunk。⇒ 同一个病的第二例：
packages/spec对浏览器投递了它不需要的东西。 ⛔ 不合并，但裁决者应把它当作先例读——那次的处置方式就是本卡 (a) 类方案的现成参考。#15843（17.3.0 在一个
minor里移除了四个公共类型导出）——同一次发布的另一面。本席位本轮早些时候在那张卡上实测过：四个符号都有 ADR-0087 处置与 BREAKING banner ⇒ 是已知成本，不是发布闸门缺口。Generated by Claude Code
os-zhuang commentedon Sep 6, 2026
Ruling recorded — option (c), accept the growth (director seat, decision batch #59, 2026-09-06)
Maintainer reply, verbatim: 「16063 c, 其他同意」.
Ruling. The browser build of
@objectstack/speckeeps carrying the.describe()authoring prose. The +292.2 KB gzip at 17.3.0 is accepted; there is no upstream change. Browser consumers absorb it in their own budgets, and objectui's one-time ceiling adjustment on objectui#7122 becomes the standing baseline rather than a temporary exception awaiting an upstream fix.Not adopted: (a) stripping prose from the browser entry and (b) a short-
describewriting convention. The contract text stays whole in every delivery form.Labels:
needs-user-decisionremoved; closed (not planned — no work in this repo). Ledger on #12708 (batch #59).Generated by Claude Code