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

package/dist/catalog/plugin-import.js

@@ -8,14 +8,16 @@ 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 { 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 { 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 +26,40 @@ 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 { findConnectorIn } from "./catalog-content.js";
-import { assertPluginNameOwner, catalogObjectPrefix, itemView, permissionsMismatch, precheckCatalogImport, putCatalogFiles, templateProblems, writeCatalogVersion, } from "./catalog-items.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 { 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, } 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,7 +69,7 @@ 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
@@ -64,13 +78,13 @@ import { maxSatisfying, satisfiesRange } from "./versions.js";
  * 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
@@ -123,16 +137,20 @@ const fileOf = (path, data) => ({
 let PluginImport = class PluginImport {
     kdb;
     adminLock;
+    orgLock;
     installLock;
     approveLock;
     itemLock;
     config;
     installs;
     ops;
+    admin;
     blobs;
     registry;
     log;
     txHost;
+    platform;
+    maintenance;
     /** Where plugin files go (the kernel's object storage; the CLI's own, see {@link useCliStorage}). */
     files;
     /**
@@ -142,24 +160,34 @@ 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) {
         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.files = storage;
     }
     /** The kernel-schema handle of the current context (the transaction, else the pool). */
@@ -174,21 +202,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 +315,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 +332,34 @@ 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 }),
-        });
+        // 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);
@@ -318,7 +378,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 +408,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 }),
@@ -364,8 +425,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,10 +441,12 @@ 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 (content.files.length > 0 && retry === undefined) {
             objectPrefix = catalogObjectPrefix(itemId, version, stagingId);
             await putCatalogFiles(this.files, objectPrefix, content.files);
         }
@@ -405,15 +469,16 @@ let PluginImport = class PluginImport {
             ...(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);
         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) {
         const { extension } = review;
         const t = this.db;
-        await this.authorizeActor(actor);
+        await this.authorizeActor(actor, owner);
         await t
             .insertInto("plugin_import_staging")
             .values({
@@ -424,6 +489,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 +510,7 @@ let PluginImport = class PluginImport {
                 ...(extension && {
                     extension: { sha256: extension.sha256, action: extension.action },
                 }),
+                ...(owner !== undefined && { orgId: owner.orgId }),
             },
         });
     }
@@ -465,9 +533,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 +544,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 +556,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 +677,92 @@ 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);
         let now;
         let previous;
         if (reviewed) {
@@ -544,23 +772,84 @@ 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);
+        }
+        // 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();
+        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,
@@ -570,7 +859,7 @@ let PluginImport = class PluginImport {
             manifest: m,
             listing: {
                 publisher: m.publisher,
-                description: m.description,
+                description: pluginDescription(m.description).en,
                 displayName: m.displayName ?? null,
             },
             newItemId: staged.itemId,
@@ -591,12 +880,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
@@ -786,7 +1207,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 +1218,67 @@ 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;
+        // extension_blobs (a PG-stored package) goes with the row (ON DELETE CASCADE)
+        await t.deleteFrom("extension_packages").where("sha256", "=", sha).execute();
+        // 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") {
@@ -943,26 +1423,52 @@ let PluginImport = class PluginImport {
     }
     /**
      * 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 +1486,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 +1508,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),
@@ -1027,10 +1533,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 +1561,28 @@ __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)))
 ], PluginImport);
 export { PluginImport };
 /**
@@ -1097,13 +1611,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 };
@@ -1206,3 +1727,22 @@ 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.
+ */
+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");
+}