@riddix/hamh 2.1.0-alpha.829 → 2.1.0-alpha.831

package/dist/backend/cli.js

@@ -131529,6 +131529,12 @@ var init_bridge_config_schema = __esm({
           description: "When a controller drops all subscriptions, clean up the dead session and re-announce after 5 seconds instead of 60. Opt-in for Google Home users whose devices go offline after a cancelled subscription (#386). It shortens the offline window but cannot stop the controller from rejecting the subscription. Default off.",
           type: "boolean",
           default: false
+        },
+        stableIdentity: {
+          title: "Stable Device Identity",
+          description: "Anchor each device to its Home Assistant entity registry id instead of the entity id, so renaming an entity no longer re-adds it in your controller (Alexa, Google Home, Apple Home) and keeps groups and automations. Records are seeded from the start, so enabling this later is safe and never re-adds existing devices. Default off.",
+          type: "boolean",
+          default: false
         }
       }
     };
@@ -132293,6 +132299,12 @@ var init_home_assistant_entity_behavior = __esm({
         customName;
         /** Entity mapping configuration (optional, used for advanced features like filter life sensor) */
         mapping;
+        /**
+         * Stable identity anchor for uniqueId/serialNumber. Set to the entity_id the
+         * identity was first seeded under, so those stay frozen across HA renames.
+         * Undefined falls back to the live entity_id (legacy behaviour).
+         */
+        identityAnchor;
       }
       HomeAssistantEntityBehavior2.State = State;
       class Events2 extends EventEmitter {
@@ -133576,7 +133588,7 @@ function diagnosticApi(bridgeService, haClient, haRegistry, version2, startTime)
 
 // src/api/entity-mapping-api.ts
 import express7 from "express";
-function entityMappingApi(mappingStorage) {
+function entityMappingApi(mappingStorage, identityStorage) {
   const router = express7.Router();
   router.get("/:bridgeId", (req, res) => {
     const { bridgeId } = req.params;
@@ -133657,6 +133669,7 @@ function entityMappingApi(mappingStorage) {
   router.delete("/:bridgeId", async (req, res) => {
     const { bridgeId } = req.params;
     await mappingStorage.deleteBridgeMappings(bridgeId);
+    await identityStorage.deleteBridgeIdentities(bridgeId);
     res.status(204).send();
   });
   return router;
@@ -134523,7 +134536,7 @@ function endpointToJson(endpoint, parentId) {
 
 // src/api/matter-api.ts
 var ajv = new Ajv();
-function matterApi(bridgeService, haRegistry) {
+function matterApi(bridgeService, haRegistry, identityStorage) {
   const router = express11.Router();
   router.get("/", (_, res) => {
     res.status(200).json({});
@@ -134600,6 +134613,7 @@ function matterApi(bridgeService, haRegistry) {
     const bridgeId = req.params.bridgeId;
     try {
       await bridgeService.delete(bridgeId);
+      await identityStorage?.deleteBridgeIdentities(bridgeId);
       res.status(204).send();
     } catch (e) {
       res.status(500).json({
@@ -134615,6 +134629,7 @@ function matterApi(bridgeService, haRegistry) {
       return;
     }
     try {
+      await identityStorage?.deleteBridgeIdentities(bridgeId);
       await bridge.factoryReset();
       await bridge.start();
       res.status(200).json(bridge.data);
@@ -136597,13 +136612,14 @@ var WebSocketApi = class {
 
 // src/api/web-api.ts
 var WebApi = class extends Service {
-  constructor(logger245, bridgeService, haClient, haRegistry, bridgeStorage, mappingStorage, lockCredentialStorage, settingsStorage, backupService, props) {
+  constructor(logger245, bridgeService, haClient, haRegistry, bridgeStorage, mappingStorage, identityStorage, lockCredentialStorage, settingsStorage, backupService, props) {
     super("WebApi");
     this.bridgeService = bridgeService;
     this.haClient = haClient;
     this.haRegistry = haRegistry;
     this.bridgeStorage = bridgeStorage;
     this.mappingStorage = mappingStorage;
+    this.identityStorage = identityStorage;
     this.lockCredentialStorage = lockCredentialStorage;
     this.settingsStorage = settingsStorage;
     this.backupService = backupService;
@@ -136623,6 +136639,7 @@ var WebApi = class extends Service {
   haRegistry;
   bridgeStorage;
   mappingStorage;
+  identityStorage;
   lockCredentialStorage;
   settingsStorage;
   backupService;
@@ -136639,7 +136656,10 @@ var WebApi = class extends Service {
   }
   async initialize() {
     const api = express17.Router();
-    api.use(express17.json()).use(nocache()).use("/matter", matterApi(this.bridgeService, this.haRegistry)).use(
+    api.use(express17.json()).use(nocache()).use(
+      "/matter",
+      matterApi(this.bridgeService, this.haRegistry, this.identityStorage)
+    ).use(
       "/health",
       healthApi(
         this.bridgeService,
@@ -136650,7 +136670,10 @@ var WebApi = class extends Service {
     ).use("/bridges", bridgeExportApi(this.bridgeStorage)).use("/bridge-icons", bridgeIconApi(this.props.storageLocation)).use(
       "/device-images",
       deviceImageApi(this.props.storageLocation, this.haRegistry)
-    ).use("/entity-mappings", entityMappingApi(this.mappingStorage)).use("/mapping-profiles", mappingProfileApi(this.mappingStorage)).use("/lock-credentials", lockCredentialApi(this.lockCredentialStorage)).use(
+    ).use(
+      "/entity-mappings",
+      entityMappingApi(this.mappingStorage, this.identityStorage)
+    ).use("/mapping-profiles", mappingProfileApi(this.mappingStorage)).use("/lock-credentials", lockCredentialApi(this.lockCredentialStorage)).use(
       "/settings",
       settingsApi(this.settingsStorage, this.bridgeService, this.props.auth)
     ).use(
@@ -138355,9 +138378,112 @@ var BridgeStorage = class extends Service {
   }
 };
 
-// src/services/storage/entity-mapping-storage.ts
+// src/services/storage/entity-identity-storage.ts
 init_service();
 var CURRENT_VERSION = 1;
+var PERSIST_DEBOUNCE_MS = 500;
+var EntityIdentityStorage = class extends Service {
+  constructor(appStorage) {
+    super("EntityIdentityStorage");
+    this.appStorage = appStorage;
+  }
+  appStorage;
+  storage;
+  identities = /* @__PURE__ */ new Map();
+  persistTimer = null;
+  async initialize() {
+    this.storage = this.appStorage.createContext("entity-identities");
+    await this.load();
+  }
+  async dispose() {
+    await this.flush();
+  }
+  async load() {
+    const stored = await this.storage.get("data", {
+      version: CURRENT_VERSION,
+      identities: {}
+    });
+    if (!stored || Object.keys(stored).length === 0) {
+      return;
+    }
+    const data = stored;
+    if (data.version !== CURRENT_VERSION) {
+      await this.migrate(data);
+      return;
+    }
+    for (const [bridgeId, records] of Object.entries(data.identities)) {
+      const bridgeMap = /* @__PURE__ */ new Map();
+      for (const [key, record] of Object.entries(records)) {
+        bridgeMap.set(key, record);
+      }
+      this.identities.set(bridgeId, bridgeMap);
+    }
+  }
+  async migrate(data) {
+    if (data.version < CURRENT_VERSION) {
+      for (const [bridgeId, records] of Object.entries(data.identities)) {
+        const bridgeMap = /* @__PURE__ */ new Map();
+        for (const [key, record] of Object.entries(records)) {
+          bridgeMap.set(key, record);
+        }
+        this.identities.set(bridgeId, bridgeMap);
+      }
+      await this.persist();
+    }
+  }
+  async persist() {
+    const data = {
+      version: CURRENT_VERSION,
+      identities: {}
+    };
+    for (const [bridgeId, bridgeMap] of this.identities) {
+      const records = {};
+      for (const [key, record] of bridgeMap) {
+        records[key] = record;
+      }
+      data.identities[bridgeId] = records;
+    }
+    await this.storage.set("data", data);
+  }
+  schedulePersist() {
+    if (this.persistTimer) return;
+    this.persistTimer = setTimeout(() => {
+      this.persistTimer = null;
+      void this.persist();
+    }, PERSIST_DEBOUNCE_MS);
+  }
+  // Flush any pending debounced write, used on dispose and by tests.
+  async flush() {
+    if (this.persistTimer) {
+      clearTimeout(this.persistTimer);
+      this.persistTimer = null;
+    }
+    await this.persist();
+  }
+  getIdentity(bridgeId, key) {
+    return this.identities.get(bridgeId)?.get(key);
+  }
+  getBridgeIdentities(bridgeId) {
+    return this.identities.get(bridgeId) ?? /* @__PURE__ */ new Map();
+  }
+  setIdentity(bridgeId, key, record) {
+    let bridgeMap = this.identities.get(bridgeId);
+    if (!bridgeMap) {
+      bridgeMap = /* @__PURE__ */ new Map();
+      this.identities.set(bridgeId, bridgeMap);
+    }
+    bridgeMap.set(key, record);
+    this.schedulePersist();
+  }
+  async deleteBridgeIdentities(bridgeId) {
+    this.identities.delete(bridgeId);
+    await this.flush();
+  }
+};
+
+// src/services/storage/entity-mapping-storage.ts
+init_service();
+var CURRENT_VERSION2 = 1;
 var EntityMappingStorage = class extends Service {
   constructor(appStorage) {
     super("EntityMappingStorage");
@@ -138372,14 +138498,14 @@ var EntityMappingStorage = class extends Service {
   }
   async load() {
     const stored = await this.storage.get("data", {
-      version: CURRENT_VERSION,
+      version: CURRENT_VERSION2,
       mappings: {}
     });
     if (!stored || Object.keys(stored).length === 0) {
       return;
     }
     const data = stored;
-    if (data.version !== CURRENT_VERSION) {
+    if (data.version !== CURRENT_VERSION2) {
       await this.migrate(data);
       return;
     }
@@ -138392,7 +138518,7 @@ var EntityMappingStorage = class extends Service {
     }
   }
   async migrate(data) {
-    if (data.version < CURRENT_VERSION) {
+    if (data.version < CURRENT_VERSION2) {
       for (const [bridgeId, configs] of Object.entries(data.mappings)) {
         const bridgeMap = /* @__PURE__ */ new Map();
         for (const config11 of configs) {
@@ -138405,7 +138531,7 @@ var EntityMappingStorage = class extends Service {
   }
   async persist() {
     const data = {
-      version: CURRENT_VERSION,
+      version: CURRENT_VERSION2,
       mappings: {}
     };
     for (const [bridgeId, bridgeMap] of this.mappings) {
@@ -138565,7 +138691,7 @@ function sanitizeThrottleMs(value) {
 // src/services/storage/lock-credential-storage.ts
 init_service();
 import { pbkdf2Sync, randomBytes as randomBytes3, timingSafeEqual as timingSafeEqual2 } from "node:crypto";
-var CURRENT_VERSION2 = 2;
+var CURRENT_VERSION3 = 2;
 var HASH_ITERATIONS = 1e5;
 var HASH_KEY_LENGTH = 64;
 var HASH_ALGORITHM = "sha512";
@@ -138584,14 +138710,14 @@ var LockCredentialStorage = class extends Service {
   }
   async load() {
     const stored = await this.storage.get("data", {
-      version: CURRENT_VERSION2,
+      version: CURRENT_VERSION3,
       credentials: []
     });
     if (!stored || Object.keys(stored).length === 0) {
       return;
     }
     const data = stored;
-    if (data.version !== CURRENT_VERSION2) {
+    if (data.version !== CURRENT_VERSION3) {
       await this.migrate(data);
       return;
     }
@@ -138620,7 +138746,7 @@ var LockCredentialStorage = class extends Service {
   }
   async persist() {
     const data = {
-      version: CURRENT_VERSION2,
+      version: CURRENT_VERSION3,
       credentials: Array.from(this.credentials.values())
     };
     await this.storage.set("data", data);
@@ -156975,8 +157101,8 @@ var AggregatorEndpoint2 = class extends Endpoint {
 // src/matter/endpoints/entity-endpoint.ts
 init_esm7();
 var EntityEndpoint = class extends Endpoint {
-  constructor(type, entityId, customName, mappedEntityIds) {
-    super(type, { id: createEndpointId(entityId, customName) });
+  constructor(type, entityId, customName, mappedEntityIds, endpointId) {
+    super(type, { id: endpointId ?? createEndpointId(entityId, customName) });
     this.entityId = entityId;
     this.mappedEntityIds = mappedEntityIds ?? [];
   }
@@ -157262,13 +157388,14 @@ var BasicInformationServer2 = class extends BridgedDeviceBasicInformationServer
     const homeAssistant = this.agent.get(HomeAssistantEntityBehavior);
     const device = entity.deviceRegistry;
     const mapping = homeAssistant.state.mapping;
+    const anchor = homeAssistant.state.identityAnchor ?? entity.entity_id;
     const registryName = featureFlags?.preferEntityRegistryName ? entity.registry?.name ?? entity.registry?.original_name : void 0;
     const nodeLabel = ellipse(32, homeAssistant.state.customName) ?? ellipse(32, registryName) ?? ellipse(32, entity.state?.attributes?.friendly_name) ?? ellipse(32, entity.entity_id);
     const productNameFromNodeLabel = featureFlags?.productNameFromNodeLabel === true ? ellipse(32, sanitizeMatterString(nodeLabel ?? "")) ?? void 0 : void 0;
     const serialNumberSuffix = this.env.get(BridgeDataProvider).serialNumberSuffix;
     const maxRawLen = 32 - (serialNumberSuffix?.length ?? 0);
     const registrySerial = featureFlags?.useHaRegistrySerial ? ellipse(maxRawLen, device?.serial_number) : void 0;
-    const rawSerial = ellipse(maxRawLen, mapping?.customSerialNumber) ?? registrySerial ?? hash(maxRawLen, entity.entity_id);
+    const rawSerial = ellipse(maxRawLen, mapping?.customSerialNumber) ?? registrySerial ?? hash(maxRawLen, anchor);
     const serialNumber = rawSerial && serialNumberSuffix ? `${rawSerial}${serialNumberSuffix}` : rawSerial;
     const customVendorId = mapping?.customVendorId;
     const vendorId3 = isValidVendorId(customVendorId) ? customVendorId : basicInformation.vendorId;
@@ -157288,18 +157415,18 @@ var BasicInformationServer2 = class extends BridgedDeviceBasicInformationServer
       // multiple fabric connections. Using MD5 hash of entity_id for stability.
       // uniqueIdSuffix mints a fresh identity so stale controller cloud
       // records keyed on it can be shed (#385).
-      uniqueId: this.frozenUniqueId(entity.entity_id)
+      uniqueId: this.frozenUniqueId(anchor)
     });
     logger201.debug(
       `[${entity.entity_id}] basicInfo vendor=${this.state.vendorName} product=${this.state.productName} label=${this.state.productLabel} serial=${this.state.serialNumber} node=${this.state.nodeLabel} uniqueId=${this.state.uniqueId}`
     );
   }
-  frozenUniqueId(entityId) {
+  frozenUniqueId(anchor) {
     const provider = this.env.get(BridgeDataProvider);
-    const key = `${provider.id}:${entityId}`;
+    const key = `${provider.id}:${anchor}`;
     let uniqueId = appliedUniqueIds.get(key);
     if (uniqueId == null) {
-      uniqueId = crypto6.createHash("md5").update(entityId + (provider.uniqueIdSuffix ?? "")).digest("hex").substring(0, 32);
+      uniqueId = crypto6.createHash("md5").update(anchor + (provider.uniqueIdSuffix ?? "")).digest("hex").substring(0, 32);
       appliedUniqueIds.set(key, uniqueId);
     }
     return uniqueId;
@@ -159071,7 +159198,7 @@ var ComposedAirPurifierEndpoint = class _ComposedAirPurifierEndpoint extends End
         })
       );
     }
-    const endpointId = createEndpointId2(primaryEntityId, config11.customName);
+    const endpointId = config11.endpointId ?? createEndpointId2(primaryEntityId, config11.customName);
     const parts = [];
     const airPurifierSub = new Endpoint(
       airPurifierSubType.set({
@@ -159116,7 +159243,8 @@ var ComposedAirPurifierEndpoint = class _ComposedAirPurifierEndpoint extends End
       homeAssistantEntity: {
         entity: primaryPayload,
         customName: config11.customName,
-        mapping: parentMapping
+        mapping: parentMapping,
+        identityAnchor: config11.identityAnchor
       }
     });
     const mappedIds = [];
@@ -160574,7 +160702,7 @@ var ComposedClimateFanEndpoint = class _ComposedClimateFanEndpoint extends Endpo
     const { registry: registry2, primaryEntityId } = config11;
     const payload = buildEntityPayload2(registry2, primaryEntityId);
     if (!payload) return void 0;
-    const endpointId = createEndpointId3(primaryEntityId, config11.customName);
+    const endpointId = config11.endpointId ?? createEndpointId3(primaryEntityId, config11.customName);
     const mapping = config11.mapping ?? {
       entityId: primaryEntityId
     };
@@ -160618,7 +160746,8 @@ var ComposedClimateFanEndpoint = class _ComposedClimateFanEndpoint extends Endpo
       homeAssistantEntity: {
         entity: payload,
         customName: config11.customName,
-        mapping
+        mapping,
+        identityAnchor: config11.identityAnchor
       }
     });
     const endpoint = new _ComposedClimateFanEndpoint(
@@ -160882,7 +161011,7 @@ var ComposedSensorEndpoint = class _ComposedSensorEndpoint extends Endpoint {
         })
       );
     }
-    const endpointId = createEndpointId4(primaryEntityId, config11.customName);
+    const endpointId = config11.endpointId ?? createEndpointId4(primaryEntityId, config11.customName);
     const parts = [];
     const tempSub = new Endpoint(
       TemperatureSubType2.set({
@@ -160924,7 +161053,8 @@ var ComposedSensorEndpoint = class _ComposedSensorEndpoint extends Endpoint {
       homeAssistantEntity: {
         entity: primaryPayload,
         customName: config11.customName,
-        mapping
+        mapping,
+        identityAnchor: config11.identityAnchor
       }
     });
     const mappedIds = [];
@@ -169960,7 +170090,7 @@ function WeatherDevice(homeAssistant) {
 
 // src/matter/endpoints/legacy/create-legacy-endpoint-type.ts
 var legacyLogger = Logger.get("LegacyEndpointType");
-function createLegacyEndpointType(entity, mapping, areaName, options) {
+function createLegacyEndpointType(entity, mapping, areaName, options, identityAnchor) {
   if (mapping?.disableBatteryMapping) {
     entity = {
       ...entity,
@@ -169973,11 +170103,12 @@ function createLegacyEndpointType(entity, mapping, areaName, options) {
   }
   const domain = entity.entity_id.split(".")[0];
   const customName = mapping?.customName;
+  const ha = { entity, customName, mapping, identityAnchor };
   let type;
   if (mapping?.matterDeviceType) {
     const overrideFactory = matterDeviceTypeFactories[mapping.matterDeviceType];
     if (overrideFactory) {
-      type = overrideFactory({ entity, customName, mapping });
+      type = overrideFactory(ha);
       if (type && mapping.batteryEntity && !hasPowerSource(type)) {
         type = addPowerSource(type);
       }
@@ -169986,14 +170117,14 @@ function createLegacyEndpointType(entity, mapping, areaName, options) {
   if (!type) {
     if (domain === "vacuum") {
       type = VacuumDevice(
-        { entity, customName, mapping },
+        ha,
         options?.vacuumOnOff,
         options?.cleaningModeOptions
       );
     } else {
       const factory = deviceCtrs[domain];
       if (factory) {
-        type = factory({ entity, customName, mapping });
+        type = factory(ha);
       } else if (options?.pluginDomainMappings?.has(domain)) {
         const mappedType = options.pluginDomainMappings.get(domain);
         const mappedFactory = matterDeviceTypeFactories[mappedType];
@@ -170001,7 +170132,7 @@ function createLegacyEndpointType(entity, mapping, areaName, options) {
           legacyLogger.info(
             `Using plugin domain mapping for "${domain}" \u2192 "${mappedType}"`
           );
-          type = mappedFactory({ entity, customName, mapping });
+          type = mappedFactory(ha);
         }
       } else {
         return void 0;
@@ -170186,7 +170317,7 @@ var UserComposedEndpoint = class _UserComposedEndpoint extends Endpoint {
     if (hasParentBattery) {
       parentType = parentType.with(DefaultPowerSourceServer);
     }
-    const endpointId = createEndpointId5(primaryEntityId, config11.customName);
+    const endpointId = config11.endpointId ?? createEndpointId5(primaryEntityId, config11.customName);
     const parts = [];
     const subEndpointMap = /* @__PURE__ */ new Map();
     const mappedIds = [];
@@ -170264,7 +170395,8 @@ var UserComposedEndpoint = class _UserComposedEndpoint extends Endpoint {
       homeAssistantEntity: {
         entity: primaryPayload,
         customName: config11.customName,
-        mapping: config11.mapping
+        mapping: config11.mapping,
+        identityAnchor: config11.identityAnchor
       }
     });
     const endpoint = new _UserComposedEndpoint(
@@ -170386,7 +170518,7 @@ function asStandaloneEndpointType(type) {
 // src/matter/endpoints/legacy/legacy-endpoint.ts
 var logger240 = Logger.get("LegacyEndpoint");
 var LegacyEndpoint = class _LegacyEndpoint extends EntityEndpoint {
-  static async create(registry2, entityId, mapping, pluginDomainMappings, standalone = false) {
+  static async create(registry2, entityId, mapping, pluginDomainMappings, standalone = false, endpointId, identityAnchor) {
     const deviceRegistry = registry2.deviceOf(entityId);
     let state = registry2.initialState(entityId);
     const entity = registry2.entity(entityId);
@@ -170639,7 +170771,9 @@ var LegacyEndpoint = class _LegacyEndpoint extends EntityEndpoint {
         mapping: effectiveMapping,
         composedEntities: effectiveMapping.composedEntities,
         customName: effectiveMapping?.customName,
-        areaName: composedAreaName
+        areaName: composedAreaName,
+        endpointId,
+        identityAnchor
       });
       if (composed) {
         return composed;
@@ -170661,7 +170795,9 @@ var LegacyEndpoint = class _LegacyEndpoint extends EntityEndpoint {
           powerEntityId: effectiveMapping?.powerEntity,
           energyEntityId: effectiveMapping?.energyEntity,
           customName: effectiveMapping?.customName,
-          areaName: composedAreaName
+          areaName: composedAreaName,
+          endpointId,
+          identityAnchor
         });
         return composed;
       }
@@ -170681,7 +170817,9 @@ var LegacyEndpoint = class _LegacyEndpoint extends EntityEndpoint {
             energyEntityId: effectiveMapping?.energyEntity,
             mapping: effectiveMapping,
             customName: effectiveMapping?.customName,
-            areaName: composedAreaName
+            areaName: composedAreaName,
+            endpointId,
+            identityAnchor
           });
           if (composed) {
             return composed;
@@ -170698,7 +170836,9 @@ var LegacyEndpoint = class _LegacyEndpoint extends EntityEndpoint {
           primaryEntityId: entityId,
           mapping: effectiveMapping,
           customName: effectiveMapping?.customName,
-          areaName: composedAreaName
+          areaName: composedAreaName,
+          endpointId,
+          identityAnchor
         });
         if (composed) {
           return composed;
@@ -170732,11 +170872,17 @@ var LegacyEndpoint = class _LegacyEndpoint extends EntityEndpoint {
       }
     }
     const areaName = registry2.getAreaName(entityId);
-    let type = createLegacyEndpointType(payload, effectiveMapping, areaName, {
-      vacuumOnOff: registry2.isVacuumOnOffEnabled(),
-      cleaningModeOptions,
-      pluginDomainMappings
-    });
+    let type = createLegacyEndpointType(
+      payload,
+      effectiveMapping,
+      areaName,
+      {
+        vacuumOnOff: registry2.isVacuumOnOffEnabled(),
+        cleaningModeOptions,
+        pluginDomainMappings
+      },
+      identityAnchor
+    );
     if (!type) {
       return;
     }
@@ -170750,11 +170896,12 @@ var LegacyEndpoint = class _LegacyEndpoint extends EntityEndpoint {
       entityId,
       customName,
       mappedIds,
-      effectiveMapping?.updateThrottleMs
+      effectiveMapping?.updateThrottleMs,
+      endpointId
     );
   }
-  constructor(type, entityId, customName, mappedEntityIds, throttleMs) {
-    super(type, entityId, customName, mappedEntityIds);
+  constructor(type, entityId, customName, mappedEntityIds, throttleMs, endpointId) {
+    super(type, entityId, customName, mappedEntityIds, endpointId);
     this.flushUpdate = throttleMs && throttleMs > 50 ? throttleLatest(this.flushPendingUpdate.bind(this), throttleMs) : debounce6(this.flushPendingUpdate.bind(this), 50);
   }
   lastState;
@@ -171601,11 +171748,124 @@ var EntityIsolationServiceImpl = class {
 };
 var EntityIsolationService = new EntityIsolationServiceImpl();
 
+// src/services/bridges/identity-resolver.ts
+var SEP = "\0";
+function identityKey(entity) {
+  const uniqueId = entity.registry?.unique_id;
+  const platform = entity.registry?.platform;
+  if (!uniqueId || !platform) {
+    return null;
+  }
+  const domain = entity.entity_id.split(".")[0];
+  return platform + SEP + domain + SEP + uniqueId;
+}
+var IdentityResolver = class {
+  constructor(identityStorage, mappingStorage) {
+    this.identityStorage = identityStorage;
+    this.mappingStorage = mappingStorage;
+  }
+  identityStorage;
+  mappingStorage;
+  async resolveIdentity(bridgeId, entity, mapping, opts) {
+    const entityId = entity.entity_id;
+    const key = identityKey(entity);
+    if (key == null) {
+      return {
+        endpointId: createEndpointId(entityId, mapping?.customName),
+        anchorEntityId: entityId,
+        protected: false
+      };
+    }
+    const existing = this.identityStorage.getIdentity(bridgeId, key);
+    if (existing) {
+      const renamedFrom = existing.lastEntityId !== entityId ? existing.lastEntityId ?? existing.anchorEntityId : void 0;
+      if (opts.stableIdentity) {
+        if (renamedFrom) {
+          this.identityStorage.setIdentity(bridgeId, key, {
+            ...existing,
+            lastEntityId: entityId
+          });
+          await this.rekeyMapping(bridgeId, renamedFrom, entityId);
+        }
+        return {
+          endpointId: existing.endpointId,
+          anchorEntityId: existing.anchorEntityId,
+          protected: true,
+          renamedFrom
+        };
+      }
+      const liveEndpointId = createEndpointId(entityId, mapping?.customName);
+      if (existing.endpointId !== liveEndpointId || existing.anchorEntityId !== entityId || existing.lastEntityId !== entityId) {
+        this.identityStorage.setIdentity(bridgeId, key, {
+          ...existing,
+          endpointId: liveEndpointId,
+          anchorEntityId: entityId,
+          lastEntityId: entityId
+        });
+      }
+      return {
+        endpointId: liveEndpointId,
+        anchorEntityId: entityId,
+        protected: false,
+        renamedFrom
+      };
+    }
+    const desired = createEndpointId(entityId, mapping?.customName);
+    let endpointId = desired;
+    if (opts.stableIdentity) {
+      let n = 2;
+      while (opts.isEndpointIdTaken(endpointId, key)) {
+        endpointId = `${desired}_${n++}`;
+      }
+    }
+    const record = {
+      endpointId,
+      anchorEntityId: entityId,
+      lastEntityId: entityId,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    this.identityStorage.setIdentity(bridgeId, key, record);
+    if (opts.stableIdentity) {
+      return {
+        endpointId: record.endpointId,
+        anchorEntityId: record.anchorEntityId,
+        protected: true
+      };
+    }
+    return {
+      endpointId: desired,
+      anchorEntityId: entityId,
+      protected: false
+    };
+  }
+  // Carry a mapping from the old entity_id to the new one on rename. anchorEntityId
+  // never changes, only the mapping key. Skips when no old mapping exists or a new
+  // one already does, so a manual mapping under the new id is never clobbered.
+  async rekeyMapping(bridgeId, oldEntityId, newEntityId) {
+    if (oldEntityId === newEntityId) {
+      return;
+    }
+    const old = this.mappingStorage.getMapping(bridgeId, oldEntityId);
+    if (!old) {
+      return;
+    }
+    if (this.mappingStorage.getMapping(bridgeId, newEntityId)) {
+      return;
+    }
+    await this.mappingStorage.setMapping({
+      ...old,
+      bridgeId,
+      entityId: newEntityId
+    });
+    await this.mappingStorage.deleteMapping(bridgeId, oldEntityId);
+  }
+};
+
 // src/services/bridges/bridge-endpoint-manager.ts
 var MAX_ENTITY_ID_LENGTH = 150;
 var ENDPOINT_REMOVAL_GRACE_MS = 6e4;
 var BridgeEndpointManager = class extends Service {
-  constructor(client, registry2, mappingStorage, bridgeId, log, pluginManager, pluginRegistry, pluginInstaller) {
+  constructor(client, registry2, mappingStorage, identityStorage, bridgeId, log, pluginManager, pluginRegistry, pluginInstaller) {
     super("BridgeEndpointManager");
     this.client = client;
     this.registry = registry2;
@@ -171616,6 +171876,10 @@ var BridgeEndpointManager = class extends Service {
     this.pluginRegistry = pluginRegistry;
     this.pluginInstaller = pluginInstaller;
     this.root = new AggregatorEndpoint2("aggregator");
+    this.identityResolver = new IdentityResolver(
+      identityStorage,
+      mappingStorage
+    );
     EntityIsolationService.registerIsolationCallback(
       bridgeId,
       this.isolateEntity.bind(this)
@@ -171654,6 +171918,7 @@ var BridgeEndpointManager = class extends Service {
       failedAt: (/* @__PURE__ */ new Date()).toISOString()
     });
   }
+  identityResolver;
   wirePluginCallbacks() {
     if (!this.pluginManager) return;
     this.pluginManager.onDeviceRegistered = async (pluginName, device) => {
@@ -171993,10 +172258,57 @@ var BridgeEndpointManager = class extends Service {
         if (humId) this.registry.markComposedSubEntityUsed(humId);
       }
     }
+    const stableIdentity = this.registry.isStableIdentityEnabled();
+    const resolvedByEntity = /* @__PURE__ */ new Map();
+    const endpointIdToEntity = /* @__PURE__ */ new Map();
+    const claimedEndpointIds = /* @__PURE__ */ new Map();
+    for (const entityId of this.entityIds) {
+      const entityInfo = {
+        entity_id: entityId,
+        registry: this.registry.entity(entityId)
+      };
+      const resolved = await this.identityResolver.resolveIdentity(
+        this.bridgeId,
+        entityInfo,
+        this.getEntityMapping(entityId),
+        {
+          stableIdentity,
+          isEndpointIdTaken: (id, key) => claimedEndpointIds.has(id) && claimedEndpointIds.get(id) !== key
+        }
+      );
+      resolvedByEntity.set(entityId, resolved);
+      claimedEndpointIds.set(
+        resolved.endpointId,
+        identityKey(entityInfo) ?? `\0e:${entityId}`
+      );
+      endpointIdToEntity.set(resolved.endpointId, entityId);
+      if (resolved.renamedFrom && this.mappingFingerprints.has(resolved.renamedFrom)) {
+        const fp = this.mappingFingerprints.get(resolved.renamedFrom);
+        this.mappingFingerprints.delete(resolved.renamedFrom);
+        this.mappingFingerprints.set(entityId, fp);
+      }
+    }
     const existingEndpoints = [];
     const now = Date.now();
     for (const endpoint of endpoints) {
       const present = this.entityIds.includes(endpoint.entityId);
+      const claimant = endpointIdToEntity.get(endpoint.id);
+      if (!present && claimant != null && claimant !== endpoint.entityId) {
+        this.log.info(
+          `Entity renamed ${endpoint.entityId} -> ${claimant}, keeping endpoint ${endpoint.id}`
+        );
+        try {
+          await endpoint.close();
+        } catch (e) {
+          this.log.warn(
+            `Failed to close renamed endpoint ${endpoint.entityId}:`,
+            e
+          );
+        }
+        this.pendingRemovals.delete(endpoint.entityId);
+        this.mappingFingerprints.delete(endpoint.entityId);
+        continue;
+      }
       if (present) {
         this.pendingRemovals.delete(endpoint.entityId);
       }
@@ -172039,7 +172351,8 @@ var BridgeEndpointManager = class extends Service {
           this.log.info(
             `Mapping changed for ${endpoint.entityId}, recreating endpoint`
           );
-          const sameId = createEndpointId(endpoint.entityId, currentMapping?.customName) === endpoint.id;
+          const resolvedId = resolvedByEntity.get(endpoint.entityId)?.endpointId ?? createEndpointId(endpoint.entityId, currentMapping?.customName);
+          const sameId = resolvedId === endpoint.id;
           try {
             if (sameId) {
               await endpoint.close();
@@ -172097,11 +172410,15 @@ var BridgeEndpointManager = class extends Service {
       if (!endpoint) {
         try {
           const domainMappings = this.getPluginDomainMappings();
+          const resolved = resolvedByEntity.get(entityId);
           endpoint = await LegacyEndpoint.create(
             this.registry,
             entityId,
             mapping,
-            domainMappings
+            domainMappings,
+            false,
+            resolved?.endpointId,
+            resolved?.anchorEntityId
           );
         } catch (e) {
           const reason = this.extractErrorReason(e);
@@ -172513,6 +172830,11 @@ var BridgeRegistry = class _BridgeRegistry {
   isVacuumOnOffEnabled() {
     return this.dataProvider.featureFlags?.vacuumOnOff === true;
   }
+  // Consume frozen device identities (#404). Seeding always runs; only
+  // consumption of the stored endpoint id/anchor is gated on this flag.
+  isStableIdentityEnabled() {
+    return this.dataProvider.featureFlags?.stableIdentity === true;
+  }
   /**
    * Check if the vacuum OnOff cluster should be included for server-mode vacuums.
    * Defaults to OFF. OnOff is NOT part of the RoboticVacuumCleaner (0x74) device
@@ -173942,7 +174264,7 @@ function ServerModeVacuumDevice(homeAssistantEntity, includeOnOff = false, clean
 // src/matter/endpoints/server-mode-vacuum-endpoint.ts
 var logger243 = Logger.get("ServerModeVacuumEndpoint");
 var ServerModeVacuumEndpoint = class _ServerModeVacuumEndpoint extends EntityEndpoint {
-  static async create(registry2, entityId, mapping) {
+  static async create(registry2, entityId, mapping, endpointId) {
     const deviceRegistry = registry2.deviceOf(entityId);
     let state = registry2.initialState(entityId);
     const entity = registry2.entity(entityId);
@@ -174123,14 +174445,15 @@ var ServerModeVacuumEndpoint = class _ServerModeVacuumEndpoint extends EntityEnd
       endpointType,
       entityId,
       customName,
-      mappedIds
+      mappedIds,
+      endpointId
     );
   }
   lastState;
   pendingMappedChange = false;
   flushUpdate;
-  constructor(type, entityId, customName, mappedEntityIds) {
-    super(type, entityId, customName, mappedEntityIds);
+  constructor(type, entityId, customName, mappedEntityIds, endpointId) {
+    super(type, entityId, customName, mappedEntityIds, endpointId);
     this.flushUpdate = debounce7(this.flushPendingUpdate.bind(this), 50);
   }
   clearTimers() {
@@ -174197,7 +174520,7 @@ var ServerModeVacuumEndpoint = class _ServerModeVacuumEndpoint extends EntityEnd
 // src/services/bridges/server-mode-endpoint-manager.ts
 var MAX_SERVER_MODE_DEVICES = 10;
 var ServerModeEndpointManager = class extends Service {
-  constructor(serverNode, client, registry2, mappingStorage, dataProvider, log) {
+  constructor(serverNode, client, registry2, mappingStorage, identityStorage, dataProvider, log) {
     super("ServerModeEndpointManager");
     this.serverNode = serverNode;
     this.client = client;
@@ -174205,6 +174528,10 @@ var ServerModeEndpointManager = class extends Service {
     this.mappingStorage = mappingStorage;
     this.dataProvider = dataProvider;
     this.log = log;
+    this.identityResolver = new IdentityResolver(
+      identityStorage,
+      mappingStorage
+    );
   }
   serverNode;
   client;
@@ -174223,6 +174550,7 @@ var ServerModeEndpointManager = class extends Service {
   get devices() {
     return [...this.endpoints.values()].map((entry) => entry.endpoint);
   }
+  identityResolver;
   getEntityMapping(entityId) {
     return this.mappingStorage.getMapping(this.dataProvider.id, entityId);
   }
@@ -174291,6 +174619,19 @@ var ServerModeEndpointManager = class extends Service {
       this.endpoints.delete(entityId);
     }
   }
+  // Like removeEndpoints but close() keeps the persisted number pre-allocated,
+  // so a same-id recreate reuses it. Used on rename and same-id recreates (#404).
+  async closeEndpoint(entityId) {
+    const entry = this.endpoints.get(entityId);
+    if (!entry) return;
+    try {
+      await entry.endpoint.close();
+    } catch (e) {
+      this.log.warn(`Failed to close endpoint ${entityId}:`, e);
+    }
+    this.serverNode.forgetDevice(entry.endpoint);
+    this.endpoints.delete(entityId);
+  }
   async refreshDevices() {
     this.registry.refresh();
     this._failedEntities = [];
@@ -174318,10 +174659,45 @@ var ServerModeEndpointManager = class extends Service {
           `Server mode node is capped at ${MAX_SERVER_MODE_DEVICES} devices, ${surplus.length} entities skipped`
         );
       }
+      const stableIdentity = this.dataProvider.featureFlags?.stableIdentity === true;
+      const resolvedByEntity = /* @__PURE__ */ new Map();
+      const endpointIdToEntity = /* @__PURE__ */ new Map();
+      const claimedEndpointIds = /* @__PURE__ */ new Map();
+      for (const entityId of orderedIds) {
+        const entityInfo = {
+          entity_id: entityId,
+          registry: this.registry.entity(entityId)
+        };
+        const resolved = await this.identityResolver.resolveIdentity(
+          this.dataProvider.id,
+          entityInfo,
+          this.getEntityMapping(entityId),
+          {
+            stableIdentity,
+            isEndpointIdTaken: (id, key) => claimedEndpointIds.has(id) && claimedEndpointIds.get(id) !== key
+          }
+        );
+        resolvedByEntity.set(entityId, resolved);
+        claimedEndpointIds.set(
+          resolved.endpointId,
+          identityKey(entityInfo) ?? `\0e:${entityId}`
+        );
+        endpointIdToEntity.set(resolved.endpointId, entityId);
+      }
       const keep = new Set(orderedIds);
       const removed = [...this.endpoints.keys()].filter((id) => !keep.has(id));
       let structureChanged = removed.length > 0;
-      await this.removeEndpoints(removed);
+      const genuinelyRemoved = [];
+      for (const oldId of removed) {
+        const entry = this.endpoints.get(oldId);
+        const claimant = entry ? endpointIdToEntity.get(entry.endpoint.id) : void 0;
+        if (entry && claimant != null && claimant !== oldId) {
+          await this.closeEndpoint(oldId);
+        } else {
+          genuinelyRemoved.push(oldId);
+        }
+      }
+      await this.removeEndpoints(genuinelyRemoved);
       for (const entityId of orderedIds) {
         const mapping = this.getEntityMapping(entityId);
         if (mapping?.disabled) {
@@ -174344,9 +174720,14 @@ var ServerModeEndpointManager = class extends Service {
           this.log.debug(`Device endpoint already exists for ${entityId}`);
           continue;
         }
+        const resolved = resolvedByEntity.get(entityId);
         if (existing) {
           this.log.info(`Mapping changed for ${entityId}, recreating endpoint`);
-          await this.removeEndpoints([entityId]);
+          if (resolved && existing.endpoint.id === resolved.endpointId) {
+            await this.closeEndpoint(entityId);
+          } else {
+            await this.removeEndpoints([entityId]);
+          }
           structureChanged = true;
         }
         const claimedBy = [...this.endpoints.entries()].find(
@@ -174359,7 +174740,7 @@ var ServerModeEndpointManager = class extends Service {
           });
           continue;
         }
-        const endpointId = createEndpointId(entityId, mapping?.customName);
+        const endpointId = resolved?.endpointId ?? createEndpointId(entityId, mapping?.customName);
         const collision = [...this.endpoints.entries()].find(
           ([, entry]) => entry.endpoint.id === endpointId
         );
@@ -174382,12 +174763,18 @@ var ServerModeEndpointManager = class extends Service {
         }
         try {
           const domain = entityId.split(".")[0];
-          const endpoint = domain === "vacuum" ? await this.createServerModeVacuumEndpoint(entityId, mapping) : await LegacyEndpoint.create(
+          const endpoint = domain === "vacuum" ? await this.createServerModeVacuumEndpoint(
+            entityId,
+            mapping,
+            resolved?.endpointId
+          ) : await LegacyEndpoint.create(
             this.registry,
             entityId,
             mapping,
             void 0,
-            true
+            true,
+            resolved?.endpointId,
+            resolved?.anchorEntityId
           );
           if (!endpoint) {
             this._failedEntities.push({
@@ -174455,8 +174842,13 @@ var ServerModeEndpointManager = class extends Service {
    * This makes the vacuum appear as a standalone Matter device, which is required
    * for Apple Home Siri voice commands and Alexa discovery.
    */
-  async createServerModeVacuumEndpoint(entityId, mapping) {
-    return ServerModeVacuumEndpoint.create(this.registry, entityId, mapping);
+  async createServerModeVacuumEndpoint(entityId, mapping, endpointId) {
+    return ServerModeVacuumEndpoint.create(
+      this.registry,
+      entityId,
+      mapping,
+      endpointId
+    );
   }
 };
 
@@ -174540,6 +174932,7 @@ var BridgeEnvironment = class _BridgeEnvironment extends EnvironmentBase {
         await this.load(HomeAssistantClient),
         this.get(BridgeRegistry),
         await this.load(EntityMappingStorage),
+        await this.load(EntityIdentityStorage),
         bridgeId,
         this.endpointManagerLogger,
         pluginManager,
@@ -174625,6 +175018,7 @@ var BridgeEnvironmentFactory = class extends BridgeFactory {
       await env.load(HomeAssistantClient),
       env.get(BridgeRegistry),
       await env.load(EntityMappingStorage),
+      await env.load(EntityIdentityStorage),
       dataProvider,
       loggerService.get("ServerModeEndpointManager")
     );
@@ -174676,6 +175070,10 @@ var AppEnvironment = class _AppEnvironment extends EnvironmentBase {
       EntityMappingStorage,
       new EntityMappingStorage(await this.load(AppStorage))
     );
+    this.set(
+      EntityIdentityStorage,
+      new EntityIdentityStorage(await this.load(AppStorage))
+    );
     this.set(
       LockCredentialStorage,
       new LockCredentialStorage(await this.load(AppStorage))
@@ -174736,6 +175134,7 @@ var AppEnvironment = class _AppEnvironment extends EnvironmentBase {
         await this.load(HomeAssistantRegistry),
         await this.load(BridgeStorage),
         await this.load(EntityMappingStorage),
+        await this.load(EntityIdentityStorage),
         await this.load(LockCredentialStorage),
         await this.load(AppSettingsStorage),
         await this.load(BackupService),