# Data Model: Finding Governance Health & Resolution Semantics Surface Hardening

## 1. Finding

- **Purpose**: Tenant-owned issue record that carries workflow lifecycle, severity, due state, ownership, and evidence-backed diagnostic context.
- **Ownership**: Tenant-owned (`workspace_id` + `tenant_id` already exist).
- **Relevant existing fields**:
  - `id`
  - `workspace_id`
  - `tenant_id`
  - `finding_type`
  - `status`: `new`, `acknowledged`, `triaged`, `in_progress`, `reopened`, `resolved`, `closed`, `risk_accepted`
  - `severity`
  - `owner_user_id`
  - `assignee_user_id`
  - `due_at`
  - `sla_days`
  - `resolved_at`, `resolved_reason`
  - `closed_at`, `closed_reason`, `closed_by_user_id`
  - `reopened_at`, `triaged_at`, `in_progress_at`
  - `current_operation_run_id`, `baseline_operation_run_id`
  - `evidence_jsonb`
- **Relationships**:
  - belongs to `Tenant`
  - has one current `FindingException`
  - belongs to owner, assignee, acknowledged-by, and closed-by users
- **Existing invariants preserved**:
  - Workflow status remains the source of lifecycle truth.
  - `risk_accepted` remains a finding workflow state, not proof of healthy governance by itself.
  - Open-status and terminal-status helper behavior does not change in this slice.

## 2. FindingException

- **Purpose**: Tenant-owned governance record that determines whether accepted risk is currently backed by valid, expiring, expired, revoked, rejected, or missing-support governance.
- **Ownership**: Tenant-owned (`workspace_id` + `tenant_id` already exist).
- **Relevant existing fields**:
  - `id`
  - `workspace_id`
  - `tenant_id`
  - `finding_id`
  - `status`: `pending`, `active`, `expiring`, `expired`, `rejected`, `revoked`, `superseded`
  - `current_validity_state`: `valid`, `expiring`, `expired`, `revoked`, `rejected`, `missing_support`
  - `requested_by_user_id`
  - `owner_user_id`
  - `approved_by_user_id`
  - `request_reason`, `approval_reason`, `rejection_reason`, `revocation_reason`
  - `requested_at`, `approved_at`, `rejected_at`, `revoked_at`
  - `effective_from`, `review_due_at`, `expires_at`
  - `current_decision_id`
  - `evidence_summary`
- **Relationships**:
  - belongs to `Finding`
  - belongs to requester, owner, approver, and current decision
  - has many decisions and evidence references
- **Existing invariants preserved**:
  - Governance validity remains derived from exception state and timing.
  - The exception remains the authoritative source for healthy versus lapsed governance.

## 3. Derived Surface Projection: Finding Governance Surface State

- **Purpose**: Non-persisted operator-facing projection used by findings list, finding detail, exception surfaces, and summary widgets.
- **Derived from**:
  - `Finding.status`
  - `Finding.severity`
  - `Finding.owner_user_id`, `Finding.assignee_user_id`, `Finding.due_at`
  - linked `FindingException`
  - `FindingRiskGovernanceResolver::resolveFindingState()`
  - `FindingRiskGovernanceResolver::resolveWarningMessage()`
- **Proposed derived fields**:
  - `workflow_status`: current finding status value
  - `workflow_family`: `active`, `accepted_risk`, or `historical`
  - `governance_validity`: `valid`, `expiring`, `expired`, `revoked`, `rejected`, `missing_support`, or `null`
  - `governance_attention`: `healthy`, `attention_needed`, or `not_applicable`
  - `governance_warning`: nullable operator-readable warning message
  - `due_attention`: `overdue`, `due_soon`, `none`
  - `ownership_attention`: `assigned`, `owner_missing`, `assignee_missing`, or `both_missing` where relevant
  - `resolution_context`: nullable secondary text such as `no longer observed` when derivable
  - `primary_next_action`: derived operator guidance such as inspect exception, renew governance, review overdue finding, or review historical closure
- **Invariant**:
  - This projection is derived only. It must not become a new stored truth or a replacement status enum.

## 4. Derived Surface Projection: Finding Detail Status Zone

- **Purpose**: Non-persisted grouping for the leading zone on finding detail.
- **Derived from**:
  - the Finding Governance Surface State
  - existing finding severity and related owner or assignee relationships
  - existing exception owner or approver details when relevant
- **Required visible fields**:
  - lifecycle status
  - severity or priority
  - governance validity and warning when applicable
  - owner and assignee context
  - due or SLA urgency
  - next-step guidance
- **Invariant**:
  - This zone reorganizes existing truth only; it does not add a new domain layer.

## 5. Derived Surface Projection: Tenant Governance Attention Summary

- **Purpose**: Non-persisted aggregate for dashboard and baseline-compare summary surfaces.
- **Derived from**:
  - findings with open or terminal statuses
  - overdue findings in open workflow states
  - accepted-risk findings whose governance projection resolves to expiring, expired, revoked, rejected, or missing-support states
  - existing compare summary state from `BaselineCompareStats`
- **Proposed aggregate values**:
  - `overdue_open_findings_count`
  - `expiring_governance_count`
  - `lapsed_governance_count`
  - `active_non_new_findings_count`
  - `high_severity_active_findings_count`
  - `healthy_checks` fallback only when none of the above require attention
- **Invariant**:
  - Summary surfaces remain glance-first and DB-only. They surface operator-critical truth without becoming a new reporting system.

## Surface State Families

### Finding workflow families

- `active`: `new`, `acknowledged`, `triaged`, `in_progress`, `reopened`
- `accepted_risk`: `risk_accepted`
- `historical`: `resolved`, `closed`

### Governance-health families

- `healthy`: accepted risk with `valid` governance
- `attention_needed`: accepted risk with `expiring`, `expired`, `revoked`, `rejected`, or `missing_support` governance
- `not_applicable`: active or historical findings without current governance relevance

### Urgency families

- `overdue`: open finding with due date in the past
- `due_soon`: open finding approaching due threshold if current UI supports it
- `none`: no immediate due urgency signal

## Relationship Rules

- A finding can exist without an exception.
- A finding in `risk_accepted` status without a valid linked exception must project as governance attention, not as healthy accepted risk.
- A finding outside `risk_accepted` may still have historical exception context, but workflow lifecycle remains the primary status dimension.
- Exception surfaces and finding surfaces must render the same governance truth for the same finding or exception combination.

## Behavioral Invariants For This Spec

- No new persisted entity, table, enum, or status family is introduced.
- `resolved` and `closed` remain workflow states and do not gain implicit technical-remediation meaning.
- Governance validity remains derived from exception truth, not from finding status alone.
- Summary attention must not count only `new` findings when overdue or lapsed-governance conditions already exist.