TenantAtlas/specs/173-tenant-dashboard-truth-alignment/data-model.md

Phase 1 Data Model: Tenant Dashboard KPI & Attention Truth Alignment

Overview

This feature does not add a table, persisted summary entity, or new runtime domain subsystem. It aligns existing persistent tenant truth and existing derived summary contracts so the tenant dashboard's KPI, attention, compare, and recency surfaces describe the same tenant reality.

Persistent Source Truths

Tenant

Purpose: Scope boundary for every dashboard query and every destination opened from the tenant dashboard.

Key fields:

• id
• workspace_id
• external_id

Validation rules:

• Every dashboard summary and destination must resolve for one explicit tenant scope at a time.
• Canonical admin destinations opened from the dashboard must preserve this tenant scope through filters or navigation context.

Finding

Purpose: Source of drift, workflow, severity, and due-state truth used by tenant dashboard KPI and attention surfaces.

Key fields:

• tenant_id
• workspace_id
• finding_type
• status
• severity
• due_at
• assignee_user_id
• scope_key
• baseline_operation_run_id
• current_operation_run_id

Validation rules:

• Canonical active/open semantics come from Finding::openStatusesForQuery().
• Canonical high-severity tenant-summary semantics use SEVERITY_HIGH plus SEVERITY_CRITICAL.
• If a dashboard metric intentionally uses a narrower subset, the label and destination must say so explicitly.

Relevant state families:

• new
• acknowledged
• triaged
• in_progress
• reopened
• risk_accepted
• resolved
• closed

FindingException / Governance Validity

Purpose: Supplies expiring and lapsed accepted-risk governance truth used by tenant-level attention and calmness guards.

Key fields:

• tenant_id
• workspace_id
• finding_id
• status
• current_validity_state
• review_due_at
• expires_at

Validation rules:

• Expiring and lapsed governance must remain derived from existing validity state and timing rules.
• No dashboard-local governance state family may replace or reinterpret existing validity truth.

OperationRun

Purpose: Source of tenant activity, compare execution state, and canonical operation detail navigation.

Key fields:

• id
• tenant_id
• workspace_id
• type
• status
• outcome
• created_at
• started_at
• completed_at
• context

Validation rules:

• Canonical active operations semantics come from OperationRun::scopeActive() and the Operations page active tab.
• Dashboard activity signals must remain distinct from governance posture signals.
• Attention-worthy operations follow-up is narrower than generic activity and is limited to failed, warning, or unusually long-running or stalled tenant runs that require operator review.

Existing Runtime Source Objects

BaselineCompareStats

Purpose: Existing compare- and governance-aware source object that already owns overdue, expiring, lapsed, and high-severity active findings counts alongside compare posture inputs.

Key consumed fields:

• profileName
• state
• operationRunId
• lastComparedHuman
• findingsCount
• overdueOpenFindingsCount
• expiringGovernanceCount
• lapsedGovernanceCount
• activeNonNewFindingsCount
• highSeverityActiveFindingsCount

Validation rules:

• Existing compare and governance counts remain the source of truth for compare-backed dashboard calmness guards.
• The feature must not create a second competing count path for the same compare-backed summary family.

BaselineCompareSummaryAssessment

Purpose: Existing summary contract that maps compare stats into posture family, tone, headline, supporting message, and next-action intent.

Key consumed fields:

• stateFamily
• tone
• headline
• supportingMessage
• reasonCode
• positiveClaimAllowed
• nextActionLabel()
• nextActionTarget()

Validation rules:

• Dashboard compare calmness must remain sourced from this assessment path.
• If the dashboard suppresses additional calm claims beyond compare posture, it must do so by consuming existing tenant attention truth, not by inventing a new tone system.

TenantGovernanceAggregate

Purpose: Existing derived tenant-scoped summary contract that already combines compare posture and governance-related counts for tenant dashboard consumers.

Key consumed fields:

• headline
• profileName
• lastComparedLabel
• compareState
• summaryAssessment
• overdueOpenFindingsCount
• expiringGovernanceCount
• lapsedGovernanceCount
• highSeverityActiveFindingsCount
• nextActionLabel
• nextActionTarget
• stats

Validation rules:

• The feature should extend or reuse this existing contract rather than creating a new dashboard-only aggregate.
• Widgets using this aggregate must not re-query the same owned summary fields locally.

Derived Dashboard View Contracts

Dashboard KPI Metric

Purpose: Compact tenant dashboard stat that names one count universe and one matching destination.

Fields

Field	Type	Required	Description
key	string	yes	Stable metric identity such as new_drift, high_severity_active, or active_operations
label	string	yes	Operator-facing label that must match the actual count universe
count	integer	yes	Metric value
problemFamily	enum	yes	Shared dashboard problem family limited to findings or operations for the KPI strip in this slice
findingUniverse	enum nullable	no	new_drift_only, open_drift, or active_findings when applicable
severityUniverse	enum nullable	no	high_only or high_and_critical when applicable
destination	object	yes	Shared destination contract carrying kind, tenant-scoping, semantics label, any filter state needed to reproduce the same subset, and disabled/helper-text state when a visible affordance is intentionally non-clickable

Validation rules

• The metric label must accurately reflect findingUniverse and severityUniverse when either is present.
• The destination must reproduce the same subset or explicitly broaden it with visible framing.
• The metric problemFamily must use the same shared family naming used by AttentionItem and the internal OpenAPI contract.
• If a KPI remains visible for an in-scope member who lacks destination capability, the shared destination contract must carry the disabled state and helper text instead of implying a clickable drill-through.
• In this slice, KPI destinations are limited to tenant_findings or canonical_operations, with none reserved only for intentionally passive reassurance states.
• A canonical operations destination must carry tenant filter state from the dashboard context.

Needs Attention Item

Purpose: One dashboard attention row that describes a tenant-level problem and tells the operator where to go next.

Fields

Field	Type	Required	Description
key	string	yes	Stable attention identity such as overdue_findings, lapsed_governance, or baseline_compare_posture
title	string	yes	Operator-facing problem name
body	string	yes	Short explanation of the risk or follow-up need
supportingMessage	string nullable	no	Secondary explanatory text when the item needs more context without changing its primary destination
badge	string	yes	Existing summary family label such as Findings, Governance, Baseline, or Operations
tone	string	yes	Existing tone family used by the shared contract
problemFamily	enum	yes	findings, governance, compare, or operations
actionLabel	string nullable	no	Primary follow-up verb for this item
actionDisabled	boolean nullable	no	Whether the visible follow-up state is intentionally non-clickable for an in-scope member lacking destination capability
helperText	string nullable	no	Helper text explaining why the visible follow-up state is disabled or non-clickable
nextStepLabel	string nullable	no	Secondary text when the compare assessment already defines the next step
destination	object	yes	Shared destination contract carrying the target surface semantics, including disabled/helper-text state when the visible follow-up is intentionally non-clickable

Validation rules

• Central attention items must be actionable: destination must be present, and the item must expose either actionLabel, nextStepLabel, or a disabled explanatory state for an in-scope member who lacks the downstream capability.
• If the visible follow-up is disabled, actionDisabled must be true and helperText must be populated.
• Central attention item destinations are limited to tenant_findings, baseline_compare_landing, or canonical_operations in this slice.
• Each item may expose one primary destination only.
• Items derived from TenantGovernanceAggregate must reuse its count and posture fields rather than recompute them.

Findings Destination Filter State

Purpose: Structured state needed to make a dashboard findings drill-through semantically recoverable on the tenant findings list.

Fields

Field	Type	Required	Description
tenant	tenant route key	yes	Tenant route scope
tab	enum nullable	no	needs_action, overdue, risk_accepted, resolved, or all
status	string nullable	no	Explicit status filter when a narrower subset is intended
high_severity	boolean nullable	no	Whether the destination must enable the high-severity quick filter
finding_type	string nullable	no	drift when the dashboard metric is drift-only

Validation rules

• A dashboard findings link must use at least one of tab, status, high_severity, or finding_type when the originating KPI or attention item names a subset narrower than the default list.
• high_severity=true must align with the findings list's existing HIGH + CRITICAL filter semantics.

Operations Destination Filter State

Purpose: Structured state needed to keep /admin/operations tenant-safe and semantically continuous when opened from the tenant dashboard.

Fields

Field	Type	Required	Description
workspace_id	integer	yes	Existing workspace context
tenant_id	integer or tenant route key	yes	Active tenant filter for canonical admin operations
activeTab	enum nullable	no	active, failed, blocked, succeeded, partial, or all; blocked reproduces warning, stalled, or unusually long-running follow-up and failed reproduces terminal failure follow-up
navigationContext	string nullable	no	Optional serialized canonical back-link context carried through the canonical operations destination

Validation rules

• Dashboard operations links must preserve tenant filter state.
• Operations activity KPIs should use the activeTab=active semantics when the metric names active work.
• Operations follow-up links must use failed for terminal failure follow-up and blocked for warning, stalled, or unusually long-running follow-up so dashboard semantics stay recoverable on /admin/operations.

Relationships

• One Tenant owns many Finding rows and many OperationRun rows.
• One Finding may have zero or one current effective FindingException governance state relevant to this slice.
• One TenantGovernanceAggregate summarizes one tenant using one BaselineCompareStats instance and one BaselineCompareSummaryAssessment instance.
• DashboardKpis, NeedsAttention, and BaselineCompareNow consume overlapping derived truth and must remain semantically aligned.
• RecentDriftFindings and RecentOperations consume the same tenant scope but are diagnostic-only consumers, not posture owners.

Lifecycle Notes

1. Tenant dashboard loads for one current tenant.
2. Aggregate-backed summary surfaces resolve the current tenant's compare and governance truth.
3. KPI and attention surfaces expose destinations whose filter state must preserve the originating problem family.
4. Recency surfaces expose recent records for context only.
5. Canonical operations and tenant findings destinations resolve within the same tenant scope and remain subject to existing server-side authorization.

Migration Notes

• No schema migration is required.
• No new persisted artifact is required.
• If implementation needs a new helper, it should stay local to existing OperationRunLinks, findings list filter handling, or the existing aggregate path rather than introducing a new dashboard framework.