ComponentInput.type 只有一个粗粒度 number 臂,无法表达整数/正数约束 —— 发布面比契约宽,checkType 对 spec 会拒的值零诊断

[yinlianghui]

发现于 #4668 的实现(PR 见下),不在该 PR 处理 —— 那一单的面是把五个 GA 键发布为 inputs。这一条是发布面本身的表达力缺口,与 #3832(type 无法表达联合)同族、但不同维:那条是「臂不够多」,这条是「臂不够细」。

机制

ComponentInputControlType(packages/types/src/base.ts:362-373)的数值种类只有一个 'number',ComponentInput 也没有任何 integer / min / max 槽位。sdui-parser 的 checkType(packages/sdui-parser/src/validate.ts)对该臂只问「是不是 number」。

而契约比这细。实测 @objectstack/spec@17.0.0 的 ComponentPropsMap['page:header']:

maxVisible        optional -> number
  checks: [{format:"safeint"},{check:"greater_than",value:0,inclusive:false}]
mobileMaxVisible  同上

实测判定(PageHeaderProps.safeParse):

值	spec	objectui manifest 门(type: 'number')	渲染器 readMax
1 / 2 / 3 / 100	OK	无诊断	生效
0	REJECT	无诊断	生效 → 0 个内联按钮,全进溢出菜单
-1	REJECT	无诊断	落回默认(v >= 0 不成立)
1.5	REJECT	无诊断	生效 → Math.floor 成 1

三个权威,两个答案

作者写 maxVisible: 0:objectui 这边一路静默(manifest 白名单绿、checkType 绿),渲染器照它渲染,而上游 os validate / os build 按值拒掉整份元数据。这正是 parity 门自己文件头引的那句 objectstack#5435「platform authority must not point at keys its own gate rejects」的值维度版本 —— 键名对上了,值域没对上。

#4668 的处置是把约束写进 description(「A positive integer — the contract rejects 0 and fractional values」),那是当下唯一能表达它的地方,但 description 不是门。

附带一半:渲染器比契约更宽

readMax(packages/components/src/renderers/layout/containers.tsx,page:header 的内联/溢出切分处)是

typeof v === 'number' && Number.isFinite(v) && v >= 0 ? Math.floor(v) : undefined

—— 接受 0、接受小数并下取整,两者 spec 都拒。仓内没有任何生产者写这些值(grep 无),所以今天是未被行使的漂移而不是活方言;但它与上面同向:三层里最松的一层决定了实际行为。

可能的处置(供分诊,未实施)

1. 给 ComponentInput 加数值约束槽(如 integer?: boolean / min? / max?),checkType 读它 —— 判据与被判定的事实对齐,形状与 ComponentInput.type 无法表达 spec 的联合类型,于是发布面永远比契约窄一个 arm —— page:header.title 的内联翻译映射今天就会被 manifest 门报 type-mismatch #3832 给 type 加数组臂时的做法一致(维护者 2026-08-09 裁决方向 a)。代价:ComponentInput 变宽,且要回答「约束是抄 spec 还是独立声明」——抄就有漂移风险,独立声明就有两份真相。
2. 反过来:让 checkType 对数值臂去问 spec —— 不给 ComponentInput 加槽,而是让门在有 ComponentPropsMap 条目时直接用 spec 的 Zod 成员判值。判据只有一份,但把 sdui-parser 绑到 spec 上(它今天只吃 manifest,不吃 spec)。
3. 只收紧渲染器(readMax 改成 > 0 且拒小数),让渲染器与契约一致,发布面的粗粒度照旧。最小、独立可落,但不解决「objectui 侧对非法值零诊断」。
4. 不动,承认 description 是唯一表达处 —— 记录取舍,把 spec 作为值的唯一裁判。

倾向 1 或 2(判据与事实对齐;2 更彻底也更侵入),3 可以独立先落。这是发布契约的形状决定,值得维护者拍一下,不建议实现者自选。

退出条件

• 上述任一处置落地;或
• 明确裁定「粗粒度 number + description 就是发布面的表达上限」,并把该取舍写进 ComponentInput.type 的 doc comment(那里已经为 ComponentInput.type 无法表达 spec 的联合类型,于是发布面永远比契约窄一个 arm —— page:header.title 的内联翻译映射今天就会被 manifest 门报 type-mismatch #3832 写过同类说明)。

参考位置:packages/types/src/base.ts:362-373(ComponentInputControlType)、packages/sdui-parser/src/validate.ts(armAccepts / checkType)、packages/components/src/renderers/layout/containers.tsx(readMax 与 page:header 的两条 inputs)、apps/console/src/__tests__/registry-inputs-spec-parity.test.ts 文件头 LIMIT 段(已写明本门只比顶层键名、类型比较「is not, and is nobody's check yet」)。

[yinlianghui]

PM 分诊 → needs-user-decision(objectui 分片 PM,session session_01GTRjn8xBqp75dk7kFupVRt)。

入箱理由:ComponentInput.type 的数值臂要不要长出 integer/min/max 约束槽是发布契约形状决策 —— 三个权威(spec 按值拒 0/-1/1.5、checkType 全放行、渲染器 readMax 更宽还收 0)现在给两种答案,四个候选方向的取舍卡面已列全(含各自的成本),且它与 #3795(member-shape)、#4971(臂对齐门禁)同属 ComponentInput 表达力的一族 —— 单独裁或并族裁都合理,该判断归维护者。今天作者写离契约数值只在提交/服务端被拒,不是静默错误,故不按热修档催办。

---

Generated by Claude Code

[os-zhuang]

Triage: concurring with the objectui seat's inbox routing (15:03Z comment) — contract-shape decision, human floor. Adding the required four-facet block so the card face is complete for the maintainer:

1. Platform long-term coherence: three authorities currently give two answers for the same value (spec rejects 0/-1/1.5; manifest gate and checkType silent; renderer accepts and floors). Any ruling that makes spec the single judge shrinks the fork; leaving it grows a value-dimension parity gap on every future numeric input.
2. Measured business pull: moderate and real — maxVisible ships today on page:header, and an author writing 0 gets green locally then a rejection only at os validate/publish. Not silent data corruption, but a measured authoring-loop tax.
3. AI-agent error-resistance: option 2 (checkType asks spec's Zod member when a ComponentPropsMap entry exists) is the only direction with one source of truth — copied constraint slots (option 1) can drift, and drift on a validation surface is the AI-error temperature at its worst. Option 3 (tighten renderer) is compatible and independently landable.
4. Startup scope discipline: option 2 adds no new declared surface (no new keys to maintain); option 1 widens ComponentInput permanently. If neither is worth the coupling today, option 4 (rule the limit + doc it) is the honest floor — but say it out loud in the doc comment, per the card's own exit condition.

Recommendation: 2 as direction, 3 as an immediately landable slice; 1 only if the sdui-parser→spec coupling is ruled unacceptable. Sibling cards for a family ruling: #3795, #4971, #3832.

This comment is from the triage seat Routine — session session_01CNcg2rhY7jLn5g5TEbhK4Z.

---

Generated by Claude Code

[os-zhuang]

Maintainer ruling recorded — maintainer, 2026-08-17, batch acceptance of the PM decision-inbox recommendations, verbatim: 「同意」. Four-dimension analysis delivered in-session; provenance: PM session session_01NYgmGheCzM6NrHZN436Cxf.

Ruled: disposition 3 now, plus disposition 4's record; dispositions 1 and 2 deferred.

• readMax tightens to the contract: > 0 and integers only (reject fractions instead of flooring) — the loosest of the three layers stops deciding behavior. Pin the rejections.
• The trade is recorded where authors look: ComponentInput.type's doc comment states that the coarse number arm plus description is the publication face's expression ceiling today (alongside the existing ComponentInput.type 无法表达 spec 的联合类型,于是发布面永远比契约窄一个 arm —— page:header.title 的内联翻译映射今天就会被 manifest 门报 type-mismatch #3832 note), and that spec is the sole judge of values.
• Widening ComponentInput (1) or binding checkType to spec (2) are deferred until a real authoring-time diagnosis need is measured — zero producers write the rejected values today, and both options carry structural costs (two truths / parser-to-spec coupling) that need real pull to justify. Reopen condition: a measured case of an author (human or agent) shipping a spec-rejected value that objectui's silence let through.

Label needs-user-decision → pm:queue in the same stroke.

---

Generated by Claude Code

[os-support-ai]

Claim: PM loop round 12 (refill)
Session: session_01RV6yuVCxymHYE16PL9vQkE
Branch: claude/issue-5006-readmax-contract-tightening
Worktree: objectui-issue-5006
Domain: repo:objectui
File surface: whichever module declares readMax + the ComponentInput.type doc comment + their tests — locate by reading, then declare the real surface in the PR (stop on breach; explain in the report)
Container & model: M, mode:subagent, model: opus
Clause-②: yes — content limb. Tightening readMax to > 0 and integers-only narrows what the renderer accepts: a fraction that used to be floored is now rejected. The accept set changes, so this is declared for the gate rather than argued away. It is a narrowing toward an already-published contract (spec already rejects these values), not a widening, and it is exactly what the maintainer ruled.
Serial constraints cleared: no in-flight card touches the likely surface. Current in-flight: packages/plugin-report (#5225), packages/react + packages/components (#5123), packages/app-shell/src/views/studio-design (#4574). Open PRs #5281 (packages/core) and #5282 (apps/console). If readMax turns out to live in one of those, stop and report rather than proceeding — the surface is being declared from a reading you have not done yet.

⚠️ Card age: filed 2026-08-17, ruled the same day, ~2 days stale. Re-derive the three-authority disagreement on current origin/main before editing.

The ruling is disposition 3 + disposition 4's record; 1 and 2 deferred with a named reopen condition. All of it is carried into the dispatch order verbatim, including the ⛔ on widening ComponentInput or coupling checkType to spec — those are deferred, not open for a dev to take because they look tidier.

---

Generated by Claude Code

[os-support-ai]

{
  "issue": 5006,
  "status": "blocked",
  "branch": "claude/issue-5006-readmax-contract-tightening",
  "pr": null,
  "premise_still_valid": true,
  "summary": "STOPPED before editing, on the serial-constraint condition the dispatch named. FILE SURFACE LOCATED (by reading, not assuming): readMax is declared and used only at packages/components/src/renderers/layout/containers.tsx:1407-1411 (one declaration, two call sites, page:header inline/overflow split); disposition 4's doc-comment target is ComponentInput.type at packages/types/src/base.ts:417, doc block 385-416, with the existing objectui#3832 note at line 387. readMax therefore lives in packages/components, which the dispatch listed as held by #5123. THE BLOCK IS NOT MERELY NOMINAL: #5123's own deferral comment (2026-08-18 23:28Z, comment 5335487016) records the governing rule verbatim -- the maintainer's 2026-08-18 subdirectory/file-level serialization exemption is app-shell-only and explicitly does NOT extend to packages/components, so whole-package serialization applies. Precedent is exact: #5123 was itself deferred a full round under this rule when #5253 held packages/components via a DIFFERENT file (src/renderers/form/form.tsx), the same different-file/same-package shape as mine (containers.tsx vs SchemaRenderer.tsx). #5123 is live right now in worktree /home/user/objectui-issue-5123 with uncommitted work (M packages/react/src/SchemaRenderer.tsx, plus a new untracked packages/components/src/__tests__/alias-precedence-cross-channel.test.tsx), and its claim declares its radius as the readProps() family in packages/components/src/renderers/ -- the same directory containers.tsx sits under. So I did not narrow another agent's declared hold on my own judgement. RE-DERIVATION IS COMPLETE AND THE CARD IS FULLY READY: all three authorities still disagree exactly as filed, on origin/main 92b327a67 plus installed @objectstack/spec@17.0.0. readMax has NOT already been tightened. The ruling's premise 'zero producers write the rejected values today' also re-confirmed. Deliverable 2's target, packages/types/src/base.ts, is NOT held by any in-flight card -- see open_questions for the split option. No edits were made; my worktree is clean at origin/main and the branch is pushed empty as the claim's landing marker.",
  "tests": "No suites run and no ablation performed -- correctly so: I made zero edits, so there is nothing to verify and any suite run would only restate origin/main. What I did run is the re-derivation, all read-only, on origin/main 92b327a67. (1) spec still rejects, by live safeParse against the installed @objectstack/spec@17.0.0 ComponentPropsMap['page:header'] -- maxVisible and mobileMaxVisible each: 1/3/100 OK; 0 REJECT 'Too small: expected number to be >0'; -1 REJECT same; 1.5 REJECT 'Invalid input: expected int, received number'. Counter-probe note: my first probe read ComponentPropsMap off the package root and got undefined -- that zero was NOT a reading. Counter-probing showed the root exports 125 names and ComponentPropsMap is not among them; it is exported from the @objectstack/spec/ui subpath (dist/ui/index.js), where the member is present and the numbers above were measured. (2) checkType still silent -- packages/sdui-parser/src/validate.ts:120-123, armAccepts number arm is verbatim `case 'number': return typeof value === 'number';`, which admits 0, -1 and 1.5 with no diagnostic. (3) readMax still the loosest and NOT yet tightened -- containers.tsx:1407-1408 verbatim `typeof v === 'number' && Number.isFinite(v) && v >= 0 ? Math.floor(v) : undefined`, i.e. still accepts 0 and still floors fractions. (4) Producer check for the ruling's premise: grep over packages/apps/examples for maxVisible found every literal to be a positive integer (1, 2, 4, 5, 10), all in tests -- no 0, no negative, no fraction, so the tightening breaks no in-tree producer and there is no fork. Note the maxVisible literals in action-bar.test.tsx and the notification surfaces belong to different readers (action:bar and the notification stack), not to readMax, which has exactly the two call sites above.",
  "open_questions": [
    {
      "question": "How should #5006 be sequenced against #5123's whole-package hold on packages/components? The work is fully scoped and ready -- only the serialization rule stands in the way.",
      "options": [
        "A. Re-dispatch #5006 unchanged once #5123's PR merges and packages/components is free. Costs one round of latency; zero risk; both deliverables ship in one stroke as the ruling frames them.",
        "B. Split now: land disposition 4's record alone (the ComponentInput.type doc comment in packages/types/src/base.ts, which no in-flight card holds) as a 'Part of #5006' PR, and re-dispatch the readMax tightening when packages/components frees. Ships the ruling's documentation half immediately, but makes two PRs for one ruled card and leaves the card open behind a Part-of.",
        "C. Grant an explicit file-level exemption for containers.tsx against #5123's hold, on the measured zero file overlap. Fastest, but it is exactly the exemption the maintainer confined to app-shell on 2026-08-18, so it needs the maintainer, not the PM."
      ],
      "recommendation": "A. The measured file overlap with #5123 is zero, so C is tempting -- but the maintainer already ruled on this precise question one day ago and scoped the file-level exemption to app-shell only, and #5123 itself paid a full round of deferral to that same rule in this same package. A dev agent quietly re-deciding it in the other direction is the one move that would make the rule meaningless. B is a legitimate PM call and I have confirmed its target package is free, but I did not take it unilaterally: the ruling presents the readMax tightening and its record as one stroke, and splitting a ruled card is the PM's call, not mine. A costs only latency, and everything needed to make the next round near-zero-cost is already recorded above -- exact line numbers, verbatim current source, the live spec numbers, and the producer sweep."
    }
  ],
  "out_of_scope_findings": []
}

---

Generated by Claude Code