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

package/dist/catalog/component-scope.controller.js

@@ -0,0 +1,287 @@
+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 { Controller, Get, HttpCode, Inject, Post, Put, Req } from "@nestjs/common";
+import { z } from "zod";
+import { ApiError } from "../errors.js";
+import { CurrentPrincipal, patTokenId, requireUser, SuperAdmin, } from "../identity/principal.js";
+import { createZodDto } from "../infra/validation/create-zod-dto.js";
+import { ZBody, ZParam, ZQuery } from "../infra/validation/zod-params.js";
+import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
+import { ComponentScopeService, } from "./component-scope.service.js";
+import { COMPONENT_KINDS } from "./component-state.js";
+import { PlatformComponents } from "./platform-components.js";
+const Kind = z.enum(COMPONENT_KINDS);
+const Scope = z.enum(["all", "optional", "named"]);
+const Orgs = z.array(z.string().min(1).max(128)).max(1000);
+const Hash = z.string().min(1).max(128);
+const ComponentParams = z.object({ kind: Kind, id: z.string().min(1).max(128) });
+const ListQuery = z.object({ kind: Kind }).strict();
+const OrgListQuery = z
+    .object({ kind: Kind.optional(), itemId: z.string().uuid().optional() })
+    .strict();
+/** `{ scope, orgs? }`, `{ disabled: true }` or `{ follow: true }`: exactly one. */
+const PreviewBody = z
+    .object({
+    scope: Scope.optional(),
+    orgs: Orgs.optional(),
+    disabled: z.literal(true).optional(),
+    follow: z.literal(true).optional(),
+})
+    .strict()
+    .refine((b) => [b.scope !== undefined, b.disabled === true, b.follow === true].filter(Boolean).length === 1, { message: "send exactly one of scope (with orgs for named), disabled: true or follow: true" })
+    .refine((b) => b.scope !== undefined || b.orgs === undefined, {
+    message: "orgs: only allowed with scope named",
+    path: ["orgs"],
+});
+/** `{ scope, orgs?, scopeHash }` or `{ follow: true, scopeHash }`. */
+const ScopeBody = z
+    .object({
+    scope: Scope.optional(),
+    orgs: Orgs.optional(),
+    follow: z.literal(true).optional(),
+    scopeHash: Hash,
+})
+    .strict()
+    .refine((b) => (b.scope !== undefined) !== (b.follow === true), {
+    message: "send either scope (with orgs for named) or follow: true",
+})
+    .refine((b) => b.scope !== undefined || b.orgs === undefined, {
+    message: "orgs: only allowed with scope named",
+    path: ["orgs"],
+});
+const DisabledBody = z.object({ disabled: z.boolean(), scopeHash: Hash.optional() }).strict();
+const ShownBody = z.object({ shownToOthers: z.boolean() }).strict();
+const SwitchBody = z
+    .object({
+    enabled: z.boolean(),
+    confirm: z
+        .string()
+        .regex(/^[0-9a-f]{64}$/)
+        .optional(),
+})
+    .strict();
+const IdParams = z.object({ id: z.string().min(1).max(128) });
+const TemplateVersionBody = z.object({ content: z.string().min(1).max(400_000) }).strict();
+class ComponentIdParams extends createZodDto(IdParams, "ComponentIdParams") {
+}
+class TemplateVersionDto extends createZodDto(TemplateVersionBody, "TemplateVersionBody") {
+}
+class ComponentParamsDto extends createZodDto(ComponentParams, "ComponentParams") {
+}
+class ComponentListQuery extends createZodDto(ListQuery, "ComponentListQuery") {
+}
+class OrgComponentListQuery extends createZodDto(OrgListQuery, "OrgComponentListQuery") {
+}
+class ComponentScopePreviewBody extends createZodDto(PreviewBody, "ComponentScopePreviewBody") {
+}
+class ComponentScopeBody extends createZodDto(ScopeBody, "ComponentScopeBody") {
+}
+class ComponentDisabledBody extends createZodDto(DisabledBody, "ComponentDisabledBody") {
+}
+class ComponentShownBody extends createZodDto(ShownBody, "ComponentShownBody") {
+}
+class ComponentSwitchBody extends createZodDto(SwitchBody, "ComponentSwitchBody") {
+}
+const actorOpts = (actor) => {
+    const tokenId = patTokenId(actor);
+    return tokenId !== undefined ? { actorTokenId: tokenId } : {};
+};
+/**
+ * Platform components (`/api/v1/admin/components/*`, super admins; plugin scope phase 2, Task 6):
+ * the global list of skills, agent templates and connector templates, and each one's own scope,
+ * disable and visibility (spec §5 rules 2, 4, 8, 10). Changes that take something away are
+ * previewed (`POST …/scope/preview`) and confirmed with `scopeHash`.
+ */
+let AdminComponentsController = class AdminComponentsController {
+    scope;
+    components;
+    constructor(scope, components) {
+        this.scope = scope;
+        this.components = components;
+    }
+    /**
+     * Updates a platform skill on its own (spec §7.2): the skill package (zip) as the raw body
+     * (`application/octet-stream`, at most `packages.maxBytes`). The package keeps the skill's name
+     * (400 `validation_failed`), is checked like an org upload (400 `skill.invalid_package`), and
+     * becomes the next version, flagged as updated on its own; it keeps its plugin and serves in
+     * orgs at once. Unknown component -> 404 `component.not_found`. Audits `component.version_uploaded`.
+     */
+    uploadSkillVersion(principal, p, req) {
+        const actor = requireUser(principal);
+        const body = req.body;
+        if (!Buffer.isBuffer(body) || body.byteLength === 0) {
+            throw new ApiError("unsupported_media_type", "Send the skill package (.zip) as the request body with content-type application/octet-stream");
+        }
+        return this.components.uploadSkillVersion({ accountId: actor.account.id, ...actorOpts(actor) }, p.id, new Uint8Array(body.buffer, body.byteOffset, body.byteLength));
+    }
+    /** Updates a platform agent template on its own: `{ content }` is the template markdown file. */
+    uploadAgentTemplateVersion(principal, p, body) {
+        const actor = requireUser(principal);
+        return this.components.uploadAgentTemplateVersion({ accountId: actor.account.id, ...actorOpts(actor) }, p.id, body.content);
+    }
+    /** `GET ?kind=`: every platform component of the kind (plugin, owner, scope, version, orgs on). */
+    async list(q) {
+        return { components: await this.scope.list(q.kind) };
+    }
+    /**
+     * A component's versions, newest first: `{ versions: [{ version, catalogVersion, updatedOnOwn,
+     * createdAt }] }` (a connector template keeps no history: its current version only). Unknown or
+     * removed -> 404 `component.not_found`.
+     */
+    async versions(p) {
+        return { versions: await this.scope.versions(p.kind, p.id) };
+    }
+    /**
+     * What a component scope change (`{ scope, orgs? }`), a disable (`{ disabled: true }`) or a
+     * return to its plugin's scope (`{ follow: true }`) would do: `{ affected: [{ orgId, orgName,
+     * agents }], conflicts: [{ orgId, orgName, name, skills }], scopeHash }`. Unknown component ->
+     * 404 `component.not_found`; of a builtin plugin -> 409 `plugin.builtin`.
+     */
+    preview(p, body) {
+        return this.scope.preview(p.kind, p.id, body.scope !== undefined
+            ? { scope: body.scope, ...(body.orgs !== undefined && { orgs: body.orgs }) }
+            : body.disabled === true
+                ? { disabled: true }
+                : { follow: true });
+    }
+    /**
+     * Gives the component its own scope, or makes it follow its plugin again, confirmed with the
+     * preview's `scopeHash` (a difference -> 409 `plugin.scope_stale`); an org whose own skill has
+     * its name would newly be offered it -> 409 `plugin.skill_conflict`. Audits
+     * `component.scope_changed`.
+     */
+    setScope(principal, p, body) {
+        const actor = requireUser(principal);
+        return this.scope.setScope(actor.account.id, p.kind, p.id, body.scope !== undefined
+            ? {
+                scope: body.scope,
+                scopeHash: body.scopeHash,
+                ...(body.orgs !== undefined && { orgs: body.orgs }),
+            }
+            : { follow: true, scopeHash: body.scopeHash }, actorOpts(actor));
+    }
+    /** Disables the component on the deployment (`scopeHash` required) or enables it again. */
+    setDisabled(principal, p, body) {
+        const actor = requireUser(principal);
+        return this.scope.setDisabled(actor.account.id, p.kind, p.id, {
+            disabled: body.disabled,
+            ...(body.scopeHash !== undefined && { scopeHash: body.scopeHash }),
+        }, actorOpts(actor));
+    }
+    /** Shows or hides the component to orgs outside its `named` list. */
+    setShown(principal, p, body) {
+        const actor = requireUser(principal);
+        return this.scope.setShown(actor.account.id, p.kind, p.id, body.shownToOthers, actorOpts(actor));
+    }
+};
+__decorate([
+    Post("skill/:id/versions"),
+    HttpCode(201),
+    __param(0, CurrentPrincipal()),
+    __param(1, ZParam(ComponentIdParams)),
+    __param(2, Req())
+], AdminComponentsController.prototype, "uploadSkillVersion", null);
+__decorate([
+    Post("agent_template/:id/versions"),
+    HttpCode(201),
+    __param(0, CurrentPrincipal()),
+    __param(1, ZParam(ComponentIdParams)),
+    __param(2, ZBody(TemplateVersionDto))
+], AdminComponentsController.prototype, "uploadAgentTemplateVersion", null);
+__decorate([
+    Get(),
+    __param(0, ZQuery(ComponentListQuery))
+], AdminComponentsController.prototype, "list", null);
+__decorate([
+    Get(":kind/:id/versions"),
+    __param(0, ZParam(ComponentParamsDto))
+], AdminComponentsController.prototype, "versions", null);
+__decorate([
+    Post(":kind/:id/scope/preview"),
+    HttpCode(200),
+    __param(0, ZParam(ComponentParamsDto)),
+    __param(1, ZBody(ComponentScopePreviewBody))
+], AdminComponentsController.prototype, "preview", null);
+__decorate([
+    Put(":kind/:id/scope"),
+    __param(0, CurrentPrincipal()),
+    __param(1, ZParam(ComponentParamsDto)),
+    __param(2, ZBody(ComponentScopeBody))
+], AdminComponentsController.prototype, "setScope", null);
+__decorate([
+    Put(":kind/:id/disabled"),
+    __param(0, CurrentPrincipal()),
+    __param(1, ZParam(ComponentParamsDto)),
+    __param(2, ZBody(ComponentDisabledBody))
+], AdminComponentsController.prototype, "setDisabled", null);
+__decorate([
+    Put(":kind/:id/shown"),
+    __param(0, CurrentPrincipal()),
+    __param(1, ZParam(ComponentParamsDto)),
+    __param(2, ZBody(ComponentShownBody))
+], AdminComponentsController.prototype, "setShown", null);
+AdminComponentsController = __decorate([
+    Controller("api/v1/admin/components"),
+    SuperAdmin(),
+    __param(0, Inject(ComponentScopeService)),
+    __param(1, Inject(PlatformComponents))
+], AdminComponentsController);
+export { AdminComponentsController };
+/**
+ * An org admin's switch of one platform component (`PUT orgs/:orgId/components/:kind/:id/switch`,
+ * spec §5 rule 5, §13.5): `{ enabled: true }` -> 200 `{ component }`; `{ enabled: false }` on a
+ * component in use -> 200 `{ preview: { agents }, confirm }`, then with `confirm` -> `{ component }`.
+ * The route needs `catalog.read`; the service re-checks the kind's manage action (org admins).
+ */
+let OrgComponentsController = class OrgComponentsController {
+    scope;
+    constructor(scope) {
+        this.scope = scope;
+    }
+    /**
+     * The platform components offered to the org (`?kind=`, `?itemId=`: only those; Task 10): each
+     * with its state in the org (`on`, `locked` for `all`, the org's `switch`) and whether an org
+     * admin may switch it. Members read it (the workspace pages are read-only for them).
+     */
+    async list(org, q) {
+        return {
+            components: await this.scope.orgList(org.orgId, {
+                ...(q.kind !== undefined && { kind: q.kind }),
+                ...(q.itemId !== undefined && { itemId: q.itemId }),
+            }),
+        };
+    }
+    async setSwitch(principal, org, p, body) {
+        const actor = requireUser(principal);
+        const r = await this.scope.setSwitch(org.orgId, actor.account.id, p.kind, p.id, { enabled: body.enabled, ...(body.confirm !== undefined && { confirm: body.confirm }) }, patTokenId(actor));
+        return r.kind === "done"
+            ? { component: r.component }
+            : { preview: r.preview, confirm: r.confirm };
+    }
+};
+__decorate([
+    Get(),
+    OrgAction("catalog.read"),
+    __param(0, CurrentOrg()),
+    __param(1, ZQuery(OrgComponentListQuery))
+], OrgComponentsController.prototype, "list", null);
+__decorate([
+    Put(":kind/:id/switch"),
+    OrgAction("catalog.read"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(ComponentParamsDto)),
+    __param(3, ZBody(ComponentSwitchBody))
+], OrgComponentsController.prototype, "setSwitch", null);
+OrgComponentsController = __decorate([
+    Controller("api/v1/orgs/:orgId/components"),
+    __param(0, Inject(ComponentScopeService))
+], OrgComponentsController);
+export { OrgComponentsController };

package/dist/catalog/component-scope.service.d.ts

@@ -0,0 +1,303 @@
+import { ApiError } from "../errors.js";
+import { SuperAdminLock } from "../identity/super-admin.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { OrgLock } from "../orgs/org-lock.js";
+import type { ActorOpts } from "./catalog.service.js";
+import { ComponentPromotion } from "./component-promotion.js";
+import { type ComponentKind } from "./component-state.js";
+import { type Owner } from "./ownership.js";
+import type { PluginScope } from "./scope.js";
+/**
+ * What a component scope change, a component disable or a switch back to its plugin's scope would
+ * do (spec §5 rules 8 and 10): the orgs where it is on now and would be off, with their agents that
+ * use it (by its id or an org copy linked to it), and the orgs it would newly be offered to whose
+ * own skills already use its name (the change is refused while there are any). `scopeHash` is
+ * confirmed with the change.
+ */
+export interface ComponentScopePreview {
+    affected: {
+        orgId: string;
+        orgName: string;
+        agents: {
+            id: string;
+            name: string;
+        }[];
+        /** A connector template: the org's connectors made from it, which stay as the org's own. */
+        connectorsKept: number;
+    }[];
+    /**
+     * `skills`: the clashing skill ids (org skills, other platform skills; for an agent template the
+     * clashing template ids, `name` its roster type, ruling P4-13); `plugins`: theirs.
+     */
+    conflicts: {
+        orgId: string;
+        orgName: string;
+        name: string;
+        skills: string[];
+        plugins: string[];
+        /** An agent template's: the owner of each clashing template, in `skills`' order. */
+        owners?: Owner[];
+    }[];
+    scopeHash: string;
+}
+/** A component's own scope (`orgs` only with `named`), a disable, or following its plugin again. */
+export type ComponentTarget = {
+    scope: PluginScope;
+    orgs?: string[];
+} | {
+    disabled: boolean;
+} | {
+    follow: true;
+};
+/**
+ * A component in the admin list (`GET admin/components`): a platform component, or (ruling P2-11)
+ * an org's own skill or agent template, listed read-only (`owner` = the org; its scope fields
+ * say it is on in that org only; scope, disable and uploads are platform-only, 404 for it).
+ */
+export interface ComponentView {
+    kind: ComponentKind;
+    id: string;
+    name: string;
+    description: string | null;
+    /** The plugin it came from (null: none). */
+    plugin: string | null;
+    itemId: string | null;
+    /** The platform, or the org that owns it (ruling P3-1). */
+    owner: Owner;
+    /** Its owner shares it with other orgs (the share gate; always false for the platform's). */
+    shareable: boolean;
+    /**
+     * A platform row created from an org's own skill or agent template when it was first shared
+     * (promote on share, ruling P3-3); false for an org row and for a plugin's component.
+     */
+    promoted: boolean;
+    /** Of a builtin plugin: on everywhere, its scope cannot be changed nor disabled (409). */
+    builtin: boolean;
+    scopeMode: "follow" | "own";
+    /** The effective scope: the plugin's (builtin: `all`) when following it, else its own. */
+    scope: PluginScope;
+    /** The effective `named` list (the plugin's when following it), sorted. */
+    orgs: string[];
+    disabled: boolean;
+    /** The plugin is disabled or deleted: the component is off everywhere. */
+    pluginStopped: boolean;
+    shownToOthers: boolean;
+    version: string;
+    /** The orgs it is on in now, sorted. */
+    onIn: string[];
+    /**
+     * Orgs whose admin switched it off while its effective scope is `all` (layering spec §4); 0 for
+     * other scopes, builtin plugins and orgs' own rows.
+     */
+    offCount: number;
+}
+/** One version of a platform component (`GET admin/components/:kind/:id/versions`). */
+export interface ComponentVersionView {
+    /** The component's own version counter (a connector template: its catalog version). */
+    version: string;
+    /** The plugin version it came from (null: uploaded on its own). */
+    catalogVersion: string | null;
+    /** Written by an upload of the component on its own (spec §7.2). */
+    updatedOnOwn: boolean;
+    createdAt: string;
+}
+/** An org's view of one component after its switch. */
+export interface OrgComponentView {
+    kind: ComponentKind;
+    id: string;
+    name: string;
+    plugin: string | null;
+    /** The org's switch (null: never switched). */
+    switch: boolean | null;
+    on: boolean;
+    /** Of a builtin plugin: it cannot be switched off (an `all` one can, layering spec §4). */
+    locked: boolean;
+}
+/**
+ * A platform component offered to an org (`GET orgs/:orgId/components`, Task 10): on there, or one
+ * an org admin could switch on; what the workspace 技能 / 智能体模板 pages and the plugin detail
+ * show with their switches. Never a component the org cannot see.
+ */
+export interface OrgOfferedComponentView extends OrgComponentView {
+    description: string | null;
+    itemId: string | null;
+    version: string;
+    scopeMode: "follow" | "own";
+    /** A `follow` component's plugin is on in the org (always true for `own`). */
+    pluginOn: boolean;
+    /**
+     * An org admin may switch it now: not locked, and (`follow`) its plugin is on in the org (a
+     * component of a plugin that is off is switched on with the plugin, spec §5 rule 5).
+     */
+    switchable: boolean;
+    /** On by platform default: the effective scope (its own, or its plugin's) is `all` and it is not builtin. */
+    platformDefault: boolean;
+    /**
+     * The org's copies linked to it without a pin (skills, agent templates): agents that select one
+     * of these ids use this component, and lose it while it is off (spec §5 rule 8).
+     */
+    linkedIds: string[];
+    /**
+     * The platform, or the org that owns it (an org's upload, ruling P3-1): what the workspace pages
+     * name as its owner (本组织 for the viewing org's own, the owner's name for another org's).
+     */
+    owner: Owner;
+}
+/** The result of an org switch: the component, or (switching off without `confirm`) the preview. */
+export type ComponentSwitchResult = {
+    kind: "done";
+    component: OrgComponentView;
+} | {
+    kind: "preview";
+    preview: {
+        agents: {
+            id: string;
+            name: string;
+            refs: string[];
+        }[];
+        connectorsKept: number;
+    };
+    confirm: string;
+};
+/**
+ * 409 `plugin.skill_conflict` listing the orgs whose own skills use a component's name (rule 10);
+ * for an agent template 409 `agent_template.name_taken` listing the orgs that already use its
+ * roster type (ruling P4-13; details `[{ orgId, type, templateId, owner }]`, one per clashing
+ * template, `owner` as save-as names it).
+ */
+export declare function nameConflictError(conflicts: ComponentScopePreview["conflicts"], kind?: ComponentKind): ApiError;
+/**
+ * Component scope and org switches (plugin scope phase 2, Task 6; spec §5 rules 2, 5, 8, 10, 11,
+ * §13.5). The super admin gives a platform component its own scope (`all` / `optional` / `named`),
+ * sends it back to following its plugin, disables it on the whole deployment or shows it to other
+ * orgs; each change that takes something away is previewed and confirmed with `scopeHash`
+ * (recomputed under the component row lock; a difference -> 409 `plugin.scope_stale`), and one that
+ * would offer a skill to an org whose own skill has its name is refused (409 `plugin.skill_conflict`).
+ * An org admin switches one component on or off in the org (only that component, rule 5); one of a
+ * builtin plugin -> 409 `plugin.scope_locked` (an `all` one may go off, layering spec §4); switching
+ * off something in use is previewed with its agents first.
+ * Name clashes are checked for skills only: an org agent template always carries its plugin's
+ * type, so one with a platform template's type is a copy of it. Components are resolved at read
+ * time (skills/usable.ts, agents/templates.ts), so nothing is enqueued. Stateless, shared by every
+ * replica.
+ */
+export declare class ComponentScopeService {
+    private readonly kdb;
+    private readonly adminLock;
+    /** The org row lock (orgs/org-lock.ts): joins the caller's transaction. */
+    private readonly orgLock;
+    /** Promote on share (ruling P3-3): an org row shown or associated becomes a platform row. */
+    private readonly promotion;
+    readonly txHost: TransactionHost;
+    constructor(kdb: KernelDb, adminLock: SuperAdminLock, 
+    /** The org row lock (orgs/org-lock.ts): joins the caller's transaction. */
+    orgLock: OrgLock, 
+    /** Promote on share (ruling P3-3): an org row shown or associated becomes a platform row. */
+    promotion: ComponentPromotion, txHost: TransactionHost);
+    private get db();
+    /**
+     * What the admin routes act on (ruling P3-23): the platform component `id`, an org row the org
+     * promoted already (its platform row), or an org's own row not promoted yet. A connector
+     * template has no org rows; anything else -> 404 `component.not_found`.
+     */
+    private resolve;
+    /**
+     * Runs `write` with the org row prepared for promotion ({@link ComponentPromotion.prepare}, files
+     * copied before the transaction), preparing again when the row changed meanwhile.
+     */
+    private withPromotion;
+    /** The platform components of `kind`, with their effective scope and the orgs they are on in. */
+    list(kind: ComponentKind): Promise<ComponentView[]>;
+    /**
+     * The platform components offered to the org (`kind` / `itemId`: only those), by kind then name:
+     * on there, or visible to it and not stopped on the deployment (spec §5 rules 5, 11, §13.5).
+     */
+    orgList(orgId: string, filter: {
+        kind?: ComponentKind;
+        itemId?: string;
+    }): Promise<OrgOfferedComponentView[]>;
+    /**
+     * The org's copies of platform skills or agent templates linked without a pin (ruling B2), by
+     * platform id: they resolve to it, so agents that select them use it (none for connector
+     * templates).
+     */
+    private linkedCopies;
+    /**
+     * The orgs' own skills (org scope) and agent templates, not linked to a platform component
+     * (ruling P2-11): listed read-only, on in their org only. Connector templates have none.
+     */
+    private orgOwned;
+    /** The preview of a scope change, a disable or a return to following the plugin (nothing written). */
+    preview(kind: ComponentKind, id: string, target: ComponentTarget): Promise<ComponentScopePreview>;
+    /** Gives the component its own scope, or makes it follow its plugin again, after its preview. */
+    setScope(actor: string, kind: ComponentKind, id: string, body: ({
+        scope: PluginScope;
+        orgs?: string[];
+    } | {
+        follow: true;
+    }) & {
+        scopeHash: string;
+    }, opts?: ActorOpts): Promise<ComponentView>;
+    /**
+     * Disables the component on the whole deployment (after its preview, `scopeHash` required) or
+     * enables it again (no hash; refused while an org it would be offered to has a skill of its name).
+     */
+    setDisabled(actor: string, kind: ComponentKind, id: string, body: {
+        disabled: boolean;
+        scopeHash?: string;
+    }, opts?: ActorOpts): Promise<ComponentView>;
+    /** Shows or hides the component to orgs outside its `named` list (never makes it usable). */
+    setShown(actor: string, kind: ComponentKind, id: string, shown: boolean, opts?: ActorOpts): Promise<ComponentView>;
+    /**
+     * The org admin's switch of one component (`PUT orgs/:orgId/components/:kind/:id/switch`): only
+     * this component (rule 5). A component not offered to the org -> 404. On: refused while the
+     * component or its plugin is disabled (`plugin.disabled`) or an own skill of the org has its name
+     * (`plugin.skill_conflict`, rule 10). Off: of a builtin plugin -> `plugin.scope_locked`; while it
+     * is on, without `confirm` the preview (agents that use it) and its hash are returned, with the
+     * current hash the switch is written (a changed preview -> `plugin.switch_stale`).
+     */
+    setSwitch(orgId: string, actor: string, kind: ComponentKind, id: string, body: {
+        enabled: boolean;
+        confirm?: string;
+    }, actorTokenId?: string): Promise<ComponentSwitchResult>;
+    /**
+     * `x.hashId`: the id the preview was asked for (an org row's id before its promotion);
+     * `x.promote`: the org row to promote first, in this transaction. Returns the id written.
+     */
+    private writeScope;
+    private writeDisabled;
+    /** `promote`: the org row to promote first, in this transaction. Returns the id written. */
+    private writeShown;
+    /**
+     * A live component's versions, newest first. A connector template keeps no history: its one entry
+     * is the current version. Missing (or removed) -> 404 `component.not_found`.
+     */
+    versions(kind: ComponentKind, id: string): Promise<ComponentVersionView[]>;
+    /** An org-owned skill's or agent template's versions (ruling P2-11); else 404. */
+    private orgOwnedVersions;
+    private view;
+    /** The live component (row locked with `forUpdate`); missing -> 404, of a builtin plugin -> 409. */
+    private component;
+    /**
+     * The scope that offers the component now: its own (`listed`: its own list), or for `follow` its
+     * plugin's (`all` for a builtin or deleted plugin: the widest, so nothing counts as widening).
+     */
+    private effectiveScope;
+    /** The component's own `named` list, sorted. */
+    private listed;
+    /**
+     * The state after the change: `orgs` only with `named`, each a live org. `listed`: the list now
+     * (an org row not promoted yet: `[owner]`), else read.
+     */
+    private targetOf;
+    /** Live orgs (`only`: that one), sorted by id. */
+    private liveOrgs;
+    private on;
+    /**
+     * The preview of moving `c` to `target` (read through the current context). `x.hashId`: the id
+     * the hash names (the one the preview was asked for); `x.listed`: the list now of an org row not
+     * promoted yet (`[owner]`).
+     */
+    private compute;
+}