@capybara-hq/kernel 0.1.0-rc.4 → 0.1.0-rc.5

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

@@ -1,4 +1,6 @@
+import { type PluginScope } from "../catalog/scope.js";
 import { type Keyring } from "../ctx/secrets.js";
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
 import { KernelEvents } from "../infra/events/kernel-events.js";
@@ -6,6 +8,7 @@ import type { KernelLogger } from "../log.js";
 import { OrgLock } from "../orgs/org-lock.js";
 import { type ConfigIssue, toIssues } from "./config-issues.js";
 import { type JsonSchema } from "./config-json-schema.js";
+import { EffectiveConfigs } from "./effective-config.js";
 import { ExtensionHost } from "./host.js";
 import { ExtensionInstalls } from "./installs.js";
 import { type PermissionGroup } from "./permission-view.js";
@@ -37,7 +40,26 @@ export interface OrgExtensionView {
      * disabled here (`extension.required`); its org config, when it has one, can still be set.
      */
     required: boolean;
+    /** The catalog plugin the extension ships in and its scope (builtin counts as `all`); null without one. */
+    catalogItem: {
+        itemId: string;
+        scope: PluginScope;
+    } | null;
+    /** The org admin can switch it (the plugin's switch): never for an `all` / builtin plugin. */
+    switchable: boolean;
+    /**
+     * The two-level deployment config (spec A §5.3, §5.4): `following` the platform, a `copy` of the
+     * overridable fields, or `none` (the extension has no overridable field, or is unavailable).
+     */
+    overrideState: "following" | "copy" | "none";
+    /**
+     * The org must configure the extension before it works here (spec A §6): its effective config
+     * is not valid, or a required org-only field is missing. Always false when unavailable.
+     */
+    needsConfig: boolean;
 }
+/** The extension points an extension provides, from its permission list's `provides` group. */
+export declare function providesOf(view: Pick<OrgExtensionView, "permissions">): string[];
 /** `put` 的输入：`config` 中的密钥字段缺省 = 保留原值、`null` = 清除、其他值 = 新值。 */
 export interface OrgExtensionInput {
     enabled?: boolean | undefined;
@@ -48,7 +70,7 @@ export interface OrgExtensionInput {
 /** `put` 的内部选项（不来自 HTTP）。 */
 export interface OrgExtensionPutOptions {
     /**
-     * Enable through this enterprise catalog item (the extension's own item, or an app item: plugins
+     * Enable through this platform catalog item (the extension's own item, or an app item: plugins
      * in an app follow the app item's policy, C22). When omitted, judged by every source item in
      * `extension_catalog_sources` (the strictest wins); an extension not installed through the catalog
      * is not bound by catalog policy.
@@ -69,6 +91,13 @@ export interface OrgExtensionPutOptions {
     ifDisabled?: {
         skipped: boolean;
     };
+    /**
+     * Check the role and the config (the given `config`, or with `enabled: true` the stored one,
+     * merged with the stored secrets, against the schema) and write nothing: lets a caller that must
+     * do another write first fail without a side effect. The rules for newly enabling (catalog policy,
+     * dependencies) are left to that write: the plugin install that enables it checks them.
+     */
+    validateOnly?: boolean;
 }
 /**
  * Org-level extension config: enablement and the `config.org` config stored per org.
@@ -90,6 +119,8 @@ export declare class OrgExtensionConfigs {
     private readonly events;
     /** Secret values handled (written or decrypted) are masked in the logs after the commit. */
     private readonly log;
+    /** The effective deployment config of each org (spec A §6): read for `needsConfig`. */
+    private readonly effective;
     /** Test seam only: a deterministic interleaving point after the config rows are read, before the secrets. */
     afterConfigRowRead: (() => Promise<void>) | undefined;
     constructor(kdb: KernelDb, txHost: TransactionHost, keyring: Keyring, host: ExtensionHost, 
@@ -100,7 +131,9 @@ export declare class OrgExtensionConfigs {
     /** `extension.org-disabled` after a disable commits (channel connections drop at once). */
     events: KernelEvents, 
     /** Secret values handled (written or decrypted) are masked in the logs after the commit. */
-    log: KernelLogger);
+    log: KernelLogger, 
+    /** The effective deployment config of each org (spec A §6): read for `needsConfig`. */
+    effective: EffectiveConfigs);
     /** The kernel-schema handle of the current transaction. */
     private get db();
     /** 把一份组织配置里的密钥值登记到日志打码（无密钥时无操作）；调用方须在事务提交后调用。 */
@@ -108,12 +141,34 @@ export declare class OrgExtensionConfigs {
     /** After a write committed: a disabled extension's channel connections drop at once. */
     private afterPut;
     /**
-     * 列出所有已加载插件在该组织下的状态（按加载顺序）；无记录时 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.
      */
     list(orgId: string): Promise<OrgExtensionView[]>;
+    /**
+     * 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.
+     */
+    private withLayers;
     /** `REPEATABLE READ` read-only: the config rows and the secrets come from one snapshot. */
     private listSnapshot;
+    /**
+     * 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).
+     */
+    switchPlan(plugin: string, enabled: boolean): Promise<{
+        kind: "direct";
+    } | {
+        kind: "locked";
+    } | {
+        kind: "item";
+        itemId: string;
+    }>;
     /**
      * Writes enablement and / or config. The actor's role is re-read under the org row lock (needs
      * `org.extensions.manage`).
@@ -125,8 +180,16 @@ export declare 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`.
      */
-    put(orgId: string, plugin: string, input: OrgExtensionInput, actorAccountId: string, actorTokenId?: string, opts?: OrgExtensionPutOptions): Promise<OrgExtensionView>;
+    put(orgId: string, plugin: string, input: OrgExtensionInput, 
+    /** null: the kernel itself (the plugin scope sync installing a plugin), no role check. */
+    actorAccountId: string | null, actorTokenId?: string, opts?: OrgExtensionPutOptions): Promise<OrgExtensionView>;
     private write;
+    /**
+     * 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.
+     */
+    private assertSwitchRules;
     /**
      * 读取并解密某插件在该组织下的完整配置（供运行时按组织构造插件实例）。
      * A required bootstrap plugin is enabled without a row (its stored config, or `{}`, is validated).
@@ -150,7 +213,7 @@ export declare class OrgExtensionConfigs {
      * 在调用方事务里停用（应用安装的回滚与卸载用；调用方已锁组织行并复核角色）：不检查依赖方，配置保留，
      * 审计 `org.plugin_config.updated`（带 reason）。提交后调用方须再调 {@link afterDisable}。
      */
-    disableIn(orgId: string, plugin: string, actorAccountId: string, reason: string): Promise<boolean>;
+    disableIn(orgId: string, plugin: string, actorAccountId: string | null, reason: string): Promise<boolean>;
     /** {@link disableIn} 的事务提交之后：通知停用（断开该插件的渠道连接等）。 */
     afterDisable(orgId: string, plugin: string): Promise<void>;
     /** 该组织已启用的插件名（只含当前已加载的插件；待批准的不算；必需的引导插件始终算启用）。 */
@@ -175,3 +238,9 @@ export declare class OrgExtensionConfigs {
     /** 该组织在 `kernel` 命名空间下已设置的插件配置密钥键（不解密）。 */
     private setSecretKeys;
 }
+/**
+ * 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 declare function extensionVisibleTo(db: KernelSchemaDb, orgId: string, plugin: string): Promise<boolean>;

package/dist/extensions/org-config.js

@@ -9,7 +9,8 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 import { EXTENSION_POINTS, parseExtensionPoint, } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable } from "@nestjs/common";
-import { assertItemInstallable, assertPluginSourcesInstallable, disabledPluginItems, pluginItemDisabled, } from "../catalog/requests.service.js";
+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";
@@ -23,14 +24,36 @@ 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 { 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";
 export { toIssues };
 /** 内核自己的 secrets 命名空间（plugin-sdk 把 `kernel` 列为保留插件名，插件不会与之相撞）。 */
 const SECRETS_NAMESPACE = "kernel";
 const secretKey = (plugin, path) => `plugin-config:${plugin}:${path}`;
+/** 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 校验报错）。 */
 function setDeep(obj, path, value) {
@@ -80,6 +103,7 @@ let OrgExtensionConfigs = class OrgExtensionConfigs {
     installs;
     events;
     log;
+    effective;
     /** Test seam only: a deterministic interleaving point after the config rows are read, before the secrets. */
     afterConfigRowRead;
     constructor(kdb, txHost, keyring, host, 
@@ -90,7 +114,9 @@ let OrgExtensionConfigs = class OrgExtensionConfigs {
     /** `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) {
+    log, 
+    /** The effective deployment config of each org (spec A §6): read for `needsConfig`. */
+    effective) {
         this.kdb = kdb;
         this.txHost = txHost;
         this.keyring = keyring;
@@ -99,6 +125,7 @@ let OrgExtensionConfigs = class OrgExtensionConfigs {
         this.installs = installs;
         this.events = events;
         this.log = log;
+        this.effective = effective;
     }
     /** The kernel-schema handle of the current transaction. */
     get db() {
@@ -118,15 +145,38 @@ let OrgExtensionConfigs = class OrgExtensionConfigs {
             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.installs.list()).map((r) => ({
             name: r.name,
             version: r.version,
         }));
-        return this.listSnapshot(orgId, installed);
+        return this.withLayers(orgId, await this.listSnapshot(orgId, installed));
+    }
+    /**
+     * 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) {
@@ -141,10 +191,23 @@ let OrgExtensionConfigs = class OrgExtensionConfigs {
         // 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 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))
+            .filter((i) => !names.has(i.name) && seen(i.name))
             .sort((a, b) => a.name.localeCompare(b.name))
             .map((i) => ({
             plugin: i.name,
@@ -157,9 +220,31 @@ let OrgExtensionConfigs = class OrgExtensionConfigs {
             orgConfigSchema: null,
             available: false,
             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
      * `org.extensions.manage`).
@@ -171,19 +256,22 @@ let OrgExtensionConfigs = 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`);
         }
-        return this.write(orgId, plugin, manifest, input, actorAccountId, actorTokenId, opts);
+        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 t = this.db;
-        await this.orgLock.lockAndAuthorize(orgId, actorAccountId, "org.extensions.manage");
+        await this.orgLock.lockFor(orgId, actorAccountId, "org.extensions.manage");
         const row = await t
             .selectFrom("extension_org_configs")
             .select(["enabled", "config"])
@@ -191,31 +279,18 @@ let OrgExtensionConfigs = class OrgExtensionConfigs {
             .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);
+            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);
-        // 新启用来自企业目录的插件：按条目策略与授予复核（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);
+        // 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 = [];
@@ -253,7 +328,7 @@ let OrgExtensionConfigs = class OrgExtensionConfigs {
                 next = r.data;
             }
             seen = { schema, config: next };
-            if (input.config !== undefined) {
+            if (!opts.validateOnly && input.config !== undefined) {
                 changed = changedPaths(schema, before, next);
                 plain = structuredClone(next);
                 for (const p of paths) {
@@ -266,6 +341,10 @@ let OrgExtensionConfigs = class OrgExtensionConfigs {
                 }
             }
         }
+        // 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, "");
@@ -309,7 +388,7 @@ let OrgExtensionConfigs = class OrgExtensionConfigs {
             .where("plugin", "=", plugin)
             .where("org_id", "=", orgId)
             .executeTakeFirst();
-        const view = this.view(manifest, saved, await this.setSecretKeys(t, orgId), required);
+        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 () => {
@@ -318,6 +397,31 @@ let OrgExtensionConfigs = class OrgExtensionConfigs {
         });
         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).
@@ -496,7 +600,7 @@ let OrgExtensionConfigs = 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;
@@ -516,6 +620,12 @@ let OrgExtensionConfigs = class OrgExtensionConfigs {
             orgConfigSchema: schema ? this.formSchema(m.name, m.version, schema) : null,
             available: true,
             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))),
         };
     }
     /**
@@ -571,7 +681,49 @@ OrgExtensionConfigs = __decorate([
     __param(4, Inject(OrgLock)),
     __param(5, Inject(ExtensionInstalls)),
     __param(6, Inject(KernelEvents)),
-    __param(7, Inject(KERNEL_LOGGER))
+    __param(7, Inject(KERNEL_LOGGER)),
+    __param(8, Inject(EffectiveConfigs))
 ], 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`);

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

@@ -0,0 +1,37 @@
+import { type JsonSchema } from "@capybara-hq/plugin-sdk";
+import { z } from "zod";
+/**
+ * The org level of a deployment config field (spec A §5.1): `hidden` (platform only, orgs never
+ * see it; a field without `orgAccess`), `readonly` (orgs see it, cannot change it) or `override`
+ * (the platform sets the default, an org may bring its own value). Levels sit on top-level keys of
+ * the deployment schema only (§5.2); a nested field has its top-level key's level.
+ */
+export type FieldLevel = "hidden" | "readonly" | "override";
+/** The top-level keys of a `ZodObject` deployment schema with their level; empty otherwise. */
+export declare function fieldLevels(schema: z.ZodTypeAny | undefined): Map<string, FieldLevel>;
+/**
+ * The same levels read from a package's static form schema (`x-org` on top-level properties), for
+ * an install record whose module this replica has not loaded.
+ */
+export declare function jsonSchemaFieldLevels(schema: JsonSchema | undefined): Map<string, FieldLevel>;
+/**
+ * The platform's relaxed schema (§5.4a): a plain object rebuilt from the shape with every
+ * `override` key optional, so the platform may leave overridable fields empty (each org then
+ * brings its own); hidden and read-only fields stay as declared. Object-level refinements
+ * (`.refine` / `.superRefine`) are not carried over: they may read the absent fields, and zod
+ * refuses `.extend()` on a refined object. The identity when there is no `override` key. Parse
+ * through {@link parseLoadGate}, which uses this only when an overridable field is missing.
+ */
+export declare function relaxOverridable(schema: z.ZodTypeAny): z.ZodTypeAny;
+/**
+ * The platform's load gate (§5.4a): the original schema, refinements included, whenever the
+ * platform config `raw` leaves no required overridable field empty; otherwise the relaxed plain
+ * object ({@link relaxOverridable}). Following orgs are then `needsConfig` and never called, and
+ * an org copy is parsed with the full schema.
+ */
+export declare function parseLoadGate(schema: z.ZodTypeAny, raw: unknown): z.ZodSafeParseResult<unknown>;
+/**
+ * The required `override` keys the platform config `raw` leaves empty (absent and refused by the
+ * key's own schema), in schema order: orgs that follow the platform must configure them.
+ */
+export declare function missingOverridable(schema: z.ZodTypeAny, raw: unknown): string[];

package/dist/extensions/org-levels.js

@@ -0,0 +1,71 @@
+import { orgAccessOf } from "@capybara-hq/plugin-sdk";
+import { z } from "zod";
+/** The top-level keys of a `ZodObject` deployment schema with their level; empty otherwise. */
+export function fieldLevels(schema) {
+    const out = new Map();
+    if (!(schema instanceof z.ZodObject))
+        return out;
+    for (const [key, field] of Object.entries(schema.shape)) {
+        out.set(key, orgAccessOf(field) ?? "hidden");
+    }
+    return out;
+}
+/**
+ * The same levels read from a package's static form schema (`x-org` on top-level properties), for
+ * an install record whose module this replica has not loaded.
+ */
+export function jsonSchemaFieldLevels(schema) {
+    const out = new Map();
+    const props = schema?.properties;
+    if (typeof props !== "object" || props === null)
+        return out;
+    for (const [key, prop] of Object.entries(props)) {
+        const v = prop?.["x-org"];
+        out.set(key, v === "readonly" || v === "override" ? v : "hidden");
+    }
+    return out;
+}
+const overrideKeys = (schema) => [...fieldLevels(schema)].filter(([, l]) => l === "override").map(([k]) => k);
+/**
+ * The platform's relaxed schema (§5.4a): a plain object rebuilt from the shape with every
+ * `override` key optional, so the platform may leave overridable fields empty (each org then
+ * brings its own); hidden and read-only fields stay as declared. Object-level refinements
+ * (`.refine` / `.superRefine`) are not carried over: they may read the absent fields, and zod
+ * refuses `.extend()` on a refined object. The identity when there is no `override` key. Parse
+ * through {@link parseLoadGate}, which uses this only when an overridable field is missing.
+ */
+export function relaxOverridable(schema) {
+    const keys = overrideKeys(schema);
+    if (keys.length === 0)
+        return schema;
+    const obj = schema;
+    const shape = { ...obj.shape };
+    for (const k of keys)
+        shape[k] = shape[k].optional();
+    const plain = z.object(shape);
+    const catchall = obj._zod.def.catchall;
+    return catchall ? plain.catchall(catchall) : plain;
+}
+/**
+ * The platform's load gate (§5.4a): the original schema, refinements included, whenever the
+ * platform config `raw` leaves no required overridable field empty; otherwise the relaxed plain
+ * object ({@link relaxOverridable}). Following orgs are then `needsConfig` and never called, and
+ * an org copy is parsed with the full schema.
+ */
+export function parseLoadGate(schema, raw) {
+    if (missingOverridable(schema, raw).length === 0)
+        return schema.safeParse(raw);
+    return relaxOverridable(schema).safeParse(raw);
+}
+/**
+ * The required `override` keys the platform config `raw` leaves empty (absent and refused by the
+ * key's own schema), in schema order: orgs that follow the platform must configure them.
+ */
+export function missingOverridable(schema, raw) {
+    const keys = overrideKeys(schema);
+    if (keys.length === 0)
+        return [];
+    const shape = schema.shape;
+    const value = typeof raw === "object" && raw !== null ? raw : {};
+    return keys.filter((k) => value[k] === undefined && !shape[k].safeParse(undefined).success);
+}