@capybara-hq/kernel 0.1.0-rc.23 → 0.1.0-rc.25

package/dist/catalog/platform-import-update.js

@@ -0,0 +1,116 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable } from "@nestjs/common";
+import { ApiError } from "../errors.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { PluginImport } from "./plugin-import.js";
+import { PlatformPluginUpdater, } from "./plugin-upgrade.js";
+const notInstalled = (name) => new ApiError("plugin.upgrade_target_invalid", `Plugin ${name} is not a platform plugin of this deployment yet; install it with the import review instead`, [{ reason: "not_installed" }]);
+/**
+ * The platform's update of an installed plugin to a version staged for import (the one wizard of
+ * the admin plugin pages, maintainer decision 2026-11-13): the import review (prepared as any
+ * import, `PluginImport.prepare`) and the platform update preview of the staged version
+ * ({@link preview}: `PlatformPluginUpdater.previewStaged`, the target read from the staging) are
+ * confirmed together ({@link confirm} with the review's `reviewHash` and the preview's `diffHash`).
+ * Nothing is written before that confirm: cancelling the wizard leaves only the staging row, which
+ * expires like any staged import.
+ *
+ * The confirm holds the item's update lock (`PlatformPluginUpdater.withItemLock`, one per item
+ * across replicas: another update -> 409 `plugin.install_in_progress`), recomputes the preview
+ * (another `diffHash` -> 409 `plugin.upgrade_stale`, nothing written), commits the import without
+ * deploying its extension (the permission snapshot is written as the review approved it), then
+ * runs the platform update, which moves the extension with its own rollback and writes the
+ * components in one transaction. When that update fails, the platform stays on its version, the
+ * extension where it was and its previous approval is put back; the imported version stays in the
+ * catalog (its 版本 tab, and 更新到 retries the update with the plain update preview): 409
+ * `plugin.imported_not_updated` says so, with the cause in the details. No in-process state.
+ */
+let PlatformImportUpdate = class PlatformImportUpdate {
+    pluginImport;
+    updater;
+    log;
+    constructor(pluginImport, updater, log) {
+        this.pluginImport = pluginImport;
+        this.updater = updater;
+        this.log = log;
+    }
+    /**
+     * The platform update the staged version would apply (writes nothing). The staging must be a
+     * platform staging (else 404 `plugin.staging_not_found`) of a new version of a live
+     * platform-owned plugin (else 409 `plugin.upgrade_target_invalid`, reason `not_installed`); the
+     * updater's refusals apply as for any update preview. `needsApproval` is false: the confirm
+     * approves the permissions the review shows.
+     */
+    async preview(stagingId) {
+        const st = await this.target(stagingId);
+        return this.previewOf(st);
+    }
+    /** Confirms the import and the update together (see the class comment). */
+    async confirm(actor, stagingId, input, opts = {}) {
+        const st = await this.target(stagingId);
+        return this.updater.withItemLock(st.itemId, async () => {
+            const preview = await this.previewOf(st);
+            if (preview.diffHash !== input.diffHash) {
+                throw new ApiError("plugin.upgrade_stale", `What updating plugin ${preview.name} to ${st.version} does changed since the preview; preview it again`);
+            }
+            // The review hash is checked by the import's confirm (409 plugin.review_stale, nothing
+            // written)
+            const imported = await this.pluginImport.confirm(actor, stagingId, { reviewHash: input.reviewHash, deploy: false }, opts);
+            try {
+                const update = await this.updater.updateHeld(actor, st.itemId, { version: st.version, diffHash: input.diffHash }, opts);
+                return { item: await this.pluginImport.view(st.itemId), update };
+            }
+            catch (e) {
+                let restored = imported.approval === undefined;
+                if (imported.approval !== undefined) {
+                    try {
+                        restored = await this.pluginImport.restoreApproval(actor, imported.approval, opts);
+                    }
+                    catch (err) {
+                        this.log.error("cannot restore an extension's approval after a failed update", {
+                            itemId: st.itemId,
+                            err,
+                        });
+                    }
+                }
+                const cause = e instanceof ApiError ? e : undefined;
+                throw new ApiError("plugin.imported_not_updated", `Version ${st.version} of plugin ${preview.name} was imported, but updating the platform to it failed (${cause?.code ?? "internal"}); the platform stays on ${preview.from ?? "(none)"}. Update to ${st.version} from the plugin's page to retry`, [
+                    {
+                        version: st.version,
+                        from: preview.from,
+                        code: cause?.code ?? "internal",
+                        ...(cause !== undefined && { message: cause.message }),
+                        ...(cause?.details !== undefined && { causeDetails: cause.details }),
+                        approvalRestored: restored,
+                    },
+                ]);
+            }
+        });
+    }
+    /** The staged target, which must be a new version of a live platform-owned plugin. */
+    async target(stagingId) {
+        const st = await this.pluginImport.stagedTarget(stagingId);
+        if (!st.existing) {
+            throw notInstalled((await this.pluginImport.staged(stagingId)).review.name);
+        }
+        return st;
+    }
+    async previewOf(st) {
+        const p = await this.updater.previewStaged(st.itemId, st.version, st.target);
+        return p.extension === null ? p : { ...p, extension: { ...p.extension, needsApproval: false } };
+    }
+};
+PlatformImportUpdate = __decorate([
+    Injectable(),
+    __param(0, Inject(PluginImport)),
+    __param(1, Inject(PlatformPluginUpdater)),
+    __param(2, Inject(KERNEL_LOGGER))
+], PlatformImportUpdate);
+export { PlatformImportUpdate };

package/dist/catalog/plugin-import.d.ts

@@ -1,5 +1,4 @@
 import { type AgentTemplate, type AgentTemplateTier, type LocalizedName, type PluginManifest, type ThemeScheme } from "@capybara-hq/plugin-sdk";
-import type { Queue } from "bullmq";
 import { ClientBuilds } from "../client/client-builds.service.js";
 import { ApiError } from "../errors.js";
 import { ExtensionAdminOps } from "../extensions/admin-ops.js";
@@ -8,6 +7,7 @@ import { ExtensionBlobs } from "../extensions/blobs.js";
 import { ExtensionInstalls } from "../extensions/installs.js";
 import { PluginApproveLock, PluginInstallLock } from "../extensions/locks.js";
 import { ExtensionPackageError } from "../extensions/package.js";
+import { type PermissionSet } from "../extensions/permission-set.js";
 import { type PackageWarning, type PermissionGroup, type PermissionItem } from "../extensions/permission-view.js";
 import { ExtensionRegistry } from "../extensions/registry.js";
 import type { SingleProviderBlock } from "../extensions/single-provider.js";
@@ -15,6 +15,7 @@ import { SuperAdminLock } from "../identity/super-admin.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
+import { OutboxService } from "../infra/outbox/outbox.service.js";
 import type { KernelLogger } from "../log.js";
 import { OrgLock } from "../orgs/org-lock.js";
 import type { ProvenanceResult } from "../packages/provenance.js";
@@ -26,8 +27,6 @@ import { CatalogItemLock } from "./locks.js";
 import { PlatformComponents } from "./platform-components.js";
 import { PluginPackageError } from "./plugin-package.js";
 import type { PluginScope } from "./scope.js";
-/** How long after a failed post-import platform sync the migration job runs for the item. */
-export declare const PLATFORM_SYNC_RETRY_MS = 60000;
 /**
  * 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.
@@ -53,8 +52,10 @@ export declare const PLATFORM_SYNC_RETRY_MS = 60000;
  * 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`;
+ * `extension_sha256`, the files under the staging prefix); an item's first usable version also
+ * gets its platform component rows there (their files copied before, keyed by content: a failure
+ * leaves nothing a retry copies again; no job heals an item later). 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.
  *
@@ -317,6 +318,18 @@ export interface PluginConfirmResult {
      * extension (applied at once, plan Task 6).
      */
     firstVersion: boolean;
+    /**
+     * A confirm with `deploy: false` that approved the extension's permissions (its snapshot
+     * written): what {@link PluginImport.restoreApproval} needs to put the previous approval back
+     * when the step that was to deploy it fails. Never sent over HTTP (the route always deploys).
+     */
+    approval?: HeldApproval;
+}
+/** The approval a confirm without its deploy wrote (see {@link PluginConfirmResult.approval}). */
+export interface HeldApproval {
+    review: PluginReview;
+    extension: PluginReviewExtension;
+    previous: PreviousSnapshot | null;
 }
 /** What prepare checks besides the package itself (npm and marketplace imports). */
 export interface PluginPrepareExpect {
@@ -338,6 +351,14 @@ export interface ReviewProvenance {
     provenance: ProvenanceResult;
     warning?: "repository_mismatch";
 }
+/** The snapshot overwritten at confirm (restored when deploying an upgrade fails). */
+export interface PreviousSnapshot {
+    version: string;
+    permissions: PermissionSet;
+    approvedBy: string | null;
+    approvedAt: Date;
+    source: "auto" | "web" | "cli" | "bootstrap";
+}
 /** What an org's staged upload targets (see {@link PluginImport.stagedTarget}). */
 export interface StagedTarget {
     itemId: string;
@@ -392,12 +413,14 @@ export declare class PluginImport {
     private readonly registry;
     private readonly log;
     readonly txHost: TransactionHost;
-    /** The platform rows of a new item's components, written after the confirm's commit. */
+    /** The platform rows of a new item's components, written in the confirm's transaction. */
     private readonly platform;
-    /** A failed platform sync enqueues a run of the migration job here (it heals the item). */
-    private readonly maintenance;
     /** The client build of a dropped org upload's package is deleted with it. */
     private readonly clientBuilds;
+    /** The scope sync's backstop, owed by the confirm's commit (ruling R24). */
+    private readonly outbox;
+    /** The backstop's delay (a test seam; default `SCOPE_BACKSTOP_DELAY_MS`). */
+    private readonly backstopDelayMs;
     /** Where plugin files go (the kernel's object storage; the CLI's own, see {@link useCliStorage}). */
     private files;
     /**
@@ -415,12 +438,14 @@ export declare class PluginImport {
     blobs: ExtensionBlobs, 
     /** Config-declared names, loaded connectors and extension versions (the extension registry). */
     registry: ExtensionRegistry, log: KernelLogger, txHost: TransactionHost, 
-    /** The platform rows of a new item's components, written after the confirm's commit. */
+    /** The platform rows of a new item's components, written in the confirm's transaction. */
     platform: PlatformComponents, 
-    /** A failed platform sync enqueues a run of the migration job here (it heals the item). */
-    maintenance: Pick<Queue, "add">, 
     /** The client build of a dropped org upload's package is deleted with it. */
-    clientBuilds: ClientBuilds);
+    clientBuilds: ClientBuilds, 
+    /** The scope sync's backstop, owed by the confirm's commit (ruling R24). */
+    outbox: Pick<OutboxService, "add">, 
+    /** The backstop's delay (a test seam; default `SCOPE_BACKSTOP_DELAY_MS`). */
+    backstopDelayMs?: number);
     /** The kernel-schema handle of the current context (the transaction, else the pool). */
     private get db();
     /**
@@ -521,8 +546,10 @@ export declare class PluginImport {
      * 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`.
+     * Without `owner`: a platform staging, and `existing` means a live platform-owned item (the
+     * platform's import and update, `PlatformImportUpdate`).
      */
-    stagedTarget(stagingId: string, owner: ImportOwner): Promise<StagedTarget>;
+    stagedTarget(stagingId: string, owner?: ImportOwner): Promise<StagedTarget>;
     /** The catalog item's view (as a confirm returns it). */
     view(itemId: string): Promise<CatalogItemView>;
     /**
@@ -553,15 +580,23 @@ export declare class PluginImport {
         orgs?: string[];
         /** An org upload's new item: shared with other orgs by its owner (default false, P3-16). */
         shareable?: boolean;
+        /**
+         * Deploy the extension after the commit (default true). false (the platform's import and
+         * update, `PlatformImportUpdate`) leaves the deployment to the platform update that follows,
+         * which moves the extension with its own rollback; the approval written is returned in
+         * `approval`.
+         */
+        deploy?: boolean;
     }, opts?: ActorOpts & {
         owner?: ImportOwner;
     }): Promise<PluginConfirmResult>;
     /**
-     * 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}).
+     * The platform components of the staged version when its confirm will most likely make it the
+     * item's first usable version ({@link commit} decides under its locks): no live item of the name
+     * yet, or an org upload replacing its own first upload still awaiting confirmation. Planned from
+     * the staged content and their files copied, outside any transaction; otherwise undefined.
      */
-    writePlatformComponents(itemId: string, version: string): Promise<void>;
+    private prepareFirstVersion;
     /**
      * 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
@@ -575,17 +610,15 @@ export declare class PluginImport {
      * 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).
+     *
+     * The item's first usable version (a new item not waiting, or an awaiting first upload replaced)
+     * writes the platform rows of its skills, agent templates, connector templates and themes
+     * (plugin scope phase 2) from `prepared` (their files copied before the transaction, keyed by
+     * content): a failure rolls the whole confirm back, and a retry copies nothing again. A plan made
+     * for another item or version, or a component changed since it -> `plugin.review_stale`. A new
+     * version of an existing item leaves them to the platform update.
      */
     private commit;
-    /**
-     * 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.
-     */
-    private syncPlatform;
     /**
      * Writes the extension's permission snapshot for the version being imported (source web; cli
      * without an actor; bootstrap for the bootstrap step), after
@@ -603,6 +636,11 @@ export declare class PluginImport {
      * admin (the package is already in the package store) with the sha256 from the result.
      */
     private deploy;
+    /**
+     * Puts back the approval a confirm with `deploy: false` wrote, after the step that was to deploy
+     * the extension failed (see {@link restoreSnapshot}; false when someone changed it meanwhile).
+     */
+    restoreApproval(actor: string | null, held: HeldApproval, opts?: ActorOpts): Promise<boolean>;
     /**
      * Restores the snapshot overwritten at confirm (deletes it when there was none before), audits
      * `extension.permissions_restored`. Compare-and-write (row locked): restores only while the

package/dist/catalog/plugin-import.js

@@ -9,8 +9,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 import { createHash, randomUUID } from "node:crypto";
 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 { Inject, Injectable, Optional } from "@nestjs/common";
 import { sql } from "kysely";
 import semver from "semver";
 import { ClientBuilds } from "../client/client-builds.service.js";
@@ -35,10 +34,10 @@ 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 { OutboxService } from "../infra/outbox/outbox.service.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";
@@ -52,15 +51,13 @@ 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 { PlanStale, PlatformComponents } from "./platform-components.js";
 import { PluginPackageError, readPluginFiles, readPluginPackage, themeApiError, } from "./plugin-package.js";
 import { hasImportRequests, importRequestOf, resolveImportRequests } from "./request-rules.js";
 import { assertNameNotReserved } from "./reserved-names.js";
+import { oweScopeItem, SCOPE_BACKSTOP_DELAY, SCOPE_BACKSTOP_DELAY_MS } from "./scope-jobs.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;
 /**
  * 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.
@@ -86,8 +83,10 @@ export const PLATFORM_SYNC_RETRY_MS = 60_000;
  * 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`;
+ * `extension_sha256`, the files under the staging prefix); an item's first usable version also
+ * gets its platform component rows there (their files copied before, keyed by content: a failure
+ * leaves nothing a retry copies again; no job heals an item later). 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.
  *
@@ -164,8 +163,9 @@ let PluginImport = class PluginImport {
     log;
     txHost;
     platform;
-    maintenance;
     clientBuilds;
+    outbox;
+    backstopDelayMs;
     /** Where plugin files go (the kernel's object storage; the CLI's own, see {@link useCliStorage}). */
     files;
     /**
@@ -183,12 +183,14 @@ let PluginImport = class PluginImport {
     blobs, 
     /** Config-declared names, loaded connectors and extension versions (the extension registry). */
     registry, log, txHost, 
-    /** The platform rows of a new item's components, written after the confirm's commit. */
+    /** The platform rows of a new item's components, written in the confirm's transaction. */
     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) {
+    clientBuilds, 
+    /** The scope sync's backstop, owed by the confirm's commit (ruling R24). */
+    outbox, 
+    /** The backstop's delay (a test seam; default `SCOPE_BACKSTOP_DELAY_MS`). */
+    backstopDelayMs = SCOPE_BACKSTOP_DELAY_MS) {
         this.kdb = kdb;
         this.adminLock = adminLock;
         this.orgLock = orgLock;
@@ -204,8 +206,9 @@ let PluginImport = class PluginImport {
         this.log = log;
         this.txHost = txHost;
         this.platform = platform;
-        this.maintenance = maintenance;
         this.clientBuilds = clientBuilds;
+        this.outbox = outbox;
+        this.backstopDelayMs = backstopDelayMs;
         this.files = storage;
     }
     /** The kernel-schema handle of the current context (the transaction, else the pool). */
@@ -610,6 +613,8 @@ let PluginImport = class PluginImport {
      * 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`.
+     * Without `owner`: a platform staging, and `existing` means a live platform-owned item (the
+     * platform's import and update, `PlatformImportUpdate`).
      */
     async stagedTarget(stagingId, owner) {
         if (!UUID_RE.test(stagingId))
@@ -630,7 +635,7 @@ let PluginImport = class PluginImport {
             .select(["id", "awaiting_confirmation"])
             .where("id", "=", staged.itemId)
             .where("deleted_at", "is", null)
-            .where("owner_org_id", "=", owner.orgId)
+            .where((eb) => owner === undefined ? eb("owner_org_id", "is", null) : eb("owner_org_id", "=", owner.orgId))
             .executeTakeFirst();
         const imported = staged.retry === true
             ? await this.db
@@ -732,11 +737,16 @@ let PluginImport = class PluginImport {
         const stored = reviewed && reviewed.action !== "keep" && owner === undefined
             ? await this.readStored(reviewed.sha256)
             : undefined;
+        // The platform components of the item's first usable version: planned and their files copied
+        // (keyed by content) before the transaction, their rows written in it
+        const prepared = staged.retry === true || (owner !== undefined && reviewed !== undefined)
+            ? undefined
+            : await this.prepareFirstVersion(staged, row.object_prefix, owner);
         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);
+        }, stored, opts, prepared);
         const { now } = committed;
         if (committed.pending) {
             // Waits for the super admin (P3-10): no platform components, nothing deployed
@@ -748,11 +758,19 @@ let PluginImport = class PluginImport {
                 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);
+        if (input.deploy === false) {
+            return {
+                item: await this.itemView(committed.itemId),
+                created: committed.created,
+                deploy: null,
+                pending: false,
+                firstVersion: committed.firstVersion,
+                ...(now &&
+                    committed.previous !== undefined && {
+                    approval: { review, extension: now, previous: committed.previous },
+                }),
+            };
+        }
         const deploy = now && now.action !== "keep"
             ? await this.deploy(actor, review, committed.itemId, now, committed.previous, opts, input.enable ?? true)
             : null;
@@ -765,12 +783,31 @@ let PluginImport = class PluginImport {
         };
     }
     /**
-     * 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}).
+     * The platform components of the staged version when its confirm will most likely make it the
+     * item's first usable version ({@link commit} decides under its locks): no live item of the name
+     * yet, or an org upload replacing its own first upload still awaiting confirmation. Planned from
+     * the staged content and their files copied, outside any transaction; otherwise undefined.
      */
-    async writePlatformComponents(itemId, version) {
-        await this.syncPlatform(itemId, version);
+    async prepareFirstVersion(staged, objectPrefix, owner) {
+        const live = await this.db
+            .selectFrom("catalog_items")
+            .select(["id", "awaiting_confirmation", "owner_org_id"])
+            .where("name", "=", staged.manifest.name)
+            .where("deleted_at", "is", null)
+            .executeTakeFirst();
+        const first = live === undefined ||
+            (owner !== undefined && live.awaiting_confirmation && live.owner_org_id === owner.orgId);
+        if (!first)
+            return undefined;
+        return this.platform.prepareImport({
+            itemId: live?.id ?? staged.itemId,
+            plugin: staged.manifest.name,
+            version: staged.version,
+            manifest: staged.manifest,
+            objectPrefix,
+            files: staged.files,
+            sourceFormat: staged.sourceFormat ?? "capybara",
+        });
     }
     /**
      * The confirm's transaction: the staging row consumed, the extension's action recomputed under
@@ -785,8 +822,15 @@ let PluginImport = class PluginImport {
      * 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).
+     *
+     * The item's first usable version (a new item not waiting, or an awaiting first upload replaced)
+     * writes the platform rows of its skills, agent templates, connector templates and themes
+     * (plugin scope phase 2) from `prepared` (their files copied before the transaction, keyed by
+     * content): a failure rolls the whole confirm back, and a retry copies nothing again. A plan made
+     * for another item or version, or a component changed since it -> `plugin.review_stale`. A new
+     * version of an existing item leaves them to the platform update.
      */
-    async commit(actor, c, scope, stored, opts) {
+    async commit(actor, c, scope, stored, opts, prepared) {
         const { stagingId, review, staged, src, manifest } = c;
         const reviewed = review.extension;
         const stale = () => reviewStale(review);
@@ -1019,61 +1063,44 @@ let PluginImport = class PluginImport {
             await markVersionApplied(t, itemId, staged.version);
             await releaseExtensionClaim(t, m.name, existing.package_name);
         }
+        const firstVersion = (created && !pending) || replacedAwaiting;
+        if (firstVersion) {
+            if (prepared?.plan.itemId !== itemId || prepared.plan.version !== staged.version) {
+                throw stale();
+            }
+            try {
+                await this.platform.applySyncIn(prepared);
+            }
+            catch (e) {
+                if (e instanceof PlanStale)
+                    throw stale();
+                throw e;
+            }
+        }
+        // The commit owes the scope sync's backstop (ruling R24) when the item's scope turns it on by
+        // itself: the caller owes the immediate sync after the deploy, which a crash may lose
+        if (!pending) {
+            const item = await t
+                .selectFrom("catalog_items")
+                .select("scope")
+                .where("id", "=", itemId)
+                .executeTakeFirstOrThrow();
+            if (item.scope !== "optional") {
+                await oweScopeItem(this.outbox, t, itemId, {
+                    backstop: true,
+                    backstopDelayMs: this.backstopDelayMs,
+                });
+            }
+        }
         return {
             itemId,
             created,
-            firstVersion: (created && !pending) || replacedAwaiting,
+            firstVersion,
             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
      * without an actor; bootstrap for the bootstrap step), after
@@ -1184,6 +1211,13 @@ let PluginImport = class PluginImport {
             return { ...base, result: "failed", ...failure(e) };
         }
     }
+    /**
+     * Puts back the approval a confirm with `deploy: false` wrote, after the step that was to deploy
+     * the extension failed (see {@link restoreSnapshot}; false when someone changed it meanwhile).
+     */
+    async restoreApproval(actor, held, opts = {}) {
+        return this.restoreSnapshot(actor, held.review, held.extension, held.previous, opts);
+    }
     /**
      * Restores the snapshot overwritten at confirm (deletes it when there was none before), audits
      * `extension.permissions_restored`. Compare-and-write (row locked): restores only while the
@@ -1705,8 +1739,10 @@ PluginImport = __decorate([
     __param(13, Inject(KERNEL_LOGGER)),
     __param(14, Inject(TransactionHost)),
     __param(15, Inject(PlatformComponents)),
-    __param(16, Inject(getQueueToken(MAINTENANCE_QUEUE_NAME))),
-    __param(17, Inject(ClientBuilds))
+    __param(16, Inject(ClientBuilds)),
+    __param(17, Inject(OutboxService)),
+    __param(18, Optional()),
+    __param(18, Inject(SCOPE_BACKSTOP_DELAY))
 ], PluginImport);
 export { PluginImport };
 /**