Order the core/read-users collection by display name

[gziolo]

What?

Split out of #931 so it can be reviewed on its own.

Two small changes to core/read-users and one test change for core/read-content:

1. core/read-users collections are now ordered by display name, ascending, and the output schema says so.
2. The comments on test_include_order_does_not_control_the_result_order explain the new order.
3. test_query_lean_projection_does_not_prime_the_post_meta_cache becomes test_query_lean_projection_does_not_request_post_meta_priming and checks what the ability asks for.

Why?

Collection order. core/read-users returned users in whatever order WP_User_Query picked by default, which is by user login. The output schema documented no order at all, so a caller had no way to know what to expect, and the order could change under them. Ordering by display name matches /wp/v2/users, and it is the name a person actually sees in the response. Setting it here and writing it into the schema turns an accident into a promise.

The lean projection test. The old test counted the post meta queries that ran after the request and asserted zero. That measures the wrong layer. Whether update_post_meta_cache is honored belongs to whoever runs the query, and that layer is free to prime more for its own reasons. What this ability owns is the request it builds, so that is what the test now checks.

How?

core/read-users sets orderby => display_name and order => ASC on the collection query, and the users property description in the output schema gains "ordered by name, A to Z".

The include list keeps working the way it did. It selects which users come back, it does not order them, which is also what the REST users controller does unless a caller asks for the include order.

test_query_lean_projection_does_not_request_post_meta_priming hooks pre_get_posts, picks out the query the ability built (the one with a non-empty post__in), and asserts update_post_meta_cache is off on it.

Use of AI Tools

AI assistance: Yes
Tool(s): Claude Code
Model(s): Claude Opus 5
Used for: Extracting these changes from #931, and drafting this description. Verified locally against the test suite. I reviewed and edited the result, and I take responsibility for it.

Testing Instructions

1. npm run wp-env:test start
2. npm run test:php — the full suite passes (1373 tests, 3914 assertions, 44 skipped).
3. npm run lint:php and npm run lint:php:stan — both clean.

To confirm the rewritten test still guards the behavior, make Content::should_prime_post_caches() return true and run it again. It fails.

Changelog Entry

Changed - The core/read-users ability now returns collections ordered by display name, A to Z, and the output schema documents that order.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: gziolo <gziolo@git.wordpress.org>
Co-authored-by: jorgefilipecosta <jorgefilipecosta@git.wordpress.org>
Co-authored-by: dkotter <dkotter@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[github-actions]

✅ WordPress Plugin Check Report

✅ Status: Passed

📊 Report

All checks passed! No errors or warnings found.

---

🤖 Generated by WordPress Plugin Check Action • Learn more about Plugin Check

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 73.87%. Comparing base (e05758f) to head (e6b3257).

Additional details and impacted files

@@            Coverage Diff             @@
##             develop     #948   +/-   ##
==========================================
  Coverage      73.86%   73.87%           
  Complexity      3032     3032           
==========================================
  Files            132      132           
  Lines          12004    12006    +2     
==========================================
+ Hits            8867     8869    +2     
  Misses          3137     3137           

Flag	Coverage Δ
unit	73.87% <100.00%> (+<0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[jorgefilipecosta]

LGTM 👍