TenantAtlas/specs/148-central-tenant-operability-policy/data-model.md

# Phase 1 Data Model: Central Tenant Operability Policy

## Overview

This feature does not require a new database table in its first implementation slice. The primary data-model work is the formalization of existing persistent records plus new derived domain objects that express tenant operability consistently across lanes.

## Persistent Domain Entities

### Tenant

**Purpose**: Durable workspace-owned record whose lifecycle influences operability.

**Key fields**:
- `id`
- `workspace_id`
- `external_id`
- `status` with canonical values `draft`, `onboarding`, `active`, `archived`
- `deleted_at` for archive persistence behavior

**Relationships**:
- Belongs to one workspace
- Has many onboarding sessions, audit logs, provider connections, and tenant-owned operational records
- May be referenced by canonical workspace records such as `OperationRun`

**Validation rules**:
- `workspace_id` must match the active workspace scope for all in-scope route or action decisions
- `status` must resolve through the canonical `TenantLifecycle` model
- Soft-delete state is an implementation input, never the only semantic rule

**State transitions relevant to this feature**:
- `draft` → `onboarding`
- `onboarding` → `active`
- `active` → `archived`
- `archived` → `active`

### TenantOnboardingSession

**Purpose**: Separate workspace-scoped workflow record used to evaluate onboarding-lane actions.

**Key fields**:
- `id`
- `workspace_id`
- `tenant_id` nullable until linked
- workflow state and lifecycle fields already used by onboarding services

**Relationships**:
- Belongs to one workspace
- Optionally belongs to one tenant

**Validation rules**:
- Must be in the same workspace as any linked tenant
- Onboarding-specific operability decisions must validate both tenant lifecycle and workflow resumability

### OperationRun

**Purpose**: Canonical workspace-owned record that may reference a tenant without becoming subordinate to selected tenant context.

**Key fields**:
- `id`
- `workspace_id`
- `tenant_id` nullable
- `type`
- `status`
- `outcome`

**Relationships**:
- Belongs to one workspace
- May belong to one tenant reference

**Validation rules**:
- Canonical route legitimacy is based on the run and workspace first
- Tenant-linked follow-up actions must still respect tenant entitlement and operability outcomes

### UserTenantPreference and WorkspaceContext Session State

**Purpose**: Stores remembered tenant context for the active operating lane.

**Key fields**:
- `user_id`
- `tenant_id`
- `last_used_at`
- session-scoped workspace and remembered-tenant identifiers

**Validation rules**:
- Remembered tenant is valid only when workspace match, tenant existence, entitlement, and selector-lane operability all still hold

## New Derived Domain Objects

### TenantInteractionLane

**Purpose**: Explicitly identifies the lane in which the tenant is being evaluated.

**Canonical values**:
- `standard_active_operating`
- `onboarding_workflow`
- `administrative_management`
- `canonical_workspace_record`

**Why it exists**:
- The same tenant can be selector-ineligible yet still administratively viewable or canonically referenceable

### TenantOperabilityContext

**Purpose**: Normalized evaluation input for the central policy layer.

**Fields**:
- `tenant`
- `actor`
- `workspaceId`
- `lane`
- `pageCategory`
- `linkedRecordType` nullable
- `linkedRecordId` nullable
- `onboardingDraft` nullable
- `requiredCapability` nullable
- `selectedTenant` nullable

**Context ownership**:
- Consumers normalize and pass route, record, workflow, and selected-tenant inputs into the context.
- The central service resolves workspace membership, tenant entitlement, capability truth, lifecycle, and archived persistence state through canonical workspace, tenant, and RBAC helpers at evaluation time.
- Consumers may request a capability-aware question, but they do not authoritatively decide membership or entitlement before evaluation.

**Validation rules**:
- `tenant.workspace_id` must equal `workspaceId`
- linked records must belong to the same workspace when tenant-linked
- `selectedTenant` may be informative but never authoritative

### TenantOperabilityQuestion

**Purpose**: Declares the exact semantic question the consumer is asking.

**Canonical values**:
- `selector_eligibility`
- `remembered_context_validity`
- `tenant_bound_viewability`
- `canonical_linked_record_viewability`
- `archive_eligibility`
- `restore_eligibility`
- `resume_onboarding_eligibility`
- `onboarding_completion_eligibility`
- `verification_readiness_eligibility`
- `administrative_discoverability`

### TenantOperabilityOutcome

**Purpose**: Structured result returned by the central operability policy.

**Fields**:
- `question`
- `allowed`
- `lifecycle`
- `lane`
- `reasonCode` nullable
- `requiredCapability` nullable
- `discoverable` boolean
- `informationalMessageKey` nullable
- `metadata` key-value bag for consumer-safe hints

**Behavior**:
- Must be stable enough for unit assertions and UI mapping
- May expose helper methods for common adapters, but raw outcome data remains canonical

### TenantOperabilityReasonCode

**Purpose**: Stable denial or ineligibility reason catalog.

**Initial values**:
- `workspace_mismatch`
- `tenant_not_entitled`
- `missing_capability`
- `wrong_lane`
- `selector_ineligible_lifecycle`
- `tenant_not_archived`
- `tenant_already_archived`
- `onboarding_not_resumable`
- `canonical_view_followup_only`
- `remembered_context_stale`

## Consumer Mapping

| Consumer | Primary question(s) |
|---|---|
| Choose-tenant page | `selector_eligibility` |
| Select-tenant controller | `selector_eligibility`, `remembered_context_validity` |
| WorkspaceContext | `remembered_context_validity` |
| OperateHubShell | `tenant_bound_viewability`, `canonical_linked_record_viewability`, `administrative_discoverability` |
| TenantActionPolicySurface | `archive_eligibility`, `restore_eligibility`, `resume_onboarding_eligibility`, `verification_readiness_eligibility` |
| ManagedTenantOnboardingWizard | `resume_onboarding_eligibility`, `onboarding_completion_eligibility`, `verification_readiness_eligibility` |
| TenantResource global search and admin listing | `administrative_discoverability` |
| TenantlessOperationRunViewer | `canonical_linked_record_viewability` and follow-up action questions |

## Migration Notes

- No persistence migration is required for the first slice.
- Existing boolean accessors on `TenantOperabilityService` may remain as compatibility adapters while consumers migrate to structured outcomes.
- Any new enums or value objects should live under `app/Support/Tenants` to stay aligned with existing lifecycle, page-category, and action-surface support code.