# Data Model: Tenant Action Taxonomy and Lifecycle-Safe Visibility

## 1. Tenant

**Type**: Existing persisted model (`App\Models\Tenant`)

**Core fields**:
- `id`
- `workspace_id`
- `external_id`
- `tenant_id`
- `name`
- `status` (`draft`, `onboarding`, `active`, `archived`)
- `deleted_at`
- `is_current`

**Relationships**:
- belongs to `Workspace`
- has many `TenantOnboardingSession`
- has many provider/operational records already used elsewhere in the admin plane

**Validation / invariants**:
- `workspace_id` is required
- `status` must resolve to a canonical `TenantLifecycle`
- soft-delete implies archived semantics on lifecycle-sensitive surfaces
- only active tenants are selectable as remembered tenant context

**Lifecycle transitions relevant to this feature**:
- `draft -> onboarding`: onboarding workflow progresses after tenant identification
- `onboarding -> active`: onboarding completes through workflow activation semantics
- `onboarding -> draft`: last resumable onboarding draft is cancelled and linked tenant is normalized back to draft
- `active -> archived`: archive action soft-deletes tenant and sets archived semantics
- `archived -> active`: restore action reactivates archived tenant

## 2. TenantOnboardingSession

**Type**: Existing persisted model (`App\Models\TenantOnboardingSession`)

**Core fields**:
- `id`
- `workspace_id`
- `tenant_id` nullable until linked
- `entra_tenant_id`
- `current_step`
- `lifecycle_state`
- `current_checkpoint`
- `last_completed_checkpoint`
- `state` JSON
- `completed_at`
- `cancelled_at`
- `version`

**Relationships**:
- belongs to `Workspace`
- belongs to `Tenant` optionally
- belongs to `startedByUser`
- belongs to `updatedByUser`

**Validation / invariants**:
- workspace entitlement always required
- tenant entitlement required once a linked tenant exists
- resumability is workflow-derived, not inferred only from tenant lifecycle
- activation readiness is determined by `OnboardingLifecycleService`

**Lifecycle semantics relevant to this feature**:
- drives `Resume onboarding`
- drives `Complete onboarding` availability
- must remain distinct from archive/restore semantics

## 3. TenantActionContext

**Type**: New derived domain object or array DTO proposed by this plan

**Purpose**: Encapsulate the inputs needed to decide whether an action is visible, enabled, grouped, or executable on a specific surface.

**Fields**:
- `tenant_id`
- `workspace_id`
- `tenant_lifecycle`
- `surface` (`tenant_index_row`, `tenant_view_header`, `tenant_edit_header`, `onboarding_index_row`, `onboarding_detail_header`, `widget`, `context_menu`)
- `page_category`
- `has_related_onboarding_session`
- `related_onboarding_is_resumable`
- `is_member`
- `has_capability`
- `is_archived`

**Derivation sources**:
- `TenantOperabilityService`
- `OnboardingLifecycleService`
- `TenantOnboardingSessionPolicy`
- `UiEnforcement` / capability resolvers

## 4. TenantActionDescriptor

**Type**: New derived domain object or array DTO proposed by this plan

**Purpose**: Normalized description of one operator-facing action returned by the tenant-action policy surface.

**Fields**:
- `key` (`view`, `resume_onboarding`, `archive`, `restore`, `view_operations`, `verify`, `grant_admin_consent`)
- `family` (`neutral`, `onboarding_workflow`, `lifecycle_management`, `readiness`)
- `label`
- `visible`
- `enabled`
- `destructive`
- `requires_confirmation`
- `capability`
- `audit_action_id` nullable
- `reason_code` nullable when hidden or disabled
- `priority` or `group` to distinguish primary versus overflow actions
- `url` or `handler` metadata depending on surface

**Invariants**:
- label must match domain semantics
- archive and restore are mutually exclusive for one tenant on one surface
- onboarding-only actions and active-only actions are mutually exclusive except in explicit workflow context
- `requires_confirmation` must be true for destructive-like lifecycle mutations

## 5. TenantActionPolicySurface

**Type**: New service/resolver proposed by this plan

**Purpose**: Produce `TenantActionDescriptor` collections from `TenantActionContext` and central lifecycle/workflow/RBAC rules.

**Responsibilities**:
- resolve primary and overflow actions per surface
- enforce lifecycle-safe visibility before RBAC helper decoration
- keep onboarding workflow actions distinct from archive/restore
- provide reusable predicates for `canArchiveTenant`, `canRestoreTenant`, `canResumeOnboardingTenant`, `canShowActivationAction`, and `canShowReadinessActions`

**Non-responsibilities**:
- executing mutations
- replacing server-side authorization
- persisting lifecycle state

## 6. Audit Lifecycle Events

**Type**: Existing enum-backed audit vocabulary

**Relevant values**:
- `tenant.archived`
- `tenant.restored`
- `tenant.returned_to_draft`
- `managed_tenant_onboarding.resume`
- `managed_tenant_onboarding.cancelled`
- `managed_tenant_onboarding.activation`

**Requirement**:
- UI action taxonomy must stay aligned with these events so operator intent can be reconstructed from audit history.