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

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 };

package/dist/extensions/sources.d.ts

@@ -14,8 +14,13 @@ import type { KernelLogger } from "../log.js";
 export type ExtensionSource = "config" | "install";
 /** 副本（进程）id：`<hostname>-<pid>-<6 位随机>`，每个进程唯一（`http.replicaId` 可能跨重启不变或多副本相同）。 */
 export declare function newReplicaId(): string;
-/** Why `extension_replica_status.state = pending` (F-I: the admin view derives pending_config and so on from it). */
-export type PendingReason = "config" | "approval" | "migration" | "dependency";
+/**
+ * Why `extension_replica_status.state = pending` (F-I: the admin view derives pending_config and so
+ * on from it). `dependency`: an extension point it requires has no provider; `conflict`: it
+ * provides a single-provider extension point another loaded extension already provides (it loads
+ * once that one is disabled or uninstalled, no restart).
+ */
+export type PendingReason = "config" | "approval" | "migration" | "dependency" | "conflict";
 /** One load result (written to `extension_replica_status`). */
 export interface ExtensionLoadStatus {
     plugin: string;
@@ -31,6 +36,12 @@ export interface ExtensionLoadStatus {
      * 省略视同 null。
      */
     servingVersion?: string | null;
+    /**
+     * The package sha256 this replica serves for the plugin: the row's own `sha256` when `loaded`,
+     * the older package still running beside a failed / pending version, null when none runs.
+     * Omitted counts as null.
+     */
+    servingSha256?: string | null;
 }
 /** This replica's extension load status (PG `extension_replica_status`; each replica writes only its own rows). */
 export declare class ReplicaStatusStore {

package/dist/extensions/sources.js

@@ -55,6 +55,7 @@ let ReplicaStatusStore = class ReplicaStatusStore {
             reason: s.reason,
             detail: s.detail === null ? null : this.cleanDetail(s.detail),
             serving_version: s.servingVersion ?? null,
+            serving_sha256: s.servingSha256 ?? null,
             http_replica_id: this.httpReplicaId ?? null,
             heartbeat_at: sql `now()`,
         };
@@ -69,6 +70,7 @@ let ReplicaStatusStore = class ReplicaStatusStore {
             reason: values.reason,
             detail: values.detail,
             serving_version: values.serving_version,
+            serving_sha256: values.serving_sha256,
             http_replica_id: values.http_replica_id,
             heartbeat_at: values.heartbeat_at,
         }))

package/dist/extensions/state.module.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The extension state the model domain reads below the host: the install records with their
+ * packages and approvals, and each extension's effective config per org. Apart from
+ * `ExtensionsModule` so the model provider registry (and the `ctx.models` broker the host injects)
+ * can depend on it without a module cycle (writing-kernel-api: a cycle is cut by moving the shared
+ * part into its own provider both sides inject). `ExtensionsModule` re-exports it.
+ */
+export declare class ExtensionStateModule {
+}

package/dist/extensions/state.module.js

@@ -0,0 +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 { Module } from "@nestjs/common";
+import { ClientModule } from "../client/client.module.js";
+import { SuperAdminLockModule } from "../identity/super-admin.js";
+import { OrgLockModule } from "../orgs/org-lock.js";
+import { StorageModule } from "../storage/storage.module.js";
+import { ExtensionApprovals } from "./approvals.js";
+import { ExtensionBlobs } from "./blobs.js";
+import { EffectiveConfigs } from "./effective-config.js";
+import { ExtensionInstalls } from "./installs.js";
+import { ExtensionRegistryModule } from "./registry.js";
+/**
+ * The extension state the model domain reads below the host: the install records with their
+ * packages and approvals, and each extension's effective config per org. Apart from
+ * `ExtensionsModule` so the model provider registry (and the `ctx.models` broker the host injects)
+ * can depend on it without a module cycle (writing-kernel-api: a cycle is cut by moving the shared
+ * part into its own provider both sides inject). `ExtensionsModule` re-exports it.
+ */
+let ExtensionStateModule = class ExtensionStateModule {
+};
+ExtensionStateModule = __decorate([
+    Module({
+        imports: [
+            ExtensionRegistryModule,
+            SuperAdminLockModule,
+            OrgLockModule,
+            StorageModule,
+            // a package with client code stores its client build (`ExtensionBlobs`)
+            ClientModule,
+        ],
+        providers: [ExtensionApprovals, ExtensionBlobs, ExtensionInstalls, EffectiveConfigs],
+        exports: [
+            ExtensionRegistryModule,
+            ExtensionApprovals,
+            ExtensionBlobs,
+            ExtensionInstalls,
+            EffectiveConfigs,
+        ],
+    })
+], ExtensionStateModule);
+export { ExtensionStateModule };

package/dist/extensions/unavailable.d.ts

@@ -0,0 +1,50 @@
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { type DeploymentExtensionStatus } from "./permission-view.js";
+import { ExtensionRegistry } from "./registry.js";
+/**
+ * Why an extension cannot be used right now (Platform tool spec §14.2 problem 1, §14.5 item 4):
+ * - `not_deployed`: no install record on the platform (a catalog plugin whose extension was never
+ *   installed);
+ * - `needs_deployment_config`: installed, its deployment config is missing or invalid;
+ * - `pending_approval`: its permissions wait for the super admin's approval;
+ * - `pending_migration` / `loading`: the platform is still bringing it up;
+ * - `dependency`: an extension point it requires has no loaded provider;
+ * - `conflict`: it provides a single-provider extension point another loaded extension provides;
+ * - `failed`: it failed to load (or its package cannot be read);
+ * - `deployment_disabled`: the super admin disabled it on the platform.
+ * State only: never a config value or field name.
+ */
+export type ExtensionUnavailableReason = "not_deployed" | "needs_deployment_config" | "pending_approval" | "pending_migration" | "loading" | "dependency" | "conflict" | "failed" | "deployment_disabled";
+/** The deployment status of an extension that is not loaded, and the reason it shows for it. */
+export interface ExtensionUnavailability {
+    /** Null when it has no install record (`not_deployed`). */
+    status: DeploymentExtensionStatus | null;
+    reason: ExtensionUnavailableReason;
+}
+/** The reason an org or the Platform tool shows for a deployment status of a not-loaded extension. */
+export declare function unavailableReason(status: DeploymentExtensionStatus): ExtensionUnavailableReason;
+/**
+ * The state of extensions that are not loaded on this replica, derived like the admin console's
+ * status ({@link deriveExtensionStatus}) from the install record and the replicas' recent reports,
+ * without reading packages: a pending approval and a pending config come from the replicas' rows
+ * (`pending` with reason `approval` / `config`). Reads PG on every call (no in-process state).
+ *
+ * Its inputs differ slightly from the admin view's (`ExtensionAdmin`): there `pendingApproval`
+ * compares the package's permission set with the snapshot and `configValid` checks the deployment
+ * config, while here both come from what the replicas last reported. They agree once a replica
+ * has tried the current package; until then this view says `loading` where the admin view may
+ * already say `pending_approval` or `pending_config`.
+ *
+ * Which extensions count as loaded is this replica's registry: replica-local and transient. During
+ * a rollout, or right after an enable or upgrade, one replica may answer `loading` while another
+ * has it loaded; the next call (or the next reconcile) converges.
+ */
+export declare class ExtensionAvailability {
+    private readonly kdb;
+    private readonly config;
+    private readonly registry;
+    constructor(kdb: KernelDb, config: KernelConfigService, registry: ExtensionRegistry);
+    /** For each of `names` not loaded on this replica: its status and reason (loaded ones absent). */
+    unavailable(names: readonly string[]): Promise<Map<string, ExtensionUnavailability>>;
+}