Field designer offers a `referenceTo` control for lookup fields — a key FieldSchema rejects by name, so saving a lookup field hard-blocks the object

[yinlianghui-tw]

Surfaced by the key-level parity gate built for #5761 (scripts/check-designer-field-key-parity.mjs). Filed rather than fixed: #5761's ruling is that the gate surfaces instances and each surfaced key gets its own card, because the three prior instances (#4644 indexed, #4687 distance_metric, #4676 placeholder) took three different correct resolutions.

The key

referenceTo is not in FieldSchema's accept set. Measured against the installed @objectstack/spec 17.2.0:

FieldSchema.safeParse({ type:'lookup', label:'Account', referenceTo:'account' })
 => success = false
 => [{ code: 'unrecognized_keys', keys: ['referenceTo'] }]

The spec's spelling is reference:

reference — Target object name (snake_case) for lookup/master_detail fields. Required for relationship types. Used by $expand to resolve foreign key IDs into full objects.

Why this is live, not latent

Unlike sortOrder (declared but never populated), referenceTo has a live form control and two live writers:

• packages/plugin-designer/src/FieldDesigner.tsx:311 — the field editor renders an input for it, visibleWhen: "record.type == 'lookup'".
• packages/plugin-designer/src/FieldDesigner.tsx:221,242 — both the create and the update path write referenceTo: data.referenceTo ? String(data.referenceTo) : undefined.
• packages/plugin-designer/src/MetadataFieldsPage.tsx — fromDesignerField writes referenceTo: designed.referenceTo onto the ServerFieldSchema that is PUT.
• packages/app-shell/src/services/MetadataService.ts:104 — toFieldPayload writes referenceTo: field.referenceTo onto FieldMetadataPayload, which saveFields PUTs as fields.map(toFieldPayload).

So an author who creates a lookup field in the designer and fills in the referenced object writes a key the API refuses. This is the #4644 shape exactly: PUT /api/v1/meta/object/:name returns a hard 422 INVALID_METADATA, which then blocks every subsequent save of that object until the key is cleared — and the author has no way to tell from the designer UI which key did it.

Also note the read direction is broken symmetrically: toDesignerField reads raw.referenceTo from the server payload, but a spec-parsed server sends reference, so an existing lookup field loads into the designer with an empty reference box.

Why this is not a mechanical rename in this card

reference is the obvious candidate, but choosing it is an adjudication:

• FieldSchema marks reference required for relationship types, so a rename changes what a half-filled designer draft parses as — today the empty case is undefined and the field saves.
• finding(types): VectorFieldMetadata has two declared keys FieldSchema rejects — indexed and distance_metric #4687 shows "delete the declaration" is sometimes the right answer even when a near-spelling exists.
• Both field designers author placeholder, a key FieldSchema rejects by name — but the designer's own preview renders it, so this is a contract question not a deletion #4676 shows "move the producer upstream" is sometimes the right answer.

Both directions (read and write), both designers, and the i18n label key appDesigner.fieldDesigner.referenceTo are in scope for whoever takes it.

Verification

pnpm check:designer-field-key-parity reports it. The key is recorded in that gate's KNOWN_UNPARSEABLE_KEYS ledger pointing here; removing it from the payload shapes without removing the ledger entry is also red, so the ledger cannot go stale.

Refs: #5761 (the gate) · #4644 · #4687 · #4676

[os-zhuang]

Triage: lands in packages/plugin-designer (FieldDesigner.tsx, MetadataFieldsPage.tsx) + app-shell/services/MetadataService.ts; routed pm:queue + domain:ui, type Bug — live hard-block: authoring a lookup field through the field designer 422-blocks every later save of the object, and the read side loads existing lookups with an empty reference box. Family + fold-or-serial (answered): #6041/#6043/#6044 all come from the #5761 parity gate and touch the same files — #6041 + #6044 are a fold candidate (both are spelling-parity repairs toward the spec's declared key, each independently verifiable per key against the gate's ledger; all members now graded); #6043 is excluded from the fold (its resolution runs through the CEL expression-language question — a different repair shape) and serializes behind whichever lands first on these files. Per #5761's ruling each key keeps its own card either way — a fold shares the branch/PR with per-card commits and one Fixes line per member. Repair-direction note: the spec's reference is required for relationship types, so the rename changes what a half-filled draft does — that edge is in scope, not a surprise.

---

Generated by Claude Code

[yinlianghui]

Claim: PM loop round 39 — FOLD: #6041 + #6044
Session: session_01CSoz9uGhaaSgiq3hshtN7L
Branch: claude/issue-6041-designer-spec-key-parity
Worktree: objectui-issue-6041
Domain: domain:ui
Container & model: L, mode:subagent, model: opus
Clause-②: yes — the designer stops emitting keys FieldSchema refuses by name, so what a save accepts changes. Declared; Opus under this seat's recorded Fable-quota exemption.

File surface: packages/plugin-designer (FieldDesigner.tsx, MetadataFieldsPage.tsx) + packages/app-shell/src/services/MetadataService.ts, plus tests and a changeset.

裁决 — triage (2026-08-25 00:26Z), binding

lands in packages/plugin-designer (FieldDesigner.tsx, MetadataFieldsPage.tsx) + app-shell/services/MetadataService.ts; pm:queue + domain:ui, type Bug — live hard-block: authoring a lookup field through the field designer 422-blocks every later save of the object, and the read side loads existing lookups with an empty reference box.
Family + fold-or-serial (answered): #6041/#6043/#6044 all come from the #5761 parity gate and touch the same files — #6041 + #6044 are a fold candidate (both are spelling-parity repairs toward the spec's declared key, each independently verifiable per key against the gate's ledger; all members now graded); #6043 is EXCLUDED from the fold (its resolution runs through the CEL expression-language question — a different repair shape) and serializes behind whichever lands first on these files.
Per #5761's ruling each key keeps its own card either way — a fold shares the branch/PR with per-card commits and one Fixes line per member.
Repair-direction note: the spec's reference is required for relationship types, so the rename changes what a half-filled draft does — that edge is in scope, not a surprise.

The two members

card	designer emits	spec declares	consequence today
#6041	referenceTo on lookup fields	reference	FieldSchema refuses by name → saving a lookup field hard-blocks the object
#6044	isSystem	system	system-field detection reads a key the server never sends, and the key round-trips back out as a 422

⛔ #6043 (formula → expression) is NOT in this fold. ⛔ Do not touch it, do not "fix it while you're there" — triage excluded it because a bare rename would ship non-CEL expressions under a valid key, i.e. a silent runtime failure strictly worse than the loud 422.

PM mechanism assumptions — measure, do not inherit

1. ⛔ Re-derive every site. These were filed 2026-08-24 and main has moved a great deal overnight. Report each read/write site as you find it, ⛔ not as the card names it. (On [Decision] schema.onNavigate is a function value read off the grid schema — the fifth key #5091's ruling did not cover #5234 tonight a card's line number was stale by 147 lines.)
2. ⚠️ The rename has a behavioural edge the note names, and it is yours to handle: reference is required for relationship types, so a half-filled draft that was previously savable (carrying referenceTo, ignored) may now fail validation, or vice-versa. ✅ Measure what a half-filled draft does before and after, and state it. ⛔ Do not discover this in review.
3. ⚠️ There are two directions per key and they can be fixed independently — check both. The write side (designer emits the wrong key → 422) and the read side (existing records load with an empty reference box, because the reader looks for the wrong key). ⚠️ Fixing only the write side leaves every already-saved field still unreadable. ✅ Say explicitly, per key, that both directions are covered.
4. ⚠️ MetadataService.ts is shared with the read path — confirm whether the round-trip (isSystem out → 422) is a separate site from the detection read, or the same one. The Both designer field shapes spell the spec's system flag as isSystem — so system-field detection reads a key the server never sends, and the key round-trips back out as a 422 #6044 card describes both symptoms; they may or may not be one line.
5. ⚠️ The finding: nothing guards the CLASS "a field designer authors a key FieldSchema refuses" — three per-key tombstones, no key-level parity check #5761 parity gate has a ledger. ✅ Each key is "independently verifiable per key against the gate's ledger" — so use the ledger as your oracle and quote its entry for each of the two keys, before and after. ⛔ If the ledger does not move when you fix a key, your fix is not the one it measures.

Fold mechanics — ⚠️ get these exactly right

• One branch, one PR, with per-card commits — one commit for Field designer offers a referenceTo control for lookup fields — a key FieldSchema rejects by name, so saving a lookup field hard-blocks the object #6041, one for Both designer field shapes spell the spec's system flag as isSystem — so system-field detection reads a key the server never sends, and the key round-trips back out as a 422 #6044. ⛔ Do not squash them into one commit locally.
• One Fixes line per member in the PR body: Fixes #6041 and Fixes #6044, both present.
• ⚠️ Each key keeps its own card (finding: nothing guards the CLASS "a field designer authors a key FieldSchema refuses" — three per-key tombstones, no key-level parity check #5761's ruling) — ⛔ do not close one as a duplicate of the other.
• ⚠️ Audit the PR body for closing keywords near any OTHER issue number — ⛔ especially Field designer offers a formula control for formula fields — a key FieldSchema rejects by name (spec spells it expression), so saving a formula field hard-blocks the object #6043, which must stay open. GitHub's parser ignores negation: "excluded, not fixed: Field designer offers a formula control for formula fields — a key FieldSchema rejects by name (spec spells it expression), so saving a formula field hard-blocks the object #6043" still closes Field designer offers a formula control for formula fields — a key FieldSchema rejects by name (spec spells it expression), so saving a formula field hard-blocks the object #6043. Measured on [finding] PluginComponentInput is a published name with zero consumers, and after #4972 it is a pure alias of ComponentInput #5674 yesterday.

Verification

⚠️ Reproduce both hard-blocks before fixing — the 422 on save and the empty reference box on load — red for a value reason, ⛔ not a mount error. Predict the direction before running.

⚠️ Commit before you ablate. ⛔ git checkout <ref> -- <path> writes the INDEX as well as the worktree, so reading a baseline that way and restoring with git checkout -- <path> restores the baseline over your work.

⚠️ Seven phantom-class defects were self-caught by devs in the last two days, all one root: an assertion or control that cannot distinguish the two states of the world. Among them: a shared mock object carrying a previous test's write into the next case; an entire harness whose two principals degenerated to the same value; a grep -oE with an unescaped ( returning 0 for every pattern; and a probe reporting its verdict through a console.log vitest never surfaced, so it printed the same answer in both states. ✅ State explicitly which of your assertions would still pass if your change were reverted, and make each control a string present in both versions of the file.

⚠️ Ablate per key, not per PR — removing #6041's fix must red only #6041's cases and leave #6044's green, and vice-versa. That is what "independently verifiable per key" means, and it is the fold's whole justification.

Prove every mutation on disk by grepping injected and separately removed text; print the landing site; ⚠️ assert anchor uniqueness before writing, bounded to the right span — a file-wide anchor with 2 hits was caught by that assert on #5234 tonight; restore under trap … EXIT INT TERM with a cwd-independent command; confirm git diff HEAD --stat empty.

Gates by name, with exit codes: type-check for @object-ui/plugin-designer and @object-ui/app-shell (⚠️ hyphenated; echo the script name; distinguish unbuilt-closure red from missing-node_modules red; ⚠️ build ./examples/** too), root-form vitest quoting per-test names, the downstream prefix-form sweep with direction demonstrated, eslint with merge-base delta (⚠️ plain eslint .; ⛔ no --no-inline-config), and the #5761 parity gate itself — that one is your oracle, ⛔ not optional.

⚠️ The gate set grew overnight: runs now carry 25 checks, up from 19 yesterday. New ones include Pre-Install Import Graph Check, Inert vi.mock Specifier Check and Doc Fence Language Check. ✅ Derive your set by enumerating each CI job's own step list, ⛔ not top-level script names.

⚠️ Use pnpm exec vitest run [paths] from the repo root — ⛔ not pnpm --filter … test -- [paths], which silently drops everything after -- (guarded, objectui#3288). ⚠️ Zero-match pnpm trap: a filter matching nothing prints "No projects matched the filters" and exits 0. ⚠️ A cached turbo green is not a measurement — use --force on any turbo gate you treat as evidence. Run node scripts/check-changeset-presence.mjs rather than guessing. Changeset patch unless a published signature moves; ⛔ never major.

Deliverable

Draft PR, body with both Fixes #6041 and Fixes #6044. ⛔ Do not mark ready, ⛔ do not enqueue, ⛔ no auto-merge — the PM lands it. Post the terminal report on this issue (plain-text first line os-dev-report; ⛔ avoid short angle-bracket placeholders) and return it. State per gate: command, exit code, what a red would have meant; every re-derived site; the ledger entry for each key before and after; what a half-filled draft does before and after; that both directions (write and read) are covered per key; which of your assertions would still pass on a revert; the per-key ablation result; and any deviation with its reason.

---

Generated by Claude Code