@capybara-hq/kernel 0.1.0-rc.1 → 0.1.0-rc.11

package/dist/catalog/plugin-install.js

@@ -1,18 +1,77 @@
-import { randomUUID } from "node:crypto";
-import { EXTENSION_POINTS, parseExtensionPoint, parseSkillMd, SKILL_ENTRY_FILE, } 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 { createHash, randomUUID } from "node:crypto";
+import { EXTENSION_POINTS, marketplaceEntryDeprecation, parseExtensionPoint, parseSkillMd, SKILL_ENTRY_FILE, } from "@capybara-hq/plugin-sdk";
+import { Inject, Injectable } from "@nestjs/common";
 import { sql } from "kysely";
-import { normalizeToolRef } from "../agents/definition.js";
-import { putTemplateVersionIn, revertTemplateVersionIn, softDeleteTemplateIn, } from "../agents/templates.js";
+import semver from "semver";
+import { revertTemplateVersionIn, softDeleteTemplateIn } from "../agents/templates.js";
 import { ApiError } from "../errors.js";
 import { isExtensionEnabled } from "../extensions/enabled.js";
+import { OrgExtensionConfigs, } from "../extensions/org-config.js";
+import { ExtensionRegistry } from "../extensions/registry.js";
 import { audit } from "../identity/audit.js";
-import { lockOrg } from "../orgs/org-lock.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { afterCommit } from "../infra/database/after-commit.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 { packagePath } from "../packages/tgz.js";
-import { skillConflictError, skillConflicts, } from "../skills/skills.service.js";
-import { lockOrgForActions, readCatalogAgentTemplates, readCatalogFiles, readCatalogTemplates, requiredActions, skillOf, templateConnectorInput, templatePluginProblem, } from "./org-catalog.service.js";
-import { assertItemInstallable, disabledPluginItems, pluginItemDisabled, } from "./requests.service.js";
-import { upgradeInfo } from "./upgrade-targets.js";
+import { SkillsService, skillConflictError, skillConflicts, } from "../skills/skills.service.js";
+import { StorageService } from "../storage/storage.service.js";
+import { assertNotPlatformDefault, themesPreview, } from "../themes/theme-usage.js";
+import { ConnectorsService } from "../tools/connectors.service.js";
+import { findConnectorIn, lockOrgForActions, readCatalogAgentTemplates, readCatalogFiles, readCatalogTemplates, requiredActions, templateConnectorInput, templatePluginProblem, } from "./catalog-content.js";
+import { versionUsable } from "./catalog-items.js";
+import { agentDefinitionRefs, componentOn, connectorTemplateState, connectorTemplatesOn, listedIn, loadComponents, loadScopeState, pluginFactsOf, referenceIds, switchOf, themeIdClashes, } from "./component-state.js";
+import { assertItemInstallable, disabledPluginItems, pluginItemDisabled, resolveRequestsByInstall, } from "./request-rules.js";
+import { visibleTo } from "./scope.js";
+import { ScopeNoLongerWanted, ScopeStillWanted, wantedByScope } from "./scope-state.js";
 import { maxSatisfying, satisfiesRange } from "./versions.js";
+/** The confirm hash of an uninstall preview: sha256 over its sorted JSON (the scheme of `diffHash`). */
+export function uninstallPreviewHash(p) {
+    const by = (xs) => [...xs].sort((a, b) => `${a.kind}:${a.ref}`.localeCompare(`${b.kind}:${b.ref}`));
+    return createHash("sha256")
+        .update(JSON.stringify({
+        ...p,
+        components: by(p.components),
+        kept: by(p.kept),
+        agents: [...p.agents]
+            .sort((a, b) => a.id.localeCompare(b.id))
+            .map((a) => ({ ...a, uses: by(a.uses) })),
+    }))
+        .digest("hex");
+}
+/** Upserts the org's switch row of an item in the caller's transaction (the org lock is held). */
+export async function upsertOrgSwitch(db, orgId, itemId, enabled, actor) {
+    await db
+        .insertInto("catalog_item_org_switches")
+        .values({ item_id: itemId, org_id: orgId, enabled, updated_by: actor })
+        .onConflict((oc) => oc.columns(["item_id", "org_id"]).doUpdateSet({
+        enabled,
+        updated_by: actor,
+        updated_at: sql `now()`,
+    }))
+        .execute();
+}
+/** The kernel (actor null, the scope sync) never installs what needs the org's input. */
+export class NeedsOrgInput extends ApiError {
+    plugin;
+    constructor(plugin) {
+        super("internal", `Plugin ${plugin} needs the organization's input (connector templates); only a person can install it`);
+        this.plugin = plugin;
+    }
+}
+const systemNeedsInput = (name) => new NeedsOrgInput(name);
 /** How deep plugin dependencies may nest (the root plugin's dependencies are level 1). */
 export const DEPENDENCY_DEPTH_LIMIT = 10;
 /** A failed install step, carried up through the dependency installs to the root install. */
@@ -45,33 +104,66 @@ const installNotFound = () => new ApiError("plugin.install_not_found", "Plugin i
 const fail = (path, message) => new ApiError("validation_failed", "Request validation failed", [{ path, message }]);
 const isUniqueViolation = (e) => typeof e === "object" && e !== null && e.code === "23505";
 const unresolved = (name, range, why) => new ApiError("catalog.dependency_unresolved", `Dependency ${name}@${range} cannot be resolved: ${why}`, [{ dependency: name, range }]);
-const dependencyDisabled = (name) => new ApiError("catalog.dependency_disabled", `Dependency ${name} is disabled by the enterprise admin, so this plugin cannot be installed`, [{ dependency: name }]);
+const dependencyDisabled = (name) => new ApiError("catalog.dependency_disabled", `Dependency ${name} is disabled by the super admin, so this plugin cannot be installed`, [{ dependency: name }]);
 /**
- * The dependency `d` resolved against the catalog: the highest imported version (of the live item
- * with that name) satisfying its range. No such item or version -> `catalog.dependency_unresolved`;
- * the item disabled -> `catalog.dependency_disabled` (the enterprise admin's ban is not bypassed,
- * spec §10).
+ * The dependency `d` resolved against the catalog (ruling P2-17, one version per deployment): the
+ * dependency's platform version (`platform_synced_version`), which must satisfy its range; only
+ * while it has none yet (its first sync failed), the highest imported version satisfying the range
+ * that its marketplace does not deprecate, a stable one before a prerelease (the marketplace
+ * folding rule). No such item or version -> `catalog.dependency_unresolved`; the item disabled ->
+ * `catalog.dependency_disabled` (the super admin's ban is not bypassed, spec §10).
  */
 async function resolveOne(db, d) {
     const item = await db
         .selectFrom("catalog_items")
-        .select(["id", "policy"])
+        .select([
+        "id",
+        "disabled",
+        "platform_synced_version",
+        "marketplace_id",
+        "awaiting_confirmation",
+        "owner_org_id",
+        "latest_version",
+    ])
         .where("name", "=", d.name)
         .where("deleted_at", "is", null)
         .executeTakeFirst();
     if (!item) {
-        throw unresolved(d.name, d.version, "it is not in the enterprise catalog; ask the enterprise admin to import it");
+        throw unresolved(d.name, d.version, "it is not in the platform catalog; ask the super admin to import it");
     }
-    if (item.policy === "disabled")
+    if (item.disabled)
         throw dependencyDisabled(d.name);
+    // An org upload waiting for the super admin is no dependency target (ruling P3-9)
+    if (item.awaiting_confirmation) {
+        throw unresolved(d.name, d.version, "it waits for a super admin to confirm its extension");
+    }
     const versions = await db
         .selectFrom("catalog_item_versions")
-        .select(["version", "manifest", "imported_at"])
+        .select(["version", "manifest", "imported_at", "applied_at", "rejected_at"])
         .where("item_id", "=", item.id)
         .execute();
-    const v = maxSatisfying(versions.map((x) => ({ ...x, importedAt: x.imported_at })), d.version);
+    let v;
+    if (item.platform_synced_version !== null) {
+        v = versions.find((x) => x.version === item.platform_synced_version);
+        if (!v || !satisfiesRange(v.version, d.version)) {
+            throw unresolved(d.name, d.version, `its platform version ${item.platform_synced_version} does not satisfy the range; ask ` +
+                "the super admin to update it");
+        }
+    }
+    else {
+        const deprecated = await deprecatedVersions(db, d.name, item.marketplace_id);
+        // An org's plugin offers only its applied version: never one pending or rejected (P3-34),
+        // also once transferred to the platform (P3-52)
+        const candidates = versions
+            .filter((x) => versionUsable(x))
+            .filter((x) => item.owner_org_id === null || x.version === item.latest_version)
+            .filter((x) => !deprecated.has(x.version))
+            .map((x) => ({ ...x, importedAt: x.imported_at }));
+        v =
+            maxSatisfying(candidates.filter((x) => semver.prerelease(x.version) === null), d.version) ?? maxSatisfying(candidates, d.version);
+    }
     if (!v) {
-        throw unresolved(d.name, d.version, "no imported version satisfies the range; ask the enterprise admin to import one");
+        throw unresolved(d.name, d.version, "no imported version satisfies the range; ask the super admin to import one");
     }
     return {
         name: d.name,
@@ -81,10 +173,24 @@ async function resolveOne(db, d) {
         manifest: v.manifest,
     };
 }
+/** The versions of plugin `name` its marketplace (`marketplaceId`) marks deprecated. */
+async function deprecatedVersions(db, name, marketplaceId) {
+    if (marketplaceId === null)
+        return new Set();
+    const rows = await db
+        .selectFrom("marketplace_entries")
+        .select(["version", "entry"])
+        .where("source_id", "=", marketplaceId)
+        .where("name", "=", name)
+        .execute();
+    return new Set(rows
+        .filter((r) => marketplaceEntryDeprecation(r.entry) !== null)
+        .map((r) => r.version));
+}
 /**
- * Resolves a plugin's dependencies against the catalog: for each one the highest imported version
- * of the live item with that name satisfying its range. The whole dependency tree is checked: a
- * dependency nothing satisfies -> `catalog.dependency_unresolved`; a disabled one ->
+ * Resolves a plugin's dependencies against the catalog: for each one the platform version of the
+ * live item with that name, which must satisfy its range (see `resolveOne`). The whole dependency
+ * tree is checked: a dependency nothing satisfies -> `catalog.dependency_unresolved`; a disabled one ->
  * `catalog.dependency_disabled`; a cycle (`a` -> `b` -> `a`, by name) or nesting deeper than
  * {@link DEPENDENCY_DEPTH_LIMIT} -> `catalog.dependency_cycle`. Returns the direct dependencies.
  */
@@ -169,9 +275,11 @@ export function under(e, at) {
  *    not run it; already enabled is recorded created=false);
  * 3. connectors from the templates (credentials / clients go to secrets, default policies are
  *    recorded `policy_source 'template'`);
- * 4. the skills (an org skill of the same name from the same catalog item gets a new version,
- *    recorded created=false with skill_version; one of other provenance, the org's own or another
- *    item's, refuses the install while planning with `plugin.skill_conflict`, spec §9.2).
+ * The plugin's skills and agent templates are platform components (plugin scope phase 2): stored
+ * once for the deployment and on in the org while the plugin is, so an install writes no org rows
+ * for them; a skill name the org already uses (its own skill, another plugin's) refuses the install
+ * while planning with `plugin.skill_conflict` (spec §9.2, rule 10). Uninstall leaves the org copies
+ * earlier installs wrote (linked to the platform components by the migration).
  * Approval follows the installed plugin's policy only (spec §10): dependency components are
  * re-checked against the root item's policy and their own item's disabled state. Each component is
  * recorded in `plugin_install_components` as soon as it exists; if any step fails, the components
@@ -179,18 +287,47 @@ export function under(e, at) {
  * install is marked failed (error holds only the step and the error code) and 502
  * `plugin.install_failed` is thrown. Uninstall removes only components with created=true that
  * nothing else uses, and reports what it kept and why. No in-process state; the org row lock
- * serializes writes within one org. In-place upgrades are run by `PluginUpgrader`
- * (plugin-upgrade.ts), which reuses the planning, install and ledger methods here (the ones without
- * `private` are internal to the catalog, not an API).
+ * serializes writes within one org. There is no per-org upgrade: a platform plugin is updated
+ * once for the deployment (`PlatformPluginUpdater`, plugin-upgrade.ts, ruling F2); an install left
+ * `upgrading` by an earlier per-org upgrade is undone from its journal by the next uninstall. The
+ * methods without `private` are internal to the catalog, not an API.
  */
-export class PluginInstaller {
-    d;
-    constructor(d) {
-        this.d = d;
+let PluginInstaller = class PluginInstaller {
+    kdb;
+    orgLock;
+    storage;
+    registry;
+    skills;
+    orgConfigs;
+    config;
+    connectors;
+    log;
+    txHost;
+    constructor(kdb, 
+    /** The org row lock (orgs/org-lock.ts): joins the caller's transaction. */
+    orgLock, storage, 
+    /** The loaded extensions and connectors of this replica (the extension registry). */
+    registry, skills, orgConfigs, config, 
+    /** Org connectors: installs create, upgrade and remove them. */
+    connectors, log, txHost) {
+        this.kdb = kdb;
+        this.orgLock = orgLock;
+        this.storage = storage;
+        this.registry = registry;
+        this.skills = skills;
+        this.orgConfigs = orgConfigs;
+        this.config = config;
+        this.connectors = connectors;
+        this.log = log;
+        this.txHost = txHost;
+    }
+    /** The kernel-schema handle of the current context (the transaction, else the pool). */
+    get db() {
+        return this.kdb.db;
     }
-    /** The installer's dependencies (shared with `PluginUpgrader`). */
-    get deps() {
-        return this.d;
+    /** `catalog.staleInstallMinutes`: an install `installing` for longer can be cleaned up by uninstalling it. */
+    staleInstallMinutes() {
+        return this.config.get().catalog.staleInstallMinutes;
     }
     /**
      * The checks an install runs before it creates anything, without the org's input (for the org
@@ -200,15 +337,20 @@ export class PluginInstaller {
     async preflight(orgId, actor, itemId, version) {
         const plan = await this.plan(orgId, actor, itemId, version, null, "", undefined);
         await this.assertNoSkillConflicts(orgId, plan);
+        await this.assertNoThemeClashes(orgId, itemId);
         return { actions: planActions(plan) };
     }
     async install(orgId, actor, itemId, version, input, opts = {}) {
+        const { switchOn, via, ...actorOpts } = opts;
         const plan = await this.plan(orgId, actor, itemId, version, input, "", undefined);
         await this.assertNoSkillConflicts(orgId, plan);
+        await this.assertNoThemeClashes(orgId, itemId);
         let installId;
         try {
-            installId = await this.execute(orgId, actor, plan, opts, {
+            installId = await this.execute(orgId, actor, plan, actorOpts, {
                 actions: planActions(plan),
+                ...(switchOn === true && { switchOn }),
+                ...(via !== undefined && { via }),
             });
         }
         catch (e) {
@@ -243,14 +385,50 @@ export class PluginInstaller {
      * and a name two plugins of the same plan both bring (the one installed first is the source).
      */
     async assertNoSkillConflicts(orgId, plan) {
-        const conflicts = await planSkillConflicts(this.d.db, orgId, plan);
+        const conflicts = await planSkillConflicts(this.db, orgId, plan);
         if (conflicts.length > 0)
             throw skillConflictError(conflicts);
     }
+    /**
+     * Refuses installing a plugin whose themes would come on in the org (they follow it) while
+     * another theme with the same id is on there (themes spec §6, rule 10): 409 `theme.id_taken`,
+     * details `[{ theme, orgId, themes, plugins }]`, before anything is written.
+     */
+    async assertNoThemeClashes(orgId, itemId) {
+        const themes = await loadComponents(this.db, "theme", { itemId });
+        if (themes.length === 0)
+            return;
+        const st = await loadScopeState(this.db, "theme", themes);
+        const conflicts = [];
+        for (const c of themes) {
+            const p = pluginFactsOf(st, c.itemId, orgId);
+            const listed = listedIn(st, c.id, orgId);
+            const sw = switchOf(st, c.id, orgId);
+            if (componentOn(c, p, listed, sw) ||
+                !componentOn(c, p && { ...p, installed: true }, listed, sw)) {
+                continue;
+            }
+            const clash = await themeIdClashes(this.db, orgId, c, c.name);
+            if (clash.length > 0) {
+                conflicts.push({
+                    theme: c.name,
+                    orgId,
+                    themes: clash.map((x) => x.id),
+                    plugins: clash.map((x) => x.plugin ?? "platform"),
+                });
+            }
+        }
+        if (conflicts.length > 0) {
+            throw new ApiError("theme.id_taken", `The plugin's themes would come on next to themes with the same id already on in this organization (${conflicts.map((c) => c.theme).join(", ")}); switch those themes off first`, conflicts);
+        }
+    }
     /** The connector checks of templates against what this replica loads right now. */
     templateDeps() {
-        const versions = new Map(this.d.host.manifests().map((m) => [m.name, m.version]));
-        return { findConnector: this.d.findConnector, pluginVersion: (n) => versions.get(n) };
+        const versions = new Map(this.registry.manifests().map((m) => [m.name, m.version]));
+        return {
+            findConnector: (plugin, kind) => findConnectorIn(this.registry, plugin, kind),
+            pluginVersion: (n) => versions.get(n),
+        };
     }
     /**
      * Plans the install of one plugin version and, depth first, of its dependencies not yet
@@ -261,7 +439,7 @@ export class PluginInstaller {
     async plan(orgId, actor, itemId, version, input, at, approvedBy) {
         if (!UUID_RE.test(itemId))
             throw new ApiError("catalog.item_not_found", "Plugin not found");
-        const v = await this.d.db
+        const v = await this.db
             .selectFrom("catalog_item_versions as v")
             .innerJoin("catalog_items as i", "i.id", "v.item_id")
             .select([
@@ -279,11 +457,19 @@ export class PluginInstaller {
         if (!v)
             throw new ApiError("catalog.item_not_found", "Plugin version not found");
         const manifest = v.manifest;
-        const deps = await resolveDependencies(this.d.db, manifest);
+        const declared = await resolveDependencies(this.db, manifest);
         const extension = await this.planExtension(orgId, manifest);
-        const templates = await readCatalogTemplates(this.d.storage, v);
-        const skillNames = await catalogSkillNames(this.d.storage, v, manifest);
-        const agentTemplates = await readCatalogAgentTemplates(this.d.storage, v);
+        const allTemplates = await readCatalogTemplates(this.storage, v);
+        // Only the connector templates on in the org make connectors (ruling P2-6): one switched off
+        // there, outside its own scope or disabled is skipped (input given for it is ignored)
+        const on = await connectorTemplatesOn(this.db, orgId, itemId, allTemplates.map((t) => t.id));
+        const templates = allTemplates.filter((t) => on.has(t.id));
+        const deps = [
+            ...declared,
+            ...(await this.impliedProviders(orgId, manifest, templates, declared)),
+        ];
+        const skillNames = await catalogSkillNames(this.storage, v, manifest);
+        const agentTemplates = await readCatalogAgentTemplates(this.storage, v);
         const connectors = new Map();
         if (input === null) {
             for (const ct of templates) {
@@ -293,14 +479,17 @@ export class PluginInstaller {
             }
         }
         else {
-            this.checkInput(manifest, templates, input, at);
+            this.checkInput(manifest, allTemplates, input, at);
             for (const ct of templates) {
+                // The kernel installs only what needs no org input (the scope sync's `needs_config` rule)
+                if (actor === null)
+                    throw systemNeedsInput(manifest.name);
                 connectors.set(ct.id, this.planConnector(actor, { itemId, version, name: manifest.name }, ct, input, at, approvedBy));
             }
         }
         const dependencies = [];
         for (const dep of deps) {
-            if (await this.liveDependency(this.d.db, orgId, dep)) {
+            if (await this.liveDependency(this.db, orgId, dep)) {
                 dependencies.push({ dep, plan: null });
                 continue;
             }
@@ -325,6 +514,64 @@ export class PluginInstaller {
             dependencies,
         };
     }
+    /**
+     * The providers of the templates' connector kinds as implied dependencies: a template whose
+     * `plugin` is neither this plugin, a declared dependency nor already enabled in the org makes that
+     * plugin a dependency (installed first, recorded like a declared one, so an uninstall hands it
+     * back). No such plugin offered by the catalog -> `connector.kind_unavailable` naming it, before
+     * anything is written.
+     */
+    async impliedProviders(orgId, manifest, templates, declared) {
+        const out = [];
+        const seen = new Set([manifest.name, ...declared.map((d) => d.name)]);
+        for (const ct of templates) {
+            const provider = ct.file.template.plugin;
+            if (seen.has(provider))
+                continue;
+            seen.add(provider);
+            // Not deployed: the not_deployed refusal of the plan's own checks says it
+            if (templatePluginProblem(this.templateDeps(), ct.file.template) !== undefined)
+                continue;
+            if (await isExtensionEnabled(this.db, orgId, provider))
+                continue;
+            const refuse = (why) => new ApiError("connector.kind_unavailable", `Connector template ${ct.id} needs the plugin ${provider}, which is not enabled in this organization: ${why}`);
+            let dep;
+            try {
+                const { manifest: _m, ...resolved } = await resolveOne(this.db, {
+                    name: provider,
+                    version: ct.file.template.pluginVersion ?? "*",
+                });
+                dep = resolved;
+            }
+            catch (e) {
+                if (!(e instanceof ApiError))
+                    throw e;
+                throw refuse(e.code === "catalog.dependency_unresolved"
+                    ? `${provider} is deployed but switched off here and the catalog has no entry to switch it on; ask the super admin to enable it`
+                    : `${provider} is not offered to this organization`);
+            }
+            // Scope: only a plugin offered to this org may be switched on for it (nothing more is said)
+            const item = await this.db
+                .selectFrom("catalog_items")
+                .select(["scope", "builtin"])
+                .where("id", "=", dep.itemId)
+                .executeTakeFirstOrThrow();
+            const listed = await this.db
+                .selectFrom("catalog_item_scope_orgs")
+                .select("item_id")
+                .where("item_id", "=", dep.itemId)
+                .where("org_id", "=", orgId)
+                .executeTakeFirst();
+            if (!visibleTo({ scope: item.builtin ? "all" : item.scope }, listed !== undefined)) {
+                throw refuse(`${provider} is not offered to this organization`);
+            }
+            if (await this.findLiveDependency(this.db, orgId, dep, false)) {
+                throw refuse(`${provider} is installed but switched off in this organization`);
+            }
+            out.push(dep);
+        }
+        return out;
+    }
     /**
      * The connector input of one template from the org's input (C30), checked without a connection:
      * the template's connector extension deployed, the input valid, the credential / OAuth client it
@@ -355,7 +602,7 @@ export class PluginInstaller {
                     : `This connector template needs ${needs}`);
         }
         try {
-            this.d.connectors.checkCreateInput(actor, ci);
+            this.connectors.checkCreateInput(actor, ci);
         }
         catch (e) {
             throw under(e, path);
@@ -397,30 +644,30 @@ export class PluginInstaller {
      * cannot leave the component pointing at a removed install. `created` false: the org's existing
      * install, if any (returns its id, undefined when there is none); it must be `installed`
      * (`installing` -> 409 `plugin.install_in_progress`, retry later) and in range. `created` true:
-     * `child`, the dependency install this install just created, must still exist.
+     * `child`, the dependency install this install just created, must still exist. A step of an
+     * install or upgrade: it commits on its own (`requires_new`), the undo on failure relies on it.
      */
     async recordDependency(orgId, dep, record, child) {
-        return this.d.db.transaction().execute(async (t) => {
-            await lockOrg(t, orgId);
-            const live = await this.findLiveDependency(t, orgId, dep, true);
-            if (child !== undefined) {
-                if (live?.id !== child || live.status !== "installed") {
-                    throw unresolved(dep.name, dep.range, "its install in this organization was removed meanwhile; try again");
-                }
-                await record({ kind: "plugin", ref: child, created: true, skillVersion: null }, t);
-                return child;
-            }
-            if (!live)
-                return undefined;
-            if (!satisfiesRange(live.version, dep.range)) {
-                throw unresolved(dep.name, dep.range, `this organization has version ${live.version} installed; uninstall it to install a matching version`);
+        const t = this.db;
+        await this.orgLock.lock(orgId);
+        const live = await this.findLiveDependency(t, orgId, dep, true);
+        if (child !== undefined) {
+            if (live?.id !== child || live.status !== "installed") {
+                throw unresolved(dep.name, dep.range, "its install in this organization was removed meanwhile; try again");
             }
-            if (live.status !== "installed") {
-                throw new ApiError("plugin.install_in_progress", `Dependency ${dep.name} is being installed by another install in this organization; try again when it finishes. An install stuck for longer than catalog.staleInstallMinutes can be removed by uninstalling it`);
-            }
-            await record({ kind: "plugin", ref: live.id, created: false, skillVersion: null }, t);
-            return live.id;
-        });
+            await record({ kind: "plugin", ref: child, created: true, skillVersion: null });
+            return child;
+        }
+        if (!live)
+            return undefined;
+        if (!satisfiesRange(live.version, dep.range)) {
+            throw unresolved(dep.name, dep.range, `this organization has version ${live.version} installed; uninstall it to install a matching version`);
+        }
+        if (live.status !== "installed") {
+            throw new ApiError("plugin.install_in_progress", `Dependency ${dep.name} is being installed by another install in this organization; try again when it finishes. An install stuck for longer than catalog.staleInstallMinutes can be removed by uninstalling it`);
+        }
+        await record({ kind: "plugin", ref: live.id, created: false, skillVersion: null });
+        return live.id;
     }
     /**
      * Runs a plan: the install row, then the steps (see the class comment). Throws
@@ -428,63 +675,19 @@ export class PluginInstaller {
      * as they are. Returns the install id.
      */
     async execute(orgId, actor, plan, opts, ctx) {
-        const { itemId, version, manifest } = plan;
+        const { itemId, manifest } = plan;
         // The install row (role and item policy re-checked under the lock; one live install per org
         // and item)
         const installId = randomUUID();
-        await this.d.db.transaction().execute(async (t) => {
-            await lockOrgForActions(t, orgId, actor, ctx.actions);
-            if (ctx.approvedBy !== undefined) {
-                // A dependency disabled (or removed) since it was planned
-                const own = await t
-                    .selectFrom("catalog_items")
-                    .select(["policy", "deleted_at"])
-                    .where("id", "=", itemId)
-                    .forShare()
-                    .executeTakeFirst();
-                if (!own || own.deleted_at !== null) {
-                    throw unresolved(plan.name, plan.version, "it was removed from the enterprise catalog");
-                }
-                if (own.policy === "disabled")
-                    throw dependencyDisabled(plan.name);
-            }
-            await assertItemInstallable(t, orgId, itemId, ctx.approvedBy ?? itemId);
-            const live = await t
-                .selectFrom("plugin_installs")
-                .select("id")
-                .where("org_id", "=", orgId)
-                .where("item_id", "=", itemId)
-                .where("status", "<>", "failed")
-                .executeTakeFirst();
-            if (live)
-                throw alreadyInstalled();
-            try {
-                await t
-                    .insertInto("plugin_installs")
-                    .values({
-                    id: installId,
-                    org_id: orgId,
-                    item_id: itemId,
-                    version,
-                    status: "installing",
-                    installed_by: actor,
-                })
-                    .execute();
-            }
-            catch (e) {
-                if (isUniqueViolation(e))
-                    throw alreadyInstalled();
-                throw e;
-            }
-        });
+        await this.createInstallRow(orgId, actor, plan, ctx, installId);
         const done = [];
-        // Records a component in the given transaction (the install row already cleaned up -> the FK
-        // fails, the install aborts and rolls back)
-        const record = async (c, t) => {
+        // Records a component in the transaction of the context (none: on its own; the install row
+        // already cleaned up -> the FK fails, the install aborts and rolls back)
+        const record = async (c) => {
             // Into `done` first: a component that exists is rolled back even when recording it fails
             // (enabling an extension and recording it share one transaction and fail together)
             done.push(c);
-            await (t ?? this.d.db)
+            await this.db
                 .insertInto("plugin_install_components")
                 .values({
                 install_id: installId,
@@ -514,6 +717,7 @@ export class PluginInstaller {
                         actions: requiredActions(depPlan.manifest),
                         approvedBy,
                         parent: installId,
+                        ...(ctx.via !== undefined && { via: ctx.via }),
                     });
                 }
                 catch (e) {
@@ -532,25 +736,19 @@ export class PluginInstaller {
             }
             step = "extension";
             if (plan.extension !== null) {
-                const p = plan.extension;
-                // "Enabled before" is decided under the org row lock (already enabled: put writes nothing,
-                // the config is untouched); the component is recorded in the same transaction
-                await this.d.orgConfigs.put(orgId, p, {
+                await this.enableExtension(orgId, plan.extension, {
                     enabled: true,
                     ...(plan.extensionConfig !== undefined && { config: plan.extensionConfig }),
-                }, actor, opts.actorTokenId, {
-                    viaItem: itemId,
-                    ...(nested && { approvedBy }),
-                    ifDisabled: { skipped: false },
-                    inTransaction: (t, skipped) => record({ kind: "extension", ref: p, created: !skipped, skillVersion: null }, t),
-                });
+                }, actor, opts.actorTokenId, { viaItem: itemId, ...(nested && { approvedBy }) }, record);
             }
             step = "connectors";
             for (const ct of plan.templates) {
                 const ci = plan.connectors.get(ct.id);
                 if (!ci)
                     throw new ApiError("internal", `Connector template ${ct.id} was not planned`);
-                const r = await this.d.connectors.create(orgId, actor, ci, opts.actorTokenId);
+                if (actor === null)
+                    throw systemNeedsInput(manifest.name);
+                const r = await this.connectors.create(orgId, actor, ci, opts.actorTokenId);
                 await record({
                     kind: "connector",
                     ref: r.connector.id,
@@ -559,109 +757,170 @@ export class PluginInstaller {
                     templateId: ct.id,
                 });
             }
-            step = "agent_templates";
-            for (const a of plan.agentTemplates) {
-                // Created (or a new version of the org's live template of this plugin and name) and
-                // recorded in one transaction, under the org row lock
-                await this.d.db.transaction().execute(async (t) => {
-                    await lockOrg(t, orgId);
-                    const r = await putTemplateVersionIn(t, {
-                        orgId,
-                        plugin: plan.name,
-                        catalogItemId: itemId,
-                        catalogVersion: version,
-                        sourceFormat: plan.sourceFormat,
-                    }, a.template);
-                    await record({
-                        kind: "agent_template",
-                        ref: r.id,
-                        created: r.created,
-                        skillVersion: !r.created && r.changed ? r.version : null,
-                    }, t);
-                });
-            }
-            step = "skills";
-            for (const s of manifest.skills ?? []) {
-                const files = await readCatalogFiles(this.d.storage, plan.row.object_prefix, plan.row.files, packagePath(s.path));
-                const r = await this.d.skills.createVersionFromFiles(orgId, actor, { ...skillOf(files), files }, {
-                    catalog: {
-                        itemId,
-                        version,
-                        ...(nested && { approvedBy }),
-                        format: plan.sourceFormat,
-                        suggestPinned: s.pinned === true,
-                    },
-                    ...opts,
-                });
-                await record({
-                    kind: "skill",
-                    ref: r.skill.id,
-                    created: r.created,
-                    skillVersion: r.created ? null : r.version,
-                });
-            }
-            await this.d.db.transaction().execute(async (t) => {
-                await lockOrg(t, orgId);
-                const updated = await t
-                    .updateTable("plugin_installs")
-                    .set({ status: "installed" })
-                    .where("id", "=", installId)
-                    .where("status", "=", "installing")
-                    .executeTakeFirst();
-                // The install row was already cleaned up as stale: do not audit plugin.org_installed, roll
-                // back
-                if (updated.numUpdatedRows === 0n) {
-                    throw new ApiError("plugin.install_not_found", "The install record was cleaned up as stale while the install was running");
-                }
-                await this.d.requests.resolveByInstall(t, orgId, itemId, actor, opts);
-                await audit(t, {
-                    actorAccountId: actor,
-                    ...(opts.actorTokenId !== undefined && { actorTokenId: opts.actorTokenId }),
-                    orgId,
-                    action: "plugin.org_installed",
-                    target: installId,
-                    detail: {
-                        itemId,
-                        name: plan.name,
-                        version,
-                        components: done,
-                        ...(ctx.parent !== undefined && { dependencyOf: ctx.parent }),
-                    },
-                });
-            });
+            // Skills and agent templates are platform components (plugin scope phase 2): stored once for
+            // the deployment and on in the org while the plugin is, so the install writes no org rows
+            await this.markInstalled(orgId, actor, installId, plan, done, ctx, opts);
             return installId;
         }
         catch (e) {
             const failure = e instanceof InstallFailure ? e : undefined;
             const code = failure ? failure.code : e instanceof ApiError ? e.code : "internal";
             const rollbackErrors = await this.rollback(orgId, actor, installId, done, opts);
-            await this.d.db.transaction().execute(async (t) => {
-                await t
-                    .updateTable("plugin_installs")
-                    .set({ status: "failed", error: JSON.stringify({ step, code }) })
-                    .where("id", "=", installId)
-                    .execute();
-                await audit(t, {
-                    actorAccountId: actor,
-                    ...(opts.actorTokenId !== undefined && { actorTokenId: opts.actorTokenId }),
-                    orgId,
-                    action: "plugin.org_install_failed",
-                    target: installId,
-                    detail: {
-                        itemId,
-                        name: plan.name,
-                        version,
-                        step,
-                        code,
-                        rolledBack: done,
-                        rollbackErrors,
-                        ...(ctx.parent !== undefined && { dependencyOf: ctx.parent }),
-                    },
-                });
-            });
+            await this.markFailed(orgId, actor, installId, plan, ctx, { step, code, done, rollbackErrors }, opts);
             throw new InstallFailure(failure ? failure.step : step, failure ? failure.cause : e, failure ? failure.dependency : [], rollbackErrors.length === 0 && (failure?.rolledBack ?? true));
         }
     }
+    /**
+     * The install row (role and item policy re-checked under the lock; one live install per org and
+     * item). A step of the install: committed on its own.
+     */
+    /**
+     * Enables a plugin's extension for the org and records it as a component of the install, in one
+     * transaction (`put` joins it): "enabled before" is decided under the org row lock (already
+     * enabled: `put` writes nothing, the config is untouched, the component is recorded as not
+     * created), and the ledger row is written before the COMMIT, so no concurrent uninstall fits
+     * between enabling and recording. Used by the install and the upgrade.
+     */
+    async enableExtension(orgId, name, input, actor, actorTokenId, opts, record) {
+        const ifDisabled = { skipped: false };
+        await this.orgConfigs.put(orgId, name, input, actor, actorTokenId, { ...opts, ifDisabled });
+        await record({
+            kind: "extension",
+            ref: name,
+            created: !ifDisabled.skipped,
+            skillVersion: null,
+        });
+    }
+    async createInstallRow(orgId, actor, plan, ctx, installId) {
+        const { itemId, version } = plan;
+        const t = this.db;
+        await lockOrgForActions(this.orgLock, orgId, actor, ctx.actions);
+        // The scope sync decided outside this lock: a person's switch-off or a scope change committed
+        // since then wins (nothing written, converged)
+        if (ctx.via === "scope" &&
+            ctx.approvedBy === undefined &&
+            !(await wantedByScope(t, orgId, itemId))) {
+            throw new ScopeNoLongerWanted(orgId, itemId);
+        }
+        if (ctx.approvedBy !== undefined) {
+            // A dependency disabled (or removed) since it was planned
+            const own = await t
+                .selectFrom("catalog_items")
+                .select(["disabled", "deleted_at"])
+                .where("id", "=", itemId)
+                .forShare()
+                .executeTakeFirst();
+            if (!own || own.deleted_at !== null) {
+                throw unresolved(plan.name, plan.version, "it was removed from the platform catalog");
+            }
+            if (own.disabled)
+                throw dependencyDisabled(plan.name);
+        }
+        await assertItemInstallable(t, orgId, itemId, ctx.approvedBy ?? itemId);
+        const live = await t
+            .selectFrom("plugin_installs")
+            .select("id")
+            .where("org_id", "=", orgId)
+            .where("item_id", "=", itemId)
+            .where("status", "<>", "failed")
+            .executeTakeFirst();
+        if (live)
+            throw alreadyInstalled();
+        try {
+            await t
+                .insertInto("plugin_installs")
+                .values({
+                id: installId,
+                org_id: orgId,
+                item_id: itemId,
+                version,
+                status: "installing",
+                installed_by: actor,
+            })
+                .execute();
+        }
+        catch (e) {
+            if (isUniqueViolation(e))
+                throw alreadyInstalled();
+            throw e;
+        }
+    }
+    /** The install `installed` and its `plugin.org_installed` audit, under the org row lock (its own transaction). */
+    async markInstalled(orgId, actor, installId, plan, done, ctx, opts) {
+        const { itemId, version } = plan;
+        const t = this.db;
+        await this.orgLock.lock(orgId);
+        // The platform version current at commit (one per deployment): a platform update that
+        // committed while this install ran moved the row already, or did not see it yet
+        const updated = await t
+            .updateTable("plugin_installs")
+            .set((eb) => ({
+            status: "installed",
+            version: eb.fn.coalesce(eb
+                .selectFrom("catalog_items as i")
+                .select("i.platform_synced_version")
+                .where("i.id", "=", itemId), eb.ref("plugin_installs.version")),
+        }))
+            .where("id", "=", installId)
+            .where("status", "=", "installing")
+            .executeTakeFirst();
+        // The install row was already cleaned up as stale: do not audit plugin.org_installed, roll
+        // back
+        if (updated.numUpdatedRows === 0n) {
+            throw new ApiError("plugin.install_not_found", "The install record was cleaned up as stale while the install was running");
+        }
+        await resolveRequestsByInstall(t, orgId, itemId, actor, opts);
+        // The org switch is written with the install, in one transaction under the org lock
+        if (ctx.switchOn === true && ctx.parent === undefined) {
+            await upsertOrgSwitch(t, orgId, itemId, true, actor);
+        }
+        await audit(t, {
+            actorAccountId: actor,
+            ...(opts.actorTokenId !== undefined && { actorTokenId: opts.actorTokenId }),
+            orgId,
+            action: "plugin.org_installed",
+            target: installId,
+            detail: {
+                itemId,
+                name: plan.name,
+                version,
+                components: done,
+                ...(ctx.parent !== undefined && { dependencyOf: ctx.parent }),
+                ...(ctx.via !== undefined && { via: ctx.via }),
+                ...opts.auditDetail,
+            },
+        });
+    }
+    /** The install `failed` with `{ step, code }` and its `plugin.org_install_failed` audit (its own transaction). */
+    async markFailed(orgId, actor, installId, plan, ctx, f, opts) {
+        const { itemId, version } = plan;
+        const { step, code, done, rollbackErrors } = f;
+        const t = this.db;
+        await t
+            .updateTable("plugin_installs")
+            .set({ status: "failed", error: JSON.stringify({ step, code }) })
+            .where("id", "=", installId)
+            .execute();
+        await audit(t, {
+            actorAccountId: actor,
+            ...(opts.actorTokenId !== undefined && { actorTokenId: opts.actorTokenId }),
+            orgId,
+            action: "plugin.org_install_failed",
+            target: installId,
+            detail: {
+                itemId,
+                name: plan.name,
+                version,
+                step,
+                code,
+                rolledBack: done,
+                rollbackErrors,
+                ...(ctx.parent !== undefined && { dependencyOf: ctx.parent }),
+                ...(ctx.via !== undefined && { via: ctx.via }),
+                ...opts.auditDetail,
+            },
+        });
+    }
     /**
      * The extension to enable: the plugin's own, when it has one. Not loaded on this replica ->
      * `catalog.not_deployed`; not yet enabled in this org while its own catalog item is disabled ->
@@ -672,11 +931,11 @@ export class PluginInstaller {
         if (!manifest.extension)
             return null;
         const name = manifest.name;
-        if (!this.d.host.manifests().some((m) => m.name === name)) {
-            throw new ApiError("catalog.not_deployed", `The extension of plugin ${name} is not deployed; ask the enterprise admin to install and enable it`);
+        if (!this.registry.manifests().some((m) => m.name === name)) {
+            throw new ApiError("catalog.not_deployed", `The extension of plugin ${name} is not running on the platform (not installed, waiting for its deployment config or permission approval, disabled, or failed to load); the org cannot switch it on until it runs`);
         }
-        const enabled = await isExtensionEnabled(this.d.db, orgId, name);
-        if (!enabled && (await disabledPluginItems(this.d.db, [name])).length > 0) {
+        const enabled = await isExtensionEnabled(this.db, orgId, name);
+        if (!enabled && (await disabledPluginItems(this.db, [name])).length > 0) {
             throw pluginItemDisabled([name]);
         }
         return name;
@@ -705,46 +964,13 @@ export class PluginInstaller {
             if (!c.created && c.skillVersion === null)
                 continue;
             try {
-                const disabled = [];
-                await this.d.db.transaction().execute(async (t) => {
-                    await lockOrg(t, orgId);
-                    if (c.kind === "plugin") {
-                        // A dependency install this install created: uninstalled by the usual rules
-                        const sub = { removed: [], kept: [] };
-                        await this.uninstallIn(t, orgId, actor, c.ref, {
-                            report: sub,
-                            removing: new Set([installId]),
-                            from: installId,
-                            authorize: false,
-                            reason: "plugin_install_rollback",
-                            opts,
-                        });
-                        disabled.push(...sub.removed.filter((r) => r.kind === "extension").map((r) => r.ref));
-                    }
-                    else {
-                        // Another enabled extension depends on it (only it provides what that one needs in this
-                        // org): kept (its component row too), so the other does not lose its dependency
-                        if (c.kind === "extension" &&
-                            (await this.d.orgConfigs.enabledDependents(t, orgId, c.ref)).length > 0) {
-                            return;
-                        }
-                        const removed = await this.removeComponent(t, orgId, actor, c, "plugin_install_rollback");
-                        if (removed && c.kind === "extension")
-                            disabled.push(c.ref);
-                    }
-                    await t
-                        .deleteFrom("plugin_install_components")
-                        .where("install_id", "=", installId)
-                        .where("kind", "=", c.kind)
-                        .where("ref", "=", c.ref)
-                        .execute();
-                });
+                const disabled = await this.rollbackOne(orgId, actor, installId, c, opts);
                 for (const p of disabled)
-                    await this.d.orgConfigs.afterDisable(orgId, p);
+                    await this.orgConfigs.afterDisable(orgId, p);
             }
             catch (e) {
                 errors.push({ kind: c.kind, ref: c.ref });
-                this.d.log?.warn("plugin install rollback step failed", {
+                this.log.warn("plugin install rollback step failed", {
                     orgId,
                     kind: c.kind,
                     ref: c.ref,
@@ -754,11 +980,53 @@ export class PluginInstaller {
         }
         return errors;
     }
+    /**
+     * Undoes one component of a failed install and deletes its component row, under the org row lock,
+     * in a transaction of its own (committed when it returns); returns the extensions it disabled
+     * (the caller notifies them).
+     */
+    async rollbackOne(orgId, actor, installId, c, opts) {
+        const disabled = [];
+        const t = this.db;
+        await this.orgLock.lock(orgId);
+        if (c.kind === "plugin") {
+            // A dependency install this install created: uninstalled by the usual rules
+            const sub = { removed: [], kept: [] };
+            await this.uninstallIn(orgId, actor, c.ref, {
+                report: sub,
+                removing: new Set([installId]),
+                from: installId,
+                authorize: false,
+                reason: "plugin_install_rollback",
+                opts,
+            });
+            disabled.push(...sub.removed.filter((r) => r.kind === "extension").map((r) => r.ref));
+        }
+        else {
+            // Another enabled extension depends on it (only it provides what that one needs in this
+            // org): kept (its component row too), so the other does not lose its dependency
+            if (c.kind === "extension" &&
+                (await this.orgConfigs.enabledDependents(orgId, c.ref)).length > 0) {
+                return [];
+            }
+            const removed = await this.removeComponent(orgId, actor, c, "plugin_install_rollback");
+            if (removed && c.kind === "extension")
+                disabled.push(c.ref);
+        }
+        await t
+            .deleteFrom("plugin_install_components")
+            .where("install_id", "=", installId)
+            .where("kind", "=", c.kind)
+            .where("ref", "=", c.ref)
+            .execute();
+        return disabled;
+    }
     /** Removes one component (one already gone is no error); returns whether anything changed. */
-    async removeComponent(t, orgId, actor, c, reason) {
+    async removeComponent(orgId, actor, c, reason) {
         if (c.kind === "extension") {
-            return this.d.orgConfigs.disableIn(t, orgId, c.ref, actor, reason);
+            return this.orgConfigs.disableIn(orgId, c.ref, actor, reason);
         }
+        const t = this.db;
         if (c.kind === "connector") {
             const live = await t
                 .selectFrom("connectors")
@@ -769,11 +1037,18 @@ export class PluginInstaller {
                 .executeTakeFirst();
             if (!live)
                 return false;
-            await this.d.connectors.removeIn(t, orgId, c.ref, actor, undefined, reason);
+            await this.connectors.removeIn(orgId, c.ref, actor, undefined, reason);
             return true;
         }
         if (c.kind === "plugin")
             return false;
+        // A row the org promoted is the org's own shared item (ruling P3-47): an install never
+        // removes or reverts it (P3-46 keeps plugin content from being promoted; this guards rows
+        // recorded before that or by a legacy install)
+        if ((c.kind === "agent_template" || c.kind === "skill") &&
+            (await promotedOrgRow(t, orgId, c.kind, c.ref))) {
+            return false;
+        }
         if (c.kind === "agent_template") {
             if (c.created)
                 return softDeleteTemplateIn(t, orgId, c.ref);
@@ -783,9 +1058,9 @@ export class PluginInstaller {
             return false;
         }
         if (c.created)
-            return this.d.skills.softDeleteIn(t, orgId, c.ref, actor, reason);
+            return this.skills.softDeleteIn(orgId, c.ref, actor, reason);
         if (c.skillVersion !== null) {
-            return this.d.skills.revertVersionIn(t, orgId, c.ref, c.skillVersion, actor, reason);
+            return this.skills.revertVersionIn(orgId, c.ref, c.skillVersion, actor, reason);
         }
         return false;
     }
@@ -811,35 +1086,115 @@ export class PluginInstaller {
      * (a replica crashed midway) - the last two are cleaned up as a rollback (versions added to
      * existing skills are reverted too). Still installing -> `plugin.install_in_progress`.
      */
-    async uninstall(orgId, actor, installId, opts = {}) {
+    async uninstall(orgId, actor, installId, opts = {}, sw) {
         if (!UUID_RE.test(installId))
             throw installNotFound();
+        return this.writeUninstall(orgId, actor, installId, opts, sw);
+    }
+    /**
+     * The uninstall's one transaction; the extensions it disabled are notified once it commits. A
+     * scope sync uninstall (`via: "scope"`) re-checks under the org row lock that the item is still
+     * not wanted in the org and that no other live install depends on it ({@link ScopeStillWanted},
+     * nothing written), and keeps the connectors it created as the org's own (`org_owned`).
+     */
+    async writeUninstall(orgId, actor, installId, opts, sw) {
+        const { via, ...actorOpts } = opts;
         const report = { removed: [], kept: [] };
-        await this.d.db.transaction().execute(async (t) => {
-            const outcome = await this.uninstallIn(t, orgId, actor, installId, {
-                report,
-                removing: new Set(),
-                authorize: true,
-                opts,
-            });
-            if (outcome === "missing")
-                throw installNotFound();
-            if (outcome === "kept") {
-                report.kept.push({ kind: "plugin", ref: installId, reason: "used_by_other_install" });
+        let itemId;
+        if (via === "scope") {
+            // A person's switch-on (or a scope change) committed after the sync's decision wins
+            await this.orgLock.lock(orgId);
+            const row = await this.db
+                .selectFrom("plugin_installs")
+                .select("item_id")
+                .where("id", "=", installId)
+                .where("org_id", "=", orgId)
+                .executeTakeFirst();
+            if (row !== undefined &&
+                ((await wantedByScope(this.db, orgId, row.item_id)) ||
+                    (await this.heir(orgId, new Set([installId]), "plugin", installId)) !== undefined)) {
+                throw new ScopeStillWanted(orgId, row.item_id);
+            }
+        }
+        if (sw !== undefined) {
+            // Switching off: the org lock first, then the preview is re-checked and the switch row is
+            // written in this same transaction
+            await this.orgLock.lock(orgId);
+            const row = await this.db
+                .selectFrom("plugin_installs")
+                .select("item_id")
+                .where("id", "=", installId)
+                .where("org_id", "=", orgId)
+                .executeTakeFirst();
+            itemId = row?.item_id;
+            // The item row FOR SHARE, as a switch without an uninstall takes it: an owner's delete or
+            // transfer (FOR UPDATE) decides on who uses it
+            if (itemId !== undefined) {
+                await this.db
+                    .selectFrom("catalog_items")
+                    .select("id")
+                    .where("id", "=", itemId)
+                    .forShare()
+                    .executeTakeFirst();
+            }
+            if (sw.expectHash !== undefined && row !== undefined) {
+                const now = uninstallPreviewHash(await this.previewUninstall(orgId, installId));
+                if (now !== sw.expectHash) {
+                    throw new ApiError("plugin.switch_stale", "The uninstall preview changed; review it and confirm again");
+                }
             }
+        }
+        // An org's own uninstall never takes the platform default theme away from it (themes spec §7;
+        // a scope sync uninstall follows a scope change or disable that was guarded already)
+        if (via !== "scope")
+            await this.assertKeepsPlatformDefault(orgId, installId);
+        const outcome = await this.uninstallIn(orgId, actor, installId, {
+            report,
+            removing: new Set(),
+            authorize: true,
+            opts: actorOpts,
+            ...(via !== undefined && { via }),
         });
-        for (const r of report.removed) {
-            if (r.kind === "extension")
-                await this.d.orgConfigs.afterDisable(orgId, r.ref);
+        if (outcome === "missing")
+            throw installNotFound();
+        if (outcome === "kept") {
+            report.kept.push({ kind: "plugin", ref: installId, reason: "used_by_other_install" });
         }
+        if (itemId !== undefined && outcome === "removed") {
+            await upsertOrgSwitch(this.db, orgId, itemId, false, actor);
+        }
+        afterCommit(async () => {
+            for (const r of report.removed) {
+                if (r.kind === "extension")
+                    await this.orgConfigs.afterDisable(orgId, r.ref);
+            }
+        });
         return report;
     }
+    /**
+     * 409 `theme.platform_default` when uninstalling `installId` would switch the platform default
+     * theme off in the org (one of the plugin's `follow` themes on there through it, themes spec §7),
+     * in the caller's transaction before anything is written. A missing install passes (the
+     * uninstall reports it).
+     */
+    async assertKeepsPlatformDefault(orgId, installId) {
+        const found = await this.db
+            .selectFrom("plugin_installs")
+            .select("id")
+            .where("id", "=", installId)
+            .where("org_id", "=", orgId)
+            .executeTakeFirst();
+        if (!found)
+            return;
+        const p = await this.previewUninstall(orgId, installId);
+        await assertNotPlatformDefault(this.db, (p.themes ?? []).map((t) => t.id), () => "narrower");
+    }
     /**
      * The oldest other live install (not in `removing`) that has component `kind` / `ref`, or
      * undefined.
      */
-    async heir(t, orgId, removing, kind, ref) {
-        let q = t
+    async heir(orgId, removing, kind, ref) {
+        let q = this.db
             .selectFrom("plugin_install_components as c")
             .innerJoin("plugin_installs as a", "a.id", "c.install_id")
             .select("a.id")
@@ -853,8 +1208,8 @@ export class PluginInstaller {
         return row?.id;
     }
     /** Passes ownership of a component to `heir` (its component row becomes created=true). */
-    async handOver(t, heir, kind, ref) {
-        await t
+    async handOver(heir, kind, ref) {
+        await this.db
             .updateTable("plugin_install_components")
             .set({ created: true })
             .where("install_id", "=", heir)
@@ -868,7 +1223,8 @@ export class PluginInstaller {
      * outcome of the install itself is returned for the caller to report: `missing`, `kept` (another
      * install outside this uninstall depends on it) or `removed`.
      */
-    async uninstallIn(t, orgId, actor, installId, ctx) {
+    async uninstallIn(orgId, actor, installId, ctx) {
+        const t = this.db;
         const { removing } = ctx;
         if (removing.has(installId))
             return "removed";
@@ -882,7 +1238,7 @@ export class PluginInstaller {
             mine.kept.push(x);
             ctx.report.kept.push(x);
         };
-        const staleMinutes = this.d.staleInstallMinutes();
+        const staleMinutes = this.staleInstallMinutes();
         if (ctx.authorize) {
             const target = await t
                 .selectFrom("plugin_installs as a")
@@ -891,7 +1247,7 @@ export class PluginInstaller {
                 .where("a.id", "=", installId)
                 .where("a.org_id", "=", orgId)
                 .executeTakeFirst();
-            await lockOrgForActions(t, orgId, actor, target ? requiredActions(target.manifest) : ALL_ACTIONS);
+            await lockOrgForActions(this.orgLock, orgId, actor, target ? requiredActions(target.manifest) : ALL_ACTIONS);
         }
         const row = await t
             .selectFrom("plugin_installs as a")
@@ -912,12 +1268,17 @@ export class PluginInstaller {
             .executeTakeFirst();
         if (!row)
             return "missing";
+        // A dependency its own scope still wants on in the org stays as a standalone install (the
+        // dependent's component row goes with the dependent's install row)
+        if (ctx.from !== undefined && (await wantedByScope(t, orgId, row.item_id))) {
+            return "wanted_by_scope";
+        }
         // Another install outside this uninstall depends on it: kept (a dependency uninstall hands
         // ownership over)
-        const user = await this.heir(t, orgId, new Set([...removing, installId]), "plugin", installId);
+        const user = await this.heir(orgId, new Set([...removing, installId]), "plugin", installId);
         if (user !== undefined) {
             if (ctx.from !== undefined)
-                await this.handOver(t, user, "plugin", installId);
+                await this.handOver(user, "plugin", installId);
             return "kept";
         }
         if (row.status === "uninstalling" ||
@@ -927,7 +1288,7 @@ export class PluginInstaller {
         }
         if (row.status === "upgrading") {
             // An upgrade interrupted midway (a replica crashed): undone first, back at the old version
-            const undone = await this.undoUpgradeIn(t, orgId, actor, installId, journalEntries(row.upgrade), "plugin_upgrade_cleanup");
+            const undone = await this.undoUpgradeIn(orgId, actor, installId, journalEntries(row.upgrade), "plugin_upgrade_cleanup");
             for (const x of undone)
                 addRemoved(x);
         }
@@ -953,7 +1314,7 @@ export class PluginInstaller {
                     ? 2 + extensionOrder.indexOf(c.ref)
                     : 1000 + (c.created ? 0 : 1);
         comps.sort((a, b) => rank(a) - rank(b));
-        const agentRefs = await this.agentRefs(t, orgId);
+        const agentRefs = await this.agentRefs(orgId);
         for (const c of comps) {
             const keep = (reason) => addKept({ kind: c.kind, ref: c.ref, reason });
             let created = c.created;
@@ -977,13 +1338,17 @@ export class PluginInstaller {
                 created = now.created;
             }
             const comp = { kind: c.kind, ref: c.ref, created, skillVersion: c.skill_version };
+            // Skills and agent templates of earlier installs (org copies, now linked to the platform
+            // components, phase 2) stay: the plugin's components go off in the org with the install
+            if ((c.kind === "skill" || c.kind === "agent_template") && !rollbackMode)
+                continue;
             if (!created) {
                 // Rollback cleanup: a version this install added to an existing skill is reverted; other
                 // pre-existing components are kept
                 if (rollbackMode &&
                     (c.kind === "skill" || c.kind === "agent_template") &&
                     c.skill_version !== null &&
-                    (await this.removeComponent(t, orgId, actor, comp, "plugin_install_cleanup"))) {
+                    (await this.removeComponent(orgId, actor, comp, "plugin_install_cleanup"))) {
                     addRemoved({ kind: c.kind, ref: c.ref });
                     continue;
                 }
@@ -991,15 +1356,23 @@ export class PluginInstaller {
                 continue;
             }
             if (c.kind === "plugin") {
-                const outcome = await this.uninstallIn(t, orgId, actor, c.ref, { ...ctx, from: installId });
+                const outcome = await this.uninstallIn(orgId, actor, c.ref, { ...ctx, from: installId });
                 if (outcome === "removed")
                     addRemoved({ kind: "plugin", ref: c.ref });
                 else if (outcome === "kept")
                     keep("used_by_other_install");
+                else if (outcome === "wanted_by_scope")
+                    keep("wanted_by_scope");
+                continue;
+            }
+            // A scope sync uninstall leaves the connectors to the org (spec §5 rule 8): the component row
+            // goes with the install row, so nothing removes them later
+            if (c.kind === "connector" && ctx.via === "scope" && !rollbackMode) {
+                keep("org_owned");
                 continue;
             }
             const reason = rollbackMode ? "plugin_install_cleanup" : (ctx.reason ?? "plugin_uninstall");
-            const outcome = await this.decideRemovalIn(t, orgId, actor, comp, removing, agentRefs, reason);
+            const outcome = await this.decideRemovalIn(orgId, actor, comp, removing, agentRefs, reason);
             if (outcome === "removed")
                 addRemoved({ kind: c.kind, ref: c.ref });
             else if (outcome !== "gone")
@@ -1020,6 +1393,8 @@ export class PluginInstaller {
                 removed: mine.removed,
                 kept: mine.kept,
                 ...(ctx.from !== undefined && { dependencyOf: ctx.from }),
+                ...(ctx.via !== undefined && { via: ctx.via }),
+                ...ctx.opts.auditDetail,
             },
         });
         return "removed";
@@ -1034,7 +1409,7 @@ export class PluginInstaller {
      * (`used_by_plugins`); otherwise removed (`removed`, or `gone` when it no longer existed). Used
      * by uninstall and by an upgrade's removals.
      */
-    async decideRemovalIn(t, orgId, actor, c, removing, agentRefs, reason) {
+    async decideRemovalIn(orgId, actor, c, removing, agentRefs, reason) {
         if (c.kind === "skill" && agentRefs.skills.has(c.ref))
             return "used_by_agents";
         if (c.kind === "agent_template" && agentRefs.templates.has(c.ref))
@@ -1042,16 +1417,16 @@ export class PluginInstaller {
         if (c.kind === "connector" && agentRefs.connectors.has(c.ref))
             return "used_by_agents";
         if (c.kind !== "connector") {
-            const heir = await this.heir(t, orgId, removing, c.kind, c.ref);
+            const heir = await this.heir(orgId, removing, c.kind, c.ref);
             if (heir !== undefined) {
-                await this.handOver(t, heir, c.kind, c.ref);
+                await this.handOver(heir, c.kind, c.ref);
                 return "used_by_other_install";
             }
         }
         if (c.kind === "extension") {
             const kinds = this.connectorKindsOf(c.ref);
             if (kinds.length > 0) {
-                const used = await t
+                const used = await this.db
                     .selectFrom("connectors")
                     .select("id")
                     .where("org_id", "=", orgId)
@@ -1061,21 +1436,21 @@ export class PluginInstaller {
                 if (used)
                     return "used_by_connectors";
             }
-            if ((await this.d.orgConfigs.enabledDependents(t, orgId, c.ref)).length > 0) {
+            if ((await this.orgConfigs.enabledDependents(orgId, c.ref)).length > 0) {
                 return "used_by_plugins";
             }
         }
-        return (await this.removeComponent(t, orgId, actor, c, reason)) ? "removed" : "gone";
+        return (await this.removeComponent(orgId, actor, c, reason)) ? "removed" : "gone";
     }
     /** The order extensions are uninstalled in: the reverse of the install (requires) order; extensions not loaded on this replica last. */
     uninstallExtensionOrder(refs) {
-        const loaded = new Map(this.d.host.manifests().map((m) => [m.name, m]));
+        const loaded = new Map(this.registry.manifests().map((m) => [m.name, m]));
         const known = refs.filter((r) => loaded.has(r)).map((r) => loaded.get(r));
         return [...orderByRequires(known).reverse(), ...refs.filter((r) => !loaded.has(r))];
     }
     /** The org's plugin installs (failed ones included), newest first; `installId` picks one. */
     async list(orgId, installId) {
-        let q = this.d.db
+        let q = this.db
             .selectFrom("plugin_installs as a")
             .innerJoin("catalog_items as i", "i.id", "a.item_id")
             .select([
@@ -1094,8 +1469,7 @@ export class PluginInstaller {
         const rows = await q.orderBy("a.installed_at", "desc").orderBy("a.id").execute();
         if (rows.length === 0)
             return [];
-        const info = await upgradeInfo(this.d.db, this.d.host, rows.map((r) => ({ itemId: r.item_id, name: r.name, version: r.version })));
-        const comps = await this.d.db
+        const comps = await this.db
             .selectFrom("plugin_install_components")
             .select(["install_id", "kind", "ref", "created", "skill_version", "dropped"])
             .where("install_id", "in", rows.map((r) => r.id))
@@ -1118,8 +1492,8 @@ export class PluginInstaller {
                 skillVersion: c.skill_version,
                 dropped: c.dropped,
             })),
-            upgradeAvailable: info.get(`${r.item_id}@${r.version}`)?.upgradeAvailable ?? null,
-            deploymentPending: info.get(`${r.item_id}@${r.version}`)?.deploymentPending ?? false,
+            upgradeAvailable: null,
+            deploymentPending: false,
         }));
     }
     /**
@@ -1131,9 +1505,9 @@ export class PluginInstaller {
      * extension among them needs `afterDisable` once committed). Used when an upgrade fails and when
      * an interrupted one is cleaned up.
      */
-    async undoUpgradeIn(t, orgId, actor, installId, steps, reason) {
+    async undoUpgradeIn(orgId, actor, installId, steps, reason) {
         const removed = [];
-        const dropRow = (kind, ref) => t
+        const dropRow = (kind, ref) => this.db
             .deleteFrom("plugin_install_components")
             .where("install_id", "=", installId)
             .where("kind", "=", kind)
@@ -1141,11 +1515,11 @@ export class PluginInstaller {
             .execute();
         for (const s of [...steps].reverse()) {
             if (s.op === "skill_version") {
-                await this.d.skills.revertVersionIn(t, orgId, s.ref, s.version, actor, reason);
+                await this.skills.revertVersionIn(orgId, s.ref, s.version, actor, reason);
                 continue;
             }
             if (s.op === "template_version") {
-                await revertTemplateVersionIn(t, orgId, s.ref, s.version);
+                await revertTemplateVersionIn(this.db, orgId, s.ref, s.version);
                 continue;
             }
             if (s.op === "recorded") {
@@ -1155,7 +1529,7 @@ export class PluginInstaller {
             if (s.kind === "plugin") {
                 const sub = { removed: [], kept: [] };
                 await dropRow(s.kind, s.ref);
-                const outcome = await this.uninstallIn(t, orgId, actor, s.ref, {
+                const outcome = await this.uninstallIn(orgId, actor, s.ref, {
                     report: sub,
                     removing: new Set([installId]),
                     from: installId,
@@ -1169,59 +1543,506 @@ export class PluginInstaller {
                 continue;
             }
             if (s.kind === "extension" &&
-                (await this.d.orgConfigs.enabledDependents(t, orgId, s.ref)).length > 0) {
+                (await this.orgConfigs.enabledDependents(orgId, s.ref)).length > 0) {
                 // Another enabled extension needs it: kept, and stays this install's component
                 continue;
             }
             const c = { kind: s.kind, ref: s.ref, created: true, skillVersion: null };
-            if (await this.removeComponent(t, orgId, actor, c, reason)) {
+            if (await this.removeComponent(orgId, actor, c, reason)) {
                 removed.push({ kind: s.kind, ref: s.ref });
             }
             await dropRow(s.kind, s.ref);
         }
         return removed;
     }
+    /**
+     * Installs the dependencies an installed plugin's version declares and the org lacks (rule 9),
+     * as the kernel (actor null): a platform update can add one. Each is recorded on the install
+     * as a `plugin` component (created when this installed it, so an uninstall takes it along). One
+     * that needs the org's input (connector templates) is left out and its name returned. A
+     * dependency already installed in the org is recorded as it is (created false).
+     */
+    async addMissingDependencies(orgId, installId) {
+        const row = await this.db
+            .selectFrom("plugin_installs as a")
+            .innerJoin("catalog_item_versions as v", (j) => j.onRef("v.item_id", "=", "a.item_id").onRef("v.version", "=", "a.version"))
+            .select(["a.item_id", "a.status", "v.manifest"])
+            .where("a.id", "=", installId)
+            .where("a.org_id", "=", orgId)
+            .executeTakeFirst();
+        if (row?.status !== "installed")
+            return [];
+        const record = async (c) => {
+            await this.db
+                .insertInto("plugin_install_components")
+                .values({
+                install_id: installId,
+                kind: c.kind,
+                ref: c.ref,
+                created: c.created,
+                skill_version: null,
+            })
+                .onConflict((oc) => oc.columns(["install_id", "kind", "ref"]).doNothing())
+                .execute();
+        };
+        const needsInput = [];
+        for (const dep of await resolveDependencies(this.db, row.manifest)) {
+            if ((await this.recordDependency(orgId, dep, record)) !== undefined)
+                continue;
+            let plan;
+            try {
+                plan = await this.plan(orgId, null, dep.itemId, dep.version, {}, "", row.item_id);
+            }
+            catch (e) {
+                if (e instanceof NeedsOrgInput) {
+                    needsInput.push(dep.name);
+                    continue;
+                }
+                throw e;
+            }
+            const child = await this.execute(orgId, null, plan, {}, {
+                actions: requiredActions(plan.manifest),
+                approvedBy: row.item_id,
+                parent: installId,
+                via: "scope",
+            });
+            await this.recordDependency(orgId, dep, record, child);
+        }
+        return needsInput;
+    }
+    /**
+     * The connector templates of an installed plugin that are on in the org (ruling P2-6) and have
+     * no live connector there: made from the platform template (`platform_template_id`) or recorded
+     * on the install (`template_id`). The org's plugin is `needs_config` while any is missing (ruling
+     * P2-10). Empty for a plugin not installed.
+     */
+    async missingConnectors(orgId, itemId) {
+        const a = await this.db
+            .selectFrom("plugin_installs as a")
+            .innerJoin("catalog_item_versions as v", (j) => j.onRef("v.item_id", "=", "a.item_id").onRef("v.version", "=", "a.version"))
+            .select(["a.id", "a.version", "v.manifest", "v.object_prefix", "v.files"])
+            .where("a.org_id", "=", orgId)
+            .where("a.item_id", "=", itemId)
+            .where("a.status", "=", "installed")
+            .executeTakeFirst();
+        if (!a)
+            return undefined;
+        if ((a.manifest.connectorTemplates ?? []).length === 0) {
+            return { installId: a.id, version: a.version, templates: [] };
+        }
+        const all = await readCatalogTemplates(this.storage, a);
+        const on = await connectorTemplatesOn(this.db, orgId, itemId, all.map((t) => t.id));
+        const made = new Set((await this.db
+            .selectFrom("connectors as c")
+            .innerJoin("platform_connector_templates as p", "p.id", "c.platform_template_id")
+            .select("p.template_id")
+            .where("c.org_id", "=", orgId)
+            .where("c.deleted_at", "is", null)
+            .where("p.catalog_item_id", "=", itemId)
+            .execute()).map((r) => r.template_id));
+        const recorded = await this.db
+            .selectFrom("plugin_install_components as l")
+            .innerJoin("connectors as c", (j) => j.on(sql `c.id::text`, "=", sql `l.ref`))
+            .select("l.template_id")
+            .where("l.install_id", "=", a.id)
+            .where("l.kind", "=", "connector")
+            .where("c.deleted_at", "is", null)
+            .execute();
+        for (const r of recorded)
+            if (r.template_id !== null)
+                made.add(r.template_id);
+        return {
+            installId: a.id,
+            version: a.version,
+            templates: all.filter((t) => on.has(t.id) && !made.has(t.id)),
+        };
+    }
+    /**
+     * Creates the connectors an installed plugin is missing (ruling P2-10, `POST …/catalog/:itemId/
+     * connectors`): `input.connectors` names some of {@link missingConnectors}' templates with the
+     * same input as an install (endpoint, credential or OAuth client); each is created as at install
+     * and recorded on the install. Returns the created connectors by template.
+     */
+    async configureConnectors(orgId, actor, itemId, input, opts = {}) {
+        if (!UUID_RE.test(itemId))
+            throw installNotFound();
+        const missing = await this.missingConnectors(orgId, itemId);
+        if (!missing)
+            throw installNotFound();
+        const keys = Object.keys(input.connectors ?? {});
+        if (keys.length === 0) {
+            throw new ApiError("validation_failed", "Request validation failed", [
+                { path: "connectors", message: "Give the input of at least one missing connector" },
+            ]);
+        }
+        for (const k of keys) {
+            if (!missing.templates.some((t) => t.id === k)) {
+                throw new ApiError("validation_failed", "Request validation failed", [
+                    {
+                        path: `connectors.${k}`,
+                        message: "No connector of this template is missing in this organization",
+                    },
+                ]);
+            }
+        }
+        const item = await this.db
+            .selectFrom("catalog_items")
+            .select("name")
+            .where("id", "=", itemId)
+            .executeTakeFirstOrThrow();
+        const plans = missing.templates
+            .filter((t) => keys.includes(t.id))
+            .map((t) => ({
+            id: t.id,
+            ci: this.planConnector(actor, { itemId, version: missing.version, name: item.name }, t, input, "", undefined),
+        }));
+        const out = [];
+        for (const p of plans) {
+            const r = await this.connectors.create(orgId, actor, p.ci, opts.actorTokenId);
+            await this.recordConnector(missing.installId, r.connector.id, p.id);
+            out.push({ templateId: p.id, connectorId: r.connector.id });
+        }
+        return out;
+    }
+    /** A configured connector's ledger row (its own transaction). */
+    async recordConnector(installId, ref, templateId) {
+        await this.db
+            .insertInto("plugin_install_components")
+            .values({
+            install_id: installId,
+            kind: "connector",
+            ref,
+            created: true,
+            skill_version: null,
+            template_id: templateId,
+        })
+            .onConflict((oc) => oc.columns(["install_id", "kind", "ref"]).doNothing())
+            .execute();
+    }
+    /**
+     * One more connector from a platform connector template on in the org (rulings P4-7, P4-T6-8;
+     * `POST …/connector-templates/:templateId/connectors`): `templateId` is the platform connector
+     * template's id; `config` is an install's connector input (endpoint, credential or OAuth client,
+     * slug) and `name` its name. Without a slug the name and slug default to the first free ones,
+     * chosen by the create under the org lock after its outbound calls
+     * (`CreateConnectorInput.slugDefault`); only a given slug answers 409 `connector.slug_taken`. Created as at install ({@link planConnector}, then
+     * `ConnectorsService.create`, which checks the slug before any outbound call and re-checks it,
+     * `connectors.manage`, the item and the template being on under the org lock), linked to the
+     * template, and recorded on the plugin's live install in the org when there is one. A template
+     * that is missing, deleted or not offered to the org -> 404 `component.not_found`; offered but
+     * off there (its plugin not installed, or switched off) -> 409 `component.off`; input errors ->
+     * 400 `validation_failed` at `config.<field>`.
+     */
+    async addTemplateConnector(orgId, actor, templateId, input, opts = {}) {
+        const notFound = () => new ApiError("component.not_found", "The connector template does not exist or is not available in this organization");
+        if (!UUID_RE.test(templateId))
+            throw notFound();
+        // read here to fail early, and again under the org lock by the create (`mustBeOn`)
+        const state = await connectorTemplateState(this.db, orgId, templateId);
+        if (state === "absent")
+            throw notFound();
+        if (state === "off") {
+            throw new ApiError("component.off", "This connector template is off in this organization; switch it (or its plugin) on first");
+        }
+        const row = await this.db
+            .selectFrom("platform_connector_templates as t")
+            .innerJoin("catalog_items as i", "i.id", "t.catalog_item_id")
+            .leftJoin("plugin_installs as a", (j) => j
+            .onRef("a.item_id", "=", "t.catalog_item_id")
+            .on("a.org_id", "=", orgId)
+            .on("a.status", "=", "installed"))
+            .select([
+            "t.template_id",
+            "t.catalog_item_id",
+            "t.file",
+            "i.name",
+            "i.latest_version",
+            "a.version",
+        ])
+            .where("t.id", "=", templateId)
+            .executeTakeFirstOrThrow();
+        const ct = { id: row.template_id, file: row.file };
+        const at = `connectors.${ct.id}`;
+        // the paths of an install's input and of the create, under `config` here (`name` stays)
+        const rebase = (e) => {
+            if (!(e instanceof ApiError) || e.code !== "validation_failed" || !e.details)
+                return e;
+            return new ApiError(e.code, e.message, e.details.map((d) => {
+                const path = d.path;
+                if (typeof path !== "string")
+                    return d;
+                const rest = path === at || path.startsWith(`${at}.`) ? path.slice(at.length + 1) : path;
+                if (!/^(slug|credential|endpoint|client)(\.|$)/.test(rest)) {
+                    return rest === path ? d : { ...d, path: rest };
+                }
+                return { ...d, path: `config.${rest}` };
+            }));
+        };
+        const display = ct.file.displayName?.en ?? ct.id;
+        // a slug given by the caller is theirs (409 when taken); otherwise the create picks the first
+        // free default under the org lock, after its outbound calls (no retry repeats them)
+        const defaulted = input.config.slug === undefined;
+        let ci;
+        try {
+            ci = this.planConnector(actor, { itemId: row.catalog_item_id, version: row.version ?? row.latest_version, name: row.name }, ct, {
+                connectors: {
+                    [ct.id]: { ...input.config, ...(input.name !== undefined && { name: input.name }) },
+                },
+            }, "", undefined);
+        }
+        catch (e) {
+            throw rebase(e);
+        }
+        ci = {
+            ...ci,
+            template: ci.template && { ...ci.template, mustBeOn: true },
+            ...(defaulted && {
+                slugDefault: { display, ...(input.name !== undefined && { name: input.name }) },
+            }),
+        };
+        try {
+            const r = await this.connectors.create(orgId, actor, ci, opts.actorTokenId);
+            await this.recordOnLiveInstall(orgId, row.catalog_item_id, r.connector.id, ct.id);
+            return r;
+        }
+        catch (e) {
+            throw rebase(e);
+        }
+    }
+    /**
+     * Records a connector made from a plugin's template on the org's live install of that plugin,
+     * when there is one, under the org lock (so an uninstall in between is seen).
+     */
+    async recordOnLiveInstall(orgId, itemId, connectorId, templateId) {
+        await this.orgLock.lock(orgId);
+        const install = await this.db
+            .selectFrom("plugin_installs")
+            .select("id")
+            .where("org_id", "=", orgId)
+            .where("item_id", "=", itemId)
+            .where("status", "=", "installed")
+            .executeTakeFirst();
+        if (!install)
+            return;
+        await this.db
+            .insertInto("plugin_install_components")
+            .values({
+            install_id: install.id,
+            kind: "connector",
+            ref: connectorId,
+            created: true,
+            skill_version: null,
+            template_id: templateId,
+        })
+            .onConflict((oc) => oc.columns(["install_id", "kind", "ref"]).doNothing())
+            .execute();
+    }
     /** The connector kinds an extension provides (the `connector@1` implementations loaded on this replica). */
     connectorKindsOf(plugin) {
-        return this.d.host
+        return this.registry
             .list("connector")
             .filter((e) => e.plugin === plugin)
             .map((e) => e.impl?.kind)
             .filter((k) => typeof k === "string");
     }
     /**
-     * The connectors, org skills and agent templates (`subagents.templates`) referenced by the
-     * current definitions of the org's live agents.
+     * The uninstall preview of an install (see {@link UninstallPreview}); the real uninstall may keep
+     * more (another install using a component, a connector still using an extension). The plugin's
+     * skills and agent templates are platform components (phase 2): the ones on in the org through
+     * the plugin (`follow`) go off with it, so the agents using them (by the platform id or an
+     * unpinned org copy linked to it) are listed, also for the dependency installs it created that
+     * go with it; ledger rows of earlier installs' org copies are not removed and not listed (an
+     * uninstall keeps legacy copies, like the platform update keeps copies of removed components).
      */
-    async agentRefs(t, orgId) {
-        const rows = await t
-            .selectFrom("agents as a")
-            .innerJoin("agent_versions as v", (j) => j.onRef("v.agent_id", "=", "a.id").onRef("v.version", "=", "a.current_version"))
-            .select("v.definition")
+    async previewUninstall(orgId, installId) {
+        if (!UUID_RE.test(installId))
+            throw installNotFound();
+        const t = this.db;
+        const row = await t
+            .selectFrom("plugin_installs as a")
+            .innerJoin("catalog_items as i", "i.id", "a.item_id")
+            .select(["a.id", "a.item_id", "a.version", "i.name"])
+            .where("a.id", "=", installId)
             .where("a.org_id", "=", orgId)
-            .where("a.deleted_at", "is", null)
+            .executeTakeFirst();
+        if (!row)
+            throw installNotFound();
+        const ledger = (id) => t
+            .selectFrom("plugin_install_components")
+            .select(["kind", "ref", "created"])
+            .where("install_id", "=", id)
+            .orderBy("kind")
+            .orderBy("ref")
             .execute();
-        const connectors = new Set();
-        const skills = new Set();
-        const templates = new Set();
-        for (const r of rows) {
-            const def = r.definition;
-            for (const ref of def?.tools ?? []) {
-                const n = normalizeToolRef(ref);
-                if (n?.kind === "connector" && typeof n.connectorId === "string") {
-                    connectors.add(n.connectorId);
+        const comps = (await ledger(installId)).filter((c) => c.kind !== "skill" && c.kind !== "agent_template");
+        const agents = await agentDefinitionRefs(t, orgId);
+        const used = new Map();
+        const use = (a, kind, ref) => {
+            const e = used.get(a.id) ?? { id: a.id, name: a.name, uses: [] };
+            if (!e.uses.some((u) => u.kind === kind && u.ref === ref))
+                e.uses.push({ kind, ref });
+            used.set(a.id, e);
+        };
+        const kept = [];
+        /**
+         * The agents using what goes with an install: connectors it created (they stay, kept for the
+         * agents) and the plugin's platform skills and agent templates on in the org through it
+         * (`follow`; by the platform id or an unpinned org copy linked to it). Dependency installs it
+         * created go with it unless their own scope wants them (Task 7: their components count too).
+         */
+        const visit = async (itemId, rows, top, seen) => {
+            for (const c of rows) {
+                if (!c.created) {
+                    if (top)
+                        kept.push({ kind: c.kind, ref: c.ref, reason: "pre_existing" });
+                    continue;
+                }
+                if (c.kind === "plugin") {
+                    const dep = await t
+                        .selectFrom("plugin_installs")
+                        .select("item_id")
+                        .where("id", "=", c.ref)
+                        .where("org_id", "=", orgId)
+                        .executeTakeFirst();
+                    if (!dep)
+                        continue;
+                    if (await wantedByScope(t, orgId, dep.item_id)) {
+                        if (top)
+                            kept.push({ kind: c.kind, ref: c.ref, reason: "wanted_by_scope" });
+                        continue;
+                    }
+                    if (seen.has(c.ref))
+                        continue;
+                    seen.add(c.ref);
+                    const sub = (await ledger(c.ref)).filter((x) => x.kind !== "skill" && x.kind !== "agent_template");
+                    await visit(dep.item_id, sub, false, seen);
+                    continue;
+                }
+                if (c.kind !== "connector")
+                    continue;
+                const users = agents.filter((a) => a.connectors.has(c.ref));
+                if (users.length === 0)
+                    continue;
+                if (top)
+                    kept.push({ kind: c.kind, ref: c.ref, reason: "used_by_agents" });
+                for (const a of users)
+                    use(a, c.kind, c.ref);
+            }
+            for (const kind of ["skill", "agent_template"]) {
+                const platform = await loadComponents(t, kind, { itemId });
+                const st = await loadScopeState(t, kind, platform);
+                const off = platform.filter((c) => c.scopeMode === "follow" &&
+                    componentOn(c, pluginFactsOf(st, c.itemId, orgId), listedIn(st, c.id, orgId), switchOf(st, c.id, orgId)));
+                const refs = await referenceIds(t, orgId, kind, off.map((c) => c.id));
+                for (const a of agents) {
+                    for (const ref of kind === "skill" ? a.skills : a.templates) {
+                        if (refs.has(ref))
+                            use(a, kind, ref);
+                    }
+                }
+            }
+            const themes = await loadComponents(t, "theme", { itemId });
+            const tst = await loadScopeState(t, "theme", themes);
+            for (const c of themes) {
+                if (c.scopeMode === "follow" &&
+                    componentOn(c, pluginFactsOf(tst, c.itemId, orgId), listedIn(tst, c.id, orgId), switchOf(tst, c.id, orgId))) {
+                    lostThemes.set(c.id, new Set([orgId]));
                 }
             }
-            for (const s of def?.skills?.orgSkills ?? [])
-                if (typeof s === "string")
-                    skills.add(s);
-            for (const x of def?.subagents?.templates ?? [])
-                if (typeof x === "string")
-                    templates.add(x);
-        }
-        return { connectors, skills, templates };
+        };
+        /** The themes that go off in the org with the install (and the dependencies it removes). */
+        const lostThemes = new Map();
+        await visit(row.item_id, comps, true, new Set([installId]));
+        const themes = await themesPreview(t, lostThemes);
+        return {
+            installId,
+            name: row.name,
+            version: row.version,
+            components: comps.map((c) => ({ kind: c.kind, ref: c.ref, created: c.created })),
+            kept,
+            agents: [...used.values()]
+                .map((a) => ({ ...a, uses: a.uses.sort((x, y) => x.ref.localeCompare(y.ref)) }))
+                .sort((x, y) => x.id.localeCompare(y.id)),
+            ...(themes !== undefined && { themes }),
+        };
     }
-}
+    /**
+     * The connectors, skills (selected, pinned, or in an inline sub-agent template) and agent
+     * templates (`subagents.templates`) referenced by the current definitions of the org's live
+     * agents.
+     */
+    async agentRefs(orgId) {
+        const out = { connectors: new Set(), skills: new Set(), templates: new Set() };
+        for (const a of await agentDefinitionRefs(this.db, orgId)) {
+            for (const x of a.connectors)
+                out.connectors.add(x);
+            for (const x of a.skills)
+                out.skills.add(x);
+            for (const x of a.templates)
+                out.templates.add(x);
+        }
+        return out;
+    }
+};
+__decorate([
+    Transactional({ propagation: "requires_new" })
+], PluginInstaller.prototype, "recordDependency", null);
+__decorate([
+    Transactional()
+], PluginInstaller.prototype, "enableExtension", null);
+__decorate([
+    Transactional({ propagation: "requires_new" })
+], PluginInstaller.prototype, "createInstallRow", null);
+__decorate([
+    Transactional({ propagation: "requires_new" })
+], PluginInstaller.prototype, "markInstalled", null);
+__decorate([
+    Transactional({ propagation: "requires_new" })
+], PluginInstaller.prototype, "markFailed", null);
+__decorate([
+    Transactional({ propagation: "requires_new" })
+], PluginInstaller.prototype, "rollbackOne", null);
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], PluginInstaller.prototype, "removeComponent", null);
+__decorate([
+    Transactional()
+], PluginInstaller.prototype, "writeUninstall", null);
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], PluginInstaller.prototype, "heir", null);
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], PluginInstaller.prototype, "handOver", null);
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], PluginInstaller.prototype, "uninstallIn", null);
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], PluginInstaller.prototype, "decideRemovalIn", null);
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], PluginInstaller.prototype, "undoUpgradeIn", null);
+__decorate([
+    Transactional({ propagation: "requires_new" })
+], PluginInstaller.prototype, "recordConnector", null);
+__decorate([
+    Transactional()
+], PluginInstaller.prototype, "recordOnLiveInstall", null);
+PluginInstaller = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(OrgLock)),
+    __param(2, Inject(StorageService)),
+    __param(3, Inject(ExtensionRegistry)),
+    __param(4, Inject(SkillsService)),
+    __param(5, Inject(OrgExtensionConfigs)),
+    __param(6, Inject(KernelConfigService)),
+    __param(7, Inject(ConnectorsService)),
+    __param(8, Inject(KERNEL_LOGGER)),
+    __param(9, Inject(TransactionHost))
+], PluginInstaller);
+export { PluginInstaller };
 /**
  * The skill names of a catalog version, read from each skill's SKILL.md in storage (the names are
  * not in plugin.json). Used by install planning and the upgrade preview.
@@ -1331,3 +2152,36 @@ function orderByRequires(set) {
     }
     return placed;
 }
+/**
+ * Whether org row `id` (a skill or an agent template of the org) is linked without a pin to a live
+ * platform row the org promoted when sharing it (ruling P3-3): owned by the org and from no plugin
+ * (`catalog_item_id` null). A component of the org's own uploaded plugin is a plugin's, so its
+ * install copies are removed and reverted as any plugin's.
+ */
+async function promotedOrgRow(db, orgId, kind, id) {
+    const row = kind === "skill"
+        ? await db
+            .selectFrom("skills as s")
+            .innerJoin("platform_skills as p", "p.id", "s.platform_skill_id")
+            .select("s.id")
+            .where("s.id", "=", id)
+            .where("s.org_id", "=", orgId)
+            .where("s.pinned_version", "is", null)
+            .where("p.owner_org_id", "=", orgId)
+            // promoted, not an org plugin's component (which has its plugin, P3-2)
+            .where("p.catalog_item_id", "is", null)
+            .where("p.deleted_at", "is", null)
+            .executeTakeFirst()
+        : await db
+            .selectFrom("agent_templates as a")
+            .innerJoin("platform_agent_templates as p", "p.id", "a.platform_template_id")
+            .select("a.id")
+            .where("a.id", "=", id)
+            .where("a.org_id", "=", orgId)
+            .where("a.pinned_version", "is", null)
+            .where("p.owner_org_id", "=", orgId)
+            .where("p.catalog_item_id", "is", null)
+            .where("p.deleted_at", "is", null)
+            .executeTakeFirst();
+    return row !== undefined;
+}