TenantAtlas/specs/168-tenant-governance-aggregate-contract/data-model.md

# Phase 1 Data Model: Tenant Governance Aggregate Contract

## Overview

This feature does not add a database table or persisted summary artifact. It formalizes the existing persistent source truths that already drive tenant governance posture and adds one derived runtime contract plus request-scoped reuse rules for the shared summary family.

## Persistent Source Truths

### Tenant

**Purpose**: The tenant is the scope boundary for the aggregate and for every covered surface.

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

**Validation rules**:
- Aggregate resolution is allowed only for one explicit tenant scope at a time.
- Workspace membership and tenant entitlement remain authoritative before any summary surface renders.

### BaselineTenantAssignment and BaselineProfile

**Purpose**: Define whether the tenant has an assigned baseline and which profile and snapshot chain determine compare availability.

**Key fields**:
- `baseline_tenant_assignments.tenant_id`
- `baseline_tenant_assignments.baseline_profile_id`
- `baseline_profiles.id`
- `baseline_profiles.name`
- `baseline_profiles.active_snapshot_id`

**Validation rules**:
- Missing assignment and missing snapshot remain derived availability states, not new persisted governance states.

### BaselineSnapshot

**Purpose**: Supplies consumable compare-snapshot truth for the assigned baseline profile.

**Key fields**:
- `id`
- `baseline_profile_id`
- lifecycle/completion fields already used by `BaselineSnapshotTruthResolver`

**Validation rules**:
- Snapshot usability remains governed by existing compare truth logic.
- The aggregate must not invent a second snapshot-availability rule set.

### OperationRun

**Purpose**: Supplies baseline-compare progress, completion, failure, and freshness context.

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

**Validation rules**:
- Only existing baseline-compare runs influence compare posture in this slice.
- The aggregate does not introduce a new run type or a second operational state model.

### Finding and FindingException

**Purpose**: Supply overdue workflow state, visible drift pressure, and accepted-risk governance validity.

**Key fields**:
- `findings.tenant_id`
- `findings.status`
- `findings.severity`
- `findings.due_at`
- `finding_exceptions.current_validity_state`

**Validation rules**:
- Overdue, expiring, lapsed, active-non-new, and high-severity-active counts remain derived from current findings truth.
- The aggregate must not redefine accepted-risk validity semantics.

## Existing Runtime Source Objects

### BaselineCompareStats

**Purpose**: Existing query-backed compare truth object that already combines compare availability, diagnostics, and governance-attention counts for one tenant.

**Key fields consumed by this feature**:
- `state`
- `profileName`
- `operationRunId`
- `findingsCount`
- `lastComparedHuman`
- `lastComparedIso`
- `reasonCode`
- `overdueOpenFindingsCount`
- `expiringGovernanceCount`
- `lapsedGovernanceCount`
- `activeNonNewFindingsCount`
- `highSeverityActiveFindingsCount`

**Relationship to the new aggregate**:
- The aggregate is built from one `BaselineCompareStats` resolution.
- Landing diagnostics continue to read `BaselineCompareStats` directly.

### BaselineCompareSummaryAssessment

**Purpose**: Existing summary interpretation object that maps `BaselineCompareStats` to posture family, tone, headline, supporting message, and next-action target.

**Key fields consumed by this feature**:
- `stateFamily`
- `headline`
- `supportingMessage`
- `tone`
- `positiveClaimAllowed`
- `reasonCode`
- `nextActionTarget()`
- `nextActionLabel()`

**Relationship to the new aggregate**:
- The aggregate uses the summary assessment as its summary-semantics input.
- The feature must not fork a second state-family interpretation path.

## New Derived Runtime Entities

### TenantGovernanceAggregate

**Purpose**: One tenant-scoped operator summary contract that owns the shared posture, count family, and next-action intent for tenant-governance summary surfaces.

#### Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `tenant_id` | int | yes | Tenant scope for the aggregate |
| `workspace_id` | int | yes | Workspace scope for request-local reuse safety |
| `profile_name` | string nullable | no | Assigned baseline profile name when available |
| `compare_state` | string | yes | Existing compare availability or execution state from `BaselineCompareStats` |
| `state_family` | string | yes | Existing summary posture family from `BaselineCompareSummaryAssessment` |
| `tone` | string | yes | Existing tone family used by covered summary surfaces |
| `headline` | string | yes | Operator-facing summary headline |
| `supporting_message` | string nullable | no | Secondary operator-facing explanation |
| `reason_code` | string nullable | no | Summary reason code when available |
| `last_compared_label` | string nullable | no | Human-readable freshness label |
| `visible_drift_findings_count` | int | yes | Visible drift findings count from compare stats |
| `overdue_open_findings_count` | int | yes | Overdue open findings count |
| `expiring_governance_count` | int | yes | Accepted-risk governance nearing expiry |
| `lapsed_governance_count` | int | yes | Accepted-risk governance no longer valid |
| `active_non_new_findings_count` | int | yes | Active non-new findings pressure |
| `high_severity_active_findings_count` | int | yes | High-severity active findings pressure |
| `next_action_label` | string | yes | Stable operator-facing next-step label |
| `next_action_target` | enum(`findings`,`run`,`landing`,`none`) | yes | Stable next-action intent; surfaces map this to local URLs |
| `positive_claim_allowed` | bool | yes | Whether the current summary posture qualifies as a trustworthy all-clear |
| `stats` | `BaselineCompareStats` | yes | Embedded source truth used when a consumer also needs compare diagnostics |
| `summary_assessment` | `BaselineCompareSummaryAssessment` | yes | Embedded summary truth used by all covered surfaces |

#### Validation rules

- The aggregate must be built from exactly one `BaselineCompareStats` instance and exactly one `BaselineCompareSummaryAssessment` derived from that stats instance.
- Count fields must be copied from the same stats instance; surfaces must not recompute them locally.
- Final URLs, local badges, and layout-specific copy remain outside the aggregate.

### TenantGovernanceAggregateResolver

**Purpose**: Service seam that resolves one `TenantGovernanceAggregate` per tenant scope and handles request-local reuse.

#### Fields / Inputs

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `tenant` | `Tenant` nullable | yes | Target tenant; nullable only for explicit no-tenant handling paths |
| `workspace_id` | int nullable | no | Optional explicit scope input for guardable key composition |
| `surface_variant` | string | yes | Stable consumer variant used when request-local reuse or guard declarations need surface-specific context |

#### Validation rules

- The resolver must stay derived-only.
- Reuse must be request-local only.
- A no-tenant or wrong-tenant path must never reuse a previous tenant’s aggregate.

### DerivedStateFamily::TenantGovernanceAggregate

**Purpose**: Extends the existing Spec 167 request-scoped derived-state contract so the aggregate follows the same consumer-declaration and guard rules as other supported deterministic families.

#### Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `family` | enum value | yes | Stable family identifier for request-local aggregate reuse |
| `default_freshness_policy` | enum | yes | Expected to remain `invalidate_after_mutation` for landing refresh paths |
| `allows_negative_result_cache` | bool | yes | Aggregate resolution should be reusable for deterministic no-tenant or unavailable states only if the final key contract explicitly supports it |

## Consumer Mapping

| Consumer | Aggregate responsibility | Local responsibility |
|---|---|---|
| `NeedsAttention` | Overdue, expiring, lapsed, high-severity counts; baseline posture headline; next-action intent | Operations-in-progress count and widget-specific healthy fallback layout |
| `BaselineCompareNow` | Baseline posture family, headline, supporting message, next-action intent | Tenant-panel URL mapping for findings, run detail, and landing drill-down |
| `BaselineCompareCoverageBanner` | Banner visibility posture family, tone, headline, supporting message, next-action intent | Banner-specific show/hide threshold and local URL mapping |
| `BaselineCompareLanding` | Default-visible posture zone and next-action intent | Compare diagnostics, evidence-gap detail, duplicate-name detail, and existing `Compare now` action |

## Derived State Lifecycle

1. A covered tenant summary surface asks the resolver for the current tenant aggregate.
2. The resolver resolves or reuses one request-scoped aggregate for that tenant scope.
3. Covered surfaces read the same posture family, count family, and next-action intent from the shared aggregate.
4. If an in-request mutation or refresh path makes the current aggregate stale, the resolver uses explicit invalidation or fresh-resolution semantics.
5. The next request builds a new aggregate from current source truth.

## Migration Notes

- No schema migration is required.
- Existing `BaselineCompareStats` tests remain the low-level source-truth tests.
- If the implementation adds a new derived-state family, it must also extend the Spec 167 consumer-declaration contract and guard test.