TenantAtlas/specs/220-governance-run-summaries/data-model.md

Data Model: Humanized Diagnostic Summaries for Governance Operations

Overview

This feature does not add or modify persisted domain entities. It adds a logical derived presentation model for canonical governance operation run detail under /admin/operations/{run}.

The design constraint is strict:

• OperationRun remains the only persisted source for run lifecycle and execution truth.
• Related artifacts such as BaselineSnapshot, EvidenceSnapshot, TenantReview, and ReviewPack remain the persisted source for artifact truth where they exist.
• ArtifactTruthPresenter, OperatorExplanationBuilder, and ReasonPresenter remain the semantic inputs.
• The new summary remains fully derived and surface-specific.

Existing Persistent Inputs

1. OperationRun

• Purpose: Canonical operational record for background and governance work.
• Key persisted fields used by this feature:
  • id
  • workspace_id
  • tenant_id
  • type
  • status
  • outcome
  • context
  • summary_counts
  • failure_summary
  • started_at
  • completed_at
• Relationships and derived lookups used by this feature:
  • workspace and tenant context
  • related artifact resolution through current operation catalog and presenter logic

2. Related Governance Artifacts

These are not newly modeled by this feature, but they remain relevant when a run produced or references an artifact.

• BaselineSnapshot
• EvidenceSnapshot
• TenantReview
• ReviewPack

The feature only reads their already-derived truth where available.

Existing Derived Inputs

A. ArtifactTruthEnvelope

ArtifactTruthPresenter already derives ArtifactTruthEnvelope for OperationRun and related artifact records.

Important envelope dimensions already available:

• artifactExistence
• contentState
• freshnessState
• publicationReadiness
• supportState
• actionability
• primaryLabel
• primaryExplanation
• reason
• diagnosticLabel

This feature must consume that envelope instead of replacing it.

B. OperatorExplanationPattern

OperatorExplanationBuilder already derives an explanation pattern containing:

• headline
• evaluationResult
• executionOutcome
• trustworthinessLevel
• reliabilityStatement
• coverageStatement
• dominantCauseCode
• dominantCauseLabel
• dominantCauseExplanation
• nextActionCategory
• nextActionText
• countDescriptors

This feature reuses that pattern as input to the new run-detail summary.

Derived Presentation Entities

1. GovernanceRunDiagnosticSummary

Primary derived object for canonical run detail.

Field	Meaning	Source
headline	One dominant first-pass statement for the run detail page	derived from ArtifactTruthEnvelope + OperatorExplanationPattern
executionOutcomeLabel	Technical execution result kept visible as a separate fact	OperationRun.outcome via existing badge semantics
artifactImpactLabel	What the resulting artifact means for operator action	artifact truth + explanation pattern
primaryReason	One short reason supporting the headline	dominant cause explanation or primary explanation
affectedScaleCue	One operator-readable scale cue, such as ambiguous subjects or missing sections	summary_counts, run context, or related artifact truth
nextActionText	First follow-up step the operator should see	existing explanation or next-step logic
secondaryCauses[]	Additional contributing causes preserved below the primary cause	ranked from reason/context inputs
diagnosticsAvailable	Whether deeper technical sections still exist below	derived from reason, payload, or technical sections

Validation rules:

• Exactly one headline is allowed for the default-visible summary.
• artifactImpactLabel must stay distinct from executionOutcomeLabel.
• affectedScaleCue is optional, but when present it must be backed by numeric or enumerated persisted evidence, not freeform guesswork.
• secondaryCauses[] must not repeat the dominant cause.

2. DominantCauseBreakdown

Logical grouping of the main and supporting causes for degraded runs.

Field	Meaning
primaryCauseCode	Stable internal reason or derived cause key
primaryCauseLabel	Operator-facing dominant cause label
primaryCauseExplanation	Short explanation shown in the summary area
secondaryCauses[]	Additional causes shown in supporting detail only
rankingRule	Stable ranking rule used to keep ordering deterministic

Rules:

• Ranking must be deterministic for equivalent runs.
• The same cause class must keep the same reading direction across covered governance families.
• A run with no meaningful secondary cause data may omit the secondary list entirely.

3. AffectedScaleCue

Small derived object explaining what was affected and at what scale.

Field	Meaning
label	Operator-facing scale label such as Affected subjects, Missing sections, or Incomplete dimensions
value	Human-readable count or scale statement
source	Where the cue came from: summary_counts, context, or related artifact truth
confidence	Whether the cue is exact, bounded, or best available from persisted context

Rules:

• This object remains optional because not every run family has equally rich scale data.
• It must never introduce a new persisted count contract.
• It must not imply precision the persisted data does not support.

4. GovernanceRunSummaryContext

Logical context for the summary builder.

Field	Meaning
surface	Always canonical_operation_run_detail for this spec
canonicalOperationType	Canonical operation type from OperationCatalog
artifactFamily	Related artifact family when one exists
tenantVisibility	Whether related tenant/artifact context is visible to the current actor

Rules:

• This context is surface-specific and must not become a cross-product taxonomy.
• Tenant visibility rules must suppress inaccessible related labels and links.

Covered Run Families

Canonical Type	Primary Artifact Family	Typical Affected-Scale Source	Dominant-Cause Focus
baseline.capture	baseline_snapshot	summary_counts, context.result, baseline snapshot summary	blocked prerequisite, zero in-scope subjects, unusable snapshot result
baseline.compare	none direct, but linked baseline/evidence truth may exist	summary_counts, context.baseline_compare, evidence-gap payloads	suppressed output, ambiguous matches, evidence gaps, strategy failure
tenant.evidence.snapshot.generate	evidence_snapshot	evidence snapshot summary, completeness state, run counts	stale or incomplete evidence basis, blocked snapshot generation
tenant.review.compose	tenant_review	review summary, missing sections, related evidence truth	missing sections, stale evidence, internal-only review outcome
tenant.review_pack.generate	review_pack	pack summary, linked review state, generation context	internal-only or blocked pack outcome, source-review limitations

Derivation Rules

Summary selection order

1. Resolve canonical operation type.
2. Resolve related artifact truth if present.
3. Resolve operator explanation pattern.
4. Derive dominant cause and supporting causes.
5. Derive affected-scale cue from existing persisted data.
6. Build one GovernanceRunDiagnosticSummary.
7. Render diagnostics below that summary without altering the underlying truth.

Zero-output runs

• If a run completed technically but produced no decision-grade artifact, the summary must explicitly say so.
• Zero output must never default to a neutral or green reading.

Multi-cause degraded runs

• One primary cause is required.
• Additional causes remain visible as supporting detail only.
• The ranking rule must be deterministic and shared across all covered run families.

Authorization-sensitive output

• Related artifact names, tenant names, and links may only appear when entitlement checks already pass.
• The summary may remain useful without those labels by using generic operator-safe phrasing.