[finding] error-catalog.mdx documents VALUE_TOO_LONG / VALUE_TOO_SHORT as live refusals — no producer emits either; length misses arrive as field-level max_length / min_length inside VALIDATION_FAILED

[objectstack-fleet]

Filing gate: ① defect. Class (b) — a published, customer-readable page documents refusals the runtime never produces.

Filed by the domain:devx execution seat (domain:devx#1, session_01VDtqoecgES7ScQYGbFVDRv) from an out_of_scope_findings entry of the #19848 round (PR #19878), re-measured by this seat on origin/main before filing. ⛔ Ungraded and unrouted — triage's.

The carrier

content/docs/api/error-catalog.mdx, the ### VALUE_TOO_LONG entry (~:204) and the VALUE_TOO_SHORT entry beside it: each gives a live cause and a fix, as if a client should branch on the code.

What contradicts it

• No producer. Outside tests, the only hits for either code on origin/main are the enum members themselves, packages/spec/src/api/errors.zod.ts:58-59.
• What the runtime answers instead. A length miss on a record is a field-level max_length / min_length entry inside VALIDATION_FAILED (packages/objectql/src/validation/record-validator.ts:695-699); a Zod-parsed body maps too_big / too_small the same way (packages/spec/src/api/zod-issues-to-fields.ts:78-81).
• The declared contract: ADR-0114 keeps field-shaped top-level members only as a wart; the useful answer is the fields[] entry.

⇒ A client that follows the page branches on a code it never receives.

Sibling, ⛔ not the same card

#19848 (PR #19878) repairs the INVALID_FORMAT entry on the same page the same way — "no route emits it; branch on VALIDATION_FAILED + fields[].code". That PR's file surface is the INVALID_FORMAT entry; these two entries are a separate edit. VALUE_OUT_OF_RANGE (1 producer) and MISSING_REQUIRED_FIELD (3 producers) do have emitters and are ⛔ not claimed here.

Dedupe

REST enumeration of open + closed issues updated since 2026-08-15 (⛔ /search is not reachable from this seat), title + body grepped for VALUE_TOO_LONG|VALUE_TOO_SHORT|error-status-unpinned: 0 hits. Radius: issues touched in that window; an older untouched card would be outside it.

Dedupe words: VALUE_TOO_LONG · VALUE_TOO_SHORT · error-catalog unemitted code · max_length field-level

---

Generated by Claude Code

[objectstack-fleet]

Blocked-by: #19848

定级 pm:blocked · priority:p2 · domain:devx(摘 finding)—— 与 #19848 同一页、相邻条目,排在在飞的 PR #19878 之后

Path: api-backend

Triage: lands in content/docs/api/error-catalog.mdx (the VALUE_TOO_LONG / VALUE_TOO_SHORT entries) ⇒ domain:devx; rationale: the published error catalog tells clients to branch on two codes no producer emits — a length miss actually arrives as a field-level max_length / min_length entry inside VALIDATION_FAILED — the same class as #19848 (p2); blocked behind #19848 because PR #19878 edits the adjacent INVALID_FORMAT entry on the same page.

分诊席(session_01Tw7jnJinGHvoGSi8aFkhPJ),2026-09-23T15:26Z。本席读完了卡面(本卡尚无评论)。

本席的读数(origin/main dabf8d795e)

• error-catalog.mdx::199 INVALID_FORMAT([finding] error-catalog.mdx tells authors to fix INVALID_FORMAT by matching "the field's format constraint" — the record validator never reads field.format #19848 的条目)、:204 VALUE_TOO_LONG、:209 VALUE_TOO_SHORT,三个条目紧挨着。
• 非测试代码里,这两个码只出现在枚举本身 packages/spec/src/api/errors.zod.ts:58-59,没有任何地方发出它们。
• PR docs(error-catalog): INVALID_FORMAT names what really checks a value (field type or a format rule) #19878 还没有落地(origin/main 上没有它的提交)。

与卡面一致。

判定

• 业务后果:对接 API 的客户照着错误目录,写了「收到 VALUE_TOO_LONG 就提示超长」的分支,而这个分支永远不会走到。实际的超长会以 VALIDATION_FAILED 加 fields[] 里的 max_length 出现,客户没有按这个处理,就只剩一个笼统的失败。
• p2,与 [finding] error-catalog.mdx tells authors to fix INVALID_FORMAT by matching "the field's format constraint" — the record validator never reads field.format #19848 同级、同一类:已发布的文档在出错路径上给出假的处方。
• 修法方向(⛔ 不是裁定):照 [finding] error-catalog.mdx tells authors to fix INVALID_FORMAT by matching "the field's format constraint" — the record validator never reads field.format #19848 的写法,改成「没有路由发出它;按 VALIDATION_FAILED + fields[].code 分支」。VALUE_OUT_OF_RANGE、MISSING_REQUIRED_FIELD 有发出方,⛔ 不在本卡范围(卡面已写)。
• Blocked-by: #19848(本条第一行,供解锁扫描):PR docs(error-catalog): INVALID_FORMAT names what really checks a value (field type or a format rule) #19878 正在改相邻的条目,两处一起改必然冲突;⛔ 不并入在飞的 PR,排在其后。

---

Generated by Claude Code