@capybara-hq/kernel 0.1.0-rc.2 → 0.1.0-rc.20

package/dist/extensions/host.js

@@ -7,14 +7,13 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
-import { createHash } from "node:crypto";
 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 { Inject, Injectable } from "@nestjs/common";
-import { changedPaths, configFields, getPath, secretValues, setPath, unreachableSecrets, } from "../config/fields.js";
+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";
@@ -25,56 +24,26 @@ 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 { EmbedTokens } from "../ui/embed-token.js";
 import { ExtensionApprovals, planApprovals, readSnapshots, withPreApproved, } from "./approvals.js";
 import { ExtensionBlobIntegrityError } from "./blobs.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 { permissionSetOfSection, readMigrationSql } from "./package.js";
-import { blockingKeys, computePermissionSet, UI_VIEW_KEY_PREFIX, } from "./permission-set.js";
+import { parseLoadGate } from "./org-levels.js";
+import { declaredDisplayName, permissionSetOfSection, readMigrationSql } from "./package.js";
+import { blockingKeys, computePermissionSet, SETUP_CHECK_KEY_PREFIX, 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";
 /** 停机时等进行中的 unload / reload 的上限（之后直接关闭 setup 中的 ctx、撤销其余实例）。 */
 const CLOSE_LIFECYCLE_WAIT_MS = 2_000;
@@ -162,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
@@ -171,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）；返回已应用的文件，
@@ -234,6 +226,7 @@ let ExtensionHost = class ExtensionHost {
     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
@@ -298,12 +291,18 @@ let ExtensionHost = 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;
     }
     /**
      * M-1: plugin → mount points where deployment state expects `policy` hooks. A per-replica copy of PG
@@ -335,6 +334,11 @@ let ExtensionHost = 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 用，含待配置而未加载的）。 */
@@ -351,6 +355,11 @@ let ExtensionHost = 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;
@@ -370,6 +379,8 @@ let ExtensionHost = class ExtensionHost {
     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
@@ -393,14 +404,32 @@ let ExtensionHost = class ExtensionHost {
      */
     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) {
+    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),
+            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,
@@ -410,19 +439,13 @@ let ExtensionHost = class ExtensionHost {
             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.hooks = new HookRegistry({
-            instances: () => this.registry.all(),
-            current: (plugin) => this.registry.current(plugin),
-            expectedPolicy: (mount) => this.expectedPolicy(mount),
-            enabledPlugins: (orgId) => this.enabledPlugins(orgId),
-            locks,
-            config: () => ({ hooks: { timeoutMs: this.config.get().hooks.timeoutMs } }),
-            log,
-        });
         this.registry.onChange(() => {
             this.installedCache = undefined;
         });
@@ -461,6 +484,8 @@ let ExtensionHost = class ExtensionHost {
                 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);
@@ -516,6 +541,7 @@ let ExtensionHost = 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 只能由安装记录满足，先挑出来，等安装记录加载完再解析与加载
@@ -568,7 +594,7 @@ let ExtensionHost = 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);
             }
@@ -584,6 +610,23 @@ let ExtensionHost = class ExtensionHost {
             });
         }
     }
+    /**
+     * 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).
@@ -683,10 +726,23 @@ let ExtensionHost = 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) {
@@ -698,6 +754,8 @@ let ExtensionHost = class ExtensionHost {
                 }
                 continue;
             }
+            if (losers.has(d.name))
+                continue;
             wanted.set(d.name, d);
             // 按审阅过的静态清单（不论随后加载成败）
             for (const cap of d.section.manifest.provides) {
@@ -716,7 +774,7 @@ let ExtensionHost = 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);
@@ -774,22 +832,30 @@ let ExtensionHost = 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,
@@ -797,11 +863,12 @@ let ExtensionHost = 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;
@@ -841,10 +908,42 @@ let ExtensionHost = 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
@@ -1032,6 +1131,39 @@ let ExtensionHost = 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) {
         try {
@@ -1044,15 +1176,24 @@ let ExtensionHost = class ExtensionHost {
     /**
      * 写本副本的加载状态；失败只记 warn（状态是给后台看的，不影响加载）。这一行的版本没加载成（failed / pending）
      * 而本副本仍有别的版本在跑时，记下那个版本（`servingVersion`，后台同时显示「新版失败、旧版仍在服务」）。
+     * `servingSha256` is the package this replica actually serves for the plugin (client code follows
+     * it, client extensions spec §9.3): the row's own package when loaded; for a failed / pending row
+     * the package of the instance still running here (an older one, or the row's own package when it
+     * stays loaded, e.g. beside a provider conflict), else null.
      */
     async writeStatus(s) {
-        if (s.servingVersion === undefined && (s.state === "failed" || s.state === "pending")) {
-            const cur = this.registry.current(s.plugin);
-            s = {
-                ...s,
-                servingVersion: cur && (cur.sha256 !== s.sha256 || cur.version !== s.version) ? cur.version : null,
-            };
-        }
+        const waiting = s.state === "failed" || s.state === "pending";
+        const cur = waiting ? this.registry.current(s.plugin) : undefined;
+        const other = cur && (cur.sha256 !== s.sha256 || cur.version !== s.version) ? cur : null;
+        s = {
+            ...s,
+            ...(waiting && s.servingVersion === undefined && { servingVersion: other?.version ?? null }),
+            servingSha256: s.servingSha256 !== undefined
+                ? s.servingSha256
+                : s.state === "loaded"
+                    ? s.sha256
+                    : (cur?.sha256 ?? null),
+        };
         if (s.source === "install") {
             if (s.state === "unloaded")
                 this.installRows.delete(s.plugin);
@@ -1123,7 +1264,9 @@ let ExtensionHost = 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") {
@@ -1138,7 +1281,7 @@ let ExtensionHost = class ExtensionHost {
                 before.reason !== decision.pending.reason) {
                 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;
         }
@@ -1157,9 +1300,9 @@ let ExtensionHost = class ExtensionHost {
                 // 权限变少、不变（版本变了）或只多出视图（ui.view:*，不卡加载）：直接加载，快照跟上当前清单。
                 // 补进视图不写审计（与 autoApprove 一样，Ruling A4），只记日志
                 const updated = await approvals.refresh(name, manifest.version, a.set);
-                const merged = decision.added.filter((k) => k.startsWith(UI_VIEW_KEY_PREFIX));
+                const merged = decision.added.filter((k) => k.startsWith(UI_VIEW_KEY_PREFIX) || k.startsWith(SETUP_CHECK_KEY_PREFIX));
                 if (updated && merged.length > 0 && blockingKeys(decision.added).length === 0) {
-                    this.log.info("plugin ui views merged into the permission snapshot", {
+                    this.log.info("plugin ui views and setup checks merged into the permission snapshot", {
                         plugin: name,
                         version: manifest.version,
                         merged,
@@ -1244,10 +1387,17 @@ let ExtensionHost = class ExtensionHost {
         }
         // 升级：替换加载参数（之后的依赖方连锁与 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;
@@ -1293,7 +1443,8 @@ let ExtensionHost = 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,
             };
         });
     }
@@ -1491,7 +1642,7 @@ let ExtensionHost = 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,
@@ -1531,6 +1682,7 @@ let ExtensionHost = 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 {
@@ -1569,7 +1721,7 @@ let ExtensionHost = class ExtensionHost {
             },
         });
         if (timeoutMs === undefined)
-            return p;
+            return p.then((inst) => this.logUiResolution(inst));
         let timer;
         let onClose = () => { };
         const stop = new Promise((resolve) => {
@@ -1582,8 +1734,9 @@ let ExtensionHost = class ExtensionHost {
         });
         try {
             const r = await Promise.race([p.then((inst) => ({ inst })), stop]);
+            // a late instance that is disposed right away never logs its UI resolution
             if (typeof r === "object")
-                return r.inst;
+                return this.logUiResolution(r.inst);
             // setup 迟迟不返回：关闭它的 ctx（此后它的登记立即撤销），迟到完成的实例直接撤销
             p.then((inst) => this.disposeQuietly(inst, 0), () => { });
             if (this.settingUp === ctx)
@@ -1600,6 +1753,20 @@ let ExtensionHost = class ExtensionHost {
             this.abort.signal.removeEventListener("abort", onClose);
         }
     }
+    /** Logs once per load what slot resolution left out or flagged (UI slots spec §3.2). */
+    logUiResolution(inst) {
+        const at = { plugin: inst.name, version: inst.version };
+        if (inst.uiDropped.length > 0) {
+            this.log.warn("plugin ui contributions dropped", { ...at, dropped: inst.uiDropped });
+        }
+        if (inst.uiUnknownAnchors.length > 0) {
+            this.log.warn("plugin ui anchors unknown", { ...at, anchors: inst.uiUnknownAnchors });
+        }
+        if (inst.uiDeprecatedPlace.length > 0) {
+            this.log.info("plugin ui uses the deprecated place", { ...at, ids: inst.uiDeprecatedPlace });
+        }
+        return inst;
+    }
     /** 取能力实现：单选能力无需 providerName，多选能力必须指定。 */
     get(capability, providerName) {
         const providers = this.registry.all().filter((i) => i.provided.has(capability));
@@ -1638,6 +1805,15 @@ let ExtensionHost = class ExtensionHost {
     deploymentConfig(plugin) {
         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（生效实例 → 配置声明 → 安装记录准备好的候选）；
      * 都没有返回 undefined（如未加载的安装记录：调用方改用包内静态清单）。
@@ -1658,7 +1834,9 @@ let ExtensionHost = 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）。
@@ -1673,7 +1851,7 @@ let ExtensionHost = 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.log.warn("cannot read the stored deployment config of plugin", {
@@ -1695,8 +1873,12 @@ let ExtensionHost = class ExtensionHost {
                 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) {
+                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)
@@ -1746,6 +1928,95 @@ let ExtensionHost = class ExtensionHost {
             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);
@@ -1840,17 +2111,25 @@ let ExtensionHost = class ExtensionHost {
      * 是否在某组织启用由调用方另查（每次查询，不缓存）。
      */
     uiContributions() {
-        return this.registry.all().flatMap((i) => (i.manifest.ui ?? []).map((c) => {
-            const render = c.kind === "view" ? i.uiViews.get(c.id) : undefined;
-            const action = c.kind === "view" ? i.uiActions.get(c.id) : undefined;
+        return this.registry.all().flatMap((i) => i.ui.map(({ contribution: c, slot, after }) => {
+            // a view's, or a component's server view (client extensions spec §5.2); embeds have none
+            const served = c.kind === "view" || c.kind === "component";
+            const render = served ? i.uiViews.get(c.id) : undefined;
+            const action = served ? i.uiActions.get(c.id) : undefined;
             return {
                 plugin: i.name,
                 contribution: c,
+                slot,
+                ...(after !== undefined && { after }),
                 ...(render !== undefined && { render }),
                 ...(action !== undefined && { action }),
             };
         }));
     }
+    /** The UI contributions the loaded extension left out at load (UI slots spec §3.2); `[]` when not loaded. */
+    uiDropped(name) {
+        return [...(this.registry.current(name)?.uiDropped ?? [])];
+    }
     /** 串行执行生命周期操作（unload / reload 互不交错）；宿主关闭后拒绝。 */
     serial(fn) {
         const guarded = () => {
@@ -1947,7 +2226,7 @@ let ExtensionHost = class ExtensionHost {
             source: inst.source,
             state: "loaded",
             reason: null,
-            detail: null,
+            detail: this.checkConfigUi(spec.manifest),
         });
         if (old)
             await this.disposeQuietly(old, drainMs);
@@ -2023,6 +2302,10 @@ let ExtensionHost = 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;
@@ -2105,6 +2388,8 @@ ExtensionHost = __decorate([
     __param(9, Inject(EmbedTokens)),
     __param(10, Inject(LockService)),
     __param(11, Inject(KERNEL_LOGGER)),
-    __param(12, Inject(KERNEL_APP_OPTIONS))
+    __param(12, Inject(KERNEL_APP_OPTIONS)),
+    __param(13, Inject(EffectiveConfigs)),
+    __param(14, Inject(ModelEmbeddings))
 ], ExtensionHost);
 export { ExtensionHost };