## Summary Follow-up to: #3586243+s Before 1.0, lock down what custom scope authors and contrib can safely depend on, without landing the full persistence/orchestration refactor from [#3586243](https://git.drupalcode.org/project/ai_context/-/work_items/3586243). This issue is documentation and internal seam-setting only: no new public interface methods and no user-visible behavior changes. The current scope plugin API is already broad enough for map-backed custom scopes, but docs and code send mixed signals. The scope manager is marked `@internal` while developer docs show injection patterns; the resolver interface docblock calls itself public while `api-stability.md` treats it as internal; `supportsSubscriptions()` is documented for agent forms but also drives context auto-inclusion internally; and core code still hardcodes `'global'`, `'target_entity'`, and `'use_case'` in scattered places. ## Problem | Concern | Today | |---------|--------| | Public vs internal boundary | Contradictory docs for manager and resolver | | `supportsSubscriptions()` | Documented as agent-form visibility only; also used for auto-inclusion | | Custom scope storage | Implied flexibility via `getValuesFromEntity()`; no clear 1.0 contract for custom storage | | Internal coupling | Magic scope ID strings and a one-off `target_entity` branch in stored-value summary logic | | Superseded work | [#3586243](https://git.drupalcode.org/project/ai_context/-/work_items/3586243) / [MR !164](https://git.drupalcode.org/project/ai_context/-/merge_requests/164) attempted a large refactor that is out of scope for 1.0 | ## Solution 1. **Documentation alignment** - In `api-stability.md`, `scope_api.md`, and `custom_scopes.md`, state clearly: - Scope plugins, hooks, and the subscription form builder are public. - `plugin.manager.ai_context_scope`, the resolver, index, and cleanup services are internal. - Document that `supportsSubscriptions(): FALSE` means both (a) hidden on agent subscription forms and (b) eligible for context auto-inclusion when `matchesCurrentContext()` returns TRUE. - State explicitly: **1.0 custom scopes are supported on the scope map field**; custom entity-field storage, indexing, cleanup, and form lifecycle integration are **not** a supported extension surface in 1.0 (planned for 1.1). 2. **Internal identifier cleanup** - Add `PLUGIN_ID` constants to built-in scope plugins (matching the existing `VALUE_GLOBAL` pattern). - Replace internal `'global'`, `'target_entity'`, and `'use_case'` string literals in `src/` with those constants where safe. 3. **Single internal seam for target entity stored values** - Consolidate the `target_entity` special case in stored-value summary logic (e.g. `AiContextScopeManager::buildScopeSummaryFromStoredValues()`) behind one private/internal helper so 1.1 persistence work does not require hunting call sites. 4. **Tests** - Add or adjust kernel/unit tests covering constants and unchanged behavior (stored vs effective scope summaries, subscription form builder still works, no regression in scope plugin discovery). ## Out of scope - New methods on `AiContextScopeInterface` - Splitting `supportsSubscriptions()` into separate capability flags - Target entity encapsulation, manager orchestration, presave validation, index/cleanup plugin APIs - Per-item inclusion mode, agent-form UX reframing ([#3586281](https://git.drupalcode.org/project/ai_context/-/work_items/3586281)) - Boundaries / exclusions ([#3586197](https://git.drupalcode.org/project/ai_context/-/work_items/3586197)) - Moving `target_entity` storage from DER into the scope map ## Acceptance criteria - [ ] `api-stability.md`, `scope_api.md`, and `custom_scopes.md` agree on public vs internal scope-related APIs - [ ] Dual semantics of `supportsSubscriptions()` are documented with examples - [ ] 1.0 custom-scope storage contract is explicit (scope map yes; custom storage lifecycle no) - [ ] Built-in scope plugins expose `PLUGIN_ID` constants; internal literals in `src/` use them - [ ] Target-entity stored-value handling uses one internal helper, not ad hoc branching at call sites - [ ] `./lint.sh` passes - [ ] Relevant kernel/unit tests pass - [ ] [#3586243](https://git.drupalcode.org/project/ai_context/-/work_items/3586243) closed with pointer to this issue and the 1.1 follow-up; [MR !164](https://git.drupalcode.org/project/ai_context/-/merge_requests/164) closed as superseded ## Related - Supersedes: [#3586243](https://git.drupalcode.org/project/ai_context/-/work_items/3586243) - Builds toward: 1.1 capability-based persistence API issue (to be created) - Downstream UX/semantics: [#3586281](https://git.drupalcode.org/project/ai_context/-/work_items/3586281) → [#3586197](https://git.drupalcode.org/project/ai_context/-/work_items/3586197) ## AI usage - [x] AI assisted issue