spec(ui): pin the sort orthography, register the ADR-0087 entry, add the changeset

Pins on both doors: the SortItem array is accepted and echoed; the legacy string
clause and a bare number are refused at `sort` (`invalid_type`, expected array);
a misspelled or absent direction at `sort.0.order`; `bogusProp` is still refused
by name on the same call (the control the card keeps). A census over the whole
map pins that `record:related_list` is the ONE `sort` door still taking a string,
and why that is deliberate.

Registers the semantic migration `object-block-sort-item-array` under protocol
major 18 (registry.ts is regenerated by `gen:migration-registry`, never edited)
and declares the breaking accept-set change as `minor` per the launch-window
convention.

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

Author: os-bill

.changeset/object-block-sort-item-array.md

@@ -0,0 +1,69 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec)!: `object-grid` and `object-calendar` constrain the `sort` VALUE to the `SortItem` array — one sort orthography platform-wide reaches the last two unconstrained doors (#16553; objectui#8221, decision batch #77 option B)
+
+<!-- adr-0087: registered object-block-sort-item-array -->
+
+**BREAKING** accept-set change at two doors — `ComponentPropsMap['object-grid'].sort`
+and `ComponentPropsMap['object-calendar'].sort` — shipped as `minor` under the
+repo's launch-window convention for breaking changes; the migration prescription
+is registered under protocol major 18 as `object-block-sort-item-array`.
+
+One `sort` spelling platform-wide, the array (objectui#8221, decision batch #77,
+2026-09-07, maintainer verbatim 「其他同意」, option B; the consumer half is
+objectui PR #8758, which drops the legacy string arm from
+`convertSortToQueryParams`). Item 4 of that ruling is this release's subject:
+「`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」.
+
+Until this release both doors declared `z.unknown()` — no orthography at all.
+Measured on `@objectstack/spec` 17.2.0 and re-measured on this tree before the
+change: an array, the legacy string clause and a bare NUMBER all returned
+`success: true`, while `bogusProp` was refused by name on the same call. So key
+checking was live and only the VALUE was unheld, and an author following
+objectui's own registrations (`plugin-grid/src/index.tsx:222` has published
+`type: 'array'` all along) and an author following the legacy string each got a
+silent success receipt for a different shape — while objectui's html tier
+answered `type-mismatch` on the second one. Both doors now declare
+`z.array(SortItemSchema)`, the array `ElementDataSourceSchema.sort`,
+`ListPageSchema.sort` and `element:record_picker`'s flat `sort` shorthand already
+carry: one shared schema, not a third copy.
+
+Sequenced measurement-first, as this family has to be. At the objectui pin this
+repo builds against (`53ded82b`) the string is still lowered —
+`ObjectGrid.tsx:1844-1851` carries an explicit `typeof === 'string'` arm onto
+`$orderby` beside the array arm, and `ObjectCalendar.tsx:431` hands `schema.sort`
+to `convertSortToQueryParams`, whose string arm is still present at
+`sort-query.ts:66-70`. This declaration therefore lands ahead of the pinned
+consumer, which the ruling permits explicitly — either order, since the
+registrations already declare the array — and the next pin bump carries the
+retirement in.
+
+**Migration** (`object-block-sort-item-array`): `sort: 'created_at desc'` becomes
+`sort: [{ field: 'created_at', order: 'desc' }]`; a bare field name
+`sort: 'created_at'` meant ascending and becomes
+`sort: [{ field: 'created_at', order: 'asc' }]` — `order` is required in
+`SortItemSchema`, so it is written out rather than omitted; a comma-separated
+clause becomes one array entry per key, in the same order. The string is refused
+at `sort` (`invalid_type`, expected array), as is a bare number; a misspelled or
+absent direction is refused at `sort.0.order`. Metadata AT REST is not rewritten
+and this disposition adds no D2 conversion — a stored page carrying a string
+`sort` keeps loading and still renders at the pinned `.objectui-sha`; what
+changes is that RE-SAVING it is refused at the `sort` door.
+
+**Not moved by this release.** `record:related_list.sort` keeps its declared
+string arm: that string is the `'field'` / `'-field'` dialect read by
+`RelatedList.normalizeSortSpec`, it never reaches `convertSortToQueryParams`, and
+retiring it was not ruled — objectui#8221's own implementing round narrowed it,
+established the dialect and reverted the narrowing byte-identically.
+`object-grid.defaultSort` is a different key, already retired by #11805. Zero
+authored `sort` values on either block exist in this repo (the two showcase pages
+that author `object-grid` declare none), so nothing in-tree was converted.
+
+Type aliases are unchanged: `SortItemSchema`'s input equals its infer, so neither
+block's parsed state moves for this key, and both already take the
+`…PropsParsed` route for `filter` (ADR-0122).

packages/spec/src/migrations/entries/semantic/18.object-block-sort-item-array.ts

@@ -0,0 +1,74 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { SemanticMigration } from '../../types.js';
+
+export const entry: SemanticMigration = {
+  id: 'object-block-sort-item-array',
+  surface:
+    'The `sort` prop of `object-grid` and `object-calendar` in `ComponentPropsMap` '
+    + '(the FORM: the accept-anything `z.unknown()` at both block doors, vs the '
+    + '`SortItem` array `[{ field, order }, ...]`)',
+  replacement:
+    '`z.array(SortItemSchema)` at both doors — the array `ElementDataSourceSchema.sort`, '
+    + '`ListPageSchema.sort` and `element:record_picker`\'s flat `sort` shorthand already '
+    + 'carry. The legacy OData-ish clause `sort: \'created_at desc\'` becomes '
+    + '`sort: [{ field: \'created_at\', order: \'desc\' }]`; a bare field name '
+    + '`sort: \'created_at\'` meant ascending and becomes '
+    + '`sort: [{ field: \'created_at\', order: \'asc\' }]` — `order` is required in '
+    + '`SortItemSchema`, so it is written out rather than omitted. A comma-separated '
+    + 'clause becomes one array entry per key, in the same order. `record:related_list` '
+    + 'is NOT moved by this entry: its string is the `\'field\'` / `\'-field\'` dialect '
+    + 'read by `RelatedList.normalizeSortSpec`, which never reaches '
+    + '`convertSortToQueryParams`, and retiring it was not ruled. '
+    + '`object-grid.defaultSort` is a different key, retired separately by the '
+    + '`ui__ObjectGridProps__defaultSort` entry.',
+  reason:
+    'One `sort` spelling platform-wide, the array (objectui#8221, decision batch #77, '
+    + '2026-09-07, maintainer verbatim 「其他同意」, option B; the consumer half is '
+    + 'objectui PR #8758, which drops the string arm from `convertSortToQueryParams`). '
+    + 'Item 4 of that ruling is this entry\'s subject: 「`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()` at '
+    + 'both doors was a read-point record (#7751), the same vintage as the `filter` doors '
+    + 'the `element-data-source-and-object-block-filter-rule-array` entry moved, and not an '
+    + 'exception to the ruling: measured on `@objectstack/spec` 17.2.0 an array, a string '
+    + 'and a bare NUMBER all returned `success: true` while `bogusProp` was refused by name '
+    + 'on the same call, so key checking was live and only the VALUE was unheld. Meanwhile '
+    + 'objectui\'s own html tier has published `type: \'array\'` for the grid all along '
+    + '(`plugin-grid/src/index.tsx:222`) and answered `type-mismatch` on the string — a '
+    + 'spelling `@object-ui/core` implemented, the docs taught and the validator refused, '
+    + 'which is what made this a ruling rather than a mechanical widening. '
+    + 'Sequenced measurement-first: at the objectui pin this repo builds against '
+    + '(`53ded82b`) the string is still lowered — `ObjectGrid.tsx:1844-1851` carries an '
+    + 'explicit `typeof === \'string\'` arm onto `$orderby`, and `ObjectCalendar.tsx:431` '
+    + 'hands `schema.sort` to `convertSortToQueryParams`, whose string arm is still present '
+    + 'at `sort-query.ts:66-70`. So this declaration lands AHEAD of the pinned consumer, '
+    + 'which the ruling permits explicitly (either order; the registrations already declare '
+    + 'the array). The in-repo sweep found ZERO authored `sort` on either block — the two '
+    + 'showcase pages that author `object-grid` (`command-center.page.ts`, '
+    + '`my-work.page.ts`) declare none — with the same grep shape finding 40+ string `sort` '
+    + 'values at OTHER doors (view definitions, ObjectQL `query.sort`) as the control that '
+    + 'the sweep fires; so this entry carries the prescription for authors outside the repo. '
+    + '⚠️ Metadata AT REST is deliberately NOT rewritten and this disposition adds no D2 '
+    + 'conversion: `os migrate meta --stored` replays D2 conversions only, and the read path '
+    + 'does not re-validate stored rows (`applyConversionsToStoredItem` replays the chain '
+    + 'without validating, by its own contract), so a stored page carrying a string `sort` '
+    + 'keeps loading and is still rendered by objectui at the pinned `.objectui-sha`. What '
+    + 'changes is that RE-SAVING it is refused at the `sort` door, on its next save and not '
+    + 'before. ADR-0049, ADR-0087.',
+  acceptanceCriteria:
+    '`ComponentPropsMap[\'object-grid\' | \'object-calendar\'].safeParse({ objectName, '
+    + 'sort: [{ field: \'created_at\', order: \'desc\' }] })` succeeds and the parsed `sort` '
+    + 'is that same array, equal value-for-value to '
+    + '`ElementDataSourceSchema.parse({ object, sort: <that array> }).sort`. The legacy '
+    + 'string clause is refused at the `sort` path on both doors (`invalid_type`, expected '
+    + 'array), and so is a bare number; a misspelled or ABSENT direction is refused at '
+    + '`sort.0.order` (`invalid_value` — `order` is a required enum, so both take one '
+    + 'verdict) and a missing field at `sort.0.field` (`invalid_type`). An undeclared key '
+    + 'is still refused BY NAME on the same call (`unrecognized_keys` naming it), the '
+    + 'control that makes those refusals verdicts rather than a schema reporting nothing. '
+    + 'No `sort` door in `ComponentPropsMap` accepts a string except `record:related_list`, '
+    + 'which is the one deliberate exception. At runtime each block orders exactly as the '
+    + 'array orders — the same `$orderby` the string lowered to.',
+};

packages/spec/src/migrations/registry.ts

@@ -8702,6 +8702,76 @@ const step18: MigrationStep = {
         + 'set stays exactly `DEFAULT_METADATA_TYPE_REGISTRY` plus item-population growth, '
         + 'before and after.',
     },
+    {
+      id: 'object-block-sort-item-array',
+      surface:
+        'The `sort` prop of `object-grid` and `object-calendar` in `ComponentPropsMap` '
+        + '(the FORM: the accept-anything `z.unknown()` at both block doors, vs the '
+        + '`SortItem` array `[{ field, order }, ...]`)',
+      replacement:
+        '`z.array(SortItemSchema)` at both doors — the array `ElementDataSourceSchema.sort`, '
+        + '`ListPageSchema.sort` and `element:record_picker`\'s flat `sort` shorthand already '
+        + 'carry. The legacy OData-ish clause `sort: \'created_at desc\'` becomes '
+        + '`sort: [{ field: \'created_at\', order: \'desc\' }]`; a bare field name '
+        + '`sort: \'created_at\'` meant ascending and becomes '
+        + '`sort: [{ field: \'created_at\', order: \'asc\' }]` — `order` is required in '
+        + '`SortItemSchema`, so it is written out rather than omitted. A comma-separated '
+        + 'clause becomes one array entry per key, in the same order. `record:related_list` '
+        + 'is NOT moved by this entry: its string is the `\'field\'` / `\'-field\'` dialect '
+        + 'read by `RelatedList.normalizeSortSpec`, which never reaches '
+        + '`convertSortToQueryParams`, and retiring it was not ruled. '
+        + '`object-grid.defaultSort` is a different key, retired separately by the '
+        + '`ui__ObjectGridProps__defaultSort` entry.',
+      reason:
+        'One `sort` spelling platform-wide, the array (objectui#8221, decision batch #77, '
+        + '2026-09-07, maintainer verbatim 「其他同意」, option B; the consumer half is '
+        + 'objectui PR #8758, which drops the string arm from `convertSortToQueryParams`). '
+        + 'Item 4 of that ruling is this entry\'s subject: 「`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()` at '
+        + 'both doors was a read-point record (#7751), the same vintage as the `filter` doors '
+        + 'the `element-data-source-and-object-block-filter-rule-array` entry moved, and not an '
+        + 'exception to the ruling: measured on `@objectstack/spec` 17.2.0 an array, a string '
+        + 'and a bare NUMBER all returned `success: true` while `bogusProp` was refused by name '
+        + 'on the same call, so key checking was live and only the VALUE was unheld. Meanwhile '
+        + 'objectui\'s own html tier has published `type: \'array\'` for the grid all along '
+        + '(`plugin-grid/src/index.tsx:222`) and answered `type-mismatch` on the string — a '
+        + 'spelling `@object-ui/core` implemented, the docs taught and the validator refused, '
+        + 'which is what made this a ruling rather than a mechanical widening. '
+        + 'Sequenced measurement-first: at the objectui pin this repo builds against '
+        + '(`53ded82b`) the string is still lowered — `ObjectGrid.tsx:1844-1851` carries an '
+        + 'explicit `typeof === \'string\'` arm onto `$orderby`, and `ObjectCalendar.tsx:431` '
+        + 'hands `schema.sort` to `convertSortToQueryParams`, whose string arm is still present '
+        + 'at `sort-query.ts:66-70`. So this declaration lands AHEAD of the pinned consumer, '
+        + 'which the ruling permits explicitly (either order; the registrations already declare '
+        + 'the array). The in-repo sweep found ZERO authored `sort` on either block — the two '
+        + 'showcase pages that author `object-grid` (`command-center.page.ts`, '
+        + '`my-work.page.ts`) declare none — with the same grep shape finding 40+ string `sort` '
+        + 'values at OTHER doors (view definitions, ObjectQL `query.sort`) as the control that '
+        + 'the sweep fires; so this entry carries the prescription for authors outside the repo. '
+        + '⚠️ Metadata AT REST is deliberately NOT rewritten and this disposition adds no D2 '
+        + 'conversion: `os migrate meta --stored` replays D2 conversions only, and the read path '
+        + 'does not re-validate stored rows (`applyConversionsToStoredItem` replays the chain '
+        + 'without validating, by its own contract), so a stored page carrying a string `sort` '
+        + 'keeps loading and is still rendered by objectui at the pinned `.objectui-sha`. What '
+        + 'changes is that RE-SAVING it is refused at the `sort` door, on its next save and not '
+        + 'before. ADR-0049, ADR-0087.',
+      acceptanceCriteria:
+        '`ComponentPropsMap[\'object-grid\' | \'object-calendar\'].safeParse({ objectName, '
+        + 'sort: [{ field: \'created_at\', order: \'desc\' }] })` succeeds and the parsed `sort` '
+        + 'is that same array, equal value-for-value to '
+        + '`ElementDataSourceSchema.parse({ object, sort: <that array> }).sort`. The legacy '
+        + 'string clause is refused at the `sort` path on both doors (`invalid_type`, expected '
+        + 'array), and so is a bare number; a misspelled or ABSENT direction is refused at '
+        + '`sort.0.order` (`invalid_value` — `order` is a required enum, so both take one '
+        + 'verdict) and a missing field at `sort.0.field` (`invalid_type`). An undeclared key '
+        + 'is still refused BY NAME on the same call (`unrecognized_keys` naming it), the '
+        + 'control that makes those refusals verdicts rather than a schema reporting nothing. '
+        + 'No `sort` door in `ComponentPropsMap` accepts a string except `record:related_list`, '
+        + 'which is the one deliberate exception. At runtime each block orders exactly as the '
+        + 'array orders — the same `$orderby` the string lowered to.',
+    },
     {
       id: 'object-grid-data-view-data-converged',
       surface:

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

@@ -2033,8 +2033,11 @@ describe('`object-grid` / `object-calendar` `sort` — one sort orthography, the
     // `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']);
+    // Same code as the misspelling above, and deliberately so: `order` is a
+    // required enum, so an ABSENT direction and a wrong one are one verdict at
+    // one path — the pair is what the schema asks for.
     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']);
+    expect(issuesAtPath(noDirection, 'sort.0.order').map((i) => i.code)).toEqual(['invalid_value']);
     const noField = door(type).safeParse({ objectName: 'showcase_task', sort: [{ order: 'asc' }] });
     expect(issuesAtPath(noField, 'sort.0.field').map((i) => i.code)).toEqual(['invalid_type']);
   });