@smarthome.exchange/integrations 0.2.0 → 2.0.0

package/ts/integrations/wiz/wiz.classes.integration.ts

@@ -1,80 +1,224 @@
-import type * as shxInterfaces from '@smarthome.exchange/interfaces';
+import * as plugins from '../../plugins.js';
 import { BaseIntegration } from '../../core/classes.baseintegration.js';
-import type { IIntegrationEntity, IIntegrationEvent, IIntegrationRuntime, IIntegrationSetupContext, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
+import { ConsoleLogger } from '../../core/classes.logger.js';
+import { NativeIntegrationOwner, type INativeSetupLease } from '../../core/classes.nativeintegrationowner.js';
+import type { IDeviceFeatureWriteRequest, ILogger, IIntegrationEntity, IIntegrationEvent, IIntegrationRuntime,
+  IIntegrationSetupContext, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
 import { WizClient } from './wiz.classes.client.js';
 import { WizConfigFlow } from './wiz.classes.configflow.js';
 import { createWizDiscoveryDescriptor } from './wiz.discovery.js';
 import { WizMapper } from './wiz.mapper.js';
-import type { IWizConfig } from './wiz.types.js';
+import type { IWizConfig, IWizSnapshot, IWizWriteResult, TWizControl } from './wiz.types.js';
+import { normalizeWizConfig } from './wiz.validation.js';
+
+export interface IWizIntegrationOptions {
+  readonly homeId?: string;
+  readonly capacity?: number;
+}
 
 export class WizIntegration extends BaseIntegration<IWizConfig> {
   public readonly domain = 'wiz';
   public readonly displayName = 'WiZ';
   public readonly status = 'control-runtime' as const;
   public readonly discoveryDescriptor = createWizDiscoveryDescriptor();
-  public readonly configFlow = new WizConfigFlow();
+  public readonly configFlow: WizConfigFlow;
   public readonly metadata = {
-    source: 'home-assistant/core',
-    upstreamPath: 'homeassistant/components/wiz',
-    upstreamDomain: 'wiz',
-    integrationType: 'device',
-    iotClass: 'local_push',
-    requirements: ['pywizlight==0.6.3'],
-    dependencies: ['network'],
-    afterDependencies: [] as string[],
-    codeowners: ['@sbidy', '@arturpragacz'],
-    documentation: 'https://www.home-assistant.io/integrations/wiz',
-    protocolDocumentation: 'https://docs.pro.wizconnected.com/#introduction',
-    dhcp: [
-      { registeredDevices: true },
-      { macaddress: 'A8BB50*' },
-      { macaddress: 'D8A011*' },
-      { macaddress: '444F8E*' },
-      { macaddress: '6C2990*' },
-      { hostname: 'wiz_*' },
-    ],
+    source: '@ecobridge.xyz/devicemanager', documentation: 'https://www.home-assistant.io/integrations/wiz',
+    integrationType: 'device', iotClass: 'local_polling', networkAuthenticated: false,
+    supportedControls: ['explicit power', 'observed brightness', 'observed RGB'],
   };
+  readonly #owner: NativeIntegrationOwner;
+
+  constructor(optionsArg: IWizIntegrationOptions = {}) {
+    super();
+    this.#owner = new NativeIntegrationOwner('wiz', optionsArg);
+    this.configFlow = new WizConfigFlow(this.#owner);
+  }
 
   public async setup(configArg: IWizConfig, contextArg: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
-    void contextArg;
-    return new WizRuntime(new WizClient(configArg));
+    const config = normalizeWizConfig(configArg);
+    return this.#owner.runSetup(contextArg, config.homeId, async (leaseArg) => {
+      const client = new WizClient(config, { ...leaseArg.context, abortSignal: leaseArg.signal });
+      let runtime: WizRuntime | undefined;
+      let cleanupAttempts = 0;
+      const closeClient = (): Promise<void> => cleanupAttempts++ === 0 ? client.destroy() : client.retryCleanup();
+      leaseArg.own(() => runtime ? runtime.cleanup() : closeClient());
+      const snapshot = await client.getSnapshot(leaseArg.signal);
+      leaseArg.assertOpen();
+      runtime = new WizRuntime(client, snapshot, leaseArg.context.logger, leaseArg, closeClient);
+      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(); }
 }
 
 export class HomeAssistantWizIntegration extends WizIntegration {}
 
+interface IWizSubscription {
+  handler(eventArg: IIntegrationEvent): void;
+  release(): void;
+}
+
 class WizRuntime implements IIntegrationRuntime {
-  public domain = 'wiz';
+  public readonly domain = 'wiz';
+  readonly #subscriptions = new Set<IWizSubscription>();
+  readonly #client: WizClient;
+  readonly #logger: ILogger;
+  readonly #lease: INativeSetupLease;
+  readonly #closeClient: () => Promise<void>;
+  readonly #ownerAbort = (): void => { this.markClosed(); };
+  #snapshot: IWizSnapshot;
+  #timer?: ReturnType<typeof setTimeout>;
+  #poll?: Promise<void>;
+  #pollController?: AbortController;
+  #closed = false;
 
-  constructor(private readonly client: WizClient) {}
+  constructor(clientArg: WizClient, snapshotArg: IWizSnapshot, loggerArg: ILogger | undefined, leaseArg: INativeSetupLease, closeClientArg: () => Promise<void>) {
+    this.#client = clientArg; this.#snapshot = snapshotArg; this.#logger = loggerArg ?? new ConsoleLogger();
+    this.#lease = leaseArg; this.#closeClient = closeClientArg;
+    leaseArg.signal.addEventListener('abort', this.#ownerAbort, { once: true });
+    if (leaseArg.signal.aborted) this.#ownerAbort();
+  }
 
-  public async devices(): Promise<shxInterfaces.data.IDeviceDefinition[]> {
-    return WizMapper.toDevices(await this.client.getSnapshot());
+  public isHealthy(): boolean { return !this.#closed && this.#client.isHealthy(); }
+  public async devices(signalArg?: AbortSignal): Promise<plugins.shxInterfaces.data.IDeviceDefinition[]> { return WizMapper.toDevices(await this.refresh(signalArg)); }
+  public async entities(): Promise<IIntegrationEntity[]> { return WizMapper.toEntities(await this.refresh()); }
+
+  public async subscribe(handlerArg: (eventArg: IIntegrationEvent) => void, signalArg?: AbortSignal): Promise<() => Promise<void>> {
+    if (this.#closed) throw new Error('WiZ runtime is destroyed.');
+    if (typeof handlerArg !== 'function') throw new TypeError('WiZ subscription requires a handler.');
+    signalArg?.throwIfAborted();
+    const subscription: IWizSubscription = {
+      handler: handlerArg,
+      release: () => {
+        this.#subscriptions.delete(subscription);
+        signalArg?.removeEventListener('abort', subscription.release);
+        if (!this.#subscriptions.size) this.stopPolling();
+      },
+    };
+    try {
+      const snapshot = await this.#client.getSnapshot(signalArg);
+      if (this.#closed) throw new Error('WiZ runtime is destroyed.');
+      signalArg?.throwIfAborted();
+      this.#snapshot = snapshot;
+      handlerArg(this.observation(snapshot));
+      if (this.#closed) throw new Error('WiZ runtime was destroyed during initial subscription delivery.');
+      signalArg?.throwIfAborted();
+      this.#subscriptions.add(subscription);
+      signalArg?.addEventListener('abort', subscription.release, { once: true });
+      if (signalArg?.aborted) subscription.release();
+      this.schedulePolling();
+    } catch (errorArg) { subscription.release(); throw errorArg; }
+    return async () => {
+      subscription.release();
+      if (!this.#subscriptions.size) await this.#poll;
+    };
   }
 
-  public async entities(): Promise<IIntegrationEntity[]> {
-    return WizMapper.toEntities(await this.client.getSnapshot());
+  public async callService(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
+    let control: TWizControl;
+    try { control = WizMapper.controlForService(this.#snapshot, requestArg); }
+    catch (errorArg) { return this.admissionFailure(errorArg); }
+    return this.write(control);
   }
 
-  public async subscribe(handlerArg: (eventArg: IIntegrationEvent) => void): Promise<() => Promise<void>> {
-    const unsubscribe = this.client.onEvent((eventArg) => handlerArg(WizMapper.toIntegrationEvent(eventArg)));
-    await this.client.getSnapshot();
-    return async () => unsubscribe();
+  public async writeFeature(requestArg: IDeviceFeatureWriteRequest, signalArg?: AbortSignal): Promise<IServiceCallResult> {
+    let control: TWizControl;
+    try { control = WizMapper.controlForFeature(this.#snapshot, requestArg); }
+    catch (errorArg) { return this.admissionFailure(errorArg); }
+    return this.write(control, signalArg);
   }
 
-  public async callService(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
-    const snapshot = await this.client.getSnapshot();
-    const command = WizMapper.commandForService(snapshot, requestArg);
-    if (!command) {
-      return { success: false, error: `WiZ service ${requestArg.domain}.${requestArg.service} has no native setPilot mapping for the target.` };
+  public destroy(): Promise<void> {
+    this.markClosed();
+    return this.#lease.close();
+  }
+
+  /** Called only by the owning lease, including explicit retained-cleanup retry. */
+  public async cleanup(): Promise<void> {
+    this.markClosed();
+    const results = await Promise.allSettled([Promise.resolve().then(this.#closeClient), this.#poll]);
+    const errors = results.flatMap((resultArg) => resultArg.status === 'rejected' ? [resultArg.reason] : []);
+    if (errors.length) throw new AggregateError(errors, 'WiZ runtime cleanup failed after draining polling.');
+  }
+
+  private markClosed(): void {
+    if (this.#closed) return;
+    this.#closed = true;
+    this.#lease.signal.removeEventListener('abort', this.#ownerAbort);
+    for (const subscription of [...this.#subscriptions]) subscription.release();
+    this.stopPolling();
+  }
+
+  private async refresh(signalArg?: AbortSignal): Promise<IWizSnapshot> {
+    if (this.#closed) throw new Error('WiZ runtime is destroyed.');
+    const snapshot = await this.#client.getSnapshot(signalArg);
+    if (this.#closed) throw new Error('WiZ runtime is destroyed.');
+    this.#snapshot = snapshot;
+    this.notify(this.observation(snapshot));
+    return snapshot;
+  }
+
+  private async write(controlArg: TWizControl, signalArg?: AbortSignal): Promise<IServiceCallResult> {
+    if (this.#closed) return this.admissionFailure(new Error('WiZ runtime is destroyed.'));
+    const data = await this.#client.write(controlArg, signalArg);
+    if (data.observedState && !this.#closed) {
+      this.#snapshot = Object.freeze({ ...this.#snapshot, observedAt: new Date().toISOString(),
+        info: Object.freeze({ ...this.#snapshot.info, observedState: data.observedState }) });
+      this.notify(this.observation(this.#snapshot));
     }
-    const result = await this.client.sendCommand(command);
-    return { success: result.success, error: result.error, data: result.data };
+    return this.writeResult(data);
+  }
+
+  private writeResult(dataArg: IWizWriteResult): IServiceCallResult {
+    return { success: dataArg.outcome === 'accepted' && dataArg.errorCode === undefined, data: dataArg,
+      error: dataArg.outcome === 'accepted' && dataArg.errorCode === undefined ? undefined : dataArg.outcome === 'accepted' ?
+        'WiZ firmware accepted the operation, but observed readback failed; do not replay it.' :
+        `WiZ operation outcome is ${dataArg.outcome}; automatic replay is prohibited.` };
+  }
+
+  private admissionFailure(errorArg: unknown): IServiceCallResult {
+    return { success: false, error: errorArg instanceof Error ? errorArg.message : 'WiZ admission failed.',
+      data: { outcome: 'not-sent', physicalStateConfirmed: false } };
+  }
+
+  private observation(snapshotArg: IWizSnapshot): IIntegrationEvent {
+    return { type: 'state_changed', integrationDomain: 'wiz', deviceId: WizMapper.deviceId(snapshotArg),
+      entityId: WizMapper.entityId(snapshotArg), timestamp: Date.parse(snapshotArg.observedAt),
+      data: { device: WizMapper.toDevices(snapshotArg)[0], entity: WizMapper.toEntities(snapshotArg)[0] } };
+  }
+
+  private notify(eventArg: IIntegrationEvent): void {
+    for (const subscription of [...this.#subscriptions]) {
+      try { subscription.handler(eventArg); }
+      catch { subscription.release(); this.#logger.log('error', 'WiZ subscription handler failed and was removed.'); }
+    }
+  }
+
+  private schedulePolling(): void {
+    if (this.#closed || this.#timer || this.#poll || !this.#subscriptions.size || !this.#client.pollIntervalMs) return;
+    this.#timer = setTimeout(() => {
+      this.#timer = undefined;
+      const controller = new AbortController();
+      this.#pollController = controller;
+      this.#poll = this.refresh(controller.signal).then(() => undefined).catch((errorArg: unknown) => {
+        if (controller.signal.aborted || this.#closed) return;
+        this.notify({ type: 'availability_changed', integrationDomain: 'wiz', deviceId: WizMapper.deviceId(this.#snapshot),
+          timestamp: Date.now(), data: { available: false } });
+        this.#logger.log('error', 'WiZ polling did not obtain an authoritative observation.');
+        if (errorArg instanceof plugins.ecobridgeDeviceManager.WizProtocolError && errorArg.code === 'EXCHANGE_LIMIT') void this.destroy();
+      }).finally(() => {
+        this.#poll = undefined; this.#pollController = undefined; this.schedulePolling();
+      });
+    }, this.#client.pollIntervalMs);
   }
 
-  public async destroy(): Promise<void> {
-    await this.client.destroy();
+  private stopPolling(): void {
+    if (this.#timer) clearTimeout(this.#timer);
+    this.#timer = undefined;
+    this.#pollController?.abort(new Error('WiZ subscription polling stopped.'));
   }
 }

package/ts/integrations/wiz/wiz.discovery.ts

@@ -1,314 +1,71 @@
 import { DiscoveryDescriptor } from '../../core/classes.discoverydescriptor.js';
-import type {
-  IDiscoveryCandidate,
-  IDiscoveryContext,
-  IDiscoveryMatch,
-  IDiscoveryMatcher,
-  IDiscoveryProbe,
-  IDiscoveryProbeResult,
-  IDiscoveryValidator,
-} from '../../core/types.js';
-import type { IWizManualEntry, IWizMdnsRecord, IWizUdpDiscoveryRecord, IWizUdpResponse } from './wiz.types.js';
-import { wizDefaultPort } from './wiz.types.js';
-
-const wizMacPrefixes = ['a8bb50', 'd8a011', '444f8e', '6c2990'];
-const wizUdpMethods = new Set(['getPilot', 'setPilot', 'syncPilot', 'syncSystemConfig', 'getSystemConfig', 'registration']);
-
-export class WizUdpDiscoveryProbe implements IDiscoveryProbe {
-  public id = 'wiz-udp-discovery-probe';
-  public source = 'custom' as const;
-  public description = 'Discover WiZ devices by UDP registration broadcast on port 38899.';
-
-  public async probe(contextArg: IDiscoveryContext): Promise<IDiscoveryProbeResult> {
-    if (contextArg.abortSignal?.aborted) {
-      return { candidates: [] };
-    }
-    return { candidates: await this.discover(1200) };
-  }
-
-  private async discover(timeoutMsArg: number): Promise<IDiscoveryCandidate[]> {
-    const { createSocket } = await import('node:dgram');
-    const message = Buffer.from(JSON.stringify({
-      method: 'registration',
-      params: {
-        phoneMac: 'AAAAAAAAAAAA',
-        register: false,
-        phoneIp: '1.2.3.4',
-        id: '1',
+import type { IDiscoveryCandidate, IDiscoveryMatch, IDiscoveryMatcher, IDiscoveryValidator } from '../../core/types.js';
+import type { IWizManualEntry, IWizMdnsRecord, IWizUdpDiscoveryRecord } from './wiz.types.js';
+import { wizAddress, wizInteger, wizMac, wizRecord, wizText } from './wiz.validation.js';
+
+function hint(hostArg: unknown, macArg: unknown, portArg: unknown, nameArg: unknown, sourceArg: IDiscoveryCandidate['source']): IDiscoveryMatch {
+  try {
+    const host = wizAddress(hostArg);
+    const macAddress = wizMac(macArg);
+    return {
+      matched: true, confidence: 'medium', reason: 'Selected WiZ endpoint and MAC are unauthenticated setup hints; live admission is required.',
+      normalizedDeviceId: macAddress, candidate: {
+        source: sourceArg, integrationDomain: 'wiz', id: macAddress, host, macAddress,
+        port: wizInteger(portArg, 38899, 1, 65535), name: nameArg === undefined ? 'WiZ' : wizText(nameArg, 'name', 128),
+        manufacturer: 'WiZ', metadata: { authenticated: false },
       },
-    }));
-    const matcher = new WizUdpMatcher();
-    const candidates: IDiscoveryCandidate[] = [];
-
-    return new Promise((resolve) => {
-      const socket = createSocket({ type: 'udp4', reuseAddr: true });
-      const timer = setTimeout(() => {
-        try {
-          socket.close();
-        } catch {
-          // The discovery socket may already be closed after an OS error.
-        }
-        resolve(candidates);
-      }, timeoutMsArg);
-
-      socket.on('message', async (dataArg, remoteArg) => {
-        let response: IWizUdpResponse<Record<string, unknown>> | undefined;
-        try {
-          response = JSON.parse(dataArg.toString('utf8')) as IWizUdpResponse<Record<string, unknown>>;
-        } catch {
-          return;
-        }
-        const match = await matcher.matches({ host: remoteArg.address, port: remoteArg.port, response });
-        if (match.matched && match.candidate && !candidates.some((candidateArg) => candidateArg.id === match.candidate?.id || candidateArg.host === match.candidate?.host)) {
-          candidates.push(match.candidate);
-        }
-      });
-      socket.on('error', () => {
-        clearTimeout(timer);
-        try {
-          socket.close();
-        } catch {
-          // Ignore discovery socket close races.
-        }
-        resolve(candidates);
-      });
-      socket.bind(() => {
-        socket.setBroadcast(true);
-        socket.send(message, wizDefaultPort, '255.255.255.255');
-        setTimeout(() => socket.send(message, wizDefaultPort, '255.255.255.255'), 500);
-      });
-    });
-  }
+    };
+  } catch { return { matched: false, confidence: 'low', reason: 'WiZ hints require an explicit local IPv4 endpoint and unicast MAC.' }; }
 }
 
 export class WizMdnsMatcher implements IDiscoveryMatcher<IWizMdnsRecord> {
-  public id = 'wiz-mdns-match';
-  public source = 'mdns' as const;
-  public description = 'Recognize WiZ mDNS or hostname advertisements.';
-
+  public readonly id = 'wiz-mdns-match';
+  public readonly source = 'mdns' as const;
   public async matches(recordArg: IWizMdnsRecord): Promise<IDiscoveryMatch> {
-    const txt = recordArg.txt || recordArg.properties || {};
-    const type = this.normalizeType(recordArg.type);
-    const host = recordArg.host || recordArg.hostname || recordArg.addresses?.[0];
-    const mac = this.normalizeMac(this.txt(txt, 'mac') || this.txt(txt, 'macaddress') || this.txt(txt, 'mac_address'));
-    const name = this.name(recordArg, txt);
-    const text = [type, recordArg.name, recordArg.hostname, host, name, this.txt(txt, 'manufacturer'), this.txt(txt, 'model')]
-      .filter((valueArg): valueArg is string => typeof valueArg === 'string')
-      .join(' ')
-      .toLowerCase();
-    const matched = Boolean(mac && this.isWizMac(mac)) || /(^|[._-])wiz([._-]|$)/i.test(text) || text.includes('wizconnected');
-    if (!matched) {
-      return { matched: false, confidence: 'low', reason: 'mDNS record is not a WiZ advertisement.' };
-    }
-    return {
-      matched: true,
-      confidence: mac ? 'certain' : host ? 'high' : 'medium',
-      reason: mac ? 'mDNS record contains a WiZ MAC address.' : 'mDNS record contains WiZ hostname or TXT metadata.',
-      normalizedDeviceId: mac || recordArg.name || host,
-      candidate: {
-        source: 'mdns',
-        integrationDomain: 'wiz',
-        id: mac || recordArg.name || host,
-        host,
-        port: recordArg.port || wizDefaultPort,
-        name: name || 'WiZ',
-        manufacturer: 'WiZ',
-        model: this.txt(txt, 'model') || this.txt(txt, 'moduleName') || 'WiZ device',
-        macAddress: mac,
-        metadata: {
-          mdnsName: recordArg.name,
-          mdnsType: recordArg.type,
-          txt,
-        },
-      },
-    };
-  }
-
-  private txt(txtArg: Record<string, string | undefined>, keyArg: string): string | undefined {
-    return txtArg[keyArg] || txtArg[keyArg.toUpperCase()];
-  }
-
-  private name(recordArg: IWizMdnsRecord, txtArg: Record<string, string | undefined>): string | undefined {
-    return this.txt(txtArg, 'name') || this.txt(txtArg, 'friendly_name') || recordArg.name?.split('._', 1)[0] || recordArg.hostname?.replace(/\.local\.?$/i, '');
-  }
-
-  private normalizeType(valueArg?: string): string {
-    return (valueArg || '').toLowerCase().replace(/\.$/, '');
-  }
-
-  private normalizeMac(valueArg?: string): string | undefined {
-    if (!valueArg) {
-      return undefined;
-    }
-    const compact = valueArg.replace(/[^a-fA-F0-9]/g, '').toLowerCase();
-    return compact.length === 12 ? compact.match(/.{1,2}/g)?.join(':') : valueArg.toLowerCase();
-  }
-
-  private isWizMac(valueArg: string): boolean {
-    const compact = valueArg.replace(/[^a-fA-F0-9]/g, '').toLowerCase();
-    return wizMacPrefixes.some((prefixArg) => compact.startsWith(prefixArg));
+    try {
+      const value = wizRecord(recordArg, ['type', 'name', 'host', 'hostname', 'addresses', 'port', 'txt', 'properties']);
+      const txt = wizRecord(value.txt ?? value.properties ?? {});
+      return hint(value.host, txt.mac ?? txt.macaddress ?? txt.mac_address, value.port, value.name, 'mdns');
+    } catch { return { matched: false, confidence: 'low', reason: 'Malformed WiZ mDNS hint.' }; }
   }
 }
 
 export class WizUdpMatcher implements IDiscoveryMatcher<IWizUdpDiscoveryRecord> {
-  public id = 'wiz-udp-match';
-  public source = 'custom' as const;
-  public description = 'Recognize WiZ UDP JSON discovery responses.';
-
+  public readonly id = 'wiz-udp-match';
+  public readonly source = 'custom' as const;
   public async matches(recordArg: IWizUdpDiscoveryRecord): Promise<IDiscoveryMatch> {
-    const response = recordArg.response;
-    const result = response?.result || recordArg.result || {};
-    const method = response?.method || recordArg.method;
-    const host = recordArg.host || recordArg.address || recordArg.ip || recordArg.ip_address;
-    const mac = this.normalizeMac(recordArg.mac || recordArg.mac_address || this.stringValue(result.mac));
-    const matched = Boolean(mac) || Boolean(method && wizUdpMethods.has(method)) || recordArg.metadata?.wiz === true;
-    if (!matched) {
-      return { matched: false, confidence: 'low', reason: 'UDP record is not a WiZ JSON response.' };
-    }
-    return {
-      matched: true,
-      confidence: mac && host ? 'certain' : mac || host ? 'high' : 'medium',
-      reason: mac ? 'UDP response contains a WiZ MAC address.' : 'UDP response method matches WiZ JSON protocol.',
-      normalizedDeviceId: mac || recordArg.name || host,
-      candidate: {
-        source: 'custom',
-        integrationDomain: 'wiz',
-        id: mac || recordArg.name || host,
-        host,
-        port: recordArg.port || wizDefaultPort,
-        name: recordArg.name || (mac ? `WiZ ${this.shortMac(mac)}` : 'WiZ'),
-        manufacturer: 'WiZ',
-        model: 'WiZ UDP JSON device',
-        macAddress: mac,
-        metadata: {
-          ...recordArg.metadata,
-          discoveryProtocol: 'udp',
-          method,
-          result,
-        },
-      },
-    };
-  }
-
-  private stringValue(valueArg: unknown): string | undefined {
-    return typeof valueArg === 'string' && valueArg.trim() ? valueArg.trim() : undefined;
-  }
-
-  private shortMac(valueArg?: string): string {
-    return (valueArg || '').replace(/[^a-fA-F0-9]/g, '').slice(-6).toUpperCase();
-  }
-
-  private normalizeMac(valueArg?: string): string | undefined {
-    if (!valueArg) {
-      return undefined;
-    }
-    const compact = valueArg.replace(/[^a-fA-F0-9]/g, '').toLowerCase();
-    return compact.length === 12 ? compact.match(/.{1,2}/g)?.join(':') : valueArg.toLowerCase();
+    try {
+      const value = wizRecord(recordArg, ['host', 'port', 'method', 'result', 'response']);
+      const response = value.response === undefined ? value : wizRecord(value.response, ['method', 'result']);
+      if (typeof response.method !== 'string' || !['getPilot', 'getSystemConfig', 'registration'].includes(response.method)) throw new TypeError('Unsupported WiZ hint method.');
+      const result = wizRecord(response.result);
+      return hint(value.host, result.mac, value.port, undefined, 'custom');
+    } catch { return { matched: false, confidence: 'low', reason: 'Malformed WiZ UDP hint.' }; }
   }
 }
 
 export class WizManualMatcher implements IDiscoveryMatcher<IWizManualEntry> {
-  public id = 'wiz-manual-match';
-  public source = 'manual' as const;
-  public description = 'Recognize manual WiZ setup entries.';
-
-  public async matches(inputArg: IWizManualEntry): Promise<IDiscoveryMatch> {
-    const mac = this.normalizeMac(inputArg.mac || inputArg.macAddress || inputArg.deviceInfo?.mac);
-    const text = [inputArg.name, inputArg.manufacturer, inputArg.model, inputArg.deviceInfo?.manufacturer, inputArg.deviceInfo?.model, inputArg.deviceInfo?.moduleName]
-      .filter((valueArg): valueArg is string => typeof valueArg === 'string')
-      .join(' ')
-      .toLowerCase();
-    const matched = Boolean(inputArg.host || mac || inputArg.metadata?.wiz || text.includes('wiz'));
-    if (!matched) {
-      return { matched: false, confidence: 'low', reason: 'Manual entry does not contain WiZ setup hints.' };
-    }
-    return {
-      matched: true,
-      confidence: inputArg.host && mac ? 'certain' : inputArg.host || mac ? 'high' : 'medium',
-      reason: 'Manual entry can start WiZ setup.',
-      normalizedDeviceId: mac || inputArg.id || inputArg.host,
-      candidate: {
-        source: 'manual',
-        integrationDomain: 'wiz',
-        id: inputArg.id || mac || inputArg.host,
-        host: inputArg.host,
-        port: inputArg.port || wizDefaultPort,
-        name: inputArg.name || inputArg.deviceInfo?.name || (mac ? `WiZ ${this.shortMac(mac)}` : 'WiZ'),
-        manufacturer: inputArg.manufacturer || inputArg.deviceInfo?.manufacturer || 'WiZ',
-        model: inputArg.model || inputArg.deviceInfo?.model || inputArg.deviceInfo?.moduleName || 'WiZ device',
-        macAddress: mac,
-        metadata: {
-          ...inputArg.metadata,
-          discoveryProtocol: 'manual',
-          deviceInfo: inputArg.deviceInfo,
-          pilot: inputArg.pilot,
-          snapshot: inputArg.snapshot,
-        },
-      },
-    };
-  }
-
-  private shortMac(valueArg?: string): string {
-    return (valueArg || '').replace(/[^a-fA-F0-9]/g, '').slice(-6).toUpperCase();
-  }
-
-  private normalizeMac(valueArg?: string): string | undefined {
-    if (!valueArg) {
-      return undefined;
-    }
-    const compact = valueArg.replace(/[^a-fA-F0-9]/g, '').toLowerCase();
-    return compact.length === 12 ? compact.match(/.{1,2}/g)?.join(':') : valueArg.toLowerCase();
+  public readonly id = 'wiz-manual-match';
+  public readonly source = 'manual' as const;
+  public async matches(recordArg: IWizManualEntry): Promise<IDiscoveryMatch> {
+    try {
+      const value = wizRecord(recordArg, ['host', 'port', 'macAddress', 'name']);
+      return hint(value.host, value.macAddress, value.port, value.name, 'manual');
+    } catch { return { matched: false, confidence: 'low', reason: 'Malformed WiZ manual hint.' }; }
   }
 }
 
 export class WizCandidateValidator implements IDiscoveryValidator {
-  public id = 'wiz-candidate-validator';
-  public description = 'Validate WiZ candidates from mDNS, UDP, DHCP, and manual setup.';
-
+  public readonly id = 'wiz-candidate-validator';
   public async validate(candidateArg: IDiscoveryCandidate): Promise<IDiscoveryMatch> {
-    const metadata = candidateArg.metadata || {};
-    const mac = this.normalizeMac(candidateArg.macAddress);
-    const compactMac = (mac || '').replace(/[^a-fA-F0-9]/g, '').toLowerCase();
-    const name = (candidateArg.name || '').toLowerCase();
-    const model = (candidateArg.model || '').toLowerCase();
-    const manufacturer = (candidateArg.manufacturer || '').toLowerCase();
-    const mdnsType = typeof metadata.mdnsType === 'string' ? metadata.mdnsType.toLowerCase() : '';
-    const discoveryProtocol = typeof metadata.discoveryProtocol === 'string' ? metadata.discoveryProtocol : undefined;
-    const macMatched = wizMacPrefixes.some((prefixArg) => compactMac.startsWith(prefixArg));
-    const hostMatched = Boolean(candidateArg.host && /^wiz[_-]/i.test(candidateArg.host));
-    const textMatched = name.includes('wiz') || model.includes('wiz') || manufacturer.includes('wiz') || mdnsType.includes('wiz');
-    const matched = candidateArg.integrationDomain === 'wiz'
-      || macMatched
-      || hostMatched
-      || textMatched
-      || candidateArg.port === wizDefaultPort
-      || metadata.wiz === true
-      || discoveryProtocol === 'udp'
-      || discoveryProtocol === 'manual';
-    return {
-      matched,
-      confidence: matched && (candidateArg.integrationDomain === 'wiz' || macMatched) && candidateArg.host ? 'certain' : matched && candidateArg.host ? 'high' : matched ? 'medium' : 'low',
-      reason: matched ? 'Candidate has WiZ metadata or local UDP port information.' : 'Candidate is not WiZ.',
-      candidate: matched ? candidateArg : undefined,
-      normalizedDeviceId: mac || candidateArg.id || candidateArg.host,
-      metadata: matched ? { macMatched, hostMatched, discoveryProtocol } : undefined,
-    };
-  }
-
-  private normalizeMac(valueArg?: string): string | undefined {
-    if (!valueArg) {
-      return undefined;
-    }
-    const compact = valueArg.replace(/[^a-fA-F0-9]/g, '').toLowerCase();
-    return compact.length === 12 ? compact.match(/.{1,2}/g)?.join(':') : valueArg.toLowerCase();
+    try {
+      const candidate = wizRecord(candidateArg);
+      if (candidate.integrationDomain !== undefined && candidate.integrationDomain !== 'wiz') return { matched: false, confidence: 'low', reason: 'Candidate belongs to another integration.' };
+      return hint(candidate.host, candidate.macAddress, candidate.port, candidate.name, candidateArg.source);
+    } catch { return { matched: false, confidence: 'low', reason: 'Malformed WiZ candidate.' }; }
   }
 }
 
-export const createWizDiscoveryDescriptor = (): DiscoveryDescriptor => {
-  return new DiscoveryDescriptor({ integrationDomain: 'wiz', displayName: 'WiZ' })
-    .addProbe(new WizUdpDiscoveryProbe())
-    .addMatcher(new WizMdnsMatcher())
-    .addMatcher(new WizUdpMatcher())
-    .addMatcher(new WizManualMatcher())
-    .addValidator(new WizCandidateValidator());
-};
+/** Discovery consumes supplied advertisements only; it never broadcasts or provisions devices. */
+export const createWizDiscoveryDescriptor = (): DiscoveryDescriptor => new DiscoveryDescriptor({ integrationDomain: 'wiz', displayName: 'WiZ' })
+  .addMatcher(new WizMdnsMatcher()).addMatcher(new WizUdpMatcher()).addMatcher(new WizManualMatcher()).addValidator(new WizCandidateValidator());