observability-toolkit 2.0.0 → 2.1.0

package/dist/lib/observability/trace-anomaly-schemas.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Zod schemas for per-span anomaly detection (INV-2).
+ *
+ * ## Data-grounded design (2026-04-06)
+ *
+ * Analysis of 23,448 spans across 3 real sessions revealed:
+ * - All traces are single-span (each hook invocation = 1 span, no parent-child)
+ * - 21 distinct span names; hook:builtin-pre/post-tool is 77% of volume
+ * - Median duration: 1.44ms; p95: 4.78ms; warn at >50ms, critical at >200ms
+ * - Token data is sparse (~2% coverage): input p95=17K, output p95=28K
+ * - 5.6% error rate from hook:tsc-check only ("require is not defined" — known false positive)
+ *
+ * ## OTel spec grounding
+ *
+ * No OTel semconv defines span count, nesting, or complexity limits.
+ * Anomaly signals are anchored to:
+ * - gen_ai.usage.input_tokens / gen_ai.usage.output_tokens (Development stability)
+ * - span.status.code (UNSET=0, OK=1, ERROR=2)
+ * - Duration derived from startTime/endTime HrTime tuples
+ *
+ * ## Recommendation for OTEL2 implementation
+ *
+ * - Use per-span-name thresholds (21 known names; table-driven)
+ * - Primary signals: duration, error_status, input_tokens, output_tokens
+ * - Nesting depth: NOT applicable (data always single-span)
+ * - Span count per trace: flag if >2 (instrumentation loop indicator)
+ * - Unknown span names: flag as anomaly (instrumentation drift indicator)
+ * - Exclude hook:tsc-check from error_status signal (permanent false positive)
+ */
+import { z } from 'zod';
+/**
+ * Span category derived from span name prefix.
+ * Used to select the correct duration threshold table.
+ */
+export declare const spanCategorySchema: z.ZodEnum<{
+    unknown: "unknown";
+    tool: "tool";
+    agent: "agent";
+    hook: "hook";
+    mcp: "mcp";
+}>;
+export type SpanCategory = z.infer<typeof spanCategorySchema>;
+/** Four-level severity mirroring OpenTelemetry log severity groupings. */
+export declare const anomalySeveritySchema: z.ZodEnum<{
+    warn: "warn";
+    error: "error";
+    critical: "critical";
+    none: "none";
+}>;
+export type AnomalySeverity = z.infer<typeof anomalySeveritySchema>;
+/**
+ * Signal types detectable without cross-span correlation.
+ * All signals are derivable from a single ExportedSpan object.
+ */
+export declare const anomalySignalSchema: z.ZodEnum<{
+    input_tokens: "input_tokens";
+    output_tokens: "output_tokens";
+    duration: "duration";
+    error_status: "error_status";
+    unknown_span_name: "unknown_span_name";
+    span_count: "span_count";
+}>;
+export type AnomalySignal = z.infer<typeof anomalySignalSchema>;
+/** Duration thresholds per span category (milliseconds). */
+export declare const durationThresholdsSchema: z.ZodObject<{
+    warnMs: z.ZodNumber;
+    criticalMs: z.ZodNumber;
+}, z.core.$strip>;
+export type DurationThresholds = z.infer<typeof durationThresholdsSchema>;
+/** Token anomaly thresholds (token counts). */
+export declare const tokenAnomalyThresholdsSchema: z.ZodObject<{
+    inputWarnTokens: z.ZodNumber;
+    inputCriticalTokens: z.ZodNumber;
+    outputWarnTokens: z.ZodNumber;
+    outputCriticalTokens: z.ZodNumber;
+}, z.core.$strip>;
+export type TokenAnomalyThresholds = z.infer<typeof tokenAnomalyThresholdsSchema>;
+/** A single fired anomaly signal with observed vs threshold values. */
+export declare const signalAnomalySchema: z.ZodObject<{
+    signal: z.ZodEnum<{
+        input_tokens: "input_tokens";
+        output_tokens: "output_tokens";
+        duration: "duration";
+        error_status: "error_status";
+        unknown_span_name: "unknown_span_name";
+        span_count: "span_count";
+    }>;
+    severity: z.ZodEnum<{
+        warn: "warn";
+        error: "error";
+        critical: "critical";
+        none: "none";
+    }>;
+    observed: z.ZodOptional<z.ZodNumber>;
+    threshold: z.ZodOptional<z.ZodNumber>;
+    detail: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type SignalAnomaly = z.infer<typeof signalAnomalySchema>;
+/** Per-span anomaly assessment. One record per analyzed span. */
+export declare const spanAnomalySchema: z.ZodObject<{
+    spanId: z.ZodString;
+    traceId: z.ZodString;
+    spanName: z.ZodString;
+    category: z.ZodEnum<{
+        unknown: "unknown";
+        tool: "tool";
+        agent: "agent";
+        hook: "hook";
+        mcp: "mcp";
+    }>;
+    overallSeverity: z.ZodEnum<{
+        warn: "warn";
+        error: "error";
+        critical: "critical";
+        none: "none";
+    }>;
+    signals: z.ZodArray<z.ZodObject<{
+        signal: z.ZodEnum<{
+            input_tokens: "input_tokens";
+            output_tokens: "output_tokens";
+            duration: "duration";
+            error_status: "error_status";
+            unknown_span_name: "unknown_span_name";
+            span_count: "span_count";
+        }>;
+        severity: z.ZodEnum<{
+            warn: "warn";
+            error: "error";
+            critical: "critical";
+            none: "none";
+        }>;
+        observed: z.ZodOptional<z.ZodNumber>;
+        threshold: z.ZodOptional<z.ZodNumber>;
+        detail: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    excluded: z.ZodBoolean;
+}, z.core.$strip>;
+export type SpanAnomaly = z.infer<typeof spanAnomalySchema>;
+/** Aggregated anomaly counts for a session or time window. */
+export declare const anomalySummarySchema: z.ZodObject<{
+    sessionId: z.ZodOptional<z.ZodString>;
+    analyzedAt: z.ZodISODateTime;
+    totalSpans: z.ZodNumber;
+    anomalousSpans: z.ZodNumber;
+    excludedSpans: z.ZodNumber;
+    criticalCount: z.ZodNumber;
+    errorCount: z.ZodNumber;
+    warnCount: z.ZodNumber;
+    signalCounts: z.ZodRecord<z.ZodEnum<{
+        input_tokens: "input_tokens";
+        output_tokens: "output_tokens";
+        duration: "duration";
+        error_status: "error_status";
+        unknown_span_name: "unknown_span_name";
+        span_count: "span_count";
+    }>, z.ZodNumber>;
+}, z.core.$strip>;
+export type AnomalySummary = z.infer<typeof anomalySummarySchema>;
+/**
+ * Span name prefixes that identify each category.
+ * First matching prefix wins; falls back to 'unknown'.
+ */
+export declare const SPAN_CATEGORY_PREFIXES: Record<SpanCategory, readonly string[]>;
+/**
+ * Duration thresholds per category.
+ *
+ * Hook baseline: median 1.44ms, p95 4.78ms.
+ * Warn = 10× p95 baseline; critical = 40× p95 baseline.
+ * Agent/tool/mcp are intentionally lenient (long-running operations expected).
+ */
+export declare const DEFAULT_DURATION_THRESHOLDS: Record<SpanCategory, DurationThresholds>;
+/**
+ * Token anomaly thresholds.
+ * Derived from 2026-04-06 session data (sparse coverage, ~2% of spans).
+ */
+export declare const DEFAULT_TOKEN_THRESHOLDS: TokenAnomalyThresholds;
+/**
+ * Span names excluded from error_status anomaly signal.
+ *
+ * hook:tsc-check always fails with "require is not defined" in ESM context.
+ * This is a permanent instrumentation false positive, not a real error.
+ */
+export declare const ERROR_STATUS_EXCLUSIONS: Set<string>;
+/**
+ * Maximum expected spans per trace in current telemetry.
+ * Data shows all traces are single-span. Flag if exceeded.
+ */
+export declare const MAX_SPANS_PER_TRACE = 1;
+//# sourceMappingURL=trace-anomaly-schemas.d.ts.map

package/dist/lib/observability/trace-anomaly-schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-anomaly-schemas.d.ts","sourceRoot":"","sources":["../../../src/lib/observability/trace-anomaly-schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAOxB;;;GAGG;AACH,eAAO,MAAM,kBAAkB;;;;;;EAAsD,CAAC;AACtF,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D,0EAA0E;AAC1E,eAAO,MAAM,qBAAqB;;;;;EAAgD,CAAC;AACnF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE;;;GAGG;AACH,eAAO,MAAM,mBAAmB;;;;;;;EAO9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAMhE,4DAA4D;AAC5D,eAAO,MAAM,wBAAwB;;;iBAKmC,CAAC;AAEzE,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E,+CAA+C;AAC/C,eAAO,MAAM,4BAA4B;;;;;iBASvC,CAAC;AAEH,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAMlF,uEAAuE;AACvE,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;iBAS9B,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,iEAAiE;AACjE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAW5B,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D,8DAA8D;AAC9D,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;iBAW/B,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAMlE;;;GAGG;AACH,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAM1E,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,EAAE,MAAM,CAAC,YAAY,EAAE,kBAAkB,CAMhF,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,wBAAwB,EAAE,sBAKtC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,aAElC,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,mBAAmB,IAAI,CAAC"}

package/dist/lib/observability/trace-anomaly-schemas.js

@@ -0,0 +1,167 @@
+/**
+ * Zod schemas for per-span anomaly detection (INV-2).
+ *
+ * ## Data-grounded design (2026-04-06)
+ *
+ * Analysis of 23,448 spans across 3 real sessions revealed:
+ * - All traces are single-span (each hook invocation = 1 span, no parent-child)
+ * - 21 distinct span names; hook:builtin-pre/post-tool is 77% of volume
+ * - Median duration: 1.44ms; p95: 4.78ms; warn at >50ms, critical at >200ms
+ * - Token data is sparse (~2% coverage): input p95=17K, output p95=28K
+ * - 5.6% error rate from hook:tsc-check only ("require is not defined" — known false positive)
+ *
+ * ## OTel spec grounding
+ *
+ * No OTel semconv defines span count, nesting, or complexity limits.
+ * Anomaly signals are anchored to:
+ * - gen_ai.usage.input_tokens / gen_ai.usage.output_tokens (Development stability)
+ * - span.status.code (UNSET=0, OK=1, ERROR=2)
+ * - Duration derived from startTime/endTime HrTime tuples
+ *
+ * ## Recommendation for OTEL2 implementation
+ *
+ * - Use per-span-name thresholds (21 known names; table-driven)
+ * - Primary signals: duration, error_status, input_tokens, output_tokens
+ * - Nesting depth: NOT applicable (data always single-span)
+ * - Span count per trace: flag if >2 (instrumentation loop indicator)
+ * - Unknown span names: flag as anomaly (instrumentation drift indicator)
+ * - Exclude hook:tsc-check from error_status signal (permanent false positive)
+ */
+import { z } from 'zod';
+import { SessionIdSchema, SpanIdSchema, TraceIdSchema } from '../core/shared-schemas.js';
+// ============================================================================
+// Enums
+// ============================================================================
+/**
+ * Span category derived from span name prefix.
+ * Used to select the correct duration threshold table.
+ */
+export const spanCategorySchema = z.enum(['hook', 'agent', 'tool', 'mcp', 'unknown']);
+/** Four-level severity mirroring OpenTelemetry log severity groupings. */
+export const anomalySeveritySchema = z.enum(['none', 'warn', 'error', 'critical']);
+/**
+ * Signal types detectable without cross-span correlation.
+ * All signals are derivable from a single ExportedSpan object.
+ */
+export const anomalySignalSchema = z.enum([
+    'duration', // span took longer than per-category threshold
+    'error_status', // span.status.code === 2 (ERROR)
+    'input_tokens', // gen_ai.usage.input_tokens exceeded threshold
+    'output_tokens', // gen_ai.usage.output_tokens exceeded threshold
+    'unknown_span_name', // name not in known-names set (instrumentation drift)
+    'span_count', // >1 span per trace (instrumentation loop)
+]);
+// ============================================================================
+// Threshold schemas (configuration layer)
+// ============================================================================
+/** Duration thresholds per span category (milliseconds). */
+export const durationThresholdsSchema = z.object({
+    /** Warn if duration exceeds this. Data-derived: hook p95 ≈ 5ms → warn at 10× (50ms). */
+    warnMs: z.number().nonnegative(),
+    /** Critical if duration exceeds this. */
+    criticalMs: z.number().nonnegative(),
+}).refine(t => t.criticalMs > t.warnMs, 'criticalMs must exceed warnMs');
+/** Token anomaly thresholds (token counts). */
+export const tokenAnomalyThresholdsSchema = z.object({
+    /** Warn on input_tokens ≥ this. Data-derived: p95 = 17K. */
+    inputWarnTokens: z.number().nonnegative(),
+    /** Critical on input_tokens ≥ this. Data-derived: p99 ≈ 25K. */
+    inputCriticalTokens: z.number().nonnegative(),
+    /** Warn on output_tokens ≥ this. Data-derived: p95 = 28K. */
+    outputWarnTokens: z.number().nonnegative(),
+    /** Critical on output_tokens ≥ this. Data-derived: p99 ≈ 55K. */
+    outputCriticalTokens: z.number().nonnegative(),
+});
+// ============================================================================
+// Detection result schemas
+// ============================================================================
+/** A single fired anomaly signal with observed vs threshold values. */
+export const signalAnomalySchema = z.object({
+    signal: anomalySignalSchema,
+    severity: anomalySeveritySchema,
+    /** Numeric observed value (ms for duration, token count for tokens). */
+    observed: z.number().optional(),
+    /** Threshold that was exceeded. */
+    threshold: z.number().optional(),
+    /** Human-readable detail for console output. */
+    detail: z.string().optional(),
+});
+/** Per-span anomaly assessment. One record per analyzed span. */
+export const spanAnomalySchema = z.object({
+    spanId: SpanIdSchema,
+    traceId: TraceIdSchema,
+    spanName: z.string().min(1),
+    category: spanCategorySchema,
+    /** Highest severity across all fired signals. */
+    overallSeverity: anomalySeveritySchema,
+    /** All fired signals, ordered by severity descending. */
+    signals: z.array(signalAnomalySchema),
+    /** True if this span matched the known false-positive exclude list. */
+    excluded: z.boolean(),
+});
+/** Aggregated anomaly counts for a session or time window. */
+export const anomalySummarySchema = z.object({
+    sessionId: SessionIdSchema.optional(),
+    analyzedAt: z.iso.datetime(),
+    totalSpans: z.number().nonnegative(),
+    anomalousSpans: z.number().nonnegative(),
+    excludedSpans: z.number().nonnegative(),
+    criticalCount: z.number().nonnegative(),
+    errorCount: z.number().nonnegative(),
+    warnCount: z.number().nonnegative(),
+    /** Per-signal fire counts (for surfacing top anomaly types). */
+    signalCounts: z.record(anomalySignalSchema, z.number().nonnegative()),
+});
+// ============================================================================
+// Data-grounded defaults (derived from 2026-04-06 analysis)
+// ============================================================================
+/**
+ * Span name prefixes that identify each category.
+ * First matching prefix wins; falls back to 'unknown'.
+ */
+export const SPAN_CATEGORY_PREFIXES = {
+    hook: ['hook:'],
+    agent: ['agent:', 'gen_ai.agent', 'invoke_agent'],
+    tool: ['tool:', 'execute_tool'],
+    mcp: ['mcp:'],
+    unknown: [],
+};
+/**
+ * Duration thresholds per category.
+ *
+ * Hook baseline: median 1.44ms, p95 4.78ms.
+ * Warn = 10× p95 baseline; critical = 40× p95 baseline.
+ * Agent/tool/mcp are intentionally lenient (long-running operations expected).
+ */
+export const DEFAULT_DURATION_THRESHOLDS = {
+    hook: { warnMs: 50, criticalMs: 200 },
+    agent: { warnMs: 5_000, criticalMs: 30_000 },
+    tool: { warnMs: 500, criticalMs: 5_000 },
+    mcp: { warnMs: 1_000, criticalMs: 10_000 },
+    unknown: { warnMs: 50, criticalMs: 200 },
+};
+/**
+ * Token anomaly thresholds.
+ * Derived from 2026-04-06 session data (sparse coverage, ~2% of spans).
+ */
+export const DEFAULT_TOKEN_THRESHOLDS = {
+    inputWarnTokens: 17_000,
+    inputCriticalTokens: 25_000,
+    outputWarnTokens: 28_000,
+    outputCriticalTokens: 55_000,
+};
+/**
+ * Span names excluded from error_status anomaly signal.
+ *
+ * hook:tsc-check always fails with "require is not defined" in ESM context.
+ * This is a permanent instrumentation false positive, not a real error.
+ */
+export const ERROR_STATUS_EXCLUSIONS = new Set([
+    'hook:tsc-check',
+]);
+/**
+ * Maximum expected spans per trace in current telemetry.
+ * Data shows all traces are single-span. Flag if exceeded.
+ */
+export const MAX_SPANS_PER_TRACE = 1;
+//# sourceMappingURL=trace-anomaly-schemas.js.map

package/dist/lib/observability/trace-anomaly-schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-anomaly-schemas.js","sourceRoot":"","sources":["../../../src/lib/observability/trace-anomaly-schemas.ts"],"names":[],"mappings":"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"}

package/dist/lib/privacy/content-redaction.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Content Redaction for LLM Observability Telemetry (R10)
+ *
+ * Tier 1 (irreversible) regex-based PII redaction for span attributes and log event bodies
+ * before export. Designed for pre-export hook in the OTel SDK span processor.
+ *
+ * Architecture:
+ * - Attribute redaction: allowlist/blocklist on structured key-value span attributes
+ * - Body redaction: pattern-based replacement on free-text log event body content
+ * - Customizable via RedactionConfig: override patterns, add custom rules, disable categories
+ *
+ * @see docs/roadmap/r10-content-redaction-pipelines.md
+ */
+/** Placeholder used for irreversible redaction (Tier 1) */
+export declare const REDACTION_PLACEHOLDER = "[REDACTED]";
+/** Appended when input was truncated before redaction — signals incomplete sanitization */
+export declare const REDACTION_TRUNCATION_SENTINEL = "[TRUNCATED\u2014REDACTION INCOMPLETE]";
+/** Category-specific placeholders for human-readable audit trails */
+export declare const REDACTION_PLACEHOLDERS: {
+    readonly email: "[EMAIL]";
+    readonly phone: "[PHONE]";
+    readonly ssn: "[SSN]";
+    readonly creditCard: "[CREDIT_CARD]";
+    readonly ipAddress: "[IP_ADDRESS]";
+    readonly apiKey: "[API_KEY]";
+    readonly generic: "[REDACTED]";
+};
+export type RedactionCategory = keyof typeof REDACTION_PLACEHOLDERS;
+/**
+ * Span attribute keys that contain LLM prompt/completion content.
+ * These keys are blocked by default when attribute-level redaction is enabled.
+ */
+export declare const GENAI_CONTENT_ATTRIBUTE_KEYS: ReadonlySet<string>;
+/**
+ * Span attribute keys that are safe to pass through without redaction.
+ * Structural/metadata attributes that contain no user content.
+ *
+ * Reviewed against OTel GenAI semantic conventions v1.29.0.
+ * Re-audit this set on semconv upgrade — some keys (e.g. gen_ai.system) may
+ * carry user-supplied content in certain instrumentation libraries.
+ *
+ * @see https://opentelemetry.io/docs/specs/semconv/gen-ai/ (v1.29.0)
+ */
+export declare const GENAI_SAFE_ATTRIBUTE_KEYS: ReadonlySet<string>;
+/** A single custom redaction rule */
+export interface RedactionRule {
+    /** Unique identifier for this rule (used in audit logs) */
+    id: string;
+    /** Regex to match; must have the `g` flag for global replacement */
+    pattern: RegExp;
+    /** Replacement string (default: REDACTION_PLACEHOLDER) */
+    placeholder?: string;
+}
+export interface RedactionConfig {
+    /**
+     * Categories to disable from the built-in pattern set.
+     * When omitted, all built-in categories are active.
+     */
+    disabledCategories?: RedactionCategory[];
+    /**
+     * Additional custom redaction rules applied after built-in patterns.
+     * Rules are applied in order.
+     */
+    customRules?: RedactionRule[];
+    /**
+     * When true, redact the value of any span attribute key in GENAI_CONTENT_ATTRIBUTE_KEYS.
+     * Default: false (attributes are passed through; only body redaction is applied).
+     */
+    redactContentAttributes?: boolean;
+    /**
+     * When true, skip all built-in patterns and only apply customRules.
+     * Useful for callers that want full control over redaction behavior.
+     */
+    disableBuiltins?: boolean;
+}
+/**
+ * Redact PII from a free-text string using the configured pattern set.
+ *
+ * - Input is truncated at MAX_SANITIZE_LENGTH before regex processing (ReDoS guard).
+ * - Returns the original value unchanged if it is not a string.
+ * - Patterns are applied sequentially; each uses a freshly reset lastIndex.
+ *
+ * @param text - Input text to redact
+ * @param config - Redaction configuration
+ * @returns Redacted text with PII replaced by placeholders
+ */
+export declare function redactText(text: string, config?: RedactionConfig): string;
+/**
+ * Redact PII from a span attribute value.
+ *
+ * - If the key is in GENAI_CONTENT_ATTRIBUTE_KEYS and redactContentAttributes is enabled,
+ *   the value is replaced wholesale with REDACTION_PLACEHOLDER.
+ * - Otherwise, applies text redaction to string values.
+ * - Non-string attribute values (numbers, booleans, arrays) pass through unchanged.
+ *
+ * @param key - Span attribute key
+ * @param value - Span attribute value
+ * @param config - Redaction configuration
+ * @returns Redacted attribute value
+ */
+export declare function redactAttributeValue(key: string, value: unknown, config?: RedactionConfig): unknown;
+/**
+ * Redact PII from all attributes in a span attribute map.
+ *
+ * Returns a new object — does not mutate the input.
+ *
+ * @param attributes - Span attribute map (key → value)
+ * @param config - Redaction configuration
+ * @returns New attribute map with PII redacted
+ */
+export declare function redactAttributes(attributes: Record<string, unknown>, config?: RedactionConfig): Record<string, unknown>;
+/**
+ * Minimal shape of an OTel span as used within this toolkit.
+ * Only fields relevant to redaction are required.
+ */
+export interface RedactableSpan {
+    attributes?: Record<string, unknown>;
+    /** Optional free-text body (log events, custom spans) */
+    body?: string;
+    /** Other span fields pass through unchanged */
+    [key: string]: unknown;
+}
+/**
+ * Redact PII from a single span (attributes + body).
+ *
+ * Returns a new object — does not mutate the input.
+ *
+ * @param span - Span to redact
+ * @param config - Redaction configuration
+ * @returns New span with PII redacted from attributes and body
+ */
+export declare function redactSpan(span: RedactableSpan, config?: RedactionConfig): RedactableSpan;
+/**
+ * Redact PII from an array of spans in one pass.
+ *
+ * @param spans - Array of spans to redact
+ * @param config - Redaction configuration
+ * @returns New array of spans with PII redacted
+ */
+export declare function redactSpans(spans: RedactableSpan[], config?: RedactionConfig): RedactableSpan[];
+//# sourceMappingURL=content-redaction.d.ts.map

package/dist/lib/privacy/content-redaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-redaction.d.ts","sourceRoot":"","sources":["../../../src/lib/privacy/content-redaction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAQH,2DAA2D;AAC3D,eAAO,MAAM,qBAAqB,eAAe,CAAC;AAElD,2FAA2F;AAC3F,eAAO,MAAM,6BAA6B,0CAAqC,CAAC;AAEhF,qEAAqE;AACrE,eAAO,MAAM,sBAAsB;;;;;;;;CAQzB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,MAAM,OAAO,sBAAsB,CAAC;AAEpE;;;GAGG;AACH,eAAO,MAAM,4BAA4B,EAAE,WAAW,CAAC,MAAM,CAO3D,CAAC;AAEH;;;;;;;;;GASG;AACH,eAAO,MAAM,yBAAyB,EAAE,WAAW,CAAC,MAAM,CAQxD,CAAC;AA0CH,qCAAqC;AACrC,MAAM,WAAW,aAAa;IAC5B,2DAA2D;IAC3D,EAAE,EAAE,MAAM,CAAC;IACX,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,kBAAkB,CAAC,EAAE,iBAAiB,EAAE,CAAC;IACzC;;;OAGG;IACH,WAAW,CAAC,EAAE,aAAa,EAAE,CAAC;IAC9B;;;OAGG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAmCD;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,GAAE,eAAoB,GAAG,MAAM,CAe7E;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,OAAO,EACd,MAAM,GAAE,eAAoB,GAC3B,OAAO,CAUT;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,MAAM,GAAE,eAAoB,GAC3B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAMzB;AAMD;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,yDAAyD;IACzD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,cAAc,EAAE,MAAM,GAAE,eAAoB,GAAG,cAAc,CAY7F;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,cAAc,EAAE,EAAE,MAAM,GAAE,eAAoB,GAAG,cAAc,EAAE,CAEnG"}