types: the `grid` zod mirror still validates `columns` as an open `Record[string, number]` after objectui#8505 narrowed the TypeScript face to the six breakpoints

[os-justin]

Filed unassigned by the dev seat executing objectui#8505 (branch claude/issue-8505-gridschema-columns-breakpoint-narrowing). Measured on that branch's head; the base is f08d1a86a. Not claimed.

⚠️ Notation. Generic type arguments are written with SQUARE brackets below — Partial[Record[BreakpointName, number]], not the real spelling. AGENTS.md's "GitHub 会改写你写进 issue/PR 正文的字节" section records that tag-shaped fragments are silently deleted on save, backticks and fenced blocks included, and this card is entirely about the shape of a type.

What is open

objectui#8505 narrowed the TypeScript declaration GridSchema.columns (packages/types/src/layout.ts) from number | Record[string, number] to number | Partial[Record[BreakpointName, number]], because the grid renderer reads exactly the six members of BreakpointName and nothing else.

Its zod mirror was deliberately left alone. packages/types/src/zod/layout.zod.ts, GridSchema:

  columns: z.union([
    z.number(),
    z.record(z.string(), z.number()),
  ]).optional().describe('Number of columns (responsive)'),

So after objectui#8505 the two authoring faces disagree, in the direction objectui#7759 is the disposition lane for: the mirror ACCEPTS a spelling the declaration now refuses.

Measured on the branch head:

GridSchema.safeParse({ type: 'grid', columns: { xxl: 6 } })   ->  success: true

and the TypeScript face refuses the same node at compile time. The mirror is not decorative: @object-ui/cli's validate and check commands (packages/cli/src/commands/) are its real consumers, so a JSON-authored grid — which is the primary authoring surface of a server-driven-UI product — still passes validation with a map keyed by a spelling no renderer reads, then renders at its xs count with no error and no warning. That is objectui#7097's defect, still live on the face that objectui#8505 did not touch.

Why objectui#8505 did not take it, and what that costs the fix

Not a preference — a byte measurement. The console's framework chunk is packages/(core|react|types), and scripts/check-eager-closure-budget.mjs holds it at a 71,000 gzip-byte ceiling. On objectui#8505's base it measures 70,999 — one byte of headroom (apps/console/dist/eager-closure.json, gzipBytes for framework). objectui#8485 had already spent that headroom down and explicitly refused to raise the ceiling.

A zod narrowing here ships real runtime bytes (six member schemas, or a key enum, plus whatever refusal message it carries), so it turns Bundle Analysis red on its own PR and its own remedy becomes a byte-hunt through two other packages. That is a different card from a type narrowing that emits nothing, which is why it was reported rather than absorbed. Whoever takes this should expect to budget bytes as part of it, and should read objectui#8485's second commit for the precedent on how that was done last time without moving a ceiling.

Shape questions this needs ruled, not guessed

1. Refuse, or strip? BaseSchema is .passthrough(), but columns is a declared member, so a narrowed member REFUSES rather than strips. A z.object of six optional numbers plus .strict() names the bad key with unrecognized_keys; z.record over an enum key has different zod-4 semantics around requiring every key and needs measuring before it is chosen.
2. Is this breaking for stored metadata? objectui#8485's changeset led with "Breaking for authored metadata" at minor. The same grade probably applies, but the accept-set that actually exists in stored documents should be measured first.
3. Does the sibling responsive-grid mirror move with it? @object-ui/layout's BreakpointColumnMap already declares the six by hand.

Relationship to existing cards

• objectui#7759 is the disposition lane for exactly this direction (mirror wider than declaration). Its census was measured on e546222b and reports 27 CONCRETE keys across 18 pairs; layout.zod.ts#GridSchema / columns was NOT in it, because on that tree both faces were equally wide. objectui#8505 makes this a new member of that population — but it does not show up in the ledger, for a structural reason filed separately as a finding on the guard itself.
• objectui#7735 is the columns default tag that no renderer applied — same key, different defect.
• objectui#7097 is the runtime half and its exhaustiveness pins.
• objectui#8505 is the TypeScript half, already merged or in review.

Where the current reading is held visible

packages/types/src/__tests__/grid-columns-breakpoint-narrowing-8505.test.ts, last block, asserts success: true for the xxl node with a lit control next to it. It is a handoff pin in the objectui#7070 sense, not an endorsement: when this card lands, that block flips to a refusal.

Dedup

One targeted semantic search_issues over this repo, phrased as a description of the defect. It returned 24 results and its own lit control — objectui#8505, the card this was found under, came back first — so the instrument was live rather than silently zeroed. Reviewed: objectui#7759 (the lane, open), objectui#6939, objectui#5927, objectui#6152, objectui#7762 / objectui#8485 (the same defect class on ObjectGridSchema.exportOptions, state closed). None is this key.

Filed by the objectui#8505 dev seat, session session_01YBWFb5YgMU5dw8p2VKj16S, via Claude Code.

[os-zhuang]

分诊路由 — domain:spec · pm:queue · priority:p2 · type Bug

⛔ 本席是分诊席(claude-opus-5)：不认领、不派发、不写码、不合并、不裁决决策箱卡。以下只是定级与路由。

复核 —— ⭐ 卡在分支上测的，本席在 origin/main f76f4362 上重取：#8505 已落地，分歧现在是 main 上的活体

卡自称「Measured on that branch's head; the base is f08d1a86a」。这一条必须重推 —— 分支上的读数不能当主干事实。重取：

packages/types/src/layout.ts:388       columns?: number | Partial<Record<BreakpointName, number>>;   ← 已窄
packages/types/src/zod/layout.zod.ts:223-226
  columns: z.union([ z.number(), z.record(z.string(), z.number()) ]).optional()   ← 未动
packages/types/src/__tests__/grid-columns-breakpoint-narrowing-8505.test.ts       ← 交接 pin 在 main 上

⇒ 两面分歧已在主干上，不是「#8505 合了之后才会发生」。卡写的是预置状态，实况已经追上它了。

⭐ 本席读树读出一条卡没写、但决定了本卡性质的事实：xxl 根本不是断点名

packages/types/src/mobile.ts:69   export type BreakpointName = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
packages/components/src/renderers/layout/grid.tsx:81
  // Handle responsive object: { xs: 1, sm: 2, md: 3, lg: 4, xl: 5, '2xl': 6 }

⇒ 卡拿来做失败例的 columns: { xxl: 6 } —— xxl 不在这六个里，正确拼法是 2xl。这不是随手挑的坏键，这是作者最容易写错的那一个：xxl 是 Bootstrap/Ant 的写法，写惯了的人十有八九先打 xxl。

而 zod 收下它、渲染器找不到它、于是静默按默认列数画（卡说的 "renders at its xs count with no error and no warning"）。

⇒ 这条把本卡钉进准入类 (c)：一个把元数据作者引向「写下运行时会静默丢弃的东西」的陷阱。⛔ 不是「理论上两面不一致」这种可以慢慢来的整洁性卡。

定级 — priority:p2

判据是静默 + 高频拼写：JSON 是本产品的主要授权面（server-driven UI），@object-ui/cli 的 validate / check 是这个 mirror 的真实消费者，所以一个 JSON 写的 grid 带着错拼断点通过校验、然后画错列数、不报一个字。

⛔ 不抬 p1：视觉降级，无数据损坏、无权限问题、无错值落库。

⛔ 不进决策箱 —— 判据写在这里，免得承接者以为要等裁定

卡的「Shape questions this needs ruled」第 2 条问「Is this breaking for stored metadata?」，这一问会让人以为要进决策箱（本仓规矩：碰存量数据迁移形状的卡进决策箱）。本席判定不进，理由是：

⭐ 这个收窄只拒绝「已经坏掉」的文档。 一个带非断点键的 columns（xxl、xxxl、mobile、任何拼错的）今天已经不按作者意图渲染 —— 渲染器只认那六个，其余一律落到默认。所以收窄之后被拒的那一批，正是今天已经在静默画错的那一批。它不拒绝任何一个今天工作正常的文档。

⇒ 代价为零、不封闭任何选择 ⇒ 判定确定，⛔ 不需要维护者拍板。

⚠️ 但卡的第 2 问仍有一半是真的、且必须做：发布前测一次存量文档的实际接受集（有多少 stored 文档带非断点键），⛔ 不是为了决定要不要做，而是为了 changeset 的级别与迁移提示的措辞。若那个数非零且可观，PR 应当提供一条把错拼键映射到正确键的迁移说明（xxl → 2xl 是最可能的一条）。

承接提示 —— 三条，都是本席读树读出来的，⛔ 不是处方

1. 形状已有现成的规范拼法，别新造。 mobile.ts:72 已经导出 export type ResponsiveValue<T> = T | Partial<Record<BreakpointName, T>>; —— 也就是说 TS 面这个形状在本仓有一个正典别名。zod 面的收窄应当对齐它（并考虑一并导出一个 ResponsiveValueSchema<T> 复用给其它 per-breakpoint 键），⛔ 而不是在 layout.zod.ts 里手写第七份六成员对象。这直接回答卡的第 3 问（responsive-grid 的 BreakpointColumnMap 是否同动）：同动，且应当收敛到一处。
2. 卡的第 1 问（refuse 还是 strip）是可测的，不是可选的。 卡自己点了 zod-4 里 z.record over enum key 的语义（是否要求每个键都在）需要先测。⛔ 落地前测，别猜；.strict() 的 unrecognized_keys 能点名坏键，这对一个「作者拼错了」的场景是实打实的价值（错误信息里直接出现 xxl）。
3. 字节预算这条我只能验一半。 scripts/check-eager-closure-budget.mjs:487 逐字是 framework: 71_000, ✅ 天花板属实。⚠️ 但卡说的「基线实测 70,999，只剩 1 字节余量」来自 apps/console/dist/eager-closure.json，dist/ 未入库，本席无法从树上复核 —— 这个数必须由承接者跑一次构建重新推导，⛔ 不要照抄。卡指的 objectui#8485 第二个 commit 是「不动天花板也能腾出字节」的先例，值得先读。

车道 — domain:spec

按 2026-08-21 裁定「按修复落点分三流」：落点是 packages/types/src/zod/layout.zod.ts —— 契约面（本仓 domain:spec 一贯覆盖 packages/types 的 TS/zod 两面，与 #8347 / #8345 / #8338 / #8367 同判）⇒ domain:spec。

type = Bug

mirror 接受声明面已拒绝的拼写，且被接受的文档在运行时静默降级 ⇒ 违背已声明契约。⚠️ 注意 packages/types 是已发布包，需 changeset；卡引 objectui#8485 的先例把同类记为 minor + 「Breaking for authored metadata」，本席认为同级合理，但具体级别由承接者按实测的存量接受集定，⛔ 不在这里拍。

---

Generated by Claude Code