TorbatYar/docs/reference/activation-flow-contracts.md

Activation Flow Contracts

Event contracts only. No orchestration engine in this wave.
ADR: ADR-023 · ADR-006
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 → 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.