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

package/dist/extensions/bootstrap.js

@@ -1,39 +1,64 @@
+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 { readFile } from "node:fs/promises";
+import { readdir, readFile, stat } from "node:fs/promises";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { bootstrapFileName, parseBootstrapManifest, SDK_VERSION, } from "@capybara-hq/plugin-sdk";
+import { parseBootstrapManifest, SDK_VERSION, } from "@capybara-hq/plugin-sdk";
+import { Inject, Injectable, Optional } from "@nestjs/common";
 import { sql } from "kysely";
-import pg from "pg";
 import semver from "semver";
+import { otherNameOwner } from "../catalog/ownership.js";
 import { catalogPackageError } from "../catalog/plugin-import.js";
 import { PluginPackageError, readPluginPackage } from "../catalog/plugin-package.js";
-import { pgConnectOptions } from "../db/pool.js";
 import { ApiError } from "../errors.js";
 import { audit } from "../identity/audit.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 { LockService } from "../infra/lock/lock.service.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { fetchNpmPackage, IntegrityMismatchError, NpmFetchError, PackageTooLargeError, } from "../packages/npm.js";
+import { ExtensionAdminOps } from "./admin-ops.js";
 import { writeSnapshot } from "./approvals.js";
+import { ExtensionInstalls } from "./installs.js";
+import { PluginApproveLock } from "./locks.js";
 import { ExtensionPackageError, permissionSetOfPackage, readExtensionPackage } from "./package.js";
 import { diffPermissions } from "./permission-set.js";
+import { ExtensionRegistry } from "./registry.js";
 /**
- * The bootstrap step (package ecosystem spec §7): installs the plugins pinned by the bootstrap
- * manifest (`packages/kernel/bootstrap.json`) from the tgz files baked into the image. It replaced
- * the builtin extensions.
+ * The bootstrap step (package ecosystem spec §7, startup bootstrap spec): installs the plugins
+ * pinned by the bootstrap manifest (`packages/kernel/bootstrap.json`). It replaced the builtin
+ * extensions.
  *
- * - Every file (`<dir>/<name>-<version>.tgz`) is checked against the entry's sha512 before anything
- *   is read or written; a missing file is `bootstrap.missing_file`, a mismatch
- *   `bootstrap.integrity_mismatch` (both name the plugin), and then nothing is written. It never
- *   touches the network.
- * - The whole run holds the session advisory lock `capybara.bootstrap` on a connection of its own
- *   (taken with `pg_try_advisory_lock` in a backoff loop that observes the signal, and closed
- *   afterwards, so the lock never outlives the run): when several replicas start together only one
- *   runs it; the others wait, then find it done. "Done" is a `bootstrap_runs` row for the
+ * - When the run is already done for the manifest nothing is read: no directory, no network, so a
+ *   restart of an installed deployment never needs npm.
+ * - Otherwise, inside the lock and before anything is written, every entry's tgz is obtained
+ *   ({@link resolveBootstrapPackages}): a `*.tgz` file of the optional offline directory whose
+ *   sha512 equals the entry's `integrity` (the file name does not matter), else the npm download
+ *   of a `source: "npm"` entry (`packages.npmRegistry` / `npmToken` / `maxBytes`, verified against
+ *   the pin only). A workspace entry without a matching file is `bootstrap.missing_file`, a failed
+ *   download `bootstrap.download_failed`, a download that differs from the pin
+ *   `bootstrap.integrity_mismatch` (all name the plugin), and then nothing is written. Downloading
+ *   inside the lock means a fleet starting together downloads once.
+ * - The whole run holds the Redis lock `lock:bootstrap` (`LockService`, decision R5 of the Nest
+ *   kernel spec: TTL {@link BOOTSTRAP_LOCK_TTL_MS}, renewed every third of it, so a run longer than the TTL keeps
+ *   it and a crashed holder's lock expires within it), taken by an unbounded wait that observes
+ *   the signal: when several replicas (or `capybara bootstrap` and a starting kernel) run it
+ *   together only one runs it; the others wait, then find it done. A lost lock (renewal failed
+ *   until expiry) aborts the run at its next step. "Done" is a `bootstrap_runs` row for the
  *   manifest's sha256 (written with the audit `bootstrap.completed` only when every entry
- *   succeeded; otherwise the next start runs it again, which is idempotent). A lock connection
- *   that drops mid-run is not detected (its errors are swallowed) and the run goes on without the
- *   lock, so a second replica could run concurrently: accepted, since a concurrent import or
- *   install degrades to `catalog.version_exists` and a deploy from the package store.
+ *   succeeded; otherwise the next start runs it again, which is idempotent).
  * - Only entries new to the manifest are installed (Ruling 5): an optional entry that the last
- *   completed run already handled and that is not installed now (an enterprise admin uninstalled
+ *   completed run already handled and that is not installed now (a super admin uninstalled
  *   it) stays uninstalled -> `kept`. A required entry is always installed.
  * - Per entry, by the installed state of its extension:
  *   - not installed (and new, or required): imported into the catalog (source `bootstrap`, ref
@@ -42,8 +67,8 @@ import { diffPermissions } from "./permission-set.js";
  *     and enabled -> `installed`;
  *   - installed from `bootstrap` at a lower version: upgraded the same way (core's release vouched
  *     for the version, so new permissions are pre-approved and audited), keeping the desired state
- *     an enterprise admin chose (a disabled optional plugin stays disabled) -> `upgraded`;
- *   - installed at a higher version, or from another source (an enterprise admin upgraded it), or
+ *     a super admin chose (a disabled optional plugin stays disabled) -> `upgraded`;
+ *   - installed at a higher version, or from another source (a super admin upgraded it), or
  *     the name is config-declared (`declared`: config wins, no install record is created):
  *     untouched, never downgraded -> `kept`;
  *   - a declarative plugin (no extension): imported into the catalog only -> `imported` (`kept`
@@ -58,8 +83,11 @@ import { diffPermissions } from "./permission-set.js";
  *   loses `required` -> `required_cleared`.
  * A failed entry does not stop the others; the run then throws {@link BootstrapFailedError} naming
  * them. The packages are kept in PG (`blob_store = 'pg'`), so installing an extension never needs
- * the object store (object-store-s3 is itself a bootstrap plugin); a declarative plugin's catalog
- * files do.
+ * the object store (object-store-s3 is itself a bootstrap plugin) and the directory and npm are
+ * never needed again. A plugin's icons and setup guide files are kept in PG too (`catalog_files`),
+ * so they never need it either; its skills, connector templates and agent templates do (an entry
+ * shipping them fails while no object store runs; an optional one is retried after the extensions
+ * loaded).
  */
 /** The bootstrap manifest that ships with the kernel package. */
 export const BOOTSTRAP_MANIFEST_FILE = fileURLToPath(new URL("../../bootstrap.json", import.meta.url));
@@ -95,16 +123,149 @@ export async function readBootstrapManifest(file = BOOTSTRAP_MANIFEST_FILE) {
     return parsed;
 }
 const integrityOf = (bytes) => `sha512-${createHash("sha512").update(bytes).digest("base64")}`;
-/** The advisory lock around a whole run. */
-const LOCK_KEY = "capybara.bootstrap";
-export class BootstrapService {
-    d;
-    constructor(d) {
-        this.d = d;
+/**
+ * Obtains every entry's tgz, checked against its pinned sha512: from the offline directory when a
+ * file there has that sha512, else (a `source: "npm"` entry) downloaded from the npm registry and
+ * verified against the pin (the packument's `dist.integrity` is not consulted). Throws an
+ * {@link ApiError} naming the plugin for the first entry it cannot obtain
+ * (`bootstrap.missing_file`, `bootstrap.download_failed`, `bootstrap.integrity_mismatch`).
+ */
+export async function resolveBootstrapPackages(manifest, o) {
+    const out = new Map();
+    if (manifest.plugins.length === 0)
+        return out;
+    const { npmRegistry, npmToken, maxBytes } = o.config.packages;
+    const offline = o.dir !== undefined ? await scanOfflineDir(o.dir, maxBytes, o.log) : new Map();
+    const fetchPackage = o.fetch ?? fetchNpmPackage;
+    const signal = o.signal ?? new AbortController().signal;
+    const where = o.dir !== undefined ? o.dir : "the bootstrap directory (config bootstrap.dir)";
+    for (const e of manifest.plugins) {
+        signal.throwIfAborted();
+        const found = offline.get(e.integrity);
+        if (found !== undefined) {
+            out.set(e.name, found);
+            continue;
+        }
+        if (e.source === "workspace") {
+            throw new ApiError("bootstrap.missing_file", `Bootstrap plugin ${e.name} ${e.version}: no file in ${where} has its pinned sha512 (${e.integrity.slice(0, 19)}…), and a workspace entry cannot be downloaded; put its package tgz (pnpm pack-plugin ${e.path}) in that directory`);
+        }
+        const registry = registryOrigin(npmRegistry);
+        const offlineHint = `to install offline, put the package tgz (npm pack ${e.npm}@${e.version}, any file name) in ${where}`;
+        try {
+            const r = await fetchPackage({ registry: npmRegistry, ...(npmToken !== undefined && { token: npmToken }), maxBytes }, e.npm, e.version, signal, { expectedIntegrity: e.integrity });
+            out.set(e.name, r.bytes);
+        }
+        catch (err) {
+            if (signal.aborted)
+                throw err;
+            if (err instanceof IntegrityMismatchError) {
+                throw new ApiError("bootstrap.integrity_mismatch", `Bootstrap plugin ${e.name} ${e.version}: the package ${e.npm}@${e.version} downloaded from ${registry} does not match its pinned sha512 (expected ${e.integrity.slice(0, 19)}…, got ${err.actual.slice(0, 19)}…); refusing to install anything`);
+            }
+            const reason = err instanceof NpmFetchError || err instanceof PackageTooLargeError
+                ? err.message
+                : err instanceof Error
+                    ? err.message
+                    : String(err);
+            throw new ApiError("bootstrap.download_failed", `Bootstrap plugin ${e.name} ${e.version}: cannot download ${e.npm}@${e.version} from ${registry} (${reason}); ${offlineHint}, or set packages.npmRegistry to a reachable mirror`);
+        }
+    }
+    return out;
+}
+/** The registry's origin, for messages (never its credentials or path). */
+function registryOrigin(registry) {
+    try {
+        return new URL(registry).origin;
+    }
+    catch {
+        return "the configured npm registry";
+    }
+}
+/**
+ * The `*.tgz` files directly in `dir` by their sha512 integrity. A missing directory is an empty
+ * one; a file larger than `maxBytes` is skipped with a warning.
+ */
+async function scanOfflineDir(dir, maxBytes, log) {
+    const out = new Map();
+    let names;
+    try {
+        names = await readdir(dir);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT" || code === "ENOTDIR")
+            return out;
+        throw err;
+    }
+    for (const name of names.sort()) {
+        if (!name.endsWith(".tgz"))
+            continue;
+        const file = join(dir, name);
+        const st = await stat(file).catch(() => undefined);
+        if (!st?.isFile())
+            continue;
+        if (st.size > maxBytes) {
+            log?.warn("bootstrap: a file in the bootstrap directory exceeds packages.maxBytes; skipped", {
+                file,
+                size: st.size,
+                maxBytes,
+            });
+            continue;
+        }
+        const bytes = new Uint8Array(await readFile(file));
+        const integrity = integrityOf(bytes);
+        if (!out.has(integrity))
+            out.set(integrity, bytes);
+    }
+    return out;
+}
+/** The lock around a whole run (`lock:bootstrap`). */
+export const BOOTSTRAP_LOCK_KEY = "bootstrap";
+/** Its lifetime without renewal; a run keeps it by renewal, a crashed holder's expires. */
+export const BOOTSTRAP_LOCK_TTL_MS = 120_000;
+/** Optional provider: the lock's lifetime (ms) instead of {@link BOOTSTRAP_LOCK_TTL_MS} (tests shorten it). */
+export const BOOTSTRAP_LOCK_TTL = Symbol("BOOTSTRAP_LOCK_TTL");
+/** The pause between attempts while another holder runs the step. */
+const LOCK_RETRY_MS = 500;
+let BootstrapService = class BootstrapService {
+    kdb;
+    txHost;
+    locks;
+    approveLock;
+    installs;
+    ops;
+    registry;
+    configService;
+    log;
+    lockTtlMs;
+    constructor(kdb, txHost, locks, approveLock, installs, ops, 
+    /**
+     * Config-declared extension names (an entry of the same name is kept, config wins, and no
+     * install record is created): the start sequence records them before the bootstrap step, the
+     * CLI from its inspection.
+     */
+    registry, configService, log, 
+    /** The lock's lifetime without renewal. */
+    lockTtlMs = BOOTSTRAP_LOCK_TTL_MS) {
+        this.kdb = kdb;
+        this.txHost = txHost;
+        this.locks = locks;
+        this.approveLock = approveLock;
+        this.installs = installs;
+        this.ops = ops;
+        this.registry = registry;
+        this.configService = configService;
+        this.log = log;
+        this.lockTtlMs = lockTtlMs;
+    }
+    get db() {
+        return this.kdb.db;
+    }
+    config() {
+        return this.configService.get();
     }
     /** Whether the bootstrap step completed for the manifest with this sha256. */
     async isDone(manifestSha256) {
-        const row = await this.d.db
+        const row = await this.db
             .selectFrom("bootstrap_runs")
             .select("manifest_sha256")
             .where("manifest_sha256", "=", manifestSha256)
@@ -120,27 +281,42 @@ export class BootstrapService {
      */
     async run(o) {
         const manifestSha256 = bootstrapManifestSha256(o.manifest);
-        const files = await this.verifyFiles(o.manifest, o.dir);
-        return this.locked(o.signal, async () => {
-            const done = await this.d.db
+        const recorded = async () => {
+            const done = await this.db
                 .selectFrom("bootstrap_runs")
                 .select("results")
                 .where("manifest_sha256", "=", manifestSha256)
                 .executeTakeFirst();
-            if (done) {
-                return { manifestSha256, results: done.results };
-            }
+            return done && { manifestSha256, results: done.results };
+        };
+        // Done: no lock, no directory, no network
+        const before = await recorded();
+        if (before)
+            return before;
+        return this.locked(o.signal, async (signal) => {
+            // Another replica may have finished it while this one waited for the lock
+            const done = await recorded();
+            if (done)
+                return done;
+            // Every package is obtained and checked before the first write
+            const files = await resolveBootstrapPackages(o.manifest, {
+                ...(o.dir !== undefined && { dir: o.dir }),
+                config: this.config(),
+                signal,
+                log: this.log,
+            });
             const handled = await this.lastRunNames();
             const results = [];
             const failures = [];
             for (const e of o.manifest.plugins) {
-                o.signal?.throwIfAborted();
+                signal.throwIfAborted();
+                await this.warnIfHeld(e);
                 try {
-                    const r = await this.entry(e, files.get(e.name), handled);
+                    const r = await this.entry(e, files.get(e.name), handled, o.imports);
                     results.push(carried(r, o.carry));
                 }
                 catch (err) {
-                    this.d.log.error("bootstrap: a plugin could not be installed", {
+                    this.log.error("bootstrap: a plugin could not be installed", {
                         plugin: e.name,
                         version: e.version,
                         required: e.required,
@@ -157,63 +333,70 @@ export class BootstrapService {
             results.push(...(await this.clearRemoved(o.manifest)));
             if (failures.length > 0)
                 throw new BootstrapFailedError(failures, results);
-            await this.d.db.transaction().execute(async (trx) => {
-                await trx
-                    .insertInto("bootstrap_runs")
-                    .values({
-                    manifest_sha256: manifestSha256,
-                    completed_at: sql `now()`,
-                    results: JSON.stringify(results),
-                })
-                    .execute();
-                await audit(trx, {
-                    action: "bootstrap.completed",
-                    target: manifestSha256,
-                    detail: { manifestSha256, results },
-                });
-            });
-            this.d.log.info("bootstrap completed", { manifestSha256, results });
+            signal.throwIfAborted();
+            await this.recordDone(manifestSha256, results);
+            this.log.info("bootstrap completed", { manifestSha256, results });
             return { manifestSha256, results };
         });
     }
     /**
-     * Runs `fn` holding the session advisory lock on a connection of its own: `pg_try_advisory_lock`
-     * retried with a backoff (100 ms doubling to 1 s) that stops when `signal` aborts. The connection
-     * is closed afterwards in every case, which releases the lock even when the unlock failed.
+     * A pin whose plugin name an org holds (a live org-owned catalog item): the bootstrap takes no
+     * name over (ruling P3-28), so the entry fails; this warning tells the super admin why and
+     * which org holds it (final review M4).
+     */
+    async warnIfHeld(e) {
+        const holder = await otherNameOwner(this.db, e.name, null);
+        if (holder?.kind !== "org")
+            return;
+        this.log.warn("bootstrap: the plugin name is held by an organization; the entry cannot take it over until the organization renames or deletes its plugin", {
+            plugin: e.name,
+            version: e.version,
+            required: e.required,
+            ownerOrgId: holder.orgId,
+            ownerOrg: holder.name,
+        });
+    }
+    /** The `bootstrap_runs` row and the `bootstrap.completed` audit, in one transaction. */
+    async recordDone(manifestSha256, results) {
+        await this.db
+            .insertInto("bootstrap_runs")
+            .values({
+            manifest_sha256: manifestSha256,
+            completed_at: sql `now()`,
+            results: JSON.stringify(results),
+        })
+            .execute();
+        await audit(this.db, {
+            action: "bootstrap.completed",
+            target: manifestSha256,
+            detail: { manifestSha256, results },
+        });
+    }
+    /**
+     * Runs `fn` holding `lock:bootstrap`: waits without bound while another replica holds it
+     * (until `signal` aborts), renews it while `fn` runs and releases it afterwards. `fn` gets a
+     * signal that also aborts when the lock is lost.
      */
     async locked(signal, fn) {
-        const client = new pg.Client({
-            connectionString: this.d.dbUrl,
-            ...pgConnectOptions({ connectTimeoutMs: this.d.connectTimeoutMs }),
+        const handle = await this.locks.acquire(BOOTSTRAP_LOCK_KEY, {
+            ttlMs: this.lockTtlMs,
+            waitMs: Number.POSITIVE_INFINITY,
+            retryMs: LOCK_RETRY_MS,
+            ...(signal !== undefined && { signal }),
         });
-        client.on("error", () => { });
+        // An unbounded wait returns a handle or throws the abort reason
+        if (!handle)
+            throw new Error("bootstrap: the lock could not be taken");
         try {
-            await client.connect();
-            for (let wait = 100;; wait = Math.min(wait * 2, 1_000)) {
-                signal?.throwIfAborted();
-                const r = await client.query("SELECT pg_try_advisory_lock(hashtext($1)) AS ok", [LOCK_KEY]);
-                if (r.rows[0]?.ok === true)
-                    break;
-                await sleep(wait, signal);
-            }
-            try {
-                return await fn();
-            }
-            finally {
-                await client
-                    .query("SELECT pg_advisory_unlock(hashtext($1))", [LOCK_KEY])
-                    .catch((err) => this.d.log.warn("bootstrap: cannot release the advisory lock; closing its connection", {
-                    err,
-                }));
-            }
+            return await fn(signal ? AbortSignal.any([signal, handle.lost]) : handle.lost);
         }
         finally {
-            await client.end().catch(() => { });
+            await handle.release();
         }
     }
     /** The entry names the last completed run handled (undefined before any run completed). */
     async lastRunNames() {
-        const row = await this.d.db
+        const row = await this.db
             .selectFrom("bootstrap_runs")
             .select("results")
             .orderBy("completed_at", "desc")
@@ -225,31 +408,9 @@ export class BootstrapService {
             .filter((r) => r.action !== "required_cleared")
             .map((r) => r.name));
     }
-    /** Reads every entry's file and checks its sha512 (before the lock: nothing is written yet). */
-    async verifyFiles(manifest, dir) {
-        const out = new Map();
-        for (const e of manifest.plugins) {
-            const file = join(dir, bootstrapFileName(e));
-            let bytes;
-            try {
-                bytes = new Uint8Array(await readFile(file));
-            }
-            catch (err) {
-                if (err.code !== "ENOENT")
-                    throw err;
-                throw new ApiError("bootstrap.missing_file", `Bootstrap plugin ${e.name} ${e.version}: ${file} is missing; the image must carry every package bootstrap.json pins`);
-            }
-            const actual = integrityOf(bytes);
-            if (actual !== e.integrity) {
-                throw new ApiError("bootstrap.integrity_mismatch", `Bootstrap plugin ${e.name} ${e.version}: ${file} does not match its pinned sha512 (expected ${e.integrity.slice(0, 19)}…, got ${actual.slice(0, 19)}…); refusing to install anything`);
-            }
-            out.set(e.name, bytes);
-        }
-        return out;
-    }
-    async entry(e, bytes, handled) {
+    async entry(e, bytes, handled, imports) {
         const pkg = await readPluginPackage(bytes, {
-            maxBytes: this.d.config().packages.maxBytes,
+            maxBytes: this.config().packages.maxBytes,
             hostSdkVersion: SDK_VERSION,
         }).catch((err) => {
             throw err instanceof PluginPackageError ? catalogPackageError(err) : err;
@@ -261,34 +422,37 @@ export class BootstrapService {
         // Not new to the manifest: an optional entry left out on purpose stays out (Ruling 5)
         const isNew = handled === undefined || !handled.has(e.name);
         if (!pkg.manifest.extension) {
+            await this.markBuiltin(e.name, e.required);
             if (!isNew)
                 return { name: e.name, action: "kept", version: e.version };
-            const imported = await this.importOnly(e, bytes, ref);
+            const imported = await this.importOnly(e, bytes, ref, imports);
+            await this.markBuiltin(e.name, e.required);
             return { name: e.name, action: imported ? "imported" : "kept", version: e.version };
         }
-        if (this.d.declared?.().has(e.name)) {
-            this.d.log.warn("bootstrap: the plugin is declared in the extensions config list; the config plugin is used", { plugin: e.name });
+        if (this.registry.declared().has(e.name)) {
+            this.log.warn("bootstrap: the plugin is declared in the extensions config list; the config plugin is used", { plugin: e.name });
             return { name: e.name, action: "kept", version: e.version };
         }
-        const row = await this.d.db
+        const row = await this.db
             .selectFrom("extension_installs")
             .select(["version", "source", "required", "desired_state", "sha256"])
             .where("name", "=", e.name)
             .executeTakeFirst();
         if (!row && !isNew && !e.required) {
-            this.d.log.info("bootstrap: an optional plugin that is not installed stays uninstalled", {
+            this.log.info("bootstrap: an optional plugin that is not installed stays uninstalled", {
                 plugin: e.name,
             });
             return { name: e.name, action: "kept", version: e.version };
         }
         let result;
+        let leftDisabled;
         if (!row) {
-            await this.deploy(e, bytes, ref, true);
+            leftDisabled = await this.deploy(e, bytes, ref, true, imports);
             result = { name: e.name, action: "installed", version: e.version };
         }
         else if (row.source === "bootstrap" && isLower(row.version, e.version)) {
             // The desired state the admin chose is kept; a required plugin is enabled below anyway
-            await this.deploy(e, bytes, ref, row.desired_state === "enabled");
+            leftDisabled = await this.deploy(e, bytes, ref, row.desired_state === "enabled", imports);
             result = { name: e.name, action: "upgraded", version: e.version };
         }
         else {
@@ -297,12 +461,12 @@ export class BootstrapService {
                 row.sha256 !== createHash("sha256").update(bytes).digest("hex")) {
                 // The pin changed bytes without a version bump (an image built from main between
                 // releases): the installed package stays, so say so instead of keeping it silently
-                this.d.log.warn("bootstrap: the image's package differs from the installed one at the same version; the installed package is kept (bump the version to roll it out)", { plugin: e.name, version: e.version });
+                this.log.warn("bootstrap: the image's package differs from the installed one at the same version; the installed package is kept (bump the version to roll it out)", { plugin: e.name, version: e.version });
             }
             result = { name: e.name, action: "kept", version: row.version };
         }
         if (row?.required !== e.required) {
-            await this.d.db
+            await this.db
                 .updateTable("extension_installs")
                 .set({ required: e.required })
                 .where("name", "=", e.name)
@@ -310,22 +474,52 @@ export class BootstrapService {
         }
         // A required install must run on the deployment (an org cannot use it otherwise)
         if (e.required && row?.desired_state === "disabled") {
-            await this.d.ops.enable(e.name, null);
+            leftDisabled = await this.enableOrWarn(e);
         }
-        return result;
+        await this.markBuiltin(e.name, e.required);
+        return leftDisabled === undefined ? result : { ...result, leftDisabled };
+    }
+    /**
+     * The catalog item of a bootstrap entry follows `required`: a required entry is builtin, offered
+     * to every org (scope `all`) and not disabled (migration 0075 could leave a required plugin
+     * disabled); an entry that stops being required is no longer builtin and keeps scope `all` (the
+     * admin may change it from then on).
+     */
+    async markBuiltin(name, required) {
+        const touch = { updated_at: sql `now()` };
+        if (required) {
+            await this.db
+                .updateTable("catalog_items")
+                .set({
+                builtin: true,
+                scope: "all",
+                disabled: false,
+                scope_version: sql `scope_version + 1`,
+                ...touch,
+            })
+                .where("name", "=", name)
+                .where("deleted_at", "is", null)
+                .where((eb) => eb.or([eb("builtin", "=", false), eb("scope", "<>", "all"), eb("disabled", "=", true)]))
+                .execute();
+            return;
+        }
+        await this.db
+            .updateTable("catalog_items")
+            .set({ builtin: false, ...touch })
+            .where("name", "=", name)
+            .where("deleted_at", "is", null)
+            .where("builtin", "=", true)
+            .execute();
     }
     /** A declarative plugin: catalog only. Returns false when that version is already imported. */
-    async importOnly(e, bytes, ref) {
+    async importOnly(e, bytes, ref, imports) {
         try {
-            const { stagingId, review } = await this.d.imports.prepare(null, bytes, {
+            const { stagingId, review } = await imports.prepare(null, bytes, {
                 kind: "bootstrap",
                 ref,
                 integrity: e.integrity,
             });
-            await this.d.imports.confirm(null, stagingId, {
-                reviewHash: review.reviewHash,
-                deployExtension: false,
-            });
+            await imports.confirm(null, stagingId, { reviewHash: review.reviewHash });
             return true;
         }
         catch (err) {
@@ -335,14 +529,14 @@ export class BootstrapService {
         }
     }
     /**
-     * Imports, approves, installs and enables (one review, confirmed with `deployExtension`). When
+     * Imports, approves, installs and enables (one review; its confirm deploys the extension). When
      * the catalog already has this version (an earlier run stopped after importing, or the same
      * package came from a marketplace), the extension is deployed from the package store instead.
      */
-    async deploy(e, bytes, ref, enable) {
+    async deploy(e, bytes, ref, enable, imports) {
         let staged;
         try {
-            staged = await this.d.imports.prepare(null, bytes, {
+            staged = await imports.prepare(null, bytes, {
                 kind: "bootstrap",
                 ref,
                 integrity: e.integrity,
@@ -350,70 +544,140 @@ export class BootstrapService {
         }
         catch (err) {
             if (err instanceof ApiError && err.code === "catalog.version_exists") {
-                await this.deployFromStore(e, bytes, ref, enable);
-                return;
+                return this.deployFromStore(e, bytes, ref, enable);
             }
             throw err;
         }
-        const r = await this.d.imports.confirm(null, staged.stagingId, {
+        const r = await imports.confirm(null, staged.stagingId, {
             reviewHash: staged.review.reviewHash,
-            deployExtension: true,
             enable,
         });
         if (r.deploy?.result === "failed") {
             throw new ApiError((r.deploy.code ?? "internal"), r.deploy.message ?? `installing extension ${e.name} failed`);
         }
+        if (r.deploy?.singleProvider !== undefined) {
+            return this.leftDisabled(e, {
+                code: r.deploy.code,
+                message: r.deploy.message,
+                singleProvider: r.deploy.singleProvider,
+            });
+        }
+        return undefined;
     }
     /** The extension of a catalog version already imported: ingest, approve, install (, enable). */
     async deployFromStore(e, bytes, ref, enable) {
-        const review = await this.d.installs.ingest(null, bytes, { source: "bootstrap", ref }, { store: "pg" });
+        const review = await this.installs.ingest(null, bytes, { source: "bootstrap", ref }, { store: "pg" });
         let set;
         try {
             set = permissionSetOfPackage(await readExtensionPackage(bytes, {
-                maxBytes: this.d.config().packages.maxBytes,
+                maxBytes: this.config().packages.maxBytes,
                 hostSdkVersion: SDK_VERSION,
             }));
         }
         catch (err) {
             throw err instanceof ExtensionPackageError ? catalogPackageError(err) : err;
         }
-        await this.d.db.transaction().execute(async (trx) => {
-            await sql `SELECT pg_advisory_xact_lock(hashtext(${`capybara.plugin-approve:${e.name}`}))`.execute(trx);
-            const snap = await trx
-                .selectFrom("extension_permission_snapshots")
-                .select("permissions")
-                .where("plugin", "=", e.name)
-                .forUpdate()
-                .executeTakeFirst();
-            const { added, removed } = diffPermissions(snap?.permissions, set);
-            await writeSnapshot(trx, e.name, e.version, set, {
-                source: "bootstrap",
-                audit: { added, removed, sha256: review.sha256 },
-            });
-        });
-        const item = await this.d.db
+        await this.approveStored(e, set, review.sha256);
+        const item = await this.db
             .selectFrom("catalog_items")
             .select("id")
             .where("name", "=", e.name)
             .where("deleted_at", "is", null)
             .executeTakeFirst();
-        await this.d.ops.install(e.name, review.sha256, null, undefined, item ? { catalogItemId: item.id } : {});
-        if (enable)
-            await this.d.ops.enable(e.name, null);
+        const installed = await this.ops.install(e.name, review.sha256, null, undefined, item ? { catalogItemId: item.id } : {});
+        // An upgrade newly providing a held single-provider point is left disabled by the install
+        if (installed.leftDisabled !== undefined)
+            return this.leftDisabled(e, installed.leftDisabled);
+        return enable ? this.enableOrWarn(e) : undefined;
+    }
+    /**
+     * Enables a bootstrap extension unless another enabled extension provides one of its
+     * single-provider extension points (see {@link leftDisabled}).
+     */
+    async enableOrWarn(e) {
+        const r = await this.ops.enableUnlessOccupied(e.name, null);
+        return r.enabled ? undefined : this.leftDisabled(e, r.note);
+    }
+    /**
+     * A bootstrap extension left disabled because another enabled extension holds a single-provider
+     * extension point it provides. An optional preinstall (a sandbox while the super admin runs
+     * another one) stays disabled with a warning, and the entry's result says so. A required entry
+     * fails (thrown, so the run is not recorded done, `capybara bootstrap` exits 1 and
+     * `capybara start` refuses to serve): the deployment cannot run without it, and only the super
+     * admin can free the point, by disabling the other provider and running the bootstrap again.
+     */
+    leftDisabled(e, note) {
+        const block = note.singleProvider;
+        if (e.required) {
+            const other = block.enabled.name;
+            throw new ApiError(note.code, `Required plugin ${e.name} provides ${block.extensionPoint}, which ${other} already provides; disable ${other} and run the bootstrap again`, [block]);
+        }
+        this.log.warn(`bootstrap: the plugin is installed disabled; ${note.message}`, {
+            plugin: e.name,
+            required: e.required,
+        });
+        return note;
+    }
+    /** The permission snapshot of a stored package (source `bootstrap`), under the approve lock. */
+    async approveStored(e, set, sha256) {
+        await this.approveLock.lock(e.name);
+        const snap = await this.db
+            .selectFrom("extension_permission_snapshots")
+            .select("permissions")
+            .where("plugin", "=", e.name)
+            .forUpdate()
+            .executeTakeFirst();
+        const { added, removed } = diffPermissions(snap?.permissions, set);
+        await writeSnapshot(this.db, e.name, e.version, set, {
+            source: "bootstrap",
+            audit: { added, removed, sha256 },
+        });
     }
     /** Install records still `required` whose entry left the manifest lose `required`. */
     async clearRemoved(manifest) {
         const names = manifest.plugins.map((p) => p.name);
-        let q = this.d.db
+        let q = this.db
             .updateTable("extension_installs")
             .set({ required: false })
             .where("required", "=", true);
         if (names.length > 0)
             q = q.where("name", "not in", names);
         const rows = await q.returning(["name", "version"]).execute();
+        for (const r of rows)
+            await this.markBuiltin(r.name, false);
+        // A declarative plugin has no install record: clear builtin by catalog name
+        let items = this.db
+            .updateTable("catalog_items")
+            .set({ builtin: false, updated_at: sql `now()` })
+            .where("builtin", "=", true)
+            .where("deleted_at", "is", null);
+        if (names.length > 0)
+            items = items.where("name", "not in", names);
+        await items.execute();
         return rows.map((r) => ({ name: r.name, action: "required_cleared", version: r.version }));
     }
-}
+};
+__decorate([
+    Transactional()
+], BootstrapService.prototype, "recordDone", null);
+__decorate([
+    Transactional()
+], BootstrapService.prototype, "approveStored", null);
+BootstrapService = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(TransactionHost)),
+    __param(2, Inject(LockService)),
+    __param(3, Inject(PluginApproveLock)),
+    __param(4, Inject(ExtensionInstalls)),
+    __param(5, Inject(ExtensionAdminOps)),
+    __param(6, Inject(ExtensionRegistry)),
+    __param(7, Inject(KernelConfigService)),
+    __param(8, Inject(KERNEL_LOGGER)),
+    __param(9, Optional()),
+    __param(9, Inject(BOOTSTRAP_LOCK_TTL))
+], BootstrapService);
+export { BootstrapService };
 /** A `kept` result whose entry an earlier pass of the same start installed / upgraded / imported. */
 function carried(r, carry) {
     if (r.action !== "kept")
@@ -423,19 +687,5 @@ function carried(r, carry) {
         ? before
         : r;
 }
-/** Resolves after `ms`; rejects with the abort reason when `signal` aborts first. */
-function sleep(ms, signal) {
-    return new Promise((resolve, reject) => {
-        const onAbort = () => {
-            clearTimeout(timer);
-            reject(signal?.reason);
-        };
-        const timer = setTimeout(() => {
-            signal?.removeEventListener("abort", onAbort);
-            resolve();
-        }, ms);
-        signal?.addEventListener("abort", onAbort, { once: true });
-    });
-}
 /** `installed` is below `pinned` (a version that is not semver is never upgraded). */
 const isLower = (installed, pinned) => semver.valid(installed) !== null && semver.valid(pinned) !== null && semver.lt(installed, pinned);