@capybara-hq/kernel 0.1.0-rc.4 → 0.1.0-rc.6

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/extensions.module.js

@@ -5,25 +5,25 @@ 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 { OrgExtensionConfigs } from "./org-config.js";
+import { OrgOverrides } from "./org-overrides.js";
 import { ExtensionPointDefaults } from "./point-defaults.js";
 import { ExtensionRegistryModule } from "./registry.js";
 import { ReplicaStatusStore } from "./sources.js";
+import { ExtensionStateModule } from "./state.module.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
@@ -36,19 +36,19 @@ 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,
             ReplicaStatusStore,
             ExtensionHost,
             ExtensionLifecycle,
@@ -57,16 +57,15 @@ ExtensionsModule = __decorate([
             ExtensionDisplayNames,
             ExtensionDeploymentConfigService,
             OrgExtensionConfigs,
+            OrgOverrides,
             ExtensionPointDefaults,
             BootstrapService,
         ],
         exports: [
             ExtensionRegistryModule,
+            ExtensionStateModule,
             PluginInstallLock,
             PluginApproveLock,
-            ExtensionApprovals,
-            ExtensionBlobs,
-            ExtensionInstalls,
             ReplicaStatusStore,
             ExtensionHost,
             ExtensionLifecycle,
@@ -75,6 +74,7 @@ ExtensionsModule = __decorate([
             ExtensionDisplayNames,
             ExtensionDeploymentConfigService,
             OrgExtensionConfigs,
+            OrgOverrides,
             ExtensionPointDefaults,
             BootstrapService,
         ],

package/dist/extensions/hooks.d.ts

@@ -1,6 +1,7 @@
 import { type AvailableHook, type HookHandler, type HookOptions, type HookPayloads, type Logger, type PolicyHook } from "@capybara-hq/plugin-sdk";
 import type { KernelConfig } from "../config/schema.js";
 import type { LockService } from "../infra/lock/lock.service.js";
+import { type EffectiveConfig } from "./effective-config.js";
 import { type InflightTracker } from "./inflight.js";
 /** Default of `hooks.timeoutMs` (used when a host is built without kernel config, e.g. in tests). */
 export declare const DEFAULT_HOOK_TIMEOUT_MS = 5000;
@@ -27,8 +28,8 @@ export type HookOutcome = {
     cause: "deny" | "hook_error" | "timeout";
     detail?: string;
     /**
-     * R10: the hooks could not run at all (organization lookup or payload copy failed); `plugin` is
-     * only the first policy plugin on the mount, not the cause.
+     * R10: the hooks could not run at all (organization lookup, config read or payload copy
+     * failed); `plugin` is only the first policy plugin on the mount, not the cause.
      */
     preflight?: true;
     /**
@@ -36,7 +37,21 @@ export type HookOutcome = {
      * approved, but is not loaded on this replica: the call fails closed without running any hook.
      */
     notLoaded?: true;
+    /**
+     * Layering spec A §6: `plugin` has a policy hook on this mount but its effective config is not
+     * valid in the organization, so it behaves as if not loaded: the call fails closed without
+     * running any policy hook.
+     */
+    needsConfig?: true;
 };
+/**
+ * Thrown by a `usage.report` handler wrapper (see {@link HookRegistry.handlers}) instead of calling
+ * a handler whose extension's effective config is not valid in the payload's organization.
+ */
+export declare class HookNeedsConfigError extends Error {
+    readonly plugin: string;
+    constructor(plugin: string);
+}
 /** A hook a plugin instance registered through `ctx.hooks.on` (kept on the instance, like tools). */
 export interface RegisteredHook {
     mount: AvailableHook;
@@ -80,7 +95,12 @@ export declare const HOOK_DETAIL_MAX_CHARS = 2048;
  *    If a plugin the organization enabled is expected to run policy hooks on the mount (deployment
  *    state, `expectedPolicy`) but is not loaded on this replica, deny with a generic reason
  *    (`hook_error`, `notLoaded`) without running any policy hook (M-1: fail closed). Observe hooks
- *    of plugins that are not loaded are simply missing.
+ *    of plugins that are not loaded are simply missing. Then each enabled plugin with a hook on the
+ *    mount gets its effective config for the organization (layering spec A §6; one read per plugin
+ *    and call, failing like the lookup above). A plugin whose config is not valid behaves as one
+ *    that is not loaded: with a policy hook on the mount the call is denied (`hook_error`,
+ *    `needsConfig`) without running any policy hook, and its observe hooks are skipped. Every
+ *    hook is called with `{ config }` as its third argument.
  * 3. Policy hooks run serially by plugin name (registration order within a plugin), each limited
  *    by `hooks.timeoutMs` (read on every run, hot). `{ deny }`, an error or a timeout stops the chain
  *    and denies (`deny` / `hook_error` / `timeout`). A policy hook cut off by its instance being
@@ -112,6 +132,12 @@ export declare class HookRegistry {
          */
         expectedPolicy?(mount: PolicyHook): readonly string[];
         enabledPlugins(orgId: string): Promise<Set<string>>;
+        /**
+         * The effective deployment config of a plugin for an organization (`EffectiveConfigs.get`):
+         * passed to every hook call, and no hook of the plugin runs for the organization when it is
+         * not valid.
+         */
+        effectiveConfig(orgId: string, plugin: string): Promise<EffectiveConfig>;
         /** The warn-once markers (`lease`: set unless present, with a TTL). */
         locks: Pick<LockService, "lease">;
         config: () => {
@@ -132,7 +158,9 @@ export declare class HookRegistry {
     private unloadedPolicy;
     /**
      * `usage.report` handlers by plugin name (delivered by the usage queue, not by {@link run}); each
-     * call runs through the instance's `inflight.run`.
+     * call runs through the instance's `inflight.run` with the plugin's effective config for the
+     * payload's organization, and throws {@link HookNeedsConfigError} without calling the handler
+     * when that config is not valid (layering spec A §6).
      */
     handlers(mount: "usage.report"): {
         plugin: string;
@@ -146,6 +174,11 @@ export declare class HookRegistry {
      * admin.
      */
     private notLoadedDenial;
+    /**
+     * The layering spec A §6 denial: `needy` (sorted) are enabled policy plugins whose effective
+     * config is not valid in the organization. Generic model-visible reason, as for M-1.
+     */
+    private needsConfigDenial;
     /** Active entries of a mount point, sorted by plugin name (stable: registration order within). */
     private entries;
     /** One plugin's policy hooks in registration order; reruns once on a newer generation if revoked. */