## Problem/motivation After #3586394, selection uses a six-group ladder: `global → always-included → exact-match → scope-scored → situational-match → broad-fill` Scope plugins still expose one flag, `supportsSubscriptions()`, and that flag now gates **five** behaviors: 1. **Agent-form widget visibility** — `AiContextAgentForm` and `AiContextScopeSubscriptionFormBuilder` hide `FALSE` scopes from the subscription form and list them in the "do not allow subscriptions" note. 2. **Exact-match eligibility** — a `FALSE` scope whose `matchesRequestContext()` returns `TRUE` enters the **exact-match** group in all modes, including Minimal (`AiContextScopeResolver::getExactMatchItems()`). 3. **Subscription-scoring participation** — `FALSE` scopes are skipped in `calculateScopeScore()`. 4. **Minimal-prefilter index candidacy** — items indexed under a `FALSE` scope are loaded into Minimal's candidate set (`getNonSubscriptionIndexedItemIds()`). 5. **Save-time value preservation** (#3586412) — stored subscription values for `FALSE` scopes are preserved on save (`AiContextScopeManager::preserveUnusableScopeValues()`). A sixth behavior, **situational-match** (Relevant and above), is a hardcoded allowlist — `SITUATIONAL_SCOPE_PLUGIN_IDS` on `AiContextScopeResolverInterface` (language, site_section, entity_type, taxonomy) — read by both `getSituationalMatchItems()` and `AiContextSubscriptionBudgetCalculator::isPotentialContextMatch()`. Consequences: - Custom scopes cannot opt into situational-match without a core change. - Returning `FALSE` cannot mean "hide from the agent form" without also becoming exact-match eligible and entering the Minimal prefilter. Roles (#3586415) works around this by never returning `TRUE` from `matchesRequestContext()` **plus** a hardcoded per-ID exclusion in `getNonSubscriptionIndexedItemIds()` so Minimal does not load Roles-indexed items it would always discard. That hardcode is the symptom this issue removes. - `docs/developers/scope_api.md` already tells custom scope authors "a future release may split them into explicit capability methods." This is a public plugin-contract change (`docs/developers/api-stability.md` lists `AiContextScope` plugins as a public extension point), so it needs its own issue and beta-upgrade documentation rather than riding along inside #3586394. ## Proposed resolution Split the conflated flag into three explicit capability methods on `AiContextScopeInterface`, with defaults on `AiContextScopeBase`, following the `isAvailable()` precedent (method added directly to the interface in beta, base-class default, "Beta upgrade" note telling direct interface implementations to add it): - `supportsSubscriptions(): bool` — show on agent subscription forms, participate in subscription scoring, and have stored values preserved when hidden. Keeps its current base default (`TRUE`) and current overrides (Global, Roles, Entity Item return `FALSE`). - `supportsExactMatch(): bool` — a positive `matchesRequestContext()` may enter the exact-match group, and the scope's indexed items are Minimal prefilter candidates. Base default is **`FALSE`** — exact-match is opt-in, because a strict match injecting the item in every mode (including Minimal, with no subscription) is a strong behavior a scope must declare deliberately. Entity Item declares `TRUE` and is the only built-in that does; Roles and Global inherit the default, with the rationale in their class docblocks (for Roles, inheriting `FALSE` is what replaces the #3586415 hardcode, keyed off the capability in the resolver and pinned by the capability matrix test). The old implicit rule (`supportsSubscriptions(): FALSE` ⇒ exact-match eligible) is retired: custom scopes that relied on it must add `supportsExactMatch(): TRUE`, documented as a beta upgrade. The `ai_context_test_scope_exact_match` fixture declares the capability explicitly. - `supportsSituationalMatch(): bool` — a positive `matchesRequestContext()` may enter situational-match in Relevant and above. Base default **`FALSE`**; Language, Site Sections, Entity Types, and Taxonomy Terms return `TRUE`. Behavior defaults (unchanged behavior for every existing plugin): | Plugin | supportsSubscriptions | supportsExactMatch | supportsSituationalMatch | |---|---|---|---| | global | FALSE | FALSE (default) | FALSE | | use_case | TRUE | FALSE (default) | FALSE | | tag | TRUE | FALSE (default) | FALSE | | roles | FALSE | **FALSE (default — replaces the #3586415 hardcode; pinned by the capability matrix test and documented in the class docblock)** | FALSE | | language | TRUE | FALSE (default) | **TRUE** | | site_section | TRUE | FALSE (default) | **TRUE** | | entity_type | TRUE | FALSE (default) | **TRUE** | | taxonomy | TRUE | FALSE (default) | **TRUE** | | entity_item | FALSE | **TRUE (explicit)** | FALSE | Resolver changes: - `getExactMatchItems()` and `getNonSubscriptionIndexedItemIds()` select scopes by `supportsExactMatch()` instead of `!supportsSubscriptions()` minus per-ID exceptions; remove the Roles hardcode, rename `getNonSubscriptionIndexedItemIds()` to `getExactMatchIndexedItemIds()` to match its new semantics (internal interface), and update the matching comments in `AiContextSelector`. - `getSituationalMatchItems()` selects scopes by `supportsSituationalMatch()`; retire `SITUATIONAL_SCOPE_PLUGIN_IDS` (internal interface, allowed) and switch its second reader, `AiContextSubscriptionBudgetCalculator`, in the same commit. - Align the situational path's gate with the `isEnabledAndAvailable()` gate every other selection path uses (it previously required only `isEnabled()`, the lone outlier): an unavailable scope is now ignored by every path. The concrete behavior change is Language on a monolingual site — items still carrying language values (from before a language was removed, or from imports; the tag cannot be created through the UI there) are no longer situationally included in Relevant. They still pass hard filters, so they stay reachable via Broad, Global, Always include, or another matching scope, and resume matching when a second language makes the scope available. Apply the same gate in `AiContextSubscriptionBudgetCalculator`'s Relevant estimate, which previously had no enabled/available check, so estimates match selection. Update the kernel tests that relied on monolingual language situational matches to configure a second language, and add coverage pinning the new rule in both directions. (Related but separate: #3586416 cleans stored values whose *option* was deleted; this gate governs still-valid values on a scope that is currently unavailable — the values #3586412 preserves on save.) Because the capabilities are independent declarations, a scope may declare both `supportsSubscriptions()` and `supportsExactMatch()` — newly expressible under the split. Document the ordering consequence: exact-match outranks scope-scored. No update hook, config schema change, or migration: capabilities are code-level plugin methods; nothing is persisted. ## Remaining tasks - Add the three methods to `AiContextScopeInterface`, defaults to `AiContextScopeBase`, explicit overrides per the table above. - Rewrite `AiContextScopeResolver` (exact-match, situational, and the renamed `getExactMatchIndexedItemIds()`) and `AiContextScopeResolverInterface` docblocks; remove the Roles hardcode; sweep `AiContextSelector` comments. - Switch `AiContextSubscriptionBudgetCalculator` off the retired constant. - Align the situational and estimate gates on `isEnabledAndAvailable()` and update the kernel tests that relied on monolingual language situational matches (second configured language via an `addSpanishLanguage()` helper); add coverage that an enabled-but-unavailable scope is ignored in Relevant but its items still reach Broad, and that matching resumes when the scope becomes available. - Update `ai_context_test_scope_exact_match` to declare `supportsExactMatch(): TRUE` explicitly; add a new test scope module for a custom **situational** scope with a kernel test proving it enters situational-match in Relevant and not in Minimal. - Update kernel coverage: resolver, selection-mode ladder, Roles (assert the prefilter skip now comes from the capability, not a hardcode), per-plugin capability assertions, and a regression assertion that `preserveUnusableScopeValues()` (#3586412) still keys on `supportsSubscriptions()`. - Documentation: fulfil the `scope_api.md` split promise; rewrite the `supportsSubscriptions()` sections in `scope_api.md` and `custom_scopes.md`; add a "Beta upgrade: scope capability methods" section to `api-stability.md` (direct interface implementations must add the methods); update the situational-scope enumerations in `features/scopes.md`, `features/context_selection.md`, and `developers/services.md`; document that situational `matchesRequestContext()` implementations must be cheap and memoize current-value resolution — Relevant and Broad scan the full published catalog and situational plugins pay `matchesRequestContext()` twice per item. - Resolve the two `custom_scopes.md` cross-references that promise this issue makes custom-field/external storage discoverable by Minimal: that is index participation, not a capability flag, and is **not** delivered here — re-point both references at a dedicated follow-up issue opened with this MR. ## UI changes None. Form visibility semantics are unchanged; the agent subscription form and the "do not allow subscriptions" note behave exactly as today. ## API changes Three methods added to `AiContextScopeInterface` (public extension point) with `AiContextScopeBase` defaults; `supportsSubscriptions()` keeps its signature with a narrowed, documented contract. `SITUATIONAL_SCOPE_PLUGIN_IDS` is removed from the internal resolver interface. One behavior change: situational matching (and the budget estimate) now ignores enabled-but-unavailable scopes, like every other selection path. Documented in a change record and an api-stability.md beta upgrade section. ## Data model changes None. ## Sequencing - Land **before** #3586438 (split scope weight) — both change the scope plugin contract and the same `scope_api.md` method tables. - Safe to land before #3586346 (consumer rearchitecture): the subscription form builder's `supportsSubscriptions()` semantics are unchanged, and #3586346's consumer editor inherits them as-is. ## Follow-up candidates - Custom scope storage / Minimal index participation for scopes that do not use the scope field (the re-pointed `custom_scopes.md` references). - #3586438: split display weight from scoring weight. - #3586448: decide whether Languages should stop supporting subscriptions — the first use of the no-subscriptions + situational combination this split makes expressible. ## AI usage - [x] AI assisted issue