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

package/dist/extensions/bootstrap.d.ts

@@ -1,11 +1,17 @@
 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 { 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 type { ExtensionAdminOps } from "./admin-ops.js";
-import type { ExtensionInstalls } from "./installs.js";
-import type { ExtensionSource } from "./sources.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, startup bootstrap spec): installs the plugins
  * pinned by the bootstrap manifest (`packages/kernel/bootstrap.json`). It replaced the builtin
@@ -21,17 +27,16 @@ import type { ExtensionSource } from "./sources.js";
  *   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 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
+ * - 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
@@ -40,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`
@@ -57,7 +62,10 @@ import type { ExtensionSource } from "./sources.js";
  * 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) and the directory and npm are
- * never needed again; a declarative plugin's catalog files do need the object store.
+ * 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;
@@ -67,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}). */
@@ -117,25 +130,42 @@ export interface BootstrapResolveOptions {
  * (`bootstrap.missing_file`, `bootstrap.download_failed`, `bootstrap.integrity_mismatch`).
  */
 export declare function resolveBootstrapPackages(manifest: BootstrapManifest, o: BootstrapResolveOptions): Promise<Map<string, Uint8Array>>;
-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">;
+/** 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 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 kernel resolves them from `extensions` before loading.
+     * install record is created): the start sequence records them before the bootstrap step, the
+     * CLI from its inspection.
      */
-    declared?: () => ReadonlySet<string> | ReadonlyMap<string, ExtensionSource>;
-    log: Pick<Logger, "info" | "warn" | "error">;
-}
-export declare class BootstrapService {
-    private readonly d;
-    constructor(d: BootstrapServiceDeps);
+    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>;
     /**
@@ -151,26 +181,59 @@ export declare class BootstrapService {
         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;
     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;
 }