# Data Model: Deferred Operator Surfaces Retrofit

## Overview

This feature introduces no new persisted entity, no new table, and no new state family. It reuses existing `OperationRun` truth plus existing tenant-detail and onboarding presentation state to enforce clearer CTA hierarchy and scope signals.

## Entity: OperationRun

- **Type**: Existing persisted model
- **Purpose in this feature**: Canonical record whose existing admin-plane collection/detail routes remain the inspect targets for tenant-detail and onboarding embedded surfaces.

### Relevant Fields

| Field | Type | Notes |
|-------|------|-------|
| `id` | integer | Existing operation identifier used by embedded links and labels. |
| `type` | string | Continues to determine the operation label and UX guidance. |
| `workspace_id` | integer nullable | Preserves workspace-context routing and entitlement checks. |
| `tenant_id` | integer nullable | Preserves tenant-context entitlement and embedded-surface filtering. |
| `status` | string | Drives whether the current run is still active. |
| `outcome` | string | Drives blocked/failed/succeeded summary presentation. |
| `context` | array/json | Already carries target-scope, verification-report, and next-step metadata used by the affected surfaces. |
| `created_at` | timestamp | Used for recency display on recent-operations surfaces. |
| `started_at` / `completed_at` | timestamp nullable | Used for in-progress vs completed display and technical details. |

### Relationships

| Relationship | Target | Purpose |
|--------------|--------|---------|
| `tenant` | `Tenant` | Keeps tenant entitlement and tenant detail context explicit. |
| `workspace` | `Workspace` | Preserves workspace-context authorization for onboarding and admin viewers. |
| `initiator` | `User` / platform initiator context | Remains unchanged; no notification or lifecycle behavior changes in this feature. |

### Feature-Specific Invariants

- `/admin/operations` and `/admin/operations/{run}` remain the canonical collection/detail destinations.
- No new `OperationRun` type, state transition, notification timing, or summary-count behavior is introduced.
- Embedded surfaces may change CTA hierarchy and nearby scope copy, but not the underlying destination semantics.

### State Transitions Used By This Feature

| Transition | Preconditions | Result |
|------------|---------------|--------|
| Render inspect link for existing record | A covered surface already has a current `OperationRun` reference | No state change; surface exposes a single primary inspect path for that record. |
| Render workflow-start action | Covered surface has no current `OperationRun` reference and the operator can start the workflow | No state change; surface exposes one next-step CTA such as `Start verification`. |

## Derived Surface State: Tenant Detail Recent Operations Summary

- **Type**: Existing derived widget state, not persisted
- **Sources**:
  - `app/Filament/Resources/TenantResource/Pages/ViewTenant.php`
  - `app/Filament/Widgets/Tenant/RecentOperationsSummary.php`
  - `resources/views/filament/widgets/tenant/recent-operations-summary.blade.php`
  - `app/Support/OperationRunLinks.php`

### Relevant Fields

| Field | Type | Purpose |
|-------|------|---------|
| `tenant` | `Tenant` | Provides the current tenant context for filtering and copy. |
| `runs` | collection of `OperationRun` | Existing recent operation records rendered in the embedded summary. |
| `operationsIndexUrl` | string | Existing admin-plane collection destination. |
| `rowOperationUrl` | string derived | Existing admin-plane detail destination per rendered run. |
| `hasRuns` | boolean derived | Distinguishes empty vs populated summary state. |

### Feature-Specific Invariants

- Row-level `Open operation` remains the primary inspect affordance for displayed records.
- Any collection drill-in that remains visible is secondary and must make the broader admin scope explicit through placement or nearby helper text.
- The table-based recent-operations widget on `/admin/t/{tenant}` remains out of scope for this model.

### State Rules

| State | Preconditions | Primary CTA | Secondary CTA |
|-------|---------------|-------------|---------------|
| Empty summary | `runs` is empty | None or a single next-step/collection affordance if retained | Admin-scope collection link only if clearly secondary |
| Populated summary | `runs` is not empty | Per-row `Open operation` for each visible record | One secondary collection affordance at most |

## Derived Surface State: Tenant Verification Widget

- **Type**: Existing derived widget state, not persisted
- **Sources**:
  - `app/Filament/Resources/TenantResource/Pages/ViewTenant.php`
  - `app/Filament/Widgets/Tenant/TenantVerificationReport.php`
  - `resources/views/filament/widgets/tenant/tenant-verification-report.blade.php`

### Relevant Fields

| Field | Type | Purpose |
|-------|------|---------|
| `run` | `OperationRun` nullable | Current verification-backed operation, if one exists. |
| `runUrl` | string nullable | Canonical inspect path for the current run. |
| `report` | array nullable | Stored verification report payload displayed read-only. |
| `isInProgress` | boolean | Distinguishes active vs completed run state. |
| `showStartAction` | boolean | Whether the embedded surface may expose a workflow-start CTA in empty-state conditions. |
| `canStart` | boolean | Whether the current actor can start verification. |
| `startTooltip` | string nullable | Existing permission helper text for disabled start states. |
| `lifecycleNotice` | string nullable | Existing archived/inactive-tenant explanation when starting work is not allowed. |

### Feature-Specific Invariants

- When no run exists and the tenant can be operated, the widget exposes one primary `Start verification` CTA.
- When a run exists, the widget exposes one primary inspect CTA for that run and does not compete with an inline rerun CTA.
- The existing tenant-detail header action remains the rerun/start path when the page still needs one outside the embedded widget.
- Archived or inoperable tenants may show explanation text, but no new inspect or start path is introduced by this feature.

### State Matrix

| State | Preconditions | Primary CTA | Secondary Inline CTA |
|-------|---------------|-------------|----------------------|
| No run / start allowed | `run` is null and `showStartAction && canStart` | `Start verification` | None |
| No run / cannot start | `run` is null and `! canStart` | None | None |
| Active run | `run` exists and `isInProgress` | `Open operation` | None |
| Completed or stale run | `run` exists and `! isInProgress` | `Open operation` | None |
| Archived / inactive tenant | `showStartAction` is false and `lifecycleNotice` is present | None | None |

## Derived Surface State: Onboarding Verification Surface

- **Type**: Existing guided-flow report state, not persisted
- **Sources**:
  - `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php`
  - `resources/views/filament/forms/components/managed-tenant-onboarding-verification-report.blade.php`
  - `resources/views/filament/modals/onboarding-verification-technical-details.blade.php`
  - `managed_tenant_onboarding_sessions.state[verification_operation_run_id]`

### Relevant Fields

| Field | Type | Purpose |
|-------|------|---------|
| `verification_operation_run_id` | integer nullable | Existing onboarding-session pointer to the current verification run. |
| `run` | array nullable | Read-only operation data rendered in the onboarding report. |
| `runUrl` | string nullable | Canonical inspect path for the current run. |
| `previousRunUrl` | string nullable | Secondary link to the previously relevant run, when retained. |
| `report` | array nullable | Stored verification report payload rendered in the onboarding step. |
| `workflowPrimaryAction` | derived string nullable | Existing step-level CTA such as `Start verification` or `Refresh`. |
| `technicalDetailsVisible` | boolean derived | Controls whether advanced monitoring/context affordances are available. |

### Feature-Specific Invariants

- The wizard step owns workflow-next-step controls such as `Start verification` and `Refresh`.
- The embedded report/technical-details surfaces may expose one inspect CTA for the current run, but previous-run and monitoring links remain diagnostics-secondary only.
- Any advanced monitoring/admin destination is visible only when the destination is legitimate for the current operator and remains explicitly labeled as advanced.
- No new onboarding state, session field, or workflow branch is introduced.

### State Matrix

| State | Preconditions | Workflow CTA | Inspect CTA | Diagnostics CTA |
|-------|---------------|--------------|-------------|-----------------|
| No run | onboarding session has no current verification run | `Start verification` | None | None |
| Active run | current verification run exists and is not completed | `Refresh` | One current-run inspect link if retained on the report surface | Advanced monitoring only in technical details |
| Completed run | current verification run exists and is completed | None or existing step progression controls | One current-run inspect link | Previous-run and monitoring links remain secondary |

## Governance Artifact: Deferred Surface Exemption And Conformance Coverage

- **Type**: Existing registry and test coverage, not persisted
- **Sources**:
  - `app/Support/Ui/ActionSurface/ActionSurfaceExemptions.php`
  - `tests/Feature/Guards/ActionSurfaceContractTest.php`
  - focused widget/onboarding feature tests listed in the plan

### Relevant Fields

| Field | Type | Purpose |
|-------|------|---------|
| `className` | string | Exempted page/component class still outside declaration-backed discovery. |
| `reason` | string | Concrete justification for the current exemption. |
| `focusedTests` | derived list | Dedicated conformance coverage that protects the exempted surface behavior. |

### Feature-Specific Invariants

- `ManagedTenantOnboardingWizard` may remain baseline-exempt if the reason continues to point to dedicated conformance tests.
- This feature does not introduce a new widget declaration system or a new validator mode.
- Governance for the retrofitted surfaces should become narrower and more explicit, not broader.

## Persistence Impact

- **Schema changes**: None
- **Data migration**: None
- **New indexes**: None
- **Retention impact**: None