docs: #3583031 Document the access() contract and its input-validation gate

Closes #3583031 (closed)

Summary

Scoped per @michaellander's comment: item 4 plus writing the access() contract down. No behaviour change. Items 1 (Forbidden vs Neutral) and 3 (the values-free question) are left for the access-phases / runner follow-ups; item 2 was crossed out in the summary.

  • ToolInterface::access() docblock now states the question it answers, that the answer is value-dependent and can change after setInputValue(), that it is deliberately not an answer to "may this account use this tool at all", why the validation denial is generic and not cacheable (#3582961 (closed)), and that callers must call validateInputs() first to tell a correctable argument problem from a permission problem. Return value documented, @see links added.
  • ToolBase::access(): the catch branch gets a comment with the same reasoning.
  • ToolBase::checkAccess(): two stale lines fixed — "By default, it returns forbidden access" (the method is abstract) and "Defaults to current user" on $account (already resolved by access()).
  • docs/configuration.md and docs/developers/creating-a-tool.md: the same contract for consumers and tool authors, with a validate-then-access snippet. This goes slightly past "the docblock" — happy to drop it if you want the MR tighter.

Notes for review

  • The docblock cites #3583031 (closed) as where the design for splitting the two questions lives. Once the follow-up issues exist, that reference should point at them instead.
  • Diff touches no executable code and no tests; the existing ToolBaseTest::testAccess* cases already pin the documented behaviour.

Testing

Check Result
phpcs (project phpcs.xml, all of src/) 0 errors, 0 warnings
phpstan level 3, module config no errors
PHPUnit full suite, Drupal 11.4.7 / PHP 8.3 589 tests, 2,279 assertions, 0 failures
mkdocs build --strict clean, new anchor link verified

Merge request reports

Loading
Loading