@capybara-hq/kernel 0.1.0-rc.3 → 0.1.0-rc.5

package/dist/extensions/hooks.js

@@ -1,4 +1,5 @@
 import { HOOKS_AVAILABLE, POLICY_HOOKS, } from "@capybara-hq/plugin-sdk";
+import { NEEDS_CONFIG_REASON } from "./effective-config.js";
 import { ExtensionUnloadedError } from "./inflight.js";
 /** Default of `hooks.timeoutMs` (used when a host is built without kernel config, e.g. in tests). */
 export const DEFAULT_HOOK_TIMEOUT_MS = 5000;
@@ -13,6 +14,18 @@ export const OBSERVE_INFLIGHT_MAX = 64;
 export const EMPTY_DENY_REASON = "(no reason given)";
 /** Warnings about a plugin's hooks are logged at most once per plugin, mount and kind in this window. */
 const WARN_WINDOW_MS = 60_000;
+/**
+ * Thrown by a `usage.report` handler wrapper (see {@link HookRegistry.handlers}) instead of calling
+ * a handler whose extension's effective config is not valid in the payload's organization.
+ */
+export class HookNeedsConfigError extends Error {
+    plugin;
+    constructor(plugin) {
+        super(`extension ${plugin} ${NEEDS_CONFIG_REASON}`);
+        this.plugin = plugin;
+        this.name = "HookNeedsConfigError";
+    }
+}
 const AVAILABLE = new Set(HOOKS_AVAILABLE);
 const POLICY = new Set(POLICY_HOOKS);
 /** Error text that never throws itself (a hostile `message` getter or `toString`). */
@@ -110,7 +123,12 @@ const clipDetail = (s) => clipText(s, HOOK_DETAIL_MAX_CHARS);
  *    If a plugin the organization enabled is expected to run policy hooks on the mount (deployment
  *    state, `expectedPolicy`) but is not loaded on this replica, deny with a generic reason
  *    (`hook_error`, `notLoaded`) without running any policy hook (M-1: fail closed). Observe hooks
- *    of plugins that are not loaded are simply missing.
+ *    of plugins that are not loaded are simply missing. Then each enabled plugin with a hook on the
+ *    mount gets its effective config for the organization (layering spec A §6; one read per plugin
+ *    and call, failing like the lookup above). A plugin whose config is not valid behaves as one
+ *    that is not loaded: with a policy hook on the mount the call is denied (`hook_error`,
+ *    `needsConfig`) without running any policy hook, and its observe hooks are skipped. Every
+ *    hook is called with `{ config }` as its third argument.
  * 3. Policy hooks run serially by plugin name (registration order within a plugin), each limited
  *    by `hooks.timeoutMs` (read on every run, hot). `{ deny }`, an error or a timeout stops the chain
  *    and denies (`deny` / `hook_error` / `timeout`). A policy hook cut off by its instance being
@@ -156,13 +174,18 @@ export class HookRegistry {
     }
     /**
      * `usage.report` handlers by plugin name (delivered by the usage queue, not by {@link run}); each
-     * call runs through the instance's `inflight.run`.
+     * call runs through the instance's `inflight.run` with the plugin's effective config for the
+     * payload's organization, and throws {@link HookNeedsConfigError} without calling the handler
+     * when that config is not valid (layering spec A §6).
      */
     handlers(mount) {
         return this.entries(mount).map(({ src, hook }) => ({
             plugin: src.name,
             handler: (payload, signal) => src.inflight.run(signal, async (s) => {
-                await hook.handler(payload, s);
+                const effective = await this.d.effectiveConfig(payload.orgId, src.name);
+                if (!effective.ok)
+                    throw new HookNeedsConfigError(src.name);
+                await hook.handler(payload, s, { config: effective.config });
             }),
         }));
     }
@@ -177,6 +200,8 @@ export class HookRegistry {
         let enabled;
         let frozen;
         let missing;
+        /** Effective config per enabled plugin with a hook here; null = not valid in the org. */
+        const configs = new Map();
         try {
             const abort = abortOf(signal);
             try {
@@ -194,6 +219,19 @@ export class HookRegistry {
             }
             if (!all.some((e) => enabled.has(e.src.name)))
                 return { allowed: true };
+            for (const name of new Set(all.map((e) => e.src.name).filter((n) => enabled.has(n)))) {
+                const abortCfg = abortOf(signal);
+                try {
+                    const e = await Promise.race([
+                        this.d.effectiveConfig(payload.orgId, name),
+                        abortCfg.aborted,
+                    ]);
+                    configs.set(name, e.ok ? { config: e.config } : null);
+                }
+                finally {
+                    abortCfg.cleanup();
+                }
+            }
             // Cost: one clone + deep-freeze per call. The model.request payload carries no media bytes
             // (hookRequestOf, I-3), so it stays small. Freezing in place would freeze the logged object.
             // The clone is skipped when has() is false or no enabled plugin has a hook on this mount.
@@ -207,7 +245,7 @@ export class HookRegistry {
             if (firstPolicy !== undefined) {
                 // R10: no plugin ran; the named plugin is only the first policy plugin on this mount, so
                 // the detail says so instead of blaming it
-                const detail = clipDetail(`Hooks could not run (organization lookup or payload copy failed) before any plugin was called; ${firstPolicy} is named only as the first policy plugin on ${mount}: ${raw}`);
+                const detail = clipDetail(`Hooks could not run (organization lookup, config read or payload copy failed) before any plugin was called; ${firstPolicy} is named only as the first policy plugin on ${mount}: ${raw}`);
                 this.d.log.warn("plugin hooks could not run; denying the call", {
                     mount,
                     firstPolicyPlugin: firstPolicy,
@@ -227,9 +265,19 @@ export class HookRegistry {
             }
             return { allowed: true };
         }
-        const active = all.filter((e) => enabled.has(e.src.name));
+        const active = all.filter((e) => enabled.has(e.src.name) && configs.get(e.src.name));
         const timeoutMs = this.d.config().hooks.timeoutMs;
-        let outcome = missing.length > 0 ? this.notLoadedDenial(mount, missing) : { allowed: true };
+        // spec A §6: a policy plugin without a valid config in the org behaves as one not loaded
+        const needy = [
+            ...new Set(all
+                .filter((e) => e.hook.mode === "policy" && configs.get(e.src.name) === null)
+                .map((e) => e.src.name)),
+        ];
+        let outcome = missing.length > 0
+            ? this.notLoadedDenial(mount, missing)
+            : needy.length > 0
+                ? this.needsConfigDenial(mount, needy)
+                : { allowed: true };
         // policy hooks grouped per plugin (entries are sorted, so groups are contiguous)
         const groups = [];
         for (const e of active) {
@@ -242,7 +290,8 @@ export class HookRegistry {
                 groups.push({ src: e.src, hooks: [e.hook] });
         }
         for (const g of outcome.allowed ? groups : []) {
-            const denied = await this.runPolicies(mount, g.src, g.hooks, frozen, signal, timeoutMs);
+            const call = configs.get(g.src.name);
+            const denied = await this.runPolicies(mount, g.src, g.hooks, frozen, call, signal, timeoutMs);
             if (denied) {
                 outcome = denied;
                 break;
@@ -251,8 +300,10 @@ export class HookRegistry {
         // observe hooks are resolved again now: if the plugin was upgraded while the policy hooks ran,
         // the current generation observes (the retiring one no longer accepts calls)
         for (const e of this.entries(mount)) {
-            if (e.hook.mode === "observe" && enabled.has(e.src.name)) {
-                this.dispatchObserve(mount, e.src, e.hook, frozen, signal);
+            const call = configs.get(e.src.name);
+            // no config read for it (not valid in the org, or a plugin that appeared meanwhile): skipped
+            if (e.hook.mode === "observe" && enabled.has(e.src.name) && call) {
+                this.dispatchObserve(mount, e.src, e.hook, frozen, call, signal);
             }
         }
         return outcome;
@@ -277,6 +328,21 @@ export class HookRegistry {
             notLoaded: true,
         };
     }
+    /**
+     * The layering spec A §6 denial: `needy` (sorted) are enabled policy plugins whose effective
+     * config is not valid in the organization. Generic model-visible reason, as for M-1.
+     */
+    needsConfigDenial(mount, needy) {
+        const plugin = needy[0];
+        return {
+            allowed: false,
+            plugin,
+            reason: unavailableReason(plugin),
+            cause: "hook_error",
+            detail: `extension ${needy.join(", ")} declares a policy hook on ${mount} but ${NEEDS_CONFIG_REASON}; the call was denied without running any policy hook`,
+            needsConfig: true,
+        };
+    }
     /** Active entries of a mount point, sorted by plugin name (stable: registration order within). */
     entries(mount) {
         return this.d
@@ -285,14 +351,14 @@ export class HookRegistry {
             .sort((a, b) => (a.src.name < b.src.name ? -1 : a.src.name > b.src.name ? 1 : 0));
     }
     /** One plugin's policy hooks in registration order; reruns once on a newer generation if revoked. */
-    async runPolicies(mount, src, hooks, payload, signal, timeoutMs, rerun = false) {
+    async runPolicies(mount, src, hooks, payload, call, signal, timeoutMs, rerun = false) {
         const plugin = src.name;
         for (const hook of hooks) {
             if (signal.aborted)
                 throw signal.reason;
             let r;
             try {
-                r = await src.inflight.run(signal, (s) => this.call(hook, payload, s, timeoutMs));
+                r = await src.inflight.run(signal, (s) => this.call(hook, payload, call, s, timeoutMs));
             }
             catch (err) {
                 if (signal.aborted)
@@ -301,7 +367,7 @@ export class HookRegistry {
                     const cur = this.d.current(plugin);
                     if (!rerun && cur && cur !== src) {
                         const again = cur.hooks.filter((h) => h.mount === mount && h.mode === "policy");
-                        return this.runPolicies(mount, cur, again, payload, signal, timeoutMs, true);
+                        return this.runPolicies(mount, cur, again, payload, call, signal, timeoutMs, true);
                     }
                 }
                 r = { kind: "error", message: errMsg(err) };
@@ -338,7 +404,7 @@ export class HookRegistry {
         return undefined;
     }
     /** Fire-and-forget observe call through the instance's in-flight tracker, capped per plugin. */
-    dispatchObserve(mount, src, hook, payload, signal) {
+    dispatchObserve(mount, src, hook, payload, call, signal) {
         const plugin = src.name;
         const n = this.observing.get(plugin) ?? 0;
         if (n >= OBSERVE_INFLIGHT_MAX) {
@@ -349,7 +415,7 @@ export class HookRegistry {
         this.observing.set(plugin, n + 1);
         void (async () => {
             try {
-                const r = await src.inflight.run(signal, (s) => this.call(hook, payload, s, timeoutMs));
+                const r = await src.inflight.run(signal, (s) => this.call(hook, payload, call, s, timeoutMs));
                 if (r.kind === "error" || r.kind === "timeout") {
                     await this.warnOnce(plugin, mount, "failed", "plugin observe hook failed; the call continued", r.kind === "timeout" ? `timed out after ${timeoutMs} ms` : r.message);
                 }
@@ -371,7 +437,7 @@ export class HookRegistry {
      * Calls one handler with its own signal (aborted on timeout or when `s` aborts). Rejects with
      * `s.reason` when `s` aborts first, so callers can tell an abort from a hook failure.
      */
-    async call(hook, payload, s, timeoutMs) {
+    async call(hook, payload, call, s, timeoutMs) {
         const ac = new AbortController();
         const onAbort = () => ac.abort(s.reason);
         if (s.aborted)
@@ -385,7 +451,7 @@ export class HookRegistry {
                 timer = setTimeout(() => resolve("timeout"), timeoutMs);
             });
             const handled = Promise.resolve()
-                .then(() => hook.handler(payload, ac.signal))
+                .then(() => hook.handler(payload, ac.signal, { config: call.config }))
                 .then((v) => ({ v }), (err) => ({ err }));
             const result = await Promise.race([handled, timedOut, abort.aborted]);
             if (result === "timeout") {

package/dist/extensions/host.d.ts

@@ -1,4 +1,4 @@
-import { type ExtensionManifest, type ExtensionPointRef, type ToolHandler, type ToolSpec, type UiContribution } from "@capybara-hq/plugin-sdk";
+import { type ExtensionManifest, type ExtensionPointRef, type LocalizedName, type ToolHandler, type ToolSpec, type UiContribution } from "@capybara-hq/plugin-sdk";
 import type { Redis } from "ioredis";
 import type { core } from "zod";
 import type { KernelAppOptions } from "../app.js";
@@ -13,6 +13,7 @@ import type { KernelLogger } from "../log.js";
 import { EmbedTokens } from "../ui/embed-token.js";
 import type { UiActionHandler, UiRender } from "../ui/registry.js";
 import { ExtensionApprovals, type PendingExtension } from "./approvals.js";
+import { EffectiveConfigs } from "./effective-config.js";
 import { HookRegistry } from "./hooks.js";
 import type { InflightTracker } from "./inflight.js";
 import { type DesiredExtension, ExtensionInstalls } from "./installs.js";
@@ -46,6 +47,8 @@ export interface InspectedExtension {
     dir: string;
     /** 规范化的权限集合，见 {@link computePermissionSet}。 */
     permissions: PermissionSet;
+    /** The plugin.json `displayName` of the module's plugin directory, if any. */
+    displayName: LocalizedName | null;
 }
 /**
  * 插件两级配置 schema 中的每个 `secret()` 都必须标在对象路径的字段上（见 `unreachableSecrets`），
@@ -84,6 +87,8 @@ export interface DeclaredExtensionInfo {
     configurable: boolean;
     /** 启动配置里的部署配置按 schema 校验通过（没有 schema 时恒为 true）。 */
     configValid: boolean;
+    /** The plugin.json `displayName` of the module's plugin directory, if any. */
+    displayName: LocalizedName | null;
 }
 /** The extension sources of {@link ExtensionHost.load}, loaded in this order (see {@link ExtensionSource}). */
 export interface ExtensionLoadPlan {
@@ -108,6 +113,11 @@ export declare class ExtensionHost {
     private readonly status;
     private readonly config;
     private readonly log;
+    /**
+     * Each hook call's effective config for its organization, and the providers excluded from an
+     * org's point resolution (layering spec A §6).
+     */
+    private readonly 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
@@ -191,6 +201,11 @@ export declare class ExtensionHost {
     private readonly retiring;
     /** 配置声明插件的清单与权限集合（含未加载的；后台列表与网页批准用）。 */
     private readonly declaredInfo;
+    /**
+     * 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).
+     */
+    private readonly declaredDisplayNames;
     /** 导入过的插件名 → 来源与包（含未加载的；重名被跳过的一方不在这里）。 */
     private readonly sources;
     private didLoad;
@@ -210,6 +225,8 @@ export declare class ExtensionHost {
     private readonly configValidity;
     /** 已告警过的「部署配置不合法」（插件名 → 说明；每个周期都会重新判定，同一说明只告警一次）。 */
     private readonly configWarned;
+    /** `<name>@<version>` whose invalid config UI hints were warned about (a log dedupe only). */
+    private readonly configUiWarned;
     /**
      * 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
@@ -233,7 +250,12 @@ export declare class ExtensionHost {
      */
     installs: ExtensionInstalls, approvals: ExtensionApprovals, 
     /** This replica's load status table (`extension_replica_status`): every load result writes a row. */
-    status: ReplicaStatusStore, config: KernelConfigService, kdb: KernelDb, redis: Redis, busSubscriber: BusSubscriber, keyring: Keyring, embedTokens: EmbedTokens, locks: LockService, log: KernelLogger, options: Pick<KernelAppOptions, "resolveFrom">);
+    status: ReplicaStatusStore, config: KernelConfigService, kdb: KernelDb, redis: Redis, busSubscriber: BusSubscriber, keyring: Keyring, embedTokens: EmbedTokens, locks: LockService, log: KernelLogger, options: Pick<KernelAppOptions, "resolveFrom">, 
+    /**
+     * Each hook call's effective config for its organization, and the providers excluded from an
+     * org's point resolution (layering spec A §6).
+     */
+    effective: Pick<EffectiveConfigs, "get">);
     /** The startup config's `extensionConfig` (file / Nacos merged with env). */
     private get extensionConfig();
     /** `extensionPermissions.autoApprove` (development and trials only; see `planApprovals`). */
@@ -290,6 +312,11 @@ export declare class ExtensionHost {
      * `plugin host closed during load` at the next checkpoint.
      */
     load(plan: string[] | ExtensionLoadPlan): Promise<void>;
+    /**
+     * 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).
+     */
+    private noteDisplayNames;
     /**
      * 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).
@@ -356,6 +383,15 @@ export declare class ExtensionHost {
      * - 缺的能力没有任何提供方 → 与此前一样抛错（内核启动失败）。
      */
     private loadDeferred;
+    /**
+     * 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.
+     */
+    private checkConfigUi;
     /** 给已有状态行补说明；失败只记 warn。 */
     private noteStatus;
     /**
@@ -464,6 +500,13 @@ export declare class ExtensionHost {
      * （如 `identity-source@1` 的登录配置）；未加载返回 undefined。不得回显到响应或日志。
      */
     deploymentConfig(plugin: string): unknown;
+    /**
+     * 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: string): Promise<unknown>;
     /**
      * 本副本拿得到的插件清单里的部署级 schema（生效实例 → 配置声明 → 安装记录准备好的候选）；
      * 都没有返回 undefined（如未加载的安装记录：调用方改用包内静态清单）。

package/dist/extensions/host.js

@@ -30,10 +30,13 @@ import { EmbedTokens } from "../ui/embed-token.js";
 import { ExtensionApprovals, planApprovals, readSnapshots, withPreApproved, } from "./approvals.js";
 import { ExtensionBlobIntegrityError } from "./blobs.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 { 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";
@@ -171,7 +174,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 +237,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 +302,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
@@ -351,6 +361,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 +385,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,13 +410,19 @@ 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) {
         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.deps = {
             db: kdb.pool,
@@ -419,6 +442,7 @@ let ExtensionHost = class ExtensionHost {
             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,
@@ -461,6 +485,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 +542,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 只能由安装记录满足，先挑出来，等安装记录加载完再解析与加载
@@ -584,6 +611,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).
@@ -1032,6 +1076,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 {
@@ -1123,7 +1200,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") {
@@ -1247,7 +1326,12 @@ let ExtensionHost = class ExtensionHost {
         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 +1377,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,
             };
         });
     }
@@ -1531,6 +1616,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 {
@@ -1638,6 +1724,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（如未加载的安装记录：调用方改用包内静态清单）。
@@ -1673,7 +1768,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,7 +1790,7 @@ 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) {
                 this.log.warn("plugin deployment config changed but is invalid on this replica; keeping the current config", {
                     plugin,
@@ -1947,7 +2042,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);
@@ -2105,6 +2200,7 @@ 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))
 ], ExtensionHost);
 export { ExtensionHost };