--- id: CAP-COM-ORD-013 title: Provide purchased rights and account for their use feature: FEAT-COM-ORD-05 product_area: commerce module: orders revision: 1 status: draft product_intent: proposed implementation_evidence: observed supersedes: - CAP-COM-CAT-012 - CAP-COM-CAT-013 - CAP-COM-CAT-014 - CAP-COM-CAT-015 - CAP-COM-CAT-016 - CAP-COM-CAT-017 - CAP-COM-CAT-018 - CAP-COM-CAT-019 - CAP-COM-CAT-033 source_sha: services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b react-console: baf6dae382d6f41dce976c7f848667ccc37e076f intent_sources: - >- services-commerce:docs/migrations/entitlements/README.md#D-E-14. The download limit is per grant, whatever the copies bought (supersedes D-E-04) - >- services-commerce:docs/migrations/entitlements/README.md#D-E-15. A manual grant and a staff revoke are routes, each an audited, sensitive intervention (supersedes D-E-13) purpose: 'Purchased or manually issued rights remain visible with their holder, validity and consumption history.' outcomes: - Purchased download rights permit the specified uses and stop further consumption when exhausted. - Staff corrections and manual rights retain their reasons and audit attribution. concepts: - CON-COM-ORD-004 actors: - ACT-COM-016 - ACT-COM-015 - ACT-COM-017 - ACT-COM-018 surfaces: - console - portal - api - job preconditions: [] postconditions: [] permissions: - key: commerce.entitlements.read where_checked: api scope: tenant - key: commerce.entitlements.restore where_checked: api scope: tenant - key: commerce.entitlements.grant where_checked: api scope: tenant - key: commerce.entitlements.revoke where_checked: api scope: tenant rules: - id: BR-CAP-COM-ORD-013-01 proved_by: [ATS-COM-ORD-001-20, ATS-COM-ORD-012-15, ATS-COM-ORD-013-01, ATS-COM-ORD-013-15, ATS-COM-ORD-014-19, TST-COM-ORD-061] statement: >- Commerce fulfils a grant obligation from the specification frozen in the purchased details, independently of later product configuration. kind: lifecycle enforced_at: - service must_prove: true 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 origin: none - id: BR-CAP-COM-ORD-013-02 proved_by: [ATS-COM-ORD-013-02, TST-COM-ORD-061] statement: >- An order line grants its specified quantity once per entitlement kind, so buying three copies with a two-download grant still provides two uses. kind: calculation enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/entitlements/tests/e2e/entitlements.e2e.spec.js#grants ONE download right of two uses for the three copies, not six origin: >- services-commerce:docs/migrations/entitlements/README.md#D-E-14. The download limit is per grant, whatever the copies bought (supersedes D-E-04) - id: BR-CAP-COM-ORD-013-03 proved_by: [ATS-COM-ORD-013-03, TST-COM-ORD-071] statement: >- The specification assigns the holder to the item recipient with buyer fallback, or explicitly to the buyer. kind: calculation enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/entitlements/tests/unit/register/grant-specification.spec.js#gives the grant to the line’s recipient, to the buyer when the line names none, and to the buyer when the spec says so origin: none - id: BR-CAP-COM-ORD-013-04 proved_by: [ATS-COM-ORD-013-04, TST-COM-ORD-069] statement: >- A grant obligation with a missing or unreadable specification fails permanently and raises an operational exception. kind: validation enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/entitlements/tests/integration/services/register/grant-handler.integration.spec.js#fails the obligation of a purchase that names no specification, not retryable, with obligation_failed raised origin: none - id: BR-CAP-COM-ORD-013-05 proved_by: [ATS-COM-ORD-013-05, ATS-COM-ORD-013-12, TST-COM-ORD-061, TST-COM-ORD-066] statement: >- Consumption counts once per request reference, refuses exhausted quantities and prevents use of inactive or expired rights. kind: invariant enforced_at: - service - database must_prove: true provenance: test source: >- services-commerce:modules/entitlements/tests/e2e/entitlements.e2e.spec.js#gives the member a link and consumes one use per Idempotency-Key (the retry free), then refuses the third 409 insufficient_entitlement origin: none - id: BR-CAP-COM-ORD-013-06 proved_by: [ATS-COM-ORD-013-06, TST-COM-ORD-061] statement: >- An authorized restoration records its reason and audit history, replays under the original request key and refuses a second restoration under a new key. kind: lifecycle enforced_at: - api - service must_prove: true 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 origin: none - id: BR-CAP-COM-ORD-013-07 proved_by: [ATS-COM-ORD-013-07, TST-COM-ORD-064] statement: >- Staff can issue manual grants or revoke active rights with recorded reasons and sensitive audit controls, preserving consumed quantities and rejecting repeat revocation or an invalid validity window. kind: permission enforced_at: - api - service must_prove: true provenance: test source: >- services-commerce:modules/entitlements/tests/integration/services/entitlements/entitlement-interventions.integration.spec.js#writes a manual grant with no order, line or obligation, the window stated, the reason in its notes origin: >- services-commerce:docs/migrations/entitlements/README.md#D-E-15. A manual grant and a staff revoke are routes, each an audited, sensitive intervention (supersedes D-E-13) - id: BR-CAP-COM-ORD-013-08 proved_by: [ATS-COM-ORD-013-08, ATS-COM-ORD-013-14, ATS-COM-ORD-014-17, TST-COM-ORD-061] statement: >- Cancellation ends every active grant on the line without erasing past consumption, and retrying that revocation makes no further change. kind: lifecycle enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/entitlements/tests/e2e/entitlements.e2e.spec.js#revokes the line’s grant with the reason, refuses the download 409 entitlement_not_active, and writes the history origin: none - id: BR-CAP-COM-ORD-013-09 proved_by: [ATS-COM-ORD-013-09, ATS-COM-ORD-013-13, TST-COM-ORD-066, TST-COM-ORD-068] statement: >- Expiry sweeps mark rights expired after their validity window, while consumption independently checks that window before drawing. kind: lifecycle enforced_at: - service - database must_prove: true provenance: test source: >- services-commerce:modules/entitlements/tests/integration/services/register/entitlement-sweeper.integration.spec.js#expires the lapsed grants of both tenants, oldest expiry first, and counts what it did origin: none - id: BR-CAP-COM-ORD-013-10 proved_by: [ATS-COM-ORD-013-10, TST-COM-ORD-061] statement: >- Staff readers can inspect any holder’s or order’s rights, but portal readers are limited to their linked contact and cannot restore, manually grant or revoke them. kind: permission enforced_at: - api - service must_prove: true provenance: test source: >- services-commerce:modules/entitlements/tests/e2e/entitlements.e2e.spec.js#lets a console reader read the member’s grants by holder and by order, and refuses them the restore origin: none - id: BR-CAP-COM-ORD-013-11 proved_by: [] statement: >- Rights use download, registration inclusion, submission requirement or access kinds and can belong to a contact or organization, originating in fulfilment or a manual grant. kind: invariant enforced_at: - database must_prove: false provenance: observed source: 'services-commerce:modules/entitlements/db/entitlements.table.ts:ENTITLEMENT_KINDS' origin: none - id: BR-CAP-COM-ORD-013-12 proved_by: [ATS-COM-ORD-013-11, TST-COM-ORD-064] statement: The read-only eligibility view exposes active rights and stops exposing a revoked right immediately. kind: policy enforced_at: - database must_prove: true provenance: test source: >- services-commerce:modules/entitlements/tests/integration/services/entitlements/entitlement-interventions.integration.spec.js#takes it out of the Eligibility view and the consume function at once origin: none - id: BR-CAP-COM-ORD-013-13 proved_by: [] statement: 'Grant setup has no console screen, although Order 360 can display grants associated with its purchases.' kind: policy enforced_at: - console must_prove: false provenance: documented source: 'services-commerce:docs/milestones/plans/COMM-M2-plan.md#2. Scope' origin: none note: Finding 026 records the missing grant-configuration screen. scenarios: - id: SC-CAP-COM-ORD-013-01 given: A member’s e-book right permits two downloads. when: They consume both uses and staff restore one with a reason. then: Exactly one further download becomes available and the restoration is retained in order history. provenance: test source: >- services-commerce:modules/entitlements/tests/e2e/entitlements.e2e.spec.js#lets the member download once more, and no more edge_cases: [] constraints: [] depends_on: - CAP-COM-ORD-012 related: - CAP-COM-ORD-014 journeys: [] open_questions: [] evidence: - >- Examined reference: services-commerce:docs/migrations/entitlements/README.md#D-E-14. The download limit is per grant, whatever the copies bought (supersedes D-E-04) - >- Examined reference: services-commerce:docs/migrations/entitlements/README.md#D-E-15. A manual grant and a staff revoke are routes, each an audited, sensitive intervention (supersedes D-E-13) - 'Examined reference: services-commerce:docs/milestones/plans/COMM-M2-plan.md#2. Scope' - 'Examined reference: services-commerce:modules/entitlements/db/entitlements.table.ts:ENTITLEMENT_KINDS' - >- Examined reference: services-commerce:modules/entitlements/tests/e2e/entitlements.e2e.spec.js#delivered the obligation to the register: completed, with the grant as its record - >- Examined reference: services-commerce:modules/entitlements/tests/e2e/entitlements.e2e.spec.js#gives the member a link and consumes one use per Idempotency-Key (the retry free), then refuses the third 409 insufficient_entitlement - >- Examined reference: services-commerce:modules/entitlements/tests/e2e/entitlements.e2e.spec.js#grants ONE download right of two uses for the three copies, not six - >- Examined reference: services-commerce:modules/entitlements/tests/e2e/entitlements.e2e.spec.js#lets a console reader read the member’s grants by holder and by order, and refuses them the restore - >- Examined reference: services-commerce:modules/entitlements/tests/e2e/entitlements.e2e.spec.js#lets the member download once more, and no more - >- Examined reference: 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 - >- Examined reference: services-commerce:modules/entitlements/tests/e2e/entitlements.e2e.spec.js#revokes the line’s grant with the reason, refuses the download 409 entitlement_not_active, and writes the history - >- Examined reference: services-commerce:modules/entitlements/tests/integration/services/entitlements/entitlement-interventions.integration.spec.js#takes it out of the Eligibility view and the consume function at once - >- Examined reference: services-commerce:modules/entitlements/tests/integration/services/entitlements/entitlement-interventions.integration.spec.js#writes a manual grant with no order, line or obligation, the window stated, the reason in its notes - >- Examined reference: services-commerce:modules/entitlements/tests/integration/services/register/entitlement-sweeper.integration.spec.js#expires the lapsed grants of both tenants, oldest expiry first, and counts what it did - >- Examined reference: services-commerce:modules/entitlements/tests/integration/services/register/grant-handler.integration.spec.js#fails the obligation of a purchase that names no specification, not retryable, with obligation_failed raised - >- Examined reference: services-commerce:modules/entitlements/tests/unit/register/grant-specification.spec.js#gives the grant to the line’s recipient, to the buyer when the line names none, and to the buyer when the spec says so 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-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-CHG-001, TC-CHG-002, TC-CHG-003, TC-CHG-004, TC-CHG-007, 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] exercised_by: [FAS-COM-ORD-04-02, FAS-COM-ORD-05-01, FAS-COM-ORD-05-02, FAS-COM-ORD-05-03, FAS-COM-ORD-05-04, FAS-COM-ORD-05-05] suites: [TST-COM-ORD-061, TST-COM-ORD-064, TST-COM-ORD-066, TST-COM-ORD-068, TST-COM-ORD-069, TST-COM-ORD-071] --- # Provide purchased rights and account for their use ## Purpose Purchased or manually issued rights remain visible with their holder, validity and consumption history. Staff can resolve problems without losing the evidence of earlier use. ## How It Works The purchase carries a frozen specification for any right it grants. Commerce processes that specification when the grant obligation is fulfilled. A holder can then consume available uses within the applicable validity window. Failed consumption explains why the right cannot be used. Authorized staff can restore a use, issue a manual grant or revoke a right with a reason. The audit history preserves these interventions alongside the recorded quantity used. ## Relationships Applications freeze grant details, the fulfilment register invokes the grant handler, and cancellation ends the affected rights.