@capybara-hq/kernel 0.1.0-rc.24 → 0.1.0-rc.26

package/dist/catalog/platform-components.d.ts

@@ -1,4 +1,4 @@
-import { type AgentTemplate, type ConnectorTemplateFile, type ParsedTheme } from "@capybara-hq/plugin-sdk";
+import { type AgentTemplate, type ConnectorTemplateFile, type ParsedTheme, type PluginManifest } from "@capybara-hq/plugin-sdk";
 import type { SkillManifest, SourceFormat } from "../db/kernel-schema.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
@@ -26,7 +26,7 @@ export interface ChangedConnectorTemplateRef {
     from: string | null;
     to: string;
 }
-/** What {@link PlatformComponents.syncFromVersion} changed (unchanged components are not listed). */
+/** What {@link PlatformComponents.applySyncIn} changed (unchanged components are not listed). */
 export interface PlatformSyncResult {
     skills: ChangedRef[];
     agentTemplates: ChangedRef[];
@@ -37,11 +37,6 @@ export interface PlatformSyncResult {
 export declare const platformSkillPrefix: (id: string, version: number) => string;
 /** The prefix (in `deployment/`) of a platform agent template version's file. */
 export declare const platformAgentTemplatePrefix: (id: string, version: number) => string;
-/**
- * The prefix (in `deployment/`) of a platform theme's files (themes spec §6); a version's fonts
- * and logo are under `<prefix><version>-<catalog version>/` ({@link syncVersionPrefix}).
- */
-export declare const platformThemePrefix: (id: string) => string;
 /**
  * A fresh prefix (in `deployment/`) for a version written before its transaction (ruling P3-45):
  * `<id>/<version>-<uuid>/`, so two writers racing for one version number never overwrite each
@@ -49,12 +44,20 @@ export declare const platformThemePrefix: (id: string) => string;
  */
 export declare const uniqueVersionPrefix: (base: string) => string;
 /**
- * The prefix of a version a plugin sync writes: `<id>/<version>-<catalog version>/` (the catalog
- * version made key-safe), so syncs of two catalog versions racing for one number never overwrite
- * each other. Stored on the version row; readers use the stored prefix, so rows written before keep
+ * The prefix (in `deployment/`) of the files a plugin sync writes for a component version:
+ * `platform/<kind>/sha256-<digest>/`, the digest of the files' paths and contents
+ * ({@link skillFilesDigest}). The files are copied before the transaction that writes the rows (no
+ * storage call holds a row lock), so the same content always lands on the same keys: a sync or an
+ * import that is retried after its transaction rolled back writes nothing new, and versions with
+ * the same content share their objects. Objects are immutable and nothing deletes them (versions
+ * are kept), so an import that rolled back leaves at most objects a later import of that content
+ * reuses. Stored on the version row; readers use the stored prefix, so rows written before keep
  * theirs.
  */
-export declare const syncVersionPrefix: (base: string, catalogVersion: string) => string;
+export declare const contentPrefix: (kind: "skills" | "agent-templates" | "themes", files: {
+    path: string;
+    sha256: string;
+}[]) => string;
 /** The live component a plan was made against (absent: the plan creates it). */
 interface Base<V> {
     id: string;
@@ -112,12 +115,32 @@ export interface SyncPlan {
 export declare class PlanStale extends Error {
 }
 /**
- * A sync planned and its files copied ({@link PlatformComponents.prepareSync}), waiting for its rows
- * ({@link PlatformComponents.applySyncIn}). Opaque outside this module.
+ * A sync planned and its files copied ({@link PlatformComponents.prepareSync},
+ * {@link PlatformComponents.prepareImport}), waiting for its rows
+ * ({@link PlatformComponents.applySyncIn}). Opaque outside this module but for the item and the
+ * catalog version it was planned for.
  */
 export interface PreparedSync {
     readonly plan: SyncPlan;
 }
+/**
+ * The catalog version a sync plans from: its row, or a staged import whose row its transaction
+ * is about to write (the files are in object storage under `objectPrefix` already).
+ */
+export interface SyncSource {
+    itemId: string;
+    /** The plugin (the catalog item's name). */
+    plugin: string;
+    version: string;
+    manifest: PluginManifest;
+    objectPrefix: string | null;
+    files: {
+        path: string;
+        size: number;
+        sha256: string;
+    }[];
+    sourceFormat: SourceFormat;
+}
 /** A component version written by an upload ({@link PlatformComponents.uploadSkillVersion}). */
 export interface UploadedComponentVersion {
     kind: "skill" | "agent_template";
@@ -145,8 +168,9 @@ export interface UploadActor {
     auditDetail?: Record<string, unknown>;
 }
 /**
- * Writes the platform rows of a catalog version's components. Called by the import confirm that
- * creates a catalog item (`initial`), and by the platform plugin update for a new version.
+ * Writes the platform rows of a catalog version's components, in the transaction of the import
+ * confirm that makes an item's first usable version, of the super admin's confirmation of an org
+ * upload's first version, and of the platform plugin update to a new version.
  */
 export declare class PlatformComponents {
     private readonly kdb;
@@ -160,26 +184,19 @@ export declare class PlatformComponents {
     /** CLI only (see `PluginImport.useCliStorage`): files go to the object store the CLI set up. */
     useCliStorage(storage: PrefixedStorage): void;
     /**
-     * Creates or updates the platform rows of every component of catalog version `version` of item
-     * `itemId`: a component is matched by plugin and name (connector templates by item and template
-     * id) and gets a new version only when its content changed (skills by their files' digest,
-     * templates by canonical JSON); new rows follow the plugin's scope (`scope_mode: follow`).
-     * Files are copied from the catalog prefix to `deployment/platform/…` before the rows are
-     * written (outside the transaction), so a sync that stops midway leaves at most unreferenced
-     * files, and running it again is a no-op once it succeeded. `initial` is the confirm that
-     * created the item. Components missing from the version are left alone (the platform update
-     * decides what a removal means). On success the item records `version` as
-     * `platform_synced_version`.
+     * The first phase of a sync inside a caller's transaction (the platform plugin update, the super
+     * admin's confirmation of an org upload's first version: `confirming`, the item still awaiting
+     * it): plans the version's components and copies their files, outside any transaction (no
+     * storage call holds a row lock). {@link applySyncIn} writes the rows.
      */
-    syncFromVersion(itemId: string, version: string, opts: {
-        initial: boolean;
-    }): Promise<PlatformSyncResult>;
+    prepareSync(itemId: string, version: string, opts?: {
+        confirming?: boolean;
+    }): Promise<PreparedSync>;
     /**
-     * The first phase of a sync inside a caller's transaction (the platform plugin update): plans the
-     * version's components and copies their files, outside any transaction (no storage call holds a
-     * row lock). {@link applySyncIn} writes the rows.
+     * {@link prepareSync} for an import whose transaction writes the catalog version (the item may
+     * not exist yet): plans from the staged content and copies the files, before that transaction.
      */
-    prepareSync(itemId: string, version: string): Promise<PreparedSync>;
+    prepareImport(source: SyncSource): Promise<PreparedSync>;
     /**
      * The second phase: writes the prepared rows in the caller's transaction and records
      * `platform_synced_version`. A component changed since the plan -> {@link PlanStale} (the caller
@@ -226,11 +243,16 @@ export declare class PlatformComponents {
     private writeTemplateVersionIn;
     /**
      * Records that the item's platform components are written from `version`
-     * (`catalog_items.platform_synced_version`): the migration job syncs only items without it.
+     * (`catalog_items.platform_synced_version`, the version orgs install).
      */
     private markSynced;
+    /**
+     * The stored catalog version `version` of live item `itemId`. An org upload still waiting for the
+     * super admin has no platform components (P3-9) unless this is its `confirming`.
+     */
+    private source;
     /** Reads the version's components and the live platform rows; keeps only what changed. */
-    private plan;
+    private planFrom;
     /** Copies the planned versions' files to their platform prefixes. */
     private writeFiles;
     /**

package/dist/catalog/platform-components.js

@@ -9,8 +9,10 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 // Platform components (plugin scope phase 2, rulings A2 and C2): the skills, agent templates,
 // connector templates and themes of a catalog item, stored once for the deployment. Files live
-// under `deployment/platform/{skills,agent-templates,themes}/<id>/<version>…/`, never under an org
-// prefix (orgs are purged by prefix).
+// under `deployment/platform/{skills,agent-templates,themes}/…/`, never under an org prefix (orgs
+// are purged by prefix): a plugin sync's under the digest of their content
+// (`sha256-<digest>/`, {@link contentPrefix}), an upload's or a promotion's under
+// `<id>/<version>-<uuid>/`.
 import { createHash, randomUUID } from "node:crypto";
 import { parseAgentTemplate, } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable } from "@nestjs/common";
@@ -32,11 +34,6 @@ import { assertNotAwaiting } from "./ownership.js";
 export const platformSkillPrefix = (id, version) => `platform/skills/${id}/${version}/`;
 /** The prefix (in `deployment/`) of a platform agent template version's file. */
 export const platformAgentTemplatePrefix = (id, version) => `platform/agent-templates/${id}/${version}/`;
-/**
- * The prefix (in `deployment/`) of a platform theme's files (themes spec §6); a version's fonts
- * and logo are under `<prefix><version>-<catalog version>/` ({@link syncVersionPrefix}).
- */
-export const platformThemePrefix = (id) => `platform/themes/${id}/`;
 /**
  * A fresh prefix (in `deployment/`) for a version written before its transaction (ruling P3-45):
  * `<id>/<version>-<uuid>/`, so two writers racing for one version number never overwrite each
@@ -44,22 +41,26 @@ export const platformThemePrefix = (id) => `platform/themes/${id}/`;
  */
 export const uniqueVersionPrefix = (base) => `${base.slice(0, -1)}-${randomUUID()}/`;
 /**
- * The prefix of a version a plugin sync writes: `<id>/<version>-<catalog version>/` (the catalog
- * version made key-safe), so syncs of two catalog versions racing for one number never overwrite
- * each other. Stored on the version row; readers use the stored prefix, so rows written before keep
+ * The prefix (in `deployment/`) of the files a plugin sync writes for a component version:
+ * `platform/<kind>/sha256-<digest>/`, the digest of the files' paths and contents
+ * ({@link skillFilesDigest}). The files are copied before the transaction that writes the rows (no
+ * storage call holds a row lock), so the same content always lands on the same keys: a sync or an
+ * import that is retried after its transaction rolled back writes nothing new, and versions with
+ * the same content share their objects. Objects are immutable and nothing deletes them (versions
+ * are kept), so an import that rolled back leaves at most objects a later import of that content
+ * reuses. Stored on the version row; readers use the stored prefix, so rows written before keep
  * theirs.
  */
-export const syncVersionPrefix = (base, catalogVersion) => `${base.slice(0, -1)}-${catalogVersion.replace(/[^0-9A-Za-z.-]/g, "_")}/`;
+export const contentPrefix = (kind, files) => `platform/${kind}/sha256-${skillFilesDigest(files)}/`;
 /** 409 `catalog.not_owned`: an org's own promoted item is versioned by its owner only (P3-48). */
 const ownedByOrg = (what, name) => new ApiError("catalog.not_owned", `The ${what} ${name} belongs to an organization that shared it: only that organization uploads its versions`);
 /** A component changed between the plan and its write (a concurrent sync): plan again. */
 export class PlanStale extends Error {
 }
-/** Plans are retried this many times against concurrent syncs of the same item. */
-const SYNC_ATTEMPTS = 3;
 /**
- * Writes the platform rows of a catalog version's components. Called by the import confirm that
- * creates a catalog item (`initial`), and by the platform plugin update for a new version.
+ * Writes the platform rows of a catalog version's components, in the transaction of the import
+ * confirm that makes an item's first usable version, of the super admin's confirmation of an org
+ * upload's first version, and of the platform plugin update to a new version.
  */
 let PlatformComponents = class PlatformComponents {
     kdb;
@@ -82,56 +83,30 @@ let PlatformComponents = class PlatformComponents {
     useCliStorage(storage) {
         this.files = storage;
     }
+    // A plugin sync matches a component by plugin and name (connector templates by item and template
+    // id) and gives it a new version only when its content changed (skills by their files' digest,
+    // templates by canonical JSON); new rows follow the plugin's scope (`scope_mode: follow`).
+    // Components missing from the version are left alone (the platform update decides what a removal
+    // means). It runs in two phases: {@link prepareImport} / {@link prepareSync} plan and copy the
+    // files (keyed by content, {@link contentPrefix}) before the caller's transaction, and
+    // {@link applySyncIn} writes the rows and `platform_synced_version` in it.
     /**
-     * Creates or updates the platform rows of every component of catalog version `version` of item
-     * `itemId`: a component is matched by plugin and name (connector templates by item and template
-     * id) and gets a new version only when its content changed (skills by their files' digest,
-     * templates by canonical JSON); new rows follow the plugin's scope (`scope_mode: follow`).
-     * Files are copied from the catalog prefix to `deployment/platform/…` before the rows are
-     * written (outside the transaction), so a sync that stops midway leaves at most unreferenced
-     * files, and running it again is a no-op once it succeeded. `initial` is the confirm that
-     * created the item. Components missing from the version are left alone (the platform update
-     * decides what a removal means). On success the item records `version` as
-     * `platform_synced_version`.
+     * The first phase of a sync inside a caller's transaction (the platform plugin update, the super
+     * admin's confirmation of an org upload's first version: `confirming`, the item still awaiting
+     * it): plans the version's components and copies their files, outside any transaction (no
+     * storage call holds a row lock). {@link applySyncIn} writes the rows.
      */
-    async syncFromVersion(itemId, version, opts) {
-        for (let attempt = 1;; attempt++) {
-            const plan = await this.plan(itemId, version);
-            if (plan.skills.length === 0 &&
-                plan.agentTemplates.length === 0 &&
-                plan.connectorTemplates.length === 0 &&
-                plan.themes.length === 0) {
-                await this.markSynced(itemId, version);
-                return { skills: [], agentTemplates: [], connectorTemplates: [], themes: [] };
-            }
-            await this.writeFiles(plan);
-            try {
-                const r = await this.apply(plan);
-                await this.markSynced(itemId, version);
-                this.log.info("platform components synced", {
-                    itemId,
-                    version,
-                    initial: opts.initial,
-                    skills: r.skills.length,
-                    agentTemplates: r.agentTemplates.length,
-                    connectorTemplates: r.connectorTemplates.length,
-                    themes: r.themes.length,
-                });
-                return r;
-            }
-            catch (e) {
-                if (!(e instanceof PlanStale) || attempt >= SYNC_ATTEMPTS)
-                    throw e;
-            }
-        }
+    async prepareSync(itemId, version, opts = {}) {
+        const plan = await this.planFrom(await this.source(itemId, version, opts.confirming === true));
+        await this.writeFiles(plan);
+        return { plan };
     }
     /**
-     * The first phase of a sync inside a caller's transaction (the platform plugin update): plans the
-     * version's components and copies their files, outside any transaction (no storage call holds a
-     * row lock). {@link applySyncIn} writes the rows.
+     * {@link prepareSync} for an import whose transaction writes the catalog version (the item may
+     * not exist yet): plans from the staged content and copies the files, before that transaction.
      */
-    async prepareSync(itemId, version) {
-        const plan = await this.plan(itemId, version);
+    async prepareImport(source) {
+        const plan = await this.planFrom(source);
         await this.writeFiles(plan);
         return { plan };
     }
@@ -411,7 +386,7 @@ let PlatformComponents = class PlatformComponents {
     }
     /**
      * Records that the item's platform components are written from `version`
-     * (`catalog_items.platform_synced_version`): the migration job syncs only items without it.
+     * (`catalog_items.platform_synced_version`, the version orgs install).
      */
     async markSynced(itemId, version) {
         await this.db
@@ -420,16 +395,18 @@ let PlatformComponents = class PlatformComponents {
             .where("id", "=", itemId)
             .execute();
     }
-    /** Reads the version's components and the live platform rows; keeps only what changed. */
-    async plan(itemId, version) {
+    /**
+     * The stored catalog version `version` of live item `itemId`. An org upload still waiting for the
+     * super admin has no platform components (P3-9) unless this is its `confirming`.
+     */
+    async source(itemId, version, confirming) {
         const item = await this.db
             .selectFrom("catalog_items")
             .select(["name", "awaiting_confirmation"])
             .where("id", "=", itemId)
             .where("deleted_at", "is", null)
             .executeTakeFirst();
-        // An org upload still waiting for the super admin has no platform components (P3-9)
-        if (item !== undefined)
+        if (item !== undefined && !confirming)
             assertNotAwaiting(item);
         const row = item
             ? await this.db
@@ -442,21 +419,36 @@ let PlatformComponents = class PlatformComponents {
         if (!item || !row) {
             throw new ApiError("catalog.item_not_found", `Catalog item ${itemId}@${version} not found`);
         }
-        const plugin = item.name;
-        const manifest = row.manifest;
-        const v = row;
+        return {
+            itemId,
+            plugin: item.name,
+            version,
+            manifest: row.manifest,
+            objectPrefix: row.object_prefix,
+            files: row.files,
+            sourceFormat: row.source_format,
+        };
+    }
+    /** Reads the version's components and the live platform rows; keeps only what changed. */
+    async planFrom(src) {
+        const { itemId, plugin, version, manifest } = src;
+        const v = {
+            manifest,
+            object_prefix: src.objectPrefix,
+            files: src.files,
+        };
         const plan = {
             itemId,
             plugin,
             version,
-            sourceFormat: row.source_format,
+            sourceFormat: src.sourceFormat,
             skills: [],
             agentTemplates: [],
             connectorTemplates: [],
             themes: [],
         };
         for (const s of manifest.skills ?? []) {
-            const files = await readCatalogFiles(this.files, row.object_prefix, row.files, packagePath(s.path));
+            const files = await readCatalogFiles(this.files, v.object_prefix, v.files, packagePath(s.path));
             const pkg = { ...skillOf(files), files };
             const live = await this.db
                 .selectFrom("platform_skills as p")
@@ -475,8 +467,7 @@ let PlatformComponents = class PlatformComponents {
                 base: live && { id: live.id, version: live.current_version },
                 id,
                 to,
-                // the catalog version in the prefix: two syncs of different versions never write one key
-                prefix: syncVersionPrefix(platformSkillPrefix(id, to), version),
+                prefix: contentPrefix("skills", files),
                 files,
                 manifest: skillManifest(pkg),
             });
@@ -495,18 +486,19 @@ let PlatformComponents = class PlatformComponents {
                 .executeTakeFirst();
             if (live && canonicalJson(live.definition) === canonicalJson(a.template))
                 continue;
-            const [file] = await readCatalogFiles(this.files, row.object_prefix, row.files.filter((f) => f.path === a.path));
+            const [file] = await readCatalogFiles(this.files, v.object_prefix, v.files.filter((f) => f.path === a.path));
             if (!file)
                 throw new ApiError("internal", `Stored agent template ${a.path} is missing`);
             const id = live?.id ?? randomUUID();
             const to = (live?.current_version ?? 0) + 1;
+            const name = file.path.split("/").pop();
             plan.agentTemplates.push({
                 name: a.template.name,
                 base: live && { id: live.id, version: live.current_version },
                 id,
                 to,
-                prefix: syncVersionPrefix(platformAgentTemplatePrefix(id, to), version),
-                file: { ...file, path: file.path.split("/").pop() },
+                prefix: contentPrefix("agent-templates", [{ path: name, sha256: file.sha256 }]),
+                file: { ...file, path: name },
                 template: a.template,
             });
         }
@@ -554,9 +546,7 @@ let PlatformComponents = class PlatformComponents {
                 base: live && { id: live.id, version: live.current_version },
                 id,
                 to,
-                prefix: t.assets.length > 0
-                    ? syncVersionPrefix(`${platformThemePrefix(id)}${to}/`, version)
-                    : null,
+                prefix: t.assets.length > 0 ? contentPrefix("themes", t.assets) : null,
                 files: t.assets,
                 theme: t.theme,
             });

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";
@@ -16,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";
@@ -27,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.
@@ -54,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.
  *
@@ -413,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;
     /**
@@ -436,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();
     /**
@@ -587,11 +591,12 @@ export declare class PluginImport {
         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
@@ -605,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