spec(ui): constrain object-grid / object-calendar sort to the SortItem array

`ComponentPropsMap` declared `sort` as `z.unknown()` on both blocks, so an
array, the legacy string clause and a bare number all returned `success: true`
while `bogusProp` was refused by name on the same call. objectui#8221 decision
batch #77 (2026-09-07, option B) rules one `sort` spelling platform-wide — the
array — and its item 4 names these two doors as the spec-side half.

Both now declare `z.array(SortItemSchema)`, the shared schema
`ElementDataSourceSchema.sort`, `ListPageSchema.sort` and
`element:record_picker` already import. `record:related_list`'s string arm is
deliberately untouched: it is the `'field'` / `'-field'` dialect read by
`RelatedList.normalizeSortSpec`, never reaching `convertSortToQueryParams`, and
retiring it was not ruled.

Claude-Session: https://claude.ai/code/session_01MkQhmuuJAVDjmeWNixwDDH
Co-authored-by: Claude <noreply@anthropic.com>

Author: os-bill

packages/spec/src/ui/component.test.ts

@@ -2007,6 +2007,108 @@ describe('the four `object-*` `filter` doors — one filter orthography platform
   });
 });
 
+describe('`object-grid` / `object-calendar` `sort` — one sort orthography, the array (objectui#8221, decision batch #77, option B)', () => {
+  const SORT_DOORS = ['object-grid', 'object-calendar'] as const;
+  const ARRAY_FORM = [{ field: 'created_at', order: 'desc' }];
+  /**
+   * The legacy OData-ish clause `convertSortToQueryParams` honours at the
+   * objectui pin `53ded82b` (`core/src/utils/sort-query.ts:66-70`) and that
+   * `ObjectGrid.tsx:1845-1846` puts on `$orderby` verbatim. Retired by the
+   * ruling; refused here.
+   */
+  const STRING_FORM = 'created_at desc';
+  type ParseResult = { success: boolean; data?: { sort?: unknown }; error?: { issues: Array<{ path: PropertyKey[]; code: string }> } };
+  type Door = { shape?: Record<string, unknown>; safeParse: (v: unknown) => ParseResult };
+  const door = (type: string) => ComponentPropsMap[type as keyof typeof ComponentPropsMap] as unknown as Door;
+  const issuesAtPath = (r: ParseResult, path: string) =>
+    r.success ? [] : r.error!.issues.filter((i) => i.path.join('.') === path);
+
+  it.each(SORT_DOORS)('%s accepts a SortItem[] and echoes it — the acceptance criterion', (type) => {
+    const r = door(type).safeParse({ objectName: 'showcase_task', sort: ARRAY_FORM });
+    expect(r.success).toBe(true);
+    expect(r.data!.sort).toEqual(ARRAY_FORM);
+  });
+
+  it.each(SORT_DOORS)('%s carries the REAL SortItemSchema, not a lookalike: the direction enum and the required pair are checked', (type) => {
+    // `z.unknown()` echoed every one of these back with `success: true`.
+    const spelledOut = door(type).safeParse({ objectName: 'showcase_task', sort: [{ field: 'created_at', order: 'descending' }] });
+    expect(issuesAtPath(spelledOut, 'sort.0.order').map((i) => i.code)).toEqual(['invalid_value']);
+    const noDirection = door(type).safeParse({ objectName: 'showcase_task', sort: [{ field: 'created_at' }] });
+    expect(issuesAtPath(noDirection, 'sort.0.order').map((i) => i.code)).toEqual(['invalid_type']);
+    const noField = door(type).safeParse({ objectName: 'showcase_task', sort: [{ order: 'asc' }] });
+    expect(issuesAtPath(noField, 'sort.0.field').map((i) => i.code)).toEqual(['invalid_type']);
+  });
+
+  it.each(SORT_DOORS)('%s REFUSES the legacy string clause at the `sort` path — the shape the ruling retires', (type) => {
+    // Reverse verification on the issue envelope: located at `sort`, kind
+    // named. Before this change the same value parsed with zero issues on
+    // both doors (the card's measurement on `@objectstack/spec` 17.2.0, and
+    // the ablation in the landing PR re-runs it against this tree).
+    const r = door(type).safeParse({ objectName: 'showcase_task', sort: STRING_FORM });
+    expect(r.success).toBe(false);
+    const atSort = issuesAtPath(r, 'sort');
+    expect(atSort).toHaveLength(1);
+    expect(atSort[0].code).toBe('invalid_type');
+    expect(atSort[0]).toMatchObject({ expected: 'array' });
+  });
+
+  it.each(SORT_DOORS)('%s REFUSES a bare number at `sort` — the other value `z.unknown()` receipted', (type) => {
+    const r = door(type).safeParse({ objectName: 'showcase_task', sort: 3 });
+    expect(issuesAtPath(r, 'sort').map((i) => i.code)).toEqual(['invalid_type']);
+  });
+
+  it.each(SORT_DOORS)('%s still refuses an undeclared key BY NAME on the same call — the control the card keeps', (type) => {
+    // The control that makes the three readings above verdicts rather than a
+    // schema that reports nothing: key checking was never the thing that was
+    // missing on these doors, the VALUE was.
+    const r = door(type).safeParse({ objectName: 'showcase_task', sort: ARRAY_FORM, bogusProp: 1 });
+    expect(r.success).toBe(false);
+    expect(issuesAtPath(r, 'sort')).toEqual([]);
+    const unrecognized = r.error!.issues.filter((i) => i.code === 'unrecognized_keys') as Array<{ keys?: string[] }>;
+    expect(unrecognized.flatMap((i) => i.keys ?? [])).toContain('bogusProp');
+  });
+
+  it('`sort` agrees with `dataSource.sort` and with the picker shorthand — one shape, four doors', () => {
+    // The map's own copies are the same import (`SortItemSchema`), so this
+    // asks the question the copies could not: do the doors AGREE, value for
+    // value, with the binding every data-bound element already carries.
+    const viaBinding = ElementDataSourceSchema.parse({ object: 'showcase_task', sort: ARRAY_FORM });
+    for (const type of [...SORT_DOORS, 'element:record_picker']) {
+      const value = type === 'element:record_picker'
+        ? { object: 'showcase_task', sort: ARRAY_FORM }
+        : { objectName: 'showcase_task', sort: ARRAY_FORM };
+      const r = door(type).safeParse(value);
+      expect([type, r.success]).toEqual([type, true]);
+      expect([type, r.data!.sort]).toEqual([type, viaBinding.sort]);
+      const refused = door(type).safeParse({ ...value, sort: STRING_FORM });
+      expect([type, issuesAtPath(refused, 'sort').map((i) => i.code)]).toEqual([type, ['invalid_type']]);
+    }
+  });
+
+  it('the census: no `sort` door in ComponentPropsMap takes a string except `record:related_list`, whose string is a DIFFERENT dialect and was not ruled', () => {
+    // Asked over the WHOLE map by shape rather than by the two names above, so
+    // a future entry declaring `sort` as `z.unknown()` is caught here by name.
+    // Guarded the same way as its `filter` twin: the doors pinned above must
+    // be found, or the shape read has gone wrong and the loop is vacuous.
+    const doors = (Object.entries(ComponentPropsMap) as Array<[string, unknown]>)
+      .filter(([, schema]) => {
+        const shape = (schema as Door).shape;
+        return !!shape && 'sort' in shape;
+      })
+      .map(([type]) => type);
+    expect(doors).toEqual(expect.arrayContaining([...SORT_DOORS, 'element:record_picker', 'record:related_list']));
+    const stringTakers = doors.filter((type) => issuesAtPath(door(type).safeParse({ sort: STRING_FORM }), 'sort').length === 0);
+    // ⚠️ `record:related_list` is the ONE deliberate exception and it is pinned
+    // as such, not tolerated: its string is the `'field'` / `'-field'` form
+    // read by `RelatedList.normalizeSortSpec`, a different dialect that never
+    // reaches `convertSortToQueryParams` — measured by objectui#8221's own
+    // implementing round, which narrowed it, established the dialect and then
+    // reverted the narrowing byte-identically. Retiring it was not ruled and
+    // would delete working, spec-legal behaviour.
+    expect(stringTakers).toEqual(['record:related_list']);
+  });
+});
+
 // ---------------------------------------------------------------------------
 // Interactive Elements — element:text_input
 // ---------------------------------------------------------------------------

packages/spec/src/ui/component.zod.ts

@@ -2485,7 +2485,45 @@ export const ObjectGridPropsSchema = lazySchema(() => strictObject({
     .describe('Base query filter — the ViewFilterRule array form `[{ field, operator, value }, ...]`, the one filter orthography every `filter` door in this map shares; lowered to the wire `$filter`. THE key, singular — not the plural misspelling. The MongoDB-style record form is refused — see migration `element-data-source-and-object-block-filter-rule-array`'),
   defaultFilters: z.unknown().optional()
     .describe('Legacy base-filter fallback, read only when `filter` is absent. Prefer `filter`'),
-  sort: z.unknown().optional().describe('Initial sort (array of { field, order })'),
+  /**
+   * Initial row order — the `SortItem` ARRAY form, `[{ field, order }, ...]`,
+   * the one sort orthography every DECLARED `sort` door on this platform
+   * carries: `ElementDataSourceSchema.sort` and `ListPageSchema.sort`
+   * (page.zod.ts) and `element:record_picker`'s flat shorthand above. One
+   * shared schema rather than a third copy — all of them are
+   * `SortItemSchema`, already imported at the top of this file for the picker.
+   *
+   * objectui#8221, decision batch #77, 2026-09-07, maintainer verbatim
+   * 「其他同意」, option B: one `sort` spelling, the array; the legacy string
+   * clause is retired from `@object-ui/core`. Item 4 of that ruling is this
+   * declaration and `object-calendar`'s below — 「`ComponentPropsMap` for
+   * `object-calendar` and `object-grid` constrains the `sort` value to the
+   * array shape (today it accepts anything), so the spec, the registrations
+   * and the helper agree; that is a pull-back to the declared contract,
+   * ordinary tier」.
+   *
+   * The `z.unknown()` this door carried was a read-point record (#7751), the
+   * same vintage as its `filter` neighbour above and not an exception to the
+   * ruling: it receipted an array, a string and a bare NUMBER alike with
+   * `success: true`, while `plugin-grid/src/index.tsx:222` has published
+   * `type: 'array'` all along — so the html tier answered `type-mismatch` on a
+   * value this schema had just accepted.
+   *
+   * Sequenced measurement-first, as this family has to be. Measured at the
+   * objectui pin `53ded82b`: `ObjectGrid.tsx:1457` reads `schema.sort` and the
+   * fetch path at `:1844-1851` carries an explicit `typeof === 'string'` arm
+   * putting the clause on `$orderby` verbatim, beside the array arm that folds
+   * `[{ field, order }]` onto the same parameter. ⚠️ At THIS pin the string is
+   * therefore still lowered, and this door refuses a spelling the pinned
+   * renderer honours — the ruled sequence, not an oversight: objectui#8221's
+   * PR #8758 (merged 2026-09-09, after this pin) drops the string arm from
+   * `convertSortToQueryParams`, and the next pin bump carries it in. The array
+   * is the spelling both ends already agree on today; the header-arrow read at
+   * `:3998` hands `schemaSort` to `parseSchemaSort` as `TableSortItem[]`, the
+   * array shape and not the string.
+   */
+  sort: z.array(SortItemSchema).optional()
+    .describe('Initial row order — the SortItem array form `[{ field, order }, ...]`, the one sort orthography every declared `sort` door on this platform shares; lowered to the wire `$orderby`. The legacy string clause (`name desc`) is refused — objectui#8221 decision batch #77, option B, retired it'),
   /**
    * REMOVED (#11805, maintainer ruling 2026-08-25, decision-inbox batch 4:
    * 「#11805 退役 defaultSort,不需要major」 — the ADR-0049 enforce-or-remove
@@ -2836,7 +2874,25 @@ export const ObjectCalendarPropsSchema = lazySchema(() => strictObject({
    */
   filter: z.array(ViewFilterRuleSchema).optional()
     .describe('Base query filter — the ViewFilterRule array form `[{ field, operator, value }, ...]`, the one filter orthography every `filter` door in this map shares. The MongoDB-style record form is refused — see migration `element-data-source-and-object-block-filter-rule-array`'),
-  sort: z.unknown().optional().describe('Sort for the fetched events'),
+  /**
+   * Row order for the fetched events — the same `SortItem` ARRAY form
+   * `object-grid` declares above, and for the same ruling (objectui#8221,
+   * decision batch #77, option B; the `object-grid` entry carries the verbatim
+   * text). One sort orthography, one shared `SortItemSchema`.
+   *
+   * Measured at the objectui pin `53ded82b`: `ObjectCalendar.tsx:431` hands
+   * `schema.sort` to the shared sink `convertSortToQueryParams`
+   * (`core/src/utils/sort-query.ts`) as the fetch's `$orderby`. ⚠️ That sink
+   * still honours the legacy string clause at this pin — `sort-query.ts:66-70`
+   * — so, exactly as on `object-grid`, this declaration lands ahead of the
+   * consumer-side retirement (objectui#8221's PR #8758, merged 2026-09-09) and
+   * refuses a spelling the pinned helper still lowers. The array arm is
+   * unaffected: the sink folds `[{ field, order }]` into the field-direction
+   * map either way. Unlike the grid, `plugin-calendar/src/index.tsx` declares
+   * no `sort` input at all, so nothing on the registry side moves.
+   */
+  sort: z.array(SortItemSchema).optional()
+    .describe('Row order for the fetched events — the SortItem array form `[{ field, order }, ...]`, the one sort orthography every declared `sort` door on this platform shares; lowered to the wire `$orderby`. The legacy string clause (`name desc`) is refused — objectui#8221 decision batch #77, option B, retired it'),
   data: z.array(z.unknown()).optional().describe('Pre-fetched records — skips the internal fetch'),
   staticData: z.array(z.unknown()).optional().describe('Static inline records'),
   locale: z.string().optional().describe('Locale override for the calendar chrome'),