# Activation Flow Contracts

> **Event contracts only.** No orchestration engine in this wave.  
> ADR: [ADR-023](../architecture/adr/ADR-023.md) · [ADR-006](../architecture/adr/ADR-006.md)  
> Contract version: `activation.v1`  
> Event prefix (logical): `commercial.activation.*` / step-specific domains below

---

## 1. Pipeline (normative sequence)

```
Business Created
        ↓
Bundle Selected
        ↓
Subscription Requested
        ↓
License Requested
        ↓
Accounting Contract Requested
        ↓
Payment Activation Requested
        ↓
Workspace Initialized
        ↓
Tenant Configuration Applied
        ↓
Dashboard Generated
```

Each arrow is an **event boundary**. Consumers are idempotent. Failure at a step emits a failed/pending counterpart; no silent cross-DB writes.

---

## 2. Step contracts / events

| Step | Event name (logical) | Payload highlights | Producer (future) | Typical consumers |
| --- | --- | --- | --- | --- |
| 1 Business Created | `tenant.business.created` | `tenant_id`, `business_type_code`, `profile_ref` | Core / onboarding | Recommendation UI, CRM (opt) |
| 2 Bundle Selected | `commercial.bundle.selected` | `tenant_id`, `bundle_code`, `bundle_version_code`, `actor_id` | Core commercial | Subscription |
| 3 Subscription Requested | `commercial.subscription.requested` | `tenant_id`, `plan_code`, `pricing_item_code`, `subscription_id` | Core | License, Payment billing shell |
| 4 License Requested | `commercial.license.requested` | `tenant_id`, `subscription_id`, `license_id`, `bundle_code` | Core | Entitlement projector |
| 5 Accounting Contract Requested | `accounting.contract.requested` | `tenant_id`, `subscription_id`, `opaque_commercial_ref` | Core | Accounting |
| 6 Payment Activation Requested | `payment.activation.requested` | `tenant_id`, `license_id`, `desired_mode?`, `core_entitlement_ref` | Core | Payment workspace enable path |
| 7 Workspace Initialized | `tenant.workspace.initialized` | `tenant_id`, `workspace_template_ref` | Core / onboarding | Experience, vertical shells |
| 8 Tenant Configuration Applied | `tenant.configuration.applied` | `tenant_id`, `config_hash`, `feature_keys[]` | Core | All entitled services |
| 9 Dashboard Generated | `experience.dashboard.generated` | `tenant_id`, `dashboard_shell_ref` | Experience | Frontend shell |

### Shared envelope (all events)

| Field | Meaning |
| --- | --- |
| `event_id` | UUID |
| `event_version` | `activation.v1` |
| `occurred_at` | ISO timestamp |
| `correlation_id` | Pipeline correlation |
| `causation_id` | Prior event id |
| `tenant_id` | |
| `idempotency_key` | Required for retries |

---

## 3. Status log (admin)

Logical `ActivationLogEntry`:

| Field | Meaning |
| --- | --- |
| `correlation_id` | Pipeline id |
| `step` | Enum of steps above |
| `status` | `pending` \| `succeeded` \| `failed` \| `skipped` |
| `detail` | Human/debug |
| `at` | Timestamp |

Admin UI: [commercial-admin-portal-spec.md](commercial-admin-portal-spec.md) → Activation Logs.

---

## 4. Invariants

1. Bundle selection without subscription request MUST NOT grant entitlements.
2. Payment activation request MUST NOT invent merchant KYC or PSP credentials — Payment owns that flow when executed.
3. Dashboard generation is presentation-only; empty dashboards allowed if verticals not entitled.
4. No step in this document authorizes Payment 14.6+, booking engines, QR, or marketplace.