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