@capybara-hq/kernel 0.0.0-stage → 0.1.0-rc.1

package/dist/extensions/instance.js

@@ -0,0 +1,329 @@
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { defineExtension, ExtensionManifestError, staticManifestOf, } from "@capybara-hq/plugin-sdk";
+import { createExtensionContext, LiveConfig, } from "../ctx/create-ctx.js";
+import { InflightTracker } from "./inflight.js";
+const errMsg = (e) => (e instanceof Error ? e.message : String(e));
+/** 模块清单与审阅过的静态清单（包内 `capybara.manifest`）不一致。 */
+export class ManifestMismatchError extends Error {
+    constructor(plugin, moduleName) {
+        super(`plugin ${plugin}: the plugin module's manifest does not match the reviewed package manifest (module name "${moduleName}")`);
+        this.name = "ManifestMismatchError";
+    }
+}
+/** 键排序 JSON（jsonb 会重排对象键；比较静态清单用）。 */
+const canonical = (v) => {
+    if (Array.isArray(v))
+        return `[${v.map((x) => (x === undefined ? "null" : canonical(x))).join(",")}]`;
+    if (v !== null && typeof v === "object") {
+        const entries = Object.entries(v)
+            .filter(([, x]) => x !== undefined)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+        return `{${entries.map(([k, x]) => `${JSON.stringify(k)}:${canonical(x)}`).join(",")}}`;
+    }
+    return JSON.stringify(v) ?? "null";
+};
+/** 模块清单与审阅过的静态清单是否一致（名字与 {@link staticManifestOf} 都须相同）。 */
+export function matchesSection(manifest, name, section) {
+    return manifest.name === name && canonical(staticManifestOf(manifest)) === canonical(section);
+}
+/** 导入一个插件模块（default 导出）并按 defineExtension 校验清单。 */
+export async function importExtensionModule(url, label, resolveFrom) {
+    let mod;
+    try {
+        mod = (await import(url));
+    }
+    catch (e) {
+        throw new Error(`cannot import plugin "${label}" from "${resolveFrom}": ${errMsg(e)}`, {
+            cause: e,
+        });
+    }
+    if (typeof mod.default !== "object" || mod.default === null)
+        throw new Error(`plugin module "${label}" has no default export object`);
+    try {
+        return defineExtension(mod.default);
+    }
+    catch (e) {
+        throw new ExtensionManifestError(label, errMsg(e));
+    }
+}
+/**
+ * 一个已完成 setup 的插件实例（一代）：清单、来源、权限、部署配置，以及它经 ctx 做过的全部登记（账）。
+ * 同一插件升级 / 重新加载会产生新实例（generation 加一），旧实例 `dispose` 后它的登记全部撤销；
+ * 旧模块代码留在内存里直到进程重启（ESM 无法卸载）。
+ */
+export class ExtensionInstance {
+    name;
+    version;
+    sha256;
+    source;
+    generation;
+    manifest;
+    permissions;
+    hash;
+    live;
+    entryUrl;
+    inflight;
+    ctx;
+    log;
+    disposing;
+    /** {@link hurry}：进行中的 dispose 不再等排空时限。 */
+    hurried = new AbortController();
+    constructor(init) {
+        this.manifest = init.manifest;
+        this.name = init.manifest.name;
+        this.version = init.manifest.version;
+        this.sha256 = init.sha256;
+        this.source = init.source;
+        this.generation = init.generation;
+        this.permissions = init.permissions;
+        this.hash = init.configHash;
+        this.live = init.config;
+        this.entryUrl = init.entryUrl;
+        this.ctx = init.ctx;
+        this.log = init.log;
+        this.inflight = new InflightTracker(this.name);
+    }
+    /** 此刻的部署配置（hot 改动后是新值）。 */
+    get config() {
+        return this.live.value;
+    }
+    /** 部署配置摘要（见 `deploymentConfigHash`；hot 改动后随之更新）。 */
+    get configHash() {
+        return this.hash;
+    }
+    /** hot 字段改动：就地替换部署配置（插件下次读 `ctx.config` 拿到新值），不重新 setup（C10）。 */
+    updateConfig(config, configHash) {
+        this.live.value = config;
+        this.hash = configHash;
+    }
+    /** 提供的能力（撤销后为空）。 */
+    get provided() {
+        return this.ctx.provided;
+    }
+    get routes() {
+        return this.ctx.routes;
+    }
+    get tools() {
+        return this.ctx.registeredTools;
+    }
+    /** Hooks registered through `ctx.hooks.on` (empty after revocation). */
+    get hooks() {
+        return this.ctx.registeredHooks;
+    }
+    get uiViews() {
+        return this.ctx.uiViews;
+    }
+    get uiActions() {
+        return this.ctx.uiActions;
+    }
+    /** 账上仍在的登记（撤销后为空）。 */
+    registrations() {
+        return this.ctx.ledger.list();
+    }
+    get disposed() {
+        return this.disposing !== undefined;
+    }
+    /**
+     * Revokes this instance (idempotent; the caller should first remove it from the registry or replace
+     * it). In order:
+     * 1. stop taking new work (in-flight tracker closed, queue workers stop taking new jobs);
+     * 2. wait for in-flight tool calls and running queue worker jobs together, up to `drainMs` (one
+     *    deadline);
+     * 3. abort: remaining in-flight calls end with `ExtensionUnloadedError` (the model gets
+     *    `PLUGIN_UNLOADED_TOOL_ERROR`), `ctx.signal` aborts (so work that honours `ctx.signal` is not
+     *    aborted within the drain limit);
+     * 4. revoke the ledger's registrations one by one (in reverse; queue jobs still running at the
+     *    deadline are forced to stay in the queue);
+     * 5. call the extension's `dispose(ctx)`, up to `disposeTimeoutMs` (a throw or timeout is only
+     *    logged, and it goes on);
+     * 6. close the ctx (queue connections, pending audit writes). Step 6 throws on failure (the caller
+     *    logs it).
+     * `waitQueueJobs` (shutdown path): queue workers wait for running jobs to finish instead of being
+     * force-closed at the deadline.
+     */
+    dispose(opts) {
+        this.disposing ??= this.doDispose(opts);
+        return this.disposing;
+    }
+    /**
+     * 让进行中（或之后开始）的 {@link dispose} 立即结束排空：余下的在途调用随即中止，队列任务按到时处理
+     * （停机时宿主对后台撤销中的旧实例调用）。没有在撤销时等同于以排空时限 0 撤销。
+     */
+    hurry() {
+        this.hurried.abort();
+        this.inflight.abort();
+        return this.dispose({ drainMs: 0 });
+    }
+    async doDispose(opts) {
+        const deadline = Date.now() + Math.max(0, opts.drainMs);
+        this.inflight.close();
+        let queues = Promise.resolve("drained");
+        if (!opts.waitQueueJobs) {
+            await this.ctx.beginDispose(deadline).catch((err) => {
+                this.log.warn("plugin queue pause failed", { plugin: this.name, err });
+            });
+            queues = this.ctx.drainQueues(deadline).catch(() => "timeout");
+        }
+        let onHurry = () => { };
+        const hurried = new Promise((resolve) => {
+            onHurry = () => resolve("timeout");
+            if (this.hurried.signal.aborted)
+                onHurry();
+            else
+                this.hurried.signal.addEventListener("abort", onHurry, { once: true });
+        });
+        const [calls, jobs] = await Promise.all([
+            Promise.race([this.inflight.drain(Math.max(0, deadline - Date.now())), hurried]),
+            Promise.race([queues, hurried]),
+        ]);
+        this.hurried.signal.removeEventListener("abort", onHurry);
+        if (jobs === "timeout") {
+            this.log.warn("plugin queue jobs still running after the drain timeout; leaving them queued", {
+                plugin: this.name,
+                generation: this.generation,
+                drainMs: opts.drainMs,
+            });
+        }
+        const drained = calls;
+        if (drained === "timeout") {
+            this.log.warn("plugin calls still running after the drain timeout; aborting them", {
+                plugin: this.name,
+                generation: this.generation,
+                inflight: this.inflight.size,
+                drainMs: opts.drainMs,
+            });
+        }
+        this.inflight.abort();
+        this.ctx.abort();
+        this.ctx.ledger.seal();
+        await this.ctx.ledger.disposeAll((r, err) => this.log.warn("plugin registration dispose failed", {
+            plugin: this.name,
+            kind: r.kind,
+            key: r.key,
+            err,
+        }));
+        if (this.manifest.dispose) {
+            const dispose = this.manifest.dispose;
+            const ms = opts.disposeTimeoutMs ?? DEFAULT_DISPOSE_TIMEOUT_MS;
+            let timer;
+            try {
+                const r = await Promise.race([
+                    Promise.resolve()
+                        .then(() => dispose(this.ctx))
+                        .then(() => "done"),
+                    new Promise((resolve) => {
+                        timer = setTimeout(() => resolve("timeout"), ms);
+                    }),
+                ]);
+                if (r === "timeout") {
+                    this.log.warn("plugin dispose() did not finish in time; continuing without it", {
+                        plugin: this.name,
+                        generation: this.generation,
+                        timeoutMs: ms,
+                    });
+                }
+            }
+            catch (err) {
+                this.log.warn("plugin dispose() failed", { plugin: this.name, err });
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        }
+        await this.ctx.close();
+    }
+}
+/** 插件 `dispose()` 的默认时限（`extensionHost.disposeTimeoutSeconds` 的默认值）。 */
+export const DEFAULT_DISPOSE_TIMEOUT_MS = 10_000;
+/** 同进程导入过的插件模块数超过多少（每个插件第一个入口不算）就告警。 */
+export const UPGRADE_WARN_THRESHOLD = 20;
+/**
+ * 记录本进程导入过的插件模块入口（按插件名去重的 URL）：ESM 模块无法卸载，每个新入口（升级到新包）
+ * 的代码都留在内存里直到进程重启。同一 URL 的重新加载不新增模块，不计数。
+ * 升级数 = 各插件「不同入口数 - 1」之和；第一次超过 {@link UPGRADE_WARN_THRESHOLD} 时 `record` 返回 true（只一次）。
+ */
+export class ImportTracker {
+    urls = new Map();
+    warned = false;
+    /** 本进程的升级数（见类注释）。 */
+    get upgrades() {
+        let n = 0;
+        for (const set of this.urls.values())
+            n += set.size - 1;
+        return n;
+    }
+    /** 记一次导入；返回这次是否应当告警。 */
+    record(plugin, url) {
+        let set = this.urls.get(plugin);
+        if (!set) {
+            set = new Set();
+            this.urls.set(plugin, set);
+        }
+        set.add(url);
+        if (!this.warned && this.upgrades > UPGRADE_WARN_THRESHOLD) {
+            this.warned = true;
+            return true;
+        }
+        return false;
+    }
+}
+/** 升级次数超过阈值的告警（旧模块代码留在内存直到重启）。 */
+export function warnUpgrades(log, imports) {
+    log.warn("plugins were upgraded many times in this process; the code of earlier plugin versions stays in memory until the process restarts, so restart this replica to free it", { upgrades: imports.upgrades, threshold: UPGRADE_WARN_THRESHOLD });
+}
+/** 在已导入、已核对的清单上建 ctx（记账）并 setup；setup 抛错时撤销已登记的再抛。 */
+export async function setupInstance(deps, manifest, input) {
+    const live = new LiveConfig(input.config);
+    const ctx = createExtensionContext(deps.kernel, manifest, live, deps.extensionPointAccess);
+    input.onCtx?.(ctx);
+    try {
+        await manifest.setup(ctx);
+        ctx.sealTools();
+        for (const cap of manifest.provides) {
+            if (!ctx.provided.has(cap)) {
+                throw new Error(`declared extension point ${cap} was not provided by setup`);
+            }
+        }
+    }
+    catch (e) {
+        try {
+            await ctx.close();
+        }
+        catch (err) {
+            deps.kernel.log.warn("plugin context close failed", { plugin: manifest.name, err });
+        }
+        throw new Error(`plugin ${manifest.name}: setup failed: ${errMsg(e)}`, { cause: e });
+    }
+    finally {
+        input.onCtx?.(undefined);
+    }
+    return new ExtensionInstance({
+        manifest,
+        source: input.source,
+        sha256: input.sha256,
+        generation: deps.nextGeneration(manifest.name),
+        permissions: input.permissions,
+        configHash: input.configHash,
+        config: live,
+        entryUrl: input.entryUrl,
+        ctx,
+        log: deps.kernel.log,
+    });
+}
+/**
+ * 加载一个插件实例：import → defineExtension → 有包内静态清单（`section`）时与 {@link staticManifestOf} 核对
+ * （名字与静态清单都须一致，否则抛 {@link ManifestMismatchError}；配置声明 / 内置插件没有 section，跳过核对）
+ * → 建 ctx（记账）→ setup；setup 抛错时撤销已登记的再抛。
+ * 不做权限闸门、部署配置校验与迁移（宿主在此之前完成）；`config` 为已校验的部署配置。
+ */
+export async function loadInstance(deps, input) {
+    const label = input.section?.name ?? input.entryUrl;
+    const manifest = await importExtensionModule(input.entryUrl, label, dirname(fileURLToPath(input.entryUrl)));
+    if (input.section && !matchesSection(manifest, input.section.name, input.section.manifest)) {
+        throw new ManifestMismatchError(input.section.name, manifest.name);
+    }
+    if (deps.imports?.record(manifest.name, input.entryUrl))
+        warnUpgrades(deps.kernel.log, deps.imports);
+    return setupInstance(deps, manifest, input);
+}

package/dist/extensions/ledger.d.ts

@@ -0,0 +1,30 @@
+/** 插件经 ctx 做的一项登记的种类（C17）。 */
+export type RegistrationKind = "tool" | "route" | "queue" | "bus" | "lease" | "ui.view" | "ui.action" | "provide" | "hook";
+/** 账上的一项：撤销时调用 `dispose()`。 */
+export interface Registration {
+    kind: RegistrationKind;
+    key: string;
+    dispose(): Promise<void>;
+}
+/**
+ * 一个插件实例的登记账（每个 ctx 一本）：ctx 的每次登记都记一笔，撤销实例时逐项（倒序）撤销。
+ * 封账（`seal()`，实例开始撤销 / ctx 关闭）之后再登记：立即撤销这一项并抛错，不留下无人管的资源。
+ */
+export declare class RegistrationLedger {
+    private readonly plugin;
+    private items;
+    private closed;
+    constructor(plugin: string);
+    /**
+     * 记一笔，返回「销账」函数（插件自己撤销时调用，如退订、释放锁；只从账上拿掉，不再调用 dispose）。
+     * 已封账时先撤销这一项再抛错。
+     */
+    add(r: Registration): () => void;
+    /** 当前账上的登记（按登记顺序，副本）。 */
+    list(): Registration[];
+    get sealed(): boolean;
+    /** 封账：此后的登记立即撤销并抛错。 */
+    seal(): void;
+    /** 封账并按登记的倒序逐项撤销；单项失败交给 `onError`，继续其余各项。 */
+    disposeAll(onError: (r: Registration, e: unknown) => void): Promise<void>;
+}

package/dist/extensions/ledger.js

@@ -0,0 +1,50 @@
+/**
+ * 一个插件实例的登记账（每个 ctx 一本）：ctx 的每次登记都记一笔，撤销实例时逐项（倒序）撤销。
+ * 封账（`seal()`，实例开始撤销 / ctx 关闭）之后再登记：立即撤销这一项并抛错，不留下无人管的资源。
+ */
+export class RegistrationLedger {
+    plugin;
+    items = [];
+    closed = false;
+    constructor(plugin) {
+        this.plugin = plugin;
+    }
+    /**
+     * 记一笔，返回「销账」函数（插件自己撤销时调用，如退订、释放锁；只从账上拿掉，不再调用 dispose）。
+     * 已封账时先撤销这一项再抛错。
+     */
+    add(r) {
+        if (this.closed) {
+            void r.dispose().catch(() => { });
+            throw new Error(`plugin ${this.plugin}: the plugin instance is unloaded; ${r.kind} "${r.key}" cannot be registered`);
+        }
+        this.items.push(r);
+        return () => {
+            this.items = this.items.filter((x) => x !== r);
+        };
+    }
+    /** 当前账上的登记（按登记顺序，副本）。 */
+    list() {
+        return [...this.items];
+    }
+    get sealed() {
+        return this.closed;
+    }
+    /** 封账：此后的登记立即撤销并抛错。 */
+    seal() {
+        this.closed = true;
+    }
+    /** 封账并按登记的倒序逐项撤销；单项失败交给 `onError`，继续其余各项。 */
+    async disposeAll(onError) {
+        this.seal();
+        while (this.items.length > 0) {
+            const r = this.items.pop();
+            try {
+                await r.dispose();
+            }
+            catch (e) {
+                onError(r, e);
+            }
+        }
+    }
+}

package/dist/extensions/lifecycle.d.ts

@@ -0,0 +1,80 @@
+import type { Logger } from "@capybara-hq/plugin-sdk";
+import type { ExtensionInstance } from "./instance.js";
+import { PLUGINS_MIGRATED_TOPIC } from "./migrate-lock.js";
+import type { ReplicaStatusStore } from "./sources.js";
+/**
+ * 插件期望状态 / 快照变了（kernel bus 主题，频道 `cap:kernel:plugins.changed`，payload `{ plugin }`）。
+ * 后台、CLI 写完 PG 后发布；各副本据此 reconcile，并作废路由闸门的名字缓存。
+ */
+export declare const PLUGINS_CHANGED_TOPIC = "plugins.changed";
+/** 周期兜底（kernel bus 主题 `plugins.reconcile`，payload `{}`）：维护任务 `plugins-reconcile` 发布。 */
+export declare const PLUGINS_RECONCILE_TOPIC = "plugins.reconcile";
+export { PLUGINS_MIGRATED_TOPIC };
+/** 维护任务：每 `extensionHost.reconcileIntervalSeconds` 秒发布一次 `plugins.reconcile`（任务名与 scheduler id 不含 `:`）。 */
+export declare const PLUGINS_RECONCILE_JOB = "plugins-reconcile";
+export declare const PLUGINS_RECONCILE_SCHEDULER_ID = "plugins-reconcile-every";
+/** 副本行心跳超过这么多个 reconcile 周期的副本不计入（C16；读状态的一方据此筛选）。 */
+export declare const STALE_RECONCILE_PERIODS = 3;
+/** The host operations {@link ExtensionLifecycle} needs. */
+export interface LifecycleHost {
+    /** Converges this replica to the deployment's desired state (serialized; see `ExtensionHost.converge`). */
+    converge(): Promise<void>;
+    /** 用同一个包重新 setup（配置的非 hot 改动、依赖方联动）。 */
+    reload(name: string): Promise<ExtensionInstance>;
+    /**
+     * 部署配置保存后本副本重读并校验（hot 就地替换、非 hot 重新加载、不合法保持当前值）；
+     * 插件此刻没在本副本生效时返回 `not_loaded`（待配置的由随后的 reconcile 加载）。
+     */
+    applyDeploymentConfig(name: string): Promise<string>;
+    /** 在本副本生效、声明了部署级配置的插件（周期 reconcile 据此补上丢了消息的配置改动）。 */
+    configurablePlugins(): string[];
+    /** 作废路由闸门的安装记录名字缓存。 */
+    invalidateKnownNames(): void;
+    /** 内置与配置声明的插件名。 */
+    declared(): ReadonlyMap<string, unknown>;
+}
+export interface ExtensionLifecycleDeps {
+    host: LifecycleHost;
+    bus: {
+        subscribe(topic: string, handler: (payload: unknown) => void): Promise<() => Promise<void>>;
+    };
+    status: ReplicaStatusStore;
+    /** 安装记录里的全部插件名（任何期望状态；清理本副本已不认识的状态行）。 */
+    installedNames(): Promise<string[]>;
+    reconcileIntervalSeconds(): number;
+    log: Pick<Logger, "info" | "warn" | "error">;
+}
+/**
+ * 每副本一个：把本副本的插件加载状态收敛到 PG 期望状态（C16）。
+ * 触发来源：bus `kernel.plugins.changed`（后台 / CLI 改了期望状态或快照）、`kernel.plugins.reconcile`（维护任务周期兜底，
+ * 丢了消息也能收敛）、`kernel.plugins.migrated`（别的副本迁移完成），以及启动。
+ * `reconcile` 在本副本内排队串行：进行中时再来的请求合并成「当前这次结束后再跑一次」。
+ * 每次 reconcile 开始与结束时都刷新本副本状态行的心跳，并清理已卸载插件的行与早已退出的副本的行。
+ * 进程内只有排队用的 Promise（不是跨副本状态）。
+ */
+export declare class ExtensionLifecycle {
+    private readonly d;
+    private running;
+    private queued;
+    private unsubs;
+    private stopped;
+    constructor(d: ExtensionLifecycleDeps);
+    /** 订阅三个主题（订阅失败只记 error：周期任务的消息同样收不到时，下次启动再来）。 */
+    start(): Promise<void>;
+    /**
+     * 部署配置保存后（C10，本副本的 HTTP 请求与 bus 消息都走这里）：生效的插件重读并校验（hot 就地替换、
+     * 非 hot 重新加载）；没在本副本生效的（如待配置）跑一次 reconcile，配置合法了就加载。
+     */
+    applyConfig(plugin: string): Promise<void>;
+    /** 取消订阅；之后的 reconcile 直接返回。进行中的那次由宿主关闭收尾。 */
+    stop(): Promise<void>;
+    /**
+     * 收敛一次（本副本内串行；进行中时合并为「结束后再跑一次」，返回那一次的 Promise）。
+     * 宿主那一步失败只记 error（下一个周期再来）；之后照常刷新心跳。
+     */
+    reconcile(reason: string): Promise<void>;
+    /** 用同一个包重新 setup（配置的非 hot 改动、依赖方联动；与 reconcile 一样在宿主的串行队列里）。 */
+    reload(name: string): Promise<void>;
+    private trigger;
+    private run;
+}

package/dist/extensions/lifecycle.js

@@ -0,0 +1,152 @@
+import { PLUGIN_DEPLOYMENT_CONFIG_TOPIC } from "./deployment-config.js";
+import { PLUGINS_MIGRATED_TOPIC } from "./migrate-lock.js";
+/**
+ * 插件期望状态 / 快照变了（kernel bus 主题，频道 `cap:kernel:plugins.changed`，payload `{ plugin }`）。
+ * 后台、CLI 写完 PG 后发布；各副本据此 reconcile，并作废路由闸门的名字缓存。
+ */
+export const PLUGINS_CHANGED_TOPIC = "plugins.changed";
+/** 周期兜底（kernel bus 主题 `plugins.reconcile`，payload `{}`）：维护任务 `plugins-reconcile` 发布。 */
+export const PLUGINS_RECONCILE_TOPIC = "plugins.reconcile";
+export { PLUGINS_MIGRATED_TOPIC };
+/** 维护任务：每 `extensionHost.reconcileIntervalSeconds` 秒发布一次 `plugins.reconcile`（任务名与 scheduler id 不含 `:`）。 */
+export const PLUGINS_RECONCILE_JOB = "plugins-reconcile";
+export const PLUGINS_RECONCILE_SCHEDULER_ID = "plugins-reconcile-every";
+/** 副本行心跳超过这么多个 reconcile 周期的副本不计入（C16；读状态的一方据此筛选）。 */
+export const STALE_RECONCILE_PERIODS = 3;
+/** 心跳超过这么多个周期的行直接删除（副本早已退出；读的一方本来就不计入）。 */
+const PRUNE_RECONCILE_PERIODS = 10;
+/**
+ * 每副本一个：把本副本的插件加载状态收敛到 PG 期望状态（C16）。
+ * 触发来源：bus `kernel.plugins.changed`（后台 / CLI 改了期望状态或快照）、`kernel.plugins.reconcile`（维护任务周期兜底，
+ * 丢了消息也能收敛）、`kernel.plugins.migrated`（别的副本迁移完成），以及启动。
+ * `reconcile` 在本副本内排队串行：进行中时再来的请求合并成「当前这次结束后再跑一次」。
+ * 每次 reconcile 开始与结束时都刷新本副本状态行的心跳，并清理已卸载插件的行与早已退出的副本的行。
+ * 进程内只有排队用的 Promise（不是跨副本状态）。
+ */
+export class ExtensionLifecycle {
+    d;
+    running;
+    queued;
+    unsubs = [];
+    stopped = false;
+    constructor(d) {
+        this.d = d;
+    }
+    /** 订阅三个主题（订阅失败只记 error：周期任务的消息同样收不到时，下次启动再来）。 */
+    async start() {
+        const on = async (topic, handler) => {
+            try {
+                this.unsubs.push(await this.d.bus.subscribe(topic, handler));
+            }
+            catch (err) {
+                this.d.log.error("cannot subscribe to plugin lifecycle topic", { topic, err });
+            }
+        };
+        await on(PLUGINS_CHANGED_TOPIC, (p) => {
+            // 安装 / 卸载改变了「部署已知」的插件名：路由闸门不等 TTL
+            this.d.host.invalidateKnownNames();
+            this.trigger(`changed:${pluginOf(p)}`);
+        });
+        await on(PLUGINS_RECONCILE_TOPIC, () => this.trigger("periodic"));
+        await on(PLUGINS_MIGRATED_TOPIC, (p) => this.trigger(`migrated:${pluginOf(p)}`));
+        await on(PLUGIN_DEPLOYMENT_CONFIG_TOPIC, (p) => {
+            this.applyConfig(pluginOf(p)).catch((err) => this.d.log.error("applying a plugin deployment config change failed", {
+                plugin: pluginOf(p),
+                err,
+            }));
+        });
+    }
+    /**
+     * 部署配置保存后（C10，本副本的 HTTP 请求与 bus 消息都走这里）：生效的插件重读并校验（hot 就地替换、
+     * 非 hot 重新加载）；没在本副本生效的（如待配置）跑一次 reconcile，配置合法了就加载。
+     */
+    async applyConfig(plugin) {
+        if (this.stopped)
+            return;
+        const r = await this.d.host.applyDeploymentConfig(plugin);
+        if (r === "not_loaded")
+            await this.reconcile(`config:${plugin}`);
+    }
+    /** 取消订阅；之后的 reconcile 直接返回。进行中的那次由宿主关闭收尾。 */
+    async stop() {
+        this.stopped = true;
+        const unsubs = this.unsubs;
+        this.unsubs = [];
+        await Promise.allSettled(unsubs.map((u) => u()));
+    }
+    /**
+     * 收敛一次（本副本内串行；进行中时合并为「结束后再跑一次」，返回那一次的 Promise）。
+     * 宿主那一步失败只记 error（下一个周期再来）；之后照常刷新心跳。
+     */
+    reconcile(reason) {
+        if (this.stopped)
+            return Promise.resolve();
+        if (this.queued)
+            return this.queued;
+        if (!this.running) {
+            this.running = this.run(reason).finally(() => {
+                this.running = undefined;
+            });
+            return this.running;
+        }
+        const after = this.running;
+        this.queued = after.then(() => {
+            this.queued = undefined;
+            return this.reconcile(reason);
+        });
+        return this.queued;
+    }
+    /** 用同一个包重新 setup（配置的非 hot 改动、依赖方联动；与 reconcile 一样在宿主的串行队列里）。 */
+    async reload(name) {
+        await this.d.host.reload(name);
+    }
+    trigger(reason) {
+        this.reconcile(reason).catch((err) => this.d.log.error("plugin reconcile failed", { reason, err }));
+    }
+    async run(reason) {
+        // 开始时也刷新心跳：converge 可能很久（排空在途调用、迁移），不能因此被读状态的一方当成退出的副本
+        await this.d.status.heartbeat().catch((err) => {
+            this.d.log.warn("cannot refresh plugin replica status heartbeats", { err });
+        });
+        try {
+            await this.d.host.converge();
+        }
+        catch (err) {
+            if (this.stopped)
+                return;
+            this.d.log.error("plugin reconcile failed; retrying on the next cycle", { reason, err });
+        }
+        if (this.stopped)
+            return;
+        if (reason === "periodic") {
+            // 丢了 plugin-deployment-config 消息时：周期兜底重读生效插件的部署配置（没变时什么都不做）
+            for (const name of this.d.host.configurablePlugins()) {
+                if (this.stopped)
+                    return;
+                try {
+                    await this.d.host.applyDeploymentConfig(name);
+                }
+                catch (err) {
+                    if (this.stopped)
+                        return;
+                    this.d.log.error("applying a plugin deployment config change failed", {
+                        plugin: name,
+                        err,
+                    });
+                }
+            }
+        }
+        try {
+            await this.d.status.heartbeat();
+            const keep = [...this.d.host.declared().keys(), ...(await this.d.installedNames())];
+            const period = this.d.reconcileIntervalSeconds();
+            await this.d.status.prune(keep, PRUNE_RECONCILE_PERIODS * period);
+        }
+        catch (err) {
+            this.d.log.warn("cannot refresh plugin replica status heartbeats", { err });
+        }
+    }
+}
+const pluginOf = (p) => typeof p === "object" && p !== null && typeof p.plugin === "string"
+    ? p.plugin
+    : "?";