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

package/dist/extensions/host.js

@@ -1,67 +1,50 @@
-import { createHash } from "node:crypto";
+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 { readFile } from "node:fs/promises";
 import { createRequire } from "node:module";
 import { dirname, isAbsolute, join, resolve as resolvePath } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { EXTENSION_POINT_CARDINALITY, parseExtensionPoint, SDK_VERSION, } from "@capybara-hq/plugin-sdk";
-import { changedPaths, configFields, getPath, secretValues, setPath, unreachableSecrets, } from "../config/fields.js";
+import { Inject, Injectable } from "@nestjs/common";
+import { changedPaths, configFields, secretValues, unreachableSecrets } from "../config/fields.js";
 import { pluginSchemaName, queryEnabledPlugins, } from "../ctx/create-ctx.js";
 import { kernelDb } from "../db/kernel-schema.js";
 import { migrate } from "../db/migrator.js";
 import { createDb } from "../db/pool.js";
+import { waitWithin } from "../infra/close-within.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { LockService } from "../infra/lock/lock.service.js";
+import { KERNEL_LOGGER, KEYRING, REDIS, REDIS_SUBSCRIBER } from "../infra/tokens.js";
+import { KERNEL_APP_OPTIONS } from "../lifecycle/tokens.js";
+import { ModelEmbeddings } from "../models/embeddings.js";
 import { packagePath } from "../packages/tgz.js";
-import { ExtensionApprovals, planApprovals, withPreApproved, } from "./approvals.js";
+import { EmbedTokens } from "../ui/embed-token.js";
+import { ExtensionApprovals, planApprovals, readSnapshots, withPreApproved, } from "./approvals.js";
 import { ExtensionBlobIntegrityError } from "./blobs.js";
-import { DEFAULT_HOOK_TIMEOUT_MS, HookRegistry } from "./hooks.js";
-import { trackCalls } from "./inflight.js";
-import { DEFAULT_DISPOSE_TIMEOUT_MS, ImportTracker, importExtensionModule, ManifestMismatchError, matchesSection, setupInstance, warnUpgrades, } from "./instance.js";
-import { toIssues } from "./org-config.js";
-import { permissionSetOfSection, readMigrationSql } from "./package.js";
+import { deploymentConfigHash } from "./config-hash.js";
+import { toIssues } from "./config-issues.js";
+import { configFormSchema, describeConfigUiProblems } from "./config-json-schema.js";
+import { EffectiveConfigs } from "./effective-config.js";
+import { HookRegistry } from "./hooks.js";
+import { ExtensionInstalls } from "./installs.js";
+import { ImportTracker, importExtensionModule, ManifestMismatchError, matchesSection, setupInstance, warnUpgrades, } from "./instance.js";
+import { parseLoadGate } from "./org-levels.js";
+import { declaredDisplayName, permissionSetOfSection, readMigrationSql } from "./package.js";
 import { blockingKeys, computePermissionSet, UI_VIEW_KEY_PREFIX, } from "./permission-set.js";
 import { ExtensionRegistry } from "./registry.js";
-import { ExtensionResolveError, resolveExtensions } from "./resolve.js";
+import { ExtensionResolveError, electSingleProviders, PROVIDER_CONFLICT, providerConflictMessage, resolveExtensions, } from "./resolve.js";
+import { ReplicaStatusStore, } from "./sources.js";
 import { PackageShaMismatchError, packageRootOf } from "./sync.js";
-/** 键排序后的 JSON（对象键顺序不影响结果）；undefined 字段与 JSON.stringify 一样省略。 */
-const canonicalJson = (v) => {
-    if (Array.isArray(v))
-        return `[${v.map((x) => (x === undefined ? "null" : canonicalJson(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)}:${canonicalJson(x)}`).join(",")}}`;
-    }
-    return JSON.stringify(v) ?? "null";
-};
-/** 遮蔽 secret 字段后参与摘要的固定占位值。 */
-const SECRET_PLACEHOLDER = "<secret>";
-/**
- * 插件部署配置（校验后）中非密钥部分的摘要：先把 schema 里所有 secret 叶子（`configFields` 可达路径，
- * 加载时 `assertSecretsReachable` 已保证密钥都在这些路径上）换成固定占位值，再取 sha256(键排序 JSON) 前 16 位十六进制。
- * 给需要「配置变了就失效」的缓存键用（如模型列表）。密钥不参与摘要：不加盐的短摘要写进 Redis 键名后，
- * 低熵密钥可被离线猜测、泄露的密钥可被确认；代价是轮换密钥不会让缓存失效（缓存内容本来就不该依赖密钥）。
- * 没有部署配置 schema 时无从得知哪些是密钥，摘要不按配置区分。同一份配置在各副本上得到同一摘要。
- * 函数自己按 schema 遮蔽，调用方不必（也不能忘记）先打码。
- */
-export function deploymentConfigHash(schema, config) {
-    let redacted = null;
-    if (schema) {
-        redacted = structuredClone(config);
-        if (redacted !== null && typeof redacted === "object") {
-            for (const f of configFields(schema)) {
-                if (f.meta?.secret && getPath(redacted, f.path) !== undefined) {
-                    setPath(redacted, f.path, SECRET_PLACEHOLDER);
-                }
-            }
-        }
-    }
-    return createHash("sha256").update(canonicalJson(redacted)).digest("hex").slice(0, 16);
-}
+export { deploymentConfigHash };
 const CLOSED_DURING_LOAD = "plugin host closed during load";
-/** 撤销实例时在途调用的默认排空时限（`extensionHost.drainSeconds` 的默认值）。 */
-const DEFAULT_DRAIN_MS = 30_000;
-/** 运行中重新加载时 setup 的默认时限（`extensionHost.reloadSetupTimeoutSeconds` 的默认值）。 */
-const DEFAULT_RELOAD_SETUP_TIMEOUT_MS = 60_000;
 /** 停机时等进行中的 unload / reload 的上限（之后直接关闭 setup 中的 ctx、撤销其余实例）。 */
 const CLOSE_LIFECYCLE_WAIT_MS = 2_000;
 /** 部署已知插件名（配置声明 / 安装记录）缓存的有效期：路由闸门 503 / 404 用，跨副本靠它收敛。 */
@@ -148,8 +131,31 @@ async function permissionSets(ordered, dirs) {
     }
     return sets;
 }
+/**
+ * The single-provider extension points `manifest` provides that `others` already provide, with
+ * those providers (a `conflict` pending's {@link PendingExtension.conflicts}).
+ */
+function conflictsOf(manifest, others) {
+    return manifest.provides
+        .filter((ref) => EXTENSION_POINT_CARDINALITY[parseExtensionPoint(ref).name] === "single")
+        .map((extensionPoint) => ({
+        extensionPoint,
+        providers: others
+            .filter((m) => m.name !== manifest.name && m.provides.includes(extensionPoint))
+            .map((m) => m.name),
+    }))
+        .filter((c) => c.providers.length > 0);
+}
+/** The replica status reason of a pending extension (`new` / `added` are both `approval`). */
+function pendingReasonOf(p) {
+    return p.reason === "dependency" || p.reason === "conflict" ? p.reason : "approval";
+}
 /** 待批准插件的 warn 日志：点名插件、原因与新增项（依赖原因写明阻塞的能力与提供方）。 */
 function warnPending(log, p) {
+    if (p.reason === "conflict") {
+        log.warn("extension not loaded: it provides a single-provider extension point another extension already provides (disable that one and this one loads, no restart)", { plugin: p.plugin, version: p.version, conflicts: p.conflicts });
+        return;
+    }
     if (p.reason === "dependency") {
         const missing = (p.blockedBy ?? []).some((b) => b.providers.length === 0);
         log.warn(missing
@@ -157,7 +163,7 @@ function warnPending(log, p) {
             : "extension not loaded: a required extension point is only provided by extensions awaiting permission approval", { plugin: p.plugin, version: p.version, blockedBy: p.blockedBy });
         return;
     }
-    log.warn("extension not loaded: permissions awaiting approval (an enterprise admin approves it in the admin console, or run `capybara extensions review`, then `capybara extensions approve <name>`; running replicas load it without a restart)", { plugin: p.plugin, version: p.version, reason: p.reason, added: p.added, removed: p.removed });
+    log.warn("extension not loaded: permissions awaiting approval (a super admin approves it in the admin console, or run `capybara extensions review`, then `capybara extensions approve <name>`; running replicas load it without a restart)", { plugin: p.plugin, version: p.version, reason: p.reason, added: p.added, removed: p.removed });
 }
 /**
  * 跑单个插件的迁移（`migrationsDir` 为迁移目录的绝对路径；没有迁移时为 undefined）；返回已应用的文件，
@@ -212,16 +218,15 @@ function manifestOfSection(m) {
         },
     };
 }
-/** 内核消费的提供方能力：调用计入提供方实例的在途计数（撤销 / 升级时排空，C17）。 */
-const TRACKED_EXTENSION_POINTS = {
-    connector: { sessions: ["open"] },
-    sandbox: {},
-    "model-provider": {},
-};
 /** 插件宿主：解析、校验配置、迁移、setup，并登记插件提供的能力与路由。 */
-export class ExtensionHost {
-    deps;
-    extensionConfig;
+let ExtensionHost = class ExtensionHost {
+    registry;
+    installs;
+    approvals;
+    status;
+    config;
+    log;
+    effective;
     /**
      * Only resolves extensions and runs migrations in dependency order: no deployment config check, no
      * setup, no Redis (for `capybara migrate`). Like `load()` it checks secret markers first
@@ -245,7 +250,7 @@ export class ExtensionHost {
             const raw = createDb(opts.dbUrl, 1, () => { }, { connectTimeoutMs: opts.connectTimeoutMs });
             let decisions;
             try {
-                decisions = planApprovals(ordered, sets, await new ExtensionApprovals(kernelDb(raw)).all());
+                decisions = planApprovals(ordered, sets, await readSnapshots(kernelDb(raw)));
             }
             finally {
                 await raw.destroy();
@@ -286,15 +291,19 @@ export class ExtensionHost {
         for (const manifest of ordered)
             assertSecretsReachable(manifest);
         const sets = await permissionSets(ordered, dirs);
-        return ordered.map((manifest) => ({
-            source: "config",
-            manifest,
-            dir: dirs.get(manifest.name),
-            permissions: sets.get(manifest.name),
-        }));
+        const out = [];
+        for (const manifest of ordered) {
+            const dir = dirs.get(manifest.name);
+            out.push({
+                source: "config",
+                manifest,
+                dir,
+                permissions: sets.get(manifest.name),
+                displayName: (await declaredDisplayName(dir, manifest.name)).displayName ?? null,
+            });
+        }
+        return out;
     }
-    /** 本进程生效的插件实例（C17）：消费方每次实时取，不缓存实现对象。 */
-    registry = new ExtensionRegistry();
     /**
      * M-1: plugin → mount points where deployment state expects `policy` hooks. A per-replica copy of PG
      * deployment state (like the registry), rebuilt on every load / converge, never written elsewhere.
@@ -316,10 +325,6 @@ export class ExtensionHost {
     imports = new ImportTracker();
     /** 串行化 unload / reload（同一时刻只做一件，依赖方的连锁处理不交错）。 */
     lifecycle = Promise.resolve();
-    drainMs;
-    disposeTimeoutMs;
-    reloadSetupTimeoutMs;
-    installedNames;
     /** 安装记录里的插件名缓存（TTL + 注册表变化时作废）。 */
     installedCache;
     /** 本次因权限待批准（或依赖待批准插件）而未加载的插件。 */
@@ -329,6 +334,11 @@ export class ExtensionHost {
      * 安装记录不在这里：每次 converge 都按 PG 期望状态重新判定。
      */
     pendingActivations = new Map();
+    /**
+     * The load parameters of each config-declared extension that loaded: when its deployment config
+     * is cleared and the rest is invalid it goes back to {@link pendingActivations} (pending config).
+     */
+    declaredActivations = new Map();
     /** 安装记录准备好的候选（按插件名；sha 变了就作废）。 */
     prepared = new Map();
     /** 闸门放行后导入过的安装记录真实清单（按插件名；部署配置 schema 用，含待配置而未加载的）。 */
@@ -345,6 +355,11 @@ export class ExtensionHost {
     retiring = new Map();
     /** 配置声明插件的清单与权限集合（含未加载的；后台列表与网页批准用）。 */
     declaredInfo = new Map();
+    /**
+     * Config-declared extensions' display names, read from their plugin directory's plugin.json at
+     * load (from the startup config, the same on every replica; never written elsewhere).
+     */
+    declaredDisplayNames = new Map();
     /** 导入过的插件名 → 来源与包（含未加载的；重名被跳过的一方不在这里）。 */
     sources = new Map();
     didLoad = false;
@@ -358,53 +373,124 @@ export class ExtensionHost {
     /** 已创建、尚未登记（setup 进行中）的 ctx：close() 时立即关闭，不等 setup 返回。 */
     settingUp;
     resolveFrom;
-    onSecrets;
-    autoApprove;
-    status;
-    storedConfig;
+    /** What every extension's `ctx` is built from (kernel side only; nothing Nest crosses into `ctx`). */
+    deps;
     /** 配置声明插件的部署配置最近一次判定是否合法（后台列表用；没判定过时按启动配置校验）。 */
     configValidity = new Map();
     /** 已告警过的「部署配置不合法」（插件名 → 说明；每个周期都会重新判定，同一说明只告警一次）。 */
     configWarned = new Map();
+    /** `<name>@<version>` whose invalid config UI hints were warned about (a log dedupe only). */
+    configUiWarned = new Set();
+    /**
+     * The host builds each extension's `ctx` from the injected kernel services: the pool for
+     * `ctx.db` on the extension's schema, Redis for `kv` / `lock` / `bus` and the queues, the
+     * keyring for `secrets`. The config is read per call (`extensionConfig`, the drain and setup
+     * time limits, `extensionPermissions.autoApprove`).
+     *
+     * `KERNEL_APP_OPTIONS.resolveFrom`: the directory bare package names are resolved from, default
+     * `process.cwd()`; a relative path is made absolute against the cwd at construction. Absolute
+     * paths and `file:` URL extension specifiers are used as they are; bare package names are
+     * resolved with `createRequire(<resolveFrom>/noop.js).resolve`, so an extension package's exports
+     * must expose the `default` (or `require`) condition.
+     */
+    constructor(
+    /** The process's extension registry (one provider, shared with other domains). */
+    registry, 
     /**
-     * @param opts.resolveFrom The directory bare package names are resolved from, default
-     * `process.cwd()`; a relative path is made absolute against the cwd at construction.
-     * Absolute paths and `file:` URL extension specifiers are used as they are;
-     * bare package names are resolved with `createRequire(<resolveFrom>/noop.js).resolve`, so an
-     * extension package's exports must expose the `default` (or `require`) condition.
-     * @param opts.autoApprove Approve extension permissions automatically (config
-     * `extensionPermissions.autoApprove`, development and trials only): extensions needing approval write a
-     * snapshot with source auto and load as usual. Default false: extensions pending approval do not
-     * load (see {@link pending}).
-     * @param opts.status This replica's load status table (`extension_replica_status`): every
-     * extension's load result writes a row.
+     * The deployment's desired state (one way, spec §3): install record names (with the
+     * config-declared ones the extensions "known to the deployment": routes of one not active on
+     * this replica answer 503, an unknown name 404; cached {@link KNOWN_NAMES_TTL_MS}) and each
+     * extension's effective deployment config (the startup config plus the fields stored in PG, C10).
      */
-    constructor(deps, extensionConfig = {}, opts = {}) {
-        this.deps = deps;
-        this.extensionConfig = extensionConfig;
-        this.storedConfig = opts.deploymentConfig;
-        this.drainMs = opts.drainMs ?? (() => DEFAULT_DRAIN_MS);
-        this.disposeTimeoutMs = opts.disposeTimeoutMs ?? (() => DEFAULT_DISPOSE_TIMEOUT_MS);
-        this.reloadSetupTimeoutMs =
-            opts.reloadSetupTimeoutMs ?? (() => DEFAULT_RELOAD_SETUP_TIMEOUT_MS);
-        this.installedNames = opts.installedNames;
-        const hookTimeoutMs = opts.hookTimeoutMs ?? (() => DEFAULT_HOOK_TIMEOUT_MS);
+    installs, approvals, 
+    /** This replica's load status table (`extension_replica_status`): every load result writes a row. */
+    status, config, kdb, redis, busSubscriber, keyring, embedTokens, locks, log, options, 
+    /**
+     * Each hook call's effective config for its organization, and the providers excluded from an
+     * org's point resolution (layering spec A §6).
+     */
+    effective, 
+    /** `ctx.models`: the embeddings broker (spec B §5.4). */
+    models) {
+        this.registry = registry;
+        this.installs = installs;
+        this.approvals = approvals;
+        this.status = status;
+        this.config = config;
+        this.log = log;
+        this.effective = effective;
+        const c = config.get();
         this.hooks = new HookRegistry({
             instances: () => this.registry.all(),
             current: (plugin) => this.registry.current(plugin),
             expectedPolicy: (mount) => this.expectedPolicy(mount),
             enabledPlugins: (orgId) => this.enabledPlugins(orgId),
-            redis: deps.redis,
-            config: () => ({ hooks: { timeoutMs: hookTimeoutMs() } }),
-            log: deps.log,
+            effectiveConfig: (orgId, plugin) => effective.get(orgId, plugin),
+            locks,
+            config: () => ({ hooks: { timeoutMs: this.config.get().hooks.timeoutMs } }),
+            log,
         });
+        this.deps = {
+            db: kdb.pool,
+            dbUrl: c.db.url,
+            connectTimeoutMs: c.db.connectTimeoutMs,
+            redis,
+            busSubscriber,
+            redisUrl: c.redis.url,
+            keyring,
+            embedTokens,
+            models,
+            // ctx.models.embed fires model.request through the same registry (spec B §5.4)
+            hooks: this.hooks,
+            locks,
+            runWorkers: c.roles.includes("worker"),
+            log,
+        };
         this.registry.onChange(() => {
             this.installedCache = undefined;
         });
-        this.onSecrets = opts.onSecrets;
-        this.autoApprove = opts.autoApprove === true;
-        this.resolveFrom = resolvePath(opts.resolveFrom ?? process.cwd());
-        this.status = opts.status;
+        this.resolveFrom = resolvePath(options.resolveFrom ?? process.cwd());
+    }
+    /** The startup config's `extensionConfig` (file / Nacos merged with env). */
+    get extensionConfig() {
+        return this.config.get().extensionConfig;
+    }
+    /** `extensionPermissions.autoApprove` (development and trials only; see `planApprovals`). */
+    get autoApprove() {
+        return this.config.get().extensionPermissions.autoApprove;
+    }
+    /** In-flight calls of a revoked instance are drained within this (`extensionHost.drainSeconds`). */
+    drainMs() {
+        return this.config.get().extensionHost.drainSeconds * 1000;
+    }
+    /** An extension's `dispose()` time limit (`extensionHost.disposeTimeoutSeconds`). */
+    disposeTimeoutMs() {
+        return this.config.get().extensionHost.disposeTimeoutSeconds * 1000;
+    }
+    /** `setup` time limit of a reload in a running process (`extensionHost.reloadSetupTimeoutSeconds`). */
+    reloadSetupTimeoutMs() {
+        return this.config.get().extensionHost.reloadSetupTimeoutSeconds * 1000;
+    }
+    /**
+     * Records the config-declared extensions the CLI inspected (the CLI loads none): their names,
+     * manifests and permission sets for {@link declared} / {@link declaredPlugins}, and whether
+     * their deployment config is valid (the CLI merges and checks it like a replica would).
+     */
+    noteInspected(inspected, configValid) {
+        for (const p of inspected) {
+            this.sources.set(p.manifest.name, { source: "config", sha256: null });
+            this.declaredInfo.set(p.manifest.name, {
+                source: "config",
+                manifest: p.manifest,
+                set: p.permissions,
+            });
+            if (p.displayName)
+                this.declaredDisplayNames.set(p.manifest.name, p.displayName);
+            const valid = configValid.get(p.manifest.name);
+            if (valid !== undefined)
+                this.configValidity.set(p.manifest.name, valid);
+        }
+        this.registry.declare(inspected.map((p) => p.manifest.name));
     }
     /**
      * Imports each extension module (default export) and initializes them in dependency order; may be
@@ -455,6 +541,7 @@ export class ExtensionHost {
         this.installLoader = p.installs;
         const entries = await importEntries(p.config ?? [], this.resolveFrom);
         await this.claimNames(entries);
+        await this.noteDisplayNames(entries);
         const dirs = new Map(entries.map((e) => [e.manifest.name, e.dir]));
         const urls = new Map(entries.map((e) => [e.manifest.name, e.url]));
         // 有安装记录时：配置声明的插件若 requires 只能由安装记录满足，先挑出来，等安装记录加载完再解析与加载
@@ -464,13 +551,14 @@ export class ExtensionHost {
         const ordered = resolveExtensions(ready, SDK_VERSION);
         for (const e of entries)
             this.sources.set(e.manifest.name, { source: "config", sha256: null });
+        this.registry.declare(entries.map((e) => e.manifest.name));
         for (const e of entries)
             assertSecretsReachable(e.manifest);
         const sets = await permissionSets(ordered, dirs);
         this.noteDeclared(ordered, sets);
-        const approvals = new ExtensionApprovals(kernelDb(this.deps.db));
+        const approvals = this.approvals;
         if (this.autoApprove) {
-            this.deps.log.warn("extensionPermissions.autoApprove is ON: plugin permissions are approved automatically without review; never enable this in production");
+            this.log.warn("extensionPermissions.autoApprove is ON: plugin permissions are approved automatically without review; never enable this in production");
         }
         const snapshots = ordered.length > 0 || p.installs ? await approvals.all() : new Map();
         const decisions = new Map(planApprovals(ordered, sets, snapshots, {
@@ -496,7 +584,7 @@ export class ExtensionHost {
                 desired = await p.installs.desired();
             }
             catch (e) {
-                this.deps.log.error("cannot read extension install records; installed extensions are not loaded", {
+                this.log.error("cannot read extension install records; installed extensions are not loaded", {
                     err: e,
                 });
             }
@@ -506,7 +594,7 @@ export class ExtensionHost {
                 // the first pass unloads nothing; the second skips what the first loaded.
                 const inPg = desired.filter((d) => d.blobStore === "pg");
                 if (inPg.length > 0 && inPg.length < desired.length) {
-                    await this.applyInstalls(p.installs, inPg, true);
+                    await this.applyInstalls(p.installs, inPg, true, desired);
                 }
                 installProviders = await this.applyInstalls(p.installs, desired, true);
             }
@@ -517,11 +605,28 @@ export class ExtensionHost {
         await this.refreshPolicyExpectations(p.installs ? desired : []);
         const orphans = Object.keys(this.extensionConfig).filter((k) => !this.sources.has(k));
         if (orphans.length > 0) {
-            this.deps.log.warn("extensionConfig has keys for extensions that are not loaded", {
+            this.log.warn("extensionConfig has keys for extensions that are not loaded", {
                 keys: orphans,
             });
         }
     }
+    /**
+     * Records each config-declared extension's display name from its plugin directory's plugin.json
+     * (spec §2.2); an invalid plugin.json only warns (no display name).
+     */
+    async noteDisplayNames(entries) {
+        for (const e of entries) {
+            const { displayName, problem } = await declaredDisplayName(e.dir, e.manifest.name);
+            if (displayName)
+                this.declaredDisplayNames.set(e.manifest.name, displayName);
+            if (problem !== undefined) {
+                this.log.warn("plugin.json of a config-declared extension is invalid; no display name", {
+                    plugin: e.manifest.name,
+                    problem,
+                });
+            }
+        }
+    }
     /**
      * Config-declared extensions also take their name (I4, an addition to Ruling P3): the
      * name is inserted into `extension_name_owners` with its npm package name (left alone when present).
@@ -533,7 +638,7 @@ export class ExtensionHost {
         for (const e of entries) {
             const pkg = await packageNameOf(e.dir);
             if (pkg === undefined) {
-                this.deps.log.warn("plugin module has no package.json name; its plugin name is not claimed", {
+                this.log.warn("plugin module has no package.json name; its plugin name is not claimed", {
                     plugin: e.manifest.name,
                 });
                 continue;
@@ -557,12 +662,12 @@ export class ExtensionHost {
             for (const o of owners) {
                 const mine = rows.find((r) => r.name === o.name);
                 if (mine && mine.package_name !== o.package_name) {
-                    this.deps.log.warn("plugin name is owned by a different npm package; the data, secrets and approval kept under this name came from that package", { plugin: o.name, owner: o.package_name, package: mine.package_name });
+                    this.log.warn("plugin name is owned by a different npm package; the data, secrets and approval kept under this name came from that package", { plugin: o.name, owner: o.package_name, package: mine.package_name });
                 }
             }
         }
         catch (err) {
-            this.deps.log.warn("cannot record plugin name owners", { err });
+            this.log.warn("cannot record plugin name owners", { err });
         }
     }
     /**
@@ -598,18 +703,15 @@ export class ExtensionHost {
      * 插件此刻的部署配置（未校验）：启动配置补上 PG 里保存的字段（C10，见构造参数 `deploymentConfig`）。
      */
     async rawConfigOf(name, schema) {
-        const fileValue = this.extensionConfig[name];
-        if (!this.storedConfig)
-            return fileValue ?? {};
-        return this.storedConfig(name, fileValue, schema);
+        return this.installs.effectiveDeploymentConfig(name, this.extensionConfig[name], schema);
     }
-    /** 把一份已校验部署配置里的密钥值交给 onSecrets（日志打码）。 */
+    /** 把一份已校验部署配置里的密钥值登记到日志打码。 */
     reportSecrets(schema, config) {
-        if (!schema || !this.onSecrets)
+        if (!schema)
             return;
         const values = secretValues(schema, config);
         if (values.length > 0)
-            this.onSecrets(values);
+            this.log.addSecrets(values);
     }
     /**
      * 安装记录收敛到 PG 期望状态（启动第 3 步与运行中的 {@link converge} 共用，C16）；`desired` 为期望启用的记录。
@@ -624,21 +726,36 @@ export class ExtensionHost {
      * 4. 运行中（非启动）：对变了的能力做依赖方连锁（本轮刚加载的除外），此前因依赖卸下的插件随之补回。
      * 返回启用的安装记录在静态清单里声明提供的能力（启动第 4 步据此判断待定还是缺提供方）。
      */
-    async applyInstalls(loader, desired, startup) {
+    async applyInstalls(loader, desired, startup, 
+    /**
+     * Every install record desired enabled, in {@link ExtensionInstalls.desired} order (the
+     * single-provider election runs over all of them even when `desired` is the startup's first
+     * pass over the packages kept in PG).
+     */
+    electAmong = desired) {
         const declared = this.declared();
         const installProviders = new Map();
         const wanted = new Map();
+        // Single-provider election: of the enabled install records providing one single-provider
+        // extension point, only the earliest enabled is loaded (desired() order: enabled_at, install
+        // time, name). Decided from PG alone, never from what loaded here, so every replica and every
+        // restart picks the same one. Two enabled providers only remain from before a second enable
+        // was refused; the others are pending / conflict until the super admin disables one. A loser
+        // provides nothing (left out of `installProviders`, so `blockedBy` never names it).
+        const { losers } = electSingleProviders(electAmong.filter((d) => !declared.has(d.name)));
         for (const d of desired) {
             const taken = declared.get(d.name);
             if (taken) {
                 if (!this.warnedConflicts.has(d.name)) {
                     this.warnedConflicts.add(d.name);
-                    this.deps.log.warn("plugin is both installed and declared in the extensions config list; using the config plugin", { plugin: d.name, installedVersion: d.version });
+                    this.log.warn("plugin is both installed and declared in the extensions config list; using the config plugin", { plugin: d.name, installedVersion: d.version });
                     // 该名字的状态行属于生效的一方，不覆盖；在它的 detail 里记下冲突（后台能看到）
                     await this.noteStatus(d.name, `name_conflict: install record ${d.version} (${d.sha256.slice(0, 16)}) ignored; the ${taken} plugin of the same name is used`);
                 }
                 continue;
             }
+            if (losers.has(d.name))
+                continue;
             wanted.set(d.name, d);
             // 按审阅过的静态清单（不论随后加载成败）
             for (const cap of d.section.manifest.provides) {
@@ -657,7 +774,7 @@ export class ExtensionHost {
                 changed.push(...gone.manifest.provides);
         }
         for (const [name, row] of [...this.installRows]) {
-            if (wanted.has(name) || this.registry.current(name))
+            if (wanted.has(name) || losers.has(name) || this.registry.current(name))
                 continue;
             this.dropPending(name);
             this.prepared.delete(name);
@@ -715,22 +832,30 @@ export class ExtensionHost {
         }
         for (const c of remaining) {
             let detail = "cannot resolve the plugin's dependencies";
+            let conflict = false;
             try {
                 tryResolve(c);
             }
             catch (e) {
                 detail = errMsg(e);
+                conflict = e instanceof ExtensionResolveError && e.code === PROVIDER_CONFLICT;
             }
+            // A single-provider point another extension already provides: a conflict, not a missing
+            // dependency. Converge tries it again on every pass, so it loads once the other is gone.
+            const reason = conflict ? "conflict" : "dependency";
             this.notePending({
                 plugin: c.d.name,
                 version: c.d.version,
                 added: [],
                 removed: [],
-                reason: "dependency",
+                reason,
                 blockedBy: (c.manifest.requires ?? []).map((extensionPoint) => ({
                     extensionPoint,
                     providers: (installProviders.get(extensionPoint) ?? []).filter((n) => n !== c.d.name),
                 })),
+                ...(conflict && {
+                    conflicts: conflictsOf(c.manifest, [...base(), ...accepted.map((a) => a.manifest)]),
+                }),
             });
             await this.writeStatus({
                 plugin: c.d.name,
@@ -738,11 +863,12 @@ export class ExtensionHost {
                 sha256: c.d.sha256,
                 source: "install",
                 state: "pending",
-                reason: "dependency",
+                reason,
                 detail,
             });
         }
         if (accepted.length === 0) {
+            await this.noteLosers(desired, losers);
             if (!startup && changed.length > 0)
                 await this.cascade(changed, drainMs);
             return installProviders;
@@ -752,7 +878,7 @@ export class ExtensionHost {
         // 4. 按拓扑序逐个：权限闸门 → 配置 → 迁移 → setup → 登记（替换旧实例）
         const order = resolveExtensions([...base(), ...accepted.map((a) => a.manifest)], SDK_VERSION);
         const byName = new Map(accepted.map((c) => [c.d.name, c]));
-        const approvals = new ExtensionApprovals(kernelDb(this.deps.db));
+        const approvals = this.approvals;
         const snapshots = await approvals.all();
         const activated = new Set();
         for (const m of order) {
@@ -782,10 +908,42 @@ export class ExtensionHost {
                 changed.push(...inst.manifest.provides, ...(old?.manifest.provides ?? []));
             }
         }
+        await this.noteLosers(desired, losers);
         if (!startup && changed.length > 0)
             await this.cascade(changed, drainMs, activated);
         return installProviders;
     }
+    /**
+     * Marks the losers of the single-provider election pending / conflict, naming the winner; after
+     * this pass loaded what it could, so a winner not loaded here (failed, pending) is known: the
+     * election stays (replicas must agree), but the loser's detail says the point has no running
+     * provider and the admin view warns about it.
+     */
+    async noteLosers(desired, losers) {
+        for (const d of desired) {
+            const lost = losers.get(d.name);
+            if (!lost)
+                continue;
+            const unloaded = this.registry.current(lost.winner) === undefined;
+            this.notePending({
+                plugin: d.name,
+                version: d.version,
+                added: [],
+                removed: [],
+                reason: "conflict",
+                conflicts: [{ extensionPoint: lost.extensionPoint, providers: [lost.winner] }],
+            });
+            await this.writeStatus({
+                plugin: d.name,
+                version: d.version,
+                sha256: d.sha256,
+                source: "install",
+                state: "pending",
+                reason: "conflict",
+                detail: providerConflictMessage(lost.extensionPoint, [lost.winner, d.name], unloaded ? lost.winner : undefined),
+            });
+        }
+    }
     /**
      * The load candidate of an install record: sync it locally, then compute the permission set from
      * the reviewed static manifest and the package's migration SQL (the same algorithm as
@@ -873,7 +1031,7 @@ export class ExtensionHost {
         if (this.loggedFailures.get(plugin) === key)
             return;
         this.loggedFailures.set(plugin, key);
-        this.deps.log.error("installed extension not loaded", {
+        this.log.error("installed extension not loaded", {
             plugin,
             sha256,
             reason,
@@ -973,15 +1131,46 @@ export class ExtensionHost {
             });
         }
     }
+    /**
+     * Checks the config UI hints of a loaded module's deployment and org schemas (spec §4.1). Invalid
+     * hints never fail the load: the form schemas drop their `x-ui` (`configFormSchema`), one warning
+     * per `<name>@<version>` is logged, and the returned text goes into the status detail (null when
+     * every hint is valid). The packer refuses such a package; this covers hand-made ones. It never
+     * throws (it runs after the instance is active, before its status row is written): a conversion
+     * that throws is warned about and reported in the detail the same way.
+     */
+    checkConfigUi(manifest) {
+        const parts = [];
+        for (const level of ["deployment", "org"]) {
+            const schema = manifest.config?.[level];
+            if (!schema)
+                continue;
+            try {
+                const { problems } = configFormSchema(schema, level);
+                if (problems.length > 0)
+                    parts.push(describeConfigUiProblems(level, problems));
+            }
+            catch (err) {
+                parts.push(`${level} config UI hints could not be checked (${err instanceof Error ? err.message : String(err)})`);
+            }
+        }
+        if (parts.length === 0)
+            return null;
+        const detail = parts.join("; ");
+        const key = `${manifest.name}@${manifest.version}`;
+        if (!this.configUiWarned.has(key)) {
+            this.configUiWarned.add(key);
+            this.log.warn("extension config UI hints are invalid and ignored: its config forms show plain fields", { plugin: manifest.name, version: manifest.version, detail });
+        }
+        return detail;
+    }
     /** 给已有状态行补说明；失败只记 warn。 */
     async noteStatus(plugin, detail) {
-        if (!this.status)
-            return;
         try {
             await this.status.note(plugin, detail);
         }
         catch (e) {
-            this.deps.log.warn("cannot write plugin replica status", { plugin, err: e });
+            this.log.warn("cannot write plugin replica status", { plugin, err: e });
         }
     }
     /**
@@ -1002,13 +1191,11 @@ export class ExtensionHost {
             else
                 this.installRows.set(s.plugin, { version: s.version, sha256: s.sha256 });
         }
-        if (!this.status)
-            return;
         try {
             await this.status.write(s);
         }
         catch (e) {
-            this.deps.log.warn("cannot write plugin replica status", { plugin: s.plugin, err: e });
+            this.log.warn("cannot write plugin replica status", { plugin: s.plugin, err: e });
         }
     }
     /**
@@ -1054,7 +1241,7 @@ export class ExtensionHost {
             if (this.closed)
                 throw new Error(CLOSED_DURING_LOAD, { cause: e });
             // 读不到 PG 里保存的部署配置：按待配置处理，下次 reconcile 再试
-            this.deps.log.error("cannot read the stored deployment config of plugin", {
+            this.log.error("cannot read the stored deployment config of plugin", {
                 plugin: name,
                 err: e,
             });
@@ -1068,7 +1255,9 @@ export class ExtensionHost {
             return undefined;
         }
         let config = raw;
-        const parsed = readConfig ? schema?.safeParse(raw) : undefined;
+        // the load gate (spec A §5.4a): overridable fields may stay empty on the platform, so
+        // `ctx.config` may lack them; hidden and read-only fields must be complete
+        const parsed = readConfig && schema ? parseLoadGate(schema, raw) : undefined;
         if (a.source !== "install")
             this.configValidity.set(name, parsed?.success ?? true);
         if (decision.action === "pending") {
@@ -1081,9 +1270,9 @@ export class ExtensionHost {
             // 每个周期都会重新判定：同一版本、同一原因只告警一次
             if (before?.version !== decision.pending.version ||
                 before.reason !== decision.pending.reason) {
-                warnPending(this.deps.log, decision.pending);
+                warnPending(this.log, decision.pending);
             }
-            const reason = decision.pending.reason === "dependency" ? "dependency" : "approval";
+            const reason = pendingReasonOf(decision.pending);
             await this.writeStatus({ ...base, state: "pending", reason, detail: null });
             return undefined;
         }
@@ -1092,7 +1281,7 @@ export class ExtensionHost {
         if (decision.changed) {
             if (decision.autoApprove) {
                 await approvals.approve(name, manifest.version, a.set, { source: "auto" });
-                this.deps.log.warn("plugin permissions auto-approved (extensionPermissions.autoApprove)", {
+                this.log.warn("plugin permissions auto-approved (extensionPermissions.autoApprove)", {
                     plugin: name,
                     version: manifest.version,
                     added: decision.added,
@@ -1104,7 +1293,7 @@ export class ExtensionHost {
                 const updated = await approvals.refresh(name, manifest.version, a.set);
                 const merged = decision.added.filter((k) => k.startsWith(UI_VIEW_KEY_PREFIX));
                 if (updated && merged.length > 0 && blockingKeys(decision.added).length === 0) {
-                    this.deps.log.info("plugin ui views merged into the permission snapshot", {
+                    this.log.info("plugin ui views merged into the permission snapshot", {
                         plugin: name,
                         version: manifest.version,
                         merged,
@@ -1121,7 +1310,7 @@ export class ExtensionHost {
                 // 待配置（C10）：配置声明与安装记录都一样，内核照常启动；配置改好后下一次 reconcile 加载
                 if (this.configWarned.get(name) !== detail) {
                     this.configWarned.set(name, detail);
-                    this.deps.log.warn("extension not loaded: its deployment config is missing or invalid (set it in the admin console or the startup config; it loads without a restart)", { plugin: name, source: a.source, detail });
+                    this.log.warn("extension not loaded: its deployment config is missing or invalid (set it in the admin console or the startup config; it loads without a restart)", { plugin: name, source: a.source, detail });
                 }
                 retryLater();
                 await this.writeStatus({ ...base, state: "pending", reason: "config", detail });
@@ -1183,16 +1372,23 @@ export class ExtensionHost {
         }
         if (this.closed) {
             await inst.dispose({ drainMs: 0 }).catch((err) => {
-                this.deps.log.warn("plugin context close failed", { plugin: name, err });
+                this.log.warn("plugin context close failed", { plugin: name, err });
             });
             throw new Error(CLOSED_DURING_LOAD);
         }
         // 升级：替换加载参数（之后的依赖方连锁与 reload 用新版本），先登记新实例、再撤销旧实例
         this.specs.set(name, spec);
+        if (a.source !== "install")
+            this.declaredActivations.set(name, a);
         this.unloadedForDependency.delete(name);
         const old = this.registry.activate(inst);
         this.loggedFailures.delete(name);
-        await this.writeStatus({ ...base, state: "loaded", reason: null, detail: null });
+        await this.writeStatus({
+            ...base,
+            state: "loaded",
+            reason: null,
+            detail: this.checkConfigUi(manifest),
+        });
         if (old)
             this.retire(old);
         return inst;
@@ -1204,7 +1400,7 @@ export class ExtensionHost {
     retire(old) {
         const p = this.disposeQuietly(old, this.drainMs()).finally(() => {
             this.retiring.delete(old);
-            this.deps.log.info("previous plugin instance retired", {
+            this.log.info("previous plugin instance retired", {
                 plugin: old.name,
                 generation: old.generation,
             });
@@ -1238,7 +1434,8 @@ export class ExtensionHost {
                 permissions: d.set,
                 configurable: schema !== undefined,
                 configValid: this.configValidity.get(name) ??
-                    (schema ? schema.safeParse(this.extensionConfig[name] ?? {}).success : true),
+                    (schema ? parseLoadGate(schema, this.extensionConfig[name] ?? {}).success : true),
+                displayName: this.declaredDisplayNames.get(name) ?? null,
             };
         });
     }
@@ -1281,7 +1478,7 @@ export class ExtensionHost {
      * `shrinkOnly`: only remove entries (a plugin no longer desired or approved), never add new ones.
      */
     async refreshPolicyExpectations(desired, opts = {}) {
-        const snapshots = await new ExtensionApprovals(kernelDb(this.deps.db)).all();
+        const snapshots = await this.approvals.all();
         const next = new Map();
         const add = (name, set) => {
             const mounts = set?.permissions?.policyHooks ?? [];
@@ -1330,7 +1527,7 @@ export class ExtensionHost {
     async activatePendingNow() {
         if (this.pendingActivations.size === 0)
             return [];
-        const approvals = new ExtensionApprovals(kernelDb(this.deps.db));
+        const approvals = this.approvals;
         const snapshots = await approvals.all();
         const activated = [];
         /** 本次已经试过且失败的：同一次不再重试（下一次 converge 再试）。 */
@@ -1356,7 +1553,7 @@ export class ExtensionHost {
                     if (this.closed)
                         throw e;
                     // 配置声明的插件迁移 / setup 出错时 activate 抛错（启动时内核失败）；运行中只记 failed
-                    this.deps.log.error("approved plugin not loaded", { plugin: name, err: e });
+                    this.log.error("approved plugin not loaded", { plugin: name, err: e });
                     await this.writeStatus({
                         plugin: name,
                         version: a.manifest.version,
@@ -1370,7 +1567,7 @@ export class ExtensionHost {
                 if (this.registry.current(name)) {
                     activated.push(name);
                     progress = true;
-                    this.deps.log.info("approved plugin loaded", { plugin: name });
+                    this.log.info("approved plugin loaded", { plugin: name });
                 }
                 else {
                     // 加载失败（迁移、setup）或待配置：留着，下一次 converge 重试（同一次不再试）
@@ -1436,7 +1633,7 @@ export class ExtensionHost {
             this.pendingPlugins.push(p);
         if (before?.reason === p.reason)
             return;
-        const reason = p.reason === "dependency" ? "dependency" : "approval";
+        const reason = pendingReasonOf(p);
         await this.writeStatus({
             plugin: p.plugin,
             version: a.manifest.version,
@@ -1453,7 +1650,7 @@ export class ExtensionHost {
     }
     /** 配置声明的插件名 → 来源（安装包不能与它们重名）。 */
     declared() {
-        return new Map([...this.sources].flatMap(([n, s]) => s.source === "install" ? [] : [[n, s.source]]));
+        return this.registry.declared();
     }
     /**
      * Extensions enabled in the org: `extension_org_configs.enabled` plus every required bootstrap
@@ -1476,6 +1673,7 @@ export class ExtensionHost {
             .all()
             .flatMap((i) => i.provided.has(ref) ? [{ plugin: i.name, impl: i.provided.get(ref) }] : []),
         enabledPlugins: (orgId) => this.enabledPlugins(orgId),
+        configOk: async (orgId, plugin) => (await this.effective.get(orgId, plugin)).ok,
     };
     get loadDeps() {
         return {
@@ -1496,7 +1694,7 @@ export class ExtensionHost {
      */
     async setup(spec, timeoutMs) {
         if (this.imports.record(spec.manifest.name, spec.entryUrl)) {
-            warnUpgrades(this.deps.log, this.imports);
+            warnUpgrades(this.log, this.imports);
         }
         let ctx;
         const p = setupInstance(this.loadDeps, spec.manifest, {
@@ -1534,7 +1732,7 @@ export class ExtensionHost {
             if (this.settingUp === ctx)
                 this.settingUp = undefined;
             await ctx?.close().catch((err) => {
-                this.deps.log.warn("plugin context close failed", { plugin: spec.manifest.name, err });
+                this.log.warn("plugin context close failed", { plugin: spec.manifest.name, err });
             });
             if (r === "closed")
                 throw new Error(CLOSED_DURING_LOAD);
@@ -1574,33 +1772,23 @@ export class ExtensionHost {
      * 实时取自注册表：调用方不要缓存实现对象（插件撤销 / 升级后旧实现不再有效）。
      */
     list(extensionPointName) {
-        const out = [];
-        const tracked = TRACKED_EXTENSION_POINTS[extensionPointName];
-        for (const i of this.registry.all()) {
-            for (const [cap, impl] of i.provided) {
-                if (parseExtensionPoint(cap).name === extensionPointName) {
-                    out.push({
-                        plugin: i.name,
-                        capability: cap,
-                        // 内核消费的提供方调用计入实例在途计数：停用 / 升级时先排空、到时限中止（C17）
-                        impl: tracked && typeof impl === "object" && impl !== null
-                            ? trackCalls(impl, i.inflight, tracked)
-                            : impl,
-                        version: i.version,
-                        configHash: i.configHash,
-                        inflight: i.inflight,
-                    });
-                }
-            }
-        }
-        return out;
+        return this.registry.list(extensionPointName);
     }
     /**
      * 已加载插件的部署配置（已按清单 schema 校验，含密钥），供内核调用该插件的能力时作为 `config` 传回
      * （如 `identity-source@1` 的登录配置）；未加载返回 undefined。不得回显到响应或日志。
      */
     deploymentConfig(plugin) {
-        return this.registry.current(plugin)?.config;
+        return this.registry.deploymentConfig(plugin);
+    }
+    /**
+     * The raw (unparsed) deployment config of a running extension: the startup config merged with
+     * the PG values, as the host reads it before parsing (secrets included; never echo it). An org
+     * copy is applied to this and parsed once (layering spec A §6), so schema transforms are not
+     * run twice. Without a running instance, the stored values without a schema.
+     */
+    rawDeploymentConfig(plugin) {
+        return this.rawConfigOf(plugin, this.registry.current(plugin)?.manifest.config?.deployment);
     }
     /**
      * 本副本拿得到的插件清单里的部署级 schema（生效实例 → 配置声明 → 安装记录准备好的候选）；
@@ -1622,7 +1810,9 @@ export class ExtensionHost {
     /**
      * 部署配置保存后（`kernel.plugin-deployment-config`）本副本重读并校验（C10；与 unload / reload 串行）：
      * - 插件没在本副本生效 → `not_loaded`（配置声明的刷新后台的合法性判定；待配置的由 reconcile 加载）；
-     * - 不合法 → `invalid`：保持当前值，告警；
+     * - 不合法 → `invalid`：保持当前值，告警；但 PG 里已没有保存的配置（超级管理员清空了，`DELETE
+     *   /api/v1/admin/extensions/:name/config`）、剩下的来源（启动配置、默认值）又不够时 → `unloaded`：卸下实例、
+     *   记为待配置（pending / config），依赖方连锁；重新配好后由 reconcile 加载；
      * - 没变 → `unchanged`；只改了 hot 字段 → `hot`：就地替换，插件经 `ctx.config` 读到新值，不重新 setup；
      * - 改了非 hot 字段 → `reload`：用新配置重新加载实例（先新后旧，排空在途调用），依赖方连锁；
      *   重新加载失败旧实例保留（`reload_failed`，记 error）。
@@ -1637,10 +1827,10 @@ export class ExtensionHost {
                 if (schema) {
                     try {
                         const raw = await this.rawConfigOf(plugin, schema);
-                        this.configValidity.set(plugin, schema.safeParse(raw).success);
+                        this.configValidity.set(plugin, parseLoadGate(schema, raw).success);
                     }
                     catch (err) {
-                        this.deps.log.warn("cannot read the stored deployment config of plugin", {
+                        this.log.warn("cannot read the stored deployment config of plugin", {
                             plugin,
                             err,
                         });
@@ -1656,12 +1846,16 @@ export class ExtensionHost {
                 raw = await this.rawConfigOf(plugin, schema);
             }
             catch (err) {
-                this.deps.log.error("cannot read the stored deployment config of plugin; keeping its current config", { plugin, err });
+                this.log.error("cannot read the stored deployment config of plugin; keeping its current config", { plugin, err });
                 return "invalid";
             }
-            const r = schema.safeParse(raw);
+            const r = parseLoadGate(schema, raw);
             if (!r.success) {
-                this.deps.log.warn("plugin deployment config changed but is invalid on this replica; keeping the current config", {
+                if (await this.clearedInPg(plugin)) {
+                    await this.unloadForMissingConfig(inst, toIssues(r.error));
+                    return "unloaded";
+                }
+                this.log.warn("plugin deployment config changed but is invalid on this replica; keeping the current config", {
                     plugin,
                     detail: toIssues(r.error)
                         .map((i) => `${i.path || "<root>"}: ${i.message}`)
@@ -1684,7 +1878,7 @@ export class ExtensionHost {
             this.specs.set(plugin, { ...spec, config: next, configHash });
             if (changed.every((p) => hot.has(p))) {
                 inst.updateConfig(next, configHash);
-                this.deps.log.info("plugin deployment config updated in place (hot fields)", {
+                this.log.info("plugin deployment config updated in place (hot fields)", {
                     plugin,
                     changed,
                 });
@@ -1702,21 +1896,110 @@ export class ExtensionHost {
                     this.specs.set(plugin, spec);
                 if (this.closed)
                     throw err;
-                this.deps.log.error("plugin reload after a deployment config change failed; it keeps its previous instance", { plugin, changed, err });
+                this.log.error("plugin reload after a deployment config change failed; it keeps its previous instance", { plugin, changed, err });
                 return "reload_failed";
             }
             await this.cascade(fresh.manifest.provides, drainMs);
-            this.deps.log.info("plugin reloaded after a deployment config change", { plugin, changed });
+            this.log.info("plugin reloaded after a deployment config change", { plugin, changed });
             return "reload";
         });
     }
+    /** PG holds no deployment config for the plugin (it was cleared); a read error counts as no. */
+    async clearedInPg(plugin) {
+        try {
+            return !(await this.installs.hasStoredDeploymentConfig(plugin));
+        }
+        catch (err) {
+            this.log.warn("cannot read whether the plugin has a stored deployment config", {
+                plugin,
+                err,
+            });
+            return false;
+        }
+    }
+    /**
+     * Unloads an extension whose deployment config was cleared and is now missing or invalid (in
+     * the host's serial queue): drains it, records pending / config (a config-declared one goes back
+     * to {@link pendingActivations}; an install record is decided again on every converge) and
+     * cascades to its dependents. It loads again without a restart once it is configured.
+     */
+    async unloadForMissingConfig(inst, issues) {
+        const plugin = inst.name;
+        const drainMs = this.drainMs();
+        const gone = await this.doUnload(plugin, drainMs, null);
+        if (!gone)
+            return;
+        await this.markPendingConfig({ plugin, version: gone.version, sha256: gone.sha256, source: gone.source }, issues, "extension unloaded: its deployment config was cleared and what remains is missing or invalid (set it in the admin console or the startup config; it loads without a restart)");
+        await this.cascade(gone.manifest.provides, drainMs);
+    }
+    /**
+     * Records an extension that is not loaded as pending configuration: a config-declared one goes
+     * back to {@link pendingActivations} (a later save loads it); an install record is decided again
+     * on every converge.
+     */
+    async markPendingConfig(p, issues, message) {
+        const detail = issues.map((i) => `${i.path || "<root>"}: ${i.message}`).join("; ");
+        const declared = this.declaredActivations.get(p.plugin);
+        if (p.source !== "install") {
+            this.configValidity.set(p.plugin, false);
+            if (declared)
+                this.pendingActivations.set(p.plugin, { ...declared, fatal: false });
+        }
+        this.configWarned.set(p.plugin, detail);
+        this.log.warn(message, { plugin: p.plugin, source: p.source, detail });
+        await this.writeStatus({ ...p, state: "pending", reason: "config", detail });
+    }
+    /**
+     * Before an extension unloaded for a dependency comes back ({@link cascade}): re-reads its
+     * deployment config, which may have been saved or cleared while it was down (applyDeploymentConfig
+     * only records validity then), and refreshes its load parameters, so it never returns on a stale
+     * config or revoked secrets. Returns false when the config is now missing or invalid and PG holds
+     * none: the extension is left pending configuration instead. A read error, or an invalid config
+     * that is still stored, keeps the previous config (as for a loaded extension).
+     */
+    async refreshConfigForRestore(name, spec) {
+        const schema = spec.manifest.config?.deployment;
+        if (!schema)
+            return true;
+        let raw;
+        try {
+            raw = await this.rawConfigOf(name, schema);
+        }
+        catch (err) {
+            this.log.error("cannot read the stored deployment config of plugin; restoring it on its previous config", { plugin: name, err });
+            return true;
+        }
+        const r = parseLoadGate(schema, raw);
+        if (!r.success) {
+            if (!(await this.clearedInPg(name)))
+                return true;
+            await this.markPendingConfig({
+                plugin: name,
+                version: spec.manifest.version,
+                sha256: spec.sha256,
+                source: spec.source,
+            }, toIssues(r.error), "extension not restored after its dependency came back: its deployment config was cleared and what remains is missing or invalid (set it in the admin console or the startup config; it loads without a restart)");
+            return false;
+        }
+        if (spec.source !== "install")
+            this.configValidity.set(name, true);
+        if (changedPaths(schema, spec.config, r.data).length > 0) {
+            this.reportSecrets(schema, r.data);
+            this.specs.set(name, {
+                ...spec,
+                config: r.data,
+                configHash: deploymentConfigHash(schema, r.data),
+            });
+        }
+        return true;
+    }
     /** 本次未加载、等待批准权限的插件（含因 `requires` 只能由它们满足而未加载的插件），按依赖拓扑序。 */
     pending() {
         return structuredClone(this.pendingPlugins);
     }
     /** 已加载插件的清单（按加载顺序，即依赖拓扑序）。 */
     manifests() {
-        return this.registry.all().map((i) => i.manifest);
+        return this.registry.manifests();
     }
     /** 已加载插件的权限集合（加载时计算，清单不可变）；未加载返回 undefined。 */
     permissionSet(plugin) {
@@ -1756,15 +2039,13 @@ export class ExtensionHost {
     }
     /** 安装记录里的插件名（缓存，见 {@link unavailable}）。 */
     installed() {
-        const load = this.installedNames;
-        if (!load)
-            return Promise.resolve(new Set());
         const now = Date.now();
         if (!this.installedCache || now - this.installedCache.at > KNOWN_NAMES_TTL_MS) {
-            const names = load()
+            const names = this.installs
+                .installedNames()
                 .then((xs) => new Set(xs))
                 .catch((err) => {
-                this.deps.log.warn("cannot read plugin install records for the route gate", { err });
+                this.log.warn("cannot read plugin install records for the route gate", { err });
                 this.installedCache = undefined;
                 return new Set();
             });
@@ -1881,7 +2162,7 @@ export class ExtensionHost {
             reason,
             detail: null,
         });
-        this.deps.log.info("plugin unloaded", { plugin, generation: inst.generation, reason });
+        this.log.info("plugin unloaded", { plugin, generation: inst.generation, reason });
         return inst;
     }
     /** 新建实例并原子替换、撤销旧实例（不做连锁）。 */
@@ -1913,11 +2194,11 @@ export class ExtensionHost {
             source: inst.source,
             state: "loaded",
             reason: null,
-            detail: null,
+            detail: this.checkConfigUi(spec.manifest),
         });
         if (old)
             await this.disposeQuietly(old, drainMs);
-        this.deps.log.info("plugin reloaded", { plugin, generation: inst.generation });
+        this.log.info("plugin reloaded", { plugin, generation: inst.generation });
         return inst;
     }
     /** 生效实例按依赖拓扑排序（解析不了时退回注册表顺序）。 */
@@ -1971,7 +2252,7 @@ export class ExtensionHost {
             catch (err) {
                 if (this.closed)
                     throw err;
-                this.deps.log.error("dependent plugin reload failed; it keeps its previous instance", {
+                this.log.error("dependent plugin reload failed; it keeps its previous instance", {
                     plugin: name,
                     err,
                 });
@@ -1989,6 +2270,10 @@ export class ExtensionHost {
                 const available = providedNow();
                 if (!(spec.manifest.requires ?? []).every((c) => available.has(c)))
                     continue;
+                if (!(await this.refreshConfigForRestore(name, spec))) {
+                    this.unloadedForDependency.delete(name);
+                    continue;
+                }
                 try {
                     await this.doReload(name, drainMs);
                     progress = true;
@@ -1996,7 +2281,7 @@ export class ExtensionHost {
                 catch (err) {
                     if (this.closed)
                         throw err;
-                    this.deps.log.error("plugin reload after its dependency came back failed", {
+                    this.log.error("plugin reload after its dependency came back failed", {
                         plugin: name,
                         err,
                     });
@@ -2012,7 +2297,7 @@ export class ExtensionHost {
             await inst.dispose({ drainMs, disposeTimeoutMs: this.disposeTimeoutMs() });
         }
         catch (err) {
-            this.deps.log.error("plugin dispose failed", { plugin: inst.name, err });
+            this.log.error("plugin dispose failed", { plugin: inst.name, err });
         }
     }
     /**
@@ -2026,32 +2311,20 @@ export class ExtensionHost {
         this.closed = true;
         this.abort.abort();
         await this.migrating?.catch(() => { });
-        let timer;
-        await Promise.race([
-            this.lifecycle.catch(() => { }),
-            new Promise((resolve) => {
-                timer = setTimeout(resolve, opts.lifecycleWaitMs ?? CLOSE_LIFECYCLE_WAIT_MS);
-            }),
-        ]);
-        clearTimeout(timer);
+        const lifecycleWaitMs = opts.lifecycleWaitMs ?? CLOSE_LIFECYCLE_WAIT_MS;
+        await waitWithin(this.lifecycle.catch(() => { }), lifecycleWaitMs);
         // 升级时被替换、后台排空中的旧实例：同样最多等 lifecycleWaitMs，之后强制撤销（中止在途调用、不再排空），
         // 赶在共用资源（Redis / PG）关闭之前
         if (this.retiring.size > 0) {
-            await Promise.race([
-                Promise.allSettled([...this.retiring.values()]),
-                new Promise((resolve) => {
-                    timer = setTimeout(resolve, opts.lifecycleWaitMs ?? CLOSE_LIFECYCLE_WAIT_MS);
-                }),
-            ]);
-            clearTimeout(timer);
+            await waitWithin(Promise.allSettled([...this.retiring.values()]), lifecycleWaitMs);
             await Promise.allSettled([...this.retiring.keys()].map((old) => old.hurry().catch((err) => {
-                this.deps.log.warn("plugin close failed", { plugin: old.name, err });
+                this.log.warn("plugin close failed", { plugin: old.name, err });
             })));
         }
         const settingUp = this.settingUp;
         this.settingUp = undefined;
         await settingUp?.close().catch((e) => {
-            this.deps.log.error("plugin close failed", { err: e });
+            this.log.error("plugin close failed", { err: e });
         });
         for (const inst of this.registry.all().reverse()) {
             this.registry.deactivate(inst.name);
@@ -2061,11 +2334,30 @@ export class ExtensionHost {
                     waitQueueJobs: true,
                     disposeTimeoutMs: this.disposeTimeoutMs(),
                 });
-                this.deps.log.info("plugin closed", { plugin: inst.name });
+                this.log.info("plugin closed", { plugin: inst.name });
             }
             catch (e) {
-                this.deps.log.error("plugin close failed", { plugin: inst.name, err: e });
+                this.log.error("plugin close failed", { plugin: inst.name, err: e });
             }
         }
     }
-}
+};
+ExtensionHost = __decorate([
+    Injectable(),
+    __param(0, Inject(ExtensionRegistry)),
+    __param(1, Inject(ExtensionInstalls)),
+    __param(2, Inject(ExtensionApprovals)),
+    __param(3, Inject(ReplicaStatusStore)),
+    __param(4, Inject(KernelConfigService)),
+    __param(5, Inject(KernelDb)),
+    __param(6, Inject(REDIS)),
+    __param(7, Inject(REDIS_SUBSCRIBER)),
+    __param(8, Inject(KEYRING)),
+    __param(9, Inject(EmbedTokens)),
+    __param(10, Inject(LockService)),
+    __param(11, Inject(KERNEL_LOGGER)),
+    __param(12, Inject(KERNEL_APP_OPTIONS)),
+    __param(13, Inject(EffectiveConfigs)),
+    __param(14, Inject(ModelEmbeddings))
+], ExtensionHost);
+export { ExtensionHost };