TenantAtlas/specs/180-tenant-backup-health/research.md

# Research: Tenant Backup Health Signals

## Decision 1: Derive tenant backup health from existing backup and schedule truth instead of creating a persisted health model

- Decision: Build tenant backup health from existing `BackupSet`, `BackupItem`, `BackupSchedule`, and `BackupQualityResolver` facts at render time. Do not add a `tenant_backup_health` table, a cached rollup row, or a recovery-confidence ledger.
- Rationale: The repository already stores the facts this feature needs: completed backup timestamps, backup-quality degradations, and schedule timing. The product gap is missing tenant-level overview truth, not missing persistence.
- Alternatives considered:
  - Persist a backup-health row per tenant. Rejected because it would create a second source of truth for data that is already derivable.
  - Piggyback on `Tenant` model columns. Rejected because this slice does not need a new lifecycle-bearing tenant field.

## Decision 2: Let the latest relevant completed backup set govern posture

- Decision: The latest relevant completed backup set is the primary tenant backup-health basis. Older healthier backup history cannot override a newer stale or degraded latest basis.
- Rationale: The operator's first question is about the current recovery starting point, not whether an older good snapshot exists somewhere in history.
- Alternatives considered:
  - Choose the healthiest recent backup in the tenant. Rejected because it would calm the dashboard while the most recent relevant backup is weak.
  - Aggregate all backup history into a composite score. Rejected because the feature explicitly avoids a scoring engine.

## Decision 3: Reuse existing backup-quality truth instead of introducing a second degradation system

- Decision: Material degradation for tenant backup health is derived from existing `BackupQualitySummary` output, especially degraded item counts and existing degradation families. No new competing backup-quality taxonomy is introduced.
- Rationale: Backup-quality truth was already hardened in the dedicated backup-quality work. Re-deriving the same concepts differently at tenant level would create contradiction and extra maintenance.
- Alternatives considered:
  - Add a tenant-specific degradation matrix. Rejected because it would drift from backup-set and item detail truth.
  - Use only raw backup-item metadata in the dashboard resolver. Rejected because the shared quality resolver already exists and should remain authoritative.

## Decision 4: Define one config-backed freshness window for backup posture and keep schedule timing secondary

- Decision: Backup posture freshness is evaluated against the latest relevant completed backup set using one config-backed canonical freshness window in `config/tenantpilot.php`, initially aligned with the repo's existing 24-hour freshness posture for other safety-critical truth. Enabled schedule timing can add follow-up pressure but cannot replace or override that single freshness rule.
- Rationale: There is no current backup-health freshness rule in the codebase. Hard-coding a threshold inside widgets would be brittle, while a small config value keeps the semantics explicit and testable.
- Alternatives considered:
  - Make freshness entirely schedule-driven. Rejected because schedule state is secondary in the spec and cannot replace actual backup existence.
  - Hard-code a stale threshold inside the dashboard widget. Rejected because it would hide an important product rule in presentation code.

## Decision 5: Detect schedule follow-up from enabled schedules that look overdue or never-successful beyond a grace window

- Decision: `schedule_follow_up` is derived from enabled schedules whose `next_run_at` is overdue beyond a small grace window, whose `last_run_at` is missing after they should have started producing evidence, or whose last schedule status indicates a failed or non-successful recent run. If the latest backup basis is otherwise fresh and non-degraded, posture may remain `healthy`, but `schedule_follow_up` becomes the active reason and suppresses any positive healthy confirmation.
- Rationale: `BackupSchedule` already tracks `last_run_at`, `last_run_status`, and `next_run_at`. Those fields are enough to signal that automation needs attention without conflating it with actual backup health proof.
- Alternatives considered:
  - Ignore schedule state entirely. Rejected because the spec explicitly wants schedule follow-up represented.
  - Treat any enabled schedule as positive backup evidence. Rejected because schedule existence is not backup proof.

## Decision 6: Surface backup health through the existing dashboard widgets, not a new page or module

- Decision: Add backup health to the current `DashboardKpis` and `NeedsAttention` widgets and extend the existing healthy-check pattern instead of building a dedicated dashboard module or alternate tenant overview page.
- Rationale: The tenant dashboard is already the operator's primary overview surface, and the spec is explicitly a small hardening slice rather than a new product area.
- Alternatives considered:
  - Build a standalone backup-health page. Rejected because it does not solve the tenant-dashboard truth gap.
  - Defer backup health until a full recovery-confidence initiative. Rejected because the current dashboard already needs a narrower truth fix.

## Decision 7: Keep drillthrough reason-driven and use the least surprising existing surface for each reason

- Decision: Use reason-driven drillthroughs. `no_backup_basis` opens the backup-set list, `latest_backup_stale` and `latest_backup_degraded` open the latest relevant backup-set detail, and `schedule_follow_up` opens the backup-schedules list as the primary confirmation surface.
- Rationale: These destinations already exist and are tenant-scoped. The backup-set detail can confirm stale or degraded latest-basis truth through recency and backup-quality summary. The schedule list is safer than an edit screen as the first follow-up destination and already shows last-run and next-run timing.
- Alternatives considered:
  - Send every backup-health state to the backup-set list. Rejected because it weakens reason continuity for degraded latest-backup scenarios.
  - Send schedule follow-up directly to edit pages. Rejected because the first operator need is confirmation, not mutation.

## Decision 8: Add only the minimum continuity hardening needed on target surfaces

- Decision: Reuse the current backup-set detail and list surfaces for stale or degraded continuity and add one minimal schedule-follow-up confirmation signal on the backup-schedules list so the current timestamp columns remain scan-fast enough by themselves.
- Rationale: Spec 176 already moved backup quality into backup surfaces. This slice should not rebuild those surfaces again; it should only ensure the dashboard reason can be rediscovered quickly.
- Alternatives considered:
  - Add a banner framework or page-level explanation system. Rejected because it would overgrow the slice.
  - Leave continuity entirely to raw timestamps. Rejected because schedule follow-up may be too implicit at scan speed.

## Decision 9: Extend existing widget and dashboard truth tests before introducing new test harnesses

- Decision: Extend `DashboardKpisWidgetTest`, `NeedsAttentionWidgetTest`, `TenantDashboardTruthAlignmentTest`, and existing backup or schedule feature tests, and add one narrow unit test file for the resolver.
- Rationale: The affected behavior is server-driven widget and resource truth, which the current Pest and Livewire suite already covers well.
- Alternatives considered:
  - Rely only on manual validation. Rejected because the feature is specifically about preventing subtle trust regressions.
  - Add a large browser-only pack. Rejected because the highest-value assertions are deterministic server-side state and rendered truth.