@capybara-hq/kernel 0.1.0-rc.0 → 0.1.0-rc.10

package/dist/extensions/org-config.js

@@ -1,25 +1,59 @@
+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 { EXTENSION_POINTS, parseExtensionPoint, } from "@capybara-hq/plugin-sdk";
-import { assertItemInstallable, assertPluginSourcesInstallable, disabledPluginItems, pluginItemDisabled, } from "../catalog/requests.service.js";
+import { Inject, Injectable } from "@nestjs/common";
+import { assertItemInstallable, assertPluginSourcesInstallable, disabledPluginItems, pluginItemDisabled, } from "../catalog/request-rules.js";
+import { visibleTo } from "../catalog/scope.js";
 import { changedPaths, configFields, getPath, secretValues } from "../config/fields.js";
 import { createSecrets } from "../ctx/secrets.js";
 import { ApiError } from "../errors.js";
 import { audit } from "../identity/audit.js";
-import { lockOrgAndAuthorize } from "../orgs/org-lock.js";
-import { configToJsonSchema } from "./config-json-schema.js";
+import { afterCommit } from "../infra/database/after-commit.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 { KernelEvents } from "../infra/events/kernel-events.js";
+import { KERNEL_LOGGER, KEYRING } from "../infra/tokens.js";
+import { OrgLock } from "../orgs/org-lock.js";
+import { toIssues } from "./config-issues.js";
+import { configMessages, safeConfigFormSchema } from "./config-json-schema.js";
+import { EffectiveConfigs } from "./effective-config.js";
 import { enabledExtensionsQuery, requiredExtensions } from "./enabled.js";
-import { permissionGroups } from "./permission-view.js";
+import { ExtensionHost } from "./host.js";
+import { ExtensionInstalls } from "./installs.js";
+import { fieldLevels } from "./org-levels.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";
 const secretKey = (plugin, path) => `plugin-config:${plugin}:${path}`;
-/** 清单不可变：每个组织级 schema 的 JSON Schema 转换结果按 schema 对象缓存（只读、无跨请求状态）。 */
-const jsonSchemaCache = new WeakMap();
-function orgJsonSchema(schema) {
-    let js = jsonSchemaCache.get(schema);
-    if (!js) {
-        js = configToJsonSchema(schema);
-        jsonSchemaCache.set(schema, js);
-    }
-    return structuredClone(js);
+/** The extension points an extension provides, from its permission list's `provides` group. */
+export function providesOf(view) {
+    return view.permissions.filter((g) => g.category === "provides").flatMap((g) => g.items);
+}
+/**
+ * The scope part of an org view: the extension's primary plugin and whether the org can switch it.
+ * With several source items, a builtin one locks the extension on (scope `all`); an `all` one does
+ * not (layering spec §4).
+ */
+function scopeFields(items, required) {
+    const primary = items?.[0];
+    if (!primary)
+        return { catalogItem: null, switchable: !required };
+    const locked = required || items.some(itemLocked);
+    return {
+        catalogItem: { itemId: primary.id, scope: locked ? "all" : primary.scope },
+        switchable: !locked,
+    };
 }
 const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 /** 按点路径设值，缺失的中间对象自动创建；中间节点不是对象时放弃（交给 schema 校验报错）。 */
@@ -48,37 +82,6 @@ function deleteDeep(obj, path) {
     if (isObj(node))
         delete node[segs[segs.length - 1]];
 }
-/** 由 issue 类型与结构字段生成说明；不用 zod 的 message（自定义消息可能拼入输入值）。 */
-function issueMessage(i) {
-    switch (i.code) {
-        case "invalid_type":
-            return `expected ${i.expected}`;
-        case "too_small":
-            return `too small (minimum ${String(i.minimum)})`;
-        case "too_big":
-            return `too big (maximum ${String(i.maximum)})`;
-        case "invalid_format":
-            return `invalid ${i.format}`;
-        case "not_multiple_of":
-            return `not a multiple of ${String(i.divisor)}`;
-        case "unrecognized_keys":
-            return "unrecognized keys";
-        case "invalid_union":
-            return "no union member matched";
-        case "invalid_key":
-            return "invalid key";
-        case "invalid_element":
-            return "invalid element";
-        default:
-            return "invalid value";
-    }
-}
-export function toIssues(error) {
-    return error.issues.map((i) => ({
-        path: i.path.map(String).join("."),
-        message: issueMessage(i),
-    }));
-}
 /** 插件组织级 schema 中标记 secret 的叶子点路径（对象路径之外的 secret 已在插件加载时拒绝）。 */
 function secretPaths(schema) {
     return configFields(schema)
@@ -92,69 +95,172 @@ function secretPaths(schema) {
  * written in the same transaction as the config row.
  * No in-process state: every call reads PG, safe with multiple replicas.
  */
-export class OrgExtensionConfigs {
-    db;
+let OrgExtensionConfigs = class OrgExtensionConfigs {
+    kdb;
+    txHost;
     keyring;
     host;
-    hooks;
-    constructor(db, keyring, host, hooks = {}) {
-        this.db = db;
+    orgLock;
+    installs;
+    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, 
+    /** The org row lock (orgs/org-lock.ts): joins the transaction. */
+    orgLock, 
+    /** Install records (any desired state): the ones not loaded are listed unavailable (T14). */
+    installs, 
+    /** `extension.org-disabled` after a disable commits (channel connections drop at once). */
+    events, 
+    /** 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, 
+    /** Why an installed extension is not loaded (`status` / `reason` of the unavailable ones). */
+    availability) {
+        this.kdb = kdb;
+        this.txHost = txHost;
         this.keyring = keyring;
         this.host = host;
-        this.hooks = hooks;
+        this.orgLock = orgLock;
+        this.installs = installs;
+        this.events = events;
+        this.log = log;
+        this.effective = effective;
+        this.availability = availability;
+    }
+    /** The kernel-schema handle of the current transaction. */
+    get db() {
+        return this.kdb.db;
     }
-    /** 把一份组织配置里的密钥值交给 onSecrets（无回调或无密钥时无操作）；调用方须在事务提交后调用。 */
+    /** 把一份组织配置里的密钥值登记到日志打码（无密钥时无操作）；调用方须在事务提交后调用。 */
     reportSecrets(found) {
-        if (!found || !this.hooks.onSecrets)
+        if (!found)
             return;
         const values = secretValues(found.schema, found.config);
         if (values.length > 0)
-            this.hooks.onSecrets(values);
+            this.log.addOrgSecrets(values);
     }
-    /** `REPEATABLE READ` 只读事务：配置行与密钥来自同一个快照，不会读到跨两次提交的混合状态。 */
-    snapshot(fn) {
-        return this.db
-            .transaction()
-            .setIsolationLevel("repeatable read")
-            .setAccessMode("read only")
-            .execute(fn);
+    /** After a write committed: a disabled extension's channel connections drop at once. */
+    async afterPut(orgId, plugin, enabled) {
+        if (!enabled)
+            await this.events.emit("extension.org-disabled", { orgId, plugin });
     }
     /**
-     * 列出所有已加载插件在该组织下的状态（按加载顺序）；无记录时 enabled=false、config=null。
-     * 之后是已安装但此刻没加载的插件（部署上停用等），`available: false`，按名字排序。
+     * The state of every loaded extension the org sees, in load order (no row: `enabled` false,
+     * `config` null), then the installed extensions not loaded right now (disabled on the deployment
+     * and the like) as `available: false`, sorted by name.
      */
     async list(orgId) {
-        const installed = (await this.hooks.installed?.()) ?? [];
-        return this.snapshot(async (t) => {
-            const rows = await t
-                .selectFrom("extension_org_configs")
-                .select(["plugin", "enabled", "config"])
-                .where("org_id", "=", orgId)
-                .execute();
-            await this.hooks.afterConfigRowRead?.();
-            const setKeys = await this.setSecretKeys(t, orgId);
-            // Required bootstrap plugins are listed enabled (no org config row needed, spec §7)
-            const required = await requiredExtensions(t);
-            const loaded = this.host.manifests();
-            const views = loaded.map((m) => this.view(m, rows.find((r) => r.plugin === m.name), setKeys, required.has(m.name)));
-            const names = new Set(loaded.map((m) => m.name));
-            const unavailable = installed
-                .filter((i) => !names.has(i.name))
-                .sort((a, b) => a.name.localeCompare(b.name))
-                .map((i) => ({
-                plugin: i.name,
-                version: i.version,
-                enabled: required.has(i.name) || (rows.find((r) => r.plugin === i.name)?.enabled ?? false),
-                configurable: false,
-                config: null,
-                secrets: [],
-                permissions: [],
-                orgConfigSchema: null,
-                available: false,
-                required: required.has(i.name),
-            }));
-            return [...views, ...unavailable];
-        });
+        const installed = (await this.installs.list()).map((r) => ({
+            name: r.name,
+            version: r.version,
+        }));
+        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
+     * extensions with overridable fields (the others always run with the platform's config, which
+     * loaded valid). Reads the org's copy rows once and the effective config of each such extension.
+     */
+    async withLayers(orgId, views) {
+        const layered = views.filter((v) => v.overrideState !== "none");
+        if (layered.length === 0)
+            return views;
+        const copies = new Set((await this.db
+            .selectFrom("extension_org_overrides")
+            .select("plugin")
+            .where("org_id", "=", orgId)
+            .where("plugin", "in", layered.map((v) => v.plugin))
+            .execute()).map((r) => r.plugin));
+        for (const v of layered) {
+            v.overrideState = copies.has(v.plugin) ? "copy" : "following";
+            if (!(await this.effective.get(orgId, v.plugin)).ok)
+                v.needsConfig = true;
+        }
+        return views;
+    }
+    /** `REPEATABLE READ` read-only: the config rows and the secrets come from one snapshot. */
+    async listSnapshot(orgId, installed) {
+        const t = this.db;
+        const rows = await t
+            .selectFrom("extension_org_configs")
+            .select(["plugin", "enabled", "config"])
+            .where("org_id", "=", orgId)
+            .execute();
+        await this.afterConfigRowRead?.();
+        const setKeys = await this.setSecretKeys(t, orgId);
+        // Required bootstrap plugins are listed enabled (no org config row needed, spec §7)
+        const required = await requiredExtensions(t);
+        const loaded = this.host.manifests();
+        const items = await pluginItemsOf(t, [
+            ...loaded.map((m) => m.name),
+            ...installed.map((i) => i.name),
+        ]);
+        // An extension whose plugin the org is not offered (a `named` plugin without it) is absent
+        const listed = new Set((await t
+            .selectFrom("catalog_item_scope_orgs")
+            .select("item_id")
+            .where("org_id", "=", orgId)
+            .execute()).map((r) => r.item_id));
+        const seen = (name) => required.has(name) || itemsVisible(items.get(name), listed);
+        const views = loaded
+            .filter((m) => seen(m.name))
+            .map((m) => this.view(m, rows.find((r) => r.plugin === m.name), setKeys, required.has(m.name), items.get(m.name)));
+        const names = new Set(loaded.map((m) => m.name));
+        const unavailable = installed
+            .filter((i) => !names.has(i.name) && seen(i.name))
+            .sort((a, b) => a.name.localeCompare(b.name))
+            .map((i) => ({
+            plugin: i.name,
+            version: i.version,
+            enabled: required.has(i.name) || (rows.find((r) => r.plugin === i.name)?.enabled ?? false),
+            configurable: false,
+            config: null,
+            secrets: [],
+            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",
+            needsConfig: false,
+        }));
+        return [...views, ...unavailable];
+    }
+    /**
+     * How an `enabled` write of this extension is handled: `direct` through {@link put} (a required
+     * bootstrap plugin keeps `extension.required`; an extension without a live item is config-declared;
+     * several live items keep the direct write, the strictest source rules applying), `locked` (a live
+     * item is builtin and the write switches off: `plugin.scope_locked`), or `item` (the single plugin
+     * whose org switch it is).
+     */
+    async switchPlan(plugin, enabled) {
+        const t = this.db;
+        if ((await requiredExtensions(t)).has(plugin))
+            return { kind: "direct" };
+        const items = (await pluginItemsOf(t, [plugin])).get(plugin);
+        if (!items)
+            return { kind: "direct" };
+        if (!enabled && items.some(itemLocked))
+            return { kind: "locked" };
+        const [only] = items;
+        return items.length === 1 && only ? { kind: "item", itemId: only.id } : { kind: "direct" };
     }
     /**
      * Writes enablement and / or config. The actor's role is re-read under the org row lock (needs
@@ -167,149 +273,172 @@ export class OrgExtensionConfigs {
      * - The merged full config (or, without `config`, the existing config when the result is enabled)
      *   does not satisfy the schema -> `extension.config_invalid`.
      */
-    async put(orgId, plugin, input, actorAccountId, actorTokenId, opts = {}) {
+    async put(orgId, plugin, input, 
+    /** null: the kernel itself (the plugin scope sync installing a plugin), no role check. */
+    actorAccountId, actorTokenId, opts = {}) {
         const manifest = this.manifest(plugin);
         const schema = manifest.config?.org;
         if (input.config !== undefined && !schema) {
             throw new ApiError("extension.no_org_config", `Extension ${plugin} has no organization config`);
         }
+        const view = await this.write(orgId, plugin, manifest, input, actorAccountId, actorTokenId, opts);
+        return (await this.withLayers(orgId, [view]))[0];
+    }
+    async write(orgId, plugin, manifest, input, actorAccountId, actorTokenId, opts) {
+        const schema = manifest.config?.org;
         let seen;
-        const view = await this.db.transaction().execute(async (t) => {
-            await lockOrgAndAuthorize(t, orgId, actorAccountId, "org.extensions.manage");
-            const row = await t
-                .selectFrom("extension_org_configs")
-                .select(["enabled", "config"])
-                .where("plugin", "=", plugin)
-                .where("org_id", "=", orgId)
-                .executeTakeFirst();
-            const required = (await requiredExtensions(t)).has(plugin);
-            if (required && input.enabled === false)
-                throw requiredError(plugin);
-            if (opts.ifDisabled && (row?.enabled === true || required)) {
-                opts.ifDisabled.skipped = true;
-                await opts.inTransaction?.(t, true);
-                return this.view(manifest, row, await this.setSecretKeys(t, orgId), required);
-            }
-            // A required plugin is enabled whatever the row said (it may predate `required`)
-            const enabled = required || (input.enabled ?? row?.enabled ?? false);
-            // 新启用来自企业目录的插件：按条目策略与授予复核（C22；已启用的不受影响）
-            if (input.enabled === true && row?.enabled !== true && !required) {
-                // 插件自己的条目 disabled 是总开关，任何途径都不能新启用（裁决 M-5）
-                const killed = await disabledPluginItems(t, [plugin]);
-                if (killed.length > 0)
-                    throw pluginItemDisabled(killed);
-                // 经某个条目安装：只看该条目（应用里的插件按应用条目，C22）；直接启用：全部来源里最严格的生效
-                if (opts.viaItem !== undefined) {
-                    await assertItemInstallable(t, orgId, opts.viaItem, opts.approvedBy ?? opts.viaItem);
-                }
-                else
-                    await assertPluginSourcesInstallable(t, orgId, plugin);
-            }
-            if (input.enabled === true)
-                await this.assertDependenciesEnabled(t, orgId, manifest);
-            else if (input.enabled === false && !input.force) {
-                await this.assertNoEnabledDependents(t, orgId, manifest);
+        const t = this.db;
+        await this.orgLock.lockFor(orgId, actorAccountId, "org.extensions.manage");
+        const row = await t
+            .selectFrom("extension_org_configs")
+            .select(["enabled", "config"])
+            .where("plugin", "=", plugin)
+            .where("org_id", "=", orgId)
+            .executeTakeFirst();
+        const required = (await requiredExtensions(t)).has(plugin);
+        const item = (await pluginItemsOf(t, [plugin])).get(plugin);
+        if (required && input.enabled === false)
+            throw requiredError(plugin);
+        if (opts.ifDisabled && (row?.enabled === true || required)) {
+            opts.ifDisabled.skipped = true;
+            return this.view(manifest, row, await this.setSecretKeys(t, orgId), required, item);
+        }
+        // A required plugin is enabled whatever the row said (it may predate `required`)
+        const enabled = required || (input.enabled ?? row?.enabled ?? false);
+        // validateOnly: the rules for (newly) enabling and disabling belong to the write that follows
+        if (!opts.validateOnly) {
+            await this.assertSwitchRules(t, orgId, manifest, input, row, required, opts);
+        }
+        let plain = row?.config ?? null;
+        let changed = [];
+        if (schema) {
+            const secrets = createSecrets(t, this.keyring, SECRETS_NAMESPACE);
+            const paths = secretPaths(schema);
+            const before = structuredClone(plain ?? {});
+            for (const p of paths) {
+                const v = await secrets.get(orgId, secretKey(plugin, p));
+                if (v !== null)
+                    setDeep(before, p, JSON.parse(v));
             }
-            let plain = row?.config ?? null;
-            let changed = [];
-            if (schema) {
-                const secrets = createSecrets(t, this.keyring, SECRETS_NAMESPACE);
-                const paths = secretPaths(schema);
-                const before = structuredClone(plain ?? {});
+            let next;
+            if (input.config !== undefined) {
+                next = structuredClone(input.config);
                 for (const p of paths) {
-                    const v = await secrets.get(orgId, secretKey(plugin, p));
-                    if (v !== null)
-                        setDeep(before, p, JSON.parse(v));
-                }
-                let next;
-                if (input.config !== undefined) {
-                    next = structuredClone(input.config);
-                    for (const p of paths) {
-                        const v = getPath(input.config, p);
-                        if (v === null)
-                            deleteDeep(next, p);
-                        else if (v === undefined) {
-                            const old = getPath(before, p);
-                            if (old !== undefined)
-                                setDeep(next, p, old);
-                        }
-                    }
-                }
-                else {
-                    next = before;
-                }
-                if (input.config !== undefined || enabled) {
-                    const r = schema.safeParse(next);
-                    if (!r.success) {
-                        throw new ApiError("extension.config_invalid", `Invalid organization config for extension ${plugin}`, toIssues(r.error));
+                    const v = getPath(input.config, p);
+                    if (v === null)
+                        deleteDeep(next, p);
+                    else if (v === undefined) {
+                        const old = getPath(before, p);
+                        if (old !== undefined)
+                            setDeep(next, p, old);
                     }
-                    next = r.data;
                 }
-                seen = { schema, config: next };
-                if (input.config !== undefined) {
-                    changed = changedPaths(schema, before, next);
-                    plain = structuredClone(next);
-                    for (const p of paths) {
-                        const v = getPath(next, p);
-                        deleteDeep(plain, p);
-                        if (v === undefined)
-                            await secrets.delete(orgId, secretKey(plugin, p));
-                        else
-                            await secrets.set(orgId, secretKey(plugin, p), JSON.stringify(v));
-                    }
+            }
+            else {
+                next = before;
+            }
+            if (input.config !== undefined || enabled) {
+                const r = schema.safeParse(next);
+                if (!r.success) {
+                    throw new ApiError("extension.config_invalid", `Invalid organization config for extension ${plugin}`, toIssues(r.error, configMessages(this.formSchema(plugin, manifest.version, schema))));
                 }
+                next = r.data;
             }
-            // 当前 schema 中已不存在的密钥路径：同一事务内清掉遗留的密文行
-            const live = new Set((schema ? secretPaths(schema) : []).map((p) => secretKey(plugin, p)));
-            const prefix = secretKey(plugin, "");
-            const cleanup = createSecrets(t, this.keyring, SECRETS_NAMESPACE);
-            for (const key of await this.setSecretKeys(t, orgId)) {
-                if (key.startsWith(prefix) && !live.has(key))
-                    await cleanup.delete(orgId, key);
+            seen = { schema, config: next };
+            if (!opts.validateOnly && input.config !== undefined) {
+                changed = changedPaths(schema, before, next);
+                plain = structuredClone(next);
+                for (const p of paths) {
+                    const v = getPath(next, p);
+                    deleteDeep(plain, p);
+                    if (v === undefined)
+                        await secrets.delete(orgId, secretKey(plugin, p));
+                    else
+                        await secrets.set(orgId, secretKey(plugin, p), JSON.stringify(v));
+                }
             }
-            await t
-                .insertInto("extension_org_configs")
-                .values({
-                plugin,
-                org_id: orgId,
-                enabled,
-                config: plain === null ? null : JSON.stringify(plain),
-                updated_by: actorAccountId,
-            })
-                .onConflict((oc) => oc.columns(["plugin", "org_id"]).doUpdateSet({
+        }
+        // Also without an org config schema: nothing is written
+        if (opts.validateOnly) {
+            return this.view(manifest, row, await this.setSecretKeys(t, orgId), required, item);
+        }
+        // 当前 schema 中已不存在的密钥路径：同一事务内清掉遗留的密文行
+        const live = new Set((schema ? secretPaths(schema) : []).map((p) => secretKey(plugin, p)));
+        const prefix = secretKey(plugin, "");
+        const cleanup = createSecrets(t, this.keyring, SECRETS_NAMESPACE);
+        for (const key of await this.setSecretKeys(t, orgId)) {
+            if (key.startsWith(prefix) && !live.has(key))
+                await cleanup.delete(orgId, key);
+        }
+        await t
+            .insertInto("extension_org_configs")
+            .values({
+            plugin,
+            org_id: orgId,
+            enabled,
+            config: plain === null ? null : JSON.stringify(plain),
+            updated_by: actorAccountId,
+        })
+            .onConflict((oc) => oc.columns(["plugin", "org_id"]).doUpdateSet({
+            enabled,
+            config: plain === null ? null : JSON.stringify(plain),
+            updated_by: actorAccountId,
+            updated_at: new Date(),
+        }))
+            .execute();
+        await audit(t, {
+            actorAccountId,
+            ...(actorTokenId !== undefined && { actorTokenId }),
+            orgId,
+            action: "org.plugin_config.updated",
+            target: plugin,
+            detail: {
                 enabled,
-                config: plain === null ? null : JSON.stringify(plain),
-                updated_by: actorAccountId,
-                updated_at: new Date(),
-            }))
-                .execute();
-            await audit(t, {
-                actorAccountId,
-                ...(actorTokenId !== undefined && { actorTokenId }),
-                orgId,
-                action: "org.plugin_config.updated",
-                target: plugin,
-                detail: {
-                    enabled,
-                    changedPaths: changed,
-                    ...(opts.viaItem !== undefined && { catalogItemId: opts.viaItem }),
-                },
-            });
-            await opts.inTransaction?.(t, false);
-            // 在同一事务里读回，返回值就是刚提交的状态
-            const saved = await t
-                .selectFrom("extension_org_configs")
-                .select(["plugin", "enabled", "config"])
-                .where("plugin", "=", plugin)
-                .where("org_id", "=", orgId)
-                .executeTakeFirst();
-            return this.view(manifest, saved, await this.setSecretKeys(t, orgId), required);
+                changedPaths: changed,
+                ...(opts.viaItem !== undefined && { catalogItemId: opts.viaItem }),
+            },
+        });
+        // 在同一事务里读回，返回值就是刚提交的状态
+        const saved = await t
+            .selectFrom("extension_org_configs")
+            .select(["plugin", "enabled", "config"])
+            .where("plugin", "=", plugin)
+            .where("org_id", "=", orgId)
+            .executeTakeFirst();
+        const view = this.view(manifest, saved, await this.setSecretKeys(t, orgId), required, item);
+        // Only once the root transaction committed (an outer caller's too): a rolled-back write
+        // registers no secrets and disconnects nothing
+        afterCommit(async () => {
+            this.reportSecrets(seen);
+            await this.afterPut(orgId, plugin, view.enabled);
         });
-        // 事务已提交：回滚的写入不会走到这里
-        this.reportSecrets(seen);
-        await this.hooks.afterPut?.(orgId, plugin, view.enabled);
         return view;
     }
+    /**
+     * The rules of a write that switches: newly enabling an extension from the platform catalog
+     * re-checks the item policy and grants (C22; one already enabled is unaffected), enabling needs
+     * the dependencies enabled, disabling (without `force`) no enabled dependents.
+     */
+    async assertSwitchRules(t, orgId, manifest, input, row, required, opts) {
+        const plugin = manifest.name;
+        if (input.enabled === true && row?.enabled !== true && !required) {
+            // 插件自己的条目 disabled 是总开关，任何途径都不能新启用（裁决 M-5）
+            const killed = await disabledPluginItems(t, [plugin]);
+            if (killed.length > 0)
+                throw pluginItemDisabled(killed);
+            // 经某个条目安装：只看该条目（应用里的插件按应用条目，C22）；直接启用：全部来源里最严格的生效
+            if (opts.viaItem !== undefined) {
+                await assertItemInstallable(t, orgId, opts.viaItem, opts.approvedBy ?? opts.viaItem);
+            }
+            else
+                await assertPluginSourcesInstallable(t, orgId, plugin);
+        }
+        if (input.enabled === true)
+            await this.assertDependenciesEnabled(t, orgId, manifest);
+        else if (input.enabled === false && !input.force) {
+            await this.assertNoEnabledDependents(t, orgId, manifest);
+        }
+    }
     /**
      * 读取并解密某插件在该组织下的完整配置（供运行时按组织构造插件实例）。
      * A required bootstrap plugin is enabled without a row (its stored config, or `{}`, is validated).
@@ -319,30 +448,33 @@ export class OrgExtensionConfigs {
      */
     async get(orgId, plugin) {
         const manifest = this.manifest(plugin);
-        const result = await this.snapshot(async (t) => {
-            const row = await t
-                .selectFrom("extension_org_configs")
-                .select(["enabled", "config"])
-                .where("plugin", "=", plugin)
-                .where("org_id", "=", orgId)
-                .executeTakeFirst();
-            await this.hooks.afterConfigRowRead?.();
-            const required = (await requiredExtensions(t)).has(plugin);
-            if (!row && !required)
-                return undefined;
-            const enabled = required || row?.enabled === true;
-            const schema = manifest.config?.org;
-            // 已停用的插件不会被实例化：不校验（可能是升级前存下的旧配置），也不解密密钥
-            if (!schema || !enabled)
-                return { enabled, config: null };
-            return this.decode(t, orgId, plugin, schema, row?.config ?? {});
-        });
+        const result = await this.getSnapshot(orgId, plugin, manifest);
         // 只读快照已结束；config 非 null 意味着插件有 org schema 且已解密
         const schema = manifest.config?.org;
         if (schema && result?.config != null)
             this.reportSecrets({ schema, config: result.config });
         return result;
     }
+    /** `REPEATABLE READ` read-only: the config row and the secrets come from one snapshot. */
+    async getSnapshot(orgId, plugin, manifest) {
+        const t = this.db;
+        const row = await t
+            .selectFrom("extension_org_configs")
+            .select(["enabled", "config"])
+            .where("plugin", "=", plugin)
+            .where("org_id", "=", orgId)
+            .executeTakeFirst();
+        await this.afterConfigRowRead?.();
+        const required = (await requiredExtensions(t)).has(plugin);
+        if (!row && !required)
+            return undefined;
+        const enabled = required || row?.enabled === true;
+        const schema = manifest.config?.org;
+        // 已停用的插件不会被实例化：不校验（可能是升级前存下的旧配置），也不解密密钥
+        if (!schema || !enabled)
+            return { enabled, config: null };
+        return this.decode(t, orgId, plugin, schema, row?.config ?? {});
+    }
     async decode(t, orgId, plugin, schema, stored) {
         const full = structuredClone(stored);
         const secrets = createSecrets(t, this.keyring, SECRETS_NAMESPACE);
@@ -362,9 +494,10 @@ export class OrgExtensionConfigs {
     }
     /**
      * 该组织里已启用、且所 requires 的按组织启用的能力只剩这个插件提供的插件（停用它会让它们失去依赖）。
-     * 在调用方事务里读（应用卸载 / 回滚前判断是否保留）。
+     * 在调用方事务里读（应用卸载 / 回滚前判断是否保留；`mandatory`: the caller holds the org row lock).
      */
-    async enabledDependents(t, orgId, plugin) {
+    async enabledDependents(orgId, plugin) {
+        const t = this.db;
         const manifest = this.host.manifests().find((m) => m.name === plugin);
         if (!manifest)
             return [];
@@ -391,7 +524,8 @@ export class OrgExtensionConfigs {
      * 在调用方事务里停用（应用安装的回滚与卸载用；调用方已锁组织行并复核角色）：不检查依赖方，配置保留，
      * 审计 `org.plugin_config.updated`（带 reason）。提交后调用方须再调 {@link afterDisable}。
      */
-    async disableIn(t, orgId, plugin, actorAccountId, reason) {
+    async disableIn(orgId, plugin, actorAccountId, reason) {
+        const t = this.db;
         // A required bootstrap plugin stays enabled in every org
         if ((await requiredExtensions(t)).has(plugin))
             return false;
@@ -416,7 +550,7 @@ export class OrgExtensionConfigs {
     }
     /** {@link disableIn} 的事务提交之后：通知停用（断开该插件的渠道连接等）。 */
     async afterDisable(orgId, plugin) {
-        await this.hooks.afterPut?.(orgId, plugin, false);
+        await this.afterPut(orgId, plugin, false);
     }
     /** 该组织已启用的插件名（只含当前已加载的插件；待批准的不算；必需的引导插件始终算启用）。 */
     async enabledSet(t, orgId) {
@@ -483,7 +617,7 @@ export class OrgExtensionConfigs {
             throw new ApiError("extension.not_found", `Extension ${plugin} is not installed`);
         return set;
     }
-    view(m, row, setKeys, required) {
+    view(m, row, setKeys, required, items) {
         const schema = m.config?.org;
         const paths = schema ? secretPaths(schema) : [];
         let config = null;
@@ -500,11 +634,27 @@ export class OrgExtensionConfigs {
             config,
             secrets: paths.map((p) => ({ path: p, set: setKeys.has(secretKey(m.name, p)) })),
             permissions: permissionGroups(this.permissionsOf(m.name)),
-            orgConfigSchema: schema ? orgJsonSchema(schema) : null,
+            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")
+                ? "following"
+                : "none",
+            needsConfig: schema !== undefined &&
+                orgConfigIncomplete(schema, config, (p) => setKeys.has(secretKey(m.name, p))),
         };
     }
+    /**
+     * The org schema's form JSON Schema, a copy (`x-ui` stripped when its hints are invalid; the host
+     * warns at load). Never throws: a hint conversion that throws serves the plain schema, or null
+     * (one warning per schema on this replica), so one hand-made package cannot fail the org's list.
+     */
+    formSchema(plugin, version, schema) {
+        const r = safeConfigFormSchema(schema, "org", (err, fallback) => this.log.warn("the org config form schema could not be built with its UI hints; hints dropped", { plugin, version, schema: fallback, err }));
+        return r ? structuredClone(r.schema) : null;
+    }
     /** 该组织在 `kernel` 命名空间下已设置的插件配置密钥键（不解密）。 */
     async setSecretKeys(db, orgId) {
         const rows = await db
@@ -516,5 +666,83 @@ export class OrgExtensionConfigs {
             .execute();
         return new Set(rows.map((r) => r.key));
     }
+};
+__decorate([
+    Transactional({
+        propagation: "requires_new",
+        isolationLevel: "repeatable read",
+        accessMode: "read only",
+    })
+], OrgExtensionConfigs.prototype, "listSnapshot", null);
+__decorate([
+    Transactional()
+], OrgExtensionConfigs.prototype, "write", null);
+__decorate([
+    Transactional({
+        propagation: "requires_new",
+        isolationLevel: "repeatable read",
+        accessMode: "read only",
+    })
+], OrgExtensionConfigs.prototype, "getSnapshot", null);
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], OrgExtensionConfigs.prototype, "enabledDependents", null);
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], OrgExtensionConfigs.prototype, "disableIn", null);
+OrgExtensionConfigs = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(TransactionHost)),
+    __param(2, Inject(KEYRING)),
+    __param(3, Inject(ExtensionHost)),
+    __param(4, Inject(OrgLock)),
+    __param(5, Inject(ExtensionInstalls)),
+    __param(6, Inject(KernelEvents)),
+    __param(7, Inject(KERNEL_LOGGER)),
+    __param(8, Inject(EffectiveConfigs)),
+    __param(9, Inject(ExtensionAvailability))
+], OrgExtensionConfigs);
+export { OrgExtensionConfigs };
+/**
+ * Whether an org may see an extension with these live catalog items (`listed`: the items whose
+ * `named` list has the org): one visible item is enough; without an item (config-declared, or its
+ * items deleted) it is visible. A builtin item counts as `all`.
+ */
+function itemsVisible(items, listed) {
+    if (!items)
+        return true;
+    return items.some((i) => visibleTo({ scope: i.builtin ? "all" : i.scope }, listed.has(i.id)));
+}
+/**
+ * Whether the org sees `plugin` in its extension list (a required bootstrap plugin always; else
+ * under its catalog items' scope, as {@link OrgExtensionConfigs.list} filters). `db` may be a
+ * transaction.
+ */
+export async function extensionVisibleTo(db, orgId, plugin) {
+    if ((await requiredExtensions(db)).has(plugin))
+        return true;
+    const items = (await pluginItemsOf(db, [plugin])).get(plugin);
+    if (!items)
+        return true;
+    const listed = new Set((await db
+        .selectFrom("catalog_item_scope_orgs")
+        .select("item_id")
+        .where("org_id", "=", orgId)
+        .where("item_id", "in", items.map((i) => i.id))
+        .execute()).map((r) => r.item_id));
+    return itemsVisible(items, listed);
+}
+/**
+ * The stored org-only config does not satisfy the org schema (a required field missing): what the
+ * org form reports before any edit. A set secret is not decrypted here; issues on it or below it
+ * are ignored (it was validated when written).
+ */
+function orgConfigIncomplete(schema, plain, secretSet) {
+    const r = schema.safeParse(plain ?? {});
+    if (r.success)
+        return false;
+    const secrets = secretPaths(schema).filter(secretSet);
+    return toIssues(r.error).some((i) => !secrets.some((p) => i.path === p || i.path.startsWith(`${p}.`)));
 }
 const requiredError = (plugin) => new ApiError("extension.required", `Extension ${plugin} is required by this deployment (a bootstrap plugin): it is enabled in every organization and cannot be disabled`);