logixia 2.0.0 → 2.0.4

package/dist/index.d.ts

@@ -1,16 +1,13 @@
-import { p as TransportLogEntry, s as IAsyncTransport } from "./transport.types-CGoHpWQR.js";
-import { A as HttpResponse, C as RequestContext, D as TraceIdExtractorConfig, E as TraceIdConfig, M as RequestTiming, O as HttpError, S as RedactConfig, T as TimingEntry, _ as LogLevel, a as DEFAULT_LOG_LEVELS, b as LoggerWithLevels, c as ExtractLevels, d as ILogFormatter, f as ILogger, g as LogFieldKey, h as LogEntry, i as DEFAULT_LOG_COLORS, j as RequestMetrics, k as HttpRequest, l as GracefulShutdownConfig, m as LogColor, n as ContextData, o as Environment, p as ILoggerDefault, r as CustomLevelMethods, s as ErrorSerializationOptions, t as AdaptiveSamplingConfig, u as IBaseLogger, v as LogLevelString, w as SamplingConfig, x as NamespaceLevels, y as LoggerConfig } from "./index-DhIoploR.js";
-import { a as globalPluginRegistry, i as PluginRegistry, n as createLogger$1, o as usePlugin, r as LogixiaPlugin, t as LogixiaLogger } from "./logitron-logger-UVeN-mQm.js";
-import { a as DiscordTransport, i as DiscordEmbed, n as SlackTransport, o as DiscordTransportConfig, r as SlackTransportConfig, t as SlackMessage } from "./slack.transport-CXjQYOes.js";
-import { A as SearchStats, C as SearchFilters, D as SearchPreset, E as SearchOptions, F as SuggestionType, I as TimeRange, L as TimelineEvent, M as SemanticIndex, N as SimilarLog, O as SearchQuery, P as SortField, S as RelativeTime, T as SearchMatch, _ as ParsedNLQuery, a as ILogSearchEngine, b as RelatedLog, c as SearchManager, d as CorrelatedLogs, f as EntityType, g as LogPattern, h as LogCorrelationSummary, i as BasicSearchEngine, j as SearchSuggestion, k as SearchResult, l as SearchManagerConfig, m as LogCluster, n as NLPSearchEngine, o as BasicLogIndexer, p as ExportOptions, r as CorrelationEngine, s as ILogIndexer, t as PatternRecognitionEngine, u as AnomalyDetection, v as QueryEntity, w as SearchHighlight, x as RelationshipType, y as QueryIntent } from "./search-CNh9uVwR.js";
+import { A as HttpResponse, C as RequestContext, D as TraceIdExtractorConfig, E as TraceIdConfig, M as RequestTiming, O as HttpError, S as RedactConfig, T as TimingEntry, _ as LogLevel, a as DEFAULT_LOG_LEVELS, b as LoggerWithLevels, c as ExtractLevels, d as ILogFormatter, f as ILogger, g as LogFieldKey, h as LogEntry, i as DEFAULT_LOG_COLORS, j as RequestMetrics, k as HttpRequest, l as GracefulShutdownConfig, m as LogColor, n as ContextData, o as Environment, p as ILoggerDefault, r as CustomLevelMethods, s as ErrorSerializationOptions, t as AdaptiveSamplingConfig, u as IBaseLogger, v as LogLevelString, w as SamplingConfig, x as NamespaceLevels, y as LoggerConfig } from "./index-DwozbmB4.js";
+import { a as globalPluginRegistry, i as PluginRegistry, n as createLogger$1, o as usePlugin, r as LogixiaPlugin, t as LogixiaLogger } from "./logitron-logger-D2B75Oc7.js";
+import { a as DiscordTransport, c as OtlpLogTransportConfig, i as DiscordEmbed, l as toOtelSeverity, n as SlackTransport, o as DiscordTransportConfig, r as SlackTransportConfig, s as OtlpLogTransport, t as SlackMessage } from "./slack.transport-DrirgDNy.js";
+import { A as SearchStats, C as SearchFilters, D as SearchPreset, E as SearchOptions, F as SuggestionType, I as TimeRange, L as TimelineEvent, M as SemanticIndex, N as SimilarLog, O as SearchQuery, P as SortField, S as RelativeTime, T as SearchMatch, _ as ParsedNLQuery, a as ILogSearchEngine, b as RelatedLog, c as SearchManager, d as CorrelatedLogs, f as EntityType, g as LogPattern, h as LogCorrelationSummary, i as BasicSearchEngine, j as SearchSuggestion, k as SearchResult, l as SearchManagerConfig, m as LogCluster, n as NLPSearchEngine, o as BasicLogIndexer, p as ExportOptions, r as CorrelationEngine, s as ILogIndexer, t as PatternRecognitionEngine, u as AnomalyDetection, v as QueryEntity, w as SearchHighlight, x as RelationshipType, y as QueryIntent } from "./search-CazwyX5Z.js";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { IncomingMessage, ServerResponse } from "node:http";
-
-//#region src/core/default-config.d.ts
 /**
  * Default configuration for Logixia logger
  */
-declare const DEFAULT_CONFIG: {
+export declare const DEFAULT_CONFIG: {
   appName: string;
   environment: Environment;
   traceId: boolean;
@@ -43,9 +40,7 @@ declare const DEFAULT_CONFIG: {
   };
   outputs: string[];
 };
-//#endregion
-//#region src/formatters/json.formatter.d.ts
-declare class JsonFormatter implements ILogFormatter {
+export declare class JsonFormatter implements ILogFormatter {
   private includeTimestamp;
   private includeLevel;
   private includeAppName;
@@ -63,9 +58,7 @@ declare class JsonFormatter implements ILogFormatter {
   format(entry: LogEntry): string;
   private serializePayload;
 }
-//#endregion
-//#region src/formatters/text.formatter.d.ts
-declare class TextFormatter implements ILogFormatter {
+export declare class TextFormatter implements ILogFormatter {
   private colorize;
   private includeTimestamp;
   private includeAppName;
@@ -92,8 +85,6 @@ declare class TextFormatter implements ILogFormatter {
   static createDetailed(): TextFormatter;
   static createMinimal(): TextFormatter;
 }
-//#endregion
-//#region src/utils/error.utils.d.ts
 /**
  * Serialize an Error into a plain JSON-safe object, including:
  *  - `name`, `message`, `stack`
@@ -102,17 +93,15 @@ declare class TextFormatter implements ILogFormatter {
  *  - standard Node.js error fields (`code`, `statusCode`, `errno`, …)
  *  - any other enumerable own properties
  */
-declare function serializeError(error: Error, options?: ErrorSerializationOptions): Record<string, unknown>;
+export declare function serializeError(error: Error, options?: ErrorSerializationOptions): Record<string, unknown>;
 /**
  * Type guard: returns true if the value looks like an Error object.
  */
-declare function isError(value: unknown): value is Error;
+export declare function isError(value: unknown): value is Error;
 /**
  * Coerce any thrown value into a proper Error instance.
  */
-declare function normalizeError(error: unknown): Error;
-//#endregion
-//#region src/utils/otel.d.ts
+export declare function normalizeError(error: unknown): Error;
 /**
  * logixia — OpenTelemetry auto trace-log correlation
  *
@@ -189,7 +178,7 @@ interface OtelBridgeOptions {
  * - No active span exists (root context)
  * - The span context is invalid (all-zeros)
  */
-declare function getActiveOtelContext(opts?: OtelBridgeOptions): OtelSpanContext | undefined;
+export declare function getActiveOtelContext(opts?: OtelBridgeOptions): OtelSpanContext | undefined;
 /**
  * Returns a metadata object with OTel context fields ready to merge into a log call,
  * using the configured field names.
@@ -204,7 +193,7 @@ declare function getActiveOtelContext(opts?: OtelBridgeOptions): OtelSpanContext
  * });
  * ```
  */
-declare function getOtelMetaFields(opts?: OtelBridgeOptions): Record<string, unknown>;
+export declare function getOtelMetaFields(opts?: OtelBridgeOptions): Record<string, unknown>;
 /**
  * Initialise the global OTel bridge.
  *
@@ -218,26 +207,22 @@ declare function getOtelMetaFields(opts?: OtelBridgeOptions): Record<string, unk
  * initOtelBridge();
  * ```
  */
-declare function initOtelBridge(opts?: OtelBridgeOptions): void;
+export declare function initOtelBridge(opts?: OtelBridgeOptions): void;
 /**
  * Disable the OTel bridge (useful for tests).
  */
-declare function disableOtelBridge(): void;
-//#endregion
-//#region src/utils/redact.utils.d.ts
+export declare function disableOtelBridge(): void;
 /**
  * Redact an object according to the given RedactConfig and return a new
  * top-level object. Subtrees with nothing to redact are shared with the input,
  * never mutated. Circular references become `[Circular]`.
  */
-declare function redactObject(obj: Record<string, unknown>, config: RedactConfig, _currentPath?: string): Record<string, unknown>;
+export declare function redactObject(obj: Record<string, unknown>, config: RedactConfig, _currentPath?: string): Record<string, unknown>;
 /**
  * Apply redaction to a log payload (top-level call convenience wrapper).
  * Returns a new object — never mutates the input.
  */
-declare function applyRedaction(payload: Record<string, unknown> | undefined, config: RedactConfig | undefined): Record<string, unknown> | undefined;
-//#endregion
-//#region src/utils/runtime-control.d.ts
+export declare function applyRedaction(payload: Record<string, unknown> | undefined, config: RedactConfig | undefined): Record<string, unknown> | undefined;
 /** Minimal logger surface the runtime controls need. */
 interface ReconfigurableLogger {
   getLevel(): LogLevelString;
@@ -259,7 +244,7 @@ interface LevelSignalOptions {
  * memorizable command (`kill -USR2 <pid>`) is enough to ratchet verbosity up
  * while chasing a bug and back down again — no value to remember.
  */
-declare function registerLevelSignal(logger: ReconfigurableLogger, options?: LevelSignalOptions): () => void;
+export declare function registerLevelSignal(logger: ReconfigurableLogger, options?: LevelSignalOptions): () => void;
 interface MinimalReq {
   method?: string | undefined;
   headers?: Record<string, string | string[] | undefined> | undefined;
@@ -290,11 +275,9 @@ interface MinimalRes {
  * which also keeps cross-site form posts out) and a body of at most 16 KB
  * (otherwise 413).
  */
-declare function createLevelControlHandler(logger: ReconfigurableLogger, options?: {
+export declare function createLevelControlHandler(logger: ReconfigurableLogger, options?: {
   allowedLevels?: string[];
 }): (req: MinimalReq, res: MinimalRes) => void;
-//#endregion
-//#region src/utils/safe-stringify.d.ts
 /**
  * logixia — robust JSON serialization for log payloads.
  *
@@ -334,27 +317,25 @@ interface SafeStringifyOptions {
  * Serialize any value to JSON without throwing on circular references or BigInt.
  * Circular refs become `"[Circular]"` (or `{ $ref }` pointers when `decycle`).
  */
-declare function safeStringify(value: unknown, options?: SafeStringifyOptions): string;
+export declare function safeStringify(value: unknown, options?: SafeStringifyOptions): string;
 /**
  * Replace repeated object references with round-trippable `{ "$ref": "$..." }`
  * JSONPath pointers (the classic Crockford decycle). Pair with {@link retrocycle}
  * to reconstruct the original shared/circular graph.
  */
-declare function decycleValue(value: unknown, bigint?: 'string' | 'number'): unknown;
+export declare function decycleValue(value: unknown, bigint?: 'string' | 'number'): unknown;
 /**
  * Inverse of {@link decycleValue}: resolve `{ "$ref": "$..." }` pointers back
  * into the live object graph (mutates and returns the parsed input).
  */
-declare function retrocycle<T>(root: T): T;
+export declare function retrocycle<T>(root: T): T;
 /**
  * `JSON.stringify` for log output. Takes the plain fast path first and only
  * falls back to {@link safeStringify} when that throws (a cycle, a BigInt, a
  * throwing `toJSON`), so a bad payload costs nothing until it shows up.
  * Never throws: if even the safe walk fails, the value is replaced by a marker.
  */
-declare function stringifyForLog(value: unknown): string;
-//#endregion
-//#region src/utils/shutdown.utils.d.ts
+export declare function stringifyForLog(value: unknown): string;
 /**
  * Graceful shutdown utilities for Logixia
  *
@@ -362,8 +343,8 @@ declare function stringifyForLog(value: unknown): string;
  * exits on SIGTERM / SIGINT — solving the "last N seconds of logs are lost on
  * deployment" problem reported in Pino issue #2002 and LogDNA issue #15.
  */
-type ExitMode = 'auto' | 'always' | 'never';
-interface FlushOnExitOptions {
+export type ExitMode = 'auto' | 'always' | 'never';
+export interface FlushOnExitOptions {
   /** How long (ms) to wait for transports to flush before force-exiting. Default: 5000 */
   timeout?: number;
   /** OS signals that trigger a graceful flush. Default: ['SIGTERM', 'SIGINT'] */
@@ -392,12 +373,12 @@ type Closeable = {
  * Called automatically when `gracefulShutdown: true` is set in logger config.
  */
 /** Test helper: number of loggers currently registered for graceful shutdown. */
-declare function _shutdownRegistrySize(): number;
-declare function registerForShutdown(logger: Closeable): void;
+export declare function _shutdownRegistrySize(): number;
+export declare function registerForShutdown(logger: Closeable): void;
 /**
  * Deregister a logger (e.g. after `logger.close()` is called manually).
  */
-declare function deregisterFromShutdown(logger: Closeable): void;
+export declare function deregisterFromShutdown(logger: Closeable): void;
 /**
  * Register SIGTERM / SIGINT handlers that flush all registered loggers before
  * the process exits. Idempotent — the first call wins and later calls with
@@ -412,16 +393,14 @@ declare function deregisterFromShutdown(logger: Closeable): void;
  * flushOnExit({ timeout: 5000 });
  * ```
  */
-declare function flushOnExit(options?: FlushOnExitOptions): void;
+export declare function flushOnExit(options?: FlushOnExitOptions): void;
 /**
  * Remove all graceful shutdown handlers and clear the registry.
  * Primarily useful in tests.
  */
-declare function resetShutdownHandlers(): void;
-//#endregion
-//#region src/utils/trace.utils.d.ts
+export declare function resetShutdownHandlers(): void;
 /** Default key used to store the trace ID in AsyncLocalStorage. */
-declare const TRACE_CONTEXT_KEY: "traceId";
+export declare const TRACE_CONTEXT_KEY: "traceId";
 /**
  * Singleton that owns the AsyncLocalStorage and the active contextKey.
  *
@@ -437,7 +416,7 @@ declare const TRACE_CONTEXT_KEY: "traceId";
  *   TraceContext.instance.contextKey          // → 'traceId' (or custom)
  *   TraceContext.instance.getCurrentTraceId() // same as standalone fn
  */
-declare class TraceContext {
+export declare class TraceContext {
   private static _instance;
   readonly storage: AsyncLocalStorage<Record<string, unknown>>;
   private _contextKey;
@@ -479,16 +458,16 @@ declare class TraceContext {
  * The shared AsyncLocalStorage instance.
  * @deprecated Prefer `TraceContext.instance.storage` for new code.
  */
-declare const traceStorage: AsyncLocalStorage<Record<string, unknown>>;
+export declare const traceStorage: AsyncLocalStorage<Record<string, unknown>>;
 /** Returns the key currently used to store the trace ID in AsyncLocalStorage. */
-declare function getTraceContextKey(): string;
+export declare function getTraceContextKey(): string;
 /** @internal Called by TraceMiddleware / traceMiddleware() when they boot. */
-declare function _setActiveContextKey(key: string): void;
+export declare function _setActiveContextKey(key: string): void;
 /**
  * Get the current trace ID from async context.
  * Returns `undefined` when called outside a traced request.
  */
-declare function getCurrentTraceId(): string | undefined;
+export declare function getCurrentTraceId(): string | undefined;
 /**
  * Set trace ID in the CURRENT async context without starting a new one.
  *
@@ -542,11 +521,11 @@ declare function getCurrentTraceId(): string | undefined;
  * @deprecated Use `runWithTraceId(traceId, fn)` — do not call `setTraceId`
  *             from request-handling code.
  */
-declare function setTraceId(traceId: string, data?: Record<string, unknown>): void;
+export declare function setTraceId(traceId: string, data?: Record<string, unknown>): void;
 /** Run `fn` inside a new async context carrying `traceId`. */
-declare function runWithTraceId<T>(traceId: string, fn: () => T, data?: Record<string, unknown>): T;
+export declare function runWithTraceId<T>(traceId: string, fn: () => T, data?: Record<string, unknown>): T;
 /** Maximum accepted length for an incoming trace / correlation / request ID. */
-declare const MAX_INCOMING_ID_LENGTH = 128;
+export declare const MAX_INCOMING_ID_LENGTH = 128;
 /**
  * Validate an externally supplied identifier (trace ID, correlation ID, origin
  * service name, message-queue ID). Accepts only 1-128 characters from
@@ -554,20 +533,18 @@ declare const MAX_INCOMING_ID_LENGTH = 128;
  * first element. Returns the cleaned value, or `undefined` when it is unusable
  * so callers can generate a fresh ID instead of passing client text through.
  */
-declare function sanitizeIncomingId(value: unknown): string | undefined;
+export declare function sanitizeIncomingId(value: unknown): string | undefined;
 /** Extract trace ID from request using configuration (header → query → body → params). */
-declare function extractTraceId(request: unknown, config: TraceIdExtractorConfig): string | undefined;
+export declare function extractTraceId(request: unknown, config: TraceIdExtractorConfig): string | undefined;
 /**
  * Default headers checked for incoming trace ID propagation, in priority order:
  *   traceparent (W3C/OTel) → x-trace-id → x-request-id → x-correlation-id → trace-id
  */
-declare const DEFAULT_TRACE_HEADERS: string[];
+export declare const DEFAULT_TRACE_HEADERS: string[];
 /**
  * Create trace ID middleware for Express/NestJS
  */
-declare function createTraceMiddleware(config: TraceIdConfig): (req: unknown, res: unknown, next: () => void) => void;
-//#endregion
-//#region src/utils/typed-logger.d.ts
+export declare function createTraceMiddleware(config: TraceIdConfig): (req: unknown, res: unknown, next: () => void) => void;
 /**
  * logixia — TypeScript typed log fields
  *
@@ -616,7 +593,7 @@ interface LogFieldDef {
   /** Custom validator — return a string to emit it as a warning message. */
   validate?: (value: unknown) => string | undefined;
 }
-type LogSchema<TFields extends Record<string, unknown>> = { [K in keyof TFields]: LogFieldDef };
+type LogSchema<TFields extends Record<string, unknown>> = { [K in keyof TFields]: LogFieldDef; };
 interface CompiledSchema<TFields extends Record<string, unknown>> {
   readonly fields: LogSchema<TFields>;
   /**
@@ -632,7 +609,7 @@ interface CompiledSchema<TFields extends Record<string, unknown>> {
  * Call this once at module initialisation and pass it to `createTypedLogger`.
  * In development, every log call is validated against the schema.
  */
-declare function defineLogSchema<TFields extends Record<string, unknown>>(fields: LogSchema<TFields>): CompiledSchema<TFields>;
+export declare function defineLogSchema<TFields extends Record<string, unknown>>(fields: LogSchema<TFields>): CompiledSchema<TFields>;
 /** IBaseLogger-compatible subset used by TypedLogger */
 interface LoggerLike {
   error(message: string | Error, data?: Record<string, unknown>): Promise<void>;
@@ -665,9 +642,7 @@ interface TypedLogger<TFields extends Record<string, unknown>> {
  * @param logger  Any object that implements `IBaseLogger` (e.g. the result of `createLogger()`)
  * @param schema  Optional schema for dev-time validation. Created with `defineLogSchema()`.
  */
-declare function createTypedLogger<TFields extends Record<string, unknown>>(logger: LoggerLike, schema?: CompiledSchema<TFields>): TypedLogger<TFields>;
-//#endregion
-//#region src/wide-events.d.ts
+export declare function createTypedLogger<TFields extends Record<string, unknown>>(logger: LoggerLike, schema?: CompiledSchema<TFields>): TypedLogger<TFields>;
 /**
  * logixia — Canonical Log Lines / Wide Events.
  *
@@ -725,18 +700,18 @@ interface WideEventOptions {
  * throw) when called outside a `withWideEvent` / middleware scope, so business
  * code can call it unconditionally.
  */
-declare function addEventFields(fields: WideEventFields): void;
+export declare function addEventFields(fields: WideEventFields): void;
 /** Set a single field on the current wide event. */
-declare function setEventField(key: string, value: unknown): void;
+export declare function setEventField(key: string, value: unknown): void;
 /** Read a shallow copy of the wide event accumulated so far, or undefined. */
-declare function getEventFields(): WideEventFields | undefined;
+export declare function getEventFields(): WideEventFields | undefined;
 /**
  * Run `callback` inside a wide-event scope. `addEventFields` calls anywhere in
  * the (async) call tree accumulate onto one event, which is emitted exactly once
  * when the callback settles — on success OR error (the canonical "emit in
  * finally" guarantee). On error, `error` + `errorMessage` fields are added.
  */
-declare function withWideEvent<T>(logger: WideEventLogger, initialFields: WideEventFields, callback: () => Promise<T> | T, options?: WideEventOptions): Promise<T>;
+export declare function withWideEvent<T>(logger: WideEventLogger, initialFields: WideEventFields, callback: () => Promise<T> | T, options?: WideEventOptions): Promise<T>;
 interface MwReq {
   method?: string | undefined;
   url?: string | undefined;
@@ -764,63 +739,17 @@ interface WideEventMiddlewareOptions extends WideEventOptions {
  * more via `addEventFields`. The completion event includes `statusCode` and the
  * request duration.
  */
-declare function wideEventMiddleware(logger: WideEventLogger, options?: WideEventMiddlewareOptions): (req: MwReq, res: MwRes, next: () => void) => void;
-//#endregion
-//#region src/transports/otlp.transport.d.ts
-interface OtlpLogTransportConfig {
-  /** OTLP/HTTP logs endpoint, e.g. `http://localhost:4318/v1/logs`. */
-  url: string;
-  /** Extra HTTP headers (auth, tenant, etc.). */
-  headers?: Record<string, string>;
-  /** `service.name` resource attribute. Default: 'logixia'. */
-  serviceName?: string;
-  /** `service.version` resource attribute. */
-  serviceVersion?: string;
-  /** `deployment.environment` resource attribute. */
-  environment?: string;
-  /** Extra resource attributes merged into the OTLP resource. */
-  resourceAttributes?: Record<string, string | number | boolean>;
-  /** Entries per batch / per POST. Default: 100. */
-  batchSize?: number;
-  /** Auto-flush interval (ms). Default: 5000. */
-  flushIntervalMs?: number;
-  /** Abort a request that has not finished after this many ms. Default: 10000. */
-  requestTimeoutMs?: number;
-  /** Max buffered entries; the oldest are dropped past this. Default: 10000. */
-  maxBufferSize?: number;
-  level?: string;
-}
+export declare function wideEventMiddleware(logger: WideEventLogger, options?: WideEventMiddlewareOptions): (req: MwReq, res: MwRes, next: () => void) => void;
 /**
- * Map a logixia level name to an OTel SeverityNumber (1–24) and text.
- * Per the OTel logs SDK spec: TRACE=1, DEBUG=5, INFO=9, WARN=13, ERROR=17,
- * FATAL=21. Custom/unknown levels fall back to INFO (9).
+ * Per-request trace ID resolution shared by the HTTP logger middleware and the
+ * context helpers. Internal: not re-exported from the package entry points.
  */
-declare function toOtelSeverity(level: string): {
-  number: number;
-  text: string;
-};
-declare class OtlpLogTransport implements IAsyncTransport {
-  readonly name = "otlp";
-  readonly level: string | undefined;
-  private readonly url;
-  private readonly headers;
-  private readonly batchSize;
-  private readonly flushIntervalMs;
-  private readonly requestTimeoutMs;
-  private readonly resourceAttrs;
-  private readonly buffer;
-  private flushTimer;
-  constructor(config: OtlpLogTransportConfig);
-  write(entry: TransportLogEntry): void;
-  /** Convert one entry into an OTLP LogRecord. */
-  private toLogRecord;
-  private buildPayload;
-  flush(): Promise<void>;
-  private send;
-  close(): Promise<void>;
+type TraceHeaderOption = string | readonly string[];
+/** Minimal structural request shape; Express and Fastify requests satisfy it. */
+interface ContextRequestLike {
+  headers?: Record<string, string | string[] | undefined>;
+  id?: unknown;
 }
-//#endregion
-//#region src/context/async-context.d.ts
 interface LogContext {
   traceId?: string;
   spanId?: string;
@@ -829,7 +758,7 @@ interface LogContext {
   sessionId?: string;
   [key: string]: unknown;
 }
-declare const LogixiaContext: {
+export declare const LogixiaContext: {
   /**
    * Run `callback` inside an async context that carries `store` fields.
    * All loggers queried within `callback` (and its async descendants) will
@@ -859,33 +788,53 @@ declare const LogixiaContext: {
    */
   getStorage(): AsyncLocalStorage<LogContext>;
 };
+interface ContextHelperOptions<Req extends ContextRequestLike> {
+  /**
+   * Extract additional fields from the request. A `traceId` returned here is ignored:
+   * the resolved request trace ID always wins.
+   */
+  enrich?: (request: Req & Record<string, unknown>) => Partial<LogContext>;
+  /**
+   * Header name, or list of names tried in order, to read the trace ID from.
+   * Default: `DEFAULT_TRACE_HEADERS` (traceparent is parsed to its 32-hex trace id).
+   */
+  traceIdHeader?: TraceHeaderOption;
+  /**
+   * Echo the resolved trace ID on the response under this header name.
+   * Default: `false` (no response header is set).
+   */
+  responseHeader?: string | false;
+}
 /**
  * Create an Express/Connect-compatible middleware that wraps each request in
  * a `LogixiaContext.run()` scope populated with common request fields.
  *
+ * Trace ID: the first present header of `traceIdHeader` (default
+ * `DEFAULT_TRACE_HEADERS`, `traceparent` parsed), else `request.id`, else a
+ * generated UUID. It is available via `getCurrentTraceId()` and is the logger's
+ * top-level `traceId` inside the request. No response header is set unless
+ * `responseHeader` is given.
+ *
  * @example
  * ```ts
  * import { createExpressContextMiddleware } from 'logixia';
- * app.use(createExpressContextMiddleware());
+ * app.use(createExpressContextMiddleware({ responseHeader: 'x-trace-id' }));
  * ```
  */
-declare function createExpressContextMiddleware(options?: {
-  /** Extract additional fields from the request. */
-  enrich?: (req: Record<string, unknown>) => Partial<LogContext>;
-  /** Header to read the traceId from. Default: 'x-trace-id'. */
-  traceIdHeader?: string;
-}): (req: Record<string, unknown>, _res: unknown, next: () => void) => void;
+export declare function createExpressContextMiddleware<Req extends ContextRequestLike = ContextRequestLike>(options?: ContextHelperOptions<Req>): (req: Req, res: {
+  setHeader?: (name: string, value: string) => unknown;
+}, next: () => void) => void;
 /**
  * Create a Fastify lifecycle hook that wraps each request in a context scope.
  *
  * Register with `fastify.addHook('onRequest', createFastifyContextHook())`.
+ * Resolves the trace ID exactly like {@link createExpressContextMiddleware} and
+ * shares it with `createFastifyPlugin()` from `logixia/middleware`. Fastify's
+ * default counter `request.id` (`req-1`, ...) is never used as a trace ID.
  */
-declare function createFastifyContextHook(options?: {
-  enrich?: (request: Record<string, unknown>) => Partial<LogContext>;
-  traceIdHeader?: string;
-}): (request: Record<string, unknown>, _reply: unknown, done: () => void) => void;
-//#endregion
-//#region src/utils/sampling.utils.d.ts
+export declare function createFastifyContextHook<Req extends ContextRequestLike = ContextRequestLike>(options?: ContextHelperOptions<Req>): (request: Req, reply: {
+  header?: (name: string, value: string) => unknown;
+}, done: () => void) => void;
 interface SamplingStats {
   /** Total calls evaluated since last reset. */
   evaluated: number;
@@ -901,8 +850,6 @@ interface SamplingStats {
   /** Window start (ms since epoch). */
   windowStart: number;
 }
-//#endregion
-//#region src/exceptions/types.d.ts
 /**
  * Unified error response shape for logixia.
  *
@@ -1010,8 +957,6 @@ interface ErrorDetail {
    */
   code: string;
 }
-//#endregion
-//#region src/exceptions/builder.d.ts
 /** Input parameters for `ErrorResponseBuilder.build`. */
 interface BuildParams {
   /** The caught exception — any type. */
@@ -1057,10 +1002,10 @@ interface BuildParams {
  *
  * @example `'550e8400-e29b-41d4-a716-446655440000'`
  */
-declare function generateTraceId(): string;
+export declare function generateTraceId(): string;
 /** @deprecated Use `generateTraceId` instead. */
-declare const generateRequestId: typeof generateTraceId;
-declare class ErrorResponseBuilder {
+export declare const generateRequestId: typeof generateTraceId;
+export declare class ErrorResponseBuilder {
   /**
    * Build a `LogixiaErrorResponse` from any thrown value.
    *
@@ -1097,8 +1042,6 @@ declare class ErrorResponseBuilder {
     httpStatus: number;
   };
 }
-//#endregion
-//#region src/exceptions/exception.d.ts
 /**
  * Constructor options for `LogixiaException`.
  *
@@ -1158,7 +1101,7 @@ interface LogixiaExceptionOptions<TCode extends string = string, TType extends s
    */
   metadata?: Record<string, unknown>;
 }
-declare class LogixiaException<TCode extends string = string, TType extends string = string> extends Error {
+export declare class LogixiaException<TCode extends string = string, TType extends string = string> extends Error {
   /** @readonly The machine-readable error code supplied by the caller. */
   readonly errorCode: TCode;
   /** @readonly The error type category supplied by the caller. */
@@ -1190,9 +1133,7 @@ declare class LogixiaException<TCode extends string = string, TType extends stri
  * }
  * ```
  */
-declare function isLogixiaException<TCode extends string = string, TType extends string = string>(value?: unknown): value is LogixiaException<TCode, TType>;
-//#endregion
-//#region src/metrics.d.ts
+export declare function isLogixiaException<TCode extends string = string, TType extends string = string>(value?: unknown): value is LogixiaException<TCode, TType>;
 /**
  * Increment a counter on each matching log entry.
  *
@@ -1265,7 +1206,7 @@ interface GaugeConfig {
 type MetricConfig = CounterConfig | HistogramConfig | GaugeConfig;
 type MetricsMap = Record<string, MetricConfig>;
 /** Label value used for the series that absorbs label sets beyond the cardinality cap. */
-declare const OVERFLOW_LABEL_VALUE = "__overflow__";
+export declare const OVERFLOW_LABEL_VALUE = "__overflow__";
 interface MetricsPluginOptions {
   /**
    * Maximum number of distinct label sets tracked per metric. Once reached, new
@@ -1291,7 +1232,7 @@ interface MetricsPluginOptions {
  * logger.use(metrics);
  * ```
  */
-declare class MetricsPlugin implements LogixiaPlugin {
+export declare class MetricsPlugin implements LogixiaPlugin {
   readonly name = "logixia-metrics";
   private readonly map;
   private readonly metricState;
@@ -1382,19 +1323,17 @@ declare class MetricsPlugin implements LogixiaPlugin {
  *
  * Pass `{ maxLabelSets }` to change the per-metric label cardinality cap (default 1000).
  */
-declare function createMetricsPlugin(map: MetricsMap, options?: MetricsPluginOptions): MetricsPlugin;
-//#endregion
-//#region src/index.d.ts
+export declare function createMetricsPlugin(map: MetricsMap, options?: MetricsPluginOptions): MetricsPlugin;
 /**
  * Create a new Logixia logger instance with TypeScript support for custom levels
  * @param config - Logger configuration
  * @returns Typed logger instance
  */
-declare const createLogger: typeof createLogger$1;
+export declare const createLogger: typeof createLogger$1;
 /**
  * Default logger instance
  */
-declare const logger: LogixiaLogger<{
+export declare const logger: LogixiaLogger<{
   appName: string;
   environment: Environment;
   traceId: boolean;
@@ -1427,6 +1366,8 @@ declare const logger: LogixiaLogger<{
   };
   outputs: string[];
 }>;
-//#endregion
-export { AdaptiveSamplingConfig, AnomalyDetection, BasicLogIndexer, BasicSearchEngine, type BuildParams, type CompiledSchema, ContextData, CorrelatedLogs, CorrelationEngine, type CounterConfig, CustomLevelMethods, DEFAULT_CONFIG, DEFAULT_LOG_COLORS, DEFAULT_LOG_LEVELS, DEFAULT_TRACE_HEADERS, type DiscordEmbed, DiscordTransport, type DiscordTransportConfig, EntityType, Environment, type ErrorDetail, ErrorResponseBuilder, ErrorSerializationOptions, ExitMode, ExportOptions, ExtractLevels, FlushOnExitOptions, type GaugeConfig, GracefulShutdownConfig, type HistogramConfig, HttpError, HttpRequest, HttpResponse, IBaseLogger, ILogFormatter, ILogIndexer, ILogSearchEngine, ILogger, ILoggerDefault, JsonFormatter, type LevelSignalOptions, LogCluster, LogColor, type LogContext, LogCorrelationSummary, LogEntry, type LogFieldDef, LogFieldKey, type LogFieldType, LogLevel, LogLevelString, LogPattern, type LogSchema, LoggerConfig, LoggerConfig as LoggerConfigInterface, type LoggerLike, LoggerWithLevels, LogixiaContext, type LogixiaErrorResponse, LogixiaException, type LogixiaExceptionOptions, LogixiaLogger, type LogixiaPlugin, MAX_INCOMING_ID_LENGTH, type MetricConfig, type MetricsMap, MetricsPlugin, type MetricsPluginOptions, NLPSearchEngine, NamespaceLevels, OVERFLOW_LABEL_VALUE, type OtelBridgeOptions, type OtelSpanContext, OtlpLogTransport, type OtlpLogTransportConfig, ParsedNLQuery, PatternRecognitionEngine, PluginRegistry, QueryEntity, QueryIntent, type ReconfigurableLogger, type RedactConfig, RelatedLog, RelationshipType, RelativeTime, RequestContext, RequestMetrics, RequestTiming, type SafeStringifyOptions, SamplingConfig, type SamplingStats, SearchFilters, SearchHighlight, SearchManager, SearchManagerConfig, SearchMatch, SearchOptions, SearchPreset, SearchQuery, SearchResult, SearchStats, SearchSuggestion, SemanticIndex, SimilarLog, type SlackMessage, SlackTransport, type SlackTransportConfig, SortField, SuggestionType, TRACE_CONTEXT_KEY, TextFormatter, TimeRange, TimelineEvent, TimingEntry, TraceContext, TraceIdConfig, TraceIdExtractorConfig, type TypedLogger, type WideEventFields, type WideEventLogger, type WideEventMiddlewareOptions, type WideEventOptions, _setActiveContextKey, _shutdownRegistrySize, addEventFields, applyRedaction, createExpressContextMiddleware, createFastifyContextHook, createLevelControlHandler, createLogger, createMetricsPlugin, createTraceMiddleware, createTypedLogger, decycleValue, defineLogSchema, deregisterFromShutdown, disableOtelBridge, extractTraceId, flushOnExit, generateRequestId, generateTraceId, getActiveOtelContext, getCurrentTraceId, getEventFields, getOtelMetaFields, getTraceContextKey, globalPluginRegistry, initOtelBridge, isError, isLogixiaException, logger, normalizeError, redactObject, registerForShutdown, registerLevelSignal, resetShutdownHandlers, retrocycle, runWithTraceId, safeStringify, sanitizeIncomingId, serializeError, setEventField, setTraceId, stringifyForLog, toOtelSeverity, traceStorage, usePlugin, wideEventMiddleware, withWideEvent };
+/**
+ * Export default configuration for reference
+ */
+export { AdaptiveSamplingConfig, type AnomalyDetection, BasicLogIndexer, BasicSearchEngine, type BuildParams, type CompiledSchema, ContextData, type CorrelatedLogs, CorrelationEngine, type CounterConfig, CustomLevelMethods, DEFAULT_LOG_COLORS, DEFAULT_LOG_LEVELS, type DiscordEmbed, DiscordTransport, type DiscordTransportConfig, type EntityType, Environment, type ErrorDetail, ErrorSerializationOptions, type ExportOptions, ExtractLevels, type GaugeConfig, GracefulShutdownConfig, type HistogramConfig, HttpError, HttpRequest, HttpResponse, IBaseLogger, ILogFormatter, type ILogIndexer, type ILogSearchEngine, ILogger, ILoggerDefault, type LevelSignalOptions, type LogCluster, LogColor, type LogContext, type LogCorrelationSummary, LogEntry, type LogFieldDef, LogFieldKey, type LogFieldType, LogLevel, LogLevelString, type LogPattern, type LogSchema, LoggerConfig, type LoggerConfig as LoggerConfigInterface, type LoggerLike, LoggerWithLevels, type LogixiaErrorResponse, type LogixiaExceptionOptions, LogixiaLogger, type LogixiaPlugin, type MetricConfig, type MetricsMap, type MetricsPluginOptions, NLPSearchEngine, NamespaceLevels, type OtelBridgeOptions, type OtelSpanContext, OtlpLogTransport, type OtlpLogTransportConfig, type ParsedNLQuery, PatternRecognitionEngine, PluginRegistry, type QueryEntity, type QueryIntent, type ReconfigurableLogger, RedactConfig, type RelatedLog, type RelationshipType, type RelativeTime, RequestContext, RequestMetrics, RequestTiming, type SafeStringifyOptions, SamplingConfig, type SamplingStats, type SearchFilters, type SearchHighlight, SearchManager, type SearchManagerConfig, type SearchMatch, type SearchOptions, type SearchPreset, type SearchQuery, type SearchResult, type SearchStats, type SearchSuggestion, type SemanticIndex, type SimilarLog, type SlackMessage, SlackTransport, type SlackTransportConfig, type SortField, type SuggestionType, type TimeRange, type TimelineEvent, TimingEntry, TraceIdConfig, TraceIdExtractorConfig, type TypedLogger, type WideEventFields, type WideEventLogger, type WideEventMiddlewareOptions, type WideEventOptions, globalPluginRegistry, toOtelSeverity, usePlugin };
 //# sourceMappingURL=index.d.ts.map