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

package/dist/extensions/registry.d.ts

@@ -1,18 +1,63 @@
+import { type ExtensionManifest, type ExtensionPointRef } from "@capybara-hq/plugin-sdk";
+import { type InflightTracker } from "./inflight.js";
 import type { ExtensionInstance } from "./instance.js";
+import type { ExtensionSource } from "./sources.js";
+/** One item of {@link ExtensionRegistry.list}. */
+export interface ExtensionPointEntry {
+    plugin: string;
+    capability: ExtensionPointRef;
+    impl: unknown;
+    /** 插件清单的 version。 */
+    version: string;
+    /** 部署配置摘要，见 `deploymentConfigHash`。 */
+    configHash: string;
+    /** The provider instance's in-flight tracker (a tracked point's `impl`: connector, sandbox, model-provider, web-search, web-fetch, is already a proxy counted in it). */
+    inflight: InflightTracker;
+}
 /**
- * 本进程生效的插件实例（按插件名，一名一个）。顺序 = 首次激活的顺序（宿主按依赖拓扑序加载；
- * 替换同名实例保持原位置）。只是本进程的视图：跨副本的期望状态在 PG（安装记录），由各副本自己 reconcile。
+ * The extension instances in effect in this process (by extension name, one each). One provider
+ * per process (decision R6 of the Nest kernel spec): the extension host writes it, other domains
+ * read extension points and manifests from it, never from the host. The order is the order of
+ * first activation (the host loads in dependency order; a replaced instance keeps its place). It
+ * is only this process's view: the desired state across replicas is in PG (the install records),
+ * and each replica reconciles itself.
  */
 export declare class ExtensionRegistry {
     private readonly instances;
     private readonly listeners;
     private rev;
+    /** The config-declared extension names of this process (the startup config `extensions` list). */
+    private declaredNames;
+    /**
+     * Records the config-declared extensions (the host at load; before it, the start sequence for
+     * the bootstrap step; the CLI from its inspection). Install records cannot take these names and
+     * the admin operations refuse them (C15).
+     */
+    declare(names: Iterable<string>): void;
+    /** The config-declared extension names → source (see {@link declare}). */
+    declared(): Map<string, ExtensionSource>;
     /** 原子替换：登记新实例，返回被替换的旧实例（由调用方 dispose）。 */
     activate(inst: ExtensionInstance): ExtensionInstance | undefined;
     /** 摘下：返回被摘下的实例（由调用方 dispose）；不在时返回 undefined。 */
     deactivate(name: string): ExtensionInstance | undefined;
     current(name: string): ExtensionInstance | undefined;
+    /**
+     * An active extension's deployment config (validated against its manifest's schema, secrets
+     * included), passed back as `config` when the kernel calls its extension points (such as the
+     * login config of `identity-source@1`); undefined when it is not active. Never echo it in a
+     * response or a log.
+     */
+    deploymentConfig(name: string): unknown;
     all(): ExtensionInstance[];
+    /**
+     * 列出提供某能力（任意主版本）的所有插件及实现；`extensionPointName` 为能力名（不含主版本），
+     * 同一插件提供多个主版本时各占一项，由调用方按主版本选择。
+     * 每项带插件版本与部署配置摘要，供调用方做「插件升级 / 改配置即失效」的缓存键。
+     * 实时取自注册表：调用方不要缓存实现对象（插件撤销 / 升级后旧实现不再有效）。
+     */
+    list(extensionPointName: string): ExtensionPointEntry[];
+    /** 已加载插件的清单（按加载顺序，即依赖拓扑序）。 */
+    manifests(): ExtensionManifest[];
     /** 每次激活 / 摘下加一（给按版本缓存的派生视图用，如插件路由表）。 */
     revision(): number;
     /**
@@ -22,3 +67,6 @@ export declare class ExtensionRegistry {
     onChange(listener: (name: string) => void): () => void;
     private changed;
 }
+/** The one {@link ExtensionRegistry}: every domain that reads extension points imports this. */
+export declare class ExtensionRegistryModule {
+}

package/dist/extensions/registry.js

@@ -1,11 +1,46 @@
+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;
+};
+import { parseExtensionPoint, } from "@capybara-hq/plugin-sdk";
+import { Injectable, Module } from "@nestjs/common";
+import { trackCalls } from "./inflight.js";
+/** 内核消费的提供方能力：调用计入提供方实例的在途计数（撤销 / 升级时排空，C17）。 */
+const TRACKED_EXTENSION_POINTS = {
+    connector: { sessions: ["open"] },
+    sandbox: {},
+    "model-provider": {},
+    "web-search": {},
+    "web-fetch": {},
+};
 /**
- * 本进程生效的插件实例（按插件名，一名一个）。顺序 = 首次激活的顺序（宿主按依赖拓扑序加载；
- * 替换同名实例保持原位置）。只是本进程的视图：跨副本的期望状态在 PG（安装记录），由各副本自己 reconcile。
+ * The extension instances in effect in this process (by extension name, one each). One provider
+ * per process (decision R6 of the Nest kernel spec): the extension host writes it, other domains
+ * read extension points and manifests from it, never from the host. The order is the order of
+ * first activation (the host loads in dependency order; a replaced instance keeps its place). It
+ * is only this process's view: the desired state across replicas is in PG (the install records),
+ * and each replica reconciles itself.
  */
-export class ExtensionRegistry {
+let ExtensionRegistry = class ExtensionRegistry {
     instances = new Map();
     listeners = new Set();
     rev = 0;
+    /** The config-declared extension names of this process (the startup config `extensions` list). */
+    declaredNames = new Map();
+    /**
+     * Records the config-declared extensions (the host at load; before it, the start sequence for
+     * the bootstrap step; the CLI from its inspection). Install records cannot take these names and
+     * the admin operations refuse them (C15).
+     */
+    declare(names) {
+        this.declaredNames = new Map([...names].map((n) => [n, "config"]));
+    }
+    /** The config-declared extension names → source (see {@link declare}). */
+    declared() {
+        return new Map(this.declaredNames);
+    }
     /** 原子替换：登记新实例，返回被替换的旧实例（由调用方 dispose）。 */
     activate(inst) {
         const old = this.instances.get(inst.name);
@@ -25,9 +60,50 @@ export class ExtensionRegistry {
     current(name) {
         return this.instances.get(name);
     }
+    /**
+     * An active extension's deployment config (validated against its manifest's schema, secrets
+     * included), passed back as `config` when the kernel calls its extension points (such as the
+     * login config of `identity-source@1`); undefined when it is not active. Never echo it in a
+     * response or a log.
+     */
+    deploymentConfig(name) {
+        return this.instances.get(name)?.config;
+    }
     all() {
         return [...this.instances.values()];
     }
+    /**
+     * 列出提供某能力（任意主版本）的所有插件及实现；`extensionPointName` 为能力名（不含主版本），
+     * 同一插件提供多个主版本时各占一项，由调用方按主版本选择。
+     * 每项带插件版本与部署配置摘要，供调用方做「插件升级 / 改配置即失效」的缓存键。
+     * 实时取自注册表：调用方不要缓存实现对象（插件撤销 / 升级后旧实现不再有效）。
+     */
+    list(extensionPointName) {
+        const out = [];
+        const tracked = TRACKED_EXTENSION_POINTS[extensionPointName];
+        for (const i of this.instances.values()) {
+            for (const [cap, impl] of i.provided) {
+                if (parseExtensionPoint(cap).name === extensionPointName) {
+                    out.push({
+                        plugin: i.name,
+                        capability: cap,
+                        // 内核消费的提供方调用计入实例在途计数：停用 / 升级时先排空、到时限中止（C17）
+                        impl: tracked && typeof impl === "object" && impl !== null
+                            ? trackCalls(impl, i.inflight, tracked)
+                            : impl,
+                        version: i.version,
+                        configHash: i.configHash,
+                        inflight: i.inflight,
+                    });
+                }
+            }
+        }
+        return out;
+    }
+    /** 已加载插件的清单（按加载顺序，即依赖拓扑序）。 */
+    manifests() {
+        return this.all().map((i) => i.manifest);
+    }
     /** 每次激活 / 摘下加一（给按版本缓存的派生视图用，如插件路由表）。 */
     revision() {
         return this.rev;
@@ -53,4 +129,15 @@ export class ExtensionRegistry {
             }
         }
     }
-}
+};
+ExtensionRegistry = __decorate([
+    Injectable()
+], ExtensionRegistry);
+export { ExtensionRegistry };
+/** The one {@link ExtensionRegistry}: every domain that reads extension points imports this. */
+let ExtensionRegistryModule = class ExtensionRegistryModule {
+};
+ExtensionRegistryModule = __decorate([
+    Module({ providers: [ExtensionRegistry], exports: [ExtensionRegistry] })
+], ExtensionRegistryModule);
+export { ExtensionRegistryModule };

package/dist/extensions/resolve.d.ts

@@ -1,7 +1,57 @@
 import { type ExtensionManifest } from "@capybara-hq/plugin-sdk";
+/**
+ * Code of the {@link ExtensionResolveError} for a single-provider extension point that more than
+ * one extension provides: nothing is missing, the extensions conflict (replica reason `conflict`).
+ */
+export declare const PROVIDER_CONFLICT = "extension.provider_conflict";
+/**
+ * The message (and replica `detail`) of a {@link PROVIDER_CONFLICT}; read back by
+ * {@link parseProviderConflict}. `unloaded`: the provider the single-provider election picked
+ * (named first) is not loaded on this replica, so nothing provides the point here.
+ */
+export declare function providerConflictMessage(extensionPoint: string, providers: string[], unloaded?: string): string;
+/**
+ * The extension point and its providers from a {@link providerConflictMessage}; null for any other
+ * text. `unprovided`: the message says the elected provider is not loaded (no running provider).
+ */
+export declare function parseProviderConflict(detail: string | null): {
+    extensionPoint: string;
+    providers: string[];
+    unprovided?: true;
+} | null;
+/**
+ * The single-provider extension points (`sandbox`, `object-store`, `secret-store`,
+ * `config-source`; `EXTENSION_POINT_CARDINALITY`) among `provides`, sorted (the lock order).
+ */
+export declare function singlePointsOf(provides: readonly string[]): string[];
+/**
+ * The single-provider election over enabled install records in `ExtensionInstalls.desired` order
+ * (the earliest enabled first): for each single-provider extension point the first record
+ * providing it wins (`owners`: point -> winner); every later one is a loser (`losers`: name -> the
+ * point it lost and the winner). A loser claims none of its points. The host loads by it; the
+ * single-provider guard names its winners, so a refusal names the provider actually running.
+ */
+export declare function electSingleProviders(desired: readonly {
+    name: string;
+    section: {
+        manifest: {
+            provides: readonly string[];
+        };
+    };
+}[]): {
+    owners: Map<string, string>;
+    losers: Map<string, {
+        extensionPoint: string;
+        winner: string;
+    }>;
+};
 /** 插件依赖解析失败（信息列出插件名与能力名）。 */
 export declare class ExtensionResolveError extends Error {
-    constructor(message: string);
+    /** Error code of the failure, when it has one. */
+    readonly code?: string | undefined;
+    constructor(message: string, 
+    /** Error code of the failure, when it has one. */
+    code?: string | undefined);
 }
 /**
  * 校验 sdk 范围、依赖满足度、单选能力唯一性与无环，返回按依赖拓扑排序后的列表（同层保持输入顺序）。

package/dist/extensions/resolve.js

@@ -1,9 +1,82 @@
-import { EXTENSION_POINT_CARDINALITY, OBJECT_STORE_EXTENSION_POINT, parseExtensionPoint, } from "@capybara-hq/plugin-sdk";
+import { EXTENSION_POINT_CARDINALITY, EXTENSION_POINTS, OBJECT_STORE_EXTENSION_POINT, parseExtensionPoint, } from "@capybara-hq/plugin-sdk";
 import semver from "semver";
+/**
+ * Code of the {@link ExtensionResolveError} for a single-provider extension point that more than
+ * one extension provides: nothing is missing, the extensions conflict (replica reason `conflict`).
+ */
+export const PROVIDER_CONFLICT = "extension.provider_conflict";
+const CONFLICT_RE = /^extension point (\S+) is single-provider but provided by: (.+?)(; \S+ is not loaded, so \S+ has no running provider)?$/;
+/**
+ * The message (and replica `detail`) of a {@link PROVIDER_CONFLICT}; read back by
+ * {@link parseProviderConflict}. `unloaded`: the provider the single-provider election picked
+ * (named first) is not loaded on this replica, so nothing provides the point here.
+ */
+export function providerConflictMessage(extensionPoint, providers, unloaded) {
+    const base = `extension point ${extensionPoint} is single-provider but provided by: ${providers.join(", ")}`;
+    return unloaded === undefined
+        ? base
+        : `${base}; ${unloaded} is not loaded, so ${extensionPoint} has no running provider`;
+}
+/**
+ * The extension point and its providers from a {@link providerConflictMessage}; null for any other
+ * text. `unprovided`: the message says the elected provider is not loaded (no running provider).
+ */
+export function parseProviderConflict(detail) {
+    const m = detail === null ? null : CONFLICT_RE.exec(detail);
+    if (!m)
+        return null;
+    return {
+        extensionPoint: m[1],
+        providers: m[2].split(", "),
+        ...(m[3] !== undefined && { unprovided: true }),
+    };
+}
+/**
+ * The single-provider extension points (`sandbox`, `object-store`, `secret-store`,
+ * `config-source`; `EXTENSION_POINT_CARDINALITY`) among `provides`, sorted (the lock order).
+ */
+export function singlePointsOf(provides) {
+    return [
+        ...new Set(provides.filter((ref) => {
+            try {
+                return EXTENSION_POINT_CARDINALITY[parseExtensionPoint(ref).name] === "single";
+            }
+            catch {
+                return false;
+            }
+        })),
+    ].sort();
+}
+/**
+ * The single-provider election over enabled install records in `ExtensionInstalls.desired` order
+ * (the earliest enabled first): for each single-provider extension point the first record
+ * providing it wins (`owners`: point -> winner); every later one is a loser (`losers`: name -> the
+ * point it lost and the winner). A loser claims none of its points. The host loads by it; the
+ * single-provider guard names its winners, so a refusal names the provider actually running.
+ */
+export function electSingleProviders(desired) {
+    const owners = new Map();
+    const losers = new Map();
+    for (const d of desired) {
+        const points = singlePointsOf(d.section.manifest.provides);
+        const lost = points.find((p) => owners.has(p));
+        if (lost !== undefined) {
+            losers.set(d.name, { extensionPoint: lost, winner: owners.get(lost) });
+            continue;
+        }
+        for (const p of points)
+            owners.set(p, d.name);
+    }
+    return { owners, losers };
+}
 /** 插件依赖解析失败（信息列出插件名与能力名）。 */
 export class ExtensionResolveError extends Error {
-    constructor(message) {
+    code;
+    constructor(message, 
+    /** Error code of the failure, when it has one. */
+    code) {
         super(message);
+        this.code = code;
         this.name = "ExtensionResolveError";
     }
 }
@@ -23,6 +96,15 @@ export function resolveExtensions(manifests, sdkVersion) {
             throw new ExtensionResolveError(`plugin ${m.name}: sdk range "${m.sdk}" is not satisfied by SDK_VERSION ${sdkVersion}`);
         }
     }
+    for (const m of manifests) {
+        for (const ref of m.provides) {
+            const { name, major } = parseExtensionPoint(ref);
+            const majors = EXTENSION_POINTS[name]?.majors;
+            if (majors && !majors.includes(major)) {
+                throw new ExtensionResolveError(`Plugin ${m.name} provides ${ref}, which this kernel no longer supports; upgrade it to a version that provides ${name}@${Math.max(...majors)}.`, "extension.unsupported_extension_point");
+            }
+        }
+    }
     const providers = new Map();
     for (const m of manifests) {
         for (const cap of m.provides)
@@ -31,7 +113,7 @@ export function resolveExtensions(manifests, sdkVersion) {
     for (const [cap, list] of providers) {
         if (EXTENSION_POINT_CARDINALITY[parseExtensionPoint(cap).name] === "single" &&
             list.length > 1) {
-            throw new ExtensionResolveError(`extension point ${cap} is single-provider but provided by: ${list.map((p) => p.name).join(", ")}`);
+            throw new ExtensionResolveError(providerConflictMessage(cap, list.map((p) => p.name)), PROVIDER_CONFLICT);
         }
     }
     for (const m of manifests) {

package/dist/extensions/single-provider.d.ts

@@ -0,0 +1,92 @@
+import type { LocalizedName } from "@capybara-hq/plugin-sdk";
+import { ApiError } from "../errors.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { ExtensionDisplayNames } from "./display-name.js";
+import { SingleProviderLock } from "./locks.js";
+import { ExtensionRegistry } from "./registry.js";
+/** The error code of an enable refused because another extension provides the same single point. */
+export declare const SINGLE_PROVIDER_ENABLED = "extension.single_provider_enabled";
+/**
+ * The error code of an enable refused because a required bootstrap plugin provides the same single
+ * point: a required plugin cannot be disabled, so nothing can replace it. A code of its own (not
+ * {@link SINGLE_PROVIDER_ENABLED} with a flag) because the next step differs: there is none, while
+ * {@link SINGLE_PROVIDER_ENABLED} says to disable the other one first; the web, the CLI and the
+ * Platform tool key their text on the code.
+ */
+export declare const SINGLE_PROVIDER_REQUIRED = "extension.single_provider_required";
+/** Either single-provider refusal code. */
+export declare const isSingleProviderCode: (code: string) => boolean;
+/**
+ * What keeps an extension from being enabled: the point and the enabled extension providing it
+ * (`required`: a required bootstrap plugin, which cannot be disabled).
+ */
+export interface SingleProviderBlock {
+    extensionPoint: string;
+    enabled: {
+        name: string;
+        displayName: LocalizedName | null;
+    };
+    required?: true;
+}
+/**
+ * An extension left disabled by an install or import path because a single-provider point it
+ * provides is taken: the refusal's code and message and the block (as in the 409's details).
+ */
+export interface SingleProviderNote {
+    code: string;
+    message: string;
+    singleProvider: SingleProviderBlock;
+}
+/** The English message of the refusal ({@link SINGLE_PROVIDER_ENABLED} / {@link SINGLE_PROVIDER_REQUIRED}). */
+export declare function singleProviderMessage(block: SingleProviderBlock, name: string, displayName: LocalizedName | null): string;
+/** The 409 refusal, details `[{ extensionPoint, enabled, required? }]`. */
+export declare function singleProviderError(block: SingleProviderBlock, name: string, displayName: LocalizedName | null): ApiError;
+/** The note of a refusal ({@link singleProviderError}) an install path reports instead of failing. */
+export declare function singleProviderNote(refusal: ApiError): SingleProviderNote;
+/**
+ * The single-provider rule of the deployment (maintainer decision 2026-11-08): a single-provider
+ * extension point has at most one enabled provider. Enabling a second one is refused (409
+ * {@link SINGLE_PROVIDER_ENABLED}); to switch, the super admin disables the current one first. A
+ * required bootstrap plugin cannot be disabled, so a point it holds cannot change provider (409
+ * {@link SINGLE_PROVIDER_REQUIRED}). An upgrade that newly provides a held point installs the new
+ * version disabled (`ExtensionAdminOps.install`, `leftDisabled`).
+ * Every path that sets an install record's desired state to `enabled` goes through
+ * `ExtensionAdminOps.enable`, which calls {@link assertFree} in its transaction; install and import
+ * paths that would enable call it through `enableUnlessOccupied` and leave the extension disabled
+ * when the point is taken. Stateless.
+ */
+export declare class SingleProviderGuard {
+    private readonly kdb;
+    readonly txHost: TransactionHost;
+    private readonly pointLock;
+    /** Config-declared extensions loaded on this replica (empty in the CLI: install records only). */
+    private readonly registry;
+    private readonly displayNames;
+    constructor(kdb: KernelDb, txHost: TransactionHost, pointLock: SingleProviderLock, 
+    /** Config-declared extensions loaded on this replica (empty in the CLI: install records only). */
+    registry: ExtensionRegistry, displayNames: ExtensionDisplayNames);
+    /**
+     * The first single-provider point of `provides` that an extension other than `name` holds, or
+     * null: a config-declared extension loaded here, else the winner of the single-provider election
+     * ({@link electSingleProviders}, the host's) over the other enabled install records, so the
+     * extension named is the one actually loaded (a loser of the election holds nothing). A read
+     * without locks: views and prechecks use it; the enable itself uses {@link assertFree}.
+     */
+    occupant(name: string, provides: readonly string[]): Promise<SingleProviderBlock | null>;
+    /**
+     * The occupant ({@link occupant}) of `name`'s single-provider points among `provides`, read
+     * after taking one transaction-scoped lock per point ({@link SingleProviderLock}, sorted) in the
+     * caller's transaction (after its install lock), so two concurrent writes enabling providers of
+     * one point run one after the other and the second sees the first's committed state.
+     */
+    lockedOccupant(name: string, provides: readonly string[]): Promise<SingleProviderBlock | null>;
+    /** The note of `name` left disabled by `block` (the refusal's code, message and block). */
+    note(block: SingleProviderBlock, name: string): Promise<SingleProviderNote>;
+    /**
+     * Refuses (409 {@link SINGLE_PROVIDER_ENABLED}, or {@link SINGLE_PROVIDER_REQUIRED} when the
+     * holder is a required plugin) to enable `name` while another extension holds one of its
+     * single-provider points; under the points' locks ({@link lockedOccupant}).
+     */
+    assertFree(name: string, provides: readonly string[]): Promise<void>;
+}

package/dist/extensions/single-provider.js

@@ -0,0 +1,180 @@
+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 { Inject, Injectable } from "@nestjs/common";
+import { sql } from "kysely";
+import { ApiError } from "../errors.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 { ExtensionDisplayNames } from "./display-name.js";
+import { SingleProviderLock } from "./locks.js";
+import { ExtensionRegistry } from "./registry.js";
+import { electSingleProviders, singlePointsOf } from "./resolve.js";
+/** The error code of an enable refused because another extension provides the same single point. */
+export const SINGLE_PROVIDER_ENABLED = "extension.single_provider_enabled";
+/**
+ * The error code of an enable refused because a required bootstrap plugin provides the same single
+ * point: a required plugin cannot be disabled, so nothing can replace it. A code of its own (not
+ * {@link SINGLE_PROVIDER_ENABLED} with a flag) because the next step differs: there is none, while
+ * {@link SINGLE_PROVIDER_ENABLED} says to disable the other one first; the web, the CLI and the
+ * Platform tool key their text on the code.
+ */
+export const SINGLE_PROVIDER_REQUIRED = "extension.single_provider_required";
+/** Either single-provider refusal code. */
+export const isSingleProviderCode = (code) => code === SINGLE_PROVIDER_ENABLED || code === SINGLE_PROVIDER_REQUIRED;
+/** The English message of the refusal ({@link SINGLE_PROVIDER_ENABLED} / {@link SINGLE_PROVIDER_REQUIRED}). */
+export function singleProviderMessage(block, name, displayName) {
+    const other = block.enabled.displayName?.en ?? block.enabled.name;
+    if (block.required === true) {
+        return `${block.extensionPoint} is provided by the required plugin ${other}; it can't be replaced`;
+    }
+    const self = displayName?.en ?? name;
+    return `Only one extension may provide ${block.extensionPoint}; disable ${other} first, then enable ${self}`;
+}
+/** The 409 refusal, details `[{ extensionPoint, enabled, required? }]`. */
+export function singleProviderError(block, name, displayName) {
+    return new ApiError(block.required === true ? SINGLE_PROVIDER_REQUIRED : SINGLE_PROVIDER_ENABLED, singleProviderMessage(block, name, displayName), [block]);
+}
+/** The note of a refusal ({@link singleProviderError}) an install path reports instead of failing. */
+export function singleProviderNote(refusal) {
+    return {
+        code: refusal.code,
+        message: refusal.message,
+        singleProvider: refusal.details?.[0],
+    };
+}
+/**
+ * The single-provider rule of the deployment (maintainer decision 2026-11-08): a single-provider
+ * extension point has at most one enabled provider. Enabling a second one is refused (409
+ * {@link SINGLE_PROVIDER_ENABLED}); to switch, the super admin disables the current one first. A
+ * required bootstrap plugin cannot be disabled, so a point it holds cannot change provider (409
+ * {@link SINGLE_PROVIDER_REQUIRED}). An upgrade that newly provides a held point installs the new
+ * version disabled (`ExtensionAdminOps.install`, `leftDisabled`).
+ * Every path that sets an install record's desired state to `enabled` goes through
+ * `ExtensionAdminOps.enable`, which calls {@link assertFree} in its transaction; install and import
+ * paths that would enable call it through `enableUnlessOccupied` and leave the extension disabled
+ * when the point is taken. Stateless.
+ */
+let SingleProviderGuard = class SingleProviderGuard {
+    kdb;
+    txHost;
+    pointLock;
+    registry;
+    displayNames;
+    constructor(kdb, txHost, pointLock, 
+    /** Config-declared extensions loaded on this replica (empty in the CLI: install records only). */
+    registry, displayNames) {
+        this.kdb = kdb;
+        this.txHost = txHost;
+        this.pointLock = pointLock;
+        this.registry = registry;
+        this.displayNames = displayNames;
+    }
+    /**
+     * The first single-provider point of `provides` that an extension other than `name` holds, or
+     * null: a config-declared extension loaded here, else the winner of the single-provider election
+     * ({@link electSingleProviders}, the host's) over the other enabled install records, so the
+     * extension named is the one actually loaded (a loser of the election holds nothing). A read
+     * without locks: views and prechecks use it; the enable itself uses {@link assertFree}.
+     */
+    async occupant(name, provides) {
+        const points = singlePointsOf(provides);
+        if (points.length === 0)
+            return null;
+        const declared = this.registry
+            .all()
+            .filter((i) => i.source === "config" && i.name !== name)
+            .map((i) => ({ name: i.name, provides: i.manifest.provides }));
+        const declaredNames = new Set(this.registry.declared().keys());
+        const rows = await this.kdb.db
+            .selectFrom("extension_installs")
+            .innerJoin("extension_packages", "extension_packages.sha256", "extension_installs.sha256")
+            .select([
+            "extension_installs.name",
+            "extension_installs.required",
+            "extension_packages.section",
+        ])
+            .where("extension_installs.desired_state", "=", "enabled")
+            .where("extension_installs.name", "<>", name)
+            // ExtensionInstalls.desired's order: the election's
+            .orderBy(sql `extension_installs.enabled_at ASC NULLS LAST`)
+            .orderBy("extension_installs.installed_at")
+            .orderBy("extension_installs.name")
+            .execute();
+        const installs = rows
+            .filter((r) => !declaredNames.has(r.name))
+            .map((r) => ({
+            name: r.name,
+            required: r.required,
+            section: {
+                manifest: {
+                    provides: r.section?.manifest?.provides ?? [],
+                },
+            },
+        }));
+        const { owners } = electSingleProviders(installs);
+        for (const extensionPoint of points) {
+            const config = declared.find((o) => o.provides.includes(extensionPoint));
+            const holder = config?.name ?? owners.get(extensionPoint);
+            if (holder === undefined)
+                continue;
+            const required = config === undefined && installs.find((i) => i.name === holder)?.required;
+            return {
+                extensionPoint,
+                enabled: { name: holder, displayName: await this.displayNames.get(holder) },
+                ...(required === true && { required: true }),
+            };
+        }
+        return null;
+    }
+    /**
+     * The occupant ({@link occupant}) of `name`'s single-provider points among `provides`, read
+     * after taking one transaction-scoped lock per point ({@link SingleProviderLock}, sorted) in the
+     * caller's transaction (after its install lock), so two concurrent writes enabling providers of
+     * one point run one after the other and the second sees the first's committed state.
+     */
+    async lockedOccupant(name, provides) {
+        const points = singlePointsOf(provides);
+        if (points.length === 0)
+            return null;
+        for (const p of points)
+            await this.pointLock.lock(p);
+        return this.occupant(name, points);
+    }
+    /** The note of `name` left disabled by `block` (the refusal's code, message and block). */
+    async note(block, name) {
+        return singleProviderNote(singleProviderError(block, name, await this.displayNames.get(name)));
+    }
+    /**
+     * Refuses (409 {@link SINGLE_PROVIDER_ENABLED}, or {@link SINGLE_PROVIDER_REQUIRED} when the
+     * holder is a required plugin) to enable `name` while another extension holds one of its
+     * single-provider points; under the points' locks ({@link lockedOccupant}).
+     */
+    async assertFree(name, provides) {
+        const block = await this.lockedOccupant(name, provides);
+        if (block)
+            throw singleProviderError(block, name, await this.displayNames.get(name));
+    }
+};
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], SingleProviderGuard.prototype, "lockedOccupant", null);
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], SingleProviderGuard.prototype, "assertFree", null);
+SingleProviderGuard = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(TransactionHost)),
+    __param(2, Inject(SingleProviderLock)),
+    __param(3, Inject(ExtensionRegistry)),
+    __param(4, Inject(ExtensionDisplayNames))
+], SingleProviderGuard);
+export { SingleProviderGuard };