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.
Go aialertsdashboarddockerdocker-monitoringgohomelabinfrastructure-monitoringkubernetesmonitoringmspproxmoxproxmox-backup-serverproxmox-mail-gatewayproxmox-veself-hostedtruenastypescriptvspherewebhooks
import { describe, expect, it } from 'vitest';
import {
buildFastResourceStorePatchOps,
getFastResourceMergePatchKeys,
mergeCanonicalResourceDeltaSnapshot,
mergeCanonicalResourceSnapshot,
nodeFromResource,
pbsInstanceFromResource,
pmgInstanceFromResource,
unionResourceChangedKeys,
} from '../resourceStateAdapters';
import type { Resource } from '@/types/resource';
it('withdraws a previous browser observation when realtime reports startup pending delivery', () => {
const existing: Resource = {
id: 'waiting-agent',
type: 'agent',
name: 'Host',
displayName: 'Host',
platformId: 'agent',
platformType: 'agent',
sourceType: 'agent',
status: 'online',
lastSeen: 1000,
sources: ['agent'],
cpu: { current: 12 },
memory: { current: 25 },
uptime: 60,
agent: { agentId: 'waiting-agent', cpuCount: 4 } as Resource['agent'],
};
const incoming: Resource = {
id: existing.id,
type: 'agent',
name: 'Host',
displayName: 'Host',
platformId: 'agent',
platformType: 'agent',
sourceType: 'agent',
status: 'unknown',
lastSeen: 1000,
sources: ['agent'],
sourceStatus: { agent: { status: 'pending' } },
agent: { agentId: 'waiting-agent' } as Resource['agent'],
};
for (const result of [
mergeCanonicalResourceSnapshot([incoming], [existing]),
mergeCanonicalResourceDeltaSnapshot([incoming], [existing], new Set([incoming.id])),
]) {
expect(result[0]).toMatchObject({
status: 'unknown',
lastSeen: 1000,
sourceStatus: incoming.sourceStatus,
});
expect(result[0]?.cpu).toBeUndefined();
expect(result[0]?.memory).toBeUndefined();
expect(result[0]?.uptime).toBeUndefined();
expect(result[0]?.agent?.cpuCount).toBeUndefined();
}
});
const createNodeResource = (platformData: Record<string, unknown>): Resource =>
({
id: 'node-1',
type: 'agent',
name: 'pve-node-1',
displayName: 'PVE Node 1',
platformId: 'pve-node-1',
platformType: 'proxmox-pve',
sourceType: 'api',
status: 'online',
lastSeen: Date.now(),
cpu: { current: 10 },
memory: { current: 20, total: 1024, used: 256 },
disk: { current: 30, total: 2048, used: 512 },
platformData,
}) as Resource;
const createServiceResource = (
type: 'pbs' | 'pmg',
platformData: Record<string, unknown>,
overrides: Partial<Resource> = {},
): Resource =>
({
id: `${type}-1`,
type,
name: `${type}-name`,
displayName: `${type.toUpperCase()} Display`,
platformId: '',
platformType: type === 'pbs' ? 'proxmox-pbs' : 'proxmox-pmg',
sourceType: 'api',
status: 'online',
lastSeen: Date.now(),
cpu: { current: 10 },
memory: { current: 20, total: 1024, used: 256 },
disk: { current: 30, total: 2048, used: 512 },
platformData,
...overrides,
}) as Resource;
describe('resourceStateAdapters nodeFromResource', () => {
it('keeps selected memory provenance independent of a different raw platform reading', () => {
const observation = {
state: 'last-known',
source: 'guest-agent-meminfo',
observedAt: '2026-10-04T14:00:00Z',
};
const raw = { state: 'current', source: 'status-mem', observedAt: '2026-10-04T17:00:00Z' };
const resource = {
...createNodeResource({}),
memory: { current: 25, total: 1024, used: 256, observation },
proxmox: { memory: { total: 1024, used: 768, usage: 75, observation: raw } },
} as Resource;
expect(nodeFromResource(resource)?.memory).toMatchObject({ usage: 25, observation });
expect(
nodeFromResource({ ...resource, memory: { current: 25, total: 1024, used: 256 } })?.memory,
).not.toHaveProperty('observation');
expect(nodeFromResource({ ...resource, memory: undefined })?.memory).toMatchObject({
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', () => {
const resource = {
...createNodeResource({ proxmox: { nodeName: 'pve-node-1' } }),
id: 'agent-canonical-id',
metricsTarget: { resourceType: 'node', resourceId: 'cluster-pve-node-1' },
discoveryTarget: { resourceType: 'agent', resourceId: 'pve-node-1', agentId: 'pve-node-1' },
} as Resource;
const node = nodeFromResource(resource);
expect(node?.metricsTarget).toEqual(resource.metricsTarget);
expect(node?.linkedAgentId).toBeUndefined();
const linked = nodeFromResource({ ...resource, agent: { agentId: 'real-agent' } });
expect(linked?.linkedAgentId).toBe('real-agent');
});
it('maps canonical linkedAgentId', () => {
const node = nodeFromResource(
createNodeResource({
linkedAgentId: 'agent-canonical',
proxmox: { nodeName: 'pve-node-1' },
}),
);
expect(node?.linkedAgentId).toBe('agent-canonical');
});
it('falls back to the actionable agent identity when linkedAgentId is absent', () => {
const node = nodeFromResource(
createNodeResource({
proxmox: { nodeName: 'pve-node-1' },
agent: { agentId: 'agent-from-facet' },
}),
);
expect(node?.linkedAgentId).toBe('agent-from-facet');
});
it('uses typed canonical identity for node labels when proxmox nodeName is absent', () => {
const node = nodeFromResource({
...createNodeResource({
proxmox: {},
} as Record<string, unknown>),
name: '',
displayName: '',
platformId: '',
canonicalIdentity: {
displayName: 'Tower',
hostname: 'tower.local',
platformId: 'pve-canonical',
},
} as Resource);
expect(node?.name).toBe('tower.local');
expect(node?.displayName).toBe('Tower');
expect(node?.host).toBe('tower.local');
expect(node?.instance).toBe('pve-canonical');
expect(node?.clusterName).toBeUndefined();
});
it('keeps node operator labels on local identity when governed summaries exist', () => {
const node = nodeFromResource({
...createNodeResource({
proxmox: {},
} as Record<string, unknown>),
name: '',
displayName: 'Tower',
platformId: 'tower-id',
policy: {
sensitivity: 'restricted',
routing: { scope: 'local-only', redact: ['hostname'] },
},
canonicalIdentity: {
displayName: 'Tower',
hostname: 'tower.local',
platformId: 'tower-id',
},
} as Resource);
expect(node?.name).toBe('tower.local');
expect(node?.displayName).toBe('Tower');
expect(node?.host).toBe('tower.local');
});
it('maps the PVE web interface URL from proxmox metadata', () => {
const node = nodeFromResource(
createNodeResource({
proxmox: {
nodeName: 'pve-node-1',
guestUrl: 'https://pve.example.com:8006',
host: 'https://192.168.0.5:8006',
},
}),
);
expect(node?.guestURL).toBe('https://pve.example.com:8006');
expect(node?.host).toBe('pve-node-1');
});
it('falls back to the PVE API connection URL when no guest URL override exists', () => {
const node = nodeFromResource(
createNodeResource({
proxmox: {
nodeName: 'pve-node-1',
host: 'https://192.168.0.5:8006',
},
}),
);
expect(node?.guestURL).toBe('https://192.168.0.5:8006');
});
it('projects the canonical cluster name through the shared helper', () => {
const node = nodeFromResource(
createNodeResource({
proxmox: {
nodeName: 'pve-node-1',
clusterName: 'cluster-a',
},
}),
);
expect(node?.clusterName).toBe('cluster-a');
});
it('falls back to normalized Proxmox resource facets for node name and version', () => {
const node = nodeFromResource({
...createNodeResource({}),
proxmox: { node: 'pve-node-2', instance: 'cluster-a' },
agent: { osName: 'Proxmox VE', osVersion: '9.1.9' },
network: { rxBytes: 1024, txBytes: 2048 },
diskIO: { readRate: 4096, writeRate: 8192 },
} as Resource);
expect(node?.name).toBe('pve-node-2');
expect(node?.pveVersion).toBe('9.1.9');
expect(node?.networkIn).toBe(1024);
expect(node?.networkOut).toBe(2048);
expect(node?.diskRead).toBe(4096);
expect(node?.diskWrite).toBe(8192);
});
it('uses Proxmox network inventory unless a linked agent has richer interface data', () => {
const proxmoxOnly = nodeFromResource({
...createNodeResource({}),
proxmox: {
nodeName: 'pve-node-2',
networkInterfaces: [
{ name: 'eno1', addresses: [] },
{ name: 'vmbr0', addresses: ['192.168.10.21/24'] },
],
},
} as Resource);
expect(proxmoxOnly?.networkInterfaces).toEqual([
{ name: 'eno1', addresses: [] },
{ name: 'vmbr0', addresses: ['192.168.10.21/24'] },
]);
const linkedAgent = nodeFromResource({
...createNodeResource({}),
proxmox: {
nodeName: 'pve-node-2',
networkInterfaces: [{ name: 'vmbr0', addresses: ['192.168.10.21/24'] }],
},
agent: {
networkInterfaces: [{ name: 'eth0', addresses: ['192.168.10.22'] }],
},
} as Resource);
expect(linkedAgent?.networkInterfaces).toEqual([
{ name: 'eth0', addresses: ['192.168.10.22'] },
]);
});
it("reads a Proxmox node's CPU low and record from the poller's temperature details", () => {
// The unified resource API publishes the scalar maximum as
// proxmox.temperature and the full reading as proxmox.temperatureDetails.
const proxmox = {
nodeName: 'pve-node-2',
temperature: 58,
temperatureDetails: {
available: true,
hasCPU: true,
cpuPackage: 52,
cpuMax: 58,
cpuMin: 41,
cpuMaxRecord: 76,
minRecorded: '2026-10-06T08:00:00Z',
maxRecorded: '2026-10-06T12:00:00Z',
cores: [{ core: 0, temp: 58 }],
lastUpdate: '2026-10-06T15:00:00Z',
},
};
const node = nodeFromResource({
...createNodeResource({ proxmox }),
temperature: 58,
proxmox,
} as unknown as Resource);
expect(node?.temperature).toMatchObject({
available: true,
cpuPackage: 52,
cpuMax: 58,
cpuMin: 41,
cpuMaxRecord: 76,
lastUpdate: '2026-10-06T15:00:00Z',
});
expect(node?.temperature?.cores).toEqual([{ core: 0, temp: 58 }]);
// Without details there is no history: the current reading must not be
// reported as the node's low or record.
const bare = nodeFromResource({
...createNodeResource({ proxmox: { nodeName: 'pve-node-2', temperature: 58 } }),
temperature: 58,
} as unknown as Resource);
expect(bare?.temperature?.cpuPackage).toBe(58);
expect(bare?.temperature?.cpuMin).toBeUndefined();
expect(bare?.temperature?.cpuMaxRecord).toBeUndefined();
// Details without a CPU reading do not displace a valid scalar CPU reading.
const sensorsOnly = nodeFromResource({
...createNodeResource({
proxmox: {
nodeName: 'pve-node-2',
temperatureDetails: {
available: true,
hasCPU: false,
nvme: [{ device: 'nvme0', temp: 44 }],
},
},
}),
temperature: 58,
} as unknown as Resource);
expect(sensorsOnly?.temperature?.cpuPackage).toBe(58);
expect(sensorsOnly?.temperature?.available).toBe(true);
// An unusable earlier record still falls back to the scalar reading.
const legacyUnavailable = nodeFromResource({
...createNodeResource({
temperature: { available: false },
proxmox: { nodeName: 'pve-node-2', temperature: { available: false, cpuPackage: 58 } },
}),
temperature: 58,
} as unknown as Resource);
expect(legacyUnavailable?.temperature?.cpuPackage).toBe(58);
expect(legacyUnavailable?.temperature?.available).toBe(true);
// A node with a host agent keeps reading the agent facet first.
const agentLinked = nodeFromResource({
...createNodeResource({ proxmox, agent: { agentId: 'pve-agent', temperature: 61 } }),
temperature: 61,
proxmox,
} as unknown as Resource);
expect(agentLinked?.temperature?.cpuPackage).toBe(61);
expect(agentLinked?.temperature?.cpuMin).toBeUndefined();
});
it("carries the backend's primary CPU temperature, not one rebuilt from details", () => {
// The details hold a core hotter than the resource temperature. The node
// keeps the resource value, the reading its history line records.
const proxmox = {
nodeName: 'pve-node-2',
temperature: 52,
temperatureDetails: {
available: true,
hasCPU: true,
cpuPackage: 52,
cpuMax: 57,
cores: [{ core: 0, temp: 57 }],
lastUpdate: '2026-10-06T15:00:00Z',
},
};
const node = nodeFromResource({
...createNodeResource({ proxmox }),
temperature: 52,
proxmox,
} as unknown as Resource);
expect(node?.cpuTemperature).toBe(52);
// A linked agent's reading wins, the same source as the agent history line.
const agentLinked = nodeFromResource({
...createNodeResource({ proxmox, agent: { agentId: 'pve-agent', temperature: 61 } }),
temperature: 61,
proxmox,
} as unknown as Resource);
expect(agentLinked?.cpuTemperature).toBe(61);
// No usable reading means no headline value at all.
for (const temperature of [undefined, 0, Number.NaN]) {
const unread = nodeFromResource({
...createNodeResource({ proxmox: { nodeName: 'pve-node-2' } }),
temperature,
} as unknown as Resource);
expect(unread?.cpuTemperature).toBeUndefined();
}
});
it('preserves linked-agent GPU telemetry for the Proxmox node drawer', () => {
const gpu = {
id: '0',
name: 'NVIDIA RTX A6000',
temperatureCelsius: 63,
utilizationPercent: 42,
memoryUsedBytes: 8 * 1024 * 1024 * 1024,
memoryTotalBytes: 48 * 1024 * 1024 * 1024,
};
const node = nodeFromResource({
...createNodeResource({}),
proxmox: { nodeName: 'pve-node-2' },
agent: { agentId: 'pve-agent', sensors: { gpu: [gpu] } },
} as Resource);
expect(node?.sensors?.gpu).toEqual([gpu]);
});
it('keeps linked-agent power and its own freshness on the projected PVE node', () => {
const powerWatts = { cpu_package: 12.87716, cpu_core: 6.1511, dram: 1.74011 };
const nodeResource = {
...createNodeResource({}),
status: 'online',
proxmox: { nodeName: 'pve-node-2', connectionHealth: 'healthy' },
agent: { agentId: 'pve-agent', stale: false, sensors: { powerWatts } },
} as Resource;
const node = nodeFromResource(nodeResource);
expect(node?.sensors?.powerWatts).toEqual(powerWatts);
expect(node?.sensorsStale).toBe(false);
const silent = nodeFromResource({
...nodeResource,
agent: { ...nodeResource.agent, stale: true },
} as Resource);
expect(silent?.status).toBe('online');
expect(silent?.sensors?.powerWatts).toEqual(powerWatts);
expect(silent?.sensorsStale).toBe(true);
const withdrawn = nodeFromResource({ ...nodeResource, agent: undefined } as Resource);
expect(withdrawn?.sensors).toBeUndefined();
expect(withdrawn?.sensorsStale).toBe(false);
});
it('maps PBS display and host identity through shared resource helpers', () => {
const instance = pbsInstanceFromResource(
createServiceResource('pbs', {
pbs: { hostname: 'pbs-service.local', instanceId: 'pbs-instance-1' },
}),
);
expect(instance?.name).toBe('PBS Display');
expect(instance?.host).toBe('https://pbs-service.local:8007');
});
it('keeps PBS operator labels on local identity when governed summaries exist', () => {
const instance = pbsInstanceFromResource(
createServiceResource(
'pbs',
{
pbs: { hostname: 'pbs-service.local', instanceId: 'pbs-instance-1' },
},
{
displayName: 'PBS Main',
policy: {
sensitivity: 'restricted',
routing: { scope: 'local-only', redact: ['hostname'] },
},
},
),
);
expect(instance?.name).toBe('PBS Main');
});
it('maps PMG identity through shared hostname fallback when displayName is absent', () => {
const instance = pmgInstanceFromResource(
createServiceResource(
'pmg',
{
pmg: { hostname: 'pmg-service.local', instanceId: 'pmg-instance-1' },
},
{ displayName: '' as unknown as Resource['displayName'] },
),
);
expect(instance?.name).toBe('pmg-service.local');
expect(instance?.host).toBe('https://pmg-service.local:8006');
});
it('uses PMG host and guest URLs from canonical platform data when available', () => {
const instance = pmgInstanceFromResource(
createServiceResource('pmg', {
pmg: {
hostname: 'pmg-service.local',
hostUrl: 'https://pmg-service.local:8443',
guestUrl: 'https://mail.example.com',
instanceId: 'pmg-instance-1',
},
}),
);
expect(instance?.host).toBe('https://pmg-service.local:8443');
expect(instance?.guestURL).toBe('https://mail.example.com');
});
it('keeps PMG operator labels on local identity when governed summaries exist', () => {
const instance = pmgInstanceFromResource(
createServiceResource(
'pmg',
{
pmg: { hostname: 'pmg-service.local', instanceId: 'pmg-instance-1' },
},
{
displayName: 'PMG Main',
policy: {
sensitivity: 'restricted',
routing: { scope: 'local-only', redact: ['hostname'] },
},
},
),
);
expect(instance?.name).toBe('PMG Main');
});
it('canonicalizes thin realtime resource platform data without inventing standalone clusters', () => {
const [resource] = mergeCanonicalResourceSnapshot(
[
{
id: 'docker-host-1',
type: 'docker-host',
name: 'Ops Services 01',
displayName: 'Ops Services 01',
platformId: 'ops-services-01',
platformType: 'docker',
sourceType: 'api',
status: 'online',
lastSeen: Date.now(),
platformData: {
hostname: 'ops-services-01',
hostSourceId: 'ops-services-01',
runtime: 'docker',
},
} as Resource,
{
id: 'pbs-1',
type: 'pbs',
name: 'backup-vault',
displayName: 'backup-vault',
platformId: 'pbs-1',
platformType: 'proxmox-pbs',
sourceType: 'api',
status: 'online',
lastSeen: Date.now(),
platformData: {
host: '198.51.100.10',
version: '3.2.1',
connectionHealth: 'healthy',
numDatastores: 2,
},
} as Resource,
],
[],
);
expect(resource.clusterId).toBeUndefined();
const pbs = mergeCanonicalResourceSnapshot(
[
{
id: 'pbs-1',
type: 'pbs',
name: 'backup-vault',
displayName: 'backup-vault',
platformId: 'pbs-1',
platformType: 'proxmox-pbs',
sourceType: 'api',
status: 'online',
lastSeen: Date.now(),
platformData: {
host: '198.51.100.10',
version: '3.2.1',
connectionHealth: 'healthy',
numDatastores: 2,
},
} as Resource,
],
[],
)[0];
expect((pbs.platformData as Record<string, unknown>)?.pbs).toMatchObject({
hostname: '198.51.100.10',
version: '3.2.1',
connectionHealth: 'healthy',
datastoreCount: 2,
});
});
it('preserves canonical platform scopes across realtime resource merges', () => {
const existing = {
id: 'docker-container-frigate-141',
type: 'app-container',
name: 'frigate',
displayName: 'frigate',
platformId: 'frigate',
platformType: 'docker',
platformScopes: ['proxmox-pve', 'docker'],
sourceType: 'api',
sources: ['docker'],
status: 'online',
lastSeen: Date.now() - 1_000,
platformData: {
sources: ['docker'],
docker: {
hostSourceId: 'proxmox-lxc-docker:pve-a:node-a:141',
containerId: 'frigate',
runtime: 'docker',
},
},
} as Resource;
const [resource] = mergeCanonicalResourceSnapshot(
[
{
...existing,
lastSeen: Date.now(),
platformScopes: undefined,
} as Resource,
],
[existing],
);
expect(resource.platformScopes).toEqual(['proxmox-pve', 'docker']);
});
it('preserves canonical identity succession across thin realtime merges', () => {
const existing = {
...createNodeResource({ proxmox: { nodeName: 'pve-node-1' } }),
canonicalIdentity: {
primaryId: 'agent:connection-current',
aliases: ['agent-current', 'node-1'],
supersededIds: ['agent-retired-before-refresh'],
},
} as Resource;
const [resource] = mergeCanonicalResourceSnapshot(
[
{
...existing,
lastSeen: Date.now(),
canonicalIdentity: {
primaryId: 'agent:connection-current',
aliases: ['agent-current'],
supersededIds: ['agent-retired-in-refresh'],
},
} as Resource,
],
[existing],
);
expect(resource.canonicalIdentity).toMatchObject({
primaryId: 'agent:connection-current',
aliases: ['agent-current', 'node-1'],
supersededIds: ['agent-retired-in-refresh', 'agent-retired-before-refresh'],
});
});
it('canonicalizes agentless availability realtime resources as availability endpoints', () => {
const [resource] = mergeCanonicalResourceSnapshot(
[
{
id: 'network-endpoint-1',
type: 'network-endpoint',
name: 'MQTT power meter',
displayName: 'MQTT power meter',
platformId: 'mock-availability-mqtt-meter',
platformType: 'generic',
sourceType: 'api',
status: 'online',
lastSeen: Date.now(),
platformData: {
availability: {
targetId: 'mock-availability-mqtt-meter',
protocol: 'tcp',
address: 'power-meter-01.lab.local',
port: 1883,
},
},
} as Resource,
],
[],
);
expect(resource.platformType).toBe('availability');
expect(resource.sourceType).toBe('api');
expect(resource.availability).toMatchObject({
targetId: 'mock-availability-mqtt-meter',
protocol: 'tcp',
address: 'power-meter-01.lab.local',
port: 1883,
});
expect((resource.platformData as Record<string, unknown>).sources).toEqual(['availability']);
});
it('preserves plural attached availability facets across thin realtime merges', () => {
const availabilityChecks = [
{
targetId: 'ops-api',
linkedResourceId: 'docker-host-1',
protocol: 'tcp',
address: '192.0.2.18',
port: 8007,
available: true,
correlationState: 'attached' as const,
},
{
targetId: 'ops-web',
linkedResourceId: 'docker-host-1',
protocol: 'https',
address: 'ops.example.test',
path: '/health',
available: true,
correlationState: 'attached' as const,
},
];
const existing = {
id: 'docker-host-1',
type: 'docker-host',
name: 'Operations Docker',
displayName: 'Operations Docker',
platformId: 'docker-host-1',
platformType: 'docker',
sourceType: 'api',
sources: ['docker', 'availability'],
status: 'online',
lastSeen: Date.now() - 1_000,
availability: availabilityChecks[0],
availabilityChecks,
} as Resource;
const [resource] = mergeCanonicalResourceSnapshot(
[
{
...existing,
lastSeen: Date.now(),
availability: undefined,
availabilityChecks: undefined,
} as Resource,
],
[existing],
);
expect(resource.availability).toEqual(availabilityChecks[0]);
expect(resource.availabilityChecks).toEqual(availabilityChecks);
});
it('canonicalizes native TrueNAS share resources with the TrueNAS facet intact', () => {
const [resource] = mergeCanonicalResourceSnapshot(
[
{
id: 'truenas-share-media',
type: 'network-share',
name: 'Media',
displayName: 'SMB Media',
platformId: 'truenas-main:smb:media',
platformType: 'truenas',
sourceType: 'api',
status: 'online',
lastSeen: Date.now(),
truenas: {
hostname: 'truenas-main.local',
share: {
id: 'smb-media',
name: 'Media',
protocol: 'SMB',
path: '/mnt/tank/media',
dataset: 'tank/media',
enabled: true,
readOnly: false,
},
},
} as Resource,
],
[],
);
expect(resource.platformType).toBe('truenas');
expect(resource.sourceType).toBe('api');
expect(resource.truenas?.share).toMatchObject({
id: 'smb-media',
protocol: 'SMB',
dataset: 'tank/media',
path: '/mnt/tank/media',
});
expect((resource.platformData as Record<string, unknown>).sources).toEqual(['truenas']);
expect((resource.platformData as Record<string, unknown>).truenas).toMatchObject({
hostname: 'truenas-main.local',
share: { id: 'smb-media' },
});
});
it('canonicalizes top-level Proxmox and agent facets as one hybrid PVE resource', () => {
const [resource] = mergeCanonicalResourceSnapshot(
[
{
id: 'agent-pi',
type: 'agent',
name: 'pi',
displayName: 'pi',
platformId: 'pi',
platformType: 'agent',
sourceType: 'agent',
status: 'online',
lastSeen: Date.now(),
proxmox: {
nodeName: 'pi',
instance: 'pi',
},
agent: {
hostname: 'pi',
platform: 'debian',
osName: 'Debian GNU/Linux',
osVersion: '12',
},
} as Resource,
],
[],
);
expect(resource.platformType).toBe('proxmox-pve');
expect(resource.sourceType).toBe('hybrid');
expect(resource.proxmox).toMatchObject({ nodeName: 'pi', instance: 'pi' });
expect(resource.agent).toMatchObject({ hostname: 'pi', osName: 'Debian GNU/Linux' });
expect((resource.platformData as Record<string, unknown>).sources).toEqual([
'proxmox',
'agent',
]);
expect((resource.platformData as Record<string, unknown>).proxmox).toMatchObject({
nodeName: 'pi',
});
expect((resource.platformData as Record<string, unknown>).agent).toMatchObject({
hostname: 'pi',
});
});
// The server presents host rows already coalesced (presentation coalesce
// with the operator's exclusions), so the browser renders each realtime row
// as delivered: a joined node and agent arrive as one hybrid row, and a pair
// the operator split arrives as two rows that must stay two. Fixtures follow
// the broadcast shape (monitorPlatformData flattens a Proxmox host's facts
// into platformData; the broadcast adds platformData.sources itself).
const lastSeen = Date.now();
const proxmoxFacet = {
nodeName: 'pve1',
instance: 'pve1',
clusterName: 'homelab',
linkedAgentId: 'agent-pve1',
};
const proxmoxPlatformData = {
instance: 'pve1',
host: '',
pveVersion: '9.1.9',
kernelVersion: '6.14.8-2-pve',
cpuInfo: { model: 'Xeon', cores: 8 },
isClusterMember: true,
clusterName: 'homelab',
connectionHealth: 'online',
};
const agentFacet = { agentId: 'agent-pve1', hostname: 'pve1', machineId: 'machine-pve1' };
const splitNode = {
id: 'agent-node-pve1',
type: 'agent',
name: 'pve1',
displayName: 'pve1',
platformId: 'pve1',
platformType: 'proxmox-pve',
sourceType: 'api',
sources: ['proxmox'],
clusterId: 'cluster:homelab',
status: 'online',
lastSeen,
canonicalIdentity: {
displayName: 'pve1',
hostname: 'pve1',
platformId: 'pve1',
primaryId: 'node:pve1:pve1',
aliases: ['node:pve1:pve1'],
},
identity: { hostnames: ['pve1'], clusterName: 'homelab' },
// The monitor's node record keeps its link to the agent after a split.
proxmox: proxmoxFacet,
platformData: proxmoxPlatformData,
} as unknown as Resource;
const splitAgent = {
id: 'agent-machine-pve1',
type: 'agent',
name: 'pve1',
displayName: 'pve1',
platformId: 'pve1',
platformType: 'agent',
sourceType: 'agent',
sources: ['agent'],
status: 'online',
lastSeen,
canonicalIdentity: {
displayName: 'pve1',
hostname: 'pve1',
platformId: 'pve1',
primaryId: 'agent:machine-pve1',
aliases: ['agent:machine-pve1'],
},
identity: { hostnames: ['pve1'], machineId: 'machine-pve1' },
agent: agentFacet,
platformData: {
platform: 'linux',
osName: 'Debian GNU/Linux',
osVersion: '13',
agentVersion: '6.0.0',
},
} as unknown as Resource;
// What the server presented while the pair was joined.
const joinedHost = {
...splitAgent,
platformType: 'proxmox-pve',
sourceType: 'hybrid',
sources: ['agent', 'proxmox'],
clusterId: 'cluster:homelab',
canonicalIdentity: {
...splitAgent.canonicalIdentity,
aliases: ['agent:machine-pve1', 'node:pve1:pve1'],
},
identity: { hostnames: ['pve1'], machineId: 'machine-pve1', clusterName: 'homelab' },
proxmox: proxmoxFacet,
platformData: proxmoxPlatformData,
} as unknown as Resource;
it('keeps a server-joined node and agent as one hybrid row', () => {
const rows = mergeCanonicalResourceSnapshot([structuredClone(joinedHost)], []);
expect(rows).toHaveLength(1);
expect(rows[0]?.id).toBe('agent-machine-pve1');
expect(rows[0]?.platformType).toBe('proxmox-pve');
expect(rows[0]?.sourceType).toBe('hybrid');
expect(rows[0]?.proxmox).toMatchObject({ nodeName: 'pve1' });
expect(rows[0]?.agent).toMatchObject({ agentId: 'agent-pve1' });
});
it('keeps an operator-split node and agent as two rows through snapshots and deltas', () => {
const expectSplitRows = (rows: Resource[]) => {
expect(rows.map((row) => row.id).sort()).toEqual(['agent-machine-pve1', 'agent-node-pve1']);
const node = rows.find((row) => row.id === 'agent-node-pve1');
const agent = rows.find((row) => row.id === 'agent-machine-pve1');
expect(node?.sources).toEqual(['proxmox']);
expect(node?.agent?.agentId).toBeUndefined();
expect((node?.agent as Record<string, unknown> | undefined)?.machineId).toBeUndefined();
expect(agent?.sources).toEqual(['agent']);
expect(agent?.sourceType).toBe('agent');
expect(agent?.platformType).toBe('agent');
// Nothing the joined row carried for the node stays on the agent: no
// Proxmox facet (nor the flattened facts it is synthesized from), scope,
// cluster, cluster identity, or node alias.
expect(agent?.proxmox).toBeUndefined();
const agentPlatformData = agent?.platformData as Record<string, unknown>;
expect(agentPlatformData.proxmox).toBeUndefined();
expect(agentPlatformData.pveVersion).toBeUndefined();
expect(agentPlatformData.clusterName).toBeUndefined();
expect(agent?.platformScopes ?? []).not.toContain('proxmox-pve');
expect(agent?.clusterId).toBeUndefined();
expect((agent?.identity as Record<string, unknown>).clusterName).toBeUndefined();
expect(agent?.canonicalIdentity?.aliases).toEqual(['agent:machine-pve1']);
};
for (const incoming of [
[splitNode, splitAgent],
[splitAgent, splitNode],
]) {
expectSplitRows(mergeCanonicalResourceSnapshot(structuredClone(incoming), []));
}
// The split lands on a browser still holding the joined row: the agent
// keeps the joined row's ID and must shed the node's Proxmox facet.
const full = mergeCanonicalResourceSnapshot(
[structuredClone(splitNode), structuredClone(splitAgent)],
[mergeCanonicalResourceSnapshot([structuredClone(joinedHost)], [])[0]!],
);
expectSplitRows(full);
const agentTick = mergeCanonicalResourceDeltaSnapshot(
[structuredClone(splitNode), { ...structuredClone(splitAgent), cpu: { current: 42 } }],
full,
new Set(['agent-machine-pve1']),
);
expectSplitRows(agentTick);
expect(agentTick[0]).toBe(full[0]);
expect(agentTick[1]?.cpu?.current).toBe(42);
const bothTick = mergeCanonicalResourceDeltaSnapshot(
[
{ ...structuredClone(splitNode), cpu: { current: 7 } },
{ ...structuredClone(splitAgent), cpu: { current: 43 } },
],
agentTick,
new Set(['agent-node-pve1', 'agent-machine-pve1']),
);
expectSplitRows(bothTick);
expect(bothTick.map((row) => row.cpu?.current)).toEqual([7, 43]);
// A delta that adds the node beside the joined row (the split's first
// tick) leaves two rows as well.
const firstSplitTick = mergeCanonicalResourceDeltaSnapshot(
[structuredClone(splitAgent), structuredClone(splitNode)],
mergeCanonicalResourceSnapshot([structuredClone(joinedHost)], []),
new Set(['agent-machine-pve1', 'agent-node-pve1']),
);
expectSplitRows(firstSplitTick);
});
it('keeps REST-only scopes a departed source did not own', () => {
// A Docker container in a Proxmox LXC whose availability check was
// removed: REST promoted its platform scopes and source status,
// which the realtime payload never carries. Docker stays listed, so its
// status entry, its recorded action refusal and its Proxmox scope (the LXC
// host) stay; only the availability entry goes.
const restRow = {
id: 'app-container-frigate',
type: 'app-container',
name: 'frigate',
displayName: 'frigate',
platformType: 'docker',
platformScopes: ['proxmox-pve', 'docker', 'availability'],
sourceType: 'hybrid',
status: 'online',
lastSeen,
actionReadiness: [{ name: 'restart', available: false, reason: 'lifecycle disabled' }],
availability: { status: 'up' },
sourceStatus: { docker: { status: 'impaired' }, availability: { status: 'online' } },
platformData: {
sources: ['docker', 'availability'],
sourceStatus: { docker: { status: 'impaired' }, availability: { status: 'online' } },
docker: { hostSourceId: 'proxmox-lxc-docker:pve-a:node-a:141', runtime: 'docker' },
},
} as unknown as Resource;
const [row] = mergeCanonicalResourceSnapshot(
[
{
id: 'app-container-frigate',
type: 'app-container',
name: 'frigate',
displayName: 'frigate',
platformType: 'docker',
sourceType: 'api',
sources: ['docker'],
status: 'online',
lastSeen,
docker: { hostSourceId: 'proxmox-lxc-docker:pve-a:node-a:141', runtime: 'docker' },
} as unknown as Resource,
],
[restRow],
);
expect(row?.platformScopes).toEqual(['proxmox-pve', 'docker']);
expect(row?.actionReadiness).toEqual([
{ name: 'restart', available: false, reason: 'lifecycle disabled' },
]);
expect(row?.availability).toBeUndefined();
expect(row?.sourceStatus).toEqual({ docker: { status: 'impaired' } });
expect((row?.platformData as Record<string, unknown>).sourceStatus).toEqual({
docker: { status: 'impaired' },
});
});
it('keeps the Proxmox scope of a Docker LXC host when a Proxmox source departs', () => {
// The row's two lists disagree (an enrichment of another generation named a
// Proxmox source). The Docker host still runs inside a Proxmox container, so
// the server keeps placing it on the Proxmox page whatever sources it lists;
// an agent scope no surviving source or facet supports goes.
const hostSourceId = 'proxmox-lxc-docker:pve-a:node-a:141';
const skewed = {
id: 'docker-host-141',
type: 'agent',
name: 'frigate-host',
displayName: 'frigate-host',
platformType: 'docker',
platformScopes: ['proxmox-pve', 'docker', 'agent'],
sourceType: 'api',
sources: ['docker'],
status: 'online',
lastSeen,
docker: { hostSourceId, runtime: 'docker' },
platformData: {
sources: ['docker', 'proxmox', 'agent'],
docker: { hostSourceId, runtime: 'docker' },
},
} as unknown as Resource;
const realtime = {
id: 'docker-host-141',
type: 'agent',
name: 'frigate-host',
displayName: 'frigate-host',
platformType: 'docker',
sourceType: 'api',
sources: ['docker'],
status: 'online',
lastSeen,
docker: { hostSourceId, runtime: 'docker' },
} as unknown as Resource;
const [row] = mergeCanonicalResourceSnapshot([realtime], [skewed]);
expect(row?.platformScopes).toEqual(['proxmox-pve', 'docker']);
});
it('drops the agent scope of a split node that keeps the joined id', () => {
// The node's flattened kernel version reads as an agent facet once the row
// is canonicalized; that is compatibility synthesis, not evidence that the
// agent still reports for this row.
const joined = {
...structuredClone(joinedHost),
platformScopes: ['agent', 'proxmox-pve'],
} as unknown as Resource;
const node = {
...structuredClone(splitNode),
id: joinedHost.id,
platformData: { ...proxmoxPlatformData, kernelVersion: '6.14.8-2-pve' },
} as unknown as Resource;
const [row] = mergeCanonicalResourceSnapshot([node], [joined]);
expect(row?.sources).toEqual(['proxmox']);
expect(row?.platformScopes).toEqual(['proxmox-pve']);
});
it('keeps the Proxmox scope of an agent-reported disk that carries a Proxmox facet', () => {
// The server gives an agent-reported SMART disk under a merged Proxmox node
// a Proxmox ownership facet while it lists only the agent (registry.go).
const previous = {
id: 'disk-1',
type: 'physical_disk',
name: 'sda',
displayName: 'sda',
platformType: 'agent',
platformScopes: ['agent', 'proxmox-pve'],
sourceType: 'agent',
sources: ['agent'],
status: 'online',
lastSeen,
platformData: { sources: ['agent', 'proxmox'] },
} as unknown as Resource;
const incoming = {
id: 'disk-1',
type: 'physical_disk',
name: 'sda',
displayName: 'sda',
platformType: 'agent',
sourceType: 'agent',
sources: ['agent'],
status: 'online',
lastSeen,
proxmox: { nodeName: 'pve1', instance: 'pve1' },
} as unknown as Resource;
const [row] = mergeCanonicalResourceSnapshot([incoming], [previous]);
expect(row?.platformScopes).toEqual(['agent', 'proxmox-pve']);
});
it('deletes inherited source status when pruning leaves nothing', () => {
const status = { proxmox: { status: 'online', lastSeen: '2026-02-06T12:00:00Z' } };
const previous = {
...structuredClone(joinedHost),
sourceStatus: status,
platformData: { sources: ['agent', 'proxmox'], sourceStatus: status },
} as unknown as Resource;
// The incoming row's own enrichment names only the departed source.
const incoming = {
...structuredClone(splitAgent),
sourceStatus: status,
platformData: { sources: ['agent'], sourceStatus: status },
} as unknown as Resource;
const [row] = mergeCanonicalResourceSnapshot([incoming], [previous]);
expect(row?.sourceStatus).toBeUndefined();
expect((row?.platformData as Record<string, unknown>).sourceStatus).toBeUndefined();
});
it('rebuilds a row whose own source lists disagree once the realtime row drops the extra source', () => {
// What a late REST response, or a shared array that changed under the row,
// leaves behind: top-level sources already say agent, the joined era's
// enrichment still says Proxmox too.
const status = {
agent: { status: 'online', lastSeen: '2026-02-06T12:00:00Z' },
proxmox: { status: 'online', lastSeen: '2026-02-06T12:00:00Z' },
};
const halfUpdated = {
...structuredClone(splitAgent),
platformType: 'proxmox-pve',
platformScopes: ['agent', 'proxmox-pve'],
sourceStatus: status,
canonicalIdentity: {
...splitAgent.canonicalIdentity,
aliases: ['agent:machine-pve1', 'node:pve1:pve1'],
},
platformData: {
sources: ['agent', 'proxmox'],
platformScopes: ['agent', 'proxmox-pve'],
sourceStatus: status,
...proxmoxPlatformData,
},
} as unknown as Resource;
const [row] = mergeCanonicalResourceSnapshot([structuredClone(splitAgent)], [halfUpdated]);
expect(row?.platformType).toBe('agent');
expect(row?.platformScopes ?? []).not.toContain('proxmox-pve');
expect(Object.keys(row?.sourceStatus ?? {})).not.toContain('proxmox');
const platformData = row?.platformData as Record<string, unknown>;
expect(platformData.sources).toEqual(['agent']);
expect(platformData.platformScopes).toBeUndefined();
expect(Object.keys(platformData.sourceStatus as object)).toEqual(['agent']);
expect(Object.keys(row?.sourceStatus ?? {})).toEqual(['agent']);
expect(platformData.pveVersion).toBeUndefined();
expect(row?.canonicalIdentity?.aliases).toEqual(['agent:machine-pve1']);
});
it('prunes source status entries of sources the merged row no longer lists', () => {
const status = {
agent: { status: 'online', lastSeen: '2026-02-06T12:00:00Z' },
proxmox: { status: 'online', lastSeen: '2026-02-06T12:00:00Z' },
};
// The previous display row already lists only the agent but still carries
// the enrichment of the joined era (what a late REST response leaves).
const existing = {
id: 'agent-machine-pve1',
type: 'agent',
name: 'pve1',
displayName: 'pve1',
platformId: 'pve1',
platformType: 'agent',
sourceType: 'agent',
sources: ['agent'],
status: 'online',
lastSeen,
sourceStatus: status,
platformData: { sources: ['agent'], sourceStatus: status },
} as unknown as Resource;
// A realtime row omits the key; it never sets it to undefined.
const withoutStatus = (row: Resource, sources: string[]): Resource => {
const copy = structuredClone(row) as unknown as Record<string, unknown>;
delete copy.sourceStatus;
copy.platformData = { sources };
return copy as unknown as Resource;
};
const incoming = withoutStatus(existing, ['agent']);
const [row] = mergeCanonicalResourceSnapshot([incoming], [existing]);
expect(Object.keys(row?.sourceStatus ?? {})).toEqual(['agent']);
expect(
Object.keys((row?.platformData as Record<string, unknown>).sourceStatus as object),
).toEqual(['agent']);
// Entries of listed sources stay, as REST enrichment the realtime row lacks.
const joined = {
...structuredClone(existing),
sources: ['agent', 'proxmox'],
platformData: { sources: ['agent', 'proxmox'], sourceStatus: status },
} as unknown as Resource;
const [kept] = mergeCanonicalResourceSnapshot(
[withoutStatus(joined, ['agent', 'proxmox'])],
[joined],
);
expect(Object.keys(kept?.sourceStatus ?? {}).sort()).toEqual(['agent', 'proxmox']);
});
it('merges a thin row without a source list of its own instead of rebuilding it', () => {
// Only a source list the incoming row carries proves a source left; one
// inferred from a thin row's facets does not.
const previous = mergeCanonicalResourceSnapshot([structuredClone(joinedHost)], [])[0]!;
const thin = {
...structuredClone(joinedHost),
sources: undefined,
agent: undefined,
platformData: undefined,
} as unknown as Resource;
const [row] = mergeCanonicalResourceSnapshot([thin], [previous]);
expect(row?.clusterId).toBe('cluster:homelab');
expect(row?.canonicalIdentity?.aliases).toEqual(['agent:machine-pve1', 'node:pve1:pve1']);
expect((row?.identity as Record<string, unknown>).machineId).toBe('machine-pve1');
});
it('keeps same-hostname standalone Proxmox provider rows separate across realtime merges', () => {
const providerRow = (
id: string,
displayName: string,
instance: string,
host: string,
agentId?: string,
): Resource =>
({
id,
type: 'agent',
name: displayName,
displayName,
platformId: 'pve',
platformType: 'proxmox-pve',
sourceType: agentId ? 'hybrid' : 'api',
sources: agentId ? ['proxmox', 'agent'] : ['proxmox'],
status: 'online',
lastSeen: Date.now(),
canonicalIdentity: {
displayName,
hostname: 'pve',
platformId: 'pve',
},
identity: {
hostnames: ['pve'],
...(agentId ? { machineId: `machine-${agentId}` } : {}),
},
proxmox: {
sourceId: id,
nodeIdentity: id,
nodeName: 'pve',
nodeDisplayName: displayName,
instance,
host,
},
...(agentId
? {
agent: {
agentId,
hostname: 'pve',
machineId: `machine-${agentId}`,
},
}
: {}),
}) as Resource;
// Mirrors #1753 after one same-name site's agent has authenticated while
// the other is still represented by its independent provider poll. The
// browser must not undo the server's provider-scoped split on a later
// realtime reconciliation. Whether two rows of one endpoint join is the
// server's presentation decision (presentation_coalesce.go).
const staging = providerRow(
'staging-pve',
'Tripper Staging',
'hema-staging',
'https://pve.hemastaging.hot:8006',
'host-staging',
);
const production = providerRow(
'production-pve',
'VV Staging',
'hema-production',
'https://pve.hemaproduction.hot:8006',
);
const full = mergeCanonicalResourceSnapshot([staging, production], []);
expect(full).toHaveLength(2);
expect(full.map((resource) => resource.displayName).sort()).toEqual([
'Tripper Staging',
'VV Staging',
]);
const delta = mergeCanonicalResourceDeltaSnapshot(
[structuredClone(staging), structuredClone(production)],
full,
new Set(['production-pve']),
);
expect(delta).toHaveLength(2);
expect(delta.map((resource) => resource.proxmox?.instance).sort()).toEqual([
'hema-production',
'hema-staging',
]);
});
it('does not coalesce same-name agent-only records without a platform source bridge', () => {
const resources = mergeCanonicalResourceSnapshot(
[
{
id: 'agent-runtime-1',
type: 'agent',
name: 'shared-hostname',
displayName: 'shared-hostname',
platformId: 'shared-hostname',
platformType: 'agent',
sourceType: 'agent',
sources: ['agent'],
status: 'online',
lastSeen: Date.now(),
} as Resource,
{
id: 'agent-runtime-2',
type: 'agent',
name: 'shared-hostname',
displayName: 'shared-hostname',
platformId: 'shared-hostname',
platformType: 'agent',
sourceType: 'agent',
sources: ['agent'],
status: 'online',
lastSeen: Date.now(),
} as Resource,
],
[],
);
expect(resources.map((resource) => resource.id)).toEqual([
'agent-runtime-1',
'agent-runtime-2',
]);
});
it.each(['vmware', 'truenas', 'agent'])(
'keeps flat storage coordinates within their %s source',
(source) => {
const platformType = source === 'vmware' ? 'vmware-vsphere' : source;
const incoming = {
...createNodeResource({ instance: 'storage-canonical', node: '', cpus: 4 }),
id: 'storage-canonical',
type: 'storage',
platformType,
sources: [source],
vmware:
source === 'vmware' ? { connectionId: 'vc-1', connectionName: 'Lab vCenter' } : undefined,
} as Resource;
const [resource] = mergeCanonicalResourceSnapshot([incoming], []);
expect(resource.proxmox).toBeUndefined();
expect((resource.platformData as Record<string, unknown>).proxmox).toBeUndefined();
expect(resource.platformType).toBe(platformType);
expect(resource.vmware).toEqual(incoming.vmware);
const [refreshed] = mergeCanonicalResourceDeltaSnapshot(
[incoming],
[resource],
new Set([incoming.id]),
);
expect(refreshed.proxmox).toBeUndefined();
expect(refreshed.vmware).toEqual(incoming.vmware);
},
);
it('keeps explicit Proxmox ownership on an agent-reported disk', () => {
const incoming = {
...createNodeResource({ instance: 'legacy-storage-coordinate' }),
type: 'physical_disk',
platformType: 'agent',
sources: ['agent'],
proxmox: { instance: 'owned-pve', nodeName: 'owned-node' },
} as Resource;
const [resource] = mergeCanonicalResourceSnapshot([incoming], []);
expect(resource.proxmox).toEqual(incoming.proxmox);
});
it('uses authoritative top-level sources for realtime storage platform canonicalization', () => {
const [resource] = mergeCanonicalResourceSnapshot(
[
{
id: 'storage:tower-array',
type: 'storage',
name: 'Tower Array',
displayName: 'Tower Array',
platformId: 'tower-array',
platformType: 'proxmox-pve',
sourceType: 'agent',
sources: ['agent'],
status: 'degraded',
lastSeen: Date.now(),
storage: {
platform: 'unraid',
type: 'unraid-array',
topology: 'array',
postureSummary: 'Unraid array is running without parity protection',
},
platformData: {
platform: 'unraid',
type: 'unraid-array',
topology: 'array',
postureSummary: 'Unraid array is running without parity protection',
},
} as Resource,
],
[],
);
expect(resource.platformType).toBe('agent');
expect(resource.sourceType).toBe('agent');
expect((resource.platformData as Record<string, unknown>).sources).toEqual(['agent']);
expect((resource.platformData as Record<string, unknown>).storage).toMatchObject({
platform: 'unraid',
type: 'unraid-array',
topology: 'array',
});
expect((resource.platformData as Record<string, unknown>).proxmox).toBeUndefined();
});
it('does not synthesize Docker platform state from an empty machine-agent Docker facet', () => {
const [resource] = mergeCanonicalResourceSnapshot(
[
{
id: 'agent-tower',
type: 'agent',
name: 'Tower',
displayName: 'Tower',
platformId: 'tower',
platformType: 'agent',
sourceType: 'hybrid',
status: 'online',
lastSeen: Date.now(),
agent: {
hostname: 'Tower',
},
docker: {},
platformData: {
agent: {
hostname: 'Tower',
},
docker: {},
},
} as Resource,
],
[],
);
expect(resource.platformType).toBe('agent');
expect(resource.sourceType).toBe('agent');
expect(resource.docker).toBeUndefined();
expect((resource.platformData as Record<string, unknown>).sources).toEqual(['agent']);
expect((resource.platformData as Record<string, unknown>).docker).toBeUndefined();
});
it('replaces stale platform source facets with the current snapshot sources', () => {
const existing = {
id: 'agent-tower',
type: 'agent',
name: 'Tower',
displayName: 'Tower',
platformId: 'tower',
platformType: 'proxmox-pve',
sourceType: 'hybrid',
status: 'degraded',
lastSeen: Date.now(),
proxmox: {
nodeName: 'Tower',
},
agent: {
hostname: 'Tower',
hostProfile: 'unraid',
osName: 'Unraid',
},
platformData: {
sources: ['proxmox', 'docker', 'agent'],
proxmox: {
nodeName: 'Tower',
},
docker: {
runtime: 'docker',
},
agent: {
hostname: 'Tower',
hostProfile: 'unraid',
osName: 'Unraid',
},
},
} as Resource;
const [resource] = mergeCanonicalResourceSnapshot(
[
{
id: 'agent-tower',
type: 'agent',
name: 'Tower',
displayName: 'Tower',
platformId: 'tower',
platformType: 'agent',
sourceType: 'hybrid',
status: 'degraded',
lastSeen: Date.now(),
agent: {
hostname: 'Tower',
hostProfile: 'unraid',
osName: 'Unraid',
},
docker: {
runtime: 'docker',
},
} as Resource,
],
[existing],
);
expect(resource.platformType).toBe('docker');
expect(resource.sourceType).toBe('hybrid');
expect(resource.proxmox).toBeUndefined();
expect(resource.agent).toMatchObject({ hostProfile: 'unraid', osName: 'Unraid' });
expect((resource.platformData as Record<string, unknown>).sources).toEqual(['docker', 'agent']);
expect((resource.platformData as Record<string, unknown>).proxmox).toBeUndefined();
});
it('does not synthesize a Proxmox facet from flat agent disk telemetry', () => {
const [resource] = mergeCanonicalResourceSnapshot(
[
{
id: 'agent-tower',
type: 'agent',
name: 'Tower',
displayName: 'Tower',
platformId: 'tower',
platformType: 'agent',
sourceType: 'hybrid',
status: 'degraded',
lastSeen: Date.now(),
agent: {
hostname: 'Tower',
hostProfile: 'unraid',
osName: 'Unraid',
},
docker: {
runtime: 'docker',
},
platformData: {
osName: 'Unraid',
osVersion: '7.2.2',
platform: 'linux',
disks: [
{
device: 'rootfs',
mountpoint: '/',
filesystem: 'rootfs',
},
],
},
} as Resource,
],
[],
);
expect(resource.platformType).toBe('docker');
expect((resource.platformData as Record<string, unknown>).sources).toEqual(['docker', 'agent']);
expect((resource.platformData as Record<string, unknown>).proxmox).toBeUndefined();
});
it('preserves richer existing resource details when realtime updates are thinner', () => {
const existing: Resource = {
id: 'node-1',
type: 'agent',
name: 'West Production A',
displayName: 'West Production A',
platformId: 'west-production-a',
platformType: 'proxmox-pve',
sourceType: 'hybrid',
status: 'online',
lastSeen: Date.now(),
cpu: { current: 10 },
diskIO: { readRate: 1_250_000, writeRate: 640_000 },
platformData: {
proxmox: {
clusterName: 'Core Fabric',
},
},
} as Resource;
const [merged] = mergeCanonicalResourceSnapshot(
[
{
id: 'node-1',
type: 'agent',
name: 'West Production A',
displayName: 'West Production A',
platformId: 'west-production-a',
platformType: 'proxmox-pve',
sourceType: 'hybrid',
status: 'online',
lastSeen: Date.now(),
cpu: { current: 42 },
platformData: {},
} as Resource,
],
[existing],
);
expect(merged.cpu?.current).toBe(42);
expect(merged.diskIO).toEqual({
readRate: 1_250_000,
writeRate: 640_000,
});
expect(merged.clusterId).toBe('Core Fabric');
});
it('preserves canonical health context from realtime resources', () => {
const [agent] = mergeCanonicalResourceSnapshot(
[
{
id: 'agent:tower',
type: 'agent',
name: 'Tower',
displayName: 'Tower',
platformId: 'agent-1',
platformType: 'agent',
sourceType: 'agent',
status: 'degraded',
lastSeen: Date.now(),
incidentSummary: 'Unraid array is running without parity protection',
agent: {
osName: 'Unraid',
storagePostureSummary: 'Unraid array is running without parity protection',
unraid: {
postureSummary: 'Unraid array is running without parity protection',
risk: {
level: 'warning',
reasons: [
{
code: 'unraid_no_parity',
severity: 'warning',
summary: 'Unraid array is running without parity protection',
},
],
},
},
},
} as Resource,
],
[],
);
expect(agent.incidentSummary).toBe('Unraid array is running without parity protection');
expect(agent.agent?.storagePostureSummary).toBe(
'Unraid array is running without parity protection',
);
expect(agent.agent?.unraid?.risk?.reasons?.[0]?.code).toBe('unraid_no_parity');
});
});
describe('resourceStateAdapters unavailable memory contract', () => {
const unavailableProxmoxMemory = {
nodeName: 'n1',
memory: {
total: 8192,
used: 0,
free: 0,
usage: 0,
usageUnavailable: true,
},
} as unknown as Resource['proxmox'];
it('clears a previous metric when a snapshot explicitly reports unavailable memory', () => {
const previous = createNodeResource({});
const incoming = { ...previous, proxmox: unavailableProxmoxMemory };
delete incoming.memory; // JSON omitempty, not an explicit undefined property.
const [merged] = mergeCanonicalResourceSnapshot([incoming], [previous]);
expect(nodeFromResource(merged)?.memory.usageUnavailable).toBe(true);
expect(merged.memory).toBeUndefined();
});
it('clears withdrawn memory through both delta paths and emits the store clear', () => {
const previous = {
...createNodeResource({}),
type: 'vm',
proxmox: unavailableProxmoxMemory,
} as Resource;
const incoming = { ...previous };
delete incoming.memory;
for (const keys of [undefined, new Map([[previous.id, ['memory']]])]) {
const [merged] = mergeCanonicalResourceDeltaSnapshot(
[incoming],
[previous],
new Set([previous.id]),
keys,
);
expect(merged.memory).toBeUndefined();
expect(buildFastResourceStorePatchOps(merged, ['memory'])).toEqual([
{ key: 'memory', value: undefined, mode: 'set' },
]);
expect(buildFastResourceStorePatchOps(merged, ['proxmox'])).toContainEqual({
key: 'memory',
value: undefined,
mode: 'set',
});
}
});
it('retains richer memory on partial omission without unavailable evidence', () => {
const previous = createNodeResource({});
const incoming = { ...previous };
delete incoming.memory;
const [merged] = mergeCanonicalResourceSnapshot([incoming], [previous]);
expect(merged.memory).toEqual(previous.memory);
});
it('accepts a newly trusted metric after an unavailable snapshot', () => {
const previous = { ...createNodeResource({}), proxmox: unavailableProxmoxMemory };
delete previous.memory;
const incoming = { ...previous, memory: { current: 0, total: 8192, used: 0 } };
const [merged] = mergeCanonicalResourceSnapshot([incoming], [previous]);
expect(nodeFromResource(merged)?.memory).toMatchObject({ usage: 0, usageUnavailable: false });
});
it('preserves explicit unavailable usage when no trusted metric exists', () => {
const node = nodeFromResource({
...createNodeResource({}),
memory: undefined,
proxmox: unavailableProxmoxMemory,
});
expect(node?.memory).toMatchObject({
total: 8192,
used: 0,
usage: 0,
usageUnavailable: true,
});
});
it('lets a trusted merged metric override unavailable raw evidence', () => {
const node = nodeFromResource({
...createNodeResource({}),
memory: { current: 50, total: 8192, used: 4096, free: 4096 },
proxmox: unavailableProxmoxMemory,
});
expect(node?.memory).toMatchObject({
total: 8192,
used: 4096,
usage: 50,
usageUnavailable: false,
});
});
});
describe('incremental canonical resource snapshots', () => {
it('clears a node sensor setup verdict when the next snapshot sends false', () => {
// Facets merge field by field and an omitted field is read as a partial
// snapshot, so the registry sends every Proxmox node an explicit verdict.
const node = (sensorSetupOutdated?: boolean) =>
({
id: 'agent-pve3',
type: 'agent',
name: 'pve3',
status: 'online',
sources: ['proxmox'],
proxmox: { nodeName: 'pve3', sensorSetupOutdated },
}) as unknown as Resource;
const [cleared] = mergeCanonicalResourceSnapshot([node(false)], [node(true)]);
expect(cleared?.proxmox?.sensorSetupOutdated).toBe(false);
const [omitted] = mergeCanonicalResourceSnapshot(
[{ ...node(), proxmox: { nodeName: 'pve3' } } as unknown as Resource],
[node(true)],
);
expect(omitted?.proxmox?.sensorSetupOutdated).toBe(true);
});
it('preserves untouched row identity while refreshing changed resources', () => {
const unchanged = {
id: 'vm-unchanged',
type: 'vm',
name: 'vm-unchanged',
status: 'running',
cpu: { current: 10 },
} as Resource;
const changed = {
id: 'vm-changed',
type: 'vm',
name: 'vm-changed',
status: 'running',
cpu: { current: 20 },
} as Resource;
const incoming = [
structuredClone(unchanged),
{ ...structuredClone(changed), cpu: { current: 75 } },
];
const result = mergeCanonicalResourceDeltaSnapshot(
incoming,
[unchanged, changed],
new Set(['vm-changed']),
);
expect(result[0]).toBe(unchanged);
expect(result[1]).not.toBe(changed);
expect(result[1]?.cpu?.current).toBe(75);
});
it('preserves an unchanged agent row by identity', () => {
const agent = {
id: 'agent-a',
type: 'agent',
name: 'host-a',
status: 'online',
sources: ['agent'],
} as unknown as Resource;
const vm = {
id: 'vm-1',
type: 'vm',
name: 'vm-1',
status: 'running',
cpu: { current: 5 },
} as Resource;
const incoming = [structuredClone(agent), { ...structuredClone(vm), cpu: { current: 60 } }];
const result = mergeCanonicalResourceDeltaSnapshot(incoming, [agent, vm], new Set(['vm-1']));
expect(result[0]).toBe(agent);
expect(result[1]?.cpu?.current).toBe(60);
});
it('refreshes an agent when its own id is in the delta', () => {
const agent = {
id: 'agent-a',
type: 'agent',
name: 'host-a',
status: 'online',
cpu: { current: 10 },
sources: ['agent'],
} as unknown as Resource;
const incoming = [{ ...structuredClone(agent), cpu: { current: 90 } }];
const result = mergeCanonicalResourceDeltaSnapshot(incoming, [agent], new Set(['agent-a']));
expect(result[0]).not.toBe(agent);
expect(result[0]?.cpu?.current).toBe(90);
});
it('drops a removed row and keeps its same-host neighbour by identity', () => {
// A flagged id missing from the incoming snapshot is a removal; the
// neighbour sharing its hostname is a separate server row and stays as is.
const agent = {
id: 'agent-a',
type: 'agent',
name: 'host-a',
status: 'online',
sources: ['agent'],
} as unknown as Resource;
const platformSide = {
id: 'pve-a',
type: 'agent',
name: 'host-a',
status: 'online',
sources: ['proxmox-pve'],
} as unknown as Resource;
const result = mergeCanonicalResourceDeltaSnapshot(
[structuredClone(agent)],
[agent, platformSide],
new Set(['pve-a']),
);
expect(result).toHaveLength(1);
expect(result[0]).toBe(agent);
});
it('keeps two server rows that share a hostname as two rows', () => {
const agentSide = {
id: 'agent-a',
type: 'agent',
name: 'host-a',
status: 'online',
sources: ['agent'],
} as unknown as Resource;
const platformSide = {
id: 'pve-a',
type: 'agent',
name: 'host-a',
status: 'online',
sources: ['proxmox-pve'],
} as unknown as Resource;
const incoming = [structuredClone(agentSide), structuredClone(platformSide)];
const result = mergeCanonicalResourceDeltaSnapshot(incoming, [], new Set(['pve-a']));
expect(result.map((row) => row.id)).toEqual(['agent-a', 'pve-a']);
expect(result[0]?.sources).toEqual(['agent']);
expect(result[1]?.sources).toEqual(['proxmox-pve']);
});
});
describe('fast merge path for metrics-only delta patches', () => {
// Mirrors the wire shape of a PVE guest metrics tick captured from the mock
// estate: top-level metric subtrees, the proxmox facet mirror, and the four
// platformData metric mirror leaves.
const createPveGuestRaw = (): Resource =>
({
id: 'vm-fast-1',
type: 'vm',
name: 'vm-fast-1',
displayName: 'VM Fast 1',
platformId: 'pve-node-1',
platformType: 'proxmox-pve',
sourceType: 'api',
status: 'running',
lastSeen: 1700000000000,
uptime: 1000,
cpu: { current: 10 },
memory: { current: 20, total: 1024, used: 256, free: 768 },
disk: { current: 30, total: 2048, used: 512, free: 1536 },
network: { rxBytes: 100, txBytes: 200 },
diskIO: { readRate: 5, writeRate: 7 },
tags: ['prod'],
canonicalIdentity: { canonicalId: 'vm-fast-1', aliases: ['vm/100'] },
proxmox: {
vmid: 100,
nodeName: 'pve-node-1',
memory: { free: 768, usage: 20, used: 256 },
uptime: 1000,
},
platformData: {
sources: ['proxmox-pve'],
instance: 'pve-node-1',
vmid: 100,
diskRead: 5,
diskWrite: 7,
networkIn: 100,
networkOut: 200,
proxmox: { vmid: 100, nodeName: 'pve-node-1' },
},
}) as unknown as Resource;
const METRICS_PATCH_KEYS = [
'cpu',
'uptime',
'lastSeen',
'memory',
'network',
'diskIO',
'proxmox',
'platformData.diskRead',
'platformData.diskWrite',
'platformData.networkIn',
'platformData.networkOut',
] as const;
const applyMetricsTick = (raw: Resource): Resource => {
const next = structuredClone(raw) as unknown as Record<string, unknown>;
next.cpu = { current: 55 };
next.uptime = 1002;
next.lastSeen = 1700000002000;
next.memory = { current: 40, total: 1024, used: 400, free: 624 };
next.network = { rxBytes: 300, txBytes: 400 };
next.diskIO = { readRate: 9, writeRate: 11 };
next.proxmox = {
...(next.proxmox as Record<string, unknown>),
memory: { free: 624, usage: 40, used: 400 },
uptime: 1002,
};
next.platformData = {
...(next.platformData as Record<string, unknown>),
diskRead: 9,
diskWrite: 11,
networkIn: 300,
networkOut: 400,
};
return next as unknown as Resource;
};
const seedDisplayRows = (raw: Resource[]): Resource[] =>
mergeCanonicalResourceDeltaSnapshot(
raw.map((row) => structuredClone(row)),
[],
new Set(raw.map((row) => row.id)),
);
it('clears omitted guest read-state fields on a new native outcome in full and fast deltas', () => {
const raw = createPveGuestRaw();
raw.proxmox = {
...raw.proxmox,
runtimeStatus: 'running',
guestAgentStatus: 'deferred',
diskStatusReason: 'prev-vm-locked',
guestAgentExpected: true,
lock: 'backup',
};
const previous = seedDisplayRows([raw]);
const incoming = structuredClone(raw);
incoming.proxmox = {
vmid: 100,
nodeName: 'pve-node-1',
runtimeStatus: 'running',
guestAgentStatus: 'available',
};
const changed = new Set([raw.id]);
const keys = new Map([[raw.id, ['proxmox']]]);
expect(getFastResourceMergePatchKeys(keys, raw.id, previous[0])).toEqual(['proxmox']);
const full = mergeCanonicalResourceSnapshot([incoming], previous);
const delta = mergeCanonicalResourceDeltaSnapshot([incoming], previous, changed);
const fast = mergeCanonicalResourceDeltaSnapshot([incoming], previous, changed, keys);
expect(fast[0]).toEqual(delta[0]);
expect(fast[0]).toEqual(full[0]);
for (const [merged] of [full, delta, fast]) {
expect(merged.proxmox?.guestAgentStatus).toBe('available');
expect(merged.proxmox?.diskStatusReason).toBeUndefined();
expect(merged.proxmox?.lock).toBeUndefined();
expect(merged.proxmox?.guestAgentExpected).toBeUndefined();
expect(merged.proxmox?.uptime).toBe(1000); // unrelated richer facet is retained
expect(buildFastResourceStorePatchOps(merged, ['proxmox'])).toContainEqual({
key: 'proxmox',
value: merged.proxmox,
mode: 'reconcile',
});
}
});
it('applies the same read-state clearing to the compatibility provider facet', () => {
const raw = createPveGuestRaw();
raw.proxmox = {
...raw.proxmox,
runtimeStatus: 'running',
guestAgentStatus: 'deferred',
diskStatusReason: 'prev-vm-locked',
guestAgentExpected: true,
lock: 'backup',
};
raw.platformData = { ...raw.platformData, proxmox: raw.proxmox };
const previous = seedDisplayRows([raw]);
const incoming = structuredClone(raw);
incoming.proxmox = {
vmid: 100,
nodeName: 'pve-node-1',
runtimeStatus: 'running',
guestAgentStatus: 'available',
};
incoming.platformData = { ...incoming.platformData, proxmox: incoming.proxmox };
const [merged] = mergeCanonicalResourceSnapshot([incoming], previous);
expect(merged.platformData?.proxmox).toEqual(merged.proxmox);
expect(merged.proxmox?.diskStatusReason).toBeUndefined();
expect(merged.proxmox?.lock).toBeUndefined();
});
it('preserves read-state evidence on partial facet omission, including the fast path', () => {
const raw = createPveGuestRaw();
raw.proxmox = {
...raw.proxmox,
runtimeStatus: 'running',
guestAgentStatus: 'deferred',
diskStatusReason: 'prev-agent-timeout',
guestAgentExpected: true,
lock: 'backup',
};
const previous = seedDisplayRows([raw]);
for (const proxmox of [
undefined,
{ vmid: 100, uptime: 1001 },
{ guestAgentStatus: 'available' },
{ vmid: 0, runtimeStatus: 'running', guestAgentStatus: 'available' },
{ vmid: 1.5, runtimeStatus: 'running', guestAgentStatus: 'available' },
{ vmid: Infinity, runtimeStatus: 'running', guestAgentStatus: 'available' },
{ vmid: 100, runtimeStatus: ' ', guestAgentStatus: 'available' },
{ vmid: 100, runtimeStatus: 'running', guestAgentStatus: ' ' },
]) {
const incoming = { ...raw, proxmox } as Resource;
const full = mergeCanonicalResourceSnapshot([incoming], previous);
const fast = mergeCanonicalResourceDeltaSnapshot(
[incoming],
previous,
new Set([raw.id]),
new Map([[raw.id, ['proxmox']]]),
);
for (const [merged] of [full, fast]) {
expect(merged.proxmox).toMatchObject({
diskStatusReason: 'prev-agent-timeout',
guestAgentExpected: true,
lock: 'backup',
});
}
}
});
it("lets a linked agent's filesystems and freshness replace withdrawn ones", () => {
const raw = createPveGuestRaw();
raw.sources = ['proxmox-pve', 'agent'] as Resource['sources'];
raw.platformData = { ...raw.platformData, sources: ['proxmox-pve', 'agent'] };
raw.proxmox = {
...raw.proxmox,
runtimeStatus: 'running',
guestAgentStatus: 'available',
disks: [{ mountpoint: '/', total: 2048, used: 512 }],
};
raw.agent = {
agentId: 'agent-in-vm',
stale: true,
disks: [{ mountpoint: '/', total: 4096, used: 1024 }],
} as Resource['agent'];
raw.platformData = { ...raw.platformData, agent: raw.agent };
const previous = seedDisplayRows([raw]);
// The guest agent stopped, so Proxmox withdraws its filesystems, and the
// linked Pulse agent reports again with an explicit stale=false.
const incoming = structuredClone(raw);
incoming.proxmox = {
vmid: 100,
nodeName: 'pve-node-1',
runtimeStatus: 'running',
guestAgentStatus: 'expected-unreachable',
diskStatusReason: 'agent-not-running',
};
incoming.agent = { ...raw.agent, stale: false } as Resource['agent'];
incoming.platformData = { ...incoming.platformData, agent: incoming.agent };
const changed = new Set([raw.id]);
const full = mergeCanonicalResourceSnapshot([incoming], previous);
const delta = mergeCanonicalResourceDeltaSnapshot([incoming], previous, changed);
const fast = mergeCanonicalResourceDeltaSnapshot(
[incoming],
previous,
changed,
new Map([[raw.id, ['proxmox', 'agent']]]),
);
for (const [merged] of [full, delta, fast]) {
expect(merged.proxmox?.disks).toBeUndefined();
expect(merged.proxmox?.diskStatusReason).toBe('agent-not-running');
expect(merged.agent?.stale).toBe(false);
expect(merged.agent?.disks).toEqual(raw.agent?.disks);
}
// A partial facet without a native outcome keeps the prior filesystems.
const partial = { ...raw, proxmox: { vmid: 100, uptime: 1001 } } as Resource;
const [kept] = mergeCanonicalResourceSnapshot([partial], previous);
expect(kept.proxmox?.disks).toEqual(raw.proxmox?.disks);
// A native agent report (it always carries stale) without disks has
// withdrawn them; a legacy facet without stale keeps the prior list.
const withdrawn = structuredClone(raw);
withdrawn.agent = { agentId: 'agent-in-vm', stale: false } as Resource['agent'];
withdrawn.platformData = { ...withdrawn.platformData, agent: withdrawn.agent };
for (const [merged] of [
mergeCanonicalResourceSnapshot([withdrawn], previous),
mergeCanonicalResourceDeltaSnapshot([withdrawn], previous, changed),
mergeCanonicalResourceDeltaSnapshot(
[withdrawn],
previous,
changed,
new Map([[raw.id, ['agent']]]),
),
]) {
expect(merged.agent?.disks).toBeUndefined();
expect(merged.agent?.stale).toBe(false);
// The compatibility mirror that host threshold rows read drops them too.
const mirror = (merged.platformData as { agent?: { disks?: unknown } } | undefined)?.agent;
expect(mirror?.disks).toBeUndefined();
}
const legacy = { ...raw, agent: { agentId: 'agent-in-vm' } } as Resource;
const [legacyKept] = mergeCanonicalResourceSnapshot([legacy], previous);
expect(legacyKept.agent?.disks).toEqual(raw.agent?.disks);
});
it('keeps explicit lock and deferral evidence on a new outcome, including false expected', () => {
const raw = createPveGuestRaw();
raw.proxmox = {
...raw.proxmox,
runtimeStatus: 'running',
guestAgentStatus: 'available',
};
const previous = seedDisplayRows([raw]);
const incoming = structuredClone(raw);
incoming.proxmox = {
...raw.proxmox,
guestAgentStatus: 'deferred',
diskStatusReason: 'agent-busy',
guestAgentExpected: false,
lock: 'migrate',
};
const [merged] = mergeCanonicalResourceDeltaSnapshot(
[incoming],
previous,
new Set([raw.id]),
new Map([[raw.id, ['proxmox']]]),
);
expect(merged.proxmox).toMatchObject({
guestAgentStatus: 'deferred',
diskStatusReason: 'agent-busy',
guestAgentExpected: false,
lock: 'migrate',
});
});
it('produces the same merged row as the full path for a metrics-only patch', () => {
const raw = createPveGuestRaw();
const display = seedDisplayRows([raw]);
const patched = applyMetricsTick(raw);
const changedIds = new Set(['vm-fast-1']);
const changedKeys = new Map([['vm-fast-1', [...METRICS_PATCH_KEYS]]]);
const fast = mergeCanonicalResourceDeltaSnapshot([patched], display, changedIds, changedKeys);
const slow = mergeCanonicalResourceDeltaSnapshot(
[structuredClone(patched)],
display,
changedIds,
);
expect(fast[0]).toEqual(slow[0]);
expect(fast[0]?.cpu?.current).toBe(55);
expect(fast[0]?.uptime).toBe(1002);
expect((fast[0]?.platformData as Record<string, unknown>)?.diskRead).toBe(9);
expect((fast[0]?.proxmox as Record<string, unknown>)?.uptime).toBe(1002);
});
it('keeps unpatched subtree identity on the fast path', () => {
const raw = createPveGuestRaw();
const display = seedDisplayRows([raw]);
const patched = applyMetricsTick(raw);
const changedKeys = new Map([['vm-fast-1', [...METRICS_PATCH_KEYS]]]);
const fast = mergeCanonicalResourceDeltaSnapshot(
[patched],
display,
new Set(['vm-fast-1']),
changedKeys,
);
expect(fast[0]).not.toBe(display[0]);
expect(fast[0]?.canonicalIdentity).toBe(display[0]?.canonicalIdentity);
expect(fast[0]?.disk).toBe(display[0]?.disk);
expect(fast[0]?.tags).toBe(display[0]?.tags);
// platformData is rebuilt for the patched leaves but its untouched nested
// records keep identity so downstream reconciles short-circuit on them.
expect((fast[0]?.platformData as Record<string, unknown>)?.proxmox).toBe(
(display[0]?.platformData as Record<string, unknown>)?.proxmox,
);
// The fast row must not adopt the raw row's subtrees: reconcile mutates
// adopted objects in place and would corrupt the raw delta baseline.
expect(fast[0]?.cpu).not.toBe(patched.cpu);
expect(fast[0]?.proxmox).not.toBe(patched.proxmox);
});
it('falls back to the full merge when a patch touches an ineligible key', () => {
const raw = createPveGuestRaw();
const display = seedDisplayRows([raw]);
const patched = {
...applyMetricsTick(raw),
tags: ['prod', 'new-tag'],
} as unknown as Resource;
const changedKeys = new Map([['vm-fast-1', [...METRICS_PATCH_KEYS, 'tags']]]);
expect(getFastResourceMergePatchKeys(changedKeys, 'vm-fast-1', display[0])).toBeNull();
const result = mergeCanonicalResourceDeltaSnapshot(
[patched],
display,
new Set(['vm-fast-1']),
changedKeys,
);
expect(result[0]?.tags).toEqual(['prod', 'new-tag']);
expect(result[0]?.cpu?.current).toBe(55);
});
it('falls back to the full merge for platformData leaves outside the metric mirrors', () => {
const display = seedDisplayRows([createPveGuestRaw()]);
const changedKeys = new Map([['vm-fast-1', ['cpu', 'platformData.instance']]]);
expect(getFastResourceMergePatchKeys(changedKeys, 'vm-fast-1', display[0])).toBeNull();
});
it('treats unknown change shapes and agent rows as ineligible', () => {
const display = seedDisplayRows([createPveGuestRaw()]);
expect(
getFastResourceMergePatchKeys(new Map([['vm-fast-1', null]]), 'vm-fast-1', display[0]),
).toBeNull();
expect(getFastResourceMergePatchKeys(undefined, 'vm-fast-1', display[0])).toBeNull();
expect(
getFastResourceMergePatchKeys(new Map([['vm-fast-1', ['cpu']]]), 'vm-fast-1', undefined),
).toBeNull();
const agent = { ...createPveGuestRaw(), type: 'agent' } as unknown as Resource;
expect(
getFastResourceMergePatchKeys(new Map([['vm-fast-1', ['cpu']]]), 'vm-fast-1', agent),
).toBeNull();
});
it('keeps the existing value when a fast key was deleted from the raw row', () => {
const raw = createPveGuestRaw();
const display = seedDisplayRows([raw]);
const patched = structuredClone(raw) as unknown as Record<string, unknown>;
delete patched.diskIO;
const changedKeys = new Map([['vm-fast-1', ['diskIO']]]);
const fast = mergeCanonicalResourceDeltaSnapshot(
[patched as unknown as Resource],
display,
new Set(['vm-fast-1']),
changedKeys,
);
const slow = mergeCanonicalResourceDeltaSnapshot(
[structuredClone(patched) as unknown as Resource],
display,
new Set(['vm-fast-1']),
);
expect(fast[0]?.diskIO).toEqual(display[0]?.diskIO);
expect(fast[0]).toEqual(slow[0]);
});
it('unions changed keys across ticks with null contamination', () => {
expect(unionResourceChangedKeys(['cpu'], ['memory', 'cpu'])).toEqual(['cpu', 'memory']);
expect(unionResourceChangedKeys(['cpu'], null)).toBeNull();
expect(unionResourceChangedKeys(null, ['cpu'])).toBeNull();
expect(unionResourceChangedKeys(undefined, ['cpu'])).toEqual(['cpu']);
expect(unionResourceChangedKeys(['cpu'], undefined)).toEqual(['cpu']);
});
it('builds per-key store patch ops for a fast row', () => {
const raw = createPveGuestRaw();
const display = seedDisplayRows([raw]);
const patched = applyMetricsTick(raw);
const changedKeys = new Map([['vm-fast-1', [...METRICS_PATCH_KEYS]]]);
const fast = mergeCanonicalResourceDeltaSnapshot(
[patched],
display,
new Set(['vm-fast-1']),
changedKeys,
);
const ops = buildFastResourceStorePatchOps(fast[0]!, [...METRICS_PATCH_KEYS]);
const byTarget = new Map(ops.map((op) => [op.leaf ? `${op.key}.${op.leaf}` : op.key, op]));
expect(byTarget.get('cpu')?.mode).toBe('reconcile');
expect(byTarget.get('uptime')).toEqual({ key: 'uptime', value: 1002, mode: 'set' });
expect(byTarget.get('platformData.diskRead')).toEqual({
key: 'platformData',
leaf: 'diskRead',
value: 9,
mode: 'set',
});
expect(byTarget.get('proxmox')?.mode).toBe('reconcile');
// No op may reference platformData wholesale; only leaf writes are allowed
// so unpatched platformData subtrees never get touched in the store.
expect(ops.every((op) => op.key !== 'platformData' || op.leaf !== undefined)).toBe(true);
});
});
it('replaces recovered availability without replacing independent metrics', () => {
const old = createNodeResource({
sources: ['proxmox-pve', 'availability'],
availability: {
targetId: 'check',
enabled: true,
available: false,
lastError: 'HTTP 503',
consecutiveFailures: 3,
},
});
const [previous] = mergeCanonicalResourceSnapshot([old], []);
const incoming = {
...old,
cpu: { current: 44 },
availability: { targetId: 'check', enabled: true, available: true, latencyMillis: 4 },
platformData: {
sources: ['proxmox-pve', 'availability'],
availability: { targetId: 'check', enabled: true, available: true, latencyMillis: 4 },
},
} as Resource;
const [merged] = mergeCanonicalResourceSnapshot([incoming], [previous]);
expect(merged.availability).toEqual(incoming.availability);
expect(merged.cpu).toEqual({ current: 44 });
expect(merged.memory).toEqual(previous.memory);
expect(merged.disk).toEqual(previous.disk);
});