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.

Keep retained guest memory distinct from current observations

pulse-triage[bot]835f88576f19
diff --git a/docs/release-control/v6/internal/subsystems/api-contracts.md b/docs/release-control/v6/internal/subsystems/api-contracts.md
index cba4da2477..aa67fa3c82 100644
--- a/docs/release-control/v6/internal/subsystems/api-contracts.md
+++ b/docs/release-control/v6/internal/subsystems/api-contracts.md
@@ -20,6 +20,16 @@
## Purpose
+### Optional guest-memory observation reaches existing frontend consumers
+
+Frontend Memory and ResourceMetric model the existing optional server-owned
+`observation` fields (state, source, original observedAt). The shared wire
+reader selects only those fields and never invents an annotation for a legacy
+metric. API/canonical workload mapping preserves the selected annotation, not
+that of a conflicting platform facet. Unknown states/times stay non-current in
+the Proxmox guest drawer. Numeric selection, permissions and existing endpoint
+shape remain unchanged; hook/adapter/History controls verify this consumer.
+
### Platform connection alerts share the constructed runtime owners
The default monitor's connection-alert snapshot callback is installed only after
diff --git a/docs/release-control/v6/internal/subsystems/frontend-primitives.md b/docs/release-control/v6/internal/subsystems/frontend-primitives.md
index e12228086b..bd2fbe8a17 100644
--- a/docs/release-control/v6/internal/subsystems/frontend-primitives.md
+++ b/docs/release-control/v6/internal/subsystems/frontend-primitives.md
@@ -20,6 +20,32 @@
## Purpose
+### Guest drawers consume selected memory provenance
+
+Existing guest drawers consume optional server-owned `memory.observation` and
+selected canonical/API metric annotations without renewing their original
+observation time from resource LastSeen, disk-read deferral or another platform
+facet. `useWorkloads`, `useUnifiedResources` and the legacy resource adapter
+preserve the selected annotation. A selected unannotated metric cannot borrow a
+conflicting raw platform annotation. Raw-memory fallback retains its own
+annotation only when its numeric reading is actually selected.
+
+Proxmox VM/LXC Overview states current, last known, unavailable or freshness
+unknown with the original known UTC time and an allowlisted source label.
+Missing, unrecognised or unusable provenance is not current. Unavailable usage
+keeps known capacity but never invents zero used/free/swap measurements. History
+keeps retained/unknown numeric context separate from current legends and stored
+points, dated inspection and denied source access. Same-guest source changes
+update without resetting the drawer or refetching History. Independent valid
+PVE/Pulse Agent readings remain current even while QGA disk reads are deferred;
+unannotated unrelated platforms keep existing presentation.
+
+Connected original-source/normalizer/adapter and mounted History controls plus
+`browser-tests/guest-memory-provenance.cjs` exercise these boundaries. They do
+not establish native thaw, covered-filesystem writes, liveness, reporter relief,
+publication or an installed containing release. No route, collection, numeric
+selection, retention, alert policy or diagnostic permission is added.
+
Pulse system-alert presentation uses the existing reserved ID/metadata markers,
not the displayed name or a platform fallback. Overview and both History layouts
keep service warnings, occurrence timelines and acknowledgement usable without
@@ -49,8 +75,8 @@ requires independent thaw and writes to covered filesystems. Running power
state, an OK backup or reported agent availability establishes none of those.
Fresh same-guest evidence withdraws the precaution without a new diagnostic or
collector request. Existing filesystem provenance, metric values, History,
-Discovery/action permissions and monitoring policy are unchanged. No disk-read
-reason is used to invent memory provenance that the workload API does not expose.
+Discovery/action permissions and monitoring policy are unchanged. Memory qualification uses its own authoritative observation; disk-read state
+cannot qualify a different metric or renew its observation time.
Verification: `GuestDrawerOverview.agent-state.test.tsx` covers each current state
with/without cached version, unknown private fields, action ownership, platform
diff --git a/docs/release-control/v6/internal/subsystems/performance-and-scalability.md b/docs/release-control/v6/internal/subsystems/performance-and-scalability.md
index 0ce5bfa2c4..5315612235 100644
--- a/docs/release-control/v6/internal/subsystems/performance-and-scalability.md
+++ b/docs/release-control/v6/internal/subsystems/performance-and-scalability.md
@@ -15,6 +15,18 @@
## Purpose
+### Memory presentation does not collect or renew observations
+
+Guest-memory provenance is projected from the already-owned snapshot in the
+existing drawer. A same-guest provenance change updates the Overview/History
+label without refetching metrics History, resetting the drawer, creating chart
+points or running a diagnostic. Fixed source labels and the original known
+time replace fabricated current freshness; there is no new timer, collector or
+fleet-wide query. Connected hook and mounted sparse/provenance controls pin
+unchanged numeric selection, source isolation and no-extra-History-read
+behaviour. Browser comparisons are source/render acceptance, not native CPU,
+RSS, backup safety or installed relief measurements.
+
### Guest read-state display does not start another read
The existing workload drawer's guest-read state and backup precaution derive
diff --git a/docs/release-control/v6/internal/subsystems/storage-recovery.md b/docs/release-control/v6/internal/subsystems/storage-recovery.md
index bf835e0494..0a0168e91a 100644
--- a/docs/release-control/v6/internal/subsystems/storage-recovery.md
+++ b/docs/release-control/v6/internal/subsystems/storage-recovery.md
@@ -21,6 +21,18 @@
## Purpose
+### Guest-memory read state stays independent of backup disk state
+
+The existing guest drawer retains Core's selected memory provenance through
+both resources-API and canonical snapshot consumers. Retained memory remains
+last-known at its original observation time, even after a new poll or cleared
+backup lock. Missing provenance is unknown, unavailable memory is not zero,
+and an independent current Proxmox/Pulse Agent memory reading remains current
+while guest-agent filesystem reads are deferred. History samples and its
+access-denial boundary remain authoritative. This client repair does not run
+backup/QGA operations or establish independent thaw, covered-filesystem writes,
+liveness, resumption or delivery. Existing outage precautions remain effective.
+
### Memory provenance does not imply recoverability
Canonical metric values may carry optional selected guest memory observation
diff --git a/docs/release-control/v6/internal/subsystems/unified-resources.md b/docs/release-control/v6/internal/subsystems/unified-resources.md
index 4ad877c1d1..ae04260b9a 100644
--- a/docs/release-control/v6/internal/subsystems/unified-resources.md
+++ b/docs/release-control/v6/internal/subsystems/unified-resources.md
@@ -23,6 +23,32 @@ and sort the complete canonical change table while startup and ingestion wait.
## Purpose
+### Guest drawers consume selected memory provenance
+
+Existing guest drawers consume optional server-owned `memory.observation` and
+selected canonical/API metric annotations without renewing their original
+observation time from resource LastSeen, disk-read deferral or another platform
+facet. `useWorkloads`, `useUnifiedResources` and the legacy resource adapter
+preserve the selected annotation. A selected unannotated metric cannot borrow a
+conflicting raw platform annotation. Raw-memory fallback retains its own
+annotation only when its numeric reading is actually selected.
+
+Proxmox VM/LXC Overview states current, last known, unavailable or freshness
+unknown with the original known UTC time and an allowlisted source label.
+Missing, unrecognised or unusable provenance is not current. Unavailable usage
+keeps known capacity but never invents zero used/free/swap measurements. History
+keeps retained/unknown numeric context separate from current legends and stored
+points, dated inspection and denied source access. Same-guest source changes
+update without resetting the drawer or refetching History. Independent valid
+PVE/Pulse Agent readings remain current even while QGA disk reads are deferred;
+unannotated unrelated platforms keep existing presentation.
+
+Connected original-source/normalizer/adapter and mounted History controls plus
+`browser-tests/guest-memory-provenance.cjs` exercise these boundaries. They do
+not establish native thaw, covered-filesystem writes, liveness, reporter relief,
+publication or an installed containing release. No route, collection, numeric
+selection, retention, alert policy or diagnostic permission is added.
+
### Guest memory provenance follows metric selection
Raw Proxmox `memory.observation` preserves the guest builder's state, source
diff --git a/frontend-modern/browser-tests/guest-memory-provenance.cjs b/frontend-modern/browser-tests/guest-memory-provenance.cjs
new file mode 100644
index 0000000000..16f2b1b63b
--- /dev/null
+++ b/frontend-modern/browser-tests/guest-memory-provenance.cjs
@@ -0,0 +1,418 @@
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { chromium, webkit } = require('playwright');
+const root = '/workspace/frontend-modern';
+const output = '/workspace/tmp/guest-memory-provenance';
+const origin = 'http://127.0.0.1:5329';
+const runtime = [
+ 'frontend-modern/src/types/api.ts',
+ 'frontend-modern/src/types/resource.ts',
+ 'frontend-modern/src/utils/memoryObservation.ts',
+ 'frontend-modern/src/utils/resourceStateAdapters.ts',
+ 'frontend-modern/src/hooks/useUnifiedResources.ts',
+ 'frontend-modern/src/hooks/useWorkloads.ts',
+ 'frontend-modern/src/components/Workloads/guestDrawerModel.ts',
+ 'frontend-modern/src/components/Workloads/GuestDrawerOverview.tsx',
+ 'frontend-modern/src/components/Workloads/GuestDrawerHistory.tsx',
+];
+const hash = (p) => crypto.createHash('sha256').update(fs.readFileSync(p)).digest('hex');
+const initial = () => ({
+ state: 'last-known',
+ source: 'guest-agent-meminfo',
+ observedAt: '2026-10-04T14:00:00Z',
+ usage: 25,
+});
+const resource = (read) => {
+ const capacity = 4 * 1024 ** 3;
+ return {
+ id: read.peer ? 'fixture-b-pve1-101' : 'fixture-a-pve1-101',
+ type: 'vm',
+ name: read.peer ? 'peer-guest' : 'backup-guest',
+ status: 'online',
+ lastSeen: read.lastSeen ?? '2026-10-04T17:00:00Z',
+ sources: ['proxmox', 'agent'],
+ platformScopes: ['proxmox-pve'],
+ metrics: {
+ cpu: { percent: 10 },
+ ...(read.state === 'unavailable'
+ ? {}
+ : {
+ memory: {
+ percent: read.usage,
+ used: (capacity * read.usage) / 100,
+ total: capacity,
+ ...(read.state === undefined
+ ? {}
+ : {
+ observation: {
+ state: read.state,
+ source: read.source ?? '',
+ ...(read.observedAt ? { observedAt: read.observedAt } : {}),
+ },
+ }),
+ },
+ }),
+ disk: { percent: 50, total: capacity, used: capacity / 2 },
+ },
+ proxmox: {
+ vmid: 101,
+ nodeName: 'pve1',
+ instance: read.peer ? 'fixture-b' : 'fixture-a',
+ runtimeStatus: 'running',
+ guestAgentStatus: 'deferred',
+ guestAgentExpected: true,
+ diskStatusReason: 'prev-vm-locked',
+ lock: 'backup',
+ memory: {
+ total: capacity,
+ usageUnavailable: read.state === 'unavailable',
+ observation: { state: 'current', source: 'status-mem', observedAt: '2026-10-04T17:00:00Z' },
+ },
+ },
+ };
+};
+(async () => {
+ fs.mkdirSync(output, { recursive: true });
+ const result = {
+ result: 'incomplete',
+ playwright: require('playwright/package.json').version,
+ runtime_hashes: Object.fromEntries(runtime.map((p) => [p, hash('/workspace/' + p)])),
+ cases: [],
+ screenshots: [],
+ limits:
+ 'Production drawer/history/model with real raw, API, unified API and canonical full/delta/fast consumers. Synthetic source payloads, History replies and disconnected websocket metadata. No full App, native QGA/thaw, filesystem writes, physical phone, reporter, installed or publication acceptance.',
+ };
+ assert.equal(
+ result.playwright,
+ JSON.parse(fs.readFileSync('/workspace/tests/integration/package-lock.json')).packages[
+ 'node_modules/@playwright/test'
+ ].version,
+ );
+ process.chdir(root);
+ const { createServer } = await import(path.join(root, 'node_modules/vite/dist/node/index.js'));
+ const server = await createServer({
+ root,
+ configFile: path.join(root, 'vite.config.ts'),
+ cacheDir: output + '/cache',
+ server: { host: '127.0.0.1', port: 5329, strictPort: true },
+ });
+ let browser;
+ try {
+ await server.listen();
+ for (const [name, engine, width, dark] of [
+ ['desktop-light', chromium, 1365, false],
+ ['desktop-dark', chromium, 1365, true],
+ ['phone-dark', webkit, 390, true],
+ ['narrow-light', webkit, 320, false],
+ ]) {
+ browser = await engine.launch(
+ engine === chromium
+ ? { headless: true, channel: 'chromium', args: ['--no-sandbox'] }
+ : { headless: true },
+ );
+ for (const transport of [
+ 'raw',
+ 'api',
+ 'unified-api',
+ 'canonical-full',
+ 'canonical-delta',
+ 'canonical-fast',
+ ]) {
+ const page = await browser.newPage({
+ viewport: { width, height: width < 768 ? 844 : 900 },
+ isMobile: width < 768,
+ hasTouch: width < 768,
+ locale: 'en-GB',
+ timezoneId: 'UTC',
+ });
+ page.setDefaultTimeout(15000);
+ page.setDefaultNavigationTimeout(60000);
+ let read = initial(),
+ mode = 'empty';
+ const record = {
+ name,
+ transport,
+ width,
+ dark,
+ browser: browser.version(),
+ errors: [],
+ requests: [],
+ states: [],
+ };
+ result.cases.push(record);
+ page.on('pageerror', (e) => record.errors.push(e.message));
+ await page.route('**/*', async (route) => {
+ const url = new URL(route.request().url());
+ if (url.origin !== origin) {
+ record.requests.push({ blocked: true, origin: url.origin });
+ return route.abort();
+ }
+ if (!url.pathname.startsWith('/api/')) return route.continue();
+ record.requests.push({ path: url.pathname, method: route.request().method() });
+ assert.equal(route.request().method(), 'GET');
+ if (url.pathname === '/api/resources')
+ return route.fulfill({ json: { data: [resource(read)], meta: { totalPages: 1 } } });
+ if (url.pathname === '/api/metrics-store/history') {
+ if (mode === 'denied')
+ return route.fulfill({ status: 403, json: { error: 'private fixture refusal' } });
+ const start = Date.UTC(2026, 9, 4, 14),
+ end = Date.UTC(2026, 9, 4, 17),
+ point = (timestamp, value) => ({ timestamp, value, min: value, max: value });
+ return route.fulfill({
+ json: {
+ resourceType: url.searchParams.get('resourceType'),
+ resourceId: url.searchParams.get('resourceId'),
+ range: url.searchParams.get('range'),
+ start,
+ end,
+ metrics:
+ mode === 'stored'
+ ? {
+ memory: [point(start, 20), point(end, 30)],
+ cpu: [point(start, 10), point(end, 15)],
+ }
+ : {},
+ source: 'store',
+ },
+ });
+ }
+ return route.fulfill({
+ json:
+ url.pathname === '/api/license/runtime-capabilities'
+ ? {
+ capabilities: [],
+ limits: [],
+ max_history_days: 7,
+ hosted_mode: false,
+ runtime: { build: 'community' },
+ blocked_capabilities: [],
+ }
+ : { success: true, data: [], alerts: [], anomalies: [], config: null },
+ });
+ });
+ await page.addInitScript(
+ (value) =>
+ document.addEventListener('DOMContentLoaded', () => {
+ if (value) document.documentElement.classList.add('dark');
+ }),
+ dark,
+ );
+ await page.goto(
+ origin + '/browser-tests/guest-memory-provenance.html?transport=' + transport,
+ );
+ const drawer = page.getByRole('region', { name: 'Guest details' });
+ await drawer.getByText('Memory reading', { exact: true }).waitFor();
+ const overview = drawer.getByRole('tab', { name: 'Overview', exact: true });
+ const history = drawer.getByRole('tab', { name: 'History', exact: true });
+ const activate = async (control) => {
+ if (width < 768) await control.tap();
+ else {
+ await control.focus();
+ await page.keyboard.press('Enter');
+ }
+ };
+ // ObjectDrawerHeader deliberately extends its collapse hit area by
+ // four pixels into the surrounding padding. Its region scrollWidth is
+ // not a text-clipping measure. Check the actual reading cell and the
+ // page viewport instead, including retained and unknown long labels.
+ const checkReadingLayout = async (state) => {
+ const row = drawer.getByText('Memory reading', { exact: true }).locator('..');
+ const cell = row.locator('td').nth(1);
+ const layout = await cell.evaluate((element) => {
+ const text = element.querySelector('span');
+ const bounds = element.getBoundingClientRect();
+ const valueBounds = text.getBoundingClientRect();
+ const style = getComputedStyle(text);
+ return {
+ documentWidth: document.documentElement.clientWidth,
+ documentScrollWidth: document.documentElement.scrollWidth,
+ cell: { left: bounds.left, right: bounds.right },
+ value: {
+ left: valueBounds.left,
+ right: valueBounds.right,
+ width: text.clientWidth,
+ scrollWidth: text.scrollWidth,
+ whiteSpace: style.whiteSpace,
+ textOverflow: style.textOverflow,
+ },
+ };
+ });
+ (record.layouts ??= []).push({ state, ...layout });
+ assert(layout.documentScrollWidth <= layout.documentWidth + 1);
+ assert(layout.value.scrollWidth <= layout.value.width + 1);
+ assert(layout.value.left >= layout.cell.left - 1);
+ assert(layout.value.right <= layout.cell.right + 1);
+ assert.equal(layout.value.whiteSpace, 'normal');
+ assert.notEqual(layout.value.textOverflow, 'ellipsis');
+ };
+ const capture = async (state) => {
+ if (transport !== 'unified-api') return;
+ const file = `${name}-${state}.png`;
+ await drawer.screenshot({ path: output + '/' + file });
+ result.screenshots.push({
+ file,
+ sha256: hash(output + '/' + file),
+ name,
+ transport,
+ state,
+ });
+ };
+ const note = async (state) =>
+ record.states.push({
+ state,
+ evidence: await page.evaluate(() => window.__guestMemory.evidence()),
+ });
+ const update = async (next) => {
+ read = next;
+ await page.evaluate((value) => window.__guestMemory.update(value), next);
+ };
+ assert.match(
+ await drawer.innerText(),
+ /Last known · QEMU guest agent · 2026-10-04 14:00:00 UTC/,
+ );
+ await checkReadingLayout('retained-overview');
+ await capture('retained-overview');
+ await activate(history);
+ const chart = drawer.locator('[data-history-group="utilization"]');
+ await chart.locator('[data-history-last-known="memory"]').waitFor();
+ assert.equal(await chart.locator('[data-history-current="memory"]').count(), 0);
+ assert.match(
+ await chart.locator('[data-history-last-known="memory"]').innerText(),
+ /25\.0%.*last known/s,
+ );
+ assert.match(
+ await chart.locator('[data-history-deferred="memory"]').innerText(),
+ /14:00:00 UTC/,
+ );
+ assert.equal(await chart.locator('path').count(), 0);
+ const historyCalls = record.requests.filter(
+ (r) => r.path === '/api/metrics-store/history',
+ ).length;
+ await page.evaluate(() => {
+ window.__chartIdentity = document.querySelector('[data-history-group="utilization"]');
+ });
+ await note('retained');
+ await capture('retained-history');
+ await update({ ...initial(), lastSeen: '2026-10-04T18:00:00Z' });
+ assert.doesNotMatch(
+ await chart.locator('[data-history-deferred="memory"]').innerText(),
+ /18:00:00/,
+ );
+ await update({
+ state: 'current',
+ source: 'status-mem',
+ observedAt: '2026-10-04T17:00:00Z',
+ usage: 35,
+ });
+ await chart.locator('[data-history-current="memory"]').waitFor();
+ assert.match(
+ await chart.locator('[data-history-current="memory"]').innerText(),
+ /35\.0%.*current/s,
+ );
+ assert.equal(await chart.locator('[data-history-deferred="memory"]').count(), 0);
+ assert.equal(await chart.locator('[data-history-last-known="disk"]').count(), 1);
+ await note('independent-current-pve');
+ await update({ state: 'unavailable', source: 'unavailable', usage: 0 });
+ assert.equal(await chart.locator('[data-history-current="memory"]').count(), 0);
+ assert.equal(await chart.locator('[data-history-last-known="memory"]').count(), 0);
+ assert.match(await chart.innerText(), /Memory\s*-/);
+ await note('unavailable');
+ await update({ usage: 40 });
+ await chart.locator('[data-history-unknown="memory"]').waitFor();
+ assert.match(
+ await chart.locator('[data-history-unknown="memory"]').innerText(),
+ /40\.0%.*freshness unknown/s,
+ );
+ assert.equal(await chart.locator('[data-history-current="memory"]').count(), 0);
+ assert.equal(await chart.locator('[data-history-last-known="memory"]').count(), 0);
+ assert.equal(
+ await page.evaluate(
+ () =>
+ window.__chartIdentity ===
+ document.querySelector('[data-history-group="utilization"]'),
+ ),
+ true,
+ );
+ assert.equal(
+ record.requests.filter((r) => r.path === '/api/metrics-store/history').length,
+ historyCalls,
+ );
+ await activate(overview);
+ assert.match(await drawer.innerText(), /Freshness unknown · Unknown source · time unknown/);
+ await checkReadingLayout('unknown-overview');
+ await capture('unknown-overview');
+ await note('legacy-unknown');
+ await activate(history);
+ await update({ state: 'last-known', source: 'private provider detail', usage: 0 });
+ await chart.locator('[data-history-last-known="memory"]').waitFor();
+ assert.match(
+ await chart.locator('[data-history-last-known="memory"]').innerText(),
+ /0\.0%.*last known/s,
+ );
+ assert.match(
+ await chart.locator('[data-history-deferred="memory"]').innerText(),
+ /Observation time unknown/,
+ );
+ assert.doesNotMatch(await drawer.innerText(), /private provider detail/);
+ await note('retained-zero-unknown-age');
+ mode = 'stored';
+ await activate(drawer.getByRole('button', { name: 'Refresh history', exact: true }));
+ await page.waitForFunction(
+ () => document.querySelectorAll('[data-history-group="utilization"] path').length === 2,
+ );
+ assert.equal(await chart.locator('[data-history-current="memory"]').count(), 0);
+ assert.equal(await chart.locator('[data-history-last-known="memory"]').count(), 0);
+ assert.match(await chart.innerText(), /Memory\s*30\.0%/);
+ const slider = chart.getByRole('slider');
+ await slider.focus();
+ await page.keyboard.press('Home');
+ assert.match(await slider.getAttribute('aria-valuetext'), /Memory 20\.0%/);
+ await note('stored-keyboard-inspection');
+ mode = 'denied';
+ await activate(drawer.getByRole('button', { name: 'Refresh history', exact: true }));
+ await drawer.getByRole('button', { name: 'Retry history', exact: true }).waitFor();
+ assert.equal(await drawer.locator('[data-history-deferred]').count(), 0);
+ assert.equal(await drawer.locator('[data-history-group]').count(), 0);
+ assert.doesNotMatch(await drawer.innerText(), /private fixture refusal/);
+ mode = 'empty';
+ await activate(drawer.getByRole('button', { name: 'Retry history', exact: true }));
+ await chart.locator('[data-history-last-known="memory"]').waitFor();
+ await note('denied-and-recovered');
+ await update({
+ peer: true,
+ state: 'current',
+ source: 'agent',
+ observedAt: '2026-10-04T16:00:00Z',
+ usage: 70,
+ });
+ await drawer.getByText('peer-guest', { exact: true }).waitFor();
+ assert.equal(await overview.getAttribute('aria-selected'), 'true');
+ assert.match(await drawer.innerText(), /Current · Pulse Agent · 2026-10-04 16:00:00 UTC/);
+ assert.doesNotMatch(await drawer.innerText(), /14:00:00 UTC/);
+ await note('peer-identity-replacement');
+ await checkReadingLayout('peer-overview');
+ assert.deepEqual(record.errors, []);
+ assert(record.requests.every((r) => !r.blocked && r.method === 'GET'));
+ await page.close();
+ }
+ await browser.close();
+ browser = undefined;
+ }
+ result.result = 'passed';
+ fs.writeFileSync(output + '/result.json', JSON.stringify(result, null, 2) + '\n');
+ process.stdout.write(
+ `Guest memory provenance: ${result.cases.length} transport/layout cases passed.\n`,
+ );
+ } catch (error) {
+ fs.writeFileSync(
+ output + '/failure.json',
+ JSON.stringify({ error: String(error), stack: error.stack, result }, null, 2) + '\n',
+ );
+ throw error;
+ } finally {
+ if (browser) await browser.close();
+ await server.close();
+ }
+})();
diff --git a/frontend-modern/browser-tests/guest-memory-provenance.html b/frontend-modern/browser-tests/guest-memory-provenance.html
new file mode 100644
index 0000000000..7a8916a1c3
--- /dev/null
+++ b/frontend-modern/browser-tests/guest-memory-provenance.html
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+ <head>
+ <meta charset="UTF-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <title>Guest memory provenance evidence</title>
+ </head>
+ <body>
+ <div id="root"></div>
+ <script type="module" src="/browser-tests/guest-memory-provenance.tsx"></script>
+ </body>
+</html>
diff --git a/frontend-modern/browser-tests/guest-memory-provenance.tsx b/frontend-modern/browser-tests/guest-memory-provenance.tsx
new file mode 100644
index 0000000000..a33edaeac4
--- /dev/null
+++ b/frontend-modern/browser-tests/guest-memory-provenance.tsx
@@ -0,0 +1,213 @@
+// Production hook/adapter/drawer consumers, synthetic source snapshots only.
+import { createSignal, Show } from 'solid-js';
+import { render } from 'solid-js/web';
+import { Router, Route } from '@solidjs/router';
+import { useWorkloads } from '../src/hooks/useWorkloads';
+import { useUnifiedResources } from '../src/hooks/useUnifiedResources';
+import {
+ mergeCanonicalResourceSnapshot,
+ mergeCanonicalResourceDeltaSnapshot,
+} from '../src/utils/resourceStateAdapters';
+import { GuestDrawer } from '../src/components/Workloads/GuestDrawer';
+import { DarkModeContext } from '../src/contexts/appRuntime';
+import { syncAIRuntimeSettings } from '../src/stores/aiRuntimeState';
+import type { Resource } from '../src/types/resource';
+import type { MemoryObservation } from '../src/types/api';
+import type { WorkloadGuest } from '../src/types/workloads';
+import '../src/index.css';
+
+syncAIRuntimeSettings({ discovery_enabled: false });
+interface Reading {
+ state?: string;
+ source?: string;
+ observedAt?: string;
+ usage: number;
+ lastSeen?: string;
+ peer?: boolean;
+}
+const initial: Reading = {
+ state: 'last-known',
+ source: 'guest-agent-meminfo',
+ observedAt: '2026-10-04T14:00:00Z',
+ usage: 25,
+};
+const observation = (read: Reading): MemoryObservation | undefined =>
+ read.state === undefined
+ ? undefined
+ : {
+ state: read.state,
+ source: read.source ?? '',
+ ...(read.observedAt ? { observedAt: read.observedAt } : {}),
+ };
+const capacity = 4 * 1024 ** 3;
+const id = (read: Reading) => (read.peer ? 'fixture-b-pve1-101' : 'fixture-a-pve1-101');
+const nativeResource = (read: Reading): Resource => ({
+ id: id(read),
+ type: 'vm',
+ name: read.peer ? 'peer-guest' : 'backup-guest',
+ displayName: read.peer ? 'peer-guest' : 'backup-guest',
+ status: 'online',
+ sources: ['proxmox', 'agent'],
+ platformType: 'proxmox-pve',
+ platformScopes: ['proxmox-pve'],
+ sourceType: 'hybrid',
+ lastSeen: Date.parse(read.lastSeen ?? '2026-10-04T17:00:00Z'),
+ cpu: { current: 10 },
+ memory:
+ read.state === 'unavailable'
+ ? undefined
+ : {
+ current: read.usage,
+ used: (capacity * read.usage) / 100,
+ total: capacity,
+ ...(observation(read) ? { observation: observation(read) } : {}),
+ },
+ disk: { current: 50, used: capacity / 2, total: capacity },
+ proxmox: {
+ vmid: 101,
+ nodeName: 'pve1',
+ instance: read.peer ? 'fixture-b' : 'fixture-a',
+ runtimeStatus: 'running',
+ guestAgentStatus: 'deferred',
+ guestAgentExpected: true,
+ diskStatusReason: 'prev-vm-locked',
+ lock: 'backup',
+ memory: {
+ total: capacity,
+ used: capacity / 2,
+ free: capacity / 2,
+ usage: 50,
+ usageUnavailable: read.state === 'unavailable',
+ observation: { state: 'current', source: 'status-mem', observedAt: '2026-10-04T17:00:00Z' },
+ },
+ },
+});
+const rawGuest = (read: Reading): WorkloadGuest => ({
+ id: id(read),
+ vmid: 101,
+ name: read.peer ? 'peer-guest' : 'backup-guest',
+ instance: read.peer ? 'fixture-b' : 'fixture-a',
+ node: 'pve1',
+ type: 'qemu',
+ status: 'running',
+ cpu: 0.1,
+ cpus: 2,
+ memory: {
+ total: capacity,
+ used: (capacity * read.usage) / 100,
+ free: (capacity * (100 - read.usage)) / 100,
+ usage: read.usage,
+ usageUnavailable: read.state === 'unavailable',
+ ...(observation(read) ? { observation: observation(read) } : {}),
+ },
+ disk: { usage: 50, total: capacity, used: capacity / 2 },
+ diskStatusReason: 'prev-vm-locked',
+ lock: 'backup',
+ guestAgentStatus: 'deferred',
+ guestAgentExpected: true,
+ networkIn: 10,
+ networkOut: 20,
+ diskRead: 30,
+ diskWrite: 40,
+ uptime: 3600,
+ template: false,
+ lastBackup: 0,
+ lastSeen: read.lastSeen ?? '2026-10-04T17:00:00Z',
+ tags: [],
+});
+// Only the websocket transport is synthetic. API conversion and owned hooks
+// remain production code, with real requests fulfilled by the bounded script.
+window.__pulseWsStore = {
+ state: { resources: [], activeAlerts: [], recentlyResolved: [] },
+ connected: () => false,
+ initialDataReceived: () => true,
+ resourceSnapshotReceived: () => false,
+ resourceChange: () => ({ version: 0, changedIds: null, changedKeys: null }),
+ changedResourceMetaSince: () => null,
+ changedResourceIdsSince: () => null,
+ shutdown: () => {},
+} as unknown as NonNullable<typeof window.__pulseWsStore>;
+function Fixture() {
+ const transport = new URLSearchParams(window.location.search).get('transport') ?? 'api';
+ const [read, setRead] = createSignal(initial);
+ const [snapshot, setSnapshot] = createSignal<Resource[]>([nativeResource(initial)]);
+ const unified =
+ transport === 'unified-api'
+ ? useUnifiedResources({ query: 'type=vm', realtimeEnabled: () => false })
+ : null;
+ const workloads =
+ transport === 'raw'
+ ? null
+ : useWorkloads(
+ () => true,
+ transport === 'api'
+ ? {}
+ : { resourceSnapshot: unified ? () => unified.resources() : snapshot },
+ );
+ const guest = () => (transport === 'raw' ? rawGuest(read()) : workloads!.workloads()[0]);
+ (window as any).__guestMemory = {
+ update: async (next: Reading) => {
+ setRead(next);
+ if (transport === 'raw') return;
+ if (transport === 'api') {
+ await workloads!.refetch();
+ return;
+ }
+ if (unified) {
+ await unified.refetch();
+ return;
+ }
+ const incoming = nativeResource(next);
+ setSnapshot((previous) =>
+ transport === 'canonical-full' || next.peer
+ ? mergeCanonicalResourceSnapshot([incoming], previous)
+ : mergeCanonicalResourceDeltaSnapshot(
+ [incoming],
+ previous,
+ new Set([incoming.id]),
+ transport === 'canonical-fast'
+ ? new Map([[incoming.id, ['memory', 'proxmox', 'lastSeen']]])
+ : undefined,
+ ),
+ );
+ },
+ evidence: () => ({
+ id: guest()?.id,
+ observation: guest()?.memory.observation,
+ usage: guest()?.memory.usage,
+ unavailable: guest()?.memory.usageUnavailable,
+ }),
+ };
+ return (
+ <main class="mx-auto min-h-screen max-w-5xl space-y-3 bg-surface p-3 text-base-content">
+ <h1 class="text-base font-semibold">Guest memory evidence</h1>
+ <p class="text-xs text-muted">
+ Synthetic {transport} observations. No guest checks are sent.
+ </p>
+ <Show when={guest()}>
+ {() => (
+ <section aria-label="Guest details">
+ <GuestDrawer guest={guest()!} onClose={() => {}} />
+ </section>
+ )}
+ </Show>
+ </main>
+ );
+}
+render(
+ () => (
+ <Router>
+ <Route
+ path="*"
+ component={() => (
+ <DarkModeContext.Provider
+ value={() => document.documentElement.classList.contains('dark')}
+ >
+ <Fixture />
+ </DarkModeContext.Provider>
+ )}
+ />
+ </Router>
+ ),
+ document.getElementById('root')!,
+);
diff --git a/frontend-modern/browser-verification/aca8311c65fac54f.json b/frontend-modern/browser-verification/aca8311c65fac54f.json
new file mode 100644
index 0000000000..6beb5131a5
--- /dev/null
+++ b/frontend-modern/browser-verification/aca8311c65fac54f.json
@@ -0,0 +1,77 @@
+{
+ "version": 1,
+ "result": "passed",
+ "base_sha": "3d846f76d724b1853a3ea58201cfc6eb7e25b084",
+ "changed_paths": [
+ "frontend-modern/src/components/Workloads/GuestDrawerHistory.tsx",
+ "frontend-modern/src/components/Workloads/GuestDrawerOverview.tsx",
+ "frontend-modern/src/components/Workloads/guestDrawerModel.ts",
+ "frontend-modern/src/hooks/useUnifiedResources.ts",
+ "frontend-modern/src/hooks/useWorkloads.ts",
+ "frontend-modern/src/types/api.ts",
+ "frontend-modern/src/types/resource.ts",
+ "frontend-modern/src/utils/memoryObservation.ts",
+ "frontend-modern/src/utils/resourceStateAdapters.ts"
+ ],
+ "content_sha256": {
+ "frontend-modern/src/types/api.ts": "f5805a599793431a45c5a88341cc8af4ad1a05787ce51d75b9fbb75f5dcf5606",
+ "frontend-modern/src/types/resource.ts": "daffee073bb11699518d9c45aeb8075d4e53535ee6f385b0dffb8d06a05c670d",
+ "frontend-modern/src/utils/memoryObservation.ts": "a9ef178ff58cf9ab3e622af3a6cceb9e9da9f42e03b2d246fe73ab22e8a3bf1e",
+ "frontend-modern/src/utils/resourceStateAdapters.ts": "f55c5ff10daafad9b6c577f68777696329c69e0b0bb2c13ec662c7c7d59e4e29",
+ "frontend-modern/src/hooks/useUnifiedResources.ts": "e4ea180cd2e372eab77414ae96d9c180ad706b67b2619a67f29bb046e38a55ef",
+ "frontend-modern/src/hooks/useWorkloads.ts": "0915943dd0cbb65940ab75a3e1143a80eda53c32db485181d56948e640f9e66d",
+ "frontend-modern/src/components/Workloads/guestDrawerModel.ts": "c4e4d5f2ecd0d65cba73b14d400af0f8eacae10965d1ad9b499dfc1b03ac658d",
+ "frontend-modern/src/components/Workloads/GuestDrawerOverview.tsx": "2c72e3b40e311c91ee789724ac72cde01ebe36166c1f23a462a320d1a7f03add",
+ "frontend-modern/src/components/Workloads/GuestDrawerHistory.tsx": "5d592a9c3422a20e4596d25dc673f894219663c80392240ea1094ccd282e0848"
+ },
+ "routes": [
+ "/browser-tests/guest-memory-provenance.html?transport=raw",
+ "/browser-tests/guest-memory-provenance.html?transport=api",
+ "/browser-tests/guest-memory-provenance.html?transport=unified-api",
+ "/browser-tests/guest-memory-provenance.html?transport=canonical-full",
+ "/browser-tests/guest-memory-provenance.html?transport=canonical-delta",
+ "/browser-tests/guest-memory-provenance.html?transport=canonical-fast"
+ ],
+ "states": [
+ "retained QGA memory with original observation time",
+ "repeated deferral without renewing age or History reads",
+ "independent current PVE memory despite disk deferral",
+ "unavailable memory without fabricated zero/free measurement",
+ "legacy unknown memory without borrowing conflicting platform provenance",
+ "retained measured zero with unknown source/time",
+ "stored points and dated keyboard inspection",
+ "403 concealment followed by permitted recovery",
+ "same-guest replacement without chart remount; peer identity replacement resets drawer"
+ ],
+ "interactions": [
+ "keyboard Enter and touch select real drawer tabs and Refresh/Retry",
+ "Home key inspects stored history through the accessible slider",
+ "production raw/API/unified/canonical full/delta/fast consumer updates",
+ "reading-cell wrapping and page-width checks at all viewports",
+ "only bounded synthetic GET responses; no mutations or guest diagnostics",
+ "twelve captured and inspected light/dark Overview/History images, including 390px and 320px"
+ ],
+ "viewports": [
+ {
+ "width": 1365,
+ "height": 900
+ },
+ {
+ "width": 390,
+ "height": 844
+ },
+ {
+ "width": 320,
+ "height": 844
+ }
+ ],
+ "verified_at": "2026-10-04T19:16:25Z",
+ "browsers": [
+ "141.0.7390.37",
+ "26.0"
+ ],
+ "playwright_version": "1.56.1",
+ "proof_script": "frontend-modern/browser-tests/guest-memory-provenance.cjs",
+ "proof_cases": 24,
+ "limits": "Production drawer/history/model with real raw, API, unified API and canonical full/delta/fast consumers. Synthetic source payloads, History replies and disconnected websocket metadata. No full App, native QGA/thaw, filesystem writes, physical phone, reporter, installed or publication acceptance."
+}
diff --git a/frontend-modern/src/components/Workloads/GuestDrawerHistory.tsx b/frontend-modern/src/components/Workloads/GuestDrawerHistory.tsx
index c8881b9407..1f1ace5910 100644
--- a/frontend-modern/src/components/Workloads/GuestDrawerHistory.tsx
+++ b/frontend-modern/src/components/Workloads/GuestDrawerHistory.tsx
@@ -328,7 +328,8 @@ const GuestDrawerHistoryGroupChart: Component<GuestDrawerHistoryGroupChartProps>
deferred,
descriptionId: `${inspectionId}-deferred-${index}`,
isCurrent: isFallback && !deferred,
- isLastKnown: isFallback && Boolean(deferred),
+ isLastKnown: isFallback && Boolean(deferred) && !deferred?.valueLabel,
+ isUnknown: isFallback && deferred?.valueLabel === 'freshness unknown',
valueLabel: hovered
? getGuestDrawerHistoryValueLabel([hovered.point], item.unit)
: activeTimestamp() !== null
@@ -393,6 +394,7 @@ const GuestDrawerHistoryGroupChart: Component<GuestDrawerHistoryGroupChartProps>
class="inline-flex items-center gap-1"
data-history-current={item.isCurrent ? item.metric : undefined}
data-history-last-known={item.isLastKnown ? item.metric : undefined}
+ data-history-unknown={item.isUnknown ? item.metric : undefined}
aria-describedby={item.deferred ? item.descriptionId : undefined}
>
<svg aria-hidden="true" class="h-2.5 w-2.5 shrink-0" viewBox="0 0 10 10">
@@ -403,6 +405,9 @@ const GuestDrawerHistoryGroupChart: Component<GuestDrawerHistoryGroupChartProps>
<Show when={item.isCurrent}>
<span>current</span>
</Show>
+ <Show when={item.isUnknown}>
+ <span>freshness unknown</span>
+ </Show>
<Show when={item.isLastKnown}>
<span>last known</span>
</Show>
@@ -419,7 +424,7 @@ const GuestDrawerHistoryGroupChart: Component<GuestDrawerHistoryGroupChartProps>
class="mb-2 text-xs leading-relaxed text-muted"
data-history-deferred={item.metric}
>
- {item.label} live reading: {item.deferred?.message}
+ {item.label} reading: {item.deferred?.message}
</p>
)}
</For>
@@ -637,11 +642,10 @@ export const GuestDrawerHistory: Component<GuestDrawerHistoryProps> = (props) =>
});
const locked = createMemo(() => isRangeLocked(props.range));
- const historyQuery = createNonSuspendingQuery<
- AllMetricsHistoryResponse,
- GuestDrawerHistoryQueryKey
- >({
- source: () => {
+ // Snapshot replacement often creates a new target object with unchanged
+ // coordinates. Only a real target/range/access change owns a new read.
+ const historySource = createMemo<GuestDrawerHistoryQueryKey | null>(
+ () => {
const target = props.target;
if (!target || locked()) return null;
return {
@@ -650,6 +654,24 @@ export const GuestDrawerHistory: Component<GuestDrawerHistoryProps> = (props) =>
range: props.range,
};
},
+ null,
+ {
+ equals: (previous, next) =>
+ previous === next ||
+ Boolean(
+ previous &&
+ next &&
+ previous.resourceType === next.resourceType &&
+ previous.resourceId === next.resourceId &&
+ previous.range === next.range,
+ ),
+ },
+ );
+ const historyQuery = createNonSuspendingQuery<
+ AllMetricsHistoryResponse,
+ GuestDrawerHistoryQueryKey
+ >({
+ source: historySource,
fetcher: async (key, signal) =>
normalizeHistoryResponse(
await ChartsAPI.getMetricsHistory({
diff --git a/frontend-modern/src/components/Workloads/GuestDrawerOverview.tsx b/frontend-modern/src/components/Workloads/GuestDrawerOverview.tsx
index a118a6cd1e..d03798cb7c 100644
--- a/frontend-modern/src/components/Workloads/GuestDrawerOverview.tsx
+++ b/frontend-modern/src/components/Workloads/GuestDrawerOverview.tsx
@@ -23,6 +23,7 @@ import { buildWorkloadsDiskPresentation } from './diskListModel';
import {
getGuestDrawerAlertMessage,
getGuestDrawerMemoryRows,
+ getGuestDrawerMemoryReading,
getGuestDrawerGuestReadPresentation,
isGuestDrawerVM,
} from './guestDrawerModel';
@@ -94,6 +95,9 @@ export function GuestDrawerOverview(props: GuestDrawerOverviewProps) {
tone: guestReadPresentation()?.tone,
wrap: true,
}),
+ makeDetailRow('Memory reading', getGuestDrawerMemoryReading(props.guest)?.summary, {
+ wrap: true,
+ }),
makeDetailRow('Primary IP', props.ipAddresses[0]),
// Starting or ending an operation is not evidence of a completed
// backup. Keep its activity separate from the last completed age.
diff --git a/frontend-modern/src/components/Workloads/__tests__/GuestDrawerHistory.disk-provenance.test.tsx b/frontend-modern/src/components/Workloads/__tests__/GuestDrawerHistory.disk-provenance.test.tsx
index 6c1bcb45e5..238a40f0df 100644
--- a/frontend-modern/src/components/Workloads/__tests__/GuestDrawerHistory.disk-provenance.test.tsx
+++ b/frontend-modern/src/components/Workloads/__tests__/GuestDrawerHistory.disk-provenance.test.tsx
@@ -30,7 +30,13 @@ const guest = (reason: string, usage = 50): WorkloadGuest => ({
status: 'running',
cpu: 0.1,
cpus: 2,
- memory: { total: 100, used: 25, free: 75, usage: 25 },
+ memory: {
+ total: 100,
+ used: 25,
+ free: 75,
+ usage: 25,
+ observation: { state: 'current', source: 'status-mem', observedAt: '2026-10-04T03:00:00Z' },
+ },
disk: { total: 100, used: usage, usage },
networkIn: 100,
networkOut: 200,
@@ -86,7 +92,7 @@ describe('GuestDrawerHistory filesystem provenance', () => {
const retained = chart.querySelector('[data-history-last-known="disk"]')!;
expect(retained).toHaveTextContent('Disk50.0%last known');
expect(retained).toHaveAccessibleDescription(
- `Disk live reading: Using last known disk stats. ${message}`,
+ `Disk reading: Using last known disk stats. ${message}`,
);
expect(chart.querySelector('[data-history-deferred="disk"]')).toBeVisible();
expect(chart.querySelector('[data-history-current="cpu"]')).toHaveTextContent(
diff --git a/frontend-modern/src/components/Workloads/__tests__/GuestDrawerHistory.memory-provenance.test.tsx b/frontend-modern/src/components/Workloads/__tests__/GuestDrawerHistory.memory-provenance.test.tsx
index 918c6cce6c..86f106771d 100644
--- a/frontend-modern/src/components/Workloads/__tests__/GuestDrawerHistory.memory-provenance.test.tsx
+++ b/frontend-modern/src/components/Workloads/__tests__/GuestDrawerHistory.memory-provenance.test.tsx
@@ -9,6 +9,7 @@ import {
getGuestDrawerCurrentMetrics,
getGuestDrawerDeferredMetrics,
getGuestDrawerMemoryRows,
+ getGuestDrawerMemoryReading,
} from '../guestDrawerModel';
vi.mock('@/stores/license', () => ({
@@ -92,10 +93,7 @@ describe('guest memory original-observation provenance', () => {
lastKnownValue: 25,
message: expect.stringContaining('2026-10-04 14:00:00 UTC'),
});
- expect(getGuestDrawerMemoryRows(value)).toContainEqual({
- label: 'Reading',
- value: expect.stringContaining('Last known'),
- });
+ expect(getGuestDrawerMemoryReading(value)?.summary).toContain('Last known');
expect(getGuestDrawerCurrentMetrics(value)).toMatchObject({ cpu: 10, disk: 50, netin: 100 });
},
);
@@ -156,7 +154,21 @@ describe('guest memory original-observation provenance', () => {
).toBeUndefined();
});
+ it('retains unknown original age without exposing a raw source string', () => {
+ const value = guest({ state: 'last-known', source: 'private provider detail' });
+ expect(getGuestDrawerMemoryReading(value)?.summary).toBe(
+ 'Last known · Unknown source · time unknown',
+ );
+ expect(getGuestDrawerDeferredMetrics(value).memory.message).toContain(
+ 'Observation time unknown.',
+ );
+ expect(getGuestDrawerDeferredMetrics(value).memory.message).not.toContain(
+ 'private provider detail',
+ );
+ });
+
it('retains measured zero and leaves unannotated non-Proxmox data unchanged', () => {
+ expect(getGuestDrawerDeferredMetrics(guest(annotation('last-known'), 0)).memory).toBeDefined();
expect(
getGuestDrawerDeferredMetrics(guest(annotation('last-known'), 0)).memory.lastKnownValue,
).toBe(0);
diff --git a/frontend-modern/src/components/Workloads/__tests__/GuestDrawerHistory.sparse.test.tsx b/frontend-modern/src/components/Workloads/__tests__/GuestDrawerHistory.sparse.test.tsx
index 5ca01afbf3..2d428eca9e 100644
--- a/frontend-modern/src/components/Workloads/__tests__/GuestDrawerHistory.sparse.test.tsx
+++ b/frontend-modern/src/components/Workloads/__tests__/GuestDrawerHistory.sparse.test.tsx
@@ -49,6 +49,65 @@ const group = (id = 'utilization') =>
const dots = () => document.querySelectorAll('[data-history-observation]');
describe('GuestDrawerHistory sparse observations and current provenance', () => {
+ it('reads again only for changed coordinates, not a fresh same-target snapshot object', async () => {
+ const fetch = vi.spyOn(ChartsAPI, 'getMetricsHistory').mockResolvedValue(response());
+ const [source, setSource] = createSignal(target);
+ const [usage, setUsage] = createSignal(25);
+ render(() => (
+ <GuestDrawerHistory target={source()} range="1h" currentMetrics={{ memory: usage() }} />
+ ));
+ await waitFor(() =>
+ expect(screen.getByRole('button', { name: 'Refresh history' })).toHaveAttribute(
+ 'aria-busy',
+ 'false',
+ ),
+ );
+ const chart = group();
+ setSource({ ...target });
+ setUsage(35);
+ await waitFor(() =>
+ expect(chart.querySelector('[data-history-current="memory"]')).toHaveTextContent(
+ '35.0%current',
+ ),
+ );
+ expect(fetch).toHaveBeenCalledTimes(1);
+ expect(group()).toBe(chart);
+ setSource({ ...target, resourceId: 'peer-host' });
+ await waitFor(() => expect(fetch).toHaveBeenCalledTimes(2));
+ expect(fetch.mock.calls[1][0]).toMatchObject({ resourceId: 'peer-host' });
+ });
+
+ it('keeps unknown freshness distinct from current, last-known and stored readings', async () => {
+ vi.spyOn(ChartsAPI, 'getMetricsHistory').mockResolvedValue(response());
+ render(() => (
+ <GuestDrawerHistory
+ target={target}
+ range="1h"
+ currentMetrics={{ memory: 99 }}
+ deferredMetrics={{
+ memory: {
+ lastKnownValue: 25,
+ valueLabel: 'freshness unknown',
+ message: 'Observation time unknown. Not a current measurement.',
+ },
+ }}
+ />
+ ));
+ await waitFor(() =>
+ expect(screen.getAllByText('No stored history in this range')).toHaveLength(3),
+ );
+ expect(group().querySelector('[data-history-unknown="memory"]')).toHaveTextContent(
+ 'Memory25.0%freshness unknown',
+ );
+ expect(group().querySelector('[data-history-unknown="memory"]')).toHaveAccessibleDescription(
+ 'Memory reading: Observation time unknown. Not a current measurement.',
+ );
+ expect(group().querySelector('[data-history-current]')).toBeNull();
+ expect(group().querySelector('[data-history-last-known]')).toBeNull();
+ expect(group().querySelector('path')).toBeNull();
+ expect(dots()).toHaveLength(0);
+ });
+
it('gives explicit deferred evidence precedence over a numeric current fallback', async () => {
vi.spyOn(ChartsAPI, 'getMetricsHistory').mockResolvedValue(response());
render(() => (
@@ -67,7 +126,7 @@ describe('GuestDrawerHistory sparse observations and current provenance', () =>
'Disk50.0%last known',
);
expect(group().querySelector('[data-history-last-known="disk"]')).toHaveAccessibleDescription(
- 'Disk live reading: Guest reads paused.',
+ 'Disk reading: Guest reads paused.',
);
expect(group().querySelector('path')).toBeNull();
expect(dots()).toHaveLength(0);
diff --git a/frontend-modern/src/components/Workloads/__tests__/guestDrawerModel.branchcov2.test.ts b/frontend-modern/src/components/Workloads/__tests__/guestDrawerModel.branchcov2.test.ts
index c0e1fbd806..2ffd5318e2 100644
--- a/frontend-modern/src/components/Workloads/__tests__/guestDrawerModel.branchcov2.test.ts
+++ b/frontend-modern/src/components/Workloads/__tests__/guestDrawerModel.branchcov2.test.ts
@@ -80,7 +80,17 @@ describe('guestDrawerModel (branch coverage)', () => {
it('scales the canonical workload cpu ratio by 100 and returns finite metric values', () => {
const guest = makeGuest({
cpu: 1.0,
- memory: { total: 100, used: 40, free: 60, usage: 0.4 },
+ memory: {
+ total: 100,
+ used: 40,
+ free: 60,
+ usage: 0.4,
+ observation: {
+ state: 'current',
+ source: 'status-mem',
+ observedAt: '2026-10-04T03:00:00Z',
+ },
+ },
disk: { total: 100, used: 30, free: 70, usage: 0.3 },
networkIn: 100,
networkOut: 200,
diff --git a/frontend-modern/src/components/Workloads/guestDrawerModel.ts b/frontend-modern/src/components/Workloads/guestDrawerModel.ts
index a48cf69ec0..e511545781 100644
--- a/frontend-modern/src/components/Workloads/guestDrawerModel.ts
+++ b/frontend-modern/src/components/Workloads/guestDrawerModel.ts
@@ -65,6 +65,7 @@ export interface GuestDrawerHistoryTimeBounds {
export interface GuestDrawerHistoryDeferredMetric {
lastKnownValue?: number;
+ valueLabel?: 'freshness unknown';
message: string;
}
@@ -106,18 +107,106 @@ const getGuestDrawerDiskUsage = (guest: Guest): number | undefined => {
return typeof usage === 'number' && Number.isFinite(usage) && usage >= 0 ? usage : undefined;
};
+export interface GuestDrawerMemoryReading {
+ state: 'current' | 'last-known' | 'unavailable' | 'unknown';
+ summary: string;
+ message: string;
+}
+
+const memorySourceLabels: Record<string, string> = {
+ 'guest-agent-meminfo': 'QEMU guest agent',
+ 'guest-agent-meminfo-derived': 'QEMU guest agent',
+ agent: 'Pulse Agent',
+ 'available-field': 'Proxmox',
+ 'derived-free-buffers-cached': 'Proxmox',
+ 'derived-total-minus-used': 'Proxmox',
+ 'status-mem': 'Proxmox',
+ 'status-freemem': 'Proxmox',
+ 'cluster-resources': 'Proxmox',
+ 'previous-snapshot': 'Previous snapshot',
+};
+
+const getGuestDrawerMemoryUsage = (guest: Guest): number | undefined => {
+ const usage = guest.memory?.usage;
+ return guest.telemetryAvailability?.memory !== false &&
+ !guest.memory?.usageUnavailable &&
+ typeof usage === 'number' &&
+ Number.isFinite(usage) &&
+ usage >= 0 &&
+ usage <= 100
+ ? usage
+ : undefined;
+};
+
+export const getGuestDrawerMemoryReading = (guest: Guest): GuestDrawerMemoryReading | null => {
+ const observation = guest.memory?.observation;
+ const nonProxmoxVMware =
+ guest.platformScopes?.includes('vmware-vsphere') &&
+ !guest.platformScopes.includes('proxmox-pve');
+ const proxmoxGuest =
+ !nonProxmoxVMware &&
+ (guest.type === 'qemu' ||
+ guest.type === 'lxc' ||
+ guest.platformScopes?.includes('proxmox-pve') ||
+ (guest.vmid > 0 && Boolean(guest.node && guest.instance)));
+ // Unannotated unrelated platforms retain their existing behaviour. Legacy
+ // Proxmox readings lack authority to assert current freshness.
+ if (!proxmoxGuest && !observation) return null;
+ const timestamp =
+ typeof observation?.observedAt === 'string' ? Date.parse(observation.observedAt) : NaN;
+ const validTime = Number.isFinite(timestamp) && timestamp > 0 && timestamp <= Date.now();
+ const observed = validTime
+ ? new Date(timestamp).toISOString().replace('T', ' ').replace('.000Z', 'Z').replace('Z', ' UTC')
+ : null;
+ const state =
+ getGuestDrawerMemoryUsage(guest) === undefined || observation?.state === 'unavailable'
+ ? 'unavailable'
+ : observation?.state === 'last-known'
+ ? 'last-known'
+ : observation?.state === 'current' && validTime
+ ? 'current'
+ : 'unknown';
+ const label =
+ state === 'current'
+ ? 'Current'
+ : state === 'last-known'
+ ? 'Last known'
+ : state === 'unavailable'
+ ? 'Unavailable'
+ : 'Freshness unknown';
+ const source =
+ observation && Object.hasOwn(memorySourceLabels, observation.source)
+ ? memorySourceLabels[observation.source]
+ : 'Unknown source';
+ const time = observed ? `Observed: ${observed}.` : 'Observation time unknown.';
+ return {
+ state,
+ summary: `${label} · ${source}${observed ? ` · ${observed}` : ' · time unknown'}`,
+ message: `${label}. Source: ${source}. ${time}${state === 'last-known' || state === 'unknown' ? ' Not a current measurement.' : ''}`,
+ };
+};
+
export const getGuestDrawerDeferredMetrics = (
guest: Guest,
): Record<string, GuestDrawerHistoryDeferredMetric> => {
- if (!isGuestDrawerVM(guest) || !guest.diskStatusReason) return {};
- return {
- disk: {
+ const metrics: Record<string, GuestDrawerHistoryDeferredMetric> = {};
+ if (isGuestDrawerVM(guest) && guest.diskStatusReason) {
+ metrics.disk = {
lastKnownValue: guest.diskStatusReason.startsWith('prev-')
? getGuestDrawerDiskUsage(guest)
: undefined,
message: getWorkloadGuestDiskStatusMessage(guest.diskStatusReason),
- },
- };
+ };
+ }
+ const memory = getGuestDrawerMemoryReading(guest);
+ if (memory && memory.state !== 'current') {
+ metrics.memory = {
+ lastKnownValue: memory.state === 'unavailable' ? undefined : getGuestDrawerMemoryUsage(guest),
+ ...(memory.state === 'unknown' ? { valueLabel: 'freshness unknown' as const } : {}),
+ message: memory.message,
+ };
+ }
+ return metrics;
};
// Current-value metrics displayed beside history legends while the metrics
@@ -128,8 +217,11 @@ export const getGuestDrawerCurrentMetrics = (guest: Guest): Record<string, numbe
const available = (metric: keyof NonNullable<Guest['telemetryAvailability']>): boolean =>
availability?.[metric] ?? true;
const cpuPercent = available('cpu') ? getWorkloadCPUPercent(guest.cpu) : undefined;
+ const memoryReading = getGuestDrawerMemoryReading(guest);
const memUsage =
- available('memory') && !guest.memory?.usageUnavailable ? guest.memory?.usage : undefined;
+ available('memory') && (!memoryReading || memoryReading.state === 'current')
+ ? getGuestDrawerMemoryUsage(guest)
+ : undefined;
// A paused filesystem read is not current, even if the snapshot still
// carries a numeric summary. Retained evidence has its own labelled path.
const diskUsage =
@@ -497,11 +589,12 @@ export const getGuestDrawerMemoryRows = (guest: Guest): GuestDrawerMemoryRow[] =
if (!memory) return [];
const rows: GuestDrawerMemoryRow[] = [];
+ const reading = getGuestDrawerMemoryReading(guest);
const total = memory.total ?? 0;
const used = memory.used ?? 0;
const cache = memory.cache ?? 0;
- if (memory.usageUnavailable) {
+ if (memory.usageUnavailable || reading?.state === 'unavailable') {
rows.push({ label: 'Usage', value: 'Unavailable' });
if (total > 0) {
rows.push({ label: 'Total', value: formatBytes(total) });
@@ -524,7 +617,12 @@ export const getGuestDrawerMemoryRows = (guest: Guest): GuestDrawerMemoryRow[] =
rows.push({ label: 'Balloon', value: formatBytes(memory.balloon) });
}
- if (memory.swapTotal && memory.swapTotal > 0) {
+ if (
+ !memory.usageUnavailable &&
+ reading?.state !== 'unavailable' &&
+ memory.swapTotal &&
+ memory.swapTotal > 0
+ ) {
rows.push({
label: 'Swap',
value: `${formatBytes(memory.swapUsed ?? 0)} / ${formatBytes(memory.swapTotal)}`,
diff --git a/frontend-modern/src/hooks/__tests__/useUnifiedResources.test.ts b/frontend-modern/src/hooks/__tests__/useUnifiedResources.test.ts
index 4f87635c71..3f62f9fa63 100644
--- a/frontend-modern/src/hooks/__tests__/useUnifiedResources.test.ts
+++ b/frontend-modern/src/hooks/__tests__/useUnifiedResources.test.ts
@@ -180,6 +180,23 @@ describe('useUnifiedResources', () => {
try {
await waitForResourceCount(() => result.resources().length);
expect(result.resources()[0].memory).toMatchObject({ current: 50, observation });
+ apiFetchMock.mockResolvedValue(
+ resourceResponse([
+ {
+ ...v2Resource,
+ lastSeen: '2026-10-04T17:00:00Z',
+ metrics: {
+ ...v2Resource.metrics,
+ memory: { ...v2Resource.metrics.memory, observation },
+ },
+ },
+ ]),
+ );
+ await result.refetch();
+ expect(result.resources()[0].memory).toMatchObject({ current: 50, observation });
+ apiFetchMock.mockResolvedValue(resourceResponse([v2Resource]));
+ await result.refetch();
+ expect(result.resources()[0].memory).not.toHaveProperty('observation');
} finally {
dispose();
}
diff --git a/frontend-modern/src/hooks/__tests__/useWorkloads.test.ts b/frontend-modern/src/hooks/__tests__/useWorkloads.test.ts
index f5c088f43f..e0c4a0eac0 100644
--- a/frontend-modern/src/hooks/__tests__/useWorkloads.test.ts
+++ b/frontend-modern/src/hooks/__tests__/useWorkloads.test.ts
@@ -539,6 +539,21 @@ describe('useWorkloads', () => {
await flushAsync();
expect(result.workloads()[0].memory).not.toHaveProperty('observation');
expect(result.workloads()[0].memory.usage).toBe(50);
+ const live = {
+ ...resource,
+ metrics: {
+ ...resource.metrics,
+ memory: { ...resource.metrics.memory, observation: raw },
+ },
+ memory: { ...resource.memory, observation: raw },
+ };
+ if (transport === 'snapshot') setSnapshot([live]);
+ else {
+ apiFetchJSONMock.mockResolvedValue({ data: [live], meta: { totalPages: 1 } });
+ await result.refetch();
+ }
+ await flushAsync();
+ expect(result.workloads()[0].memory).toMatchObject({ usage: 50, observation: raw });
} finally {
dispose();
}
diff --git a/frontend-modern/src/hooks/useUnifiedResources.ts b/frontend-modern/src/hooks/useUnifiedResources.ts
index dbb5d9b3d8..489881c89c 100644
--- a/frontend-modern/src/hooks/useUnifiedResources.ts
+++ b/frontend-modern/src/hooks/useUnifiedResources.ts
@@ -1,3 +1,5 @@
+import { readMemoryObservation } from '@/utils/memoryObservation';
+import type { MemoryObservation } from '@/types/api';
import { batch, createEffect, createSignal, onCleanup, untrack, type Accessor } from 'solid-js';
import { createStore, reconcile, unwrap } from 'solid-js/store';
import { canonicalizeMetricsHistoryTargetType } from '@/api/charts';
@@ -69,6 +71,7 @@ const UNIFIED_RESOURCES_WS_INITIAL_HYDRATION_WAIT_MS = 1_200;
const UNIFIED_RESOURCES_WS_CANONICAL_REVALIDATE_DELAY_MS = UNIFIED_RESOURCES_CACHE_MAX_AGE_MS + 250;
type APIMetricValue = {
+ observation?: MemoryObservation;
value?: number;
used?: number;
total?: number;
@@ -793,9 +796,11 @@ const metricToResourceMetric = (metric?: APIMetricValue) => {
const used = metric.used ?? undefined;
const total = metric.total ?? undefined;
const current = metric.percent ?? metric.value ?? 0;
+ const observation = readMemoryObservation(metric.observation);
const free = total !== undefined && used !== undefined ? total - used : undefined;
return {
current,
+ ...(observation ? { observation } : {}),
total,
used,
free,
diff --git a/frontend-modern/src/hooks/useWorkloads.ts b/frontend-modern/src/hooks/useWorkloads.ts
index b60f46937d..605418bc57 100644
--- a/frontend-modern/src/hooks/useWorkloads.ts
+++ b/frontend-modern/src/hooks/useWorkloads.ts
@@ -1,3 +1,5 @@
+import { readMemoryObservation } from '@/utils/memoryObservation';
+import type { MemoryObservation } from '@/types/api';
import { onCleanup, createEffect, createSignal, untrack, type Accessor } from 'solid-js';
import { apiFetchJSON, getOrgID } from '@/utils/apiClient';
import { normalizeOrgScope } from '@/utils/orgScope';
@@ -40,6 +42,7 @@ const WORKLOADS_MAX_PAGES = 100;
const WORKLOADS_CACHE_MAX_AGE_MS = 15_000;
type APIMetricValue = {
+ observation?: MemoryObservation;
value?: number;
used?: number;
total?: number;
@@ -559,8 +562,10 @@ const mapResourceToWorkload = (resource: APIResource): WorkloadGuest | null => {
memory: (() => {
const base = buildMetric(resource.metrics?.memory);
const cache = resource.proxmox?.memoryCache ?? 0;
+ const observation = readMemoryObservation(resource.metrics?.memory?.observation);
return {
...base,
+ ...(observation ? { observation } : {}),
usageUnavailable: !memoryAvailable,
// buildMetric derives free as total-used (available); carve the
// reclaimable cache back out so free means truly-free pages.
@@ -688,6 +693,7 @@ const metricToAPI = (metric?: Resource['cpu']): APIMetricValue | undefined =>
metric
? {
percent: metric.current,
+ ...(metric.observation ? { observation: metric.observation } : {}),
used: metric.used,
total: metric.total,
}
diff --git a/frontend-modern/src/types/api.ts b/frontend-modern/src/types/api.ts
index 29e6a0ee92..5e7da6d6de 100644
--- a/frontend-modern/src/types/api.ts
+++ b/frontend-modern/src/types/api.ts
@@ -1170,6 +1170,15 @@ export interface PBSJobHealthEvidence {
error?: string;
}
+/** Server-owned provenance of the selected guest-memory reading. */
+export interface MemoryObservation {
+ /** current, last-known or unavailable. Unrecognised/absent states are unknown. */
+ state: string;
+ source: string;
+ /** Original source time, never the refreshed resource LastSeen. */
+ observedAt?: string;
+}
+
export interface Memory {
total: number;
used: number;
@@ -1178,6 +1187,7 @@ export interface Memory {
cache?: number;
/** Total is known, but no cache-aware source can establish current usage. */
usageUnavailable?: boolean;
+ observation?: MemoryObservation;
usage: number;
balloon?: number;
swapUsed?: number;
diff --git a/frontend-modern/src/types/resource.ts b/frontend-modern/src/types/resource.ts
index 36899574e6..57f305f505 100644
--- a/frontend-modern/src/types/resource.ts
+++ b/frontend-modern/src/types/resource.ts
@@ -16,6 +16,7 @@ import type {
HostSensorSummary,
HostRAIDArray,
Memory,
+ MemoryObservation,
DockerRuntimeCommand,
PBSBackupJob,
PBSGarbageJob,
@@ -119,7 +120,8 @@ export interface ResourceHealth {
// Metric value with optional limits
export interface ResourceMetric {
- current: number; // Current value (percentage or bytes)
+ current: number; // Selected numeric value (percentage or bytes), not a freshness assertion.
+ observation?: MemoryObservation;
total?: number; // Total capacity (bytes) - null for percentages
used?: number; // Used amount (bytes)
free?: number; // Free amount (bytes)
diff --git a/frontend-modern/src/utils/__tests__/resourceStateAdapters.test.ts b/frontend-modern/src/utils/__tests__/resourceStateAdapters.test.ts
index 0014cc7aaa..bea2d130c6 100644
--- a/frontend-modern/src/utils/__tests__/resourceStateAdapters.test.ts
+++ b/frontend-modern/src/utils/__tests__/resourceStateAdapters.test.ts
@@ -72,6 +72,15 @@ describe('resourceStateAdapters nodeFromResource', () => {
usage: 75,
observation: raw,
});
+ expect(
+ nodeFromResource({
+ ...resource,
+ memory: {
+ ...resource.memory!,
+ observation: { state: 'current', source: 'agent', observedAt: '2026-10-04T16:00:00Z' },
+ },
+ })?.memory.observation?.source,
+ ).toBe('agent');
});
it('keeps Proxmox metric coordinates without inventing an agent from discovery routing', () => {
diff --git a/frontend-modern/src/utils/memoryObservation.ts b/frontend-modern/src/utils/memoryObservation.ts
new file mode 100644
index 0000000000..f53e2ff612
--- /dev/null
+++ b/frontend-modern/src/utils/memoryObservation.ts
@@ -0,0 +1,13 @@
+import type { MemoryObservation } from '@/types/api';
+
+// Keep only the existing server-owned wire fields. Missing/future state is not
+// replaced by a resource poll time or a platform facet from another metric.
+export const readMemoryObservation = (value: unknown): MemoryObservation | undefined => {
+ if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined;
+ const record = value as Record<string, unknown>;
+ return {
+ state: typeof record.state === 'string' ? record.state : '',
+ source: typeof record.source === 'string' ? record.source : '',
+ ...(typeof record.observedAt === 'string' ? { observedAt: record.observedAt } : {}),
+ };
+};
diff --git a/frontend-modern/src/utils/resourceStateAdapters.ts b/frontend-modern/src/utils/resourceStateAdapters.ts
index 58408371bf..fef157dbc0 100644
--- a/frontend-modern/src/utils/resourceStateAdapters.ts
+++ b/frontend-modern/src/utils/resourceStateAdapters.ts
@@ -1,3 +1,4 @@
+import { readMemoryObservation } from '@/utils/memoryObservation';
import type {
Disk,
HostNetworkInterface,
@@ -1326,6 +1327,9 @@ const buildMemory = (
proxmoxMeta?: Record<string, unknown>,
): Memory => {
const total = metric?.total ?? asNumber(fallback?.total) ?? 0;
+ const observation = readMemoryObservation(
+ metric == null ? fallback?.observation : metric.observation,
+ );
const usageUnavailable = metric == null && asBoolean(fallback?.usageUnavailable) === true;
const used = metric?.used ?? asNumber(fallback?.used) ?? 0;
const cache = asNumber(proxmoxMeta?.memoryCache) ?? asNumber(fallback?.cache) ?? 0;
@@ -1344,6 +1348,7 @@ const buildMemory = (
free,
usage,
usageUnavailable,
+ ...(observation ? { observation } : {}),
cache: cache > 0 ? cache : undefined,
swapUsed: asNumber(proxmoxMeta?.swapUsed) ?? asNumber(fallback?.swapUsed),
swapTotal: asNumber(proxmoxMeta?.swapTotal) ?? asNumber(fallback?.swapTotal),