## Summary Follow-up to: #3586595+s When the token budget is too small, the renderer shortens some items and leaves others out. CCC still reports and records every selected item as delivered: * `AiContextSelectionResult::getSelectedItemIds()` returns the items selected before rendering (`AiContextSelector::renderAndBuildResult()`). * `getTruncatedItemIds()` mixes items that were shortened with items that were left out completely, so a caller cannot tell them apart. * Both push paths (`AiContextBuildSystemPromptSubscriber` and `AiContextPreGenerateResponseSubscriber`) record usage for every selected ID. The generic path also puts the same IDs in the invocation result (`item_ids`, `item_count`). Result: the usage pages show an item as used by a consumer that never received it, and the invocation result says that the item was pushed. Seen on 1.0.x `8a57807`, from the code. Reproduced on a site by dcgoodwin during the review of !363 (2026-11-05), on both push paths. ### Steps to reproduce 1. Turn on usage tracking. 2. Create three published global items of about 1000 tokens each. 3. Set the token budget of a consumer to 1500, and run it (an agent, or a generic chat call). 4. The prompt has fewer than three items, but the usage listing shows all three items as used by the consumer. ## Proposed resolution 1. [x] Make the renderer report the items that it left out separately from the items that it shortened. Keep `getTruncatedItemIds()` as it is, and add a getter, for example `getOmittedItemIds()`. 2. [x] Record usage only for items that were delivered. A shortened item counts as delivered. 3. [x] Put only delivered items in the invocation result. `item_ids` is listed in `api-stability.md` ("Generic-path invocation result"), so document the change as a bug fix in the release notes. 4. [x] Kernel tests: a budget that leaves one item out. Assert the usage records and the invocation result, on both push paths. 5. [x] Docs: `usage_tracking.md` and the "Invocation result" section of `consumer_api.md`. ## Release notes snippet Bug fix: usage records and the invocation result now list only the context items that the token budget delivered to the prompt. An item that the budget shortened counts as delivered. An item that the budget left out is no longer recorded as used. The invocation result keys `item_ids` and `item_count` keep their shape, but they can now contain fewer items on a site with a small token budget. `AiContextSelectionResult::getSelectedItemIds()` does not change. `AiContextSelectionResult` has the new methods `getOmittedItemIds()` and `getDeliveredItemIds()`, and `AiContextSelectionTextRenderedEvent` has the new method `getOmittedItemIds()`. If the budget leaves out every selected item but a `TEXT_RENDERED` subscriber added text, that text is still pushed, with an empty `item_ids` list. See "Beta upgrade: usage and item_ids count delivered items" in `docs/developers/api-stability.md`. ## Questions 1. [x] Should a shortened item count as used? Yes, because part of it reached the model. 2. [x] When the budget leaves out every selected item but a `TEXT_RENDERED` subscriber added text, should the generic path still push that text? Yes, as on 1.0.x and on the agent path. The status is `pushed`, `item_ids` is empty, and no usage is recorded. 3. [x] Does a `TEXT_RENDERED` subscriber that changes or removes item text change what counts as delivered? No. The renderer decides what was delivered, and `usage_tracking.md` and `consumer_api.md` say so. ## Related issues * #3586595+s * #3586600+s ## Stakeholders * @kepol: maintainer (reviews and merges) > [!note] > Check the one that best describes your usage, or leave all unchecked if AI was not significantly used. > > * [ ] AI **Assisted Issue** \ > _Mainly written by a human; AI used for partial generation under full human supervision._ > > * [x] AI **Generated Issue** \ > _Mainly generated by AI, reviewed and approved by a human before this issue was created._