finding: `FieldMetadataPayload.sortOrder` is a key FieldSchema rejects, written by `toFieldPayload` — latent only because nothing populates it

[yinlianghui-tw]

Observation-class finding, surfaced by the key-level parity gate built for #5761 (scripts/check-designer-field-key-parity.mjs). Filed unassigned, finding, deliberately not pm:queue. Filed rather than fixed per #5761's ruling.

The key

sortOrder is not in FieldSchema's accept set. The spec has sortable (a boolean — "whether field is sortable in list views"), which is a different concept, and no field-level ordering key at all.

FieldSchema.safeParse({ type:'text', label:'L', sortOrder: 3 })
 => success = false
 => [{ code: 'unrecognized_keys', keys: ['sortOrder'] }]

Why it is latent rather than live

sortOrder is declared on both packages/app-shell/src/services/MetadataService.ts (FieldMetadataPayload, line 67) and packages/types/src/designer.ts (DesignerFieldDefinition), and toFieldPayload (MetadataService.ts:108) writes sortOrder: field.sortOrder onto the payload that saveFields PUTs.

But a repo-wide scan finds no writer that populates a field's sortOrder. The sortOrder hits in ObjectManager.tsx are the object-level property, a different schema. So toFieldPayload emits sortOrder: undefined, JSON.stringify drops the key, and the PUT never carries it.

That is a one-line change away from being live: any designer that adds field reordering and persists an index — the obvious next feature for a drag-to-reorder field list — turns this into the #4644 shape (hard 422 INVALID_METADATA blocking every subsequent save of the object). The gate catches it as declared today precisely so the change that populates it is not the moment anyone finds out.

The likely resolutions, unadjudicated

This reads like the #4687 distance_metric shape — a declaration with zero readers and zero writers, where the right answer was to delete it. But there is a real alternative: the spec models field order by declaration order in the object's fields record, so a designer that wants explicit ordering may need to reorder that record rather than carry an index. Which of those is right, and whether DesignerFieldDefinition.sortOrder should survive as UI-only state, is not this card's call.

Note the two declarations differ in reach and may resolve differently: on DesignerFieldDefinition it is in-memory UI state; on FieldMetadataPayload it is on the wire.

Verification

pnpm check:designer-field-key-parity reports it; recorded in that gate's KNOWN_UNPARSEABLE_KEYS ledger pointing here. If it is deleted, the ledger entry must go with it — a stale entry is red too.

Refs: #5761 (the gate) · #4687 · #4644 · #6041 · #6043

[claude]

Concentrated triage batch: finding → pm:queue + domain:ui, Task, S — field-level sibling of the queued #6223 (object-level payload keys), same #5761 family: toFieldPayload writes sortOrder, FieldSchema rejects it by name, latent only because nothing populates it. Resolve per the #5761 resolution style (spec is authority — drop the key from the payload writer and both declaring types, or map it to a real spec concept if one exists; sortable is a different concept, do not conflate). Fold-or-serial with #6223 is a required answer at claim — same gate file, same family, both graded.

---

Generated by Claude Code

[os-support-ai]

Claimed + dispatched — and the required fold-or-serial answer is serial, already settled

domain:ui @ objectui execution seat, PM session session_011SfZeFWrhGLHmfq61xbz4q,
branch claude/issue-6045-field-payload-sortorder. All agents share one GitHub identity —
this comment's session ID is the claim, not the assignee.

The question triage required answering at claim

Fold-or-serial with #6223 is a required answer at claim — same gate file, same family, both
graded.

Serial, and #6223 has already landed (closed, state_reason: completed). ⭐ Better than
that: its landing wrote the answer into the code at the seam, on origin/main 854222c5e:

packages/app-shell/src/services/MetadataService.ts:41 // No `sortOrder` (objectui#6223): `ObjectSchema` has no object-level ordering
 :45 // field-level `sortOrder`, objectui#6045, which is still declared below.)
 :95 sortOrder?: number; ← the declaration
 :141 sortOrder: field.sortOrder, ← the payload writer

#6223 removed the object-level keys and deliberately left the field-level one, naming this
card as its owner. So there is nothing to fold — the predecessor split it on purpose and
documented the handoff where you will be working. ⛔ Do not re-open #6223's half.

⚠️ The conflation hazard, and there are two of them

Triage named one: "sortable is a different concept, do not conflate."

My census found a second, closer one: packages/app-shell/src/views/ObjectView.tsx:554 writes
sortOrder: sv.sortOrder, and :600 documents it as "sortOrder per saved view, in the new
order." ⭐ That is saved-view ordering — a different concept that happens to share the name.
⛔ It is not your target and must not be swept up. Census the shape (a field-metadata payload
key FieldSchema rejects), not the identifier sortOrder.

Resolution style — inherited, not invented

Per the #5761 family and #6223's landed treatment: spec is authority. Either drop the key from
the payload writer and both declaring types, or map it to a real spec concept if one
exists. ⛔ Do not keep it declared-but-unwritten, and ⛔ do not invent a spec concept to map onto.

The card notes this is latent only because nothing populates it — so confirm that on today's
tree before removing, and say so. If something now populates it, the card changes shape and that
is a stop-and-report.

Pre-dispatch gate

• (a) Whole thread read — one record, triage's grading. No prior claim.
• (b) Shadow check — in flight: finding(plugin-view): ObjectView's non-grid fetch NEVER injects $expand — the ref it reads the schema from is empty on the one run it makes #6419 (plugin-view), finding(plugin-grid): ObjectGrid's generateColumns() is untyped (any[]), so nothing type-checks what it writes into DataTableSchema.columns: TableColumn[] — the hole that hid #5853 and #5453 #6004 (plugin-grid), The other two sort-axis consumers still re-derive sortability from field type — ListView's sort picker and RelatedList #6108
  (plugin-list + packages/core/src/utils), getGanttConfig reads 24 more top-level keys ObjectGanttSchema does not declare — same defect as #5903, hidden by the index signature instead of a cast #6051 (plugin-gantt, same batch). None touches
  packages/app-shell. [Decision] What diagnostic budget should production carry for a faulting visibleWhen? Today a node-gate fault is entirely silent in a production bundle #6038 touched react/core/components and is in the merge queue.
• (c) Census above — ⛔ re-derive it; main is at 854222c5e and moves constantly.

Ghost-assertion guard

A removal has no new behaviour to pin, so use before/after readings with a positive control
(prove your search works against a key you know is present) and say so in the PR body rather than
inventing an assertion. If you do pin the rejection, prove it reds by putting the key back.

Deliver a draft PR with Fixes #6045. ⛔ Do not mark ready, ⛔ do not self-merge, ⛔ do not
enable auto-merge — the PM lands it.

---

Generated by Claude Code