@smarthome.exchange/integrations 1.0.0 → 2.0.0

package/ts/core/classes.configstore.ts

@@ -28,6 +28,12 @@ export interface IConfigStoreInitializationOptions {
   signal?: AbortSignal;
 }
 
+interface IConfigStoreOperationState {
+  keyLookups: Set<Promise<void>>;
+  settled: boolean;
+  providerFailed: boolean;
+}
+
 const validateName = (valueArg: string, nameArg: string, maxLengthArg: number): string => {
   if (typeof valueArg !== 'string' || valueArg.length === 0 || valueArg.length > maxLengthArg || /[\p{Cc}\p{Cs}]/u.test(valueArg)) {
     throw new TypeError(`${nameArg} must be a non-empty string without control characters, at most ${maxLengthArg} characters.`);
@@ -102,9 +108,13 @@ export class NoSqlConfigStore implements IConfigStore {
   readonly #maxValueBytes: number;
   readonly #lifetime = new AbortController();
   readonly #preparations = new Set<Promise<void>>();
+  readonly #keyLookups = new Set<Promise<void>>();
+  readonly #retainedOperations = new Set<IConfigStoreOperationState>();
+  readonly #keyProviderFailures = new Set<Error>();
   #operationTail: Promise<void> = Promise.resolve();
   #pendingOperations = 0;
   #closePromise?: Promise<void>;
+  #retryPromise?: Promise<void>;
 
   constructor(optionsArg: INoSqlConfigStoreOptions) {
     this.#homeId = validateName(optionsArg.homeId, 'homeId', 256);
@@ -156,19 +166,34 @@ export class NoSqlConfigStore implements IConfigStore {
         await Promise.allSettled([
           ...this.#preparations,
           this.#operationTail,
+          ...this.#keyLookups,
         ]);
+        if (this.#keyProviderFailures.size) {
+          throw new AggregateError([...this.#keyProviderFailures], 'NoSqlConfigStore key-provider cleanup failed.');
+        }
       });
       this.#lifetime.abort(new Error('NoSqlConfigStore is closed.'));
     }
     return this.#closePromise;
   }
 
+  /** Acknowledges settled provider cleanup failures without repeating callbacks or reopening the store. */
+  public retryCleanup(): Promise<void> {
+    if (!this.#closePromise) return Promise.reject(new Error('NoSqlConfigStore cleanup requires terminal close.'));
+    this.#retryPromise ??= Promise.resolve().then(async () => {
+      await this.#closePromise!.catch(() => undefined);
+      this.#keyProviderFailures.clear();
+      this.#retainedOperations.clear();
+    });
+    return this.#retryPromise;
+  }
+
   public get<TValue>(keyArg: string, optionsArg: IConfigStoreOperationOptions = {}): Promise<TValue | undefined> {
     const key = validateName(keyArg, 'config key', 1024);
     const databaseOptions = this.#databaseOptions(optionsArg);
-    return this.#runOperation(async () => {
+    return this.#runOperation(async (operationArg) => {
       const record = await this.#records.getInstance(this.#selector(key), databaseOptions);
-      return record ? this.#decrypt<TValue>(key, record.encryptedValue) : undefined;
+      return record ? this.#decrypt<TValue>(key, record.encryptedValue, operationArg) : undefined;
     });
   }
 
@@ -176,8 +201,9 @@ export class NoSqlConfigStore implements IConfigStore {
     const key = validateName(keyArg, 'config key', 1024);
     const serialized = this.#serialize(valueArg);
     const databaseOptions = this.#databaseOptions(optionsArg);
-    return this.#runOperation(async () => {
-      const encryptedValue = await this.#encrypt(key, serialized);
+    return this.#runOperation(async (operationArg) => {
+      const encryptedValue = await this.#encrypt(key, serialized, operationArg);
+      this.#assertOpen();
       await this.#records.atomicUpdate({ id: this.#selector(key).id }, {
         $set: { homeId: this.#homeId, integrationDomain: this.#integrationDomain, key, encryptedValue },
       }, { upsert: true, ...databaseOptions });
@@ -189,10 +215,11 @@ export class NoSqlConfigStore implements IConfigStore {
     const key = validateName(keyArg, 'config key', 1024);
     const serialized = this.#serialize(valueArg);
     const databaseOptions = this.#databaseOptions(optionsArg);
-    return this.#runOperation(async () => {
+    return this.#runOperation(async (operationArg) => {
       const record = Object.assign(new this.#records(), this.#selector(key), {
-        encryptedValue: await this.#encrypt(key, serialized),
+        encryptedValue: await this.#encrypt(key, serialized, operationArg),
       });
+      this.#assertOpen();
       await this.#records.insert(record, databaseOptions);
     });
   }
@@ -253,8 +280,9 @@ export class NoSqlConfigStore implements IConfigStore {
     return serialized;
   }
 
-  async #encrypt(keyArg: string, serializedArg: string): Promise<IEncryptedConfigValue> {
-    const encryptionKey = await this.#lookupKey((signalArg) => this.#keyProvider.currentKey(signalArg));
+  async #encrypt(keyArg: string, serializedArg: string, operationArg: IConfigStoreOperationState): Promise<IEncryptedConfigValue> {
+    const encryptionKey = await this.#lookupKey((signalArg) => this.#keyProvider.currentKey(signalArg), operationArg);
+    this.#assertOpen();
     const keyId = validateName(encryptionKey.id, 'encryption key ID', 128);
     const key = copyKey(encryptionKey.key);
     try {
@@ -268,13 +296,15 @@ export class NoSqlConfigStore implements IConfigStore {
     }
   }
 
-  async #decrypt<TValue>(keyArg: string, valueArg: IEncryptedConfigValue): Promise<TValue> {
+  async #decrypt<TValue>(keyArg: string, valueArg: IEncryptedConfigValue, operationArg: IConfigStoreOperationState): Promise<TValue> {
     if (!valueArg || valueArg.version !== 1) throw new Error('Stored config encryption envelope is invalid.');
     const keyId = validateName(valueArg.keyId, 'stored encryption key ID', 128);
     const nonce = decodeBase64(valueArg.nonce, 12, 12);
     const tag = decodeBase64(valueArg.tag, 16, 16);
     const ciphertext = decodeBase64(valueArg.ciphertext, this.#maxValueBytes);
-    const key = copyKey(await this.#lookupKey((signalArg) => this.#keyProvider.keyForId(keyId, signalArg)));
+    const decryptionKey = await this.#lookupKey((signalArg) => this.#keyProvider.keyForId(keyId, signalArg), operationArg);
+    this.#assertOpen();
+    const key = copyKey(decryptionKey);
     try {
       const decipher = plugins.crypto.createDecipheriv('aes-256-gcm', key, nonce);
       decipher.setAAD(this.#aad(keyArg, keyId));
@@ -294,24 +324,46 @@ export class NoSqlConfigStore implements IConfigStore {
     }
   }
 
-  async #lookupKey<TResult>(lookupArg: (signalArg: AbortSignal) => Promise<TResult>): Promise<TResult> {
+  async #lookupKey<TResult>(lookupArg: (signalArg: AbortSignal) => Promise<TResult>, operationArg: IConfigStoreOperationState): Promise<TResult> {
     this.#assertOpen();
     const controller = new AbortController();
-    let timer: ReturnType<typeof setTimeout> | undefined;
-    const deadline = new Promise<never>((resolveArg, rejectArg) => {
+    const signal = AbortSignal.any([controller.signal, this.#lifetime.signal]);
+    let resolveProvider!: (valueArg: TResult | PromiseLike<TResult>) => void;
+    let rejectProvider!: (errorArg: unknown) => void;
+    const provider = new Promise<TResult>((resolveArg, rejectArg) => {
+      resolveProvider = resolveArg;
+      rejectProvider = rejectArg;
+    });
+    let abortLookup!: () => void;
+    const settlement = provider.then(() => undefined, (errorArg: unknown) => {
+      if (signal.aborted && errorArg !== signal.reason) {
+        operationArg.providerFailed = true;
+        this.#keyProviderFailures.add(new Error('Config encryption key provider rejected after cancellation.'));
+      }
+    }).finally(() => {
+      this.#keyLookups.delete(settlement);
+      operationArg.keyLookups.delete(settlement);
+      if (operationArg.settled && !operationArg.keyLookups.size && !operationArg.providerFailed) {
+        this.#retainedOperations.delete(operationArg);
+      }
+      signal.removeEventListener('abort', abortLookup);
+    });
+    // Own the actual callback promise before invoking foreign code, including synchronous close reentry.
+    this.#keyLookups.add(settlement);
+    operationArg.keyLookups.add(settlement);
+    const cancellation = new Promise<never>((resolveArg, rejectArg) => {
       void resolveArg;
-      timer = setTimeout(() => {
-        const error = new Error('Config encryption key lookup timed out.');
-        controller.abort(error);
-        rejectArg(error);
-      }, this.#timeoutMs);
-      timer.unref();
+      abortLookup = () => {
+        rejectArg(signal.reason);
+      };
+      signal.addEventListener('abort', abortLookup, { once: true });
     });
+    const timer = setTimeout(() => controller.abort(new Error('Config encryption key lookup timed out.')), this.#timeoutMs);
+    timer.unref();
     try {
-      const result = await Promise.race([
-        lookupArg(AbortSignal.any([controller.signal, this.#lifetime.signal])),
-        deadline,
-      ]);
+      try { resolveProvider(lookupArg(signal)); } catch (errorArg) { rejectProvider(errorArg); }
+      const result = await Promise.race([provider, cancellation]);
+      signal.throwIfAborted();
       this.#assertOpen();
       return result;
     } finally {
@@ -319,18 +371,23 @@ export class NoSqlConfigStore implements IConfigStore {
     }
   }
 
-  #runOperation<TResult>(operationArg: () => Promise<TResult>): Promise<TResult> {
+  #runOperation<TResult>(operationArg: (stateArg: IConfigStoreOperationState) => Promise<TResult>): Promise<TResult> {
     if (this.#lifetime.signal.aborted) {
       return Promise.reject(this.#lifetime.signal.reason);
     }
-    if (this.#pendingOperations >= this.#maxPendingOperations) {
+    if (this.#pendingOperations + this.#retainedOperations.size >= this.#maxPendingOperations) {
       return Promise.reject(new Error(`NoSqlConfigStore operation capacity reached: ${this.#maxPendingOperations}.`));
     }
     this.#pendingOperations += 1;
+    const state: IConfigStoreOperationState = { keyLookups: new Set(), settled: false, providerFailed: false };
     const operation = this.#operationTail.then(() => {
       this.#assertOpen();
-      return operationArg();
-    }).finally(() => { this.#pendingOperations -= 1; });
+      return operationArg(state);
+    }).finally(() => {
+      state.settled = true;
+      this.#pendingOperations -= 1;
+      if (state.keyLookups.size || state.providerFailed) this.#retainedOperations.add(state);
+    });
     this.#operationTail = operation.then(() => undefined, () => undefined);
     return operation;
   }

package/ts/core/classes.nativehomeadmission.ts

@@ -0,0 +1,96 @@
+import { NoSqlConfigStore } from './classes.configstore.js';
+import type { IConfigFlowContext, IIntegrationSetupContext, ILogger } from './types.js';
+
+export interface INativeHomeAdmissionOptions {
+  readonly homeId?: string;
+}
+
+/** A captured host selection, not an authentication credential. Persistence resources are borrowed. */
+export interface INativeAdmissionContext {
+  readonly homeId: string;
+  readonly configStore?: NoSqlConfigStore;
+  readonly logger?: ILogger;
+  readonly abortSignal?: AbortSignal;
+}
+
+const identifier = (valueArg: unknown, nameArg: string, maximumArg: number): string => {
+  if (typeof valueArg !== 'string' || !valueArg || valueArg.length > maximumArg
+    || valueArg.trim() !== valueArg || /[\p{Cc}\p{Cs}]/u.test(valueArg)) {
+    throw new TypeError(`${nameArg} must be a non-empty identifier without surrounding whitespace or control characters, at most ${maximumArg} characters.`);
+  }
+  return valueArg;
+};
+
+const dataFields = (valueArg: unknown, allowedArg: readonly string[], nameArg: string): Record<string, unknown> => {
+  if (!valueArg || typeof valueArg !== 'object'
+    || (Object.getPrototypeOf(valueArg) !== Object.prototype && Object.getPrototypeOf(valueArg) !== null)) {
+    throw new TypeError(`${nameArg} must be a plain data object.`);
+  }
+  const captured: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
+  for (const key of Reflect.ownKeys(valueArg)) {
+    const descriptor = Object.getOwnPropertyDescriptor(valueArg, key);
+    if (typeof key !== 'string' || !allowedArg.includes(key) || !descriptor
+      || !descriptor.enumerable || !('value' in descriptor)) {
+      throw new TypeError(`${nameArg} contains an unsupported field or accessor.`);
+    }
+    captured[key] = descriptor.value as unknown;
+  }
+  return captured;
+};
+
+const logger = (valueArg: unknown): ILogger | undefined => {
+  if (valueArg === undefined) return undefined;
+  if (!valueArg || typeof valueArg !== 'object') throw new TypeError('Native logger must expose a log method.');
+  let target: object | null = valueArg;
+  for (let depth = 0; target && depth < 16; depth += 1) {
+    const descriptor = Object.getOwnPropertyDescriptor(target, 'log');
+    if (descriptor) {
+      if ('value' in descriptor && typeof descriptor.value === 'function') return valueArg as ILogger;
+      break;
+    }
+    target = Object.getPrototypeOf(target) as object | null;
+  }
+  throw new TypeError('Native logger must expose a data-method log function.');
+};
+
+/** Binds to independently selected host context only after all synchronous checks pass. */
+export class NativeHomeAdmission {
+  readonly #domain: string;
+  #homeId?: string;
+
+  constructor(domainArg: string, optionsArg: INativeHomeAdmissionOptions = {}) {
+    this.#domain = identifier(domainArg, 'integrationDomain', 128);
+    const options = dataFields(optionsArg, ['homeId'], 'Native home options');
+    if (options.homeId !== undefined) this.#homeId = identifier(options.homeId, 'homeId', 256);
+  }
+
+  public get homeId(): string | undefined { return this.#homeId; }
+
+  public admit(contextArg: IIntegrationSetupContext | IConfigFlowContext, configHomeIdArg?: string): INativeAdmissionContext {
+    const context = dataFields(contextArg, ['homeId', 'configStore', 'logger', 'abortSignal'], 'Native context');
+    const homeId = identifier(context.homeId, 'Host-selected homeId', 256);
+    if (this.#homeId !== undefined && this.#homeId !== homeId) throw new Error('Native owning home does not match the selected host home.');
+    if (configHomeIdArg !== undefined && identifier(configHomeIdArg, 'Configuration homeId', 256) !== homeId) {
+      throw new Error('Native configuration home does not match the selected host home.');
+    }
+    const configStore = context.configStore;
+    if (configStore !== undefined) {
+      if (!(configStore instanceof NoSqlConfigStore)) throw new TypeError('Native configStore must be an actual NoSqlConfigStore.');
+      // Call the owning implementation: a structural or overridden getScope cannot grant admission.
+      const scope = NoSqlConfigStore.prototype.getScope.call(configStore);
+      if (scope.homeId !== homeId || scope.integrationDomain !== this.#domain) {
+        throw new Error('Native configStore home/domain does not match the admitted owner.');
+      }
+    }
+    const capturedLogger = logger(context.logger);
+    const abortSignal = context.abortSignal;
+    if (abortSignal !== undefined) {
+      if (!(abortSignal instanceof AbortSignal)) throw new TypeError('Native abortSignal must be an AbortSignal.');
+      AbortSignal.prototype.throwIfAborted.call(abortSignal);
+    }
+    const captured = Object.freeze({ homeId, configStore: configStore as NoSqlConfigStore | undefined,
+      logger: capturedLogger, abortSignal: abortSignal as AbortSignal | undefined });
+    this.#homeId = homeId;
+    return captured;
+  }
+}

package/ts/core/classes.nativeintegrationowner.ts

@@ -0,0 +1,297 @@
+import { NativeHomeAdmission, type INativeAdmissionContext, type INativeHomeAdmissionOptions } from './classes.nativehomeadmission.js';
+import type { IConfigFlowContext, IIntegrationSetupContext } from './types.js';
+
+export interface INativeIntegrationOwnerOptions extends INativeHomeAdmissionOptions {
+  /** Shared limit for pending operations, runtimes, and retained cleanup resources. Defaults to 16. */
+  readonly capacity?: number;
+}
+
+export interface INativeOperationLease {
+  readonly context: INativeAdmissionContext;
+  readonly signal: AbortSignal;
+  assertOpen(): void;
+  /** Register immediately after allocation, before invoking initialization or other foreign callbacks. */
+  own(cleanupArg: () => Promise<void>): void;
+  close(): Promise<void>;
+}
+
+export interface INativeSetupLease extends INativeOperationLease {
+  /** Transfers this operation's cleanup ownership to the returned runtime. */
+  promoteToRuntime(): void;
+}
+
+interface INativeResource {
+  readonly cleanup: () => Promise<void>;
+  status: 'idle' | 'pending' | 'closed' | 'failed';
+  promise?: Promise<void>;
+}
+
+interface INativeScopeState {
+  readonly lifetime: AbortController;
+  readonly leases: Set<NativeIntegrationLease>;
+  readonly operations: Set<Promise<unknown>>;
+  closed: boolean;
+  closePromise?: Promise<void>;
+  retryPromise?: Promise<void>;
+}
+
+const scopeState = (): INativeScopeState => ({ lifetime: new AbortController(), leases: new Set(), operations: new Set(), closed: false });
+
+class NativeIntegrationLease implements INativeSetupLease {
+  readonly #state: NativeOwnerState;
+  readonly #scope: INativeScopeState;
+  readonly #runtimeAllowed: boolean;
+  readonly #lifetime = new AbortController();
+  readonly #resources = new Set<INativeResource>();
+  readonly context: INativeAdmissionContext;
+  readonly signal: AbortSignal;
+  #pending = true;
+  #promoted = false;
+  #closed = false;
+  #closePromise?: Promise<void>;
+
+  constructor(stateArg: NativeOwnerState, scopeArg: INativeScopeState, contextArg: INativeAdmissionContext, runtimeAllowedArg: boolean) {
+    this.#state = stateArg;
+    this.#scope = scopeArg;
+    this.#runtimeAllowed = runtimeAllowedArg;
+    this.context = contextArg;
+    this.signal = AbortSignal.any([stateArg.lifetime.signal, scopeArg.lifetime.signal, this.#lifetime.signal,
+      ...(contextArg.abortSignal ? [contextArg.abortSignal] : [])]);
+    // Abort owns cleanup as well as cancellation; rejected cleanup remains on this retained lease.
+    this.signal.addEventListener('abort', () => { void this.close().catch(() => undefined); }, { once: true });
+  }
+
+  public get promoted(): boolean { return this.#promoted; }
+  public get weight(): number { return Math.max(1, [...this.#resources].filter((resource) => resource.status !== 'closed').length); }
+  public get failed(): boolean { return [...this.#resources].some((resource) => resource.status === 'failed'); }
+
+  public assertOpen(): void {
+    if (this.#closed || this.#state.closed || this.#scope.closed) throw new Error('Native admission lease is closed.');
+    this.signal.throwIfAborted();
+  }
+
+  public own(cleanupArg: () => Promise<void>): void {
+    this.assertOpen();
+    if (typeof cleanupArg !== 'function') throw new TypeError('Native cleanup must be a function.');
+    if ([...this.#resources].filter((resource) => resource.status !== 'closed').length > 0) this.#state.assertCapacity();
+    this.#resources.add({ cleanup: cleanupArg, status: 'idle' });
+  }
+
+  public promoteToRuntime(): void {
+    this.assertOpen();
+    if (!this.#runtimeAllowed || !this.#pending) throw new Error('Only an admitted pending setup can become a runtime.');
+    if (!this.#resources.size) throw new Error('A native runtime must retain an owned cleanup handle.');
+    this.#promoted = true;
+  }
+
+  public finish(): void { this.#pending = false; this.#releaseIfClosed(); }
+
+  public close(): Promise<void> {
+    if (!this.#closePromise) {
+      this.#closed = true;
+      this.#closePromise = Promise.resolve().then(() => this.#drain(false));
+      this.#lifetime.abort(new Error('Native admission lease is closed.'));
+    }
+    return this.#closePromise;
+  }
+
+  public retryCleanup(): Promise<void> { return this.#drain(true); }
+
+  async #drain(retryArg: boolean): Promise<void> {
+    const results = await Promise.allSettled([...this.#resources].map((resource) => {
+      if (retryArg && resource.status === 'failed') resource.promise = undefined;
+      if (!resource.promise) {
+        resource.status = 'pending';
+        resource.promise = Promise.resolve().then(() => resource.cleanup()).then(() => {
+          resource.status = 'closed';
+        }, (errorArg: unknown) => {
+          resource.status = 'failed';
+          throw errorArg;
+        });
+      }
+      return resource.promise;
+    }));
+    this.#releaseIfClosed();
+    const failures = results.filter((result): result is PromiseRejectedResult => result.status === 'rejected').map((result) => result.reason as unknown);
+    if (failures.length) throw new AggregateError(failures, 'Native resource cleanup failed; handles remain owned for explicit retry.');
+  }
+
+  #releaseIfClosed(): void {
+    if (!this.#pending && this.#closed && [...this.#resources].every((resource) => resource.status === 'closed')) {
+      this.#state.release(this, this.#scope);
+    }
+  }
+}
+
+class NativeOwnerState {
+  readonly admission: NativeHomeAdmission;
+  readonly lifetime = new AbortController();
+  readonly root = scopeState();
+  readonly #capacity: number;
+  readonly #leases = new Set<NativeIntegrationLease>();
+  readonly #scopes = new Set<INativeScopeState>([this.root]);
+  closed = false;
+  #closePromise?: Promise<void>;
+  #retryPromise?: Promise<void>;
+
+  constructor(domainArg: string, optionsArg: INativeIntegrationOwnerOptions) {
+    if (!optionsArg || (Object.getPrototypeOf(optionsArg) !== Object.prototype && Object.getPrototypeOf(optionsArg) !== null)) {
+      throw new TypeError('Native owner options must be a plain data object.');
+    }
+    for (const key of Reflect.ownKeys(optionsArg)) {
+      const descriptor = Object.getOwnPropertyDescriptor(optionsArg, key);
+      if ((key !== 'homeId' && key !== 'capacity') || !descriptor || !descriptor.enumerable || !('value' in descriptor)) {
+        throw new TypeError('Native owner options contain an unsupported field or accessor.');
+      }
+    }
+    this.#capacity = optionsArg.capacity ?? 16;
+    if (!Number.isSafeInteger(this.#capacity) || this.#capacity < 1) throw new RangeError('Native owner capacity must be a positive safe integer.');
+    this.admission = new NativeHomeAdmission(domainArg, { homeId: optionsArg.homeId });
+  }
+
+  public assertOpen(scopeArg: INativeScopeState): void {
+    if (this.closed || scopeArg.closed) throw new Error('Native integration owner/scope is closed.');
+  }
+
+  public assertCapacity(): void {
+    if ([...this.#leases].reduce((count, lease) => count + lease.weight, 0) >= this.#capacity) {
+      throw new Error(`Native integration ownership capacity reached: ${this.#capacity}.`);
+    }
+  }
+
+  public createScope(): INativeScopeState {
+    this.assertOpen(this.root);
+    if (this.#scopes.size > this.#capacity) throw new Error('Native config-flow scope capacity reached.');
+    const scope = scopeState();
+    this.#scopes.add(scope);
+    return scope;
+  }
+
+  public admit(scopeArg: INativeScopeState, contextArg: IIntegrationSetupContext | IConfigFlowContext, configHomeIdArg?: string): INativeAdmissionContext {
+    this.assertOpen(scopeArg);
+    return this.admission.admit(contextArg, configHomeIdArg);
+  }
+
+  public run<TResult>(scopeArg: INativeScopeState, contextArg: IIntegrationSetupContext | IConfigFlowContext,
+    configHomeIdArg: string | undefined, workArg: (leaseArg: INativeSetupLease) => Promise<TResult>, runtimeArg: boolean): Promise<TResult> {
+    this.assertOpen(scopeArg);
+    if (typeof workArg !== 'function') throw new TypeError('Native operation must be a function.');
+    if (runtimeArg && typeof configHomeIdArg !== 'string') throw new TypeError('Native setup requires configuration homeId.');
+    this.assertCapacity();
+    const context = this.admission.admit(contextArg, configHomeIdArg);
+    const lease = new NativeIntegrationLease(this, scopeArg, context, runtimeArg);
+    this.#leases.add(lease);
+    scopeArg.leases.add(lease);
+    // Publish ownership and work before invoking any caller callback.
+    const operation = Promise.resolve().then(async () => {
+      try {
+        lease.assertOpen();
+        const result = await workArg(lease);
+        if (runtimeArg) {
+          // Returning a live runtime is a new admission; a completed flow effect is already accepted.
+          lease.assertOpen();
+          if (!lease.promoted) throw new Error('Native setup must transfer its cleanup lease to the returned runtime.');
+        }
+        if (!runtimeArg) await lease.close();
+        return result;
+      } catch (errorArg) {
+        try { await lease.close(); }
+        catch (cleanupErrorArg) { throw new AggregateError([errorArg, cleanupErrorArg], 'Native operation and cleanup failed.'); }
+        throw errorArg;
+      } finally { lease.finish(); }
+    });
+    scopeArg.operations.add(operation);
+    void operation.then(() => scopeArg.operations.delete(operation), () => scopeArg.operations.delete(operation));
+    return operation;
+  }
+
+  public release(leaseArg: NativeIntegrationLease, scopeArg: INativeScopeState): void {
+    this.#leases.delete(leaseArg);
+    scopeArg.leases.delete(leaseArg);
+  }
+
+  public closeScope(scopeArg: INativeScopeState): Promise<void> {
+    if (!scopeArg.closePromise) {
+      scopeArg.closed = true;
+      scopeArg.closePromise = Promise.resolve().then(async () => {
+        await this.#drain([scopeArg]);
+        this.#scopes.delete(scopeArg);
+      });
+      for (const lease of scopeArg.leases) void lease.close().catch(() => undefined);
+      scopeArg.lifetime.abort(new Error('Native config-flow scope is closed.'));
+    }
+    return scopeArg.closePromise;
+  }
+
+  public close(): Promise<void> {
+    if (!this.#closePromise) {
+      this.closed = true;
+      for (const scope of this.#scopes) scope.closed = true;
+      this.#closePromise = Promise.resolve().then(() => this.#drain([...this.#scopes]));
+      for (const lease of this.#leases) void lease.close().catch(() => undefined);
+      this.lifetime.abort(new Error('Native integration owner is closed.'));
+      for (const scope of this.#scopes) scope.lifetime.abort(this.lifetime.signal.reason);
+    }
+    return this.#closePromise;
+  }
+
+  public retryCleanup(scopeArg?: INativeScopeState): Promise<void> {
+    const existing = scopeArg ? scopeArg.retryPromise : this.#retryPromise;
+    if (existing) return existing;
+    const retry = Promise.resolve().then(async () => {
+      const leases = [...(scopeArg ? scopeArg.leases : this.#leases)].filter((lease) => lease.failed);
+      const results = await Promise.allSettled(leases.map((lease) => lease.retryCleanup()));
+      const errors = results.filter((result): result is PromiseRejectedResult => result.status === 'rejected').map((result) => result.reason as unknown);
+      if (errors.length) throw new AggregateError(errors, 'Explicit native cleanup retry failed.');
+      for (const scope of this.#scopes) {
+        if (scope !== this.root && scope.closed && !scope.leases.size && !scope.operations.size) this.#scopes.delete(scope);
+      }
+    });
+    if (scopeArg) scopeArg.retryPromise = retry;
+    else this.#retryPromise = retry;
+    const settled = (): void => { if (scopeArg) scopeArg.retryPromise = undefined; else this.#retryPromise = undefined; };
+    void retry.then(settled, settled);
+    return retry;
+  }
+
+  async #drain(scopesArg: INativeScopeState[]): Promise<void> {
+    const cleanup = scopesArg.flatMap((scope) => [...scope.leases].map((lease) => lease.close()));
+    const operations = scopesArg.flatMap((scope) => [...scope.operations]);
+    const [results] = await Promise.all([Promise.allSettled(cleanup), Promise.allSettled(operations)]);
+    // Operation failures are delivered to their callers; owner close owns joining and cleanup failures.
+    const finalResults = await Promise.allSettled(scopesArg.flatMap((scope) => [...scope.leases].map((lease) => lease.close())));
+    const errors = [...results, ...finalResults].filter((result): result is PromiseRejectedResult => result.status === 'rejected').map((result) => result.reason as unknown);
+    if (errors.length) throw new AggregateError([...new Set(errors)], 'Native owner cleanup failed; resources remain retained.');
+  }
+}
+
+/** A terminal child scope shares owner home admission and resource capacity. */
+export class NativeIntegrationScope {
+  readonly #state: NativeOwnerState;
+  readonly #scope: INativeScopeState;
+  constructor(stateArg: NativeOwnerState, scopeArg: INativeScopeState) { this.#state = stateArg; this.#scope = scopeArg; }
+  public admit(contextArg: IConfigFlowContext, configHomeIdArg?: string): INativeAdmissionContext {
+    return this.#state.admit(this.#scope, contextArg, configHomeIdArg);
+  }
+  public run<TResult>(contextArg: IConfigFlowContext, configHomeIdArg: string | undefined,
+    workArg: (leaseArg: INativeOperationLease) => Promise<TResult>): Promise<TResult> {
+    return this.#state.run(this.#scope, contextArg, configHomeIdArg, workArg, false);
+  }
+  public close(): Promise<void> { return this.#state.closeScope(this.#scope); }
+  public retryCleanup(): Promise<void> { return this.#state.retryCleanup(this.#scope); }
+}
+
+/** Owns native admission, in-flight work, runtimes and failed cleanup without replaying transport work. */
+export class NativeIntegrationOwner {
+  readonly #state: NativeOwnerState;
+  constructor(domainArg: string, optionsArg: INativeIntegrationOwnerOptions = {}) { this.#state = new NativeOwnerState(domainArg, optionsArg); }
+  public get admission(): NativeHomeAdmission { return this.#state.admission; }
+  public get signal(): AbortSignal { return this.#state.lifetime.signal; }
+  public runSetup<TResult>(contextArg: IIntegrationSetupContext, configHomeIdArg: string,
+    workArg: (leaseArg: INativeSetupLease) => Promise<TResult>): Promise<TResult> {
+    return this.#state.run(this.#state.root, contextArg, configHomeIdArg, workArg, true);
+  }
+  public createFlowScope(): NativeIntegrationScope { return new NativeIntegrationScope(this.#state, this.#state.createScope()); }
+  public close(): Promise<void> { return this.#state.close(); }
+  public retryCleanup(): Promise<void> { return this.#state.retryCleanup(); }
+}

package/ts/core/index.ts

@@ -9,3 +9,5 @@ export * from './classes.runtimemanager.js';
 export * from './classes.simplelocalintegration.js';
 export * from './errors.js';
 export * from './types.js';
+export * from './classes.nativehomeadmission.js';
+export * from './classes.nativeintegrationowner.js';

package/ts/core/types.ts

@@ -1,4 +1,5 @@
 import * as plugins from '../plugins.js';
+import type { NoSqlConfigStore } from './classes.configstore.js';
 
 export type TDiscoverySource =
   | 'mdns'
@@ -112,11 +113,18 @@ export interface IDiscoveryDescriptorOptions {
 }
 
 export interface IIntegrationSetupContext {
+  /** Explicit owning home selected by the embedding host, never by device configuration. */
+  readonly homeId?: string;
   logger?: ILogger;
   configStore?: IConfigStore;
   abortSignal?: AbortSignal;
 }
 
+export interface INativeIntegrationSetupContext extends IIntegrationSetupContext {
+  readonly homeId: string;
+  readonly configStore?: NoSqlConfigStore;
+}
+
 export type TEntityPlatform =
   | 'light'
   | 'switch'
@@ -211,8 +219,16 @@ export interface IConfigFlowField {
 }
 
 export interface IConfigFlowContext {
+  /** Explicit owning home selected by the embedding host. This is not an authentication token. */
+  readonly homeId?: string;
   logger?: ILogger;
   configStore?: IConfigStore;
+  abortSignal?: AbortSignal;
+}
+
+export interface INativeConfigFlowContext extends IConfigFlowContext {
+  readonly homeId: string;
+  readonly configStore?: NoSqlConfigStore;
 }
 
 export interface IConfigFlowStep<TConfig = unknown> {