TenantAtlas/specs/189-portfolio-triage-review-state/data-model.md

# Data Model: Portfolio Triage Review State and Operator Progress

## Overview

This feature adds one persisted operator-progress entity and a small set of derived read models. Current backup-health and recovery-evidence posture remain authoritative and are not duplicated in storage.

## Existing Source Truths

### Current concern truth

**Type**: Existing derived posture state  
**Sources**: `TenantBackupHealthResolver`, `TenantBackupHealthAssessment`, `RestoreSafetyResolver`, `WorkspaceOverviewBuilder`, `TenantResource`, `PortfolioArrivalContextResolver`

| Concern Family | Stable Inputs | Notes |
|---------------|---------------|-------|
| `backup_health` | posture state, stable reason code, schedule-follow-up family, freshness family | Current source of truth for backup triage remains existing tenant backup-health assessment |
| `recovery_evidence` | posture state, stable reason code, restore-evidence concern family | Current source of truth for recovery triage remains existing restore-safety and recovery-evidence assessment |

### Existing arrival context

**Type**: Existing request-scoped continuity contract  
**Source**: `PortfolioArrivalContext`, `PortfolioArrivalContextToken`, `PortfolioArrivalContextResolver`

This feature consumes the existing concern-family focus on `/admin/t/{tenant}` to know which triage-review state should be rendered or mutated from the tenant dashboard.

## New Persisted Entity

### TenantTriageReview

**Table**: `tenant_triage_reviews`  
**Type**: Workspace-shared persisted operator-progress record  
**Lifecycle**: Active while it is the current manual review record for one workspace, tenant, and concern family; becomes inactive when superseded or explicitly resolved

| Field | Type | Validation / Notes |
|------|------|--------------------|
| `id` | bigint | Primary key |
| `workspace_id` | foreign key | Required; must reference the active workspace scope |
| `tenant_id` | foreign key | Required; must reference the tenant inside the same workspace |
| `concern_family` | string | Required; allowlisted to `backup_health` or `recovery_evidence` in V1 |
| `current_state` | string | Required; persisted values limited to `reviewed` or `follow_up_needed` |
| `reviewed_at` | timestamp | Required for active rows; when the manual state was recorded |
| `reviewed_by_user_id` | foreign key nullable | Optional actor reference for workspace-shared progress visibility |
| `review_fingerprint` | string | Required; deterministic fingerprint of the current material concern situation at review time |
| `review_snapshot` | jsonb | Required; bounded diagnostic snapshot with stable concern state, reason, and small supporting keys |
| `last_seen_matching_at` | timestamp nullable | Optional lightweight diagnostic field; initialized on write and may be refreshed opportunistically by future maintenance, but render-time correctness must not depend on it |
| `resolved_at` | timestamp nullable | Null for the current active row; set when a row is superseded or explicitly marked inactive |
| `created_at` | timestamp | Laravel default |
| `updated_at` | timestamp | Laravel default |

### Constraints and Indexes

| Constraint | Purpose |
|-----------|---------|
| Foreign keys on `workspace_id`, `tenant_id`, `reviewed_by_user_id` | Preserve workspace and tenant ownership plus reviewer linkage |
| Partial unique index on (`workspace_id`, `tenant_id`, `concern_family`) where `resolved_at IS NULL` | Ensures at most one active review record per workspace, tenant, and concern family |
| Lookup index on (`workspace_id`, `concern_family`, `resolved_at`, `tenant_id`) | Supports batch loading for workspace and registry current-set resolution |
| Check constraint or enum cast for `current_state` | Limits persisted manual states to `reviewed` or `follow_up_needed` |

## New Derived Read Models

### Derived review state

**Type**: Request-scoped resolved state  
**Source**: `TenantTriageReviewStateResolver`

| Derived State | Rule | Stored? |
|--------------|------|---------|
| `not_reviewed` | Current concern exists and no active review row exists for the same workspace, tenant, and concern family | No |
| `reviewed` | Current concern exists, active review row exists, `current_state = reviewed`, and fingerprint matches | No |
| `follow_up_needed` | Current concern exists, active review row exists, `current_state = follow_up_needed`, and fingerprint matches | No |
| `changed_since_review` | Current concern exists, active review row exists, and current fingerprint differs from the stored fingerprint | No |
| `inactive` / excluded | Current concern does not exist in the current affected set | No |

### Current-set progress summary

**Type**: Request-scoped aggregate summary  
**Source**: `TenantTriageReviewStateResolver` batch output, consumed by workspace overview and registry surfaces

| Field | Type | Notes |
|------|------|-------|
| `concern_family` | string | `backup_health` or `recovery_evidence` |
| `affected_total` | integer | Count of currently visible affected tenants in the family-specific set |
| `reviewed_count` | integer | Count of current affected rows resolved to `reviewed` |
| `follow_up_needed_count` | integer | Count of current affected rows resolved to `follow_up_needed` |
| `changed_since_review_count` | integer | Count of current affected rows resolved to `changed_since_review` |
| `not_reviewed_count` | integer | Count of current affected rows resolved to `not_reviewed` |

### Resolved row payload

**Type**: Request-scoped row-level bundle  
**Source**: `TenantTriageReviewStateResolver`

| Field | Type | Notes |
|------|------|-------|
| `tenant_id` | integer | Tenant identifier for the current row |
| `concern_family` | string | Family the resolved review state refers to |
| `current_concern_present` | boolean | False rows are excluded from current-set progress |
| `current_fingerprint` | string | Deterministic fingerprint of current concern truth |
| `derived_state` | string | `not_reviewed`, `reviewed`, `follow_up_needed`, or `changed_since_review` |
| `reviewed_at` | timestamp or null | From active review row when present |
| `reviewed_by_user_id` | integer or null | From active review row when present |
| `review_snapshot` | array or null | Bounded snapshot for optional secondary display |

## Validation Rules

### Concern-family rules

| Concern Family | Allowed Current States | Fingerprint Inputs |
|---------------|------------------------|--------------------|
| `backup_health` | `reviewed`, `follow_up_needed` | Stable backup posture, stable reason code, schedule-follow-up family, freshness family |
| `recovery_evidence` | `reviewed`, `follow_up_needed` | Stable recovery posture, stable reason code, restore-evidence concern family |

### Snapshot rules

- `review_snapshot` must remain lightweight and bounded.
- Allowed snapshot keys may include `concern_family`, `concern_state`, `reason_code`, `severity_key`, `supporting_key`, and small label-safe metadata.
- Snapshot data must not contain comments, evidence payloads, free-text notes, rendered HTML, or volatile timestamps that would destabilize equality.

### Fingerprint rules

- Fingerprints must be deterministic across repeated reads of the same material concern situation.
- Fingerprints must ignore translated copy, badge labels, rendered descriptions, and volatile time values.
- Fingerprints must change when material concern family, stable state, or stable reason keys change.

## Lifecycle and State Transitions

### Manual mutation transitions

| Event | Existing Active Row | Result |
|------|---------------------|--------|
| `Mark reviewed` | none | Insert new active row with `current_state = reviewed` |
| `Mark reviewed` | active row exists | Set prior row `resolved_at`, then insert new active `reviewed` row |
| `Mark follow_up_needed` | none | Insert new active row with `current_state = follow_up_needed` |
| `Mark follow_up_needed` | active row exists | Set prior row `resolved_at`, then insert new active `follow_up_needed` row |

### Derived-state precedence

1. If the current concern is absent, the row is excluded from current-set state.
2. If the current concern exists and no active row exists, the derived state is `not_reviewed`.
3. If an active row exists and the current fingerprint does not match, the derived state is `changed_since_review`.
4. If an active row exists and fingerprints match, the derived state follows the stored manual state.

### Inactivity handling

- Superseded writes always resolve the previous active row.
- UI correctness does not depend on immediately writing `resolved_at` when a concern naturally disappears from the current affected set; current-set exclusion is derived from current concern truth.
- If later cleanup or maintenance chooses to mark concern-gone rows as resolved, that is an implementation detail and not required for V1 correctness.

## Relationships

- One workspace has many `TenantTriageReview` rows.
- One tenant has many `TenantTriageReview` rows across concern families and historical supersessions.
- One user may review many rows through `reviewed_by_user_id`.
- One current concern family on one tenant resolves to zero or one active row.

## Rendering Rules

- Posture truth remains primary and is displayed independently of review state.
- Registry and overview counts include only current affected rows, never calm or resolved rows.
- Mixed-family registry views must label which concern family the displayed review state refers to.
- Tenant dashboard review-state actions render only when portfolio-arrival context provides a valid concern-family focus.