finding(plugin-grid): ObjectGrid copies `reference_to_field` onto every column's fieldMeta, and nothing in the repo reads it

[os-sales]

Provenance: measured while implementing #6694 (feeding the dashboard widgets' lookup cells
their reference target). Filed unassigned, no pm:queue label — an observation, severity is
for triage to set.

What's measured

ObjectGrid's RELATIONAL_META_KEYS (packages/plugin-grid/src/ObjectGrid.tsx:433) lists
nine keys that applyRelationalMeta copies off the object-schema field def onto the built
fieldMeta, at all three of its column-building call sites (lines 2009, 2200, 2283):

'reference_to', 'reference', 'reference_to_field',
'display_field', 'id_field', 'description_field',
'lookup_filters', 'lookupFilters', 'titleFormat',

reference_to_field has zero member reads anywhere in the repo. Measured across
packages/ and apps/, excluding dist/, the only occurrences of the identifier are:

• the RELATIONAL_META_KEYS array literal itself (the write), and
• the prose / fixture in packages/plugin-dashboard/src/recordFields.tsx and
  __tests__/lookupRelationalMeta-6694.test.tsx that finding(plugin-dashboard): lookup cells in ObjectDataTable / RecordDetailDrawer never get reference_to/reference — refSchema-driven resolution and drill-through links never engage #6694 added to record why it is NOT in
  that seam's copy set.

No .reference_to_field member access, no destructuring, no bracket read. The value is
written onto every relational column's fieldMeta on every column build and consumed by
nothing.

Control for the measurement: the same sweep over its eight list-mates finds real readers for
all of them — reference_to / reference / display_field in LookupCellRenderer
(packages/fields/src/index.tsx), and id_field / description_field / lookup_filters /
lookupFilters / titleFormat in packages/fields/src/widgets/LookupField.tsx and
UserField.tsx. So the zero is specific to this key, not an artefact of how the sweep was
written.

Why this is worth a card

This is the same defect class this repo has retired twice in recent memory, both times in the
sibling producer:

• finding(plugin-dashboard): FieldMeta.decimals is written from the schema def but read by nothing #6625 — FieldMeta.decimals, written from the schema def on every call, read by nothing.
• referenceTo column override: promised in the README, kept by nothing — make the promise real or withdraw it (enforce-or-remove, from #6425) #6597 — FieldMeta.referenceTo, same shape, plus a README promise that was never kept.

Both were retired under the maintainer's standing startup-stage rule (2026-08-27: no measured
demand retires immediately). reference_to_field is that shape in plugin-grid rather than
plugin-dashboard, and it has never been adjudicated either way.

⚠️ Worth noting for triage: unlike decimals / referenceTo, this key is not an
author-facing override — it is copied from the object schema field def, so retiring it is a
question about the copy list, not about an authoring promise. The cheap check is whether
@objectstack/spec declares reference_to_field on a field at all; if the spec does not
declare it, no schema field def can carry it and the copy is unreachable as well as unread.
That check was not run here — this card records the measured zero-readers fact only.

Scope note

Not folded into #6694: that card's fix lands in plugin-dashboard and deliberately does NOT
copy this key (its copy set is the three keys a cell renderer actually reads). Removing the
key from plugin-grid's list is a separate change to a different package, with its own
measurement and its own blast radius — ObjectGrid's cells are editable, so anything touching
its relational copy set has to re-check the inline picker's query path.