Skip to content

armgit / Pulse

Public Imported from GitHub
0

Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.

Explain backup protection in plain words

rcourtman43c38253b675
diff --git a/docs/release-control/v6/internal/subsystems/frontend-primitives.md b/docs/release-control/v6/internal/subsystems/frontend-primitives.md
index 6eb8d0dd48..caa7456fdb 100644
--- a/docs/release-control/v6/internal/subsystems/frontend-primitives.md
+++ b/docs/release-control/v6/internal/subsystems/frontend-primitives.md
@@ -7449,6 +7449,10 @@ presentation. The compact row remains actionable: plain-language rationale and
provider history/permission limitations live one disclosure deeper beside
bounded restore evidence. A posture fetch failure must keep the evidence
inspectable and show unknown, never a locally inferred healthy fallback.
+The table renders the server explanation verbatim and keeps its own fallbacks
+(checking, not rated, unknown) and the snapshot-only age tooltip in the same
+plain voice, without model terms such as canonical identity or provider
+evidence.
The bounded restore evidence keeps the newest point and the newest completed
point of each source before filling with the newest overall, so a run of guest
snapshots or a running job cannot push the latest usable backup out of the
diff --git a/docs/release-control/v6/internal/subsystems/storage-recovery.md b/docs/release-control/v6/internal/subsystems/storage-recovery.md
index 890572cc5c..ed3f3e4803 100644
--- a/docs/release-control/v6/internal/subsystems/storage-recovery.md
+++ b/docs/release-control/v6/internal/subsystems/storage-recovery.md
@@ -3808,6 +3808,16 @@ expected. Stale, failed, partial, or unverified evidence is attention;
unprotected requires complete evidence of no qualifying backup; unavailable
identity, history, collection, or permission evidence fails to unknown.
Snapshots remain distinct and never prove independent recovery by themselves.
+The posture `explanation` is user-facing copy (the Coverage row tooltip and
+expansion render it verbatim), so it is written in plain words rather than the
+model's vocabulary: "recent backup", "full backup history", "one of its backup
+sources has reported a failure", "verification is missing or overdue", and
+the stale case names the policy window ("the newest confirmed backup is older
+than 7 days") through `formatPostureWindow`, which never rounds a sub-hour or
+fractional window up. Copy only claims a backup exists on branches that have
+one. Terms such as
+"subject-linked", "provider history" and "freshness window" stay in code and
+contracts, not in the explanation.
The per-tenant recovery store persists provider observations and a materialized
posture index, refreshes it after writes, reconciliation, migration, identity
diff --git a/docs/release-control/v6/internal/subsystems/unified-resources.md b/docs/release-control/v6/internal/subsystems/unified-resources.md
index 0a8439f2df..50115e23f5 100644
--- a/docs/release-control/v6/internal/subsystems/unified-resources.md
+++ b/docs/release-control/v6/internal/subsystems/unified-resources.md
@@ -3312,7 +3312,10 @@ metadata.
### Protection posture identity consumer
`ProxmoxCoverageTable` remains a unified-resource identity consumer while
-storage/recovery owns protection truth. Dropping the per-source age columns
+storage/recovery owns protection truth. Its explanation copy for rows without a
+canonical workload identity says so in user terms ("does not match a guest
+Pulse currently monitors, so it is not rated"); the identity rule itself is
+unchanged. Dropping the per-source age columns
from its rows changes no identity input: rows still key posture by the exact
canonical `Resource.id`. Live VM/LXC rows carry the exact
canonical `Resource.id` into one bounded posture batch; the table must not parse
diff --git a/frontend-modern/browser-tests/composed-backups.cjs b/frontend-modern/browser-tests/composed-backups.cjs
index fd000eb8e1..e122af5292 100644
--- a/frontend-modern/browser-tests/composed-backups.cjs
+++ b/frontend-modern/browser-tests/composed-backups.cjs
@@ -226,7 +226,7 @@ const { chromium, webkit } = require('playwright');
await scopedAge.getByText('None', { exact: true }).waitFor();
assert.ok(
(await scopedAge.locator('span[title]').getAttribute('title')).includes(
- 'Guest snapshots alone do not prove independent recovery.',
+ 'A snapshot is not a separate backup, so it does not count.',
),
);
checks.push(
diff --git a/frontend-modern/browser-verification/35a436c1be2a9bb6.json b/frontend-modern/browser-verification/35a436c1be2a9bb6.json
new file mode 100644
index 0000000000..317ed3e74d
--- /dev/null
+++ b/frontend-modern/browser-verification/35a436c1be2a9bb6.json
@@ -0,0 +1,36 @@
+{
+ "version": 1,
+ "base_sha": "a82a8e04747263f5c49083f4c537e03040ba3c62",
+ "verified_at": "2026-10-05T04:01:52Z",
+ "result": "passed",
+ "changed_paths": [
+ "frontend-modern/src/features/proxmox/ProxmoxCoverageTable.tsx",
+ "frontend-modern/src/features/proxmox/proxmoxBackupRecoveryModel.ts"
+ ],
+ "content_sha256": {
+ "frontend-modern/src/features/proxmox/ProxmoxCoverageTable.tsx": "ffdd41704d33d02194119521d60f2cfcfa1b2a10f069e95e80eaacee7f63d40f",
+ "frontend-modern/src/features/proxmox/proxmoxBackupRecoveryModel.ts": "9073910e7ccb6806424e3a324424942afef939d102fc40e94db8323100dd78a6"
+ },
+ "routes": [
+ "/proxmox/backups/coverage"
+ ],
+ "viewports": [
+ {
+ "width": 1440,
+ "height": 1000
+ },
+ {
+ "width": 390,
+ "height": 844
+ }
+ ],
+ "states": [
+ "Coverage rows on a rebuilt backend: protected, attention (failed source, stale beyond 7 days), unprotected (no backup, snapshots only), unknown and not-evaluated explanations all read in plain words",
+ "Failed-source guest expansion: Needs attention: A backup exists, but one of its backup sources has reported a failure.",
+ "Snapshot-only age tooltip: No PBS snapshot or PVE backup file. A snapshot is not a separate backup, so it does not count."
+ ],
+ "interactions": [
+ "Read every posture tooltip on the coverage table",
+ "Expanded the failed-source guest row"
+ ]
+}
diff --git a/frontend-modern/src/features/proxmox/ProxmoxCoverageTable.tsx b/frontend-modern/src/features/proxmox/ProxmoxCoverageTable.tsx
index 6fd43f852a..34233d7e81 100644
--- a/frontend-modern/src/features/proxmox/ProxmoxCoverageTable.tsx
+++ b/frontend-modern/src/features/proxmox/ProxmoxCoverageTable.tsx
@@ -53,7 +53,7 @@ const COVERAGE_EMPTY_LABEL = 'None';
const COVERAGE_NO_BACKUP_TITLE = 'No PBS snapshot or PVE backup file';
// Matches the posture engine's own wording for a snapshot-only subject.
const COVERAGE_SNAPSHOT_ONLY_TITLE =
- 'No PBS snapshot or PVE backup file. Guest snapshots alone do not prove independent recovery.';
+ 'No PBS snapshot or PVE backup file. A snapshot is not a separate backup, so it does not count.';
function CoverageAgeFallback(props: { unknown?: boolean; emptyTitle: string; compact?: boolean }) {
const title = () =>
@@ -129,11 +129,11 @@ const evidenceQualityLabel = (value: string): string => {
const postureExplanation = (row: WorkloadCoverageRow): string => {
if (row.protectionPosture?.explanation) return row.protectionPosture.explanation;
- if (row.posture === 'checking') return 'Pulse is checking provider protection evidence.';
+ if (row.posture === 'checking') return "Pulse is checking this guest's backups.";
if (row.posture === 'not-evaluated') {
- return 'This backup target has no current canonical workload identity, so Pulse does not evaluate workload protection for it.';
+ return 'This backup does not match a guest Pulse currently monitors, so it is not rated.';
}
- return 'Pulse does not have enough provider evidence to determine protection.';
+ return 'Pulse cannot tell yet whether this guest is backed up.';
};
// "Workload coverage" table: one row per workload answering "does this have a
diff --git a/frontend-modern/src/features/proxmox/__tests__/ProxmoxCoverageTable.test.tsx b/frontend-modern/src/features/proxmox/__tests__/ProxmoxCoverageTable.test.tsx
index e9b9490ce0..a051faf0f4 100644
--- a/frontend-modern/src/features/proxmox/__tests__/ProxmoxCoverageTable.test.tsx
+++ b/frontend-modern/src/features/proxmox/__tests__/ProxmoxCoverageTable.test.tsx
@@ -225,4 +225,37 @@ describe('ProxmoxCoverageTable column visibility', () => {
expect(empty(title)).toHaveTextContent(/^None$/);
}
});
+
+ it('explains snapshot-only and unrated rows in plain words', () => {
+ render(() => (
+ <ProxmoxCoverageTable
+ rows={[
+ { ...row, key: 'snapshot-only', snapshotCount: 2 },
+ { ...row, key: 'unrated', posture: 'not-evaluated', protectionPosture: undefined },
+ ]}
+ hasAnyRows
+ emptyIcon={<span />}
+ emptyTitle=""
+ emptyDescription=""
+ sortKey={(() => 'posture') as Accessor<CoverageSortKey>}
+ sortDirection={() => 'asc'}
+ onSort={() => {}}
+ expandedKeys={new Set<string>()}
+ onToggleExpand={() => {}}
+ showTaskColumn={true}
+ layoutWidth={() => 1_200}
+ />
+ ));
+
+ const titles = [...document.querySelectorAll('td span[title]')].map((span) =>
+ span.getAttribute('title'),
+ );
+ expect(titles).toContain(
+ 'No PBS snapshot or PVE backup file. A snapshot is not a separate backup, so it does not count.',
+ );
+ expect(titles).toContain(
+ 'This backup does not match a guest Pulse currently monitors, so it is not rated.',
+ );
+ expect(titles.join(' ')).not.toMatch(/canonical|provider evidence|independent recovery/);
+ });
});
diff --git a/frontend-modern/src/features/proxmox/proxmoxBackupRecoveryModel.ts b/frontend-modern/src/features/proxmox/proxmoxBackupRecoveryModel.ts
index d75fe771e2..7c52f4d144 100644
--- a/frontend-modern/src/features/proxmox/proxmoxBackupRecoveryModel.ts
+++ b/frontend-modern/src/features/proxmox/proxmoxBackupRecoveryModel.ts
@@ -149,7 +149,7 @@ export function getRecoveryAgeBand(
// A guest snapshot shares the guest's storage, so it is listed as restore
// evidence but never counted as a backup. Mirrors the server posture rule that
-// "snapshots alone do not prove independent recovery".
+// "a snapshot is not a separate backup, so it does not count".
export function isBackupArtifact(artifact: RecoverableArtifact): boolean {
return artifact.sourceKind !== 'snapshot';
}
diff --git a/internal/recovery/posture.go b/internal/recovery/posture.go
index 89abfa20cc..5065c6528b 100644
--- a/internal/recovery/posture.go
+++ b/internal/recovery/posture.go
@@ -390,7 +390,7 @@ func DeriveProtectionPostureAt(
ProviderStates: []ProtectionProviderState{},
RepositoryResourceIDs: []string{},
EvidenceIDs: []string{},
- Explanation: "Pulse has no complete provider history linked to this resource, so protection is unknown.",
+ Explanation: "Pulse has no readable backup history for this resource, so it cannot say whether it is protected.",
EvaluatedAt: now,
}
@@ -561,37 +561,41 @@ func DeriveProtectionPostureAt(
(!stateVerificationExpected || posture.Verification == ProtectionVerificationVerified):
posture.State = ProtectionStateProtected
if posture.Verification == ProtectionVerificationVerified {
- posture.Explanation = "A current subject-linked backup is available and has recent verification evidence."
+ posture.Explanation = "A recent backup is available and it was verified recently."
} else {
- posture.Explanation = "A current subject-linked backup is available from complete provider history."
+ posture.Explanation = "A recent backup is available, and Pulse can see the full backup history."
}
if hasUnknownBlock {
- posture.Explanation += " Another linked provider has unavailable history, but it does not invalidate the confirmed recovery point."
+ posture.Explanation += " Another backup source could not be read, but that does not change this backup."
}
case hasSupportedQualifyingSuccess:
posture.State = ProtectionStateAttention
switch {
case hasInvalidatingFailure:
- posture.Explanation = "A backup exists, but a newer provider failure needs attention before Pulse can call this resource protected."
+ posture.Explanation = "A backup exists, but one of its backup sources has reported a failure."
case posture.Freshness == ProtectionFreshnessStale:
- posture.Explanation = "The strongest subject-linked backup is older than the configured freshness window."
+ posture.Explanation = fmt.Sprintf("The newest confirmed backup is older than %s.", formatPostureWindow(policy.FreshnessWindow))
case stateVerificationExpected && posture.Verification != ProtectionVerificationVerified:
- posture.Explanation = "A current backup exists, but its verification evidence is missing or stale."
+ posture.Explanation = "A recent backup exists, but its verification is missing or overdue."
default:
- posture.Explanation = "Recovery evidence exists, but provider history or permissions are incomplete."
+ posture.Explanation = "A backup exists, but Pulse can see only part of the backup history or cannot read all of it."
}
case hasUnknownBlock:
posture.State = ProtectionStateUnknown
- posture.Explanation = "Provider history or permissions are unavailable, so Pulse cannot make a stronger protection claim."
+ posture.Explanation = "Pulse cannot read the backup history (it is unavailable or Pulse lacks permission), so it cannot say whether this is protected."
case hasQualifyingSuccess || hasPartial:
posture.State = ProtectionStateAttention
- posture.Explanation = "Recovery evidence exists, but provider history or permissions are incomplete."
+ if hasQualifyingSuccess {
+ posture.Explanation = "A backup exists, but Pulse can see only part of the backup history or cannot read all of it."
+ } else {
+ posture.Explanation = "Pulse can see only part of the backup history, so it cannot confirm a backup."
+ }
case hasCompleteHistory:
posture.State = ProtectionStateUnprotected
if hasSnapshotsOnly {
- posture.Explanation = "Provider history is complete, but only snapshots are present; snapshots alone do not prove independent recovery."
+ posture.Explanation = "Only snapshots were found. A snapshot is not a separate backup, so it does not count."
} else {
- posture.Explanation = "Provider history is complete, but no qualifying subject-linked backup exists."
+ posture.Explanation = "Pulse can see the full backup history and found no backup for this resource."
}
default:
posture.State = ProtectionStateUnknown
@@ -684,3 +688,26 @@ func validProtectionPermissions(value operationaltrust.EvidencePermissions) bool
return false
}
}
+
+// formatPostureWindow renders the freshness window the way the explanation
+// reads it: whole days, then whole hours, otherwise minutes, so a sub-hour or
+// fractional window is never rounded into a claim it did not make.
+func formatPostureWindow(window time.Duration) string {
+ plural := func(n int, unit string) string {
+ if n == 1 {
+ return fmt.Sprintf("1 %s", unit)
+ }
+ return fmt.Sprintf("%d %ss", n, unit)
+ }
+ switch {
+ case window >= 24*time.Hour && window%(24*time.Hour) == 0:
+ return plural(int(window/(24*time.Hour)), "day")
+ case window >= time.Hour && window%time.Hour == 0:
+ return plural(int(window/time.Hour), "hour")
+ case window > 0:
+ minutes := int((window + time.Minute - 1) / time.Minute)
+ return plural(minutes, "minute")
+ default:
+ return "0 minutes"
+ }
+}
diff --git a/internal/recovery/posture_test.go b/internal/recovery/posture_test.go
index 103f0ad17a..9bf2041b78 100644
--- a/internal/recovery/posture_test.go
+++ b/internal/recovery/posture_test.go
@@ -55,7 +55,7 @@ func TestDeriveProtectionPostureTruthTable(t *testing.T) {
wantFresh: ProtectionFreshnessCurrent,
wantVerify: ProtectionVerificationVerified,
wantCoverage: ProtectionCoverageComplete,
- wantText: "current subject-linked backup",
+ wantText: "A recent backup is available",
},
{
name: "stale success needs attention",
@@ -66,7 +66,7 @@ func TestDeriveProtectionPostureTruthTable(t *testing.T) {
wantFresh: ProtectionFreshnessStale,
wantVerify: ProtectionVerificationStale,
wantCoverage: ProtectionCoverageComplete,
- wantText: "older than",
+ wantText: "newest confirmed backup is older than 7 days",
},
{
name: "missing expected verification needs attention",
@@ -79,7 +79,7 @@ func TestDeriveProtectionPostureTruthTable(t *testing.T) {
wantFresh: ProtectionFreshnessCurrent,
wantVerify: ProtectionVerificationUnverified,
wantCoverage: ProtectionCoverageComplete,
- wantText: "verification evidence",
+ wantText: "verification is missing or overdue",
},
{
name: "newer provider failure invalidates protected claim",
@@ -94,7 +94,7 @@ func TestDeriveProtectionPostureTruthTable(t *testing.T) {
wantFresh: ProtectionFreshnessCurrent,
wantVerify: ProtectionVerificationVerified,
wantCoverage: ProtectionCoverageComplete,
- wantText: "newer provider failure",
+ wantText: "one of its backup sources has reported a failure",
},
{
name: "complete snapshot-only history is unprotected",
@@ -114,7 +114,7 @@ func TestDeriveProtectionPostureTruthTable(t *testing.T) {
wantFresh: ProtectionFreshnessUnknown,
wantVerify: ProtectionVerificationUnknown,
wantCoverage: ProtectionCoverageNone,
- wantText: "snapshots alone",
+ wantText: "A snapshot is not a separate backup",
},
{
name: "partial provider history is attention when a backup exists",
@@ -128,7 +128,21 @@ func TestDeriveProtectionPostureTruthTable(t *testing.T) {
wantFresh: ProtectionFreshnessCurrent,
wantVerify: ProtectionVerificationVerified,
wantCoverage: ProtectionCoveragePartial,
- wantText: "incomplete",
+ wantText: "only part of the backup history",
+ },
+ {
+ name: "partial history without any backup does not claim one exists",
+ summaries: func() []ProtectionProviderSummary {
+ summary := protectionTestSummary(now, nil)
+ summary.HistoryCompleteness = ProtectionHistoryPartial
+ summary.BackupPointCount = 0
+ return []ProtectionProviderSummary{summary}
+ }(),
+ wantState: ProtectionStateAttention,
+ wantFresh: ProtectionFreshnessUnknown,
+ wantVerify: ProtectionVerificationUnknown,
+ wantCoverage: ProtectionCoveragePartial,
+ wantText: "cannot confirm a backup",
},
{
name: "permission denied is unknown",
@@ -142,7 +156,7 @@ func TestDeriveProtectionPostureTruthTable(t *testing.T) {
wantFresh: ProtectionFreshnessCurrent,
wantVerify: ProtectionVerificationVerified,
wantCoverage: ProtectionCoverageUnknown,
- wantText: "permissions are unavailable",
+ wantText: "cannot read the backup history",
},
{
name: "confirmed PBS recovery is not invalidated by an unknown legacy provider",
@@ -166,7 +180,7 @@ func TestDeriveProtectionPostureTruthTable(t *testing.T) {
wantFresh: ProtectionFreshnessCurrent,
wantVerify: ProtectionVerificationVerified,
wantCoverage: ProtectionCoverageUnknown,
- wantText: "does not invalidate",
+ wantText: "does not change this backup",
},
{
name: "no provider evidence is unknown",
@@ -175,7 +189,7 @@ func TestDeriveProtectionPostureTruthTable(t *testing.T) {
wantFresh: ProtectionFreshnessUnknown,
wantVerify: ProtectionVerificationUnknown,
wantCoverage: ProtectionCoverageUnknown,
- wantText: "no complete provider history",
+ wantText: "no readable backup history",
},
}
@@ -338,7 +352,7 @@ func TestBuildProtectionPostureDoesNotTreatSuccessfulTaskAsAvailableBackup(t *te
if got.LastSuccessfulPointAt != nil {
t.Fatalf("last successful point = %v, want nil for task-only evidence", got.LastSuccessfulPointAt)
}
- if !strings.Contains(got.Explanation, "no qualifying subject-linked backup") {
+ if !strings.Contains(got.Explanation, "found no backup") {
t.Fatalf("explanation = %q, want no qualifying backup", got.Explanation)
}
}
@@ -436,3 +450,23 @@ func TestDeriveProtectionPostureFailsClosedToDefaultPolicy(t *testing.T) {
t.Fatalf("freshness = %q, want current after default-policy fallback", posture.Freshness)
}
}
+
+func TestFormatPostureWindowReadsAsDaysOrHours(t *testing.T) {
+ for _, tc := range []struct {
+ window time.Duration
+ want string
+ }{
+ {7 * 24 * time.Hour, "7 days"},
+ {24 * time.Hour, "1 day"},
+ {36 * time.Hour, "36 hours"},
+ {time.Hour, "1 hour"},
+ {30 * time.Minute, "30 minutes"},
+ {90 * time.Minute, "90 minutes"},
+ {time.Minute, "1 minute"},
+ {0, "0 minutes"},
+ } {
+ if got := formatPostureWindow(tc.window); got != tc.want {
+ t.Fatalf("formatPostureWindow(%s) = %q, want %q", tc.window, got, tc.want)
+ }
+ }
+}