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

package/dist/extensions/bootstrap.d.ts

@@ -1,30 +1,42 @@
 import { type BootstrapManifest, type Logger } from "@capybara-hq/plugin-sdk";
 import { type PluginImport } from "../catalog/plugin-import.js";
 import type { KernelConfig } from "../config/schema.js";
-import type { KernelDb } from "../db/kernel-schema.js";
-import type { ExtensionAdminOps } from "./admin-ops.js";
-import type { ExtensionInstalls } from "./installs.js";
-import type { ExtensionSource } from "./sources.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 { LockService } from "../infra/lock/lock.service.js";
+import type { KernelLogger } from "../log.js";
+import { fetchNpmPackage } from "../packages/npm.js";
+import { ExtensionAdminOps } from "./admin-ops.js";
+import { ExtensionInstalls } from "./installs.js";
+import { PluginApproveLock } from "./locks.js";
+import { ExtensionRegistry } from "./registry.js";
+import type { SingleProviderNote } from "./single-provider.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
@@ -33,8 +45,8 @@ import type { ExtensionSource } from "./sources.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`
@@ -49,8 +61,11 @@ import type { ExtensionSource } from "./sources.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 declare const BOOTSTRAP_MANIFEST_FILE: string;
@@ -60,6 +75,11 @@ export interface BootstrapEntryResult {
     action: "installed" | "upgraded" | "kept" | "imported" | "required_cleared";
     /** The version installed / imported now, or the version kept. */
     version: string;
+    /**
+     * An optional entry installed (or upgraded) but left disabled: another enabled extension holds
+     * a single-provider extension point it provides. (A required entry fails instead.)
+     */
+    leftDisabled?: SingleProviderNote;
 }
 export interface BootstrapResult {
     /** sha256 (hex) of the manifest ({@link bootstrapManifestSha256}). */
@@ -89,25 +109,63 @@ export declare class BootstrapFailedError extends Error {
 export declare function bootstrapManifestSha256(manifest: BootstrapManifest): string;
 /** Reads and parses a bootstrap manifest file; an invalid one throws with its problems. */
 export declare function readBootstrapManifest(file?: string): Promise<BootstrapManifest>;
-export interface BootstrapServiceDeps {
-    db: KernelDb;
-    /** The lock connection is opened separately (and closed after every run). */
-    dbUrl: string;
-    connectTimeoutMs?: number;
-    config: () => KernelConfig;
-    imports: Pick<PluginImport, "prepare" | "confirm">;
-    installs: Pick<ExtensionInstalls, "ingest">;
-    ops: Pick<ExtensionAdminOps, "install" | "enable">;
+/** What {@link resolveBootstrapPackages} needs from the kernel config. */
+export interface BootstrapResolveOptions {
     /**
-     * Config-declared extension names (an entry of the same name is kept, config wins, and no
-     * install record is created). The kernel resolves them from `extensions` before loading.
+     * The offline directory: every `*.tgz` directly in it is matched to the entries by sha512.
+     * Omitted or missing: no offline packages.
      */
-    declared?: () => ReadonlySet<string> | ReadonlyMap<string, ExtensionSource>;
-    log: Pick<Logger, "info" | "warn" | "error">;
+    dir?: string;
+    config: Pick<KernelConfig, "packages">;
+    signal?: AbortSignal;
+    log?: Pick<Logger, "warn">;
+    /** The npm download (default {@link fetchNpmPackage}; tests replace it). */
+    fetch?: typeof fetchNpmPackage;
 }
+/**
+ * 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 declare function resolveBootstrapPackages(manifest: BootstrapManifest, o: BootstrapResolveOptions): Promise<Map<string, Uint8Array>>;
+/** The lock around a whole run (`lock:bootstrap`). */
+export declare const BOOTSTRAP_LOCK_KEY = "bootstrap";
+/** Its lifetime without renewal; a run keeps it by renewal, a crashed holder's expires. */
+export declare const BOOTSTRAP_LOCK_TTL_MS = 120000;
+/** Optional provider: the lock's lifetime (ms) instead of {@link BOOTSTRAP_LOCK_TTL_MS} (tests shorten it). */
+export declare const BOOTSTRAP_LOCK_TTL: unique symbol;
+/** What a run imports a declarative entry or an entry's catalog version with. */
+export type BootstrapImports = Pick<PluginImport, "prepare" | "confirm">;
 export declare class BootstrapService {
-    private readonly d;
-    constructor(d: BootstrapServiceDeps);
+    private readonly kdb;
+    readonly txHost: TransactionHost;
+    private readonly locks;
+    private readonly approveLock;
+    private readonly installs;
+    private readonly 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.
+     */
+    private readonly registry;
+    private readonly configService;
+    private readonly log;
+    /** The lock's lifetime without renewal. */
+    private readonly lockTtlMs;
+    constructor(kdb: KernelDb, txHost: TransactionHost, locks: LockService, approveLock: PluginApproveLock, installs: ExtensionInstalls, ops: ExtensionAdminOps, 
+    /**
+     * 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: ExtensionRegistry, configService: KernelConfigService, log: KernelLogger, 
+    /** The lock's lifetime without renewal. */
+    lockTtlMs?: number);
+    private get db();
+    private config;
     /** Whether the bootstrap step completed for the manifest with this sha256. */
     isDone(manifestSha256: string): Promise<boolean>;
     /**
@@ -119,31 +177,63 @@ export declare class BootstrapService {
      */
     run(o: {
         manifest: BootstrapManifest;
-        dir: string;
+        /** The offline directory (see {@link resolveBootstrapPackages}); omitted: npm only. */
+        dir?: string;
         signal?: AbortSignal;
         carry?: readonly BootstrapEntryResult[];
+        /** The plugin import a declarative entry (or an entry's catalog version) goes through. */
+        imports: BootstrapImports;
     }): Promise<BootstrapResult>;
     /**
-     * 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).
+     */
+    private warnIfHeld;
+    /** The `bootstrap_runs` row and the `bootstrap.completed` audit, in one transaction. */
+    private recordDone;
+    /**
+     * 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.
      */
     private locked;
     /** The entry names the last completed run handled (undefined before any run completed). */
     private lastRunNames;
-    /** Reads every entry's file and checks its sha512 (before the lock: nothing is written yet). */
-    private verifyFiles;
     private entry;
+    /**
+     * 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).
+     */
+    private markBuiltin;
     /** A declarative plugin: catalog only. Returns false when that version is already imported. */
     private importOnly;
     /**
-     * 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.
      */
     private deploy;
     /** The extension of a catalog version already imported: ingest, approve, install (, enable). */
     private deployFromStore;
+    /**
+     * Enables a bootstrap extension unless another enabled extension provides one of its
+     * single-provider extension points (see {@link leftDisabled}).
+     */
+    private enableOrWarn;
+    /**
+     * 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.
+     */
+    private leftDisabled;
+    /** The permission snapshot of a stored package (source `bootstrap`), under the approve lock. */
+    private approveStored;
     /** Install records still `required` whose entry left the manifest lose `required`. */
     private clearRemoved;
 }