@smarthome.exchange/integrations 1.0.0 → 3.0.0

package/ts/integrations/modbus/modbus.classes.configflow.ts

@@ -1,52 +1,81 @@
-import type { IConfigFlow, IConfigFlowContext, IConfigFlowStep, IDiscoveryCandidate } from '../../core/types.js';
-import type { IModbusConfig } from './modbus.types.js';
-
-const defaultModbusTcpPort = 502;
+import { NativeIntegrationOwner, type NativeIntegrationScope } from '../../core/classes.nativeintegrationowner.js';
+import type { IConfigFlow, IConfigFlowStep, IDiscoveryCandidate, INativeConfigFlowContext } from '../../core/types.js';
+import { ModbusClient } from './modbus.classes.client.js';
+import { ModbusMapper } from './modbus.mapper.js';
+import type { IModbusConfig, IModbusIntegrationOptions } from './modbus.types.js';
+import { modbusRecord, normalizeModbusConfig } from './modbus.validation.js';
 
 export class ModbusConfigFlow implements IConfigFlow<IModbusConfig> {
-  public async start(candidateArg: IDiscoveryCandidate, contextArg: IConfigFlowContext): Promise<IConfigFlowStep<IModbusConfig>> {
-    void contextArg;
+  readonly #scope: NativeIntegrationScope;
+
+  constructor(optionsArg: IModbusIntegrationOptions = {}, scopeArg?: NativeIntegrationScope) {
+    this.#scope = scopeArg ?? new NativeIntegrationOwner('modbus', optionsArg).createFlowScope();
+  }
+
+  public async start(candidateArg: IDiscoveryCandidate, contextArg: INativeConfigFlowContext): Promise<IConfigFlowStep<IModbusConfig>> {
+    const candidate = modbusRecord(candidateArg);
+    if (candidate.source !== 'manual' || candidate.integrationDomain !== undefined && candidate.integrationDomain !== 'modbus') {
+      throw new TypeError('Modbus config admission accepts explicit manual candidates only.');
+    }
+    const metadata = candidate.metadata === undefined ? {} : modbusRecord(candidate.metadata);
+    const context = this.#scope.admit(contextArg);
     return {
-      kind: 'form',
-      title: 'Connect Modbus TCP hub',
-      description: 'Configure a known Modbus TCP endpoint. Serial RTU ports are intentionally not guessed or probed.',
+      kind: 'form', title: 'Select Modbus TCP device',
+      description: 'Select the private IPv4 endpoint, unit, vendor and product for the host-selected home. Supply an explicit JSON array of zero-based raw read mappings; writes require single-address permission. Identity strings are unauthenticated LAN observations.',
       fields: [
-        { name: 'name', label: 'Hub name', type: 'text', required: false },
-        { name: 'host', label: 'Host', type: 'text', required: true },
-        { name: 'port', label: 'TCP port', type: 'number', required: false },
-        { name: 'unitId', label: 'Default unit ID', type: 'number', required: false },
-        { name: 'timeoutMs', label: 'Timeout milliseconds', type: 'number', required: false },
+        { name: 'address', label: 'Selected local IPv4 address', type: 'text', required: true },
+        { name: 'port', label: 'TCP port', type: 'number' },
+        { name: 'unitId', label: 'Selected unit ID', type: 'number', required: true },
+        { name: 'expectedVendorName', label: 'Exact vendor name', type: 'text', required: true },
+        { name: 'expectedProductCode', label: 'Exact product code', type: 'text', required: true },
+        { name: 'expectedRevision', label: 'Optional exact revision', type: 'text' },
+        { name: 'allowUnencryptedLan', label: 'Accept unencrypted LAN transport', type: 'boolean', required: true },
+        { name: 'mappings', label: 'Owner raw mappings JSON', type: 'text', required: true },
+        { name: 'name', label: 'Display name', type: 'text' },
       ],
-      submit: async (valuesArg) => {
-        const unitId = this.numberValue(valuesArg.unitId) || this.numberValue(candidateArg.metadata?.unitId) || 1;
-        const port = this.numberValue(valuesArg.port) || candidateArg.port || defaultModbusTcpPort;
-        return {
-          kind: 'done',
-          title: 'Modbus TCP hub configured',
-          config: {
-            hubs: [{
-              id: candidateArg.id,
-              name: this.stringValue(valuesArg.name) || candidateArg.name || 'modbus_hub',
-              type: 'tcp',
-              host: this.stringValue(valuesArg.host) || candidateArg.host || '',
-              port,
-              timeoutMs: this.numberValue(valuesArg.timeoutMs) || 5000,
-              slave: unitId,
-              manufacturer: candidateArg.manufacturer,
-              model: candidateArg.model,
-              serialNumber: candidateArg.serialNumber,
-            }],
-          },
-        };
-      },
+      submit: (valuesArg) => this.submit(valuesArg, candidate, metadata, context),
     };
   }
 
-  private stringValue(valueArg: unknown): string | undefined {
-    return typeof valueArg === 'string' && valueArg.trim() ? valueArg.trim() : undefined;
-  }
+  public destroy(): Promise<void> { return this.#scope.close(); }
+  public retryCleanup(): Promise<void> { return this.#scope.retryCleanup(); }
 
-  private numberValue(valueArg: unknown): number | undefined {
-    return typeof valueArg === 'number' && Number.isFinite(valueArg) ? valueArg : typeof valueArg === 'string' && valueArg.trim() && Number.isFinite(Number(valueArg)) ? Number(valueArg) : undefined;
+  private async submit(valuesArg: Record<string, unknown>, candidateArg: Record<string, unknown>, metadataArg: Record<string, unknown>,
+    contextArg: INativeConfigFlowContext): Promise<IConfigFlowStep<IModbusConfig>> {
+    try {
+      const values = modbusRecord(valuesArg, ['homeId', 'address', 'port', 'unitId', 'expectedVendorName', 'expectedProductCode', 'expectedRevision',
+        'allowUnencryptedLan', 'mappings', 'name', 'localAddress', 'timeoutMs', 'maxQueuedOperations']);
+      if (values.homeId !== undefined && values.homeId !== contextArg.homeId) throw new Error('Modbus submitted home conflicts with the host-selected home.');
+      let mappings: unknown = values.mappings;
+      if (typeof mappings === 'string') {
+        if (mappings.length > 32768) throw new TypeError('Modbus mapping JSON exceeds its size bound.');
+        mappings = JSON.parse(mappings);
+      }
+      const config = normalizeModbusConfig({ ...values, homeId: contextArg.homeId, mappings,
+        address: values.address === undefined ? candidateArg.host : values.address,
+        port: values.port === undefined ? candidateArg.port : values.port,
+        unitId: values.unitId === undefined ? metadataArg.unitId : values.unitId,
+        expectedVendorName: values.expectedVendorName === undefined ? metadataArg.expectedVendorName : values.expectedVendorName,
+        expectedProductCode: values.expectedProductCode === undefined ? metadataArg.expectedProductCode : values.expectedProductCode,
+        expectedRevision: values.expectedRevision === undefined ? metadataArg.expectedRevision : values.expectedRevision });
+      return await this.#scope.run(contextArg, config.homeId, async (leaseArg) => {
+        const client = new ModbusClient(config, leaseArg.signal);
+        let cleanupAttempted = false;
+        leaseArg.own(() => {
+          if (cleanupAttempted) return client.retryCleanup();
+          cleanupAttempted = true;
+          return client.destroy();
+        });
+        await client.getSnapshot(leaseArg.signal);
+        leaseArg.assertOpen();
+        await client.destroy();
+        leaseArg.assertOpen();
+        if (leaseArg.context.configStore) await leaseArg.context.configStore.set(`device:${ModbusMapper.deviceId(config)}`, config);
+        leaseArg.assertOpen();
+        return { kind: 'done', title: 'Selected Modbus device and read mappings verified', config };
+      });
+    } catch (errorArg) {
+      return { kind: 'error', title: 'Modbus admission failed', error: errorArg instanceof Error ? errorArg.message : 'Modbus admission failed.' };
+    }
   }
 }

package/ts/integrations/modbus/modbus.classes.integration.ts

@@ -1,96 +1,151 @@
-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 { NativeIntegrationOwner, type INativeSetupLease } from '../../core/classes.nativeintegrationowner.js';
+import type { IDeviceFeatureWriteRequest, IIntegrationEntity, IIntegrationEvent, IIntegrationRuntime, INativeIntegrationSetupContext, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
 import { ModbusClient } from './modbus.classes.client.js';
 import { ModbusConfigFlow } from './modbus.classes.configflow.js';
 import { createModbusDiscoveryDescriptor } from './modbus.discovery.js';
 import { ModbusMapper } from './modbus.mapper.js';
-import type { IModbusConfig } from './modbus.types.js';
+import type { IModbusConfig, IModbusIntegrationOptions, IModbusSnapshot, TModbusCommand } from './modbus.types.js';
+import { normalizeModbusConfig } from './modbus.validation.js';
 
 export class ModbusIntegration extends BaseIntegration<IModbusConfig> {
   public readonly domain = 'modbus';
   public readonly displayName = 'Modbus';
   public readonly status = 'control-runtime' as const;
   public readonly discoveryDescriptor = createModbusDiscoveryDescriptor();
-  public readonly configFlow = new ModbusConfigFlow();
+  public readonly configFlow: ModbusConfigFlow;
   public readonly metadata = {
-    source: 'home-assistant/core',
-    upstreamPath: 'homeassistant/components/modbus',
-    upstreamDomain: 'modbus',
-    iotClass: 'local_polling',
-    requirements: ['pymodbus==3.11.2'],
-    dependencies: [],
-    afterDependencies: [],
-    codeowners: [],
-    documentation: 'https://www.home-assistant.io/integrations/modbus',
-    configFlow: true,
-    discovery: {
-      manual: true,
-      tcp: true,
-      serial: false,
-      note: 'Manual Modbus TCP setup is implemented. Serial RTU ports are not guessed or probed.',
-    },
-    runtime: {
-      type: 'control-runtime',
-      polling: 'local snapshot or explicit Modbus TCP requests',
-      services: ['read_coil', 'read_register', 'write_coil', 'write_register', 'stop', 'restart', 'refresh'],
-    },
+    source: 'native', upstreamDomain: 'modbus',
+    runtime: { type: 'control-runtime', polling: 'explicit owner reads', services: ['read', 'write_coil', 'write_register'] },
     localApi: {
-      implemented: [
-        'manual Modbus TCP hub configuration',
-        'snapshot/manual configured registers and coils',
-        'Modbus TCP MBAP request shape for read coils, read discrete inputs, read holding/input registers, write coil(s), and write register(s)',
-        'register/coils mapping to sensor, binary_sensor, switch, and number entities',
-      ],
-      explicitUnsupported: [
-        'unsafe serial RTU discovery or serial port guessing',
-        'serial RTU runtime transport',
-        'RTU-over-TCP framer runtime transport',
-        'UDP runtime transport',
-        'climate, cover, fan, and light platform behavior beyond configured register/coil entities',
-      ],
+      implemented: ['selected home/IPv4/unit/vendor/product', 'fresh basic identity on every operation', 'explicit raw bit/register read mappings',
+        'default-deny single absolute FC5/6 writes', 'bounded devicemanager admission and terminal cleanup'],
+      explicitUnsupported: ['automatic discovery', 'serial RTU', 'UDP', 'RTU-over-TCP', 'register-map inference', 'scaling or semantic device capabilities',
+        'multi-address writes', 'toggles', 'automatic retries or replay', 'cryptographic device authentication', 'physical effect confirmation'],
     },
   };
+  readonly #owner: NativeIntegrationOwner;
 
-  public async setup(configArg: IModbusConfig, contextArg: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
-    void contextArg;
-    return new ModbusRuntime(new ModbusClient(configArg));
+  constructor(optionsArg: IModbusIntegrationOptions = {}) {
+    super();
+    this.#owner = new NativeIntegrationOwner(this.domain, optionsArg);
+    this.configFlow = new ModbusConfigFlow({}, this.#owner.createFlowScope());
   }
 
-  public async destroy(): Promise<void> {}
+  public setup(configArg: IModbusConfig, contextArg: INativeIntegrationSetupContext): Promise<IIntegrationRuntime> {
+    try {
+      const config = normalizeModbusConfig(configArg);
+      return this.#owner.runSetup(contextArg, config.homeId, async (leaseArg) => {
+        const client = new ModbusClient(config, leaseArg.signal);
+        let cleanupAttempted = false;
+        leaseArg.own(() => {
+          if (cleanupAttempted) return client.retryCleanup();
+          cleanupAttempted = true;
+          return client.destroy();
+        });
+        const snapshot = await client.getSnapshot(leaseArg.signal);
+        leaseArg.assertOpen();
+        const runtime = new ModbusRuntime(client, snapshot, leaseArg);
+        leaseArg.promoteToRuntime();
+        return runtime;
+      });
+    } catch (errorArg) { return Promise.reject(errorArg); }
+  }
+
+  public destroy(): Promise<void> { return this.#owner.close(); }
+  public retryCleanup(): Promise<void> { return this.#owner.retryCleanup(); }
 }
 
 export class HomeAssistantModbusIntegration extends ModbusIntegration {}
 
 class ModbusRuntime implements IIntegrationRuntime {
-  public domain = 'modbus';
-
-  constructor(private readonly client: ModbusClient) {}
+  public readonly domain = 'modbus';
+  readonly #subscriptions = new Set<{ handler: (event: IIntegrationEvent) => void; release: () => void }>();
+  readonly #ownerAbort = (): void => { void this.destroy().then(() => undefined, () => undefined); };
+  #closed = false;
+  #closing?: Promise<void>;
 
-  public async devices(): Promise<shxInterfaces.data.IDeviceDefinition[]> {
-    return ModbusMapper.toDevices(await this.client.getSnapshot());
+  constructor(private readonly client: ModbusClient, private snapshot: IModbusSnapshot, private readonly lease: INativeSetupLease) {
+    lease.signal.addEventListener('abort', this.#ownerAbort, { once: true });
+    if (lease.signal.aborted) this.#ownerAbort();
   }
+  public isHealthy(): boolean { return !this.#closed && this.client.isHealthy(); }
 
-  public async entities(): Promise<IIntegrationEntity[]> {
-    return ModbusMapper.toEntities(await this.client.getSnapshot());
+  public async devices(signalArg?: AbortSignal): Promise<plugins.shxInterfaces.data.IDeviceDefinition[]> {
+    return ModbusMapper.toDevices(await this.refresh(signalArg));
   }
 
-  public async subscribe(handlerArg: (eventArg: IIntegrationEvent) => void): Promise<() => Promise<void>> {
-    const unsubscribe = this.client.onEvent((eventArg) => handlerArg(ModbusMapper.toIntegrationEvent(eventArg)));
-    return async () => unsubscribe();
+  public async entities(): Promise<IIntegrationEntity[]> { return ModbusMapper.toEntities(await this.refresh()); }
+
+  /** Passive observations only: subscribing never starts reads or a polling timer. */
+  public async subscribe(handlerArg: (eventArg: IIntegrationEvent) => void, signalArg?: AbortSignal): Promise<() => Promise<void>> {
+    this.assertOpen();
+    if (typeof handlerArg !== 'function') throw new TypeError('Modbus subscription handler must be a function.');
+    if (signalArg !== undefined && !(signalArg instanceof AbortSignal)) throw new TypeError('Modbus subscription signal must be an AbortSignal.');
+    signalArg?.throwIfAborted();
+    const entry = { handler: handlerArg, release: (): void => { this.#subscriptions.delete(entry); signalArg?.removeEventListener('abort', entry.release); } };
+    this.#subscriptions.add(entry);
+    signalArg?.addEventListener('abort', entry.release, { once: true });
+    if (signalArg?.aborted) entry.release();
+    return async () => entry.release();
   }
 
   public async callService(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
-    const snapshot = await this.client.getSnapshot();
-    const command = ModbusMapper.commandForService(snapshot, requestArg);
-    if (!command) {
-      return { success: false, error: `Unsupported Modbus service: ${requestArg.domain}.${requestArg.service}` };
+    try { this.assertOpen(); return await this.execute(ModbusMapper.commandForService(this.client.config, requestArg)); }
+    catch (errorArg) { return this.failure(errorArg); }
+  }
+
+  public async writeFeature(requestArg: IDeviceFeatureWriteRequest, signalArg?: AbortSignal): Promise<IServiceCallResult> {
+    try { this.assertOpen(); return await this.execute(ModbusMapper.commandForFeature(this.client.config, requestArg), signalArg); }
+    catch (errorArg) { return this.failure(errorArg); }
+  }
+
+  public destroy(): Promise<void> {
+    if (this.#closing) return this.#closing;
+    this.#closed = true;
+    this.#closing = Promise.resolve().then(() => this.lease.close());
+    this.lease.signal.removeEventListener('abort', this.#ownerAbort);
+    for (const entry of [...this.#subscriptions]) entry.release();
+    return this.#closing;
+  }
+
+  private async refresh(signalArg?: AbortSignal): Promise<IModbusSnapshot> {
+    this.assertOpen();
+    const snapshot = await this.client.getSnapshot(signalArg);
+    this.assertOpen();
+    this.snapshot = snapshot;
+    for (const entity of ModbusMapper.toEntities(snapshot)) this.notify({ type: 'state_changed', integrationDomain: 'modbus',
+      deviceId: entity.deviceId, entityId: entity.id, timestamp: Date.parse(snapshot.observedAt), data: { entity } });
+    return snapshot;
+  }
+
+  private async execute(commandArg: TModbusCommand, signalArg?: AbortSignal): Promise<IServiceCallResult> {
+    const result = await this.client.sendCommand(commandArg, signalArg);
+    if ('mapping' in result) {
+      this.assertOpen();
+      const snapshot = { ...this.snapshot, identity: result.identity, observations: [result], observedAt: result.observedAt };
+      const entity = ModbusMapper.toEntities(snapshot)[0];
+      this.notify({ type: 'state_changed', integrationDomain: 'modbus', deviceId: entity.deviceId, entityId: entity.id,
+        timestamp: Date.parse(result.observedAt), data: { entity } });
     }
-    const result = await this.client.sendCommand(command);
-    return { success: result.success, error: result.error, data: result.data };
+    return { success: true, data: result };
   }
 
-  public async destroy(): Promise<void> {
-    await this.client.destroy();
+  private failure(errorArg: unknown): IServiceCallResult {
+    return { success: false, error: errorArg instanceof Error ? errorArg.message : 'Modbus operation failed.',
+      data: { physicalEffectConfirmed: false, effectOutcome: errorArg instanceof plugins.ecobridgeDeviceManager.ModbusProtocolError ? errorArg.effectOutcome : 'not-sent',
+        ...(errorArg instanceof plugins.ecobridgeDeviceManager.ModbusProtocolError ? { errorCode: errorArg.code } : {}) } };
+  }
+
+  private assertOpen(): void {
+    if (this.#closed) throw new Error('Modbus runtime is destroyed.');
+    this.lease.assertOpen();
+  }
+  private notify(eventArg: IIntegrationEvent): void {
+    for (const entry of [...this.#subscriptions]) {
+      if (this.#closed) break;
+      entry.handler(eventArg);
+    }
   }
 }

package/ts/integrations/modbus/modbus.discovery.ts

@@ -1,124 +1,56 @@
 import { DiscoveryDescriptor } from '../../core/classes.discoverydescriptor.js';
 import type { IDiscoveryCandidate, IDiscoveryContext, IDiscoveryMatch, IDiscoveryMatcher, IDiscoveryValidator } from '../../core/types.js';
 import type { IModbusManualTcpEntry } from './modbus.types.js';
-
-const modbusDomain = 'modbus';
-const defaultModbusTcpPort = 502;
+import { modbusAddress, modbusIdentityText, modbusInteger, modbusRecord, modbusText, modbusUnit } from './modbus.validation.js';
 
 export class ModbusManualTcpMatcher implements IDiscoveryMatcher<IModbusManualTcpEntry> {
-  public id = 'modbus-manual-tcp-match';
-  public source = 'manual' as const;
-  public description = 'Recognize manual Modbus TCP setup entries without probing serial ports.';
+  public readonly id = 'modbus-manual-tcp-match';
+  public readonly source = 'manual' as const;
+  public readonly description = 'Accept explicit Modbus endpoint and family identity selections without network probes.';
 
   public async matches(inputArg: IModbusManualTcpEntry, contextArg: IDiscoveryContext): Promise<IDiscoveryMatch> {
-    void contextArg;
-    if (inputArg.type === 'serial' || this.looksLikeSerialPort(inputArg.host) || this.looksLikeSerialPort(String(inputArg.port || ''))) {
-      return {
-        matched: false,
-        confidence: 'low',
-        reason: 'Serial RTU setup is not auto-discovered by this integration.',
-      };
-    }
-
-    const haystack = `${inputArg.name || ''} ${inputArg.protocol || ''} ${inputArg.manufacturer || ''} ${inputArg.model || ''}`.toLowerCase();
-    const hasModbusHint = inputArg.type === 'tcp' || haystack.includes('modbus') || Boolean(inputArg.metadata?.modbus || inputArg.metadata?.modbusTcp);
-    const matched = Boolean(inputArg.host && (hasModbusHint || inputArg.port === defaultModbusTcpPort));
-    if (!matched) {
-      return {
-        matched: false,
-        confidence: 'low',
-        reason: 'Manual entry does not contain a Modbus TCP host or hint.',
-      };
+    contextArg.abortSignal?.throwIfAborted();
+    try {
+      const input = modbusRecord(inputArg, ['integrationDomain', 'address', 'port', 'unitId', 'expectedVendorName', 'expectedProductCode', 'expectedRevision', 'name']);
+      if (input.integrationDomain !== 'modbus') throw new TypeError('Manual Modbus selection requires the exact integration domain.');
+      const address = modbusAddress(input.address);
+      const port = modbusInteger(input.port === undefined ? 502 : input.port, 1, 65535);
+      const unitId = modbusUnit(input.unitId);
+      const expectedVendorName = modbusIdentityText(input.expectedVendorName);
+      const expectedProductCode = modbusIdentityText(input.expectedProductCode);
+      const expectedRevision = input.expectedRevision === undefined ? undefined : modbusIdentityText(input.expectedRevision);
+      const id = `modbus:${address}:${port}:${unitId}`;
+      return { matched: true, confidence: 'low', reason: 'Explicit manual selection is structurally valid; no network identity verification has occurred.',
+        normalizedDeviceId: id, candidate: { source: 'manual', integrationDomain: 'modbus', id, host: address, port,
+          ...(input.name === undefined ? {} : { name: modbusText(input.name, 'name', 128) }),
+          metadata: { unitId, expectedVendorName, expectedProductCode, ...(expectedRevision === undefined ? {} : { expectedRevision }) } } };
+    } catch (errorArg) {
+      return { matched: false, confidence: 'low', reason: errorArg instanceof Error ? errorArg.message : 'Invalid explicit Modbus selection.' };
     }
-
-    const id = this.normalizedId(inputArg);
-    return {
-      matched: true,
-      confidence: hasModbusHint ? 'high' : 'medium',
-      reason: 'Manual entry can be configured as a Modbus TCP hub.',
-      normalizedDeviceId: id,
-      candidate: {
-        source: 'manual',
-        integrationDomain: modbusDomain,
-        id,
-        host: inputArg.host,
-        port: inputArg.port || defaultModbusTcpPort,
-        name: inputArg.name,
-        manufacturer: inputArg.manufacturer || 'Modbus',
-        model: inputArg.model || 'TCP hub',
-        serialNumber: inputArg.serialNumber,
-        metadata: {
-          ...inputArg.metadata,
-          type: 'tcp',
-          unitId: inputArg.unitId || inputArg.slave || 1,
-        },
-      },
-    };
-  }
-
-  private normalizedId(inputArg: IModbusManualTcpEntry): string {
-    return slug(inputArg.id || inputArg.serialNumber || `${inputArg.host || 'modbus'}_${inputArg.port || defaultModbusTcpPort}`);
-  }
-
-  private looksLikeSerialPort(valueArg: string | undefined): boolean {
-    return Boolean(valueArg && (/^\/dev\//.test(valueArg) || /^com\d+$/i.test(valueArg)));
   }
 }
 
 export class ModbusCandidateValidator implements IDiscoveryValidator {
-  public id = 'modbus-candidate-validator';
-  public description = 'Validate that a candidate has enough Modbus TCP information for setup.';
+  public readonly id = 'modbus-candidate-validator';
+  public readonly description = 'Validate explicit manual selections; live admission belongs to the config flow.';
 
   public async validate(candidateArg: IDiscoveryCandidate, contextArg: IDiscoveryContext): Promise<IDiscoveryMatch> {
-    void contextArg;
-    const type = String(candidateArg.metadata?.type || '').toLowerCase();
-    if (type === 'serial' || this.looksLikeSerialPort(candidateArg.host)) {
-      return {
-        matched: false,
-        confidence: 'low',
-        reason: 'Serial RTU candidates require explicit serial configuration and are not probed.',
-      };
+    contextArg.abortSignal?.throwIfAborted();
+    try {
+      const candidate = modbusRecord(candidateArg);
+      if (candidate.source !== 'manual' || candidate.integrationDomain !== 'modbus') throw new TypeError('Modbus accepts explicit manual candidates only.');
+      const metadata = modbusRecord(candidate.metadata, ['unitId', 'expectedVendorName', 'expectedProductCode', 'expectedRevision']);
+      return new ModbusManualTcpMatcher().matches({ integrationDomain: 'modbus', address: modbusAddress(candidate.host),
+        port: candidate.port === undefined ? undefined : modbusInteger(candidate.port, 1, 65535), unitId: modbusUnit(metadata.unitId),
+        expectedVendorName: modbusIdentityText(metadata.expectedVendorName), expectedProductCode: modbusIdentityText(metadata.expectedProductCode),
+        ...(metadata.expectedRevision === undefined ? {} : { expectedRevision: modbusIdentityText(metadata.expectedRevision) }),
+        ...(candidate.name === undefined ? {} : { name: modbusText(candidate.name, 'name', 128) }) }, contextArg);
+    } catch (errorArg) {
+      return { matched: false, confidence: 'low', reason: errorArg instanceof Error ? errorArg.message : 'Invalid explicit Modbus candidate.' };
     }
-
-    const haystack = `${candidateArg.name || ''} ${candidateArg.model || ''} ${candidateArg.manufacturer || ''}`.toLowerCase();
-    const matched = Boolean(candidateArg.host && (
-      candidateArg.integrationDomain === modbusDomain
-      || candidateArg.port === defaultModbusTcpPort
-      || type === 'tcp'
-      || haystack.includes('modbus')
-      || candidateArg.metadata?.modbus
-      || candidateArg.metadata?.modbusTcp
-    ));
-    const id = slug(candidateArg.id || candidateArg.serialNumber || `${candidateArg.host || 'modbus'}_${candidateArg.port || defaultModbusTcpPort}`);
-    return {
-      matched,
-      confidence: matched && candidateArg.integrationDomain === modbusDomain ? 'high' : matched ? 'medium' : 'low',
-      reason: matched ? 'Candidate has Modbus TCP setup data.' : 'Candidate is not a Modbus TCP hub.',
-      normalizedDeviceId: matched ? id : undefined,
-      candidate: matched ? {
-        ...candidateArg,
-        integrationDomain: modbusDomain,
-        id,
-        port: candidateArg.port || defaultModbusTcpPort,
-        manufacturer: candidateArg.manufacturer || 'Modbus',
-        model: candidateArg.model || 'TCP hub',
-        metadata: {
-          ...candidateArg.metadata,
-          type: 'tcp',
-        },
-      } : undefined,
-    };
-  }
-
-  private looksLikeSerialPort(valueArg: string | undefined): boolean {
-    return Boolean(valueArg && (/^\/dev\//.test(valueArg) || /^com\d+$/i.test(valueArg)));
   }
 }
 
-export const createModbusDiscoveryDescriptor = (): DiscoveryDescriptor => {
-  return new DiscoveryDescriptor({ integrationDomain: modbusDomain, displayName: 'Modbus' })
-    .addMatcher(new ModbusManualTcpMatcher())
-    .addValidator(new ModbusCandidateValidator());
-};
-
-const slug = (valueArg: string): string => valueArg.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '') || modbusDomain;
+export const createModbusDiscoveryDescriptor = (): DiscoveryDescriptor =>
+  new DiscoveryDescriptor({ integrationDomain: 'modbus', displayName: 'Modbus' })
+    .addMatcher(new ModbusManualTcpMatcher()).addValidator(new ModbusCandidateValidator());