autotel 3.5.0 → 3.7.0

package/dist/sampling.js

@@ -1,6 +1,442 @@
-export { AUTOTEL_SAMPLING_TAIL_EVALUATED, AUTOTEL_SAMPLING_TAIL_KEEP, AdaptiveSampler, AlwaysSampler, CompositeSampler, FeatureFlagSampler, NeverSampler, RandomSampler, UserIdSampler, createLinkFromHeaders, extractLinksFromBatch, resolveSamplingPreset, samplingPresets } from './chunk-DPSA4QLA.js';
-import './chunk-55ER2KD5.js';
-import './chunk-J5QENANM.js';
-import './chunk-HA2WBOGQ.js';
-//# sourceMappingURL=sampling.js.map
+import { TraceFlags } from "@opentelemetry/api";
+
+//#region src/sampling.ts
+/**
+* Tail sampling attribute keys (autotel-internal, not OTel semconv)
+*/
+const AUTOTEL_SAMPLING_TAIL_KEEP = "autotel.sampling.tail.keep";
+const AUTOTEL_SAMPLING_TAIL_EVALUATED = "autotel.sampling.tail.evaluated";
+/**
+* Simple random sampler
+*
+* @example
+* ```typescript
+* new RandomSampler(0.1) // Sample 10% of requests
+* ```
+*/
+var RandomSampler = class {
+	sampleRate;
+	constructor(sampleRate) {
+		this.sampleRate = sampleRate;
+		if (sampleRate < 0 || sampleRate > 1) throw new Error("Sample rate must be between 0 and 1");
+	}
+	shouldSample(_context) {
+		return Math.random() < this.sampleRate;
+	}
+};
+/**
+* Always sample (100% tracing)
+*/
+var AlwaysSampler = class {
+	shouldSample(_context) {
+		return true;
+	}
+};
+/**
+* Never sample (0% tracing)
+*/
+var NeverSampler = class {
+	shouldSample(_context) {
+		return false;
+	}
+};
+/**
+* Adaptive sampler that always traces errors and slow requests
+*
+* This is the recommended sampler for production use.
+* It ensures you never miss critical issues while keeping costs down.
+*
+* Strategy:
+* - Always trace errors (critical for debugging)
+* - Always trace slow requests (performance issues)
+* - Use baseline sample rate for successful fast requests
+*
+* **IMPORTANT - Tail Sampling Requirement:**
+* This sampler uses tail sampling (makes decisions AFTER execution).
+* You MUST use TailSamplingSpanProcessor for it to work correctly:
+*
+* - If using initInstrumentation(): TailSamplingSpanProcessor is auto-configured
+* - If using custom TracerProvider: You MUST manually register TailSamplingSpanProcessor
+*
+* Without TailSamplingSpanProcessor, ALL spans are exported (defeating the cost savings).
+*
+* @see TailSamplingSpanProcessor
+* @see README.md "Tail Sampling with Custom Providers" section
+*
+* @example
+* ```typescript
+* new AdaptiveSampler({
+*   baselineSampleRate: 0.1,    // 10% of normal requests
+*   slowThresholdMs: 1000,       // Requests > 1s are "slow"
+*   alwaysSampleErrors: true,    // Always trace errors
+*   alwaysSampleSlow: true       // Always trace slow requests
+* })
+* ```
+*/
+var AdaptiveSampler = class {
+	baselineSampleRate;
+	slowThresholdMs;
+	alwaysSampleErrors;
+	alwaysSampleSlow;
+	linksBased;
+	linksRate;
+	logger;
+	samplingDecisions = /* @__PURE__ */ new WeakMap();
+	operationResults = /* @__PURE__ */ new WeakMap();
+	constructor(options = {}) {
+		this.baselineSampleRate = options.baselineSampleRate ?? .1;
+		this.slowThresholdMs = options.slowThresholdMs ?? 1e3;
+		this.alwaysSampleErrors = options.alwaysSampleErrors ?? true;
+		this.alwaysSampleSlow = options.alwaysSampleSlow ?? true;
+		this.linksBased = options.linksBased ?? false;
+		this.linksRate = options.linksRate ?? 1;
+		this.logger = options.logger;
+		if (this.baselineSampleRate < 0 || this.baselineSampleRate > 1) throw new Error("Baseline sample rate must be between 0 and 1");
+		if (this.linksRate < 0 || this.linksRate > 1) throw new Error("Links rate must be between 0 and 1");
+	}
+	needsTailSampling() {
+		return true;
+	}
+	shouldSample(context) {
+		const baselineDecision = Math.random() < this.baselineSampleRate;
+		this.samplingDecisions.set(context.args, baselineDecision);
+		return true;
+	}
+	/**
+	* Check if any links point to sampled spans.
+	*
+	* A span is considered linked to a sampled span if any of its links
+	* have trace_flags with the sampled bit set (0x01).
+	*
+	* @param links - Array of span links to check
+	* @returns true if any linked span is sampled, false otherwise
+	*/
+	hasSampledLink(links) {
+		if (!links || links.length === 0) return false;
+		return links.some((link) => link.context && (link.context.traceFlags & TraceFlags.SAMPLED) !== 0);
+	}
+	/**
+	* Re-evaluate sampling decision after operation completes
+	*
+	* This allows us to always capture errors and slow requests,
+	* even if they weren't initially sampled.
+	*
+	* @param context - Sampling context
+	* @param result - Operation result
+	* @returns true if this operation should be kept (not discarded)
+	*/
+	shouldKeepTrace(context, result) {
+		const baselineDecision = this.samplingDecisions.get(context.args) ?? false;
+		if (this.alwaysSampleErrors && !result.success) {
+			if (!baselineDecision) this.logger?.debug({
+				operation: context.operationName,
+				error: result.error?.message
+			}, "Adaptive sampling: Keeping error trace");
+			return true;
+		}
+		if (this.alwaysSampleSlow && result.duration >= this.slowThresholdMs) {
+			if (!baselineDecision) this.logger?.debug({
+				operation: context.operationName,
+				duration: result.duration
+			}, "Adaptive sampling: Keeping slow trace");
+			return true;
+		}
+		if (this.linksBased && context.links && this.hasSampledLink(context.links)) {
+			const keepLinked = Math.random() < this.linksRate;
+			if (keepLinked && !baselineDecision) this.logger?.debug({
+				operation: context.operationName,
+				linkCount: context.links.length
+			}, "Adaptive sampling: Keeping trace due to sampled link");
+			return keepLinked;
+		}
+		return baselineDecision;
+	}
+};
+/**
+* User-based sampler for consistent tracing
+*
+* Always samples requests from specific user IDs.
+* Useful for debugging specific user issues or monitoring VIP users.
+*
+* @example
+* ```typescript
+* new UserIdSampler({
+*   baselineSampleRate: 0.01,      // 1% of normal users
+*   alwaysSampleUsers: ['vip_123'], // Always trace VIP users
+*   extractUserId: (args) => args[0]?.userId // Extract user ID from first arg
+* })
+* ```
+*/
+var UserIdSampler = class {
+	baselineSampleRate;
+	alwaysSampleUsers;
+	extractUserId;
+	logger;
+	constructor(options) {
+		this.baselineSampleRate = options.baselineSampleRate ?? .1;
+		this.alwaysSampleUsers = new Set(options.alwaysSampleUsers || []);
+		this.extractUserId = options.extractUserId;
+		this.logger = options.logger;
+	}
+	shouldSample(context) {
+		const userId = this.extractUserId(context.args);
+		if (userId && this.alwaysSampleUsers.has(userId)) {
+			this.logger?.debug({
+				operation: context.operationName,
+				userId
+			}, "Sampling user request");
+			return true;
+		}
+		if (userId) return this.hashString(userId) < this.baselineSampleRate;
+		return Math.random() < this.baselineSampleRate;
+	}
+	/**
+	* Add user IDs to always-sample list
+	*/
+	addAlwaysSampleUsers(...userIds) {
+		for (const userId of userIds) this.alwaysSampleUsers.add(userId);
+	}
+	/**
+	* Remove user IDs from always-sample list
+	*/
+	removeAlwaysSampleUsers(...userIds) {
+		for (const userId of userIds) this.alwaysSampleUsers.delete(userId);
+	}
+	/**
+	* Simple hash function for consistent user sampling
+	*/
+	hashString(str) {
+		let hash = 0;
+		for (let i = 0; i < str.length; i++) {
+			const char = str.codePointAt(i) ?? 0;
+			hash = (hash << 5) - hash + char;
+			hash = hash & hash;
+		}
+		return Math.abs(hash) / 2147483647;
+	}
+};
+/**
+* Composite sampler that combines multiple samplers
+*
+* Samples if ANY of the child samplers returns true.
+*
+* @example
+* ```typescript
+* new CompositeSampler([
+*   new UserIdSampler({ extractUserId: (args) => args[0]?.userId }),
+*   new AdaptiveSampler({ baselineSampleRate: 0.1 })
+* ])
+* ```
+*/
+var CompositeSampler = class {
+	samplers;
+	constructor(samplers) {
+		this.samplers = samplers;
+		if (samplers.length === 0) throw new Error("CompositeSampler requires at least one child sampler");
+	}
+	shouldSample(context) {
+		return this.samplers.some((sampler) => sampler.shouldSample(context));
+	}
+};
+/**
+* Feature flag sampler
+*
+* Always samples requests with specific feature flags enabled.
+* Perfect for correlating A/B test experiments with metrics.
+*
+* @example
+* ```typescript
+* new FeatureFlagSampler({
+*   baselineSampleRate: 0.01,
+*   alwaysSampleFlags: ['new_checkout', 'experimental_ui'],
+*   extractFlags: (args, metadata) => metadata?.featureFlags
+* })
+* ```
+*/
+var FeatureFlagSampler = class {
+	baselineSampleRate;
+	alwaysSampleFlags;
+	extractFlags;
+	logger;
+	constructor(options) {
+		this.baselineSampleRate = options.baselineSampleRate ?? .1;
+		this.alwaysSampleFlags = new Set(options.alwaysSampleFlags || []);
+		this.extractFlags = options.extractFlags;
+		this.logger = options.logger;
+	}
+	shouldSample(context) {
+		const flags = this.extractFlags(context.args, context.metadata);
+		if (flags && flags.some((flag) => this.alwaysSampleFlags.has(flag))) {
+			this.logger?.debug({
+				operation: context.operationName,
+				flags
+			}, "Sampling feature flag request");
+			return true;
+		}
+		return Math.random() < this.baselineSampleRate;
+	}
+	/**
+	* Add feature flags to always-sample list
+	*/
+	addAlwaysSampleFlags(...flags) {
+		for (const flag of flags) this.alwaysSampleFlags.add(flag);
+	}
+	/**
+	* Remove feature flags from always-sample list
+	*/
+	removeAlwaysSampleFlags(...flags) {
+		for (const flag of flags) this.alwaysSampleFlags.delete(flag);
+	}
+};
+/**
+* Sampling preset factories.
+*
+* For most users, the string shorthand on `init()` is simpler:
+* ```typescript
+* init({ service: 'my-app', sampling: 'production' })
+* ```
+*
+* Use factories when you need to customize:
+* ```typescript
+* init({ service: 'my-app', sampler: samplingPresets.production({ baselineSampleRate: 0.05 }) })
+* ```
+*/
+const samplingPresets = {
+	/** Capture everything — best for local development and debugging */
+	development: () => new AlwaysSampler(),
+	/** Only bad outcomes — zero baseline, errors always kept */
+	errorsOnly: () => new AdaptiveSampler({
+		baselineSampleRate: 0,
+		alwaysSampleErrors: true
+	}),
+	/**
+	* Balanced production defaults — 10% baseline + errors + slow traces.
+	* Pass overrides to tune (uses the same option names as AdaptiveSampler).
+	*/
+	production: (overrides) => new AdaptiveSampler({
+		baselineSampleRate: .1,
+		alwaysSampleErrors: true,
+		alwaysSampleSlow: true,
+		slowThresholdMs: 1e3,
+		...overrides
+	}),
+	/** Disable sampling entirely */
+	off: () => new NeverSampler()
+};
+/**
+* Resolve a preset string to a Sampler instance.
+* Used internally by `init()` when `sampling` string is provided.
+*
+* @throws Error if preset is not recognized
+*/
+function resolveSamplingPreset(preset) {
+	switch (preset) {
+		case "development": return samplingPresets.development();
+		case "errors-only": return samplingPresets.errorsOnly();
+		case "production": return samplingPresets.production();
+		case "off": return samplingPresets.off();
+		default: throw new Error(`Unknown sampling preset: "${preset}". Valid presets: development, errors-only, production, off`);
+	}
+}
+/**
+* Create a Link from W3C trace context headers (e.g., from a message queue).
+*
+* This is useful for message consumers that need to link to the producer span.
+* The headers should contain at least a `traceparent` header in W3C format.
+*
+* @param headers - Dictionary containing traceparent/tracestate headers
+* @param attributes - Optional attributes for the link
+* @returns Link object if context could be extracted, null otherwise
+*
+* @example
+* ```typescript
+* // In a Kafka consumer
+* const headers = { traceparent: '00-abc123...-def456...-01' };
+* const link = createLinkFromHeaders(headers);
+* if (link) {
+*   // Use with tracer.startActiveSpan options or ctx.addLink()
+*   tracer.startActiveSpan('process.message', { links: [link] }, span => { ... });
+* }
+* ```
+*/
+function createLinkFromHeaders(headers, attributes) {
+	const traceparent = headers.traceparent || headers["traceparent"];
+	if (!traceparent) return null;
+	const spanContext = parseTraceparent(traceparent);
+	if (!spanContext || !isValidSpanContext(spanContext)) return null;
+	return {
+		context: spanContext,
+		attributes: attributes ?? {}
+	};
+}
+/**
+* Extract Links from a batch of messages for fan-in scenarios.
+*
+* Useful for batch processing where multiple producer spans should be linked.
+* This enables tracing causality in event-driven architectures where a single
+* consumer processes messages from multiple producers.
+*
+* @param messages - List of message objects
+* @param headersKey - Key in each message containing trace headers (default: 'headers')
+* @returns List of Link objects for all valid trace contexts
+*
+* @example
+* ```typescript
+* // Processing a batch of SQS/Kafka messages
+* const messages = [
+*   { body: '...', headers: { traceparent: '...' } },
+*   { body: '...', headers: { traceparent: '...' } },
+* ];
+* const links = extractLinksFromBatch(messages);
+*
+* tracer.startActiveSpan('process.batch', { links }, span => {
+*   for (const msg of messages) {
+*     processMessage(msg);
+*   }
+* });
+* ```
+*/
+function extractLinksFromBatch(messages, headersKey = "headers") {
+	const links = [];
+	for (const msg of messages) {
+		const msgHeaders = msg[headersKey];
+		if (msgHeaders && typeof msgHeaders === "object" && msgHeaders !== null) {
+			const link = createLinkFromHeaders(msgHeaders, { "messaging.batch.message_index": links.length });
+			if (link) links.push(link);
+		}
+	}
+	return links;
+}
+/**
+* Parse W3C traceparent header into SpanContext
+* Format: version-traceId-spanId-traceFlags (e.g., 00-abc123...-def456...-01)
+*
+* @see https://www.w3.org/TR/trace-context/#traceparent-header
+*/
+function parseTraceparent(traceparent) {
+	const match = traceparent.match(/^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/i);
+	if (!match || match.length < 5) return null;
+	const version = match[1];
+	const traceId = match[2];
+	const spanId = match[3];
+	const flags = match[4];
+	if (!version || !traceId || !spanId || !flags) return null;
+	if (version === "ff") return null;
+	return {
+		traceId,
+		spanId,
+		traceFlags: Number.parseInt(flags, 16),
+		isRemote: true
+	};
+}
+/**
+* Check if a SpanContext is valid (has non-zero trace and span IDs)
+*/
+function isValidSpanContext(spanContext) {
+	if (!spanContext) return false;
+	return spanContext.traceId !== "00000000000000000000000000000000" && spanContext.spanId !== "0000000000000000";
+}
+
+//#endregion
+export { AUTOTEL_SAMPLING_TAIL_EVALUATED, AUTOTEL_SAMPLING_TAIL_KEEP, AdaptiveSampler, AlwaysSampler, CompositeSampler, FeatureFlagSampler, NeverSampler, RandomSampler, UserIdSampler, createLinkFromHeaders, extractLinksFromBatch, resolveSamplingPreset, samplingPresets };
 //# sourceMappingURL=sampling.js.map

package/dist/sampling.js.map

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"sampling.js"}
+{"version":3,"file":"sampling.js","names":[],"sources":["../src/sampling.ts"],"sourcesContent":["/**\n * Sampling Strategies\n *\n * Provides intelligent sampling beyond simple random rates.\n * Helps reduce telemetry costs while capturing critical data.\n *\n * Key strategies:\n * - Always trace errors and slow requests (critical for debugging)\n * - Sample by user ID for consistent request tracing\n * - Adaptive sampling based on load\n * - Sample by feature flags for A/B testing correlation\n *\n * @example\n * ```typescript\n * import { AlwaysOnErrorSampler, UserIdSampler } from './sampling'\n *\n * @Instrumented({\n *   serviceName: 'user',\n *   sampler: new AlwaysOnErrorSampler(0.1) // 10% baseline, 100% on errors\n * })\n * class UserService { }\n * ```\n */\n\nimport type { Link, Attributes } from '@opentelemetry/api';\nimport { TraceFlags } from '@opentelemetry/api';\nimport { type Logger } from './logger';\n\n/**\n * Tail sampling attribute keys (autotel-internal, not OTel semconv)\n */\nexport const AUTOTEL_SAMPLING_TAIL_KEEP = 'autotel.sampling.tail.keep';\nexport const AUTOTEL_SAMPLING_TAIL_EVALUATED =\n  'autotel.sampling.tail.evaluated';\n\n/**\n * Sampler interface - return true to trace, false to skip\n */\nexport interface Sampler {\n  /**\n   * Decide whether to trace this operation\n   *\n   * @param context - Sampling context\n   * @returns true to trace, false to skip\n   */\n  shouldSample(context: SamplingContext): boolean;\n\n  /**\n   * Whether this sampler needs tail sampling (post-execution decision)\n   * If true, spans are always created and shouldKeepTrace() is called after execution\n   *\n   * @returns true if this sampler needs to evaluate after operation completes\n   */\n  needsTailSampling?(): boolean;\n\n  /**\n   * Re-evaluate sampling decision after operation completes (tail sampling)\n   * Only called if needsTailSampling() returns true\n   *\n   * @param context - Sampling context\n   * @param result - Operation result\n   * @returns true if this trace should be kept, false to drop it\n   */\n  shouldKeepTrace?(context: SamplingContext, result: OperationResult): boolean;\n}\n\n/**\n * Context information for sampling decisions\n */\nexport interface SamplingContext {\n  /** Operation name */\n  operationName: string;\n  /** Method arguments (for extracting user IDs, etc.) */\n  args: unknown[];\n  /** Optional metadata (e.g., feature flags, request headers) */\n  metadata?: Record<string, unknown>;\n  /** Optional span links for links-based sampling */\n  links?: Link[];\n}\n\n/**\n * Result of a trace operation (for post-execution sampling)\n */\nexport interface OperationResult {\n  /** Whether the operation succeeded */\n  success: boolean;\n  /** Duration in milliseconds */\n  duration: number;\n  /** Error if operation failed */\n  error?: Error;\n}\n\n/**\n * Simple random sampler\n *\n * @example\n * ```typescript\n * new RandomSampler(0.1) // Sample 10% of requests\n * ```\n */\nexport class RandomSampler implements Sampler {\n  constructor(private readonly sampleRate: number) {\n    if (sampleRate < 0 || sampleRate > 1) {\n      throw new Error('Sample rate must be between 0 and 1');\n    }\n  }\n\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  shouldSample(_context: SamplingContext): boolean {\n    return Math.random() < this.sampleRate;\n  }\n}\n\n/**\n * Always sample (100% tracing)\n */\nexport class AlwaysSampler implements Sampler {\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  shouldSample(_context: SamplingContext): boolean {\n    return true;\n  }\n}\n\n/**\n * Never sample (0% tracing)\n */\nexport class NeverSampler implements Sampler {\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  shouldSample(_context: SamplingContext): boolean {\n    return false;\n  }\n}\n\n/**\n * Adaptive sampler that always traces errors and slow requests\n *\n * This is the recommended sampler for production use.\n * It ensures you never miss critical issues while keeping costs down.\n *\n * Strategy:\n * - Always trace errors (critical for debugging)\n * - Always trace slow requests (performance issues)\n * - Use baseline sample rate for successful fast requests\n *\n * **IMPORTANT - Tail Sampling Requirement:**\n * This sampler uses tail sampling (makes decisions AFTER execution).\n * You MUST use TailSamplingSpanProcessor for it to work correctly:\n *\n * - If using initInstrumentation(): TailSamplingSpanProcessor is auto-configured\n * - If using custom TracerProvider: You MUST manually register TailSamplingSpanProcessor\n *\n * Without TailSamplingSpanProcessor, ALL spans are exported (defeating the cost savings).\n *\n * @see TailSamplingSpanProcessor\n * @see README.md \"Tail Sampling with Custom Providers\" section\n *\n * @example\n * ```typescript\n * new AdaptiveSampler({\n *   baselineSampleRate: 0.1,    // 10% of normal requests\n *   slowThresholdMs: 1000,       // Requests > 1s are \"slow\"\n *   alwaysSampleErrors: true,    // Always trace errors\n *   alwaysSampleSlow: true       // Always trace slow requests\n * })\n * ```\n */\nexport class AdaptiveSampler implements Sampler {\n  private baselineSampleRate: number;\n  private slowThresholdMs: number;\n  private alwaysSampleErrors: boolean;\n  private alwaysSampleSlow: boolean;\n  private linksBased: boolean;\n  private linksRate: number;\n  private logger?: Logger;\n\n  // Track whether we should sample this request\n  private readonly samplingDecisions = new WeakMap<unknown[], boolean>();\n  // Track operation results to enable post-execution decision\n  private readonly operationResults = new WeakMap<unknown[], OperationResult>();\n\n  constructor(\n    options: {\n      baselineSampleRate?: number;\n      slowThresholdMs?: number;\n      alwaysSampleErrors?: boolean;\n      alwaysSampleSlow?: boolean;\n      /** Enable links-based sampling for event-driven architectures */\n      linksBased?: boolean;\n      /** Sampling rate for spans linked to sampled spans (0.0-1.0) */\n      linksRate?: number;\n      logger?: Logger;\n    } = {},\n  ) {\n    this.baselineSampleRate = options.baselineSampleRate ?? 0.1;\n    this.slowThresholdMs = options.slowThresholdMs ?? 1000;\n    this.alwaysSampleErrors = options.alwaysSampleErrors ?? true;\n    this.alwaysSampleSlow = options.alwaysSampleSlow ?? true;\n    this.linksBased = options.linksBased ?? false;\n    this.linksRate = options.linksRate ?? 1;\n    this.logger = options.logger;\n\n    if (this.baselineSampleRate < 0 || this.baselineSampleRate > 1) {\n      throw new Error('Baseline sample rate must be between 0 and 1');\n    }\n    if (this.linksRate < 0 || this.linksRate > 1) {\n      throw new Error('Links rate must be between 0 and 1');\n    }\n  }\n\n  needsTailSampling(): boolean {\n    // AdaptiveSampler ALWAYS needs tail sampling to implement error/slow capture\n    return true;\n  }\n\n  shouldSample(context: SamplingContext): boolean {\n    // For tail sampling, we optimistically create spans for all requests\n    // The real decision happens in shouldKeepTrace() after execution\n    // We still store the baseline decision for shouldKeepTrace() to use\n    const baselineDecision = Math.random() < this.baselineSampleRate;\n    this.samplingDecisions.set(context.args, baselineDecision);\n\n    // Always return true to create the span (tail sampling will decide if we keep it)\n    return true;\n  }\n\n  /**\n   * Check if any links point to sampled spans.\n   *\n   * A span is considered linked to a sampled span if any of its links\n   * have trace_flags with the sampled bit set (0x01).\n   *\n   * @param links - Array of span links to check\n   * @returns true if any linked span is sampled, false otherwise\n   */\n  hasSampledLink(links: Link[]): boolean {\n    if (!links || links.length === 0) {\n      return false;\n    }\n    return links.some(\n      (link) =>\n        link.context && (link.context.traceFlags & TraceFlags.SAMPLED) !== 0,\n    );\n  }\n\n  /**\n   * Re-evaluate sampling decision after operation completes\n   *\n   * This allows us to always capture errors and slow requests,\n   * even if they weren't initially sampled.\n   *\n   * @param context - Sampling context\n   * @param result - Operation result\n   * @returns true if this operation should be kept (not discarded)\n   */\n  shouldKeepTrace(context: SamplingContext, result: OperationResult): boolean {\n    const baselineDecision = this.samplingDecisions.get(context.args) ?? false;\n\n    // Always keep errors\n    if (this.alwaysSampleErrors && !result.success) {\n      if (!baselineDecision) {\n        this.logger?.debug(\n          {\n            operation: context.operationName,\n            error: result.error?.message,\n          },\n          'Adaptive sampling: Keeping error trace',\n        );\n      }\n      return true;\n    }\n\n    // Always keep slow requests\n    if (this.alwaysSampleSlow && result.duration >= this.slowThresholdMs) {\n      if (!baselineDecision) {\n        this.logger?.debug(\n          {\n            operation: context.operationName,\n            duration: result.duration,\n          },\n          'Adaptive sampling: Keeping slow trace',\n        );\n      }\n      return true;\n    }\n\n    // Check for sampled links (links-based sampling for event-driven systems)\n    if (\n      this.linksBased &&\n      context.links &&\n      this.hasSampledLink(context.links)\n    ) {\n      // Use linksRate to decide whether to keep the linked span\n      const keepLinked = Math.random() < this.linksRate;\n      if (keepLinked && !baselineDecision) {\n        this.logger?.debug(\n          {\n            operation: context.operationName,\n            linkCount: context.links.length,\n          },\n          'Adaptive sampling: Keeping trace due to sampled link',\n        );\n      }\n      return keepLinked;\n    }\n\n    // Otherwise, use baseline decision\n    return baselineDecision;\n  }\n}\n\n/**\n * User-based sampler for consistent tracing\n *\n * Always samples requests from specific user IDs.\n * Useful for debugging specific user issues or monitoring VIP users.\n *\n * @example\n * ```typescript\n * new UserIdSampler({\n *   baselineSampleRate: 0.01,      // 1% of normal users\n *   alwaysSampleUsers: ['vip_123'], // Always trace VIP users\n *   extractUserId: (args) => args[0]?.userId // Extract user ID from first arg\n * })\n * ```\n */\nexport class UserIdSampler implements Sampler {\n  private baselineSampleRate: number;\n  private alwaysSampleUsers: Set<string>;\n  private extractUserId: (args: unknown[]) => string | undefined;\n  private logger?: Logger;\n\n  constructor(options: {\n    baselineSampleRate?: number;\n    alwaysSampleUsers?: string[];\n    extractUserId: (args: unknown[]) => string | undefined;\n    logger?: Logger;\n  }) {\n    this.baselineSampleRate = options.baselineSampleRate ?? 0.1;\n    this.alwaysSampleUsers = new Set(options.alwaysSampleUsers || []);\n    this.extractUserId = options.extractUserId;\n    this.logger = options.logger;\n  }\n\n  shouldSample(context: SamplingContext): boolean {\n    const userId = this.extractUserId(context.args);\n\n    // Always sample specific users\n    if (userId && this.alwaysSampleUsers.has(userId)) {\n      this.logger?.debug(\n        {\n          operation: context.operationName,\n          userId,\n        },\n        'Sampling user request',\n      );\n      return true;\n    }\n\n    // For consistent per-user sampling, hash the user ID\n    if (userId) {\n      const hash = this.hashString(userId);\n      return hash < this.baselineSampleRate;\n    }\n\n    // Fallback to random sampling if no user ID\n    return Math.random() < this.baselineSampleRate;\n  }\n\n  /**\n   * Add user IDs to always-sample list\n   */\n  addAlwaysSampleUsers(...userIds: string[]): void {\n    for (const userId of userIds) {\n      this.alwaysSampleUsers.add(userId);\n    }\n  }\n\n  /**\n   * Remove user IDs from always-sample list\n   */\n  removeAlwaysSampleUsers(...userIds: string[]): void {\n    for (const userId of userIds) {\n      this.alwaysSampleUsers.delete(userId);\n    }\n  }\n\n  /**\n   * Simple hash function for consistent user sampling\n   */\n  private hashString(str: string): number {\n    let hash = 0;\n    for (let i = 0; i < str.length; i++) {\n      const char = str.codePointAt(i) ?? 0;\n      hash = (hash << 5) - hash + char;\n      hash = hash & hash; // Convert to 32-bit integer\n    }\n    return Math.abs(hash) / 2_147_483_647; // Normalize to 0-1\n  }\n}\n\n/**\n * Composite sampler that combines multiple samplers\n *\n * Samples if ANY of the child samplers returns true.\n *\n * @example\n * ```typescript\n * new CompositeSampler([\n *   new UserIdSampler({ extractUserId: (args) => args[0]?.userId }),\n *   new AdaptiveSampler({ baselineSampleRate: 0.1 })\n * ])\n * ```\n */\nexport class CompositeSampler implements Sampler {\n  constructor(private readonly samplers: Sampler[]) {\n    if (samplers.length === 0) {\n      throw new Error('CompositeSampler requires at least one child sampler');\n    }\n  }\n\n  shouldSample(context: SamplingContext): boolean {\n    return this.samplers.some((sampler) => sampler.shouldSample(context));\n  }\n}\n\n/**\n * Feature flag sampler\n *\n * Always samples requests with specific feature flags enabled.\n * Perfect for correlating A/B test experiments with metrics.\n *\n * @example\n * ```typescript\n * new FeatureFlagSampler({\n *   baselineSampleRate: 0.01,\n *   alwaysSampleFlags: ['new_checkout', 'experimental_ui'],\n *   extractFlags: (args, metadata) => metadata?.featureFlags\n * })\n * ```\n */\nexport class FeatureFlagSampler implements Sampler {\n  private baselineSampleRate: number;\n  private alwaysSampleFlags: Set<string>;\n  private extractFlags: (\n    args: unknown[],\n    metadata?: Record<string, unknown>,\n  ) => string[] | undefined;\n  private logger?: Logger;\n\n  constructor(options: {\n    baselineSampleRate?: number;\n    alwaysSampleFlags?: string[];\n    extractFlags: (\n      args: unknown[],\n      metadata?: Record<string, unknown>,\n    ) => string[] | undefined;\n    logger?: Logger;\n  }) {\n    this.baselineSampleRate = options.baselineSampleRate ?? 0.1;\n    this.alwaysSampleFlags = new Set(options.alwaysSampleFlags || []);\n    this.extractFlags = options.extractFlags;\n    this.logger = options.logger;\n  }\n\n  shouldSample(context: SamplingContext): boolean {\n    const flags = this.extractFlags(context.args, context.metadata);\n\n    // Always sample if any monitored flag is enabled\n    if (flags && flags.some((flag) => this.alwaysSampleFlags.has(flag))) {\n      this.logger?.debug(\n        {\n          operation: context.operationName,\n          flags,\n        },\n        'Sampling feature flag request',\n      );\n      return true;\n    }\n\n    // Fallback to random sampling\n    return Math.random() < this.baselineSampleRate;\n  }\n\n  /**\n   * Add feature flags to always-sample list\n   */\n  addAlwaysSampleFlags(...flags: string[]): void {\n    for (const flag of flags) {\n      this.alwaysSampleFlags.add(flag);\n    }\n  }\n\n  /**\n   * Remove feature flags from always-sample list\n   */\n  removeAlwaysSampleFlags(...flags: string[]): void {\n    for (const flag of flags) {\n      this.alwaysSampleFlags.delete(flag);\n    }\n  }\n}\n\n// ============================================================================\n// Sampling Presets\n// ============================================================================\n\n/**\n * Named sampling presets for common environments.\n * Use with `init({ sampling: 'production' })` or directly via factories.\n */\nexport type SamplingPreset =\n  | 'development'\n  | 'errors-only'\n  | 'production'\n  | 'off';\n\n/**\n * Sampling preset factories.\n *\n * For most users, the string shorthand on `init()` is simpler:\n * ```typescript\n * init({ service: 'my-app', sampling: 'production' })\n * ```\n *\n * Use factories when you need to customize:\n * ```typescript\n * init({ service: 'my-app', sampler: samplingPresets.production({ baselineSampleRate: 0.05 }) })\n * ```\n */\nexport const samplingPresets = {\n  /** Capture everything — best for local development and debugging */\n  development: () => new AlwaysSampler(),\n\n  /** Only bad outcomes — zero baseline, errors always kept */\n  errorsOnly: () =>\n    new AdaptiveSampler({\n      baselineSampleRate: 0,\n      alwaysSampleErrors: true,\n    }),\n\n  /**\n   * Balanced production defaults — 10% baseline + errors + slow traces.\n   * Pass overrides to tune (uses the same option names as AdaptiveSampler).\n   */\n  production: (overrides?: {\n    baselineSampleRate?: number;\n    slowThresholdMs?: number;\n    alwaysSampleErrors?: boolean;\n    alwaysSampleSlow?: boolean;\n  }) =>\n    new AdaptiveSampler({\n      baselineSampleRate: 0.1,\n      alwaysSampleErrors: true,\n      alwaysSampleSlow: true,\n      slowThresholdMs: 1000,\n      ...overrides,\n    }),\n\n  /** Disable sampling entirely */\n  off: () => new NeverSampler(),\n};\n\n/**\n * Resolve a preset string to a Sampler instance.\n * Used internally by `init()` when `sampling` string is provided.\n *\n * @throws Error if preset is not recognized\n */\nexport function resolveSamplingPreset(preset: SamplingPreset): Sampler {\n  switch (preset) {\n    case 'development':\n      return samplingPresets.development();\n    case 'errors-only':\n      return samplingPresets.errorsOnly();\n    case 'production':\n      return samplingPresets.production();\n    case 'off':\n      return samplingPresets.off();\n    default:\n      throw new Error(\n        `Unknown sampling preset: \"${preset}\". Valid presets: development, errors-only, production, off`,\n      );\n  }\n}\n\n// ============================================================================\n// Link Helper Functions\n// ============================================================================\n\n/**\n * Create a Link from W3C trace context headers (e.g., from a message queue).\n *\n * This is useful for message consumers that need to link to the producer span.\n * The headers should contain at least a `traceparent` header in W3C format.\n *\n * @param headers - Dictionary containing traceparent/tracestate headers\n * @param attributes - Optional attributes for the link\n * @returns Link object if context could be extracted, null otherwise\n *\n * @example\n * ```typescript\n * // In a Kafka consumer\n * const headers = { traceparent: '00-abc123...-def456...-01' };\n * const link = createLinkFromHeaders(headers);\n * if (link) {\n *   // Use with tracer.startActiveSpan options or ctx.addLink()\n *   tracer.startActiveSpan('process.message', { links: [link] }, span => { ... });\n * }\n * ```\n */\nexport function createLinkFromHeaders(\n  headers: Record<string, string>,\n  attributes?: Attributes,\n): Link | null {\n  // Parse W3C traceparent header directly for reliability\n  // Format: version-traceId-spanId-traceFlags (e.g., 00-abc123...-def456...-01)\n  const traceparent = headers.traceparent || headers['traceparent'];\n  if (!traceparent) {\n    return null;\n  }\n\n  const spanContext = parseTraceparent(traceparent);\n  if (!spanContext || !isValidSpanContext(spanContext)) {\n    return null;\n  }\n\n  return {\n    context: spanContext,\n    attributes: attributes ?? {},\n  };\n}\n\n/**\n * Extract Links from a batch of messages for fan-in scenarios.\n *\n * Useful for batch processing where multiple producer spans should be linked.\n * This enables tracing causality in event-driven architectures where a single\n * consumer processes messages from multiple producers.\n *\n * @param messages - List of message objects\n * @param headersKey - Key in each message containing trace headers (default: 'headers')\n * @returns List of Link objects for all valid trace contexts\n *\n * @example\n * ```typescript\n * // Processing a batch of SQS/Kafka messages\n * const messages = [\n *   { body: '...', headers: { traceparent: '...' } },\n *   { body: '...', headers: { traceparent: '...' } },\n * ];\n * const links = extractLinksFromBatch(messages);\n *\n * tracer.startActiveSpan('process.batch', { links }, span => {\n *   for (const msg of messages) {\n *     processMessage(msg);\n *   }\n * });\n * ```\n */\nexport function extractLinksFromBatch(\n  messages: Array<{ [key: string]: unknown }>,\n  headersKey: string = 'headers',\n): Link[] {\n  const links: Link[] = [];\n\n  for (const msg of messages) {\n    const msgHeaders = msg[headersKey];\n    if (msgHeaders && typeof msgHeaders === 'object' && msgHeaders !== null) {\n      const link = createLinkFromHeaders(msgHeaders as Record<string, string>, {\n        'messaging.batch.message_index': links.length,\n      });\n      if (link) {\n        links.push(link);\n      }\n    }\n  }\n\n  return links;\n}\n\n/**\n * Parse W3C traceparent header into SpanContext\n * Format: version-traceId-spanId-traceFlags (e.g., 00-abc123...-def456...-01)\n *\n * @see https://www.w3.org/TR/trace-context/#traceparent-header\n */\nfunction parseTraceparent(\n  traceparent: string,\n): import('@opentelemetry/api').SpanContext | null {\n  // W3C traceparent format: version-traceId-parentId-traceFlags\n  // Example: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01\n  const TRACEPARENT_REGEX =\n    /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/i;\n\n  const match = traceparent.match(TRACEPARENT_REGEX);\n  if (!match || match.length < 5) {\n    return null;\n  }\n\n  const version = match[1];\n  const traceId = match[2];\n  const spanId = match[3];\n  const flags = match[4];\n\n  // Validate all parts are present (TypeScript narrowing)\n  if (!version || !traceId || !spanId || !flags) {\n    return null;\n  }\n\n  // Version 00 is currently the only version, but we should be forward compatible\n  if (version === 'ff') {\n    // Version ff is invalid according to spec\n    return null;\n  }\n\n  return {\n    traceId,\n    spanId,\n    traceFlags: Number.parseInt(flags, 16),\n    isRemote: true,\n  };\n}\n\n/**\n * Check if a SpanContext is valid (has non-zero trace and span IDs)\n */\nfunction isValidSpanContext(\n  spanContext: import('@opentelemetry/api').SpanContext | null,\n): spanContext is import('@opentelemetry/api').SpanContext {\n  if (!spanContext) return false;\n  // TraceId should not be all zeros (00000000000000000000000000000000)\n  // SpanId should not be all zeros (0000000000000000)\n  return (\n    spanContext.traceId !== '00000000000000000000000000000000' &&\n    spanContext.spanId !== '0000000000000000'\n  );\n}\n"],"mappings":"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"}

package/dist/security-schema.cjs

@@ -1,61 +1,81 @@
-'use strict';
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
-// src/security-schema.ts
-var SECURITY_SEVERITIES = [
-  "info",
-  "warning",
-  "error",
-  "critical"
+//#region src/security-schema.ts
+/** All severities, lowest first. */
+const SECURITY_SEVERITIES = [
+	"info",
+	"warning",
+	"error",
+	"critical"
 ];
-var SECURITY_SEVERITY_RANK = {
-  info: 0,
-  warning: 1,
-  error: 2,
-  critical: 3
+/** Numeric rank per severity for threshold comparisons. */
+const SECURITY_SEVERITY_RANK = {
+	info: 0,
+	warning: 1,
+	error: 2,
+	critical: 3
 };
+/**
+* Parse an untrusted value (span attribute, event payload field) into a
+* severity, falling back when it is missing or malformed.
+*/
 function parseSecuritySeverity(value, fallback = "info") {
-  return typeof value === "string" && value in SECURITY_SEVERITY_RANK ? value : fallback;
+	return typeof value === "string" && value in SECURITY_SEVERITY_RANK ? value : fallback;
 }
+/** `true` when `severity` meets or exceeds `min`. */
 function securitySeverityAtLeast(severity, min) {
-  return SECURITY_SEVERITY_RANK[severity] >= SECURITY_SEVERITY_RANK[min];
+	return SECURITY_SEVERITY_RANK[severity] >= SECURITY_SEVERITY_RANK[min];
 }
+/** The higher-ranked of two severities (e.g. escalate failures to ≥ error). */
 function escalateSecuritySeverity(severity, floor) {
-  return SECURITY_SEVERITY_RANK[severity] >= SECURITY_SEVERITY_RANK[floor] ? severity : floor;
+	return SECURITY_SEVERITY_RANK[severity] >= SECURITY_SEVERITY_RANK[floor] ? severity : floor;
 }
-var SECURITY_ATTR = {
-  /** Marker set on every span carrying a security event. */
-  marker: "autotel.security",
-  /** Set when the event was force-kept through tail sampling. */
-  forceKeep: "autotel.security.force_keep",
-  event: "security.event",
-  category: "security.category",
-  outcome: "security.outcome",
-  severity: "security.severity",
-  actorId: "security.actor_id",
-  targetType: "security.target_type",
-  targetId: "security.target_id",
-  tenantId: "security.tenant_id",
-  reason: "security.reason",
-  /** Custom metadata keys dropped because they looked credential-shaped. */
-  droppedKeys: "security.dropped_keys",
-  /** Set by the signal processor on suspicious request paths. */
-  suspiciousRequest: "security.suspicious_request",
-  /** Pattern name that flagged a suspicious request, e.g. `path_traversal`. */
-  signal: "security.signal"
+/**
+* Span attribute keys of the security schema. Emitters and consumers must
+* reference these instead of re-typing the strings.
+*/
+const SECURITY_ATTR = {
+	/** Marker set on every span carrying a security event. */
+	marker: "autotel.security",
+	/** Set when the event was force-kept through tail sampling. */
+	forceKeep: "autotel.security.force_keep",
+	event: "security.event",
+	category: "security.category",
+	outcome: "security.outcome",
+	severity: "security.severity",
+	actorId: "security.actor_id",
+	targetType: "security.target_type",
+	targetId: "security.target_id",
+	tenantId: "security.tenant_id",
+	reason: "security.reason",
+	/** Custom metadata keys dropped because they looked credential-shaped. */
+	droppedKeys: "security.dropped_keys",
+	/** Set by the signal processor on suspicious request paths. */
+	suspiciousRequest: "security.suspicious_request",
+	/** Pattern name that flagged a suspicious request, e.g. `path_traversal`. */
+	signal: "security.signal"
 };
-var SECURITY_METRICS = {
-  events: "autotel.security.events",
-  httpSuspicious: "autotel.security.http.suspicious",
-  httpDenied: "autotel.security.http.denied",
-  anomaly: "autotel.security.anomaly",
-  heartbeat: "autotel.security.heartbeat"
+/** Metric names emitted by the security instrumentation. */
+const SECURITY_METRICS = {
+	events: "autotel.security.events",
+	httpSuspicious: "autotel.security.http.suspicious",
+	httpDenied: "autotel.security.http.denied",
+	anomaly: "autotel.security.anomaly",
+	heartbeat: "autotel.security.heartbeat"
 };
-var SECURITY_DENIED_STATUSES = [401, 403, 429];
-var HTTP_STATUS_ATTRIBUTES = [
-  "http.response.status_code",
-  "http.status_code"
+/** HTTP statuses counted as denied responses by default. */
+const SECURITY_DENIED_STATUSES = [
+	401,
+	403,
+	429
 ];
+/**
+* Span attributes carrying the HTTP response status, current semconv
+* first, legacy fallback second.
+*/
+const HTTP_STATUS_ATTRIBUTES = ["http.response.status_code", "http.status_code"];
 
+//#endregion
 exports.HTTP_STATUS_ATTRIBUTES = HTTP_STATUS_ATTRIBUTES;
 exports.SECURITY_ATTR = SECURITY_ATTR;
 exports.SECURITY_DENIED_STATUSES = SECURITY_DENIED_STATUSES;
@@ -65,5 +85,4 @@ exports.SECURITY_SEVERITY_RANK = SECURITY_SEVERITY_RANK;
 exports.escalateSecuritySeverity = escalateSecuritySeverity;
 exports.parseSecuritySeverity = parseSecuritySeverity;
 exports.securitySeverityAtLeast = securitySeverityAtLeast;
-//# sourceMappingURL=security-schema.cjs.map
 //# sourceMappingURL=security-schema.cjs.map

package/dist/security-schema.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/security-schema.ts"],"names":[],"mappings":";;;AAeO,IAAM,mBAAA,GAAmD;AAAA,EAC9D,MAAA;AAAA,EACA,SAAA;AAAA,EACA,OAAA;AAAA,EACA;AACF;AAGO,IAAM,sBAAA,GAA2D;AAAA,EACtE,IAAA,EAAM,CAAA;AAAA,EACN,OAAA,EAAS,CAAA;AAAA,EACT,KAAA,EAAO,CAAA;AAAA,EACP,QAAA,EAAU;AACZ;AAMO,SAAS,qBAAA,CACd,KAAA,EACA,QAAA,GAA6B,MAAA,EACX;AAClB,EAAA,OAAO,OAAO,KAAA,KAAU,QAAA,IAAY,KAAA,IAAS,yBACxC,KAAA,GACD,QAAA;AACN;AAGO,SAAS,uBAAA,CACd,UACA,GAAA,EACS;AACT,EAAA,OAAO,sBAAA,CAAuB,QAAQ,CAAA,IAAK,sBAAA,CAAuB,GAAG,CAAA;AACvE;AAGO,SAAS,wBAAA,CACd,UACA,KAAA,EACkB;AAClB,EAAA,OAAO,uBAAuB,QAAQ,CAAA,IAAK,sBAAA,CAAuB,KAAK,IACnE,QAAA,GACA,KAAA;AACN;AAMO,IAAM,aAAA,GAAgB;AAAA;AAAA,EAE3B,MAAA,EAAQ,kBAAA;AAAA;AAAA,EAER,SAAA,EAAW,6BAAA;AAAA,EACX,KAAA,EAAO,gBAAA;AAAA,EACP,QAAA,EAAU,mBAAA;AAAA,EACV,OAAA,EAAS,kBAAA;AAAA,EACT,QAAA,EAAU,mBAAA;AAAA,EACV,OAAA,EAAS,mBAAA;AAAA,EACT,UAAA,EAAY,sBAAA;AAAA,EACZ,QAAA,EAAU,oBAAA;AAAA,EACV,QAAA,EAAU,oBAAA;AAAA,EACV,MAAA,EAAQ,iBAAA;AAAA;AAAA,EAER,WAAA,EAAa,uBAAA;AAAA;AAAA,EAEb,iBAAA,EAAmB,6BAAA;AAAA;AAAA,EAEnB,MAAA,EAAQ;AACV;AAGO,IAAM,gBAAA,GAAmB;AAAA,EAC9B,MAAA,EAAQ,yBAAA;AAAA,EACR,cAAA,EAAgB,kCAAA;AAAA,EAChB,UAAA,EAAY,8BAAA;AAAA,EACZ,OAAA,EAAS,0BAAA;AAAA,EACT,SAAA,EAAW;AACb;AAGO,IAAM,wBAAA,GAA8C,CAAC,GAAA,EAAK,GAAA,EAAK,GAAG;AAMlE,IAAM,sBAAA,GAA4C;AAAA,EACvD,2BAAA;AAAA,EACA;AACF","file":"security-schema.cjs","sourcesContent":["/**\n * Security telemetry wire schema — the single source of truth for the\n * `security.*` span-attribute contract emitted by `autotel-audit`\n * (`securityEvent()`, `withSecurity()`, `createSecuritySignalProcessor()`)\n * and consumed by `autotel-subscribers`, `autotel-devtools`, and the\n * `autotel security` CLI commands.\n *\n * Dependency-free and side-effect-free by design: safe to import from\n * browser bundles (devtools widget) and anything else that only needs\n * the constants, without pulling in the OpenTelemetry SDK.\n */\n\nexport type SecuritySeverity = 'info' | 'warning' | 'error' | 'critical';\n\n/** All severities, lowest first. */\nexport const SECURITY_SEVERITIES: readonly SecuritySeverity[] = [\n  'info',\n  'warning',\n  'error',\n  'critical',\n];\n\n/** Numeric rank per severity for threshold comparisons. */\nexport const SECURITY_SEVERITY_RANK: Record<SecuritySeverity, number> = {\n  info: 0,\n  warning: 1,\n  error: 2,\n  critical: 3,\n};\n\n/**\n * Parse an untrusted value (span attribute, event payload field) into a\n * severity, falling back when it is missing or malformed.\n */\nexport function parseSecuritySeverity(\n  value: unknown,\n  fallback: SecuritySeverity = 'info',\n): SecuritySeverity {\n  return typeof value === 'string' && value in SECURITY_SEVERITY_RANK\n    ? (value as SecuritySeverity)\n    : fallback;\n}\n\n/** `true` when `severity` meets or exceeds `min`. */\nexport function securitySeverityAtLeast(\n  severity: SecuritySeverity,\n  min: SecuritySeverity,\n): boolean {\n  return SECURITY_SEVERITY_RANK[severity] >= SECURITY_SEVERITY_RANK[min];\n}\n\n/** The higher-ranked of two severities (e.g. escalate failures to ≥ error). */\nexport function escalateSecuritySeverity(\n  severity: SecuritySeverity,\n  floor: SecuritySeverity,\n): SecuritySeverity {\n  return SECURITY_SEVERITY_RANK[severity] >= SECURITY_SEVERITY_RANK[floor]\n    ? severity\n    : floor;\n}\n\n/**\n * Span attribute keys of the security schema. Emitters and consumers must\n * reference these instead of re-typing the strings.\n */\nexport const SECURITY_ATTR = {\n  /** Marker set on every span carrying a security event. */\n  marker: 'autotel.security',\n  /** Set when the event was force-kept through tail sampling. */\n  forceKeep: 'autotel.security.force_keep',\n  event: 'security.event',\n  category: 'security.category',\n  outcome: 'security.outcome',\n  severity: 'security.severity',\n  actorId: 'security.actor_id',\n  targetType: 'security.target_type',\n  targetId: 'security.target_id',\n  tenantId: 'security.tenant_id',\n  reason: 'security.reason',\n  /** Custom metadata keys dropped because they looked credential-shaped. */\n  droppedKeys: 'security.dropped_keys',\n  /** Set by the signal processor on suspicious request paths. */\n  suspiciousRequest: 'security.suspicious_request',\n  /** Pattern name that flagged a suspicious request, e.g. `path_traversal`. */\n  signal: 'security.signal',\n} as const;\n\n/** Metric names emitted by the security instrumentation. */\nexport const SECURITY_METRICS = {\n  events: 'autotel.security.events',\n  httpSuspicious: 'autotel.security.http.suspicious',\n  httpDenied: 'autotel.security.http.denied',\n  anomaly: 'autotel.security.anomaly',\n  heartbeat: 'autotel.security.heartbeat',\n} as const;\n\n/** HTTP statuses counted as denied responses by default. */\nexport const SECURITY_DENIED_STATUSES: readonly number[] = [401, 403, 429];\n\n/**\n * Span attributes carrying the HTTP response status, current semconv\n * first, legacy fallback second.\n */\nexport const HTTP_STATUS_ATTRIBUTES: readonly string[] = [\n  'http.response.status_code',\n  'http.status_code',\n];\n"]}
+{"version":3,"file":"security-schema.cjs","names":[],"sources":["../src/security-schema.ts"],"sourcesContent":["/**\n * Security telemetry wire schema — the single source of truth for the\n * `security.*` span-attribute contract emitted by `autotel-audit`\n * (`securityEvent()`, `withSecurity()`, `createSecuritySignalProcessor()`)\n * and consumed by `autotel-subscribers`, `autotel-devtools`, and the\n * `autotel security` CLI commands.\n *\n * Dependency-free and side-effect-free by design: safe to import from\n * browser bundles (devtools widget) and anything else that only needs\n * the constants, without pulling in the OpenTelemetry SDK.\n */\n\nexport type SecuritySeverity = 'info' | 'warning' | 'error' | 'critical';\n\n/** All severities, lowest first. */\nexport const SECURITY_SEVERITIES: readonly SecuritySeverity[] = [\n  'info',\n  'warning',\n  'error',\n  'critical',\n];\n\n/** Numeric rank per severity for threshold comparisons. */\nexport const SECURITY_SEVERITY_RANK: Record<SecuritySeverity, number> = {\n  info: 0,\n  warning: 1,\n  error: 2,\n  critical: 3,\n};\n\n/**\n * Parse an untrusted value (span attribute, event payload field) into a\n * severity, falling back when it is missing or malformed.\n */\nexport function parseSecuritySeverity(\n  value: unknown,\n  fallback: SecuritySeverity = 'info',\n): SecuritySeverity {\n  return typeof value === 'string' && value in SECURITY_SEVERITY_RANK\n    ? (value as SecuritySeverity)\n    : fallback;\n}\n\n/** `true` when `severity` meets or exceeds `min`. */\nexport function securitySeverityAtLeast(\n  severity: SecuritySeverity,\n  min: SecuritySeverity,\n): boolean {\n  return SECURITY_SEVERITY_RANK[severity] >= SECURITY_SEVERITY_RANK[min];\n}\n\n/** The higher-ranked of two severities (e.g. escalate failures to ≥ error). */\nexport function escalateSecuritySeverity(\n  severity: SecuritySeverity,\n  floor: SecuritySeverity,\n): SecuritySeverity {\n  return SECURITY_SEVERITY_RANK[severity] >= SECURITY_SEVERITY_RANK[floor]\n    ? severity\n    : floor;\n}\n\n/**\n * Span attribute keys of the security schema. Emitters and consumers must\n * reference these instead of re-typing the strings.\n */\nexport const SECURITY_ATTR = {\n  /** Marker set on every span carrying a security event. */\n  marker: 'autotel.security',\n  /** Set when the event was force-kept through tail sampling. */\n  forceKeep: 'autotel.security.force_keep',\n  event: 'security.event',\n  category: 'security.category',\n  outcome: 'security.outcome',\n  severity: 'security.severity',\n  actorId: 'security.actor_id',\n  targetType: 'security.target_type',\n  targetId: 'security.target_id',\n  tenantId: 'security.tenant_id',\n  reason: 'security.reason',\n  /** Custom metadata keys dropped because they looked credential-shaped. */\n  droppedKeys: 'security.dropped_keys',\n  /** Set by the signal processor on suspicious request paths. */\n  suspiciousRequest: 'security.suspicious_request',\n  /** Pattern name that flagged a suspicious request, e.g. `path_traversal`. */\n  signal: 'security.signal',\n} as const;\n\n/** Metric names emitted by the security instrumentation. */\nexport const SECURITY_METRICS = {\n  events: 'autotel.security.events',\n  httpSuspicious: 'autotel.security.http.suspicious',\n  httpDenied: 'autotel.security.http.denied',\n  anomaly: 'autotel.security.anomaly',\n  heartbeat: 'autotel.security.heartbeat',\n} as const;\n\n/** HTTP statuses counted as denied responses by default. */\nexport const SECURITY_DENIED_STATUSES: readonly number[] = [401, 403, 429];\n\n/**\n * Span attributes carrying the HTTP response status, current semconv\n * first, legacy fallback second.\n */\nexport const HTTP_STATUS_ATTRIBUTES: readonly string[] = [\n  'http.response.status_code',\n  'http.status_code',\n];\n"],"mappings":";;;;AAeA,MAAa,sBAAmD;CAC9D;CACA;CACA;CACA;AACF;;AAGA,MAAa,yBAA2D;CACtE,MAAM;CACN,SAAS;CACT,OAAO;CACP,UAAU;AACZ;;;;;AAMA,SAAgB,sBACd,OACA,WAA6B,QACX;CAClB,OAAO,OAAO,UAAU,YAAY,SAAS,yBACxC,QACD;AACN;;AAGA,SAAgB,wBACd,UACA,KACS;CACT,OAAO,uBAAuB,aAAa,uBAAuB;AACpE;;AAGA,SAAgB,yBACd,UACA,OACkB;CAClB,OAAO,uBAAuB,aAAa,uBAAuB,SAC9D,WACA;AACN;;;;;AAMA,MAAa,gBAAgB;;CAE3B,QAAQ;;CAER,WAAW;CACX,OAAO;CACP,UAAU;CACV,SAAS;CACT,UAAU;CACV,SAAS;CACT,YAAY;CACZ,UAAU;CACV,UAAU;CACV,QAAQ;;CAER,aAAa;;CAEb,mBAAmB;;CAEnB,QAAQ;AACV;;AAGA,MAAa,mBAAmB;CAC9B,QAAQ;CACR,gBAAgB;CAChB,YAAY;CACZ,SAAS;CACT,WAAW;AACb;;AAGA,MAAa,2BAA8C;CAAC;CAAK;CAAK;AAAG;;;;;AAMzE,MAAa,yBAA4C,CACvD,6BACA,kBACF"}