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

Feature Specification: Canonical Provider Connection State Cleanup

Feature Branch: [188-provider-connection-state-cleanup]
Created: 2026-04-09
Status: Draft
Input: User description: "Spec 188 — Canonical Provider Connection State Cleanup"

Spec Scope Fields (mandatory)

• Scope: workspace + tenant + platform directory alignment
• Primary Routes:
  • /admin/provider-connections
  • /admin/provider-connections/{record}
  • /admin/provider-connections/{record}/edit
  • /admin/tenants
  • /admin/tenants/{tenant}
  • existing tenant-context admin flows under /admin/t/{tenant}/...
  • /system/directory/tenants
  • /system/directory/tenants/{tenant}
• Data Ownership: Provider connection state remains tenant-owned truth on provider connection records scoped by workspace and tenant. This feature removes the legacy provider status and health storage from that tenant-owned truth and leaves one explicit lifecycle truth beside the existing consent and verification truth. System directory surfaces remain read-only views over the same tenant-owned truth; no compatibility mirror, summary artifact, or second state ledger is introduced.
• RBAC: The admin plane under /admin and tenant-context admin routes under /admin/t/{tenant}/... continue to require workspace entitlement plus tenant entitlement. The platform directory under /system continues to require platform directory access and must not inherit admin-plane membership. Non-members remain deny-as-not-found (404). In-scope actors missing the required capability remain forbidden (403). Existing server-side capability checks, confirmations, and audit behavior for provider mutations remain authoritative.

For canonical-view specs, the spec MUST define:

• Default filter behavior when tenant-context is active: Workspace-context provider connection surfaces remain prefiltered to the current tenant when tenant context or an explicit tenant filter is active. Platform directory surfaces under /system never inherit tenant context and remain platform-scoped.
• Explicit entitlement checks preventing cross-tenant leakage: Admin-plane queries, summaries, shared provider-state entries, and drill-downs must continue to scope provider connections to the active workspace and entitled tenant set only. Any platform-directory link into an admin-plane tenant surface must still respect admin-plane workspace and tenant entitlement and fail as 404 when that entitlement is absent.

UI/UX Surface Classification (mandatory when operator-facing surfaces are changed)

Surface	Surface Type	Primary Inspect/Open Model	Row Click	Secondary Actions Placement	Destructive Actions Placement	Canonical Collection Route	Canonical Detail Route	Scope Signals	Canonical Noun	Critical Truth Visible by Default	Exception Type
Provider connections list	CRUD / List-first Resource	Full-row click into provider connection detail	required	Header New connection; non-primary mutations remain in More	Existing lifecycle and credential mutations remain secondary in More and keep confirmation where destructive-like	/admin/provider-connections	/admin/provider-connections/{record}	Active workspace, current tenant filter, provider identity, default marker	Provider Connections / Provider Connection	Lifecycle, consent, and verification shown as separate dimensions; no legacy status or health language	none
Provider connection detail	Detail / view-first resource	Dedicated detail page	forbidden	Existing detail actions stay grouped in the header area	Existing lifecycle and credential mutations stay grouped and confirmed	/admin/provider-connections	/admin/provider-connections/{record}	Tenant identity, provider identity, connection type, default marker	Provider Connection	Lifecycle, consent, and verification remain distinct while diagnostics stay secondary	none
Provider connection edit	Edit surface	Dedicated edit page	forbidden	Save/cancel plus existing grouped helper actions	Existing lifecycle and credential mutations stay grouped and confirmed	/admin/provider-connections	/admin/provider-connections/{record}/edit	Tenant identity, provider identity, connection type, default marker	Provider Connection	Current lifecycle, consent, and verification context is visible without legacy fields	none
Tenant list	CRUD / List-first Resource	Full-row click into tenant detail	required	Existing tenant helper and workflow actions remain secondary	Existing tenant destructive actions remain secondary and unchanged	/admin/tenants	/admin/tenants/{tenant}	Active workspace, tenant identity, environment	Tenants / Tenant	Any provider-state summary must come only from canonical lifecycle, consent, and verification truth	none
Tenant detail and tenant-context admin provider summaries	Detail / dashboard / workflow surfaces	Existing tenant page or tenant-context page itself	forbidden	Existing tenant and provider navigation actions remain secondary	Existing destructive tenant or provider mutations remain grouped and confirmed	/admin/tenants and existing /admin/t/{tenant}/... routes	/admin/tenants/{tenant} plus existing tenant-context destinations	Active workspace, tenant context, provider identity	Tenant / Provider Connection	Provider state is presented as lifecycle, consent, and verification only, with no shadow diagnostic truth	none
System tenant directory list	Read-only registry / list	Full-row click into system tenant detail	required	No secondary actions are introduced	none	/system/directory/tenants	/system/directory/tenants/{tenant}	Platform context, workspace label, tenant identity	Tenants / Tenant	Read-only health summaries must not depend on legacy provider status or health fields	none
System tenant detail	Read-only detail surface	Dedicated detail page	forbidden	Existing navigation links remain the only secondary affordances	none	/system/directory/tenants	/system/directory/tenants/{tenant}	Platform context, workspace label, tenant identity	Tenant / Provider Connection	Provider rows show only lifecycle, consent, and verification truth	none

Operator Surface Contract (mandatory when operator-facing surfaces are changed)

Surface	Primary Persona	Surface Type	Primary Operator Question	Default-visible Information	Diagnostics-only Information	Status Dimensions Used	Mutation Scope	Primary Actions	Dangerous Actions
Provider connections list	Tenant operator or tenant manager	List	Which connections are operable, consented, and technically verified right now?	Provider identity, default marker, lifecycle, consent, verification	Last check recency, raw provider errors, low-level identifiers	lifecycle, consent, verification	Existing provider mutations only; no new mutation type	Open provider connection, New connection	Disable connection, credential deletion or rotation, and similar existing lifecycle mutations remain secondary and confirmed
Provider connection detail	Tenant operator or tenant manager	Detail	Can this connection be used, is consent present, and what does the last verification actually prove?	Lifecycle, consent, verification, provider identity, default designation	Raw provider response details, timestamps, supporting diagnostics	lifecycle, consent, verification	Existing provider mutations only	Check connection, Grant admin consent, Edit	Existing lifecycle and credential mutations remain grouped, capability-gated, and confirmed
Provider connection edit	Tenant manager	Edit	What can I safely change without confusing configuration, consent, and verification truth?	Editable settings plus current lifecycle, consent, and verification context	Low-level technical metadata only when explicitly needed	lifecycle, consent, verification	Existing provider configuration mutations only	Save changes, Cancel	Existing lifecycle and credential mutations remain grouped, capability-gated, and confirmed
Tenant list	Workspace operator	List	Which tenants have provider connections that need attention, and is that attention about lifecycle, consent, or verification?	Tenant identity plus any bounded provider-state summary derived from canonical truth	Legacy-style provider diagnostics are not allowed as hidden primary truth	lifecycle, consent, verification when summarized	none; read-first list	Open tenant	Existing tenant destructive actions remain outside this spec and stay secondary
Tenant detail and tenant-context admin provider summaries	Tenant operator	Detail / workflow	What is the provider state for this tenant, and which dimension needs action?	Lifecycle, consent, verification, next-step guidance	Supporting diagnostics such as timestamps or detailed messages	lifecycle, consent, verification	Existing tenant and provider mutations only	Open provider connection, Grant admin consent, Start verification where already available	Existing destructive tenant or provider actions remain confirmed and capability-gated
System tenant directory list	Platform operator	Read-only list	Which tenants show provider-connection concerns without importing a second truth model?	Tenant identity, workspace, any read-only summary derived from canonical truth	Low-level health breakdowns remain secondary if shown at all	lifecycle, consent, verification when summarized	none	Open tenant detail	none
System tenant detail	Platform operator	Read-only detail	Does the same provider connection tell the same lifecycle, consent, and verification story here as it does in admin surfaces?	Provider rows with lifecycle, consent, verification	Supporting diagnostics and recent runs	lifecycle, consent, verification	none	Open admin tenant when legitimately available, View runs when already available	none

Proportionality Review (mandatory when structural complexity is introduced)

• New source of truth?: yes
• New persisted entity/table/artifact?: no
• New abstraction?: no
• New enum/state/reason family?: yes
• New cross-domain UI framework/taxonomy?: no
• Current operator problem: Provider connections still carry two competing state languages. The same connection can appear disabled, connected, healthy, consented, or verified depending on which legacy field or newer field a runtime path or page reads. That creates incorrect gates, inconsistent operator guidance, and semantic confusion.
• Existing structure is insufficient because: Consent truth and verification truth already exist, but the remaining legacy status and health fields still persist, still influence runtime behavior, and still appear in multiple surfaces. The leftover administrative semantics, especially enabled or disabled behavior, do not belong inside consent or verification and cannot be modeled cleanly by leaving the legacy layer half-active.
• Narrowest correct implementation: Remove legacy provider status and health truth completely, keep consent and verification as the canonical truth for their own dimensions, and make lifecycle explicit as the only additional canonical dimension required to preserve real enabled or disabled behavior.
• Ownership cost: This adds one focused state-model cleanup across persistence, runtime readers and writers, contracts, badges, filters, operator surfaces, and regression coverage, but it avoids carrying an indefinite compatibility tail.
• Alternative intentionally rejected: Keeping legacy fields as compatibility mirrors, or forcing disabled or enabled semantics into consent or verification, was rejected because both options preserve parallel truth and semantic drift.
• Release truth: current-release hard cutover and canonical domain cleanup

User Scenarios & Testing (mandatory)

User Story 1 - Read One Canonical Provider State Language (Priority: P1)

An operator can open a provider connection from provider, tenant, or system surfaces and understand separately whether the connection is operable, whether consent is present, and what verification currently proves.

Why this priority: The primary user risk is operator misread. If the product still presents multiple competing state languages, the domain remains unsafe even before any code-level cleanup is discussed.

Independent Test: Can be fully tested by seeding provider connections with canonical contradiction scenarios such as disabled with granted consent, enabled with missing consent, and enabled with blocked verification, then rendering provider, tenant, and system surfaces to verify that operators only see lifecycle, consent, and verification as the authoritative dimensions.

Acceptance Scenarios:

1. Given a connection is disabled while consent is granted and verification is successful, When an operator opens provider detail and system tenant detail, Then lifecycle shows the connection as disabled while consent and verification remain separately positive and no legacy labels appear.
2. Given a connection is enabled, consent is missing, and verification is unknown, When an operator opens provider list or tenant summaries, Then the product shows missing consent and unknown verification without substituting a legacy health or status shortcut.

---

User Story 2 - Trust Runtime Decisions Again (Priority: P1)

An operator or reviewer can trust that readiness checks, action visibility, onboarding callbacks, verification starts, and health checks all use the same canonical provider truth instead of hidden legacy gates.

Why this priority: UI cleanup alone is not enough. Runtime behavior must stop depending on removed fields or the product will remain semantically inconsistent and operationally brittle.

Independent Test: Can be fully tested by executing create, onboarding, consent, verification, health-check, and mutation flows while asserting that all reads, writes, and queries depend only on lifecycle, consent, and verification truth.

Acceptance Scenarios:

1. Given a connection is administratively disabled, When runtime gates determine whether an operation may proceed, Then that decision uses canonical lifecycle truth rather than legacy status fields.
2. Given consent callbacks, verification starts, or health checks update a connection, When the write completes, Then only canonical lifecycle, consent, and verification truth is persisted and no legacy field is written.
3. Given resolver, list, and aggregate queries run after the cleanup, When provider-state logic executes, Then there are no active filters or gates based on removed legacy status or health fields.

---

User Story 3 - Finish The Hard Cut Without Residual Tail (Priority: P2)

The product owner can release this cleanup knowing that schema, badges, filters, contracts, helpers, and tests no longer preserve a hidden compatibility layer for removed provider state.

Why this priority: The requested hard cut only succeeds if the repo no longer contains product-relevant legacy truth or a path that silently recreates it later.

Independent Test: Can be fully tested by applying the final schema, running focused regression coverage, and performing residual checks that prove legacy provider status or health truth no longer appears in runtime logic, presentation helpers, filters, factories, or tests.

Acceptance Scenarios:

1. Given the final migration has been applied, When the provider connection schema is inspected, Then the legacy status and health fields no longer exist.
2. Given provider-focused regression coverage and residual checks run, When the release is validated, Then no active badge, contract, filter, helper, query, or test depends on legacy provider status or health semantics.

Edge Cases

• A connection remains disabled even though consent is granted and the most recent verification was successful; lifecycle must stay separate from positive consent or verification truth.
• Consent can be revoked or missing while lifecycle remains enabled; the product must not translate that into a lifecycle failure.
• Verification can be unknown, degraded, error, or blocked while lifecycle remains enabled; the product must not translate that into consent truth or administrative disablement.
• The same connection must tell the same lifecycle, consent, and verification story on provider, tenant, and system surfaces even when older code previously summarized it through legacy health.
• Because this is a hard cut with no legacy preservation, missing or removed legacy fields must fail validation during implementation rather than being silently reconstructed through accessors or fallback shims.

Requirements (mandatory)

Constitution alignment (required): This feature changes existing provider-state write paths and existing provider-state reads that already participate in onboarding, consent, verification, and health-check behavior. It introduces no new Microsoft Graph endpoint family, no new provider type, and no new run family. Existing preview, confirmation, audit, tenant-isolation, and run-observability rules remain in force. The change is limited to what provider connection state is persisted, projected, queried, gated, and rendered.

Constitution alignment (PROP-001 / ABSTR-001 / PERSIST-001 / STATE-001 / BLOAT-001): The spec introduces one necessary canonical lifecycle dimension because current-release provider truth already requires a separate administrative enabled or disabled answer that neither consent nor verification can carry correctly. No new table, artifact, or abstraction layer is added. The bias is replacement before layering: remove legacy truth, keep existing consent and verification truth, and introduce only the explicit lifecycle dimension required to preserve real behavior.

Constitution alignment (OPS-UX): Existing verification and health-check runs keep their current OperationRun ownership, notification, and observability rules. This cleanup does not introduce a new run type or new progress surface. Regression coverage must prove that state cleanup does not bypass existing run ownership or reporting contracts in the flows that already use them.

Constitution alignment (RBAC-UX): This feature spans tenant/admin /admin, tenant-context admin routes under /admin/t/{tenant}/..., and platform /system read surfaces. Cross-plane access remains deny-as-not-found. Non-members or actors outside workspace or tenant entitlement remain 404. In-scope actors missing required capability remain 403. Server-side authorization for lifecycle mutations, onboarding flows, consent callbacks, and verification starts stays with the existing policy and capability registry. Provider connections remain non-globally-searchable, tenant global search behavior is unchanged and tenant-safe, and existing destructive-like actions such as disabling a connection or deleting credentials remain confirmation-gated. Coverage must include at least one positive and one negative authorization regression on touched provider-state mutations or surfaces.

Constitution alignment (OPS-EX-AUTH-001): Not applicable. Authentication handshake behavior is unchanged.

Constitution alignment (BADGE-001): Badge semantics remain centralized. The cleanup removes legacy provider status and health badge domains and leaves lifecycle, consent, and verification to be rendered through shared badge mappings rather than page-local labels or colors. Regression coverage must prevent legacy badge domains or ad-hoc provider-state mappings from reappearing.

Constitution alignment (UI-FIL-001): Existing Filament tables, infolists, sections, filters, and shared provider-state primitives remain the presentation base. The cleanup must avoid local replacement markup or page-local status color systems. No exception is expected.

Constitution alignment (UI-NAMING-001): Operator-facing vocabulary must consistently use Lifecycle, Consent, and Verification when describing provider connection state. Existing verbs such as Enable connection, Disable connection, Grant admin consent, Start verification, and Check connection remain acceptable because they correspond to one dimension each. Surfaces must not expose labels such as Legacy status, Legacy health, Diagnostic status, or Diagnostic health as active product language.

Constitution alignment (UI-CONST-001 / UI-SURF-001 / UI-HARD-001 / UI-EX-001 / UI-REVIEW-001): The affected surfaces remain list-first provider and tenant resources, detail-first provider and tenant pages, and read-only platform directory pages. Each surface keeps one primary inspect model, existing secondary actions stay in their current regions, destructive actions stay secondary, routes stay canonical, and the critical default-visible truth becomes lifecycle, consent, and verification only.

Constitution alignment (OPSURF-001): Default-visible content must stay operator-first and avoid raw implementation detail. Diagnostics remain secondary and explicitly subordinate to the three canonical dimensions. No new mutation scope is introduced; existing actions continue to communicate whether they affect TenantPilot state, Microsoft tenant state, or both, and their safe-execution pattern remains unchanged.

Constitution alignment (UI-SEM-001 / LAYER-001 / TEST-TRUTH-001): Direct mapping from canonical lifecycle, consent, and verification truth to UI is sufficient once the legacy layer is removed. The feature must not introduce a new presenter framework, shadow diagnostics truth, or compatibility wrapper. Tests focus on business consequences: what operators see, what runtime paths decide, and what persistence shape remains.

Constitution alignment (Filament Action Surfaces): The Action Surface Contract remains satisfied. Affected admin surfaces keep one primary inspect model, no redundant View actions are added, no empty action groups are introduced, and destructive-like actions retain their required placement and confirmation rules. UI-FIL-001 is satisfied with no approved exception.

Constitution alignment (Global Search / Rendering Safety): TenantResource global search remains tenant-safe and unchanged, ProviderConnectionResource remains non-globally-searchable, and touched provider, tenant, and system surfaces must preserve DB-only rendering without introducing per-row remote calls. Coverage must include explicit search-safety and DB-only regressions for touched resources and summaries.

Constitution alignment (UX-001 — Layout & Information Architecture): No new screen type is introduced. Existing provider list screens retain search, sort, and canonical filters. Detail pages continue to use view-first patterns and infolist-style status presentation. Edit pages continue to use structured form sections and save/cancel actions. Empty states remain specific and single-CTA where they already exist. The required change is that state presentation and core filters align to lifecycle, consent, and verification rather than legacy provider status or health.

Hard-Cutover Assumptions

• No relevant existing data requires preserving after cutover. A one-time migration backfill may translate legacy status = disabled into is_enabled = false, but legacy provider status and health values do not remain active product truth.
• No dual-read, dual-write, compatibility accessor, compatibility mutator, or fallback shim is allowed.
• Runtime readers and writers must be fully moved to canonical lifecycle, consent, and verification before legacy columns are removed.
• Administrative lifecycle must remain explicit and must not be hidden inside consent or verification semantics.

Functional Requirements

• FR-188-001: Provider connection state MUST be expressed through exactly three business dimensions: lifecycle, consent, and verification.
• FR-188-002: Lifecycle MUST have one explicit canonical truth on the provider connection record and MUST carry the current administrative enabled or disabled semantics that do not belong to consent or verification.
• FR-188-003: Consent truth MUST rely only on consent_status and MUST NOT inherit lifecycle or legacy status semantics.
• FR-188-004: Verification truth MUST rely only on verification_status and MUST NOT inherit lifecycle or legacy health semantics.
• FR-188-005: The legacy provider connection fields status and health_status MUST be removed from the active domain model, the persisted schema, and any compatibility layer.
• FR-188-006: No accessor, mutator, cast, fallback, projection shim, or presentation shim may simulate removed legacy provider fields after cutover.
• FR-188-007: Shared provider-state outputs and projections MUST return only lifecycle, consent, and verification information and MUST exclude legacy fields.
• FR-188-008: Resolver decisions, readiness checks, action visibility, operator guidance, and aggregate logic MUST use only lifecycle, consent, and verification truth.
• FR-188-009: No active product query may filter, aggregate, or gate on legacy provider status or legacy provider health.
• FR-188-010: Create flows, onboarding flows, consent callbacks, verification starts, health checks, mutation services, and similar write paths MUST persist only canonical truth and MUST NOT dual-write legacy fields.
• FR-188-011: Health and verification contracts MUST carry only the information needed to derive canonical consent and verification truth plus supporting diagnostics, and MUST drop vocabulary whose sole purpose was legacy persistence or legacy display. Lifecycle remains explicit record truth via is_enabled and MUST NOT be derived from health-check transport.
• FR-188-012: Operator-facing provider, tenant, and system surfaces MUST remove legacy status and health fields, labels, hidden entries, toggles, and filters and MUST display one consistent canonical state language.
• FR-188-013: Diagnostics MAY show supporting facts such as recency, errors, or next steps, but they MUST NOT create a second competing provider truth model.
• FR-188-014: Shared badge and mapping layers MUST retire legacy provider status and health domains and present only canonical lifecycle, consent, and verification states through centralized mappings.
• FR-188-015: Tenant-facing, provider-facing, and system-facing views of the same connection MUST remain semantically aligned and show the same lifecycle, consent, and verification truth.
• FR-188-016: Disabled or enabled behavior MUST remain intact through the canonical lifecycle dimension and MUST NOT be reinterpreted as consent granted or denied or as verification healthy or unhealthy.
• FR-188-017: Factories, helpers, regression scaffolds, and automated tests MUST stop setting, asserting, or filtering on legacy provider status or health truth.
• FR-188-018: The cutover MUST complete in ordered phases: lifecycle foundation and 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.
• FR-188-021: Touched provider, tenant, and system surfaces MUST preserve DB-only rendering and MUST NOT introduce new per-row remote calls while the canonical lifecycle, consent, and verification state is adopted.
• FR-188-019: Existing provider lifecycle and credential mutations MUST keep their current server-side authorization, confirmation, and audit behavior while evaluating eligibility from canonical lifecycle, consent, and verification only.
• FR-188-020: The release is not complete unless release validation shows zero active runtime, UI, badge, contract, query, helper, test, or schema coupling to legacy provider status or health semantics.

UI Action Matrix (mandatory when Filament is changed)

Surface	Location	Header Actions	Inspect Affordance (List/Table)	Row Actions (max 2 visible)	Bulk Actions (grouped)	Empty-State CTA(s)	View Header Actions	Create/Edit Save+Cancel	Audit log?	Notes / Exemptions
Provider connections list	/admin/provider-connections	New connection	Clickable row to provider detail	Existing More actions remain; no new primary row mutation is introduced	none	Existing New connection CTA remains	n/a	n/a	existing only	Action Surface Contract remains satisfied. Default-visible columns and filters change to canonical lifecycle, consent, and verification. Legacy provider status and health filters are removed.
Provider connection detail	/admin/provider-connections/{record}	No new header action labels; existing grouped actions remain	Dedicated detail page	n/a	none	n/a	Existing grouped actions such as Grant admin consent, Edit, Check connection, and View last check run remain	n/a	existing only	Detail presentation removes legacy entries and shows lifecycle, consent, and verification as separate truths.
Provider connection edit	/admin/provider-connections/{record}/edit	No new header action labels	Dedicated edit page	n/a	none	n/a	Existing grouped lifecycle and credential actions remain secondary	Save and Cancel remain unchanged	existing only	Edit context may show canonical truth for operator context, but not legacy fields or legacy filters.
Tenant list	/admin/tenants	Existing tenant entry and onboarding actions remain unchanged	Clickable row to tenant detail	Existing helper and workflow actions remain secondary	Existing grouped tenant bulk actions remain unchanged	Existing empty-state CTA remains unchanged	n/a	n/a	existing only	Any provider-state summary or filter on the list must derive from canonical lifecycle, consent, and verification only.
Tenant detail and tenant-context admin provider summaries	/admin/tenants/{tenant} and existing /admin/t/{tenant}/... routes	No new action labels required	Dedicated tenant page or tenant-context page	n/a	none added by this spec	n/a	Existing tenant and provider navigation actions remain unchanged	Existing save/cancel behavior remains unchanged where edit exists	existing only	Shared provider-state entries, onboarding guidance, and provider summaries remove legacy status or health semantics and keep the three canonical dimensions distinct.
System tenant directory list	/system/directory/tenants	none	Clickable row to system tenant detail	none	none	Existing empty-state guidance remains	n/a	n/a	no new audit event	Read-only system directory. Any summary health signal must stop depending on legacy provider status or health.
System tenant detail	/system/directory/tenants/{tenant}	none	Dedicated detail page	none	none	n/a	Existing read-only navigation links remain if already present	n/a	no new audit event	Provider rows must use canonical lifecycle, consent, and verification only and must align with admin-plane truth.

Key Entities (include if feature involves data)

• Provider connection lifecycle truth: The canonical answer to whether the connection is administratively operable or intentionally disabled.
• Provider connection consent truth: The canonical answer to whether required consent is present, missing, revoked, or otherwise not satisfied.
• Provider connection verification truth: The canonical answer to what the latest verification currently proves, such as healthy, unknown, degraded, error, or blocked.
• Provider connection state projection: The derived state representation consumed by queries and surfaces that must mirror only lifecycle, consent, and verification truth without introducing an extra status layer.
• Provider diagnostics: Supporting information such as timestamps, errors, or next-step guidance that may help interpretation but must not become a fourth truth dimension.

Success Criteria (mandatory)

Measurable Outcomes

• SC-188-001: Release validation shows 100% of targeted provider, tenant, and system surfaces using lifecycle, consent, and verification language only, with zero visible legacy provider status or health labels.
• SC-188-002: In contradictory seeded scenarios, 100% of targeted surfaces let operators distinguish lifecycle, consent, and verification without one dimension being implied by another.
• SC-188-003: All targeted create, onboarding, consent, verification, health-check, and mutation flows complete release validation without reading, writing, or querying legacy provider status or health fields.
• SC-188-004: Final release validation confirms the provider connection record shape contains one explicit lifecycle truth alongside consent and verification truth and no longer contains legacy provider status or health fields.
• SC-188-005: Residual checks and focused regression coverage report zero active badge, contract, filter, helper, factory, or test paths that reintroduce legacy provider status or health semantics.
• SC-188-006: In cross-surface comparison validation, 100% of admin and system views of the same provider connection show the same lifecycle, consent, and verification story.
• SC-188-007: TenantResource global search remains tenant-safe, ProviderConnectionResource remains excluded from global search, and touched provider, tenant, and system surfaces retain DB-only rendering guarantees after the cleanup.

Assumptions

• There are no relevant historic or production data obligations that require preserving or interpreting legacy provider status or health values after cutover.
• Existing consent and verification truth is already authoritative enough to remain the canonical truth for those dimensions.
• Existing enabled or disabled behavior is real product behavior and must survive as explicit lifecycle truth rather than being collapsed into consent or verification.
• Existing authorization, audit, and run-observability behavior remains authoritative; this spec changes the provider-state model and dependent behavior, not the surrounding security model.

Non-Goals

• General provider-registry redesign
• A new diagnostics score or replacement health score
• Historical legacy-data support, backfill, or compatibility reads
• A broader credential redesign beyond what the provider-state cleanup requires
• Dashboard, portfolio, or onboarding redesign outside the touched provider-state surfaces
• Changes in other domains that do not directly depend on provider connection state truth

Dependencies

• Existing provider connection records and tenant scoping remain the canonical persistence base for provider-state truth.
• Existing consent, onboarding, verification, and health-check flows remain the producers of canonical provider-state updates.
• Existing centralized badge and shared provider-state presentation helpers remain the single presentation layer after legacy badge domains are removed.
• Existing admin-plane provider and tenant surfaces and existing system directory surfaces remain the operator-facing consumers that must stay aligned.
• Focused regression coverage across runtime truth, UI truth, badge semantics, contracts, schema, and authorization remains required to keep the cleanup from regressing.

Definition of Done

• Legacy provider status and health_status fields are absent from the provider connection schema and active domain model.
• One explicit lifecycle truth exists beside consent and verification truth.
• Consent is modeled only through consent_status.
• Verification is modeled only through verification_status.
• No runtime decision reads legacy provider status or health fields.
• No runtime write persists legacy provider status or health fields.
• Shared provider-state outputs, contracts, badges, filters, and operator surfaces use only lifecycle, consent, and verification truth.
• Tenant, provider, and system surfaces show the same canonical provider-state language.
• Tests, factories, and helpers no longer set or expect legacy provider status or health truth.
• Residual validation finds no active runtime, UI, badge, contract, query, helper, test, or schema coupling to legacy provider status or health semantics.