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.