Rhythm 2.0 Specifications

Appearance

CAP-COM-ORD-013Provide purchased rights and account for their use

Markdown

CAP-COM-ORD-013

Provide purchased rights and account for their use

Markdown
  • DocumentDraft
  • Product intentProposed
  • ImplementationObserved

Planning

Feature
FEAT-COM-ORD-05
Key concepts
CON-COM-ORD-004
Actors
ACT-COM-016, ACT-COM-015, ACT-COM-017, ACT-COM-018
Depends on
CAP-COM-ORD-012
Related
CAP-COM-ORD-014
Proved by
ATS-COM-ORD-013

KindCapabilityProduct areaCommerceModuleCustomer purchases, purchased benefits and vendor stockRevision1

Read atservices-commerce c8b66a98react-console baf6dae3

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.

The Formal Contract

The narrative above explains; the sections below are authoritative — the rules, scenarios and tests this document binds.

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.
Surfaces
consoleportalapijob
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)

Controls

37 controls apply, from the corpus control catalogue.

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

Permissions

KeyChecked atScope
commerce.entitlements.readapitenant
commerce.entitlements.restoreapitenant
commerce.entitlements.grantapitenant
commerce.entitlements.revokeapitenant

Business Rules

13 rules, 11 to be proved before approval. A rule's product intent is derived from its origin: 0 confirmed by a product decision, the rest inheriting this capability's proposed.

IdRuleKindEnforced atProvenance
01must prove
Proposed
Commerce fulfils a grant obligation from the specification frozen in the purchased details, independently of later product configuration.
no proof recorded yet
lifecycleservicetest
services-commerce:modules/entitlements/tests/e2e/entitlements.e2e.spec.js#delivered the obligation to the register: completed, with the grant as its record
02must prove
Proposed
An order line grants its specified quantity once per entitlement kind, so buying three copies with a two-download grant still provides two uses.
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)
no proof recorded yet
calculationservicetest
services-commerce:modules/entitlements/tests/e2e/entitlements.e2e.spec.js#grants ONE download right of two uses for the three copies, not six
03must prove
Proposed
The specification assigns the holder to the item recipient with buyer fallback, or explicitly to the buyer.
no proof recorded yet
calculationservicetest
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
04must prove
Proposed
A grant obligation with a missing or unreadable specification fails permanently and raises an operational exception.
no proof recorded yet
validationservicetest
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
05must prove
Proposed
Consumption counts once per request reference, refuses exhausted quantities and prevents use of inactive or expired rights.
no proof recorded yet
invariantservice, databasetest
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
06must prove
Proposed
An authorized restoration records its reason and audit history, replays under the original request key and refuses a second restoration under a new key.
no proof recorded yet
lifecycleapi, servicetest
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
07must prove
Proposed
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.
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)
no proof recorded yet
permissionapi, servicetest
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
08must prove
Proposed
Cancellation ends every active grant on the line without erasing past consumption, and retrying that revocation makes no further change.
no proof recorded yet
lifecycleservicetest
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
09must prove
Proposed
Expiry sweeps mark rights expired after their validity window, while consumption independently checks that window before drawing.
no proof recorded yet
lifecycleservice, databasetest
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
10must prove
Proposed
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.
no proof recorded yet
permissionapi, servicetest
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
11
Proposed
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.
invariantdatabaseobserved
services-commerce:modules/entitlements/db/entitlements.table.ts:ENTITLEMENT_KINDS
12must prove
Proposed
The read-only eligibility view exposes active rights and stops exposing a revoked right immediately.
no proof recorded yet
policydatabasetest
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
13
Proposed
Grant setup has no console screen, although Order 360 can display grants associated with its purchases.
policyconsoledocumented
services-commerce:docs/milestones/plans/COMM-M2-plan.md#2. Scope

Scenarios

IdGivenWhenThenProvenance
01A member’s e-book right permits two downloads.They consume both uses and staff restore one with a reason.Exactly one further download becomes available and the restoration is retained in order history.test
services-commerce:modules/entitlements/tests/e2e/entitlements.e2e.spec.js#lets the member download once more, and no more

The Markdown files under specs/ in rhythmsoftware/rhythm-v2-docs are the canonical source of truth. This reader is a generated, read-only projection of them.

Rhythm Software