TenantAtlas/specs/179-provider-truth-cleanup/data-model.md

# Phase 1 Data Model: Provider Readiness Source-of-Truth Cleanup

## Overview

This feature adds no table, no new enum, and no persisted readiness artifact. It reclassifies which already-stored fields are allowed to act as leading operator truth on tenant and provider connection surfaces.

## Persistent Source Truths

### Tenant

**Purpose**: Tenant identity and lifecycle boundary for all tenant-facing operator surfaces.

**Key fields**:
- `id`
- `workspace_id`
- `external_id`
- `name`
- `status`
- `app_status` (legacy tenant-level projection)
- `rbac_status`

**Relationships**:
- `Tenant` has many `ProviderConnection`

**Validation rules**:
- `status` remains the authoritative tenant lifecycle input and maps through `TenantLifecycle`.
- `app_status` remains persisted but is no longer allowed to act as leading operator truth on targeted tenant surfaces.
- `rbac_status` remains a separate domain and must not substitute for provider readiness.

### ProviderConnection

**Purpose**: Canonical stored provider-connection record for tenant-scoped provider integration state.

**Key fields**:
- `id`
- `tenant_id`
- `workspace_id`
- `provider`
- `display_name`
- `is_default`
- `connection_type`
- `consent_status`
- `verification_status`
- `status` (legacy connection-state projection)
- `health_status` (legacy health projection)
- `last_health_check_at`
- `last_error_reason_code`
- `last_error_message`
- `migration_review_required`

**Relationships**:
- `ProviderConnection` belongs to `Tenant`
- `ProviderConnection` belongs to `Workspace`
- `ProviderConnection` has one `ProviderCredential`

**Validation rules**:
- `consent_status` is the primary stored truth for consent progression.
- `verification_status` is the primary stored truth for current provider verification outcome.
- `status` and `health_status` may remain persisted and updated by existing projections, but targeted operator surfaces must treat them as secondary diagnostics only.
- `is_default` remains the routing anchor for tenant-facing provider summaries where a single connection must be chosen.

### ProviderCredential

**Purpose**: Encrypted credential storage associated with a provider connection.

**Key fields**:
- `provider_connection_id`
- encrypted credential payload fields

**Relationships**:
- `ProviderCredential` belongs to `ProviderConnection`

**Validation rules**:
- This spec does not change credential persistence, mutation rules, or encryption handling.
- Credential presence may continue to influence diagnostic projections, but it is not itself rendered as a leading readiness label on the targeted surfaces.

### OperationRun / Verification Report

**Purpose**: Stored verification evidence used by tenant verification and provider check surfaces.

**Key fields**:
- `tenant_id`
- `type` with `provider.connection.check`
- `status`
- `outcome`
- `context`
- stored verification report payload derived from the run

**Relationships**:
- `OperationRun` belongs to `Tenant` when tenant-bound

**Validation rules**:
- The latest stored verification report remains the deep-dive verification surface for tenant detail.
- This spec does not change run lifecycle, queueing, or verification report persistence.

## Existing Domain State Families

### TenantLifecycle

**Values**:
- `draft`
- `onboarding`
- `active`
- `archived`

**Rule**:
- Lifecycle answers whether the tenant is in the normal lifecycle. It does not answer provider consent, provider verification, or provider readiness.

### ProviderConsentStatus

**Values**:
- `unknown`
- `required`
- `granted`
- `failed`
- `revoked`

**Rule**:
- Consent answers whether the permission or consent step has been completed. It does not prove provider verification health.

### ProviderVerificationStatus

**Values**:
- `unknown`
- `pending`
- `healthy`
- `degraded`
- `blocked`
- `error`

**Rule**:
- Verification is the primary current provider-state axis for whether a connection has been checked and what that check currently proves.

### Legacy Diagnostic Projections

**Known provider projection values in current surfaces**:
- `status`: commonly `connected`, `needs_consent`, `error`, `disabled`
- `health_status`: commonly `ok`, `degraded`, `down`, `unknown`

**Rule**:
- These values remain diagnostics or projections. They must not compete with consent and verification as primary operator truth on targeted surfaces.

## Derived Surface Contracts

### Tenant List Row Truth (derived, non-persisted)

**Purpose**: Minimal row-level truth for `/admin/tenants`.

| Field | Type | Required | Description |
|------|------|----------|-------------|
| `tenantId` | integer | yes | Tenant identifier |
| `tenantLabel` | string | yes | Tenant name |
| `lifecycle` | string | yes | Lifecycle label derived from `TenantLifecycle` |
| `providerSignal` | object nullable | no | Optional bounded provider summary derived from current truth; may be absent in this slice |
| `legacyAppStatusVisible` | boolean | yes | Must be `false` on default-visible tenant list surfaces |
| `primaryInspectUrl` | string | yes | Canonical tenant detail destination |

**Validation rules**:
- `providerSignal` may be omitted when a truthful single-row summary cannot be stated without inventing a readiness model.
- `legacyAppStatusVisible` must be `false` for the default tenant list configuration.

### Tenant Detail Provider Summary (derived, non-persisted)

**Purpose**: Compact provider-state summary rendered inside the tenant detail `Provider` section.

| Field | Type | Required | Description |
|------|------|----------|-------------|
| `connectionPresence` | enum | yes | `missing`, `configured`, or `default_configured` |
| `ctaUrl` | string | yes | Canonical provider-connections destination |
| `displayName` | string nullable | no | Default or chosen connection display name |
| `provider` | string nullable | no | Provider label |
| `consentStatus` | string nullable | no | Current consent state from the chosen connection |
| `verificationStatus` | string nullable | no | Current verification state from the chosen connection |
| `lastCheckedAt` | string nullable | no | Stored last-check timestamp |
| `lastErrorReasonCode` | string nullable | no | Diagnostic reason code when present |
| `legacyStatus` | string nullable | no | Legacy diagnostic projection |
| `legacyHealthStatus` | string nullable | no | Legacy health projection |

**Validation rules**:
- Consent and verification are the leading fields in this summary.
- Legacy status and health may remain available only as diagnostics.
- When no default Microsoft provider connection exists, the summary must explicitly say action is needed and must not invent a healthy or ready label.

### Provider Connection Surface Truth (derived, non-persisted)

**Purpose**: Shared truth hierarchy for provider connection list, view, and edit surfaces.

| Field | Type | Required | Description |
|------|------|----------|-------------|
| `connectionId` | integer | yes | Provider connection identifier |
| `tenantLabel` | string nullable | no | Tenant label when rendered on tenantless canonical surfaces |
| `displayName` | string | yes | Connection display name |
| `provider` | string | yes | Provider key or label |
| `connectionType` | string | yes | Platform or dedicated |
| `isDefault` | boolean | yes | Default designation |
| `consentStatus` | string | yes | Leading consent truth |
| `verificationStatus` | string | yes | Leading verification truth |
| `legacyStatus` | string nullable | no | Secondary diagnostic projection |
| `legacyHealthStatus` | string nullable | no | Secondary diagnostic projection |
| `migrationReviewRequired` | boolean | yes | Secondary diagnostic flag |
| `lastCheckedAt` | string nullable | no | Last stored check timestamp |
| `lastErrorReasonCode` | string nullable | no | Stored diagnostic reason code |

**Validation rules**:
- List, view, and edit surfaces must display `consentStatus` and `verificationStatus` before any legacy projection fields.
- Legacy fields may remain filterable or visible only when clearly marked and positioned as diagnostics.
- `connectionType` and `isDefault` remain supporting facts, not substitutes for readiness.

## Surface Truth Hierarchy Rules

1. Tenant lifecycle is the primary tenant-state axis.
2. Provider consent and provider verification are the primary provider-state axes.
3. RBAC remains a separate tenant-management domain.
4. Legacy tenant app status, provider status, and provider health are diagnostic-only on targeted surfaces.
5. No derived surface contract in this feature may collapse `active`, `connected`, or `consented` into a synthetic `ready` value.

## No New Persistence

- No new table is introduced.
- No new enum or reason family is introduced.
- No new persisted readiness summary is introduced.
- Existing persisted legacy fields remain for compatibility, but their surface role is reduced.