@capybara-hq/kernel 0.0.0-stage → 0.1.0-rc.0

package/dist/extensions/admin-view.js

@@ -0,0 +1,327 @@
+import { SDK_VERSION } from "@capybara-hq/plugin-sdk";
+import { sql } from "kysely";
+import { ApiError } from "../errors.js";
+import { lockEnterpriseAdminsAndAuthorize } from "../identity/enterprise-admin.js";
+import { ExtensionApprovals, snapshotCovers, writeSnapshot, } from "./approvals.js";
+import { PLUGINS_CHANGED_TOPIC, STALE_RECONCILE_PERIODS } from "./lifecycle.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";
+export { PLUGINS_CHANGED_TOPIC };
+/** 内容寻址的包 → 权限集合（包不可变，缓存安全；只作缓存，不是跨副本状态）。 */
+const PACKAGE_SET_CACHE_MAX = 256;
+/** 空权限集合（包读不到的降级项）。 */
+const EMPTY_SET = buildPermissionSet({
+    provides: [],
+    config: { deployment: [], org: [] },
+    tables: [],
+});
+/**
+ * The package cannot be read -> `extension.package_unavailable`, or is in the pre-0.1.0 format ->
+ * `extension.legacy_format` (details and approval cannot be based on an unreadable package).
+ */
+function assertReadable(s) {
+    if (s.legacy)
+        throw new ApiError("extension.legacy_format", s.broken);
+    if (s.broken !== undefined) {
+        throw new ApiError("extension.package_unavailable", `The package of extension ${s.name} cannot be read: ${s.broken}`);
+    }
+}
+/**
+ * 部署级插件后台（企业管理员）：列表 / 详情与网页批准权限（D8）。无状态，多副本共用；
+ * 状态由 PG（安装记录、快照、各副本状态行）与本副本宿主（配置声明插件的清单）推出。
+ */
+export class ExtensionAdmin {
+    d;
+    packageSets = new Map();
+    constructor(d) {
+        this.d = d;
+    }
+    /** 全部插件（配置声明 → 安装记录，各自按名字）。 */
+    async list() {
+        const subjects = await this.subjects();
+        return this.views(subjects);
+    }
+    /**
+     * A single extension; unknown -> `extension.not_found`; package unreadable ->
+     * `extension.package_unavailable`. With `allowUnreadable` an unreadable package returns the same
+     * degraded item as {@link list} (status failed, with `error`): used after a write has committed, so
+     * an operation that took effect is not reported as failed. A package in the pre-0.1.0 format is
+     * a state, not an error: it always returns the item with status `legacy_format` (so the admin can
+     * see it and uninstall it).
+     */
+    async get(name, opts = {}) {
+        const s = (await this.subjects(name))[0];
+        if (!s)
+            throw new ApiError("extension.not_found", `Extension ${name} is not known to this deployment`);
+        if (!opts.allowUnreadable && !s.legacy)
+            assertReadable(s);
+        return (await this.views([s]))[0];
+    }
+    /**
+     * Web approval: re-checks the enterprise 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
+     * the bus, the periodic job catches lost messages). Returns the view after approval.
+     * - Unknown -> `extension.not_found`;
+     * - the install record's `sha256` differs from the current one, or `reviewHash` differs from the one
+     *   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`.
+     */
+    async approve(actor, name, body, opts = {}) {
+        const s = (await this.subjects(name))[0];
+        if (!s)
+            throw new ApiError("extension.not_found", `Extension ${name} is not known to this deployment`);
+        assertReadable(s);
+        if (s.install === null && body.sha256 !== null) {
+            throw new ApiError("validation_failed", `Extension ${name} is declared in the startup config; approve it with sha256 null`);
+        }
+        const stale = () => new ApiError("extension.approval_stale", `The permissions of extension ${name} changed since they were reviewed; review them again`);
+        if (s.install !== null && body.sha256 !== s.install.sha256)
+            throw stale();
+        if (body.reviewHash !== reviewHash(s.set, s.warnings))
+            throw stale();
+        await this.d.db.transaction().execute(async (trx) => {
+            await lockEnterpriseAdminsAndAuthorize(trx, actor);
+            await sql `SELECT pg_advisory_xact_lock(hashtext(${`capybara.plugin-approve:${name}`}))`.execute(trx);
+            if (s.install !== null) {
+                // 审阅之后安装记录可能已换包（T14 升级）：锁行复核
+                const row = await trx
+                    .selectFrom("extension_installs")
+                    .select("sha256")
+                    .where("name", "=", name)
+                    .forUpdate()
+                    .executeTakeFirst();
+                if (row?.sha256 !== s.install.sha256)
+                    throw stale();
+            }
+            const snapRow = await trx
+                .selectFrom("extension_permission_snapshots")
+                .select(["version", "permissions"])
+                .where("plugin", "=", name)
+                .forUpdate()
+                .executeTakeFirst();
+            const snap = snapRow && {
+                version: snapRow.version,
+                permissions: snapRow.permissions,
+            };
+            if (snapshotCovers(snap, s.set)) {
+                throw new ApiError("extension.not_pending", `Extension ${name} ${s.version} has no new permissions awaiting approval`);
+            }
+            const { added, removed } = diffPermissions(snap?.permissions, s.set);
+            await writeSnapshot(trx, name, s.version, s.set, {
+                source: "web",
+                approvedBy: actor,
+                ...(opts.actorTokenId !== undefined && { actorTokenId: opts.actorTokenId }),
+                audit: { added, removed, sha256: s.install?.sha256 ?? null },
+            });
+        });
+        try {
+            await this.d.bus.publish(PLUGINS_CHANGED_TOPIC, { plugin: name });
+        }
+        catch (err) {
+            // 快照已写入；其他副本由周期 reconcile（T14）兜底
+            this.d.log.warn("cannot publish plugins.changed after approval", { plugin: name, err });
+        }
+        try {
+            await this.d.reconcile?.(`approved:${name}`);
+        }
+        catch (err) {
+            this.d.log.error("loading approved plugins on this replica failed", { plugin: name, err });
+        }
+        return this.get(name);
+    }
+    /** 配置声明 → 安装记录（与配置声明重名的安装记录不生效，不单列）。`only` 给出时只取这一个。 */
+    async subjects(only) {
+        const declared = this.d.host
+            .declaredPlugins()
+            .filter((p) => only === undefined || p.name === only);
+        const taken = new Set(this.d.host.declaredPlugins().map((p) => p.name));
+        const out = [...declared]
+            .sort((a, b) => a.name.localeCompare(b.name))
+            .map((p) => ({
+            name: p.name,
+            source: p.source,
+            version: p.version,
+            set: p.permissions,
+            install: null,
+            configurable: p.configurable,
+            configValid: p.configValid,
+            warnings: [],
+        }));
+        if (only !== undefined && out.length > 0)
+            return out;
+        const rows = (await this.d.installs.list()).filter((r) => !taken.has(r.name) && (only === undefined || r.name === only));
+        for (const r of rows) {
+            let info;
+            try {
+                info = await this.packageInfo(r.sha256);
+            }
+            catch (err) {
+                // One unreadable package (bytes missing / corrupt, over the current limit) does not break
+                // the list: it becomes a failed item; a pre-0.1.0 package becomes a legacy_format item.
+                const legacy = err instanceof ExtensionPackageError && err.code === "extension.legacy_format";
+                const detail = legacy
+                    ? err.message
+                    : `package ${r.name} ${r.version} (${r.sha256}) cannot be read: ${err instanceof Error ? err.message : String(err)}`;
+                // A pre-0.1.0 package is an expected state (repack needed), logged without a stack trace.
+                this.d.log.warn("plugin package unreadable for the admin view", {
+                    plugin: r.name,
+                    sha256: r.sha256,
+                    ...(legacy ? { reason: detail } : { err }),
+                });
+                out.push({
+                    name: r.name,
+                    source: "install",
+                    version: r.version,
+                    set: EMPTY_SET,
+                    install: r,
+                    configurable: false,
+                    configValid: null,
+                    broken: detail,
+                    ...(legacy && { legacy }),
+                    warnings: [],
+                });
+                continue;
+            }
+            const { set, configurable, warnings } = info;
+            out.push({
+                name: r.name,
+                source: "install",
+                version: r.version,
+                set,
+                install: r,
+                configurable,
+                configValid: null,
+                warnings,
+            });
+        }
+        return out;
+    }
+    /**
+     * 包的权限集合（静态清单 + 迁移 SQL，与上传时的审阅相同）、迁移审阅警告与是否有部署级配置字段；按 sha256 缓存。
+     */
+    async packageInfo(sha256) {
+        let cached = this.packageSets.get(sha256);
+        if (!cached) {
+            const pkg = await readExtensionPackage(await this.d.blobs.get(sha256), {
+                maxBytes: this.d.config().packages.maxBytes,
+                hostSdkVersion: SDK_VERSION,
+            });
+            cached = {
+                set: permissionSetOfPackage(pkg),
+                warnings: migrationWarnings(pkg.migrationSql, pkg.section.manifest.name),
+            };
+            if (this.packageSets.size >= PACKAGE_SET_CACHE_MAX)
+                this.packageSets.clear();
+            this.packageSets.set(sha256, cached);
+        }
+        return { ...cached, configurable: cached.set.config.deployment.length > 0 };
+    }
+    async views(subjects) {
+        if (subjects.length === 0)
+            return [];
+        const names = subjects.map((s) => s.name);
+        const snapshots = await new ExtensionApprovals(this.d.db).all();
+        const staleSeconds = STALE_RECONCILE_PERIODS * this.d.config().extensionHost.reconcileIntervalSeconds;
+        const rows = await this.d.db
+            .selectFrom("extension_replica_status")
+            .selectAll()
+            .where("plugin", "in", names)
+            .where("heartbeat_at", ">", sql `now() - make_interval(secs => ${staleSeconds})`)
+            .orderBy("replica_id")
+            .execute();
+        return subjects.map((s) => {
+            const replicas = rows.filter((r) => r.plugin === s.name);
+            const snap = snapshots.get(s.name);
+            const { added, removed } = diffPermissions(snap?.permissions, s.set);
+            const target = s.install?.sha256 ?? null;
+            const configValid = s.configValid ??
+                !replicas.some((r) => r.state === "pending" && r.reason === "config" && r.sha256 === target);
+            const install = s.install;
+            if (s.broken !== undefined) {
+                return {
+                    name: s.name,
+                    version: s.version,
+                    source: s.source,
+                    sha256: target,
+                    status: s.legacy ? "legacy_format" : "failed",
+                    desired: install && {
+                        version: install.version,
+                        sha256: install.sha256,
+                        state: install.desiredState,
+                    },
+                    replicas: replicas.map(replicaView),
+                    permissions: [],
+                    added: [],
+                    addedItems: [],
+                    removed: [],
+                    reviewHash: reviewHash(s.set),
+                    sensitive: false,
+                    warnings: [],
+                    snapshot: snapshotView(snap),
+                    configurable: false,
+                    configValid,
+                    removable: install?.required !== true,
+                    required: install?.required === true,
+                    installSource: install?.source ?? null,
+                    error: s.broken,
+                };
+            }
+            const permissions = permissionGroups(s.set);
+            return {
+                name: s.name,
+                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 })),
+                }),
+                desired: install && {
+                    version: install.version,
+                    sha256: install.sha256,
+                    state: install.desiredState,
+                },
+                replicas: replicas.map(replicaView),
+                permissions,
+                added,
+                addedItems: permissionKeyItems(added),
+                removed,
+                reviewHash: reviewHash(s.set, s.warnings),
+                sensitive: permissions.some((g) => g.sensitive),
+                warnings: s.warnings,
+                snapshot: snapshotView(snap),
+                configurable: s.configurable,
+                configValid,
+                removable: s.source === "install" && install?.required !== true,
+                required: install?.required === true,
+                installSource: install?.source ?? null,
+            };
+        });
+    }
+}
+const replicaView = (r) => ({
+    replicaId: r.replica_id,
+    version: r.version,
+    state: r.state,
+    reason: r.reason,
+    detail: r.detail,
+    servingVersion: r.serving_version,
+    heartbeatAt: r.heartbeat_at.toISOString(),
+});
+const snapshotView = (snap) => snap
+    ? {
+        version: snap.version,
+        approvedAt: snap.approvedAt.toISOString(),
+        approvedBy: snap.approvedBy,
+        source: snap.source,
+    }
+    : null;

package/dist/extensions/approvals.d.ts

@@ -0,0 +1,119 @@
+import { type ExtensionManifest } from "@capybara-hq/plugin-sdk";
+import { type Transaction } from "kysely";
+import type { KernelDatabase, KernelDb } from "../db/kernel-schema.js";
+import { type PermissionSet } from "./permission-set.js";
+/** An approved permission snapshot (one row of `capybara.extension_permission_snapshots`). */
+export interface PermissionSnapshot {
+    plugin: string;
+    version: string;
+    permissions: PermissionSet;
+    approvedBy: string | null;
+    approvedAt: Date;
+    /** cli：`capybara extensions approve`；auto：`extensionPermissions.autoApprove`；web：后台网页批准（T13）；bootstrap: the bootstrap step (core vouched for the version). */
+    source: "cli" | "auto" | "web" | "bootstrap";
+}
+/**
+ * An extension pending approval and not loaded this time (one item of `ExtensionHost.pending()` /
+ * `capybara extensions review`).
+ * 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).
+ */
+export interface PendingExtension {
+    plugin: string;
+    version: string;
+    added: string[];
+    removed: string[];
+    reason: "new" | "added" | "dependency";
+    /**
+     * 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).
+     */
+    blockedBy?: {
+        extensionPoint: string;
+        providers: string[];
+    }[];
+}
+/** {@link planApprovals} 对单个插件的结论。 */
+export type ApprovalDecision = {
+    plugin: string;
+    action: "load";
+    /** 需要批准但 autoApprove 开启：调用方以 source auto 写快照。 */
+    autoApprove: boolean;
+    added: string[];
+    removed: string[];
+    /** 快照需要写入或更新（无快照、权限或版本变了）。 */
+    changed: boolean;
+} | {
+    plugin: string;
+    action: "pending";
+    pending: PendingExtension;
+};
+/**
+ * 按依赖拓扑序（`ordered`）比对快照，决定每个插件加载还是待批准：
+ * - 无快照或比快照多出任何需要批准的一项（{@link blockingKeys}：`ui.view:*` 除外）→ 待批准
+ *   （`autoApprove` 时改为加载，由调用方写快照）；只多出 `ui.view:*` 时照常加载，`changed` 为真，
+ *   调用方经 `refresh` 把它们补进快照；
+ * - 权限变少或不变 → 加载，`changed` 表示快照需要更新（权限或版本变了）；版本比快照旧时照常加载但不更新快照；
+ * - 某个 `requires` 能力的提供方全都不加载 → 同样不加载（reason dependency）；`optional` 不受影响；
+ * - 声明了 `permissions.storage` 而 `object-store@1` 没有提供方、或提供方全都不加载 → 同样不加载（reason dependency）。
+ */
+export declare function planApprovals(ordered: ExtensionManifest[], sets: Map<string, PermissionSet>, snapshots: Map<string, PermissionSnapshot>, opts?: {
+    autoApprove?: boolean;
+}): ApprovalDecision[];
+/**
+ * 给已决定加载的插件（生效的实例）补一份与当前权限集合相同的快照，
+ * 让 {@link planApprovals} 视其为「已批准、无变化」：不进待批准、不写快照，依赖它的插件照常判定。
+ */
+export declare function withPreApproved(snapshots: Map<string, PermissionSnapshot>, manifests: ExtensionManifest[], sets: Map<string, PermissionSet>): Map<string, PermissionSnapshot>;
+/** 快照是否已覆盖该权限集合（没有需要批准的新增；F-N：「待批准」只看这一条，与期望状态无关）。 */
+export declare function snapshotCovers(snap: Pick<PermissionSnapshot, "permissions"> | undefined, set: PermissionSet): boolean;
+/**
+ * Writes (adds or overwrites) a snapshot in the caller's transaction; with `audit`, the
+ * `extension.permissions_approved` audit is written in the same transaction (actor is `approvedBy`,
+ * empty for the CLI).
+ */
+export declare function writeSnapshot(trx: Transaction<KernelDatabase>, plugin: string, version: string, permissions: PermissionSet, opts: {
+    source: PermissionSnapshot["source"];
+    approvedBy?: string | null;
+    actorTokenId?: string;
+    /** `app`：经应用包导入一次批准时的应用（T25）。 */
+    audit?: {
+        added: string[];
+        removed: string[];
+        sha256?: string | null;
+        app?: {
+            name: string;
+            version: string;
+        };
+    };
+}): Promise<void>;
+/** 读写权限快照（直连 PG；内核启动与 CLI 共用）。 */
+export declare class ExtensionApprovals {
+    private readonly db;
+    constructor(db: KernelDb);
+    /** 全部快照，按插件名索引。 */
+    all(): Promise<Map<string, PermissionSnapshot>>;
+    /**
+     * Approves (adds or overwrites) a snapshot: writes the current permission set and version,
+     * approved_at is now. With `audit`, the `extension.permissions_approved` audit is written in the
+     * same transaction (actor is `approvedBy`, empty for the CLI).
+     */
+    approve(plugin: string, version: string, permissions: PermissionSet, opts: {
+        source: PermissionSnapshot["source"];
+        approvedBy?: string | null;
+        audit?: {
+            added: string[];
+            removed: string[];
+            sha256?: string | null;
+        };
+    }): Promise<void>;
+    /**
+     * 权限变少、不变或只多出 `ui.view:*`（不卡加载）时更新快照的权限集合与版本；批准人、批准时间与来源保持不变，
+     * 不写审计（与 autoApprove 一样，Ruling A4；调用方记日志）。
+     * 在事务内锁行后重新核对（多副本并发启动时以库里的当前快照为准）：快照不存在、`version` 比快照旧、
+     * 或当前集合相对快照有需要批准的新增时不更新。返回是否更新。
+     */
+    refresh(plugin: string, version: string, permissions: PermissionSet): Promise<boolean>;
+}

package/dist/extensions/approvals.js

@@ -0,0 +1,205 @@
+import { OBJECT_STORE_EXTENSION_POINT } from "@capybara-hq/plugin-sdk";
+import { sql } from "kysely";
+import semver from "semver";
+import { audit } from "../identity/audit.js";
+import { blockingKeys, diffPermissions, permissionKeys, } from "./permission-set.js";
+/**
+ * 按依赖拓扑序（`ordered`）比对快照，决定每个插件加载还是待批准：
+ * - 无快照或比快照多出任何需要批准的一项（{@link blockingKeys}：`ui.view:*` 除外）→ 待批准
+ *   （`autoApprove` 时改为加载，由调用方写快照）；只多出 `ui.view:*` 时照常加载，`changed` 为真，
+ *   调用方经 `refresh` 把它们补进快照；
+ * - 权限变少或不变 → 加载，`changed` 表示快照需要更新（权限或版本变了）；版本比快照旧时照常加载但不更新快照；
+ * - 某个 `requires` 能力的提供方全都不加载 → 同样不加载（reason dependency）；`optional` 不受影响；
+ * - 声明了 `permissions.storage` 而 `object-store@1` 没有提供方、或提供方全都不加载 → 同样不加载（reason dependency）。
+ */
+export function planApprovals(ordered, sets, snapshots, opts = {}) {
+    const skipped = new Set();
+    const out = [];
+    for (const m of ordered) {
+        const set = sets.get(m.name);
+        const snap = snapshots.get(m.name);
+        const { added, removed } = diffPermissions(snap?.permissions, set);
+        const needsApproval = !snap || blockingKeys(added).length > 0;
+        if (needsApproval && !opts.autoApprove) {
+            skipped.add(m.name);
+            out.push({
+                plugin: m.name,
+                action: "pending",
+                pending: {
+                    plugin: m.name,
+                    version: m.version,
+                    added,
+                    removed,
+                    reason: snap ? "added" : "new",
+                },
+            });
+            continue;
+        }
+        const blockedBy = [];
+        for (const cap of m.requires ?? []) {
+            const providers = ordered.filter((p) => p.provides.includes(cap)).map((p) => p.name);
+            if (providers.length > 0 && providers.every((p) => skipped.has(p))) {
+                blockedBy.push({ extensionPoint: cap, providers });
+            }
+        }
+        if (m.permissions?.storage) {
+            const providers = ordered
+                .filter((p) => p !== m && p.provides.includes(OBJECT_STORE_EXTENSION_POINT))
+                .map((p) => p.name);
+            if (providers.every((p) => skipped.has(p))) {
+                blockedBy.push({ extensionPoint: OBJECT_STORE_EXTENSION_POINT, providers });
+            }
+        }
+        if (blockedBy.length > 0) {
+            skipped.add(m.name);
+            out.push({
+                plugin: m.name,
+                action: "pending",
+                pending: {
+                    plugin: m.name,
+                    version: m.version,
+                    added,
+                    removed,
+                    reason: "dependency",
+                    blockedBy,
+                },
+            });
+            continue;
+        }
+        // 权限集合由清单规范化得到，键相同即集合相同（jsonb 会重排对象键，不能比 JSON 文本）
+        // 比快照版本旧（滚动升级中重启的旧副本、或有意回滚）：照常加载但不缩减快照，
+        // 否则旧副本会把新版本已批准的权限写没，之后的新副本又变成待批准
+        const changed = !snap ||
+            (!isOlder(m.version, snap.version) &&
+                (snap.version !== m.version ||
+                    permissionKeys(snap.permissions).join("\n") !== permissionKeys(set).join("\n")));
+        out.push({
+            plugin: m.name,
+            action: "load",
+            autoApprove: needsApproval,
+            added,
+            removed,
+            changed,
+        });
+    }
+    return out;
+}
+/**
+ * 给已决定加载的插件（生效的实例）补一份与当前权限集合相同的快照，
+ * 让 {@link planApprovals} 视其为「已批准、无变化」：不进待批准、不写快照，依赖它的插件照常判定。
+ */
+export function withPreApproved(snapshots, manifests, sets) {
+    const out = new Map(snapshots);
+    for (const m of manifests) {
+        out.set(m.name, {
+            plugin: m.name,
+            version: m.version,
+            permissions: sets.get(m.name),
+            approvedBy: null,
+            approvedAt: new Date(0),
+            source: "auto",
+        });
+    }
+    return out;
+}
+/** 快照是否已覆盖该权限集合（没有需要批准的新增；F-N：「待批准」只看这一条，与期望状态无关）。 */
+export function snapshotCovers(snap, set) {
+    return (snap !== undefined && blockingKeys(diffPermissions(snap.permissions, set).added).length === 0);
+}
+/**
+ * Writes (adds or overwrites) a snapshot in the caller's transaction; with `audit`, the
+ * `extension.permissions_approved` audit is written in the same transaction (actor is `approvedBy`,
+ * empty for the CLI).
+ */
+export async function writeSnapshot(trx, plugin, version, permissions, opts) {
+    const values = {
+        plugin,
+        version,
+        permissions: JSON.stringify(permissions),
+        approved_by: opts.approvedBy ?? null,
+        approved_at: sql `now()`,
+        source: opts.source,
+    };
+    await trx
+        .insertInto("extension_permission_snapshots")
+        .values(values)
+        .onConflict((oc) => oc.column("plugin").doUpdateSet({
+        version: values.version,
+        permissions: values.permissions,
+        approved_by: values.approved_by,
+        approved_at: values.approved_at,
+        source: values.source,
+    }))
+        .execute();
+    if (opts.audit) {
+        await audit(trx, {
+            ...(opts.approvedBy && { actorAccountId: opts.approvedBy }),
+            ...(opts.actorTokenId !== undefined && { actorTokenId: opts.actorTokenId }),
+            action: "extension.permissions_approved",
+            target: plugin,
+            detail: { plugin, version, source: opts.source, ...opts.audit },
+        });
+    }
+}
+/** `version` 是否比 `than` 旧（任一方不是合法 semver 时视为不旧）。 */
+const isOlder = (version, than) => semver.valid(version) !== null && semver.valid(than) !== null && semver.lt(version, than);
+/** 读写权限快照（直连 PG；内核启动与 CLI 共用）。 */
+export class ExtensionApprovals {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /** 全部快照，按插件名索引。 */
+    async all() {
+        const rows = await this.db.selectFrom("extension_permission_snapshots").selectAll().execute();
+        return new Map(rows.map((r) => [
+            r.plugin,
+            {
+                plugin: r.plugin,
+                version: r.version,
+                permissions: r.permissions,
+                approvedBy: r.approved_by,
+                approvedAt: r.approved_at,
+                source: r.source,
+            },
+        ]));
+    }
+    /**
+     * Approves (adds or overwrites) a snapshot: writes the current permission set and version,
+     * approved_at is now. With `audit`, the `extension.permissions_approved` audit is written in the
+     * same transaction (actor is `approvedBy`, empty for the CLI).
+     */
+    async approve(plugin, version, permissions, opts) {
+        await this.db
+            .transaction()
+            .execute((trx) => writeSnapshot(trx, plugin, version, permissions, opts));
+    }
+    /**
+     * 权限变少、不变或只多出 `ui.view:*`（不卡加载）时更新快照的权限集合与版本；批准人、批准时间与来源保持不变，
+     * 不写审计（与 autoApprove 一样，Ruling A4；调用方记日志）。
+     * 在事务内锁行后重新核对（多副本并发启动时以库里的当前快照为准）：快照不存在、`version` 比快照旧、
+     * 或当前集合相对快照有需要批准的新增时不更新。返回是否更新。
+     */
+    async refresh(plugin, version, permissions) {
+        return this.db.transaction().execute(async (trx) => {
+            const row = await trx
+                .selectFrom("extension_permission_snapshots")
+                .select(["version", "permissions"])
+                .where("plugin", "=", plugin)
+                .forUpdate()
+                .executeTakeFirst();
+            if (!row || isOlder(version, row.version))
+                return false;
+            const { added } = diffPermissions(row.permissions, permissions);
+            if (blockingKeys(added).length > 0) {
+                return false;
+            }
+            await trx
+                .updateTable("extension_permission_snapshots")
+                .set({ version, permissions: JSON.stringify(permissions) })
+                .where("plugin", "=", plugin)
+                .execute();
+            return true;
+        });
+    }
+}