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

package/dist/catalog/org-plugin-uploads.controller.js

@@ -0,0 +1,213 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Controller, Delete, Get, HttpCode, Inject, Post, Put, Req } from "@nestjs/common";
+import { z } from "zod";
+import { ApiError } from "../errors.js";
+import { CurrentPrincipal, patTokenId, requireUser, } from "../identity/principal.js";
+import { createZodDto } from "../infra/validation/create-zod-dto.js";
+import { ZBody, ZParam } from "../infra/validation/zod-params.js";
+import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
+import { CatalogScopeService } from "./catalog-scope.service.js";
+import { OrgPluginUploads, } from "./org-plugin-uploads.js";
+import { OwnedItems } from "./owned-items.js";
+const StagingParams = z.object({ stagingId: z.string().min(1).max(100) });
+const OwnedParams = z.object({ id: z.string().min(1).max(100) });
+const ConfirmBody = z
+    .object({
+    reviewHash: z.string().min(1).max(128),
+    /** The org shares the new item with other orgs (default false, P3-16). */
+    shareable: z.boolean().optional(),
+    /** Skill names suggested as pinned (spec §9.1); omitted keeps the plugin's flags. */
+    pinnedSuggestions: z.array(z.string().min(1).max(64)).max(50).optional(),
+})
+    .strict();
+class OrgUploadStagingParams extends createZodDto(StagingParams, "OrgUploadStagingParams") {
+}
+class OrgUploadConfirmBody extends createZodDto(ConfirmBody, "OrgUploadConfirmBody") {
+}
+class OrgOwnedPluginParams extends createZodDto(OwnedParams, "OrgOwnedPluginParams") {
+}
+const ShareableBody = z.object({ shareable: z.boolean() }).strict();
+const DeleteBody = z.object({ previewHash: z.string().min(1).max(128) }).strict();
+class OrgOwnedShareableBody extends createZodDto(ShareableBody, "OrgOwnedShareableBody") {
+}
+class OrgOwnedDeleteBody extends createZodDto(DeleteBody, "OrgOwnedDeleteBody") {
+}
+const actorOpts = (actor) => {
+    const tokenId = patTokenId(actor);
+    return tokenId !== undefined ? { actorTokenId: tokenId } : {};
+};
+/**
+ * An org admin's plugin uploads (`/api/v1/orgs/:orgId/catalog/uploads/*`, spec §14, rulings P3-7,
+ * P3-8): a `.tgz` without an extension, prepared (one review) and confirmed like the super admin's
+ * import, owned by the org. Writes re-check the org admin under the org row lock.
+ */
+let OrgPluginUploadsController = class OrgPluginUploadsController {
+    uploads;
+    constructor(uploads) {
+        this.uploads = uploads;
+    }
+    /**
+     * Prepares an upload (the tgz as the raw body, `application/octet-stream`, at most
+     * `packages.maxBytes`): `{ stagingId, review, update }`, the staging kept 24 hours for this org.
+     * The checks of the platform import, plus: `customSkills` = deny with skills or agent templates,
+     * or `customConnectors` = deny with connector templates -> 403 `catalog.custom_disabled`
+     * (ruling P3-15'); a name live for another owner -> 409 `plugin.name_taken` (details
+     * `[{ owner }]`); a dependency the org cannot use -> 409 `plugin.dependency_unavailable`
+     * (details `[{ dependencies }]`).
+     */
+    async upload(principal, org, req) {
+        const actor = requireUser(principal);
+        const body = req.body;
+        if (!Buffer.isBuffer(body) || body.byteLength === 0) {
+            throw new ApiError("unsupported_media_type", "Send the plugin package (.tgz) as the request body with content-type application/octet-stream");
+        }
+        return this.uploads.prepare(actor.account.id, org.orgId, new Uint8Array(body.buffer, body.byteOffset, body.byteLength), actorOpts(actor));
+    }
+    /** The org's staged upload; unknown, expired, confirmed, another org's or the platform's -> 404. */
+    staged(org, params) {
+        return this.uploads.staged(org.orgId, params.stagingId);
+    }
+    /**
+     * Confirms the org's staged upload (201 `{ item, outcome }`): a new item owned by the org, scope
+     * `named: [org]`, not shown to other orgs, `shareable` as sent (default false), installed in the
+     * org by the scope sync (`installed`); a new version of its own item (`updated`). The checks of
+     * prepare run again under the item name's lock (the first confirm of a name wins). A package
+     * with an extension waits for the super admin (`pending`, ruling P3-10): stored, its extension
+     * name claimed (another package's -> 409 `extension.name_conflict` naming the owner), nothing
+     * installed or usable until confirmed in 待确认; a later upload replaces the pending version
+     * (P3-11). A version without an extension for an item whose first version still waits replaces
+     * that upload and is installed at once (`installed`).
+     */
+    confirm(principal, org, params, body) {
+        const actor = requireUser(principal);
+        return this.uploads.confirm(actor.account.id, org.orgId, params.stagingId, {
+            reviewHash: body.reviewHash,
+            ...(body.shareable !== undefined && { shareable: body.shareable }),
+            ...(body.pinnedSuggestions !== undefined && { pinnedSuggestions: body.pinnedSuggestions }),
+        }, actorOpts(actor));
+    }
+};
+__decorate([
+    Post("file"),
+    HttpCode(200),
+    OrgAction("catalog.upload"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Req())
+], OrgPluginUploadsController.prototype, "upload", null);
+__decorate([
+    Get(":stagingId"),
+    OrgAction("catalog.upload"),
+    __param(0, CurrentOrg()),
+    __param(1, ZParam(OrgUploadStagingParams))
+], OrgPluginUploadsController.prototype, "staged", null);
+__decorate([
+    Post(":stagingId/confirm"),
+    HttpCode(201),
+    OrgAction("catalog.upload"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(OrgUploadStagingParams)),
+    __param(3, ZBody(OrgUploadConfirmBody))
+], OrgPluginUploadsController.prototype, "confirm", null);
+OrgPluginUploadsController = __decorate([
+    Controller("api/v1/orgs/:orgId/catalog/uploads"),
+    __param(0, Inject(OrgPluginUploads))
+], OrgPluginUploadsController);
+export { OrgPluginUploadsController };
+/**
+ * The org's own plugins (`/api/v1/orgs/:orgId/owned-plugins/*`, spec §14, P3-17 to P3-19): the
+ * owner org's admin withdraws a pending upload, toggles 可共享 and deletes the plugin after a
+ * preview. Another org's or a platform plugin -> 404. Writes re-check the org admin under the org
+ * row lock.
+ */
+let OrgOwnedPluginsController = class OrgOwnedPluginsController {
+    scope;
+    owned;
+    constructor(scope, owned) {
+        this.scope = scope;
+        this.owned = owned;
+    }
+    /**
+     * Sets 可共享 (ruling P3-2: the plugin and its component rows in one transaction; turning it
+     * off keeps the orgs already associated and hides it from new ones, ruling P3-25). 204.
+     */
+    async setShareable(principal, org, params, body) {
+        const actor = requireUser(principal);
+        await this.owned.setShareable(org.orgId, actor.account.id, { kind: "plugin", id: params.id }, body.shareable, actorOpts(actor));
+    }
+    /**
+     * What deleting the plugin does (P3-19, nothing written): `outcome` `removed` (no other org
+     * uses it) or `transferred` (to the platform), `orgs` the other orgs using it, `agents` the
+     * org's agents that lose it, and the `previewHash` to confirm.
+     */
+    previewDelete(org, params) {
+        return this.owned.previewDelete(org.orgId, params.id);
+    }
+    /**
+     * Deletes the plugin after its preview: removed, or transferred to the platform when another
+     * org uses it (platform notice `ownership_transferred`). A preview that changed meanwhile ->
+     * 409 `catalog.preview_stale`. 204.
+     */
+    async delete(principal, org, params, body) {
+        const actor = requireUser(principal);
+        await this.owned.delete(org.orgId, actor.account.id, params.id, body.previewHash, actorOpts(actor));
+    }
+    /**
+     * Withdraws the org's pending upload of the plugin (ruling P3-10, no notice): a first version
+     * is removed (its name free again), a new version's pending state cleared (the platform version
+     * keeps running). Another org's or a platform plugin -> 404; nothing pending -> 409
+     * `extension.not_pending`. 204.
+     */
+    async withdraw(principal, org, params) {
+        const actor = requireUser(principal);
+        await this.scope.withdraw(org.orgId, actor.account.id, params.id, actorOpts(actor));
+    }
+};
+__decorate([
+    Put(":id/shareable"),
+    HttpCode(204),
+    OrgAction("catalog.upload"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(OrgOwnedPluginParams)),
+    __param(3, ZBody(OrgOwnedShareableBody))
+], OrgOwnedPluginsController.prototype, "setShareable", null);
+__decorate([
+    Post(":id/delete/preview"),
+    HttpCode(200),
+    OrgAction("catalog.upload"),
+    __param(0, CurrentOrg()),
+    __param(1, ZParam(OrgOwnedPluginParams))
+], OrgOwnedPluginsController.prototype, "previewDelete", null);
+__decorate([
+    Post(":id/delete"),
+    HttpCode(204),
+    OrgAction("catalog.upload"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(OrgOwnedPluginParams)),
+    __param(3, ZBody(OrgOwnedDeleteBody))
+], OrgOwnedPluginsController.prototype, "delete", null);
+__decorate([
+    Delete(":id/pending"),
+    HttpCode(204),
+    OrgAction("catalog.upload"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(OrgOwnedPluginParams))
+], OrgOwnedPluginsController.prototype, "withdraw", null);
+OrgOwnedPluginsController = __decorate([
+    Controller("api/v1/orgs/:orgId/owned-plugins"),
+    __param(0, Inject(CatalogScopeService)),
+    __param(1, Inject(OwnedItems))
+], OrgOwnedPluginsController);
+export { OrgOwnedPluginsController };

package/dist/catalog/org-plugin-uploads.d.ts

@@ -0,0 +1,63 @@
+import type { ActorOpts, CatalogItemView } from "./catalog.service.js";
+import { CatalogScopeService } from "./catalog-scope.service.js";
+import { PluginImport, type PluginReview } from "./plugin-import.js";
+import { PlatformPluginUpdater, type PlatformUpdatePreview } from "./plugin-upgrade.js";
+/** A staged org upload: the review, and the update preview of a new version (null: none). */
+export interface OrgUploadReview {
+    stagingId: string;
+    /**
+     * The review. For a new version of the org's own plugin its `reviewHash` covers the update
+     * preview too (one hash, ruling P3-12): confirm with it.
+     */
+    review: PluginReview;
+    /**
+     * The platform update a new version of the org's own plugin without an extension applies at
+     * once (ruling P3-12); null for a first upload and for a version with an extension (it waits for
+     * the super admin, plan Task 6).
+     */
+    update: PlatformUpdatePreview | null;
+}
+/**
+ * What a confirmed org upload did: `installed` (a new item, installed in the owner org by the scope
+ * sync), `pending` (waiting for the super admin: an extension, plan Task 6), `updated` (a new
+ * version of the org's own item, applied through the platform updater).
+ */
+export type OrgUploadOutcome = "installed" | "pending" | "updated";
+/** The hash an org confirms a new version with: the review's and the update's (P3-12). */
+export declare function ownerUpdateHash(reviewHash: string, diffHash: string): string;
+/**
+ * An org admin's plugin upload (spec §14.1 item 1, rulings P3-7, P3-8, P3-12, P3-13 to P3-15'): a
+ * `.tgz` prepared and confirmed through {@link PluginImport} in owner mode (the org's own staging,
+ * its admin re-checked under the org row lock), owned by the org with scope `named: [owner]`. After
+ * the confirm's commit the item's scope sync is enqueued here (as `CatalogScopeService.confirmImport`
+ * does; `PluginImport` cannot reach the scope service, which depends on it), and installs it in the
+ * owner org.
+ *
+ * A new version of the org's own plugin without an extension (P3-12, P3-12') is reviewed with the
+ * platform update it applies (`PlatformPluginUpdater.previewForOwner` on the staged target,
+ * pre-flight F3) and one hash ({@link ownerUpdateHash}); the confirm checks it, commits the version,
+ * then runs `updateAsOwner` with that diff. A failed update leaves the version imported; the same
+ * tgz uploaded again gets an update-only review (F4) whose confirm retries the update. Pinned
+ * suggestions are the plugin's own on a new version (they would change the reviewed update).
+ */
+export declare class OrgPluginUploads {
+    private readonly pluginImport;
+    private readonly scope;
+    private readonly updater;
+    constructor(pluginImport: PluginImport, scope: CatalogScopeService, updater: PlatformPluginUpdater);
+    /** Reads, checks and stages the uploaded tgz for the org (see `PluginImport.prepare`). */
+    prepare(actor: string, orgId: string, bytes: Uint8Array, opts?: ActorOpts): Promise<OrgUploadReview>;
+    /** The org's own staged upload; another org's or the platform's -> 404 `plugin.staging_not_found`. */
+    staged(orgId: string, stagingId: string): Promise<OrgUploadReview>;
+    /** Confirms the org's staged upload (applying a new version), then enqueues the scope sync. */
+    confirm(actor: string, orgId: string, stagingId: string, input: {
+        reviewHash: string;
+        shareable?: boolean;
+        pinnedSuggestions?: string[];
+    }, opts?: ActorOpts): Promise<{
+        item: CatalogItemView;
+        outcome: OrgUploadOutcome;
+    }>;
+    /** The review with the update preview of a new version and the combined hash (P3-12). */
+    private withUpdate;
+}

package/dist/catalog/org-plugin-uploads.js

@@ -0,0 +1,116 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { createHash } from "node:crypto";
+import { Inject, Injectable } from "@nestjs/common";
+import { ApiError } from "../errors.js";
+import { canonicalJson } from "../tools/canonical-json.js";
+import { CatalogScopeService } from "./catalog-scope.service.js";
+import { PluginImport } from "./plugin-import.js";
+import { PlatformPluginUpdater } from "./plugin-upgrade.js";
+/** The hash an org confirms a new version with: the review's and the update's (P3-12). */
+export function ownerUpdateHash(reviewHash, diffHash) {
+    return createHash("sha256")
+        .update(canonicalJson({ reviewHash, diffHash }))
+        .digest("hex")
+        .slice(0, 32);
+}
+const reviewStale = (name, version) => new ApiError("plugin.review_stale", `The review of plugin ${name} ${version} is out of date (it changed, or its extension on this deployment changed since it was prepared); review it again`);
+/**
+ * An org admin's plugin upload (spec §14.1 item 1, rulings P3-7, P3-8, P3-12, P3-13 to P3-15'): a
+ * `.tgz` prepared and confirmed through {@link PluginImport} in owner mode (the org's own staging,
+ * its admin re-checked under the org row lock), owned by the org with scope `named: [owner]`. After
+ * the confirm's commit the item's scope sync is enqueued here (as `CatalogScopeService.confirmImport`
+ * does; `PluginImport` cannot reach the scope service, which depends on it), and installs it in the
+ * owner org.
+ *
+ * A new version of the org's own plugin without an extension (P3-12, P3-12') is reviewed with the
+ * platform update it applies (`PlatformPluginUpdater.previewForOwner` on the staged target,
+ * pre-flight F3) and one hash ({@link ownerUpdateHash}); the confirm checks it, commits the version,
+ * then runs `updateAsOwner` with that diff. A failed update leaves the version imported; the same
+ * tgz uploaded again gets an update-only review (F4) whose confirm retries the update. Pinned
+ * suggestions are the plugin's own on a new version (they would change the reviewed update).
+ */
+let OrgPluginUploads = class OrgPluginUploads {
+    pluginImport;
+    scope;
+    updater;
+    constructor(pluginImport, scope, updater) {
+        this.pluginImport = pluginImport;
+        this.scope = scope;
+        this.updater = updater;
+    }
+    /** Reads, checks and stages the uploaded tgz for the org (see `PluginImport.prepare`). */
+    async prepare(actor, orgId, bytes, opts = {}) {
+        const r = await this.pluginImport.prepare(actor, bytes, { kind: "file", ref: "upload" }, { ...opts, owner: { orgId } });
+        return this.withUpdate(orgId, r.stagingId, r.review);
+    }
+    /** The org's own staged upload; another org's or the platform's -> 404 `plugin.staging_not_found`. */
+    async staged(orgId, stagingId) {
+        const r = await this.pluginImport.staged(stagingId, { orgId });
+        return this.withUpdate(orgId, r.stagingId, r.review);
+    }
+    /** Confirms the org's staged upload (applying a new version), then enqueues the scope sync. */
+    async confirm(actor, orgId, stagingId, input, opts = {}) {
+        const st = await this.pluginImport.stagedTarget(stagingId, { orgId });
+        if (!appliesAtOnce(st)) {
+            const r = await this.pluginImport.confirm(actor, stagingId, input, {
+                ...opts,
+                owner: { orgId },
+            });
+            // A version waiting for the super admin is synced by their confirmation (P3-10)
+            if (r.pending)
+                return { item: r.item, outcome: "pending" };
+            await this.scope.enqueueSync(r.item.id);
+            return { item: r.item, outcome: r.firstVersion ? "installed" : "updated" };
+        }
+        if (input.pinnedSuggestions !== undefined) {
+            throw new ApiError("validation_failed", "pinnedSuggestions: a new version keeps the plugin's own pinned suggestions", [{ path: "pinnedSuggestions", message: "not allowed for a new version" }]);
+        }
+        // The one hash covers the review and the update (P3-12): both recomputed now
+        const preview = await this.updater.previewForOwner(orgId, st.itemId, st.version, st.target);
+        if (input.reviewHash !== ownerUpdateHash(st.reviewHash, preview.diffHash)) {
+            throw reviewStale(preview.name, st.version);
+        }
+        const r = await this.pluginImport.confirm(actor, stagingId, {
+            reviewHash: st.reviewHash,
+            ...(input.shareable !== undefined && { shareable: input.shareable }),
+        }, { ...opts, owner: { orgId } });
+        // The version is committed; a failed update leaves it imported (uploading it again retries)
+        await this.updater.updateAsOwner(orgId, actor, r.item.id, st.version, preview.diffHash, opts);
+        return { item: await this.pluginImport.view(r.item.id), outcome: "updated" };
+    }
+    /** The review with the update preview of a new version and the combined hash (P3-12). */
+    async withUpdate(orgId, stagingId, review) {
+        const st = await this.pluginImport.stagedTarget(stagingId, { orgId });
+        if (!appliesAtOnce(st))
+            return { stagingId, review, update: null };
+        const update = await this.updater.previewForOwner(orgId, st.itemId, st.version, st.target);
+        return {
+            stagingId,
+            review: { ...review, reviewHash: ownerUpdateHash(review.reviewHash, update.diffHash) },
+            update,
+        };
+    }
+};
+OrgPluginUploads = __decorate([
+    Injectable(),
+    __param(0, Inject(PluginImport)),
+    __param(1, Inject(CatalogScopeService)),
+    __param(2, Inject(PlatformPluginUpdater))
+], OrgPluginUploads);
+export { OrgPluginUploads };
+/**
+ * A new version of the org's own plugin without an extension: applied at once through the
+ * platform updater (P3-12). Not while the item's first version still waits for the super admin:
+ * such an upload replaces that first version instead (`PluginImport.commit`, plan Task 6).
+ */
+function appliesAtOnce(st) {
+    return st.existing && !st.extension && !st.awaiting;
+}

package/dist/catalog/owned-items.d.ts

@@ -0,0 +1,184 @@
+import type { Queue } from "bullmq";
+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 { SkillsService } from "../skills/skills.service.js";
+import { type ActorOpts, CatalogService } from "./catalog.service.js";
+import { CatalogScopeService } from "./catalog-scope.service.js";
+import { type OwnedRef } from "./ownership.js";
+import { PluginInstaller } from "./plugin-install.js";
+/**
+ * What deleting an owned plugin does (P3-19): `removed` when no other org uses it, else
+ * `transferred` to the platform; `orgs` the other orgs using it (their names were disclosed by
+ * `item_shared` notices already), `agents` the owner's agents that lose it. Confirmed with
+ * `previewHash`.
+ */
+export interface OwnedDeletePreview {
+    outcome: "removed" | "transferred";
+    orgs: {
+        id: string;
+        name: string;
+    }[];
+    agents: {
+        id: string;
+        name: string;
+    }[];
+    previewHash: string;
+}
+/** Why an owned item leaves its owner (the `ownership_transferred` notice's `reason`). */
+export type OwnerLeaveReason = "owner_deleted" | "org_deleted";
+/** What deleting an org skill does (`GET orgs/:orgId/skills/:id/delete-preview`, pre-flight F19). */
+export type OwnedSkillDeletePreview = Omit<OwnedDeletePreview, "previewHash">;
+/**
+ * The owner org's actions on the items it owns (P3-17: it toggles 可共享, switches the item off in
+ * its own org and deletes it; it never changes the scope or the list). The org admin is re-checked
+ * under the org row lock; another org's or a platform item -> 404. Stateless, shared by every
+ * replica.
+ */
+export declare class OwnedItems {
+    private readonly kdb;
+    private readonly orgLock;
+    private readonly catalog;
+    private readonly scope;
+    /** The owner org's own uninstall of a removed plugin (ruling P3-41). */
+    private readonly installer;
+    /** The owner's org skill row, soft-deleted after its promoted platform row leaves it. */
+    private readonly skills;
+    /** The removed plugin's cleanup job (`owned-plugin-cleanup-<itemId>`, P3-20). */
+    private readonly queue;
+    private readonly log;
+    readonly txHost: TransactionHost;
+    constructor(kdb: KernelDb, orgLock: OrgLock, catalog: CatalogService, scope: CatalogScopeService, 
+    /** The owner org's own uninstall of a removed plugin (ruling P3-41). */
+    installer: PluginInstaller, 
+    /** The owner's org skill row, soft-deleted after its promoted platform row leaves it. */
+    skills: SkillsService, 
+    /** The removed plugin's cleanup job (`owned-plugin-cleanup-<itemId>`, P3-20). */
+    queue: Pick<Queue, "add">, log: KernelLogger, txHost: TransactionHost);
+    private get db();
+    /**
+     * The owner org's 可共享 flag of its item, written on the item and (a plugin) every component
+     * row in one transaction (ruling P3-2; turning it off narrows as ruling P3-25 says). A skill or
+     * an agent template is named by the org row's id (`skills.manage` / `agents.manage`): only the
+     * org's own rows (ruling P3-6: not an agent's skill, not a copy of another owner's platform item:
+     * 409 `catalog.not_owned`); one it promoted writes its platform row too (pre-flight F16). Audits
+     * `catalog.shareable_changed`.
+     */
+    setShareable(orgId: string, actor: string, ref: OwnedRef, shareable: boolean, opts?: ActorOpts): Promise<void>;
+    /** {@link setShareable} of an org skill or agent template (named by the org row's id). */
+    private setComponentShareable;
+    /** The other live orgs the item is on in (P3-18, {@link orgsUsing}), by name. */
+    usedByOthers(ref: OwnedRef): Promise<{
+        id: string;
+        name: string;
+    }[]>;
+    /**
+     * What deleting the org's skill `skillId` does (pre-flight F19, P3-19): one it promoted that
+     * another org uses is `transferred` (`orgs`: those orgs), else `removed`; `agents`: the org's
+     * agents that lose it (by its id, or its platform id). Not an org-scope skill of the org -> 404
+     * `skill.not_found`.
+     */
+    previewSkillDelete(orgId: string, skillId: string): Promise<OwnedSkillDeletePreview>;
+    /**
+     * The owner deletes its org skill (`DELETE orgs/:orgId/skills/:id`, `skills.manage` re-checked
+     * under the org row lock): one it promoted goes through {@link transferOrRemove} with reason
+     * `owner_deleted` (another org using it keeps it, now the platform's), then the org row is
+     * soft-deleted as before (audit `skill.deleted`). Not an org-scope skill of the org -> 404.
+     */
+    deleteSkill(orgId: string, actor: string, skillId: string, opts?: ActorOpts): Promise<"transferred" | "removed">;
+    /**
+     * What deleting the org's own agent template `id` does (ruling P4-12, as
+     * {@link previewSkillDelete}): one it promoted that another org uses is `transferred` (`orgs`:
+     * those orgs), else `removed`; `agents`: the org's agents whose roster loses it. Not the org's
+     * own -> 409 `catalog.not_owned`; missing -> 404 `component.not_found`.
+     */
+    previewAgentTemplateDelete(orgId: string, id: string): Promise<OwnedSkillDeletePreview>;
+    /**
+     * The owner deletes its org template (`DELETE orgs/:orgId/agent-templates/:id`, ruling P4-12;
+     * `agents.manage` re-checked under the org row lock), by the P3 owner rules: one it promoted
+     * goes through {@link transferOrRemove} with reason `owner_deleted` (another org using it keeps
+     * it, now the platform's, ruling P3-19), then the org row is soft-deleted (sub-agents already
+     * started keep their frozen definition; the roster skips it). Agents created from it are never
+     * touched (ruling P4-3). Audits `agent_template.deleted`. Not the org's own -> 409
+     * `catalog.not_owned`; missing -> 404.
+     */
+    deleteAgentTemplate(orgId: string, actor: string, id: string, opts?: ActorOpts): Promise<"transferred" | "removed">;
+    /**
+     * The org-scope skill `skillId` of the org (`forUpdate`: row locked), with the platform row it
+     * promoted (`link`; a copy of another owner's platform skill has none here). Missing -> 404.
+     */
+    private orgSkill;
+    /**
+     * The org's own skill or agent template `id` (ruling P3-6), locked with `forUpdate`: missing
+     * (or another org's) -> 404; an agent's own skill, or a copy linked to a platform item another
+     * owner has (or pinned to one) -> 409 `catalog.not_owned`. `link`: the platform row it promoted.
+     */
+    private ownedComponent;
+    /** The preview of deleting the org's own plugin (nothing written). */
+    previewDelete(orgId: string, itemId: string): Promise<OwnedDeletePreview>;
+    /**
+     * Deletes the org's own plugin after its preview (P3-19): the preview recomputed under the item
+     * row lock must give `previewHash` (else 409 `catalog.preview_stale`), then
+     * {@link transferOrRemove} with reason `owner_deleted`.
+     */
+    delete(orgId: string, actor: string, itemId: string, previewHash: string, opts?: ActorOpts): Promise<"transferred" | "removed">;
+    /**
+     * The owner leaves its item, in the caller's transaction (P3-19, P3-20; pre-flight F14, F15).
+     * Another live org uses it ({@link orgsUsing}) -> `transferred`: the item and its components
+     * become platform-owned, a pending version is cleared, `shown_to_others` is turned off when the
+     * owner had not made it shareable (no exposure the owner switched off), the former owner leaves
+     * the list and its switches (an `all` scope, the item's or a component's own, is narrowed to
+     * `named` = the orgs using it, ruling P3-39; an `optional` item stays `optional`, ruling P3-40:
+     * it passed the share gate already, so every org could see it, and the former owner is then an
+     * ordinary org that may switch it on again), written
+     * directly rather than through the guarded scope writer (ruling P3-27); platform notice
+     * `ownership_transferred`, audit `catalog.ownership_transferred`, the scope sync enqueued after
+     * the commit (it uninstalls the former owner's install). Otherwise -> `removed`: the soft delete
+     * of `catalog.remove` ({@link CatalogService.removeIn}) and, after the commit, the cleanup job
+     * `owned-plugin-cleanup-<itemId>` that takes its extension out; an owner delete
+     * (`owner_deleted`) also uninstalls it in the owner org through the normal uninstall, keeping the
+     * connectors it created as the org's own (ruling P3-41). A first upload still waiting is never
+     * transferred. A gone or platform item -> 404.
+     */
+    transferOrRemove(ref: OwnedRef, reason: OwnerLeaveReason, actor: string | null, opts?: ActorOpts): Promise<"transferred" | "removed">;
+    /**
+     * An org is deleted (P3-20), in `OrgsService.softDeleteIn`'s transaction (PG writes only; the
+     * org row is already marked deleted, so it counts as no user): the org's live plugins and the
+     * platform skills and agent templates it promoted (ruling P3-3) are locked `FOR UPDATE`, then
+     * each goes through {@link transferOrRemove} with reason `org_deleted`. A first upload still
+     * waiting is removed and its extension name released here (nothing is installed under it,
+     * pre-flight F10); a pending new version of a transferred plugin is cleared; a removed plugin's
+     * extension is taken out by the cleanup job after the commit. The org's unpromoted rows (its own
+     * skills, copies, installs) are left: they go with the org as before. Must not inject
+     * `OrgsService` (it calls this).
+     */
+    onOrgDeleted(orgId: string, actor: string | null, opts?: ActorOpts): Promise<{
+        transferred: number;
+        removed: number;
+    }>;
+    /**
+     * {@link transferOrRemove} of a platform skill or agent template the org promoted (ruling P3-3;
+     * `id` its platform id): another live org uses it -> `transferred`: platform-owned, not shown
+     * when the owner had not made it shareable, an `all` scope narrowed to `named` = the orgs using
+     * it (ruling P3-39), the former owner off its list and switches, platform notice
+     * `ownership_transferred`, audit `catalog.ownership_transferred`. Otherwise `removed`: the
+     * platform row is soft-deleted (audit `component.removed`). The owner's org row is the caller's
+     * (an owner delete soft-deletes it). Gone or platform-owned -> 404.
+     */
+    private transferOrRemoveComponent;
+    /** The live orgs other than `except` where component `c` is on now ({@link componentOn}). */
+    private componentOrgsOn;
+    /**
+     * The owner org's live install of a removed plugin, uninstalled in the caller's transaction
+     * through the normal uninstall (ruling P3-41): `via: "scope"` (the item is gone, so no scope
+     * wants it), which keeps the connectors it created as the org's own. One that another install
+     * still depends on, or one still installing, stays (logged).
+     */
+    private uninstallInOwner;
+    /** Enqueues the removed plugin's cleanup; a failure only warns (the daily sweep repairs it). */
+    enqueueCleanup(itemId: string): Promise<void>;
+    private computeDelete;
+    /** The org's own live plugin (`forUpdate`: row locked); another org's or a platform one -> 404. */
+    private ownedRow;
+}