@monochromatic-dev/module-logger 0.1.0 → 0.3.0

package/dist/final/neutral/index.d.mts

@@ -1,137 +1,89 @@
-import { stat as stat$1 } from "node:fs/promises";
-import { dirname as dirname$1, join as join$1 } from "node:path";
-//#region src/types.d.ts
-/**
- * Log severity levels ordered from least to most severe.
- */
-type Level = "debug" | "error" | "fatal" | "info" | "trace" | "warn";
-/**
- * Structured log record written to sinks.
- */
-type LogRecord = {
-  readonly level: Level;
-  readonly message: string;
-  readonly timestamp: number;
-};
-/**
- * Optional drain hook for sinks that buffer records internally.
- * Called via logger-level {@link Logger.flush} to force buffered work
- * through before a process exit, critical error boundary, or assertion.
- *
- * Always async: sinks whose drain is synchronous return an
- * already-resolved promise so callers `await` uniformly. A `void` arm is
- * not used; under the `no-optional-escape` rule `T | void` is a banned
- * fake-optional encoding, and there is no real synchronous value to carry.
- */
-type SinkFlush = () => Promise<void>;
-/**
- * Verification function that checks if a sink backend is available.
- * May run setup side effects (resolving a log path, opening a writable
- * stream) and reports whether the backend is usable. A sink whose
- * verification resolves `false` (or rejects) is dropped by the logger and
- * receives no further records.
- *
- * Always async, matching `write` and `flush`: a synchronous check returns an
- * already-resolved promise (`Promise.resolve(check)`) so the logger awaits
- * verification uniformly with no sync/async branch.
- */
-type Verify = () => Promise<boolean>;
-/**
- * Sink that receives log records. A sink is a self-describing adapter: it
- * carries everything the logger must know to use it, namely how to
- * `verify` its backend is available, how to `write` a record, and
- * optionally how to `flush` buffered work. Holding `verify` on the sink
- * (rather than as a sibling export the logger pairs by hand) lets the
- * logger treat a registry as a plain `Sink[]` and lets a test supply one
- * self-contained fake.
- *
- * Sinks that buffer records (e.g. microtask-batched console) may
- * expose a `flush` hook so callers can force emission on demand.
- *
- * `write` is always async: a synchronous sink does its work eagerly and
- * returns an already-resolved promise, so the logger observes a uniform
- * `Promise<void>`. A rejected write is handled per sink and does not
- * disable the backend; only a failed `verify` drops a sink. A `void` arm
- * is not used, for the reason stated on {@link SinkFlush}.
- */
-type Sink = {
-  readonly flush?: SinkFlush;
-  readonly verify: Verify;
-  readonly write: (record: LogRecord) => Promise<void>;
-};
-/**
- * Logger interface with 6 log levels plus `flush` for startup and sink drains.
- * `flush()` resolves once startup verification has completed, tracked sink
- * writes have settled, and every available sink's own {@link SinkFlush} hook
- * has settled. Safe to call even when no sink buffers.
- */
-type Logger = {
-  readonly debug: (message: string) => void;
-  readonly error: (message: string) => void;
-  readonly fatal: (message: string) => void;
-  readonly flush: () => Promise<void>;
-  readonly info: (message: string) => void;
-  readonly trace: (message: string) => void;
-  readonly warn: (message: string) => void;
-};
-//#endregion
+import { a as SinkFlush, i as Sink, n as LogRecord, o as Verify, r as Logger, t as Level } from "./types-BkkBXgY3.mjs";
 //#region src/create-logger.d.ts
 /**
- * Default `flush()` deadline in milliseconds. Measured on 2026-09-06: a
- * default logger flushing 100 records through the console and file sinks
- * settles in about 2 ms locally, so this leaves three orders of magnitude for
- * a slow but working backend while still bounding shutdown on a wedged one.
- * Override per logger through the `flushDeadlineMs` option of
- * {@link createLogger}.
- */
+Default `flush()` deadline in milliseconds. Measured on 2026-09-06: a
+default logger flushing 100 records through the console and file sinks
+settles in about 2 ms locally, so this leaves three orders of magnitude for
+a slow but working backend while still bounding shutdown on a wedged one.
+Override per logger through the `flushDeadlineMs` option of
+{@link createLogger}.
+*/
 export declare const DEFAULT_FLUSH_DEADLINE_MS = 5e3;
 /**
- * Builds a multi-sink logger over the supplied sink adapters. All
- * orchestration (per-sink availability, startup buffering and replay,
- * in-flight write tracking, and flush) lives here; the exported default
- * `logger` is just this factory applied to the default sink set, and tests
- * apply it to fake sinks to exercise the orchestration directly.
- *
- * Verification runs eagerly at construction and never blocks callers:
- * records emitted while an async sink is still verifying buffer internally
- * and replay to that sink the moment it verifies. A sink whose `verify`
- * resolves `false` or throws is dropped and receives no records. A rejected
- * `write` is the sink's own concern and does not disable the backend.
- *
- * `flush()` always resolves: one deadline (`flushDeadlineMs`, default
- * {@link DEFAULT_FLUSH_DEADLINE_MS}) wraps startup verification, the
- * in-flight write drain, and every sink flush hook together. When it elapses
- * the logger reports one breadcrumb, abandons the tracked writes from its
- * view (the sinks expose no cancellation, so the underlying work continues),
- * and resolves, so a wedged backend cannot hang a shutdown.
- *
- * @param sinks - Sink adapters to fan each record out to, in priority order.
- *
- * @param flushDeadlineMs - Milliseconds one `flush()` may take before it
- * resolves anyway; raise it for slow but working backends such as network
- * filesystems.
- *
- * @returns Logger plus its eager `initPromise`; callers need not await
- * `initPromise` before logging, since startup records replay on verify.
- *
- * @example
- * ```ts
- * const { logger } = createLogger({ sinks: [createConsoleSink()] });
- * logger.info('ready');
- * await logger.flush();
- * ```
- *
- * @example
- * ```ts
- * const { logger } = createLogger({
- *   sinks: [createFileSink()],
- *   flushDeadlineMs: 30_000,
- * });
- * ```
- */
-export declare function createLogger({ sinks, flushDeadlineMs }: {
+Default per-sink `verify()` time limit in milliseconds. Measured on
+2026-09-06: the default logger's five shipped verifies complete together in
+about 2.4 ms locally, so this leaves three orders of magnitude for a slow
+but working backend probe (a network filesystem, a busy IndexedDB) while a
+verify that never answers (a hung mount, an IndexedDB open blocked by
+another tab) can no longer stall startup. Override per logger through the
+`verifyTimeoutMs` option of {@link createLogger}.
+*/
+export declare const DEFAULT_VERIFY_TIMEOUT_MS = 5e3;
+/**
+Most records the logger buffers before its sinks have verified. Startup
+lasts at most {@link DEFAULT_VERIFY_TIMEOUT_MS}, so this bounds the memory a
+burst during that window can claim; on overflow the oldest buffered record
+is dropped so the newest (usually most diagnostic) context survives, and
+one synthetic `warn` record naming the dropped count is written to every
+available sink once initialization completes.
+*/
+export declare const STARTUP_BUFFER_CAP = 1e4;
+/**
+Builds a multi-sink logger over the supplied sink adapters. All
+orchestration (per-sink availability, startup buffering and replay,
+in-flight write tracking, and flush) lives here; the exported default
+`logger` is just this factory applied to the default sink set, and tests
+apply it to fake sinks to exercise the orchestration directly.
+
+Verification runs eagerly at construction and never blocks callers:
+records emitted while an async sink is still verifying buffer internally
+and replay to that sink the moment it verifies. Every sink verifies
+concurrently under its own time limit (`verifyTimeoutMs`, default
+{@link DEFAULT_VERIFY_TIMEOUT_MS}), so one backend that never answers
+cannot starve the others or keep the logger from initializing. A sink
+whose `verify` resolves `false`, throws, or runs past the limit is dropped
+and receives no records; an answer that arrives after the limit is
+ignored. A rejected `write` is the sink's own concern and does not disable
+the backend.
+
+`flush()` always resolves: one deadline (`flushDeadlineMs`, default
+{@link DEFAULT_FLUSH_DEADLINE_MS}) wraps startup verification, the
+in-flight write drain, and every sink flush hook together. When it elapses
+the logger reports one breadcrumb, abandons the tracked writes from its
+view (the sinks expose no cancellation, so the underlying work continues),
+and resolves, so a wedged backend cannot hang a shutdown.
+
+@param sinks - Sink adapters to fan each record out to, in priority order.
+
+@param flushDeadlineMs - Milliseconds one `flush()` may take before it
+resolves anyway; raise it for slow but working backends such as network
+filesystems.
+
+@param verifyTimeoutMs - Milliseconds one sink's `verify()` may take before
+the sink counts as unavailable; raise it for a slow but working probe.
+
+@returns Logger plus its eager `initPromise`; callers need not await
+`initPromise` before logging, since startup records replay on verify.
+
+@example
+```ts
+const { logger } = createLogger({ sinks: [createConsoleSink()] });
+logger.info('ready');
+await logger.flush();
+```
+
+@example
+```ts
+const { logger } = createLogger({
+sinks: [createFileSink()],
+flushDeadlineMs: 30_000,
+});
+```
+*/
+export declare function createLogger({ sinks, flushDeadlineMs, verifyTimeoutMs }: {
   readonly sinks: readonly Sink[];
   readonly flushDeadlineMs?: number;
+  readonly verifyTimeoutMs?: number;
 }): {
   readonly initPromise: Promise<void>;
   readonly logger: Logger;
@@ -139,310 +91,152 @@ export declare function createLogger({ sinks, flushDeadlineMs }: {
 //#endregion
 //#region src/logger.d.ts
 /**
- * Eager readiness promise. Consumers do not need to await this before logging;
- * {@link Logger.flush} awaits it internally, and startup records replay to
- * async sinks as they become available.
- */
+Eager readiness promise. Consumers do not need to await this before logging;
+{@link Logger.flush} awaits it internally, and startup records replay to
+async sinks as they become available.
+*/
 export declare const initPromise: Promise<void>;
 /**
- * Multi-sink logger that writes to all available backends.
- * Startup records replay to async sinks that verify after the log call.
- * Log calls throw only when initialization proves no backend is available,
- * which the console sink prevents in every supported runtime.
- *
- * @example
- * ```ts
- * import { logger, } from '\@monochromatic-dev/module-logger/logger';
- *
- * logger.error('unexpected shutdown',);
- * await logger.flush();
- * ```
- */
+Multi-sink logger that writes to all available backends.
+Startup records replay to async sinks that verify after the log call.
+Log calls throw only when initialization proves no backend is available,
+which the console sink prevents in every supported runtime.
+
+@example
+```ts
+import { logger, } from '\@monochromatic-dev/module-logger/logger';
+
+logger.error('unexpected shutdown',);
+await logger.flush();
+```
+*/
 export declare const logger: Logger;
 //#endregion
 //#region src/sink/console.d.ts
 /**
- * Builds a microtask-batched console sink. The pending buffer, schedule flag,
- * and memoized verbose detection live in this instance's closure (no
- * module-global state), so independent loggers and tests stay isolated with
- * no reset hook. Collapses contiguous same-level runs into single `console.*`
- * calls, sharply reducing console-panel overhead when an instrumented path
- * emits many records per sync frame.
- *
- * @returns Sink that writes formatted lines to `console.*`, except
- * process-hosted debug records write to stderr.
- *
- * @example
- * ```ts
- * const { logger } = createLogger({ sinks: [createConsoleSink()] });
- * logger.info('server started');
- * ```
- */
+Builds a microtask-batched console sink. The pending buffer, schedule flag,
+and memoized verbose detection live in this instance's closure (no
+module-global state), so independent loggers and tests stay isolated with
+no reset hook. Collapses contiguous same-level runs into single `console.*`
+calls, sharply reducing console-panel overhead when an instrumented path
+emits many records per sync frame.
+
+@returns Sink that writes formatted lines to `console.*`, except
+process-hosted debug records write to stderr.
+
+@example
+```ts
+const { logger } = createLogger({ sinks: [createConsoleSink()] });
+logger.info('server started');
+```
+*/
 declare function createConsoleSink(): Sink;
 //#endregion
-//#region src/error-format.d.ts
-/**
- * Reports a logger-internal caught value without going back through logger
- * sinks, formatting it via {@link caughtValueText}.
- *
- * @param context - Human-readable operation that caught the value.
- *
- * @param error - Caught value to include in the diagnostic.
- *
- * @mutates error - `caughtValueText` may invoke string-conversion hooks.
- *
- * @example
- * ```ts
- * reportLoggerInternalError({
- *   context: 'console sink verify failed',
- *   error: new Error('blocked'),
- * });
- * ```
- */
-declare function reportLoggerInternalError({ context, error }: {
-  readonly context: string;
-  readonly error: unknown;
-}): void;
-//#endregion
-//#region src/sink/file.d.ts
-/**
- * Sentinel returned by {@link findNodeModulesUp} when no ancestor directory
- * contains a `node_modules`. A unique symbol so it never collides with a real
- * path string the walk might otherwise return, keeping the result free of a
- * banned `string | undefined` union.
- *
- * @example
- * ```ts
- * const dir = await findNodeModulesUp({ cwd, stat, dirname, join });
- * if (dir === NO_NODE_MODULES_FOUND) {
- *   // no ancestor project root
- * }
- * ```
- */
-declare const NO_NODE_MODULES_FOUND: unique symbol;
-/**
- * Walks up from `cwd` to find the nearest ancestor directory containing a
- * `node_modules` subdirectory, returning that subdirectory's absolute path.
- *
- * Using find-up rather than cwd-relative placement keeps log directories
- * anchored to the project the caller actually belongs to. Without this,
- * scripts invoked from build output (e.g. `dist/`) or other stray cwds
- * would create `node_modules/.monochromatic/` inside those trees, polluting
- * shipped artifacts.
- *
- * Exported primarily so `index.unit.test.ts` can exercise both the hit
- * and miss paths directly with an injected `stat`.
- *
- * @param cwd - starting directory for the upward search
- *
- * @param stat - `node:fs/promises` stat (injected so the dynamic
- * import stays in one place)
- *
- * @param dirname - `node:path` dirname
- *
- * @param join - `node:path` join
- *
- * @param reportError - logger fault reporter injected for deterministic tests
- *
- * @returns absolute path to the nearest ancestor `node_modules`, or
- * {@link NO_NODE_MODULES_FOUND} when no ancestor contains one
- *
- * @example
- * ```ts
- * const dir = await findNodeModulesUp({ cwd: process.cwd(), stat, dirname, join });
- * ```
- */
-declare function findNodeModulesUp({ cwd, stat, dirname, join, reportError }: {
-  readonly cwd: string;
-  readonly stat: typeof stat$1;
-  readonly dirname: typeof dirname$1;
-  readonly join: typeof join$1;
-  readonly reportError?: typeof reportLoggerInternalError;
-}): Promise<string | typeof NO_NODE_MODULES_FOUND>;
-/**
- * Builds a file sink that appends JSONL records to the nearest ancestor
- * `node_modules/.monochromatic/{timestamp}.log.jsonl` (resolved once during
- * verification). The resolved path, the cached `appendFile`, and the
- * verification memo live in this instance's closure (no module-global state),
- * so independent loggers and tests never share a log file or need a reset
- * hook. No `flush` hook: each `write` awaits `appendFile` directly, so there
- * is no buffered state to drain.
- *
- * @returns Sink backed by `node:fs/promises`.
- *
- * @example
- * ```ts
- * const { logger } = createLogger({ sinks: [createFileSink()] });
- * logger.error('unhandled rejection');
- * await logger.flush();
- * ```
- */
-declare function createFileSink(): Sink;
-//#endregion
-//#region src/sink/indexed-db.d.ts
-/**
- * Builds an IndexedDB sink that buffers serialized records through the shared
- * {@link createRecordBuffer} policy and persists each newline-joined JSONL
- * batch as one string value per transaction, measured at 0.15 µs of
- * main-thread enqueue per record on headless Chromium 149 (one `add` per
- * 32 KiB batch). The connection lives in this instance's closure (no
- * module-global state), so independent loggers and tests never share a
- * handle or need a reset hook.
- *
- * Records are readable the moment their transaction settles (DevTools
- * Application tab included), survive tab close and browser restart, and
- * auto-incremented keys serialize across tabs, so no run-scoped naming is
- * needed. Retention trims oldest-first past {@link MAX_STORED_BATCHES}.
- * Transactions use the default relaxed durability: relaxed commits reach the
- * browser's storage backend promptly and survive renderer crashes, and the
- * OS-crash window `durability: 'strict'` would close is the rarest failure
- * class, not worth an fsync per batch.
- *
- * Flush triggers (32 KiB in-write cap, `warn`-or-worse severity, 250 ms
- * quiet-period deadline, page lifecycle, and the `flush` hook) are the
- * buffer's; see {@link createRecordBuffer}. The sink's `flush` hook awaits
- * every issued batch transaction before resolving.
- *
- * @returns Sink backed by IndexedDB.
- *
- * @example
- * ```ts
- * const { logger } = createLogger({ sinks: [createIndexedDbSink()] });
- * logger.warn('quota nearing limit');
- * ```
- */
-declare function createIndexedDbSink(): Sink;
-//#endregion
 //#region src/sink/local-storage.d.ts
 /**
- * Builds a localStorage sink that buffers serialized records through the
- * shared {@link createRecordBuffer} policy and persists each newline-joined
- * JSONL batch under a run-scoped counter-incremented key through
- * {@link createLocalStorageStore}. One uniform write path runs on every
- * runtime; no per-runtime mode exists. Flush triggers (32 KiB in-write cap,
- * `warn`-or-worse severity, 250 ms quiet-period deadline, page lifecycle,
- * and the `flush` hook) are the buffer's; see {@link createRecordBuffer}.
- *
- * Unlike the sessionStorage sink, whose store dies with the tab, this sink's
- * batches survive tab close and browser restart, bounded by oldest-first
- * eviction at half the localStorage quota; that makes it the web storage sink
- * whose records remain inspectable after a full crash-and-restart.
- *
- * @returns Sink backed by web `localStorage`.
- *
- * @example
- * ```ts
- * const { logger } = createLogger({ sinks: [createLocalStorageSink()] });
- * logger.info('user signed in'); // buffered
- * logger.warn('quota near');     // flushes both records in one batch
- * ```
- */
+Builds a localStorage sink that buffers serialized records through the
+shared {@link createRecordBuffer} policy and persists each newline-joined
+JSONL batch under a run-scoped counter-incremented key through
+{@link createLocalStorageStore}. One uniform write path runs on every
+runtime; no per-runtime mode exists. Flush triggers (32 KiB in-write cap,
+`warn`-or-worse severity, 250 ms quiet-period deadline, page lifecycle,
+and the `flush` hook) are the buffer's; see {@link createRecordBuffer}.
+
+Unlike the sessionStorage sink, whose store dies with the tab, this sink's
+batches survive tab close and browser restart, bounded by oldest-first
+eviction at half the localStorage quota; that makes it the web storage sink
+whose records remain inspectable after a full crash-and-restart.
+
+@returns Sink backed by web `localStorage`.
+
+@example
+```ts
+const { logger } = createLogger({ sinks: [createLocalStorageSink()] });
+logger.info('user signed in'); // buffered
+logger.warn('quota near');     // flushes both records in one batch
+```
+*/
 declare function createLocalStorageSink(): Sink;
 //#endregion
 //#region src/sink/noop.d.ts
 /**
- * Builds a noop sink that discards every record and always verifies as
- * available. Stateless, so the returned adapters share the same functions;
- * the factory shape merely matches the other sinks. Useful as a stand-in
- * that disables logging without removing log calls.
- *
- * @returns Sink that discards all records and exposes no `flush` (nothing
- * is buffered).
- *
- * @example
- * ```ts
- * const { logger } = createLogger({ sinks: [createNoopSink()] });
- * logger.info('goes nowhere');
- * ```
- */
+Builds a noop sink that discards every record and always verifies as
+available. Stateless, so the returned adapters share the same functions;
+the factory shape merely matches the other sinks. Useful as a stand-in
+that disables logging without removing log calls.
+
+@returns Sink that discards all records and exposes no `flush` (nothing
+is buffered).
+
+@example
+```ts
+const { logger } = createLogger({ sinks: [createNoopSink()] });
+logger.info('goes nowhere');
+```
+*/
 declare function createNoopSink(): Sink;
 //#endregion
-//#region src/sink/opfs.d.ts
-/**
- * Builds an OPFS sink that buffers serialized records through the shared
- * {@link createRecordBuffer} policy and appends each newline-joined JSONL
- * batch to a per-session file in the Origin Private File System with one
- * stream write per batch. The kept-open writable stream lives in this
- * instance's closure (no module-global state), so independent loggers and
- * tests never share a handle or need a reset hook.
- *
- * Flush triggers (32 KiB in-write cap, `warn`-or-worse severity, 250 ms
- * quiet-period deadline, page lifecycle, and the `flush` hook) are the
- * buffer's; see {@link createRecordBuffer}. Batch writes queue on the stream
- * in issue order, so ordering holds at the batch boundary, and the sink's
- * `flush` hook awaits every issued batch before resolving.
- *
- * @returns Sink backed by OPFS.
- *
- * @example
- * ```ts
- * const { logger } = createLogger({ sinks: [createOpfsSink()] });
- * logger.warn('quota nearing limit');
- * ```
- */
-declare function createOpfsSink(): Sink;
-//#endregion
 //#region src/sink/session-storage.d.ts
 /**
- * Builds a sessionStorage sink that buffers serialized records through the
- * shared {@link createRecordBuffer} policy and persists each newline-joined
- * JSONL batch under a counter-incremented key through
- * {@link createSessionStorageStore}. One uniform write path runs on every
- * runtime; no per-runtime mode exists. Flush triggers (32 KiB in-write cap,
- * `warn`-or-worse severity, 250 ms quiet-period deadline, page lifecycle,
- * and the `flush` hook) are the buffer's; see {@link createRecordBuffer}.
- *
- * @returns Sink backed by web `sessionStorage`.
- *
- * @example
- * ```ts
- * const { logger } = createLogger({ sinks: [createSessionStorageSink()] });
- * logger.info('user signed in'); // buffered
- * logger.warn('quota near');     // flushes both records in one batch
- * ```
- */
+Builds a sessionStorage sink that buffers serialized records through the
+shared {@link createRecordBuffer} policy and persists each newline-joined
+JSONL batch under a counter-incremented key through
+{@link createSessionStorageStore}. One uniform write path runs on every
+runtime; no per-runtime mode exists. Flush triggers (32 KiB in-write cap,
+`warn`-or-worse severity, 250 ms quiet-period deadline, page lifecycle,
+and the `flush` hook) are the buffer's; see {@link createRecordBuffer}.
+
+@returns Sink backed by web `sessionStorage`.
+
+@example
+```ts
+const { logger } = createLogger({ sinks: [createSessionStorageSink()] });
+logger.info('user signed in'); // buffered
+logger.warn('quota near');     // flushes both records in one batch
+```
+*/
 declare function createSessionStorageSink(): Sink;
 declare namespace index_d_exports {
-  export { NO_NODE_MODULES_FOUND, createConsoleSink, createFileSink, createIndexedDbSink, createLocalStorageSink, createNoopSink, createOpfsSink, createSessionStorageSink, findNodeModulesUp };
+  export { createConsoleSink, createLocalStorageSink, createNoopSink, createSessionStorageSink };
 }
 //#endregion
 //#region src/tagged.d.ts
 /**
- * Wraps a logger so every message is prefixed with `[tag] `.
- * Callers typically pass `myFn.name` as tag to keep prefixes
- * in sync with refactors.
- *
- * @param tag - Prefix string inserted before each message
- *
- * @param l - Base logger to wrap; defaults to the module-level {@link logger}
- *   singleton
- *
- * @returns Logger whose methods prepend `[tag] ` to every message
- *
- * @example
- * ```ts
- * import { tagged } from '\@monochromatic-dev/module-logger/tagged';
- *
- * function handleRequest({ l }: { l: Logger }): void {
- *   l.info('received');
- * }
- *
- * handleRequest({ l: tagged({ tag: handleRequest.name }) });
- * // logs: [handleRequest] received
- * ```
- *
- * @example
- * ```ts
- * // Composing tags: the outermost wrap (`l2` here) prepends to the message
- * // last, so its tag ends up rightmost. The innermost wrap (`l1`) hits the
- * // underlying logger first, so its tag is leftmost. The chain reads
- * // root-first: outer wrap = inner tag position.
- * const l1 = tagged({ tag: 'http' });
- * const l2 = tagged({ tag: 'retry', l: l1 });
- * l2.info('attempt 3');
- * // logs: [http] [retry] attempt 3
- * ```
- */
+Wraps a logger so every message is prefixed with `[tag] `.
+Callers typically pass `myFn.name` as tag to keep prefixes
+in sync with refactors.
+
+@param tag - Prefix string inserted before each message
+
+@param l - Base logger to wrap; defaults to the module-level {@link logger}
+singleton
+
+@returns Logger whose methods prepend `[tag] ` to every message
+
+@example
+```ts
+import { tagged } from '\@monochromatic-dev/module-logger/tagged';
+
+function handleRequest({ l }: { l: Logger }): void {
+l.info('received');
+}
+
+handleRequest({ l: tagged({ tag: handleRequest.name }) });
+// logs: [handleRequest] received
+```
+
+@example
+```ts
+// Composing tags: the outermost wrap (`l2` here) prepends to the message
+// last, so its tag ends up rightmost. The innermost wrap (`l1`) hits the
+// underlying logger first, so its tag is leftmost. The chain reads
+// root-first: outer wrap = inner tag position.
+const l1 = tagged({ tag: 'http' });
+const l2 = tagged({ tag: 'retry', l: l1 });
+l2.info('attempt 3');
+// logs: [http] [retry] attempt 3
+```
+*/
 export declare function tagged({ tag, l }: {
   readonly l?: Logger;
   readonly tag: string;
@@ -450,31 +244,31 @@ export declare function tagged({ tag, l }: {
 //#endregion
 //#region src/sink/console-control-chars.d.ts
 /**
- * Neutralizes terminal control characters in console-bound text. One linear
- * pass over the code points: each neutralized control becomes a `\uXXXX`
- * escape, everything else is copied through, and newline and tab pass
- * untouched. Well-formed and malformed escape sequences get no
- * special treatment because the introducer byte itself is neutralized, so a
- * trailing lone ESC, an unterminated OSC, and a nested ESC all lose their
- * teeth the same way.
- *
- * @param text - Message text destined for `console.*` or `process.stderr`.
- *
- * @returns Text with every neutralized control rendered as `\uXXXX`.
- *
- * @example
- * ```ts
- * neutralizeControlCharacters('title:\u001B]0;x\u0007 ok\n\tnext');
- * // => 'title:\\u001B]0;x\\u0007 ok\n\tnext'
- * ```
- */
+Neutralizes terminal control characters in console-bound text. One linear
+pass over the code points: each neutralized control becomes a `\uXXXX`
+escape, everything else is copied through, and newline and tab pass
+untouched. Well-formed and malformed escape sequences get no
+special treatment because the introducer byte itself is neutralized, so a
+trailing lone ESC, an unterminated OSC, and a nested ESC all lose their
+teeth the same way.
+
+@param text - Message text destined for `console.*` or `process.stderr`.
+
+@returns Text with every neutralized control rendered as `\uXXXX`.
+
+@example
+```ts
+neutralizeControlCharacters('title:\u001B]0;x\u0007 ok\n\tnext');
+// => 'title:\\u001B]0;x\\u0007 ok\n\tnext'
+```
+*/
 declare function neutralizeControlCharacters(text: string): string;
 //#endregion
 //#region src/sink/local-storage-key.d.ts
 /**
- * Parsed identity of one owned localStorage entry, used to order eviction
- * across runs.
- */
+Parsed identity of one owned localStorage entry, used to order eviction
+across runs.
+*/
 type ParsedLogKey = {
   readonly key: string;
   readonly stamp: number;
@@ -482,64 +276,64 @@ type ParsedLogKey = {
   readonly index: number;
 };
 /**
- * Builds the namespaced localStorage key for one batch slot of one run.
- *
- * @param stamp - Run creation time ordering runs oldest-first.
- *
- * @param nonce - Same-millisecond disambiguator between concurrent tabs.
- *
- * @param index - Zero-based batch slot within the run.
- *
- * @returns Key such as `monochromatic.log.1753000000000.a1b2.3`.
- *
- * @example
- * ```ts
- * buildLogKey({ stamp: 1753000000000, nonce: 'a1b2', index: 3 });
- * ```
- */
+Builds the namespaced localStorage key for one batch slot of one run.
+
+@param stamp - Run creation time ordering runs oldest-first.
+
+@param nonce - Same-millisecond disambiguator between concurrent tabs.
+
+@param index - Zero-based batch slot within the run.
+
+@returns Key such as `monochromatic.log.1753000000000.a1b2.3`.
+
+@example
+```ts
+buildLogKey({ stamp: 1753000000000, nonce: 'a1b2', index: 3 });
+```
+*/
 declare function buildLogKey({ stamp, nonce, index }: {
   readonly stamp: number;
   readonly nonce: string;
   readonly index: number;
 }): string;
 /**
- * Parses a localStorage key back into its run identity, or reports it foreign
- * by leaving `parsed` absent. Parsing is strict (exact prefix, exactly the
- * identity segment count, digit-shaped stamp and index, non-empty nonce)
- * because eviction trusts this to never classify a host application's key, or
- * the sessionStorage sink's flat `monochromatic.log.{n}` shape, as evictable.
- *
- * @param key - Candidate localStorage key.
- *
- * @returns Wrapper whose `parsed` property is present only for an owned key.
- *
- * @example
- * ```ts
- * parseLogKey('monochromatic.log.1753000000000.a1b2.3').parsed; // ParsedLogKey
- * parseLogKey('monochromatic.log.5').parsed; // undefined: sessionStorage shape
- * ```
- */
+Parses a localStorage key back into its run identity, or reports it foreign
+by leaving `parsed` absent. Parsing is strict (exact prefix, exactly the
+identity segment count, digit-shaped stamp and index, non-empty nonce)
+because eviction trusts this to never classify a host application's key, or
+the sessionStorage sink's flat `monochromatic.log.{n}` shape, as evictable.
+
+@param key - Candidate localStorage key.
+
+@returns Wrapper whose `parsed` property is present only for an owned key.
+
+@example
+```ts
+parseLogKey('monochromatic.log.1753000000000.a1b2.3').parsed; // ParsedLogKey
+parseLogKey('monochromatic.log.5').parsed; // undefined: sessionStorage shape
+```
+*/
 declare function parseLogKey(key: string): {
   readonly parsed?: ParsedLogKey;
 };
 /**
- * Orders parsed keys oldest-first for eviction: by run stamp, then by nonce
- * (an arbitrary but stable tiebreak between same-millisecond runs), then by
- * batch index within the run.
- *
- * @param first - Parsed key compared first.
- *
- * @param second - Parsed key compared second.
- *
- * @returns Negative when `first` is older, positive when newer, zero on ties.
- *
- * @example
- * ```ts
- * entries.toSorted(function byOldestFirst(first, second) {
- *   return compareLogKeys({ first, second });
- * });
- * ```
- */
+Orders parsed keys oldest-first for eviction: by run stamp, then by nonce
+(an arbitrary but stable tiebreak between same-millisecond runs), then by
+batch index within the run.
+
+@param first - Parsed key compared first.
+
+@param second - Parsed key compared second.
+
+@returns Negative when `first` is older, positive when newer, zero on ties.
+
+@example
+```ts
+entries.toSorted(function byOldestFirst(first, second) {
+return compareLogKeys({ first, second });
+});
+```
+*/
 declare function compareLogKeys({ first, second }: {
   readonly first: ParsedLogKey;
   readonly second: ParsedLogKey;
@@ -547,86 +341,86 @@ declare function compareLogKeys({ first, second }: {
 //#endregion
 //#region src/sink/local-storage-quota.d.ts
 /**
- * Detects the current runtime's default localStorage quota in UTF-16 code
- * units, or `Number.POSITIVE_INFINITY` when the runtime is unrecognized so the
- * caller leaves its footprint uncapped and relies on reactive eviction alone.
- *
- * @returns Total quota in code units, or `Number.POSITIVE_INFINITY` if unknown.
- *
- * @example
- * ```ts
- * const capChars = detectLocalStorageQuotaChars() / 2; // half the total
- * ```
- */
+Detects the current runtime's default localStorage quota in UTF-16 code
+units, or `Number.POSITIVE_INFINITY` when the runtime is unrecognized so the
+caller leaves its footprint uncapped and relies on reactive eviction alone.
+
+@returns Total quota in code units, or `Number.POSITIVE_INFINITY` if unknown.
+
+@example
+```ts
+const capChars = detectLocalStorageQuotaChars() / 2; // half the total
+```
+*/
 declare function detectLocalStorageQuotaChars(): number;
 //#endregion
 //#region src/sink/local-storage-store.d.ts
 /**
- * Builds the persistence engine behind the localStorage sink: each `persist`
- * lands one already-serialized batch under a run-scoped counter-incremented
- * key, with proactive and reactive quota eviction. Run identity and counters
- * live in this instance's closure (no module-global state), so independent
- * sinks and tests never share keys or need a reset hook.
- *
- * Unlike sessionStorage, localStorage is shared by every tab of the origin and
- * survives restarts, so this engine differs from the sessionStorage engine in
- * two ways. Keys carry a run identity (see `local-storage-key.ts`), so
- * concurrent tabs never collide on a counter. And on its first persist the
- * engine adopts every strictly-parsed entry left by other runs into its
- * footprint tally, evicting those oldest-first before its own entries;
- * without that, leftovers from dead sessions would fill the store until no
- * run could ever write again. Adoption is deferred to first persist rather
- * than construction so building the default sink set never touches
- * `globalThis.localStorage` on runtimes where the sink never verifies (plain
- * Node warns on mere access). Keys that fail the strict parse, including the
- * host application's, are never counted and never evicted.
- *
- * The engine caps its own footprint (adopted entries included) at half the
- * runtime's localStorage quota, proactively dropping oldest-first, and
- * reactively drops again if the real store still overflows; see
- * {@link createLocalStorageStore.persist}.
- *
- * @returns Engine exposing `persist` for one batch value per call.
- *
- * @example
- * ```ts
- * const store = createLocalStorageStore();
- * store.persist('{"level":"info","message":"hi","timestamp":0}');
- * ```
- */
+Builds the persistence engine behind the localStorage sink: each `persist`
+lands one already-serialized batch under a run-scoped counter-incremented
+key, with proactive and reactive quota eviction. Run identity and counters
+live in this instance's closure (no module-global state), so independent
+sinks and tests never share keys or need a reset hook.
+
+Unlike sessionStorage, localStorage is shared by every tab of the origin and
+survives restarts, so this engine differs from the sessionStorage engine in
+two ways. Keys carry a run identity (see `local-storage-key.ts`), so
+concurrent tabs never collide on a counter. And on its first persist the
+engine adopts every strictly-parsed entry left by other runs into its
+footprint tally, evicting those oldest-first before its own entries;
+without that, leftovers from dead sessions would fill the store until no
+run could ever write again. Adoption is deferred to first persist rather
+than construction so building the default sink set never touches
+`globalThis.localStorage` on runtimes where the sink never verifies (plain
+Node warns on mere access). Keys that fail the strict parse, including the
+host application's, are never counted and never evicted.
+
+The engine caps its own footprint (adopted entries included) at half the
+runtime's localStorage quota, proactively dropping oldest-first, and
+reactively drops again if the real store still overflows; see
+{@link createLocalStorageStore.persist}.
+
+@returns Engine exposing `persist` for one batch value per call.
+
+@example
+```ts
+const store = createLocalStorageStore();
+store.persist('{"level":"info","message":"hi","timestamp":0}');
+```
+*/
 declare function createLocalStorageStore(): {
   readonly persist: (batch: string) => void;
 };
 //#endregion
 //#region src/sink/record-buffer.d.ts
 /**
- * Builds the buffering stage shared by batch-persisting sinks: serialized
- * records accumulate and leave as one newline-joined JSONL batch through
- * `onFlush`. One uniform policy runs on every runtime; no per-runtime mode
- * exists.
- *
- * A batch flushes synchronously from inside `add` when it reaches
- * {@link FLUSH_BUFFER_CAP_CHARS} or when the record's severity is `warn` or
- * worse, by timer after {@link FLUSH_DEADLINE_MS} of quiet, on `pagehide`
- * and on the document becoming hidden (where those events exist), and on
- * `drain`. The byte-cap and severity flushes run on the caller's stack, so
- * neither a synchronous workload nor a wedged main thread can accumulate
- * more than one cap of unhanded records. When an addition would breach the
- * cap, the existing entries flush first so an oversized record's downstream
- * failure can only ever drop that record, never its batch-mates.
- *
- * @param onFlush - Backend handoff receiving each newline-joined batch;
- * called synchronously from whichever trigger fires, in record order.
- *
- * @returns Buffer exposing `add` for records and `drain` for forced flushes.
- *
- * @example
- * ```ts
- * const buffer = createRecordBuffer({ onFlush: (batch) => store.persist(batch) });
- * buffer.add({ level: 'info', serialized: JSON.stringify(record) });
- * buffer.drain();
- * ```
- */
+Builds the buffering stage shared by batch-persisting sinks: serialized
+records accumulate and leave as one newline-joined JSONL batch through
+`onFlush`. One uniform policy runs on every runtime; no per-runtime mode
+exists.
+
+A batch flushes synchronously from inside `add` when it reaches
+{@link FLUSH_BUFFER_CAP_CHARS} or when the record's severity is `warn` or
+worse, by timer after {@link FLUSH_DEADLINE_MS} of quiet, on `pagehide`
+and on the document becoming hidden (where those events exist), and on
+`drain`. The byte-cap and severity flushes run on the caller's stack, so
+neither a synchronous workload nor a wedged main thread can accumulate
+more than one cap of unhanded records. When an addition would breach the
+cap, the existing entries flush first so an oversized record's downstream
+failure can only ever drop that record, never its batch-mates.
+
+@param onFlush - Backend handoff receiving each newline-joined batch;
+called synchronously from whichever trigger fires, in record order.
+
+@returns Buffer exposing `add` for records and `drain` for forced flushes.
+
+@example
+```ts
+const buffer = createRecordBuffer({ onFlush: (batch) => store.persist(batch) });
+buffer.add({ level: 'info', serialized: JSON.stringify(record) });
+buffer.drain();
+```
+*/
 declare function createRecordBuffer({ onFlush }: {
   readonly onFlush: (batch: string) => void;
 }): {
@@ -639,35 +433,35 @@ declare function createRecordBuffer({ onFlush }: {
 //#endregion
 //#region src/sink/session-storage-quota.d.ts
 /**
- * Detects the current runtime's default sessionStorage quota in UTF-16 code
- * units, or `Number.POSITIVE_INFINITY` when the runtime is unrecognized so the
- * caller leaves its footprint uncapped and relies on reactive eviction alone.
- *
- * @returns Total quota in code units, or `Number.POSITIVE_INFINITY` if unknown.
- *
- * @example
- * ```ts
- * const capChars = detectSessionStorageQuotaChars() / 2; // half the total
- * ```
- */
+Detects the current runtime's default sessionStorage quota in UTF-16 code
+units, or `Number.POSITIVE_INFINITY` when the runtime is unrecognized so the
+caller leaves its footprint uncapped and relies on reactive eviction alone.
+
+@returns Total quota in code units, or `Number.POSITIVE_INFINITY` if unknown.
+
+@example
+```ts
+const capChars = detectSessionStorageQuotaChars() / 2; // half the total
+```
+*/
 declare function detectSessionStorageQuotaChars(): number;
 //#endregion
 //#region src/sink/web-storage-quota-error.d.ts
 /**
- * Reports whether a caught `setItem` value is a storage quota overflow, so
- * eviction reclaims space only for a full store and never for an unrelated
- * write fault such as a disabled-storage `SecurityError`.
- *
- * @param error - Caught value from a `setItem` failure.
- *
- * @returns Whether `error` names a quota overflow.
- *
- * @example
- * ```ts
- * try { sessionStorage.setItem(k, v); }
- * catch (error: unknown) { if (isQuotaExceededError(error)) evictOldest(); }
- * ```
- */
+Reports whether a caught `setItem` value is a storage quota overflow, so
+eviction reclaims space only for a full store and never for an unrelated
+write fault such as a disabled-storage `SecurityError`.
+
+@param error - Caught value from a `setItem` failure.
+
+@returns Whether `error` names a quota overflow.
+
+@example
+```ts
+try { sessionStorage.setItem(k, v); }
+catch (error: unknown) { if (isQuotaExceededError(error)) evictOldest(); }
+```
+*/
 declare function isQuotaExceededError(error: unknown): boolean;
 //#endregion
 export { type Level, type LogRecord, type Logger, type Sink, type SinkFlush, type Verify, buildLogKey as _buildLogKey, compareLogKeys as _compareLogKeys, createLocalStorageStore as _createLocalStorageStore, createRecordBuffer as _createRecordBuffer, detectLocalStorageQuotaChars as _detectLocalStorageQuotaChars, detectSessionStorageQuotaChars as _detectSessionStorageQuotaChars, isQuotaExceededError as _isQuotaExceededError, neutralizeControlCharacters as _neutralizeControlCharacters, parseLogKey as _parseLogKey, index_d_exports as sinks };