docs(plugin-list): the sort remedy names a stored denormalised field — not the formula type the server refuses (#4335)

[yinlianghui]

Fixes #4335

packages/plugin-list/README.md, section "Sorting (and why relational columns are not offered)", prescribed the one field type the server hard-refuses to order by — and the sentence after it described a column the picker no longer offers. Docs-only: one file, no runtime change, no strings, no tests.

Before

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 relational field that the view's
CURRENT sort already uses stays listed, labelled `(by ID)`, so existing view
metadata round-trips instead of silently losing its sort.

After

So the sort picker withholds relational fields and says so. To sort by a related
record's name, denormalize that name onto this object as a **stored field,
written when the source changes**, then sort by that field — the remedy the
server's own refusal prescribes, in the same words the sort panel's hint uses.

**Not a formula field.** A formula value is computed on read, so no driver
materializes a column behind it, and since `objectstack#6994` the server answers
a sort that names one with a hard `400 INVALID_SORT` (before that it degraded
silently: the rows came back in an arbitrary order under a `200`, `asc` and
`desc` identical). The picker withholds formula fields for the same reason
(`objectui#4243`), so there is no formula column here to sort "like any other
text column" — the column you sort is the stored one the denormalization writes.

A field the view's CURRENT sort already uses stays listed under both rules —
relational ones labelled `(by ID)` — so existing view metadata round-trips
instead of silently losing its sort, and a sort the server would refuse can
still be edited away in the picker that otherwise hides its field.

Every factual claim, verified at its source

Read-only, at objectui origin/main @ a90888230 and objectstack origin/main @ 5d24f4b94.

1. "denormalize ... as a stored field, written when the source changes" is the shared vocabulary. Measured first, per the ruling. The landed [i18n] The list sort panel's relational hint recommends a formula field, which the server refuses to sort by (400) #4294 hint — packages/i18n/src/locales/en.ts list.sortRelationalHint, byte-identical to the provider-less fallback in packages/plugin-list/src/ListView.tsx — reads: "To sort by that name, denormalize it onto this object as a stored field, written when the source changes, and sort by that. Not a formula field: it is virtual, so no column is stored for it and the server refuses to sort by one." The server's refusal hint (objectstack packages/metadata-protocol/src/protocol.ts) says the same thing in the same words: "Denormalise the value onto '${object}' (a stored field, written when the source changes) and sort by that. A formula field is virtual: with no column behind it the ORDER BY reaches the driver, finds nothing, and is dropped." The README now uses that vocabulary too, so the three surfaces read as one voice.

2. "a hard 400 INVALID_SORT". objectstack protocol.ts: UNMATERIALIZED_SORT_TYPES is new Set(['formula']); the sort gate filters the requested names through it and, on a hit, throws via invalidSortError, which sets err.status = 400 and err.code = 'INVALID_SORT'. Cited by behavior, not line number — the card's :1593 and the triage comment's :1903 disagree, and the constant is what is stable.

3. "since objectstack#6994" — the refusal branch is introduced by a comment naming that issue as "the third verdict on this axis".

4. "before that it degraded silently: ... arbitrary order under a 200, asc and desc identical". The same comment carries the measurement that motivated the refusal: a formula orderBy returned five rows under a 200 in an order matching neither direction, with asc and desc byte-identical.

5. "The picker withholds formula fields for the same reason (objectui#4243)". ListView.tsx: UNSORTABLE_FIELD_TYPES = new Set(['formula']), and the sortFields memo pushes a field only when it is neither relational nor in that set — so the old "sort that column like any other text column" named a column the picker does not list. That is what the repaired clause now says.

6. "stays listed under both rules ... a sort the server would refuse can still be edited away". Same memo: the inUse exception applies to both the relational and the unsortable branch, and only relational entries get the (by ID) suffix (list.sortByIdSuffix). The README previously described this exception as relational-only.

Verification

node scripts/check-control-bytes.mjs
  OK (scanned 4309 tracked text file(s); skipped 85 binary).
node scripts/check-doc-links.mjs
  Links are valid across 13 scan roots.
node scripts/check-changeset-presence.mjs
  Compared the working tree with a90888230 (merge-base with origin/main): 1 file(s)
  changed, 0 of them under the src/ of a package the release covers, 0 under a package
  changesets ignores, 0 changeset(s) added.
  No source of a released package changed in this range, so no changeset is owed.

Plus a self-scan of the edited file for raw control bytes beyond the gate's surface — grep -naP over the x00-x08 / x0b / x0c / x0e-x1f / x7f range: no matches. eslint / tsc / vitest are not implicated by a .md-only change and were not run.

Changeset: none — the presence gate's own verdict, quoted above. README.md is not under a package's src/.

Surface

packages/plugin-list/README.md only (16 insertions, 4 deletions, one file). No locale packs, no src, no content/docs/releases/.

Out of scope, filed not fixed

#4559 — ListView.tsx's own comment above the sortFields memo still calls a formula field "the supported alternative ... which sorts like any text column", describing a hint that has said the opposite since #4294 and code that filters it out. Observation-class (a comment; nothing renders it), so finding, unassigned, no pm:queue.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectui	Ignored		Aug 13, 2026 9:11am

[github-actions]

✅ Console Performance Budget

Metric	Value	Budget
Main entry (gzip)	24.7 KB	350 KB
Entry file	index-Dnkledme.js	—
Status	PASS	—

---

📦 Bundle Size Report

Package	Size	Gzipped
app-shell (index.js)	9.56KB	3.59KB
app-shell (runtime-config.js)	7.42KB	2.32KB
app-shell (types.js)	0.01KB	0.04KB
app-shell (urlParams.js)	8.92KB	3.41KB
auth (AuthContext.js)	0.31KB	0.24KB
auth (AuthGuard.js)	1.17KB	0.53KB
auth (AuthProvider.js)	25.13KB	5.40KB
auth (AuthShell.js)	3.49KB	1.40KB
auth (ForgotPasswordForm.js)	12.21KB	3.45KB
auth (LoginForm.js)	18.13KB	5.39KB
auth (PreviewBanner.js)	0.90KB	0.50KB
auth (RegisterForm.js)	6.64KB	2.21KB
auth (SocialSignInButtons.js)	9.60KB	3.89KB
auth (UserMenu.js)	3.40KB	1.22KB
auth (auth-gate-events.js)	1.29KB	0.66KB
auth (authStyles.js)	5.04KB	1.72KB
auth (createAuthClient.js)	38.46KB	10.17KB
auth (createAuthenticatedFetch.js)	6.34KB	2.43KB
auth (index.js)	2.35KB	1.07KB
auth (org-roles.js)	6.66KB	2.78KB
auth (phone-identifier.js)	1.11KB	0.66KB
auth (types.js)	0.59KB	0.35KB
auth (useAuth.js)	5.02KB	0.88KB
auth (useIsWorkspaceAdmin.js)	1.61KB	0.85KB
collaboration (CommentThread.js)	26.07KB	7.56KB
collaboration (LiveCursors.js)	3.17KB	1.27KB
collaboration (PresenceAvatars.js)	6.49KB	2.64KB
collaboration (PresenceProvider.js)	2.79KB	1.13KB
collaboration (index.js)	1.65KB	0.73KB
collaboration (useCollaborationTranslation.js)	6.05KB	2.52KB
collaboration (useCommentSearch.js)	1.98KB	0.88KB
collaboration (useConflictResolution.js)	7.75KB	1.86KB
collaboration (useMentionNotifications.js)	1.81KB	0.68KB
collaboration (usePresence.js)	6.33KB	1.84KB
collaboration (useRealtimeSubscription.js)	7.91KB	2.01KB
components (index.js)	489.32KB	108.45KB
core (index.js)	3.37KB	1.34KB
create-plugin (index.js)	10.08KB	3.26KB
data-objectstack (index.js)	158.47KB	43.13KB
fields (index.js)	230.18KB	57.13KB
i18n (LocalizationContext.js)	1.76KB	0.96KB
i18n (currency.js)	1.22KB	0.64KB
i18n (i18n.js)	4.32KB	1.77KB
i18n (index.js)	3.35KB	1.38KB
i18n (pickLocalized.js)	3.69KB	1.73KB
i18n (provider.js)	23.12KB	7.62KB
i18n (useDisplayLocale.js)	2.84KB	1.45KB
i18n (useObjectLabel.js)	27.59KB	6.63KB
i18n (useSafeTranslation.js)	7.77KB	3.13KB
layout (index.js)	38.98KB	10.85KB
mobile (MobileProvider.js)	0.92KB	0.49KB
mobile (ResponsiveContainer.js)	0.94KB	0.38KB
mobile (breakpoints.js)	1.51KB	0.70KB
mobile (createOfflineDataSource.js)	5.61KB	1.74KB
mobile (index.js)	1.50KB	0.62KB
mobile (offlineQueue.js)	3.91KB	1.35KB
mobile (pwa.js)	0.97KB	0.49KB
mobile (serviceWorker.js)	1.48KB	0.62KB
mobile (serviceWorkerSource.js)	3.41KB	1.48KB
mobile (useBreakpoint.js)	1.54KB	0.65KB
mobile (useGesture.js)	6.96KB	1.98KB
mobile (useOfflineSync.js)	1.99KB	0.72KB
mobile (usePullToRefresh.js)	2.53KB	0.85KB
mobile (useResponsive.js)	0.71KB	0.42KB
mobile (useResponsiveConfig.js)	1.36KB	0.63KB
mobile (useSpecGesture.js)	4.32KB	1.64KB
mobile (useTouchTarget.js)	1.01KB	0.54KB
permissions (MePermissionsProvider.js)	8.75KB	3.06KB
permissions (PermissionContext.js)	0.31KB	0.25KB
permissions (PermissionGuard.js)	0.89KB	0.45KB
permissions (PermissionProvider.js)	3.67KB	1.12KB
permissions (evaluator.js)	4.41KB	1.44KB
permissions (index.js)	0.91KB	0.41KB
permissions (store.js)	0.91KB	0.42KB
permissions (useFieldPermissions.js)	1.28KB	0.52KB
permissions (usePermissions.js)	1.55KB	0.71KB
plugin-ai (index.js)	15.75KB	3.80KB
plugin-calendar (index.js)	46.86KB	12.91KB
plugin-charts (index.js)	62.10KB	17.67KB
plugin-chatbot (index.js)	181.21KB	43.14KB
plugin-dashboard (index.js)	120.95KB	31.53KB
plugin-designer (index.js)	212.58KB	42.83KB
plugin-detail (index.js)	239.88KB	59.99KB
plugin-editor (index.js)	2.46KB	1.10KB
plugin-form (index.js)	114.58KB	27.68KB
plugin-gantt (index.js)	164.28KB	40.02KB
plugin-grid (index.js)	189.36KB	50.33KB
plugin-kanban (index.js)	52.74KB	14.53KB
plugin-list (index.js)	111.13KB	27.12KB
plugin-map (index.js)	18.16KB	5.81KB
plugin-markdown (index.js)	13.72KB	4.69KB
plugin-report (index.js)	41.16KB	10.96KB
plugin-timeline (index.js)	26.68KB	7.66KB
plugin-tree (index.js)	8.50KB	2.88KB
plugin-view (index.js)	84.08KB	20.55KB
providers (DataSourceProvider.js)	0.75KB	0.39KB
providers (MetadataProvider.js)	1.37KB	0.59KB
providers (ThemeProvider.js)	1.90KB	0.85KB
providers (UploadProvider.js)	11.71KB	3.53KB
providers (index.js)	0.44KB	0.22KB
providers (types.js)	0.01KB	0.04KB
react-runtime (index.js)	5.67KB	2.37KB
react (LazyPluginLoader.js)	3.77KB	1.33KB
react (SchemaRenderer.js)	23.73KB	7.96KB
react (data-invalidation.js)	5.05KB	2.08KB
react (index.js)	1.23KB	0.66KB
react (spec-input.js)	0.20KB	0.18KB
sdui-parser (codegen.js)	4.09KB	1.74KB
sdui-parser (index.js)	4.47KB	2.03KB
sdui-parser (parse.js)	10.04KB	2.82KB
sdui-parser (types.js)	0.29KB	0.24KB
sdui-parser (validate.js)	4.69KB	1.48KB
types (ai.js)	0.20KB	0.17KB
types (api-types.js)	0.20KB	0.18KB
types (app.js)	2.87KB	0.99KB
types (base.js)	0.20KB	0.18KB
types (blocks.js)	0.20KB	0.18KB
types (complex.js)	0.20KB	0.18KB
types (crud.js)	0.20KB	0.18KB
types (dashboard-filter-alias.js)	6.23KB	2.74KB
types (data-display.js)	0.20KB	0.18KB
types (data-protocol.js)	0.20KB	0.19KB
types (data.js)	0.20KB	0.18KB
types (designer.js)	1.87KB	0.85KB
types (disclosure.js)	0.20KB	0.18KB
types (error-code.js)	1.54KB	0.88KB
types (feedback.js)	0.20KB	0.18KB
types (field-types.js)	0.20KB	0.18KB
types (form.js)	0.20KB	0.18KB
types (http-retry.js)	4.32KB	2.02KB
types (index.js)	3.05KB	1.52KB
types (layout.js)	0.20KB	0.18KB
types (managed-by.js)	0.19KB	0.18KB
types (mobile.js)	2.59KB	1.31KB
types (navigation.js)	0.20KB	0.18KB
types (objectql.js)	0.20KB	0.18KB
types (overlay.js)	0.20KB	0.18KB
types (permissions.js)	0.20KB	0.18KB
types (plugin-scope.js)	0.20KB	0.18KB
types (record-components.js)	0.20KB	0.19KB
types (record-semantics.js)	1.28KB	0.67KB
types (registry.js)	0.20KB	0.18KB
types (reports.js)	0.20KB	0.18KB
types (spec-report.js)	5.05KB	1.93KB
types (system-fields.js)	3.33KB	1.54KB
types (theme.js)	0.20KB	0.18KB
types (ui-action.js)	3.40KB	1.71KB
types (views.js)	0.20KB	0.18KB
types (widget.js)	0.20KB	0.18KB

Size Limits

• ✅ Core packages should be < 50KB gzipped
• ✅ Component packages should be < 100KB gzipped
• ⚠️ Plugin packages should be < 150KB gzipped

[yinlianghui]

PM step-7 复核 — ACCEPT (session_017Qqyix2QcnpUC9XeYVDzx3)

• Every factual claim in the rewritten paragraph is verified at its source and quoted — including the discovery that the server's own invalidSortError hint deliberately shares its remedy wording with the [i18n] The list sort panel's relational hint recommends a formula field, which the server refuses to sort by (400) #4294 sort-panel hint, which the README now joins: three surfaces, one voice. The line-number disagreement between the card and the triage note was resolved by measurement (the card was right) and made irrelevant by citing the constant and the behavior, not a line.
• The declared scope extension is correct: the (by ID) round-trip sentence described the picker's in-use exception as relational-only when the memo applies it to BOTH rules — and for a refused formula sort that exception is the only way to edit the sort away. Fixing one clause without the other would have left the paragraph inconsistent one sentence over.
• The skip-changeset investigation is a model of gate literacy: the label object exists but nothing reads it (.github/WORKFLOWS.md documents 5 workflows that do not exist and omits 9 that do — including a changeset gate and a skip-changeset label neither of which is real #3724 deleted the phantom inventory that claimed otherwise), so applying it would have risked clobbering the bot's labels for zero gate effect. Correctly not written; the presence gate's own no-changeset-owed verdict quoted instead.
• Resource discipline noted: an .md-only change ran the three relevant node gates without a pnpm install. CI 18/18 green on per-job conclusions. Finding [finding] ListView.tsx's own comment still says the relational hint "points at the supported alternative (a formula field)" — the hint says the opposite since #4294 #4559 (the ListView comment carrying the last surviving copy of the retired advice) filed properly as observation-class.

Auto-merge armed (squash) — landing verified per the merge-queue discipline.

---

Generated by Claude Code

---

Generated by Claude Code