TenantAtlas/specs/161-operator-explanation-layer/data-model.md

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.