While developing the TypeSafe AI provider, I began to create "Decision" operation types. First ai_decision was part of ai_provider_typesafe_ai, then I split into its own project, now we are working to integrate the functionality into AI core without a separate submodule. Throughout the evolution of that development and testing this issue was discovered and a fix developed in https://git.drupalcode.org/project/ai/-/merge_requests/2046 among updates for other issues. This is 5 of a set of issues that will be solved with this MR. ## Problem/motivation `ProviderProxy` dispatches `PreGenerateResponseEvent` before it calls the provider's operation method. Pre-generation subscribers include guardrails: global guardrail sets attach at priority 100, and some checks are themselves paid AI calls, such as moderation or restrict-to-topic. Some requests are invalid for the selected provider and model before anything is sent. Examples: - the input has the wrong type or is empty; - it uses a feature the model doesn't declare; - it exceeds a known limit, such as the number of choice options. Today the provider only rejects these inside its operation method, after every pre-generation subscriber has run. So: - **Wasted spend.** The site pays for guardrail calls on a request that was never going to be sent. - **Misleading records.** Logging and observability see a pre-generation event for a request that could not execute. A pre-generation subscriber can't do this check reliably. The event carries the provider ID and configuration, not the configured provider instance, and creating a fresh instance loses configuration set on the caller's instance. The first consumer is Decision (#3586751). Its providers declare per-model capabilities and must reject unsupported requests with `validateDecisionInput()` before transport. ### Steps to reproduce 1. Attach a guardrail set with a Moderation pre-check backed by a paid provider, globally or on the input. 2. Through the proxy, call an operation whose provider rejects the request in its operation method: for example a Decision request with more choice options than the model's declared maximum. 3. The moderation provider is called first; only then does the operation provider throw `AiBadRequestException`. ## Proposed resolution **Declaring a validator** - `#[OperationType]` gets an optional `input_validation_method` argument naming a method on the operation interface. - The method must be a public instance method taking the input and a `string` model ID and returning `void`, with no references or variadics. - It must not run inference or change its arguments. - Discovery and `AiProviderPluginManager::getOperationTypes()` expose the value as `input_validation_method`, which is `NULL` when an operation doesn't opt in. **What the proxy does** - In `ProviderProxy::wrapperCall()`, the validator runs after configuration and tags are normalized and the pre-generation event is built, but before that event is dispatched. - It resolves the validator from the operation interface that matches the trigger method, and invokes it on the same configured provider instance with the input and model ID. - It first checks the input against the validator's parameter type. A mismatch becomes an `AiBadRequestException` instead of a PHP `TypeError`. - A missing method, a wrong signature or conflicting validators raise `AiSetupFailureException`. **Errors** - All of these exceptions take the existing exception path, now shared in a private `handleOperationException()`. It wraps raw HTTP client exceptions and dispatches `AiExceptionEvent` with the thread ID, provider, operation, configuration, input, model, tags, debug data and metadata. - It returns a subscriber's forced output when one is set; otherwise it re-throws. This is the same behavior as for provider errors today. **Unchanged** - Operations that don't opt in keep their current event order. - Providers must still validate inside the operation method, because pre-generation subscribers can change the input or configuration after the early check. Decision opts in with `input_validation_method: 'validateDecisionInput'`. ## Remaining tasks - Review. Points worth a look: - **Per-call reflection.** The validator is resolved by reflection on every proxied call, for all operations including chat. The cost is small; caching the result per provider class and trigger method would remove it. - **Exception without a start event.** An early rejection dispatches `AiExceptionEvent` with no preceding `PreGenerateResponseEvent`. Subscribers that pair start and end events must tolerate an exception for a thread ID they haven't seen. Webprofiler's AI collector already ignores such events, so rejected calls don't appear in its panel. - Decide whether other core operations should opt in. ## User interface changes None. ## API changes - New optional `input_validation_method` argument on the `OperationType` attribute, and a matching key in operation type definitions. - For operations that opt in, the proxy validates input before `PreGenerateResponseEvent`. A rejection dispatches only `AiExceptionEvent`. - No change for operations that don't opt in. ## Data model changes None.