TenantAtlas/specs/175-workspace-governance-attention/data-model.md

# Phase 1 Data Model: Workspace Governance Attention Foundation

## Overview

This feature does not add a table, persisted workspace summary, or new cross-domain runtime subsystem. It aligns the existing workspace overview surface with already-available tenant truth so the workspace home can answer which visible tenants need governance attention, why they need it, and where the operator should jump next.

## Persistent Source Truths

### Workspace

**Purpose**: Scope boundary for the workspace home and all workspace-safe aggregates.

**Key fields**:
- `id`
- `name`
- `slug`

**Validation rules**:
- Workspace overview aggregation must always resolve for one explicit workspace.
- Non-members must receive deny-as-not-found behavior before any workspace truth is rendered.

### Tenant

**Purpose**: Scope boundary and identity anchor for every governance-aware workspace attention item.

**Key fields**:
- `id`
- `workspace_id`
- `external_id`
- `name`
- `status`

**Validation rules**:
- Only active tenants inside the current workspace and inside the current user's entitled tenant slice may contribute to workspace attention or governance-risk metrics.
- Every workspace attention item must identify one visible tenant explicitly.

### Finding

**Purpose**: Source of overdue findings, high-severity active findings, and other governance workflow pressure promoted into workspace attention.

**Key fields**:
- `tenant_id`
- `workspace_id`
- `finding_type`
- `status`
- `severity`
- `due_at`
- `scope_key`

**Validation rules**:
- Canonical open and active semantics remain sourced from existing finding query helpers.
- Workspace promotion must not invent a second finding status universe.

### FindingException / Governance Validity

**Purpose**: Source of lapsed governance and expiring governance truth for risk-accepted findings.

**Key fields**:
- `tenant_id`
- `workspace_id`
- `finding_id`
- `status`
- `current_validity_state`
- `review_due_at`
- `expires_at`

**Validation rules**:
- Lapsed and expiring governance remain derived from existing validity-state rules.
- Workspace promotion must not replace existing governance-validity semantics with a new workspace-specific status family.

### OperationRun

**Purpose**: Source of workspace activity, operation failures, and canonical operation drill-through.

**Key fields**:
- `id`
- `workspace_id`
- `tenant_id`
- `type`
- `status`
- `outcome`
- `created_at`
- `completed_at`

**Validation rules**:
- Active operations and failed or warning operations remain activity truths, not governance truths.
- Workspace attention may still include operations follow-up, but those items must remain semantically distinct from governance items.

### AlertDelivery

**Purpose**: Source of workspace alert-delivery failures that remain supporting attention but no longer define workspace calmness by themselves.

**Key fields**:
- `workspace_id`
- `tenant_id`
- `status`
- `created_at`

**Validation rules**:
- Alert-delivery failures remain lower-priority supporting signals once governance-critical tenant states exist.

### EvidenceSnapshot and TenantReview

**Purpose**: Existing tenant-level evidence and review truth that may serve as a precise workspace drill-through target when already-available truth makes them the best next jump.

**Key fields**:
- `tenant_id`
- `workspace_id`
- `status` or completeness fields on the owning model
- associated detail identifiers needed by tenant evidence or review resources

**Validation rules**:
- This slice does not add a new workspace evidence or review aggregate.
- Evidence or review destinations may only be used when existing tenant truth already makes them the most precise action target.

## Existing Runtime Source Objects

### TenantGovernanceAggregate

**Purpose**: Existing derived tenant summary that already combines compare posture with overdue, expiring, lapsed, and high-severity counts.

**Key consumed fields**:
- `tenantId`
- `workspaceId`
- `compareState`
- `stateFamily`
- `tone`
- `headline`
- `supportingMessage`
- `overdueOpenFindingsCount`
- `expiringGovernanceCount`
- `lapsedGovernanceCount`
- `highSeverityActiveFindingsCount`
- `nextActionLabel`
- `nextActionTarget`
- `positiveClaimAllowed`
- `summaryAssessment`

**Validation rules**:
- Workspace promotion should consume this existing summary contract before considering lower-level recomputation.
- Any workspace calmness or ranking rule based on compare or governance must remain consistent with this aggregate.

### BaselineCompareStats

**Purpose**: Existing compare-backed statistics object underlying the tenant governance aggregate.

**Key consumed fields**:
- `overdueOpenFindingsCount`
- `expiringGovernanceCount`
- `lapsedGovernanceCount`
- `highSeverityActiveFindingsCount`
- compare posture state and evidence-gap fields needed by `summaryAssessment`

**Validation rules**:
- Workspace code should not fork a second compare-summary model while this object already provides the necessary facts.

### BaselineCompareSummaryAssessment

**Purpose**: Existing compare posture contract that maps compare stats into a state family, tone, headline, and next-action intent.

**Key consumed fields**:
- `stateFamily`
- `tone`
- `headline`
- `supportingMessage`
- `reasonCode`
- `nextActionTarget()` semantics as reflected into the aggregate

**Validation rules**:
- Workspace compare attention and calmness suppression should reuse this assessment path rather than inventing a workspace-only tone system.

### WorkspaceOverviewBuilder Payload

**Purpose**: Existing page-level payload that already carries summary metrics, attention items, recent operations, quick actions, and empty states for `/admin`.

**Validation rules**:
- Governance hardening extends this payload shape rather than replacing the page with a new surface framework.
- Existing visible-tenant filtering remains the workspace aggregation guardrail.

## Derived Workspace View Contracts

### Workspace Summary Metric

**Purpose**: Compact workspace stat that answers one scope, governance-risk, or activity question and optionally opens one matching destination.

#### Fields

| Field | Type | Required | Description |
|------|------|----------|-------------|
| `key` | string | yes | Stable metric identity such as `accessible_tenants`, `governance_attention_tenants`, `overdue_findings_tenants`, or `active_operations` |
| `label` | string | yes | Operator-facing label that must accurately describe the counted universe |
| `value` | integer | yes | Metric value |
| `category` | enum | yes | `scope`, `governance_risk`, `activity`, or `alerts` |
| `description` | string | yes | Short explanation of what the metric means |
| `color` | string | yes | Existing tone family used by the widget |
| `destination` | object nullable | no | Shared drill-through contract when the metric is actionable |

#### Validation rules

- Governance-risk metrics count affected visible tenants, not raw issue totals.
- Activity metrics remain activity-only and must not imply governance health.
- The stat strip must make the difference between `governance_risk` and `activity` categories obvious.

### Workspace Attention Item

**Purpose**: One prioritized workspace triage item that names a visible tenant problem and one next jump.

#### Fields

| Field | Type | Required | Description |
|------|------|----------|-------------|
| `key` | string | yes | Stable attention identity such as `tenant_overdue_findings`, `tenant_lapsed_governance`, `tenant_compare_attention`, or `tenant_failed_operation` |
| `tenantId` | integer | yes | Visible tenant identifier |
| `tenantLabel` | string | yes | Tenant name shown to the operator |
| `family` | enum | yes | `governance`, `findings`, `compare`, `evidence`, `review`, `operations`, or `alerts` |
| `urgency` | enum | yes | `critical`, `high`, `medium`, or `supporting` |
| `title` | string | yes | Primary operator-facing summary |
| `body` | string | yes | Short explanation of why this needs attention |
| `badge` | string | yes | Existing family label shown in the UI |
| `badgeColor` | string | yes | Existing tone family used for the item |
| `supportingMessage` | string nullable | no | Secondary explanatory text when needed |
| `destination` | object nullable | no | Shared drill-through contract |
| `actionDisabled` | boolean nullable | no | Whether the visible next step is intentionally disabled |
| `helperText` | string nullable | no | Explanation when the visible next step is disabled |

#### Validation rules

- Every workspace attention item is tenant-bound and must include both `tenantId` and `tenantLabel`.
- Governance, findings, compare, evidence or review, and operations items must remain semantically distinct.
- Compare attention promotes `BaselineCompareSummaryAssessment::STATE_STALE` directly and only treats `BaselineCompareSummaryAssessment::STATE_ACTION_REQUIRED` as materially degraded compare posture when the aggregate's next action remains compare-specific rather than findings-driven.
- `BaselineCompareSummaryAssessment::STATE_CAUTION` stays below the workspace-attention threshold unless another governance signal independently warrants promotion.
- Workspace-wide operations or alert totals remain in summary metrics or recent operations until they can be attributed to one visible tenant.
- Each item may expose one primary destination only.
- Every item must either expose a non-null destination or set `actionDisabled=true` with explanatory `helperText`; null destination without an explicit disabled state is invalid.
- If the most precise destination is not available to the current in-scope user, the item must either use an allowed fallback or expose a disabled explanatory state instead of a clickable dead end.

### Workspace Recent Operation

**Purpose**: One bounded recent-operations entry shown on the workspace overview as diagnostic recency, not governance posture.

#### Fields

| Field | Type | Required | Description |
|------|------|----------|-------------|
| `id` | integer | yes | Operation run identifier |
| `title` | string | yes | Operator-facing operation label |
| `tenantLabel` | string nullable | no | Tenant name when the run is tenant-bound |
| `statusLabel` | string | yes | Human-readable run status |
| `statusColor` | string | yes | Existing tone family for the run status |
| `outcomeLabel` | string | yes | Human-readable run outcome |
| `outcomeColor` | string | yes | Existing tone family for the run outcome |
| `guidance` | string nullable | no | Short follow-up guidance when helpful |
| `startedAt` | string | yes | Render-ready recency label |
| `destination` | object | yes | Canonical operation-detail drill-through target |

#### Validation rules

- The recent-operations collection is bounded to the five most recent visible runs.
- Recent operations remain diagnostic context and do not define calmness on their own.
- `tenantLabel` may be null only when the run is genuinely workspace-wide rather than tenant-bound.

### Workspace Drill-Through Target

**Purpose**: Shared navigation contract used by summary metrics and attention items.

#### Fields

| Field | Type | Required | Description |
|------|------|----------|-------------|
| `kind` | enum | yes | `choose_tenant`, `tenant_dashboard`, `tenant_findings`, `baseline_compare_landing`, `tenant_evidence`, `tenant_reviews`, `operations_index`, `operation_detail`, `alerts_overview`, `switch_workspace`, or `none` |
| `url` | string nullable | no | Destination URL when the target is actionable |
| `tenantRouteKey` | string nullable | no | Tenant route scope when the destination is tenant-bound |
| `filters` | object nullable | no | Query or state needed to reproduce the same subset on the destination |
| `label` | string nullable | no | Primary action label |
| `disabled` | boolean | yes | Whether the target is intentionally non-clickable |
| `helperText` | string nullable | no | Explanation shown when the target is disabled |

#### Validation rules

- `kind=none` may only be used for intentionally passive reassurance states.
- `tenant_findings` must carry the filter state needed to reproduce overdue, high-severity, expiring-governance, or other directly filterable findings subsets when applicable.
- Aggregate lapsed-governance attention uses `tenant_dashboard` when the current tenant findings filters would otherwise narrow the full invalid-governance family to a smaller subset such as `missing_support`.
- `operations_index` may carry tenant and tab filters but must remain the canonical admin operations route and the workspace-member-safe fallback for low-permission workspace states.
- `alerts_overview` targets the existing alerts overview at `/admin/alerts`, which remains the canonical alert-delivery follow-up surface for this slice.
- `switch_workspace` targets `/admin/choose-workspace` and is the default zero-tenant recovery action.

### Workspace Calmness State

**Purpose**: The derived claim that the workspace is currently calm enough for an empty or reassurance state.

#### Fields

| Field | Type | Required | Description |
|------|------|----------|-------------|
| `isCalm` | boolean | yes | Whether the workspace may currently make a calmness claim |
| `checkedDomains` | array<enum> | yes | Domains actually checked before the claim was made: `governance`, `findings`, `compare`, `evidence`, `review`, `operations`, `alerts`, `tenant_access` |
| `title` | string | yes | Empty-state or reassurance title |
| `body` | string | yes | Supporting explanation constrained to the checked domains |
| `nextAction` | object | yes | One bounded next action |

#### Validation rules

- `isCalm=true` is invalid whenever any visible tenant has governance-critical conditions inside the checked domains.
- Zero-tenant states and low-permission states must not masquerade as healthy calmness states.
- Zero-tenant states default `nextAction.kind` to `switch_workspace`, while low-permission states default `nextAction.kind` to `operations_index` unless a more specific allowed in-scope recovery action exists.
- Calm wording must not imply portfolio health beyond the `checkedDomains` list.

## Ranking Rules

1. Governance-critical tenant conditions outrank activity-only and alert-only items.
2. A single tenant may contribute multiple raw issues, but workspace attention should surface a bounded prioritized subset.
3. The stat strip answers portfolio counts by tenant, while the attention list answers which tenant to open next.
4. Recent operations remain supporting recency context and do not participate in calmness unless explicitly modeled as an operations-follow-up issue.