# 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.