Reviewed application entitlement lifecycle

plan_application_test_entitlement_change, execute_application_test_entitlement_change, plan_application_entitlement_consumption, execute_application_entitlement_consumption, review_application_test_entitlement_change, and review_application_entitlement_consumption belong only to the independent application-entitlement-changes toolset. Test changes require capabilities.applicationTestEntitlementChanges; consumption requires the separate capabilities.applicationEntitlementConsumption. Neither capability, the read-only application-monetization toolset, ordinary guild scope, nor SKU audit grants the other authority.

Test-entitlement policy uses exact scopes.applicationTestEntitlementGuildIds, scopes.applicationTestEntitlementUserIds, and scopes.applicationTestEntitlementSkuIds. A test guild must also be in the outer readScope.guildIds. Consumable policy uses exact scopes.applicationConsumableEntitlementUserIds and scopes.applicationConsumableEntitlementSkuIds. Both write-specific SKU allowlists must be subsets of scopes.applicationMonetizationSkuIds so fresh complete-catalog evidence is bounded to operator-selected current-application SKUs; this shared evidence scope does not require or grant capabilities.applicationMonetizationAudit.

Test creation accepts only one exact configured guild or user and one exact current-application subscription SKU whose documented guild or user purchase scope matches that beneficiary. Planning freshly verifies the pinned application and bot, reads the complete current SKU catalog, and obtains a complete present-access inventory for that exact beneficiary and SKU. An existing matching entitlement is a no-op. Otherwise execution submits one non-retried test-entitlement creation, validates its exact response, durably checkpoints the returned entitlement ID before further observation, and requires an independent exact-ID readback.

Test deletion requires acknowledgeIrreversibleDeletion: true, the exact entitlement ID, and the original creation operation key. A completed connector receipt must bind that creation key to the same application, beneficiary, SKU, entitlement ID, verified readback, and content-free activity record. Planning also requires exact current lifecycle evidence for the same perpetual test entitlement. Arbitrary, externally created, receipt-mismatched, already ended, or ambiguous entitlement deletion is unavailable. Execution sends one non-retried exact-ID deletion and accepts only exact deleted-state readback or authoritative absence; there is no rollback or recreation path.

Consumable entitlement consumption accepts only one exact configured user, current-application SKU, and entitlement. Fresh complete SKU evidence must identify a consumable SKU with no subscription purchase-scope flag, and exact lifecycle evidence must identify the same active, unconsumed, non-deleted user entitlement. The caller must set acknowledgeExternalFulfillment: true only after the application has durably delivered its own purchased benefit and supply one application-owned durable fulfillmentReference. The connector cannot verify fulfillment, refund a purchase, restore consumption, or roll back; it persists only a domain-separated SHA-256 hash of the reference. Execution sends one non-retried consume request and requires exact consumed: true readback.

Both planners bind the complete fresh identity, SKU, beneficiary, entitlement, lifecycle, no-op, risk, warning, privacy, verification, one-shot operation-key, and action-specific acknowledgement evidence into a process-keyed digest. A restart invalidates that digest. The signed MCP request state contains only exact IDs, action, acknowledgement values, operation-key and fulfillment-reference hashes when applicable, creation-proof hash when deleting, and the plan digest. It never contains the raw local reason, operation key, creation key, or fulfillment reference. The local auditReason is transient and neither sent to Discord nor persisted because these Discord endpoints do not support an audit-log reason.

Execution requires MCP host write approval, signed interactive confirmation, and another exact fresh-plan match. A no-op returns without confirmation, operation-key reservation, activity, or Discord mutation; the production facade may briefly acquire and release the application collection claim while rechecking that result. A real change acquires the durable application-wide entitlement collection claim, atomically reserves its one-shot operation key, appends pending content-free activity, and performs one mutation. Rate limiting, timeout, transport ambiguity, server failure, malformed success, response mismatch, readback failure, or durable-finalization failure is uncertain: the key remains spent, the claim remains quarantined, and the connector never retries, guesses, compensates, or continues with another application entitlement write.

Activity and receipt records contain only application, beneficiary, SKU, and entitlement IDs; action; domain-separated hashes; stage; timestamps; fixed status, outcome, and verification values; activity ID; and sanitized error category. They never contain product text, beneficiary profiles, raw payloads, audit reasons, raw keys, fulfillment references, credentials, or transport causes. Both guided prompts strictly validate their action-specific inputs, call only the matching planner, explain the irreversible and external-system boundaries, and stop before execution. Discord's Entitlement resource and SKU resource define the external lifecycle and product-type contracts.

Canonical source: docs/reference.md