TenantAtlas/specs/353-provider-connections-resolution-guidance-v1/contracts/provider-readiness-signal-map.md

# Provider Readiness Signal Map: Spec 353

## Purpose

Inventory the existing repo-backed signals that can feed Provider Connections Resolution Guidance v1 without adding new provider truth or live render-time calls.

## Signal Inventory

| Signal | Source file / class | Repo-backed? | Scope | Current UI consumer | Possible guidance case | Possible action | Mutating? | Capability / audit / OperationRun behavior |
|---|---|---|---|---|---|---|---|---|
| No provider connection | `ManagedEnvironmentResource::providerConnectionState()`, `ProviderConnectionResolver`-adjacent usage, provider-connection queries | yes | environment -> workspace | dashboard/provider state helpers, create/list empty-state paths | `provider.connection_missing` | Open Provider Connections | no | navigation only; existing surface auth stays authoritative |
| Connection disabled | `ProviderConnection.is_enabled`, `ProviderConnectionSurfaceSummary::readinessSummary()` | yes | record | Provider Connections list/detail, provider-state helper | `provider.connection_disabled` | Open Provider Connection | no | existing enable/disable mutations are confirmed, audited, capability-gated |
| Consent not granted / required / failed / revoked | `ProviderConnection.consent_status`, `RequiredPermissionsLinks::adminConsentPrimaryUrl()`, `ProviderReasonTranslator` | yes | record + environment | Provider Connections, Required Permissions, blocked verification reports | `provider.admin_consent_required` | Grant admin consent / open required permissions | no | existing consent navigation only; no inline mutation |
| Verification status unknown / pending / healthy / degraded / blocked / error | `ProviderConnection.verification_status`, `ProviderVerificationStatus`, `ProviderConnectionSurfaceSummary` | yes | record | Provider Connections, dashboard readiness cards | `provider.verification_required`, `provider.verification_failed`, `provider.ready` | Run verification / open last check run | no | existing run start uses `StartVerification` + `OperationRun` |
| Last check timestamp | `ProviderConnection.last_health_check_at` | yes | record | Provider Connections list/detail | stale / recently checked nuance | Open last check run or re-run verification | no | proof-only; no mutation |
| Last error reason code | `ProviderConnection.last_error_reason_code`, `ProviderReasonTranslator` | yes | record | Provider Connections diagnostics, verification reports | consent missing, credential missing, permission missing, auth failed, etc. | Open required permissions / provider connection / re-run verification | no | translated to next-step options; existing proof links only |
| Last error message (sanitized) | `ProviderConnection.last_error_message`, sanitizers in resource | yes | record | Provider Connections diagnostics | secondary detail only | none primary; open proof if needed | no | must stay secondary and redacted |
| Provider capability groups | `ManagedEnvironmentRequiredPermissionsViewModelBuilder::deriveCapabilityGroups()` | yes | environment | Required Permissions summary/cards | capability missing / at risk / supported | Open required permissions / re-run verification | no | derived from stored permission comparison |
| Primary capability group | `ManagedEnvironmentRequiredPermissionsViewModelBuilder::primaryCapabilityGroup()` | yes | environment | Required Permissions summary | dominant missing capability | Review permissions / re-run verification | no | derived only |
| Missing application permission count | `ManagedEnvironmentRequiredPermissionsViewModelBuilder::deriveCounts()` | yes | environment | Required Permissions summary/issues, dashboard required-permissions action | `provider.required_permissions_missing` | Open required permissions / admin consent | no | derived only |
| Missing delegated permission count | `ManagedEnvironmentRequiredPermissionsViewModelBuilder::deriveCounts()` | yes | environment | Required Permissions summary/issues, dashboard delegated-permissions action | `provider.delegated_permissions_missing` | Open required permissions / re-run verification | no | derived only |
| Freshness / stale permission evidence | `ManagedEnvironmentRequiredPermissionsViewModelBuilder::deriveFreshness()` | yes | environment | Required Permissions summary/issues | `provider.verification_stale` | Start / re-run verification | no | derived from stored timestamps only |
| Overall permission posture | `ManagedEnvironmentRequiredPermissionsViewModelBuilder::deriveOverallStatus()` | yes | environment | Required Permissions badge | blocked / needs attention / ready | route to dominant provider action | no | derived only |
| Existing dashboard provider blocker | `EnvironmentDashboardSummaryBuilder::providerOperatorGuidance()` | yes | environment | Environment Dashboard | continuity source only | Open required permissions | no | current dashboard selection layer only |
| Last provider verification run | `OperationRun` rows of type `provider.connection.check`, `EditProviderConnection::view_last_check_run` | yes | environment + record | Edit Provider Connection, verification reports | `provider.verification_failed` / proof continuity | Open last check run | no | existing proof-only deep link |
| Verification run start | `StartVerification`, `ProviderOperationStartResultPresenter` | yes | environment + record | existing provider actions | `provider.verification_required` | Run verification | yes | capability-gated, queued/deduped/blocked via existing `OperationRun` contract |
| Required Permissions route and admin-consent URL | `RequiredPermissionsLinks` | yes | environment | dashboard/provider/detail links | permissions blocker remediation | Open required permissions / open admin consent | no | link-only helper; no render-time remote call should be introduced |

## Observed Gaps To Avoid Inventing Around

- There is no single repo-real `ProviderReadinessPresenter` yet.
- There is no repo-real standalone Required Permissions page-report file today.
- There is no repo-real dedicated provider-health page class to reuse.

These are implementation-shape gaps, not reasons to create new provider truth.

## Guidance-Shaping Rules Derived From The Map

1. Prefer stored counts, statuses, capability groups, freshness, and last-run proof over raw diagnostic detail.
2. Use `ProviderReasonTranslator` and `VerificationLinkBehavior` for safe next-step phrasing before adding another local mapping table.
3. Treat admin-consent navigation and verification-run start as existing safe actions; do not invent auto-remediation.
4. Keep raw permission rows, copy payloads, and sanitized error messages secondary.
5. Keep the guidance request-scoped and DB-local.