@capybara-hq/kernel 0.1.0-rc.1 → 0.1.0-rc.11

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

@@ -1,20 +1,34 @@
-import { type AgentTemplate, type AgentTemplateTier, type Connector, type LocalizedName, type Logger } from "@capybara-hq/plugin-sdk";
-import type { KernelConfig } from "../config/schema.js";
-import type { KernelDb } from "../db/kernel-schema.js";
+import { type AgentTemplate, type AgentTemplateTier, type LocalizedName, type PluginManifest, type ThemeScheme } from "@capybara-hq/plugin-sdk";
+import type { Queue } from "bullmq";
 import { ApiError } from "../errors.js";
-import type { ExtensionAdminOps } from "../extensions/admin-ops.js";
-import type { ExtensionInstalls } from "../extensions/installs.js";
+import { ExtensionAdminOps } from "../extensions/admin-ops.js";
+import { ExtensionAdmin } from "../extensions/admin-view.js";
+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 PackageWarning, type PermissionGroup, type PermissionItem } from "../extensions/permission-view.js";
-import type { ExtensionSource } from "../extensions/sources.js";
+import { ExtensionRegistry } from "../extensions/registry.js";
+import type { SingleProviderBlock } from "../extensions/single-provider.js";
+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 type { KernelLogger } from "../log.js";
+import { OrgLock } from "../orgs/org-lock.js";
 import type { ProvenanceResult } from "../packages/provenance.js";
-import type { StorageService } from "../storage/storage.service.js";
-import { type ActorOpts, type CatalogItemView, type PermissionsMismatch, type SourceDetail } from "./catalog.service.js";
+import { type PrefixedStorage, StorageService } from "../storage/storage.service.js";
+import type { ActorOpts, CatalogItemView, PermissionsMismatch, SourceDetail } from "./catalog.service.js";
 import { type ClaudeEntryOverlay } from "./claude/manifest.js";
 import { type TranslationReport } from "./claude/report.js";
+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;
 /**
- * Enterprise import of a plugin (package ecosystem spec §4.3): one review for every plugin, whatever
+ * Platform import of a plugin (package ecosystem spec §4.3): one review for every plugin, whatever
  * it contains (an extension, skills, connector templates, dependencies), confirmed once.
  *
  * prepare: the tgz is always hostile input, and **nothing is written until every check passes**
@@ -24,31 +38,34 @@ import { PluginPackageError } from "./plugin-package.js";
  * refused; name ownership; a downgrade to a version with unrun migrations is refused), each skill by
  * the skill package rules, each connector template against the connector loaded on this replica (or
  * statically when the connector is provided by the plugin's own extension or by a dependency), the
- * catalog name / version conflicts and the actor still an enterprise admin. Dependencies are only
+ * catalog name / version conflicts and the actor still a super admin. Dependencies are only
  * resolved against the imported catalog versions for the review (an unresolved one does not block
  * the import, spec §4.1); they are never fetched. Only then is the extension handed to
- * `ExtensionInstalls.ingest` (source `catalog`), the skill / template / icon files written to object
- * storage, a staging row written (24 hours) and `catalog.plugin_staged` audited.
+ * `ExtensionInstalls.ingest` (source `catalog`), the skill / template files written to object
+ * storage, the display files (icons, setup guide files; `catalog-files.ts`) written to PG with a
+ * staging row (24 hours), and `catalog.plugin_staged` audited. A display file inside a skill
+ * directory or at a template's path goes to both places: each reader finds it where it looks.
  *
  * confirm: `reviewHash` must match the staging; in one transaction it deletes the staging row
  * (confirm works once), locks the extension name and recomputes its deployment state (installed /
  * upgraded / swapped after the review -> `plugin.review_stale`), writes the extension's permission
- * snapshot when it is installed by this import (or upgraded with `deployExtension`; source web, audit
- * `extension.permissions_approved` carrying the plugin), and creates the item or adds the version
- * (`manifest` = the normalized plugin.json, `extension_sha256`, the files under the staging prefix).
- * After the commit, with `deployExtension`, the plugin's own extension is installed on the
- * deployment and enabled (`ExtensionAdminOps.install` + `enable`; each replica reconciles, no
- * restart); a failure is returned, not thrown, and an upgrade that was not installed gets its old
- * snapshot back.
+ * snapshot when it is installed or upgraded by this import (source web, audit
+ * `extension.permissions_approved` carrying the plugin), and creates the item (with the scope the
+ * admin chose, default `optional`) or adds the version (`manifest` = the normalized plugin.json,
+ * `extension_sha256`, the files under the staging prefix). After the commit the plugin's own
+ * extension is installed on the deployment and enabled (`ExtensionAdminOps.install` + `enable`;
+ * each replica reconciles, no restart); a failure is returned, not thrown, and an upgrade that was
+ * not installed gets its old snapshot back.
  *
  * Expired staging is cleaned by the maintenance job `app-staging-cleanup`
- * ({@link PluginImport.cleanupExpired}): it deletes the staging row and its object prefix; a stored
- * extension package stays in the content-addressed `extension_packages` (the same as importing the
- * same tgz again; without an install record referencing it it is never loaded).
+ * ({@link PluginImport.cleanupExpired}): it deletes the staging row and its object prefix, then the
+ * display files (`catalog_files`) nothing lists any more; a stored extension package stays in the
+ * content-addressed `extension_packages` (the same as importing the same tgz again; without an
+ * install record referencing it it is never loaded).
  */
 /** How long a staged import is kept. */
 export declare const PLUGIN_STAGING_TTL_MS: number;
-/** The deployment state of the plugin's extension and what confirming with `deployExtension` does. */
+/** The deployment state of the plugin's extension and what confirming does with it. */
 export type ExtensionReviewAction = "install" | "upgrade" | "keep";
 /** The plugin's extension in a review. */
 export interface PluginReviewExtension {
@@ -57,10 +74,17 @@ export interface PluginReviewExtension {
     /** sha256 of the plugin tgz (the package store key). */
     sha256: string;
     /**
-     * install: not on the deployment; upgrade: installed from another package (another version), the
-     * import's package replaces it when deployed; keep: this exact package is installed.
+     * install: not on the deployment; upgrade: installed from another package whose version is not
+     * above the import's, the import's package replaces it when confirmed; keep: this exact package is
+     * installed, or the installed version is newer (`olderThanDeployed`): the confirm records the
+     * version in the catalog only and never downgrades the deployment.
      */
     action: ExtensionReviewAction;
+    /**
+     * The import's version is below the one deployed: the review warns that confirming keeps the
+     * deployed extension (action `keep`); absent otherwise.
+     */
+    olderThanDeployed?: true;
     /** Installed on the deployment (any version). */
     deployed: boolean;
     /** The installed version (null when not installed). */
@@ -110,6 +134,18 @@ export interface PluginReviewAgentTemplate {
     maxSteps?: number;
     skills?: string[];
 }
+/** One theme in a review (themes spec §6): what the super admin sees before confirming. */
+export interface PluginReviewTheme {
+    /** The theme id (the file's base name). */
+    id: string;
+    name: LocalizedName;
+    /** The schemes it defines. */
+    schemes: ThemeScheme[];
+    /** Number of fonts. */
+    fonts: number;
+    /** It replaces the logo mark, the wordmark or the favicon. */
+    logo: boolean;
+}
 /** The source of a staged import. */
 export interface PluginImportSource {
     /**
@@ -125,11 +161,19 @@ export interface PluginImportSource {
     /** Where it came from (stored on the catalog version as `source_detail`). */
     detail?: SourceDetail;
 }
+/**
+ * An org upload (spec §14, rulings P3-7, P3-8): the org that will own the plugin. Its admin is
+ * authorized (`catalog.upload`) instead of the super admin, its staging is its own, and the new
+ * item is owned by it with scope `named: [orgId]`.
+ */
+export interface ImportOwner {
+    orgId: string;
+}
 /** The format a plugin was read from: a Capybara plugin, or a translated Claude Code plugin. */
 export type PluginSourceFormat = "capybara" | "claude-code";
 /** The largest license text stored (bytes); a longer one is omitted (`licenseTruncated`). */
 export declare const LICENSE_TEXT_MAX_BYTES = 65536;
-/** The one review of a plugin (the enterprise admin sees every component before confirming). */
+/** The one review of a plugin (the super admin sees every component before confirming). */
 export interface PluginReview {
     name: string;
     /** `claude-code`: translated from a Claude Code plugin (no extension; see `translation`). */
@@ -160,7 +204,10 @@ export interface PluginReview {
     /** package.json `name`; null for a git plugin without package.json. */
     packageName: string | null;
     publisher: string;
+    /** The plugin.json description's English text (a plain string description is English). */
     description: string;
+    /** Its Chinese text (`description.zh`); null without one. */
+    descriptionZh: string | null;
     displayName?: LocalizedName;
     license?: string;
     homepage?: string;
@@ -180,6 +227,11 @@ export interface PluginReview {
      * {@link pluginReviewHash} when empty, so their digests are unchanged.
      */
     agentTemplates?: PluginReviewAgentTemplate[];
+    /**
+     * Themes (themes spec §6). Absent without any; left out of {@link pluginReviewHash} when empty,
+     * so the digests of plugins without themes are unchanged.
+     */
+    themes?: PluginReviewTheme[];
     /**
      * Each dependency with the highest imported catalog version satisfying its range (null when
      * nothing does yet: the import still completes, an org install is refused until it is imported).
@@ -203,7 +255,7 @@ export interface PluginReview {
     /** Digest of everything above that confirm depends on; sent back on confirm. */
     reviewHash: string;
 }
-/** The deploy result of the plugin's extension with `deployExtension`. */
+/** The deploy result of the plugin's extension at confirm. */
 export interface ExtensionDeployResult {
     name: string;
     action: "install" | "upgrade";
@@ -212,19 +264,42 @@ export interface ExtensionDeployResult {
     sha256: string;
     /**
      * enabled: installed and enabled; installed: installed, desired state left as it was (confirm
-     * with `enable: false`, the bootstrap step's upgrades); failed: see code / message.
+     * with `enable: false`, the bootstrap step's upgrades), or left disabled because a
+     * single-provider extension point is taken (code / message / `singleProvider` say so); failed:
+     * see code / message.
      */
     result: "enabled" | "installed" | "failed";
     code?: string;
     message?: string;
+    /**
+     * Installed but left disabled (result `installed`, code `extension.single_provider_enabled`, or
+     * `extension.single_provider_required` when the holder is a required plugin): another enabled
+     * extension provides a single-provider extension point this one provides (a new install, or an
+     * upgrade whose new version newly provides it). The super admin disables that one, then enables
+     * this one; a required holder cannot be replaced.
+     */
+    singleProvider?: SingleProviderBlock;
     /** e.g. `snapshot_not_restored: …` when an upgrade failed and the snapshot had changed since. */
     note?: string;
 }
 /** The result of {@link PluginImport.confirm}. */
 export interface PluginConfirmResult {
     item: CatalogItemView;
-    /** null without `deployExtension` or when there is nothing to deploy (no extension, keep). */
+    /** This confirm created the item (a first import of the name), else it added a version. */
+    created: boolean;
+    /** null when there is nothing to deploy (no extension, or keep). */
     deploy: ExtensionDeployResult | null;
+    /**
+     * An org upload with an extension: the version waits for the super admin's confirmation
+     * (ruling P3-10); nothing was approved, installed or synced.
+     */
+    pending: boolean;
+    /**
+     * The confirm made the item's first usable version: it created the item, or it replaced an org
+     * upload's first version that was still waiting for the super admin with a version without an
+     * extension (applied at once, plan Task 6).
+     */
+    firstVersion: boolean;
 }
 /** What prepare checks besides the package itself (npm and marketplace imports). */
 export interface PluginPrepareExpect {
@@ -246,38 +321,102 @@ export interface ReviewProvenance {
     provenance: ProvenanceResult;
     warning?: "repository_mismatch";
 }
-export interface PluginImportDeps {
-    db: KernelDb;
-    config: () => KernelConfig;
-    storage: StorageService;
-    installs: Pick<ExtensionInstalls, "ingest" | "fetchNpm" | "fetchProvenance">;
-    ops: Pick<ExtensionAdminOps, "install" | "enable">;
-    /** Reads a package from the package store (confirm recomputes the permission set). */
-    blobs: {
-        get(sha256: string): Promise<Uint8Array>;
+/** What an org's staged upload targets (see {@link PluginImport.stagedTarget}). */
+export interface StagedTarget {
+    itemId: string;
+    version: string;
+    /** The review's own hash (an org's review of an update shows a combined one, P3-12). */
+    reviewHash: string;
+    /** The review has an extension. */
+    extension: boolean;
+    /** The live item exists already (a new version), owned by the staging's org. */
+    existing: boolean;
+    /** That item's first version still waits for the super admin (P3-9). */
+    awaiting: boolean;
+    /** The version is imported already (pre-flight F4). */
+    retry: boolean;
+    /** The target as the platform updater reads it (the staged manifest and files). */
+    target: {
+        version: string;
+        manifest: PluginManifest;
+        object_prefix: string | null;
+        files: {
+            path: string;
+            size: number;
+            sha256: string;
+        }[];
+        extension_sha256: string | null;
     };
-    /** Config-declared extension names -> source. */
-    declared: () => ReadonlyMap<string, ExtensionSource>;
-    /** The connector `kind` provided by extension `plugin` loaded on this replica. */
-    findConnector: (plugin: string, kind: string) => Connector | undefined;
-    /** The version of an extension loaded on this replica (templates' `pluginVersion` is checked). */
-    pluginVersion?: (plugin: string) => string | undefined;
-    /**
-     * false: this process loads no connectors (the CLI), so a template of an unknown connector gets
-     * only the static endpoint checks and `endpointChecked: false`; the org install re-checks it
-     * against the loaded connector. Default true (the HTTP path).
-     */
-    connectorsLoaded?: boolean;
-    log: Pick<Logger, "info" | "warn" | "error">;
 }
 /**
  * The API error of a plugin package that cannot be read in a catalog path: the pre-0.1.0 format ->
- * `catalog.legacy_format`, anything else -> `catalog.invalid_manifest` (issues as details).
+ * `catalog.legacy_format`; a failing theme (themes spec §5) -> `theme.invalid` (details
+ * `[{ theme, errors }]`) or `theme.unreadable` (details `[{ theme, issues }]`, the failing pairs);
+ * anything else -> `catalog.invalid_manifest` (issues as details).
  */
 export declare function catalogPackageError(e: PluginPackageError | ExtensionPackageError): ApiError;
 export declare class PluginImport {
-    private readonly d;
-    constructor(d: PluginImportDeps);
+    private readonly kdb;
+    /** The super admin lock (identity/super-admin.ts): joins the caller's transaction. */
+    private readonly adminLock;
+    /** The owner org's lock: an org upload re-checks its admin under it (ruling P3-7). */
+    private readonly orgLock;
+    private readonly installLock;
+    private readonly approveLock;
+    private readonly itemLock;
+    private readonly config;
+    private readonly installs;
+    private readonly ops;
+    private readonly admin;
+    /** Reads a package from the package store (confirm recomputes the permission set). */
+    private readonly blobs;
+    /** Config-declared names, loaded connectors and extension versions (the extension registry). */
+    private readonly registry;
+    private readonly log;
+    readonly txHost: TransactionHost;
+    /** The platform rows of a new item's components, written after the confirm's commit. */
+    private readonly platform;
+    /** A failed platform sync enqueues a run of the migration job here (it heals the item). */
+    private readonly maintenance;
+    /** Where plugin files go (the kernel's object storage; the CLI's own, see {@link useCliStorage}). */
+    private files;
+    /**
+     * false: this process loads no connectors (the CLI), so a template of an unknown connector gets
+     * only the static endpoint checks and `endpointChecked: false`; the org install re-checks it
+     * against the loaded connector.
+     */
+    private connectorsLoaded;
+    constructor(kdb: KernelDb, 
+    /** The super admin lock (identity/super-admin.ts): joins the caller's transaction. */
+    adminLock: SuperAdminLock, 
+    /** The owner org's lock: an org upload re-checks its admin under it (ruling P3-7). */
+    orgLock: OrgLock, installLock: PluginInstallLock, approveLock: PluginApproveLock, itemLock: CatalogItemLock, config: KernelConfigService, storage: StorageService, installs: ExtensionInstalls, ops: ExtensionAdminOps, admin: ExtensionAdmin, 
+    /** Reads a package from the package store (confirm recomputes the permission set). */
+    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. */
+    platform: PlatformComponents, 
+    /** A failed platform sync enqueues a run of the migration job here (it heals the item). */
+    maintenance: Pick<Queue, "add">);
+    /** The kernel-schema handle of the current context (the transaction, else the pool). */
+    private get db();
+    /**
+     * CLI only (like `ExtensionHost.noteInspected`): plugin files go to the object store the CLI set
+     * up itself, and connector templates get static checks only (the CLI loads no connector). Called
+     * once, right after the command's context is created.
+     */
+    useCliStorage(storage: PrefixedStorage): void;
+    /**
+     * The super-admin re-check under the lock, in the caller's transaction. `actor` null is the
+     * CLI (the operator of the deployment: no account to re-check, audits carry no actor), like
+     * `ExtensionInstalls.ingest`. An org upload (`owner`) re-checks the actor as an admin of the
+     * owner org under the org row lock instead (`catalog.upload`; an org deleted meanwhile -> 404
+     * `org.not_found`).
+     */
+    private authorizeActor;
+    /** The re-check alone, in a transaction of its own (before anything is written). */
+    private authorize;
     /**
      * Reads, checks and stages a plugin (see the file header). Returns the staging id and review.
      * `fallback` (a marketplace archive): a tgz without plugin.json may be skills only, named,
@@ -292,6 +431,8 @@ export declare class PluginImport {
         };
         provenance?: ReviewProvenance;
         claudeManifestIgnored?: true;
+        /** An org upload (a `file` source only, ruling P3-7). */
+        owner?: ImportOwner;
     }): Promise<{
         stagingId: string;
         review: PluginReview;
@@ -332,6 +473,8 @@ export declare class PluginImport {
      * (required with an extension: it is stored in the package store); `size` is recorded.
      */
     private prepareContents;
+    /** The staging row and the `catalog.plugin_staged` audit, the actor re-checked under the lock. */
+    private writeStaging;
     /** Fetches a plugin from the configured npm registry (verified by `dist.integrity`), then prepares it. */
     prepareNpm(actor: string | null, input: {
         package: string;
@@ -343,33 +486,90 @@ export declare class PluginImport {
     /**
      * A staged import's review, as prepare returned it, with a marketplace import's permission
      * mismatch when there is one (the import page loads `?staging=<id>` with it). Unknown, expired or
-     * already confirmed -> 404 `plugin.staging_not_found`.
+     * already confirmed -> 404 `plugin.staging_not_found`. Each sees only its own staging (P3-8):
+     * the super admin's routes the platform's (no `owner`), an org's routes that org's.
      */
-    staged(stagingId: string): Promise<{
+    staged(stagingId: string, owner?: ImportOwner): Promise<{
         stagingId: string;
         review: PluginReview;
         permissionsMismatch?: PermissionsMismatch;
     }>;
     /**
-     * Confirms a staged import (see the file header). Returns the committed catalog item and, with
-     * `deployExtension`, the extension's deploy result (a failed deploy is returned, not thrown).
+     * What an org's staged upload targets (P3-12, pre-flight F3): its item, version and review hash,
+     * whether the item exists (a new version of the org's own plugin) or the version is imported
+     * already (F4), and the target as the platform updater reads it: the staged manifest and files,
+     * or the imported version's for a retry. Another org's staging -> 404 `plugin.staging_not_found`.
+     */
+    stagedTarget(stagingId: string, owner: ImportOwner): Promise<StagedTarget>;
+    /** The catalog item's view (as a confirm returns it). */
+    view(itemId: string): Promise<CatalogItemView>;
+    /**
+     * Confirms a staged import (see the file header). Returns the committed catalog item and the
+     * extension's deploy result (a failed deploy is returned, not thrown). `scope` (default
+     * `optional`) and `orgs` (only with `named`; each an existing org, else `validation_failed`) are
+     * written when this confirm creates the item; a new version of an existing item keeps its scope.
+     * The caller enqueues the scope sync of the item after this returns.
+     *
+     * An org upload (`opts.owner`, spec §14): only that org's staging; the actor re-checked as its
+     * admin; `scope` / `orgs` are not taken: a new item is owned by the org, scope `named: [owner]`,
+     * not shown to other orgs, `shareable` as given (default false). Custom deny, the name owner and
+     * the dependencies are checked again under the item name's lock. A package with an extension
+     * is stored and its extension name claimed, nothing approved or installed: the version waits
+     * for the super admin (`pending`, ruling P3-10; see {@link commit}).
      */
     confirm(actor: string | null, stagingId: string, input: {
         reviewHash: string;
-        deployExtension: boolean;
         /**
-         * With `deployExtension`: enable the extension after installing it (default true). false
-         * keeps the install record's desired state (a new install stays disabled), for the bootstrap
-         * step's upgrades of a plugin an enterprise admin may have disabled.
+         * Enable the extension after installing it (default true). false keeps the install record's
+         * desired state (a new install stays disabled), for the bootstrap step's upgrades of a
+         * plugin a super admin may have disabled.
          */
         enable?: boolean;
+        /** The new item's scope (default `optional`). */
+        scope?: PluginScope;
+        /** The orgs of a `named` scope. */
+        orgs?: string[];
         /**
          * The skills (by name, each in the review) suggested as pinned when an agent selects them
          * (spec §9.1); replaces the plugin's `pinned` flags in the stored manifest. Omitted keeps
-         * them. An admin decision like `deployExtension`, so not part of `reviewHash`.
+         * them. An admin decision like the scope, so not part of `reviewHash`.
          */
         pinnedSuggestions?: string[];
-    }, opts?: ActorOpts): Promise<PluginConfirmResult>;
+        /** An org upload's new item: shared with other orgs by its owner (default false, P3-16). */
+        shareable?: 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}).
+     */
+    writePlatformComponents(itemId: string, version: string): Promise<void>;
+    /**
+     * The confirm's transaction: the staging row consumed, the extension's action recomputed under
+     * its install lock (stale -> `plugin.review_stale`), its snapshot approved, and the catalog
+     * version written under the item name's lock.
+     *
+     * An org upload with an extension (ruling P3-10) approves nothing: under the install lock it
+     * claims the extension name for its package (another package's -> 409
+     * `extension.name_conflict` naming its owner, before anything is written), and the version
+     * written becomes the item's pending one (`pending_version` / `_by` / `_at`; a first version
+     * also `awaiting_confirmation`). A later upload replaces the pending version (P3-11). An org
+     * upload without an extension for an item whose first version still waits (plan Task 6) replaces
+     * that upload and applies at once: the item stops waiting and the claim is released (nothing
+     * was installed under it).
+     */
+    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
@@ -379,7 +579,9 @@ export declare class PluginImport {
     private approve;
     /**
      * Deploys the plugin's extension after the commit: `install` (a new install is disabled, a version
-     * change keeps the desired state) then `enable`. Nothing is thrown; the result says what happened.
+     * change keeps the desired state) then `enable`, unless another enabled extension provides one of
+     * its single-provider extension points: then it stays disabled (result `installed` with code
+     * `extension.single_provider_enabled`). Nothing is thrown; the result says what happened.
      * When an upgrade was not installed, the snapshot overwritten at confirm is restored (the old
      * version keeps running, F-O; audit `extension.permissions_restored`). Retry through the extension
      * admin (the package is already in the package store) with the sha256 from the result.
@@ -393,11 +595,27 @@ export declare class PluginImport {
      */
     private restoreSnapshot;
     /**
-     * Deletes expired staging rows and their object prefixes (maintenance job `app-staging-cleanup`).
-     * Row by row: objects first, then the row (a failed object delete keeps the row for the next
-     * round); concurrent replicas skip each other's rows (`SKIP LOCKED`). Returns the rows deleted.
+     * Deletes expired staging rows and their object prefixes (maintenance job `app-staging-cleanup`),
+     * then the unused display files ({@link sweepDisplayFiles}). Row by row: objects first, then the
+     * row (a failed object delete keeps the row for the next round); concurrent replicas skip each
+     * other's rows (`SKIP LOCKED`). Returns the rows deleted.
      */
     cleanupExpired(): Promise<number>;
+    /** The expired staging rows, batch by batch; returns the rows deleted. */
+    private cleanupStagingRows;
+    /**
+     * One expired staging row (row lock, `SKIP LOCKED`): its objects, then the row; false when another
+     * replica has it or it is gone.
+     */
+    private cleanupOne;
+    /**
+     * An expired org staging's extension package (an org upload stores it at prepare, P3-10): removed
+     * with the staging unless something else uses it — an install (running or migrated), a catalog
+     * version, another staging — or it was stored by anyone else (the package row's source must be
+     * this staging's own `catalog` ref). A platform staging keeps its package, as before. Its object
+     * is deleted after the commit.
+     */
+    private dropOrgPackage;
     /** npm / marketplace imports: the package must be the one that was asked for. */
     private checkExpected;
     /** A config-declared extension's name cannot be taken by an imported plugin. */
@@ -409,7 +627,10 @@ export declare class PluginImport {
     private checkContent;
     /**
      * The highest imported, non-deleted catalog version satisfying each dependency's range (null when
-     * none does).
+     * none does). An org upload (`owner`, P3-13) resolves only against items the org can use
+     * ({@link usableBy}: confirmed, not disabled, offered to it), and any dependency left unresolved
+     * -> 409 `plugin.dependency_unavailable` (details `[{ dependencies }]`, their names): an org
+     * upload never brings in anything the org could not install itself.
      */
     private resolveDependencies;
     /**
@@ -427,10 +648,11 @@ export declare class PluginImport {
  * current version / package, its own review digest), every template field, each skill's name / path
  * / file count, the dependency resolution, the sha256 of every stored file, the format, the
  * translation report's items, the sha256 of the license text and the two review flags
- * (`claudeManifestIgnored`, `licenseTruncated`), and the agent templates when there are any.
+ * (`claudeManifestIgnored`, `licenseTruncated`), the agent templates when there are any and the
+ * themes when there are any.
  * Exported for tests. `repository` is display only.
  */
-export declare function pluginReviewHash(r: Pick<PluginReview, "name" | "version" | "contentDigest" | "extension" | "connectorTemplates" | "agentTemplates" | "skills" | "dependencies" | "format" | "translation" | "licenseText" | "claudeManifestIgnored" | "licenseTruncated">, files: {
+export declare function pluginReviewHash(r: Pick<PluginReview, "name" | "version" | "contentDigest" | "extension" | "connectorTemplates" | "agentTemplates" | "themes" | "skills" | "dependencies" | "format" | "translation" | "licenseText" | "claudeManifestIgnored" | "licenseTruncated">, files: {
     path: string;
     sha256: string;
 }[]): string;