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

package/dist/infra/database/xact-lock.d.ts

@@ -0,0 +1,17 @@
+import { KernelDb } from "./kernel-db.js";
+import { TransactionHost } from "./transaction-host.js";
+/**
+ * Transaction-scoped advisory locks (decision R9 of the Nest kernel spec): `pg_advisory_xact_lock`
+ * is transaction semantics, like `FOR UPDATE`. It is held by the caller's transaction and released
+ * at its COMMIT or ROLLBACK, so it serializes writers whose invariant is checked inside that same
+ * transaction ("never zero active enterprise admins", "set up once", "one account per external
+ * identity"). The one place that takes such a lock; `propagation: "mandatory"` makes a call outside
+ * a transaction (where the lock would be released at once) throw.
+ */
+export declare class XactLock {
+    private readonly db;
+    readonly txHost: TransactionHost;
+    constructor(db: KernelDb, txHost: TransactionHost);
+    /** Takes the lock named `key` until the caller's transaction ends (waits while another holds it). */
+    lock(key: string): Promise<void>;
+}

package/dist/infra/database/xact-lock.js

@@ -0,0 +1,43 @@
+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 { Inject, Injectable } from "@nestjs/common";
+import { sql } from "kysely";
+import { KernelDb } from "./kernel-db.js";
+import { TransactionHost } from "./transaction-host.js";
+import { Transactional } from "./transactional.decorator.js";
+/**
+ * Transaction-scoped advisory locks (decision R9 of the Nest kernel spec): `pg_advisory_xact_lock`
+ * is transaction semantics, like `FOR UPDATE`. It is held by the caller's transaction and released
+ * at its COMMIT or ROLLBACK, so it serializes writers whose invariant is checked inside that same
+ * transaction ("never zero active enterprise admins", "set up once", "one account per external
+ * identity"). The one place that takes such a lock; `propagation: "mandatory"` makes a call outside
+ * a transaction (where the lock would be released at once) throw.
+ */
+let XactLock = class XactLock {
+    db;
+    txHost;
+    constructor(db, txHost) {
+        this.db = db;
+        this.txHost = txHost;
+    }
+    /** Takes the lock named `key` until the caller's transaction ends (waits while another holds it). */
+    async lock(key) {
+        await sql `SELECT pg_advisory_xact_lock(hashtext(${key}))`.execute(this.db.db);
+    }
+};
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], XactLock.prototype, "lock", null);
+XactLock = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(TransactionHost))
+], XactLock);
+export { XactLock };

package/dist/infra/events/kernel-events.d.ts

@@ -0,0 +1,96 @@
+import type { KernelLogger } from "../../log.js";
+/**
+ * The kernel's in-process domain events (nest kernel spec §3b): a domain announces what happened,
+ * and another domain reacts without the first depending on it. Same-process only, so only for
+ * notifications that may be lost and are re-derived elsewhere; anything that must reach every
+ * replica goes over the kernel bus (`KERNEL_BUS`).
+ */
+export interface KernelEventMap {
+    /**
+     * An organization was soft-deleted (after the commit). Channel connections drop their long
+     * connections (the connection reads also filter deleted orgs, so a lost event only delays it).
+     */
+    "org.deleted": {
+        orgId: string;
+    };
+    /**
+     * An organization disabled an extension (after the commit). Its channel connections in the org
+     * drop their long connections at once (the supervisor's periodic re-check is the fallback).
+     */
+    "extension.org-disabled": {
+        orgId: string;
+        plugin: string;
+    };
+    /**
+     * A person decided a tool call approval (after the commit, exactly once: only the decision that
+     * changed it from pending). The run's waits resume it and its IM delivery is enqueued; a lost
+     * event is re-derived by the wait sweep (runs waiting on a decided approval are resumed).
+     */
+    "approval.decided": {
+        id: string;
+        orgId: string;
+        conversationId: string;
+        runId: string;
+        status: "approved" | "denied";
+    };
+    /**
+     * A person answered a tool call's input request (after the commit, exactly once). Same
+     * consumers and the same re-derivation as `approval.decided`.
+     */
+    "question.answered": {
+        id: string;
+        orgId: string;
+        conversationId: string;
+        runId: string;
+    };
+    /**
+     * EventAppended: a conversation's event log advanced to `toSeq` (after the commit, from
+     * `EventLog.notify`, right after the bus publish). The channel outbound delivery enqueues a job
+     * for a conversation with an IM target; a lost event is re-derived by the next append's (and the
+     * finished delivery job re-checks the log for content it has not delivered).
+     */
+    "conversation.event-appended": {
+        conversationId: string;
+        toSeq: number;
+    };
+    /**
+     * A run started executing on this replica (its first start, a resume, or a takeover after a
+     * stall), after it took the conversation lock and an org quota slot. The channel outbound
+     * enqueues the conversation's IM delivery; a lost event is re-derived by the run's next append.
+     */
+    "run.started": {
+        conversationId: string;
+        runId: string;
+    };
+    /**
+     * A stop of a run waiting on a person was handled (`RunControl.abortWaiting`, whether or not it
+     * still waited): its approval and question cards change, so the channel outbound enqueues the
+     * conversation's IM delivery (re-derived by the next append when lost).
+     */
+    "run.wait-stopped": {
+        conversationId: string;
+        runId: string;
+    };
+    /**
+     * `ensureRun` marked an orphaned run failed (after the commit): the waits stop its active
+     * sub-agents at once. A lost event is repaired by the wait sweep (children of finished runs).
+     */
+    "run.orphaned": {
+        runId: string;
+    };
+}
+type Handler<K extends keyof KernelEventMap> = (payload: KernelEventMap[K]) => Promise<void> | void;
+/** Typed in-process event emitter; handlers run in order, a failing one is logged and skipped. */
+export declare class KernelEvents {
+    private readonly log;
+    private readonly handlers;
+    constructor(log: Pick<KernelLogger, "warn">);
+    /** Subscribes; returns the unsubscribe function. */
+    on<K extends keyof KernelEventMap>(event: K, handler: Handler<K>): () => void;
+    /** Runs every handler of `event` and waits for them. */
+    emit<K extends keyof KernelEventMap>(event: K, payload: KernelEventMap[K]): Promise<void>;
+}
+/** Global: the one {@link KernelEvents}. */
+export declare class KernelEventsModule {
+}
+export {};

package/dist/infra/events/kernel-events.js

@@ -0,0 +1,65 @@
+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 { Global, Inject, Injectable, Module } from "@nestjs/common";
+import { KERNEL_LOGGER } from "../tokens.js";
+/** The payload's id for the failure log (`approvalId` / `questionId`, as the old hooks logged). */
+function idFields(event, payload) {
+    const id = payload.id;
+    if (typeof id !== "string")
+        return {};
+    if (event === "approval.decided")
+        return { approvalId: id };
+    if (event === "question.answered")
+        return { questionId: id };
+    return { id };
+}
+/** Typed in-process event emitter; handlers run in order, a failing one is logged and skipped. */
+let KernelEvents = class KernelEvents {
+    log;
+    handlers = new Map();
+    constructor(log) {
+        this.log = log;
+    }
+    /** Subscribes; returns the unsubscribe function. */
+    on(event, handler) {
+        const list = this.handlers.get(event) ?? [];
+        list.push(handler);
+        this.handlers.set(event, list);
+        return () => {
+            const at = list.indexOf(handler);
+            if (at >= 0)
+                list.splice(at, 1);
+        };
+    }
+    /** Runs every handler of `event` and waits for them. */
+    async emit(event, payload) {
+        for (const h of [...(this.handlers.get(event) ?? [])]) {
+            try {
+                await h(payload);
+            }
+            catch (err) {
+                this.log.warn("kernel event handler failed", { event, ...idFields(event, payload), err });
+            }
+        }
+    }
+};
+KernelEvents = __decorate([
+    Injectable(),
+    __param(0, Inject(KERNEL_LOGGER))
+], KernelEvents);
+export { KernelEvents };
+/** Global: the one {@link KernelEvents}. */
+let KernelEventsModule = class KernelEventsModule {
+};
+KernelEventsModule = __decorate([
+    Global(),
+    Module({ providers: [KernelEvents], exports: [KernelEvents] })
+], KernelEventsModule);
+export { KernelEventsModule };

package/dist/infra/health/health.controller.d.ts

@@ -0,0 +1,26 @@
+import type { Logger } from "@capybara-hq/plugin-sdk";
+import { HealthCheckService, HealthIndicatorService } from "@nestjs/terminus";
+import type { FastifyReply } from "fastify";
+import { type ReadinessCheck } from "./health.options.js";
+import { type ShutdownState } from "./shutdown-state.js";
+/** A dependency that hangs (Redis reconnecting, commands in the offline queue) must still give 503 fast. */
+export declare const CHECK_TIMEOUT_MS = 2000;
+/**
+ * `GET /healthz` (process alive, always 200) and `GET /readyz` (dependencies ready).
+ * The readyz body only names each check as `"ok"` / `"error"`; the failure reason goes to the log
+ * (redacted) and never into the response: driver errors can carry connection strings. Once a stop
+ * has begun readyz answers 503 at once and runs no check. `@Public()`: the global auth guard
+ * applies here too when the kernel API is mounted.
+ */
+export declare class HealthController {
+    private readonly health;
+    private readonly indicators;
+    private readonly checks;
+    private readonly shutdown;
+    private readonly log;
+    constructor(health: HealthCheckService, indicators: HealthIndicatorService, checks: Record<string, ReadinessCheck>, shutdown: ShutdownState, log: Logger);
+    healthz(): {
+        ok: true;
+    };
+    readyz(reply: FastifyReply): Promise<Record<string, unknown>>;
+}

package/dist/infra/health/health.controller.js

@@ -0,0 +1,104 @@
+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 { Controller, Get, Inject, Res } from "@nestjs/common";
+import { HealthCheckService, HealthIndicatorService, } from "@nestjs/terminus";
+import { Public } from "../../identity/principal.js";
+import { KERNEL_LOGGER } from "../tokens.js";
+import { HEALTH_CHECKS } from "./health.options.js";
+import { SHUTDOWN_STATE } from "./shutdown-state.js";
+/** A dependency that hangs (Redis reconnecting, commands in the offline queue) must still give 503 fast. */
+export const CHECK_TIMEOUT_MS = 2_000;
+/**
+ * `GET /healthz` (process alive, always 200) and `GET /readyz` (dependencies ready).
+ * The readyz body only names each check as `"ok"` / `"error"`; the failure reason goes to the log
+ * (redacted) and never into the response: driver errors can carry connection strings. Once a stop
+ * has begun readyz answers 503 at once and runs no check. `@Public()`: the global auth guard
+ * applies here too when the kernel API is mounted.
+ */
+let HealthController = class HealthController {
+    health;
+    indicators;
+    checks;
+    shutdown;
+    log;
+    constructor(health, indicators, checks, shutdown, log) {
+        this.health = health;
+        this.indicators = indicators;
+        this.checks = checks;
+        this.shutdown = shutdown;
+        this.log = log;
+    }
+    healthz() {
+        return { ok: true };
+    }
+    async readyz(reply) {
+        const stopping = () => {
+            reply.code(503);
+            return { ok: false, stopping: true };
+        };
+        if (this.shutdown.isShuttingDown())
+            return stopping();
+        const names = Object.keys(this.checks);
+        const logged = new Set();
+        const fns = names.map((name) => () => this.indicators
+            .check(name)
+            .attempt(async () => {
+            try {
+                await this.checks[name]();
+            }
+            catch (err) {
+                logged.add(name);
+                this.log.warn("readiness check failed", { check: name, err });
+                throw err;
+            }
+        })
+            .withTimeout(CHECK_TIMEOUT_MS));
+        // `check` throws a 503 exception carrying the same `details` when any indicator is down
+        const details = await this.health.check(fns).then((r) => r.details, (e) => {
+            const d = e.getResponse?.().details;
+            if (d === undefined)
+                throw e;
+            return d;
+        });
+        if (this.shutdown.isShuttingDown())
+            return stopping();
+        const body = {};
+        let ok = true;
+        for (const name of names) {
+            const up = details[name]?.status === "up";
+            if (!up) {
+                ok = false;
+                // A timeout never reaches the wrapper's catch in time
+                if (!logged.has(name))
+                    this.log.warn("readiness check failed", { check: name, err: details[name] });
+            }
+            body[name] = up ? "ok" : "error";
+        }
+        reply.code(ok ? 200 : 503);
+        return { ok, ...body };
+    }
+};
+__decorate([
+    Get("healthz")
+], HealthController.prototype, "healthz", null);
+__decorate([
+    Get("readyz"),
+    __param(0, Res({ passthrough: true }))
+], HealthController.prototype, "readyz", null);
+HealthController = __decorate([
+    Controller(),
+    Public(),
+    __param(0, Inject(HealthCheckService)),
+    __param(1, Inject(HealthIndicatorService)),
+    __param(2, Inject(HEALTH_CHECKS)),
+    __param(3, Inject(SHUTDOWN_STATE)),
+    __param(4, Inject(KERNEL_LOGGER))
+], HealthController);
+export { HealthController };

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

@@ -0,0 +1,9 @@
+/**
+ * The terminus machinery behind `/healthz` and `/readyz`. The controller
+ * ({@link HealthController}) is registered by the root module, which also provides
+ * `HEALTH_CHECKS`; `SHUTDOWN_STATE` is the global `GracefulShutdown`. Terminus' own error logging
+ * is off: the
+ * controller logs a failed check once, with the redacted error, and never puts it in the body.
+ */
+export declare class HealthModule {
+}

package/dist/infra/health/health.module.js

@@ -0,0 +1,24 @@
+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 { Module } from "@nestjs/common";
+import { TerminusModule } from "@nestjs/terminus";
+/**
+ * The terminus machinery behind `/healthz` and `/readyz`. The controller
+ * ({@link HealthController}) is registered by the root module, which also provides
+ * `HEALTH_CHECKS`; `SHUTDOWN_STATE` is the global `GracefulShutdown`. Terminus' own error logging
+ * is off: the
+ * controller logs a failed check once, with the redacted error, and never puts it in the body.
+ */
+let HealthModule = class HealthModule {
+};
+HealthModule = __decorate([
+    Module({
+        imports: [TerminusModule.forRoot({ logger: false })],
+        exports: [TerminusModule],
+    })
+], HealthModule);
+export { HealthModule };

package/dist/infra/health/health.options.d.ts

@@ -0,0 +1,10 @@
+import type { Redis } from "ioredis";
+import { type Kysely } from "kysely";
+/** One readiness check: resolves when the dependency is ready, rejects when it is not. */
+export type ReadinessCheck = () => Promise<void>;
+/** Injection token of the named readiness checks (`Record<string, ReadinessCheck>`). */
+export declare const HEALTH_CHECKS: unique symbol;
+/** `select 1` on the pool. */
+export declare const databaseCheck: (pool: Kysely<any>) => ReadinessCheck;
+/** PING on a connection that must already be `ready` (a reconnecting client is not ready). */
+export declare const redisCheck: (redis: Redis) => ReadinessCheck;

package/dist/infra/health/health.options.js

@@ -0,0 +1,15 @@
+import { sql } from "kysely";
+/** Injection token of the named readiness checks (`Record<string, ReadinessCheck>`). */
+export const HEALTH_CHECKS = Symbol("HEALTH_CHECKS");
+/** `select 1` on the pool. */
+export const databaseCheck = 
+// biome-ignore lint/suspicious/noExplicitAny: the pool carries no schema types
+(pool) => async () => {
+    await sql `select 1`.execute(pool);
+};
+/** PING on a connection that must already be `ready` (a reconnecting client is not ready). */
+export const redisCheck = (redis) => async () => {
+    if (redis.status !== "ready")
+        throw new Error(`redis status ${redis.status}`);
+    await redis.ping();
+};

package/dist/infra/health/shutdown-state.d.ts

@@ -0,0 +1,6 @@
+/** Whether the process is shutting down; readiness answers 503 from then on. */
+export interface ShutdownState {
+    isShuttingDown(): boolean;
+}
+/** Injection token of the {@link ShutdownState}: `GracefulShutdown` (`GracefulShutdownModule`). */
+export declare const SHUTDOWN_STATE: unique symbol;

package/dist/infra/health/shutdown-state.js

@@ -0,0 +1,2 @@
+/** Injection token of the {@link ShutdownState}: `GracefulShutdown` (`GracefulShutdownModule`). */
+export const SHUTDOWN_STATE = Symbol("SHUTDOWN_STATE");

package/dist/infra/lifecycle/graceful-shutdown.module.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Global: {@link GracefulShutdown}, also as the health endpoints' `SHUTDOWN_STATE`. The infra
+ * modules that close resources at shutdown (Redis, the pool) import it for the shared stop budget.
+ */
+export declare class GracefulShutdownModule {
+}

package/dist/infra/lifecycle/graceful-shutdown.module.js

@@ -0,0 +1,23 @@
+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 { SHUTDOWN_STATE } from "../health/shutdown-state.js";
+import { GracefulShutdown } from "./graceful-shutdown.service.js";
+/**
+ * Global: {@link GracefulShutdown}, also as the health endpoints' `SHUTDOWN_STATE`. The infra
+ * modules that close resources at shutdown (Redis, the pool) import it for the shared stop budget.
+ */
+let GracefulShutdownModule = class GracefulShutdownModule {
+};
+GracefulShutdownModule = __decorate([
+    Global(),
+    Module({
+        providers: [GracefulShutdown, { provide: SHUTDOWN_STATE, useExisting: GracefulShutdown }],
+        exports: [GracefulShutdown, SHUTDOWN_STATE],
+    })
+], GracefulShutdownModule);
+export { GracefulShutdownModule };

package/dist/infra/lifecycle/graceful-shutdown.service.d.ts

@@ -0,0 +1,70 @@
+import { type BeforeApplicationShutdown, type OnApplicationShutdown } from "@nestjs/common";
+import type { KernelLogger } from "../../log.js";
+import type { ShutdownState } from "../health/shutdown-state.js";
+/**
+ * The total stop budget: from the moment the shutdown begins, the stop phases and the infra closes
+ * (bus, Redis, pool) share these 30 s; whatever is still open after it is abandoned.
+ */
+export declare const STOP_TIMEOUT_MS = 30000;
+/**
+ * The process's shutdown state, the one source of "are we stopping" (nest kernel spec §4).
+ *
+ * {@link begin} (idempotent, synchronous) flips readiness to 503 ({@link isShuttingDown}, read by
+ * `/readyz`), aborts {@link signal} (the start sequence stops at its next checkpoint, an extension
+ * migration of the start is aborted, the SSE stream registries close and refuse new streams) and
+ * starts the {@link STOP_TIMEOUT_MS} deadline that every later stop step takes its share of
+ * ({@link remainingMs}).
+ *
+ * {@link trackInFlight} registers work the stop must let finish before it closes what that work
+ * uses; {@link drain} waits for the set to empty, re-reading it each round (work registered by
+ * tracked work while draining is waited for too), up to a budget, and reports a timeout instead of
+ * hanging. The kernel's stop phases (`KernelLifecycle`) call `begin()` first and drain at their
+ * start-work step; components with their own close (the run workers, the extension host, Fastify)
+ * keep draining themselves within their phase budgets.
+ *
+ * `beforeApplicationShutdown` runs `begin()` and a final drain bounded by the remaining budget, so
+ * a Nest application without `KernelLifecycle` (or whose stop phases already drained) behaves the
+ * same: the readiness flip happens while the port is still open, before `dispose()` closes it.
+ *
+ * {@link closeLast} registers the close of an infra connection (the bus and Redis, the pool);
+ * `onApplicationShutdown` runs them all at once. This is a global module's hook, so it runs after
+ * every other module's stop hooks: nothing uses those connections once they start closing, and a
+ * close that hangs (Redis down) does not hold back the others, which share what is left of the
+ * same budget.
+ */
+export declare class GracefulShutdown implements BeforeApplicationShutdown, OnApplicationShutdown, ShutdownState {
+    private readonly log;
+    private shuttingDown;
+    private deadline;
+    private readonly abort;
+    private readonly inFlight;
+    private readonly lastCloses;
+    constructor(log: KernelLogger);
+    /** True from the moment the shutdown began; readiness answers 503 from then on. */
+    isShuttingDown(): boolean;
+    /** Aborted when the shutdown begins. */
+    get signal(): AbortSignal;
+    /** Begins the shutdown (idempotent): readiness 503, {@link signal} aborted, the deadline set. */
+    begin(): void;
+    /** What is left of the total stop budget (the whole budget before the shutdown began). */
+    remainingMs(): number;
+    /** Registers work the stop waits for (see {@link drain}); returns `p`. */
+    trackInFlight<T>(p: Promise<T>): Promise<T>;
+    /** The number of tracked promises not settled yet. */
+    get inFlightCount(): number;
+    /**
+     * Waits until no tracked work is left, at most `budgetMs` (capped by {@link remainingMs} once the
+     * shutdown began). Resolves true when everything settled, false on timeout: what is left is
+     * logged and abandoned (no later drain waits for it again). Rejections of tracked work are not
+     * this wait's business: they only count as settled.
+     */
+    drain(budgetMs: number): Promise<boolean>;
+    beforeApplicationShutdown(): Promise<void>;
+    /**
+     * Registers the close of an infra connection, run at the very end of the shutdown together with
+     * the others (see the class comment). `close` bounds itself by {@link remainingMs} and never
+     * throws.
+     */
+    closeLast(close: () => Promise<void>): void;
+    onApplicationShutdown(): Promise<void>;
+}