@capybara-hq/kernel 0.1.0-rc.4 → 0.1.0-rc.5

package/dist/catalog/catalog.service.js

@@ -11,21 +11,23 @@ import { isSafePackagePath, marketplaceEntryVersion, } from "@capybara-hq/plugin
 import { Inject, Injectable } from "@nestjs/common";
 import { sql } from "kysely";
 import { ApiError } from "../errors.js";
-import { ExtensionAdminOps } from "../extensions/admin-ops.js";
+import { ExtensionAdmin } from "../extensions/admin-view.js";
 import { ExtensionInstalls } from "../extensions/installs.js";
+import { PluginInstallLock } from "../extensions/locks.js";
 import { audit } from "../identity/audit.js";
-import { EnterpriseAdminLock } from "../identity/enterprise-admin.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 { Transactional } from "../infra/database/transactional.decorator.js";
 import { sameRepository } from "../packages/provenance.js";
-import { countInstalls, itemView, marketplaceLatest } from "./catalog-items.js";
+import { countInstalls, itemConfirmations, itemScopeFacts, itemView, marketplaceLatest, versionUsable, } from "./catalog-items.js";
 import { expandGitUrl, GitSourceError, gitErrorDetails, normalGitPath, readGitTreeAndOids, resolveGitCommit, } from "./git-source.js";
 import { fetchMarketplaceArchive, marketplaceNetPolicy, marketplaceUrlProblem, } from "./marketplace-fetch.js";
-import { entryCompatible, entrySourceHost, HOST_VERSIONS, hostAllowed, loadMarketplaceEntry, MarketplacesService, pluginNameFrom, } from "./marketplaces.service.js";
+import { assertEntryNotDeprecated, entryCompatible, entrySourceHost, HOST_VERSIONS, hostAllowed, loadMarketplaceEntry, MarketplacesService, pluginNameFrom, } from "./marketplaces.service.js";
+import { releaseExtensionClaim } from "./ownership.js";
 import { PluginImport } from "./plugin-import.js";
-import { cancelPendingRequests } from "./requests.service.js";
+import { cancelPendingRequests } from "./request-rules.js";
 import { newestFirst } from "./versions.js";
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const notFound = () => new ApiError("catalog.item_not_found", "Catalog item not found");
@@ -77,34 +79,41 @@ function gitSource(loc, read, pinned) {
 export const CATALOG_LIST_DEFAULT_LIMIT = 200;
 export const CATALOG_LIST_MAX_LIMIT = 1000;
 /**
- * Enterprise catalog items (D9 / C21 / C22, `/api/v1/admin/catalog/*`, enterprise admins only). One
+ * Platform catalog items (D9 / C21 / C22, `/api/v1/admin/catalog/*`, super admins only). One
  * kind: every item is a plugin (spec §4), imported through {@link PluginImport} (prepare -> confirm,
- * one review); this service lists and shows items, changes policy, deletes, installs an item's
- * extension on the deployment, and prepares marketplace imports. Stateless, shared by every replica.
+ * one review, whose confirm installs the plugin's extension); this service lists and shows items,
+ * deletes, and prepares marketplace imports (scope and disable: `CatalogScopeService`). Stateless,
+ * shared by every replica.
  */
 let CatalogService = class CatalogService {
     kdb;
     adminLock;
     config;
     installs;
-    ops;
+    admin;
     pluginImport;
     marketplaces;
+    installLock;
     txHost;
     constructor(kdb, 
-    /** The enterprise admin lock (identity/enterprise-admin.ts): joins the caller's transaction. */
-    adminLock, config, installs, ops, 
+    /** The super admin lock (identity/super-admin.ts): joins the caller's transaction. */
+    adminLock, config, installs, 
+    /** The deployment's extensions with their approvals (what is pending confirmation). */
+    admin, 
     /** Plugin import (a marketplace entry goes through its prepare). */
     pluginImport, 
-    /** The token of an enterprise marketplace (sent only to its URL's origin). */
-    marketplaces, txHost) {
+    /** The token of a custom marketplace (sent only to its URL's origin). */
+    marketplaces, 
+    /** Serializes a claim release with an install of that name still committing (F10). */
+    installLock, txHost) {
         this.kdb = kdb;
         this.adminLock = adminLock;
         this.config = config;
         this.installs = installs;
-        this.ops = ops;
+        this.admin = admin;
         this.pluginImport = pluginImport;
         this.marketplaces = marketplaces;
+        this.installLock = installLock;
         this.txHost = txHost;
     }
     /** The kernel-schema handle of the current context (the transaction, else the pool). */
@@ -124,7 +133,8 @@ let CatalogService = class CatalogService {
     /**
      * Prepares the import of one marketplace entry (C25 / C26, spec §5.2): `version` defaults to the
      * newest compatible version the marketplace lists for `name`; the entry must be compatible with
-     * the host (`marketplace.incompatible`); an npm source is downloaded from the configured registry
+     * the host (`marketplace.incompatible`) and not deprecated (`marketplace.entry_deprecated`, 409; the
+     * confirm does not read the marketplace again); an npm source is downloaded from the configured registry
      * and an archive source from its URL, both always verified against the marketplace's integrity
      * (`marketplace.integrity_mismatch`, nothing written). A `path` source is read from the git
      * marketplace's repository at its last refreshed commit (an http marketplace has none:
@@ -146,6 +156,7 @@ let CatalogService = class CatalogService {
         if (!entryCompatible(entry)) {
             throw new ApiError("marketplace.incompatible", `${entry.name}${version !== null ? `@${version}` : ""} needs kernel >= ${entry.minKernel}; this deployment runs kernel ${HOST_VERSIONS.kernel}`);
         }
+        assertEntryNotDeprecated(entry);
         const src = entry.source;
         const host = entrySourceHost(entry);
         if (host !== undefined && !hostAllowed(host, config)) {
@@ -327,6 +338,25 @@ let CatalogService = class CatalogService {
     }
     /** Same as {@link list}, plus the offset of the next page (null when there is none). */
     async page(q = {}) {
+        // `pending`: every item waiting for a confirmation (one list, not paged: the pending set is small)
+        if (q.pending === true) {
+            const all = await this.page({
+                ...(q.includeDeleted && { includeDeleted: true }),
+                limit: CATALOG_LIST_MAX_LIMIT,
+            });
+            const items = [...all.items];
+            let next = all.nextOffset;
+            while (next !== null) {
+                const more = await this.page({
+                    ...(q.includeDeleted && { includeDeleted: true }),
+                    limit: CATALOG_LIST_MAX_LIMIT,
+                    offset: next,
+                });
+                items.push(...more.items);
+                next = more.nextOffset;
+            }
+            return { items: items.filter((i) => i.pending), nextOffset: null };
+        }
         const limit = Math.min(Math.max(1, q.limit ?? CATALOG_LIST_DEFAULT_LIMIT), CATALOG_LIST_MAX_LIMIT);
         const offset = Math.max(0, q.offset ?? 0);
         let query = this.db
@@ -354,19 +384,29 @@ let CatalogService = class CatalogService {
             "integrity",
             "source_detail",
             "imported_at",
+            "manifest",
+            "source_format",
+            "applied_at",
+            "rejected_at",
         ])
             .where("item_id", "in", items.map((i) => i.id))
             .execute();
+        const platformOwned = new Set(items.filter((i) => i.owner_org_id === null).map((i) => i.id));
         const byItem = new Map();
         for (const v of versions) {
+            // a platform item offers only versions it may use (a transferred org item's rejected or
+            // never-applied uploads stay out, ruling P3-52); an org item's pending ones show in 待确认
+            if (platformOwned.has(v.item_id) && !versionUsable(v))
+                continue;
             const list = byItem.get(v.item_id) ?? [];
             list.push(v);
             byItem.set(v.item_id, list);
         }
         const installs = await countInstalls(this.db, items, byItem);
         const latest = await marketplaceLatest(this.db, this.config.get(), items, byItem);
+        const facts = await itemScopeFacts(this.db, items, await itemConfirmations(this.admin, items, byItem));
         return {
-            items: items.map((i) => itemView(i, byItem.get(i.id) ?? [], installs.get(i.id) ?? 0, latest.get(i.id))),
+            items: items.map((i) => itemView(i, byItem.get(i.id) ?? [], installs.get(i.id) ?? 0, latest.get(i.id), facts.get(i.id))),
             nextOffset,
         };
     }
@@ -381,20 +421,22 @@ let CatalogService = class CatalogService {
             .executeTakeFirst();
         if (!item)
             throw notFound();
-        const rows = await this.db
+        const rows = (await this.db
             .selectFrom("catalog_item_versions")
             .selectAll()
             .where("item_id", "=", itemId)
-            .execute();
+            .execute()).filter((v) => item.owner_org_id !== null || versionUsable(v));
         rows.sort((a, b) => newestFirst({ version: a.version, importedAt: a.imported_at }, { version: b.version, importedAt: b.imported_at }));
         const byItem = new Map([[item.id, rows]]);
         const installs = await countInstalls(this.db, [item], byItem);
         const latest = await marketplaceLatest(this.db, this.config.get(), [item], byItem);
+        const facts = await itemScopeFacts(this.db, [item], await itemConfirmations(this.admin, [item], byItem));
         return {
             item: {
-                ...itemView(item, rows, installs.get(item.id) ?? 0, latest.get(item.id)),
+                ...itemView(item, rows, installs.get(item.id) ?? 0, latest.get(item.id), facts.get(item.id)),
                 packageName: item.package_name,
                 deletedAt: item.deleted_at?.toISOString() ?? null,
+                platformVersion: item.platform_synced_version ?? item.latest_version,
             },
             versions: rows.map((v) => ({
                 version: v.version,
@@ -416,43 +458,6 @@ let CatalogService = class CatalogService {
             })),
         };
     }
-    /**
-     * Changes the policy (audit `catalog.policy_changed`, not written when unchanged). Deleted /
-     * missing -> `catalog.item_not_found`.
-     */
-    async setPolicy(actor, itemId, policy, opts = {}) {
-        if (!UUID_RE.test(itemId))
-            throw notFound();
-        await this.writePolicy(actor, itemId, policy, opts);
-        return this.view(itemId);
-    }
-    async writePolicy(actor, itemId, policy, opts) {
-        const t = this.db;
-        await this.adminLock.lockAndAuthorize(actor);
-        const row = await t
-            .selectFrom("catalog_items")
-            .select(["name", "policy"])
-            .where("id", "=", itemId)
-            .where("deleted_at", "is", null)
-            .forUpdate()
-            .executeTakeFirst();
-        if (!row)
-            throw notFound();
-        if (row.policy === policy)
-            return;
-        await t
-            .updateTable("catalog_items")
-            .set({ policy, updated_at: sql `now()` })
-            .where("id", "=", itemId)
-            .execute();
-        await audit(t, {
-            actorAccountId: actor,
-            ...(opts.actorTokenId !== undefined && { actorTokenId: opts.actorTokenId }),
-            action: "catalog.policy_changed",
-            target: itemId,
-            detail: { name: row.name, from: row.policy, to: policy },
-        });
-    }
     /**
      * Deletes the item (soft delete, audit `catalog.removed`; requests still pending are cancelled in
      * the same transaction): versions and stored files are kept (installed components still refer to
@@ -465,84 +470,77 @@ let CatalogService = class CatalogService {
         await this.writeRemove(actor, itemId, opts);
     }
     async writeRemove(actor, itemId, opts) {
-        const t = this.db;
         await this.adminLock.lockAndAuthorize(actor);
+        if ((await this.removeIn(actor, itemId, opts)) === null)
+            throw notFound();
+    }
+    /**
+     * The soft delete of {@link remove} in the caller's transaction, without its super admin check
+     * (pre-flight F14: the super admin's remove and an owner's delete or an org deletion,
+     * `OwnedItems.transferOrRemove`, share it): `deleted_at` set, a pending version cleared, the
+     * extension name claim of a first upload still waiting released (ruling P3-37, F10), pending
+     * requests cancelled, audit `catalog.removed` (`actor` null: the kernel). Returns the removed
+     * item's name, or null when it is gone already.
+     */
+    async removeIn(actor, itemId, opts = {}) {
+        const t = this.db;
+        const now = sql `now()`;
         const row = await t
             .updateTable("catalog_items")
             .set({
-            deleted_at: sql `now()`,
-            updated_at: sql `now()`,
+            deleted_at: now,
+            updated_at: now,
+            pending_version: null,
+            pending_by: null,
+            pending_at: null,
         })
             .where("id", "=", itemId)
             .where("deleted_at", "is", null)
-            .returning(["name"])
+            .returning(["name", "awaiting_confirmation", "package_name", "owner_org_id"])
             .executeTakeFirst();
         if (!row)
-            throw notFound();
+            return null;
+        // An org upload still waiting: free the name when nothing is installed under its claim
+        // (ruling P3-37, pre-flight F10). Under the install lock, so an install a running confirmation
+        // is committing is seen: that claim stays for its take-out or the cleanup job
+        if (row.awaiting_confirmation && row.package_name !== null) {
+            await this.installLock.lock(row.name);
+            await releaseExtensionClaim(t, row.name, row.package_name);
+        }
         // Pending requests for a deleted item are pointless: cancel them in the same transaction
         await cancelPendingRequests(t, { itemId }, actor, "item_removed", opts);
         await audit(t, {
             actorAccountId: actor,
             ...(opts.actorTokenId !== undefined && { actorTokenId: opts.actorTokenId }),
+            // an org-owned item's removal shows in its owner org's audit log too
+            ...(row.owner_org_id !== null && { orgId: row.owner_org_id }),
             action: "catalog.removed",
             target: itemId,
-            detail: { name: row.name },
-        });
-    }
-    /**
-     * Installs the extension of one version of an item on the deployment
-     * (`ExtensionAdminOps.install`: a new install is disabled, a version change keeps the desired
-     * state; audit `extension.installed`), with the install record linked to the item (F-AA). The
-     * returned status may be `pending_approval` when the version's permissions are not approved yet.
-     * A version without an extension -> `catalog.no_extension`; item or version missing ->
-     * `catalog.item_not_found`.
-     */
-    async installToDeployment(actor, itemId, version, opts = {}) {
-        if (!UUID_RE.test(itemId))
-            throw notFound();
-        const item = await this.db
-            .selectFrom("catalog_items")
-            .select(["id", "name"])
-            .where("id", "=", itemId)
-            .where("deleted_at", "is", null)
-            .executeTakeFirst();
-        if (!item)
-            throw notFound();
-        const v = await this.db
-            .selectFrom("catalog_item_versions")
-            .select("extension_sha256")
-            .where("item_id", "=", itemId)
-            .where("version", "=", version)
-            .executeTakeFirst();
-        if (!v) {
-            throw new ApiError("catalog.item_not_found", `Version ${version} of this item not found`);
-        }
-        if (v.extension_sha256 === null) {
-            throw new ApiError("catalog.no_extension", `Plugin ${item.name} ${version} has no extension; there is nothing to install on the deployment`);
-        }
-        return this.ops.install(item.name, v.extension_sha256, actor, opts.actorTokenId, {
-            catalogItemId: itemId,
+            detail: {
+                name: row.name,
+                ...(row.owner_org_id !== null && { ownerOrgId: row.owner_org_id }),
+                ...(opts.reason !== undefined && { reason: opts.reason }),
+            },
         });
-    }
-    async view(itemId) {
-        return (await this.get(itemId)).item;
+        return { name: row.name };
     }
 };
-__decorate([
-    Transactional()
-], CatalogService.prototype, "writePolicy", null);
 __decorate([
     Transactional()
 ], CatalogService.prototype, "writeRemove", null);
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], CatalogService.prototype, "removeIn", null);
 CatalogService = __decorate([
     Injectable(),
     __param(0, Inject(KernelDb)),
-    __param(1, Inject(EnterpriseAdminLock)),
+    __param(1, Inject(SuperAdminLock)),
     __param(2, Inject(KernelConfigService)),
     __param(3, Inject(ExtensionInstalls)),
-    __param(4, Inject(ExtensionAdminOps)),
+    __param(4, Inject(ExtensionAdmin)),
     __param(5, Inject(PluginImport)),
     __param(6, Inject(MarketplacesService)),
-    __param(7, Inject(TransactionHost))
+    __param(7, Inject(PluginInstallLock)),
+    __param(8, Inject(TransactionHost))
 ], CatalogService);
 export { CatalogService };

package/dist/catalog/cli.d.ts

@@ -4,11 +4,21 @@ import { type ExtensionCli } from "../extensions/cli.js";
 import type { KernelLogger } from "../log.js";
 import { CatalogService } from "./catalog.service.js";
 import { PluginImport } from "./plugin-import.js";
+import type { PluginScope } from "./scope.js";
 /** {@link openCatalogCli}'s result: the extension CLI context plus the catalog services. */
 export interface CatalogCli extends ExtensionCli {
     catalog: CatalogService;
     /** Plugin import (prepare / confirm). The CLI acts without an account (actor `null`). */
     imports: PluginImport;
+    /**
+     * After an import's confirm: enqueues the item's plugin scope sync, as the admin console's
+     * confirm does, when its scope turns it on by itself (`all` or `named`). A failure only warns
+     * (the next worker start enqueues every item); returns whether it was enqueued.
+     */
+    enqueueScopeSync(item: {
+        id: string;
+        scope: PluginScope;
+    }): Promise<boolean>;
 }
 /** What the CLI can do with the deployment's object store, and why not when it cannot. */
 export type CliObjectStore = {
@@ -35,7 +45,7 @@ export declare function loadCliObjectStore(cli: Pick<ExtensionCli, "inspected" |
  * The CLI's plugin catalog context (`capybara plugins *`): {@link openExtensionCli} with the
  * catalog's {@link CatalogImportModule}, so {@link PluginImport} and {@link CatalogService} are the
  * kernel's providers. Imports run with actor `null` (the operator of the
- * deployment, like `capybara extensions install`: no enterprise-admin re-check, audits without an
+ * deployment, like `capybara extensions install`: no super-admin re-check, audits without an
  * actor, permission snapshots written with source `cli`). Files of the plugin (skills, connector
  * templates, icons) go to the deployment's object store, set up in-process from the declared or
  * installed object-store extension (see {@link loadCliObjectStore}; an installed package is synced

package/dist/catalog/cli.js

@@ -8,11 +8,15 @@ import { openExtensionCli } from "../extensions/cli.js";
 import { assertSecretsReachable } from "../extensions/host.js";
 import { importExtensionModule, matchesSection } from "../extensions/instance.js";
 import { packageRootOf, syncPackage } from "../extensions/sync.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { addJobOnce } from "../infra/queue/add-job-once.js";
+import { REDIS } from "../infra/tokens.js";
 import { packagePath } from "../packages/tgz.js";
 import { PrefixedStorage } from "../storage/storage.service.js";
 import { CatalogImportModule } from "./catalog.module.js";
 import { CatalogService } from "./catalog.service.js";
 import { PluginImport } from "./plugin-import.js";
+import { PLUGIN_SCOPE_QUEUE, scopeItemJob } from "./scope-sync.js";
 /**
  * Sets up the deployment's object-store extension inside the CLI process. The CLI hosts no
  * extensions, so this runs only the provider's `setup` with a context that offers `config` and
@@ -148,7 +152,7 @@ class CliStorage extends PrefixedStorage {
  * The CLI's plugin catalog context (`capybara plugins *`): {@link openExtensionCli} with the
  * catalog's {@link CatalogImportModule}, so {@link PluginImport} and {@link CatalogService} are the
  * kernel's providers. Imports run with actor `null` (the operator of the
- * deployment, like `capybara extensions install`: no enterprise-admin re-check, audits without an
+ * deployment, like `capybara extensions install`: no super-admin re-check, audits without an
  * actor, permission snapshots written with source `cli`). Files of the plugin (skills, connector
  * templates, icons) go to the deployment's object store, set up in-process from the declared or
  * installed object-store extension (see {@link loadCliObjectStore}; an installed package is synced
@@ -175,10 +179,31 @@ export async function openCatalogCli(config, log, opts = {}) {
         const imports = cli.app.get(PluginImport);
         imports.useCliStorage(storage);
         const catalog = cli.app.get(CatalogService);
+        const db = cli.app.get(KernelDb);
+        const redis = cli.app.get(REDIS);
         return {
             ...cli,
             catalog,
             imports,
+            async enqueueScopeSync(item) {
+                if (item.scope === "optional")
+                    return false;
+                try {
+                    const row = await db.db
+                        .selectFrom("catalog_items")
+                        .select("scope_version")
+                        .where("id", "=", item.id)
+                        .executeTakeFirst();
+                    if (!row)
+                        return false;
+                    await addJobOnce(redis, PLUGIN_SCOPE_QUEUE, scopeItemJob(item.id, row.scope_version));
+                    return true;
+                }
+                catch (err) {
+                    log.warn("cannot enqueue the plugin scope sync; the next worker start converges the orgs", { itemId: item.id, err });
+                    return false;
+                }
+            },
             async close() {
                 await cli.close();
                 await removeSyncDir();

package/dist/catalog/component-promotion.d.ts

@@ -0,0 +1,96 @@
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import { ApiError } from "../errors.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { StorageService } from "../storage/storage.service.js";
+/** The kinds an org owns as rows of its own (connector templates have none). */
+export type PromotableKind = "skill" | "agent_template";
+/**
+ * An org's own skill (org scope) or agent template, as the admin component routes see it: not
+ * linked (`link` null), or linked to a platform row the same org owns (`link`: that row, already
+ * promoted). A copy linked to a platform row of another owner is never an `OrgRow`.
+ */
+export interface OrgRow {
+    kind: PromotableKind;
+    id: string;
+    orgId: string;
+    name: string;
+    /** The roster plugin of an agent template (null: a bare `<name>`); null for skills. */
+    plugin: string | null;
+    version: number;
+    shareable: boolean;
+    /** The platform row the org promoted it to, or null while it is an org row only. */
+    link: string | null;
+    /**
+     * Content the org created itself (ruling P3-46): a skill without plugin provenance
+     * (`catalog_item_id` null); an agent template without a plugin and a catalog item (an org
+     * template saved from an agent, ruling P4-13). Anything else is refused with 409
+     * `catalog.not_owned`.
+     */
+    ownable: boolean;
+}
+/** A promotion whose files are copied ({@link ComponentPromotion.prepare}), waiting for its rows. */
+export interface PreparedPromotion {
+    readonly kind: PromotableKind;
+    readonly orgRowId: string;
+    readonly orgId: string;
+    /** The platform id it gets (the existing one when the row is promoted already). */
+    readonly platformId: string;
+    /** The org row's version the files were copied from. */
+    readonly version: number;
+    readonly already: boolean;
+    /** Where the files were copied (a fresh prefix, ruling P3-45); null: nothing copied. */
+    readonly prefix: string | null;
+}
+/** The org row changed between {@link ComponentPromotion.prepare} and its transaction: prepare again. */
+export declare class PromotionStale extends Error {
+}
+/** How many times a caller prepares again after {@link PromotionStale}. */
+export declare const PROMOTION_ATTEMPTS = 3;
+/** 409 `catalog.not_owned`: only the org's own rows can be shared (P3-6). */
+export declare function notOwnedError(what: string): ApiError;
+/** 409 `component.version_stale`: the org row kept changing while it was being promoted. */
+export declare const promotionStaleError: () => ApiError;
+/**
+ * Promotes an org's own skill or agent template to a platform row when it is first shared
+ * (ruling P3-3). Stateless, shared by every replica.
+ */
+export declare class ComponentPromotion {
+    private readonly kdb;
+    /** Where files are read and written (the kernel's object storage). */
+    private readonly files;
+    readonly txHost: TransactionHost;
+    constructor(kdb: KernelDb, 
+    /** Where files are read and written (the kernel's object storage). */
+    files: StorageService, txHost: TransactionHost);
+    private get db();
+    /**
+     * The live org row `id` of `kind` (an org-scope skill, an agent template) of a live org, when it
+     * is the org's own (see {@link OrgRow}); undefined otherwise.
+     */
+    orgRow(kind: PromotableKind, id: string, forUpdate?: boolean): Promise<OrgRow | undefined>;
+    /**
+     * The first phase, outside any transaction: reads the org row and (a skill) copies its current
+     * version's files to `deployment/platform/skills/<platformId>/<version>/`, checking each file
+     * against the manifest. A row promoted already needs nothing. A failed copy throws and nothing is
+     * linked (the copied files stay unreferenced). Missing or not the org's own -> 404.
+     */
+    prepare(kind: PromotableKind, orgRowId: string): Promise<PreparedPromotion>;
+    /** Deletes a prepared promotion's files after its transaction failed (best effort, P3-45). */
+    discard(p: PreparedPromotion): Promise<void>;
+    /**
+     * The second phase, in the caller's transaction: re-reads the org row under its lock (after the
+     * org row, so an org deletion is serialized), checks the share gate on it (409
+     * `catalog.not_shareable`) and writes the platform row (`current_version` = the org row's, one
+     * version row at that number), its list `[owner]`, and the link (no pin). Idempotent: a row the
+     * org promoted already returns its platform id. A version written since {@link prepare} ->
+     * {@link PromotionStale}; a live platform row of the same name created in this org already (a
+     * shared item whose owner deleted it and then made a new one) -> 409 `plugin.skill_conflict`.
+     * Audits `component.promoted`. Returns the platform id.
+     */
+    promote(p: PreparedPromotion, actor: string | null): Promise<string>;
+    /** Copies the skill's current version files to its platform prefix (outside any transaction). */
+    private copySkillFiles;
+}
+/** {@link ComponentPromotion.orgRow} through `db` (readers outside the provider). */
+export declare function readOrgRow(db: KernelSchemaDb, kind: PromotableKind, id: string, forUpdate?: boolean): Promise<OrgRow | undefined>;