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

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

@@ -0,0 +1,1116 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { createHash } from "node:crypto";
+import { getQueueToken } from "@nestjs/bullmq";
+import { Inject, Injectable } from "@nestjs/common";
+import { sql } from "kysely";
+import { ApiError } from "../errors.js";
+import { ExtensionAdminOps } from "../extensions/admin-ops.js";
+import { ExtensionAdmin } from "../extensions/admin-view.js";
+import { ExtensionLifecycle } from "../extensions/lifecycle.js";
+import { PluginInstallLock } from "../extensions/locks.js";
+import { audit } from "../identity/audit.js";
+import { SuperAdminLock } from "../identity/super-admin.js";
+import { addOrgNotice, itemDisplayName, notifyItemShared } from "../inbox/org-notices.js";
+import { afterCommit } from "../infra/database/after-commit.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { Transactional } from "../infra/database/transactional.decorator.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { OrgLock } from "../orgs/org-lock.js";
+import { MAINTENANCE_QUEUE_NAME } from "../runtime/maintenance-queue.js";
+import { CatalogService } from "./catalog.service.js";
+import { assertOrgsExist, markVersionApplied } from "./catalog-items.js";
+import { nameConflictError } from "./component-scope.service.js";
+import { agentsUsing, COMPONENT_KINDS, componentOffered, componentOn, listedIn, loadComponents, loadScopeState, pluginFactsOf, skillNameClashes, switchOf, } from "./component-state.js";
+import { ownedPluginCleanupJob } from "./job-ids.js";
+import { assertNotAwaiting, assertOwnerListed, assertShareable, assertShareableTarget, itemRemovedError, newlySharedWith, ownerOf, ownersOf, PLATFORM_OWNER, packageOwner, pendingDigest, releaseExtensionClaim, } from "./ownership.js";
+import { PluginImport } from "./plugin-import.js";
+import { PluginInstaller } from "./plugin-install.js";
+import { PlatformPluginUpdater } from "./plugin-upgrade.js";
+import { cancelPendingRequests } from "./request-rules.js";
+import { wantedOn } from "./scope.js";
+import { addScopeOrg } from "./scope-orgs.js";
+import { PluginScopeSync, reconcileWithin } from "./scope-sync.js";
+import { narrowComponentOnUnshare, narrowItemOnUnshare } from "./unshare.js";
+/** How long the super admin's confirmation waits for this replica to load the extension. */
+const CONFIRM_RECONCILE_WAIT_MS = 5_000;
+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 LIVE = ["installing", "installed", "upgrading"];
+const notFound = () => new ApiError("catalog.item_not_found", "Catalog item not found");
+const notPending = (name) => new ApiError("extension.not_pending", `Plugin ${name} has no upload waiting for confirmation`);
+const pendingStale = (name) => new ApiError("extension.approval_stale", `The pending upload of ${name} changed since it was reviewed; review it again`);
+const builtinError = () => new ApiError("plugin.builtin", "This plugin is built in: it is on in every organization and its scope cannot be changed or disabled");
+const staleError = () => new ApiError("plugin.scope_stale", "What this change affects has changed since the preview; preview it again and confirm the new hash");
+/** The hash of a preview: sha256 over its sorted JSON, the target included. */
+function scopeHash(target, p) {
+    return createHash("sha256")
+        .update(JSON.stringify({
+        target: { ...target, orgs: [...target.orgs].sort() },
+        affected: [...p.affected]
+            .sort((a, b) => a.orgId.localeCompare(b.orgId))
+            .map((a) => ({
+            ...a,
+            agents: [...a.agents].sort((x, y) => x.id.localeCompare(y.id)),
+        })),
+        needsConfig: [...p.needsConfig].sort(),
+        replaced: [...p.replaced].sort((a, b) => a.id.localeCompare(b.id)),
+        conflicts: [...p.conflicts].sort((a, b) => a.orgId.localeCompare(b.orgId)),
+    }))
+        .digest("hex");
+}
+/**
+ * The super admin's plugin scope and deployment-level disable (plugin and component management
+ * spec §4.1, §5 rules 2-4 and 8), and the import confirm that enqueues the scope sync of the item it
+ * wrote. A change is previewed, then confirmed with the preview's `scopeHash`, recomputed under the
+ * item row lock (a difference -> 409 `plugin.scope_stale`); it bumps `scope_version`, audits
+ * `catalog.scope_changed` and, after the commit, enqueues the item's scope sync, which installs or
+ * uninstalls in every org. Disabling keeps the scope, its org list and the org switches, so
+ * re-enabling (no hash needed) reinstalls where it was on. Builtin items -> 409 `plugin.builtin`.
+ * Stateless, shared by every replica.
+ */
+let CatalogScopeService = class CatalogScopeService {
+    kdb;
+    adminLock;
+    catalog;
+    pluginImport;
+    installer;
+    extensions;
+    ops;
+    sync;
+    updater;
+    orgLock;
+    installLock;
+    lifecycle;
+    maintenance;
+    log;
+    txHost;
+    constructor(kdb, adminLock, catalog, pluginImport, installer, extensions, ops, sync, updater, 
+    /** The owner org's lock: an org admin withdrawing its pending upload (ruling P3-10). */
+    orgLock, 
+    /** The per-name install lock a reject / withdraw releases the name claim under (M1). */
+    installLock, 
+    /** This replica's reconcile once a confirmed extension is enabled (before the scope sync). */
+    lifecycle, 
+    /** The removed org plugin's cleanup job, backing the take-out of P3-21 (pre-flight F9). */
+    maintenance, log, txHost) {
+        this.kdb = kdb;
+        this.adminLock = adminLock;
+        this.catalog = catalog;
+        this.pluginImport = pluginImport;
+        this.installer = installer;
+        this.extensions = extensions;
+        this.ops = ops;
+        this.sync = sync;
+        this.updater = updater;
+        this.orgLock = orgLock;
+        this.installLock = installLock;
+        this.lifecycle = lifecycle;
+        this.maintenance = maintenance;
+        this.log = log;
+        this.txHost = txHost;
+    }
+    get db() {
+        return this.kdb.db;
+    }
+    /**
+     * Confirms a staged import ({@link PluginImport.confirm}: installs and enables the extension,
+     * writes the new item's scope), then enqueues the item's scope sync when its scope turns it on
+     * by itself (`all` or `named`; an `optional` item is on only where an org admin switches it on).
+     */
+    async confirmImport(actor, stagingId, input, opts = {}) {
+        const r = await this.pluginImport.confirm(actor, stagingId, input, opts);
+        if (r.item.scope !== "optional")
+            await this.enqueue(r.item.id);
+        return r;
+    }
+    /**
+     * Confirms the permissions of an item's extension (the admin's 待确认): approves the current
+     * permission set with snapshot source `web` (`permissionsHash` is the item view's, the extension
+     * review digest; a changed set -> 409 `extension.approval_stale`); an extension that was never
+     * deployed (no install record) is installed and enabled first (the package is in the package
+     * store from the import). Nothing waiting (a covered snapshot a person approved already, an item
+     * without an extension) -> 409 `extension.not_pending`. Enqueues the item's scope sync after.
+     *
+     * An org-owned item is confirmed only while an upload of it waits (ruling P3-10, see
+     * {@link confirmOrgUpload}); otherwise -> 409 `extension.not_pending`.
+     */
+    async confirmPermissions(actor, itemId, permissionsHash, opts = {}) {
+        if (!UUID_RE.test(itemId))
+            throw notFound();
+        const item = await this.db
+            .selectFrom("catalog_items")
+            .select([
+            "id",
+            "name",
+            "latest_version",
+            "builtin",
+            "owner_org_id",
+            "awaiting_confirmation",
+            "pending_version",
+        ])
+            .where("id", "=", itemId)
+            .where("deleted_at", "is", null)
+            .executeTakeFirst();
+        if (!item)
+            throw notFound();
+        if (item.owner_org_id !== null) {
+            return this.confirmOrgUpload(actor, { id: item.id, name: item.name }, permissionsHash, opts);
+        }
+        const version = await this.db
+            .selectFrom("catalog_item_versions")
+            .select("extension_sha256")
+            .where("item_id", "=", itemId)
+            .where("version", "=", item.latest_version)
+            .executeTakeFirst();
+        const sha256 = version?.extension_sha256 ?? null;
+        if (sha256 === null) {
+            throw new ApiError("extension.not_pending", `Plugin ${item.name} has no extension to confirm`);
+        }
+        const stale = () => new ApiError("extension.approval_stale", `The permissions of ${item.name} changed since they were reviewed; review them again`);
+        const installed = await this.extensions
+            .get(item.name, { allowUnreadable: true })
+            .then(() => true)
+            .catch((e) => {
+            if (e instanceof ApiError && e.code === "extension.not_found")
+                return false;
+            throw e;
+        });
+        if (!installed) {
+            if ((await this.extensions.packageReviewHash(sha256)) !== permissionsHash)
+                throw stale();
+            await this.ops.install(item.name, sha256, actor, opts.actorTokenId, {
+                catalogItemId: itemId,
+            });
+        }
+        const current = await this.extensions.get(item.name);
+        // A disabled install is what an earlier confirm that stopped before the enable left behind
+        const disabled = current.desired?.state === "disabled";
+        try {
+            await this.extensions.approve(actor, item.name, { sha256: current.sha256, reviewHash: permissionsHash }, { ...opts, confirmBootstrap: item.builtin });
+        }
+        catch (e) {
+            // Already approved but not enabled yet: carry on to the enable; else nothing to confirm
+            if (!disabled || !(e instanceof ApiError && e.code === "extension.not_pending"))
+                throw e;
+        }
+        if (disabled)
+            await this.ops.enable(item.name, actor, opts.actorTokenId);
+        await this.enqueue(itemId);
+        return (await this.catalog.get(itemId)).item;
+    }
+    /**
+     * The super admin's confirmation of an org upload's pending version (rulings P3-10, P3-11,
+     * P3-21): `permissionsHash` must be the digest of that version's package ({@link pendingDigest};
+     * another -> 409 `extension.approval_stale`, also for a version a later upload replaced); no
+     * pending version (withdrawn, rejected, replaced by one without an extension) -> 409
+     * `extension.not_pending`.
+     *
+     * A first version: its extension installed, its permissions approved, enabled, then (one
+     * transaction) the item stops waiting and the owner is told (`upload_confirmed`); after the
+     * commit its platform components are written and the scope sync enqueued. Each step re-reads
+     * the item under its row lock: removed meanwhile -> 409 `catalog.item_removed`, the pending
+     * version replaced -> `extension.approval_stale`; the extension this confirmation installed is
+     * then taken out again. A new version: the platform update to it
+     * ({@link PlatformPluginUpdater.updateToPending}, which installs or upgrades the extension,
+     * clears the pending state, tells the owner and the orgs using a shared plugin), then its
+     * permissions approved.
+     */
+    async confirmOrgUpload(actor, item, permissionsHash, opts) {
+        // Every step under the item's update lock (ruling P3-35): a second confirmation waits its
+        // turn out as 409 plugin.install_in_progress and never undoes the first one's install
+        const first = await this.updater.withItemLock(item.id, () => this.confirmLocked(actor, item.id, item.name, permissionsHash, opts));
+        if (first !== null) {
+            // Loaded here before the scope sync plans its install, waited for at most a few seconds
+            // (the enable does not wait for the reconcile); a sync on a replica that has not loaded it
+            // yet defers and retries (ruling P3-38)
+            await reconcileWithin(this.lifecycle, `confirmed:${item.name}`, CONFIRM_RECONCILE_WAIT_MS, this.log);
+            await this.pluginImport.writePlatformComponents(item.id, first);
+            await this.enqueue(item.id);
+        }
+        return (await this.catalog.get(item.id)).item;
+    }
+    /**
+     * {@link confirmOrgUpload} under the item lock; returns the confirmed first version (its
+     * platform components and scope sync follow after), null for a new version.
+     */
+    async confirmLocked(actor, itemId, name, permissionsHash, opts) {
+        // Read again under the lock (the caller's read was outside it)
+        const item = await this.db
+            .selectFrom("catalog_items")
+            .select([
+            "deleted_at",
+            "owner_org_id",
+            "awaiting_confirmation",
+            "pending_version",
+            "pending_by",
+            "pending_at",
+            "package_name",
+            "platform_synced_version",
+        ])
+            .where("id", "=", itemId)
+            .executeTakeFirst();
+        if (!item || item.deleted_at !== null || item.owner_org_id === null) {
+            throw itemRemovedError(name);
+        }
+        const version = item.pending_version;
+        if (version === null)
+            throw notPending(name);
+        const row = await this.db
+            .selectFrom("catalog_item_versions")
+            .select("extension_sha256")
+            .where("item_id", "=", itemId)
+            .where("version", "=", version)
+            .executeTakeFirst();
+        const sha = row?.extension_sha256 ?? null;
+        if (sha === null)
+            throw notPending(name);
+        const reviewHash = await this.extensions.packageReviewHash(sha);
+        if (reviewHash === null || pendingDigest(sha, reviewHash) !== permissionsHash) {
+            throw pendingStale(name);
+        }
+        // An install of this name that is not this item's (left by an earlier item, of another
+        // package or of the same package name under another owner): the org's code never inherits its
+        // deployment config, secrets or data (rulings P3-36, P3-51). This item's own install, or one
+        // its owner's removed item of the same package left, is upgraded in place.
+        const install = await this.db
+            .selectFrom("extension_installs as x")
+            .innerJoin("extension_packages as p", "p.sha256", "x.sha256")
+            .leftJoin("catalog_items as ci", "ci.id", "x.catalog_item_id")
+            .select(["x.sha256", "x.catalog_item_id", "p.package_name", "ci.owner_org_id"])
+            .where("x.name", "=", name)
+            .executeTakeFirst();
+        const own = install === undefined ||
+            (install.package_name === item.package_name &&
+                (install.catalog_item_id === itemId ||
+                    (install.catalog_item_id !== null && install.owner_org_id === item.owner_org_id)));
+        if (install !== undefined && !own) {
+            // who holds it: the install's own item's owner, else the package's (none: the platform)
+            const holderOrg = install.catalog_item_id === null ? null : install.owner_org_id;
+            const holder = install.catalog_item_id !== null
+                ? ownerOf(holderOrg, await ownersOf(this.db, holderOrg === null ? [] : [holderOrg]))
+                : install.package_name !== item.package_name
+                    ? await packageOwner(this.db, install.package_name, name)
+                    : PLATFORM_OWNER;
+            throw new ApiError("extension.name_conflict", install.package_name !== item.package_name
+                ? `Extension ${name} is installed from package ${install.package_name}; the upload's package ${item.package_name ?? "(none)"} cannot take it over`
+                : `Extension ${name} is installed for another plugin of package ${install.package_name}; this upload cannot take it over`, [{ owner: holder }]);
+        }
+        if (!item.awaiting_confirmation) {
+            const pending = {
+                version,
+                by: item.pending_by,
+                at: item.pending_at,
+            };
+            // A new version: applied (unless an earlier confirmation applied it and stopped before the
+            // approval), then its permissions approved; an approval that fails puts the pending state
+            // back, so the version shows in 待确认 again (ruling P3-37)
+            if (item.platform_synced_version !== version) {
+                try {
+                    await this.updater.updateToPendingLocked(actor, itemId, version, opts);
+                }
+                catch (e) {
+                    if (e instanceof ApiError && e.code === "catalog.item_not_found") {
+                        throw itemRemovedError(name);
+                    }
+                    throw e;
+                }
+            }
+            else {
+                await this.clearPending(itemId, version);
+            }
+            try {
+                await this.approvePackage(actor, name, sha, reviewHash, opts);
+            }
+            catch (e) {
+                await this.restorePending(itemId, pending);
+                throw e;
+            }
+            return null;
+        }
+        await this.stillPending(itemId, name, version);
+        let installedHere = false;
+        try {
+            if (install?.sha256 !== sha) {
+                await this.ops.install(name, sha, actor, opts.actorTokenId, { catalogItemId: itemId });
+                installedHere = install === undefined;
+            }
+            await this.stillPending(itemId, name, version);
+            await this.approvePackage(actor, name, sha, reviewHash, opts);
+            await this.stillPending(itemId, name, version);
+            await this.ops.enable(name, actor, opts.actorTokenId);
+            await this.finishFirstVersion(actor, itemId, version, opts);
+        }
+        catch (e) {
+            // Taken out only when this confirmation did not win: the item gone or still waiting
+            if (installedHere && !(await this.confirmed(itemId))) {
+                await this.takeOut(itemId, name, actor, opts);
+            }
+            throw e;
+        }
+        return version;
+    }
+    /** The item is live and its first version confirmed (no longer awaiting). */
+    async confirmed(itemId) {
+        const row = await this.db
+            .selectFrom("catalog_items")
+            .select(["deleted_at", "awaiting_confirmation"])
+            .where("id", "=", itemId)
+            .executeTakeFirst();
+        return row !== undefined && row.deleted_at === null && !row.awaiting_confirmation;
+    }
+    /** Clears the pending state of a version an earlier confirmation applied already. */
+    async clearPending(itemId, version) {
+        await this.db
+            .updateTable("catalog_items")
+            .set({ pending_version: null, pending_by: null, pending_at: null })
+            .where("id", "=", itemId)
+            .where("pending_version", "=", version)
+            .execute();
+    }
+    /**
+     * Puts a confirmed new version's pending state back after its approval failed (ruling P3-37):
+     * the version applied, its permissions still waiting, 待确认 shows it again. Not when another
+     * upload is pending meanwhile.
+     */
+    async restorePending(itemId, p) {
+        await this.db
+            .updateTable("catalog_items")
+            .set({ pending_version: p.version, pending_by: p.by, pending_at: p.at })
+            .where("id", "=", itemId)
+            .where("deleted_at", "is", null)
+            .where("pending_version", "is", null)
+            .execute();
+    }
+    /** Approves the permissions of the installed package `sha` (already covered: nothing to do). */
+    async approvePackage(actor, name, sha, reviewHash, opts) {
+        try {
+            await this.extensions.approve(actor, name, { sha256: sha, reviewHash }, opts);
+        }
+        catch (e) {
+            if (!(e instanceof ApiError && e.code === "extension.not_pending"))
+                throw e;
+        }
+    }
+    /**
+     * An extension a confirmation installed whose item was removed or replaced meanwhile is taken
+     * out again (disabled, uninstalled; P3-21), and the name claim released when the item is gone
+     * (ruling P3-37). Inline and best effort (a failure is logged); a removed item's cleanup job
+     * (`owned-plugin-cleanup-<itemId>`, idempotent) is enqueued as well, so a failed take-out is
+     * retried (pre-flight F9).
+     */
+    async takeOut(itemId, name, actor, opts) {
+        try {
+            await this.ops.disable(name, actor, opts.actorTokenId);
+            await this.ops.uninstall(name, actor, opts.actorTokenId);
+            await this.releaseIfGone(itemId, name);
+        }
+        catch (err) {
+            this.log.error("taking out the extension of a removed org upload failed", { name, err });
+        }
+        const gone = await this.db
+            .selectFrom("catalog_items")
+            .select("id")
+            .where("id", "=", itemId)
+            .where("deleted_at", "is not", null)
+            .executeTakeFirst();
+        if (gone === undefined)
+            return;
+        const job = ownedPluginCleanupJob(itemId);
+        try {
+            await this.maintenance.add(job.name, job.data, job.opts);
+        }
+        catch (err) {
+            this.log.warn("enqueueing the owned plugin cleanup failed", { itemId, err });
+        }
+    }
+    /** Releases the name claim of a removed item (nothing installed under it any more). */
+    async releaseIfGone(itemId, name) {
+        const row = await this.db
+            .selectFrom("catalog_items")
+            .select(["deleted_at", "package_name"])
+            .where("id", "=", itemId)
+            .forUpdate()
+            .executeTakeFirst();
+        if (row === undefined || row.deleted_at !== null) {
+            await releaseExtensionClaim(this.db, name, row?.package_name ?? null);
+        }
+    }
+    /** The item is still live and pending with `version` (row lock), else 409 (P3-21). */
+    async stillPending(itemId, name, version) {
+        await this.pendingRow(itemId, name, version);
+    }
+    /** {@link stillPending} in the caller's transaction; returns the owner org. */
+    async pendingRow(itemId, name, version) {
+        const row = await this.db
+            .selectFrom("catalog_items")
+            .select(["deleted_at", "pending_version", "owner_org_id"])
+            .where("id", "=", itemId)
+            .forUpdate()
+            .executeTakeFirst();
+        if (!row || row.deleted_at !== null || row.owner_org_id === null) {
+            throw itemRemovedError(name);
+        }
+        if (row.pending_version !== version)
+            throw pendingStale(name);
+        return row.owner_org_id;
+    }
+    /** A confirmed first version: the item stops waiting, the owner is told (`upload_confirmed`). */
+    async finishFirstVersion(actor, itemId, version, opts) {
+        await this.adminLock.lockAndAuthorize(actor);
+        const named = await this.db
+            .selectFrom("catalog_items")
+            .select("name")
+            .where("id", "=", itemId)
+            .executeTakeFirstOrThrow();
+        const owner = await this.pendingRow(itemId, named.name, version);
+        await this.db
+            .updateTable("catalog_items")
+            .set({
+            awaiting_confirmation: false,
+            pending_version: null,
+            pending_by: null,
+            pending_at: null,
+            // the confirmed version is the item's latest (ruling P3-34)
+            latest_version: version,
+            updated_at: sql `now()`,
+        })
+            .where("id", "=", itemId)
+            .execute();
+        await markVersionApplied(this.db, itemId, version);
+        await addOrgNotice(this.db, owner, "upload_confirmed", {
+            itemId,
+            name: named.name,
+            displayName: await itemDisplayName(this.db, itemId),
+            version,
+        });
+        await audit(this.db, {
+            actorAccountId: actor,
+            ...(opts.actorTokenId !== undefined && { actorTokenId: opts.actorTokenId }),
+            action: "catalog.upload_confirmed",
+            target: itemId,
+            detail: { name: named.name, version, ownerOrgId: owner },
+        });
+    }
+    /**
+     * The super admin rejects an org upload's pending version (ruling P3-10, `reason` shown to the
+     * owner in `upload_rejected`): a first version is removed (soft delete, its requests
+     * cancelled), a new version's pending state cleared (the version stays imported, never applied);
+     * the extension name claim is released when nothing is installed under it (pre-flight F10).
+     * Nothing pending, or a platform-owned item (pre-flight F11) -> 409 `extension.not_pending`.
+     */
+    async reject(actor, itemId, reason, opts = {}) {
+        if (!UUID_RE.test(itemId))
+            throw notFound();
+        await this.dropPending(actor, itemId, { kind: "reject", reason }, opts);
+    }
+    /**
+     * The owner org withdraws its pending upload (ruling P3-10): as {@link reject}, without a
+     * notice. Another org's or a platform item -> 404; nothing pending -> 409
+     * `extension.not_pending`.
+     */
+    async withdraw(orgId, actor, itemId, opts = {}) {
+        if (!UUID_RE.test(itemId))
+            throw notFound();
+        await this.dropPending(actor, itemId, { kind: "withdraw", orgId }, opts);
+    }
+    async dropPending(actor, itemId, how, opts) {
+        if (how.kind === "reject")
+            await this.adminLock.lockAndAuthorize(actor);
+        else
+            await this.orgLock.lockAndAuthorize(how.orgId, actor, "catalog.upload");
+        const t = this.db;
+        const item = await t
+            .selectFrom("catalog_items")
+            .select([
+            "id",
+            "name",
+            "owner_org_id",
+            "awaiting_confirmation",
+            "pending_version",
+            "package_name",
+        ])
+            .where("id", "=", itemId)
+            .where("deleted_at", "is", null)
+            .forUpdate()
+            .executeTakeFirst();
+        if (!item)
+            throw notFound();
+        if (how.kind === "withdraw" && item.owner_org_id !== how.orgId)
+            throw notFound();
+        if (item.owner_org_id === null || item.pending_version === null)
+            throw notPending(item.name);
+        const now = sql `now()`;
+        await t
+            .updateTable("catalog_items")
+            .set({
+            pending_version: null,
+            pending_by: null,
+            pending_at: null,
+            updated_at: now,
+            // A first version is removed: the name is free again (P3-10)
+            ...(item.awaiting_confirmation && { deleted_at: now }),
+        })
+            .where("id", "=", itemId)
+            .execute();
+        if (item.awaiting_confirmation) {
+            await cancelPendingRequests(t, { itemId }, actor, "item_removed", opts);
+        }
+        if (how.kind === "reject") {
+            // never usable afterwards, whoever owns the item later (ruling P3-52)
+            await t
+                .updateTable("catalog_item_versions")
+                .set({ rejected_at: now })
+                .where("item_id", "=", itemId)
+                .where("version", "=", item.pending_version)
+                .execute();
+        }
+        // Under the per-name install lock, as CatalogService.removeIn: a confirm's install still
+        // committing is seen, so its claim is never released under it
+        await this.installLock.lock(item.name);
+        await releaseExtensionClaim(t, item.name, item.package_name);
+        if (how.kind === "reject") {
+            await addOrgNotice(t, item.owner_org_id, "upload_rejected", {
+                itemId,
+                name: item.name,
+                displayName: await itemDisplayName(t, itemId),
+                version: item.pending_version,
+                reason: how.reason,
+            });
+        }
+        await audit(t, {
+            actorAccountId: actor,
+            ...(opts.actorTokenId !== undefined && { actorTokenId: opts.actorTokenId }),
+            action: how.kind === "reject" ? "catalog.upload_rejected" : "catalog.upload_withdrawn",
+            target: itemId,
+            detail: {
+                name: item.name,
+                version: item.pending_version,
+                ownerOrgId: item.owner_org_id,
+                removed: item.awaiting_confirmation,
+                ...(how.kind === "reject" && { reason: how.reason }),
+            },
+        });
+    }
+    /** The preview of a scope change or a disable (nothing written). */
+    async preview(itemId, target) {
+        const item = await this.item(itemId, false);
+        return this.compute(item, await this.targetOf(item, target));
+    }
+    /** Changes the scope after its preview (`scopeHash`); returns the item. */
+    async setScope(actor, itemId, body, opts = {}) {
+        if (!UUID_RE.test(itemId))
+            throw notFound();
+        const target = { scope: body.scope, ...(body.orgs !== undefined && { orgs: body.orgs }) };
+        await this.writeScope(actor, itemId, target, body.scopeHash, opts);
+        return (await this.catalog.get(itemId)).item;
+    }
+    /**
+     * Disables the plugin on the whole deployment (after its preview, `scopeHash` required) or
+     * enables it again (no hash); returns the item.
+     */
+    async setDisabled(actor, itemId, body, opts = {}) {
+        if (!UUID_RE.test(itemId))
+            throw notFound();
+        if (body.disabled && body.scopeHash === undefined) {
+            throw new ApiError("validation_failed", "scopeHash: required when disabling (from POST scope/preview with disabled: true)", [{ path: "scopeHash", message: "required when disabling" }]);
+        }
+        await this.writeDisabled(actor, itemId, body.disabled, body.scopeHash, opts);
+        return (await this.catalog.get(itemId)).item;
+    }
+    /** Shows or hides the item to orgs outside its `named` list; returns the item. */
+    async setShown(actor, itemId, shown, opts = {}) {
+        if (!UUID_RE.test(itemId))
+            throw notFound();
+        await this.writeShown(actor, itemId, shown, opts);
+        return (await this.catalog.get(itemId)).item;
+    }
+    async writeShown(actor, itemId, shown, opts) {
+        await this.adminLock.lockAndAuthorize(actor);
+        // A builtin item is `all`: the flag is irrelevant there but harmless, so it is not refused
+        const item = await this.db
+            .selectFrom("catalog_items")
+            .select(["name", "shown_to_others", "owner_org_id", "shareable", "awaiting_confirmation"])
+            .where("id", "=", itemId)
+            .where("deleted_at", "is", null)
+            .forUpdate()
+            .executeTakeFirst();
+        if (!item)
+            throw notFound();
+        // A first version waiting for the super admin is nobody's to show yet (P3-9)
+        assertNotAwaiting(item);
+        // Showing goes through the share gate (P3-16); hiding is always allowed
+        if (shown)
+            assertShareable(item);
+        if (item.shown_to_others === shown)
+            return;
+        await this.db
+            .updateTable("catalog_items")
+            .set({ shown_to_others: shown, updated_at: sql `now()` })
+            .where("id", "=", itemId)
+            .execute();
+        await audit(this.db, {
+            actorAccountId: actor,
+            ...(opts.actorTokenId !== undefined && { actorTokenId: opts.actorTokenId }),
+            action: "catalog.shown_changed",
+            target: itemId,
+            detail: { name: item.name, from: item.shown_to_others, to: shown },
+        });
+    }
+    async writeScope(actor, itemId, target, hash, opts) {
+        await this.adminLock.lockAndAuthorize(actor);
+        const item = await this.item(itemId, true);
+        assertNotAwaiting(item);
+        const t = await this.targetOf(item, target);
+        const from = await this.listed(itemId);
+        // The owner stays listed (P3-17); widening goes through the share gate (P3-16)
+        assertOwnerListed(item, t);
+        assertShareableTarget(item, { scope: item.scope, orgs: from }, t);
+        const p = await this.compute(item, t);
+        if (p.scopeHash !== hash)
+            throw staleError();
+        if (p.conflicts.length > 0)
+            throw nameConflictError(p.conflicts);
+        if (item.scope === t.scope && from.join() === t.orgs.join() && p.replaced.length === 0)
+            return;
+        await this.followAgain(actor, itemId, p.replaced, opts);
+        await this.db
+            .updateTable("catalog_items")
+            .set({
+            scope: t.scope,
+            scope_version: sql `scope_version + 1`,
+            updated_at: sql `now()`,
+        })
+            .where("id", "=", itemId)
+            .execute();
+        await this.db.deleteFrom("catalog_item_scope_orgs").where("item_id", "=", itemId).execute();
+        if (t.orgs.length > 0) {
+            await this.db
+                .insertInto("catalog_item_scope_orgs")
+                .values(t.orgs.map((org_id) => ({ item_id: itemId, org_id })))
+                .execute();
+        }
+        const shared = newlySharedWith({ scope: item.scope, orgs: from }, t);
+        if (shared === "all_orgs" || shared.length > 0) {
+            await notifyItemShared(this.db, item.owner_org_id, { kind: "plugin", id: itemId }, item.name, shared);
+        }
+        await audit(this.db, {
+            actorAccountId: actor,
+            ...(opts.actorTokenId !== undefined && { actorTokenId: opts.actorTokenId }),
+            action: "catalog.scope_changed",
+            target: itemId,
+            detail: {
+                name: item.name,
+                from: { scope: item.scope, orgs: from },
+                to: { scope: t.scope, orgs: t.orgs },
+            },
+        });
+        afterCommit(() => this.enqueue(itemId));
+    }
+    async writeDisabled(actor, itemId, disabled, hash, opts) {
+        await this.adminLock.lockAndAuthorize(actor);
+        const item = await this.item(itemId, true);
+        if (item.disabled === disabled)
+            return;
+        const p = await this.compute(item, disabled
+            ? await this.targetOf(item, { disabled: true })
+            : { scope: item.scope, orgs: await this.listed(itemId), disabled, scopeChange: false });
+        if (disabled && p.scopeHash !== hash)
+            throw staleError();
+        if (p.conflicts.length > 0)
+            throw nameConflictError(p.conflicts);
+        await this.db
+            .updateTable("catalog_items")
+            .set({
+            disabled,
+            scope_version: sql `scope_version + 1`,
+            updated_at: sql `now()`,
+        })
+            .where("id", "=", itemId)
+            .execute();
+        await audit(this.db, {
+            actorAccountId: actor,
+            ...(opts.actorTokenId !== undefined && { actorTokenId: opts.actorTokenId }),
+            action: "catalog.scope_changed",
+            target: itemId,
+            detail: { name: item.name, disabled: { from: item.disabled, to: disabled } },
+        });
+        afterCommit(() => this.enqueue(itemId));
+    }
+    /**
+     * Writes an org-owned plugin's 可共享 flag and copies it to its component rows (ruling P3-2).
+     * Turning it off narrows an `optional` / `all` plugin, and each component with its own such
+     * scope, to the owner plus the orgs where it is on now (ruling P3-25), and enqueues the item's
+     * scope sync after the commit. The caller authorizes (the owner org's admin, Task 7). A platform
+     * item (no owner) or a missing one -> 404.
+     */
+    async setShareable(itemId, shareable, actor = null) {
+        if (!UUID_RE.test(itemId))
+            throw notFound();
+        const item = await this.db
+            .selectFrom("catalog_items")
+            .select(["id", "name", "scope", "builtin", "owner_org_id", "shareable"])
+            .where("id", "=", itemId)
+            .where("deleted_at", "is", null)
+            .forUpdate()
+            .executeTakeFirst();
+        if (!item || item.owner_org_id === null)
+            throw notFound();
+        await this.db
+            .updateTable("catalog_items")
+            .set({ shareable })
+            .where("id", "=", itemId)
+            .execute();
+        for (const table of [
+            "platform_skills",
+            "platform_agent_templates",
+            "platform_connector_templates",
+        ]) {
+            await this.db
+                .updateTable(table)
+                .set({ shareable })
+                .where("catalog_item_id", "=", itemId)
+                .where("deleted_at", "is", null)
+                .execute();
+        }
+        if (shareable)
+            return;
+        const narrowed = await narrowItemOnUnshare(this.db, actor, item);
+        for (const kind of COMPONENT_KINDS) {
+            for (const c of await loadComponents(this.db, kind, { itemId, forUpdate: true })) {
+                await narrowComponentOnUnshare(this.db, actor, c);
+            }
+        }
+        if (narrowed)
+            afterCommit(() => this.enqueue(itemId));
+    }
+    /**
+     * Adds one org to a `named` item's list in the caller's transaction (an approved `access`
+     * request, spec §5.1 rule 2): nobody loses access, so no preview. The item row is locked; it
+     * must be live and not builtin (404 / `plugin.builtin`). Bumps `scope_version`, audits
+     * `catalog.scope_changed` and enqueues the item's scope sync after the commit. Returns whether
+     * the list changed (false: not `named`, or listed already).
+     */
+    async addOrg(actor, itemId, orgId, opts = {}) {
+        const item = await this.item(itemId, true);
+        assertNotAwaiting(item);
+        const changed = await addScopeOrg(this.db, actor, item, orgId, opts);
+        if (changed)
+            afterCommit(() => this.enqueue(itemId));
+        return changed;
+    }
+    /**
+     * Enqueues the item's scope sync after a commit made elsewhere (an org upload's confirm,
+     * `OrgPluginUploads`); a failure only warns.
+     */
+    async enqueueSync(itemId) {
+        await this.enqueue(itemId);
+    }
+    /** Enqueues the item's scope sync; a failure only warns (the next change or org sync converges). */
+    async enqueue(itemId) {
+        try {
+            await this.sync.enqueueItem(itemId);
+        }
+        catch (err) {
+            this.log.warn("enqueueing the plugin scope sync failed", { itemId, err });
+        }
+    }
+    /** The live item (row locked with `forUpdate`); missing -> 404, builtin -> `plugin.builtin`. */
+    async item(itemId, forUpdate) {
+        if (!UUID_RE.test(itemId))
+            throw notFound();
+        let q = this.db
+            .selectFrom("catalog_items")
+            .select([
+            "id",
+            "name",
+            "scope",
+            "builtin",
+            "disabled",
+            "latest_version",
+            "owner_org_id",
+            "shareable",
+            "awaiting_confirmation",
+        ])
+            .where("id", "=", itemId)
+            .where("deleted_at", "is", null);
+        if (forUpdate)
+            q = q.forUpdate();
+        const row = await q.executeTakeFirst();
+        if (!row)
+            throw notFound();
+        if (row.builtin)
+            throw builtinError();
+        return row;
+    }
+    /** The `named` list of the item, sorted. */
+    async listed(itemId) {
+        const rows = await this.db
+            .selectFrom("catalog_item_scope_orgs")
+            .select("org_id")
+            .where("item_id", "=", itemId)
+            .orderBy("org_id")
+            .execute();
+        return rows.map((r) => r.org_id);
+    }
+    /** The state after the change: `orgs` only with `named`, each a live org. */
+    async targetOf(item, target) {
+        if ("disabled" in target) {
+            return {
+                scope: item.scope,
+                orgs: await this.listed(item.id),
+                disabled: true,
+                scopeChange: false,
+            };
+        }
+        if (target.orgs !== undefined && target.scope !== "named") {
+            throw new ApiError("validation_failed", "orgs: only allowed with scope named", [
+                { path: "orgs", message: "only allowed with scope named" },
+            ]);
+        }
+        const orgs = [...new Set(target.orgs ?? [])].sort();
+        await assertOrgsExist(this.db, orgs);
+        return { scope: target.scope, orgs, disabled: item.disabled, scopeChange: true };
+    }
+    /** The preview of moving `item` to `target` (read through the current context). */
+    async compute(item, target) {
+        const db = this.db;
+        // one after the other: `db` may be a transaction's single connection
+        const orgs = await db
+            .selectFrom("orgs")
+            .select(["id", "name"])
+            .where("deleted_at", "is", null)
+            .orderBy("id")
+            .execute();
+        const listedNow = new Set(await this.listed(item.id));
+        const switches = await db
+            .selectFrom("catalog_item_org_switches")
+            .select(["org_id", "enabled"])
+            .where("item_id", "=", item.id)
+            .execute();
+        const installs = await db
+            .selectFrom("plugin_installs")
+            .select(["id", "org_id"])
+            .where("item_id", "=", item.id)
+            .where("status", "in", [...LIVE])
+            .execute();
+        const sw = new Map(switches.map((s) => [s.org_id, s.enabled]));
+        const live = new Map(installs.map((a) => [a.org_id, a.id]));
+        const listedAfter = new Set(target.orgs);
+        const after = { scope: target.scope, disabled: target.disabled, builtin: false };
+        const affected = [];
+        const needsConfig = [];
+        /** The orgs the plugin will be on in after the change (a live install kept or made). */
+        const onAfter = new Set();
+        for (const org of orgs) {
+            const s = sw.get(org.id) ?? null;
+            const wanted = wantedOn(after, listedAfter.has(org.id), s);
+            const installId = live.get(org.id);
+            if (installId !== undefined) {
+                // A live install another one depends on stays (spec §5 rule 9, as the sync does)
+                if (wanted || (await this.sync.dependedOn(org.id, installId))) {
+                    onAfter.add(org.id);
+                    continue;
+                }
+                const p = await this.installer.previewUninstall(org.id, installId);
+                affected.push({
+                    orgId: org.id,
+                    orgName: org.name,
+                    agents: p.agents.map((a) => ({ id: a.id, name: a.name })),
+                    // The sync's uninstall keeps the connectors the install created as the org's own
+                    connectorsKept: p.components.filter((c) => c.kind === "connector" && c.created).length,
+                });
+                continue;
+            }
+            if (!wanted || wantedOn(item, listedNow.has(org.id), s))
+                continue;
+            let needs = false;
+            try {
+                needs = await this.sync.needsInput(org.id, item.id, item.latest_version);
+            }
+            catch (e) {
+                // Not installable as it is (a dependency unresolved): the sync reports it. Anything else
+                // (a database error) propagates: inside the write's transaction it is not recoverable
+                if (!(e instanceof ApiError))
+                    throw e;
+            }
+            if (needs)
+                needsConfig.push(org.id);
+            else
+                onAfter.add(org.id);
+        }
+        const { replaced, conflicts } = await this.componentChanges(item, target, orgs, onAfter, affected);
+        const p = { affected, needsConfig, replaced, conflicts };
+        return { ...p, scopeHash: scopeHash(target, p) };
+    }
+    /**
+     * The component side of a plugin scope change or disable (spec §5 rules 2, 8, 10): the
+     * components with their own scope a scope change replaces; the orgs where a skill or agent
+     * template is on now and would be off after (agents merged into `affected`: a component with its
+     * own scope that goes back to following the plugin, or one cut by the disable); and the orgs a
+     * skill would newly be offered to whose own skills use its name. `onAfter`: the orgs the plugin
+     * is on in after the change.
+     */
+    async componentChanges(item, target, orgs, onAfter, affected) {
+        const db = this.db;
+        const replaced = [];
+        const conflicts = [];
+        const lose = new Map();
+        for (const kind of COMPONENT_KINDS) {
+            const comps = await loadComponents(db, kind, { itemId: item.id });
+            if (comps.length === 0)
+                continue;
+            if (target.scopeChange) {
+                for (const c of comps) {
+                    if (c.scopeMode === "own")
+                        replaced.push({ kind, id: c.id, name: c.name });
+                }
+            }
+            if (kind === "connector_template")
+                continue;
+            const st = await loadScopeState(db, kind, comps);
+            for (const c of comps) {
+                const cAfter = target.scopeChange ? { ...c, scopeMode: "follow" } : c;
+                for (const org of orgs) {
+                    const pNow = pluginFactsOf(st, c.itemId, org.id);
+                    const pAfter = pNow && {
+                        ...pNow,
+                        scope: target.scope,
+                        disabled: target.disabled,
+                        listed: target.orgs.includes(org.id),
+                        installed: onAfter.has(org.id),
+                    };
+                    const listed = listedIn(st, c.id, org.id);
+                    const s = switchOf(st, c.id, org.id);
+                    if (componentOn(c, pNow, listed, s) && !componentOn(cAfter, pAfter, listed, s)) {
+                        for (const a of await agentsUsing(db, org.id, kind, [c.id])) {
+                            const m = lose.get(org.id) ?? new Map();
+                            m.set(a.id, a.name);
+                            lose.set(org.id, m);
+                        }
+                        if (!lose.has(org.id))
+                            lose.set(org.id, new Map());
+                    }
+                    if (kind === "skill" &&
+                        componentOffered(cAfter, pAfter, listed) &&
+                        !componentOffered(c, pNow, listed)) {
+                        const clash = await skillNameClashes(db, org.id, c, c.name);
+                        if (clash.skills.length > 0) {
+                            conflicts.push({ orgId: org.id, orgName: org.name, name: c.name, ...clash });
+                        }
+                    }
+                }
+            }
+        }
+        for (const org of orgs) {
+            const m = lose.get(org.id);
+            if (!m)
+                continue;
+            let e = affected.find((a) => a.orgId === org.id);
+            if (!e) {
+                e = { orgId: org.id, orgName: org.name, agents: [], connectorsKept: 0 };
+                affected.push(e);
+            }
+            for (const [id, name] of m) {
+                if (!e.agents.some((a) => a.id === id))
+                    e.agents.push({ id, name });
+            }
+        }
+        return { replaced, conflicts };
+    }
+    /**
+     * Sends the components of the item with their own scope back to following it (a plugin scope
+     * change, spec §5 rule 2): `scope_mode = follow`, their own lists dropped, `scope_version`
+     * bumped, one `component.scope_changed` audit each. In the caller's transaction.
+     */
+    async followAgain(actor, itemId, replaced, opts) {
+        for (const r of replaced) {
+            const table = r.kind === "skill"
+                ? "platform_skills"
+                : r.kind === "agent_template"
+                    ? "platform_agent_templates"
+                    : "platform_connector_templates";
+            await this.db
+                .updateTable(table)
+                .set({
+                scope_mode: "follow",
+                scope_version: sql `scope_version + 1`,
+                updated_at: sql `now()`,
+            })
+                .where("id", "=", r.id)
+                .where("scope_mode", "=", "own")
+                .execute();
+            await this.db
+                .deleteFrom("component_scope_orgs")
+                .where("kind", "=", r.kind)
+                .where("component_id", "=", r.id)
+                .execute();
+            await audit(this.db, {
+                actorAccountId: actor,
+                ...(opts.actorTokenId !== undefined && { actorTokenId: opts.actorTokenId }),
+                action: "component.scope_changed",
+                target: r.id,
+                detail: { kind: r.kind, name: r.name, itemId, to: { scopeMode: "follow" }, via: "plugin" },
+            });
+        }
+    }
+};
+__decorate([
+    Transactional()
+], CatalogScopeService.prototype, "clearPending", null);
+__decorate([
+    Transactional()
+], CatalogScopeService.prototype, "restorePending", null);
+__decorate([
+    Transactional()
+], CatalogScopeService.prototype, "releaseIfGone", null);
+__decorate([
+    Transactional()
+], CatalogScopeService.prototype, "stillPending", null);
+__decorate([
+    Transactional()
+], CatalogScopeService.prototype, "finishFirstVersion", null);
+__decorate([
+    Transactional()
+], CatalogScopeService.prototype, "dropPending", null);
+__decorate([
+    Transactional()
+], CatalogScopeService.prototype, "writeShown", null);
+__decorate([
+    Transactional()
+], CatalogScopeService.prototype, "writeScope", null);
+__decorate([
+    Transactional()
+], CatalogScopeService.prototype, "writeDisabled", null);
+__decorate([
+    Transactional()
+], CatalogScopeService.prototype, "setShareable", null);
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], CatalogScopeService.prototype, "addOrg", null);
+CatalogScopeService = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(SuperAdminLock)),
+    __param(2, Inject(CatalogService)),
+    __param(3, Inject(PluginImport)),
+    __param(4, Inject(PluginInstaller)),
+    __param(5, Inject(ExtensionAdmin)),
+    __param(6, Inject(ExtensionAdminOps)),
+    __param(7, Inject(PluginScopeSync)),
+    __param(8, Inject(PlatformPluginUpdater)),
+    __param(9, Inject(OrgLock)),
+    __param(10, Inject(PluginInstallLock)),
+    __param(11, Inject(ExtensionLifecycle)),
+    __param(12, Inject(getQueueToken(MAINTENANCE_QUEUE_NAME))),
+    __param(13, Inject(KERNEL_LOGGER)),
+    __param(14, Inject(TransactionHost))
+], CatalogScopeService);
+export { CatalogScopeService };