@seedcord/core 0.10.0 → 0.11.0

package/dist/PluginHost-B8kxLOeb.mjs

@@ -0,0 +1,245 @@
+import { n as StartupPhase, t as ShutdownPhase } from "./phases-BauKJOTT.mjs";
+import { SeedcordErrorCode } from "@seedcord/errors";
+import { SeedcordError, SeedcordRangeError, SeedcordTypeError } from "@seedcord/errors/internal";
+import { FRAMEWORK_CHANNELS, Logger } from "@seedcord/logger";
+import { HostPluginKeys } from "@seedcord/types/internal";
+
+//#region src/hmr/devChannel.ts
+let channel;
+/** @internal */
+function setDevChannel(next) {
+	channel = next;
+}
+/** @internal */
+function getDevChannel() {
+	return channel;
+}
+
+//#endregion
+//#region src/plugin/lifecycle.ts
+const DEFAULT_INIT_TIMEOUT_MS = 15e3;
+const DEFAULT_READY_TIMEOUT_MS = 15e3;
+const DEFAULT_DISPOSE_TIMEOUT_MS = 1e4;
+function timeoutOf(field, declared, fallback, pluginName) {
+	if (declared === void 0) return fallback;
+	if (!Number.isFinite(declared) || declared <= 0) throw new SeedcordRangeError(SeedcordErrorCode.LifecycleInvalidTimeout, [`${pluginName}'s lifecycle ${field}.timeout`, declared]);
+	return declared;
+}
+/** @internal */
+function resolveLifecycleSpec(spec, pluginName) {
+	return {
+		init: {
+			phase: spec?.init?.phase ?? 1,
+			timeout: timeoutOf("init", spec?.init?.timeout, DEFAULT_INIT_TIMEOUT_MS, pluginName)
+		},
+		ready: { timeout: timeoutOf("ready", spec?.ready?.timeout, DEFAULT_READY_TIMEOUT_MS, pluginName) },
+		dispose: {
+			phase: spec?.dispose?.phase ?? 3,
+			timeout: timeoutOf("dispose", spec?.dispose?.timeout, DEFAULT_DISPOSE_TIMEOUT_MS, pluginName)
+		}
+	};
+}
+
+//#endregion
+//#region src/plugin/Plugin.ts
+/** @internal */
+const resolvedSpecSlot = Symbol("seedcord:plugin:spec");
+/** @internal */
+const loggerSlot = Symbol("seedcord:plugin:logger");
+/** @internal */
+const scopeSlot = Symbol("seedcord:plugin:scope");
+/** @internal */
+const FixedScope = Symbol("seedcord:plugin:fixed-scope");
+/**
+* Base class for a seedcord plugin. Extend it and implement `init()`. `this.core` is the running
+* bot.
+*
+* Your constructor takes the host first and passes it to `super()`. Add your own parameters after
+* it. `attach()` types them at the call site.
+*
+* A plugin that narrows `transport` or `runtime` in `Opts` passes the same values to `super()`.
+* `attach()` throws when either one differs from the bot's.
+*
+* @typeParam Opts - Where this plugin may attach.
+* @typeParam TCore - The `Core` each transport binds `this.core` to.
+* @typeParam Fixed - The `transport` and `runtime` values a transport's own `Plugin` base sets. Leave it out.
+*
+* @example
+* ```ts
+* class Analytics extends Plugin<{ transport: 'gateway' }> {
+*     constructor(
+*         host: CoreBase,
+*         private readonly apiKey: string
+*     ) {
+*         super(host, { transport: 'gateway', init: { phase: StartupPhase.Login } });
+*     }
+*
+*     public async init(): Promise<void> {
+*         await this.connect(this.apiKey);
+*     }
+* }
+*
+* seedcord.attach('analytics', Analytics, apiKey);
+* ```
+*/
+var Plugin = class {
+	host;
+	/** @internal */
+	static [FixedScope] = {};
+	/** @internal */
+	[resolvedSpecSlot];
+	/** @internal */
+	[loggerSlot];
+	/** @internal */
+	[scopeSlot];
+	/** Logs under the plugin's class name, on the channel its attach key sets. */
+	logger;
+	constructor(host, ...[spec]) {
+		this.host = host;
+		this.logger = new Logger(this.constructor.name);
+		this[loggerSlot] = this.logger;
+		this[resolvedSpecSlot] = resolveLifecycleSpec(spec, this.constructor.name);
+		const passed = spec;
+		const fixed = new.target[FixedScope];
+		this[scopeSlot] = {
+			transport: fixed.transport ?? passed?.transport ?? "any",
+			runtime: fixed.runtime ?? passed?.runtime ?? "any"
+		};
+	}
+	/** The host, typed to the transport whose `Plugin` base this class extends. */
+	get core() {
+		return this.host;
+	}
+	/**
+	* Rejects the options this plugin got.
+	*
+	* @param reason - Why the options are invalid.
+	* @throws A **SeedcordTypeError** every time, with the plugin class name and `reason` in its message.
+	*/
+	rejectOptions(reason) {
+		throw new SeedcordTypeError(SeedcordErrorCode.PluginOptionsRejected, [this.constructor.name, reason]);
+	}
+	/** Override to reload plugin state on an HMR update. */
+	onHmr(_event) {
+		return Promise.resolve();
+	}
+	/**
+	* Registers critical file patterns that should trigger a full restart when changed in Dev HMR.
+	* @param patterns - Glob patterns. A relative one resolves against `root` from `seedcord.config.ts`.
+	*/
+	registerCriticalFiles(patterns) {
+		getDevChannel()?.send("seedcord:register-critical-files", { patterns });
+	}
+};
+/** @internal */
+function resolvedLifecycleSpecOf(plugin) {
+	return plugin[resolvedSpecSlot];
+}
+/** @internal */
+function extendsThisCorePlugin(ctor) {
+	return ctor.prototype instanceof Plugin;
+}
+/** @internal */
+function pluginLoggerOf(plugin) {
+	return plugin[loggerSlot];
+}
+/** @internal */
+function declaredScopeOf(plugin) {
+	return plugin[scopeSlot];
+}
+
+//#endregion
+//#region src/plugin/PluginHost.ts
+const RESERVED_KEYS = new Set(FRAMEWORK_CHANNELS);
+const attachmentsSlot = Symbol("seedcord:host:attachments");
+const sealSlot = Symbol("seedcord:host:seal");
+/** Base class for a plugin host. */
+var PluginHost = class {
+	#sealed = false;
+	#attachments = [];
+	#groups = /* @__PURE__ */ new Map();
+	#scope;
+	constructor(transport, runtime) {
+		this.#scope = {
+			transport,
+			runtime
+		};
+	}
+	/** @internal */
+	get [attachmentsSlot]() {
+		return this.#attachments;
+	}
+	/** @internal */
+	[sealSlot]() {
+		this.#sealed = true;
+	}
+	/** @internal codegen reads this to emit the `Core` augmentation */
+	get [HostPluginKeys]() {
+		return this.#attachments.map((attachment) => attachment.key);
+	}
+	attach(key, Plugin, ...args) {
+		if (this.#sealed) throw new SeedcordError(SeedcordErrorCode.CorePluginAfterInit);
+		const dot = key.indexOf(".");
+		const head = dot === -1 ? key : key.slice(0, dot);
+		if (RESERVED_KEYS.has(head)) throw new SeedcordTypeError(SeedcordErrorCode.CorePluginReservedChannel, [head]);
+		const leaf = dot === -1 ? void 0 : key.slice(dot + 1);
+		if (head === "" || leaf === "") throw new SeedcordTypeError(SeedcordErrorCode.CorePluginKeyMalformed, [key, "has an empty part."]);
+		if (leaf?.includes(".")) throw new SeedcordTypeError(SeedcordErrorCode.CorePluginKeyMalformed, [key, "has more than one dot."]);
+		this.#assertFree(head, leaf, key);
+		if (!extendsThisCorePlugin(Plugin)) throw new SeedcordTypeError(SeedcordErrorCode.CorePluginFromOtherCore, [Plugin.name]);
+		const instance = new Plugin(this, ...args);
+		this.#assertScope(Plugin.name, declaredScopeOf(instance));
+		pluginLoggerOf(instance).setChannel(key);
+		this.#attachments.push({
+			key,
+			instance,
+			spec: resolvedLifecycleSpecOf(instance)
+		});
+		if (leaf === void 0) return Object.assign(this, { [key]: instance });
+		this.#groupFor(head)[leaf] = instance;
+		return this;
+	}
+	#assertFree(head, leaf, key) {
+		if (leaf === void 0) {
+			if (this.#groups.has(key)) throw new SeedcordTypeError(SeedcordErrorCode.CorePluginKeyHoldsGroup, [key]);
+			if (key in this) throw new SeedcordTypeError(SeedcordErrorCode.CorePluginKeyExists, [key]);
+			return;
+		}
+		const group = this.#groups.get(head);
+		if (!group) {
+			if (head in this) throw new SeedcordTypeError(SeedcordErrorCode.CorePluginGroupTaken, [head, key]);
+			return;
+		}
+		if (Object.hasOwn(group, leaf)) throw new SeedcordTypeError(SeedcordErrorCode.CorePluginKeyExists, [key]);
+	}
+	#assertScope(pluginName, declared) {
+		for (const axis of ["transport", "runtime"]) {
+			const host = this.#scope[axis];
+			if (declared[axis] === "any" || declared[axis] === host) continue;
+			throw new SeedcordTypeError(SeedcordErrorCode.CorePluginScopeMismatch, [
+				pluginName,
+				axis,
+				declared[axis],
+				host
+			]);
+		}
+	}
+	#groupFor(head) {
+		const existing = this.#groups.get(head);
+		if (existing) return existing;
+		const group = Object.create(null);
+		this.#groups.set(head, group);
+		Object.assign(this, { [head]: group });
+		return group;
+	}
+};
+function attachmentsOf(host) {
+	return host[attachmentsSlot];
+}
+function sealAttachments(host) {
+	host[sealSlot]();
+}
+
+//#endregion
+export { Plugin as a, setDevChannel as c, FixedScope as i, attachmentsOf as n, pluginLoggerOf as o, sealAttachments as r, getDevChannel as s, PluginHost as t };
+//# sourceMappingURL=PluginHost-B8kxLOeb.mjs.map

package/dist/PluginHost-B8kxLOeb.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"PluginHost-B8kxLOeb.mjs","names":[],"sources":["../src/hmr/devChannel.ts","../src/plugin/lifecycle.ts","../src/plugin/Plugin.ts","../src/plugin/PluginHost.ts"],"sourcesContent":["import type { DevChannel, SeedcordCliEvents, SeedcordFrameworkEvents } from '@seedcord/types/internal';\n\nexport type CliChannel = DevChannel<SeedcordFrameworkEvents, SeedcordCliEvents>;\n\n// one module instance per process, the HmrManager write and every framework read share it\nlet channel: CliChannel | undefined;\n\n/** @internal */\nexport function setDevChannel(next: CliChannel | undefined): void {\n    channel = next;\n}\n\n/** @internal */\nexport function getDevChannel(): CliChannel | undefined {\n    return channel;\n}\n","import { SeedcordErrorCode } from '@seedcord/errors';\nimport { SeedcordRangeError } from '@seedcord/errors/internal';\n\nimport { ShutdownPhase, StartupPhase } from '#src/lifecycle/phases';\n\n/**\n * Sets when a plugin's lifecycle methods run. Pass it as the second argument to `super()`. Omit a\n * field to keep its default.\n *\n * @see {@link StartupPhase}\n * @see {@link ShutdownPhase}\n * @example\n * ```ts\n * super(host, { init: { phase: StartupPhase.Login }, dispose: { timeout: 30_000 } });\n * ```\n */\nexport interface PluginLifecycleSpec {\n    /**\n     * Defaults to `StartupPhase.Configuration` and 15000ms. Set the phase to `Ready` and `init()`\n     * runs ahead of every plugin's `ready()`.\n     */\n    init?: { phase?: StartupPhase; timeout?: number };\n    /** `ready()` always runs in `StartupPhase.Ready`. Defaults to a 15000ms timeout. */\n    ready?: { timeout?: number };\n    /** Defaults to `ShutdownPhase.Disconnect` and 10000ms. */\n    dispose?: { phase?: ShutdownPhase; timeout?: number };\n}\n\n/** @internal */\nexport interface ResolvedPluginLifecycleSpec {\n    readonly init: { readonly phase: StartupPhase; readonly timeout: number };\n    readonly ready: { readonly timeout: number };\n    readonly dispose: { readonly phase: ShutdownPhase; readonly timeout: number };\n}\n\nconst DEFAULT_INIT_TIMEOUT_MS = 15_000;\nconst DEFAULT_READY_TIMEOUT_MS = 15_000;\nconst DEFAULT_DISPOSE_TIMEOUT_MS = 10_000;\n\nfunction timeoutOf(\n    field: 'init' | 'ready' | 'dispose',\n    declared: number | undefined,\n    fallback: number,\n    pluginName: string\n): number {\n    if (declared === undefined) return fallback;\n    if (!Number.isFinite(declared) || declared <= 0) {\n        throw new SeedcordRangeError(SeedcordErrorCode.LifecycleInvalidTimeout, [\n            `${pluginName}'s lifecycle ${field}.timeout`,\n            declared\n        ]);\n    }\n    return declared;\n}\n\n/** @internal */\nexport function resolveLifecycleSpec(\n    spec: PluginLifecycleSpec | undefined,\n    pluginName: string\n): ResolvedPluginLifecycleSpec {\n    return {\n        init: {\n            phase: spec?.init?.phase ?? StartupPhase.Configuration,\n            timeout: timeoutOf('init', spec?.init?.timeout, DEFAULT_INIT_TIMEOUT_MS, pluginName)\n        },\n        ready: {\n            timeout: timeoutOf('ready', spec?.ready?.timeout, DEFAULT_READY_TIMEOUT_MS, pluginName)\n        },\n        dispose: {\n            phase: spec?.dispose?.phase ?? ShutdownPhase.Disconnect,\n            timeout: timeoutOf('dispose', spec?.dispose?.timeout, DEFAULT_DISPOSE_TIMEOUT_MS, pluginName)\n        }\n    };\n}\n","import { SeedcordErrorCode } from '@seedcord/errors';\nimport { SeedcordTypeError } from '@seedcord/errors/internal';\nimport { Logger } from '@seedcord/logger';\n\nimport { getDevChannel } from '#hmr/devChannel';\n\nimport { RuntimeBrand, TransportBrand } from './brands';\nimport { resolveLifecycleSpec } from './lifecycle';\n\nimport type { CoreBase } from '#interfaces/CoreBase';\nimport type { ScopedSpec } from './brands';\nimport type { ResolvedPluginLifecycleSpec, PluginLifecycleSpec } from './lifecycle';\nimport type {\n    DeclaredScope,\n    TransportOf,\n    PluginOptions,\n    PluginSpecArgs,\n    RuntimeOf,\n    ScopeAxis,\n    Runtime,\n    RuntimeAssert,\n    Transport,\n    TransportAssert\n} from './options';\nimport type { Tail, FrameworkChannel, HmrAware, HmrUpdateEvent } from '@seedcord/types';\n\nexport interface Initializeable {\n    init(): Promise<void>;\n}\n\n/** @internal */\nconst resolvedSpecSlot = Symbol('seedcord:plugin:spec');\n/** @internal */\nconst loggerSlot = Symbol('seedcord:plugin:logger');\n/** @internal */\nconst scopeSlot = Symbol('seedcord:plugin:scope');\n/** @internal */\nexport const FixedScope = Symbol('seedcord:plugin:fixed-scope');\n\n/**\n * Base class for a seedcord plugin. Extend it and implement `init()`. `this.core` is the running\n * bot.\n *\n * Your constructor takes the host first and passes it to `super()`. Add your own parameters after\n * it. `attach()` types them at the call site.\n *\n * A plugin that narrows `transport` or `runtime` in `Opts` passes the same values to `super()`.\n * `attach()` throws when either one differs from the bot's.\n *\n * @typeParam Opts - Where this plugin may attach.\n * @typeParam TCore - The `Core` each transport binds `this.core` to.\n * @typeParam Fixed - The `transport` and `runtime` values a transport's own `Plugin` base sets. Leave it out.\n *\n * @example\n * ```ts\n * class Analytics extends Plugin<{ transport: 'gateway' }> {\n *     constructor(\n *         host: CoreBase,\n *         private readonly apiKey: string\n *     ) {\n *         super(host, { transport: 'gateway', init: { phase: StartupPhase.Login } });\n *     }\n *\n *     public async init(): Promise<void> {\n *         await this.connect(this.apiKey);\n *     }\n * }\n *\n * seedcord.attach('analytics', Analytics, apiKey);\n * ```\n */\nexport abstract class Plugin<\n    Opts extends PluginOptions = {},\n    TCore extends CoreBase = CoreBase,\n    Fixed extends ScopeAxis = never\n>\n    implements Initializeable, HmrAware\n{\n    /** @internal */\n    protected static readonly [FixedScope]: Partial<DeclaredScope> = {};\n\n    // phantom, never set at runtime.\n    /** @internal */\n    declare readonly [TransportBrand]?: TransportOf<Opts>;\n    /** @internal */\n    declare readonly [RuntimeBrand]?: RuntimeOf<Opts>;\n\n    /** @internal */\n    readonly [resolvedSpecSlot]: ResolvedPluginLifecycleSpec;\n    /** @internal */\n    readonly [loggerSlot]: Logger;\n    /** @internal */\n    readonly [scopeSlot]: DeclaredScope;\n\n    /** Logs under the plugin's class name, on the channel its attach key sets. */\n    protected readonly logger: Logger;\n\n    // CoreBase here keeps the augmented Core out of ConstructorParameters, which attach reads\n    constructor(\n        private readonly host: CoreBase,\n        ...[spec]: PluginSpecArgs<Opts, Fixed>\n    ) {\n        this.logger = new Logger(this.constructor.name);\n        this[loggerSlot] = this.logger;\n        this[resolvedSpecSlot] = resolveLifecycleSpec(spec, this.constructor.name);\n\n        const passed: (PluginLifecycleSpec & Partial<DeclaredScope>) | undefined = spec;\n        const fixed = new.target[FixedScope];\n        this[scopeSlot] = {\n            transport: fixed.transport ?? passed?.transport ?? 'any',\n            runtime: fixed.runtime ?? passed?.runtime ?? 'any'\n        };\n    }\n\n    /** The host, typed to the transport whose `Plugin` base this class extends. */\n    protected get core(): TCore {\n        // justified: each transport binds TCore to the Core its own host satisfies\n        return this.host as TCore;\n    }\n\n    /**\n     * Runs in `StartupPhase.Configuration` by default.\n     * Move it to a different phase with the {@link PluginLifecycleSpec}.\n     */\n    abstract init(): Promise<void>;\n\n    /**\n     * Runs in the Ready phase, after every attached plugin's `init()` has resolved. The other Ready\n     * tasks run alongside it, including the http server binding its port.\n     *\n     * Override it when your work needs a logged-in client or a resolved application id.\n     */\n    ready?(): Promise<void>;\n\n    /**\n     * Runs during teardown, in `ShutdownPhase.Disconnect` by default. seedcord skips it when `init()`\n     * has thrown.\n     *\n     * When `init()` outlasts its timeout, seedcord calls this once that `init()` resolves, outside any\n     * shutdown phase. The process must still be alive for that call to happen.\n     */\n    dispose?(): Promise<void>;\n\n    /**\n     * Rejects the options this plugin got.\n     *\n     * @param reason - Why the options are invalid.\n     * @throws A **SeedcordTypeError** every time, with the plugin class name and `reason` in its message.\n     */\n    protected rejectOptions(reason: string): never {\n        throw new SeedcordTypeError(SeedcordErrorCode.PluginOptionsRejected, [this.constructor.name, reason]);\n    }\n\n    /** Override to reload plugin state on an HMR update. */\n    public onHmr(_event: HmrUpdateEvent): Promise<void> {\n        return Promise.resolve();\n    }\n\n    /**\n     * Registers critical file patterns that should trigger a full restart when changed in Dev HMR.\n     * @param patterns - Glob patterns. A relative one resolves against `root` from `seedcord.config.ts`.\n     */\n    protected registerCriticalFiles(patterns: string[]): void {\n        getDevChannel()?.send('seedcord:register-critical-files', { patterns });\n    }\n}\n\n/** @internal */\nexport function resolvedLifecycleSpecOf(plugin: PluginLike): ResolvedPluginLifecycleSpec {\n    return plugin[resolvedSpecSlot];\n}\n\n/** @internal */\nexport function extendsThisCorePlugin(ctor: PluginCtor): boolean {\n    return ctor.prototype instanceof Plugin;\n}\n\n/** @internal */\nexport function pluginLoggerOf(plugin: PluginLike): Logger {\n    return plugin[loggerSlot];\n}\n\n/** @internal */\nexport function declaredScopeOf(plugin: PluginLike): DeclaredScope {\n    return plugin[scopeSlot];\n}\n\nexport type { PluginLifecycleSpec } from './lifecycle';\nexport type { PluginOptions } from './options';\n\n// a bound of Plugin<{}> rejects every plugin that declares an option, since Plugin<A> and Plugin<B>\n// are mutually unassignable. every member here must stay Opts-independent.\n/** @internal */\nexport type PluginLike = Pick<\n    Plugin,\n    'init' | 'ready' | 'dispose' | 'onHmr' | typeof resolvedSpecSlot | typeof loggerSlot | typeof scopeSlot\n>;\n\n// a `CoreBase` first parameter rejects a narrowing ctor on its own, and it also collapses\n// `InstanceType<Ctor>` to `PluginLike` at every attach call. CoreParamAssert checks it instead.\n/** @internal */\nexport type PluginCtor<TPlugin extends PluginLike = PluginLike> = new (...args: any[]) => TPlugin;\n\n/** @internal */\nexport type PluginArgs<Ctor extends PluginCtor> =\n    InheritsScopedConstructor<Ctor> extends true ? [] : Tail<ConstructorParameters<Ctor>>;\n\n// a narrowed plugin with no constructor of its own inherits the base one, whose spec carries ScopedSpec\ntype InheritsScopedConstructor<Ctor extends PluginCtor> =\n    Tail<ConstructorParameters<Ctor>> extends [infer Spec, ...unknown[]]\n        ? typeof ScopedSpec extends keyof Spec\n            ? true\n            : false\n        : false;\n\n/** @internal */\nexport type Attached<Key extends string, Instance> = Key extends `${infer Group}.${infer Leaf}`\n    ? Record<Group, Record<Leaf, Instance>>\n    : Record<Key, Instance>;\n\n// attach writes the key onto the host, so a key like toString would shadow the one on Object.prototype\n// eslint-disable-next-line @typescript-eslint/no-wrapper-object-types -- lint:fix swaps this for `keyof object`, which is never\ntype HostMember<Host> = keyof Host | keyof Object;\n\n// a string argument against an object type renders only as `string is not assignable`\n/** @internal */\nexport type AttachKeyAssert<Key extends string, Host> = Key extends ''\n    ? 'A plugin key needs a name.'\n    : Key extends `${infer Group}.${infer Leaf}`\n      ? Leaf extends `${string}.${string}`\n          ? `'${Key}' has more than one dot. A plugin key takes one dot at most.`\n          : '' extends Group | Leaf\n            ? `'${Key}' has an empty part. Write a group and a plugin name around the dot, like 'services.users'.`\n            : Group extends FrameworkChannel\n              ? `'${Group}' is a channel the framework logs on. Pick another group name.`\n              : Group extends keyof Host\n                ? Host[Group] extends PluginLike\n                    ? `'${Group}' already holds a plugin, so '${Leaf}' cannot nest inside it.`\n                    : Host[Group] extends Record<string, PluginLike>\n                      ? Leaf extends keyof Host[Group]\n                          ? `'${Key}' is already attached.`\n                          : Key\n                      : `'${Group}' is already a member on the bot. Pick another group name.`\n                : Group extends HostMember<Host>\n                  ? `'${Group}' is already a member on the bot. Pick another group name.`\n                  : Key\n      : Key extends FrameworkChannel\n        ? `'${Key}' is a channel the framework logs on. Pick another plugin key.`\n        : Key extends keyof Host\n          ? Host[Key] extends PluginLike\n              ? `'${Key}' is already attached.`\n              : Host[Key] extends Record<string, PluginLike>\n                ? `'${Key}' already holds a group of plugins. Attach this one under a name of its own.`\n                : `'${Key}' is already a member on the bot. Pick another plugin key.`\n          : Key extends HostMember<Host>\n            ? `'${Key}' is already a member on the bot. Pick another plugin key.`\n            : Key;\n\ntype CoreParamTooNarrow = Record<\n    'this plugin constructor must take CoreBase as its first parameter and read the transport Core off this.core',\n    never\n>;\n\n// a narrowed first parameter fails `CoreBase extends Param`\ntype CoreParamAssert<Ctor extends PluginCtor> = CoreBase extends ConstructorParameters<Ctor>[0]\n    ? unknown\n    : CoreParamTooNarrow;\n\ntype ConstructorMissing = Record<\n    \"this plugin narrows its transport or runtime. Give it a constructor that passes them to super(), like super(host, { runtime: 'server' })\",\n    never\n>;\n\ntype OwnConstructorAssert<Ctor extends PluginCtor> =\n    InheritsScopedConstructor<Ctor> extends true ? ConstructorMissing : unknown;\n\ntype AttachAsserts<Ctor extends PluginCtor, BotT extends Transport, BotRt extends Runtime> = TransportAssert<\n    InstanceType<Ctor>,\n    BotT\n> &\n    RuntimeAssert<InstanceType<Ctor>, BotRt> &\n    CoreParamAssert<Ctor> &\n    OwnConstructorAssert<Ctor>;\n\n// typescript can't infer Ctor from a generic class through `Ctor & AttachAsserts`. every assert returns unknown to pass.\n/** @internal */\nexport type AttachableCtor<Ctor extends PluginCtor, BotT extends Transport, BotRt extends Runtime> =\n    unknown extends AttachAsserts<Ctor, BotT, BotRt> ? Ctor : AttachAsserts<Ctor, BotT, BotRt>;\n","import { SeedcordErrorCode } from '@seedcord/errors';\nimport { SeedcordError, SeedcordTypeError } from '@seedcord/errors/internal';\nimport { FRAMEWORK_CHANNELS } from '@seedcord/logger';\nimport { HostPluginKeys } from '@seedcord/types/internal';\n\nimport { declaredScopeOf, extendsThisCorePlugin, pluginLoggerOf, resolvedLifecycleSpecOf } from './Plugin';\n\nimport type { CoreBase } from '#interfaces/CoreBase';\nimport type { Bus } from '#subscribers/Bus';\nimport type { ResolvedPluginLifecycleSpec } from './lifecycle';\nimport type { DeclaredScope, Runtime, Transport } from './options';\nimport type { AttachableCtor, Attached, AttachKeyAssert, PluginArgs, PluginCtor, PluginLike } from './Plugin';\nimport type { REST } from '@discordjs/rest';\nimport type { Config, IRateLimiter } from '@seedcord/types';\n\nexport interface Attachment {\n    readonly key: string;\n    readonly instance: PluginLike;\n    readonly spec: ResolvedPluginLifecycleSpec;\n}\n\nconst RESERVED_KEYS: ReadonlySet<string> = new Set(FRAMEWORK_CHANNELS);\n\nconst attachmentsSlot = Symbol('seedcord:host:attachments');\nconst sealSlot = Symbol('seedcord:host:seal');\n\n/** Base class for a plugin host. */\nexport abstract class PluginHost<BotT extends Transport, BotRt extends Runtime> implements CoreBase {\n    public abstract readonly config: Config;\n    public abstract readonly rest: REST;\n    public abstract readonly applicationId: string;\n    public abstract readonly rateLimiter: IRateLimiter;\n    public abstract readonly bus: Bus;\n\n    #sealed = false;\n    readonly #attachments: Attachment[] = [];\n    readonly #groups = new Map<string, Record<string, PluginLike>>();\n    readonly #scope: { readonly transport: BotT; readonly runtime: BotRt };\n\n    constructor(transport: BotT, runtime: BotRt) {\n        this.#scope = { transport, runtime };\n    }\n\n    /** @internal */\n    public get [attachmentsSlot](): readonly Attachment[] {\n        return this.#attachments;\n    }\n\n    /** @internal */\n    public [sealSlot](): void {\n        this.#sealed = true;\n    }\n\n    /** @internal codegen reads this to emit the `Core` augmentation */\n    public get [HostPluginKeys](): readonly string[] {\n        return this.#attachments.map((attachment) => attachment.key);\n    }\n\n    /**\n     * Attaches a plugin under `key`. Read the instance back as `core[key]`. `seedcord codegen`\n     * writes the `Core` augmentation that types it there.\n     *\n     * Put one dot in the key to nest the plugin under a group. `'services.users'` reads back as\n     * `core.services.users`. Each name holds one plugin or one group.\n     *\n     * Startup runs each plugin's `init()` in attach order within its phase. A node bot starts in\n     * `start()`. An edge bot starts on its first request.\n     *\n     * Attaching a plugin whose `transport` or `runtime` differs from this host fails to compile.\n     * Your constructor takes `CoreBase` as its first parameter (you don't need to pass it though).\n     * A narrower one fails to compile here.\n     *\n     * @param key - Also the channel the plugin logs on, dots included.\n     * @param args - Whatever your constructor takes after the host.\n     * @throws A **SeedcordError** when you attach after the bot has started.\n     * @throws A **SeedcordTypeError** when `key` is taken, reserved, or malformed.\n     * @throws A **SeedcordTypeError** when the plugin extends `Plugin` from another copy of `@seedcord/core`.\n     * @throws A **SeedcordTypeError** when the plugin's `transport` or `runtime` differs from this host and the types were bypassed.\n     * @example\n     * ```ts\n     * seedcord.attach('db', Mongoose, { uri: 'mongodb://...', name: 'seedcord', dir: ... });\n     * ```\n     */\n    public attach<Key extends string, Ctor extends PluginCtor>(\n        this: this,\n        key: AttachKeyAssert<Key, this>,\n        Plugin: AttachableCtor<Ctor, BotT, BotRt>,\n        ...args: PluginArgs<Ctor>\n    ): this & Attached<Key, InstanceType<Ctor>>;\n    public attach<Key extends string, Ctor extends PluginCtor>(\n        this: this,\n        key: Key,\n        Plugin: Ctor,\n        ...args: PluginArgs<Ctor>\n    ): this & Attached<Key, InstanceType<Ctor>> {\n        if (this.#sealed) {\n            throw new SeedcordError(SeedcordErrorCode.CorePluginAfterInit);\n        }\n\n        const dot = key.indexOf('.');\n        const head = dot === -1 ? key : key.slice(0, dot);\n\n        // runs before assertFree because some reserved channels are also host members\n        if (RESERVED_KEYS.has(head)) {\n            throw new SeedcordTypeError(SeedcordErrorCode.CorePluginReservedChannel, [head]);\n        }\n\n        const leaf = dot === -1 ? undefined : key.slice(dot + 1);\n        if (head === '' || leaf === '') {\n            throw new SeedcordTypeError(SeedcordErrorCode.CorePluginKeyMalformed, [key, 'has an empty part.']);\n        }\n        if (leaf?.includes('.')) {\n            throw new SeedcordTypeError(SeedcordErrorCode.CorePluginKeyMalformed, [key, 'has more than one dot.']);\n        }\n        this.#assertFree(head, leaf, key);\n\n        if (!extendsThisCorePlugin(Plugin)) {\n            throw new SeedcordTypeError(SeedcordErrorCode.CorePluginFromOtherCore, [Plugin.name]);\n        }\n\n        const instance = new Plugin(this, ...args);\n        this.#assertScope(Plugin.name, declaredScopeOf(instance));\n        pluginLoggerOf(instance).setChannel(key);\n        this.#attachments.push({ key, instance, spec: resolvedLifecycleSpecOf(instance) });\n\n        if (leaf === undefined) {\n            return Object.assign(this, { [key]: instance }) as this & Attached<Key, InstanceType<Ctor>>;\n        }\n\n        this.#groupFor(head)[leaf] = instance;\n        return this as this & Attached<Key, InstanceType<Ctor>>;\n    }\n\n    #assertFree(head: string, leaf: string | undefined, key: string): void {\n        if (leaf === undefined) {\n            if (this.#groups.has(key)) throw new SeedcordTypeError(SeedcordErrorCode.CorePluginKeyHoldsGroup, [key]);\n            if (key in this) throw new SeedcordTypeError(SeedcordErrorCode.CorePluginKeyExists, [key]);\n            return;\n        }\n\n        const group = this.#groups.get(head);\n        if (!group) {\n            if (head in this) throw new SeedcordTypeError(SeedcordErrorCode.CorePluginGroupTaken, [head, key]);\n            return;\n        }\n        if (Object.hasOwn(group, leaf)) throw new SeedcordTypeError(SeedcordErrorCode.CorePluginKeyExists, [key]);\n    }\n\n    // the types already reject a mismatch. plain JS and casts reach this.\n    #assertScope(pluginName: string, declared: DeclaredScope): void {\n        for (const axis of ['transport', 'runtime'] as const) {\n            const host = this.#scope[axis];\n            if (declared[axis] === 'any' || declared[axis] === host) continue;\n            throw new SeedcordTypeError(SeedcordErrorCode.CorePluginScopeMismatch, [\n                pluginName,\n                axis,\n                declared[axis],\n                host\n            ]);\n        }\n    }\n\n    #groupFor(head: string): Record<string, PluginLike> {\n        const existing = this.#groups.get(head);\n        if (existing) return existing;\n\n        // a null prototype makes a leaf called __proto__ or valueOf an ordinary key\n        const group = Object.create(null) as Record<string, PluginLike>;\n        this.#groups.set(head, group);\n        Object.assign(this, { [head]: group });\n        return group;\n    }\n}\n\nexport function attachmentsOf(\n    host: Pick<PluginHost<Transport, Runtime>, typeof attachmentsSlot>\n): readonly Attachment[] {\n    return host[attachmentsSlot];\n}\n\nexport function sealAttachments(host: Pick<PluginHost<Transport, Runtime>, typeof sealSlot>): void {\n    host[sealSlot]();\n}\n"],"mappings":"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"}

package/dist/{Plugin-Dhx_ivqj.d.mts → PluginHost-DB4j8unu.d.mts}

@@ -1,9 +1,12 @@
-import { n as StartupPhase, r as CoreBase, t as ShutdownPhase } from "./phases-D_zQBXga.mjs";
+import { i as Bus, n as StartupPhase, r as CoreBase, t as ShutdownPhase } from "./phases-FTM69J3a.mjs";
 import { Logger } from "@seedcord/logger";
-import { FrameworkChannel, HmrAware, HmrUpdateEvent, Tail, TypedExclude } from "@seedcord/types";
+import { REST } from "@discordjs/rest";
+import { HostPluginKeys } from "@seedcord/types/internal";
+import { Config, FrameworkChannel, HmrAware, HmrUpdateEvent, IRateLimiter, Tail, TypedExclude } from "@seedcord/types";
 //#region src/plugin/brands.d.ts
 declare const TransportBrand: unique symbol;
 declare const RuntimeBrand: unique symbol;
+declare const ScopedSpec: unique symbol;
 //#endregion
 //#region src/plugin/lifecycle.d.ts
 /**
@@ -53,13 +56,17 @@ interface ResolvedPluginLifecycleSpec {
 //#endregion
 //#region src/plugin/options.d.ts
 /**
- * Declares where a plugin may attach. Pass it as the `Plugin<Opts>` type argument. `attach()` fails
- * to compile when the host does not match.
+ * Declares where a plugin may attach. Pass it as the `Plugin<Opts>` type argument. Every field you
+ * narrow goes to `super()` as well. `attach()` fails to compile when the host does not match.
  *
  * @example
  * ```ts
  * // attaching this to an http bot fails to compile
  * class Voice extends Plugin<{ transport: 'gateway' }> {
+ *     constructor(host: CoreBase) {
+ *         super(host, { transport: 'gateway' });
+ *     }
+ *
  *     public async init(): Promise<void> {}
  * }
  * ```
@@ -84,9 +91,26 @@ type RuntimeOf<Opts extends PluginOptions> = undefined extends Opts['runtime'] ?
 type Transport = TypedExclude<NonNullable<PluginOptions['transport']>, 'any'>;
 /** @internal */
 type Runtime = TypedExclude<NonNullable<PluginOptions['runtime']>, 'any'>;
+/** @internal */
+interface DeclaredScope {
+  readonly transport: Transport | 'any';
+  readonly runtime: Runtime | 'any';
+}
+/** @internal */
+type ScopeAxis = keyof DeclaredScope;
+type NarrowedTransport<Opts extends PluginOptions> = TransportOf<Opts> extends 'any' ? unknown : {
+  transport: TransportOf<Opts>;
+};
+type NarrowedRuntime<Opts extends PluginOptions> = RuntimeOf<Opts> extends 'any' ? unknown : {
+  runtime: RuntimeOf<Opts>;
+};
+type ScopeToPass<Opts extends PluginOptions, Fixed extends ScopeAxis> = ('transport' extends Fixed ? unknown : NarrowedTransport<Opts>) & ('runtime' extends Fixed ? unknown : NarrowedRuntime<Opts>);
+/** @internal */
+type PluginSpecArgs<Opts extends PluginOptions, Fixed extends ScopeAxis> = unknown extends ScopeToPass<Opts, Fixed> ? [spec?: PluginLifecycleSpec] : [spec: PluginLifecycleSpec & ScopeToPass<Opts, Fixed> & {
+  readonly [ScopedSpec]?: never;
+}];
 type TransportMismatch<PluginT extends string, BotT extends string> = Record<`this plugin declares transport '${PluginT}' but this bot runs '${BotT}'`, never>;
 type RuntimeMismatch<PluginRt extends string, BotRt extends string> = Record<`this plugin declares runtime '${PluginRt}' but this bot runs '${BotRt}'`, never>;
-type EdgePluginsUnsupported = Record<'an edge bot takes no plugins until edge support ships after v1', never>;
 type BrandTransport<Plug> = Plug extends {
   readonly [TransportBrand]?: infer T extends string;
 } ? T : 'any';
@@ -96,7 +120,7 @@ type BrandRuntime<Plug> = Plug extends {
 /** @internal */
 type TransportAssert<Plug, BotT extends Transport> = BrandTransport<Plug> extends 'any' | BotT ? unknown : TransportMismatch<BrandTransport<Plug>, BotT>;
 /** @internal */
-type RuntimeAssert<Plug, BotRt extends Runtime> = 'edge' extends BotRt ? EdgePluginsUnsupported : BrandRuntime<Plug> extends 'any' | BotRt ? unknown : RuntimeMismatch<BrandRuntime<Plug>, BotRt>;
+type RuntimeAssert<Plug, BotRt extends Runtime> = BrandRuntime<Plug> extends 'any' | BotRt ? unknown : RuntimeMismatch<BrandRuntime<Plug>, BotRt>;
 //#endregion
 //#region src/plugin/Plugin.d.ts
 interface Initializeable {
@@ -106,6 +130,10 @@ interface Initializeable {
 declare const resolvedSpecSlot: unique symbol;
 /** @internal */
 declare const loggerSlot: unique symbol;
+/** @internal */
+declare const scopeSlot: unique symbol;
+/** @internal */
+declare const FixedScope: unique symbol;
 /**
  * Base class for a seedcord plugin. Extend it and implement `init()`. `this.core` is the running
  * bot.
@@ -113,8 +141,12 @@ declare const loggerSlot: unique symbol;
  * Your constructor takes the host first and passes it to `super()`. Add your own parameters after
  * it. `attach()` types them at the call site.
  *
- * @typeParam Opts - Where this plugin may attach, checked only at compile time.
+ * A plugin that narrows `transport` or `runtime` in `Opts` passes the same values to `super()`.
+ * `attach()` throws when either one differs from the bot's.
+ *
+ * @typeParam Opts - Where this plugin may attach.
  * @typeParam TCore - The `Core` each transport binds `this.core` to.
+ * @typeParam Fixed - The `transport` and `runtime` values a transport's own `Plugin` base sets. Leave it out.
  *
  * @example
  * ```ts
@@ -123,7 +155,7 @@ declare const loggerSlot: unique symbol;
  *         host: CoreBase,
  *         private readonly apiKey: string
  *     ) {
- *         super(host, { init: { phase: StartupPhase.Login } });
+ *         super(host, { transport: 'gateway', init: { phase: StartupPhase.Login } });
  *     }
  *
  *     public async init(): Promise<void> {
@@ -134,9 +166,11 @@ declare const loggerSlot: unique symbol;
  * seedcord.attach('analytics', Analytics, apiKey);
  * ```
  */
-declare abstract class Plugin<Opts extends PluginOptions = {}, TCore extends CoreBase = CoreBase> implements Initializeable, HmrAware {
+declare abstract class Plugin<Opts extends PluginOptions = {}, TCore extends CoreBase = CoreBase, Fixed extends ScopeAxis = never> implements Initializeable, HmrAware {
   private readonly host;
   /** @internal */
+  protected static readonly [FixedScope]: Partial<DeclaredScope>;
+  /** @internal */
   readonly [TransportBrand]?: TransportOf<Opts>;
   /** @internal */
   readonly [RuntimeBrand]?: RuntimeOf<Opts>;
@@ -144,9 +178,11 @@ declare abstract class Plugin<Opts extends PluginOptions = {}, TCore extends Cor
   readonly [resolvedSpecSlot]: ResolvedPluginLifecycleSpec;
   /** @internal */
   readonly [loggerSlot]: Logger;
+  /** @internal */
+  readonly [scopeSlot]: DeclaredScope;
   /** Logs under the plugin's class name, on the channel its attach key sets. */
   protected readonly logger: Logger;
-  constructor(host: CoreBase, spec?: PluginLifecycleSpec);
+  constructor(host: CoreBase, ...[spec]: PluginSpecArgs<Opts, Fixed>);
   /** The host, typed to the transport whose `Plugin` base this class extends. */
   protected get core(): TCore;
   /**
@@ -170,25 +206,27 @@ declare abstract class Plugin<Opts extends PluginOptions = {}, TCore extends Cor
    */
   dispose?(): Promise<void>;
   /**
-   * Throws a `SeedcordError` that contains the plugin class name and the reason.
+   * Rejects the options this plugin got.
    *
    * @param reason - Why the options are invalid.
+   * @throws A **SeedcordTypeError** every time, with the plugin class name and `reason` in its message.
    */
   protected rejectOptions(reason: string): never;
   /** Override to reload plugin state on an HMR update. */
   onHmr(_event: HmrUpdateEvent): Promise<void>;
   /**
    * Registers critical file patterns that should trigger a full restart when changed in Dev HMR.
-   * @param patterns - Glob patterns relative to the project root
+   * @param patterns - Glob patterns. A relative one resolves against `root` from `seedcord.config.ts`.
    */
   protected registerCriticalFiles(patterns: string[]): void;
 }
 /** @internal */
-type PluginLike = Pick<Plugin, 'init' | 'ready' | 'dispose' | 'onHmr' | typeof resolvedSpecSlot | typeof loggerSlot>;
+type PluginLike = Pick<Plugin, 'init' | 'ready' | 'dispose' | 'onHmr' | typeof resolvedSpecSlot | typeof loggerSlot | typeof scopeSlot>;
 /** @internal */
 type PluginCtor<TPlugin extends PluginLike = PluginLike> = new (...args: any[]) => TPlugin;
 /** @internal */
-type PluginArgs<Ctor extends PluginCtor> = Tail<ConstructorParameters<Ctor>>;
+type PluginArgs<Ctor extends PluginCtor> = InheritsScopedConstructor<Ctor> extends true ? [] : Tail<ConstructorParameters<Ctor>>;
+type InheritsScopedConstructor<Ctor extends PluginCtor> = Tail<ConstructorParameters<Ctor>> extends [infer Spec, ...unknown[]] ? typeof ScopedSpec extends keyof Spec ? true : false : false;
 /** @internal */
 type Attached<Key extends string, Instance> = Key extends `${infer Group}.${infer Leaf}` ? Record<Group, Record<Leaf, Instance>> : Record<Key, Instance>;
 type HostMember<Host> = keyof Host | keyof Object;
@@ -196,9 +234,64 @@ type HostMember<Host> = keyof Host | keyof Object;
 type AttachKeyAssert<Key extends string, Host> = Key extends '' ? 'A plugin key needs a name.' : Key extends `${infer Group}.${infer Leaf}` ? Leaf extends `${string}.${string}` ? `'${Key}' has more than one dot. A plugin key takes one dot at most.` : '' extends Group | Leaf ? `'${Key}' has an empty part. Write a group and a plugin name around the dot, like 'services.users'.` : Group extends FrameworkChannel ? `'${Group}' is a channel the framework logs on. Pick another group name.` : Group extends keyof Host ? Host[Group] extends PluginLike ? `'${Group}' already holds a plugin, so '${Leaf}' cannot nest inside it.` : Host[Group] extends Record<string, PluginLike> ? Leaf extends keyof Host[Group] ? `'${Key}' is already attached.` : Key : `'${Group}' is already a member on the bot. Pick another group name.` : Group extends HostMember<Host> ? `'${Group}' is already a member on the bot. Pick another group name.` : Key : Key extends FrameworkChannel ? `'${Key}' is a channel the framework logs on. Pick another plugin key.` : Key extends keyof Host ? Host[Key] extends PluginLike ? `'${Key}' is already attached.` : Host[Key] extends Record<string, PluginLike> ? `'${Key}' already holds a group of plugins. Attach this one under a name of its own.` : `'${Key}' is already a member on the bot. Pick another plugin key.` : Key extends HostMember<Host> ? `'${Key}' is already a member on the bot. Pick another plugin key.` : Key;
 type CoreParamTooNarrow = Record<'this plugin constructor must take CoreBase as its first parameter and read the transport Core off this.core', never>;
 type CoreParamAssert<Ctor extends PluginCtor> = CoreBase extends ConstructorParameters<Ctor>[0] ? unknown : CoreParamTooNarrow;
-type AttachAsserts<Ctor extends PluginCtor, BotT extends Transport, BotRt extends Runtime> = TransportAssert<InstanceType<Ctor>, BotT> & RuntimeAssert<InstanceType<Ctor>, BotRt> & CoreParamAssert<Ctor>;
+type ConstructorMissing = Record<"this plugin narrows its transport or runtime. Give it a constructor that passes them to super(), like super(host, { runtime: 'server' })", never>;
+type OwnConstructorAssert<Ctor extends PluginCtor> = InheritsScopedConstructor<Ctor> extends true ? ConstructorMissing : unknown;
+type AttachAsserts<Ctor extends PluginCtor, BotT extends Transport, BotRt extends Runtime> = TransportAssert<InstanceType<Ctor>, BotT> & RuntimeAssert<InstanceType<Ctor>, BotRt> & CoreParamAssert<Ctor> & OwnConstructorAssert<Ctor>;
 /** @internal */
 type AttachableCtor<Ctor extends PluginCtor, BotT extends Transport, BotRt extends Runtime> = unknown extends AttachAsserts<Ctor, BotT, BotRt> ? Ctor : AttachAsserts<Ctor, BotT, BotRt>;
 //#endregion
-export { Plugin as a, PluginLike as c, Transport as d, PluginLifecycleSpec as f, Initializeable as i, PluginOptions as l, AttachableCtor as n, PluginArgs as o, Attached as r, PluginCtor as s, AttachKeyAssert as t, Runtime as u };
-//# sourceMappingURL=Plugin-Dhx_ivqj.d.mts.map
+//#region src/plugin/PluginHost.d.ts
+interface Attachment {
+  readonly key: string;
+  readonly instance: PluginLike;
+  readonly spec: ResolvedPluginLifecycleSpec;
+}
+declare const attachmentsSlot: unique symbol;
+declare const sealSlot: unique symbol;
+/** Base class for a plugin host. */
+declare abstract class PluginHost<BotT extends Transport, BotRt extends Runtime> implements CoreBase {
+  #private;
+  abstract readonly config: Config;
+  abstract readonly rest: REST;
+  abstract readonly applicationId: string;
+  abstract readonly rateLimiter: IRateLimiter;
+  abstract readonly bus: Bus;
+  constructor(transport: BotT, runtime: BotRt);
+  /** @internal */
+  get [attachmentsSlot](): readonly Attachment[];
+  /** @internal */
+  [sealSlot](): void;
+  /** @internal codegen reads this to emit the `Core` augmentation */
+  get [HostPluginKeys](): readonly string[];
+  /**
+   * Attaches a plugin under `key`. Read the instance back as `core[key]`. `seedcord codegen`
+   * writes the `Core` augmentation that types it there.
+   *
+   * Put one dot in the key to nest the plugin under a group. `'services.users'` reads back as
+   * `core.services.users`. Each name holds one plugin or one group.
+   *
+   * Startup runs each plugin's `init()` in attach order within its phase. A node bot starts in
+   * `start()`. An edge bot starts on its first request.
+   *
+   * Attaching a plugin whose `transport` or `runtime` differs from this host fails to compile.
+   * Your constructor takes `CoreBase` as its first parameter (you don't need to pass it though).
+   * A narrower one fails to compile here.
+   *
+   * @param key - Also the channel the plugin logs on, dots included.
+   * @param args - Whatever your constructor takes after the host.
+   * @throws A **SeedcordError** when you attach after the bot has started.
+   * @throws A **SeedcordTypeError** when `key` is taken, reserved, or malformed.
+   * @throws A **SeedcordTypeError** when the plugin extends `Plugin` from another copy of `@seedcord/core`.
+   * @throws A **SeedcordTypeError** when the plugin's `transport` or `runtime` differs from this host and the types were bypassed.
+   * @example
+   * ```ts
+   * seedcord.attach('db', Mongoose, { uri: 'mongodb://...', name: 'seedcord', dir: ... });
+   * ```
+   */
+  attach<Key extends string, Ctor extends PluginCtor>(this: this, key: AttachKeyAssert<Key, this>, Plugin: AttachableCtor<Ctor, BotT, BotRt>, ...args: PluginArgs<Ctor>): this & Attached<Key, InstanceType<Ctor>>;
+}
+declare function attachmentsOf(host: Pick<PluginHost<Transport, Runtime>, typeof attachmentsSlot>): readonly Attachment[];
+declare function sealAttachments(host: Pick<PluginHost<Transport, Runtime>, typeof sealSlot>): void;
+//#endregion
+export { FixedScope as a, PluginArgs as c, Transport as d, PluginLifecycleSpec as f, sealAttachments as i, PluginCtor as l, PluginHost as n, Initializeable as o, attachmentsOf as r, Plugin as s, Attachment as t, PluginOptions as u };
+//# sourceMappingURL=PluginHost-DB4j8unu.d.mts.map