TenantAtlas/specs/178-ops-truth-alignment/data-model.md

# Phase 1 Data Model: Operations Lifecycle Alignment & Cross-Surface Truth Consistency

## Overview

This feature does not add a table, persisted summary entity, or new lifecycle state machine. It aligns existing `OperationRun` truth and existing freshness/reconciliation semantics across multiple operator surfaces by introducing a small set of derived cross-surface contracts.

The central rule is unchanged: `OperationRun` is the only canonical lifecycle source of truth. Everything else in this slice is derived from status, outcome, freshness, and reconciliation metadata already present in the repo.

## Persistent Source Truths

### OperationRun

**Purpose**: Canonical operational record for queued, running, completed, stale, and automatically reconciled work shown across tenant, workspace, canonical admin, and system monitoring surfaces.

**Key fields**:
- `id`
- `workspace_id`
- `tenant_id`
- `type`
- `status`
- `outcome`
- `initiator_name`
- `summary_counts`
- `failure_summary`
- `context`
- `created_at`
- `started_at`
- `completed_at`

**Validation rules**:
- `status` and `outcome` remain service-owned; this feature must not introduce page-local lifecycle mutation.
- Every covered summary, list, detail, and notification surface must derive from the same run record and the same underlying lifecycle fields.
- The feature must not add a second persisted problem-state field or a new lifecycle table.

### Reconciliation Context (within `OperationRun.context`)

**Purpose**: Existing stored lineage that indicates a run was automatically reconciled after lifecycle drift.

**Expected fields**:
- `reconciled_at`
- `reason`
- `reason_code`
- `source`

**Validation rules**:
- Reconciliation context remains nested under `context.reconciliation`; this feature does not move it or normalize it into a new table.
- If reconciliation context exists, surfaces must preserve that stale/reconciled lineage within one navigation step of the canonical run truth.

## Existing Runtime Source Objects

### OperationRunFreshnessState

**Purpose**: Existing derived lifecycle interpretation for one run.

**Cases**:
- `fresh_active`
- `likely_stale`
- `reconciled_failed`
- `terminal_normal`
- `unknown`

**Validation rules**:
- This remains the canonical freshness interpretation for the slice.
- Spec 178 must not introduce a parallel freshness-state family.

### OperationLifecyclePolicy

**Purpose**: Existing threshold policy for deciding when queued/running work becomes stale.

**Consumed fields**:
- covered operation types
- queued stale threshold
- running stale threshold

**Validation rules**:
- Tenant, workspace, admin, and system stale or stuck semantics must all derive from the same underlying lifecycle-policy thresholds.

### StuckRunClassifier

**Purpose**: Existing system-panel classifier for active queued/running runs that crossed the stuck threshold.

**Validation rules**:
- `Stuck` remains an active-stale registry surface.
- System visibility for reconciled stale runs must be preserved through adjacent system surfaces rather than a new classifier or new stored state.

### OperationUxPresenter

**Purpose**: Existing operator-facing seam for guidance, notification wording, and run presentation.

**Validation rules**:
- New stale/reconciled wording should flow through this seam or a compatible existing presentation seam rather than widget-local strings.

## Derived Cross-Surface Contracts

### ProblemClassContract

**Purpose**: The thin operator-facing split used to align summary buckets, monitoring filters, local progress removal rules, and entry-point wording.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `freshnessState` | enum | yes | Existing `OperationRunFreshnessState` value |
| `problemClass` | enum | yes | `none`, `active_stale_attention`, or `terminal_follow_up` |
| `staleLineage` | boolean | yes | Whether the run is terminal but carries stale/reconciled history |
| `isCurrentlyActive` | boolean | yes | Whether the run should still be treated as actively executing |
| `requiresOperatorReview` | boolean | yes | Whether the surface should escalate the run into an attention/follow-up bucket |

**Validation rules**:
- `freshnessState = fresh_active` ⇒ `problemClass = none`, `isCurrentlyActive = true`
- `freshnessState = likely_stale` ⇒ `problemClass = active_stale_attention`, `isCurrentlyActive = true`, `requiresOperatorReview = true`
- `freshnessState = reconciled_failed` ⇒ `problemClass = terminal_follow_up`, `staleLineage = true`, `isCurrentlyActive = false`, `requiresOperatorReview = true`
- `freshnessState = terminal_normal` and `outcome in {blocked, partially_succeeded, failed}` ⇒ `problemClass = terminal_follow_up`, `staleLineage = false`
- `freshnessState = terminal_normal` and healthy terminal outcome ⇒ `problemClass = none`

### OperationsAttentionBucket

**Purpose**: Shared contract for tenant/workspace operations attention summaries.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `problemClass` | enum | yes | `terminal_follow_up` or `active_stale_attention` |
| `count` | integer | yes | Bucket size |
| `label` | string | yes | Operator-facing bucket label |
| `destination` | object | yes | Canonical operations route plus tenant/workspace-safe filter state |
| `emptyAllowed` | boolean | yes | Whether the bucket may be hidden when count is zero |

**Validation rules**:
- Attention surfaces must not mix both problem classes into one undifferentiated bucket.
- Each bucket exposes one destination only.

### OperationsHubFilterState

**Purpose**: Structured state needed to keep `/admin/operations` semantically continuous when opened from a summary or notification.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `workspace_id` | integer | yes | Existing workspace scope |
| `tenant_id` | integer nullable | no | Active tenant filter when applicable |
| `problemClass` | enum | yes | `terminal_follow_up`, `active_stale_attention`, or `all` |
| `activeTab` | string nullable | no | Existing or extended visible tab/filter state |
| `navigationContext` | string nullable | no | Existing canonical back-link or page-context state |

**Validation rules**:
- Links opened because of stale active attention must land in a visibly stale-active view, not a mixed generic bucket.
- Links opened because of terminal follow-up must land in a visibly terminal-problem view.

### RecentOperationRowTruth

**Purpose**: Shared row-level contract for tenant/workspace recent-operation tables and admin/system list rendering.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `runId` | integer | yes | Canonical run identifier |
| `status` | string | yes | Existing lifecycle status |
| `outcome` | string | yes | Existing execution outcome |
| `freshnessState` | enum | yes | Existing freshness interpretation |
| `problemClass` | enum | yes | Derived attention class |
| `staleLineage` | boolean | yes | Whether the row should visibly indicate reconciled stale history |
| `guidance` | string nullable | no | Short operator-facing row hint |
| `destination` | object | yes | Canonical detail URL plus optional collection URL |

**Validation rules**:
- A recent-operations row must not visually imply healthy active progress when `problemClass = active_stale_attention` or `staleLineage = true`.
- Terminal/reconciled rows must remain distinguishable from healthy completed rows.

### BulkOperationProgressSnapshot

**Purpose**: Active-only overlay contract for local progress rendering.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `runId` | integer | yes | Run being shown |
| `tenantId` | integer | yes | Tenant scope for the overlay |
| `freshnessState` | enum | yes | Existing freshness interpretation |
| `displayAsActive` | boolean | yes | Whether the run should remain visible in the overlay |
| `shouldPoll` | boolean | yes | Whether the component should continue polling |
| `overflowCount` | integer | yes | Existing overflow behavior |

**Validation rules**:
- Only currently active runs may remain in the overlay.
- If a run becomes terminal or reconciled, `displayAsActive` must become `false` within one refresh cycle.
- `shouldPoll` must become `false` when no relevant active runs remain.

### RunDecisionZoneTruth

**Purpose**: Canonical detail contract for what the operator should learn first.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `freshnessState` | enum | yes | Existing freshness interpretation |
| `problemClass` | enum | yes | Derived attention class |
| `isCurrentlyActive` | boolean | yes | Plain answer to “is the run still active?” |
| `isReconciled` | boolean | yes | Whether automatic reconciliation already happened |
| `staleLineageNote` | string nullable | no | Visible explanation when terminal truth came from stale reconciliation |
| `primaryNextAction` | string | yes | First follow-up step the operator should take |

**Validation rules**:
- For `likely_stale` and `reconciled_failed`, this contract must be visible in the primary decision hierarchy rather than only in diagnostics.
- `primaryNextAction` must differ by problem class: infrastructure investigation for stale-active, follow-up/retry/artifact review for terminal problems.

### NotificationTruthPayload

**Purpose**: Minimal contract for completed notification wording and link continuity.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `title` | string | yes | Operator-facing summary title |
| `problemClass` | enum | yes | Derived attention class |
| `staleLineage` | boolean | yes | Whether stale/reconciled history must be visible in wording |
| `runUrl` | string | yes | Canonical run destination |

**Validation rules**:
- Notification wording must not be calmer than the current run truth.
- If `staleLineage = true`, the notification must preserve that lineage in title or body without requiring the operator to infer it later.

## Relationships

- One `OperationRun` yields one `OperationRunFreshnessState` and one derived `ProblemClassContract`.
- Tenant/workspace attention buckets, recent-operation rows, admin monitoring filters, system monitoring lists, canonical detail, and completed notifications all consume the same derived problem-class contract.
- `BulkOperationProgressSnapshot` is a specialized active-only view over the same run truth.
- `RunDecisionZoneTruth` is the highest-trust detailed interpretation of the same run truth and should confirm the same problem class visible on summary surfaces.

## Lifecycle Notes

1. `OperationRun` remains the single persisted source of lifecycle truth.
2. Freshness is derived by the existing lifecycle policy and freshness-state enum.
3. Problem class is derived from freshness plus terminal outcome; it is not stored.
4. Summary surfaces consume the derived problem class in separate buckets.
5. The canonical operations hub consumes the derived problem class as visible filter state.
6. Local progress consumes the same truth but removes terminal/reconciled runs because it is active-only.
7. Canonical detail and notifications confirm the same truth with stronger operator guidance.