@smarthome.exchange/integrations 1.0.0 → 3.0.0

package/ts/integrations/sonos/sonos.classes.configflow.ts

@@ -1,38 +1,35 @@
-import type { IConfigFlow, IConfigFlowContext, IConfigFlowStep, IDiscoveryCandidate } from '../../core/types.js';
+import { NativeIntegrationOwner, type NativeIntegrationScope } from '../../core/classes.nativeintegrationowner.js';
+import type { IConfigFlow, IConfigFlowStep, IDiscoveryCandidate, INativeConfigFlowContext } from '../../core/types.js';
 import type { ISonosConfig } from './sonos.types.js';
 import { isSonosDataRecord, normalizeSonosConfig } from './sonos.config.js';
 
 export class SonosConfigFlow implements IConfigFlow<ISonosConfig> {
-  public async start(candidateArg: IDiscoveryCandidate, contextArg: IConfigFlowContext): Promise<IConfigFlowStep<ISonosConfig>> {
-    void contextArg;
+  private readonly scope: NativeIntegrationScope;
+  constructor(scope?: NativeIntegrationScope, options: { readonly homeId?: string } = {}) {
+    this.scope = scope ?? new NativeIntegrationOwner('sonos', options).createFlowScope();
+  }
+  public async start(candidateArg: IDiscoveryCandidate, contextArg: INativeConfigFlowContext): Promise<IConfigFlowStep<ISonosConfig>> {
     if (!isSonosDataRecord(candidateArg) || candidateArg.integrationDomain !== 'sonos') return { kind: 'error', error: 'Candidate does not belong to Sonos.' };
-    candidateArg = { source: candidateArg.source, integrationDomain: 'sonos', host: candidateArg.host, port: candidateArg.port, id: candidateArg.id };
+    const candidate = { source: candidateArg.source, host: candidateArg.host, port: candidateArg.port, id: candidateArg.id };
+    const admitted = this.scope.admit(contextArg);
     return {
-      kind: 'form',
-      title: 'Connect Sonos',
-      description: 'Configure the local Sonos player HTTP endpoint discovered by SSDP or mDNS.',
-      fields: [
-        { name: 'host', label: 'Host', type: 'text', required: true },
-        { name: 'port', label: 'Port', type: 'number' },
-      ],
-      submit: async (valuesArg) => {
-        if (!isSonosDataRecord(valuesArg)) throw new Error('Sonos form values must be a plain object.');
-        for (const key of Reflect.ownKeys(valuesArg)) {
-          const descriptor = Object.getOwnPropertyDescriptor(valuesArg, key);
-          if (typeof key !== 'string' || !['host', 'port'].includes(key) || !descriptor || !('value' in descriptor)) throw new Error('Sonos form contains an unsupported field.');
-        }
-        if (valuesArg.host !== undefined && typeof valuesArg.host !== 'string') throw new Error('Sonos host must be text.');
-        if (valuesArg.port !== undefined && typeof valuesArg.port !== 'number') throw new Error('Sonos port must be numeric.');
-        return {
-          kind: 'done',
-          title: 'Sonos configured',
-          config: normalizeSonosConfig({
-            host: typeof valuesArg.host === 'string' ? valuesArg.host : candidateArg.host ?? '',
-            port: typeof valuesArg.port === 'number' ? valuesArg.port : candidateArg.port ?? 1400,
-            ...(candidateArg.id ? { expectedUid: candidateArg.id } : {}),
-          }),
-        };
+      kind: 'form', title: 'Connect Sonos', description: 'Configure the selected local Sonos HTTP endpoint for the host-selected home.',
+      fields: [{ name: 'host', label: 'Host', type: 'text', required: true }, { name: 'port', label: 'Port', type: 'number' }],
+      submit: (values) => {
+        if (!isSonosDataRecord(values)) throw new Error('Sonos form values must be a plain object.');
+        if (Object.keys(values).some((key) => !['homeId', 'host', 'port'].includes(key))) throw new Error('Sonos form contains an unsupported field.');
+        if (values.homeId !== undefined && values.homeId !== admitted.homeId) throw new Error('Sonos submitted home conflicts with the host-selected home.');
+        if (values.host !== undefined && typeof values.host !== 'string') throw new Error('Sonos host must be text.');
+        if (values.port !== undefined && typeof values.port !== 'number') throw new Error('Sonos port must be numeric.');
+        const config = normalizeSonosConfig({ homeId: admitted.homeId, host: typeof values.host === 'string' ? values.host : candidate.host ?? '',
+          port: typeof values.port === 'number' ? values.port : candidate.port ?? 1400, ...(candidate.id ? { expectedUid: candidate.id } : {}) });
+        return this.scope.run(admitted, config.homeId, async (lease) => {
+          lease.assertOpen();
+          return { kind: 'done', title: 'Sonos configured', config };
+        });
       },
     };
   }
+  public destroy(): Promise<void> { return this.scope.close(); }
+  public retryCleanup(): Promise<void> { return this.scope.retryCleanup(); }
 }

package/ts/integrations/sonos/sonos.classes.integration.ts

@@ -1,60 +1,66 @@
 import * as plugins from '../../plugins.js';
 import { BaseIntegration } from '../../core/classes.baseintegration.js';
-import type { IDeviceFeatureWriteRequest, IIntegrationEntity, IIntegrationEvent, IIntegrationRuntime, IIntegrationSetupContext, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
-import { SonosClient } from './sonos.classes.client.js';
+import { NativeIntegrationOwner, type INativeSetupLease } from '../../core/classes.nativeintegrationowner.js';
+import type { IDeviceFeatureWriteRequest, IIntegrationEntity, IIntegrationEvent, IIntegrationRuntime, INativeIntegrationSetupContext, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
+import { SonosClient, SonosCommandError, type ISonosOperationSession } from './sonos.classes.client.js';
 import { SonosConfigFlow } from './sonos.classes.configflow.js';
 import { createSonosDiscoveryDescriptor } from './sonos.discovery.js';
 import { SonosMapper } from './sonos.mapper.js';
-import { isSonosDataRecord } from './sonos.config.js';
-import type { ISonosConfig, ISonosSnapshot } from './sonos.types.js';
+import { isSonosDataRecord, normalizeSonosConfig, normalizeSonosOwnerOptions } from './sonos.config.js';
+import type { ISonosConfig, ISonosControlResult, ISonosOwnerOptions, ISonosSnapshot } from './sonos.types.js';
 
 export class SonosIntegration extends BaseIntegration<ISonosConfig> {
   public readonly domain = 'sonos';
   public readonly displayName = 'Sonos';
   public readonly status = 'control-runtime' as const;
   public readonly discoveryDescriptor = createSonosDiscoveryDescriptor();
-  public readonly configFlow = new SonosConfigFlow();
+  public readonly configFlow: SonosConfigFlow;
   public readonly metadata = { source: 'native-typescript', integrationType: 'device', iotClass: 'local_poll' };
-  private readonly runtimes = new Set<SonosRuntime>();
-  private readonly setups = new Set<Promise<IIntegrationRuntime>>();
-  private readonly lifetime = new AbortController();
+  private readonly owner: NativeIntegrationOwner;
+  private readonly options: Readonly<ISonosOwnerOptions>;
   private closePromise?: Promise<void>;
 
-  public setup(config: ISonosConfig, context: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
-    if (this.lifetime.signal.aborted) return Promise.reject(new Error('Sonos integration is closed.'));
-    const signal = AbortSignal.any([this.lifetime.signal, ...(context.abortSignal ? [context.abortSignal] : [])]);
-    const pending = (async () => {
-      const client = new SonosClient(config, signal);
-      try {
-        const initial = await client.getSnapshot(signal);
-        signal.throwIfAborted();
-        const runtime = new SonosRuntime(client, initial, { ...context, abortSignal: signal }, () => { this.runtimes.delete(runtime); });
-        this.runtimes.add(runtime);
+  constructor(options: ISonosOwnerOptions = {}) {
+    super();
+    this.options = normalizeSonosOwnerOptions(options);
+    this.owner = new NativeIntegrationOwner('sonos', this.options.homeId === undefined ? {} : { homeId: this.options.homeId });
+    this.configFlow = new SonosConfigFlow(this.owner.createFlowScope());
+  }
+
+  public setup(config: ISonosConfig, context: INativeIntegrationSetupContext): Promise<IIntegrationRuntime> {
+    try {
+      const selected = normalizeSonosConfig(config);
+      return this.owner.runSetup(context, selected.homeId, async (lease) => {
+        const client = new SonosClient(selected, lease.context, this.options, { owner: this.owner, lease });
+        let runtime: SonosRuntime | undefined;
+        let cleanupStarted = false;
+        lease.own(() => {
+          const retry = cleanupStarted;
+          cleanupStarted = true;
+          return runtime ? runtime.closeOwnedResources(retry) : retry ? client.retryCleanup() : client.destroy();
+        });
+        const initial = await client.withSetupLease(lease, (session) => session.getSnapshot());
+        lease.assertOpen();
+        runtime = new SonosRuntime(client, initial, lease);
+        lease.promoteToRuntime();
         return runtime;
-      } catch (error) {
-        try { await client.destroy(); }
-        catch (cleanupError) { throw new AggregateError([error, cleanupError], 'Sonos setup and cleanup failed.'); }
-        throw error;
-      }
-    })();
-    this.setups.add(pending);
-    void pending.then(() => this.setups.delete(pending), () => this.setups.delete(pending));
-    return pending;
+      });
+    } catch (error) { return Promise.reject(error); }
   }
 
   public destroy(): Promise<void> {
     if (!this.closePromise) {
-      this.lifetime.abort(new Error('Sonos integration is closed.'));
-      this.closePromise = (async () => {
-        await Promise.allSettled([...this.setups]);
-        const results = await Promise.allSettled([...this.runtimes].map((runtime) => runtime.destroy()));
-        this.runtimes.clear();
+      let closing: Promise<void>[] = [];
+      this.closePromise = Promise.resolve().then(async () => {
+        const results = await Promise.allSettled(closing);
         const failures = results.filter((result): result is PromiseRejectedResult => result.status === 'rejected');
-        if (failures.length) throw new AggregateError(failures.map((result) => result.reason), 'Sonos runtime cleanup failed.');
-      })();
+        if (failures.length) throw new AggregateError(failures.map((result) => result.reason), 'Sonos owned cleanup failed; handles remain retained.');
+      });
+      closing = [this.configFlow.destroy(), this.owner.close()];
     }
     return this.closePromise;
   }
+  public retryCleanup(): Promise<void> { return this.owner.retryCleanup(); }
 }
 
 export class HomeAssistantSonosIntegration extends SonosIntegration {}
@@ -64,6 +70,7 @@ interface ISonosSubscription {
   job: Promise<void>;
   failed: boolean;
   failure?: unknown;
+  stopPromise?: Promise<void>;
   stop(): Promise<void>;
 }
 
@@ -74,178 +81,198 @@ class SonosRuntime implements IIntegrationRuntime {
   private healthy = true;
   private closed = false;
   private closePromise?: Promise<void>;
-  private readonly parentAbort?: () => void;
-
-  constructor(private readonly client: SonosClient, private snapshot: ISonosSnapshot, private readonly context: IIntegrationSetupContext = {}, private readonly onClosed?: () => void) {
-    if (context.abortSignal) {
-      this.parentAbort = () => this.lifetime.abort(context.abortSignal?.reason);
-      context.abortSignal.addEventListener('abort', this.parentAbort, { once: true });
-      if (context.abortSignal.aborted) this.parentAbort();
-    }
-  }
 
-  public isHealthy(): boolean { return this.healthy && !this.closed && !this.lifetime.signal.aborted; }
+  constructor(private readonly client: SonosClient, private snapshot: ISonosSnapshot, private readonly lease: INativeSetupLease) {}
+  public isHealthy(): boolean { return this.healthy && !this.closed && !this.lease.signal.aborted; }
 
-  public async devices(signal?: AbortSignal): Promise<plugins.shxInterfaces.data.IDeviceDefinition[]> {
-    return SonosMapper.toDevices(await this.read(signal));
+  public devices(signal?: AbortSignal): Promise<plugins.shxInterfaces.data.IDeviceDefinition[]> {
+    return this.observe(async (session) => SonosMapper.toDevices(await this.read(session)), signal);
   }
+  public entities(): Promise<IIntegrationEntity[]> { return this.observe(async (session) => SonosMapper.toEntities(await this.read(session))); }
 
-  public async entities(): Promise<IIntegrationEntity[]> { return SonosMapper.toEntities(await this.read()); }
-
-  public async writeFeature(request: IDeviceFeatureWriteRequest, signal?: AbortSignal): Promise<IServiceCallResult> {
-    assertDataRecord(request, ['device', 'feature', 'value']);
-    assertDataRecord(request.device);
-    assertDataRecord(request.feature);
-    const deviceId = request.device.id;
-    const integrationDomain = request.device.integrationDomain;
-    const featureId = request.feature.id;
-    const value = request.value;
-    const snapshot = await this.read(signal);
-    const device = SonosMapper.toDevices(snapshot)[0];
-    if (integrationDomain !== this.domain || deviceId !== device.id) throw new Error('Sonos feature target does not belong to the selected renderer.');
-    const feature = device.features.find((feature) => feature.id === featureId);
-    if (!feature?.writable || feature.capability !== 'media') throw new Error('Sonos feature is not writable for this renderer.');
-    if (feature.id === 'volume') {
-      if (typeof value !== 'number') throw new Error('Sonos volume must be numeric.');
-      await this.client.setVolume(value, this.signal(signal));
-    } else if (feature.id === 'muted') {
-      if (typeof value !== 'boolean') throw new Error('Sonos mute must be boolean.');
-      await this.client.setMute(value, this.signal(signal));
-    } else if (feature.id === 'playback') {
-      if (value === 'playing') await this.client.play(this.signal(signal));
-      else if (value === 'paused') await this.client.pause(this.signal(signal));
-      else if (value === 'stopped') await this.client.stop(this.signal(signal));
-      else throw new Error('Sonos playback must be playing, paused or stopped.');
-    } else throw new Error('Unsupported Sonos feature.');
-    return this.readback(signal);
+  public writeFeature(request: IDeviceFeatureWriteRequest, signal?: AbortSignal): Promise<IServiceCallResult> {
+    try {
+      assertDataRecord(request, ['device', 'feature', 'value']); assertDataRecord(request.device); assertDataRecord(request.feature);
+      const deviceId = request.device.id; const integrationDomain = request.device.integrationDomain; const featureId = request.feature.id; const value = request.value;
+      this.assertControlAllowed();
+      return this.observe(async (session) => {
+        const device = SonosMapper.toDevices(await this.read(session))[0];
+        if (integrationDomain !== this.domain || deviceId !== device.id) throw new Error('Sonos feature target does not belong to the selected renderer.');
+        const feature = device.features.find((feature) => feature.id === featureId);
+        if (!feature?.writable || feature.capability !== 'media') throw new Error('Sonos feature is not writable for this renderer.');
+        let result: ISonosControlResult;
+        if (feature.id === 'volume') {
+          if (typeof value !== 'number') throw new Error('Sonos volume must be numeric.');
+          result = await session.setVolume(value);
+        } else if (feature.id === 'muted') {
+          if (typeof value !== 'boolean') throw new Error('Sonos mute must be boolean.');
+          result = await session.setMute(value);
+        } else if (feature.id === 'playback') {
+          if (value === 'playing') result = await session.play();
+          else if (value === 'paused') result = await session.pause();
+          else if (value === 'stopped') result = await session.stop();
+          else throw new Error('Sonos playback must be playing, paused or stopped.');
+        } else throw new Error('Unsupported Sonos feature.');
+        return this.result(result);
+      }, signal);
+    } catch (error) { return Promise.reject(error); }
   }
 
-  public async callService(request: IServiceCallRequest): Promise<IServiceCallResult> {
-    assertDataRecord(request, ['domain', 'service', 'target', 'data']);
-    assertDataRecord(request.target, ['deviceId', 'entityId']);
-    if (request.data !== undefined) assertDataRecord(request.data);
-    request = { domain: request.domain, service: request.service,
-      target: { ...(request.target.deviceId === undefined ? {} : { deviceId: request.target.deviceId }),
-        ...(request.target.entityId === undefined ? {} : { entityId: request.target.entityId }) },
-      ...(request.data === undefined ? {} : { data: { ...request.data } }) };
-    if (request.domain !== 'media_player' || typeof request.service !== 'string') throw new Error('Unsupported Sonos service domain.');
-    const snapshot = await this.read();
-    const deviceId = SonosMapper.deviceId(snapshot);
-    const entityId = SonosMapper.entityId(snapshot.speakerInfo.uid);
-    if ((!request.target.deviceId && !request.target.entityId) || (request.target.deviceId !== undefined && request.target.deviceId !== deviceId)
-      || (request.target.entityId !== undefined && request.target.entityId !== entityId)) throw new Error('Sonos service target does not belong to the selected renderer.');
-    const data = request.data ?? {};
-    assertDataRecord(data);
-    const signal = this.signal();
-    if (['play', 'pause', 'stop', 'next_track', 'previous_track'].includes(request.service)) {
-      assertDataRecord(data, []);
-      if (request.service === 'play') await this.client.play(signal);
-      else if (request.service === 'pause') await this.client.pause(signal);
-      else if (request.service === 'stop') await this.client.stop(signal);
-      else if (request.service === 'next_track') await this.client.next(signal);
-      else await this.client.previous(signal);
-    } else if (request.service === 'volume_set') {
-      assertDataRecord(data, ['volume', 'volume_level']);
-      if (Object.hasOwn(data, 'volume') === Object.hasOwn(data, 'volume_level')) throw new Error('Sonos volume_set requires exactly one volume argument.');
-      const value = Object.hasOwn(data, 'volume') ? data.volume : data.volume_level;
-      if (typeof value !== 'number' || !Number.isFinite(value)) throw new Error('Sonos volume must be finite.');
-      const percent = Math.round(value * 100);
-      if (Object.hasOwn(data, 'volume_level') && (value < 0 || value > 1 || Math.abs(value * 100 - percent) > 1e-8)) throw new Error('Sonos volume_level must represent an integer percent from 0 to 100.');
-      await this.client.setVolume(Object.hasOwn(data, 'volume') ? value : percent, signal);
-    } else if (request.service === 'volume_mute') {
-      assertDataRecord(data, ['muted', 'is_volume_muted']);
-      if (Object.hasOwn(data, 'muted') === Object.hasOwn(data, 'is_volume_muted')) throw new Error('Sonos volume_mute requires exactly one mute argument.');
-      const value = Object.hasOwn(data, 'muted') ? data.muted : data.is_volume_muted;
-      if (typeof value !== 'boolean') throw new Error('Sonos mute must be boolean.');
-      await this.client.setMute(value, signal);
-    } else if (request.service === 'play_media') {
-      assertDataRecord(data, ['uri', 'media_content_id', 'title', 'mime_type']);
-      if (Object.hasOwn(data, 'uri') === Object.hasOwn(data, 'media_content_id')) throw new Error('Sonos play_media requires exactly one URI argument.');
-      const uri = Object.hasOwn(data, 'uri') ? data.uri : data.media_content_id;
-      if (typeof uri !== 'string' || (data.title !== undefined && typeof data.title !== 'string') || (data.mime_type !== undefined && typeof data.mime_type !== 'string')) throw new Error('Sonos media URI, title and MIME type must be text.');
-      await this.client.playUri(uri, { title: data.title, mimeType: data.mime_type }, signal);
-    } else throw new Error(`Unsupported Sonos service: ${request.service}`);
-    return this.readback();
+  public callService(request: IServiceCallRequest): Promise<IServiceCallResult> {
+    try {
+      assertDataRecord(request, ['domain', 'service', 'target', 'data']); assertDataRecord(request.target, ['deviceId', 'entityId']);
+      if (request.data !== undefined) assertDataRecord(request.data);
+      const selected: IServiceCallRequest = { domain: request.domain, service: request.service,
+        target: { ...(request.target.deviceId === undefined ? {} : { deviceId: request.target.deviceId }), ...(request.target.entityId === undefined ? {} : { entityId: request.target.entityId }) },
+        ...(request.data === undefined ? {} : { data: { ...request.data } }) };
+      if (selected.domain !== 'media_player' || typeof selected.service !== 'string') throw new Error('Unsupported Sonos service domain.');
+      this.assertControlAllowed();
+      return this.observe(async (session) => {
+        const snapshot = await this.read(session);
+        const deviceId = SonosMapper.deviceId(snapshot); const entityId = SonosMapper.entityId(snapshot.homeId, snapshot.speakerInfo.uid);
+        if ((!selected.target.deviceId && !selected.target.entityId) || (selected.target.deviceId !== undefined && selected.target.deviceId !== deviceId)
+          || (selected.target.entityId !== undefined && selected.target.entityId !== entityId)) throw new Error('Sonos service target does not belong to the selected renderer.');
+        const data = selected.data ?? {}; assertDataRecord(data);
+        let result: ISonosControlResult;
+        if (['play', 'pause', 'stop', 'next_track', 'previous_track'].includes(selected.service)) {
+          assertDataRecord(data, []);
+          if (selected.service === 'play') result = await session.play();
+          else if (selected.service === 'pause') result = await session.pause();
+          else if (selected.service === 'stop') result = await session.stop();
+          else if (selected.service === 'next_track') result = await session.next();
+          else result = await session.previous();
+        } else if (selected.service === 'volume_set') {
+          assertDataRecord(data, ['volume', 'volume_level']);
+          if (Object.hasOwn(data, 'volume') === Object.hasOwn(data, 'volume_level')) throw new Error('Sonos volume_set requires exactly one volume argument.');
+          const value = Object.hasOwn(data, 'volume') ? data.volume : data.volume_level;
+          if (typeof value !== 'number' || !Number.isFinite(value)) throw new Error('Sonos volume must be finite.');
+          const percent = Math.round(value * 100);
+          if (Object.hasOwn(data, 'volume_level') && (value < 0 || value > 1 || Math.abs(value * 100 - percent) > 1e-8)) throw new Error('Sonos volume_level must represent an integer percent from 0 to 100.');
+          result = await session.setVolume(Object.hasOwn(data, 'volume') ? value : percent);
+        } else if (selected.service === 'volume_mute') {
+          assertDataRecord(data, ['muted', 'is_volume_muted']);
+          if (Object.hasOwn(data, 'muted') === Object.hasOwn(data, 'is_volume_muted')) throw new Error('Sonos volume_mute requires exactly one mute argument.');
+          const value = Object.hasOwn(data, 'muted') ? data.muted : data.is_volume_muted;
+          if (typeof value !== 'boolean') throw new Error('Sonos mute must be boolean.');
+          result = await session.setMute(value);
+        } else if (selected.service === 'play_media') {
+          assertDataRecord(data, ['uri', 'media_content_id', 'title', 'mime_type']);
+          if (Object.hasOwn(data, 'uri') === Object.hasOwn(data, 'media_content_id')) throw new Error('Sonos play_media requires exactly one URI argument.');
+          const uri = Object.hasOwn(data, 'uri') ? data.uri : data.media_content_id;
+          if (typeof uri !== 'string' || (data.title !== undefined && typeof data.title !== 'string') || (data.mime_type !== undefined && typeof data.mime_type !== 'string')) throw new Error('Sonos media URI, title and MIME type must be text.');
+          result = await session.playUri(uri, { title: data.title, mimeType: data.mime_type });
+        } else throw new Error(`Unsupported Sonos service: ${selected.service}`);
+        return this.result(result);
+      });
+    } catch (error) { return Promise.reject(error); }
   }
 
-  public async subscribe(handler: (event: IIntegrationEvent) => void, signal?: AbortSignal): Promise<() => Promise<void>> {
-    if (typeof handler !== 'function') throw new Error('Sonos subscription handler must be callable.');
-    if (this.subscriptions.size >= 16) throw new Error('Sonos runtime supports at most 16 subscriptions.');
-    const controller = new AbortController();
-    const combined = AbortSignal.any([this.signal(signal), controller.signal]);
-    const initial = await this.read(combined);
-    combined.throwIfAborted();
-    if (this.subscriptions.size >= 16) throw new Error('Sonos runtime supports at most 16 subscriptions.');
-    handler(this.event('state_changed', initial));
-    combined.throwIfAborted();
-    let subscription: ISonosSubscription;
-    const job = (async () => {
-      while (!combined.aborted) {
-        await wait(this.client.config.pollIntervalMs, combined);
-        if (combined.aborted) return;
-        let snapshot: ISonosSnapshot;
-        try { snapshot = await this.read(combined); }
-        catch (error) {
+  public subscribe(handler: (event: IIntegrationEvent) => void, signal?: AbortSignal): Promise<() => Promise<void>> {
+    try {
+      this.lease.assertOpen();
+      if (typeof handler !== 'function') throw new Error('Sonos subscription handler must be callable.');
+      if (this.subscriptions.size >= 16) throw new Error('Sonos runtime supports at most 16 subscriptions.');
+      const controller = new AbortController();
+      const combined = AbortSignal.any([this.lease.signal, this.lifetime.signal, controller.signal, ...(signal ? [signal] : [])]);
+      combined.throwIfAborted();
+      const subscription: ISonosSubscription = {
+        controller, job: Promise.resolve(), failed: false,
+        stop: () => {
+          if (!subscription.stopPromise) {
+            subscription.stopPromise = Promise.resolve().then(async () => {
+              await subscription.job;
+              this.subscriptions.delete(subscription);
+              if (subscription.failed) throw subscription.failure;
+            });
+            controller.abort(new Error('Sonos subscription stopped.'));
+          }
+          return subscription.stopPromise;
+        },
+      };
+      // Reservation precedes the initial read and the first caller callback.
+      this.subscriptions.add(subscription);
+      const publish = async (type: IIntegrationEvent['type'], data: unknown): Promise<void> => {
+        try { await handler(this.event(type, data)); }
+        catch (error) { subscription.failed = true; subscription.failure = error; throw error; }
+      };
+      const initial = this.observe(async (session) => {
+        const snapshot = await this.read(session); combined.throwIfAborted();
+        await publish('state_changed', snapshot); combined.throwIfAborted();
+      }, combined);
+      subscription.job = initial.then(async () => {
+        while (!combined.aborted) {
+          await wait(this.client.config.pollIntervalMs, combined);
           if (combined.aborted) return;
-          handler(this.event('availability_changed', { available: false }));
-          handler(this.event('error', { message: error instanceof Error ? error.message : 'Sonos read failed.' }));
-          continue;
+          await this.observe(async (session) => {
+            let snapshot: ISonosSnapshot;
+            try { snapshot = await this.read(session); }
+            catch (error) {
+              if (combined.aborted) return;
+              await publish('availability_changed', { available: false });
+              await publish('error', { message: error instanceof Error ? error.message : 'Sonos read failed.' });
+              return;
+            }
+            await publish('state_changed', snapshot);
+          }, combined);
         }
-        handler(this.event('state_changed', snapshot));
-      }
-    })().catch((error: unknown) => {
-      if (!combined.aborted) { subscription.failed = true; subscription.failure = error; this.healthy = false; controller.abort(error); }
-    }).then(() => {
-      if (!subscription.failed) this.subscriptions.delete(subscription);
-    });
-    subscription = {
-      controller, job, failed: false,
-      stop: async () => {
-        controller.abort(new Error('Sonos subscription stopped.'));
-        await job;
-        this.subscriptions.delete(subscription);
-        if (subscription.failed) throw subscription.failure;
-      },
-    };
-    this.subscriptions.add(subscription);
-    return subscription.stop;
+      }).catch((error: unknown) => {
+        if (!combined.aborted || subscription.failed) { subscription.failed = true; subscription.failure = error; this.healthy = false; controller.abort(error); }
+      }).then(() => { if (!subscription.failed) this.subscriptions.delete(subscription); });
+      return initial.then(() => subscription.stop, async (error: unknown) => {
+        try { await subscription.stop(); } catch (cleanupError) { if (cleanupError !== error) throw new AggregateError([error, cleanupError], 'Sonos subscription admission and cleanup failed.'); }
+        throw error;
+      });
+    } catch (error) { return Promise.reject(error); }
   }
 
-  public destroy(): Promise<void> {
+  public destroy(): Promise<void> { return this.lease.close(); }
+
+  /** The owner's retained composite handle invokes this, including explicit cleanup retry. */
+  public closeOwnedResources(retry = false): Promise<void> {
+    if (retry) return this.drain(true);
     if (!this.closePromise) {
-      this.closed = true;
-      this.healthy = false;
+      this.closed = true; this.healthy = false;
+      this.closePromise = Promise.resolve().then(() => this.drain(false));
       this.lifetime.abort(new Error('Sonos runtime is closed.'));
-      if (this.parentAbort) this.context.abortSignal?.removeEventListener('abort', this.parentAbort);
-      this.closePromise = (async () => {
-        const results = await Promise.allSettled([this.client.destroy(), ...[...this.subscriptions].map((subscription) => subscription.stop())]);
-        this.onClosed?.();
-        const failures = results.filter((result): result is PromiseRejectedResult => result.status === 'rejected');
-        if (failures.length) throw new AggregateError(failures.map((result) => result.reason), 'Sonos cleanup failed.');
-      })();
     }
     return this.closePromise;
   }
+  private async drain(retry: boolean): Promise<void> {
+    const results = await Promise.allSettled([
+      Promise.resolve().then(() => retry ? this.client.retryCleanup() : this.client.destroy()),
+      ...[...this.subscriptions].map((subscription) => Promise.resolve().then(() => subscription.stop())),
+    ]);
+    const failures = results.filter((result): result is PromiseRejectedResult => result.status === 'rejected');
+    if (failures.length) throw new AggregateError(failures.map((result) => result.reason), 'Sonos cleanup or subscriber failed; ownership remains retained.');
+  }
 
-  private async read(signal?: AbortSignal): Promise<ISonosSnapshot> {
-    try { this.snapshot = await this.client.getSnapshot(this.signal(signal)); this.healthy = true; return this.snapshot; }
+  private observe<TResult>(work: (session: ISonosOperationSession) => Promise<TResult>, signal?: AbortSignal): Promise<TResult> {
+    try {
+      this.lease.assertOpen();
+      return this.client.withOperation(async (session) => {
+        try { return await work(session); }
+        catch (error) { if (error instanceof SonosCommandError && error.effectOutcome === 'indeterminate') this.healthy = false; throw error; }
+      }, signal);
+    }
+    catch (error) { return Promise.reject(error); }
+  }
+  private async read(session: ISonosOperationSession): Promise<ISonosSnapshot> {
+    try { this.snapshot = await session.getSnapshot(); this.healthy = true; return this.snapshot; }
     catch (error) { this.healthy = false; throw error; }
   }
-
-  private async readback(signal?: AbortSignal): Promise<IServiceCallResult> {
-    const snapshot = await this.read(signal);
-    return { success: true, data: { devices: SonosMapper.toDevices(snapshot), entities: SonosMapper.toEntities(snapshot) } };
+  private assertControlAllowed(): void {
+    this.lease.assertOpen();
+    if (!this.client.controlAllowed) throw new Error('Sonos control requires explicit runtime owner permission.');
   }
-
-  private signal(signal?: AbortSignal): AbortSignal {
-    const combined = AbortSignal.any([this.lifetime.signal, ...(signal ? [signal] : [])]);
-    combined.throwIfAborted();
-    return combined;
+  private result(result: ISonosControlResult): IServiceCallResult {
+    this.snapshot = result.snapshot; this.healthy = true;
+    return { success: true, data: { acknowledgedActions: result.acknowledgedActions, outcome: result.outcome, requestedValue: result.requestedValue, observedValue: result.observedValue,
+      physicalEffectConfirmed: false, observationAtomic: false, observedAt: result.snapshot.observedAt,
+      devices: SonosMapper.toDevices(result.snapshot), entities: SonosMapper.toEntities(result.snapshot) } };
   }
-
   private event(type: IIntegrationEvent['type'], data: unknown): IIntegrationEvent {
-    return { type, integrationDomain: this.domain, deviceId: SonosMapper.deviceId(this.snapshot),
-      entityId: SonosMapper.entityId(this.snapshot.speakerInfo.uid), data: structuredClone(data), timestamp: Date.now() };
+    return { type, integrationDomain: this.domain, deviceId: SonosMapper.deviceId(this.snapshot), entityId: SonosMapper.entityId(this.snapshot.homeId, this.snapshot.speakerInfo.uid),
+      data: structuredClone(data), timestamp: Date.now() };
   }
 }
 
@@ -256,12 +283,10 @@ function assertDataRecord(value: unknown, allowed?: string[]): asserts value is
     if (typeof key !== 'string' || !descriptor || !('value' in descriptor) || (allowed && !allowed.includes(key))) throw new Error('Sonos input contains an unsupported field.');
   }
 }
-
 function wait(milliseconds: number, signal: AbortSignal): Promise<void> {
   return new Promise((resolve) => {
     const finish = (): void => { clearTimeout(timer); signal.removeEventListener('abort', finish); resolve(); };
     const timer = setTimeout(finish, milliseconds);
-    signal.addEventListener('abort', finish, { once: true });
-    if (signal.aborted) finish();
+    signal.addEventListener('abort', finish, { once: true }); if (signal.aborted) finish();
   });
 }

package/ts/integrations/sonos/sonos.config.ts

@@ -1,6 +1,7 @@
-import type { ISonosConfig } from './sonos.types.js';
+import type { ISonosConfig, ISonosEndpointConfig, ISonosOwnerOptions } from './sonos.types.js';
 
 export interface INormalizedSonosConfig extends ISonosConfig {
+  readonly homeId: string;
   readonly host: string;
   readonly port: number;
   readonly expectedUid?: string;
@@ -9,6 +10,19 @@ export interface INormalizedSonosConfig extends ISonosConfig {
   readonly pollIntervalMs: number;
 }
 
+export function normalizeSonosHome(value: unknown): string {
+  if (typeof value !== 'string' || !value || value.length > 256 || value.trim() !== value || /[\p{Cc}\p{Cs}]/u.test(value)) {
+    throw new Error('Sonos homeId must be a bounded nonempty identifier without surrounding whitespace or control characters.');
+  }
+  return value;
+}
+
+export function normalizeSonosOwnerOptions(input: ISonosOwnerOptions): Readonly<ISonosOwnerOptions> {
+  if (!isSonosDataRecord(input) || Object.keys(input).some((key) => !['homeId', 'allowControl'].includes(key))) throw new Error('Sonos owner options contain unsupported fields.');
+  if (input.allowControl !== undefined && typeof input.allowControl !== 'boolean') throw new Error('Sonos allowControl must be boolean.');
+  return Object.freeze({ ...(input.homeId === undefined ? {} : { homeId: normalizeSonosHome(input.homeId) }), allowControl: input.allowControl === true });
+}
+
 export function normalizeSonosUid(value: unknown): string {
   if (typeof value !== 'string' || !/^RINCON_[0-9a-f]{12}0?1400$/i.test(value)) {
     throw new Error('Sonos player identity must be a RINCON UUID.');
@@ -20,11 +34,19 @@ export function isSonosDataRecord(value: unknown): value is Record<string, unkno
   if (!value || typeof value !== 'object' || Array.isArray(value) || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) return false;
   return Reflect.ownKeys(value).every((key) => {
     const descriptor = Object.getOwnPropertyDescriptor(value, key);
-    return typeof key === 'string' && descriptor !== undefined && 'value' in descriptor;
+    return typeof key === 'string' && descriptor !== undefined && descriptor.enumerable === true && 'value' in descriptor;
   });
 }
 
 export function normalizeSonosConfig(input: ISonosConfig): INormalizedSonosConfig {
+  if (!isSonosDataRecord(input) || !Object.hasOwn(input, 'homeId')) throw new Error('Sonos configuration requires its own homeId.');
+  const homeId = normalizeSonosHome(input.homeId);
+  const { homeId: _homeId, ...endpoint } = input;
+  return Object.freeze({ ...normalizeSonosEndpoint(endpoint), homeId });
+}
+
+/** Discovery validates an endpoint only; it cannot select an owning home. */
+export function normalizeSonosEndpoint(input: ISonosEndpointConfig): Omit<INormalizedSonosConfig, 'homeId'> {
   if (!isSonosDataRecord(input) || !Object.hasOwn(input, 'host')) throw new Error('Sonos configuration must be a plain object containing its own host field.');
   const allowed = new Set(['host', 'port', 'expectedUid', 'timeoutMs', 'maxResponseBytes', 'pollIntervalMs']);
   for (const key of Reflect.ownKeys(input)) {