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

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/bootstrap.d.ts

@@ -35,7 +35,7 @@ import { ExtensionRegistry } from "./registry.js";
  *   manifest's sha256 (written with the audit `bootstrap.completed` only when every entry
  *   succeeded; otherwise the next start runs it again, which is idempotent).
  * - Only entries new to the manifest are installed (Ruling 5): an optional entry that the last
- *   completed run already handled and that is not installed now (an enterprise admin uninstalled
+ *   completed run already handled and that is not installed now (a super admin uninstalled
  *   it) stays uninstalled -> `kept`. A required entry is always installed.
  * - Per entry, by the installed state of its extension:
  *   - not installed (and new, or required): imported into the catalog (source `bootstrap`, ref
@@ -44,8 +44,8 @@ import { ExtensionRegistry } from "./registry.js";
  *     and enabled -> `installed`;
  *   - installed from `bootstrap` at a lower version: upgraded the same way (core's release vouched
  *     for the version, so new permissions are pre-approved and audited), keeping the desired state
- *     an enterprise admin chose (a disabled optional plugin stays disabled) -> `upgraded`;
- *   - installed at a higher version, or from another source (an enterprise admin upgraded it), or
+ *     a super admin chose (a disabled optional plugin stays disabled) -> `upgraded`;
+ *   - installed at a higher version, or from another source (a super admin upgraded it), or
  *     the name is config-declared (`declared`: config wins, no install record is created):
  *     untouched, never downgraded -> `kept`;
  *   - a declarative plugin (no extension): imported into the catalog only -> `imported` (`kept`
@@ -175,6 +175,12 @@ export declare class BootstrapService {
         /** The plugin import a declarative entry (or an entry's catalog version) goes through. */
         imports: BootstrapImports;
     }): Promise<BootstrapResult>;
+    /**
+     * A pin whose plugin name an org holds (a live org-owned catalog item): the bootstrap takes no
+     * name over (ruling P3-28), so the entry fails; this warning tells the super admin why and
+     * which org holds it (final review M4).
+     */
+    private warnIfHeld;
     /** The `bootstrap_runs` row and the `bootstrap.completed` audit, in one transaction. */
     private recordDone;
     /**
@@ -186,10 +192,17 @@ export declare class BootstrapService {
     /** The entry names the last completed run handled (undefined before any run completed). */
     private lastRunNames;
     private entry;
+    /**
+     * The catalog item of a bootstrap entry follows `required`: a required entry is builtin, offered
+     * to every org (scope `all`) and not disabled (migration 0075 could leave a required plugin
+     * disabled); an entry that stops being required is no longer builtin and keeps scope `all` (the
+     * admin may change it from then on).
+     */
+    private markBuiltin;
     /** A declarative plugin: catalog only. Returns false when that version is already imported. */
     private importOnly;
     /**
-     * Imports, approves, installs and enables (one review, confirmed with `deployExtension`). When
+     * Imports, approves, installs and enables (one review; its confirm deploys the extension). When
      * the catalog already has this version (an earlier run stopped after importing, or the same
      * package came from a marketplace), the extension is deployed from the package store instead.
      */

package/dist/extensions/bootstrap.js

@@ -15,6 +15,7 @@ import { parseBootstrapManifest, SDK_VERSION, } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable, Optional } from "@nestjs/common";
 import { sql } from "kysely";
 import semver from "semver";
+import { otherNameOwner } from "../catalog/ownership.js";
 import { catalogPackageError } from "../catalog/plugin-import.js";
 import { PluginPackageError, readPluginPackage } from "../catalog/plugin-package.js";
 import { ApiError } from "../errors.js";
@@ -57,7 +58,7 @@ import { ExtensionRegistry } from "./registry.js";
  *   manifest's sha256 (written with the audit `bootstrap.completed` only when every entry
  *   succeeded; otherwise the next start runs it again, which is idempotent).
  * - Only entries new to the manifest are installed (Ruling 5): an optional entry that the last
- *   completed run already handled and that is not installed now (an enterprise admin uninstalled
+ *   completed run already handled and that is not installed now (a super admin uninstalled
  *   it) stays uninstalled -> `kept`. A required entry is always installed.
  * - Per entry, by the installed state of its extension:
  *   - not installed (and new, or required): imported into the catalog (source `bootstrap`, ref
@@ -66,8 +67,8 @@ import { ExtensionRegistry } from "./registry.js";
  *     and enabled -> `installed`;
  *   - installed from `bootstrap` at a lower version: upgraded the same way (core's release vouched
  *     for the version, so new permissions are pre-approved and audited), keeping the desired state
- *     an enterprise admin chose (a disabled optional plugin stays disabled) -> `upgraded`;
- *   - installed at a higher version, or from another source (an enterprise admin upgraded it), or
+ *     a super admin chose (a disabled optional plugin stays disabled) -> `upgraded`;
+ *   - installed at a higher version, or from another source (a super admin upgraded it), or
  *     the name is config-declared (`declared`: config wins, no install record is created):
  *     untouched, never downgraded -> `kept`;
  *   - a declarative plugin (no extension): imported into the catalog only -> `imported` (`kept`
@@ -306,6 +307,7 @@ let BootstrapService = class BootstrapService {
             const failures = [];
             for (const e of o.manifest.plugins) {
                 signal.throwIfAborted();
+                await this.warnIfHeld(e);
                 try {
                     const r = await this.entry(e, files.get(e.name), handled, o.imports);
                     results.push(carried(r, o.carry));
@@ -334,6 +336,23 @@ let BootstrapService = class BootstrapService {
             return { manifestSha256, results };
         });
     }
+    /**
+     * A pin whose plugin name an org holds (a live org-owned catalog item): the bootstrap takes no
+     * name over (ruling P3-28), so the entry fails; this warning tells the super admin why and
+     * which org holds it (final review M4).
+     */
+    async warnIfHeld(e) {
+        const holder = await otherNameOwner(this.db, e.name, null);
+        if (holder?.kind !== "org")
+            return;
+        this.log.warn("bootstrap: the plugin name is held by an organization; the entry cannot take it over until the organization renames or deletes its plugin", {
+            plugin: e.name,
+            version: e.version,
+            required: e.required,
+            ownerOrgId: holder.orgId,
+            ownerOrg: holder.name,
+        });
+    }
     /** The `bootstrap_runs` row and the `bootstrap.completed` audit, in one transaction. */
     async recordDone(manifestSha256, results) {
         await this.db
@@ -400,9 +419,11 @@ let BootstrapService = class BootstrapService {
         // Not new to the manifest: an optional entry left out on purpose stays out (Ruling 5)
         const isNew = handled === undefined || !handled.has(e.name);
         if (!pkg.manifest.extension) {
+            await this.markBuiltin(e.name, e.required);
             if (!isNew)
                 return { name: e.name, action: "kept", version: e.version };
             const imported = await this.importOnly(e, bytes, ref, imports);
+            await this.markBuiltin(e.name, e.required);
             return { name: e.name, action: imported ? "imported" : "kept", version: e.version };
         }
         if (this.registry.declared().has(e.name)) {
@@ -451,8 +472,41 @@ let BootstrapService = class BootstrapService {
         if (e.required && row?.desired_state === "disabled") {
             await this.ops.enable(e.name, null);
         }
+        await this.markBuiltin(e.name, e.required);
         return result;
     }
+    /**
+     * The catalog item of a bootstrap entry follows `required`: a required entry is builtin, offered
+     * to every org (scope `all`) and not disabled (migration 0075 could leave a required plugin
+     * disabled); an entry that stops being required is no longer builtin and keeps scope `all` (the
+     * admin may change it from then on).
+     */
+    async markBuiltin(name, required) {
+        const touch = { updated_at: sql `now()` };
+        if (required) {
+            await this.db
+                .updateTable("catalog_items")
+                .set({
+                builtin: true,
+                scope: "all",
+                disabled: false,
+                scope_version: sql `scope_version + 1`,
+                ...touch,
+            })
+                .where("name", "=", name)
+                .where("deleted_at", "is", null)
+                .where((eb) => eb.or([eb("builtin", "=", false), eb("scope", "<>", "all"), eb("disabled", "=", true)]))
+                .execute();
+            return;
+        }
+        await this.db
+            .updateTable("catalog_items")
+            .set({ builtin: false, ...touch })
+            .where("name", "=", name)
+            .where("deleted_at", "is", null)
+            .where("builtin", "=", true)
+            .execute();
+    }
     /** A declarative plugin: catalog only. Returns false when that version is already imported. */
     async importOnly(e, bytes, ref, imports) {
         try {
@@ -461,10 +515,7 @@ let BootstrapService = class BootstrapService {
                 ref,
                 integrity: e.integrity,
             });
-            await imports.confirm(null, stagingId, {
-                reviewHash: review.reviewHash,
-                deployExtension: false,
-            });
+            await imports.confirm(null, stagingId, { reviewHash: review.reviewHash });
             return true;
         }
         catch (err) {
@@ -474,7 +525,7 @@ let BootstrapService = class BootstrapService {
         }
     }
     /**
-     * Imports, approves, installs and enables (one review, confirmed with `deployExtension`). When
+     * Imports, approves, installs and enables (one review; its confirm deploys the extension). When
      * the catalog already has this version (an earlier run stopped after importing, or the same
      * package came from a marketplace), the extension is deployed from the package store instead.
      */
@@ -496,7 +547,6 @@ let BootstrapService = class BootstrapService {
         }
         const r = await imports.confirm(null, staged.stagingId, {
             reviewHash: staged.review.reviewHash,
-            deployExtension: true,
             enable,
         });
         if (r.deploy?.result === "failed") {
@@ -552,6 +602,17 @@ let BootstrapService = class BootstrapService {
         if (names.length > 0)
             q = q.where("name", "not in", names);
         const rows = await q.returning(["name", "version"]).execute();
+        for (const r of rows)
+            await this.markBuiltin(r.name, false);
+        // A declarative plugin has no install record: clear builtin by catalog name
+        let items = this.db
+            .updateTable("catalog_items")
+            .set({ builtin: false, updated_at: sql `now()` })
+            .where("builtin", "=", true)
+            .where("deleted_at", "is", null);
+        if (names.length > 0)
+            items = items.where("name", "not in", names);
+        await items.execute();
         return rows.map((r) => ({ name: r.name, action: "required_cleared", version: r.version }));
     }
 };

package/dist/extensions/cli.d.ts

@@ -54,6 +54,18 @@ export interface ExtensionCli {
     publishChanged(plugin: string): Promise<boolean>;
     close(): Promise<void>;
 }
+/**
+ * The effective deployment config (the startup config `fileValue` completed by the `stored` PG
+ * fields) parsed as the host's load gate does: overridable fields may stay empty (spec A §5.4a),
+ * hidden and read-only ones must be complete.
+ */
+export declare function parseDeploymentConfig(schema: z.ZodTypeAny, stored: Record<string, unknown>, fileValue: unknown): {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    issues: ConfigIssue[];
+};
 /**
  * The CLI's extension management context (C18, F-Q): a Nest application context with
  * the extensions module over the database and a lazy Redis connection used only for publishing

package/dist/extensions/cli.js

@@ -13,7 +13,17 @@ import { ExtensionsModule } from "./extensions.module.js";
 import { ExtensionHost } from "./host.js";
 import { ExtensionInstalls } from "./installs.js";
 import { PLUGINS_CHANGED_TOPIC } from "./lifecycle-topics.js";
+import { parseLoadGate } from "./org-levels.js";
 import { ExtensionPackageError, extensionPackageApiError, permissionSetOfPackage, readExtensionPackage, } from "./package.js";
+/**
+ * The effective deployment config (the startup config `fileValue` completed by the `stored` PG
+ * fields) parsed as the host's load gate does: overridable fields may stay empty (spec A §5.4a),
+ * hidden and read-only ones must be complete.
+ */
+export function parseDeploymentConfig(schema, stored, fileValue) {
+    const r = parseLoadGate(schema, mergeDeploymentConfig(stored, fileValue, schemaFields(schema).map((f) => f.path)));
+    return r.success ? { ok: true, value: r.data } : { ok: false, issues: toIssues(r.error) };
+}
 /**
  * The CLI's extension management context (C18, F-Q): a Nest application context with
  * the extensions module over the database and a lazy Redis connection used only for publishing
@@ -44,8 +54,7 @@ export async function openExtensionCli(config, log, opts = {}) {
         const stored = await readStoredDeploymentConfig(db.db, keyring, name, {
             secretPaths: secretPathsOf(schemaFields(schema)),
         });
-        const r = schema.safeParse(mergeDeploymentConfig(stored, config.extensionConfig[name], schemaFields(schema).map((f) => f.path)));
-        return r.success ? { ok: true, value: r.data } : { ok: false, issues: toIssues(r.error) };
+        return parseDeploymentConfig(schema, stored, config.extensionConfig[name]);
     };
     const configIssues = new Map();
     const deploymentConfigs = new Map();

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;