@smarthome.exchange/integrations 2.0.0 → 4.0.0

package/ts/integrations/homeassistant/homeassistant.classes.integration.ts

@@ -1,14 +1,17 @@
 import * as plugins from '../../plugins.js';
+import { NativeIntegrationOwner } from '../../core/classes.nativeintegrationowner.js';
+import { normalizeHomeAssistantConfig } from './homeassistant.classes.client.js';
+import { homeAssistantRecord } from './homeassistant.validation.js';
 import { BaseIntegration } from '../../core/classes.baseintegration.js';
 import { DiscoveryDescriptor } from '../../core/classes.discoverydescriptor.js';
 import type {
-  IIntegrationRuntime,
   IIntegrationSetupContext,
 } from '../../core/types.js';
 import { HomeAssistantClient } from './homeassistant.classes.client.js';
 import { HomeAssistantRuntime } from './homeassistant.classes.runtime.js';
 import type {
   IHomeAssistantHomeassistantConfig,
+  IHomeAssistantIntegrationOptions,
   THomeAssistantWebSocketFactory,
 } from './homeassistant.types.js';
 
@@ -29,26 +32,40 @@ export class HomeAssistantHomeassistantIntegration extends BaseIntegration<IHome
     transport: 'websocket',
   };
 
-  constructor(
-    private readonly webSocketFactory: THomeAssistantWebSocketFactory = (
-      urlArg
-    ) => new globalThis.WebSocket(urlArg)
-  ) {
+  private readonly owner: NativeIntegrationOwner;
+  private readonly webSocketFactory: THomeAssistantWebSocketFactory;
+
+  constructor(optionsOrFactoryArg: IHomeAssistantIntegrationOptions | THomeAssistantWebSocketFactory = {}) {
     super();
+    const options = homeAssistantRecord(typeof optionsOrFactoryArg === 'function'
+      ? { webSocketFactory: optionsOrFactoryArg } : optionsOrFactoryArg);
+    if (Object.keys(options).some((key) => !['homeId', 'capacity', 'webSocketFactory'].includes(key))) throw new TypeError('Home Assistant integration options contain unsupported fields.');
+    if (options.webSocketFactory !== undefined && typeof options.webSocketFactory !== 'function') throw new TypeError('Home Assistant webSocketFactory must be a function.');
+    this.webSocketFactory = options.webSocketFactory as THomeAssistantWebSocketFactory | undefined ?? ((urlArg) => new globalThis.WebSocket(urlArg));
+    this.owner = new NativeIntegrationOwner(this.domain, { homeId: options.homeId as string | undefined, capacity: options.capacity as number | undefined });
   }
 
-  public async setup(
-    configArg: IHomeAssistantHomeassistantConfig,
-    contextArg: IIntegrationSetupContext
-  ): Promise<IIntegrationRuntime> {
-    const client = new HomeAssistantClient(
-      configArg,
-      plugins.homeAssistantWebsocket,
-      this.webSocketFactory
-    );
-    await client.init(contextArg.abortSignal);
-    return new HomeAssistantRuntime(client);
+  public async setup(configArg: IHomeAssistantHomeassistantConfig, contextArg: IIntegrationSetupContext): Promise<HomeAssistantRuntime> {
+    // Validate/capture before deferred setup so later caller mutation cannot change scope.
+    normalizeHomeAssistantConfig(configArg);
+    const config = structuredClone(configArg);
+    return this.owner.runSetup(contextArg, config.homeId, async (leaseArg) => {
+      const client = new HomeAssistantClient(config, leaseArg.context, plugins.homeAssistantWebsocket,
+        this.webSocketFactory, { owner: this.owner, lease: leaseArg });
+      let cleanupStarted = false;
+      leaseArg.own(() => {
+        const retry = cleanupStarted;
+        cleanupStarted = true;
+        return retry ? client.retryCleanup() : client.destroy();
+      });
+      await client.init(leaseArg.signal);
+      leaseArg.assertOpen();
+      const runtime = new HomeAssistantRuntime(client, leaseArg, this.owner);
+      leaseArg.promoteToRuntime();
+      return runtime;
+    });
   }
 
-  public async destroy(): Promise<void> {}
+  public destroy(): Promise<void> { return this.owner.close(); }
+  public retryCleanup(): Promise<void> { return this.owner.retryCleanup(); }
 }

package/ts/integrations/homeassistant/homeassistant.classes.runtime.ts

@@ -1,3 +1,4 @@
+import type { INativeSetupLease, NativeIntegrationOwner } from '../../core/classes.nativeintegrationowner.js';
 import type * as shxInterfaces from '@smarthome.exchange/interfaces';
 import type {
   IDeviceFeatureWriteRequest,
@@ -10,6 +11,7 @@ import { HomeAssistantMapper } from './homeassistant.mapper.js';
 import { homeAssistantRecord } from './homeassistant.validation.js';
 import type {
   IHomeAssistantClient,
+  IHomeAssistantOperationSession,
   IHomeAssistantTargetScope,
 } from './homeassistant.types.js';
 
@@ -21,43 +23,44 @@ const abortError = (abortSignalArg: AbortSignal): Error => {
 
 export class HomeAssistantRuntime implements IIntegrationRuntime {
   public readonly domain = 'homeassistant';
-  private readonly subscriptions = new Set<() => void>();
   private destroyed = false;
-  private cleanupComplete = false;
   private destroyPromise?: Promise<void>;
   private readonly targetScope: IHomeAssistantTargetScope;
 
-  constructor(private readonly client: IHomeAssistantClient) {
+  constructor(private readonly client: IHomeAssistantClient, private readonly lease?: INativeSetupLease, private readonly owner?: NativeIntegrationOwner) {
     this.targetScope = Object.freeze({ ...client.getTargetScope() });
   }
 
   public isHealthy(): boolean {
-    return !this.destroyed && this.client.connected;
+    return !this.destroyed && !this.lease?.signal.aborted && this.client.connected;
   }
 
   public async devices(
     abortSignalArg?: AbortSignal
   ): Promise<shxInterfaces.data.IDeviceDefinition[]> {
     this.assertActive();
-    if (abortSignalArg?.aborted) {
-      throw abortError(abortSignalArg);
-    }
-    return HomeAssistantMapper.toDevices(
-      this.client.getSnapshot(),
-      this.client.connected,
-      this.client.getEntityPlatforms(),
-      this.client.getServices(),
-      this.targetScope
-    );
+    return this.client.withOperation(async () => {
+      this.assertActive();
+      return HomeAssistantMapper.toDevices(
+        this.client.getSnapshot(),
+        this.client.connected,
+        this.client.getEntityPlatforms(),
+        this.client.getServices(),
+        this.targetScope
+      );
+    }, abortSignalArg);
   }
 
   public async entities(): Promise<IIntegrationEntity[]> {
     this.assertActive();
-    return HomeAssistantMapper.toEntities(this.client.getSnapshot(), this.client.connected, this.targetScope);
+    return this.client.withOperation(async () => {
+      this.assertActive();
+      return HomeAssistantMapper.toEntities(this.client.getSnapshot(), this.client.connected, this.targetScope);
+    });
   }
 
   public async subscribe(
-    handlerArg: (eventArg: IIntegrationEvent) => void,
+    handlerArg: (eventArg: IIntegrationEvent) => void | Promise<void>,
     abortSignalArg?: AbortSignal
   ): Promise<() => Promise<void>> {
     this.assertActive();
@@ -65,32 +68,14 @@ export class HomeAssistantRuntime implements IIntegrationRuntime {
       throw abortError(abortSignalArg);
     }
 
-    let subscribed = true;
-    const unsubscribeClient = this.client.subscribe(() => {
-      handlerArg({
+    if (typeof handlerArg !== 'function') throw new TypeError('Home Assistant subscriber must be a function.');
+    return this.client.subscribe(() => {
+      return handlerArg({
         type: 'state_changed',
         integrationDomain: this.domain,
         timestamp: Date.now(),
       });
-    });
-    const unsubscribe = (): void => {
-      if (!subscribed) {
-        return;
-      }
-      subscribed = false;
-      this.subscriptions.delete(unsubscribe);
-      abortSignalArg?.removeEventListener('abort', unsubscribe);
-      unsubscribeClient();
-    };
-    this.subscriptions.add(unsubscribe);
-    abortSignalArg?.addEventListener('abort', unsubscribe, { once: true });
-    if (abortSignalArg?.aborted) {
-      unsubscribe();
-    }
-
-    return async () => {
-      unsubscribe();
-    };
+    }, abortSignalArg);
   }
 
   public async writeFeature(
@@ -101,6 +86,19 @@ export class HomeAssistantRuntime implements IIntegrationRuntime {
     if (abortSignalArg?.aborted) {
       throw abortError(abortSignalArg);
     }
+    homeAssistantRecord(requestArg);
+    homeAssistantRecord(requestArg.device);
+    homeAssistantRecord(requestArg.feature);
+    if (requestArg.device.metadata !== undefined) homeAssistantRecord(requestArg.device.metadata);
+    const request = structuredClone(requestArg);
+    return this.client.withOperation((sessionArg) => this.writeAdmitted(request, sessionArg), abortSignalArg);
+  }
+
+  private async writeAdmitted(
+    requestArg: IDeviceFeatureWriteRequest,
+    sessionArg: IHomeAssistantOperationSession
+  ): Promise<IServiceCallResult> {
+    this.assertActive();
     if (Object.keys(homeAssistantRecord(requestArg)).some((key) => !['device', 'feature', 'value'].includes(key))) {
       return { success: false, error: 'Home Assistant feature requests contain unsupported fields.' };
     }
@@ -145,10 +143,8 @@ export class HomeAssistantRuntime implements IIntegrationRuntime {
       return { success: false, error: mappedCall.error || 'Unsupported Home Assistant write.' };
     }
 
-    const data = await this.client.callService(mappedCall.request, abortSignalArg);
-    if (abortSignalArg?.aborted) {
-      throw abortError(abortSignalArg);
-    }
+    const data = await sessionArg.callService(mappedCall.request);
+    sessionArg.signal.throwIfAborted();
     return {
       success: true,
       data: {
@@ -159,34 +155,25 @@ export class HomeAssistantRuntime implements IIntegrationRuntime {
   }
 
   private assertActive(): void {
+    this.lease?.assertOpen();
     if (this.destroyed) throw new Error('Home Assistant runtime is destroyed.');
   }
 
   public destroy(): Promise<void> {
-    if (this.destroyPromise) {
-      return this.destroyPromise;
-    }
-    if (this.cleanupComplete) {
-      return Promise.resolve();
+    if (!this.destroyPromise) {
+      this.destroyed = true;
+      this.destroyPromise = Promise.resolve().then(() => this.performDestroy());
     }
-    this.destroyed = true;
-    const destroyPromise = this.performDestroy();
-    this.destroyPromise = destroyPromise;
-    void destroyPromise.then(() => {
-      this.cleanupComplete = true;
-    }).finally(() => {
-      if (this.destroyPromise === destroyPromise) {
-        this.destroyPromise = undefined;
-      }
-    }).catch(() => undefined);
-    return destroyPromise;
+    return this.destroyPromise;
+  }
+
+  public retryCleanup(): Promise<void> {
+    if (!this.destroyPromise) return Promise.reject(new Error('Home Assistant cleanup retry requires destruction.'));
+    return this.owner ? this.owner.retryCleanup() : this.client.retryCleanup();
   }
 
   private async performDestroy(): Promise<void> {
-    for (const unsubscribe of [...this.subscriptions]) {
-      unsubscribe();
-    }
-    this.subscriptions.clear();
-    await this.client.destroy();
+    // The client closes transport before joining its owned subscriber continuations.
+    await (this.lease ? this.lease.close() : this.client.destroy());
   }
 }

package/ts/integrations/homeassistant/homeassistant.types.ts

@@ -1,3 +1,4 @@
+import type { INativeIntegrationOwnerOptions } from '../../core/classes.nativeintegrationowner.js';
 import type * as homeAssistantWebsocket from 'home-assistant-js-websocket';
 
 export type THomeAssistantVacuumCommand =
@@ -8,6 +9,10 @@ export type THomeAssistantVacuumCommand =
   | 'locate'
   | 'clean_spot';
 
+export interface IHomeAssistantIntegrationOptions extends INativeIntegrationOwnerOptions {
+  readonly webSocketFactory?: THomeAssistantWebSocketFactory;
+}
+
 export interface IHomeAssistantHomeassistantConfig {
   homeId: string;
   baseUrl: string;
@@ -72,12 +77,23 @@ export interface IHomeAssistantClient {
   getEntityPlatforms(): Record<string, string>;
   getServices(): ReadonlySet<string>;
   getTargetScope(): IHomeAssistantTargetScope;
-  subscribe(handlerArg: () => void): () => void;
+  subscribe(handlerArg: () => void | Promise<void>, abortSignalArg?: AbortSignal): () => Promise<void>;
+  withOperation<TResult>(
+    workArg: (sessionArg: IHomeAssistantOperationSession) => Promise<TResult>,
+    abortSignalArg?: AbortSignal
+  ): Promise<TResult>;
   callService(
     requestArg: IHomeAssistantServiceCall,
     abortSignalArg?: AbortSignal
   ): Promise<unknown>;
   destroy(): Promise<void>;
+  retryCleanup(): Promise<void>;
+}
+
+/** A service session remains usable only inside its admitted continuation. */
+export interface IHomeAssistantOperationSession {
+  readonly signal: AbortSignal;
+  callService(requestArg: IHomeAssistantServiceCall): Promise<unknown>;
 }
 
 export interface IHomeAssistantTargetScope {

package/ts/integrations/homeassistant/readme.md

@@ -1,9 +1,9 @@
 # Home Assistant runtime
 
-`HomeAssistantHomeassistantIntegration` connects directly to Home Assistant's authenticated `/api/websocket` endpoint through the installed official `home-assistant-js-websocket` client and Node's native WebSocket. Its existing optional WebSocket-factory constructor remains available. Production contains no fixture entities or credentials.
+`HomeAssistantHomeassistantIntegration` connects directly to Home Assistant's authenticated `/api/websocket` endpoint through the installed official `home-assistant-js-websocket` client and Node's native WebSocket. Its existing WebSocket-factory constructor remains available; an options object additionally accepts `homeId`, `capacity` and `webSocketFactory`. Production contains no fixture entities or credentials.
 
 ```typescript
-const integration = new HomeAssistantHomeassistantIntegration();
+const integration = new HomeAssistantHomeassistantIntegration({ capacity: 16 });
 const runtime = await integration.setup({
   homeId: 'house-a',
   baseUrl: 'https://ha.example.test:8123',
@@ -14,15 +14,19 @@ const runtime = await integration.setup({
   setupRetry: 0,
   initialSnapshotTimeoutMs: 10_000,
   serviceCallTimeoutMs: 15_000,
-}, { abortSignal });
+}, { homeId: 'house-a', abortSignal });
 try {
   const devices = await runtime.devices();
   // Send selected advertised features through the hub's scoped tool boundary.
 } finally {
-  await runtime.destroy();
+  await integration.destroy();
 }
 ```
 
+Setup requires an independent host-selected `context.homeId`, even if the constructor constrains a home. Configuration home is an exact consistency check. The first admitted home remains fixed after failed readiness; context is frozen before allocation. An optional borrowed `NoSqlConfigStore` must be a real instance with exactly that home and the `homeassistant` domain; HA never closes it, its database, logger or caller-owned signal.
+
+For a host-owned encrypted config store, pass `{ homeId: selectedHome, configStore: homeAssistantStore, abortSignal }` as context. The store's scope must be `{ homeId: selectedHome, integrationDomain: 'homeassistant' }`. The host closes that store after its integrations finish. Supplying a store does not replace the required inline runtime token or create a credential-reference API.
+
 `homeId`, an HTTP(S) origin without user information, path, query or fragment, and a nonempty configured access token are required. Home IDs contain 1–128 alphanumeric, underscore, period, colon or hyphen characters and begin with an alphanumeric character. The exact configured ID is preserved, including case and colons in IDs such as `home:studio` and `home:unconfigured`; it is never trimmed or renamed. Optional entity IDs and domains form intersecting allowlists. Credentials stay in runtime configuration; a caller that persists configuration must use the core encrypted NoSql config store and its external key provider. This integration writes no application data to the filesystem.
 
 Setup uses one deadline for authentication, subscription acknowledgements, an authoritative `get_states` snapshot, `get_services`, and `config/entity_registry/list_for_display`. Registry provenance is fetched for selected entities even when strict registry enforcement is disabled. Strict enforcement additionally requires every explicitly configured entity to exist in the state and registry snapshots. Home Assistant must support these documented commands; an unsupported or malformed response rejects setup.
@@ -33,8 +37,20 @@ Supported writes are exact light/switch/input-boolean `turn_on` and `turn_off`,
 
 `state_changed` updates are authoritative. Service acknowledgements never synthesize state. `service_registered`, `service_removed` and `entity_registry_updated` events revoke snapshot readiness until fresh state, service and registry snapshots complete. Reconnects do the same before health or writes recover. Missing required entities, offline entities, malformed states or inconsistent event targets block controls. A malformed state event closes its connection and leaves retained devices offline.
 
-Snapshots and buffered events are bounded at 10,000 entities, services at 10,000 actions and 1,000 domains, and entity attributes at depth 16 and 4,096 values. Caller aborts and write deadlines cancel the pending command through the owning connection; commands are never retried or replayed by this adapter. Cancellation after dispatch leaves the physical effect uncertain. Destroy aborts pending callers, releases all subscriptions, closes sockets, waits for physical closure up to one second, clears retained data and makes the runtime terminal. Failed cleanup remains retryable through `destroy()`.
+Snapshots and buffered events are bounded at 10,000 entities, services at 10,000 actions and 1,000 domains, and entity attributes at depth 16 and 4,096 values. Caller aborts and write deadlines cancel the pending command through the owning connection; commands are never retried or replayed by this adapter. Cancellation after dispatch leaves the physical effect uncertain. Destroy aborts pending callers, releases all subscriptions, closes sockets, waits for physical closure up to one second, clears retained data and makes the runtime terminal. Repeated `destroy()` calls return the same permanent result, including a failure. `retryCleanup()` retries only failed cleanup handles and never reopens, authenticates or replays a command. Integration `destroy()` drains setup and all promoted runtimes, returns one permanent result and rejects reopening; integration `retryCleanup()` performs cleanup only. Runtime destruction closes its setup lease. Cancellation of the setup context remains attached after promotion. A shared capacity (default 16) counts pending work, live runtimes and retained cleanup; rejection happens before allocation. The exported controlling client also requires independent context: `new HomeAssistantClient(config, { homeId: selectedHome }, api?, webSocketFactory?)`.
+
+Close joins actual connection, subscription, refresh and service settlement even when caller cancellation has already rejected. A late handle remains owned until its cleanup completes. Sibling cleanup proceeds even when one unsubscribe fails.
+
+Runtime reads, feature writes, direct service calls and subscriber delivery use the same owner capacity as live runtimes. `client.withOperation(async (session) => ...)` owns the entire continuation and provides `session.signal` and a scoped `session.callService(request)`; a session cannot dispatch after that continuation finishes. Caller cancellation rejects promptly while the actual continuation and any dispatched service promise still occupy capacity until settlement. Requests are captured before deferred admission and validated against current authoritative state at dispatch.
+
+Subscribers may return `Promise<void>`. The returned unsubscribe function fences new and queued delivery immediately, returns one stable promise and joins callbacks already running. Runtime and integration close shut down transport before joining callbacks. Synchronous and asynchronous callback failures, and rejected callback admission, remain observable through unsubscribe and close; a failed subscriber stops receiving events while siblings continue. Explicit cleanup retry clears reported callback failures and retries retained cleanup without replaying callbacks or commands. A callback must finish its own work before awaiting destruction of its owning runtime.
+
+The local test fixtures use real HTTP upgrades and native WebSockets with test-only tokens. Their delayed replies preserve the result captured when a command was received. They verify exact request bytes, acknowledgement gates, catalogue changes, registry refresh, reconnect readiness, authoritative state, malformed inputs, cross-home and mutated-target rejection, shared capacity, callback drainage, cancellation and physical closure. The five suites contain 62 tests: injected behavior 20, native protocol 15, lifecycle 6, native ownership 9, finite operations/subscribers 12. The domain has seven production TypeScript roots and seven test/support roots for strict type and emit checks.
+
+Qualification commands are `pnpm exec tstest test/homeassistant/ --verbose --logfile --timeout 60`, `pnpm run build`, and `pnpm exec tsbuild check 'test/**/*'` without `skipLibCheck`. For the domain's 14 roots, use the installed `@git.zone/tsbuild` `TsCompiler.checkTypes(roots, { strict: true })` and `checkEmit(roots, { strict: true })`; the package build also covers the shared owner and generated domains.
+
+One upstream contract remains blocked. In installed `home-assistant-js-websocket` 9.7.0, terminal `Connection.close()` leaves an unacknowledged `subscribeEvents()` promise pending forever. `Connection._handleClose` preserves subscription commands for reconnect before checking `closeRequested`, then stops reconnecting. A fixture probe sent one subscription, closed its socket and observed no subscription settlement. The published 9.7.1 artifact was inspected on 2026-10-11 and retains the same implementation. HA's actual-work ledger deliberately continues owning that promise; shutdown during an unacknowledged subscription cannot be qualified as complete. The proper path is a fix and published release in the official client that rejects unresolved subscriptions on terminal close, followed by a published consumer update and native terminal-subscription regressions. No local shim, command replay or fabricated settlement is used.
 
-The local test fixtures use real HTTP upgrades and native WebSockets with test-only tokens. They verify exact request bytes, catalogue changes, registry refresh, reconnect readiness, authoritative state, malformed inputs, cross-home and mutated-target rejection, cancellation and physical closure. Hardware acceptance against the owner's Home Assistant remains outside this lane.
+Real Home Assistant authentication, registry compatibility, credential revocation, commissioning/control and physical shutdown acceptance remain owner-gated. Credential references and config flow, explicit control/plaintext consent, public offline-mapper defaults and `reconnect-error` reporting remain separate public-contract decisions.
 
 API references: [Home Assistant WebSocket API](https://developers.home-assistant.io/docs/api/websocket/), [REST API](https://developers.home-assistant.io/docs/api/rest/), and [official JavaScript client](https://github.com/home-assistant/home-assistant-js-websocket).