ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
e840007127
TenantAtlas/specs/176-backup-quality-truth/data-model.md
ahmido e840007127 feat: add backup quality truth surfaces (#211) 
## Summary
- add a shared backup-quality resolver and summary model for backup sets, backup items, policy versions, and restore selection
- surface backup-quality truth across Filament backup-set, policy-version, and restore-wizard entry points
- add focused Pest coverage and the full Spec Kit artifact set for spec 176

## Testing
- focused backup-quality verification and integrated-browser smoke coverage were completed during implementation
- degraded browser smoke path was validated with temporary seeded records and then cleaned up again
- the workspace already has a prior `vendor/bin/sail artisan test --compact` run exiting non-zero; that full-suite failure was not reworked as part of this PR

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #211
2026-04-07 11:39:40 +00:00

12 KiB
Raw Blame History

Data Model: Backup Quality Truth Surfaces

Overview

This feature does not add or change a top-level persisted domain entity. It introduces a tighter derived backup-quality model around the existing tenant-owned backup, version, and restore-selection surfaces.

The central design task is to make existing backup truth visible without changing:

  • BackupSet, BackupItem, or PolicyVersion ownership
  • existing backup or restore route identity
  • existing restore-safety, preview, and execution authority
  • existing audit and RBAC responsibilities
  • the no-new-table boundary of this feature

Existing Persistent Entities

1. BackupSet

  • Purpose: Tenant-owned backup collection that records lifecycle state and groups captured backup items.
  • Existing persistent fields used by this feature:
    • id
    • tenant_id
    • name
    • status
    • item_count
    • metadata
    • created_by
    • completed_at
    • created_at
  • Existing relationships used by this feature:
    • tenant
    • items
    • restoreRuns

Proposed nested metadata additions

None. Backup-set quality is derived from related backup items and existing set facts. No new backup-set status or metadata field is required.

2. BackupItem

  • Purpose: Tenant-owned captured recovery input for one backed-up policy or foundation record.
  • Existing persistent fields used by this feature:
    • id
    • tenant_id
    • backup_set_id
    • policy_id
    • policy_version_id
    • policy_identifier
    • policy_type
    • platform
    • payload
    • assignments
    • metadata
    • captured_at
  • Existing relationships used by this feature:
    • tenant
    • backupSet
    • policy
    • policyVersion

Existing metadata signals used by this feature

Key Type Meaning
source string or null Primary source marker; may be metadata_only
snapshot_source string or null Copied source marker from a linked policy version when a backup item is created from a version
warnings array Warning messages; may include metadata-only fallback wording
assignments_fetch_failed boolean Assignment capture failed for this item
assignment_capture_reason string or null Informational reason such as separate_role_assignments; not all reasons are degradations
has_orphaned_assignments boolean One or more resolved assignment targets were orphaned
assignment_count integer or null Captured assignment count
scope_tag_ids array<int string>
scope_tag_names array Captured scope-tag names
integrity_warning string or null Existing integrity or redaction warning copied into the backup item
protected_paths_count integer or null Count of protected or redacted paths copied from the policy version context

3. PolicyVersion

  • Purpose: Tenant-owned immutable version record for a policy snapshot.
  • Existing persistent fields used by this feature:
    • id
    • tenant_id
    • policy_id
    • version_number
    • snapshot
    • metadata
    • assignments
    • scope_tags
    • secret_fingerprints
    • redaction_version
    • captured_at
    • capture_purpose
  • Existing relationships used by this feature:
    • tenant
    • policy
    • operationRun

Existing metadata signals used by this feature

Key Type Meaning
source string or null Snapshot source marker; metadata_only is the primary degraded completeness signal
warnings array Snapshot warnings; may include metadata-only fallback language
assignments_fetch_failed boolean Assignment capture failed during version capture
assignments_fetch_error string or null Human-readable assignment capture error
assignments_fetch_error_code int or string or null Technical assignment capture error code
has_orphaned_assignments boolean One or more captured assignment targets were orphaned
capture_source string or null Existing capture context such as version_capture

Related persisted integrity context used by this feature

Field Type Meaning
secret_fingerprints array Existing redaction context used to expose integrity notes on version-derived restore inputs
redaction_version integer Existing redaction version for operator diagnostics
scope_tags array Existing scope-tag context surfaced alongside quality truth where useful

4. Restore selection context

  • Purpose: Existing wizard state that lets operators choose a backup set and optional backup-item subset before running risk checks.
  • Existing state used by this feature:
    • backup_set_id
    • scope_mode
    • backup_item_ids
    • group_mapping
    • is_dry_run

No new persisted restore-selection state is planned. This feature only enriches the current rendered option models.

Derived Models

1. SnapshotCompletenessFact

Derived completeness truth shared by backup items and policy versions.

Field Type Source Notes
mode string metadata-derived full, metadata_only, or unknown
sourceSignal string or null metadata.source or metadata.snapshot_source Authoritative direct signal when present
warningEvidence list metadata.warnings Secondary fallback signal
badgeState string derived Routes to the existing PolicySnapshotModeBadge state

Rules:

  • metadata_only when source or snapshot_source equals metadata_only, or when warning evidence clearly states metadata-only capture.
  • full only when there is no metadata-only evidence and the record contains enough captured payload context to justify a complete-snapshot claim.
  • unknown only when existing metadata cannot prove either full or metadata_only.

2. AssignmentCaptureFact

Derived assignment-quality truth for backup items and policy versions.

Field Type Source Notes
fetchFailed boolean assignments_fetch_failed Primary degraded assignment signal
captureReason string or null assignment_capture_reason Informational reason; not always degraded
orphanedAssignments boolean has_orphaned_assignments Secondary degraded signal
assignmentCount integer or null assignment_count or assignments length Informational support data
issuePresent boolean derived True when fetch failed or orphaned targets exist

Rules:

  • assignment_capture_reason = separate_role_assignments is informative and must not be misread as a failure on its own.
  • fetchFailed = true is a degraded quality signal.
  • orphanedAssignments = true is a degraded quality signal even if fetch succeeded.

3. BackupItemQualityFact

Default item-level backup-quality model for backup items.

Field Type Source Notes
backupItemId integer record id Identity
snapshotCompleteness SnapshotCompletenessFact derived Primary completeness truth
assignmentCapture AssignmentCaptureFact derived Assignment quality truth
integrityWarning string or null metadata.integrity_warning Existing integrity signal
degradationFamilies list derived Examples: metadata_only, assignment_capture_issue, orphaned_assignments, integrity_warning, unknown_quality
hasDegradations boolean derived True when one or more degradation families apply
summaryMessage string derived Concise operator-facing truth
nextAction string derived Primary next step such as inspect detail or continue with caution

4. BackupSetQualitySummary

Aggregate backup-quality truth for one backup set.

Field Type Source Notes
backupSetId integer record id Identity
totalItems integer item_count or related count Informational total
degradedItemCount integer aggregated item facts Number of degraded items
metadataOnlyCount integer aggregated item facts Count of metadata-only items
assignmentIssueCount integer aggregated item facts Count of assignment capture failures
orphanedAssignmentCount integer aggregated item facts Count of orphaned-assignment signals
integrityWarningCount integer aggregated item facts Count of integrity warnings carried into backup items
unknownQualityCount integer aggregated item facts Count of items whose quality is truly unknown
degradationFamilies list derived Set-level union of degradation families
summaryMessage string derived Compact summary for list and detail
nextAction string derived Open detail, inspect degraded items, prefer stronger version, or continue with caution
positiveClaimBoundary string derived Explains that quality does not equal safe restore or tenant recoverability

Rules:

  • Aggregate counts are computed from related BackupItemQualityFact values, never from BackupSet.status.
  • completed but degraded remains a display combination of lifecycle plus quality summary, not a new persisted backup-set status.

5. PolicyVersionQualityFact

Version-level backup-quality truth for policy versions.

Field Type Source Notes
policyVersionId integer record id Identity
snapshotCompleteness SnapshotCompletenessFact derived from version metadata Primary completeness truth
assignmentCapture AssignmentCaptureFact derived from version metadata and assignments Assignment quality truth
integrityWarning string or null derived from existing redaction or integrity context Existing warning already present in current restore and version flows
degradationFamilies list derived Same family as backup items where applicable
hasDegradations boolean derived True when one or more degradation families apply
summaryMessage string derived Concise operator-facing truth
nextAction string derived Prefer stronger version, inspect raw settings, or continue to restore with caution

6. RestoreSelectionQualityHint

Selection-stage quality model for restore wizard step 1 and step 2.

Field Type Source Notes
targetType string derived backup_set or backup_item
targetId integer selected record id Identity
summaryMessage string derived Early warning before risk checks
degradationFamilies list derived Carries through set-level or item-level truth
nextAction string derived Inspect detail or continue with caution
positiveClaimBoundary string derived Explicitly states that input quality is not restore safety

Rules:

  • Step 1 uses BackupSetQualitySummary facts.
  • Step 2 uses BackupItemQualityFact facts.
  • Neither step may claim safe to restore, restore ready, or tenant recoverable.

Validation Rules

  • Never derive backup quality from BackupSet.status, PolicyVersion action availability, or restore gating alone.
  • assignments_fetch_failed and has_orphaned_assignments are distinct signals and must be surfaced separately where the UI can support it.
  • assignment_capture_reason is explanatory metadata, not automatically a degraded state.
  • unknown quality is permitted only when current metadata cannot justify full or metadata_only and cannot justify an assignment-quality claim.
  • TENANT_VIEW visibility for backup-quality truth must remain independent from TENANT_MANAGE restore capability.
  • Restore selection hints must explicitly preserve the claim boundary that backup quality is not restore safety.