`signature` / `qrcode` have no `maxLength` enforcement anywhere, so they cannot join the TEXT family — a data-URI signature is refused at 255 chars and the declared bound binds nothing

[huangyiirene]

Found while fixing #11794 (richtext emitted as varchar(255)). Filed unassigned; deliberately not fixed there — that card's fence was "if it turns out to widen accepted physical shapes beyond the declared contract, stop and report", and these two are exactly what it caught.

Related: #11431 (the string family ignores maxLength). Independent of it — that card is about a bound that exists and is not honoured; this one is about a bound that is honoured by nothing at all.

The invariant #11794 established

A field type may take an unbounded TEXT column exactly when the write seam enforces its declared maxLength. That is not a new rule — schema-drift.ts already rests on it, in as many words:

A TEXT column refuses nothing a maxLength allows, so there is no divergence to plan an ALTER for; the bound is enforced at the write seam.

The measurement

validateRecord (packages/objectql/src/validation/record-validator.ts) applies its max_length / min_length branch to a hard-coded type list. Measured — a { type: T, maxLength: 64 } field, a 100-character value, mode: 'insert':

text REFUSED VALIDATION_FAILED f must be <= 64 characters (got 100)
textarea REFUSED VALIDATION_FAILED f must be <= 64 characters (got 100)
markdown REFUSED VALIDATION_FAILED f must be <= 64 characters (got 100)
html REFUSED VALIDATION_FAILED f must be <= 64 characters (got 100)
richtext REFUSED VALIDATION_FAILED f must be <= 64 characters (got 100)
code REFUSED VALIDATION_FAILED f must be <= 64 characters (got 100)
signature ACCEPTED <- no max_length branch
qrcode ACCEPTED <- no max_length branch
secret ACCEPTED <- no max_length branch
color ACCEPTED <- no max_length branch
string ACCEPTED <- no max_length branch (the column carries it — #11431)

maxLength is a plain optional key on FieldSchema (field.zod.ts), admitted on every field type. So Field.signature({ maxLength: 64 }) parses, publishes, and binds nothing.

Why that leaves these two types stuck

signature and qrcode are STRING_VALUE_TYPES members whose stored value is the author's own value, and it is routinely far past 255 characters — field-zoo writes a data-URI PNG for signature. So they have the same live defect #11794 fixed for richtext. Measured on live MySQL 8.0.46 (STRICT_TRANS_TABLES) and Postgres 16, a 1000-character value today:

 physical column 1000-char write
signature pg character varying(255) REFUSED 22001
signature my varchar(255) REFUSED ER_DATA_TOO_LONG
qrcode pg character varying(255) REFUSED 22001
qrcode my varchar(255) REFUSED ER_DATA_TOO_LONG

But moving them into the TEXT family the way richtext and code moved would replace an under-accepting column with an over-accepting one: with no write-seam bound and no column bound, a declared maxLength would be enforced by nothing on any dialect. That is a physical surface wider than the declared contract, so #11794 left them where they were and asserted the refusal out loud instead (sql-driver-11794-richtext-text-family.test.ts, "records the STILL-OPEN half"). Note the enforcement is not uniformly absent even today: the #11374 keyed-and-bounded rule would give a keyed bounded column varchar(maxLength), so a move would make enforcement depend on whether an index happens to key the column — the dialect/shape-divergent enforcement of one declaration that this file's conformance matrices exist to close.

The decision this needs

Not prescribing a remedy. At least three readings, and they shape a public contract:

1. Give the write seam a bound for them — add signature / qrcode to the record-validator's string branch, then move them into the TEXT family. Declared = enforced, and the data-URI defect goes away.
2. Treat them as string-family — declaredVarcharLength, i.e. varchar(maxLength) with TEXT above MAX_VARCHAR_CHARS. Honours a declared bound, but an undeclared signature still takes varchar(255) and still refuses a data URI.
3. Rule maxLength inapplicable to them (ADR-0049 enforce-or-remove) and refuse it at publish time — then TEXT is unambiguously correct and option 1's validator change is unnecessary.

secret and color sit in the same measurement and may or may not travel with the answer: secret persists an opaque sys_secret ref (ADR-0100) rather than the declared value, and color is short by construction — neither has the live refusal these two have.

Reproduce

• Write-seam table: validateRecord({ fields: { f: { type: T, maxLength: 64 } } }, { f: 'y'.repeat(100) }, 'insert') per type.
• Physical columns and refusals: packages/drivers/driver-sql/src/sql-driver-11794-richtext-text-family.test.ts with OS_TEST_POSTGRES_URL / OS_TEST_MYSQL_URL provisioned; its body_sig / body_qr are the controls.

---

Generated by Claude Code

[os-zhuang]

Triage: routed to the decision inbox (needs-user-decision + domain:engine, type Bug — the data-URI refusal at 255 chars is live on the published face, but every repair direction shapes a public contract, which is the manual floor). 四维分析(从业务角度):

① 项目长远合理性:#11794 立了不变量「进 TEXT 家族 = 写缝强制 maxLength」。选项 1(写缝加界 + 两类型入 TEXT)缩小特例、declared = enforced;选项 3(裁 maxLength 对这两类型不适用,发布期拒绝 + TEXT)同样闭合、但走 ADR-0049 退役流程;选项 2(varchar(maxLength))让「未声明界的 signature」继续在 255 被拒,且强制与否取决于是否恰好有索引 —— 加深同一声明的方言分叉,最差。
② 实际业务拉动:真实存在 —— field-zoo 自己就给 signature 写 data-URI PNG,在 PG(22001)与 MySQL(ER_DATA_TOO_LONG)双双实测被拒。签名/二维码是常见业务字段,这是用户今天就撞的已发布面缺陷。
③ 防 AI 写代码犯错:选项 1 的写缝响亮拒绝优于列上限静默截断;「maxLength 声明了却无人兑现」正是声明即须强制的反例 —— 今天 Field.signature({ maxLength: 64 }) 解析、发布、绑定为零。
④ 创业阶段不扩散需求:选项 1 只是把两个类型加进既有 string 分支,零新面;选项 3 义务更小(少两个可声明键)但要走退役流程。secret/color 不随裁 —— secret 存的是 sys_secret ref(ADR-0100),color 构造上就短。

推荐 1(写缝给 signature/qrcode 加 max_length 分支,然后按 #11794 的既定路线入 TEXT 家族);若维护者认为 maxLength 对这两类型本无意义,则 3。⛔ 不推荐 2。
置信缺口:存量部署里是否有作者真的声明过 signature/qrcode 的 maxLength(census 未跑);两类型入 TEXT 后对 #11374 keyed-and-bounded 规则的交互只在卡内推理、未实测。

<!-- os-decision-facets -->

---

Generated by Claude Code

[os-support-ai]

Maintainer ruling — option 1: the write seam enforces maxLength for signature / qrcode, then both join the TEXT family

Source: maintainer, 2026-08-25, live PM chat (decision-inbox batch 6 review, session session_01KWRU3s15AJz7PGW7a7wdCh), verbatim: 「其他同意」 — accepting the batch's presented recommendation for this card: option 1.

• signature and qrcode join validateRecord's max_length branch (declared bound refuses loudly at the write seam), and then move into the TEXT family under exactly the invariant driver-sql: richtext is emitted as varchar(255) while its markdown/html siblings get TEXT — a rich-text body is capped at 255 characters #11794 established — a TEXT column is permitted precisely because the seam enforces the declared bound. The live defect (a data-URI signature refused at 255 chars on both measured dialects) goes away; declared = enforced.
• Option 2 (varchar(maxLength)) is rejected as presented: an undeclared bound would still refuse at 255, and enforcement would depend on whether an index happens to key the column — dialect/shape-divergent enforcement of one declaration.
• Option 3 remains the recorded alternative if implementation shows maxLength genuinely meaningless for these types — but the ruling is 1; a flip to 3 would be a fork back, not a silent pivot.
• secret and color are explicitly not covered by this ruling (opaque ref per ADR-0100; short by construction).
• Interaction check carried from the card: verify against the driver-sql: the platform-objects schema does not sync onto MySQL — unbounded string fields become TEXT, which MySQL refuses to index #11374 keyed-and-bounded rule on the real matrices, and extend sql-driver-11794-richtext-text-family.test.ts's "STILL-OPEN half" cases into the closed shape.

Discipline: Clause-② yes (accept/reject behaviour changes in both directions: long values become storable, over-bound values become refused); CONTRACT_REVIEW_TIER.

State: needs-user-decision → pm:queue in the same write; domain:engine stands.

---

Generated by Claude Code

[os-warren]

Claim: PM loop (domain:engine seat)
Session: session_01W6HFzyH98W1YaQXhJUJt6o
Branch: claude/issue-11875-signature-qrcode-bounded-text-family
Worktree: objectstack-issue-11875
Domain: domain:engine
Container & model: M, mode:subagent, CONTRACT_REVIEW_TIER
Clause-②: yes — both limbs. The maintainer ruling already declared the declaration limb (accept/reject moves in both directions). The path limb fires too, for the reason below.

⚠️ The card's premise sentence is stale — read this before starting

The card states: "maxLength is a plain optional key on FieldSchema (field.zod.ts), admitted on every field type. So Field.signature({ maxLength: 64 }) parses, publishes, and binds nothing."

That was true when filed (2026-08-24). It is no longer true on origin/main. #11566/#11989 landed after it:

• packages/spec/src/data/field.zod.ts:123 — BOUNDED_STRING_FIELD_TYPES = text, textarea, email, url, phone, password, markdown, html, richtext, code. Neither signature nor qrcode is a member.
• packages/spec/src/data/field.zod.ts:1649 — a superRefine that refuses maxLength on any type outside that set.

So Field.signature({ maxLength: 64 }) is refused at the authoring seam today. The defect's shape has changed: it is no longer "a bound that binds nothing", it is "a bound that cannot be declared at all, on a type whose real values are routinely past 255".

⇒ Option 1 therefore requires a packages/spec/src/** edit (adding both types to the set), which is the clause ② path limb. Note the refusal message at :1655-1657 hand-enumerates the ten types in prose — a second copy of the same list that must move with it or it drifts on day one. This is the #12017 family; do not leave it inconsistent.

The live physical defect the card measured (data-URI signature refused at 255 on PG 22001 / MySQL ER_DATA_TOO_LONG) is unaffected by this and still stands — re-measure it, don't recall it.

Serial constraints cleared

Measured by symbol on origin/main (packages/drivers/driver-sql/src/sql-driver.ts, 15,248 lines):

• This card's band: 13275–13900 — declaredVarcharLength (:13321), keyableTextLength (:13330), varcharColumnChars (:13468), and the createColumn/alter call sites at :13536 :13773 :13864.
• ⛔ driver-sql: a declared field named id / created_at / updated_at is silently discarded by initObjects — declared type, length and constraints all ignored with no diagnostic #12015 is dispatched in parallel on the 8600–9130 band (builtinColumns at :8629 :8645 :9078 :9100 :9127). Do not touch it. If your change needs a line in that band, stop and report — that is a serial breach, not a merge to resolve.
• Second surface packages/objectql/src/validation/record-validator.ts (max_length at :557) — no other open PR touches it.
• ⚠️ Fence: PR feat(spec): declare the audit door and catch the delete request schema up — both meta-door casts retired #12003 is open on packages/spec/api-surface/api.json, authorable-surface/api.json, export-origins/api.json, json-schema.manifest/api.json. Adding members to a ReadonlySet<string> should not move any of them (membership is not in the type). If a regeneration does rewrite one of those four files, stop and report rather than landing a conflict against feat(spec): declare the audit door and catch the delete request schema up — both meta-door casts retired #12003.

Prior art to read first, not recall: #11876 landed — richtext/code are already in the TEXT family on main, so the card's "PR #11876 (open)" note is resolved.

---

Generated by Claude Code