## Problem/motivation Last call for public API naming and signature changes before beta5 is tagged. After this lands, the surfaces in `docs/developers/api-stability.md` are the freeze: scope plugins, optional scope interfaces, consumer types, selection factory / params / result, documented events, and the config and permission names listed there. ## Solution Final pass on leftover unused APIs, public-vs-internal visibility, a small set of contract holes, and naming. Prefer the names shipped in #3586346+s / !283 unless something is clearly wrong. This issue is the freeze record. Naming keep/skip decisions are listed below so they do not reopen. Remaining test work stays on #3586455+s except for the contract tests that shipped with this change. A saved-agent `tool_usage_limits` rename from `agent_id` to `consumer_id` is documented here and deferred so it does not land with the beta4-to-beta5 path on #3586470+s. ## Naming decisions (keep / skip) Recorded so these do not resurface before 1.0: | Decision | Outcome | |----------|---------| | Event classes `AiContextSelectionItemsSelectedEvent` / `AiContextSelectionTextRenderedEvent` | **Keep.** The `Selection` prefix matches the VO/factory family. Event *string* names stay `ai_context.selection.*`. | | Scope `defaultConfiguration()` → `defaultSettings()` | **Skip.** Scopes do not implement `ConfigurableInterface`. Consumers already use `defaultTypeSettings()`. Skip for churn; the split is documented. | | `submitSettingsForm()` → extract-style name | **Skip.** Matches Form API `submitForm`. | | Shorten `getSubscriptionScoringWeight()` | **Keep.** The long name is the display vs scoring split. | | Prefix `SchedulerAiContextItemEvents` to match CCC events | **Skip.** Follows Scheduler’s `Scheduler{Entity}Events` pattern; strings are already `scheduler.ai_context_item_*`. The class and strings are listed as public. | | `getLabelRoute()` / `getManageRoute()` return `Url` | **Keep arrays** `{route_name, route_parameters}`. Same module pattern on both sides. | | `excluded_request_tags` configurable | **No.** Hard-coded on the router; documented. | | `hook_ai_context_consumer_type_info_alter()` | **Do not add.** Types are owned by the consuming project. Site lever is `enabled` on `ai_context.consumer_type_settings.{type}`. | | `getMaxTokens()` on the items-selected event | **Skip.** Adding the resolved budget later is additive. `$event->getSelection()->getMaxTokens()` is `NULL` when the request defers to site settings. | | Router / Factory / RouteResult / ProviderRequestContext / `getCandidateRequestTags()` | **Keep.** Do not start another naming pass. | | Type vs instance `getId()`, two “request context” meanings, `InvocationResult` vs `ai_context` metadata key | **Leave.** Documented; not worth freeze churn. | | `fromPreGenerateEvent` → `fromPreGenerateResponseEvent` | **Already done** on the consumer branch. | Deferred to 2.x: detected-value cacheability companion, `icon_class` accessor, config-key constants, Site Section AJAX companion interface. ## Extra contract decisions from #3586404+s | Decision | Outcome | |----------|---------| | Omitted / `null` `push_enabled` | **Type default.** Landed here. Schema is nullable. Stored `isPushEnabled()` is NULL; resolve and `isPushAllowed()` use the type default. | | `isGlobal()` when the Global scope is disabled | **Keep.** Returns the stored/effective global flag. Do not AND with `isEnabledAndAvailable()`. If Global is disabled, keep the item checkbox visible (or document that existing globals stay global). Fix stays on the scope rc1 issue. | | Public execute path | **`getResultFromSelection()`** on the factory. Do not inject the `@internal` selector after `fromConsumer()` / `fromParameters()`. | | Tool parameter `agent_id` | **Renamed to `consumer_id`.** Saved `tool_usage_limits` still keyed as `agent_id` are ignored. Re-save on `consumer_id`. A rename hook is a follow-up after #3586470+s. | ## Contract changes that landed - Type-settings save: `NULL` **clears** the key (parity with scopes). Keys omitted from the returned array still stay in config. - Request-context matching goes through public `getDetectedValue()`, not `doGetDetectedValue()`. Custom `matchesRequestContext()` overrides that still call the protected method directly are a leftover bypass; documented. - `resolveConsumerId()` no longer must decline excluded tags. The router pre-filters. Automator’s `hasExcludedRequestTag()` call was removed. The helper stays `@internal` and router-only. - `AiContextSelectionParams::fromArray()` drops an unrecognized `selection_mode` (including leftover `match_all`) to NULL and logs non-empty junk at debug. The factory then inherits the consumer or site default. `AiContextSelection` and `AiContextSelectionResult` constructors, and `fromParameters()`, throw `\InvalidArgumentException` on a non-NULL invalid string (was `assert()`). The params constructor does not validate. - `fromArray()` keeps a non-empty string `entity_id` (machine names). Get Relevant now uses the same rule as List. - `fromArray()` trims a padded canonical `consumer_id` before `isValid()`. The Get Relevant / List subscriber writes the trimmed value back. - `fromArray()` drops a non-string `task` to `''`. `always_include` / `never_include` keep strings and ints and drop everything else (no `(string)` cast). - `AiContextSelectionTextRenderedEvent`: `tokensUsed` and `truncatedItems` are readonly snapshots. `setRenderedText()` does not update them; the selector recomputes `tokensUsed` on the result. - `stopPropagation()` is the Symfony default. The selector does not skip later pipeline steps when it is called. - `buildValueForm()` / `buildWidgets()` take `array $form`, not `array &$form`. Implementations that keep `&` will fatal. - Consumer types gained `getAvailabilityCacheableMetadata()`. Base returns empty metadata; Automator adds `config:core.extension`. Router and admin listings merge it. Automator no longer hand-patches that tag inside `getInstances()`. - Consumer types gained `getConsumerIdForDeletedEntity()`. The attribute may set `host_entity_type` for the 1:1 case. Merged from #3586489+s. - `AiContextSelectionResult::getSelectionMode()` returns the resolved ladder rung (`minimal` / `relevant` / `broad`). Never NULL. - `getCacheableMetadata()` on the result returns a clone. - `getSelectedItems()` is `label` + `purpose`. `getSelectedItems(TRUE)` is the selector full payload. New keys may be added later. Removing or renaming a key is a break. - `AiContextScopeInterface::isEnabledAndAvailable()` is the public usable gate. The manager helper delegates and stays `@internal`. - `AiContextSelectionFactoryInterface::getResultFromSelection()` is the supported execute path. - Stored and resolved consumer config expose `getSettings()`. - `usage_max_records` and `usage_max_age` have schema `Range` `min: 0` (no max). - `AiContextItemPriority` is public allowed-values API. - `SchedulerAiContextItemEvents` and the `scheduler.ai_context_item_*` strings are public. - A non-empty non-canonical tool `consumer_id` is replaced with `agent:{running agent}` and logged at debug. - Scope-value labels keep `<` (no `strip_tags()`). Pill tooltips are encoded for `data-ai-tooltip`. The cutoff is 17 characters (`mb_strlen()`), matching CSS `17ch`. - Post-update `0009` clears leftover Diff `fields.ai_context_item.tags` on sites that have Diff. Ahmad’s stale-keys note from #3586346+s: leftover keys that a plugin stops returning stay until an explicit clear. That save behavior is unchanged; type-settings NULL is now the explicit clear. ## Removals and visibility Removed unused public leftovers, including `isDynamic()`, scope `getId()`, entity-item render helpers, router `resolveConsumerId()`, collection `getCacheableMetadata()`, unused usage setters, `getAllScopeValues()` / `buildScopeSummaryFromEntity()`, and dead `AiContextLimitResolver`. Public service IDs and interfaces stay public; concrete factory / form-builder classes are `@internal`. Views field, function-call, and formatter **plugin IDs** stay public config; their PHP classes are `@internal`. Site Section path helpers are `protected`. Form API callbacks stay public and `@internal`. `isLoopAware()` lives on the Agent type only, not on generic stored / resolved consumer config. ## Out of scope - Consumer leftover hardening still parked: re-entrancy, updates 10028 / 10031. The dead `resolveLimit()` helper **was** removed here (zero callers). - Consumer admin leftovers (type-settings local-task trail, unguarded `Url::fromRoute()`). - Broader test coverage on #3586455+s. Tests that pin this issue’s contract changes shipped with the MR. - Contributed-type instance-settings UI (by design; they own that form). - `tool_usage_limits` `agent_id` → `consumer_id` rename hook (after #3586470+s; see #3586484+s / !296). - `isGlobal()` when Global is disabled (scope rc1). - 2.x add-ons listed above. ## Related issues #3586346+s, #3586404+s, #3586455+s, #3586470+s, #3586484+s, #3586489+s ## AI usage - [x] AI assisted issue