@smarthome.exchange/integrations 2.0.0 → 4.0.0

package/ts/integrations/tasmota/tasmota.discovery.ts

@@ -1,7 +1,10 @@
 import { DiscoveryDescriptor } from '../../core/classes.discoverydescriptor.js';
+import * as plugins from '../../plugins.js';
+import { NativeIntegrationOwner, type NativeIntegrationScope } from '../../core/classes.nativeintegrationowner.js';
 import type { IConfigFlow, IConfigFlowContext, IConfigFlowStep, IDiscoveryCandidate, IDiscoveryMatch, IDiscoveryMatcher, IDiscoveryValidator } from '../../core/types.js';
 import { normalizeTasmotaConfig } from './tasmota.config.js';
-import type { IHomeAssistantTasmotaConfig } from './tasmota.types.js';
+import type { IHomeAssistantTasmotaConfig, ITasmotaIntegrationOptions } from './tasmota.types.js';
+import { createTasmotaCredential, tasmotaBrokerIdentity, tasmotaCopy, tasmotaCredentialKey, tasmotaData, tasmotaOptions, tasmotaText } from './tasmota.credentials.js';
 
 class TasmotaManualMatcher implements IDiscoveryMatcher<IDiscoveryCandidate> {
   public readonly id = 'tasmota-selected-device';
@@ -35,8 +38,28 @@ export const createTasmotaDiscoveryDescriptor = (): DiscoveryDescriptor => {
 };
 
 export class TasmotaConfigFlow implements IConfigFlow<IHomeAssistantTasmotaConfig> {
+  private readonly scope: NativeIntegrationScope;
+  private readonly hasResolver: boolean;
+
+  constructor(optionsArg: ITasmotaIntegrationOptions = {}, ownerArg?: NativeIntegrationOwner) {
+    const options = tasmotaOptions(optionsArg);
+    const owner = ownerArg ?? new NativeIntegrationOwner('tasmota', { homeId: options.homeId, capacity: options.capacity });
+    this.scope = owner.createFlowScope();
+    this.hasResolver = options.credentialResolver !== undefined;
+  }
+
+  public destroy(): Promise<void> { return this.scope.close(); }
+  public retryCleanup(): Promise<void> { return this.scope.retryCleanup(); }
+
   public async start(candidateArg: IDiscoveryCandidate, contextArg: IConfigFlowContext): Promise<IConfigFlowStep<IHomeAssistantTasmotaConfig>> {
-    void contextArg;
+    const candidate = tasmotaData(tasmotaCopy(candidateArg), 'Tasmota candidate');
+    const metadata = candidate.metadata === undefined ? undefined : tasmotaData(candidate.metadata, 'Tasmota candidate metadata');
+    const context = this.scope.admit(contextArg);
+    const candidateHost = candidate.host;
+    const candidatePort = candidate.port;
+    const candidateTopic = metadata?.topic;
+    let pending = false;
+    let submitted = false;
     return {
       kind: 'form',
       title: 'Connect a selected Tasmota device',
@@ -45,6 +68,8 @@ export class TasmotaConfigFlow implements IConfigFlow<IHomeAssistantTasmotaConfi
         { name: 'host', label: 'MQTT broker host', type: 'text', required: true },
         { name: 'port', label: 'MQTT broker port', type: 'number' },
         { name: 'useTls', label: 'Use MQTT TLS', type: 'boolean' },
+        { name: 'anonymous', label: 'Use an anonymous broker', type: 'boolean' },
+        { name: 'credentialRef', label: 'Existing broker credential reference', type: 'text' },
         { name: 'username', label: 'Broker username', type: 'text' },
         { name: 'password', label: 'Broker password', type: 'password' },
         { name: 'topic', label: 'Device Topic', type: 'text', required: true },
@@ -53,31 +78,69 @@ export class TasmotaConfigFlow implements IConfigFlow<IHomeAssistantTasmotaConfi
         { name: 'brightness', label: 'Single-channel Dimmer', type: 'boolean' },
       ],
       submit: async (valuesArg) => {
+        if (pending || submitted) return { kind: 'error', error: 'This Tasmota form is already submitting or completed.' };
+        pending = true;
         try {
-          for (const field of ['username', 'password', 'fullTopic']) if (valuesArg[field] !== undefined && typeof valuesArg[field] !== 'string') throw new Error(`${field} must be a string.`);
-          for (const field of ['useTls', 'brightness']) if (valuesArg[field] !== undefined && typeof valuesArg[field] !== 'boolean') throw new Error(`${field} must be boolean.`);
-          const relayCount = valuesArg.relayCount ?? 1;
-          if (typeof relayCount !== 'number' || !Number.isInteger(relayCount) || relayCount < 0 || relayCount > 32) throw new Error('relayCount must be an integer from 0 through 32.');
-          const host = valuesArg.host ?? candidateArg.host;
-          const topic = valuesArg.topic ?? candidateArg.metadata?.topic;
-          if (typeof host !== 'string' || typeof topic !== 'string') throw new Error('Broker host and device topic are required.');
-          const port = valuesArg.port ?? candidateArg.port;
-          if (port !== undefined && (typeof port !== 'number' || !Number.isInteger(port) || port < 1 || port > 65_535)) throw new Error('Broker port must be an integer from 1 through 65535.');
-          const config: IHomeAssistantTasmotaConfig = {
-            broker: {
-              host,
-              port,
-              protocol: valuesArg.useTls === true ? 'mqtts' : 'mqtt',
-              username: typeof valuesArg.username === 'string' ? valuesArg.username : undefined,
-              password: typeof valuesArg.password === 'string' ? valuesArg.password : undefined,
-            },
-            devices: [{ topic, fullTopic: typeof valuesArg.fullTopic === 'string' && valuesArg.fullTopic ? valuesArg.fullTopic : undefined, relays: Array.from({ length: relayCount }, (_, indexArg) => indexArg + 1), brightness: valuesArg.brightness === true }],
-          };
-          normalizeTasmotaConfig(config);
-          return { kind: 'done', title: 'Selected Tasmota device configured', config };
+          const values = tasmotaData(tasmotaCopy(valuesArg), 'Tasmota form');
+          return await this.scope.run(context, context.homeId, async (leaseArg) => {
+            if (Object.keys(values).some((keyArg) => !['homeId', 'host', 'port', 'useTls', 'anonymous', 'credentialRef', 'username', 'password', 'topic', 'fullTopic', 'relayCount', 'brightness'].includes(keyArg))) throw new Error('Tasmota form contains unsupported fields.');
+            if (values.homeId !== undefined && values.homeId !== context.homeId) throw new Error('Tasmota form home conflicts with the admitted host home.');
+            for (const field of ['username', 'password', 'fullTopic', 'credentialRef']) if (values[field] !== undefined && typeof values[field] !== 'string') throw new Error(`${field} must be a string.`);
+            for (const field of ['useTls', 'brightness', 'anonymous']) if (values[field] !== undefined && typeof values[field] !== 'boolean') throw new Error(`${field} must be boolean.`);
+            const relayCount = values.relayCount ?? 1;
+            if (typeof relayCount !== 'number' || !Number.isInteger(relayCount) || relayCount < 0 || relayCount > 32) throw new Error('relayCount must be an integer from 0 through 32.');
+            const host = values.host ?? candidateHost;
+            const topic = values.topic ?? candidateTopic;
+            if (typeof host !== 'string' || typeof topic !== 'string') throw new Error('Broker host and device topic are required.');
+            const port = values.port ?? candidatePort;
+            if (port !== undefined && (typeof port !== 'number' || !Number.isInteger(port) || port < 1 || port > 65_535)) throw new Error('Broker port must be an integer from 1 through 65535.');
+            const secretInput = values.username !== undefined || values.password !== undefined;
+            const anonymous = values.anonymous === true;
+            if (anonymous && (secretInput || values.credentialRef !== undefined)) throw new Error('Anonymous Tasmota mode cannot contain credentials.');
+            if (!anonymous && !secretInput && values.credentialRef === undefined) throw new Error('Select anonymous mode explicitly or provide broker credentials.');
+            if (secretInput && values.credentialRef !== undefined) throw new Error('Provide transient credentials or an existing reference, not both.');
+            const reference = anonymous ? undefined : secretInput ? plugins.crypto.randomUUID() : tasmotaText(values.credentialRef, 'Credential reference', 512);
+            const config: IHomeAssistantTasmotaConfig = {
+              homeId: context.homeId,
+              authentication: reference === undefined ? { mode: 'anonymous' } : { mode: 'credential-reference', credentialRef: reference },
+              broker: {
+                host,
+                port,
+                protocol: values.useTls === true ? 'mqtts' : 'mqtt',
+              },
+              devices: [{ topic, fullTopic: typeof values.fullTopic === 'string' && values.fullTopic ? values.fullTopic : undefined, relays: Array.from({ length: relayCount }, (_, indexArg) => indexArg + 1), brightness: values.brightness === true }],
+            };
+            const normalized = normalizeTasmotaConfig(config);
+            if (!anonymous) {
+              const store = leaseArg.context.configStore;
+              if (secretInput) {
+                if (!store) throw new Error('Transient Tasmota broker credentials require an admitted encrypted config store.');
+                const credential = createTasmotaCredential(tasmotaBrokerIdentity(normalized),
+                  typeof values.username === 'string' ? values.username : undefined,
+                  typeof values.password === 'string' ? values.password : undefined);
+                const key = tasmotaCredentialKey(reference!);
+                let committed = false;
+                let write: Promise<void> = Promise.resolve();
+                leaseArg.own(async () => {
+                  const result = await Promise.allSettled([write]);
+                  if (result[0].status === 'fulfilled' && !committed) {
+                    try { await store.delete(key); }
+                    catch { throw new Error('Tasmota cancelled credential cleanup failed.'); }
+                  }
+                });
+                write = Promise.resolve().then(() => store.create(key, credential));
+                try { await write; }
+                catch { throw new Error('Tasmota encrypted credential persistence failed.'); }
+                leaseArg.assertOpen();
+                committed = true;
+              } else if (!store && !this.hasResolver) throw new Error('Tasmota credential reference requires an explicit credential source.');
+            }
+            submitted = true;
+            return { kind: 'done', title: 'Selected Tasmota device configured', config };
+          });
         } catch (errorArg) {
           return { kind: 'error', error: errorArg instanceof Error ? errorArg.message : 'Invalid Tasmota configuration.' };
-        }
+        } finally { pending = false; }
       },
     };
   }

package/ts/integrations/tasmota/tasmota.mapper.ts

@@ -50,9 +50,9 @@ export class TasmotaMapper {
     return sensors;
   }
 
-  public static device(deviceArg: ITasmotaSelectedDevice, stateArg: ITasmotaDeviceState, connectedArg: boolean): plugins.shxInterfaces.data.IDeviceDefinition {
-    const features: plugins.shxInterfaces.data.IDeviceFeature[] = deviceArg.relays.map((relayArg) => ({ id: `power_${relayArg}`, capability: 'switch', name: `Relay ${relayArg}`, readable: true, writable: true }));
-    if (deviceArg.brightness) features.push({ id: 'brightness', capability: 'light', name: 'Brightness', readable: true, writable: true, unit: '%' });
+  public static device(deviceArg: ITasmotaSelectedDevice, stateArg: ITasmotaDeviceState, connectedArg: boolean, enableControlsArg = false): plugins.shxInterfaces.data.IDeviceDefinition {
+    const features: plugins.shxInterfaces.data.IDeviceFeature[] = deviceArg.relays.map((relayArg) => ({ id: `power_${relayArg}`, capability: 'switch', name: `Relay ${relayArg}`, readable: true, writable: enableControlsArg }));
+    if (deviceArg.brightness) features.push({ id: 'brightness', capability: 'light', name: 'Brightness', readable: true, writable: enableControlsArg, unit: '%' });
     for (const id of Object.keys(stateArg.sensors).sort()) features.push({ id, capability: id.startsWith('sensor_ENERGY/') ? 'energy' : 'sensor', name: id.slice('sensor_'.length).split('/').map(decodeURIComponent).join(' '), readable: true, writable: false });
     const values = { ...stateArg.controls, ...stateArg.sensors };
     return {
@@ -69,12 +69,12 @@ export class TasmotaMapper {
     };
   }
 
-  public static entities(deviceArg: plugins.shxInterfaces.data.IDeviceDefinition): IIntegrationEntity[] {
+  public static entities(deviceArg: plugins.shxInterfaces.data.IDeviceDefinition, homeIdArg: string): IIntegrationEntity[] {
     return deviceArg.features.map((featureArg) => {
       const platform = featureArg.capability === 'switch' ? 'switch' : featureArg.capability === 'light' ? 'light' : 'sensor';
       return {
-        id: `${platform}.${encodeURIComponent(deviceArg.id)}.${encodeURIComponent(featureArg.id)}`,
-        uniqueId: `${deviceArg.id}:${featureArg.id}`,
+        id: `${encodeURIComponent(homeIdArg)}:${platform}.${encodeURIComponent(JSON.stringify([deviceArg.id, featureArg.id]))}`,
+        uniqueId: JSON.stringify([homeIdArg, deviceArg.id, featureArg.id]),
         integrationDomain: 'tasmota',
         deviceId: deviceArg.id,
         platform,

package/ts/integrations/tasmota/tasmota.types.ts

@@ -1,4 +1,41 @@
 import type { IMqttConfig } from '../mqtt/mqtt.types.js';
+import type { INativeIntegrationOwnerOptions } from '../../core/classes.nativeintegrationowner.js';
+
+export interface ITasmotaBrokerIdentity {
+  readonly host: string;
+  readonly port: number;
+  readonly protocol: 'mqtt' | 'mqtts';
+}
+
+export interface ITasmotaCredential extends ITasmotaBrokerIdentity {
+  readonly version: 1;
+  readonly username?: string;
+  readonly password?: string;
+  readonly ca?: string;
+  readonly cert?: string;
+  readonly key?: string;
+  readonly servername?: string;
+}
+
+export interface ITasmotaCredentialRequest {
+  readonly homeId: string;
+  readonly credentialRef: string;
+  readonly broker: ITasmotaBrokerIdentity;
+  readonly signal: AbortSignal;
+  /** Absolute deadline on performance.now(), not wall-clock time. */
+  readonly deadlineMonotonicMs: number;
+}
+
+export type TTasmotaCredentialResolver = (requestArg: ITasmotaCredentialRequest) => Promise<ITasmotaCredential>;
+
+export interface ITasmotaIntegrationOptions extends INativeIntegrationOwnerOptions {
+  /** Runtime-only embedding-owner permission. Defaults to false. */
+  readonly enableControls?: boolean;
+  readonly credentialResolver?: TTasmotaCredentialResolver;
+}
+
+export type TTasmotaAuthentication = { readonly mode: 'anonymous' }
+  | { readonly mode: 'credential-reference'; readonly credentialRef: string };
 
 export interface ITasmotaDeviceConfig {
   topic: string;
@@ -14,7 +51,9 @@ export interface ITasmotaDeviceConfig {
 }
 
 export interface IHomeAssistantTasmotaConfig {
-  broker: IMqttConfig & { host: string };
+  readonly homeId: string;
+  broker: Omit<IMqttConfig, 'username' | 'password'> & { host: string };
+  readonly authentication: TTasmotaAuthentication;
   devices: ITasmotaDeviceConfig[];
   initialSnapshotTimeoutMs?: number;
 }
@@ -34,7 +73,9 @@ export interface ITasmotaSelectedDevice {
 }
 
 export interface ITasmotaConfig {
-  broker: IMqttConfig & { host: string };
+  readonly homeId: string;
+  readonly authentication: TTasmotaAuthentication;
+  broker: Omit<IMqttConfig, 'username' | 'password'> & { host: string };
   devices: ITasmotaSelectedDevice[];
   initialSnapshotTimeoutMs: number;
 }

package/ts/integrations/tuya/readme.md

@@ -1,7 +1,7 @@
 # Tuya local protocol 3.4
 
 `TuyaIntegration` and the existing `HomeAssistantTuyaIntegration` export provide a
-native local runtime through published `@ecobridge.xyz/devicemanager` 4.2.0.
+native local runtime through published `@ecobridge.xyz/devicemanager` 4.11.1.
 Setup requires an explicit home, device ID, literal private/link-local/loopback
 IPv4 endpoint, local key and this product's verified datapoint schema. Discovery
 has no broadcast probes and makes no claim to locate devices or obtain credentials.
@@ -33,11 +33,12 @@ const config: IHomeAssistantTuyaConfig = {
     { id: 108, name: 'Temperature', kind: 'sensor', valueType: 'integer', scale: 1, unit: '°C' },
   ],
 };
-const integration = new TuyaIntegration();
+const integration = new TuyaIntegration({ homeId: 'home-one' });
+const context = Object.freeze({ homeId: 'home-one', configStore: store });
 // One explicit provisioning action stores configuration and the opaque 16-byte
 // local key together, encrypted under the caller's key provider.
-await integration.provisionLocalKey(config, configuredLocalKeyBytes, { configStore: store });
-const runtime = await integration.setup(config, { configStore: store });
+await integration.provisionLocalKey(config, configuredLocalKeyBytes, context);
+const runtime = await integration.setup(config, context);
 try {
   const [device] = await runtime.devices();
   const power = device.features.find((feature) => feature.id === 'dp_7');
@@ -52,6 +53,14 @@ try {
 }
 ```
 
+The host must independently select `context.homeId` for provisioning and setup.
+It must match the configuration home and the actual store scope; it is never
+inferred from either. An optional constructor `homeId` constrains the instance.
+Otherwise, the first valid synchronous admission fixes its home even if subsequent
+I/O fails. Configuration, context fields and local-key bytes are captured before
+asynchronous work. Accessors and overridden store-scope methods cannot grant
+admission. The host still owns authenticated access to the selected home.
+
 The store must be an actual `NoSqlConfigStore` scoped to the exact configured home
 and `tuya` domain. Generic stores are rejected. Configuration and credentials use
 `device:<configured device ID>` in that encrypted scope; setup rejects a different
@@ -85,14 +94,38 @@ arrive. Failures retain `effectOutcome: 'not-sent'`, `'rejected'` or `'indetermi
 a transmitted effect with a lost/late response may already have happened. There is
 no retry, retransmission or reconnect. Lifetime/setup cancellation and feature-write
 signals are supported. `destroy()` is permanent, idempotent and drains setup and
-protocol operations; use a new integration for a new lifetime. Cached reads after
-shutdown remain marked unavailable with their original report timestamps.
+protocol operations and admitted asynchronous subscriber continuations. A fulfilled
+provisioning write remains fulfilled if cancellation or close arrives during its
+persistence; close joins the actual write result and never replays it. Setup and
+provisioning are reserved before store or protocol callbacks run. Destruction
+publishes one stable close promise before abort callbacks run. Caller cancellation
+also closes promoted runtime ownership and releases its slot after cleanup.
+Use a new integration for a new lifetime. Cached reads after
+shutdown remain unavailable and read-only with their original report timestamps.
 
-Subscriptions are bounded to 128 listeners, abortable and explicitly removable.
-Handlers must not block. Asynchronous handler work is caller-owned; handler failures
-are reported through the supplied logger using a generic credential-free message.
+Subscriptions are bounded to 128 listeners and 128 outstanding callback
+continuations, abortable and explicitly removable. Handlers must not block or
+await destruction of their own runtime: destruction joins their continuation.
+Returned promises and thenables are owned and joined even after listener removal.
+Callback failures are retained through cleanup and logged with a generic,
+credential-free message. Overflow closes the runtime and retains the failure.
 All listeners are removed during destruction.
-One integration owns at most 32 simultaneous setup/provisioning/runtime lifetimes.
+
+The shared native owner accounts for pending setup/provisioning operations,
+promoted runtimes and retained failed cleanup. Its default limit is 16; the optional
+constructor `capacity` selects a positive safe-integer limit. A failed cleanup
+retains its capacity slot and rejects destruction. `integration.retryCleanup()`
+retries only failed cleanup handles and explicitly acknowledges already-drained
+subscriber failures; it never reruns callbacks, provisioning, queries or controls,
+and never reopens a session. It does not change the original rejected close promise.
+A resource whose owning cleanup still rejects remains retained.
+
+Per-DP provisioned `read-write` access continues to grant control. There is no
+additional host control-permission API and no automatic preflight or post-write
+readback. Those public-contract changes require a separate product decision, as
+does a config flow. Protocol authentication proves possession of the local key;
+identity fields are checked when present, but this is not independent hardware
+attestation. Firmware qualification remains separate from fixture verification.
 
 Other protocol versions, cloud-only and sleeping devices, gateway children, BLE,
 Zigbee, raw/bitmap/enum mappings and arbitrary actions are unsupported. The shared
@@ -101,6 +134,15 @@ device protocol union currently has no Tuya member, so the generic device report
 loopback fixture tests cover the implementation; qualification against real product
 firmware requires separately authorized hardware access.
 
+Fixture qualification uses `pnpm exec tstest test/tuya/ --verbose --logfile --timeout 60`:
+`test.tuya.node.ts` contains 28 encrypted persistence/protocol cases and
+`test.tuya.owner.node.ts` adds 22 admission, reentry, cancellation, capacity,
+accepted-persistence, retained-cleanup and callback-continuation regressions.
+The 50-case suite passes with no device or cloud account. Strict domain/test checks
+use `strict: true`, `noImplicitAny: true` and `skipLibCheck: false`; production
+build and the complete test type check are also required. This fixture evidence
+does not establish physical acceptance for a particular product or firmware.
+
 Product types and permissions follow the vendor's [DP Model and Control Protocol](https://developer.tuya.com/en/docs/iot-device-dev/TuyaOS-iot_abi_dp_ctrl?id=Kcoglhn5r7ajr).
 LAN framing is implemented by the owning dependency, whose public API and wire
 contract are documented in its [readme](https://code.foss.global/ecobridge.xyz/devicemanager).

package/ts/integrations/tuya/tuya.classes.integration.ts

@@ -1,10 +1,11 @@
 import * as plugins from '../../plugins.js';
 import { BaseIntegration } from '../../core/classes.baseintegration.js';
+import { NativeIntegrationOwner } from '../../core/classes.nativeintegrationowner.js';
 import { DiscoveryDescriptor } from '../../core/classes.discoverydescriptor.js';
 import type { IIntegrationRuntime, IIntegrationSetupContext } from '../../core/types.js';
 import { TuyaRuntime } from './tuya.classes.runtime.js';
-import type { IHomeAssistantTuyaConfig, ITuyaStoredConfiguration } from './tuya.types.js';
-import { normalizeTuyaConfig, scopedTuyaStore, tuyaCredentialId, tuyaKeys, tuyaRecord } from './tuya.validation.js';
+import type { IHomeAssistantTuyaConfig, ITuyaIntegrationOptions, ITuyaStoredConfiguration } from './tuya.types.js';
+import { normalizeTuyaConfig, tuyaSetupContext, tuyaCredentialId, tuyaKeys, tuyaRecord } from './tuya.validation.js';
 
 export class TuyaIntegration extends BaseIntegration<IHomeAssistantTuyaConfig> {
   public readonly domain = 'tuya';
@@ -12,118 +13,88 @@ export class TuyaIntegration extends BaseIntegration<IHomeAssistantTuyaConfig> {
   public readonly status = 'control-runtime' as const;
   public readonly discoveryDescriptor = new DiscoveryDescriptor({ integrationDomain: 'tuya', displayName: 'Tuya 3.4 local device' });
   public readonly metadata = Object.freeze({ source: 'native-typescript', integrationType: 'device', iotClass: 'local_push', protocolVersion: '3.4' });
-  readonly #setups = new Set<Promise<unknown>>();
-  readonly #controllers = new Set<AbortController>();
-  readonly #runtimes = new Set<TuyaRuntime>();
-  #destroyed = false;
-  #destroy?: Promise<void>;
+  readonly #owner: NativeIntegrationOwner;
+
+  constructor(optionsArg: ITuyaIntegrationOptions = {}) {
+    super();
+    this.#owner = new NativeIntegrationOwner(this.domain, optionsArg);
+  }
 
   public provisionLocalKey(configArg: IHomeAssistantTuyaConfig, localKeyArg: Uint8Array, contextArg: IIntegrationSetupContext): Promise<void> {
-    this.#assertOpen();
-    this.#assertCapacity();
     const config = normalizeTuyaConfig(configArg);
-    const store = scopedTuyaStore(config, contextArg);
+    const context = tuyaSetupContext(contextArg);
     if (!(localKeyArg instanceof Uint8Array) || localKeyArg.byteLength !== 16) throw new TypeError('Tuya local key must contain exactly 16 opaque bytes.');
     const copy = Buffer.from(localKeyArg);
-    const controller = new AbortController();
-    this.#controllers.add(controller);
-    const signal = contextArg.abortSignal ? AbortSignal.any([controller.signal, contextArg.abortSignal]) : controller.signal;
-    const operation = (async () => {
-      try {
-        signal.throwIfAborted();
-        await store.initialize({ signal });
-        this.#assertOpen();
-        signal.throwIfAborted();
+    try {
+      return this.#owner.runOperation(context, config.homeId, async (leaseArg) => {
+        const store = leaseArg.context.configStore!;
+        await store.initialize({ signal: leaseArg.signal });
+        leaseArg.assertOpen();
         await store.set<ITuyaStoredConfiguration>(tuyaCredentialId(config.deviceId), { version: 1, config, localKey: copy.toString('base64') });
-        this.#assertOpen();
-        signal.throwIfAborted();
-      } finally { copy.fill(0); this.#controllers.delete(controller); }
-    })();
-    return this.#track(operation);
+        // A fulfilled admitted write stays fulfilled even if close/cancellation arrives during persistence.
+      }).finally(() => copy.fill(0));
+    } catch (errorArg) { copy.fill(0); throw errorArg; }
   }
 
   public setup(configArg: IHomeAssistantTuyaConfig, contextArg: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
-    this.#assertOpen();
-    this.#assertCapacity();
     const config = normalizeTuyaConfig(configArg);
-    const store = scopedTuyaStore(config, contextArg);
-    const controller = new AbortController();
-    this.#controllers.add(controller);
-    const signal = contextArg.abortSignal ? AbortSignal.any([controller.signal, contextArg.abortSignal]) : controller.signal;
-    const operation = (async () => {
-      let protocol: plugins.ecobridgeDeviceManager.TuyaProtocol | undefined;
+    const context = tuyaSetupContext(contextArg);
+    return this.#owner.runSetup(context, config.homeId, async (leaseArg) => {
+      const store = leaseArg.context.configStore!;
+      const signal = leaseArg.signal;
+      await store.initialize({ signal });
+      leaseArg.assertOpen();
+      const stored = tuyaRecord(await store.get<unknown>(tuyaCredentialId(config.deviceId)), 'stored configuration');
+      tuyaKeys(stored, ['version', 'config', 'localKey']);
+      if (stored.version !== 1 || JSON.stringify(normalizeTuyaConfig(stored.config)) !== JSON.stringify(config)) {
+        throw new TypeError('Tuya configuration does not match its encrypted provisioned configuration.');
+      }
+      if (typeof stored.localKey !== 'string' || stored.localKey.length !== 24) throw new TypeError('Tuya stored local key is invalid.');
+      const key = Buffer.from(stored.localKey, 'base64');
+      let protocol: plugins.ecobridgeDeviceManager.TuyaProtocol;
+      let runtime: TuyaRuntime | undefined;
       let unsubscribeAdmission: (() => void) | undefined;
+      let cleanupAttempted = false;
       try {
-        signal.throwIfAborted();
-        await store.initialize({ signal });
-        signal.throwIfAborted();
-        const stored = tuyaRecord(await store.get<unknown>(tuyaCredentialId(config.deviceId)), 'stored configuration');
-        tuyaKeys(stored, ['version', 'config', 'localKey']);
-        if (stored.version !== 1 || JSON.stringify(normalizeTuyaConfig(stored.config)) !== JSON.stringify(config)) {
-          throw new TypeError('Tuya configuration does not match its encrypted provisioned configuration.');
-        }
-        if (typeof stored.localKey !== 'string' || stored.localKey.length !== 24) throw new TypeError('Tuya stored local key is invalid.');
-        const key = Buffer.from(stored.localKey, 'base64');
-        try {
-          if (key.byteLength !== 16 || key.toString('base64') !== stored.localKey) throw new TypeError('Tuya stored local key is invalid.');
-          signal.throwIfAborted();
-          protocol = new plugins.ecobridgeDeviceManager.TuyaProtocol({
-            deviceId: config.deviceId, localKey: key, host: config.host, port: config.port, version: config.version,
-            connectTimeoutMs: config.connectTimeoutMs, requestTimeoutMs: config.requestTimeoutMs,
-            heartbeatIntervalMs: config.heartbeatIntervalMs, abortSignal: signal,
-          });
-        } finally { key.fill(0); }
-        const reports: plugins.ecobridgeDeviceManager.ITuyaDatapointReport[] = [];
-        let admissionOverflow = false;
-        unsubscribeAdmission = protocol.subscribe((reportArg) => {
-          if (reports.length >= 128) { admissionOverflow = true; controller.abort(); }
-          else reports.push(reportArg);
+        if (key.byteLength !== 16 || key.toString('base64') !== stored.localKey) throw new TypeError('Tuya stored local key is invalid.');
+        leaseArg.assertOpen();
+        protocol = new plugins.ecobridgeDeviceManager.TuyaProtocol({
+          deviceId: config.deviceId, localKey: key, host: config.host, port: config.port, version: config.version,
+          connectTimeoutMs: config.connectTimeoutMs, requestTimeoutMs: config.requestTimeoutMs,
+          heartbeatIntervalMs: config.heartbeatIntervalMs, abortSignal: signal,
         });
-        await protocol.connect(signal);
-        await protocol.queryDatapoints(signal);
-        if (admissionOverflow) throw new Error('Tuya admission report capacity exceeded.');
-        signal.throwIfAborted();
-        this.#assertOpen();
-        unsubscribeAdmission();
-        unsubscribeAdmission = undefined;
-        const runtime = new TuyaRuntime(config, protocol, reports, () => {
-          this.#runtimes.delete(runtime);
-          this.#controllers.delete(controller);
-        }, contextArg.logger);
-        this.#runtimes.add(runtime);
-        return runtime;
-      } catch (errorArg) {
-        controller.abort();
-        unsubscribeAdmission?.();
-        await protocol?.close();
-        this.#controllers.delete(controller);
-        throw errorArg;
-      }
-    })();
-    return this.#track(operation);
-  }
-
-  public destroy(): Promise<void> {
-    if (this.#destroy) return this.#destroy;
-    this.#destroyed = true;
-    for (const controller of this.#controllers) controller.abort();
-    this.#destroy = (async () => {
-      await Promise.allSettled([...this.#setups]);
-      await Promise.all([...this.#runtimes].map((runtimeArg) => runtimeArg.destroy()));
-      this.#controllers.clear();
-    })();
-    return this.#destroy;
+        // One composite handle transfers protocol and callback cleanup together to the runtime.
+        leaseArg.own(async () => {
+          const retry = cleanupAttempted;
+          cleanupAttempted = true;
+          unsubscribeAdmission?.();
+          unsubscribeAdmission = undefined;
+          if (runtime) await runtime.closeOwnedResources(retry);
+          else await protocol.close();
+        });
+      } finally { key.fill(0); }
+      const reports: plugins.ecobridgeDeviceManager.ITuyaDatapointReport[] = [];
+      let admissionOverflow = false;
+      unsubscribeAdmission = protocol.subscribe((reportArg) => {
+        if (reports.length >= 128) { admissionOverflow = true; void leaseArg.close().catch(() => undefined); }
+        else reports.push(reportArg);
+      });
+      await protocol.connect(signal);
+      await protocol.queryDatapoints(signal);
+      if (admissionOverflow) throw new Error('Tuya admission report capacity exceeded.');
+      leaseArg.assertOpen();
+      unsubscribeAdmission();
+      unsubscribeAdmission = undefined;
+      runtime = new TuyaRuntime(config, protocol, reports, leaseArg);
+      leaseArg.promoteToRuntime();
+      return runtime;
+    });
   }
 
-  #assertOpen(): void { if (this.#destroyed) throw new Error('Tuya integration is permanently destroyed.'); }
+  public destroy(): Promise<void> { return this.#owner.close(); }
 
-  #assertCapacity(): void { if (this.#controllers.size >= 32) throw new Error('Tuya integration lifetime capacity reached.'); }
-
-  #track<TResult>(operationArg: Promise<TResult>): Promise<TResult> {
-    this.#setups.add(operationArg);
-    void operationArg.then(() => this.#setups.delete(operationArg), () => this.#setups.delete(operationArg));
-    return operationArg;
-  }
+  /** Retry retained cleanup only; never reopen a session or replay an accepted operation. */
+  public retryCleanup(): Promise<void> { return this.#owner.retryCleanup(); }
 }
 
 export class HomeAssistantTuyaIntegration extends TuyaIntegration {}