@capybara-hq/kernel 0.1.0-rc.24 → 0.1.0-rc.25

package/dist/extensions/hooks.d.ts

@@ -1,4 +1,4 @@
-import { type AvailableHook, type HookHandler, type HookOptions, type HookPayloads, type Logger, type PolicyHook } from "@capybara-hq/plugin-sdk";
+import { type AvailableHook, type HookHandler, type HookOptions, type HookPayloads, type LIFECYCLE_HOOKS, 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";
@@ -63,7 +63,16 @@ export interface HookSource {
     readonly name: string;
     readonly hooks: readonly RegisteredHook[];
     readonly inflight: InflightTracker;
+    /** The instance's platform deployment config (what lifecycle hooks are called with). */
+    readonly config?: unknown;
 }
+/** A lifecycle mount: an observe-only notice that a member, an agent or an org was removed. */
+export type LifecycleHook = (typeof LIFECYCLE_HOOKS)[number];
+/**
+ * Mounts delivered by a queue (at least once, by plugin) instead of {@link HookRegistry.run}:
+ * `usage.report` and the lifecycle mounts.
+ */
+export type QueuedHook = "usage.report" | LifecycleHook;
 /** Error text that never throws itself (a hostile `message` getter or `toString`). */
 export declare function errMsg(e: unknown): string;
 /**
@@ -166,8 +175,18 @@ export declare class HookRegistry {
         plugin: string;
         handler: HookHandler<"usage.report">;
     }[];
-    /** Runs the hooks of a mount point (see the class comment). */
-    run<K extends Exclude<AvailableHook, "usage.report">>(mount: K, payload: HookPayloads[K], signal: AbortSignal): Promise<HookOutcome>;
+    /**
+     * Lifecycle handlers by plugin name (delivered by the lifecycle queue, `lifecycle-hooks.ts`, not
+     * by {@link run}). Each call runs through the instance's `inflight.run` with the plugin's platform
+     * deployment config, never an org's copy: cleanup goes out whether or not the org's effective
+     * config is valid (or the org still exists).
+     */
+    lifecycleHandlers<K extends LifecycleHook>(mount: K): {
+        plugin: string;
+        handler: HookHandler<K>;
+    }[];
+    /** Runs the hooks of a mount point (see the class comment); queue-delivered mounts excluded. */
+    run<K extends Exclude<AvailableHook, QueuedHook>>(mount: K, payload: HookPayloads[K], signal: AbortSignal): Promise<HookOutcome>;
     /**
      * The M-1 denial: `missing` (sorted) are enabled policy plugins that are not loaded on this replica.
      * The model-visible reason is generic; the detail and a throttled warning name the plugin for the

package/dist/extensions/hooks.js

@@ -189,7 +189,21 @@ export class HookRegistry {
             }),
         }));
     }
-    /** Runs the hooks of a mount point (see the class comment). */
+    /**
+     * Lifecycle handlers by plugin name (delivered by the lifecycle queue, `lifecycle-hooks.ts`, not
+     * by {@link run}). Each call runs through the instance's `inflight.run` with the plugin's platform
+     * deployment config, never an org's copy: cleanup goes out whether or not the org's effective
+     * config is valid (or the org still exists).
+     */
+    lifecycleHandlers(mount) {
+        return this.entries(mount).map(({ src, hook }) => ({
+            plugin: src.name,
+            handler: (payload, signal) => src.inflight.run(signal, async (s) => {
+                await hook.handler(payload, s, { config: src.config });
+            }),
+        }));
+    }
+    /** Runs the hooks of a mount point (see the class comment); queue-delivered mounts excluded. */
     async run(mount, payload, signal) {
         if (signal.aborted)
             throw signal.reason;

package/dist/extensions/lifecycle-hooks.d.ts

@@ -0,0 +1,99 @@
+import type { HookPayloads } from "@capybara-hq/plugin-sdk";
+import { WorkerHost } from "@nestjs/bullmq";
+import type { Job, Worker } from "bullmq";
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { OutboxService } from "../infra/outbox/outbox.service.js";
+import type { KernelLogger } from "../log.js";
+import { type LifecycleHook } from "./hooks.js";
+import { ExtensionHost } from "./host.js";
+/** Queue of lifecycle hook deliveries (no `:` in the name). */
+export declare const LIFECYCLE_QUEUE = "cap-kernel-lifecycle";
+/** The job name of every delivery (registered in `infra/outbox/registry.ts`). */
+export declare const LIFECYCLE_JOB = "lifecycle";
+/** One handler call's time limit. */
+export declare const LIFECYCLE_HOOK_TIMEOUT_MS = 5000;
+/** Job data: one mount's payload for one subscribing plugin. */
+export interface LifecycleJob<K extends LifecycleHook = LifecycleHook> {
+    mount: K;
+    plugin: string;
+    payload: HookPayloads[K];
+}
+/**
+ * The deterministic job id of one delivery: the mount, the plugin and the payload's ids (no `:`;
+ * kernel ids and plugin names carry none). Removing the same member, agent or org again while the
+ * first delivery is still owed is the same job.
+ */
+export declare function lifecycleJobId<K extends LifecycleHook>(mount: K, plugin: string, payload: HookPayloads[K]): string;
+/**
+ * Plugins that subscribe to a lifecycle mount according to deployment state: the approved
+ * permission snapshot declares the mount in `permissions.hooks`, and that approved version is the
+ * one the deployment runs: an enabled install of that version, or a replica status row (not
+ * `unloaded`) that loaded or still serves it (an upgrade pending approval keeps serving the
+ * approved version; a config-declared plugin has only replica rows). A snapshot approved for
+ * another version than the one installed or served does not count. Org enablement does not count
+ * either: cleanup concerns data the plugin already holds (memory plugin spec §6.3). Sorted by name.
+ */
+export declare function queryLifecycleSubscribers(db: KernelSchemaDb, mount: LifecycleHook): Promise<string[]>;
+/**
+ * Durable delivery of the lifecycle hooks `org.member_removed`, `agent.deleted` and `org.deleted`
+ * (memory plugin spec §6.3), so extensions reliably learn to delete the data they hold:
+ * - **Owe** ({@link recordIn}): in the transaction that removes the member, the agent or the org,
+ *   one outbox job per subscribing plugin ({@link queryLifecycleSubscribers}) on
+ *   {@link LIFECYCLE_QUEUE}, under {@link lifecycleJobId}, with no `org_id` (it is the deletion's
+ *   own cleanup work, transactional outbox spec §9); a rollback owes nothing. The outbox delivers
+ *   it to BullMQ after the commit (registry: attempts and backoff).
+ * - **Deliver** ({@link process}, worker role): the plugin's handlers loaded on this replica are
+ *   called in turn (5 s each). Not loaded on this replica -> the job fails and is retried (another
+ *   replica or a later attempt). Loaded without a handler -> dropped with a warning. Handlers get
+ *   the plugin's platform deployment config (`call.config`), never an org's copy, so an org whose
+ *   effective config is not valid still gets its cleanup. The last failed attempt logs an error.
+ * Handlers must be idempotent (a delivery may repeat when a replica dies after the call).
+ */
+export declare class LifecycleHooks {
+    private readonly kdb;
+    readonly txHost: TransactionHost;
+    private readonly outbox;
+    /** The loaded plugins' handlers (`hooks.handlers`) and whether a plugin is active here. */
+    private readonly host;
+    private readonly log;
+    constructor(kdb: KernelDb, txHost: TransactionHost, outbox: Pick<OutboxService, "add">, 
+    /** The loaded plugins' handlers (`hooks.handlers`) and whether a plugin is active here. */
+    host: Pick<ExtensionHost, "hooks" | "current">, log: KernelLogger);
+    /**
+     * Owes one delivery per subscribing plugin in the caller's transaction (`mandatory`); returns
+     * the plugins.
+     */
+    recordIn<K extends LifecycleHook>(mount: K, payload: HookPayloads[K]): Promise<string[]>;
+    /** One delivery job (the consumer {@link LifecycleHooksProcessor} calls it). */
+    process(data: LifecycleJob, stop: AbortSignal): Promise<void>;
+    /** One handler call, aborted after {@link LIFECYCLE_HOOK_TIMEOUT_MS} or when the replica stops. */
+    private call;
+    /** A job failed (the worker's `failed` event): a retry warns, the last attempt logs an error. */
+    onFailed(j: Job<LifecycleJob> | undefined, err: Error): void;
+}
+/**
+ * The consumer of {@link LIFECYCLE_QUEUE}: {@link LifecycleHooks.process}. Worker role only
+ * (`LifecycleHookWorkersModule`); built with `autorun: false`, started by the worker role after the
+ * extensions loaded.
+ */
+export declare class LifecycleHooksProcessor extends WorkerHost<Worker<LifecycleJob>> {
+    private readonly hooks;
+    private readonly log;
+    private readonly stopping;
+    constructor(hooks: LifecycleHooks, log: Pick<KernelLogger, "error">);
+    process(job: Job<LifecycleJob>): Promise<void>;
+    /** Starts consuming (worker role, after the extensions loaded). */
+    start(): void;
+    /** Aborts the calls in flight and closes the worker. */
+    close(): Promise<void>;
+    failed(job: Job<LifecycleJob> | undefined, err: Error): void;
+    error(err: Error): void;
+}
+/** Lifecycle hook delivery: owing the jobs, and the queue the outbox adds them to, on every role. */
+export declare class LifecycleHooksModule {
+}
+/** The lifecycle queue's consumer; imported only by the worker role (`WorkerModule`). */
+export declare class LifecycleHookWorkersModule {
+}

package/dist/extensions/lifecycle-hooks.js

@@ -0,0 +1,273 @@
+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 { OnWorkerEvent, Processor, WorkerHost } from "@nestjs/bullmq";
+import { Inject, Injectable, Module } from "@nestjs/common";
+import { sql } from "kysely";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { Transactional } from "../infra/database/transactional.decorator.js";
+import { OutboxService } from "../infra/outbox/outbox.service.js";
+import { QueueModule } from "../infra/queue/queue.module.js";
+import { runJob } from "../infra/queue/run-job.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { ExtensionsModule } from "./extensions.module.js";
+import { deepFreeze, errMsg } from "./hooks.js";
+import { ExtensionHost } from "./host.js";
+/** Queue of lifecycle hook deliveries (no `:` in the name). */
+export const LIFECYCLE_QUEUE = "cap-kernel-lifecycle";
+/** The job name of every delivery (registered in `infra/outbox/registry.ts`). */
+export const LIFECYCLE_JOB = "lifecycle";
+/** One handler call's time limit. */
+export const LIFECYCLE_HOOK_TIMEOUT_MS = 5000;
+/** Concurrent deliveries per worker replica. */
+const LIFECYCLE_CONCURRENCY = 4;
+/**
+ * The deterministic job id of one delivery: the mount, the plugin and the payload's ids (no `:`;
+ * kernel ids and plugin names carry none). Removing the same member, agent or org again while the
+ * first delivery is still owed is the same job.
+ */
+export function lifecycleJobId(mount, plugin, payload) {
+    const ids = Object.entries(payload)
+        .sort(([a], [b]) => (a < b ? -1 : 1))
+        .map(([, v]) => String(v));
+    return ["lifecycle", mount.replaceAll(".", "-"), plugin, ...ids].join("-").replaceAll(":", "-");
+}
+/**
+ * Plugins that subscribe to a lifecycle mount according to deployment state: the approved
+ * permission snapshot declares the mount in `permissions.hooks`, and that approved version is the
+ * one the deployment runs: an enabled install of that version, or a replica status row (not
+ * `unloaded`) that loaded or still serves it (an upgrade pending approval keeps serving the
+ * approved version; a config-declared plugin has only replica rows). A snapshot approved for
+ * another version than the one installed or served does not count. Org enablement does not count
+ * either: cleanup concerns data the plugin already holds (memory plugin spec §6.3). Sorted by name.
+ */
+export async function queryLifecycleSubscribers(db, mount) {
+    const rows = await db
+        .selectFrom("extension_permission_snapshots as s")
+        .select("s.plugin")
+        .distinct()
+        .where(sql `s.permissions -> 'permissions' -> 'hooks' ? ${mount}`)
+        .where((eb) => eb.or([
+        eb.exists(eb
+            .selectFrom("extension_installs as i")
+            .select(sql `1`.as("one"))
+            .whereRef("i.name", "=", "s.plugin")
+            .whereRef("i.version", "=", "s.version")
+            .where("i.desired_state", "=", "enabled")),
+        eb.exists(eb
+            .selectFrom("extension_replica_status as r")
+            .select(sql `1`.as("one"))
+            .whereRef("r.plugin", "=", "s.plugin")
+            .where("r.state", "<>", "unloaded")
+            .where((r) => r.or([
+            r("r.version", "=", r.ref("s.version")),
+            r("r.serving_version", "=", r.ref("s.version")),
+        ]))),
+    ]))
+        .orderBy("s.plugin")
+        .execute();
+    return rows.map((r) => r.plugin);
+}
+/**
+ * Durable delivery of the lifecycle hooks `org.member_removed`, `agent.deleted` and `org.deleted`
+ * (memory plugin spec §6.3), so extensions reliably learn to delete the data they hold:
+ * - **Owe** ({@link recordIn}): in the transaction that removes the member, the agent or the org,
+ *   one outbox job per subscribing plugin ({@link queryLifecycleSubscribers}) on
+ *   {@link LIFECYCLE_QUEUE}, under {@link lifecycleJobId}, with no `org_id` (it is the deletion's
+ *   own cleanup work, transactional outbox spec §9); a rollback owes nothing. The outbox delivers
+ *   it to BullMQ after the commit (registry: attempts and backoff).
+ * - **Deliver** ({@link process}, worker role): the plugin's handlers loaded on this replica are
+ *   called in turn (5 s each). Not loaded on this replica -> the job fails and is retried (another
+ *   replica or a later attempt). Loaded without a handler -> dropped with a warning. Handlers get
+ *   the plugin's platform deployment config (`call.config`), never an org's copy, so an org whose
+ *   effective config is not valid still gets its cleanup. The last failed attempt logs an error.
+ * Handlers must be idempotent (a delivery may repeat when a replica dies after the call).
+ */
+let LifecycleHooks = class LifecycleHooks {
+    kdb;
+    txHost;
+    outbox;
+    host;
+    log;
+    constructor(kdb, txHost, outbox, 
+    /** The loaded plugins' handlers (`hooks.handlers`) and whether a plugin is active here. */
+    host, log) {
+        this.kdb = kdb;
+        this.txHost = txHost;
+        this.outbox = outbox;
+        this.host = host;
+        this.log = log;
+    }
+    /**
+     * Owes one delivery per subscribing plugin in the caller's transaction (`mandatory`); returns
+     * the plugins.
+     */
+    async recordIn(mount, payload) {
+        const plugins = await queryLifecycleSubscribers(this.kdb.db, mount);
+        for (const plugin of plugins) {
+            const data = { mount, plugin, payload };
+            await this.outbox.add({
+                queue: LIFECYCLE_QUEUE,
+                name: LIFECYCLE_JOB,
+                jobId: lifecycleJobId(mount, plugin, payload),
+                data,
+            });
+        }
+        return plugins;
+    }
+    /** One delivery job (the consumer {@link LifecycleHooksProcessor} calls it). */
+    async process(data, stop) {
+        const fields = { mount: data.mount, plugin: data.plugin };
+        const handlers = this.host.hooks
+            .lifecycleHandlers(data.mount)
+            .filter((h) => h.plugin === data.plugin)
+            .map((h) => h.handler);
+        if (handlers.length === 0) {
+            if (this.host.current(data.plugin) === undefined) {
+                // another replica or a later attempt may have it loaded
+                throw new Error(`plugin ${data.plugin} is not loaded on this replica`);
+            }
+            this.log.warn("lifecycle hook delivery dropped: the plugin registered no handler", fields);
+            return;
+        }
+        const payload = deepFreeze(structuredClone(data.payload));
+        for (const h of handlers)
+            await this.call(h, payload, stop);
+    }
+    /** One handler call, aborted after {@link LIFECYCLE_HOOK_TIMEOUT_MS} or when the replica stops. */
+    async call(h, payload, stop) {
+        const ac = new AbortController();
+        const onStop = () => ac.abort(new Error("replica stopping"));
+        if (stop.aborted)
+            onStop();
+        else
+            stop.addEventListener("abort", onStop, { once: true });
+        let timer;
+        try {
+            await Promise.race([
+                Promise.resolve().then(() => h(payload, ac.signal)),
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => {
+                        const err = new Error(`timed out after ${LIFECYCLE_HOOK_TIMEOUT_MS} ms`);
+                        ac.abort(err);
+                        reject(err);
+                    }, LIFECYCLE_HOOK_TIMEOUT_MS);
+                    // already aborted (the replica was stopping before the call): no abort event will fire
+                    if (ac.signal.aborted)
+                        reject(ac.signal.reason);
+                    else
+                        ac.signal.addEventListener("abort", () => reject(ac.signal.reason), { once: true });
+                }),
+            ]);
+        }
+        finally {
+            clearTimeout(timer);
+            stop.removeEventListener("abort", onStop);
+        }
+    }
+    /** A job failed (the worker's `failed` event): a retry warns, the last attempt logs an error. */
+    onFailed(j, err) {
+        if (!j)
+            return;
+        const fields = {
+            jobId: j.id,
+            mount: j.data.mount,
+            plugin: j.data.plugin,
+            attempt: j.attemptsMade,
+            error: errMsg(err),
+        };
+        if (j.attemptsMade >= (j.opts.attempts ?? 1)) {
+            this.log.error("lifecycle hook delivery failed on its last attempt; given up", fields);
+        }
+        else
+            this.log.warn("lifecycle hook delivery failed; retrying", fields);
+    }
+};
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], LifecycleHooks.prototype, "recordIn", null);
+LifecycleHooks = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(TransactionHost)),
+    __param(2, Inject(OutboxService)),
+    __param(3, Inject(ExtensionHost)),
+    __param(4, Inject(KERNEL_LOGGER))
+], LifecycleHooks);
+export { LifecycleHooks };
+/**
+ * The consumer of {@link LIFECYCLE_QUEUE}: {@link LifecycleHooks.process}. Worker role only
+ * (`LifecycleHookWorkersModule`); built with `autorun: false`, started by the worker role after the
+ * extensions loaded.
+ */
+let LifecycleHooksProcessor = class LifecycleHooksProcessor extends WorkerHost {
+    hooks;
+    log;
+    stopping = new AbortController();
+    constructor(hooks, log) {
+        super();
+        this.hooks = hooks;
+        this.log = log;
+    }
+    process(job) {
+        return runJob(LIFECYCLE_QUEUE, job, () => this.hooks.process(job.data, this.stopping.signal));
+    }
+    /** Starts consuming (worker role, after the extensions loaded). */
+    start() {
+        void this.worker.run().catch((err) => this.error(err));
+    }
+    /** Aborts the calls in flight and closes the worker. */
+    async close() {
+        this.stopping.abort();
+        await this.worker.close();
+    }
+    failed(job, err) {
+        this.hooks.onFailed(job, err);
+    }
+    error(err) {
+        this.log.error("lifecycle hook worker error", { err });
+    }
+};
+__decorate([
+    OnWorkerEvent("failed")
+], LifecycleHooksProcessor.prototype, "failed", null);
+__decorate([
+    OnWorkerEvent("error")
+], LifecycleHooksProcessor.prototype, "error", null);
+LifecycleHooksProcessor = __decorate([
+    Injectable(),
+    Processor(LIFECYCLE_QUEUE, { autorun: false, concurrency: LIFECYCLE_CONCURRENCY }),
+    __param(0, Inject(LifecycleHooks)),
+    __param(1, Inject(KERNEL_LOGGER))
+], LifecycleHooksProcessor);
+export { LifecycleHooksProcessor };
+const LIFECYCLE_QUEUE_MODULE = QueueModule.registerQueue(LIFECYCLE_QUEUE);
+/** Lifecycle hook delivery: owing the jobs, and the queue the outbox adds them to, on every role. */
+let LifecycleHooksModule = class LifecycleHooksModule {
+};
+LifecycleHooksModule = __decorate([
+    Module({
+        imports: [ExtensionsModule, LIFECYCLE_QUEUE_MODULE],
+        providers: [LifecycleHooks],
+        exports: [LifecycleHooks, LIFECYCLE_QUEUE_MODULE],
+    })
+], LifecycleHooksModule);
+export { LifecycleHooksModule };
+/** The lifecycle queue's consumer; imported only by the worker role (`WorkerModule`). */
+let LifecycleHookWorkersModule = class LifecycleHookWorkersModule {
+};
+LifecycleHookWorkersModule = __decorate([
+    Module({
+        imports: [LifecycleHooksModule],
+        providers: [LifecycleHooksProcessor],
+        exports: [LifecycleHooksProcessor],
+    })
+], LifecycleHookWorkersModule);
+export { LifecycleHookWorkersModule };

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

@@ -110,6 +110,16 @@ export interface OrgExtensionPutOptions {
      */
     validateOnly?: boolean;
 }
+/**
+ * An org's stored config of a plugin no longer matches its org schema (e.g. after a plugin upgrade):
+ * a known state, not a read error. The message names the plugin, the org and the failing paths,
+ * never the values.
+ */
+export declare class OrgConfigInvalidError extends Error {
+    readonly plugin: string;
+    readonly orgId: string;
+    constructor(plugin: string, orgId: string, detail: string);
+}
 /**
  * Org-level extension config: enablement and the `config.org` config stored per org.
  * The non-secret part is stored in `capybara.extension_org_configs.config`; each secret field is
@@ -210,7 +220,9 @@ export declare class OrgExtensionConfigs {
      * A required bootstrap plugin is enabled without a row (its stored config, or `{}`, is validated).
      * 无记录 → undefined；插件无 `config.org` 或已停用（`enabled=false`，不校验、不读密钥）时 `config` 为 null。
      * 配置行与密钥在同一个 `REPEATABLE READ` 只读事务里读取。
-     * 已存配置不再满足 schema（如插件升级后）→ 抛 Error，信息含插件名、组织 ID 与出错路径（不含值）。
+     * A stored config that no longer matches the schema (e.g. after a plugin upgrade) throws
+     * {@link OrgConfigInvalidError} (plugin, org ID and the failing paths, no values); other errors are
+     * read errors.
      */
     get(orgId: string, plugin: string): Promise<{
         enabled: boolean;

package/dist/extensions/org-config.js

@@ -88,6 +88,21 @@ function secretPaths(schema) {
         .filter((f) => f.meta?.secret)
         .map((f) => f.path);
 }
+/**
+ * An org's stored config of a plugin no longer matches its org schema (e.g. after a plugin upgrade):
+ * a known state, not a read error. The message names the plugin, the org and the failing paths,
+ * never the values.
+ */
+export class OrgConfigInvalidError extends Error {
+    plugin;
+    orgId;
+    constructor(plugin, orgId, detail) {
+        super(`plugin ${plugin}: stored organization config for org ${orgId} is invalid: ${detail}`);
+        this.plugin = plugin;
+        this.orgId = orgId;
+        this.name = "OrgConfigInvalidError";
+    }
+}
 /**
  * Org-level extension config: enablement and the `config.org` config stored per org.
  * The non-secret part is stored in `capybara.extension_org_configs.config`; each secret field is
@@ -444,7 +459,9 @@ let OrgExtensionConfigs = class OrgExtensionConfigs {
      * A required bootstrap plugin is enabled without a row (its stored config, or `{}`, is validated).
      * 无记录 → undefined；插件无 `config.org` 或已停用（`enabled=false`，不校验、不读密钥）时 `config` 为 null。
      * 配置行与密钥在同一个 `REPEATABLE READ` 只读事务里读取。
-     * 已存配置不再满足 schema（如插件升级后）→ 抛 Error，信息含插件名、组织 ID 与出错路径（不含值）。
+     * A stored config that no longer matches the schema (e.g. after a plugin upgrade) throws
+     * {@link OrgConfigInvalidError} (plugin, org ID and the failing paths, no values); other errors are
+     * read errors.
      */
     async get(orgId, plugin) {
         const manifest = this.manifest(plugin);
@@ -488,7 +505,7 @@ let OrgExtensionConfigs = class OrgExtensionConfigs {
             const detail = toIssues(r.error)
                 .map((i) => `${i.path || "<root>"}: ${i.message}`)
                 .join("; ");
-            throw new Error(`plugin ${plugin}: stored organization config for org ${orgId} is invalid: ${detail}`);
+            throw new OrgConfigInvalidError(plugin, orgId, detail);
         }
         return { enabled: true, config: r.data };
     }

package/dist/extensions/permission-view.d.ts

@@ -30,7 +30,7 @@ export interface PermissionGroup {
  * ({@link SENSITIVE_EXTENSION_POINTS}; the code is the extension point name without `@<major>`, with
  * `-` replaced by `_`).
  */
-export type SensitiveReason = "secrets" | "public_routes" | "tools" | "hooks" | "ui_embed" | "client_code" | "ui_component" | "channel" | "directory" | "identity_source" | "sandbox" | "object_store" | "migration_warnings";
+export type SensitiveReason = "secrets" | "public_routes" | "tools" | "hooks" | "ui_embed" | "client_code" | "ui_component" | "channel" | "directory" | "identity_source" | "sandbox" | "object_store" | "context" | "migration_warnings";
 /** 权限清单里的一项（分组里的一项，或 `added` 里的一个权限键）。 */
 export interface PermissionItem {
     value: string;
@@ -39,10 +39,14 @@ export interface PermissionItem {
     reason?: SensitiveReason;
 }
 /**
- * 敏感的能力（D10 + 计划扩展，F-AI）：`sandbox@2` 在部署里执行任意命令、`object-store@1` 保管全部附件与插件包（D10）；
- * `channel@1` 收到组织在 IM 里的对话内容（Ruling A33）、`directory@1` 能把人加进组织（并为其建账号、建身份）、
- * `identity-source@1` 决定谁能登录成哪个账号。插件提供其中任何一个时，「提供」一组标为敏感，
- * 后台插件列表的 `sensitive` 为真，须超级管理员批准。只影响展示，不改权限快照的键。
+ * Sensitive capabilities (D10 + planned extensions, F-AI): `sandbox@2` runs arbitrary commands in
+ * the deployment, `object-store@1` holds every attachment and plugin package (D10); `channel@1`
+ * receives the org's IM conversations (Ruling A33), `directory@1` can add people to orgs (creating
+ * their accounts and identities), `identity-source@1` decides who can sign in as which account;
+ * `context@1` adds text to the model's context in conversations of orgs that enable it (memory
+ * plugin spec §6.1). A plugin providing any of them has its "provides" group marked sensitive and
+ * `sensitive` true in the admin plugin list, for the super admin to approve. Display only: the keys
+ * of the permission snapshot do not change.
  */
 export declare const SENSITIVE_EXTENSION_POINTS: readonly string[];
 /**

package/dist/extensions/permission-view.js

@@ -18,10 +18,14 @@ export function reviewHash(set, warnings = []) {
     return h.digest("hex").slice(0, 16);
 }
 /**
- * 敏感的能力（D10 + 计划扩展，F-AI）：`sandbox@2` 在部署里执行任意命令、`object-store@1` 保管全部附件与插件包（D10）；
- * `channel@1` 收到组织在 IM 里的对话内容（Ruling A33）、`directory@1` 能把人加进组织（并为其建账号、建身份）、
- * `identity-source@1` 决定谁能登录成哪个账号。插件提供其中任何一个时，「提供」一组标为敏感，
- * 后台插件列表的 `sensitive` 为真，须超级管理员批准。只影响展示，不改权限快照的键。
+ * Sensitive capabilities (D10 + planned extensions, F-AI): `sandbox@2` runs arbitrary commands in
+ * the deployment, `object-store@1` holds every attachment and plugin package (D10); `channel@1`
+ * receives the org's IM conversations (Ruling A33), `directory@1` can add people to orgs (creating
+ * their accounts and identities), `identity-source@1` decides who can sign in as which account;
+ * `context@1` adds text to the model's context in conversations of orgs that enable it (memory
+ * plugin spec §6.1). A plugin providing any of them has its "provides" group marked sensitive and
+ * `sensitive` true in the admin plugin list, for the super admin to approve. Display only: the keys
+ * of the permission snapshot do not change.
  */
 export const SENSITIVE_EXTENSION_POINTS = [
     "channel@1",
@@ -29,6 +33,7 @@ export const SENSITIVE_EXTENSION_POINTS = [
     "identity-source@1",
     "sandbox@2",
     "object-store@1",
+    "context@1",
 ];
 /** The one item of the "client" group (client extensions spec §5.4). */
 const CLIENT_ITEM = "client code";

package/dist/extensions/point-defaults.d.ts

@@ -18,6 +18,16 @@ export type PointResolution<T> = {
     ok: false;
     reason: "none" | "ambiguous";
 };
+/**
+ * One provider of a multi-provider extension point for an org ({@link ExtensionPointDefaults.providersFor}),
+ * with its org config and its effective deployment config for the org, both to pass back to it.
+ */
+export interface PointProvider<T> {
+    extension: string;
+    impl: T;
+    orgConfig: unknown;
+    config: unknown;
+}
 /** One `org-default` extension point of an org (the admin view). */
 export interface OrgPointDefaultView {
     point: string;
@@ -50,6 +60,19 @@ export declare class ExtensionPointDefaults {
      * point has no `selection`.
      */
     resolve<T>(orgId: string, point: string): Promise<PointResolution<T>>;
+    /**
+     * Every provider of `point` (the name without the major, e.g. `context`) that could serve
+     * `orgId` now, in extension-name order: the same candidates {@link resolve} chooses from (loaded
+     * here, enabled in the org, valid org and effective config, `configured()` not false), for
+     * points whose every enabled provider is used (no `selection`). `failed`: the providers enabled
+     * in the org whose status could not be read (reading a config or `configured()` threw, e.g. a
+     * transient database error); they are neither serving nor known to be off. An invalid stored
+     * org config ({@link OrgConfigInvalidError}) is not a read error: that provider is off.
+     */
+    providersFor<T>(orgId: string, point: string): Promise<{
+        providers: PointProvider<T>[];
+        failed: Set<string>;
+    }>;
     /** Every `org-default` point with its candidates, stored default and effective provider. */
     list(orgId: string): Promise<OrgPointDefaultView[]>;
     /** Whether each `org-default` point has a provider for the org now (no extension names). */
@@ -65,7 +88,11 @@ export declare class ExtensionPointDefaults {
     setDefault(orgId: string, point: string, extension: string, actorId: string, 
     /** Merged into the audit detail (a write made through the Platform tool). */
     auditDetail?: Record<string, unknown>): Promise<void>;
-    /** The candidates of `point` in `orgId`, by extension name. */
+    /**
+     * The candidates of `point` in `orgId`, by extension name, and the enabled providers whose status
+     * could not be read (a read or `configured()` threw: excluded, logged). A provider whose stored
+     * org config or effective config is invalid is excluded but not `failed`: it is known to be off.
+     */
     private candidates;
     private choose;
     /** The org's stored defaults, point → extension. */