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

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

@@ -1,11 +1,19 @@
-import type { Transaction } from "kysely";
-import type { z } from "zod";
+import { type PluginScope } from "../catalog/scope.js";
 import { type Keyring } from "../ctx/secrets.js";
-import type { KernelDatabase, KernelDb } from "../db/kernel-schema.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";
+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 type { ExtensionHost } from "./host.js";
-import { type PermissionGroup } from "./permission-view.js";
-type Trx = Transaction<KernelDatabase>;
+import { EffectiveConfigs } from "./effective-config.js";
+import { ExtensionHost } from "./host.js";
+import { ExtensionInstalls } from "./installs.js";
+import { type DeploymentExtensionStatus, type PermissionGroup } from "./permission-view.js";
+import { ExtensionAvailability, type ExtensionUnavailableReason } from "./unavailable.js";
+export { type ConfigIssue, toIssues };
 /** 组织视角下一个已加载插件的状态；`config` 永远不含密钥字段，密钥只回显「是否已设置」。 */
 export interface OrgExtensionView {
     plugin: string;
@@ -28,12 +36,41 @@ export interface OrgExtensionView {
      * 组织的启用开关保留不变（不能修改），其余字段为空。
      */
     available: boolean;
+    /**
+     * The extension's status on the deployment, as the admin console derives it
+     * (`deriveExtensionStatus`): `enabled` when it is loaded here; otherwise why not.
+     */
+    status: DeploymentExtensionStatus;
+    /**
+     * Only when unavailable: why it cannot be used (spec §14.5 item 4), e.g.
+     * `needs_deployment_config`. State only, never a config value or field name.
+     */
+    reason?: ExtensionUnavailableReason;
     /**
      * A required bootstrap plugin: enabled in every org (`enabled` is always true) and cannot be
      * disabled here (`extension.required`); its org config, when it has one, can still be set.
      */
     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;
@@ -44,7 +81,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.
@@ -56,24 +93,23 @@ export interface OrgExtensionPutOptions {
      */
     approvedBy?: string;
     /**
-     * 应用安装用：在组织行锁内读到该插件已启用时什么都不写（不改配置、不审计），并把 `skipped` 置为 true——
-     * 「之前就启用」与「本次启用」在锁内判定，不会与并发的启用竞争。
+     * For a plugin install: when the extension is already enabled under the org row lock, nothing is
+     * written (no config change, no audit) and `skipped` is set to true. "Enabled before" and
+     * "enabled now" are decided under the lock, so a concurrent enable cannot race it. A caller that
+     * records the extension in the same transaction (the catalog install, `put` joins its
+     * transaction) reads `skipped` after `put` returns: no concurrent uninstall fits in between.
      */
     ifDisabled?: {
         skipped: boolean;
     };
     /**
-     * 在同一个事务（组织行锁内）里最后执行，`skipped` 同 {@link ifDisabled}：应用安装在这里记组件，启用与记录之间
-     * 插不进并发的卸载。
+     * 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.
      */
-    inTransaction?: (t: Trx, skipped: boolean) => Promise<void>;
+    validateOnly?: boolean;
 }
-/** 校验失败的单条原因：只含路径与按 issue 类型生成的说明，不回显字段值。 */
-export interface ConfigIssue {
-    path: string;
-    message: string;
-}
-export declare function toIssues(error: z.ZodError): ConfigIssue[];
 /**
  * Org-level extension config: enablement and the `config.org` config stored per org.
  * The non-secret part is stored in `capybara.extension_org_configs.config`; each secret field is
@@ -82,38 +118,72 @@ export declare function toIssues(error: z.ZodError): ConfigIssue[];
  * No in-process state: every call reads PG, safe with multiple replicas.
  */
 export declare class OrgExtensionConfigs {
-    private readonly db;
+    private readonly kdb;
+    readonly txHost: TransactionHost;
     private readonly keyring;
     private readonly host;
-    private readonly hooks;
-    constructor(db: KernelDb, keyring: Keyring, host: ExtensionHost, hooks?: {
-        /**
-         * 经手（写入或解密读出）的密钥值，含嵌套字段；只在事务提交后调用（回滚的写入不上报）。
-         * 内核传 `log.addOrgSecrets` 使其在日志中打码。
-         */
-        onSecrets?: (values: string[]) => void;
-        /**
-         * 写入提交之后调用（`enabled` 为写入后的启用状态）。内核传：停用时给该组织该插件的渠道连接广播
-         * `channel.changed`，持有长连接的副本立即断开。
-         */
-        afterPut?: (orgId: string, plugin: string, enabled: boolean) => Promise<void>;
-        /** 部署上的安装记录（任何期望状态）：没加载的列为不可用（T14）。 */
-        installed?: () => Promise<{
-            name: string;
-            version: string;
-        }[]>;
-        /** 仅供测试：在读完配置行之后、读密钥之前插入确定性的交错点。 */
-        afterConfigRowRead?: () => Promise<void>;
-    });
-    /** 把一份组织配置里的密钥值交给 onSecrets（无回调或无密钥时无操作）；调用方须在事务提交后调用。 */
+    /** The org row lock (orgs/org-lock.ts): joins the transaction. */
+    private readonly orgLock;
+    /** Install records (any desired state): the ones not loaded are listed unavailable (T14). */
+    private readonly installs;
+    /** `extension.org-disabled` after a disable commits (channel connections drop at once). */
+    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;
+    /** Why an installed extension is not loaded (`status` / `reason` of the unavailable ones). */
+    private readonly availability;
+    /** Test seam only: a deterministic interleaving point after the config rows are read, before the secrets. */
+    afterConfigRowRead: (() => Promise<void>) | undefined;
+    constructor(kdb: KernelDb, txHost: TransactionHost, keyring: Keyring, host: ExtensionHost, 
+    /** The org row lock (orgs/org-lock.ts): joins the transaction. */
+    orgLock: OrgLock, 
+    /** Install records (any desired state): the ones not loaded are listed unavailable (T14). */
+    installs: ExtensionInstalls, 
+    /** `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, 
+    /** The effective deployment config of each org (spec A §6): read for `needsConfig`. */
+    effective: EffectiveConfigs, 
+    /** Why an installed extension is not loaded (`status` / `reason` of the unavailable ones). */
+    availability: ExtensionAvailability);
+    /** The kernel-schema handle of the current transaction. */
+    private get db();
+    /** 把一份组织配置里的密钥值登记到日志打码（无密钥时无操作）；调用方须在事务提交后调用。 */
     private reportSecrets;
-    /** `REPEATABLE READ` 只读事务：配置行与密钥来自同一个快照，不会读到跨两次提交的混合状态。 */
-    private snapshot;
+    /** 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,7 +195,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).
@@ -137,17 +216,19 @@ export declare class OrgExtensionConfigs {
         enabled: boolean;
         config: unknown;
     } | undefined>;
+    /** `REPEATABLE READ` read-only: the config row and the secrets come from one snapshot. */
+    private getSnapshot;
     private decode;
     /**
      * 该组织里已启用、且所 requires 的按组织启用的能力只剩这个插件提供的插件（停用它会让它们失去依赖）。
-     * 在调用方事务里读（应用卸载 / 回滚前判断是否保留）。
+     * 在调用方事务里读（应用卸载 / 回滚前判断是否保留；`mandatory`: the caller holds the org row lock).
      */
-    enabledDependents(t: Trx, orgId: string, plugin: string): Promise<string[]>;
+    enabledDependents(orgId: string, plugin: string): Promise<string[]>;
     /**
      * 在调用方事务里停用（应用安装的回滚与卸载用；调用方已锁组织行并复核角色）：不检查依赖方，配置保留，
      * 审计 `org.plugin_config.updated`（带 reason）。提交后调用方须再调 {@link afterDisable}。
      */
-    disableIn(t: Trx, 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>;
     /** 该组织已启用的插件名（只含当前已加载的插件；待批准的不算；必需的引导插件始终算启用）。 */
@@ -163,7 +244,18 @@ export declare class OrgExtensionConfigs {
     private manifest;
     private permissionsOf;
     private view;
+    /**
+     * 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.
+     */
+    private formSchema;
     /** 该组织在 `kernel` 命名空间下已设置的插件配置密钥键（不解密）。 */
     private setSecretKeys;
 }
-export {};
+/**
+ * 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>;