TenantAtlas/specs/277-stored-reports-surface/data-model.md

Data Model: Stored Reports Surface v1

Date: 2026-05-06
Branch: 277-stored-reports-surface

Overview

This slice introduces no new persisted entity. StoredReport remains the only stored-report source of truth. The new surface adds tenant-scoped, read-only view models over that truth and keeps downstream evidence, review, and review-pack consumers separate.

Existing Persisted Truth

1. Stored Report

Persistence: Existing stored_reports table
Ownership: Tenant-owned
Scope: Many retained rows per tenant and report family

Field	Type	Nullable	Notes
id	bigint	no	Internal stored-report id
workspace_id	bigint	no	Required workspace isolation anchor
tenant_id	bigint	no	Required tenant isolation anchor
report_type	string	no	Current v1 supported values: permission_posture, entra.admin_roles
payload	jsonb	no	Family-specific report payload
fingerprint	string	yes	Integrity anchor for the current row
previous_fingerprint	string	yes	Historical lineage anchor
created_at	datetime	yes	Persisted creation time
updated_at	datetime	yes	Standard timestamp

Behavior rules:

• Stored reports are immutable retained artifacts after creation.
• current versus historical is derived by comparing the row with the latest row for the same tenant_id and report_type.
• retention_state stays derived as retained in this slice.
• No new persisted lifecycle, publication, or browse metadata is introduced.

2. Evidence Snapshot Item Source Reference

Persistence: Existing evidence_snapshot_items.source_record_type and source_record_id fields
Ownership: Existing evidence domain

These fields remain downstream identity anchors when evidence items point to a stored report. They are context only in this slice and do not create an additional v1 launch seam.

3. Review Pack / Tenant Review Consumption

Persistence: Existing review-pack and tenant-review summaries
Ownership: Existing reporting domains

These consumers remain separate business truth. The stored-report surface may describe that stored reports are reused downstream, but it does not converge their operator routes in v1.

Derived Read Models

4. Stored Report Row Summary

Persistence: none, derived at runtime
Owner: stored-report register

Field	Type	Required	Notes
report_id	int	yes	Backed by stored_reports.id
display_reference	string	yes	Stored report #{id} ({family label}) from existing artifact-truth wording
report_type	string	yes	Raw family key
report_family_label	string	yes	Headline-style label such as Permission posture report
lifecycle_state	string	yes	current or historical from artifact truth
retention_state	string	yes	retained
measured_at	datetime	yes	Derived from payload timestamp when present, otherwise created_at
summary_highlights	list	yes	Bounded, family-specific summary facts
history_visibility	bool	yes	Whether the row is included only when history is revealed

5. Stored Report Detail View

Persistence: none, derived at runtime
Owner: stored-report detail page

Field	Type	Required	Notes
artifact_truth	array	yes	Reused ArtifactTruthPresenter::forStoredReport() envelope
display_reference	string	yes	Stable stored-report reference
report_family_label	string	yes	Headline family label
measured_at	datetime	yes	Payload timestamp or created_at
integrity_anchor	string	no	fingerprint, shown when present
previous_fingerprint	string	no	Historical lineage anchor
current_report_id	int	no	Latest same-family row when viewing a historical record
current_report_url	string	no	Canonical detail URL for the current row
summary_branch	object	yes	One of the two supported family-specific summary shapes below
raw_payload	array	yes	Present but collapsed by default

6. Permission Posture Summary

Persistence: none, derived from StoredReport.payload

Payload anchors from current repo truth:

• posture_score
• required_count
• granted_count
• checked_at
• permissions[] entries with key, type, status, and features

Derived summary fields:

Field	Type	Notes
posture_score	int or null	Primary posture score
required_count	int	Required permissions count
granted_count	int	Granted permissions count
missing_count	int	Derived as required_count - granted_count, never persisted
at_risk_permissions	list	First few non-granted permission entries for operator summary
checked_at	datetime or null	Preferred measurement timestamp when present

7. Entra Admin Roles Summary

Persistence: none, derived from StoredReport.payload

Payload anchors from current repo truth:

• measured_at
• totals.roles_total
• totals.assignments_total
• totals.high_privilege_assignments
• high_privilege[] entries with role, principal, scope, and severity fields

Derived summary fields:

Field	Type	Notes
roles_total	int	Total role definitions captured
assignments_total	int	Total assignments captured
high_privilege_assignments	int	Count of privileged assignments
highest_risk_assignment	array or null	First highest-severity assignment for operator context
measured_at	datetime or null	Preferred measurement timestamp

8. Stored Report Launch Seam

Persistence: none, derived from existing operator routes

Field	Type	Required	Notes
source_surface	string	yes	Current v1 source surface name
target_url	string	yes	Canonical stored-report detail URL

Current v1 seam:

• AdminRolesSummaryWidget is the only confirmed canonical drilldown source in this slice.

Derived State Rules

Rule	Derived Behavior
Current row selection	Latest row by created_at desc, id desc for the same tenant_id and report_type
Lifecycle state	current for the latest row, otherwise historical
Retention state	retained for v1 stored-report browsing
Measured time	payload.measured_at or payload.checked_at when available, otherwise created_at
Register visibility	Only rows with an explicit family-to-capability mapping are listed
Detail authorization	Family-aware capability check after workspace and tenant membership is established
Unexpected report family	Outside v1 browse and detail scope until a follow-up spec adds support

Boundaries Explicitly Preserved

• No new report-generation, export, or lifecycle-mutation truth is introduced.
• Evidence snapshots, tenant reviews, review packs, and stored reports remain separate artifacts.
• Current versus historical stays derived and is not persisted as a new domain state.
• No generic report registry, schema catalog, or renderer framework is created.
• Evidence, review, and review-pack routes remain context only and are not v1 convergence targets.