TenantAtlas/specs/188-provider-connection-state-cleanup/research.md

Phase 0 Research: Canonical Provider Connection State Cleanup

Decision: Persist lifecycle as a single is_enabled boolean and present it as the Lifecycle dimension

Rationale: The only provider-state behavior still carried uniquely by legacy status is the explicit enabled or disabled gate. Consent and verification already have canonical enums and should not absorb administrative disablement. A boolean is_enabled is the narrowest persisted truth that preserves the current disabled behavior without inventing a broader lifecycle framework or another enum class.

Alternatives considered:

• Add a new lifecycle_status enum class: rejected because current-release behavior is binary and a boolean is narrower.
• Keep deriving disablement from legacy status: rejected because it preserves the dual-truth model the spec is removing.
• Encode disablement inside verification_status: rejected because administrative pause is not a verification outcome.

Decision: Keep ProviderConsentStatus and ProviderVerificationStatus as the only consent and verification truths

Rationale: The current schema already stores consent_status and verification_status, and the runtime already uses them in onboarding, consent, and health-check flows. The cleanup should remove the competing legacy layer, not introduce a new readiness or health family. Consent continues to answer permission state, verification continues to answer what the latest check proves, and lifecycle remains separate.

Alternatives considered:

• Introduce a new combined provider readiness status: rejected because it would collapse three distinct operator questions back into one ambiguous state.
• Preserve legacy status as a derived compatibility field: rejected because the spec calls for a hard cut with no compatibility tail.

Decision: Remove legacy projection outputs and trim ProviderConnectionStateProjector to canonical verification-outcome logic only

Rationale: ProviderConnectionStateProjector::project() and projectForConnection() exist to emit status and health_status, preserve disabled, and keep legacy fields alive across multiple writers. That responsibility disappears after cutover. The only reusable logic worth retaining is the current projectVerificationOutcome() reasoning that translates a health-check result plus current consent state into canonical consent and verification outcomes and error metadata. Retaining that narrow derivation avoids duplicating reason-code handling while still eliminating legacy field projection.

Alternatives considered:

• Keep the projector and repoint it to emit a new canonical DTO: rejected because direct canonical persistence is simpler and a new DTO layer is unnecessary.
• Inline all verification-outcome logic into each writer: rejected because the consent and verification reason-code rules already exist in one place and are reused.

Decision: Replace legacy HealthResult transport fields with canonical verification output

Rationale: HealthResult currently transports legacy status and healthStatus, and MicrosoftProviderHealthCheck manufactures those values purely so downstream code can keep writing the removed columns. The contract should instead expose canonical verification intent and diagnostics only: verificationStatus, reasonCode, message, and meta. That keeps health-check output aligned with the final storage model and removes a legacy vocabulary bridge from the contract layer.

Alternatives considered:

• Keep status and healthStatus in HealthResult until the final migration: rejected because that prolongs legacy semantics inside the runtime contract layer.
• Replace HealthResult with a new service or result hierarchy: rejected because the existing contract can be narrowed without new abstraction.

Decision: Treat reader cutover as the first breaking-change phase and schema removal as the last

Rationale: The current runtime still reads legacy fields in ProviderConnectionResolver, ScanEntraAdminRolesJob, ProviderConnectionResource action visibility, tenant provider summaries, system directory queries, and shared Blade views. Dropping columns before those reads move would break provider resolution, action gating, and page rendering immediately. The correct order is lifecycle foundation plus the one-time disabled-state backfill first, canonical reader cutover across shared helpers, operator surfaces, and runtime gates second, canonical writer and transport cleanup third, badge and helper cleanup fourth, residual test-scaffolding cleanup fifth, and schema removal last.

Alternatives considered:

• Remove columns immediately and fix failures opportunistically: rejected because the affected reads span resolvers, background jobs, Livewire actions, and read-only system pages.
• Dual-read or dual-write for a compatibility period: rejected because the feature explicitly forbids a compatibility tail.

Decision: Recompute system-directory health summaries from canonical verification and permission truth

Rationale: The system directory currently counts provider issues from health_status and renders provider rows from status and health_status. Those summaries must move to canonical verification plus existing permission signals so /system remains semantically aligned with /admin. Tenant-level list rollups count only the default Microsoft provider connection for each tenant; non-default connections may still appear on the read-only detail page but do not affect list rollup badges. The existing SystemHealth badge domain can stay; only its input contract changes.

Alternatives considered:

• Leave /system on legacy diagnostics while /admin becomes canonical: rejected because the same connection would tell two different stories depending on the plane.
• Introduce a new system-only provider-health projection: rejected because that would add another layer of derived truth.

Decision: Reuse existing centralized badge infrastructure and retire legacy provider badge domains

Rationale: The repo already has BadgeDomain::BooleanEnabled, ProviderConsentStatus, and ProviderVerificationStatus. That is enough to render lifecycle, consent, and verification without inventing a provider-lifecycle badge domain. The cleanup should delete BadgeDomain::ProviderConnectionStatus, BadgeDomain::ProviderConnectionHealth, and their mapper classes, while reusing BooleanEnabled for lifecycle and the existing provider consent and verification mappings for the other two dimensions.

Alternatives considered:

• Add a new provider lifecycle badge domain: rejected because BooleanEnabled already matches the required enabled or disabled semantics.
• Keep legacy badge domains for diagnostics only: rejected because their continued existence makes reintroduction of legacy truth too easy.

Decision: Shared provider-state helpers and views must emit only lifecycle, consent, and verification

Rationale: TenantResource::providerConnectionState(), the shared provider-connection-state.blade.php entry, and system directory detail views still carry status and health_status keys. Those helpers are the most likely place for accidental legacy fallback because many surfaces share them. Their contract should change directly to lifecycle, consent, verification, and diagnostics such as last_health_check_at and last_error_reason_code.

Alternatives considered:

• Leave legacy keys in helper arrays and stop rendering them: rejected because hidden compatibility keys would keep inviting silent legacy reads.
• Create a new presenter for canonical provider state: rejected because the existing helper contract can be narrowed without adding a new presentation layer.

Decision: Update factories and Pest helpers before final schema removal and add contradiction and residual-guard coverage

Rationale: ProviderConnectionFactory and the shared Pest helper still force status = connected and health_status = ok when constructing default provider fixtures. Those helpers will recreate legacy coupling unless they change before the drop migration lands. The regression suite also needs explicit contradiction scenarios, such as disabled plus consent granted and disabled plus verification healthy, so lifecycle separation is proven after the cutover. A final residual guard should fail if provider-state runtime paths still reference removed columns.

Alternatives considered:

• Let individual tests update as they fail: rejected because the helper layer would keep reintroducing removed fields across unrelated suites.
• Rely only on migration failure to find remaining references: rejected because many references live in PHP helpers, Blade views, and query builders that can survive until runtime.