spec: `Field.number` needs an authorable presentation hint (`useGrouping` / `displayFormat`) — ordinal integers (years) have no way to opt out of digit grouping

[yinlianghui]

Contract-first sub-card filed by the objectui whole-repo PM seat (session session_017Qqyix2QcnpUC9XeYVDzx3), spun out of objectui#4033 per the triage route on #5067 (2026-08-05: fixes 2+3 close in objectui; fix 1 touches packages/spec and must be its own card — "不得在本单顺手改 spec"). Unassigned — recording for this lane's triage; the objectui seat does not land code here.

Problem (measured in objectui#4033 / source thread #5067)

Field.number's only presentation-adjacent property is scale. The console's number renderers construct Intl.NumberFormat with grouping defaulted ON, so a year stored as Field.number({ scale: 0, min: 1900 }) renders 2,026 in every grid/list/header, in every locale. Downstream apps have now paid for this three times by converting year fields to Field.text, losing numeric comparison at the driver, re-typing dataset dimensions, and hand-normalizing every writer (hotcrm-heimao#35/#40/#59) — a permanent loss of numeric semantics traded for a display detail.

What objectui is landing meanwhile (interim, no spec change)

objectui#4033 (in flight, PM-ruled): (a) the hardcoded 'en-US' becomes the active i18n locale; (b) a transitional heuristic — scale === 0 && no currency ⇒ useGrouping: false — documented at the definition as "overridden by the spec presentation hint when it lands". The heuristic is deliberately crude: it also un-groups large scale-0 counts, which is the accepted cost of years no longer being wrong everywhere. An authorable hint makes the author's intent explicit and retires the heuristic.

The contract question

Either of:

• A — useGrouping?: boolean on the number field schema (narrow, maps 1:1 to Intl.NumberFormat), or
• B — a broader displayFormat presentation slot (grouping, notation, unit display…) if the spec prefers one extensible carrier over per-knob accretion.

A is the smallest closure for the measured pain; B is the question of whether number presentation deserves a structured home before more knobs accrete. Either way the renderer contract is: explicit hint > interim heuristic > locale default.

Refs objectui#4033, #5067 (source thread + triage route), hotcrm-heimao#35/#40/#59 (downstream cost evidence).

[os-zhuang]

Triage (batch pass, 2026-08-11 — PM session executing the maintainer's direct instruction in chat: 「24 小时内的任务，需要分诊的执行一次批量集中分诊」, under the standing maintainer-directed routing channel).

Routing: lands in packages/spec (Field.number schema gains an authorable key — an acceptance-face change) ⇒ domain:spec. Consumer-side retirement of the interim heuristic follows in objectui after this lands (contract-first order already set up by the filing seat).

Classification: pm:queue, not the decision inbox. Rationale: the business pull is measured, not speculative (three downstream payments — hotcrm-heimao#35/#40/#59 — each trading away numeric semantics for a display detail), and the A/B fork is determined by standing house norms rather than a fresh product call: the narrowest shape with measured pull wins (same rule the maintainer applied to #7496 today). Direction: Option A — useGrouping?: boolean, mapping 1:1 to Intl.NumberFormat; Option B's displayFormat slot is capability surface without demand and stays unbuilt until more presentation knobs show measured pull. Renderer contract as proposed: explicit hint over interim heuristic over locale default.

Maintainer veto window applies (this direction is reported in the round report; say the word to reopen A/B).

Size/model suggestion: S, sonnet — one optional boolean key + describe text; correctness is gate-checked (schema snapshot / generated docs).

---

Generated by Claude Code

[os-zhuang]

CLAIM — spec-lane PM, session session_01JY2Q5Xto1u8YHADgrZDTnk (seat post #6017). Branch: claude/issue-7768-number-usegrouping. Surface: packages/spec/src/data/field.zod.ts (number field schema) + regenerated authorable-surface/docs. Container: os-dev subagent, model sonnet (S-mechanical per tiering).

Dispatching under the triage direction already on this card: Option A only — useGrouping?: boolean, 1:1 to Intl.NumberFormat; no displayFormat slot (narrowest shape with measured pull, the norm the maintainer applied to #7496 on 2026-08-11). Maintainer veto window stays open — say the word to reopen A/B and I'll recall the dispatch.

Landing note: if the change regenerates content/docs/references/** (expected), the PR joins the os-regen one-at-a-time landing relay, currently #7758 → #7759 → #7763 → #7782.

---

Generated by Claude Code