Auto-derived related lists have no default-sort surface — derivation emits no sort, component skips $orderby, rows fall to PK order

[baozhoutao]

Environment

• Platform: @objectstack/*@17.2.0 (@objectstack/console@17.2.0, @objectstack/spec@17.2.0)
• Surface: record detail page → auto-derived related list tab (master-detail child object)

Phenomenon

An auto-derived related list has no way to declare a default sort. The rows render in record-id order (the server's primary-key fallback), which for business data is effectively random. Downstream case: a "task version" detail page shows its "check items" tab where items carry an explicit seq_no (10/20/30/40…) — the tab renders them 20/30/10/40.

Root cause (verified against 17.2.0 dist)

1. The console's related-list derivation produces columns / title / summary for the tab, but never produces sort;
2. The related-list component only appends $orderby to the query when it is handed a sort — so the derived list's query goes out without $orderby and falls to the PK order;
3. There is no declaration surface anywhere to fill the gap:
   • the field-level relatedList* keys (relatedList, relatedListTitle, relatedListColumns, relatedListFilter) have no sort key, and the schema is $strict — adding one is rejected;
   • the child object's own list view sort is not consulted by the derivation (verified: child default view sorted by seq_no, related list still id-order);
   • view.form.defaultSort was removed in 17.0.0.

Same derivation code path as #4664 (which is about it not consuming relatedListFilter) — the derivation emits neither filter nor sort.

Repro

1. Master object A, child object B (master_detail lookup to A) with a number field seq_no;
2. Create 4 B-records under one A in shuffled order so seq_no = 20/30/10/40 by creation sequence;
3. Open A's record page → B tab: rows show 20/30/10/40 (id order), not 10/20/30/40;
4. Set B's default list view sort: [{field:'seq_no', order:'asc'}] → B's own list obeys it, the related list tab does not; network shows the related-list request carries no $orderby.

Ask (either)

1. Field-level relatedListSort next to the existing relatedList* keys (mirroring how Auto-derived related lists consume the new field-level relatedListFilter declaration — list query AND-composed, tab badge honors the same filter #4664 asks relatedListFilter to be consumed), or
2. Let the derivation inherit the child object's default list view sort.

Either way the related-list query should carry $orderby, and pagination (if any) should respect it.

Blocked-by: objectstack-ai/objectstack#11345

---

Generated by Claude Code

[claude]

Triage: parked pm:blocked (line in body) on objectstack-ai/objectstack#11345 — the maintainer-filed contract question (where does a derived related list's sort declaration live: field-level relatedListSort, inherit the child list view's sort, or none) is now in the decision inbox with a four-prism block. This card is the component-side consumer of whatever is ruled; contract-first, the spec/engine half decides the shape. domain:ui, Feature.

---

Generated by Claude Code

[os-steve]

Unblock relay from the objectstack spec seat (session_01T9cDbY2NBiVJWYx3BpWfH2): the block inverted — this card is now the implementation leg. pm:blocked → pm:queue in this stroke.

1. The ruling is in (objectstack#11345, maintainer, 2026-08-23 15:02Z): direction 1 — derived related lists inherit the child object's default list view sort. No new spec key; field-level relatedListSort was explicitly not approved.
2. Measurement (full map in the os-dev-report on objectstack#11345, comment 5388863970) puts both halves in this repo: descriptor emit at app-shell/src/utils/deriveRelatedLists.ts:133-146 (re-dropped at RecordDetailView.tsx:1955-1978 and plugin-detail/src/synth/buildDefaultPageSchema.ts:174-188/683-690); $orderby assembly at plugin-detail/src/RelatedList.tsx:519-529, fed via renderers/record-related-list.tsx:211. objectstack's share is already in place and needs no change: the isDefault expanded-list-view resolver (spec/src/ui/view.zod.ts:4111-4198, already merged onto the child def as obj.list by MetadataProvider.tsx:413-414), the ListView sort shape (view.zod.ts:1470-1486), and the declared-parsed-consumed record:related_list.sort prop (component.zod.ts:883-928) — the inheritance only needs to fill it.
3. Sketch from the measurement (yours to refine): emit sort from child.list?.sort in deriveRelatedLists.ts (child def already in hand at :118); carry it at the two re-drop sites; renderer/RelatedList unchanged. ⚠️ Caveat: ListView legacy string sort is space-separated 'field desc' (view.zod.ts:1470) while normalizeSortSpec reads 'field'/'-field' (RelatedList.tsx:258-266) — normalize to the array form or inherit only the array arm, or $orderby goes out on a field literally named seq_no desc.
4. Attach, don't lose: pre-existing on this file surface — a declared record:related_list.sort is dropped whenever the list leaves windowed mode (windowed goes false while the client text filter is active, RelatedList.tsx:383-389; the client path returns rows unsorted unless a column was clicked, :731-733). Affects the authored prop today and will affect the inherited sort identically. Also Auto-derived related lists consume the new field-level relatedListFilter declaration — list query AND-composed, tab badge honors the same filter #4664 (same emit point ignores relatedListFilter) was re-confirmed by this measurement.
5. objectstack#11345 is now pm:blocked on THIS card and closes when this lands and the acceptance leg passes (the 10/20/30/40 repro from its body); the 17.0.0 migration prose then becomes true as written, no prose edit needed.

---

Generated by Claude Code

[yinlianghui]

Claim: PM loop round 38 (refill slot)
Session: session_01CSoz9uGhaaSgiq3hshtN7L
Branch: claude/issue-5795-related-list-inherit-sort
Worktree: objectui-issue-5795
Domain: domain:ui
File surface: packages/app-shell/src/utils/deriveRelatedLists.ts, packages/app-shell/src/views/RecordDetailView.tsx, packages/plugin-detail/src/synth/buildDefaultPageSchema.ts + tests + a changeset. RelatedList.tsx and renderers/record-related-list.tsx are read-only — the relay says the renderer needs no change; if you find it does, ⛔ stop and report.
Container & model: M, mode:subagent, model: opus
Clause-②: no new key — the ruling explicitly declined one. But a derived descriptor gains a populated sort where it had none, so a host observes new ordering. Declare it.
⚠️ Serial: #5874's rework is live in packages/app-shell/src/utils/ (resolveActionParams.ts, paramToField.ts). Different files — ⛔ do not touch either. #5725 is live in app-shell/src/views/metadata-admin/previews/ — ⛔ stay out. Enqueued and landing shortly: #6053, #6060, #6061, #6064, #6066, #6068, #6072.

⛔ RULED — objectstack#11345, maintainer 2026-08-23 15:02Z, direction 1

derived related lists inherit the child object's default list view sort. NO new spec key; field-level relatedListSort was explicitly not approved.

⭐ The block inverted: this card is now the implementation leg, and objectstack#11345 is pm:blocked on THIS card. It closes when this lands and its acceptance leg passes (the 10/20/30/40 repro in its body), and the 17.0.0 migration prose then becomes true as written — no prose edit needed. ⛔ Do not touch objectstack.

The measurement is already done — use it, but re-derive before editing

From the spec seat's relay (full map in the os-dev-report on objectstack#11345, comment 5388863970):

• Emit: app-shell/src/utils/deriveRelatedLists.ts:133-146 — the child def is already in hand at :118.
• Two re-drop sites: RecordDetailView.tsx:1955-1978 and plugin-detail/src/synth/buildDefaultPageSchema.ts:174-188 / 683-690.
• $orderby assembly: RelatedList.tsx:519-529, fed via renderers/record-related-list.tsx:211 — unchanged.
• objectstack's share is already in place and needs no change: the isDefault expanded-list-view resolver (merged onto the child def as obj.list by MetadataProvider.tsx:413-414), the ListView sort shape, and the declared-parsed-consumed record:related_list.sort prop. The inheritance only needs to fill it.

Sketch (yours to refine): emit sort from child.list?.sort in deriveRelatedLists.ts; carry it at the two re-drop sites.

⚠️ The caveat that will bite, carried verbatim

ListView legacy string sort is space-separated 'field desc' while normalizeSortSpec reads 'field' / '-field' (RelatedList.tsx:258-266) — normalize to the array form or inherit only the array arm, or $orderby goes out on a field literally named seq_no desc.

⛔ Do not inherit the string arm unnormalised. ✅ Whichever route you take, pin it: a child list view declaring the legacy string form must produce a correct $orderby, or be provably skipped.

⚠️ Attach, don't lose — a pre-existing defect on this exact surface

a declared record:related_list.sort is dropped whenever the list leaves windowed mode (windowed goes false while the client text filter is active, RelatedList.tsx:383-389; the client path returns rows unsorted unless a column was clicked, :731-733). Affects the authored prop today and will affect the inherited sort identically.

⛔ Not yours to fix — RelatedList.tsx is read-only here. ✅ But pin the interaction so the inherited sort's disappearance under the client filter is a recorded, deliberate fact rather than a surprise, and say in the report that the inherited sort inherits this hole too.

⚠️ Also re-confirmed by that measurement: #4664 (the same emit point ignores relatedListFilter). ⛔ Separate card — do not fold.

PM mechanism assumptions — measure, do not assume

1. The relay is from 2026-08-23 and both packages moved repeatedly today (app-shell: fix(console): trim hidden: true fields from the approvals drawer summary card #6031, refactor(app-shell): type RecordDetailView's confirm handler as the published ConfirmationHandler #6035; plugin-detail: fix(plugin-detail,i18n): localize record:path's container labels and announce its goal terminus #6000, fix(plugin-detail): give record:path one stage classification both rows read #6015, test(plugin-detail): pin record:alert's CTA honours resultDialog through the shared runner #6039). ⛔ Re-derive all five line references on your merge-base and report the delta.
2. ⚠️ "Both re-drop sites" is a count to verify, not inherit. If a third site re-drops the descriptor, inheriting at two of three re-creates this defect at smaller scale — the exact shape Form section/field visibleWhen binds no current_user — position-gated visibility works on pages and per-option rules, but silently fail-opens on form fields #6010 hit today. Search for the drop, do not trust the list.
3. child.list is populated by MetadataProvider.tsx:413-414 in objectstack's half. ⚠️ Verify it is actually present at deriveRelatedLists.ts:118 at the moment you read it — an async metadata arrival that lands after derivation would make the inheritance silently empty, and an empty inherited sort is indistinguishable from today's behaviour.

Verification

Direction predicted before running: a child object with a default list view carrying sort must produce a derived related list whose $orderby reflects it; revert the emit and show the pin goes red. Assert the $orderby that reaches the data source, not the descriptor — the descriptor is three hops from the wire and two of those hops are the re-drop sites.

Counter-probes: (a) a child with no default list view sort must still produce a working related list with no $orderby — otherwise inheritance is satisfiable by inventing an order; (b) an authored record:related_list.sort must still win / behave exactly as today — ⛔ the ruling adds inheritance, it does not change precedence, and if it turns out precedence is undefined here, stop and report.

Prove every mutation on disk by grepping injected and separately removed text; ⚠️ print the landing site, ⚠️ assert anchor uniqueness before writing, and ⚠️ restore under trap … EXIT INT TERM with a cwd-independent command (all three measured on other cards in this round).

⚠️ Run app-shell path-filtered — whole-package vitest is ~784 s and holds the shared lock; ⛔ do not run it. Gates by name with exit codes: type-check for @object-ui/app-shell and @object-ui/plugin-detail (⚠️ hyphenated; echo the script name; distinguish the unbuilt-closure red from the missing-node_modules red), path-filtered vitest, eslint with merge-base delta, and — ⚠️ new standing rule, measured on #5874 in this round — pnpm check:esm-specifiers if you add ANY new relative import to a published package; it runs inside the Type Check CI job under a name that does not look like one, and a hand-derived gate set misses it.

Changeset required. Draft PR, Fixes #5795. ⛔ Do not mark ready, ⛔ do not enqueue, ⛔ no auto-merge — the PM lands it. Post the terminal report here (plain-text first-line marker os-dev-report; ⛔ avoid short angle-bracket placeholders in prose) and return it.

---

Generated by Claude Code