/**
 * Diagnostics -- centralized runtime warning/error emission.
 *
 * Provides typed warning/error helpers with a swappable sink so runtime
 * boundaries can emit operator-visible diagnostics without hard-coding
 * console calls throughout the codebase.
 *
 * @module
 */
import { type Clock } from './clock.js';
/** Severity level for a {@link DiagnosticEvent}. */
export type DiagnosticLevel = 'warn' | 'error';
/**
 * Operator-facing payload shape for a single diagnostic emission: a stable
 * `source`/`code` pair for filtering, a human message, plus optional structured
 * detail and an underlying cause.
 */
export interface DiagnosticPayload {
    readonly source: string;
    readonly code: string;
    readonly message: string;
    readonly cause?: unknown;
    readonly detail?: unknown;
}
/** A {@link DiagnosticPayload} enriched with severity and an emission timestamp. */
export interface DiagnosticEvent extends DiagnosticPayload {
    readonly level: DiagnosticLevel;
    readonly timestamp: number;
}
/** Swappable transport that receives {@link DiagnosticEvent}s from {@link Diagnostics}. */
export interface DiagnosticsSink {
    emit(event: DiagnosticEvent): void;
}
declare function warn(payload: DiagnosticPayload): DiagnosticEvent;
declare function error(payload: DiagnosticPayload): DiagnosticEvent;
declare function warnOnce(payload: DiagnosticPayload): DiagnosticEvent | null;
declare function setSink(sink: DiagnosticsSink): DiagnosticsSink;
declare function resetSink(): void;
declare function setClock(clock: Clock): Clock;
declare function resetClock(): void;
declare function clearOnce(): void;
declare function reset(): void;
declare function createBufferSink(): {
    readonly sink: DiagnosticsSink;
    readonly events: DiagnosticEvent[];
};
/**
 * Diagnostics facade — runtime boundaries call {@link Diagnostics.warn} / {@link Diagnostics.error}
 * instead of `console.*` so hosts can redirect or capture every diagnostic via {@link Diagnostics.setSink}.
 */
export declare const Diagnostics: {
    /** Emit a `warn`-level {@link DiagnosticEvent} to the current sink. */
    readonly warn: typeof warn;
    /** Emit an `error`-level {@link DiagnosticEvent} to the current sink. */
    readonly error: typeof error;
    /** {@link Diagnostics.warn}, but deduplicated by `source:code:message`. */
    readonly warnOnce: typeof warnOnce;
    /** Replace the active sink (e.g. for tests or hosted environments). */
    readonly setSink: typeof setSink;
    /** Restore the default sink that writes through `console`. */
    readonly resetSink: typeof resetSink;
    /**
     * Replace the clock the emission `timestamp` (a wall-clock TIMESTAMP) is read
     * from; returns the previous clock. Pass a `fixedClock`/`manualClock` for
     * deterministic, replayable diagnostic timestamps.
     */
    readonly setClock: typeof setClock;
    /** Restore the default {@link wallClock} timestamp source. */
    readonly resetClock: typeof resetClock;
    /** Clear the deduplication set used by {@link Diagnostics.warnOnce}. */
    readonly clearOnce: typeof clearOnce;
    /** Convenience for `resetSink()` + `clearOnce()` — mostly for test teardown. */
    readonly reset: typeof reset;
    /** Build an in-memory sink that collects events into an array — useful for tests. */
    readonly createBufferSink: typeof createBufferSink;
};
export declare namespace Diagnostics {
    /** Alias for {@link DiagnosticPayload}. */
    type Payload = DiagnosticPayload;
    /** Alias for {@link DiagnosticEvent}. */
    type Event = DiagnosticEvent;
    /** Alias for {@link DiagnosticLevel}. */
    type Level = DiagnosticLevel;
    /** Alias for {@link DiagnosticsSink}. */
    type Sink = DiagnosticsSink;
}
export {};
//# sourceMappingURL=diagnostics.d.ts.map