@capybara-hq/kernel 0.1.0-rc.1 → 0.1.0-rc.11

package/dist/extensions/installs.d.ts

@@ -1,11 +1,17 @@
 import { type PluginExtensionSection } from "@capybara-hq/plugin-sdk";
-import type { KernelConfig } from "../config/schema.js";
-import type { KernelDb } from "../db/kernel-schema.js";
+import type { core } from "zod";
+import type { Keyring } from "../ctx/secrets.js";
+import { SuperAdminLock } from "../identity/super-admin.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { OrgLock } from "../orgs/org-lock.js";
 import { type ProvenanceResult } from "../packages/provenance.js";
-import type { ExtensionBlobs } from "./blobs.js";
+import { ExtensionApprovals } from "./approvals.js";
+import { ExtensionBlobs } from "./blobs.js";
 import { migrationWarnings, type PackageWarning, type PermissionGroup, type PermissionItem } from "./permission-view.js";
+import { ExtensionRegistry } from "./registry.js";
 export { migrationWarnings, type PackageWarning };
-import type { ExtensionSource } from "./sources.js";
 /** 上传 / 拉取一个包后的审阅结果（权限按静态清单与迁移 SQL 计算，不执行插件代码）。 */
 export interface PackageReview {
     sha256: string;
@@ -69,19 +75,45 @@ export interface IngestSource {
     source: "npm" | "file" | "catalog" | "bootstrap";
     ref: string;
 }
-export interface ExtensionInstallsDeps {
-    db: KernelDb;
-    blobs: ExtensionBlobs;
-    config: () => KernelConfig;
-    /** 配置声明的插件名 → 来源（安装包不能与它们重名，C15）。 */
-    declared: () => ReadonlyMap<string, ExtensionSource>;
-    /** npm 下载的总时限（毫秒），默认 120s。 */
-    npmTimeoutMs?: number;
-}
-/** 插件安装记录与包的导入（上传文件、npm）。本身无状态，多副本共用。 */
+/**
+ * Extension install records and package imports (uploaded file, npm), and the deployment's desired
+ * state the replicas converge to: the install records desired enabled and each extension's
+ * effective deployment config (the startup config completed by the fields stored in PG). Stateless,
+ * shared by every replica; the extension host reads the desired state from here (one way).
+ */
 export declare class ExtensionInstalls {
-    private readonly d;
-    constructor(d: ExtensionInstallsDeps);
+    private readonly db;
+    readonly txHost: TransactionHost;
+    /** The super admin lock (identity/super-admin.ts): joins the transaction. */
+    private readonly adminLock;
+    private readonly blobs;
+    private readonly approvals;
+    /** The config-declared extension names (an install cannot take them, C15). */
+    private readonly registry;
+    private readonly config;
+    private readonly keyring;
+    /** The owner org's lock: an org upload re-checks its org admin instead (ruling P3-10). */
+    private readonly orgLock;
+    constructor(db: KernelDb, txHost: TransactionHost, 
+    /** The super admin lock (identity/super-admin.ts): joins the transaction. */
+    adminLock: SuperAdminLock, blobs: ExtensionBlobs, approvals: ExtensionApprovals, 
+    /** The config-declared extension names (an install cannot take them, C15). */
+    registry: ExtensionRegistry, config: KernelConfigService, keyring: Keyring, 
+    /** The owner org's lock: an org upload re-checks its org admin instead (ruling P3-10). */
+    orgLock: OrgLock);
+    /**
+     * An extension's effective deployment config, not validated yet (C10): the startup config
+     * (`fileValue`, file / Nacos merged with env) completed by the fields stored in PG; merged by
+     * the fields of `schema` when it is given.
+     */
+    effectiveDeploymentConfig(plugin: string, fileValue: unknown, schema?: core.$ZodType): Promise<unknown>;
+    /**
+     * Whether PG holds a deployment config row for the extension (a super admin saved one and has
+     * not cleared it since; `DELETE /api/v1/admin/extensions/:name/config` removes it).
+     */
+    hasStoredDeploymentConfig(plugin: string): Promise<boolean>;
+    /** Every install record's extension name (any desired state). */
+    installedNames(): Promise<string[]>;
     /**
      * Validates and stores one package and returns the review; audits `extension.package_uploaded`.
      * Only stores: no install, no desired state change (T14).
@@ -90,13 +122,31 @@ export declare class ExtensionInstalls {
      * - extension name equal to a config-declared one -> `extension.config_declared`;
      * - an install record of the same name comes from another npm package -> `extension.name_conflict`
      *   (a new version of the same package is an upgrade, handled elsewhere).
-     * `actor` null means the CLI (no enterprise admin re-check, audit without an actor).
+     * `actor` null means the CLI (no super admin re-check, audit without an actor). `owner`: an org
+     * upload (spec §14, P3-10): the actor is re-checked as an org admin of that org (`catalog.upload`)
+     * instead of a super admin; the package is only stored, as always (nothing runs, no install).
      */
     ingest(actor: string | null, bytes: Uint8Array, src: IngestSource, opts?: {
         actorTokenId?: string;
         store?: "object" | "pg";
         expectPackageName?: string;
+        owner?: {
+            orgId: string;
+        };
     }): Promise<PackageReview>;
+    /**
+     * The super admin re-check under its lock, in a transaction of its own (`requires_new`, as
+     * before the conversion): the package write that follows never runs inside a caller's
+     * transaction holding the lock.
+     */
+    private authorize;
+    /** The super admin, or for an org upload the owner org's admin, re-checked under its lock. */
+    private authorizeIn;
+    /**
+     * The `extension.package_uploaded` audit, re-checking the actor under the lock, committed on its
+     * own (`requires_new`): the stored package it records is not rolled back by a caller either.
+     */
+    private auditUpload;
     /** 上传的 tgz（来源 `file`）。 */
     ingestFile(actor: string | null, bytes: Uint8Array, opts?: {
         actorTokenId?: string;
@@ -105,7 +155,7 @@ export declare class ExtensionInstalls {
     /**
      * Fetches one package from the configured npm registry (verified by `dist.integrity`, see
      * packages/npm.ts), downloading only, not storing: download failure -> `packages.npm_failed` (502);
-     * over `packages.maxBytes` -> `extension.package_too_large`. Enterprise catalog npm imports use it
+     * over `packages.maxBytes` -> `extension.package_too_large`. Platform catalog npm imports use it
      * too.
      */
     fetchNpm(input: {
@@ -161,6 +211,10 @@ export declare class ExtensionInstalls {
     }): Promise<PackageReview>;
     /** 全部安装记录（按名字）。 */
     list(): Promise<ExtensionInstallRow[]>;
-    /** Install records desired enabled, with their reviewed extension sections (by name). */
+    /**
+     * Install records desired enabled, with their reviewed extension sections, the earliest enabled
+     * first (`enabled_at`, then the install time, then the name): of two enabled providers of a
+     * single-provider extension point the first one in this order is the one every replica loads.
+     */
     desired(): Promise<DesiredExtension[]>;
 }

package/dist/extensions/installs.js

@@ -1,19 +1,98 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
 import { SDK_VERSION } from "@capybara-hq/plugin-sdk";
+import { Inject, Injectable } from "@nestjs/common";
+import { sql } from "kysely";
+import { configFields } from "../config/fields.js";
 import { ApiError } from "../errors.js";
 import { audit } from "../identity/audit.js";
-import { lockEnterpriseAdminsAndAuthorize } from "../identity/enterprise-admin.js";
+import { SuperAdminLock } from "../identity/super-admin.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { Transactional } from "../infra/database/transactional.decorator.js";
+import { KEYRING } from "../infra/tokens.js";
+import { OrgLock } from "../orgs/org-lock.js";
 import { fetchNpmPackage, IntegrityMismatchError, NpmFetchError, PackageTooLargeError, } from "../packages/npm.js";
 import { fetchProvenance, PROVENANCE_TIMEOUT_MS, } from "../packages/provenance.js";
 import { ExtensionApprovals } from "./approvals.js";
+import { ExtensionBlobs } from "./blobs.js";
+import { mergeDeploymentConfig, readStoredDeploymentConfig, schemaFields, secretPathsOf, } from "./deployment-config-store.js";
 import { ExtensionPackageError, extensionPackageApiError, permissionSetOfPackage, readExtensionPackage, } from "./package.js";
 import { diffPermissions } from "./permission-set.js";
 import { migrationWarnings, permissionGroups, permissionKeyItems, reviewHash, } from "./permission-view.js";
+import { ExtensionRegistry } from "./registry.js";
 export { migrationWarnings };
-/** 插件安装记录与包的导入（上传文件、npm）。本身无状态，多副本共用。 */
-export class ExtensionInstalls {
-    d;
-    constructor(d) {
-        this.d = d;
+/** The npm download time limit (ms). */
+const NPM_TIMEOUT_MS = 120_000;
+/**
+ * Extension install records and package imports (uploaded file, npm), and the deployment's desired
+ * state the replicas converge to: the install records desired enabled and each extension's
+ * effective deployment config (the startup config completed by the fields stored in PG). Stateless,
+ * shared by every replica; the extension host reads the desired state from here (one way).
+ */
+let ExtensionInstalls = class ExtensionInstalls {
+    db;
+    txHost;
+    adminLock;
+    blobs;
+    approvals;
+    registry;
+    config;
+    keyring;
+    orgLock;
+    constructor(db, txHost, 
+    /** The super admin lock (identity/super-admin.ts): joins the transaction. */
+    adminLock, blobs, approvals, 
+    /** The config-declared extension names (an install cannot take them, C15). */
+    registry, config, keyring, 
+    /** The owner org's lock: an org upload re-checks its org admin instead (ruling P3-10). */
+    orgLock) {
+        this.db = db;
+        this.txHost = txHost;
+        this.adminLock = adminLock;
+        this.blobs = blobs;
+        this.approvals = approvals;
+        this.registry = registry;
+        this.config = config;
+        this.keyring = keyring;
+        this.orgLock = orgLock;
+    }
+    /**
+     * An extension's effective deployment config, not validated yet (C10): the startup config
+     * (`fileValue`, file / Nacos merged with env) completed by the fields stored in PG; merged by
+     * the fields of `schema` when it is given.
+     */
+    async effectiveDeploymentConfig(plugin, fileValue, schema) {
+        const stored = await readStoredDeploymentConfig(this.db.db, this.keyring, plugin, {
+            secretPaths: secretPathsOf(schemaFields(schema)),
+        });
+        const fields = schema ? configFields(schema).map((f) => f.path) : undefined;
+        return mergeDeploymentConfig(stored, fileValue, fields);
+    }
+    /**
+     * Whether PG holds a deployment config row for the extension (a super admin saved one and has
+     * not cleared it since; `DELETE /api/v1/admin/extensions/:name/config` removes it).
+     */
+    async hasStoredDeploymentConfig(plugin) {
+        const row = await this.db
+            .selectFrom("extension_deployment_configs")
+            .select("plugin")
+            .where("plugin", "=", plugin)
+            .executeTakeFirst();
+        return row !== undefined;
+    }
+    /** Every install record's extension name (any desired state). */
+    async installedNames() {
+        const rows = await this.db.selectFrom("extension_installs").select("name").execute();
+        return rows.map((r) => r.name);
     }
     /**
      * Validates and stores one package and returns the review; audits `extension.package_uploaded`.
@@ -23,10 +102,15 @@ export class ExtensionInstalls {
      * - extension name equal to a config-declared one -> `extension.config_declared`;
      * - an install record of the same name comes from another npm package -> `extension.name_conflict`
      *   (a new version of the same package is an upgrade, handled elsewhere).
-     * `actor` null means the CLI (no enterprise admin re-check, audit without an actor).
+     * `actor` null means the CLI (no super admin re-check, audit without an actor). `owner`: an org
+     * upload (spec §14, P3-10): the actor is re-checked as an org admin of that org (`catalog.upload`)
+     * instead of a super admin; the package is only stored, as always (nothing runs, no install).
      */
     async ingest(actor, bytes, src, opts = {}) {
-        const maxBytes = this.d.config().packages.maxBytes;
+        if (opts.owner !== undefined && actor === null) {
+            throw new Error("an org upload has an actor");
+        }
+        const maxBytes = this.config.get().packages.maxBytes;
         if (bytes.byteLength > maxBytes) {
             throw new ApiError("extension.package_too_large", `The extension package is larger than ${maxBytes} bytes`);
         }
@@ -47,11 +131,11 @@ export class ExtensionInstalls {
                 issue,
             ]);
         }
-        const declared = this.d.declared().get(m.name);
+        const declared = this.registry.declared().get(m.name);
         if (declared === "config") {
             throw new ApiError("extension.config_declared", `Extension ${m.name} is declared in the startup config (extensions); remove it there before installing it as a package`);
         }
-        const installed = await this.d.db
+        const installed = await this.db
             .selectFrom("extension_installs")
             .innerJoin("extension_packages", "extension_packages.sha256", "extension_installs.sha256")
             .select("extension_packages.package_name")
@@ -60,29 +144,24 @@ export class ExtensionInstalls {
         if (installed && installed.package_name !== packageName) {
             throw new ApiError("extension.name_conflict", `Extension ${m.name} is already installed from package ${installed.package_name}; package ${packageName} uses the same extension name`);
         }
-        // 写包之前在锁内复核发起人仍是企业管理员（守卫读到的身份可能已过期）；审计在写完后同样复核
-        if (actor !== null) {
-            await this.d.db.transaction().execute((trx) => lockEnterpriseAdminsAndAuthorize(trx, actor));
-        }
-        await this.d.blobs.put(pkg, bytes, {
+        // 写包之前在锁内复核发起人仍是超级管理员（守卫读到的身份可能已过期）；审计在写完后同样复核
+        if (actor !== null)
+            await this.authorize(actor, opts.owner);
+        await this.blobs.put(pkg, bytes, {
             source: src.source,
             ref: src.ref,
             actor,
             ...(opts.store !== undefined && { store: opts.store }),
         });
-        await this.d.db.transaction().execute(async (trx) => {
-            if (actor !== null)
-                await lockEnterpriseAdminsAndAuthorize(trx, actor);
-            await audit(trx, {
-                ...(actor !== null && { actorAccountId: actor }),
-                ...(opts.actorTokenId !== undefined && { actorTokenId: opts.actorTokenId }),
-                action: "extension.package_uploaded",
-                target: m.name,
-                detail: { name: m.name, version: m.version, sha256: pkg.sha256, source: src.source },
-            });
-        });
+        await this.auditUpload(actor, opts.actorTokenId, {
+            name: m.name,
+            version: m.version,
+            sha256: pkg.sha256,
+            source: src.source,
+            ...(opts.owner !== undefined && { orgId: opts.owner.orgId }),
+        }, opts.owner);
         const set = permissionSetOfPackage(pkg);
-        const snapshot = (await new ExtensionApprovals(this.d.db).all()).get(m.name);
+        const snapshot = (await this.approvals.all()).get(m.name);
         const { added, removed } = diffPermissions(snapshot?.permissions, set);
         const warnings = migrationWarnings(pkg.migrationSql, m.name);
         return {
@@ -97,6 +176,36 @@ export class ExtensionInstalls {
             warnings,
         };
     }
+    /**
+     * The super admin re-check under its lock, in a transaction of its own (`requires_new`, as
+     * before the conversion): the package write that follows never runs inside a caller's
+     * transaction holding the lock.
+     */
+    async authorize(actor, owner) {
+        await this.authorizeIn(actor, owner);
+    }
+    /** The super admin, or for an org upload the owner org's admin, re-checked under its lock. */
+    async authorizeIn(actor, owner) {
+        if (owner !== undefined)
+            await this.orgLock.lockAndAuthorize(owner.orgId, actor, "catalog.upload");
+        else
+            await this.adminLock.lockAndAuthorize(actor);
+    }
+    /**
+     * The `extension.package_uploaded` audit, re-checking the actor under the lock, committed on its
+     * own (`requires_new`): the stored package it records is not rolled back by a caller either.
+     */
+    async auditUpload(actor, actorTokenId, detail, owner) {
+        if (actor !== null)
+            await this.authorizeIn(actor, owner);
+        await audit(this.db.db, {
+            ...(actor !== null && { actorAccountId: actor }),
+            ...(actorTokenId !== undefined && { actorTokenId }),
+            action: "extension.package_uploaded",
+            target: detail.name,
+            detail,
+        });
+    }
     /** 上传的 tgz（来源 `file`）。 */
     ingestFile(actor, bytes, opts = {}) {
         return this.ingest(actor, bytes, { source: "file", ref: "upload" }, opts);
@@ -104,17 +213,17 @@ export class ExtensionInstalls {
     /**
      * Fetches one package from the configured npm registry (verified by `dist.integrity`, see
      * packages/npm.ts), downloading only, not storing: download failure -> `packages.npm_failed` (502);
-     * over `packages.maxBytes` -> `extension.package_too_large`. Enterprise catalog npm imports use it
+     * over `packages.maxBytes` -> `extension.package_too_large`. Platform catalog npm imports use it
      * too.
      */
     async fetchNpm(input, signal) {
-        const c = this.d.config();
+        const c = this.config.get();
         const cfg = {
             registry: c.packages.npmRegistry,
             maxBytes: c.packages.maxBytes,
             ...(c.packages.npmToken !== undefined && { token: c.packages.npmToken }),
         };
-        const timeout = AbortSignal.timeout(this.d.npmTimeoutMs ?? 120_000);
+        const timeout = AbortSignal.timeout(NPM_TIMEOUT_MS);
         try {
             return await fetchNpmPackage(cfg, input.package, input.version, signal ? AbortSignal.any([signal, timeout]) : timeout);
         }
@@ -149,7 +258,7 @@ export class ExtensionInstalls {
      * failure is `{ checked: false, reason }`. `integrity` ties the statement to the tarball.
      */
     fetchProvenance(input, signal) {
-        const c = this.d.config();
+        const c = this.config.get();
         const cfg = {
             registry: c.packages.npmRegistry,
             maxBytes: c.packages.maxBytes,
@@ -159,14 +268,14 @@ export class ExtensionInstalls {
         return fetchProvenance(cfg, input.package, input.version, signal ? AbortSignal.any([signal, timeout]) : timeout, input.integrity !== undefined ? { integrity: input.integrity } : {});
     }
     async fetchVerified(input, signal, codes) {
-        const c = this.d.config();
+        const c = this.config.get();
         const cfg = {
             registry: c.packages.npmRegistry,
             maxBytes: c.packages.maxBytes,
             allowInsecureLoopback: c.marketplaces.allowInsecureLoopback,
             ...(c.packages.npmToken !== undefined && { token: c.packages.npmToken }),
         };
-        const timeout = AbortSignal.timeout(this.d.npmTimeoutMs ?? 120_000);
+        const timeout = AbortSignal.timeout(NPM_TIMEOUT_MS);
         try {
             return await fetchNpmPackage(cfg, input.package, input.version, signal ? AbortSignal.any([signal, timeout]) : timeout, {
                 expectedIntegrity: input.integrity,
@@ -201,7 +310,7 @@ export class ExtensionInstalls {
     }
     /** 全部安装记录（按名字）。 */
     async list() {
-        const rows = await this.d.db
+        const rows = await this.db
             .selectFrom("extension_installs")
             .innerJoin("extension_packages", "extension_packages.sha256", "extension_installs.sha256")
             .selectAll("extension_installs")
@@ -223,9 +332,13 @@ export class ExtensionInstalls {
             updatedAt: r.updated_at.toISOString(),
         }));
     }
-    /** Install records desired enabled, with their reviewed extension sections (by name). */
+    /**
+     * Install records desired enabled, with their reviewed extension sections, the earliest enabled
+     * first (`enabled_at`, then the install time, then the name): of two enabled providers of a
+     * single-provider extension point the first one in this order is the one every replica loads.
+     */
     async desired() {
-        const rows = await this.d.db
+        const rows = await this.db
             .selectFrom("extension_installs")
             .innerJoin("extension_packages", "extension_packages.sha256", "extension_installs.sha256")
             .select([
@@ -238,6 +351,8 @@ export class ExtensionInstalls {
             "extension_packages.blob_store",
         ])
             .where("extension_installs.desired_state", "=", "enabled")
+            .orderBy(sql `extension_installs.enabled_at ASC NULLS LAST`)
+            .orderBy("extension_installs.installed_at")
             .orderBy("extension_installs.name")
             .execute();
         return rows.map((r) => ({
@@ -250,4 +365,26 @@ export class ExtensionInstalls {
             section: r.section,
         }));
     }
-}
+};
+__decorate([
+    Transactional({ propagation: "requires_new" })
+], ExtensionInstalls.prototype, "authorize", null);
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], ExtensionInstalls.prototype, "authorizeIn", null);
+__decorate([
+    Transactional({ propagation: "requires_new" })
+], ExtensionInstalls.prototype, "auditUpload", null);
+ExtensionInstalls = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(TransactionHost)),
+    __param(2, Inject(SuperAdminLock)),
+    __param(3, Inject(ExtensionBlobs)),
+    __param(4, Inject(ExtensionApprovals)),
+    __param(5, Inject(ExtensionRegistry)),
+    __param(6, Inject(KernelConfigService)),
+    __param(7, Inject(KEYRING)),
+    __param(8, Inject(OrgLock))
+], ExtensionInstalls);
+export { ExtensionInstalls };

package/dist/extensions/job-ids.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The maintenance job scheduler ids the plugins reconcile had before becoming `@LockedCron` /
+ * `@LockedInterval` jobs (retired at worker start, `RETIRED_SCHEDULER_IDS`). A leaf module.
+ */
+/** The BullMQ repeatable scheduler the job had before it became `@LockedInterval` (retired). */
+export declare const PLUGINS_RECONCILE_SCHEDULER_ID = "plugins-reconcile-every";

package/dist/extensions/job-ids.js

@@ -0,0 +1,6 @@
+/**
+ * The maintenance job scheduler ids the plugins reconcile had before becoming `@LockedCron` /
+ * `@LockedInterval` jobs (retired at worker start, `RETIRED_SCHEDULER_IDS`). A leaf module.
+ */
+/** The BullMQ repeatable scheduler the job had before it became `@LockedInterval` (retired). */
+export const PLUGINS_RECONCILE_SCHEDULER_ID = "plugins-reconcile-every";

package/dist/extensions/lifecycle-topics.d.ts

@@ -0,0 +1,18 @@
+/** The kernel bus topics and the job of the extension lifecycle (a leaf module: no imports). */
+/**
+ * 插件期望状态 / 快照变了（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";
+/** The `@LockedInterval` job that publishes `plugins.reconcile` every `extensionHost.reconcileIntervalSeconds`. */
+export declare const PLUGINS_RECONCILE_JOB = "plugins-reconcile";
+/** 副本行心跳超过这么多个 reconcile 周期的副本不计入（C16；读状态的一方据此筛选）。 */
+export declare const STALE_RECONCILE_PERIODS = 3;
+/**
+ * 部署配置保存之后（kernel bus 主题，频道 `cap:kernel:plugin-deployment-config`，payload `{ plugin }`）：
+ * 各副本重读并校验——只改了 hot 字段就地替换，改了非 hot 字段重新加载实例，不合法保持当前值并告警；
+ * 插件此刻待配置时，下一次 reconcile 加载它。
+ */
+export declare const PLUGIN_DEPLOYMENT_CONFIG_TOPIC = "plugin-deployment-config";

package/dist/extensions/lifecycle-topics.js

@@ -0,0 +1,18 @@
+/** The kernel bus topics and the job of the extension lifecycle (a leaf module: no imports). */
+/**
+ * 插件期望状态 / 快照变了（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";
+/** The `@LockedInterval` job that publishes `plugins.reconcile` every `extensionHost.reconcileIntervalSeconds`. */
+export const PLUGINS_RECONCILE_JOB = "plugins-reconcile";
+/** 副本行心跳超过这么多个 reconcile 周期的副本不计入（C16；读状态的一方据此筛选）。 */
+export const STALE_RECONCILE_PERIODS = 3;
+/**
+ * 部署配置保存之后（kernel bus 主题，频道 `cap:kernel:plugin-deployment-config`，payload `{ plugin }`）：
+ * 各副本重读并校验——只改了 hot 字段就地替换，改了非 hot 字段重新加载实例，不合法保持当前值并告警；
+ * 插件此刻待配置时，下一次 reconcile 加载它。
+ */
+export const PLUGIN_DEPLOYMENT_CONFIG_TOPIC = "plugin-deployment-config";

package/dist/extensions/lifecycle.d.ts

@@ -1,49 +1,13 @@
-import type { Logger } from "@capybara-hq/plugin-sdk";
-import type { ExtensionInstance } from "./instance.js";
+import type { ExtensionContext } from "@capybara-hq/plugin-sdk";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { LockService } from "../infra/lock/lock.service.js";
+import type { KernelLogger } from "../log.js";
+import { ExtensionHost } from "./host.js";
+import { ExtensionInstalls } from "./installs.js";
+import { PLUGINS_CHANGED_TOPIC, PLUGINS_RECONCILE_JOB, PLUGINS_RECONCILE_TOPIC, STALE_RECONCILE_PERIODS } from "./lifecycle-topics.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">;
-}
+import { ReplicaStatusStore } from "./sources.js";
+export { PLUGINS_CHANGED_TOPIC, PLUGINS_MIGRATED_TOPIC, PLUGINS_RECONCILE_JOB, PLUGINS_RECONCILE_TOPIC, STALE_RECONCILE_PERIODS, };
 /**
  * 每副本一个：把本副本的插件加载状态收敛到 PG 期望状态（C16）。
  * 触发来源：bus `kernel.plugins.changed`（后台 / CLI 改了期望状态或快照）、`kernel.plugins.reconcile`（维护任务周期兜底，
@@ -53,12 +17,22 @@ export interface ExtensionLifecycleDeps {
  * 进程内只有排队用的 Promise（不是跨副本状态）。
  */
 export declare class ExtensionLifecycle {
-    private readonly d;
+    private readonly host;
+    private readonly bus;
+    private readonly status;
+    /** Every install record's name (any desired state): prunes status rows this replica no longer knows. */
+    private readonly installs;
+    private readonly config;
+    private readonly log;
     private running;
     private queued;
     private unsubs;
+    /** {@link start} was called (the kernel's start sequence; never in the CLI, which loads nothing). */
+    private started;
     private stopped;
-    constructor(d: ExtensionLifecycleDeps);
+    constructor(host: ExtensionHost, bus: Pick<ExtensionContext["bus"], "publish" | "subscribe">, status: ReplicaStatusStore, 
+    /** Every install record's name (any desired state): prunes status rows this replica no longer knows. */
+    installs: ExtensionInstalls, config: KernelConfigService, log: KernelLogger);
     /** 订阅三个主题（订阅失败只记 error：周期任务的消息同样收不到时，下次启动再来）。 */
     start(): Promise<void>;
     /**
@@ -78,3 +52,17 @@ export declare class ExtensionLifecycle {
     private trigger;
     private run;
 }
+/**
+ * The periodic reconcile fallback (job `plugins-reconcile`, once per
+ * `extensionHost.reconcileIntervalSeconds` across replicas): publishes `kernel.plugins.reconcile`,
+ * so every replica converges even when it lost a message. A worker-role job (`WorkerModule`); every
+ * replica's {@link ExtensionLifecycle} subscribes to the topic.
+ */
+export declare class PluginsReconcileJob {
+    private readonly bus;
+    readonly config: KernelConfigService;
+    readonly lockService: LockService;
+    readonly log: KernelLogger;
+    constructor(bus: Pick<ExtensionContext["bus"], "publish">, config: KernelConfigService, lockService: LockService, log: KernelLogger);
+    run(): Promise<void>;
+}