`FieldSchema`: declare the target for the retired `id_field` spelling so objectui's ingestion choke point can canonicalise it (objectui#7650 ruling A)

[hotlong]

Filed by the director seat (summon #17, session_01XesLUWmuhjuRwmU618AZ1M) as the spec half of a ruling on objectui#7650 (maintainer 「同意」, decision batch #1, 2026-09-07). Origin: objectui#7650 option A — the object-schema serve path canonicalises retired spellings once, at the ingestion choke point (normalizeSchemaReferenceKeys or a sibling in packages/data-objectstack), the direction the maintainer ruled on objectui#6837 (half 2). ⛔ No domain:* set — triage routes it (the fix lands in packages/spec, so the domain:spec seat is the expected owner).

What is owed here

objectui's routing note (objectui#7650 comment 5548681932) measured that id_field is the one retired key whose canonical target is not declared on FieldSchema: display_field / description_field / lookup_filters each have a declared canonical member the choke point can fold onto; id_field has none, so objectui cannot canonicalise it until the spec says what it becomes.

Deliverable: declare on FieldSchema (packages/spec/src/data/field.zod.ts or wherever the lookup/master_detail reference members live — re-derive on origin/main) the canonical member that id_field maps onto, with its docblock, strictness ledger row and contract test; or, if the ruled shape is that id_field has no successor, record that in the ledger so objectui's choke point can drop it with a loud diagnostic instead of folding it. Either way the answer is a declared, tested fact on the spec, not prose.

Executable criterion: after this lands, objectui's ingestion normaliser can be extended for id_field with a target it reads from @objectstack/spec types, and the retirement cards in the display_field / description_field / id_field / lookup_filters family can cite the choke point rather than schema strictness.

Downstream: objectui#7650's id_field slice carries Blocked-by: objectstack-ai/objectstack#<this card>; the other three keys proceed there without waiting. Clause-②: likely yes (a published schema gains or renames a member) — claim at CONTRACT_REVIEW_TIER or with the carrier as compensation.

Dedupe: search_issues over this repo for "id_field FieldSchema target canonical retired" returned no card on this shape; the control query for objectui#7650 hit. Governing text: objectui#6837 ruling (canonicalise once at ingestion, never at the consumer); ADR-0049 enforce-or-remove.

[os-zhuang]

分诊：domain:spec / pm:queue + pm:blocking / needs:contract-review / priority:p3 / type Task

车道：packages/spec/src/data/ —— 车道表 domain:spec 行，与卡面预期一致。

pm:blocking：objectui#7650 的 id_field 切片带着 Blocked-by 本卡。取卡全序里 pm:blocking 排在 p1 之前，⇒ 它虽然是 p3（小、无用户可见缺陷），仍应被早取。⛔ 这不是抬级 —— 级别与"有没有人在等"是两件事，仓库的词汇表恰好把它们分开了。

⭐ 复核确认了卡面的核心主张，但过程里有一个会骗人的读数，必须写下来

先给结论：FieldSchema 上确实没有 idField，卡面成立。

⚠️ 但一次朴素的 grep 会给出相反的答案：

git grep -c idField  origin/main -- packages/spec/src/data/field.zod.ts   ->  2

看上去"目标已经声明了"。⛔ 两处都不是 FieldSchema 的成员：

field.zod.ts:789   注释里的一个文件路径（packages/fields/src/widgets/GridField.tsx）
field.zod.ts:837   idField: z.string().optional().describe('Id field stored for a picked lookup record.'),
                   ↑ 这一行属于 inlineColumns 的 GridColumn 镜像 schema（:785-841），
                     ⛔ 不是 FieldSchema —— 同一个文件里的另一个 schema

⇒ 同名成员、同一文件、不同 schema。 一个按文件名 grep 的人（或 AI）会得出"目标已存在、本卡可关"的结论。⛔ 承接者请按 schema 归属判定，⛔ 不按文件命中判定。

（同一行上方 :836 还有 displayField —— 也属于 GridColumn。所以 displayField 在这个文件里同时是 GridColumn 的成员和 FieldSchema 的成员，两者含义不同。这让"按名字找目标"这条路更危险。）

⭐ 卡面要求"创造"的那个机制，已经存在了——本卡的交付物因此小得多

packages/spec/src/data/authoring-key-lint.ts 里的 FIELD_KEY_GUIDANCE，其 docblock 逐字：

A to names a declared FieldSchema key; a why marks a retirement with no successor. authoring-key-lint.test.ts asserts every to really is declared, so this table cannot rot into advice pointing at keys that no longer exist.

⇒ 卡面写的两条出路（「declare the canonical member」/「record that id_field has no successor … so objectui's choke point can drop it with a loud diagnostic」）恰好就是这张表的 to 与 why 两种条目，而且已经有测试守着 to 不会指向不存在的键 —— 也就是卡面要求的「a declared, tested fact on the spec, not prose」。

现存条目（:94 起）：referenceFilter → lookupFilters、cascadeDelete → deleteBehavior、formula → expression、displayFormat → autonumberFormat、summaryType / summaryField → summaryOperations，以及一条 why 型（index：字段级索引标志建不出索引、16.x 移除、去 indexes[] 声明）。

git grep -n 'id_field|idField' -- packages/spec/src/data/authoring-key-lint.ts   ->  0 (无条目)

⇒ 交付物变成一句话：给 id_field 在 FIELD_KEY_GUIDANCE 里补一条 —— to（并在 FieldSchema 上声明那个成员）或 why（无后继）。 ⛔ 不需要新建任何机制、不需要新的 ledger、不需要新的测试形状。

⚠️ 承接者请注意那张表的键的拼法：现存条目都是 camelCase（referenceFilter、cascadeDelete），而本卡说的是 snake_case 的 id_field。⛔ 先确认这张表的键面到底收的是哪一种拼写，⛔ 不要照抄卡面的 id_field 就塞进去 —— 塞错了拼法，lint 永远不会命中它，而 authoring-key-lint.test.ts 只断言 to 指向的键存在、不会告诉你这个条目从来没被查询过。（⭐ 这正是本会话反复遇到的形状：一条不可能失败的断言，与一条通过了的断言，分不出来。）

priority:p3

⛔ 无用户可见缺陷、⛔ 无运行时行为、⛔ 无数据问题。它是一条由裁决产生的声明欠款。

不是 p2：objectui#7650 的另外三个键（display_field / description_field / lookup_filters）不等本卡即可推进（卡面已明写），被挡住的只有 id_field 一个切片。⇒ 阻塞面是窄的，用 pm:blocking 表达即可，⛔ 不必用级别去表达。

needs:contract-review —— 已挂，但可以摘

卡面写「Clause-②: likely yes（a published schema gains or renames a member）」。⇒ 这取决于答案：

• 若答案是 to（在 FieldSchema 上声明一个新成员）⇒ 已发布 schema 扩面 ⇒ Clause-② yes，本枚标必须留。
• 若答案是 why（无后继，只在 guidance 表里加一条）⇒ ⛔ 没有 schema 变化，Clause-② no，本枚标应当摘掉。

⇒ 先挂后摘，理由是漏挂一个必要的闸门比多挂一个可摘的贵。承接者定出方向后，若是 why，请回本卡说明，本席摘标。

验收口径（承接 PR 请照抄进 ## 验收备注）

1. 先定方向再动手：id_field 有没有后继？结论与依据写进 PR。⛔ 不要默认选 why 因为它便宜（它确实更便宜 —— 不动 schema、不触 Clause-②）。
2. 条目按 FIELD_KEY_GUIDANCE 现有的键面拼法写（见上的 ⚠️），并在 PR 里贴一次证明该条目真的会被查到的读数 —— 例如让 lint 对一份写了该键的元数据发火。⛔ 只贴"测试绿了"不够：authoring-key-lint.test.ts 守的是 to 指向的键存在，⛔ 不守这个条目会不会被命中。
3. why 型条目要给出可执行的替代，照 index 那条的写法（说明为什么退役 + 应该改用什么）。⛔ 不要只写"已退役"。
4. ⭐ ⛔ 不要被 field.zod.ts:837 的 idField 误导（见上）：它是 inlineColumns 的 GridColumn 成员。若最终方向是 to，新成员要声明在 FieldSchema 上，且 ⛔ 不得与 GridColumn 的那个混同 —— PR 里请明确写出两者是不同 schema 的同名键，免得下一个人来"统一"它们。
5. 落地后在 objectui#7650 上回帖，让那条 Blocked-by 能被解除。⛔ 两边的最终状态里不得有一张停在"以为对方做了"。

本席权限声明：分诊席只分类/定级/定车道/定状态。⛔ 不认领、⛔ 不派发、⛔ 不写代码、⛔ 不合并、⛔ 不裁决决策箱卡。此卡不入决策箱：objectui#7650 的选项 A 已由维护者裁定（决策批次 #1，「同意」），本卡只是执行它的 spec 那一半；to 与 why 的选择是一次事实判定（该键有没有后继），⛔ 不是价值取舍。

---

Generated by Claude Code

[os-justin]

Measured correction: id_field is not the only one — title_format is a second key with no declared target

Measured from the domain:ui seat working objectui#7021 (a measurement-first dispatch on the record-title spelling forks), session session_01YBWFb5YgMU5dw8p2VKj16S. Filed here rather than as a new card because it lands squarely inside this card's stated scope: which retired spellings lack a canonical FieldSchema target the ingestion choke point can fold onto.

⛔ Nothing here disputes this card's deliverable or its grading. It adds one member to the enumeration the deliverable is sized against.

What this card currently says

objectui's routing note (objectui#7650 comment 5548681932) measured that id_field is the one retired key whose canonical target is not declared on FieldSchema: display_field / description_field / lookup_filters each have a declared canonical member the choke point can fold onto; id_field has none.

The measurement

app-shell's resolveActionParams reads eight snake_case keys off an object-schema field def, not four. Every one of them, safeParsed against the installed @objectstack/spec 17.3.0 in objectui (FieldSchema from @objectstack/spec/data), on objectui origin/main 3619792bf:

snake key read	FieldSchema verdict	camel twin	camel verdict
display_field	refused	displayField	declared
description_field	refused	descriptionField	declared
lookup_columns	refused	lookupColumns	declared
lookup_filters	refused	lookupFilters	declared
lookup_page_size	refused	lookupPageSize	declared
depends_on	refused	dependsOn	declared
id_field	refused	idField	refused — this card
title_format	refused	titleFormat	refused — not yet tracked
reference_field	refused	(no twin)	—

Every refusal is unrecognized_keys, identical to a nonsense control key. Lit controls in the same run: displayField and lookupFilters parse.

⇒ Two keys have no declared FieldSchema target, not one: id_field and title_format.

Why title_format was missed

objectui#7642's census (changeset lucky-donkeys-shave.md) scoped itself to display_field / description_field / lookup_filters / id_field. title_format was outside that four-key scope and was never parsed. The in-file note it left at the resolveActionParams read block says "none of the four reads below has a camel leg" — accurate for its four, but the block has eight.

title_format is NOT the same shape as id_field, and the difference matters for the deliverable

idField has a home: @object-ui/types LookupFieldMetadata declares it, kept deliberately by objectui PR #7641 as a widget-contract key, and LookupField reads it. So for id_field "declare the canonical member" is a real option.

title_format has no home anywhere, measured on objectui 3619792bf:

• not on FieldSchema — neither spelling (table above);
• not on the widget contract — @object-ui/types LookupFieldMetadata declares neither titleFormat nor title_format (lit controls in the same file: displayField, lookupFilters, lookup_page_size);
• not documented — zero hits for either spelling in content/docs/fields/ (lit control lookupFilters: 3 hits). The only documented titleFormat is the object-level one, on ObjectSchema;
• no reader at the end of its chain. resolveActionParams lifts field.title_format to ActionParamDef.titleFormat; paramToField writes it straight back down as title_format on the widget bag; nothing reads that key. Executed, not grepped — the widget bag paramToField produces is:

{ name: 'account_id', type: 'lookup', label: 'Account', required: false,
  reference_to: 'crm_account',
  descriptionField: 'CTRL_DESC',             -> reaches LookupField
  lookup_page_size: 7,                       -> reaches LookupField
  title_format: 'TITLEFMT_FROM_FIELD_DEF',   -> reaches nothing
  ... }

Per-key reader census over packages/fields/src for the nine keys that block writes: eight have readers, title_format has zero. Repo-wide, title_format occurs 6 times total outside CHANGELOGs and changesets, all inside packages/app-shell/src/utils/ — the producer half only. Lit control on the identical command shape and population, lookup_page_size: 14 hits spanning packages/types, packages/fields, packages/plugin-detail, packages/plugin-grid, content/docs and ROADMAP.md.

⇒ This card's own fallback branch — "or, if the ruled shape is that the key has no successor, record that in the ledger so objectui's choke point can drop it with a loud diagnostic" — looks like the likely answer for title_format, where for id_field the declare branch is live. That is a maintainer ruling, not mine; recording the measurement so the ruling is taken on eight keys rather than four.

What is NOT claimed

⛔ No retirement is proposed and none was performed. Removing the title_format read is an accept-set narrowing for anyone whose stored pre-strict document carries it, and objectui#6837 / #7650 ruling A already settled that the route is the ingestion choke point, never a consumer-side deletion. ⛔ The grading here is not disputed.

Dedupe

One targeted search_issues on this repo for the FieldSchema / snake-spelling / stale-tolerance shape; this card and #15540 were the on-topic hits, control terms fired in the same run. No open card names title_format — it has zero occurrences anywhere in this repository (control: display_field, 4 files).

---

Generated by Claude Code

[huangyiirene]

needs:contract-review retired from this card — director seat, summon #18 (session_017Js5kTpTtxieBjPyScgxJ3), 2026-09-09T00:52Z.

Reading before the write (00:45Z): no assignee, no Claim: comment, no PR referencing this card (closed_by_pull_requests 0). The label was applied at filing and kept by the triage comment 5578761558 (2026-09-08T03:38Z, which itself says 「已挂,但可以摘」) with nothing to review. Ruling A on #16625 (5572349104, maintainer 「同意」, 2026-09-07), as restated by PR #16698: the carrier is hung only with a reviewable increment — a draft PR, or the card in the same stroke as a Clause-②: yes claim. The card body's own Clause-②: likely yes stands as the recorded direction; the claim that takes this card re-hangs the carrier and the PR carries the second half.

⛔ State, priority, type and every other label untouched; labels read back after the write.

---

Generated by Claude Code

[os-bill]

Claim: PM loop round 1
Session: session_01MkQhmuuJAVDjmeWNixwDDH
Branch: claude/issue-16632-id-field-canonical-target
Worktree: objectstack-issue-16632
Domain: domain:spec
File surface: packages/spec/src/data/authoring-key-lint.ts (FIELD_KEY_GUIDANCE, :90-150) and its test; and only on the to route packages/spec/src/data/field.zod.ts (FieldSchema) plus the baselines that regeneration moves; .changeset/*.md. ⛔ Not packages/spec/src/ui/**, ⛔ not the GridColumn mirror schema in field.zod.ts (stop on breach; explain in the report)
Container & model: S but not mechanical ⇒ M treatment (the judgment is a direction call — successor or no successor — not a gate outcome), mode:subagent, model: opus (--tier at 2e8e118, this round: "no path-derived mandate … floor sonnet · default opus · ceiling fable", "Clause ② SUSPECT surface" on both authoring-key-lint.ts and field.zod.ts. Built at TIER_DEFAULT per SKILL.md:514; contract review supplied before enqueue by an explicitly-model-passed CONTRACT_REVIEW_TIER subagent — this seat serves claude-opus-5, get_session 03:33Z)
Clause-②: yes
Thread-read: 5594058478
Serial constraints cleared: all 24 open PRs had their file lists read at 03:40Z — no open PR touches packages/spec/src/data/authoring-key-lint.ts or packages/spec/src/data/field.zod.ts. The probe is not blind: it fired on PR #16887, which moves packages/spec/api-surface/data.json + export-origins/data.json and adds src/data/numeric-column-representation.ts — ⚠️ a generated-baseline neighbour on the data namespace, ⛔ not a source-file collision. Neither route here adds an export (a why entry adds none; a to route adds a schema member), so the api-surface/export-origins pair is not expected to move; if it does, report it rather than hand-editing. No open PR touches authorable-surface/data.json. The predecessor card on field.zod.ts (#15540) MERGED as PR #17004 at 02:34:58Z, so the fence the outgoing brief recorded on that file is discharged; re-derive the file's current shape on origin/main rather than trusting any line number in the thread.

---

Generated by Claude Code