@smarthome.exchange/integrations 1.0.0 → 3.0.0

package/ts/integrations/wiz/wiz.types.ts

@@ -1,223 +1,41 @@
-import type { IServiceCallRequest, TEntityPlatform } from '../../core/types.js';
+import type * as plugins from '../../plugins.js';
 
 export const wizDefaultPort = 38899;
 
-export type TWizBulbType = 'rgb' | 'tw' | 'dw' | 'socket' | 'fan' | 'unknown' | string;
-export type TWizDiscoveryProtocol = 'mdns' | 'udp' | 'manual';
-
 export interface IWizConfig {
-  host?: string;
+  homeId: string;
+  host: string;
+  macAddress: string;
   port?: number;
-  mac?: string;
   name?: string;
-  deviceInfo?: IWizDeviceInfo;
-  pilot?: IWizPilotState;
-  snapshot?: IWizSnapshot;
-  devices?: IWizSnapshotDevice[];
-  manualEntries?: IWizManualEntry[];
-  events?: IWizEvent[];
   timeoutMs?: number;
-  commandExecutor?: TWizCommandExecutor;
-  [key: string]: unknown;
+  /** Zero disables subscription polling; explicit reads still deliver observations. */
+  pollIntervalMs?: number;
+  maxPendingOperations?: number;
+  maxExchanges?: number;
 }
 
 export interface IHomeAssistantWizConfig extends IWizConfig {}
 
-export interface IWizDeviceFeatures {
-  light?: boolean;
-  switch?: boolean;
-  brightness?: boolean;
-  color?: boolean;
-  colorTemp?: boolean;
-  effect?: boolean;
-  fan?: boolean;
-  fanReverse?: boolean;
-  fanBreezeMode?: boolean;
-  power?: boolean;
-  occupancy?: boolean;
-  button?: boolean;
-  dualHead?: boolean;
-  [key: string]: unknown;
-}
-
-export interface IWizKelvinRange {
-  min?: number;
-  max?: number;
-}
-
-export interface IWizDeviceInfo {
-  id?: string;
-  mac?: string;
-  host?: string;
-  port?: number;
-  name?: string;
-  manufacturer?: string;
-  model?: string;
-  moduleName?: string;
-  fwVersion?: string;
-  typeId?: number | string;
-  bulbType?: TWizBulbType;
-  isSocket?: boolean;
-  whiteChannels?: number;
-  kelvinRange?: IWizKelvinRange;
-  fanSpeedRange?: number;
-  powerMonitoring?: boolean;
-  features?: IWizDeviceFeatures;
-  [key: string]: unknown;
-}
-
-export interface IWizPilotState {
-  mac?: string;
-  rssi?: number;
-  src?: string;
-  state?: boolean;
-  sceneId?: number;
-  schdPsetId?: number;
-  temp?: number;
-  dimming?: number;
-  r?: number;
-  g?: number;
-  b?: number;
-  c?: number;
-  w?: number;
-  speed?: number;
-  ratio?: number;
-  pc?: number;
-  fanState?: number;
-  fanMode?: number;
-  fanSpeed?: number;
-  fanRevrs?: number;
-  [key: string]: unknown;
-}
-
-export interface IWizPilotPatch {
-  state?: boolean;
-  sceneId?: number;
-  temp?: number;
-  dimming?: number;
-  r?: number;
-  g?: number;
-  b?: number;
-  c?: number;
-  w?: number;
-  speed?: number;
-  ratio?: number;
-  fanState?: number;
-  fanMode?: number;
-  fanSpeed?: number;
-  fanRevrs?: number;
-  [key: string]: unknown;
-}
-
-export interface IWizSensorRecord {
-  key: string;
-  name?: string;
-  platform?: 'sensor' | 'binary_sensor';
-  value?: unknown;
-  unit?: string;
-  deviceClass?: string;
-  writable?: boolean;
-  available?: boolean;
-  [key: string]: unknown;
-}
-
-export interface IWizButtonRecord {
-  key: string;
-  name?: string;
-  value?: unknown;
-  lastPressedAt?: string | number;
-  available?: boolean;
-  [key: string]: unknown;
-}
-
-export interface IWizEntityRecord {
-  platform: TEntityPlatform;
-  key?: string;
-  entityId?: string;
-  uniqueId?: string;
-  name?: string;
-  state?: unknown;
-  attributes?: Record<string, unknown>;
-  available?: boolean;
-  writable?: boolean;
-  [key: string]: unknown;
-}
-
-export interface IWizSnapshotDevice {
-  id?: string;
-  host?: string;
-  port?: number;
-  mac?: string;
-  name?: string;
-  available?: boolean;
-  deviceInfo?: IWizDeviceInfo;
-  pilot?: IWizPilotState;
-  sensors?: IWizSensorRecord[];
-  buttons?: IWizButtonRecord[];
-  entities?: IWizEntityRecord[];
-  metadata?: Record<string, unknown>;
-  [key: string]: unknown;
-}
+export type TWizControl =
+  | { readonly feature: 'power'; readonly value: boolean }
+  | { readonly feature: 'brightness'; readonly value: number }
+  | { readonly feature: 'rgb'; readonly value: Readonly<plugins.ecobridgeDeviceManager.IWizRgb> };
 
 export interface IWizSnapshot {
-  connected: boolean;
-  host?: string;
-  port?: number;
-  devices: IWizSnapshotDevice[];
-  events: IWizEvent[];
+  readonly homeId: string;
+  readonly host: string;
+  readonly port: number;
+  readonly name?: string;
+  readonly info: plugins.ecobridgeDeviceManager.IWizDeviceInfo;
+  readonly observedAt: string;
 }
 
-export interface IWizEvent {
-  type: 'pilot' | 'command_mapped' | 'command_failed' | 'udp_response' | 'error' | string;
-  timestamp?: number;
-  deviceId?: string;
-  entityId?: string;
-  command?: IWizClientCommand;
-  data?: unknown;
-  [key: string]: unknown;
-}
-
-export interface IWizClientCommand {
-  type: string;
-  service: string;
-  deviceId?: string;
-  entityId?: string;
-  payload: IWizPilotPatch;
-  target?: IServiceCallRequest['target'];
-  [key: string]: unknown;
-}
-
-export interface IWizCommandResult {
-  success: boolean;
-  error?: string;
-  data?: unknown;
-}
-
-export type TWizCommandExecutor = (
-  commandArg: IWizClientCommand
-) => Promise<IWizCommandResult | unknown> | IWizCommandResult | unknown;
-
-export interface IWizUdpCommand<TParams extends Record<string, unknown> = Record<string, unknown>> {
-  method: string;
-  params?: TParams;
-  id?: number | string;
-  env?: string;
-}
-
-export interface IWizUdpError {
-  code?: number;
-  message?: string;
-  data?: unknown;
-}
-
-export interface IWizUdpResponse<TResult = unknown> {
-  method?: string;
-  env?: string;
-  id?: number | string;
-  result?: TResult;
-  params?: TResult;
-  error?: IWizUdpError;
-  [key: string]: unknown;
+export interface IWizWriteResult {
+  readonly outcome: plugins.ecobridgeDeviceManager.TWizEffectOutcome;
+  readonly physicalStateConfirmed: false;
+  readonly observedState?: plugins.ecobridgeDeviceManager.IWizPilotState;
+  readonly errorCode?: plugins.ecobridgeDeviceManager.TWizErrorCode;
 }
 
 export interface IWizMdnsRecord {
@@ -229,37 +47,19 @@ export interface IWizMdnsRecord {
   port?: number;
   txt?: Record<string, string | undefined>;
   properties?: Record<string, string | undefined>;
-  [key: string]: unknown;
 }
 
 export interface IWizUdpDiscoveryRecord {
   host?: string;
-  address?: string;
-  ip?: string;
-  ip_address?: string;
   port?: number;
-  mac?: string;
-  mac_address?: string;
-  name?: string;
   method?: string;
   result?: Record<string, unknown>;
-  response?: IWizUdpResponse<Record<string, unknown>>;
-  metadata?: Record<string, unknown>;
-  [key: string]: unknown;
+  response?: { method?: string; result?: Record<string, unknown> };
 }
 
 export interface IWizManualEntry {
   host?: string;
   port?: number;
-  id?: string;
-  mac?: string;
   macAddress?: string;
   name?: string;
-  manufacturer?: string;
-  model?: string;
-  deviceInfo?: IWizDeviceInfo;
-  pilot?: IWizPilotState;
-  snapshot?: IWizSnapshot;
-  metadata?: Record<string, unknown>;
-  [key: string]: unknown;
 }

package/ts/integrations/wiz/wiz.validation.ts

@@ -0,0 +1,73 @@
+import * as plugins from '../../plugins.js';
+import type { IWizConfig, TWizControl } from './wiz.types.js';
+
+export function wizRecord(valueArg: unknown, allowedArg?: readonly string[]): Record<string, unknown> {
+  if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg) || Object.getPrototypeOf(valueArg) !== Object.prototype) {
+    throw new TypeError('WiZ inputs must be plain data objects.');
+  }
+  const result: Record<string, unknown> = {};
+  for (const key of Reflect.ownKeys(valueArg)) {
+    const descriptor = Object.getOwnPropertyDescriptor(valueArg, key);
+    if (typeof key !== 'string' || allowedArg && !allowedArg.includes(key) || !descriptor || !('value' in descriptor) || !descriptor.enumerable) {
+      throw new TypeError('WiZ inputs may not contain accessors, symbols, hidden or unsupported fields.');
+    }
+    Object.defineProperty(result, key, { value: descriptor.value, enumerable: true });
+  }
+  return result;
+}
+
+export function wizText(valueArg: unknown, nameArg: string, maximumArg = 256): string {
+  if (typeof valueArg !== 'string' || !valueArg.length || valueArg.length > maximumArg || valueArg !== valueArg.trim() || /[\p{Cc}\p{Cs}]/u.test(valueArg)) {
+    throw new TypeError(`WiZ ${nameArg} must be bounded nonempty text without control characters.`);
+  }
+  return valueArg;
+}
+
+export function wizMac(valueArg: unknown): string {
+  if (typeof valueArg !== 'string' || !/^(?:[a-fA-F0-9]{12}|(?:[a-fA-F0-9]{2}:){5}[a-fA-F0-9]{2})$/.test(valueArg)) {
+    throw new TypeError('WiZ macAddress requires exactly six hexadecimal bytes.');
+  }
+  const mac = valueArg.replaceAll(':', '').toLowerCase();
+  if (mac === '000000000000' || (Number.parseInt(mac.slice(0, 2), 16) & 1) !== 0) throw new TypeError('WiZ requires a unicast device MAC.');
+  return mac;
+}
+
+export function wizAddress(valueArg: unknown): string {
+  if (typeof valueArg !== 'string' || plugins.net.isIP(valueArg) !== 4) throw new TypeError('WiZ requires an explicit local unicast IPv4 address.');
+  const parts = valueArg.split('.').map(Number);
+  const local = parts[0] === 10 || parts[0] === 127 || parts[0] === 172 && parts[1] >= 16 && parts[1] <= 31 ||
+    parts[0] === 192 && parts[1] === 168 || parts[0] === 169 && parts[1] === 254;
+  if (!local || parts[3] === 0 || parts[3] === 255) throw new TypeError('WiZ requires a private, link-local or loopback unicast IPv4 address.');
+  return valueArg;
+}
+
+export function wizInteger(valueArg: unknown, fallbackArg: number, minimumArg: number, maximumArg: number): number {
+  const value = valueArg === undefined ? fallbackArg : valueArg;
+  if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < minimumArg || value > maximumArg) {
+    throw new TypeError(`WiZ value must be an integer from ${minimumArg} through ${maximumArg}.`);
+  }
+  return value;
+}
+
+export function normalizeWizConfig(valueArg: unknown): Readonly<Required<Omit<IWizConfig, 'name'>> & Pick<IWizConfig, 'name'>> {
+  const value = wizRecord(valueArg, ['homeId', 'host', 'macAddress', 'port', 'name', 'timeoutMs', 'pollIntervalMs', 'maxPendingOperations', 'maxExchanges']);
+  const pollIntervalMs = wizInteger(value.pollIntervalMs, 30000, 0, 3600000);
+  if (pollIntervalMs > 0 && pollIntervalMs < 100) throw new TypeError('WiZ subscription polling must be disabled or at least 100 milliseconds.');
+  return Object.freeze({
+    homeId: wizText(value.homeId, 'homeId'), host: wizAddress(value.host), macAddress: wizMac(value.macAddress),
+    port: wizInteger(value.port, 38899, 1, 65535), ...(value.name === undefined ? {} : { name: wizText(value.name, 'name', 128) }),
+    timeoutMs: wizInteger(value.timeoutMs, 5000, 1, 60000), pollIntervalMs,
+    maxPendingOperations: wizInteger(value.maxPendingOperations, 16, 1, 128), maxExchanges: wizInteger(value.maxExchanges, 4096, 1, 16384),
+  });
+}
+
+export function wizControl(valueArg: unknown): TWizControl {
+  const value = wizRecord(valueArg, ['feature', 'value']);
+  if (value.feature === 'power' && typeof value.value === 'boolean') return Object.freeze({ feature: 'power', value: value.value });
+  if (value.feature === 'brightness') return Object.freeze({ feature: 'brightness', value: wizInteger(value.value, 0, 1, 100) });
+  if (value.feature === 'rgb') {
+    const rgb = wizRecord(value.value, ['red', 'green', 'blue']);
+    return Object.freeze({ feature: 'rgb', value: Object.freeze({ red: wizInteger(rgb.red, -1, 0, 255), green: wizInteger(rgb.green, -1, 0, 255), blue: wizInteger(rgb.blue, -1, 0, 255) }) });
+  }
+  throw new TypeError('WiZ supports one exact power, brightness or RGB control per operation.');
+}

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