@oneuptime/common 12.0.8 → 12.0.9

package/build/dist/Utils/Monitor/NetworkTopologyUtil.js

@@ -1,5 +1,29 @@
 import { normalizeMac } from "./EndpointAttachmentUtil";
 import { classifyDeviceRole, classifyEndpointRole, } from "./NetworkDeviceRoleUtil";
+const MATCH_KEY_KINDS_STRONGEST_FIRST = [
+    "name",
+    "serial",
+    "mac",
+    "shortHost",
+];
+/*
+ * The kinds strong enough to say "these two reports describe one peer".
+ *
+ * shortHost is excluded on purpose: `sw01.site-a` and `sw01.site-b` share
+ * one, and merging those would invent a device nobody owns. Against a
+ * MANAGED device the same key is safe, because a key two devices both
+ * claim is dropped from the index entirely rather than guessed at.
+ */
+const PEER_IDENTITY_KINDS = new Set([
+    "name",
+    "serial",
+    "mac",
+]);
+/*
+ * Hoisted so the literal is not the object of a member expression, which
+ * `wrap-regex` and Prettier cannot agree on.
+ */
+const IPV4_PATTERN = /^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/;
 // A device not seen within this window is treated as not currently up.
 const FRESH_WINDOW_MS = 15 * 60 * 1000;
 // Endpoint nodes rendered per graph; the slice is deterministic (by MAC).
@@ -7,9 +31,11 @@ const ENDPOINT_RENDER_CAP = 2000;
 export default class NetworkTopologyUtil {
     /*
      * Builds the topology graph from every device in a project. Nodes are the
-     * devices; LLDP and CDP neighbors that match another device (by sysName,
-     * hostname or name) become edges, and neighbors that match nothing become
-     * lightweight "unmanaged" nodes so links don't dead-end. Edges are
+     * devices; LLDP and CDP neighbors that match another device (by name,
+     * serial, interface MAC or FQDN short form — see MatchKeyKind) become
+     * edges, and neighbors that match nothing become lightweight "unmanaged"
+     * nodes so links don't dead-end. Reports that share an identity-grade
+     * alias are one unmanaged node, however many switches saw it. Edges are
      * undirected and deduplicated — a link reported from both ends, or by
      * both protocols, appears once with the union of what each report knew
      * (ports, protocols, per-end interface state). When `interfaces` rows are
@@ -19,15 +45,32 @@ export default class NetworkTopologyUtil {
      * "endpoint" node linked by an "fdb" edge (capped, deterministic by MAC);
      * the rest are dropped and counted in droppedEndpointCount.
      */
-    static buildTopology(devices, now, interfaces = [], endpoints = []) {
+    static buildTopology(devices, now, interfaces = [], endpoints = [], manualLinks = [], suppressedNodeKeys = new Set()) {
+        var _a;
         const nodes = [];
-        // Index managed devices by the identifiers neighbor entries reference.
+        /*
+         * Index managed devices by every identifier a neighbor entry could
+         * reference. A key TWO devices both claim is deleted rather than
+         * resolved: last-writer-wins would quietly draw the link to whichever
+         * device happened to be indexed second, and a wrong cable on a network
+         * map is worse than a missing one.
+         */
         const deviceByMatchKey = new Map();
+        const ambiguousMatchKeyIds = new Set();
         for (const device of devices) {
             for (const key of NetworkTopologyUtil.matchKeysForDevice(device)) {
-                deviceByMatchKey.set(key, device);
+                const keyId = NetworkTopologyUtil.matchKeyId(key);
+                const existing = deviceByMatchKey.get(keyId);
+                if (existing && existing.id !== device.id) {
+                    ambiguousMatchKeyIds.add(keyId);
+                    continue;
+                }
+                deviceByMatchKey.set(keyId, device);
             }
         }
+        for (const keyId of ambiguousMatchKeyIds) {
+            deviceByMatchKey.delete(keyId);
+        }
         // Index interface rows by (device, index) and by (device, name).
         const interfaceByDeviceAndIndex = new Map();
         const interfaceByDeviceAndName = new Map();
@@ -38,7 +81,10 @@ export default class NetworkTopologyUtil {
                 interfaceByDeviceAndName.set(`${row.networkDeviceId}::${nameKey}`, row);
             }
         }
+        // Kept aside so the diagnostics pass below can read it back per node.
+        const isNeighborDiscoveryEnabledById = new Map();
         for (const device of devices) {
+            isNeighborDiscoveryEnabledById.set(device.id, device.isNeighborDiscoveryEnabled);
             nodes.push({
                 id: device.id,
                 name: device.name,
@@ -60,142 +106,242 @@ export default class NetworkTopologyUtil {
                 deviceModel: device.deviceModel,
             });
         }
-        const unmanagedNodeById = new Map();
         const edgeByKey = new Map();
+        /*
+         * Resolve every neighbor report before drawing anything.
+         *
+         * A managed match is decidable from one report, but the IDENTITY of an
+         * unmanaged peer is not: the switch at one end may know its neighbor's
+         * sysName while the switch at the other end knows only its chassis MAC,
+         * and only the whole set of reports says those two describe one box.
+         */
+        const resolvedClaims = [];
         for (const device of devices) {
             for (const claim of NetworkTopologyUtil.neighborClaimsForDevice(device)) {
-                if (!claim.matchKey) {
+                const candidates = NetworkTopologyUtil.candidateKeysForClaim(claim);
+                if (candidates.length === 0) {
                     continue;
                 }
-                const matched = deviceByMatchKey.get(claim.matchKey);
-                let toNodeId;
+                // Candidates arrive strongest-first, so the first hit is the best one.
+                let matched = undefined;
+                for (const candidate of candidates) {
+                    matched = deviceByMatchKey.get(NetworkTopologyUtil.matchKeyId(candidate));
+                    if (matched) {
+                        break;
+                    }
+                }
                 if (matched) {
                     if (matched.id === device.id) {
                         // Self-referential neighbor entry; skip.
                         continue;
                     }
-                    toNodeId = matched.id;
-                }
-                else {
-                    toNodeId = `unmanaged:${claim.matchKey}`;
-                    const existingUnmanaged = unmanagedNodeById.get(toNodeId);
-                    if (!existingUnmanaged) {
-                        const unmanagedName = claim.displayName || "Unknown device";
-                        const unmanagedNode = {
-                            id: toNodeId,
-                            name: unmanagedName,
-                            isManaged: false,
-                            kind: "unmanaged",
-                            role: classifyDeviceRole({
-                                platform: claim.remotePlatform,
-                                name: unmanagedName,
-                            }),
-                            status: "unknown",
-                            deviceModel: claim.remotePlatform,
-                        };
-                        unmanagedNodeById.set(toNodeId, unmanagedNode);
-                        nodes.push(unmanagedNode);
-                    }
-                    else if (!existingUnmanaged.deviceModel && claim.remotePlatform) {
-                        /*
-                         * A later CDP claim may know the platform the first one didn't
-                         * — which is usually the only evidence a peer's role rests on,
-                         * so the role is re-derived rather than left at whatever the
-                         * name alone produced.
-                         */
-                        existingUnmanaged.deviceModel = claim.remotePlatform;
-                        existingUnmanaged.role = classifyDeviceRole({
-                            platform: claim.remotePlatform,
-                            name: existingUnmanaged.name,
-                        });
-                    }
-                }
-                // The reporting device's own end, enriched from its interface row.
-                let localEndpoint = undefined;
-                let localPortLabel = undefined;
-                if (claim.localInterfaceIndex !== undefined) {
-                    const localInterface = interfaceByDeviceAndIndex.get(`${device.id}::${claim.localInterfaceIndex}`);
-                    localEndpoint = {
-                        interfaceIndex: claim.localInterfaceIndex,
-                        interfaceName: localInterface === null || localInterface === void 0 ? void 0 : localInterface.name,
-                        isOperationallyUp: localInterface === null || localInterface === void 0 ? void 0 : localInterface.isOperationallyUp,
-                        isAdministrativelyUp: localInterface === null || localInterface === void 0 ? void 0 : localInterface.isAdministrativelyUp,
-                        utilizationPercent: localInterface === null || localInterface === void 0 ? void 0 : localInterface.utilizationPercent,
-                        inRateMbps: localInterface === null || localInterface === void 0 ? void 0 : localInterface.inRateMbps,
-                        outRateMbps: localInterface === null || localInterface === void 0 ? void 0 : localInterface.outRateMbps,
-                        errorsPerSecond: localInterface === null || localInterface === void 0 ? void 0 : localInterface.errorsPerSecond,
-                    };
-                    localPortLabel =
-                        (localInterface === null || localInterface === void 0 ? void 0 : localInterface.name) || `if${claim.localInterfaceIndex}`;
-                }
-                /*
-                 * The far end: best-effort — the advertised remote port id often
-                 * matches the remote device's interface name (e.g. "GigabitEthernet
-                 * 0/1"). Only attach data when it does; a bare port id string stays
-                 * in toPort.
-                 */
-                let remoteEndpoint = undefined;
-                if (matched && claim.remotePortId) {
-                    const remotePortKey = NetworkTopologyUtil.normalizeKey(claim.remotePortId);
-                    const remoteInterface = remotePortKey
-                        ? interfaceByDeviceAndName.get(`${matched.id}::${remotePortKey}`)
-                        : undefined;
-                    if (remoteInterface) {
-                        remoteEndpoint = {
-                            interfaceIndex: remoteInterface.interfaceIndex,
-                            interfaceName: remoteInterface.name,
-                            isOperationallyUp: remoteInterface.isOperationallyUp,
-                            isAdministrativelyUp: remoteInterface.isAdministrativelyUp,
-                            utilizationPercent: remoteInterface.utilizationPercent,
-                            inRateMbps: remoteInterface.inRateMbps,
-                            outRateMbps: remoteInterface.outRateMbps,
-                            errorsPerSecond: remoteInterface.errorsPerSecond,
-                        };
-                    }
-                }
-                // Undirected dedupe: canonicalize the endpoint pair.
-                const edgeKey = [device.id, toNodeId].sort().join("::");
-                const existing = edgeByKey.get(edgeKey);
-                if (!existing) {
-                    edgeByKey.set(edgeKey, {
-                        fromNodeId: device.id,
-                        toNodeId: toNodeId,
-                        fromPort: localPortLabel,
-                        toPort: claim.remotePortId,
-                        protocols: [claim.protocol],
-                        fromInterface: localEndpoint,
-                        toInterface: remoteEndpoint,
+                    resolvedClaims.push({
+                        device: device,
+                        claim: claim,
+                        matchedDeviceId: matched.id,
+                        peerAliases: [],
                     });
                     continue;
                 }
-                /*
-                 * Same link reported again — from the other end, or by the other
-                 * protocol. Merge instead of dropping so both ends keep the best
-                 * data anyone reported about them.
-                 */
-                if (existing.protocols &&
-                    !existing.protocols.includes(claim.protocol)) {
-                    existing.protocols.push(claim.protocol);
-                }
-                if (existing.fromNodeId === device.id) {
-                    existing.fromPort = existing.fromPort || localPortLabel;
-                    existing.toPort = existing.toPort || claim.remotePortId;
-                    existing.fromInterface = NetworkTopologyUtil.mergeEndpoints(existing.fromInterface, localEndpoint);
-                    existing.toInterface = NetworkTopologyUtil.mergeEndpoints(existing.toInterface, remoteEndpoint);
-                }
-                else {
-                    existing.toPort = existing.toPort || localPortLabel;
-                    existing.fromPort = existing.fromPort || claim.remotePortId;
-                    existing.toInterface = NetworkTopologyUtil.mergeEndpoints(existing.toInterface, localEndpoint);
-                    existing.fromInterface = NetworkTopologyUtil.mergeEndpoints(existing.fromInterface, remoteEndpoint);
+                resolvedClaims.push({
+                    device: device,
+                    claim: claim,
+                    matchedDeviceId: undefined,
+                    peerAliases: candidates.filter((candidate) => {
+                        return PEER_IDENTITY_KINDS.has(candidate.kind);
+                    }),
+                });
+            }
+        }
+        const peerNodeIdByClaim = NetworkTopologyUtil.buildUnmanagedPeerNodes(resolvedClaims, nodes);
+        for (const resolved of resolvedClaims) {
+            const device = resolved.device;
+            const claim = resolved.claim;
+            const matchedId = resolved.matchedDeviceId;
+            const toNodeId = matchedId || peerNodeIdByClaim.get(resolved);
+            if (!toNodeId) {
+                continue;
+            }
+            // The reporting device's own end, enriched from its interface row.
+            let localEndpoint = undefined;
+            let localPortLabel = undefined;
+            if (claim.localInterfaceIndex !== undefined) {
+                const localInterface = interfaceByDeviceAndIndex.get(`${device.id}::${claim.localInterfaceIndex}`);
+                localEndpoint = {
+                    interfaceIndex: claim.localInterfaceIndex,
+                    interfaceName: localInterface === null || localInterface === void 0 ? void 0 : localInterface.name,
+                    isOperationallyUp: localInterface === null || localInterface === void 0 ? void 0 : localInterface.isOperationallyUp,
+                    isAdministrativelyUp: localInterface === null || localInterface === void 0 ? void 0 : localInterface.isAdministrativelyUp,
+                    utilizationPercent: localInterface === null || localInterface === void 0 ? void 0 : localInterface.utilizationPercent,
+                    inRateMbps: localInterface === null || localInterface === void 0 ? void 0 : localInterface.inRateMbps,
+                    outRateMbps: localInterface === null || localInterface === void 0 ? void 0 : localInterface.outRateMbps,
+                    errorsPerSecond: localInterface === null || localInterface === void 0 ? void 0 : localInterface.errorsPerSecond,
+                };
+                localPortLabel =
+                    (localInterface === null || localInterface === void 0 ? void 0 : localInterface.name) || `if${claim.localInterfaceIndex}`;
+            }
+            /*
+             * The far end: best-effort — the advertised remote port id often
+             * matches the remote device's interface name (e.g. "GigabitEthernet
+             * 0/1"). Only attach data when it does; a bare port id string stays
+             * in toPort.
+             */
+            let remoteEndpoint = undefined;
+            if (matchedId && claim.remotePortId) {
+                const remotePortKey = NetworkTopologyUtil.normalizeKey(claim.remotePortId);
+                const remoteInterface = remotePortKey
+                    ? interfaceByDeviceAndName.get(`${matchedId}::${remotePortKey}`)
+                    : undefined;
+                if (remoteInterface) {
+                    remoteEndpoint = {
+                        interfaceIndex: remoteInterface.interfaceIndex,
+                        interfaceName: remoteInterface.name,
+                        isOperationallyUp: remoteInterface.isOperationallyUp,
+                        isAdministrativelyUp: remoteInterface.isAdministrativelyUp,
+                        utilizationPercent: remoteInterface.utilizationPercent,
+                        inRateMbps: remoteInterface.inRateMbps,
+                        outRateMbps: remoteInterface.outRateMbps,
+                        errorsPerSecond: remoteInterface.errorsPerSecond,
+                    };
                 }
             }
+            // Undirected dedupe: canonicalize the endpoint pair.
+            const edgeKey = [device.id, toNodeId].sort().join("::");
+            const existing = edgeByKey.get(edgeKey);
+            if (!existing) {
+                edgeByKey.set(edgeKey, {
+                    fromNodeId: device.id,
+                    toNodeId: toNodeId,
+                    fromPort: localPortLabel,
+                    toPort: claim.remotePortId,
+                    protocols: [claim.protocol],
+                    fromInterface: localEndpoint,
+                    toInterface: remoteEndpoint,
+                });
+                continue;
+            }
+            /*
+             * Same link reported again — from the other end, or by the other
+             * protocol. Merge instead of dropping so both ends keep the best
+             * data anyone reported about them.
+             */
+            if (existing.protocols && !existing.protocols.includes(claim.protocol)) {
+                existing.protocols.push(claim.protocol);
+            }
+            if (existing.fromNodeId === device.id) {
+                existing.fromPort = existing.fromPort || localPortLabel;
+                existing.toPort = existing.toPort || claim.remotePortId;
+                existing.fromInterface = NetworkTopologyUtil.mergeEndpoints(existing.fromInterface, localEndpoint);
+                existing.toInterface = NetworkTopologyUtil.mergeEndpoints(existing.toInterface, remoteEndpoint);
+            }
+            else {
+                existing.toPort = existing.toPort || localPortLabel;
+                existing.fromPort = existing.fromPort || claim.remotePortId;
+                existing.toInterface = NetworkTopologyUtil.mergeEndpoints(existing.toInterface, localEndpoint);
+                existing.fromInterface = NetworkTopologyUtil.mergeEndpoints(existing.fromInterface, remoteEndpoint);
+            }
         }
-        const edges = Array.from(edgeByKey.values());
-        // --- Endpoint nodes + fdb edges ---
         const deviceNodeIds = new Set(devices.map((device) => {
             return device.id;
         }));
+        /*
+         * --- Operator-declared links ---
+         *
+         * Merged into the SAME edge map the discovery protocols write to, so a
+         * cable somebody drew by hand and the same cable LLDP later reports are
+         * one line carrying both protocols — not two lines between one pair of
+         * boxes, which is exactly the duplicate an operator would read as a
+         * second physical link.
+         *
+         * Ends outside this graph are skipped rather than drawn: a link to a
+         * device in another site (or one since archived) has nothing to attach
+         * to here.
+         */
+        for (const link of manualLinks) {
+            if (!deviceNodeIds.has(link.fromDeviceId) ||
+                !deviceNodeIds.has(link.toDeviceId) ||
+                link.fromDeviceId === link.toDeviceId) {
+                continue;
+            }
+            const edgeKey = [link.fromDeviceId, link.toDeviceId]
+                .sort()
+                .join("::");
+            const existing = edgeByKey.get(edgeKey);
+            if (!existing) {
+                edgeByKey.set(edgeKey, {
+                    fromNodeId: link.fromDeviceId,
+                    toNodeId: link.toDeviceId,
+                    fromPort: link.fromPortName,
+                    toPort: link.toPortName,
+                    protocols: ["manual"],
+                    monitorState: link.monitorStatus,
+                    name: link.name,
+                });
+                continue;
+            }
+            if (existing.protocols && !existing.protocols.includes("manual")) {
+                existing.protocols.push("manual");
+            }
+            /*
+             * Discovered data wins on the shared fields — it is measured, and the
+             * hand-typed port is a best recollection. The operator's name and the
+             * monitor's verdict have no discovered counterpart, so they always
+             * apply.
+             */
+            if (existing.fromNodeId === link.fromDeviceId) {
+                existing.fromPort = existing.fromPort || link.fromPortName;
+                existing.toPort = existing.toPort || link.toPortName;
+            }
+            else {
+                existing.toPort = existing.toPort || link.fromPortName;
+                existing.fromPort = existing.fromPort || link.toPortName;
+            }
+            existing.name = existing.name || link.name;
+            existing.monitorState = (_a = existing.monitorState) !== null && _a !== void 0 ? _a : link.monitorStatus;
+        }
+        const edges = Array.from(edgeByKey.values());
+        /*
+         * --- Why a device has no links ---
+         *
+         * Attached to every managed node, so the detail panel can answer "the
+         * router is not linked to anything" with a cause instead of a shrug.
+         * Built from the claims that were just resolved: the unmatched ones are
+         * the actionable evidence — a renamed peer, a device nobody has added
+         * yet — and they are otherwise thrown away here.
+         */
+        const reportedNeighborCountByDeviceId = new Map();
+        const unmatchedIdentifiersByDeviceId = new Map();
+        for (const resolved of resolvedClaims) {
+            const deviceId = resolved.device.id;
+            reportedNeighborCountByDeviceId.set(deviceId, (reportedNeighborCountByDeviceId.get(deviceId) || 0) + 1);
+            if (resolved.matchedDeviceId) {
+                continue;
+            }
+            const identifier = resolved.claim.displayName || resolved.claim.identifiers[0];
+            if (!identifier) {
+                continue;
+            }
+            const bucket = unmatchedIdentifiersByDeviceId.get(deviceId);
+            if (bucket) {
+                if (!bucket.includes(identifier)) {
+                    bucket.push(identifier);
+                }
+            }
+            else {
+                unmatchedIdentifiersByDeviceId.set(deviceId, [identifier]);
+            }
+        }
+        for (const node of nodes) {
+            if (node.kind !== "device") {
+                continue;
+            }
+            node.diagnostics = {
+                isNeighborDiscoveryEnabled: isNeighborDiscoveryEnabledById.get(node.id),
+                reportedNeighborCount: reportedNeighborCountByDeviceId.get(node.id) || 0,
+                unmatchedNeighborIdentifiers: unmatchedIdentifiersByDeviceId.get(node.id) || [],
+            };
+        }
+        // --- Endpoint nodes + fdb edges ---
         /*
          * Deterministic render order: by normalized MAC, then id, so the capped
          * slice is stable across rebuilds regardless of query order.
@@ -273,11 +419,39 @@ export default class NetworkTopologyUtil {
                     : undefined,
             });
         }
+        /*
+         * --- Hidden nodes ---
+         *
+         * Applied last, on the finished graph, so a suppressed node cannot
+         * change how anything else resolved. Hiding a switch must not silently
+         * re-route its neighbours' links or turn its peers into strangers — it
+         * takes the box off the map and nothing more. Its edges go with it,
+         * because a line to a node that is not drawn is a line into empty space.
+         */
+        if (suppressedNodeKeys.size === 0) {
+            return {
+                nodes,
+                edges,
+                droppedEndpointCount,
+                endpointsTruncated,
+                suppressedNodeCount: 0,
+            };
+        }
+        const visibleNodes = nodes.filter((node) => {
+            return !suppressedNodeKeys.has(node.id);
+        });
+        const visibleNodeIds = new Set(visibleNodes.map((node) => {
+            return node.id;
+        }));
         return {
-            nodes,
-            edges,
+            nodes: visibleNodes,
+            edges: edges.filter((edge) => {
+                return (visibleNodeIds.has(edge.fromNodeId) &&
+                    visibleNodeIds.has(edge.toNodeId));
+            }),
             droppedEndpointCount,
             endpointsTruncated,
+            suppressedNodeCount: nodes.length - visibleNodes.length,
         };
     }
     /*
@@ -288,11 +462,25 @@ export default class NetworkTopologyUtil {
     static neighborClaimsForDevice(device) {
         const claims = [];
         for (const neighbor of device.lldpNeighbors || []) {
+            /*
+             * Both identifiers are carried, not just the first non-empty one.
+             * The chassis id used to be a fallback that only applied when the
+             * peer advertised no sysName; it is in fact an identifier in its own
+             * right — a MAC or a serial — and the device it names is very often
+             * one we already manage.
+             */
+            const identifiers = [];
+            if (neighbor.remoteSysName) {
+                identifiers.push(neighbor.remoteSysName);
+            }
+            if (neighbor.remoteChassisId) {
+                identifiers.push(neighbor.remoteChassisId);
+            }
             claims.push({
                 protocol: "lldp",
-                matchKey: NetworkTopologyUtil.normalizeKey(neighbor.remoteSysName) ||
-                    NetworkTopologyUtil.normalizeKey(neighbor.remoteChassisId),
+                identifiers: identifiers,
                 displayName: neighbor.remoteSysName || neighbor.remoteChassisId,
+                hasAdvertisedName: Boolean(neighbor.remoteSysName),
                 localInterfaceIndex: neighbor.localInterfaceIndex,
                 remotePortId: neighbor.remotePortId,
                 remotePlatform: undefined,
@@ -301,8 +489,9 @@ export default class NetworkTopologyUtil {
         for (const neighbor of device.cdpNeighbors || []) {
             claims.push({
                 protocol: "cdp",
-                matchKey: NetworkTopologyUtil.normalizeKey(neighbor.remoteDeviceId),
+                identifiers: neighbor.remoteDeviceId ? [neighbor.remoteDeviceId] : [],
                 displayName: neighbor.remoteDeviceId,
+                hasAdvertisedName: Boolean(neighbor.remoteDeviceId),
                 localInterfaceIndex: neighbor.localInterfaceIndex,
                 remotePortId: neighbor.remotePortId,
                 remotePlatform: neighbor.remotePlatform,
@@ -310,6 +499,84 @@ export default class NetworkTopologyUtil {
         }
         return claims;
     }
+    /*
+     * Every key a claim could be resolved by, strongest kind first and, within
+     * a kind, strongest SOURCE first (an advertised sysName ahead of a chassis
+     * id). Sorting by kind before source is deliberate: a MAC read off a
+     * chassis id identifies a box far more precisely than the first label of
+     * somebody's FQDN, whichever field it arrived in.
+     */
+    static candidateKeysForClaim(claim) {
+        const byKind = new Map();
+        const seen = new Set();
+        for (const identifier of claim.identifiers) {
+            for (const key of NetworkTopologyUtil.candidateKeysForIdentifier(identifier)) {
+                const keyId = NetworkTopologyUtil.matchKeyId(key);
+                if (seen.has(keyId)) {
+                    continue;
+                }
+                seen.add(keyId);
+                const bucket = byKind.get(key.kind);
+                if (bucket) {
+                    bucket.push(key);
+                }
+                else {
+                    byKind.set(key.kind, [key]);
+                }
+            }
+        }
+        const ordered = [];
+        for (const kind of MATCH_KEY_KINDS_STRONGEST_FIRST) {
+            ordered.push(...(byKind.get(kind) || []));
+        }
+        return ordered;
+    }
+    /*
+     * One identifier string, offered as every kind it could be.
+     *
+     * A chassis id is just bytes on the wire — nothing in the protocol says
+     * whether it is a name, a serial or a MAC — so it is offered as all of
+     * them, and only a key some device actually published can match.
+     */
+    static candidateKeysForIdentifier(raw) {
+        const normalized = NetworkTopologyUtil.normalizeKey(raw);
+        if (!normalized) {
+            return [];
+        }
+        const keys = [
+            { kind: "name", value: normalized },
+            { kind: "serial", value: normalized },
+        ];
+        const mac = normalizeMac(normalized);
+        if (mac) {
+            keys.push({ kind: "mac", value: mac });
+        }
+        const shortHost = NetworkTopologyUtil.shortHostKey(normalized);
+        if (shortHost) {
+            keys.push({ kind: "shortHost", value: shortHost });
+        }
+        return keys;
+    }
+    /*
+     * The first label of a hostname, or undefined when taking one would be
+     * nonsense. An IPv4 literal would shorten to "10" and a MAC to its first
+     * octet pair — both of which would collide half the estate into one node,
+     * so both are refused outright.
+     */
+    static shortHostKey(normalized) {
+        if (IPV4_PATTERN.test(normalized) || normalizeMac(normalized)) {
+            return undefined;
+        }
+        const firstLabel = normalized.split(".")[0] || "";
+        return firstLabel.length > 0 ? firstLabel : undefined;
+    }
+    static matchKeyId(key) {
+        /*
+         * A NUL separator, because every kind shares one namespace and a
+         * hostname may legitimately contain a colon-ish character.
+         */
+        return `${key.kind}\u0000${key.value}`;
+    }
     // Existing fields win; the incoming report only fills what's missing.
     static mergeEndpoints(existing, incoming) {
         var _a, _b, _c, _d, _e, _f, _g, _h;
@@ -330,21 +597,251 @@ export default class NetworkTopologyUtil {
             errorsPerSecond: (_h = existing.errorsPerSecond) !== null && _h !== void 0 ? _h : incoming.errorsPerSecond,
         };
     }
+    /*
+     * Every key this device answers to.
+     *
+     * Unlike a claim's candidates, these are NOT speculative: we know which
+     * column each value came from, so a serial is only ever registered as a
+     * serial. That asymmetry is the whole point — a claim may offer its
+     * chassis id as a name, a serial and a MAC, but only the kind a device
+     * actually published can be the one that matches.
+     */
     static matchKeysForDevice(device) {
-        /*
-         * sysName / hostname / name — the identifiers LLDP remoteSysName and
-         * CDP remoteDeviceId advertise. Order matters only across devices
-         * (last writer wins on a collision), not within one device.
-         */
         const keys = [];
+        const seen = new Set();
+        const add = (key) => {
+            const keyId = NetworkTopologyUtil.matchKeyId(key);
+            if (seen.has(keyId)) {
+                return;
+            }
+            seen.add(keyId);
+            keys.push(key);
+        };
+        // sysName / hostname / name — what both protocols advertise.
         for (const candidate of [device.sysName, device.hostname, device.name]) {
-            const key = NetworkTopologyUtil.normalizeKey(candidate);
-            if (key && !keys.includes(key)) {
-                keys.push(key);
+            const normalized = NetworkTopologyUtil.normalizeKey(candidate);
+            if (!normalized) {
+                continue;
+            }
+            add({ kind: "name", value: normalized });
+            /*
+             * The short form is registered for EVERY name, dotted or not, so the
+             * two halves of the comparison meet: an FQDN on the wire has to be
+             * able to find a bare sysName here, and a bare name on the wire has
+             * to be able to find an FQDN.
+             */
+            const shortHost = NetworkTopologyUtil.shortHostKey(normalized);
+            if (shortHost) {
+                add({ kind: "shortHost", value: shortHost });
+            }
+        }
+        const serial = NetworkTopologyUtil.normalizeKey(device.serialNumber);
+        if (serial) {
+            add({ kind: "serial", value: serial });
+        }
+        for (const rawMac of device.macAddresses || []) {
+            const mac = normalizeMac(rawMac);
+            if (mac) {
+                add({ kind: "mac", value: mac });
             }
         }
         return keys;
     }
+    /*
+     * Turns the unmatched claims into unmanaged peer NODES, one per box.
+     *
+     * Reports are merged when they share any identity-grade alias, so the
+     * neighbor one switch knows as "ap-lobby" and another knows only by its
+     * chassis MAC lands on a single node instead of the two strangers the map
+     * used to draw. Appends the nodes it mints to `nodes` and returns the node
+     * id each claim should draw its edge to.
+     */
+    static buildUnmanagedPeerNodes(resolvedClaims, nodes) {
+        const unmanagedClaims = resolvedClaims.filter((resolved) => {
+            return !resolved.matchedDeviceId && resolved.peerAliases.length > 0;
+        });
+        const rootByAliasId = NetworkTopologyUtil.groupPeerAliases(unmanagedClaims);
+        // Claims per peer, in first-encounter order so the output is stable.
+        const claimsByRoot = new Map();
+        for (const resolved of unmanagedClaims) {
+            const root = rootByAliasId.get(NetworkTopologyUtil.matchKeyId(resolved.peerAliases[0]));
+            if (!root) {
+                continue;
+            }
+            const bucket = claimsByRoot.get(root);
+            if (bucket) {
+                bucket.push(resolved);
+            }
+            else {
+                claimsByRoot.set(root, [resolved]);
+            }
+        }
+        const nodeIdByClaim = new Map();
+        const usedNodeIds = new Set();
+        for (const groupClaims of claimsByRoot.values()) {
+            /*
+             * The nicest label anyone reported: a name the peer advertises about
+             * itself beats a bare chassis id, whichever report arrived first.
+             */
+            let displayName = undefined;
+            let platform = undefined;
+            for (const resolved of groupClaims) {
+                if (!displayName && resolved.claim.hasAdvertisedName) {
+                    displayName = resolved.claim.displayName;
+                }
+                if (!platform && resolved.claim.remotePlatform) {
+                    platform = resolved.claim.remotePlatform;
+                }
+            }
+            if (!displayName) {
+                for (const resolved of groupClaims) {
+                    if (resolved.claim.displayName) {
+                        displayName = resolved.claim.displayName;
+                        break;
+                    }
+                }
+            }
+            /*
+             * The id keeps its historic `unmanaged:<value>` shape — it is the key
+             * saved arrangements are stored under, so changing it would scatter
+             * every pinned peer on the map. It is named after the label wherever
+             * that label is one of the peer's own aliases, so merging a report
+             * that knew a sysName with one that knew only a chassis MAC still
+             * produces `unmanaged:ap-lobby` rather than an id made of hex.
+             */
+            const nodeId = NetworkTopologyUtil.uniqueNodeId(`unmanaged:${NetworkTopologyUtil.canonicalPeerValue(groupClaims, displayName)}`, usedNodeIds);
+            usedNodeIds.add(nodeId);
+            const unmanagedName = displayName || "Unknown device";
+            nodes.push({
+                id: nodeId,
+                name: unmanagedName,
+                isManaged: false,
+                kind: "unmanaged",
+                /*
+                 * Classified from the whole group rather than from whichever
+                 * report happened to be first: the platform string is usually the
+                 * only real evidence about a peer, and it may well arrive on the
+                 * second report of it.
+                 */
+                role: classifyDeviceRole({
+                    platform: platform,
+                    name: unmanagedName,
+                }),
+                status: "unknown",
+                deviceModel: platform,
+            });
+            for (const resolved of groupClaims) {
+                nodeIdByClaim.set(resolved, nodeId);
+            }
+        }
+        return nodeIdByClaim;
+    }
+    /*
+     * The alias a merged peer is named after.
+     *
+     * The chosen label wins whenever it is genuinely one of the peer's own
+     * aliases; otherwise the strongest kind present decides, and within it
+     * the lexicographically smallest value, so the id never depends on which
+     * switch happened to be polled first.
+     */
+    static canonicalPeerValue(groupClaims, displayName) {
+        const valuesByKind = new Map();
+        for (const resolved of groupClaims) {
+            for (const alias of resolved.peerAliases) {
+                const bucket = valuesByKind.get(alias.kind);
+                if (bucket) {
+                    if (!bucket.includes(alias.value)) {
+                        bucket.push(alias.value);
+                    }
+                }
+                else {
+                    valuesByKind.set(alias.kind, [alias.value]);
+                }
+            }
+        }
+        const preferred = NetworkTopologyUtil.normalizeKey(displayName);
+        if (preferred && (valuesByKind.get("name") || []).includes(preferred)) {
+            return preferred;
+        }
+        for (const kind of MATCH_KEY_KINDS_STRONGEST_FIRST) {
+            const values = valuesByKind.get(kind);
+            if (values && values.length > 0) {
+                return [...values].sort()[0];
+            }
+        }
+        return "unknown-peer";
+    }
+    /*
+     * Two peers could in principle canonicalize to the same string (one by
+     * name, one by serial). Suffixing rather than merging keeps them the
+     * distinct boxes they are.
+     */
+    static uniqueNodeId(preferred, used) {
+        if (!used.has(preferred)) {
+            return preferred;
+        }
+        let suffix = 2;
+        while (used.has(`${preferred}#${suffix}`)) {
+            suffix++;
+        }
+        return `${preferred}#${suffix}`;
+    }
+    /*
+     * Union-find over peer aliases: two reports that share ANY identity-grade
+     * alias describe one box. Returns the representative alias id for every
+     * alias seen.
+     */
+    static groupPeerAliases(unmanagedClaims) {
+        const parent = new Map();
+        const find = (key) => {
+            let root = key;
+            let next = parent.get(root);
+            while (next !== undefined && next !== root) {
+                root = next;
+                next = parent.get(root);
+            }
+            // Path compression, so repeated lookups stay flat.
+            let cursor = key;
+            while (cursor !== root) {
+                const following = parent.get(cursor) || root;
+                parent.set(cursor, root);
+                cursor = following;
+            }
+            return root;
+        };
+        const union = (a, b) => {
+            const rootA = find(a);
+            const rootB = find(b);
+            if (rootA === rootB) {
+                return;
+            }
+            // Lexicographic tie-break, so the result ignores input order.
+            if (rootA < rootB) {
+                parent.set(rootB, rootA);
+            }
+            else {
+                parent.set(rootA, rootB);
+            }
+        };
+        for (const resolved of unmanagedClaims) {
+            const aliasIds = resolved.peerAliases.map((alias) => {
+                return NetworkTopologyUtil.matchKeyId(alias);
+            });
+            for (const aliasId of aliasIds) {
+                if (!parent.has(aliasId)) {
+                    parent.set(aliasId, aliasId);
+                }
+            }
+            for (let index = 1; index < aliasIds.length; index++) {
+                union(aliasIds[0], aliasIds[index]);
+            }
+        }
+        const rootByAliasId = new Map();
+        for (const aliasId of parent.keys()) {
+            rootByAliasId.set(aliasId, find(aliasId));
+        }
+        return rootByAliasId;
+    }
     static normalizeKey(value) {
         if (!value) {
             return undefined;
@@ -352,7 +849,16 @@ export default class NetworkTopologyUtil {
         const trimmed = value.trim().toLowerCase();
         return trimmed.length > 0 ? trimmed : undefined;
     }
+    /*
+     * A stamped monitor status beats SNMP freshness, and freshness is the
+     * fallback — the same precedence SiteStatusRollupUtil already applies when
+     * it rolls devices up into a site, so a device cannot read "up" on the map
+     * and "down" on the site card above it.
+     */
     static deviceStatus(device, now) {
+        if (device.monitorStatus) {
+            return device.monitorStatus;
+        }
         return NetworkTopologyUtil.statusFromLastSeen(device.lastSeenAt, now);
     }
     // The shared freshness rule: seen within the window = up, stale = down.