/**
 * @module trace-context
 * W3C Trace Context implementation for distributed tracing
 *
 * Implements the W3C Trace Context specification for distributed tracing across
 * xBind agent operations, enabling correlation of requests across service boundaries.
 *
 * Standard: https://www.w3.org/TR/trace-context/
 *
 * Headers:
 * - `traceparent`: Required header with version, trace-id, parent-id, and trace-flags
 * - `tracestate`: Optional vendor-specific state
 *
 * Format: `{version}-{trace-id}-{parent-id}-{trace-flags}`
 * Example: `00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01`
 *
 * Usage:
 * ```typescript
 * import { TraceContext } from '@private.me/xbind';
 *
 * // Create a new trace context
 * const ctx = TraceContext.create();
 *
 * // Attach to request headers
 * const headers = new Headers();
 * ctx.inject(headers);
 *
 * // Extract from incoming headers
 * const incomingCtx = TraceContext.extract(headers);
 *
 * // Create child span
 * const childCtx = incomingCtx.createChild();
 * ```
 */
/**
 * W3C Trace Context specification constants
 */
export declare const TRACEPARENT_HEADER = "traceparent";
export declare const TRACESTATE_HEADER = "tracestate";
/**
 * Trace context version (currently only 00 is supported)
 */
export declare const TRACE_VERSION = "00";
/**
 * Trace flags
 */
export declare enum TraceFlags {
    /** Not sampled */
    NONE = 0,
    /** Sampled */
    SAMPLED = 1
}
/**
 * Trace state key-value pair
 */
export interface TraceStateEntry {
    key: string;
    value: string;
}
/**
 * Parsed traceparent header components
 */
export interface TraceparentSpec {
    version: string;
    traceId: string;
    parentId: string;
    traceFlags: number;
}
/**
 * W3C Trace Context implementation
 *
 * Represents a single point in a distributed trace with parent-child relationships.
 */
export declare class TraceContext {
    /** W3C version (always '00' for now) */
    readonly version: string;
    /** Trace ID (32 hex characters, 16 bytes) */
    readonly traceId: string;
    /** Parent span ID (16 hex characters, 8 bytes) */
    readonly parentId: string;
    /** Trace flags (8-bit field) */
    readonly traceFlags: number;
    /** Vendor-specific trace state */
    readonly traceState: TraceStateEntry[];
    /**
     * Create a trace context
     *
     * @param traceId - 32-character hex trace ID
     * @param parentId - 16-character hex parent span ID
     * @param traceFlags - 8-bit trace flags
     * @param traceState - Optional vendor-specific state
     */
    constructor(traceId: string, parentId: string, traceFlags?: number, traceState?: TraceStateEntry[]);
    /**
     * Create a new root trace context
     *
     * Generates a new trace ID and parent ID for a new trace.
     *
     * @param sampled - Whether this trace should be sampled
     * @returns New trace context
     *
     * @example
     * ```typescript
     * const ctx = TraceContext.create();
     * console.log(ctx.traceId); // => "4bf92f3577b34da6a3ce929d0e0e4736"
     * ```
     */
    static create(sampled?: boolean): TraceContext;
    /**
     * Extract trace context from headers
     *
     * Parses the traceparent and tracestate headers according to W3C spec.
     *
     * @param headers - Headers object or plain object
     * @returns Trace context if found, null otherwise
     *
     * @example
     * ```typescript
     * const headers = new Headers({
     *   traceparent: '00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01'
     * });
     * const ctx = TraceContext.extract(headers);
     * ```
     */
    static extract(headers: Headers | Record<string, string>): TraceContext | null;
    /**
     * Inject trace context into headers
     *
     * Adds traceparent and tracestate headers to the provided headers object.
     *
     * @param headers - Headers to modify
     * @returns Modified headers
     *
     * @example
     * ```typescript
     * const ctx = TraceContext.create();
     * const headers = new Headers();
     * ctx.inject(headers);
     * ```
     */
    inject<T extends Headers | Record<string, string>>(headers: T): T;
    /**
     * Create a child trace context
     *
     * Generates a new parent ID (span ID) while keeping the same trace ID.
     * This represents a new span in the same trace.
     *
     * @param sampled - Override sampling decision (defaults to parent's decision)
     * @returns New child trace context
     *
     * @example
     * ```typescript
     * const parent = TraceContext.create();
     * const child = parent.createChild();
     * console.log(parent.traceId === child.traceId); // => true
     * console.log(parent.parentId === child.parentId); // => false
     * ```
     */
    createChild(sampled?: boolean): TraceContext;
    /**
     * Format as traceparent header value
     *
     * @returns traceparent string
     */
    toTraceparent(): string;
    /**
     * Format as tracestate header value
     *
     * @returns tracestate string
     */
    toTracestate(): string;
    /**
     * Check if this trace is sampled
     *
     * @returns True if sampled
     */
    isSampled(): boolean;
    /**
     * Add or update tracestate entry
     *
     * @param key - Vendor key (format: vendor[@system])
     * @param value - State value
     * @returns New trace context with updated state
     *
     * @example
     * ```typescript
     * const ctx = TraceContext.create();
     * const updated = ctx.withTracestate('private.me', 'did:key:z6Mk...');
     * ```
     */
    withTracestate(key: string, value: string): TraceContext;
    /**
     * Get tracestate value by key
     *
     * @param key - Vendor key
     * @returns State value or undefined
     */
    getTracestate(key: string): string | undefined;
    /**
     * Convert to plain object
     *
     * @returns Plain object representation
     */
    toObject(): {
        version: string;
        traceId: string;
        parentId: string;
        traceFlags: number;
        traceState: TraceStateEntry[];
        sampled: boolean;
    };
}
/**
 * Generate a random trace ID (32 hex characters)
 *
 * @returns 32-character hex string
 */
export declare function generateTraceId(): string;
/**
 * Generate a random span ID (16 hex characters)
 *
 * @returns 16-character hex string
 */
export declare function generateSpanId(): string;
/**
 * Validate trace ID format
 *
 * @param traceId - Trace ID to validate
 * @returns True if valid
 */
export declare function validateTraceId(traceId: string): boolean;
/**
 * Validate span ID format
 *
 * @param spanId - Span ID to validate
 * @returns True if valid
 */
export declare function validateSpanId(spanId: string): boolean;
/**
 * Parse traceparent header value
 *
 * @param traceparent - Header value
 * @returns Parsed components or null if invalid
 */
export declare function parseTraceparent(traceparent: string): TraceparentSpec | null;
/**
 * Parse tracestate header value
 *
 * @param tracestate - Header value
 * @returns Array of key-value pairs
 */
export declare function parseTracestate(tracestate: string): TraceStateEntry[];
