/**
 * SMI-5615: Shared structured JSON-line logger.
 *
 * Generalized from the dead `packages/mcp-server/src/logger.ts` (SMI-883
 * redaction) into a surface-agnostic module usable by the MCP server, CLI,
 * and VS Code extension independently — `createLogger(surface)` is a
 * factory, not a singleton, so each host process can mint its own logger
 * (optionally stamped with its own package version) while still writing to
 * per-surface files that are safe to share across processes for the same
 * surface (see `rotation.ts`).
 *
 * Call-site invariants (see
 * docs/internal/implementation/production-error-logging.md §1 and the
 * Shared-State / Coordination Audit table, F2/F3):
 *
 *   - `getCorrelationId()` is read SYNCHRONOUSLY at the call site, inside
 *     `buildRecord`, never inside an async flush/rotation callback (F3) — a
 *     deferred read could observe a different call's (or no) correlation ID
 *     once the originating call's `AsyncLocalStorage` scope has unwound.
 *   - The full JSON-line record (including the synchronously-read
 *     correlation ID and synchronously-applied redaction) is built and
 *     `JSON.stringify`'d BEFORE handing the string off to `rotation.ts`'s
 *     serialized per-surface writer (F2) — only the actual disk write may
 *     complete asynchronously; by the time it starts, the record content is
 *     already frozen.
 *   - Logger calls never throw. Any failure while assembling or persisting a
 *     record falls back to `console.error`/`console.warn` (matching level,
 *     with `info`/`debug` also routed to `console.error`) rather than being
 *     fully silent — stderr remains the safety net of last resort. This
 *     differs from the old logger's "silently fail" comment intent, which is
 *     no longer acceptable once this is the only durable failure signal.
 *   - `warn`/`error` ALWAYS mirror to `console.warn`/`console.error`,
 *     synchronously, regardless of whether the disk write succeeds — this is
 *     NOT a failure-only fallback for those two levels (only `info`/`debug`
 *     use console purely as a write-failure fallback). This is what makes
 *     `logger.error`/`logger.warn` a safe drop-in replacement for existing
 *     `console.error`/`console.warn` call sites in the MCP server and CLI —
 *     the caller-visible terminal/stderr output stays identical to today,
 *     with redacted disk persistence added on top rather than instead of it.
 */
import type { LogDetails, Surface } from './types.js';
export interface CreateLoggerOptions {
    /**
     * Package/CLI version stamped on every record from this logger instance.
     * Defaults to `'unknown'` — pass each host package's own `version` (e.g.
     * from its own `package.json`) at its entrypoint for an accurate value.
     */
    version?: string;
}
export interface Logger {
    info(message: string, details?: LogDetails): void;
    warn(message: string, details?: LogDetails): void;
    error(message: string, details?: LogDetails): void;
    debug(message: string, details?: LogDetails): void;
}
/**
 * Creates a logger bound to `surface`. Independent instances for different
 * surfaces (or the same surface with different `version` stamps) are safe to
 * create concurrently — they only share state at the `rotation.ts` layer,
 * which is itself safe for concurrent writers to the same surface (F2).
 */
export declare function createLogger(surface: Surface, options?: CreateLoggerOptions): Logger;
/**
 * Memoized per-surface logger created with default options
 * (`version: 'unknown'`). Prefer calling `createLogger(surface, { version })`
 * once at each package's entrypoint so records carry that package's real
 * version; `getLogger` is a convenience for call sites that don't need a
 * custom version stamp and want a single shared instance per surface.
 */
export declare function getLogger(surface: Surface): Logger;
//# sourceMappingURL=logger.d.ts.map