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

package/dist/catalog/scope-sync.js

@@ -0,0 +1,576 @@
+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 { getQueueToken, OnWorkerEvent, WorkerHost } from "@nestjs/bullmq";
+import { Inject, Injectable } from "@nestjs/common";
+import { ApiError } from "../errors.js";
+import { ExtensionLifecycle } from "../extensions/lifecycle.js";
+import { ExtensionRegistry } from "../extensions/registry.js";
+import { audit } from "../identity/audit.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 { LockService } from "../infra/lock/lock.service.js";
+import { runJob } from "../infra/queue/run-job.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { connectorTemplatesOn, templateIdOfPath } from "./component-state.js";
+import { isUsable } from "./ownership.js";
+import { PluginInstaller } from "./plugin-install.js";
+import { wantedOn } from "./scope.js";
+import { ScopeNoLongerWanted, ScopeStillWanted } from "./scope-state.js";
+/**
+ * The plugin scope sync (plugin and component management spec §5, phase 1): converges every org
+ * to each platform plugin's scope. In phase 1 "on in an org" is the org's plugin install, so for
+ * each (item, org) the sync:
+ * - wanted on (`wantedOn`, or a live install in the org depends on it: rule 9) and no live install
+ *   -> installs it as the kernel itself (actor null, audits `via: "scope"`), unless the install
+ *   needs the org's input (connector templates, or a required org config of its extension not set):
+ *   that is `needs_config`, derived by the org catalog, never attempted here;
+ * - wanted off and a live install -> uninstalls it (`via: "scope"`; the person who changed the
+ *   scope or the switch confirmed the preview); the connectors the install created stay as the
+ *   org's own (spec §5 rule 8); a dependency install it took along that its own scope still wants
+ *   on stays as a standalone install (the installer's rule), the others are synced again.
+ * The decision is made outside the org row lock; the installer re-checks the scope under it for a
+ * `via: "scope"` install or uninstall, so a person's switch committed meanwhile wins.
+ * The sync writes no switch row: those record people's choices, and `wantedOn` honours them for
+ * every scope (an org that switched an `all` item off stays off, also across a scope change away
+ * and back, layering spec §4). Builtin items are left alone (on everywhere through their required
+ * extension). A failed install, uninstall or dependency install is logged, audited
+ * `plugin.scope_sync_failed`, kept as the pair's open failure (`plugin_scope_sync_failures`, the
+ * super admin's inbox, until a later sync of the pair does not fail) and not retried until the next
+ * enqueue. An error outside those steps (a read, the failure write itself) ends the attempt without
+ * touching the pair's row, so an older failure stays open.
+ * Every worker start enqueues every live item once ({@link PluginScopeSync.enqueueAll}), which
+ * also catches a lost enqueue.
+ *
+ * Jobs (queue {@link PLUGIN_SCOPE_QUEUE}): one per item and scope version
+ * (`scope-item-<itemId>-<scope_version>`, every org), one per org (`scope-org-<orgId>`, every item,
+ * enqueued after the org is created). Both are removed when done, so the next enqueue with the same
+ * id is not swallowed. Pairs of one org are serialized across replicas by a Redis lock per org; the
+ * installer's org row lock and its one-live-install rule are the backstop.
+ */
+/** The scope sync queue (no `:` in the name). */
+export const PLUGIN_SCOPE_QUEUE = "cap-kernel-plugin-scope";
+/** The job converging one item in every org. */
+export const SCOPE_ITEM_JOB = "scope-item";
+/** The job converging every item in one org. */
+export const SCOPE_ORG_JOB = "scope-org";
+/** One item job per scope version (no `:`: item ids are UUIDs). */
+export const scopeItemJobId = (itemId, version) => `scope-item-${itemId}-${version}`;
+/** One org job at a time per org. */
+export const scopeOrgJobId = (orgId) => `scope-org-${orgId}`;
+/**
+ * The delayed retry `n` of an item job whose extension this replica had not loaded yet (ruling
+ * P3-38); deterministic, so replicas deferring the same item add it once.
+ */
+export const scopeRetryJobId = (itemId, version, n) => `scope-item-${itemId}-${version}-r${n}`;
+/** How many delayed retries an item job gets while its extension is not loaded here (P3-38). */
+export const SCOPE_LOAD_RETRIES = 6;
+/** The delay of each such retry. */
+export const SCOPE_LOAD_RETRY_DELAY_MS = 5_000;
+/** How long a pair waits for this replica's reconcile before deferring (P3-38). */
+export const SCOPE_RECONCILE_WAIT_MS = 10_000;
+/**
+ * Awaits this replica's extension reconcile for at most `ms` (a slower one carries on in the
+ * background); a failure only warns.
+ */
+export async function reconcileWithin(lifecycle, reason, ms, log) {
+    let timer;
+    try {
+        await Promise.race([
+            lifecycle.reconcile(reason),
+            new Promise((resolve) => {
+                timer = setTimeout(resolve, ms);
+            }),
+        ]);
+    }
+    catch (err) {
+        log.warn("reconciling extensions on this replica failed", { reason, err });
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+/** The item job of a scope version (what {@link PluginScopeSync.enqueueItem} adds). */
+export function scopeItemJob(itemId, version) {
+    return {
+        name: SCOPE_ITEM_JOB,
+        data: { kind: "item", itemId },
+        opts: {
+            jobId: scopeItemJobId(itemId, version),
+            attempts: 1,
+            removeOnComplete: true,
+            removeOnFail: true,
+        },
+    };
+}
+/** How long one org's pairs wait for each other (an install can take a while). */
+const ORG_LOCK_TTL_MS = 60_000;
+const ORG_LOCK_WAIT_MS = 10 * 60_000;
+/** The worker's concurrency. */
+export const PLUGIN_SCOPE_CONCURRENCY = 2;
+const LIVE = ["installing", "installed", "upgrading"];
+let PluginScopeSync = class PluginScopeSync {
+    kdb;
+    queue;
+    installer;
+    registry;
+    lifecycle;
+    locks;
+    log;
+    txHost;
+    constructor(kdb, queue, installer, registry, 
+    /** This replica's reconcile, awaited (bounded) before deferring an install (P3-38). */
+    lifecycle, locks, log, txHost) {
+        this.kdb = kdb;
+        this.queue = queue;
+        this.installer = installer;
+        this.registry = registry;
+        this.lifecycle = lifecycle;
+        this.locks = locks;
+        this.log = log;
+        this.txHost = txHost;
+    }
+    get db() {
+        return this.kdb.db;
+    }
+    /** Enqueues the sync of an item in every org, once per scope version. Call after the commit. */
+    async enqueueItem(itemId) {
+        const row = await this.db
+            .selectFrom("catalog_items")
+            .select("scope_version")
+            .where("id", "=", itemId)
+            .executeTakeFirst();
+        if (!row)
+            return;
+        const job = scopeItemJob(itemId, row.scope_version);
+        await this.queue.add(job.name, job.data, job.opts);
+    }
+    /**
+     * Enqueues the sync of every live, not builtin item (a worker start): retries what failed or was
+     * never enqueued (a lost `afterCommit` enqueue, a migrated scope). The job ids are the items'
+     * scope versions, so replicas starting together add each one once.
+     */
+    async enqueueAll() {
+        const items = await this.db
+            .selectFrom("catalog_items")
+            .select("id")
+            .where("deleted_at", "is", null)
+            .where("builtin", "=", false)
+            .orderBy("id")
+            .execute();
+        for (const i of items)
+            await this.enqueueItem(i.id);
+    }
+    /** Enqueues the sync of every item in an org (a new org). Call after the commit. */
+    async enqueueOrg(orgId) {
+        await this.queue.add(SCOPE_ORG_JOB, { kind: "org", orgId }, { jobId: scopeOrgJobId(orgId), attempts: 1, removeOnComplete: true, removeOnFail: true });
+    }
+    /** One job: every org of an item, or every item of an org; `signal` stops between pairs. */
+    async process(data, signal) {
+        const pairs = data.kind === "item"
+            ? (await this.db
+                .selectFrom("orgs")
+                .select("id")
+                .where("deleted_at", "is", null)
+                .orderBy("id")
+                .execute()).map((o) => [data.itemId, o.id])
+            : (await this.db
+                .selectFrom("catalog_items")
+                .select("id")
+                .where("deleted_at", "is", null)
+                .where("builtin", "=", false)
+                .orderBy("id")
+                .execute()).map((i) => [i.id, data.orgId]);
+        const retry = data.kind === "item" ? (data.retry ?? 0) : 0;
+        const finalTry = data.kind === "item" && retry >= SCOPE_LOAD_RETRIES;
+        const deferred = new Set();
+        for (const [itemId, orgId] of pairs) {
+            if (signal?.aborted)
+                return;
+            try {
+                const r = await this.syncPair(itemId, orgId, signal, { finalTry });
+                if (r === "deferred")
+                    deferred.add(itemId);
+            }
+            catch (err) {
+                this.log.warn("plugin scope sync of a pair failed", { itemId, orgId, err });
+            }
+        }
+        // An extension this replica had not loaded yet: the item again after a delay (P3-38)
+        for (const itemId of deferred) {
+            try {
+                await this.enqueueRetry(itemId, retry + 1);
+            }
+            catch (err) {
+                this.log.warn("enqueueing a delayed plugin scope sync failed", { itemId, err });
+            }
+        }
+    }
+    /** The delayed retry `n` of an item job (deterministic id, P3-38). */
+    async enqueueRetry(itemId, n) {
+        const row = await this.db
+            .selectFrom("catalog_items")
+            .select("scope_version")
+            .where("id", "=", itemId)
+            .executeTakeFirst();
+        if (!row)
+            return;
+        await this.queue.add(SCOPE_ITEM_JOB, { kind: "item", itemId, retry: n }, {
+            jobId: scopeRetryJobId(itemId, row.scope_version, n),
+            delay: SCOPE_LOAD_RETRY_DELAY_MS,
+            attempts: 1,
+            removeOnComplete: true,
+            removeOnFail: true,
+        });
+    }
+    /**
+     * Whether the install of the item's `version` may go ahead on this replica (P3-38): its
+     * extension is loaded here, or it is not enabled on the deployment (the install reports
+     * `catalog.not_deployed` as before). Enabled but not loaded here: this replica's reconcile is
+     * awaited (bounded); still not loaded -> false, unless this is the last try.
+     */
+    async extensionReady(itemId, version, finalTry) {
+        const v = await this.db
+            .selectFrom("catalog_item_versions")
+            .select("manifest")
+            .where("item_id", "=", itemId)
+            .where("version", "=", version)
+            .executeTakeFirst();
+        const m = v?.manifest;
+        if (!m?.extension)
+            return true;
+        const loaded = () => this.registry.manifests().some((x) => x.name === m.name);
+        if (loaded())
+            return true;
+        const install = await this.db
+            .selectFrom("extension_installs")
+            .select("desired_state")
+            .where("name", "=", m.name)
+            .executeTakeFirst();
+        if (install?.desired_state !== "enabled")
+            return true;
+        await reconcileWithin(this.lifecycle, `scope-sync:${m.name}`, SCOPE_RECONCILE_WAIT_MS, this.log);
+        return loaded() || finalTry;
+    }
+    /** Converges one (item, org), under the org's sync lock; `signal` ends the wait for it. */
+    syncPair(itemId, orgId, signal, opts = {}) {
+        return this.locks.run(`plugin-scope-org-${orgId}`, {
+            ttlMs: ORG_LOCK_TTL_MS,
+            waitMs: ORG_LOCK_WAIT_MS,
+            ...(signal !== undefined && { signal }),
+        }, () => this.syncRecorded(itemId, orgId, opts.finalTry === true));
+    }
+    /**
+     * {@link syncLocked} plus the pair's open failure (`plugin_scope_sync_failures`, the super
+     * admin's inbox): an attempt that failed records it, any other attempt clears it. An attempt
+     * that throws (outside the recorded steps) leaves the row as it was.
+     */
+    async syncRecorded(itemId, orgId, finalTry = false) {
+        const attempt = { failed: false, finalTry };
+        const result = await this.syncLocked(itemId, orgId, attempt);
+        // a deferred pair changed nothing: an older failure stays open
+        if (!attempt.failed && result !== "deferred") {
+            await this.db
+                .deleteFrom("plugin_scope_sync_failures")
+                .where("item_id", "=", itemId)
+                .where("org_id", "=", orgId)
+                .execute();
+        }
+        return result;
+    }
+    async syncLocked(itemId, orgId, attempt) {
+        const item = await this.db
+            .selectFrom("catalog_items")
+            .select([
+            "id",
+            "scope",
+            "builtin",
+            "disabled",
+            "deleted_at",
+            "awaiting_confirmation",
+            "latest_version",
+            "platform_synced_version",
+        ])
+            .where("id", "=", itemId)
+            .where("deleted_at", "is", null)
+            .executeTakeFirst();
+        const org = await this.db
+            .selectFrom("orgs")
+            .select("id")
+            .where("id", "=", orgId)
+            .where("deleted_at", "is", null)
+            .executeTakeFirst();
+        if (!item || !org || item.builtin)
+            return "unchanged";
+        const [listed, sw, live] = await Promise.all([
+            this.db
+                .selectFrom("catalog_item_scope_orgs")
+                .select("item_id")
+                .where("item_id", "=", itemId)
+                .where("org_id", "=", orgId)
+                .executeTakeFirst(),
+            this.db
+                .selectFrom("catalog_item_org_switches")
+                .select("enabled")
+                .where("item_id", "=", itemId)
+                .where("org_id", "=", orgId)
+                .executeTakeFirst(),
+            this.db
+                .selectFrom("plugin_installs")
+                .select(["id", "status"])
+                .where("org_id", "=", orgId)
+                .where("item_id", "=", itemId)
+                .where("status", "in", [...LIVE])
+                .executeTakeFirst(),
+        ]);
+        const wanted = wantedOn(item, listed !== undefined, sw?.enabled ?? null) ||
+            (live !== undefined && (await this.dependedOn(orgId, live.id)));
+        if (wanted) {
+            if (live) {
+                // A platform update may have added dependencies: installed here (rule 9, Task 7)
+                if (live.status === "installed") {
+                    try {
+                        await this.installer.addMissingDependencies(orgId, live.id);
+                    }
+                    catch (e) {
+                        await this.failed(orgId, itemId, "dependencies", e, attempt);
+                    }
+                }
+                return "unchanged";
+            }
+            // Never installed while not usable: an org upload still waiting for the super admin
+            // (ruling P3-9) has nothing confirmed to install
+            if (!isUsable(item))
+                return "unchanged";
+            // The platform's version (one per deployment, Task 7); the latest import before the first sync
+            const version = item.platform_synced_version ?? item.latest_version;
+            try {
+                if (!(await this.extensionReady(itemId, version, attempt.finalTry)))
+                    return "deferred";
+                if (await this.needsInput(orgId, itemId, version))
+                    return "needs_config";
+                await this.installer.install(orgId, null, itemId, version, {}, { via: "scope" });
+                return "installed";
+            }
+            catch (e) {
+                // A person switched it off (or the scope changed) after this decision: the installer's
+                // re-check under the org row lock refused it, nothing written
+                if (e instanceof ScopeNoLongerWanted)
+                    return "unchanged";
+                // Another install of this item got there first (a person, or a dependency): converged
+                if (e instanceof ApiError &&
+                    (e.code === "plugin.already_installed" || e.code === "plugin.install_in_progress")) {
+                    return "unchanged";
+                }
+                await this.failed(orgId, itemId, "install", e, attempt);
+                return "unchanged";
+            }
+        }
+        // Wanted off: only a settled install is removed (one still installing or upgrading waits for
+        // the next enqueue)
+        if (live?.status !== "installed")
+            return "unchanged";
+        const deps = await this.createdDependencies(live.id);
+        try {
+            await this.installer.uninstall(orgId, null, live.id, { via: "scope" });
+        }
+        catch (e) {
+            // A person switched it on (or the scope changed, or another install came to depend on it)
+            // after this decision: the installer's re-check under the org row lock refused it
+            if (e instanceof ScopeStillWanted)
+                return "unchanged";
+            await this.failed(orgId, itemId, "uninstall", e, attempt);
+            return "unchanged";
+        }
+        // Dependency installs it took along may be wanted on by their own scope: synced again
+        for (const dep of deps) {
+            if (dep !== itemId)
+                await this.syncRecorded(dep, orgId);
+        }
+        return "removed";
+    }
+    /** Whether a live install of the org depends on this install (spec §5 rule 9). */
+    async dependedOn(orgId, installId) {
+        const row = await this.db
+            .selectFrom("plugin_install_components as c")
+            .innerJoin("plugin_installs as a", "a.id", "c.install_id")
+            .select("a.id")
+            .where("a.org_id", "=", orgId)
+            .where("a.status", "in", [...LIVE])
+            .where("c.kind", "=", "plugin")
+            .where("c.ref", "=", installId)
+            .executeTakeFirst();
+        return row !== undefined;
+    }
+    /** The items of the dependency installs this install created. */
+    async createdDependencies(installId) {
+        // `ref` is text: the child install ids are read first, then their items
+        const refs = await this.db
+            .selectFrom("plugin_install_components")
+            .select("ref")
+            .where("install_id", "=", installId)
+            .where("kind", "=", "plugin")
+            .where("created", "=", true)
+            .execute();
+        if (refs.length === 0)
+            return [];
+        const rows = await this.db
+            .selectFrom("plugin_installs")
+            .select("item_id")
+            .where("id", "in", refs.map((r) => r.ref))
+            .execute();
+        return rows.map((r) => r.item_id);
+    }
+    /**
+     * Whether installing the item (with the dependencies the org lacks) needs the org's input: a
+     * connector template, or an extension whose org config is required and not set in the org. The
+     * same rule as the org catalog's `needs_config`, applied to the whole tree.
+     */
+    async needsInput(orgId, itemId, version) {
+        const v = await this.db
+            .selectFrom("catalog_item_versions")
+            .select("manifest")
+            .where("item_id", "=", itemId)
+            .where("version", "=", version)
+            .executeTakeFirst();
+        const root = v?.manifest;
+        if (root === undefined)
+            return false;
+        if (await this.manifestNeedsInput(orgId, root, itemId))
+            return true;
+        // the dependencies the install would bring (planning reads no input of the org)
+        const plan = await this.installer.plan(orgId, null, itemId, version, null, "", undefined);
+        const visit = async (p) => {
+            if (await this.manifestNeedsInput(orgId, p.manifest, p.itemId))
+                return true;
+            for (const d of p.dependencies)
+                if (d.plan && (await visit(d.plan)))
+                    return true;
+            return false;
+        };
+        return visit(plan);
+    }
+    /**
+     * Whether installing plugin `itemId` (manifest `m`) needs the org's input: a connector template
+     * on in the org (ruling P2-6: templates switched off there, outside their own scope or disabled
+     * make no connector), or a required org config of its extension not set yet.
+     */
+    async manifestNeedsInput(orgId, m, itemId) {
+        const ids = (m.connectorTemplates ?? []).map((t) => templateIdOfPath(t.path));
+        if ((await connectorTemplatesOn(this.db, orgId, itemId, ids)).size > 0)
+            return true;
+        if (!m.extension)
+            return false;
+        const ext = this.registry.manifests().find((x) => x.name === m.name);
+        const schema = ext?.config?.org;
+        if (schema === undefined || schema.safeParse({}).success)
+            return false;
+        const configured = await this.db
+            .selectFrom("extension_org_configs")
+            .select("plugin")
+            .where("org_id", "=", orgId)
+            .where("plugin", "=", m.name)
+            .where("config", "is not", null)
+            .executeTakeFirst();
+        return configured === undefined;
+    }
+    /**
+     * Logs and audits a failed install or uninstall (`plugin.scope_sync_failed`, actor null) and
+     * records it as the pair's open failure (the super admin's inbox).
+     */
+    async failed(orgId, itemId, op, e, attempt) {
+        attempt.failed = true;
+        const code = e instanceof ApiError ? e.code : "internal";
+        const message = e instanceof Error ? e.message : String(e);
+        this.log.warn("plugin scope sync failed", { orgId, itemId, op, code, err: e });
+        await this.recordFailure(orgId, itemId, op, code, message);
+    }
+    async recordFailure(orgId, itemId, op, code, message) {
+        await audit(this.db, {
+            actorAccountId: null,
+            orgId,
+            action: "plugin.scope_sync_failed",
+            target: itemId,
+            detail: { via: "scope", op, code, message },
+        });
+        const failure = { op, code, message, failed_at: new Date() };
+        await this.db
+            .insertInto("plugin_scope_sync_failures")
+            .values({ item_id: itemId, org_id: orgId, ...failure })
+            .onConflict((oc) => oc.columns(["item_id", "org_id"]).doUpdateSet(failure))
+            .execute();
+    }
+};
+__decorate([
+    Transactional({ propagation: "requires_new" })
+], PluginScopeSync.prototype, "recordFailure", null);
+PluginScopeSync = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(getQueueToken(PLUGIN_SCOPE_QUEUE))),
+    __param(2, Inject(PluginInstaller)),
+    __param(3, Inject(ExtensionRegistry)),
+    __param(4, Inject(ExtensionLifecycle)),
+    __param(5, Inject(LockService)),
+    __param(6, Inject(KERNEL_LOGGER)),
+    __param(7, Inject(TransactionHost))
+], PluginScopeSync);
+export { PluginScopeSync };
+/** The consumer of {@link PLUGIN_SCOPE_QUEUE}: {@link PluginScopeSync}. */
+let PluginScopeSyncProcessor = class PluginScopeSyncProcessor extends WorkerHost {
+    sync;
+    log;
+    stopping = new AbortController();
+    constructor(sync, log) {
+        super();
+        this.sync = sync;
+        this.log = log;
+    }
+    process(job) {
+        return runJob(PLUGIN_SCOPE_QUEUE, job, () => this.sync.process(job.data, this.stopping.signal));
+    }
+    /** Starts consuming (worker role, after the extensions loaded; built with `autorun: false`). */
+    start() {
+        void this.worker.run().catch((err) => this.error(err));
+    }
+    /**
+     * Enqueues every live item's sync once (the worker role, after the start gate opened), in the
+     * background; a failure is only logged (the next worker start, or the next change, enqueues).
+     */
+    resync() {
+        void this.sync
+            .enqueueAll()
+            .catch((err) => this.log.error("plugin scope resync failed", { err }));
+    }
+    /** Stops between pairs and closes the worker. */
+    async close() {
+        this.stopping.abort();
+        await this.worker.close();
+    }
+    failed(job, err) {
+        this.log.error("plugin scope job failed", { name: job?.name, jobId: job?.id, err });
+    }
+    error(err) {
+        this.log.error("plugin scope worker error", { err });
+    }
+};
+__decorate([
+    OnWorkerEvent("failed")
+], PluginScopeSyncProcessor.prototype, "failed", null);
+__decorate([
+    OnWorkerEvent("error")
+], PluginScopeSyncProcessor.prototype, "error", null);
+PluginScopeSyncProcessor = __decorate([
+    Injectable(),
+    __param(0, Inject(PluginScopeSync)),
+    __param(1, Inject(KERNEL_LOGGER))
+], PluginScopeSyncProcessor);
+export { PluginScopeSyncProcessor };

package/dist/catalog/scope.d.ts

@@ -0,0 +1,42 @@
+/** Who a platform plugin is offered to: every org, an opt-in set, or the listed orgs. */
+export type PluginScope = "all" | "optional" | "named";
+/**
+ * The effective state of a plugin in one org. `not_offered`: a `named` item that does not list the
+ * org but is shown to other orgs, which may request access (spec §5.1). `awaiting_confirmation`:
+ * the org's own upload with an extension, until the super admin confirms it (ruling P3-9).
+ */
+export type OrgPluginState = "on" | "off" | "needs_config" | "unavailable" | "not_offered"
+/** The org's own upload, waiting for the super admin's confirmation (owner only, P3-9). */
+ | "awaiting_confirmation";
+/**
+ * Whether the item should be on in the org. Builtin is on unless disabled and its switch is
+ * ignored. Otherwise `all` is on unless disabled or the org switched it off (layering spec §4),
+ * `optional` is on only with an explicit `true` switch, and `named` is on for a listed org unless
+ * its switch is `false`.
+ */
+export declare function wantedOn(item: {
+    scope: PluginScope;
+    disabled: boolean;
+    builtin: boolean;
+}, inList: boolean, sw: boolean | null): boolean;
+/** Whether the org may see the item at all: a named item only for the orgs on its list. */
+export declare function visibleTo(item: {
+    scope: PluginScope;
+}, inList: boolean): boolean;
+/** Whether the org admin may switch the item: every item but a builtin one (layering spec §4). */
+export declare function switchable(item: {
+    scope: PluginScope;
+    builtin: boolean;
+}): boolean;
+/**
+ * Whether an org outside a `named` item's list sees it as requestable: shown to other orgs, not
+ * builtin (a builtin item is `all`) and through the share gate (ruling P3-16: an org-owned item its
+ * owner has not made shareable stays hidden, whatever its stored `shown_to_others`).
+ */
+export declare function requestable(item: {
+    scope: PluginScope;
+    builtin: boolean;
+    shown_to_others: boolean;
+    owner_org_id: string | null;
+    shareable: boolean;
+}, inList: boolean): boolean;

package/dist/catalog/scope.js

@@ -0,0 +1,42 @@
+/**
+ * Plugin scope rules (plugin and component management spec §5). Pure functions only: the
+ * caller reads the item's scope, disabled and builtin flags, the org's list membership and its
+ * explicit switch, and these functions decide the effective state.
+ */
+import { shareGate } from "./ownership.js";
+/**
+ * Whether the item should be on in the org. Builtin is on unless disabled and its switch is
+ * ignored. Otherwise `all` is on unless disabled or the org switched it off (layering spec §4),
+ * `optional` is on only with an explicit `true` switch, and `named` is on for a listed org unless
+ * its switch is `false`.
+ */
+export function wantedOn(item, inList, sw) {
+    if (item.disabled)
+        return false;
+    if (item.builtin)
+        return true;
+    switch (item.scope) {
+        case "all":
+            return sw !== false;
+        case "optional":
+            return sw === true;
+        case "named":
+            return inList && sw !== false;
+    }
+}
+/** Whether the org may see the item at all: a named item only for the orgs on its list. */
+export function visibleTo(item, inList) {
+    return item.scope !== "named" || inList;
+}
+/** Whether the org admin may switch the item: every item but a builtin one (layering spec §4). */
+export function switchable(item) {
+    return !item.builtin;
+}
+/**
+ * Whether an org outside a `named` item's list sees it as requestable: shown to other orgs, not
+ * builtin (a builtin item is `all`) and through the share gate (ruling P3-16: an org-owned item its
+ * owner has not made shareable stays hidden, whatever its stored `shown_to_others`).
+ */
+export function requestable(item, inList) {
+    return (!item.builtin && item.scope === "named" && !inList && item.shown_to_others && shareGate(item));
+}

package/dist/catalog/unshare.d.ts

@@ -0,0 +1,22 @@
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import { type ComponentRow } from "./component-state.js";
+import type { PluginScope } from "./scope.js";
+/**
+ * Narrows an org-owned plugin (row locked by the caller) whose scope is `optional` / `all` to
+ * `named` = owner + the live orgs with a live install or a switch on. Bumps `scope_version` and
+ * audits `catalog.scope_changed`; returns whether the scope changed (the caller enqueues the item's
+ * scope sync after the commit).
+ */
+export declare function narrowItemOnUnshare(db: KernelSchemaDb, actor: string | null, item: {
+    id: string;
+    name: string;
+    scope: PluginScope;
+    owner_org_id: string | null;
+}): Promise<boolean>;
+/**
+ * Narrows an org-owned component with its own `optional` / `all` scope (row locked by the caller)
+ * to `named` = owner + the live orgs where it is on now ({@link componentOn}). A component that
+ * follows its plugin is narrowed with the plugin. Bumps `scope_version`, audits
+ * `component.scope_changed`.
+ */
+export declare function narrowComponentOnUnshare(db: KernelSchemaDb, actor: string | null, c: ComponentRow): Promise<boolean>;