TenantAtlas/specs/214-governance-outcome-compression/data-model.md

# Data Model: Governance Operator Outcome Compression

## Overview

This feature does not introduce or modify persisted domain entities. It adds a logical derived presentation model that consumes existing governance artifact truth and returns one operator-first summary for each covered surface context.

The key design constraint is that compression remains fully derived from current records and current truth envelopes:

- baseline snapshot truth from `BaselineSnapshot` and `ArtifactTruthPresenter`
- evidence snapshot truth from `EvidenceSnapshot` and `ArtifactTruthPresenter`
- tenant review truth from `TenantReview` and `ArtifactTruthPresenter`
- review-pack truth from `ReviewPack` and `ArtifactTruthPresenter`
- artifact-oriented run truth from `OperationRun` and `ArtifactTruthPresenter`
- operator explanation patterns from `OperatorExplanationBuilder`

## Existing Persistent Inputs

### 1. BaselineSnapshot

- Purpose: Workspace-scoped baseline artifact used for downstream compare and governance follow-up.
- Key persisted fields used by this feature:
  - `id`
  - `workspace_id`
  - `baseline_profile_id`
  - `status`
  - `summary_jsonb`
  - `captured_at`
  - `completed_at`
  - `failed_at`
- Relationships used by this feature:
  - `baselineProfile`
  - `items`

### 2. EvidenceSnapshot

- Purpose: Tenant-scoped evidence basis assembled from multiple governance evidence dimensions.
- Key persisted fields used by this feature:
  - `id`
  - `workspace_id`
  - `tenant_id`
  - `status`
  - `completeness_state`
  - `summary`
  - `generated_at`
  - `expires_at`
  - `fingerprint`
- Relationships used by this feature:
  - `items`
  - `tenantReviews`
  - `reviewPacks`
  - `operationRun`

### 3. TenantReview

- Purpose: Tenant-scoped governance review artifact anchored to one evidence snapshot.
- Key persisted fields used by this feature:
  - `id`
  - `workspace_id`
  - `tenant_id`
  - `evidence_snapshot_id`
  - `status`
  - `completeness_state`
  - `summary`
  - `generated_at`
  - `published_at`
  - `archived_at`
  - `fingerprint`
- Relationships used by this feature:
  - `evidenceSnapshot`
  - `currentExportReviewPack`
  - `reviewPacks`
  - `operationRun`

### 4. ReviewPack

- Purpose: Tenant-scoped export artifact derived from a review and evidence basis.
- Key persisted fields used by this feature:
  - `id`
  - `workspace_id`
  - `tenant_id`
  - `tenant_review_id`
  - `evidence_snapshot_id`
  - `status`
  - `summary`
  - `generated_at`
  - `expires_at`
  - `fingerprint`
  - `file_path`
- Relationships used by this feature:
  - `tenantReview`
  - `evidenceSnapshot`
  - `operationRun`

### 5. OperationRun

- Purpose: Canonical operational detail and observability record for background governance work.
- Key persisted fields used by this feature:
  - `id`
  - `workspace_id`
  - `tenant_id`
  - `type`
  - `status`
  - `outcome`
  - `context`
  - `summary_counts`
  - `started_at`
  - `completed_at`
  - `failure_summary`
- Relationships used by this feature:
  - linked artifact references resolved through current context or related-resource helpers

## Existing Derived State Chain

### A. Canonical Artifact Truth

`ArtifactTruthPresenter` already derives `ArtifactTruthEnvelope` for:

- `BaselineSnapshot`
- `EvidenceSnapshot`
- `TenantReview`
- `ReviewPack`
- `OperationRun`

The envelope already preserves these dimensions:

- `artifactExistence`
- `contentState`
- `freshnessState`
- `publicationReadiness`
- `supportState`
- `actionability`
- `primaryLabel`
- `primaryExplanation`
- `reason`
- `nextActionLabel`
- `diagnosticLabel`

This feature must consume that chain instead of replacing it.

### B. Operator Explanation Pattern

`OperatorExplanationBuilder` already transforms the truth envelope into an operator explanation pattern that contains:

- headline
- evaluation result
- trustworthiness level
- reliability statement
- coverage statement
- dominant cause label and explanation
- next action category and text

This feature must reuse that pattern as a secondary input for the compressed operator summary.

## Derived Presentation Entities

### 1. SurfaceCompressionContext

This is a logical context, not necessarily a persisted or standalone class.

| Field | Meaning |
|---|---|
| `surfaceFamily` | Which surface family is rendering: `baseline_snapshot`, `evidence_snapshot`, `tenant_review`, `review_pack`, `review_register`, `evidence_overview`, or `operation_run_artifact` |
| `decisionRole` | Whether the surface is primary decision, secondary context, or tertiary evidence |
| `primaryQuestion` | The first operator question this surface must answer |
| `primaryDimensionPriority` | Ordered list of which truth dimensions may become primary on this surface |
| `secondaryDimensions` | Which dimensions remain visible but demoted |
| `diagnosticsAllowed` | Whether deep technical truth may be shown behind the primary summary |
| `canonicalNoun` | Stable artifact noun used in labels and next-step phrasing |

Rules:

- One compression context exists per surface family.
- A compression context must not mutate the underlying truth envelope.
- The same artifact may produce different compressed summaries on different surface families if the operator question differs.

### 2. CompressedGovernanceOutcome

This is the primary derived output of the feature.

| Field | Meaning | Source |
|---|---|---|
| `decisionDirection` | Dominant operator outcome, such as usable, stale, internal-only, blocked, or follow-up-needed | derived from truth envelope + compression context |
| `primaryLabel` | One dominant operator statement | compression of existing `primaryLabel`, publication readiness, and explanation pattern |
| `primaryReason` | One short supporting reason | existing `primaryExplanation` or dominant cause explanation |
| `nextActionText` | First follow-up step the operator should see | existing `nextActionLabel` / explanation pattern |
| `primaryBadge` | Existing canonical badge spec for the dominant outcome | `BadgeCatalog` / `BadgeRenderer` |
| `secondaryFacts[]` | Small number of still-relevant secondary dimensions | selected from freshness, completeness, publication, support, lifecycle |
| `diagnosticsSummary` | Optional summary that deep detail exists below | existing explanation and diagnostic state |

Validation rules:

- Exactly one `primaryLabel` is allowed for the default-visible summary.
- `primaryReason` must stay shorter and lower-priority than the primary label.
- `nextActionText` may be omitted only when actionability is effectively `none`.
- `primaryBadge` must come from existing centralized badge domains; no page-local mapping is allowed.

### 3. SecondaryFact

Small, bounded supporting fact shown below or beside the primary outcome.

| Field | Meaning |
|---|---|
| `label` | Stable operator-facing descriptor such as `Freshness`, `Coverage`, or `Publication` |
| `value` | Short human-readable fact |
| `badge` | Optional centralized badge spec |
| `visibilityRule` | Rule describing when the fact remains visible on the current surface family |

Rules:

- Secondary facts must support the first decision, not compete with it.
- A surface should render only the minimum secondary facts needed for correct interpretation.

### 4. DiagnosticsBundle

Logical grouping of the details preserved behind the compressed summary.

| Field | Meaning |
|---|---|
| `dimensions[]` | Full underlying truth dimensions preserved for deeper review |
| `reasonDetails` | Raw or expanded reason data already available today |
| `countDescriptors[]` | Existing count and coverage descriptors |
| `technicalPayloadAvailable` | Whether deeper technical view data exists |

Rules:

- Diagnostics remain available wherever they exist today.
- Diagnostics are never the default mental model on covered surfaces.

## Surface Mapping Rules

### Baseline Snapshot Surfaces

- Primary question: Is this baseline artifact usable right now?
- Primary candidates: artifact usability, current-vs-historical truth, major blocking reason
- Secondary candidates: fidelity, lifecycle, gap count
- Diagnostics: item-level gaps, technical detail, rendering payloads

### Evidence Snapshot Surfaces

- Primary question: Is this evidence basis usable now?
- Primary candidates: usability, freshness burden, completeness burden
- Secondary candidates: counts and supporting evidence dimensions
- Diagnostics: raw summary JSON, dimension-level states

### Tenant Review Surfaces

- Primary question: Is this review ready for real use or publication?
- Primary candidates: publication readiness, major blocker, internal-only status
- Secondary candidates: freshness, completeness, evidence basis
- Diagnostics: section detail, raw summary JSON, audit context

### Review Pack Surfaces

- Primary question: Can this pack be shared externally?
- Primary candidates: shareability or internal-only posture, source-review burden, expiration only if materially relevant
- Secondary candidates: linked review state, freshness burden, generation state
- Diagnostics: fingerprints, generation metadata, source evidence detail

### Canonical Review Register

- Primary question: Which tenant reviews need attention right now?
- Primary candidates: row-level publication or follow-up posture
- Secondary candidates: freshness/completeness context, tenant scope
- Diagnostics: detail drill-through only

### Evidence Overview

- Primary question: Which tenants have usable evidence now?
- Primary candidates: row-level usability and next step
- Secondary candidates: freshness and completeness context, tenant scope
- Diagnostics: detail drill-through only

### Artifact-Oriented Operation Run Detail

- Primary question: Why did this run leave the artifact trustworthy, limited, or blocked?
- Primary candidates: dominant artifact impact and next step
- Secondary candidates: execution outcome separated from artifact usability
- Diagnostics: raw run payloads, counters, provider detail

## Validation Rules

- The same artifact state must compress to the same decision direction across list/detail/register/run-detail surfaces unless the surface family legitimately asks a different primary question.
- Review and review-pack surfaces may prioritize publication/shareability, but they must not contradict each other about the same underlying artifact burden.
- Baseline and evidence surfaces must not let secondary fidelity or renderer facts outrank primary usability.
- When multiple limiters apply, the compressed summary must choose one dominant operator direction and keep the rest as secondary facts.
- View-only users must still see truthful compressed outcomes without gaining mutation affordances.

## State Notes

This feature introduces no new persisted state.

Existing state and badge families that remain canonical:

- `GovernanceArtifactExistence`
- `GovernanceArtifactContent`
- `GovernanceArtifactFreshness`
- tenant review completeness and readiness badge domains
- review-pack status badge domain
- baseline snapshot lifecycle and fidelity badge domains
- operator explanation trustworthiness and evaluation result semantics