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

package/dist/extensions/display-name.d.ts

@@ -0,0 +1,22 @@
+import type { LocalizedName } from "@capybara-hq/plugin-sdk";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { ExtensionHost } from "./host.js";
+/**
+ * Extension display names (extension config forms spec §2.2), the one resolver every extension and
+ * model API uses: a config-declared extension's plugin.json (read by this replica's host at load,
+ * the same on every replica), else the installed package's `display_name`, else the live catalog
+ * item of the same name, else null. No backfill: a package stored before 0066 gets a name with its
+ * next version. Stateless; one query per call.
+ */
+export declare class ExtensionDisplayNames {
+    private readonly db;
+    /** The config-declared extensions (they win over an install record of the same name, C15). */
+    private readonly host;
+    constructor(db: KernelDb, 
+    /** The config-declared extensions (they win over an install record of the same name, C15). */
+    host: ExtensionHost);
+    /** One extension's display name. */
+    get(name: string): Promise<LocalizedName | null>;
+    /** The display names of `names` (each one a key, null when it has none), in one query. */
+    many(names: string[]): Promise<Map<string, LocalizedName | null>>;
+}

package/dist/extensions/display-name.js

@@ -0,0 +1,77 @@
+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 { KernelDb } from "../infra/database/kernel-db.js";
+import { ExtensionHost } from "./host.js";
+/**
+ * Extension display names (extension config forms spec §2.2), the one resolver every extension and
+ * model API uses: a config-declared extension's plugin.json (read by this replica's host at load,
+ * the same on every replica), else the installed package's `display_name`, else the live catalog
+ * item of the same name, else null. No backfill: a package stored before 0066 gets a name with its
+ * next version. Stateless; one query per call.
+ */
+let ExtensionDisplayNames = class ExtensionDisplayNames {
+    db;
+    host;
+    constructor(db, 
+    /** The config-declared extensions (they win over an install record of the same name, C15). */
+    host) {
+        this.db = db;
+        this.host = host;
+    }
+    /** One extension's display name. */
+    async get(name) {
+        return (await this.many([name])).get(name) ?? null;
+    }
+    /** The display names of `names` (each one a key, null when it has none), in one query. */
+    async many(names) {
+        const out = new Map();
+        if (names.length === 0)
+            return out;
+        const declared = new Map(this.host.declaredPlugins().map((p) => [p.name, p]));
+        const rest = [];
+        for (const n of new Set(names)) {
+            const d = declared.get(n);
+            if (d)
+                out.set(n, d.displayName);
+            else
+                rest.push(n);
+        }
+        if (rest.length === 0)
+            return out;
+        const rows = await this.db
+            .selectFrom("extension_installs")
+            .innerJoin("extension_packages", "extension_packages.sha256", "extension_installs.sha256")
+            .select([
+            "extension_installs.name as name",
+            "extension_packages.display_name as display_name",
+            sql `0`.as("rank"),
+        ])
+            .where("extension_installs.name", "in", rest)
+            .unionAll((eb) => eb
+            .selectFrom("catalog_items")
+            .select(["name", "display_name", sql `1`.as("rank")])
+            .where("name", "in", rest)
+            .where("deleted_at", "is", null))
+            .execute();
+        rows.sort((a, b) => Number(a.rank) - Number(b.rank));
+        for (const n of rest) {
+            out.set(n, rows.find((r) => r.name === n && r.display_name !== null)?.display_name ?? null);
+        }
+        return out;
+    }
+};
+ExtensionDisplayNames = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(ExtensionHost))
+], ExtensionDisplayNames);
+export { ExtensionDisplayNames };

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

@@ -0,0 +1,127 @@
+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 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,368 @@
+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}`;
+/** 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 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 {
+                ok: false,
+                notRunning: true,
+                issues: [{ path: "", segments: [], message: "the extension is not running" }],
+            };
+        }
+        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/enabled.d.ts

@@ -1,4 +1,4 @@
-import type { KernelDb } from "../db/kernel-schema.js";
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
 /**
  * Which extensions an organization has enabled. Two sources, and every reader goes through these
  * helpers so none of them misses one:
@@ -9,7 +9,7 @@ import type { KernelDb } from "../db/kernel-schema.js";
  * that need that check it themselves, as before. `db` may be a transaction.
  */
 /** The names of the extensions enabled in `orgId` (a subquery with one column, `plugin`). */
-export declare function enabledExtensionsQuery(db: KernelDb, orgId: string): import("kysely").SelectQueryBuilder<import("../db/kernel-schema.js").KernelDatabase & {
+export declare function enabledExtensionsQuery(db: KernelSchemaDb, orgId: string): import("kysely").SelectQueryBuilder<import("../db/kernel-schema.js").KernelDatabase & {
     eoc: import("../db/kernel-schema.js").ExtensionOrgConfigsTable;
 }, "eoc", {
     plugin: string;
@@ -19,13 +19,13 @@ export declare function enabledExtensionsQuery(db: KernelDb, orgId: string): imp
  * `plugin`): `.innerJoin(enabledExtensionsByOrg(db).as("en"), (j) => j.onRef("en.org_id", …)…)`.
  * Soft-deleted orgs are included, as their org config rows are; callers filter `orgs.deleted_at`.
  */
-export declare function enabledExtensionsByOrg(db: KernelDb): import("kysely").SelectQueryBuilder<import("../db/kernel-schema.js").KernelDatabase & {
+export declare function enabledExtensionsByOrg(db: KernelSchemaDb): import("kysely").SelectQueryBuilder<import("../db/kernel-schema.js").KernelDatabase & {
     eoc: import("../db/kernel-schema.js").ExtensionOrgConfigsTable;
 }, "eoc", {
     org_id: string;
     plugin: string;
 }>;
 /** Whether `plugin` is enabled in `orgId` (see the file header). */
-export declare function isExtensionEnabled(db: KernelDb, orgId: string, plugin: string): Promise<boolean>;
+export declare function isExtensionEnabled(db: KernelSchemaDb, orgId: string, plugin: string): Promise<boolean>;
 /** The names of the required bootstrap plugins (installed with `required`). */
-export declare function requiredExtensions(db: KernelDb): Promise<Set<string>>;
+export declare function requiredExtensions(db: KernelSchemaDb): Promise<Set<string>>;

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

@@ -0,0 +1,8 @@
+/**
+ * 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
+ * way: spec §3), the per-replica lifecycle and its periodic reconcile, the admin operations,
+ * deployment and org configs, the bootstrap step, and the shared {@link ExtensionRegistry}.
+ */
+export declare class ExtensionsModule {
+}