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

package/dist/catalog/ownership.js

@@ -0,0 +1,326 @@
+// Owners of catalog items and platform components, and the share gate (plugin scope phase 3, spec
+// §14, rulings P3-1, P3-16, P3-17). An item or component is owned by the platform
+// (`owner_org_id` null) or by one org; an org-owned one reaches other orgs only while its owner
+// makes it shareable. Every writer that shows an item to another org or associates one checks the
+// gate on the row it writes, read `FOR UPDATE` in its transaction.
+import { createHash } from "node:crypto";
+import { sql } from "kysely";
+import { ApiError } from "../errors.js";
+import { componentOn, listedIn, loadComponents, loadScopeState, pluginFactsOf, switchOf, } from "./component-state.js";
+import { wantedOn } from "./scope.js";
+export const PLATFORM_OWNER = { kind: "platform" };
+/**
+ * The share gate (P3-1): a platform item, or an org-owned one its owner made shareable. Closed:
+ * the item is never shown, requestable or associable outside its owner (orgs already associated
+ * keep it).
+ */
+export function shareGate(row) {
+    return row.owner_org_id === null || row.shareable;
+}
+/** 409 `catalog.not_shareable` unless the row passes the {@link shareGate} (P3-16). */
+export function assertShareable(row) {
+    if (shareGate(row))
+        return;
+    throw new ApiError("catalog.not_shareable", `${row.name} is owned by an organization that has not made it shareable`);
+}
+/**
+ * 409 `catalog.owner_required` when a `named` list after a change leaves out the item's owner org
+ * (P3-17: the owner stays on its own item's list).
+ */
+export function assertOwnerListed(row, target) {
+    if (row.owner_org_id === null || target.scope !== "named")
+        return;
+    if (target.orgs.includes(row.owner_org_id))
+        return;
+    throw new ApiError("catalog.owner_required", `${row.name} is owned by an organization that must stay on its list`);
+}
+const BREADTH = { named: 0, optional: 1, all: 2 };
+/**
+ * A widening of the scope for a row that does not pass the share gate -> 409
+ * `catalog.not_shareable`: a broader scope (`named` < `optional` < `all`), or, `named` to `named`,
+ * an org not on the list before the change. Narrowing is always allowed (P3-16).
+ */
+export function assertShareableTarget(row, from, target) {
+    if (shareGate(row))
+        return;
+    const wider = (BREADTH[target.scope] ?? 2) > (BREADTH[from.scope] ?? 2);
+    const known = new Set(from.orgs);
+    const added = from.scope === "named" && target.scope === "named" && target.orgs.some((o) => !known.has(o));
+    if (wider || added)
+        assertShareable(row);
+}
+/**
+ * Whether an item can serve anything at all (ruling P3-9, F12): confirmed (not a first upload
+ * still waiting for the super admin), not disabled and not deleted. The one predicate for the
+ * dependency check of org uploads (P3-13), the scope sync, org switches and installs.
+ */
+export function isUsable(item) {
+    return !item.awaiting_confirmation && !item.disabled && item.deleted_at === null;
+}
+/**
+ * 409 `catalog.item_pending`: the item, or the version asked for, waits for the super admin's
+ * confirmation in 待确认 (ruling P3-9): no scope edit, switch, install or generic update.
+ */
+export function itemPendingError(name, version) {
+    return new ApiError("catalog.item_pending", version === undefined
+        ? `${name} waits for a super admin to confirm its extension; confirm or reject it in 待确认 first`
+        : `Version ${version} of ${name} waits for a super admin to confirm its extension; confirm it in 待确认`);
+}
+/**
+ * 409 `catalog.item_removed`: the item was removed while a super admin confirmation of its upload
+ * was running (ruling P3-21).
+ */
+export function itemRemovedError(name) {
+    return new ApiError("catalog.item_removed", `${name} was removed while its confirmation was running; nothing of it stays installed`);
+}
+/** 409 `catalog.item_pending` while the item's first version waits for the super admin (P3-9). */
+export function assertNotAwaiting(item) {
+    if (item.awaiting_confirmation)
+        throw itemPendingError(item.name);
+}
+/**
+ * The digest a super admin confirms an org upload's pending version with (rulings P3-10, P3-11):
+ * the extension's permission review digest bound to the exact package, so a pending version
+ * replaced by another upload is stale even when both ask for the same permissions.
+ */
+export function pendingDigest(sha256, reviewHash) {
+    return createHash("sha256")
+        .update(JSON.stringify({ sha256, reviewHash }))
+        .digest("hex")
+        .slice(0, 32);
+}
+/**
+ * Releases the extension name an org upload claimed (pre-flight F10), in the caller's
+ * transaction, when nothing is installed under it: a rejected or withdrawn upload, a pending first
+ * version replaced by one without an extension, a deleted org's pending upload. An installed
+ * extension keeps its claim (its removal is the cleanup job's).
+ */
+export async function releaseExtensionClaim(db, name, packageName) {
+    if (packageName === null)
+        return;
+    const installed = await db
+        .selectFrom("extension_installs")
+        .select("name")
+        .where("name", "=", name)
+        .executeTakeFirst();
+    if (installed !== undefined)
+        return;
+    await db
+        .deleteFrom("extension_name_owners")
+        .where("name", "=", name)
+        .where("package_name", "=", packageName)
+        .execute();
+}
+/**
+ * Whether `orgId` can use the item (P3-13): {@link isUsable}, and its owner, or listed by a `named`
+ * scope (an org already associated keeps it), or offered to every org (`all` / `optional`, builtin)
+ * through the {@link shareGate} (another org's item only while it is shared).
+ */
+export function usableBy(item, orgId, listed) {
+    if (!isUsable(item))
+        return false;
+    if (item.owner_org_id === orgId)
+        return true;
+    if (!item.builtin && item.scope === "named")
+        return listed;
+    return listed || shareGate(item);
+}
+/**
+ * The owner of the live catalog item called `name` when it is not `owner` (null = the platform),
+ * else undefined: a plugin name is live for one owner only (ruling P3-14).
+ */
+export async function otherNameOwner(db, name, owner) {
+    const live = await db
+        .selectFrom("catalog_items")
+        .select("owner_org_id")
+        .where("name", "=", name)
+        .where("deleted_at", "is", null)
+        .executeTakeFirst();
+    if (live === undefined || live.owner_org_id === owner)
+        return undefined;
+    const ids = live.owner_org_id === null ? [] : [live.owner_org_id];
+    return ownerOf(live.owner_org_id, await ownersOf(db, ids));
+}
+/**
+ * 409 `plugin.name_taken` (details `[{ owner }]`) when the plugin name is live for another owner
+ * than `owner` (null = the platform): an org cannot upload a platform's or another org's name, and
+ * the super admin cannot import an org's (ruling P3-14). The same owner adds a version.
+ */
+export async function assertNameFree(db, name, owner) {
+    const other = await otherNameOwner(db, name, owner);
+    if (other === undefined)
+        return;
+    throw new ApiError("plugin.name_taken", other.kind === "platform"
+        ? `Plugin name ${name} is taken by the platform`
+        : `Plugin name ${name} is taken by organization ${other.name}`, [{ owner: other }]);
+}
+/**
+ * The owner other than `owner` (an org id) that already holds npm package `packageName`, else
+ * undefined (ruling P3-51: a package name is an identity only within one owner). Held = a catalog
+ * item of the package of another owner that is live, or removed while its extension is still
+ * installed or its name claimed (a cleanup not run yet); an install of the package whose catalog
+ * item is not one of `owner`'s (none = the platform: bootstrap or a direct install); a name claim
+ * of the package for which `owner` has no item of that name (an uninstalled platform extension
+ * keeps its claim).
+ */
+export async function otherPackageOwner(db, packageName, owner) {
+    if (packageName === null)
+        return undefined;
+    const found = async (ownerOrgId) => ownerOf(ownerOrgId, await ownersOf(db, ownerOrgId === null ? [] : [ownerOrgId]));
+    const item = await db
+        .selectFrom("catalog_items as ci")
+        .select("ci.owner_org_id")
+        .where("ci.package_name", "=", packageName)
+        .where(sql `ci.owner_org_id IS DISTINCT FROM ${owner}`)
+        .where(({ or, eb, exists, selectFrom }) => or([
+        eb("ci.deleted_at", "is", null),
+        exists(selectFrom("extension_installs as x")
+            .innerJoin("extension_packages as p", "p.sha256", "x.sha256")
+            .select("x.name")
+            .whereRef("x.name", "=", "ci.name")
+            .whereRef("p.package_name", "=", "ci.package_name")),
+        exists(selectFrom("extension_name_owners as o")
+            .select("o.name")
+            .whereRef("o.name", "=", "ci.name")
+            .whereRef("o.package_name", "=", "ci.package_name")),
+    ]))
+        .orderBy("ci.deleted_at", (o) => o.desc().nullsFirst())
+        .orderBy("ci.created_at")
+        .executeTakeFirst();
+    if (item !== undefined)
+        return found(item.owner_org_id);
+    const install = await db
+        .selectFrom("extension_installs as x")
+        .innerJoin("extension_packages as p", "p.sha256", "x.sha256")
+        .leftJoin("catalog_items as ci", "ci.id", "x.catalog_item_id")
+        .select(["ci.id", "ci.owner_org_id"])
+        .where("p.package_name", "=", packageName)
+        .where((eb) => eb.or([eb("ci.id", "is", null), eb("ci.owner_org_id", "is distinct from", owner)]))
+        .executeTakeFirst();
+    if (install !== undefined)
+        return found(install.id === null ? null : install.owner_org_id);
+    const claim = await db
+        .selectFrom("extension_name_owners as o")
+        .select("o.name")
+        .where("o.package_name", "=", packageName)
+        .where(({ not, exists, selectFrom }) => not(exists(selectFrom("catalog_items as ci")
+        .select("ci.id")
+        .whereRef("ci.name", "=", "o.name")
+        .whereRef("ci.package_name", "=", "o.package_name")
+        .where("ci.owner_org_id", "=", owner))))
+        .executeTakeFirst();
+    if (claim !== undefined)
+        return packageOwner(db, packageName, claim.name);
+    return undefined;
+}
+/**
+ * 409 `plugin.name_taken` (details `[{ owner }]`) when an org upload's npm package is held by
+ * another owner ({@link otherPackageOwner}, ruling P3-51): an org never shares a package identity
+ * with another org or the platform, so no name claim, existing install or cleanup can mistake one
+ * owner's plugin for another's.
+ */
+export async function assertPackageFree(db, packageName, owner) {
+    const other = await otherPackageOwner(db, packageName, owner);
+    if (other === undefined)
+        return;
+    throw new ApiError("plugin.name_taken", other.kind === "platform"
+        ? `Package ${packageName} is used by a plugin of the platform; rename the package (package.json name) and upload it again`
+        : `Package ${packageName} is used by a plugin of organization ${other.name}; rename the package (package.json name) and upload it again`, [{ owner: other }]);
+}
+/**
+ * The owner of extension `extensionName`, held by npm package `packageName` (package -> its live
+ * catalog item -> that item's owner; ruling P3-14). The item is the one named like the extension
+ * (a plugin and its extension share one name), else the oldest live item of the package; none ->
+ * the platform (an extension installed outside the catalog is the super admin's).
+ */
+export async function packageOwner(db, packageName, extensionName) {
+    if (packageName === null)
+        return PLATFORM_OWNER;
+    const item = await db
+        .selectFrom("catalog_items")
+        .select("owner_org_id")
+        .where("package_name", "=", packageName)
+        .where("deleted_at", "is", null)
+        .orderBy(sql `name = ${extensionName}`, "desc")
+        .orderBy("created_at")
+        .orderBy("id")
+        .executeTakeFirst();
+    const id = item?.owner_org_id ?? null;
+    return ownerOf(id, await ownersOf(db, id === null ? [] : [id]));
+}
+/** The owners of `orgIds` by org id (deleted orgs included, by their name). */
+export async function ownersOf(db, orgIds) {
+    const ids = [...new Set(orgIds)];
+    const out = new Map();
+    if (ids.length === 0)
+        return out;
+    const rows = await db.selectFrom("orgs").select(["id", "name"]).where("id", "in", ids).execute();
+    for (const r of rows)
+        out.set(r.id, { kind: "org", orgId: r.id, name: r.name });
+    return out;
+}
+/** The {@link Owner} of a row from {@link ownersOf}'s map (an org row gone: its id as the name). */
+export function ownerOf(ownerOrgId, owners) {
+    if (ownerOrgId === null)
+        return PLATFORM_OWNER;
+    return owners.get(ownerOrgId) ?? { kind: "org", orgId: ownerOrgId, name: ownerOrgId };
+}
+/**
+ * The live orgs an item is on in (ruling P3-18: listed and not switched off for `named`, switched
+ * on for `optional`, any live org for `all`; a component by {@link componentOn}), minus
+ * `except` (usually the owner), by name. One definition for the update notices and the
+ * "used by another org" check of deletes. An item that is gone or disabled is on nowhere.
+ */
+export async function orgsUsing(db, ref, opts = {}) {
+    const orgs = await db
+        .selectFrom("orgs")
+        .select(["id", "name"])
+        .where("deleted_at", "is", null)
+        .orderBy("name")
+        .orderBy("id")
+        .execute();
+    const others = orgs.filter((o) => o.id !== opts.except);
+    if (others.length === 0)
+        return [];
+    if (ref.kind === "plugin") {
+        const item = await db
+            .selectFrom("catalog_items")
+            .select(["scope", "builtin", "disabled"])
+            .where("id", "=", ref.id)
+            .where("deleted_at", "is", null)
+            .executeTakeFirst();
+        if (!item)
+            return [];
+        const listed = new Set((await db
+            .selectFrom("catalog_item_scope_orgs")
+            .select("org_id")
+            .where("item_id", "=", ref.id)
+            .execute()).map((r) => r.org_id));
+        const switches = new Map((await db
+            .selectFrom("catalog_item_org_switches")
+            .select(["org_id", "enabled"])
+            .where("item_id", "=", ref.id)
+            .execute()).map((r) => [r.org_id, r.enabled]));
+        return others.filter((o) => wantedOn(item, listed.has(o.id), switches.get(o.id) ?? null));
+    }
+    const kind = ref.kind;
+    const [c] = await loadComponents(db, kind, { ids: [ref.id] });
+    if (!c)
+        return [];
+    const st = await loadScopeState(db, kind, [c]);
+    return others.filter((o) => componentOn(c, pluginFactsOf(st, c.itemId, o.id), listedIn(st, c.id, o.id), switchOf(st, c.id, o.id)));
+}
+/**
+ * Who a scope change newly shows an org-owned item to (the `item_shared` notice, P3-22): the orgs
+ * added to a `named` list, or `all_orgs` when the scope gets broader (`named` < `optional` < `all`);
+ * nothing for a narrowing or a platform-owned item.
+ */
+export function newlySharedWith(from, to) {
+    if ((BREADTH[to.scope] ?? 2) > (BREADTH[from.scope] ?? 2))
+        return "all_orgs";
+    if (from.scope === "named" && to.scope === "named") {
+        const known = new Set(from.orgs);
+        return to.orgs.filter((o) => !known.has(o));
+    }
+    return [];
+}

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

@@ -0,0 +1,223 @@
+import { type AgentTemplate, type ConnectorTemplateFile } from "@capybara-hq/plugin-sdk";
+import type { SkillManifest, SourceFormat } from "../db/kernel-schema.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import type { KernelLogger } from "../log.js";
+import { type SkillPackageFile } from "../skills/package.js";
+import { type PrefixedStorage, StorageService } from "../storage/storage.service.js";
+import { CatalogItemLock } from "./locks.js";
+/** A skill or agent template version a sync wrote (`from` null: the component was created). */
+export interface ChangedRef {
+    kind: "skill" | "agent_template";
+    id: string;
+    name: string;
+    from: number | null;
+    to: number;
+}
+/**
+ * A connector template a sync wrote. Connector templates carry the catalog version that last
+ * changed them (`platform_connector_templates.current_version` is text), so `from` / `to` are
+ * catalog versions; `name` is the template id (the file's base name).
+ */
+export interface ChangedConnectorTemplateRef {
+    kind: "connector_template";
+    id: string;
+    name: string;
+    from: string | null;
+    to: string;
+}
+/** What {@link PlatformComponents.syncFromVersion} changed (unchanged components are not listed). */
+export interface PlatformSyncResult {
+    skills: ChangedRef[];
+    agentTemplates: ChangedRef[];
+    connectorTemplates: ChangedConnectorTemplateRef[];
+}
+/** The prefix (in `deployment/`) of a platform skill version's files. */
+export declare const platformSkillPrefix: (id: string, version: number) => string;
+/** The prefix (in `deployment/`) of a platform agent template version's file. */
+export declare const platformAgentTemplatePrefix: (id: string, version: number) => string;
+/**
+ * A fresh prefix (in `deployment/`) for a version written before its transaction (ruling P3-45):
+ * `<id>/<version>-<uuid>/`, so two writers racing for one version number never overwrite each
+ * other's objects, and the loser's are deleted after its transaction failed.
+ */
+export declare const uniqueVersionPrefix: (base: string) => string;
+/**
+ * The prefix of a version a plugin sync writes: `<id>/<version>-<catalog version>/` (the catalog
+ * version made key-safe), so syncs of two catalog versions racing for one number never overwrite
+ * each other. Stored on the version row; readers use the stored prefix, so rows written before keep
+ * theirs.
+ */
+export declare const syncVersionPrefix: (base: string, catalogVersion: string) => string;
+/** The live component a plan was made against (absent: the plan creates it). */
+interface Base<V> {
+    id: string;
+    version: V;
+}
+interface SkillStep {
+    name: string;
+    base: Base<number> | undefined;
+    id: string;
+    to: number;
+    prefix: string;
+    files: SkillPackageFile[];
+    manifest: SkillManifest;
+    suggestPinned: boolean;
+}
+interface TemplateStep {
+    name: string;
+    base: Base<number> | undefined;
+    id: string;
+    to: number;
+    prefix: string;
+    file: SkillPackageFile;
+    template: AgentTemplate;
+}
+interface ConnectorTemplateStep {
+    name: string;
+    base: Base<string> | undefined;
+    id: string;
+    file: ConnectorTemplateFile;
+}
+/** A planned sync (see {@link PreparedSync}). */
+export interface SyncPlan {
+    itemId: string;
+    plugin: string;
+    version: string;
+    sourceFormat: SourceFormat;
+    skills: SkillStep[];
+    agentTemplates: TemplateStep[];
+    connectorTemplates: ConnectorTemplateStep[];
+}
+/** A component changed between the plan and its write (a concurrent sync): plan again. */
+export declare class PlanStale extends Error {
+}
+/**
+ * A sync planned and its files copied ({@link PlatformComponents.prepareSync}), waiting for its rows
+ * ({@link PlatformComponents.applySyncIn}). Opaque outside this module.
+ */
+export interface PreparedSync {
+    readonly plan: SyncPlan;
+}
+/** A component version written by an upload ({@link PlatformComponents.uploadSkillVersion}). */
+export interface UploadedComponentVersion {
+    kind: "skill" | "agent_template";
+    id: string;
+    name: string;
+    /** The version written (`current_version` after the upload). */
+    version: number;
+}
+/**
+ * The owner's next version of a skill it promoted (ruling P3-4), its files written
+ * ({@link PlatformComponents.prepareOwnerVersion}), waiting for its row
+ * ({@link PlatformComponents.addOwnerVersionIn}).
+ */
+export interface OwnerVersion {
+    readonly platformId: string;
+    /** The version it becomes (the platform row's current version + 1 when prepared). */
+    readonly to: number;
+    readonly prefix: string;
+}
+/** Who uploads (the super admin; `actorTokenId` when through a personal access token). */
+export interface UploadActor {
+    accountId: string;
+    actorTokenId?: string;
+    /** Added to the audit detail (the Platform tool's `via`). */
+    auditDetail?: Record<string, unknown>;
+}
+/**
+ * Writes the platform rows of a catalog version's components. Called by the import confirm that
+ * creates a catalog item (`initial`), and by the platform plugin update for a new version.
+ */
+export declare class PlatformComponents {
+    private readonly kdb;
+    private readonly itemLock;
+    private readonly log;
+    readonly txHost: TransactionHost;
+    /** Where the files are read and written (the kernel's object storage; the CLI's own). */
+    private files;
+    constructor(kdb: KernelDb, storage: StorageService, itemLock: CatalogItemLock, log: KernelLogger, txHost: TransactionHost);
+    private get db();
+    /** CLI only (see `PluginImport.useCliStorage`): files go to the object store the CLI set up. */
+    useCliStorage(storage: PrefixedStorage): void;
+    /**
+     * Creates or updates the platform rows of every component of catalog version `version` of item
+     * `itemId`: a component is matched by plugin and name (connector templates by item and template
+     * id) and gets a new version only when its content changed (skills by their files' digest,
+     * templates by canonical JSON); new rows follow the plugin's scope (`scope_mode: follow`).
+     * Files are copied from the catalog prefix to `deployment/platform/…` before the rows are
+     * written (outside the transaction), so a sync that stops midway leaves at most unreferenced
+     * files, and running it again is a no-op once it succeeded. `initial` is the confirm that
+     * created the item. Components missing from the version are left alone (the platform update
+     * decides what a removal means). On success the item records `version` as
+     * `platform_synced_version`.
+     */
+    syncFromVersion(itemId: string, version: string, opts: {
+        initial: boolean;
+    }): Promise<PlatformSyncResult>;
+    /**
+     * The first phase of a sync inside a caller's transaction (the platform plugin update): plans the
+     * version's components and copies their files, outside any transaction (no storage call holds a
+     * row lock). {@link applySyncIn} writes the rows.
+     */
+    prepareSync(itemId: string, version: string): Promise<PreparedSync>;
+    /**
+     * The second phase: writes the prepared rows in the caller's transaction and records
+     * `platform_synced_version`. A component changed since the plan -> {@link PlanStale} (the caller
+     * prepares again).
+     */
+    applySyncIn(p: PreparedSync): Promise<PlatformSyncResult>;
+    /**
+     * A platform skill updated on its own (spec §7.2): the super admin uploads a skill package (zip)
+     * for component `id`. The package keeps the component's name (else 400 `validation_failed`);
+     * the new version keeps the component's plugin provenance and format, is flagged `updated_on_own`
+     * (the next plugin update preview marks it) and serves in orgs at once (resolution is
+     * read-time). Files go to the platform prefix before the transaction; a concurrent change of the
+     * component -> 409 `component.version_stale`. Audits `component.version_uploaded`.
+     */
+    uploadSkillVersion(actor: UploadActor, id: string, zip: Uint8Array): Promise<UploadedComponentVersion>;
+    /**
+     * A platform agent template updated on its own (spec §7.2), as {@link uploadSkillVersion}: the
+     * template file (markdown) keeps the component's name.
+     */
+    uploadAgentTemplateVersion(actor: UploadActor, id: string, text: string): Promise<UploadedComponentVersion>;
+    /**
+     * The first phase of the owner's new version of platform skill `platformId` (ruling P3-4: an org
+     * that promoted its skill writes later versions to the platform row, never a pin on its copy):
+     * the files go to a fresh `deployment/platform/skills/<id>/<current + 1>-<uuid>/` (ruling
+     * P3-45), outside any transaction; a caller whose transaction then fails calls
+     * {@link discardPrefix}. Missing -> 404 `component.not_found`.
+     */
+    prepareOwnerVersion(platformId: string, files: SkillPackageFile[]): Promise<OwnerVersion>;
+    /**
+     * The second phase, in the caller's transaction (the owner org's skill upload, under the org row
+     * and the copy's row lock): the platform row becomes version `v.to` with `manifest`, keeping its
+     * format. A version written since the first phase -> 409 `component.version_stale`. Returns
+     * the version written. The caller tells the orgs using it (`notifySharedUpdate`).
+     */
+    addOwnerVersionIn(v: OwnerVersion, manifest: SkillManifest, actorAccountId: string | null): Promise<number>;
+    /**
+     * Deletes the objects a version wrote before its transaction failed (ruling P3-45), best effort:
+     * nothing references them; a failure is logged.
+     */
+    discardPrefix(prefix: string): Promise<void>;
+    private liveSkill;
+    private liveTemplate;
+    private writeSkillVersionIn;
+    private writeTemplateVersionIn;
+    /**
+     * Records that the item's platform components are written from `version`
+     * (`catalog_items.platform_synced_version`): the migration job syncs only items without it.
+     */
+    private markSynced;
+    /** Reads the version's components and the live platform rows; keeps only what changed. */
+    private plan;
+    /** Copies the planned versions' files to their platform prefixes. */
+    private writeFiles;
+    /**
+     * Writes the planned rows under the item name's lock (the lock of the import confirm), after
+     * checking that every component is still where the plan found it ({@link PlanStale} otherwise).
+     */
+    private apply;
+}
+export {};