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

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

@@ -0,0 +1,133 @@
+import type { z } from "zod";
+import { type Keyring } from "../ctx/secrets.js";
+import { CacheService } from "../infra/cache/cache.service.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 type { KernelLogger } from "../log.js";
+import { type ConfigIssue } from "./config-issues.js";
+import { ExtensionInstalls } from "./installs.js";
+import { type FieldLevel } from "./org-levels.js";
+import { ExtensionRegistry } from "./registry.js";
+type Obj = Record<string, unknown>;
+/**
+ * Why an org-bound call is not made (spec A §6): the extension's effective config for the org is
+ * not valid. Model-visible as a tool's unavailable reason (English).
+ */
+export declare const NEEDS_CONFIG_REASON = "needs configuration in this organization";
+/** The kernel's own secrets namespace (`kernel` is a reserved plugin name). */
+export declare const OVERRIDE_SECRETS_NAMESPACE = "kernel";
+/**
+ * Where a copy's secret field lives in `capybara.secrets` (under the org): a namespace of its own,
+ * distinct from the org-only `plugin-config:<plugin>:<path>` (spec A §5.8).
+ */
+export declare const overrideSecretKey: (plugin: string, path: string) => string;
+/**
+ * The effective deployment config of an extension for an org (spec A §6): `ok` with the config
+ * and where its overridable fields come from, or the validation issues (paths only, no values).
+ */
+export type EffectiveConfig = {
+    ok: true;
+    config: unknown;
+    source: "platform" | "copy";
+}
+/** `notRunning`: the extension is not running on this replica (not a configuration problem). */
+ | {
+    ok: false;
+    issues: ConfigIssue[];
+    notRunning?: true;
+};
+/** An org's stored copy: its non-secret values and its secrets by field dot path. */
+export interface StoredCopy {
+    config: Obj;
+    secrets: Record<string, unknown>;
+}
+/** The secret leaf paths of a deployment schema. */
+export declare function secretLeafPaths(schema: z.ZodTypeAny): string[];
+/** The secret leaf paths under the `override` top-level keys (the secrets a copy may hold). */
+export declare function overrideSecretPaths(schema: z.ZodTypeAny, levels?: Map<string, FieldLevel>): string[];
+/**
+ * The platform's non-secret values of the `override` keys: what a new copy starts from (spec A
+ * §5.4, platform secrets never enter a copy).
+ */
+export declare function platformOverrideValues(schema: z.ZodTypeAny, platform: unknown): Obj;
+/**
+ * The deployment config an org with a copy runs with, before validation (spec A §5.4): the
+ * platform's values of the hidden and read-only keys, and for each `override` key the copy's value
+ * (its non-secret part and its own secrets). An `override` key the copy does not hold (one that
+ * became overridable after the copy was made) takes the platform's value with every secret leaf
+ * removed: a copy never falls back to a platform secret, required or not. Copy values of keys that
+ * are no longer `override` are ignored.
+ */
+export declare function mergeCopy(schema: z.ZodTypeAny, platform: unknown, copy: StoredCopy): Obj;
+/**
+ * The effective extension config of an org (spec A §5.3, §5.4, §6): the platform's deployment
+ * config while the org follows it, or the platform's values with the org's copy applied to the
+ * overridable fields. Every org-bound call takes its config from here.
+ *
+ * Following orgs get this replica's running config (`ctx.config`), so a platform change reaches
+ * them as soon as the instance has it. For a copy, the platform's raw (unparsed) deployment config
+ * and the copy's raw values are merged and parsed once, so a schema transform runs exactly once.
+ * The org half (the copy row and its secrets) is cached in Redis through `@Cacheable`, sealed with
+ * a key derived from the master keyring so no secret sits in Redis in clear, under a per-(org,
+ * plugin) generation token that every copy write replaces after its commit: a read that started
+ * before the write can only cache under the old token, which nobody reads any more. No
+ * in-process state.
+ *
+ * It reads the running instances from the {@link ExtensionRegistry} and the raw platform config
+ * from the install records (not through the host), so the host can inject it for its hook
+ * dispatcher.
+ */
+export declare class EffectiveConfigs {
+    private readonly kdb;
+    readonly txHost: TransactionHost;
+    readonly cacheService: CacheService;
+    private readonly keyring;
+    private readonly registry;
+    private readonly installs;
+    private readonly kernelConfig;
+    /** Secret values of a copy read here are masked in the logs. */
+    private readonly log;
+    constructor(kdb: KernelDb, txHost: TransactionHost, cacheService: CacheService, keyring: Keyring, registry: Pick<ExtensionRegistry, "current">, installs: Pick<ExtensionInstalls, "effectiveDeploymentConfig">, kernelConfig: Pick<KernelConfigService, "get">, 
+    /** Secret values of a copy read here are masked in the logs. */
+    log: KernelLogger);
+    private get db();
+    /**
+     * The config of `plugin` for work done for the platform (a `platform.page` view, UI slots spec
+     * §7): the running instance's deployment config, no org copy applies; `notRunning` when the
+     * extension is not running on this replica.
+     */
+    platform(plugin: string): EffectiveConfig;
+    /**
+     * The effective config of `plugin` for `orgId`. Following: the running platform config, `ok:
+     * false` when it leaves a required overridable field empty (the host loaded it with those
+     * fields optional, so that is the only way the full schema can refuse it). Copy: the platform's
+     * raw config with the copy applied ({@link mergeCopy}), parsed once with the full schema. An
+     * extension not running on this replica -> `ok: false`, `notRunning`, with a root issue.
+     */
+    get(orgId: string, plugin: string): Promise<EffectiveConfig>;
+    /** The org's copy (decrypted), or undefined while it follows the platform. */
+    copyOf(orgId: string, plugin: string): Promise<StoredCopy | undefined>;
+    /**
+     * Makes every cached copy of (org, plugin) unreachable: a new generation token, and the entry of
+     * the old one deleted. Call it after the write committed (`afterCommit`), never inside it.
+     */
+    invalidate(orgId: string, plugin: string): Promise<void>;
+    /** Keyed by the generation token read just before the PG read. */
+    private cachedCopy;
+    /**
+     * The copy row and its secrets from one snapshot (joins the caller's transaction, so a write
+     * sees what it just wrote).
+     */
+    private readCopy;
+    /**
+     * The number of orgs (not deleted) where the extension is on and has no valid effective config
+     * (spec A §5.4a). Following orgs share the platform's result; each copy is checked on its own.
+     * 0 when the extension is not running on this replica.
+     */
+    countNeedingConfig(plugin: string): Promise<number>;
+    private cacheKey;
+    private seal;
+    private open;
+}
+export {};

package/dist/extensions/effective-config.js

@@ -0,0 +1,379 @@
+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 { createCipheriv, createDecipheriv, randomBytes, randomUUID } from "node:crypto";
+import { Inject, Injectable } from "@nestjs/common";
+import { configFields } from "../config/fields.js";
+import { createSecrets } from "../ctx/secrets.js";
+import { CacheService } from "../infra/cache/cache.service.js";
+import { Cacheable } from "../infra/cache/cacheable.decorator.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { currentStore, TransactionHost } from "../infra/database/transaction-host.js";
+import { Transactional } from "../infra/database/transactional.decorator.js";
+import { KERNEL_LOGGER, KEYRING } from "../infra/tokens.js";
+import { toIssues } from "./config-issues.js";
+import { deleteDeep, isObj, setDeep } from "./deployment-config-store.js";
+import { enabledExtensionsByOrg } from "./enabled.js";
+import { ExtensionInstalls } from "./installs.js";
+import { fieldLevels, missingOverridable } from "./org-levels.js";
+import { ExtensionRegistry } from "./registry.js";
+/**
+ * Why an org-bound call is not made (spec A §6): the extension's effective config for the org is
+ * not valid. Model-visible as a tool's unavailable reason (English).
+ */
+export const NEEDS_CONFIG_REASON = "needs configuration in this organization";
+/** The kernel's own secrets namespace (`kernel` is a reserved plugin name). */
+export const OVERRIDE_SECRETS_NAMESPACE = "kernel";
+const OVERRIDE_KEY_PREFIX = "plugin-override:";
+/**
+ * Where a copy's secret field lives in `capybara.secrets` (under the org): a namespace of its own,
+ * distinct from the org-only `plugin-config:<plugin>:<path>` (spec A §5.8).
+ */
+export const overrideSecretKey = (plugin, path) => `${OVERRIDE_KEY_PREFIX}${plugin}:${path}`;
+const notRunning = () => ({
+    ok: false,
+    notRunning: true,
+    issues: [{ path: "", segments: [], message: "the extension is not running" }],
+});
+/** The secret leaf paths of a deployment schema. */
+export function secretLeafPaths(schema) {
+    return configFields(schema)
+        .filter((f) => f.meta?.secret === true)
+        .map((f) => f.path);
+}
+const under = (path, key) => path === key || path.startsWith(`${key}.`);
+/** The secret leaf paths under the `override` top-level keys (the secrets a copy may hold). */
+export function overrideSecretPaths(schema, levels = fieldLevels(schema)) {
+    const keys = [...levels].filter(([, l]) => l === "override").map(([k]) => k);
+    return secretLeafPaths(schema).filter((p) => keys.some((k) => under(p, k)));
+}
+/**
+ * The platform's non-secret values of the `override` keys: what a new copy starts from (spec A
+ * §5.4, platform secrets never enter a copy).
+ */
+export function platformOverrideValues(schema, platform) {
+    const levels = fieldLevels(schema);
+    const secrets = secretLeafPaths(schema);
+    const out = {};
+    for (const [key, level] of levels) {
+        if (level !== "override")
+            continue;
+        const v = isObj(platform) ? platform[key] : undefined;
+        if (v === undefined)
+            continue;
+        const tmp = { [key]: structuredClone(v) };
+        for (const p of secrets)
+            if (under(p, key))
+                deleteDeep(tmp, p);
+        if (tmp[key] !== undefined)
+            out[key] = tmp[key];
+    }
+    return out;
+}
+/**
+ * The deployment config an org with a copy runs with, before validation (spec A §5.4): the
+ * platform's values of the hidden and read-only keys, and for each `override` key the copy's value
+ * (its non-secret part and its own secrets). An `override` key the copy does not hold (one that
+ * became overridable after the copy was made) takes the platform's value with every secret leaf
+ * removed: a copy never falls back to a platform secret, required or not. Copy values of keys that
+ * are no longer `override` are ignored.
+ */
+export function mergeCopy(schema, platform, copy) {
+    const levels = fieldLevels(schema);
+    const secrets = secretLeafPaths(schema);
+    const plat = isObj(platform) ? platform : {};
+    const out = {};
+    for (const [key, level] of levels) {
+        if (level !== "override") {
+            if (plat[key] !== undefined)
+                out[key] = structuredClone(plat[key]);
+            continue;
+        }
+        const own = {};
+        if (copy.config[key] !== undefined)
+            own[key] = structuredClone(copy.config[key]);
+        const keySecrets = secrets.filter((p) => under(p, key));
+        // a secret never comes from the non-secret part, even a hand-edited one
+        for (const p of keySecrets)
+            deleteDeep(own, p);
+        for (const p of keySecrets) {
+            const v = copy.secrets[p];
+            if (v !== undefined)
+                setDeep(own, p, structuredClone(v));
+        }
+        if (own[key] !== undefined) {
+            out[key] = own[key];
+            continue;
+        }
+        if (plat[key] === undefined)
+            continue;
+        const fallback = { [key]: structuredClone(plat[key]) };
+        for (const p of keySecrets)
+            deleteDeep(fallback, p);
+        if (fallback[key] !== undefined)
+            out[key] = fallback[key];
+    }
+    return out;
+}
+const CACHE_KEY_INFO = "org-override-cache";
+/** Lifetime of a cached copy (seconds). */
+const COPY_TTL = 300;
+/**
+ * Lifetime of a generation token (seconds): far longer than {@link COPY_TTL}, so a copy cached
+ * under the token-less generation `"0"` has expired long before a token lapses back to `"0"`.
+ */
+const GENERATION_TTL = 86_400;
+/** The Redis key of the cache generation of (org, plugin); a copy write replaces it. */
+const generationKey = (orgId, plugin) => `effective-config-gen:${orgId}:${plugin}`;
+const IV_LEN = 12;
+const TAG_LEN = 16;
+/**
+ * The effective extension config of an org (spec A §5.3, §5.4, §6): the platform's deployment
+ * config while the org follows it, or the platform's values with the org's copy applied to the
+ * overridable fields. Every org-bound call takes its config from here.
+ *
+ * Following orgs get this replica's running config (`ctx.config`), so a platform change reaches
+ * them as soon as the instance has it. For a copy, the platform's raw (unparsed) deployment config
+ * and the copy's raw values are merged and parsed once, so a schema transform runs exactly once.
+ * The org half (the copy row and its secrets) is cached in Redis through `@Cacheable`, sealed with
+ * a key derived from the master keyring so no secret sits in Redis in clear, under a per-(org,
+ * plugin) generation token that every copy write replaces after its commit: a read that started
+ * before the write can only cache under the old token, which nobody reads any more. No
+ * in-process state.
+ *
+ * It reads the running instances from the {@link ExtensionRegistry} and the raw platform config
+ * from the install records (not through the host), so the host can inject it for its hook
+ * dispatcher.
+ */
+let EffectiveConfigs = class EffectiveConfigs {
+    kdb;
+    txHost;
+    cacheService;
+    keyring;
+    registry;
+    installs;
+    kernelConfig;
+    log;
+    constructor(kdb, txHost, cacheService, keyring, registry, installs, kernelConfig, 
+    /** Secret values of a copy read here are masked in the logs. */
+    log) {
+        this.kdb = kdb;
+        this.txHost = txHost;
+        this.cacheService = cacheService;
+        this.keyring = keyring;
+        this.registry = registry;
+        this.installs = installs;
+        this.kernelConfig = kernelConfig;
+        this.log = log;
+    }
+    get db() {
+        return this.kdb.db;
+    }
+    /**
+     * The config of `plugin` for work done for the platform (a `platform.page` view, UI slots spec
+     * §7): the running instance's deployment config, no org copy applies; `notRunning` when the
+     * extension is not running on this replica.
+     */
+    platform(plugin) {
+        const inst = this.registry.current(plugin);
+        if (!inst)
+            return notRunning();
+        return { ok: true, config: inst.config, source: "platform" };
+    }
+    /**
+     * The effective config of `plugin` for `orgId`. Following: the running platform config, `ok:
+     * false` when it leaves a required overridable field empty (the host loaded it with those
+     * fields optional, so that is the only way the full schema can refuse it). Copy: the platform's
+     * raw config with the copy applied ({@link mergeCopy}), parsed once with the full schema. An
+     * extension not running on this replica -> `ok: false`, `notRunning`, with a root issue.
+     */
+    async get(orgId, plugin) {
+        const inst = this.registry.current(plugin);
+        if (!inst)
+            return notRunning();
+        const schema = inst.manifest.config?.deployment;
+        if (!schema)
+            return { ok: true, config: inst.config, source: "platform" };
+        const levels = fieldLevels(schema);
+        // without an overridable field there is no copy to apply, and the loaded config is complete
+        if (![...levels.values()].includes("override")) {
+            return { ok: true, config: inst.config, source: "platform" };
+        }
+        const copy = await this.copyOf(orgId, plugin);
+        if (!copy) {
+            const missing = missingOverridable(schema, inst.config);
+            if (missing.length === 0)
+                return { ok: true, config: inst.config, source: "platform" };
+            return {
+                ok: false,
+                issues: missing.map((path) => ({
+                    path,
+                    segments: [path],
+                    message: "required: the platform leaves it empty",
+                })),
+            };
+        }
+        const values = Object.values(copy.secrets);
+        if (values.length > 0)
+            this.log.addOrgSecrets(values);
+        // the host's raw read (ExtensionHost.rawDeploymentConfig): startup config plus the PG values
+        const raw = await this.installs.effectiveDeploymentConfig(plugin, this.kernelConfig.get().extensionConfig[plugin], schema);
+        // the full schema, object-level refinements included: zod runs them only once every field
+        // parsed, so a refinement never sees an absent required field
+        const r = schema.safeParse(mergeCopy(schema, raw, copy));
+        return r.success
+            ? { ok: true, config: r.data, source: "copy" }
+            : { ok: false, issues: toIssues(r.error) };
+    }
+    /** The org's copy (decrypted), or undefined while it follows the platform. */
+    async copyOf(orgId, plugin) {
+        // inside a transaction: no Redis, read what the transaction sees
+        if (currentStore())
+            return (await this.readCopy(orgId, plugin)) ?? undefined;
+        const gen = (await this.cacheService.get(generationKey(orgId, plugin))) ?? "0";
+        const cached = await this.cachedCopy(orgId, plugin, gen);
+        if (!cached.copy)
+            return undefined;
+        const opened = this.open(orgId, plugin, cached.sealed);
+        // sealed with a key no longer in the keyring: read through
+        if (opened)
+            return opened;
+        const fresh = await this.readCopy(orgId, plugin);
+        return fresh ?? undefined;
+    }
+    /**
+     * Makes every cached copy of (org, plugin) unreachable: a new generation token, and the entry of
+     * the old one deleted. Call it after the write committed (`afterCommit`), never inside it.
+     */
+    async invalidate(orgId, plugin) {
+        const key = generationKey(orgId, plugin);
+        const old = (await this.cacheService.get(key)) ?? "0";
+        await this.cacheService.set(key, randomUUID(), GENERATION_TTL);
+        await this.cacheService.del(copyCacheKey(orgId, plugin, old));
+    }
+    /** Keyed by the generation token read just before the PG read. */
+    async cachedCopy(orgId, plugin, _gen) {
+        const copy = await this.readCopy(orgId, plugin);
+        return copy ? { copy: true, sealed: this.seal(orgId, plugin, copy) } : { copy: false };
+    }
+    /**
+     * The copy row and its secrets from one snapshot (joins the caller's transaction, so a write
+     * sees what it just wrote).
+     */
+    async readCopy(orgId, plugin) {
+        const t = this.db;
+        const row = await t
+            .selectFrom("extension_org_overrides")
+            .select("config")
+            .where("plugin", "=", plugin)
+            .where("org_id", "=", orgId)
+            .executeTakeFirst();
+        if (!row)
+            return null;
+        const prefix = overrideSecretKey(plugin, "");
+        const keys = await t
+            .selectFrom("secrets")
+            .select("key")
+            .where("namespace", "=", OVERRIDE_SECRETS_NAMESPACE)
+            .where("org_id", "=", orgId)
+            .where("key", "like", `${prefix}%`)
+            .execute();
+        const store = createSecrets(t, this.keyring, OVERRIDE_SECRETS_NAMESPACE);
+        const secrets = {};
+        for (const { key } of keys) {
+            if (!key.startsWith(prefix))
+                continue;
+            const v = await store.get(orgId, key);
+            if (v !== null)
+                secrets[key.slice(prefix.length)] = JSON.parse(v);
+        }
+        return { config: row.config ?? {}, secrets };
+    }
+    /**
+     * The number of orgs (not deleted) where the extension is on and has no valid effective config
+     * (spec A §5.4a). Following orgs share the platform's result; each copy is checked on its own.
+     * 0 when the extension is not running on this replica.
+     */
+    async countNeedingConfig(plugin) {
+        if (!this.registry.current(plugin))
+            return 0;
+        const rows = await this.db
+            .selectFrom(enabledExtensionsByOrg(this.db).as("en"))
+            .innerJoin("orgs", "orgs.id", "en.org_id")
+            .leftJoin("extension_org_overrides as ov", (j) => j.onRef("ov.org_id", "=", "en.org_id").onRef("ov.plugin", "=", "en.plugin"))
+            .select(["en.org_id as orgId", "ov.org_id as copyOrg"])
+            .where("orgs.deleted_at", "is", null)
+            .where("en.plugin", "=", plugin)
+            .execute();
+        let n = 0;
+        let following;
+        for (const r of rows) {
+            if (r.copyOrg === null) {
+                following ??= (await this.get(r.orgId, plugin)).ok;
+                if (!following)
+                    n++;
+            }
+            else if (!(await this.get(r.orgId, plugin)).ok)
+                n++;
+        }
+        return n;
+    }
+    cacheKey() {
+        return this.keyring.deriveKey(CACHE_KEY_INFO);
+    }
+    seal(orgId, plugin, copy) {
+        const keys = this.cacheKey();
+        const iv = randomBytes(IV_LEN);
+        const cipher = createCipheriv("aes-256-gcm", keys.current, iv);
+        cipher.setAAD(Buffer.from(`${orgId}\0${plugin}`, "utf8"));
+        const data = Buffer.concat([cipher.update(JSON.stringify(copy), "utf8"), cipher.final()]);
+        return `${keys.currentId}:${Buffer.concat([iv, cipher.getAuthTag(), data]).toString("base64")}`;
+    }
+    open(orgId, plugin, sealed) {
+        const at = sealed.indexOf(":");
+        const key = at > 0 ? this.cacheKey().byId(sealed.slice(0, at)) : undefined;
+        if (!key)
+            return undefined;
+        try {
+            const blob = Buffer.from(sealed.slice(at + 1), "base64");
+            const decipher = createDecipheriv("aes-256-gcm", key, blob.subarray(0, IV_LEN));
+            decipher.setAAD(Buffer.from(`${orgId}\0${plugin}`, "utf8"));
+            decipher.setAuthTag(blob.subarray(IV_LEN, IV_LEN + TAG_LEN));
+            const plain = Buffer.concat([
+                decipher.update(blob.subarray(IV_LEN + TAG_LEN)),
+                decipher.final(),
+            ]).toString("utf8");
+            return JSON.parse(plain);
+        }
+        catch {
+            return undefined;
+        }
+    }
+};
+__decorate([
+    Cacheable({ key: "effective-config:#{0}:#{1}:#{2}", ttl: COPY_TTL })
+], EffectiveConfigs.prototype, "cachedCopy", null);
+__decorate([
+    Transactional({ isolationLevel: "repeatable read" })
+], EffectiveConfigs.prototype, "readCopy", null);
+EffectiveConfigs = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(TransactionHost)),
+    __param(2, Inject(CacheService)),
+    __param(3, Inject(KEYRING)),
+    __param(4, Inject(ExtensionRegistry)),
+    __param(5, Inject(ExtensionInstalls)),
+    __param(6, Inject(KernelConfigService)),
+    __param(7, Inject(KERNEL_LOGGER))
+], EffectiveConfigs);
+export { EffectiveConfigs };
+/** The cache key of a copy under a generation (the `@Cacheable` key of `cachedCopy`). */
+const copyCacheKey = (orgId, plugin, gen) => `effective-config:${orgId}:${plugin}:${gen}`;

package/dist/extensions/extensions.module.js

@@ -5,23 +5,29 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 import { Module } from "@nestjs/common";
-import { EnterpriseAdminLockModule } from "../identity/enterprise-admin.js";
+import { SuperAdminLockModule } from "../identity/super-admin.js";
+import { ModelsModule } from "../models/models.module.js";
 import { OrgLockModule } from "../orgs/org-lock.js";
 import { StorageModule } from "../storage/storage.module.js";
 import { EmbedTokensModule } from "../ui/embed-token.js";
 import { ExtensionAdminOps } from "./admin-ops.js";
 import { ExtensionAdmin } from "./admin-view.js";
-import { ExtensionApprovals } from "./approvals.js";
-import { ExtensionBlobs } from "./blobs.js";
 import { BootstrapService } from "./bootstrap.js";
 import { ExtensionDeploymentConfigService } from "./deployment-config.js";
+import { ExtensionDisplayNames } from "./display-name.js";
 import { ExtensionHost } from "./host.js";
-import { ExtensionInstalls } from "./installs.js";
 import { ExtensionLifecycle } from "./lifecycle.js";
-import { PluginApproveLock, PluginDeploymentConfigLock, PluginInstallLock } from "./locks.js";
+import { PluginApproveLock, PluginDeploymentConfigLock, PluginInstallLock, SingleProviderLock, } from "./locks.js";
 import { OrgExtensionConfigs } from "./org-config.js";
+import { OrgOverrides } from "./org-overrides.js";
+import { PluginGuides } from "./plugin-guides.js";
+import { PluginIcons } from "./plugin-icons.js";
+import { ExtensionPointDefaults } from "./point-defaults.js";
 import { ExtensionRegistryModule } from "./registry.js";
+import { SingleProviderGuard } from "./single-provider.js";
 import { ReplicaStatusStore } from "./sources.js";
+import { ExtensionStateModule } from "./state.module.js";
+import { ExtensionAvailability } from "./unavailable.js";
 /**
  * The extensions domain: the extension host (it builds each `ctx` from the injected kernel
  * services), the package store and install records (the desired state the host converges to, one
@@ -34,43 +40,56 @@ ExtensionsModule = __decorate([
     Module({
         imports: [
             ExtensionRegistryModule,
-            EnterpriseAdminLockModule,
+            SuperAdminLockModule,
             OrgLockModule,
             StorageModule,
             // ctx.ui verifies embed tokens with the one provider the UI routes issue them with
             EmbedTokensModule,
+            ExtensionStateModule,
+            // ctx.models: the embeddings broker (models domain, below the host through ExtensionStateModule)
+            ModelsModule,
         ],
         providers: [
             PluginInstallLock,
             PluginApproveLock,
             PluginDeploymentConfigLock,
-            ExtensionApprovals,
-            ExtensionBlobs,
-            ExtensionInstalls,
+            SingleProviderLock,
+            SingleProviderGuard,
             ReplicaStatusStore,
             ExtensionHost,
             ExtensionLifecycle,
             ExtensionAdmin,
             ExtensionAdminOps,
+            ExtensionDisplayNames,
+            PluginIcons,
+            PluginGuides,
             ExtensionDeploymentConfigService,
             OrgExtensionConfigs,
+            OrgOverrides,
+            ExtensionPointDefaults,
             BootstrapService,
+            ExtensionAvailability,
         ],
         exports: [
             ExtensionRegistryModule,
+            ExtensionStateModule,
             PluginInstallLock,
             PluginApproveLock,
-            ExtensionApprovals,
-            ExtensionBlobs,
-            ExtensionInstalls,
             ReplicaStatusStore,
             ExtensionHost,
             ExtensionLifecycle,
             ExtensionAdmin,
             ExtensionAdminOps,
+            ExtensionDisplayNames,
+            PluginIcons,
+            PluginGuides,
             ExtensionDeploymentConfigService,
             OrgExtensionConfigs,
+            OrgOverrides,
+            ExtensionPointDefaults,
             BootstrapService,
+            ExtensionAvailability,
+            SingleProviderGuard,
         ],
     })
 ], ExtensionsModule);

package/dist/extensions/guide-places.d.ts

@@ -0,0 +1,68 @@
+import { type PluginSetupGuide, type SetupGuideAudience, type SetupGuidePlace } from "@capybara-hq/plugin-sdk";
+import type { KernelConfig } from "../config/schema.js";
+import type { KernelDb } from "../infra/database/kernel-db.js";
+import type { OrgAction } from "../orgs/roles.js";
+/** Why a known variable has no value: what the web and the `Platform` tool tell the reader. */
+export type UnresolvedReason = 
+/** The target is not saved yet (the webhook URL). */
+"not_saved"
+/** No name typed yet on the new target's form (a connection name on 新建渠道). */
+ | "no_name"
+/** `http.publicUrl` is not set (the URLs built from it). */
+ | "public_url"
+/** `channels.webhookBaseUrl` is not set or unusable. */
+ | "webhook_base"
+/** No connector is made from the template yet. */
+ | "no_connector"
+/** Rendered for the platform (the super admin's preview), not for an org. */
+ | "no_org";
+/** The org action each audience of a place needs besides `catalog.read` (spec §9.1). */
+export declare const PLACE_ACTIONS: Readonly<Record<SetupGuidePlace, Readonly<Partial<Record<SetupGuideAudience, OrgAction>>>>>;
+/** The object a guide is rendered for. */
+export interface GuideTarget {
+    kind: "channel-connection" | "connector";
+    id: string;
+}
+/** The target parameters of the guide route, per place. */
+export interface GuideTargetQuery {
+    connectionId?: string | undefined;
+    name?: string | undefined;
+    connectorId?: string | undefined;
+}
+/** What a place resolves for one rendering (the mode is the caller's: it picks it from these). */
+export interface PlaceResolution {
+    /** Every variable of the place except `mode`; null = known without a value. */
+    values: Record<string, string | null>;
+    /** The reason of each variable that is null in `values`. */
+    reasons: Record<string, UnresolvedReason>;
+    target: GuideTarget | null;
+    /** The target's stored mode (a channel connection's `inbound_mode`), null without one. */
+    storedMode: string | null;
+}
+/** Where the values come from. */
+export interface PlaceContext {
+    db: KernelDb;
+    config: Pick<KernelConfig, "http" | "channels"> & {
+        tools: Pick<KernelConfig["tools"], "oauthAllowInsecureLoopback">;
+    };
+    item: {
+        id: string;
+        name: string;
+        version: string;
+    };
+    guide: PluginSetupGuide;
+    locale: "en" | "zh";
+    /** The org rendered for; null for the platform preview (no org, no target). */
+    org: {
+        orgId: string;
+        name: string;
+    } | null;
+    query: GuideTargetQuery;
+}
+/**
+ * The variable values of a place for one rendering (spec §6.3): the common ones, then the place's
+ * own from its target. Throws 400 `validation_failed` for another place's target parameter and 404
+ * (`channel.not_found`, `connector.not_found`) for a target that is not a live object of the org on
+ * the guide's plugin.
+ */
+export declare function resolvePlace(ctx: PlaceContext): Promise<PlaceResolution>;