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

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

@@ -1,15 +1,20 @@
-import { EnterpriseAdminLock } from "../identity/enterprise-admin.js";
+import { SuperAdminLock } from "../identity/super-admin.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
 import type { KernelLogger } from "../log.js";
 import { ExtensionApprovals } from "./approvals.js";
 import { ExtensionBlobs } from "./blobs.js";
+import { ExtensionDeploymentConfigService } from "./deployment-config.js";
+import { ExtensionDisplayNames } from "./display-name.js";
+import { EffectiveConfigs } from "./effective-config.js";
 import { ExtensionHost } from "./host.js";
 import { ExtensionInstalls } from "./installs.js";
 import { ExtensionLifecycle, PLUGINS_CHANGED_TOPIC } from "./lifecycle.js";
 import { PluginApproveLock } from "./locks.js";
 import { type AdminExtensionView } from "./permission-view.js";
+import { PluginIcons } from "./plugin-icons.js";
+import { SingleProviderGuard } from "./single-provider.js";
 export { PLUGINS_CHANGED_TOPIC };
 /** The web approval request body (`POST /api/v1/admin/extensions/:name/approve`). */
 export interface ApproveBody {
@@ -22,13 +27,13 @@ export interface PublishBus {
     publish(topic: string, payload: unknown): Promise<void>;
 }
 /**
- * 部署级插件后台（企业管理员）：列表 / 详情与网页批准权限（D8）。无状态，多副本共用；
+ * 部署级插件后台（超级管理员）：列表 / 详情与网页批准权限（D8）。无状态，多副本共用；
  * 状态由 PG（安装记录、快照、各副本状态行）与本副本宿主（配置声明插件的清单）推出。
  */
 export declare class ExtensionAdmin {
     private readonly kdb;
     readonly txHost: TransactionHost;
-    /** The enterprise admin lock (identity/enterprise-admin.ts): joins the transaction. */
+    /** The super admin lock (identity/super-admin.ts): joins the transaction. */
     private readonly adminLock;
     private readonly approveLock;
     private readonly blobs;
@@ -41,17 +46,38 @@ export declare class ExtensionAdmin {
     private readonly config;
     private readonly bus;
     private readonly log;
+    private readonly displayNames;
+    /** Which required overridable fields the platform left empty (spec A §5.4a). */
+    private readonly deploymentConfig;
+    /** How many orgs still need their own config for such an extension. */
+    private readonly effectiveConfigs;
+    /** Which enabled extension keeps a disabled one from being enabled (`enableBlocked`). */
+    private readonly singleProvider;
+    /** The plugins' icons (admin catalog routes). */
+    private readonly icons;
     private readonly packageSets;
     constructor(kdb: KernelDb, txHost: TransactionHost, 
-    /** The enterprise admin lock (identity/enterprise-admin.ts): joins the transaction. */
-    adminLock: EnterpriseAdminLock, approveLock: PluginApproveLock, blobs: ExtensionBlobs, installs: ExtensionInstalls, approvals: ExtensionApprovals, 
+    /** The super admin lock (identity/super-admin.ts): joins the transaction. */
+    adminLock: SuperAdminLock, approveLock: PluginApproveLock, blobs: ExtensionBlobs, installs: ExtensionInstalls, approvals: ExtensionApprovals, 
     /** 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, 
+    /** Which required overridable fields the platform left empty (spec A §5.4a). */
+    deploymentConfig: ExtensionDeploymentConfigService, 
+    /** How many orgs still need their own config for such an extension. */
+    effectiveConfigs: EffectiveConfigs, 
+    /** Which enabled extension keeps a disabled one from being enabled (`enableBlocked`). */
+    singleProvider: SingleProviderGuard, 
+    /** The plugins' icons (admin catalog routes). */
+    icons: PluginIcons);
     private get db();
-    /** 全部插件（配置声明 → 安装记录，各自按名字）。 */
-    list(): Promise<AdminExtensionView[]>;
+    /**
+     * Every extension (config-declared, then install records, each by name). With `names`, only
+     * those: no other package is read, so a caller that needs a few items (the catalog's pending
+     * check) neither pays for nor logs about the packages of unrelated extensions.
+     */
+    list(names?: ReadonlySet<string>): Promise<AdminExtensionView[]>;
     /**
      * A single extension; unknown -> `extension.not_found`; package unreadable ->
      * `extension.package_unavailable`. With `allowUnreadable` an unreadable package returns the same
@@ -64,7 +90,12 @@ export declare class ExtensionAdmin {
         allowUnreadable?: boolean;
     }): Promise<AdminExtensionView>;
     /**
-     * Web approval: re-checks the enterprise admin under the lock, compares the reviewed package
+     * The review digest of a stored package (the `reviewHash` its extension would show once
+     * installed); null when the package cannot be read.
+     */
+    packageReviewHash(sha256: string): Promise<string | null>;
+    /**
+     * Web approval: re-checks the super admin under the lock, compares the reviewed package
      * (`sha256`) and permission digest (`reviewHash`), writes the snapshot (source web) and the
      * `extension.permissions_approved` audit; after the commit publishes `kernel.plugins.changed` (a
      * failure only warns) and waits for one reconcile on this replica (other replicas converge through
@@ -74,10 +105,12 @@ export declare class ExtensionAdmin {
      *   recomputed now -> `extension.approval_stale`; a config-declared extension's `sha256` must be
      *   null (otherwise `validation_failed`);
      * - the snapshot already covers the current permission set (nothing to approve, F-N) ->
-     *   `extension.not_pending`.
+     *   `extension.not_pending`, except with `confirmBootstrap` when the snapshot is the bootstrap
+     *   step's (the catalog's confirm re-writes it with source web).
      */
     approve(actor: string, name: string, body: ApproveBody, opts?: {
         actorTokenId?: string;
+        confirmBootstrap?: boolean;
     }): Promise<AdminExtensionView>;
     private writeApproval;
     /** 配置声明 → 安装记录（与配置声明重名的安装记录不生效，不单列）。`only` 给出时只取这一个。 */
@@ -86,5 +119,19 @@ export declare class ExtensionAdmin {
      * 包的权限集合（静态清单 + 迁移 SQL，与上传时的审阅相同）、迁移审阅警告与是否有部署级配置字段；按 sha256 缓存。
      */
     private packageInfo;
+    /**
+     * For each configurable, readable extension whose platform config leaves required overridable
+     * fields empty (spec A §5.4a): the number of orgs still needing their own config. Extensions
+     * without overridable fields cost no read.
+     */
+    private orgsNeedingConfig;
     private views;
+    /**
+     * The client build of each subject and its newest reports (at most {@link CLIENT_REPORTS_SHOWN}
+     * per extension, limited in SQL), in two queries over all subjects. The build is the one a live
+     * replica serves (`serving_sha256` of the fresh rows `live`, like the shell reads: the install's
+     * own package when it runs, else the newest still served, e.g. the old one beside an upgrade
+     * awaiting approval or failed); with none served, the install record package's build.
+     */
+    private clientsOf;
 }

package/dist/extensions/admin-view.js

@@ -11,7 +11,7 @@ import { SDK_VERSION } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable } from "@nestjs/common";
 import { sql } from "kysely";
 import { ApiError } from "../errors.js";
-import { EnterpriseAdminLock } from "../identity/enterprise-admin.js";
+import { SuperAdminLock } from "../identity/super-admin.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
@@ -19,6 +19,10 @@ 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 { ExtensionDeploymentConfigService } from "./deployment-config.js";
+import { ExtensionDisplayNames } from "./display-name.js";
+import { EffectiveConfigs } from "./effective-config.js";
+import { enabledExtensionsByOrg } from "./enabled.js";
 import { ExtensionHost } from "./host.js";
 import { ExtensionInstalls } from "./installs.js";
 import { ExtensionLifecycle, PLUGINS_CHANGED_TOPIC, STALE_RECONCILE_PERIODS } from "./lifecycle.js";
@@ -26,9 +30,15 @@ import { PluginApproveLock } from "./locks.js";
 import { ExtensionPackageError, permissionSetOfPackage, readExtensionPackage } from "./package.js";
 import { buildPermissionSet, diffPermissions } from "./permission-set.js";
 import { deriveExtensionStatus, migrationWarnings, permissionGroups, permissionKeyItems, reviewHash, } from "./permission-view.js";
+import { PluginIcons } from "./plugin-icons.js";
+import { pluginItemsOf } from "./plugin-items.js";
+import { parseProviderConflict } from "./resolve.js";
+import { SingleProviderGuard } from "./single-provider.js";
 export { PLUGINS_CHANGED_TOPIC };
 /** 内容寻址的包 → 权限集合（包不可变，缓存安全；只作缓存，不是跨副本状态）。 */
 const PACKAGE_SET_CACHE_MAX = 256;
+/** The most client reports an extension view lists (the newest). */
+const CLIENT_REPORTS_SHOWN = 50;
 /** 空权限集合（包读不到的降级项）。 */
 const EMPTY_SET = buildPermissionSet({
     provides: [],
@@ -47,7 +57,7 @@ function assertReadable(s) {
     }
 }
 /**
- * 部署级插件后台（企业管理员）：列表 / 详情与网页批准权限（D8）。无状态，多副本共用；
+ * 部署级插件后台（超级管理员）：列表 / 详情与网页批准权限（D8）。无状态，多副本共用；
  * 状态由 PG（安装记录、快照、各副本状态行）与本副本宿主（配置声明插件的清单）推出。
  */
 let ExtensionAdmin = class ExtensionAdmin {
@@ -63,14 +73,27 @@ let ExtensionAdmin = class ExtensionAdmin {
     config;
     bus;
     log;
+    displayNames;
+    deploymentConfig;
+    effectiveConfigs;
+    singleProvider;
+    icons;
     packageSets = new Map();
     constructor(kdb, txHost, 
-    /** The enterprise admin lock (identity/enterprise-admin.ts): joins the transaction. */
+    /** The super admin lock (identity/super-admin.ts): joins the transaction. */
     adminLock, approveLock, blobs, installs, approvals, 
     /** 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, 
+    /** Which required overridable fields the platform left empty (spec A §5.4a). */
+    deploymentConfig, 
+    /** How many orgs still need their own config for such an extension. */
+    effectiveConfigs, 
+    /** Which enabled extension keeps a disabled one from being enabled (`enableBlocked`). */
+    singleProvider, 
+    /** The plugins' icons (admin catalog routes). */
+    icons) {
         this.kdb = kdb;
         this.txHost = txHost;
         this.adminLock = adminLock;
@@ -83,13 +106,22 @@ let ExtensionAdmin = class ExtensionAdmin {
         this.config = config;
         this.bus = bus;
         this.log = log;
+        this.displayNames = displayNames;
+        this.deploymentConfig = deploymentConfig;
+        this.effectiveConfigs = effectiveConfigs;
+        this.singleProvider = singleProvider;
+        this.icons = icons;
     }
     get db() {
         return this.kdb.db;
     }
-    /** 全部插件（配置声明 → 安装记录，各自按名字）。 */
-    async list() {
-        const subjects = await this.subjects();
+    /**
+     * Every extension (config-declared, then install records, each by name). With `names`, only
+     * those: no other package is read, so a caller that needs a few items (the catalog's pending
+     * check) neither pays for nor logs about the packages of unrelated extensions.
+     */
+    async list(names) {
+        const subjects = await this.subjects(undefined, names);
         return this.views(subjects);
     }
     /**
@@ -109,7 +141,20 @@ let ExtensionAdmin = class ExtensionAdmin {
         return (await this.views([s]))[0];
     }
     /**
-     * Web approval: re-checks the enterprise admin under the lock, compares the reviewed package
+     * The review digest of a stored package (the `reviewHash` its extension would show once
+     * installed); null when the package cannot be read.
+     */
+    async packageReviewHash(sha256) {
+        try {
+            const { set, warnings } = await this.packageInfo(sha256);
+            return reviewHash(set, warnings);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Web approval: re-checks the super admin under the lock, compares the reviewed package
      * (`sha256`) and permission digest (`reviewHash`), writes the snapshot (source web) and the
      * `extension.permissions_approved` audit; after the commit publishes `kernel.plugins.changed` (a
      * failure only warns) and waits for one reconcile on this replica (other replicas converge through
@@ -119,7 +164,8 @@ let ExtensionAdmin = class ExtensionAdmin {
      *   recomputed now -> `extension.approval_stale`; a config-declared extension's `sha256` must be
      *   null (otherwise `validation_failed`);
      * - the snapshot already covers the current permission set (nothing to approve, F-N) ->
-     *   `extension.not_pending`.
+     *   `extension.not_pending`, except with `confirmBootstrap` when the snapshot is the bootstrap
+     *   step's (the catalog's confirm re-writes it with source web).
      */
     async approve(actor, name, body, opts = {}) {
         const s = (await this.subjects(name))[0];
@@ -134,7 +180,7 @@ let ExtensionAdmin = class ExtensionAdmin {
             throw stale();
         if (body.reviewHash !== reviewHash(s.set, s.warnings))
             throw stale();
-        await this.writeApproval(actor, name, s, opts.actorTokenId, stale);
+        await this.writeApproval(actor, name, s, opts.actorTokenId, stale, opts.confirmBootstrap === true);
         try {
             await this.bus.publish(PLUGINS_CHANGED_TOPIC, { plugin: name });
         }
@@ -150,7 +196,7 @@ let ExtensionAdmin = class ExtensionAdmin {
         }
         return this.get(name);
     }
-    async writeApproval(actor, name, s, actorTokenId, stale) {
+    async writeApproval(actor, name, s, actorTokenId, stale, confirmBootstrap) {
         const db = this.db;
         await this.adminLock.lockAndAuthorize(actor);
         await this.approveLock.lock(name);
@@ -167,7 +213,7 @@ let ExtensionAdmin = class ExtensionAdmin {
         }
         const snapRow = await db
             .selectFrom("extension_permission_snapshots")
-            .select(["version", "permissions"])
+            .select(["version", "permissions", "source"])
             .where("plugin", "=", name)
             .forUpdate()
             .executeTakeFirst();
@@ -175,7 +221,9 @@ let ExtensionAdmin = class ExtensionAdmin {
             version: snapRow.version,
             permissions: snapRow.permissions,
         };
-        if (snapshotCovers(snap, s.set)) {
+        // `confirmBootstrap` (the catalog's confirm): a snapshot the bootstrap step wrote was never
+        // confirmed by a person, so a covered one is still taken over
+        if (snapshotCovers(snap, s.set) && !(confirmBootstrap && snapRow?.source === "bootstrap")) {
             throw new ApiError("extension.not_pending", `Extension ${name} ${s.version} has no new permissions awaiting approval`);
         }
         const { added, removed } = diffPermissions(snap?.permissions, s.set);
@@ -187,10 +235,9 @@ let ExtensionAdmin = class ExtensionAdmin {
         });
     }
     /** 配置声明 → 安装记录（与配置声明重名的安装记录不生效，不单列）。`only` 给出时只取这一个。 */
-    async subjects(only) {
-        const declared = this.host
-            .declaredPlugins()
-            .filter((p) => only === undefined || p.name === only);
+    async subjects(only, names) {
+        const wanted = (name) => (only === undefined || name === only) && (names === undefined || names.has(name));
+        const declared = this.host.declaredPlugins().filter((p) => wanted(p.name));
         const taken = new Set(this.host.declaredPlugins().map((p) => p.name));
         const out = [...declared]
             .sort((a, b) => a.name.localeCompare(b.name))
@@ -206,7 +253,7 @@ let ExtensionAdmin = class ExtensionAdmin {
         }));
         if (only !== undefined && out.length > 0)
             return out;
-        const rows = (await this.installs.list()).filter((r) => !taken.has(r.name) && (only === undefined || r.name === only));
+        const rows = (await this.installs.list()).filter((r) => !taken.has(r.name) && wanted(r.name));
         for (const r of rows) {
             let info;
             try {
@@ -273,11 +320,41 @@ let ExtensionAdmin = class ExtensionAdmin {
         }
         return { ...cached, configurable: cached.set.config.deployment.length > 0 };
     }
+    /**
+     * For each configurable, readable extension whose platform config leaves required overridable
+     * fields empty (spec A §5.4a): the number of orgs still needing their own config. Extensions
+     * without overridable fields cost no read.
+     */
+    async orgsNeedingConfig(subjects) {
+        const out = new Map();
+        for (const s of subjects) {
+            if (!s.configurable || s.broken !== undefined)
+                continue;
+            try {
+                const missing = await this.deploymentConfig.orgMustConfigure(s.name);
+                if (missing.length > 0) {
+                    out.set(s.name, await this.effectiveConfigs.countNeedingConfig(s.name));
+                }
+            }
+            catch (err) {
+                // the list never fails for one extension's config; the field is then left out
+                this.log.warn("cannot tell whether orgs must configure the extension", {
+                    plugin: s.name,
+                    err,
+                });
+            }
+        }
+        return out;
+    }
     async views(subjects) {
         if (subjects.length === 0)
             return [];
         const names = subjects.map((s) => s.name);
         const snapshots = await this.approvals.all();
+        const [displayNames, icons] = await Promise.all([
+            this.displayNames.many(names),
+            this.icons.many(names, { kind: "admin" }),
+        ]);
         const staleSeconds = STALE_RECONCILE_PERIODS * this.config.get().extensionHost.reconcileIntervalSeconds;
         const rows = await this.db
             .selectFrom("extension_replica_status")
@@ -286,7 +363,52 @@ let ExtensionAdmin = class ExtensionAdmin {
             .where("heartbeat_at", ">", sql `now() - make_interval(secs => ${staleSeconds})`)
             .orderBy("replica_id")
             .execute();
+        const items = await pluginItemsOf(this.db, names);
+        // The other providers named by a `conflict` row, for their display names.
+        const conflicts = new Map(rows.flatMap((r) => {
+            const c = r.state === "pending" && r.reason === "conflict" && parseProviderConflict(r.detail);
+            return c ? [[r.plugin, c]] : [];
+        }));
+        const otherNames = [
+            ...new Set([...conflicts].flatMap(([n, c]) => c.providers.filter((p) => p !== n))),
+        ];
+        const otherDisplay = otherNames.length > 0 ? await this.displayNames.many(otherNames) : null;
+        const needing = await this.orgsNeedingConfig(subjects);
+        // A disabled install whose single-provider point another enabled extension provides: enabling
+        // it would be refused, so the view says which one to disable first.
+        const blocked = new Map();
+        for (const s of subjects) {
+            if (s.install?.desiredState !== "disabled" || s.broken !== undefined)
+                continue;
+            const block = await this.singleProvider.occupant(s.name, s.set.provides);
+            if (block)
+                blocked.set(s.name, block);
+        }
+        const counts = new Map((await this.db
+            .selectFrom(enabledExtensionsByOrg(this.db).as("en"))
+            .innerJoin("orgs", "orgs.id", "en.org_id")
+            .select(["en.plugin", (eb) => eb.fn.countAll().as("n")])
+            .where("orgs.deleted_at", "is", null)
+            .where("en.plugin", "in", names)
+            .groupBy("en.plugin")
+            .execute()).map((r) => [r.plugin, Number(r.n)]));
+        const { clients, reports } = await this.clientsOf(subjects, rows);
         return subjects.map((s) => {
+            const of = items.get(s.name);
+            const clientFields = {
+                client: clients.get(s.name) ?? null,
+                clientReports: reports.get(s.name) ?? [],
+            };
+            const builtin = of?.some((i) => i.builtin) === true || s.install?.required === true;
+            const scopeInfo = {
+                scope: of?.[0]
+                    ? builtin || of.some((i) => i.scope === "all")
+                        ? "all"
+                        : of[0].scope
+                    : null,
+                enabledOrgs: counts.get(s.name) ?? 0,
+                builtin,
+            };
             const replicas = rows.filter((r) => r.plugin === s.name);
             const snap = snapshots.get(s.name);
             const { added, removed } = diffPermissions(snap?.permissions, s.set);
@@ -294,9 +416,13 @@ 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;
+            const icon = icons.get(s.name) ?? null;
             if (s.broken !== undefined) {
                 return {
                     name: s.name,
+                    displayName,
+                    icon,
                     version: s.version,
                     source: s.source,
                     sha256: target,
@@ -319,24 +445,42 @@ let ExtensionAdmin = class ExtensionAdmin {
                     configValid,
                     removable: install?.required !== true,
                     required: install?.required === true,
+                    ...scopeInfo,
                     installSource: install?.source ?? null,
+                    uiDropped: this.host.uiDropped(s.name),
+                    ...clientFields,
                     error: s.broken,
                 };
             }
             const permissions = permissionGroups(s.set);
+            const status = deriveExtensionStatus({
+                source: s.source,
+                desired: install && { sha256: install.sha256, state: install.desiredState },
+                pendingApproval: !snapshotCovers(snap, s.set),
+                configValid,
+                migratedSha: install?.migratedSha ?? null,
+                replicas: replicas.map((r) => ({ state: r.state, reason: r.reason, sha256: r.sha256 })),
+            });
+            const conflict = status === "conflict" ? conflicts.get(s.name) : undefined;
+            const enableBlocked = blocked.get(s.name);
             return {
                 name: s.name,
+                displayName,
+                icon,
                 version: s.version,
                 source: s.source,
                 sha256: target,
-                status: deriveExtensionStatus({
-                    source: s.source,
-                    desired: install && { sha256: install.sha256, state: install.desiredState },
-                    pendingApproval: !snapshotCovers(snap, s.set),
-                    configValid,
-                    migratedSha: install?.migratedSha ?? null,
-                    replicas: replicas.map((r) => ({ state: r.state, reason: r.reason, sha256: r.sha256 })),
+                status,
+                ...(conflict && {
+                    conflict: {
+                        extensionPoint: conflict.extensionPoint,
+                        providers: conflict.providers
+                            .filter((p) => p !== s.name)
+                            .map((p) => ({ name: p, displayName: otherDisplay?.get(p) ?? null })),
+                        ...(conflict.unprovided && { unprovided: true }),
+                    },
                 }),
+                ...(enableBlocked && { enableBlocked }),
                 desired: install && {
                     version: install.version,
                     sha256: install.sha256,
@@ -353,12 +497,85 @@ let ExtensionAdmin = class ExtensionAdmin {
                 snapshot: snapshotView(snap),
                 configurable: s.configurable,
                 configValid,
+                ...(needing.has(s.name) && { orgsNeedingConfig: needing.get(s.name) }),
                 removable: s.source === "install" && install?.required !== true,
                 required: install?.required === true,
+                ...scopeInfo,
                 installSource: install?.source ?? null,
+                uiDropped: this.host.uiDropped(s.name),
+                ...clientFields,
             };
         });
     }
+    /**
+     * The client build of each subject and its newest reports (at most {@link CLIENT_REPORTS_SHOWN}
+     * per extension, limited in SQL), in two queries over all subjects. The build is the one a live
+     * replica serves (`serving_sha256` of the fresh rows `live`, like the shell reads: the install's
+     * own package when it runs, else the newest still served, e.g. the old one beside an upgrade
+     * awaiting approval or failed); with none served, the install record package's build.
+     */
+    async clientsOf(subjects, live) {
+        const targets = subjects.flatMap((s) => {
+            if (s.install === undefined || s.install === null || s.broken !== undefined)
+                return [];
+            const serving = new Set(live.flatMap((r) => r.plugin === s.name && r.serving_sha256 !== null ? [r.serving_sha256] : []));
+            return [{ plugin: s.name, sha: s.install.sha256, serving }];
+        });
+        const clients = new Map();
+        const reports = new Map();
+        if (targets.length === 0)
+            return { clients, reports };
+        const shas = [...new Set(targets.flatMap((t) => [t.sha, ...t.serving]))];
+        const builds = await this.db
+            .selectFrom("extension_client_builds")
+            .select(["package_sha256", "plugin", "sizes", "api_version", "created_at"])
+            .where("package_sha256", "in", shas)
+            .orderBy("created_at", "desc")
+            .execute();
+        for (const t of targets) {
+            const mine = builds.filter((x) => x.plugin === t.plugin);
+            const b = (t.serving.has(t.sha) ? mine.find((x) => x.package_sha256 === t.sha) : undefined) ??
+                mine.find((x) => t.serving.has(x.package_sha256)) ??
+                (t.serving.size === 0 ? mine.find((x) => x.package_sha256 === t.sha) : undefined);
+            if (b === undefined)
+                continue;
+            clients.set(t.plugin, {
+                build: b.package_sha256,
+                files: Object.entries(b.sizes)
+                    .map(([path, bytes]) => ({ path, bytes }))
+                    .sort((x, y) => x.path.localeCompare(y.path)),
+                apiVersion: b.api_version,
+            });
+        }
+        const built = [...clients].map(([plugin, c]) => ({ plugin, build: c.build }));
+        if (built.length === 0)
+            return { clients, reports };
+        const ranked = this.db
+            .selectFrom("extension_client_reports")
+            .selectAll()
+            .select(sql `row_number() over (partition by plugin order by last_at desc)`.as("rank"))
+            .where((eb) => eb.or(built.map((c) => eb.and([eb("plugin", "=", c.plugin), eb("build", "=", c.build)]))));
+        const rows = await this.db
+            .selectFrom(ranked.as("r"))
+            .selectAll()
+            .where("r.rank", "<=", CLIENT_REPORTS_SHOWN)
+            .orderBy("r.last_at", "desc")
+            .execute();
+        for (const r of rows) {
+            const list = reports.get(r.plugin) ?? [];
+            list.push({
+                orgId: r.org_id,
+                contribution: r.contribution,
+                kind: r.kind,
+                count: r.count,
+                firstAt: r.first_at.toISOString(),
+                lastAt: r.last_at.toISOString(),
+                lastMessage: r.last_message,
+            });
+            reports.set(r.plugin, list);
+        }
+        return { clients, reports };
+    }
 };
 __decorate([
     Transactional()
@@ -367,7 +584,7 @@ ExtensionAdmin = __decorate([
     Injectable(),
     __param(0, Inject(KernelDb)),
     __param(1, Inject(TransactionHost)),
-    __param(2, Inject(EnterpriseAdminLock)),
+    __param(2, Inject(SuperAdminLock)),
     __param(3, Inject(PluginApproveLock)),
     __param(4, Inject(ExtensionBlobs)),
     __param(5, Inject(ExtensionInstalls)),
@@ -376,7 +593,12 @@ 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)),
+    __param(13, Inject(ExtensionDeploymentConfigService)),
+    __param(14, Inject(EffectiveConfigs)),
+    __param(15, Inject(SingleProviderGuard)),
+    __param(16, Inject(PluginIcons))
 ], ExtensionAdmin);
 export { ExtensionAdmin };
 const replicaView = (r) => ({

package/dist/extensions/approvals.d.ts

@@ -19,14 +19,15 @@ export interface PermissionSnapshot {
  * reason: new = no snapshot (first seen); added = more permissions than the snapshot;
  * dependency = needs no approval itself, but an extension point it `requires` is provided only by
  * extensions pending approval (or not loaded because of that); the same when it declares
- * `permissions.storage` and `object-store@1` has no provider that will load (providers may be empty).
+ * `permissions.storage` and `object-store@1` has no provider that will load (providers may be empty);
+ * conflict = see {@link PendingExtension.conflicts}.
  */
 export interface PendingExtension {
     plugin: string;
     version: string;
     added: string[];
     removed: string[];
-    reason: "new" | "added" | "dependency";
+    reason: "new" | "added" | "dependency" | "conflict";
     /**
      * When reason is dependency: the extension points blocking it and their providers (only providers
      * that are not loading; empty when there is no provider at all).
@@ -35,6 +36,15 @@ export interface PendingExtension {
         extensionPoint: string;
         providers: string[];
     }[];
+    /**
+     * When reason is conflict (an installed extension, not an approval matter): the single-provider
+     * extension points it provides that other extensions already provide, and those providers. It
+     * loads once they are disabled or uninstalled.
+     */
+    conflicts?: {
+        extensionPoint: string;
+        providers: string[];
+    }[];
 }
 /** {@link planApprovals} 对单个插件的结论。 */
 export type ApprovalDecision = {

package/dist/extensions/blobs.d.ts

@@ -1,3 +1,4 @@
+import { ClientBuilds } from "../client/client-builds.service.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";
@@ -10,6 +11,13 @@ import type { ExtensionPackage } from "./package.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 declare class ExtensionBlobIntegrityError extends Error {
@@ -31,6 +39,7 @@ export declare class ExtensionBlobs {
     /** Without an object-store extension (the CLI) packages go to PG. */
     private readonly storage;
     private readonly config;
+    private readonly 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
@@ -40,7 +49,7 @@ export declare class ExtensionBlobs {
     private readonly local;
     constructor(db: KernelDb, txHost: TransactionHost, 
     /** Without an object-store extension (the CLI) packages go to PG. */
-    storage: StorageService, config: KernelConfigService);
+    storage: StorageService, config: KernelConfigService, clientBuilds: ClientBuilds);
     /** `packages.maxBytes` (read at every call). */
     private maxBytes;
     /**
@@ -54,6 +63,10 @@ export declare class ExtensionBlobs {
      * (content-addressed, idempotent; replicas writing the same package concurrently is harmless).
      */
     put(p: ExtensionPackage, bytes: Uint8Array, src: ExtensionBlobSource): Promise<void>;
+    /** {@link put} after its checks; `client` for a package with client code (under its lock). */
+    private store;
+    /** The files under `dist/client/` of a package's bytes (sha256 already checked by the caller). */
+    private clientFiles;
     private record;
     /** 已有记录的包：按记录的存放位置检查字节在不在，不在就写回（调用方已校验 sha256）。 */
     private repair;