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

package/dist/extensions/admin-ops.js

@@ -396,6 +396,8 @@ export { ExtensionAdminOps };
 function fallbackView(name, known, err) {
     return {
         name,
+        // the degraded item reads nothing more (the read that failed may be the database)
+        displayName: null,
         version: known.version,
         source: "install",
         sha256: known.sha256,

package/dist/extensions/admin-view.d.ts

@@ -5,6 +5,7 @@ import { TransactionHost } from "../infra/database/transaction-host.js";
 import type { KernelLogger } from "../log.js";
 import { ExtensionApprovals } from "./approvals.js";
 import { ExtensionBlobs } from "./blobs.js";
+import { ExtensionDisplayNames } from "./display-name.js";
 import { ExtensionHost } from "./host.js";
 import { ExtensionInstalls } from "./installs.js";
 import { ExtensionLifecycle, PLUGINS_CHANGED_TOPIC } from "./lifecycle.js";
@@ -41,6 +42,7 @@ export declare class ExtensionAdmin {
     private readonly config;
     private readonly bus;
     private readonly log;
+    private readonly displayNames;
     private readonly packageSets;
     constructor(kdb: KernelDb, txHost: TransactionHost, 
     /** The enterprise admin lock (identity/enterprise-admin.ts): joins the transaction. */
@@ -48,7 +50,7 @@ export declare class ExtensionAdmin {
     /** The config-declared extensions (this replica's host; the CLI fills it from its inspection). */
     host: ExtensionHost, 
     /** This replica's reconcile after an approval (a no-op where the lifecycle never started: the CLI). */
-    lifecycle: ExtensionLifecycle, config: KernelConfigService, bus: PublishBus, log: KernelLogger);
+    lifecycle: ExtensionLifecycle, config: KernelConfigService, bus: PublishBus, log: KernelLogger, displayNames: ExtensionDisplayNames);
     private get db();
     /** 全部插件（配置声明 → 安装记录，各自按名字）。 */
     list(): Promise<AdminExtensionView[]>;

package/dist/extensions/admin-view.js

@@ -19,6 +19,7 @@ import { Transactional } from "../infra/database/transactional.decorator.js";
 import { KERNEL_BUS, KERNEL_LOGGER } from "../infra/tokens.js";
 import { ExtensionApprovals, snapshotCovers, writeSnapshot, } from "./approvals.js";
 import { ExtensionBlobs } from "./blobs.js";
+import { ExtensionDisplayNames } from "./display-name.js";
 import { ExtensionHost } from "./host.js";
 import { ExtensionInstalls } from "./installs.js";
 import { ExtensionLifecycle, PLUGINS_CHANGED_TOPIC, STALE_RECONCILE_PERIODS } from "./lifecycle.js";
@@ -63,6 +64,7 @@ let ExtensionAdmin = class ExtensionAdmin {
     config;
     bus;
     log;
+    displayNames;
     packageSets = new Map();
     constructor(kdb, txHost, 
     /** The enterprise admin lock (identity/enterprise-admin.ts): joins the transaction. */
@@ -70,7 +72,7 @@ let ExtensionAdmin = class ExtensionAdmin {
     /** The config-declared extensions (this replica's host; the CLI fills it from its inspection). */
     host, 
     /** This replica's reconcile after an approval (a no-op where the lifecycle never started: the CLI). */
-    lifecycle, config, bus, log) {
+    lifecycle, config, bus, log, displayNames) {
         this.kdb = kdb;
         this.txHost = txHost;
         this.adminLock = adminLock;
@@ -83,6 +85,7 @@ let ExtensionAdmin = class ExtensionAdmin {
         this.config = config;
         this.bus = bus;
         this.log = log;
+        this.displayNames = displayNames;
     }
     get db() {
         return this.kdb.db;
@@ -278,6 +281,7 @@ let ExtensionAdmin = class ExtensionAdmin {
             return [];
         const names = subjects.map((s) => s.name);
         const snapshots = await this.approvals.all();
+        const displayNames = await this.displayNames.many(names);
         const staleSeconds = STALE_RECONCILE_PERIODS * this.config.get().extensionHost.reconcileIntervalSeconds;
         const rows = await this.db
             .selectFrom("extension_replica_status")
@@ -294,9 +298,11 @@ let ExtensionAdmin = class ExtensionAdmin {
             const configValid = s.configValid ??
                 !replicas.some((r) => r.state === "pending" && r.reason === "config" && r.sha256 === target);
             const install = s.install;
+            const displayName = displayNames.get(s.name) ?? null;
             if (s.broken !== undefined) {
                 return {
                     name: s.name,
+                    displayName,
                     version: s.version,
                     source: s.source,
                     sha256: target,
@@ -326,6 +332,7 @@ let ExtensionAdmin = class ExtensionAdmin {
             const permissions = permissionGroups(s.set);
             return {
                 name: s.name,
+                displayName,
                 version: s.version,
                 source: s.source,
                 sha256: target,
@@ -376,7 +383,8 @@ ExtensionAdmin = __decorate([
     __param(8, Inject(ExtensionLifecycle)),
     __param(9, Inject(KernelConfigService)),
     __param(10, Inject(KERNEL_BUS)),
-    __param(11, Inject(KERNEL_LOGGER))
+    __param(11, Inject(KERNEL_LOGGER)),
+    __param(12, Inject(ExtensionDisplayNames))
 ], ExtensionAdmin);
 export { ExtensionAdmin };
 const replicaView = (r) => ({

package/dist/extensions/blobs.js

@@ -123,6 +123,7 @@ let ExtensionBlobs = class ExtensionBlobs {
             source: src.source,
             source_ref: src.ref,
             uploaded_by: src.actor,
+            display_name: p.displayName === undefined ? null : JSON.stringify(p.displayName),
         })
             .onConflict((oc) => oc.column("sha256").doNothing())
             .returning("sha256")

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

@@ -1,7 +1,19 @@
 import type { z } from "zod";
 /** 校验失败的单条原因：只含路径与按 issue 类型生成的说明，不回显字段值。 */
 export interface ConfigIssue {
+    /** The path joined with dots (`""` = the root); ambiguous when a key contains a dot. */
     path: string;
+    /** The zod path unjoined (record keys such as endpoint names may contain dots). */
+    segments: (string | number)[];
     message: string;
+    /**
+     * A custom issue whose `params.ui` names a key of the schema's root `x-ui.messages`: the form
+     * shows that localized message (spec §4.4). Never zod's own custom text.
+     */
+    messageKey?: string;
 }
-export declare function toIssues(error: z.ZodError): ConfigIssue[];
+/**
+ * The issues of a failed config parse. `messages` is the root `x-ui.messages` of the schema's
+ * form JSON Schema (`configMessages`): custom issues naming one of its keys get `messageKey`.
+ */
+export declare function toIssues(error: z.ZodError, messages?: Record<string, unknown>): ConfigIssue[];

package/dist/extensions/config-issues.js

@@ -23,9 +23,26 @@ function issueMessage(i) {
             return "invalid value";
     }
 }
-export function toIssues(error) {
-    return error.issues.map((i) => ({
-        path: i.path.map(String).join("."),
-        message: issueMessage(i),
-    }));
+/** The `params.ui` of a custom issue when it names one of `messages` (own keys only). */
+function messageKeyOf(i, messages) {
+    if (i.code !== "custom" || messages === undefined)
+        return undefined;
+    const key = i.params?.ui;
+    return typeof key === "string" && Object.hasOwn(messages, key) ? key : undefined;
+}
+/**
+ * The issues of a failed config parse. `messages` is the root `x-ui.messages` of the schema's
+ * form JSON Schema (`configMessages`): custom issues naming one of its keys get `messageKey`.
+ */
+export function toIssues(error, messages) {
+    return error.issues.map((i) => {
+        const segments = i.path.map((s) => (typeof s === "number" ? s : String(s)));
+        const messageKey = messageKeyOf(i, messages);
+        return {
+            path: segments.join("."),
+            segments,
+            message: issueMessage(i),
+            ...(messageKey !== undefined && { messageKey }),
+        };
+    });
 }

package/dist/extensions/config-json-schema.d.ts

@@ -1,9 +1,45 @@
-import { z } from "zod";
-export type JsonSchema = Record<string, unknown>;
 /**
- * 把插件配置 schema 转成 JSON Schema（供界面渲染表单）：
- * - `secret()` 字段带 `"x-secret": true`（去掉 zod 附带的 `secret` 元数据键）；
- * - 无法表达的类型为 `{ "x-unsupported": true }`，不抛错；
- * - 以输入侧形态输出（含 default），不带 `$schema`。
+ * Config schema → JSON Schema for forms. The conversion (and the secret scrub) lives in the SDK
+ * (`configJsonSchema`, extension config forms spec §4.1) so the packer, the checks and the kernel
+ * share one implementation; the kernel keeps no copy.
  */
-export declare function configToJsonSchema(schema: z.ZodType): JsonSchema;
+import { type ConfigUiProblem, type JsonSchema } from "@capybara-hq/plugin-sdk";
+import type { z } from "zod";
+export { configJsonSchema as configToJsonSchema, type JsonSchema } from "@capybara-hq/plugin-sdk";
+/** The config level a schema belongs to (which hints `validateConfigUi` allows). */
+export type ConfigLevel = "deployment" | "org" | "connection";
+/** A config schema as served to forms, with the problems of its hints (empty = kept). */
+export interface ConfigFormSchema {
+    /** Shared by every caller: clone it before handing it out or changing it. */
+    readonly schema: JsonSchema;
+    readonly problems: ConfigUiProblem[];
+}
+/**
+ * Removes every `x-ui` from a JSON Schema in place (a property named `x-ui` is kept, and so are
+ * values: `default`, `const`, `enum` and `examples` are left as they are).
+ */
+export declare function stripConfigUi(node: unknown): void;
+/**
+ * Validates the hints of a JSON Schema at a level and strips every `x-ui` when there is any
+ * problem (in place): invalid hints never reach a form, and never fail a load (spec §4.1).
+ */
+export declare function checkConfigUi(schema: JsonSchema, level: ConfigLevel): ConfigUiProblem[];
+/** A config schema's form JSON Schema ({@link checkConfigUi} applied), cached per schema object. */
+export declare function configFormSchema(schema: z.ZodTypeAny, level: ConfigLevel): ConfigFormSchema;
+/**
+ * {@link configFormSchema} that never throws, for every caller that serves a form schema or reads
+ * its messages (deployment, org, connection, issues). A hint conversion that throws (a hand-made
+ * package, e.g. hints that won't serialize as JSON) drops the hints: the plain schema with every
+ * `x-ui` stripped, else `null` when even the plain conversion fails. `onFallback` runs once per
+ * schema object and level on this replica (the caller's one warning); later calls reuse the result.
+ */
+export declare function safeConfigFormSchema(schema: z.ZodTypeAny, level: ConfigLevel, onFallback: (err: unknown, fallback: "plain" | "none") => void): ConfigFormSchema | null;
+/**
+ * The secret record paths some `x-ui.secrets[].path` of a form schema names (spec §4.3), anywhere in
+ * the schema. Read from a checked schema: one whose hints were invalid was stripped and names none.
+ */
+export declare function hintedSecretPaths(node: unknown, out?: Set<string>): Set<string>;
+/** The root `x-ui.messages` of a form schema (the localized texts of custom issues), if any. */
+export declare function configMessages(schema: JsonSchema | null | undefined): Record<string, unknown> | undefined;
+/** A short text of hint problems for a status detail or a log (the first few). */
+export declare function describeConfigUiProblems(level: ConfigLevel, problems: ConfigUiProblem[]): string;

package/dist/extensions/config-json-schema.js

@@ -1,73 +1,139 @@
-import { z } from "zod";
-/** JSON Schema 无法表达的 zod 类型：降级为 `{}` 并标注 `x-unsupported`。 */
-const UNSUPPORTED = new Set([
-    "bigint",
-    "date",
-    "symbol",
-    "undefined",
-    "void",
-    "nan",
-    "map",
-    "set",
-    "function",
-    "promise",
-    "custom",
-    "file",
-]);
 /**
- * 把插件配置 schema 转成 JSON Schema（供界面渲染表单）：
- * - `secret()` 字段带 `"x-secret": true`（去掉 zod 附带的 `secret` 元数据键）；
- * - 无法表达的类型为 `{ "x-unsupported": true }`，不抛错；
- * - 以输入侧形态输出（含 default），不带 `$schema`。
+ * Config schema → JSON Schema for forms. The conversion (and the secret scrub) lives in the SDK
+ * (`configJsonSchema`, extension config forms spec §4.1) so the packer, the checks and the kernel
+ * share one implementation; the kernel keeps no copy.
  */
-export function configToJsonSchema(schema) {
-    const out = z.toJSONSchema(schema, {
-        io: "input",
-        unrepresentable: "any",
-        override: (ctx) => {
-            const js = ctx.jsonSchema;
-            const def = ctx.zodSchema._zod.def;
-            if (js.secret === true) {
-                delete js.secret;
-                js["x-secret"] = true;
-            }
-            if (UNSUPPORTED.has(def.type))
-                js["x-unsupported"] = true;
-        },
-    });
-    delete out.$schema;
-    scrubSecrets(out);
-    return out;
-}
-/** 会泄露取值的关键字：密钥字段一律不输出。 */
-const VALUE_KEYWORDS = ["default", "examples", "const", "enum"];
-/** 值为「名字 -> 子 schema」映射的关键字：其键是用户字段名，不是关键字。 */
+import { configJsonSchema, validateConfigUi, } from "@capybara-hq/plugin-sdk";
+export { configJsonSchema as configToJsonSchema } from "@capybara-hq/plugin-sdk";
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** Keywords whose value maps names to sub-schemas: their keys are field names, not keywords. */
 const SCHEMA_MAPS = new Set(["properties", "patternProperties", "$defs", "definitions"]);
+/** Keywords whose value is data, not a schema: never recursed into. */
+const VALUE_KEYWORDS = new Set(["default", "const", "enum", "examples"]);
 /**
- * 递归清掉密钥节点及其所有后代上会暴露取值的关键字（`inSecret` 随递归下传）；无环（输出为纯 JSON 树）。
- * 只有 schema 关键字 default / examples / const / enum 的值被当作数据跳过；
- * `properties` 等映射里的键是字段名，名为 default / enum 的字段照常遍历。
+ * Removes every `x-ui` from a JSON Schema in place (a property named `x-ui` is kept, and so are
+ * values: `default`, `const`, `enum` and `examples` are left as they are).
  */
-function scrubSecrets(node, inSecret = false) {
+export function stripConfigUi(node) {
     if (Array.isArray(node)) {
         for (const n of node)
-            scrubSecrets(n, inSecret);
+            stripConfigUi(n);
         return;
     }
-    if (typeof node !== "object" || node === null)
+    if (!isObj(node))
         return;
-    const o = node;
-    const secret = inSecret || o["x-secret"] === true;
-    if (secret)
-        for (const k of VALUE_KEYWORDS)
-            delete o[k];
-    for (const [k, v] of Object.entries(o)) {
-        if (SCHEMA_MAPS.has(k) && typeof v === "object" && v !== null) {
+    delete node["x-ui"];
+    for (const [k, v] of Object.entries(node)) {
+        if (VALUE_KEYWORDS.has(k))
+            continue;
+        if (SCHEMA_MAPS.has(k) && isObj(v))
             for (const child of Object.values(v))
-                scrubSecrets(child, secret);
+                stripConfigUi(child);
+        else
+            stripConfigUi(v);
+    }
+}
+/**
+ * Validates the hints of a JSON Schema at a level and strips every `x-ui` when there is any
+ * problem (in place): invalid hints never reach a form, and never fail a load (spec §4.1).
+ */
+export function checkConfigUi(schema, level) {
+    const problems = validateConfigUi(schema, level);
+    if (problems.length > 0)
+        stripConfigUi(schema);
+    return problems;
+}
+/** Manifests are immutable: one conversion per zod schema object and level (read-only, per replica). */
+const caches = {
+    deployment: new WeakMap(),
+    org: new WeakMap(),
+    connection: new WeakMap(),
+};
+/** A config schema's form JSON Schema ({@link checkConfigUi} applied), cached per schema object. */
+export function configFormSchema(schema, level) {
+    const cache = caches[level];
+    let r = cache.get(schema);
+    if (!r) {
+        const js = configJsonSchema(schema);
+        r = { schema: js, problems: checkConfigUi(js, level) };
+        cache.set(schema, r);
+    }
+    return r;
+}
+/** The schemas whose hinted conversion threw: their fallback (plain schema, or null). */
+const fallbacks = {
+    deployment: new WeakMap(),
+    org: new WeakMap(),
+    connection: new WeakMap(),
+};
+/**
+ * {@link configFormSchema} that never throws, for every caller that serves a form schema or reads
+ * its messages (deployment, org, connection, issues). A hint conversion that throws (a hand-made
+ * package, e.g. hints that won't serialize as JSON) drops the hints: the plain schema with every
+ * `x-ui` stripped, else `null` when even the plain conversion fails. `onFallback` runs once per
+ * schema object and level on this replica (the caller's one warning); later calls reuse the result.
+ */
+export function safeConfigFormSchema(schema, level, onFallback) {
+    const failed = fallbacks[level].get(schema);
+    if (failed !== undefined)
+        return failed;
+    try {
+        return configFormSchema(schema, level);
+    }
+    catch (err) {
+        let r = null;
+        try {
+            const plain = configJsonSchema(schema);
+            stripConfigUi(plain);
+            r = { schema: plain, problems: [] };
+        }
+        catch {
+            r = null;
         }
-        else if (!VALUE_KEYWORDS.includes(k)) {
-            scrubSecrets(v, secret);
+        fallbacks[level].set(schema, r);
+        onFallback(err, r ? "plain" : "none");
+        return r;
+    }
+}
+/**
+ * The secret record paths some `x-ui.secrets[].path` of a form schema names (spec §4.3), anywhere in
+ * the schema. Read from a checked schema: one whose hints were invalid was stripped and names none.
+ */
+export function hintedSecretPaths(node, out = new Set()) {
+    if (Array.isArray(node)) {
+        for (const n of node)
+            hintedSecretPaths(n, out);
+        return out;
+    }
+    if (!isObj(node))
+        return out;
+    const hints = node["x-ui"];
+    if (isObj(hints) && Array.isArray(hints.secrets)) {
+        for (const s of hints.secrets) {
+            if (isObj(s) && typeof s.path === "string")
+                out.add(s.path);
         }
     }
+    for (const [k, v] of Object.entries(node)) {
+        if (k === "x-ui" || VALUE_KEYWORDS.has(k))
+            continue;
+        if (SCHEMA_MAPS.has(k) && isObj(v)) {
+            for (const child of Object.values(v))
+                hintedSecretPaths(child, out);
+        }
+        else
+            hintedSecretPaths(v, out);
+    }
+    return out;
+}
+/** The root `x-ui.messages` of a form schema (the localized texts of custom issues), if any. */
+export function configMessages(schema) {
+    const hints = schema?.["x-ui"];
+    return isObj(hints) && isObj(hints.messages) ? hints.messages : undefined;
+}
+/** A short text of hint problems for a status detail or a log (the first few). */
+export function describeConfigUiProblems(level, problems) {
+    const shown = problems.slice(0, 5).map((p) => `${p.path || "<root>"}: ${p.message}`);
+    const more = problems.length > shown.length ? `; and ${problems.length - shown.length} more` : "";
+    return `${level} config UI hints ignored (${shown.join("; ")}${more})`;
 }

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

@@ -1,6 +1,7 @@
 import type { core } from "zod";
 import { type Keyring } from "../ctx/secrets.js";
 import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import type { JsonSchema } from "./config-json-schema.js";
 type Obj = Record<string, unknown>;
 /**
  * The stored half of the deployment-level extension config (C10): where PG keeps it, how it is read
@@ -16,6 +17,11 @@ export declare const secretKey: (plugin: string, path: string) => string;
 export interface DeploymentSchemaInfo {
     version: string;
     schema?: core.$ZodType | undefined;
+    /**
+     * Without `schema` (no module on this replica): the package's static form schema
+     * (`extension.configSchemas.deployment`), shown but never used to validate.
+     */
+    jsonSchema?: JsonSchema | undefined;
     fields: {
         path: string;
         secret: boolean;

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

@@ -1,3 +1,4 @@
+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";
@@ -12,6 +13,7 @@ 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";
@@ -34,15 +36,36 @@ 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[];
+}
+/**
+ * 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;
@@ -79,6 +102,7 @@ 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, 
@@ -91,7 +115,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 +137,40 @@ 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`.
+     * `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 `lockEnterpriseAdminsAndAuthorize` (re-checks the enterprise 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 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;
 }
 /**
  * 本副本拿不到模块时（未加载的安装记录）按包内审阅过的静态清单给出字段（没有 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>;