import { type Channel } from 'node:diagnostics_channel';
import type { EmitOptions, EventOf, LibOf, PayloadOf } from './types.js';
/** The prefix all channels created by this convention share. */
export declare const CHANNEL_PREFIX = "aviary";
/**
 * Current envelope schema version, stamped onto every emitted
 * {@link DiagnosticEvent} as `v`. Bump this only when the wire shape changes in a
 * way observers must adapt to. Observers should tolerate envelopes without `v`
 * (legacy emitters published before versioning) and treat them as version `1`.
 */
export declare const SCHEMA_VERSION = 1;
/**
 * The channel name for a `<lib>`/`<event>` pair: `aviary:<lib>:<event>`. This is
 * the cross-repo wire contract — keep it identical on producer and observer.
 */
export declare function channelName(lib: string, event: string): string;
/**
 * The memoized `node:diagnostics_channel` for a `<lib>`/`<event>` pair. Node
 * returns the same {@link Channel} object for the same name, so reading
 * `.hasSubscribers` is the cheap gate before building an envelope. Touching the
 * channel also records its name in the {@link registerChannel registry} so a
 * generic observer can discover it.
 *
 * Memoized via {@link channelCache}: only the first call for a `(lib, event)`
 * pair builds the name, resolves the channel, and registers it; subsequent calls
 * return the cached object after two map lookups.
 */
export declare function getChannel(lib: string, event: string): Channel;
/**
 * Emit a diagnostics event on `aviary:<lib>:<event>`.
 *
 * - The envelope's `ts` is `Date.now()` evaluated *inside* this call (never at
 *   module load).
 * - `traceId` is taken from `opts.traceId` if given, else auto-filled from the
 *   registered context accessor (if resolvable), else left undefined.
 * - The envelope is built and published ONLY when the channel `hasSubscribers`,
 *   so emitting is effectively free when nothing is listening.
 * - When `opts.sample` is given, it is consulted AFTER the `hasSubscribers` gate
 *   and BEFORE the envelope is built: a falsy result sheds this event without
 *   allocating anything. Default (no `sample`) always publishes when subscribed.
 * - The envelope carries the current {@link SCHEMA_VERSION} as `v`.
 * - Never throws: emitting observability must not break the caller.
 *
 * ```ts
 * emit('billing', 'invoice-paid', { invoiceId: 'inv_123', amount: 4200 });
 * // Shed 90% of a hot event:
 * emit('authz', 'decision', payload, { sample: () => Math.random() < 0.1 });
 * ```
 *
 * When `(lib, event)` is declared in the typed
 * {@link import('./types.js').ChannelRegistry ChannelRegistry}, `payload` is
 * checked against the declared type at compile time; every other pair keeps the
 * untyped `unknown` payload. The runtime behavior is identical either way.
 */
export declare function emit<TLib extends LibOf, TEvent extends EventOf<TLib>>(lib: TLib, event: TEvent, payload: PayloadOf<TLib, TEvent>, opts?: EmitOptions): void;
//# sourceMappingURL=channel.d.ts.map