ahmido
1f0cc5de56
## Summary - add the shared operator explanation layer with explanation families, trustworthiness semantics, count descriptors, and centralized badge mappings - adopt explanation-first rendering across baseline compare, governance operation run detail, baseline snapshot presentation, tenant review detail, and review register rows - extend reason translation, artifact-truth presentation, fallback ops UX messaging, and focused regression coverage for operator explanation semantics ## Testing - vendor/bin/sail bin pint --dirty --format agent - vendor/bin/sail artisan test --compact tests/Feature/Monitoring/OperationsTenantScopeTest.php tests/Feature/Operations/OperationRunBlockedExecutionPresentationTest.php - vendor/bin/sail artisan test --compact ## Notes - Livewire v4 compatible - panel provider registration remains in bootstrap/providers.php - no destructive Filament actions were added or changed in this PR - no new global-search behavior was introduced in this slice Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #191
163 lines
5.2 KiB
Markdown
163 lines
5.2 KiB
Markdown
# Data Model: Operator Explanation Layer
|
|
|
|
## Entity: OperatorExplanationPattern
|
|
|
|
Purpose:
|
|
- The reusable view-model contract that turns an internal governance outcome into one operator-readable explanation block.
|
|
|
|
Core fields:
|
|
- `headline`
|
|
- Primary operator statement answering what happened
|
|
- `executionOutcome`
|
|
- Technical run or workflow completion state
|
|
- `evaluationResult`
|
|
- Business-level result statement such as complete, incomplete, suppressed, or unavailable
|
|
- `reliabilityStatement`
|
|
- Whether the result is trustworthy, limited-confidence, diagnostically useful, or unusable
|
|
- `coverageStatement`
|
|
- What is known about completeness, evidence coverage, or missing-input boundaries
|
|
- `dominantCause`
|
|
- Primary explanation for why the result looks the way it does
|
|
- `nextAction`
|
|
- Recommended operator follow-up category and text
|
|
- `countDescriptors`
|
|
- Structured list of counts with semantic roles and labels
|
|
- `diagnosticsAvailable`
|
|
- Boolean or summary indicating that deeper technical detail exists
|
|
|
|
Relationships:
|
|
- Composed from `ReasonResolutionEnvelope`, `ArtifactTruthEnvelope`, `OperationRun`, and surface-specific stats providers such as baseline compare stats.
|
|
- Rendered by Filament pages, resources, and Blade views on affected operator surfaces.
|
|
|
|
Validation / invariants:
|
|
- Every pattern must provide a headline, reliability statement, and next action when the result is degraded, suppressed, blocked, or incomplete.
|
|
- Diagnostics may enrich the pattern but may not replace the primary explanation fields.
|
|
- The pattern must never collapse execution success into result trustworthiness when those truths diverge.
|
|
|
|
## Entity: CountDescriptor
|
|
|
|
Purpose:
|
|
- Describes one visible numeric count together with its semantic meaning so counts cannot be misread.
|
|
|
|
Core fields:
|
|
- `label`
|
|
- `value`
|
|
- `role`
|
|
- Allowed values in V1:
|
|
- `execution`
|
|
- `evaluation_output`
|
|
- `coverage`
|
|
- `reliability_signal`
|
|
- `qualifier`
|
|
- Optional operator-safe context such as `partial`, `suppressed`, or `not complete`
|
|
- `visibilityTier`
|
|
- `primary` or `diagnostic`
|
|
|
|
Validation / invariants:
|
|
- A count with role `evaluation_output` must not imply full completeness on its own.
|
|
- A count with role `coverage` or `reliability_signal` must not be visually indistinguishable from an outcome count.
|
|
|
|
## Entity: ReasonResolutionEnvelope (extended use)
|
|
|
|
Purpose:
|
|
- Existing translated reason container that now also feeds the shared explanation layer.
|
|
|
|
Relevant fields used by this feature:
|
|
- `operatorLabel`
|
|
- `operatorExplanation`
|
|
- `actionability`
|
|
- `nextSteps`
|
|
|
|
New or clarified semantic outputs for this feature:
|
|
- `trustImpact`
|
|
- How the reason affects decision confidence
|
|
- `absencePattern`
|
|
- Whether the reason represents true no-result, suppressed result, missing input, blocked prerequisite, or unavailable evaluation
|
|
|
|
Validation / invariants:
|
|
- Domain reason codes remain technical identifiers.
|
|
- Operator explanation fields must remain safe to show without diagnostics.
|
|
|
|
## Entity: ArtifactTruthEnvelope (composed input)
|
|
|
|
Purpose:
|
|
- Existing multi-dimensional truth model for governance artifacts used as one semantic source for the explanation pattern.
|
|
|
|
Relevant dimensions for this feature:
|
|
- artifact existence
|
|
- content or usability
|
|
- freshness
|
|
- support level
|
|
- actionability
|
|
- publication readiness
|
|
- execution outcome where applicable
|
|
|
|
Feature constraints:
|
|
- Artifact truth remains the semantic substrate for artifact detail surfaces.
|
|
- The explanation pattern may compress or prioritize dimensions, but must not lose the underlying truth distinctions.
|
|
|
|
## Entity: GovernanceResultSurfaceModel
|
|
|
|
Purpose:
|
|
- Surface-specific read model delivered to a Filament page or resource section.
|
|
|
|
Core fields:
|
|
- `primaryPattern`
|
|
- The `OperatorExplanationPattern` for the page
|
|
- `secondaryTruth`
|
|
- Structured truth dimensions still shown by default but not as the headline
|
|
- `diagnostics`
|
|
- Raw or technical detail rendered secondarily
|
|
- `actions`
|
|
- Existing allowed actions for the surface
|
|
|
|
Relationships:
|
|
- Used by Baseline Compare, Monitoring run detail, and selected governance artifact surfaces.
|
|
|
|
Validation / invariants:
|
|
- The first visible screenful must answer: what happened, how reliable is it, why, and what next.
|
|
- Diagnostics must remain available but not dominate primary reading order.
|
|
|
|
## Derived Concepts
|
|
|
|
### Explanation Family
|
|
|
|
Definition:
|
|
- A reusable state family applied across domains, such as:
|
|
- completed but degraded
|
|
- completed but incomplete
|
|
- no output because suppressed
|
|
- no output because missing input
|
|
- output exists but is not decision-grade
|
|
|
|
Rule:
|
|
- The same family must map to the same primary reading direction and next-action category across reference surfaces.
|
|
|
|
### Trustworthiness Level
|
|
|
|
Definition:
|
|
- The operator-facing confidence level for a produced result.
|
|
|
|
Allowed values in V1:
|
|
- `trustworthy`
|
|
- `limited_confidence`
|
|
- `diagnostic_only`
|
|
- `unusable`
|
|
|
|
Rule:
|
|
- Trustworthiness must be visibly separate from execution outcome.
|
|
|
|
### Absent-Output Pattern
|
|
|
|
Definition:
|
|
- The operator explanation class used when no normal result output exists.
|
|
|
|
Required distinctions in V1:
|
|
- true no-issues result
|
|
- missing input
|
|
- blocked prerequisite
|
|
- suppressed output
|
|
- evaluation not yet available
|
|
|
|
Rule:
|
|
- These states must not collapse into one generic `no results` message. |