# Data Model: Baseline Compare Summary Trust Propagation & Compliance Claim Hardening

## Overview

This feature introduces no new persistence model. The data model is a derived view-model contract that lifts existing compare truth, explanation, and evidence signals into compact summary surfaces.

## Derived Entities

### 1. BaselineCompareStats

- Type: existing immutable support DTO
- Source: `app/Support/Baselines/BaselineCompareStats`
- Responsibility: canonical aggregate of baseline assignment state, latest compare run state, findings totals, severity counts, coverage status, reason code, evidence-gap totals, diagnostics, and related run identity
- Relevant fields for this feature:
  - `state`
  - `message`
  - `reasonCode`
  - `reasonMessage`
  - `operationRunId`
  - `findingsCount`
  - `severityCounts`
  - `coverageStatus`
  - `uncoveredTypesCount`
  - `uncoveredTypes`
  - `fidelity`
  - `evidenceGapsCount`
  - `evidenceGapDetails`
  - `lastComparedHuman`
  - `lastComparedIso`

### 2. OperatorExplanationPattern

- Type: existing derived explanation object
- Source: `BaselineCompareExplanationRegistry::forStats()` via `BaselineCompareStats::operatorExplanation()`
- Responsibility: translates stats into explanation family, evaluation result, trustworthiness, reliability statement, coverage statement, dominant cause, and next action
- Relevant fields for this feature:
  - `family`
  - `headline`
  - `executionOutcome`
  - `evaluationResult`
  - `trustworthinessLevel`
  - `reliabilityStatement`
  - `coverageStatement`
  - `dominantCauseCode`
  - `dominantCauseLabel`
  - `nextActionCategory`
  - `nextActionText`
  - `countDescriptors`

### 3. BaselineSummaryAssessment

- Type: new derived support-layer contract
- Persistence: none
- Responsibility: one compact summary-safe interpretation of the current baseline compare posture that can be rendered consistently across dashboard, banner, and landing summary surfaces
- Documentation note: `not-ready` in the spec or task wording is not an extra enum value; it must resolve to either `in_progress` or `unavailable` in the formal contract.

#### Proposed Fields

- `stateFamily`: one of `positive`, `caution`, `stale`, `action_required`, `unavailable`, `in_progress`
- `headline`: strongest safe primary statement for the current compare posture
- `supportingMessage`: short secondary explanation, optional
- `tone`: centralized tone or badge domain for rendering emphasis
- `positiveClaimAllowed`: boolean guard used to block compliant or no-drift wording
- `trustworthinessLevel`: copied or normalized from operator explanation
- `evaluationResult`: copied or normalized from operator explanation, including `failed_result` when compare execution failed or produced no decision-grade artifact
- `evidenceImpact`: enum-like derived label such as `none`, `coverage_warning`, `evidence_gap`, `stale_result`, `suppressed_output`, `unavailable`
- `findingsVisibleCount`: numeric descriptor, not itself the verdict
- `highSeverityCount`: numeric descriptor for compact severity emphasis
- `nextAction`: structured object with:
  - `label`: concise action cue
  - `target`: one of `landing`, `findings`, `run`, `none`
- `lastComparedLabel`: relative-time summary where applicable
- `reasonCode`: current dominant reason code when one exists

#### Validation Rules

- `positiveClaimAllowed` may be `true` only when:
  - a usable compare result exists
  - trustworthiness is decision-grade
  - evaluation result is not incomplete, suppressed, failed, or unavailable
  - there is no material evidence or coverage limitation undermining the claim
- `stateFamily = positive` requires `positiveClaimAllowed = true`
- `stateFamily = caution` requires a usable but limited result
- `stateFamily = stale` requires a usable but no-longer-fresh result whose age materially limits the safety of an all-clear claim
- `stateFamily = action_required` requires confirmed drift, failed compare execution, or another follow-up-critical state
- `stateFamily = unavailable` requires no usable result, no snapshot, compare never run, or equivalent pre-execution unavailability
- `headline` must never be semantically stronger than the current explanation family and trustworthiness combination

### 4. Surface Consumption Profile

- Type: new derived rendering hint, optionally implicit rather than a dedicated class
- Persistence: none
- Responsibility: allows the same summary assessment to render at different compactness levels without changing its semantic meaning

#### Candidate Variants

- `dashboard_widget`
- `needs_attention`
- `coverage_banner`
- `landing_summary`
- `canonical_detail_reference`

#### Expected Behavior

- All variants share the same `stateFamily`, `headline`, and `positiveClaimAllowed`
- Variants may differ in verbosity, badge count, and which next-action link is most prominent
- No variant may upgrade a cautionary or unavailable assessment into a positive assessment

## Relationships

- `BaselineCompareStats` -> `OperatorExplanationPattern`
- `BaselineCompareStats` + `OperatorExplanationPattern` -> `BaselineSummaryAssessment`
- `BaselineSummaryAssessment` + `Surface Consumption Profile` -> rendered widget, banner, or landing summary output
- Canonical run detail remains the deeper truth surface that validates the same underlying explanation and reason semantics

## State Families

### Positive

- Meaning: no confirmed drift and the result is safe to treat as trustworthy
- Allowed only when positive-claim guard passes
- Example outcomes:
  - trustworthy no-result with no material evidence limitation

### Caution

- Meaning: no all-clear claim is allowed because the result is limited, incomplete, or partially reliable
- Typical drivers:
  - evidence gaps
  - coverage warnings
  - suppressed output
  - limited-confidence explanation family

### Stale

- Meaning: a previously usable compare result exists, but its freshness is no longer strong enough to support a current-state all-clear claim
- Typical drivers:
  - aged compare history beyond the current freshness threshold
  - no newer compare since a material tenant or baseline change

### Action Required

- Meaning: confirmed drift, failed compare requiring review, or another immediately actionable posture
- Typical drivers:
  - visible open drift findings
  - failed compare with explicit investigation path

### Unavailable

- Meaning: no usable compare result currently exists
- Typical drivers:
  - no assignment
  - no snapshot
  - compare never run
  - blocked prerequisite

### In Progress

- Meaning: compare is queued or running and current numbers are diagnostic only
- Typical drivers:
  - active compare operation run

## State Transitions

The summary-state family is derived, not persisted. Expected transition patterns:

- `unavailable` -> `in_progress` when a compare starts
- `in_progress` -> `positive` when the compare completes with trustworthy no-result semantics
- `in_progress` -> `caution` when the compare completes with limited-confidence or suppressed-result semantics
- `positive` or `caution` -> `stale` when freshness decays below the decision-grade threshold without a newer compare
- `stale` -> `in_progress` when a refresh compare starts
- `in_progress` -> `action_required` when the compare records open drift findings or a failure state demanding review
- `positive` -> `caution` if later evidence or coverage limits undercut trustworthiness
- `positive` or `caution` -> `unavailable` when no consumable snapshot or no usable result remains available

## Test-Critical Invariants

- `0 findings` must not force `stateFamily = positive`
- `positiveClaimAllowed = false` must block `Compliant`, `No drift`, `No open drift`, and equivalent copy on all compact surfaces
- Evidence gaps must be able to move a surface from `positive` to `caution` even when `coverageStatus = ok`
- Stale compare history must not collapse into `unavailable` or `positive`; it needs its own compact summary semantics
- Dashboard and landing surfaces consuming the same assessment must not disagree on the primary state family
- Compact surfaces may omit details, but not semantic qualifiers