import type { EventOf, LibOf, PayloadOf, TraceOptions } from './types.js';
/**
 * Span envelope schema version, stamped onto every {@link SpanEvent} as `v`.
 * Versioned independently of the POINT `SCHEMA_VERSION` so the two wire shapes
 * can evolve apart. Observers should treat an absent `v` as version `1`.
 */
export declare const SPAN_SCHEMA_VERSION = 1;
/**
 * The five span sub-channel names for a `(lib, event)` pair. They extend the
 * POINT `aviary:<lib>:<event>` name with a `:<phase>` suffix, mirroring Node's
 * own `tracingChannel` sub-channels (start/end/asyncStart/asyncEnd/error) while
 * staying inside the `aviary:` convention so the same generic observer can read
 * both POINT and SPAN traffic.
 */
export interface TraceChannelNames {
    start: string;
    end: string;
    asyncStart: string;
    asyncEnd: string;
    error: string;
}
/** Build the five span sub-channel names for a `(lib, event)` pair. */
export declare function traceChannelNames(lib: string, event: string): TraceChannelNames;
/**
 * Wrap an (async) operation and publish span-like start / end / asyncStart /
 * asyncEnd / error events over `node:diagnostics_channel`, so consumers get real
 * start/end/error pairing with timing for authz decisions, durable steps, etc.
 *
 * Naming follows the existing convention: events ride
 * `aviary:<lib>:<event>:<phase>` (see {@link traceChannelNames}). `emit` is
 * unchanged — `trace` is the additional span surface.
 *
 * Lifecycle:
 * - Sync `fn`: publishes `start` then, on return, `end` (with `result`); on
 *   throw, `error`. The value/throw is propagated to the caller unchanged.
 * - Async `fn` (returns a promise): publishes `start` synchronously, `asyncStart`
 *   when the promise settles begins resolving, then `asyncEnd` (with `result`)
 *   on fulfilment or `error` on rejection. The promise is returned to the caller.
 *
 * Cost: when NO span sub-channel has a subscriber, `trace` calls `fn` and returns
 * its value directly — no span id, no envelope, no timing — so the hot path is a
 * handful of `hasSubscribers` reads.
 *
 * Trace id: resolved once at span start from `opts.traceId` (wins) else the
 * registered context accessor, and stamped on every phase event.
 *
 * ```ts
 * const decision = trace('authz', 'decision', () => evaluate(req), { subject });
 * const out = await trace('durable', 'step', () => runStep(), { name });
 * ```
 */
export declare function trace<TLib extends LibOf, TEvent extends EventOf<TLib>, R>(lib: TLib, event: TEvent, fn: () => R, payload?: PayloadOf<TLib, TEvent>, opts?: TraceOptions): R;
/** A {@link trace} bound to one `(lib, event)` pair — see {@link tracingChannel}. */
export interface TracingChannel<TPayload = unknown> {
    /** The base `aviary:<lib>:<event>` channel name. */
    readonly name: string;
    /** The five span sub-channel names. */
    readonly channels: TraceChannelNames;
    /** Trace an operation on this channel; same semantics as {@link trace}. */
    trace<R>(fn: () => R, payload?: TPayload, opts?: TraceOptions): R;
}
/**
 * A {@link trace} factory bound to a single `(lib, event)` pair — the ergonomic,
 * reusable form for a hot call site that always traces the same operation. Named
 * after Node's `diagnostics_channel.tracingChannel()` (whose sub-channels we
 * mirror) but kept inside the `aviary:` convention.
 *
 * ```ts
 * const decision = tracingChannel('authz', 'decision');
 * decision.trace(() => evaluate(req), { subject });
 * ```
 */
export declare function tracingChannel<TLib extends LibOf, TEvent extends EventOf<TLib>>(lib: TLib, event: TEvent): TracingChannel<PayloadOf<TLib, TEvent>>;
//# sourceMappingURL=trace.d.ts.map