/**
 * W3C Trace Context propagation helpers.
 *
 * Implements parsing, formatting, and injection/extraction of the
 * `traceparent` header as defined in the W3C Trace Context specification.
 *
 * @see https://www.w3.org/TR/trace-context/
 * @module propagation
 */
/**
 * Parsed W3C trace context fields from a `traceparent` header.
 *
 * @example
 * ```ts
 * import { formatTraceParent, type TraceContext } from '@lostgradient/weft/observability';
 *
 * const context: TraceContext = {
 *   version: '00',
 *   traceId: '4bf92f3577b34da6a3ce929d0e0e4736',
 *   spanId: '00f067aa0ba902b7',
 *   traceFlags: 1,
 * };
 * console.log(formatTraceParent(context));
 * ```
 */
export interface TraceContext {
    version: string;
    traceId: string;
    spanId: string;
    traceFlags: number;
}
/**
 * Parse a W3C traceparent header string.
 *
 * @example
 * ```ts
 * import { parseTraceParent } from '@lostgradient/weft';
 *
 * const ctx = parseTraceParent(
 *   '00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01',
 * );
 * console.log(ctx?.traceId);  // '4bf92f3577b34da6a3ce929d0e0e4736'
 * console.log(ctx?.traceFlags); // 1
 * ```
 */
export declare function parseTraceParent(value: string): TraceContext | null;
/**
 * Format a TraceContext to a W3C traceparent string.
 *
 * @example
 * ```ts
 * import { formatTraceParent, generateTraceId, generateSpanId } from '@lostgradient/weft';
 *
 * const header = formatTraceParent({
 *   version: '00',
 *   traceId: generateTraceId(),
 *   spanId: generateSpanId(),
 *   traceFlags: 1,
 * });
 * console.log(header); // '00-<32hex>-<16hex>-01'
 * ```
 */
export declare function formatTraceParent(context: TraceContext): string;
/**
 * Extract and parse a `traceparent` header from a headers map.
 *
 * @example
 * ```ts
 * import { extractTraceParent } from '@lostgradient/weft/observability';
 *
 * const headers = new Map([
 *   ['traceparent', '00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01'],
 * ]);
 * console.log(extractTraceParent(headers)?.traceId);
 * ```
 */
export declare function extractTraceParent(headers: Map<string, string>): TraceContext | null;
/**
 * Format and inject a `traceparent` header into a headers map.
 *
 * @example
 * ```ts
 * import { generateSpanId, generateTraceId, injectTraceParent } from '@lostgradient/weft/observability';
 *
 * const headers = new Map<string, string>();
 * injectTraceParent(headers, {
 *   version: '00',
 *   traceId: generateTraceId(),
 *   spanId: generateSpanId(),
 *   traceFlags: 1,
 * });
 * console.log(headers.has('traceparent'));
 * ```
 */
export declare function injectTraceParent(headers: Map<string, string>, context: TraceContext): void;
/**
 * Generate a random trace ID (32 hex chars / 16 bytes).
 *
 * @example
 * ```ts
 * import { generateTraceId } from '@lostgradient/weft';
 *
 * const traceId = generateTraceId();
 * console.log(traceId.length);  // 32
 * console.log(/^[0-9a-f]{32}$/.test(traceId)); // true
 * ```
 */
export declare function generateTraceId(): string;
/**
 * Generate a random span ID (16 hex chars / 8 bytes).
 *
 * @example
 * ```ts
 * import { generateSpanId } from '@lostgradient/weft';
 *
 * const spanId = generateSpanId();
 * console.log(spanId.length);  // 16
 * console.log(/^[0-9a-f]{16}$/.test(spanId)); // true
 * ```
 */
export declare function generateSpanId(): string;