--- id: SVC-PFM-OPS-licensing title: Licensing and Application Standing product_area: platform module: operations repository: services-platform source_module: modules/licensing revision: 1 status: draft design_intent: confirmed origin: >- services-platform:docs/proposals/application-access-and-entitlements.md#Status (built and accepted by Andrew 2026-10-15) implementation_evidence: observed source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f owns: - DOM-PFM-OPS-003 - DOM-PFM-OPS-004 does_not_own: - 'Security owns workspace identity, classification and commercial-company linkage.' - >- Security owns request authority, security history and cache-refresh execution; Licensing supplies availability inputs. - Application owners implement their workspace preparation participants. - The export owner administers and consumes allowances stored by Licensing. inference: [] operations: - operation_id: getLicensingHealth intent: Return technical build health for the licensing function. access: public permission: none realises: [] published_to_submissions: 'not published: a technical health route' - operation_id: getTenantLicensing intent: >- Return each workspace application’s licence, readiness, availability and full override history to authorized staff. access: internal permission: hq.licensing.read realises: - CAP-PFM-OPS-013 published_to_submissions: 'not published: a staff-only Rhythm HQ operation, never configurable intake' - operation_id: getHubspotCompanyLicensing intent: >- Return the stored company contracts, lines, windows, resolution diagnostics, linked workspaces and read health. access: internal permission: hq.licensing.read realises: - CAP-PFM-OPS-012 - CAP-PFM-OPS-013 published_to_submissions: 'not published: a staff-only Rhythm HQ operation, never configurable intake' - operation_id: syncHubspotCompanyLicensing intent: Run one complete company read synchronously and return its recorded outcome. access: internal permission: hq.licensing.manage realises: - CAP-PFM-OPS-012 published_to_submissions: 'not published: a staff-only Rhythm HQ operation, never configurable intake' - operation_id: getLicenceSyncHealth intent: >- Return provider configuration and linked-company synchronization health, including missing or unclaimed copies. access: internal permission: hq.licensing.read realises: - CAP-PFM-OPS-012 published_to_submissions: 'not published: a staff-only Rhythm HQ operation, never configurable intake' - operation_id: createTenantLicenceOverride intent: >- Create a reasoned application grant or withhold and prepare a missing operational application for a grant. access: internal permission: hq.licensing.manage realises: - CAP-PFM-OPS-011 - CAP-PFM-OPS-015 published_to_submissions: 'not published: a staff-only Rhythm HQ operation, never configurable intake' - operation_id: revokeTenantLicenceOverride intent: Withdraw the named override while retaining its historical decision. access: internal permission: hq.licensing.manage realises: - CAP-PFM-OPS-011 published_to_submissions: 'not published: a staff-only Rhythm HQ operation, never configurable intake' - operation_id: suspendTenantApplication intent: 'Record a reasoned suspension of an enabled application, retaining prepared data.' access: internal permission: hq.licensing.manage realises: - CAP-PFM-OPS-015 published_to_submissions: 'not published: a staff-only Rhythm HQ operation, never configurable intake' - operation_id: resumeTenantApplication intent: Return a suspended application to enabled operation. access: internal permission: hq.licensing.manage realises: - CAP-PFM-OPS-015 published_to_submissions: 'not published: a staff-only Rhythm HQ operation, never configurable intake' - operation_id: retryTenantApplicationProvisioning intent: Repeat preparation for an application whose operational state records preparation failure. access: internal permission: hq.licensing.manage realises: - CAP-PFM-OPS-015 published_to_submissions: 'not published: a staff-only Rhythm HQ operation, never configurable intake' - operation_id: receiveHubspotWebhook intent: Verify the HubSpot delivery and publish company-read requests for supported changes. access: public permission: 'none: authenticated by the HubSpot signature over the request bytes' realises: - CAP-PFM-OPS-012 published_to_submissions: 'not published: a provider notification, not intake' - operation_id: listTenantApplicationsForTenant intent: >- Return a reduced availability explanation to the workspace administrator, served through workspace routes. access: console permission: platform.tenant-applications.read realises: - CAP-PFM-OPS-016 published_to_submissions: 'not published: a read that captures no business data' events: [] jobs: - name: Licence sync consumer schedule: on each queued company does: >- Process company messages sequentially within the batch; acknowledge malformed inputs and recorded provider outcomes, and return thrown errors for redelivery. concurrency: >- Worker concurrency is bounded; five receives lead to dead-lettering, with source and dead-letter retention of four and fourteen days. - name: Nightly licence reconcile schedule: '03:10 UTC daily' does: 'When provider configuration exists, refresh product labels and publish linked-company reads.' concurrency: The nightly function reserves one invocation and monitors invocation absence. - name: Access refresh request schedule: after each licensing write that changes access does: Ask Security to invalidate cached authority after successful access-changing follow-up work. concurrency: Each request can create an independent refresh job; repeated invalidation is safe. integrations: - system: HubSpot direction: inbound contract: >- Read company, contract, line and product data; require a token for reads and a signing secret for webhook verification. - system: Security direction: outbound contract: >- Supply the availability rule; attempt security-history insertion and request cache refresh through their owning functions. - system: Workspace lifecycle participants direction: outbound contract: >- Initialize declared application participants and remove workspace overrides and application rows during purge. - system: Data exports direction: inbound contract: Expose allowance persistence to the module responsible for export decisions and execution. consistency: - rule: >- Staff decisions commit before preparation, auditing and refresh; subsequent errors do not reverse the decision. kind: eventual compensation: >- There is no rollback of a committed staff decision; history or preparation can be missing after an error. - rule: >- Successful sync commits commercial replacement with success health; provider failure changes health while retaining stored coverage. kind: transactional compensation: 'Failed replacement rolls back, while a failed provider read preserves the preceding snapshot.' - rule: Cached authority follows successful invalidation or expiry after licensing changes. kind: eventual compensation: Cache expiry is fallback when the refresh request is skipped or fails. - rule: Preparation records start and outcome in separate transactions with participant calls outside them. kind: eventual compensation: No reconciler or staff retry repairs an interrupted provisioning row. evidence: - >- services-platform at ad3f6a6: modules/licensing/aws/api/licensing.routes.ts, licensing-api-mapper.ts, licensing.schemas.ts; aws/lambda (LICENCE_SYNC, LICENCE_RECONCILE); aws/logic/licensing-sync.lambda.ts; aws/resources/licence-sync.sqs.ts; services/*; modules/tenants/aws/api/tenant-applications.routes.ts; aws/platform.service.ts (HQ_LICENSING_PERMISSIONS, TENANT_APPLICATIONS_PERMISSIONS); docs/licensing.md. - 'react-console at baf6dae: lib/hq/licensing.ts, components/console/hq/tenant-licensing-card.tsx.' - >- codex examination 2026-10-23: checked the pinned source anchors, planning references and enforcement boundaries; unresolved limits are recorded in module findings. controls: [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-AZ-006, 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-DAT-005, TC-DAT-006, TC-IAM-001, TC-IAM-002, TC-IAM-003, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-MON-002, TC-MON-003, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-PRV-001, TC-PRV-002, 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] --- # Licensing and Application Standing ## What This Service Is For Licensing supplies the commercial and operational answers behind workspace application access. Staff inspect and manage exceptions and readiness in HQ. Customer administrators receive a smaller explanation without staff or commercial details. ## Boundary The module owns catalogue records, overrides, commercial snapshots, windows, synchronization health and operational application rows. Export allowances are stored here but administered by the export owner. Security owns workspace identity and company linkage, request authority, security history and refresh jobs. Application owners supply preparation participants. ## Operations in Words Staff readers inspect workspace licensing, company snapshots and feed health. Managers create or withdraw exceptions, synchronize a company, suspend or resume application operation, and retry failed preparation. The public webhook authenticates provider hints rather than customer intake. The workspace administrative route returns reduced licensing and readiness information and checks workspace reach. Its computation belongs here; Console Shell retains a provisional contract and presentation home pending ownership reconciliation. All operations record their Submissions exclusion. ## Events and Jobs No business events are declared. The company queue and its dead-letter queue support synchronization, and the daily pass publishes linked companies when configured. Completed access-changing paths request Security’s refresh job. Provider failures returned as recorded outcomes are acknowledged rather than immediately redelivered. ## Consistency Guarantees Commercial replacement is atomic after a complete read, but simultaneous snapshots have no established ordering. Staff decisions are durable before follow-up work, leaving audit and preparation gaps on failure. The pinned guide records licence enforcement enabled and provider activation unfinished; runtime configuration is not independently established by this examination.