183 lines
8.0 KiB
Markdown
183 lines
8.0 KiB
Markdown
# 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 |