@smarthome.exchange/integrations 2.0.0 → 4.0.0

package/ts/integrations/webostv/webostv.classes.client.ts

@@ -1,7 +1,9 @@
 import * as plugins from '../../plugins.js';
 import { NoSqlConfigStore } from '../../core/classes.configstore.js';
-import type { IWebostvConfig, IWebostvInput, IWebostvIntegrationOptions, IWebostvSnapshot, TWebostvClientEvent, TWebostvCommand } from './webostv.types.js';
-import { normalizeWebostvConfig, webostvInteger, webostvObject, webostvString } from './webostv.validation.js';
+import { NativeHomeAdmission, type INativeAdmissionContext } from '../../core/classes.nativehomeadmission.js';
+import type { INativeIntegrationSetupContext } from '../../core/types.js';
+import type { IWebostvCommandResult, IWebostvConfig, IWebostvInput, IWebostvIntegrationOptions, IWebostvSnapshot, TWebostvClientEvent, TWebostvClientHandler, TWebostvCommand } from './webostv.types.js';
+import { normalizeWebostvConfig, normalizeWebostvOptions, webostvInteger, webostvObject, webostvString } from './webostv.validation.js';
 
 interface IPendingRequest {
   resolve(valueArg: Record<string, unknown>): void;
@@ -26,38 +28,47 @@ export class WebostvClient {
   readonly #config: Readonly<IWebostvConfig>;
   readonly #store: NoSqlConfigStore;
   readonly #ownsStore: boolean;
+  readonly #context: INativeAdmissionContext;
+  readonly #allowedCommands: readonly TWebostvCommand[];
   readonly #lifetime = new AbortController();
   readonly #pending = new Map<string, IPendingRequest>();
   readonly #subscriptions = new Map<string, (payloadArg: Record<string, unknown>) => void>();
-  readonly #handlers = new Set<(eventArg: TWebostvClientEvent) => void>();
+  readonly #handlers = new Set<TWebostvClientHandler>();
+  readonly #operations = new Set<Promise<unknown>>();
+  readonly #handlerOperations = new Map<TWebostvClientHandler, Set<Promise<void>>>();
   #socket?: plugins.ws.WebSocket;
   #snapshot?: IWebostvSnapshot;
   #sequence = 0;
   #start?: Promise<IWebostvSnapshot>;
   #destroy?: Promise<void>;
+  #retry?: Promise<void>;
   #heartbeat?: ReturnType<typeof setInterval>;
   #awaitingPong = false;
   #ready = false;
   #failure?: Error;
-  #storage?: Promise<unknown>;
-  readonly #handlerCleanups = new Map<(eventArg: TWebostvClientEvent) => void, () => void>();
+  readonly #handlerCleanups = new Map<TWebostvClientHandler, () => void>();
   #removeExternalAbort: () => void = () => undefined;
 
-  constructor(configArg: IWebostvConfig, optionsArg?: IWebostvIntegrationOptions | NoSqlConfigStore, signalArg?: AbortSignal) {
+  constructor(configArg: IWebostvConfig, contextArg: INativeIntegrationSetupContext, optionsArg: IWebostvIntegrationOptions = {}) {
     this.#config = normalizeWebostvConfig(configArg);
-    if (optionsArg instanceof NoSqlConfigStore) {
-      const scope = optionsArg.getScope();
-      if (scope.homeId !== this.#config.homeId || scope.integrationDomain !== 'webostv') throw new TypeError('webOS requires an encrypted config store scoped to the exact configured home and webostv domain.');
-      this.#store = optionsArg;
+    const options = normalizeWebostvOptions(optionsArg);
+    this.#context = new NativeHomeAdmission('webostv', { homeId: options.homeId }).admit(contextArg, this.#config.homeId);
+    this.#allowedCommands = options.allowedCommands!;
+    if (this.#context.configStore) {
+      this.#store = this.#context.configStore;
       this.#ownsStore = false;
     } else {
-      if (!optionsArg?.db || !optionsArg.keyProvider) throw new TypeError('webOS requires an owner-supplied database and external encryption key provider.');
-      this.#store = new NoSqlConfigStore({ db: optionsArg.db, keyProvider: optionsArg.keyProvider, homeId: this.#config.homeId, integrationDomain: 'webostv' });
+      if (!options.db || !options.keyProvider) throw new TypeError('webOS requires an owner-supplied database and external encryption key provider.');
+      this.#store = new NoSqlConfigStore({ db: options.db, keyProvider: options.keyProvider, homeId: this.#context.homeId, integrationDomain: 'webostv' });
       this.#ownsStore = true;
     }
+  }
+
+  #startAbortListener(): void {
+    const signalArg = this.#context.abortSignal;
     if (signalArg) {
-      const abort = (): void => { void this.destroy(); };
-      if (signalArg.aborted) this.#lifetime.abort(new Error('webOS setup was aborted.'));
+      const abort = (): void => { void this.destroy().catch(() => undefined); };
+      if (signalArg.aborted) abort();
       else { signalArg.addEventListener('abort', abort, { once: true }); this.#removeExternalAbort = () => signalArg.removeEventListener('abort', abort); }
     }
   }
@@ -66,55 +77,99 @@ export class WebostvClient {
 
   public async getSnapshot(signalArg?: AbortSignal): Promise<IWebostvSnapshot> {
     if (signalArg?.aborted) throw new Error('webOS snapshot was aborted.');
-    if (!this.#start) this.#start = this.#initialize().catch(async (errorArg: unknown) => { await this.destroy(); throw errorArg; });
+    if (!this.#start) {
+      if (this.#destroy) throw new Error('webOS client is closed.');
+      // Track raw startup before foreign work; its rejection handler joins close only after settlement.
+      this.#start = this.#track(() => this.#initialize()).catch(async (errorArg: unknown) => {
+        try { await this.destroy(); }
+        catch (cleanupErrorArg) { throw new AggregateError([errorArg, cleanupErrorArg], 'webOS setup and cleanup failed.'); }
+        throw errorArg;
+      });
+      this.#startAbortListener();
+    }
     await this.#start;
     if (signalArg?.aborted) throw new Error('webOS snapshot was aborted.');
     if (!this.#snapshot) throw new Error('webOS state is unavailable.');
     return structuredClone({ ...this.#snapshot, connected: this.isHealthy() });
   }
 
-  public async execute(commandArg: TWebostvCommand, argumentArg?: unknown, signalArg?: AbortSignal): Promise<void> {
-    if (!this.isHealthy()) throw new Error('webOS is disconnected; command was not sent.');
-    let uri: string;
-    let payload: Record<string, unknown> = {};
-    if (commandArg === 'volume_set') { uri = 'audio/setVolume'; payload = { volume: webostvInteger(argumentArg, 'volume', 0, 100) }; }
-    else if (commandArg === 'volume_mute') {
-      if (typeof argumentArg !== 'boolean') throw new TypeError('webOS mute must be boolean.');
-      uri = 'audio/setMute'; payload = { mute: argumentArg };
-    } else if (commandArg === 'select_source') {
-      const inputId = webostvString(argumentArg, 'inputId');
-      if (!this.#snapshot?.inputs.some((inputArg) => inputArg.id === inputId)) throw new TypeError('webOS input must match an advertised input id.');
-      uri = 'tv/switchInput'; payload = { inputId };
-    } else {
-      if (!Object.hasOwn(commandEndpoints, commandArg) || argumentArg !== undefined) throw new TypeError('Unsupported webOS command or extra arguments.');
-      uri = commandEndpoints[commandArg];
-    }
-    await this.#request('request', uri, payload, undefined, signalArg);
+  public execute(commandArg: TWebostvCommand, argumentArg?: unknown, signalArg?: AbortSignal): Promise<IWebostvCommandResult> {
+    return this.#track(async () => {
+      if (!this.#allowedCommands.includes(commandArg)) throw new Error('webOS command is not authorized by its owner.');
+      if (!this.isHealthy()) throw new Error('webOS is disconnected; command was not sent.');
+      let uri: string;
+      let payload: Record<string, unknown> = {};
+      if (commandArg === 'volume_set') { uri = 'audio/setVolume'; payload = { volume: webostvInteger(argumentArg, 'volume', 0, 100) }; }
+      else if (commandArg === 'volume_mute') {
+        if (typeof argumentArg !== 'boolean') throw new TypeError('webOS mute must be boolean.');
+        uri = 'audio/setMute'; payload = { mute: argumentArg };
+      } else if (commandArg === 'select_source') {
+        const inputId = webostvString(argumentArg, 'inputId');
+        if (!this.#snapshot?.inputs.some((inputArg) => inputArg.id === inputId)) throw new TypeError('webOS input must match an advertised input id.');
+        uri = 'tv/switchInput'; payload = { inputId };
+      } else {
+        if (!Object.hasOwn(commandEndpoints, commandArg) || argumentArg !== undefined) throw new TypeError('Unsupported webOS command or extra arguments.');
+        uri = commandEndpoints[commandArg];
+      }
+      await this.#request('request', uri, payload, undefined, signalArg);
+      // Correlated acceptance is not proof of physical completion. Read state independently.
+      try {
+        const observed: Partial<IWebostvSnapshot> = {};
+        for (const [field, endpoint] of Object.entries(endpoints)) {
+          this.#applyState(observed, field as keyof typeof endpoints, await this.#request('request', endpoint, {}, undefined, signalArg));
+        }
+        if (!this.isHealthy() || !this.#snapshot) throw new Error('webOS observation is unavailable.');
+        const observation = { ...this.#snapshot, ...observed, observedAt: new Date().toISOString() };
+        return { acknowledgement: 'tv-response', physicalCompletion: 'unverified', observationStatus: 'observed', observation: structuredClone(observation) };
+      } catch {
+        return { acknowledgement: 'tv-response', physicalCompletion: 'unverified', observationStatus: 'unavailable' };
+      }
+    });
   }
 
-  public async subscribe(handlerArg: (eventArg: TWebostvClientEvent) => void, signalArg?: AbortSignal): Promise<() => Promise<void>> {
+  public async subscribe(handlerArg: TWebostvClientHandler, signalArg?: AbortSignal): Promise<() => Promise<void>> {
     await this.getSnapshot(signalArg);
     if (signalArg?.aborted || this.#lifetime.signal.aborted) throw new Error('webOS subscription was aborted.');
     if (this.#handlers.size >= 128) throw new Error('webOS subscriber capacity reached.');
-    const subscriber = (eventArg: TWebostvClientEvent): void => handlerArg(eventArg);
+    if (typeof handlerArg !== 'function') throw new TypeError('webOS subscriber must be a function.');
+    const subscriber: TWebostvClientHandler = (eventArg) => handlerArg(eventArg);
     this.#handlers.add(subscriber);
     const remove = (): void => { this.#handlers.delete(subscriber); this.#handlerCleanups.delete(subscriber); signalArg?.removeEventListener('abort', remove); };
     this.#handlerCleanups.set(subscriber, remove);
     signalArg?.addEventListener('abort', remove, { once: true });
-    return async () => remove();
+    return async () => {
+      remove();
+      await Promise.allSettled([...(this.#handlerOperations.get(subscriber) ?? [])]);
+    };
   }
 
   public destroy(): Promise<void> {
     if (this.#destroy) return this.#destroy;
-    this.#destroy = this.#close();
+    this.#destroy = Promise.resolve().then(() => this.#close());
+    this.#ready = false;
+    this.#lifetime.abort(new Error('webOS client was closed.'));
     return this.#destroy;
   }
 
+  public retryCleanup(): Promise<void> {
+    if (!this.#destroy) return Promise.reject(new Error('webOS cleanup retry requires terminal close.'));
+    if (!this.#retry) {
+      const retry = Promise.resolve().then(async () => {
+        await this.#destroy!.catch(() => undefined);
+        if (this.#ownsStore) await this.#store.retryCleanup();
+      });
+      this.#retry = retry;
+      const settled = (): void => { this.#retry = undefined; };
+      void retry.then(settled, settled);
+    }
+    return this.#retry;
+  }
+
   async #close(): Promise<void> {
-    this.#ready = false;
-    this.#lifetime.abort(new Error('webOS client was closed.'));
     this.#removeExternalAbort();
     const closeStore = this.#ownsStore ? this.#store.close() : Promise.resolve();
+    // Install a rejection handler immediately; socket shutdown and callback drainage run concurrently.
+    const storeResult = Promise.allSettled([closeStore]);
     clearInterval(this.#heartbeat);
     for (const request of this.#pending.values()) { clearTimeout(request.timer); request.cleanup(); request.reject(new Error('webOS connection closed; effects already sent have an indeterminate outcome.')); }
     this.#pending.clear(); this.#subscriptions.clear();
@@ -122,23 +177,21 @@ export class WebostvClient {
     for (const cleanup of [...this.#handlerCleanups.values()]) cleanup();
     this.#handlers.clear();
     const socket = this.#socket;
-    if (!socket || socket.readyState === plugins.ws.WebSocket.CLOSED) { await Promise.all([closeStore, this.#storage?.catch(() => undefined)]); return; }
-    await new Promise<void>((resolveArg) => {
+    if (socket && socket.readyState !== plugins.ws.WebSocket.CLOSED) await new Promise<void>((resolveArg) => {
       const timer = setTimeout(() => { socket.terminate(); }, 1000);
       socket.once('close', () => { clearTimeout(timer); socket.removeAllListeners(); resolveArg(); });
       if (socket.readyState === plugins.ws.WebSocket.CONNECTING) socket.terminate();
       else socket.close(1000);
     });
-    await Promise.all([closeStore, this.#storage?.catch(() => undefined)]);
+    await Promise.allSettled([...this.#operations, ...[...this.#handlerOperations.values()].flatMap((operationsArg) => [...operationsArg])]);
+    const [result] = await storeResult;
+    if (result.status === 'rejected') throw new Error('webOS encrypted pairing cleanup failed; explicit retryCleanup is required.');
   }
 
   async #persist<TResult>(operationArg: () => Promise<TResult>): Promise<TResult> {
     if (this.#lifetime.signal.aborted) throw new Error('webOS persistence was aborted.');
-    const operation = operationArg();
-    this.#storage = operation;
-    try { return await operation; }
+    try { return await operationArg(); }
     catch { throw new Error(this.#lifetime.signal.aborted ? 'webOS persistence was aborted.' : 'webOS encrypted pairing storage failed.'); }
-    finally { if (this.#storage === operation) this.#storage = undefined; }
   }
 
   async #initialize(): Promise<IWebostvSnapshot> {
@@ -157,7 +210,8 @@ export class WebostvClient {
     const hello = await this.#request('hello', undefined, { appId: 'exchange.smarthome', appName: 'smarthome.exchange' });
     if (hello.deviceUUID !== this.#config.expectedDeviceUUID) throw new Error('webOS hello device UUID does not match the verified TV.');
     // New webOS requires this request before registration; permission denial fails setup explicitly.
-    await this.#request('request', 'system/getSystemInfo', {});
+    const systemInfo = await this.#request('request', 'system/getSystemInfo', {});
+    const model = systemInfo.modelName === undefined ? undefined : webostvString(systemInfo.modelName, 'reported model');
     const registered = await this.#request('register', undefined, {
       pairingType: 'PROMPT', ...(clientKey ? { 'client-key': clientKey } : {}),
       manifest: { manifestVersion: 1, appVersion: '1.0', permissions },
@@ -178,7 +232,7 @@ export class WebostvClient {
       await this.#request('subscribe', uri, {}, (payloadArg) => update(field as keyof typeof endpoints, payloadArg));
     }
     if (initial.powerState === undefined || initial.volume === undefined || initial.muted === undefined || initial.currentAppId === undefined || initial.inputs === undefined) throw new Error('webOS did not supply a complete initial state.');
-    this.#snapshot = { homeId: this.#config.homeId, deviceUUID: this.#config.expectedDeviceUUID, name: this.#config.name!, connected: true, powerState: initial.powerState, volume: initial.volume, muted: initial.muted, currentAppId: initial.currentAppId, inputs: initial.inputs, observedAt: new Date().toISOString() };
+    this.#snapshot = { homeId: this.#context.homeId, deviceUUID: this.#config.expectedDeviceUUID, name: this.#config.name!, model, authorizedCommands: this.#allowedCommands, connected: true, powerState: initial.powerState, volume: initial.volume, muted: initial.muted, currentAppId: initial.currentAppId, inputs: initial.inputs, observedAt: new Date().toISOString() };
     if (this.#lifetime.signal.aborted || this.#socket?.readyState !== plugins.ws.WebSocket.OPEN) throw new Error('webOS connection closed during setup.');
     this.#ready = true;
     this.#heartbeat = setInterval(() => {
@@ -288,13 +342,32 @@ export class WebostvClient {
       request.reject(request.type === 'request' ? new Error(`${errorArg.message} Effects already sent have an indeterminate outcome.`) : errorArg);
     }
     this.#pending.clear();
-    void this.destroy();
+    void this.destroy().catch(() => undefined);
   }
 
   #emit(eventArg: TWebostvClientEvent): void {
     for (const handler of [...this.#handlers]) {
-      try { handler(eventArg.type === 'state' ? { ...eventArg, snapshot: structuredClone(eventArg.snapshot) } : eventArg); }
-      catch { this.#handlerCleanups.get(handler)?.(); }
+      const operations = this.#handlerOperations.get(handler) ?? new Set<Promise<void>>();
+      this.#handlerOperations.set(handler, operations);
+      const event = eventArg.type === 'state' ? { ...eventArg, snapshot: structuredClone(eventArg.snapshot) } : eventArg;
+      // Publish callback ownership before invoking user code, including close reentry.
+      const operation = Promise.resolve().then(() => {
+        const result = handler(event);
+        // A terminal callback may return the very close it triggered; never make close await itself.
+        return result === this.#destroy ? undefined : result;
+      }).catch(() => { this.#handlerCleanups.get(handler)?.(); });
+      operations.add(operation);
+      void operation.then(() => {
+        operations.delete(operation);
+        if (!operations.size) this.#handlerOperations.delete(handler);
+      });
     }
   }
+
+  #track<TResult>(operationArg: () => Promise<TResult>): Promise<TResult> {
+    const operation = Promise.resolve().then(operationArg);
+    this.#operations.add(operation);
+    void operation.then(() => this.#operations.delete(operation), () => this.#operations.delete(operation));
+    return operation;
+  }
 }

package/ts/integrations/webostv/webostv.classes.configflow.ts

@@ -1,22 +1,42 @@
-import type { IConfigFlow, IConfigFlowContext, IConfigFlowStep, IDiscoveryCandidate } from '../../core/types.js';
+import { NativeIntegrationOwner, type INativeIntegrationOwnerOptions, type NativeIntegrationScope } from '../../core/classes.nativeintegrationowner.js';
+import type { IConfigFlow, IConfigFlowStep, IDiscoveryCandidate, INativeConfigFlowContext } from '../../core/types.js';
 import { createWebostvDiscoveryDescriptor } from './webostv.discovery.js';
 import type { IWebostvConfig } from './webostv.types.js';
 import { normalizeWebostvConfig, webostvKeys, webostvObject } from './webostv.validation.js';
 
 export class WebostvConfigFlow implements IConfigFlow<IWebostvConfig> {
-  public async start(candidateArg: IDiscoveryCandidate, contextArg: IConfigFlowContext): Promise<IConfigFlowStep<IWebostvConfig>> {
-    const result = await createWebostvDiscoveryDescriptor().getValidators()[0].validate(candidateArg, contextArg);
-    if (!result.matched || !result.candidate) return { kind: 'error', error: result.reason };
-    const candidate = result.candidate;
-    return { kind: 'form', title: 'Pair verified LG webOS TV', description: 'The host must supply an encrypted database and external key provider. Prompt mode requires confirmation on the TV.',
-      fields: [{ name: 'homeId', label: 'Home id', type: 'text', required: true }, { name: 'pairingMode', label: 'Pairing mode', type: 'select', required: true, options: [{ label: 'Use durable existing pairing', value: 'existing' }, { label: 'Confirm new pairing on TV', value: 'prompt' }] }, { name: 'allowUnencryptedConnection', label: 'Allow explicit cleartext local endpoint', type: 'boolean' }],
-      submit: async (valuesArg) => {
-        try {
-          const values = webostvObject(valuesArg, 'webOS config flow values'); webostvKeys(values, ['homeId', 'pairingMode', 'allowUnencryptedConnection', 'certificateAuthority']);
-          const config = normalizeWebostvConfig({ ...values, endpoint: candidate.metadata!.endpoint, expectedDeviceUUID: candidate.metadata!.expectedDeviceUUID, name: candidate.name } as IWebostvConfig);
-          return { kind: 'done', config };
-        } catch (errorArg) { return { kind: 'error', error: errorArg instanceof Error ? errorArg.message : 'Invalid webOS config.' }; }
-      },
-    };
+  readonly #owner: NativeIntegrationOwner;
+  readonly #scope: NativeIntegrationScope;
+  readonly #ownsOwner: boolean;
+
+  constructor(optionsArg: INativeIntegrationOwnerOptions = {}, ownerArg?: NativeIntegrationOwner) {
+    this.#owner = ownerArg ?? new NativeIntegrationOwner('webostv', optionsArg);
+    this.#ownsOwner = ownerArg === undefined;
+    this.#scope = this.#owner.createFlowScope();
+  }
+
+  public start(candidateArg: IDiscoveryCandidate, contextArg: INativeConfigFlowContext): Promise<IConfigFlowStep<IWebostvConfig>> {
+    const context = this.#scope.admit(contextArg);
+    return this.#scope.run(context, undefined, async () => {
+      const result = await createWebostvDiscoveryDescriptor().getValidators()[0].validate(candidateArg, context);
+      if (!result.matched || !result.candidate) return { kind: 'error', error: result.reason };
+      const candidate = result.candidate;
+      return { kind: 'form', title: 'Pair verified LG webOS TV', description: 'Pairing uses the selected home. Prompt mode requires confirmation on the TV.',
+        fields: [{ name: 'pairingMode', label: 'Pairing mode', type: 'select', required: true, options: [{ label: 'Use durable existing pairing', value: 'existing' }, { label: 'Confirm new pairing on TV', value: 'prompt' }] }, { name: 'allowUnencryptedConnection', label: 'Allow explicit cleartext local endpoint', type: 'boolean' }],
+        submit: async (valuesArg) => {
+          try {
+            return await this.#scope.run(context, context.homeId, async () => {
+              const values = webostvObject(valuesArg, 'webOS config flow values');
+              webostvKeys(values, ['pairingMode', 'allowUnencryptedConnection', 'certificateAuthority']);
+              const config = normalizeWebostvConfig({ ...values, homeId: context.homeId, endpoint: candidate.metadata!.endpoint, expectedDeviceUUID: candidate.metadata!.expectedDeviceUUID, name: candidate.name } as IWebostvConfig);
+              return { kind: 'done', config };
+            });
+          } catch (errorArg) { return { kind: 'error', error: errorArg instanceof Error ? errorArg.message : 'Invalid webOS config.' }; }
+        },
+      };
+    });
   }
+
+  public close(): Promise<void> { return this.#ownsOwner ? this.#owner.close() : this.#scope.close(); }
+  public retryCleanup(): Promise<void> { return this.#ownsOwner ? this.#owner.retryCleanup() : this.#scope.retryCleanup(); }
 }

package/ts/integrations/webostv/webostv.classes.integration.ts

@@ -1,14 +1,14 @@
 import * as plugins from '../../plugins.js';
 import { BaseIntegration } from '../../core/classes.baseintegration.js';
-import { NoSqlConfigStore } from '../../core/classes.configstore.js';
-import type { IDeviceFeatureWriteRequest, IIntegrationEntity, IIntegrationEvent, IIntegrationRuntime, IIntegrationSetupContext, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
+import { NativeIntegrationOwner } from '../../core/classes.nativeintegrationowner.js';
+import type { IDeviceFeatureWriteRequest, IIntegrationEntity, IIntegrationEvent, IIntegrationRuntime, INativeIntegrationSetupContext, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
 import { WebostvClient } from './webostv.classes.client.js';
 import { WebostvConfigFlow } from './webostv.classes.configflow.js';
 import { createWebostvDiscoveryDescriptor } from './webostv.discovery.js';
 import { WebostvMapper } from './webostv.mapper.js';
 import type { IWebostvConfig, IWebostvIntegrationOptions, IWebostvSnapshot, TWebostvCommand } from './webostv.types.js';
 import { webostvProfile } from './webostv.types.js';
-import { webostvKeys, webostvObject } from './webostv.validation.js';
+import { normalizeWebostvConfig, normalizeWebostvOptions, webostvKeys, webostvObject } from './webostv.validation.js';
 
 export class WebostvIntegration extends BaseIntegration<IWebostvConfig> {
   public readonly domain = 'webostv';
@@ -16,51 +16,58 @@ export class WebostvIntegration extends BaseIntegration<IWebostvConfig> {
   public readonly status = 'control-runtime' as const;
   public readonly metadata = webostvProfile.metadata;
   public readonly discoveryDescriptor = createWebostvDiscoveryDescriptor();
-  public readonly configFlow = new WebostvConfigFlow();
-  readonly #runtimes = new Set<WebostvRuntime>();
-  readonly #pending = new Set<WebostvClient>();
-  #destroyed = false;
+  public readonly configFlow: WebostvConfigFlow;
+  readonly #owner: NativeIntegrationOwner;
+  readonly #options: Readonly<IWebostvIntegrationOptions>;
   #destroy?: Promise<void>;
 
-  constructor(private readonly options?: IWebostvIntegrationOptions) { super(); }
-
-  public async setup(configArg: IWebostvConfig, contextArg: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
-    if (this.#destroyed) throw new Error('webOS integration is destroyed.');
-    if (contextArg.configStore !== undefined && !(contextArg.configStore instanceof NoSqlConfigStore)) throw new TypeError('webOS runtime context requires an encrypted NoSqlConfigStore.');
-    const client = new WebostvClient(configArg, contextArg.configStore ?? this.options, contextArg.abortSignal);
-    this.#pending.add(client);
-    try {
-      const snapshot = await client.getSnapshot(contextArg.abortSignal);
-      if (this.#destroyed) throw new Error('webOS integration was destroyed during setup.');
-      const runtime = new WebostvRuntime(client, snapshot, () => this.#runtimes.delete(runtime));
-      this.#runtimes.add(runtime);
-      return runtime;
-    } catch (errorArg) { await client.destroy(); throw errorArg; }
-    finally { this.#pending.delete(client); }
+  constructor(optionsArg: IWebostvIntegrationOptions = {}) {
+    super();
+    this.#options = normalizeWebostvOptions(optionsArg);
+    this.#owner = new NativeIntegrationOwner(this.domain, { homeId: this.#options.homeId, capacity: this.#options.capacity });
+    this.configFlow = new WebostvConfigFlow({}, this.#owner);
   }
 
-  public destroy(): Promise<void> {
-    if (this.#destroy) return this.#destroy;
-    this.#destroyed = true;
-    this.#destroy = Promise.all([...this.#runtimes].map((runtimeArg) => runtimeArg.destroy()).concat([...this.#pending].map((clientArg) => clientArg.destroy()))).then(() => undefined);
-    return this.#destroy;
+  public setup(configArg: IWebostvConfig, contextArg: INativeIntegrationSetupContext): Promise<IIntegrationRuntime> {
+    const config = normalizeWebostvConfig(configArg);
+    return this.#owner.runSetup(contextArg, config.homeId, async (leaseArg) => {
+      const client = new WebostvClient(config, leaseArg.context, this.#options);
+      let cleanupStarted = false;
+      leaseArg.own(() => {
+        if (cleanupStarted) return client.retryCleanup();
+        cleanupStarted = true;
+        return client.destroy();
+      });
+      const snapshot = await client.getSnapshot();
+      leaseArg.promoteToRuntime();
+      return new WebostvRuntime(client, snapshot, () => leaseArg.close(), (promiseArg) => promiseArg === this.#destroy);
+    });
   }
+
+  public destroy(): Promise<void> { return this.#destroy ??= this.#owner.close(); }
+  public retryCleanup(): Promise<void> { return this.#owner.retryCleanup(); }
 }
 
 export class HomeAssistantWebostvIntegration extends WebostvIntegration {}
 
 class WebostvRuntime implements IIntegrationRuntime {
   public readonly domain = 'webostv';
-  constructor(private readonly client: WebostvClient, private readonly identity: IWebostvSnapshot, private readonly onDestroyed: () => void) {}
+  #destroy?: Promise<void>;
+  constructor(private readonly client: WebostvClient, private readonly identity: IWebostvSnapshot,
+    private readonly close: () => Promise<void>, private readonly isOwnerClose: (promiseArg: unknown) => boolean) {}
   public isHealthy(): boolean { return this.client.isHealthy(); }
   public async devices(signalArg?: AbortSignal): Promise<plugins.shxInterfaces.data.IDeviceDefinition[]> { return WebostvMapper.toDevices(await this.client.getSnapshot(signalArg)); }
   public async entities(): Promise<IIntegrationEntity[]> { return WebostvMapper.toEntities(await this.client.getSnapshot()); }
   public async subscribe(handlerArg: (eventArg: IIntegrationEvent) => void, signalArg?: AbortSignal): Promise<() => Promise<void>> {
+    const handler = handlerArg as (eventArg: IIntegrationEvent) => void | Promise<void>;
     return this.client.subscribe((eventArg) => {
       const base = { integrationDomain: this.domain, deviceId: WebostvMapper.deviceId(this.identity), timestamp: Date.now() };
-      if (eventArg.type === 'state') handlerArg({ ...base, type: 'state_changed', entityId: `${base.deviceId}:media_player`, data: { entity: WebostvMapper.toEntities(eventArg.snapshot)[0] } });
-      else if (eventArg.type === 'availability') handlerArg({ ...base, type: 'availability_changed', data: { available: eventArg.available } });
-      else handlerArg({ ...base, type: 'error', data: { message: eventArg.error.message } });
+      const result = eventArg.type === 'state'
+        ? handler({ ...base, type: 'state_changed', entityId: `${base.deviceId}:media_player`, data: { entity: WebostvMapper.toEntities(eventArg.snapshot)[0] } })
+        : eventArg.type === 'availability'
+          ? handler({ ...base, type: 'availability_changed', data: { available: eventArg.available } })
+          : handler({ ...base, type: 'error', data: { message: eventArg.error.message } });
+      return result === this.#destroy || this.isOwnerClose(result) ? undefined : result;
     }, signalArg);
   }
 
@@ -81,8 +88,7 @@ class WebostvRuntime implements IIntegrationRuntime {
       else if (service === 'volume_mute') { webostvKeys(data, ['mute']); argument = data.mute; }
       else if (service === 'select_source') { webostvKeys(data, ['inputId']); argument = data.inputId; }
       else webostvKeys(data, []);
-      await this.client.execute(service as TWebostvCommand, argument);
-      return { success: true, data: { acknowledgement: 'tv-response', state: 'observe-subscriptions' } };
+      return { success: true, data: await this.client.execute(service as TWebostvCommand, argument) };
     } catch (errorArg) { return { success: false, error: errorArg instanceof Error ? errorArg.message : 'webOS operation failed.' }; }
   }
 
@@ -92,11 +98,12 @@ class WebostvRuntime implements IIntegrationRuntime {
       const device = webostvObject(request.device, 'feature device');
       const feature = webostvObject(request.feature, 'feature');
       if (device.id !== WebostvMapper.deviceId(this.identity) || device.integrationDomain !== this.domain) throw new Error('webOS feature device is not owned by this runtime.');
-      if (feature.id === 'volume') await this.client.execute('volume_set', request.value, signalArg);
-      else if (feature.id === 'muted') await this.client.execute('volume_mute', request.value, signalArg);
+      let result;
+      if (feature.id === 'volume') result = await this.client.execute('volume_set', request.value, signalArg);
+      else if (feature.id === 'muted') result = await this.client.execute('volume_mute', request.value, signalArg);
       else throw new Error('webOS feature is not writable.');
-      return { success: true, data: { acknowledgement: 'tv-response', state: 'observe-subscriptions' } };
+      return { success: true, data: result };
     } catch (errorArg) { return { success: false, error: errorArg instanceof Error ? errorArg.message : 'webOS feature write failed.' }; }
   }
-  public async destroy(): Promise<void> { await this.client.destroy(); this.onDestroyed(); }
+  public destroy(): Promise<void> { return this.#destroy ??= this.close(); }
 }

package/ts/integrations/webostv/webostv.mapper.ts

@@ -13,15 +13,15 @@ export class WebostvMapper {
     ];
     return [{
       id: this.deviceId(snapshotArg), integrationDomain: 'webostv', name: snapshotArg.name,
-      protocol: 'http', manufacturer: 'LG', model: 'webOS TV', online: snapshotArg.connected,
+      protocol: 'http', manufacturer: 'LG', model: snapshotArg.model, online: snapshotArg.connected,
       features: [
         { id: 'power', capability: 'media', name: 'Power state', readable: true, writable: false },
-        { id: 'volume', capability: 'media', name: 'Volume', readable: true, writable: true, unit: '%' },
-        { id: 'muted', capability: 'media', name: 'Muted', readable: true, writable: true },
+        { id: 'volume', capability: 'media', name: 'Volume', readable: true, writable: snapshotArg.connected && snapshotArg.authorizedCommands.includes('volume_set'), unit: '%' },
+        { id: 'muted', capability: 'media', name: 'Muted', readable: true, writable: snapshotArg.connected && snapshotArg.authorizedCommands.includes('volume_mute') },
         { id: 'current_app', capability: 'media', name: 'Foreground application', readable: true, writable: false },
       ],
       state: states.map(([featureId, value]) => ({ featureId, value, updatedAt: snapshotArg.observedAt })),
-      metadata: { homeId: snapshotArg.homeId, deviceUUID: snapshotArg.deviceUUID, transport: 'ssap-websocket', inputs: structuredClone(snapshotArg.inputs) },
+      metadata: { homeId: snapshotArg.homeId, deviceUUID: snapshotArg.deviceUUID, transport: 'ssap-websocket', inputs: structuredClone(snapshotArg.inputs), authorizedCommands: [...snapshotArg.authorizedCommands], modelKnown: snapshotArg.model !== undefined },
     }];
   }
 

package/ts/integrations/webostv/webostv.types.ts

@@ -1,5 +1,6 @@
 import type * as plugins from '../../plugins.js';
 import type { IConfigEncryptionKeyProvider } from '../../core/classes.configstore.js';
+import type { INativeIntegrationOwnerOptions } from '../../core/classes.nativeintegrationowner.js';
 
 export const webostvDomain = 'webostv';
 export const webostvDefaultName = 'LG webOS TV';
@@ -19,9 +20,11 @@ export interface IWebostvConfig {
   maxPendingRequests?: number;
 }
 
-export interface IWebostvIntegrationOptions {
-  db: plugins.nosqldb.SmartdataDb;
-  keyProvider: IConfigEncryptionKeyProvider;
+export interface IWebostvIntegrationOptions extends INativeIntegrationOwnerOptions {
+  db?: plugins.nosqldb.SmartdataDb;
+  keyProvider?: IConfigEncryptionKeyProvider;
+  /** Runtime-only owner permission. An omitted or empty list authorizes no effects. */
+  allowedCommands?: readonly TWebostvCommand[];
 }
 
 export interface IHomeAssistantWebostvConfig extends IWebostvConfig {}
@@ -30,7 +33,10 @@ export interface IWebostvSnapshot {
   homeId: string;
   deviceUUID: string;
   name: string;
+  /** Actual system/getSystemInfo modelName, absent when the TV did not report one. */
+  model?: string;
   connected: boolean;
+  authorizedCommands: readonly TWebostvCommand[];
   powerState: string;
   volume: number;
   muted: boolean;
@@ -45,6 +51,15 @@ export type TWebostvClientEvent =
   | { type: 'error'; error: Error };
 export type TWebostvCommand = 'turn_on' | 'turn_off' | 'volume_set' | 'volume_up' | 'volume_down' | 'volume_mute' | 'select_source' | 'media_play' | 'media_pause' | 'media_stop';
 
+export interface IWebostvCommandResult {
+  acknowledgement: 'tv-response';
+  physicalCompletion: 'unverified';
+  observationStatus: 'observed' | 'unavailable';
+  observation?: IWebostvSnapshot;
+}
+
+export type TWebostvClientHandler = (eventArg: TWebostvClientEvent) => void | Promise<void>;
+
 export const webostvProfile = {
   domain: webostvDomain, displayName: webostvDefaultName, status: 'control-runtime',
   metadata: { source: 'home-assistant/core', upstreamDomain: webostvDomain, localApi: { implemented: ['verified SSAP registration', 'encrypted durable pairing keys', 'authoritative state subscriptions'], explicitUnsupported: ['fixture or injected-client production configs', 'deep standby wake-on-LAN', 'next/previous media track', 'automatic command replay'] } },

package/ts/integrations/webostv/webostv.validation.ts

@@ -1,4 +1,25 @@
-import type { IWebostvConfig } from './webostv.types.js';
+import type { IWebostvConfig, IWebostvIntegrationOptions, TWebostvCommand } from './webostv.types.js';
+
+export const webostvCommands: readonly TWebostvCommand[] = Object.freeze(['turn_on', 'turn_off', 'volume_set', 'volume_up', 'volume_down', 'volume_mute', 'select_source', 'media_play', 'media_pause', 'media_stop']);
+
+export const normalizeWebostvOptions = (valueArg: IWebostvIntegrationOptions = {}): Readonly<IWebostvIntegrationOptions> => {
+  const value = webostvObject(valueArg, 'webOS owner options');
+  webostvKeys(value, ['homeId', 'capacity', 'db', 'keyProvider', 'allowedCommands']);
+  if ((value.db === undefined) !== (value.keyProvider === undefined)) throw new TypeError('webOS persistence requires both database and keyProvider.');
+  const commands = value.allowedCommands ?? [];
+  if (!Array.isArray(commands) || commands.length > webostvCommands.length || Reflect.ownKeys(commands).some((keyArg) => {
+    const descriptor = Object.getOwnPropertyDescriptor(commands, keyArg);
+    return typeof keyArg !== 'string' || !descriptor || !('value' in descriptor) || (keyArg !== 'length' && !/^(0|[1-9][0-9]*)$/.test(keyArg));
+  })) throw new TypeError('webOS allowedCommands must be a finite data array.');
+  const captured: TWebostvCommand[] = [];
+  for (let index = 0; index < commands.length; index += 1) {
+    const command: unknown = Object.getOwnPropertyDescriptor(commands, String(index))?.value;
+    if (typeof command !== 'string' || !webostvCommands.includes(command as TWebostvCommand) || captured.includes(command as TWebostvCommand)) throw new TypeError('webOS allowedCommands contains an unsupported or duplicate command.');
+    captured.push(command as TWebostvCommand);
+  }
+  return Object.freeze({ homeId: value.homeId as string | undefined, capacity: value.capacity as number | undefined,
+    db: value.db as IWebostvIntegrationOptions['db'], keyProvider: value.keyProvider as IWebostvIntegrationOptions['keyProvider'], allowedCommands: Object.freeze(captured) });
+};
 
 export const webostvObject = (valueArg: unknown, nameArg: string): Record<string, unknown> => {
   if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg) || ![Object.prototype, null].includes(Object.getPrototypeOf(valueArg))) throw new TypeError(`${nameArg} must be a plain object.`);