logquill 0.3.0 → 1.0.0

package/dist/index.d.ts

@@ -1,93 +1,350 @@
-/** Log levels, shared by name and numeric weight with the logquill-python contract. */
-declare enum Level {
-    TRACE = 5,
-    DEBUG = 10,
-    INFO = 20,
-    WARN = 30,
-    ERROR = 40,
-    FATAL = 50
-}
-/** A level given as a `Level`, a level name (any case), or its numeric weight. */
-type LevelInput = Level | number | string;
-/** The level's name, e.g. `levelName(Level.INFO) === "INFO"`. */
-declare function levelName(level: Level): string;
-/** Normalize a level given as a `Level`, level name, or numeric weight. Throws if unknown. */
-declare function parseLevel(level: LevelInput): Level;
+import { P as Plugin, L as LogRecord, a as Level, b as Logger, T as Transport, c as LevelInput, F as Formatter } from './logger-CRdmCDfC.js';
+export { B as BackpressurePolicy, C as CollectingTransport, D as DispatchQueue, d as DispatchQueueOptions, e as FlushableTransport, f as FunctionPlugin, J as JSONFormatter, g as LoggerOptions, M as MiddlewareFunc, S as SpanOptions, h as Task, i as createRecord, j as hasFlush, l as levelName, p as parseLevel, u as utcTimestamp } from './logger-CRdmCDfC.js';
 
-/** The cross-language record shape shared with logquill-python. */
-interface LogRecord {
-    timestamp: string;
-    level: string;
-    logger: string;
-    message: string;
-    meta: Record<string, unknown>;
+/**
+ * Injects fixed key/value pairs into every record's `meta`.
+ * A value already present in a record's own `meta` wins over the fixed context.
+ */
+declare class ContextPlugin implements Plugin {
+    /** Fixed key/value pairs merged into every record's `meta`. */
+    readonly context: Record<string, unknown>;
+    constructor(context: Record<string, unknown>);
+    beforeLog(record: LogRecord): LogRecord;
 }
-/** ISO8601 UTC timestamp with millisecond precision, matching Python's `utc_timestamp()`. */
-declare function utcTimestamp(): string;
-declare function createRecord(params: {
-    level: Level;
-    logger: string;
-    message: string;
-    meta: Record<string, unknown>;
-}): LogRecord;
 
-/** `format(record) -> string`, per the transport contract shared with logquill-python. */
-interface Formatter {
-    format(record: LogRecord): string;
+/**
+ * The merged key/value pairs bound by every `bindContext()` block currently
+ * active in this execution context, or `{}` outside any block. Backed by
+ * `AsyncLocalStorage` (not a plain module variable) so concurrent async
+ * operations sharing one `Logger` don't see each other's bound context —
+ * the Node equivalent of Python's `contextvars`-based `current_context()`.
+ */
+declare function currentContext(): Record<string, unknown>;
+/**
+ * Runs `fn` with `values` merged into the request-scoped context for the
+ * rest of its execution — every `Logger` call underneath it, through any
+ * number of function calls and `await`s deep, picks them up in `meta`
+ * automatically, without threading them through every signature by hand:
+ *
+ * ```ts
+ * await bindContext({ requestId: "abc123" }, async () => {
+ *   await handleRequest(); // any logging in here, or in what it calls,
+ *                          // gets meta.requestId = "abc123" for free
+ * });
+ * ```
+ *
+ * Calls nest by merging: an inner `bindContext`'s value wins over an outer
+ * one on key collision, the same way an explicit call-site `meta` value
+ * always wins over anything bound here. `fn`'s return value (including a
+ * `Promise`, whose continuations stay inside the bound context across any
+ * `await`) is returned unchanged.
+ */
+declare function bindContext<T>(values: Record<string, unknown>, fn: () => T): T;
+
+/** Derives the key a record is rate-limited under. Any hashable value works — it's used as a `Map` key. */
+type RateLimitKeyFunc = (record: LogRecord) => unknown;
+/** Options for {@link RateLimitPlugin}. */
+interface RateLimitPluginOptions {
+    /** Groups records into independent windows. Default: `(logger, level)`. */
+    keyFunc?: RateLimitKeyFunc;
+    /** Distinct keys tracked at once before the least-recently-seen one is evicted. Default 1000. */
+    maxKeys?: number;
+    /** Injectable clock (seconds), for deterministic window-rollover tests. Defaults to `performance.now() / 1000` — monotonic, so a wall-clock adjustment can't shrink or extend a window. */
+    clock?: () => number;
 }
-/** Serializes a record to the canonical JSON line shape. */
-declare class JSONFormatter implements Formatter {
-    format(record: LogRecord): string;
+/**
+ * Drops records once a key — by default `(logger, level)` — exceeds
+ * `maxRecords` within a rolling `perSeconds` window, capping a noisy loop
+ * (a retry that logs the same error every iteration, a hot path that logs
+ * once per request) without silencing the logger's other messages.
+ *
+ * Each key gets its own fixed window: the count for a key resets
+ * `perSeconds` after that *key's own* first record in the current window,
+ * not a shared global clock, so unrelated keys never reset in lockstep.
+ *
+ * Pass `keyFunc` to rate-limit on something other than `(logger, level)` —
+ * e.g. per error message, or per a `meta` field identifying the caller.
+ *
+ * Bounded by `maxKeys` distinct keys tracked at once; past that, the
+ * least-recently-seen key's window is evicted to make room for a new one —
+ * the same bounded-memory trade-off `SamplingPlugin` makes for trace
+ * buffering, since an unbounded key space (e.g. rate-limiting per user id)
+ * would otherwise grow memory without limit.
+ */
+declare class RateLimitPlugin implements Plugin {
+    /** Records allowed per key within a `perSeconds` window before further records for that key are dropped. */
+    readonly maxRecords: number;
+    /** Length, in seconds, of each key's rolling window. */
+    readonly perSeconds: number;
+    /** Distinct keys tracked at once before the least-recently-seen one is evicted. */
+    readonly maxKeys: number;
+    private readonly keyFunc;
+    private readonly clock;
+    private readonly windows;
+    constructor(maxRecords: number, perSeconds: number, options?: RateLimitPluginOptions);
+    beforeLog(record: LogRecord): LogRecord | null;
+    private evictOldest;
 }
 
+/** Maps a pino numeric level to a LogQuill level. */
+type PinoLevelMap = Readonly<Record<number, Level>>;
+/** pino's default numeric levels (`trace`=10 … `fatal`=60), mapped onto the matching LogQuill level. */
+declare const DEFAULT_PINO_LEVEL_MAP: PinoLevelMap;
+/** Options for {@link LogQuillPinoDestination}. */
+interface LogQuillPinoDestinationOptions {
+    /** Overrides `DEFAULT_PINO_LEVEL_MAP` — useful for a pino instance configured with custom levels. An unmapped level falls back to `INFO`. */
+    levelMap?: PinoLevelMap;
+}
 /**
- * The plugin pipeline hooks, matching the Python hook names: `beforeLog`,
- * `afterLog`, `onError`. All hooks are optional — implement only what you need.
- * A hook that throws cannot crash logging: the pipeline catches it, routes it
- * to `onError`, and moves on.
+ * A pino `destination` — pass an instance directly as `pino(destination)`
+ * to have pino's own NDJSON output parsed back into LogQuill calls, so an
+ * existing `pino()` call site keeps working exactly as it does today while
+ * its records also flow through every LogQuill `Transport`/`Plugin`
+ * attached to the given `Logger` — handy for migrating incrementally
+ * rather than in one PR.
+ *
+ * ```ts
+ * import pino from "pino";
+ * import { Logger, LogQuillPinoDestination } from "logquill";
+ *
+ * const logquill = new Logger("app");
+ * const log = pino(new LogQuillPinoDestination(logquill));
+ *
+ * log.info({ userId: 42 }, "still works exactly as before");
+ * ```
+ *
+ * No `pino` import needed here — a destination only has to be duck-type
+ * compatible with a Node `Writable`'s `.write(chunk)`, so unlike the
+ * `winston-transport`-based bridge, this needs no dependency on `pino`
+ * itself and ships from the main entry point.
+ *
+ * pino batches writes over a fast, buffered stream, so a single `write()`
+ * call can carry more than one NDJSON line; each complete line is parsed
+ * and dispatched independently, and a line that fails to parse as JSON is
+ * skipped rather than crashing the destination.
  */
-interface Plugin {
-    /** Return a (possibly modified) record, or `null` to drop it. */
-    beforeLog?(record: LogRecord): LogRecord | null;
-    /** Called after the record has been dispatched to every transport. */
-    afterLog?(record: LogRecord): void;
-    /** Called when one of this plugin's own hooks throws. */
-    onError?(error: unknown, record: LogRecord): void;
+declare class LogQuillPinoDestination {
+    /**
+     * Pino only recognizes a bare object passed as its sole argument
+     * (`pino(destination)`, without a separate options argument) as a
+     * destination stream, rather than an options object, if it looks
+     * stream-like — checking for `.writable`/`._writableState`, the same
+     * duck-typing `stream.Writable` itself satisfies. Without this, `pino()`
+     * would silently fall back to writing to `process.stdout` instead.
+     */
+    readonly writable = true;
+    private readonly target;
+    private readonly levelMap;
+    constructor(logquillLogger: Logger, options?: LogQuillPinoDestinationOptions);
+    /** Node `Writable`-compatible write hook — splits `chunk` into NDJSON lines and dispatches each as a `Logger` call. */
+    write(chunk: string): boolean;
+    private writeLine;
+}
+
+/** Options for {@link RunPlugin}. */
+interface RunPluginOptions {
+    /** Adopt an id handed in from elsewhere (e.g. an upstream call) instead of generating a fresh `randomUUID()`. */
+    runId?: string;
 }
-/** A plain `beforeLog`-style function, as accepted by `Logger.use()` in place of a `Plugin`. */
-type MiddlewareFunc = (record: LogRecord) => LogRecord | null;
 /**
- * Wraps a plain `beforeLog`-style function as a `Plugin`. `Logger.use()`
- * builds one of these automatically when given a function instead of a
- * `Plugin` — Express/Koa-style middleware ergonomics, without needing to
- * read the `Plugin` interface first. There's no `next()` chaining: the
- * pipeline already calls hooks in sequence, so this is sugar for a
- * single-method `Plugin`, not a new execution model.
+ * Stamps `meta.runId` — a stable id grouping every record from one agent
+ * run — plus an incrementing `meta.step` counter, one per record processed
+ * through this plugin instance.
+ *
+ * Distinct from `TraceContextPlugin`'s `traceId`: `runId` scopes one agent
+ * run, `traceId` follows one request across services. A run can span
+ * multiple traces (e.g. an agent that calls several downstream services);
+ * the two ids are independent.
+ *
+ * One instance is one run: attach a fresh `RunPlugin()` per run (typically
+ * via `logger.child("agent").use(new RunPlugin())`), never a process-wide
+ * singleton shared across runs — otherwise concurrent runs would share both
+ * the run id and the step counter.
+ *
+ * A record that already carries `meta.runId` (e.g. propagated from an
+ * upstream call) keeps its existing value; `meta.step` is always set from
+ * this instance's own counter.
  */
-declare class FunctionPlugin implements Plugin {
-    private readonly func;
-    constructor(func: MiddlewareFunc);
-    beforeLog(record: LogRecord): LogRecord | null;
+declare class RunPlugin implements Plugin {
+    /** Id stamped onto `meta.runId` for every record this instance processes. */
+    readonly runId: string;
+    private step;
+    constructor(options?: RunPluginOptions);
+    beforeLog(record: LogRecord): LogRecord;
 }
 
 /**
- * Injects fixed key/value pairs into every record's `meta`.
- * A value already present in a record's own `meta` wins over the fixed context.
+ * Sets the inbound trace header for the current execution context (e.g.
+ * request-scoped HTTP middleware, before the handler runs) — the
+ * propagation mechanism framework middleware uses to hand `TraceContextPlugin`
+ * an inbound header without threading it through every log call. Backed by
+ * `AsyncLocalStorage`, so it's isolated per concurrent request. Returns a
+ * function that restores the previous value; call it (typically in a
+ * `finally` block) once the request is done.
  */
-declare class ContextPlugin implements Plugin {
-    readonly context: Record<string, unknown>;
-    constructor(context: Record<string, unknown>);
+declare function setTraceparent(value: string | undefined): () => void;
+/** The header most recently set via `setTraceparent()` for this execution context. */
+declare function getTraceparent(): string | undefined;
+/** A fresh 32-hex-char id, matching the shape of an OTel/W3C trace id. */
+declare function generateTraceId(): string;
+/**
+ * Extracts a 32-hex-char trace id from a W3C `traceparent`, AWS X-Ray
+ * `X-Amzn-Trace-Id`, or GCP `X-Cloud-Trace-Context` header value. Returns
+ * `undefined` if `header` doesn't match any of the three shapes.
+ */
+declare function parseTraceHeader(header: string): string | undefined;
+/**
+ * Best-effort, synchronous lookup of the active OpenTelemetry span's trace
+ * id via a plain `require("@opentelemetry/api")` — `@opentelemetry/api` is
+ * never a declared dependency of this package (matching `logquill-python`'s
+ * lazy `import opentelemetry`); this returns `undefined` whenever it isn't
+ * installed, or no span is currently active, rather than throwing.
+ *
+ * A `require()` (via `createRequire`) rather than a dynamic `import()` is
+ * deliberate: `Plugin.beforeLog` is synchronous, so this has to be too.
+ */
+declare function defaultResolveActiveOtelTraceId(): string | undefined;
+/** Options for {@link TraceContextPlugin}. */
+interface TraceContextPluginOptions {
+    /** `meta` key the trace id is written to. Default `"traceId"`. */
+    traceKey?: string;
+    /** An inbound trace header to resolve on every record, bypassing `setTraceparent()`. */
+    traceparent?: string;
+    /** Override for testing, or to plug in a non-Node OTel API surface. Defaults to `defaultResolveActiveOtelTraceId`. */
+    resolveActiveOtelTraceId?: () => string | undefined;
+}
+/**
+ * Stamps `meta.traceId` for cross-service correlation — distinct from
+ * `RunPlugin`'s `runId`: `traceId` follows one request across services,
+ * `runId` scopes one agent run.
+ *
+ * A record that already carries `meta[traceKey]` (e.g. because
+ * `SamplingPlugin`'s tail-based elevation, or an upstream plugin, already
+ * set one) is left alone. Otherwise resolves a trace id in priority order:
+ *
+ * 1. An active OpenTelemetry span's trace id, if `@opentelemetry/api` is
+ *    installed and a span is current — read directly, not just inbound
+ *    headers.
+ * 2. The `traceparent` constructor option, if given.
+ * 3. Whatever `setTraceparent()` most recently set for the current
+ *    execution context.
+ * 4. A freshly generated trace id, if none of the above produced one.
+ *
+ * Header parsing understands W3C `traceparent`, AWS X-Ray
+ * `X-Amzn-Trace-Id`, and GCP `X-Cloud-Trace-Context` — see
+ * `parseTraceHeader`. A header that doesn't parse is treated the same as no
+ * header: falls through to generating a new trace id.
+ */
+declare class TraceContextPlugin implements Plugin {
+    /** `meta` key the trace id is written to. */
+    readonly traceKey: string;
+    private readonly explicitTraceparent;
+    private readonly resolveActiveOtelTraceId;
+    constructor(options?: TraceContextPluginOptions);
     beforeLog(record: LogRecord): LogRecord;
+    private resolveTraceId;
 }
 
+/** The subset of an OTel `SpanContext` this processor reads. */
+interface OtelSpanContextLike {
+    /** 16-hex-char span id. */
+    spanId: string;
+}
+/** The subset of an OTel `SpanStatus` this processor reads. */
+interface OtelStatusLike {
+    /** Numeric status code — compared against OTel's `SpanStatusCode.ERROR` (`2`). */
+    code: number;
+    /** Present when the span ended with an error status; used as the `.error()` message. */
+    message?: string;
+}
+/**
+ * The subset of an OTel `Span`/`ReadableSpan`'s shape this processor reads,
+ * duck-typed so this package never declares a real dependency on
+ * `@opentelemetry/api`/`@opentelemetry/sdk-trace-base` — the same approach
+ * `TraceContextPlugin` uses for its own OTel lookup. Matches what any
+ * standard `@opentelemetry/sdk-trace-base`-backed tracer provider actually
+ * passes to a registered `SpanProcessor`.
+ */
+interface OtelSpanLike {
+    /** Span name — becomes the `.action()`/`.observation()`/`.error()` message. */
+    name: string;
+    /** Returns this span's own id (and trace id), matching an OTel `Span`'s `spanContext()`. */
+    spanContext(): OtelSpanContextLike;
+    /** Present on `@opentelemetry/sdk-trace-base` >=1.9's `Span`. */
+    parentSpanContext?: OtelSpanContextLike;
+    /** Pre-1.9 `@opentelemetry/sdk-trace-base` shape (superseded by `parentSpanContext`) — read as a fallback when that isn't present. */
+    parentSpanId?: string;
+    /** Span attributes, copied verbatim onto `meta[attributesKey]` when non-empty. */
+    attributes: Record<string, unknown>;
+    /** This span's OTel status — an error status routes the end record through `.error()` instead of `.observation()`. */
+    status: OtelStatusLike;
+    /** Wall-clock duration as an OTel `HrTime` tuple, only meaningful once the span has ended. */
+    duration: readonly [seconds: number, nanoseconds: number];
+}
+/** Options for {@link OtelSpanProcessor}. */
+interface OtelSpanProcessorOptions {
+    /** `meta` key non-empty span attributes are copied onto. Default `"attributes"`. */
+    attributesKey?: string;
+}
+/**
+ * Bridges an OpenTelemetry-native integration — the Vercel AI SDK's
+ * `experimental_telemetry` is the main JS example — into LogQuill without
+ * forcing it through the callback-handler-object model `LangChainAdapter`
+ * uses. Register an instance the same way any other span processor is
+ * registered:
+ *
+ * ```ts
+ * import { BasicTracerProvider } from "@opentelemetry/sdk-trace-base";
+ * import { OtelSpanProcessor } from "logquill";
+ *
+ * const provider = new BasicTracerProvider();
+ * provider.addSpanProcessor(new OtelSpanProcessor(log.child("agent")));
+ * ```
+ *
+ * Every span the SDK creates becomes one `.action()` call on start and one
+ * `.observation()` (or `.error()`, if the span ended with an error status)
+ * call on end — the same two-call shape `LangChainAdapter` uses for
+ * `handleToolStart`/`handleToolEnd`. Both carry the span's own `spanId`/
+ * `parentSpanId` — OTel span ids are already the same 16-hex-char shape
+ * LogQuill's own `spanId` uses, so no translation is needed — and the end
+ * call additionally carries `meta.durationMs`. Non-empty span attributes are
+ * copied onto `meta[attributesKey]` verbatim, unrenamed — mapping onto the
+ * OTel `gen_ai.*` semantic conventions is deliberately out of scope here
+ * (see the v2.0 `OTLPTransport`/`gen_ai.*` plan).
+ *
+ * Never imports `@opentelemetry/api` or `@opentelemetry/sdk-trace-base` —
+ * duck-typed against the shape a `Span`/`ReadableSpan` actually has, so
+ * `import { Logger } from "logquill"` still never requires either package
+ * to be installed.
+ */
+declare class OtelSpanProcessor {
+    private readonly log;
+    private readonly attributesKey;
+    constructor(log: Logger, options?: OtelSpanProcessorOptions);
+    /** Called by the tracer provider when a span starts — emits `.action()`. */
+    onStart(span: OtelSpanLike): void;
+    /** Called by the tracer provider when a span ends — emits `.observation()`, or `.error()` if the span's status is an error. */
+    onEnd(span: OtelSpanLike): void;
+    /** No internal buffering to flush — every span is forwarded to the `Logger` immediately. */
+    forceFlush(): Promise<void>;
+    /** No resources of its own to release; flush/close the wrapped `Logger` separately. */
+    shutdown(): Promise<void>;
+    private baseMeta;
+}
+
+/** `meta` keys (case-insensitive) `RedactPlugin` replaces by default. */
 declare const DEFAULT_REDACTED_KEYS: readonly string[];
+/** Options for {@link RedactPlugin}. */
 interface RedactPluginOptions {
+    /** Keys (case-insensitive) to redact. Default `DEFAULT_REDACTED_KEYS`. */
     keys?: readonly string[];
+    /** Placeholder a matched value is replaced with. Default `"***"`. */
     replacement?: string;
 }
 /** Replaces sensitive `meta` values, matched by key (case-insensitive), with a placeholder. */
 declare class RedactPlugin implements Plugin {
     private readonly keys;
+    /** Placeholder a matched value is replaced with. */
     readonly replacement: string;
     constructor(options?: RedactPluginOptions);
     beforeLog(record: LogRecord): LogRecord;
@@ -100,8 +357,11 @@ declare class RedactPlugin implements Plugin {
  * for anything stricter.
  */
 declare const DEFAULT_PII_PATTERNS: Readonly<Record<string, RegExp>>;
+/** Options for {@link PIIRedactPlugin}. */
 interface PIIRedactPluginOptions {
+    /** Named patterns to scan for. Default `DEFAULT_PII_PATTERNS`. */
     patterns?: Readonly<Record<string, RegExp>>;
+    /** Placeholder a matched substring is replaced with. Default `"***"`. */
     replacement?: string;
 }
 /**
@@ -125,7 +385,9 @@ interface PIIRedactPluginOptions {
  * throwing.
  */
 declare class PIIRedactPlugin implements Plugin {
+    /** Named patterns scanned for in every string `meta` value. */
     readonly patterns: Readonly<Record<string, RegExp>>;
+    /** Placeholder a matched substring is replaced with. */
     readonly replacement: string;
     constructor(options?: PIIRedactPluginOptions);
     beforeLog(record: LogRecord): LogRecord;
@@ -133,28 +395,9 @@ declare class PIIRedactPlugin implements Plugin {
     private redactText;
 }
 
-/**
- * Sink for log records, per the cross-language transport contract:
- * `format(record) -> string`, `write(formatted, record)`, `close()` on shutdown.
- */
-declare abstract class Transport {
-    formatter: Formatter;
-    constructor(formatter?: Formatter);
-    format(record: LogRecord): string;
-    abstract write(formatted: string, record: LogRecord): void;
-    /** Flush/release resources on shutdown. No-op unless a transport overrides it. */
-    close(): void;
-}
-/** In-memory transport for tests: collects every (formatted, record) pair written to it. */
-declare class CollectingTransport extends Transport {
-    readonly formatted: string[];
-    readonly records: LogRecord[];
-    closed: boolean;
-    write(formatted: string, record: LogRecord): void;
-    close(): void;
-}
-
+/** Options for {@link SamplingPlugin}. */
 interface SamplingPluginOptions {
+    /** Source of randomness for the rate check. Defaults to `Math.random`; override with a seeded/fake generator for deterministic tests. */
     rng?: () => number;
     /** `meta` key holding the trace/run id used to group buffered records. Default `"traceId"`. */
     traceKey?: string;
@@ -198,11 +441,17 @@ interface SamplingPluginOptions {
  * or high-cardinality trace grow memory without limit.
  */
 declare class SamplingPlugin implements Plugin {
+    /** Fraction of non-elevated records kept, in `[0, 1]`. */
     readonly rate: number;
+    /** `meta` key holding the trace/run id used to group buffered records. */
     readonly traceKey: string;
+    /** A record at or above this level elevates its whole trace. */
     readonly elevateAt: Level;
+    /** Transports buffered records are flushed straight to on elevation; `undefined` disables tail-based elevation. */
     readonly transports: Transport[] | undefined;
+    /** Total buffered records allowed across every trace before the oldest trace is evicted. */
     readonly maxBufferedRecords: number;
+    /** Distinct trace ids held at once before the oldest is evicted. */
     readonly maxTraces: number;
     private readonly rng;
     private readonly buffer;
@@ -215,8 +464,11 @@ declare class SamplingPlugin implements Plugin {
     private evictOldestTrace;
 }
 
+/** The hash chain's starting value — a record's `prevHash` when it's the first record in the chain. */
 declare const GENESIS_HASH: string;
+/** Options for {@link TamperEvidentPlugin}. */
 interface TamperEvidentPluginOptions {
+    /** Starting hash the chain builds from. Default `GENESIS_HASH`. Override to continue a chain started elsewhere (e.g. a previous process). */
     genesisHash?: string;
 }
 /**
@@ -249,6 +501,7 @@ declare class TamperEvidentPlugin implements Plugin {
     static verifyChain(records: Iterable<Pick<LogRecord, "timestamp" | "level" | "logger" | "message" | "meta">>, options?: TamperEvidentPluginOptions): boolean;
 }
 
+/** Options for {@link AlertingPlugin} and every concrete alert plugin that extends it. */
 interface AlertingPluginOptions {
     /** A record at or above this level fires an alert. Default `Level.ERROR`. */
     threshold?: LevelInput;
@@ -271,9 +524,10 @@ interface AlertingPluginOptions {
  * default: level + logger + message) fires `sendAlert` right away, without
  * awaiting it — so the log call that triggered it is never blocked on a
  * webhook, SMTP handshake, or any other I/O, even if the destination is
- * slow or unreachable. This stands in for the shared async dispatch queue
- * a later phase will introduce; once that queue exists, `AlertingPlugin`
- * can route through it instead of firing its own unawaited call per alert.
+ * slow or unreachable. This stands in for `Logger`'s own async dispatch
+ * queue, which doesn't yet handle alert delivery; `AlertingPlugin` could
+ * route through it instead of firing its own unawaited call per alert
+ * once it does.
  *
  * Any further record matching the same dedupe key within
  * `dedupeWindowMs` of the first is *not* sent again — it just increments a
@@ -289,8 +543,11 @@ interface AlertingPluginOptions {
  * that throws.
  */
 declare abstract class AlertingPlugin implements Plugin {
+    /** A record at or above this level fires an alert. */
     readonly threshold: Level;
+    /** How long a dedupe window stays open before a collapsed follow-up alert (if any) fires. */
     readonly dedupeWindowMs: number;
+    /** Distinct concurrent dedupe keys tracked at once; beyond this, new keys are dropped rather than tracked. */
     readonly maxTrackedKeys: number;
     private readonly dedupeKeyFn;
     private readonly windows;
@@ -312,7 +569,9 @@ declare abstract class AlertingPlugin implements Plugin {
 
 /** Posts one alert body to a Slack incoming webhook URL. Swap in a fake for tests. */
 type SlackSender = (webhookUrl: string, body: string) => Promise<void> | void;
+/** Options for {@link SlackAlertPlugin}. */
 interface SlackAlertPluginOptions extends AlertingPluginOptions {
+    /** Posts one alert. Defaults to a `fetch` POST; override for a fake or an alternate backend. */
     sender?: SlackSender;
 }
 /**
@@ -323,6 +582,7 @@ interface SlackAlertPluginOptions extends AlertingPluginOptions {
  * fake for tests or an alternate backend.
  */
 declare class SlackAlertPlugin extends AlertingPlugin {
+    /** Slack "Incoming Webhook" URL every alert is posted to. */
     readonly webhookUrl: string;
     private readonly sender;
     constructor(webhookUrl: string, options?: SlackAlertPluginOptions);
@@ -331,7 +591,9 @@ declare class SlackAlertPlugin extends AlertingPlugin {
 
 /** POSTs one PagerDuty Events API v2 payload. Swap in a fake for tests. */
 type PagerDutySender = (body: string) => Promise<void> | void;
+/** Options for {@link PagerDutyAlertPlugin}. */
 interface PagerDutyAlertPluginOptions extends AlertingPluginOptions {
+    /** Posts one Events API v2 payload. Defaults to a `fetch` POST; override for a fake or an alternate backend. */
     sender?: PagerDutySender;
 }
 /**
@@ -343,22 +605,29 @@ interface PagerDutyAlertPluginOptions extends AlertingPluginOptions {
  * swap in a fake for tests or an alternate backend.
  */
 declare class PagerDutyAlertPlugin extends AlertingPlugin {
+    /** PagerDuty Events API v2 integration key every alert is sent under. */
     readonly routingKey: string;
     private readonly sender;
     constructor(routingKey: string, options?: PagerDutyAlertPluginOptions);
     protected sendAlert(record: LogRecord, occurrences: number): Promise<void>;
 }
 
+/** One email alert, as built from a deduplicated record before being handed to `nodemailer` (or an injected `sender`). */
 interface EmailMessage {
+    /** Envelope `From` address. */
     from: string;
+    /** Envelope `To` addresses. */
     to: string[];
+    /** Subject line — the record's level and logger, with an occurrence count appended on a deduped follow-up. */
     subject: string;
+    /** Plain-text body: the message, occurrence count, timestamp, and JSON-serialized `meta`. */
     text: string;
 }
 /** Sends one email message. Swap in a fake for tests. */
 type EmailSender = (message: EmailMessage) => Promise<void> | void;
 /** The subset of a `nodemailer` transporter that `EmailAlertPlugin` needs. */
 interface NodemailerTransporterLike {
+    /** Sends one message; matches `nodemailer`'s own `Transporter.sendMail`. */
     sendMail(message: {
         from: string;
         to: string;
@@ -366,12 +635,19 @@ interface NodemailerTransporterLike {
         text: string;
     }): Promise<unknown>;
 }
+/** Options for {@link EmailAlertPlugin}. */
 interface EmailAlertPluginOptions extends AlertingPluginOptions {
+    /** SMTP server hostname. */
     smtpHost: string;
+    /** SMTP server port. */
     smtpPort: number;
+    /** Envelope `From` address for every alert. */
     fromAddr: string;
+    /** Envelope `To` addresses for every alert. */
     toAddrs: string[];
+    /** SMTP auth username. Only used if `password` is also set. */
     username?: string;
+    /** SMTP auth password. Only used if `username` is also set. */
     password?: string;
     /** `false` for an SMTP server that doesn't support STARTTLS (e.g. a local relay). Default `true`. */
     useTls?: boolean;
@@ -386,9 +662,13 @@ interface EmailAlertPluginOptions extends AlertingPluginOptions {
  * `username`/`password` are only used if both are set.
  */
 declare class EmailAlertPlugin extends AlertingPlugin {
+    /** SMTP server hostname. */
     readonly smtpHost: string;
+    /** SMTP server port. */
     readonly smtpPort: number;
+    /** Envelope `From` address for every alert. */
     readonly fromAddr: string;
+    /** Envelope `To` addresses for every alert. */
     readonly toAddrs: string[];
     private readonly username;
     private readonly password;
@@ -400,7 +680,9 @@ declare class EmailAlertPlugin extends AlertingPlugin {
     private importTransporter;
 }
 
+/** Options for {@link BatchingTransport} and every concrete batching transport that extends it. */
 interface BatchingTransportOptions {
+    /** Turns a `LogRecord` into the string this transport writes. Defaults to `JSONFormatter`. */
     formatter?: Formatter;
     /** Flush once the buffer holds this many items. Default 100. */
     maxRecords?: number;
@@ -418,7 +700,9 @@ interface BatchingTransportOptions {
  * matching `HTTPTransport`'s contract.
  */
 declare abstract class BatchingTransport<T = LogRecord> extends Transport {
+    /** Buffer is flushed once it holds this many items. */
     readonly maxRecords: number;
+    /** Buffer is flushed once its estimated byte size reaches this many bytes. */
     readonly maxBytes: number;
     private buffer;
     private bufferBytes;
@@ -427,6 +711,7 @@ declare abstract class BatchingTransport<T = LogRecord> extends Transport {
     protected toItem(formatted: string, record: LogRecord): T;
     /** Estimated byte size of one buffered item, used for the `maxBytes` bound. */
     protected sizeOf(item: T): number;
+    /** Buffers the record, flushing the batch once `maxRecords`/`maxBytes` is reached. */
     write(formatted: string, record: LogRecord): void;
     /** Send the current batch now, even if it hasn't reached a bound. */
     flush(): void;
@@ -437,17 +722,26 @@ declare abstract class BatchingTransport<T = LogRecord> extends Transport {
 
 /** One row of the fixed `logs` table schema shared across every SQL transport. */
 interface SQLLogRow {
+    /** `record.timestamp`, as ISO8601. */
     timestamp: string;
+    /** `record.level`. */
     level: string;
+    /** `record.logger`. */
     logger: string;
+    /** `record.message`. */
     message: string;
     /** `record.meta`, JSON-serialized — every SQL dialect can store this as TEXT/JSON/JSONB. */
     meta: string;
+    /** `record.meta.runId`, if present. */
     runId: string | null;
+    /** `record.meta.spanId`, if present. */
     spanId: string | null;
+    /** `record.meta.parentSpanId`, if present. */
     parentSpanId: string | null;
+    /** `record.meta.traceId`, if present. */
     traceId: string | null;
 }
+/** Options for {@link BaseSQLTransport} and every concrete SQL transport that extends it. */
 interface BaseSQLTransportOptions extends BatchingTransportOptions {
     /** Table to write into. Default `"logs"`. */
     tableName?: string;
@@ -465,7 +759,9 @@ interface BaseSQLTransportOptions extends BatchingTransportOptions {
  * Inserts are always batched — never one query per log call.
  */
 declare abstract class BaseSQLTransport extends BatchingTransport<SQLLogRow> {
+    /** Table records are inserted into. */
     readonly tableName: string;
+    /** Whether `createTableSQL()` runs before the first insert. Dev/test convenience only. */
     readonly ensureSchema: boolean;
     private schemaEnsured;
     constructor(options?: BaseSQLTransportOptions);
@@ -487,12 +783,16 @@ declare abstract class BaseSQLTransport extends BatchingTransport<SQLLogRow> {
 
 /** The subset of a `better-sqlite3` prepared statement that `SQLiteTransport` needs. */
 interface SQLiteStatementLike {
+    /** Executes the prepared statement with `params` bound positionally. */
     run(...params: unknown[]): unknown;
 }
 /** The subset of a `better-sqlite3` `Database` that `SQLiteTransport` needs. Inject a fake in tests. */
 interface SQLiteClientLike {
+    /** Runs one or more SQL statements with no return value, e.g. `createTableSQL()`. */
     exec(sql: string): unknown;
+    /** Compiles `sql` into a reusable, repeatedly-`run`-able statement. */
     prepare(sql: string): SQLiteStatementLike;
+    /** Wraps `fn` so every call runs inside a single SQLite transaction. */
     transaction<Args extends unknown[]>(fn: (...args: Args) => void): (...args: Args) => void;
 }
 interface SQLiteTransportOptions extends BaseSQLTransportOptions {
@@ -523,6 +823,7 @@ declare class SQLiteTransport extends BaseSQLTransport {
 
 /** The subset of a `pg` `Pool`/`Client` that `PostgresTransport` needs. Inject a fake in tests. */
 interface PgClientLike {
+    /** Runs a parameterized query, matching `pg`'s own `Pool`/`Client.query(text, values)`. */
     query(text: string, values: unknown[]): Promise<unknown>;
 }
 interface PostgresTransportOptions extends BaseSQLTransportOptions {
@@ -558,6 +859,7 @@ declare class PostgresTransport extends BaseSQLTransport {
 
 /** The subset of a `mysql2/promise` connection/pool that `MySQLTransport` needs. Inject a fake in tests. */
 interface MySQLClientLike {
+    /** Runs a parameterized query, matching `mysql2`'s own `Connection`/`Pool.execute(sql, values)`. */
     execute(sql: string, values: unknown[]): Promise<unknown>;
 }
 interface MySQLTransportOptions extends BaseSQLTransportOptions {
@@ -594,15 +896,20 @@ declare class MySQLTransport extends BaseSQLTransport {
 
 /** The subset of a `mongodb` `Collection` that `MongoDBTransport` needs. Inject a fake in tests. */
 interface MongoCollectionLike {
+    /** Inserts every document in one call, matching `mongodb`'s own `Collection.insertMany()`. */
     insertMany(docs: readonly unknown[]): Promise<unknown>;
 }
 /** The subset of a `mongodb` `MongoClient` that `MongoDBTransport` needs to lazily connect. */
 interface MongoClientLike {
+    /** Opens the connection, matching `mongodb`'s own `MongoClient.connect()`. */
     connect(): Promise<unknown>;
+    /** Returns a database handle, from which a collection is looked up by name. */
     db(name: string): {
+        /** Returns a collection handle for `name`, matching `mongodb`'s own `Db.collection()`. */
         collection(name: string): MongoCollectionLike;
     };
 }
+/** Options for {@link MongoDBTransport}. */
 interface MongoDBTransportOptions extends BatchingTransportOptions {
     /** Pre-built collection, e.g. for tests, or an already-connected app. Skips the `mongodb` auto-import entirely. */
     collection?: MongoCollectionLike;
@@ -636,14 +943,23 @@ declare class MongoDBTransport extends BatchingTransport {
 
 /** One item written to DynamoDB: `runId` is the partition key, `timestamp` is the sort key. */
 interface DynamoLogItem {
+    /** Partition key: `record.meta.runId`, else `record.meta.traceId`, else the logger name. */
     runId: string;
+    /** Sort key: `record.timestamp`, as ISO8601. */
     timestamp: string;
+    /** `record.level`. */
     level: string;
+    /** `record.logger`. */
     logger: string;
+    /** `record.message`. */
     message: string;
+    /** `record.meta`, stored as-is (DynamoDB items are schemaless). */
     meta: Record<string, unknown>;
+    /** `record.meta.spanId`, if present. */
     spanId?: string;
+    /** `record.meta.parentSpanId`, if present. */
     parentSpanId?: string;
+    /** `record.meta.traceId`, if present. */
     traceId?: string;
 }
 /**
@@ -656,8 +972,10 @@ interface DynamoLogItem {
  * `@aws-sdk/client-dynamodb` wrapper by not injecting a `client`.
  */
 interface DynamoClientLike {
+    /** Writes one chunk of items (already capped at `DYNAMO_BATCH_LIMIT`) to `tableName` via a `BatchWriteItem`-equivalent call. */
     batchWriteItems(tableName: string, items: readonly DynamoLogItem[]): Promise<unknown>;
 }
+/** Options for {@link DynamoDBTransport}. */
 interface DynamoDBTransportOptions extends BatchingTransportOptions {
     /** Pre-built client, e.g. for tests, or a custom wrapper. Skips the `@aws-sdk/client-dynamodb` auto-import entirely. */
     client?: DynamoClientLike;
@@ -698,8 +1016,10 @@ declare class DynamoDBTransport extends BatchingTransport {
 
 /** The subset of a `redis` (node-redis v4) client that `RedisTransport` needs. Inject a fake in tests. */
 interface RedisClientLike {
+    /** Appends one entry to `stream`, matching `node-redis`'s own `client.xAdd()`. */
     xAdd(stream: string, id: string, fields: Record<string, string>): Promise<unknown>;
 }
+/** Options for {@link RedisTransport}. */
 interface RedisTransportOptions extends BatchingTransportOptions {
     /** Pre-built, already-connected client, e.g. for tests. Skips the `redis` auto-import entirely. */
     client?: RedisClientLike;
@@ -709,9 +1029,9 @@ interface RedisTransportOptions extends BatchingTransportOptions {
     stream?: string;
 }
 /**
- * Sink for Redis, via Redis Streams (`XADD`) — as CLAUDE.md's spec puts it,
- * "a fast local buffer, a different use case from durable storage, not a
- * replacement for the others." Reach for this when you want a low-latency
+ * Sink for Redis, via Redis Streams (`XADD`) — a fast local buffer, a
+ * different use case from durable storage, not a replacement for the
+ * others. Reach for this when you want a low-latency
  * local tail (e.g. feeding a `redis-cli XREAD`-based live viewer) rather than
  * a system of record.
  *
@@ -738,6 +1058,7 @@ declare class RedisTransport extends BatchingTransport {
     protected sendBatch(batch: readonly LogRecord[]): Promise<void>;
 }
 
+/** Options for {@link BaseQueueTransport} and every concrete queue transport that extends it. */
 interface BaseQueueTransportOptions extends BatchingTransportOptions {
     /**
      * Destination name on the backend — a Kafka topic, a RabbitMQ queue name,
@@ -756,6 +1077,7 @@ interface BaseQueueTransportOptions extends BatchingTransportOptions {
  * `publishBatch()` against its own driver's publish API.
  */
 declare abstract class BaseQueueTransport extends BatchingTransport {
+    /** Destination name on the backend — a Kafka topic, a RabbitMQ queue name, an SQS queue URL, or a GCP Pub/Sub topic. */
     readonly topic: string;
     constructor(options: BaseQueueTransportOptions);
     protected sendBatch(batch: readonly LogRecord[]): Promise<void>;
@@ -767,6 +1089,7 @@ declare abstract class BaseQueueTransport extends BatchingTransport {
 interface KafkaProducerLike {
     /** Optional: some injected producers (or fakes) are already connected. */
     connect?(): Promise<void>;
+    /** Publishes one batch of messages to a topic, matching `kafkajs`'s own `Producer.send()`. */
     send(record: {
         topic: string;
         messages: {
@@ -813,6 +1136,7 @@ declare class KafkaTransport extends BaseQueueTransport {
 interface AmqpChannelLike {
     /** Optional: only called once, and only when provided, to ensure the queue exists. */
     assertQueue?(queue: string, options?: unknown): Promise<unknown>;
+    /** Publishes one message directly to `queue`, matching `amqplib`'s own `Channel.sendToQueue()`. */
     sendToQueue(queue: string, content: Buffer, options?: unknown): boolean;
 }
 interface RabbitMQTransportOptions extends BaseQueueTransportOptions {
@@ -860,6 +1184,7 @@ declare class RabbitMQTransport extends BaseQueueTransport {
  * a fake in tests, or wrap a real `SQSClient` to match this shape.
  */
 interface SQSClientLike {
+    /** Sends one chunk of entries (already capped at SQS's 10-message `SendMessageBatch` limit) to `queueUrl`. */
     sendMessageBatch(queueUrl: string, entries: {
         id: string;
         body: string;
@@ -898,6 +1223,7 @@ declare class SQSTransport extends BaseQueueTransport {
  * needs. Inject a fake in tests, or an already-resolved `Topic` instance.
  */
 interface PubSubTopicLike {
+    /** Publishes one message, matching `@google-cloud/pubsub`'s own `Topic.publishMessage()`. */
     publishMessage(message: {
         data: Buffer;
     }): Promise<string>;
@@ -932,7 +1258,9 @@ declare class PubSubTransport extends BaseQueueTransport {
 
 /** One CloudWatch Logs event: epoch-milliseconds timestamp plus a single log line. */
 interface CloudWatchLogEvent {
+    /** Epoch-milliseconds timestamp. */
     timestamp: number;
+    /** Formatted log line. */
     message: string;
 }
 /**
@@ -943,8 +1271,10 @@ interface CloudWatchLogEvent {
  * small for tests; `importClient()` builds the real adapter around it.
  */
 interface CloudWatchClientLike {
+    /** Sends one already timestamp-sorted batch of events to `logGroupName`/`logStreamName`. */
     putLogEvents(logGroupName: string, logStreamName: string, events: readonly CloudWatchLogEvent[]): Promise<unknown>;
 }
+/** Options for {@link CloudWatchTransport}. */
 interface CloudWatchTransportOptions extends BatchingTransportOptions {
     /** CloudWatch Logs log group to write into. */
     logGroupName: string;
@@ -966,8 +1296,11 @@ interface CloudWatchTransportOptions extends BatchingTransportOptions {
  * `CloudWatchLogsClient` wrapped to match `CloudWatchClientLike`).
  */
 declare class CloudWatchTransport extends BatchingTransport {
+    /** CloudWatch Logs log group written into. */
     readonly logGroupName: string;
+    /** CloudWatch Logs log stream, within `logGroupName`, written into. */
     readonly logStreamName: string;
+    /** AWS region passed to the real SDK client; `undefined` when `client` is injected or the SDK's own credential-chain resolution is used. */
     readonly region: string | undefined;
     private readonly injectedClient;
     private client;
@@ -980,8 +1313,11 @@ declare class CloudWatchTransport extends BatchingTransport {
 
 /** One GCP Cloud Logging entry, shaped for `Log#write`. */
 interface CloudLoggingEntry {
+    /** Cloud Logging `LogSeverity` value, mapped from the record's level. */
     severity: string;
+    /** ISO8601 timestamp. */
     timestamp: string;
+    /** The record, JSON-decoded, as Cloud Logging's structured payload. */
     jsonPayload: Record<string, unknown>;
 }
 /**
@@ -990,8 +1326,10 @@ interface CloudLoggingEntry {
  * `importClient()` builds the real adapter around `logging.log(name).write(entries)`.
  */
 interface CloudLoggingClientLike {
+    /** Writes one batch of entries to the configured log. */
     writeLogEntries(entries: readonly CloudLoggingEntry[]): Promise<unknown>;
 }
+/** Options for {@link CloudLoggingTransport}. */
 interface CloudLoggingTransportOptions extends BatchingTransportOptions {
     /** GCP log name (the last segment of the log resource path). Default `"logquill"`. */
     logName?: string;
@@ -1010,7 +1348,9 @@ interface CloudLoggingTransportOptions extends BatchingTransportOptions {
  * `Log` wrapped to match `CloudLoggingClientLike`).
  */
 declare class CloudLoggingTransport extends BatchingTransport {
+    /** GCP log name (the last segment of the log resource path). */
     readonly logName: string;
+    /** GCP project ID passed to the real SDK client; `undefined` when `client` is injected or Application Default Credentials' project is used. */
     readonly projectId: string | undefined;
     private readonly injectedClient;
     private client;
@@ -1023,7 +1363,9 @@ declare class CloudLoggingTransport extends BatchingTransport {
 
 /** One Application Insights trace: a message plus its `SeverityLevel`. */
 interface AppInsightsTrace {
+    /** Formatted log line. */
     message: string;
+    /** Application Insights `SeverityLevel` value, mapped from the record's level. */
     severity: number;
 }
 /**
@@ -1039,8 +1381,10 @@ interface AppInsightsTrace {
  * batch call — Application Insights doesn't offer one.
  */
 interface AppInsightsClientLike {
+    /** Tracks every trace in the batch, then flushes once at the end. */
     trackTraceBatch(traces: readonly AppInsightsTrace[]): Promise<unknown>;
 }
+/** Options for {@link AppInsightsTransport}. */
 interface AppInsightsTransportOptions extends BatchingTransportOptions {
     /** Azure Application Insights connection string. Passed to the real SDK client; ignored when `client` is injected. */
     connectionString?: string;
@@ -1059,6 +1403,7 @@ interface AppInsightsTransportOptions extends BatchingTransportOptions {
  * wrapped to match `AppInsightsClientLike`).
  */
 declare class AppInsightsTransport extends BatchingTransport {
+    /** Azure Application Insights connection string passed to the real SDK client; `undefined` when `client` is injected. */
     readonly connectionString: string | undefined;
     private readonly injectedClient;
     private client;
@@ -1071,6 +1416,7 @@ declare class AppInsightsTransport extends BatchingTransport {
 
 /** Sends one batch of formatted lines to Datadog's Logs intake API at `url`. Swap in a fake for tests. */
 type DatadogSender = (url: string, apiKey: string, batch: readonly string[]) => Promise<void> | void;
+/** Options for {@link DatadogTransport}. */
 interface DatadogTransportOptions extends BatchingTransportOptions {
     /** Datadog API key, sent in the `DD-API-KEY` header. */
     apiKey: string;
@@ -1081,6 +1427,7 @@ interface DatadogTransportOptions extends BatchingTransportOptions {
      * region's intake host silently fails to deliver logs to your account.
      */
     site?: string;
+    /** Delivers one batch. Defaults to a `fetch` POST; override for a fake or a different delivery mechanism. */
     sender?: DatadogSender;
 }
 /**
@@ -1089,8 +1436,11 @@ interface DatadogTransportOptions extends BatchingTransportOptions {
  * `sender` to swap in a fake for tests, or a different delivery mechanism.
  */
 declare class DatadogTransport extends BatchingTransport {
+    /** Logs intake endpoint derived from `site`. */
     readonly url: string;
+    /** Datadog API key sent in the `DD-API-KEY` header. */
     readonly apiKey: string;
+    /** Datadog site (region) this transport sends to. */
     readonly site: string;
     private readonly sender;
     constructor(options: DatadogTransportOptions);
@@ -1099,6 +1449,7 @@ declare class DatadogTransport extends BatchingTransport {
 
 /** Sends one pre-built NDJSON `_bulk` body to `url` with the given headers. Swap in a fake for tests. */
 type ElasticsearchSender = (url: string, headers: Readonly<Record<string, string>>, body: string) => Promise<void> | void;
+/** Options for {@link ElasticsearchTransport}. */
 interface ElasticsearchTransportOptions extends BatchingTransportOptions {
     /** Cluster base URL, e.g. `"https://localhost:9200"`. */
     node: string;
@@ -1106,6 +1457,7 @@ interface ElasticsearchTransportOptions extends BatchingTransportOptions {
     index?: string;
     /** Elasticsearch API key (base64 `id:api_key`), sent as `Authorization: ApiKey <apiKey>`. Omit to send no auth header (e.g. behind a proxy that adds its own). */
     apiKey?: string;
+    /** Delivers one NDJSON `_bulk` body. Defaults to a `fetch` POST; override for a fake or a different delivery mechanism. */
     sender?: ElasticsearchSender;
 }
 /**
@@ -1115,7 +1467,9 @@ interface ElasticsearchTransportOptions extends BatchingTransportOptions {
  * to swap in a fake for tests, or a different delivery mechanism.
  */
 declare class ElasticsearchTransport extends BatchingTransport {
+    /** `_bulk` endpoint derived from the `node` option. */
     readonly url: string;
+    /** Index written into. */
     readonly index: string;
     private readonly apiKey;
     private readonly sender;
@@ -1127,13 +1481,16 @@ declare class ElasticsearchTransport extends BatchingTransport {
 type NewRelicRegion = "US" | "EU";
 /** What `NewRelicSender` reports back about one delivery attempt, so the transport can drive its own 429 backoff logic. */
 interface NewRelicSenderResult {
+    /** `true` for a 2xx response. */
     ok: boolean;
+    /** HTTP status code of the response. */
     status: number;
     /** The raw `Retry-After` response header value, if present — either a number of seconds or an HTTP-date, per RFC 9110. */
     retryAfter: string | null;
 }
 /** Sends one gzip-compressed batch to New Relic's Log API at `url`. Swap in a fake for tests. */
 type NewRelicSender = (url: string, headers: Readonly<Record<string, string>>, body: Buffer) => Promise<NewRelicSenderResult> | NewRelicSenderResult;
+/** Options for {@link NewRelicTransport}. */
 interface NewRelicTransportOptions extends BatchingTransportOptions {
     /** New Relic license key, sent in the `Api-Key` header. */
     licenseKey: string;
@@ -1144,6 +1501,7 @@ interface NewRelicTransportOptions extends BatchingTransportOptions {
      * vice versa) is rejected. Default `"US"`.
      */
     region?: NewRelicRegion;
+    /** Delivers one gzip-compressed batch. Defaults to a `fetch` POST; override for a fake or to intercept 429s in tests. */
     sender?: NewRelicSender;
     /** Injectable clock for the 429 backoff window, matching `SamplingPlugin`'s injectable `rng`. Default `Date.now`. */
     clock?: () => number;
@@ -1160,7 +1518,9 @@ interface NewRelicTransportOptions extends BatchingTransportOptions {
  * backoff tests without waiting on a real clock.
  */
 declare class NewRelicTransport extends BatchingTransport {
+    /** Ingest endpoint derived from `region`. */
     readonly url: string;
+    /** New Relic account region this transport sends to. */
     readonly region: NewRelicRegion;
     private readonly licenseKey;
     private readonly sender;
@@ -1172,12 +1532,18 @@ declare class NewRelicTransport extends BatchingTransport {
 
 /** The subset of `console` this transport needs — swap in a fake for tests. */
 interface ConsoleLike {
+    /** Writes one already-formatted line, e.g. for a TRACE–WARN record. */
     log(message: string): void;
+    /** Writes one already-formatted line, e.g. for an ERROR/FATAL record. */
     error(message: string): void;
 }
+/** Options for {@link ConsoleTransport}. */
 interface ConsoleTransportOptions {
+    /** Turns a `LogRecord` into the string this transport writes. Defaults to `JSONFormatter`. */
     formatter?: Formatter;
+    /** Wrap each line in an ANSI color escape for its level. Defaults to `true` unless the `NO_COLOR` env var is set. */
     colorize?: boolean;
+    /** Sink to write through instead of the global `console` — swap in a fake for tests. */
     console?: ConsoleLike;
 }
 /**
@@ -1186,25 +1552,68 @@ interface ConsoleTransportOptions {
  * so this transport works unmodified in a browser bundle.
  */
 declare class ConsoleTransport extends Transport {
+    /** Whether each line is wrapped in an ANSI color escape for its level. */
     colorize: boolean;
     private readonly out;
     constructor(options?: ConsoleTransportOptions);
+    /** Writes `formatted` via `console.log`, or `console.error` for ERROR/FATAL records. */
     write(formatted: string, record: LogRecord): void;
     private applyColor;
 }
 
+/** Sends one batch of formatted lines to `url`. Swap in a fake for tests. */
+type BeaconSender = (url: string, batch: readonly string[]) => void;
+/** Options for {@link BeaconTransport}. */
+interface BeaconTransportOptions {
+    /** Turns a `LogRecord` into the string this transport writes. Defaults to `JSONFormatter`. */
+    formatter?: Formatter;
+    /** Flush once the buffer holds this many lines. Default 20 — kept low since `sendBeacon` payloads are capped. */
+    batchSize?: number;
+    /** Delivers one batch. Defaults to `sendBeacon` with a `fetch(..., { keepalive: true })` fallback; override for a fake or a different backend. */
+    sender?: BeaconSender;
+}
+/**
+ * Batches formatted records and sends them via `navigator.sendBeacon`,
+ * falling back to a `keepalive` `fetch` where `sendBeacon` isn't available.
+ * Meant for the browser: unlike `HTTPTransport`, a beacon send can complete
+ * even after the page that queued it starts unloading. Keep `batchSize`
+ * small — `sendBeacon` payloads are capped (64KB in most browsers).
+ */
+declare class BeaconTransport extends Transport {
+    /** Endpoint each batch is sent to. */
+    readonly url: string;
+    /** Buffer is flushed once it holds this many lines. */
+    readonly batchSize: number;
+    private readonly sender;
+    private batch;
+    constructor(url: string, options?: BeaconTransportOptions);
+    /** Buffers the formatted line, flushing the batch once `batchSize` is reached. */
+    write(formatted: string): void;
+    /** Send the current batch now, even if it hasn't reached `batchSize`. */
+    flush(): void;
+    close(): void;
+}
+
+/** Options for {@link FileTransport}. */
 interface FileTransportOptions {
+    /** Turns a `LogRecord` into the string this transport writes. Defaults to `JSONFormatter`. */
     formatter?: Formatter;
+    /** Rotate once the file reaches this many bytes. `0` disables rotation. Default 10MB. */
     maxBytes?: number;
+    /** How many rotated backups (`.1`, `.2`, ...) to keep. The oldest is deleted once exceeded. Default 5. */
     backupCount?: number;
 }
 /** Appends formatted records to a file, rotating when it exceeds `maxBytes`. */
 declare class FileTransport extends Transport {
+    /** Path of the file records are appended to. */
     readonly path: string;
+    /** File is rotated once it reaches this many bytes. `0` disables rotation. */
     readonly maxBytes: number;
+    /** How many rotated backups (`.1`, `.2`, ...) are kept. */
     readonly backupCount: number;
     private fd;
     constructor(path: string, options?: FileTransportOptions);
+    /** Appends one formatted line to the file, rotating first if `maxBytes` has been exceeded. */
     write(formatted: string): void;
     private rotate;
     close(): void;
@@ -1212,9 +1621,13 @@ declare class FileTransport extends Transport {
 
 /** Sends one batch of formatted lines to `url`. Swap in a fake for tests. */
 type Sender = (url: string, batch: readonly string[]) => Promise<void> | void;
+/** Options for {@link HTTPTransport}. */
 interface HTTPTransportOptions {
+    /** Turns a `LogRecord` into the string this transport writes. Defaults to `JSONFormatter`. */
     formatter?: Formatter;
+    /** Flush once the buffer holds this many lines. Default 50. */
     batchSize?: number;
+    /** Delivers one batch. Defaults to a `fetch` POST of newline-delimited JSON; override for a fake or a different backend. */
     sender?: Sender;
 }
 /**
@@ -1222,53 +1635,75 @@ interface HTTPTransportOptions {
  * Pass `sender` to swap in a fake for tests, or a different backend.
  */
 declare class HTTPTransport extends Transport {
+    /** Endpoint each batch is POSTed to. */
     readonly url: string;
+    /** Buffer is flushed once it holds this many lines. */
     readonly batchSize: number;
     private readonly sender;
     private batch;
     constructor(url: string, options?: HTTPTransportOptions);
+    /** Buffers the formatted line, flushing the batch once `batchSize` is reached. */
     write(formatted: string): void;
     /** Send the current batch now, even if it hasn't reached `batchSize`. */
     flush(): void;
     close(): void;
 }
 
-interface LoggerOptions {
-    level?: LevelInput;
-    transports?: Transport[];
-    plugins?: (Plugin | MiddlewareFunc)[];
-    meta?: Record<string, unknown>;
-}
-declare class Logger {
-    readonly name: string;
-    readonly transports: Transport[];
-    readonly plugins: Plugin[];
-    private currentLevel;
-    private readonly baseMeta;
-    constructor(name: string, options?: LoggerOptions);
-    get level(): Level;
-    setLevel(level: LevelInput): void;
-    /**
-     * Register a plugin, or a plain `beforeLog`-style function. A function is
-     * wrapped internally as an anonymous `Plugin` (`FunctionPlugin`) — the
-     * same middleware ergonomics as Express/Koa, without needing to read the
-     * `Plugin` interface first. Returns `this` so calls can be chained.
-     */
-    use(plugin: Plugin | MiddlewareFunc): this;
-    /** Close every attached transport. Call on shutdown to flush buffered writes. */
-    close(): void;
-    /** A logger scoped under this one, inheriting its level, transports, and plugins. */
-    child(name: string, meta?: Record<string, unknown>): Logger;
-    private notifyError;
-    private dispatch;
-    trace(message: string, meta?: Record<string, unknown>): LogRecord | null;
-    debug(message: string, meta?: Record<string, unknown>): LogRecord | null;
-    info(message: string, meta?: Record<string, unknown>): LogRecord | null;
-    warn(message: string, meta?: Record<string, unknown>): LogRecord | null;
-    error(message: string, meta?: Record<string, unknown>): LogRecord | null;
-    fatal(message: string, meta?: Record<string, unknown>): LogRecord | null;
+/**
+ * Wraps a serverless handler so `logger.flush()` is awaited before the
+ * wrapped function returns or throws. A serverless runtime can freeze or
+ * recycle its execution environment the instant a handler settles, so
+ * anything still sitting in the dispatch queue — or a batching transport's
+ * own buffer — needs to be sent before that happens, not left for an
+ * invocation that may not come for a while (or ever, if the environment is
+ * torn down instead of frozen).
+ *
+ * The handler shape itself doesn't matter here — only that `fn` is an async
+ * function whose settling is the runtime's cue to freeze — so the same
+ * wrapper covers AWS Lambda, GCP Cloud Functions, and Azure Functions
+ * equally; `withLambda`/`withCloudFunction`/`withAzureFunction` are the same
+ * function under names that match each platform's docs.
+ *
+ * ```ts
+ * export const handler = withLambda(logger, async (event) => {
+ *   logger.info("handling request", { requestId: event.requestId });
+ *   return { statusCode: 200 };
+ * });
+ * ```
+ */
+declare function withFlush<Args extends unknown[], TResult>(logger: Logger, fn: (...args: Args) => Promise<TResult>): (...args: Args) => Promise<TResult>;
+/** `withFlush`, named for an AWS Lambda handler. */
+declare const withLambda: typeof withFlush;
+/** `withFlush`, named for a GCP Cloud Functions handler. */
+declare const withCloudFunction: typeof withFlush;
+/** `withFlush`, named for an Azure Functions handler. */
+declare const withAzureFunction: typeof withFlush;
+
+/** Options for {@link installShutdownHandlers}. */
+interface ShutdownHandlerOptions {
+    /** Signals to flush-and-close on (e.g. an orchestrator's SIGTERM). Default `["SIGTERM", "SIGINT"]`. */
+    signals?: NodeJS.Signals[];
 }
+/**
+ * Registers listeners so `logger.close()` runs once as the process ends —
+ * on `beforeExit` (the event loop draining naturally) and on the given
+ * `signals` (a container/orchestrator asking the process to stop) — so
+ * whatever is still in the dispatch queue or a batching transport's buffer
+ * isn't silently lost. Node-only (uses `process`); don't call this from a
+ * browser bundle.
+ *
+ * Registering a listener for a signal like `SIGTERM` opts this process out
+ * of Node's default "terminate immediately" behavior for it, so this
+ * function calls `process.exit(0)` itself once `close()` settles — `
+ * beforeExit` doesn't need that, since the process is already on its way
+ * out there.
+ *
+ * Returns a function that removes the listeners again — call it in tests,
+ * or if the caller wants to manage its own shutdown lifecycle instead.
+ */
+declare function installShutdownHandlers(logger: Logger, options?: ShutdownHandlerOptions): () => void;
 
+/** This package's version, matching `package.json`'s `version` field. */
 declare const VERSION = "0.3.0";
 
-export { AlertingPlugin, type AlertingPluginOptions, type AmqpChannelLike, type AppInsightsClientLike, type AppInsightsTrace, AppInsightsTransport, type AppInsightsTransportOptions, BaseQueueTransport, type BaseQueueTransportOptions, BaseSQLTransport, type BaseSQLTransportOptions, BatchingTransport, type BatchingTransportOptions, type CloudLoggingClientLike, type CloudLoggingEntry, CloudLoggingTransport, type CloudLoggingTransportOptions, type CloudWatchClientLike, type CloudWatchLogEvent, CloudWatchTransport, type CloudWatchTransportOptions, CollectingTransport, type ConsoleLike, ConsoleTransport, type ConsoleTransportOptions, ContextPlugin, DEFAULT_PII_PATTERNS, DEFAULT_REDACTED_KEYS, type DatadogSender, DatadogTransport, type DatadogTransportOptions, type DynamoClientLike, DynamoDBTransport, type DynamoDBTransportOptions, type DynamoLogItem, type ElasticsearchSender, ElasticsearchTransport, type ElasticsearchTransportOptions, EmailAlertPlugin, type EmailAlertPluginOptions, type EmailMessage, type EmailSender, FileTransport, type FileTransportOptions, type Formatter, FunctionPlugin, GENESIS_HASH, HTTPTransport, type HTTPTransportOptions, JSONFormatter, type KafkaProducerLike, KafkaTransport, type KafkaTransportOptions, Level, type LevelInput, type LogRecord, Logger, type LoggerOptions, type MiddlewareFunc, type MongoClientLike, type MongoCollectionLike, MongoDBTransport, type MongoDBTransportOptions, type MySQLClientLike, MySQLTransport, type MySQLTransportOptions, type NewRelicRegion, type NewRelicSender, type NewRelicSenderResult, NewRelicTransport, type NewRelicTransportOptions, type NodemailerTransporterLike, PIIRedactPlugin, type PIIRedactPluginOptions, PagerDutyAlertPlugin, type PagerDutyAlertPluginOptions, type PagerDutySender, type PgClientLike, type Plugin, PostgresTransport, type PostgresTransportOptions, type PubSubTopicLike, PubSubTransport, type PubSubTransportOptions, RabbitMQTransport, type RabbitMQTransportOptions, RedactPlugin, type RedactPluginOptions, type RedisClientLike, RedisTransport, type RedisTransportOptions, type SQLLogRow, type SQLiteClientLike, type SQLiteStatementLike, SQLiteTransport, type SQLiteTransportOptions, type SQSClientLike, SQSTransport, type SQSTransportOptions, SamplingPlugin, type SamplingPluginOptions, type Sender, SlackAlertPlugin, type SlackAlertPluginOptions, type SlackSender, TamperEvidentPlugin, type TamperEvidentPluginOptions, Transport, VERSION, createRecord, levelName, parseLevel, utcTimestamp };
+export { AlertingPlugin, type AlertingPluginOptions, type AmqpChannelLike, type AppInsightsClientLike, type AppInsightsTrace, AppInsightsTransport, type AppInsightsTransportOptions, BaseQueueTransport, type BaseQueueTransportOptions, BaseSQLTransport, type BaseSQLTransportOptions, BatchingTransport, type BatchingTransportOptions, type BeaconSender, BeaconTransport, type BeaconTransportOptions, type CloudLoggingClientLike, type CloudLoggingEntry, CloudLoggingTransport, type CloudLoggingTransportOptions, type CloudWatchClientLike, type CloudWatchLogEvent, CloudWatchTransport, type CloudWatchTransportOptions, type ConsoleLike, ConsoleTransport, type ConsoleTransportOptions, ContextPlugin, DEFAULT_PII_PATTERNS, DEFAULT_PINO_LEVEL_MAP, DEFAULT_REDACTED_KEYS, type DatadogSender, DatadogTransport, type DatadogTransportOptions, type DynamoClientLike, DynamoDBTransport, type DynamoDBTransportOptions, type DynamoLogItem, type ElasticsearchSender, ElasticsearchTransport, type ElasticsearchTransportOptions, EmailAlertPlugin, type EmailAlertPluginOptions, type EmailMessage, type EmailSender, FileTransport, type FileTransportOptions, Formatter, GENESIS_HASH, HTTPTransport, type HTTPTransportOptions, type KafkaProducerLike, KafkaTransport, type KafkaTransportOptions, Level, LevelInput, LogQuillPinoDestination, type LogQuillPinoDestinationOptions, LogRecord, Logger, type MongoClientLike, type MongoCollectionLike, MongoDBTransport, type MongoDBTransportOptions, type MySQLClientLike, MySQLTransport, type MySQLTransportOptions, type NewRelicRegion, type NewRelicSender, type NewRelicSenderResult, NewRelicTransport, type NewRelicTransportOptions, type NodemailerTransporterLike, type OtelSpanContextLike, type OtelSpanLike, OtelSpanProcessor, type OtelSpanProcessorOptions, type OtelStatusLike, PIIRedactPlugin, type PIIRedactPluginOptions, PagerDutyAlertPlugin, type PagerDutyAlertPluginOptions, type PagerDutySender, type PgClientLike, type PinoLevelMap, Plugin, PostgresTransport, type PostgresTransportOptions, type PubSubTopicLike, PubSubTransport, type PubSubTransportOptions, RabbitMQTransport, type RabbitMQTransportOptions, type RateLimitKeyFunc, RateLimitPlugin, type RateLimitPluginOptions, RedactPlugin, type RedactPluginOptions, type RedisClientLike, RedisTransport, type RedisTransportOptions, RunPlugin, type RunPluginOptions, type SQLLogRow, type SQLiteClientLike, type SQLiteStatementLike, SQLiteTransport, type SQLiteTransportOptions, type SQSClientLike, SQSTransport, type SQSTransportOptions, SamplingPlugin, type SamplingPluginOptions, type Sender, type ShutdownHandlerOptions, SlackAlertPlugin, type SlackAlertPluginOptions, type SlackSender, TamperEvidentPlugin, type TamperEvidentPluginOptions, TraceContextPlugin, type TraceContextPluginOptions, Transport, VERSION, bindContext, currentContext, defaultResolveActiveOtelTraceId, generateTraceId, getTraceparent, installShutdownHandlers, parseTraceHeader, setTraceparent, withAzureFunction, withCloudFunction, withFlush, withLambda };