/**
 * Trace Metadata Tags - Add custom metadata to traces for filtering and querying.
 */
import type { AgentTrace } from './types';
export interface TraceMetadata {
    environment?: string;
    version?: string;
    user_segment?: string;
    feature_flags?: string[];
    [key: string]: any;
}
export interface MetadataFilter {
    /** Key must equal value */
    equals?: Record<string, any>;
    /** Key must contain value (for arrays) */
    contains?: Record<string, string>;
    /** Key must exist */
    exists?: string[];
    /** Key must not exist */
    notExists?: string[];
}
/**
 * Tag a trace with metadata, merging into existing metadata.
 */
export declare function tagTrace(trace: AgentTrace, metadata: TraceMetadata): AgentTrace;
/**
 * Filter traces by metadata criteria.
 */
export declare function filterByMetadata(traces: AgentTrace[], filter: MetadataFilter): AgentTrace[];
/**
 * Merge metadata from multiple sources (later sources override).
 */
export declare function mergeMetadata(...sources: TraceMetadata[]): TraceMetadata;
/**
 * Validate metadata against expected keys.
 */
export declare function validateMetadata(metadata: TraceMetadata, requiredKeys: string[]): {
    valid: boolean;
    missing: string[];
};
/**
 * Build an index of metadata values across multiple traces.
 */
export declare function extractMetadataIndex(traces: AgentTrace[]): Record<string, Set<any>>;
//# sourceMappingURL=trace-metadata.d.ts.map