spec: `maxLength` is authorable on every field type and validated as no more than a number — `maxLength: 0` and `maxLength: 12.5` parse cleanly

[claude]

Found while implementing #11431. Filed unassigned. Cannot be fixed from the driver lane — packages/spec is a different seat.

What

packages/spec/src/data/field.zod.ts declares:

maxLength: z.number().optional().describe("Max character length"),

on the base field schema. Two consequences:

1. No shape validation. .number() alone accepts 0, -5, 12.5 and Infinity. None of those is a character length, and each parses without complaint.
2. Authorable on every type. Being on the base schema, maxLength is legal on boolean, date, lookup, autonumber, formula — types where it describes nothing that is stored.

Evidence that this is not theoretical

schema-drift.ts read a malformed bound as authoritative and planned DDL no server accepts — maxLength: 0 took the narrowing arm (0 > 255 is false) and asked for varchar(0), at severity error / category destructive, i.e. as work os migrate apply --allow-destructive should go do. Fixed on the driver side in #11431 by refusing anything that is not a positive integer, but that is a consumer defending itself against a producer that should not have emitted the value (PD #12).

The authoring forms already disagree about where the key applies, which suggests the base-schema placement was never deliberate:

• field.form.ts shows maxLength for text / textarea / email only
• object.form.ts shows it for text,textarea,email,url,phone,password,markdown,html,richtext

Neither list matches the other, and neither matches the base schema's "every type".

The write-time validator (packages/objectql/src/validation/record-validator.ts) enforces maxLength for text | textarea | email | url | phone | password | markdown | html | richtext | code — a third list, and the closest thing to a real answer for which types the key means something.

Direction (for triage — not prescribing)

Two separable decisions:

• Shape. z.number().int().min(1) is the house pattern, and the file already applies exactly it to precision one field below (z.number().int().min(0)) for the same stated reason — spec: Field.scale accepts meaningless declarations (2.5, -1) — now that scale is enforced, malformed declarations should be refused at authoring time #8321's "a non-integer or negative declaration has no defined meaning". Cheap, and strictly a tightening.
• Applicability. Whether maxLength should be refused on types that do not store a bounded string is the larger question, and touches ADR-0078 declared=enforced. The validator's ten-type list is the natural candidate for the allowed set.

---

Generated by Claude Code

[os-zhuang]

分诊(Routine 席,小时轮):入决策箱,needs-user-decision + domain:spec,type Bug(校验缺口本体是缺陷,但两个修法都收窄接受集 = 契约变化,人工地板)。下游注记:#11431(engine,pm:blocked)的 Blocked-by 指向本卡,裁决落地即解锁它。标准四棱块:

os-decision-facets

① 实际业务需求:maxLength: 0 已实测把 schema-drift 推到「计划一个没有服务器接受的 varchar(0) DDL、且标记为 destructive」——这是真实的错误放大链,不是理论洞。写侧校验器的十类型清单就是今天真实在读这个键的消费者。

② 项目长远合理性:形状收紧(z.number().int().min(1))与同文件 precision 的既有 house pattern 完全同构,是把已声明意图兑现;适用面收窄(哪些类型允许 maxLength)触 ADR-0078 declared=enforced,且三份清单(field.form / object.form / record-validator)互不一致——收敛到校验器的十类型清单是唯一有实测读者背书的答案。

③ 防 AI 犯错:这是四轴里最强的一条:maxLength 现在「每个类型都可声明、什么形状都能过」,AI 作者在 boolean/lookup 上写 maxLength 得不到任何响声。publish 时响亮拒绝优于驱动侧逐个防御(#11431 已被迫在消费端防了一次)。

④ 创业阶段不扩散需求:两个修法都是收窄不是扩张,成本一次性;不裁的成本是每个驱动/工具各自防御一遍。

推荐:形状收紧(int ≥1)+ 适用面收敛到 record-validator 的十类型清单,一次裁掉两问;实施走条款②契约复审档位,并同笔对齐 field.form/object.form 两份表单清单。 本分析看不见的:存量已发布 app 里是否有踩线声明(如小数/0/挂在非字符串类型上)——若维护者知道存在,裁决需附迁移/宽限条款。

---

Generated by Claude Code

[os-zhuang]

Maintainer ruling recorded — tighten both halves

Provenance: maintainer, 2026-08-24, live PM chat, batch acceptance, verbatim: 「四维分析一致的，接手你的建议。」 The four-facet block above is aligned, so the recommendation is adopted.

Ruled: shape tightens to the house pattern (z.number().int().min(1), per the precision precedent one field below), and applicability converges to the write-time validator's ten-type list (text | textarea | email | url | phone | password | markdown | html | richtext | code) — maxLength refused on types that store no bounded string. The two authoring-form lists (field.form.ts, object.form.ts) are aligned to the same ten in the same stroke. Clause-②: yes (narrows the accept set) — contract-review tier applies at dispatch.

State: needs-user-decision → pm:queue (spec lane). Downstream: #11431's Blocked-by: #11566 unlocks when this closes; the engine seat should re-verify that card's surface on the post-landing ref per the unlock discipline.

---

Generated by Claude Code

[os-support-ai]

Claim: PM loop round R5 wave 1
Session: session_01K93P8PbH7kVjsAXkqzH1zY
Branch: claude/issue-11566-maxlength-shape-applicability
Worktree: objectstack-issue-11566
Domain: domain:spec
File surface: packages/spec/src/data/field.zod.ts (base-schema maxLength at :856 + the length/size alias map at :738), packages/spec/src/data/field.form.ts, packages/spec/src/data/object.form.ts, new rejection pins + changeset (stop on breach; explain in the report). ⛔ packages/spec/src/migrations/registry.ts is HELD by the #10724/#11169 family dispatch this wave — if this tightening's conventions force a touch there, stop and report rather than editing it.
Container & model: M, mode:subagent, model: claude-fable-5 — dispatch-gates --tier packages/spec/src/data/field.zod.ts (this dispatch): "Clause ② SUSPECT surface — packages/spec/src/** — the contract surface … the normal landing zone of a clause-② card"; content reading is the verdict: the 2026-08-24 ruling narrows the accept set ⇒ fable-mandatory.
Clause-②: yes
Serial constraints cleared: same-file predecessor PR #11903 (deleteBehavior, the .overwrite() region) merged 2026-08-25 — same-day churn clause applies, work from current merged main. H17 hit named per protocol: hold #8345 declares field.zod.ts as a Restart-touch trigger file — notification only, no rider work taken from it. In-flight overlap: none (lane had 0 dispatched cards at fire); lane sibling #11408 (editMode, may touch object.form.ts) is deliberately held to wave 2 behind this card — cross-wave serial, not a fold (different defect shape, fails family gate ①). Cross-lane: #11739 (services, feat(spec,auth)) touches spec on the auth-posture surface, disjoint from this file set.

---

Generated by Claude Code