# Data Model: Operation Run Active-State Visibility & Stale Escalation

## Overview

This feature introduces no new persisted entity, table, or stored projection. It formalizes one derived active-state presentation contract over existing `OperationRun` lifecycle truth so tenant and workspace monitoring surfaces present the same meaning.

## Source Entity: OperationRun

- **Purpose**: Canonical lifecycle and outcome record for long-running admin-plane work.
- **Existing fields used by this feature**:
  - `id`
  - `workspace_id`
  - `tenant_id`
  - `type`
  - `status`
  - `outcome`
  - `created_at`
  - `started_at`
  - `completed_at`
  - `context`
  - `failure_summary`
- **Existing relationships used by this feature**:
  - `tenant`
  - `user` where available for initiator context
- **Existing invariants**:
  - Lifecycle status and outcome remain service-owned.
  - Reconciliation metadata stays inside `context.reconciliation`.
  - No new persisted status or outcome values are introduced for visibility purposes.

## Derived Truth: OperationRunFreshnessState

- **Type**: Existing enum `App\Support\Operations\OperationRunFreshnessState`
- **Values**:
  - `fresh_active`
  - `likely_stale`
  - `reconciled_failed`
  - `terminal_normal`
  - `unknown`
- **Inputs**:
  - `status`
  - `created_at`
  - `started_at`
  - `context.reconciliation`
  - existing `OperationLifecyclePolicy`
- **Behavioral rule**:
  - This remains the only stale/late truth input for surface rendering.
  - No widget, page, or Livewire component may introduce its own threshold logic.

## Derived Truth: OperationRun Problem Class

- **Type**: Existing derived string on `OperationRun`
- **Values**:
  - `none`
  - `active_stale_attention`
  - `terminal_follow_up`
- **Purpose**:
  - Separates active stale attention from terminal follow-up while keeping both distinct from calm/no-action runs.
- **Relationship to freshness**:
  - `likely_stale` freshness yields `active_stale_attention`.
  - `reconciled_failed` freshness yields `terminal_follow_up`.
  - Completed blocked/partial/failed runs may also yield `terminal_follow_up` without stale lineage.

## Derived View Model: Active-State Presentation Contract

- **Type**: Derived, request-scoped presentation payload. Prefer reuse of `OperationUxPresenter::decisionZoneTruth()` and existing badge/presenter outputs before adding any new helper.
- **Required fields across covered surfaces**:
  - `freshness_state`
  - `problem_class`
  - `is_currently_active`
  - `is_reconciled`
  - `compact_label`
  - `diagnostic_label`
  - `guidance`
  - `stale_lineage_note`
  - `show_in_active_progress`
  - `keep_active_polling`
- **Presentation categories**:
  - `healthy_active`
  - `past_expected_lifecycle`
  - `likely_stale`
  - `no_longer_active`
  - `unknown` fallback
- **Category mapping rules**:
  - `fresh_active` + active run -> `healthy_active`
  - `likely_stale` on compact summary surfaces -> `past_expected_lifecycle`
  - `likely_stale` on canonical or stronger diagnostic surfaces -> `likely_stale`
  - `terminal_normal` or `reconciled_failed` -> `no_longer_active`
  - `unknown` -> fallback copy without false stale escalation
- **Important constraint**:
  - `past_expected_lifecycle` and `likely_stale` are density variants over the same stale truth, not separate persisted states.

## Derived Surface Policy: Tenant Active Progress Visibility

- **Current consumers**:
  - `App\Livewire\BulkOperationProgress`
  - `App\Support\OpsUx\ActiveRuns`
- **Former issue**:
  - Both used `healthyActive()` and therefore suppressed stale-active runs from the tenant progress overlay and polling decision.
- **Implemented rule**:
  - Fresh and stale active runs remain visible as active work.
  - Terminal runs disappear on the next refresh cycle.
  - Polling continues while any visible active work remains, including stale-active runs.
  - Overlay rendering uses the existing status badge and `OperationUxPresenter` guidance path so stale-active elevation stays derived from shared freshness truth.

## Covered Surface Consumers

| Consumer | Current Truth Inputs | Required Change |
|---|---|---|
| `BulkOperationProgress` | Active run query, `healthyActive()`, `ActiveRuns` | Include stale-active work in visibility and polling semantics while keeping terminal runs excluded |
| `RecentOperationsSummary` | Raw recent runs for tenant | Ensure active-state emphasis and copy stay aligned with canonical freshness meaning |
| `Dashboard\RecentOperations` | Badge rendering + `OperationUxPresenter` | Preserve and tighten existing freshness-aware row semantics |
| `Dashboard\NeedsAttention` / `DashboardKpis` | Problem-class counts + links | Keep stale-active counts and linked monitoring semantics aligned |
| `WorkspaceOverviewBuilder` / `WorkspaceRecentOperations` | Badge rendering + `OperationUxPresenter` | Preserve workspace summary consistency and diagnostic separation |
| `OperationRunResource` | Status/outcome badges + lifecycle summaries | Keep canonical list/detail authoritative and consistent with compact surfaces |
| `TenantlessOperationRunViewer` | Canonical detail page around resource truth | Preserve diagnostic-first explanation of stale versus terminal meaning |

## State Transitions Relevant To This Feature

1. `queued` or `running` within lifecycle threshold
   - Freshness: `fresh_active`
   - Presentation: `healthy_active`
   - Visible on active-only compact surfaces: yes

2. `queued` or `running` beyond lifecycle threshold
   - Freshness: `likely_stale`
   - Presentation: `past_expected_lifecycle` on compact surfaces, `likely_stale` on diagnostic surfaces
   - Visible on active-only compact surfaces: yes

3. `completed` without reconciliation
   - Freshness: `terminal_normal`
   - Presentation: `no_longer_active`
   - Visible on active-only compact surfaces: no

4. `completed` with reconciliation metadata
   - Freshness: `reconciled_failed`
   - Presentation: `no_longer_active` with stale-lineage diagnostics
   - Visible on active-only compact surfaces: no

## Validation Rules And Invariants

- No new `OperationRun.status` or `OperationRun.outcome` values may be added.
- No new persisted `operation_runs` summary or mirror table may be added.
- All stale/late meaning must derive from existing freshness truth.
- Tenant-scoped surfaces must only reflect runs already visible to the current tenant-entitled operator.
- Workspace summaries must stay limited to entitled tenant slices.
- Healthy queued/running work must not inherit stale emphasis.
- Terminal runs must stop appearing in active-only surfaces on the next refresh cycle.