@smarthome.exchange/integrations 1.0.0 → 2.0.0

package/ts/integrations/pioneer/pioneer.classes.configflow.ts

@@ -1,9 +1,71 @@
-import { SimpleLocalConfigFlow } from '../../core/index.js';
+import type { IConfigFlow, INativeConfigFlowContext, IConfigFlowStep, IDiscoveryCandidate } from '../../core/types.js';
+import type { INativeAdmissionContext } from '../../core/classes.nativehomeadmission.js';
+import { NativeIntegrationOwner, NativeIntegrationScope, type INativeIntegrationOwnerOptions } from '../../core/classes.nativeintegrationowner.js';
 import type { IPioneerConfig } from './pioneer.types.js';
-import { pioneerProfile } from './pioneer.types.js';
+import { PioneerClient } from './pioneer.classes.client.js';
+import { normalizePioneerConfig, pioneerConfigKeys, pioneerRecord } from './pioneer.validation.js';
 
-export class PioneerConfigFlow extends SimpleLocalConfigFlow<IPioneerConfig> {
-  constructor() {
-    super(pioneerProfile);
+export class PioneerConfigFlow implements IConfigFlow<IPioneerConfig> {
+  private readonly owner?: NativeIntegrationOwner;
+  private readonly scope: NativeIntegrationScope;
+
+  public constructor(options: INativeIntegrationOwnerOptions | NativeIntegrationScope = {}) {
+    if (options instanceof NativeIntegrationScope) this.scope = options;
+    else {
+      this.owner = new NativeIntegrationOwner('pioneer', options);
+      this.scope = this.owner.createFlowScope();
+    }
+  }
+
+  public async start(input: IDiscoveryCandidate, context: INativeConfigFlowContext): Promise<IConfigFlowStep<IPioneerConfig>> {
+    const candidate = pioneerRecord(input);
+    if (candidate.integrationDomain !== 'pioneer') return { kind: 'error', error: 'Candidate does not belong to Pioneer.' };
+    const metadata = candidate.metadata === undefined ? {} : pioneerRecord(candidate.metadata);
+    const hints = Object.freeze({ host: candidate.host, expectedUdn: candidate.id, model: candidate.model, descriptionUrl: metadata.descriptionUrl });
+    const captured = this.scope.admit(context);
+    return {
+      kind: 'form', title: 'Connect selected Pioneer SC-95 receiver',
+      description: 'The host selects the owning home. Confirm the private IPv4, UPnP identity and raw owner volume ceiling. HTTP/TCP identity is unauthenticated LAN consistency. Network Standby must already be enabled when needed.',
+      fields: [
+        { name: 'host', label: 'Selected receiver IPv4', type: 'text', required: true },
+        { name: 'descriptionUrl', label: 'Selected UPnP description URL', type: 'text', required: true },
+        { name: 'expectedUdn', label: 'Expected UPnP UDN', type: 'text', required: true },
+        { name: 'model', label: 'Documented model', type: 'select', required: true, options: [{ label: 'SC-95', value: 'SC-95' }] },
+        { name: 'allowUnencryptedLan', label: 'Allow plaintext LAN control', type: 'boolean', required: true },
+        { name: 'maximumVolumeRaw', label: 'Owner maximum raw volume (0–185)', type: 'number', required: true },
+        { name: 'name', label: 'Display name', type: 'text' },
+      ],
+      submit: (values) => this.submit(hints, values, captured),
+    };
+  }
+
+  public destroy(): Promise<void> { return this.owner ? this.owner.close() : this.scope.close(); }
+  public retryCleanup(): Promise<void> { return this.owner ? this.owner.retryCleanup() : this.scope.retryCleanup(); }
+
+  private async submit(hints: Readonly<Record<string, unknown>>, input: unknown,
+    context: INativeAdmissionContext): Promise<IConfigFlowStep<IPioneerConfig>> {
+    this.scope.admit(context);
+    try {
+      const values = pioneerRecord(input, pioneerConfigKeys);
+      if (values.homeId !== undefined && values.homeId !== context.homeId) throw new Error('Pioneer form home conflicts with the host-selected home.');
+      const config = normalizePioneerConfig({ ...hints, ...values, homeId: context.homeId });
+      return await this.scope.run(context, config.homeId, async (lease) => {
+        const client = new PioneerClient(config, lease.context);
+        let cleanupStarted = false;
+        lease.own(() => {
+          const retry = cleanupStarted;
+          cleanupStarted = true;
+          return retry ? client.retryCleanup() : client.destroy();
+        });
+        await client.start(lease.signal);
+        lease.assertOpen();
+        return { kind: 'done', title: 'Selected receiver admitted', config };
+      });
+    } catch (error) {
+      // Cleanup failures remain actionable; the shared owner retains their handles for explicit retry.
+      if (error instanceof AggregateError) throw error;
+      this.scope.admit(context);
+      return { kind: 'error', title: 'Pioneer admission failed', error: 'Confirm exact home scope, SC-95 model, private IPv4 and UPnP identity, readable receiver settings and explicit raw owner volume ceiling.' };
+    }
   }
 }

package/ts/integrations/pioneer/pioneer.classes.integration.ts

@@ -1,23 +1,237 @@
-import { SimpleLocalIntegration, SimpleLocalRuntime, type IIntegrationRuntime, type IIntegrationSetupContext } from '../../core/index.js';
+import * as plugins from '../../plugins.js';
+import { BaseIntegration } from '../../core/classes.baseintegration.js';
+import type { IDeviceFeatureWriteRequest, IIntegrationEntity, IIntegrationEvent, IIntegrationRuntime, INativeIntegrationSetupContext, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
+import { NativeIntegrationOwner, type INativeIntegrationOwnerOptions, type INativeSetupLease } from '../../core/classes.nativeintegrationowner.js';
 import { PioneerClient } from './pioneer.classes.client.js';
 import { PioneerConfigFlow } from './pioneer.classes.configflow.js';
 import { createPioneerDiscoveryDescriptor } from './pioneer.discovery.js';
-import type { IPioneerConfig } from './pioneer.types.js';
-import { pioneerDomain, pioneerProfile } from './pioneer.types.js';
+import { PioneerMapper } from './pioneer.mapper.js';
+import { normalizePioneerConfig, pioneerRecord, validatePioneerControl } from './pioneer.validation.js';
+import type { IPioneerConfig, IPioneerSnapshot, TPioneerControl } from './pioneer.types.js';
+import { pioneerProfile } from './pioneer.types.js';
 
-export class PioneerIntegration extends SimpleLocalIntegration<IPioneerConfig> {
-  public readonly domain = pioneerDomain;
+export class PioneerIntegration extends BaseIntegration<IPioneerConfig> {
+  public readonly domain = 'pioneer';
+  public readonly displayName = 'Pioneer selected SC-95 receiver';
+  public readonly status = 'control-runtime' as const;
   public readonly discoveryDescriptor = createPioneerDiscoveryDescriptor();
-  public readonly configFlow = new PioneerConfigFlow();
+  public readonly configFlow: PioneerConfigFlow;
+  public readonly metadata = pioneerProfile.metadata;
+  private readonly owner: NativeIntegrationOwner;
 
-  constructor() {
-    super(pioneerProfile);
+  public constructor(options: INativeIntegrationOwnerOptions = {}) {
+    super();
+    this.owner = new NativeIntegrationOwner('pioneer', options);
+    this.configFlow = new PioneerConfigFlow(this.owner.createFlowScope());
   }
 
-  public override async setup(configArg: IPioneerConfig, contextArg: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
-    void contextArg;
-    return new SimpleLocalRuntime(pioneerProfile, new PioneerClient(configArg));
+  public setup(input: IPioneerConfig, context: INativeIntegrationSetupContext): Promise<IIntegrationRuntime> {
+    try {
+      const config = normalizePioneerConfig(input);
+      return this.owner.runSetup(context, config.homeId, async (lease) => {
+        const client = new PioneerClient(config, lease.context);
+        let runtime: PioneerRuntime | undefined;
+        let cleanupStarted = false;
+        lease.own(() => {
+          const retry = cleanupStarted;
+          cleanupStarted = true;
+          return runtime ? runtime.cleanupResources(retry) : retry ? client.retryCleanup() : client.destroy();
+        });
+        const initial = await client.start(lease.signal);
+        lease.assertOpen();
+        runtime = new PioneerRuntime(client, initial, lease);
+        lease.promoteToRuntime();
+        return runtime;
+      });
+    } catch (error) { return Promise.reject(error); }
   }
+
+  public destroy(): Promise<void> { return this.owner.close(); }
+  public retryCleanup(): Promise<void> { return this.owner.retryCleanup(); }
 }
 
 export class HomeAssistantPioneerIntegration extends PioneerIntegration {}
+
+interface IPioneerSubscription {
+  handler: (event: IIntegrationEvent) => void;
+  readonly callbacks: Set<Promise<void>>;
+  active: boolean;
+  failure?: unknown;
+  failed: boolean;
+  detach(): void;
+  stop(): Promise<void>;
+}
+
+class PioneerRuntime implements IIntegrationRuntime {
+  public readonly domain = 'pioneer';
+  private readonly subscriptions = new Set<IPioneerSubscription>();
+  private readonly parentAbort: () => void;
+  private closePromise?: Promise<void>;
+  private cleanupPromise?: Promise<void>;
+  private closed = false;
+
+  public constructor(private readonly client: PioneerClient, private snapshot: IPioneerSnapshot,
+    private readonly lease: INativeSetupLease) {
+    // The lease retains the client and callbacks until cleanup succeeds, including explicit retries.
+    this.parentAbort = () => { void this.destroy().catch(() => {}); };
+    lease.signal.addEventListener('abort', this.parentAbort, { once: true });
+    if (lease.signal.aborted) this.parentAbort();
+  }
+
+  public isHealthy(): boolean { return !this.closed && this.client.isHealthy(); }
+
+  public async devices(signal?: AbortSignal): Promise<plugins.shxInterfaces.data.IDeviceDefinition[]> {
+    this.assertOpen();
+    const snapshot = await this.client.getSnapshot(signal);
+    this.publish(snapshot);
+    return PioneerMapper.toDevices(snapshot);
+  }
+
+  public async entities(): Promise<IIntegrationEntity[]> {
+    this.assertOpen();
+    const snapshot = await this.client.getSnapshot();
+    this.publish(snapshot);
+    return PioneerMapper.toEntities(snapshot);
+  }
+
+  public async writeFeature(input: IDeviceFeatureWriteRequest, signal?: AbortSignal): Promise<IServiceCallResult> {
+    this.assertOpen();
+    const request = pioneerRecord(input, ['device', 'feature', 'value']);
+    const device = pioneerRecord(request.device);
+    const feature = pioneerRecord(request.feature);
+    const canonical = PioneerMapper.toDevices(this.snapshot)[0];
+    if (device.id !== canonical.id || device.integrationDomain !== this.domain) throw new Error('Pioneer feature target is outside the selected home and receiver.');
+    const admitted = canonical.features.find((entry) => entry.id === feature.id);
+    if (!admitted?.writable || feature.capability !== admitted.capability) throw new Error('Pioneer feature is not writable for the selected receiver.');
+    return this.control(validatePioneerControl({ feature: admitted.id, value: request.value }), signal);
+  }
+
+  public async callService(input: IServiceCallRequest): Promise<IServiceCallResult> {
+    this.assertOpen();
+    const request = pioneerRecord(input, ['domain', 'service', 'target', 'data']);
+    const target = pioneerRecord(request.target, ['deviceId', 'entityId']);
+    const deviceId = PioneerMapper.deviceId(this.snapshot.homeId, this.snapshot.identity.udn);
+    const entityId = PioneerMapper.entityId(this.snapshot.homeId, this.snapshot.identity.udn);
+    if ((!target.deviceId && !target.entityId) || (target.deviceId !== undefined && target.deviceId !== deviceId)
+      || (target.entityId !== undefined && target.entityId !== entityId)) throw new Error('Pioneer service target is outside the selected home and receiver.');
+    if (request.domain !== 'media_player') throw new Error('Pioneer services use media_player.');
+    let control: TPioneerControl;
+    if (request.service === 'turn_on' || request.service === 'turn_off') {
+      pioneerRecord(request.data ?? {}, []);
+      control = { feature: 'power', value: request.service === 'turn_on' };
+    } else if (request.service === 'set_volume_raw') {
+      const data = pioneerRecord(request.data, ['volume_raw']);
+      control = validatePioneerControl({ feature: 'volume_raw', value: data.volume_raw });
+    } else if (request.service === 'volume_mute') {
+      const data = pioneerRecord(request.data, ['is_volume_muted']);
+      control = validatePioneerControl({ feature: 'muted', value: data.is_volume_muted });
+    } else if (request.service === 'select_source') {
+      const data = pioneerRecord(request.data, ['source']);
+      control = validatePioneerControl({ feature: 'input', value: data.source });
+    } else throw new Error('Pioneer supports explicit power, mute, raw integer volume and observed physical input controls only.');
+    return this.control(control);
+  }
+
+  /** Emits completed observations only, with no background polling or unsolicited-event claim. */
+  public async subscribe(handler: (event: IIntegrationEvent) => void, signal?: AbortSignal): Promise<() => Promise<void>> {
+    this.assertOpen();
+    if (typeof handler !== 'function' || (signal !== undefined && !(signal instanceof AbortSignal))) throw new TypeError('Pioneer subscription requires a callback and optional AbortSignal.');
+    signal?.throwIfAborted();
+    if (this.subscriptions.size >= 32) throw new Error('Pioneer subscription capacity reached.');
+    const subscription: IPioneerSubscription = {
+      handler, callbacks: new Set(), active: true, failed: false,
+      detach: () => { subscription.active = false; signal?.removeEventListener('abort', aborted); },
+      stop: async () => {
+        subscription.detach();
+        await Promise.all([...subscription.callbacks]);
+        this.subscriptions.delete(subscription);
+        if (subscription.failed) throw subscription.failure;
+      },
+    };
+    const aborted = () => {
+      subscription.detach();
+      // Allow the current invocation and its tracked callback to settle before automatic removal.
+      void Promise.resolve().then(async () => {
+        await Promise.all([...subscription.callbacks]);
+        if (!subscription.failed) this.subscriptions.delete(subscription);
+      });
+    };
+    signal?.addEventListener('abort', aborted, { once: true });
+    this.subscriptions.add(subscription);
+    if (signal?.aborted) aborted();
+    return subscription.stop;
+  }
+
+  public destroy(): Promise<void> {
+    if (!this.closePromise) {
+      this.closed = true;
+      this.closePromise = Promise.resolve().then(() => this.lease.close());
+    }
+    return this.closePromise;
+  }
+
+  public cleanupResources(retry = false): Promise<void> {
+    if (retry) this.cleanupPromise = undefined;
+    if (!this.cleanupPromise) {
+      this.closed = true;
+      this.cleanupPromise = Promise.resolve().then(async () => {
+        const results = await Promise.allSettled([retry ? this.client.retryCleanup() : this.client.destroy(),
+          ...[...this.subscriptions].map((subscription) => subscription.stop())]);
+        const failures = results.filter((result): result is PromiseRejectedResult => result.status === 'rejected');
+        if (failures.length) throw new AggregateError(failures.map((result) => result.reason as unknown), 'Pioneer runtime cleanup failed.');
+      });
+      this.lease.signal.removeEventListener('abort', this.parentAbort);
+      for (const subscription of this.subscriptions) subscription.detach();
+    }
+    return this.cleanupPromise;
+  }
+
+  private async control(control: TPioneerControl, signal?: AbortSignal): Promise<IServiceCallResult> {
+    try {
+      const result = await this.client.setControl(control, signal);
+      try { this.publish(result.snapshot); }
+      catch { return { success: false, error: 'Pioneer was closed after dispatch; its effect is indeterminate.',
+        data: { dispatch: result.dispatch, effectOutcome: 'indeterminate', commandAcknowledged: false, causalityConfirmed: false } }; }
+      return { success: result.outcome === 'observed-target', data: { dispatch: result.dispatch, effectOutcome: result.outcome,
+        commandAcknowledged: result.commandAcknowledged, causalityConfirmed: result.causalityConfirmed } };
+    } catch (error) {
+      return { success: false, error: 'Pioneer control was refused or its observation could not be reconciled.',
+        data: { effectOutcome: error instanceof plugins.ecobridgeDeviceManager.PioneerProtocolError ? error.effectOutcome : 'not-sent',
+          commandAcknowledged: false, causalityConfirmed: false } };
+    }
+  }
+
+  private publish(snapshot: IPioneerSnapshot): void {
+    this.assertOpen(); this.snapshot = snapshot;
+    for (const subscription of this.subscriptions) {
+      if (!subscription.active) continue;
+      if (subscription.callbacks.size >= this.client.config.maxPendingOperations) {
+        subscription.failed = true;
+        subscription.failure = new Error('Pioneer observation callback capacity reached.');
+        subscription.detach();
+        continue;
+      }
+      let complete: () => void = () => {};
+      let fail: (error: unknown) => void = () => {};
+      const invoked = new Promise<void>((resolve, reject) => { complete = resolve; fail = reject; });
+      const callback = invoked.catch((error: unknown) => {
+        subscription.failed = true; subscription.failure = error; subscription.detach();
+      }).finally(() => subscription.callbacks.delete(callback));
+      // Register before user code can synchronously abort or destroy its owner.
+      subscription.callbacks.add(callback);
+      try {
+        const returned: unknown = subscription.handler({ type: 'state_changed', integrationDomain: this.domain,
+          deviceId: PioneerMapper.deviceId(snapshot.homeId, snapshot.identity.udn),
+          entityId: PioneerMapper.entityId(snapshot.homeId, snapshot.identity.udn),
+          data: { snapshot: structuredClone(snapshot), source: 'completed-receiver-observation' }, timestamp: Date.now() });
+        void Promise.resolve(returned).then(complete, fail);
+      } catch (error) { fail(error); }
+    }
+    this.assertOpen();
+  }
+
+  private assertOpen(): void {
+    if (this.closed) throw new Error('Pioneer runtime is closed.');
+    this.lease.assertOpen();
+  }
+}

package/ts/integrations/pioneer/pioneer.discovery.ts

@@ -1,4 +1,46 @@
-import { createSimpleLocalDiscoveryDescriptor } from '../../core/index.js';
-import { pioneerProfile } from './pioneer.types.js';
+import { DiscoveryDescriptor } from '../../core/classes.discoverydescriptor.js';
+import type { IDiscoveryCandidate, IDiscoveryMatch, IDiscoveryMatcher, IDiscoveryValidator } from '../../core/types.js';
+import type { IPioneerManualEntry } from './pioneer.types.js';
+import { pioneerDescription, pioneerHost, pioneerRecord, pioneerText, pioneerUdn } from './pioneer.validation.js';
 
-export const createPioneerDiscoveryDescriptor = () => createSimpleLocalDiscoveryDescriptor(pioneerProfile);
+const miss = (reason: string): IDiscoveryMatch => ({ matched: false, confidence: 'low', reason });
+
+export class PioneerManualMatcher implements IDiscoveryMatcher<IPioneerManualEntry> {
+  public readonly id = 'pioneer-manual-match';
+  public readonly source = 'manual' as const;
+  public readonly description = 'Selected SC-95 descriptor setup hints; native admission reads fresh identity.';
+
+  public async matches(input: IPioneerManualEntry): Promise<IDiscoveryMatch> {
+    try {
+      const record = pioneerRecord(input, ['source', 'integrationDomain', 'host', 'descriptionUrl', 'expectedUdn', 'id', 'name', 'manufacturer', 'model', 'metadata']);
+      if (record.source !== undefined && record.source !== 'manual') return miss('Only selected manual endpoint hints are supported.');
+      if (record.integrationDomain !== undefined && record.integrationDomain !== 'pioneer') return miss('Foreign integration hint.');
+      const metadata = record.metadata === undefined ? {} : pioneerRecord(record.metadata, ['descriptionUrl', 'identityEvidence']);
+      const host = pioneerHost(record.host);
+      const descriptionUrl = pioneerDescription(record.descriptionUrl ?? metadata.descriptionUrl, host);
+      const id = pioneerUdn(record.expectedUdn ?? record.id);
+      if (record.expectedUdn !== undefined && record.id !== undefined && pioneerUdn(record.expectedUdn) !== pioneerUdn(record.id)) return miss('Manual receiver identities conflict.');
+      if (record.model !== 'SC-95') return miss('Model has no selected vendor profile.');
+      if (record.manufacturer !== undefined && record.manufacturer !== 'Pioneer') return miss('Manufacturer does not match the selected profile.');
+      const name = record.name === undefined ? undefined : pioneerText(record.name, 'name', 128);
+      return { matched: true, confidence: 'medium', reason: 'Selected SC-95 setup hint; fresh UPnP and receiver state are required for native admission.',
+        normalizedDeviceId: id, candidate: { source: 'manual', integrationDomain: 'pioneer', id, host, name, manufacturer: 'Pioneer', model: 'SC-95',
+          metadata: { descriptionUrl, identityEvidence: 'unauthenticated-discovery-hint' } } };
+    } catch { return miss('Manual setup requires the selected SC-95 model, private endpoint, descriptor URL and exact UDN.'); }
+  }
+}
+
+export class PioneerCandidateValidator implements IDiscoveryValidator {
+  public readonly id = 'pioneer-candidate-validator';
+  public async validate(input: IDiscoveryCandidate): Promise<IDiscoveryMatch> {
+    try {
+      const record = pioneerRecord(input);
+      if (record.integrationDomain !== 'pioneer' || record.source !== 'manual') return miss('Candidate does not belong to selected Pioneer discovery.');
+      return new PioneerManualMatcher().matches(input);
+    } catch { return miss('Candidate must be a plain selected Pioneer record.'); }
+  }
+}
+
+export const createPioneerDiscoveryDescriptor = (): DiscoveryDescriptor =>
+  new DiscoveryDescriptor({ integrationDomain: 'pioneer', displayName: 'Pioneer selected SC-95 receiver' })
+    .addMatcher(new PioneerManualMatcher()).addValidator(new PioneerCandidateValidator());

package/ts/integrations/pioneer/pioneer.mapper.ts

@@ -1,26 +1,70 @@
-import type * as shxInterfaces from '@smarthome.exchange/interfaces';
-import { SimpleLocalMapper, type IIntegrationEntity, type ISimpleLocalSnapshot, type ISimpleLocalSnapshotOptions, type TSimpleLocalRawData } from '../../core/index.js';
-import type { IPioneerConfig } from './pioneer.types.js';
+import type * as plugins from '../../plugins.js';
+import type { IIntegrationEntity } from '../../core/types.js';
+import { SimpleLocalMapper } from '../../core/classes.simplelocalintegration.js';
+import type { IPioneerOfflineConfig, IPioneerOfflineSnapshot, IPioneerSnapshot, TPioneerRawData } from './pioneer.types.js';
 import { pioneerProfile } from './pioneer.types.js';
 
 export class PioneerMapper {
-  public static toSnapshot(optionsArg: Omit<ISimpleLocalSnapshotOptions<IPioneerConfig>, 'profile'>): ISimpleLocalSnapshot {
-    return SimpleLocalMapper.toSnapshot({ ...optionsArg, profile: pioneerProfile });
+  public static deviceId(homeId: string, udn: string): string {
+    return `pioneer.receiver.${encodeURIComponent(homeId)}.${encodeURIComponent(udn)}`;
   }
 
-  public static toSnapshotFromRaw(configArg: IPioneerConfig, rawDataArg: TSimpleLocalRawData): ISimpleLocalSnapshot {
-    return SimpleLocalMapper.toSnapshot({ profile: pioneerProfile, config: configArg, rawData: rawDataArg, online: true, source: 'manual' });
+  public static entityId(homeId: string, udn: string): string {
+    return `media_player.pioneer.${encodeURIComponent(homeId)}.${encodeURIComponent(udn)}`;
   }
 
-  public static toDevices(snapshotArg: ISimpleLocalSnapshot): shxInterfaces.data.IDeviceDefinition[] {
-    return SimpleLocalMapper.toDevices(pioneerProfile, snapshotArg);
+  public static toDevices(snapshot: IPioneerSnapshot): plugins.shxInterfaces.data.IDeviceDefinition[] {
+    return [{
+      id: this.deviceId(snapshot.homeId, snapshot.identity.udn), integrationDomain: 'pioneer', name: snapshot.name,
+      protocol: 'tcp', manufacturer: snapshot.identity.manufacturer, model: snapshot.identity.model, online: true,
+      features: [
+        { id: 'power', capability: 'media', name: 'Main-zone power', readable: true, writable: true },
+        { id: 'muted', capability: 'media', name: 'Main-zone mute', readable: true, writable: true },
+        { id: 'volume_raw', capability: 'media', name: 'Main-zone raw volume', unit: 'raw', readable: true, writable: true },
+        { id: 'input', capability: 'media', name: 'Main-zone physical input', readable: true, writable: snapshot.observedInputs.length > 0 },
+      ],
+      state: [
+        { featureId: 'power', value: snapshot.power, updatedAt: snapshot.observedAt },
+        { featureId: 'muted', value: snapshot.muted, updatedAt: snapshot.observedAt },
+        { featureId: 'volume_raw', value: snapshot.volumeRaw, updatedAt: snapshot.observedAt },
+        { featureId: 'input', value: snapshot.inputId, updatedAt: snapshot.observedAt },
+      ],
+      metadata: { homeId: snapshot.homeId, udn: snapshot.identity.udn, host: snapshot.host, port: snapshot.port,
+        serialNumber: snapshot.identity.serialNumber, zone: 'main', observedInputs: [...snapshot.observedInputs],
+        maximumVolumeRaw: snapshot.maximumVolumeRaw, minimumVolumeRaw: 0, maximumReceiverVolumeRaw: 185,
+        identitySource: snapshot.identity.source, identityTrust: snapshot.identity.trust,
+        stateSource: 'receiver-observation', commandAcknowledged: false, causalityConfirmed: false },
+    }];
   }
 
-  public static toEntities(snapshotArg: ISimpleLocalSnapshot): IIntegrationEntity[] {
-    return SimpleLocalMapper.toEntities(pioneerProfile, snapshotArg);
+  public static toEntities(snapshot: IPioneerSnapshot): IIntegrationEntity[] {
+    return [{
+      id: this.entityId(snapshot.homeId, snapshot.identity.udn), uniqueId: this.deviceId(snapshot.homeId, snapshot.identity.udn),
+      integrationDomain: 'pioneer', deviceId: this.deviceId(snapshot.homeId, snapshot.identity.udn), platform: 'media_player',
+      name: snapshot.name, state: snapshot.power ? 'on' : 'off', available: true,
+      attributes: { homeId: snapshot.homeId, udn: snapshot.identity.udn, zone: 'main', power: snapshot.power,
+        volumeRaw: snapshot.volumeRaw, muted: snapshot.muted, source: snapshot.inputId,
+        observedInputs: [...snapshot.observedInputs], maximumVolumeRaw: snapshot.maximumVolumeRaw,
+        observedAt: snapshot.observedAt, stateSource: 'receiver-observation', identityTrust: snapshot.identity.trust,
+        commandAcknowledged: false, causalityConfirmed: false },
+    }];
+  }
+}
+
+/** Explicitly offline transformation; this helper never creates or admits a native runtime. */
+export class PioneerOfflineMapper {
+  public static toSnapshotFromRaw(config: IPioneerOfflineConfig, rawData: TPioneerRawData): IPioneerOfflineSnapshot {
+    return this.offline(SimpleLocalMapper.toSnapshot({ profile: pioneerProfile, config: { ...config }, rawData, online: false, source: 'manual' }));
+  }
+  public static toDevices(snapshot: IPioneerOfflineSnapshot): plugins.shxInterfaces.data.IDeviceDefinition[] {
+    return SimpleLocalMapper.toDevices(pioneerProfile, this.offline(snapshot));
+  }
+  public static toEntities(snapshot: IPioneerOfflineSnapshot): IIntegrationEntity[] {
+    return SimpleLocalMapper.toEntities(pioneerProfile, this.offline(snapshot));
   }
 
-  public static slug(valueArg: unknown): string {
-    return SimpleLocalMapper.slug(valueArg);
+  private static offline(snapshot: IPioneerOfflineSnapshot): IPioneerOfflineSnapshot {
+    return { ...snapshot, online: false, capabilities: { localRead: true, localControl: false, liveControlRequiresExecutor: false },
+      entities: snapshot.entities.map((entity) => ({ ...entity, available: false, writable: false })) };
   }
 }

package/ts/integrations/pioneer/pioneer.types.ts

@@ -1,97 +1,99 @@
-import type { ISimpleLocalConfig, ISimpleLocalIntegrationProfile, ISimpleLocalSnapshot, TSimpleLocalRawData } from '../../core/index.js';
+import type { ISimpleLocalIntegrationProfile, ISimpleLocalSnapshot, TSimpleLocalRawData } from '../../core/classes.simplelocalintegration.js';
 
-export const pioneerDomain = "pioneer";
-export const pioneerDefaultName = "Pioneer";
+export const pioneerDomain = 'pioneer';
+export const pioneerDefaultName = 'Pioneer';
 export const pioneerDefaultPort = 23;
 export const pioneerMaxVolume = 185;
-export const pioneerMaxSourceNumbers = 60;
+export type TPioneerModel = 'SC-95';
 
-export type TPioneerRawData = TSimpleLocalRawData;
-export interface IPioneerSnapshot extends ISimpleLocalSnapshot {}
-export interface IPioneerConfig extends ISimpleLocalConfig {
-  url?: string;
-  macAddress?: string;
-  deviceId?: string;
-  sources?: Record<string, string>;
-  sourceScanLimit?: number;
-  commandTimeoutMs?: number;
+export interface IPioneerConfig {
+  homeId: string;
+  host: string;
+  descriptionUrl: string;
+  expectedUdn: string;
+  model: TPioneerModel;
+  allowUnencryptedLan: true;
+  maximumVolumeRaw: number;
+  name?: string;
+  port?: number;
+  timeoutMs?: number;
+  maxPendingOperations?: number;
+  maxDescriptionBytes?: number;
+  maxFrameBytes?: number;
 }
 export interface IHomeAssistantPioneerConfig extends IPioneerConfig {}
 
+export interface IPioneerIdentity {
+  readonly udn: string;
+  readonly model: TPioneerModel;
+  readonly manufacturer: 'Pioneer';
+  readonly reportedManufacturer: string;
+  readonly name: string;
+  readonly serialNumber?: string;
+  readonly source: 'selected-upnp-description';
+  readonly trust: 'unauthenticated-lan';
+  readonly observedAt: string;
+}
+
+export interface IPioneerSnapshot {
+  readonly homeId: string;
+  readonly host: string;
+  readonly port: number;
+  readonly name: string;
+  readonly identity: IPioneerIdentity;
+  readonly power: boolean;
+  readonly muted: boolean;
+  readonly volumeRaw: number;
+  readonly inputId: string;
+  readonly observedInputs: readonly string[];
+  readonly maximumVolumeRaw: number;
+  readonly observedAt: string;
+}
+
+export type TPioneerControl =
+  | { feature: 'power'; value: boolean }
+  | { feature: 'muted'; value: boolean }
+  | { feature: 'volume_raw'; value: number }
+  | { feature: 'input'; value: string };
+
+export interface IPioneerEffectResult {
+  readonly dispatch: 'written';
+  readonly outcome: 'observed-target' | 'indeterminate';
+  readonly commandAcknowledged: false;
+  readonly causalityConfirmed: false;
+  readonly snapshot: IPioneerSnapshot;
+}
+
+export interface IPioneerManualEntry {
+  host?: string;
+  descriptionUrl?: string;
+  expectedUdn?: string;
+  id?: string;
+  name?: string;
+  manufacturer?: string;
+  model?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface IPioneerOfflineConfig {
+  name?: string;
+  uniqueId?: string;
+  metadata?: Record<string, unknown>;
+}
+export type TPioneerRawData = TSimpleLocalRawData;
+export interface IPioneerOfflineSnapshot extends ISimpleLocalSnapshot {}
+
 export const pioneerProfile: ISimpleLocalIntegrationProfile = {
-  domain: pioneerDomain,
-  displayName: "Pioneer",
-  manufacturer: "Pioneer",
-  model: "Pioneer local integration",
-  defaultName: pioneerDefaultName,
-  defaultPort: pioneerDefaultPort,
-  defaultProtocol: 'telnet',
-  status: "control-runtime",
-  platforms: [
-    "media_player",
-  ],
-  serviceDomains: [
-    "media_player",
-  ],
-  controlServices: [
-    "select_source",
-    "set_volume_level",
-    "turn_off",
-    "turn_on",
-    "volume_mute",
-    "volume_down",
-    "volume_up",
-  ],
-  discoverySources: [
-    'manual',
-    'custom',
-  ],
-  discoveryKeywords: [
-    "pioneer",
-    "Pioneer",
-  ],
+  domain: pioneerDomain, displayName: 'Pioneer selected SC-95 receiver', manufacturer: 'Pioneer', model: 'SC-95',
+  defaultName: pioneerDefaultName, defaultPort: pioneerDefaultPort, defaultProtocol: 'tcp', status: 'control-runtime',
+  platforms: ['media_player'], serviceDomains: ['media_player'],
+  controlServices: ['turn_on', 'turn_off', 'volume_mute', 'set_volume_raw', 'select_source'], discoverySources: ['manual'],
+  discoveryKeywords: ['pioneer'],
   metadata: {
-    "source": "home-assistant/core",
-    "upstreamPath": "homeassistant/components/pioneer",
-    "upstreamDomain": "pioneer",
-    "iotClass": "local_polling",
-    "qualityScale": "legacy",
-    "configFlow": false,
-    "requirements": [],
-    "documentation": "https://www.home-assistant.io/integrations/pioneer",
-    "runtime": {
-      "type": "control-runtime",
-      "services": [
-        "snapshot",
-        "status",
-        "refresh",
-        "select_source",
-        "set_volume_level",
-        "turn_off",
-        "turn_on",
-        "volume_mute",
-        "volume_down",
-        "volume_up",
-      ],
-      "platforms": [
-        "media_player",
-      ],
-      "controls": "native Pioneer telnet commands for power, mute, source, and volume; injected executors remain supported",
-    },
-    "localApi": {
-      "implemented": [
-        "native Pioneer AVR Telnet/TCP polling on port 23 using ?P, ?V, ?M, ?RGBxx, and ?F",
-        "native Pioneer AVR Telnet/TCP control using PO, PF, VU, VD, xxxVL, MO, MF, and xxFN",
-        "manual local setup for Pioneer endpoints, snapshots, rawData, snapshotProvider, and injected native clients",
-        "runtime mapping for Pioneer device snapshots and Home Assistant platform metadata",
-        "safe command delegation to injected client.execute or commandExecutor",
-      ],
-      "explicitUnsupported": [
-        "Pioneer pairing, subscriptions, and event streams because the Home Assistant source only documents polling Telnet commands",
-        "media_play and media_pause because the Home Assistant Pioneer source declares features but exposes no concrete Telnet command implementation",
-        "Home Assistant entity registry migrations and repair flows",
-        "claiming write success for commands outside the documented Pioneer Telnet command set without injected client.execute or commandExecutor",
-      ],
+    source: 'native-typescript', upstreamDomain: pioneerDomain, upstreamPath: 'homeassistant/components/pioneer',
+    localApi: {
+      implemented: ['selected SC-95/CUXJ main-zone protocol', 'exact home-scoped admission', 'absolute raw integer volume', 'receiver-observed physical input selection'],
+      explicitUnsupported: ['injected clients or executors', 'native runtime snapshots', 'arbitrary ASCII commands', 'toggles or relative controls', 'dB or percentage volume conversion', 'advanced zones or media playback', 'automatic retry or reconnect'],
     },
   },
 };