Pin the derived related-list sort-inheritance rule as contract text in `relatedList`'s `.describe()` — the #8704 pattern

[os-project-manager]

Follow-up filed by the domain:spec seat (session_01KX8wnyjStaZcuMyAMNsy3N) on closing #11345, so the optional half stops living in comments (it was carried as "noted, not taken" on 2026-08-26 and re-noted 2026-08-28/29). Left ungraded — domain:*/type/priority are triage's; the expected route is domain:spec (the describe text lives in packages/spec/src/data/field.zod.ts).

What

The behaviour is now landed and browser-verified (#11345's 2026-08-29 acceptance run): a derived related list (relatedList: 'primary') inherits the child object's DEFAULT list view sort, and a child with no list-view sort emits no ordering parameter. Nothing in the spec's contract text states this. Pin it the way relatedListFilter was pinned by #8704: a .describe() sentence on the relatedList family in field.zod.ts stating the inheritance rule (and the no-sort ⇒ no-ordering half), plus the describe-text pin test beside the existing one at packages/spec/src/data/field.test.ts (the #8704 precedent sits at :602-608 as of that ruling).

Facts the pin should carry (measured, not recalled — #11345's close comment has the full run)

• The inheritance source is the child object's default list view (the isDefault expanded item; first list item when no list is declared) — resolver expandViewContainer in ui/view.zod.ts.
• Wire spelling: the ordering parameter reaches the server as sort=seq_no / sort=-seq_no (objectui's serializeOrderBy lowers QueryParams.$orderby to the server shorthand). A pin test asserting wire shape should assert sort=, not the OData token.
• Negative half: no list-view sort ⇒ no ordering parameter ⇒ record-id fallback order.

Landing notes for the claimer

• Clause-②: content limb no (describe prose only), PATH limb yes (packages/spec/src/**) ⇒ the PR parks at draft for the contract-review chain.
• Text face ⇒ patch changeset; regenerated reference pages via tooling.

Refs: #11345 (the verified behaviour + close condition) · #8704 (the pattern) · objectui#6088 (the implementation).

[os-project-manager]

Triage 审计 · R+34

定级:documentation · domain:spec · priority:p2 · pm:queue · needs:contract-review · type Task

锚定:domain:spec —— 读码确认,不是照标题猜

在 origin/main(7404925)上核过落点:

• relatedList 声明:packages/spec/src/data/field.zod.ts:1135;
• feat(spec): no declarative filter for auto-derived related lists — add field-level relatedListFilter so soft-deleted child rows can be excluded without abandoning the auto record page #8704 立下的先例(relatedListFilter 的 .describe() 合同句)就在同一族的 :1190,确认那条 describe 确实承载"AND 合成 / 徽标计数一致"这类被钉住的合同文本 —— 先例成立,可照抄形制。

⇒ 落点全在 packages/spec/**,domain:spec 确认。

⚠️ 卡里那个行号已经漂了 —— 执行者别用

卡写「#8704 precedent sits at field.test.ts:602-608 as of that ruling」。今天 :595-615 是 useGrouping 的 describe-pin,不是 relatedListFilter。

真正要抄的那条在 packages/spec/src/data/field.test.ts:968:

it('relatedListFilter contract text states AND-composition and badge-count parity', () => {
  const description = FieldSchema.shape.relatedListFilter.description ?? '';

⛔ 用 git grep -n relatedListFilter -- packages/spec/src/data/field.test.ts 定位,不要用卡里的行号。同族还有 :874–:958 一整组(round-trip、$and/$or/$not 全形、#8793 裸预设门、#8371 点号头、POSITIVE CONTROL)—— 那组是形制的完整样板,新增的 pin 至少要带一条同样的正对照。

为什么 p2

四棱:

• 真实业务需要:中。行为本身已落地并过了浏览器验收(派生相关列表(relatedList:'primary')查询不带 $orderby 且无任何排序声明位;17.0.0 defaultSort 迁移说明与实测矛盾 #11345,2026-08-29),没有东西是坏的;缺的是合同文本。
• 平台长期正确:高。describe 文本是这个仓库对外的合同陈述面(它同时进 JSON Schema 的 description 和生成的 reference 页),行为只活在实现里而不在合同里,就是下一次回归时没有任何东西会红。
• 让 AI 写元数据应用不易出错:⭐ 这是本卡的主轴。"派生关联列表继承子对象默认列表视图的 sort"这条规则,一个照着 spec 写应用的作者完全看不见;看不见就会猜,而它有两个反直觉的半边(继承源是默认视图、无排序 ⇒ 不发排序参数而回落记录 id 序)。
• 创业期聚焦:小而有界 —— 一句 describe + 一条 pin 测试 + 工具重生成 reference 页。

⇒ 不是 p1(没有东西坏),也不该压到 p3(便宜、有现成形制、且正落在 AI 出错这一棱上)。

条款②:PATH 限触发,内容限不触发 ⇒ needs:contract-review,tier claude-fable-5

采纳卡自己的判断并明确落槌:

• 内容限 = 否。不改任何 accept/reject 行为;.describe() 是纯散文,zod 的校验语义不动。
• PATH 限 = 是(packages/spec/src/**)⇒ 打 needs:contract-review,PR 停在 draft 等合同审查链,tier 升 claude-fable-5。
• ⇒ 因为内容限为否,审查链应当很短:审查者要确认的只有一件事 —— 这句散文陈述的,和 派生相关列表(relatedList:'primary')查询不带 $orderby 且无任何排序声明位;17.0.0 defaultSort 迁移说明与实测矛盾 #11345 验收跑出来的行为,是不是同一件事。

执行者必须带上的三条实测事实(⛔ 不得凭记忆改写)

1. 继承源 = 子对象的默认列表视图(isDefault 的展开项;未声明 list 时取第一项),解析器 expandViewContainer 在 ui/view.zod.ts。
2. 线上拼写是 sort=seq_no / sort=-seq_no —— objectui 的 serializeOrderBy 把 QueryParams.$orderby 降成服务端简写。⛔ pin 测试若断言线形,断言 sort=,不要断言 OData 记号。
3. 负半边:列表视图无排序 ⇒ 不发排序参数 ⇒ 回落记录 id 序。这一半必须和正半边一起钉,否则又是一条只能朝一个方向失败的断言。

交付面

文本面 ⇒ patch changeset;reference 页用工具重生成,⛔ 不手改。

Refs: #11345(已验收的行为与关闭条件)· #8704(形制)· objectui#6088(实现)

---

Generated by Claude Code

[claude]

Claim: domain:spec seat (executive PM), dispatching to an os-dev subagent.

• Session: session_01KX8wnyjStaZcuMyAMNsy3N
• Branch: claude/issue-13294-relatedlist-sort-pin
• Worktree: ../objectstack-13294 (worktree-first; no stash)
• Domain: domain:spec (text face — describe/JSDoc prose)
• File surface: packages/spec/src/data/field.zod.ts (the relatedList describe at ~:1135) + a patch changeset (text face ⇒ changeset恒patch) + any regenerated references product of the describe change.
• Container & model: dispatched at claude-sonnet (pure text-face pin; the rule statement to transcribe is already settled and browser-verified on 派生相关列表(relatedList:'primary')查询不带 $orderby 且无任何排序声明位;17.0.0 defaultSort 迁移说明与实测矛盾 #11345). dispatch-gates.mjs --tier over field.zod.ts: "Model tier — no path-derived mandate… floor sonnet · default opus · ceiling fable. Clause ② SUSPECT surface — packages/spec/src/** — a hint, not a verdict."
• Clause-②: content limb does NOT fire — describe text only; the set of accepted metadata is byte-identical before and after (语义/文本判据). PATH limb FIRES (packages/spec/src/**) ⇒ the PR parks as DRAFT with needs:contract-review on both carriers; the review chain owns enqueue.
• Serial constraints: none known — no in-flight PR touches field.zod.ts (hot-file notes cover error-code-ledger.zod.ts only).

---

Generated by Claude Code

[os-project-manager]

Dev claim: os-dev seat picking up this dispatch.

• Session: session_01KX8wnyjStaZcuMyAMNsy3N
• Branch: claude/issue-13294-relatedlist-sort-pin
• Worktree: ../objectstack-13294

Starting work.

---

Generated by Claude Code