@smarthome.exchange/integrations 2.0.0 → 4.0.0

package/ts/integrations/mqtt/mqtt.classes.client.ts

@@ -1,6 +1,6 @@
 import * as plugins from '../../plugins.js';
 import { MqttMapper } from './mqtt.mapper.js';
-import type { IMqttConfig, IMqttConnectionState, IMqttMessage, IMqttPublishOptions, IMqttSnapshot } from './mqtt.types.js';
+import type { IMqttConfig, IMqttConnectionState, IMqttMessage, IMqttPublishOptions, IMqttSnapshot, IMqttTransportCredentials } from './mqtt.types.js';
 
 type TMqttMessageHandler = (messageArg: IMqttMessage) => void;
 type TMqttStateHandler = (stateArg: IMqttConnectionState) => void;
@@ -10,6 +10,11 @@ interface IMqttSubscription {
   handler?: TMqttMessageHandler;
 }
 
+interface IMqttTransportCleanup {
+  promise?: Promise<void>;
+  failed: boolean;
+}
+
 export const mqttTopicMatches = (filterArg: string, topicArg: string): boolean => {
   if (topicArg.startsWith('$') && !filterArg.startsWith('$')) return false;
   const filter = filterArg.split('/');
@@ -37,17 +42,23 @@ export class MqttClient {
   private startPromise?: Promise<void>;
   private destroyPromise?: Promise<void>;
   private cleanupPromise = Promise.resolve();
+  private retryPromise?: Promise<void>;
+  private readonly transportCleanups = new Map<plugins.mqtt.MqttClient, IMqttTransportCleanup>();
   private destroyed = false;
   private ready = false;
   private hasStarted = false;
   private generation = 0;
+  private currentGeneration?: number;
+  private currentStream?: plugins.mqtt.MqttClient['stream'];
   private readonly subscriptions = new Set<IMqttSubscription>();
   private readonly messageHandlers = new Set<TMqttMessageHandler>();
   private readonly stateHandlers = new Set<TMqttStateHandler>();
   private readonly messages = new Map<string, IMqttMessage>();
+  private readonly currentMessageTopics = new Set<string>();
   private readonly persistentTopics = new Set<string>();
   private readonly brokerTopics = new Set<string>();
   private readonly pendingOperations = new Set<(errorArg: Error) => void>();
+  private readonly publications = new Map<plugins.mqtt.MqttClient, number>();
   private topicSync?: Promise<void>;
   private topicSyncRequested = false;
   private bufferedBytes = 0;
@@ -57,8 +68,9 @@ export class MqttClient {
   private readonly maxPayloadBytes: number;
   private readonly maxBufferedBytes: number;
 
-  constructor(private readonly config: IMqttConfig) {
+  constructor(private readonly config: IMqttConfig, private readonly credentials: IMqttTransportCredentials = {}) {
     this.config = structuredClone(config);
+    this.credentials = structuredClone(credentials);
     this.connectTimeoutMs = this.integerOption(config.connectTimeoutMs, 7000, 1, 2147483647);
     this.operationTimeoutMs = this.integerOption(config.operationTimeoutMs, 7000, 1, 2147483647);
     this.maxMessageTopics = this.integerOption(config.maxMessageTopics, 4096, 1, 100000);
@@ -73,6 +85,13 @@ export class MqttClient {
       validateMqttTopic(topic, true);
       this.persistentTopics.add(topic);
     }
+    if (config.mode === 'selected-topics') {
+      for (const mapping of config.mappings ?? []) {
+        for (const topic of [mapping.stateTopic, ...(mapping.availabilityTopic ? [mapping.availabilityTopic] : [])]) {
+          validateMqttTopic(topic); this.persistentTopics.add(topic);
+        }
+      }
+    }
     if (config.discovery !== false) {
       const prefix = config.discoveryPrefix || 'homeassistant';
       validateMqttTopic(prefix);
@@ -106,6 +125,14 @@ export class MqttClient {
     return MqttMapper.toSnapshot({ ...this.config, retainedMessages: [], discoveryMessages: [] }, this.connected, [...this.messages.values()]);
   }
 
+  /** Live broker observations only, including arrivals before readiness; never starts a transport. */
+  public getCurrentSnapshot(): IMqttMessage[] {
+    if (this.destroyed || this.currentGeneration !== this.generation || !this.client?.connected ||
+      this.client.stream !== this.currentStream || this.currentStream?.destroyed) return [];
+    return [...this.messages.values()].filter((messageArg) => this.currentMessageTopics.has(messageArg.topic))
+      .map((messageArg) => structuredClone(messageArg));
+  }
+
   public async start(abortSignalArg?: AbortSignal): Promise<void> {
     this.throwIfAborted(abortSignalArg);
     if (this.destroyed) throw new Error('MQTT client has been destroyed.');
@@ -144,13 +171,18 @@ export class MqttClient {
       if (packetArg.cmd === 'publish' && packetArg.payload === payload) packetId = packetArg.messageId;
     };
     client.on('packetsend', observePacket);
+    this.publications.set(client, (this.publications.get(client) ?? 0) + 1);
     try {
       await this.bounded(client.publishAsync(optionsArg.topic, payload, {
         qos: optionsArg.qos ?? 0, retain: optionsArg.retain ?? false,
       }), this.operationTimeoutMs, abortSignalArg, () => {
         if (packetId !== undefined && optionsArg.qos) client.removeOutgoingMessage(packetId);
       });
-    } finally { client.removeListener('packetsend', observePacket); }
+    } finally {
+      client.removeListener('packetsend', observePacket);
+      const remaining = (this.publications.get(client) ?? 1) - 1;
+      if (remaining) this.publications.set(client, remaining); else this.publications.delete(client);
+    }
   }
 
   public async subscribe(topicArg: string, handlerArg?: TMqttMessageHandler, abortSignalArg?: AbortSignal): Promise<() => Promise<void>> {
@@ -175,10 +207,35 @@ export class MqttClient {
   }
 
   public destroy(): Promise<void> {
-    if (!this.destroyPromise) this.destroyPromise = this.destroyConnection();
+    if (!this.destroyPromise) {
+      this.destroyed = true;
+      this.clearCurrentGeneration();
+      this.destroyPromise = Promise.resolve().then(() => this.destroyConnection());
+    }
     return this.destroyPromise;
   }
 
+  /** Retry retained close handles only; this never admits a connection or replays application effects. */
+  public retryCleanup(): Promise<void> {
+    if (!this.destroyPromise) return this.destroy();
+    if (!this.retryPromise) {
+      const retry = Promise.resolve().then(async () => {
+        await this.destroyPromise?.then(() => undefined, () => undefined);
+        const cleanup = [...this.transportCleanups].filter(([, recordArg]) => recordArg.failed).map(([clientArg, recordArg]) => {
+          recordArg.promise = undefined;
+          recordArg.failed = false;
+          return this.closeClient(clientArg);
+        });
+        const results = await Promise.allSettled(cleanup);
+        const failures = results.flatMap((result) => result.status === 'rejected' ? [result.reason as unknown] : []);
+        if (failures.length) throw new AggregateError(failures, 'MQTT retained transport cleanup failed.');
+      });
+      this.retryPromise = retry;
+      void retry.then(() => { this.retryPromise = undefined; }, () => { this.retryPromise = undefined; });
+    }
+    return this.retryPromise;
+  }
+
   private async startConnection(): Promise<void> {
     let client = this.client;
     if (!client) {
@@ -191,6 +248,7 @@ export class MqttClient {
         protocolVersion: 4,
         clientId: this.config.clientId || 'shx-' + plugins.crypto.randomBytes(8).toString('hex'),
         username: this.config.username, password: this.config.password,
+        ...this.credentials,
         clean: this.config.clean ?? true,
         keepalive: this.config.keepalive ?? 60,
         rejectUnauthorized: this.config.rejectUnauthorized !== false,
@@ -202,9 +260,21 @@ export class MqttClient {
       });
       this.client = client;
       const ownedClient = client;
+      const receivedGenerations = new WeakMap<plugins.mqtt.IPublishPacket, number>();
+      client.on('packetreceive', (packetArg) => {
+        if (packetArg.cmd !== 'publish' || this.client !== ownedClient || this.destroyed ||
+          this.currentGeneration !== this.generation || !ownedClient.connected ||
+          ownedClient.stream !== this.currentStream || this.currentStream?.destroyed) return;
+        // MQTT.js delivers the same packet through message, including its default QoS 2 store.
+        if (!receivedGenerations.has(packetArg)) receivedGenerations.set(packetArg, this.generation);
+      });
       client.on('connect', () => {
+        if (this.client !== ownedClient || this.destroyed || !ownedClient.connected || ownedClient.stream.destroyed) return;
+        this.clearCurrentGeneration();
         this.brokerTopics.clear();
         const generation = ++this.generation;
+        this.currentGeneration = generation;
+        this.currentStream = ownedClient.stream;
         void this.bounded(this.initializeConnection(ownedClient), this.operationTimeoutMs).then(() => {
           if (this.client !== ownedClient || generation !== this.generation || !ownedClient.connected) return;
           this.ready = true;
@@ -214,7 +284,9 @@ export class MqttClient {
         });
       });
       client.on('message', (topicArg, payloadArg, packetArg) => {
-        if (this.client !== ownedClient) return;
+        if (this.client !== ownedClient || this.destroyed || this.currentGeneration !== this.generation ||
+          receivedGenerations.get(packetArg) !== this.currentGeneration || !ownedClient.connected ||
+          ownedClient.stream !== this.currentStream || this.currentStream?.destroyed) return;
         try {
           this.handleMessage({ topic: topicArg, payload: payloadArg.toString('utf8'), qos: packetArg.qos, retain: packetArg.retain, timestamp: Date.now() });
         } catch (error) { void this.failConnection(this.asError(error), ownedClient); }
@@ -222,15 +294,22 @@ export class MqttClient {
       client.on('error', (errorArg) => {
         if (this.client === ownedClient) {
           this.ready = false;
-          this.emitState({ connected: false, error: errorArg });
+          this.generation++;
+          this.clearCurrentGeneration();
+          try { this.emitState({ connected: false, error: errorArg }); }
+          catch (error) { void this.failConnection(this.asError(error), ownedClient); }
         }
       });
       client.on('close', () => {
         if (this.client !== ownedClient) return;
         this.ready = false;
         this.generation++;
+        this.clearCurrentGeneration();
         this.brokerTopics.clear();
-        this.emitState({ connected: false });
+        try { this.emitState({ connected: false }); }
+        catch (error) { void this.failConnection(this.asError(error), ownedClient); }
+        // A new connection must never replay an unacknowledged application effect.
+        if (this.publications.has(ownedClient)) void this.failConnection(new Error('MQTT publication lost its connection before acknowledgement.'), ownedClient);
       });
     }
     if (this.connected) return;
@@ -313,14 +392,20 @@ export class MqttClient {
   }
 
   private handleMessage(messageArg: IMqttMessage): void {
+    if (this.config.mode === 'selected-topics' && !this.persistentTopics.has(messageArg.topic)) return;
     this.storeMessage(messageArg);
+    this.currentMessageTopics.add(messageArg.topic);
     if (this.config.discovery !== false && messageArg.topic.endsWith('/config') && mqttTopicMatches((this.config.discoveryPrefix || 'homeassistant') + '/#', messageArg.topic)) {
       void this.synchronizeTopics();
     }
+    const failures: unknown[] = [];
     for (const subscription of this.subscriptions) {
-      if (subscription.handler && mqttTopicMatches(subscription.topic, messageArg.topic)) subscription.handler(messageArg);
+      if (subscription.handler && mqttTopicMatches(subscription.topic, messageArg.topic)) {
+        try { subscription.handler(messageArg); } catch (error) { failures.push(error); }
+      }
     }
-    for (const handler of this.messageHandlers) handler(messageArg);
+    for (const handler of this.messageHandlers) { try { handler(messageArg); } catch (error) { failures.push(error); } }
+    if (failures.length) throw new AggregateError(failures, 'MQTT message callbacks failed.');
   }
 
   private storeMessage(messageArg: IMqttMessage): void {
@@ -337,6 +422,7 @@ export class MqttClient {
   }
 
   private removeMessage(topicArg: string): void {
+    this.currentMessageTopics.delete(topicArg);
     const message = this.messages.get(topicArg);
     if (message) {
       this.bufferedBytes -= this.payloadBuffer(message.payload).length + Buffer.byteLength(topicArg);
@@ -344,31 +430,47 @@ export class MqttClient {
     }
   }
 
+  private clearCurrentGeneration(): void {
+    this.currentGeneration = undefined;
+    this.currentStream = undefined;
+    this.currentMessageTopics.clear();
+  }
+
   private async destroyConnection(): Promise<void> {
     this.destroyed = true;
     this.ready = false;
+    this.clearCurrentGeneration();
     const client = this.client;
     this.client = undefined;
     this.rejectOperations(new Error('MQTT client has been destroyed.'));
-    this.emitState({ connected: false });
+    const stateHandlers = [...this.stateHandlers];
+    const notify = Promise.resolve().then(() => this.emitState({ connected: false }, stateHandlers));
     this.subscriptions.clear();
     this.messageHandlers.clear();
     this.stateHandlers.clear();
     this.messages.clear();
     this.bufferedBytes = 0;
     this.brokerTopics.clear();
-    if (client) await this.closeClient(client);
-    await this.cleanupPromise;
+    const results = await Promise.allSettled([notify, ...(client ? [this.closeClient(client)] : []), this.cleanupPromise,
+      ...(this.startPromise ? [this.startPromise.catch(() => undefined)] : []), ...(this.topicSync ? [this.topicSync.catch(() => undefined)] : [])]);
+    const failures = results.flatMap((result) => result.status === 'rejected' ? [result.reason as unknown] : []);
+    if (failures.length) throw new AggregateError(failures, 'MQTT client cleanup failed.');
   }
 
   private failConnection(errorArg: Error, clientArg: plugins.mqtt.MqttClient): Promise<void> {
     if (this.client !== clientArg) return this.cleanupPromise;
     this.ready = false;
     this.generation++;
+    this.clearCurrentGeneration();
     this.client = undefined;
     this.brokerTopics.clear();
-    this.emitState({ connected: false, error: errorArg });
-    const cleanup = this.closeClient(clientArg);
+    const cleanup = Promise.resolve().then(async () => {
+      const results = await Promise.allSettled([
+        Promise.resolve().then(() => this.emitState({ connected: false, error: errorArg })), this.closeClient(clientArg),
+      ]);
+      const failures = results.flatMap((result) => result.status === 'rejected' ? [result.reason as unknown] : []);
+      if (failures.length) throw new AggregateError(failures, 'MQTT cancellation cleanup failed.');
+    });
     this.cleanupPromise = cleanup;
     void cleanup.then(() => this.rejectOperations(errorArg), (error: unknown) => {
       this.rejectOperations(new AggregateError([errorArg, error], 'MQTT cancellation cleanup failed.'));
@@ -376,10 +478,23 @@ export class MqttClient {
     return cleanup;
   }
 
-  private async closeClient(clientArg: plugins.mqtt.MqttClient): Promise<void> {
+  private closeClient(clientArg: plugins.mqtt.MqttClient): Promise<void> {
+    let record = this.transportCleanups.get(clientArg);
+    if (!record) { record = { failed: false }; this.transportCleanups.set(clientArg, record); }
+    if (!record.promise) {
+      const captured = record;
+      record.promise = Promise.resolve().then(() => this.performClientClose(clientArg)).then(() => {
+        this.transportCleanups.delete(clientArg);
+      }, (error: unknown) => { captured.failed = true; throw error; });
+    }
+    return record.promise;
+  }
+
+  private async performClientClose(clientArg: plugins.mqtt.MqttClient): Promise<void> {
     const closed = clientArg.stream.closed ? Promise.resolve() : new Promise<void>((resolve) => clientArg.once('close', resolve));
-    await clientArg.endAsync(true);
-    await closed;
+    const results = await Promise.allSettled([clientArg.endAsync(true), closed]);
+    const failures = results.flatMap((result) => result.status === 'rejected' ? [result.reason as unknown] : []);
+    if (failures.length) throw new AggregateError(failures, 'MQTT transport cleanup failed.');
   }
 
   private bounded<TValue>(promiseArg: Promise<TValue>, timeoutMsArg: number, abortSignalArg?: AbortSignal, cancelArg?: () => void): Promise<TValue> {
@@ -419,8 +534,10 @@ export class MqttClient {
     this.pendingOperations.clear();
   }
 
-  private emitState(stateArg: IMqttConnectionState): void {
-    for (const handler of this.stateHandlers) handler(stateArg);
+  private emitState(stateArg: IMqttConnectionState, handlersArg: Iterable<TMqttStateHandler> = this.stateHandlers): void {
+    const failures: unknown[] = [];
+    for (const handler of handlersArg) { try { handler(stateArg); } catch (error) { failures.push(error); } }
+    if (failures.length) throw new AggregateError(failures, 'MQTT connection callbacks failed.');
   }
 
   private requireClient(): plugins.mqtt.MqttClient {

package/ts/integrations/mqtt/mqtt.classes.configflow.ts

@@ -1,48 +1,61 @@
+import { NativeIntegrationOwner, type NativeIntegrationScope } from '../../core/classes.nativeintegrationowner.js';
+import type { INativeAdmissionContext } from '../../core/classes.nativehomeadmission.js';
 import type { IConfigFlow, IConfigFlowContext, IConfigFlowStep, IDiscoveryCandidate } from '../../core/types.js';
 import type { IMqttConfig } from './mqtt.types.js';
+import { mqttRecord, normalizeMqttIntegrationConfig } from './mqtt.validation.js';
 
 export class MqttConfigFlow implements IConfigFlow<IMqttConfig> {
+  readonly #scope: NativeIntegrationScope;
+
+  constructor(ownerArg: NativeIntegrationOwner = new NativeIntegrationOwner('mqtt')) {
+    this.#scope = ownerArg.createFlowScope();
+  }
+
+  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<IMqttConfig>> {
-    void contextArg;
+    if (candidateArg.integrationDomain !== undefined && candidateArg.integrationDomain !== 'mqtt') return { kind: 'error', error: 'MQTT requires an MQTT candidate.' };
+    let context: INativeAdmissionContext;
+    try { context = this.#scope.admit(contextArg); }
+    catch { return { kind: 'error', error: 'MQTT configuration requires the explicit matching host home and an open flow.' }; }
+    const host = typeof candidateArg.host === 'string' ? candidateArg.host : undefined;
     return {
-      kind: 'form',
-      title: 'Connect MQTT broker',
-      description: 'Configure a local MQTT 3.1.1 broker and Home Assistant-style MQTT discovery.',
+      kind: 'form', title: 'Connect selected MQTT broker',
+      description: 'Use a caller-owned credential reference. Selected topic observations are read-only; discovery mode uses the configured MQTT discovery schema.',
       fields: [
-        { name: 'host', label: 'Broker host', type: 'text', required: true },
+        { name: 'host', label: 'Selected broker host', type: 'text', required: true },
         { name: 'port', label: 'Broker port', type: 'number' },
-        { name: 'protocol', label: 'Protocol', type: 'select', options: [{ label: 'MQTT', value: 'mqtt' }, { label: 'MQTTS', value: 'mqtts' }] },
-        { name: 'username', label: 'Username', type: 'text' },
-        { name: 'password', label: 'Password', type: 'password' },
+        { name: 'protocol', label: 'Protocol', type: 'select', options: [{ label: 'MQTTS', value: 'mqtts' }, { label: 'MQTT', value: 'mqtt' }] },
+        { name: 'mode', label: 'Mapping mode', type: 'select', options: [{ label: 'Selected topics', value: 'selected-topics' }, { label: 'MQTT discovery', value: 'discovery' }] },
+        { name: 'mappings', label: 'Explicit observation mappings', type: 'text' },
+        { name: 'credentialKey', label: 'Caller credential reference', type: 'text' },
+        { name: 'allowUnencryptedLan', label: 'Consent to unencrypted local MQTT', type: 'boolean' },
         { name: 'clientId', label: 'Client ID', type: 'text' },
         { name: 'discoveryPrefix', label: 'Discovery prefix', type: 'text' },
       ],
-      submit: async (valuesArg) => {
-        const host = this.stringValue(valuesArg.host) || candidateArg.host;
-        const protocol = valuesArg.protocol === 'mqtts' ? 'mqtts' : 'mqtt';
-        const port = valuesArg.port ?? candidateArg.port ?? (protocol === 'mqtts' ? 8883 : 1883);
-        if (!host || typeof port !== 'number' || !Number.isSafeInteger(port) || port < 1 || port > 65535) {
-          return { kind: 'error', error: 'A broker host and integer port from 1 through 65535 are required.' };
-        }
-        return {
-          kind: 'done',
-          title: 'MQTT configured',
-          config: {
-            host,
-            port,
-            protocol,
-            username: this.stringValue(valuesArg.username),
-            password: typeof valuesArg.password === 'string' ? valuesArg.password : undefined,
-            clientId: this.stringValue(valuesArg.clientId),
-            discovery: true,
-            discoveryPrefix: this.stringValue(valuesArg.discoveryPrefix) || 'homeassistant',
-          },
-        };
-      },
+      submit: (valuesArg) => this.#submit(valuesArg, context, host),
     };
   }
 
-  private stringValue(valueArg: unknown): string | undefined {
-    return typeof valueArg === 'string' && valueArg.trim() ? valueArg.trim() : undefined;
+  async #submit(valuesArg: Record<string, unknown>, contextArg: INativeAdmissionContext, candidateHostArg?: string): Promise<IConfigFlowStep<IMqttConfig>> {
+    let config: IMqttConfig & { homeId: string };
+    try {
+      const values = mqttRecord(valuesArg, ['homeId', 'host', 'port', 'protocol', 'mode', 'mappings', 'credentialKey',
+        'allowUnencryptedLan', 'clientId', 'discoveryPrefix', 'connectTimeoutMs', 'operationTimeoutMs']);
+      if (values.homeId !== undefined && values.homeId !== contextArg.homeId) throw new TypeError('MQTT form home conflicts with the host home.');
+      const mappings = typeof values.mappings === 'string' ? JSON.parse(values.mappings) as unknown : values.mappings;
+      config = normalizeMqttIntegrationConfig({ ...values, mappings, host: values.host ?? candidateHostArg,
+        protocol: values.protocol ?? 'mqtts', mode: values.mode ?? 'discovery', homeId: contextArg.homeId });
+    } catch { return { kind: 'error', error: 'MQTT values, exact topic mappings or host home are invalid. Supply credential references rather than secrets.' }; }
+    try {
+      return await this.#scope.run(contextArg, config.homeId, async (leaseArg): Promise<IConfigFlowStep<IMqttConfig>> => {
+        leaseArg.assertOpen();
+        return { kind: 'done', title: 'MQTT reference configuration prepared', config };
+      });
+    } catch (error) {
+      if (error instanceof AggregateError) throw error;
+      return { kind: 'error', error: 'MQTT configuration flow is closed or cancelled.' };
+    }
   }
 }

package/ts/integrations/mqtt/mqtt.classes.integration.ts

@@ -1,18 +1,23 @@
 import * as plugins from '../../plugins.js';
 import { BaseIntegration } from '../../core/classes.baseintegration.js';
+import { NativeIntegrationOwner, type INativeSetupLease } from '../../core/classes.nativeintegrationowner.js';
 import type { IDeviceFeatureWriteRequest, IIntegrationEntity, IIntegrationEvent, IIntegrationRuntime, IIntegrationSetupContext, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
 import { MqttClient } from './mqtt.classes.client.js';
 import { MqttConfigFlow } from './mqtt.classes.configflow.js';
 import { createMqttDiscoveryDescriptor } from './mqtt.discovery.js';
 import { MqttMapper } from './mqtt.mapper.js';
-import type { IMqttConfig, IMqttPublishOptions } from './mqtt.types.js';
+import { MqttSession } from './mqtt.classes.session.js';
+import { normalizeMqttIntegrationConfig } from './mqtt.validation.js';
+import type { IMqttConfig, IMqttIntegrationOptions, IMqttPublishOptions } from './mqtt.types.js';
 
 export class MqttIntegration extends BaseIntegration<IMqttConfig> {
   public readonly domain = 'mqtt';
   public readonly displayName = 'MQTT';
   public readonly status = 'control-runtime' as const;
   public readonly discoveryDescriptor = createMqttDiscoveryDescriptor();
-  public readonly configFlow = new MqttConfigFlow();
+  public readonly configFlow: MqttConfigFlow;
+  readonly #owner: NativeIntegrationOwner;
+  readonly #options: IMqttIntegrationOptions;
   public readonly metadata = {
     source: 'home-assistant/core',
     upstreamPath: 'homeassistant/components/mqtt',
@@ -22,20 +27,31 @@ export class MqttIntegration extends BaseIntegration<IMqttConfig> {
     qualityScale: 'platinum',
   };
 
+  constructor(optionsArg: IMqttIntegrationOptions = {}) {
+    super();
+    this.#owner = new NativeIntegrationOwner('mqtt', { homeId: optionsArg.homeId, capacity: optionsArg.capacity });
+    this.#options = Object.freeze({ resolveCredentials: optionsArg.resolveCredentials });
+    this.configFlow = new MqttConfigFlow(this.#owner);
+  }
+
   public async setup(configArg: IMqttConfig, contextArg: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
-    const client = new MqttClient(configArg);
-    const runtime = new MqttRuntime(client);
-    try {
-      await client.start(contextArg.abortSignal);
+    const config = normalizeMqttIntegrationConfig(configArg);
+    return this.#owner.runSetup(contextArg, config.homeId, async (leaseArg) => {
+      const session = new MqttSession(config, leaseArg, this.#options.resolveCredentials);
+      let runtime: MqttRuntime | undefined;
+      let cleanupAttempts = 0;
+      const closeSession = (): Promise<void> => cleanupAttempts++ === 0 ? session.close() : session.retryCleanup();
+      leaseArg.own(() => runtime ? runtime.cleanup() : closeSession());
+      const client = await session.start();
+      leaseArg.assertOpen();
+      runtime = new MqttRuntime(client, config, leaseArg, closeSession);
+      leaseArg.promoteToRuntime();
       return runtime;
-    } catch (error) {
-      try { await runtime.destroy(); }
-      catch (cleanupError) { throw new AggregateError([error, cleanupError], 'MQTT setup and cleanup failed.'); }
-      throw error;
-    }
+    });
   }
 
-  public async destroy(): Promise<void> {}
+  public destroy(): Promise<void> { return this.#owner.close(); }
+  public retryCleanup(): Promise<void> { return this.#owner.retryCleanup(); }
 }
 
 export class HomeAssistantMqttIntegration extends MqttIntegration {}
@@ -51,25 +67,30 @@ class MqttRuntime implements IIntegrationRuntime {
   private updateRequested = false;
   private updating = false;
   private destroyed = false;
+  private readonly operations = new Set<Promise<unknown>>();
+  private readonly failures = new Set<unknown>();
+  private readonly ownerAbort = (): void => { this.destroyed = true; };
 
-  constructor(private readonly client: MqttClient) {
+  constructor(private readonly client: MqttClient, private readonly config: IMqttConfig,
+    private readonly lease: INativeSetupLease, private readonly closeSession: () => Promise<void>) {
     this.removeMessageHandler = client.onMessage(() => this.queueUpdate());
     this.removeConnectionHandler = client.onConnectionState((stateArg) => {
       if (stateArg.error) this.emit({ type: 'error', integrationDomain: this.domain, data: { message: stateArg.error.message }, timestamp: Date.now() });
       this.queueUpdate();
     });
+    lease.signal.addEventListener('abort', this.ownerAbort, { once: true });
   }
 
   public isHealthy(): boolean {
-    return this.client.isHealthy();
+    return !this.destroyed && this.client.isHealthy();
   }
 
   public async devices(abortSignalArg?: AbortSignal): Promise<plugins.shxInterfaces.data.IDeviceDefinition[]> {
-    return MqttMapper.toDevices(await this.client.getSnapshot(abortSignalArg));
+    return this.operation(async () => MqttMapper.toDevices(await this.client.getSnapshot(this.signal(abortSignalArg))));
   }
 
   public async entities(): Promise<IIntegrationEntity[]> {
-    return MqttMapper.toEntities(await this.client.getSnapshot());
+    return this.operation(async () => MqttMapper.toEntities(await this.client.getSnapshot(this.signal())));
   }
 
   public async subscribe(handlerArg: (eventArg: IIntegrationEvent) => void, abortSignalArg?: AbortSignal): Promise<() => Promise<void>> {
@@ -92,35 +113,64 @@ class MqttRuntime implements IIntegrationRuntime {
   }
 
   public async callService(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
-    try {
-      let command: IMqttPublishOptions | undefined;
-      if (requestArg.domain === 'mqtt') {
-        if (requestArg.service !== 'publish') return { success: false, error: 'Unsupported MQTT broker service.' };
-        command = this.publishOptionsFromRequest(requestArg);
-      } else command = MqttMapper.commandForService(await this.client.getSnapshot(), requestArg);
-      if (!command) return { success: false, error: 'MQTT service requires an available, unambiguous supported target and valid input.' };
-      await this.client.publish(command);
-      return { success: true };
-    } catch (error) { return { success: false, error: error instanceof Error ? error.message : String(error) }; }
+    if (this.config.mode === 'selected-topics') return { success: false, error: 'Selected MQTT topic mappings are read-only.' };
+    return this.operation(async () => {
+      try {
+        let command: IMqttPublishOptions | undefined;
+        if (requestArg.domain === 'mqtt') {
+          if (requestArg.service !== 'publish') return { success: false, error: 'Unsupported MQTT broker service.' };
+          command = this.publishOptionsFromRequest(requestArg);
+        } else command = MqttMapper.commandForService(await this.client.getSnapshot(), requestArg);
+        if (!command) return { success: false, error: 'MQTT service requires an available, unambiguous supported target and valid input.' };
+        await this.client.publish(command, this.signal());
+        return { success: true, data: { transportAccepted: true, brokerAcknowledged: command.qos === 1 || command.qos === 2, physicalOutcomeConfirmed: false } };
+      } catch (error) { return { success: false, error: error instanceof Error ? error.message : String(error) }; }
+    });
   }
 
   public async writeFeature(requestArg: IDeviceFeatureWriteRequest, abortSignalArg?: AbortSignal): Promise<IServiceCallResult> {
-    try {
-      const command = MqttMapper.commandForFeature(await this.client.getSnapshot(abortSignalArg), requestArg);
-      if (!command) return { success: false, error: 'MQTT feature requires an available, unambiguous supported target and valid value.' };
-      await this.client.publish(command, abortSignalArg);
-      return { success: true };
-    } catch (error) { return { success: false, error: error instanceof Error ? error.message : String(error) }; }
+    if (this.config.mode === 'selected-topics') return { success: false, error: 'Selected MQTT topic mappings are read-only.' };
+    return this.operation(async () => {
+      try {
+        const signal = this.signal(abortSignalArg);
+        const command = MqttMapper.commandForFeature(await this.client.getSnapshot(signal), requestArg);
+        if (!command) return { success: false, error: 'MQTT feature requires an available, unambiguous supported target and valid value.' };
+        await this.client.publish(command, signal);
+        return { success: true, data: { transportAccepted: true, brokerAcknowledged: command.qos === 1 || command.qos === 2, physicalOutcomeConfirmed: false } };
+      } catch (error) { return { success: false, error: error instanceof Error ? error.message : String(error) }; }
+    });
   }
 
-  public async destroy(): Promise<void> {
+  public destroy(): Promise<void> { return this.lease.close(); }
+
+  public async cleanup(): Promise<void> {
     this.destroyed = true;
     this.removeMessageHandler();
     this.removeConnectionHandler();
-    for (const cleanup of [...this.subscriptionCleanups]) await cleanup();
+    const cleanups = [...this.subscriptionCleanups];
     this.handlers.clear();
-    await this.client.destroy();
-    await this.updatePromise;
+    this.lease.signal.removeEventListener('abort', this.ownerAbort);
+    const results = await Promise.allSettled([
+      ...cleanups.map((cleanup) => Promise.resolve().then(cleanup)), this.closeSession(), this.updatePromise,
+      ...[...this.operations].map((operation) => operation.then(() => undefined, () => undefined)),
+    ]);
+    const failures = [...this.failures, ...results.flatMap((result) => result.status === 'rejected' ? [result.reason as unknown] : [])];
+    this.failures.clear();
+    if (failures.length) throw new AggregateError(failures, 'MQTT runtime cleanup failed; retry cleanup explicitly.');
+  }
+
+  private signal(signalArg?: AbortSignal): AbortSignal {
+    this.lease.assertOpen();
+    if (this.destroyed) throw new Error('MQTT runtime has been destroyed.');
+    return signalArg ? AbortSignal.any([this.lease.signal, signalArg]) : this.lease.signal;
+  }
+
+  private operation<TValue>(workArg: () => Promise<TValue>): Promise<TValue> {
+    this.signal();
+    const work = Promise.resolve().then(workArg);
+    this.operations.add(work);
+    void work.then(() => { this.operations.delete(work); }, () => { this.operations.delete(work); });
+    return work;
   }
 
   private queueUpdate(): void {
@@ -129,7 +179,16 @@ class MqttRuntime implements IIntegrationRuntime {
     if (this.updating) return;
     this.updating = true;
     this.updatePromise = this.updateSnapshots().catch((error: unknown) => {
-      if (!this.destroyed) this.emit({ type: 'error', integrationDomain: this.domain, data: { message: error instanceof Error ? error.message : String(error) }, timestamp: Date.now() });
+      if (!this.destroyed || error instanceof AggregateError) this.failures.add(error);
+      if (!this.destroyed) {
+        try { this.emit({ type: 'error', integrationDomain: this.domain, data: { message: error instanceof Error ? error.message : String(error) }, timestamp: Date.now() }); }
+        catch (callbackError) { this.failures.add(callbackError); }
+      }
+      if (this.failures.size) {
+        this.destroyed = true;
+        // Stop admitting updates after a delivery failure; the retained lease owns reporting/retry.
+        void this.lease.close().catch(() => undefined);
+      }
     }).finally(() => {
       this.updating = false;
       if (this.updateRequested && !this.destroyed) this.queueUpdate();
@@ -158,7 +217,9 @@ class MqttRuntime implements IIntegrationRuntime {
   }
 
   private emit(eventArg: IIntegrationEvent): void {
-    for (const handler of this.handlers) handler(eventArg);
+    const failures: unknown[] = [];
+    for (const handler of this.handlers) { try { handler(eventArg); } catch (error) { failures.push(error); } }
+    if (failures.length) throw new AggregateError(failures, 'MQTT event callbacks failed.');
   }
 
   private publishOptionsFromRequest(requestArg: IServiceCallRequest): IMqttPublishOptions | undefined {