@capybara-hq/kernel 0.1.0-rc.14 → 0.1.0-rc.15

package/dist/client/client.schemas.d.ts

@@ -0,0 +1,55 @@
+import { type UiSlotId } from "@capybara-hq/plugin-sdk";
+import { z } from "zod";
+/** The DTO schemas and response shapes of the client extension routes (spec §9.2). */
+/** `GET /api/v1/admin/ui/client?plugin=`: at most that plugin's platform set. */
+export declare const AdminClientQuery: z.ZodObject<{
+    plugin: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** One file URL of a client build, with the integrity recorded when the package was stored. */
+export interface ClientFileRef {
+    url: string;
+    integrity: string;
+}
+/** One extension of a shell read: its build's files and the components the viewer may use. */
+export interface ClientExtensionItem {
+    plugin: string;
+    /** The package sha256: the build id in the file URLs. */
+    build: string;
+    entry: ClientFileRef | null;
+    /** Empty in the admin set (spec §9.6). */
+    styles: ClientFileRef[];
+    components: {
+        id: string;
+        slot: UiSlotId;
+    }[];
+}
+/** The shell read (spec §9.2). */
+export interface ClientExtensionsResponse {
+    /** False under the kill switch: `items` is then empty. */
+    enabled: boolean;
+    /** The host's `CLIENT_API_VERSION`, echoed for diagnostics. */
+    apiVersion: number;
+    items: ClientExtensionItem[];
+}
+/** The most characters of a report's `message` (spec §10.4): longer is refused, not truncated. */
+export declare const REPORT_MESSAGE_MAX = 500;
+/**
+ * `POST /api/v1/orgs/:orgId/ui/client/reports` and `POST /api/v1/admin/ui/client/reports` (spec
+ * §10.4): one crash or load report of client code, from the browser that ran it. `build` is the
+ * package sha256 the files were loaded from; `contribution` the component id (null: the whole
+ * extension, e.g. the entry failed to load), which must be a component of that build's manifest.
+ */
+export declare const ReportBody: z.ZodObject<{
+    plugin: z.ZodString;
+    build: z.ZodString;
+    contribution: z.ZodNullable<z.ZodString>;
+    kind: z.ZodEnum<{
+        api: "api";
+        budget: "budget";
+        event: "event";
+        load: "load";
+        render: "render";
+    }>;
+    message: z.ZodString;
+}, z.core.$strip>;
+export type ReportBodyInput = z.infer<typeof ReportBody>;

package/dist/client/client.schemas.js

@@ -0,0 +1,27 @@
+import { EXTENSION_NAME_RE } from "@capybara-hq/plugin-sdk";
+import { z } from "zod";
+/** The DTO schemas and response shapes of the client extension routes (spec §9.2). */
+/** `GET /api/v1/admin/ui/client?plugin=`: at most that plugin's platform set. */
+export const AdminClientQuery = z.object({
+    plugin: z.string().regex(EXTENSION_NAME_RE, "must be an extension name").optional(),
+});
+/** The most characters of a report's `message` (spec §10.4): longer is refused, not truncated. */
+export const REPORT_MESSAGE_MAX = 500;
+/** The UI contribution id grammar of the SDK (`ui[].id`): what a report's `contribution` names. */
+const COMPONENT_ID_RE = /^[a-z][a-z0-9-]{0,39}$/;
+/**
+ * `POST /api/v1/orgs/:orgId/ui/client/reports` and `POST /api/v1/admin/ui/client/reports` (spec
+ * §10.4): one crash or load report of client code, from the browser that ran it. `build` is the
+ * package sha256 the files were loaded from; `contribution` the component id (null: the whole
+ * extension, e.g. the entry failed to load), which must be a component of that build's manifest.
+ */
+export const ReportBody = z.object({
+    plugin: z.string().regex(EXTENSION_NAME_RE, "must be an extension name"),
+    build: z.string().regex(/^[0-9a-f]{64}$/, "must be a 64-character lowercase hex sha256"),
+    contribution: z
+        .string()
+        .regex(COMPONENT_ID_RE, "must be a component id of the build (or null)")
+        .nullable(),
+    kind: z.enum(["load", "render", "event", "api", "budget"]),
+    message: z.string().max(REPORT_MESSAGE_MAX),
+});

package/dist/ctx/create-ctx.d.ts

@@ -140,9 +140,10 @@ export declare class LiveConfig {
  * - `secrets` only with `permissions.secrets`, `storage` only with `permissions.storage`, `models`
  *   only with `permissions.models` (and only its `embedding` purposes, through `deps.models`); `http.route`
  *   only the method + path declared in `permissions.http`; `tools.register` only names declared in
- *   `permissions.tools`; `ui.view` / `ui.action` only ids declared in `permissions.ui.views` (during
- *   setup only); `setup.check` only ids declared in `permissions.setupChecks` (during setup only,
- *   `place` and `run` read once and frozen); `ui.invalidate` sends a refresh over the kernel bus (namespace `kernel`), across
+ *   `permissions.tools`; `ui.view` / `ui.action` only ids declared in `permissions.ui.views` or
+ *   `permissions.ui.components` (a component's server view; during setup only); `setup.check` only
+ *   ids declared in `permissions.setupChecks` (during setup only, `place` and `run` read once and
+ *   frozen); `ui.invalidate` sends a refresh over the kernel bus (namespace `kernel`), across
  *   replicas; `ui.verifyEmbedToken` checks an embed token the kernel signed: `claims.plugin` must be
  *   this extension, the extension still enabled in that org and the caller still an active member of
  *   the org (org not deleted); returns the current role;

package/dist/ctx/create-ctx.js

@@ -181,9 +181,10 @@ export class LiveConfig {
  * - `secrets` only with `permissions.secrets`, `storage` only with `permissions.storage`, `models`
  *   only with `permissions.models` (and only its `embedding` purposes, through `deps.models`); `http.route`
  *   only the method + path declared in `permissions.http`; `tools.register` only names declared in
- *   `permissions.tools`; `ui.view` / `ui.action` only ids declared in `permissions.ui.views` (during
- *   setup only); `setup.check` only ids declared in `permissions.setupChecks` (during setup only,
- *   `place` and `run` read once and frozen); `ui.invalidate` sends a refresh over the kernel bus (namespace `kernel`), across
+ *   `permissions.tools`; `ui.view` / `ui.action` only ids declared in `permissions.ui.views` or
+ *   `permissions.ui.components` (a component's server view; during setup only); `setup.check` only
+ *   ids declared in `permissions.setupChecks` (during setup only, `place` and `run` read once and
+ *   frozen); `ui.invalidate` sends a refresh over the kernel bus (namespace `kernel`), across
  *   replicas; `ui.verifyEmbedToken` checks an embed token the kernel signed: `claims.plugin` must be
  *   this extension, the extension still enabled in that org and the caller still an active member of
  *   the org (org not deleted); returns the current role;

package/dist/db/kernel-schema.d.ts

@@ -1103,6 +1103,12 @@ export interface ExtensionReplicaStatusTable {
     detail: string | null;
     /** The old version this replica still serves when this row's version did not load (see migration 0030). */
     serving_version: Generated<string | null>;
+    /**
+     * 0107: the package sha256 this replica actually serves for the plugin (the row's `sha256` when
+     * loaded, the older package still running when the row's version is pending or failed, null when
+     * none runs). Client code is delivered for the package a live replica serves.
+     */
+    serving_sha256: Generated<string | null>;
     http_replica_id: string | null;
     heartbeat_at: Ts;
 }
@@ -1234,6 +1240,42 @@ export interface KernelDatabase {
     org_notices: OrgNoticesTable;
     platform_notices: PlatformNoticesTable;
     plugin_scope_sync_failures: PluginScopeSyncFailuresTable;
+    extension_client_builds: ExtensionClientBuildsTable;
+    extension_client_reports: ExtensionClientReportsTable;
+}
+/**
+ * 0107: the client files of an extension package (client extensions spec §9.1), keyed by the
+ * package sha256 (the build id). Paths are the manifest keys (`./dist/client/...`); the files live
+ * in object storage under `deployment/<object_prefix>`.
+ */
+export interface ExtensionClientBuildsTable {
+    package_sha256: string;
+    plugin: string;
+    /** `./dist/client/client.mjs`, or null for CSS-only decoration. */
+    entry: string | null;
+    styles: ColumnType<string[], string[], string[]>;
+    assets: ColumnType<string[], string[], string[]>;
+    /** Manifest key -> `sha384-<base64>`, checked against the bytes when stored. */
+    integrity: Json<Record<string, string>>;
+    /** Manifest key -> size in bytes. */
+    sizes: Json<Record<string, number>>;
+    api_version: number;
+    /** Relative to `deployment/`: `platform/client/<plugin>/<sha256>/`. */
+    object_prefix: string;
+    created_at: Ts;
+}
+/** 0107: crash and load reports of client code (client extensions spec §10.4). */
+export interface ExtensionClientReportsTable {
+    plugin: string;
+    build: string;
+    /** Null for admin pages. */
+    org_id: string | null;
+    contribution: string | null;
+    kind: "load" | "render" | "event" | "api" | "budget";
+    count: Generated<number>;
+    first_at: Ts;
+    last_at: Ts;
+    last_message: string;
 }
 /** 0082: one run of the platform components migration job (`catalog/platform-migration.ts`). */
 export interface PlatformMigrationRunsTable {
@@ -1529,6 +1571,11 @@ export interface CatalogItemVersionsTable {
     applied_at: TsNullable;
     /** 0084 (ruling P3-52): when the super admin rejected this pending org version. */
     rejected_at: TsNullable;
+    /**
+     * 0107: the keys of `suggestedAppearance.replacements` in plugin.json order (jsonb does not keep
+     * key order); null without replacements.
+     */
+    appearance_order: ColumnType<string[] | null, string[] | null | undefined, string[] | null>;
 }
 /** 0035_catalogs.sql, renamed in 0042: marketplaces (official / custom). */
 export interface MarketplacesTable {

package/dist/errors.d.ts

@@ -133,6 +133,35 @@ export declare const ERROR_CODES: {
      * a removed theme's versions are still served.
      */
     readonly "theme.not_found": 404;
+    /**
+     * An `extension.client` section whose extension manifest lacks `permissions.client: true`
+     * (client extensions spec §5.4: client code is always declared and reviewed).
+     */
+    readonly "client.undeclared": 400;
+    /**
+     * A client file's sha384 is not the integrity its plugin.json records (spec §9.1); details
+     * `[{ file }]` (the manifest key).
+     */
+    readonly "client.integrity_mismatch": 400;
+    /**
+     * The client section or a client file fails the import checks (spec §4.1, §9.1: a listed file
+     * missing, a file not listed, a key that cannot be looked up exactly, a size limit, a stylesheet
+     * not wrapped in `@layer extensions` or with `@import` / an absolute `url()`); details
+     * `[{ file, reason }]`.
+     */
+    readonly "client.invalid": 400;
+    /**
+     * The client section's `apiVersion` is newer than the deployment's `CLIENT_API_VERSION` (spec
+     * §4.2): the web host could not run the bundle; details `[{ apiVersion, supported }]`.
+     */
+    readonly "client.api_unsupported": 400;
+    /**
+     * A client file URL (`/api/v1/client/<plugin>/<build>/<file>`, spec §9.3) the caller may not
+     * fetch: an unknown or old build, a file the build does not list (by its exact key), an extension
+     * not running or not approved, not enabled in any live org the caller belongs to, or stopped by
+     * the kill switch. One code for all, so nothing tells them apart.
+     */
+    readonly "client.not_found": 404;
     readonly "directory.not_configured": 409;
     readonly "catalog.item_disabled": 403;
     readonly "plugin.disabled": 409;

package/dist/errors.js

@@ -133,6 +133,35 @@ export const ERROR_CODES = {
      * a removed theme's versions are still served.
      */
     "theme.not_found": 404,
+    /**
+     * An `extension.client` section whose extension manifest lacks `permissions.client: true`
+     * (client extensions spec §5.4: client code is always declared and reviewed).
+     */
+    "client.undeclared": 400,
+    /**
+     * A client file's sha384 is not the integrity its plugin.json records (spec §9.1); details
+     * `[{ file }]` (the manifest key).
+     */
+    "client.integrity_mismatch": 400,
+    /**
+     * The client section or a client file fails the import checks (spec §4.1, §9.1: a listed file
+     * missing, a file not listed, a key that cannot be looked up exactly, a size limit, a stylesheet
+     * not wrapped in `@layer extensions` or with `@import` / an absolute `url()`); details
+     * `[{ file, reason }]`.
+     */
+    "client.invalid": 400,
+    /**
+     * The client section's `apiVersion` is newer than the deployment's `CLIENT_API_VERSION` (spec
+     * §4.2): the web host could not run the bundle; details `[{ apiVersion, supported }]`.
+     */
+    "client.api_unsupported": 400,
+    /**
+     * A client file URL (`/api/v1/client/<plugin>/<build>/<file>`, spec §9.3) the caller may not
+     * fetch: an unknown or old build, a file the build does not list (by its exact key), an extension
+     * not running or not approved, not enabled in any live org the caller belongs to, or stopped by
+     * the kill switch. One code for all, so nothing tells them apart.
+     */
+    "client.not_found": 404,
     "directory.not_configured": 409,
     "catalog.item_disabled": 403,
     "plugin.disabled": 409,

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

@@ -125,7 +125,9 @@ export declare class ExtensionAdminOps {
      * fix: clearing them would let org enablement bypass catalog policy, C22). The detail of the
      * `extension.installed` audit carries `catalogItemId`; when it already points at the same package
      * and only the source item changed, only that column changes, audit
-     * `extension.install_source_changed`.
+     * `extension.install_source_changed`. With `opts.liveItem` (an org upload's confirmation) a
+     * source item gone or removed when its row lock is granted -> 409 `catalog.item_removed`, before
+     * anything is written.
      * A version change of an enabled extension whose new version provides a single-provider
      * extension point the old one did not, while another extension holds it: the new version is
      * installed **disabled** (`enabled_at` cleared, audit `extension.disabled` with `singleProvider`)
@@ -135,6 +137,7 @@ export declare class ExtensionAdminOps {
      */
     install(name: string, sha256: string, actor: string | null, actorTokenId?: string, opts?: {
         catalogItemId?: string;
+        liveItem?: true;
         owner?: ExtensionOpsOwner;
     }): Promise<InstallView>;
     private writeInstall;

package/dist/extensions/admin-ops.js

@@ -112,7 +112,9 @@ let ExtensionAdminOps = class ExtensionAdminOps {
      * fix: clearing them would let org enablement bypass catalog policy, C22). The detail of the
      * `extension.installed` audit carries `catalogItemId`; when it already points at the same package
      * and only the source item changed, only that column changes, audit
-     * `extension.install_source_changed`.
+     * `extension.install_source_changed`. With `opts.liveItem` (an org upload's confirmation) a
+     * source item gone or removed when its row lock is granted -> 409 `catalog.item_removed`, before
+     * anything is written.
      * A version change of an enabled extension whose new version provides a single-provider
      * extension point the old one did not, while another extension holds it: the new version is
      * installed **disabled** (`enabled_at` cleared, audit `extension.disabled` with `singleProvider`)
@@ -159,6 +161,23 @@ let ExtensionAdminOps = class ExtensionAdminOps {
     async writeInstall(name, sha256, pkg, target, actor, actorTokenId, opts) {
         const db = this.db;
         await this.authorize(actor, opts.owner);
+        // The source item's row before the install lock (the global lock order: the item, then the
+        // install lock; ruling P3-50): the catalog source and install rows written below check it by
+        // foreign key (FOR KEY SHARE), and an org deletion or an item removal holds it FOR UPDATE
+        // while it waits for the install lock (CatalogService.removeIn). Taken after the install lock
+        // instead, the two deadlock (40P01).
+        if (opts.catalogItemId !== undefined) {
+            const item = await db
+                .selectFrom("catalog_items")
+                .select("deleted_at")
+                .where("id", "=", opts.catalogItemId)
+                .forKeyShare()
+                .executeTakeFirst();
+            // The lock waits out a removal holding the row; the row read then is the removed one
+            if (opts.liveItem && (item === undefined || item.deleted_at !== null)) {
+                throw new ApiError("catalog.item_removed", `${name} was removed while its confirmation was running; nothing of it stays installed`);
+            }
+        }
         const row = await this.lockRow(name);
         // 不经目录重装时保留原来的来源条目（不清空，C22）
         const catalogItemId = opts.catalogItemId ?? row?.catalog_item_id ?? null;
@@ -520,6 +539,8 @@ function fallbackView(name, known, err) {
         builtin: false,
         installSource: null,
         uiDropped: [],
+        client: null,
+        clientReports: [],
         error: `the change was saved, but its current status cannot be read: ${err instanceof Error ? err.message : String(err)}`,
     };
 }

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

@@ -126,4 +126,12 @@ export declare class ExtensionAdmin {
      */
     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

@@ -37,6 +37,8 @@ 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: [],
@@ -390,8 +392,13 @@ let ExtensionAdmin = class ExtensionAdmin {
             .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]
@@ -441,6 +448,7 @@ let ExtensionAdmin = class ExtensionAdmin {
                     ...scopeInfo,
                     installSource: install?.source ?? null,
                     uiDropped: this.host.uiDropped(s.name),
+                    ...clientFields,
                     error: s.broken,
                 };
             }
@@ -495,9 +503,79 @@ let ExtensionAdmin = class ExtensionAdmin {
                 ...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()

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;

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")
@@ -135,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) {
@@ -205,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/host.d.ts

@@ -26,7 +26,8 @@ import { type ExtensionSource, ReplicaStatusStore } from "./sources.js";
 export { deploymentConfigHash };
 /**
  * One item of {@link ExtensionHost.uiContributions}: a UI contribution from the manifest whose slot
- * resolved at load (dropped ones never appear), with its registered view / action (embeds have none).
+ * resolved at load (dropped ones never appear), with its registered view / action (a view's or a
+ * component's; embeds have none).
  */
 export interface LoadedUiContribution {
     plugin: string;
@@ -412,6 +413,10 @@ export declare class ExtensionHost {
     /**
      * 写本副本的加载状态；失败只记 warn（状态是给后台看的，不影响加载）。这一行的版本没加载成（failed / pending）
      * 而本副本仍有别的版本在跑时，记下那个版本（`servingVersion`，后台同时显示「新版失败、旧版仍在服务」）。
+     * `servingSha256` is the package this replica actually serves for the plugin (client code follows
+     * it, client extensions spec §9.3): the row's own package when loaded; for a failed / pending row
+     * the package of the instance still running here (an older one, or the row's own package when it
+     * stays loaded, e.g. beside a provider conflict), else null.
      */
     private writeStatus;
     /**