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

package/dist/catalog/org-catalog.service.js

@@ -1,345 +1,86 @@
-import { createHash } from "node:crypto";
-import { parseAgentTemplate, parseConnectorTemplateFile, } from "@capybara-hq/plugin-sdk";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable } from "@nestjs/common";
 import { ApiError } from "../errors.js";
-import { lockOrgAndAuthorize } from "../orgs/org-lock.js";
+import { ExtensionRegistry } from "../extensions/registry.js";
+import { ExtensionAvailability } from "../extensions/unavailable.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 { KERNEL_LOGGER } from "../infra/tokens.js";
+import { OrgLock } from "../orgs/org-lock.js";
 import { can, roleAtLeast } from "../orgs/roles.js";
 import { packagePath } from "../packages/tgz.js";
-import { checkSkillFiles, SkillArchiveError } from "../skills/package.js";
-import { itemView } from "./catalog.service.js";
-import { iconProblem } from "./plugin-package.js";
-import { upgradeInfo } from "./upgrade-targets.js";
-import { satisfiesRange } from "./versions.js";
-/**
- * A connector template as an org sees it (the install wizard and the upgrade preview's inputs):
- * presets and editable paths, no credentials.
- */
-export function orgTemplateView(id, file) {
-    const t = file.template;
-    return {
-        id,
-        displayName: file.displayName,
-        description: file.description ?? "",
-        plugin: t.plugin,
-        connector: t.connector,
-        endpoint: t.endpoint,
-        editableEndpoint: t.editableEndpoint ?? [],
-        auth: t.auth,
-        ownership: t.ownership ??
-            (typeof t.auth.ownership === "string" ? t.auth.ownership : null),
-    };
-}
-const iconNotFound = () => new ApiError("catalog.icon_not_found", "This catalog item has no icon");
-/**
- * The item's latest version row; item missing, deleted or (when `includeDisabled` is false)
- * disabled -> `catalog.item_not_found`.
- */
-async function latestVersionRow(db, itemId, includeDisabled) {
-    if (!UUID_RE.test(itemId))
-        throw itemNotFound();
-    const item = await db
-        .selectFrom("catalog_items")
-        .select(["latest_version", "policy"])
-        .where("id", "=", itemId)
-        .where("deleted_at", "is", null)
-        .executeTakeFirst();
-    // An item the caller cannot see is "not found" before any version / storage is read, so "no icon"
-    // never reveals that it exists
-    if (!item || (!includeDisabled && item.policy === "disabled"))
-        throw itemNotFound();
-    const v = await db
-        .selectFrom("catalog_item_versions")
-        .select(["manifest", "object_prefix", "files"])
-        .where("item_id", "=", itemId)
-        .where("version", "=", item.latest_version)
-        .executeTakeFirst();
-    if (!v)
-        throw itemNotFound();
-    return { item, v };
-}
-/** The icon's path in the version's files (undefined without an icon). */
-const iconPath = (v) => {
-    const icon = v.manifest.icon;
-    return icon === undefined ? undefined : packagePath(icon);
-};
-/** Whether the item's latest version has an icon; unreadable counts as none. */
-export async function catalogHasIcon(db, itemId) {
-    try {
-        const { v } = await latestVersionRow(db, itemId, true);
-        const path = iconPath(v);
-        return path !== undefined && v.files.some((f) => f.path === path);
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Reads the icon of the item's latest version (served only through kernel routes, with nosniff and
- * a CSP sandbox in the response headers; the web only shows it with `<img>`). Item missing, deleted
- * or (when `includeDisabled` is false) disabled -> `catalog.item_not_found` (decided before reading
- * storage); no icon -> `catalog.icon_not_found`; stored content that is not a valid svg / png
- * (checked at import, this guards against tampered storage) -> `internal`.
- */
-export async function readCatalogIcon(db, storage, itemId, includeDisabled) {
-    const { item, v } = await latestVersionRow(db, itemId, includeDisabled);
-    const path = iconPath(v);
-    const f = path === undefined ? undefined : v.files.find((x) => x.path === path);
-    if (path === undefined || !f)
-        throw iconNotFound();
-    const [file] = await readCatalogFiles(storage, v.object_prefix, [f]);
-    if (!file)
-        throw iconNotFound();
-    const problem = iconProblem(path, file.data);
-    if (problem !== undefined)
-        throw new ApiError("internal", `Stored icon is invalid: ${problem}`);
-    return {
-        data: file.data,
-        contentType: /\.svg$/i.test(path) ? "image/svg+xml" : "image/png",
-        policy: item.policy,
-    };
-}
+import { StorageService } from "../storage/storage.service.js";
+import { catalogHasIcon, findConnectorIn, orgTemplateView, readCatalogIcon, readCatalogTemplates, templatePluginProblem, } from "./catalog-content.js";
+import { itemView, ownerOnlyFacts, versionUsable } from "./catalog-items.js";
+import { connectorTemplatesOn, templateIdOfPath } from "./component-state.js";
+import { itemPendingError, ownerOf, ownersOf } from "./ownership.js";
+import { PluginInstaller, uninstallPreviewHash, upsertOrgSwitch, } from "./plugin-install.js";
+import { requestable, switchable, visibleTo, wantedOn } from "./scope.js";
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const itemNotFound = () => new ApiError("catalog.item_not_found", "Catalog item not found");
-const itemDisabled = () => new ApiError("catalog.item_disabled", "This catalog item is disabled by the enterprise admin and cannot be newly installed");
-const fail = (path, message) => new ApiError("validation_failed", "Request validation failed", [{ path, message }]);
-/**
- * The org actions installing / uninstalling a plugin needs: the union over its components (an
- * extension -> `org.extensions.manage`, skills -> `skills.manage`, connector templates ->
- * `connectors.manage`, agent templates -> `agents.manage`), re-checked inside the org row lock.
- */
-export function requiredActions(m) {
-    const out = [];
-    if (m.extension)
-        out.push("org.extensions.manage");
-    if ((m.connectorTemplates ?? []).length > 0)
-        out.push("connectors.manage");
-    if ((m.skills ?? []).length > 0)
-        out.push("skills.manage");
-    if ((m.agents ?? []).length > 0)
-        out.push("agents.manage");
-    return out.length > 0 ? out : ["org.extensions.manage"];
-}
-/** Locks the org row in the caller's transaction and re-checks the actor can do every action (else `forbidden`). */
-export async function lockOrgForActions(t, orgId, actor, actions) {
-    const [first, ...rest] = actions;
-    const { role } = await lockOrgAndAuthorize(t, orgId, actor, first);
-    for (const a of rest) {
-        if (!can(role, a))
-            throw new ApiError("forbidden", "Insufficient organization role");
-    }
-}
-const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
-const UNSAFE_KEYS = new Set(["__proto__", "prototype", "constructor"]);
-/** 对象的全部叶子点路径（数组与非对象值算叶子）。 */
-function leafPaths(v, base = "") {
-    const out = [];
-    for (const [k, x] of Object.entries(v)) {
-        const p = base ? `${base}.${k}` : k;
-        if (isObj(x) && Object.keys(x).length > 0)
-            out.push(...leafPaths(x, p));
-        else
-            out.push(p);
-    }
-    return out;
-}
-/** The value at a dot path of `v` (own keys only), undefined when absent. */
-export function getPath(v, path) {
-    let node = v;
-    for (const seg of path.split(".")) {
-        if (!isObj(node) || !Object.hasOwn(node, seg))
-            return undefined;
-        node = node[seg];
-    }
-    return node;
-}
-/** Sets the value at a dot path of `obj`, creating the objects on the way. */
-export function setPath(obj, path, value) {
-    const segs = path.split(".");
-    let node = obj;
-    for (const seg of segs.slice(0, -1)) {
-        if (!isObj(node[seg]))
-            node[seg] = {};
-        node = node[seg];
-    }
-    node[segs[segs.length - 1]] = value;
-}
-/**
- * 模板的连接器插件此刻是否可用：插件加载且提供该 kind，并满足 `pluginVersion`（若写了）；不可用返回原因
- * （模型不可见，给管理员看的英文）。
- */
-export function templatePluginProblem(d, template) {
-    if (!d.findConnector(template.plugin, template.connector)) {
-        return `Connector extension ${template.plugin} providing "${template.connector}" is not deployed; ask the enterprise admin to install and enable it`;
-    }
-    const range = template.pluginVersion;
-    const version = d.pluginVersion(template.plugin);
-    if (range !== undefined && version !== undefined && !satisfiesRange(version, range)) {
-        return `Connector extension ${template.plugin} is deployed at version ${version}, but the template needs ${range}; ask the enterprise admin to upgrade it`;
-    }
-    return undefined;
-}
+const notOffered = () => new ApiError("catalog.approval_required", "This plugin is not offered to this organization; an org admin can request access");
+const pluginDisabled = () => new ApiError("plugin.disabled", "This plugin is disabled by the super admin and cannot be switched on");
 /**
- * Builds the connector install input from a connector template plus what the org filled in (C30):
- * the endpoint comes from the template, only paths listed in `editableEndpoint` (or fields under
- * them) may be changed by the org, changing another path -> `validation_failed`; the auth method
- * comes from the template, the org only gives credentials (static credentials via `credential`,
- * OAuth via `client`). Re-checks the template's plugin, kind and `pluginVersion` against the
- * connectors loaded on this replica right now (unmet -> `catalog.not_deployed`); the endpoint
- * (merged as a whole) schema check, credential pattern check and OAuth URL policy are re-checked by
- * `ConnectorsService.create`.
+ * Organizations see the platform catalog with the plugin scope rules applied (plugin and component
+ * management spec §5): a plugin is `all` (on in every org unless an org admin switched it off,
+ * layering spec §4), `optional` (an org admin switches it on), or `named` (offered to the listed
+ * orgs). Members get the list read-only; org admins switch a plugin on (an install by
+ * {@link PluginInstaller}, with its dependencies; the union of the component actions of the plugins
+ * it brings in is re-checked inside the org row lock) or off (an uninstall, after a preview they
+ * confirm with its hash). Disabled item -> `plugin.disabled`; a
+ * dependency unresolved / disabled / in a cycle -> `catalog.dependency_*`; an extension or a
+ * template's connector not on the deployment -> `catalog.not_deployed`. No in-process state.
  */
-export function templateConnectorInput(deps, template, ref, input, defaultName, at = "connector") {
-    const problem = templatePluginProblem(deps, template);
-    if (problem !== undefined)
-        throw new ApiError("catalog.not_deployed", problem);
-    const given = input ?? {};
-    const editable = template.editableEndpoint ?? [];
-    const endpoint = structuredClone(template.endpoint);
-    if (given.endpoint !== undefined) {
-        if (!isObj(given.endpoint))
-            throw fail(`${at}.endpoint`, "Expected an object");
-        for (const p of leafPaths(given.endpoint)) {
-            const segs = p.split(".");
-            if (segs.some((s) => UNSAFE_KEYS.has(s))) {
-                throw fail(`${at}.endpoint.${p}`, "Invalid key");
-            }
-            const allowed = editable.some((e) => p === e || p.startsWith(`${e}.`));
-            if (!allowed) {
-                throw fail(`${at}.endpoint.${p}`, "This endpoint field is set by the template and cannot be changed");
-            }
-        }
-        for (const e of editable) {
-            const v = getPath(given.endpoint, e);
-            if (v !== undefined)
-                setPath(endpoint, e, v);
-        }
-    }
-    const auth = template.auth;
-    const oauth = auth.type === "oauth_code" || auth.type === "oauth_client";
-    if (oauth && given.credential !== undefined) {
-        throw fail(`${at}.credential`, "This connector uses OAuth; provide client instead");
+let OrgCatalogService = class OrgCatalogService {
+    kdb;
+    orgLock;
+    storage;
+    registry;
+    pluginInstaller;
+    log;
+    txHost;
+    availability;
+    constructor(kdb, 
+    /** The org row lock (orgs/org-lock.ts): joins the caller's transaction. */
+    orgLock, storage, registry, pluginInstaller, log, txHost, 
+    /** Why a plugin's extension cannot run (the `unavailable` state's reason). */
+    availability) {
+        this.kdb = kdb;
+        this.orgLock = orgLock;
+        this.storage = storage;
+        this.registry = registry;
+        this.pluginInstaller = pluginInstaller;
+        this.log = log;
+        this.txHost = txHost;
+        this.availability = availability;
     }
-    if (!oauth && given.client !== undefined) {
-        throw fail(`${at}.client`, "This connector does not use OAuth; provide credential instead");
+    /** The kernel-schema handle of the current context (the transaction, else the pool). */
+    get db() {
+        return this.kdb.db;
     }
-    const credential = oauth ? given.client : given.credential;
-    return {
-        name: given.name ?? defaultName,
-        ...(given.slug !== undefined && { slug: given.slug }),
-        connector: template.connector,
-        endpoint,
-        auth,
-        ...(credential !== undefined && { credential }),
-        template: {
-            ...ref,
-            ...(template.defaultToolPolicies !== undefined && {
-                defaultToolPolicies: template.defaultToolPolicies,
-            }),
-        },
-    };
-}
-/** 从部署存储读目录版本里的文件（按版本行的 sha256 校验）；`under` 给出时只读该目录下的文件，路径去掉该前缀。 */
-export async function readCatalogFiles(storage, objectPrefix, files, under) {
-    storage.assertAvailable();
-    if (objectPrefix === null)
-        return [];
-    const store = storage.deployment();
-    const dir = under === undefined ? "" : `${under}/`;
-    const out = [];
-    for (const f of files) {
-        if (!f.path.startsWith(dir))
-            continue;
-        const got = await store.get(`${objectPrefix}${f.path}`);
-        if (!got) {
-            throw new ApiError("storage.unavailable", `Catalog file ${f.path} is missing from object storage`);
-        }
-        const data = new Uint8Array(await new Response(got.body).arrayBuffer());
-        if (createHash("sha256").update(data).digest("hex") !== f.sha256) {
-            throw new ApiError("internal", `Catalog file ${f.path} does not match its recorded hash`);
-        }
-        out.push({ path: f.path.slice(dir.length), size: data.byteLength, sha256: f.sha256, data });
-    }
-    return out;
-}
-/** 校验技能文件并取名字与描述（导入时已校验过；这里防存储被改）。 */
-export function skillOf(files) {
-    try {
-        // Stored files: a version imported before phase D keeps installing (its invocation keys are
-        // read leniently; `skillInvocation` ignores values of the wrong type)
-        return checkSkillFiles(files, { invocationKeys: false });
-    }
-    catch (e) {
-        if (e instanceof SkillArchiveError) {
-            throw new ApiError("internal", `Stored skill is invalid: ${e.problems.join("; ")}`);
-        }
-        throw e;
-    }
-}
-/** The connector templates of a catalog version, read from storage (id = the file's base name). */
-export async function readCatalogTemplates(storage, v) {
-    const refs = v.manifest.connectorTemplates ?? [];
-    if (refs.length === 0)
-        return [];
-    const paths = refs.map((r) => packagePath(r.path));
-    const files = await readCatalogFiles(storage, v.object_prefix, v.files.filter((f) => paths.includes(f.path)));
-    return paths.map((path) => {
-        const f = files.find((x) => x.path === path);
-        let parsed;
-        try {
-            parsed = f && parseConnectorTemplateFile(JSON.parse(new TextDecoder().decode(f.data)));
-        }
-        catch {
-            parsed = undefined;
-        }
-        if (!parsed || "errors" in parsed) {
-            throw new ApiError("internal", `Stored connector template ${path} is missing or invalid`);
-        }
-        return { id: path.split("/").pop().replace(/\.json$/, ""), file: parsed };
-    });
-}
-/**
- * The agent templates of a catalog version (`manifest.agents`, listed explicitly since import),
- * parsed from storage (checked at import; parsed again in case storage was changed).
- */
-export async function readCatalogAgentTemplates(storage, v) {
-    const refs = v.manifest.agents ?? [];
-    if (refs.length === 0)
-        return [];
-    const paths = refs.map((r) => packagePath(r.path));
-    const files = await readCatalogFiles(storage, v.object_prefix, v.files.filter((f) => paths.includes(f.path)));
-    return paths.map((path) => {
-        const f = files.find((x) => x.path === path);
-        const parsed = f && parseAgentTemplate(new TextDecoder().decode(f.data));
-        if (!parsed || "errors" in parsed) {
-            throw new ApiError("internal", `Stored agent template ${path} is missing or invalid`);
-        }
-        return { path, template: parsed.template };
-    });
-}
-/**
- * Organizations browse and install from the enterprise catalog (C22): members browse (without
- * disabled items) and request, org admins install. Every item is a plugin, installed with its
- * dependencies by {@link PluginInstaller}; installing requires the union of the component actions
- * of the plugins it brings in ({@link requiredActions}), re-checked inside the org row lock; item
- * disabled -> `catalog.item_disabled`; a dependency unresolved / disabled / in a cycle ->
- * `catalog.dependency_*`; an extension or a template's connector not on the deployment ->
- * `catalog.not_deployed`; needs_approval without a grant -> a stage deployment request (HTTP 202;
- * dependencies are not approved separately, spec §10). No in-process state.
- */
-export class OrgCatalogService {
-    d;
-    constructor(d) {
-        this.d = d;
-    }
-    /** The org's view of the items; members (not admins) don't see disabled items. */
+    /**
+     * The org's view of the items: a `named` item without the org on its list is `not_offered` when
+     * shown to other orgs and absent otherwise; disabled ones are shown to admins as `unavailable`
+     * and absent for members. Each item carries the org's pending request for it.
+     */
     async list(orgId, accountId, itemId) {
-        const m = await this.d.db
+        const m = await this.db
             .selectFrom("memberships")
             .select("role")
             .where("org_id", "=", orgId)
             .where("account_id", "=", accountId)
             .executeTakeFirst();
         const isAdmin = m !== undefined && roleAtLeast(m.role, "admin");
-        let q = this.d.db
+        let q = this.db
             .selectFrom("catalog_items")
             .selectAll()
             .where("deleted_at", "is", null)
@@ -348,67 +89,163 @@ export class OrgCatalogService {
         if (itemId !== undefined)
             q = q.where("id", "=", itemId);
         if (!isAdmin)
-            q = q.where("policy", "<>", "disabled");
-        const items = await q.execute();
+            q = q.where("disabled", "=", false);
+        const all = await q.execute();
+        const [listed, switches] = await Promise.all([
+            this.db
+                .selectFrom("catalog_item_scope_orgs")
+                .select("item_id")
+                .where("org_id", "=", orgId)
+                .execute(),
+            this.db
+                .selectFrom("catalog_item_org_switches")
+                .select(["item_id", "enabled"])
+                .where("org_id", "=", orgId)
+                .execute(),
+        ]);
+        const inList = new Set(listed.map((r) => r.item_id));
+        // Hidden `named` items (not listed, not shown to other orgs) are absent; shown ones are
+        // `not_offered`
+        // An org upload waiting for the super admin is its owner's only (ruling P3-9)
+        const items = all.filter((i) => (!i.awaiting_confirmation || i.owner_org_id === orgId) &&
+            (visibleTo({ scope: i.builtin ? "all" : i.scope }, inList.has(i.id)) ||
+                requestable(i, inList.has(i.id))));
         if (items.length === 0)
             return [];
+        const sw = new Map(switches.map((r) => [r.item_id, r.enabled]));
         const ids = items.map((i) => i.id);
-        const [versions, grants, requests, pluginInstalls] = await Promise.all([
-            this.d.db
+        const [versions, pluginInstalls, configs, requests] = await Promise.all([
+            this.db
                 .selectFrom("catalog_item_versions")
-                .select(["item_id", "version", "source", "manifest", "object_prefix", "files"])
+                .select([
+                "item_id",
+                "version",
+                "source",
+                "source_format",
+                "manifest",
+                "object_prefix",
+                "files",
+                "applied_at",
+                "rejected_at",
+            ])
                 .where("item_id", "in", ids)
                 .execute(),
-            this.d.db
-                .selectFrom("catalog_org_grants")
-                .select("item_id")
-                .where("org_id", "=", orgId)
-                .execute(),
-            this.d.requests.latestByItem(orgId),
-            this.d.db
+            this.db
                 .selectFrom("plugin_installs")
                 .select(["id", "item_id", "version"])
                 .where("org_id", "=", orgId)
                 .where("status", "in", ["installing", "installed", "upgrading"])
                 .execute(),
+            this.db
+                .selectFrom("extension_org_configs")
+                .select("plugin")
+                .where("org_id", "=", orgId)
+                .where("config", "is not", null)
+                .execute(),
+            this.db
+                .selectFrom("catalog_requests")
+                .select(["id", "item_id", "kind", "created_at"])
+                .where("org_id", "=", orgId)
+                .where("item_id", "in", ids)
+                .where("kind", "in", ["access", "enable"])
+                .where("status", "=", "pending")
+                .orderBy("created_at")
+                .execute(),
         ]);
-        const upgrades = await upgradeInfo(this.d.db, this.d.host, pluginInstalls.flatMap((a) => {
-            const item = items.find((i) => i.id === a.item_id);
-            return item ? [{ itemId: a.item_id, name: item.name, version: a.version }] : [];
-        }));
-        const granted = new Set(grants.map((g) => g.item_id));
+        const pending = new Map(requests.map((r) => [
+            r.item_id,
+            { id: r.id, kind: r.kind, createdAt: r.created_at.toISOString() },
+        ]));
         const undeployed = await this.undeployed(items.flatMap((i) => {
             const v = versions.find((x) => x.item_id === i.id && x.version === i.latest_version);
             return v ? [v] : [];
         }));
+        const configured = new Set(configs.map((c) => c.plugin));
+        const owners = await ownersOf(this.db, items.flatMap((i) => (i.owner_org_id === null ? [] : [i.owner_org_id])));
+        const loaded = new Map(this.registry.manifests().map((x) => [x.name, x]));
+        // the extensions of the latest versions that are not loaded: why (the `unavailable` reason)
+        const extensionOf = (i) => {
+            const v = versions.find((x) => x.item_id === i.id && x.version === i.latest_version);
+            const m = v?.manifest;
+            return m?.extension ? m.name : undefined;
+        };
+        const unloaded = await this.availability.unavailable(items.flatMap((i) => {
+            const n = extensionOf(i);
+            return n === undefined ? [] : [n];
+        }));
         const out = [];
         for (const i of items) {
-            const vs = versions.filter((v) => v.item_id === i.id);
-            const { installs: _installs, marketplaceId: _source, latestMarketplaceVersion: _latest, newerInMarketplace: _newer, ...view } = itemView(i, vs);
+            // Another org sees only an org-owned plugin's applied version, never one its owner
+            // uploaded that is pending or was rejected (ruling P3-34), nor such a version of a plugin
+            // transferred to the platform since (ruling P3-52)
+            const vs = versions.filter((v) => v.item_id === i.id &&
+                (i.owner_org_id === orgId ||
+                    (versionUsable(v) && (i.owner_org_id === null || v.version === i.latest_version))));
+            const { installs: _installs, marketplaceId: _source, latestMarketplaceVersion: _latest, newerInMarketplace: _newer, scopeOrgs: _scopeOrgs, enabledOrgs: _enabledOrgs, offCount: _offCount, pending: _pending, shownToOthers: _shown, awaitingConfirmation, pendingVersion, ...view } = itemView(i, vs, 0, undefined, ownerOnlyFacts(ownerOf(i.owner_org_id, owners)));
             const latest = vs.find((v) => v.version === i.latest_version);
-            let installable;
-            if (i.policy === "disabled")
-                installable = "disabled";
-            else if (latest && undeployed.has(i.id)) {
-                installable = "not_deployed";
+            const a = pluginInstalls.find((x) => x.item_id === i.id);
+            const scope = i.builtin ? "all" : i.scope;
+            const wanted = wantedOn(i, inList.has(i.id), sw.get(i.id) ?? null);
+            let state;
+            let reason;
+            const extName = extensionOf(i);
+            const why = extName === undefined ? undefined : unloaded.get(extName);
+            if (i.awaiting_confirmation)
+                state = "awaiting_confirmation";
+            else if (i.disabled) {
+                state = "unavailable";
+                reason = "plugin_disabled";
             }
-            else if (i.policy === "needs_approval") {
-                installable = granted.has(i.id) ? "granted" : "needs_approval";
+            else if (requestable(i, inList.has(i.id)))
+                state = "not_offered";
+            // not installed here and its extension cannot run: switching it on would fail (spec §14.2
+            // problem 1); an installed one keeps its state (an org admin can still switch it off)
+            else if (!a && why !== undefined) {
+                state = "unavailable";
+                reason = why.reason;
+            }
+            else if (a) {
+                // An on connector template without a connector here (ruling P2-10)
+                const missing = await this.pluginInstaller.missingConnectors(orgId, i.id);
+                state = (missing?.templates.length ?? 0) > 0 ? "needs_config" : "on";
+            }
+            else if (i.builtin)
+                state = "on";
+            else if (!wanted)
+                state = "off";
+            else {
+                const m = latest?.manifest;
+                const ext = m?.extension ? loaded.get(m.name) : undefined;
+                // only the connector templates on in the org need input (ruling P2-6)
+                const templateIds = (m?.connectorTemplates ?? []).map((t) => templateIdOfPath(t.path));
+                const needsInputs = (await connectorTemplatesOn(this.db, orgId, i.id, templateIds)).size > 0 ||
+                    (m?.extension !== undefined &&
+                        ext?.config?.org !== undefined &&
+                        !ext.config.org.safeParse({}).success &&
+                        !configured.has(m.name));
+                // Wanted but not installed and needing nothing: the sync has not installed it (yet, or its
+                // install failed); `off`, so an org admin can switch it on (the worker start retries it)
+                state = needsInputs ? "needs_config" : "off";
             }
-            else
-                installable = "yes";
-            const a = pluginInstalls.find((x) => x.item_id === i.id);
             out.push({
                 ...view,
-                installable,
+                // A pending upload is the owner's business only (other orgs never learn of it)
+                ...(i.owner_org_id === orgId && { awaitingConfirmation, pendingVersion }),
+                scope,
+                builtin: i.builtin,
+                state,
+                ...(reason !== undefined && { reason }),
+                switchable: state !== "not_offered" && state !== "awaiting_confirmation" && switchable(i),
+                notDeployed: latest !== undefined && undeployed.has(i.id),
                 installed: a
                     ? {
                         pluginInstallId: a.id,
                         version: a.version,
-                        upgradeAvailable: upgrades.get(`${a.item_id}@${a.version}`)?.upgradeAvailable ?? null,
+                        // no per-org upgrade: the platform update moves every org (ruling F2)
+                        upgradeAvailable: null,
                     }
                     : null,
-                request: requests.get(i.id) ?? null,
+                request: pending.get(i.id) ?? null,
             });
         }
         return out;
@@ -425,7 +262,7 @@ export class OrgCatalogService {
         const [item] = await this.list(orgId, accountId, itemId);
         if (!item)
             throw itemNotFound();
-        const v = await this.d.db
+        const v = await this.db
             .selectFrom("catalog_item_versions")
             .select(["manifest", "object_prefix", "files"])
             .where("item_id", "=", itemId)
@@ -434,26 +271,64 @@ export class OrgCatalogService {
         if (!v)
             throw itemNotFound();
         const m = v.manifest;
+        const templates = await readCatalogTemplates(this.storage, v);
+        // Providers the install would switch on first (a refusal is the install's to report)
+        const implied = await this.pluginInstaller
+            .impliedProviders(orgId, m, templates, m.dependencies ?? [])
+            .catch((e) => {
+            if (e instanceof ApiError)
+                return [];
+            throw e;
+        });
         return {
             item,
             hasIcon: m.icon !== undefined,
             extension: m.extension ? m.name : null,
-            templates: (await readCatalogTemplates(this.d.storage, v)).map((t) => orgTemplateView(t.id, t.file)),
-            dependencies: (m.dependencies ?? []).map((d) => ({ name: d.name, range: d.version })),
+            templates: templates.map((t) => orgTemplateView(t.id, t.file)),
+            dependencies: [
+                ...(m.dependencies ?? []).map((d) => ({ name: d.name, range: d.version })),
+                ...implied.map((d) => ({ name: d.name, range: d.range, implied: true })),
+            ],
             skills: (m.skills ?? []).map((s) => packagePath(s.path)),
             agents: (m.agents ?? []).map((a) => packagePath(a.path)),
+            missingTemplates: item.installed !== null && item.state === "needs_config"
+                ? ((await this.pluginInstaller.missingConnectors(orgId, itemId))?.templates ?? []).map((t) => orgTemplateView(t.id, t.file))
+                : [],
         };
     }
     /**
-     * The item's icon; members don't see disabled items (-> `catalog.item_not_found`, decided before
-     * reading storage).
+     * The item's icon; members don't see disabled items, nobody outside its list sees a hidden
+     * `named` item (-> `catalog.item_not_found`, decided before reading storage). Without `orgId`
+     * (the super admin) every item.
      */
-    icon(itemId, isAdmin) {
-        return readCatalogIcon(this.d.db, this.d.storage, itemId, isAdmin);
+    async icon(itemId, isAdmin, orgId) {
+        if (orgId === undefined)
+            return readCatalogIcon(this.db, itemId, isAdmin);
+        if (!UUID_RE.test(itemId))
+            throw itemNotFound();
+        // A hidden `named` item stays absent here too
+        const item = await this.db
+            .selectFrom("catalog_items")
+            .select(["scope", "builtin", "shown_to_others", "owner_org_id", "shareable"])
+            .where("id", "=", itemId)
+            .where("deleted_at", "is", null)
+            .executeTakeFirst();
+        // Not requestable from outside its list (hidden, or held back by the share gate): only listed orgs
+        if (item && !item.builtin && item.scope === "named" && !requestable(item, false)) {
+            const listed = await this.db
+                .selectFrom("catalog_item_scope_orgs")
+                .select("item_id")
+                .where("item_id", "=", itemId)
+                .where("org_id", "=", orgId)
+                .executeTakeFirst();
+            if (listed === undefined)
+                throw itemNotFound();
+        }
+        return readCatalogIcon(this.db, itemId, isAdmin);
     }
     /** For the admin item detail: whether the latest version has an icon. */
     hasIcon(itemId) {
-        return catalogHasIcon(this.d.db, itemId);
+        return catalogHasIcon(this.db, itemId);
     }
     /**
      * The items (latest versions) this replica cannot install now: the plugin's extension is not
@@ -462,9 +337,9 @@ export class OrgCatalogService {
      * deployed here (the install reads it again).
      */
     async undeployed(versions) {
-        const loaded = new Map(this.d.host.manifests().map((m) => [m.name, m.version]));
+        const loaded = new Map(this.registry.manifests().map((m) => [m.name, m.version]));
         const deps = {
-            findConnector: this.d.findConnector,
+            findConnector: (plugin, kind) => findConnectorIn(this.registry, plugin, kind),
             pluginVersion: (n) => loaded.get(n),
         };
         const out = new Set();
@@ -477,14 +352,14 @@ export class OrgCatalogService {
             if ((m.connectorTemplates ?? []).length === 0)
                 return;
             try {
-                const templates = await readCatalogTemplates(this.d.storage, v);
+                const templates = await readCatalogTemplates(this.storage, v);
                 if (templates.some((t) => templatePluginProblem(deps, t.file.template) !== undefined)) {
                     out.add(v.item_id);
                 }
             }
             catch (e) {
                 // Unreadable here: counted as deployed, the install reports it
-                this.d.log?.warn("catalog template read failed in the org list", {
+                this.log.warn("catalog template read failed in the org list", {
                     itemId: v.item_id,
                     error: e instanceof Error ? e.message : String(e),
                 });
@@ -492,28 +367,19 @@ export class OrgCatalogService {
         }));
         return out;
     }
-    /** Installs a plugin in the org (see the class comment). */
-    async install(orgId, actor, itemId, body, actorTokenId) {
+    /**
+     * Installs a plugin in the org (the old install route, an alias of switching it on): the role
+     * first, then item errors (a member cannot probe a disabled item through error codes), then the
+     * installer. Records the org's switch as on.
+     */
+    async install(orgId, actor, itemId, body, actorTokenId, auditDetail) {
         if (!UUID_RE.test(itemId))
             throw itemNotFound();
-        // The role first (forbidden when it can install nothing), then item errors: a member cannot
-        // probe the existence or versions of a disabled item through error codes
-        await this.d.db.transaction().execute(async (t) => {
-            const { role } = await lockOrgAndAuthorize(t, orgId, actor, "catalog.read");
-            const canAny = ["org.extensions.manage", "connectors.manage", "skills.manage"].some((a) => can(role, a));
-            if (!canAny)
-                throw new ApiError("forbidden", "Insufficient organization role");
-        });
-        const item = await this.d.db
-            .selectFrom("catalog_items")
-            .selectAll()
-            .where("id", "=", itemId)
-            .where("deleted_at", "is", null)
-            .executeTakeFirst();
-        if (!item)
-            throw itemNotFound();
-        const version = body.version ?? item.latest_version;
-        const v = await this.d.db
+        await this.assertCanInstall(orgId, actor);
+        const item = await this.visibleItem(orgId, itemId);
+        // The platform's version (one per deployment, ruling P2-17)
+        const version = item.platform_synced_version ?? item.latest_version;
+        const v = await this.db
             .selectFrom("catalog_item_versions")
             .select("version")
             .where("item_id", "=", itemId)
@@ -521,105 +387,198 @@ export class OrgCatalogService {
             .executeTakeFirst();
         if (!v)
             throw new ApiError("catalog.item_not_found", `Version ${version} of this item not found`);
-        const opts = actorTokenId !== undefined ? { actorTokenId } : {};
-        if (item.policy === "disabled")
-            throw itemDisabled();
-        // Dependencies resolved, extensions deployed, template connectors available: before a request
-        // is created. The actions are the union over the plugins the install brings in
-        const { actions } = await this.d.pluginInstaller.preflight(orgId, actor, itemId, version);
-        // 1. Role and policy under the lock; needs_approval without a grant -> a request (202). Approval
-        //    follows this plugin's policy only, not its dependencies' (spec §10)
-        const pending = await this.d.db.transaction().execute(async (t) => {
-            await lockOrgForActions(t, orgId, actor, actions);
-            const locked = await t
-                .selectFrom("catalog_items")
-                .select(["policy", "deleted_at"])
-                .where("id", "=", itemId)
-                .forShare()
-                .executeTakeFirst();
-            if (!locked || locked.deleted_at !== null)
-                throw itemNotFound();
-            if (locked.policy === "disabled")
-                throw itemDisabled();
-            if (locked.policy === "needs_approval") {
-                const grant = await t
-                    .selectFrom("catalog_org_grants")
-                    .select("item_id")
-                    .where("item_id", "=", itemId)
-                    .where("org_id", "=", orgId)
-                    .executeTakeFirst();
-                if (!grant) {
-                    return this.d.requests.requestDeployment(t, orgId, actor, item, version, opts);
-                }
-            }
-            return undefined;
-        });
-        if (pending !== undefined) {
-            return { status: 202, request: await this.d.requests.view(this.d.db, pending) };
-        }
-        // 2. Install (each step re-checks the item policy in its own transaction)
-        const { version: _version, ...input } = body;
-        const view = await this.d.pluginInstaller.install(orgId, actor, itemId, version, input, opts);
+        const opts = {
+            switchOn: true,
+            ...(actorTokenId !== undefined && { actorTokenId }),
+            ...(auditDetail !== undefined && { auditDetail }),
+        };
+        if (item.disabled)
+            throw pluginDisabled();
+        // Dependencies resolved, extensions deployed, template connectors available
+        await this.pluginInstaller.preflight(orgId, actor, itemId, version);
+        const view = await this.pluginInstaller.install(orgId, actor, itemId, version, body, opts);
         return {
             status: 201,
             installed: { itemId, version, pluginInstallId: view.id },
             install: view,
         };
     }
-    /** The upgrade preview of an org install (spec §10, see `PluginUpgrader`). */
-    async upgradePreview(orgId, actor, installId, version) {
-        await this.assertCanInstall(orgId, actor);
-        return this.d.pluginUpgrader.preview(orgId, actor, installId, version);
+    /** The item when the org may see it (scope), else `catalog.item_not_found`. */
+    async visibleItem(orgId, itemId) {
+        const item = await this.db
+            .selectFrom("catalog_items")
+            .selectAll()
+            .where("id", "=", itemId)
+            .where("deleted_at", "is", null)
+            .executeTakeFirst();
+        if (!item)
+            throw itemNotFound();
+        // An org upload waiting for the super admin: absent for other orgs, not switchable by its
+        // owner (ruling P3-9)
+        if (item.awaiting_confirmation) {
+            if (item.owner_org_id !== orgId)
+                throw itemNotFound();
+            throw itemPendingError(item.name);
+        }
+        const listed = await this.db
+            .selectFrom("catalog_item_scope_orgs")
+            .select("item_id")
+            .where("item_id", "=", itemId)
+            .where("org_id", "=", orgId)
+            .executeTakeFirst();
+        if (!visibleTo({ scope: item.builtin ? "all" : item.scope }, listed !== undefined)) {
+            // Shown to other orgs: the org sees it and may request access, but cannot switch it on
+            if (requestable(item, false))
+                throw notOffered();
+            throw itemNotFound();
+        }
+        return item;
+    }
+    /** The org's live plugin install of the item, if any. */
+    liveInstall(orgId, itemId) {
+        return this.db
+            .selectFrom("plugin_installs")
+            .select("id")
+            .where("org_id", "=", orgId)
+            .where("item_id", "=", itemId)
+            .where("status", "in", ["installing", "installed", "upgrading"])
+            .executeTakeFirst();
     }
     /**
-     * Upgrades an org install in place (spec §10, Decision 11): the preview's `diffHash` is checked
-     * first (`plugin.upgrade_stale`); the item disabled -> `catalog.item_disabled`; needs_approval
-     * without a grant -> a stage deployment request for the target version (202; after approval the
-     * org admin runs the upgrade again); otherwise the upgrade runs (200, the install view).
+     * The org admin's switch of a plugin (`PUT catalog/:itemId/switch`). On: installs it (or just
+     * records the switch when it is installed already). Off: refused for builtin items
+     * (`plugin.scope_locked`; an `all` one may go off, layering spec §4); without `confirm` returns
+     * the uninstall preview and its hash, with the hash of the current preview uninstalls (a changed
+     * preview -> `plugin.switch_stale`). The switch row is written after the install / uninstall.
      */
-    async upgrade(orgId, actor, installId, body, actorTokenId) {
+    async setSwitch(orgId, actor, itemId, body, actorTokenId, auditDetail) {
+        if (!UUID_RE.test(itemId))
+            throw itemNotFound();
         await this.assertCanInstall(orgId, actor);
-        const opts = actorTokenId !== undefined ? { actorTokenId } : {};
-        const { itemId, actions, diff } = await this.d.pluginUpgrader.check(orgId, actor, installId, body);
-        const pending = await this.d.db.transaction().execute(async (t) => {
-            await lockOrgForActions(t, orgId, actor, actions);
-            const locked = await t
-                .selectFrom("catalog_items")
-                .select(["id", "name", "policy", "deleted_at"])
-                .where("id", "=", itemId)
-                .forShare()
-                .executeTakeFirst();
-            if (!locked || locked.deleted_at !== null)
+        const item = await this.visibleItem(orgId, itemId);
+        const opts = {
+            ...(actorTokenId !== undefined && { actorTokenId }),
+            ...(auditDetail !== undefined && { auditDetail }),
+        };
+        if (body.enabled) {
+            if (item.disabled)
+                throw pluginDisabled();
+            if ((await this.liveInstall(orgId, itemId)) !== undefined) {
+                await this.recordSwitch(orgId, actor, itemId, true);
+            }
+            else {
+                await this.install(orgId, actor, itemId, body.inputs ?? {}, actorTokenId, auditDetail);
+            }
+            return { kind: "done", item: await this.itemOf(orgId, actor, itemId) };
+        }
+        if (!switchable(item)) {
+            throw new ApiError("plugin.scope_locked", "This plugin is built in: it is on for every organization and cannot be switched off here");
+        }
+        const live = await this.liveInstall(orgId, itemId);
+        if (live === undefined) {
+            await this.recordSwitch(orgId, actor, itemId, false);
+            return { kind: "done", item: await this.itemOf(orgId, actor, itemId) };
+        }
+        const preview = await this.pluginInstaller.previewUninstall(orgId, live.id);
+        const confirm = uninstallPreviewHash(preview);
+        if (body.confirm === undefined)
+            return { kind: "preview", preview, confirm };
+        // The hash is re-checked and the switch row written inside the uninstall's transaction
+        await this.pluginInstaller.uninstall(orgId, actor, live.id, opts, { expectHash: body.confirm });
+        return { kind: "done", item: await this.itemOf(orgId, actor, itemId) };
+    }
+    /**
+     * `DELETE plugin-installs/:installId` of a catalog plugin follows the switch-off semantics: builtin
+     * items are refused (`plugin.scope_locked`) unless the install is not live (failed, or
+     * `installing`: the installer cleans up a stale one and refuses a fresh one). Removing a live
+     * install writes the switch row false in the uninstall's transaction (an `all` item then stays
+     * off in the org); removing a failed or stale one writes none.
+     */
+    async uninstall(orgId, actor, installId, actorTokenId, 
+    /** Merged into the audit detail (a write made through the Platform tool). */
+    auditDetail) {
+        if (!UUID_RE.test(installId))
+            throw new ApiError("plugin.install_not_found", "Plugin install not found");
+        const row = await this.db
+            .selectFrom("plugin_installs as a")
+            .innerJoin("catalog_items as i", "i.id", "a.item_id")
+            .select(["i.scope", "i.builtin", "a.status"])
+            .where("a.id", "=", installId)
+            .where("a.org_id", "=", orgId)
+            .executeTakeFirst();
+        // A failed or stuck install is cleaned up whatever the scope (it is not on anyway)
+        const live = row?.status === "installed" || row?.status === "upgrading";
+        if (row !== undefined && live && !switchable(row)) {
+            throw new ApiError("plugin.scope_locked", "This plugin is built in: it is on for every organization and cannot be uninstalled here");
+        }
+        return this.pluginInstaller.uninstall(orgId, actor, installId, {
+            ...(actorTokenId !== undefined && { actorTokenId }),
+            ...(auditDetail !== undefined && { auditDetail }),
+        }, 
+        // only a live install was on: removing a failed or stale one writes no switch row, so an
+        // item its scope wants stays wanted and the sync installs it again
+        row !== undefined && live ? {} : undefined);
+    }
+    async itemOf(orgId, accountId, itemId) {
+        const [item] = await this.list(orgId, accountId, itemId);
+        if (!item)
+            throw itemNotFound();
+        return item;
+    }
+    /**
+     * Writes the org's switch row of the item under the org row lock. The item row is locked FOR
+     * SHARE first (exclusive with a scope change, an unshare, ruling P3-25, and an owner's delete or
+     * transfer); switching on re-checks that the org may still see it; the install path re-checks the same in `assertItemInstallable`.
+     */
+    async recordSwitch(orgId, actor, itemId, enabled) {
+        await this.orgLock.lock(orgId);
+        // Both directions lock the item row FOR SHARE: an owner's delete or transfer (FOR UPDATE)
+        // decides on who uses it, so a switch-off racing it must not change that answer meanwhile
+        const item = await this.db
+            .selectFrom("catalog_items")
+            .select(["scope", "builtin"])
+            .where("id", "=", itemId)
+            .where("deleted_at", "is", null)
+            .forShare()
+            .executeTakeFirst();
+        if (enabled) {
+            if (!item)
                 throw itemNotFound();
-            if (locked.policy === "disabled")
-                throw itemDisabled();
-            if (locked.policy !== "needs_approval")
-                return undefined;
-            const grant = await t
-                .selectFrom("catalog_org_grants")
+            const listed = await this.db
+                .selectFrom("catalog_item_scope_orgs")
                 .select("item_id")
                 .where("item_id", "=", itemId)
                 .where("org_id", "=", orgId)
                 .executeTakeFirst();
-            if (grant)
-                return undefined;
-            return this.d.requests.requestDeployment(t, orgId, actor, locked, body.version, opts);
-        });
-        if (pending !== undefined) {
-            return { status: 202, request: await this.d.requests.view(this.d.db, pending) };
+            if (!visibleTo({ scope: item.builtin ? "all" : item.scope }, listed !== undefined)) {
+                throw itemNotFound();
+            }
         }
-        return {
-            status: 200,
-            install: await this.d.pluginUpgrader.upgrade(orgId, actor, installId, body, opts, diff),
-        };
+        await upsertOrgSwitch(this.db, orgId, itemId, enabled, actor);
     }
     /** The actor can install something in the org (forbidden otherwise), checked before item errors. */
     async assertCanInstall(orgId, actor) {
-        await this.d.db.transaction().execute(async (t) => {
-            const { role } = await lockOrgAndAuthorize(t, orgId, actor, "catalog.read");
-            const canAny = ["org.extensions.manage", "connectors.manage", "skills.manage"].some((a) => can(role, a));
-            if (!canAny)
-                throw new ApiError("forbidden", "Insufficient organization role");
-        });
+        const { role } = await this.orgLock.lockAndAuthorize(orgId, actor, "catalog.read");
+        const canAny = ["org.extensions.manage", "connectors.manage", "skills.manage"].some((a) => can(role, a));
+        if (!canAny)
+            throw new ApiError("forbidden", "Insufficient organization role");
     }
-}
+};
+__decorate([
+    Transactional()
+], OrgCatalogService.prototype, "recordSwitch", null);
+__decorate([
+    Transactional()
+], OrgCatalogService.prototype, "assertCanInstall", null);
+OrgCatalogService = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(OrgLock)),
+    __param(2, Inject(StorageService)),
+    __param(3, Inject(ExtensionRegistry)),
+    __param(4, Inject(PluginInstaller)),
+    __param(5, Inject(KERNEL_LOGGER)),
+    __param(6, Inject(TransactionHost)),
+    __param(7, Inject(ExtensionAvailability))
+], OrgCatalogService);
+export { OrgCatalogService };