@discord-player/plugin-host 8.0.0-dev.0 → 8.0.0-dev.2

package/dist/lyrics.js

@@ -0,0 +1,110 @@
+import { z } from 'zod';
+/** Validate provider-neutral records crossing a process boundary. @internal */
+export const lyricsResultSchema = z.strictObject({
+    trackId: z.string().optional(),
+    provider: z.strictObject({ pluginId: z.string().min(1), hostId: z.string().optional(), data: z.json() }).optional(),
+    plain: z.discriminatedUnion('available', [
+        z.strictObject({ available: z.literal(false) }),
+        z.strictObject({ available: z.literal(true), text: z.string() }),
+    ]),
+    synced: z.discriminatedUnion('available', [
+        z.strictObject({ available: z.literal(false) }),
+        z.strictObject({
+            available: z.literal(true),
+            lines: z.array(z.strictObject({ timestampMs: z.number().nonnegative(), line: z.string() })),
+        }),
+    ]),
+    metadata: z.json().optional(),
+});
+/** Normalize and validate a lyrics record once, including sorted synchronized timestamps.
+ * @param result Provider record.
+ * @returns Validated record with duplicate timestamps resolved deterministically.
+ */
+export function normalizeLyrics(result) {
+    const value = lyricsResultSchema.parse(result);
+    const normalized = {
+        plain: value.plain,
+        synced: value.synced,
+        ...(value.trackId === undefined ? {} : { trackId: value.trackId }),
+        ...(value.metadata === undefined ? {} : { metadata: value.metadata }),
+        ...(value.provider
+            ? {
+                provider: {
+                    pluginId: value.provider.pluginId,
+                    data: value.provider.data,
+                    ...(value.provider.hostId === undefined ? {} : { hostId: value.provider.hostId }),
+                },
+            }
+            : {}),
+    };
+    if (!value.synced.available)
+        return normalized;
+    const lines = new Map(value.synced.lines.map((line) => [line.timestampMs, line.line]));
+    return {
+        ...normalized,
+        synced: {
+            available: true,
+            lines: [...lines].sort(([a], [b]) => a - b).map(([timestampMs, line]) => ({ timestampMs, line })),
+        },
+    };
+}
+/** Parse LRC once, including multiple timestamps and decimal-second fractions.
+ * @param text LRC text.
+ * @returns Sorted normalized lines, with the last line winning duplicate timestamps.
+ */
+export function parseLyrics(text) {
+    const lines = new Map();
+    const offset = Number(/\[offset:([+-]?\d+)\]/i.exec(text)?.[1] ?? 0);
+    for (const row of text.split(/\r?\n/)) {
+        const matches = [...row.matchAll(/\[(\d+):(\d{2})(?:\.(\d{1,3}))?\]/g)];
+        const line = row.replace(/\[\d+:\d{2}(?:\.\d{1,3})?\]/g, '').trim();
+        for (const match of matches) {
+            const seconds = Number(match[2]);
+            if (seconds >= 60)
+                continue;
+            const timestampMs = Number(match[1]) * 60000 + seconds * 1000 + Number((match[3] ?? '').padEnd(3, '0')) + offset;
+            if (Number.isFinite(timestampMs) && timestampMs >= 0)
+                lines.set(timestampMs, line);
+        }
+    }
+    return [...lines].sort(([a], [b]) => a - b).map(([timestampMs, line]) => ({ timestampMs, line }));
+}
+/** Resolve lyrics through the same operation registry as source metadata.
+ * @param plugins Shared registry.
+ * @param input Track or raw query.
+ * @param signal Caller lifetime.
+ * @returns Results in provider priority order, preferring explicit and source affinity.
+ */
+export async function searchLyrics(plugins, input, signal) {
+    signal?.throwIfAborted();
+    await plugins.ready();
+    const providers = plugins.providers('lyrics.search');
+    const preferred = typeof input === 'string' ? [] : [input.lyricsReference, input.sourceReference];
+    const ordered = [...providers];
+    for (const reference of preferred.reverse()) {
+        if (!reference)
+            continue;
+        const index = ordered.findIndex((provider) => provider.pluginId === reference.pluginId && (!reference.hostId || provider.hostId === reference.hostId));
+        if (index >= 0)
+            ordered.unshift(...ordered.splice(index, 1));
+    }
+    const results = [];
+    const seen = new Set();
+    for (const provider of ordered) {
+        const groups = await plugins.execute('lyrics.search', { input }, { pluginId: provider.pluginId, hostId: provider.hostId ?? null, signal });
+        for (const result of groups.flatMap((group) => group ?? [])) {
+            const normalized = normalizeLyrics({
+                ...result,
+                ...(typeof input === 'string' ? {} : { trackId: input.id }),
+                provider: { ...provider, data: result.provider?.data ?? null },
+            });
+            const key = JSON.stringify([normalized.plain, normalized.synced]);
+            if ((!normalized.plain.available && !normalized.synced.available) || seen.has(key))
+                continue;
+            seen.add(key);
+            results.push(normalized);
+        }
+    }
+    return results;
+}
+//# sourceMappingURL=lyrics.js.map

package/dist/lyrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lyrics.js","sourceRoot":"","sources":["../src/lyrics.ts"],"names":[],"mappings":"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"}

package/dist/media.d.ts

@@ -0,0 +1,15 @@
+/** Access limits for remote media materialization. Providers execute trusted code; this is not a plugin sandbox. */
+export interface MediaAccessPolicy {
+    /** Permit private and loopback destinations, including redirects. Default false. */
+    allowPrivateNetworks?: boolean;
+    /** Optional exact hostname allowlist, also applied to redirects. */
+    allowedHosts?: readonly string[];
+    /** Authorized file roots. Default empty; roots and their parents must be administrator-owned. */
+    allowedFileRoots?: readonly string[];
+    /** Maximum encoded bytes per response. Default 512 MiB. */
+    maxBytes?: number;
+    /** Maximum simultaneous streams per host. Default 32. */
+    maxConcurrent?: number;
+    /** Whole-stream deadline in milliseconds, including DNS and connection. Default 30 minutes. */
+    timeoutMs?: number;
+}

package/dist/media.js

@@ -0,0 +1,193 @@
+import { lookup } from 'node:dns/promises';
+import { request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+import { BlockList, isIP } from 'node:net';
+import { open, realpath } from 'node:fs/promises';
+import { relative, isAbsolute, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Readable, Transform, addAbortSignal, pipeline } from 'node:stream';
+const active = new WeakMap();
+const denied = new BlockList();
+const deniedV6 = new BlockList();
+deniedV6.addSubnet('2001::', 23, 'ipv6');
+deniedV6.addSubnet('2001:db8::', 32, 'ipv6');
+deniedV6.addSubnet('2002::', 16, 'ipv6');
+deniedV6.addSubnet('3fff::', 20, 'ipv6');
+for (const [address, prefix] of [
+    ['0.0.0.0', 8],
+    ['10.0.0.0', 8],
+    ['100.64.0.0', 10],
+    ['127.0.0.0', 8],
+    ['169.254.0.0', 16],
+    ['172.16.0.0', 12],
+    ['192.0.0.0', 24],
+    ['192.0.2.0', 24],
+    ['192.168.0.0', 16],
+    ['198.18.0.0', 15],
+    ['198.51.100.0', 24],
+    ['203.0.113.0', 24],
+    ['224.0.0.0', 3],
+])
+    denied.addSubnet(address, prefix);
+function publicAddress(address) {
+    if (isIP(address) === 4)
+        return !denied.check(address, 'ipv4');
+    // Only global unicast IPv6; reject transition/mapped forms and documentation ranges.
+    return /^[23][0-9a-f]{3}:/i.test(address) && !deniedV6.check(address, 'ipv6');
+}
+function positive(value) {
+    if (!Number.isSafeInteger(value) || value < 1)
+        throw new RangeError('Invalid media resource limit');
+    return value;
+}
+/** Validate URL policy and resolve the exact address used for a connection.
+ * @internal
+ * @param url Provider URL.
+ * @param policy Host access policy.
+ * @param signal Caller lifetime.
+ * @returns Validated destination; callers opening sockets must pin this address.
+ */
+export async function authorizeMediaURL(url, policy, signal) {
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password)
+        throw new Error('Media requires an HTTP(S) URL without user credentials');
+    const hostname = url.hostname.replace(/^\[|\]$/g, '');
+    if (policy.allowedHosts && !policy.allowedHosts.includes(hostname))
+        throw new Error('Media hostname denied');
+    signal.throwIfAborted();
+    const addresses = await new Promise((resolve, reject) => {
+        const abort = () => reject(signal.reason);
+        signal.addEventListener('abort', abort, { once: true });
+        lookup(hostname, { all: true })
+            .then(resolve, reject)
+            .finally(() => signal.removeEventListener('abort', abort));
+    });
+    signal.throwIfAborted();
+    if (!addresses.length || (!policy.allowPrivateNetworks && addresses.some(({ address }) => !publicAddress(address))))
+        throw new Error('Media destination denied');
+    const selected = addresses[0];
+    return selected;
+}
+async function remote(url, policy, signal, redirects = 0) {
+    const selected = await authorizeMediaURL(url, policy, signal);
+    const response = await new Promise((resolve, reject) => {
+        const req = (url.protocol === 'https:' ? httpsRequest : httpRequest)(url, {
+            signal,
+            // Pin the checked address; keep the original Host and TLS server name. No second DNS lookup.
+            lookup: (_hostname, options, callback) => {
+                if (options.all)
+                    callback(null, [selected]);
+                else
+                    callback(null, selected.address, selected.family);
+            },
+            headers: { 'accept-encoding': 'identity' },
+        }, resolve);
+        req.once('error', reject);
+        req.setTimeout(30000, () => req.destroy(new Error('Media upstream idle timeout')));
+        req.end();
+    });
+    if ([301, 302, 303, 307, 308].includes(response.statusCode ?? 0)) {
+        const location = response.headers.location;
+        response.destroy();
+        if (!location || redirects >= 5)
+            throw new Error('Invalid media redirect');
+        const target = new URL(location, url);
+        if (url.protocol === 'https:' && target.protocol !== 'https:')
+            throw new Error('Media TLS downgrade denied');
+        return remote(target, policy, signal, redirects + 1);
+    }
+    if (response.statusCode !== 200) {
+        response.destroy();
+        throw new Error(`Media upstream returned ${response.statusCode}`);
+    }
+    return response;
+}
+/** Open bounded encoded media under a host policy. No whole-response buffering occurs.
+ * @internal
+ * @param source Trusted provider result, potentially containing an untrusted location.
+ * @param policy Host authorization and resource limits.
+ * @param signal Resolution/consumer lifetime.
+ * @returns Owned stream; close, abort, errors and deadlines release upstream resources.
+ */
+export async function openMedia(source, policy, signal) {
+    const maxBytes = positive(policy.maxBytes ?? 512 * 1024 * 1024);
+    const maxConcurrent = positive(policy.maxConcurrent ?? 32);
+    const timeout = positive(policy.timeoutMs ?? 1800000);
+    const expiration = 'expiresAtMs' in source ? Number(source.expiresAtMs) : undefined;
+    if (expiration !== undefined && (!Number.isFinite(expiration) || expiration <= Date.now())) {
+        if ('stream' in source)
+            source.stream.destroy();
+        throw new Error('Media source credentials have expired; resolve the source again');
+    }
+    if ((active.get(policy) ?? 0) >= maxConcurrent) {
+        if ('stream' in source)
+            source.stream.destroy();
+        throw new Error('Media concurrency limit reached');
+    }
+    active.set(policy, (active.get(policy) ?? 0) + 1);
+    const controller = new AbortController();
+    const lifetime = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
+    const timer = setTimeout(() => controller.abort(new Error('Media deadline exceeded')), timeout);
+    timer.unref();
+    let input;
+    let released = false;
+    const release = () => {
+        if (released)
+            return;
+        released = true;
+        clearTimeout(timer);
+        active.set(policy, (active.get(policy) ?? 1) - 1);
+        input?.destroy();
+    };
+    try {
+        lifetime.throwIfAborted();
+        if ('stream' in source)
+            input = source.stream;
+        else if ('buffer' in source)
+            input = Readable.from([source.buffer]);
+        else if ('file' in source) {
+            const path = await realpath(source.file.startsWith('file:') ? fileURLToPath(source.file) : source.file);
+            const roots = await Promise.all((policy.allowedFileRoots ?? []).map((root) => realpath(root)));
+            if (!roots.some((root) => {
+                const rel = relative(root, path);
+                return rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+            }))
+                throw new Error('Media file outside allowed roots');
+            const file = await open(path, 'r');
+            try {
+                if (!(await file.stat()).isFile())
+                    throw new Error('Media path is not a regular file');
+                input = file.createReadStream();
+            }
+            catch (error) {
+                await file.close();
+                throw error;
+            }
+        }
+        else if ('url' in source)
+            input = await remote(new URL(source.url), policy, lifetime);
+        else
+            throw new Error('A source host cannot materialize another operation source');
+        lifetime.throwIfAborted();
+        let bytes = 0;
+        const output = new Transform({
+            destroy(error, callback) {
+                release();
+                callback(error);
+            },
+            transform(chunk, _encoding, callback) {
+                bytes += chunk.length;
+                callback(bytes > maxBytes ? new Error('Media byte limit exceeded') : null, chunk);
+            },
+        });
+        output.once('close', release);
+        addAbortSignal(lifetime, output);
+        pipeline(input, output, () => { });
+        return { stream: output, ...(expiration === undefined ? {} : { expiresAtMs: expiration }) };
+    }
+    catch (error) {
+        controller.abort();
+        release();
+        throw error;
+    }
+}
+//# sourceMappingURL=media.js.map

package/dist/media.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"media.js","sourceRoot":"","sources":["../src/media.ts"],"names":[],"mappings":"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"}

package/dist/plugins/execution-options.d.ts

@@ -3,6 +3,8 @@ import type { MediaSource } from '@remedia/client';
 export interface ExecuteOptions {
     /** Restrict execution to one provider. */
     pluginId?: string;
+    /** Restrict deployment; null restricts execution to embedded registrations. */
+    hostId?: string | null;
     /** Caller cancellation. */
     signal?: AbortSignal;
     /** Disabled source IDs. */

package/dist/plugins/operation-dispatch.js

@@ -1,5 +1,27 @@
 import { Readable } from 'node:stream';
 import { PluginError } from './plugin-error.js';
+/** Select active, permitted handlers using the dispatcher's own routing rules.
+ * @internal
+ * @param operation Operation being inspected.
+ * @param input Routing input.
+ * @param options Provider targeting and block list.
+ * @param state Current registry state.
+ * @returns Ordered applicable subscriptions without invoking them.
+ */
+export function selectHandlers(operation, input, options, state) {
+    return state.handlers
+        .filter((handler) => handler.operation === operation &&
+        handler.entry.active &&
+        (!options.pluginId || handler.entry.id === options.pluginId) &&
+        (options.hostId === undefined ||
+            (handler.entry.registration.definition.remoteHost?.hostId ?? null) === options.hostId) &&
+        !options.blocked?.includes(handler.entry.id) &&
+        !state.blocked().includes(handler.entry.id) &&
+        (!input.protocol ||
+            !handler.protocols?.length ||
+            handler.protocols?.includes(input.protocol)))
+        .sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0) || a.order - b.order);
+}
 /** Dispatch a typed operation against initialized host state.
  * @internal
  * @param operation Operation name.
@@ -14,16 +36,7 @@ export async function dispatchOperation(operation, input, options, state, handle
     if (!policy) {
         throw new Error(`Undefined operation: ${operation}`);
     }
-    const handlers = state.handlers
-        .filter((handler) => handler.operation === operation &&
-        handler.entry.active &&
-        (!options.pluginId || handler.entry.id === options.pluginId) &&
-        !options.blocked?.includes(handler.entry.id) &&
-        !state.blocked().includes(handler.entry.id) &&
-        (!input.protocol ||
-            !handler.protocols?.length ||
-            handler.protocols.includes(input.protocol)))
-        .sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0) || a.order - b.order);
+    const handlers = selectHandlers(operation, input, options, state);
     const results = [];
     let value = input;
     for (const handler of handlers) {
@@ -70,7 +83,13 @@ export async function dispatchOperation(operation, input, options, state, handle
             }
         }
         if (operation === 'search.query.match' && result !== null) {
-            result = { ...result, pluginId: handler.entry.id };
+            result = {
+                ...result,
+                pluginId: handler.entry.id,
+                ...(handler.entry.registration.definition.remoteHost
+                    ? { hostId: handler.entry.registration.definition.remoteHost.hostId }
+                    : {}),
+            };
         }
         if (policy === 'first') {
             let owner = handler.entry;

package/dist/plugins/operation-dispatch.js.map

@@ -1 +1 @@
-{"version":3,"file":"operation-dispatch.js","sourceRoot":"","sources":["../../src/plugins/operation-dispatch.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"operation-dispatch.js","sourceRoot":"","sources":["../../src/plugins/operation-dispatch.ts"],"names":[],"mappings":"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"}

package/dist/plugins/plugin-error.js.map

@@ -1 +1 @@
-{"version":3,"file":"plugin-error.js","sourceRoot":"","sources":["../../src/plugins/plugin-error.ts"],"names":[],"mappings":"AAAA,oFAAoF;AACpF,MAAM,OAAO,WAAY,SAAQ,KAAK;IAQlB,QAAQ;IAER,SAAS;IAT3B;;;;OAIG;IACH;IACE,uCAAuC;IACvB,QAAgB;IAChC,2CAA2C;IAC3B,SAAiB,EACjC,KAAc;QAEd,KAAK,CAAC,UAAU,QAAQ,kBAAkB,SAAS,KAAK,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE;YAChH,KAAK;SACN,CAAC,CAAC;wBAPa,QAAQ;yBAER,SAAS;QAOzB,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC5B,CAAC;CACF"}
+{"version":3,"file":"plugin-error.js","sourceRoot":"","sources":["../../src/plugins/plugin-error.ts"],"names":[],"mappings":"AAAA,oFAAoF;AACpF,MAAM,OAAO,WAAY,SAAQ,KAAK;IAQlB,QAAQ;IAGR,SAAS;IAV3B;;;;OAIG;IACH;IACE,uCAAuC;IACvB,QAAgB;IAEhC,2CAA2C;IAC3B,SAAiB,EAEjC,KAAc;QAEd,KAAK,CAAC,UAAU,QAAQ,kBAAkB,SAAS,KAAK,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE;YAChH,KAAK;SACN,CAAC,CAAC;wBATa,QAAQ;yBAGR,SAAS;QAQzB,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC5B,CAAC;CACF"}

package/dist/plugins/registry-internals.d.ts

@@ -1,4 +1,4 @@
-import type { DispatchPolicy, HandlerOptions, OperationInput, OperationContext, OperationName, OperationResult, PluginRegistration, SourcePluginContext } from './types.js';
+import type { DispatchPolicy, HandlerOptions, OperationInput, OperationContext, OperationName, OperationResult, PluginRegistration, PluginContext } from './types.js';
 import type { ExecuteOptions } from './execution-options.js';
 /** Internal registration ownership record. */
 export type Entry = {
@@ -7,7 +7,7 @@ export type Entry = {
     /** Registration-local declaration and options. */
     registration: PluginRegistration<any>;
     /** Registration-local setup context. */
-    context: SourcePluginContext<any>;
+    context: PluginContext<any>;
     /** Registration lifetime cancellation. */
     controller: AbortController;
     /** Owned cleanup callbacks in registration order. */

package/dist/plugins/registry.d.ts

@@ -1,39 +1,80 @@
+import { type RemotePluginHostOptions } from '../remote.js';
 import type { MediaSource } from '@remedia/client';
 import type { Track } from '../structures/track.js';
 import type { ExecuteOptions, StreamResolutionOptions } from './execution-options.js';
-import type { OperationInput, OperationName, OperationResult, PluginRegistration, SourceOperationMap } from './types.js';
+import type { OperationInput, OperationName, OperationResult, PluginRegistration, ProviderReference, OperationMap } from './types.js';
 import type { LegacyPlayerContext } from '../legacy-player.js';
 export { PluginError } from './plugin-error.js';
 export type { ExecuteOptions, StreamResolutionOptions } from './execution-options.js';
-/** Context-owned source execution registry. Removal aborts and drains calls before teardown. */
+/** Context-owned capability registry. Removal aborts and drains calls before teardown. */
 export declare class PluginRegistry {
     readonly player: LegacyPlayerContext;
     private readonly blocked;
+    private readonly hostId?;
+    private advertisements;
     private entries;
     private handlers;
     private order;
     private resultOwners;
     private destroyed;
+    private readonly lifetime;
     /** Create an independent host.
      * @param player Structural source context.
      * @param blocked Default disabled source IDs supplied by the owning Player.
+     * @param hostId Owning deployment, absent in ordinary embedded execution.
      */
-    constructor(player: LegacyPlayerContext, blocked?: () => readonly string[]);
+    constructor(player: LegacyPlayerContext, blocked?: () => readonly string[], hostId?: string | undefined);
     private definitions;
     /** Define a declaration-merged operation before registering handlers.
      * @param name Operation name.
      * @param policy Dispatch policy matching its contract.
      */
-    defineOperation<K extends OperationName>(name: K, policy: SourceOperationMap[K]['policy']): void;
+    defineOperation<K extends OperationName>(name: K, policy: OperationMap[K]['policy']): void;
     /** Whether an ID is reserved or active.
      * @param id Plugin ID.
+     * @param hostId Optional deployment constraint.
      */
-    has(id: string): boolean;
+    has(id: string, hostId?: string): boolean;
+    /** List active provider/deployment references in priority and registration order.
+     * @param operation Capability to inspect.
+     * @returns Unique eligible provider/deployment references.
+     */
+    providers(operation: OperationName): ProviderReference[];
+    /** Check whether a deployment has an owned registration.
+     * @param hostId Deployment identity.
+     */
+    hasHost(hostId: string): boolean;
+    /** Advertise only actual local operation handlers.
+     * @returns Serializable provider capability descriptions.
+     */
+    describe(): {
+        id: string;
+        operations: (keyof OperationMap)[];
+        protocols: string[];
+        priorities: {
+            [k: string]: number;
+        };
+    }[];
+    /** Register all advertised providers from an existing HTTP deployment.
+     * @param host Existing deployment and authentication.
+     * @param signal Caller lifetime.
+     */
+    registerHost(host: RemotePluginHostOptions, signal?: AbortSignal): Promise<void>;
     /** Whether an active matching handler explicitly accepts a protocol.
      * @param protocol Query prefix without punctuation.
      * @param options Source targeting and block list.
      */
     supportsProtocol(protocol: string, options?: ExecuteOptions): boolean;
+    /** Ordered owners of a custom query protocol.
+     * @param protocol Registered protocol prefix.
+     * @param options Targeting and block list.
+     * @returns Eligible provider identities, in dispatch order.
+     */
+    protocolMatches(protocol: string, options?: ExecuteOptions): {
+        pluginId: string;
+        hostId: string | undefined;
+        score: number;
+    }[];
     /** Register and initialize a source descriptor, reserving its ID synchronously.
      * @param registration Descriptor produced by definePlugin.
      */
@@ -41,9 +82,10 @@ export declare class PluginRegistry {
     private cleanup;
     /** Abort new and active work, drain handlers, and release resources. Handlers must cooperate with cancellation.
      * @param id Plugin ID.
+     * @param hostId Optional deployment identity when the provider exists on multiple hosts.
      * @returns Whether the registration existed.
      */
-    unregister(id: string): Promise<boolean>;
+    unregister(id: string, hostId?: string): Promise<boolean>;
     /** Initialize pending registrations before dispatch. */
     ready(): Promise<void>;
     /** Destroy all registrations, attempting every cleanup even when one fails. */