@marcel2215/homebridge-supla-plugin 2.1.29 → 2.1.31

package/dist/platform.js

@@ -38,6 +38,8 @@ const settings_1 = require("./settings");
 const GarageDoorOpenerAccesory_1 = require("./Accesories/GarageDoorOpenerAccesory");
 const LightBulbAccesory_1 = require("./Accesories/LightBulbAccesory");
 const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const crypto_1 = require("crypto");
 const SuplaMqttClient_1 = require("./Heplers/SuplaMqttClient");
 const RGBLightBulbAccesory_1 = require("./Accesories/RGBLightBulbAccesory");
 const GateAccessory_1 = require("./Accesories/GateAccessory");
@@ -58,6 +60,7 @@ const ThermostatAccessory_1 = require("./Accesories/ThermostatAccessory");
 const ElectricityMeterAccessory_1 = require("./Accesories/ElectricityMeterAccessory");
 const DimmerRgbLightAccessory_1 = require("./Accesories/DimmerRgbLightAccessory");
 const ActionTriggerAccessory_1 = require("./Accesories/ActionTriggerAccessory");
+const DisplayName_1 = require("./Heplers/DisplayName");
 /**
  * HomebridgePlatform
  * This class is the main constructor for your plugin, this is where you should
@@ -78,27 +81,35 @@ class SuplaPlatform {
         this.mqttTransportHandlers = new Map();
         this.channelRegistry = new Map();
         this.ownerCleanups = new Map();
+        this.shutdownDrains = new Map();
+        this.gateLockFailSafeTasks = new Map();
         this.mqttDesiredSubscriptions = new Set();
         this.mqttSubscriptions = new Set();
         this.mqttPendingSubscriptions = new Set();
+        this.mqttPendingSubscriptionOperations = new Map();
         this.mqttRetryTimers = new Map();
         this.mqttRetryState = new Map();
         this.mqttRouterAttached = false;
         this.mqttTransportConnected = false;
+        this.mqttTransportEpoch = 0;
+        this.nextMqttSubscriptionOperationId = 0;
+        this.shuttingDown = false;
+        this.publishTimeoutMs = 5000;
         this.log.debug('Finished initializing platform:', this.config.name);
+        this.accountNamespace = this.computeAccountNamespace();
         const configView = this.config;
         this.coveringControlMode = this.normalizeCoveringControlMode(configView.coveringControlMode);
         this.coveringSetTopicSuffix = this.normalizeTopicSuffix(configView.coveringSetTopicSuffix || 'set/closing_percentage');
         this.coveringTiltTopicSuffix = this.normalizeTopicSuffix(configView.coveringTiltTopicSuffix || 'set/tilt');
-        this.coveringExecuteActionOpen = (configView.coveringExecuteActionOpen || 'reveal').toString();
-        this.coveringExecuteActionClose = (configView.coveringExecuteActionClose || 'shut').toString();
-        this.coveringExecuteActionStop = (configView.coveringExecuteActionStop || 'stop').toString();
-        this.coveringTravelTimeSeconds = Number(configView.coveringTravelTimeSeconds) || 0;
-        this.gateExecuteActionToggle = (configView.gateExecuteActionToggle || 'open_close').toString();
+        this.coveringExecuteActionOpen = String(configView.coveringExecuteActionOpen ?? '').trim() || 'reveal';
+        this.coveringExecuteActionClose = String(configView.coveringExecuteActionClose ?? '').trim() || 'shut';
+        this.coveringExecuteActionStop = String(configView.coveringExecuteActionStop ?? '').trim() || 'stop';
+        this.coveringTravelTimeSeconds = this.normalizeDurationSeconds(configView.coveringTravelTimeSeconds, 0, 0, 600);
+        this.gateExecuteActionToggle = String(configView.gateExecuteActionToggle ?? '').trim() || 'open_close';
         this.gateLockControlMode = this.normalizeGateLockControlMode(configView.gateLockControlMode);
-        this.gateLockExecuteAction = (configView.gateLockExecuteAction || 'open').toString();
+        this.gateLockExecuteAction = String(configView.gateLockExecuteAction ?? '').trim() || 'open';
         this.gateLockSetTopicSuffix = this.normalizeTopicSuffix(configView.gateLockSetTopicSuffix || 'set/on');
-        this.gateLockPulseSeconds = Number(configView.gateLockPulseSeconds) || 0;
+        this.gateLockPulseSeconds = this.normalizeDurationSeconds(configView.gateLockPulseSeconds, this.gateLockControlMode === 'set_on_pulse' ? 1 : 0, this.gateLockControlMode === 'set_on_pulse' ? 0.1 : 0, 60);
         this.gateLockSetOnPayload = (configView.gateLockSetOnPayload ?? 'true').toString();
         this.gateLockSetOffPayload = (configView.gateLockSetOffPayload ?? 'false').toString();
         this.frontGateFullTravelMs = this.normalizeFrontGateFullTravelMs(configView.frontGateFullTravelMs);
@@ -113,55 +124,147 @@ class SuplaPlatform {
         this.commandQos = this.normalizeCommandQos(configView.commandQos);
         this.commandRetain = this.parseBoolean(configView.commandRetain ?? false);
         this.api.on('shutdown', () => {
-            this.unregisterAllMqttHandlers();
-            if (this.MqttClient) {
-                this.MqttClient.client.end(true);
-            }
+            void this.shutdownGracefully();
         });
         this.api.on('didFinishLaunching', () => {
             log.debug('Executed didFinishLaunching callback');
-            const mqttSettings = this.config;
-            this.MqttClient = new SuplaMqttClient_1.SuplaMqttClient(mqttSettings, this.log);
-            this.startMqttRouter();
-            this.MqttClient.client.on('connect', () => {
-                this.updateMqttTransportState(true);
-                this.resubscribeAll(true);
-            });
-            this.MqttClient.client.on('close', () => {
-                this.updateMqttTransportState(false);
-                this.clearActiveSubscriptions();
-            });
-            this.MqttClient.client.on('offline', () => {
-                this.updateMqttTransportState(false);
-                this.clearActiveSubscriptions();
-            });
-            this.MqttClient.client.on('end', () => {
-                this.updateMqttTransportState(false);
-                this.clearActiveSubscriptions();
-            });
-            if (this.MqttClient.client.connected) {
-                this.updateMqttTransportState(true);
-                this.resubscribeAll(true);
-            }
-            this.discoverDevices();
-            this.MqttClient.discoverChannelsAsync((topic, handler) => (this.registerMqttHandler(topic, handler, 'discovery'))).then((channels) => {
-                this.persistChannels(channels);
-                this.discoverDevices(channels);
-                this.log.info('Channels discovered and saved to config file');
-            }).catch((error) => {
-                this.log.error(`Channel discovery failed: ${error.message}`);
+            void this.start().catch((error) => {
+                this.log.error(`Supla startup failed: ${error.message}`);
             });
         });
     }
+    async start() {
+        const mqttSettings = this.config;
+        this.MqttClient = new SuplaMqttClient_1.SuplaMqttClient(mqttSettings, this.log);
+        this.startMqttRouter();
+        this.MqttClient.client.on('connect', () => {
+            if (this.shuttingDown) {
+                return;
+            }
+            this.advanceMqttTransportEpoch();
+            this.updateMqttTransportState(true);
+            this.resubscribeAll(true);
+        });
+        this.MqttClient.client.on('close', () => {
+            this.updateMqttTransportState(false);
+            this.clearActiveSubscriptions();
+        });
+        this.MqttClient.client.on('offline', () => {
+            this.updateMqttTransportState(false);
+            this.clearActiveSubscriptions();
+        });
+        this.MqttClient.client.on('end', () => {
+            this.updateMqttTransportState(false);
+            this.clearActiveSubscriptions();
+        });
+        if (this.MqttClient.client.connected) {
+            this.advanceMqttTransportEpoch();
+            this.updateMqttTransportState(true);
+            this.resubscribeAll(true);
+        }
+        this.discoverDevices();
+        const snapshot = await this.MqttClient.discoverChannelsSnapshotAsync();
+        if (this.shuttingDown) {
+            return;
+        }
+        this.discoverDevices(snapshot.items, snapshot);
+        this.log.info(`MQTT discovery merged ${snapshot.items.length} channel(s); ` +
+            `authoritative=${snapshot.authoritative} complete=${snapshot.complete}.`);
+    }
+    shutdownGracefully() {
+        if (this.shutdownPromise) {
+            return this.shutdownPromise;
+        }
+        this.shutdownPromise = this.performGracefulShutdown();
+        return this.shutdownPromise;
+    }
+    async performGracefulShutdown() {
+        const drains = Array.from(this.shutdownDrains.values())
+            .flatMap(ownerDrains => Array.from(ownerDrains));
+        if (drains.length > 0) {
+            const drainTimeoutMs = 1500;
+            let timeout;
+            try {
+                await Promise.race([
+                    Promise.allSettled(drains.map(drain => Promise.resolve().then(drain))),
+                    new Promise((resolve) => {
+                        timeout = setTimeout(resolve, drainTimeoutMs);
+                    }),
+                ]);
+            }
+            finally {
+                if (timeout) {
+                    clearTimeout(timeout);
+                }
+            }
+        }
+        this.shuttingDown = true;
+        this.unregisterAllMqttHandlers();
+        const client = this.MqttClient?.client;
+        if (!client) {
+            return;
+        }
+        await new Promise((resolve) => {
+            let settled = false;
+            const finish = () => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                clearTimeout(forceTimer);
+                resolve();
+            };
+            const forceTimer = setTimeout(() => {
+                try {
+                    client.end(true);
+                }
+                catch (error) {
+                    this.log.debug(`Forced MQTT shutdown failed: ${error.message}`);
+                }
+                finish();
+            }, 1000);
+            try {
+                client.end(false, {}, finish);
+            }
+            catch (error) {
+                this.log.debug(`Graceful MQTT shutdown failed: ${error.message}`);
+                try {
+                    client.end(true);
+                }
+                catch {
+                    // The client is already closing; the bounded timer/finish path owns completion.
+                }
+                finish();
+            }
+        });
+    }
     /**
      * This function is invoked when homebridge restores cached accessories from disk at startup.
      * It should be used to setup event handlers for characteristics and update respective values.
      */
     configureAccessory(accessory) {
         this.log.info('Loading accessory from cache:', accessory.displayName);
+        const cachedDevice = accessory.context.device;
+        const storedNamespace = accessory.context.suplaAccountNamespace;
+        let mismatchRetirementFailed = false;
+        if (typeof storedNamespace === 'string'
+            && storedNamespace.length > 0
+            && storedNamespace !== this.accountNamespace) {
+            try {
+                this.api.unregisterPlatformAccessories(settings_1.PLUGIN_NAME, settings_1.PLATFORM_NAME, [accessory]);
+                this.log.info(`Retired cached accessory ${accessory.displayName} because its stored Supla account identity differs.`);
+                return;
+            }
+            catch (error) {
+                this.log.error(`Failed to retire account-incompatible accessory ${accessory.displayName}: ${error.message}`);
+                // Keep tracking the accessory so it can be made unavailable safely.
+                mismatchRetirementFailed = true;
+                accessory.context.deviceConfigured = false;
+                this.revokeAccessoryHandlers(accessory);
+            }
+        }
         // add the restored accessory to the accessories cache so we can track if it has already been registered
         this.accessories.push(accessory);
-        const cachedDevice = accessory.context.device;
         if (!cachedDevice || typeof cachedDevice !== 'object') {
             this.log.warn(`Cached accessory ${accessory.displayName} missing device context; will configure after discovery.`);
             accessory.context.deviceConfigured = false;
@@ -169,6 +272,16 @@ class SuplaPlatform {
         }
         const normalized = this.normalizeChannelContext(cachedDevice);
         accessory.context.device = normalized;
+        if (!this.isAccessoryAccountCompatible(accessory, normalized)) {
+            this.log.warn(`Cached accessory ${accessory.displayName} belongs to a different Supla account; ` +
+                'leaving it disabled until an authoritative discovery can retire it.');
+            accessory.context.deviceConfigured = false;
+            if (!mismatchRetirementFailed) {
+                this.revokeAccessoryHandlers(accessory);
+            }
+            return;
+        }
+        this.stampAccessoryIdentity(accessory);
         this.addChannelToRegistry(normalized);
         // Accessory construction is intentionally deferred until didFinishLaunching.
         // Homebridge restores cached accessories one at a time, so configuring a gate
@@ -180,26 +293,54 @@ class SuplaPlatform {
      * Accessories must only be registered once, previously created accessories
      * must not be registered again to prevent "duplicate UUID" errors.
      */
-    discoverDevices(channelsOverride) {
-        const rawChannels = channelsOverride ?? this.loadChannelsFromConfig();
-        let channels = rawChannels.map(channel => this.normalizeChannelContext(channel));
+    discoverDevices(channelsOverride, snapshot) {
+        const cachedChannels = this.deduplicateChannels([
+            ...this.loadPersistedChannels(),
+            ...this.accessories
+                .filter(accessory => this.isAccessoryAccountCompatible(accessory, accessory.context.device))
+                .map(accessory => accessory.context.device)
+                .filter((channel) => Boolean(channel)),
+        ].map(channel => this.normalizeChannelContext(channel)));
+        const shouldPrune = snapshot?.authoritative === true && snapshot.complete === true;
+        const rawChannels = channelsOverride === undefined
+            ? cachedChannels
+            : this.mergeChannels(cachedChannels, channelsOverride, !shouldPrune, shouldPrune);
+        let channels = rawChannels
+            .map(channel => this.normalizeChannelContext(channel))
+            .filter(channel => this.isChannelAccountCompatible(channel));
         if (channels.length === 0 && channelsOverride === undefined) {
             channels = this.accessories
+                .filter(accessory => this.isAccessoryAccountCompatible(accessory, accessory.context.device))
                 .map(accessory => accessory.context.device)
                 .filter((channel) => Boolean(channel))
                 .map(channel => this.normalizeChannelContext(channel));
         }
         channels = this.deduplicateChannels(channels);
         this.replaceChannelRegistry(channels);
+        const channelsToPersist = [...channels];
+        const retainPreviousChannel = (incoming, previous) => {
+            if (!previous) {
+                return;
+            }
+            const normalizedPrevious = this.normalizeChannelContext(previous);
+            const key = this.getChannelRegistryKey(incoming);
+            const index = channelsToPersist.findIndex(candidate => this.getChannelRegistryKey(candidate) === key);
+            if (index !== -1) {
+                channelsToPersist[index] = normalizedPrevious;
+            }
+            this.addChannelToRegistry(normalizedPrevious);
+        };
         this.log.info('Channels discovered:', channels.length);
         this.log.debug(`Discovery mode: ${channelsOverride ? 'live' : 'cached'} channels`);
         const channelUuids = new Set();
-        const shouldPrune = channelsOverride !== undefined && channels.length > 0;
-        const findExistingByIds = (candidate) => {
+        const findExistingByIds = (candidate, scopedUuid) => {
             if (candidate.deviceId === 'unknown' || candidate.channelId === 'unknown') {
                 return undefined;
             }
-            return this.accessories.find((accessory) => {
+            const matches = this.accessories.filter((accessory) => {
+                if (!this.isAccessoryAccountCompatible(accessory, accessory.context.device)) {
+                    return false;
+                }
                 const existing = accessory.context.device;
                 if (!existing) {
                     return false;
@@ -209,11 +350,32 @@ class SuplaPlatform {
                 }
                 return existing.deviceId === candidate.deviceId && existing.channelId === candidate.channelId;
             });
+            if (matches.length <= 1) {
+                return matches[0];
+            }
+            const scopedMatch = matches.find(accessory => accessory.UUID === scopedUuid);
+            if (scopedMatch) {
+                this.log.warn(`Found both scoped and legacy accessories for channel ${candidate.deviceId}/${candidate.channelId}; ` +
+                    'using the scoped identity and leaving the duplicate disabled.');
+                for (const duplicate of matches) {
+                    if (duplicate !== scopedMatch) {
+                        this.revokeAccessoryHandlers(duplicate);
+                    }
+                }
+                return scopedMatch;
+            }
+            this.log.error(`Ambiguous cached identities for channel ${candidate.deviceId}/${candidate.channelId}; ` +
+                'refusing to bind either accessory.');
+            for (const match of matches) {
+                this.revokeAccessoryHandlers(match);
+            }
+            return undefined;
         };
         // loop over the discovered devices and register each one if it has not already been registered
         for (const channel of channels) {
-            const existingByIds = findExistingByIds(channel);
-            const uuid = existingByIds?.UUID ?? this.getChannelUuid(channel);
+            const scopedUuid = this.getChannelUuid(channel);
+            const existingByIds = findExistingByIds(channel, scopedUuid);
+            const uuid = existingByIds?.UUID ?? scopedUuid;
             channelUuids.add(uuid);
             const existingAccessory = existingByIds ?? this.accessories.find(accessory => accessory.UUID === uuid);
             if (existingAccessory) {
@@ -221,45 +383,163 @@ class SuplaPlatform {
                 const signature = this.getChannelSignature(channel);
                 const previousSignature = existingAccessory.context.deviceSignature;
                 const wasConfigured = existingAccessory.context.deviceConfigured === true;
-                existingAccessory.context.device = channel;
-                existingAccessory.context.deviceSignature = signature;
                 this.log.debug(`Restoring channel ${channel.channelCaption} (${channel.deviceId}/${channel.channelId}) ` +
                     `function=${channel.channelFunction} type=${channel.channelType}`);
+                if (!this.isSupportedChannel(channel, existingAccessory)) {
+                    if (this.isExplicitlyUnsupportedChannel(channel, existingAccessory)) {
+                        this.log.warn(`Channel ${channel.channelCaption} is now explicitly unsupported ` +
+                            `(${channel.channelFunction}/${channel.channelType}); revoking its handlers.`);
+                        this.revokeAccessoryHandlers(existingAccessory);
+                        existingAccessory.context.device = channel;
+                        existingAccessory.context.deviceSignature = signature;
+                        existingAccessory.context.deviceConfigured = false;
+                        this.stampAccessoryIdentity(existingAccessory);
+                        this.api.updatePlatformAccessories([existingAccessory]);
+                    }
+                    else {
+                        this.log.warn(`Deferring incomplete channel ${channel.channelCaption} ` +
+                            `(${channel.channelFunction}/${channel.channelType}); retaining last configured context.`);
+                    }
+                    continue;
+                }
                 if (previousSignature !== signature || !wasConfigured) {
-                    if (previousSignature && previousSignature !== signature) {
-                        this.resetAccessoryServices(existingAccessory);
+                    const previousDevice = existingAccessory.context.device;
+                    const previousContext = { ...existingAccessory.context };
+                    const previousNames = this.captureAccessoryNames(existingAccessory);
+                    try {
+                        const safeDisplayName = this.resolveHomeKitDisplayName(channel, existingAccessory.displayName);
+                        if (existingAccessory.displayName !== safeDisplayName) {
+                            existingAccessory.updateDisplayName(safeDisplayName);
+                        }
+                        this.prepareAccessoryForReconfiguration(existingAccessory, channel);
+                        const configured = this.setupAccessory(channel, existingAccessory);
+                        if (!configured) {
+                            throw new Error('No compatible accessory handler');
+                        }
+                        existingAccessory.context.device = channel;
+                        existingAccessory.context.deviceSignature = signature;
+                        existingAccessory.context.deviceConfigured = true;
+                        this.stampAccessoryIdentity(existingAccessory);
+                        this.cleanupObsoleteServices(existingAccessory, channel);
+                        this.updateAccessoryNames(existingAccessory, channel);
+                        this.api.updatePlatformAccessories([existingAccessory]);
+                    }
+                    catch (error) {
+                        this.unregisterMqttHandlers(existingAccessory.UUID);
+                        this.restoreAccessoryContext(existingAccessory, previousContext);
+                        this.restoreAccessoryNames(existingAccessory, previousNames);
+                        retainPreviousChannel(channel, previousDevice);
+                        if (previousDevice && this.isSupportedChannel(previousDevice, existingAccessory)) {
+                            try {
+                                this.prepareAccessoryForReconfiguration(existingAccessory, previousDevice);
+                                existingAccessory.context.deviceConfigured = this.setupAccessory(previousDevice, existingAccessory);
+                            }
+                            catch (restoreError) {
+                                this.log.error(`Failed to restore previous handler for ${existingAccessory.displayName}: ` +
+                                    `${restoreError.message}`);
+                            }
+                        }
+                        this.log.error(`Failed to configure ${channel.channelCaption}; previous context retained: ${error.message}`);
+                        continue;
+                    }
+                }
+                else {
+                    const previousDevice = existingAccessory.context.device;
+                    const previousContext = { ...existingAccessory.context };
+                    const previousNames = this.captureAccessoryNames(existingAccessory);
+                    try {
+                        const metadataChanged = !this.areChannelContextsEqual(previousDevice, channel);
+                        const identityChanged = existingAccessory.context.suplaIdentityVersion !== 2
+                            || existingAccessory.context.suplaAccountNamespace !== this.accountNamespace;
+                        existingAccessory.context.device = channel;
+                        existingAccessory.context.deviceSignature = signature;
+                        this.stampAccessoryIdentity(existingAccessory);
+                        const namesChanged = this.updateAccessoryNames(existingAccessory, channel);
+                        if (metadataChanged || identityChanged || namesChanged) {
+                            this.api.updatePlatformAccessories([existingAccessory]);
+                        }
+                    }
+                    catch (error) {
+                        this.restoreAccessoryContext(existingAccessory, previousContext);
+                        this.restoreAccessoryNames(existingAccessory, previousNames);
+                        retainPreviousChannel(channel, previousDevice);
+                        this.log.error(`Failed to commit metadata for ${channel.channelCaption}; previous name and context retained: ` +
+                            `${error.message}`);
+                        continue;
                     }
-                    const configured = this.setupAccessory(channel, existingAccessory);
-                    existingAccessory.context.deviceConfigured = configured;
                 }
-                this.api.updatePlatformAccessories([existingAccessory]);
                 continue;
             }
             this.log.info('Adding new accessory:', channel.channelCaption);
             this.log.debug(`Registering channel ${channel.channelCaption} (${channel.deviceId}/${channel.channelId}) ` +
                 `function=${channel.channelFunction} type=${channel.channelType}`);
-            const accessory = new this.api.platformAccessory(channel.channelCaption, uuid);
-            accessory.context.device = channel;
-            accessory.context.deviceSignature = this.getChannelSignature(channel);
-            if (this.setupAccessory(channel, accessory)) {
+            if (!this.isSupportedChannel(channel)) {
+                this.log.warn(`Skipping unsupported/incomplete channel ${channel.channelCaption} ` +
+                    `(${channel.channelFunction}/${channel.channelType}).`);
+                continue;
+            }
+            const accessory = new this.api.platformAccessory(this.resolveHomeKitDisplayName(channel), uuid);
+            let registered = false;
+            try {
+                if (!this.setupAccessory(channel, accessory)) {
+                    throw new Error('No compatible accessory handler');
+                }
+                accessory.context.device = channel;
+                accessory.context.deviceSignature = this.getChannelSignature(channel);
                 accessory.context.deviceConfigured = true;
+                this.stampAccessoryIdentity(accessory);
+                this.updateAccessoryNames(accessory, channel);
                 this.api.registerPlatformAccessories(settings_1.PLUGIN_NAME, settings_1.PLATFORM_NAME, [accessory]);
+                registered = true;
                 this.accessories.push(accessory);
                 this.api.updatePlatformAccessories([accessory]);
             }
+            catch (error) {
+                this.unregisterMqttHandlers(accessory.UUID);
+                const index = this.accessories.indexOf(accessory);
+                if (index !== -1) {
+                    this.accessories.splice(index, 1);
+                }
+                if (registered) {
+                    try {
+                        this.api.unregisterPlatformAccessories(settings_1.PLUGIN_NAME, settings_1.PLATFORM_NAME, [accessory]);
+                    }
+                    catch (rollbackError) {
+                        this.log.error(`Failed to roll back registration for ${channel.channelCaption}: ` +
+                            `${rollbackError.message}`);
+                    }
+                }
+                this.log.error(`Failed to register ${channel.channelCaption}: ${error.message}`);
+            }
         }
         if (shouldPrune) {
             const accessoriesToRemove = this.accessories.filter(accessory => !channelUuids.has(accessory.UUID));
             for (const accessory of accessoriesToRemove) {
                 this.log.info('Removing existing accessory from cache:', accessory.displayName);
+                try {
+                    // Homebridge owns the durable registration. Do not tear down the live
+                    // handler until that external mutation has committed successfully.
+                    this.api.unregisterPlatformAccessories(settings_1.PLUGIN_NAME, settings_1.PLATFORM_NAME, [accessory]);
+                }
+                catch (error) {
+                    this.log.error(`Failed to remove ${accessory.displayName}; retaining its active handler: ` +
+                        `${error.message}`);
+                    const retainedDevice = accessory.context.device;
+                    if (retainedDevice && typeof retainedDevice === 'object') {
+                        this.addChannelToRegistry(this.normalizeChannelContext(retainedDevice));
+                    }
+                    continue;
+                }
                 this.unregisterMqttHandlers(accessory.UUID);
-                this.api.unregisterPlatformAccessories(settings_1.PLUGIN_NAME, settings_1.PLATFORM_NAME, [accessory]);
                 const index = this.accessories.indexOf(accessory);
                 if (index !== -1) {
                     this.accessories.splice(index, 1);
                 }
             }
         }
+        if (channelsOverride !== undefined) {
+            this.persistChannels(channelsToPersist);
+        }
     }
     loadChannelsFromConfig() {
         const rawChannels = this.config.channels;
@@ -282,32 +562,159 @@ class SuplaPlatform {
         this.log.warn('Cached channels format is invalid; expected string or array.');
         return [];
     }
-    persistChannels(channels) {
+    loadPersistedChannels() {
+        const currentStoragePath = this.getChannelCachePath();
+        const legacyStoragePath = this.getLegacyChannelCachePath();
+        const shouldMigrateLegacyPath = currentStoragePath !== legacyStoragePath
+            && !fs.existsSync(currentStoragePath)
+            && fs.existsSync(legacyStoragePath);
+        const storagePath = shouldMigrateLegacyPath ? legacyStoragePath : currentStoragePath;
         try {
-            const configPath = this.api.user.configPath();
-            const config = JSON.parse(fs.readFileSync(configPath).toString());
-            const platformConfig = config.platforms?.find((platform) => platform.platform === settings_1.PLATFORM_NAME);
-            if (!platformConfig) {
-                this.log.warn(`Failed to save channels: ${settings_1.PLATFORM_NAME} not found in config.`);
-                return;
+            if (fs.existsSync(storagePath)) {
+                const parsed = JSON.parse(fs.readFileSync(storagePath, 'utf8'));
+                if (parsed.version === 2
+                    && parsed.accountNamespace === this.accountNamespace
+                    && Array.isArray(parsed.channels)) {
+                    if (shouldMigrateLegacyPath) {
+                        this.log.info('Migrating Supla channel cache to the port/protocol-scoped filename.');
+                        this.persistChannels(parsed.channels);
+                    }
+                    return parsed.channels;
+                }
+                if (parsed.version === 1 && Array.isArray(parsed.channels)) {
+                    const compatible = parsed.channels.filter(channel => this.isSafeLegacyCacheMigration(channel));
+                    if (compatible.length === parsed.channels.length) {
+                        this.log.info('Migrating version 1 Supla channel cache to account-scoped format.');
+                        this.persistChannels(compatible);
+                        return compatible;
+                    }
+                    this.log.warn('Version 1 Supla cache contains account-unscoped legacy channels; ' +
+                        'live discovery or explicit migrateUnscopedLegacyAccessories=true is required.');
+                    if (compatible.length > 0) {
+                        this.persistChannels(compatible);
+                        return compatible;
+                    }
+                }
+                this.log.warn(`Ignoring unsupported Supla channel cache format at ${storagePath}.`);
             }
-            platformConfig.channels = JSON.stringify(channels);
-            this.config.channels = platformConfig.channels;
-            const payload = JSON.stringify(config, null, 2);
-            const tempPath = `${configPath}.tmp`;
-            fs.writeFileSync(tempPath, payload);
-            fs.renameSync(tempPath, configPath);
-            this.log.debug(`Saved ${channels.length} channels to config.`);
         }
         catch (error) {
-            this.log.error(`Failed to save channels: ${error.message}`);
+            this.log.warn(`Failed to load channel cache: ${error.message}`);
+        }
+        const legacyChannels = this.loadChannelsFromConfig();
+        const compatibleLegacyChannels = legacyChannels.filter(channel => this.isSafeLegacyCacheMigration(channel));
+        if (compatibleLegacyChannels.length > 0) {
+            this.log.info('Migrating legacy Supla channels cache from config to Homebridge storage.');
+            this.persistChannels(compatibleLegacyChannels);
+        }
+        if (compatibleLegacyChannels.length !== legacyChannels.length) {
+            this.log.warn('Skipped account-unscoped legacy channels from config cache; ' +
+                'they will be recreated from authenticated live discovery.');
+        }
+        return compatibleLegacyChannels;
+    }
+    isSafeLegacyCacheMigration(channel) {
+        const normalized = this.normalizeChannelContext(channel);
+        return this.isChannelAccountCompatible(normalized)
+            && (!this.isUnscopedLegacyChannel(normalized) || this.shouldMigrateUnscopedLegacyAccessories());
+    }
+    persistChannels(channels) {
+        try {
+            const cachePath = this.getChannelCachePath();
+            fs.mkdirSync(path.dirname(cachePath), { recursive: true });
+            const payload = {
+                version: 2,
+                accountNamespace: this.accountNamespace,
+                channels: channels.filter(channel => this.isChannelAccountCompatible(channel)),
+            };
+            const tempPath = `${cachePath}.tmp-${process.pid}`;
+            fs.writeFileSync(tempPath, JSON.stringify(payload, null, 2), { mode: 0o600 });
+            fs.renameSync(tempPath, cachePath);
+            this.log.debug(`Saved ${channels.length} channels to Homebridge storage.`);
+        }
+        catch (error) {
+            this.log.error(`Failed to save channel cache: ${error.message}`);
         }
     }
+    getChannelCachePath() {
+        const configView = this.config;
+        const identity = [
+            settings_1.PLATFORM_NAME,
+            String(configView.name ?? ''),
+            String(configView.host ?? '').trim().toLowerCase(),
+            String(configView.port ?? '').trim(),
+            String(configView.protocol ?? '').trim().toLowerCase(),
+            String(configView.tls ?? '').trim().toLowerCase(),
+            String(configView.username ?? '').trim(),
+            this.accountNamespace,
+        ].join('\u0000');
+        const instanceKey = (0, crypto_1.createHash)('sha256').update(identity).digest('hex').slice(0, 20);
+        return path.join(this.api.user.storagePath(), `supla-channels-${instanceKey}.json`);
+    }
+    getLegacyChannelCachePath() {
+        const configView = this.config;
+        const identity = [
+            settings_1.PLATFORM_NAME,
+            String(configView.name ?? ''),
+            String(configView.host ?? ''),
+            String(configView.username ?? ''),
+        ].join('\u0000');
+        const instanceKey = (0, crypto_1.createHash)('sha256').update(identity).digest('hex').slice(0, 20);
+        return path.join(this.api.user.storagePath(), `supla-channels-${instanceKey}.json`);
+    }
+    computeAccountNamespace() {
+        const configView = this.config;
+        const identity = [
+            String(configView.host ?? '').trim().toLowerCase(),
+            String(configView.port ?? '').trim(),
+            String(configView.username ?? '').trim(),
+        ].join('\u0000');
+        return (0, crypto_1.createHash)('sha256').update(identity).digest('hex');
+    }
+    stampAccessoryIdentity(accessory) {
+        accessory.context.suplaIdentityVersion = 2;
+        accessory.context.suplaAccountNamespace = this.accountNamespace;
+        // Retain this legacy field for consumers that used the first remediation schema.
+        accessory.context.schemaVersion = 2;
+    }
+    isAccessoryAccountCompatible(accessory, channel) {
+        const storedNamespace = accessory.context.suplaAccountNamespace;
+        if (typeof storedNamespace === 'string' && storedNamespace.length > 0) {
+            return storedNamespace === this.accountNamespace;
+        }
+        if (channel === undefined) {
+            return true;
+        }
+        if (this.isUnscopedLegacyChannel(channel)) {
+            return this.shouldMigrateUnscopedLegacyAccessories();
+        }
+        return this.isChannelAccountCompatible(channel);
+    }
+    isChannelAccountCompatible(channel) {
+        const topic = this.normalizeTopicBase(channel.topic ?? channel.rawTopic ?? '');
+        const match = topic.match(/^supla\/([^/]+)\/devices\//);
+        if (!match) {
+            // Legacy rollershutter topics contain no account identifier. They are
+            // recognized here, but migration requires the explicit opt-in checked by
+            // isSafeLegacyCacheMigration/isAccessoryAccountCompatible.
+            return topic.startsWith('supla/channels/status/rollershutter/');
+        }
+        const configuredUsername = String(this.config.username ?? '');
+        return match[1] === configuredUsername;
+    }
+    isUnscopedLegacyChannel(channel) {
+        const topic = this.normalizeTopicBase(channel.topic ?? channel.rawTopic ?? '');
+        return topic.startsWith('supla/channels/status/rollershutter/');
+    }
+    shouldMigrateUnscopedLegacyAccessories() {
+        const configured = this.config.migrateUnscopedLegacyAccessories;
+        return this.parseBooleanStrict(configured) === true;
+    }
     normalizeChannelContext(channel) {
         const rawTopic = (channel.rawTopic ?? channel.topic ?? '').toString();
         const baseFromTopic = this.normalizeTopicBase(rawTopic || (channel.topic ?? '').toString());
-        let deviceId = channel.deviceId;
-        let channelId = channel.channelId;
+        let deviceId = channel.deviceId?.toString().trim();
+        let channelId = channel.channelId?.toString().trim();
         if (!deviceId || !channelId) {
             const match = baseFromTopic.match(/\/devices\/(\d+)\/channels\/(\d+)(?:\/|$)/);
             if (match) {
@@ -321,23 +728,38 @@ class SuplaPlatform {
         if (!channelId) {
             channelId = 'unknown';
         }
-        const caption = channel.channelCaption || `Device ${deviceId} Channel ${channelId}`;
-        const channelType = channel.channelType || 'UNKNOWN';
-        const channelFunction = channel.channelFunction || 'UNKNOWN';
+        const suppliedCaption = (0, DisplayName_1.normalizeVendorCaption)(channel.channelCaption);
+        const caption = suppliedCaption || (0, DisplayName_1.generatedChannelCaption)(deviceId, channelId);
+        const captionAuthoritative = Boolean(suppliedCaption)
+            && channel.channelCaptionAuthoritative !== false
+            && !(0, DisplayName_1.isGeneratedChannelCaption)(suppliedCaption, deviceId, channelId);
+        const captionSource = captionAuthoritative
+            ? channel.channelCaptionSource ?? 'cache'
+            : 'generated';
+        const channelType = channel.channelType?.toString().trim().toUpperCase() || 'UNKNOWN';
+        const channelFunction = channel.channelFunction?.toString().trim().toUpperCase() || 'UNKNOWN';
         const mqttContext = this.config;
-        const baseTopic = baseFromTopic || `supla/${mqttContext.username}/devices/${deviceId}/channels/${channelId}`;
+        const hasStableIds = deviceId !== 'unknown' && channelId !== 'unknown';
+        const baseTopic = baseFromTopic || (hasStableIds
+            ? `supla/${mqttContext.username}/devices/${deviceId}/channels/${channelId}`
+            : '');
         if (deviceId === 'unknown' || channelId === 'unknown') {
             this.log.warn(`Channel missing device/channel id for topic ${rawTopic}`);
         }
-        return new SuplaChannelContext_1.SuplaChannelContext(baseTopic, channelType, channelFunction, caption, deviceId, channelId, rawTopic || undefined);
+        return new SuplaChannelContext_1.SuplaChannelContext(baseTopic, channelType, channelFunction, caption, deviceId, channelId, rawTopic || undefined, captionAuthoritative, captionSource);
     }
     getChannelUuid(channel) {
         const deviceId = channel.deviceId;
         const channelId = channel.channelId;
         const hasIds = deviceId && channelId && deviceId !== 'unknown' && channelId !== 'unknown';
-        const key = hasIds
+        const stableTopic = this.normalizeTopicBase(channel.topic || channel.rawTopic || '');
+        const channelKey = hasIds
             ? `${deviceId}:${channelId}`
-            : (channel.topic || channel.channelCaption || `${deviceId}:${channelId}`);
+            : stableTopic;
+        if (!channelKey) {
+            throw new Error('Cannot derive a stable Supla channel identity without IDs or a topic');
+        }
+        const key = `${this.accountNamespace}:${channelKey}`;
         return this.api.hap.uuid.generate(key);
     }
     getChannelSignature(channel) {
@@ -393,18 +815,364 @@ class SuplaPlatform {
         }
         return Array.from(byKey.values());
     }
+    mergeChannels(cachedChannels, liveChannels, preserveCachedOnly = true, snapshotAuthoritative = false) {
+        const cachedByKey = new Map();
+        for (const rawChannel of cachedChannels) {
+            const channel = this.normalizeChannelContext(rawChannel);
+            cachedByKey.set(this.getChannelRegistryKey(channel), channel);
+        }
+        const merged = preserveCachedOnly
+            ? new Map(cachedByKey)
+            : new Map();
+        for (const rawChannel of liveChannels) {
+            const channel = this.normalizeChannelContext(rawChannel);
+            const key = this.getChannelRegistryKey(channel);
+            const cached = cachedByKey.get(key);
+            if (cached) {
+                const useLiveCaption = channel.channelCaptionAuthoritative === true
+                    && (snapshotAuthoritative
+                        || channel.channelCaptionSource === 'retained'
+                        || channel.channelCaptionSource === 'authoritative_snapshot');
+                merged.set(key, new SuplaChannelContext_1.SuplaChannelContext(channel.topic || cached.topic, this.isKnownMetadata(channel.channelType) ? channel.channelType : cached.channelType, this.isKnownMetadata(channel.channelFunction) ? channel.channelFunction : cached.channelFunction, useLiveCaption ? channel.channelCaption : cached.channelCaption, channel.deviceId || cached.deviceId, channel.channelId || cached.channelId, channel.rawTopic || cached.rawTopic, useLiveCaption
+                    ? true
+                    : cached.channelCaptionAuthoritative, useLiveCaption
+                    ? snapshotAuthoritative
+                        ? 'authoritative_snapshot'
+                        : channel.channelCaptionSource
+                    : cached.channelCaptionSource));
+            }
+            else if (this.isKnownMetadata(channel.channelType)
+                && this.isKnownMetadata(channel.channelFunction)) {
+                merged.set(key, channel);
+            }
+            else {
+                this.log.warn(`Deferring incomplete new channel ${channel.deviceId}/${channel.channelId} ` +
+                    `(function=${channel.channelFunction}, type=${channel.channelType}).`);
+            }
+        }
+        return Array.from(merged.values());
+    }
+    isKnownMetadata(value) {
+        return Boolean(value && value.trim() && value.toUpperCase() !== 'UNKNOWN');
+    }
     getKnownChannels() {
         return Array.from(this.channelRegistry.values());
     }
-    resetAccessoryServices(accessory) {
-        const keepUuid = this.Service.AccessoryInformation.UUID;
+    isSupportedChannel(channel, accessory) {
+        if (this.isExplicitNoFunction(channel.channelFunction)) {
+            return this.getLegacyNoFunctionServiceUuids(channel, accessory).size > 0;
+        }
+        if (!this.isKnownMetadata(channel.channelFunction) || !this.isKnownMetadata(channel.channelType)) {
+            return false;
+        }
+        return this.getExpectedServiceUuids(channel).size > 0;
+    }
+    isExplicitlyUnsupportedChannel(channel, accessory) {
+        if (this.isExplicitNoFunction(channel.channelFunction)) {
+            return this.getLegacyNoFunctionServiceUuids(channel, accessory).size === 0;
+        }
+        return this.isKnownMetadata(channel.channelFunction)
+            && this.isKnownMetadata(channel.channelType)
+            && this.getExpectedServiceUuids(channel).size === 0;
+    }
+    getExpectedServiceUuids(channel, accessory) {
+        if (this.isExplicitNoFunction(channel.channelFunction)) {
+            return this.getLegacyNoFunctionServiceUuids(channel, accessory);
+        }
+        const byFunction = {
+            CONTROLLINGTHEGARAGEDOOR: [this.Service.GarageDoorOpener.UUID],
+            CONTROLLINGTHEGATE: [this.Service.GarageDoorOpener.UUID],
+            CONTROLLINGTHEGATEWAYLOCK: [this.Service.LockMechanism.UUID],
+            LIGHTSWITCH: [this.Service.Lightbulb.UUID],
+            POWERSWITCH: [this.Service.Switch.UUID],
+            RGBLIGHTING: [this.Service.Lightbulb.UUID],
+            DIMMER: [this.Service.Lightbulb.UUID],
+            DIMMERANDRGBLIGHTING: [this.Service.Lightbulb.UUID],
+            CONTROLLINGTHEROLLERSHUTTER: [this.Service.WindowCovering.UUID],
+            CONTROLLINGTHEFACADEBLIND: [this.Service.WindowCovering.UUID],
+            OPENINGSENSOR_GATE: [this.Service.ContactSensor.UUID],
+            OPENINGSENSOR_GATEWAY: [this.Service.ContactSensor.UUID],
+            OPENINGSENSOR_WINDOW: [this.Service.ContactSensor.UUID],
+            GENERAL_PURPOSE_MEASUREMENT: [this.Service.AirQualitySensor.UUID],
+            THERMOMETER: [this.Service.TemperatureSensor.UUID],
+            HUMIDITYANDTEMPERATURE: [this.Service.TemperatureSensor.UUID, this.Service.HumiditySensor.UUID],
+            PRESSURESENSOR: [this.Service.LightSensor.UUID],
+            VALVEOPENCLOSE: [this.Service.Valve.UUID],
+            HVAC_THERMOSTAT: [this.Service.Thermostat.UUID],
+            ELECTRICITYMETER: [this.Service.LightSensor.UUID],
+            ACTION_TRIGGER: [this.Service.StatelessProgrammableSwitch.UUID],
+        };
+        const byType = {
+            BINARYSENSOR: [
+                this.isLeakSensorChannel(channel, accessory)
+                    ? this.Service.LeakSensor.UUID
+                    : this.Service.ContactSensor.UUID,
+            ],
+            THERMOMETER: [this.Service.TemperatureSensor.UUID],
+            THERMOMETERDS18B20: [this.Service.TemperatureSensor.UUID],
+            HUMIDITYANDTEMPSENSOR: [this.Service.TemperatureSensor.UUID, this.Service.HumiditySensor.UUID],
+            GENERAL_PURPOSE_MEASUREMENT: [this.Service.AirQualitySensor.UUID],
+            PRESSURESENSOR: [this.Service.LightSensor.UUID],
+            ELECTRICITYMETER: [this.Service.LightSensor.UUID],
+            ACTION_TRIGGER: [this.Service.StatelessProgrammableSwitch.UUID],
+        };
+        return new Set(byFunction[channel.channelFunction] ?? byType[channel.channelType] ?? []);
+    }
+    getLegacyNoFunctionServiceUuids(channel, accessory) {
+        if (!accessory) {
+            return new Set();
+        }
+        const compatibleByType = {
+            RELAY: [this.Service.Switch.UUID, this.Service.Lightbulb.UUID],
+            DIMMER: [this.Service.Lightbulb.UUID],
+            DIMMERANDRGBLED: [this.Service.Lightbulb.UUID],
+            BINARYSENSOR: [this.Service.LeakSensor.UUID, this.Service.ContactSensor.UUID],
+            THERMOMETER: [this.Service.TemperatureSensor.UUID],
+            THERMOMETERDS18B20: [this.Service.TemperatureSensor.UUID],
+            HUMIDITYANDTEMPSENSOR: [this.Service.TemperatureSensor.UUID, this.Service.HumiditySensor.UUID],
+        };
+        const compatible = compatibleByType[channel.channelType] ?? [];
+        return new Set(compatible.filter(uuid => accessory.services.some(service => service.UUID === uuid)));
+    }
+    isExplicitNoFunction(value) {
+        return value?.trim().toUpperCase() === 'NONE';
+    }
+    cleanupObsoleteServices(accessory, channel) {
+        const expected = this.getExpectedServiceUuids(channel, accessory);
+        const knownPluginServiceUuids = new Set([
+            this.Service.GarageDoorOpener.UUID,
+            this.Service.LockMechanism.UUID,
+            this.Service.Lightbulb.UUID,
+            this.Service.Switch.UUID,
+            this.Service.WindowCovering.UUID,
+            this.Service.Door.UUID,
+            this.Service.ContactSensor.UUID,
+            this.Service.LeakSensor.UUID,
+            this.Service.TemperatureSensor.UUID,
+            this.Service.HumiditySensor.UUID,
+            this.Service.AirQualitySensor.UUID,
+            this.Service.LightSensor.UUID,
+            this.Service.Valve.UUID,
+            this.Service.Thermostat.UUID,
+            this.Service.StatelessProgrammableSwitch.UUID,
+        ]);
+        for (const service of [...accessory.services]) {
+            if (knownPluginServiceUuids.has(service.UUID) && !expected.has(service.UUID)) {
+                accessory.removeService(service);
+            }
+        }
+    }
+    prepareAccessoryForReconfiguration(accessory, channel) {
+        this.unregisterMqttHandlers(accessory.UUID);
+        this.cleanupObsoleteServices(accessory, channel);
+        const expectedServices = this.getExpectedServiceUuids(channel, accessory);
+        for (const service of accessory.services) {
+            if (!expectedServices.has(service.UUID)) {
+                continue;
+            }
+            for (const characteristic of service.characteristics) {
+                characteristic.removeOnGet();
+                characteristic.removeOnSet();
+            }
+            this.removeObsoleteOptionalCharacteristics(service, channel);
+        }
+    }
+    removeObsoleteOptionalCharacteristics(service, channel) {
+        const obsolete = new Set();
+        const servicesWithoutStatusFault = new Set([
+            this.Service.GarageDoorOpener.UUID,
+            this.Service.LockMechanism.UUID,
+            this.Service.Lightbulb.UUID,
+            this.Service.Switch.UUID,
+            this.Service.WindowCovering.UUID,
+            this.Service.Door.UUID,
+            this.Service.Thermostat.UUID,
+            this.Service.StatelessProgrammableSwitch.UUID,
+        ]);
+        if (servicesWithoutStatusFault.has(service.UUID)) {
+            obsolete.add(this.Characteristic.StatusFault.UUID);
+        }
+        if (service.UUID === this.Service.Lightbulb.UUID) {
+            if (channel.channelFunction === 'LIGHTSWITCH') {
+                obsolete.add(this.Characteristic.Brightness.UUID);
+                obsolete.add(this.Characteristic.Hue.UUID);
+                obsolete.add(this.Characteristic.Saturation.UUID);
+            }
+            else if (channel.channelFunction === 'DIMMER') {
+                obsolete.add(this.Characteristic.Hue.UUID);
+                obsolete.add(this.Characteristic.Saturation.UUID);
+            }
+        }
+        if (service.UUID === this.Service.WindowCovering.UUID
+            && channel.channelFunction === 'CONTROLLINGTHEROLLERSHUTTER') {
+            obsolete.add(this.Characteristic.CurrentHorizontalTiltAngle.UUID);
+            obsolete.add(this.Characteristic.TargetHorizontalTiltAngle.UUID);
+        }
+        if (service.UUID === this.Service.WindowCovering.UUID) {
+            // StatusJammed is not part of the HAP WindowCovering service. Older
+            // versions added it dynamically; remove that invalid composition.
+            obsolete.add(this.Characteristic.StatusJammed.UUID);
+        }
+        for (const characteristic of [...service.characteristics]) {
+            if (obsolete.has(characteristic.UUID)) {
+                service.removeCharacteristic(characteristic);
+            }
+        }
+    }
+    revokeAccessoryHandlers(accessory) {
+        this.unregisterMqttHandlers(accessory.UUID);
+        const unavailable = new this.api.hap.HapStatusError(-70402 /* this.api.hap.HAPStatus.SERVICE_COMMUNICATION_FAILURE */);
         for (const service of accessory.services) {
-            if (service.UUID === keepUuid) {
+            if (service.UUID === this.Service.AccessoryInformation.UUID) {
                 continue;
             }
-            accessory.removeService(service);
+            for (const characteristic of service.characteristics) {
+                characteristic.removeOnGet();
+                characteristic.removeOnSet();
+                if (characteristic.props.perms.includes("pr" /* this.api.hap.Perms.PAIRED_READ */)) {
+                    characteristic.updateValue(unavailable);
+                }
+                if (characteristic.props.perms.includes("pw" /* this.api.hap.Perms.PAIRED_WRITE */)) {
+                    characteristic.onSet(() => {
+                        throw new this.api.hap.HapStatusError(-70402 /* this.api.hap.HAPStatus.SERVICE_COMMUNICATION_FAILURE */);
+                    });
+                }
+            }
+        }
+    }
+    resolveHomeKitDisplayName(channel, currentName) {
+        const captionName = channel.channelCaptionAuthoritative === true
+            ? (0, DisplayName_1.toHomeKitDisplayName)(channel.channelCaption)
+            : undefined;
+        const hasRenameEvidence = channel.channelCaptionSource === 'retained'
+            || channel.channelCaptionSource === 'authoritative_snapshot';
+        if (captionName && hasRenameEvidence) {
+            return captionName;
+        }
+        const safeCurrentName = (0, DisplayName_1.toHomeKitDisplayName)(currentName);
+        if (safeCurrentName) {
+            return safeCurrentName;
+        }
+        // A new accessory (or a damaged empty legacy display name) may use its
+        // complete cached caption as an initial/recovery label. This is not allowed
+        // to replace an already meaningful existing name.
+        if (captionName) {
+            return captionName;
+        }
+        return (0, DisplayName_1.toHomeKitDisplayName)((0, DisplayName_1.generatedChannelCaption)(channel.deviceId, channel.channelId))
+            ?? 'Supla Device';
+    }
+    captureAccessoryNames(accessory) {
+        return {
+            displayName: accessory.displayName,
+            services: accessory.services.map((service) => {
+                const characteristic = service.characteristics.find(candidate => candidate.UUID === this.Characteristic.Name.UUID);
+                return {
+                    service,
+                    displayName: service.displayName,
+                    hadNameCharacteristic: characteristic !== undefined,
+                    nameValue: typeof characteristic?.value === 'string' ? characteristic.value : undefined,
+                };
+            }),
+        };
+    }
+    restoreAccessoryNames(accessory, snapshot) {
+        try {
+            accessory.updateDisplayName(snapshot.displayName);
+        }
+        catch (error) {
+            this.log.error(`Failed to restore accessory display name ${snapshot.displayName}: ${error.message}`);
+        }
+        for (const entry of snapshot.services) {
+            try {
+                entry.service.displayName = entry.displayName;
+                const current = entry.service.characteristics.find(candidate => candidate.UUID === this.Characteristic.Name.UUID);
+                if (!entry.hadNameCharacteristic) {
+                    if (current) {
+                        entry.service.removeCharacteristic(current);
+                    }
+                }
+                else if (entry.nameValue !== undefined && current?.value !== entry.nameValue) {
+                    entry.service.setCharacteristic(this.Characteristic.Name, entry.nameValue);
+                }
+            }
+            catch (error) {
+                this.log.error(`Failed to restore service name for ${snapshot.displayName}: ${error.message}`);
+            }
         }
     }
+    restoreAccessoryContext(accessory, snapshot) {
+        for (const key of Object.keys(accessory.context)) {
+            delete accessory.context[key];
+        }
+        Object.assign(accessory.context, snapshot);
+    }
+    areChannelContextsEqual(current, incoming) {
+        if (!current) {
+            return false;
+        }
+        const fields = [
+            'topic',
+            'channelType',
+            'channelFunction',
+            'channelCaption',
+            'deviceId',
+            'channelId',
+            'rawTopic',
+            'channelCaptionAuthoritative',
+            'channelCaptionSource',
+        ];
+        return fields.every(field => current[field] === incoming[field]);
+    }
+    updateAccessoryNames(accessory, channel) {
+        let changed = false;
+        const caption = (0, DisplayName_1.normalizeVendorCaption)(channel.channelCaption);
+        const homeKitName = this.resolveHomeKitDisplayName(channel, accessory.displayName);
+        if (accessory.displayName !== homeKitName) {
+            accessory.updateDisplayName(homeKitName);
+            changed = true;
+        }
+        const informationService = accessory.getService(this.Service.AccessoryInformation);
+        const informationName = informationService?.characteristics.find(candidate => candidate.UUID === this.Characteristic.Name.UUID);
+        if (informationService) {
+            if (informationService.displayName !== homeKitName) {
+                informationService.displayName = homeKitName;
+                changed = true;
+            }
+            if (informationName?.value !== homeKitName) {
+                informationService.setCharacteristic(this.Characteristic.Name, homeKitName);
+                changed = true;
+            }
+        }
+        const expected = this.getExpectedServiceUuids(channel, accessory);
+        const electricityMetric = accessory.context.suplaElectricityMetric;
+        for (const service of accessory.services) {
+            if (expected.has(service.UUID)) {
+                const serviceName = channel.channelFunction === 'ELECTRICITYMETER'
+                    && typeof electricityMetric === 'string'
+                    ? (0, DisplayName_1.homeKitElectricityServiceName)(homeKitName, electricityMetric)
+                    : homeKitName;
+                const nameCharacteristic = service.characteristics.find(candidate => candidate.UUID === this.Characteristic.Name.UUID);
+                if (service.displayName !== serviceName) {
+                    service.displayName = serviceName;
+                    changed = true;
+                }
+                if (nameCharacteristic?.value !== serviceName) {
+                    service.setCharacteristic(this.Characteristic.Name, serviceName);
+                    changed = true;
+                }
+            }
+        }
+        if (accessory.context.suplaVendorCaption !== caption
+            || accessory.context.suplaVendorCaptionAuthoritative !== (channel.channelCaptionAuthoritative === true)
+            || accessory.context.suplaHomeKitDisplayName !== homeKitName) {
+            changed = true;
+        }
+        accessory.context.suplaVendorCaption = caption;
+        accessory.context.suplaVendorCaptionAuthoritative = channel.channelCaptionAuthoritative === true;
+        accessory.context.suplaHomeKitDisplayName = homeKitName;
+        return changed;
+    }
     setupAccessory(channel, accessory) {
         this.unregisterMqttHandlers(accessory.UUID);
         this.log.debug(`Mapping channel ${channel.channelCaption} (${channel.deviceId}/${channel.channelId}) ` +
@@ -480,13 +1248,21 @@ class SuplaPlatform {
                 new DimmerAccessory_1.DimmerAccessory(this, accessory, channel);
                 return true;
             case 'RELAY':
-                new SwitchAccessory_1.SwitchAccessory(this, accessory, channel);
+                if (!accessory.getService(this.Service.Switch)
+                    && accessory.getService(this.Service.Lightbulb)) {
+                    new LightBulbAccesory_1.LightAccesory(this, accessory, channel);
+                }
+                else {
+                    new SwitchAccessory_1.SwitchAccessory(this, accessory, channel);
+                }
                 return true;
             case 'BINARYSENSOR':
-                if (this.isLeakSensorChannel(channel)) {
+                if (this.isLeakSensorChannel(channel, accessory)) {
+                    accessory.context.suplaBinarySensorKind = 'leak';
                     new LeakSensorAccessory_1.LeakSensorAccessory(this, accessory, channel);
                 }
                 else {
+                    accessory.context.suplaBinarySensorKind = 'contact';
                     new ContactSensorAccessory_1.ContactSensorAccessory(this, accessory, channel);
                 }
                 return true;
@@ -515,9 +1291,21 @@ class SuplaPlatform {
         this.log.warn(`Unsupported channel ${channel.channelCaption} (${channel.channelFunction}/${channel.channelType})`);
         return false;
     }
-    isLeakSensorChannel(channel) {
-        const caption = (channel.channelCaption ?? '').toLowerCase();
-        return ['leak', 'flood', 'water', 'zalania'].some(term => caption.includes(term));
+    isLeakSensorChannel(channel, accessory) {
+        const functionName = (channel.channelFunction ?? '').trim().toUpperCase();
+        if (functionName.includes('FLOOD')
+            || functionName.includes('WATERLEAK')
+            || functionName === 'LEAKSENSOR') {
+            return true;
+        }
+        const persistedKind = accessory?.context?.suplaBinarySensorKind;
+        if (persistedKind === 'leak' || persistedKind === 'contact') {
+            return persistedKind === 'leak';
+        }
+        // Preserve the topology of accessories created by older releases, which
+        // inferred this type from a caption. The migrated kind is persisted by
+        // setupAccessory and subsequent captions no longer participate.
+        return accessory?.services?.some(service => service.UUID === this.Service.LeakSensor.UUID) === true;
     }
     getCoveringControlMode() {
         return this.coveringControlMode;
@@ -561,6 +1349,97 @@ class SuplaPlatform {
     getGateLockSetOffPayload() {
         return this.gateLockSetOffPayload;
     }
+    claimGateLockFailSafe(accessoryUuid) {
+        const task = this.gateLockFailSafeTasks.get(accessoryUuid);
+        if (task) {
+            this.unregisterMqttHandlers(task.ownerId);
+        }
+    }
+    transferGateLockFailSafe(accessory, stateTopic, commandTopic, offPayload) {
+        if (this.shuttingDown || accessory.context.suplaGateLockPendingOff !== true) {
+            return;
+        }
+        if (this.gateLockFailSafeTasks.has(accessory.UUID)) {
+            return;
+        }
+        const task = {
+            ownerId: `gate-lock-failsafe:${accessory.UUID}`,
+            accessory,
+            stateTopic,
+            commandTopic,
+            offPayload,
+            attempted: false,
+        };
+        this.gateLockFailSafeTasks.set(accessory.UUID, task);
+        this.registerOwnerCleanup(task.ownerId, () => {
+            if (task.retryTimer) {
+                clearTimeout(task.retryTimer);
+                task.retryTimer = undefined;
+            }
+            if (this.gateLockFailSafeTasks.get(accessory.UUID) === task) {
+                this.gateLockFailSafeTasks.delete(accessory.UUID);
+            }
+        });
+        this.registerMqttHandler(stateTopic, (message, _topic, packet) => {
+            const relayOn = this.parseBooleanStrict(message.toString());
+            if (relayOn !== false || packet?.retain === true || !task.attempted) {
+                return;
+            }
+            accessory.context.suplaGateLockPendingOff = false;
+            const accessoryStillRegistered = Array.isArray(this.accessories)
+                && this.accessories.includes(accessory);
+            try {
+                if (accessoryStillRegistered) {
+                    this.api.updatePlatformAccessories([accessory]);
+                }
+            }
+            catch (error) {
+                accessory.context.suplaGateLockPendingOff = true;
+                this.log.error(`Failed to persist transferred gate-lock OFF confirmation for ${accessory.displayName}: ` +
+                    `${error.message}`);
+                this.scheduleGateLockFailSafeRetry(task);
+                return;
+            }
+            this.log.info(`Gate-lock fail-safe OFF confirmed for ${accessory.displayName}.`);
+            this.unregisterMqttHandlers(task.ownerId);
+        }, task.ownerId);
+        this.registerMqttTransportHandler((connected) => {
+            if (connected) {
+                this.attemptGateLockFailSafe(task);
+            }
+        }, task.ownerId);
+    }
+    attemptGateLockFailSafe(task) {
+        if (this.shuttingDown
+            || this.gateLockFailSafeTasks.get(task.accessory.UUID) !== task
+            || task.publishInFlight) {
+            return;
+        }
+        task.attempted = true;
+        this.log.warn(`Publishing transferred gate-lock fail-safe OFF for ${task.accessory.displayName}.`);
+        const operation = this.publishActionAsync(task.commandTopic, task.offPayload);
+        task.publishInFlight = operation;
+        void operation.catch((error) => {
+            this.log.warn(`Transferred gate-lock OFF remains unconfirmed for ${task.accessory.displayName}: ` +
+                `${error.message}`);
+        }).finally(() => {
+            if (task.publishInFlight === operation) {
+                task.publishInFlight = undefined;
+            }
+            this.scheduleGateLockFailSafeRetry(task);
+        });
+    }
+    scheduleGateLockFailSafeRetry(task) {
+        if (this.shuttingDown
+            || task.retryTimer
+            || this.gateLockFailSafeTasks.get(task.accessory.UUID) !== task) {
+            return;
+        }
+        task.retryTimer = setTimeout(() => {
+            task.retryTimer = undefined;
+            this.attemptGateLockFailSafe(task);
+        }, 5000);
+    }
     getFrontGateConfig() {
         return {
             fullTravelMs: this.frontGateFullTravelMs,
@@ -598,6 +1477,13 @@ class SuplaPlatform {
         }
         return 'execute_action';
     }
+    normalizeDurationSeconds(value, fallback, min, max) {
+        const parsed = Number(value);
+        if (!Number.isFinite(parsed)) {
+            return fallback;
+        }
+        return Math.min(max, Math.max(min, parsed));
+    }
     normalizeFrontGateFullTravelMs(value) {
         const fallbackMs = 25000;
         const parsed = Number(value);
@@ -724,6 +1610,20 @@ class SuplaPlatform {
             }
         };
     }
+    registerShutdownDrain(ownerId, drain) {
+        const drains = this.shutdownDrains.get(ownerId) ?? new Set();
+        drains.add(drain);
+        this.shutdownDrains.set(ownerId, drains);
+        const cleanup = () => {
+            const active = this.shutdownDrains.get(ownerId);
+            active?.delete(drain);
+            if (active?.size === 0) {
+                this.shutdownDrains.delete(ownerId);
+            }
+        };
+        this.registerOwnerCleanup(ownerId, cleanup);
+        return cleanup;
+    }
     unregisterMqttHandlers(ownerId) {
         this.runOwnerCleanup(ownerId);
         const ownerTopics = this.mqttHandlerOwners.get(ownerId);
@@ -755,14 +1655,70 @@ class SuplaPlatform {
         this.mqttDesiredSubscriptions.clear();
         this.mqttSubscriptions.clear();
         this.mqttPendingSubscriptions.clear();
+        this.mqttPendingSubscriptionOperations.clear();
         this.clearAllSubscriptionRetries();
+        this.shutdownDrains.clear();
         this.ownerCleanups.clear();
     }
     publishCommand(topic, payload, callback) {
-        this.publishMqtt(topic, payload, { qos: this.commandQos, retain: this.commandRetain }, callback);
+        this.publishMqtt(topic, payload, { qos: this.commandQos, retain: this.commandRetain }, error => callback?.(error));
+    }
+    publishCommandAsync(topic, payload) {
+        return this.publishMqttAsync(topic, payload, { qos: this.commandQos, retain: this.commandRetain });
     }
     publishGateAction(topic, payload, callback) {
-        this.publishMqtt(topic, payload, { qos: 0, retain: false }, callback);
+        this.publishMqtt(topic, payload, { qos: 0, retain: false }, (error, failureOrigin) => {
+            if (error && failureOrigin === 'callback') {
+                error.mqttPublishFailureKind = 'completion_unknown';
+            }
+            callback?.(error);
+        });
+    }
+    publishActionAsync(topic, payload) {
+        return this.publishMqttAsync(topic, payload, { qos: 0, retain: false }, true);
+    }
+    publishGateActionAsync(topic, payload) {
+        return this.publishActionAsync(topic, payload);
+    }
+    isPublishCompletionUnknown(error) {
+        return error instanceof Error
+            && error.mqttPublishFailureKind === 'completion_unknown';
+    }
+    publishMqttAsync(topic, payload, options, callbackFailureIsAmbiguous = false) {
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const finish = (kind, error) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                clearTimeout(timer);
+                if (!kind || !error) {
+                    resolve();
+                    return;
+                }
+                this.log.error(`Publish failed for ${topic}: ${error.message}`);
+                const hapError = new this.api.hap.HapStatusError(kind === 'completion_unknown'
+                    ? -70408 /* this.api.hap.HAPStatus.OPERATION_TIMED_OUT */
+                    : -70402 /* this.api.hap.HAPStatus.SERVICE_COMMUNICATION_FAILURE */);
+                hapError.mqttPublishFailureKind = kind;
+                hapError.cause = error;
+                reject(hapError);
+            };
+            const timer = setTimeout(() => {
+                finish('completion_unknown', new Error(`MQTT publish completion timed out after ${this.publishTimeoutMs}ms`));
+            }, this.publishTimeoutMs);
+            this.publishMqtt(topic, payload, options, (error, failureOrigin) => {
+                if (error) {
+                    finish(callbackFailureIsAmbiguous && failureOrigin === 'callback'
+                        ? 'completion_unknown'
+                        : 'definite_failure', error);
+                }
+                else {
+                    finish();
+                }
+            });
+        });
     }
     publishMqtt(topic, payload, options, callback) {
         const client = this.MqttClient?.client;
@@ -770,19 +1726,30 @@ class SuplaPlatform {
             const error = new Error('MQTT not connected');
             this.log.error(`MQTT not connected; cannot publish ${topic}`);
             if (callback) {
-                callback(error);
+                callback(error, 'preflight');
             }
             return;
         }
-        client.publish(topic, payload, options, (error) => {
+        try {
+            client.publish(topic, payload, options, (error) => {
+                if (callback) {
+                    callback(error, error ? 'callback' : undefined);
+                    return;
+                }
+                if (error) {
+                    this.log.error(`Publish failed for ${topic}: ${error.message}`);
+                }
+            });
+        }
+        catch (error) {
+            const publishError = error instanceof Error ? error : new Error(String(error));
             if (callback) {
-                callback(error);
-                return;
+                callback(publishError, 'preflight');
             }
-            if (error) {
-                this.log.error(`Publish failed for ${topic}: ${error.message}`);
+            else {
+                this.log.error(`Publish failed for ${topic}: ${publishError.message}`);
             }
-        });
+        }
     }
     parseBoolean(value) {
         if (typeof value === 'boolean') {
@@ -825,6 +1792,21 @@ class SuplaPlatform {
         }
         return undefined;
     }
+    parseFiniteNumberStrict(value) {
+        if (typeof value === 'number') {
+            return Number.isFinite(value) ? value : undefined;
+        }
+        if (typeof value !== 'string') {
+            return undefined;
+        }
+        const normalized = value.trim();
+        if (!normalized
+            || !/^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?$/i.test(normalized)) {
+            return undefined;
+        }
+        const parsed = Number(normalized);
+        return Number.isFinite(parsed) ? parsed : undefined;
+    }
     runOwnerCleanup(ownerId) {
         const cleanups = this.ownerCleanups.get(ownerId);
         if (!cleanups) {
@@ -856,12 +1838,17 @@ class SuplaPlatform {
             }
         }
     }
+    advanceMqttTransportEpoch() {
+        this.mqttTransportEpoch += 1;
+    }
     clearActiveSubscriptions() {
+        this.advanceMqttTransportEpoch();
         if (this.mqttSubscriptions.size > 0 || this.mqttPendingSubscriptions.size > 0) {
             this.log.debug('MQTT connection lost; clearing active subscriptions.');
         }
         this.mqttSubscriptions.clear();
         this.mqttPendingSubscriptions.clear();
+        this.mqttPendingSubscriptionOperations.clear();
         this.clearAllSubscriptionRetries();
     }
     clearAllSubscriptionRetries() {
@@ -916,9 +1903,11 @@ class SuplaPlatform {
         }
         this.mqttRetryState.set(topic, state);
         this.log.debug(`Retrying MQTT subscribe for ${topic} in ${scheduledDelayMs}ms (${reason}).`);
+        const scheduledEpoch = this.mqttTransportEpoch;
         const timer = setTimeout(() => {
             this.mqttRetryTimers.delete(topic);
-            if (!this.mqttDesiredSubscriptions.has(topic)) {
+            if (scheduledEpoch !== this.mqttTransportEpoch
+                || !this.mqttDesiredSubscriptions.has(topic)) {
                 return;
             }
             this.ensureSubscribed(topic, true);
@@ -927,7 +1916,7 @@ class SuplaPlatform {
     }
     isSubscriptionGranted(topic, granted) {
         if (!Array.isArray(granted) || granted.length === 0) {
-            return true;
+            return false;
         }
         const entry = granted.find((item) => item.topic === topic);
         if (!entry) {
@@ -971,11 +1960,25 @@ class SuplaPlatform {
             return;
         }
         this.mqttPendingSubscriptions.add(topic);
+        const client = this.MqttClient.client;
+        const operation = {
+            client,
+            epoch: this.mqttTransportEpoch,
+            id: ++this.nextMqttSubscriptionOperationId,
+        };
+        this.mqttPendingSubscriptionOperations.set(topic, operation);
         const subscribeOptions = {
             qos: 0,
             ...(this.mqttNoLocalTopics.has(topic) && this.mqttProtocolVersion === 5 ? { nl: true } : {}),
         };
-        this.MqttClient.client.subscribe(topic, subscribeOptions, (err, granted) => {
+        client.subscribe(topic, subscribeOptions, (err, granted) => {
+            if (this.mqttPendingSubscriptionOperations.get(topic) !== operation
+                || this.mqttTransportEpoch !== operation.epoch
+                || this.MqttClient?.client !== operation.client
+                || !operation.client.connected) {
+                return;
+            }
+            this.mqttPendingSubscriptionOperations.delete(topic);
             this.mqttPendingSubscriptions.delete(topic);
             if (err) {
                 this.logSubscriptionIssue(topic, `MQTT subscribe failed for ${topic}: ${err.message}`);
@@ -1014,6 +2017,7 @@ class SuplaPlatform {
         }
         if (force) {
             this.mqttPendingSubscriptions.clear();
+            this.mqttPendingSubscriptionOperations.clear();
         }
         for (const topic of this.mqttDesiredSubscriptions) {
             this.ensureSubscribed(topic, force);
@@ -1023,18 +2027,17 @@ class SuplaPlatform {
         this.mqttDesiredSubscriptions.delete(topic);
         this.mqttNoLocalTopics.delete(topic);
         this.mqttPendingSubscriptions.delete(topic);
+        this.mqttPendingSubscriptionOperations.delete(topic);
         this.clearSubscriptionRetry(topic);
-        if (!this.MqttClient) {
+        const wasSubscribed = this.mqttSubscriptions.delete(topic);
+        if (!wasSubscribed || !this.MqttClient || this.shuttingDown) {
             return;
         }
-        if (this.mqttSubscriptions.has(topic)) {
-            this.MqttClient.client.unsubscribe(topic, (err) => {
-                if (err) {
-                    this.log.error(`MQTT unsubscribe failed for ${topic}: ${err.message}`);
-                }
-            });
-            this.mqttSubscriptions.delete(topic);
-        }
+        this.MqttClient.client.unsubscribe(topic, (err) => {
+            if (err) {
+                this.log.error(`MQTT unsubscribe failed for ${topic}: ${err.message}`);
+            }
+        });
     }
     removeHandler(topic, handler) {
         const handlerMap = this.isWildcardTopic(topic) ? this.mqttWildcardHandlers : this.mqttHandlers;