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

package/dist/catalog/plugin-package.js

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { AGENT_TEMPLATE_LIMITS, CATALOG_ITEM_NAME_RE, CONNECTOR_TEMPLATE_LIMITS, hostSdkProblem, PLUGIN_MANIFEST_FILE, PLUGIN_MANIFEST_LIMITS, parseAgentTemplate, parseConnectorTemplateFile, parsePluginManifest, parseSkillMd, SKILL_ENTRY_FILE, validatePluginPackageJsonFor, } from "@capybara-hq/plugin-sdk";
+import { AGENT_TEMPLATE_LIMITS, CATALOG_ITEM_NAME_RE, CONNECTOR_TEMPLATE_LIMITS, hostSdkProblem, PLUGIN_MANIFEST_FILE, PLUGIN_MANIFEST_LIMITS, parseAgentTemplate, parseConnectorTemplateFile, parsePluginManifest, parseSkillMd, SKILL_ENTRY_FILE, setupGuideFileProblem, validatePluginPackageJsonFor, } from "@capybara-hq/plugin-sdk";
 import { HOST_ZOD_VERSION, LEGACY_FORMAT_MESSAGE, PackageTgzError, packagePath, parsePackageJsonFile, unpackPackageTgz, } from "../packages/tgz.js";
 export { LEGACY_FORMAT_MESSAGE, packagePath };
 /** The plugin package is invalid; `issues` lists the problems (English, shown to the admin). */
@@ -354,6 +354,19 @@ export function readPluginFiles(files, opts) {
             issues.push(`icon: ${problem}`);
     }
     const ext = manifest.extension;
+    // Setup guides: their template files are text within the size limit (spec
+    // 2026-11-08-plugin-setup-guides-design.md §2); a channel guide needs a channel extension, which
+    // the manifest parser checks when the extension section is there
+    manifest.setupGuides?.forEach((g, i) => {
+        if (g.place === "channel-connection" && ext === undefined) {
+            issues.push(`setupGuides.${i}: a channel-connection guide needs the plugin's extension to provide channel@1`);
+        }
+        g.files?.forEach((f, j) => {
+            const problem = setupGuideFileProblem(f.path, files.get(packagePath(f.path)));
+            if (problem !== undefined)
+                issues.push(`setupGuides.${i}.files.${j}: ${problem}`);
+        });
+    });
     if (ext !== undefined) {
         if (!files.has(packagePath(ext.entry))) {
             issues.push(`extension.entry: ${ext.entry} not found in the package (the plugin has an extension but no build output; build it before packing or committing it)`);

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

@@ -1,222 +1,335 @@
-import type { AgentTemplate, ConnectorTemplateFile, PluginManifest } from "@capybara-hq/plugin-sdk";
-import type { SourceFormat } from "../db/kernel-schema.js";
-import type { OrgAction } from "../orgs/roles.js";
-import type { CreateConnectorInput, TemplateUpdateInput } from "../tools/connectors.service.js";
-import type { ConnectorAuth } from "../tools/credentials.js";
-import { type CatalogVersionFiles, type OrgCatalogTemplate } from "./org-catalog.service.js";
-import { type ComponentKind, type InstallPlan, type PluginInstaller, type PluginInstallInput, type PluginInstallView, type ResolvedDependency } from "./plugin-install.js";
-/** How a component differs between the installed and the target version. */
-export type UpgradeChange = "added" | "changed" | "removed" | "unchanged";
-/**
- * One component of an upgrade preview: `ref` is the extension name, the dependency's plugin name,
- * the skill name, the connector template id or the agent template name.
- */
-export interface UpgradeComponent {
+import type { PluginManifest } from "@capybara-hq/plugin-sdk";
+import { ExtensionAdminOps } from "../extensions/admin-ops.js";
+import { ExtensionBlobs } from "../extensions/blobs.js";
+import { ExtensionRegistry } from "../extensions/registry.js";
+import type { SingleProviderNote } 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 { LockService } from "../infra/lock/lock.service.js";
+import type { KernelLogger } from "../log.js";
+import { OrgLock } from "../orgs/org-lock.js";
+import { StorageService } from "../storage/storage.service.js";
+import { ConnectorsService } from "../tools/connectors.service.js";
+import { type CatalogVersionFiles } from "./catalog-content.js";
+import { type ComponentKind } from "./component-state.js";
+import { CatalogItemLock } from "./locks.js";
+import { PlatformComponents } from "./platform-components.js";
+import { PluginInstaller } from "./plugin-install.js";
+import { PluginScopeSync } from "./scope-sync.js";
+/** How a component differs between the platform's current and the target version (spec §7.1). */
+export type UpdateChange = "added" | "removed" | "upgrade" | "downgrade" | "same";
+/** One component of an update preview. */
+export interface PlatformUpdateComponent {
     kind: ComponentKind;
-    ref: string;
-    change: UpgradeChange;
-    detail?: string;
+    /** The platform component (null: added by the target). */
+    id: string | null;
+    /** Skill or agent template name; a connector template's id. */
+    name: string;
+    change: UpdateChange;
+    /** The catalog version of the component's current version (null: added, or no catalog version). */
+    from: string | null;
+    /** The target version (null: removed). */
+    to: string | null;
+    /** The current version was updated on its own (spec §7.2): the confirm moves it to the plugin's. */
+    updatedOnOwn: boolean;
+    /** The component has its own scope (spec §5 rule 2); the update keeps it. */
+    ownScope: boolean;
+    /**
+     * The orgs where the component is on whose linked copy is pinned to its own version (ruling B2):
+     * the confirm clears those pins, except for a removed component (the copy keeps its version).
+     */
+    pinnedOrgs: string[];
+    /**
+     * A removed skill or agent template agents use: it stays (spec §7.3), listed with the orgs and
+     * agents using it. Absent otherwise.
+     */
+    kept?: {
+        orgId: string;
+        agents: {
+            id: string;
+            name: string;
+        }[];
+    }[];
+}
+/** The org connectors an update touches (ruling E2, spec §6). */
+export interface PlatformUpdateConnectorOrg {
+    orgId: string;
+    /**
+     * Connectors made from a changed template: they get the template's endpoint preset (the org's
+     * values at the editable paths), auth preset and default policies; `credentialsReset` when the
+     * auth method or the credentials it needs changed (cleared: the org re-enters them).
+     */
+    connectors: {
+        id: string;
+        name: string;
+        templateId: string;
+        credentialsReset: boolean;
+    }[];
+    /**
+     * Templates the update turns on in the org where the plugin is on: added ones, and ones the
+     * target no longer ships off (`defaultEnabled`) without an org switch. Their connectors need the
+     * org's input (endpoint, credentials), so the update creates none.
+     */
+    needsConfig: string[];
+    /**
+     * Templates the target ships off (`defaultEnabled: false`) that were on in the org only by
+     * default (no org switch): they turn off there, with the agents using them; the connectors made
+     * from them stay as the org's own (`connectorsKept`). Absent when none.
+     */
+    turnedOff?: {
+        templateId: string;
+        agents: {
+            id: string;
+            name: string;
+        }[];
+        connectorsKept: number;
+    }[];
 }
-/** `POST …/plugin-installs/:installId/upgrade/preview` (spec §10, step 1). */
-export interface UpgradePreview {
-    from: string;
+/** `POST /api/v1/admin/catalog/items/:id/update/preview`. */
+export interface PlatformUpdatePreview {
+    itemId: string;
+    name: string;
+    /** The platform's current version (null: never synced). */
+    from: string | null;
     to: string;
-    /** Confirm with it; it changes when the target, the install's components or the inputs change. */
+    components: PlatformUpdateComponent[];
+    /**
+     * The deployment's extension moves (`from` null: installed by the update); null: unchanged.
+     * `orgs`: the orgs using it (where the plugin is on; spec §7.4, one version for all of them);
+     * `needsApproval`: the new version asks for permissions the approved snapshot does not cover,
+     * so it waits as `pending_approval` until the super admin approves them.
+     */
+    extension: {
+        from: string | null;
+        /** null: the target drops the extension (an owner update only, ruling P3-12'). */
+        to: string | null;
+        orgs: string[];
+        needsApproval: boolean;
+    } | null;
+    connectorOrgs: PlatformUpdateConnectorOrg[];
+    /**
+     * An owner's update preview only ({@link PlatformPluginUpdater.previewForOwner}): the name of
+     * every org the preview mentions, by id. An org admin cannot read other orgs, and these names
+     * are already disclosed to the owner (rulings P3-14, P3-19). Not covered by `diffHash`.
+     */
+    orgNames?: Record<string, string>;
+    /** Confirm with it; recomputed under the item lock at the confirm. */
     diffHash: string;
-    components: UpgradeComponent[];
-    inputs: {
-        /** Added templates: their connectors are created with the org's input (as at install). */
-        connectors: string[];
-        /** Changed templates whose auth method or required credentials changed: re-entry needed. */
-        credentialsChanged: string[];
-        /** The extension is added and not yet enabled in the org: its org config may be given. */
-        extensionConfig: boolean;
-    };
-    /**
-     * The target version's connector templates named in `inputs.connectors` and
-     * `inputs.credentialsChanged` (presets and auth, no credentials), for the input form: the target
-     * is not always the latest version (an extension's plugin moves to the deployed version).
-     */
-    templates: OrgCatalogTemplate[];
 }
-/** The body of `POST …/plugin-installs/:installId/upgrade`. */
-export interface PluginUpgradeInput extends PluginInstallInput {
+/** `PUT /api/v1/admin/catalog/items/:id/update`. */
+export interface PlatformUpdateResult {
+    itemId: string;
     version: string;
-    diffHash: string;
-}
-interface LedgerRow {
-    kind: ComponentKind;
-    ref: string;
-    created: boolean;
-    skill_version: number | null;
-    template_id: string | null;
-    dropped: boolean;
+    components: PlatformUpdateComponent[];
+    extension: PlatformUpdatePreview["extension"];
+    connectorOrgs: PlatformUpdateConnectorOrg[];
+    /**
+     * The update installed the extension but left it disabled: another enabled extension provides a
+     * single-provider extension point it provides (an extension the update added, or a new version
+     * that newly provides the point). Code `extension.single_provider_enabled` (disable that one
+     * first) or `extension.single_provider_required` (a required plugin holds it: no replacing).
+     */
+    extensionLeftDisabled?: SingleProviderNote;
 }
 interface VersionRow extends CatalogVersionFiles {
     version: string;
     manifest: PluginManifest;
-    source_format: SourceFormat;
-}
-interface SkillDiff {
-    name: string;
-    change: UpgradeChange;
-    /** The skill directory in the target version (added / changed / unchanged). */
-    dir?: string;
-    /** The target version suggests pinning the skill (spec §9.1). */
-    suggestPinned?: boolean;
-    /** The ledger row of the org skill (by skill id), when the install has one that is live. */
-    ledger?: LedgerRow;
-}
-interface AgentTemplateDiff {
-    name: string;
-    change: UpgradeChange;
-    /** The target version's template (added / changed / unchanged). */
-    template?: AgentTemplate;
-    /** The ledger row of the org template, when the install has one that is live. */
-    ledger?: LedgerRow;
-}
-interface TemplateDiff {
-    id: string;
-    change: UpgradeChange;
-    target?: ConnectorTemplateFile;
-    /** The org connector created from the template (live), when the install has one. */
-    connector?: {
-        id: string;
-        connector: string;
-        endpoint: unknown;
-        auth: ConnectorAuth;
-    };
-    ledger?: LedgerRow;
-    credentialsChanged: boolean;
-}
-interface DependencyDiff {
-    name: string;
-    change: UpgradeChange;
-    range?: string;
-    fromRange?: string;
-    resolved?: ResolvedDependency;
-    /** The dependency install recorded in the ledger. */
-    child?: {
-        installId: string;
-        version: string;
-        ledger: LedgerRow;
-    };
-    /** Added: null when already installed in the org (recorded created=false). */
-    plan?: InstallPlan | null;
+    extension_sha256: string | null;
 }
 /**
- * Everything an upgrade will do, computed before anything is written (opaque outside this module:
- * {@link PluginUpgrader.check} hands it to {@link PluginUpgrader.upgrade}).
+ * An update's target read from somewhere other than `catalog_item_versions`: an org upload's
+ * staging (pre-flight F3), so the org's review can show the update before the version is imported.
+ * Its files are at `object_prefix`, where the confirm's version row will point too.
  */
-export interface UpgradeDiff {
-    installId: string;
-    itemId: string;
-    name: string;
-    from: VersionRow;
-    to: VersionRow;
-    ledger: LedgerRow[];
-    extension: {
-        change: UpgradeChange;
-        name: string;
-    } | null;
-    skills: SkillDiff[];
-    agentTemplates: AgentTemplateDiff[];
-    templates: TemplateDiff[];
-    dependencies: DependencyDiff[];
-    components: UpgradeComponent[];
-    inputs: UpgradePreview["inputs"];
-    diffHash: string;
-    ledgerHash: string;
-    actions: OrgAction[];
-    /** With input: the connectors to create and the template updates to prepare. */
-    creates: Map<string, CreateConnectorInput>;
-    updates: Map<string, TemplateUpdateInput>;
-}
+export type UpdateTarget = VersionRow;
 /**
- * Org in-place upgrade (and, for declarative plugins, rollback) of an installed plugin (package
- * ecosystem spec §10, Decisions 9–11):
- * - **preview** diffs the installed and the target version per component (extension, dependency
- *   plugins, skills by name, connector templates by id) and returns the inputs needed and a
- *   `diffHash`; the same checks as an install run first (dependencies resolve, extension and
- *   template connectors deployed, skill conflicts -> `plugin.skill_conflict`), plus the target
- *   rules (`plugin.upgrade_target_invalid`): an extension-bearing plugin can move only to the
- *   catalog version carrying the deployment's extension, and installs depending on this plugin must
- *   still accept the target;
- * - **upgrade** re-checks the `diffHash` (`plugin.upgrade_stale`), sets the install `upgrading`
- *   under the org lock (another upgrade or an uninstall -> `plugin.install_in_progress`), then:
- *   added dependencies (installed by the install flow), the added extension (enabled), added and
- *   changed skills (a new version of the same skill; agents keep selecting it by id), added
- *   connectors (created from the template), and in one final transaction the changed connectors
- *   (template-owned fields only, `applyTemplateIn`), the removals by the uninstall rules, the new
- *   version and the audit `plugin.org_upgraded`. Each step is journaled in
- *   `plugin_installs.upgrade`; on failure the journal is undone (created components removed, skill
- *   versions reverted; changed connectors were never committed), the install stays `installed` at
- *   the old version with `error = { step, code }`, audit `plugin.org_upgrade_failed`, 502
- *   `plugin.upgrade_failed`. An upgrade interrupted for longer than `catalog.staleInstallMinutes`
- *   is undone by the next preview, upgrade or uninstall.
- * Approval follows the item's policy (the org catalog service creates the request). No in-process
- * state.
+ * The platform plugin update (spec §7; ruling F2 retires the per-org upgrades):
+ * - **preview** diffs the platform's current components of the plugin (the version recorded in
+ *   `catalog_items.platform_synced_version`, components updated on their own included) against a
+ *   catalog version: each skill (by name, by its files' digest), agent template (by name, canonical
+ *   definition) and connector template (by id, canonical file) is `added`, `removed`, `same`, or
+ *   `upgrade` / `downgrade` (the target's direction from the component's catalog version). It marks
+ *   components updated on their own, components with their own scope and the orgs whose linked
+ *   copy is pinned; lists removed components agents still use (they stay, spec §7.3), the org
+ *   connectors made from changed templates (all orgs, ruling E2; `credentialsReset` when the
+ *   credential shape changed), the templates it turns on that will need an org's input (added, or
+ *   no longer shipped off) and those it turns off (now shipped off, on only by default), the
+ *   deployment's extension move, and a `diffHash`. Refused: same version, a disabled or deleted
+ *   item, a target without the extension the deployment runs for it or moving a config-declared
+ *   one, a template moving to another connector, a plugin another platform plugin depends on
+ *   outside its range, and an added skill whose name is taken where the plugin is on (rule 10).
+ * - **update** runs under a Redis lock per item (another update -> `plugin.install_in_progress`):
+ *   the extension first (`ExtensionAdminOps.install`, enabled when the update installs it; added
+ *   permissions wait for the admin's approval as for any extension upgrade), then one transaction
+ *   under the item name's lock that recomputes the diff (`plugin.upgrade_stale` on a difference)
+ *   and writes the platform versions (`PlatformComponents.syncFromVersion`, which records
+ *   `platform_synced_version`), the pinned suggestions of unchanged skills, the removals (a
+ *   component no agent uses is soft-deleted, so unpinned linked copies go with it; pinned copies
+ *   keep their own version; a removed connector template leaves its connectors as the orgs' own),
+ *   clears the pins of linked copies, fans changed templates out to every connector made from them
+ *   (`applyTemplateIn`, under each org's row lock, credentials cleared only for a changed
+ *   credential shape), moves every org install to the version and audits
+ *   `plugin.platform_updated`; the scope sync of the item and its dependencies is enqueued after
+ *   the commit (orgs get new dependencies by rule 9). A failure rolls the transaction back and
+ *   puts the extension back where it was (audit `plugin.platform_update_failed`, 502
+ *   `plugin.upgrade_failed`); files copied to `deployment/platform/` stay unreferenced.
+ * Storage is never read or written inside the transaction: the target's contents (and the
+ * extension package, for `needsApproval`) are read and the platform files copied
+ * (`PlatformComponents.prepareSync`) after the Redis lock is taken and before the transaction,
+ * which reuses them and writes rows only (`applySyncIn`). The confirm-time diff treats the
+ * extension this update moved as expected (the install record must point at that package).
+ * Recovery: a process that dies between the extension step and the transaction leaves the
+ * deployment on the target's extension with the platform components unchanged; a new preview
+ * then shows the extension unchanged (`extension: null`) and the components still to move, and
+ * confirming it completes the update (or an update back to the old version moves it back).
+ * No in-process state.
  */
-export declare class PluginUpgrader {
+export declare class PlatformPluginUpdater {
+    private readonly kdb;
+    readonly txHost: TransactionHost;
+    private readonly adminLock;
+    private readonly itemLock;
+    private readonly orgLock;
+    private readonly locks;
+    private readonly storage;
+    private readonly registry;
+    private readonly ops;
+    /** Reads the target's extension package (its permissions, for `needsApproval`). */
+    private readonly blobs;
+    private readonly config;
+    private readonly platform;
+    /** Template dependencies (the deployed connector kinds). */
     private readonly installer;
-    private readonly d;
-    constructor(installer: PluginInstaller);
-    /** The upgrade preview (see the class comment). */
-    preview(orgId: string, actor: string, installId: string, version: string): Promise<UpgradePreview>;
+    private readonly connectors;
+    private readonly sync;
+    private readonly log;
+    constructor(kdb: KernelDb, txHost: TransactionHost, adminLock: SuperAdminLock, itemLock: CatalogItemLock, orgLock: OrgLock, locks: LockService, storage: StorageService, registry: ExtensionRegistry, ops: ExtensionAdminOps, 
+    /** Reads the target's extension package (its permissions, for `needsApproval`). */
+    blobs: ExtensionBlobs, config: KernelConfigService, platform: PlatformComponents, 
+    /** Template dependencies (the deployed connector kinds). */
+    installer: PluginInstaller, connectors: ConnectorsService, sync: PluginScopeSync, log: KernelLogger);
+    private get db();
+    /** The update preview (see the class comment); writes nothing. */
+    preview(itemId: string, version: string): Promise<PlatformUpdatePreview>;
     /**
-     * The checks of {@link upgrade} before an approval request (the org catalog service creates one
-     * for a needs_approval item without a grant): the diff with the input, the `diffHash`. Returns
-     * the item and the org actions the upgrade needs.
+     * The update preview of a new version of an org's own plugin (ruling P3-12): the item must be
+     * owned by `orgId` (else 404, as for any item the org cannot see), the target carries no
+     * extension (an extension-bearing version waits for the super admin, plan Task 6), and a target
+     * dropping the deployment's extension is allowed (P3-12'). `staged` is the target read from the
+     * org's staging (pre-flight F3); without it the imported version `version` is read. The route
+     * authorizes the org admin; writes nothing.
      */
-    check(orgId: string, actor: string, installId: string, input: PluginUpgradeInput): Promise<{
-        itemId: string;
-        name: string;
-        actions: OrgAction[];
-        diff: UpgradeDiff;
-    }>;
+    previewForOwner(orgId: string, itemId: string, version: string, staged?: UpdateTarget): Promise<PlatformUpdatePreview>;
     /**
-     * Runs an upgrade (see the class comment); returns the install view. `checked` is the diff
-     * {@link check} computed for the same input (re-verified under the org lock: the install's
-     * version and ledger must be unchanged), otherwise it is computed here.
+     * Locks, in sorted order and before the item (ruling P3-50), every live org the update may
+     * write in: the orgs with connectors made from the plugin's connector templates and the item's
+     * owner org. `acting`: the owner org an owner update acts for, locked with its admin re-checked
+     * (`catalog.upload`; deleted -> 404 `org.not_found`). Returns the live orgs locked; another
+     * deleted one is skipped.
      */
-    upgrade(orgId: string, actor: string, installId: string, input: PluginUpgradeInput, opts?: {
+    private lockUpdateOrgs;
+    /** The names of the orgs a preview mentions, by id (an owner's preview, see `orgNames`). */
+    private orgNamesOf;
+    /**
+     * Applies a new version of an org's own plugin for its owner (ruling P3-12, see
+     * {@link previewForOwner}): the actor must be an admin of the owner org (`catalog.upload`,
+     * re-checked under the org row lock in the transaction), then the platform update as
+     * {@link update} does, also removing the extension when the target drops it. In the update's
+     * transaction the orgs using the shared plugin are told (`shared_item_updated`, one notice per
+     * plugin) and a pending version is cleared (pre-flight F7: the new version replaces it).
+     */
+    updateAsOwner(orgId: string, actor: string, itemId: string, version: string, diffHash: string, opts?: {
+        actorTokenId?: string;
+    }): Promise<PlatformUpdateResult>;
+    /** The actor is an admin of the owner org (a read of the membership under the org row lock). */
+    private authorizeOwner;
+    /** Runs `f` holding the item's update lock (another update -> `plugin.install_in_progress`). */
+    private locked;
+    /**
+     * The super admin's confirmation of an org upload's pending new version (rulings P3-10, P3-21,
+     * pre-flight F8): the update to `version` as {@link update} does it (the super admin's, the
+     * extension installed or upgraded on the deployment), with the version allowed although it is
+     * pending. Its transaction re-reads the item under the row lock: removed meanwhile -> 409
+     * `catalog.item_removed`, the pending version replaced -> 409 `extension.approval_stale` (both
+     * undo the extension step); then the pending state is cleared and the owner told
+     * (`upload_confirmed`). The caller checked the digest of the version's package.
+     */
+    updateToPending(actor: string, itemId: string, version: string, opts?: {
         actorTokenId?: string;
-    }, checked?: UpgradeDiff): Promise<PluginInstallView>;
+    }): Promise<PlatformUpdateResult>;
     /**
-     * Undoes a failed upgrade (its journal, in one transaction): the install back `installed` at the
-     * old version with `error = { step, code }`, audit `plugin.org_upgrade_failed`. When the journal
-     * is no longer this upgrade's (another request cleaned it up as interrupted and undid what it
-     * journaled), only the step whose journal write failed is undone and the install row is left as
-     * the cleanup set it. Returns the error to throw: 502 `plugin.upgrade_failed` (a dependency
-     * another install is still installing: its 409 as it is).
+     * {@link updateToPending} for a caller already holding the item's update lock
+     * ({@link withItemLock}): the super admin's confirmation runs all its steps under it (ruling
+     * P3-35).
      */
-    private failed;
+    updateToPendingLocked(actor: string, itemId: string, version: string, opts?: {
+        actorTokenId?: string;
+    }): Promise<PlatformUpdateResult>;
     /**
-     * An upgrade interrupted for longer than `catalog.staleInstallMinutes` (a replica crashed
-     * midway): its journal is undone, the install back `installed` at the old version (error step
-     * `interrupted`), audit `plugin.org_upgrade_failed`. Nothing to do otherwise.
+     * Runs `f` holding the item's update lock (the one every platform update of the item takes;
+     * another holder -> 409 `plugin.install_in_progress`): the super admin's confirmation of an org
+     * upload runs every step under it (ruling P3-35).
      */
-    private recoverInterrupted;
+    withItemLock<T>(itemId: string, f: () => Promise<T>): Promise<T>;
     /**
-     * The removals of an upgrade, in the final transaction, by the uninstall rules
-     * (`decideRemovalIn`): only components this install created are removed, and only when nothing
-     * else uses them; one still used (by an agent, a connector or another extension) stays in the
-     * ledger marked `dropped` ("no longer in the plugin", still this install's), every other removed
-     * component leaves the ledger; a dropped component the target brings back is un-dropped. A dependency
-     * install is uninstalled by the same rules (another install using it takes it over). Skills ->
-     * connectors -> extension -> dependencies.
+     * Runs an update confirmed with the preview's `diffHash` (see the class comment). A version an
+     * org upload waits with, or an item whose first version waits, -> 409 `catalog.item_pending`
+     * (confirmed in 待确认 instead, pre-flight F8).
      */
-    private removeIn;
+    update(actor: string, itemId: string, input: {
+        version: string;
+        diffHash: string;
+    }, opts?: {
+        actorTokenId?: string;
+        auditDetail?: Record<string, unknown>;
+    }): Promise<PlatformUpdateResult>;
+    private updateLocked;
+    /** `plugin.platform_update_failed`, in a transaction of its own. */
+    private auditFailure;
     /**
-     * Computes an upgrade (see the class comment). `input` null: the preview (no input checks);
-     * otherwise the connector inputs are built and checked as at install.
+     * The update's transaction (see the class comment): the super admin re-checked, the diff
+     * recomputed under the item name's lock, then every write. Returns the diff it applied.
+     */
+    private commit;
+    /**
+     * The template update of one connector: the new endpoint preset with the org's values at the
+     * editable paths, the auth preset and default policies; credentials cleared (no new ones: they
+     * are the org's) when the credential shape changed.
+     */
+    private prepare;
+    /**
+     * Computes an update (see the class comment). `target`: the target read from an org's staging
+     * instead of `catalog_item_versions` (pre-flight F3). `owner`: an owner update (P3-12): the item
+     * must be the org's, an extension-bearing target is refused, and a target dropping the
+     * extension removes it.
      */
     private diff;
+    /** The target's skill names, agent templates and connector templates, from object storage. */
+    private readContents;
+    /**
+     * Whether the target's extension package asks for permissions the approved snapshot does not
+     * cover (no snapshot, or a blocking addition): it then loads only once approved (§7.4).
+     */
+    private needsApproval;
+    /**
+     * The deployment's extension step: none when the target carries the extension the deployment
+     * runs; a version without the extension the deployment runs for the plugin is refused, except
+     * for an owner update (`allowRemove`, ruling P3-12': removing code runs none), which removes an
+     * installed one; a move of a config-declared extension is refused.
+     */
+    private extensionTarget;
     /**
-     * The update of a changed template's connector: the new endpoint preset with the org's values at
-     * the editable paths, the new auth preset and policies; credentials only when the auth method or
-     * the credentials it needs changed (then the input must give what the template needs).
+     * Other platform plugins depending on this one must accept the target (their platform version's
+     * dependency range); returns the catalog items of the target's own dependencies (their scope
+     * sync is enqueued after the update: rule 9).
      */
-    private templateUpdate;
+    private checkDependents;
+    /** The plugin's live platform components with their current versions. */
+    private liveComponents;
+    /** The orgs where the plugin is on: a live install (builtin: every live org). */
+    private pluginOrgs;
+    private liveOrgs;
 }
 export {};