TenantAtlas/specs/188-provider-connection-state-cleanup/data-model.md

Phase 1 Data Model: Canonical Provider Connection State Cleanup

Overview

This feature removes the persisted legacy provider-state columns status and health_status and replaces their last remaining behavioral responsibility with one explicit lifecycle truth: is_enabled. Consent and verification remain on their existing canonical enums. No new table, no new persisted summary artifact, and no new cross-domain provider-state framework are introduced.

Persistent Source Truths

ProviderConnection

Purpose: Canonical tenant-owned provider integration record for provider lifecycle, consent, verification, and supporting diagnostics.

Key fields:

• id
• tenant_id
• workspace_id
• provider
• entra_tenant_id
• display_name
• is_default
• connection_type
• is_enabled
• consent_status
• consent_granted_at
• consent_last_checked_at
• consent_error_code
• consent_error_message
• verification_status
• migration_review_required
• migration_reviewed_at
• scopes_granted
• last_health_check_at
• last_error_reason_code
• last_error_message
• metadata

Removed fields:

• status
• health_status

Relationships:

• ProviderConnection belongs to Tenant
• ProviderConnection belongs to Workspace
• ProviderConnection has one ProviderCredential

Validation rules:

• is_enabled is the only persisted lifecycle truth and defaults to true for newly created connections.
• consent_status remains the only consent truth.
• verification_status remains the only verification truth.
• status and health_status are not recreated through accessors, casts, appended attributes, helper arrays, or audit context shims.
• Existing unique constraints on tenant, provider, and Entra tenant identity remain unchanged.
• Existing indexes for consent_status and verification_status remain. Legacy indexes tied to removed columns are dropped. No new lifecycle index is introduced unless implementation profiling proves it necessary.

ProviderCredential

Purpose: Encrypted credential material associated with a provider connection.

Key fields:

• provider_connection_id
• encrypted credential payload fields

Relationships:

• ProviderCredential belongs to ProviderConnection

Validation rules:

• This feature does not change credential storage or encryption.
• Credential presence remains a diagnostic or blocker input for lifecycle-safe verification semantics, not a fourth provider-state dimension.

HealthResult (internal contract)

Purpose: Canonical result object emitted by provider health checks before persistence.

Key fields:

• verification_status
• reason_code
• message
• meta

Validation rules:

• The contract must not carry legacy status or health_status fields.
• The contract may carry only the minimum data needed to derive canonical consent and verification outcomes plus diagnostics.

Canonical State Families

Lifecycle (derived from is_enabled)

Persisted form:

• is_enabled = true
• is_enabled = false

Operator-facing form:

• Enabled
• Disabled

Rule:

• Lifecycle answers only whether the connection is administratively allowed to operate.
• Lifecycle does not imply consent and does not imply the latest verification outcome.

ProviderConsentStatus

Values:

• unknown
• required
• granted
• failed
• revoked

Rule:

• Consent answers only whether required provider consent currently exists and whether consent-specific failure or revocation was detected.
• Consent does not imply lifecycle and does not imply technical verification success.

ProviderVerificationStatus

Values:

• unknown
• pending
• healthy
• degraded
• blocked
• error

Rule:

• Verification answers only what the latest verification attempt or local canonical blocker currently proves.
• Verification does not imply lifecycle and does not rewrite consent.

State Transitions

Lifecycle transitions

From	To	Trigger	Notes
true	false	Explicit disable action	Consent and verification remain intact as separate truths.
false	true	Explicit enable action	Lifecycle resumes without fabricating consent or a healthy verification state.

Consent transitions

From	To	Trigger	Notes
unknown or required	granted	Successful admin consent callback or successful verification that proves consent still exists	Does not change lifecycle.
granted	revoked	Verification detects consent was revoked	Verification may become blocked, but lifecycle remains separate.
any	failed	Consent-specific failure during callback or verification	Does not disable the connection.

Verification transitions

From	To	Trigger	Notes
unknown	pending	Verification start	Existing start surfaces remain authoritative.
pending	healthy, degraded, blocked, or error	Verification completion	Derived from the health-check result and current consent truth.
any	unknown	New connection creation, successful enable with present credentials, or credential mutation that invalidates prior verification but does not prove a blocker	Keeps stale success from surviving a material configuration change.
any	blocked	Local or remote evidence proves a blocker, such as missing credentials, invalid connection type, consent missing, or review-required state	Blocked remains a verification consequence, not a lifecycle substitute.

Mutation Rules

Connection creation and onboarding bootstrap

Expected persisted shape:

• is_enabled = true
• consent_status = required for pre-consent onboarding starts
• verification_status = unknown
• diagnostics cleared or initialized from the current event

Consent callback

Expected persisted shape:

• lifecycle unchanged or initialized to is_enabled = true
• consent_status updated from callback outcome
• verification_status = unknown
• consent and error timestamps refreshed

Verification start

Expected persisted shape:

• lifecycle unchanged
• consent unchanged
• verification_status = pending
• legacy status or health projections are not written

Verification completion / health check

Expected persisted shape:

• lifecycle unchanged
• consent_status updated only when the result proves a consent consequence
• verification_status updated from the canonical health result
• error and recency diagnostics refreshed

Enable and disable actions

Expected persisted shape:

• Disable writes only is_enabled = false plus any audit metadata that records the lifecycle change.
• Enable writes is_enabled = true and resets stale verification truth without fabricating a healthy state.
• When enabling reveals a local blocker such as missing credentials, verification_status becomes blocked and the blocker reason is recorded in diagnostics.

Credential-source and mutation-service changes

Expected persisted shape:

• lifecycle unchanged unless the operator explicitly disables the connection
• consent unchanged unless the mutation directly changes consent evidence
• verification reset to unknown or blocked depending on whether the mutation invalidates prior verification or proves a blocker

Derived Surface Contracts

Canonical provider state bundle

Purpose: Shared derived state used by provider detail, edit, tenant summaries, and system read-only views.

Field	Type	Required	Description
lifecycle	string	yes	enabled or disabled, derived from is_enabled
isEnabled	boolean	yes	Raw persisted lifecycle truth
consentStatus	string nullable	yes	Canonical consent status
verificationStatus	string nullable	yes	Canonical verification status
connectionType	string	yes	Platform or dedicated
isDefault	boolean	yes	Default designation
lastCheckedAt	string nullable	no	Stored verification recency
lastErrorReasonCode	string nullable	no	Latest diagnostic reason
lastErrorMessage	string nullable	no	Latest diagnostic message
migrationReviewRequired	boolean	yes	Existing migration-review diagnostic

Validation rules:

• No helper array or view model may expose status or health_status keys.
• Diagnostics remain subordinate to lifecycle, consent, and verification.

Tenant provider summary

Purpose: Compact provider summary rendered from TenantResource::providerConnectionState() and the shared provider-state Blade entry.

Field	Type	Required	Description
state	string	yes	missing, configured, or default_configured
cta_url	string	yes	Canonical provider-connections destination
needs_default_connection	boolean	yes	Signals action needed without inventing provider health
display_name	string nullable	no	Chosen connection display name
provider	string nullable	no	Provider label
is_enabled	boolean nullable	no	Raw lifecycle truth when a connection exists
consent_status	string nullable	no	Canonical consent status
verification_status	string nullable	no	Canonical verification status
last_health_check_at	string nullable	no	Stored verification recency
last_error_reason_code	string nullable	no	Latest diagnostic reason

Validation rules:

• Missing or non-default states must never read as healthy or ready.
• The summary must not return removed legacy keys for compatibility.

System tenant health rollup

Purpose: Read-only system-directory aggregate used to derive SystemHealth badges.

Field	Type	Required	Description
tenantStatus	string	yes	Existing tenant lifecycle/status input
criticalProviderCount	integer	yes	Count of each tenant's default Microsoft provider connection when its verification_status is blocked or error
warningProviderCount	integer	yes	Count of each tenant's default Microsoft provider connection when its verification_status = degraded
missingPermissionCount	integer	yes	Existing tenant-permission signal

Validation rules:

• System health rollups must not query removed health_status values.
• Tenant-directory list rollups count only the default Microsoft provider connection for each tenant. Non-default connections may still appear on the system tenant detail page, but they do not affect list rollup counts.
• The same provider connection must produce semantically aligned admin and system readings.

Removal Rules

1. status and health_status are removed from the database schema, Eloquent model interactions, helper arrays, Blade views, badge domains, query filters, and audit metadata.
2. ProviderConnection::classificationProjection() and any equivalent projection helpers no longer emit removed fields.
3. Runtime gates read lifecycle from is_enabled, not from any verification or consent surrogate.
4. Diagnostics remain stored and displayed only as supporting facts, not as another state language.

No New Persistence Beyond The Narrow Lifecycle Field

• No new table is introduced.
• No new provider-readiness summary is persisted.
• No new enum class is introduced for lifecycle; the persisted truth is a boolean and the operator-facing labels are derived.
• The cleanup removes more persisted truth than it adds: two legacy columns out, one lifecycle column in.