@smarthome.exchange/integrations 1.0.0 → 3.0.0

package/ts/integrations/webostv/readme.md

@@ -1,35 +1,69 @@
-# Native LG webOS TV
+# LG webOS TV
 
-`WebostvIntegration` and the exported `HomeAssistantWebostvIntegration` constructor speak the TV's documented SSAP WebSocket protocol. Setup verifies an explicitly configured TV UUID, registers, persists the returned pairing credential encrypted, and obtains complete initial power, volume, mute, foreground-app and input-list subscriptions before exposing a runtime.
+The native runtime pairs with a verified TV through its SSAP WebSocket endpoint,
+stores pairing keys encrypted in the host's database, and observes power, volume,
+mute, foreground application and external inputs through authoritative subscriptions.
+It uses the installed `ws` transport and requires no Home Assistant server.
+`HomeAssistantWebostvIntegration` remains an exported constructor alias.
 
 ```typescript
-const integration = new WebostvIntegration({ db, keyProvider });
+const integration = new WebostvIntegration({
+  db,
+  keyProvider,
+  allowedCommands: ['volume_set', 'volume_mute'],
+});
 const runtime = await integration.setup({
-  homeId: 'home-one',
-  endpoint: 'wss://verified-tv.example:3001/',
+  homeId: 'home:example',
+  endpoint: 'wss://tv.example:3001/',
   expectedDeviceUUID: verifiedDeviceUUID,
   pairingMode: 'prompt',
-  certificateAuthority: verifiedPemCertificateChain,
-}, {});
-const device = (await runtime.devices())[0];
-await runtime.callService!({
-  domain: 'media_player', service: 'volume_set',
-  target: { deviceId: device.id }, data: { volume: 25 },
+  certificateAuthority: ownerCertificateChain,
+}, { homeId: 'home:example', abortSignal });
+
+const [device] = await runtime.devices();
+const result = await runtime.callService!({
+  domain: 'webostv',
+  service: 'volume_set',
+  target: { deviceId: device.id },
+  data: { volume: 25 },
 });
 await integration.destroy();
 ```
 
-The default registry's no-argument constructor also supports `setup(config, { configStore })`, where `configStore` is an actual `NoSqlConfigStore` whose public `getScope()` exactly matches the configured home and `webostv` domain. Generic stores and other scopes fail before connection; an invalid provided store never falls back to constructor options. A correctly scoped context store takes precedence over constructor persistence options.
+The host independently selects `context.homeId`. The integration binds that home
+once, including through config flow and failed setup. An optional constructor
+`homeId` constrains the selected context. Configuration, discovery, form values
+and database scope cannot select a home or grant control. Config flow captures
+the selected home and rejects submitted home fields. Its forms stop accepting
+submissions after flow close or integration destruction.
 
-The caller owns `db` and the external `keyProvider` (`currentKey(signal)` / `keyForId(id, signal)`, 32-byte keys). The integration constructs the existing `NoSqlConfigStore` in the immutable `homeId` / `webostv` scope. The pairing record also binds the exact endpoint and TV UUID. Accepted keys are durably stored before subscription setup; storage failure closes setup. There is no filesystem or memory-only credential fallback. `existing` mode rejects any prompt response and closes the connection; the TV may briefly display its prompt before that close. It never waits for or accepts fresh pairing in that mode. Explicit `prompt` mode permits a user to approve initial/rejected-key registration on the TV; a valid stored key is still reused. No key appears in device state, events, command receipts or errors.
+The exported client has the same host boundary:
+`new WebostvClient(config, { homeId, abortSignal }, options)`. Construction performs
+no pairing, provider calls or transport I/O. Setup requires either constructor
+`db` and `keyProvider` together, or an actual `NoSqlConfigStore` in the context
+with the exact selected home and `webostv` domain. Scope checks call the genuine
+store implementation; overriding `getScope` cannot grant ownership. Context
+stores, databases and key providers remain caller-owned.
+The provider supplies 32-byte keys through `currentKey(signal)` and
+`keyForId(id, signal)`. A correctly scoped context store takes precedence over
+constructor persistence; an invalid supplied store fails without falling back.
 
-Use the TV's independently verified UUID and endpoint; discovery supplies no network probes or identity verification by itself. Only explicit manual candidates with `integrationDomain: 'webostv'` and metadata `{ endpoint, expectedDeviceUUID }` are accepted. WSS uses normal certificate-chain and hostname validation, optionally with the supplied PEM CA chain. TLS verification is never disabled. A deliberately selected cleartext local `ws://...:3000/` endpoint requires `allowUnencryptedConnection: true`; its UUID check is a device selection check and provides no cryptographic protection against an attacker on that network. No automatic WS downgrade, redirects or endpoint guessing occur.
+Every effect defaults to denied. The host supplies a copied, immutable
+`allowedCommands` list in constructor options. The supported exact values are
+`turn_on`, `turn_off`, `volume_set`, `volume_up`, `volume_down`, `volume_mute`,
+`select_source`, `media_play`, `media_pause` and `media_stop`. Unknown, duplicate,
+sparse or accessor-bearing lists are rejected. Saved configuration and form
+values cannot set permissions. Volume and mute features are writable only while
+connected and explicitly authorized. Service targets and feature writes must
+refer to this runtime's home-prefixed device and media-player entity; input
+selection requires an advertised input ID. Deep-standby wake-on-LAN and
+next/previous track controls are unsupported.
 
-Supported exact-target services in `webostv` or `media_player`:
+Services accept the `webostv` or `media_player` domain with these exact arguments:
 
-| Service | Exact data | SSAP endpoint |
+| Service | Data | SSAP endpoint |
 | --- | --- | --- |
-| `status`, `snapshot` | none | Last authoritative subscribed state, with current connection availability |
+| `status`, `snapshot` | none | Last authoritative subscribed state and current availability |
 | `volume_set` | `{ volume: integer 0..100 }` | `audio/setVolume` |
 | `volume_up`, `volume_down` | none | `audio/volumeUp`, `audio/volumeDown` |
 | `volume_mute` | `{ mute: boolean }` | `audio/setMute` |
@@ -37,12 +71,71 @@ Supported exact-target services in `webostv` or `media_player`:
 | `media_play`, `media_pause`, `media_stop` | none | `media.controls/play`, `/pause`, `/stop` |
 | `turn_on`, `turn_off` | none | `system/turnOn`, `system/turnOff` |
 
-Calls require the connected home-scoped device id or its exact media-player entity id. Foreign domains/devices/entities, unknown services, extra arguments, accessors, arbitrary input ids and out-of-range volume fail before command I/O. `writeFeature` accepts only the owned `volume` and `muted` features with validated values. Power state and foreground-app features are read only.
+The TV must report the expected UUID before an existing pairing key is sent.
+Stored keys are bound to both UUID and endpoint. `prompt` explicitly permits
+pairing confirmation on the TV; `existing` refuses absent or rejected durable
+pairing. TLS certificate validation stays enabled, and an owner-supplied PEM
+chain can establish trust. Cleartext `ws` requires explicit
+`allowUnencryptedConnection: true`. Credentials in endpoints, arbitrary URL
+paths and fixture/injected-client production configs are rejected.
+Discovery admits only explicit manual candidates with the domain and metadata
+`{ endpoint, expectedDeviceUUID }`; it does not probe or verify a TV. Cleartext
+UUID selection provides no cryptographic authentication. There is no automatic
+WS downgrade, endpoint guessing, filesystem persistence or credential fallback.
+The accepted key is stored before subscriptions start. Existing mode never
+accepts fresh pairing, though the TV may display a prompt before disconnection.
+
+A successful command receipt reports `acknowledgement: 'tv-response'` and
+`physicalCompletion: 'unverified'`. Independent one-shot reads of the documented
+state endpoints produce `observationStatus: 'observed'` and an observation when
+available. Failure to read back an already accepted command produces
+`observationStatus: 'unavailable'`; it never replays the command or substitutes
+cached state as a fresh observation. Readback does not optimistically overwrite
+subscription state. Model metadata comes from `system/getSystemInfo.modelName`
+and stays absent when unreported. Owner permissions are not advertised as a
+TV-reported per-command capability list.
+Power-off timeout remains indeterminate even if the TV physically turned off.
+`turn_on` requires an already connected TV supporting that method. Media controls
+depend on the foreground application. All five state subscriptions and the
+pre-registration system-info request are required; unsupported firmware fails
+setup explicitly. Remote pointer sockets, app launching, channels and calibration
+remain outside the runtime.
+
+The owner defaults to a combined capacity of 16 pending operations, runtimes and
+retained cleanup resources. Runtime destruction releases its setup lease.
+Integration destruction is terminal and shares one close promise. The client
+publishes its close promise before cancellation and availability callbacks, then
+drains startup, commands, accepted async subscribers and owned store cleanup.
+Unsubscribe removes admission and joins callbacks already accepted for that
+subscription. Throwing or rejecting subscribers are isolated and removed.
+Callbacks can request teardown; directly returning the client, runtime or owner's close promise
+does not create a self-wait. A callback must not await teardown that is itself
+waiting for that callback to finish.
+
+Late encryption-provider cleanup failures reject close and remain retained.
+After the provider settles, explicit `retryCleanup()` acknowledges cleanup
+without replaying provider calls, pairing or commands, and without reopening
+admission. A client closes only stores it created; borrowed stores remain usable.
+Frames, pending requests, subscribers and inputs remain bounded. Heartbeat or
+malformed authoritative state closes the instance. Disconnected snapshots retain
+their observation timestamp and report unavailable. Reconnection requires a new
+setup; there is no surviving command queue.
 
-Success means a correlated positive TV response, not verified physical completion. State changes only from validated subscription responses. A timeout, cancellation or disconnect after dispatch has an indeterminate effect outcome and is never replayed automatically. TV power-off responses are sometimes absent: that is reported as indeterminate even if the TV turns off. `turn_on` requires an already connected TV that supports that SSAP method; deep standby wake-on-LAN is not implemented. Media commands depend on the current TV application, and vendor rejections fail. Next/previous track, remote pointer sockets, app launching, channels and calibration are outside this runtime.
+Migration requires an independently selected home in setup, flow and client
+contexts, and explicit constructor command permissions for effects. The former
+client `(config, persistenceOptions, signal)` signature becomes
+`(config, { homeId, configStore?, abortSignal? }, options)`. Production `rawData`,
+`snapshot`, `snapshotProvider`, injected clients/command executors and fixture
+mapping remain unsupported; fixture data belongs only in tests.
 
-Connection, pairing and requests have bounded deadlines; frames, pending requests, inputs and subscribers have limits. Heartbeat failure closes the instance. Malformed authoritative responses fail the connection; disconnected snapshots retain their observation timestamp and report unavailable. Caller abort closes setup; `destroy()` rejects pending requests, drains current encrypted-storage work and closes the owned socket. Initialization uses the config store's bounded, cancellable collection preparation. Constructor-created config stores are closed and drained on destroy; injected context stores and the caller's database remain open. Throwing event subscribers are removed without interrupting other subscribers. Reconnection requires a new setup; no command queue survives connection loss.
+Protocol and transport references:
 
-Breaking migration: `rawData`, `snapshot`, `snapshotProvider`, injected `client` / `commandExecutor`, generic host/transport/path configuration and `WebostvMapper.toSnapshot*` fixture mapping were removed from the production webOS config. Supply the explicit native fields and constructor persistence owner above. Existing fixture-only test data belongs in a local protocol fixture, not application configuration. No existing fixture config is automatically converted because it does not prove a TV's identity or provide durable pairing credentials.
+- [SSAP endpoints in aiowebostv](https://github.com/home-assistant-libs/aiowebostv/blob/main/aiowebostv/endpoints.py)
+- [ConnectSDK webOS service](https://github.com/ConnectSDK/Connect-SDK-Android-Core/blob/master/src/com/connectsdk/service/WebOSTVService.java)
+- [ws transport documentation](https://github.com/websockets/ws/blob/master/doc/ws.md)
+- [ws on npm](https://www.npmjs.com/package/ws)
 
-Protocol sources: [LG Connect SDK socket registration and hello](https://github.com/ConnectSDK/Connect-SDK-Android-Core/blob/master/src/com/connectsdk/service/webos/WebOSTVServiceSocketClient.java), [LG SSAP control implementations](https://github.com/ConnectSDK/Connect-SDK-Android-Core/blob/master/src/com/connectsdk/service/WebOSTVService.java), [Home Assistant's maintained SSAP endpoints](https://github.com/home-assistant-libs/aiowebostv/blob/main/aiowebostv/endpoints.py), [pre-registration system-info sequence and state subscriptions](https://github.com/home-assistant-libs/aiowebostv/blob/main/aiowebostv/webos_client.py), [ws transport API](https://github.com/websockets/ws/blob/master/doc/ws.md). Registration uses a neutral unsigned permission manifest, not LG's test identity/signatures. Hardware pairing/firmware behavior was not verified against an owner's TV; local real WebSocket fixtures cover the documented exchange. Setup currently requires the documented pre-registration system-info request and all five state subscriptions; unsupported firmware fails explicitly.
+Verification uses local WebSocket/TLS and disposable in-memory database fixtures.
+Real pairing, firmware acceptance and owner-device control require separate owner
+authorization. No TV-reported per-command service-list contract was confirmed;
+the adapter does not invent one.

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(); }
 }