@smarthome.exchange/integrations 2.0.0 → 3.0.0

package/ts/integrations/sonos/sonos.classes.client.ts

@@ -1,169 +1,438 @@
 import * as plugins from '../../plugins.js';
-import { isSonosDataRecord, normalizeSonosConfig, normalizeSonosUid, type INormalizedSonosConfig } from './sonos.config.js';
+import { NativeHomeAdmission, type INativeAdmissionContext } from '../../core/classes.nativehomeadmission.js';
+import { NativeIntegrationOwner, type INativeOperationLease, type INativeSetupLease } from '../../core/classes.nativeintegrationowner.js';
+import type { INativeIntegrationSetupContext } from '../../core/types.js';
+import { isSonosDataRecord, normalizeSonosConfig, normalizeSonosOwnerOptions, normalizeSonosUid, type INormalizedSonosConfig } from './sonos.config.js';
 import { parseSonosGroup } from './sonos.topology.js';
-import type { ISonosConfig, ISonosGroup, ISonosMediaOptions, ISonosPositionInfo, ISonosSnapshot, ISonosSpeakerInfo, ISonosTransportInfo } from './sonos.types.js';
+import type { ISonosCapabilities, ISonosConfig, ISonosControlResult, ISonosGroup, ISonosMediaOptions, ISonosOwnerOptions, ISonosPositionInfo, ISonosSnapshot, ISonosSpeakerInfo, ISonosTransportInfo } from './sonos.types.js';
 import { readSonosXmlElement, readSonosText, readSonosOptionalText } from './sonos.xml.js';
 
 const transportPath = '/MediaRenderer/AVTransport/Control';
+const renderingPath = '/MediaRenderer/RenderingControl/Control';
+const transportService = 'urn:schemas-upnp-org:service:AVTransport:1';
+const renderingService = 'urn:schemas-upnp-org:service:RenderingControl:1';
+
+interface ISonosDescription { speakerInfo: ISonosSpeakerInfo; device: Record<string, unknown>; }
+interface ISonosResources {
+  soap: plugins.ecobridgeDeviceManager.UpnpSoapClient;
+  playback: plugins.ecobridgeDeviceManager.UpnpPlaybackController;
+  volume: plugins.ecobridgeDeviceManager.UpnpVolumeController;
+}
+interface ISonosCleanup { close(): Promise<void>; status: 'idle' | 'pending' | 'failed' | 'closed'; promise?: Promise<void>; }
+interface ISonosClientOwnership { readonly owner: NativeIntegrationOwner; readonly lease: INativeSetupLease; }
+
+/** A session cannot escape its admitted operation or outlive its deadline. */
+export interface ISonosOperationSession {
+  getSnapshot(): Promise<ISonosSnapshot>;
+  getSpeakerInfo(): Promise<ISonosSpeakerInfo>;
+  getTransportInfo(): Promise<ISonosTransportInfo>;
+  getPositionInfo(): Promise<ISonosPositionInfo>;
+  getVolume(): Promise<number>;
+  getMute(): Promise<boolean>;
+  play(): Promise<ISonosControlResult>;
+  pause(): Promise<ISonosControlResult>;
+  stop(): Promise<ISonosControlResult>;
+  next(): Promise<ISonosControlResult>;
+  previous(): Promise<ISonosControlResult>;
+  setVolume(value: number): Promise<ISonosControlResult>;
+  setMute(value: boolean): Promise<ISonosControlResult>;
+  playUri(uri: string, options?: ISonosMediaOptions): Promise<ISonosControlResult>;
+}
+
+export class SonosCommandError extends Error {
+  public readonly physicalEffectConfirmed = false;
+  public readonly acknowledgedActions: readonly string[];
+  constructor(message: string, public readonly effectOutcome: 'not-sent' | 'rejected' | 'indeterminate', acknowledgedActions: readonly string[], cause?: unknown) {
+    super(message, { cause });
+    this.name = 'SonosCommandError';
+    this.acknowledgedActions = Object.freeze([...acknowledgedActions]);
+  }
+}
 
 export class SonosClient {
   public readonly config: INormalizedSonosConfig;
+  public readonly controlAllowed: boolean;
+  private readonly context: INativeAdmissionContext;
+  private readonly owner: NativeIntegrationOwner;
+  private readonly standalone: boolean;
+  private readonly resourceLease: Promise<INativeSetupLease>;
+  private readonly setupLease?: INativeSetupLease;
   private readonly lifetime = new AbortController();
-  private readonly soap: plugins.ecobridgeDeviceManager.UpnpSoapClient;
-  private readonly playback: plugins.ecobridgeDeviceManager.UpnpPlaybackController;
-  private readonly volume: plugins.ecobridgeDeviceManager.UpnpVolumeController;
   private readonly operations = new Set<Promise<unknown>>();
+  private readonly cleanup = new Set<ISonosCleanup>();
+  private resources?: ISonosResources;
   private selectedUid?: string;
+  private closed = false;
   private closePromise?: Promise<void>;
+  private ownedClosePromise?: Promise<void>;
+  private retryPromise?: Promise<void>;
 
-  constructor(config: ISonosConfig, private readonly abortSignal?: AbortSignal) {
+  /** The explicit context remains required even when constructor home is constrained. */
+  constructor(config: ISonosConfig, context: INativeIntegrationSetupContext, options: ISonosOwnerOptions = {}, ownership?: ISonosClientOwnership) {
     this.config = normalizeSonosConfig(config);
-    const baseUrl = `http://${this.config.host}:${this.config.port}`;
-    this.soap = new plugins.ecobridgeDeviceManager.UpnpSoapClient(baseUrl, {
+    const selected = normalizeSonosOwnerOptions(options);
+    this.context = new NativeHomeAdmission('sonos', selected.homeId === undefined ? {} : { homeId: selected.homeId }).admit(context, this.config.homeId);
+    this.controlAllowed = selected.allowControl === true;
+    if (ownership && !(ownership.owner instanceof NativeIntegrationOwner)) throw new Error('Sonos requires an actual native integration owner.');
+    this.standalone = ownership === undefined;
+    this.owner = ownership?.owner ?? new NativeIntegrationOwner('sonos', { homeId: this.context.homeId });
+    // This admission is independent of config, discovery, and the shared owner's prior binding.
+    this.owner.admission.admit(this.context, this.config.homeId);
+    if (ownership) {
+      ownership.lease.assertOpen();
+      if (ownership.lease.context.homeId !== this.context.homeId || ownership.lease.context.configStore !== this.context.configStore) throw new Error('Sonos client ownership does not match its admitted context.');
+      this.setupLease = ownership.lease;
+      this.resourceLease = Promise.resolve(ownership.lease);
+    } else {
+      let cleanupStarted = false;
+      this.resourceLease = this.owner.runSetup(this.context, this.config.homeId, async (lease) => {
+        lease.own(() => { const retry = cleanupStarted; cleanupStarted = true; return this.closeOwnedResources(retry); });
+        lease.promoteToRuntime();
+        return lease;
+      });
+      // The owning ledger retains failures; construction has no unhandled promise rejection.
+      void this.resourceLease.catch(() => undefined);
+    }
+  }
+
+  public getSnapshot(signal?: AbortSignal): Promise<ISonosSnapshot> { return this.withOperation((session) => session.getSnapshot(), signal); }
+  public getSpeakerInfo(signal?: AbortSignal): Promise<ISonosSpeakerInfo> { return this.withOperation((session) => session.getSpeakerInfo(), signal); }
+  public getTransportInfo(signal?: AbortSignal): Promise<ISonosTransportInfo> { return this.withOperation((session) => session.getTransportInfo(), signal); }
+  public getPositionInfo(signal?: AbortSignal): Promise<ISonosPositionInfo> { return this.withOperation((session) => session.getPositionInfo(), signal); }
+  public getVolume(signal?: AbortSignal): Promise<number> { return this.withOperation((session) => session.getVolume(), signal); }
+  public getMute(signal?: AbortSignal): Promise<boolean> { return this.withOperation((session) => session.getMute(), signal); }
+  public play(signal?: AbortSignal): Promise<ISonosControlResult> { return this.withOperation((session) => session.play(), signal); }
+  public pause(signal?: AbortSignal): Promise<ISonosControlResult> { return this.withOperation((session) => session.pause(), signal); }
+  public stop(signal?: AbortSignal): Promise<ISonosControlResult> { return this.withOperation((session) => session.stop(), signal); }
+  public next(signal?: AbortSignal): Promise<ISonosControlResult> { return this.withOperation((session) => session.next(), signal); }
+  public previous(signal?: AbortSignal): Promise<ISonosControlResult> { return this.withOperation((session) => session.previous(), signal); }
+  public setVolume(value: number, signal?: AbortSignal): Promise<ISonosControlResult> { return this.withOperation((session) => session.setVolume(value), signal); }
+  public setMute(value: boolean, signal?: AbortSignal): Promise<ISonosControlResult> { return this.withOperation((session) => session.setMute(value), signal); }
+  public playUri(uri: string, options: ISonosMediaOptions = {}, signal?: AbortSignal): Promise<ISonosControlResult> {
+    const selected = media(uri, options);
+    return this.withOperation((session) => session.playUri(selected.uri, selected.options), signal);
+  }
+
+  /** Registers the entire caller continuation, not only individual HTTP exchanges. */
+  public withOperation<TResult>(work: (session: ISonosOperationSession) => Promise<TResult>, signal?: AbortSignal): Promise<TResult> {
+    try {
+      this.assertOpen();
+      if (typeof work !== 'function' || (signal !== undefined && !(signal instanceof AbortSignal))) throw new Error('Sonos operation/cancellation is invalid.');
+      signal?.throwIfAborted();
+      const deadline = new AbortController();
+      const combined = AbortSignal.any([this.lifetime.signal, deadline.signal, ...(this.context.abortSignal ? [this.context.abortSignal] : []), ...(signal ? [signal] : [])]);
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      const operation = this.owner.runOperation({ ...this.context, abortSignal: combined }, this.config.homeId, async (lease) => {
+        lease.own(async () => { clearTimeout(timer); });
+        const resources = await this.resourceLease;
+        resources.assertOpen();
+        return this.runAdmitted(lease, resources, work);
+      });
+      // Capacity and home are reserved before allocation; deadline includes queued callback time.
+      timer = setTimeout(() => deadline.abort(new Error('Sonos operation deadline expired.')), this.config.timeoutMs);
+      void operation.then(() => clearTimeout(timer), () => clearTimeout(timer));
+      return operation;
+    } catch (error) { return Promise.reject(error); }
+  }
+
+  /** Integration setup already owns this exact lease; no second setup/operation pool is created. */
+  public withSetupLease<TResult>(lease: INativeSetupLease, work: (session: ISonosOperationSession) => Promise<TResult>): Promise<TResult> {
+    this.assertOpen();
+    if (lease !== this.setupLease) throw new Error('Sonos setup requires its exact owning lease.');
+    lease.assertOpen();
+    if (lease.context.homeId !== this.context.homeId || lease.context.configStore !== this.context.configStore) throw new Error('Sonos setup lease conflicts with client admission.');
+    return this.runAdmitted(lease, lease, work);
+  }
+
+  public destroy(): Promise<void> {
+    if (!this.closePromise) {
+      this.closed = true;
+      let close: Promise<void>;
+      this.closePromise = Promise.resolve().then(() => close);
+      close = this.standalone ? this.owner.close() : this.closeOwnedResources(false);
+      this.lifetime.abort(new Error('Sonos client is closed.'));
+    }
+    return this.closePromise;
+  }
+
+  public retryCleanup(): Promise<void> {
+    if (!this.closed) return Promise.reject(new Error('Sonos cleanup retry requires a closed client.'));
+    if (!this.retryPromise) {
+      const retry = Promise.resolve().then(() => this.standalone ? this.owner.retryCleanup() : this.closeOwnedResources(true));
+      this.retryPromise = retry;
+      const settled = (): void => { this.retryPromise = undefined; };
+      void retry.then(settled, settled);
+    }
+    return this.retryPromise;
+  }
+
+  private closeOwnedResources(retry: boolean): Promise<void> {
+    if (retry) return this.drain(true);
+    if (!this.ownedClosePromise) {
+      this.closed = true;
+      this.ownedClosePromise = Promise.resolve().then(() => this.drain(false));
+      this.lifetime.abort(new Error('Sonos client is closed.'));
+    }
+    return this.ownedClosePromise;
+  }
+
+  private async drain(retry: boolean): Promise<void> {
+    const closing = [...this.cleanup].map((entry) => {
+      if (retry && entry.status === 'failed') entry.promise = undefined;
+      if (!entry.promise) {
+        entry.status = 'pending';
+        entry.promise = Promise.resolve().then(() => entry.close()).then(() => { entry.status = 'closed'; }, (error: unknown) => { entry.status = 'failed'; throw error; });
+      }
+      return entry.promise;
+    });
+    const [results] = await Promise.all([Promise.allSettled(closing), Promise.allSettled([...this.operations])]);
+    const failures = results.filter((result): result is PromiseRejectedResult => result.status === 'rejected');
+    if (failures.length) throw new AggregateError(failures.map((result) => result.reason), 'Sonos client cleanup failed; handles remain retained.');
+  }
+
+  private allocate(lease: INativeSetupLease): ISonosResources {
+    this.assertOpen();
+    lease.assertOpen();
+    if (this.resources) return this.resources;
+    const soap = new plugins.ecobridgeDeviceManager.UpnpSoapClient(`http://${this.config.host}:${this.config.port}`, {
       timeoutMs: this.config.timeoutMs, maxResponseBytes: this.config.maxResponseBytes,
-      abortSignal: this.signal(),
+      abortSignal: AbortSignal.any([this.lifetime.signal, lease.signal]),
     });
-    this.playback = plugins.ecobridgeDeviceManager.UpnpPlaybackController.forSonos(this.config.host, this.config.port, this.soap);
-    this.volume = plugins.ecobridgeDeviceManager.UpnpVolumeController.forSonos(this.config.host, this.config.port, this.soap);
-  }
-
-  public getSnapshot(abortSignal?: AbortSignal): Promise<ISonosSnapshot> {
-    return this.request(async (signal) => {
-      const speakerInfo = await this.getSpeakerInfo(signal);
-      const [group, transportInfo, positionInfo, volume, muted] = await settledValues([
-        this.getGroup(speakerInfo.uid, signal), this.getTransportInfo(signal), this.getPositionInfo(signal),
-        this.volume.getVolume(signal), this.volume.getMute(signal),
-      ] as const);
-      return { speakerInfo, group, transportInfo, positionInfo, volume, muted, observedAt: new Date().toISOString() };
-    }, abortSignal);
-  }
-
-  public getSpeakerInfo(abortSignal?: AbortSignal): Promise<ISonosSpeakerInfo> {
-    return this.request(async (signal) => {
-      const xml = await this.soap.getXml('/xml/device_description.xml', signal);
-      const root = readSonosXmlElement(this.soap.parseXml(xml).root, 'device description');
-      if (root['@_xmlns'] !== 'urn:schemas-upnp-org:device-1-0') throw new Error('Sonos device description has an invalid namespace.');
-      const device = readSonosXmlElement(root.device, 'renderer');
-      if (readSonosText(device, 'deviceType') !== 'urn:schemas-upnp-org:device:ZonePlayer:1' || !['sonos', 'sonos, inc.'].includes(readSonosText(device, 'manufacturer').toLowerCase())) {
-        throw new Error('Configured endpoint is not a Sonos ZonePlayer.');
-      }
-      const uid = normalizeSonosUid(readSonosText(device, 'UDN').replace(/^uuid:/i, ''));
-      const expectedUid = this.config.expectedUid ?? this.selectedUid;
-      if (expectedUid && uid !== expectedUid) throw new Error('Sonos renderer identity changed or does not match configuration.');
-      this.selectedUid ??= uid;
-      const zoneXml = await this.soap.soapAction('/DeviceProperties/Control', 'urn:schemas-upnp-org:service:DeviceProperties:1', 'GetZoneAttributes', {}, signal);
-      const zoneName = this.soap.extractValue(zoneXml, 'CurrentZoneName');
-      if (!zoneName.trim() || zoneName.length > 256) throw new Error('Sonos zone name is invalid.');
-      return {
-        uid, zoneName, manufacturer: 'Sonos', modelName: readSonosOptionalText(device, 'modelName'),
-        modelNumber: readSonosOptionalText(device, 'modelNumber'), serialNumber: readSonosOptionalText(device, 'serialNum'),
-        softwareVersion: readSonosOptionalText(device, 'softwareVersion'),
+    this.cleanup.add({ close: () => soap.close(), status: 'idle' });
+    const playback = plugins.ecobridgeDeviceManager.UpnpPlaybackController.forSonos(this.config.host, this.config.port, soap);
+    this.cleanup.add({ close: () => playback.close(), status: 'idle' });
+    const volume = plugins.ecobridgeDeviceManager.UpnpVolumeController.forSonos(this.config.host, this.config.port, soap);
+    this.cleanup.add({ close: () => volume.close(), status: 'idle' });
+    this.resources = { soap, playback, volume };
+    return this.resources;
+  }
+
+  private runAdmitted<TResult>(lease: INativeOperationLease, resourceLease: INativeSetupLease, work: (session: ISonosOperationSession) => Promise<TResult>): Promise<TResult> {
+    const deadline = new AbortController();
+    const signal = AbortSignal.any([lease.signal, resourceLease.signal, this.lifetime.signal, deadline.signal]);
+    const timer = setTimeout(() => deadline.abort(new Error('Sonos operation deadline expired.')), this.config.timeoutMs);
+    let active = true;
+    let operation: Promise<TResult>;
+    operation = Promise.resolve().then(async () => {
+      this.assertOpen(); lease.assertOpen(); signal.throwIfAborted();
+      const resources = this.allocate(resourceLease);
+      const calls = new Set<Promise<unknown>>();
+      let controlStarted = false;
+      const invoke = <TValue>(callback: () => Promise<TValue>): Promise<TValue> => {
+        if (!active) throw new Error('Sonos operation session is closed.');
+        this.assertOpen(); lease.assertOpen(); signal.throwIfAborted();
+        let call: Promise<TValue>;
+        call = Promise.resolve().then(callback).finally(() => calls.delete(call));
+        calls.add(call);
+        void call.then(() => undefined, () => undefined);
+        return call;
+      };
+      const control = (callback: () => Promise<ISonosControlResult>): Promise<ISonosControlResult> => {
+        if (controlStarted) throw new Error('Sonos admits one control sequence per operation.');
+        controlStarted = true;
+        return invoke(callback);
       };
-    }, abortSignal);
+      const session: ISonosOperationSession = Object.freeze({
+        getSnapshot: () => invoke(() => this.readSnapshot(resources, signal)),
+        getSpeakerInfo: () => invoke(async () => (await this.readDescription(resources, signal)).speakerInfo),
+        getTransportInfo: () => invoke(() => this.readTransport(resources, signal)),
+        getPositionInfo: () => invoke(() => this.readPosition(resources, signal)),
+        getVolume: () => invoke(async () => { await this.readDescription(resources, signal); return resources.volume.getVolume(signal); }),
+        getMute: () => invoke(async () => { await this.readDescription(resources, signal); return resources.volume.getMute(signal); }),
+        play: () => control(() => this.transportControl(resources, 'Play', signal)),
+        pause: () => control(() => this.transportControl(resources, 'Pause', signal)),
+        stop: () => control(() => this.transportControl(resources, 'Stop', signal)),
+        next: () => control(() => this.transportControl(resources, 'Next', signal)),
+        previous: () => control(() => this.transportControl(resources, 'Previous', signal)),
+        setVolume: (value: number) => control(() => this.renderingControl(resources, 'SetVolume', value, signal)),
+        setMute: (value: boolean) => control(() => this.renderingControl(resources, 'SetMute', value, signal)),
+        playUri: (uri: string, options: ISonosMediaOptions = {}) => { const selected = media(uri, options); return control(() => this.mediaControl(resources, selected, signal)); },
+      });
+      let result: TResult;
+      try { result = await work(session); }
+      catch (error) { active = false; await Promise.allSettled([...calls]); throw error; }
+      active = false;
+      const results = await Promise.allSettled([...calls]);
+      const failures = results.filter((entry): entry is PromiseRejectedResult => entry.status === 'rejected');
+      if (failures.length) throw new AggregateError(failures.map((entry) => entry.reason), 'Sonos operation continuation failed.');
+      return result;
+    }).finally(() => { active = false; clearTimeout(timer); this.operations.delete(operation); });
+    this.operations.add(operation);
+    return operation;
   }
 
-  public getTransportInfo(abortSignal?: AbortSignal): Promise<ISonosTransportInfo> {
-    return this.request(async (signal) => {
-      const transport = await this.soap.getTransportInfo(transportPath, signal);
-      return { currentTransportState: transport.state, currentTransportStatus: transport.status, currentSpeed: transport.speed };
-    }, abortSignal);
+  private assertOpen(): void {
+    if (this.closed) throw new Error('Sonos client is closed.');
+    this.lifetime.signal.throwIfAborted();
+    this.context.abortSignal?.throwIfAborted();
   }
 
-  public getPositionInfo(abortSignal?: AbortSignal): Promise<ISonosPositionInfo> {
-    return this.request(async (signal) => {
-      const position = await this.soap.getPositionInfo(transportPath, signal);
-      const metadata = position.trackMetadata && position.trackMetadata !== 'NOT_IMPLEMENTED'
-        ? this.soap.extractOptionalValues(position.trackMetadata, ['title', 'creator', 'artist', 'album', 'albumArtURI']) : {};
-      return {
-        track: position.track, trackDuration: position.trackDuration, trackMetaData: position.trackMetadata,
-        trackUri: position.trackUri, relativeTime: position.relativeTime, title: metadata.title,
-        artist: metadata.creator ?? metadata.artist, album: metadata.album, albumArtUri: metadata.albumArtURI,
-      };
-    }, abortSignal);
+  private async readDescription(resources: ISonosResources, signal: AbortSignal): Promise<ISonosDescription> {
+    const root = readSonosXmlElement(resources.soap.parseXml(await resources.soap.getXml('/xml/device_description.xml', signal)).root, 'device description');
+    if (root['@_xmlns'] !== 'urn:schemas-upnp-org:device-1-0') throw new Error('Sonos device description has an invalid namespace.');
+    const device = readSonosXmlElement(root.device, 'renderer');
+    if (readSonosText(device, 'deviceType') !== 'urn:schemas-upnp-org:device:ZonePlayer:1' || !['sonos', 'sonos, inc.'].includes(readSonosText(device, 'manufacturer').toLowerCase())) throw new Error('Configured endpoint is not a Sonos ZonePlayer.');
+    const uid = normalizeSonosUid(readSonosText(device, 'UDN').replace(/^uuid:/i, ''));
+    if ((this.config.expectedUid ?? this.selectedUid) && uid !== (this.config.expectedUid ?? this.selectedUid)) throw new Error('Sonos renderer identity changed or does not match configuration.');
+    this.selectedUid ??= uid;
+    const xml = await resources.soap.soapAction('/DeviceProperties/Control', 'urn:schemas-upnp-org:service:DeviceProperties:1', 'GetZoneAttributes', {}, signal);
+    const zoneName = resources.soap.extractValue(xml, 'CurrentZoneName');
+    if (!zoneName.trim() || zoneName.length > 256) throw new Error('Sonos zone name is invalid.');
+    return { device, speakerInfo: { uid, zoneName, manufacturer: 'Sonos', modelName: readSonosOptionalText(device, 'modelName'), modelNumber: readSonosOptionalText(device, 'modelNumber'), serialNumber: readSonosOptionalText(device, 'serialNum'), softwareVersion: readSonosOptionalText(device, 'softwareVersion') } };
   }
 
-  public getVolume(signal?: AbortSignal): Promise<number> { return this.request((signal) => this.volume.getVolume(signal), signal); }
-  public getMute(signal?: AbortSignal): Promise<boolean> { return this.request((signal) => this.volume.getMute(signal), signal); }
-  public play(signal?: AbortSignal): Promise<void> { return this.transport((signal) => this.playback.play(undefined, signal), signal); }
-  public pause(signal?: AbortSignal): Promise<void> { return this.transport((signal) => this.playback.pause(signal), signal); }
-  public stop(signal?: AbortSignal): Promise<void> { return this.transport((signal) => this.playback.stop(signal), signal); }
-  public next(signal?: AbortSignal): Promise<void> { return this.transport((signal) => this.playback.next(signal), signal); }
-  public previous(signal?: AbortSignal): Promise<void> { return this.transport((signal) => this.playback.previous(signal), signal); }
+  private async readSnapshot(resources: ISonosResources, signal: AbortSignal): Promise<ISonosSnapshot> {
+    const description = await this.readDescription(resources, signal);
+    const [group, transportInfo, positionInfo, volume, muted, transport, rendering] = await settledValues([
+      this.readGroup(resources, description.speakerInfo.uid, signal), this.readTransport(resources, signal), this.readPosition(resources, signal),
+      resources.volume.getVolume(signal), resources.volume.getMute(signal), this.transportCapabilities(resources, description.device, signal), this.renderingCapabilities(resources, description.device, signal),
+    ] as const);
+    signal.throwIfAborted();
+    return { homeId: this.context.homeId, controlAllowed: this.controlAllowed, speakerInfo: description.speakerInfo, group, transportInfo, positionInfo, volume, muted,
+      capabilities: { ...transport, ...rendering }, observedAt: new Date().toISOString() };
+  }
 
-  public setVolume(value: number, signal?: AbortSignal): Promise<void> {
-    if (!Number.isInteger(value) || value < 0 || value > 100) throw new Error('Sonos volume must be an integer from 0 to 100.');
-    return this.request(async (signal) => { await this.getSpeakerInfo(signal); await this.volume.setVolume(value, signal); }, signal);
+  private async readGroup(resources: ISonosResources, uid: string, signal: AbortSignal): Promise<ISonosGroup> {
+    const xml = await resources.soap.soapAction('/ZoneGroupTopology/Control', 'urn:schemas-upnp-org:service:ZoneGroupTopology:1', 'GetZoneGroupState', {}, signal);
+    return parseSonosGroup(resources.soap.parseXml(resources.soap.extractValue(xml, 'ZoneGroupState')), uid);
+  }
+  private async readTransport(resources: ISonosResources, signal: AbortSignal): Promise<ISonosTransportInfo> {
+    const value = await resources.soap.getTransportInfo(transportPath, signal);
+    return { currentTransportState: value.state, currentTransportStatus: value.status, currentSpeed: value.speed };
+  }
+  private async readPosition(resources: ISonosResources, signal: AbortSignal): Promise<ISonosPositionInfo> {
+    const value = await resources.soap.getPositionInfo(transportPath, signal);
+    const metadata = value.trackMetadata && value.trackMetadata !== 'NOT_IMPLEMENTED' ? resources.soap.extractOptionalValues(value.trackMetadata, ['title', 'creator', 'artist', 'album', 'albumArtURI']) : {};
+    return { track: value.track, trackDuration: value.trackDuration, trackMetaData: value.trackMetadata, trackUri: value.trackUri, relativeTime: value.relativeTime,
+      title: metadata.title, artist: metadata.creator ?? metadata.artist, album: metadata.album, albumArtUri: metadata.albumArtURI };
   }
 
-  public setMute(value: boolean, signal?: AbortSignal): Promise<void> {
-    if (typeof value !== 'boolean') throw new Error('Sonos mute must be boolean.');
-    return this.request(async (signal) => { await this.getSpeakerInfo(signal); await this.volume.setMute(value, signal); }, signal);
+  private async serviceActions(resources: ISonosResources, device: Record<string, unknown>, serviceType: string, controlPath: string, signal: AbortSignal): Promise<string[]> {
+    const services: Record<string, unknown>[] = [];
+    const visit = (value: Record<string, unknown>, depth: number): void => {
+      if (depth > 8) throw new Error('Sonos device description nesting is excessive.');
+      if (value.serviceList !== undefined) for (const service of list(readSonosXmlElement(value.serviceList, 'service list').service)) {
+        services.push(readSonosXmlElement(service, 'service'));
+        if (services.length > 64) throw new Error('Sonos description contains too many services.');
+      }
+      if (value.deviceList !== undefined) for (const child of list(readSonosXmlElement(value.deviceList, 'device list').device)) visit(readSonosXmlElement(child, 'device'), depth + 1);
+    };
+    visit(device, 0);
+    const matches = services.filter((service) => readSonosText(service, 'serviceType') === serviceType);
+    if (matches.length !== 1) throw new Error('Sonos selected renderer must declare exactly one required service.');
+    const selected = matches[0];
+    const origin = new URL(`http://${this.config.host}:${this.config.port}`).origin;
+    const control = new URL(readSonosText(selected, 'controlURL'), origin);
+    const scpd = new URL(readSonosText(selected, 'SCPDURL'), origin);
+    if (control.origin !== origin || control.pathname !== controlPath || control.username || control.password || control.search || control.hash
+      || scpd.origin !== origin || scpd.username || scpd.password || scpd.search || scpd.hash || !scpd.pathname.startsWith('/xml/')) throw new Error('Sonos service description must remain on the exact selected renderer.');
+    const root = readSonosXmlElement(resources.soap.parseXml(await resources.soap.getXml(scpd.pathname, signal)).scpd, 'service description');
+    if (root['@_xmlns'] !== 'urn:schemas-upnp-org:service-1-0') throw new Error('Sonos service description namespace is invalid.');
+    const actions = list(readSonosXmlElement(root.actionList, 'action list').action).map((action) => readSonosText(readSonosXmlElement(action, 'action'), 'name'));
+    if (!actions.length || actions.length > 256 || actions.some((action) => !/^[A-Za-z_][A-Za-z0-9_]{0,127}$/.test(action)) || new Set(actions).size !== actions.length) throw new Error('Sonos service actions are invalid or duplicated.');
+    return actions;
   }
 
-  public playUri(uri: string, options: ISonosMediaOptions = {}, signal?: AbortSignal): Promise<void> {
-    if (!isSonosDataRecord(options) || Object.keys(options).some((key) => !['title', 'mimeType'].includes(key))) throw new Error('Sonos media options contain unsupported fields.');
-    const { title, mimeType } = options;
-    if (typeof uri !== 'string' || uri.length > 4096 || /[\x00-\x20]/.test(uri)) throw new Error('Sonos media URI is invalid.');
-    const url = new URL(uri);
-    if (!['http:', 'https:', 'x-sonos-http:', 'x-rincon-mp3radio:'].includes(url.protocol) || !url.hostname
-      || uri.slice(url.protocol.length, url.protocol.length + 2) !== '//' || url.username || url.password) throw new Error('Sonos media URI must use an uncredentialed supported stream URL.');
-    if (title !== undefined && (typeof title !== 'string' || !title.trim() || title.length > 256)) throw new Error('Sonos media title is invalid.');
-    if (mimeType !== undefined && (typeof mimeType !== 'string' || !/^audio\/[a-z0-9][a-z0-9!#$&^_.+-]{0,126}$/i.test(mimeType))) throw new Error('Sonos MIME type must identify a specific audio format.');
-    if (title !== undefined && mimeType === undefined) throw new Error('Sonos titled media requires an explicit audio MIME type.');
-    const metadata = title === undefined ? '' : this.soap.generateDidlMetadata(title, uri, mimeType);
-    return this.transport(async (signal) => {
-      await this.soap.setAVTransportURI(transportPath, uri, metadata, signal);
-      await this.playback.play(undefined, signal);
-    }, signal);
+  private async transportCapabilities(resources: ISonosResources, device: Record<string, unknown>, signal: AbortSignal): Promise<Pick<ISonosCapabilities, 'transportActions' | 'declaredTransportActions'>> {
+    const declaredTransportActions = await this.serviceActions(resources, device, transportService, transportPath, signal);
+    if (!declaredTransportActions.includes('GetCurrentTransportActions')) throw new Error('Sonos renderer does not expose current transport action authority.');
+    const xml = await resources.soap.soapAction(transportPath, transportService, 'GetCurrentTransportActions', { InstanceID: 0 }, signal);
+    const value = resources.soap.extractValue(xml, 'Actions');
+    const transportActions = value === '' ? [] : value.split(',').map((action) => action.trim());
+    if (transportActions.length > 128 || transportActions.some((action) => !/^[A-Za-z_][A-Za-z0-9_]{0,127}$/.test(action)) || new Set(transportActions).size !== transportActions.length) throw new Error('Sonos current transport actions are malformed.');
+    return { transportActions, declaredTransportActions };
   }
 
-  public destroy(): Promise<void> {
-    if (!this.closePromise) {
-      this.lifetime.abort(new Error('Sonos client is closed.'));
-      this.closePromise = (async () => {
-        const results = await Promise.allSettled([this.playback.close(), this.volume.close(), this.soap.close()]);
-        await Promise.allSettled([...this.operations]);
-        const failures = results.filter((result): result is PromiseRejectedResult => result.status === 'rejected');
-        if (failures.length) throw new AggregateError(failures.map((result) => result.reason), 'Sonos client cleanup failed.');
-      })();
+  private async renderingCapabilities(resources: ISonosResources, device: Record<string, unknown>, signal: AbortSignal): Promise<Pick<ISonosCapabilities, 'volumeWritable' | 'muteWritable'>> {
+    const actions = await this.serviceActions(resources, device, renderingService, renderingPath, signal);
+    let fixed = false;
+    if (actions.includes('GetOutputFixed')) {
+      const xml = await resources.soap.soapAction(renderingPath, renderingService, 'GetOutputFixed', { InstanceID: 0 }, signal);
+      const value = resources.soap.extractValue(xml, 'CurrentFixed');
+      if (!['0', '1', 'false', 'true'].includes(value)) throw new Error('Sonos fixed-output response is invalid.');
+      fixed = value === '1' || value === 'true';
     }
-    return this.closePromise;
+    return { volumeWritable: actions.includes('SetVolume') && !fixed, muteWritable: actions.includes('SetMute') };
+  }
+
+  private async transportAuthority(resources: ISonosResources, action: string, signal: AbortSignal): Promise<void> {
+    const description = await this.readDescription(resources, signal);
+    const [group, capabilities] = await settledValues([this.readGroup(resources, description.speakerInfo.uid, signal), this.transportCapabilities(resources, description.device, signal)] as const);
+    if (group.coordinatorUid !== description.speakerInfo.uid) throw new Error('Sonos playback requires selecting the group coordinator.');
+    if (!capabilities.declaredTransportActions.includes(action) || (action !== 'SetAVTransportURI' && !capabilities.transportActions.includes(action))) throw new Error(`Sonos renderer does not currently authorize ${action}.`);
+    signal.throwIfAborted();
   }
 
-  private getGroup(uid: string, signal: AbortSignal): Promise<ISonosGroup> {
-    return this.request(async (signal) => {
-      const response = await this.soap.soapAction('/ZoneGroupTopology/Control', 'urn:schemas-upnp-org:service:ZoneGroupTopology:1', 'GetZoneGroupState', {}, signal);
-      return parseSonosGroup(this.soap.parseXml(this.soap.extractValue(response, 'ZoneGroupState')), uid);
-    }, signal);
+  private async transportControl(resources: ISonosResources, action: 'Play' | 'Pause' | 'Stop' | 'Next' | 'Previous', signal: AbortSignal): Promise<ISonosControlResult> {
+    const target = action === 'Play' ? 'PLAYING' : action === 'Pause' ? 'PAUSED_PLAYBACK' : action === 'Stop' ? 'STOPPED' : undefined;
+    return this.control(resources, signal, async (acknowledge, attempted) => {
+      await this.transportAuthority(resources, action, signal); attempted();
+      if (action === 'Play') await resources.playback.play(undefined, signal);
+      else if (action === 'Pause') await resources.playback.pause(signal);
+      else if (action === 'Stop') await resources.playback.stop(signal);
+      else if (action === 'Next') await resources.playback.next(signal);
+      else await resources.playback.previous(signal);
+      acknowledge(action);
+    }, target, (snapshot) => snapshot.transportInfo.currentTransportState);
   }
 
-  private transport(operation: (signal: AbortSignal) => Promise<void>, signal?: AbortSignal): Promise<void> {
-    return this.request(async (signal) => {
-      const speaker = await this.getSpeakerInfo(signal);
-      const group = await this.getGroup(speaker.uid, signal);
-      if (group.coordinatorUid !== speaker.uid) throw new Error('Sonos playback requires selecting the group coordinator.');
-      signal.throwIfAborted();
-      await operation(signal);
-    }, signal);
+  private renderingControl(resources: ISonosResources, action: 'SetVolume' | 'SetMute', value: number | boolean, signal: AbortSignal): Promise<ISonosControlResult> {
+    if ((action === 'SetVolume' && (typeof value !== 'number' || !Number.isInteger(value) || value < 0 || value > 100))
+      || (action === 'SetMute' && typeof value !== 'boolean')) throw new Error('Sonos rendering value must be an integer percent from 0 to 100 or boolean mute.');
+    return this.control(resources, signal, async (acknowledge, attempted) => {
+      const description = await this.readDescription(resources, signal);
+      const capabilities = await this.renderingCapabilities(resources, description.device, signal);
+      if (action === 'SetVolume' ? !capabilities.volumeWritable : !capabilities.muteWritable) throw new Error('Sonos rendering control is not currently writable.');
+      signal.throwIfAborted(); attempted();
+      if (action === 'SetVolume') await resources.volume.setVolume(value as number, signal);
+      else await resources.volume.setMute(value as boolean, signal);
+      acknowledge(action);
+    }, value, (snapshot) => action === 'SetVolume' ? snapshot.volume : snapshot.muted);
   }
 
-  private signal(signal?: AbortSignal): AbortSignal {
-    return AbortSignal.any([this.lifetime.signal, ...(this.abortSignal ? [this.abortSignal] : []), ...(signal ? [signal] : [])]);
+  private mediaControl(resources: ISonosResources, selected: { uri: string; options: ISonosMediaOptions }, signal: AbortSignal): Promise<ISonosControlResult> {
+    return this.control(resources, signal, async (acknowledge, attempted) => {
+      await this.transportAuthority(resources, 'SetAVTransportURI', signal);
+      const metadata = selected.options.title === undefined ? '' : resources.soap.generateDidlMetadata(selected.options.title, selected.uri, selected.options.mimeType);
+      attempted(); await resources.soap.setAVTransportURI(transportPath, selected.uri, metadata, signal); acknowledge('SetAVTransportURI');
+      // URI admission changes transport state; authority must be observed again before the distinct Play effect.
+      await this.transportAuthority(resources, 'Play', signal);
+      attempted(); await resources.playback.play(undefined, signal); acknowledge('Play');
+    }, undefined, () => undefined);
   }
 
-  private request<TResult>(operation: (signal: AbortSignal) => Promise<TResult>, signal?: AbortSignal): Promise<TResult> {
-    const combined = this.signal(signal);
-    combined.throwIfAborted();
-    const result = operation(combined);
-    this.operations.add(result);
-    void result.then(() => this.operations.delete(result), () => this.operations.delete(result));
-    return result;
+  private async control(resources: ISonosResources, signal: AbortSignal, dispatch: (acknowledge: (action: string) => void, attempted: () => void) => Promise<void>, requestedValue: string | number | boolean | undefined, observation: (snapshot: ISonosSnapshot) => string | number | boolean | undefined): Promise<ISonosControlResult> {
+    const acknowledgedActions: string[] = [];
+    let attempted = false;
+    try {
+      if (!this.controlAllowed) throw new Error('Sonos control requires explicit runtime owner permission.');
+      await dispatch((action) => acknowledgedActions.push(action), () => { attempted = true; });
+      const snapshot = await this.readSnapshot(resources, signal);
+      const observedValue = observation(snapshot);
+      return Object.freeze({ acknowledgedActions: Object.freeze([...acknowledgedActions]), snapshot, requestedValue, observedValue,
+        outcome: requestedValue === undefined ? 'observed-state' : requestedValue === observedValue ? 'observed-target' : 'observed-different', physicalEffectConfirmed: false });
+    } catch (error) {
+      const outcome = !attempted ? 'not-sent' : error instanceof plugins.ecobridgeDeviceManager.UpnpSoapFault && !acknowledgedActions.length ? 'rejected' : 'indeterminate';
+      throw new SonosCommandError(error instanceof Error ? error.message : 'Sonos control failed.', outcome, acknowledgedActions, error);
+    }
   }
 }
 
+function media(uri: string, options: ISonosMediaOptions): { uri: string; options: ISonosMediaOptions } {
+  if (!isSonosDataRecord(options) || Object.keys(options).some((key) => !['title', 'mimeType'].includes(key))) throw new Error('Sonos media options contain unsupported fields.');
+  const { title, mimeType } = options;
+  if (typeof uri !== 'string' || uri.length > 4096 || /[\x00-\x20]/.test(uri)) throw new Error('Sonos media URI is invalid.');
+  const url = new URL(uri);
+  if (!['http:', 'https:', 'x-sonos-http:', 'x-rincon-mp3radio:'].includes(url.protocol) || !url.hostname || uri.slice(url.protocol.length, url.protocol.length + 2) !== '//' || url.username || url.password) throw new Error('Sonos media URI must use an uncredentialed supported stream URL.');
+  if (title !== undefined && (typeof title !== 'string' || !title.trim() || title.length > 256)) throw new Error('Sonos media title is invalid.');
+  if (mimeType !== undefined && (typeof mimeType !== 'string' || !/^audio\/[a-z0-9][a-z0-9!#$&^_.+-]{0,126}$/i.test(mimeType))) throw new Error('Sonos MIME type must identify a specific audio format.');
+  if (title !== undefined && mimeType === undefined) throw new Error('Sonos titled media requires an explicit audio MIME type.');
+  return { uri, options: Object.freeze({ title, mimeType }) };
+}
+function list(value: unknown): unknown[] { return value === undefined ? [] : Array.isArray(value) ? value : [value]; }
 async function settledValues<TValues extends readonly unknown[]>(values: { [TKey in keyof TValues]: Promise<TValues[TKey]> }): Promise<TValues> {
   const results = await Promise.allSettled(values);
-  const failure = results.find((result): result is PromiseRejectedResult => result.status === 'rejected');
-  if (failure) throw failure.reason;
+  const failures = results.filter((result): result is PromiseRejectedResult => result.status === 'rejected');
+  if (failures.length) throw new AggregateError(failures.map((result) => result.reason), 'Sonos observation failed.');
   return results.map((result) => (result as PromiseFulfilledResult<unknown>).value) as unknown as TValues;
 }