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

package/dist/catalog/owned-plugin-cleanup.js

@@ -9,9 +9,9 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 // Taking out the extension of a removed org-owned plugin (plugin scope phase 3, spec §14, P3-20,
 // P3-21; pre-flight F9, F10): the one-off job `owned-plugin-cleanup-<itemId>` on
-// `cap-kernel-maintenance` (dispatched by `MaintenanceProcessor`) and its daily sweep. Worker-only:
-// `OwnedPluginCleanupModule` is imported only by `MaintenanceModule`, which only `WorkerModule`
-// imports.
+// `cap-kernel-maintenance` (dispatched by `MaintenanceProcessor`), owed in the outbox by the
+// removal's transaction (transactional outbox spec §8.1). Worker-only: `OwnedPluginCleanupModule`
+// is imported only by `MaintenanceModule`, which only `WorkerModule` imports.
 import { Inject, Injectable, Module } from "@nestjs/common";
 import { ApiError } from "../errors.js";
 import { ExtensionAdminOps } from "../extensions/admin-ops.js";
@@ -19,11 +19,8 @@ import { ExtensionsModule } from "../extensions/extensions.module.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 { LockService } from "../infra/lock/lock.service.js";
-import { LockedCron } from "../infra/schedule/locked-cron.decorator.js";
 import { KERNEL_LOGGER } from "../infra/tokens.js";
 import { CatalogImportModule } from "./catalog.module.js";
-import { OWNED_PLUGIN_CLEANUP_SWEEP_JOB } from "./job-ids.js";
 import { CatalogItemLock } from "./locks.js";
 import { releaseExtensionClaim } from "./ownership.js";
 /** Codes that mean another run (or the confirmation's own take-out) got there first. */
@@ -31,27 +28,24 @@ const GONE = new Set(["extension.not_found", "extension.not_disabled"]);
 /**
  * The cleanup of a removed org-owned plugin: {@link run} disables and uninstalls its extension (an
  * install of the item's name from the item's package) when no live catalog item uses it any more
- * ({@link OwnedPluginCleanup.referenced}), then releases the extension name claim, in one transaction under the import's item name lock
- * (pre-flight F10: the claim of an
- * installed extension is released here, never at the removal). Idempotent: a live item (a
- * transferred one), a platform item or nothing installed changes nothing but the claim. The
- * extension's data, secrets and configs stay, as with every uninstall. {@link sweep} runs it daily
- * for every removed org-owned item whose extension is still installed (a lost enqueue).
+ * ({@link OwnedPluginCleanup.referenced}), then releases the extension name claim, in one
+ * transaction under the import's item name lock (pre-flight F10: the claim of an installed
+ * extension is released here, never at the removal). Idempotent: a live item (a transferred one),
+ * a platform item or nothing installed changes nothing but the claim. The extension's data,
+ * secrets and configs stay, as with every uninstall.
  */
 let OwnedPluginCleanup = class OwnedPluginCleanup {
     kdb;
     ops;
     itemLock;
-    lockService;
     log;
     txHost;
     constructor(kdb, ops, 
     /** The import's item name lock (M5: no uninstall racing a re-import of the package). */
-    itemLock, lockService, log, txHost) {
+    itemLock, log, txHost) {
         this.kdb = kdb;
         this.ops = ops;
         this.itemLock = itemLock;
-        this.lockService = lockService;
         this.log = log;
         this.txHost = txHost;
     }
@@ -100,50 +94,6 @@ let OwnedPluginCleanup = class OwnedPluginCleanup {
         }
         await releaseExtensionClaim(this.db, name, pkg);
     }
-    /**
-     * Daily: {@link run} for every removed org-owned item no live item {@link referenced} names
-     * whose extension is still installed, or whose name claim is still held (a lost enqueue, or a
-     * run that uninstalled and failed before releasing the claim).
-     */
-    async sweep() {
-        const rows = await this.db
-            .selectFrom("catalog_items as ci")
-            .select("ci.id")
-            .where("ci.deleted_at", "is not", null)
-            .where("ci.owner_org_id", "is not", null)
-            .where("ci.package_name", "is not", null)
-            .where(({ and, or, not, exists, selectFrom }) => and([
-            not(exists(selectFrom("catalog_items as live")
-                .select("live.id")
-                .whereRef("live.name", "=", "ci.name")
-                .whereRef("live.package_name", "=", "ci.package_name")
-                .where("live.deleted_at", "is", null)
-                .where((eb) => eb.or([
-                eb("live.owner_org_id", "is", null),
-                eb("live.owner_org_id", "=", eb.ref("ci.owner_org_id")),
-            ])))),
-            or([
-                exists(selectFrom("extension_installs as x")
-                    .innerJoin("extension_packages as p", "p.sha256", "x.sha256")
-                    .select("x.name")
-                    .whereRef("x.name", "=", "ci.name")
-                    .whereRef("p.package_name", "=", "ci.package_name")),
-                exists(selectFrom("extension_name_owners as o")
-                    .select("o.name")
-                    .whereRef("o.name", "=", "ci.name")
-                    .whereRef("o.package_name", "=", "ci.package_name")),
-            ]),
-        ]))
-            .execute();
-        for (const r of rows) {
-            try {
-                await this.run(r.id);
-            }
-            catch (err) {
-                this.log.error("owned plugin cleanup failed", { itemId: r.id, err });
-            }
-        }
-    }
     /**
      * A live catalog item still uses the extension: one named like it (a plugin and its extension
      * share one name) from the same package whose owner is the removed item's owner (a re-upload)
@@ -165,22 +115,18 @@ let OwnedPluginCleanup = class OwnedPluginCleanup {
 __decorate([
     Transactional()
 ], OwnedPluginCleanup.prototype, "takeOut", null);
-__decorate([
-    LockedCron("40 3 * * *", { name: OWNED_PLUGIN_CLEANUP_SWEEP_JOB })
-], OwnedPluginCleanup.prototype, "sweep", null);
 OwnedPluginCleanup = __decorate([
     Injectable(),
     __param(0, Inject(KernelDb)),
     __param(1, Inject(ExtensionAdminOps)),
     __param(2, Inject(CatalogItemLock)),
-    __param(3, Inject(LockService)),
-    __param(4, Inject(KERNEL_LOGGER)),
-    __param(5, Inject(TransactionHost))
+    __param(3, Inject(KERNEL_LOGGER)),
+    __param(4, Inject(TransactionHost))
 ], OwnedPluginCleanup);
 export { OwnedPluginCleanup };
 /**
  * {@link OwnedPluginCleanup}: imported only by `MaintenanceModule` (the job's dispatcher), which
- * only the worker role imports, so the sweep runs on worker replicas only.
+ * only the worker role imports.
  */
 let OwnedPluginCleanupModule = class OwnedPluginCleanupModule {
 };

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/platform-import-update.d.ts

@@ -0,0 +1,50 @@
+import type { KernelLogger } from "../log.js";
+import type { ActorOpts, CatalogItemView } from "./catalog.service.js";
+import { PluginImport } from "./plugin-import.js";
+import { PlatformPluginUpdater, type PlatformUpdatePreview, type PlatformUpdateResult } from "./plugin-upgrade.js";
+/** `POST /api/v1/admin/catalog/imports/:stagingId/update`: the import and the update it applied. */
+export interface PlatformImportUpdateResult {
+    item: CatalogItemView;
+    update: PlatformUpdateResult;
+}
+/**
+ * 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.
+ */
+export declare class PlatformImportUpdate {
+    private readonly pluginImport;
+    private readonly updater;
+    private readonly log;
+    constructor(pluginImport: PluginImport, updater: PlatformPluginUpdater, log: KernelLogger);
+    /**
+     * 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.
+     */
+    preview(stagingId: string): Promise<PlatformUpdatePreview>;
+    /** Confirms the import and the update together (see the class comment). */
+    confirm(actor: string, stagingId: string, input: {
+        reviewHash: string;
+        diffHash: string;
+    }, opts?: ActorOpts): Promise<PlatformImportUpdateResult>;
+    /** The staged target, which must be a new version of a live platform-owned plugin. */
+    private target;
+    private previewOf;
+}