@superblocksteam/telemetry 2.0.83-next.1

package/dist-esm/node/exporters/resilient-exporter.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Resilient Exporter
+ *
+ * Wrapper that ensures Tier 2/3 export failures never block core request paths.
+ * Export failures are observable via metrics, not via blocking or exceptions.
+ */
+import type { SpanExporter, ReadableSpan } from "@opentelemetry/sdk-trace-base";
+import { ExportResult } from "@opentelemetry/core";
+/**
+ * Configuration for the resilient exporter.
+ */
+export interface ResilientExporterConfig {
+    /** Underlying exporter to wrap */
+    delegate: SpanExporter;
+    /** Max items to buffer before dropping (default: 2048) */
+    maxQueueSize?: number;
+    /** Export timeout in ms (default: 30000) */
+    exportTimeoutMs?: number;
+    /** Callback when items are dropped due to backpressure */
+    onDrop?: (count: number, reason: "queue_full" | "export_failed" | "timeout") => void;
+}
+/**
+ * Metrics exposed by the resilient exporter.
+ */
+export interface ResilientExporterMetrics {
+    /** Total spans dropped due to backpressure or failure */
+    dropped: number;
+    /** Current queue size */
+    queued: number;
+    /** Total export failures */
+    failures: number;
+}
+/**
+ * Resilient exporter wrapper that:
+ * - Drops spans when queue is full (never blocks)
+ * - Catches export failures and emits metrics
+ * - Times out stalled exports
+ *
+ * CRITICAL: Telemetry export must be fire-and-forget from the application's perspective.
+ * Export failures should be observable via metrics, not via blocking or exceptions.
+ */
+export declare class ResilientExporter implements SpanExporter {
+    private readonly delegate;
+    private readonly maxQueueSize;
+    private readonly exportTimeoutMs;
+    private readonly onDrop;
+    private queuedCount;
+    private droppedCount;
+    private exportFailures;
+    private shuttingDown;
+    constructor(config: ResilientExporterConfig);
+    /**
+     * Export spans with resilient error handling.
+     *
+     * IMPORTANT: Always returns SUCCESS to caller - export failures are
+     * observable via metrics, not via the result callback.
+     */
+    export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void;
+    /**
+     * Shutdown the underlying exporter.
+     * Marks exporter as shutting down to reject new exports.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Force flush the underlying exporter.
+     */
+    forceFlush(): Promise<void>;
+    /**
+     * Get current metrics for observability.
+     */
+    getMetrics(): ResilientExporterMetrics;
+    /**
+     * Reset metrics (for testing).
+     */
+    resetMetrics(): void;
+}
+//# sourceMappingURL=resilient-exporter.d.ts.map

package/dist-esm/node/exporters/resilient-exporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resilient-exporter.d.ts","sourceRoot":"","sources":["../../../src/node/exporters/resilient-exporter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAChF,OAAO,EAAE,YAAY,EAAoB,MAAM,qBAAqB,CAAC;AAErE;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,kCAAkC;IAClC,QAAQ,EAAE,YAAY,CAAC;IACvB,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,4CAA4C;IAC5C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,0DAA0D;IAC1D,MAAM,CAAC,EAAE,CACP,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,YAAY,GAAG,eAAe,GAAG,SAAS,KAC/C,IAAI,CAAC;CACX;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB,yBAAyB;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,4BAA4B;IAC5B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;GAQG;AACH,qBAAa,iBAAkB,YAAW,YAAY;IACpD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAe;IACxC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAGb;IAEV,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,YAAY,CAAS;gBAEjB,MAAM,EAAE,uBAAuB;IAO3C;;;;;OAKG;IACH,MAAM,CACJ,KAAK,EAAE,YAAY,EAAE,EACrB,cAAc,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,GAC7C,IAAI;IA0DP;;;OAGG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAK/B;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAIjC;;OAEG;IACH,UAAU,IAAI,wBAAwB;IAQtC;;OAEG;IACH,YAAY,IAAI,IAAI;CAIrB"}

package/dist-esm/node/exporters/resilient-exporter.js

@@ -0,0 +1,125 @@
+/**
+ * Resilient Exporter
+ *
+ * Wrapper that ensures Tier 2/3 export failures never block core request paths.
+ * Export failures are observable via metrics, not via blocking or exceptions.
+ */
+import { ExportResultCode } from "@opentelemetry/core";
+/**
+ * Resilient exporter wrapper that:
+ * - Drops spans when queue is full (never blocks)
+ * - Catches export failures and emits metrics
+ * - Times out stalled exports
+ *
+ * CRITICAL: Telemetry export must be fire-and-forget from the application's perspective.
+ * Export failures should be observable via metrics, not via blocking or exceptions.
+ */
+export class ResilientExporter {
+    delegate;
+    maxQueueSize;
+    exportTimeoutMs;
+    onDrop;
+    queuedCount = 0;
+    droppedCount = 0;
+    exportFailures = 0;
+    shuttingDown = false;
+    constructor(config) {
+        this.delegate = config.delegate;
+        this.maxQueueSize = config.maxQueueSize ?? 2048;
+        this.exportTimeoutMs = config.exportTimeoutMs ?? 30000;
+        this.onDrop = config.onDrop ?? (() => { });
+    }
+    /**
+     * Export spans with resilient error handling.
+     *
+     * IMPORTANT: Always returns SUCCESS to caller - export failures are
+     * observable via metrics, not via the result callback.
+     */
+    export(spans, resultCallback) {
+        // Don't accept new exports during shutdown
+        if (this.shuttingDown) {
+            resultCallback({ code: ExportResultCode.SUCCESS });
+            return;
+        }
+        // Check backpressure - drop if queue is full
+        if (this.queuedCount + spans.length > this.maxQueueSize) {
+            this.droppedCount += spans.length;
+            this.onDrop(spans.length, "queue_full");
+            // Still return success - don't block the caller
+            resultCallback({ code: ExportResultCode.SUCCESS });
+            return;
+        }
+        this.queuedCount += spans.length;
+        let completed = false;
+        // Wrap with timeout
+        const timeoutId = setTimeout(() => {
+            if (completed)
+                return;
+            completed = true;
+            this.queuedCount -= spans.length;
+            this.droppedCount += spans.length;
+            this.onDrop(spans.length, "timeout");
+            resultCallback({ code: ExportResultCode.SUCCESS }); // Don't propagate failure
+        }, this.exportTimeoutMs);
+        try {
+            this.delegate.export(spans, (result) => {
+                if (completed)
+                    return;
+                completed = true;
+                clearTimeout(timeoutId);
+                this.queuedCount -= spans.length;
+                if (result.code !== ExportResultCode.SUCCESS) {
+                    this.exportFailures++;
+                    this.droppedCount += spans.length;
+                    this.onDrop(spans.length, "export_failed");
+                }
+                // Always return success to caller - export failures are observable via metrics
+                resultCallback({ code: ExportResultCode.SUCCESS });
+            });
+        }
+        catch (error) {
+            if (completed)
+                return;
+            completed = true;
+            clearTimeout(timeoutId);
+            this.queuedCount -= spans.length;
+            this.exportFailures++;
+            this.droppedCount += spans.length;
+            this.onDrop(spans.length, "export_failed");
+            console.warn("[Telemetry] Span export threw:", error);
+            resultCallback({ code: ExportResultCode.SUCCESS }); // Don't propagate failure
+        }
+    }
+    /**
+     * Shutdown the underlying exporter.
+     * Marks exporter as shutting down to reject new exports.
+     */
+    async shutdown() {
+        this.shuttingDown = true;
+        return this.delegate.shutdown();
+    }
+    /**
+     * Force flush the underlying exporter.
+     */
+    async forceFlush() {
+        return this.delegate.forceFlush?.() ?? Promise.resolve();
+    }
+    /**
+     * Get current metrics for observability.
+     */
+    getMetrics() {
+        return {
+            dropped: this.droppedCount,
+            queued: this.queuedCount,
+            failures: this.exportFailures,
+        };
+    }
+    /**
+     * Reset metrics (for testing).
+     */
+    resetMetrics() {
+        this.droppedCount = 0;
+        this.exportFailures = 0;
+    }
+}
+//# sourceMappingURL=resilient-exporter.js.map

package/dist-esm/node/exporters/resilient-exporter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resilient-exporter.js","sourceRoot":"","sources":["../../../src/node/exporters/resilient-exporter.ts"],"names":[],"mappings":"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"}

package/dist-esm/node/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Node.js Telemetry Bootstrap
+ *
+ * This is the ONLY approved way to initialize telemetry in Node.js services.
+ */
+export { initNodeTelemetry, getTelemetryInstance, isTelemetryInitialized, resetTelemetry, type NodeTelemetryInstance, } from "./init.js";
+export { MetricsClient, type Labels, type CounterHandle, type GaugeHandle, type HistogramHandle, } from "./metrics-client.js";
+export { TracedSocket, type TracedSocketConfig, type TracedSocketOptions, } from "./traced-socket.js";
+export { ResilientExporter, type ResilientExporterConfig, type ResilientExporterMetrics, } from "./exporters/resilient-exporter.js";
+export { PolicyAwareLogProcessor, LogExportMode, getLoggingPolicy, type LoggingPolicyConfig, } from "./log-processor.js";
+//# sourceMappingURL=index.d.ts.map

package/dist-esm/node/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/node/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,sBAAsB,EACtB,cAAc,EACd,KAAK,qBAAqB,GAC3B,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,aAAa,EACb,KAAK,MAAM,EACX,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,eAAe,GACrB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,YAAY,EACZ,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,GACzB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,iBAAiB,EACjB,KAAK,uBAAuB,EAC5B,KAAK,wBAAwB,GAC9B,MAAM,mCAAmC,CAAC;AAE3C,OAAO,EACL,uBAAuB,EACvB,aAAa,EACb,gBAAgB,EAChB,KAAK,mBAAmB,GACzB,MAAM,oBAAoB,CAAC"}

package/dist-esm/node/index.js

@@ -0,0 +1,11 @@
+/**
+ * Node.js Telemetry Bootstrap
+ *
+ * This is the ONLY approved way to initialize telemetry in Node.js services.
+ */
+export { initNodeTelemetry, getTelemetryInstance, isTelemetryInitialized, resetTelemetry, } from "./init.js";
+export { MetricsClient, } from "./metrics-client.js";
+export { TracedSocket, } from "./traced-socket.js";
+export { ResilientExporter, } from "./exporters/resilient-exporter.js";
+export { PolicyAwareLogProcessor, LogExportMode, getLoggingPolicy, } from "./log-processor.js";
+//# sourceMappingURL=index.js.map

package/dist-esm/node/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/node/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,sBAAsB,EACtB,cAAc,GAEf,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,aAAa,GAKd,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,YAAY,GAGb,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,iBAAiB,GAGlB,MAAM,mCAAmC,CAAC;AAE3C,OAAO,EACL,uBAAuB,EACvB,aAAa,EACb,gBAAgB,GAEjB,MAAM,oBAAoB,CAAC"}

package/dist-esm/node/init.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Node.js Telemetry Bootstrap
+ *
+ * This is the ONLY approved way to initialize telemetry in Node.js services.
+ * Direct NodeSDK usage outside this package is prohibited.
+ */
+import { Tracer, Meter } from "@opentelemetry/api";
+import { Logger } from "@opentelemetry/api-logs";
+import { NodeSDK } from "@opentelemetry/sdk-node";
+import { TelemetryPolicyEvaluator } from "../common/policy-evaluator.js";
+import type { NodeTelemetryConfig } from "../types/index.js";
+import { TelemetryPolicy } from "../types/policy.js";
+import { MetricsClient } from "./metrics-client.js";
+/**
+ * Telemetry instance returned by initNodeTelemetry.
+ */
+export interface NodeTelemetryInstance {
+    /** The underlying NodeSDK instance (undefined in CI/no-op mode) */
+    sdk?: NodeSDK;
+    /** Policy evaluator for runtime decisions */
+    policyEvaluator: TelemetryPolicyEvaluator;
+    /** Get a tracer for the service */
+    getTracer: (name?: string) => Tracer;
+    /** Get a meter for the service */
+    getMeter: (name?: string) => Meter;
+    /** Get a logger for the service */
+    getLogger: (name?: string) => Logger;
+    /** Metrics client for recording counters, gauges, and histograms */
+    metricsClient: MetricsClient;
+    /** Graceful shutdown */
+    shutdown: () => Promise<void>;
+}
+/**
+ * Initialize Node.js telemetry with policy enforcement.
+ *
+ * This is the ONLY approved way to initialize telemetry in Node.js services.
+ * Direct NodeSDK usage outside this package is prohibited.
+ *
+ * @param config - Service configuration
+ * @param policy - Telemetry policy (REQUIRED)
+ * @returns Telemetry instance with SDK and utilities
+ *
+ * @example
+ * ```typescript
+ * import { initNodeTelemetry } from '@superblocksteam/telemetry/node';
+ * import { getDefaultPolicy, DeploymentType } from '@superblocksteam/shared';
+ *
+ * const policy = getDefaultPolicy(DeploymentType.CLOUD_PREM);
+ * const telemetry = initNodeTelemetry({
+ *   serviceName: 'my-service',
+ *   serviceVersion: '1.0.0',
+ *   environment: 'production',
+ *   otlpUrl: 'http://localhost:4318',
+ * }, policy);
+ *
+ * const tracer = telemetry.getTracer();
+ * ```
+ */
+export declare function initNodeTelemetry(config: NodeTelemetryConfig, policy: TelemetryPolicy): NodeTelemetryInstance;
+/**
+ * Get the current telemetry instance.
+ *
+ * @throws Error if not initialized
+ */
+export declare function getTelemetryInstance(): NodeTelemetryInstance;
+/**
+ * Check if telemetry is initialized.
+ */
+export declare function isTelemetryInitialized(): boolean;
+/**
+ * Reset telemetry (for testing only).
+ * @internal
+ */
+export declare function resetTelemetry(): void;
+//# sourceMappingURL=init.d.ts.map

package/dist-esm/node/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/node/init.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAS,MAAM,EAAW,KAAK,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,EAAQ,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAWvD,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAIlD,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AACzE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAiB,MAAM,oBAAoB,CAAC;AAOpE,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,mEAAmE;IACnE,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,6CAA6C;IAC7C,eAAe,EAAE,wBAAwB,CAAC;IAC1C,mCAAmC;IACnC,SAAS,EAAE,CAAC,IAAI,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IACrC,kCAAkC;IAClC,QAAQ,EAAE,CAAC,IAAI,CAAC,EAAE,MAAM,KAAK,KAAK,CAAC;IACnC,mCAAmC;IACnC,SAAS,EAAE,CAAC,IAAI,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IACrC,oEAAoE;IACpE,aAAa,EAAE,aAAa,CAAC;IAC7B,wBAAwB;IACxB,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B;AA0ED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,mBAAmB,EAC3B,MAAM,EAAE,eAAe,GACtB,qBAAqB,CAkJvB;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,qBAAqB,CAO5D;AAED;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,OAAO,CAEhD;AAED;;;GAGG;AACH,wBAAgB,cAAc,IAAI,IAAI,CAErC"}

package/dist-esm/node/init.js

@@ -0,0 +1,239 @@
+/**
+ * Node.js Telemetry Bootstrap
+ *
+ * This is the ONLY approved way to initialize telemetry in Node.js services.
+ * Direct NodeSDK usage outside this package is prohibited.
+ */
+import { trace, metrics } from "@opentelemetry/api";
+import { logs } from "@opentelemetry/api-logs";
+import { AsyncLocalStorageContextManager } from "@opentelemetry/context-async-hooks";
+import { W3CTraceContextPropagator } from "@opentelemetry/core";
+import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-http";
+import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { BatchLogRecordProcessor } from "@opentelemetry/sdk-logs";
+import { AggregationTemporality, PeriodicExportingMetricReader, } from "@opentelemetry/sdk-metrics";
+import { NodeSDK } from "@opentelemetry/sdk-node";
+import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { buildResource, validateResource } from "../common/resource.js";
+import { TelemetryPolicyEvaluator } from "../common/policy-evaluator.js";
+import { TelemetryTier } from "../types/policy.js";
+import { ResilientExporter } from "./exporters/resilient-exporter.js";
+import { PolicyAwareLogProcessor, getLoggingPolicy, LogExportMode, } from "./log-processor.js";
+import { MetricsClient } from "./metrics-client.js";
+// Singleton instance
+let instance;
+/**
+ * Create a no-op telemetry instance for CI environments.
+ *
+ * IMPORTANT: We intentionally do NOT use NodeSDK here. NodeSDK.start()
+ * auto-configures OTLP exporters for traces, metrics, and logs from
+ * environment defaults (localhost:4318). During shutdown, these exporters
+ * try to flush to the non-existent collector, causing ECONNREFUSED errors
+ * that fail test suites even when all tests pass.
+ *
+ * Instead, we return a lightweight instance that uses the global OTel API
+ * (which returns no-op tracers/meters/loggers when no provider is registered).
+ */
+function createNoOpInstance(config, policy) {
+    const policyEvaluator = new TelemetryPolicyEvaluator(policy);
+    // Use a no-op meter for the metrics client
+    const defaultMeter = metrics.getMeter(config.serviceName, config.serviceVersion);
+    return {
+        sdk: undefined,
+        policyEvaluator,
+        getTracer: (name) => trace.getTracer(name ?? config.serviceName, config.serviceVersion),
+        getMeter: (name) => metrics.getMeter(name ?? config.serviceName, config.serviceVersion),
+        getLogger: (name) => logs.getLogger(name ?? config.serviceName, config.serviceVersion),
+        metricsClient: new MetricsClient(defaultMeter),
+        shutdown: async () => {
+            // No-op: nothing to flush or shut down
+        },
+    };
+}
+/**
+ * Validate telemetry configuration.
+ *
+ * @param config - Configuration to validate
+ * @throws Error if configuration is invalid
+ */
+function validateNodeTelemetryConfig(config) {
+    if (!config.serviceName?.trim()) {
+        throw new Error("[Telemetry] serviceName is required and cannot be empty");
+    }
+    if (!config.serviceVersion?.trim()) {
+        throw new Error("[Telemetry] serviceVersion is required and cannot be empty");
+    }
+    if (!config.environment?.trim()) {
+        throw new Error("[Telemetry] environment is required and cannot be empty");
+    }
+    if (config.otlpUrl) {
+        try {
+            new URL(config.otlpUrl);
+        }
+        catch (error) {
+            throw new Error(`[Telemetry] Invalid otlpUrl: ${config.otlpUrl} (${error.message})`);
+        }
+    }
+}
+/**
+ * Initialize Node.js telemetry with policy enforcement.
+ *
+ * This is the ONLY approved way to initialize telemetry in Node.js services.
+ * Direct NodeSDK usage outside this package is prohibited.
+ *
+ * @param config - Service configuration
+ * @param policy - Telemetry policy (REQUIRED)
+ * @returns Telemetry instance with SDK and utilities
+ *
+ * @example
+ * ```typescript
+ * import { initNodeTelemetry } from '@superblocksteam/telemetry/node';
+ * import { getDefaultPolicy, DeploymentType } from '@superblocksteam/shared';
+ *
+ * const policy = getDefaultPolicy(DeploymentType.CLOUD_PREM);
+ * const telemetry = initNodeTelemetry({
+ *   serviceName: 'my-service',
+ *   serviceVersion: '1.0.0',
+ *   environment: 'production',
+ *   otlpUrl: 'http://localhost:4318',
+ * }, policy);
+ *
+ * const tracer = telemetry.getTracer();
+ * ```
+ */
+export function initNodeTelemetry(config, policy) {
+    // Policy is required
+    if (!policy) {
+        throw new Error("[Telemetry] Policy is required. Cannot initialize telemetry without a policy.");
+    }
+    // Validate config
+    validateNodeTelemetryConfig(config);
+    // Return existing instance if already initialized
+    if (instance) {
+        // Warn if config differs from existing
+        const existingPolicy = instance.policyEvaluator.getPolicy();
+        if (existingPolicy.deploymentType !== policy.deploymentType) {
+            console.warn(`[Telemetry] Already initialized with different deployment type ` +
+                `(existing: ${existingPolicy.deploymentType}, requested: ${policy.deploymentType}). ` +
+                `Returning existing instance.`);
+        }
+        return instance;
+    }
+    // CI environment detection - use no-op telemetry
+    if (process.env.CI === "true") {
+        console.debug("[Telemetry] CI environment detected, using no-op telemetry");
+        instance = createNoOpInstance(config, policy);
+        return instance;
+    }
+    const policyEvaluator = new TelemetryPolicyEvaluator(policy);
+    const resource = buildResource(config);
+    // Validate resource has required attributes
+    validateResource(resource);
+    // Track dropped spans for observability
+    let droppedSpans = 0;
+    const onDrop = (count, reason) => {
+        droppedSpans += count;
+        console.warn(`[Telemetry] Dropped ${count} spans (${reason}). Total dropped: ${droppedSpans}`);
+    };
+    // Create trace exporter if URL provided and Tier 2 export is enabled
+    // Use isExportEnabled (not canExport) - sampling applies at runtime, not initialization
+    let traceExporter;
+    if (config.otlpUrl &&
+        policyEvaluator.isExportEnabled(TelemetryTier.TIER_2_OPERATIONAL)) {
+        traceExporter = new ResilientExporter({
+            delegate: new OTLPTraceExporter({ url: `${config.otlpUrl}/v1/traces` }),
+            onDrop,
+        });
+    }
+    // Create metric exporter if enabled
+    // Use isExportEnabled (not canExport) - sampling applies at runtime, not initialization
+    let metricReader;
+    if (config.otlpUrl &&
+        config.metricsEnabled !== false &&
+        policyEvaluator.isExportEnabled(TelemetryTier.TIER_2_OPERATIONAL)) {
+        metricReader = new PeriodicExportingMetricReader({
+            exporter: new OTLPMetricExporter({
+                url: `${config.otlpUrl}/v1/metrics`,
+                temporalityPreference: AggregationTemporality.DELTA,
+            }),
+            exportIntervalMillis: 10000, // every 10 seconds
+        });
+    }
+    // Create log processor with policy-aware filtering and sanitization
+    // The PolicyAwareLogProcessor wraps the batch processor to:
+    // 1. Filter logs by severity level based on export mode (LOCAL_ONLY, ERRORS_ONLY, INFO_AND_ABOVE)
+    // 2. Sanitize log bodies and attributes to remove PII, file paths, stack traces
+    // 3. Remove forbidden fields that should never be exported
+    let logProcessor;
+    const loggingPolicy = getLoggingPolicy(policy);
+    if (config.otlpUrl &&
+        config.logsEnabled !== false &&
+        policyEvaluator.isExportEnabled(TelemetryTier.TIER_2_OPERATIONAL) &&
+        loggingPolicy.exportMode !== LogExportMode.LOCAL_ONLY) {
+        const batchProcessor = new BatchLogRecordProcessor(new OTLPLogExporter({ url: `${config.otlpUrl}/v1/logs` }));
+        logProcessor = new PolicyAwareLogProcessor(loggingPolicy, batchProcessor);
+    }
+    // Create the SDK
+    // Note: instrumentations typed as unknown[] for flexibility with various OTEL instrumentation packages
+    const sdk = new NodeSDK({
+        resource,
+        spanProcessor: traceExporter
+            ? new BatchSpanProcessor(traceExporter)
+            : undefined,
+        metricReader,
+        logRecordProcessor: logProcessor,
+        contextManager: new AsyncLocalStorageContextManager(),
+        textMapPropagator: new W3CTraceContextPropagator(),
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- OTEL instrumentation types vary
+        instrumentations: (config.instrumentations ?? []),
+    });
+    sdk.start();
+    console.info(`[Telemetry] Initialized for ${config.serviceName} (${policy.deploymentType})` +
+        ` | Traces: ${traceExporter ? "enabled" : "disabled"}` +
+        ` | Metrics: ${metricReader ? "enabled" : "disabled"}` +
+        ` | Logs: ${logProcessor ? "enabled" : "disabled"}`);
+    const defaultMeter = metrics.getMeter(config.serviceName, config.serviceVersion);
+    instance = {
+        sdk,
+        policyEvaluator,
+        getTracer: (name) => trace.getTracer(name ?? config.serviceName, config.serviceVersion),
+        getMeter: (name) => metrics.getMeter(name ?? config.serviceName, config.serviceVersion),
+        getLogger: (name) => logs.getLogger(name ?? config.serviceName, config.serviceVersion),
+        metricsClient: new MetricsClient(defaultMeter),
+        shutdown: async () => {
+            try {
+                await sdk.shutdown();
+            }
+            finally {
+                instance = undefined;
+            }
+        },
+    };
+    return instance;
+}
+/**
+ * Get the current telemetry instance.
+ *
+ * @throws Error if not initialized
+ */
+export function getTelemetryInstance() {
+    if (!instance) {
+        throw new Error("[Telemetry] Not initialized. Call initNodeTelemetry() first.");
+    }
+    return instance;
+}
+/**
+ * Check if telemetry is initialized.
+ */
+export function isTelemetryInitialized() {
+    return instance !== undefined;
+}
+/**
+ * Reset telemetry (for testing only).
+ * @internal
+ */
+export function resetTelemetry() {
+    instance = undefined;
+}
+//# sourceMappingURL=init.js.map

package/dist-esm/node/init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../../src/node/init.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,KAAK,EAAU,OAAO,EAAS,MAAM,oBAAoB,CAAC;AACnE,OAAO,EAAE,IAAI,EAAU,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,+BAA+B,EAAE,MAAM,oCAAoC,CAAC;AACrF,OAAO,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,wCAAwC,CAAC;AACzE,OAAO,EAAE,kBAAkB,EAAE,MAAM,2CAA2C,CAAC;AAC/E,OAAO,EAAE,iBAAiB,EAAE,MAAM,yCAAyC,CAAC;AAC5E,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,EACL,sBAAsB,EACtB,6BAA6B,GAC9B,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAClD,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAEnE,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACxE,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAEzE,OAAO,EAAmB,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AACtE,OAAO,EACL,uBAAuB,EACvB,gBAAgB,EAChB,aAAa,GACd,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAsBpD,qBAAqB;AACrB,IAAI,QAA2C,CAAC;AAEhD;;;;;;;;;;;GAWG;AACH,SAAS,kBAAkB,CACzB,MAA2B,EAC3B,MAAuB;IAEvB,MAAM,eAAe,GAAG,IAAI,wBAAwB,CAAC,MAAM,CAAC,CAAC;IAE7D,2CAA2C;IAC3C,MAAM,YAAY,GAAG,OAAO,CAAC,QAAQ,CACnC,MAAM,CAAC,WAAW,EAClB,MAAM,CAAC,cAAc,CACtB,CAAC;IAEF,OAAO;QACL,GAAG,EAAE,SAAS;QACd,eAAe;QACf,SAAS,EAAE,CAAC,IAAa,EAAE,EAAE,CAC3B,KAAK,CAAC,SAAS,CAAC,IAAI,IAAI,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,cAAc,CAAC;QACpE,QAAQ,EAAE,CAAC,IAAa,EAAE,EAAE,CAC1B,OAAO,CAAC,QAAQ,CAAC,IAAI,IAAI,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,cAAc,CAAC;QACrE,SAAS,EAAE,CAAC,IAAa,EAAE,EAAE,CAC3B,IAAI,CAAC,SAAS,CAAC,IAAI,IAAI,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,cAAc,CAAC;QACnE,aAAa,EAAE,IAAI,aAAa,CAAC,YAAY,CAAC;QAC9C,QAAQ,EAAE,KAAK,IAAI,EAAE;YACnB,uCAAuC;QACzC,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAS,2BAA2B,CAAC,MAA2B;IAC9D,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,IAAI,EAAE,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CAAC,yDAAyD,CAAC,CAAC;IAC7E,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,cAAc,EAAE,IAAI,EAAE,EAAE,CAAC;QACnC,MAAM,IAAI,KAAK,CACb,4DAA4D,CAC7D,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,IAAI,EAAE,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CAAC,yDAAyD,CAAC,CAAC;IAC7E,CAAC;IACD,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QACnB,IAAI,CAAC;YACH,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC1B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CACb,gCAAgC,MAAM,CAAC,OAAO,KAAM,KAAe,CAAC,OAAO,GAAG,CAC/E,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAA2B,EAC3B,MAAuB;IAEvB,qBAAqB;IACrB,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACb,+EAA+E,CAChF,CAAC;IACJ,CAAC;IAED,kBAAkB;IAClB,2BAA2B,CAAC,MAAM,CAAC,CAAC;IAEpC,kDAAkD;IAClD,IAAI,QAAQ,EAAE,CAAC;QACb,uCAAuC;QACvC,MAAM,cAAc,GAAG,QAAQ,CAAC,eAAe,CAAC,SAAS,EAAE,CAAC;QAC5D,IAAI,cAAc,CAAC,cAAc,KAAK,MAAM,CAAC,cAAc,EAAE,CAAC;YAC5D,OAAO,CAAC,IAAI,CACV,iEAAiE;gBAC/D,cAAc,cAAc,CAAC,cAAc,gBAAgB,MAAM,CAAC,cAAc,KAAK;gBACrF,8BAA8B,CACjC,CAAC;QACJ,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,iDAAiD;IACjD,IAAI,OAAO,CAAC,GAAG,CAAC,EAAE,KAAK,MAAM,EAAE,CAAC;QAC9B,OAAO,CAAC,KAAK,CAAC,4DAA4D,CAAC,CAAC;QAC5E,QAAQ,GAAG,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC9C,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,MAAM,eAAe,GAAG,IAAI,wBAAwB,CAAC,MAAM,CAAC,CAAC;IAC7D,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IAEvC,4CAA4C;IAC5C,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IAE3B,wCAAwC;IACxC,IAAI,YAAY,GAAG,CAAC,CAAC;IACrB,MAAM,MAAM,GAAG,CAAC,KAAa,EAAE,MAAc,EAAE,EAAE;QAC/C,YAAY,IAAI,KAAK,CAAC;QACtB,OAAO,CAAC,IAAI,CACV,uBAAuB,KAAK,WAAW,MAAM,qBAAqB,YAAY,EAAE,CACjF,CAAC;IACJ,CAAC,CAAC;IAEF,qEAAqE;IACrE,wFAAwF;IACxF,IAAI,aAA4C,CAAC;IACjD,IACE,MAAM,CAAC,OAAO;QACd,eAAe,CAAC,eAAe,CAAC,aAAa,CAAC,kBAAkB,CAAC,EACjE,CAAC;QACD,aAAa,GAAG,IAAI,iBAAiB,CAAC;YACpC,QAAQ,EAAE,IAAI,iBAAiB,CAAC,EAAE,GAAG,EAAE,GAAG,MAAM,CAAC,OAAO,YAAY,EAAE,CAAC;YACvE,MAAM;SACP,CAAC,CAAC;IACL,CAAC;IAED,oCAAoC;IACpC,wFAAwF;IACxF,IAAI,YAAuD,CAAC;IAC5D,IACE,MAAM,CAAC,OAAO;QACd,MAAM,CAAC,cAAc,KAAK,KAAK;QAC/B,eAAe,CAAC,eAAe,CAAC,aAAa,CAAC,kBAAkB,CAAC,EACjE,CAAC;QACD,YAAY,GAAG,IAAI,6BAA6B,CAAC;YAC/C,QAAQ,EAAE,IAAI,kBAAkB,CAAC;gBAC/B,GAAG,EAAE,GAAG,MAAM,CAAC,OAAO,aAAa;gBACnC,qBAAqB,EAAE,sBAAsB,CAAC,KAAK;aACpD,CAAC;YACF,oBAAoB,EAAE,KAAK,EAAE,mBAAmB;SACjD,CAAC,CAAC;IACL,CAAC;IAED,oEAAoE;IACpE,4DAA4D;IAC5D,kGAAkG;IAClG,gFAAgF;IAChF,2DAA2D;IAC3D,IAAI,YAAiD,CAAC;IACtD,MAAM,aAAa,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAE/C,IACE,MAAM,CAAC,OAAO;QACd,MAAM,CAAC,WAAW,KAAK,KAAK;QAC5B,eAAe,CAAC,eAAe,CAAC,aAAa,CAAC,kBAAkB,CAAC;QACjE,aAAa,CAAC,UAAU,KAAK,aAAa,CAAC,UAAU,EACrD,CAAC;QACD,MAAM,cAAc,GAAG,IAAI,uBAAuB,CAChD,IAAI,eAAe,CAAC,EAAE,GAAG,EAAE,GAAG,MAAM,CAAC,OAAO,UAAU,EAAE,CAAC,CAC1D,CAAC;QACF,YAAY,GAAG,IAAI,uBAAuB,CAAC,aAAa,EAAE,cAAc,CAAC,CAAC;IAC5E,CAAC;IAED,iBAAiB;IACjB,uGAAuG;IACvG,MAAM,GAAG,GAAG,IAAI,OAAO,CAAC;QACtB,QAAQ;QACR,aAAa,EAAE,aAAa;YAC1B,CAAC,CAAC,IAAI,kBAAkB,CAAC,aAAa,CAAC;YACvC,CAAC,CAAC,SAAS;QACb,YAAY;QACZ,kBAAkB,EAAE,YAAY;QAChC,cAAc,EAAE,IAAI,+BAA+B,EAAE;QACrD,iBAAiB,EAAE,IAAI,yBAAyB,EAAE;QAClD,iGAAiG;QACjG,gBAAgB,EAAE,CAAC,MAAM,CAAC,gBAAgB,IAAI,EAAE,CAAQ;KACzD,CAAC,CAAC;IAEH,GAAG,CAAC,KAAK,EAAE,CAAC;IAEZ,OAAO,CAAC,IAAI,CACV,+BAA+B,MAAM,CAAC,WAAW,KAAK,MAAM,CAAC,cAAc,GAAG;QAC5E,cAAc,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,EAAE;QACtD,eAAe,YAAY,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,EAAE;QACtD,YAAY,YAAY,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,EAAE,CACtD,CAAC;IAEF,MAAM,YAAY,GAAG,OAAO,CAAC,QAAQ,CACnC,MAAM,CAAC,WAAW,EAClB,MAAM,CAAC,cAAc,CACtB,CAAC;IAEF,QAAQ,GAAG;QACT,GAAG;QACH,eAAe;QACf,SAAS,EAAE,CAAC,IAAa,EAAE,EAAE,CAC3B,KAAK,CAAC,SAAS,CAAC,IAAI,IAAI,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,cAAc,CAAC;QACpE,QAAQ,EAAE,CAAC,IAAa,EAAE,EAAE,CAC1B,OAAO,CAAC,QAAQ,CAAC,IAAI,IAAI,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,cAAc,CAAC;QACrE,SAAS,EAAE,CAAC,IAAa,EAAE,EAAE,CAC3B,IAAI,CAAC,SAAS,CAAC,IAAI,IAAI,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,cAAc,CAAC;QACnE,aAAa,EAAE,IAAI,aAAa,CAAC,YAAY,CAAC;QAC9C,QAAQ,EAAE,KAAK,IAAI,EAAE;YACnB,IAAI,CAAC;gBACH,MAAM,GAAG,CAAC,QAAQ,EAAE,CAAC;YACvB,CAAC;oBAAS,CAAC;gBACT,QAAQ,GAAG,SAAS,CAAC;YACvB,CAAC;QACH,CAAC;KACF,CAAC;IAEF,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB;IAClC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CACb,8DAA8D,CAC/D,CAAC;IACJ,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,sBAAsB;IACpC,OAAO,QAAQ,KAAK,SAAS,CAAC;AAChC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc;IAC5B,QAAQ,GAAG,SAAS,CAAC;AACvB,CAAC"}

package/dist-esm/node/log-processor.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Policy-Aware Log Processor
+ *
+ * Wraps a delegate LogRecordProcessor to provide:
+ * 1. Export mode filtering (LOCAL_ONLY, ERRORS_ONLY, INFO_AND_ABOVE)
+ * 2. Severity level filtering
+ * 3. Log body and attribute sanitization
+ *
+ * @see https://github.com/superblocksteam/engineering/blob/main/projects/o11y-refactor/epics/epic-c4-logging-strategy.md
+ */
+import type { LogRecordProcessor, ReadableLogRecord } from "@opentelemetry/sdk-logs";
+import type { Context } from "@opentelemetry/api";
+import { TelemetryPolicy } from "../types/policy.js";
+/**
+ * Controls what logs are exported via OTEL.
+ */
+export declare enum LogExportMode {
+    /** No log export - local stdout/stderr only */
+    LOCAL_ONLY = "local_only",
+    /** Export WARN/ERROR/FATAL only (default for cloud-prem) */
+    ERRORS_ONLY = "errors_only",
+    /** Export INFO and above (not recommended for cloud-prem) */
+    INFO_AND_ABOVE = "info_and_above"
+}
+/**
+ * Logging-specific policy configuration.
+ */
+export interface LoggingPolicyConfig {
+    /** What logs to export */
+    exportMode: LogExportMode;
+    /** Maximum log level for local retention */
+    localMaxLevel: "trace" | "debug" | "info" | "warn" | "error" | "fatal";
+    /** Regex patterns to redact from log content */
+    redactPatterns: RegExp[];
+    /** Fields to never include in exported logs */
+    forbiddenFields: Set<string>;
+}
+/**
+ * Get logging policy based on telemetry policy.
+ *
+ * @param policy - Telemetry policy
+ * @returns Logging policy configuration
+ */
+export declare function getLoggingPolicy(policy: TelemetryPolicy): LoggingPolicyConfig;
+/**
+ * Log processor that filters and sanitizes logs based on policy.
+ *
+ * This processor:
+ * 1. Blocks all logs if exportMode is LOCAL_ONLY
+ * 2. Filters by severity level based on exportMode
+ * 3. Sanitizes log body and attributes before forwarding
+ */
+export declare class PolicyAwareLogProcessor implements LogRecordProcessor {
+    private readonly policy;
+    private readonly delegate;
+    constructor(policy: LoggingPolicyConfig, delegate: LogRecordProcessor);
+    /**
+     * Called when a log record is emitted.
+     */
+    onEmit(logRecord: ReadableLogRecord, context?: Context): void;
+    /**
+     * Sanitize a log record for export.
+     * Mutates the log record in place to preserve OTEL SDK internal state.
+     */
+    private sanitizeLogRecord;
+    /**
+     * Check if a string contains a stack trace.
+     */
+    private containsStackTrace;
+    /**
+     * Sanitize log attributes.
+     */
+    private sanitizeAttributes;
+    /**
+     * Shutdown the processor.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Force flush pending logs.
+     */
+    forceFlush(): Promise<void>;
+}
+//# sourceMappingURL=log-processor.d.ts.map

package/dist-esm/node/log-processor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-processor.d.ts","sourceRoot":"","sources":["../../src/node/log-processor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAiB,MAAM,oBAAoB,CAAC;AAepE;;GAEG;AACH,oBAAY,aAAa;IACvB,+CAA+C;IAC/C,UAAU,eAAe;IACzB,4DAA4D;IAC5D,WAAW,gBAAgB;IAC3B,6DAA6D;IAC7D,cAAc,mBAAmB;CAClC;AAMD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,0BAA0B;IAC1B,UAAU,EAAE,aAAa,CAAC;IAC1B,4CAA4C;IAC5C,aAAa,EAAE,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;IACvE,gDAAgD;IAChD,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,+CAA+C;IAC/C,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC9B;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,eAAe,GAAG,mBAAmB,CAyC7E;AAuDD;;;;;;;GAOG;AACH,qBAAa,uBAAwB,YAAW,kBAAkB;IAChE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsB;IAC7C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;gBAElC,MAAM,EAAE,mBAAmB,EAAE,QAAQ,EAAE,kBAAkB;IAKrE;;OAEG;IACH,MAAM,CAAC,SAAS,EAAE,iBAAiB,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI;IAsB7D;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAuCzB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAY1B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAyC1B;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAI/B;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;CAGlC"}