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

package/dist/extensions/blobs.js

@@ -9,10 +9,13 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 import { createHash } from "node:crypto";
 import { Inject, Injectable } from "@nestjs/common";
+import { ClientBuilds } from "../client/client-builds.service.js";
+import { CLIENT_DIR } from "../client/client-files.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
 import { Transactional } from "../infra/database/transactional.decorator.js";
+import { unpackPackageTgz } from "../packages/tgz.js";
 import { StorageService } from "../storage/storage.service.js";
 /**
  * Content-addressed extension package store (C13): one copy per sha256 of the whole tgz.
@@ -21,6 +24,13 @@ import { StorageService } from "../storage/storage.service.js";
  *   extension, F-Q): PG `extension_blobs` (`blob_store = pg`, also limited by `packages.maxBytes`).
  * Each package's location is recorded in `extension_packages.blob_store`; reads follow the record and
  * check the sha256.
+ *
+ * A package with an `extension.client` section also stores its client build (`ClientBuilds`,
+ * client extensions spec §9.1): the client files are read again from the bytes being stored,
+ * checked against the section and written to object storage before the package row's transaction,
+ * and the build row is inserted in that transaction, all under the build's lock. Without object
+ * storage (`ClientBuilds`' own, which the CLI points at its store) such a package is refused
+ * (`storage.unavailable`), so a stored build always has its files.
  */
 /** 取到的包与 sha256 不符（存储里的字节被篡改或损坏）。 */
 export class ExtensionBlobIntegrityError extends Error {
@@ -39,6 +49,7 @@ let ExtensionBlobs = class ExtensionBlobs {
     txHost;
     storage;
     config;
+    clientBuilds;
     /**
      * CLI only: packages the CLI process imported itself and reads back before the store, since such
      * a package may be recorded in an object store the CLI cannot read. Each entry's sha256 was
@@ -48,11 +59,12 @@ let ExtensionBlobs = class ExtensionBlobs {
     local = new Map();
     constructor(db, txHost, 
     /** Without an object-store extension (the CLI) packages go to PG. */
-    storage, config) {
+    storage, config, clientBuilds) {
         this.db = db;
         this.txHost = txHost;
         this.storage = storage;
         this.config = config;
+        this.clientBuilds = clientBuilds;
     }
     /** `packages.maxBytes` (read at every call). */
     maxBytes() {
@@ -85,16 +97,38 @@ let ExtensionBlobs = class ExtensionBlobs {
         if (createHash("sha256").update(bytes).digest("hex") !== p.sha256) {
             throw new ExtensionBlobIntegrityError(p.sha256);
         }
+        const client = p.section.client;
+        if (client === undefined) {
+            await this.store(p, bytes, src, undefined);
+            return;
+        }
+        // client code is delivered from object storage: refused before anything is written without it
+        this.clientBuilds.assertAvailable();
+        const files = await this.clientFiles(bytes);
+        // one store or delete of this package's client build at a time (ClientBuilds header)
+        await this.clientBuilds.locked(p.sha256, () => this.store(p, bytes, src, { section: client, files }));
+    }
+    /** {@link put} after its checks; `client` for a package with client code (under its lock). */
+    async store(p, bytes, src, client) {
+        const plugin = p.section.manifest.name;
         const existing = await this.db
             .selectFrom("extension_packages")
             .select("blob_store")
             .where("sha256", "=", p.sha256)
             .executeTakeFirst();
         if (existing) {
-            // 记录已在：字节若丢了（对象被删、库被清）就按原存放位置补上
+            // The row is there: bytes that went missing (an object deleted, a database cleared) are
+            // restored where the row says, and so are the client build's files and row
             await this.repair(p.sha256, existing.blob_store, bytes);
+            if (client !== undefined) {
+                await this.clientBuilds.extract(p.sha256, plugin, client.files, client.section);
+            }
             return;
         }
+        // checked and written before the transaction (no object storage call inside one)
+        const build = client !== undefined
+            ? await this.clientBuilds.writeFiles(p.sha256, plugin, client.files, client.section)
+            : undefined;
         const store = src.store ?? (this.storage.available ? "object" : "pg");
         if (store === "object") {
             if (!this.storage.available)
@@ -106,9 +140,14 @@ let ExtensionBlobs = class ExtensionBlobs {
         }
         // the row stores the plugin's extension section as reviewed (without the name / version copy)
         const { name: _name, version: _version, ...section } = p.section;
-        await this.record(p, section, bytes, src, store);
+        await this.record(p, section, bytes, src, store, build);
+    }
+    /** The files under `dist/client/` of a package's bytes (sha256 already checked by the caller). */
+    async clientFiles(bytes) {
+        const files = await unpackPackageTgz(bytes, { maxBytes: this.maxBytes() });
+        return new Map(files.filter((f) => f.path.startsWith(CLIENT_DIR)).map((f) => [f.path, f.data]));
     }
-    async record(p, section, bytes, src, store) {
+    async record(p, section, bytes, src, store, build) {
         const m = p.section.manifest;
         const inserted = await this.db
             .insertInto("extension_packages")
@@ -123,6 +162,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")
@@ -134,6 +174,9 @@ let ExtensionBlobs = class ExtensionBlobs {
                 .onConflict((oc) => oc.column("sha256").doNothing())
                 .execute();
         }
+        // the build row commits with the package row it references (or after another replica's)
+        if (build !== undefined)
+            await this.clientBuilds.insert(build);
     }
     /** 已有记录的包：按记录的存放位置检查字节在不在，不在就写回（调用方已校验 sha256）。 */
     async repair(sha256, store, bytes) {
@@ -204,7 +247,8 @@ ExtensionBlobs = __decorate([
     __param(0, Inject(KernelDb)),
     __param(1, Inject(TransactionHost)),
     __param(2, Inject(StorageService)),
-    __param(3, Inject(KernelConfigService))
+    __param(3, Inject(KernelConfigService)),
+    __param(4, Inject(ClientBuilds))
 ], ExtensionBlobs);
 export { ExtensionBlobs };
 async function readCapped(body, max) {

package/dist/extensions/bootstrap.d.ts

@@ -11,6 +11,7 @@ import { ExtensionAdminOps } from "./admin-ops.js";
 import { ExtensionInstalls } from "./installs.js";
 import { PluginApproveLock } from "./locks.js";
 import { ExtensionRegistry } from "./registry.js";
+import type { SingleProviderNote } from "./single-provider.js";
 /**
  * The bootstrap step (package ecosystem spec §7, startup bootstrap spec): installs the plugins
  * pinned by the bootstrap manifest (`packages/kernel/bootstrap.json`). It replaced the builtin
@@ -35,7 +36,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 +45,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`
@@ -61,7 +62,10 @@ import { ExtensionRegistry } from "./registry.js";
  * A failed entry does not stop the others; the run then throws {@link BootstrapFailedError} naming
  * them. The packages are kept in PG (`blob_store = 'pg'`), so installing an extension never needs
  * the object store (object-store-s3 is itself a bootstrap plugin) and the directory and npm are
- * never needed again; a declarative plugin's catalog files do need the object store.
+ * never needed again. A plugin's icons and setup guide files are kept in PG too (`catalog_files`),
+ * so they never need it either; its skills, connector templates and agent templates do (an entry
+ * shipping them fails while no object store runs; an optional one is retried after the extensions
+ * loaded).
  */
 /** The bootstrap manifest that ships with the kernel package. */
 export declare const BOOTSTRAP_MANIFEST_FILE: string;
@@ -71,6 +75,11 @@ export interface BootstrapEntryResult {
     action: "installed" | "upgraded" | "kept" | "imported" | "required_cleared";
     /** The version installed / imported now, or the version kept. */
     version: string;
+    /**
+     * An optional entry installed (or upgraded) but left disabled: another enabled extension holds
+     * a single-provider extension point it provides. (A required entry fails instead.)
+     */
+    leftDisabled?: SingleProviderNote;
 }
 export interface BootstrapResult {
     /** sha256 (hex) of the manifest ({@link bootstrapManifestSha256}). */
@@ -175,6 +184,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,16 +201,37 @@ 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.
      */
     private deploy;
     /** The extension of a catalog version already imported: ingest, approve, install (, enable). */
     private deployFromStore;
+    /**
+     * Enables a bootstrap extension unless another enabled extension provides one of its
+     * single-provider extension points (see {@link leftDisabled}).
+     */
+    private enableOrWarn;
+    /**
+     * A bootstrap extension left disabled because another enabled extension holds a single-provider
+     * extension point it provides. An optional preinstall (a sandbox while the super admin runs
+     * another one) stays disabled with a warning, and the entry's result says so. A required entry
+     * fails (thrown, so the run is not recorded done, `capybara bootstrap` exits 1 and
+     * `capybara start` refuses to serve): the deployment cannot run without it, and only the super
+     * admin can free the point, by disabling the other provider and running the bootstrap again.
+     */
+    private leftDisabled;
     /** The permission snapshot of a stored package (source `bootstrap`), under the approve lock. */
     private approveStored;
     /** Install records still `required` whose entry left the manifest lose `required`. */

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`
@@ -83,7 +84,10 @@ import { ExtensionRegistry } from "./registry.js";
  * A failed entry does not stop the others; the run then throws {@link BootstrapFailedError} naming
  * them. The packages are kept in PG (`blob_store = 'pg'`), so installing an extension never needs
  * the object store (object-store-s3 is itself a bootstrap plugin) and the directory and npm are
- * never needed again; a declarative plugin's catalog files do need the object store.
+ * never needed again. A plugin's icons and setup guide files are kept in PG too (`catalog_files`),
+ * so they never need it either; its skills, connector templates and agent templates do (an entry
+ * shipping them fails while no object store runs; an optional one is retried after the extensions
+ * loaded).
  */
 /** The bootstrap manifest that ships with the kernel package. */
 export const BOOTSTRAP_MANIFEST_FILE = fileURLToPath(new URL("../../bootstrap.json", import.meta.url));
@@ -306,6 +310,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 +339,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 +422,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)) {
@@ -421,13 +445,14 @@ let BootstrapService = class BootstrapService {
             return { name: e.name, action: "kept", version: e.version };
         }
         let result;
+        let leftDisabled;
         if (!row) {
-            await this.deploy(e, bytes, ref, true, imports);
+            leftDisabled = await this.deploy(e, bytes, ref, true, imports);
             result = { name: e.name, action: "installed", version: e.version };
         }
         else if (row.source === "bootstrap" && isLower(row.version, e.version)) {
             // The desired state the admin chose is kept; a required plugin is enabled below anyway
-            await this.deploy(e, bytes, ref, row.desired_state === "enabled", imports);
+            leftDisabled = await this.deploy(e, bytes, ref, row.desired_state === "enabled", imports);
             result = { name: e.name, action: "upgraded", version: e.version };
         }
         else {
@@ -449,9 +474,42 @@ let BootstrapService = class BootstrapService {
         }
         // A required install must run on the deployment (an org cannot use it otherwise)
         if (e.required && row?.desired_state === "disabled") {
-            await this.ops.enable(e.name, null);
+            leftDisabled = await this.enableOrWarn(e);
         }
-        return result;
+        await this.markBuiltin(e.name, e.required);
+        return leftDisabled === undefined ? result : { ...result, leftDisabled };
+    }
+    /**
+     * 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) {
@@ -461,10 +519,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 +529,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.
      */
@@ -489,19 +544,25 @@ let BootstrapService = class BootstrapService {
         }
         catch (err) {
             if (err instanceof ApiError && err.code === "catalog.version_exists") {
-                await this.deployFromStore(e, bytes, ref, enable);
-                return;
+                return this.deployFromStore(e, bytes, ref, enable);
             }
             throw err;
         }
         const r = await imports.confirm(null, staged.stagingId, {
             reviewHash: staged.review.reviewHash,
-            deployExtension: true,
             enable,
         });
         if (r.deploy?.result === "failed") {
             throw new ApiError((r.deploy.code ?? "internal"), r.deploy.message ?? `installing extension ${e.name} failed`);
         }
+        if (r.deploy?.singleProvider !== undefined) {
+            return this.leftDisabled(e, {
+                code: r.deploy.code,
+                message: r.deploy.message,
+                singleProvider: r.deploy.singleProvider,
+            });
+        }
+        return undefined;
     }
     /** The extension of a catalog version already imported: ingest, approve, install (, enable). */
     async deployFromStore(e, bytes, ref, enable) {
@@ -523,9 +584,39 @@ let BootstrapService = class BootstrapService {
             .where("name", "=", e.name)
             .where("deleted_at", "is", null)
             .executeTakeFirst();
-        await this.ops.install(e.name, review.sha256, null, undefined, item ? { catalogItemId: item.id } : {});
-        if (enable)
-            await this.ops.enable(e.name, null);
+        const installed = await this.ops.install(e.name, review.sha256, null, undefined, item ? { catalogItemId: item.id } : {});
+        // An upgrade newly providing a held single-provider point is left disabled by the install
+        if (installed.leftDisabled !== undefined)
+            return this.leftDisabled(e, installed.leftDisabled);
+        return enable ? this.enableOrWarn(e) : undefined;
+    }
+    /**
+     * Enables a bootstrap extension unless another enabled extension provides one of its
+     * single-provider extension points (see {@link leftDisabled}).
+     */
+    async enableOrWarn(e) {
+        const r = await this.ops.enableUnlessOccupied(e.name, null);
+        return r.enabled ? undefined : this.leftDisabled(e, r.note);
+    }
+    /**
+     * A bootstrap extension left disabled because another enabled extension holds a single-provider
+     * extension point it provides. An optional preinstall (a sandbox while the super admin runs
+     * another one) stays disabled with a warning, and the entry's result says so. A required entry
+     * fails (thrown, so the run is not recorded done, `capybara bootstrap` exits 1 and
+     * `capybara start` refuses to serve): the deployment cannot run without it, and only the super
+     * admin can free the point, by disabling the other provider and running the bootstrap again.
+     */
+    leftDisabled(e, note) {
+        const block = note.singleProvider;
+        if (e.required) {
+            const other = block.enabled.name;
+            throw new ApiError(note.code, `Required plugin ${e.name} provides ${block.extensionPoint}, which ${other} already provides; disable ${other} and run the bootstrap again`, [block]);
+        }
+        this.log.warn(`bootstrap: the plugin is installed disabled; ${note.message}`, {
+            plugin: e.name,
+            required: e.required,
+        });
+        return note;
     }
     /** The permission snapshot of a stored package (source `bootstrap`), under the approve lock. */
     async approveStored(e, set, sha256) {
@@ -552,6 +643,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-hash.d.ts

@@ -0,0 +1,10 @@
+import type { core } from "zod";
+/**
+ * 插件部署配置（校验后）中非密钥部分的摘要：先把 schema 里所有 secret 叶子（`configFields` 可达路径，
+ * 加载时 `assertSecretsReachable` 已保证密钥都在这些路径上）换成固定占位值，再取 sha256(键排序 JSON) 前 16 位十六进制。
+ * 给需要「配置变了就失效」的缓存键用（如模型列表）。密钥不参与摘要：不加盐的短摘要写进 Redis 键名后，
+ * 低熵密钥可被离线猜测、泄露的密钥可被确认；代价是轮换密钥不会让缓存失效（缓存内容本来就不该依赖密钥）。
+ * 没有部署配置 schema 时无从得知哪些是密钥，摘要不按配置区分。同一份配置在各副本上得到同一摘要。
+ * 函数自己按 schema 遮蔽，调用方不必（也不能忘记）先打码。
+ */
+export declare function deploymentConfigHash(schema: core.$ZodType | undefined, config: unknown): string;

package/dist/extensions/config-hash.js

@@ -0,0 +1,38 @@
+import { createHash } from "node:crypto";
+import { configFields, getPath, setPath } from "../config/fields.js";
+/** 键排序后的 JSON（对象键顺序不影响结果）；undefined 字段与 JSON.stringify 一样省略。 */
+const canonicalJson = (v) => {
+    if (Array.isArray(v))
+        return `[${v.map((x) => (x === undefined ? "null" : canonicalJson(x))).join(",")}]`;
+    if (v !== null && typeof v === "object") {
+        const entries = Object.entries(v)
+            .filter(([, x]) => x !== undefined)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+        return `{${entries.map(([k, x]) => `${JSON.stringify(k)}:${canonicalJson(x)}`).join(",")}}`;
+    }
+    return JSON.stringify(v) ?? "null";
+};
+/** 遮蔽 secret 字段后参与摘要的固定占位值。 */
+const SECRET_PLACEHOLDER = "<secret>";
+/**
+ * 插件部署配置（校验后）中非密钥部分的摘要：先把 schema 里所有 secret 叶子（`configFields` 可达路径，
+ * 加载时 `assertSecretsReachable` 已保证密钥都在这些路径上）换成固定占位值，再取 sha256(键排序 JSON) 前 16 位十六进制。
+ * 给需要「配置变了就失效」的缓存键用（如模型列表）。密钥不参与摘要：不加盐的短摘要写进 Redis 键名后，
+ * 低熵密钥可被离线猜测、泄露的密钥可被确认；代价是轮换密钥不会让缓存失效（缓存内容本来就不该依赖密钥）。
+ * 没有部署配置 schema 时无从得知哪些是密钥，摘要不按配置区分。同一份配置在各副本上得到同一摘要。
+ * 函数自己按 schema 遮蔽，调用方不必（也不能忘记）先打码。
+ */
+export function deploymentConfigHash(schema, config) {
+    let redacted = null;
+    if (schema) {
+        redacted = structuredClone(config);
+        if (redacted !== null && typeof redacted === "object") {
+            for (const f of configFields(schema)) {
+                if (f.meta?.secret && getPath(redacted, f.path) !== undefined) {
+                    setPath(redacted, f.path, SECRET_PLACEHOLDER);
+                }
+            }
+        }
+    }
+    return createHash("sha256").update(canonicalJson(redacted)).digest("hex").slice(0, 16);
+}

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 }),
+        };
+    });
 }