ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects 1 Releases Wiki Activity
02e75e1cda
TenantAtlas/specs/165-baseline-summary-trust/data-model.md
ahmido 02e75e1cda feat: harden baseline compare summary trust surfaces (#196) 
## Summary
- add a shared baseline compare summary assessment and assessor for compact trust propagation
- harden dashboard, landing, and banner baseline compare surfaces against false all-clear claims
- add focused Pest coverage for dashboard, landing, banner, reason translation, and canonical detail parity

## Validation
- vendor/bin/sail bin pint --dirty --format agent
- vendor/bin/sail artisan test --compact tests/Feature/Baselines/BaselineCompareSummaryAssessmentTest.php tests/Feature/Baselines/BaselineCompareExplanationFallbackTest.php tests/Feature/Filament/BaselineCompareNowWidgetTest.php tests/Feature/Filament/NeedsAttentionWidgetTest.php tests/Feature/Filament/BaselineCompareExplanationSurfaceTest.php tests/Feature/Filament/BaselineCompareLandingWhyNoFindingsTest.php tests/Feature/Filament/BaselineCompareCoverageBannerTest.php tests/Feature/Filament/BaselineCompareSummaryConsistencyTest.php tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php tests/Feature/ReasonTranslation/ReasonTranslationExplanationTest.php

## Notes
- Livewire compliance: Filament v5 / Livewire v4 stack unchanged
- Provider registration: unchanged, Laravel 12 providers remain in bootstrap/providers.php
- Global search: no searchable resource behavior changed
- Destructive actions: none introduced by this change
- Assets: no new assets registered; existing deploy process remains unchanged

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #196
2026-03-27 00:19:53 +00:00

183 lines
8.0 KiB
Markdown
Raw Blame History

# 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
Reference in New Issue View Git Blame Copy Permalink