# Quickstart: Canonical Provider Connection State Cleanup

## Goal

Validate that provider connections use exactly three canonical business dimensions after the cutover:

- `Lifecycle` from `is_enabled`
- `Consent` from `consent_status`
- `Verification` from `verification_status`

The release is not complete until runtime readers, runtime writers, shared helpers, system-directory summaries, badges, factories, and tests stop depending on `status` and `health_status`.

## Prerequisites

1. Start Sail.
2. Work from the feature branch with the new lifecycle migration available.
3. Prepare seeded scenarios for at least:
   - disabled connection with granted consent and `verification_status = healthy`
   - enabled connection with required consent and unknown verification
   - enabled connection with granted consent and blocked verification caused by missing credentials
   - tenant with no default Microsoft provider connection
4. Ensure one workspace member with provider manage access and one out-of-scope actor are available for authorization checks.

## Validation Order

### 1. Run the reader-cutover regression pack

```bash
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections/ProviderConnectionEnableDisableTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections/ProviderConnectionHealthCheckStartSurfaceTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections/ProviderConnectionListAuthorizationTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections/ProviderConnectionAuthorizationTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/ProviderConnectionsUiEnforcementTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Rbac/ProviderConnectionsCreateUiEnforcementTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Rbac/EditProviderConnectionUiEnforcementTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/EntraAdminRoles/ScanEntraAdminRolesJobTest.php
```

Expected outcome:
- Resolver gates, action visibility, enable or disable behavior, and the Entra admin-roles scan all evaluate lifecycle from `is_enabled` rather than `status`.

### 2. Run the operator-surface and shared-helper regression pack

```bash
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections/ProviderConnectionTruthCleanupSpec179Test.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/ProviderConnectionsDbOnlyTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/TenantGlobalSearchLifecycleScopeTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/TenantScopingTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Tenants/TenantProviderConnectionsCtaTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/System/Spec114/DirectoryTenantsTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections/ProviderConnectionViewsDbOnlyRenderingSpec081Test.php
```

Expected outcome:
- Provider list, provider detail, provider edit, tenant provider summaries, system directory summaries, tenant global search, provider-connection search exclusion, and DB-only rendering paths show lifecycle, consent, and verification without legacy status or health language.
- System-directory list rollups count only each tenant's default Microsoft provider connection, while detail rows stay canonical for every rendered connection.

### 3. Run the writer-cutover regression pack

```bash
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections/MvpProviderScopeTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections/ProviderConnectionHealthCheckJobTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Verification/ProviderConnectionHealthCheckWritesReportTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Onboarding/OnboardingProviderConnectionTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Onboarding/OnboardingProviderConnectionPlatformDefaultTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ManagedTenantOnboardingWizardTest.php
```

Expected outcome:
- Direct resource create, health checks, onboarding, consent bootstrap, and verification start flows persist only `is_enabled`, `consent_status`, `verification_status`, and diagnostics.
- No writer recreates `status` or `health_status`.

### 4. Run the audit and badge regression pack

```bash
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections/ProviderConnectionEnableDisableTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Audit/ProviderConnectionConsentAuditTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Audit/ProviderConnectionConsentRevocationAuditTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Audit/ProviderConnectionVerificationAuditTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Badges/BooleanEnabledBadgesTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Badges/BadgeCatalogTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Badges/ProviderConnectionBadgesTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Providers/ProviderConnectionBadgeMappingTest.php
```

Expected outcome:
- Audit metadata and lifecycle-mutation regressions record lifecycle changes without reintroducing legacy `from_status` or `to_status` fields.
- Provider surfaces reuse centralized badge mappings for lifecycle, consent, and verification only.

### 5. Update helpers and run contradiction coverage

Implementation requirement:
- Update `database/factories/ProviderConnectionFactory.php` and `tests/Pest.php` so default provider fixtures use `is_enabled`, `consent_status`, and `verification_status` only.
- Add contradiction coverage proving that disabled plus consent granted and disabled plus `verification_status = healthy` remain separate truths.
- Add `tests/Feature/Guards/NoLegacyProviderConnectionStateFallbackTest.php` so targeted provider-state runtime files cannot reference removed provider columns again.

Expected outcome:
- Shared test scaffolding stops recreating removed fields.
- Canonical-state separation is enforced by tests instead of by convention.

### 6. Format touched files

```bash
cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent
```

Expected outcome:
- All touched implementation files match project formatting.

### 7. Apply the final schema state

```bash
cd apps/platform && ./vendor/bin/sail artisan migrate
```

Expected outcome:
- The final drop migration has been applied and the verification pack runs against the post-drop schema state.

### 8. Run the focused final verification pack

```bash
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections/ProviderConnectionEnableDisableTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections/ProviderConnectionListAuthorizationTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections/ProviderConnectionAuthorizationTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections/ProviderConnectionHealthCheckJobTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections/MvpProviderScopeTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Verification/ProviderConnectionHealthCheckWritesReportTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Onboarding/OnboardingProviderConnectionTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Onboarding/OnboardingProviderConnectionPlatformDefaultTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ManagedTenantOnboardingWizardTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/EntraAdminRoles/ScanEntraAdminRolesJobTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/ProviderConnectionsUiEnforcementTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Rbac/ProviderConnectionsCreateUiEnforcementTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Rbac/EditProviderConnectionUiEnforcementTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections/ProviderConnectionTruthCleanupSpec179Test.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/ProviderConnectionsDbOnlyTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/TenantGlobalSearchLifecycleScopeTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/TenantScopingTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Tenants/TenantProviderConnectionsCtaTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/System/Spec114/DirectoryTenantsTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Audit/ProviderConnectionConsentAuditTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Audit/ProviderConnectionConsentRevocationAuditTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Audit/ProviderConnectionVerificationAuditTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Badges/BooleanEnabledBadgesTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Badges/BadgeCatalogTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Badges/ProviderConnectionBadgesTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Providers/ProviderConnectionBadgeMappingTest.php
```

Expected outcome:
- The cutover works across runtime gates, writes, shared operator surfaces, audits, and badges without any dependency on removed legacy provider columns.

### 9. Perform the residual legacy-state sweep

Implementation requirement:
- Run the new residual guard test.
- Search targeted provider-state runtime paths for the removed column names to confirm there is no surviving dependency in resolvers, jobs, resources, controllers, helpers, factories, or shared Blade views.

```bash
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Guards/NoLegacyProviderConnectionStateFallbackTest.php
```

Expected outcome:
- No targeted provider-state file still reads, writes, filters, or renders `status` or `health_status` for `ProviderConnection`.

## Manual Smoke Check

1. Open `/admin/provider-connections` and confirm the default-visible state columns are `Lifecycle`, `Consent`, and `Verification`.
2. Open a disabled connection that still has granted consent and confirm the page shows `Lifecycle: Disabled` without losing the positive consent state.
3. Open a connection with granted consent and blocked verification and confirm the page shows the blocker as verification truth rather than as a synthetic legacy error state.
4. Open `/admin/tenants/{tenant}` and confirm the shared provider summary no longer renders legacy status or health diagnostics as peer truths.
5. Open `/system/directory/tenants` and `/system/directory/tenants/{tenant}` and confirm read-only summaries align with the same lifecycle, consent, and verification story shown in `/admin`.
6. Trigger enable, disable, consent, and verification flows and confirm audit history and notifications remain intact.
7. Trigger admin global search in workspace context and confirm tenants remain searchable while provider connections remain excluded.
8. Repeat one admin-plane URL as an out-of-scope actor and confirm deny-as-not-found behavior remains unchanged.

## Release Completion Criteria

- Schema no longer contains `status` or `health_status` on `provider_connections`.
- Runtime readers and writers no longer mention removed fields.
- Legacy badge domains for provider connection status and health are deleted.
- Shared helpers and views no longer expose removed legacy keys.
- Focused regression coverage and the residual guard prove the hard cut is complete.