# Data Model: Decision-Based Governance Inbox v1

**Date**: 2026-04-28  
**Feature**: [spec.md](spec.md)

## Model Posture

This slice introduces no new persisted entity. Every object below is a derived read model used to compose one decision-first page over existing repo truth.

## Existing Source Truth

| Source Model | Ownership | Relevant Truth Reused |
|---|---|---|
| `Finding` | tenant-owned | assigned work, intake work, severity, due or overdue state, reopened state, tenant entitlement |
| `OperationRun` | tenant-owned with workspace monitoring access | stale or terminal-follow-up attention, canonical run destination |
| `AlertDelivery` | workspace-scoped | failed or otherwise operator-relevant alert delivery outcomes |
| `TenantReview` | tenant-owned | latest review drill-through destination |
| `TenantTriageReview` | tenant-owned | follow-up-needed and changed-since-review attention |

## Derived Read Models

### GovernanceInboxSection

Represents one visible source family on the inbox page.

| Field | Type | Notes |
|---|---|---|
| `key` | string | bounded page-local family key such as `assigned_findings`, `intake_findings`, `stale_operations`, `alert_delivery_failures`, `review_follow_up`; `stale_operations` is the canonical key for both stale and terminal-follow-up operations attention |
| `label` | string | operator-facing section title aligned to the source family |
| `count` | int | visible item count for the current actor and active filters |
| `summary` | string | calm one-line summary of why the family matters |
| `dominant_action_label` | string | primary CTA label, routed to the existing source surface |
| `dominant_action_url` | string | canonical source destination |
| `entries` | list<GovernanceAttentionEntry> | bounded preview list, not a second queue truth |
| `empty_state` | string | optional local empty explanation when the family is selected explicitly |

### GovernanceAttentionEntry

Represents one preview item inside a visible section.

| Field | Type | Notes |
|---|---|---|
| `family_key` | string | matches the owning `GovernanceInboxSection.key` |
| `source_model` | string | `Finding`, `OperationRun`, `AlertDelivery`, `TenantReview`, or `TenantTriageReview` |
| `source_key` | string | stable source identifier for routing only |
| `tenant_id` | int or null | nullable for workspace-scoped alert or run cases |
| `tenant_label` | string or null | only shown when truthful |
| `headline` | string | concise operator-facing summary |
| `subline` | string or null | bounded reason, owner, or due-state context |
| `urgency_rank` | int | derived sort priority within the family |
| `status_label` | string | reused source-family wording |
| `destination_url` | string | existing canonical route |
| `back_label` | string | return label back to the inbox |

## Filter State

### GovernanceInboxFilterState

| Field | Type | Notes |
|---|---|---|
| `tenant_id` | int or null | optional tenant prefilter; explicit out-of-scope values return `404` |
| `family` | string or null | optional family filter for one visible source family; `stale_operations` remains the canonical filter key for stale or terminal-follow-up operations attention |
| `nav` | array or null | optional shared navigation payload used for return continuity |

## Ordering Rules

### Section Order

1. Assigned findings
2. Findings intake
3. Stale or terminal-follow-up operations
4. Alert-delivery failures
5. Review follow-up

This order is deliberately explicit and page-local. It is not a new persisted workflow taxonomy.

### Entry Order

- Findings-based sections reuse their existing queue ordering.
- Operations reuse the current monitoring-attention ordering exposed by the canonical operations surface.
- Alert-delivery failures order newest unresolved operator-relevant failures first.
- Review follow-up orders explicit follow-up-needed states before changed-since-review states.

## Relationships

- One `GovernanceInboxSection` maps to one existing source family.
- One `GovernanceInboxSection` has many derived `GovernanceAttentionEntry` values.
- Each `GovernanceAttentionEntry` points to exactly one existing source record and one existing source destination.
- No derived object owns or mutates source truth.

## Persistence Rules

- No new table.
- No new cache.
- No new inbox-specific audit stream.
- No new acknowledged, snoozed, or assigned state.

## Data Integrity Rules

- Hidden tenants never contribute to derived section counts or entry previews.
- Family visibility is capability-driven; invisible families do not render empty placeholders.
- Tenantless alert or operation entries must not invent tenant labels.
- Source destinations must stay canonical and existing; the inbox must not invent a parallel detail shell.