@shaferllc/keel 0.66.0 → 0.74.0

package/dist/core/instrumentation.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Framework instrumentation — the typed event stream that lets a package observe
+ * the framework without patching it. Core seams (the query builder, the HTTP
+ * kernel, the queue, the cache, …) call `instrument(event, payload)`; anything
+ * that wants to watch subscribes with `listen()`. The mail layer already works
+ * this way (`mail.sent`); this generalises it.
+ *
+ * These events are deliberately fire-and-forget: `instrument()` never blocks the
+ * work it describes, and a listener that throws can't break a query or a
+ * request. That's the difference between instrumentation and business logic.
+ *
+ * A **request id** ties a request to everything that happened inside it — the
+ * queries it ran, the logs it wrote, the jobs it dispatched. The kernel opens a
+ * request scope with `runRequest(id, …)`; anything emitted inside it can read
+ * `currentRequestId()` to attribute itself. It flows through `await` chains via
+ * `AsyncLocalStorage`, so nothing has to be threaded by hand.
+ */
+/** A SQL statement that ran on a connection. */
+export interface QueryEvent {
+    sql: string;
+    bindings: unknown[];
+    /** Wall-clock time the statement took, in milliseconds. */
+    durationMs: number;
+    /** The registered connection name it ran on. */
+    connection: string;
+    /** "select" (row-returning) or "write" (insert/update/delete/DDL). */
+    kind: "select" | "write";
+    /** The request that ran it, if any. */
+    requestId?: string;
+}
+/** A request that finished (or threw). */
+export interface RequestEvent {
+    id: string;
+    method: string;
+    path: string;
+    status: number;
+    durationMs: number;
+    /** Request headers, lower-cased (auth/cookies are redacted by watchers). */
+    headers: Record<string, string>;
+    ip?: string;
+}
+/** An error that reached the HTTP kernel. */
+export interface ExceptionEvent {
+    error: unknown;
+    method?: string;
+    path?: string;
+    /** The status it rendered as. */
+    status: number;
+    requestId?: string;
+}
+/** A queued job at one point in its lifecycle. */
+export interface JobEvent {
+    job: string;
+    payload?: unknown;
+    /** Set on `job.processed` / `job.failed`. */
+    durationMs?: number;
+    /** Set on `job.failed`. */
+    error?: unknown;
+    requestId?: string;
+}
+/** A cache lookup. */
+export interface CacheEvent {
+    key: string;
+    store: string;
+    requestId?: string;
+}
+/** A notification that was sent. */
+export interface NotificationEvent {
+    notification: string;
+    channels: string[];
+    notifiable?: unknown;
+    requestId?: string;
+}
+/** A scheduled task that ran. */
+export interface ScheduleEvent {
+    task: string;
+    durationMs: number;
+}
+/**
+ * Register the instrumentation events on the framework's typed event registry,
+ * so `listen("db.query", (e) => …)` gets a fully-typed `e`. Any code that
+ * augments `EventsList` merges with this — declaring your own events elsewhere
+ * still works.
+ */
+declare module "./events.js" {
+    interface EventsList {
+        "db.query": QueryEvent;
+        "request.handled": RequestEvent;
+        "exception": ExceptionEvent;
+        "job.processing": JobEvent;
+        "job.processed": JobEvent;
+        "job.failed": JobEvent;
+        "cache.hit": CacheEvent;
+        "cache.miss": CacheEvent;
+        "notification.sent": NotificationEvent;
+        "schedule.task.run": ScheduleEvent;
+    }
+}
+/** The instrumentation event names, for iteration and toggling. */
+export type InstrumentEvent = "db.query" | "request.handled" | "exception" | "job.processing" | "job.processed" | "job.failed" | "cache.hit" | "cache.miss" | "notification.sent" | "schedule.task.run";
+/** A random id for a request/batch. 16 hex chars is plenty to be unique. */
+export declare function newRequestId(): string;
+/** Run `fn` inside a request scope, so everything it does can be attributed. */
+export declare function runRequest<T>(id: string, fn: () => T): T;
+/** The id of the request currently in scope, if any. */
+export declare function currentRequestId(): string | undefined;
+/**
+ * Emit an instrumentation event — fire-and-forget. Never throws, never blocks:
+ * a broken watcher can't take down the request it was watching, and the work
+ * being measured doesn't wait on the measurement. A no-op when there's no live
+ * application (e.g. a unit test that never booted one).
+ */
+export declare function instrument<E extends InstrumentEvent>(event: E, payload: import("./events.js").EventsList[E]): void;

package/dist/core/instrumentation.js

@@ -0,0 +1,52 @@
+/**
+ * Framework instrumentation — the typed event stream that lets a package observe
+ * the framework without patching it. Core seams (the query builder, the HTTP
+ * kernel, the queue, the cache, …) call `instrument(event, payload)`; anything
+ * that wants to watch subscribes with `listen()`. The mail layer already works
+ * this way (`mail.sent`); this generalises it.
+ *
+ * These events are deliberately fire-and-forget: `instrument()` never blocks the
+ * work it describes, and a listener that throws can't break a query or a
+ * request. That's the difference between instrumentation and business logic.
+ *
+ * A **request id** ties a request to everything that happened inside it — the
+ * queries it ran, the logs it wrote, the jobs it dispatched. The kernel opens a
+ * request scope with `runRequest(id, …)`; anything emitted inside it can read
+ * `currentRequestId()` to attribute itself. It flows through `await` chains via
+ * `AsyncLocalStorage`, so nothing has to be threaded by hand.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+import { emit, hasApplication } from "./helpers.js";
+/* ------------------------------ request scope ----------------------------- */
+const store = new AsyncLocalStorage();
+/** A random id for a request/batch. 16 hex chars is plenty to be unique. */
+export function newRequestId() {
+    const bytes = new Uint8Array(8);
+    crypto.getRandomValues(bytes);
+    return [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+/** Run `fn` inside a request scope, so everything it does can be attributed. */
+export function runRequest(id, fn) {
+    return store.run({ id }, fn);
+}
+/** The id of the request currently in scope, if any. */
+export function currentRequestId() {
+    return store.getStore()?.id;
+}
+/* -------------------------------- emitting -------------------------------- */
+/**
+ * Emit an instrumentation event — fire-and-forget. Never throws, never blocks:
+ * a broken watcher can't take down the request it was watching, and the work
+ * being measured doesn't wait on the measurement. A no-op when there's no live
+ * application (e.g. a unit test that never booted one).
+ */
+export function instrument(event, payload) {
+    if (!hasApplication())
+        return;
+    try {
+        void Promise.resolve(emit(event, payload)).catch(() => { });
+    }
+    catch {
+        // hasApplication() raced with teardown — instrumentation stays silent.
+    }
+}

package/dist/core/lock.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Distributed locks — "only one of you may do this at a time", across processes
+ * and across nodes. The counterpart to the cache's stampede protection: that
+ * collapses concurrent work *inside one isolate*, this one coordinates work
+ * *between* them.
+ *
+ *   const [ran] = await lock("invoice:42").run(async () => charge(invoice));
+ *   if (!ran) return;   // someone else is already charging it
+ *
+ * Like every other backend in keel, the store is a small pluggable seam and the
+ * core imports no driver — `MemoryLockStore` is the built-in default (per
+ * isolate, so it's for tests and single-process apps); the locks guide has Redis
+ * and database recipes for the real thing.
+ *
+ * ## Two safety properties, both easy to get wrong
+ *
+ * **Ownership.** Every acquisition mints a random owner token, and release and
+ * extend only succeed for the owner. Without that, a lock whose TTL expired
+ * mid-work gets picked up by process B, and process A's `release()` — arriving
+ * late — would delete *B's* lock, letting a third process in. A store must
+ * compare-and-delete, not just delete.
+ *
+ * **TTL.** A lock always expires. If a holder crashes, the lock must not be held
+ * forever, so there's no "hold until released" mode. Pick a TTL longer than the
+ * work; if the work might outrun it, `extend()` from inside.
+ */
+/**
+ * The bridge to a lock backend.
+ *
+ * Every method is keyed by `owner` for the reason above: implementations MUST
+ * make `acquire` atomic (set-if-absent) and `release`/`extend` conditional on
+ * the owner matching. A store that can't do that isn't a lock.
+ */
+export interface LockStore {
+    /** Set the key if absent. Returns whether this owner got it. Must be atomic. */
+    acquire(key: string, owner: string, ttlMs: number): Promise<boolean>;
+    /** Delete the key only if `owner` still holds it. Returns whether it did. */
+    release(key: string, owner: string): Promise<boolean>;
+    /** Push the expiry out, only if `owner` still holds it. */
+    extend(key: string, owner: string, ttlMs: number): Promise<boolean>;
+    /** Whether anyone currently holds the key. */
+    isLocked(key: string): Promise<boolean>;
+    /** Milliseconds until the key expires, or null if nobody holds it. */
+    remainingTime(key: string): Promise<number | null>;
+}
+/**
+ * An in-memory `LockStore` — the default. Per-isolate, so it coordinates
+ * *within* one process and nothing more: perfect for tests and single-process
+ * apps, useless across a cluster. Point `setLockStore()` at Redis for that.
+ */
+export declare class MemoryLockStore implements LockStore {
+    private entries;
+    /** The live entry for a key, dropping it if it has expired. */
+    private live;
+    acquire(key: string, owner: string, ttlMs: number): Promise<boolean>;
+    release(key: string, owner: string): Promise<boolean>;
+    extend(key: string, owner: string, ttlMs: number): Promise<boolean>;
+    isLocked(key: string): Promise<boolean>;
+    remainingTime(key: string): Promise<number | null>;
+}
+export interface AcquireOptions {
+    /**
+     * Give up after this many milliseconds of waiting. Default: 0 — don't wait at
+     * all, fail immediately if the lock is held.
+     */
+    timeout?: number;
+    /** Milliseconds between attempts while waiting. Default: 50. */
+    retryDelay?: number;
+}
+/** A lock that has expired or was never held. */
+export declare class LockNotHeldError extends Error {
+    constructor(key: string);
+}
+export declare class Lock {
+    readonly key: string;
+    /** How long the lock is held before it expires on its own. Milliseconds. */
+    readonly ttlMs: number;
+    private store;
+    /** Non-null only while this instance holds the lock. */
+    private owner?;
+    constructor(key: string, 
+    /** How long the lock is held before it expires on its own. Milliseconds. */
+    ttlMs: number, store: LockStore, owner?: string);
+    /**
+     * Take the lock, run `fn`, and always give it back — the form you want almost
+     * every time, because the `finally` is what stops a throwing callback from
+     * leaving the lock held until its TTL runs out.
+     *
+     * Returns `[ran, result]`: `ran` is false if someone else holds it, in which
+     * case `fn` never ran.
+     *
+     *   const [ran, invoice] = await lock("invoice:42").run(() => charge(id));
+     *   if (!ran) return;   // another worker is on it
+     */
+    run<T>(fn: () => Promise<T> | T, options?: AcquireOptions): Promise<[boolean, T | undefined]>;
+    /** `run()`, but never waits: if the lock is held, give up at once. */
+    runImmediately<T>(fn: () => Promise<T> | T): Promise<[boolean, T | undefined]>;
+    /**
+     * Take the lock, waiting up to `timeout` for it. Returns whether we got it.
+     *
+     * Prefer `run()` — with a bare `acquire()` you own the `try/finally`, and a
+     * throw between here and `release()` leaks the lock for the rest of its TTL.
+     */
+    acquire(options?: AcquireOptions): Promise<boolean>;
+    /** Take the lock only if it's free right now. */
+    acquireImmediately(): Promise<boolean>;
+    /** Give the lock back. A no-op if we no longer hold it (it may have expired). */
+    release(): Promise<boolean>;
+    /**
+     * Push the expiry out — for work that might outrun the TTL. Throws
+     * `LockNotHeldError` if we've already lost it, because the alternative (a
+     * silent no-op) would let you carry on believing you hold a lock you don't.
+     */
+    extend(ttlMs?: number): Promise<void>;
+    /** Whether *anyone* holds this key — not necessarily us. */
+    isLocked(): Promise<boolean>;
+    /** Whether we held this lock but no longer do. */
+    isExpired(): Promise<boolean>;
+    /** Milliseconds until the lock expires, or null if nobody holds it. */
+    getRemainingTime(): Promise<number | null>;
+    /**
+     * Freeze the lock (key, TTL, owner token) to a string, so another process can
+     * `restoreLock()` it and release or extend the *same* lock — the handoff you
+     * need when one process takes the lock and another finishes the work.
+     */
+    serialize(): string;
+}
+/** Register the lock store used by `lock()`. */
+export declare function setLockStore(next: LockStore): LockStore;
+/** The active lock store. */
+export declare function getLockStore(): LockStore;
+/**
+ * A lock on `key`, held for `ttlMs` once acquired (default 30s).
+ *
+ *   const [ran] = await lock("invoice:42").run(() => charge(invoice));
+ */
+export declare function lock(key: string, ttlMs?: number): Lock;
+/** Rebuild a lock from `serialize()` — same key, same TTL, same owner token. */
+export declare function restoreLock(serialized: string): Lock;

package/dist/core/lock.js

@@ -0,0 +1,215 @@
+/**
+ * Distributed locks — "only one of you may do this at a time", across processes
+ * and across nodes. The counterpart to the cache's stampede protection: that
+ * collapses concurrent work *inside one isolate*, this one coordinates work
+ * *between* them.
+ *
+ *   const [ran] = await lock("invoice:42").run(async () => charge(invoice));
+ *   if (!ran) return;   // someone else is already charging it
+ *
+ * Like every other backend in keel, the store is a small pluggable seam and the
+ * core imports no driver — `MemoryLockStore` is the built-in default (per
+ * isolate, so it's for tests and single-process apps); the locks guide has Redis
+ * and database recipes for the real thing.
+ *
+ * ## Two safety properties, both easy to get wrong
+ *
+ * **Ownership.** Every acquisition mints a random owner token, and release and
+ * extend only succeed for the owner. Without that, a lock whose TTL expired
+ * mid-work gets picked up by process B, and process A's `release()` — arriving
+ * late — would delete *B's* lock, letting a third process in. A store must
+ * compare-and-delete, not just delete.
+ *
+ * **TTL.** A lock always expires. If a holder crashes, the lock must not be held
+ * forever, so there's no "hold until released" mode. Pick a TTL longer than the
+ * work; if the work might outrun it, `extend()` from inside.
+ */
+/**
+ * An in-memory `LockStore` — the default. Per-isolate, so it coordinates
+ * *within* one process and nothing more: perfect for tests and single-process
+ * apps, useless across a cluster. Point `setLockStore()` at Redis for that.
+ */
+export class MemoryLockStore {
+    entries = new Map();
+    /** The live entry for a key, dropping it if it has expired. */
+    live(key) {
+        const entry = this.entries.get(key);
+        if (!entry)
+            return undefined;
+        if (entry.expiresAt <= Date.now()) {
+            this.entries.delete(key);
+            return undefined;
+        }
+        return entry;
+    }
+    async acquire(key, owner, ttlMs) {
+        if (this.live(key))
+            return false;
+        this.entries.set(key, { owner, expiresAt: Date.now() + ttlMs });
+        return true;
+    }
+    async release(key, owner) {
+        const entry = this.live(key);
+        if (!entry || entry.owner !== owner)
+            return false;
+        this.entries.delete(key);
+        return true;
+    }
+    async extend(key, owner, ttlMs) {
+        const entry = this.live(key);
+        if (!entry || entry.owner !== owner)
+            return false;
+        entry.expiresAt = Date.now() + ttlMs;
+        return true;
+    }
+    async isLocked(key) {
+        return this.live(key) !== undefined;
+    }
+    async remainingTime(key) {
+        const entry = this.live(key);
+        return entry ? entry.expiresAt - Date.now() : null;
+    }
+}
+/** A lock that has expired or was never held. */
+export class LockNotHeldError extends Error {
+    constructor(key) {
+        super(`The lock "${key}" is not held by you — it expired or was released.`);
+        this.name = "LockNotHeldError";
+    }
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** A random owner token. Web Crypto, so it works on Node and the edge. */
+function mintOwner() {
+    return crypto.randomUUID();
+}
+/* ---------------------------------- lock ---------------------------------- */
+export class Lock {
+    key;
+    ttlMs;
+    store;
+    /** Non-null only while this instance holds the lock. */
+    owner;
+    constructor(key, 
+    /** How long the lock is held before it expires on its own. Milliseconds. */
+    ttlMs, store, owner) {
+        this.key = key;
+        this.ttlMs = ttlMs;
+        this.store = store;
+        this.owner = owner;
+    }
+    /**
+     * Take the lock, run `fn`, and always give it back — the form you want almost
+     * every time, because the `finally` is what stops a throwing callback from
+     * leaving the lock held until its TTL runs out.
+     *
+     * Returns `[ran, result]`: `ran` is false if someone else holds it, in which
+     * case `fn` never ran.
+     *
+     *   const [ran, invoice] = await lock("invoice:42").run(() => charge(id));
+     *   if (!ran) return;   // another worker is on it
+     */
+    async run(fn, options = {}) {
+        if (!(await this.acquire(options)))
+            return [false, undefined];
+        try {
+            return [true, await fn()];
+        }
+        finally {
+            await this.release();
+        }
+    }
+    /** `run()`, but never waits: if the lock is held, give up at once. */
+    runImmediately(fn) {
+        return this.run(fn, { timeout: 0 });
+    }
+    /**
+     * Take the lock, waiting up to `timeout` for it. Returns whether we got it.
+     *
+     * Prefer `run()` — with a bare `acquire()` you own the `try/finally`, and a
+     * throw between here and `release()` leaks the lock for the rest of its TTL.
+     */
+    async acquire(options = {}) {
+        const { timeout = 0, retryDelay = 50 } = options;
+        const deadline = Date.now() + timeout;
+        const owner = mintOwner();
+        for (;;) {
+            if (await this.store.acquire(this.key, owner, this.ttlMs)) {
+                this.owner = owner;
+                return true;
+            }
+            // Wait only if there's time left to wait *and* to sleep before the deadline.
+            if (Date.now() + retryDelay >= deadline)
+                return false;
+            await sleep(retryDelay);
+        }
+    }
+    /** Take the lock only if it's free right now. */
+    acquireImmediately() {
+        return this.acquire({ timeout: 0 });
+    }
+    /** Give the lock back. A no-op if we no longer hold it (it may have expired). */
+    async release() {
+        if (!this.owner)
+            return false;
+        const released = await this.store.release(this.key, this.owner);
+        this.owner = undefined;
+        return released;
+    }
+    /**
+     * Push the expiry out — for work that might outrun the TTL. Throws
+     * `LockNotHeldError` if we've already lost it, because the alternative (a
+     * silent no-op) would let you carry on believing you hold a lock you don't.
+     */
+    async extend(ttlMs = this.ttlMs) {
+        if (!this.owner || !(await this.store.extend(this.key, this.owner, ttlMs))) {
+            this.owner = undefined;
+            throw new LockNotHeldError(this.key);
+        }
+    }
+    /** Whether *anyone* holds this key — not necessarily us. */
+    isLocked() {
+        return this.store.isLocked(this.key);
+    }
+    /** Whether we held this lock but no longer do. */
+    async isExpired() {
+        if (!this.owner)
+            return false; // never acquired — not the same as expired
+        return !(await this.store.isLocked(this.key));
+    }
+    /** Milliseconds until the lock expires, or null if nobody holds it. */
+    getRemainingTime() {
+        return this.store.remainingTime(this.key);
+    }
+    /**
+     * Freeze the lock (key, TTL, owner token) to a string, so another process can
+     * `restoreLock()` it and release or extend the *same* lock — the handoff you
+     * need when one process takes the lock and another finishes the work.
+     */
+    serialize() {
+        return JSON.stringify({ key: this.key, ttlMs: this.ttlMs, owner: this.owner });
+    }
+}
+/* --------------------------------- global --------------------------------- */
+let store = new MemoryLockStore();
+/** Register the lock store used by `lock()`. */
+export function setLockStore(next) {
+    store = next;
+    return store;
+}
+/** The active lock store. */
+export function getLockStore() {
+    return store;
+}
+/**
+ * A lock on `key`, held for `ttlMs` once acquired (default 30s).
+ *
+ *   const [ran] = await lock("invoice:42").run(() => charge(invoice));
+ */
+export function lock(key, ttlMs = 30_000) {
+    return new Lock(key, ttlMs, store);
+}
+/** Rebuild a lock from `serialize()` — same key, same TTL, same owner token. */
+export function restoreLock(serialized) {
+    const { key, ttlMs, owner } = JSON.parse(serialized);
+    return new Lock(key, ttlMs, store, owner);
+}

package/dist/core/logger.d.ts

@@ -5,8 +5,37 @@
  *
  *   logger().info("user registered", { userId: user.id });
  *   logger().error("payment failed", { orderId, error });
+ *
+ * Output goes through a `Sink` — `console` by default, but any function, so logs
+ * can go to a file, an HTTP collector, or a buffer in tests. Register extra
+ * loggers by name (`setLogger(audit, "audit")`) when a subsystem needs its own
+ * level or destination.
  */
-export type LogLevel = "debug" | "info" | "warn" | "error";
+/** Levels, quietest last. `trace` is the most verbose; `fatal` the most severe. */
+export type LogLevel = "trace" | "debug" | "info" | "warn" | "error" | "fatal";
+/** One log event, as handed to a `Sink`. */
+export interface LogRecord {
+    level: LogLevel;
+    /** ISO 8601. */
+    time: string;
+    msg: string;
+    /** Bindings merged with the call's context, after redaction. */
+    fields: Record<string, unknown>;
+}
+/** Where log lines go. Return nothing; a sink that throws is a sink that lies. */
+export type Sink = (record: LogRecord) => void;
+export interface RedactOptions {
+    /**
+     * Field paths to redact — a top-level key (`"password"`), a dot path
+     * (`"req.headers.authorization"`), or a wildcard segment (`"*.password"`,
+     * `"user.*.token"`).
+     */
+    paths: string[];
+    /** What to replace matched values with. Default: `"[redacted]"`. */
+    censor?: string;
+    /** Delete the key outright instead of censoring it. Default: false. */
+    remove?: boolean;
+}
 export interface LoggerOptions {
     /** Minimum level to emit. Default: "info". */
     level?: LogLevel;
@@ -15,20 +44,76 @@ export interface LoggerOptions {
     /** Fields merged into every log line. */
     bindings?: Record<string, unknown>;
     /**
-     * Field paths to redact from log output — top-level keys (`"password"`) or dot
-     * paths (`"req.headers.authorization"`). Matched values become `"[redacted]"`.
+     * Field paths to redact. A `string[]` is shorthand for `{ paths }` — matched
+     * values become `"[redacted]"`.
      */
-    redact?: string[];
+    redact?: string[] | RedactOptions;
+    /** Where lines go. Default: the console (`console.log` / `.warn` / `.error`). */
+    sink?: Sink;
+    /** Silence the logger entirely — nothing is emitted, at any level. */
+    enabled?: boolean;
+}
+/** The default sink: JSON to stdout, or a pretty single line when `pretty`. */
+export declare function consoleSink(pretty?: boolean): Sink;
+/** A sink that collects records in memory — for tests. Assert on `.records`. */
+export declare class MemorySink {
+    readonly records: LogRecord[];
+    /** The sink function to hand to `LoggerOptions.sink`. */
+    readonly sink: Sink;
+    /** Records at one level. */
+    at(level: LogLevel): LogRecord[];
+    /** The messages logged, in order. */
+    messages(): string[];
+    clear(): void;
 }
+/**
+ * Observe every log record emitted anywhere in the app. Returns an unsubscribe.
+ * A tap that throws is ignored — watching logs must never break logging.
+ *
+ *   const off = tapLogs((record) => store.record(record));
+ */
+export declare function tapLogs(sink: Sink): () => void;
 export declare class Logger {
     private options;
     private threshold;
+    private redact?;
+    private sink;
     constructor(options?: LoggerOptions);
+    /**
+     * Whether a level would be emitted. Check it before building an expensive
+     * context object — the work of assembling it happens whether or not the line
+     * is ever written.
+     *
+     *   if (logger().isLevelEnabled("debug")) {
+     *     logger().debug("state", { snapshot: expensiveSnapshot() });
+     *   }
+     */
+    isLevelEnabled(level: LogLevel): boolean;
+    /** Run `fn` only if `level` would be emitted — the callback form of the above. */
+    ifLevelEnabled(level: LogLevel, fn: (log: Logger) => void): void;
     private write;
+    trace(message: string, context?: Record<string, unknown>): void;
     debug(message: string, context?: Record<string, unknown>): void;
     info(message: string, context?: Record<string, unknown>): void;
     warn(message: string, context?: Record<string, unknown>): void;
     error(message: string, context?: Record<string, unknown>): void;
+    /** An unrecoverable failure — the loudest level. */
+    fatal(message: string, context?: Record<string, unknown>): void;
+    /** Log at a level chosen at runtime. */
+    log(level: LogLevel, message: string, context?: Record<string, unknown>): void;
     /** A child logger with additional bound fields (e.g. a request id). */
     child(bindings: Record<string, unknown>): Logger;
 }
+/**
+ * Register a logger under a name, so a subsystem can have its own level or
+ * destination:
+ *
+ *   setLogger(new Logger({ level: "trace", sink: auditSink }), "audit");
+ *   namedLogger("audit").trace("permission granted", { userId });
+ *
+ * The default logger is the application's `Logger` singleton — resolve that with
+ * the global `logger()` helper, not this.
+ */
+export declare function setLogger(instance: Logger, name: string): Logger;
+/** A logger registered with `setLogger`. Throws for an unknown name. */
+export declare function namedLogger(name: string): Logger;