Rhythm 2.0 Specifications

Appearance

CAP-PFM-OPS-012Derive application licences from commercial contracts

Markdown

CAP-PFM-OPS-012

Derive application licences from commercial contracts

Markdown
  • DocumentDraft
  • Product intentConfirmed
  • ImplementationPartially observed

Planning

Feature
FEAT-PFM-OPS-03
Exercised by
FAS-PFM-OPS-03-01, FAS-PFM-OPS-03-03, FAS-PFM-OPS-03-04, FAS-PFM-OPS-03-05
Key concepts
CON-PFM-OPS-003
Actors
ACT-PFM-043, ACT-PFM-006, ACT-PFM-004, ACT-PFM-005
Journeys
JNY-PFM-OPS-005
Related
CAP-PFM-OPS-011, CAP-PFM-OPS-014, CAP-PFM-SEC-002
Proved by
ATS-PFM-OPS-012

Implementation

Executable suites
TST-PFM-OPS-080, TST-PFM-OPS-106, TST-PFM-OPS-108, TST-PFM-OPS-116

KindCapabilityProduct areaPlatformModuleOperational RecordsRevision1

Read atservices-platform ad3f6a65

Derive application licences from commercial contracts ​

Purpose ​

Use commercial contract terms to maintain the application licences shared by a customer’s workspaces.

How It Works ​

The synchronization flow reads a company’s contracts and associated lines from HubSpot. The resolver interprets active terms and expands mapped products into application windows. Adjacent renewals combine while actual gaps remain visible. A complete read replaces the stored commercial copy and derived windows together. A provider failure preserves the prior copy and records synchronization health. That preservation does not extend a contract beyond its already known expiry and grace dates. Verified notifications and nightly work arrange future reads, while a staff operation can request a direct sync. Queue recovery distinguishes recorded provider failures from thrown processing failures. Contract sync does not prepare missing application state, leaving an accepted automatic-enablement gap. The pinned documentation reports that live configuration and property confirmation are still pending.

Relationships ​

Licence decisions feed availability alongside operational state; security applies the resulting access decision and the console explains it.

The Formal Contract

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

Outcomes
Eligible commercial terms resolve to application coverage windows.Provider failure preserves the last commercial copy without extending its known expiry.
Surfaces
apijob
Preconditions
The workspace has a commercial company link and the deployment has a configured provider token.
Postconditions
A completed read replaces the derived commercial windows, while an unsuccessful provider read preserves them.
Constraints
HubSpot is a read-only commercial source, and the documented activation still requires property confirmation.
Intent sources
services-platform:docs/proposals/application-access-and-entitlements.md#10.1 Decided by Andrew on 2026-10-11 (D2, D3, D4)services-platform:docs/proposals/application-access-and-entitlements.md#10.1 (product list confirmed, 2026-10-12)

Controls

48 controls apply, from the corpus control catalogue.

TC-AVL-001 TC-AVL-004 TC-AVL-005 TC-AZ-001 TC-AZ-002 TC-AZ-003 TC-AZ-004 TC-AZ-005 TC-CHG-001 TC-CHG-002 TC-CHG-003 TC-CHG-004 TC-CHG-005 TC-CHG-006 TC-CRY-001 TC-CRY-002 TC-CRY-003 TC-CRY-004 TC-DAT-001 TC-DAT-002 TC-DAT-003 TC-DAT-004 TC-IAM-001 TC-IAM-002 TC-IAM-003 TC-IAM-004 TC-IAM-005 TC-IAM-006 TC-LOG-001 TC-LOG-004 TC-LOG-005 TC-MON-001 TC-MON-002 TC-PI-001 TC-PI-002 TC-PI-004 TC-PI-005 TC-SEC-001 TC-SEC-002 TC-SEC-003 TC-SEC-004 TC-TEN-001 TC-TEN-002 TC-TEN-003 TC-TEN-004 TC-VEN-001 TC-VEN-002 TC-VEN-003

Permissions

KeyChecked atScope
hq.licensing.readapiglobal
hq.licensing.manageapiglobal

Business Rules

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

IdRuleKindEnforced atProvenance
01must prove
Confirmed
Only in-force contracts produce licences; known inactive statuses produce none, and unfamiliar statuses are flagged without granting access.
origin: services-platform:docs/proposals/application-access-and-entitlements.md#D2
proved by ATS-PFM-OPS-012-01, TST-PFM-OPS-116
calculationservicetest
services-platform:modules/licensing/tests/unit/licences/resolve-licence-windows.spec.ts#resolves nothing for a status it has never heard of, and flags it so the vocabulary can be confirmed
02must prove
Confirmed
A contract with unreadable term dates produces no licence and a flag, while an automatic-renewal contract may have an open-ended term.
proved by ATS-PFM-OPS-012-02, TST-PFM-OPS-116
calculationservicetest
services-platform:modules/licensing/tests/unit/licences/resolve-licence-windows.spec.ts#licenses nothing and is flagged when it has no end date and does not renew automatically
03must prove
Confirmed
Each line-item term boundary independently uses its own date when supplied and otherwise inherits the corresponding contract date.
proved by ATS-PFM-OPS-012-03, TST-PFM-OPS-116
calculationservicetest
services-platform:modules/licensing/tests/unit/licences/resolve-licence-windows.spec.ts#takes each date independently, so a line may override one and inherit the other
04must prove
Confirmed
The code-held product map expands recognized products into grants, flags unmapped products and grants no applications for integration, payment, service or licence-only products.
origin: services-platform:docs/proposals/application-access-and-entitlements.md#D4
proved by ATS-PFM-OPS-012-04, TST-PFM-OPS-116
calculationservicetest
services-platform:modules/licensing/tests/unit/licences/resolve-licence-windows.spec.ts#licenses nothing and flags the SKU when the map does not cover it
05must prove
Confirmed
Overlapping and adjacent terms for an application combine into one licence window, while genuinely separated terms remain distinct.
proved by ATS-PFM-OPS-012-05, TST-PFM-OPS-116
calculationservicetest
services-platform:modules/licensing/tests/unit/licences/resolve-licence-windows.spec.ts#leaves a real gap between two terms as two windows, because the licence did lapse
06must prove
Confirmed
Finite licence windows receive seven calendar days of grace, and open-ended windows have no grace end.
origin: services-platform:docs/proposals/application-access-and-entitlements.md#D3
proved by ATS-PFM-OPS-012-06, TST-PFM-OPS-116
calculationservicetest
services-platform:modules/licensing/tests/unit/licences/resolve-licence-windows.spec.ts#is the seven days after the end date that decision D3 settled on
07must prove
Confirmed
The product should notify workspace administrators beginning sixty days before a contract ends; this accepted notice behavior is absent.
origin: services-platform:docs/proposals/application-access-and-entitlements.md#D3
proved by ATS-PFM-OPS-012-07
policyserviceunknown
FND-PFM-OPS-012
08must prove
Confirmed
A complete company read replaces contracts, lines and licence windows transactionally and records success; provider failure preserves the prior commercial snapshot and records a redacted error.
proved by ATS-PFM-OPS-012-08, ATS-PFM-OPS-012-14, ATS-PFM-OPS-012-15, ATS-PFM-OPS-013-08, ATS-PFM-OPS-014-09, TST-PFM-OPS-108
policyservicetest
services-platform:modules/licensing/tests/integration/services/sync/sync-company-licences.integration.spec.js#changes no snapshot, no window and no last success
09must prove
Confirmed
A missing HubSpot token records an unconfigured outcome without changing existing licences or raising a provider-failure alarm.
proved by ATS-PFM-OPS-012-09, TST-PFM-OPS-108
policyservicetest
services-platform:modules/licensing/tests/integration/services/sync/sync-company-licences.integration.spec.js#leaves the licences of a company synced before the key was removed exactly as they were
10must prove
Confirmed
Changed licence windows request one post-commit authorization flush, whether access increases or decreases, while identical windows request none.
proved by ATS-PFM-OPS-012-10, TST-PFM-OPS-108
policyservicetest
services-platform:modules/licensing/tests/integration/services/sync/sync-company-licences.integration.spec.js#changes nothing and asks for no second flush when the read is the same as the last
11
Confirmed
Nightly reconciliation, verified HubSpot notifications, manual staff sync and workspace company-link changes feed the shared company-sync operation.
policyservicedocumented
services-platform:docs/licensing.md#12. The operating story
12must prove
Confirmed
Webhook acceptance requires a signature for the exact request body and address within the replay window, and missing secret configuration refuses delivery without revealing verification detail.
proved by ATS-PFM-OPS-012-11, TST-PFM-OPS-080
validationapitest
services-platform:modules/licensing/tests/e2e/hubspot-licensing.e2e.spec.js#refuses a delivery signed for a different URI, so a signature cannot be replayed at another route
13
Confirmed
Verified deliveries deduplicate company sync requests and resolve contract owners from the stored snapshot, leaving unknown contracts and unsupported events for nightly reconciliation.
policyservicetest
services-platform:modules/licensing/tests/integration/services/sync/accept-webhook-delivery.integration.spec.js#reports an event about a contract it has never seen as unresolved, for the nightly pass to pick up
14must prove
Confirmed
Staff licensing readers can inspect company commercial copies and synchronization health, while company synchronization requires management authority and customer callers are refused.
proved by ATS-PFM-OPS-012-12, ATS-PFM-OPS-012-16, TST-PFM-OPS-080
permissionapitest
services-platform:modules/licensing/tests/e2e/hubspot-licensing.e2e.spec.js#refuses a staff member holding only hq.licensing.read on the sync, with 403
15
Confirmed
Workspace deletion retains company-level commercial copies and licence windows shared by production and sandbox workspaces.
proved by ATS-PFM-OPS-012-19
policyserviceobserved
services-platform:modules/licensing/services/maintenance/tenant-participant.ts
16must prove
Confirmed
The sync worker acknowledges malformed input and recorded provider outcomes, reserving queue redelivery for thrown processing failures.
proved by ATS-PFM-OPS-012-17
policyserviceobserved
services-platform:modules/licensing/aws/lambda/LICENCE_SYNC.handler.ts:processLicenceSyncBatch
17must prove
Confirmed
Webhook processing acknowledges failed queue publication, reports refused companies and relies on later reconciliation for recovery.
proved by ATS-PFM-OPS-012-18, TST-PFM-OPS-106
policyserviceobserved
services-platform:modules/licensing/services/sync/accept-webhook-delivery.ts:acceptWebhookDelivery
18must prove
Confirmed
The sync queue allows five receives before dead-lettering, with four-day source retention and fourteen-day dead-letter retention.
no proof recorded yet
lifecycleserviceobserved
services-platform:modules/licensing/aws/resources/licence-sync.sqs.ts:createLicenceSyncQueue
19must prove
Confirmed
Contract sync replaces commercial copies and licence windows without initializing a newly licensed application’s missing operational state.
no proof recorded yet
lifecycleserviceobserved
services-platform:modules/licensing/services/sync/sync-company-licences.ts:syncCompanyLicences

Scenarios

IdGivenWhenThenProvenance
01A renewal begins immediately after the earlier term ends.The company’s commercial snapshot is synchronized.The resolver produces a continuous window through the renewal’s final day.inferred
services-platform:modules/licensing/tests/integration/services/sync/sync-company-licences.integration.spec.js#extends the licence to the end of the new term, as one window
02HubSpot cannot complete a company contract read.Synchronization records the provider failure.The previous commercial snapshot remains and health records the redacted explanation.inferred
services-platform:modules/licensing/tests/integration/services/sync/sync-company-licences.integration.spec.js#records the reason, so an operator can see why the licences have stopped being refreshed

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