TenantAtlas/specs/174-evidence-freshness-publication-trust/data-model.md

Data Model: Evidence Temporal Freshness & Review Publication Trust

Overview

This feature does not add or modify persisted domain entities. It strengthens the derived trust-propagation model that transforms existing evidence, review, and pack records into operator-facing truth across tenant-scoped detail pages and canonical summary pages.

The key design constraint is that freshness and publication trust remain derived from existing fields and relationships:

• evidence-source freshness signals
• evidence snapshot completeness and summary state
• tenant review completeness and publish blockers
• review pack linkage back to a source review and source evidence snapshot
• the existing ArtifactTruthEnvelope dimensions

Existing Persistent Entities

1. EvidenceSnapshot

• Purpose: Immutable tenant-scoped evidence basis assembled from multiple evidence dimensions.
• Key persisted fields used by this feature:
  • id
  • workspace_id
  • tenant_id
  • status
  • completeness_state
  • summary
  • generated_at
  • expires_at
  • operation_run_id
  • fingerprint
• Key summary fields used by this feature:
  • dimension_count
  • missing_dimensions
  • stale_dimensions
  • dimensions[]
  • finding_count
  • report_count
  • operation_count
• Relationships used by this feature:
  • items
  • tenantReviews
  • reviewPacks
  • operationRun
  • tenant

2. EvidenceSnapshotItem

• Purpose: Dimension-level evidence record inside one snapshot.
• Key persisted fields used by this feature:
  • evidence_snapshot_id
  • tenant_id
  • dimension_key
  • state
  • required
  • measured_at
  • freshness_at
  • source_kind
  • source_record_type
  • source_record_id
  • summary_payload
  • sort_order
• Relationships used by this feature:
  • snapshot
  • tenant

3. TenantReview

• Purpose: Tenant-scoped 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
  • current_export_review_pack_id
  • operation_run_id
  • fingerprint
• Key summary fields used by this feature:
  • publish_blockers[]
  • section_state_counts.complete
  • section_state_counts.partial
  • section_state_counts.missing
  • section_state_counts.stale
  • section_count
  • finding_count
  • report_count
  • operation_count
• Relationships used by this feature:
  • evidenceSnapshot
  • sections
  • currentExportReviewPack
  • reviewPacks
  • operationRun
  • tenant

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
  • file_disk
  • file_path
  • file_size
  • operation_run_id
  • fingerprint
• Key summary fields used by this feature:
  • review_status
  • review_completeness_state
  • evidence_resolution.outcome
  • evidence_resolution.snapshot_id
  • evidence_resolution.snapshot_fingerprint
  • evidence_resolution.completeness_state
  • finding_count
  • report_count
  • operation_count
• Relationships used by this feature:
  • tenantReview
  • evidenceSnapshot
  • operationRun
  • tenant

Existing Derived State Chain

A. Evidence Freshness Derivation

Evidence freshness is already determined in the evidence domain before any UI surface is rendered.

1. Each evidence source provider returns a dimension payload with:
   • state
   • required
   • measured_at
   • freshness_at
2. EvidenceCompletenessEvaluator rolls required dimension states into snapshot completeness:
   • missing wins first
   • then stale
   • then partial
   • otherwise complete
3. EvidenceSnapshotService persists:
   • completeness_state
   • summary.missing_dimensions
   • summary.stale_dimensions
   • per-dimension summary state

This feature must reuse that chain instead of replacing it.

B. Review Readiness Derivation

Tenant review readiness is already derived from section completeness and blockers.

1. TenantReviewSectionFactory and related composition logic produce section completeness states.
2. TenantReviewReadinessGate derives:
   • blockersForSections()
   • completenessForSections()
   • statusForSections()
3. TenantReview.summary persists:
   • publish_blockers[]
   • section_state_counts.*

This feature must reuse those publish blockers and section-state counts rather than adding a parallel publish-readiness source.

Derived View Models

1. ArtifactTruthPropagationModel

This is the conceptual chain, not a new class.

Stage	Inputs	Derived outputs
Evidence source item	source-specific timestamps and source-record state	per-dimension state, freshness_at, required
Evidence snapshot	item states, snapshot status, summary counts	artifactExistence, contentState, freshnessState, actionability
Tenant review	review status, review completeness, section-state counts, publish blockers, linked snapshot	artifactExistence, contentState, freshnessState, publicationReadiness, actionability
Review pack	pack status, evidence resolution, linked review trust burden, linked snapshot burden	artifactExistence, contentState, freshnessState, publicationReadiness, actionability
Canonical summary row	tenant label, record timestamps, derived artifact truth envelope	row-level artifact truth, publication signal, freshness signal, next step

2. SnapshotTruthModel

Derived from EvidenceSnapshot plus ArtifactTruthPresenter::buildEvidenceSnapshotEnvelope().

Field	Meaning	Source
artifactExistence	whether a current or historical snapshot exists	snapshot status
contentState	whether the evidence basis is trusted, partial, missing, or empty	snapshot completeness_state, summary.dimension_count
freshnessState	whether the evidence basis is current or stale	snapshot completeness_state, summary.stale_dimensions, historical status
actionability	whether the operator must act, may optionally act, or can do nothing	derived from freshness and completeness
nextStepText	operator-facing refresh or wait guidance	existing presenter logic

3. ReviewTruthModel

Derived from TenantReview plus ArtifactTruthPresenter::buildTenantReviewEnvelope().

Field	Meaning	Source
artifactExistence	whether the review is current, failed, or historical	review status
contentState	whether the review body is complete enough or partial	review completeness
freshnessState	whether the review evidence basis is stale	review completeness and summary.section_state_counts.stale
publicationReadiness	whether the review is blocked, internal-only, or publishable	review status, publish blockers, and this feature's stricter freshness/partiality propagation
actionability	whether the operator must resolve blockers, should refresh, or can leave the review alone	derived from publication and freshness burden
nextStepText	resolve blockers, complete work, refresh evidence, or no action needed	existing presenter logic tightened by this feature

4. PackTruthModel

Derived from ReviewPack plus ArtifactTruthPresenter::buildReviewPackEnvelope().

Field	Meaning	Source
artifactExistence	whether a current, failed, or historical pack exists	pack status
contentState	whether the pack has a trustworthy source basis	evidence resolution and source review burden
freshnessState	whether the pack should be treated as current or stale for operator trust	pack expiration plus propagated source review/evidence staleness
publicationReadiness	whether the pack is blocked, internal-only, or publishable	pack status plus propagated review and evidence burden
actionability	whether the operator must revisit the review or simply note caution	derived from the trust posture
nextStepText	open source review, refresh evidence, or no action needed	existing presenter logic tightened by this feature

5. CanonicalSummaryRowModel

Used conceptually by both EvidenceOverview and ReviewRegister.

Field	Type	Purpose
tenantName	string	Maintain tenant context in canonical pages
recordId	int	Link the summary row back to the tenant-scoped detail page
artifactTruth	label + badge spec + explanation	Primary trust summary shown in the row
freshness	badge spec	Evidence overview freshness summary
publication	badge spec	Review register publication summary
nextStep	string	Operator-facing follow-up guidance that matches detail surfaces
viewUrl	string	Drill-through to the tenant-scoped detail page

Rules:

• Canonical rows must never appear calmer than the corresponding detail pages.
• nextStep may be shorter than detail guidance, but not contradictory.
• Canonical rows must stay derived from the same truth envelope rather than page-local heuristics.

Validation Rules

• A snapshot can be structurally complete and still stale; the derived truth must preserve that distinction.
• A review can be internally useful while not being publishable; the derived truth must preserve that distinction.
• A pack must not be calmer than its source review or source evidence basis.
• Canonical overview and register rows must not contradict the tenant-scoped detail view for the same artifact.
• Freshness, completeness, and publication readiness remain separate dimensions even when they jointly influence the primary label.

State Notes

This feature introduces no new persisted state.

Existing state and badge families that remain canonical:

• EvidenceCompletenessState
• EvidenceSnapshotStatus
• TenantReviewCompletenessState
• TenantReviewStatus
• ReviewPackStatus
• BadgeDomain::GovernanceArtifactFreshness
• BadgeDomain::GovernanceArtifactPublicationReadiness

The feature only changes how these existing states combine into operator-facing trust across multiple related surfaces.