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

package/dist/extensions/deployment-config.d.ts

@@ -1,9 +1,10 @@
+import type { LocalizedName } from "@capybara-hq/plugin-sdk";
 import type { core } from "zod";
 import type { KernelAppOptions } from "../app.js";
 import { type ConfigSourceKind } from "../config/sources.js";
 import { type Keyring } from "../ctx/secrets.js";
 import type { KernelSchemaDb } from "../db/kernel-schema.js";
-import { EnterpriseAdminLock } from "../identity/enterprise-admin.js";
+import { SuperAdminLock } from "../identity/super-admin.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
@@ -12,12 +13,14 @@ import type { PublishBus } from "./admin-view.js";
 import { type ConfigIssue } from "./config-issues.js";
 import { type JsonSchema } from "./config-json-schema.js";
 import { DEPLOYMENT_SECRETS_ORG, type DeploymentSchemaInfo, mergeDeploymentConfig, readStoredDeploymentConfig, schemaFields, secretPathsOf } from "./deployment-config-store.js";
+import { ExtensionDisplayNames } from "./display-name.js";
 import { ExtensionHost } from "./host.js";
 import { ExtensionInstalls } from "./installs.js";
 import { ExtensionLifecycle } from "./lifecycle.js";
 import { PLUGIN_DEPLOYMENT_CONFIG_TOPIC } from "./lifecycle-topics.js";
 import { PluginDeploymentConfigLock } from "./locks.js";
 export { DEPLOYMENT_SECRETS_ORG, type DeploymentSchemaInfo, mergeDeploymentConfig, readStoredDeploymentConfig, schemaFields, secretPathsOf, };
+type Obj = Record<string, unknown>;
 export type { ConfigIssue };
 export { PLUGIN_DEPLOYMENT_CONFIG_TOPIC };
 /** 后台一个部署配置字段：来源、是否只读；非密钥字段给出生效值，密钥字段只给 `set`。 */
@@ -34,15 +37,41 @@ export interface DeploymentConfigField {
     value?: unknown;
     /** 密钥字段是否已设置（任何来源）；值永不回显。 */
     set?: boolean;
+    /**
+     * Only on a secret record some `x-ui.secrets[].path` names: the record's keys that are set, sorted
+     * (item names, not secret values; spec §4.3). Other secret fields report only `set`.
+     */
+    keys?: string[];
+    /**
+     * What orgs may do with the field (spec A §5.1, the level of its top-level key): `readonly` (they
+     * see it) or `override` (they may bring their own value); absent = hidden from orgs.
+     */
+    org?: "readonly" | "override";
+}
+/**
+ * One operation on a secret record drawn per item (spec §4.3), only for a path some
+ * `x-ui.secrets[].path` names: `renameFrom` moves an existing value to `key` (nothing when it has
+ * none, replacing a value already at `key`), then `value` sets it (a string) or removes it (`null`).
+ */
+export interface SecretEntry {
+    path: string;
+    key: string;
+    value?: string | null | undefined;
+    renameFrom?: string | undefined;
 }
 /** The response of `GET / PUT /api/v1/admin/extensions/:name/config`. */
 export interface DeploymentConfigView {
     plugin: string;
+    /** The plugin's display name (`ExtensionDisplayNames`); null when it has none. */
+    displayName: LocalizedName | null;
     version: string;
     /** 插件声明了部署级配置。 */
     configurable: boolean;
     fields: DeploymentConfigField[];
-    /** 部署级 schema 的 JSON Schema（密钥字段带 `x-secret`）；本副本拿不到模块（未加载的安装记录）时为 null。 */
+    /**
+     * 部署级 schema 的 JSON Schema（密钥字段带 `x-secret`，提示 `x-ui` / `x-hot`）。本副本拿不到模块（未加载的
+     * 安装记录）时取包内的 `extension.configSchemas.deployment`（`validated` 为 false）；旧包没有它时为 null。
+     */
     schema: JsonSchema | null;
     /** 生效配置按 schema 校验通过（`validated` 为 false 时没有校验，恒为 true，界面不要据此显示「合法」）。 */
     valid: boolean;
@@ -53,6 +82,11 @@ export interface DeploymentConfigView {
     validated: boolean;
     /** 校验失败的原因（只有路径与说明，不含值）。 */
     issues: ConfigIssue[];
+    /**
+     * The required `override` fields the platform left empty (spec A §5.4a): the extension still
+     * loads, and every org that follows the platform must configure them itself.
+     */
+    orgMustConfigure: string[];
 }
 /**
  * Deployment-level extension config (D8 / C10): non-secret fields are stored in
@@ -65,7 +99,7 @@ export interface DeploymentConfigView {
 export declare class ExtensionDeploymentConfigService {
     private readonly kdb;
     readonly txHost: TransactionHost;
-    /** The enterprise admin lock (identity/enterprise-admin.ts): joins the transaction. */
+    /** The super admin lock (identity/super-admin.ts): joins the transaction. */
     private readonly adminLock;
     private readonly configLock;
     private readonly keyring;
@@ -79,11 +113,12 @@ export declare class ExtensionDeploymentConfigService {
     /** Publishes {@link PLUGIN_DEPLOYMENT_CONFIG_TOPIC} after a save (a failure only warns). */
     private readonly bus;
     private readonly log;
+    private readonly displayNames;
     /** Where each startup-config field comes from (see `extensionConfigSources`); those fields are read-only. */
     private readonly sources;
     constructor(kdb: KernelDb, txHost: TransactionHost, 
-    /** The enterprise admin lock (identity/enterprise-admin.ts): joins the transaction. */
-    adminLock: EnterpriseAdminLock, configLock: PluginDeploymentConfigLock, keyring: Keyring, config: KernelConfigService, 
+    /** The super admin lock (identity/super-admin.ts): joins the transaction. */
+    adminLock: SuperAdminLock, configLock: PluginDeploymentConfigLock, keyring: Keyring, config: KernelConfigService, 
     /** This replica's extension schemas (loaded, config-declared or prepared install records). */
     host: ExtensionHost, 
     /** The effective (stored plus startup) deployment config. */
@@ -91,7 +126,7 @@ export declare class ExtensionDeploymentConfigService {
     /** Applies a saved config on this replica at once (other replicas through the bus). */
     lifecycle: ExtensionLifecycle, 
     /** Publishes {@link PLUGIN_DEPLOYMENT_CONFIG_TOPIC} after a save (a failure only warns). */
-    bus: PublishBus, log: KernelLogger, options: Pick<KernelAppOptions, "env" | "extensionConfigSources">);
+    bus: PublishBus, log: KernelLogger, options: Pick<KernelAppOptions, "env" | "extensionConfigSources">, displayNames: ExtensionDisplayNames);
     private get db();
     /** The startup config's `extensionConfig` (file / Nacos merged with env). */
     private fileConfig;
@@ -113,17 +148,52 @@ export declare class ExtensionDeploymentConfigService {
      *   invalid after merging (except a problem in a read-only startup-config field itself) ->
      *   `extension.config_invalid` (details carry only paths and messages);
      * - a field present in the startup config (file / Nacos / env) -> 409 `extension.config_readonly`.
-     * In a transaction, first `lockEnterpriseAdminsAndAuthorize` (re-checks the enterprise admin under
+     * `secretEntries` change single keys of secret records some `x-ui.secrets[].path` names
+     * ({@link SecretEntry}; spec §4.3): applied under the same locks to the decrypted record, which
+     * is re-encrypted whole, then validated with `values`; the audit lists the record's path, no keys.
+     * A path no hint names -> 400 `validation_failed`; one in the startup config -> 409
+     * `extension.config_readonly`.
+     * In a transaction, first `lockSuperAdminsAndAuthorize` (re-checks the super admin under
      * the lock), then an advisory lock per extension; audit `extension.deployment_config_updated`
      * (detail only `changedPaths`). After the commit publishes {@link PLUGIN_DEPLOYMENT_CONFIG_TOPIC} and
      * applies it on this replica right away.
      */
-    put(plugin: string, values: Record<string, unknown>, actor: string, actorTokenId?: string): Promise<DeploymentConfigView>;
+    put(plugin: string, values: Record<string, unknown>, actor: string, actorTokenId?: string, secretEntries?: readonly SecretEntry[]): Promise<DeploymentConfigView>;
+    /**
+     * Secret entries name a secret record field some hint names (else 400 `validation_failed`, also
+     * for a path given in `values` too, an entry with neither `value` nor `renameFrom`, or a key
+     * `__proto__`). Messages carry paths and keys only, never values.
+     */
+    private checkSecretEntries;
     private write;
     private info;
     private render;
+    /**
+     * The required `override` fields the platform left empty ({@link DeploymentConfigView}
+     * `orgMustConfigure`); reads nothing when the extension has no `override` field. Unknown to the
+     * deployment -> `extension.not_found`.
+     */
+    orgMustConfigure(plugin: string): Promise<string[]>;
+    /**
+     * The form JSON Schema of the description: the zod schema's, else the package's static one. A
+     * hint conversion that throws (a hand-made package) drops the hints: the plain schema, or none
+     * when even the conversion fails; one warning per schema. Never throws.
+     */
+    private formSchemaOf;
+    private messagesOf;
+    /** The secret record paths some hint of the form schema names. */
+    private hintedPaths;
 }
+/**
+ * Applies secret entries in order to the decrypted config `next` (in place): each record is read
+ * from `next` at its path, renamed, set or removed, and put back; an empty record is removed (the
+ * field falls back to its default).
+ */
+export declare function applySecretEntries(next: Obj, entries: readonly SecretEntry[]): void;
 /**
  * 本副本拿不到模块时（未加载的安装记录）按包内审阅过的静态清单给出字段（没有 zod schema：不校验，加载时再校验）。
+ * The package's `extension.configSchemas.deployment` (written by the packer) is the form schema;
+ * its hints are checked like a loaded schema's (stripped when invalid, silently: a hand-made
+ * package). It is not compared with the module (not part of `manifest_mismatch`, spec §4.5).
  */
 export declare function staticDeploymentSchema(db: KernelSchemaDb, plugin: string): Promise<DeploymentSchemaInfo | undefined>;

package/dist/extensions/deployment-config.js

@@ -14,7 +14,7 @@ import { configSourceKind, extensionConfigSources, fieldSource, } from "../confi
 import { createSecrets } from "../ctx/secrets.js";
 import { ApiError } from "../errors.js";
 import { audit } from "../identity/audit.js";
-import { EnterpriseAdminLock } from "../identity/enterprise-admin.js";
+import { SuperAdminLock } from "../identity/super-admin.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
@@ -22,25 +22,17 @@ import { Transactional } from "../infra/database/transactional.decorator.js";
 import { KERNEL_BUS, KERNEL_LOGGER, KEYRING } from "../infra/tokens.js";
 import { KERNEL_APP_OPTIONS } from "../lifecycle/tokens.js";
 import { toIssues } from "./config-issues.js";
-import { configToJsonSchema } from "./config-json-schema.js";
-import { DEPLOYMENT_SECRETS_ORG, deleteDeep, mergeDeploymentConfig, readStoredDeploymentConfig, SECRETS_NAMESPACE, schemaFields, secretKey, secretPathsOf, setDeep, } from "./deployment-config-store.js";
+import { checkConfigUi, configMessages, hintedSecretPaths, safeConfigFormSchema, } from "./config-json-schema.js";
+import { DEPLOYMENT_SECRETS_ORG, deleteDeep, isObj, mergeDeploymentConfig, readStoredDeploymentConfig, SECRETS_NAMESPACE, schemaFields, secretKey, secretPathsOf, setDeep, } from "./deployment-config-store.js";
+import { ExtensionDisplayNames } from "./display-name.js";
 import { ExtensionHost } from "./host.js";
 import { ExtensionInstalls } from "./installs.js";
 import { ExtensionLifecycle } from "./lifecycle.js";
 import { PLUGIN_DEPLOYMENT_CONFIG_TOPIC } from "./lifecycle-topics.js";
 import { PluginDeploymentConfigLock } from "./locks.js";
+import { fieldLevels, jsonSchemaFieldLevels, missingOverridable, parseLoadGate, } from "./org-levels.js";
 export { DEPLOYMENT_SECRETS_ORG, mergeDeploymentConfig, readStoredDeploymentConfig, schemaFields, secretPathsOf, };
 export { PLUGIN_DEPLOYMENT_CONFIG_TOPIC };
-/** JSON Schema 转换按 schema 对象缓存（清单不可变）。 */
-const jsonSchemaCache = new WeakMap();
-function jsonSchemaOf(schema) {
-    let js = jsonSchemaCache.get(schema);
-    if (!js) {
-        js = configToJsonSchema(schema);
-        jsonSchemaCache.set(schema, js);
-    }
-    return structuredClone(js);
-}
 /** 某字段 zod 叶子上的默认值（整份配置不合法、校验没能补上默认值时，视图仍按它显示）。 */
 function defaultOf(schema, path) {
     const f = configFields(schema).find((x) => x.path === path);
@@ -69,10 +61,11 @@ let ExtensionDeploymentConfigService = class ExtensionDeploymentConfigService {
     lifecycle;
     bus;
     log;
+    displayNames;
     /** Where each startup-config field comes from (see `extensionConfigSources`); those fields are read-only. */
     sources;
     constructor(kdb, txHost, 
-    /** The enterprise admin lock (identity/enterprise-admin.ts): joins the transaction. */
+    /** The super admin lock (identity/super-admin.ts): joins the transaction. */
     adminLock, configLock, keyring, config, 
     /** This replica's extension schemas (loaded, config-declared or prepared install records). */
     host, 
@@ -81,7 +74,7 @@ let ExtensionDeploymentConfigService = class ExtensionDeploymentConfigService {
     /** Applies a saved config on this replica at once (other replicas through the bus). */
     lifecycle, 
     /** Publishes {@link PLUGIN_DEPLOYMENT_CONFIG_TOPIC} after a save (a failure only warns). */
-    bus, log, options) {
+    bus, log, options, displayNames) {
         this.kdb = kdb;
         this.txHost = txHost;
         this.adminLock = adminLock;
@@ -93,6 +86,7 @@ let ExtensionDeploymentConfigService = class ExtensionDeploymentConfigService {
         this.lifecycle = lifecycle;
         this.bus = bus;
         this.log = log;
+        this.displayNames = displayNames;
         const env = options.env ?? process.env;
         this.sources =
             options.extensionConfigSources ??
@@ -125,8 +119,11 @@ let ExtensionDeploymentConfigService = class ExtensionDeploymentConfigService {
     /** Admin view; an extension unknown to the deployment -> `extension.not_found`. */
     async view(plugin) {
         const info = await this.info(plugin);
-        const stored = await this.readStored(plugin, info);
-        return this.render(plugin, info, stored);
+        const [stored, displayName] = await Promise.all([
+            this.readStored(plugin, info),
+            this.displayNames.get(plugin),
+        ]);
+        return this.render(plugin, info, stored, displayName);
     }
     /** `REPEATABLE READ` read-only: every stored field from one snapshot. */
     readStored(plugin, info) {
@@ -141,12 +138,17 @@ let ExtensionDeploymentConfigService = class ExtensionDeploymentConfigService {
      *   invalid after merging (except a problem in a read-only startup-config field itself) ->
      *   `extension.config_invalid` (details carry only paths and messages);
      * - a field present in the startup config (file / Nacos / env) -> 409 `extension.config_readonly`.
-     * In a transaction, first `lockEnterpriseAdminsAndAuthorize` (re-checks the enterprise admin under
+     * `secretEntries` change single keys of secret records some `x-ui.secrets[].path` names
+     * ({@link SecretEntry}; spec §4.3): applied under the same locks to the decrypted record, which
+     * is re-encrypted whole, then validated with `values`; the audit lists the record's path, no keys.
+     * A path no hint names -> 400 `validation_failed`; one in the startup config -> 409
+     * `extension.config_readonly`.
+     * In a transaction, first `lockSuperAdminsAndAuthorize` (re-checks the super admin under
      * the lock), then an advisory lock per extension; audit `extension.deployment_config_updated`
      * (detail only `changedPaths`). After the commit publishes {@link PLUGIN_DEPLOYMENT_CONFIG_TOPIC} and
      * applies it on this replica right away.
      */
-    async put(plugin, values, actor, actorTokenId) {
+    async put(plugin, values, actor, actorTokenId, secretEntries = []) {
         const info = await this.info(plugin);
         if (info.fields.length === 0) {
             throw new ApiError("extension.config_invalid", `Extension ${plugin} has no deployment config`);
@@ -156,14 +158,16 @@ let ExtensionDeploymentConfigService = class ExtensionDeploymentConfigService {
         if (unknown.length > 0) {
             throw new ApiError("extension.config_invalid", `Unknown deployment config fields for extension ${plugin}`, unknown.map((path) => ({ path, message: "unknown field" })));
         }
+        this.checkSecretEntries(plugin, info, values, secretEntries);
         const sources = this.sources[plugin];
-        const readonly = Object.keys(values).filter((p) => fieldSource(sources, p) !== undefined);
+        const entryPaths = [...new Set(secretEntries.map((e) => e.path))];
+        const readonly = [...Object.keys(values), ...entryPaths].filter((p) => fieldSource(sources, p) !== undefined);
         if (readonly.length > 0) {
             throw new ApiError("extension.config_readonly", `These deployment config fields of extension ${plugin} are set in the startup config (file, Nacos or environment) and are read-only here: ${readonly.join(", ")}`, readonly.map((path) => ({ path, source: fieldSource(sources, path) })));
         }
         const fileValue = this.fileConfig()[plugin];
         const fieldPaths = info.fields.map((f) => f.path);
-        const { saved, changed } = await this.write(plugin, values, actor, actorTokenId, info, sources, fileValue);
+        const { saved, changed } = await this.write(plugin, values, secretEntries, actor, actorTokenId, info, sources, fileValue);
         const stored = saved ?? {};
         if (info.schema) {
             const secrets = secretValues(info.schema, mergeDeploymentConfig(stored, fileValue, fieldPaths));
@@ -187,9 +191,38 @@ let ExtensionDeploymentConfigService = class ExtensionDeploymentConfigService {
                 });
             }
         }
-        return this.render(plugin, info, stored);
+        return this.render(plugin, info, stored, await this.displayNames.get(plugin));
     }
-    async write(plugin, values, actor, actorTokenId, info, sources, fileValue) {
+    /**
+     * Secret entries name a secret record field some hint names (else 400 `validation_failed`, also
+     * for a path given in `values` too, an entry with neither `value` nor `renameFrom`, or a key
+     * `__proto__`). Messages carry paths and keys only, never values.
+     */
+    checkSecretEntries(plugin, info, values, entries) {
+        if (entries.length === 0)
+            return;
+        const hinted = this.hintedPaths(plugin, info);
+        const secret = new Set(secretPathsOf(info.fields));
+        const problems = [];
+        for (const e of entries) {
+            if (!hinted.has(e.path) || !secret.has(e.path)) {
+                problems.push({ path: e.path, message: "no config UI hint draws this secret per item" });
+            }
+            else if (Object.hasOwn(values, e.path)) {
+                problems.push({ path: e.path, message: "given both in values and in secretEntries" });
+            }
+            else if (e.value === undefined && e.renameFrom === undefined) {
+                problems.push({ path: e.path, message: `entry ${e.key} has neither value nor renameFrom` });
+            }
+            else if (e.key === "__proto__" || e.renameFrom === "__proto__") {
+                problems.push({ path: e.path, message: "__proto__ is not a valid key" });
+            }
+        }
+        if (problems.length > 0) {
+            throw new ApiError("validation_failed", `Invalid secret entries for the deployment config of extension ${plugin}`, problems);
+        }
+    }
+    async write(plugin, values, secretEntries, actor, actorTokenId, info, sources, fileValue) {
         const fieldPaths = info.fields.map((f) => f.path);
         let changed = [];
         const t = this.db;
@@ -206,17 +239,20 @@ let ExtensionDeploymentConfigService = class ExtensionDeploymentConfigService {
             else
                 setDeep(next, path, structuredClone(v));
         }
+        applySecretEntries(next, secretEntries);
+        const touched = new Set([...Object.keys(values), ...secretEntries.map((e) => e.path)]);
         if (info.schema) {
-            const r = info.schema.safeParse(mergeDeploymentConfig(next, fileValue, fieldPaths));
+            // overridable fields may stay empty on the platform (spec A §5.4a)
+            const r = parseLoadGate(info.schema, mergeDeploymentConfig(next, fileValue, fieldPaths));
             if (!r.success) {
                 // 启动配置里只读字段自己的问题这里改不了（照样保存，插件保持待配置），其余拒绝
-                const issues = toIssues(r.error).filter((i) => i.path === "" || fieldSource(sources, i.path) === undefined);
+                const issues = toIssues(r.error, this.messagesOf(plugin, info)).filter((i) => i.path === "" || fieldSource(sources, i.path) === undefined);
                 if (issues.length > 0) {
                     throw new ApiError("extension.config_invalid", `Invalid deployment config for extension ${plugin}`, issues);
                 }
             }
         }
-        changed = Object.keys(values)
+        changed = [...touched]
             .filter((p) => !isDeepStrictEqual(getPath(before, p), getPath(next, p)))
             .sort();
         const saved = next;
@@ -228,7 +264,7 @@ let ExtensionDeploymentConfigService = class ExtensionDeploymentConfigService {
             if (!f.secret)
                 continue;
             deleteDeep(plain, f.path);
-            if (!(f.path in values))
+            if (!touched.has(f.path))
                 continue;
             const v = getPath(next, f.path);
             if (v === undefined)
@@ -261,7 +297,7 @@ let ExtensionDeploymentConfigService = class ExtensionDeploymentConfigService {
         }
         return info;
     }
-    render(plugin, info, stored) {
+    render(plugin, info, stored, displayName) {
         const fileValue = this.fileConfig()[plugin];
         const sources = this.sources[plugin];
         const raw = mergeDeploymentConfig(stored, fileValue, info.fields.map((f) => f.path));
@@ -269,14 +305,18 @@ let ExtensionDeploymentConfigService = class ExtensionDeploymentConfigService {
         let valid = true;
         let issues = [];
         if (info.schema) {
-            const r = info.schema.safeParse(raw);
+            // the load gate: overridable fields may stay empty (spec A §5.4a)
+            const r = parseLoadGate(info.schema, raw);
             if (r.success)
                 effective = r.data;
             else {
                 valid = false;
-                issues = toIssues(r.error);
+                issues = toIssues(r.error, this.messagesOf(plugin, info));
             }
         }
+        const formSchema = this.formSchemaOf(plugin, info);
+        const hinted = formSchema ? hintedSecretPaths(formSchema) : new Set();
+        const levels = levelsOf(info);
         const fields = info.fields.map((f) => {
             const from = fieldSource(sources, f.path);
             let value = getPath(effective, f.path);
@@ -291,28 +331,72 @@ let ExtensionDeploymentConfigService = class ExtensionDeploymentConfigService {
                     value = d.value;
                 source = value === undefined ? "unset" : "default";
             }
+            const level = levels.get(f.path.split(".")[0]);
             const base = {
                 path: f.path,
                 secret: f.secret,
                 hot: f.hot,
                 source,
                 readonly: from !== undefined,
+                ...(level !== undefined && level !== "hidden" && { org: level }),
             };
+            // a schema default (e.g. `secret(record).default({})`) is no secret anybody set
+            const set = value !== undefined && source !== "default";
+            if (f.secret && hinted.has(f.path)) {
+                // record keys are item names, never values
+                return { ...base, set, keys: set && isObj(value) ? Object.keys(value).sort() : [] };
+            }
             if (f.secret)
-                return { ...base, set: value !== undefined };
+                return { ...base, set };
             return value === undefined ? base : { ...base, value: structuredClone(value) };
         });
         return {
             plugin,
+            displayName,
             version: info.version,
             configurable: info.fields.length > 0,
             fields,
-            schema: info.schema ? jsonSchemaOf(info.schema) : null,
+            schema: structuredClone(formSchema ?? null),
             valid,
             validated: info.schema !== undefined,
             issues,
+            orgMustConfigure: orgMustConfigureOf(info, raw, levels),
         };
     }
+    /**
+     * The required `override` fields the platform left empty ({@link DeploymentConfigView}
+     * `orgMustConfigure`); reads nothing when the extension has no `override` field. Unknown to the
+     * deployment -> `extension.not_found`.
+     */
+    async orgMustConfigure(plugin) {
+        const info = await this.info(plugin);
+        const levels = levelsOf(info);
+        if (![...levels.values()].includes("override"))
+            return [];
+        const stored = await this.readStored(plugin, info);
+        const raw = mergeDeploymentConfig(stored, this.fileConfig()[plugin], info.fields.map((f) => f.path));
+        return orgMustConfigureOf(info, raw, levels);
+    }
+    /**
+     * The form JSON Schema of the description: the zod schema's, else the package's static one. A
+     * hint conversion that throws (a hand-made package) drops the hints: the plain schema, or none
+     * when even the conversion fails; one warning per schema. Never throws.
+     */
+    formSchemaOf(plugin, info) {
+        if (!info.schema)
+            return info.jsonSchema;
+        const r = safeConfigFormSchema(info.schema, "deployment", (err, schema) => this.log.warn("the deployment config form schema could not be built with its UI hints; hints dropped", { plugin, version: info.version, schema, err }));
+        return r?.schema;
+    }
+    messagesOf(plugin, info) {
+        const js = this.formSchemaOf(plugin, info);
+        return js && configMessages(js);
+    }
+    /** The secret record paths some hint of the form schema names. */
+    hintedPaths(plugin, info) {
+        const js = this.formSchemaOf(plugin, info);
+        return js ? hintedSecretPaths(js) : new Set();
+    }
 };
 __decorate([
     Transactional({
@@ -328,7 +412,7 @@ ExtensionDeploymentConfigService = __decorate([
     Injectable(),
     __param(0, Inject(KernelDb)),
     __param(1, Inject(TransactionHost)),
-    __param(2, Inject(EnterpriseAdminLock)),
+    __param(2, Inject(SuperAdminLock)),
     __param(3, Inject(PluginDeploymentConfigLock)),
     __param(4, Inject(KEYRING)),
     __param(5, Inject(KernelConfigService)),
@@ -337,11 +421,58 @@ ExtensionDeploymentConfigService = __decorate([
     __param(8, Inject(ExtensionLifecycle)),
     __param(9, Inject(KERNEL_BUS)),
     __param(10, Inject(KERNEL_LOGGER)),
-    __param(11, Inject(KERNEL_APP_OPTIONS))
+    __param(11, Inject(KERNEL_APP_OPTIONS)),
+    __param(12, Inject(ExtensionDisplayNames))
 ], ExtensionDeploymentConfigService);
 export { ExtensionDeploymentConfigService };
+/** The org level of each top-level key: from the zod schema, else the package's form schema. */
+function levelsOf(info) {
+    return info.schema
+        ? fieldLevels(info.schema)
+        : jsonSchemaFieldLevels(info.jsonSchema);
+}
+/**
+ * The required `override` keys `raw` leaves empty: by the zod schema, else (a static form schema)
+ * the `required` keys marked `override` that have no value.
+ */
+function orgMustConfigureOf(info, raw, levels) {
+    if (info.schema)
+        return missingOverridable(info.schema, raw);
+    const required = info.jsonSchema?.required;
+    if (!Array.isArray(required))
+        return [];
+    return [...levels]
+        .filter(([k, l]) => l === "override" && required.includes(k) && getPath(raw, k) === undefined)
+        .map(([k]) => k);
+}
+/**
+ * Applies secret entries in order to the decrypted config `next` (in place): each record is read
+ * from `next` at its path, renamed, set or removed, and put back; an empty record is removed (the
+ * field falls back to its default).
+ */
+export function applySecretEntries(next, entries) {
+    for (const e of entries) {
+        const cur = getPath(next, e.path);
+        const rec = isObj(cur) ? { ...cur } : {};
+        if (e.renameFrom !== undefined && e.renameFrom !== e.key && Object.hasOwn(rec, e.renameFrom)) {
+            rec[e.key] = rec[e.renameFrom];
+            delete rec[e.renameFrom];
+        }
+        if (e.value === null)
+            delete rec[e.key];
+        else if (e.value !== undefined)
+            rec[e.key] = e.value;
+        if (Object.keys(rec).length === 0)
+            deleteDeep(next, e.path);
+        else
+            setDeep(next, e.path, rec);
+    }
+}
 /**
  * 本副本拿不到模块时（未加载的安装记录）按包内审阅过的静态清单给出字段（没有 zod schema：不校验，加载时再校验）。
+ * The package's `extension.configSchemas.deployment` (written by the packer) is the form schema;
+ * its hints are checked like a loaded schema's (stripped when invalid, silently: a hand-made
+ * package). It is not compared with the module (not part of `manifest_mismatch`, spec §4.5).
  */
 export async function staticDeploymentSchema(db, plugin) {
     const row = await db
@@ -355,8 +486,15 @@ export async function staticDeploymentSchema(db, plugin) {
     // new rows hold the plugin's extension section, pre-0.1.0 rows the old capybara section; both
     // carry the static manifest
     const section = row.section;
+    const stored = section.configSchemas?.deployment;
+    let jsonSchema;
+    if (typeof stored === "object" && stored !== null && !Array.isArray(stored)) {
+        jsonSchema = structuredClone(stored);
+        checkConfigUi(jsonSchema, "deployment");
+    }
     return {
         version: row.version,
+        ...(jsonSchema !== undefined && { jsonSchema }),
         fields: (section.manifest.config?.deployment ?? []).map((f) => ({
             path: f.path,
             secret: f.secret,

package/dist/extensions/display-name.d.ts

@@ -0,0 +1,22 @@
+import type { LocalizedName } from "@capybara-hq/plugin-sdk";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { ExtensionHost } from "./host.js";
+/**
+ * Extension display names (extension config forms spec §2.2), the one resolver every extension and
+ * model API uses: a config-declared extension's plugin.json (read by this replica's host at load,
+ * the same on every replica), else the installed package's `display_name`, else the live catalog
+ * item of the same name, else null. No backfill: a package stored before 0066 gets a name with its
+ * next version. Stateless; one query per call.
+ */
+export declare class ExtensionDisplayNames {
+    private readonly db;
+    /** The config-declared extensions (they win over an install record of the same name, C15). */
+    private readonly host;
+    constructor(db: KernelDb, 
+    /** The config-declared extensions (they win over an install record of the same name, C15). */
+    host: ExtensionHost);
+    /** One extension's display name. */
+    get(name: string): Promise<LocalizedName | null>;
+    /** The display names of `names` (each one a key, null when it has none), in one query. */
+    many(names: string[]): Promise<Map<string, LocalizedName | null>>;
+}

package/dist/extensions/display-name.js

@@ -0,0 +1,77 @@
+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 { Inject, Injectable } from "@nestjs/common";
+import { sql } from "kysely";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { ExtensionHost } from "./host.js";
+/**
+ * Extension display names (extension config forms spec §2.2), the one resolver every extension and
+ * model API uses: a config-declared extension's plugin.json (read by this replica's host at load,
+ * the same on every replica), else the installed package's `display_name`, else the live catalog
+ * item of the same name, else null. No backfill: a package stored before 0066 gets a name with its
+ * next version. Stateless; one query per call.
+ */
+let ExtensionDisplayNames = class ExtensionDisplayNames {
+    db;
+    host;
+    constructor(db, 
+    /** The config-declared extensions (they win over an install record of the same name, C15). */
+    host) {
+        this.db = db;
+        this.host = host;
+    }
+    /** One extension's display name. */
+    async get(name) {
+        return (await this.many([name])).get(name) ?? null;
+    }
+    /** The display names of `names` (each one a key, null when it has none), in one query. */
+    async many(names) {
+        const out = new Map();
+        if (names.length === 0)
+            return out;
+        const declared = new Map(this.host.declaredPlugins().map((p) => [p.name, p]));
+        const rest = [];
+        for (const n of new Set(names)) {
+            const d = declared.get(n);
+            if (d)
+                out.set(n, d.displayName);
+            else
+                rest.push(n);
+        }
+        if (rest.length === 0)
+            return out;
+        const rows = await this.db
+            .selectFrom("extension_installs")
+            .innerJoin("extension_packages", "extension_packages.sha256", "extension_installs.sha256")
+            .select([
+            "extension_installs.name as name",
+            "extension_packages.display_name as display_name",
+            sql `0`.as("rank"),
+        ])
+            .where("extension_installs.name", "in", rest)
+            .unionAll((eb) => eb
+            .selectFrom("catalog_items")
+            .select(["name", "display_name", sql `1`.as("rank")])
+            .where("name", "in", rest)
+            .where("deleted_at", "is", null))
+            .execute();
+        rows.sort((a, b) => Number(a.rank) - Number(b.rank));
+        for (const n of rest) {
+            out.set(n, rows.find((r) => r.name === n && r.display_name !== null)?.display_name ?? null);
+        }
+        return out;
+    }
+};
+ExtensionDisplayNames = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(ExtensionHost))
+], ExtensionDisplayNames);
+export { ExtensionDisplayNames };