派生相关列表(relatedList:'primary')查询不带 $orderby 且无任何排序声明位;17.0.0 defaultSort 迁移说明与实测矛盾

[baozhoutao]

一句话:由字段级 relatedList:'primary' 自动派生的相关列表,列表查询不带任何 $orderby(行序 = 记录 id 兜底序),而 17.2.0 没有给这类相关列表任何排序声明位;且 17.0.0 移除 view.form.defaultSort 时的迁移说明「a related list inside a form sorts by its own list view's sort」与 17.2.0 实测行为不符。请求提供排序能力(字段级 relatedListSort,或让派生相关列表真正继承子对象列表视图的 sort)。

复现(17.2.0,真机 Console UI)

1. 父对象 task_version,子对象 task_version_check_item 通过 lookup 字段声明 relatedList:'primary'(带 relatedListColumns);子对象有字段 seq_no(顺序号)。
2. 子对象自身的列表视图声明 sort: [task_code asc, seq_no asc]。
3. 在父记录详情页的派生相关列表下,按创建顺序 40 / 10 / 30 / 20 建 4 条子记录(顺序号故意与创建序不同)。
4. 观察页签行序:既非 seq_no 序也非创建序,逐条比对后确认是记录 id 升序 —— 即服务端在无 $orderby 时的兜底主键序。若迁移说明成立(继承子对象视图 sort),行序应为 10/20/30/40。

逐层核实过的可声明面(17.2.0)

1. 字段级:相关列表家族只有 relatedList / relatedListTitle / relatedListColumns / relatedListFilter(17.2.0 新增)四键,无排序键;字段 schema strict,自造 relatedListSort 被校验拒绝。
2. 视图级:子对象列表视图的 sort 实测不作用于派生相关列表(见复现第 4 步)。
3. 表单级:view.form.defaultSort 已在 17.0.0 移除(schema 现为 ZodNever),但当时迁移说明原话是「a related list inside a form sorts by its own list view's sort」——与第 2 条实测矛盾,两者必有一处需要修正(实现补上继承,或迁移说明改口)。
4. 渲染层:console 17.2.0 由对象 schema 派生相关列表时,产出的描述符只有 childObject / referenceField / title / columns / isPrimary,不产出 sort;相关列表组件仅在拿到 sort 时才拼 $orderby。顺带:同一段派生代码也未消费 17.2.0 新增的 relatedListFilter(spec 已开、console 未跟,近似旧单 record:related_list.filter 声明了却无人读:RelatedList 的列表查询只按父关系过滤,作者写的 filter(以及 dataSource 合成出的 filter)整条丢弃 #7118 的 filter 不消费问题,但那单针对的是 page 块 record:related_list.filter)。

请求

二选一即可解除应用侧阻塞:

• A. 字段级新增 relatedListSort(与 relatedListColumns 同族),派生描述符与组件消费之;
• B. 派生相关列表继承子对象默认列表视图的 sort(即让 17.0.0 迁移说明成立)。

应用侧影响

steedos-labs/os-project-titanwind-ehr#1746(任务检查项按顺序号显示)因此挂起;项目侧唯一替代路径是 type:'record'+kind:'slotted' 整页接管页签区,爆炸半径远超一条默认排序,已按「等平台不绕行」纪律冻结。

[claude]

Triage: needs-user-decision, domain:spec, Feature —— 排序声明位是契约形状提案(spec 面新增键 或 语义继承规则),人工地板。维护者亲filed,复现完整(17.2.0 真机)。姊妹卡 objectui#5795(组件侧同一现象)已并挂 pm:blocked 指向本卡 —— 单一派发入口在此。

四维分析(中文):

• 实际业务需求 — 真实业务数据(检查项 seq_no)在派生相关列表里按记录 id 兜底序渲染,对用户等于随机序;复现在维护者自己的应用上,拉动为实。
• 项目长远合理性 — 17.0.0 移除 view.form.defaultSort 时的迁移说明(「相关列表按子对象列表视图自身 sort 排序」)与 17.2.0 实测不符 —— 要么兑现迁移说明(继承路线),要么给新声明位;维持「说明与行为都不成立」最伤。
• 防 AI 写代码犯错 — 迁移说明 declared≠enforced 正是 AI 消费文档时会照抄出错的形状;继承路线零新键、语义可从现有文档推出,新键路线则要同步 spec/引擎/UI 三面,漏一面就是新的半声明。
• 创业阶段不扩散需求 — 继承子对象列表视图 sort(兑现既有迁移说明)不新增任何 spec 面;字段级 relatedListSort 是新键扩面,仅当继承语义确实不够表达(同一子对象在不同父视图要不同排序)才值得付。

选项:1) 派生查询继承子对象列表视图的 sort(兑现 17.0.0 迁移说明,零新键);2) 新增字段级 relatedListSort 声明位(spec 契约扩面,条款②);3) 两者皆做(继承为默认,字段级覆写)。
推荐:方向 1 —— 零扩面、兑现已发布的迁移承诺、修复 declared≠enforced;若维护者判「同一子对象不同父上下文需不同排序」是真需求,再走 3 的覆写增量。

---

Generated by Claude Code

[claude]

Maintainer ruling recorded (atomic four-part write)

Ruled 2026-08-23, live PM chat, verbatim: 「10950 不考虑存量，其他接受你的建议」 — this card falls under the accepted recommendations. Ruled: direction 1 — derived related lists inherit the child object's list view sort; no new spec key. This honours the published 17.0.0 migration note (declared becomes enforced). needs-user-decision → pm:queue in the same stroke. Dispatch notes: locate the derivation emit point first (fix lands where the derived query is built); the 17.0.0 migration prose and 17.2.0 behavior must end up agreeing; objectui#5795 stays parked on this card and returns via the unlock scan as the UI-side acceptance leg when this closes. Field-level relatedListSort was NOT approved — do not add a key.

---

Generated by Claude Code

[os-steve]

Claim: PM seat session_01T9cDbY2NBiVJWYx3BpWfH2 (/pm-dispatch, spec lane) — dispatching to an os-dev subagent under the recorded maintainer ruling (2026-08-23 15:02Z, direction 1: derived related lists inherit the child object's list view sort; no new spec key — relatedListSort NOT approved).
Session: session_01T9cDbY2NBiVJWYx3BpWfH2
Branch: claude/issue-11345-related-list-inherit-sort
Worktree: ../objectstack-11345 (created by the dev agent, per-task)
Domain: domain:spec
File surface: measurement-first — the ruling's dispatch note says locate the derivation emit point before fixing (where the derived related-list descriptor/query is built). If the emit point lives in THIS repo (server/client SDK side), the fix lands here + the 17.0.0 migration prose must end up agreeing with behaviour. If it lives in objectui's console/renderer, the dev STOPS with the measured locations and zero objectstack-side implementation — this seat then routes the execution leg (scope order: this seat handles spec@objectstack only; objectui#5795 stays parked on this card either way).
Container & model: os-dev subagent, opus (cross-layer measurement + inheritance semantics).
Clause-②: not expected — the ruling adds NO spec key; inheritance is behaviour at the derivation site + prose truth. If the fix turns out to require a packages/spec/src/** diff (e.g. describe/prose on the relatedList family), the path limb applies: stop at PR-draft and report for contract review.
Serial constraints: none against in-flight #11287 (i18n-resolver) / #11307 (object.zod.ts annotation).

---

Generated by Claude Code

[os-steve]

os-dev-report

Route: STOP — the emit point lives wholly in objectui. Zero objectstack-side implementation, no branch, no PR. Phase 1 measurement below is read-only and complete; every claim in the card's section 4 is confirmed at file:line.

Ruling honoured

Ruled: direction 1 — derived related lists inherit the child object's list view sort; no new spec key. This honours the published 17.0.0 migration note (declared becomes enforced). … Field-level relatedListSort was NOT approved — do not add a key.

Nothing was added, nothing was edited. The measurement confirms direction 1 is reachable with no new spec key: the descriptor slot it needs is already declared and already consumed (see "contract channel" below).

Measurement map

(a) Descriptor derivation — objectui

• objectui/packages/app-shell/src/utils/deriveRelatedLists.ts:48-67 — DerivedRelatedList: childObject / childLabel / referenceField / title? / columns? / isOwned / isPrimary. No sort, no filter.
• objectui/packages/app-shell/src/utils/deriveRelatedLists.ts:133-146 — the emit point. Builds that descriptor from fieldDef.relatedList / relatedListTitle / relatedListColumns only. It iterates the child object defs at :118 but never reads their views.
• objectui/packages/app-shell/src/views/RecordDetailView.tsx:1052-1057 — call site: deriveRelatedLists(objectDef, objects, { canRead }).
• objectui/packages/app-shell/src/views/RecordDetailView.tsx:1955-1978 — second drop point: maps each descriptor into buildDefaultPageSchema's related shape, emitting title / objectName / relationshipField / columns? / icon? / isPrimary?.
• objectui/packages/plugin-detail/src/synth/buildDefaultPageSchema.ts:174-188 — the related option type has no sort member; :683-690 — componentNode('record:related_list', …) forwards title/objectName/relationshipField/columns/limit/icon and no sort.

(b) Query assembly — objectui

• objectui/packages/plugin-detail/src/renderers/record-related-list.tsx:211 — defaultSort={schema.sort}. The renderer already forwards a block-level sort; the channel is open and unfilled on the derived path.
• objectui/packages/plugin-detail/src/RelatedList.tsx:251-267 — normalizeSortSpec: 'field' / '-field' string or [{field, order}] to the array form.
• objectui/packages/plugin-detail/src/RelatedList.tsx:519-529 — the assembly, verbatim confirmation of the card: const orderby = fetchSortField ? [{…}] : defaultSortSpec; if (orderby.length > 0) params.$orderby = orderby; — no sort in, no $orderby out, hence the PK fallback order.
• objectui/packages/plugin-detail/src/RelatedList.tsx:383-389 — windowed = !dataProvided && !!api && effectivePageSize > 0 && dataSource.find && !filterActive. A derived related list self-fetches, so it is windowed by default: an inherited sort would take effect through this exact path.

(c) Which child list view is "the" list view — objectstack owns the resolver, already exported and already consumed

• objectstack/packages/spec/src/ui/view.zod.ts:4111-4198 — expandViewContainerWithDiagnostics / expandViewContainer. The item matching the declared default list is flagged isDefault (:4146-4150); with no list declared, the first list item takes the flag (:4147).
• objectui/packages/app-shell/src/providers/MetadataProvider.tsx:9 imports it (from '@objectstack/spec/ui'), :413-414 calls it, :377-378 if (view.isDefault) bucket.primary = entry, :429-431 if (extra.primary && !obj.list) merged.list = extra.primary.
• Answer: "the" list view is the child object def's list after that merge — the isDefault expanded list view. Its sort is declared at objectstack/packages/spec/src/ui/view.zod.ts:1470-1486 (union: legacy string "field desc" | [{field, order}], with direction aliased to order).
• Nothing new needs exporting from objectstack — resolver and value are already on the objectui side of the boundary.

Contract channel already open (this is why no new key is needed)

objectstack/packages/spec/src/ui/component.zod.ts:883-928 — RecordRelatedListProps.sort: z.union([z.string(), z.array(strictObject({ field, order }))]).optional().describe('Sort order for related records'). Declared, parsed, forwarded by the renderer, consumed by RelatedList. Direction 1 only has to fill it on the derived path.

The 17.0.0 prose

• objectstack/packages/spec/src/ui/view.zod.ts:2487-2494 — the form.defaultSort retiredKey text: "nothing read it: a related list inside a form sorts by its own list view's sort."
• Mirrors: content/docs/references/ui/view.mdx:284 (generated) and packages/spec/liveness/view.json:355.
• Per the ruling, behaviour moves to match the prose, so no prose edit is needed and none was made. The published skills do not repeat the claim (skills/objectstack-ui/SKILL.md:151-160, skills/objectstack-data/rules/relationships.md:316-335 cover prominence / title / columns only), so no published skill text is falsified either.

Is there ANY objectstack-side slice?

No implementation slice. Everything objectstack owns here is already in place and correct: the default-list-view resolver, the ListView sort shape, and the record:related_list.sort prop. Confirmed no server/SDK-side related-list query builder exists — grep for relatedListFilter|relatedListColumns across packages/runtime/src packages/rest/src packages/objectql/src packages/metadata/src returns nothing, packages/console is a stub (README + CHANGELOG + package.json only), and the only record:related_list occurrences in objectstack sources are lint validators, the spec itself, and hand-authored platform-objects pages. This matches the recorded #8704 precedent, which already ruled the derivation lives wholly in objectui (packages/spec/src/data/field.test.ts:596-600).

The one optional objectstack slice, offered for routing rather than taken: mirroring the #8704 pattern, the inheritance rule could be pinned as contract text in relatedList's .describe() (as relatedListFilter did at field.zod.ts:1014-1047, pinned by field.test.ts:602-608). That would be a packages/spec/src/** diff and therefore the path limb — not started, since the dispatch says stop at zero objectstack implementation when the emit point is objectui.

Handoff — what the objectui-side fix is

Three edits, no new keys, no spec change:

1. deriveRelatedLists.ts — add sort? to DerivedRelatedList and emit it from the child object def's default list view (child.list?.sort), never from a field key. The child def is already in hand at :118; no new plumbing.
2. RecordDetailView.tsx:1955-1978 — carry sort onto the related entry (childObjectDef is already resolved at :1956).
3. buildDefaultPageSchema.ts:174-188 and :683-690 — add sort to the related option type and forward it into the record:related_list node. Renderer and RelatedList need no change.

Shape caveat for the implementer: the ListView legacy string form is space-separated "field desc" (view.zod.ts:1470), while normalizeSortSpec (RelatedList.tsx:258-266) reads a string as 'field' / '-field'. Copying a legacy string through verbatim would emit $orderby on a field literally named seq_no desc. The inheritance must normalize the ListView union into the array form, or inherit only the array arm.

The three acceptance pins the dispatch specified all land in objectui: (i) derived query carries $orderby from the child list view's sort; (ii) child with no list-view sort still emits no $orderby; (iii) the view read is the isDefault one.

Out-of-scope findings (searched before filing; no new cards created)

1. relatedListFilter non-consumption — confirmed as the same gap at the same two lines (deriveRelatedLists.ts:133-146 emits no filter; RecordDetailView.tsx:1959-1978 forwards none; buildDefaultPageSchema.ts:683-690 has no filter), while the block prop exists (component.zod.ts:930) and the spec's contract text binds every consumer. Already filed: objectui#4664 (open, pm:queue). Not fixed, no duplicate card.
2. This card's objectui half — already filed: objectui#5795 (open, pm:blocked, parked here). Its root-cause section matches this measurement exactly.
3. NEW, covered by neither card: a declared record:related_list.sort is silently dropped whenever the list leaves windowed mode. windowed goes false while the client text filter is active (RelatedList.tsx:383-389) and the client-mode path returns rows unsorted unless the user clicked a column (:731-733, if (windowed || !sortField) return filteredData;). So an authored sort stops applying the moment a viewer types in the filter box — pre-existing, affecting the authored prop today, and it will affect the inherited sort identically. Deliberately not filed: it lands in objectui on the same file surface objectui#5795 already owns and the PM routes objectui; a third overlapping card risks two agents on one file. Recommend attaching it to objectui#5795 as an acceptance sub-point.

Report

{
 "issue": 11345,
 "status": "blocked",
 "branch": null,
 "pr": null,
 "premise_still_valid": true,
 "summary": "Measurement-first routing: the derived related-list descriptor is emitted in objectui (deriveRelatedLists.ts:133-146, re-dropped at RecordDetailView.tsx:1955-1978 and buildDefaultPageSchema.ts:174-188/683-690), and the $orderby assembly is objectui too (RelatedList.tsx:519-529, fed via record-related-list.tsx:211). Both halves the ruling touches are objectui-side, so per dispatch I stopped with zero objectstack implementation: no worktree, no branch, no PR, no spec diff, no prose edit. objectstack's share of direction 1 is already in place and needs no change - the default-list-view resolver (view.zod.ts:4111-4198, isDefault, already imported by objectui's MetadataProvider), the ListView sort shape (view.zod.ts:1470-1486), and the record:related_list.sort prop the inheritance would fill (component.zod.ts:883-928), which is why no new spec key is required. The 17.0.0 migration prose (view.zod.ts:2487-2494) stays as written and becomes true once the objectui leg lands.",
 "measurement_map": {
 "descriptor_derivation": "objectui/packages/app-shell/src/utils/deriveRelatedLists.ts:48-67 (interface, no sort), :133-146 (emit point); re-dropped at objectui/packages/app-shell/src/views/RecordDetailView.tsx:1955-1978 and objectui/packages/plugin-detail/src/synth/buildDefaultPageSchema.ts:174-188 + :683-690",
 "query_assembly": "objectui/packages/plugin-detail/src/RelatedList.tsx:519-529 ($orderby only when handed a sort), :251-267 (normalizeSortSpec), :396-403 (defaultSortSpec memo), :383-389 (windowed predicate); fed by objectui/packages/plugin-detail/src/renderers/record-related-list.tsx:211 (defaultSort={schema.sort})",
 "which_child_list_view": "The isDefault expanded list view: objectstack/packages/spec/src/ui/view.zod.ts:4111-4198 flags it (:4146-4150; first list item when no `list` is declared, :4147); objectui/packages/app-shell/src/providers/MetadataProvider.tsx:9,:413-414,:377-378,:429-431 merges it onto the child object def as `obj.list`. Its sort shape: objectstack/packages/spec/src/ui/view.zod.ts:1470-1486.",
 "contract_channel_already_open": "objectstack/packages/spec/src/ui/component.zod.ts:883-928 - RecordRelatedListProps.sort is declared, parsed, forwarded and consumed; direction 1 only needs to fill it, hence no new spec key.",
 "prose": "objectstack/packages/spec/src/ui/view.zod.ts:2487-2494 (retiredKey text), mirrored at content/docs/references/ui/view.mdx:284 and packages/spec/liveness/view.json:355. No edit made or needed - behaviour moves to match it. Published skills do not repeat the claim (skills/objectstack-ui/SKILL.md:151-160, skills/objectstack-data/rules/relationships.md:316-335).",
 "objectstack_side_slice": "None for implementation. No server/SDK related-list query builder exists: relatedListFilter|relatedListColumns absent from packages/runtime/src, packages/rest/src, packages/objectql/src, packages/metadata/src; packages/console is a stub; record:related_list in objectstack appears only in lint validators, the spec, and hand-authored platform-objects pages. Matches the #8704 precedent recorded at packages/spec/src/data/field.test.ts:596-600. Optional, NOT taken: pinning the inheritance rule as contract text in relatedList's .describe() (the #8704 pattern) - that would be a packages/spec/src/** diff and therefore the path limb.",
 "objectui_fix": "1) deriveRelatedLists.ts - add sort? to DerivedRelatedList, emit from child.list?.sort (child def already in hand at :118). 2) RecordDetailView.tsx:1955-1978 - carry sort onto the related entry (childObjectDef resolved at :1956). 3) buildDefaultPageSchema.ts:174-188 and :683-690 - add sort to the related option type and forward into the record:related_list node. Renderer and 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, else $orderby goes out on a field literally named 'seq_no desc'."
 },
 "tests": "None run - zero edits were made, so there is nothing to verify and no gate to derive. Phase 1 was read-only static tracing across both checkouts (/home/user/objectstack at b863f012fa, /home/user/objectui), by grep and file reads only. No worktree, no install, no build, no test, no dispatch-gates run, no lock taken. Declared explicitly rather than reported as a pass.",
 "open_questions": [],
 "out_of_scope_findings": [
 "already filed as objectui#4664 (open, pm:queue): the same emit point ignores relatedListFilter - confirmed at deriveRelatedLists.ts:133-146, RecordDetailView.tsx:1959-1978, buildDefaultPageSchema.ts:683-690; not fixed, no duplicate card",
 "already filed as objectui#5795 (open, pm:blocked, parked on #11345): this card's objectui execution half; its root-cause section matches this measurement",
 "NOT filed (reported for attachment to objectui#5795): 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) and the client path returns rows unsorted unless a column was clicked (:731-733). Pre-existing, affects the authored prop today and will affect the inherited sort identically. Not filed to avoid a third card on the file surface objectui#5795 already owns"
 ]
}

---

Generated by Claude Code