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

package/dist/extensions/deployment-config.js

@@ -1,155 +1,39 @@
+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 { isDeepStrictEqual } from "node:util";
-import { sql } from "kysely";
+import { Inject, Injectable } from "@nestjs/common";
 import { configFields, describeSchema, getPath, secretValues } from "../config/fields.js";
-import { fieldSource } from "../config/sources.js";
+import { configSourceKind, extensionConfigSources, fieldSource, } from "../config/sources.js";
 import { createSecrets } from "../ctx/secrets.js";
 import { ApiError } from "../errors.js";
 import { audit } from "../identity/audit.js";
-import { lockEnterpriseAdminsAndAuthorize } from "../identity/enterprise-admin.js";
-import { configToJsonSchema } from "./config-json-schema.js";
-import { toIssues } from "./org-config.js";
-/** 部署级插件配置的密钥存在 `capybara.secrets` 的这个 org_id 下（不是真实组织；namespace `kernel`）。 */
-export const DEPLOYMENT_SECRETS_ORG = "_deployment";
-/** 内核自己的 secrets 命名空间（`kernel` 是保留插件名）。 */
-const SECRETS_NAMESPACE = "kernel";
-const SECRET_KEY_PREFIX = "plugin-deployment-config:";
-const secretKey = (plugin, path) => `${SECRET_KEY_PREFIX}${plugin}:${path}`;
-/**
- * 部署配置保存之后（kernel bus 主题，频道 `cap:kernel:plugin-deployment-config`，payload `{ plugin }`）：
- * 各副本重读并校验——只改了 hot 字段就地替换，改了非 hot 字段重新加载实例，不合法保持当前值并告警；
- * 插件此刻待配置时，下一次 reconcile 加载它。
- */
-export const PLUGIN_DEPLOYMENT_CONFIG_TOPIC = "plugin-deployment-config";
-/** 由 zod schema 得出字段清单（`configFields`：对象路径上的叶子，secret 向下继承）。 */
-export function schemaFields(schema) {
-    if (!schema)
-        return [];
-    return configFields(schema).map((f) => ({
-        path: f.path,
-        secret: f.meta?.secret === true,
-        hot: f.meta?.hot === true,
-    }));
-}
-const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
-/** 按点路径设值，缺失的中间对象自动创建；中间节点不是对象时放弃。 */
-function setDeep(obj, path, value) {
-    const segs = path.split(".");
-    let node = obj;
-    for (const seg of segs.slice(0, -1)) {
-        const next = node[seg];
-        if (next === undefined)
-            node[seg] = {};
-        else if (!isObj(next))
-            return;
-        node = node[seg];
-    }
-    node[segs[segs.length - 1]] = value;
-}
-/** 按点路径删除键；删完变空的中间对象一并删掉。 */
-function deleteDeep(obj, path) {
-    const segs = path.split(".");
-    const chain = [obj];
-    let node = obj;
-    for (const seg of segs.slice(0, -1)) {
-        if (!isObj(node))
-            return;
-        node = node[seg];
-        if (!isObj(node))
-            return;
-        chain.push(node);
-    }
-    delete chain[chain.length - 1][segs[segs.length - 1]];
-    for (let i = chain.length - 1; i > 0; i--) {
-        if (Object.keys(chain[i]).length > 0)
-            break;
-        delete chain[i - 1][segs[i - 1]];
-    }
-}
-/** 叶子点路径（对象递归；其余都是叶子）。 */
-function leafPaths(value, prefix = "", out = []) {
-    if (isObj(value)) {
-        for (const [k, v] of Object.entries(value))
-            leafPaths(v, prefix ? `${prefix}.${k}` : k, out);
-    }
-    else if (prefix !== "")
-        out.push(prefix);
-    return out;
-}
-/** 启动配置（文件 / 环境变量合并后的值）是否覆盖了这个字段：给了它、它下面的值，或在祖先上给了非对象值。 */
-function coveredBy(fileValue, path) {
-    let node = fileValue;
-    for (const seg of path.split(".")) {
-        if (node === undefined)
-            return false;
-        if (!isObj(node))
-            return true;
-        node = node[seg];
-    }
-    return node !== undefined;
-}
-/**
- * 合并一个插件的部署配置（C10 的优先级：环境变量 > 文件 / Nacos > PG > schema 默认值）：以启动配置
- * （`fileValue`，已含环境变量）为底，逐字段补上 PG 里保存、而启动配置没有覆盖的值。按字段合并：启动配置给了的字段
- * 整个以它为准（不与 PG 的值深合并）。`fields` 为字段点路径（没有 schema 时用 PG 值的叶子路径）。默认值由校验补上。
- */
-export function mergeDeploymentConfig(stored, fileValue, fields = leafPaths(stored)) {
-    if (fileValue !== undefined && !isObj(fileValue))
-        return fileValue;
-    const out = structuredClone(fileValue ?? {});
-    for (const path of fields) {
-        const v = getPath(stored, path);
-        if (v === undefined || coveredBy(fileValue, path))
-            continue;
-        setDeep(out, path, structuredClone(v));
-    }
-    return out;
-}
-/**
- * PG 里一个插件保存的部署配置（非密钥字段 + 解密的密钥字段，按点路径放回对象）。只并入 `secretPaths`（当前
- * schema 里是密钥的字段）的密钥：旧版本留下、现在已不是密钥或已删掉的字段不解密、不并入（否则会被当成明文回显
- * 或保存）。
- */
-export async function readStoredDeploymentConfig(db, keyring, plugin, opts) {
-    let q = db
-        .selectFrom("extension_deployment_configs")
-        .select("config")
-        .where("plugin", "=", plugin);
-    if (opts.forUpdate)
-        q = q.forUpdate();
-    const row = await q.executeTakeFirst();
-    const out = structuredClone(row?.config ?? {});
-    const prefix = secretKey(plugin, "");
-    const wanted = new Set(opts.secretPaths);
-    if (wanted.size === 0)
-        return out;
-    const keys = await db
-        .selectFrom("secrets")
-        .select("key")
-        .where("namespace", "=", SECRETS_NAMESPACE)
-        .where("org_id", "=", DEPLOYMENT_SECRETS_ORG)
-        .execute();
-    const secrets = createSecrets(db, keyring, SECRETS_NAMESPACE);
-    for (const { key } of keys) {
-        if (!key.startsWith(prefix) || !wanted.has(key.slice(prefix.length)))
-            continue;
-        const v = await secrets.get(DEPLOYMENT_SECRETS_ORG, key);
-        if (v !== null)
-            setDeep(out, key.slice(prefix.length), JSON.parse(v));
-    }
-    return out;
-}
-/** 字段清单里的密钥字段路径。 */
-export const secretPathsOf = (fields) => fields.filter((f) => f.secret).map((f) => f.path);
-/** 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);
-}
+import { SuperAdminLock } from "../identity/super-admin.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { afterCommit } from "../infra/database/after-commit.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { Transactional } from "../infra/database/transactional.decorator.js";
+import { KERNEL_BUS, KERNEL_LOGGER, KEYRING } from "../infra/tokens.js";
+import { KERNEL_APP_OPTIONS } from "../lifecycle/tokens.js";
+import { toIssues } from "./config-issues.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 };
 /** 某字段 zod 叶子上的默认值（整份配置不合法、校验没能补上默认值时，视图仍按它显示）。 */
 function defaultOf(schema, path) {
     const f = configFields(schema).find((x) => x.path === path);
@@ -166,30 +50,87 @@ function defaultOf(schema, path) {
  * follows {@link mergeDeploymentConfig}. No in-process state, shared by every replica.
  * Secret values are never echoed: responses only say "set", audits only record which paths changed.
  */
-export class ExtensionDeploymentConfigService {
-    d;
-    constructor(d) {
-        this.d = d;
+let ExtensionDeploymentConfigService = class ExtensionDeploymentConfigService {
+    kdb;
+    txHost;
+    adminLock;
+    configLock;
+    keyring;
+    config;
+    host;
+    installs;
+    lifecycle;
+    bus;
+    log;
+    displayNames;
+    /** Where each startup-config field comes from (see `extensionConfigSources`); those fields are read-only. */
+    sources;
+    constructor(kdb, txHost, 
+    /** 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, 
+    /** The effective (stored plus startup) deployment config. */
+    installs, 
+    /** 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, displayNames) {
+        this.kdb = kdb;
+        this.txHost = txHost;
+        this.adminLock = adminLock;
+        this.configLock = configLock;
+        this.keyring = keyring;
+        this.config = config;
+        this.host = host;
+        this.installs = installs;
+        this.lifecycle = lifecycle;
+        this.bus = bus;
+        this.log = log;
+        this.displayNames = displayNames;
+        const env = options.env ?? process.env;
+        this.sources =
+            options.extensionConfigSources ??
+                extensionConfigSources({ extensionConfig: config.get().extensionConfig }, env, configSourceKind(env));
+    }
+    get db() {
+        return this.kdb.db;
+    }
+    /** The startup config's `extensionConfig` (file / Nacos merged with env). */
+    fileConfig() {
+        return this.config.get().extensionConfig;
+    }
+    /**
+     * The extension's deployment config description; undefined when the deployment does not know
+     * the extension (`extension.not_found`). Public for tests only.
+     */
+    async schemaOf(plugin) {
+        const local = this.host.deploymentSchema(plugin);
+        if (local)
+            return { ...local, fields: schemaFields(local.schema) };
+        // 与配置声明重名的安装记录不生效
+        if (this.host.declared().has(plugin))
+            return undefined;
+        return staticDeploymentSchema(this.db, plugin);
     }
     /** 插件的生效部署配置（未校验）：启动配置为底，补上 PG 里保存的字段。`schema` 给出时按它的字段合并。 */
-    async effective(plugin, fileValue, schema) {
-        const stored = await readStoredDeploymentConfig(this.d.db, this.d.keyring, plugin, {
-            secretPaths: secretPathsOf(schemaFields(schema)),
-        });
-        const fields = schema ? configFields(schema).map((f) => f.path) : undefined;
-        return mergeDeploymentConfig(stored, fileValue, fields);
+    effective(plugin, fileValue, schema) {
+        return this.installs.effectiveDeploymentConfig(plugin, fileValue, schema);
     }
     /** Admin view; an extension unknown to the deployment -> `extension.not_found`. */
     async view(plugin) {
         const info = await this.info(plugin);
-        const stored = await this.d.db
-            .transaction()
-            .setIsolationLevel("repeatable read")
-            .setAccessMode("read only")
-            .execute((t) => readStoredDeploymentConfig(t, this.d.keyring, plugin, {
+        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) {
+        return readStoredDeploymentConfig(this.db, this.keyring, plugin, {
             secretPaths: secretPathsOf(info.fields),
-        }));
-        return this.render(plugin, info, stored);
+        });
     }
     /**
      * Saves some fields: `values` keyed by field dot path, `null` = clear (back to the default),
@@ -198,12 +139,17 @@ export 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`);
@@ -213,124 +159,244 @@ export 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" })));
         }
-        const sources = this.d.sources[plugin];
-        const readonly = Object.keys(values).filter((p) => fieldSource(sources, p) !== undefined);
+        this.checkSecretEntries(plugin, info, values, secretEntries);
+        const sources = this.sources[plugin];
+        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.d.fileConfig()[plugin];
+        const fileValue = this.fileConfig()[plugin];
         const fieldPaths = info.fields.map((f) => f.path);
-        let saved;
-        let changed = [];
-        await this.d.db.transaction().execute(async (t) => {
-            await lockEnterpriseAdminsAndAuthorize(t, actor);
-            await sql `SELECT pg_advisory_xact_lock(hashtext(${`capybara.plugin-deployment-config:${plugin}`}))`.execute(t);
-            const before = await readStoredDeploymentConfig(t, this.d.keyring, plugin, {
-                forUpdate: true,
-                secretPaths: secretPathsOf(info.fields),
-            });
-            const next = structuredClone(before);
-            for (const [path, v] of Object.entries(values)) {
-                if (v === null)
-                    deleteDeep(next, path);
-                else
-                    setDeep(next, path, structuredClone(v));
+        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));
+            if (secrets.length > 0)
+                this.log.addSecrets(secrets);
+        }
+        if (changed.length > 0) {
+            try {
+                await this.bus.publish(PLUGIN_DEPLOYMENT_CONFIG_TOPIC, { plugin });
             }
-            if (info.schema) {
-                const r = info.schema.safeParse(mergeDeploymentConfig(next, fileValue, fieldPaths));
-                if (!r.success) {
-                    // 启动配置里只读字段自己的问题这里改不了（照样保存，插件保持待配置），其余拒绝
-                    const issues = toIssues(r.error).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);
-                    }
-                }
+            catch (err) {
+                this.log.warn("cannot publish plugin-deployment-config after saving", { plugin, err });
             }
-            changed = Object.keys(values)
-                .filter((p) => !isDeepStrictEqual(getPath(before, p), getPath(next, p)))
-                .sort();
-            saved = next;
-            if (changed.length === 0)
-                return;
-            const plain = structuredClone(next);
-            const secrets = createSecrets(t, this.d.keyring, SECRETS_NAMESPACE);
-            for (const f of info.fields) {
-                if (!f.secret)
-                    continue;
-                deleteDeep(plain, f.path);
-                if (!(f.path in values))
-                    continue;
-                const v = getPath(next, f.path);
-                if (v === undefined)
-                    await secrets.delete(DEPLOYMENT_SECRETS_ORG, secretKey(plugin, f.path));
-                else
-                    await secrets.set(DEPLOYMENT_SECRETS_ORG, secretKey(plugin, f.path), JSON.stringify(v));
+            try {
+                await this.lifecycle.applyConfig(plugin);
+            }
+            catch (err) {
+                this.log.error("applying the plugin deployment config on this replica failed", {
+                    plugin,
+                    err,
+                });
             }
+        }
+        return this.render(plugin, info, stored, await this.displayNames.get(plugin));
+    }
+    /**
+     * Clears the deployment config stored in PG: the `extension_deployment_configs` row and every
+     * secret stored for the extension (any path, also ones an older version declared). Fields from
+     * the startup config (file / Nacos / env) are untouched and stay in effect (they stay
+     * `readonly` in the view; only the startup config changes them). Unknown to the deployment ->
+     * `extension.not_found`.
+     * In a transaction: `lockAndAuthorize` (re-checks the super admin under the lock), the advisory
+     * lock per extension, audit `extension.config_cleared` (detail `clearedPaths`: the stored field
+     * paths, never values; nothing stored -> no audit, no publish). After the commit publishes
+     * {@link PLUGIN_DEPLOYMENT_CONFIG_TOPIC} and applies it on this replica: every replica re-reads,
+     * and the extension loads from what remains, or is unloaded and becomes pending configuration
+     * when that is missing or invalid (`ExtensionHost.applyDeploymentConfig`), without a restart.
+     */
+    async clear(plugin, actor, actorTokenId) {
+        const info = await this.info(plugin);
+        await this.clearStored(plugin, info.fields.map((f) => f.path), actor, actorTokenId);
+        return this.render(plugin, info, {}, await this.displayNames.get(plugin));
+    }
+    async clearStored(plugin, fieldPaths, actor, actorTokenId) {
+        const t = this.db;
+        await this.adminLock.lockAndAuthorize(actor);
+        await this.configLock.lock(plugin);
+        const row = await t
+            .selectFrom("extension_deployment_configs")
+            .select("config")
+            .where("plugin", "=", plugin)
+            .forUpdate()
+            .executeTakeFirst();
+        const prefix = secretKey(plugin, "");
+        const secretKeys = (await t
+            .selectFrom("secrets")
+            .select("key")
+            .where("namespace", "=", SECRETS_NAMESPACE)
+            .where("org_id", "=", DEPLOYMENT_SECRETS_ORG)
+            .execute())
+            .map((r) => r.key)
+            .filter((k) => k.startsWith(prefix));
+        if (row === undefined && secretKeys.length === 0)
+            return;
+        if (secretKeys.length > 0) {
             await t
-                .insertInto("extension_deployment_configs")
-                .values({ plugin, config: JSON.stringify(plain), updated_by: actor })
-                .onConflict((oc) => oc.column("plugin").doUpdateSet({
-                config: JSON.stringify(plain),
-                updated_by: actor,
-                updated_at: new Date(),
-            }))
+                .deleteFrom("secrets")
+                .where("namespace", "=", SECRETS_NAMESPACE)
+                .where("org_id", "=", DEPLOYMENT_SECRETS_ORG)
+                .where("key", "in", secretKeys)
                 .execute();
-            await audit(t, {
-                actorAccountId: actor,
-                ...(actorTokenId !== undefined && { actorTokenId }),
-                action: "extension.deployment_config_updated",
-                target: plugin,
-                detail: { changedPaths: changed },
-            });
-        });
-        const stored = saved ?? {};
-        if (info.schema && this.d.onSecrets) {
-            const values = secretValues(info.schema, mergeDeploymentConfig(stored, fileValue, fieldPaths));
-            if (values.length > 0)
-                this.d.onSecrets(values);
         }
-        if (changed.length > 0) {
+        await t.deleteFrom("extension_deployment_configs").where("plugin", "=", plugin).execute();
+        const clearedPaths = [
+            ...new Set([
+                ...fieldPaths.filter((p) => getPath(row?.config ?? {}, p) !== undefined),
+                ...secretKeys.map((k) => k.slice(prefix.length)),
+            ]),
+        ].sort();
+        await audit(t, {
+            actorAccountId: actor,
+            ...(actorTokenId !== undefined && { actorTokenId }),
+            action: "extension.config_cleared",
+            target: plugin,
+            detail: { clearedPaths },
+        });
+        afterCommit(async () => {
             try {
-                await this.d.bus?.publish(PLUGIN_DEPLOYMENT_CONFIG_TOPIC, { plugin });
+                await this.bus.publish(PLUGIN_DEPLOYMENT_CONFIG_TOPIC, { plugin });
             }
             catch (err) {
-                this.d.log.warn("cannot publish plugin-deployment-config after saving", { plugin, err });
+                this.log.warn("cannot publish plugin-deployment-config after clearing", { plugin, err });
             }
             try {
-                await this.d.applyLocal?.(plugin);
+                await this.lifecycle.applyConfig(plugin);
             }
             catch (err) {
-                this.d.log.error("applying the plugin deployment config on this replica failed", {
+                this.log.error("applying the cleared plugin deployment config on this replica failed", {
                     plugin,
                     err,
                 });
             }
+        });
+    }
+    /**
+     * 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;
+        await this.adminLock.lockAndAuthorize(actor);
+        await this.configLock.lock(plugin);
+        const before = await readStoredDeploymentConfig(t, this.keyring, plugin, {
+            forUpdate: true,
+            secretPaths: secretPathsOf(info.fields),
+        });
+        const next = structuredClone(before);
+        for (const [path, v] of Object.entries(values)) {
+            if (v === null)
+                deleteDeep(next, path);
+            else
+                setDeep(next, path, structuredClone(v));
+        }
+        applySecretEntries(next, secretEntries);
+        const touched = new Set([...Object.keys(values), ...secretEntries.map((e) => e.path)]);
+        if (info.schema) {
+            // 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, 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 = [...touched]
+            .filter((p) => !isDeepStrictEqual(getPath(before, p), getPath(next, p)))
+            .sort();
+        const saved = next;
+        if (changed.length === 0)
+            return { saved, changed };
+        const plain = structuredClone(next);
+        const secrets = createSecrets(t, this.keyring, SECRETS_NAMESPACE);
+        for (const f of info.fields) {
+            if (!f.secret)
+                continue;
+            deleteDeep(plain, f.path);
+            if (!touched.has(f.path))
+                continue;
+            const v = getPath(next, f.path);
+            if (v === undefined)
+                await secrets.delete(DEPLOYMENT_SECRETS_ORG, secretKey(plugin, f.path));
+            else
+                await secrets.set(DEPLOYMENT_SECRETS_ORG, secretKey(plugin, f.path), JSON.stringify(v));
         }
-        return this.render(plugin, info, stored);
+        await t
+            .insertInto("extension_deployment_configs")
+            .values({ plugin, config: JSON.stringify(plain), updated_by: actor })
+            .onConflict((oc) => oc.column("plugin").doUpdateSet({
+            config: JSON.stringify(plain),
+            updated_by: actor,
+            updated_at: new Date(),
+        }))
+            .execute();
+        await audit(t, {
+            actorAccountId: actor,
+            ...(actorTokenId !== undefined && { actorTokenId }),
+            action: "extension.deployment_config_updated",
+            target: plugin,
+            detail: { changedPaths: changed },
+        });
+        return { saved, changed };
     }
     async info(plugin) {
-        const info = await this.d.schemaOf(plugin);
+        const info = await this.schemaOf(plugin);
         if (!info) {
             throw new ApiError("extension.not_found", `Extension ${plugin} is not known to this deployment`);
         }
         return info;
     }
-    render(plugin, info, stored) {
-        const fileValue = this.d.fileConfig()[plugin];
-        const sources = this.d.sources[plugin];
+    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));
         let effective = raw;
         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);
@@ -345,31 +411,151 @@ export 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({
+        propagation: "requires_new",
+        isolationLevel: "repeatable read",
+        accessMode: "read only",
+    })
+], ExtensionDeploymentConfigService.prototype, "readStored", null);
+__decorate([
+    Transactional()
+], ExtensionDeploymentConfigService.prototype, "clearStored", null);
+__decorate([
+    Transactional()
+], ExtensionDeploymentConfigService.prototype, "write", null);
+ExtensionDeploymentConfigService = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(TransactionHost)),
+    __param(2, Inject(SuperAdminLock)),
+    __param(3, Inject(PluginDeploymentConfigLock)),
+    __param(4, Inject(KEYRING)),
+    __param(5, Inject(KernelConfigService)),
+    __param(6, Inject(ExtensionHost)),
+    __param(7, Inject(ExtensionInstalls)),
+    __param(8, Inject(ExtensionLifecycle)),
+    __param(9, Inject(KERNEL_BUS)),
+    __param(10, Inject(KERNEL_LOGGER)),
+    __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
@@ -383,8 +569,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,