--- id: SVC-PFM-TNL-crm-tenant-lifecycle title: CRM Lifecycle Participants product_area: platform module: tenant-lifecycle repository: services-crm source_module: modules/tenant-lifecycle revision: 1 status: draft design_intent: confirmed origin: services-platform:docs/tenants/tenant-lifecycle-plan.md#§6.1 Registration (approved 2026-10-09); services-platform:docs/data-jobs/tenant-reset.md#§3 The contract for a macroservice that holds a tenant's records implementation_evidence: observed inference: [] source_sha: services-crm: a8d1364f1dd44b723bb5f9acba12f983e9ec8d69 services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 owns: [] does_not_own: - Platform’s orchestration plan, integration switch and recorded workflow accounting. - System-owned workspace lifecycle facts. - Business record ownership, which remains with the application’s domain modules. operations: - operation_id: describe route: lifecycle function crm_tenant_lifecycle operation describe intent: Return participant declarations and the operations the application supports. access: internal permission: 'none: invoked by Platform''s lifecycle jobs through an IAM invoke grant; no person calls it' realises: - CAP-PFM-TNL-007 published_to_submissions: 'not published: internal lifecycle or deployment work is not configurable intake.' provenance: observed source: services-crm:modules/tenant-lifecycle/services/lifecycle/tenant-lifecycle-operations.ts:TENANT_LIFECYCLE_OPERATIONS - operation_id: provision route: lifecycle function crm_tenant_lifecycle operation provision intent: Apply the selected participant’s starter defaults through its construction implementation. access: internal permission: 'none: invoked by Platform''s lifecycle jobs through an IAM invoke grant; no person calls it' realises: - CAP-PFM-TNL-002 - CAP-PFM-TNL-008 published_to_submissions: 'not published: internal lifecycle or deployment work is not configurable intake.' provenance: observed source: services-crm:modules/tenant-lifecycle/services/lifecycle/tenant-lifecycle-operations.ts:TENANT_LIFECYCLE_OPERATIONS - operation_id: verifyProvisioned route: lifecycle function crm_tenant_lifecycle operation verifyProvisioned intent: Report readiness and the requirements the selected participant finds missing. access: internal permission: 'none: invoked by Platform''s lifecycle jobs through an IAM invoke grant; no person calls it' realises: - CAP-PFM-TNL-002 - CAP-PFM-TNL-008 published_to_submissions: 'not published: internal lifecycle or deployment work is not configurable intake.' provenance: observed source: services-crm:modules/tenant-lifecycle/services/lifecycle/tenant-lifecycle-operations.ts:TENANT_LIFECYCLE_OPERATIONS - operation_id: purge route: lifecycle function crm_tenant_lifecycle operation purge intent: Remove a bounded batch of declared participant resources and return progress. access: internal permission: 'none: invoked by Platform''s lifecycle jobs through an IAM invoke grant; no person calls it' realises: - CAP-PFM-TNL-017 published_to_submissions: 'not published: internal lifecycle or deployment work is not configurable intake.' provenance: observed source: services-crm:modules/tenant-lifecycle/services/lifecycle/tenant-lifecycle-operations.ts:TENANT_LIFECYCLE_OPERATIONS - operation_id: inventory route: lifecycle function crm_tenant_lifecycle operation inventory intent: Count the selected participant’s remaining declared resources. access: internal permission: 'none: invoked by Platform''s lifecycle jobs through an IAM invoke grant; no person calls it' realises: - CAP-PFM-TNL-017 published_to_submissions: 'not published: internal lifecycle or deployment work is not configurable intake.' provenance: observed source: services-crm:modules/tenant-lifecycle/services/lifecycle/tenant-lifecycle-operations.ts:TENANT_LIFECYCLE_OPERATIONS - operation_id: reset route: lifecycle function crm_tenant_lifecycle operation reset intent: Run the selected participant’s initial-load removal behavior. access: internal permission: 'none: invoked by Platform''s lifecycle jobs through an IAM invoke grant; no person calls it' realises: - CAP-PFM-TNL-012 published_to_submissions: 'not published: internal lifecycle or deployment work is not configurable intake.' provenance: observed source: services-crm:modules/tenant-lifecycle/services/lifecycle/tenant-lifecycle-operations.ts:TENANT_LIFECYCLE_OPERATIONS - operation_id: export route: lifecycle function crm_tenant_lifecycle operation export intent: Write the next batch of a declared export dataset and return its part and continuation. access: internal permission: 'none: invoked by Platform''s lifecycle jobs through an IAM invoke grant; no person calls it' realises: - CAP-PFM-TNL-010 published_to_submissions: 'not published: internal lifecycle or deployment work is not configurable intake.' provenance: observed source: services-crm:modules/tenant-lifecycle/services/lifecycle/tenant-lifecycle-operations.ts:TENANT_LIFECYCLE_OPERATIONS - operation_id: reconcileBaseline route: deployment custom resource (BaselineReconciliationRun) invoking crm_tenant_lifecycle intent: Apply missing baseline seed sets across the eligible existing workspaces. access: internal permission: 'none: invoked by CloudFormation during CRM''s own deployment' realises: - CAP-PFM-TNL-009 - CAP-PFM-TNL-008 published_to_submissions: 'not published: internal lifecycle or deployment work is not configurable intake.' provenance: observed source: services-crm:modules/tenant-lifecycle/services/lifecycle/baseline-reconciliation.ts:baselineReconciliationResponse events: [] jobs: - name: crm_tenant_lifecycle kind: Lambda function, reserved concurrency 1, four-minute timeout trigger: Invoked by the declared lifecycle caller or deployment hook; enablement and recovery limits are stated below. notes: The caller controls batch iteration; reconciliation covers active, loading and failed-provisioning workspaces. - name: BaselineReconciliationRun kind: CloudFormation custom resource trigger: Invoked by the declared lifecycle caller or deployment hook; enablement and recovery limits are stated below. notes: The caller controls batch iteration; reconciliation covers active, loading and failed-provisioning workspaces. integrations: - system: Platform workspace lifecycle jobs direction: inbound contract: A synchronous invocation selects the operation and participant and supplies workspace, run and batching context as required by that operation. - system: AWS CloudFormation direction: inbound contract: A synchronous invocation selects the operation and participant and supplies workspace, run and batching context as required by that operation. - system: Workspace export staging bucket direction: outbound contract: Export writes a staged dataset part and returns metadata for the coordinator. consistency: - rule: A removal batch commits within its workspace before the invocation returns. kind: transactional compensation: Retry continues removal; completed batches are retained. - rule: Repeated removal works toward empty declared resources; provisioning repeats follow participant-specific behavior. kind: eventual compensation: Recovery retries forward without undoing earlier batches. - rule: Each default and its seed entry are committed together. kind: transactional compensation: The transaction either retains both or neither. - rule: Purge and reset disable change capture within their removal transactions. kind: transactional compensation: No downstream change event is generated for those removals. - rule: Reconciliation continues after individual workspace failures and reports them together. kind: eventual compensation: A later deployment can retry missing defaults. evidence: - 'services-crm at a8d1364f: modules/tenant-lifecycle/services/lifecycle/{tenant-lifecycle-operations, baseline-reconciliation, tenant-availability}.ts; services/participants/*.ts; services/persistence/*.ts; services/export/*.ts; aws/logic/tenant-lifecycle.lambda.ts; db/tenant-seed-applications.table.ts; db/platform/tenants.ts.' 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-CHG-007, 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-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-VEN-001, TC-VEN-002, TC-VEN-003] --- # CRM Lifecycle Participants ## What This Service Is For CRM prepares its starter configuration, removes declared CRM resources, resets imported records and exports declared datasets. Deployment reconciliation also applies missing defaults to eligible existing workspaces. ## Boundary CRM owns its seven participants, ledger and reconciliation implementation; its business modules retain their records. Platform chooses when to invoke participants and in what order. CRM reads workspace lifecycle facts for its local availability gate and does not own those facts. ## Operations in Words Description publishes each participant’s resources, dependencies, seed sets and supported operations. Provisioning applies ledgered defaults, and readiness reports missing requirements. Purge and reset process bounded batches within the selected workspace, with guarded functions for protected histories. Reset preserves or reapplies configuration according to each participant’s classification. Export validates its request and writes one declared dataset batch. Reconciliation invokes initialization for enabled participants with seed sets across active, loading and failed-provisioning workspaces, including disabled ones. ## Events and Jobs The interface declares no business events, and removal transactions suppress change capture. Platform drives lifecycle calls through the function. A deployment custom resource requests baseline reconciliation after the release’s migrations and function update; unchanged resource properties do not cause another run. ## Consistency Guarantees Default records and seed ledger entries commit together. Each removal batch commits separately from Platform’s progress accounting, so recovery continues forward rather than rolling back completed batches. Reconciliation collects workspace failures while continuing with other workspaces and then reports failure to deployment. Applied defaults remain after stack rollback.