@matter-server/ws-controller 0.6.8 → 0.7.0-alpha.0-20260516-8ee9631

package/src/controller/ControllerCommandHandler.ts

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import type { WebRtcCallbackData } from "@matter-server/ws-client";
 import {
     Abort,
     AsyncObservable,
@@ -21,7 +22,6 @@ import {
     Observable,
     Seconds,
     ServerAddress,
-    ServerAddressUdp,
     SoftwareUpdateInfo,
     SoftwareUpdateManager,
     Time,
@@ -37,6 +37,8 @@ import {
     GeneralCommissioning,
     OperationalCredentials,
 } from "@matter/main/clusters";
+import { WebRtcTransportDefinitions } from "@matter/main/clusters/web-rtc-transport-definitions";
+import { WebRtcTransportProvider } from "@matter/main/clusters/web-rtc-transport-provider";
 import {
     DecodedAttributeReportValue,
     DecodedEventReportValue,
@@ -44,7 +46,6 @@ import {
     PeerAddress,
     Read,
     Specifier,
-    SupportedTransportsSchema,
     PeerSet,
 } from "@matter/main/protocol";
 import {
@@ -61,6 +62,8 @@ import {
     StatusResponseError,
     VendorId,
 } from "@matter/main/types";
+import { Endpoint } from "@matter/node";
+import { CameraControllerDevice } from "@matter/node/devices/camera-controller";
 import { CommissioningController, NodeCommissioningOptions } from "@project-chip/matter.js";
 import { NodeStates } from "@project-chip/matter.js/device";
 import { ClusterMap, ClusterMapEntry, GlobalAttributes } from "../model/ModelMapper.js";
@@ -98,12 +101,14 @@ import {
 } from "../types/WebSocketMessageTypes.js";
 import { formatNodeId } from "../util/formatNodeId.js";
 import { pingIp } from "../util/network.js";
+import { WebRtcTransportRequestorServer } from "./behaviors/WebRtcTransportRequestorServer.js";
 import { CustomClusterPoller } from "./CustomClusterPoller.js";
 import { Nodes } from "./Nodes.js";
+import { attachWebRtcCallbackBridge } from "./WebRtcCallbackBridge.js";
 
 const logger = Logger.get("ControllerCommandHandler");
 
-/** After this duration in Reconnecting state, declare the node unavailable */
+/** Grace period after leaving Connected before a node is declared unavailable. */
 const RECONNECT_TIMEOUT = Minutes(3);
 
 /**
@@ -173,6 +178,7 @@ export class ControllerCommandHandler {
         nodeDecommissioned: new Observable<[nodeId: NodeId]>(),
         nodeEndpointAdded: new Observable<[nodeId: NodeId, endpointId: EndpointNumber]>(),
         nodeEndpointRemoved: new Observable<[nodeId: NodeId, endpointId: EndpointNumber]>(),
+        webRtcCallback: new Observable<[WebRtcCallbackData]>(),
     };
     #peers?: PeerSet;
 
@@ -240,6 +246,7 @@ export class ControllerCommandHandler {
         }
 
         await this.events.started.emit();
+        await this.#setupWebRtcCallbackBridge();
     }
 
     /**
@@ -284,6 +291,88 @@ export class ControllerCommandHandler {
         }
     }
 
+    async #setupWebRtcCallbackBridge() {
+        try {
+            await this.#cameraControllerEndpoint().act(agent => {
+                attachWebRtcCallbackBridge(agent.get(WebRtcTransportRequestorServer).events, data =>
+                    this.events.webRtcCallback.emit(data),
+                );
+            });
+            logger.info("WebRTC callback bridge wired");
+        } catch (error) {
+            logger.warn("Failed to setup WebRTC callback bridge:", error);
+        }
+    }
+
+    #cameraControllerEndpoint(): Endpoint<typeof CameraControllerDevice> {
+        return this.#controller.node.endpoints.for("camera-controller") as Endpoint<typeof CameraControllerDevice>;
+    }
+
+    /** `originatingEndpointId` is server-injected; any client-supplied value in `payload` is overwritten. */
+    async sendWebRtcProviderCommand(args: {
+        nodeId: NodeId;
+        endpointId: EndpointNumber;
+        commandName: "ProvideOffer" | "SolicitOffer";
+        payload: Record<string, unknown>;
+    }): Promise<WebRtcTransportProvider.ProvideOfferResponse | WebRtcTransportProvider.SolicitOfferResponse> {
+        const { nodeId, endpointId, commandName, payload } = args;
+
+        if (commandName !== "ProvideOffer" && commandName !== "SolicitOffer") {
+            throw ServerError.invalidArguments(
+                `Unsupported WebRTC provider command "${commandName}"; expected ProvideOffer or SolicitOffer`,
+            );
+        }
+
+        const requestorEndpoint = this.#cameraControllerEndpoint();
+        const originatingEndpointId = EndpointNumber(requestorEndpoint.number);
+        const fabricIndex = this.#controller.fabric.fabricIndex;
+
+        const node = this.#nodes.get(nodeId);
+
+        const fields: Record<string, unknown> = {
+            ...payload,
+            originatingEndpointId,
+        };
+        const command = commandName === "ProvideOffer" ? "provideOffer" : "solicitOffer";
+
+        const response = (await this.#invokeCommand(node.node, {
+            endpoint: endpointId,
+            cluster: WebRtcTransportProvider,
+            command,
+            fields,
+        })) as WebRtcTransportProvider.ProvideOfferResponse | WebRtcTransportProvider.SolicitOfferResponse | undefined;
+
+        if (response === undefined || typeof response.webRtcSessionId !== "number") {
+            throw ServerError.sdkStackError(
+                `${commandName} did not return a WebRTCSessionID for node ${this.formatNode(nodeId)}`,
+            );
+        }
+
+        const streamUsage = payload.streamUsage as WebRtcTransportDefinitions.WebRtcSession["streamUsage"];
+        const metadataEnabled = (payload.metadataEnabled as boolean | undefined) ?? false;
+        const videoStreams = response.videoStreamId != null ? [response.videoStreamId] : new Array<number>();
+        const audioStreams = response.audioStreamId != null ? [response.audioStreamId] : new Array<number>();
+        const session: WebRtcTransportDefinitions.WebRtcSession = {
+            id: response.webRtcSessionId,
+            peerNodeId: nodeId,
+            peerEndpointId: endpointId,
+            streamUsage,
+            metadataEnabled,
+            videoStreams,
+            audioStreams,
+            fabricIndex,
+        };
+
+        logger.info(
+            `upserting WebRTC session id=${session.id} peerNodeId=${nodeId} peerEndpointId=${endpointId} fabricIndex=${fabricIndex} streamUsage=${streamUsage} originatingEndpointId=${originatingEndpointId}`,
+        );
+        await requestorEndpoint.act(agent => {
+            agent.get(WebRtcTransportRequestorServer).upsertSession(session);
+        });
+
+        return response;
+    }
+
     async close() {
         for (const timer of this.#reconnectTimers.values()) {
             timer.stop();
@@ -300,16 +389,12 @@ export class ControllerCommandHandler {
         const node = await this.#controller.getNode(nodeId);
         const attributeCache = this.#nodes.attributeCache;
 
-        // Wire all Events to the Event emitters
-        // Track if a BasicInformation or BridgedDeviceBasicInformation attribute changed during
-        // a subscription batch. When the batch ends (connectionAlive), emit a full node_updated.
+        // Defer the full node_updated until the subscription batch ends (connectionAlive)
+        // so consumers see one update per batch rather than one per attribute.
         let basicInfoChangedInBatch = false;
         node.events.attributeChanged.on(data => {
-            // Update the attribute cache with the new value in WebSocket format
             attributeCache.updateAttribute(nodeId, data);
-            // Then emit the event for listeners
             this.events.attributeChanged.emit(nodeId, data);
-            // Mark for full node_updated if any BasicInformation cluster attribute changed
             if (FULL_UPDATE_CLUSTER_IDS.has(data.path.clusterId)) {
                 basicInfoChangedInBatch = true;
             }
@@ -323,7 +408,6 @@ export class ControllerCommandHandler {
         });
         node.events.eventTriggered.on(data => this.events.eventChanged.emit(nodeId, data));
         node.events.stateChanged.on(state => {
-            // Only refresh cache on Connected state
             if (state === NodeStates.Connected) {
                 attributeCache.update(node);
                 const attributes = attributeCache.get(nodeId);
@@ -332,35 +416,35 @@ export class ControllerCommandHandler {
                 }
             }
 
-            // Manage reconnect timer
-            if (state === NodeStates.Reconnecting) {
-                if (!this.#reconnectTimers.has(nodeId)) {
-                    const timer = Time.getTimer(`reconnect-timeout-${nodeId}`, RECONNECT_TIMEOUT, () => {
-                        this.#reconnectTimers.delete(nodeId);
-                        if (this.#nodes.forceUnavailable(nodeId)) {
-                            logger.info(
-                                `Node ${this.formatNode(nodeId)} still reconnecting after timeout, marking unavailable`,
-                            );
-                            this.events.nodeAvailabilityChanged.emit(nodeId, false);
-                        }
-                    });
-                    timer.utility = true;
-                    timer.start();
-                    this.#reconnectTimers.set(nodeId, timer);
-                }
-            } else {
-                // Any non-Reconnecting state clears the timer
+            // Arm on Connected->Reconnecting only; keep running across later
+            // non-Connected states; cancel on return to Connected.
+            if (state === NodeStates.Connected) {
                 this.#reconnectTimers.get(nodeId)?.stop();
                 this.#reconnectTimers.delete(nodeId);
+            } else if (
+                state === NodeStates.Reconnecting &&
+                !this.#reconnectTimers.has(nodeId) &&
+                this.#nodes.isAvailable(nodeId)
+            ) {
+                const timer = Time.getTimer(`reconnect-timeout-${nodeId}`, RECONNECT_TIMEOUT, () => {
+                    this.#reconnectTimers.delete(nodeId);
+                    if (this.#nodes.forceUnavailable(nodeId)) {
+                        logger.info(
+                            `Node ${this.formatNode(nodeId)} offline grace period expired, marking unavailable`,
+                        );
+                        this.events.nodeAvailabilityChanged.emit(nodeId, false);
+                    }
+                });
+                timer.utility = true;
+                timer.start();
+                this.#reconnectTimers.set(nodeId, timer);
             }
 
-            // Process state change and check if availability changed
-            const result = this.#nodes.processStateChange(nodeId, state);
+            const debouncePending = this.#reconnectTimers.has(nodeId);
+            const result = this.#nodes.processStateChange(nodeId, state, debouncePending);
 
-            // Emit state changed event
             this.events.nodeStateChanged.emit(nodeId, state);
 
-            // Emit availability changed if it actually changed
             if (result.availabilityChanged) {
                 logger.info(
                     `Node ${this.formatNode(nodeId)} availability changed to ${result.available} (state: ${NodeStates[state]})`,
@@ -369,13 +453,10 @@ export class ControllerCommandHandler {
             }
         });
         node.events.structureChanged.on(() => {
-            // Structure changed means endpoints may have been added/removed, refresh cache
             if (node.isConnected) {
                 attributeCache.update(node);
             }
             basicInfoChangedInBatch = false;
-            // Emit node_updated first so consumers see the new endpoint in node.endpoints,
-            // then drain any endpoint_added events queued since the previous structure change.
             this.events.nodeStructureChanged.emit(nodeId);
             for (const endpointId of this.#nodes.drainPendingEndpointAdds(nodeId)) {
                 this.events.nodeEndpointAdded.emit(nodeId, endpointId);
@@ -388,15 +469,12 @@ export class ControllerCommandHandler {
         node.events.nodeEndpointAdded.on(endpointId => this.#nodes.queueEndpointAdded(nodeId, endpointId));
         node.events.nodeEndpointRemoved.on(endpointId => this.events.nodeEndpointRemoved.emit(nodeId, endpointId));
 
-        // Store the node for direct access
         this.#nodes.set(nodeId, node);
 
         this.#nodes.seedState(nodeId, node.connectionState);
 
-        // Initialize attribute cache if node is already initialized
         if (node.initialized) {
             attributeCache.add(node);
-            // Register for custom cluster polling (e.g., Eve energy)
             const attributes = attributeCache.get(nodeId);
             if (attributes) {
                 this.#customClusterPoller.registerNode(this.#peerOf(nodeId), attributes);
@@ -659,7 +737,8 @@ export class ControllerCommandHandler {
 
         value = convertWebSocketTagBasedToMatter(value, attributeModel, clusterEntry.model);
 
-        logger.info("Writing attribute", attributeId, "with value", value);
+        const attributeName = attributeModel.propertyName;
+        logger.info(`Writing attribute ${clusterId}.${attributeName} (${clusterId}.${attributeId}) with value`, value);
         const { status, clusterStatus } = await this.#writeAttribute(
             nodeId,
             endpointId,
@@ -675,12 +754,11 @@ export class ControllerCommandHandler {
         request: Invoke.ConcreteCommandRequest<C>,
         options: Omit<Invoke.Definition, "commands"> = {},
     ) {
-        for await (const data of node.interaction.invoke(
-            Invoke({
-                commands: [request],
-                ...options,
-            }),
-        )) {
+        const invoke = Invoke({
+            commands: [request],
+            ...options,
+        });
+        for await (const data of node.interaction.invoke(invoke)) {
             for (const entry of data) {
                 // We send only one command, so we only get one response back
                 switch (entry.kind) {
@@ -827,6 +905,17 @@ export class ControllerCommandHandler {
                 regulatoryCountryCode: "XX",
                 wifiNetwork,
                 threadNetwork,
+                onAttestationFailure: findings => {
+                    let accept = true;
+                    for (const f of findings) {
+                        if (f.level === "error") {
+                            accept = false;
+                        }
+                        logger.info(`Attestation finding (${f.level}):`, f.type, f.message);
+                    }
+                    logger.info(`Attestation ${accept ? "accepted" : "rejected"}`);
+                    return accept;
+                },
             },
             discovery: {
                 knownAddress,
@@ -901,12 +990,12 @@ export class ControllerCommandHandler {
             return [];
         }
         return [latestDiscovery].map(({ DT, DN, CM, D, RI, PH, PI, T, VP, deviceIdentifier, addresses, SII, SAI }) => {
-            const { tcpClient: supportsTcpClient, tcpServer: supportsTcpServer } = SupportedTransportsSchema.decode(
-                T ?? 0,
-            );
+            const supportsTcpClient = T?.tcpClient ?? false;
+            const supportsTcpServer = T?.tcpServer ?? false;
             const vendorId = VP === undefined ? -1 : VP.includes("+") ? parseInt(VP.split("+")[0]) : parseInt(VP);
             const productId = VP === undefined ? -1 : VP.includes("+") ? parseInt(VP.split("+")[1]) : -1;
-            const port = addresses.length ? (addresses[0] as ServerAddressUdp).port : 0;
+            const firstAddress = addresses[0];
+            const port = firstAddress && ServerAddress.isIp(firstAddress) ? firstAddress.port : 0;
             const numIPs = addresses.length;
             return {
                 commissioningMode: CM,
@@ -926,7 +1015,7 @@ export class ControllerCommandHandler {
                 vendorId,
                 supportsTcpServer,
                 supportsTcpClient,
-                addresses: (addresses.filter(({ type }) => type === "udp") as ServerAddressUdp[]).map(({ ip }) => ip),
+                addresses: addresses.filter(ServerAddress.isIp).map(({ ip }) => ip),
                 mrpSessionIdleInterval: SII,
                 mrpSessionActiveInterval: SAI,
             };
@@ -948,7 +1037,7 @@ export class ControllerCommandHandler {
             }
         }
         if (peer) {
-            const sessionIp = peer.newestSession?.channel.networkAddress?.ip;
+            const sessionIp = peer.newestSession()?.channel.networkAddress?.ip;
             if (sessionIp) {
                 addresses.add(sessionIp);
             }
@@ -958,9 +1047,7 @@ export class ControllerCommandHandler {
         const node = this.#nodes.get(nodeId);
         const commissioningAddresses = node.node.maybeStateOf(CommissioningClient)?.addresses;
         if (commissioningAddresses !== undefined && commissioningAddresses.length > 0) {
-            const fallbackAddresses = commissioningAddresses
-                .filter((addr): addr is ServerAddressUdp => addr.type === "udp")
-                .map(addr => addr.ip);
+            const fallbackAddresses = commissioningAddresses.filter(ServerAddress.isIp).map(addr => addr.ip);
             for (const address of fallbackAddresses) {
                 addresses.add(address);
             }

package/src/controller/MatterController.ts

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { cdSigners, paaRoots, vendors } from "@matter/dcl-data/node";
 import {
     Bytes,
     CommissioningClient,
@@ -18,11 +19,14 @@ import {
     SoftwareUpdateManager,
     Timestamp,
 } from "@matter/main";
-import { VendorInfo } from "@matter/main/protocol";
+import { VendorInfo, DclCertificateService, DclVendorInfoService } from "@matter/main/protocol";
 import { VendorId } from "@matter/main/types";
+import { Endpoint } from "@matter/node";
+import { CameraControllerDevice } from "@matter/node/devices/camera-controller";
 import { CommissioningController } from "@project-chip/matter.js";
 import { Readable } from "node:stream";
 import { ConfigStorage } from "../server/ConfigStorage.js";
+import { WebRtcTransportRequestorServer } from "./behaviors/WebRtcTransportRequestorServer.js";
 import { BorderRouterDiscovery } from "./BorderRouterDiscovery.js";
 import { ControllerCommandHandler } from "./ControllerCommandHandler.js";
 import { LegacyDataInjector, LegacyServerData } from "./LegacyDataInjector.js";
@@ -62,6 +66,8 @@ export async function computeCompressedNodeId(
 export interface MatterControllerOptions {
     enableTestNetDcl?: boolean;
     disableOtaProvider?: boolean;
+    /** Disable bundled offline DCL seed data (PAA roots, CD signers, vendors). When true, only network DCL is used. */
+    disableDclSeed?: boolean;
     /** Server ID for storage. Default is "server", but may be "server-<hex(fabricId)>-<hex(vendorId)>" for multi-fabric support */
     serverId?: string;
     /** Server version string (e.g., "0.2.10" or "0.2.10-alpha.0"). Used for BasicInformation cluster. */
@@ -95,7 +101,9 @@ export class MatterController {
     #legacyCommissionedDates?: Map<string, Timestamp>;
     #enableTestNetDcl = false;
     #disableOtaProvider = true;
+    #disableDclSeed = false;
     readonly #borderRouterDiscovery: BorderRouterDiscovery;
+    #webRtcRequestor?: Endpoint<typeof CameraControllerDevice>;
 
     static async create(
         environment: Environment,
@@ -173,6 +181,7 @@ export class MatterController {
         this.#serverVersion = options.serverVersion ?? "0.0.0";
         this.#enableTestNetDcl = options.enableTestNetDcl ?? this.#enableTestNetDcl;
         this.#disableOtaProvider = options.disableOtaProvider ?? this.#disableOtaProvider;
+        this.#disableDclSeed = options.disableDclSeed ?? this.#disableDclSeed;
     }
 
     protected async initialize(
@@ -181,6 +190,24 @@ export class MatterController {
         legacyCommissionedDates?: Map<string, Timestamp>,
     ) {
         this.#legacyCommissionedDates = legacyCommissionedDates?.size ? legacyCommissionedDates : undefined;
+
+        // Register DCL services on the root environment; DclBehavior picks them up.
+        // When seeding is enabled (default), pre-populate from the bundled offline snapshot so
+        // commissioning works without internet access.
+        const includeTest = this.#enableTestNetDcl;
+        if (this.#disableDclSeed) {
+            new DclCertificateService(this.#env.root, { fetchTestCertificates: includeTest });
+        } else {
+            new DclCertificateService(this.#env.root, {
+                fetchTestCertificates: includeTest,
+                seed: {
+                    paaRoots: paaRoots({ includeTest }),
+                    cdSigners: cdSigners({ includeTest }),
+                },
+            });
+            new DclVendorInfoService(this.#env.root, { seed: { vendors: vendors({ includeTest }) } });
+        }
+
         this.#controllerInstance = new CommissioningController({
             environment: {
                 environment: this.#env,
@@ -192,6 +219,8 @@ export class MatterController {
             adminFabricId: fabricId !== undefined ? FabricId(fabricId) : undefined,
             rootNodeId: NodeId(112233), // TODO Remove when we switch to random IDs
             enableOtaProvider: !this.#disableOtaProvider,
+            tcp: true,
+            transportPreference: "tcp",
             basicInformation: {
                 vendorName: "Open Home Foundation",
                 productName: "OHF Matter Server",
@@ -216,7 +245,8 @@ export class MatterController {
             );
 
             this.#commandHandler.events.started.once(async () => {
-                this.#controllerInstance!.node.behaviors.require(DclBehavior, {
+                this.#controllerInstance!.node.behaviors.require(DclBehavior);
+                await this.#controllerInstance!.node.setStateOf(DclBehavior, {
                     fetchTestCertificates: this.#enableTestNetDcl,
                 });
 
@@ -228,13 +258,14 @@ export class MatterController {
 
                 // Start loading and initialization of meta data
                 initPromises.push(this.vendorInfoService());
-                initPromises.push(this.certificateService());
+                // initPromises.push(this.certificateService()); // postponed to commissioning needs
 
                 if (!this.#disableOtaProvider && this.#enableTestNetDcl) {
                     initPromises.push(this.#enableTestOtaImages());
                 }
 
                 initPromises.push(this.#borderRouterDiscovery.start());
+                initPromises.push(this.#enableWebRtcRequestor());
 
                 try {
                     await MatterAggregateError.allSettled(initPromises);
@@ -251,6 +282,27 @@ export class MatterController {
         return this.#borderRouterDiscovery;
     }
 
+    get webRtcRequestor(): Endpoint<typeof CameraControllerDevice> {
+        if (!this.#webRtcRequestor) {
+            throw new Error("WebRTC requestor endpoint not initialized");
+        }
+        return this.#webRtcRequestor;
+    }
+
+    async #enableWebRtcRequestor(): Promise<void> {
+        if (!this.#controllerInstance) {
+            throw new Error("Controller not started");
+        }
+        const node = this.#controllerInstance.node;
+        if (node.endpoints.has("camera-controller")) {
+            this.#webRtcRequestor = node.endpoints.for("camera-controller") as Endpoint<typeof CameraControllerDevice>;
+            return;
+        }
+        this.#webRtcRequestor = await node.add(
+            new Endpoint(CameraControllerDevice.with(WebRtcTransportRequestorServer), { id: "camera-controller" }),
+        );
+    }
+
     /**
      * Get the DCL vendor info service instance.
      * Lazily initializes the service if not already present.
@@ -324,6 +376,7 @@ export class MatterController {
     }
 
     async stop() {
+        await this.certificateService(); // Ensure it was initialized so that shutdown works
         await this.#borderRouterDiscovery.stop();
         await this.#commandHandler?.close(); // This closes also the controller instance if started
     }

package/src/controller/Nodes.ts

@@ -22,36 +22,24 @@ import { AttributeDataCache } from "./AttributeDataCache.js";
 export class Nodes {
     #nodes = new Map<NodeId, PairedNode>();
     #attributeCache = new AttributeDataCache();
-    /** Track previous connection state for availability debouncing */
-    #previousStates = new Map<NodeId, NodeStates>();
-    /** Cached availability so serialization and event paths always agree */
+    /** Cached so serialization and event paths always agree on availability. */
     #lastAvailability = new Map<NodeId, boolean>();
     /**
-     * Endpoint additions queued until the next nodeStructureChanged for that node.
-     * Preserves the wire contract used by python-matter-server: endpoint_added must
-     * arrive AFTER a node_updated that already carries the new endpoint, so consumers
-     * (e.g., Home Assistant) can resolve node.endpoints[endpoint_id] in their callback.
+     * Buffered endpoint_added events. python-matter-server wire contract requires
+     * node_updated (carrying the new endpoint) to arrive before endpoint_added,
+     * so HA can resolve node.endpoints[endpoint_id] in its callback.
      */
     #pendingEndpointAdds = new Map<NodeId, EndpointNumber[]>();
 
-    /**
-     * Get the attribute cache instance.
-     */
     get attributeCache(): AttributeDataCache {
         return this.#attributeCache;
     }
 
-    /**
-     * Get all node IDs.
-     */
     getIds(): NodeId[] {
         return Array.from(this.#nodes.keys());
     }
 
-    /**
-     * Get a node by ID.
-     * @throws ServerError if node not found
-     */
+    /** @throws ServerError if node not found */
     get(nodeId: NodeId): PairedNode {
         const node = this.#nodes.get(nodeId);
         if (node === undefined) {
@@ -60,34 +48,21 @@ export class Nodes {
         return node;
     }
 
-    /**
-     * Check if a node exists.
-     */
     has(nodeId: NodeId): boolean {
         return this.#nodes.has(nodeId);
     }
 
-    /**
-     * Add or update a node in storage.
-     */
     set(nodeId: NodeId, node: PairedNode): void {
         this.#nodes.set(nodeId, node);
     }
 
-    /**
-     * Remove a node from storage and clear its attribute cache and state tracking.
-     */
     delete(nodeId: NodeId): void {
         this.#nodes.delete(nodeId);
         this.#attributeCache.delete(nodeId);
-        this.#previousStates.delete(nodeId);
         this.#lastAvailability.delete(nodeId);
         this.#pendingEndpointAdds.delete(nodeId);
     }
 
-    /**
-     * Buffer an endpoint_added until the next nodeStructureChanged for that node.
-     */
     queueEndpointAdded(nodeId: NodeId, endpointId: EndpointNumber): void {
         let queue = this.#pendingEndpointAdds.get(nodeId);
         if (queue === undefined) {
@@ -97,10 +72,7 @@ export class Nodes {
         queue.push(endpointId);
     }
 
-    /**
-     * Take ownership of buffered endpoint additions for a node and clear the queue.
-     * Returned array is in insertion order; an empty array is returned if nothing is queued.
-     */
+    /** Returns insertion-ordered queue; empty if nothing pending. */
     drainPendingEndpointAdds(nodeId: NodeId): EndpointNumber[] {
         const queue = this.#pendingEndpointAdds.get(nodeId);
         if (queue === undefined || queue.length === 0) {
@@ -110,30 +82,19 @@ export class Nodes {
         return queue;
     }
 
-    /**
-     * Initialize state tracking for a newly paired/discovered node.
-     * Sets previous state and initial availability so the first stateChanged event
-     * has a real previous state instead of undefined.
-     */
     seedState(nodeId: NodeId, initialState: NodeStates): void {
-        this.#previousStates.set(nodeId, initialState);
         this.#lastAvailability.set(nodeId, initialState === NodeStates.Connected);
     }
 
-    /**
-     * Process a state change for a node. Reads previous state BEFORE updating,
-     * computes new availability, and updates both tracking maps atomically.
-     * Returns whether availability changed and the new value.
-     */
+    /** `debouncePending` = reconnect timer armed by caller; keeps non-Connected states available. */
     processStateChange(
         nodeId: NodeId,
         newState: NodeStates,
+        debouncePending: boolean,
     ): { availabilityChanged: true; available: boolean } | { availabilityChanged: false } {
-        const previousState = this.#previousStates.get(nodeId);
         const wasAvailable = this.#lastAvailability.get(nodeId) ?? false;
-        const available = this.isNodeAvailable(newState, previousState);
+        const available = this.isNodeAvailable(newState, debouncePending);
 
-        this.#previousStates.set(nodeId, newState);
         this.#lastAvailability.set(nodeId, available);
 
         if (wasAvailable !== available) {
@@ -142,47 +103,21 @@ export class Nodes {
         return { availabilityChanged: false };
     }
 
-    /**
-     * Force a node to unavailable state. Used by reconnect timeout
-     * when debounce period expires without reconnection.
-     * Only updates #lastAvailability — #previousStates is left as-is because
-     * processStateChange() will overwrite it on the next real state transition.
-     * Returns true if the node was previously considered available.
-     */
+    /** Returns true if the node was previously considered available. */
     forceUnavailable(nodeId: NodeId): boolean {
         const wasAvailable = this.#lastAvailability.get(nodeId) ?? false;
         this.#lastAvailability.set(nodeId, false);
         return wasAvailable;
     }
 
-    /**
-     * Determine if a node should be considered available based on its connection state.
-     * Uses debouncing logic similar to Python Matter Server:
-     * - Connected: available
-     * - Reconnecting when previously Connected: still available (debouncing)
-     * - WaitingForDeviceDiscovery or Disconnected: unavailable
-     *
-     * @param currentState Current connection state
-     * @param previousState Previous connection state (undefined if first state change)
-     * @returns true if node should be considered available
-     */
-    isNodeAvailable(currentState: NodeStates, previousState?: NodeStates): boolean {
+    isNodeAvailable(currentState: NodeStates, debouncePending = false): boolean {
         if (currentState === NodeStates.Connected) {
             return true;
         }
-        // Debounce: if transitioning from Connected to Reconnecting, still consider available
-        if (currentState === NodeStates.Reconnecting && previousState === NodeStates.Connected) {
-            return true;
-        }
-        // WaitingForDeviceDiscovery, Disconnected, or Reconnecting from non-connected state
-        return false;
+        return debouncePending;
     }
 
-    /**
-     * Check if a node is available. Returns the cached availability value set by
-     * seedState/processStateChange/forceUnavailable, avoiding the race where
-     * recomputing from live state disagrees with the event path's determination.
-     */
+    /** Returns the cached value, not a recomputation — avoids disagreement with the event path. */
     isAvailable(nodeId: NodeId): boolean {
         return this.#lastAvailability.get(nodeId) ?? false;
     }