feat(types,core,fields,app-shell,plugins)!: reference is the only relational-target spelling objectui writes or reads; reference_to retires (objectui#11070, round 4) (#11264)

Refs #11070
Clause-②: yes (narrowing). `LookupFieldMetadata`,
`MasterDetailFieldMetadata`, and `DetailViewField` retire `reference_to`
and declare `reference`, and the ingestion pass no longer stamps
`reference_to` onto served defs, under the startup no-gradualism rule.
It is priced in the changeset.

Round 4 of objectui#11070, the `reference_to` round: the seat's answer A
to Q1 (`5915992755`), under the maintainer ruling on objectui#6837
(`5475017957`, 2026-08-31, verbatim:
「objectui不是前端的项目吗？后端的元数据只要对，前端按协议执行就行了呀」, with the earlier question 「按
spec 拒绝面直接删不是更合理吗」). Claim `5916640555`.

`reference` is now the only spelling ObjectUI writes or reads for a
relational field's target object. The one fold that remains is the
ruling's choke point: `normalizeFieldReferenceKeys` folds a foreign
`reference_to` / `referenceTo` onto `reference` when `reference` is
absent, keeps its dev warning, and never drops a key.

## What changed

- **Types (`@object-ui/types`).** `LookupFieldMetadata` and
`MasterDetailFieldMetadata` declare `reference` typed by reference to
`@objectstack/spec`'s `FieldSchema.reference`. `DetailViewField` and its
zod mirror `DetailViewFieldSchema` move from `reference_to` to
`reference` in the same commit, so the two faces keep equal key sets.
The `form.ts` comments and the form-field mirror's comment now say that
the lookup and user widgets read `reference` only.
`strict-face-read-keys-11070.test.ts` moves `reference_to` from the
pending list to the retired list, and gains a type-level pin: both field
metadata types carry the spec member, and none of the three contracts
has a `reference_to` key.
- **Ingestion (`@object-ui/core`, `reference-keys.ts`).** The pass folds
onto `reference` and no longer stamps `reference_to`. The header prose
that described a stamp of "BOTH snake_case keys" now describes the fold,
and it records why the stamp protected nothing once both ends moved. The
leave-arm rule stands.
- **Readers read `reference` only:** `LookupField`, `UserField`,
`LookupCellRenderer` and `UserCellRenderer` (only those two reads in
`fields/src/index.tsx`), `InlineFieldInput`'s reference fallback,
`schemaDefaults`' `current_user` seed, `sectionFields`' view override,
and `MetadataProvider`'s inline-subform parent.
- **Emitters write `reference`:** `paramToField`, `RecordDetailView`,
`FlowReferenceField` (its one target line), `RecordDetailPanel`,
`RecordMetaFooter`, `RelatedList`, `fieldEnrichment`,
`buildDefaultPageSchema`, `sectionFields`, `bulkParamToField` and
`ObjectGallery`.
- **Copy sets and ledgers.** `plugin-grid`'s `RELATIONAL_META_READ_SET`
loses its `reference_to` row and the `adapter-stamped` verdict that row
alone held. `plugin-dashboard`'s `CELL_RELATIONAL_META_KEYS` and
`FieldMeta` drop `reference_to`. `resolveActionParams`' unread
`RuntimeField.reference_to` member goes. `FieldDefaultsSchemaLike` pins
three members.
- **Docs and fixtures.** `lookup.mdx` (typed fences, plaintext fences,
prose, plus one paragraph on the retirement), `record-edit-modes.md`,
`plugin-form.mdx`'s field-slot row and `plugin-form`'s README. The tests
that fed `reference_to` to a widget, a cell or a served-def stub now
feed `reference`. The pins whose job is the fold, or a refusal, keep
`reference_to` as their input and assert the fold to `reference` with no
stamp back, or the refusal.
- **One changeset**, `.changeset/11070-reference-to-round4.md`, minor
with the break stated (AGENTS.md §9: never `major`). Fifteen pending
changesets that this round made false get an appended dated note, in the
append-only shape: `6837-reference-to-arm-deletion`,
`6837-gantt-tree-referenceto-arms`,
`6837-recorddrawer-invented-target-arms`,
`6694-dashboard-lookup-reference-meta`,
`6597-retire-fieldmeta-referenceto`,
`7166-retire-inert-fieldmeta-copies`,
`paramtofield-reference-rule-derives-from-core-5312`,
`6711-retire-reference-to-field`, `6874-retire-titleformat`,
`7155-converge-lookup-dialect-camelcase`,
`6528-resolve-reference-to-census`,
`7324-plugin-form-nameable-parameter-types`,
`11070-field-metadata-spec-spellings`, `10535-person-name-read-gate` and
`6875-grid-relational-meta-derive`.

### Pins that flipped, and why

These pins asserted the stamp. Each now asserts that no stamp happens,
and that the fold still does:
- `reference-keys.test.ts`: a `reference` def gains no `reference_to`;
`referenceTo` folds to `reference` only; idempotence; the map and array
containers.
- `reference-keys.legacyWarning-6837.test.ts`, case 5: "the STAMP is
unchanged" becomes "the FOLD still runs". The `referenceTo` case asserts
no `reference_to`; the `reference_to` case keeps the input key, because
the pass never drops one.
- `MetadataProvider.itemReferenceKeys-7650.test.tsx`: the first pin
asserted the stamp and now asserts its absence. The rest feed a legacy
spelling, because a `reference`-only def comes back unchanged and cannot
show that the pass ran.
- `getObjectSchema.test.ts` (data-objectstack).
- The emit-side pins that read `reference_to` off an emitted bag:
`referenceArms-6837.divergent.test.ts` (plugin-detail),
`RecordDetailDrawer.referenceArms-6837.test.tsx`,
`HeaderHighlight.editable.test.tsx`, `relationalMetaCopySet-6711` /
`-6874`, `lookupRelationalMeta-6694`, `sectionFields*`,
`paramToField.test.ts`, `resolveActionParams.test.ts`,
`bulkParamToField.test.ts`.
- New refusal pins: the lookup cell, the user cell and `LookupField`
each read no target from a `reference_to`-only def.

Pins that assert something else were not "fixed green". Three copy-set
floors, which required more than two keys in `RELATIONAL_META_KEYS`, now
require more than one, because the set is now `reference` and
`displayField`, and each floor now also names `reference`.

### Beyond the claim's file surface, stated

- `ObjectDataTable.tsx` gains
`ObjectDataTableRetiredReferenceToSnakeTombstone`, and both
ObjectDataTable test files gain a directive and a counter-control for
it. Retiring `FieldMeta.reference_to` removed the key from the derived
refusal bands' pool, and `recordFields.tsx`'s own `FieldMeta` docblock
requires that a retired member be re-refused by hand at that seam. This
is the third tombstone, beside `decimals` and `referenceTo`.
- Comment-only corrections to statements this round made false:
`auditHistoryDisplay.ts`, `deriveRelatedLists.ts`,
`useDatasetFields.ts`, `object-fields-io.ts`,
`components/custom/field.tsx`, core `ActionRunner.ts` /
`chart-series.ts` / `expand-fields.ts`, `data-objectstack/src/index.ts`,
`RecordPickerDialog.tsx`, `lookupColumnDisplay.tsx`,
`HeaderHighlight.tsx` and `ObjectGantt.tsx`, plus the stamp prose in the
gantt / tree / drawer 6837 pins.
- The named tail is folded. PR #11243 landed, so the three
`ObjectGrid.tsx` relational-metadata comments now name `reference` and
`displayField` (seat message, 18:53Z). `ListView.tsx`'s two lines were
left as they are, because both are true after this round: one says
`FieldSchema` refuses `reference_to`, the other that a list column
declares neither spelling. PR #11233 landed, so the `form.zod.ts`
comment, the `FormPage.tsx` comment, the `plugin-form.mdx` row and the
`FormPage.sharedFieldResolver-10179` pin were folded as well (seat
message, 19:54Z; the comment only in `form.zod.ts`, with no new
declaration). `FormPage.sharedWidgets-10179`'s lookup fixture moved
first, because that test went red on the change.

## Census, before and after

Base: merge base `615346d` for the round's own diff. Code lines are
non-comment lines in `packages/*/src`, `apps/console/src` and
`examples/*/src`, excluding tests. The typed half comes from a
TypeScript LanguageService `findReferences` over 5568 source files, with
workspace packages resolved to source.

| kind | before | after |
| --- | --: | --: |
| emitter sites writing `reference_to` onto a def or widget `field` | 11
| 0 |
| ingestion stamp of `reference_to` | 1 | 0 |
| copy sets carrying `reference_to` (grid ledger row, dashboard cell
keys) | 2 | 0 |
| reader lines reading `reference_to` (widgets, cells, inline editor,
seeding, section override, subform parent) | 10 | 0 |
| the ingestion fold's read of the legacy key (the ruling's choke point)
| 1 | 1 |
| declared `reference_to` members (field-types ×2, views, views.zod,
RuntimeField, FieldMeta, schemaDefaults ×2) | 8 | 0 |
| `reference_to?: never` refusal (tombstone) | 0 | 1 |
| typed references to a `reference_to` member: production writes / test
writes | 2 / 7 | no member left to reference |

The eleven emitters are the PM census's eleven. The type-checker census
found two of them typed (`FlowReferenceField`, `RelatedList`); the other
nine write through `any` or `Record` bags. It found no typed reader:
every reader was an untyped read.

## Runtime probe — the user-visible proof

A scratch vitest file, never committed, ran against the source at merge
base `615346d` and at head (`1972d01`, re-run at `338b19d` with
identical readings). `ObjectForm` in create mode opens its lookup
picker; `ObjectGrid` renders a lookup column with a primitive id; the
referenced record is `{ id: 'a1', name: 'Acme Corp' }`.

| case | base | head |
| --- | --- | --- |
| (a) served def with `reference` only, through `ObjectStackAdapter` |
picker queries `probe_account`; cell shows `Acme Corp`; served keys
`label, reference, reference_to, type` | picker queries `probe_account`;
cell shows `Acme Corp`; served keys `label, reference, type` |
| (a) the same def from a BYO `DataSource` | works | works |
| (b) action param `referenceTo` through `paramToField` into
`LookupField` | field carries `reference_to`; picker queries
`probe_account` | field carries `reference`; picker queries
`probe_account` |
| (c1) `reference_to`-only def served through `ObjectStackAdapter` |
folded (`reference` added); dev warning fires; picker and cell work |
the same: folded, warned, picker and cell work |
| (c2) `reference_to`-only def from a BYO `DataSource` | picker queries
`probe_account`; cell shows `Acme Corp` | **no `find` call at all; the
cell shows the raw id `a1`** |

(c2) is the break, and the changeset's BREAKING paragraph names that
host.

## Hypotheses

- **H1 holds.** Read at objectstack `origin/main` `165c1d49e`. The
example apps write `reference_to` zero times, against a control of 30
`Field.lookup` / `Field.masterDetail` calls in 19 files; both helpers
write `reference`. `FieldSchema` refuses `reference_to` by name
(installed 17.5.0: `unrecognized_keys`, "Did you mean `reference_to` →
`reference`?"), and so does the spec's form-field schema. The
`field-reference-to-alias` conversion
(`packages/spec/src/conversions/registry.ts`) rewrites stored rows on
rehydration and in `os migrate meta`. The only other hits are refusals
(the SQL and Mongo doors, verify, lint), a reader of three spellings in
`plugin-security`, and a comment in `plugin-approvals` that describes
this repo's widget key (noted below).
- **H2 holds.** Every production write is one of the eleven emitters,
the ingestion stamp, or one of the two copy sets the brief listed as
readers. No twelfth writer turned up, typed or untyped.
- **H3 holds.** On the ObjectStack path the cells receive folded defs,
as probe cases (a) and (c1) show. `RELATIONAL_META_KEYS` is derived to
`reference, displayField`, and the grid's derivation gate re-extracts
the cell's read set with `reference` in it.
- **H4:** **false as posed.** The `reference_to` pair was not in M3's
class (ii) at this base. Round 1 (PR #11115) moved both `fields-lookup`
fixtures to `reference`, and round 3 reported class (ii) without it.
Measured with `scripts/measure-strict-authoring-face.mjs --json` at
merge base `af9e957` and at `338b19d`: every refusal figure is identical
(2224 nodes, 105 strict-refused, 66 strict-only, 39 red today, 599
documents, 98 refused whole-tree), and `reference_to` occurs in zero
refusals at both. The only differences are the renderer-source
word-mention counts, which the comment edits moved, and the error text
of one authored module that fails to load under either build state. So
this round moves M3 by zero in every class. The absolute class (ii)
figure at this base is NOT MEASURED: round 3's shipped-face port of PR
#11069's `findUndeclaredKeys` was a scratch script and was never
committed.

## Checks

Heavy runs went through `os-verify-lock` (slot `issue-11070`). Exit
codes were captured before any pipe.

- **Build closure** (`check-doc-snippet-types --build-filter`, turbo
`--concurrency=2`): `35 successful, 35 total`, before and after the
first merge.
- **type-check** of 21 packages, the ones this diff touches plus the
console and the schema catalog (the type-checker census found no other
typed reader): `Tasks: 56 successful, 56 total`, before and after the
first merge. After the second merge, `@object-ui/types` was rebuilt and
type-checked again, exit 0.
- **Tests, full affected set** (the 21 packages' paths, 3536 files),
before the first merge: `4 failed | 3527 passed | 5 skipped (3536)`. The
four were pins that asserted the old shape: three copy-set floors of
more than two keys, and the console shared-widget lookup fixture. They
were fixed in `c684de4` and re-run: `Test Files 4 passed (4)`, `Tests 30
passed (30)`.
- **Tests after the first merge** (`338b19d`), narrowed to the files
both sides touched plus this round's relational surface (types, fields
tests and widgets, the Flow inspectors, console components, plugin-grid,
plugin-detail and plugin-dashboard tests, plugin-form, core
reference-keys, the adapter, and app-shell providers and utils): `Test
Files 1137 passed | 3 skipped (1140)`, `Tests 16884 passed | 31 skipped
(16915)`. After the second merge (`16b43a7`, no file overlap):
`packages/types/` `295 passed (295)`, `7375 passed (7375)`, including
`zod-mirror-parity.test.ts`, whose totals did not move.
- **Doc gates** at `338b19d`: `check:doc-snippets` `696 of 696 block(s)
judged, 0 failed`; `check:doc-examples`, `check:doc-types`,
`check:spec-symbols`, `check:doc-example-readers` and
`check:doc-example-ids` all exit 0.
- **At `16b43a7`**, all exit 0: `check:doc-fences`, `docs:check-links`,
`check:control-bytes`, `check:pending-changeset-literals`,
`check-changeset-presence` (`174 source file(s) of 20 released
package(s) changed, and this change declares 1 changeset(s)`),
`changeset:check` (no major), `check:new-line-citations` (`0 new
citation(s)`), `check:test-path-roots`, `check:changeset-claims`
(report-only; every named changeset was read), and
`check-governed-queue-guard --test` over the 194 paths (`NOT GOVERNED`).
- **Lint, a measured narrowing.** The population is `eslint.config.js`'s
`**/*.{ts,tsx}` files entry; there are no `parserOptions.project` or
`projectService`, so type-aware linting is off and this diff cannot move
an untouched file's verdict. The 174 changed `.ts` / `.tsx` files were
linted at `16b43a7` and at merge base `54a7830`: 0 errors at both, 1909
warnings at both, and no file is worse than base.
- **Ablations**, each run on a committed, clean tree through
objectstack's `ablation-replace.mjs`. In every case the anchor hit once,
the blob moved, the blob was restored equal to HEAD, and `git diff HEAD`
was empty afterwards.
- A1: `lookup.mdx`'s fence writes `reference_to`. `check:doc-snippets`
exited 1 with `696 of 696 block(s) judged, 1 failed`, TS2561
"'reference_to' does not exist in type 'LookupFieldMetadata'. Did you
mean to write 'reference'?", which proves the gate read the rebuilt
`.d.ts`.
- A2: the fold stamps `reference_to` again. 6 red / 83 green, against 5
predicted: the three core stamp pins, the adapter pin and the provider
pin, plus the empty-target pin, because an empty `reference` also gained
a stamp.
- A3: `LookupCellRenderer` reads `reference || reference_to` again. 2
red / 14 green, as predicted: the new cell refusal pin, and the grid
derivation gate's unclassified-spelling check.
- **Type-checker census** at `338b19d`: the seven contracts carry no
`reference_to` member. The control run of the same instrument on
`reference` finds 7 declarations, the same two typed production writes
that moved, 1 production read, 3 test reads and 10 test writes.
- **Diff size:** 194 files, +1022 / −647 against merge base `54a7830`.
That is under the 5000-line human-merge threshold: 62 non-test files (16
of them changesets) and 132 test files.

NOT MEASURED:
- The repository-wide lint and the test shards outside the sets above.
CI runs those.
- Tests after the second merge outside `packages/types/`. Its three
incoming commits share no file with this branch, and none contains
`reference_to`.
- A browser dogfood against a live objectstack app. The probe used
`ObjectForm` / `ObjectGrid` with a stub or adapter-wrapped `DataSource`.
- The absolute M3 class (ii) figure (see H4).
- CI convergence. It was not waited on, per the dispatch contract.

## Acceptance notes

- `docs/adr/0059-action-params-shared-field-widgets.md`'s decision
section still records `referenceTo` → `reference_to` as `paramToField`'s
mapping. It was left as written: it is the accepted decision's record
(2026-07-19), and the ruling kept the historical record. Editing
`docs/adr/**` would also make this PR governed. The seat may want a
dated amendment line in a docs-only PR.
- `ROADMAP.md`'s two hits are completed items and changelog history, not
current behaviour, so they were not changed.
- `.changeset/audit-field-def-reference-narrow.md` says the choke point
"stamps both snake_case spellings". It has empty front matter, so
nothing publishes it, and no note was appended.
- objectstack `plugin-approvals`' `sys-approval-request.object.ts` has a
comment saying the console resolves a lookup config as `reference_to:
sys_user`. That spelling is now `reference`. It is a comment in the
sister repo, not a producer; noted, not filed.

---

_Generated by [Claude
Code](https://claude.ai/code/session_01TdiauJaVCHuj45EzZGUxHh)_

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: objectstack-fleet[bot]

.changeset/10535-person-name-read-gate.md

@@ -27,3 +27,5 @@ are unchanged.
 This is defence in depth: ObjectStack's `FieldMasker` already removes the
 fields a user may not read from the rows it returns, and on those rows nothing
 changes. The change matters for a backend that does not.
+
+⚠️ **Dated note, 2026-09-30 — the cell reads the person's object from `reference` alone — objectui#11070.** "the object the field's `reference_to` (or `reference`) names" above held when this change landed. Later in this same release objectui#11070 (round 4) narrowed `UserCellRenderer` to `reference`, with `sys_user` when it names none. The read gate is unaffected. `.changeset/11070-reference-to-round4.md` states what ships; the text above is kept as the reading of this change.

.changeset/11070-field-metadata-spec-spellings.md

@@ -14,3 +14,5 @@ The formula and summary field widgets read `@objectstack/spec`'s own spellings,
 **Breaking, priced as minor under the fixed group's version policy.** A literal annotated as `FormulaFieldMetadata`, `SummaryFieldMetadata` or `PasswordFieldMetadata` that still writes a retired member no longer compiles (an excess-property error naming the key), and at runtime a formula or summary field that carries only `return_type` or `summary_type` renders its value unformatted. `@objectstack/spec`'s `FieldSchema` refuses every retired spelling by name, so no spec-compliant producer writes them. The fix is the spec spelling: `returnType`, and `summaryOperations: { object, field, function }` (with `filter` for the former `summary_filter`).
 
 **Not in this change.** `LookupFieldMetadata.reference_to` and the lookup readers' `reference_to` read stay: in-repo producers still write `reference_to` onto the field definitions those readers are handed, so retiring the spelling is a separate decision on objectui#11070. The strict face keeps refusing `return_type`, `summary_type`, `summary_object` and `summary_field` on a hand-authored form's field, as before.
+
+⚠️ **Dated note, 2026-09-30 — the `reference_to` decision was taken in this same release — objectui#11070.** "Not in this change" above is still true of this change. Round 4 of objectui#11070, later in this same release, retired `LookupFieldMetadata.reference_to` and the lookup readers' `reference_to` read, and moved the in-repo producers to `reference`. `.changeset/11070-reference-to-round4.md` states what ships; the text above is kept as the reading of this change.

.changeset/11070-reference-to-round4.md

@@ -0,0 +1,32 @@
+---
+'@object-ui/types': minor
+'@object-ui/core': minor
+'@object-ui/fields': minor
+'@object-ui/app-shell': minor
+'@object-ui/plugin-detail': minor
+'@object-ui/plugin-form': minor
+'@object-ui/plugin-grid': minor
+'@object-ui/plugin-list': patch
+'@object-ui/plugin-dashboard': patch
+'@object-ui/data-objectstack': patch
+---
+
+`reference` is now the only spelling ObjectUI writes or reads for a relational field's target object (objectui#11070, round 4, under the objectui#6837 ruling: 「objectui不是前端的项目吗？后端的元数据只要对，前端按协议执行就行了呀」).
+
+- **Types.** `LookupFieldMetadata`, `MasterDetailFieldMetadata` and `DetailViewField` (with its zod mirror `DetailViewFieldSchema`) declare `reference` and no longer declare `reference_to`. On the two field metadata types the member is typed by reference to `@objectstack/spec`'s `FieldSchema.reference`. `@object-ui/plugin-form`'s `FieldDefaultsSchemaLike` drops its `reference_to` member the same way.
+- **Readers.** `LookupField`, `UserField`, `LookupCellRenderer`, `UserCellRenderer`, the inline editor's reference fallback, the form's `current_user` seeding and the inline-subform parent lookup read `reference` alone.
+- **Emitters.** Every in-repo producer that builds a field definition or a widget `field` prop writes `reference`: the action-param dialog (`paramToField`), the bulk-action dialog, the record detail page, drawer, footer, related list and synthesised page, the gallery card, the form's section-field override and the flow designer's reference picker. The grid's and the dashboard's relational copy sets carry `reference` and no longer copy `reference_to`.
+- **Ingestion.** `normalizeFieldReferenceKeys` (behind `ObjectStackAdapter.getObjectSchema` and `MetadataProvider`) still folds a legacy `reference_to` / `referenceTo` onto `reference` when `reference` is absent, and still warns in dev. It no longer stamps `reference_to` onto every relational definition, and it still never drops or overwrites a key.
+
+`@objectstack/spec`'s `FieldSchema` refuses `reference_to` by name, and objectstack#13847 rewrites stored ones on the serve path and in `os migrate meta`, so a definition served by an ObjectStack backend is unaffected.
+
+## ⚠️ BREAKING for a host that hands `reference_to` to the widgets directly
+
+The type change is a compile error for TypeScript that writes `reference_to` on `LookupFieldMetadata`, `MasterDetailFieldMetadata` or `DetailViewField`: rename it to `reference`.
+
+At runtime the break reaches exactly one kind of host: one that serves object definitions spelling the target only as `reference_to` through a `DataSource` other than `ObjectStackAdapter`, or that passes such a definition straight into `LookupField`, `UserField` or a cell renderer. Those definitions never pass the ingestion fold. Measured with an object-bound lookup field on `ObjectForm` and a lookup column on `ObjectGrid`, both fed by a hand-written `DataSource` whose `getObjectSchema` returns `{ type: 'lookup', reference_to: 'account' }`:
+
+- before this change, opening the picker queried `account` and the cell resolved the record's name;
+- after it, the picker has no object to query (no `find` call is made) and the cell shows the raw id beside the unresolved-reference marker.
+
+The same definition served through `ObjectStackAdapter.getObjectSchema` still works, before and after: the fold adds `reference`, the picker queries `account`, the cell resolves the name, and the dev warning names the field. **Fix:** spell the target `reference` in the definition your `DataSource` serves.

.changeset/6528-resolve-reference-to-census.md

@@ -35,3 +35,5 @@ already head of the old chain, so any document carrying both is unaffected.
 
 The string / array / `{ object }` carriers are untouched: the carrier is a
 separate axis from the spelling and narrowing it needs its own census.
+
+⚠️ **Dated note, 2026-09-30 — `reference_to` is no longer live on ObjectUI's own view/field schema — objectui#11070.** The table's `reference_to` row said the spelling was "live only on ObjectUI's own view/field schema". Later in this same release objectui#11070 (round 4) moved that schema (`DetailViewField` / `DetailViewFieldSchema`) and the field metadata types to `reference`. The narrowing this change made is unaffected. `.changeset/11070-reference-to-round4.md` states what ships; the text above is kept as the reading of this change.

.changeset/6597-retire-fieldmeta-referenceto.md

@@ -59,3 +59,5 @@ than assumed: `FieldMeta`, `AuthoredColumnOverrides`, `EnrichedColumn` and
 barrel re-exports only the `ObjectDataTable` component, and the package's `exports` map
 publishes only `"."`. No downstream type moves; this is a package-internal contract change
 plus a README correction, not a removal from a published type surface.
+
+⚠️ **Dated note, 2026-09-30 — `reference_to` has since left the cell and the grid's copy — objectui#11070.** The measurement above read `LookupCellRenderer` resolving its target from `field.reference_to` / `field.reference`, and `applyRelationalMeta` copying `reference_to`. Later in this same release objectui#11070 (round 4) narrowed the cell to `reference` alone and dropped `reference_to` from both copy sets. The verdict on `referenceTo` is unchanged. `.changeset/11070-reference-to-round4.md` states what ships; the text above is kept as the reading of this change.

.changeset/6694-dashboard-lookup-reference-meta.md

@@ -55,3 +55,5 @@ Behaviour note for existing dashboards: a lookup cell whose referenced object de
 `nameField` other than `name` / `title` will now show that declared name instead of the
 heuristic's pick, and valued lookup cells become links wherever the host publishes
 `recordHref`.
+
+⚠️ **Dated note, 2026-09-30 — the cell's reads and the copy set have since moved — objectui#11070.** Later in this same release objectui#11070 (round 4) narrowed `LookupCellRenderer` to `reference` alone, so "reads exactly `reference_to`, `reference` and `display_field`" and `useRefObjectSchema(reference_to)` above no longer describe what ships: the cell reads `reference`, and `buildFieldMeta` no longer copies `reference_to` (its `FieldMeta` member is retired, and `ObjectDataTable` refuses it by a hand-written tombstone). `.changeset/11070-reference-to-round4.md` states what ships; the text above is kept as the reading of this change.

.changeset/6711-retire-reference-to-field.md

@@ -38,3 +38,5 @@ correct, so the absence is pinned directly instead
 (`__tests__/relationalMetaCopySet-6711.test.tsx`): all three call sites, each with a
 presence assertion on the eight surviving keys as the control against a fixture that
 passes by never reaching the copy path.
+
+⚠️ **Dated note, 2026-09-30 — `reference_to` has since left `LookupCellRenderer` and the copy set — objectui#11070.** The control above names `reference_to` among the keys `LookupCellRenderer` read. Later in this same release objectui#11070 (round 4) narrowed the cell to `reference` and removed `reference_to` from `RELATIONAL_META_KEYS`; the retirement of `reference_to_field` is unaffected. `.changeset/11070-reference-to-round4.md` states what ships; the text above is kept as the reading of this change.

.changeset/6837-gantt-tree-referenceto-arms.md

@@ -51,3 +51,5 @@ surviving spellings.
 Pinned by `ObjectGantt.referenceArms-6837.test.tsx` and
 `ObjectTree.referenceArms-6837.test.tsx`, which keep the live arms green beside a
 named refusal for the deleted key.
+
+⚠️ **Dated note, 2026-09-30 — the choke point folds, it no longer stamps both keys — objectui#11070.** "`normalizeSchemaReferenceKeys` ... stamps both snake_case keys" above held when this change landed. Later in this same release objectui#11070 (round 4) made that pass fold a legacy spelling onto `reference` without stamping `reference_to`; a def that entered through it still carries `reference`, the one arm both components keep. `.changeset/11070-reference-to-round4.md` states what ships; the text above is kept as the reading of this change.

.changeset/6837-recorddrawer-invented-target-arms.md

@@ -34,3 +34,5 @@ pass over the same cells.
 
 Pinned by `RecordDetailDrawer.referenceArms-6837.test.tsx`, which keeps the live
 arms green beside a named refusal per deleted key.
+
+⚠️ **Dated note, 2026-09-30 — the choke point folds, and the drawer emits `reference` — objectui#11070.** "`normalizeSchemaReferenceKeys` ... stamps both snake_case keys" above held when this change landed. Later in this same release objectui#11070 (round 4) made that pass fold a legacy spelling onto `reference` without stamping `reference_to`, and the drawer's field list now carries the target as `reference`. `.changeset/11070-reference-to-round4.md` states what ships; the text above is kept as the reading of this change.

.changeset/6837-reference-to-arm-deletion.md

@@ -119,3 +119,5 @@ narrowing them would break in-repo producers, and `plugin-grid`'s
 `relationalMetaCopySet.derivation.test.ts` re-derives its read set from exactly
 those three sources — where `reference_to` is recorded with verdict
 `adapter-stamped`. `DetailViewFieldSchema` is likewise untouched.
+
+⚠️ **Dated note, 2026-09-30 — the stamp, the three readers and the emitted key have since moved — objectui#11070.** Later in this same release objectui#11070 (round 4) retired `reference_to` inside ObjectUI as well. `normalizeFieldReferenceKeys` now FOLDS a legacy `reference_to` / `referenceTo` onto `reference` and no longer stamps `reference_to`, so "Stamping is deliberately unchanged" and "stamp both snake_case keys" above no longer describe what ships. `LookupCellRenderer`, `LookupField` and `UserField` read `reference` only; `LookupFieldMetadata`, `MasterDetailFieldMetadata` and `DetailViewField` (with `DetailViewFieldSchema`) declare `reference`; and the emitters listed under "What did NOT change" write `reference`. A hand-written schema served through a `DataSource` other than `ObjectStackAdapter` that spells only `reference_to` therefore also loses the lookup picker's target and the read cell's name. `.changeset/11070-reference-to-round4.md` states what ships; the text above is kept as the reading of this change.