@smarthome.exchange/integrations 0.2.0 → 2.0.0

package/ts/integrations/wled/wled.types.ts

@@ -1,93 +1,65 @@
-import type { ISimpleLocalConfig, ISimpleLocalIntegrationProfile, ISimpleLocalSnapshot, TSimpleLocalRawData } from '../../core/index.js';
+export const wledDomain = 'wled';
+export const wledDefaultName = 'WLED';
 
-export const wledDomain = "wled";
-export const wledDefaultName = "WLED";
+export interface IWledConfig {
+  host: string;
+  port?: number;
+  expectedMac?: string;
+  requestTimeoutMs?: number;
+}
 
-export type TWledRawData = TSimpleLocalRawData;
-export interface IWledSnapshot extends ISimpleLocalSnapshot {}
-export interface IWledConfig extends ISimpleLocalConfig {}
 export interface IHomeAssistantWledConfig extends IWledConfig {}
 
-export const wledProfile: ISimpleLocalIntegrationProfile = {
-  domain: "wled",
-  displayName: "WLED",
-  manufacturer: "WLED",
-  model: "WLED controller",
-  defaultName: "WLED",
-  defaultPort: 80,
-  defaultHttpPath: "/json",
-  defaultProtocol: "http",
-  status: "control-runtime",
-  platforms: [
-    "light",
-    "sensor"
-  ],
-  serviceDomains: [
-    "light"
-  ],
-  controlServices: [
-    "turn_on",
-    "turn_off",
-    "toggle",
-    "set_level"
-  ],
-  discoverySources: [
-    "manual",
-    "mdns",
-    "ssdp",
-    "http",
-    "custom"
-  ],
-  discoveryKeywords: [
-    "wled",
-    "esp8266",
-    "esp32"
-  ],
+export interface IWledInfo {
+  mac: string;
+  name: string;
+  ver: string;
+  brand: 'WLED';
+  product?: string;
+  ws?: number;
+  leds: { count: number; maxseg: number; seglc?: number[] };
+}
+
+export interface IWledSegment {
+  id: number;
+  start: number;
+  stop: number;
+  on: boolean;
+  bri: number;
+  col: number[][];
+  n?: string;
+}
+
+export interface IWledState { on: boolean; bri: number; seg: IWledSegment[] }
+
+export interface IWledSnapshot {
+  info: IWledInfo;
+  state: IWledState;
+  updatedAt: string;
+}
+
+export type TWledRawData = { info: IWledInfo; state: IWledState };
+export interface IWledStateChange {
+  on?: boolean;
+  brightness?: number;
+  rgb?: [number, number, number];
+  white?: number;
+}
+export type TWledClientEvent =
+  | { type: 'snapshot'; snapshot: IWledSnapshot }
+  | { type: 'availability'; available: boolean }
+  | { type: 'error'; error: Error };
+
+export const wledProfile = {
+  domain: wledDomain,
+  displayName: wledDefaultName,
+  status: 'control-runtime',
   metadata: {
-    source: "home-assistant/core",
-    upstreamPath: "homeassistant/components/wled",
-    upstreamDomain: "wled",
-    integrationType: "device",
-    iotClass: "local_push",
-    qualityScale: "platinum",
-    requirements: [
-      "wled==0.22.0"
-    ],
-    dependencies: [],
-    afterDependencies: [],
-    codeowners: [
-      "@frenck",
-      "@mik-laj"
-    ],
+    source: 'native-typescript',
+    upstreamDomain: wledDomain,
+    integrationType: 'device',
+    iotClass: 'local_push',
     configFlow: true,
-    runtime: {
-      type: "control-runtime",
-      services: [
-        "snapshot",
-        "status",
-        "refresh",
-        "turn_on",
-        "turn_off",
-        "toggle",
-        "set_level"
-      ],
-      platforms: [
-        "light",
-        "sensor"
-      ],
-      controls: true
-    },
-    localApi: {
-      implemented: [
-        "manual local endpoint setup",
-        "snapshot, raw data, snapshotProvider, and injected native client operation",
-        "generic HTTP/TCP local transport when config.path, config.transport, or documented defaults are supplied"
-      ],
-      explicitUnsupported: [
-        "claiming live command success without injected client.execute or commandExecutor",
-        "cloud account flows and remote API polling",
-        "device-specific protocol features not represented by snapshot/rawData/client/executor inputs"
-      ]
-    }
-  }
-};
+    runtime: { type: 'control-runtime', platforms: ['light'], services: ['turn_on', 'turn_off', 'set_level', 'set_color'], controls: true },
+  },
+} as const;

package/ts/integrations/wled/wled.validation.ts

@@ -0,0 +1,72 @@
+import * as plugins from '../../plugins.js';
+import { DeviceCommunicationError } from '../../core/errors.js';
+import type { IWledConfig, IWledInfo, IWledSegment, IWledSnapshot, IWledState } from './wled.types.js';
+
+export const isWledRecord = (valueArg: unknown): valueArg is Record<string, unknown> =>
+  typeof valueArg === 'object' && valueArg !== null && !Array.isArray(valueArg);
+
+export const wledInteger = (valueArg: unknown, minArg: number, maxArg: number): valueArg is number =>
+  typeof valueArg === 'number' && Number.isSafeInteger(valueArg) && valueArg >= minArg && valueArg <= maxArg;
+
+export const normalizeWledMac = (valueArg: unknown): string => {
+  if (typeof valueArg !== 'string' || !/^(?:[a-f\d]{12}|(?:[a-f\d]{2}:){5}[a-f\d]{2})$/i.test(valueArg)) throw new Error('WLED requires a valid 12-digit MAC identity.');
+  return valueArg.replace(/:/g, '').toLowerCase();
+};
+
+export const wledConfig = (valueArg: unknown): IWledConfig => {
+  if (!isWledRecord(valueArg) || Object.getPrototypeOf(valueArg) !== Object.prototype) throw new Error('WLED config must be a plain object.');
+  const descriptors = Object.getOwnPropertyDescriptors(valueArg);
+  if (Reflect.ownKeys(valueArg).some((keyArg) => typeof keyArg !== 'string' || !['host', 'port', 'expectedMac', 'requestTimeoutMs'].includes(keyArg) || !('value' in descriptors[keyArg]))) throw new Error('WLED config contains unsupported settings or accessors.');
+  const host = valueArg.host;
+  if (typeof host !== 'string' || !host || /[\s\/?#@\\%]/.test(host)) throw new Error('WLED host must be an explicit hostname or IP address.');
+  const ip = host.startsWith('[') && host.endsWith(']') ? host.slice(1, -1) : host;
+  if (!plugins.net.isIP(ip) && !/^(?=.{1,253}$)(?:[a-z\d](?:[a-z\d-]{0,61}[a-z\d])?\.)*[a-z\d](?:[a-z\d-]{0,61}[a-z\d])?\.?$/i.test(host)) throw new Error('WLED host must be an explicit hostname or IP address.');
+  const port = valueArg.port === undefined ? 80 : valueArg.port;
+  const timeout = valueArg.requestTimeoutMs === undefined ? 5000 : valueArg.requestTimeoutMs;
+  if (!wledInteger(port, 1, 65535) || !wledInteger(timeout, 10, 60000)) throw new Error('WLED port or request timeout is invalid.');
+  return { host, port, requestTimeoutMs: timeout, expectedMac: valueArg.expectedMac === undefined ? undefined : normalizeWledMac(valueArg.expectedMac) };
+};
+
+export const wledEndpoint = (configArg: IWledConfig): URL => {
+  const host = configArg.host.includes(':') && !configArg.host.startsWith('[') ? `[${configArg.host}]` : configArg.host;
+  return new URL(`http://${host}:${configArg.port ?? 80}`);
+};
+
+const text = (valueArg: unknown, requiredArg = true): valueArg is string =>
+  typeof valueArg === 'string' && (!requiredArg || valueArg.length > 0) && valueArg.length <= 256 && !/[\u0000-\u001f\u007f]/.test(valueArg);
+
+export const parseWledSnapshot = (valueArg: unknown, expectedMacArg?: string): IWledSnapshot => {
+  const invalid = (): never => { throw new DeviceCommunicationError('WLED returned an invalid state and device information payload.'); };
+  if (!isWledRecord(valueArg) || !isWledRecord(valueArg.info) || !isWledRecord(valueArg.state)) return invalid();
+  const infoValue = valueArg.info;
+  const stateValue = valueArg.state;
+  if (!text(infoValue.name) || !text(infoValue.ver) || infoValue.brand !== 'WLED' || !isWledRecord(infoValue.leds)) return invalid();
+  let mac: string;
+  try { mac = normalizeWledMac(infoValue.mac); } catch { return invalid(); }
+  if (expectedMacArg !== undefined && expectedMacArg !== mac) throw new DeviceCommunicationError('WLED endpoint device identity changed or does not match the configured MAC.');
+  const ledsValue = infoValue.leds;
+  if (!wledInteger(ledsValue.count, 1, 65535) || !wledInteger(ledsValue.maxseg, 1, 255)) return invalid();
+  if (infoValue.product !== undefined && !text(infoValue.product) || infoValue.ws !== undefined && !wledInteger(infoValue.ws, -1, 255)) return invalid();
+  if (ledsValue.seglc !== undefined && (!Array.isArray(ledsValue.seglc) || ledsValue.seglc.length > ledsValue.maxseg || ledsValue.seglc.some((entryArg: unknown) => !wledInteger(entryArg, 0, 255)))) return invalid();
+  if (typeof stateValue.on !== 'boolean' || !wledInteger(stateValue.bri, 1, 255) || !Array.isArray(stateValue.seg) || stateValue.seg.length > ledsValue.maxseg) return invalid();
+  const segments: IWledSegment[] = [];
+  const ids = new Set<number>();
+  for (const [index, entry] of stateValue.seg.entries()) {
+    if (!isWledRecord(entry)) return invalid();
+    const id = entry.id ?? index;
+    if (!wledInteger(id, 0, ledsValue.maxseg - 1) || ids.has(id) || !wledInteger(entry.start, 0, ledsValue.count) || !wledInteger(entry.stop, 0, ledsValue.count)) return invalid();
+    ids.add(id);
+    if (entry.stop <= entry.start) continue;
+    if (typeof entry.on !== 'boolean' || !wledInteger(entry.bri, 0, 255) || !Array.isArray(entry.col) || entry.col.length < 1 || entry.col.length > 3 || entry.n !== undefined && !text(entry.n, false)) return invalid();
+    const colors: number[][] = [];
+    for (const color of entry.col) {
+      if (!Array.isArray(color) || ![3, 4].includes(color.length) || color.some((channelArg: unknown) => !wledInteger(channelArg, 0, 255))) return invalid();
+      colors.push([...color]);
+    }
+    segments.push({ id, start: entry.start, stop: entry.stop, on: entry.on, bri: entry.bri, col: colors, n: entry.n });
+  }
+  const info: IWledInfo = { mac, name: infoValue.name, ver: infoValue.ver, brand: 'WLED', product: infoValue.product, ws: infoValue.ws,
+    leds: { count: ledsValue.count, maxseg: ledsValue.maxseg, seglc: ledsValue.seglc === undefined ? undefined : [...ledsValue.seglc] } };
+  const state: IWledState = { on: stateValue.on, bri: stateValue.bri, seg: segments.sort((leftArg, rightArg) => leftArg.id - rightArg.id) };
+  return { info, state, updatedAt: new Date().toISOString() };
+};

package/ts/integrations/yamaha/index.ts

@@ -4,3 +4,4 @@ export * from './yamaha.classes.integration.js';
 export * from './yamaha.discovery.js';
 export * from './yamaha.mapper.js';
 export * from './yamaha.types.js';
+export * from './yamaha.validation.js';

package/ts/integrations/yamaha/yamaha.classes.client.ts

@@ -1,9 +1,153 @@
-import { SimpleLocalClient } from '../../core/index.js';
-import type { IYamahaConfig } from './yamaha.types.js';
-import { yamahaProfile } from './yamaha.types.js';
+import * as plugins from '../../plugins.js';
+import { NativeHomeAdmission, type INativeAdmissionContext } from '../../core/classes.nativehomeadmission.js';
+import type { INativeIntegrationSetupContext } from '../../core/types.js';
+import type { IYamahaConfig, IYamahaEffectResult, IYamahaSnapshot, TYamahaControl } from './yamaha.types.js';
+import { assertYamahaScope, normalizeYamahaConfig, validateYamahaControl } from './yamaha.validation.js';
 
-export class YamahaClient extends SimpleLocalClient<IYamahaConfig> {
-  constructor(configArg: IYamahaConfig) {
-    super(yamahaProfile, configArg);
+/** The published protocol owns wire behavior; this facade owns exact home admission and caller work. */
+export class YamahaClient {
+  public readonly config: ReturnType<typeof normalizeYamahaConfig>;
+  private readonly context: INativeAdmissionContext;
+  private readonly protocol: plugins.ecobridgeDeviceManager.YamahaProtocol;
+  private readonly lifetime = new AbortController();
+  private operationTail: Promise<void> = Promise.resolve();
+  private pendingOperations = 0;
+  private startPromise?: Promise<IYamahaSnapshot>;
+  private snapshot?: IYamahaSnapshot;
+  private healthy = false;
+  private closePromise?: Promise<void>;
+  private retryPromise?: Promise<void>;
+
+  public constructor(config: IYamahaConfig, context: INativeIntegrationSetupContext) {
+    this.config = normalizeYamahaConfig(config);
+    this.context = new NativeHomeAdmission('yamaha').admit(context, this.config.homeId);
+    this.protocol = new plugins.ecobridgeDeviceManager.YamahaProtocol({ origin: this.config.origin,
+      expectedDeviceId: this.config.expectedDeviceId, expectedModel: this.config.model,
+      allowUnencryptedHttp: this.config.allowUnencryptedHttp, maxVolume: this.config.maxVolume,
+      timeoutMs: this.config.timeoutMs, maxResponseBytes: this.config.maxResponseBytes, maxPendingOperations: this.config.maxPendingOperations });
+  }
+
+  public isHealthy(): boolean { return !this.lifetime.signal.aborted && !this.context.abortSignal?.aborted && this.healthy && this.protocol.isStarted; }
+
+  public start(signal?: AbortSignal): Promise<IYamahaSnapshot> {
+    try { this.assertOpen(); } catch (error) { return Promise.reject(error); }
+    if (!this.startPromise) {
+      this.startPromise = this.run(async (operationSignal, timeoutMs) => this.observe(await this.protocol.start({ signal: operationSignal, timeoutMs })),
+        signal, false).catch(async (error: unknown) => {
+          this.lifetime.abort(error);
+          try { await this.protocol.close(); }
+          catch (cleanupError) { throw new AggregateError([error, cleanupError], 'Yamaha startup and cleanup failed.'); }
+          throw error;
+        });
+    }
+    return this.startPromise;
+  }
+
+  public getObservedSnapshot(): IYamahaSnapshot {
+    this.assertOpen();
+    if (!this.snapshot) throw new Error('Yamaha has no admitted observation.');
+    return this.snapshot;
+  }
+
+  public getSnapshot(signal?: AbortSignal): Promise<IYamahaSnapshot> {
+    return this.run(async (operationSignal, timeoutMs) => this.observe(await this.protocol.readState({ signal: operationSignal, timeoutMs })), signal);
+  }
+
+  public setControl(value: TYamahaControl, signal?: AbortSignal): Promise<IYamahaEffectResult> {
+    const control = validateYamahaControl(value);
+    if (control.feature === 'volume_raw' && control.value > this.config.maxVolume) throw new RangeError('Yamaha volume exceeds the owner ceiling.');
+    return this.run(async (operationSignal, timeoutMs) => {
+      const options = { signal: operationSignal, timeoutMs };
+      const result = control.feature === 'power' ? await this.protocol.setPower(control.value, options)
+        : control.feature === 'muted' ? await this.protocol.setMute(control.value, options)
+        : control.feature === 'volume_raw' ? await this.protocol.setVolume(control.value, options)
+        : await this.protocol.setInput(control.value, options);
+      try { return Object.freeze({ dispatch: result.dispatch, outcome: result.outcome, snapshot: this.observe(result.observation) }); }
+      catch { throw new plugins.ecobridgeDeviceManager.YamahaProtocolError('Yamaha observation could not be admitted after dispatch.', 'identity-mismatch', 'indeterminate'); }
+    }, signal);
+  }
+
+  public destroy(): Promise<void> {
+    if (!this.closePromise) {
+      this.healthy = false;
+      this.closePromise = Promise.resolve().then(() => this.drain());
+      this.lifetime.abort(new Error('Yamaha client is closed.'));
+    }
+    return this.closePromise;
+  }
+
+  /** Explicitly retries cleanup of this terminal client, without replaying receiver work. */
+  public retryCleanup(): Promise<void> {
+    if (!this.closePromise) return Promise.reject(new Error('Yamaha cleanup retry requires a closed client.'));
+    if (!this.retryPromise) {
+      const retry = Promise.resolve().then(() => this.drain());
+      this.retryPromise = retry;
+      const settled = (): void => { this.retryPromise = undefined; };
+      void retry.then(settled, settled);
+    }
+    return this.retryPromise;
+  }
+
+  private async drain(): Promise<void> {
+    const results = await Promise.allSettled([
+      Promise.resolve().then(() => this.protocol.close()), this.operationTail, this.startPromise,
+    ]);
+    this.snapshot = undefined;
+    const closure = results[0];
+    if (closure.status === 'rejected') throw closure.reason;
+  }
+
+  private observe(state: plugins.ecobridgeDeviceManager.IYamahaState): IYamahaSnapshot {
+    this.assertOpen();
+    this.snapshot = Object.freeze({ homeId: this.context.homeId, origin: this.config.origin,
+      name: this.config.name ?? 'Yamaha RX-V485 main zone', identity: Object.freeze({ ...state.identity }),
+      power: state.power, muted: state.muted, volume: state.volume, receiverMaxVolume: state.maxVolume,
+      ownerMaxVolume: this.config.maxVolume, input: state.input, inputs: Object.freeze([...state.capabilities.inputs]),
+      volumeRange: Object.freeze({ ...state.capabilities.volumeRange }), observedAt: state.observedAt });
+    this.healthy = true;
+    return this.snapshot;
+  }
+
+  private assertOpen(): void {
+    this.lifetime.signal.throwIfAborted();
+    if (this.context.abortSignal) AbortSignal.prototype.throwIfAborted.call(this.context.abortSignal);
+    assertYamahaScope(this.context.configStore, this.context.homeId);
+  }
+
+  /** Validate scope when adapter work runs; its single deadline includes waiting for earlier calls. */
+  private run<TResult>(execute: (signal: AbortSignal, timeoutMs: number) => Promise<TResult>, signal?: AbortSignal, started = true): Promise<TResult> {
+    try {
+      this.assertOpen();
+      if (signal !== undefined && !(signal instanceof AbortSignal)) throw new TypeError('Yamaha cancellation requires an AbortSignal.');
+      signal?.throwIfAborted();
+      if (started && !this.protocol.isStarted) throw new Error('Yamaha client has not started.');
+      if (this.pendingOperations >= this.config.maxPendingOperations) throw new Error('Yamaha operation capacity reached.');
+    } catch (error) { return Promise.reject(error); }
+    const deadline = performance.now() + this.config.timeoutMs;
+    const controller = new AbortController();
+    const combined = AbortSignal.any([this.lifetime.signal, controller.signal,
+      ...(this.context.abortSignal ? [this.context.abortSignal] : []), ...(signal ? [signal] : [])]);
+    const timer = setTimeout(() => controller.abort(new plugins.ecobridgeDeviceManager.YamahaProtocolError('Yamaha operation deadline expired.', 'timeout')), this.config.timeoutMs);
+    this.pendingOperations++;
+    let rejectWaiting: () => void = () => {};
+    const waitingCancelled = new Promise<never>((_resolve, reject) => {
+      rejectWaiting = () => reject(combined.reason);
+      combined.addEventListener('abort', rejectWaiting, { once: true });
+    });
+    const operation = this.operationTail.then(async () => {
+      combined.removeEventListener('abort', rejectWaiting);
+      combined.throwIfAborted();
+      this.assertOpen();
+      const remaining = Math.floor(deadline - performance.now());
+      if (remaining < 1) throw new plugins.ecobridgeDeviceManager.YamahaProtocolError('Yamaha queued operation expired.', 'timeout');
+      return execute(combined, remaining);
+    }).catch((error: unknown) => { this.healthy = false; throw error; }).finally(() => {
+      combined.removeEventListener('abort', rejectWaiting);
+      clearTimeout(timer);
+      this.pendingOperations--;
+    });
+    this.operationTail = operation.then(() => {}, () => {});
+    if (combined.aborted) rejectWaiting();
+    return Promise.race([operation, waitingCancelled]);
   }
 }

package/ts/integrations/yamaha/yamaha.classes.configflow.ts

@@ -1,9 +1,104 @@
-import { SimpleLocalConfigFlow } from '../../core/index.js';
+import * as plugins from '../../plugins.js';
+import { NativeIntegrationOwner, NativeIntegrationScope } from '../../core/classes.nativeintegrationowner.js';
+import type { IConfigFlow, INativeConfigFlowContext, IConfigFlowStep, IDiscoveryCandidate } from '../../core/types.js';
 import type { IYamahaConfig } from './yamaha.types.js';
-import { yamahaProfile } from './yamaha.types.js';
+import { YamahaClient } from './yamaha.classes.client.js';
+import { normalizeYamahaConfig, yamahaRecord } from './yamaha.validation.js';
 
-export class YamahaConfigFlow extends SimpleLocalConfigFlow<IYamahaConfig> {
-  constructor() {
-    super(yamahaProfile);
+interface IYamahaConfigWrite {
+  readonly promise: Promise<void>;
+  accepted: boolean;
+}
+
+export class YamahaConfigFlow implements IConfigFlow<IYamahaConfig> {
+  private readonly scope: NativeIntegrationScope;
+  private readonly writes = new Set<IYamahaConfigWrite>();
+  private closePromise?: Promise<void>;
+
+  public constructor(scope: NativeIntegrationScope = new NativeIntegrationOwner('yamaha').createFlowScope()) {
+    this.scope = scope;
+  }
+
+  public async start(input: IDiscoveryCandidate, context: INativeConfigFlowContext): Promise<IConfigFlowStep<IYamahaConfig>> {
+    const candidate = yamahaRecord(input);
+    if (candidate.integrationDomain !== 'yamaha') return { kind: 'error', error: 'Candidate does not belong to Yamaha.' };
+    const metadata = candidate.metadata === undefined ? {} : yamahaRecord(candidate.metadata);
+    const hints = { origin: metadata.origin, expectedDeviceId: candidate.id, model: candidate.model };
+    const captured = this.scope.admit(context);
+    let pending = false;
+    let completed = false;
+    return {
+      kind: 'form', title: 'Connect selected Yamaha RX-V485 main zone',
+      description: 'Confirm selected literal private HTTP origin, expected device_id, plaintext LAN trust and an owner ceiling in vendor raw integer volume units. The embedding host selects the home. No percentage or dB conversion is inferred.',
+      fields: [
+        { name: 'origin', label: 'Selected receiver HTTP origin', type: 'text', required: true },
+        { name: 'expectedDeviceId', label: 'Expected 12-character device_id', type: 'text', required: true },
+        { name: 'model', label: 'Documented model', type: 'select', required: true, options: [{ label: 'RX-V485', value: 'RX-V485' }] },
+        { name: 'allowUnencryptedHttp', label: 'Allow unauthenticated plaintext LAN HTTP', type: 'boolean', required: true },
+        { name: 'maxVolume', label: 'Owner maximum volume (vendor raw integer units)', type: 'number', required: true },
+        { name: 'name', label: 'Display name', type: 'text' },
+      ],
+      submit: (inputValues) => {
+        if (pending || completed) return Promise.reject(new Error('Yamaha config flow submission is unavailable.'));
+        try {
+          const values = yamahaRecord(inputValues, ['homeId', 'origin', 'expectedDeviceId', 'model', 'allowUnencryptedHttp', 'maxVolume', 'name', 'timeoutMs', 'maxResponseBytes', 'maxPendingOperations']);
+          if (values.homeId !== undefined && values.homeId !== captured.homeId) throw new Error('Yamaha submitted home conflicts with the selected host home.');
+          const config = normalizeYamahaConfig({ ...hints, ...values, homeId: captured.homeId });
+          const submission = this.scope.run(captured, config.homeId, async (lease): Promise<IConfigFlowStep<IYamahaConfig>> => {
+            const client = new YamahaClient(config, lease.context);
+            let cleanupStarted = false;
+            lease.own(() => {
+              const retry = cleanupStarted;
+              cleanupStarted = true;
+              return retry ? client.retryCleanup() : client.destroy();
+            });
+            try { await client.start(lease.signal); }
+            catch (error) {
+              if (!lease.signal.aborted && error instanceof plugins.ecobridgeDeviceManager.YamahaProtocolError) {
+                return { kind: 'error', title: 'Receiver admission failed', error: error.message };
+              }
+              throw error;
+            }
+            lease.assertOpen();
+            const store = lease.context.configStore;
+            if (store) {
+              // Ownership precedes a synchronous caller callback; accepted writes drain during close.
+              const write: IYamahaConfigWrite = { accepted: false, promise: Promise.resolve().then(async () => {
+                lease.assertOpen();
+                write.accepted = true;
+                await store.set(`receiver.${encodeURIComponent(config.expectedDeviceId)}`, config);
+              }) };
+              this.writes.add(write);
+              try { await write.promise; } finally { this.writes.delete(write); }
+            }
+            completed = true;
+            return { kind: 'done', title: 'Selected receiver admitted', config };
+          });
+          pending = true;
+          const settled = (): void => { pending = false; };
+          void submission.then(settled, settled);
+          return submission;
+        } catch (error) { return Promise.reject(error); }
+      },
+    };
+  }
+
+  public destroy(): Promise<void> {
+    if (!this.closePromise) {
+      const writes = [...this.writes];
+      this.closePromise = Promise.resolve().then(async () => {
+        const [cleanup, results] = await Promise.all([
+          Promise.allSettled([this.scope.close()]), Promise.allSettled(writes.map((write) => write.promise)),
+        ]);
+        const failures = cleanup.filter((entry): entry is PromiseRejectedResult => entry.status === 'rejected').map((entry) => entry.reason as unknown);
+        results.forEach((entry, index) => { if (entry.status === 'rejected' && writes[index].accepted) failures.push(entry.reason); });
+        if (failures.length) throw new AggregateError(failures, 'Yamaha config flow cleanup failed.');
+      });
+      // Terminal admission is immediate; close owns all accepted submissions and borrowed-store writes.
+      void this.scope.close().catch(() => undefined);
+    }
+    return this.closePromise;
   }
+
+  public retryCleanup(): Promise<void> { return this.scope.retryCleanup(); }
 }