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

package/dist/catalog/plugin-import.js

@@ -8,14 +8,18 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { createHash, randomUUID } from "node:crypto";
-import { PLUGIN_MANIFEST_FILE, parseSkillMd, SDK_VERSION, SKILL_ENTRY_FILE, } from "@capybara-hq/plugin-sdk";
+import { appearanceIssues, PLUGIN_MANIFEST_FILE, parseSkillMd, pluginDescription, SDK_VERSION, SKILL_ENTRY_FILE, } from "@capybara-hq/plugin-sdk";
+import { getQueueToken } from "@nestjs/bullmq";
 import { Inject, Injectable } from "@nestjs/common";
 import { sql } from "kysely";
 import semver from "semver";
+import { ClientBuilds } from "../client/client-builds.service.js";
+import { checkClientFiles } from "../client/client-files.js";
 import { ApiError } from "../errors.js";
 import { ExtensionAdminOps } from "../extensions/admin-ops.js";
+import { ExtensionAdmin } from "../extensions/admin-view.js";
 import { writeSnapshot } from "../extensions/approvals.js";
-import { ExtensionBlobs } from "../extensions/blobs.js";
+import { blobKey, ExtensionBlobs } from "../extensions/blobs.js";
 import { ExtensionInstalls } from "../extensions/installs.js";
 import { PluginApproveLock, PluginInstallLock } from "../extensions/locks.js";
 import { unrunMigrations } from "../extensions/migrate-lock.js";
@@ -24,28 +28,41 @@ import { diffPermissions, permissionKeys, WARNINGS_KEY_PREFIX, } from "../extens
 import { reviewHash as extensionReviewHash, migrationWarnings, permissionGroups, permissionKeyItems, } from "../extensions/permission-view.js";
 import { ExtensionRegistry } from "../extensions/registry.js";
 import { audit } from "../identity/audit.js";
-import { EnterpriseAdminLock } from "../identity/enterprise-admin.js";
+import { assertCustomAllowed } from "../identity/settings.js";
+import { SuperAdminLock } from "../identity/super-admin.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { afterCommit } from "../infra/database/after-commit.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
 import { Transactional } from "../infra/database/transactional.decorator.js";
 import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { OrgLock } from "../orgs/org-lock.js";
 import { packPackageTgz } from "../packages/tgz.js";
+import { MAINTENANCE_QUEUE_NAME } from "../runtime/maintenance-queue.js";
 import { checkSkillFiles, SkillArchiveError } from "../skills/package.js";
 import { StorageService } from "../storage/storage.service.js";
+import { canonicalJson } from "../tools/canonical-json.js";
 import { endpointCredentialIssues } from "../tools/endpoint.js";
-import { canonicalJson } from "../tools/registry.js";
 import { findConnectorIn } from "./catalog-content.js";
-import { assertPluginNameOwner, catalogObjectPrefix, itemView, permissionsMismatch, precheckCatalogImport, putCatalogFiles, templateProblems, writeCatalogVersion, } from "./catalog-items.js";
+import { displayFilePaths, putDisplayFiles, sweepDisplayFiles } from "./catalog-files.js";
+import { assertOrgsExist, assertPluginNameOwner, catalogObjectPrefix, itemConfirmations, itemScopeFacts, itemView, markVersionApplied, permissionsMismatch, precheckCatalogImport, putCatalogFiles, templateProblems, unappliedOwnVersion, writeCatalogVersion, } from "./catalog-items.js";
 import { CLAUDE_PLUGIN_FILE, claudeContentDigest, } from "./claude/manifest.js";
 import { CLAUDE_MCP_CONNECTOR } from "./claude/mcp.js";
 import { item as reportItem, sortItems, } from "./claude/report.js";
 import { isClaudePluginTree, translateClaudePlugin } from "./claude/translate.js";
 import { CatalogItemLock } from "./locks.js";
-import { PluginPackageError, packagePath, readPluginFiles, readPluginPackage, } from "./plugin-package.js";
+import { assertNameFree, assertPackageFree, assertShareable, packageOwner, releaseExtensionClaim, shareGate, usableBy, } from "./ownership.js";
+import { PlatformComponents } from "./platform-components.js";
+import { PLATFORM_MIGRATION_JOB } from "./platform-migration.js";
+import { PluginPackageError, packagePath, readPluginFiles, readPluginPackage, themeApiError, } from "./plugin-package.js";
+import { hasImportRequests, importRequestOf, resolveImportRequests } from "./request-rules.js";
+import { assertNameNotReserved } from "./reserved-names.js";
+import { addScopeOrg } from "./scope-orgs.js";
 import { maxSatisfying, satisfiesRange } from "./versions.js";
+/** How long after a failed post-import platform sync the migration job runs for the item. */
+export const PLATFORM_SYNC_RETRY_MS = 60_000;
 /**
- * Enterprise import of a plugin (package ecosystem spec §4.3): one review for every plugin, whatever
+ * Platform import of a plugin (package ecosystem spec §4.3): one review for every plugin, whatever
  * it contains (an extension, skills, connector templates, dependencies), confirmed once.
  *
  * prepare: the tgz is always hostile input, and **nothing is written until every check passes**
@@ -55,27 +72,30 @@ import { maxSatisfying, satisfiesRange } from "./versions.js";
  * refused; name ownership; a downgrade to a version with unrun migrations is refused), each skill by
  * the skill package rules, each connector template against the connector loaded on this replica (or
  * statically when the connector is provided by the plugin's own extension or by a dependency), the
- * catalog name / version conflicts and the actor still an enterprise admin. Dependencies are only
+ * catalog name / version conflicts and the actor still a super admin. Dependencies are only
  * resolved against the imported catalog versions for the review (an unresolved one does not block
  * the import, spec §4.1); they are never fetched. Only then is the extension handed to
- * `ExtensionInstalls.ingest` (source `catalog`), the skill / template / icon files written to object
- * storage, a staging row written (24 hours) and `catalog.plugin_staged` audited.
+ * `ExtensionInstalls.ingest` (source `catalog`), the skill / template files written to object
+ * storage, the display files (icons, setup guide files; `catalog-files.ts`) written to PG with a
+ * staging row (24 hours), and `catalog.plugin_staged` audited. A display file inside a skill
+ * directory or at a template's path goes to both places: each reader finds it where it looks.
  *
  * confirm: `reviewHash` must match the staging; in one transaction it deletes the staging row
  * (confirm works once), locks the extension name and recomputes its deployment state (installed /
  * upgraded / swapped after the review -> `plugin.review_stale`), writes the extension's permission
- * snapshot when it is installed by this import (or upgraded with `deployExtension`; source web, audit
- * `extension.permissions_approved` carrying the plugin), and creates the item or adds the version
- * (`manifest` = the normalized plugin.json, `extension_sha256`, the files under the staging prefix).
- * After the commit, with `deployExtension`, the plugin's own extension is installed on the
- * deployment and enabled (`ExtensionAdminOps.install` + `enable`; each replica reconciles, no
- * restart); a failure is returned, not thrown, and an upgrade that was not installed gets its old
- * snapshot back.
+ * snapshot when it is installed or upgraded by this import (source web, audit
+ * `extension.permissions_approved` carrying the plugin), and creates the item (with the scope the
+ * admin chose, default `optional`) or adds the version (`manifest` = the normalized plugin.json,
+ * `extension_sha256`, the files under the staging prefix). After the commit the plugin's own
+ * extension is installed on the deployment and enabled (`ExtensionAdminOps.install` + `enable`;
+ * each replica reconciles, no restart); a failure is returned, not thrown, and an upgrade that was
+ * not installed gets its old snapshot back.
  *
  * Expired staging is cleaned by the maintenance job `app-staging-cleanup`
- * ({@link PluginImport.cleanupExpired}): it deletes the staging row and its object prefix; a stored
- * extension package stays in the content-addressed `extension_packages` (the same as importing the
- * same tgz again; without an install record referencing it it is never loaded).
+ * ({@link PluginImport.cleanupExpired}): it deletes the staging row and its object prefix, then the
+ * display files (`catalog_files`) nothing lists any more; a stored extension package stays in the
+ * content-addressed `extension_packages` (the same as importing the same tgz again; without an
+ * install record referencing it it is never loaded).
  */
 /** How long a staged import is kept. */
 export const PLUGIN_STAGING_TTL_MS = 24 * 3600_000;
@@ -94,12 +114,20 @@ const reviewStale = (review) => new ApiError("plugin.review_stale", `The review
 const mismatch = (what) => new ApiError("marketplace.package_mismatch", `The downloaded package does not match the marketplace entry: ${what}`);
 /**
  * The API error of a plugin package that cannot be read in a catalog path: the pre-0.1.0 format ->
- * `catalog.legacy_format`, anything else -> `catalog.invalid_manifest` (issues as details).
+ * `catalog.legacy_format`; undeclared client code -> `client.undeclared`; a failing theme (themes
+ * spec §5) -> `theme.invalid` (details `[{ theme, errors }]`) or `theme.unreadable` (details
+ * `[{ theme, issues }]`, the failing pairs); anything else -> `catalog.invalid_manifest` (issues as
+ * details).
  */
 export function catalogPackageError(e) {
     const legacy = e.code === "catalog.legacy_format" || e.code === "extension.legacy_format";
     if (legacy)
         return new ApiError("catalog.legacy_format", e.message, e.issues);
+    if (e.code === "client.undeclared")
+        return new ApiError("client.undeclared", e.message);
+    if (e.code === "theme.invalid" || e.code === "theme.unreadable") {
+        return themeApiError(e);
+    }
     return invalid(e.issues);
 }
 /** Runs a package read, mapping its errors with {@link catalogPackageError}. */
@@ -123,16 +151,21 @@ const fileOf = (path, data) => ({
 let PluginImport = class PluginImport {
     kdb;
     adminLock;
+    orgLock;
     installLock;
     approveLock;
     itemLock;
     config;
     installs;
     ops;
+    admin;
     blobs;
     registry;
     log;
     txHost;
+    platform;
+    maintenance;
+    clientBuilds;
     /** Where plugin files go (the kernel's object storage; the CLI's own, see {@link useCliStorage}). */
     files;
     /**
@@ -142,24 +175,37 @@ let PluginImport = class PluginImport {
      */
     connectorsLoaded = true;
     constructor(kdb, 
-    /** The enterprise admin lock (identity/enterprise-admin.ts): joins the caller's transaction. */
-    adminLock, installLock, approveLock, itemLock, config, storage, installs, ops, 
+    /** The super admin lock (identity/super-admin.ts): joins the caller's transaction. */
+    adminLock, 
+    /** The owner org's lock: an org upload re-checks its admin under it (ruling P3-7). */
+    orgLock, installLock, approveLock, itemLock, config, storage, installs, ops, admin, 
     /** Reads a package from the package store (confirm recomputes the permission set). */
     blobs, 
     /** Config-declared names, loaded connectors and extension versions (the extension registry). */
-    registry, log, txHost) {
+    registry, log, txHost, 
+    /** The platform rows of a new item's components, written after the confirm's commit. */
+    platform, 
+    /** A failed platform sync enqueues a run of the migration job here (it heals the item). */
+    maintenance, 
+    /** The client build of a dropped org upload's package is deleted with it. */
+    clientBuilds) {
         this.kdb = kdb;
         this.adminLock = adminLock;
+        this.orgLock = orgLock;
         this.installLock = installLock;
         this.approveLock = approveLock;
         this.itemLock = itemLock;
         this.config = config;
         this.installs = installs;
         this.ops = ops;
+        this.admin = admin;
         this.blobs = blobs;
         this.registry = registry;
         this.log = log;
         this.txHost = txHost;
+        this.platform = platform;
+        this.maintenance = maintenance;
+        this.clientBuilds = clientBuilds;
         this.files = storage;
     }
     /** The kernel-schema handle of the current context (the transaction, else the pool). */
@@ -174,21 +220,29 @@ let PluginImport = class PluginImport {
     useCliStorage(storage) {
         this.files = storage;
         this.connectorsLoaded = false;
+        this.platform.useCliStorage(storage);
     }
     /**
-     * The enterprise-admin re-check under the lock, in the caller's transaction. `actor` null is the
+     * The super-admin re-check under the lock, in the caller's transaction. `actor` null is the
      * CLI (the operator of the deployment: no account to re-check, audits carry no actor), like
-     * `ExtensionInstalls.ingest`.
+     * `ExtensionInstalls.ingest`. An org upload (`owner`) re-checks the actor as an admin of the
+     * owner org under the org row lock instead (`catalog.upload`; an org deleted meanwhile -> 404
+     * `org.not_found`).
      */
-    async authorizeActor(actor) {
-        if (actor === null)
+    async authorizeActor(actor, owner) {
+        if (owner !== undefined) {
+            if (actor === null)
+                throw new Error("an org upload has an actor");
+            await this.orgLock.lockAndAuthorize(owner.orgId, actor, "catalog.upload");
+        }
+        else if (actor === null)
             await this.adminLock.lock();
         else
             await this.adminLock.lockAndAuthorize(actor);
     }
     /** The re-check alone, in a transaction of its own (before anything is written). */
-    async authorize(actor) {
-        await this.authorizeActor(actor);
+    async authorize(actor, owner) {
+        await this.authorizeActor(actor, owner);
     }
     /**
      * Reads, checks and stages a plugin (see the file header). Returns the staging id and review.
@@ -279,6 +333,10 @@ let PluginImport = class PluginImport {
      */
     async prepareContents(actor, pkg, tgz, source, opts) {
         const maxBytes = this.config.get().packages.maxBytes;
+        const owner = opts.owner;
+        if (owner !== undefined && source.kind !== "file") {
+            throw new Error("an org upload is a file (ruling P3-7)");
+        }
         // 1. Every check (nothing written)
         const m = pkg.manifest;
         const packageName = packageNameOf(pkg);
@@ -292,14 +350,50 @@ let PluginImport = class PluginImport {
             ? await readingPackage(() => readExtensionPackage(bytes, { maxBytes, hostSdkVersion: SDK_VERSION }))
             : undefined;
         const content = this.checkContent(pkg, format);
-        const { existing, version } = await precheckCatalogImport(this.db, m.name, {
-            packageName,
-            version: m.version,
-            contentDigest: pkg.contentDigest,
-            ...(source.integrity !== undefined && { integrity: source.integrity }),
-            ...(source.detail !== undefined && { detail: source.detail }),
-            ...(source.marketplaceId !== undefined && { marketplaceId: source.marketplaceId }),
-        });
+        // suggestedAppearance.theme against the themes the scan found (the manifest may not list them)
+        const appearance = appearanceIssues(m, pkg.themes.map((t) => t.id));
+        if (appearance.length > 0)
+            throw invalid(appearance);
+        // Client code (client extensions spec §9.1): the section re-checked and every file against it
+        // (keys, listed = present, sizes, sha384 recomputed, the CSS layer wrap); delivered from object
+        // storage, so refused without one. The store checks the bytes it writes again. A bootstrap
+        // plugin never carries it: a bootstrap run may have no object store (it may be a bootstrap
+        // plugin itself), and a required entry failing on that would stop the start.
+        if (ext?.section.client !== undefined) {
+            if (source.kind === "bootstrap") {
+                throw new ApiError("client.invalid", `Bootstrap plugin ${m.name} ships client code (extension.client), which a bootstrap plugin may not carry: its files are kept in object storage, which a bootstrap run may not have (the object store may be a bootstrap plugin itself); take ${m.name} out of bootstrap.json and import it into the catalog instead`);
+            }
+            checkClientFiles(ext.section.client, pkg.files);
+            this.files.assertAvailable();
+        }
+        // A name live for another owner (an org's for the super admin; the platform's or another
+        // org's for an org) -> 409 plugin.name_taken naming it (P3-14); the same owner adds a version
+        await assertNameFree(this.db, m.name, owner?.orgId ?? null);
+        if (owner !== undefined) {
+            // a bootstrap or marketplace plugin's name stays free for the platform (ruling P3-28)
+            await assertNameNotReserved(this.db, m.name);
+            // its npm package is an identity of this org only (ruling P3-51)
+            await assertPackageFree(this.db, packageName, owner.orgId);
+            await assertCustomContent(this.db, content);
+        }
+        // An org's own version imported but not applied: its update is retried (pre-flight F4)
+        const retry = owner !== undefined && !m.extension
+            ? await unappliedOwnVersion(this.db, m.name, owner.orgId, {
+                packageName,
+                version: m.version,
+                contentDigest: pkg.contentDigest,
+            })
+            : undefined;
+        const { existing, version } = retry !== undefined
+            ? { existing: { id: retry.itemId }, version: retry.version }
+            : await precheckCatalogImport(this.db, m.name, {
+                packageName,
+                version: m.version,
+                contentDigest: pkg.contentDigest,
+                ...(source.integrity !== undefined && { integrity: source.integrity }),
+                ...(source.detail !== undefined && { detail: source.detail }),
+                ...(source.marketplaceId !== undefined && { marketplaceId: source.marketplaceId }),
+            });
         // The catalog name space is the extension name space: a declarative plugin cannot take a
         // config-declared or another package's extension name either
         this.assertNotDeclared(m.name);
@@ -309,8 +403,17 @@ let PluginImport = class PluginImport {
             extension = await this.reviewExtension(ext, await this.extensionState(m.name, packageName));
             await assertDowngradable(this.db, extension, ext.migrationSql);
         }
-        if (content.files.length > 0)
+        // Display files go to PG with the staging row; skills and templates need object storage, which a
+        // bootstrap import never has (the object store may be a bootstrap plugin itself). A file that is
+        // both (an icon inside a skill directory) goes to both: the readers of each look only there
+        const displayFiles = content.files.filter((f) => content.displayPaths.has(f.path));
+        const objectFiles = content.files.filter((f) => content.objectPaths.has(f.path));
+        if (objectFiles.length > 0 && retry === undefined) {
+            if (source.kind === "bootstrap" && !this.files.available) {
+                throw new ApiError("storage.unavailable", `Bootstrap plugin ${m.name} ships skills, connector templates, agent templates or themes, which are kept in object storage, and object storage is not running yet (it may be a bootstrap plugin itself); a required bootstrap plugin may ship only an icon and setup guides, an optional one is retried once the extensions have loaded`);
+            }
             this.files.assertAvailable();
+        }
         const src = {
             kind: source.kind,
             ref: source.ref,
@@ -318,7 +421,7 @@ let PluginImport = class PluginImport {
             ...(source.marketplaceId !== undefined && { marketplaceId: source.marketplaceId }),
             ...(source.detail !== undefined && { detail: source.detail }),
         };
-        const dependencies = await this.resolveDependencies(m);
+        const dependencies = await this.resolveDependencies(m, owner);
         let translation;
         if (opts.claude !== undefined) {
             const added = [
@@ -348,7 +451,8 @@ let PluginImport = class PluginImport {
             contentDigest: pkg.contentDigest,
             packageName,
             publisher: m.publisher,
-            description: m.description,
+            description: pluginDescription(m.description).en,
+            descriptionZh: pluginDescription(m.description).zh ?? null,
             ...(m.displayName !== undefined && { displayName: m.displayName }),
             ...(m.license !== undefined && { license: m.license }),
             ...(m.homepage !== undefined && { homepage: m.homepage }),
@@ -356,6 +460,7 @@ let PluginImport = class PluginImport {
             skills: content.skills,
             connectorTemplates: content.templates,
             ...(content.agentTemplates.length > 0 && { agentTemplates: content.agentTemplates }),
+            ...(content.themes.length > 0 && { themes: content.themes }),
             dependencies,
             source: src,
             provenance: (opts.provenance ?? NOT_NPM).provenance,
@@ -364,8 +469,9 @@ let PluginImport = class PluginImport {
             reviewHash: "",
         };
         review.reviewHash = pluginReviewHash(review, content.files);
-        // Re-check under the lock that the actor is still an enterprise admin before writing
-        await this.authorize(actor);
+        // Re-check under the lock that the actor is still a super admin (an org upload: an admin of
+        // the owner org) before writing
+        await this.authorize(actor, owner);
         // 2. Write: the extension into the package store, files into object storage, the staging row
         const stagingId = randomUUID();
         const itemId = existing?.id ?? randomUUID();
@@ -379,12 +485,14 @@ let PluginImport = class PluginImport {
                 }, {
                 ...(opts.actorTokenId !== undefined && { actorTokenId: opts.actorTokenId }),
                 ...(bootstrap && { store: "pg" }),
+                // an org upload only stores the package (nothing runs until the super admin confirms)
+                ...(owner !== undefined && { owner }),
             });
         }
         let objectPrefix = null;
-        if (content.files.length > 0) {
+        if (objectFiles.length > 0 && retry === undefined) {
             objectPrefix = catalogObjectPrefix(itemId, version, stagingId);
-            await putCatalogFiles(this.files, objectPrefix, content.files);
+            await putCatalogFiles(this.files, objectPrefix, objectFiles);
         }
         const keys = ext
             ? permissionKeys(permissionSetOfPackage(ext))
@@ -392,28 +500,34 @@ let PluginImport = class PluginImport {
                 .sort()
             : [];
         const mismatch = permissionsMismatch(opts.expect?.marketplace?.permissions, ext ? keys : undefined);
+        const manifest = normalizedManifest(pkg);
+        const replacements = manifest.suggestedAppearance?.replacements;
         const staged = {
             itemId,
             packageName,
             version,
             contentDigest: pkg.contentDigest,
             size: tgz.size,
-            manifest: normalizedManifest(pkg),
+            manifest,
+            ...(replacements !== undefined && { appearanceOrder: Object.keys(replacements) }),
             files: content.files.map(({ path, size, sha256 }) => ({ path, size, sha256 })),
             ...(mismatch !== null && { permissionsMismatch: mismatch }),
             sourceFormat: format,
             ...(translation !== undefined && { translation }),
             ...(license.text !== undefined && { licenseText: license.text }),
             ...(license.truncated && { licenseTruncated: true }),
+            ...(retry !== undefined && { retry: true }),
         };
-        await this.writeStaging(actor, stagingId, review, staged, objectPrefix, src, opts);
+        await this.writeStaging(actor, stagingId, review, staged, objectPrefix, src, opts, owner, displayFiles);
         return { stagingId, review, permissionKeys: keys, permissionsMismatch: mismatch };
     }
     /** The staging row and the `catalog.plugin_staged` audit, the actor re-checked under the lock. */
-    async writeStaging(actor, stagingId, review, staged, objectPrefix, src, opts) {
+    async writeStaging(actor, stagingId, review, staged, objectPrefix, src, opts, owner, displayFiles) {
         const { extension } = review;
         const t = this.db;
-        await this.authorizeActor(actor);
+        await this.authorizeActor(actor, owner);
+        // committed with the staging row that lists them (the sweep keeps what a staging lists)
+        await putDisplayFiles(t, displayFiles);
         await t
             .insertInto("plugin_import_staging")
             .values({
@@ -424,6 +538,8 @@ let PluginImport = class PluginImport {
             source: JSON.stringify(src),
             created_by: actor,
             expires_at: new Date(Date.now() + PLUGIN_STAGING_TTL_MS),
+            // the org's own staging (P3-8); null = the super admin's
+            org_id: owner?.orgId ?? null,
         })
             .execute();
         await audit(t, {
@@ -443,6 +559,8 @@ let PluginImport = class PluginImport {
                 ...(extension && {
                     extension: { sha256: extension.sha256, action: extension.action },
                 }),
+                ...(owner !== undefined && { orgId: owner.orgId }),
+                ...opts.auditDetail,
             },
         });
     }
@@ -465,9 +583,10 @@ let PluginImport = class PluginImport {
     /**
      * A staged import's review, as prepare returned it, with a marketplace import's permission
      * mismatch when there is one (the import page loads `?staging=<id>` with it). Unknown, expired or
-     * already confirmed -> 404 `plugin.staging_not_found`.
+     * already confirmed -> 404 `plugin.staging_not_found`. Each sees only its own staging (P3-8):
+     * the super admin's routes the platform's (no `owner`), an org's routes that org's.
      */
-    async staged(stagingId) {
+    async staged(stagingId, owner) {
         if (!UUID_RE.test(stagingId))
             throw notFound();
         const row = await this.db
@@ -475,6 +594,7 @@ let PluginImport = class PluginImport {
             .select(["id", "review", "manifest"])
             .where("id", "=", stagingId)
             .where("expires_at", ">", sql `now()`)
+            .where(ownStaging(owner))
             .executeTakeFirst();
         if (!row)
             throw notFound();
@@ -486,17 +606,117 @@ let PluginImport = class PluginImport {
         };
     }
     /**
-     * Confirms a staged import (see the file header). Returns the committed catalog item and, with
-     * `deployExtension`, the extension's deploy result (a failed deploy is returned, not thrown).
+     * What an org's staged upload targets (P3-12, pre-flight F3): its item, version and review hash,
+     * whether the item exists (a new version of the org's own plugin) or the version is imported
+     * already (F4), and the target as the platform updater reads it: the staged manifest and files,
+     * or the imported version's for a retry. Another org's staging -> 404 `plugin.staging_not_found`.
+     */
+    async stagedTarget(stagingId, owner) {
+        if (!UUID_RE.test(stagingId))
+            throw notFound();
+        const row = await this.db
+            .selectFrom("plugin_import_staging")
+            .select(["review", "manifest", "object_prefix"])
+            .where("id", "=", stagingId)
+            .where("expires_at", ">", sql `now()`)
+            .where(ownStaging(owner))
+            .executeTakeFirst();
+        if (!row)
+            throw notFound();
+        const review = row.review;
+        const staged = row.manifest;
+        const item = await this.db
+            .selectFrom("catalog_items")
+            .select(["id", "awaiting_confirmation"])
+            .where("id", "=", staged.itemId)
+            .where("deleted_at", "is", null)
+            .where("owner_org_id", "=", owner.orgId)
+            .executeTakeFirst();
+        const imported = staged.retry === true
+            ? await this.db
+                .selectFrom("catalog_item_versions")
+                .select(["version", "manifest", "object_prefix", "files", "extension_sha256"])
+                .where("item_id", "=", staged.itemId)
+                .where("version", "=", staged.version)
+                .executeTakeFirst()
+            : undefined;
+        return {
+            itemId: staged.itemId,
+            version: staged.version,
+            reviewHash: review.reviewHash,
+            extension: review.extension !== undefined,
+            existing: item !== undefined,
+            awaiting: item?.awaiting_confirmation === true,
+            retry: staged.retry === true,
+            target: imported !== undefined
+                ? {
+                    version: imported.version,
+                    manifest: imported.manifest,
+                    object_prefix: imported.object_prefix,
+                    files: imported.files,
+                    extension_sha256: imported.extension_sha256,
+                }
+                : {
+                    version: staged.version,
+                    manifest: staged.manifest,
+                    object_prefix: row.object_prefix,
+                    files: staged.files,
+                    extension_sha256: review.extension?.sha256 ?? null,
+                },
+        };
+    }
+    /** The catalog item's view (as a confirm returns it). */
+    async view(itemId) {
+        return this.itemView(itemId);
+    }
+    /**
+     * Confirms a staged import (see the file header). Returns the committed catalog item and the
+     * extension's deploy result (a failed deploy is returned, not thrown). `scope` (default
+     * `optional`) and `orgs` (only with `named`; each an existing org, else `validation_failed`) are
+     * written when this confirm creates the item; a new version of an existing item keeps its scope.
+     * The caller enqueues the scope sync of the item after this returns.
+     *
+     * An org upload (`opts.owner`, spec §14): only that org's staging; the actor re-checked as its
+     * admin; `scope` / `orgs` are not taken: a new item is owned by the org, scope `named: [owner]`,
+     * not shown to other orgs, `shareable` as given (default false). Custom deny, the name owner and
+     * the dependencies are checked again under the item name's lock. A package with an extension
+     * is stored and its extension name claimed, nothing approved or installed: the version waits
+     * for the super admin (`pending`, ruling P3-10; see {@link commit}).
      */
     async confirm(actor, stagingId, input, opts = {}) {
         if (!UUID_RE.test(stagingId))
             throw notFound();
+        const owner = opts.owner;
+        if (owner !== undefined && (input.scope !== undefined || input.orgs !== undefined)) {
+            throw new Error("an org upload's scope is its owner's");
+        }
+        // A staging prepared by approving an org's `import` request defaults to that org (spec §5.1
+        // rule 3); the admin may still choose any scope
+        const linked = input.scope === undefined && owner === undefined
+            ? await importRequestOf(this.db, stagingId)
+            : undefined;
+        const scope = owner !== undefined
+            ? "named"
+            : (input.scope ?? (linked !== undefined ? "named" : "optional"));
+        const orgs = owner !== undefined
+            ? [owner.orgId]
+            : (input.orgs ?? (linked !== undefined ? [linked.orgId] : undefined));
+        if (input.orgs !== undefined && scope !== "named") {
+            throw new ApiError("validation_failed", "orgs: only allowed with scope named", [
+                { path: "orgs", message: "only allowed with scope named" },
+            ]);
+        }
+        if (scope === "named" && (orgs ?? []).length === 0) {
+            throw new ApiError("validation_failed", "orgs: scope named needs at least one organization", [
+                { path: "orgs", message: "scope named needs at least one organization" },
+            ]);
+        }
         const row = await this.db
             .selectFrom("plugin_import_staging")
             .selectAll()
             .where("id", "=", stagingId)
             .where("expires_at", ">", sql `now()`)
+            .where(ownStaging(owner))
             .executeTakeFirst();
         if (!row)
             throw notFound();
@@ -507,34 +727,108 @@ let PluginImport = class PluginImport {
             throw reviewStale(review);
         const manifest = withPinned(staged.manifest, review, input.pinnedSuggestions);
         const reviewed = review.extension;
-        // Read the stored package outside the transaction (unless it was already installed as is)
-        const stored = reviewed && reviewed.action !== "keep" ? await this.readStored(reviewed.sha256) : undefined;
-        const committed = await this.commit(actor, { stagingId, review, staged, src, manifest, objectPrefix: row.object_prefix }, input, stored, opts);
+        // Read the stored package outside the transaction (unless it was already installed as is, or
+        // an org upload, which approves nothing)
+        const stored = reviewed && reviewed.action !== "keep" && owner === undefined
+            ? await this.readStored(reviewed.sha256)
+            : undefined;
+        const committed = await this.commit(actor, { stagingId, review, staged, src, manifest, objectPrefix: row.object_prefix }, {
+            scope,
+            orgs: [...new Set(orgs ?? [])].sort(),
+            ...(owner !== undefined && { owner, shareable: input.shareable ?? false }),
+        }, stored, opts);
         const { now } = committed;
-        const deploy = input.deployExtension && now && now.action !== "keep"
+        if (committed.pending) {
+            // Waits for the super admin (P3-10): no platform components, nothing deployed
+            return {
+                item: await this.itemView(committed.itemId),
+                created: committed.created,
+                deploy: null,
+                pending: true,
+                firstVersion: false,
+            };
+        }
+        // A new item's skills, agent templates and connector templates become platform components
+        // (plugin scope phase 2); a new version of an existing item leaves them to the platform
+        // update. After the commit: it copies files in object storage
+        if (committed.firstVersion)
+            await this.syncPlatform(committed.itemId, staged.version);
+        const deploy = now && now.action !== "keep"
             ? await this.deploy(actor, review, committed.itemId, now, committed.previous, opts, input.enable ?? true)
             : null;
-        return { item: await this.itemView(committed.itemId), deploy };
+        return {
+            item: await this.itemView(committed.itemId),
+            created: committed.created,
+            deploy,
+            pending: false,
+            firstVersion: committed.firstVersion,
+        };
+    }
+    /**
+     * Writes the platform components of an item's first usable version after a commit made
+     * elsewhere (the super admin's confirmation of an org upload, `CatalogScopeService`); a failure
+     * is logged and retried by the migration job (see {@link syncPlatform}).
+     */
+    async writePlatformComponents(itemId, version) {
+        await this.syncPlatform(itemId, version);
     }
     /**
      * The confirm's transaction: the staging row consumed, the extension's action recomputed under
      * its install lock (stale -> `plugin.review_stale`), its snapshot approved, and the catalog
      * version written under the item name's lock.
+     *
+     * An org upload with an extension (ruling P3-10) approves nothing: under the install lock it
+     * claims the extension name for its package (another package's -> 409
+     * `extension.name_conflict` naming its owner, before anything is written), and the version
+     * written becomes the item's pending one (`pending_version` / `_by` / `_at`; a first version
+     * also `awaiting_confirmation`). A later upload replaces the pending version (P3-11). An org
+     * upload without an extension for an item whose first version still waits (plan Task 6) replaces
+     * that upload and applies at once: the item stops waiting and the claim is released (nothing
+     * was installed under it).
      */
-    async commit(actor, c, input, stored, opts) {
+    async commit(actor, c, scope, stored, opts) {
         const { stagingId, review, staged, src, manifest } = c;
         const reviewed = review.extension;
         const stale = () => reviewStale(review);
-        await this.authorizeActor(actor);
+        const { owner } = scope;
+        await this.authorizeActor(actor, owner);
         const t = this.db;
         const used = await t
             .deleteFrom("plugin_import_staging")
             .where("id", "=", stagingId)
             .where("expires_at", ">", sql `now()`)
+            .where(ownStaging(owner))
             .returning("id")
             .executeTakeFirst();
         if (!used)
             throw notFound();
+        if (owner !== undefined) {
+            await assertCustomContent(t, {
+                skills: review.skills,
+                agentTemplates: review.agentTemplates ?? [],
+                templates: review.connectorTemplates,
+            });
+        }
+        await assertOrgsExist(t, scope.orgs);
+        // Checked again before this upload claims anything (ruling P3-51)
+        if (owner !== undefined)
+            await assertPackageFree(t, staged.packageName, owner.orgId);
+        // The item's name lock and its live row before the extension's install lock: the global lock
+        // order is the item, then the install lock (ruling P3-50; ExtensionAdminOps.install locks the
+        // source item row before the install lock, an org deletion its items before it). Taken after
+        // the install lock instead, a confirmation of an org upload racing a replacement upload
+        // deadlocks (40P01).
+        const m = manifest;
+        await this.itemLock.lock(m.name);
+        // The scope the audit records: the review's for a new item, the item's own for a new version
+        // of a live item (which keeps its scope)
+        const existing = await t
+            .selectFrom("catalog_items")
+            .select(["id", "scope", "awaiting_confirmation", "package_name"])
+            .where("name", "=", m.name)
+            .where("deleted_at", "is", null)
+            .forUpdate()
+            .executeTakeFirst();
         let now;
         let previous;
         if (reviewed) {
@@ -544,23 +838,73 @@ let PluginImport = class PluginImport {
             await this.installLock.lock(reviewed.name);
             now = {
                 ...reviewed,
-                ...actionOf(await this.extensionState(reviewed.name, staged.packageName), reviewed.sha256),
+                ...actionOf(await this.extensionState(reviewed.name, staged.packageName), reviewed.sha256, reviewed.version),
             };
             if (pluginReviewHash({ ...review, extension: now }, staged.files) !== review.reviewHash) {
                 throw stale();
             }
+            if (owner !== undefined) {
+                // An org upload only claims the name (P3-10): the super admin approves and installs it
+                await t
+                    .insertInto("extension_name_owners")
+                    .values({ name: reviewed.name, package_name: staged.packageName })
+                    .onConflict((oc) => oc.column("name").doNothing())
+                    .execute();
+                await assertPluginNameOwner(t, reviewed.name, staged.packageName);
+            }
             // A foreseeable deploy failure (a downgrade to a version with unrun migrations) is refused
             // before anything is written
-            if (input.deployExtension && now.action === "upgrade" && stored) {
+            if (now.action === "upgrade" && stored) {
                 await assertDowngradable(t, now, stored.migrationSql);
             }
-            if (now.action === "install" || (now.action === "upgrade" && input.deployExtension)) {
+            if (owner === undefined && (now.action === "install" || now.action === "upgrade")) {
                 previous = await this.approve(actor, review, staged, now, stored, opts);
             }
         }
-        const m = manifest;
-        await this.itemLock.lock(m.name);
-        const itemId = await writeCatalogVersion(t, {
+        // Under the name's lock: the first confirm of a name wins, a later one of another owner is
+        // refused naming it, before anything of it is written (P3-14)
+        await assertNameFree(t, m.name, owner?.orgId ?? null);
+        if (owner !== undefined) {
+            await assertNameNotReserved(t, m.name);
+            await this.resolveDependencies(m, owner);
+        }
+        const actual = existing === undefined
+            ? scope
+            : {
+                scope: existing.scope,
+                orgs: (await t
+                    .selectFrom("catalog_item_scope_orgs")
+                    .select("org_id")
+                    .where("item_id", "=", existing.id)
+                    .orderBy("org_id")
+                    .execute()).map((r) => r.org_id),
+            };
+        if (staged.retry === true) {
+            // An org's own version imported already (pre-flight F4): nothing to write, the caller
+            // retries its update; it must still be there as reviewed
+            const v = existing === undefined
+                ? undefined
+                : await t
+                    .selectFrom("catalog_item_versions")
+                    .select("version")
+                    .where("item_id", "=", existing.id)
+                    .where("version", "=", staged.version)
+                    .where("content_digest", "=", staged.contentDigest)
+                    .executeTakeFirst();
+            if (existing === undefined || existing.id !== staged.itemId || v === undefined)
+                throw stale();
+            return {
+                itemId: existing.id,
+                created: false,
+                firstVersion: false,
+                pending: false,
+                now,
+                previous,
+            };
+        }
+        const { id: itemId, created } = await writeCatalogVersion(t, {
+            // an org's version becomes its latest only when applied or confirmed (P3-34)
+            ...(owner !== undefined && { keepLatest: true }),
             actor,
             ...(opts.actorTokenId !== undefined && { actorTokenId: opts.actorTokenId }),
             name: m.name,
@@ -568,9 +912,10 @@ let PluginImport = class PluginImport {
             version: staged.version,
             contentDigest: staged.contentDigest,
             manifest: m,
+            appearanceOrder: staged.appearanceOrder ?? null,
             listing: {
                 publisher: m.publisher,
-                description: m.description,
+                description: pluginDescription(m.description).en,
                 displayName: m.displayName ?? null,
             },
             newItemId: staged.itemId,
@@ -591,12 +936,144 @@ let PluginImport = class PluginImport {
             licenseTruncated: staged.licenseTruncated === true,
             auditDetail: {
                 stagingId,
-                deployExtension: input.deployExtension,
+                scope: actual.scope,
+                ...(actual.scope === "named" && { orgs: actual.orgs }),
                 suggestedPinned: pinnedNames(manifest, review),
                 ...(now && { extension: { name: now.name, version: now.version, action: now.action } }),
             },
         });
-        return { itemId, now, previous };
+        // A new item gets the scope chosen in the review; a new version keeps the item's scope, its
+        // org list and its scope version (prepare reuses the live item's id, so the id cannot tell)
+        if (created) {
+            await t
+                .updateTable("catalog_items")
+                .set({
+                scope: scope.scope,
+                // an org upload: the org owns it, nobody else sees it until shared and shown (P3-16)
+                ...(owner !== undefined && {
+                    owner_org_id: owner.orgId,
+                    shareable: scope.shareable === true,
+                    shown_to_others: false,
+                }),
+            })
+                .where("id", "=", itemId)
+                .execute();
+            if (scope.scope === "named" && scope.orgs.length > 0) {
+                await t
+                    .insertInto("catalog_item_scope_orgs")
+                    .values(scope.orgs.map((org_id) => ({ item_id: itemId, org_id })))
+                    .onConflict((oc) => oc.doNothing())
+                    .execute();
+            }
+        }
+        // The org requests this staging answers resolve with the confirm; on an item that existed
+        // already (imported meanwhile) a `named` scope gains their orgs. An org-owned item held back by
+        // the share gate fails closed before any request is marked (ruling P3-26; P3-14 refuses a
+        // super admin import of an org-owned name, so this should not be reached)
+        const item = created
+            ? undefined
+            : await t
+                .selectFrom("catalog_items")
+                .select(["id", "name", "scope", "builtin", "owner_org_id", "shareable"])
+                .where("id", "=", itemId)
+                .forUpdate()
+                .executeTakeFirstOrThrow();
+        if (item !== undefined && !shareGate(item) && (await hasImportRequests(t, stagingId))) {
+            assertShareable(item);
+        }
+        const requestOrgs = await resolveImportRequests(t, stagingId, itemId, actor, opts);
+        if (item !== undefined) {
+            for (const org of requestOrgs)
+                await addScopeOrg(t, actor, item, org, opts);
+        }
+        const pending = owner !== undefined && reviewed !== undefined;
+        // An org's first version without an extension is installed at once: applied (P3-52)
+        if (owner !== undefined && created && !pending)
+            await markVersionApplied(t, itemId, staged.version);
+        if (pending) {
+            // Waits for the super admin; a later upload replaces the pending version (P3-10, P3-11)
+            await t
+                .updateTable("catalog_items")
+                .set({
+                ...(created && { awaiting_confirmation: true }),
+                pending_version: staged.version,
+                pending_by: actor,
+                pending_at: sql `now()`,
+            })
+                .where("id", "=", itemId)
+                .execute();
+        }
+        // A first version still waiting replaced by one without an extension: applied at once
+        const replacedAwaiting = owner !== undefined && !pending && existing?.awaiting_confirmation === true;
+        if (replacedAwaiting) {
+            await t
+                .updateTable("catalog_items")
+                .set({
+                awaiting_confirmation: false,
+                pending_version: null,
+                pending_by: null,
+                pending_at: null,
+                latest_version: staged.version,
+            })
+                .where("id", "=", itemId)
+                .execute();
+            await markVersionApplied(t, itemId, staged.version);
+            await releaseExtensionClaim(t, m.name, existing.package_name);
+        }
+        return {
+            itemId,
+            created,
+            firstVersion: (created && !pending) || replacedAwaiting,
+            pending,
+            now,
+            previous,
+        };
+    }
+    /**
+     * The platform components of a new item. The item is committed already, so a failure is logged
+     * and not thrown (like a failed deploy, the import itself succeeded); a run of the platform
+     * components migration job (which writes what is missing) is enqueued on `cap-kernel-maintenance`
+     * after {@link PLATFORM_SYNC_RETRY_MS}, one per item (deterministic job id). If that run fails
+     * too, its `itemsFailed` shows in the super admin's inbox; the daily run and every worker start
+     * try again.
+     */
+    async syncPlatform(itemId, version) {
+        try {
+            await this.platform.syncFromVersion(itemId, version, { initial: true });
+        }
+        catch (err) {
+            // Removed meanwhile (an org deletion racing a confirmation, P3-20): nothing to write
+            const live = await this.db
+                .selectFrom("catalog_items")
+                .select("id")
+                .where("id", "=", itemId)
+                .where("deleted_at", "is", null)
+                .executeTakeFirst();
+            if (live === undefined) {
+                this.log.info("catalog item removed before its platform components were written", {
+                    itemId,
+                    version,
+                });
+                return;
+            }
+            this.log.error("writing the platform components of a new catalog item failed", {
+                itemId,
+                version,
+                err,
+            });
+            try {
+                await this.maintenance.add(PLATFORM_MIGRATION_JOB, {}, {
+                    jobId: `${PLATFORM_MIGRATION_JOB}-retry-${itemId}`,
+                    delay: PLATFORM_SYNC_RETRY_MS,
+                    attempts: 1,
+                    removeOnComplete: true,
+                    removeOnFail: { age: 86_400 },
+                });
+            }
+            catch (e) {
+                this.log.warn("cannot enqueue the platform components migration", { itemId, err: e });
+            }
+        }
     }
     /**
      * Writes the extension's permission snapshot for the version being imported (source web; cli
@@ -644,7 +1121,9 @@ let PluginImport = class PluginImport {
     }
     /**
      * Deploys the plugin's extension after the commit: `install` (a new install is disabled, a version
-     * change keeps the desired state) then `enable`. Nothing is thrown; the result says what happened.
+     * change keeps the desired state) then `enable`, unless another enabled extension provides one of
+     * its single-provider extension points: then it stays disabled (result `installed` with code
+     * `extension.single_provider_enabled`). Nothing is thrown; the result says what happened.
      * When an upgrade was not installed, the snapshot overwritten at confirm is restored (the old
      * version keeps running, F-O; audit `extension.permissions_restored`). Retry through the extension
      * admin (the package is already in the package store) with the sha256 from the result.
@@ -659,8 +1138,9 @@ let PluginImport = class PluginImport {
         const failure = (e) => e instanceof ApiError
             ? { code: e.code, message: e.message }
             : { code: "internal", message: "Internal error" };
+        let installed;
         try {
-            await this.ops.install(p.name, p.sha256, actor, opts.actorTokenId, {
+            installed = await this.ops.install(p.name, p.sha256, actor, opts.actorTokenId, {
                 catalogItemId: itemId,
             });
         }
@@ -686,11 +1166,19 @@ let PluginImport = class PluginImport {
             }
             return result;
         }
+        // An upgrade of an enabled extension that newly provides a held single-provider point: left
+        // disabled by the install, and why
+        if (installed.leftDisabled !== undefined) {
+            return { ...base, result: "installed", ...installed.leftDisabled };
+        }
         if (!enable)
             return { ...base, result: "installed" };
         try {
-            await this.ops.enable(p.name, actor, opts.actorTokenId);
-            return { ...base, result: "enabled" };
+            const r = await this.ops.enableUnlessOccupied(p.name, actor, opts.actorTokenId);
+            if (r.enabled)
+                return { ...base, result: "enabled" };
+            // A single-provider point another enabled extension provides: installed disabled, and why
+            return { ...base, result: "installed", ...r.note };
         }
         catch (e) {
             this.log.warn("enabling a plugin's extension failed", { plugin: p.name, err: e });
@@ -745,11 +1233,24 @@ let PluginImport = class PluginImport {
         return true;
     }
     /**
-     * Deletes expired staging rows and their object prefixes (maintenance job `app-staging-cleanup`).
-     * Row by row: objects first, then the row (a failed object delete keeps the row for the next
-     * round); concurrent replicas skip each other's rows (`SKIP LOCKED`). Returns the rows deleted.
+     * Deletes expired staging rows and their object prefixes (maintenance job `app-staging-cleanup`),
+     * then the unused display files ({@link sweepDisplayFiles}). Row by row: objects first, then the
+     * row (a failed object delete keeps the row for the next round); concurrent replicas skip each
+     * other's rows (`SKIP LOCKED`). Returns the rows deleted.
      */
     async cleanupExpired() {
+        const total = await this.cleanupStagingRows();
+        // display files no version or staging lists (an abandoned import's), older than a staging
+        try {
+            await sweepDisplayFiles(this.db, PLUGIN_STAGING_TTL_MS);
+        }
+        catch (err) {
+            this.log.warn("cannot sweep unused catalog display files", { err });
+        }
+        return total;
+    }
+    /** The expired staging rows, batch by batch; returns the rows deleted. */
+    async cleanupStagingRows() {
         let total = 0;
         for (;;) {
             const batch = await this.db
@@ -786,7 +1287,7 @@ let PluginImport = class PluginImport {
         const t = this.db;
         const locked = await t
             .selectFrom("plugin_import_staging")
-            .select("id")
+            .select(["id", "org_id", "review", "manifest"])
             .where("id", "=", r.id)
             .where("expires_at", "<=", sql `now()`)
             .forUpdate()
@@ -797,8 +1298,86 @@ let PluginImport = class PluginImport {
         if (r.object_prefix)
             await this.files.deployment().deletePrefix(r.object_prefix);
         await t.deleteFrom("plugin_import_staging").where("id", "=", r.id).execute();
+        await this.dropOrgPackage(locked);
         return true;
     }
+    /**
+     * An expired org staging's extension package (an org upload stores it at prepare, P3-10): removed
+     * with the staging unless something else uses it — an install (running or migrated), a catalog
+     * version, another staging — or it was stored by anyone else (the package row's source must be
+     * this staging's own `catalog` ref). A platform staging keeps its package, as before. Its object
+     * is deleted after the commit.
+     */
+    async dropOrgPackage(row) {
+        const sha = row.review.extension?.sha256;
+        if (row.org_id === null || sha === undefined)
+            return;
+        const staged = row.manifest;
+        const t = this.db;
+        const pkg = await t
+            .selectFrom("extension_packages")
+            .select("blob_store")
+            .where("sha256", "=", sha)
+            .where("source", "=", "catalog")
+            .where("source_ref", "=", `${staged.itemId}@${staged.version}`)
+            .forUpdate()
+            .executeTakeFirst();
+        if (!pkg)
+            return;
+        const used = (await t
+            .selectFrom("extension_installs")
+            .select("name")
+            .where((eb) => eb.or([eb("sha256", "=", sha), eb("migrated_sha", "=", sha)]))
+            .executeTakeFirst()) ??
+            (await t
+                .selectFrom("catalog_item_versions")
+                .select("version")
+                .where("extension_sha256", "=", sha)
+                .executeTakeFirst()) ??
+            (await t
+                .selectFrom("plugin_import_staging")
+                .select("id")
+                .where(sql `review->'extension'->>'sha256' = ${sha}`)
+                .executeTakeFirst());
+        if (used !== undefined)
+            return;
+        const build = await t
+            .selectFrom("extension_client_builds")
+            .select("object_prefix")
+            .where("package_sha256", "=", sha)
+            .executeTakeFirst();
+        // extension_blobs (a PG-stored package) and extension_client_builds go with the row (ON
+        // DELETE CASCADE)
+        await t.deleteFrom("extension_packages").where("sha256", "=", sha).execute();
+        if (build !== undefined) {
+            afterCommit(async () => {
+                try {
+                    await this.clientBuilds.deleteFiles(sha, build.object_prefix);
+                }
+                catch (err) {
+                    this.log.warn("cannot delete an expired org upload's client build objects", {
+                        sha256: sha,
+                        err,
+                    });
+                }
+            });
+        }
+        // The object only once the row is gone for good: a failure leaves an unreferenced object
+        // (harmless; a later upload of the same bytes rewrites it), never a row without its bytes
+        if (pkg.blob_store === "object") {
+            afterCommit(async () => {
+                try {
+                    await this.files.deployment().delete(blobKey(sha));
+                }
+                catch (err) {
+                    this.log.warn("cannot delete an expired org upload's extension package object", {
+                        sha256: sha,
+                        err,
+                    });
+                }
+            });
+        }
+    }
     // ---------------------------------------------------------------------------------------------
     /** npm / marketplace imports: the package must be the one that was asked for. */
     checkExpected(pkg, expect, format = "capybara") {
@@ -845,8 +1424,16 @@ let PluginImport = class PluginImport {
             if (data !== undefined && !stored.has(path))
                 stored.set(path, fileOf(path, data));
         };
-        if (m.icon !== undefined)
-            keep(packagePath(m.icon));
+        const objectPaths = new Set();
+        const keepObject = (path) => {
+            keep(path);
+            if (stored.has(path))
+                objectPaths.add(path);
+        };
+        // The plugin icon and the setup guide documents (rendered by PluginGuides): display files
+        const displayPaths = displayFilePaths(m, pkg.connectorTemplates.flatMap((c) => (c.file.icon === undefined ? [] : [c.file.icon])));
+        for (const path of displayPaths)
+            keep(path);
         const skills = [];
         for (const s of pkg.skills) {
             const files = s.files.map((f) => fileOf(f, pkg.files.get(`${s.dir}/${f}`)));
@@ -865,7 +1452,7 @@ let PluginImport = class PluginImport {
                     suggestPinned: pinned.get(s.dir) === true,
                 });
                 for (const f of s.files)
-                    keep(`${s.dir}/${f}`);
+                    keepObject(`${s.dir}/${f}`);
             }
             catch (e) {
                 if (!(e instanceof SkillArchiveError))
@@ -909,10 +1496,8 @@ let PluginImport = class PluginImport {
             else {
                 problems.push(`${at}.connector: extension ${t.plugin} providing connector "${t.connector}" is not loaded in this deployment and is neither this plugin's extension nor a dependency`);
             }
-            keep(c.path);
+            keepObject(c.path);
             templatePaths.set(c.id, c.path);
-            if (c.file.icon !== undefined)
-                keep(packagePath(c.file.icon));
             return {
                 id: c.id,
                 displayName: c.file.displayName,
@@ -926,43 +1511,89 @@ let PluginImport = class PluginImport {
             };
         });
         const agentTemplates = pkg.agentTemplates.map((a) => {
-            keep(a.path);
+            keepObject(a.path);
             const { name, description, instructions, model, ...rest } = a.template;
             return { name, path: a.path, description, instructions, model: model ?? "inherit", ...rest };
         });
+        // Themes: the file as written, the assets as sanitized by the reader (never the uploaded
+        // originals: a shared path, e.g. the plugin icon, is stored sanitized too)
+        const themes = pkg.themes.map((t) => {
+            keepObject(t.path);
+            for (const [path, data] of t.assets) {
+                stored.set(path, fileOf(path, data));
+                objectPaths.add(path);
+            }
+            const logo = t.theme.logo;
+            return {
+                id: t.id,
+                name: t.theme.name,
+                schemes: ["dark", "light"].filter((k) => t.theme.schemes[k] !== undefined),
+                fonts: t.theme.fonts?.length ?? 0,
+                logo: logo !== undefined && Object.keys(logo).length > 0,
+            };
+        });
         if (problems.length > 0)
             throw invalid(problems);
         return {
             files: [...stored.values()],
+            displayPaths,
+            objectPaths,
             templates,
             skills,
             agentTemplates,
+            themes,
             notLoaded,
             templatePaths,
         };
     }
     /**
      * The highest imported, non-deleted catalog version satisfying each dependency's range (null when
-     * none does).
+     * none does). An org upload (`owner`, P3-13) resolves only against items the org can use
+     * ({@link usableBy}: confirmed, not disabled, offered to it), and any dependency left unresolved
+     * -> 409 `plugin.dependency_unavailable` (details `[{ dependencies }]`, their names): an org
+     * upload never brings in anything the org could not install itself.
      */
-    async resolveDependencies(m) {
+    async resolveDependencies(m, owner) {
         const deps = m.dependencies ?? [];
         if (deps.length === 0)
             return [];
-        const rows = await this.db
+        const names = deps.map((d) => d.name);
+        const versions = this.db
             .selectFrom("catalog_items as i")
             .innerJoin("catalog_item_versions as v", "v.item_id", "i.id")
-            .select(["i.name", "v.version", "v.imported_at"])
             .where("i.deleted_at", "is", null)
-            .where("i.name", "in", deps.map((d) => d.name))
-            .execute();
-        return deps.map((d) => ({
+            .where("i.name", "in", names);
+        const rows = owner === undefined
+            ? await versions.select(["i.name", "v.version", "v.imported_at"]).execute()
+            : (await versions
+                // the org's own row of a `named` list (usableBy reads whether it is listed)
+                .leftJoin("catalog_item_scope_orgs as so", (j) => j.onRef("so.item_id", "=", "i.id").on("so.org_id", "=", owner.orgId))
+                .select([
+                "i.name",
+                "v.version",
+                "v.imported_at",
+                "i.scope",
+                "i.builtin",
+                "i.disabled",
+                "i.deleted_at",
+                "i.awaiting_confirmation",
+                "i.owner_org_id",
+                "i.shareable",
+                "so.org_id as listed",
+            ])
+                .execute()).filter((r) => usableBy(r, owner.orgId, r.listed !== null));
+        const resolved = deps.map((d) => ({
             name: d.name,
             range: d.version,
             resolved: maxSatisfying(rows
                 .filter((r) => r.name === d.name)
                 .map((r) => ({ version: r.version, importedAt: r.imported_at })), d.version)?.version ?? null,
         }));
+        const missing = resolved.filter((d) => d.resolved === null).map((d) => d.name);
+        if (owner !== undefined && missing.length > 0) {
+            throw new ApiError("plugin.dependency_unavailable", `Dependencies not available to this organization: ${missing.join(", ")}`, [{ dependencies: missing }]);
+        }
+        return resolved;
     }
     /**
      * The extension's state on the deployment; installed from another npm package ->
@@ -980,7 +1611,7 @@ let PluginImport = class PluginImport {
             .where("extension_installs.name", "=", name)
             .executeTakeFirst();
         if (r && r.package_name !== packageName) {
-            throw new ApiError("extension.name_conflict", `Extension ${name} is already installed from package ${r.package_name}; package ${packageName} cannot use it`);
+            throw new ApiError("extension.name_conflict", `Extension ${name} is already installed from package ${r.package_name}; package ${packageName} cannot use it`, [{ owner: await packageOwner(this.db, r.package_name, name) }]);
         }
         return r
             ? { kind: "installed", version: r.version, sha256: r.sha256, packageName: r.package_name }
@@ -1002,7 +1633,7 @@ let PluginImport = class PluginImport {
             name,
             version: pkg.section.version,
             sha256: pkg.sha256,
-            ...actionOf(state, pkg.sha256),
+            ...actionOf(state, pkg.sha256, pkg.section.version),
             permissions,
             added,
             addedItems: permissionKeyItems(added),
@@ -1010,6 +1641,7 @@ let PluginImport = class PluginImport {
             warnings,
             reviewHash: extensionReviewHash(set, warnings),
             sensitive: permissions.some((g) => g.sensitive) || warnings.length > 0,
+            ...(pkg.section.client !== undefined && { client: reviewClient(pkg) }),
         };
     }
     async readStored(sha256) {
@@ -1027,10 +1659,11 @@ let PluginImport = class PluginImport {
             .executeTakeFirstOrThrow();
         const versions = await this.db
             .selectFrom("catalog_item_versions")
-            .select(["version", "source", "imported_at"])
+            .select(["version", "source", "imported_at", "extension_sha256", "manifest", "source_format"])
             .where("item_id", "=", itemId)
             .execute();
-        return itemView(item, versions);
+        const facts = await itemScopeFacts(this.db, [item], await itemConfirmations(this.admin, [item], new Map([[item.id, versions]])));
+        return itemView(item, versions, 0, undefined, facts.get(item.id));
     }
 };
 __decorate([
@@ -1054,21 +1687,29 @@ __decorate([
 __decorate([
     Transactional()
 ], PluginImport.prototype, "cleanupOne", null);
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], PluginImport.prototype, "dropOrgPackage", null);
 PluginImport = __decorate([
     Injectable(),
     __param(0, Inject(KernelDb)),
-    __param(1, Inject(EnterpriseAdminLock)),
-    __param(2, Inject(PluginInstallLock)),
-    __param(3, Inject(PluginApproveLock)),
-    __param(4, Inject(CatalogItemLock)),
-    __param(5, Inject(KernelConfigService)),
-    __param(6, Inject(StorageService)),
-    __param(7, Inject(ExtensionInstalls)),
-    __param(8, Inject(ExtensionAdminOps)),
-    __param(9, Inject(ExtensionBlobs)),
-    __param(10, Inject(ExtensionRegistry)),
-    __param(11, Inject(KERNEL_LOGGER)),
-    __param(12, Inject(TransactionHost))
+    __param(1, Inject(SuperAdminLock)),
+    __param(2, Inject(OrgLock)),
+    __param(3, Inject(PluginInstallLock)),
+    __param(4, Inject(PluginApproveLock)),
+    __param(5, Inject(CatalogItemLock)),
+    __param(6, Inject(KernelConfigService)),
+    __param(7, Inject(StorageService)),
+    __param(8, Inject(ExtensionInstalls)),
+    __param(9, Inject(ExtensionAdminOps)),
+    __param(10, Inject(ExtensionAdmin)),
+    __param(11, Inject(ExtensionBlobs)),
+    __param(12, Inject(ExtensionRegistry)),
+    __param(13, Inject(KERNEL_LOGGER)),
+    __param(14, Inject(TransactionHost)),
+    __param(15, Inject(PlatformComponents)),
+    __param(16, Inject(getQueueToken(MAINTENANCE_QUEUE_NAME))),
+    __param(17, Inject(ClientBuilds))
 ], PluginImport);
 export { PluginImport };
 /**
@@ -1077,7 +1718,7 @@ export { PluginImport };
  */
 function normalizedManifest(pkg) {
     const pinned = new Map((pkg.manifest.skills ?? []).map((s) => [packagePath(s.path), s.pinned]));
-    const { agents: _, ...manifest } = pkg.manifest;
+    const { agents: _, themes: __, ...manifest } = pkg.manifest;
     return {
         ...manifest,
         skills: pkg.skills.map((s) => {
@@ -1089,6 +1730,7 @@ function normalizedManifest(pkg) {
         ...(pkg.agentTemplates.length > 0 && {
             agents: pkg.agentTemplates.map((a) => ({ path: `./${a.path}` })),
         }),
+        ...(pkg.themes.length > 0 && { themes: pkg.themes.map((t) => ({ path: `./${t.path}` })) }),
     };
 }
 /** package.json `name`, or null without one (a git plugin; never the string "undefined"). */
@@ -1097,13 +1739,20 @@ function packageNameOf(pkg) {
     return typeof name === "string" ? name : null;
 }
 /** The extension's deployment state -> action and current version. */
-function actionOf(s, sha256) {
+function actionOf(s, sha256, version) {
     if (s.kind === "installed") {
+        // A version below the deployed one is recorded in the catalog only: an import never
+        // downgrades the deployment (ruling H)
+        const older = s.sha256 !== sha256 &&
+            semver.valid(version) !== null &&
+            semver.valid(s.version) !== null &&
+            semver.lt(version, s.version);
         return {
-            action: s.sha256 === sha256 ? "keep" : "upgrade",
+            action: s.sha256 === sha256 || older ? "keep" : "upgrade",
             deployed: true,
             currentVersion: s.version,
             currentSha256: s.sha256,
+            ...(older && { olderThanDeployed: true }),
         };
     }
     return { action: "install", deployed: false, currentVersion: null, currentSha256: null };
@@ -1113,13 +1762,17 @@ function actionOf(s, sha256) {
  * current version / package, its own review digest), every template field, each skill's name / path
  * / file count, the dependency resolution, the sha256 of every stored file, the format, the
  * translation report's items, the sha256 of the license text and the two review flags
- * (`claudeManifestIgnored`, `licenseTruncated`), and the agent templates when there are any.
+ * (`claudeManifestIgnored`, `licenseTruncated`), the agent templates when there are any and the
+ * themes when there are any.
  * Exported for tests. `repository` is display only.
  */
 export function pluginReviewHash(r, files) {
     const e = r.extension;
     const lic = r.licenseText;
-    const canonical = JSON.stringify([
+    // canonicalJson, not JSON.stringify: the review is stored as jsonb, which reorders object keys,
+    // so a template's auth / endpoint object would hash differently at confirm (plugin.review_stale
+    // on every import of a plugin whose connector template has a non-trivial auth block).
+    const canonical = canonicalJson([
         r.name,
         r.version,
         r.contentDigest,
@@ -1146,9 +1799,34 @@ export function pluginReviewHash(r, files) {
         ...((r.agentTemplates ?? []).length > 0
             ? [(r.agentTemplates ?? []).map((a) => [a.path, canonicalJson(a)])]
             : []),
+        // themes, only when there are any, tagged (never read as agent templates)
+        ...((r.themes ?? []).length > 0
+            ? [{ themes: (r.themes ?? []).map((t) => [t.id, canonicalJson(t)]) }]
+            : []),
     ]);
     return createHash("sha256").update(canonical).digest("hex").slice(0, 32);
 }
+/** The client code of a read extension package for its review (sizes from the package's files). */
+function reviewClient(pkg) {
+    const c = pkg.section.client;
+    const sizes = new Map(pkg.files.map((f) => [f.path, f.size]));
+    const files = [
+        ...(c.entry !== undefined ? [c.entry] : []),
+        ...(c.styles ?? []),
+        ...(c.assets ?? []),
+    ].map((path) => {
+        // checkClientFiles ran first: every listed file is in the package
+        const size = sizes.get(path.slice(2));
+        if (size === undefined)
+            throw new Error(`client file ${path} is not in the package`);
+        return { path, size };
+    });
+    return {
+        files,
+        totalBytes: files.reduce((n, f) => n + f.size, 0),
+        apiVersion: c.apiVersion,
+    };
+}
 /**
  * A version change that is a downgrade (the imported version below the installed one) whose
  * version has migrations not run on this deployment -> `extension.downgrade_unsupported` (the same
@@ -1206,3 +1884,23 @@ function pinnedNames(m, review) {
     const byPath = new Map(review.skills.map((s) => [s.path, s.name]));
     return (m.skills ?? []).filter((s) => s.pinned === true).map((s) => byPath.get(s.path) ?? s.path);
 }
+/**
+ * The staging rows a route may see (P3-8): the platform's (`org_id` null) without an owner, else
+ * the owner org's.
+ */
+function ownStaging(owner) {
+    return (eb) => owner === undefined ? eb("org_id", "is", null) : eb("org_id", "=", owner.orgId);
+}
+/**
+ * An org upload's custom deny, by content (ruling P3-15'): skills or agent templates ->
+ * `customSkills`, connector templates -> `customConnectors`; each `deny` -> 403
+ * `catalog.custom_disabled`. A package carrying neither passes; themes are covered by neither
+ * switch (themes spec §6), so a themes-only upload passes.
+ */
+async function assertCustomContent(db, content) {
+    if (content.skills.length > 0 || content.agentTemplates.length > 0) {
+        await assertCustomAllowed(db, "customSkills");
+    }
+    if (content.templates.length > 0)
+        await assertCustomAllowed(db, "customConnectors");
+}