@capybara-hq/kernel 0.1.0-rc.2 → 0.1.0-rc.20

package/dist/extensions/installs.d.ts

@@ -1,10 +1,11 @@
 import { type PluginExtensionSection } from "@capybara-hq/plugin-sdk";
 import type { core } from "zod";
 import type { Keyring } from "../ctx/secrets.js";
-import { EnterpriseAdminLock } from "../identity/enterprise-admin.js";
+import { SuperAdminLock } from "../identity/super-admin.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
+import { OrgLock } from "../orgs/org-lock.js";
 import { type ProvenanceResult } from "../packages/provenance.js";
 import { ExtensionApprovals } from "./approvals.js";
 import { ExtensionBlobs } from "./blobs.js";
@@ -83,7 +84,7 @@ export interface IngestSource {
 export declare class ExtensionInstalls {
     private readonly db;
     readonly txHost: TransactionHost;
-    /** The enterprise admin lock (identity/enterprise-admin.ts): joins the transaction. */
+    /** The super admin lock (identity/super-admin.ts): joins the transaction. */
     private readonly adminLock;
     private readonly blobs;
     private readonly approvals;
@@ -91,17 +92,26 @@ export declare class ExtensionInstalls {
     private readonly registry;
     private readonly config;
     private readonly keyring;
+    /** The owner org's lock: an org upload re-checks its org admin instead (ruling P3-10). */
+    private readonly orgLock;
     constructor(db: KernelDb, txHost: TransactionHost, 
-    /** The enterprise admin lock (identity/enterprise-admin.ts): joins the transaction. */
-    adminLock: EnterpriseAdminLock, blobs: ExtensionBlobs, approvals: ExtensionApprovals, 
+    /** The super admin lock (identity/super-admin.ts): joins the transaction. */
+    adminLock: SuperAdminLock, blobs: ExtensionBlobs, approvals: ExtensionApprovals, 
     /** The config-declared extension names (an install cannot take them, C15). */
-    registry: ExtensionRegistry, config: KernelConfigService, keyring: Keyring);
+    registry: ExtensionRegistry, config: KernelConfigService, keyring: Keyring, 
+    /** The owner org's lock: an org upload re-checks its org admin instead (ruling P3-10). */
+    orgLock: OrgLock);
     /**
      * An extension's effective deployment config, not validated yet (C10): the startup config
      * (`fileValue`, file / Nacos merged with env) completed by the fields stored in PG; merged by
      * the fields of `schema` when it is given.
      */
     effectiveDeploymentConfig(plugin: string, fileValue: unknown, schema?: core.$ZodType): Promise<unknown>;
+    /**
+     * Whether PG holds a deployment config row for the extension (a super admin saved one and has
+     * not cleared it since; `DELETE /api/v1/admin/extensions/:name/config` removes it).
+     */
+    hasStoredDeploymentConfig(plugin: string): Promise<boolean>;
     /** Every install record's extension name (any desired state). */
     installedNames(): Promise<string[]>;
     /**
@@ -112,19 +122,26 @@ export declare class ExtensionInstalls {
      * - extension name equal to a config-declared one -> `extension.config_declared`;
      * - an install record of the same name comes from another npm package -> `extension.name_conflict`
      *   (a new version of the same package is an upgrade, handled elsewhere).
-     * `actor` null means the CLI (no enterprise admin re-check, audit without an actor).
+     * `actor` null means the CLI (no super admin re-check, audit without an actor). `owner`: an org
+     * upload (spec §14, P3-10): the actor is re-checked as an org admin of that org (`catalog.upload`)
+     * instead of a super admin; the package is only stored, as always (nothing runs, no install).
      */
     ingest(actor: string | null, bytes: Uint8Array, src: IngestSource, opts?: {
         actorTokenId?: string;
         store?: "object" | "pg";
         expectPackageName?: string;
+        owner?: {
+            orgId: string;
+        };
     }): Promise<PackageReview>;
     /**
-     * The enterprise admin re-check under its lock, in a transaction of its own (`requires_new`, as
+     * The super admin re-check under its lock, in a transaction of its own (`requires_new`, as
      * before the conversion): the package write that follows never runs inside a caller's
      * transaction holding the lock.
      */
     private authorize;
+    /** The super admin, or for an org upload the owner org's admin, re-checked under its lock. */
+    private authorizeIn;
     /**
      * The `extension.package_uploaded` audit, re-checking the actor under the lock, committed on its
      * own (`requires_new`): the stored package it records is not rolled back by a caller either.
@@ -138,7 +155,7 @@ export declare class ExtensionInstalls {
     /**
      * Fetches one package from the configured npm registry (verified by `dist.integrity`, see
      * packages/npm.ts), downloading only, not storing: download failure -> `packages.npm_failed` (502);
-     * over `packages.maxBytes` -> `extension.package_too_large`. Enterprise catalog npm imports use it
+     * over `packages.maxBytes` -> `extension.package_too_large`. Platform catalog npm imports use it
      * too.
      */
     fetchNpm(input: {
@@ -194,6 +211,10 @@ export declare class ExtensionInstalls {
     }): Promise<PackageReview>;
     /** 全部安装记录（按名字）。 */
     list(): Promise<ExtensionInstallRow[]>;
-    /** Install records desired enabled, with their reviewed extension sections (by name). */
+    /**
+     * Install records desired enabled, with their reviewed extension sections, the earliest enabled
+     * first (`enabled_at`, then the install time, then the name): of two enabled providers of a
+     * single-provider extension point the first one in this order is the one every replica loads.
+     */
     desired(): Promise<DesiredExtension[]>;
 }

package/dist/extensions/installs.js

@@ -9,15 +9,17 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 import { SDK_VERSION } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable } from "@nestjs/common";
+import { sql } from "kysely";
 import { configFields } from "../config/fields.js";
 import { ApiError } from "../errors.js";
 import { audit } from "../identity/audit.js";
-import { EnterpriseAdminLock } from "../identity/enterprise-admin.js";
+import { SuperAdminLock } from "../identity/super-admin.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
 import { Transactional } from "../infra/database/transactional.decorator.js";
 import { KEYRING } from "../infra/tokens.js";
+import { OrgLock } from "../orgs/org-lock.js";
 import { fetchNpmPackage, IntegrityMismatchError, NpmFetchError, PackageTooLargeError, } from "../packages/npm.js";
 import { fetchProvenance, PROVENANCE_TIMEOUT_MS, } from "../packages/provenance.js";
 import { ExtensionApprovals } from "./approvals.js";
@@ -45,11 +47,14 @@ let ExtensionInstalls = class ExtensionInstalls {
     registry;
     config;
     keyring;
+    orgLock;
     constructor(db, txHost, 
-    /** The enterprise admin lock (identity/enterprise-admin.ts): joins the transaction. */
+    /** The super admin lock (identity/super-admin.ts): joins the transaction. */
     adminLock, blobs, approvals, 
     /** The config-declared extension names (an install cannot take them, C15). */
-    registry, config, keyring) {
+    registry, config, keyring, 
+    /** The owner org's lock: an org upload re-checks its org admin instead (ruling P3-10). */
+    orgLock) {
         this.db = db;
         this.txHost = txHost;
         this.adminLock = adminLock;
@@ -58,6 +63,7 @@ let ExtensionInstalls = class ExtensionInstalls {
         this.registry = registry;
         this.config = config;
         this.keyring = keyring;
+        this.orgLock = orgLock;
     }
     /**
      * An extension's effective deployment config, not validated yet (C10): the startup config
@@ -71,6 +77,18 @@ let ExtensionInstalls = class ExtensionInstalls {
         const fields = schema ? configFields(schema).map((f) => f.path) : undefined;
         return mergeDeploymentConfig(stored, fileValue, fields);
     }
+    /**
+     * Whether PG holds a deployment config row for the extension (a super admin saved one and has
+     * not cleared it since; `DELETE /api/v1/admin/extensions/:name/config` removes it).
+     */
+    async hasStoredDeploymentConfig(plugin) {
+        const row = await this.db
+            .selectFrom("extension_deployment_configs")
+            .select("plugin")
+            .where("plugin", "=", plugin)
+            .executeTakeFirst();
+        return row !== undefined;
+    }
     /** Every install record's extension name (any desired state). */
     async installedNames() {
         const rows = await this.db.selectFrom("extension_installs").select("name").execute();
@@ -84,9 +102,14 @@ let ExtensionInstalls = class ExtensionInstalls {
      * - extension name equal to a config-declared one -> `extension.config_declared`;
      * - an install record of the same name comes from another npm package -> `extension.name_conflict`
      *   (a new version of the same package is an upgrade, handled elsewhere).
-     * `actor` null means the CLI (no enterprise admin re-check, audit without an actor).
+     * `actor` null means the CLI (no super admin re-check, audit without an actor). `owner`: an org
+     * upload (spec §14, P3-10): the actor is re-checked as an org admin of that org (`catalog.upload`)
+     * instead of a super admin; the package is only stored, as always (nothing runs, no install).
      */
     async ingest(actor, bytes, src, opts = {}) {
+        if (opts.owner !== undefined && actor === null) {
+            throw new Error("an org upload has an actor");
+        }
         const maxBytes = this.config.get().packages.maxBytes;
         if (bytes.byteLength > maxBytes) {
             throw new ApiError("extension.package_too_large", `The extension package is larger than ${maxBytes} bytes`);
@@ -121,9 +144,9 @@ let ExtensionInstalls = class ExtensionInstalls {
         if (installed && installed.package_name !== packageName) {
             throw new ApiError("extension.name_conflict", `Extension ${m.name} is already installed from package ${installed.package_name}; package ${packageName} uses the same extension name`);
         }
-        // 写包之前在锁内复核发起人仍是企业管理员（守卫读到的身份可能已过期）；审计在写完后同样复核
+        // 写包之前在锁内复核发起人仍是超级管理员（守卫读到的身份可能已过期）；审计在写完后同样复核
         if (actor !== null)
-            await this.authorize(actor);
+            await this.authorize(actor, opts.owner);
         await this.blobs.put(pkg, bytes, {
             source: src.source,
             ref: src.ref,
@@ -135,7 +158,8 @@ let ExtensionInstalls = class ExtensionInstalls {
             version: m.version,
             sha256: pkg.sha256,
             source: src.source,
-        });
+            ...(opts.owner !== undefined && { orgId: opts.owner.orgId }),
+        }, opts.owner);
         const set = permissionSetOfPackage(pkg);
         const snapshot = (await this.approvals.all()).get(m.name);
         const { added, removed } = diffPermissions(snapshot?.permissions, set);
@@ -153,20 +177,27 @@ let ExtensionInstalls = class ExtensionInstalls {
         };
     }
     /**
-     * The enterprise admin re-check under its lock, in a transaction of its own (`requires_new`, as
+     * The super admin re-check under its lock, in a transaction of its own (`requires_new`, as
      * before the conversion): the package write that follows never runs inside a caller's
      * transaction holding the lock.
      */
-    async authorize(actor) {
-        await this.adminLock.lockAndAuthorize(actor);
+    async authorize(actor, owner) {
+        await this.authorizeIn(actor, owner);
+    }
+    /** The super admin, or for an org upload the owner org's admin, re-checked under its lock. */
+    async authorizeIn(actor, owner) {
+        if (owner !== undefined)
+            await this.orgLock.lockAndAuthorize(owner.orgId, actor, "catalog.upload");
+        else
+            await this.adminLock.lockAndAuthorize(actor);
     }
     /**
      * The `extension.package_uploaded` audit, re-checking the actor under the lock, committed on its
      * own (`requires_new`): the stored package it records is not rolled back by a caller either.
      */
-    async auditUpload(actor, actorTokenId, detail) {
+    async auditUpload(actor, actorTokenId, detail, owner) {
         if (actor !== null)
-            await this.adminLock.lockAndAuthorize(actor);
+            await this.authorizeIn(actor, owner);
         await audit(this.db.db, {
             ...(actor !== null && { actorAccountId: actor }),
             ...(actorTokenId !== undefined && { actorTokenId }),
@@ -182,7 +213,7 @@ let ExtensionInstalls = class ExtensionInstalls {
     /**
      * Fetches one package from the configured npm registry (verified by `dist.integrity`, see
      * packages/npm.ts), downloading only, not storing: download failure -> `packages.npm_failed` (502);
-     * over `packages.maxBytes` -> `extension.package_too_large`. Enterprise catalog npm imports use it
+     * over `packages.maxBytes` -> `extension.package_too_large`. Platform catalog npm imports use it
      * too.
      */
     async fetchNpm(input, signal) {
@@ -301,7 +332,11 @@ let ExtensionInstalls = class ExtensionInstalls {
             updatedAt: r.updated_at.toISOString(),
         }));
     }
-    /** Install records desired enabled, with their reviewed extension sections (by name). */
+    /**
+     * Install records desired enabled, with their reviewed extension sections, the earliest enabled
+     * first (`enabled_at`, then the install time, then the name): of two enabled providers of a
+     * single-provider extension point the first one in this order is the one every replica loads.
+     */
     async desired() {
         const rows = await this.db
             .selectFrom("extension_installs")
@@ -316,6 +351,8 @@ let ExtensionInstalls = class ExtensionInstalls {
             "extension_packages.blob_store",
         ])
             .where("extension_installs.desired_state", "=", "enabled")
+            .orderBy(sql `extension_installs.enabled_at ASC NULLS LAST`)
+            .orderBy("extension_installs.installed_at")
             .orderBy("extension_installs.name")
             .execute();
         return rows.map((r) => ({
@@ -332,6 +369,9 @@ let ExtensionInstalls = class ExtensionInstalls {
 __decorate([
     Transactional({ propagation: "requires_new" })
 ], ExtensionInstalls.prototype, "authorize", null);
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], ExtensionInstalls.prototype, "authorizeIn", null);
 __decorate([
     Transactional({ propagation: "requires_new" })
 ], ExtensionInstalls.prototype, "auditUpload", null);
@@ -339,11 +379,12 @@ ExtensionInstalls = __decorate([
     Injectable(),
     __param(0, Inject(KernelDb)),
     __param(1, Inject(TransactionHost)),
-    __param(2, Inject(EnterpriseAdminLock)),
+    __param(2, Inject(SuperAdminLock)),
     __param(3, Inject(ExtensionBlobs)),
     __param(4, Inject(ExtensionApprovals)),
     __param(5, Inject(ExtensionRegistry)),
     __param(6, Inject(KernelConfigService)),
-    __param(7, Inject(KEYRING))
+    __param(7, Inject(KEYRING)),
+    __param(8, Inject(OrgLock))
 ], ExtensionInstalls);
 export { ExtensionInstalls };

package/dist/extensions/instance.d.ts

@@ -1,5 +1,5 @@
-import { type ExtensionManifest, type ExtensionPointRef, type StaticExtensionManifest } from "@capybara-hq/plugin-sdk";
-import { type ExtensionPointAccess, type KernelDeps, type KernelExtensionContext, LiveConfig, type RegisteredTool, type Route } from "../ctx/create-ctx.js";
+import { type DroppedUiContribution, type ExtensionManifest, type ExtensionPointRef, type ResolvedUiContribution, type StaticExtensionManifest } from "@capybara-hq/plugin-sdk";
+import { type ExtensionPointAccess, type KernelDeps, type KernelExtensionContext, LiveConfig, type RegisteredSetupCheck, type RegisteredTool, type Route } from "../ctx/create-ctx.js";
 import type { UiActionHandler, UiRender } from "../ui/registry.js";
 import type { RegisteredHook } from "./hooks.js";
 import { InflightTracker } from "./inflight.js";
@@ -44,6 +44,17 @@ export declare class ExtensionInstance {
     readonly generation: number;
     readonly manifest: ExtensionManifest;
     readonly permissions: PermissionSet;
+    /** The manifest's UI contributions whose slot the catalog knows (UI slots spec §3.2), in manifest order. */
+    readonly ui: ResolvedUiContribution[];
+    /** The manifest's UI contributions left out at load (unknown slot or slot version). */
+    readonly uiDropped: DroppedUiContribution[];
+    /** `after` values that are not anchors of their slot (the contribution keeps the default position). */
+    readonly uiUnknownAnchors: {
+        id: string;
+        after: string;
+    }[];
+    /** Ids of contributions that still name the deprecated `place`. */
+    readonly uiDeprecatedPlace: string[];
     private hash;
     private readonly live;
     readonly entryUrl: string;
@@ -68,6 +79,10 @@ export declare class ExtensionInstance {
     get hooks(): readonly RegisteredHook[];
     get uiViews(): ReadonlyMap<string, UiRender>;
     get uiActions(): ReadonlyMap<string, UiActionHandler>;
+    /** Setup checks registered through `ctx.setup.check` (empty after revocation). */
+    get setupChecks(): ReadonlyMap<string, RegisteredSetupCheck>;
+    /** The instance's `ctx.signal`: aborted when it is revoked or disposed. */
+    get signal(): AbortSignal;
     /** 账上仍在的登记（撤销后为空）。 */
     registrations(): Registration[];
     get disposed(): boolean;

package/dist/extensions/instance.js

@@ -60,6 +60,14 @@ export class ExtensionInstance {
     generation;
     manifest;
     permissions;
+    /** The manifest's UI contributions whose slot the catalog knows (UI slots spec §3.2), in manifest order. */
+    ui;
+    /** The manifest's UI contributions left out at load (unknown slot or slot version). */
+    uiDropped;
+    /** `after` values that are not anchors of their slot (the contribution keeps the default position). */
+    uiUnknownAnchors;
+    /** Ids of contributions that still name the deprecated `place`. */
+    uiDeprecatedPlace;
     hash;
     live;
     entryUrl;
@@ -77,6 +85,11 @@ export class ExtensionInstance {
         this.source = init.source;
         this.generation = init.generation;
         this.permissions = init.permissions;
+        const ui = init.ctx.uiResolution;
+        this.ui = ui.resolved;
+        this.uiDropped = ui.dropped;
+        this.uiUnknownAnchors = ui.unknownAnchors;
+        this.uiDeprecatedPlace = ui.deprecatedPlace;
         this.hash = init.configHash;
         this.live = init.config;
         this.entryUrl = init.entryUrl;
@@ -117,6 +130,14 @@ export class ExtensionInstance {
     get uiActions() {
         return this.ctx.uiActions;
     }
+    /** Setup checks registered through `ctx.setup.check` (empty after revocation). */
+    get setupChecks() {
+        return this.ctx.setupChecks;
+    }
+    /** The instance's `ctx.signal`: aborted when it is revoked or disposed. */
+    get signal() {
+        return this.ctx.signal;
+    }
     /** 账上仍在的登记（撤销后为空）。 */
     registrations() {
         return this.ctx.ledger.list();

package/dist/extensions/ledger.d.ts

@@ -1,5 +1,5 @@
 /** 插件经 ctx 做的一项登记的种类（C17）。 */
-export type RegistrationKind = "tool" | "route" | "queue" | "bus" | "lease" | "ui.view" | "ui.action" | "provide" | "hook";
+export type RegistrationKind = "tool" | "route" | "queue" | "bus" | "lease" | "ui.view" | "ui.action" | "provide" | "hook" | "setup.check";
 /** 账上的一项：撤销时调用 `dispose()`。 */
 export interface Registration {
     kind: RegistrationKind;

package/dist/extensions/locks.d.ts

@@ -31,3 +31,15 @@ export declare class PluginDeploymentConfigLock {
     constructor(xactLock: XactLock, txHost: TransactionHost);
     lock(name: string): Promise<void>;
 }
+/**
+ * Serializes the enables of the providers of one single-provider extension point (`sandbox@2`, …):
+ * two concurrent enables of different providers cannot both see the point free. Joins the
+ * caller's transaction (`mandatory`); taken after the install lock of the extension's name, the
+ * points in sorted order.
+ */
+export declare class SingleProviderLock {
+    private readonly xactLock;
+    readonly txHost: TransactionHost;
+    constructor(xactLock: XactLock, txHost: TransactionHost);
+    lock(extensionPoint: string): Promise<void>;
+}

package/dist/extensions/locks.js

@@ -84,3 +84,29 @@ PluginDeploymentConfigLock = __decorate([
     __param(1, Inject(TransactionHost))
 ], PluginDeploymentConfigLock);
 export { PluginDeploymentConfigLock };
+/**
+ * Serializes the enables of the providers of one single-provider extension point (`sandbox@2`, …):
+ * two concurrent enables of different providers cannot both see the point free. Joins the
+ * caller's transaction (`mandatory`); taken after the install lock of the extension's name, the
+ * points in sorted order.
+ */
+let SingleProviderLock = class SingleProviderLock {
+    xactLock;
+    txHost;
+    constructor(xactLock, txHost) {
+        this.xactLock = xactLock;
+        this.txHost = txHost;
+    }
+    async lock(extensionPoint) {
+        await this.xactLock.lock(`capybara.single-provider:${extensionPoint}`);
+    }
+};
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], SingleProviderLock.prototype, "lock", null);
+SingleProviderLock = __decorate([
+    Injectable(),
+    __param(0, Inject(XactLock)),
+    __param(1, Inject(TransactionHost))
+], SingleProviderLock);
+export { SingleProviderLock };

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,9 +8,11 @@ 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";
+import { type DeploymentExtensionStatus, type PermissionGroup } from "./permission-view.js";
+import { ExtensionAvailability, type ExtensionUnavailableReason } from "./unavailable.js";
 export { type ConfigIssue, toIssues };
 /** 组织视角下一个已加载插件的状态；`config` 永远不含密钥字段，密钥只回显「是否已设置」。 */
 export interface OrgExtensionView {
@@ -32,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;
@@ -48,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.
@@ -69,6 +102,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 +130,10 @@ 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;
+    /** 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, 
@@ -100,7 +144,11 @@ 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, 
+    /** 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();
     /** 把一份组织配置里的密钥值登记到日志打码（无密钥时无操作）；调用方须在事务提交后调用。 */
@@ -108,12 +156,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 +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).
@@ -150,7 +228,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>;
     /** 该组织已启用的插件名（只含当前已加载的插件；待批准的不算；必需的引导插件始终算启用）。 */
@@ -166,6 +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;
 }
+/**
+ * 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>;