TenantAtlas/specs/261-provider-missing-policy-visibility/data-model.md

Data Model: Provider-Missing Policy Visibility & Restore Continuity v1

Overview

This slice changes one existing persisted entity and introduces only derived projections elsewhere. No new table, registry, or artifact family is planned.

Entity: Policy (existing, modified)

Table: policies

Fields

Field	Type	Source	Notes
id	bigint	existing	Primary key
workspace_id	bigint	existing	Required ownership anchor
tenant_id	bigint	existing	Required ownership anchor
external_id	string	existing	Provider-facing stable key
policy_type	string	existing	Canonical local policy type
ignored_at	timestamp nullable	existing	Explicit local suppression only after this slice
missing_from_provider_at	timestamp nullable	new	Provider-missing observation in the current supported provider-backed result set
last_synced_at	timestamp nullable	existing	Last successful provider observation/update on this row

Invariants

• workspace_id and tenant_id remain required and non-null.
• ignored_at may only be set or cleared by explicit local suppression flows.
• missing_from_provider_at may only be set or cleared by sync/provider-observation logic.
• A policy row remains persisted and viewable even when missing_from_provider_at is set.

Derived Visibility States

Derived state	ignored_at	missing_from_provider_at	Meaning
active	null	null	Current policy is locally visible and currently observed in the provider-backed result set
ignored_locally	set	null	Current policy is intentionally hidden/suppressed locally
provider_missing	null	set	Current policy remains local truth but is not currently observed in the supported provider-backed result set
ignored_locally_provider_missing	set	set	Policy is locally suppressed and also currently missing from the provider-backed result set

Filter Membership And Precedence

• active filter returns only active rows.
• ignored filter returns ignored_locally and ignored_locally_provider_missing rows.
• provider_missing filter returns provider_missing and ignored_locally_provider_missing rows.
• all returns the complete set.
• For current backup/export, provider_missing wins as the primary blocked_reason when both timestamps are present because fresh provider-backed capture is impossible even if the row is also locally ignored.

State Transition Rules

Event	From	To	Notes
Local ignore	active or provider_missing	ignored_locally or ignored_locally_provider_missing	Explicit operator intent
Local restore/unignore	ignored_locally or ignored_locally_provider_missing	active or provider_missing	Clears only ignored_at
Sync marks missing	active or ignored_locally	provider_missing or ignored_locally_provider_missing	Sets only missing_from_provider_at
Sync reappears	provider_missing or ignored_locally_provider_missing	active or ignored_locally	Clears only missing_from_provider_at
Sync reclassifies to supported type	any provider-present state	provider-present state	Updates policy_type without using ignore semantics

Derived Projection: Current Backup Eligibility

Persistence: none; computed from Policy

Field	Type	Meaning
policy_id	bigint	Policy being evaluated for current backup/export
eligible	boolean	True only when the policy is neither locally ignored nor provider-missing for current-state capture
blocked_reason	string nullable	ignored_locally or provider_missing when not eligible; provider_missing wins when both timestamps are present
historical_continuity_available	boolean	Indicates whether backup history already exists even if current capture is blocked

Rules

• Fresh provider-backed capture requires ignored_at = null and missing_from_provider_at = null.
• When both timestamps are set, current backup/export MUST return blocked_reason = provider_missing and MUST retain local ignore as secondary UI context.
• Historical backup existence does not make a provider-missing policy eligible for fresh capture.

Derived Projection: Restore Continuity

Persistence: none; computed from BackupItem plus optional linked Policy

Field	Type	Meaning
backup_item_id	bigint	Historical item being offered for restore
policy_id	bigint nullable	Linked current policy row when present
selectable	boolean	Restore eligibility of the historical item
provider_missing_notice	boolean	Shows that the current live policy is missing while the historical item remains valid
continuity_message	string nullable	Calm explanation shown in restore selection

Rules

• Historical restore selection continues to follow BackupItem truth.
• Provider-missing status on the live policy is descriptive unless an independent restore rule blocks the historical item.

Audit Payload (existing infrastructure, new event meanings)

Persistence: existing audit_logs

Field	Type	Meaning
action_id	string	policy.provider_missing_detected or policy.provider_missing_cleared or equivalent existing action ids if reused
workspace_id	bigint	Existing scope anchor
tenant_id	bigint	Existing scope anchor
subject_type	string	policy
subject_id	bigint	Policy id
metadata.external_id	string	Provider-facing stable key
metadata.policy_type	string	Canonical local policy type
metadata.transition_at	timestamp	When the presence transition was observed

Out of Scope Data Shapes

• No provider_deleted_at
• No lifecycle history table
• No materialized policy_state enum column
• No new recovery artifact or backup continuity table