---
id: WF-COM-ORD-009
title: 'Grant, draw, restore and revoke entitlements'
trigger: 'Grant obligations, consumption calls, interventions, domain revocation and timed expiry drive rights work.'
product_area: commerce
module: orders
revision: 1
status: draft
design_intent: proposed
implementation_evidence: observed
inference: []
source_sha:
  services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b
implements:
  - CAP-COM-ORD-013
  - CAP-COM-ORD-012
  - CAP-COM-ORD-014
moves:
  - STATE-COM-ORD-008
crosses:
  - SVC-COM-ORD-entitlements
  - SVC-COM-ORD-orders
  - SVC-PFM-ELG-eligibility
  - SVC-PFM-OPS-audit
idempotency: >-
  Grant creation is unique by purchased line and kind. Consumption replays consumer references, and
  interventions use request keys while rejecting already-restored or inactive targets.
concurrency: >-
  Consumption locks eligible grants and checks allowances before inserting uses. Domain revocation and expiry
  serialize with those grant writes; uniqueness prevents duplicate purchased grants.
hops:
  - 'n': 1
    actor_or_service: Delivery register worker (fulfilment module)
    action: Route a grant obligation to Commerce's internal grant handler.
    anchor: 'services-commerce:modules/fulfillment/services/register/obligation-worker.ts'
    seam: queue
    on_failure: >-
      The delegated worker records attempts and outcomes, with exhausted work entering its dead-letter
      handling.
    left_inconsistent: The purchased benefit can remain unavailable until grant delivery finishes.
    observer: Observed through order 360 Fulfilment card; recorded operational exceptions.
    provenance: observed
    source: 'services-commerce:modules/entitlements/services/register/grant-handler.ts'
  - 'n': 2
    actor_or_service: Entitlements
    action: >-
      Interpret the frozen specification, choose its buyer or recipient holder, create the stated allowance
      once per kind and append purchase history.
    anchor: 'services-commerce:modules/entitlements/services/register/grant-handler.ts:grantForObligation'
    seam: sync
    on_failure: Missing or invalid frozen input permanently fails the obligation and raises attention.
    left_inconsistent: Grant and history either commit together or neither commits.
    observer: Observed through the operational exception list.
    provenance: test
    source: >-
      services-commerce:modules/entitlements/tests/e2e/entitlements.e2e.spec.js#delivered the obligation to
      the register: completed, with the grant as its record
  - 'n': 3
    actor_or_service: Consuming application
    action: Consume allowed units through the database function within the consuming application's transaction.
    anchor: 'services-commerce:modules/entitlements/services/persistence/entitlements.ts:consumeEntitlements'
    seam: sync
    on_failure: Inactive or insufficient rights are refused and the caller decides whether its own work proceeds.
    left_inconsistent: Consumption has no independent partial commit.
    observer: Observed through observed through the consuming application.
    provenance: test
    source: >-
      services-commerce:modules/entitlements/tests/e2e/entitlements.e2e.spec.js#gives two downloads and
      refuses the third 409 insufficient_entitlement
  - 'n': 4
    actor_or_service: Staff
    action: >-
      Apply a reasoned manual grant, use restoration or revocation with its intervention log in the same
      transaction.
    anchor: 'services-commerce:modules/entitlements/services/entitlements/entitlement-interventions.ts'
    seam: sync
    on_failure: 'Invalid terms, state, explanation or authority prevent the intervention.'
    left_inconsistent: No partial rights intervention commits.
    observer: Observed through staff; sale history for a purchased grant.
    provenance: test
    source: >-
      services-commerce:modules/entitlements/tests/e2e/entitlements.e2e.spec.js#restores use 1 (an
      intervention: the log row, the history, the audit event), replays under the same key, refuses the same
      use under another
  - 'n': 5
    actor_or_service: Platform audit
    action: Dispatch the committed intervention's audit message.
    anchor: 'services-commerce:modules/fulfillment/services/register/intervention-audit.ts:auditIntervention'
    seam: event
    on_failure: Delivery failure is logged without undoing the rights change.
    left_inconsistent: Durable Platform audit storage is absent with the default provider.
    observer: Observed through observed through commerce's intervention log.
    provenance: observed
    source: 'services-commerce:modules/fulfillment/services/register/intervention-audit.ts'
  - 'n': 6
    actor_or_service: Cancellation or enforcement
    action: >-
      Revoke active line grants for cancellation or enforcement and reinstate only enforcement-caused
      revocation on restore.
    anchor: 'services-commerce:modules/entitlements/services/register/revocation.ts:revokeForCancellation'
    seam: sync
    on_failure: The invoking workflow carries failures; repeated domain revocation does not add another change.
    left_inconsistent: Completed revocation preserves existing use history.
    observer: Observed through sale history (entitlements revoked or reinstated).
    provenance: observed
    source: 'services-commerce:modules/entitlements/services/register/revocation.ts'
  - 'n': 7
    actor_or_service: Entitlement expiry pass
    action: Mark elapsed active grants expired during the shared minute pass.
    anchor: 'services-commerce:modules/entitlements/services/register/entitlement-sweeper.ts:sweepEntitlements'
    seam: schedule
    on_failure: Changed grants are skipped and unexpected errors terminate the invocation.
    left_inconsistent: Stored active status can lag the end of drawable availability.
    observer: Observed through failure activates the function error alarm.
    provenance: observed
    source: 'services-commerce:modules/entitlements/services/register/entitlement-sweeper.ts'
branches:
  - The active-rights view ceases to expose a revoked grant when its revocation commits.
waits:
  - The purchased-line delivery gate must open before granting its rights.
evidence:
  - >-
    services-commerce at c8b66a98: modules/entitlements/services/**; aws/api/entitlements.routes.ts;
    db/migrations/20261018130023_entitlements.sql; tests/e2e/entitlements.e2e.spec.js;
    modules/fulfillment/services/register/obligation-worker.ts, intervention-audit.ts.
controls: [TC-IAM-006, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-AZ-006, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-TEN-004, TC-CRY-001, TC-CRY-004, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-AVL-004, TC-MON-001, TC-MON-002, TC-MON-004, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-PRV-001, TC-PRV-002]
---

# Grant, draw, restore and revoke entitlements

## What It Does

Grant delivery turns frozen benefit specifications into rights and lets consumers draw them within their own transactions. Reasoned staff interventions can restore, grant or revoke, while cancellation and enforcement use domain revocation.

## The Flow

```mermaid
sequenceDiagram
  participant W as Delivery register
  participant E as Entitlements
  participant C as Consuming application
  participant S as Staff
  participant P as Platform audit
  W->>E: grant obligation for a line
  E->>E: grant from the frozen specification
  C->>E: draw (consumption function, its transaction)
  S->>E: restore, grant or revoke (reason)
  E->>P: audit event after commit
  E->>E: expiry sweep
```

## When Something Fails

Invalid frozen specifications permanently fail grant delivery because another attempt cannot change them. Consumption refusal is atomic with the caller's transaction. Interventions retain local accountability but the default audit transport writes no durable Platform record.

## Open Design Questions

The staff setup surface and live entitlement tab remain absent. Submission consumption must be integrated by its owning application.