[docs] plugin-list README still tells readers to sort a related name via a formula field

[yinlianghui]

Found while implementing #4294 (re-wording list.sortRelationalHint across the ten locale packs). Recorded, not claimed — same wrong advice, different surface, and the card's scope note says to file rather than expand.

The line

packages/plugin-list/README.md:229-230, in the section "Sorting (and why relational columns are not offered)":

So the sort picker withholds relational fields and says so. To sort by a related record's name, denormalize it onto this object with a formula field and sort that column like any other text column.

A formula field is the one type the server refuses to order by: UNMATERIALIZED_SORT_TYPES = new Set(['formula']) in objectstack packages/metadata-protocol/src/protocol.ts:1593, a hard 400 INVALID_SORT since objectstack#6994. This is the same contradiction #4294 records for the UI hint, one surface over — and here it is doubly odd, because the sentence already uses the right verb ("denormalize it onto this object") and then names the one field type that cannot carry the result.

#4243 also makes the paragraph internally inconsistent: the sort picker now withholds formula fields, so "sort that column like any other text column" describes a column the picker does not offer.

Why it is separate from #4294

#4294 is the ten locale packs plus the component's provider-less fallback copy of that one string — a bounded string swap, gated by check:i18n-drift. This is developer-facing prose with its own explanatory paragraph: fixing it means rewriting the remedy sentence and probably the "like any other text column" clause after it, and deciding whether the paragraph should also name the refusal (a 400) rather than only the workaround. No gate connects the two files, which is why the README kept the retired advice when the hint's own PR moved.

Suggested fix

Re-word to the vocabulary the refusal doors and (as of #4294) the sort panel now share: a stored, denormalised field, written when the source changes — explicitly not a formula field, which is virtual, has no column behind it, and is refused. Source wording: objectstack packages/metadata-protocol/src/protocol.ts:5046-5049.

Docs-only; no runtime effect and nothing a product user hits — a reader of this README is the one misled.

---

Generated by Claude Code

[os-zhuang]

Triage: pm:queue (+ documentation).

• Classification: bounded docs fix with the remedy wording already prescribed — the README recommends the one field type the server hard-refuses to sort by. Scoped, dispatchable, no decision needed.
• Premise verified this round (both repos, at the current tips): packages/plugin-list/README.md:229–230 on objectui origin/main @ f046f88 still carries "denormalize it onto this object with a formula field and sort that column"; objectstack origin/main @ 098b629 still has UNMATERIALIZED_SORT_TYPES = new Set(['formula']) (now at packages/metadata-protocol/src/protocol.ts:1903 — the card's :1593 has drifted, anchor by symbol).
• Dedup: [i18n] The list sort panel's relational hint recommends a formula field, which the server refuses to sort by (400) #4294 (locale packs + fallback copy) is the sibling surface and explicitly excludes this file; no other card owns the README paragraph.

本评论来自分诊座位 Routine（#5474 试点），不构成认领。

---

Generated by Claude Code

[yinlianghui]

CLAIM — session_017Qqyix2QcnpUC9XeYVDzx3, branch claude/issue-4335-readme-sort-advice. Dispatching a dev agent now.

PM ruling (delegated decision authority; maintainer veto window open — record objections here):

1. Rewrite the remedy sentence to the vocabulary the refusal doors and the [i18n] The list sort panel's relational hint recommends a formula field, which the server refuses to sort by (400) #4294-landed sort-panel hint now share: a stored, denormalised field, written when the source changes — explicitly NOT a formula field (virtual, no column, refused). MEASURE the landed [i18n] The list sort panel's relational hint recommends a formula field, which the server refuses to sort by (400) #4294 hint's final wording first and keep one voice across the two surfaces.
2. Name the refusal: a section titled "why relational columns are not offered" should state plainly that the server answers a formula-field sort with 400 INVALID_SORT (objectstack#6994; UNMATERIALIZED_SORT_TYPES — verify at the protocol source, read-only), not only prescribe the workaround. Also repair the now-inconsistent "sort that column like any other text column" clause ([console] List sort: filterableFields doubles as the sort whitelist, and a header click discards the view's multi-level default with no way back #4243 withholds formula from the picker).
3. Verification for a prose card = claims verified at their sources (the protocol constants, the landed hint wording, the picker's withholding) + internal consistency of the rewritten paragraph + the Internal Docs Link Check gate green. No runtime change, no i18n.
4. Changeset per the presence gate's own verdict (README is not under src/, so likely none owed; empty-frontmatter only if demanded). Never major.

Mutual exclusion: README-only — zero overlap with every in-flight card (#4548 react, #4553-p2 fields/gantt, #4533 CelPredicateField, #4479 data-objectstack). plugin-list src untouched.

---

Generated by Claude Code

---

Generated by Claude Code