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

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { SetupService } from "./admin/setup.service.js";
+export { closeKernelApp, createKernelApp, type KernelAppOptions, kernelAppHttp, kernelAppPort, startKernelApp, } from "./app.js";
 export { type CatalogCli, openCatalogCli } from "./catalog/cli.js";
 export { GitSourceError, type ReadGitTreeOptions, readGitTree, } from "./catalog/git-source.js";
 export type { PluginConfirmResult, PluginReview } from "./catalog/plugin-import.js";
@@ -19,23 +20,23 @@ export { createKv } from "./ctx/kv.js";
 export { createLock } from "./ctx/lock.js";
 export { createQueue } from "./ctx/queue.js";
 export { createKeyring, createSecrets, type DerivedKeys, type Keyring, rewrapDataKeys, } from "./ctx/secrets.js";
-export { type KernelDatabase, type KernelDb, kernelDb } from "./db/kernel-schema.js";
+export { type KernelDatabase, type KernelSchemaDb, kernelDb } from "./db/kernel-schema.js";
 export { type MigrationOwner, migrate } from "./db/migrator.js";
 export { createDb } from "./db/pool.js";
 export { destructiveStatements, isDestructiveBody, isDestructiveSql, type SqlStatement, splitSqlStatements, } from "./db/sql-statements.js";
 export { ApiError, ERROR_CODES, type ErrorCode } from "./errors.js";
-export { ExtensionAdminOps, type ExtensionAdminOpsDeps } from "./extensions/admin-ops.js";
+export { ExtensionAdminOps } from "./extensions/admin-ops.js";
 export { ExtensionAdmin, PLUGINS_CHANGED_TOPIC } from "./extensions/admin-view.js";
 export { type ApprovalDecision, ExtensionApprovals, type PendingExtension, type PermissionSnapshot, planApprovals, snapshotCovers, withPreApproved, } from "./extensions/approvals.js";
 export { blobKey, ExtensionBlobIntegrityError, type ExtensionBlobSource, ExtensionBlobs, } from "./extensions/blobs.js";
-export { BOOTSTRAP_MANIFEST_FILE, type BootstrapEntryResult, BootstrapFailedError, type BootstrapFailure, type BootstrapResolveOptions, type BootstrapResult, BootstrapService, type BootstrapServiceDeps, bootstrapManifestSha256, readBootstrapManifest, resolveBootstrapPackages, } from "./extensions/bootstrap.js";
+export { BOOTSTRAP_MANIFEST_FILE, type BootstrapEntryResult, BootstrapFailedError, type BootstrapFailure, type BootstrapResolveOptions, type BootstrapResult, BootstrapService, bootstrapManifestSha256, readBootstrapManifest, resolveBootstrapPackages, } from "./extensions/bootstrap.js";
 export { type ExtensionCli, openExtensionCli } from "./extensions/cli.js";
 export { DEPLOYMENT_SECRETS_ORG, type DeploymentConfigField, type DeploymentConfigView, ExtensionDeploymentConfigService, mergeDeploymentConfig, PLUGIN_DEPLOYMENT_CONFIG_TOPIC, readStoredDeploymentConfig, } from "./extensions/deployment-config.js";
 export { assertSecretsReachable, ExtensionHost, type ExtensionLoadPlan, type InspectedExtension, type InstalledExtensionLoader, type InstallFailureReason, } from "./extensions/host.js";
 export { ExtensionUnloadedError, type InflightEntry, InflightTracker, PLUGIN_UNLOADED_TOOL_ERROR, type TrackOptions, trackCalls, } from "./extensions/inflight.js";
 export { type DesiredExtension, type ExtensionInstallRow, ExtensionInstalls, type IngestSource, type PackageReview, } from "./extensions/installs.js";
 export { DEFAULT_DISPOSE_TIMEOUT_MS, type DisposeOptions, ExtensionInstance, ImportTracker, type LoadDeps, loadInstance, ManifestMismatchError, type Registration, type RegistrationKind, UPGRADE_WARN_THRESHOLD, } from "./extensions/instance.js";
-export { ExtensionLifecycle, type ExtensionLifecycleDeps, type LifecycleHost, PLUGINS_RECONCILE_JOB, PLUGINS_RECONCILE_TOPIC, } from "./extensions/lifecycle.js";
+export { ExtensionLifecycle, PLUGINS_RECONCILE_JOB, PLUGINS_RECONCILE_TOPIC, } from "./extensions/lifecycle.js";
 export { ensureMigrated, MIGRATE_LOCK_PREFIX, type MigrateLockDeps, PLUGINS_MIGRATED_TOPIC, unrunMigrations, } from "./extensions/migrate-lock.js";
 export { EXTENSION_PACKAGE_LIMITS, type ExtensionPackage, ExtensionPackageError, type ExtensionPackageLimits, type ExtensionPackageSection, extractExtensionPackage, HOST_ZOD_VERSION, permissionSetOfPackage, type ReadExtensionPackageOptions, readExtensionPackage, } from "./extensions/package.js";
 export { blockingKeys, computePermissionSet, diffPermissions, type PermissionSet, permissionKeys, WARNINGS_KEY_PREFIX, } from "./extensions/permission-set.js";
@@ -44,26 +45,30 @@ export { ExtensionRegistry } from "./extensions/registry.js";
 export { ExtensionResolveError, resolveExtensions } from "./extensions/resolve.js";
 export { type ExtensionLoadStatus, type ExtensionSource, newReplicaId, type PendingReason, ReplicaStatusStore, } from "./extensions/sources.js";
 export { syncPackage } from "./extensions/sync.js";
-export { type CreateHttpAppOptions, createHttpApp, type HealthOptions, type KernelHttp, type KernelHttpApp, } from "./http/app.js";
-export { type Account, AccountsService } from "./identity/accounts.js";
+export type { KernelHttp, KernelHttpApp } from "./http/app.js";
+export { type Account, AccountsModule, AccountsService } from "./identity/accounts.js";
 export { type ApiTokenRecord, ApiTokenService } from "./identity/api-tokens.js";
 export { audit } from "./identity/audit.js";
 export { normalizeLogin, validatePassword } from "./identity/login.js";
 export { DUMMY_PASSWORD_HASH, hashPassword, verifyPassword } from "./identity/passwords.js";
 export { type IssuedSession, REFRESH_RACE_GRACE_MS, SessionService, } from "./identity/sessions.js";
 export { DEPLOYMENT_SETTINGS, type DeploymentSettings, SettingsService, } from "./identity/settings.js";
-export { createKernel, KERNEL_MIGRATIONS_DIR, KERNEL_SCHEMA, type Kernel, type KernelOptions, type KernelRuns, migrateAll, } from "./kernel.js";
+export { type KernelCliOptions, openKernelCli, openKernelCliOverPool, } from "./infra/cli/kernel-cli.module.js";
+export { GUARD_CIRCUIT_LIMIT, GUARD_CIRCUIT_WINDOW_MS, installProcessGuards, type ProcessGuardDeps, } from "./infra/lifecycle/process-guards.js";
+export { handleShutdownSignals, type ShutdownSignalHandle, type ShutdownSignalOptions, } from "./infra/lifecycle/shutdown-signals.js";
+export { KERNEL_MIGRATIONS_DIR, KERNEL_SCHEMA, migrateAll } from "./kernel.js";
 export { createLogger, type KernelLogger, LOG_FORMATS, LOG_LEVELS, type LogFormat, type LoggerOptions, type LogLevel, type LogOutput, } from "./log.js";
 export { createConfiguredLogger, loggerOptionsFromConfig } from "./log-config.js";
 export { type ContextJob, type JobWrapper, type LogContext, logContext, setJobWrapper, setTraceContextSource, withJobContext, withLogContext, } from "./log-context.js";
 export { type Org, OrgsService } from "./orgs/orgs.service.js";
+export type { KernelOverride } from "./overrides.js";
 export { fetchNpmPackage, IntegrityMismatchError, type NpmFetchConfig, NpmFetchError, PackageTooLargeError, } from "./packages/npm.js";
 export { UNKNOWN_RESULT_TEXT } from "./runtime/context/pairing.js";
 export type { AgentLoop, LoopContext, LoopOutcome } from "./runtime/loop.js";
-export { MAINTENANCE_QUEUE_NAME } from "./runtime/maintenance.js";
+export { MAINTENANCE_QUEUE_NAME } from "./runtime/maintenance-queue.js";
 export { runJobId } from "./runtime/run-queue.js";
-export { SANDBOX_DESTROY_JOB, SANDBOX_SUSPEND_JOB, } from "./sandbox/lifecycle.js";
-export { SANDBOX_LOCK_TTL_MS, SandboxService, type SandboxServiceDeps, type SandboxUseInfo, } from "./sandbox/sandbox.service.js";
+export { SANDBOX_DESTROY_JOB, SANDBOX_SUSPEND_JOB, } from "./sandbox/jobs.js";
+export { SANDBOX_LOCK_TTL_MS, SandboxService, type SandboxUseInfo, } from "./sandbox/sandbox.service.js";
 export { MAX_STORAGE_KEY_BYTES, StorageKeyError, } from "./storage/prefix.js";
-export { StorageService, type StorageServiceDeps } from "./storage/storage.service.js";
+export { PrefixedStorage, StorageService, type StorageSource, } from "./storage/storage.service.js";
 export { SANDBOX_RECREATED_NOTICE, SANDBOX_STARTED_NOTICE, } from "./tools/builtins/sandbox/common.js";

package/dist/index.js

@@ -1,4 +1,5 @@
 export { SetupService } from "./admin/setup.service.js";
+export { closeKernelApp, createKernelApp, kernelAppHttp, kernelAppPort, startKernelApp, } from "./app.js";
 export { openCatalogCli } from "./catalog/cli.js";
 // The git reader marketplaces use; core's check:bootstrap reads the official marketplace with it.
 export { GitSourceError, readGitTree, } from "./catalog/git-source.js";
@@ -43,25 +44,27 @@ export { ExtensionRegistry } from "./extensions/registry.js";
 export { ExtensionResolveError, resolveExtensions } from "./extensions/resolve.js";
 export { newReplicaId, ReplicaStatusStore, } from "./extensions/sources.js";
 export { syncPackage } from "./extensions/sync.js";
-export { createHttpApp, } from "./http/app.js";
-export { AccountsService } from "./identity/accounts.js";
+export { AccountsModule, AccountsService } from "./identity/accounts.js";
 export { ApiTokenService } from "./identity/api-tokens.js";
 export { audit } from "./identity/audit.js";
 export { normalizeLogin, validatePassword } from "./identity/login.js";
 export { DUMMY_PASSWORD_HASH, hashPassword, verifyPassword } from "./identity/passwords.js";
 export { REFRESH_RACE_GRACE_MS, SessionService, } from "./identity/sessions.js";
 export { DEPLOYMENT_SETTINGS, SettingsService, } from "./identity/settings.js";
-export { createKernel, KERNEL_MIGRATIONS_DIR, KERNEL_SCHEMA, migrateAll, } from "./kernel.js";
+export { openKernelCli, openKernelCliOverPool, } from "./infra/cli/kernel-cli.module.js";
+export { GUARD_CIRCUIT_LIMIT, GUARD_CIRCUIT_WINDOW_MS, installProcessGuards, } from "./infra/lifecycle/process-guards.js";
+export { handleShutdownSignals, } from "./infra/lifecycle/shutdown-signals.js";
+export { KERNEL_MIGRATIONS_DIR, KERNEL_SCHEMA, migrateAll } from "./kernel.js";
 export { createLogger, LOG_FORMATS, LOG_LEVELS, } from "./log.js";
 export { createConfiguredLogger, loggerOptionsFromConfig } from "./log-config.js";
 export { logContext, setJobWrapper, setTraceContextSource, withJobContext, withLogContext, } from "./log-context.js";
 export { OrgsService } from "./orgs/orgs.service.js";
 export { fetchNpmPackage, IntegrityMismatchError, NpmFetchError, PackageTooLargeError, } from "./packages/npm.js";
 export { UNKNOWN_RESULT_TEXT } from "./runtime/context/pairing.js";
-export { MAINTENANCE_QUEUE_NAME } from "./runtime/maintenance.js";
+export { MAINTENANCE_QUEUE_NAME } from "./runtime/maintenance-queue.js";
 export { runJobId } from "./runtime/run-queue.js";
-export { SANDBOX_DESTROY_JOB, SANDBOX_SUSPEND_JOB, } from "./sandbox/lifecycle.js";
+export { SANDBOX_DESTROY_JOB, SANDBOX_SUSPEND_JOB, } from "./sandbox/jobs.js";
 export { SANDBOX_LOCK_TTL_MS, SandboxService, } from "./sandbox/sandbox.service.js";
 export { MAX_STORAGE_KEY_BYTES, StorageKeyError, } from "./storage/prefix.js";
-export { StorageService } from "./storage/storage.service.js";
+export { PrefixedStorage, StorageService, } from "./storage/storage.service.js";
 export { SANDBOX_RECREATED_NOTICE, SANDBOX_STARTED_NOTICE, } from "./tools/builtins/sandbox/common.js";

package/dist/infra/cache/cache.module.d.ts

@@ -0,0 +1,3 @@
+/** Global: `CacheService` (and the `@Cacheable` / `@CacheEvict` decorators, which read it from `this.cacheService`). */
+export declare class CacheModule {
+}

package/dist/infra/cache/cache.module.js

@@ -0,0 +1,16 @@
+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;
+};
+import { Global, Module } from "@nestjs/common";
+import { CacheService } from "./cache.service.js";
+/** Global: `CacheService` (and the `@Cacheable` / `@CacheEvict` decorators, which read it from `this.cacheService`). */
+let CacheModule = class CacheModule {
+};
+CacheModule = __decorate([
+    Global(),
+    Module({ providers: [CacheService], exports: [CacheService] })
+], CacheModule);
+export { CacheModule };

package/dist/infra/cache/cache.service.d.ts

@@ -0,0 +1,21 @@
+import type { Redis } from "ioredis";
+import type { KernelLogger } from "../../log.js";
+/** Stored instead of a value when a method returned null and `cacheNull` is set. */
+export declare const CACHE_NULL_SENTINEL = "__CACHE_NULL__";
+/**
+ * Redis access of `@Cacheable` / `@CacheEvict`. Every operation fails open: a Redis error is
+ * logged at warn and behaves like a miss (read) or a no-op (write, delete); it never throws.
+ */
+export declare class CacheService {
+    private readonly redis;
+    private readonly log;
+    constructor(redis: Redis, log: KernelLogger);
+    /** The raw stored string under `cache:<key>`, or undefined on a miss or a Redis error. */
+    get(key: string): Promise<string | undefined>;
+    /** Stores `value` under `cache:<key>` with a TTL in seconds. */
+    set(key: string, value: string, ttlSeconds: number): Promise<void>;
+    /** Like `set`, serializing `value` as JSON; an unserializable value (bigint, cycle) is not cached. */
+    setJson(key: string, value: unknown, ttlSeconds: number): Promise<void>;
+    /** Deletes `cache:<key>`. */
+    del(key: string): Promise<void>;
+}

package/dist/infra/cache/cache.service.js

@@ -0,0 +1,80 @@
+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); }
+};
+// Ported from octok-platform libs/common/src/cache/cacheable.decorator.ts (owner-approved, 2026-10-28).
+// Adapted: an injectable service over the shared Redis connection that fails open.
+import { Inject, Injectable } from "@nestjs/common";
+import { KERNEL_LOGGER, REDIS } from "../tokens.js";
+/** Stored instead of a value when a method returned null and `cacheNull` is set. */
+export const CACHE_NULL_SENTINEL = "__CACHE_NULL__";
+const prefixed = (key) => (key.startsWith("cache:") ? key : `cache:${key}`);
+/**
+ * Redis access of `@Cacheable` / `@CacheEvict`. Every operation fails open: a Redis error is
+ * logged at warn and behaves like a miss (read) or a no-op (write, delete); it never throws.
+ */
+let CacheService = class CacheService {
+    redis;
+    log;
+    constructor(redis, log) {
+        this.redis = redis;
+        this.log = log;
+    }
+    /** The raw stored string under `cache:<key>`, or undefined on a miss or a Redis error. */
+    async get(key) {
+        const cacheKey = prefixed(key);
+        try {
+            return (await this.redis.get(cacheKey)) ?? undefined;
+        }
+        catch (err) {
+            this.log.warn("cache read failed, calling through", { cacheKey, err });
+            return undefined;
+        }
+    }
+    /** Stores `value` under `cache:<key>` with a TTL in seconds. */
+    async set(key, value, ttlSeconds) {
+        const cacheKey = prefixed(key);
+        try {
+            await this.redis.set(cacheKey, value, "EX", ttlSeconds);
+        }
+        catch (err) {
+            this.log.warn("cache write failed, result not cached", { cacheKey, err });
+        }
+    }
+    /** Like `set`, serializing `value` as JSON; an unserializable value (bigint, cycle) is not cached. */
+    async setJson(key, value, ttlSeconds) {
+        let json;
+        try {
+            json = JSON.stringify(value);
+        }
+        catch (err) {
+            this.log.warn("cache value not serializable, result not cached", {
+                cacheKey: prefixed(key),
+                err,
+            });
+            return;
+        }
+        await this.set(key, json, ttlSeconds);
+    }
+    /** Deletes `cache:<key>`. */
+    async del(key) {
+        const cacheKey = prefixed(key);
+        try {
+            await this.redis.del(cacheKey);
+        }
+        catch (err) {
+            this.log.warn("cache eviction failed", { cacheKey, err });
+        }
+    }
+};
+CacheService = __decorate([
+    Injectable(),
+    __param(0, Inject(REDIS)),
+    __param(1, Inject(KERNEL_LOGGER))
+], CacheService);
+export { CacheService };

package/dist/infra/cache/cacheable.decorator.d.ts

@@ -0,0 +1,32 @@
+export interface CacheableOptions {
+    /**
+     * Cache key; `cache:` is prepended unless present. Placeholders expand from the method
+     * arguments: `#{0}`, `#{1.book.title}`, `#{user.id}` (= `#{0.user.id}`).
+     */
+    key: string;
+    /** Lifetime in seconds (default 300). */
+    ttl?: number;
+    /** Also cache a null / undefined result, as a sentinel (default false). */
+    cacheNull?: boolean;
+}
+/**
+ * Method decorator: caches the JSON-serializable result in Redis (like Spring's `@Cacheable`).
+ * A hit returns the parsed value without calling the method; Redis errors call the method. Inside a
+ * transaction the cache is bypassed (neither read nor written): the method may read rows the
+ * transaction wrote, which other callers must not see before the commit, or a cached value older
+ * than them. The class must inject `@Inject(CacheService) readonly cacheService: CacheService`.
+ */
+export declare function Cacheable(options: CacheableOptions): (_target: object, _key: string | symbol, descriptor: PropertyDescriptor) => PropertyDescriptor;
+export interface CacheEvictOptions {
+    /** One key to evict (same placeholders as `@Cacheable`). */
+    key?: string;
+    /** Several keys; `#{result}` / `#{result.id}` read the method's return value. */
+    keys?: string[];
+}
+/**
+ * Method decorator: evicts cache keys after the method succeeded (nothing is evicted when it
+ * throws). Inside a transaction the keys are evicted after its COMMIT (`afterCommit`; nothing on a
+ * rollback): evicted earlier, a reader could cache the old rows again before the commit. The class
+ * must inject `@Inject(CacheService) readonly cacheService: CacheService`.
+ */
+export declare function CacheEvict(options: CacheEvictOptions): (_target: object, _key: string | symbol, descriptor: PropertyDescriptor) => PropertyDescriptor;

package/dist/infra/cache/cacheable.decorator.js

@@ -0,0 +1,83 @@
+// Ported from octok-platform libs/common/src/cache/cacheable.decorator.ts (owner-approved, 2026-10-28).
+// Adapted: the CacheService comes from the `cacheService` property, as `@Transactional` reads
+// `txHost` and `@WithLock` reads `lockService`; Redis errors fail open (see CacheService).
+import { afterCommit } from "../database/after-commit.js";
+import { currentStore } from "../database/transaction-host.js";
+import { generateKey } from "../lock/key-template.js";
+import { CACHE_NULL_SENTINEL } from "./cache.service.js";
+function serviceOf(self, decorator) {
+    if (!self.cacheService) {
+        throw new Error(`${decorator}() needs the class to inject \`CacheService\` as \`cacheService\` ` +
+            "(`@Inject(CacheService) readonly cacheService: CacheService`).");
+    }
+    return self.cacheService;
+}
+/**
+ * Method decorator: caches the JSON-serializable result in Redis (like Spring's `@Cacheable`).
+ * A hit returns the parsed value without calling the method; Redis errors call the method. Inside a
+ * transaction the cache is bypassed (neither read nor written): the method may read rows the
+ * transaction wrote, which other callers must not see before the commit, or a cached value older
+ * than them. The class must inject `@Inject(CacheService) readonly cacheService: CacheService`.
+ */
+export function Cacheable(options) {
+    return (_target, _key, descriptor) => {
+        const original = descriptor.value;
+        descriptor.value = async function (...args) {
+            const cache = serviceOf(this, "@Cacheable");
+            if (currentStore())
+                return original.apply(this, args);
+            const key = generateKey(options.key, args);
+            const cached = await cache.get(key);
+            if (cached === CACHE_NULL_SENTINEL && options.cacheNull)
+                return null;
+            if (cached !== undefined && cached !== CACHE_NULL_SENTINEL) {
+                try {
+                    return JSON.parse(cached);
+                }
+                catch {
+                    // An unreadable entry is a miss; it is overwritten below.
+                }
+            }
+            const result = await original.apply(this, args);
+            const ttl = options.ttl ?? 300;
+            if (result == null) {
+                if (options.cacheNull) {
+                    await cache.set(key, CACHE_NULL_SENTINEL, ttl);
+                    // A hit returns null, so a miss returns null too (never undefined).
+                    return null;
+                }
+            }
+            else {
+                await cache.setJson(key, result, ttl);
+            }
+            return result;
+        };
+        return descriptor;
+    };
+}
+/**
+ * Method decorator: evicts cache keys after the method succeeded (nothing is evicted when it
+ * throws). Inside a transaction the keys are evicted after its COMMIT (`afterCommit`; nothing on a
+ * rollback): evicted earlier, a reader could cache the old rows again before the commit. The class
+ * must inject `@Inject(CacheService) readonly cacheService: CacheService`.
+ */
+export function CacheEvict(options) {
+    return (_target, _key, descriptor) => {
+        const original = descriptor.value;
+        descriptor.value = async function (...args) {
+            const cache = serviceOf(this, "@CacheEvict");
+            const result = await original.apply(this, args);
+            const patterns = options.keys ?? (options.key ? [options.key] : []);
+            const evict = async () => {
+                for (const pattern of patterns)
+                    await cache.del(generateKey(pattern, args, { result }));
+            };
+            if (currentStore())
+                afterCommit(evict);
+            else
+                await evict();
+            return result;
+        };
+        return descriptor;
+    };
+}

package/dist/infra/cli/kernel-cli.module.d.ts

@@ -0,0 +1,66 @@
+import { type DynamicModule, type INestApplicationContext, type OnApplicationShutdown, type Type } from "@nestjs/common";
+import { Redis } from "ioredis";
+import type { Kysely } from "kysely";
+import type { KernelConfig } from "../../config/schema.js";
+import type { KernelLogger } from "../../log.js";
+/** Closes the CLI's Redis connection with the context. */
+export declare class CliRedisLifecycle implements OnApplicationShutdown {
+    private readonly redis;
+    constructor(redis: Redis);
+    onApplicationShutdown(): void;
+}
+/**
+ * The CLI's Redis: one lazy connection (a command that never touches Redis never connects), which
+ * keeps reconnecting while each command on a broken connection fails fast, and the publish-only
+ * kernel bus over it (`capybara extensions *` publish `kernel.plugins.changed`; the bootstrap step
+ * takes `lock:bootstrap`).
+ */
+export declare class CliRedisModule {
+}
+export interface KernelCliOptions {
+    logger: KernelLogger;
+    /** Environment overrides (default `process.env`). */
+    env?: NodeJS.ProcessEnv;
+    /** The directory bare extension package names are resolved from. */
+    resolveFrom?: string;
+    /** The domain modules the command needs. */
+    modules: (Type | DynamicModule)[];
+    /**
+     * Whether the context has the CLI's Redis (connection, publish-only bus) and `LockService`
+     * (default true). `false` for the commands that only use PostgreSQL (`admin create`,
+     * `admin grant`): their context cannot reach Redis at all.
+     */
+    redis?: boolean;
+}
+/**
+ * The application context of a CLI command (decision R13 of the Nest kernel spec): the config
+ * loaded once (no watch), the logger, the database, the CLI's Redis, locks and in-process events,
+ * plus only the domain modules the command needs. Open it with {@link openKernelCli} and close it
+ * at the end of the command.
+ */
+export declare class KernelCliModule {
+    static forRoot(config: KernelConfig, opts: KernelCliOptions): DynamicModule;
+    /**
+     * A context over a pool the caller owns, for code that has a pool and no config
+     * (`@capybara-hq/testing`'s `createLocalAccount`): the logger, the database handles over `pool`
+     * (never closed by the context), in-process events and the given modules. No config, no keyring,
+     * no Redis: only modules that need nothing more fit.
+     */
+    static overPool(pool: Kysely<any>, opts: {
+        logger: KernelLogger;
+        modules: (Type | DynamicModule)[];
+    }): DynamicModule;
+}
+/**
+ * Opens a CLI command's application context ({@link KernelCliModule.forRoot}); the caller closes
+ * it (`app.close()`: the pool, and the Redis connection when the context has one).
+ */
+export declare function openKernelCli(config: KernelConfig, opts: KernelCliOptions): Promise<INestApplicationContext>;
+/**
+ * Opens a context over a pool the caller owns ({@link KernelCliModule.overPool}); closing it
+ * leaves the pool open.
+ */
+export declare function openKernelCliOverPool(pool: Kysely<any>, opts: {
+    logger: KernelLogger;
+    modules: (Type | DynamicModule)[];
+}): Promise<INestApplicationContext>;

package/dist/infra/cli/kernel-cli.module.js

@@ -0,0 +1,165 @@
+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); }
+};
+var KernelCliModule_1;
+import { Global, Inject, Injectable, Module, } from "@nestjs/common";
+import { NestFactory } from "@nestjs/core";
+import { Redis } from "ioredis";
+import { createBus } from "../../ctx/bus.js";
+import { KERNEL_APP_OPTIONS } from "../../lifecycle/tokens.js";
+import { ConfigModule } from "../config/config.module.js";
+import { KernelConfigService } from "../config/kernel-config.service.js";
+import { DatabaseModule } from "../database/database.module.js";
+import { KernelEventsModule } from "../events/kernel-events.js";
+import { GracefulShutdownModule } from "../lifecycle/graceful-shutdown.module.js";
+import { LockModule } from "../lock/lock.module.js";
+import { LoggingModule } from "../logging/logging.module.js";
+import { KERNEL_BUS, KERNEL_LOGGER, REDIS, REDIS_SUBSCRIBER } from "../tokens.js";
+/** How long the CLI's Redis connection may take before a command fails (a publish only warns). */
+const CLI_REDIS_CONNECT_TIMEOUT_MS = 3_000;
+/**
+ * The cap of the reconnect backoff. The connection keeps reconnecting (a `capybara bootstrap`
+ * holding `lock:bootstrap` renews it again once Redis is back), while a command issued on a broken
+ * connection still fails after one reconnect attempt (`maxRetriesPerRequest: 1`).
+ */
+const CLI_REDIS_MAX_BACKOFF_MS = 2_000;
+/** The CLI subscribes to nothing: the kernel bus is publish-only there. */
+const NO_SUBSCRIBER = {
+    subscribe: () => Promise.reject(new Error("the CLI does not subscribe")),
+};
+/** Closes the CLI's Redis connection with the context. */
+let CliRedisLifecycle = class CliRedisLifecycle {
+    redis;
+    constructor(redis) {
+        this.redis = redis;
+    }
+    onApplicationShutdown() {
+        this.redis.disconnect();
+    }
+};
+CliRedisLifecycle = __decorate([
+    Injectable(),
+    __param(0, Inject(REDIS))
+], CliRedisLifecycle);
+export { CliRedisLifecycle };
+/**
+ * The CLI's Redis: one lazy connection (a command that never touches Redis never connects), which
+ * keeps reconnecting while each command on a broken connection fails fast, and the publish-only
+ * kernel bus over it (`capybara extensions *` publish `kernel.plugins.changed`; the bootstrap step
+ * takes `lock:bootstrap`).
+ */
+let CliRedisModule = class CliRedisModule {
+};
+CliRedisModule = __decorate([
+    Global(),
+    Module({
+        providers: [
+            {
+                provide: REDIS,
+                inject: [KernelConfigService],
+                useFactory: (config) => {
+                    const redis = new Redis(config.get().redis.url, {
+                        lazyConnect: true,
+                        connectTimeout: CLI_REDIS_CONNECT_TIMEOUT_MS,
+                        maxRetriesPerRequest: 1,
+                        retryStrategy: (times) => Math.min(times * 200, CLI_REDIS_MAX_BACKOFF_MS),
+                    });
+                    // a failed publish or lock surfaces where it is used; the CLI's output stays clean
+                    redis.on("error", () => { });
+                    return redis;
+                },
+            },
+            { provide: REDIS_SUBSCRIBER, useValue: NO_SUBSCRIBER },
+            {
+                provide: KERNEL_BUS,
+                inject: [REDIS, KERNEL_LOGGER],
+                useFactory: (redis, log) => createBus(redis, NO_SUBSCRIBER, "kernel", log),
+            },
+            CliRedisLifecycle,
+        ],
+        exports: [REDIS, REDIS_SUBSCRIBER, KERNEL_BUS],
+    })
+], CliRedisModule);
+export { CliRedisModule };
+/**
+ * The application context of a CLI command (decision R13 of the Nest kernel spec): the config
+ * loaded once (no watch), the logger, the database, the CLI's Redis, locks and in-process events,
+ * plus only the domain modules the command needs. Open it with {@link openKernelCli} and close it
+ * at the end of the command.
+ */
+let KernelCliModule = KernelCliModule_1 = class KernelCliModule {
+    static forRoot(config, opts) {
+        const appOptions = {
+            logger: opts.logger,
+            ...(opts.env !== undefined && { env: opts.env }),
+            ...(opts.resolveFrom !== undefined && { resolveFrom: opts.resolveFrom }),
+        };
+        return {
+            module: KernelCliModule_1,
+            global: true,
+            imports: [
+                LoggingModule.forRoot(config, { logger: opts.logger }),
+                ConfigModule.forRoot(config, opts.env !== undefined ? { env: opts.env } : {}),
+                GracefulShutdownModule,
+                DatabaseModule.forRoot(),
+                ...(opts.redis === false ? [] : [CliRedisModule, LockModule]),
+                KernelEventsModule,
+                ...opts.modules,
+            ],
+            providers: [{ provide: KERNEL_APP_OPTIONS, useValue: appOptions }],
+            exports: [KERNEL_APP_OPTIONS],
+        };
+    }
+    /**
+     * A context over a pool the caller owns, for code that has a pool and no config
+     * (`@capybara-hq/testing`'s `createLocalAccount`): the logger, the database handles over `pool`
+     * (never closed by the context), in-process events and the given modules. No config, no keyring,
+     * no Redis: only modules that need nothing more fit.
+     */
+    static overPool(
+    // biome-ignore lint/suspicious/noExplicitAny: the pool carries no schema types
+    pool, opts) {
+        return {
+            module: KernelCliModule_1,
+            global: true,
+            imports: [
+                LoggingModule.forLogger(opts.logger),
+                DatabaseModule.borrowing(pool),
+                KernelEventsModule,
+                ...opts.modules,
+            ],
+        };
+    }
+};
+KernelCliModule = KernelCliModule_1 = __decorate([
+    Global(),
+    Module({})
+    // biome-ignore lint/complexity/noStaticOnlyClass: a Nest dynamic module
+], KernelCliModule);
+export { KernelCliModule };
+/** Creates a Nest application context of `module` the way every CLI context is created. */
+function createCliContext(module) {
+    return NestFactory.createApplicationContext(module, { logger: false, abortOnError: false });
+}
+/**
+ * Opens a CLI command's application context ({@link KernelCliModule.forRoot}); the caller closes
+ * it (`app.close()`: the pool, and the Redis connection when the context has one).
+ */
+export function openKernelCli(config, opts) {
+    return createCliContext(KernelCliModule.forRoot(config, opts));
+}
+/**
+ * Opens a context over a pool the caller owns ({@link KernelCliModule.overPool}); closing it
+ * leaves the pool open.
+ */
+export function openKernelCliOverPool(
+// biome-ignore lint/suspicious/noExplicitAny: the pool carries no schema types
+pool, opts) {
+    return createCliContext(KernelCliModule.overPool(pool, opts));
+}

package/dist/infra/close-within.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Waits for `p` at most `ms`: resolves true when it resolved in time, false when the time ran out
+ * (`p` keeps running; nothing is aborted). A rejection of `p` in time is thrown. The one "wait at
+ * most N ms" of the kernel's stop path.
+ */
+export declare function waitWithin(p: Promise<unknown>, ms: number): Promise<boolean>;
+/**
+ * Waits for an infra resource to close at shutdown (the bus subscriber, Redis, the pool) at most
+ * `budgetMs`, the share of the total stop budget left (`GracefulShutdown.remainingMs()`): a close
+ * that does not finish in time (Redis unreachable, a client never released) is abandoned with a
+ * warning, so the shutdown never hangs on it. Resolves true when `p` settled successfully in time.
+ */
+export declare function closeWithin(label: string, p: Promise<unknown>, budgetMs: number, log: {
+    warn(msg: string, fields?: Record<string, unknown>): void;
+}): Promise<boolean>;

package/dist/infra/close-within.js

@@ -0,0 +1,36 @@
+/**
+ * Waits for `p` at most `ms`: resolves true when it resolved in time, false when the time ran out
+ * (`p` keeps running; nothing is aborted). A rejection of `p` in time is thrown. The one "wait at
+ * most N ms" of the kernel's stop path.
+ */
+export async function waitWithin(p, ms) {
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(false), Math.max(0, ms));
+        timer.unref();
+    });
+    try {
+        return await Promise.race([p.then(() => true), timeout]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Waits for an infra resource to close at shutdown (the bus subscriber, Redis, the pool) at most
+ * `budgetMs`, the share of the total stop budget left (`GracefulShutdown.remainingMs()`): a close
+ * that does not finish in time (Redis unreachable, a client never released) is abandoned with a
+ * warning, so the shutdown never hangs on it. Resolves true when `p` settled successfully in time.
+ */
+export async function closeWithin(label, p, budgetMs, log) {
+    try {
+        const done = await waitWithin(p, budgetMs);
+        if (!done)
+            log.warn("shutdown step timed out", { step: label });
+        return done;
+    }
+    catch (err) {
+        log.warn("shutdown step failed", { step: label, err });
+        return false;
+    }
+}