@sixthsummit/ship-api 0.0.0-stage → 4.1.1

package/lib/app/db/client.js

@@ -0,0 +1,99 @@
+import { drizzle } from "drizzle-orm/node-postgres";
+import pg from "pg";
+import { logger } from "../../observability/logger.js";
+import { safeErrorFields } from "../../observability/safeErrorFields.js";
+import { healthCheckRegistry, } from "../health/HealthCheck.js";
+const DEFAULT_DB_CONFIG = {
+    max: 20,
+    idleTimeoutMillis: 30_000,
+    connectionTimeoutMillis: 5_000,
+    statementTimeoutMillis: 30_000,
+};
+export function createPool(config) {
+    const merged = { ...DEFAULT_DB_CONFIG, ...config };
+    const poolConfig = {
+        max: merged.max,
+        idleTimeoutMillis: merged.idleTimeoutMillis,
+        connectionTimeoutMillis: merged.connectionTimeoutMillis,
+        application_name: merged.applicationName,
+        ssl: merged.ssl,
+    };
+    if (merged.connectionString) {
+        poolConfig.connectionString = merged.connectionString;
+    }
+    else {
+        poolConfig.host = merged.host;
+        poolConfig.port = merged.port;
+        poolConfig.database = merged.database;
+        poolConfig.user = merged.user;
+        poolConfig.password = merged.password;
+    }
+    // Apply statement_timeout as a libpq startup option (`-c statement_timeout=…`)
+    // so Postgres sets it when each connection opens — no extra query. Doing this
+    // via a `pool.on('connect')` query instead trips pg's "client.query() called
+    // while the client is already executing a query" deprecation, because the pool
+    // hands the freshly-connected client to its first caller concurrently with the
+    // setter query. (A bare number is interpreted as milliseconds.)
+    if (merged.statementTimeoutMillis > 0) {
+        poolConfig.options = `-c statement_timeout=${merged.statementTimeoutMillis}`;
+    }
+    return handleIdleClientErrors(new pg.Pool(poolConfig));
+}
+/**
+ * Keep a broken idle connection from killing the process.
+ *
+ * `pg` emits `error` on the pool when an idle pooled client's connection fails. A Cloud SQL
+ * restart, failover or maintenance window ends every connection with `57P01 terminating
+ * connection due to administrator command`, and with no listener Node treats that event as an
+ * uncaught exception and exits. The pool has already discarded the broken client and the next
+ * checkout opens a fresh connection, so logging is all that is needed. Only the error's code,
+ * name and syscall are logged (the same fields `/readyz` logs for a thrown check error), because
+ * connection error messages can name the database host or user.
+ *
+ * `createPool` and `createDb` call this; call it yourself on any pool you build with
+ * `new pg.Pool()` (migration scripts, workers). A pool that already has an `error` listener is
+ * left alone, so a caller's own handling wins.
+ */
+export function handleIdleClientErrors(pool) {
+    if (pool.listenerCount("error") > 0)
+        return pool;
+    pool.on("error", (error) => {
+        logger.warn(safeErrorFields(error), "Idle Postgres connection failed; the pool discarded it");
+    });
+    return pool;
+}
+/**
+ * Readiness check that runs `select 1` on `pool`. The registry measures the
+ * latency and enforces the per-check timeout; a failure throws, so the raw
+ * error reaches the registry's failure callback (which `/readyz` logs as
+ * code/name/syscall only) rather than the response body. This is the
+ * recommended database check: a thrown driver error never puts its message in
+ * the log, where a hand-written check returning `error: err.message` would.
+ */
+export function dbHealthCheck(pool, opts = {}) {
+    return {
+        name: opts.name ?? "db.primary",
+        async check() {
+            const start = performance.now();
+            await pool.query("select 1");
+            return { ok: true, latencyMs: Math.round(performance.now() - start) };
+        },
+    };
+}
+/**
+ * Build a Drizzle client + pool. The `schema` is the composed schema record
+ * (`{ accounts, roles, permissions, ...customTables }`); `db.query.<key>` is
+ * typed against it.
+ */
+export function createDb(args) {
+    const pool = args.pool ? handleIdleClientErrors(args.pool) : createPool(args.config);
+    const db = drizzle(pool, { schema: args.schema, casing: "snake_case" });
+    if (args.healthCheck !== false) {
+        const opts = args.healthCheck ?? {};
+        (opts.registry ?? healthCheckRegistry).add(dbHealthCheck(pool, { name: opts.name }), {
+            replaceable: true,
+        });
+    }
+    return { pool, db };
+}
+//# sourceMappingURL=client.js.map

package/lib/app/db/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../../src/app/db/client.ts"],"names":[],"mappings":"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"}

package/lib/app/db/tenantScoped.d.ts

@@ -0,0 +1,59 @@
+import type { AnyPgColumn } from "drizzle-orm/pg-core";
+/**
+ * `tenantScoped(tenants)` — opt-in multi-tenancy column primitive, the sibling
+ * of `baseFields`.
+ *
+ * Tenancy is never a core default. A multi-tenant product spreads this mixin
+ * into the domain tables it wants scoped; a single-tenant product simply never
+ * uses it. Core ships the *shape* — a non-null `tenant_id` uuid foreign key to a
+ * `tenants` root table, `onDelete: "restrict"` so a tenant can't be deleted out
+ * from under its rows — but forces nothing: the `tenants` table is
+ * consumer-owned, so this is a *factory* that takes it, rather than a static
+ * object referencing a table core doesn't have.
+ *
+ * Conventions (see `docs/v4/concepts/tenancy.md`):
+ *   - Domain tables FK `tenants`, NOT `accounts` — so a future
+ *     one-tenant-per-user → membership move (Model A → B) is an
+ *     identity-tables-only migration.
+ *   - Read the active tenant from `RequestContext.tenantId` (published by
+ *     `resolveTenant()`), never from `account.tenantId` directly.
+ *   - Index `tenant_id` leading on scoped tables — usually
+ *     `(tenant_id, <natural key>)`.
+ *
+ * Usage:
+ *
+ * ```ts
+ * import { index, pgTable, uuid, varchar } from "drizzle-orm/pg-core";
+ * import { baseFields, tenantScoped } from "@sixthsummit/ship-api";
+ * import { tenants } from "../accounts/schema.js";
+ *
+ * export const projects = pgTable(
+ *   "projects",
+ *   {
+ *     id: uuid("id").primaryKey().defaultRandom(),
+ *     name: varchar("name", { length: 200 }).notNull(),
+ *     ...tenantScoped(tenants), // adds a non-null tenant_id FK → tenants.id
+ *     ...baseFields,
+ *   },
+ *   (t) => [index("projects_tenant_ix").on(t.tenantId)],
+ * );
+ * ```
+ *
+ * Tenant *enforcement* — auto-injecting `WHERE tenant_id = ?` on every query via
+ * the `beforeQuery` lifecycle hook + `RequestContext.tenantId` — is deliberately
+ * deferred (see `V4_STATUS` V8). This primitive ships only the column shape and
+ * the resolution convention; it scopes nothing on its own.
+ */
+export declare function tenantScoped<TTenants extends {
+    id: AnyPgColumn;
+}>(tenants: TTenants): {
+    readonly tenantId: import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgUUIDBuilderInitial<"tenant_id">>;
+};
+/**
+ * Row-shape contribution of `tenantScoped` (for service-level type
+ * constraints), mirroring `BaseFields`.
+ */
+export type TenantScoped = {
+    tenantId: string;
+};
+//# sourceMappingURL=tenantScoped.d.ts.map

package/lib/app/db/tenantScoped.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenantScoped.d.ts","sourceRoot":"","sources":["../../../src/app/db/tenantScoped.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAGvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,YAAY,CAAC,QAAQ,SAAS;IAAE,EAAE,EAAE,WAAW,CAAA;CAAE,EAAE,OAAO,EAAE,QAAQ;;EAMnF;AAED;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC"}

package/lib/app/db/tenantScoped.js

@@ -0,0 +1,54 @@
+import { uuid } from "drizzle-orm/pg-core";
+/**
+ * `tenantScoped(tenants)` — opt-in multi-tenancy column primitive, the sibling
+ * of `baseFields`.
+ *
+ * Tenancy is never a core default. A multi-tenant product spreads this mixin
+ * into the domain tables it wants scoped; a single-tenant product simply never
+ * uses it. Core ships the *shape* — a non-null `tenant_id` uuid foreign key to a
+ * `tenants` root table, `onDelete: "restrict"` so a tenant can't be deleted out
+ * from under its rows — but forces nothing: the `tenants` table is
+ * consumer-owned, so this is a *factory* that takes it, rather than a static
+ * object referencing a table core doesn't have.
+ *
+ * Conventions (see `docs/v4/concepts/tenancy.md`):
+ *   - Domain tables FK `tenants`, NOT `accounts` — so a future
+ *     one-tenant-per-user → membership move (Model A → B) is an
+ *     identity-tables-only migration.
+ *   - Read the active tenant from `RequestContext.tenantId` (published by
+ *     `resolveTenant()`), never from `account.tenantId` directly.
+ *   - Index `tenant_id` leading on scoped tables — usually
+ *     `(tenant_id, <natural key>)`.
+ *
+ * Usage:
+ *
+ * ```ts
+ * import { index, pgTable, uuid, varchar } from "drizzle-orm/pg-core";
+ * import { baseFields, tenantScoped } from "@sixthsummit/ship-api";
+ * import { tenants } from "../accounts/schema.js";
+ *
+ * export const projects = pgTable(
+ *   "projects",
+ *   {
+ *     id: uuid("id").primaryKey().defaultRandom(),
+ *     name: varchar("name", { length: 200 }).notNull(),
+ *     ...tenantScoped(tenants), // adds a non-null tenant_id FK → tenants.id
+ *     ...baseFields,
+ *   },
+ *   (t) => [index("projects_tenant_ix").on(t.tenantId)],
+ * );
+ * ```
+ *
+ * Tenant *enforcement* — auto-injecting `WHERE tenant_id = ?` on every query via
+ * the `beforeQuery` lifecycle hook + `RequestContext.tenantId` — is deliberately
+ * deferred (see `V4_STATUS` V8). This primitive ships only the column shape and
+ * the resolution convention; it scopes nothing on its own.
+ */
+export function tenantScoped(tenants) {
+    return {
+        tenantId: uuid("tenant_id")
+            .notNull()
+            .references(() => tenants.id, { onDelete: "restrict" }),
+    };
+}
+//# sourceMappingURL=tenantScoped.js.map

package/lib/app/db/tenantScoped.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenantScoped.js","sourceRoot":"","sources":["../../../src/app/db/tenantScoped.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,MAAM,UAAU,YAAY,CAAuC,OAAiB;IAClF,OAAO;QACL,QAAQ,EAAE,IAAI,CAAC,WAAW,CAAC;aACxB,OAAO,EAAE;aACT,UAAU,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC;KACjD,CAAC;AACb,CAAC"}

package/lib/app/db/transaction.d.ts

@@ -0,0 +1,58 @@
+import type { NodePgDatabase, NodePgQueryResultHKT } from "drizzle-orm/node-postgres";
+import type { PgTransaction } from "drizzle-orm/pg-core";
+import type { ExtractTablesWithRelations } from "drizzle-orm/relations";
+/**
+ * `withTransaction` — opens a Drizzle transaction with framework value-add.
+ *
+ * Beyond Drizzle's bare `db.transaction(...)` this wrapper provides:
+ *
+ * 1. **OTel span** named `db.transaction` so transaction duration shows up in
+ *    traces with the same correlation IDs as the surrounding request.
+ * 2. **Translation of `TransactionRollbackError`** into ShipAPI's
+ *    `RollbackError` so `catch (Error)` blocks in callers don't accidentally
+ *    swallow a rollback as a generic application failure. Raw Drizzle
+ *    rollbacks are easy to misuse; this gives them a typed identity.
+ * 3. **Optional retry-on-deadlock** for serialization failures (Postgres SQLSTATE
+ *    `40001`) and deadlocks (`40P01`). Off by default; opt in via
+ *    `retryOnConflict: { attempts: 3, backoffMs: 50 }`.
+ * 4. **`RequestContext.tx` propagation** — while inside the callback, the
+ *    canonical request context's `tx` field is set so lifecycle hooks
+ *    (audit / CDC / multi-tenant) running in nested service calls know
+ *    they're inside an active transaction without explicit threading.
+ */
+export declare class RollbackError extends Error {
+    readonly cause?: unknown;
+    constructor(message?: string, cause?: unknown);
+}
+type AnyDb<TSchema extends Record<string, unknown>> = NodePgDatabase<TSchema>;
+export type ShipTx<TSchema extends Record<string, unknown>> = PgTransaction<NodePgQueryResultHKT, TSchema, ExtractTablesWithRelations<TSchema>>;
+export interface WithTransactionOptions {
+    /**
+     * Retry the transaction on Postgres serialization failures and deadlocks.
+     * Defaults to `undefined` (no retry).
+     */
+    retryOnConflict?: {
+        attempts: number;
+        backoffMs: number;
+    };
+    /** Custom span name override. Defaults to `"db.transaction"`. */
+    spanName?: string;
+}
+/**
+ * Run `fn` inside a Drizzle transaction. The `tx` argument is the same
+ * Drizzle transaction client your service code would receive from `db.transaction(...)` —
+ * use it for all writes inside the callback so they share the transaction
+ * scope.
+ *
+ * Throwing from the callback rolls back. Calling `tx.rollback()` also rolls
+ * back (translated to `RollbackError`).
+ *
+ * @example
+ * await withTransaction(db, async (tx) => {
+ *   await tx.insert(accounts).values(values);
+ *   await tx.insert(auditLog).values(diff);
+ * });
+ */
+export declare function withTransaction<TSchema extends Record<string, unknown>, T>(db: AnyDb<TSchema>, fn: (tx: ShipTx<TSchema>) => Promise<T>, opts?: WithTransactionOptions): Promise<T>;
+export {};
+//# sourceMappingURL=transaction.d.ts.map

package/lib/app/db/transaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.d.ts","sourceRoot":"","sources":["../../../src/app/db/transaction.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACtF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,uBAAuB,CAAC;AAIxE;;;;;;;;;;;;;;;;;;GAkBG;AAEH,qBAAa,aAAc,SAAQ,KAAK;IACtC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;gBACb,OAAO,SAA4B,EAAE,KAAK,CAAC,EAAE,OAAO;CAKjE;AAED,KAAK,KAAK,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,cAAc,CAAC,OAAO,CAAC,CAAC;AAE9E,MAAM,MAAM,MAAM,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,aAAa,CACzE,oBAAoB,EACpB,OAAO,EACP,0BAA0B,CAAC,OAAO,CAAC,CACpC,CAAC;AAEF,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,eAAe,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1D,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAiBD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,eAAe,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,EAC9E,EAAE,EAAE,KAAK,CAAC,OAAO,CAAC,EAClB,EAAE,EAAE,CAAC,EAAE,EAAE,MAAM,CAAC,OAAO,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,EACvC,IAAI,GAAE,sBAA2B,GAChC,OAAO,CAAC,CAAC,CAAC,CAiDZ"}

package/lib/app/db/transaction.js

@@ -0,0 +1,106 @@
+import { TransactionRollbackError } from "drizzle-orm/errors";
+import { withSpan } from "../../observability/tracing.js";
+import { setRequestContextField } from "../context/RequestContext.js";
+/**
+ * `withTransaction` — opens a Drizzle transaction with framework value-add.
+ *
+ * Beyond Drizzle's bare `db.transaction(...)` this wrapper provides:
+ *
+ * 1. **OTel span** named `db.transaction` so transaction duration shows up in
+ *    traces with the same correlation IDs as the surrounding request.
+ * 2. **Translation of `TransactionRollbackError`** into ShipAPI's
+ *    `RollbackError` so `catch (Error)` blocks in callers don't accidentally
+ *    swallow a rollback as a generic application failure. Raw Drizzle
+ *    rollbacks are easy to misuse; this gives them a typed identity.
+ * 3. **Optional retry-on-deadlock** for serialization failures (Postgres SQLSTATE
+ *    `40001`) and deadlocks (`40P01`). Off by default; opt in via
+ *    `retryOnConflict: { attempts: 3, backoffMs: 50 }`.
+ * 4. **`RequestContext.tx` propagation** — while inside the callback, the
+ *    canonical request context's `tx` field is set so lifecycle hooks
+ *    (audit / CDC / multi-tenant) running in nested service calls know
+ *    they're inside an active transaction without explicit threading.
+ */
+export class RollbackError extends Error {
+    cause;
+    constructor(message = "Transaction rolled back", cause) {
+        super(message);
+        this.name = "RollbackError";
+        this.cause = cause;
+    }
+}
+const POSTGRES_RETRYABLE_CODES = new Set([
+    "40001", // serialization_failure
+    "40P01", // deadlock_detected
+]);
+function isRetryablePgError(err) {
+    if (typeof err !== "object" || err === null)
+        return false;
+    const code = err.code;
+    return typeof code === "string" && POSTGRES_RETRYABLE_CODES.has(code);
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Run `fn` inside a Drizzle transaction. The `tx` argument is the same
+ * Drizzle transaction client your service code would receive from `db.transaction(...)` —
+ * use it for all writes inside the callback so they share the transaction
+ * scope.
+ *
+ * Throwing from the callback rolls back. Calling `tx.rollback()` also rolls
+ * back (translated to `RollbackError`).
+ *
+ * @example
+ * await withTransaction(db, async (tx) => {
+ *   await tx.insert(accounts).values(values);
+ *   await tx.insert(auditLog).values(diff);
+ * });
+ */
+export async function withTransaction(db, fn, opts = {}) {
+    const spanName = opts.spanName ?? "db.transaction";
+    const retry = opts.retryOnConflict;
+    const maxAttempts = retry?.attempts ?? 1;
+    const backoffMs = retry?.backoffMs ?? 0;
+    return withSpan(spanName, async (span) => {
+        let attempt = 0;
+        let lastErr;
+        while (attempt < maxAttempts) {
+            attempt += 1;
+            try {
+                return await db.transaction(async (tx) => {
+                    // Make `tx` visible to lifecycle hooks running in nested service calls.
+                    setRequestContextField("tx", tx);
+                    try {
+                        return await fn(tx);
+                    }
+                    finally {
+                        setRequestContextField("tx", undefined);
+                    }
+                });
+            }
+            catch (err) {
+                lastErr = err;
+                // Drizzle marks intentional rollbacks via TransactionRollbackError.
+                if (err instanceof TransactionRollbackError) {
+                    const wrapped = new RollbackError("Transaction rolled back via tx.rollback()", err);
+                    span.setAttribute("db.rollback.kind", "explicit");
+                    throw wrapped;
+                }
+                if (attempt < maxAttempts && retry && isRetryablePgError(err)) {
+                    span.addEvent("db.transaction.retry", {
+                        attempt,
+                        "error.code": err.code ?? "unknown",
+                    });
+                    if (backoffMs > 0)
+                        await delay(backoffMs * attempt);
+                    continue;
+                }
+                throw err;
+            }
+        }
+        // Unreachable in practice — last attempt either returned or threw above.
+        /* c8 ignore next */
+        throw lastErr;
+    });
+}
+//# sourceMappingURL=transaction.js.map

package/lib/app/db/transaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.js","sourceRoot":"","sources":["../../../src/app/db/transaction.ts"],"names":[],"mappings":"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"}

package/lib/app/health/HealthCheck.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Pluggable health-check primitive.
+ *
+ * The framework exposes two HTTP endpoints (`/livez` and `/readyz`) backed
+ * by a `HealthCheckRegistry`:
+ *
+ *   - `/livez` — process is up. Always 200 with no checks. Used by load
+ *     balancers / orchestrators to decide "should I restart this pod?"
+ *   - `/readyz` — runs every registered check. 200 if all pass; 503 with
+ *     a structured `{ checks: [...] }` body otherwise. Used to decide
+ *     "should I send traffic to this pod?"
+ *
+ * `createApp()` mounts both routes by default (see `http/app/health.ts`).
+ * Modules / consumer code register checks via `healthCheckRegistry.add(...)`.
+ * Built-in checks: `createDb()` registers a `db.primary` check on its pool by
+ * default; `redisHealthCheck(provider)` is a factory you add yourself.
+ *
+ * Duplicate names: the first registration of a name wins and later ones are
+ * skipped (logged), except that a check added with `{ replaceable: true }`
+ * (what framework defaults such as `createDb`'s `db.primary` use) gives way
+ * to a later explicit registration of the same name. So a consumer that
+ * registers its own `db.primary` after `createDb()` gets exactly one check:
+ * its own.
+ */
+export interface HealthCheckResult {
+    ok: boolean;
+    /** Latency of the check itself, ms. */
+    latencyMs: number;
+    /**
+     * Free-form error message when ok=false. `/readyz` never sends it, but logs
+     * it server-side (truncated), so it must not contain secrets.
+     */
+    error?: string;
+    /** Adapter-specific extras (versions, replication lag, etc.). */
+    details?: Record<string, unknown>;
+}
+export interface HealthCheck {
+    /** Stable name reported in the readyz response (e.g., `"redis"`, `"db.primary"`). */
+    readonly name: string;
+    /**
+     * Run the check. Should return within a few seconds; timeouts are the
+     * registry's responsibility (see `runAll`'s `timeoutMs`).
+     */
+    check(): Promise<HealthCheckResult> | HealthCheckResult;
+}
+export interface AddHealthCheckOptions {
+    /**
+     * Mark this check as a default that a later `add()` of the same name may
+     * replace. Framework-registered checks (`createDb`'s `db.primary`) use
+     * this so a consumer's own check of that name takes over instead of being
+     * skipped. Default `false`.
+     */
+    replaceable?: boolean;
+}
+/** One failed check, as reported to `RunAllOptions.onCheckFailure`. */
+export interface HealthCheckFailure {
+    name: string;
+    /** The thrown value, or the `error` string the check returned (may be `undefined`). */
+    error: unknown;
+    /**
+     * The `error` string the check *returned* with `ok: false`. Absent when the
+     * check threw, timed out, or returned no string. Unlike a thrown error's
+     * message, this text was written by the app author, so `/readyz` logs it.
+     */
+    reason?: string;
+    /** `true` when the check was cut off by the registry's per-check timeout. */
+    timedOut: boolean;
+}
+export interface RunAllOptions {
+    /**
+     * Per-check timeout in milliseconds. Default 3_000 (3 s). Checks that
+     * exceed this are reported as failed with `error: "timeout"`.
+     */
+    timeoutMs?: number;
+    /**
+     * Called once per failed check with the raw error, before `runAll`
+     * resolves. `/readyz` uses it to log failures server-side while keeping
+     * the raw error out of the public response body. Exceptions thrown by the
+     * callback are swallowed.
+     */
+    onCheckFailure?: (failure: HealthCheckFailure) => void;
+}
+export interface RunAllResult {
+    ok: boolean;
+    checks: Array<{
+        name: string;
+        ok: boolean;
+        latencyMs: number;
+        error?: string;
+        details?: Record<string, unknown>;
+    }>;
+}
+/**
+ * Container for registered checks. One framework-wide singleton (below);
+ * tests construct their own via `new HealthCheckRegistry()`.
+ */
+export declare class HealthCheckRegistry {
+    private checks;
+    private replaceable;
+    /**
+     * Register a check. Returns `true` when the check is now registered,
+     * `false` when it was skipped because a check of that name already exists.
+     *
+     * Duplicate names never throw and never run twice:
+     *   - existing check is `replaceable` and the new one is not → the new
+     *     check replaces it (debug log);
+     *   - otherwise the existing check wins and the new one is skipped (debug
+     *     log when either side is `replaceable`, warn log when both are
+     *     explicit registrations, since that is usually a consumer bug).
+     */
+    add(check: HealthCheck, opts?: AddHealthCheckOptions): boolean;
+    /** Test / admin helper. */
+    remove(name: string): boolean;
+    list(): readonly HealthCheck[];
+    size(): number;
+    clear(): void;
+    runAll(opts?: RunAllOptions): Promise<RunAllResult>;
+}
+/** Framework-wide registry. Bootstrappers / modules add checks here. */
+export declare const healthCheckRegistry: HealthCheckRegistry;
+//# sourceMappingURL=HealthCheck.d.ts.map

package/lib/app/health/HealthCheck.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HealthCheck.d.ts","sourceRoot":"","sources":["../../../src/app/health/HealthCheck.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,OAAO,CAAC;IACZ,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,WAAW;IAC1B,qFAAqF;IACrF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,KAAK,IAAI,OAAO,CAAC,iBAAiB,CAAC,GAAG,iBAAiB,CAAC;CACzD;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,uEAAuE;AACvE,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,uFAAuF;IACvF,KAAK,EAAE,OAAO,CAAC;IACf;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE,kBAAkB,KAAK,IAAI,CAAC;CACxD;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,KAAK,CAAC;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,EAAE,EAAE,OAAO,CAAC;QACZ,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACnC,CAAC,CAAC;CACJ;AAED;;;GAGG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,WAAW,CAA0B;IAE7C;;;;;;;;;;OAUG;IACH,GAAG,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,GAAE,qBAA0B,GAAG,OAAO;IA0BlE,2BAA2B;IAC3B,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAU7B,IAAI,IAAI,SAAS,WAAW,EAAE;IAI9B,IAAI,IAAI,MAAM;IAId,KAAK,IAAI,IAAI;IAKP,MAAM,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,YAAY,CAAC;CA6D9D;AAED,wEAAwE;AACxE,eAAO,MAAM,mBAAmB,qBAA4B,CAAC"}