@capybara-hq/kernel 0.1.0-rc.6 → 0.1.0-rc.7

package/dist/extensions/host.js

@@ -311,6 +311,11 @@ let ExtensionHost = class ExtensionHost {
      * 安装记录不在这里：每次 converge 都按 PG 期望状态重新判定。
      */
     pendingActivations = new Map();
+    /**
+     * The load parameters of each config-declared extension that loaded: when its deployment config
+     * is cleared and the rest is invalid it goes back to {@link pendingActivations} (pending config).
+     */
+    declaredActivations = new Map();
     /** 安装记录准备好的候选（按插件名；sha 变了就作废）。 */
     prepared = new Map();
     /** 闸门放行后导入过的安装记录真实清单（按插件名；部署配置 schema 用，含待配置而未加载的）。 */
@@ -1294,6 +1299,8 @@ let ExtensionHost = class ExtensionHost {
         }
         // 升级：替换加载参数（之后的依赖方连锁与 reload 用新版本），先登记新实例、再撤销旧实例
         this.specs.set(name, spec);
+        if (a.source !== "install")
+            this.declaredActivations.set(name, a);
         this.unloadedForDependency.delete(name);
         const old = this.registry.activate(inst);
         this.loggedFailures.delete(name);
@@ -1724,7 +1731,9 @@ let ExtensionHost = class ExtensionHost {
     /**
      * 部署配置保存后（`kernel.plugin-deployment-config`）本副本重读并校验（C10；与 unload / reload 串行）：
      * - 插件没在本副本生效 → `not_loaded`（配置声明的刷新后台的合法性判定；待配置的由 reconcile 加载）；
-     * - 不合法 → `invalid`：保持当前值，告警；
+     * - 不合法 → `invalid`：保持当前值，告警；但 PG 里已没有保存的配置（超级管理员清空了，`DELETE
+     *   /api/v1/admin/extensions/:name/config`）、剩下的来源（启动配置、默认值）又不够时 → `unloaded`：卸下实例、
+     *   记为待配置（pending / config），依赖方连锁；重新配好后由 reconcile 加载；
      * - 没变 → `unchanged`；只改了 hot 字段 → `hot`：就地替换，插件经 `ctx.config` 读到新值，不重新 setup；
      * - 改了非 hot 字段 → `reload`：用新配置重新加载实例（先新后旧，排空在途调用），依赖方连锁；
      *   重新加载失败旧实例保留（`reload_failed`，记 error）。
@@ -1763,6 +1772,10 @@ let ExtensionHost = class ExtensionHost {
             }
             const r = parseLoadGate(schema, raw);
             if (!r.success) {
+                if (await this.clearedInPg(plugin)) {
+                    await this.unloadForMissingConfig(inst, toIssues(r.error));
+                    return "unloaded";
+                }
                 this.log.warn("plugin deployment config changed but is invalid on this replica; keeping the current config", {
                     plugin,
                     detail: toIssues(r.error)
@@ -1812,6 +1825,95 @@ let ExtensionHost = class ExtensionHost {
             return "reload";
         });
     }
+    /** PG holds no deployment config for the plugin (it was cleared); a read error counts as no. */
+    async clearedInPg(plugin) {
+        try {
+            return !(await this.installs.hasStoredDeploymentConfig(plugin));
+        }
+        catch (err) {
+            this.log.warn("cannot read whether the plugin has a stored deployment config", {
+                plugin,
+                err,
+            });
+            return false;
+        }
+    }
+    /**
+     * Unloads an extension whose deployment config was cleared and is now missing or invalid (in
+     * the host's serial queue): drains it, records pending / config (a config-declared one goes back
+     * to {@link pendingActivations}; an install record is decided again on every converge) and
+     * cascades to its dependents. It loads again without a restart once it is configured.
+     */
+    async unloadForMissingConfig(inst, issues) {
+        const plugin = inst.name;
+        const drainMs = this.drainMs();
+        const gone = await this.doUnload(plugin, drainMs, null);
+        if (!gone)
+            return;
+        await this.markPendingConfig({ plugin, version: gone.version, sha256: gone.sha256, source: gone.source }, issues, "extension unloaded: its deployment config was cleared and what remains is missing or invalid (set it in the admin console or the startup config; it loads without a restart)");
+        await this.cascade(gone.manifest.provides, drainMs);
+    }
+    /**
+     * Records an extension that is not loaded as pending configuration: a config-declared one goes
+     * back to {@link pendingActivations} (a later save loads it); an install record is decided again
+     * on every converge.
+     */
+    async markPendingConfig(p, issues, message) {
+        const detail = issues.map((i) => `${i.path || "<root>"}: ${i.message}`).join("; ");
+        const declared = this.declaredActivations.get(p.plugin);
+        if (p.source !== "install") {
+            this.configValidity.set(p.plugin, false);
+            if (declared)
+                this.pendingActivations.set(p.plugin, { ...declared, fatal: false });
+        }
+        this.configWarned.set(p.plugin, detail);
+        this.log.warn(message, { plugin: p.plugin, source: p.source, detail });
+        await this.writeStatus({ ...p, state: "pending", reason: "config", detail });
+    }
+    /**
+     * Before an extension unloaded for a dependency comes back ({@link cascade}): re-reads its
+     * deployment config, which may have been saved or cleared while it was down (applyDeploymentConfig
+     * only records validity then), and refreshes its load parameters, so it never returns on a stale
+     * config or revoked secrets. Returns false when the config is now missing or invalid and PG holds
+     * none: the extension is left pending configuration instead. A read error, or an invalid config
+     * that is still stored, keeps the previous config (as for a loaded extension).
+     */
+    async refreshConfigForRestore(name, spec) {
+        const schema = spec.manifest.config?.deployment;
+        if (!schema)
+            return true;
+        let raw;
+        try {
+            raw = await this.rawConfigOf(name, schema);
+        }
+        catch (err) {
+            this.log.error("cannot read the stored deployment config of plugin; restoring it on its previous config", { plugin: name, err });
+            return true;
+        }
+        const r = parseLoadGate(schema, raw);
+        if (!r.success) {
+            if (!(await this.clearedInPg(name)))
+                return true;
+            await this.markPendingConfig({
+                plugin: name,
+                version: spec.manifest.version,
+                sha256: spec.sha256,
+                source: spec.source,
+            }, toIssues(r.error), "extension not restored after its dependency came back: its deployment config was cleared and what remains is missing or invalid (set it in the admin console or the startup config; it loads without a restart)");
+            return false;
+        }
+        if (spec.source !== "install")
+            this.configValidity.set(name, true);
+        if (changedPaths(schema, spec.config, r.data).length > 0) {
+            this.reportSecrets(schema, r.data);
+            this.specs.set(name, {
+                ...spec,
+                config: r.data,
+                configHash: deploymentConfigHash(schema, r.data),
+            });
+        }
+        return true;
+    }
     /** 本次未加载、等待批准权限的插件（含因 `requires` 只能由它们满足而未加载的插件），按依赖拓扑序。 */
     pending() {
         return structuredClone(this.pendingPlugins);
@@ -2089,6 +2191,10 @@ let ExtensionHost = class ExtensionHost {
                 const available = providedNow();
                 if (!(spec.manifest.requires ?? []).every((c) => available.has(c)))
                     continue;
+                if (!(await this.refreshConfigForRestore(name, spec))) {
+                    this.unloadedForDependency.delete(name);
+                    continue;
+                }
                 try {
                     await this.doReload(name, drainMs);
                     progress = true;

package/dist/extensions/installs.d.ts

@@ -107,6 +107,11 @@ export declare class ExtensionInstalls {
      * the fields of `schema` when it is given.
      */
     effectiveDeploymentConfig(plugin: string, fileValue: unknown, schema?: core.$ZodType): Promise<unknown>;
+    /**
+     * Whether PG holds a deployment config row for the extension (a super admin saved one and has
+     * not cleared it since; `DELETE /api/v1/admin/extensions/:name/config` removes it).
+     */
+    hasStoredDeploymentConfig(plugin: string): Promise<boolean>;
     /** Every install record's extension name (any desired state). */
     installedNames(): Promise<string[]>;
     /**

package/dist/extensions/installs.js

@@ -76,6 +76,18 @@ let ExtensionInstalls = class ExtensionInstalls {
         const fields = schema ? configFields(schema).map((f) => f.path) : undefined;
         return mergeDeploymentConfig(stored, fileValue, fields);
     }
+    /**
+     * Whether PG holds a deployment config row for the extension (a super admin saved one and has
+     * not cleared it since; `DELETE /api/v1/admin/extensions/:name/config` removes it).
+     */
+    async hasStoredDeploymentConfig(plugin) {
+        const row = await this.db
+            .selectFrom("extension_deployment_configs")
+            .select("plugin")
+            .where("plugin", "=", plugin)
+            .executeTakeFirst();
+        return row !== undefined;
+    }
     /** Every install record's extension name (any desired state). */
     async installedNames() {
         const rows = await this.db.selectFrom("extension_installs").select("name").execute();

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

@@ -11,7 +11,8 @@ import { type JsonSchema } from "./config-json-schema.js";
 import { EffectiveConfigs } from "./effective-config.js";
 import { ExtensionHost } from "./host.js";
 import { ExtensionInstalls } from "./installs.js";
-import { type PermissionGroup } from "./permission-view.js";
+import { type DeploymentExtensionStatus, type PermissionGroup } from "./permission-view.js";
+import { ExtensionAvailability, type ExtensionUnavailableReason } from "./unavailable.js";
 export { type ConfigIssue, toIssues };
 /** 组织视角下一个已加载插件的状态；`config` 永远不含密钥字段，密钥只回显「是否已设置」。 */
 export interface OrgExtensionView {
@@ -35,6 +36,16 @@ export interface OrgExtensionView {
      * 组织的启用开关保留不变（不能修改），其余字段为空。
      */
     available: boolean;
+    /**
+     * The extension's status on the deployment, as the admin console derives it
+     * (`deriveExtensionStatus`): `enabled` when it is loaded here; otherwise why not.
+     */
+    status: DeploymentExtensionStatus;
+    /**
+     * Only when unavailable: why it cannot be used (spec §14.5 item 4), e.g.
+     * `needs_deployment_config`. State only, never a config value or field name.
+     */
+    reason?: ExtensionUnavailableReason;
     /**
      * A required bootstrap plugin: enabled in every org (`enabled` is always true) and cannot be
      * disabled here (`extension.required`); its org config, when it has one, can still be set.
@@ -121,6 +132,8 @@ export declare class OrgExtensionConfigs {
     private readonly log;
     /** The effective deployment config of each org (spec A §6): read for `needsConfig`. */
     private readonly effective;
+    /** Why an installed extension is not loaded (`status` / `reason` of the unavailable ones). */
+    private readonly availability;
     /** Test seam only: a deterministic interleaving point after the config rows are read, before the secrets. */
     afterConfigRowRead: (() => Promise<void>) | undefined;
     constructor(kdb: KernelDb, txHost: TransactionHost, keyring: Keyring, host: ExtensionHost, 
@@ -133,7 +146,9 @@ export declare class OrgExtensionConfigs {
     /** Secret values handled (written or decrypted) are masked in the logs after the commit. */
     log: KernelLogger, 
     /** The effective deployment config of each org (spec A §6): read for `needsConfig`. */
-    effective: EffectiveConfigs);
+    effective: EffectiveConfigs, 
+    /** Why an installed extension is not loaded (`status` / `reason` of the unavailable ones). */
+    availability: ExtensionAvailability);
     /** The kernel-schema handle of the current transaction. */
     private get db();
     /** 把一份组织配置里的密钥值登记到日志打码（无密钥时无操作）；调用方须在事务提交后调用。 */

package/dist/extensions/org-config.js

@@ -29,8 +29,9 @@ import { enabledExtensionsQuery, requiredExtensions } from "./enabled.js";
 import { ExtensionHost } from "./host.js";
 import { ExtensionInstalls } from "./installs.js";
 import { fieldLevels } from "./org-levels.js";
-import { permissionGroups } from "./permission-view.js";
+import { permissionGroups, } from "./permission-view.js";
 import { itemLocked, pluginItemsOf } from "./plugin-items.js";
+import { ExtensionAvailability } from "./unavailable.js";
 export { toIssues };
 /** 内核自己的 secrets 命名空间（plugin-sdk 把 `kernel` 列为保留插件名，插件不会与之相撞）。 */
 const SECRETS_NAMESPACE = "kernel";
@@ -104,6 +105,7 @@ let OrgExtensionConfigs = class OrgExtensionConfigs {
     events;
     log;
     effective;
+    availability;
     /** Test seam only: a deterministic interleaving point after the config rows are read, before the secrets. */
     afterConfigRowRead;
     constructor(kdb, txHost, keyring, host, 
@@ -116,7 +118,9 @@ let OrgExtensionConfigs = class OrgExtensionConfigs {
     /** Secret values handled (written or decrypted) are masked in the logs after the commit. */
     log, 
     /** The effective deployment config of each org (spec A §6): read for `needsConfig`. */
-    effective) {
+    effective, 
+    /** Why an installed extension is not loaded (`status` / `reason` of the unavailable ones). */
+    availability) {
         this.kdb = kdb;
         this.txHost = txHost;
         this.keyring = keyring;
@@ -126,6 +130,7 @@ let OrgExtensionConfigs = class OrgExtensionConfigs {
         this.events = events;
         this.log = log;
         this.effective = effective;
+        this.availability = availability;
     }
     /** The kernel-schema handle of the current transaction. */
     get db() {
@@ -154,7 +159,16 @@ let OrgExtensionConfigs = class OrgExtensionConfigs {
             name: r.name,
             version: r.version,
         }));
-        return this.withLayers(orgId, await this.listSnapshot(orgId, installed));
+        const views = await this.listSnapshot(orgId, installed);
+        const why = await this.availability.unavailable(views.filter((v) => !v.available).map((v) => v.plugin));
+        for (const v of views) {
+            const u = why.get(v.plugin);
+            if (v.available || u === undefined || u.status === null)
+                continue;
+            v.status = u.status;
+            v.reason = u.reason;
+        }
+        return this.withLayers(orgId, views);
     }
     /**
      * Fills `overrideState` and the platform half of `needsConfig` (spec A §6) for the views of
@@ -219,6 +233,9 @@ let OrgExtensionConfigs = class OrgExtensionConfigs {
             permissions: [],
             orgConfigSchema: null,
             available: false,
+            // filled in by `list` from the replicas' reports
+            status: "converging",
+            reason: "loading",
             required: required.has(i.name),
             ...scopeFields(items.get(i.name), required.has(i.name)),
             overrideState: "none",
@@ -619,6 +636,7 @@ let OrgExtensionConfigs = class OrgExtensionConfigs {
             permissions: permissionGroups(this.permissionsOf(m.name)),
             orgConfigSchema: schema ? this.formSchema(m.name, m.version, schema) : null,
             available: true,
+            status: "enabled",
             required,
             ...scopeFields(items, required),
             overrideState: [...fieldLevels(m.config?.deployment).values()].includes("override")
@@ -682,7 +700,8 @@ OrgExtensionConfigs = __decorate([
     __param(5, Inject(ExtensionInstalls)),
     __param(6, Inject(KernelEvents)),
     __param(7, Inject(KERNEL_LOGGER)),
-    __param(8, Inject(EffectiveConfigs))
+    __param(8, Inject(EffectiveConfigs)),
+    __param(9, Inject(ExtensionAvailability))
 ], OrgExtensionConfigs);
 export { OrgExtensionConfigs };
 /**

package/dist/extensions/point-defaults.controller.d.ts

@@ -1,13 +1,8 @@
-import { z } from "zod";
+import type { z } from "zod";
 import { type Principal } from "../identity/principal.js";
 import { type OrgContext } from "../orgs/org.guard.js";
 import { ExtensionPointDefaults, type OrgPointDefaultView } from "./point-defaults.js";
-declare const PointParams: z.ZodObject<{
-    point: z.ZodString;
-}, z.core.$strip>;
-declare const DefaultBody: z.ZodObject<{
-    extension: z.ZodString;
-}, z.core.$strict>;
+import { ExtensionPointDefaultBody as DefaultBody, ExtensionPointParams as PointParams } from "./point-defaults.schemas.js";
 /**
  * The org default provider of `org-default` extension points (web tools spec §6):
  * - `GET /api/v1/orgs/:orgId/extension-points` (`org.extensions.manage`) → `{ points }`: each
@@ -31,4 +26,3 @@ export declare class ExtensionPointDefaultsController {
     }>;
     setDefault(principal: Principal, org: OrgContext, { point }: z.infer<typeof PointParams>, body: z.infer<typeof DefaultBody>): Promise<void>;
 }
-export {};

package/dist/extensions/point-defaults.controller.js

@@ -8,14 +8,12 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { Controller, Get, HttpCode, Inject, Put } from "@nestjs/common";
-import { z } from "zod";
 import { CurrentPrincipal, requireUser } from "../identity/principal.js";
 import { createZodDto } from "../infra/validation/create-zod-dto.js";
 import { ZBody, ZParam } from "../infra/validation/zod-params.js";
 import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
 import { ExtensionPointDefaults } from "./point-defaults.js";
-const PointParams = z.object({ point: z.string().min(1).max(100) });
-const DefaultBody = z.object({ extension: z.string().min(1).max(214) }).strict();
+import { ExtensionPointDefaultBody as DefaultBody, ExtensionPointParams as PointParams, } from "./point-defaults.schemas.js";
 class ExtensionPointParamsDto extends createZodDto(PointParams, "ExtensionPointParams") {
 }
 class ExtensionPointDefaultBodyDto extends createZodDto(DefaultBody, "ExtensionPointDefaultBody") {

package/dist/extensions/point-defaults.d.ts

@@ -62,7 +62,9 @@ export declare class ExtensionPointDefaults {
      * the point is an `org-default` one and the extension provides it (loaded here) and is enabled
      * in the org. Audited as `extension_point.default_set`.
      */
-    setDefault(orgId: string, point: string, extension: string, actorId: string): Promise<void>;
+    setDefault(orgId: string, point: string, extension: string, actorId: string, 
+    /** Merged into the audit detail (a write made through the Platform tool). */
+    auditDetail?: Record<string, unknown>): Promise<void>;
     /** The candidates of `point` in `orgId`, by extension name. */
     private candidates;
     private choose;

package/dist/extensions/point-defaults.js

@@ -100,7 +100,9 @@ let ExtensionPointDefaults = class ExtensionPointDefaults {
      * the point is an `org-default` one and the extension provides it (loaded here) and is enabled
      * in the org. Audited as `extension_point.default_set`.
      */
-    async setDefault(orgId, point, extension, actorId) {
+    async setDefault(orgId, point, extension, actorId, 
+    /** Merged into the audit detail (a write made through the Platform tool). */
+    auditDetail) {
         const db = this.kdb.db;
         if (!hasSelection(point)) {
             throw new ApiError("validation_failed", `${point} is not an extension point with an organization default`);
@@ -123,7 +125,7 @@ let ExtensionPointDefaults = class ExtensionPointDefaults {
             orgId,
             action: "extension_point.default_set",
             target: point,
-            detail: { point, extension },
+            detail: { point, extension, ...auditDetail },
         });
     }
     /** The candidates of `point` in `orgId`, by extension name. */

package/dist/extensions/point-defaults.schemas.d.ts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+import type { RouteSchemas } from "../platform/route-schemas.js";
+export declare const ExtensionPointParams: z.ZodObject<{
+    point: z.ZodString;
+}, z.core.$strip>;
+export declare const ExtensionPointDefaultBody: z.ZodObject<{
+    extension: z.ZodString;
+}, z.core.$strict>;
+export declare const EXTENSION_POINT_ROUTES: readonly RouteSchemas[];

package/dist/extensions/point-defaults.schemas.js

@@ -0,0 +1,14 @@
+import { z } from "zod";
+export const ExtensionPointParams = z.object({ point: z.string().min(1).max(100) });
+export const ExtensionPointDefaultBody = z
+    .object({ extension: z.string().min(1).max(214) })
+    .strict();
+export const EXTENSION_POINT_ROUTES = [
+    { route: "GET /api/v1/orgs/:orgId/extension-points" },
+    { route: "GET /api/v1/orgs/:orgId/extension-points/available" },
+    {
+        route: "PUT /api/v1/orgs/:orgId/extension-points/:point/default",
+        params: ExtensionPointParams,
+        body: ExtensionPointDefaultBody,
+    },
+];

package/dist/extensions/unavailable.d.ts

@@ -0,0 +1,49 @@
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { type DeploymentExtensionStatus } from "./permission-view.js";
+import { ExtensionRegistry } from "./registry.js";
+/**
+ * Why an extension cannot be used right now (Platform tool spec §14.2 problem 1, §14.5 item 4):
+ * - `not_deployed`: no install record on the platform (a catalog plugin whose extension was never
+ *   installed);
+ * - `needs_deployment_config`: installed, its deployment config is missing or invalid;
+ * - `pending_approval`: its permissions wait for the super admin's approval;
+ * - `pending_migration` / `loading`: the platform is still bringing it up;
+ * - `dependency`: an extension point it requires has no loaded provider;
+ * - `failed`: it failed to load (or its package cannot be read);
+ * - `deployment_disabled`: the super admin disabled it on the platform.
+ * State only: never a config value or field name.
+ */
+export type ExtensionUnavailableReason = "not_deployed" | "needs_deployment_config" | "pending_approval" | "pending_migration" | "loading" | "dependency" | "failed" | "deployment_disabled";
+/** The deployment status of an extension that is not loaded, and the reason it shows for it. */
+export interface ExtensionUnavailability {
+    /** Null when it has no install record (`not_deployed`). */
+    status: DeploymentExtensionStatus | null;
+    reason: ExtensionUnavailableReason;
+}
+/** The reason an org or the Platform tool shows for a deployment status of a not-loaded extension. */
+export declare function unavailableReason(status: DeploymentExtensionStatus): ExtensionUnavailableReason;
+/**
+ * The state of extensions that are not loaded on this replica, derived like the admin console's
+ * status ({@link deriveExtensionStatus}) from the install record and the replicas' recent reports,
+ * without reading packages: a pending approval and a pending config come from the replicas' rows
+ * (`pending` with reason `approval` / `config`). Reads PG on every call (no in-process state).
+ *
+ * Its inputs differ slightly from the admin view's (`ExtensionAdmin`): there `pendingApproval`
+ * compares the package's permission set with the snapshot and `configValid` checks the deployment
+ * config, while here both come from what the replicas last reported. They agree once a replica
+ * has tried the current package; until then this view says `loading` where the admin view may
+ * already say `pending_approval` or `pending_config`.
+ *
+ * Which extensions count as loaded is this replica's registry: replica-local and transient. During
+ * a rollout, or right after an enable or upgrade, one replica may answer `loading` while another
+ * has it loaded; the next call (or the next reconcile) converges.
+ */
+export declare class ExtensionAvailability {
+    private readonly kdb;
+    private readonly config;
+    private readonly registry;
+    constructor(kdb: KernelDb, config: KernelConfigService, registry: ExtensionRegistry);
+    /** For each of `names` not loaded on this replica: its status and reason (loaded ones absent). */
+    unavailable(names: readonly string[]): Promise<Map<string, ExtensionUnavailability>>;
+}

package/dist/extensions/unavailable.js

@@ -0,0 +1,113 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable } from "@nestjs/common";
+import { sql } from "kysely";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { STALE_RECONCILE_PERIODS } from "./lifecycle-topics.js";
+import { deriveExtensionStatus } from "./permission-view.js";
+import { ExtensionRegistry } from "./registry.js";
+/** The reason an org or the Platform tool shows for a deployment status of a not-loaded extension. */
+export function unavailableReason(status) {
+    switch (status) {
+        case "pending_config":
+            return "needs_deployment_config";
+        case "pending_approval":
+            return "pending_approval";
+        case "pending_migration":
+            return "pending_migration";
+        case "dependency":
+            return "dependency";
+        case "failed":
+        case "legacy_format":
+            return "failed";
+        case "disabled":
+            return "deployment_disabled";
+        // loaded on another replica, or not yet on this one
+        case "converging":
+        case "enabled":
+            return "loading";
+    }
+}
+/**
+ * The state of extensions that are not loaded on this replica, derived like the admin console's
+ * status ({@link deriveExtensionStatus}) from the install record and the replicas' recent reports,
+ * without reading packages: a pending approval and a pending config come from the replicas' rows
+ * (`pending` with reason `approval` / `config`). Reads PG on every call (no in-process state).
+ *
+ * Its inputs differ slightly from the admin view's (`ExtensionAdmin`): there `pendingApproval`
+ * compares the package's permission set with the snapshot and `configValid` checks the deployment
+ * config, while here both come from what the replicas last reported. They agree once a replica
+ * has tried the current package; until then this view says `loading` where the admin view may
+ * already say `pending_approval` or `pending_config`.
+ *
+ * Which extensions count as loaded is this replica's registry: replica-local and transient. During
+ * a rollout, or right after an enable or upgrade, one replica may answer `loading` while another
+ * has it loaded; the next call (or the next reconcile) converges.
+ */
+let ExtensionAvailability = class ExtensionAvailability {
+    kdb;
+    config;
+    registry;
+    constructor(kdb, config, registry) {
+        this.kdb = kdb;
+        this.config = config;
+        this.registry = registry;
+    }
+    /** For each of `names` not loaded on this replica: its status and reason (loaded ones absent). */
+    async unavailable(names) {
+        const loaded = new Set(this.registry.manifests().map((m) => m.name));
+        const wanted = [...new Set(names)].filter((n) => !loaded.has(n));
+        const out = new Map();
+        if (wanted.length === 0)
+            return out;
+        const db = this.kdb.db;
+        const staleSeconds = STALE_RECONCILE_PERIODS * this.config.get().extensionHost.reconcileIntervalSeconds;
+        const [installs, replicas] = await Promise.all([
+            db
+                .selectFrom("extension_installs")
+                .select(["name", "sha256", "desired_state", "migrated_sha"])
+                .where("name", "in", wanted)
+                .execute(),
+            db
+                .selectFrom("extension_replica_status")
+                .select(["plugin", "state", "reason", "sha256"])
+                .where("plugin", "in", wanted)
+                .where("heartbeat_at", ">", sql `now() - make_interval(secs => ${staleSeconds})`)
+                .execute(),
+        ]);
+        for (const name of wanted) {
+            const install = installs.find((i) => i.name === name);
+            if (install === undefined) {
+                out.set(name, { status: null, reason: "not_deployed" });
+                continue;
+            }
+            const rows = replicas.filter((r) => r.plugin === name);
+            const target = rows.filter((r) => r.sha256 === install.sha256);
+            const status = deriveExtensionStatus({
+                source: "install",
+                desired: { sha256: install.sha256, state: install.desired_state },
+                pendingApproval: target.some((r) => r.state === "pending" && r.reason === "approval"),
+                configValid: !target.some((r) => r.state === "pending" && r.reason === "config"),
+                migratedSha: install.migrated_sha,
+                replicas: rows,
+            });
+            out.set(name, { status, reason: unavailableReason(status) });
+        }
+        return out;
+    }
+};
+ExtensionAvailability = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(KernelConfigService)),
+    __param(2, Inject(ExtensionRegistry))
+], ExtensionAvailability);
+export { ExtensionAvailability };

package/dist/files/previewers.controller.js

@@ -14,11 +14,10 @@ import { createZodDto } from "../infra/validation/create-zod-dto.js";
 import { ZBody, ZParam, ZQuery } from "../infra/validation/zod-params.js";
 import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
 import { PreviewerRegistry } from "./previewers.js";
+import { FilePreviewersOrderBody } from "./previewers.schemas.js";
 const Id = z.string().min(1).max(100);
 const PreviewQuery = z.object({ locale: z.enum(["zh", "en"]).default("en") });
-const OrderBody = z.object({
-    items: z.array(z.object({ plugin: Id, id: Id, disabled: z.boolean().default(false) })).max(500),
-});
+const OrderBody = FilePreviewersOrderBody;
 /** The previewer named in a preview path (the other path parameters are read as they are). */
 const PreviewParams = z.object({ plugin: Id, previewerId: Id });
 class FilePreviewQueryDto extends createZodDto(PreviewQuery, "FilePreviewQuery") {

package/dist/files/previewers.d.ts

@@ -61,7 +61,7 @@ export declare class PreviewerRegistry {
     }[], actor?: {
         accountId?: string;
         tokenId?: string;
-    }): Promise<OrgPreviewerItem[]>;
+    }, auditDetail?: Record<string, unknown>): Promise<OrgPreviewerItem[]>;
     /** Replaces the org's rows of the previewers this replica knows, in one transaction. */
     private putIn;
     /** Previewers that take this file (viewer must read the conversation), in the org's order. */

package/dist/files/previewers.js

@@ -141,7 +141,7 @@ let PreviewerRegistry = class PreviewerRegistry {
      * extension that is disabled now (or not loaded here yet) keep their order and `disabled`.
      * Audited as `org.file_previewers.updated`.
      */
-    async put(orgId, items, actor = {}) {
+    async put(orgId, items, actor = {}, auditDetail) {
         const known = new Set((await this.ordered(orgId)).map((l) => `${l.plugin}/${l.previewer.id}`));
         const seen = new Set();
         for (const i of items) {
@@ -151,11 +151,11 @@ let PreviewerRegistry = class PreviewerRegistry {
             }
             seen.add(k);
         }
-        await this.putIn(orgId, items, known, actor);
+        await this.putIn(orgId, items, known, actor, auditDetail);
         return this.list(orgId);
     }
     /** Replaces the org's rows of the previewers this replica knows, in one transaction. */
-    async putIn(orgId, items, known, actor) {
+    async putIn(orgId, items, known, actor, auditDetail) {
         if (known.size > 0) {
             await this.d.db
                 .deleteFrom("file_previewers")
@@ -180,7 +180,7 @@ let PreviewerRegistry = class PreviewerRegistry {
             ...(actor.tokenId !== undefined && { actorTokenId: actor.tokenId }),
             orgId,
             action: "org.file_previewers.updated",
-            detail: { items },
+            detail: { items, ...auditDetail },
         });
     }
     /** Previewers that take this file (viewer must read the conversation), in the org's order. */

package/dist/files/previewers.schemas.d.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+import type { RouteSchemas } from "../platform/route-schemas.js";
+export declare const FilePreviewersOrderBody: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        plugin: z.ZodString;
+        id: z.ZodString;
+        disabled: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const FILE_PREVIEWER_ROUTES: readonly RouteSchemas[];

package/dist/files/previewers.schemas.js

@@ -0,0 +1,9 @@
+import { z } from "zod";
+const Id = z.string().min(1).max(100);
+export const FilePreviewersOrderBody = z.object({
+    items: z.array(z.object({ plugin: Id, id: Id, disabled: z.boolean().default(false) })).max(500),
+});
+export const FILE_PREVIEWER_ROUTES = [
+    { route: "GET /api/v1/orgs/:orgId/file-previewers" },
+    { route: "PUT /api/v1/orgs/:orgId/file-previewers", body: FilePreviewersOrderBody },
+];