@smarthome.exchange/integrations 2.0.0 → 4.0.0

package/ts/integrations/tuya/tuya.classes.runtime.ts

@@ -1,47 +1,57 @@
 import * as plugins from '../../plugins.js';
-import type { IDeviceFeatureWriteRequest, IIntegrationEntity, IIntegrationEvent, IIntegrationRuntime, ILogger, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
+import type { INativeSetupLease } from '../../core/classes.nativeintegrationowner.js';
+import type { IDeviceFeatureWriteRequest, IIntegrationEntity, IIntegrationEvent, IIntegrationRuntime, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
 import type { IHomeAssistantTuyaConfig, TTuyaDatapointMapping } from './tuya.types.js';
 import { tuyaDeviceId, tuyaDevices, tuyaEntities, tuyaEntityId, tuyaFeatureId, type ITuyaObservedDatapoint } from './tuya.mapper.js';
 import { tuyaKeys, tuyaRecord, tuyaValueMatches } from './tuya.validation.js';
 
+interface ITuyaCleanupResource {
+  readonly cleanup: () => Promise<void>;
+  promise?: Promise<void>;
+  failed: boolean;
+}
+
 export class TuyaRuntime implements IIntegrationRuntime {
   public readonly domain = 'tuya';
   readonly #config: IHomeAssistantTuyaConfig;
   readonly #protocol: plugins.ecobridgeDeviceManager.TuyaProtocol;
-  readonly #onDestroyed: () => void;
-  readonly #logger?: ILogger;
+  readonly #lease: INativeSetupLease;
   readonly #observed = new Map<number, ITuyaObservedDatapoint>();
   readonly #subscriptions = new Set<(eventArg: IIntegrationEvent) => void>();
   readonly #subscriptionCleanup = new Set<() => void>();
-  readonly #unsubscribe: () => void;
-  readonly #unsubscribeErrors: () => void;
+  readonly #resources: ITuyaCleanupResource[] = [];
+  readonly #callbacks = new Set<Promise<void>>();
+  #subscriberFailure = false;
   #closed = false;
   #destroy?: Promise<void>;
 
   constructor(configArg: IHomeAssistantTuyaConfig, protocolArg: plugins.ecobridgeDeviceManager.TuyaProtocol,
-    reportsArg: readonly plugins.ecobridgeDeviceManager.ITuyaDatapointReport[], onDestroyedArg: () => void, loggerArg?: ILogger) {
+    reportsArg: readonly plugins.ecobridgeDeviceManager.ITuyaDatapointReport[], leaseArg: INativeSetupLease) {
     this.#config = configArg;
     this.#protocol = protocolArg;
-    this.#onDestroyed = onDestroyedArg;
-    this.#logger = loggerArg;
+    this.#lease = leaseArg;
+    this.#resources.push({ cleanup: () => this.#protocol.close(), failed: false });
     for (const report of reportsArg) this.#accept(report);
     if (this.#observed.size === 0) throw new Error('Tuya device reported none of the configured product datapoints.');
-    this.#unsubscribe = this.#protocol.subscribe((report) => {
+    const unsubscribe = this.#protocol.subscribe((report) => {
+      if (this.#lease.signal.aborted || this.#destroy) return;
       try { this.#accept(report); }
       catch {
         this.#closed = true;
         this.#emit({ type: 'error', data: { code: 'schema-mismatch', message: 'Tuya reported data no longer matches the configured product schema.' } });
         this.#emit({ type: 'availability_changed', data: { available: false } });
-        void this.destroy();
+        void this.destroy().catch(() => undefined);
       }
     });
-    this.#unsubscribeErrors = this.#protocol.subscribeErrors((error) => {
+    this.#resources.push({ cleanup: async () => unsubscribe(), failed: false });
+    const unsubscribeErrors = this.#protocol.subscribeErrors((error) => {
       this.#emit({ type: 'error', data: { code: error.code, effectOutcome: error.effectOutcome } });
       if (!this.#protocol.connected) this.#emit({ type: 'availability_changed', data: { available: false } });
     });
+    this.#resources.push({ cleanup: async () => unsubscribeErrors(), failed: false });
   }
 
-  public isHealthy(): boolean { return !this.#closed && this.#protocol.connected; }
+  public isHealthy(): boolean { return !this.#closed && !this.#lease.signal.aborted && this.#protocol.connected; }
 
   public async devices(signalArg?: AbortSignal): Promise<plugins.shxInterfaces.data.IDeviceDefinition[]> {
     signalArg?.throwIfAborted();
@@ -53,6 +63,7 @@ export class TuyaRuntime implements IIntegrationRuntime {
   }
 
   public async subscribe(handlerArg: (eventArg: IIntegrationEvent) => void, signalArg?: AbortSignal): Promise<() => Promise<void>> {
+    this.#lease.assertOpen();
     if (this.#closed) throw new Error('Tuya runtime is permanently closed.');
     if (typeof handlerArg !== 'function') throw new TypeError('Tuya subscription handler must be a function.');
     signalArg?.throwIfAborted();
@@ -106,16 +117,37 @@ export class TuyaRuntime implements IIntegrationRuntime {
     } catch (errorArg) { return this.#failure(errorArg); }
   }
 
-  public destroy(): Promise<void> {
-    if (this.#destroy) return this.#destroy;
-    this.#closed = true;
-    this.#unsubscribe();
-    this.#unsubscribeErrors();
-    for (const cleanup of [...this.#subscriptionCleanup]) cleanup();
-    this.#destroy = this.#protocol.close().then(() => this.#onDestroyed());
+  public destroy(): Promise<void> { return this.#lease.close(); }
+
+  /** Invoked by the retained owner handle, including explicit cleanup-only retry. */
+  public closeOwnedResources(retryArg = false): Promise<void> {
+    if (retryArg) return this.#drain(true);
+    if (!this.#destroy) {
+      this.#closed = true;
+      this.#destroy = Promise.resolve().then(() => this.#drain(false));
+    }
     return this.#destroy;
   }
 
+  async #drain(retryArg: boolean): Promise<void> {
+    for (const cleanup of [...this.#subscriptionCleanup]) cleanup();
+    // The first close already joined every admitted callback. Explicit retry acknowledges its
+    // retained failure; subscriber code is never invoked again as part of cleanup.
+    if (retryArg) this.#subscriberFailure = false;
+    const cleanup = this.#resources.map((resourceArg) => {
+      if (retryArg && resourceArg.failed) { resourceArg.promise = undefined; resourceArg.failed = false; }
+      resourceArg.promise ??= Promise.resolve().then(resourceArg.cleanup).catch(() => {
+        resourceArg.failed = true;
+        throw new Error('Tuya owned resource cleanup failed.');
+      });
+      return resourceArg.promise;
+    });
+    const [results] = await Promise.all([Promise.allSettled(cleanup), Promise.allSettled([...this.#callbacks])]);
+    const failures = results.filter((resultArg): resultArg is PromiseRejectedResult => resultArg.status === 'rejected').map((resultArg) => resultArg.reason as unknown);
+    if (this.#subscriberFailure) failures.push(new Error('Tuya event subscriber failed.'));
+    if (failures.length) throw new AggregateError(failures, 'Tuya cleanup failed; ownership remains retained for explicit retry.');
+  }
+
   #accept(reportArg: plugins.ecobridgeDeviceManager.ITuyaDatapointReport): void {
     const changes: ITuyaObservedDatapoint[] = [];
     for (const mapping of this.#config.datapoints) {
@@ -134,6 +166,7 @@ export class TuyaRuntime implements IIntegrationRuntime {
   }
 
   async #write(mappingArg: TTuyaDatapointMapping, valueArg: unknown, signalArg?: AbortSignal): Promise<IServiceCallResult> {
+    this.#lease.assertOpen();
     if (!this.isHealthy()) throw new Error('Tuya session is unavailable; no automatic reconnect or retry is performed.');
     if (mappingArg.kind === 'sensor' || mappingArg.access !== 'read-write') throw new Error('Tuya datapoint is read-only.');
     if (!tuyaValueMatches(mappingArg, valueArg)) throw new TypeError('Tuya write value does not match its configured type/range/step.');
@@ -151,16 +184,29 @@ export class TuyaRuntime implements IIntegrationRuntime {
 
   #emit(eventArg: Omit<IIntegrationEvent, 'integrationDomain' | 'deviceId' | 'timestamp'>): void {
     for (const handler of [...this.#subscriptions]) {
-      if (this.#destroy) return;
+      if (this.#destroy || this.#lease.signal.aborted) return;
+      if (this.#callbacks.size >= 128) {
+        this.#subscriberFailed();
+        void this.destroy().catch(() => undefined);
+        return;
+      }
+      // Reserve a continuation before entering foreign code, including synchronous close reentry.
+      let finish!: () => void;
+      const continuation = new Promise<void>((resolveArg) => { finish = resolveArg; });
+      this.#callbacks.add(continuation);
+      const settled = (): void => { this.#callbacks.delete(continuation); finish(); };
       try {
         const result: unknown = handler({ ...structuredClone(eventArg), integrationDomain: 'tuya', deviceId: tuyaDeviceId(this.#config), timestamp: Date.now() });
-        if (result instanceof Promise) void result.catch(() => this.#subscriberFailed());
-      } catch { this.#subscriberFailed(); }
+        if (result !== null && (typeof result === 'object' || typeof result === 'function')) {
+          void Promise.resolve(result).then(settled, () => { this.#subscriberFailed(); settled(); });
+        } else settled();
+      } catch { this.#subscriberFailed(); settled(); }
     }
   }
 
   #subscriberFailed(): void {
-    if (this.#destroy) return;
-    this.#logger?.log('error', 'Tuya event subscriber failed.', { code: 'subscriber-error' });
+    this.#subscriberFailure = true;
+    try { this.#lease.context.logger?.log('error', 'Tuya event subscriber failed.', { code: 'subscriber-error' }); }
+    catch { /* Logging cannot detach or replace a retained subscriber failure. */ }
   }
 }

package/ts/integrations/tuya/tuya.mapper.ts

@@ -25,7 +25,7 @@ export const tuyaDevices = (configArg: IHomeAssistantTuyaConfig, observedArg: re
   protocol: 'unknown', manufacturer: 'Tuya', online: availableArg,
   features: observedArg.map(({ mapping }) => ({
     id: tuyaFeatureId(mapping), name: mapping.name, readable: true,
-    writable: mapping.kind !== 'sensor' && mapping.access === 'read-write',
+    writable: availableArg && mapping.kind !== 'sensor' && mapping.access === 'read-write',
     capability: mapping.kind === 'switch' ? 'switch' : mapping.kind === 'brightness' ? 'light' : 'sensor',
     ...(mapping.kind === 'sensor' && mapping.unit !== undefined ? { unit: mapping.unit } : {}),
   })),

package/ts/integrations/tuya/tuya.types.ts

@@ -1,3 +1,7 @@
+import type { INativeIntegrationOwnerOptions } from '../../core/classes.nativeintegrationowner.js';
+
+export interface ITuyaIntegrationOptions extends INativeIntegrationOwnerOptions {}
+
 export type TTuyaDatapointAccess = 'read' | 'read-write';
 
 export interface ITuyaDatapointIdentity {

package/ts/integrations/tuya/tuya.validation.ts

@@ -97,15 +97,12 @@ export const normalizeTuyaConfig = (valueArg: unknown): IHomeAssistantTuyaConfig
   });
 };
 
-export const scopedTuyaStore = (configArg: IHomeAssistantTuyaConfig, contextArg: IIntegrationSetupContext): NoSqlConfigStore => {
+/** Capture data fields before admission; the shared owner verifies home and actual store scope. */
+export const tuyaSetupContext = (contextArg: IIntegrationSetupContext): IIntegrationSetupContext => {
   const context = tuyaRecord(contextArg, 'setup context');
-  tuyaKeys(context, ['configStore', 'abortSignal', 'logger']);
-  const store = context.configStore;
-  if (!(store instanceof NoSqlConfigStore)) throw new TypeError('Tuya requires an encrypted NoSqlConfigStore and caller-owned encryption key provider.');
-  const scope = store.getScope();
-  if (scope.homeId !== configArg.homeId || scope.integrationDomain !== 'tuya') throw new TypeError('Tuya encrypted store must belong to the exact configured home and integration.');
-  if (context.abortSignal !== undefined && !(context.abortSignal instanceof AbortSignal)) throw new TypeError('Tuya setup cancellation must be an AbortSignal.');
-  return store;
+  tuyaKeys(context, ['homeId', 'configStore', 'abortSignal', 'logger']);
+  if (!(context.configStore instanceof NoSqlConfigStore)) throw new TypeError('Tuya requires an encrypted NoSqlConfigStore and caller-owned encryption key provider.');
+  return Object.freeze(context) as IIntegrationSetupContext;
 };
 
 export const tuyaCredentialId = (deviceIdArg: string): string => `device:${deviceIdArg}`;

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.