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

package/dist/infra/database/transaction-host.js

@@ -0,0 +1,125 @@
+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/typeorm/transaction-context.ts (owner-approved, 2026-10-28).
+// Adapted to Kysely: the context holds a Kysely `Transaction` instead of a TypeORM QueryRunner.
+import { AsyncLocalStorage } from "node:async_hooks";
+import { Inject, Injectable } from "@nestjs/common";
+import { KERNEL_LOGGER, KERNEL_POOL } from "../tokens.js";
+/** One store for the process: `afterCommit` (a free function) reads it without a host instance. */
+const storage = new AsyncLocalStorage();
+/** Logger for hook failures outside a transaction; set by `TransactionHost`, console until then. */
+let hookLog = {
+    error: (msg, fields) => console.error(`[afterCommit] ${msg}`, fields ?? ""),
+};
+const errMsg = (e) => (e instanceof Error ? e.message : String(e));
+/** Queues `fn` on the current live root transaction; with none open, runs it at once. */
+export function queueAfterCommit(fn) {
+    const store = liveStore();
+    if (store) {
+        store.hooks.push(fn);
+        return;
+    }
+    try {
+        const r = fn();
+        if (r instanceof Promise) {
+            r.catch((e) => hookLog.error("afterCommit hook failed", { error: errMsg(e) }));
+        }
+    }
+    catch (e) {
+        hookLog.error("afterCommit hook failed", { error: errMsg(e) });
+    }
+}
+/** The store of the current context unless its transaction already finished. */
+function liveStore() {
+    const store = storage.getStore();
+    return store && !store.done ? store : undefined;
+}
+/** The transaction store in the current async context (used by `afterCommit`). */
+export function currentStore() {
+    return liveStore();
+}
+/**
+ * Runs `fn` with no transaction in context, whatever the caller had open. Queue processors and
+ * scheduled jobs start from here: a job outlives the transaction that enqueued it and must never
+ * join (or write through) a transaction that may already be committed or rolled back.
+ */
+export function runOutsideTransaction(fn) {
+    return storage.exit(fn);
+}
+let TransactionHost = class TransactionHost {
+    pool;
+    log;
+    constructor(
+    // biome-ignore lint/suspicious/noExplicitAny: the pool carries no schema types
+    pool, log) {
+        this.pool = pool;
+        this.log = log;
+        hookLog = log;
+    }
+    /** The transaction of the current async context on this pool, if any. */
+    // biome-ignore lint/suspicious/noExplicitAny: the pool carries no schema types
+    current() {
+        const store = liveStore();
+        return store?.pool === this.pool ? store.trx : undefined;
+    }
+    /**
+     * Runs `fn` in a transaction: a throw rolls back, a return commits. REQUIRED (default) joins the
+     * transaction in context; `requires_new` always opens its own on the pool; `mandatory` joins the
+     * one in context and throws when there is none. Hooks queued by `afterCommit` run after the
+     * root's COMMIT, outside any transaction, and are dropped on rollback.
+     */
+    async run(fn, opts = {}) {
+        const propagation = opts.propagation ?? "required";
+        if (propagation === "mandatory") {
+            if (!this.current()) {
+                throw new Error('propagation "mandatory": no transaction in context (the caller must open one and ' +
+                    "hold the locks this method relies on)");
+            }
+            return fn();
+        }
+        if (propagation === "required" && this.current())
+            return fn();
+        const hooks = [];
+        let store;
+        let result;
+        try {
+            let builder = this.pool.transaction();
+            if (opts.isolationLevel !== undefined)
+                builder = builder.setIsolationLevel(opts.isolationLevel);
+            if (opts.accessMode !== undefined)
+                builder = builder.setAccessMode(opts.accessMode);
+            result = await builder.execute((trx) => {
+                store = { pool: this.pool, trx, hooks, done: false };
+                return storage.run(store, fn);
+            });
+        }
+        finally {
+            if (store)
+                store.done = true;
+        }
+        for (const hook of hooks) {
+            try {
+                // outside any transaction: a requires_new nested in an outer one must not have its side
+                // effects join (and roll back with) the outer transaction
+                await runOutsideTransaction(hook);
+            }
+            catch (e) {
+                this.log.error("afterCommit hook failed", { error: errMsg(e) });
+            }
+        }
+        return result;
+    }
+};
+TransactionHost = __decorate([
+    Injectable(),
+    __param(0, Inject(KERNEL_POOL)),
+    __param(1, Inject(KERNEL_LOGGER))
+], TransactionHost);
+export { TransactionHost };

package/dist/infra/database/transactional.decorator.d.ts

@@ -0,0 +1,15 @@
+import type { TransactionOptions } from "./transaction-host.js";
+/**
+ * Method decorator: runs the method in a database transaction (REQUIRED by default: join the one
+ * in context, else open it; a throw rolls back, a normal return commits). The class must inject
+ * the host as a property named `txHost`:
+ *
+ * ```ts
+ * constructor(@Inject(TransactionHost) readonly txHost: TransactionHost) {}
+ * ```
+ *
+ * Use `{ propagation: "requires_new" }` for a transaction independent of the caller's, and
+ * `{ propagation: "mandatory" }` for a method whose correctness depends on a lock its caller holds
+ * (it joins the caller's transaction and throws when called outside one).
+ */
+export declare function Transactional(opts?: TransactionOptions): (_target: object, _key: string | symbol, descriptor: PropertyDescriptor) => PropertyDescriptor;

package/dist/infra/database/transactional.decorator.js

@@ -0,0 +1,27 @@
+/**
+ * Method decorator: runs the method in a database transaction (REQUIRED by default: join the one
+ * in context, else open it; a throw rolls back, a normal return commits). The class must inject
+ * the host as a property named `txHost`:
+ *
+ * ```ts
+ * constructor(@Inject(TransactionHost) readonly txHost: TransactionHost) {}
+ * ```
+ *
+ * Use `{ propagation: "requires_new" }` for a transaction independent of the caller's, and
+ * `{ propagation: "mandatory" }` for a method whose correctness depends on a lock its caller holds
+ * (it joins the caller's transaction and throws when called outside one).
+ */
+export function Transactional(opts = {}) {
+    return (_target, _key, descriptor) => {
+        const original = descriptor.value;
+        descriptor.value = function (...args) {
+            const host = this.txHost;
+            if (!host) {
+                throw new Error("@Transactional() needs the class to inject `TransactionHost` as `txHost` " +
+                    "(`@Inject(TransactionHost) readonly txHost: TransactionHost`).");
+            }
+            return host.run(() => original.apply(this, args), opts);
+        };
+        return descriptor;
+    };
+}

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 super 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 super 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,121 @@
+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 fork
+     * sub-agent at once (background sub-agents keep running, agent map spec §5.4). A lost event is
+     * repaired by the wait sweep (fork children of finished runs).
+     */
+    "run.orphaned": {
+        runId: string;
+    };
+    /**
+     * A sub-agent's `subagent_delivery` was appended to its parent conversation (after the commit;
+     * `SubagentDeliveries`). Waking an idle parent follows it; a lost event is re-derived by the
+     * next `ensureRun` (a message, the end of a run, a page opening).
+     */
+    "subagent.delivered": {
+        conversationId: string;
+    };
+    /**
+     * A background task of the conversation finished (after the commit of its
+     * `background_task_finished` event). `BackgroundWake` asks the run queue for a wake run; a lost
+     * event is re-derived by the next `ensureRun` (a message, the end of a run, a page opening).
+     */
+    "background_task.finished": {
+        conversationId: string;
+    };
+    /**
+     * An extension's `ctx.models.embed` call wrote a `model_usage` row (after the commit, spec B
+     * §5.4). The usage reporter enqueues its `usage.report` delivery; a lost event is re-derived by
+     * the usage sweep (rows whose `reported_at` is still null).
+     */
+    "model_usage.recorded": {
+        id: 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 };