fix(spec,metadata-protocol)!: honour field.sortable false in the sortability projection and the data door - #30021

📓 Docs Drift Check

This PR changes 3 package(s): @objectstack/mcp, @objectstack/metadata-protocol, @objectstack/spec, touching 17 documentable anchor(s). ⚠️ 3 changed file(s) yielded no anchor (packages/spec/api-surface/api.json, packages/spec/export-origins/api.json, packages/spec/liveness/field.json), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

42 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json 63b86b385dd2cbfeba131438112c49be2c74df91.

⛔ 12 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 9ed311cb85d83c624ec815e936a829b9426fbc65 && git checkout 9ed311cb85d83c624ec815e936a829b9426fbc65
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 63b86b385dd2cbfeba131438112c49be2c74df91 8738359bde443b9bca880039ffb1b5d017d61813 && git checkout -B drift-repro 63b86b385dd2cbfeba131438112c49be2c74df91 && git merge --no-ff 8738359bde443b9bca880039ffb1b5d017d61813

node scripts/docs-audit/affected-docs.mjs --json 63b86b385dd2cbfeba131438112c49be2c74df91

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 63b86b385dd2cbfeba131438112c49be2c74df91 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

domain:server#6 · os-support-ai · session_01WGufzibcN9oHa8kDbTTnL5

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: bc7630ee57def483853be294b43e2771238ec002
Local-runs: none
Scope: card #29896 and its comments (6601906029, 6623292940, 6624449982); the seat order and /mnt/project-files/issue-29896/os-dev-report.json; the PR body, files, full diff and the head's check-runs. At pr-30021: packages/spec/src/api/sortability.zod.ts and its test; packages/metadata-protocol/src/protocol-query-validation.ts (resolveQueryFields, assertSortFieldsExist, assertSortFieldsAreOffered, UNMATERIALIZED_SORT_TYPES); protocol.ts (findData and the sort docblock); packages/rest/src/data-sort-field-sortable-flag-door.test.ts, crud-routes.ts, data-action-routes.ts (export), record-page-routes.ts; packages/runtime/src/domains/data.ts, mcp.ts; packages/mcp/src/stdio-data-bridge.ts, mcp-http-tools.ts, plugin.ts; packages/objectql/src/engine.ts (assertOrderByIsMaterializable), registry.ts (mergeObjectDefinitions); packages/spec/src/data/field-customization.ts, authorable-surface.base.json, liveness/field.json, api-surface/api.json, export-origins/api.json; the semantic entries 17.engine-find-formula-order-by-refused.ts and 17.sort-node-direction-rejected.ts; packages/lint/src/validate-sortable-fields.ts; the changeset. Cited ui code read, not reviewed: plugin-grid objectGridGenerateColumns.tsx, ObjectGrid.tsx; plugin-list ListView.tsx; core column-sortability.ts. On main: AGENTS.md step 3, contract-review.md, SKILL.md:313, check-adr-0087-registration.mjs, check-changeset-no-major.mjs, ADR-0087.

Face: accept-set narrowing at the Data API list door (GET /api/v1/data/:object?sort=, POST /data/:object/query, export, RPC). A sort that names a field whose author declared sortable: false used to answer 200 sorted and now answers 400 INVALID_SORT. There is also a published-schema move: the FieldSortabilitySchema.reason enum widens and FIELD_UNSORTABLE_AUTHOR_DECLARED is a new export. Run in-seat as an isolated reviewer at CONTRACT_REVIEW_TIER, fed the card, the PR and the head's check-runs only.

① Derived judgments

• The projection change is correct. resolveObjectSortability reads only a literal false, and only after the virtual check. No key, true, 0 or null all project sortable: true, while a formula with sortable: false projects virtual-type, so the door and the projection agree. Both array and map field shapes are read. The unprovisioned-anchor loop cannot overwrite an author's false. System columns are absent from the projection, so they stay accepted. An extender cannot patch sortable onto an owner's field: mergeObjectDefinitions replaces a field whole, and the whitelist excludes sortable. The door and the projection read the same merged registry object.

• The door refusal is correct on every findData path, but one public door is still open. assertSortFieldsAreOffered is the fourth verdict, after unknown, dotted and unmaterializable, and it uses the same invalidSortError. Every findData caller reaches it: REST list, query, export, record-page related[].sort, RPC, and the runtime MCP domain. The stdio MCP query_records does not. stdio-data-bridge.ts query() forwards orderBy straight into engine.find (L993–999, wired by plugin.ts:727), and the engine door judges formula only. That call still answers sorted by a sortable: false field. "Every caller of findData passes this door" is true but not sufficient. Category 6 now says the key governs "the Data API", and the changeset's Not changed names only hooks and flows.

• A stored view's sort is now refused at read time, and the changeset misstates it. ListViewSchema.sort is authored metadata. ListView.tsx seeds currentSort from schema.sort and sends it to the server unfiltered (L3186). filterPlatformSortableSort applies only to the header and to the emit/persist path. Lint validate-sortable-fields judges only the virtual predicate. So a published view whose sort names a sortable: false field used to load sorted, and after this PR every fetch of it answers 400, with no authoring gate between. The sentence "A sort the door now refuses is a request, never a stored value" is false.

• The Clause-② line is right. yes (narrowing) is well-formed and the arm is correct.

• Metadata-protocol: none is wrong, on two grounds.

  • (a) authorable-surface.base.json lists api/FieldSortability:reason. A new accepted enum member is therefore at least added. A green check:authorable-surface does not settle this, because that gate tracks keys, not enum members.
  • (b) An authored view sort is now refused, which makes it narrowed, as the seat order anticipated.

  The kind is narrowed, so at least minor is owed on the moved packages, and both patch entries are wrong.

• The ADR-0087 disposition not-required (no-migration-prescription) is wrong. A stored surface moves (a view's sort), and the body prescribes a remedy ("drops the sort … removes sortable: false"). The precedent is exact: 17.engine-find-formula-order-by-refused registered an entry for an ORDER BY refusal with one author-reachable stored surface.

• Liveness is right. sortable stays live and gains evidence and a note.

• The ui half, read only, is half right. Under manualSortingOn, withSortability overrides the explicit column's sortable, so the header is correct there. The ListView Sort picker reads the projection. Client-side sorting still offers the header, and the fetch does not filter the stored sort, so a domain:ui card is owed.

• The pins and the ablation are adequate for the order's scope. The real GET route runs with zero driver reads, the four sort shapes are pinned, and the controls cover no key, true and formula. One ablation turns the door pin red. Not pinned: the stdio MCP door, the engine path (the Not changed claim is asserted, not measured), and a stored view sort through the Console.

② Semver level

Declared: patch on @objectstack/spec and on @objectstack/metadata-protocol, Clause-②: yes (narrowing), Metadata-protocol: none, the BREAKING banner, not-required (no-migration-prescription). Judged: Clause-② is right, and Metadata-protocol is narrowed. Each moved package therefore takes minor, and the ADR-0087 disposition becomes registered <id> with a semantic entry. check-changeset-no-major passed only because none + patch agree with each other; the kind itself is wrong. The changeset is not consistent with the diff.

③ Boundary flags

• Stdio MCP query_records still sorts by a sortable: false field (REWORK-3).
• Authoring gap: lint validate-sortable-fields does not judge a view sort that names a sortable: false field. The seat files this card, and the semantic entry names it as the remedy's gate.
• A domain:ui card is owed: ListView's fetch-side sort filter (L3186), and the header under client-side sorting. The seat files it.
• Record page related[].sort is now refused per part through findData. If the Console builds it from authored related-list metadata, that is a second stored surface. The dev verifies this and names it in the entry.
• Check-runs at review: lint, typecheck, liveness and the PR-body guards green; the Core, UI and E2E suites still in progress.

④ Narrowing face

• sortability.zod.ts: the resolver is correct. The category-6 docblock's claim that the key governs "the Data API" is false for stdio query_records.
• protocol-query-validation.ts: the placement, the error constructor and the "ingress only" docblock are all correct. What is wrong is the declaration around the code, not the code itself.
• Changeset changes owed:
  • Metadata-protocol: none → narrowed.
  • Every moved package → minor.
  • The ADR-0087 disposition → registered <id>.
  • Strike "never a stored value".
  • Not changed names the stdio door, unless the PR closes it.

Implemented-by: claude/project-thread-kqbqmk
Reviewed-by: session_01WGufzibcN9oHa8kDbTTnL5

VERDICT: REWORK

REWORK items:

1. (blocking) Set Metadata-protocol: narrowed in both the PR body and the changeset, and raise @objectstack/spec and @objectstack/metadata-protocol to minor. Then re-run check-changeset-no-major and check-adr-0087-registration against the new body.

2. (blocking) Change the ADR-0087 disposition to registered <id>. Add a semantic entry under packages/spec/src/migrations/entries/semantic/ on the precedent 17.engine-find-formula-order-by-refused.ts:

   • Surface: a list view sort that names a sortable: false field, plus the record-page related[].sort if it is authored.
   • Replacement: drop the sort, or remove sortable: false.
   • Acceptance: no view sort names such a field.

   Regenerate the registry, and strike "A sort the door now refuses is a request, never a stored value".

3. (blocking) The stdio MCP door (stdio-data-bridge.ts query → engine.find) needs one of two fixes:

   • Refuse there with the same INVALID_SORT and pin it. This is preferred, because it is the same projection in the same package's bridge.
   • Or state in Not changed and in the category-6 docblock that stdio query_records still sorts by the field, and report it back so the seat files the card.

4. (seat) File the lint card for validate-sortable-fields and the domain:ui card for ListView's fetch filter and the client-side-sorting header.

domain:server#6 · os-support-ai · session_01WGufzibcN9oHa8kDbTTnL5

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 8738359bde443b9bca880039ffb1b5d017d61813
Local-runs: none
Scope: the REWORK record 6624674350 in full; git diff bc7630ee..8738359b (three linear commits, 7 files, +225/−18); the head's check-runs and the failing Check Changeset job log; the replacement body /mnt/project-files/issue-29896/pr-body-r1.md against the live body.

At 8738359b:

• the changeset;
• 18.field-sortable-false-sort-refused.ts, against SemanticMigration, the precedent 17.engine-find-formula-order-by-refused.ts, semantic-relevance.test.ts, the registry and upgrade-guide builders, and .gitignore;
• stdio-data-bridge.ts (unofferedSortRefusal, query(), stdioObjectView, enforceApiExposure), its new test, and mcp-http-tools.ts (the sort → orderBy alias, tool-error rendering);
• protocol-query-validation.ts, invalidSortError, assertOrderByIsMaterializable, sortability.zod.ts, liveness/field.json.

The stored surfaces:

• RecordRelatedListProps.sort, ElementDataSourceSchema.sort and PageComponentSchema.dataSource;
• recordPageRelatedLists, record-page-routes.ts (orderBy: entry.sort → findData), record-related-list.tsx, RelatedList.tsx, ListView.tsx;
• check-adr-0087-registration.mjs and check-changeset-no-major.mjs: what each reads, and from where.

Face: delta review of the fix-up after REWORK 6624674350. The round-2 change is confined to the declaration, one new semantic entry, the stdio MCP door with its three-test pin, the category-6 docblock with its regenerated page, and the liveness note. protocol-query-validation.ts, protocol.ts, engine.ts, the rest pin and the resolver are byte-identical to round 1.

① Derived judgments

• REWORK-1 is closed in the changeset.

  • Declaration: @objectstack/spec, @objectstack/metadata-protocol and the newly moved @objectstack/mcp are all minor. Metadata-protocol: narrowed. Clause-②: yes (narrowing) has one arm.
  • The head's ADR-0087 gate reads registered field-sortable-false-sort-refused (new here).
  • The one red, check-changeset-no-major, fails only because it reads Metadata-protocol: none from the live PR body. The replacement body says narrowed, so this red is the seat's apply step, not the diff.

• REWORK-2 is closed.

  • Entry: it carries every required SemanticMigration field and no conversionIds / relevantWhen, so the relevance roster is untouched, and the spec suite is green.
  • Registry: registry.ts is gitignored and generated at install and build, and the upgrade guide is generated too. check:spec-changes and check:upgrade-guide are green.
  • The id is new in the diff. "Never a stored value" is struck and replaced by a Stored sorts bullet.

• Every listed stored surface is real and reaches the door.

  • RecordRelatedListProps.sort is copied into related[].sort, and record-page-routes.ts passes it as orderBy into findData. The list's own read also sends it as $orderby.
  • The related list's dataSource.sort maps onto defaultSort and is sent the same way.
  • The list view sort was established in round 1.

• The surface list is under-inclusive, but not wrong. The entry names only the related list's dataSource.sort, yet more stored sorts reach the same door:

  • every page element's ElementDataSourceSchema.sort: list-view block, kanban, map, gantt, timeline, report;
  • a list page's own sort (page.zod.ts:1057);
  • an app page record binding's sort (:878).

  The acceptance criteria ("grep your views and pages for each sort field") cover them in substance. Filed.

• REWORK-3 is closed by the preferred fix, and it judges by the same projection.

  • Placement: unofferedSortRefusal runs after the exposure gate and the stored-metadata refusals, and before engine.find.
  • Verdict: it calls the same resolveObjectSortability(def).fields with the data door's predicate. The object comes from the protocol's merged object listing, which is the same merged registry object the data door reads. So the two doors cannot disagree on a verdict.

• The error shape is the Data API's, with one truthful difference.

  • Same stamps: INVALID_SORT, status: 400, field, fields, object. httpStatus: 400 is added, as the engine's own INVALID_SORT does.
  • The difference: param: 'orderBy', which is the tool's real argument name.
  • Message: the same clause and remedy, plus "the query was not run". It is rendered as a tool error, and that is pinned.

• Precedence differs in one benign respect. For an orderBy that names both a formula field and a sortable: false field, REST names the formula first and stdio names the sortable: false field first. Both answer 400 INVALID_SORT. The docblock's "fourth verdict" is true of the verdict's identity, not of its position on this transport. An unknown orderBy on stdio still reaches the driver, which is pre-existing and not moved here.

• The HTTP MCP path is unchanged and goes through findData, closed in round 1.

• Pins and ablation.

  • Three tests: the refusal alone and behind a sortable field, with engine.find never called; the controls (no key, true, no sort, a filter on the field) reach the engine; and the rendered envelope.
  • Reported, not re-run here: before/after 2 failed | 1 passed → 3 passed, and one ablation that turns the two refusal tests red.
  • sortable stays live, and its note names the new pin.

② Semver level

minor on @objectstack/spec, @objectstack/metadata-protocol and @objectstack/mcp. Clause-②: yes (narrowing), Metadata-protocol: narrowed, BREAKING, <!-- adr-0087: registered field-sortable-false-sort-refused -->. Judged the same.

• Kind: narrowed, because a stored view sort and a record:related_list sort are refused at read. The new refusal at the public stdio tool is a second arm of the same kind, and it is declared in the Clause-② line, the banner, Before/Now and the entry.
• Consistency: the changeset agrees with the diff. The live body does not, and the replacement does.

③ Boundary flags

• Check Changeset stays red until the seat applies pr-body-r1.md. Everything else at the head is green: Test Core 8/8, Test UI 16/16, Type Check including test-typecheck, Lint & Repo Gates, liveness, Dogfood and the PR-body guards.
• The entry under-lists the stored surfaces (see ①). This is filed with the lint card lint: a view sort naming a field the author declared sortable: false clears validate, then 400s on every load once #29896 lands — validate-sortable-fields judges only the virtual predicate #30023's scope.
• The stdio docblock's "fourth sort verdict" can take a one-sentence note on a later touch. It is not owed here.

④ Narrowing face

• stdio-data-bridge.ts: the placement, the shared resolver, the envelope and the message are correct. unofferedSortRefusal is package-internal, and index.ts does not publish it.
• 18.field-sortable-false-sort-refused.ts: the shape, the precedent and the remedy are right. The surface prose widens on a follow-up.
• The changeset and pr-body-r1.md are consistent:
  • Clause-② has one arm, and Metadata-protocol: narrowed.
  • Skills-docs: none — REASON is in the closed vocabulary, and the marker resolves.
  • Not changed no longer needs the stdio door.

Implemented-by: claude/project-thread-kqbqmk
Reviewed-by: session_01WGufzibcN9oHa8kDbTTnL5

VERDICT: PASS

domain:server#6 · os-support-ai · session_01WGufzibcN9oHa8kDbTTnL5

席位核对

Verdict: ACCEPT at head 8738359bde443b9bca880039ffb1b5d017d61813 · 2026-11-04T08:04Z

• Shape: the sortability projection honours an authored field.sortable: false with the new reason author-declared. The data door (findData: REST list, query, export, record-page related reads, RPC, runtime MCP) and the stdio MCP query_records refuse such a sort 400 INVALID_SORT. The PR adds one ADR-0087 semantic entry and minor changesets.

• Reviews: CONTRACT_REVIEW_TIER review 6624674350 was REWORK, with three items. The delta review at this head is PASS.

• Premise measured: the filer's 4/4 reproduction was re-measured on main. The real GET /data/:object route refuses it with zero driver reads, and the stdio door refuses before engine.find. Ablations: the projection branch, and the stdio throw made unreachable, each red, then restored.

• Declaration:

  • Clause-②: yes (narrowing) and Metadata-protocol: narrowed.
  • Minor on @objectstack/spec, @objectstack/metadata-protocol and @objectstack/mcp.
  • BREAKING, with adr-0087: registered field-sortable-false-sort-refused.

  Reviewed as correct.

• Gates (head): mcp 663, spec 24376, rest pin 6/6, eslint 0, the changeset gate and the ADR-0087 gate exit 0 with the revised body, 107 dispatch-gates exit 0, and dogfood 416 files / 3456 tests. In CI, only Check Changeset is red, because it reads the stale live body.

• Accepted deviations:

  • The harness-pinned branch claude/project-thread-kqbqmk.
  • The engine door is left unchanged, so hooks and flows still sort freely, as Not changed states.
  • Out of scope and filed: lint: a view sort naming a field the author declared sortable: false clears validate, then 400s on every load once #29896 lands — validate-sortable-fields judges only the virtual predicate #30023 (lint judges stored sorts; it also takes the wider page dataSource.sort surfaces) and ui(list): a stored view sort the platform's sortability projection refuses is still sent to the server on fetch (ListView L3186), so the list 400s instead of dropping it; client-side sorting still offers a sortable: false header #30024 (the ui fetch-side filter).
  • The seat applies the signed trailer and the replacement body through the relay.

• Landing: on all-green at this head, the seat sends pr_ready + automerge_enable through the relay. The protocol.ts codemod window (Codemod split: generate the rest of the metadata-protocol protocol.ts split with a deterministic script, verified byte-identical #29985) opens after this merges.