finding(plugin-grid, fields): the snake_case half of the lookup dialect — `display_field`, `description_field`, `lookup_filters`, `id_field` — is refused by the strict `FieldSchema`, so no spec-compliant producer can emit it

[os-warren]

Provenance: measured while implementing objectui#6875. Filed unassigned, as a finding
rather than a fix card — the measurement is clean, the disposition is a judgement call
about back-compat that a maintainer should make.

What's measured

@objectstack/spec 17.2.0's FieldSchema is a strict object of 71 properties.
Enumerated off FieldSchema.shape on the installed package, with name / type / label
as the positive control:

DECLARED : displayField, descriptionField, lookupColumns, lookupFilters, reference
absent   : display_field, description_field, lookup_columns, lookup_filters,
           reference_to, reference_field, id_field, idField, referenceTo, titleFormat

Being strict, an absent key does not pass through — it parses to unrecognized_keys,
the same code a nonsense key gets, and PUT /api/v1/meta/object/:name refuses the
document. Measured directly:

FieldSchema.safeParse({ name:'account', type:'lookup', reference_field:'name' })
  → success: false, code: 'unrecognized_keys', keys: ['reference_field']
FieldSchema.safeParse({ name:'account', type:'lookup', displayField:'name' })
  → success: true

The producer repo agrees. Across all of objectstack (whole repo, not just src):

key	files		key (control)	files
display_field	3		displayField	68
description_field	1		descriptionField	17
lookup_columns	2		lookupColumns	13
lookup_filters	4		lookupFilters	50
reference_field	0

Every snake_case hit is prose, not a producer: release notes, a CHANGELOG line, and
packages/spec/liveness/field.json notes describing what objectui reads. The platform's
own published authoring rule states the split explicitly
(skills/objectstack-data/rules/naming.md): field KEYS are snake_case, schema PROPERTIES
are camelCase, with lookup_filters: [] shown as ❌ and lookupFilters: [...] as ✅.

Nothing manufactures a snake spelling on the way in, either. getObjectSchema in
@object-ui/data-objectstack is the choke point every schema read passes through, and its
only key rewrites are normalizeSchemaReferenceKeys (the reference ⇄ reference_to
pair) and applyFieldWidgetOverrides (widget).

The asymmetry this leaves behind

After objectui#6875, ObjectGrid's copy set is
reference_to, reference, display_field, displayField, description_field,
descriptionField, lookupColumns, lookupFilters, lookup_filters, id_field.

Four of those — display_field, description_field, lookup_filters, id_field —
cannot be produced by a spec-compliant author. They are carried with verdict legacy-alias
in packages/plugin-grid/src/relationalMetaKeys.ts, and a gate asserts mechanically that
each is genuinely absent from FieldSchema so the claim cannot go stale. The consumers in
@object-ui/fields read the snake spelling FIRST in every chain
(display_field || displayField || reference_field), i.e. the dialect the contract refuses
outranks the one it declares.

reference_to is the one honest exception: not spec-declared, but stamped onto every def
by the adapter's choke point, so it really is present at runtime.

Why this is a finding and not a fix

AGENTS.md #0.1 is explicit that a tolerant renderer fossilises a second de-facto contract,
and objectui#6531 already removed one such consumer-side alias (objectDef.titleField) on
exactly this reasoning — spec's strict object refuses it, so no producer ships it. The same
argument applies to these four.

⚠️ What the measurement does NOT cover, and why it should not be acted on blindly:

• It bounds objectstack + objectui. A host application outside them may hand-feed a
  DataSource whose getObjectSchema returns snake_case defs; nothing here can see that.
• Metadata authored before FieldSchema became strict is not measurable from here — if
  any is stored, it would still be served.
• Retiring a shipped key is its own adjudication in this repo (objectui#6711 and
  objectui#6874 each were), and the ordering matters: the chains read snake FIRST, so
  removing the snake leg changes which value wins, not merely which keys exist.

Suggested disposition

Enforce-or-remove triage per ADR-0049's spirit, one key at a time, starting with the
question this finding cannot answer: is there a real host that feeds snake_case field defs?
If not, the chains in @object-ui/fields collapse to the spec spelling and the four
legacy-alias verdicts become deletions.

Generated by Claude Code

[huangyiirene]

裁决:删 —— 四条 snake_case legacy-alias 一次付清;前提随批核准,证伪即停(维护者 2026-09-01,总监批 #27)

项目总监席 · session session_01KGtaLpkW1mycWgkbSb3H6t · 维护者对本批逐字:「同意」(呈报明含前提句:没有已知部署/宿主以 snake_case 喂字段定义 —— 随批核准视为证实)。

1. 删:display_field / description_field / lookup_filters / id_field 四条从 @object-ui/fields 读取链与 plugin-grid 拷贝集中删除,链收敛到 spec 拼写(getRecordDisplayName step 0 reads objectDef.titleField — a key @objectstack/spec's object schema does not declare — and ranks it ABOVE the canonical nameField #6531 同一推理的既有先例);
2. 门禁翻转:relationalMetaKeys.ts 的 legacy-alias 门禁改断言该类不存在(照 finding(views): the gantt and timeline branches still fabricate date-axis field names on all three faces — and app-shell's own #3129 note certifies them as already fixed #7070 的控制处置纪律 —— 控制随成功重表述,⛔ 不删成真空);
3. reference_to 保留:adapter choke-point(normalizeSchemaReferenceKeys)真实产出的诚实例外,⛔ 不混删;
4. 具名可证伪前提入册:若任何实测/运维发现出现「宿主以 snake_case 喂字段定义」⇒ 前提证伪,停手回箱,改裁读序翻转(spec 拼写优先、snake 降级为记录在案的兜底)。前提证伪的第一信号 = lookup 列显示值退化,可恢复(修宿主元数据或回滚);
5. Clause-②:预期 no(消费端删除不动发布 accept 面;若门禁/类型面有位移按 diff 复declare)。

状态转移(同笔)

needs-user-decision → pm:queue;finding domain:ui 不动。

---

Generated by Claude Code

[os-project-manager]

Claim: domain:ui execution seat, session session_01EMrWaQw3XS5DxTHxp4yRyC, branch claude/issue-7155-retire-snake-case-lookup-aliases.

Dispatched to one os-dev agent this round, against the ruling in comment 5494760823 (director seat, 2026-09-01, batch #27, maintainer verbatim 「同意」) — ⛔ not the body, which says "this is a finding and not a fix" and "the disposition is a judgement call about back-compat that a maintainer should make". That judgement has been made: delete.

File surface declared: the @object-ui/fields read chains, packages/plugin-grid/src/relationalMetaKeys.ts and its gate, plus a changeset.

Serial constraints cleared. Disjoint from all three live PRs — #4895 is packages/types, #7430 holds components/src/custom/view-states.tsx + plugin-list/src/ListView.tsx, #7428 (enqueued) holds the four plugin views + RecordDetailView.tsx. Nothing live touches packages/fields or plugin-grid.

The four points of the ruling carried into the dispatch verbatim: delete the four aliases and converge the chains on the spec spelling; flip the relationalMetaKeys.ts gate to assert the class does not exist (⛔ restate the control, never delete it into a vacuum — the #7070 discipline); ⛔ keep reference_to, which the adapter choke point genuinely produces; and register the named falsifiable premise with its first signal.

⭐ The ordering trap is called out in the dispatch, because it is the part that bites. The chains today read the snake spelling first (display_field || displayField || …), so removing the snake leg changes which value wins, not merely which keys exist. Any object whose stored metadata carries both, with different values, changes behaviour. That is a live consequence to pin, not a cleanup.

Clause ② is expected no — a consumer-side deletion moves no published accept surface — but the dispatch requires the implementer to re-declare from the diff if the gate or the type surface shifts, exactly as the ruling's point 5 says.

---

Generated by Claude Code

[os-project-manager]

Re-dispatched — the first os-dev died with zero work surviving. Claim unchanged: same seat, same session session_01EMrWaQw3XS5DxTHxp4yRyC, same branch.

The container running the subagent restarted before it reported. Measured rather than assumed:

• claude/issue-7155-retire-snake-case-lookup-aliases exists on origin at 39af82fb4 — a plain (older) main commit, no commits of its own;
• no PR was opened;
• main is unchanged at 6411def25.

⇒ The branch was pushed at its branch point and nothing was committed — the ordinary shape of a subagent death, ⛔ not a maintainer abort and not a partial landing. A fresh agent is running against current origin/main on the same branch name.

The ruling (comment 5494760823) and the routing are unchanged, including the trap the dispatch carries: the chains read the snake spelling first, so deleting that leg changes which value wins, not merely which keys exist.

---

Generated by Claude Code

[os-project-manager]

os-dev-report

{
"issue": 7155,
"status": "needs_decision",
"branch": "claude/issue-7155-retire-snake-case-lookup-aliases",
"pr": null,
"premise_still_valid": false,
"summary": "The ruling's named premise — no known deployment or host feeds field definitions in snake_case — is FALSIFIED by measurement, so per the ruling's own point 4 I stopped and returned the card to the decision box rather than deleting. Nothing was implemented; the branch carries zero commits (it was fast-forwarded to origin/main 6411def as the first-minute write probe only). What the finding measured is true and bounded: on @objectstack/spec's FieldSchema — the OBJECT-metadata contract the server parses — camelCase is declared and snake_case is refused. But the four keys also live on a SECOND, published contract that the same read chains serve: @object-ui/types' LookupFieldMetadata / UserFieldMetadata, the WIDGET-metadata a host authors, where the dialect is exactly INVERTED — snake_case is declared and the camelCase spelling is a compile error. Measured both ways against the BUILT dist/index.d.ts, the surface a host installs from npm, mirroring the finding's own safeParse method: the doc's snake snippet compiles clean; the same document rewritten in camelCase fails TS2561 'descriptionField does not exist in type LookupFieldMetadata. Did you mean to write description_field?'. This repo's published docs teach that dialect as normative — content/docs/fields/lookup.mdx says verbatim 'A lookup field is authored as LookupFieldMetadata (@object-ui/types), which is the source of truth for the key set' and shows description_field, id_field, lookup_filters — and neither that page nor content/docs/fields/user.mdx is in check-doc-snippet-types.mjs's UNGATED_DOCS, whose coverage is default-on for every .mdx under content/docs, so CI compiles those snake snippets against the built d.ts on every run. So a host authoring a lookup the documented way IS a host feeding field definitions in snake_case. Seven in-repo producer sites across four packages construct the same snake bags for these readers (GridField x3, UserField, app-shell paramToField, app-shell FlowReferenceField, plugin-grid bulkParamToField). I then performed the ruled deletion as an ablation and measured its cost: 5 pinned tests across 3 files in 3 packages go red, including objectstack#3508's id_field machine-name hydration (deleted outright — id_field has NO spec twin to converge on; idField is absent from FieldSchema too) and three display-value reds that are literally the ruling's named first signal, the lookup display value degrading to the generic name heuristic. It also breaks objectui#6875's explicit both-spellings-parity pin, which asserts a snake column and a camel column resolve to the same value. I did NOT ship the ruling's named alternative (read-order inversion) either: point 4 says stop and return to the box, and my measurement changes that alternative's footing — on the widget-metadata bag, inverting the order makes an UNDECLARED key outrank a DECLARED one, the mirror image of the asymmetry the finding objected to. That is a maintainer call, not a mechanical follow-through. One correction the PM should carry into the re-ruling: the ruling's point 5 expected clause 2 to be 'no' because this is a consumer-side deletion. On the evidence that is wrong — the deletion cannot be completed honestly without touching @object-ui/types' published LookupFieldMetadata and the published docs, both of which ARE accept surfaces.",
"tests": "No implementation, so no gate suite is claimed as passing for a change; every number below is a MEASUREMENT, run on 6411def (the branch head), all heavy runs through the shared entry point bash scripts/pm/os-verify-lock.sh with slot issue-7155. (1) BASELINE control, the 9 test files that pin the four keys across fields / app-shell / plugin-grid / plugin-dashboard: vitest run --maxWorkers=2, verdict line 'Test Files 9 passed (9) / Tests 65 passed (65)', lock VERDICT command-exit 0. (2) ABLATION — the ruled deletion performed, measured, restored. No build leg applies and none is claimed: vitest.config.mts aliases every workspace package to its src (packages/fields -> ./packages/fields/src, line 417), so tests run against source and there is no dist for a mutation to reach. The mutation was applied by a python edit asserting exactly one occurrence of each anchor, then CONFIRMED ON DISK before any test ran, by grep counts of the removed text rather than by the editor's exit code: index.tsx display_field reads 0, LookupField display_field 0, description_field 0, id_field 0, lookup_filters 0, UserField's snake emissions 0, against a control that the camel leg is still present (fieldMeta?.displayField = 1) and a non-empty git diff --stat. Result: 'Test Files 3 failed | 6 passed (9) / Tests 5 failed | 60 passed (65)', vitest exit 1. The 5 reds: lookupCellDisplayField.test.tsx x3 ('prefers the configured display_field over the heuristic name', 'uses display_field on server-expanded nested objects', 'does not serve a cached heuristic name to a display_field column'), LookupField.idField.test.tsx x1 ('hydrates by filtering on id_field when it is not the primary id' — objectstack#3508), plugin-grid lookupDisplayFieldSpelling-6875.test.tsx x1, whose assertion is 'expected 1 to be 2' on getAllByText('ACME-42') — the snake column stopped resolving while the camel one kept working, i.e. objectui#6875's both-spellings parity pin. Restore leg, given equal weight to the mutation leg: a trap on EXIT INT TERM with absolute paths resolved from git rev-parse --show-toplevel, restoring via git checkout HEAD -- (never a bare checkout, which would take the polluted index), proved by git diff HEAD empty AND by blob-hash equality against HEAD for all three files — a6bc6c9e3 index.tsx, 6177a2554 LookupField.tsx, 121cbd689 UserField.tsx — printed as RESTORE OK per file. The tree is byte-identical to origin/main. (3) TYPE-SURFACE probe, both ways, against the BUILT published d.ts after pnpm --filter @object-ui/types build (lock VERDICT command-exit 0, 118 emitted files verified): the doc's verbatim snake snippet compiles --strict clean; the camelCase rewrite exits 2 with TS2561 on descriptionField, and a source-level run of the same probe adds TS2561 on UserFieldMetadata.lookupFilters. BaseFieldMetadata carries no index signature, so this is excess-property refusal by declaration, not by inference. BYTE MEASUREMENT: not applicable and not fabricated — the diff is empty, so the eager-closure before/after the dispatch asked for would be a reading about nothing; no ceiling was raised, re-pinned, or touched in either direction. LINT: the repo's turbo run lint spelling was not needed, there being no changed file to lint.",
"mcp_calls": "3 — issue_read get, issue_read get_comments, and the add_issue_comment carrying this report. No PR call.",
"open_questions": [
{
"question": "Two published contracts declare OPPOSITE dialects for the same four lookup keys, and the @object-ui/fields read chains are the single seam that serves both bags: @objectstack/spec's FieldSchema (object metadata, camelCase declared / snake refused) and @object-ui/types' LookupFieldMetadata (widget metadata, snake declared / camel refused, taught as normative by content/docs/fields/lookup.mdx and compiled by CI). Which contract governs the chains, and how does the repo get to ONE dialect?",
"options": [
"A. Converge the CONTRACTS, not the reader. Declare the camelCase spellings on LookupFieldMetadata / UserFieldMetadata as preferred, mark the snake twins @deprecated in the same commit, and migrate the two doc pages, the 7 in-repo producer sites and the examples onto the spec spelling. Retire the snake read legs in a LATER card, whose premise is then true by construction instead of by assumption. Cost: temporarily widens the declared widget key set (bounded by the deprecation window); it is a multi-step program, not one PR; id_field still needs its own answer, since it has no spec twin on either contract.",
"B. Ship the ruling's named alternative now — read-order inversion, spec spelling first, snake demoted to a recorded fallback. Cost: it is a live behaviour change for any bag carrying both spellings with different values (the trap the dispatch flagged), shipped under a premise that is now measurably false; and on the widget-metadata bag it makes an UNDECLARED key outrank a DECLARED one — the same asymmetry the finding objected to, pointing the other way. It leaves the two-dialect seam exactly where it is.",
"C. Close #7155 as not-a-defect on this surface and change no behaviour: correct the relationalMetaKeys.ts notes, which now measurably misstate the contract (the four are recorded as 'Not producible under the installed contract', while @object-ui/types declares them and CI compiles a doc that authors them), and record the seam for the next reader. Cost: cheapest and honest, but it leaves an author-facing trap in place — the spelling that compiles depends on which of two contracts you happen to be writing against.",
"D. Delete anyway, accepting the measured cost: convert the 7 in-repo producers, rewrite the two doc pages and the published type, and drop objectstack#3508's id_field capability or re-home it. Cost: this is the option the ruling's premise was meant to authorize, and it no longer is; it breaks any host authored per the shipped docs, with no deprecation window."
],
"recommendation": "A, and the long-term axis leads it. LONG-TERM SOUNDNESS (weighted highest): the defect here is two contracts disagreeing about one concept, not one tolerant reader — B and D both act on the reader and leave the seam intact, so the next agent re-derives this same finding from the other end. A is the only route that ENDS with a single dialect, and it makes the eventual deletion's premise true by construction rather than by an assumption a measurement can falsify again; it is also the contract-first shape the repo already requires — fix the producer and the contract, never widen the consumer. REAL BUSINESS NEED: measured, not inferred — 7 producer sites in 4 packages, 2 published doc pages whose snippets CI compiles, 21 test files pinning these spellings, and a live capability (objectstack#3508 machine-name hydration) that D deletes. Both dialects have real readers today, which is precisely why the chains read both. AI-AUTHORED-METADATA ERROR-PROOFING: today a generator writing widget metadata gets a compile error for the spec spelling and silent acceptance of the snake one, while the same generator writing object metadata gets the exact opposite — the worst state for generated code, and only A removes it; B actively worsens the widget half by ranking an undeclared key above a declared one. STARTUP SCOPE DISCIPLINE: A adds no capability and is a rename with a deprecation window, and its first step is small and self-contained (declare + deprecate + migrate the two doc pages); the honest cost is the temporary two-spelling window, which is bounded and visible, against B's permanent seam. If the maintainer wants the smallest possible move now, C is the honest holding position and is compatible with A later; B is the one I would not ship, because it changes behaviour on a dead premise."
}
],
"out_of_scope_findings": []
}

---

Generated by Claude Code