@capybara-hq/kernel 0.1.0-rc.5 → 0.1.0-rc.7

package/dist/models/enablement.d.ts

@@ -0,0 +1,101 @@
+import { ExtensionRegistry } from "../extensions/registry.js";
+import { SuperAdminLock } from "../identity/super-admin.js";
+import { CacheService } from "../infra/cache/cache.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { OrgLock } from "../orgs/org-lock.js";
+/** The key of a model in a disabled set: `provider\u0000model`. */
+export declare const modelKey: (provider: string, model: string) => string;
+/** An agent whose current version uses a newly disabled model as its main model or fallback. */
+export interface AffectedModelAgent {
+    id: string;
+    name: string;
+    orgId: string;
+}
+/** A purpose mapping targeting a newly disabled model: a deployment default (`orgId` null) or an org override. */
+export interface AffectedModelPurpose {
+    purpose: string;
+    orgId: string | null;
+}
+/** The result of a disabled-list write: what now points at a model it disabled (spec B §5.3). */
+export interface ModelDisableResult {
+    affected: {
+        agents: AffectedModelAgent[];
+        purposes: AffectedModelPurpose[];
+    };
+}
+/**
+ * A change to one layer's disabled list of a provider: ids to disable and ids to enable. An id in
+ * neither list keeps its stored state; an id in both is refused.
+ */
+export interface ModelDisableChange {
+    disable: string[];
+    enable: string[];
+}
+/** The acting person of a write. */
+export interface ModelDisableActor {
+    accountId: string;
+    tokenId?: string | undefined;
+    /** Merged into the audit detail (a write made through the Platform tool). */
+    auditDetail?: Record<string, unknown>;
+}
+/**
+ * Models disabled on two layers (spec B §5.3, table `model_disabled`): the platform's list (the
+ * super admin; such a model is invisible to every org) and each org's (an org admin). Every model a
+ * provider lists is enabled unless a layer disabled it; a row keys on the model id, so it applies to
+ * whichever list the org sees, and an id the list does not contain is kept harmlessly. Disabling
+ * never creates an org config copy.
+ *
+ * The lists are read from PG and cached in Redis (`@Cacheable`, evicted after the commit of each
+ * write), never in process memory. `ProviderRegistry` filters its lists and `resolve` with them;
+ * purposes check their targets with {@link isEnabled}.
+ */
+export declare class ModelEnablement {
+    private readonly kdb;
+    readonly txHost: TransactionHost;
+    readonly cacheService: CacheService;
+    private readonly extensions;
+    private readonly adminLock;
+    private readonly orgLock;
+    constructor(kdb: KernelDb, txHost: TransactionHost, cacheService: CacheService, extensions: Pick<ExtensionRegistry, "list">, adminLock: Pick<SuperAdminLock, "lockAndAuthorize">, orgLock: Pick<OrgLock, "lockAndAuthorize">);
+    private get db();
+    /** One layer's disabled models (keys {@link modelKey}): the platform's (`null`) or the org's own. */
+    disabled(orgId: string | null): Promise<Set<string>>;
+    private disabledKeys;
+    private rowsOf;
+    /**
+     * The extensions `orgId` explicitly turned off: a row of the org's own switch
+     * (`extension_org_configs.enabled = false`, what the org's extension or plugin switch writes when
+     * an org admin turns it off), never a required bootstrap plugin. An extension with no row for the
+     * org is not in the set (it keeps working as before: spec A §8 with B's no-breakage anti-goal).
+     * Read from PG on every call (one small query; the switch has its own writers, nothing to evict).
+     */
+    switchedOff(orgId: string): Promise<Set<string>>;
+    /** Whether neither the platform nor `orgId` disabled the model (the lists only; see the class). */
+    isEnabled(orgId: string, provider: string, model: string): Promise<boolean>;
+    /**
+     * Changes the platform's disabled ids of `provider` by `change` (super admin, re-checked under
+     * the lock): ids in neither list keep their stored state. Returns what now points at a newly
+     * disabled model, across orgs.
+     */
+    setPlatform(provider: string, change: ModelDisableChange, actor: ModelDisableActor): Promise<ModelDisableResult>;
+    /**
+     * Changes the org's disabled ids of `provider` by `change` (`org.models.manage`, re-checked under
+     * the org lock): ids in neither list keep their stored state, so rows for models the org's page
+     * does not show (platform-disabled, or no longer listed) survive. Returns what in the org now
+     * points at a newly disabled model (its agents, its overrides and the deployment defaults it uses).
+     */
+    setOrg(orgId: string, provider: string, change: ModelDisableChange, actor: ModelDisableActor): Promise<ModelDisableResult>;
+    private apply;
+    /** Live agents (of `orgId`, or of every org) whose current version uses one of `models`. */
+    private agentsUsing;
+    /**
+     * Purpose mappings targeting one of `models`: for the platform every default and override, for
+     * an org its overrides and the deployment defaults (an org that disabled a default's model has
+     * that purpose unconfigured).
+     */
+    private purposesUsing;
+}
+/** The one {@link ModelEnablement}: the provider registry, purposes and the controllers read it. */
+export declare class ModelEnablementModule {
+}

package/dist/models/enablement.js

@@ -0,0 +1,264 @@
+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, Module } from "@nestjs/common";
+import { ApiError } from "../errors.js";
+import { ExtensionRegistry, ExtensionRegistryModule } from "../extensions/registry.js";
+import { audit } from "../identity/audit.js";
+import { SuperAdminLock, SuperAdminLockModule } from "../identity/super-admin.js";
+import { CacheService } from "../infra/cache/cache.service.js";
+import { Cacheable, CacheEvict } from "../infra/cache/cacheable.decorator.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { Transactional } from "../infra/database/transactional.decorator.js";
+import { OrgLock, OrgLockModule } from "../orgs/org-lock.js";
+/** The key of a model in a disabled set: `provider\u0000model`. */
+export const modelKey = (provider, model) => `${provider}\u0000${model}`;
+/** How long a disabled list stays cached (s); every write evicts it after its commit. */
+const DISABLED_TTL_SECONDS = 300;
+/** The cache key of a scope's disabled list (`platform` or `org.<id>`). */
+const PLATFORM_SCOPE = "platform";
+const orgScope = (orgId) => `org.${orgId}`;
+/**
+ * Models disabled on two layers (spec B §5.3, table `model_disabled`): the platform's list (the
+ * super admin; such a model is invisible to every org) and each org's (an org admin). Every model a
+ * provider lists is enabled unless a layer disabled it; a row keys on the model id, so it applies to
+ * whichever list the org sees, and an id the list does not contain is kept harmlessly. Disabling
+ * never creates an org config copy.
+ *
+ * The lists are read from PG and cached in Redis (`@Cacheable`, evicted after the commit of each
+ * write), never in process memory. `ProviderRegistry` filters its lists and `resolve` with them;
+ * purposes check their targets with {@link isEnabled}.
+ */
+let ModelEnablement = class ModelEnablement {
+    kdb;
+    txHost;
+    cacheService;
+    extensions;
+    adminLock;
+    orgLock;
+    constructor(kdb, txHost, cacheService, extensions, adminLock, orgLock) {
+        this.kdb = kdb;
+        this.txHost = txHost;
+        this.cacheService = cacheService;
+        this.extensions = extensions;
+        this.adminLock = adminLock;
+        this.orgLock = orgLock;
+    }
+    get db() {
+        return this.kdb.db;
+    }
+    /** One layer's disabled models (keys {@link modelKey}): the platform's (`null`) or the org's own. */
+    async disabled(orgId) {
+        return new Set(await this.disabledKeys(orgId === null ? PLATFORM_SCOPE : orgScope(orgId)));
+    }
+    async disabledKeys(scope) {
+        const orgId = scope === PLATFORM_SCOPE ? null : scope.slice("org.".length);
+        const rows = await this.rowsOf(orgId);
+        return rows.map((r) => modelKey(r.provider, r.model)).sort();
+    }
+    rowsOf(orgId, provider) {
+        let q = this.db
+            .selectFrom("model_disabled")
+            .select(["provider", "model"])
+            .where((eb) => (orgId === null ? eb("org_id", "is", null) : eb("org_id", "=", orgId)));
+        if (provider !== undefined)
+            q = q.where("provider", "=", provider);
+        return q.execute();
+    }
+    /**
+     * The extensions `orgId` explicitly turned off: a row of the org's own switch
+     * (`extension_org_configs.enabled = false`, what the org's extension or plugin switch writes when
+     * an org admin turns it off), never a required bootstrap plugin. An extension with no row for the
+     * org is not in the set (it keeps working as before: spec A §8 with B's no-breakage anti-goal).
+     * Read from PG on every call (one small query; the switch has its own writers, nothing to evict).
+     */
+    async switchedOff(orgId) {
+        const rows = await this.db
+            .selectFrom("extension_org_configs as eoc")
+            .leftJoin("extension_installs as ri", (j) => j.onRef("ri.name", "=", "eoc.plugin").on("ri.required", "=", true))
+            .select("eoc.plugin")
+            .where("eoc.org_id", "=", orgId)
+            .where("eoc.enabled", "=", false)
+            .where("ri.name", "is", null)
+            .execute();
+        return new Set(rows.map((r) => r.plugin));
+    }
+    /** Whether neither the platform nor `orgId` disabled the model (the lists only; see the class). */
+    async isEnabled(orgId, provider, model) {
+        const key = modelKey(provider, model);
+        const [platform, org] = await Promise.all([this.disabled(null), this.disabled(orgId)]);
+        return !platform.has(key) && !org.has(key);
+    }
+    /**
+     * Changes the platform's disabled ids of `provider` by `change` (super admin, re-checked under
+     * the lock): ids in neither list keep their stored state. Returns what now points at a newly
+     * disabled model, across orgs.
+     */
+    async setPlatform(provider, change, actor) {
+        await this.adminLock.lockAndAuthorize(actor.accountId);
+        return this.apply(null, provider, change, actor);
+    }
+    /**
+     * Changes the org's disabled ids of `provider` by `change` (`org.models.manage`, re-checked under
+     * the org lock): ids in neither list keep their stored state, so rows for models the org's page
+     * does not show (platform-disabled, or no longer listed) survive. Returns what in the org now
+     * points at a newly disabled model (its agents, its overrides and the deployment defaults it uses).
+     */
+    async setOrg(orgId, provider, change, actor) {
+        await this.orgLock.lockAndAuthorize(orgId, actor.accountId, "org.models.manage");
+        return this.apply(orgId, provider, change, actor);
+    }
+    async apply(orgId, provider, change, actor) {
+        if (!this.extensions.list("model-provider").some((e) => e.plugin === provider)) {
+            throw new ApiError("model.provider_not_found", `Model provider ${provider} is not installed`);
+        }
+        const disable = new Set(change.disable);
+        const both = change.enable.filter((m) => disable.has(m));
+        if (both.length > 0) {
+            throw new ApiError("validation_failed", `A model cannot be both disabled and enabled: ${[...new Set(both)].join(", ")}`);
+        }
+        const had = new Set((await this.rowsOf(orgId, provider)).map((r) => r.model));
+        const added = [...disable].filter((m) => !had.has(m)).sort();
+        const removed = [...new Set(change.enable)].filter((m) => had.has(m)).sort();
+        if (removed.length > 0) {
+            await this.db
+                .deleteFrom("model_disabled")
+                .where((eb) => (orgId === null ? eb("org_id", "is", null) : eb("org_id", "=", orgId)))
+                .where("provider", "=", provider)
+                .where("model", "in", removed)
+                .execute();
+        }
+        if (added.length > 0) {
+            await this.db
+                .insertInto("model_disabled")
+                .values(added.map((model) => ({
+                org_id: orgId,
+                provider,
+                model,
+                disabled_by: actor.accountId,
+            })))
+                .execute();
+        }
+        if (added.length > 0 || removed.length > 0) {
+            await audit(this.db, {
+                actorAccountId: actor.accountId,
+                ...(actor.tokenId !== undefined && { actorTokenId: actor.tokenId }),
+                ...(orgId !== null && { orgId }),
+                action: orgId === null ? "model.disabled_set" : "org.model_disabled_set",
+                target: provider,
+                detail: {
+                    scope: orgId === null ? "platform" : "org",
+                    disabled: added,
+                    enabled: removed,
+                    ...actor.auditDetail,
+                },
+            });
+        }
+        return {
+            affected: {
+                agents: await this.agentsUsing(orgId, provider, added),
+                purposes: await this.purposesUsing(orgId, provider, added),
+            },
+        };
+    }
+    /** Live agents (of `orgId`, or of every org) whose current version uses one of `models`. */
+    async agentsUsing(orgId, provider, models) {
+        if (models.length === 0)
+            return [];
+        const wanted = new Set(models);
+        let q = this.db
+            .selectFrom("agents as a")
+            .innerJoin("agent_versions as v", (j) => j.onRef("v.agent_id", "=", "a.id").onRef("v.version", "=", "a.current_version"))
+            .select(["a.id", "a.org_id", "v.definition"])
+            .where("a.deleted_at", "is", null)
+            .orderBy("a.org_id")
+            .orderBy("a.id");
+        if (orgId !== null)
+            q = q.where("a.org_id", "=", orgId);
+        const out = [];
+        for (const r of await q.execute()) {
+            const def = r.definition;
+            const uses = [def?.model, def?.fallback].some((x) => {
+                const ref = x;
+                return ref?.provider === provider && typeof ref.model === "string" && wanted.has(ref.model);
+            });
+            if (uses) {
+                out.push({
+                    id: r.id,
+                    name: typeof def?.name === "string" ? def.name : r.id,
+                    orgId: r.org_id,
+                });
+            }
+        }
+        return out;
+    }
+    /**
+     * Purpose mappings targeting one of `models`: for the platform every default and override, for
+     * an org its overrides and the deployment defaults (an org that disabled a default's model has
+     * that purpose unconfigured).
+     */
+    async purposesUsing(orgId, provider, models) {
+        if (models.length === 0)
+            return [];
+        let q = this.db
+            .selectFrom("model_purpose_mappings")
+            .select(["purpose", "org_id"])
+            .where("provider", "=", provider)
+            .where("model", "in", models)
+            .orderBy("purpose")
+            .orderBy("org_id", (ob) => ob.nullsFirst());
+        if (orgId === null) {
+            return (await q.execute()).map((r) => ({ purpose: r.purpose, orgId: r.org_id }));
+        }
+        q = q.where((eb) => eb.or([eb("org_id", "is", null), eb("org_id", "=", orgId)]));
+        const rows = await q.execute();
+        // a default the org overrides is not what the org uses
+        const overridden = new Set((await this.db
+            .selectFrom("model_purpose_mappings")
+            .select("purpose")
+            .where("org_id", "=", orgId)
+            .execute()).map((r) => r.purpose));
+        return rows
+            .filter((r) => r.org_id !== null || !overridden.has(r.purpose))
+            .map((r) => ({ purpose: r.purpose, orgId: r.org_id }));
+    }
+};
+__decorate([
+    Cacheable({ key: "capk:model-disabled:#{0}", ttl: DISABLED_TTL_SECONDS })
+], ModelEnablement.prototype, "disabledKeys", null);
+__decorate([
+    Transactional(),
+    CacheEvict({ key: `capk:model-disabled:${PLATFORM_SCOPE}` })
+], ModelEnablement.prototype, "setPlatform", null);
+__decorate([
+    Transactional(),
+    CacheEvict({ key: "capk:model-disabled:org.#{0}" })
+], ModelEnablement.prototype, "setOrg", null);
+ModelEnablement = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(TransactionHost)),
+    __param(2, Inject(CacheService)),
+    __param(3, Inject(ExtensionRegistry)),
+    __param(4, Inject(SuperAdminLock)),
+    __param(5, Inject(OrgLock))
+], ModelEnablement);
+export { ModelEnablement };
+/** The one {@link ModelEnablement}: the provider registry, purposes and the controllers read it. */
+let ModelEnablementModule = class ModelEnablementModule {
+};
+ModelEnablementModule = __decorate([
+    Module({
+        imports: [ExtensionRegistryModule, SuperAdminLockModule, OrgLockModule],
+        providers: [ModelEnablement],
+        exports: [ModelEnablement],
+    })
+], ModelEnablementModule);
+export { ModelEnablementModule };

package/dist/models/models.module.d.ts

@@ -1,3 +1,7 @@
-/** Model prices and model purposes. */
+/**
+ * Model prices, model purposes, the model disabled lists and the `ctx.models` embeddings broker.
+ * Below the extension host (the host injects {@link ModelEmbeddings} for `ctx.models`): it must not
+ * import `ExtensionsModule`.
+ */
 export declare class ModelsModule {
 }

package/dist/models/models.module.js

@@ -9,16 +9,28 @@ import { ExtensionRegistryModule } from "../extensions/registry.js";
 import { IdentityModule } from "../identity/identity.module.js";
 import { OrgLockModule } from "../orgs/org-lock.js";
 import { ProvidersModule } from "../runtime/providers.js";
+import { ModelEmbeddings } from "./embeddings.js";
+import { ModelEnablementModule } from "./enablement.js";
 import { PricesService } from "./prices.js";
 import { ModelPurposesService } from "./purposes.js";
-/** Model prices and model purposes. */
+/**
+ * Model prices, model purposes, the model disabled lists and the `ctx.models` embeddings broker.
+ * Below the extension host (the host injects {@link ModelEmbeddings} for `ctx.models`): it must not
+ * import `ExtensionsModule`.
+ */
 let ModelsModule = class ModelsModule {
 };
 ModelsModule = __decorate([
     Module({
-        imports: [ExtensionRegistryModule, IdentityModule, OrgLockModule, ProvidersModule],
-        providers: [PricesService, ModelPurposesService],
-        exports: [PricesService, ModelPurposesService],
+        imports: [
+            ExtensionRegistryModule,
+            IdentityModule,
+            OrgLockModule,
+            ProvidersModule,
+            ModelEnablementModule,
+        ],
+        providers: [PricesService, ModelPurposesService, ModelEmbeddings],
+        exports: [PricesService, ModelPurposesService, ModelEnablementModule, ModelEmbeddings],
     })
 ], ModelsModule);
 export { ModelsModule };

package/dist/models/org-models.schemas.d.ts

@@ -0,0 +1,8 @@
+import { z } from "zod";
+import type { RouteSchemas } from "../platform/route-schemas.js";
+/** `:purpose` as the org purpose route takes it (`@Param`). */
+export declare const ModelPurposePathParams: z.ZodObject<{
+    purpose: z.ZodString;
+}, z.core.$strip>;
+/** The org's model routes (the admin console's are the platform-admin domain's). */
+export declare const ORG_MODEL_ROUTES: readonly RouteSchemas[];

package/dist/models/org-models.schemas.js

@@ -0,0 +1,22 @@
+import { z } from "zod";
+import { ModelsQuery } from "../agents/models.controller.js";
+import { ModelDisabledPatch, ModelProviderParams } from "./enablement.controller.js";
+import { PURPOSE_PUT } from "./purposes.js";
+/** `:purpose` as the org purpose route takes it (`@Param`). */
+export const ModelPurposePathParams = z.object({ purpose: z.string().min(1) });
+/** The org's model routes (the admin console's are the platform-admin domain's). */
+export const ORG_MODEL_ROUTES = [
+    { route: "GET /api/v1/orgs/:orgId/models", query: ModelsQuery },
+    { route: "GET /api/v1/orgs/:orgId/models/catalog" },
+    { route: "GET /api/v1/orgs/:orgId/model-purposes" },
+    {
+        route: "PUT /api/v1/orgs/:orgId/model-purposes/:purpose",
+        params: ModelPurposePathParams,
+        body: PURPOSE_PUT,
+    },
+    {
+        route: "PATCH /api/v1/orgs/:orgId/models/:provider/disabled",
+        params: ModelProviderParams,
+        body: ModelDisabledPatch,
+    },
+];

package/dist/models/prices.d.ts

@@ -53,7 +53,9 @@ export declare class PricesService {
         provider: string;
         model: string;
         price: null;
-    }, actorAccountId: string, actorTokenId?: string): Promise<void>;
+    }, actorAccountId: string, actorTokenId?: string, 
+    /** Merged into the audit detail (the Platform tool's `via: "agent"`). */
+    auditDetail?: Record<string, unknown>): Promise<void>;
     /** The write of {@link put}, under the super admin lock. */
     private write;
 }

package/dist/models/prices.js

@@ -90,15 +90,17 @@ let PricesService = class PricesService {
      * 设置或删除（`price: null`）一个模型的价格：事务内取超级管理员锁并复核发起人仍是活跃超级管理员
      * （否则 `forbidden`），写审计 `model_price.updated` / `model_price.deleted`。
      */
-    async put(input, actorAccountId, actorTokenId) {
+    async put(input, actorAccountId, actorTokenId, 
+    /** Merged into the audit detail (the Platform tool's `via: "agent"`). */
+    auditDetail) {
         const check = MODEL_PRICE_PUT.safeParse(input);
         if (!check.success) {
             throw new ApiError("validation_failed", "Invalid model price", check.error.issues.map((i) => ({ path: i.path.join("."), message: i.message })));
         }
-        await this.write(check.data, actorAccountId, actorTokenId);
+        await this.write(check.data, actorAccountId, actorTokenId, auditDetail);
     }
     /** The write of {@link put}, under the super admin lock. */
-    async write(v, actorAccountId, actorTokenId) {
+    async write(v, actorAccountId, actorTokenId, auditDetail) {
         await this.adminLock.lockAndAuthorize(actorAccountId);
         const target = `${v.provider}/${v.model}`;
         if ("price" in v) {
@@ -112,7 +114,7 @@ let PricesService = class PricesService {
                 ...(actorTokenId !== undefined && { actorTokenId }),
                 action: "model_price.deleted",
                 target,
-                detail: { provider: v.provider, model: v.model },
+                detail: { provider: v.provider, model: v.model, ...auditDetail },
             });
             return;
         }
@@ -133,7 +135,7 @@ let PricesService = class PricesService {
             ...(actorTokenId !== undefined && { actorTokenId }),
             action: "model_price.updated",
             target,
-            detail: { ...v },
+            detail: { ...v, ...auditDetail },
         });
     }
 };

package/dist/models/purposes.d.ts

@@ -13,7 +13,9 @@ import { ProviderRegistry } from "../runtime/providers.js";
  * - 用途 = 内核用途 {@link KERNEL_PURPOSES}（目前只有评委 `eval`），或已加载插件 `permissions.models` 声明的；
  * - 映射 = 部署默认（`org_id` 为 null，超级管理员设）+ 组织覆盖（组织管理员设，`org.models.manage`）；
  *   生效的映射先取组织覆盖、再取部署默认，都没有 → `model.unconfigured`；
- * - 目标模型按部署范围解析（与运行时一致），参数按目标模型自己的声明严格校验；不做模型白名单；
+ * - a target's kind must equal the purpose's kind; an org's override must be enabled in the org on
+ *   save (a deployment default: not disabled on the platform), and an effective target disabled in
+ *   the org (by either layer) counts as unconfigured there (spec B §5.3)；参数按目标模型自己的声明严格校验；
  * - 每次都查 PG，不在进程内缓存（多副本下改映射立即生效）。`ctx.models` 仍预留，插件暂不能调用。
  */
 /**
@@ -139,7 +141,7 @@ export declare class ModelPurposesService {
     readonly txHost: TransactionHost;
     private readonly adminLock;
     private readonly orgLock;
-    constructor(db: KernelDb, extensions: ExtensionRegistry, config: KernelConfigService, providers: Pick<ProviderRegistry, "resolve">, txHost: TransactionHost, adminLock: SuperAdminLock, orgLock: OrgLock);
+    constructor(db: KernelDb, extensions: ExtensionRegistry, config: KernelConfigService, providers: Pick<ProviderRegistry, "resolve" | "platformInfo">, txHost: TransactionHost, adminLock: SuperAdminLock, orgLock: OrgLock);
     /** 全部已声明的用途：内核的在前，其后按插件加载顺序。 */
     private declared;
     private find;
@@ -147,16 +149,38 @@ export declare class ModelPurposesService {
     private views;
     /** 全部用途与映射；不给 `orgId` = 部署级视图（`override` 一律为 null）。 */
     list(orgId?: string): Promise<PurposeView[]>;
-    /** 校验目标：模型可解析（部署范围）、参数按它的声明严格通过。 */
+    /**
+     * 校验目标：模型可解析且启用（an org's override for the org, a deployment default in the
+     * platform view）、its kind is the purpose's `kind`、参数按它的声明严格通过。
+     */
     private check;
     private set;
+    /**
+     * The checks {@link set} runs before writing, nothing written: an unknown purpose, and a target
+     * model the scope cannot use, of another kind, or with invalid params (the Platform tool's
+     * precheck, so a known failure never reaches the confirmation card).
+     */
+    validate(orgId: string | null, purpose: string, target: PurposeTarget | null): Promise<void>;
     /** The mapping write of {@link set}, under the super admin or org lock. */
     private write;
     /** 设置（或 `null` 清除）部署默认；只有超级管理员（事务内复核）。 */
-    setDefault(purpose: string, target: PurposeTarget | null, actor: string, actorTokenId?: string): Promise<PurposeView>;
+    setDefault(purpose: string, target: PurposeTarget | null, actor: string, actorTokenId?: string, 
+    /** Merged into the audit detail (a write made through the Platform tool). */
+    auditDetail?: Record<string, unknown>): Promise<PurposeView>;
     /** 设置（或 `null` 清除）组织覆盖；事务内锁组织并复核 `org.models.manage`。 */
-    setOrg(orgId: string, purpose: string, target: PurposeTarget | null, actor: string, actorTokenId?: string): Promise<PurposeView>;
-    /** 生效的映射：组织覆盖，否则部署默认；都没有 → `model.unconfigured`；用途未声明 → `model.purpose_unknown`。 */
+    setOrg(orgId: string, purpose: string, target: PurposeTarget | null, actor: string, actorTokenId?: string, 
+    /** Merged into the audit detail (a write made through the Platform tool). */
+    auditDetail?: Record<string, unknown>): Promise<PurposeView>;
+    /**
+     * 生效的映射：组织覆盖，否则部署默认；都没有 → `model.unconfigured`；用途未声明 → `model.purpose_unknown`。
+     * An effective target the org cannot use counts as unconfigured there (spec B §5.3): checked in
+     * the registry's org view, so a model the platform or the org disabled, a provider off or needing
+     * configuration in the org, a model gone from the org's list or of another kind than the purpose
+     * all give `model.unconfigured`. A provider whose list fails (`ProviderListError`) keeps the
+     * mapping: the call that follows resolves the model again and fails there, retryably, so paths
+     * that only read the mapping (sub-agent tiers, eval start, `ctx.models.describe`) do not fail on
+     * a transient list error.
+     */
     resolve(orgId: string, purpose: string): Promise<PurposeTarget>;
     /** The target a {@link chat} call on `purpose` uses: the mapping, else `fallback` when unmapped. */
     private chatTarget;