TenantAtlas/specs/165-baseline-summary-trust/data-model.md

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