TenantAtlas/specs/139-verify-access-permissions-assist/data-model.md

Data Model — Spec 139 (Verify Access Required Permissions Assist)

Existing persisted entities reused

TenantOnboardingSession (existing)

• Source: app/Models/TenantOnboardingSession.php
• Role in this feature:
  • Anchors the current onboarding draft and current wizard step.
  • Holds the selected provider connection and latest verification run reference in state.
• Relevant persisted state:
  • tenant_id
  • current_step
  • state.provider_connection_id
  • state.verification_operation_run_id

OperationRun (existing)

• Source: app/Models/OperationRun.php
• Role in this feature:
  • Supplies the latest stored verification result used by Verify Access.
  • Remains the source of truth for the existing verification report.
• Relevant persisted context:
  • context.provider_connection_id
  • context.target_scope
  • context.verification_report

TenantPermission dataset (existing)

• Source: tenant_permissions via TenantPermissionService::compare(... persist: false, liveCheck: false)
• Role in this feature:
  • Supplies the current DB-only permission diagnostics summary and missing-permission breakdown used by the assist and full page.

Computed view models

VerificationAssistVisibility (computed)

• Purpose: determines whether the Verify Access step should expose View required permissions.
• Inputs:
  • Stored verification report overall/check state.
  • Existing permission diagnostics summary.
  • Stale verification context for the selected provider connection.
• Shape:
  • is_visible: bool
  • reason: 'permission_blocked' | 'permission_attention' | 'hidden_ready' | 'hidden_irrelevant'

VerificationAssistViewModel (computed)

• Purpose: compact payload rendered inside the slideover.
• Derived from:
  • verificationReportViewData() output
  • TenantRequiredPermissionsViewModelBuilder::build($tenant, ...)
• Shape:
  • tenant: { id: int, external_id: string, name: string }
  • verification: { overall: string|null, status: string|null, is_stale: bool, stale_reason: string|null }
  • overview: { overall: string, counts: { missing_application: int, missing_delegated: int, present: int, error: int }, freshness: { last_refreshed_at: string|null, is_stale: bool } }
  • missing_permissions: { application: PermissionRow[], delegated: PermissionRow[] }
  • copy: { application: string, delegated: string }
  • actions: AssistActions
  • fallback: { has_incomplete_detail: bool, message: string|null }

PermissionRow (existing computed shape reused)

• Source: TenantRequiredPermissionsViewModelBuilder
• Shape:
  • key: string
  • type: 'application' | 'delegated'
  • description: string|null
  • features: string[]
  • status: 'granted' | 'missing' | 'error'
  • details: array|null

AssistActions (computed)

• Purpose: explicit, authorization-safe actions shown in the slideover.
• Shape:
  • full_page: { label: string, url: string, opens_in_new_tab: true, is_secondary: true }
  • copy_application: { label: string, payload: string, available: bool }
  • copy_delegated: { label: string, payload: string, available: bool }
  • grant_admin_consent: { label: string, url: string|null, opens_in_new_tab: bool, available: bool }
  • manage_provider_connection: { label: string, url: string|null, opens_in_new_tab: bool, available: bool }
  • rerun_verification: { label: string, handled_by_existing_wizard: true }

VerificationLinkBehavior (computed)

• Purpose: normalize how Verify Access next-step links are rendered.
• Shape:
  • label: string
  • url: string
  • kind: 'external' | 'internal-diagnostic' | 'internal-inline-safe'
  • opens_in_new_tab: bool
  • show_new_tab_hint: bool

State transitions

Assist visibility transition

• Hidden → Visible when:
  • verification report indicates permission-related blockers or relevant needs-attention state, and
  • the current user remains authorized for the underlying tenant context.
• Visible → Hidden when:
  • verification becomes fully ready with no relevant permission guidance, or
  • authorization context no longer permits the assist.

Wizard continuity invariant

• Opening the assist does not change TenantOnboardingSession.current_step.
• Closing the assist does not mutate onboarding draft state.
• Opening the full page from the assist does not navigate the current onboarding tab away from the wizard.

Copy-action availability invariant

• A copy action is available only when the corresponding copy.* payload is a non-empty string.
• Empty payloads result in omitted or replaced controls, not broken actions.

Authorization model reuse

• Onboarding wizard access continues to depend on workspace membership plus onboarding capability rules.
• Required Permissions deep-dive access continues to depend on tenant entitlement and existing page authorization.
• The assist is visible only when both contexts are valid enough to avoid leaking tenant or permission detail.

No persistence changes

• No new tables.
• No new route-backed models.
• No new onboarding-only permissions store.
• No mutation to the existing Required Permissions page role.