TenantAtlas/specs/143-tenant-lifecycle-operability-context-semantics/data-model.md

# Data Model: Tenant Lifecycle, Operability, and Context Semantics Foundation

## Core Entities

### Workspace

- Purpose: Primary ownership, isolation, and session boundary.
- Existing source: `App\Models\Workspace`.
- Key relationships:
  - has many tenants
  - has many onboarding workflow records
  - has many canonical operation runs
- Validation and invariants:
  - Workspace membership is required before any tenant or canonical record is revealed.
  - Workspace-owned canonical viewers may exist without tenant context in the URL.

### Tenant

- Purpose: Durable workspace-owned tenant record.
- Existing source: `App\Models\Tenant`.
- Canonical fields relevant to this feature:
  - `id`
  - `workspace_id`
  - `external_id`
  - `name`
  - `status`
  - `deleted_at`
  - `is_current`
- Canonical lifecycle states:
  - `draft`
  - `onboarding`
  - `active`
  - `archived`
- Relationships:
  - belongs to workspace
  - has many memberships
  - may be linked from onboarding workflow records
  - may be referenced by operation runs
- Validation and invariants:
  - Tenant lifecycle is the durable domain status, not the full workflow progression state.
  - Only `active` tenants may become normal tenant context.
  - Archived tenants remain retained for auditability and controlled restoration.

### TenantOnboardingSession

- Purpose: Workspace-scoped onboarding workflow record.
- Existing source: `App\Models\TenantOnboardingSession`.
- Key fields relevant to this feature:
  - `id`
  - `workspace_id`
  - `tenant_id`
  - `lifecycle_state`
  - `current_checkpoint`
  - `last_completed_checkpoint`
  - `state`
  - `version`
  - `completed_at`
  - `cancelled_at`
- Relationships:
  - belongs to workspace
  - optionally belongs to tenant
- Validation and invariants:
  - Owns onboarding progression, resumability, and conflict-safe mutation.
  - Does not replace tenant lifecycle.
  - Must enforce workspace entitlement, and tenant entitlement once a tenant link exists.

### OperationRun

- Purpose: Canonical workspace-owned record for long-running or operationally relevant work.
- Existing source: `App\Models\OperationRun`.
- Key fields relevant to this feature:
  - `id`
  - `workspace_id`
  - `tenant_id` nullable
  - `type`
  - `status`
  - `outcome`
  - `context`
  - `summary_counts`
  - `failure_summary`
- Relationships:
  - belongs to workspace
  - optionally belongs to tenant
- Validation and invariants:
  - A canonical viewer authorizes from the run, workspace, and entitlement checks.
  - Tenant mismatch against remembered context must not invalidate the run.
  - Status and outcome transitions remain service-owned.

### RememberedTenantContext

- Purpose: Operator preference state that remembers the last tenant selection per workspace.
- Existing implementation surfaces:
  - `App\Support\Workspaces\WorkspaceContext`
  - `App\Http\Controllers\SelectTenantController`
  - `App\Http\Controllers\ClearTenantContextController`
  - `App\Filament\Pages\ChooseTenant`
- Data shape:
  - `workspace_id`
  - `tenant_id`
- Validation and invariants:
  - This is not an authorization primitive.
  - It may prefilter workspace pages and drive convenience redirects.
  - It must be cleared or ignored when the selected tenant is no longer eligible for normal active context.

## Derived Domain Concepts

### TenantOperabilityDecision

- Purpose: Derived policy result for what the operator may do with a tenant.
- Inputs:
  - actor
  - workspace
  - tenant
  - page category
  - requested operation
- Outputs:
  - `can_view_tenant_surface`
  - `can_select_as_context`
  - `can_operate`
  - `can_archive`
  - `can_restore`
  - `can_resume_onboarding`
  - `can_reference_in_workspace_monitoring`

### PageCategory

- Purpose: Normalize route semantics by page type.
- Canonical values:
  - `workspace_scoped`
  - `tenant_bound`
  - `onboarding_workflow`
  - `canonical_workspace_record_viewer`
- Invariants:
  - Every in-scope route must map to one category.
  - Route legitimacy rules are defined by category, not by remembered tenant state.

### LifecyclePresentationSpec

- Purpose: Central mapping from tenant lifecycle to operator-facing label, badge color, icon, and allowed explanatory copy.
- Existing extension point:
  - `BadgeCatalog`
  - `BadgeDomain::TenantStatus`
- Invariants:
  - All canonical lifecycle values must map explicitly.
  - No valid lifecycle may render as `Unknown`.

## State Transitions

### Tenant lifecycle transitions

- `draft -> onboarding`
  - Trigger: onboarding has advanced enough that the tenant exists as an in-progress managed tenant.
- `onboarding -> active`
  - Trigger: onboarding completion or activation flow defined by follow-up implementation specs.
- `active -> archived`
  - Trigger: explicit archive action with authorization, confirmation, and audit logging.
- `archived -> restored_state`
  - Trigger: explicit restore action defined by follow-up specs.
  - Note: current model restore behavior returns to `active`, but this foundation leaves restored-state semantics to follow-up work.

### Onboarding workflow transitions

- Stay owned by `TenantOnboardingSession` lifecycle and checkpoint services.
- Must not be conflated with tenant lifecycle labels or selector eligibility.

## Route-to-entity mapping

- `/admin`, `/admin/choose-workspace`, `/admin/operations`: workspace plus remembered tenant preference, optionally filtered by tenant.
- `/admin/choose-tenant`: workspace plus eligible tenant collection.
- `/admin/tenants`, `/admin/tenants/{tenant}`: workspace plus route tenant.
- `/admin/onboarding`, `/admin/onboarding/{onboardingDraft}`: workspace plus onboarding workflow record, optionally linked tenant.
- `/admin/operations/{run}`: workspace plus canonical operation run, optionally linked tenant.

## Test focus derived from the model

- Selector eligibility tests for all tenant lifecycle states.
- Canonical run viewer tests for mismatched selected tenant versus referenced tenant.
- Badge coverage tests for every canonical tenant lifecycle state.
- Authorization tests asserting 404 for non-members and 403 for members missing capability.
- Onboarding workflow tests proving onboarding drafts remain visible and resumable without becoming active tenant context.