Skip to content

Abilities API: Clarify execution when output validation fails - #16122

Open
gziolo wants to merge 13 commits into
WordPress:trunkfrom
gziolo:fix/ability-output-validation
Open

gziolo wants to merge 13 commits into
WordPress:trunkfrom
gziolo:fix/ability-output-validation

Conversation

@gziolo

@gziolo gziolo commented Nov 20, 2026 •

Copy link
Copy Markdown
Member

When an ability's callback completes but output validation fails, callers can mistake the error for a failure to execute and retry an operation whose changes have already been saved.

WP_Ability::validate_output() prepares one of two complete messages before validation and filtering:

  • Read-only: Ability "%s" returned a result that failed validation.
  • Otherwise: Ability "%s" ran, but its result failed validation. The requested action may already have taken effect. Check the outcome before retrying.

Only an explicit readonly: true selects the read-only message; false and the default null receive retry guidance. Schema failures append the validation reason. The warning covers actions such as sending email as well as saved data.

The message applies to Core's schema-validation errors and to wp_ability_validate_output returning false. Schema errors already carry the complete message when the filter receives them. Custom WP_Error results are returned unchanged, preserving the extender's control over messages, codes, and data. Callback errors and errors returned before output validation remain unchanged.

Trac ticket: https://core.trac.wordpress.org/ticket/66433

Prior work and attribution

Continues #15333. Its original commit is included as 9296bfcd26, preserving Michael Etokakpan (@MicahelE) as the author.

Carrying over the prior PR's props list:

Props micahele, gziolo, zaguiini.

Validation

  • Abilities API suite: single-site passed with 921 tests and 3,178 assertions; multisite passed with 926 tests and 3,200 assertions, including REST responses.
  • Tests ran with local PHP 8.4.5 against the Docker MySQL 8.4 test database using an isolated table prefix.
  • One new parameterized test covers read-only, non-read-only, and default annotations when a filter rejects output. Existing filter tests verify context before filtering and unchanged custom errors; existing schema and REST tests assert the updated messages.
  • PHPCS on all four changed files.
  • PHPStan on the changed source file.

Use of AI Tools

AI assistance: Yes
Tool: Codex
Model: GPT-6
Used for: Reviewing the existing PR and related requirements, implementing the changes and regression tests, running validation, and drafting this PR description. The original commit retains its author's AI disclosure in #15333.


This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.

MicahelE and others added 2 commits November 20, 2026 09:54
`WP_Ability::execute()` runs the callback and then validates its output. When validation fails, the caller gets an error but cannot tell that the callback already ran, so it may retry and repeat the same change.

The error data now includes `callback_executed` set to true. This also applies to errors from the `wp_ability_validate_output` filter, and any data they set is kept.

See #66433.
Preserve validation errors and attach a JSON-normalized output snapshot when serialization succeeds. Advise callers to check state before retrying abilities that are not explicitly read-only.

Builds on WordPress#15333.

Props micahele, gziolo, zaguiini.

See https://core.trac.wordpress.org/ticket/66433.
@github-actions

This comment has been minimized.

@github-actions

Copy link
Copy Markdown

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

  • All changes will be lost when closing a tab with a Playground instance.
  • All changes will be lost when refreshing the page.
  • A fresh instance is created each time the link below is clicked.
  • Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
    it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

…guidance.

Clarify failed output validation in validate_output(), distinguishing explicitly read-only abilities from abilities that may have side effects. Preserve error codes and data, and remove rejected output serialization.

Props micahele, gziolo, zaguiini.

See https://core.trac.wordpress.org/ticket/66433.
@gziolo gziolo changed the title Abilities API: Include output and retry guidance in validation errors Abilities API: Clarify execution when output validation fails Nov 20, 2026
Include execution context in schema errors before filters run, reuse it when a filter returns false, and preserve context without duplication for custom or rewritten error messages.

See https://core.trac.wordpress.org/ticket/66433.
Test annotation-dependent wording separately from filter behavior, use exact messages instead of overlapping substring assertions, and fold duplicate REST coverage into the existing validation test.
Reuse existing filter tests for execution context and custom error preservation. Keep one parameterized annotation test and remove redundant filter, early-failure, and callback coverage.
Keep execution context in Core-generated errors while preserving extender control over errors returned by the output validation filter.
Distinguish an invalid read-only result from an action that may already have taken effect. Retain focused coverage and preserve the existing custom-error test scenario.
@gziolo gziolo self-assigned this Nov 20, 2026
@gziolo
gziolo requested a balanced review from Copilot November 20, 2026 10:58
@gziolo
gziolo marked this pull request as ready for review November 20, 2026 11:00
@github-actions

Copy link
Copy Markdown

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs.

Core Committers: Use this line as a base for the props when committing in SVN:

Props micahele, gziolo.

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


Props Bot commands

You can trigger Props Bot actions by commenting on this PR:

  • @propsbot add <username> to give props to a GitHub or WordPress.org user. Requires write access.
  • @propsbot remove <username> to leave a user out of the props. Requires write access.
  • @propsbot refresh to refresh this list. Adding the props-bot label works too.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues were identified for the change clarifying retry risks after output validation failures.

No open issues 🎉

What changed in this PR

This PR clarifies that an ability has already run when output validation fails, helping callers avoid retrying actions that may already have taken effect.

Changes:

  • Adds retry guidance unless the ability is explicitly read-only.
  • Applies the messages to schema failures and filter rejections while preserving custom errors unchanged.
  • Updates unit and REST assertions and adds parameterized coverage for read-only annotations.
File Description
tests/​phpunit/​tests/​rest-api/​wpRestAbilitiesV1RunController.php Updates REST error expectations and verifies null error data.
tests/​phpunit/​tests/​abilities-api/​wpRegisterAbility.php Updates the expected read-only validation message.
tests/​phpunit/​tests/​abilities-api/​wpAbility.php Tests retry guidance, filter context, and custom error preservation.
src/​wp-includes/​abilities-api/​class-wp-ability.php Adds annotation-aware validation messages and documents error behavior.

Review effort: Balanced

@jorgefilipecosta jorgefilipecosta left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The change makes total sense. I wonder if it would make sense to include the invalid output on the error message as a string, so agents can better understand what happened. But even if we do that it can be follow up.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants