@capybara-hq/kernel 0.1.0-rc.2 → 0.1.0-rc.21

package/dist/catalog/plugin-upgrade.js

@@ -7,37 +7,63 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
-import { createHash, randomUUID } from "node:crypto";
+// The platform plugin update (plugin and component management spec §7, plugin scope phase 2,
+// Task 7): a platform plugin has one version for the deployment, so an update is previewed and
+// confirmed once by the super admin, per component. The per-org upgrade routes are retired (ruling
+// F2).
+import { createHash } from "node:crypto";
+import { SDK_VERSION } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable } from "@nestjs/common";
 import { sql } from "kysely";
-import { putTemplateVersionIn } from "../agents/templates.js";
 import { ApiError } from "../errors.js";
-import { isExtensionEnabled } from "../extensions/enabled.js";
-import { OrgExtensionConfigs } from "../extensions/org-config.js";
+import { ExtensionAdminOps } from "../extensions/admin-ops.js";
+import { ExtensionBlobs } from "../extensions/blobs.js";
+import { permissionSetOfPackage, readExtensionPackage } from "../extensions/package.js";
+import { blockingKeys, diffPermissions } from "../extensions/permission-set.js";
+import { PluginGuides } from "../extensions/plugin-guides.js";
 import { ExtensionRegistry } from "../extensions/registry.js";
 import { audit } from "../identity/audit.js";
+import { SuperAdminLock } from "../identity/super-admin.js";
+import { addOrgNotice, itemDisplayName, notifySharedUpdate } from "../inbox/org-notices.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 { LockService } from "../infra/lock/lock.service.js";
 import { KERNEL_LOGGER } from "../infra/tokens.js";
 import { OrgLock } from "../orgs/org-lock.js";
 import { packagePath } from "../packages/tgz.js";
-import { SkillsService, skillConflictError } from "../skills/skills.service.js";
 import { StorageService } from "../storage/storage.service.js";
+import { assertNotPlatformDefault, pickedByIn, themesPreview, } from "../themes/theme-usage.js";
+import { canonicalJson } from "../tools/canonical-json.js";
 import { ConnectorsService } from "../tools/connectors.service.js";
-import { canonicalJson } from "../tools/registry.js";
-import { getPath, lockOrgForActions, orgTemplateView, readCatalogAgentTemplates, readCatalogFiles, readCatalogTemplates, requiredActions, setPath, skillOf, templatePluginProblem, } from "./catalog-content.js";
-import { catalogSkillNames, InstallFailure, journalEntries, missingTemplateInput, PluginInstaller, planActions, planSkillConflicts, resolveDependencies, under, } from "./plugin-install.js";
-import { assertItemInstallable, CatalogRequestsService } from "./requests.service.js";
-import { deployedExtension, deploymentTarget } from "./upgrade-targets.js";
-import { satisfiesRange } from "./versions.js";
+import { dirDigest, getPath, readCatalogAgentTemplates, readCatalogTemplates, readCatalogThemes, setPath, skillFilesDigest, templatePluginProblem, themeAssetsDigest, } from "./catalog-content.js";
+import { markVersionApplied, versionUsable } from "./catalog-items.js";
+import { agentsUsing, clashingOrgSkills, clashingPlatformSkills, componentOn, connectorsMadeFrom, connectorTemplatesOn, listedIn, loadComponents, loadScopeState, pluginFactsOf, switchOf, themeIdClashes, } from "./component-state.js";
+import { CatalogItemLock } from "./locks.js";
+import { itemPendingError, itemRemovedError } from "./ownership.js";
+import { PlanStale, PlatformComponents } from "./platform-components.js";
+import { catalogSkillNames, PluginInstaller } from "./plugin-install.js";
+import { PluginScopeSync } from "./scope-sync.js";
+import { compareVersions, satisfiesRange } from "./versions.js";
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-const installNotFound = () => new ApiError("plugin.install_not_found", "Plugin install not found");
-const inProgress = () => new ApiError("plugin.install_in_progress", "This plugin install is being installed, upgraded or uninstalled; try again when it finishes");
-const stale = () => new ApiError("plugin.upgrade_stale", "The upgrade preview is out of date (the catalog version or this install's components changed); preview the upgrade again");
-const targetInvalid = (message, details) => new ApiError("plugin.upgrade_target_invalid", message, details);
-const fail = (path, message) => new ApiError("validation_failed", "Request validation failed", [{ path, message }]);
 const sha256 = (s) => createHash("sha256").update(s).digest("hex");
+const itemNotFound = () => new ApiError("catalog.item_not_found", "Catalog item not found");
+const stale = () => new ApiError("plugin.upgrade_stale", "The update preview is out of date (the catalog version, the platform components, a pin or a connector changed); preview the update again");
+/** The pending version a super admin confirms was replaced by another upload (P3-11). */
+const pendingStale = (name) => new ApiError("extension.approval_stale", `The pending upload of ${name} changed since it was reviewed; review it again`);
+const targetInvalid = (message, details) => new ApiError("plugin.upgrade_target_invalid", message, details);
+/** A version an org uploaded that was never applied or confirmed, or was rejected (P3-37, P3-52). */
+const notApplied = (name, version) => targetInvalid(`Version ${version} of plugin ${name} was uploaded by an organization and never applied or confirmed (or was rejected); the generic update cannot apply it`, [{ reason: "org_version_not_applied", version }]);
+const KIND_ORDER = {
+    skill: 0,
+    agent_template: 1,
+    connector_template: 2,
+    theme: 3,
+};
+/** How long one update holds its item (renewed while it runs). */
+const UPDATE_LOCK_TTL_MS = 60_000;
 /**
  * What a credential of `auth` looks like: two auths with the same key take the same stored
  * credential (static: the type family, ownership and header names; OAuth: any change re-enters).
@@ -58,725 +84,680 @@ function credentialKey(auth) {
     }
 }
 /** The digest of all files of a catalog version. */
-const filesDigest = (row) => sha256(row.files
-    .map((f) => `${f.path}\0${f.sha256}\n`)
-    .sort()
-    .join(""));
-/** The digest of the files under `dir/` of a catalog version (paths relative to it). */
-function dirDigest(row, dir) {
-    const prefix = `${dir}/`;
-    return sha256(row.files
-        .filter((f) => f.path.startsWith(prefix))
-        .map((f) => `${f.path.slice(prefix.length)}\0${f.sha256}\n`)
-        .sort()
-        .join(""));
-}
+const filesDigest = (row) => skillFilesDigest(row.files.map((f) => ({ path: f.path, sha256: f.sha256 })));
 /**
- * Org in-place upgrade (and, for declarative plugins, rollback) of an installed plugin (package
- * ecosystem spec §10, Decisions 9–11):
- * - **preview** diffs the installed and the target version per component (extension, dependency
- *   plugins, skills by name, connector templates by id) and returns the inputs needed and a
- *   `diffHash`; the same checks as an install run first (dependencies resolve, extension and
- *   template connectors deployed, skill conflicts -> `plugin.skill_conflict`), plus the target
- *   rules (`plugin.upgrade_target_invalid`): an extension-bearing plugin can move only to the
- *   catalog version carrying the deployment's extension, and installs depending on this plugin must
- *   still accept the target;
- * - **upgrade** re-checks the `diffHash` (`plugin.upgrade_stale`), sets the install `upgrading`
- *   under the org lock (another upgrade or an uninstall -> `plugin.install_in_progress`), then:
- *   added dependencies (installed by the install flow), the added extension (enabled), added and
- *   changed skills (a new version of the same skill; agents keep selecting it by id), added
- *   connectors (created from the template), and in one final transaction the changed connectors
- *   (template-owned fields only, `applyTemplateIn`), the removals by the uninstall rules, the new
- *   version and the audit `plugin.org_upgraded`. Each step is journaled in
- *   `plugin_installs.upgrade`; on failure the journal is undone (created components removed, skill
- *   versions reverted; changed connectors were never committed), the install stays `installed` at
- *   the old version with `error = { step, code }`, audit `plugin.org_upgrade_failed`, 502
- *   `plugin.upgrade_failed`. An upgrade interrupted for longer than `catalog.staleInstallMinutes`
- *   is undone by the next preview, upgrade or uninstall.
- * Approval follows the item's policy (the org catalog service creates the request). No in-process
- * state.
+ * The platform plugin update (spec §7; ruling F2 retires the per-org upgrades):
+ * - **preview** diffs the platform's current components of the plugin (the version recorded in
+ *   `catalog_items.platform_synced_version`, components updated on their own included) against a
+ *   catalog version: each skill (by name, by its files' digest), agent template (by name, canonical
+ *   definition) and connector template (by id, canonical file) is `added`, `removed`, `same`, or
+ *   `upgrade` / `downgrade` (the target's direction from the component's catalog version). It marks
+ *   components updated on their own, components with their own scope and the orgs whose linked
+ *   copy is pinned; lists removed components agents still use (they stay, spec §7.3), the org
+ *   connectors made from changed templates (all orgs, ruling E2; `credentialsReset` when the
+ *   credential shape changed), the templates it turns on that will need an org's input (added, or
+ *   no longer shipped off) and those it turns off (now shipped off, on only by default), the
+ *   deployment's extension move, and a `diffHash`. Refused: same version, a disabled or deleted
+ *   item, a target without the extension the deployment runs for it or moving a config-declared
+ *   one, a template moving to another connector, a plugin another platform plugin depends on
+ *   outside its range, and an added skill whose name is taken where the plugin is on (rule 10).
+ * - **update** runs under a Redis lock per item (another update -> `plugin.install_in_progress`):
+ *   the extension first (`ExtensionAdminOps.install`, enabled when the update installs it; added
+ *   permissions wait for the admin's approval as for any extension upgrade), then one transaction
+ *   under the item name's lock that recomputes the diff (`plugin.upgrade_stale` on a difference)
+ *   and writes the platform versions (`PlatformComponents.syncFromVersion`, which records
+ *   `platform_synced_version`), the pinned suggestions of unchanged skills, the removals (a
+ *   component no agent uses is soft-deleted, so unpinned linked copies go with it; pinned copies
+ *   keep their own version; a removed connector template leaves its connectors as the orgs' own),
+ *   clears the pins of linked copies, fans changed templates out to every connector made from them
+ *   (`applyTemplateIn`, under each org's row lock, credentials cleared only for a changed
+ *   credential shape), moves every org install to the version and audits
+ *   `plugin.platform_updated`; the scope sync of the item and its dependencies is enqueued after
+ *   the commit (orgs get new dependencies by rule 9). A failure rolls the transaction back and
+ *   puts the extension back where it was (audit `plugin.platform_update_failed`, 502
+ *   `plugin.upgrade_failed`); files copied to `deployment/platform/` stay unreferenced.
+ * Storage is never read or written inside the transaction: the target's contents (and the
+ * extension package, for `needsApproval`) are read and the platform files copied
+ * (`PlatformComponents.prepareSync`) after the Redis lock is taken and before the transaction,
+ * which reuses them and writes rows only (`applySyncIn`). The confirm-time diff treats the
+ * extension this update moved as expected (the install record must point at that package).
+ * Recovery: a process that dies between the extension step and the transaction leaves the
+ * deployment on the target's extension with the platform components unchanged; a new preview
+ * then shows the extension unchanged (`extension: null`) and the components still to move, and
+ * confirming it completes the update (or an update back to the old version moves it back).
+ * No in-process state.
  */
-let PluginUpgrader = class PluginUpgrader {
-    installer;
+let PlatformPluginUpdater = class PlatformPluginUpdater {
     kdb;
+    txHost;
+    adminLock;
+    itemLock;
     orgLock;
+    locks;
     storage;
     registry;
-    skills;
-    orgConfigs;
-    requests;
+    ops;
+    blobs;
+    config;
+    platform;
+    installer;
     connectors;
+    sync;
     log;
-    txHost;
-    constructor(
-    /** Planning, installs, the ledger and the uninstall rules are the installer's. */
-    installer, kdb, 
-    /** The org row lock (orgs/org-lock.ts): joins the caller's transaction. */
-    orgLock, storage, registry, skills, orgConfigs, requests, 
-    /** Org connectors: installs create, upgrade and remove them. */
-    connectors, log, txHost) {
-        this.installer = installer;
+    guides;
+    constructor(kdb, txHost, adminLock, itemLock, orgLock, locks, storage, registry, ops, 
+    /** Reads the target's extension package (its permissions, for `needsApproval`). */
+    blobs, config, platform, 
+    /** Template dependencies (the deployed connector kinds). */
+    installer, connectors, sync, log, 
+    /** The connector template guides an update changes (the preview's `guideChanges`). */
+    guides) {
         this.kdb = kdb;
+        this.txHost = txHost;
+        this.adminLock = adminLock;
+        this.itemLock = itemLock;
         this.orgLock = orgLock;
+        this.locks = locks;
         this.storage = storage;
         this.registry = registry;
-        this.skills = skills;
-        this.orgConfigs = orgConfigs;
-        this.requests = requests;
+        this.ops = ops;
+        this.blobs = blobs;
+        this.config = config;
+        this.platform = platform;
+        this.installer = installer;
         this.connectors = connectors;
+        this.sync = sync;
         this.log = log;
-        this.txHost = txHost;
+        this.guides = guides;
     }
-    /** The kernel-schema handle of the current context (the transaction, else the pool). */
     get db() {
         return this.kdb.db;
     }
-    /** The upgrade preview (see the class comment). */
-    async preview(orgId, actor, installId, version) {
-        await this.recoverInterrupted(orgId, actor, installId);
-        const diff = await this.diff(orgId, actor, installId, version, null);
-        await this.authorizeActions(orgId, actor, diff.actions);
+    /** The update preview (see the class comment); writes nothing. */
+    async preview(itemId, version) {
+        return this.withGuideChanges(await this.diff(itemId, version));
+    }
+    /** The preview of a diff with the template guides it changes. */
+    async withGuideChanges(d) {
         return {
-            from: diff.from.version,
-            to: diff.to.version,
-            diffHash: diff.diffHash,
-            components: diff.components,
-            inputs: diff.inputs,
-            templates: diff.templates.flatMap((c) => c.target !== undefined &&
-                (diff.inputs.connectors.includes(c.id) || diff.inputs.credentialsChanged.includes(c.id))
-                ? [orgTemplateView(c.id, c.target)]
-                : []),
+            ...previewOf(d),
+            guideChanges: await this.guides.templateGuideChanges(d.itemId, d.from, d.to),
         };
     }
-    /** Re-checks the actor's org actions under the org row lock (a transaction of its own). */
-    async authorizeActions(orgId, actor, actions) {
-        await lockOrgForActions(this.orgLock, orgId, actor, actions);
-    }
     /**
-     * The checks of {@link upgrade} before an approval request (the org catalog service creates one
-     * for a needs_approval item without a grant): the diff with the input, the `diffHash`. Returns
-     * the item and the org actions the upgrade needs.
+     * The update preview of a new version of an org's own plugin (ruling P3-12): the item must be
+     * owned by `orgId` (else 404, as for any item the org cannot see), the target carries no
+     * extension (an extension-bearing version waits for the super admin, plan Task 6), and a target
+     * dropping the deployment's extension is allowed (P3-12'). `staged` is the target read from the
+     * org's staging (pre-flight F3); without it the imported version `version` is read. The route
+     * authorizes the org admin; writes nothing.
      */
-    async check(orgId, actor, installId, input) {
-        await this.recoverInterrupted(orgId, actor, installId);
-        const diff = await this.diff(orgId, actor, installId, input.version, input);
-        if (diff.diffHash !== input.diffHash)
-            throw stale();
-        return { itemId: diff.itemId, name: diff.name, actions: diff.actions, diff };
+    async previewForOwner(orgId, itemId, version, staged) {
+        // An internal invariant, not reachable from input: the only caller (OrgPluginUploads) passes
+        // the staged target together with its own version (PluginImport.stagedTarget)
+        if (staged !== undefined && staged.version !== version) {
+            throw new Error(`internal: previewForOwner got the staged target of version ${staged.version} for version ${version}`);
+        }
+        const preview = await this.withGuideChanges(await this.diff(itemId, version, {
+            owner: { orgId },
+            ...(staged !== undefined && { target: staged }),
+        }));
+        // The owner sees the names of the orgs whose default a removed theme is (named like the other
+        // orgs the preview mentions, P3-14 / P3-19), but people only of its own org: other orgs'
+        // member counts were never disclosed to it. Display only: `diffHash` covers the full preview.
+        const themes = preview.themes === undefined
+            ? undefined
+            : await Promise.all(preview.themes.map(async (t) => ({
+                ...t,
+                pickedBy: await pickedByIn(this.db, t.id, new Set([orgId])),
+            })));
+        const owned = { ...preview, ...(themes !== undefined && { themes }) };
+        return { ...owned, orgNames: await this.orgNamesOf(owned) };
     }
     /**
-     * Runs an upgrade (see the class comment); returns the install view. `checked` is the diff
-     * {@link check} computed for the same input (re-verified under the org lock: the install's
-     * version and ledger must be unchanged), otherwise it is computed here.
+     * Locks, in sorted order and before the item (ruling P3-50), every live org the update may
+     * write in: the orgs with connectors made from the plugin's connector templates and the item's
+     * owner org. `acting`: the owner org an owner update acts for, locked with its admin re-checked
+     * (`catalog.upload`; deleted -> 404 `org.not_found`). Returns the live orgs locked; another
+     * deleted one is skipped.
      */
-    async upgrade(orgId, actor, installId, input, opts = {}, checked) {
-        let diff;
-        if (checked !== undefined &&
-            checked.installId === installId &&
-            checked.to.version === input.version &&
-            checked.diffHash === input.diffHash) {
-            diff = checked;
-        }
-        else {
-            await this.recoverInterrupted(orgId, actor, installId);
-            diff = await this.diff(orgId, actor, installId, input.version, input);
-            if (diff.diffHash !== input.diffHash)
-                throw stale();
-        }
-        const { itemId } = diff;
-        const upgradeId = randomUUID();
-        // Start: the install `upgrading`, under the org lock (one upgrade or uninstall at a time)
-        await this.start(orgId, actor, installId, diff, upgradeId);
-        const done = [];
-        /** The step whose journal write found the journal gone (cleaned up as interrupted meanwhile). */
-        let unjournaled;
-        // Appends a step to the journal in the transaction of the context (the journal gone: the
-        // upgrade was cleaned up as interrupted)
-        const journal = async (s) => {
-            done.push(s);
-            unjournaled = s;
-            const r = await this.db
-                .updateTable("plugin_installs")
-                .set({
-                upgrade: sql `jsonb_set(upgrade, '{done}', (upgrade->'done') || ${JSON.stringify([s])}::jsonb)`,
-            })
-                .where("id", "=", installId)
-                .where(sql `upgrade->>'id'`, "=", upgradeId)
-                .executeTakeFirst();
-            if (r.numUpdatedRows === 0n)
-                throw cleanedUp();
-            unjournaled = undefined;
-        };
-        // Records a component in the ledger and the journal, in the transaction of the context
-        const record = (c) => this.recordIn(installId, journal, c);
-        let step = "dependencies";
-        const disabled = [];
-        try {
-            for (const dep of diff.dependencies.filter((x) => x.change === "added")) {
-                const resolved = dep.resolved;
-                const rec = (c) => record(c);
-                if ((await this.installer.recordDependency(orgId, resolved, rec)) !== undefined)
-                    continue;
-                if (!dep.plan) {
-                    throw new ApiError("catalog.dependency_unresolved", `Dependency ${dep.name}@${resolved.range} cannot be resolved: its install in this organization was removed meanwhile; try again`, [{ dependency: dep.name, range: resolved.range }]);
-                }
-                let child;
-                try {
-                    child = await this.installer.execute(orgId, actor, dep.plan, opts, {
-                        actions: requiredActions(dep.plan.manifest),
-                        approvedBy: itemId,
-                        parent: installId,
-                    });
-                }
-                catch (e) {
-                    if (e instanceof InstallFailure) {
-                        throw new InstallFailure(e.step, e.cause, [dep.name, ...e.dependency], e.rolledBack);
-                    }
-                    if (e instanceof ApiError &&
-                        e.code === "plugin.already_installed" &&
-                        (await this.installer.recordDependency(orgId, resolved, rec)) !== undefined) {
-                        continue;
-                    }
-                    throw new InstallFailure("dependencies", e, [dep.name], true);
-                }
-                await this.installer.recordDependency(orgId, resolved, rec, child);
-            }
-            step = "extension";
-            if (diff.extension?.change === "added") {
-                await this.installer.enableExtension(orgId, diff.extension.name, {
-                    enabled: true,
-                    ...(input.extensionConfig !== undefined && { config: input.extensionConfig }),
-                }, actor, opts.actorTokenId, { viaItem: itemId }, record);
-            }
-            step = "skills";
-            for (const s of diff.skills) {
-                if (s.change !== "added" && s.change !== "changed")
-                    continue;
-                const files = await readCatalogFiles(this.storage, diff.to.object_prefix, diff.to.files, s.dir);
-                const r = await this.skills.createVersionFromFiles(orgId, actor, { ...skillOf(files), files }, {
-                    catalog: {
-                        itemId,
-                        version: diff.to.version,
-                        format: diff.to.source_format,
-                        suggestPinned: s.suggestPinned === true,
-                    },
-                    ...opts,
-                });
-                await this.journalSkill(r, record, journal);
-            }
-            step = "agent_templates";
-            for (const a of diff.agentTemplates) {
-                if (a.change !== "added" && a.change !== "changed")
-                    continue;
-                await this.upgradeAgentTemplate(orgId, diff, a.template, record, journal);
-            }
-            step = "connectors";
-            for (const [templateId, ci] of diff.creates) {
-                const r = await this.connectors.create(orgId, actor, ci, opts.actorTokenId);
-                await this.recordStep(installId, journal, {
-                    kind: "connector",
-                    ref: r.connector.id,
-                    created: true,
-                    skillVersion: null,
-                    templateId,
-                });
+    async lockUpdateOrgs(itemId, acting) {
+        const item = await this.db
+            .selectFrom("catalog_items")
+            .select("owner_org_id")
+            .where("id", "=", itemId)
+            .executeTakeFirst();
+        const made = await this.db
+            .selectFrom("connectors as c")
+            .innerJoin("platform_connector_templates as t", "t.id", "c.platform_template_id")
+            .select("c.org_id")
+            .distinct()
+            .where("t.catalog_item_id", "=", itemId)
+            .where("c.deleted_at", "is", null)
+            .execute();
+        const ids = new Set(made.map((r) => r.org_id));
+        if (item?.owner_org_id)
+            ids.add(item.owner_org_id);
+        if (acting !== undefined)
+            ids.add(acting.orgId);
+        const live = new Set();
+        for (const orgId of [...ids].sort()) {
+            if (orgId === acting?.orgId) {
+                await this.orgLock.lockAndAuthorize(orgId, acting.actor, "catalog.upload");
+                live.add(orgId);
             }
-            const prepared = [];
-            for (const tpl of diff.templates) {
-                const update = diff.updates.get(tpl.id);
-                if (!update || !tpl.connector)
-                    continue;
-                try {
-                    prepared.push({
-                        connectorId: tpl.connector.id,
-                        p: await this.connectors.prepareTemplateUpdate(actor, tpl.connector.connector, update),
-                    });
-                }
-                catch (e) {
-                    throw under(e, `connectors.${tpl.id}`);
-                }
+            else if (await this.orgLock.tryLock(orgId)) {
+                live.add(orgId);
             }
-            // Finish, in one transaction: changed connectors, removals, the version switch
-            await this.finish(orgId, actor, installId, upgradeId, diff, prepared, disabled, opts, () => {
-                step = "finish";
-            });
-        }
-        catch (e) {
-            throw await this.failed(orgId, actor, installId, upgradeId, diff, { done, unjournaled }, step, e, opts);
         }
-        for (const p of disabled)
-            await this.orgConfigs.afterDisable(orgId, p);
-        const [view] = await this.installer.list(orgId, installId);
-        if (!view)
-            throw installNotFound();
-        return view;
+        return live;
+    }
+    /** The names of the orgs a preview mentions, by id (an owner's preview, see `orgNames`). */
+    async orgNamesOf(p) {
+        const ids = new Set([
+            ...(p.extension?.orgs ?? []),
+            ...p.connectorOrgs.map((c) => c.orgId),
+            ...p.components.flatMap((c) => [...c.pinnedOrgs, ...(c.kept ?? []).map((k) => k.orgId)]),
+            ...(p.themes ?? []).flatMap((t) => t.orgDefaults.map((o) => o.orgId)),
+        ]);
+        if (ids.size === 0)
+            return {};
+        const rows = await this.db
+            .selectFrom("orgs")
+            .select(["id", "name"])
+            .where("id", "in", [...ids])
+            .where("deleted_at", "is", null)
+            .execute();
+        return Object.fromEntries(rows.map((r) => [r.id, r.name]));
     }
     /**
-     * Undoes a failed upgrade (its journal, in one transaction): the install back `installed` at the
-     * old version with `error = { step, code }`, audit `plugin.org_upgrade_failed`. When the journal
-     * is no longer this upgrade's (another request cleaned it up as interrupted and undid what it
-     * journaled), only the step whose journal write failed is undone and the install row is left as
-     * the cleanup set it. Returns the error to throw: 502 `plugin.upgrade_failed` (a dependency
-     * another install is still installing: its 409 as it is).
+     * Applies a new version of an org's own plugin for its owner (ruling P3-12, see
+     * {@link previewForOwner}): the actor must be an admin of the owner org (`catalog.upload`,
+     * re-checked under the org row lock in the transaction), then the platform update as
+     * {@link update} does, also removing the extension when the target drops it. In the update's
+     * transaction the orgs using the shared plugin are told (`shared_item_updated`, one notice per
+     * plugin) and a pending version is cleared (pre-flight F7: the new version replaces it).
      */
-    async failed(orgId, actor, installId, upgradeId, diff, steps, step, e, opts) {
-        const failure = e instanceof InstallFailure ? e : undefined;
-        const cause = failure ? failure.cause : e;
-        const code = cause instanceof ApiError ? cause.code : "internal";
-        const at = failure ? failure.step : step;
-        let rolledBack = failure?.rolledBack ?? true;
-        try {
-            const removed = await this.undoFailed(orgId, actor, installId, upgradeId, diff, steps, { at, code }, opts);
-            for (const r of removed) {
-                if (r.kind === "extension")
-                    await this.orgConfigs.afterDisable(orgId, r.ref);
-            }
+    async updateAsOwner(orgId, actor, itemId, version, diffHash, opts = {}) {
+        if (!UUID_RE.test(itemId))
+            throw itemNotFound();
+        await this.authorizeOwner(orgId, actor);
+        return this.locked(itemId, () => this.updateLocked(actor, itemId, { version, diffHash }, opts, { orgId }));
+    }
+    /** The actor is an admin of the owner org (a read of the membership under the org row lock). */
+    async authorizeOwner(orgId, actor) {
+        await this.orgLock.lockAndAuthorize(orgId, actor, "catalog.upload");
+    }
+    /** Runs `f` holding the item's update lock (another update -> `plugin.install_in_progress`). */
+    async locked(itemId, f) {
+        const handle = await this.locks.acquire(`plugin-update-${itemId}`, {
+            ttlMs: UPDATE_LOCK_TTL_MS,
+        });
+        if (!handle) {
+            throw new ApiError("plugin.install_in_progress", "This plugin is being updated; try again when that update finishes");
         }
-        catch (u) {
-            // Left `upgrading` with its journal: undone once it is older than catalog.staleInstallMinutes
-            rolledBack = false;
-            this.log.warn("plugin upgrade rollback failed", {
-                orgId,
-                installId,
-                error: u instanceof Error ? u.message : String(u),
-            });
+        try {
+            return await f();
         }
-        if (cause instanceof ApiError && cause.code === "plugin.install_in_progress" && rolledBack) {
-            return cause;
+        finally {
+            await handle.release();
         }
-        const dependency = failure && failure.dependency.length > 0 ? failure.dependency : [];
-        const dep = dependency.length > 0 ? ` in dependency ${dependency.join(" > ")}` : "";
-        return new ApiError("plugin.upgrade_failed", rolledBack
-            ? `Upgrading the plugin failed at step ${at}${dep} (${code}); this organization's components are back at version ${diff.from.version}`
-            : `Upgrading the plugin failed at step ${at}${dep} (${code}) and rolling back failed; it is undone after catalog.staleInstallMinutes`, [
-            {
-                step: at,
-                code,
-                ...(dependency.length > 0 && { dependency: dependency.join(" > ") }),
-                ...(cause instanceof ApiError && { message: cause.message }),
-                ...(cause instanceof ApiError &&
-                    cause.details !== undefined && { causeDetails: cause.details }),
-                rolledBack,
-            },
-        ]);
     }
     /**
-     * An upgrade interrupted for longer than `catalog.staleInstallMinutes` (a replica crashed
-     * midway): its journal is undone, the install back `installed` at the old version (error step
-     * `interrupted`), audit `plugin.org_upgrade_failed`. Nothing to do otherwise.
+     * The super admin's confirmation of an org upload's pending new version (rulings P3-10, P3-21,
+     * pre-flight F8): the update to `version` as {@link update} does it (the super admin's, the
+     * extension installed or upgraded on the deployment), with the version allowed although it is
+     * pending. Its transaction re-reads the item under the row lock: removed meanwhile -> 409
+     * `catalog.item_removed`, the pending version replaced -> 409 `extension.approval_stale` (both
+     * undo the extension step); then the pending state is cleared and the owner told
+     * (`upload_confirmed`). The caller checked the digest of the version's package.
      */
-    async recoverInterrupted(orgId, actor, installId) {
-        if (!UUID_RE.test(installId))
-            throw installNotFound();
-        const removed = await this.undoInterrupted(orgId, actor, installId);
-        for (const r of removed) {
-            if (r.kind === "extension")
-                await this.orgConfigs.afterDisable(orgId, r.ref);
-        }
+    async updateToPending(actor, itemId, version, opts = {}) {
+        if (!UUID_RE.test(itemId))
+            throw itemNotFound();
+        return this.locked(itemId, () => this.updateToPendingLocked(actor, itemId, version, opts));
     }
-    /** The upgrade's start: the install `upgrading` with an empty journal (a transaction of its own). */
-    async start(orgId, actor, installId, diff, upgradeId) {
-        const { itemId } = diff;
-        const t = this.db;
-        await lockOrgForActions(this.orgLock, orgId, actor, diff.actions);
-        const row = await t
-            .selectFrom("plugin_installs")
-            .select(["status", "version"])
-            .where("id", "=", installId)
-            .where("org_id", "=", orgId)
-            .forUpdate()
-            .executeTakeFirst();
-        if (!row || row.status === "failed")
-            throw installNotFound();
-        if (row.status !== "installed")
-            throw inProgress();
-        if (row.version !== diff.from.version ||
-            ledgerHash(await ledgerOf(t, installId)) !== diff.ledgerHash) {
-            throw stale();
-        }
-        await assertItemInstallable(t, orgId, itemId);
-        await t
-            .updateTable("plugin_installs")
-            .set({
-            status: "upgrading",
-            upgrade: sql `jsonb_build_object('id', ${upgradeId}::text, 'from', ${diff.from.version}::text, 'to', ${diff.to.version}::text, 'startedAt', now(), 'done', '[]'::jsonb)`,
-        })
-            .where("id", "=", installId)
-            .execute();
+    /**
+     * {@link updateToPending} for a caller already holding the item's update lock
+     * ({@link withItemLock}): the super admin's confirmation runs all its steps under it (ruling
+     * P3-35).
+     */
+    async updateToPendingLocked(actor, itemId, version, opts = {}) {
+        const d = await this.diff(itemId, version, { confirmPending: version });
+        return this.updateLocked(actor, itemId, { version, diffHash: d.diffHash }, opts, undefined, version);
     }
-    /** A skill step's ledger and journal rows, in a transaction of their own. */
-    async journalSkill(r, record, journal) {
-        if (r.created) {
-            await record({ kind: "skill", ref: r.skill.id, created: true, skillVersion: null });
-            return;
-        }
-        await journal({ op: "skill_version", ref: r.skill.id, version: r.version });
-        await record({ kind: "skill", ref: r.skill.id, created: false, skillVersion: r.version });
+    /**
+     * Runs `f` holding the item's update lock (the one every platform update of the item takes;
+     * another holder -> 409 `plugin.install_in_progress`): the super admin's confirmation of an org
+     * upload runs every step under it (ruling P3-35).
+     */
+    withItemLock(itemId, f) {
+        if (!UUID_RE.test(itemId))
+            throw itemNotFound();
+        return this.locked(itemId, f);
     }
     /**
-     * An agent template step: the new version (or template) and its ledger and journal rows, under
-     * the org row lock, in a transaction of their own.
+     * Runs an update confirmed with the preview's `diffHash` (see the class comment). A version an
+     * org upload waits with, or an item whose first version waits, -> 409 `catalog.item_pending`
+     * (confirmed in 待确认 instead, pre-flight F8).
      */
-    async upgradeAgentTemplate(orgId, diff, template, record, journal) {
-        const { itemId } = diff;
-        const t = this.db;
-        await this.orgLock.lock(orgId);
-        const r = await putTemplateVersionIn(t, {
-            orgId,
-            plugin: diff.name,
-            catalogItemId: itemId,
-            catalogVersion: diff.to.version,
-            sourceFormat: diff.to.source_format,
-        }, template);
-        if (r.created) {
-            await record({ kind: "agent_template", ref: r.id, created: true, skillVersion: null });
-            return;
-        }
-        if (r.changed)
-            await journal({ op: "template_version", ref: r.id, version: r.version });
-        await record({
-            kind: "agent_template",
-            ref: r.id,
-            created: false,
-            skillVersion: r.changed ? r.version : null,
-        });
+    async update(actor, itemId, input, opts = {}) {
+        if (!UUID_RE.test(itemId))
+            throw itemNotFound();
+        return this.locked(itemId, () => this.updateLocked(actor, itemId, input, opts));
     }
-    /** One ledger record (and its journal row) in a transaction of its own. */
-    async recordStep(installId, journal, c) {
-        await this.recordIn(installId, journal, c);
+    async updateLocked(actor, itemId, input, opts, owner, confirmPending) {
+        // Storage is read and written here, before any transaction (see the class comment)
+        const checked = await this.diff(itemId, input.version, {
+            ...(owner && { owner }),
+            ...(confirmPending !== undefined && { confirmPending }),
+        });
+        if (checked.diffHash !== input.diffHash)
+            throw stale();
+        const prepared = await this.platform.prepareSync(itemId, input.version);
+        const ext = checked.extension;
+        // The extension admin re-checks the actor: a super admin, or for an owner update the owner
+        // org's admin (and audits it with `ownerOrgId`)
+        const opsOwner = owner && { orgId: owner.orgId };
+        let step = "extension";
+        let extensionMoved = false;
+        let enabledHere = false;
+        let leftDisabled;
+        /** A removal: the extension was enabled before it (put back enabled on failure). */
+        let removedEnabled = false;
+        try {
+            if (ext?.sha256 === null) {
+                // The target drops the extension (P3-12'): disabled (drained), then uninstalled
+                const row = await this.db
+                    .selectFrom("extension_installs")
+                    .select("desired_state")
+                    .where("name", "=", checked.name)
+                    .executeTakeFirst();
+                removedEnabled = row?.desired_state === "enabled";
+                await this.ops.disable(checked.name, actor, opts.actorTokenId, opsOwner);
+                extensionMoved = true;
+                await this.ops.uninstall(checked.name, actor, opts.actorTokenId, opsOwner);
+            }
+            else if (ext) {
+                const installed = await this.ops.install(checked.name, ext.sha256, actor, opts.actorTokenId, { catalogItemId: itemId, ...(opsOwner && { owner: opsOwner }) });
+                extensionMoved = true;
+                // A new version newly providing a held single-provider point: left disabled by the install
+                leftDisabled = installed.leftDisabled;
+                if (ext.previous === null) {
+                    // An occupied single-provider point leaves it installed disabled
+                    const r = await this.ops.enableUnlessOccupied(checked.name, actor, opts.actorTokenId, opsOwner);
+                    enabledHere = r.enabled;
+                    if (!r.enabled)
+                        leftDisabled = r.note;
+                }
+            }
+            step = "components";
+            const diff = await this.commit(actor, itemId, input, opts, { contents: checked.contents, extension: ext }, prepared, owner, confirmPending);
+            return {
+                itemId,
+                version: diff.to.version,
+                components: diff.components,
+                extension: extensionView(diff.extension),
+                connectorOrgs: diff.connectorOrgs,
+                ...(leftDisabled !== undefined && { extensionLeftDisabled: leftDisabled }),
+            };
+        }
+        catch (e) {
+            let rolledBack = true;
+            if (extensionMoved && ext) {
+                // An owner update was authorized at its start: the put-back is not checked again
+                const back = opsOwner && { ...opsOwner, rollback: true };
+                try {
+                    if (ext.sha256 === null) {
+                        // Removed by this update: the previous package reinstalled (as it was)
+                        await this.ops.install(checked.name, ext.previous, actor, opts.actorTokenId, {
+                            catalogItemId: itemId,
+                            ...(back && { owner: back }),
+                        });
+                        if (removedEnabled)
+                            await this.ops.enable(checked.name, actor, opts.actorTokenId, back);
+                    }
+                    else if (ext.previous !== null) {
+                        await this.ops.install(checked.name, ext.previous, actor, opts.actorTokenId, {
+                            ...(back && { owner: back }),
+                        });
+                        // The install left the enabled extension disabled (a held single-provider point): the
+                        // previous version, which did not provide it, runs again
+                        if (leftDisabled !== undefined) {
+                            await this.ops.enable(checked.name, actor, opts.actorTokenId, back);
+                        }
+                    }
+                    else {
+                        // Installed by this update: an uninstall needs it disabled first
+                        if (enabledHere)
+                            await this.ops.disable(checked.name, actor, opts.actorTokenId, back);
+                        await this.ops.uninstall(checked.name, actor, opts.actorTokenId, back);
+                    }
+                }
+                catch (u) {
+                    rolledBack = false;
+                    this.log.error("putting a plugin's extension back after a failed update failed", {
+                        itemId,
+                        plugin: checked.name,
+                        err: u,
+                    });
+                }
+            }
+            const code = e instanceof ApiError ? e.code : "internal";
+            await this.auditFailure(actor, checked, { step, code, rolledBack }, opts);
+            // A refusal found under the lock (stale, disabled meanwhile, a conflict, a downgrade the
+            // extension's migrations refuse): returned as it is
+            if (e instanceof ApiError && e.status < 500 && rolledBack)
+                throw e;
+            throw new ApiError("plugin.upgrade_failed", rolledBack
+                ? `Updating the plugin failed at step ${step} (${code}); the platform is back at version ${checked.from ?? "(none)"}`
+                : `Updating the plugin failed at step ${step} (${code}) and putting its extension back failed; check the extension in the admin console`, [
+                {
+                    step,
+                    code,
+                    ...(e instanceof ApiError && { message: e.message }),
+                    ...(e instanceof ApiError && e.details !== undefined && { causeDetails: e.details }),
+                    rolledBack,
+                },
+            ]);
+        }
     }
-    /** A component's ledger row and its journal step, in the transaction of the context. */
-    async recordIn(installId, journal, c) {
-        const inserted = await this.db
-            .insertInto("plugin_install_components")
-            .values({
-            install_id: installId,
-            kind: c.kind,
-            ref: c.ref,
-            created: c.created,
-            skill_version: c.skillVersion,
-            template_id: c.templateId ?? null,
-        })
-            .onConflict((oc) => oc.columns(["install_id", "kind", "ref"]).doNothing())
-            .returning("ref")
-            .executeTakeFirst();
-        if (c.created)
-            await journal({ op: "created", kind: c.kind, ref: c.ref });
-        else if (inserted)
-            await journal({ op: "recorded", kind: c.kind, ref: c.ref });
+    /** `plugin.platform_update_failed`, in a transaction of its own. */
+    async auditFailure(actor, diff, f, opts) {
+        await audit(this.db, {
+            actorAccountId: actor,
+            ...(opts.actorTokenId !== undefined && { actorTokenId: opts.actorTokenId }),
+            action: "plugin.platform_update_failed",
+            target: diff.itemId,
+            detail: { name: diff.name, from: diff.from, to: diff.to.version, ...f },
+        });
     }
     /**
-     * The upgrade's last transaction (under the org row lock): the changed connectors, the removals,
-     * the pinned suggestions and the version switch, `plugin.org_upgraded`. `onFinish` marks the step
-     * once the connectors are applied.
+     * The update's transaction (see the class comment): the super admin re-checked, the diff
+     * recomputed under the item name's lock, then every write. Returns the diff it applied.
      */
-    async finish(orgId, actor, installId, upgradeId, diff, prepared, disabled, opts, onFinish) {
-        const { itemId } = diff;
-        const t = this.db;
-        await lockOrgForActions(this.orgLock, orgId, actor, diff.actions);
-        const row = await t
-            .selectFrom("plugin_installs")
-            .select(["status", sql `upgrade->>'id'`.as("upgradeId")])
-            .where("id", "=", installId)
-            .forUpdate()
+    async commit(actor, itemId, input, opts, pre, prepared, owner, confirmPending) {
+        if (owner === undefined)
+            await this.adminLock.lockAndAuthorize(actor);
+        // The global lock order (ruling P3-50): the orgs (sorted; the acting owner org's admin
+        // re-checked at its place), then the item, then its components; an org deletion locks its org
+        // row, then the items it owns
+        const liveOrgs = await this.lockUpdateOrgs(itemId, owner && { orgId: owner.orgId, actor });
+        const named = await this.db
+            .selectFrom("catalog_items")
+            .select("name")
+            .where("id", "=", itemId)
             .executeTakeFirst();
-        if (row?.status !== "upgrading" || row.upgradeId !== upgradeId)
-            throw cleanedUp();
-        await assertItemInstallable(t, orgId, itemId);
-        for (const c of prepared) {
-            await this.connectors.applyTemplateIn(orgId, c.connectorId, actor, c.p, opts.actorTokenId);
+        if (!named)
+            throw itemNotFound();
+        await this.itemLock.lock(named.name);
+        let pendingOwner = null;
+        if (confirmPending !== undefined) {
+            // The super admin's confirmation (P3-21): still pending with the version they reviewed
+            const row = await this.db
+                .selectFrom("catalog_items")
+                .select(["deleted_at", "pending_version", "owner_org_id"])
+                .where("id", "=", itemId)
+                .forUpdate()
+                .executeTakeFirstOrThrow();
+            if (row.deleted_at !== null)
+                throw itemRemovedError(named.name);
+            if (row.pending_version !== confirmPending)
+                throw pendingStale(named.name);
+            pendingOwner = row.owner_org_id;
         }
-        onFinish();
-        for (const dep of diff.dependencies) {
-            if (dep.change !== "changed" || !dep.child)
-                continue;
-            const live = await t
-                .selectFrom("plugin_installs")
-                .select("version")
-                .where("id", "=", dep.child.installId)
-                .forShare()
-                .executeTakeFirst();
-            if (!live || !satisfiesRange(live.version, dep.range)) {
-                throw new ApiError("catalog.dependency_unresolved", `Dependency ${dep.name}@${dep.range} cannot be resolved: its install in this organization changed meanwhile; preview the upgrade again`, [{ dependency: dep.name, range: dep.range }]);
-            }
+        const diff = await this.diff(itemId, input.version, {
+            pre,
+            ...(owner && { owner }),
+            ...(confirmPending !== undefined && { confirmPending }),
+        });
+        if (diff.diffHash !== input.diffHash)
+            throw stale();
+        const t = this.db;
+        // The platform versions (files copied before the transaction; rows only here)
+        try {
+            await this.platform.applySyncIn(prepared);
         }
-        const report = await this.removeIn(orgId, actor, diff, disabled);
-        // An unchanged skill gets no new version, so the target's pinned suggestion goes onto its
-        // current version (when that version is this plugin's) here, with the version switch.
-        for (const sk of diff.skills) {
-            if (sk.change !== "unchanged" || !sk.ledger)
-                continue;
+        catch (e) {
+            if (e instanceof PlanStale)
+                throw stale();
+            throw e;
+        }
+        for (const [id, pinned] of diff.suggest) {
             await t
-                .updateTable("skill_versions as v")
-                .set({ suggest_pinned: sk.suggestPinned === true })
-                .from("skills as s")
+                .updateTable("platform_skill_versions as v")
+                .set({ suggest_pinned: pinned })
+                .from("platform_skills as s")
                 .whereRef("s.id", "=", "v.skill_id")
                 .whereRef("s.current_version", "=", "v.version")
-                .where("s.id", "=", sk.ledger.ref)
-                .where("s.org_id", "=", orgId)
-                .where("v.catalog_item_id", "=", itemId)
-                .where("v.suggest_pinned", "<>", sk.suggestPinned === true)
+                .where("s.id", "=", id)
+                .execute();
+        }
+        // Removals (spec §7.3): kept while agents use it; otherwise soft-deleted
+        const now = sql `now()`;
+        for (const c of diff.components) {
+            if (c.change !== "removed" || c.id === null || c.kept !== undefined)
+                continue;
+            const table = c.kind === "skill"
+                ? "platform_skills"
+                : c.kind === "agent_template"
+                    ? "platform_agent_templates"
+                    : c.kind === "theme"
+                        ? "platform_themes"
+                        : "platform_connector_templates";
+            await t
+                .updateTable(table)
+                .set({ deleted_at: now, updated_at: now })
+                .where("id", "=", c.id)
                 .execute();
         }
+        // Pins of linked copies: moved to the plugin's version (spec §7.1)
+        for (const c of diff.components) {
+            if (c.change === "removed" || c.id === null || c.pinnedOrgs.length === 0)
+                continue;
+            if (c.kind === "skill") {
+                await t
+                    .updateTable("skills")
+                    .set({ pinned_version: null, updated_at: now })
+                    .where("platform_skill_id", "=", c.id)
+                    .where("org_id", "in", c.pinnedOrgs)
+                    .where("pinned_version", "is not", null)
+                    .execute();
+            }
+            else if (c.kind === "agent_template") {
+                await t
+                    .updateTable("agent_templates")
+                    .set({ pinned_version: null, updated_at: now })
+                    .where("platform_template_id", "=", c.id)
+                    .where("org_id", "in", c.pinnedOrgs)
+                    .where("pinned_version", "is not", null)
+                    .execute();
+            }
+        }
+        // Connectors made from changed templates, in every org (ruling E2)
+        const orgs = [...new Set(diff.connectors.map((c) => c.orgId))].sort();
+        for (const orgId of orgs) {
+            if (!liveOrgs.has(orgId)) {
+                // Locked before the item (P3-50): an org not locked then is deleted (its connectors go
+                // with it), or its connector was made since, which changes what the update does
+                const live = await t
+                    .selectFrom("orgs")
+                    .select("id")
+                    .where("id", "=", orgId)
+                    .where("deleted_at", "is", null)
+                    .executeTakeFirst();
+                if (live === undefined)
+                    continue;
+                throw stale();
+            }
+            for (const c of diff.connectors.filter((x) => x.orgId === orgId)) {
+                const prepared = await this.prepare(actor, itemId, diff.to.version, c);
+                await this.connectors.applyTemplateIn(orgId, c.id, actor, prepared, opts.actorTokenId);
+            }
+        }
+        // One version for the deployment: every live org install of the plugin moves with it (one
+        // still installing too, and a legacy `upgrading` row; an install marked installed later
+        // records the platform version current at its commit, PluginInstaller.markInstalled)
         await t
             .updateTable("plugin_installs")
-            .set({ version: diff.to.version, status: "installed", upgrade: null, error: null })
-            .where("id", "=", installId)
+            .set({ version: diff.to.version, error: null })
+            .where("item_id", "=", itemId)
+            .where("status", "in", ["installing", "installed", "upgrading"])
             .execute();
-        await this.requests.resolveByInstall(orgId, itemId, actor, opts);
-        await audit(t, {
-            actorAccountId: actor,
-            ...(opts.actorTokenId !== undefined && { actorTokenId: opts.actorTokenId }),
-            orgId,
-            action: "plugin.org_upgraded",
-            target: installId,
-            detail: {
+        if (owner !== undefined || confirmPending !== undefined) {
+            // An org's version becomes its latest once applied or confirmed (ruling P3-34)
+            await t
+                .updateTable("catalog_items")
+                .set({ latest_version: diff.to.version })
+                .where("id", "=", itemId)
+                .execute();
+            await markVersionApplied(t, itemId, diff.to.version);
+            // An owner's new version replaces a version waiting for the super admin (pre-flight F7):
+            // their confirmation of it is then refused (409 extension.not_pending); the super admin's
+            // confirmation applied it
+            await t
+                .updateTable("catalog_items")
+                .set({ pending_version: null, pending_by: null, pending_at: null })
+                .where("id", "=", itemId)
+                .where("pending_version", "is not", null)
+                .execute();
+        }
+        if (confirmPending !== undefined && pendingOwner !== null) {
+            await addOrgNotice(t, pendingOwner, "upload_confirmed", {
                 itemId,
                 name: diff.name,
-                from: diff.from.version,
-                to: diff.to.version,
-                components: diff.components,
-                removed: report.removed,
-                kept: report.kept,
-            },
-        });
-    }
-    /** Undoes a failed upgrade's journal (see {@link failed}) in a transaction of its own. */
-    async undoFailed(orgId, actor, installId, upgradeId, diff, steps, f, opts) {
-        const { at, code } = f;
-        const t = this.db;
-        await this.orgLock.lock(orgId);
-        const row = await t
-            .selectFrom("plugin_installs")
-            .select(sql `upgrade->>'id'`.as("upgradeId"))
-            .where("id", "=", installId)
-            .forUpdate()
-            .executeTakeFirst();
-        const ours = row?.upgradeId === upgradeId;
-        // Cleaned up meanwhile: only the step whose journal write found the journal gone is ours to
-        // undo. When that step ran in the same transaction as its journal write (the extension
-        // enable, the ledger rows), the transaction rolled back with the failed write, so undoing
-        // it is a no-op (a never-enabled extension, a never-inserted row); undoing is still safe.
-        const undo = ours ? steps.done : steps.unjournaled ? [steps.unjournaled] : [];
-        const out = await this.installer.undoUpgradeIn(orgId, actor, installId, undo, "plugin_upgrade_rollback");
-        await t
-            .updateTable("plugin_installs")
-            .set({ status: "installed", upgrade: null, error: JSON.stringify({ step: at, code }) })
-            .where("id", "=", installId)
-            .where(sql `upgrade->>'id'`, "=", upgradeId)
-            .execute();
+                displayName: await itemDisplayName(t, itemId),
+                version: diff.to.version,
+            });
+        }
+        // The orgs using a shared org-owned plugin are told, one notice per plugin (a platform-owned
+        // plugin tells nobody); a plugin never synced before has no version to come from
+        if (diff.from !== null) {
+            await notifySharedUpdate(t, { kind: "plugin", id: itemId }, { name: diff.name, from: diff.from, to: diff.to.version });
+        }
         await audit(t, {
             actorAccountId: actor,
             ...(opts.actorTokenId !== undefined && { actorTokenId: opts.actorTokenId }),
-            orgId,
-            action: "plugin.org_upgrade_failed",
-            target: installId,
+            action: "plugin.platform_updated",
+            target: itemId,
             detail: {
-                itemId: diff.itemId,
                 name: diff.name,
-                from: diff.from.version,
+                from: diff.from,
                 to: diff.to.version,
-                step: at,
-                code,
-                rolledBack: undo,
-                ...(!ours && { cleanedUpMeanwhile: true }),
+                ...(owner !== undefined && { ownerOrgId: owner.orgId }),
+                components: diff.components.map((c) => ({
+                    kind: c.kind,
+                    name: c.name,
+                    change: c.change,
+                    ...(c.kept !== undefined && { kept: true }),
+                    ...(c.pinnedOrgs.length > 0 && c.change !== "removed" && { unpinned: c.pinnedOrgs }),
+                })),
+                ...(diff.extension && { extension: extensionView(diff.extension) }),
+                connectors: diff.connectors.map((c) => ({
+                    orgId: c.orgId,
+                    id: c.id,
+                    credentialsReset: c.credentialsReset,
+                })),
+                ...opts.auditDetail,
             },
         });
-        return out;
-    }
-    /** Undoes an interrupted upgrade (see {@link recoverInterrupted}) in a transaction of its own. */
-    async undoInterrupted(orgId, actor, installId) {
-        const staleMinutes = this.installer.staleInstallMinutes();
-        const t = this.db;
-        const peek = await t
-            .selectFrom("plugin_installs")
-            .select("status")
-            .where("id", "=", installId)
-            .where("org_id", "=", orgId)
-            .executeTakeFirst();
-        if (peek?.status !== "upgrading")
-            return [];
-        await this.orgLock.lock(orgId);
-        const row = await t
-            .selectFrom("plugin_installs as a")
-            .innerJoin("catalog_items as i", "i.id", "a.item_id")
-            .select([
-            "a.status",
-            "a.upgrade",
-            "a.item_id",
-            "i.name",
-            sql `coalesce((a.upgrade->>'startedAt')::timestamptz < now() - make_interval(mins => ${staleMinutes}), false)`.as("stale"),
-        ])
-            .where("a.id", "=", installId)
-            .where("a.org_id", "=", orgId)
-            .forUpdate("a")
-            .executeTakeFirst();
-        if (row?.status !== "upgrading" || !row.stale)
-            return [];
-        const steps = journalEntries(row.upgrade);
-        const out = await this.installer.undoUpgradeIn(orgId, actor, installId, steps, "plugin_upgrade_cleanup");
-        await t
-            .updateTable("plugin_installs")
-            .set({
-            status: "installed",
-            upgrade: null,
-            error: JSON.stringify({ step: "interrupted", code: "internal" }),
-        })
-            .where("id", "=", installId)
-            .execute();
-        const j = row.upgrade;
-        await audit(t, {
-            actorAccountId: actor,
-            orgId,
-            action: "plugin.org_upgrade_failed",
-            target: installId,
-            detail: {
-                itemId: row.item_id,
-                name: row.name,
-                from: j?.from ?? null,
-                to: j?.to ?? null,
-                step: "interrupted",
-                code: "internal",
-                rolledBack: steps,
-            },
+        const enqueue = [itemId, ...diff.dependencies];
+        afterCommit(async () => {
+            for (const id of enqueue) {
+                try {
+                    await this.sync.enqueueItem(id);
+                }
+                catch (err) {
+                    this.log.warn("enqueueing the scope sync after a platform update failed", {
+                        itemId: id,
+                        err,
+                    });
+                }
+            }
         });
-        return out;
+        return diff;
     }
     /**
-     * The removals of an upgrade, in the final transaction, by the uninstall rules
-     * (`decideRemovalIn`): only components this install created are removed, and only when nothing
-     * else uses them; one still used (by an agent, a connector or another extension) stays in the
-     * ledger marked `dropped` ("no longer in the plugin", still this install's), every other removed
-     * component leaves the ledger; a dropped component the target brings back is un-dropped. A dependency
-     * install is uninstalled by the same rules (another install using it takes it over). Skills ->
-     * connectors -> extension -> dependencies.
+     * The template update of one connector: the new endpoint preset with the org's values at the
+     * editable paths, the auth preset and default policies; credentials cleared (no new ones: they
+     * are the org's) when the credential shape changed.
      */
-    async removeIn(orgId, actor, diff, disabled) {
-        const report = { removed: [], kept: [] };
-        const reason = "plugin_upgrade";
-        const t = this.db;
-        const keep = (kind, ref, why) => report.kept.push({ kind, ref, reason: why });
-        const row = (kind, ref) => t
-            .updateTable("plugin_install_components")
-            .where("install_id", "=", diff.installId)
-            .where("kind", "=", kind)
-            .where("ref", "=", ref);
-        const dropRow = (kind, ref) => t
-            .deleteFrom("plugin_install_components")
-            .where("install_id", "=", diff.installId)
-            .where("kind", "=", kind)
-            .where("ref", "=", ref)
-            .execute();
-        const removed = [
-            ...diff.skills.flatMap((x) => (x.change === "removed" && x.ledger ? [x.ledger] : [])),
-            ...diff.agentTemplates.flatMap((x) => (x.change === "removed" && x.ledger ? [x.ledger] : [])),
-            ...diff.templates.flatMap((x) => (x.change === "removed" && x.ledger ? [x.ledger] : [])),
-            ...(diff.extension?.change === "removed"
-                ? diff.ledger.filter((l) => l.kind === "extension" && l.ref === diff.extension?.name)
-                : []),
-        ];
-        const agentRefs = await this.installer.agentRefs(orgId);
-        const self = new Set([diff.installId]);
-        for (const l of removed) {
-            if (!l.created) {
-                await dropRow(l.kind, l.ref);
-                keep(l.kind, l.ref, "pre_existing");
-                continue;
-            }
-            const outcome = await this.installer.decideRemovalIn(orgId, actor, { kind: l.kind, ref: l.ref, created: true, skillVersion: null }, self, agentRefs, reason);
-            if (outcome === "used_by_agents" ||
-                outcome === "used_by_connectors" ||
-                outcome === "used_by_plugins") {
-                // Still used: stays this install's, marked dropped, so an uninstall (or a later upgrade
-                // bringing it back) still finds it
-                await row(l.kind, l.ref).set({ dropped: true }).execute();
-                keep(l.kind, l.ref, outcome);
-                continue;
-            }
-            await dropRow(l.kind, l.ref);
-            if (outcome === "removed") {
-                report.removed.push({ kind: l.kind, ref: l.ref });
-                if (l.kind === "extension")
-                    disabled.push(l.ref);
-            }
-            else if (outcome !== "gone")
-                keep(l.kind, l.ref, outcome);
-        }
-        // Components back in the plugin (dropped by an earlier upgrade, brought again by the target)
-        const back = [
-            ...diff.skills.flatMap((x) => x.change !== "removed" && x.ledger?.dropped
-                ? [{ kind: "skill", ref: x.ledger.ref }]
-                : []),
-            ...diff.agentTemplates.flatMap((x) => x.change !== "removed" && x.ledger?.dropped
-                ? [{ kind: "agent_template", ref: x.ledger.ref }]
-                : []),
-            ...diff.templates.flatMap((x) => x.change !== "removed" && x.ledger?.dropped
-                ? [{ kind: "connector", ref: x.ledger.ref }]
-                : []),
-            ...(diff.extension && diff.extension.change !== "removed"
-                ? diff.ledger
-                    .filter((l) => l.kind === "extension" && l.ref === diff.extension?.name && l.dropped)
-                    .map((l) => ({ kind: "extension", ref: l.ref }))
-                : []),
-        ];
-        for (const b of back)
-            await row(b.kind, b.ref).set({ dropped: false }).execute();
-        for (const dep of diff.dependencies) {
-            if (dep.change !== "removed" || !dep.child)
-                continue;
-            const ref = dep.child.installId;
-            await dropRow("plugin", ref);
-            if (!dep.child.ledger.created) {
-                keep("plugin", ref, "pre_existing");
-                continue;
-            }
-            const sub = { removed: [], kept: [] };
-            const outcome = await this.installer.uninstallIn(orgId, actor, ref, {
-                report: sub,
-                removing: new Set(),
-                from: diff.installId,
-                authorize: false,
-                reason,
-                opts: {},
-            });
-            for (const r of sub.removed)
-                if (r.kind === "extension")
-                    disabled.push(r.ref);
-            if (outcome === "removed")
-                report.removed.push({ kind: "plugin", ref });
-            else if (outcome === "kept")
-                keep("plugin", ref, "used_by_other_install");
+    async prepare(actor, itemId, version, c) {
+        const template = c.file.template;
+        const endpoint = structuredClone(template.endpoint);
+        for (const e of template.editableEndpoint ?? []) {
+            const v = getPath(c.endpoint, e);
+            if (v !== undefined)
+                setPath(endpoint, e, v);
         }
-        return report;
+        const input = {
+            endpoint,
+            auth: template.auth,
+            template: {
+                itemId,
+                version,
+                templateId: c.templateId,
+                ...(template.defaultToolPolicies !== undefined && {
+                    defaultToolPolicies: template.defaultToolPolicies,
+                }),
+            },
+            resetCredentials: false,
+        };
+        // Checked without credentials (nothing outbound); a changed shape then clears the old ones
+        const prepared = await this.connectors.prepareTemplateUpdate(actor, c.connector, input);
+        return c.credentialsReset
+            ? { ...prepared, input: { ...prepared.input, resetCredentials: true } }
+            : prepared;
     }
     /**
-     * Computes an upgrade (see the class comment). `input` null: the preview (no input checks);
-     * otherwise the connector inputs are built and checked as at install.
+     * Computes an update (see the class comment). `target`: the target read from an org's staging
+     * instead of `catalog_item_versions` (pre-flight F3). `owner`: an owner update (P3-12): the item
+     * must be the org's, an extension-bearing target is refused, and a target dropping the
+     * extension removes it.
      */
-    async diff(orgId, actor, installId, version, input) {
+    async diff(itemId, version, o = {}) {
         const db = this.db;
-        if (!UUID_RE.test(installId))
-            throw installNotFound();
-        const install = await db
-            .selectFrom("plugin_installs as a")
-            .innerJoin("catalog_items as i", "i.id", "a.item_id")
-            .select(["a.item_id", "a.version", "a.status", "i.name", "i.policy", "i.deleted_at"])
-            .where("a.id", "=", installId)
-            .where("a.org_id", "=", orgId)
+        if (!UUID_RE.test(itemId))
+            throw itemNotFound();
+        const item = await db
+            .selectFrom("catalog_items")
+            .select([
+            "id",
+            "name",
+            "disabled",
+            "builtin",
+            "deleted_at",
+            "platform_synced_version",
+            "owner_org_id",
+            "awaiting_confirmation",
+            "pending_version",
+            "latest_version",
+        ])
+            .where("id", "=", itemId)
             .executeTakeFirst();
-        if (!install || install.status === "failed")
-            throw installNotFound();
-        if (install.status !== "installed")
-            throw inProgress();
-        const itemId = install.item_id;
-        const name = install.name;
-        if (install.deleted_at !== null) {
-            throw new ApiError("catalog.item_not_found", "This plugin is no longer in the enterprise catalog");
+        if (!item || item.deleted_at !== null)
+            throw itemNotFound();
+        // A version waiting for the super admin applies only through their confirmation (P3-9, F8)
+        if (o.confirmPending !== version) {
+            if (item.awaiting_confirmation)
+                throw itemPendingError(item.name);
+            if (item.pending_version !== null && item.pending_version === version) {
+                throw itemPendingError(item.name, version);
+            }
+            // The super admin's generic update of an org's plugin reaches only its applied version
+            // (`latest_version`, ruling P3-34/P3-37): one the org uploaded that was never applied or
+            // confirmed (a rejected or failed one) is not theirs to apply
+            if (o.owner === undefined && item.owner_org_id !== null && version !== item.latest_version) {
+                throw notApplied(item.name, version);
+            }
         }
-        if (install.policy === "disabled") {
-            throw new ApiError("catalog.item_disabled", "This catalog item is disabled by the enterprise admin and cannot be upgraded");
+        if (o.owner !== undefined && item.owner_org_id !== o.owner.orgId)
+            throw itemNotFound();
+        if (item.disabled) {
+            throw new ApiError("catalog.item_disabled", "This plugin is disabled on the deployment; enable it before updating");
         }
-        const versions = await db
+        const name = item.name;
+        const versions = (await db
             .selectFrom("catalog_item_versions")
             .select([
             "version",
@@ -784,561 +765,774 @@ let PluginUpgrader = class PluginUpgrader {
             "object_prefix",
             "files",
             "extension_sha256",
-            "imported_at",
-            "source_format",
+            "applied_at",
+            "rejected_at",
         ])
             .where("item_id", "=", itemId)
-            .execute();
-        const fromRow = versions.find((v) => v.version === install.version);
-        const toRow = versions.find((v) => v.version === version);
-        if (!fromRow) {
-            throw new ApiError("catalog.item_not_found", `The installed version ${install.version} is no longer in the enterprise catalog`);
-        }
-        if (!toRow)
+            .execute());
+        const to = o.target ?? versions.find((v) => v.version === version);
+        if (!to)
             throw new ApiError("catalog.item_not_found", `Version ${version} of this item not found`);
-        const from = fromRow;
-        const to = toRow;
-        if (to.version === from.version) {
-            // Confirming a preview whose upgrade already ran (a concurrent confirm won): stale
-            if (input !== null)
+        // Whoever owns the item now (a transfer keeps the version rows), the generic update never
+        // reaches a version that was rejected or never applied (ruling P3-52)
+        const row = versions.find((v) => v.version === version);
+        if (o.owner === undefined && o.confirmPending !== version && row && !versionUsable(row)) {
+            throw notApplied(item.name, version);
+        }
+        if (o.owner !== undefined && to.manifest.extension) {
+            // An org's version with an extension waits for the super admin's confirmation (plan Task 6)
+            throw new ApiError("plugin.extension_upload_pending", `Version ${to.version} of plugin ${item.name} has an extension; it applies once a super admin confirms it`);
+        }
+        const from = item.platform_synced_version;
+        const fromRow = versions.find((v) => v.version === from);
+        if (from === to.version) {
+            // Confirming a preview whose update already ran (a concurrent confirm won): stale
+            if (o.pre)
                 throw stale();
-            throw targetInvalid(`This organization already has version ${from.version} installed`, [
-                { reason: "same_version", version: from.version },
+            throw targetInvalid(`The platform already runs version ${from} of plugin ${name}`, [
+                { reason: "same_version", version: from },
             ]);
         }
-        // Target rules (Decision 10)
-        if (to.manifest.extension) {
-            const deployed = await deployedExtension(db, this.registry, name);
-            const allowed = deploymentTarget(versions, deployed);
-            if (allowed?.version !== to.version) {
-                throw targetInvalid(deployed === undefined
-                    ? `The deployment does not run the extension of plugin ${name}; ask the enterprise admin to install it first`
-                    : `The deployment runs the extension of plugin ${name} at version ${deployed.version}; this organization can upgrade only to ${allowed ? `catalog version ${allowed.version}` : "a catalog version carrying that extension, and none is imported"}`, [
-                    {
-                        reason: "deployment_version",
-                        deploymentVersion: deployed?.version ?? null,
-                        allowedVersion: allowed?.version ?? null,
-                    },
-                ]);
+        const target = await this.extensionTarget(name, fromRow, to, o.owner !== undefined);
+        let extension;
+        if (o.pre) {
+            // The confirm's transaction: the extension this update moved is expected in place (a
+            // removed one gone)
+            if (o.pre.extension) {
+                const row = await db
+                    .selectFrom("extension_installs")
+                    .select("sha256")
+                    .where("name", "=", name)
+                    .executeTakeFirst();
+                if ((row?.sha256 ?? null) !== o.pre.extension.sha256)
+                    throw stale();
+                extension = o.pre.extension;
             }
-        }
-        // Installs in this org depending on this one must accept the target
-        const parents = await db
-            .selectFrom("plugin_install_components as c")
-            .innerJoin("plugin_installs as a", "a.id", "c.install_id")
-            .innerJoin("catalog_item_versions as v", (j) => j.onRef("v.item_id", "=", "a.item_id").onRef("v.version", "=", "a.version"))
-            .innerJoin("catalog_items as i", "i.id", "a.item_id")
-            .select(["i.name", "v.manifest"])
-            .where("c.kind", "=", "plugin")
-            .where("c.ref", "=", installId)
-            .where("a.org_id", "=", orgId)
-            .where("a.status", "<>", "failed")
-            .execute();
-        for (const p of parents) {
-            const range = p.manifest.dependencies?.find((x) => x.name === name)?.version;
-            if (range !== undefined && !satisfiesRange(to.version, range)) {
-                throw targetInvalid(`Plugin ${p.name} installed in this organization depends on ${name}@${range}, which version ${to.version} does not satisfy`, [{ reason: "dependent_range", dependent: p.name, range, version: to.version }]);
+            else {
+                if (target !== null)
+                    throw stale();
+                extension = null;
             }
         }
-        const ledger = await ledgerOf(db, installId);
-        const components = [];
-        // Extension
-        let extension = null;
-        let extensionConfig = false;
-        if (from.manifest.extension || to.manifest.extension) {
-            const change = !from.manifest.extension
-                ? "added"
-                : !to.manifest.extension
-                    ? "removed"
-                    : from.extension_sha256 !== to.extension_sha256 ||
-                        from.manifest.extension.manifest.version !== to.manifest.extension.manifest.version
-                        ? "changed"
-                        : "unchanged";
-            extension = { change, name };
-            if (change === "added") {
-                await this.installer.planExtension(orgId, to.manifest);
-                extensionConfig = !(await isExtensionEnabled(db, orgId, name));
-            }
-            components.push({
-                kind: "extension",
-                ref: name,
-                change,
-                ...(change === "changed" && {
-                    detail: `${from.manifest.extension?.manifest.version} -> ${to.manifest.extension?.manifest.version}`,
-                }),
-            });
+        else {
+            extension = target && {
+                ...target,
+                needsApproval: target.sha256 !== null && (await this.needsApproval(name, target.sha256)),
+                orgs: [],
+            };
         }
-        // Dependencies (by plugin name)
-        const resolved = await resolveDependencies(db, to.manifest);
-        const childIds = ledger.filter((l) => l.kind === "plugin").map((l) => l.ref);
-        const children = childIds.length === 0
-            ? []
-            : await db
-                .selectFrom("plugin_installs as a")
-                .innerJoin("catalog_items as i", "i.id", "a.item_id")
-                .select(["a.id", "a.version", "i.name"])
-                .where("a.id", "in", childIds)
-                .execute();
-        const childOf = (n) => {
-            const c = children.find((x) => x.name === n);
-            const l = c && ledger.find((x) => x.kind === "plugin" && x.ref === c.id);
-            return c && l ? { installId: c.id, version: c.version, ledger: l } : undefined;
-        };
-        const dependencies = [];
-        const fromDeps = from.manifest.dependencies ?? [];
-        for (const r of resolved) {
-            const before = fromDeps.find((x) => x.name === r.name);
-            const child = childOf(r.name);
-            if (before && child) {
-                const change = before.version === r.range ? "unchanged" : "changed";
-                if (change === "changed" && !satisfiesRange(child.version, r.range)) {
-                    throw new ApiError("catalog.dependency_unresolved", `Dependency ${r.name}@${r.range} cannot be resolved: this organization has version ${child.version} installed; upgrade it first`, [{ dependency: r.name, range: r.range }]);
-                }
-                dependencies.push({
-                    name: r.name,
-                    change,
-                    range: r.range,
-                    fromRange: before.version,
-                    resolved: r,
-                    child,
-                });
+        const contents = o.pre?.contents ?? (await this.readContents(to));
+        const dependencies = await this.checkDependents(name, to);
+        // The platform's components of the plugin and the target's
+        const live = await this.liveComponents(itemId);
+        const components = [];
+        const suggest = new Map();
+        const direction = (fromVersion) => fromVersion === null || compareVersions(to.version, fromVersion) >= 0
+            ? "upgrade"
+            : "downgrade";
+        const added = (kind, n) => ({
+            kind,
+            id: null,
+            name: n,
+            change: "added",
+            from: null,
+            to: to.version,
+            updatedOnOwn: false,
+            ownScope: false,
+            pinnedOrgs: [],
+        });
+        // Skills (by name, by their files' digest)
+        const toSkills = contents.skillNames.map((n, i) => {
+            const entry = (to.manifest.skills ?? [])[i];
+            return {
+                name: n,
+                digest: dirDigest(to, packagePath(entry?.path)),
+                pinned: entry?.pinned === true,
+            };
+        });
+        for (const s of toSkills) {
+            const l = live.skills.find((x) => x.name === s.name);
+            if (!l) {
+                components.push(added("skill", s.name));
                 continue;
             }
-            // New (or its install was not recorded): installed by the install flow
-            const live = await this.installer.liveDependency(db, orgId, r);
-            dependencies.push({
-                name: r.name,
-                change: "added",
-                range: r.range,
-                resolved: r,
-                plan: live !== undefined
-                    ? null
-                    : await this.installer.plan(orgId, actor, r.itemId, r.version, input === null ? null : {}, `dependencies.${r.name}.`, itemId),
+            const same = skillFilesDigest(l.manifest.files) === s.digest;
+            if (same && l.suggestPinned !== s.pinned)
+                suggest.set(l.id, s.pinned);
+            components.push({
+                kind: "skill",
+                id: l.id,
+                name: s.name,
+                change: same ? "same" : direction(l.catalogVersion),
+                from: l.catalogVersion,
+                to: to.version,
+                updatedOnOwn: l.updatedOnOwn,
+                ownScope: l.ownScope,
+                pinnedOrgs: [],
             });
         }
-        for (const before of fromDeps) {
-            if (resolved.some((r) => r.name === before.name))
+        for (const l of live.skills) {
+            if (toSkills.some((s) => s.name === l.name))
                 continue;
-            const child = childOf(before.name);
-            dependencies.push({
-                name: before.name,
+            components.push({
+                kind: "skill",
+                id: l.id,
+                name: l.name,
                 change: "removed",
-                fromRange: before.version,
-                ...(child && { child }),
+                from: l.catalogVersion,
+                to: null,
+                updatedOnOwn: l.updatedOnOwn,
+                ownScope: l.ownScope,
+                pinnedOrgs: [],
             });
         }
-        for (const dep of dependencies) {
+        // Agent templates (by name, canonical definition)
+        const toAgents = contents.agents;
+        for (const a of toAgents) {
+            const l = live.agentTemplates.find((x) => x.name === a.template.name);
+            if (!l) {
+                components.push(added("agent_template", a.template.name));
+                continue;
+            }
+            const same = canonicalJson(l.definition) === canonicalJson(a.template);
             components.push({
-                kind: "plugin",
-                ref: dep.name,
-                change: dep.change,
-                ...(dep.change === "changed" && { detail: `${dep.fromRange} -> ${dep.range}` }),
-                ...(dep.change === "added" && {
-                    detail: dep.plan === null ? "already installed" : `installs ${dep.resolved?.version}`,
-                }),
-            });
-        }
-        // Skills (by name)
-        const fromNames = await catalogSkillNames(this.storage, from, from.manifest);
-        const toNames = await catalogSkillNames(this.storage, to, to.manifest);
-        const dirOf = (m, i) => packagePath((m.skills ?? [])[i]?.path);
-        const fromSkills = new Map(fromNames.map((n, i) => [n, dirOf(from.manifest, i)]));
-        const toSkills = new Map(toNames.map((n, i) => [n, dirOf(to.manifest, i)]));
-        const toPinned = new Set(toNames.filter((_, i) => (to.manifest.skills ?? [])[i]?.pinned === true));
-        const skillRefs = ledger.filter((l) => l.kind === "skill").map((l) => l.ref);
-        const liveSkills = skillRefs.length === 0
-            ? []
-            : await db
-                .selectFrom("skills")
-                .select(["id", "name"])
-                .where("id", "in", skillRefs)
-                .where("org_id", "=", orgId)
-                .where("deleted_at", "is", null)
-                .execute();
-        const ledgerOfSkill = (n) => {
-            const s = liveSkills.find((x) => x.name === n);
-            return s && ledger.find((l) => l.kind === "skill" && l.ref === s.id);
-        };
-        const skills = [];
-        for (const [n, dir] of toSkills) {
-            const before = fromSkills.get(n);
-            const l = ledgerOfSkill(n);
-            const change = before === undefined
-                ? "added"
-                : dirDigest(from, before) === dirDigest(to, dir)
-                    ? "unchanged"
-                    : "changed";
-            skills.push({
-                name: n,
-                change,
-                dir,
-                suggestPinned: toPinned.has(n),
-                ...(l && { ledger: l }),
+                kind: "agent_template",
+                id: l.id,
+                name: l.name,
+                change: same ? "same" : direction(l.catalogVersion),
+                from: l.catalogVersion,
+                to: to.version,
+                updatedOnOwn: l.updatedOnOwn,
+                ownScope: l.ownScope,
+                pinnedOrgs: [],
             });
         }
-        for (const n of fromSkills.keys()) {
-            if (toSkills.has(n))
+        for (const l of live.agentTemplates) {
+            if (toAgents.some((a) => a.template.name === l.name))
                 continue;
-            const l = ledgerOfSkill(n);
-            skills.push({ name: n, change: "removed", ...(l && { ledger: l }) });
-        }
-        for (const s of skills)
-            components.push({ kind: "skill", ref: s.name, change: s.change });
-        // The same skill conflict check as an install (spec §9.2)
-        const conflicts = await planSkillConflicts(db, orgId, {
-            itemId,
-            name,
-            version: to.version,
-            skillNames: toNames,
-            dependencies: dependencies
-                .filter((x) => x.change === "added")
-                .map((x) => ({ plan: x.plan ?? null })),
-        });
-        if (conflicts.length > 0)
-            throw skillConflictError(conflicts);
-        // Agent templates (by name; phase C)
-        const fromAgents = await readCatalogAgentTemplates(this.storage, from);
-        const toAgents = await readCatalogAgentTemplates(this.storage, to);
-        const templateRefs = ledger.filter((l) => l.kind === "agent_template").map((l) => l.ref);
-        const liveTemplates = templateRefs.length === 0
-            ? []
-            : await db
-                .selectFrom("agent_templates")
-                .select(["id", "name"])
-                .where("id", "in", templateRefs)
-                .where("org_id", "=", orgId)
-                .where("deleted_at", "is", null)
-                .execute();
-        const ledgerOfTemplate = (n) => {
-            const r = liveTemplates.find((x) => x.name === n);
-            return r && ledger.find((l) => l.kind === "agent_template" && l.ref === r.id);
-        };
-        const agentTemplates = [];
-        for (const a of toAgents) {
-            const n = a.template.name;
-            const before = fromAgents.find((x) => x.template.name === n);
-            const l = ledgerOfTemplate(n);
-            const change = before === undefined
-                ? "added"
-                : canonicalJson(before.template) === canonicalJson(a.template)
-                    ? "unchanged"
-                    : "changed";
-            agentTemplates.push({ name: n, change, template: a.template, ...(l && { ledger: l }) });
-        }
-        for (const a of fromAgents) {
-            const n = a.template.name;
-            if (toAgents.some((x) => x.template.name === n))
-                continue;
-            const l = ledgerOfTemplate(n);
-            agentTemplates.push({ name: n, change: "removed", ...(l && { ledger: l }) });
-        }
-        for (const a of agentTemplates) {
-            components.push({ kind: "agent_template", ref: a.name, change: a.change });
+            components.push({
+                kind: "agent_template",
+                id: l.id,
+                name: l.name,
+                change: "removed",
+                from: l.catalogVersion,
+                to: null,
+                updatedOnOwn: l.updatedOnOwn,
+                ownScope: l.ownScope,
+                pinnedOrgs: [],
+            });
         }
-        // Connector templates (by id)
-        const fromTemplates = await readCatalogTemplates(this.storage, from);
-        const toTemplates = await readCatalogTemplates(this.storage, to);
-        // The install's connectors by template; a dropped one (kept only for the agents using it) counts
-        // only while its connector is live, so a template the target brings back maps onto it
-        const connectorRows = ledger.filter((l) => l.kind === "connector" && l.template_id !== null);
-        const liveConnectors = connectorRows.length === 0
-            ? []
-            : await db
-                .selectFrom("connectors")
-                .select(["id", "connector", "endpoint", "auth"])
-                .where("id", "in", connectorRows.map((l) => l.ref))
-                .where("org_id", "=", orgId)
-                .where("deleted_at", "is", null)
-                .execute();
-        const connectorOf = (templateId) => {
-            const rows = connectorRows.filter((x) => x.template_id === templateId);
-            const l = rows.find((x) => !x.dropped) ??
-                rows.find((x) => liveConnectors.some((c) => c.id === x.ref));
-            const c = l && liveConnectors.find((x) => x.id === l.ref);
-            return {
-                ...(l && { ledger: l }),
-                ...(c && {
-                    connector: {
-                        id: c.id,
-                        connector: c.connector,
-                        endpoint: c.endpoint,
-                        auth: c.auth,
-                    },
-                }),
-            };
-        };
+        // Connector templates (by id, canonical file) and the connectors made from them
+        const toTemplates = contents.templates;
         const deps = this.installer.templateDeps();
-        const templates = [];
+        const connectors = [];
+        const shippedOff = (f) => f.defaultEnabled === false;
+        /** Templates whose `defaultEnabled` the target flips: id -> shipped off, and the platform id. */
+        const flipped = new Map();
+        const flippedIds = new Map();
         for (const ct of toTemplates) {
-            const problem = templatePluginProblem(deps, ct.file.template);
-            const before = fromTemplates.find((x) => x.id === ct.id);
-            const mapped = connectorOf(ct.id);
-            if (!before && mapped.ledger?.dropped && mapped.connector) {
-                // Back in the plugin (an earlier upgrade dropped it, its connector was kept): the kept
-                // connector is updated to the template, not created again (its slug would be taken)
+            const l = live.templates.find((x) => x.name === ct.id);
+            if (!l) {
+                const problem = templatePluginProblem(deps, ct.file.template);
                 if (problem !== undefined)
                     throw new ApiError("catalog.not_deployed", problem);
-                if (mapped.connector.connector !== ct.file.template.connector) {
-                    throw targetInvalid(`Connector template ${ct.id} comes back for another connector (${ct.file.template.plugin} "${ct.file.template.connector}"); uninstall the plugin and install the new version instead`, [
-                        {
-                            reason: "template_connector",
-                            template: ct.id,
-                            plugin: ct.file.template.plugin,
-                            connector: ct.file.template.connector,
-                        },
-                    ]);
-                }
-                const credentialsChanged = credentialKey(mapped.connector.auth) !==
-                    credentialKey(ct.file.template.auth);
-                templates.push({
-                    id: ct.id,
-                    change: "changed",
-                    target: ct.file,
-                    ...mapped,
-                    credentialsChanged,
-                });
+                components.push(added("connector_template", ct.id));
                 continue;
             }
-            if (!before) {
-                if (problem !== undefined)
-                    throw new ApiError("catalog.not_deployed", problem);
-                templates.push({ id: ct.id, change: "added", target: ct.file, credentialsChanged: false });
+            const same = canonicalJson(l.file) === canonicalJson(ct.file);
+            components.push({
+                kind: "connector_template",
+                id: l.id,
+                name: ct.id,
+                change: same ? "same" : direction(l.version),
+                from: l.version,
+                to: to.version,
+                updatedOnOwn: false,
+                ownScope: l.ownScope,
+                pinnedOrgs: [],
+            });
+            if (same)
                 continue;
+            if (shippedOff(l.file) !== shippedOff(ct.file)) {
+                flipped.set(ct.id, shippedOff(ct.file));
+                flippedIds.set(ct.id, l.id);
             }
-            const change = canonicalJson(before.file) === canonicalJson(ct.file) ? "unchanged" : "changed";
-            if (change === "changed") {
-                if (before.file.template.plugin !== ct.file.template.plugin ||
-                    before.file.template.connector !== ct.file.template.connector) {
-                    throw targetInvalid(`Connector template ${ct.id} moves to another connector (${ct.file.template.plugin} "${ct.file.template.connector}"); uninstall the plugin and install the new version instead`, [
-                        {
-                            reason: "template_connector",
-                            template: ct.id,
-                            plugin: ct.file.template.plugin,
-                            connector: ct.file.template.connector,
-                        },
-                    ]);
-                }
-                if (problem !== undefined && mapped.connector) {
+            const before = l.file.template;
+            const after = ct.file.template;
+            if (before.plugin !== after.plugin || before.connector !== after.connector) {
+                throw targetInvalid(`Connector template ${ct.id} moves to another connector (${after.plugin} "${after.connector}"); remove the plugin and import the new version as a new plugin instead`, [
+                    {
+                        reason: "template_connector",
+                        template: ct.id,
+                        plugin: after.plugin,
+                        connector: after.connector,
+                    },
+                ]);
+            }
+            const made = await db
+                .selectFrom("connectors")
+                .select(["id", "org_id", "name", "connector", "endpoint", "auth"])
+                .where("platform_template_id", "=", l.id)
+                .where("deleted_at", "is", null)
+                .orderBy("org_id")
+                .orderBy("id")
+                .execute();
+            if (made.length > 0) {
+                const problem = templatePluginProblem(deps, after);
+                if (problem !== undefined)
                     throw new ApiError("catalog.not_deployed", problem);
-                }
             }
-            const credentialsChanged = change === "changed" &&
-                mapped.connector !== undefined &&
-                credentialKey(mapped.connector.auth) !==
-                    credentialKey(ct.file.template.auth);
-            templates.push({ id: ct.id, change, target: ct.file, ...mapped, credentialsChanged });
+            for (const c of made) {
+                connectors.push({
+                    orgId: c.org_id,
+                    id: c.id,
+                    name: c.name,
+                    connector: c.connector,
+                    endpoint: c.endpoint,
+                    templateId: ct.id,
+                    file: ct.file,
+                    credentialsReset: credentialKey(c.auth) !==
+                        credentialKey(after.auth),
+                });
+            }
         }
-        for (const ct of fromTemplates) {
-            if (toTemplates.some((x) => x.id === ct.id))
+        for (const l of live.templates) {
+            if (toTemplates.some((x) => x.id === l.name))
                 continue;
-            templates.push({
-                id: ct.id,
+            components.push({
+                kind: "connector_template",
+                id: l.id,
+                name: l.name,
                 change: "removed",
-                ...connectorOf(ct.id),
-                credentialsChanged: false,
+                from: l.version,
+                to: null,
+                updatedOnOwn: false,
+                ownScope: l.ownScope,
+                pinnedOrgs: [],
             });
         }
-        for (const c of templates) {
+        // Themes (by id, canonical definition and their assets' digest)
+        const toThemes = contents.themes;
+        for (const th of toThemes) {
+            const l = live.themes.find((x) => x.name === th.id);
+            if (!l) {
+                components.push(added("theme", th.id));
+                continue;
+            }
+            const same = canonicalJson(l.definition) === canonicalJson(th.theme) &&
+                l.assetsDigest === th.assetsDigest;
             components.push({
-                kind: "connector",
-                ref: c.id,
-                change: c.change,
-                ...(c.credentialsChanged && { detail: "credentials change" }),
-                ...(c.change !== "added" &&
-                    c.change !== "removed" &&
-                    !c.connector && { detail: "no connector in this organization" }),
+                kind: "theme",
+                id: l.id,
+                name: th.id,
+                change: same ? "same" : direction(l.catalogVersion),
+                from: l.catalogVersion,
+                to: to.version,
+                updatedOnOwn: false,
+                ownScope: l.ownScope,
+                pinnedOrgs: [],
             });
         }
-        const inputs = {
-            connectors: templates.filter((c) => c.change === "added").map((c) => c.id),
-            credentialsChanged: templates.filter((c) => c.credentialsChanged).map((c) => c.id),
-            extensionConfig,
-        };
-        // The inputs (as at install), when given
-        const creates = new Map();
-        const updates = new Map();
-        if (input !== null) {
-            for (const k of Object.keys(input.connectors ?? {})) {
-                if (!inputs.connectors.includes(k) && !inputs.credentialsChanged.includes(k)) {
-                    throw fail(`connectors.${k}`, "This upgrade takes no input for this connector template (only added templates and changed credentials)");
-                }
+        for (const l of live.themes) {
+            if (toThemes.some((x) => x.id === l.name))
+                continue;
+            components.push({
+                kind: "theme",
+                id: l.id,
+                name: l.name,
+                change: "removed",
+                from: l.catalogVersion,
+                to: null,
+                updatedOnOwn: false,
+                ownScope: l.ownScope,
+                pinnedOrgs: [],
+            });
+        }
+        // The orgs where the plugin is on (a live install; builtin: every org)
+        const onOrgs = await this.pluginOrgs(itemId, item.builtin);
+        if (extension)
+            extension = { ...extension, orgs: onOrgs };
+        // Rule 10: an added skill must not take a name already used where the plugin is on
+        const conflicts = [];
+        for (const c of components) {
+            if (c.kind !== "skill" || c.change !== "added")
+                continue;
+            for (const orgId of onOrgs) {
+                const ids = [
+                    ...(await clashingOrgSkills(db, orgId, { id: "", itemId }, c.name)),
+                    ...(await clashingPlatformSkills(db, orgId, { id: "" }, c.name)).map((x) => x.id),
+                ];
+                if (ids.length > 0)
+                    conflicts.push({ skill: c.name, orgId, conflicts: ids.sort() });
             }
-            if (input.extensionConfig !== undefined && !inputs.extensionConfig) {
-                throw fail("extensionConfig", "This upgrade does not enable the plugin's extension");
+        }
+        if (conflicts.length > 0) {
+            throw new ApiError("plugin.skill_conflict", `The update adds skills whose names organizations already use where the plugin is on (${[...new Set(conflicts.map((c) => c.skill))].join(", ")}); remove or rename those skills first`, conflicts);
+        }
+        // Themes spec §7: an update never removes the platform default theme; rule 10 (§6): an added
+        // theme must not take an id already on where the plugin is on
+        const removedThemes = components
+            .filter((c) => c.kind === "theme" && c.change === "removed" && c.id !== null)
+            .map((c) => c.id);
+        await assertNotPlatformDefault(db, removedThemes, () => "gone");
+        const themeConflicts = [];
+        for (const c of components) {
+            if (c.kind !== "theme" || c.change !== "added")
+                continue;
+            for (const orgId of onOrgs) {
+                const clash = await themeIdClashes(db, orgId, null, c.name);
+                if (clash.length > 0) {
+                    themeConflicts.push({
+                        theme: c.name,
+                        orgId,
+                        themes: clash.map((x) => x.id),
+                        plugins: clash.map((x) => x.plugin ?? "platform"),
+                    });
+                }
             }
-            for (const c of templates) {
-                if (c.change === "added") {
-                    creates.set(c.id, this.installer.planConnector(actor, { itemId, version: to.version, name }, { id: c.id, file: c.target }, input, "", undefined));
+        }
+        if (themeConflicts.length > 0) {
+            throw new ApiError("theme.id_taken", `The update adds themes whose ids are already on in organizations where the plugin is on (${[...new Set(themeConflicts.map((c) => c.theme))].join(", ")}); switch those themes off there first`, themeConflicts);
+        }
+        const themes = await this.themesLost(removedThemes);
+        // Pinned copies (in orgs where the component is on) and removed components agents use
+        for (const kind of ["skill", "agent_template"]) {
+            const mine = components.filter((c) => c.kind === kind && c.id !== null);
+            if (mine.length === 0)
+                continue;
+            const pins = kind === "skill"
+                ? await db
+                    .selectFrom("skills")
+                    .select(["org_id", "platform_skill_id as platform_id"])
+                    .where("platform_skill_id", "in", mine.map((c) => c.id))
+                    .where("pinned_version", "is not", null)
+                    .where("deleted_at", "is", null)
+                    .execute()
+                : await db
+                    .selectFrom("agent_templates")
+                    .select(["org_id", "platform_template_id as platform_id"])
+                    .where("platform_template_id", "in", mine.map((c) => c.id))
+                    .where("pinned_version", "is not", null)
+                    .where("deleted_at", "is", null)
+                    .execute();
+            const facts = mine.map((c) => {
+                const l = (kind === "skill" ? live.skills : live.agentTemplates).find((x) => x.id === c.id);
+                return {
+                    id: c.id,
+                    itemId,
+                    scopeMode: l?.scopeMode ?? "follow",
+                    scope: l?.scope ?? "optional",
+                    disabled: l?.disabled ?? false,
+                };
+            });
+            const st = await loadScopeState(db, kind, facts);
+            for (const c of mine) {
+                const f = facts.find((x) => x.id === c.id);
+                if (!f)
                     continue;
-                }
-                if (c.change !== "changed" || !c.connector || !c.target)
+                const orgsPinned = [
+                    ...new Set(pins.filter((p) => p.platform_id === c.id).map((p) => p.org_id)),
+                ];
+                c.pinnedOrgs = orgsPinned
+                    .filter((orgId) => componentOn(f, pluginFactsOf(st, itemId, orgId), listedIn(st, f.id, orgId), switchOf(st, f.id, orgId)))
+                    .sort();
+                if (c.change !== "removed")
                     continue;
-                updates.set(c.id, this.templateUpdate(itemId, to.version, c, input));
+                const kept = [];
+                for (const orgId of await this.liveOrgs()) {
+                    const agents = await agentsUsing(db, orgId, kind, [c.id]);
+                    if (agents.length > 0) {
+                        kept.push({ orgId, agents: agents.map((a) => ({ id: a.id, name: a.name })) });
+                    }
+                }
+                if (kept.length > 0)
+                    c.kept = kept;
             }
         }
-        const actions = new Set([
-            ...requiredActions(from.manifest),
-            ...requiredActions(to.manifest),
-        ]);
-        for (const dep of dependencies)
-            if (dep.plan)
-                for (const a of planActions(dep.plan))
-                    actions.add(a);
-        const removedDeps = dependencies.filter((x) => x.change === "removed" && x.child);
-        if (removedDeps.length > 0) {
-            const manifests = await 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("v.manifest")
-                .where("a.id", "in", removedDeps.map((x) => x.child?.installId))
-                .execute();
-            for (const m of manifests)
-                for (const a of requiredActions(m.manifest))
-                    actions.add(a);
+        // The org connectors: changed templates' connectors, templates turned on (needing input) or off
+        const addedTemplates = components
+            .filter((c) => c.kind === "connector_template" && c.change === "added")
+            .map((c) => c.name)
+            // an added template shipped off is on nowhere (no org can have switched it on yet)
+            .filter((id) => {
+            const f = toTemplates.find((x) => x.id === id)?.file;
+            return item.builtin || f === undefined || !shippedOff(f);
+        });
+        const byOrg = new Map();
+        const entry = (orgId) => {
+            const e = byOrg.get(orgId) ?? { orgId, connectors: [], needsConfig: [] };
+            byOrg.set(orgId, e);
+            return e;
+        };
+        for (const c of connectors) {
+            entry(c.orgId).connectors.push({
+                id: c.id,
+                name: c.name,
+                templateId: c.templateId,
+                credentialsReset: c.credentialsReset,
+            });
         }
-        const lh = ledgerHash(ledger);
+        if (addedTemplates.length > 0) {
+            for (const orgId of onOrgs) {
+                const on = await connectorTemplatesOn(db, orgId, itemId, addedTemplates);
+                if (on.size > 0)
+                    entry(orgId).needsConfig.push(...on);
+            }
+        }
+        if (flipped.size > 0) {
+            const ids = [...flipped.keys()].sort();
+            for (const orgId of onOrgs) {
+                const before = await connectorTemplatesOn(db, orgId, itemId, ids);
+                const after = await connectorTemplatesOn(db, orgId, itemId, ids, flipped);
+                for (const id of ids) {
+                    const platformId = flippedIds.get(id);
+                    if (after.has(id) && !before.has(id)) {
+                        // connectors already made from it (it was on before) need no input
+                        if ((await connectorsMadeFrom(db, orgId, platformId)) === 0) {
+                            entry(orgId).needsConfig.push(id);
+                        }
+                    }
+                    else if (before.has(id) && !after.has(id)) {
+                        const agents = await agentsUsing(db, orgId, "connector_template", [platformId]);
+                        const e = entry(orgId);
+                        e.turnedOff = [
+                            ...(e.turnedOff ?? []),
+                            {
+                                templateId: id,
+                                agents: agents.map((a) => ({ id: a.id, name: a.name })),
+                                connectorsKept: await connectorsMadeFrom(db, orgId, platformId),
+                            },
+                        ];
+                    }
+                }
+            }
+        }
+        const connectorOrgs = [...byOrg.values()]
+            .map((e) => ({
+            ...e,
+            needsConfig: e.needsConfig.sort(),
+            connectors: e.connectors.sort((a, b) => `${a.templateId}\0${a.id}`.localeCompare(`${b.templateId}\0${b.id}`)),
+        }))
+            .sort((a, b) => a.orgId.localeCompare(b.orgId));
+        components.sort((a, b) => KIND_ORDER[a.kind] - KIND_ORDER[b.kind] || a.name.localeCompare(b.name));
         const diffHash = sha256(canonicalJson({
-            installId,
-            from: from.version,
+            itemId,
+            from,
             to: to.version,
-            fromFiles: filesDigest(from),
-            toFiles: filesDigest(to),
-            ledger: lh,
+            manifest: to.manifest,
+            files: filesDigest(to),
+            // `needsApproval` is shown only: it does not change what the confirm does
+            extension: extension && {
+                from: extension.from,
+                to: extension.to,
+                orgs: extension.orgs,
+                sha256: extension.sha256,
+            },
             components,
-            inputs,
+            connectors: connectors.map((c) => ({
+                id: c.id,
+                endpoint: c.endpoint,
+                reset: c.credentialsReset,
+            })),
+            connectorOrgs,
+            // only when present: a diff without themes keeps the hash it had before themes
+            ...(themes !== undefined && { themes }),
         }));
         return {
-            installId,
             itemId,
             name,
             from,
             to,
-            ledger,
+            components,
             extension,
-            skills,
-            agentTemplates,
-            templates,
+            connectors,
+            connectorOrgs,
+            ...(themes !== undefined && { themes }),
+            suggest,
+            contents,
             dependencies,
-            components,
-            inputs,
             diffHash,
-            ledgerHash: lh,
-            actions: [...actions],
-            creates,
-            updates,
         };
     }
     /**
-     * The update of a changed template's connector: the new endpoint preset with the org's values at
-     * the editable paths, the new auth preset and policies; credentials only when the auth method or
-     * the credentials it needs changed (then the input must give what the template needs).
+     * The target's skill names, agent templates, connector templates and themes, from object storage
+     * (a theme failing its checks -> 400 `theme.invalid`, themes spec §6).
      */
-    templateUpdate(itemId, version, c, input) {
-        const template = c.target.template;
-        const connector = c.connector;
-        const path = `connectors.${c.id}`;
-        const given = input.connectors?.[c.id];
-        if (given !== undefined) {
-            for (const k of ["name", "slug", "endpoint"]) {
-                if (given[k] !== undefined) {
-                    throw fail(`${path}.${k}`, "An existing connector keeps its name, slug and endpoint fields");
-                }
+    async readContents(to) {
+        return {
+            skillNames: await catalogSkillNames(this.storage, to, to.manifest),
+            agents: await readCatalogAgentTemplates(this.storage, to),
+            templates: await readCatalogTemplates(this.storage, to),
+            themes: await readCatalogThemes(this.storage, to),
+        };
+    }
+    /**
+     * Whether the target's extension package asks for permissions the approved snapshot does not
+     * cover (no snapshot, or a blocking addition): it then loads only once approved (§7.4).
+     */
+    async needsApproval(name, sha) {
+        if (this.config.get().extensionPermissions.autoApprove)
+            return false;
+        const pkg = await readExtensionPackage(await this.blobs.get(sha), {
+            maxBytes: this.config.get().packages.maxBytes,
+            hostSdkVersion: SDK_VERSION,
+        });
+        const snap = await this.db
+            .selectFrom("extension_permission_snapshots")
+            .select("permissions")
+            .where("plugin", "=", name)
+            .executeTakeFirst();
+        if (!snap)
+            return true;
+        const { added } = diffPermissions(snap.permissions, permissionSetOfPackage(pkg));
+        return blockingKeys(added).length > 0;
+    }
+    /**
+     * The deployment's extension step: none when the target carries the extension the deployment
+     * runs; a version without the extension the deployment runs for the plugin is refused, except
+     * for an owner update (`allowRemove`, ruling P3-12': removing code runs none), which removes an
+     * installed one; a move of a config-declared extension is refused.
+     */
+    async extensionTarget(name, from, to, allowRemove = false) {
+        const want = to.manifest.extension;
+        const row = await this.db
+            .selectFrom("extension_installs")
+            .select(["sha256", "version"])
+            .where("name", "=", name)
+            .executeTakeFirst();
+        // Only an extension declared in the startup config runs without an install record; one this
+        // replica still has loaded after its uninstall (until its reconcile) does not count
+        const declared = this.registry.declared().get(name) === "config";
+        const loaded = declared ? this.registry.manifests().find((m) => m.name === name) : undefined;
+        if (!want) {
+            if (allowRemove && from?.manifest.extension && row && !declared) {
+                return { from: row.version, to: null, sha256: null, previous: row.sha256 };
             }
+            if (from?.manifest.extension && (row || declared)) {
+                throw targetInvalid(`Version ${to.version} of plugin ${name} has no extension, but the deployment runs it; uninstall the extension first`, [{ reason: "extension_removed", version: to.version }]);
+            }
+            return null;
         }
-        const endpoint = structuredClone(template.endpoint);
-        for (const e of template.editableEndpoint ?? []) {
-            const v = getPath(connector.endpoint, e);
-            if (v !== undefined)
-                setPath(endpoint, e, v);
+        if (row) {
+            if (row.sha256 === to.extension_sha256)
+                return null;
         }
-        const auth = template.auth;
-        const oauth = auth.type === "oauth_code" || auth.type === "oauth_client";
-        if (c.credentialsChanged) {
-            const missing = missingTemplateInput(template, given, { personalCredential: false });
-            if (missing !== undefined) {
-                throw fail(`${path}.${missing}`, `The auth method of this connector template changed; it needs ${missing === "client" ? "an OAuth client" : "an org credential"}`);
-            }
-            if (oauth && given?.credential !== undefined) {
-                throw fail(`${path}.credential`, "This connector uses OAuth; provide client instead");
-            }
-            if (!oauth && given?.client !== undefined) {
-                throw fail(`${path}.client`, "This connector does not use OAuth; provide credential instead");
-            }
+        else if (declared) {
+            if (loaded?.version === want.manifest.version)
+                return null;
+            throw targetInvalid(`The extension of plugin ${name} is declared in the startup config at version ${loaded?.version ?? "(not loaded)"}; it cannot be moved to ${want.manifest.version} by an update`, [{ reason: "config_extension", deploymentVersion: loaded?.version ?? null }]);
+        }
+        if (to.extension_sha256 === null) {
+            throw targetInvalid(`Version ${to.version} of plugin ${name} has no extension package`, [
+                { reason: "extension_package", version: to.version },
+            ]);
         }
-        const credential = oauth ? given?.client : given?.credential;
         return {
-            endpoint,
-            auth,
-            template: {
-                itemId,
-                version,
-                templateId: c.id,
-                ...(template.defaultToolPolicies !== undefined && {
-                    defaultToolPolicies: template.defaultToolPolicies,
-                }),
-            },
-            resetCredentials: c.credentialsChanged,
-            ...(c.credentialsChanged && credential !== undefined && { credential }),
+            from: row?.version ?? null,
+            to: want.manifest.version,
+            sha256: to.extension_sha256,
+            previous: row?.sha256 ?? null,
         };
     }
+    /**
+     * Other platform plugins depending on this one must accept the target (their platform version's
+     * dependency range); returns the catalog items of the target's own dependencies (their scope
+     * sync is enqueued after the update: rule 9).
+     */
+    async checkDependents(name, to) {
+        const rows = await this.db
+            .selectFrom("catalog_items as i")
+            .innerJoin("catalog_item_versions as v", (j) => j
+            .onRef("v.item_id", "=", "i.id")
+            .on(sql `v.version`, "=", sql `coalesce(i.platform_synced_version, i.latest_version)`))
+            .select(["i.id", "i.name", "v.manifest"])
+            .where("i.deleted_at", "is", null)
+            .execute();
+        for (const r of rows) {
+            if (r.name === name)
+                continue;
+            const range = r.manifest.dependencies?.find((d) => d.name === name)?.version;
+            if (range !== undefined && !satisfiesRange(to.version, range)) {
+                throw targetInvalid(`Plugin ${r.name} depends on ${name}@${range}, which version ${to.version} does not satisfy`, [{ reason: "dependent_range", dependent: r.name, range, version: to.version }]);
+            }
+        }
+        const wanted = new Set((to.manifest.dependencies ?? []).map((d) => d.name));
+        return rows.filter((r) => wanted.has(r.name)).map((r) => r.id);
+    }
+    /** The plugin's live platform components with their current versions. */
+    async liveComponents(itemId) {
+        const db = this.db;
+        const skills = (await db
+            .selectFrom("platform_skills as p")
+            .innerJoin("platform_skill_versions as v", (j) => j.onRef("v.skill_id", "=", "p.id").onRef("v.version", "=", "p.current_version"))
+            .select([
+            "p.id",
+            "p.name",
+            "p.scope_mode",
+            "p.scope",
+            "p.disabled",
+            "v.manifest",
+            "v.catalog_version",
+            "v.updated_on_own",
+            "v.suggest_pinned",
+        ])
+            .where("p.catalog_item_id", "=", itemId)
+            .where("p.deleted_at", "is", null)
+            .execute()).map((r) => ({
+            id: r.id,
+            name: r.name,
+            scopeMode: r.scope_mode,
+            scope: r.scope,
+            disabled: r.disabled,
+            manifest: r.manifest,
+            catalogVersion: r.catalog_version,
+            updatedOnOwn: r.updated_on_own,
+            ownScope: r.scope_mode === "own",
+            suggestPinned: r.suggest_pinned,
+        }));
+        const agentTemplates = (await db
+            .selectFrom("platform_agent_templates as p")
+            .innerJoin("platform_agent_template_versions as v", (j) => j.onRef("v.template_id", "=", "p.id").onRef("v.version", "=", "p.current_version"))
+            .select([
+            "p.id",
+            "p.name",
+            "p.scope_mode",
+            "p.scope",
+            "p.disabled",
+            "v.definition",
+            "v.catalog_version",
+            "v.updated_on_own",
+        ])
+            .where("p.catalog_item_id", "=", itemId)
+            .where("p.deleted_at", "is", null)
+            .execute()).map((r) => ({
+            id: r.id,
+            name: r.name,
+            scopeMode: r.scope_mode,
+            scope: r.scope,
+            disabled: r.disabled,
+            definition: r.definition,
+            catalogVersion: r.catalog_version,
+            updatedOnOwn: r.updated_on_own,
+            ownScope: r.scope_mode === "own",
+        }));
+        const templates = (await db
+            .selectFrom("platform_connector_templates")
+            .select(["id", "template_id", "current_version", "file", "scope_mode"])
+            .where("catalog_item_id", "=", itemId)
+            .where("deleted_at", "is", null)
+            .execute()).map((r) => ({
+            id: r.id,
+            name: r.template_id,
+            version: r.current_version,
+            file: r.file,
+            ownScope: r.scope_mode === "own",
+        }));
+        const themes = (await db
+            .selectFrom("platform_themes as p")
+            .innerJoin("platform_theme_versions as v", (j) => j.onRef("v.theme_id", "=", "p.id").onRef("v.version", "=", "p.current_version"))
+            .leftJoin("catalog_item_versions as cv", (j) => j
+            .onRef("cv.item_id", "=", "p.catalog_item_id")
+            .onRef("cv.version", "=", "v.catalog_version"))
+            .select(["p.id", "p.name", "p.scope_mode", "v.definition", "v.catalog_version", "cv.files"])
+            .where("p.catalog_item_id", "=", itemId)
+            .where("p.deleted_at", "is", null)
+            .execute()).map((r) => ({
+            id: r.id,
+            name: r.name,
+            definition: r.definition,
+            catalogVersion: r.catalog_version,
+            // no recorded files (should not happen): never equal, the update writes a new version
+            assetsDigest: r.files === null ? null : themeAssetsDigest(r.files, r.definition),
+            ownScope: r.scope_mode === "own",
+        }));
+        return { skills, agentTemplates, templates, themes };
+    }
+    /** The `themes` block of the preview: the orgs each of the removed themes `ids` is on in. */
+    async themesLost(ids) {
+        if (ids.length === 0)
+            return undefined;
+        const comps = await loadComponents(this.db, "theme", { ids });
+        const st = await loadScopeState(this.db, "theme", comps);
+        const orgs = await this.liveOrgs();
+        const lost = new Map();
+        for (const c of comps) {
+            const on = orgs.filter((orgId) => componentOn(c, pluginFactsOf(st, c.itemId, orgId), listedIn(st, c.id, orgId), switchOf(st, c.id, orgId)));
+            lost.set(c.id, new Set(on));
+        }
+        return themesPreview(this.db, lost);
+    }
+    /** The orgs where the plugin is on: a live install (builtin: every live org). */
+    async pluginOrgs(itemId, builtin) {
+        if (builtin)
+            return this.liveOrgs();
+        const rows = await this.db
+            .selectFrom("plugin_installs as a")
+            .innerJoin("orgs as o", "o.id", "a.org_id")
+            .select("a.org_id")
+            .distinct()
+            .where("a.item_id", "=", itemId)
+            .where("a.status", "in", ["installing", "installed", "upgrading"])
+            .where("o.deleted_at", "is", null)
+            .orderBy("a.org_id")
+            .execute();
+        return rows.map((r) => r.org_id);
+    }
+    async liveOrgs() {
+        const rows = await this.db
+            .selectFrom("orgs")
+            .select("id")
+            .where("deleted_at", "is", null)
+            .orderBy("id")
+            .execute();
+        return rows.map((r) => r.id);
+    }
 };
 __decorate([
     Transactional()
-], PluginUpgrader.prototype, "authorizeActions", null);
-__decorate([
-    Transactional({ propagation: "requires_new" })
-], PluginUpgrader.prototype, "start", null);
-__decorate([
-    Transactional({ propagation: "requires_new" })
-], PluginUpgrader.prototype, "journalSkill", null);
-__decorate([
-    Transactional({ propagation: "requires_new" })
-], PluginUpgrader.prototype, "upgradeAgentTemplate", null);
-__decorate([
-    Transactional({ propagation: "requires_new" })
-], PluginUpgrader.prototype, "recordStep", null);
+], PlatformPluginUpdater.prototype, "authorizeOwner", null);
 __decorate([
     Transactional({ propagation: "requires_new" })
-], PluginUpgrader.prototype, "finish", null);
+], PlatformPluginUpdater.prototype, "auditFailure", null);
 __decorate([
     Transactional({ propagation: "requires_new" })
-], PluginUpgrader.prototype, "undoFailed", null);
-__decorate([
-    Transactional({ propagation: "requires_new" })
-], PluginUpgrader.prototype, "undoInterrupted", null);
-__decorate([
-    Transactional({ propagation: "mandatory" })
-], PluginUpgrader.prototype, "removeIn", null);
-PluginUpgrader = __decorate([
+], PlatformPluginUpdater.prototype, "commit", null);
+PlatformPluginUpdater = __decorate([
     Injectable(),
-    __param(0, Inject(PluginInstaller)),
-    __param(1, Inject(KernelDb)),
-    __param(2, Inject(OrgLock)),
-    __param(3, Inject(StorageService)),
-    __param(4, Inject(ExtensionRegistry)),
-    __param(5, Inject(SkillsService)),
-    __param(6, Inject(OrgExtensionConfigs)),
-    __param(7, Inject(CatalogRequestsService)),
-    __param(8, Inject(ConnectorsService)),
-    __param(9, Inject(KERNEL_LOGGER)),
-    __param(10, Inject(TransactionHost))
-], PluginUpgrader);
-export { PluginUpgrader };
-const cleanedUp = () => new ApiError("plugin.install_not_found", "The upgrade was cleaned up as interrupted while it was running");
-/** The install's ledger rows. */
-function ledgerOf(db, installId) {
-    return db
-        .selectFrom("plugin_install_components")
-        .select(["kind", "ref", "created", "skill_version", "template_id", "dropped"])
-        .where("install_id", "=", installId)
-        .orderBy("kind")
-        .orderBy("ref")
-        .execute();
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(TransactionHost)),
+    __param(2, Inject(SuperAdminLock)),
+    __param(3, Inject(CatalogItemLock)),
+    __param(4, Inject(OrgLock)),
+    __param(5, Inject(LockService)),
+    __param(6, Inject(StorageService)),
+    __param(7, Inject(ExtensionRegistry)),
+    __param(8, Inject(ExtensionAdminOps)),
+    __param(9, Inject(ExtensionBlobs)),
+    __param(10, Inject(KernelConfigService)),
+    __param(11, Inject(PlatformComponents)),
+    __param(12, Inject(PluginInstaller)),
+    __param(13, Inject(ConnectorsService)),
+    __param(14, Inject(PluginScopeSync)),
+    __param(15, Inject(KERNEL_LOGGER)),
+    __param(16, Inject(PluginGuides))
+], PlatformPluginUpdater);
+export { PlatformPluginUpdater };
+/** The preview of a diff (without `guideChanges`, which reads PG). */
+function previewOf(d) {
+    return {
+        itemId: d.itemId,
+        name: d.name,
+        from: d.from,
+        to: d.to.version,
+        components: d.components,
+        extension: extensionView(d.extension),
+        connectorOrgs: d.connectorOrgs,
+        ...(d.themes !== undefined && { themes: d.themes }),
+        diffHash: d.diffHash,
+    };
 }
-/** A fingerprint of the ledger (order independent). */
-function ledgerHash(rows) {
-    return sha256(rows
-        .map((r) => `${r.kind}\0${r.ref}\0${r.created}\0${r.skill_version}\0${r.template_id}\0${r.dropped}\n`)
-        .sort()
-        .join(""));
+/** The extension step as the preview and the result show it. */
+function extensionView(e) {
+    return e && { from: e.from, to: e.to, orgs: e.orgs, needsApproval: e.needsApproval };
 }